docs: comprehensive codebase analysis and reference documentation

Add full codebase analysis report, issue history, test environment requirements, external research (TeaSpeak/ReSpeak/YaTQA), and offline protocol references (ReSpeak ts3protocol, TeaSpeak, YaTQA). Add master TODO list with 88 items across 11 categories. Add missing LICENSE files. Branch: docs/codebase-analysis-v2
2026-06-11 09:23:10 +09:00
parent 89bbfa1e18
commit 3b13a7edb4
10 changed files with 6173 additions and 0 deletions
@@ -0,0 +1,542 @@
+# Chanora Codebase Analysis Report
+
+**Date:** 2026-06-11  
+**Branch:** `docs/codebase-analysis-v2`  
+**Scope:** Full codebase analysis — functions, tests, documentation, dead code, duplication, architecture, external research
+
+---
+
+## Table of Contents
+
+1. [Executive Summary](#1-executive-summary)
+2. [Function Inventory](#2-function-inventory)
+3. [Test Coverage](#3-test-coverage)
+4. [Documentation Coverage](#4-documentation-coverage)
+5. [Dead Code Analysis](#5-dead-code-analysis)
+6. [Useless/Redundant Code](#6-uselessredundant-code)
+7. [Duplicated Code](#7-duplicated-code)
+8. [Document Link Coverage](#8-document-link-coverage)
+9. [Git History & Issue Patterns](#9-git-history--issue-patterns)
+10. [PR Analysis](#10-pr-analysis)
+11. [API Gap Analysis](#11-api-gap-analysis)
+12. [Crate Architecture Analysis](#12-crate-architecture-analysis)
+13. [Document Staleness Analysis](#13-document-staleness-analysis)
+14. [Test Environment Requirements](#14-test-environment-requirements)
+15. [External Research](#15-external-research)
+16. [Recommendations](#16-recommendations)
+
+---
+
+## 1. Executive Summary
+
+### Key Metrics
+
+| Metric | Value |
+|--------|-------|
+| **Total Rust public functions** | ~428 |
+| **Total Flutter/Dart functions** | ~586 |
+| **Rust test count** | 359 |
+| **Flutter test count** | 221 |
+| **Total test count** | 580 |
+| **Overall test coverage** | 75% of modules |
+| **Documentation coverage (Rust)** | 30% of functions have doc comments |
+| **Documentation coverage (Flutter)** | 58% of classes documented |
+| **Dead code items** | ~20 (5 definitely dead, 11 likely dead, 4 conditionally dead) |
+| **Duplicated code patterns** | 10 major patterns |
+| **Broken doc links** | 6 (all from missing LICENSE files) |
+| **Orphaned docs** | 14 files |
+| **Stale documents** | 5/8 major docs need updates |
+| **PRs analyzed** | 42 (34 merged, 8 closed) |
+| **Issues documented in history** | 45 significant issues |
+
+### Critical Findings
+
+1. **iOS audio is the #1 problem area** — 15+ issues, AVAudioSession lifecycle is the most recurring root cause
+2. **chanora_audio has 168 public functions but only 24% documented** — largest crate, most complex
+3. **chanora_bridge has 0 tests** — the Flutter-Rust boundary is completely untested
+4. **53 SysRS requirements (SysRS-258–310) lack SysDes allocation** — breaks traceability
+5. **Several features exist without requirements** — poke, file transfer, hard-mute, cache
+6. **engine.rs is 3,244 lines** — monolithic, needs splitting
+7. **main.dart is 2,910 lines** — monolithic, needs splitting
+8. **~39 production `unwrap()` calls in engine.rs** — crash risk on poisoned mutex
+
+---
+
+## 2. Function Inventory
+
+### Summary by Component
+
+| Component | Type | Total `pub fn` | Documented | Coverage |
+|---|---|---|---|---|
+| **chanora_core** | Rust lib | 68 | 65 | 96% |
+| **chanora_audio** | Rust crate | 168 | ~40 | 24% |
+| **chanora_bridge** | Rust crate | 65 | ~10 | 15% |
+| **chanora_protocol** | Rust crate | 35 | 33 | 94% |
+| **chanora_state** | Rust crate | 16 | ~8 | 50% |
+| **chanora_storage** | Rust crate | 20 | ~12 | 60% |
+| **chanora_cache** | Rust crate | 7 | 7 | 100% |
+| **chanora_resolver** | Rust crate | 15 | ~8 | 50% |
+| **chanora_diagnostics** | Rust crate | 27 | ~15 | 50% |
+| **chanora_prefetch** | Rust crate | 7 | 4 | 57% |
+| **Flutter app** | Dart | ~586 | ~5 | <1% |
+
+### Potentially Unused Functions
+
+Functions defined but never called from outside their module:
+
+| Crate | Function | File:Line |
+|---|---|---|
+| chanora_core | `ChanoraSession::protocol_events_snapshot()` | lib.rs:788 |
+| chanora_audio | `AudioEngine::capture_active()` | engine.rs:1621 |
+| chanora_audio | `AudioEngine::frames_sent()` | engine.rs:1626 |
+| chanora_audio | `AudioEngine::frames_received()` | engine.rs:1631 |
+| chanora_audio | `HpfProcessor::process_sample()` | dsp/hpf.rs:63 |
+| chanora_audio | `CoreMlWorker::reset_state()` | apple_coreml.rs:140 |
+| chanora_audio | `PttCapabilityLevel::is_global()` | ptt.rs:72 |
+| chanora_bridge | `handle_media_services_reset_with_route()` | api.rs:696 |
+| chanora_bridge | `handle_interruption_began()` | api.rs:703 |
+| chanora_state | `ServerState::replace_from_snapshot()` | lib.rs:114 |
+| chanora_state | `ServerState::channel_count()` | lib.rs:148 |
+| chanora_state | `ServerState::client_count()` | lib.rs:153 |
+| chanora_storage | `BookmarkStore::upsert_or_add()` | lib.rs:891 |
+| chanora_resolver | `normalize_args()` | lib.rs:778 |
+| chanora_resolver | `validate_args()` | lib.rs:785 |
+
+---
+
+## 3. Test Coverage
+
+### Summary by Component
+
+| Component | Source Modules | Modules w/ Tests | Coverage % | Test Count |
+|---|---|---|---|---|
+| **chanora_audio** | 43 | 35 | 81% | 221 |
+| **chanora_bridge** | 5 | 0 | **0%** | 0 |
+| **chanora_cache** | 1 | 1 | 100% | 7 |
+| **chanora_diagnostics** | 1 | 1 | 100% | 19 |
+| **chanora_prefetch** | 1 | 1 | 100% | 6 |
+| **chanora_protocol** | 4 | 2 | 50% | 23 |
+| **chanora_resolver** | 1 | 1 | 100% | 14 |
+| **chanora_state** | 2 | 2 | 100% | 27 |
+| **chanora_storage** | 1 | 1 | 100% | 15 |
+| **chanora_core** | 5 | 4 | 80% | 27 |
+| **Flutter (services)** | 24 | 22 | 92% | 124 |
+| **Flutter (widgets)** | 25 | 14 | 56% | 97 |
+| **TOTAL** | **113** | **85** | **75%** | **580** |
+
+### Critical Untested Areas
+
+| Component | Module | Risk |
+|---|---|---|
+| **chanora_bridge** | All 5 modules | **High** — FFI boundary, zero tests |
+| **Flutter widgets** | `voice_bar`, `voice_settings`, `connect_widgets` | **High** — core UI |
+| **chanora_protocol** | `dto` module | **Medium** — serialization bugs |
+| **chanora_core** | `events` module | **Medium** — event system |
+
+---
+
+## 4. Documentation Coverage
+
+### Doc Comment Coverage (Rust)
+
+| Crate | Functions | With Doc Comments | Coverage |
+|---|---|---|---|
+| chanora_core | 68 | 65 | 96% |
+| chanora_audio | 168 | ~40 | 24% |
+| chanora_bridge | 65 | ~10 | 15% |
+| chanora_protocol | 35 | 33 | 94% |
+| chanora_cache | 7 | 7 | 100% |
+| chanora_state | 16 | ~8 | 50% |
+| chanora_storage | 20 | ~12 | 60% |
+| chanora_resolver | 15 | ~8 | 50% |
+| chanora_diagnostics | 27 | ~15 | 50% |
+| chanora_prefetch | 7 | 4 | 57% |
+
+### Missing README Files
+
+| Directory | Status |
+|---|---|
+| crates/chanora_audio/ | **MISSING** |
+| crates/chanora_bridge/ | **MISSING** |
+| crates/chanora_cache/ | **MISSING** |
+| crates/chanora_diagnostics/ | **MISSING** |
+| crates/chanora_prefetch/ | **MISSING** |
+| crates/chanora_protocol/ | **MISSING** |
+| crates/chanora_state/ | **MISSING** |
+| crates/chanora_storage/ | **MISSING** |
+| core/chanora_core/ | **MISSING** |
+
+Only `crates/chanora_resolver/README.md` exists.
+
+---
+
+## 5. Dead Code Analysis
+
+### Definitely Dead (safe to remove)
+
+| Item | File:Line | Evidence |
+|------|-----------|----------|
+| `AudioFrame10ms` struct | frame.rs:21 | Never referenced outside tests |
+| `AudioFrame20ms` struct | frame.rs:28 | Never referenced outside tests |
+| `AudioFrame10ms::dbfs()` | frame.rs:58 | Never called anywhere |
+| `disable_failed_vad_backend()` | audio_processing.rs:216 | Only called in tests |
+| `import 'package:share_plus/share_plus.dart'` | main.dart:55 | `Share` class never used |
+
+### Likely Dead (no production callers)
+
+| Item | File:Line |
+|------|-----------|
+| `AudioEngine::output_muted()` | engine.rs:1707 |
+| `AudioEngine::output_gain()` | engine.rs:1720 |
+| `AudioEngine::capture_active()` | engine.rs:1621 |
+| `AudioEngine::transmit_gate()` | engine.rs:1614 |
+| `AudioEngine::set_transmit_active()` | engine.rs:1601 |
+| `AudioEngine::android_diagnostics()` | engine.rs:1694 |
+| `TransmitModeSelector::gate()` | transmit_selector.rs:253 |
+| `TransmitModeSelector::in_channel()` | transmit_selector.rs:198 |
+| `TransmitModeSelector::ptt_held()` | transmit_selector.rs:226 |
+| `ReleaseTailTimer::cancel()` | release_tail.rs:133 |
+| `ReleaseTailTimer::arm()` | release_tail.rs:70 |
+
+### `#[allow(dead_code)]` Annotated Items
+
+| Item | Status |
+|------|--------|
+| `AudioCommand::RemoveClient` | TODO: "Wire to client disconnect path" |
+| `android_render_ring` module | Conditionally dead (non-Android) |
+| `audio_event_queue` module | Conditionally dead (non-Android) |
+| `capture_accumulator` module | Conditionally dead (non-Android) |
+
+---
+
+## 6. Useless/Redundant Code
+
+### TODO/FIXME/HACK Inventory (12 entries, 14 occurrences)
+
+| File | Line | Content |
+|------|------|---------|
+| engine.rs | 2348 | TODO: realtime-audio callback concern |
+| mobile_voice_backend.rs | 16 | TODO(SDD-117): back-fill IosVoiceUnit |
+| audio_event_queue.rs | 27 | TODO: Wire to client disconnect path |
+| audio_lifecycle_service.dart | 151,156 | TODO: macosDefaultDeviceChanged (×2) |
+| poke_notification_service.dart | 33-168 | TODO(event-sounds) (×10) |
+
+### Risky Code
+
+| Risk | Location | Count |
+|------|----------|-------|
+| Production `unwrap()` | engine.rs | ~39 |
+| `unsafe impl Send/Sync` | Various | 8 |
+| `unimplemented!("")` in FRB | frb_generated.rs | 23 |
+
+### Complexity Warnings
+
+| File | Lines | Risk |
+|------|-------|------|
+| engine.rs | 3,244 | **High** — monolithic audio engine |
+| main.dart | 2,910 | **High** — monolithic Flutter entry |
+| adapter.rs | 2,504 | Medium |
+| api.rs | 2,432 | Medium |
+
+---
+
+## 7. Duplicated Code
+
+### Major Patterns
+
+| # | Pattern | Files | Lines Saved | Priority |
+|---|---------|-------|-------------|----------|
+| 1 | AudioProcessingConfig 4× construction | 1 Dart | ~50 | High |
+| 2 | Audio processing toggle UI duplication | 2 Dart | ~150 | High |
+| 3 | `.map_err(format!)` boilerplate | 5 Rust | ~85 closures | Medium |
+| 4 | PttCapability event construction | 1 Rust | ~15 | Medium |
+| 5 | DnsFailed/ServerRejected error mirroring | 2 Rust | ~20 | Medium |
+| 6 | Platform detection scatter | 6 Dart | ~35 checks | Medium |
+| 7 | Host normalization `trim().to_lowercase()` | 3 Rust | ~5 sites | Low |
+| 8 | `create_dir_all` pattern | 2 Rust | ~3 sites | Low |
+| 9 | `Io(String)` error variant | 3 Rust | ~10 | Low |
+| 10 | StateEvent ↔ Delta mirror | 1 Rust | ~5 | Low |
+
+---
+
+## 8. Document Link Coverage
+
+| Metric | Value |
+|--------|-------|
+| Total links checked | 38 |
+| Valid links | 32 |
+| Broken links | 6 |
+| Health rate | 84.2% |
+| Orphaned docs | 14 / 65 (21.5%) |
+
+### Broken Links
+
+All 6 broken links stem from missing `LICENSE-APACHE` and `LICENSE-MIT` files at project root.
+
+### Orphaned Documentation (14 files)
+
+Mostly in `docs/superpowers/plans/` and `docs/superpowers/specs/` — not linked from any index document.
+
+---
+
+## 9. Git History & Issue Patterns
+
+### Issue Categories (45 significant issues)
+
+| Category | Count | Severity |
+|----------|-------|----------|
+| iOS audio (AVAudioSession/VPIO) | 15+ | Most problematic |
+| Realtime thread safety (Mutex) | 5+ | Cross-platform |
+| Build toolchain (Xcode Archive) | 4+ | CI-blocking |
+| Platform-specific build | 5+ | Cross-compilation |
+| Flutter framework bugs | 3+ | Workarounds needed |
+| Protocol failures | 3+ | Silent failures |
+
+### Key Patterns
+
+1. **iOS AVAudioSession has 7+ interacting configuration dimensions** — each fix reveals the next layer
+2. **Realtime audio callbacks must NEVER use `Mutex::lock()`** — always `try_lock()` with silence fallback
+3. **Always verify with `xcodebuild archive`** — not just `flutter build`
+4. **Every protocol command should surface errors to UI** — fire-and-forget hides failures
+
+---
+
+## 10. PR Analysis
+
+### PR Summary (42 total)
+
+| Type | Count | Merged |
+|------|-------|--------|
+| Features | 15 | 7 |
+| Bug fixes | 15 | 12 |
+| Refactoring | 4 | 3 |
+| Documentation | 1 | 1 |
+| Build/Chore | 4 | 4 |
+| Performance | 1 | 1 |
+
+### Most Active Areas
+
+| Area | PR Count |
+|------|----------|
+| iOS Audio | 10+ |
+| macOS Audio | 5 |
+| Voice/VAD | 6 |
+| Flutter UI | 8 |
+| Protocol/State | 5 |
+
+### Development Patterns
+
+- **Self-review via "Oracle" agent** — effective quality gate
+- **Local CI mirroring** — GitHub Actions billing broken
+- **PR stacking complexity** — need better branch management
+- **Follow-up fix pattern** — PRs stay focused
+
+---
+
+## 11. API Gap Analysis
+
+### Requirements with NO or Minimal Implementation
+
+| Requirement | ID | Status |
+|---|---|---|
+| UI settings persistence | SysRS-143, SRS-087 | **Missing** |
+| Per-user mute persistence | SysRS-145, SRS-088 | **Missing** |
+| Event replay tool | SysRS-171, SRS-098 | **Missing** |
+| Audio loopback test tool | SysRS-073, SRS-083 | **Missing** | SRS-083 covers both loopback and processing test tools |
+| Audio processing test tool | SysRS-074, SRS-083 | **Missing** | SRS-083 shared with SysRS-073 |
+| Protocol probe tool | SysRS-128, SRS-123 | **Missing** |
+| Notification permission | SysRS-166, SRS-109 | **Missing** |
+| Recent server management | SysRS-141, SRS-085 | **Partial** |
+| Per-user volume persistence | SysRS-144, SRS-088 | **Partial** |
+| Input validation | SysRS-157, SRS-094 | **Partial** |
+
+### Missing Bridge Functions
+
+| Capability | Gap |
+|---|---|
+| `is_hard_muted()` | Missing read for hard-mute state |
+| `get_output_gain()` | Missing gain read-back |
+| `get_client_volume()` | Missing per-client volume read |
+| `connection_state()` | UI must derive from events only |
+| `reconnect()` | No manual trigger |
+
+### Hardcoded Implementations
+
+| Location | Issue |
+|---|---|
+| `adapter.rs:141` | `pick_client_version()` returns Windows version for ALL platforms |
+| `api.rs:350-356` | `log_file_path()` Android returns `None` |
+| `chanora_storage` | `keyring_load()` on Android returns `Ok(None)` always |
+
+---
+
+## 12. Crate Architecture Analysis
+
+### Current Dependency Graph
+
+```
+chanora_bridge
+  └─ chanora_core
+       ├─ chanora_audio ────── chanora_protocol ───── chanora_resolver
+       ├─ chanora_state ────── chanora_protocol
+       ├─ chanora_storage     (standalone)
+       ├─ chanora_cache       (standalone)
+       ├─ chanora_diagnostics (standalone)
+       └─ chanora_prefetch ── chanora_resolver
+```
+
+**No circular dependencies.** Max depth: 3 levels.
+
+### Crate Size
+
+| Crate | Source Lines | Files |
+|-------|-------------|-------|
+| **chanora_audio** | **18,895** | 26 |
+| chanora_bridge | 7,579 | 5 |
+| chanora_protocol | 3,372 | 4 |
+| chanora_core | 2,716 | 5 |
+| chanora_state | 1,870 | 2 |
+| chanora_resolver | 1,434 | 1 |
+| chanora_storage | 1,332 | 1 |
+| chanora_diagnostics | 1,118 | 1 |
+| chanora_cache | 359 | 1 |
+| chanora_prefetch | 312 | 1 |
+
+### chanora_audio Split Recommendation
+
+**Option A — Extract platform backends (recommended):**
+
+| New Crate | Contents | Lines |
+|---|---|---|
+| `chanora_audio` (core) | engine, frame types, transmit, VAD, DSP, PTT trait | ~8,000 |
+| `chanora_audio_android` | android_voice_unit, render_ring, event_queue, Oboe | ~3,200 |
+| `chanora_audio_apple` | ios_voice_unit, coreaudio-rs | ~1,400 |
+| `chanora_audio_desktop` | cpal, sdl_output, Windows/Linux PTT | ~3,500 |
+
+**Rationale:** Platform backends are 100% cfg-gated. Splitting removes heavy platform dependencies from core.
+
+### Common Code Extraction
+
+**Not justified at this time.** Patterns are too small for a `chanora_common` crate.
+
+---
+
+## 13. Document Staleness Analysis
+
+### Freshness Scores
+
+| Document | Score | Status |
+|---|---|---|
+| docs/sysrs.md | 8/10 | Mostly current |
+| docs/srs.md | 7/10 | Missing newer requirements |
+| docs/sysdes.md | 6/10 | Missing 53 SysRS allocations |
+| docs/architecture/sdd.md | 5/10 | Missing many modules |
+| docs/architecture/sad.md | 5/10 | Missing components |
+| docs/verification/verification-master-plan.md | 6/10 | Stale evidence source |
+| docs/governance/traceability-matrix.md | 5/10 | SRS ID mismatches |
+| docs/implementation-status-2026-05-28.md | 3/10 | 14 days stale |
+
+### Critical Staleness Issues
+
+1. **53 SysRS requirements (SysRS-258–310) lack SysDes allocation** — breaks traceability
+2. **Multiple features without requirements** — poke, file transfer, hard-mute, cache
+3. **SRS numbering mismatches** in traceability matrix
+4. **Implementation status 14 days stale** — missing v0.3.0 features
+
+---
+
+## 14. Test Environment Requirements
+
+### Current CI Coverage
+
+| Platform | CI Status |
+|----------|-----------|
+| Ubuntu (Rust + Flutter) | ✅ Automated |
+| macOS (iOS unsigned build) | ✅ Automated |
+| Android | ❌ Not in CI |
+| Windows | ❌ Not in CI |
+| macOS (native) | ❌ Not in CI |
+| Linux (non-Ubuntu) | ❌ Not in CI |
+
+### Physical Devices Needed
+
+| Device | Purpose | Est. Cost |
+|---|---|---|
+| iPhone 14+ | iOS audio, CoreML VAD | $600-800 |
+| Android phone (arm64) | Android audio, Oboe | $200-400 |
+| Windows PC | Windows PTT, audio | $500-800 |
+| Linux PC | GNOME/Wayland, PipeWire | $500-800 |
+| Audio peripherals | USB/BT headset testing | $100 |
+| **Total** | | **$2,400-4,200** |
+
+### Implementation Roadmap
+
+| Phase | Timeline | Focus |
+|-------|----------|-------|
+| Foundation | Weeks 1-4 | Android/Windows/macOS CI builds |
+| Device Integration | Weeks 5-8 | Physical devices, audio loopback |
+| Full Automation | Weeks 9-12 | E2E tests, audio quality, Firebase |
+
+---
+
+## 15. External Research
+
+### TeaSpeak
+
+- **Status:** Effectively unmaintained since ~2022
+- **Architecture:** Closed-source server, TypeScript web client, C++ music bot
+- **Lesson for Chanora:** Open-source client + formal engineering process is the right approach
+- **Market validation:** TeaSpeak's abandonment creates opportunity for Chanora
+
+### ReSpeak
+
+- **Status:** Active, 16 repositories, tsclientlib is the core library
+- **Chanora dependency:** Uses `tsclientlib` (forked) for protocol implementation
+- **Key repos:** `tsclientlib` (protocol), `tsdeclarations` (protocol spec), `quicklz` (compression)
+- **Recommendation:** Continue using tsclientlib, consider upstreaming p256 fix
+
+### yat.qa (YaTQA)
+
+- **What it is:** Windows GUI tool for TeamSpeak 3 ServerQuery management (NOT a testing/QA site)
+- **Relevance:** Low — management tool, not testing framework
+- **Useful resources:** Unofficial ServerQuery docs, server error codes, permission IDs, anti-flood mechanics
+
+---
+
+## 16. Recommendations
+
+### P0 — Critical (do immediately)
+
+1. **Add `chanora_bridge` tests** — 0/5 modules tested, FFI boundary is highest risk
+2. **Replace `Mutex::lock().unwrap()` in engine.rs** — ~39 calls, crash risk
+3. **Update implementation-status document** — 14 days stale, primary evidence source
+4. **Allocate SysRS-258–310 in SysDes** — breaks traceability chain
+5. **Fix traceability matrix SRS numbering** — IDs don't match actual SRS
+
+### P1 — High Priority (next sprint)
+
+6. **Add Android/Windows/macOS CI builds** — currently only Ubuntu
+7. **Add missing bridge functions** — `get_hard_mute()`, `get_connection_state()`, `reconnect()`
+8. **Add README files to all 8 crates + core**
+9. **Split engine.rs** (3,244 lines) into smaller modules
+10. **Add requirements for implemented features** — poke, file transfer, hard-mute, cache
+
+### P2 — Medium Priority
+
+11. **Extract platform backends from chanora_audio** — compile-time benefit
+12. **Add doc comments to chanora_audio** (24% → 80% target)
+13. **Fix `pick_client_version()` hardcoded to Windows**
+14. **Implement per-user volume/mute persistence**
+15. **Add UI settings store**
+
+### P3 — Low Priority
+
+16. **Clean up dead code** (25+ items)
+17. **Deduplicate code patterns** (10 major patterns)
+18. **Fix broken doc links** (create LICENSE files)
+19. **Link orphaned documentation**
+20. **Add protocol probe tool**
+
+---
+
+*Generated by codebase analysis agents on 2026-06-11*
@@ -0,0 +1,157 @@
+# Issue History Analysis
+
+**Date:** 2026-06-11  
+**Scope:** All git history, PRs, and issue patterns
+
+---
+
+## 1. Issue Categories
+
+### iOS Audio (15+ issues) — Most Problematic Area
+
+| Commit | Issue | Root Cause | Fix |
+|--------|-------|------------|-----|
+| #42 (OPEN) | AVAudioSession not activated before connect | Auto-join spawns VPIO before session in playAndRecord mode | Activate session BEFORE rust.connect |
+| #41 | iOS Debug builds blocked | Debug.xcconfig missing `-u` flags; verify script checked wrong Mach-O | Mirror Release xcconfig; check correct dylib |
+| #38 | Audio session dead after "already in channel" | Server response 0x0302 treated as failure | Keep session active on already-in-channel |
+| #33 | App kills other apps' audio while idle | Held `.playAndRecord` from launch | Idle baseline now `.ambient`; escalate during calls |
+| #28 | False underrun counters when muted | `peak_i16 == 0` check didn't gate on muted state | Gate underrun on `!muted` |
+| #26 | Silero exports stripped in Xcode Archive | `ld -dead_strip` removed unreferenced symbols | `-exported_symbol` whitelist in xcconfigs |
+| #10 | Voice join stuck at "Connecting" | Audio startup blocking connect critical path | Move audio startup off connect path |
+
+**Pattern:** iOS AVAudioSession has 7+ interacting configuration dimensions. Each fix reveals the next layer.
+
+### Realtime Thread Safety (5+ issues)
+
+| Commit | Issue | Root Cause | Fix |
+|--------|-------|------------|-----|
+| #20 | Android audio output stutter | Mutex contention in audio callback | Oboe config tuning + lock-free callback |
+| #27 | macOS audio event queue | Lock contention in render path | Lock-free ArrayQueue pattern |
+| engine.rs:39 | ~39 `unwrap()` calls on Mutex | Poisoned mutex will panic engine | Need `try_lock()` or `parking_lot::Mutex` |
+
+**Pattern:** Realtime audio callbacks must NEVER use `Mutex::lock()` — always `try_lock()` with silence fallback.
+
+### Build Toolchain (4+ issues)
+
+| Commit | Issue | Root Cause | Fix |
+|--------|-------|------------|-----|
+| #41 | iOS Debug builds fail | Debug.xcconfig diverged from Release | Mirror Release settings in Debug |
+| #26 | Silero exports stripped | `ld -dead_strip` + install-time `strip` | `-exported_symbol` whitelist + `STRIP_STYLE = non-global` |
+| #37 | MSVC CRT mismatch | cmake linking wrong CRT | `cmake-msvc-release-crt.cmd` |
+
+**Pattern:** Always verify with `xcodebuild archive`, not just `flutter build`.
+
+### Protocol Issues (3+ issues)
+
+| Commit | Issue | Root Cause | Fix |
+|--------|-------|------------|-----|
+| #16 | Speaking state incorrect for non-self clients | Client profiles not refreshed before mapping | Refresh non-self profiles |
+| #16 | Server-query clients missing | Missing protocol DTO fields | Add ping deviation through full stack |
+| #5 | UI crashes on unexpected state transitions | Missing null/mounted guards | Guard deferred side effects |
+
+**Pattern:** Every protocol command should surface errors to UI — fire-and-forget hides failures.
+
+---
+
+## 2. PR Development Patterns
+
+### PR Summary (42 total, 34 merged, 8 closed)
+
+| Type | Count | Merged |
+|------|-------|--------|
+| Features | 14 | 10 |
+| Bug fixes | 12 | 12 |
+| Refactoring | 4 | 3 |
+| Documentation | 1 | 1 |
+| Build/Chore | 4 | 4 |
+| Performance | 1 | 1 |
+| Dependency | 1 | 0 |
+| Closed (superseded) | 5 | 0 |
+
+### Most Active Areas
+
+| Area | PR Count | Notes |
+|------|----------|-------|
+| iOS Audio | 10+ | Most recurring issues |
+| macOS Audio | 5 | Lock-free architecture |
+| Voice/VAD | 6 | CoreML, ONNX, WebRTC |
+| Flutter UI | 8 | Event-driven, responsive |
+| Protocol/State | 5 | State reducers, events |
+
+### Quality Patterns
+
+1. **Self-review via "Oracle" agent** — catches real issues pre-merge
+2. **Local CI mirroring** — GitHub Actions billing broken
+3. **PR stacking** — need better branch management workflow
+4. **Follow-up fix pattern** — PRs stay focused
+
+---
+
+## 3. Test Cases for Known Issues
+
+### iOS Audio Session Lifecycle
+
+```dart
+// Test: Session activates before connect
+test('voice_join activates AVAudioSession before starting voice', () async {
+  // Verify session state transitions: ambient → playAndRecord → ambient
+});
+
+// Test: Already-in-channel response keeps session active
+test('voice_join keeps session active on already-in-channel response', () async {
+  // Mock server response code 0x0302
+  // Verify session remains in playAndRecord state
+});
+
+// Test: Idle app doesn't kill other audio
+test('app uses ambient mode when not in voice channel', () async {
+  // Verify session mode is .ambient + .mixWithOthers when idle
+});
+```
+
+### Realtime Thread Safety
+
+```rust
+// Test: Audio callback doesn't panic on poisoned mutex
+#[test]
+fn audio_callback_survives_poisoned_mutex() {
+    // Verify try_lock fallback produces silence, not panic
+}
+```
+
+### Protocol Error Surfacing
+
+```dart
+// Test: Server errors surface to UI
+test('server error messages are forwarded as UI events', () async {
+  // Mock protocol error
+  // Verify UI receives error event
+});
+```
+
+### Build Verification
+
+```bash
+# Test: iOS Debug build succeeds
+xcodebuild -workspace ios/Runner.xcworkspace -scheme Runner -configuration Debug build
+
+# Test: iOS Archive build preserves Silero exports
+xcodebuild archive -workspace ios/Runner.xcworkspace -scheme Runner
+# Verify: nm -g archive.xcarchive/Products/Applications/Chanora.app/Chanora | grep silero
+```
+
+---
+
+## 4. Root Cause Patterns
+
+| Pattern | Frequency | Prevention |
+|---------|-----------|------------|
+| iOS AVAudioSession lifecycle | 8+ PRs | Document state machine, add integration tests |
+| Mutex on realtime threads | 5+ issues | Use `try_lock()` or `parking_lot::Mutex` |
+| Xcode Archive vs build divergence | 4+ issues | Always test with `xcodebuild archive` |
+| Silent protocol failures | 3+ issues | Surface all errors to UI |
+| Platform-specific build quirks | 5+ issues | CI on all target platforms |
+
+---
+
+*Generated by git history analysis agents on 2026-06-11*
@@ -0,0 +1,692 @@
+# Master TODO List
+
+**Date:** 2026-06-11
+**Branch:** `docs/codebase-analysis-v2`
+**Sources:**
+- `docs/governance/codebase-analysis-2026-06-11.md` — main codebase analysis
+- `docs/governance/issue-history-analysis.md` — git history patterns and root causes
+- `docs/verification/test-environment-requirements.md` — test environment setup needs
+- `docs/references/external-research-2026-06-11.md` — external research findings
+
+---
+
+## Summary
+
+| Category | P0 | P1 | P2 | P3 | Total |
+|---|---|---|---|---|---|
+| Dead Code Removal | 0 | 0 | 0 | 5 | 5 |
+| Code Quality | 2 | 2 | 3 | 2 | 9 |
+| Test Coverage | 2 | 3 | 2 | 0 | 7 |
+| Architecture | 0 | 2 | 2 | 1 | 5 |
+| Documentation | 3 | 2 | 3 | 2 | 10 |
+| Missing APIs / Requirements | 0 | 2 | 7 | 2 | 11 |
+| Infrastructure | 0 | 3 | 5 | 1 | 9 |
+| External Research Follow-up | 0 | 1 | 2 | 2 | 5 |
+| Protocol Implementation | 0 | 2 | 8 | 3 | 13 |
+| Reference Document Improvements | 0 | 0 | 9 | 1 | 10 |
+| Additional Traceability Gaps | 0 | 0 | 3 | 1 | 4 |
+| **Total** | **7** | **17** | **44** | **20** | **88** |
+
+---
+
+## 1. Dead Code Removal
+
+### TODO-001 — Remove dead AudioFrame structs
+- **Priority:** P3
+- **Source:** codebase-analysis §5
+- **Description:** `AudioFrame10ms` and `AudioFrame20ms` structs and `AudioFrame10ms::dbfs()` are never referenced outside tests. Safe to delete.
+- **Effort:** S
+- **Dependencies:** None
+
+### TODO-002 — Remove dead `disable_failed_vad_backend()`
+- **Priority:** P3
+- **Source:** codebase-analysis §5
+- **Description:** Function only called in tests. Remove from production code.
+- **Effort:** S
+- **Dependencies:** None
+
+### TODO-003 — Remove unused `share_plus` import
+- **Priority:** P3
+- **Source:** codebase-analysis §5
+- **Description:** `import 'package:share_plus/share_plus.dart'` in main.dart:55 — `Share` class never used.
+- **Effort:** S
+- **Dependencies:** None
+
+### TODO-004 — Audit and remove likely-dead functions (16 across 5 crates)
+- **Priority:** P3
+- **Source:** codebase-analysis §2, §5
+- **Description:** 16 functions have no production callers. From §5: 11 AudioEngine/TransmitModeSelector/ReleaseTailTimer methods (output_muted, output_gain, capture_active, transmit_gate, set_transmit_active, android_diagnostics, gate, in_channel, ptt_held, cancel, arm) + `AudioEngine::frames_sent()` and `AudioEngine::frames_received()`. From §2: `ChanoraSession::protocol_events_snapshot()` (chanora_core), `ServerState::replace_from_snapshot()/channel_count()/client_count()` (chanora_state), `BookmarkStore::upsert_or_add()` (chanora_storage), `normalize_args()/validate_args()` (chanora_resolver), `HpfProcessor::process_sample()` (chanora_audio), `CoreMlWorker::reset_state()` (chanora_audio), `PttCapabilityLevel::is_global()` (chanora_audio), `handle_media_services_reset_with_route()/handle_interruption_began()` (chanora_bridge). Confirm with call-graph then remove or wire.
+- **Effort:** M
+- **Dependencies:** None
+
+### TODO-005 — Decide fate of `#[allow(dead_code)]` items
+- **Priority:** P3
+- **Source:** codebase-analysis §5
+- **Description:** `AudioCommand::RemoveClient` has TODO to wire to client disconnect path. Three Android-only modules are conditionally dead. Decide: wire, remove, or keep annotated.
+- **Effort:** M
+- **Dependencies:** None
+
+---
+
+## 2. Code Quality
+
+### TODO-006 — Replace ~39 `Mutex::lock().unwrap()` calls in engine.rs
+- **Priority:** P0
+- **Source:** codebase-analysis §6, issue-history §1 (realtime thread safety)
+- **Description:** Production `unwrap()` on Mutex locks will panic on poisoned mutex. Replace with `try_lock()` + silence fallback or `parking_lot::Mutex`.
+- **Effort:** L
+- **Dependencies:** None
+
+### TODO-007 — Audit 8 `unsafe impl Send/Sync` blocks
+- **Priority:** P0
+- **Source:** codebase-analysis §6
+- **Description:** 8 unsafe Send/Sync impls across various files. Each needs safety proof comment and review.
+- **Effort:** M
+- **Dependencies:** None
+
+### TODO-008 — Resolve 14 TODO/FIXME/HACK entries in codebase
+- **Priority:** P1
+- **Source:** codebase-analysis §6
+- **Description:** 14 occurrences across engine.rs, mobile_voice_backend.rs, audio_event_queue.rs, audio_lifecycle_service.dart, poke_notification_service.dart. Address or convert to tracked issues.
+- **Effort:** L
+- **Dependencies:** None
+
+### TODO-009 — Audit 23 `unimplemented!("")` in frb_generated.rs
+- **Priority:** P1
+- **Source:** codebase-analysis §6
+- **Description:** Flutter-Rust Bridge generated stubs contain 23 `unimplemented!("")` calls that will panic at runtime if hit. Audit and implement or guard each one.
+- **Effort:** M
+- **Dependencies:** None
+
+### TODO-010 — Fix `pick_client_version()` hardcoded to Windows
+- **Priority:** P2
+- **Source:** codebase-analysis §11
+- **Description:** `adapter.rs:141` returns Windows client version for ALL platforms. Must return platform-appropriate version strings.
+- **Effort:** S
+- **Dependencies:** None
+
+### TODO-011 — Fix Android stubs returning None/Ok(None)
+- **Priority:** P2
+- **Source:** codebase-analysis §11
+- **Description:** `log_file_path()` on Android returns `None` (api.rs:350-356), `keyring_load()` on Android returns `Ok(None)` always. These silently hide functionality gaps.
+- **Effort:** S
+- **Dependencies:** None
+
+### TODO-012 — Deduplicate AudioProcessingConfig construction (4x)
+- **Priority:** P2
+- **Source:** codebase-analysis §7
+- **Description:** AudioProcessingConfig is constructed identically in 4 places in Dart. Extract to factory or shared config.
+- **Effort:** S
+- **Dependencies:** None
+
+### TODO-013 — Deduplicate audio processing toggle UI
+- **Priority:** P3
+- **Source:** codebase-analysis §7
+- **Description:** Audio processing toggle UI duplicated across 2 Dart files (~150 lines). Extract shared widget.
+- **Effort:** S
+- **Dependencies:** None
+
+### TODO-014 — Deduplicate low-priority code patterns (7 patterns)
+- **Priority:** P3
+- **Source:** codebase-analysis §7
+- **Description:** PttCapability event construction (1 Rust, ~15 lines), DnsFailed/ServerRejected error mirroring (2 Rust, ~20 lines), host normalization (3 Rust files), create_dir_all (2 Rust files), Io(String) variant (3 crates), StateEvent/Delta mirror (1 Rust file), platform detection scatter (6 Dart, ~35 checks).
+- **Effort:** M
+- **Dependencies:** None
+
+---
+
+## 3. Test Coverage
+
+### TODO-015 — Add chanora_bridge tests (0/5 modules tested)
+- **Priority:** P0
+- **Source:** codebase-analysis §3
+- **Description:** The Flutter-Rust FFI boundary has zero tests. This is the highest-risk untested area. Need unit tests for all 5 bridge modules.
+- **Effort:** XL
+- **Dependencies:** None
+
+### TODO-016 — Add poisoned-mutex survival test for audio callbacks
+- **Priority:** P0
+- **Source:** issue-history §3
+- **Description:** Verify `try_lock()` fallback produces silence rather than panic when mutex is poisoned. Directly tests the fix for TODO-006.
+- **Effort:** M
+- **Dependencies:** TODO-006
+
+### TODO-017 — Add Flutter widget tests for untested core UI
+- **Priority:** P1
+- **Source:** codebase-analysis §3
+- **Description:** `voice_bar`, `voice_settings`, `connect_widgets` modules have no tests. These are core UI components at 56% widget coverage.
+- **Effort:** L
+- **Dependencies:** None
+
+### TODO-018 — Add chanora_protocol dto module tests
+- **Priority:** P1
+- **Source:** codebase-analysis §3
+- **Description:** Protocol dto module is untested. Serialization bugs here cause silent protocol failures.
+- **Effort:** M
+- **Dependencies:** None
+
+### TODO-019 — Add chanora_core events module tests
+- **Priority:** P1
+- **Source:** codebase-analysis §3
+- **Description:** Events module is untested (80% coverage overall, but events gap). Event system is central to app behavior.
+- **Effort:** M
+- **Dependencies:** None
+
+### TODO-020 — Add iOS audio session lifecycle integration tests
+- **Priority:** P2
+- **Source:** issue-history §3
+- **Description:** Test session transitions (ambient → playAndRecord → ambient), already-in-channel response handling, idle audio mode. 15+ historical issues justify this.
+- **Effort:** L
+- **Dependencies:** TODO-030 (device test infrastructure)
+
+### TODO-021 — Add protocol error surfacing tests
+- **Priority:** P2
+- **Source:** issue-history §3
+- **Description:** Verify server errors are forwarded as UI events, not silently swallowed. Fire-and-forget hides failures.
+- **Effort:** M
+- **Dependencies:** None
+
+---
+
+## 4. Architecture
+
+### TODO-022 — Split engine.rs (3,244 lines) into smaller modules
+- **Priority:** P1
+- **Source:** codebase-analysis §6, §12
+- **Description:** Monolithic audio engine file. Split into engine core, capture, render, transmit, diagnostics modules.
+- **Effort:** L
+- **Dependencies:** None
+
+### TODO-023 — Split main.dart (2,910 lines) into smaller modules
+- **Priority:** P1
+- **Source:** codebase-analysis §6
+- **Description:** Monolithic Flutter entry point. Extract into feature-based modules/screens.
+- **Effort:** L
+- **Dependencies:** None
+
+### TODO-024 — Extract platform backends from chanora_audio into separate crates
+- **Priority:** P2
+- **Source:** codebase-analysis §12
+- **Description:** Split into `chanora_audio` (core ~8K lines), `chanora_audio_android` (~3.2K), `chanora_audio_apple` (~1.4K), `chanora_audio_desktop` (~3.5K). Platform backends are already cfg-gated.
+- **Effort:** XL
+- **Dependencies:** TODO-022 (split engine.rs first)
+
+### TODO-025 — Reduce `.map_err(format!)` boilerplate across 5 Rust crates
+- **Priority:** P2
+- **Source:** codebase-analysis §7
+- **Description:** ~85 repeated closure patterns. Introduce a `WrapErr` trait or macro to reduce boilerplate.
+- **Effort:** L
+- **Dependencies:** None
+
+### TODO-026 — Reduce adapter.rs (2,504 lines) and api.rs (2,432 lines)
+- **Priority:** P3
+- **Source:** codebase-analysis §6
+- **Description:** Both files exceed 2,400 lines. Consider splitting by feature area.
+- **Effort:** L
+- **Dependencies:** TODO-022, TODO-023
+
+---
+
+## 5. Documentation
+
+### TODO-027 — Update implementation-status document
+- **Priority:** P0
+- **Source:** codebase-analysis §13
+- **Description:** `docs/implementation-status-2026-05-28.md` is 14 days stale, missing v0.3.0 features. This is the primary evidence source for verification.
+- **Effort:** M
+- **Dependencies:** None
+
+### TODO-028 — Allocate SysRS-258–310 in SysDes
+- **Priority:** P0
+- **Source:** codebase-analysis §13
+- **Description:** 53 SysRS requirements lack SysDes allocation, breaking the traceability chain from requirements to design.
+- **Effort:** L
+- **Dependencies:** None
+
+### TODO-029 — Fix traceability matrix SRS numbering mismatches
+- **Priority:** P0
+- **Source:** codebase-analysis §13
+- **Description:** SRS IDs in traceability matrix don't match actual SRS document. Needs manual reconciliation.
+- **Effort:** M
+- **Dependencies:** None
+
+### TODO-030 — Add README files to 8 crates + core
+- **Priority:** P1
+- **Source:** codebase-analysis §4
+- **Description:** Only `chanora_resolver` has a README. The other 9 directories need one describing purpose, architecture, and public API.
+- **Effort:** M
+- **Dependencies:** None
+
+### TODO-031 — Improve chanora_audio doc comments (24% → 80%)
+- **Priority:** P2
+- **Source:** codebase-analysis §4
+- **Description:** Largest crate (168 pub fn, 18,895 lines) at only 24% documentation. Target 80% coverage.
+- **Effort:** XL
+- **Dependencies:** None
+
+### TODO-032 — Fix 6 broken doc links (create LICENSE files)
+- **Priority:** P3
+- **Source:** codebase-analysis §8
+- **Description:** All 6 broken links point to missing `LICENSE-APACHE` and `LICENSE-MIT` files at project root. LICENSE files have been created — verify links resolve.
+- **Effort:** S
+- **Dependencies:** None
+
+### TODO-033 — Link 14 orphaned documentation files
+- **Priority:** P3
+- **Source:** codebase-analysis §8
+- **Description:** 14 files in `docs/superpowers/plans/` and `docs/superpowers/specs/` are not linked from any index document.
+- **Effort:** S
+- **Dependencies:** None
+
+### TODO-034 — Update SDD (docs/architecture/sdd.md)
+- **Priority:** P2
+- **Source:** codebase-analysis §13
+- **Description:** Software Design Description scored 5/10 freshness. Missing many modules added since initial write.
+- **Effort:** L
+- **Dependencies:** None
+
+### TODO-035 — Update SAD (docs/architecture/sad.md)
+- **Priority:** P2
+- **Source:** codebase-analysis §13
+- **Description:** Software Architecture Description scored 5/10 freshness. Missing components and interfaces.
+- **Effort:** L
+- **Dependencies:** None
+
+### TODO-036 — Update Verification Master Plan
+- **Priority:** P1
+- **Source:** codebase-analysis §13
+- **Description:** Verification Master Plan scored 6/10, stale evidence sources and missing verification methods.
+- **Effort:** M
+- **Dependencies:** None
+
+---
+
+## 6. Missing APIs / Requirements
+
+### TODO-037 — Add missing bridge read-back functions
+- **Priority:** P1
+- **Source:** codebase-analysis §11
+- **Description:** `is_hard_muted()`, `get_output_gain()`, `get_client_volume()`, `connection_state()`, `reconnect()` are missing from bridge. UI must derive state from events only.
+- **Effort:** M
+- **Dependencies:** None
+
+### TODO-038 — Write requirements for implemented features
+- **Priority:** P1
+- **Source:** codebase-analysis §13
+- **Description:** Poke, file transfer, hard-mute, and cache features exist in code but have no SysRS/SRS requirements. Breaks traceability.
+- **Effort:** L
+- **Dependencies:** None
+
+### TODO-039 — Implement UI settings persistence (SysRS-143, SRS-087)
+- **Priority:** P2
+- **Source:** codebase-analysis §11
+- **Description:** Settings persistence is a documented requirement with no implementation.
+- **Effort:** M
+- **Dependencies:** None
+
+### TODO-040 — Implement per-user mute/volume persistence (SysRS-145/144, SRS-088)
+- **Priority:** P2
+- **Source:** codebase-analysis §11
+- **Description:** Per-user mute and volume persistence requirements are partially implemented. Needs completion.
+- **Effort:** M
+- **Dependencies:** None
+
+### TODO-041 — Implement notification permission handling (SysRS-166, SRS-109)
+- **Priority:** P2
+- **Source:** codebase-analysis §11
+- **Description:** Notification permission requirement has no implementation.
+- **Effort:** M
+- **Dependencies:** None
+
+### TODO-042 — Complete recent server management (SysRS-141, SRS-085)
+- **Priority:** P2
+- **Source:** codebase-analysis §11
+- **Description:** Recent server management is partially implemented. Needs completion per spec.
+- **Effort:** M
+- **Dependencies:** None
+
+### TODO-043 — Implement event replay tool (SysRS-171, SRS-098)
+- **Priority:** P2
+- **Source:** codebase-analysis §11
+- **Description:** Event replay tool is a documented requirement with no implementation.
+- **Effort:** L
+- **Dependencies:** None
+
+### TODO-044 — Implement audio processing test tool (SysRS-074, SRS-083)
+- **Priority:** P2
+- **Source:** codebase-analysis §11
+- **Description:** Audio processing test tool is a documented requirement with no implementation.
+- **Effort:** L
+- **Dependencies:** None
+
+### TODO-045 — Complete input validation (SysRS-157, SRS-094)
+- **Priority:** P2
+- **Source:** codebase-analysis §11
+- **Description:** Input validation is partially implemented. Needs completion per spec.
+- **Effort:** M
+- **Dependencies:** None
+
+### TODO-046 — Implement audio loopback test tool (SysRS-073, SRS-083)
+- **Priority:** P3
+- **Source:** codebase-analysis §11
+- **Description:** Audio loopback test tool is a documented requirement with no implementation.
+- **Effort:** L
+- **Dependencies:** TODO-054 (audio loopback harness)
+
+### TODO-047 — Implement protocol probe tool (SysRS-128, SRS-123)
+- **Priority:** P3
+- **Source:** codebase-analysis §11
+- **Description:** Protocol probe tool is a documented requirement with no implementation.
+- **Effort:** L
+- **Dependencies:** None
+
+---
+
+## 7. Infrastructure
+
+### TODO-048 — Add Android CI build job
+- **Priority:** P1
+- **Source:** test-environment-requirements §9 Phase 1
+- **Description:** No Android CI build exists. Add NDK + cargo-ndk + multi-ABI build to GitHub Actions.
+- **Effort:** M
+- **Dependencies:** None
+
+### TODO-049 — Add Windows and macOS CI build jobs
+- **Priority:** P1
+- **Source:** test-environment-requirements §9 Phase 1
+- **Description:** Windows and macOS builds are not in CI. Add windows-latest and macOS runners for build verification.
+- **Effort:** M
+- **Dependencies:** None
+
+### TODO-050 — Add xcodebuild Archive verification to CI
+- **Priority:** P1
+- **Source:** issue-history §1
+- **Description:** 4+ historical issues caused by `flutter build` passing but `xcodebuild archive` failing. Add xcodebuild archive step to CI.
+- **Effort:** M
+- **Dependencies:** None
+
+### TODO-051 — Enable clippy as blocking CI check
+- **Priority:** P2
+- **Source:** test-environment-requirements §9 Phase 1
+- **Description:** Clippy is currently advisory only. Make it a blocking PR gate.
+- **Effort:** S
+- **Dependencies:** None
+
+### TODO-052 — Add Linux multi-distro build matrix
+- **Priority:** P2
+- **Source:** test-environment-requirements §9 Phase 1
+- **Description:** Add Docker-based CI matrix for Ubuntu, Fedora, Arch to catch distro-specific PipeWire/Portal/DBus issues.
+- **Effort:** M
+- **Dependencies:** None
+
+### TODO-053 — Add `cargo llvm-cov` coverage reporting
+- **Priority:** P2
+- **Source:** test-environment-requirements §9 Phase 1
+- **Description:** No code coverage reporting exists. Add `cargo llvm-cov` to CI for trend tracking.
+- **Effort:** M
+- **Dependencies:** None
+
+### TODO-054 — Implement audio loopback test harness
+- **Priority:** P2
+- **Source:** test-environment-requirements §9 Phase 2
+- **Description:** Build virtual audio device loopback for CI audio quality testing. Use BlackHole (macOS), VB-Audio (Windows), snd-aloop (Linux).
+- **Effort:** L
+- **Dependencies:** TODO-048, TODO-049
+
+### TODO-055 — Implement test environment Phase 2 (device integration)
+- **Priority:** P2
+- **Source:** test-environment-requirements §9 Phase 2
+- **Description:** Set up self-hosted runners for device tests, Flutter integration tests with platform channels, Firebase Test Lab for Android, network condition test suite.
+- **Effort:** XL
+- **Dependencies:** TODO-048, TODO-049
+
+### TODO-056 — Implement test environment Phase 3 (full automation)
+- **Priority:** P3
+- **Source:** test-environment-requirements §9 Phase 3
+- **Description:** Benchmark regression gates, iOS TestFlight automation, signed build automation, weekly audio quality regression, Android multi-device testing.
+- **Effort:** XL
+- **Dependencies:** TODO-055
+
+---
+
+## 8. External Research Follow-up
+
+### TODO-057 — Upstream p256 coordinate padding fix to ReSpeak
+- **Priority:** P1
+- **Source:** external-research §2 (ReSpeak)
+- **Description:** Chanora forks `tsclientlib` for a p256 fix. Submit PR upstream to reduce fork maintenance burden.
+- **Effort:** M
+- **Dependencies:** None
+
+### TODO-058 — Monitor tsdeclarations for TS5 protocol updates
+- **Priority:** P2
+- **Source:** external-research §2 (ReSpeak)
+- **Description:** No full TS5 client protocol exists yet. Watch `tsdeclarations` repo for updates that may affect Chanora compatibility.
+- **Effort:** S
+- **Dependencies:** None (ongoing)
+
+### TODO-059 — Build auto-reconnect logic internally
+- **Priority:** P2
+- **Source:** external-research §2 (ReSpeak)
+- **Description:** tsclientlib explicitly notes auto-reconnect is "not yet there." Chanora must build this independently.
+- **Effort:** L
+- **Dependencies:** None
+
+### TODO-060 — Extract server error codes from YaTQA for error handling
+- **Priority:** P3
+- **Source:** external-research §3 (YaTQA)
+- **Description:** YaTQA's `/ressourcen/` section has comprehensive unofficial server error codes. Extract for Chanora error handling reference.
+- **Effort:** S
+- **Dependencies:** None
+
+### TODO-061 — Extract anti-flood/rate-limiting reference from YaTQA
+- **Priority:** P3
+- **Source:** external-research §3 (YaTQA)
+- **Description:** YaTQA documents anti-flood mechanics and rate limiting. Use as reference when implementing Chanora's rate limiting.
+- **Effort:** S
+- **Dependencies:** None
+
+---
+
+## 9. Protocol Implementation (from Reference Documents)
+
+### TODO-062 — Implement DNS resolution chain (SRV→TSDNS→DNS)
+- **Priority:** P1
+- **Source:** yatqa-offline-reference §8.5
+- **Description:** YaTQA documents the full DNS resolution order: SRV `_ts3._udp` → SRV TSDNS → TSDNS TCP port 41144 → DNS AAAA/A. First successful resolution wins, NO fallback on connection failure. Critical for connection reliability.
+- **Effort:** M
+- **Dependencies:** None
+
+### TODO-063 — Handle TS character encoding quirks (UTF-8 vs UCS-2 vs CESU-8)
+- **Priority:** P1
+- **Source:** yatqa-offline-reference §1.3
+- **Description:** TS claims UTF-8 but uses UCS-2 (BMP only). Mobile apps use CESU-8. Chanora must handle encoding conversion to avoid display bugs with nicknames, channel names, and messages containing characters outside BMP.
+- **Effort:** M
+- **Dependencies:** None
+
+### TODO-064 — Implement client-side anti-flood point awareness
+- **Priority:** P2
+- **Source:** yatqa-offline-reference §5
+- **Description:** YaTQA documents complete point costs per action (channelsubscribe=158pts, connect=80pts, etc.). Design Chanora's client-side anti-flood awareness to avoid accidental server bans. Tick-based point reduction model.
+- **Effort:** M
+- **Dependencies:** None
+
+### TODO-065 — Implement badge fetching and display
+- **Priority:** P2
+- **Source:** yatqa-offline-reference §8.9, respeak-protocol-reference §5
+- **Description:** Badges fetched from `badges-content.teamspeak.com` in Protobuf format, cached locally, refreshed every 24h. Chanora needs badge Protobuf parsing, caching, and UI display.
+- **Effort:** L
+- **Dependencies:** None
+
+### TODO-066 — Implement TSDNS protocol support
+- **Priority:** P2
+- **Source:** yatqa-offline-reference §8.4
+- **Description:** TSDNS protocol: TCP port 41144, lowercase domain + magic bytes. Required for `ts3server://` URL resolution and server bookmark handling.
+- **Effort:** M
+- **Dependencies:** TODO-062
+
+### TODO-067 — Implement TS3 file transfer protocol
+- **Priority:** P2
+- **Source:** yatqa-offline-reference §8.3, external-research §2 (ReSpeak gap)
+- **Description:** Raw file transfer: send key from `ftinitupload`/`ftinitdownload` to server IP:port, then raw data. No escaping. ReSpeak has no file transfer implementation — Chanora must build this independently.
+- **Effort:** L
+- **Dependencies:** None
+
+### TODO-068 — Evaluate tsdeclarations machine-readable files for code generation
+- **Priority:** P2
+- **Source:** respeak-protocol-reference §9
+- **Description:** Messages.toml, Book.toml, Enums.toml, MessagesToBook.toml, BookToMessages.toml could automate protocol struct and event generation. Evaluate feasibility for Chanora's build pipeline.
+- **Effort:** M
+- **Dependencies:** None
+
+### TODO-069 — Extract Permission IDs into Chanora's permission system
+- **Priority:** P2
+- **Source:** respeak-protocol-reference §3, yatqa-offline-reference §1.2
+- **Description:** Both ReSpeak (tsdeclarations) and YaTQA provide comprehensive permission ID lists with Skip/Negate/Grant logic. Map these to Chanora's permission implementation for full TS3 compatibility.
+- **Effort:** L
+- **Dependencies:** None
+
+### TODO-070 — Document protocol implementation traps
+- **Priority:** P2
+- **Source:** yatqa-offline-reference §1.4, §1.5, §3.1
+- **Description:** Several implementation traps documented in YaTQA: icon IDs signed/unsigned mismatch, avatar flag is MD5 hash not boolean, channel subscription limited to ONE at a time, line terminator is `0x0A 0x0D` (reversed Windows). Compile into Chanora developer notes.
+- **Effort:** S
+- **Dependencies:** None
+
+### TODO-071 — Handle IPv6 blacklist canonicalization bug
+- **Priority:** P3
+- **Source:** yatqa-offline-reference §8.7
+- **Description:** TS3 server 3.1.6-3.1.7 has IPv6 canonicalization bug in Blacklist2 protocol. Chanora should be aware when connecting to older servers.
+- **Effort:** S
+- **Dependencies:** None
+
+### TODO-072 — Establish connection/message performance benchmarks
+- **Priority:** P3
+- **Source:** respeak-protocol-reference §10
+- **Description:** tsclientlib benchmarks: ~199ms connect, ~189µs/message. Use as baseline for Chanora's performance testing.
+- **Effort:** S
+- **Dependencies:** None
+
+### TODO-073 — Assess web client feasibility
+- **Priority:** P3
+- **Source:** teaspeak-offline-reference §10, external-research §1
+- **Description:** TeaSpeak's web client was a compelling installation-less option. Evaluate whether a future Chanora web client makes sense. Not current scope.
+- **Effort:** S
+- **Dependencies:** None
+
+---
+
+## 10. Reference Document Improvements
+
+### TODO-074 — Fix respeak reference: malformed badge table row
+- **Priority:** P2
+- **Source:** respeak-protocol-reference review (line 1309)
+- **Description:** MIFCOM badge row has 6 columns (5 pipes) but table header has 5 columns. "Entered Performance" is a misplaced column. Fix table formatting.
+- **Effort:** S
+- **Dependencies:** None
+
+### TODO-075 — Fix respeak reference: section numbering placeholder
+- **Priority:** P2
+- **Source:** respeak-protocol-reference review (line 764)
+- **Description:** Section "4.? Differences between Query and Full Client" has a `?` placeholder. Assign correct section number (4.9 or similar).
+- **Effort:** S
+- **Dependencies:** None
+
+### TODO-076 — Fix respeak reference: duplicate section numbering
+- **Priority:** P2
+- **Source:** respeak-protocol-reference review
+- **Description:** Both the protocol spec section and reference data sections start at `# 2.`, making "Section 2" ambiguous. Separate into Part I (Protocol) and Part II (Reference Data) or renumber.
+- **Effort:** S
+- **Dependencies:** None
+
+### TODO-077 — Resolve teaspeak reference: godmode permission contradiction
+- **Priority:** P2
+- **Source:** teaspeak-offline-reference review (lines 401 vs 414)
+- **Description:** `b_virtualserver_select_godmode` listed as active permission in "Other Permissions" table (line 401) AND as "removed" in "Removed Permissions" table (line 414). Resolve: remove from one location or clarify version-based behavior.
+- **Effort:** S
+- **Dependencies:** None
+
+### TODO-078 — Resolve teaspeak reference: music bot command contradiction
+- **Priority:** P2
+- **Source:** teaspeak-offline-reference review (lines 499 vs 1229)
+- **Description:** Music bot queue commands (`musicbotqueuelist`, `musicbotqueueadd`, etc.) listed in active Music Bot Query Commands table (lines 499-501) AND in "Removed Commands" section (lines 1229-1236). Clarify which version removed them.
+- **Effort:** S
+- **Dependencies:** None
+
+### TODO-079 — Add Chanora relevance section to teaspeak reference
+- **Priority:** P2
+- **Source:** teaspeak-offline-reference review
+- **Description:** TeaSpeak reference has no section connecting features to Chanora's needs. Add "Relevance to Chanora" section mapping TeaSpeak features to Chanora SRS requirements and identifying protocol divergence points.
+- **Effort:** M
+- **Dependencies:** None
+
+### TODO-080 — Backfill YaTQA reference: complete variable parameters tables
+- **Priority:** P2
+- **Source:** yatqa-offline-reference review
+- **Description:** Variable parameters section severely condensed: ~15 of 50+ client vars, ~15 of 35+ channel vars, ~7 of 70+ server vars. Backfill from `yat.qa/ressourcen/variablen-parameter/`.
+- **Effort:** L
+- **Dependencies:** None
+
+### TODO-081 — Backfill YaTQA reference: complete anti-flood action table
+- **Priority:** P2
+- **Source:** yatqa-offline-reference review
+- **Description:** Anti-flood section reduced ~80 individual actions to summary tiers. Replace with complete itemized table from `yat.qa/ressourcen/voice-client-anti-flood/`.
+- **Effort:** M
+- **Dependencies:** None
+
+### TODO-082 — Backfill YaTQA reference: missing error codes and truncated messages
+- **Priority:** P2
+- **Source:** yatqa-offline-reference review
+- **Description:** ~28 error codes missing, several messages truncated (errors 1030, 1035, 522). Add missing codes and fix truncated messages.
+- **Effort:** S
+- **Dependencies:** None
+
+### TODO-083 — Backfill YaTQA reference: expand ServerQuery notify events
+- **Priority:** P2
+- **Source:** yatqa-offline-reference review
+- **Description:** Missing events: `notifychanneldescriptionchanged`, `notifychannelpasswordchanged`. Most events listed by name only with no field details. Expand with full field lists and behavioral notes.
+- **Effort:** M
+- **Dependencies:** None
+
+### TODO-084 — Cross-reference YaTQA and ReSpeak error codes
+- **Priority:** P3
+- **Source:** yatqa-offline-reference review, respeak-protocol-reference review
+- **Description:** YaTQA §9 and ReSpeak Errors.csv may have discrepancies. Cross-reference and note differences.
+- **Effort:** S
+- **Dependencies:** None
+
+---
+
+## 11. Additional Traceability Gaps
+
+### TODO-085 — Add Flutter app documentation
+- **Priority:** P2
+- **Source:** codebase-analysis §4
+- **Description:** Flutter app has <1% documentation coverage (~586 functions, ~5 documented). Add dart doc comments to core services and widgets.
+- **Effort:** XL
+- **Dependencies:** None
+
+### TODO-086 — Add chanora_bridge doc comments (15% coverage)
+- **Priority:** P2
+- **Source:** codebase-analysis §4
+- **Description:** chanora_bridge has 65 pub fn at 15% documentation. This is the FFI boundary — every function should be documented.
+- **Effort:** L
+- **Dependencies:** None
+
+### TODO-087 — Track Flutter framework upstream bugs and workarounds
+- **Priority:** P2
+- **Source:** codebase-analysis §9, issue-history §1
+- **Description:** 3+ historical issues required Flutter framework workarounds. Create tracking document for upstream Flutter bugs that affect Chanora and document current workarounds.
+- **Effort:** S
+- **Dependencies:** None
+
+### TODO-088 — Improve branch management workflow
+- **Priority:** P3
+- **Source:** codebase-analysis §10, issue-history §2
+- **Description:** PR stacking complexity and local CI mirroring noted as development pain points. Evaluate git-worktree or branch management tooling.
+- **Effort:** M
+- **Dependencies:** None
+
+---
+
+*Generated from codebase analysis on 2026-06-11. 88 items across 11 categories.*