chore: complete v1.1 milestone — Custom Sound Mappings
Archive roadmap and requirements to milestones/, update PROJECT.md with shipped state, collapse ROADMAP.md, update retrospective. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
Claude Opus 4.6
@@ -0,0 +1,87 @@
|
||||
# Requirements Archive: v1.1 Custom Sound Mappings
|
||||
|
||||
**Archived:** 2026-03-26
|
||||
**Status:** SHIPPED
|
||||
|
||||
For current requirements, see `.planning/REQUIREMENTS.md`.
|
||||
|
||||
---
|
||||
|
||||
# Requirements: NetSynth
|
||||
|
||||
**Defined:** 2026-03-26
|
||||
**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.
|
||||
|
||||
## v1.1 Requirements
|
||||
|
||||
Requirements for custom sound mappings milestone. Each maps to roadmap phases.
|
||||
|
||||
### Config Loading
|
||||
|
||||
- [x] **CFG-01**: User can create a TOML config file that overrides default sound mappings
|
||||
- [x] **CFG-02**: Tool auto-discovers config from `./netsynth.toml` or `~/.config/netsynth/config.toml` (silent if absent)
|
||||
- [x] **CFG-03**: User can specify an explicit config path via `--config` flag (error if file missing)
|
||||
- [x] **CFG-04**: User can override individual values without replicating the entire default config (partial override)
|
||||
- [x] **CFG-05**: Unknown keys in config file produce a clear error with the typo'd key name
|
||||
- [x] **CFG-06**: User can run `netsynth --print-config` to see the effective config as commented TOML
|
||||
|
||||
### Waveforms
|
||||
|
||||
- [x] **WAVE-01**: User can set waveform type per traffic class (sine, square, sawtooth, triangle)
|
||||
- [x] **WAVE-02**: Non-sine waveforms use bandlimited additive synthesis (no aliasing artifacts)
|
||||
|
||||
### Custom Rules
|
||||
|
||||
- [x] **RULE-01**: User can define custom classification rules in TOML (match by port and/or protocol, assign class name and sound)
|
||||
- [x] **RULE-02**: User-defined rules take priority over built-in rules (prepend before defaults)
|
||||
- [x] **RULE-03**: User-defined class names automatically get a synthesis layer (no silent gaps)
|
||||
|
||||
## Future Requirements
|
||||
|
||||
Deferred to later releases.
|
||||
|
||||
### Audio Tuning
|
||||
|
||||
- **TUNE-01**: User can configure time window duration via `--window` flag
|
||||
- **TUNE-02**: User can configure output duration when reading pcap files via `--duration` flag
|
||||
|
||||
### Distribution
|
||||
|
||||
- **DIST-01**: Single static binary with no runtime dependencies
|
||||
|
||||
## Out of Scope
|
||||
|
||||
| Feature | Reason |
|
||||
|---------|--------|
|
||||
| Stereo position configuration | Keeps v1.1 scope focused; add in future if requested |
|
||||
| Real-time audio playback | File output only — established v1.0 constraint |
|
||||
| GUI config editor | CLI-only tool; TOML is human-editable |
|
||||
| JSON/YAML config format | TOML chosen for readability; one format keeps it simple |
|
||||
| Config hot-reload | Non-interactive tool; config read once at startup |
|
||||
|
||||
## Traceability
|
||||
|
||||
Which phases cover which requirements. Updated during roadmap creation.
|
||||
|
||||
| Requirement | Phase | Status |
|
||||
|-------------|-------|--------|
|
||||
| CFG-01 | Phase 6 | Complete |
|
||||
| CFG-02 | Phase 6 | Complete |
|
||||
| CFG-03 | Phase 6 | Complete |
|
||||
| CFG-04 | Phase 6 | Complete |
|
||||
| CFG-05 | Phase 6 | Complete |
|
||||
| CFG-06 | Phase 7 | Complete |
|
||||
| WAVE-01 | Phase 5 | Complete |
|
||||
| WAVE-02 | Phase 5 | Complete |
|
||||
| RULE-01 | Phase 7 | Complete |
|
||||
| RULE-02 | Phase 7 | Complete |
|
||||
| RULE-03 | Phase 7 | Complete |
|
||||
|
||||
**Coverage:**
|
||||
- v1.1 requirements: 11 total
|
||||
- Mapped to phases: 11
|
||||
- Unmapped: 0
|
||||
|
||||
---
|
||||
*Requirements defined: 2026-03-26*
|
||||
*Last updated: 2026-03-26 after roadmap creation (traceability complete)*
|
||||
@@ -0,0 +1,87 @@
|
||||
# Roadmap: NetSynth
|
||||
|
||||
## Milestones
|
||||
|
||||
- **v1.0 MVP** — Phases 1-4 (shipped 2026-03-26)
|
||||
- **v1.1 Custom Sound Mappings** — Phases 5-7 (in progress)
|
||||
|
||||
## Phases
|
||||
|
||||
<details>
|
||||
<summary>v1.0 MVP (Phases 1-4) — SHIPPED 2026-03-26</summary>
|
||||
|
||||
- [x] **Phase 1: Capture and Classification** - 4/4 plans — completed 2026-03-25
|
||||
- [x] **Phase 2: Audio Synthesis Engine** - 3/3 plans — completed 2026-03-26
|
||||
- [x] **Phase 3: Pipeline Integration and MVP** - 2/2 plans — completed 2026-03-26
|
||||
- [x] **Phase 4: Power User Features** - 2/2 plans — completed 2026-03-26
|
||||
|
||||
Full details: `.planning/milestones/v1.0-ROADMAP.md`
|
||||
|
||||
</details>
|
||||
|
||||
### v1.1 Custom Sound Mappings (In Progress)
|
||||
|
||||
**Milestone Goal:** Users can customize how traffic sounds via a TOML config file — setting custom frequencies, waveform types, and their own classification rules with named sounds.
|
||||
|
||||
- [x] **Phase 5: Waveform Types and Bank Decoupling** - Internal refactors establishing waveform enum and injectable bank signature (completed 2026-03-26)
|
||||
- [x] **Phase 6: Config Package and Sound Overrides** - TOML loading, auto-discovery, partial merge, and frequency/waveform overrides wired end-to-end (completed 2026-03-26)
|
||||
- [x] **Phase 7: Custom Rules and Print-Config** - User-defined classification rules and --print-config UX (completed 2026-03-26)
|
||||
|
||||
## Phase Details
|
||||
|
||||
### Phase 5: Waveform Types and Bank Decoupling
|
||||
**Goal**: Four waveform types are available per traffic class, and the synthesis bank accepts an injected config map instead of reading global state
|
||||
**Depends on**: Phase 4
|
||||
**Requirements**: WAVE-01, WAVE-02
|
||||
**Success Criteria** (what must be TRUE):
|
||||
1. User can set a traffic class to square, sawtooth, or triangle waveform and hear a tonally distinct sound with no audible aliasing or buzzing artifacts
|
||||
2. Sine waveform continues to produce the same output as v1.0 — no regression
|
||||
3. The synthesis bank builds layers from a passed-in config map rather than a hardcoded class list
|
||||
**Plans:** 2/2 plans complete
|
||||
|
||||
Plans:
|
||||
- [x] 05-01-PLAN.md — Waveform types: WaveformType enum, WaveformPresetHarmonics, NewLayer resolution
|
||||
- [x] 05-02-PLAN.md — Bank decoupling: NewBank injected config map, dynamic GainPerLayer, test updates
|
||||
|
||||
### Phase 6: Config Package and Sound Overrides
|
||||
**Goal**: Users can create a TOML config file to override frequency and waveform per traffic class, with auto-discovery, partial override semantics, and clear validation errors
|
||||
**Depends on**: Phase 5
|
||||
**Requirements**: CFG-01, CFG-02, CFG-03, CFG-04, CFG-05
|
||||
**Success Criteria** (what must be TRUE):
|
||||
1. User creates a `netsynth.toml` in the working directory with a custom Hz value and the tool uses that frequency for the specified class without touching other classes
|
||||
2. User runs the tool with no flags in a directory without a config file — it starts silently (no warning about missing config)
|
||||
3. User passes `--config /path/to/custom.toml` and the tool uses that file; if the file does not exist, the tool exits with a clear error before capture begins
|
||||
4. User types `frequncy = 440` in their config file and the tool exits at startup with an error naming `frequncy` as an unrecognized key
|
||||
5. User sets waveform for one class in TOML and leaves all other classes at their defaults — the unspecified classes are unchanged
|
||||
**Plans:** 2/2 plans complete
|
||||
|
||||
Plans:
|
||||
- [x] 06-01-PLAN.md — Config package: TOML load, validate, merge with TDD (config/config.go, config/config_test.go)
|
||||
- [x] 06-02-PLAN.md — CLI wiring: --config flag, RunSynthesis signature change, main.go integration
|
||||
|
||||
### Phase 7: Custom Rules and Print-Config
|
||||
**Goal**: Users can define their own traffic classification rules in TOML, assign custom sounds to them, and inspect the full effective config before capture begins
|
||||
**Depends on**: Phase 6
|
||||
**Requirements**: RULE-01, RULE-02, RULE-03, CFG-06
|
||||
**Success Criteria** (what must be TRUE):
|
||||
1. User adds a `[[rules]]` block in TOML matching a custom port/protocol combination and hears a distinct tone for that traffic in the output MP3
|
||||
2. User-defined rules fire before built-in protocol rules — a custom rule for port 443 overrides the default HTTPS classification for packets on that port
|
||||
3. A user-defined class name gets its own synthesis layer automatically — no silence or missing audio for traffic matched by a custom rule
|
||||
4. User runs `netsynth --print-config` and sees the full effective config (defaults merged with their overrides) as commented TOML, without starting a capture
|
||||
**Plans:** 2/2 plans complete
|
||||
|
||||
Plans:
|
||||
- [x] 07-01-PLAN.md — Config extension: RawRule, LoadResult, rule validation, auto-freq assignment (TDD)
|
||||
- [x] 07-02-PLAN.md — CLI wiring: --print-config flag, user rule prepend, PrintConfig output
|
||||
|
||||
## Progress
|
||||
|
||||
| Phase | Milestone | Plans Complete | Status | Completed |
|
||||
|-------|-----------|----------------|--------|-----------|
|
||||
| 1. Capture and Classification | v1.0 | 4/4 | Complete | 2026-03-25 |
|
||||
| 2. Audio Synthesis Engine | v1.0 | 3/3 | Complete | 2026-03-26 |
|
||||
| 3. Pipeline Integration and MVP | v1.0 | 2/2 | Complete | 2026-03-26 |
|
||||
| 4. Power User Features | v1.0 | 2/2 | Complete | 2026-03-26 |
|
||||
| 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 |
|
||||
Reference in New Issue
Block a user