docs(07): capture phase context

2026-03-26 21:27:29 +01:00
parent dddfb1b444
commit fe372c8dc8
2 changed files with 196 additions and 0 deletions
@@ -0,0 +1,73 @@
+# Phase 7: Custom Rules and Print-Config - Discussion Log
+
+> **Audit trail only.** Do not use as input to planning, research, or execution agents.
+> Decisions are captured in CONTEXT.md — this log preserves the alternatives considered.
+
+**Date:** 2026-03-26
+**Phase:** 07-custom-rules-and-print-config
+**Areas discussed:** Custom rule TOML schema, Class name collision policy, Print-config output format, Sound assignment for custom classes
+
+---
+
+## Custom Rule TOML Schema
+
+| Option | Description | Selected |
+|--------|-------------|----------|
+| Minimal: port + protocol + class | Matches existing Rule struct. Sound config in separate [sounds.X]. | ✓ |
+| Inline sound: port + protocol + class + frequency/waveform | All-in-one rule block, mixes classification and sound concerns. | |
+| Rich matching: port ranges, src/dst, regex | More expressive but significantly more complex. | |
+
+**User's choice:** Minimal — port + protocol + class
+**Notes:** Protocol is required. Port is optional (omit to match any port for the protocol).
+
+---
+
+## Class Name Collision Policy
+
+| Option | Description | Selected |
+|--------|-------------|----------|
+| Treat as override | User's rule fires first (prepended), same class name. Simplest model. | ✓ |
+| Reject with error | Startup error if user rule uses built-in class name. | |
+| Namespace: prefix user classes | User classes get "user-" prefix. Adds naming complexity. | |
+
+**User's choice:** Treat as override
+**Notes:** Resolves the design question flagged in STATE.md since Phase 5 research.
+
+---
+
+## Print-Config Output Format
+
+| Option | Description | Selected |
+|--------|-------------|----------|
+| Commented TOML | Valid TOML with comments showing default vs override. Pipeable to file. | ✓ |
+| Plain TOML | Clean but doesn't show what's default vs overridden. | |
+| Human-readable table | Formatted table, not valid TOML. | |
+
+**User's choice:** Commented TOML to stdout
+**Notes:** Output to stdout so `netsynth --print-config > template.toml` works. Shows source path in header comment.
+
+---
+
+## Sound Assignment for Custom Classes
+
+| Option | Description | Selected |
+|--------|-------------|----------|
+| Auto-assign sensible defaults | Pick unused frequency + sine waveform. No silence. | ✓ |
+| Require explicit [sounds.X] | Error if no matching sound config. More friction. | |
+| Single fallback tone | All custom classes share one tone. Defeats distinct sounds purpose. | |
+
+**User's choice:** Auto-assign sensible defaults
+**Notes:** Satisfies RULE-03 (no silent gaps). Algorithm left to Claude's discretion.
+
+---
+
+## Claude's Discretion
+
+- Auto-frequency assignment algorithm
+- --print-config as flag vs subcommand
+- Commented TOML formatting approach
+- config.Load() return type extension
+
+## Deferred Ideas
+
+None — discussion stayed within phase scope.