From 8e565ec640898d5ae4f36bcfa1095ce5871153c5 Mon Sep 17 00:00:00 2001 From: Markus Graf Date: Fri, 27 Mar 2026 08:38:08 +0100 Subject: [PATCH] docs: create milestone v1.2 roadmap (4 phases, 18 requirements) Co-Authored-By: Claude Opus 4.6 (1M context) --- .planning/REQUIREMENTS.md | 42 +++++++++++----------- .planning/ROADMAP.md | 60 +++++++++++++++++++++++++++++++ .planning/STATE.md | 74 +++++++++++++++++---------------------- 3 files changed, 113 insertions(+), 63 deletions(-) diff --git a/.planning/REQUIREMENTS.md b/.planning/REQUIREMENTS.md index 3aeba5b..842a055 100644 --- a/.planning/REQUIREMENTS.md +++ b/.planning/REQUIREMENTS.md @@ -67,30 +67,30 @@ Which phases cover which requirements. Updated during roadmap creation. | Requirement | Phase | Status | |-------------|-------|--------| -| CLEAN-01 | TBD | Pending | -| PROTO-01 | TBD | Pending | -| PROTO-02 | TBD | Pending | -| PROTO-03 | TBD | Pending | -| PROTO-04 | TBD | Pending | -| PROTO-05 | TBD | Pending | -| PROTO-06 | TBD | Pending | -| PROTO-07 | TBD | Pending | -| PROTO-08 | TBD | Pending | -| PROTO-09 | TBD | Pending | -| FREQ-01 | TBD | Pending | -| FREQ-02 | TBD | Pending | -| FREQ-03 | TBD | Pending | -| FREQ-04 | TBD | Pending | -| GRP-01 | TBD | Pending | -| GRP-02 | TBD | Pending | -| GRP-03 | TBD | Pending | -| GRP-04 | TBD | Pending | +| CLEAN-01 | Phase 8 | Pending | +| FREQ-01 | Phase 9 | Pending | +| FREQ-02 | Phase 9 | Pending | +| FREQ-03 | Phase 9 | Pending | +| FREQ-04 | Phase 9 | Pending | +| GRP-01 | Phase 9 | Pending | +| GRP-04 | Phase 9 | Pending | +| PROTO-01 | Phase 10 | Pending | +| PROTO-02 | Phase 10 | Pending | +| PROTO-03 | Phase 10 | Pending | +| PROTO-04 | Phase 10 | Pending | +| PROTO-05 | Phase 10 | Pending | +| PROTO-06 | Phase 10 | Pending | +| PROTO-07 | Phase 10 | Pending | +| PROTO-08 | Phase 10 | Pending | +| PROTO-09 | Phase 10 | Pending | +| GRP-02 | Phase 11 | Pending | +| GRP-03 | Phase 11 | Pending | **Coverage:** - v1.2 requirements: 18 total -- Mapped to phases: 0 (pending roadmap) -- Unmapped: 18 +- Mapped to phases: 18 (complete) +- Unmapped: 0 --- *Requirements defined: 2026-03-27* -*Last updated: 2026-03-27* +*Last updated: 2026-03-27 — traceability complete, roadmap phases 8-11 assigned* diff --git a/.planning/ROADMAP.md b/.planning/ROADMAP.md index f1cc559..6bc14de 100644 --- a/.planning/ROADMAP.md +++ b/.planning/ROADMAP.md @@ -4,6 +4,7 @@ - **v1.0 MVP** — Phases 1-4 (shipped 2026-03-26) - **v1.1 Custom Sound Mappings** — Phases 5-7 (shipped 2026-03-26) +- **v1.2 Extended Protocol Coverage** — Phases 8-11 (in progress) ## Phases @@ -30,6 +31,61 @@ Full details: `.planning/milestones/v1.1-ROADMAP.md` +### v1.2 Extended Protocol Coverage (In Progress) + +**Milestone Goal:** Expand traffic classification with grouped protocol families that share recognizable sound signatures — from 14 classes to ~35, organized into frequency bands by family. + +- [ ] **Phase 8: Test and Constant Cleanup** - Remove stale constants and update test bounds that would block all subsequent v1.2 work +- [ ] **Phase 9: Frequency Design and Group Architecture** - Design complete Hz allocation for all ~35 classes in family bands and add Group field to FreqConfig +- [ ] **Phase 10: Classification Layer** - Add ~21 new TrafficClass constants and port rules covering all new protocol families +- [ ] **Phase 11: Synthesis and Config Layer** - Add ClassFreqConfigs entries for all new classes, update auto-assign range, and add group-header output to --print-config + +## Phase Details + +### Phase 8: Test and Constant Cleanup +**Goal**: Pre-existing test assertions and a stale exported constant that would block or mislead all subsequent v1.2 work are removed +**Depends on**: Phase 7 +**Requirements**: CLEAN-01 +**Success Criteria** (what must be TRUE): + 1. `go test ./...` passes on main with no modifications to the new v1.2 code path + 2. The stale `NumLayers`/`GainPerLayer` exported constant no longer exists in the synth package — callers cannot accidentally use it + 3. `TestFrequenciesInRange` accepts the new extended Hz range without manual test surgery when new classes are added in Phase 10 +**Plans**: TBD + +### Phase 9: Frequency Design and Group Architecture +**Goal**: A complete, documented frequency allocation table for all ~35 traffic classes exists and the FreqConfig struct carries a Group field — design decisions are locked in before any protocol code is written +**Depends on**: Phase 8 +**Requirements**: FREQ-01, FREQ-02, FREQ-03, FREQ-04, GRP-01, GRP-04 +**Success Criteria** (what must be TRUE): + 1. A written frequency allocation table (in a planning doc or code comment) lists every built-in class, its Hz value, waveform, and group — no class is TBD + 2. Every within-family pair of frequencies satisfies at least a major second interval (ratio 1.122), verifiable by inspection of the table + 3. The `autoAssignFreq` base for user-defined custom classes is set above all built-in frequencies, with no collision possible + 4. `FreqConfig` has a `Group` string field and all existing `ClassFreqConfigs` entries compile with the new struct shape +**Plans**: TBD +**UI hint**: no + +### Phase 10: Classification Layer +**Goal**: All new protocol families are classified — ~21 new TrafficClass constants exist, AllClasses() covers them, and DefaultRules maps all new ports to their classes +**Depends on**: Phase 9 +**Requirements**: PROTO-01, PROTO-02, PROTO-03, PROTO-04, PROTO-05, PROTO-06, PROTO-07, PROTO-08, PROTO-09 +**Success Criteria** (what must be TRUE): + 1. A packet arriving on any new protocol port (e.g., TCP 143, TCP 3389, TCP 3306, UDP 5353, TCP 5060) is classified into the correct named TrafficClass, not into other-TCP or other-UDP + 2. All existing 10 protocol classifications continue to match as before — no regression in rule order or port assignments + 3. Multiple ports mapping to the same family class (e.g., IMAP port 143 and IMAPS port 993 both classify as the same Mail-IMAP class) behave identically in the classifier output + 4. `go test ./classify/...` passes with no new test failures +**Plans**: TBD + +### Phase 11: Synthesis and Config Layer +**Goal**: Every new traffic class produces a distinct, family-coherent sound and --print-config shows all classes organized by group with section headers +**Depends on**: Phase 9, Phase 10 +**Requirements**: GRP-02, GRP-03 +**Success Criteria** (what must be TRUE): + 1. Running `netsynth --print-config` shows all ~35 classes grouped by family with section header comments (e.g., `# Mail`, `# Database`) — no class is listed without a group + 2. A pcap or live capture that triggers Mail traffic produces tones that are audibly in the same timbral family — same waveform type, similar frequency register — while still being distinguishable from each other + 3. Users can define `[groups]` in their TOML config to reassign a protocol to a different sound family, and --print-config reflects the reassignment + 4. `go test ./...` passes and a listening test on a representative pcap confirms family identity is perceptually clear +**Plans**: TBD + ## Progress | Phase | Milestone | Plans Complete | Status | Completed | @@ -41,3 +97,7 @@ Full details: `.planning/milestones/v1.1-ROADMAP.md` | 5. Waveform Types and Bank Decoupling | v1.1 | 2/2 | Complete | 2026-03-26 | | 6. Config Package and Sound Overrides | v1.1 | 2/2 | Complete | 2026-03-26 | | 7. Custom Rules and Print-Config | v1.1 | 2/2 | Complete | 2026-03-26 | +| 8. Test and Constant Cleanup | v1.2 | 0/? | Not started | - | +| 9. Frequency Design and Group Architecture | v1.2 | 0/? | Not started | - | +| 10. Classification Layer | v1.2 | 0/? | Not started | - | +| 11. Synthesis and Config Layer | v1.2 | 0/? | Not started | - | diff --git a/.planning/STATE.md b/.planning/STATE.md index 1337681..57845ea 100644 --- a/.planning/STATE.md +++ b/.planning/STATE.md @@ -2,15 +2,15 @@ gsd_state_version: 1.0 milestone: v1.2 milestone_name: Extended Protocol Coverage -status: defining_requirements -stopped_at: Milestone v1.2 started -last_updated: "2026-03-26T21:02:36.710Z" -last_activity: 2026-03-26 +status: roadmap_created +stopped_at: Roadmap created for v1.2 — ready to plan Phase 8 +last_updated: "2026-03-27T00:00:00.000Z" +last_activity: 2026-03-27 progress: - total_phases: 3 - completed_phases: 3 - total_plans: 6 - completed_plans: 6 + total_phases: 4 + completed_phases: 0 + total_plans: 0 + completed_plans: 0 percent: 0 --- @@ -18,70 +18,60 @@ progress: ## Project Reference -See: .planning/PROJECT.md (updated 2026-03-26) +See: .planning/PROJECT.md (updated 2026-03-27) **Core value:** Network traffic patterns are instantly recognizable as distinct sounds — a ping sounds different from HTTPS noise, which sounds different from a port scan. -**Current focus:** Defining requirements for v1.2 +**Current focus:** Phase 8 — Test and Constant Cleanup (v1.2 start) ## Current Position -Phase: Not started (defining requirements) -Plan: — -Status: Defining requirements -Last activity: 2026-03-27 — Milestone v1.2 started -Last activity: 2026-03-26 +Phase: 8 of 11 (Test and Constant Cleanup) +Plan: — (not yet planned) +Status: Ready to plan +Last activity: 2026-03-27 — v1.2 roadmap created, 4 phases defined (8-11), 18 requirements mapped Progress: [░░░░░░░░░░] 0% ## Performance Metrics -**Velocity (v1.0 baseline):** +**Velocity (v1.1 baseline):** -- Total plans completed: 11 -- Average duration: 7.7 min -- Total execution time: ~1.4 hours +- Total plans completed: 6 +- Average duration: ~3 min +- Total execution time: ~18 min -**By Phase (v1.0):** +**By Phase (v1.1):** | Phase | Plans | Total | Avg/Plan | |-------|-------|-------|----------| -| 01 | 4 | ~30min | 7.5min | -| 02 | 3 | ~28min | 9.3min | -| 03 | 2 | ~20min | 10min | -| 04 | 2 | ~7min | 3.5min | +| 05 | 2 | ~7min | 3.5min | +| 06 | 2 | ~4min | 2min | +| 07 | 2 | ~6min | 3min | **Recent Trend:** Stable -| Phase 05 P01 | 3min | 2 tasks | 3 files | -| Phase 05 P02 | 4 | 2 tasks | 4 files | -| Phase 06 P02 | 2 | 2 tasks | 3 files | -| Phase 07 P01 | 3 | 1 tasks | 3 files | ## Accumulated Context ### Decisions -- [v1.1 Roadmap]: Phase 5 consolidates waveform types (WAVE-01, WAVE-02) with bank decoupling — both are internal refactors with no user-visible surface, establishing the injectable seam before config is added -- [v1.1 Roadmap]: Research steps 5+6 (wire config + freq/waveform overrides) collapsed into Phase 6 — they share the same integration boundary (encode.RunSynthesis signature change) and are safer to land together -- [v1.1 Roadmap]: User class name collision with built-in TrafficClass strings is an unresolved design question — decide before coding Phase 7 (treat as override vs. reject as ambiguous) -- [Phase 05]: FreqConfig struct uses named field syntax for ClassFreqConfigs entries (required by WaveformType addition) -- [Phase 05]: WaveformType zero value is WaveformCustom — all 14 existing ClassFreqConfigs entries retain hand-tuned harmonics without modification -- [Phase 05]: NewBank accepts injected config map instead of reading ClassFreqConfigs global — injection seam for Phase 6 config loading -- [Phase 05]: gainPerLayer computed as 1.0/float64(len(cfgs)) — correct for any class count, no-clip guarantee preserved -- [Phase 06]: Option A for freqCfgs propagation: pass as parameter to runLiveMode/runPcapMode — cleaner data flow vs package-level var -- [Phase 06]: config.Load positioned after BPF validation, before output path resolution — ensures fail-fast before any I/O (D-11) +- [v1.2 Roadmap]: Phase 8 before everything — stale NumLayers/GainPerLayer constant and hardcoded TestFrequenciesInRange bounds cause false CI failures throughout milestone if not removed first +- [v1.2 Roadmap]: Phase 9 is design-only (no protocol code) — Hz allocation must be locked before ClassFreqConfigs entries are written; retroactive rebalancing touches every entry +- [v1.2 Roadmap]: Phase 10 before Phase 11 — TrafficClass constants must exist before ClassFreqConfigs can reference them (three-location atomicity enforced by existing test) +- [v1.2 Roadmap]: GRP-02 and GRP-03 deferred to Phase 11 — PrintConfig group headers and TOML [groups] config depend on both Group field (Phase 9) and new class constants (Phase 10) - [Phase 07]: addAutoFreqEntries runs before merge so [sounds.X] overrides apply to user-defined classes -- [Phase 07]: LoadResult struct chosen over tuple return for config.Load() -- cleaner API contract for Plan 02 CLI wiring +- [Phase 07]: LoadResult struct chosen over tuple return for config.Load() — cleaner API contract ### Pending Todos -None. +1 pending todo: `.planning/todos/pending/001-expand-traffic-classes.md` ### Blockers/Concerns -- [Phase 7 pre-work]: User-defined class names that collide with built-in class strings (e.g., `class = "HTTPS"`) require an explicit design decision before Phase 7 coding begins. Research flags this as unresolved. Options: treat as override (simplest) or reject as ambiguous. Resolve during Phase 7 planning. +- [v1.2 pre-work]: autoAssignFreq range [1200, 2350] Hz will collide with new built-in frequencies unless pushed above all new entries (addressed in Phase 9 design) +- [v1.2 pre-work]: Frequency rebalancing may silently invalidate v1.1 user TOML configs with explicit Hz overrides — mitigation: assign all new protocols above 1047 Hz to leave existing layout frozen ## Session Continuity -Last session: 2026-03-26T20:52:30.470Z -Stopped at: Completed 07-02-PLAN.md +Last session: 2026-03-27 +Stopped at: v1.2 roadmap created Resume file: None