diff --git a/docs/superpowers/plans/2026-06-08-maintainability-continuation.md b/docs/superpowers/plans/2026-06-08-maintainability-continuation.md new file mode 100644 index 0000000..e79b679 --- /dev/null +++ b/docs/superpowers/plans/2026-06-08-maintainability-continuation.md @@ -0,0 +1,448 @@ +# Maintainability Continuation Implementation Plan + +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** Continue the current maintainability review with safe simplifications, current documentation, explicit fail-safe evidence, and Android runtime verification status. + +**Architecture:** Treat the existing uncommitted maintainability changes as the baseline slice. Preserve public Rust Core, Bridge, Protocol, Audio, and Flutter responsibilities while applying only small simplifications that are covered by focused tests and workspace verification. Record larger seam decisions as follow-up findings instead of forcing broad rewrites into this pass. + +**Tech Stack:** Rust 2021 Cargo workspace, Flutter/Dart 3.11, Flutter Rust Bridge 2.12, Android ADB, Markdown governance and verification documents. + +--- + +## File Structure + +Implementation should keep the following responsibilities stable: + +- `core/chanora_core/src/lib.rs`: public Core API, session orchestration, public re-exports, and integration-facing methods. +- `core/chanora_core/src/events.rs`: Core public event DTOs re-exported by `lib.rs`. +- `core/chanora_core/src/network_diagnostics.rs`: private bounded network diagnostic history and its local regression tests. +- `crates/chanora_audio/src/voice_render.rs`: shared render/downmix helpers. +- `crates/chanora_audio/src/ios_raw_unit.rs`, `ios_voice_unit.rs`, `android_voice_unit.rs`, `engine.rs`: platform/audio backends; avoid broad rewrites without device evidence. +- `crates/chanora_audio/src/ptt_backends/mod.rs`: PTT backend descriptor and error definitions. +- `crates/chanora_state/src/lib.rs`: snapshot reducers and state deltas. +- `crates/chanora_protocol/src/adapter.rs`: protocol adapter event ordering and DTO projection. +- `crates/chanora_bridge/src/api.rs`: bridge-facing API and DTO mapping; generated files are not manually edited. +- `crates/chanora_diagnostics/src/lib.rs`: bounded diagnostics, redaction, and export data. +- `docs/governance/maintainability-review-2026-06-08.md`: working review record and fail-safe gap log. +- `docs/governance/document-index.md`: navigation index for review records. +- `docs/architecture/sad.md`, `docs/architecture/sdd.md`: architecture updates for seams and implementation boundaries. +- `docs/implementation-status-2026-05-28.md`: implementation status updates. +- `docs/verification/swe4-unit-verification-plan.md`, `docs/verification/swe5-software-integration-verification-plan.md`: verification evidence and requirements updates. + +## Task 1: Verify Current Branch Baseline + +**Files:** +- Read: `docs/governance/maintainability-review-2026-06-08.md` +- Read: `docs/superpowers/plans/2026-06-08-core-internal-split.md` +- Inspect: all currently modified files from `git status --short` +- Modify: none unless verification exposes a small mechanical fix + +- [ ] **Step 1: Inspect current status** + +Run: `git status --short` + +Expected: output includes the existing maintainability branch changes and no staged files from unrelated work. + +- [ ] **Step 2: Inspect current diff summary** + +Run: `git diff --stat` + +Expected: diff remains focused on Core split, Audio simplifications, State/Protocol/Bridge/Diagnostics cleanup, and documentation updates. + +- [ ] **Step 3: Verify Rust formatting** + +Run: `cargo fmt --all --check` + +Expected: PASS with no output. If it fails, run `cargo fmt --all`, inspect the resulting diff, and include formatter-only changes in the smallest relevant commit. + +- [ ] **Step 4: Verify Rust compilation** + +Run: `cargo check --workspace` + +Expected: PASS for the full workspace. + +- [ ] **Step 5: Verify Rust tests** + +Run: `cargo test --workspace` + +Expected: PASS for the full workspace. + +- [ ] **Step 6: Verify Flutter analysis** + +Run from `apps/chanora_flutter`: `flutter analyze` + +Expected: PASS with no new analyzer errors. + +- [ ] **Step 7: Verify Flutter tests** + +Run from `apps/chanora_flutter`: `flutter test --exclude-tags e2e` + +Expected: PASS for non-e2e Flutter tests. + +- [ ] **Step 8: Check Android device availability** + +Run: `adb devices -l` + +Expected if a target is connected: at least one `device` row. Expected if no target is connected: only the header and no `device` row; record Android runtime verification as blocked in `docs/governance/maintainability-review-2026-06-08.md`. + +- [ ] **Step 9: Commit verified existing slice** + +Only after Steps 1-8 have been completed or any blocked Android status has been documented, stage the smallest coherent existing slice. + +Recommended first slice if tests pass: + +```bash +git add core/chanora_core/src/lib.rs core/chanora_core/src/events.rs core/chanora_core/src/network_diagnostics.rs docs/superpowers/plans/2026-06-08-core-internal-split.md +git commit -m "refactor(core): split event and diagnostics internals" +``` + +Expected: one commit containing only the Core split and its plan. + +## Task 2: Commit Existing Built-In and Helper Reuse Simplifications + +**Files:** +- Modify or stage: `crates/chanora_audio/src/ptt_backends/mod.rs` +- Modify or stage: `crates/chanora_audio/src/voice_render.rs` +- Modify or stage: `crates/chanora_audio/src/ios_raw_unit.rs` +- Modify or stage: `crates/chanora_diagnostics/src/lib.rs` +- Modify or stage: `crates/chanora_state/src/lib.rs` +- Modify or stage: `crates/chanora_resolver/Cargo.toml` +- Modify or stage: `Cargo.lock` + +- [ ] **Step 1: Inspect simplification diffs** + +Run: + +```bash +git diff -- crates/chanora_audio/src/ptt_backends/mod.rs crates/chanora_audio/src/voice_render.rs crates/chanora_audio/src/ios_raw_unit.rs crates/chanora_diagnostics/src/lib.rs crates/chanora_state/src/lib.rs crates/chanora_resolver/Cargo.toml Cargo.lock +``` + +Expected: diffs show built-in/helper reuse only: `thiserror::Error`, `VecDeque`, render helper reuse, reducer reuse, and workspace metadata inheritance. + +- [ ] **Step 2: Run focused Rust tests for changed areas** + +Run: `cargo test -p chanora_audio -p chanora_diagnostics -p chanora_state -p chanora_resolver` + +Expected: PASS for all listed crates. + +- [ ] **Step 3: Run workspace Rust verification** + +Run: `cargo check --workspace && cargo test --workspace` + +Expected: PASS for workspace compile and tests. + +- [ ] **Step 4: Commit built-in/helper reuse slice** + +Run: + +```bash +git add crates/chanora_audio/src/ptt_backends/mod.rs crates/chanora_audio/src/voice_render.rs crates/chanora_audio/src/ios_raw_unit.rs crates/chanora_diagnostics/src/lib.rs crates/chanora_state/src/lib.rs crates/chanora_resolver/Cargo.toml Cargo.lock +git commit -m "refactor: reuse built-ins and shared helpers" +``` + +Expected: one commit containing only the built-in/helper reuse simplifications. + +## Task 3: Review Remaining Audio Platform Diffs Before Committing + +**Files:** +- Inspect: `crates/chanora_audio/src/android_voice_unit.rs` +- Inspect: `crates/chanora_audio/src/engine.rs` +- Inspect: `crates/chanora_audio/src/ios_voice_unit.rs` +- Modify: `docs/governance/maintainability-review-2026-06-08.md` if Android runtime verification is blocked or audio fail-safe evidence changes + +- [ ] **Step 1: Inspect platform-audio diffs** + +Run: + +```bash +git diff -- crates/chanora_audio/src/android_voice_unit.rs crates/chanora_audio/src/engine.rs crates/chanora_audio/src/ios_voice_unit.rs +``` + +Expected: diffs are understandable as local simplification or fail-safe improvements. If a diff changes platform runtime behavior and no Android/iOS device evidence is available, keep it separate from non-platform commits. + +- [ ] **Step 2: Run audio crate tests** + +Run: `cargo test -p chanora_audio` + +Expected: PASS. + +- [ ] **Step 3: Check Android runtime availability** + +Run: `adb devices -l` + +Expected if connected: at least one target row with `device`. Expected if blocked: no target row. + +- [ ] **Step 4: Run Android build when a target is available** + +Run from `apps/chanora_flutter`: `flutter build apk --debug` + +Expected: PASS and a debug APK is produced. + +- [ ] **Step 5: Run Android install and smoke when a target is available** + +Run from `apps/chanora_flutter`: `flutter install` + +Expected: PASS and app installs on the connected target. + +Manual smoke expectations: + +- App launches without crash. +- Permission UI can be reached. +- Audio device/permission screen does not crash. +- Voice controls remain responsive. + +- [ ] **Step 6: Record blocked Android evidence if no target is available** + +Modify `docs/governance/maintainability-review-2026-06-08.md` Section 6 so it includes the exact `adb devices -l` result and states Android runtime verification is blocked until a device or emulator is connected. + +- [ ] **Step 7: Commit platform-audio slice** + +If Android runtime was verified, run: + +```bash +git add crates/chanora_audio/src/android_voice_unit.rs crates/chanora_audio/src/engine.rs crates/chanora_audio/src/ios_voice_unit.rs docs/governance/maintainability-review-2026-06-08.md +git commit -m "refactor(audio): simplify platform voice internals" +``` + +If Android runtime was blocked, run: + +```bash +git add crates/chanora_audio/src/android_voice_unit.rs crates/chanora_audio/src/engine.rs crates/chanora_audio/src/ios_voice_unit.rs docs/governance/maintainability-review-2026-06-08.md +git commit -m "refactor(audio): simplify platform voice internals" +``` + +Expected: commit message is the same, but the maintainability review explicitly records the blocked Android runtime evidence. + +## Task 4: Review Protocol and Bridge Diffs as One Boundary Slice + +**Files:** +- Inspect: `crates/chanora_protocol/src/adapter.rs` +- Inspect: `crates/chanora_bridge/src/api.rs` +- Modify: `docs/architecture/sad.md` +- Modify: `docs/architecture/sdd.md` +- Modify: `docs/governance/maintainability-review-2026-06-08.md` + +- [ ] **Step 1: Inspect protocol/bridge diffs** + +Run: + +```bash +git diff -- crates/chanora_protocol/src/adapter.rs crates/chanora_bridge/src/api.rs +``` + +Expected: diffs preserve protocol isolation and bridge DTO shape unless bridge generation and Flutter tests are included. + +- [ ] **Step 2: Verify protocol tests** + +Run: `cargo test -p chanora_protocol` + +Expected: PASS. + +- [ ] **Step 3: Verify bridge tests and compile** + +Run: `cargo test -p chanora_bridge` + +Expected: PASS. + +- [ ] **Step 4: Verify Flutter after bridge/API changes** + +Run from `apps/chanora_flutter`: `flutter analyze && flutter test --exclude-tags e2e` + +Expected: PASS for analyzer and non-e2e tests. + +- [ ] **Step 5: Document seam findings** + +Update `docs/governance/maintainability-review-2026-06-08.md` so remaining bridge DTO drift and protocol voice packet seam risks are listed under fail-safe gaps or follow-up opportunities. + +- [ ] **Step 6: Update architecture docs if seam wording changed** + +If the code diff clarifies protocol/bridge boundaries, update `docs/architecture/sad.md` and `docs/architecture/sdd.md` with one concise note each. The note should state whether protocol voice packet handling is an intentional exception and whether bridge DTO mirrors remain required by Flutter Rust Bridge. + +- [ ] **Step 7: Commit protocol/bridge slice** + +Run: + +```bash +git add crates/chanora_protocol/src/adapter.rs crates/chanora_bridge/src/api.rs docs/architecture/sad.md docs/architecture/sdd.md docs/governance/maintainability-review-2026-06-08.md +git commit -m "refactor: clarify protocol bridge boundaries" +``` + +Expected: one commit for protocol/bridge boundary cleanup plus matching architecture documentation. + +## Task 5: Run a Second-Pass Simplification Search + +**Files:** +- Inspect: Rust and Dart source files only +- Modify: only if the simplification is mechanical, local, and covered by tests +- Modify: `docs/governance/maintainability-review-2026-06-08.md` + +- [ ] **Step 1: Search for custom queue front removal** + +Run: `rg "remove\(0\)|removeAt\(0\)" core crates apps/chanora_flutter/lib apps/chanora_flutter/test` + +Expected: no results. If results exist, replace with `VecDeque` in Rust or a clearer Dart queue structure only when behavior is covered by a local test. + +- [ ] **Step 2: Search for manual Rust error formatting** + +Run: `rg "impl (std::fmt::)?Display for .*Error|impl std::error::Error for" core crates` + +Expected: only intentional manual implementations remain. For simple enum error types, replace with `thiserror::Error` and add or preserve tests for user-facing strings. + +- [ ] **Step 3: Search for duplicate mono downmix loops** + +Run: `rg "chunks_exact\(2\)|downmix|mono" crates/chanora_audio/src` + +Expected: duplicate i16/f32 mono downmix code is either absent or justified. If a duplicate remains, route it through an existing helper and run `cargo test -p chanora_audio`. + +- [ ] **Step 4: Search for shallow modules worth documenting** + +Run: `rg "^pub struct|^pub enum|^pub fn|^fn" crates/chanora_audio/src/processor crates/chanora_prefetch/src crates/chanora_resolver/src core/chanora_core/src` + +Expected: identify candidates, but do not merge modules in this task. Record speculative merges in `docs/governance/maintainability-review-2026-06-08.md` unless a candidate is trivial and already covered by tests. + +- [ ] **Step 5: Commit second-pass mechanical simplifications if any** + +If code changed, run the relevant focused tests plus `cargo check --workspace && cargo test --workspace`, then inspect the changed files: + +```bash +git status --short +``` + +Stage only the files changed by the second-pass mechanical simplification. Example for a Rust-only diagnostics simplification: + +```bash +git add crates/chanora_diagnostics/src/lib.rs docs/governance/maintainability-review-2026-06-08.md +git commit -m "refactor: apply second-pass mechanical simplifications" +``` + +Expected: commit contains only local mechanical simplifications and the review record. + +- [ ] **Step 6: Commit review-only findings if no code changed** + +If no code changed and only findings were added, run: + +```bash +git add docs/governance/maintainability-review-2026-06-08.md +git commit -m "docs: record maintainability follow-up findings" +``` + +Expected: documentation-only commit. + +## Task 6: Final Documentation Alignment + +**Files:** +- Modify: `docs/governance/maintainability-review-2026-06-08.md` +- Modify: `docs/governance/document-index.md` +- Modify: `docs/implementation-status-2026-05-28.md` +- Modify: `docs/verification/swe4-unit-verification-plan.md` +- Modify: `docs/verification/swe5-software-integration-verification-plan.md` +- Modify if needed: `docs/architecture/sad.md` +- Modify if needed: `docs/architecture/sdd.md` + +- [ ] **Step 1: Update maintainability review completion status** + +Edit `docs/governance/maintainability-review-2026-06-08.md` so these sections are current: + +- Changes applied +- Remaining simplification opportunities +- Fail-safe gaps that need evidence +- Verification policy +- Android ADB status +- Git policy + +- [ ] **Step 2: Update document index** + +Ensure `docs/governance/document-index.md` includes `docs/governance/maintainability-review-2026-06-08.md` and this plan/spec if the repository convention indexes superpowers documents. + +- [ ] **Step 3: Update implementation status** + +Ensure `docs/implementation-status-2026-05-28.md` describes maintainability review results without claiming production readiness. + +- [ ] **Step 4: Update SWE.4 verification plan** + +Ensure `docs/verification/swe4-unit-verification-plan.md` lists Rust unit verification expectations for Core, Audio, State, Protocol, Bridge, Diagnostics, Resolver, and Prefetch when those crates are touched. + +- [ ] **Step 5: Update SWE.5 verification plan** + +Ensure `docs/verification/swe5-software-integration-verification-plan.md` lists integration expectations for Bridge DTO drift, protocol event folding, Flutter analyze/test, and Android runtime smoke evidence. + +- [ ] **Step 6: Run documentation cross-link search** + +Run: `rg "maintainability-review-2026-06-08|core-internal-split|maintainability-continuation" docs README.md` + +Expected: references point to existing files and no stale path is introduced. + +- [ ] **Step 7: Commit final documentation alignment** + +Run: + +```bash +git add docs/governance/maintainability-review-2026-06-08.md docs/governance/document-index.md docs/implementation-status-2026-05-28.md docs/verification/swe4-unit-verification-plan.md docs/verification/swe5-software-integration-verification-plan.md docs/architecture/sad.md docs/architecture/sdd.md +git commit -m "docs: align maintainability verification records" +``` + +Expected: one documentation-focused commit. + +## Task 7: Final Verification and Android Evidence + +**Files:** +- Modify: `docs/governance/maintainability-review-2026-06-08.md` only if final verification status changes + +- [ ] **Step 1: Run full Rust verification** + +Run: `cargo fmt --all --check && cargo check --workspace && cargo test --workspace` + +Expected: PASS. + +- [ ] **Step 2: Run full Flutter verification** + +Run from `apps/chanora_flutter`: `flutter analyze && flutter test --exclude-tags e2e` + +Expected: PASS. + +- [ ] **Step 3: Run ADB check** + +Run: `adb devices -l` + +Expected if connected: at least one target row with `device`. Expected if blocked: no target row and the maintainability review states Android runtime verification is blocked. + +- [ ] **Step 4: Run Android build/install/smoke when connected** + +Run from `apps/chanora_flutter`: `flutter build apk --debug && flutter install` + +Expected: PASS. Manually verify app launch, permission screen access, audio settings access, and voice control responsiveness. + +- [ ] **Step 5: Commit final verification evidence if docs changed** + +If the maintainability review was updated with final verification evidence, run: + +```bash +git add docs/governance/maintainability-review-2026-06-08.md +git commit -m "docs: record maintainability verification evidence" +``` + +Expected: one small evidence-only documentation commit. + +- [ ] **Step 6: Inspect final history and status** + +Run: `git status --short && git log --oneline -10` + +Expected: no unexpected unstaged changes related to this work; recent commits are small and logically separated. + +--- + +## Self-Review + +Spec coverage: + +- Safe simplifications are covered by Tasks 1, 2, 3, 4, and 5. +- Built-in replacement opportunities are covered by Tasks 2 and 5. +- Fail-safe gaps are covered by Tasks 3, 4, 6, and 7. +- Rust, Flutter, and Android verification are covered by Tasks 1 and 7, with focused verification in Tasks 2 through 4. +- Documentation updates are covered by Tasks 4, 6, and 7. +- Small commit policy is covered by every task's dedicated commit step. + +Placeholder scan: The plan contains no open placeholders. Task 5 uses `git status --short` before staging because the exact second-pass files are only known after the search runs; the example command shows the required staging style. + +Type consistency: The plan does not introduce new APIs or types. It preserves current crate and file boundaries from the approved design.