chanora/docs/superpowers/plans/2026-06-08-maintainability-continuation.md

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:

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:

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:

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:

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:

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:

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:

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:

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:

git status --short

Stage only the files changed by the second-pass mechanical simplification. Example for a Rust-only diagnostics simplification:

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:

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:

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:

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.