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, full code-review remediation, current documentation, explicit fail-safe evidence, and Android runtime verification status.

Current status: Task 0 and the audio-realtime portion of Task 0.1 have landed in commits d835394 and 8606eb4. Task 0.2 is a documentation/status alignment slice only; it must not claim Android or iOS runtime success.

Architecture: Treat the existing uncommitted maintainability changes as the baseline slice. Fix safety and hidden-bug findings before broad Module splits. Preserve public Rust Core, Bridge, Protocol, Audio, and Flutter responsibilities while applying only tested simplifications and risk-reducing refactors. Record larger seam decisions as follow-up findings unless a huge Module must be split to make a safety fix testable.

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.

Review Findings To Remediate First

The full review added these priority fixes before the original maintainability cleanup sequence:

• Flutter privacy fail-safe: talk-power recovery must not clear a user/manual mute. Fixed in commit d835394.
• Flutter stuck-transmit fail-safe: touch PTT must release when disposed while held. Fixed in commit d835394.
• Flutter/iOS fail-safe: iOS audio-session activation errors must be caught, and activation should be moved before Rust VoiceProcessingIO startup where the current app flow allows. Missing-plugin/error hardening fixed in commit d835394; iOS device runtime verification remains required.
• Rust realtime safety: Android and iOS raw render-reference buffers must not use unsynchronized mutable aliasing. Callback-path hardening fixed in commit 8606eb4; the full lock-free AudioHandler / config / debug-recorder redesign remains a follow-up.
• Rust realtime safety: Android input callback must not block on a mutex, and non-48 kHz capture should not allocate/clone per callback. Focused callback-path hardening fixed in commit 8606eb4; Android target compilation and runtime verification remain blocked locally until the missing NDK compiler and an authorized ADB target are available.
• Rust control-plane safety: disconnect and protocol control requests must remain bounded under broken transport or sustained voice traffic.
• Governance correctness: README/release/VAD/Android API/product-decision docs must not contradict code or verification status.

Task 0: Fix Flutter Privacy and Stuck-Transmit Fail-Safes

Files:

• Modify: apps/chanora_flutter/lib/main.dart

• Modify: apps/chanora_flutter/lib/widgets/voice_compact.dart

• Modify: apps/chanora_flutter/lib/services/ios_audio_session_controller.dart

• Test: apps/chanora_flutter/test/widgets/voice_compact_test.dart

• Test: existing Flutter tests under apps/chanora_flutter/test/

• Step 1: Add failing touch PTT disposal regression test

Create or update apps/chanora_flutter/test/widgets/voice_compact_test.dart with a widget test that presses the touch PTT button, replaces the widget without sending pointer-up, and expects the callback sequence [true, false].

• Step 2: Run touch PTT test and verify RED

Run from apps/chanora_flutter: flutter test test/widgets/voice_compact_test.dart

Expected before production fix: FAIL because disposal does not emit false.

• Step 3: Implement touch PTT release-on-dispose

Add dispose() to the touch PTT button state so an active press calls widget.onHeldChanged(false) exactly once before disposal.

• Step 4: Run touch PTT test and verify GREEN

Run from apps/chanora_flutter: flutter test test/widgets/voice_compact_test.dart

Expected after fix: PASS.

• Step 5: Add or preserve mute-owner regression coverage

If an existing pure reducer seam is available, add a failing test for manual mute true -> talk power blocked -> talk power restored. If no testable seam exists, first extract the smallest voice mute owner helper from main.dart and test it directly.

• Step 6: Implement independent mute owners

Ensure talk-power recovery clears only the talk-power owner and does not clear manual/user mute or permission mute. Effective hard mute is the OR of manual, permission, and talk-power owners.

• Step 7: Harden iOS audio-session controller errors

Add tests for MissingPluginException in ios_audio_session_controller_test.dart, then catch MissingPluginException or Object so activation/deactivation failures do not become unhandled async errors.

• Step 8: Run focused Flutter verification

Run from apps/chanora_flutter: flutter test test/widgets/voice_compact_test.dart test/services/ios_audio_session_controller_test.dart && flutter analyze

Expected: PASS.

• Step 9: Commit Flutter fail-safe slice

Run:

git add apps/chanora_flutter/lib/main.dart apps/chanora_flutter/lib/widgets/voice_compact.dart apps/chanora_flutter/lib/services/ios_audio_session_controller.dart apps/chanora_flutter/test/widgets/voice_compact_test.dart apps/chanora_flutter/test/services/ios_audio_session_controller_test.dart
git commit -m "fix(voice): preserve mute owners and release touch ptt"

Expected: one commit containing only Flutter fail-safe fixes and tests.

Task 0.1: Fix Rust Realtime and Control-Plane Safety Findings

Files:

• Modify: crates/chanora_audio/src/android_voice_unit.rs

• Modify: crates/chanora_audio/src/ios_raw_unit.rs

• Modify: crates/chanora_audio/src/engine.rs

• Modify: crates/chanora_protocol/src/adapter.rs

• Modify: core/chanora_core/src/lib.rs

• Test: Rust tests in affected crates

• Step 1: Add failing bounded-buffer regression for render-reference handoff

Add host-testable unit coverage around the render-reference buffer behavior so a writer can publish a frame and a reader can read a complete latest frame without unsynchronized mutation.

• Step 2: Replace unsafe shared mutable render-reference buffers

Replace unsynchronized mutable aliasing in Android and iOS raw render-reference buffers with a realtime-safe handoff such as an ArrayQueue of complete frames or a documented atomic double-buffer. Do not add mutex locking to realtime callbacks.

• Step 3: Add failing protocol progress regression where feasible

Add or isolate a test proving control requests are not starved by sustained voice packet drain.

• Step 4: Bound voice draining and disconnect shutdown

Cap voice packet draining per protocol loop and make disconnect/shutdown bounded so UI/Core locks are not held across unbounded transport waits.

• Step 5: Run focused Rust verification

Run: cargo test -p chanora_audio -p chanora_protocol -p chanora_core

Expected: PASS.

• Step 6: Commit Rust safety slice

Run:

git add crates/chanora_audio/src/android_voice_unit.rs crates/chanora_audio/src/ios_raw_unit.rs crates/chanora_audio/src/engine.rs crates/chanora_protocol/src/adapter.rs core/chanora_core/src/lib.rs
git commit -m "fix(audio): harden realtime and protocol fail-safes"

Expected: one commit containing only Rust safety fixes and tests.

Task 0.2: Align Review Findings With Specs, Plans, and Governance Docs

Status: In progress / documentation-only alignment. Do not commit from this task unless explicitly requested.

Files:

• Modify: docs/superpowers/specs/2026-06-08-maintainability-continuation-design.md

• Modify: docs/superpowers/plans/2026-06-08-maintainability-continuation.md

• Modify: docs/governance/maintainability-review-2026-06-08.md

• Modify: README.md

• Modify if needed: CHANGELOG.md

• Modify if needed: docs/governance/product-decision-register.md

• Modify if needed: docs/release/release-readiness-go-nogo-record.md

• Modify if needed: docs/release/dv-waiver-register.md

• Modify if needed: docs/verification/verification-master-plan.md

• Modify if needed: docs/verification/sys4-system-integration-verification-plan.md

• Step 1: Record full-review findings in maintainability review

Update docs/governance/maintainability-review-2026-06-08.md with the full code-review findings, fixed items, blocked items, and follow-up Module split candidates.

• Step 2: Fix stale platform/release claims

Update Android minimum runtime claims to API 28 where code and requirements require it. Update release metadata so Flutter app version/build and Rust workspace version are clearly distinguished.

• Step 3: Clarify VAD/VoiceActivity status

Document the difference between VAD scaffolding/assets/tests and product-enabled VoiceActivity behavior. Do not claim runtime VoiceActivity is shipped unless verified.

• Step 4: Promote Android runtime verification blocker

Add Android ADB/build/install/smoke as a blocker or waiver in governing release/verification docs when no authorized target is connected.

• Step 5: Commit plan/spec/governance alignment slice

Skipped in this subagent run because the instruction for Task 0.2 explicitly says not to commit.

Run:

git add docs/superpowers/specs/2026-06-08-maintainability-continuation-design.md docs/superpowers/plans/2026-06-08-maintainability-continuation.md docs/governance/maintainability-review-2026-06-08.md README.md CHANGELOG.md docs/governance/product-decision-register.md docs/release/release-readiness-go-nogo-record.md docs/release/dv-waiver-register.md docs/verification/verification-master-plan.md docs/verification/sys4-system-integration-verification-plan.md
git commit -m "docs: align review findings and verification gates"

Expected: one documentation/governance commit, with unavailable optional files omitted only if unchanged.

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.