gurixandClaude Opus 4.6
494385b528
35 traffic classes across 9 protocol families shipped. Archives ROADMAP, REQUIREMENTS, and phase directories to milestones/v1.2-*. Updates README with new protocol families, sound design table, and [groups] TOML config documentation. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
123 lines
6.4 KiB
Markdown
123 lines
6.4 KiB
Markdown
# Retrospective
|
|
|
|
## Milestone: v1.0 — MVP
|
|
|
|
**Shipped:** 2026-03-26
|
|
**Phases:** 4 | **Plans:** 11 | **Timeline:** 3 days (2026-03-24 -> 2026-03-26)
|
|
**LOC:** 3,254 Go | **Files:** 84 modified
|
|
|
|
### What Was Built
|
|
- Config-driven packet classifier with 12 protocol rules and 4 hash-bucketed unknown classes
|
|
- Live packet capture via pure Go go-pcap with privilege detection and non-blocking channel pipeline
|
|
- Additive synthesis engine: per-class oscillators, EMA amplitude smoothing, constant-power stereo mixing
|
|
- MP3 encoding via embedded LAME, zero-packet guard
|
|
- End-to-end pipeline with clean Ctrl+C shutdown
|
|
- BPF filter and offline pcap file sonification with timestamp-based windowing
|
|
|
|
### What Worked
|
|
- Risk-ordered phases: hardest foundation first (capture), then synthesis in isolation, then integration — no phase blocked on another's bugs
|
|
- TDD approach in executor agents caught signature mismatches early
|
|
- Pure Go capture layer (go-pcap) avoided libpcap dependency headaches
|
|
- Hand-rolled synthesis kept dependencies minimal and code understandable
|
|
- Wave-based parallel execution for independent plans
|
|
|
|
### What Was Inefficient
|
|
- Some SUMMARY.md files had empty one-liner fields, causing noisy milestone extraction
|
|
- Phase 4 research could have been lighter — BPF/pcap APIs were straightforward
|
|
|
|
### Patterns Established
|
|
- Ordered []Rule slice for classifier (first-match-wins, extensible)
|
|
- io.Writer injection for testable stderr output
|
|
- Buffered channels between pipeline stages (512-1024) to absorb bursts
|
|
- Package-level globals for Cobra flag binding
|
|
- Timestamp-based windowing for non-live sources
|
|
|
|
### Key Lessons
|
|
- Embedding C source (go-lame) is a good tradeoff: CGo at build time only, no runtime dependency
|
|
- go-audio/wav was unnecessary — writing PCM bytes directly to LameWriter is simpler
|
|
- Hash-bucketed unknowns (4 classes) are sufficient for audio distinction without k-means complexity
|
|
|
|
## Milestone: v1.1 — Custom Sound Mappings
|
|
|
|
**Shipped:** 2026-03-26
|
|
**Phases:** 3 | **Plans:** 6 | **Timeline:** 1 day (2026-03-26)
|
|
**LOC:** ~4,675 Go (+1,421 from v1.0) | **Packages:** 7
|
|
|
|
### What Was Built
|
|
- Four waveform types (sine, square, sawtooth, triangle) with bandlimited additive synthesis
|
|
- TOML config system: auto-discovery, partial overrides, unknown-key validation, `--config` flag
|
|
- User-defined `[[rules]]` classification rules with first-match-wins prepend semantics
|
|
- Auto-frequency assignment (FNV-32a hash) for custom class names
|
|
- `--print-config` flag with commented TOML output and source annotations
|
|
- LoadResult struct pattern for clean config-to-pipeline data flow
|
|
|
|
### What Worked
|
|
- Incremental config extension: Phase 6 built the config package, Phase 7 extended it cleanly
|
|
- TDD plans (type: tdd in frontmatter) produced higher-quality code with fewer regressions
|
|
- FNV-32a frequency assignment was verified experimentally during research before planning
|
|
- Worktree isolation for parallel executor agents prevented merge conflicts
|
|
- Reusing existing patterns (Rule struct, NewClassifier injection, Cobra flag-on-root) kept code consistent
|
|
|
|
### What Was Inefficient
|
|
- SUMMARY.md one-liner extraction continued to be noisy — summary-extract needs improvement
|
|
- Phase 5 could potentially have been merged with Phase 6 (waveform + config together)
|
|
|
|
### Patterns Established
|
|
- LoadResult struct for multi-value config returns (extensible without breaking callers)
|
|
- Pointer fields (`*float64`, `*string`) for partial TOML override semantics
|
|
- FNV-32a hash for deterministic resource assignment from string keys
|
|
- Flag-on-root pattern for early-exit operations (--list-interfaces, --print-config)
|
|
- `addAutoFreqEntries()` pattern: fill gaps in config before merge
|
|
|
|
### Key Lessons
|
|
- BurntSushi/toml Undecoded() works with array-of-tables (verified experimentally)
|
|
- Manual string building beats TOML encoder when you need inline comments/annotations
|
|
- Config extension is smooth when the original Load() was designed with clean boundaries
|
|
|
|
## Milestone: v1.2 — Extended Protocol Coverage
|
|
|
|
**Shipped:** 2026-03-27
|
|
**Phases:** 4 | **Plans:** 7 | **Timeline:** 1 day (2026-03-27)
|
|
**LOC:** ~6,000 Go (+1,325 from v1.1) | **Files:** 19 modified
|
|
|
|
### What Was Built
|
|
- Removed stale constants and future-proofed test bounds (Nyquist-based validation)
|
|
- Rebalanced all ClassFreqConfigs to major-second ladder in family frequency bands (65-3250 Hz) with Group field
|
|
- 21 new TrafficClass constants and 30 port-matching rules across 7 protocol families
|
|
- 28 new classification subtests covering all new port/protocol/transport combinations
|
|
- 21 ClassFreqConfigs entries with family-coherent sound design
|
|
- Group-ordered --print-config with section headers and [groups] TOML reassignment
|
|
|
|
### What Worked
|
|
- Cleanup-first approach (Phase 8) prevented cascading test failures throughout the milestone
|
|
- Design-before-code (Phase 9 frequency table locked before any protocol code) avoided retroactive rebalancing
|
|
- Strict phase ordering (constants -> rules -> config) kept three-location atomicity tests green
|
|
- Musical interval spacing (major second ratio 1.122) produced perceptually distinct yet family-coherent sounds
|
|
- Oscillator normalization bug caught and fixed during frequency rebalancing (math.Abs for alternating-sign harmonics)
|
|
|
|
### What Was Inefficient
|
|
- Phase 9 plan 09-01 ROADMAP checkbox wasn't updated after execution — milestone readiness check showed incomplete
|
|
- REQUIREMENTS.md traceability wasn't updated for Phase 9 completions (FREQ-01 through GRP-04 still showed Pending)
|
|
- STATE.md accumulated merge conflict markers from earlier worktree operations, persisted unnoticed
|
|
|
|
### Patterns Established
|
|
- Group field as string (not enum) on FreqConfig — extensible without code changes
|
|
- Major-second ladder pattern for family-band frequency allocation
|
|
- groupOrder canonical slice for deterministic section ordering in config output
|
|
- rawConfig Groups map for TOML [groups] table parsing
|
|
|
|
### Key Lessons
|
|
- Musical interval ratios are better than fixed Hz steps for frequency allocation — prevents critical band masking
|
|
- Group-based config output requires building from effective (post-reassignment) groups, not defaults
|
|
- Cleanup phases are high-ROI when they prevent test failures in every subsequent phase
|
|
|
|
## Cross-Milestone Trends
|
|
|
|
| Metric | v1.0 | v1.1 | v1.2 |
|
|
|--------|------|------|------|
|
|
| Phases | 4 | 3 | 4 |
|
|
| Plans | 11 | 6 | 7 |
|
|
| Days | 3 | 1 | 1 |
|
|
| LOC | 3,254 | 4,675 | ~6,000 |
|
|
| Avg plan duration | ~8 min | ~5 min | ~4 min |
|