Flow Code Quality Audit

Last reviewed: 2026-04-25

This backlog tracks code-quality work for flow/wap-flow after the task-first, local-authority, adapter-command, and context-graph hardening pass. The canonical validation gate now includes clippy with warnings denied, and source clones pin Rust 1.95.0 through the repo-root toolchain file.

Current Baseline

• Rust is pinned to 1.95.0 with rust-toolchain.toml.
• wap-flow declares rust-version = "1.95" through workspace package metadata.
• Workspace lint policy keeps Rust 2024 safety hygiene explicit and inherits Clippy’s standard all group; pedantic, nursery, and dependency-audit policies are not enabled in this baseline.
• Compatible dependency versions were refreshed under Rust 1.95.0; major-version dependency migrations remain separate backlog work.
• cargo fmt --manifest-path flow/Cargo.toml --check passes.
• cargo check --manifest-path flow/Cargo.toml -p wap-flow passes.
• cargo clippy --manifest-path flow/Cargo.toml -p wap-flow --all-targets -- -D warnings passes.
• cargo test --manifest-path flow/Cargo.toml -p wap-flow passes.
• cargo run -q --manifest-path flow/Cargo.toml -p wap-flow -- doctor --json --strict can still report hooks_not_installed on source clones in bypass mode; treat that as local environment state unless the task is explicitly testing governed hooks.
• Context graph parser ambiguity is surfaced through existing review-context warnings when duplicate same-file symbols force call edges to be dropped, scoped to the current changed files.
• Context graph deletion reviews preserve stale indexed impact for the current payload before cleaning deleted files from the generated graph store.

P1 Backlog

• Keep task-to-branch binding segment-aware across start, check, pr, and active-task validation. Any new branch policy must add negative prefix-collision tests for issue-<n> and hyphenated task-<key> values; local branch slugs must remain separated from the task key by a non-key delimiter such as _.
• Preserve local-authority parity in acceptance and review-context flows. New review packet or graph payload fields must remain task-key/task-ref based, with GitHub issue data optional.
• Keep bundled acceptance adapters on structured argv or explicit built-in adapter identifiers. Raw shell execution is only an escape hatch for custom adapter commands.

P2 Backlog

• Continue shrinking oversized flow functions by extracting argument objects around lifecycle, memory-indexing, and acceptance-review transitions when those functions are touched for behavior changes.
• Consolidate task, branch, and authority normalization helpers so local task policy changes do not fork matching logic across checks, state, PR, and worktree code.

P3 Backlog

• Keep clippy clean as a standing regression gate. Prefer mechanical fixes first, and use targeted lint allowances only for derive-shaped CLI enums or test fixtures where refactoring would add broad churn.
• Reduce test helper argument bloat opportunistically when editing the related fixtures; avoid sweeping fixture rewrites with no behavior coverage gain.
• Replace repeated SQL placeholder and report-line construction patterns with small helpers when adjacent code is already changing.
• Consider major dependency migrations, such as rusqlite, ureq, or sha2, only as separate behavior-aware upgrade tasks.
• Consider a stricter curated lint pass only as an advisory gate first; do not blanket-enable pedantic or nursery without budgeting allowlist cleanup.

Batch Order

1. Guardrail hardening: add or update tests around task authority, branch matching, review context, adapter command selection, and parser ambiguity.
2. Clippy readiness: keep the lint gate clean with low-risk mechanical cleanup before structural refactors.
3. Contract alignment: update canonical flow specs whenever a validation gate, public CLI behavior, or output payload contract changes.