gurix/yoloyolo
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: create milestone v1.2 roadmap (4 phases, 18 requirements)

Browse Source 
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
gurix
2026-03-27 08:38:08 +01:00
co-authored by Claude Opus 4.6
parent 47b6e171c4
commit 8e565ec640
3 changed files with 113 additions and 63 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.planning/REQUIREMENTS.md
+21 -21
View File
@@ -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*
.planning/ROADMAP.md
+60
View File
@@ -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`
</details>
### 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 | - |
.planning/STATE.md
+32 -42
View File
@@ -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