docs(01): capture phase context

.planning/phases/01-capture-and-classification/01-CONTEXT.md

@@ -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*

.planning/phases/01-capture-and-classification/01-DISCUSSION-LOG.md

@@ -0,0 +1,95 @@
+# Phase 1: Capture and Classification - Discussion Log
+
+> **Audit trail only.** Do not use as input to planning, research, or execution agents.
+> Decisions are captured in CONTEXT.md — this log preserves the alternatives considered.
+
+**Date:** 2026-03-25
+**Phase:** 1-capture-and-classification
+**Areas discussed:** Protocol mapping, Privilege model
+
+---
+
+## Protocol mapping
+
+### Q1: How granular should protocol classification be?
+
+| Option | Description | Selected |
+|--------|-------------|----------|
+| Port-aware | ICMP, DNS (53), HTTPS (443), HTTP (80), SSH (22), other-TCP, other-UDP — 7 classes | |
+| Protocol-only | ICMP, TCP, UDP, DNS — 4 broad classes, simpler but less distinctive | |
+| Deep port map | ICMP, DNS, HTTPS, HTTP, SSH, SMTP, NTP, DHCP, other-TCP, other-UDP — 10+ classes | ✓ |
+
+**User's choice:** Deep port map
+**Notes:** User wants maximum sonic variety from the classification layer.
+
+### Q2: Should the classifier be extensible or hardcoded?
+
+| Option | Description | Selected |
+|--------|-------------|----------|
+| Hardcoded table | Map in code: port/proto → class name. Simple, fast | |
+| Config-driven | Rules in a Go map/struct that could later be loaded from file | ✓ |
+| You decide | Claude picks the approach | |
+
+**User's choice:** Config-driven
+**Notes:** Extensibility for future custom mappings.
+
+### Q3: How should unknown traffic be labeled before Phase 3 auto-clustering?
+
+| Option | Description | Selected |
+|--------|-------------|----------|
+| Single "unknown" | All unrecognized traffic grouped as one class | ✓ |
+| Unknown by proto | "unknown-tcp" and "unknown-udp" as separate buckets | |
+| You decide | Claude picks | |
+
+**User's choice:** Single "unknown"
+**Notes:** None.
+
+---
+
+## Privilege model
+
+### Q1: Which platforms should be supported?
+
+| Option | Description | Selected |
+|--------|-------------|----------|
+| Linux only | Simplest — CAP_NET_RAW or sudo | |
+| Linux + macOS | macOS uses BPF devices, different privilege model | ✓ |
+| All major | Linux + macOS + Windows — significantly more work | |
+
+**User's choice:** Linux + macOS
+**Notes:** None.
+
+### Q2: How should the tool handle insufficient privileges?
+
+| Option | Description | Selected |
+|--------|-------------|----------|
+| Detect and guide | Detect OS, show platform-specific fix instructions | ✓ |
+| Just suggest sudo | Simple 'try running with sudo' message | |
+| You decide | Claude picks | |
+
+**User's choice:** Detect and guide
+**Notes:** Platform-specific actionable error messages.
+
+### Q3: Static or dynamic linking?
+
+| Option | Description | Selected |
+|--------|-------------|----------|
+| Static preferred | Single binary, no libpcap needed at runtime | ✓ |
+| Dynamic is fine | Users install libpcap-dev | |
+| You decide | Claude picks based on what's practical | |
+
+**User's choice:** Static preferred
+**Notes:** Aligns with single-binary distribution goal.
+
+---
+
+## Claude's Discretion
+
+- CLI output formatting (stderr layout, colors, table width)
+- Default time window duration
+- Default interface selection when `-i` omitted
+- Verbose output format and detail level
+
+## Deferred Ideas
+
+None — discussion stayed within phase scope.