docs(01): capture phase context

2026-03-25 11:14:49 +01:00
parent 012791cb6f
commit d043180f88
2 changed files with 177 additions and 0 deletions
@@ -0,0 +1,82 @@
+# Phase 1: Capture and Classification - Context
+
+**Gathered:** 2026-03-25
+**Status:** Ready for planning
+
+<domain>
+## Phase Boundary
+
+Live packet capture from a network interface, protocol classification into named traffic classes, CLI scaffolding with interface selection and verbose output. No audio synthesis — this phase validates the capture-to-classify pipeline only.
+
+</domain>
+
+<decisions>
+## Implementation Decisions
+
+### Protocol mapping
+- **D-01:** Deep port map with 10+ classes: ICMP, DNS (53), HTTPS (443), HTTP (80), SSH (22), SMTP (25), NTP (123), DHCP (67/68), other-TCP, other-UDP
+- **D-02:** Classification rules stored in a config-driven Go map/struct (not hardcoded switch statements) — designed so rules could later be loaded from a config file
+- **D-03:** All unrecognized traffic grouped as a single "unknown" class until Phase 3 adds auto-clustering
+
+### Privilege model
+- **D-04:** Support Linux and macOS (not Windows)
+- **D-05:** On permission failure, detect the OS and show platform-specific guidance: `sudo setcap cap_net_raw+ep ...` on Linux, `sudo ...` on macOS
+- **D-06:** Prefer static binary with no runtime libpcap dependency — use pure-Go pcap backend (go-pcap) where possible
+
+### Claude's Discretion
+- CLI output formatting during capture (stderr layout, colors, table width)
+- Default time window duration for aggregation buckets
+- Default network interface selection when `-i` is omitted
+- Verbose output format and level of detail
+
+</decisions>
+
+<canonical_refs>
+## Canonical References
+
+**Downstream agents MUST read these before planning or implementing.**
+
+No external specs — requirements fully captured in decisions above and in:
+- `.planning/PROJECT.md` — Project context, constraints, key decisions
+- `.planning/REQUIREMENTS.md` — CAPT-01 through CAPT-04, CLAS-01, CLAS-03, CLAS-04
+- `.planning/research/STACK.md` — Go library recommendations (gopacket fork, go-pcap, cobra)
+- `.planning/research/PITFALLS.md` — CAP_NET_RAW silently fails on nosuid mounts, packet buffer overflow, gopacket fork status
+- `.planning/research/ARCHITECTURE.md` — Pipeline architecture, component boundaries
+
+</canonical_refs>
+
+<code_context>
+## Existing Code Insights
+
+### Reusable Assets
+- None — greenfield project, no existing code
+
+### Established Patterns
+- None yet — Phase 1 establishes the patterns
+
+### Integration Points
+- Phase 2 will consume classified traffic data (WindowSnapshot structs) from this phase's pipeline
+- The classifier's output format directly shapes the synthesis engine's input contract
+
+</code_context>
+
+<specifics>
+## Specific Ideas
+
+- The tool should feel like tcpdump in its CLI conventions (`-i`, `--list-interfaces`, stderr for stats)
+- Protocol classification should be granular enough that the eventual audio output has clear sonic variety — 10+ distinct classes
+- Error messages for privilege issues should be immediately actionable, not just "permission denied"
+
+</specifics>
+
+<deferred>
+## Deferred Ideas
+
+None — discussion stayed within phase scope
+
+</deferred>
+
+---
+
+*Phase: 01-capture-and-classification*
+*Context gathered: 2026-03-25*