Establish the codebase audit baseline and contract map

docs/roadmap/audit-sequence.md

@@ -0,0 +1,734 @@
+# Codebase Audit Sequence
+
+Status: proposed
+
+## Purpose And Relationship To The Audit Plan
+
+This document turns the [Codebase Audit Plan](audit-plan.md) into a bounded,
+execution-ready sequence. The plan owns scope, review criteria, and the finding
+standard. This document owns ordering, dependencies, working records,
+validation, and exit gates.
+
+The sequence is for investigation only. Do not mix production refactors or bug
+fixes into the audit. A confirmed urgent defect may justify stopping to request
+a separate remediation change, but its fix is not part of this sequence.
+
+## Audit Run Records
+
+Create `docs/roadmap/audit-findings.md` when the audit begins. It is the single
+working ledger and final audit report. Initialize it with:
+
+- the audited revision, branch/worktree state, Go version, platform, and audit
+  date;
+- baseline command results and timings;
+- an area coverage ledger;
+- the stage lifecycle matrix;
+- the cross-boundary scenario matrix from the audit plan;
+- a risk-to-test matrix;
+- candidate and confirmed finding registers; and
+- unresolved questions, accepted risks, and final conclusions.
+
+Track each execution stage in the coverage ledger with one of `not_started`,
+`in_progress`, `complete`, or `blocked`. For a completed stage, record:
+
+- contracts, packages, files, and important symbols reviewed;
+- graph traces, commands, tests, or other evidence used;
+- finding and candidate IDs produced;
+- explicit no-finding conclusions for reviewed high-risk behavior; and
+- follow-up questions assigned to later stages.
+
+Use stable finding IDs with these prefixes:
+
+| Prefix | Category |
+| --- | --- |
+| `COR` | Confirmed correctness defect |
+| `RSK` | Correctness or operational risk |
+| `ARC` | Ownership or architectural-boundary issue |
+| `DUP` | Duplicated mechanism or policy |
+| `SIM` | Simplification or idiomatic-Go opportunity |
+| `EFF` | Efficiency or resource-use issue |
+| `COM` | Missing, misleading, or stale explanatory comment |
+| `TST` | Test-suite gap, redundancy, brittleness, or execution issue |
+
+Candidate IDs remain candidates until manual inspection confirms the behavior,
+contract, realistic scenario, and affected callers. Rejected candidates remain
+in a short classification log so later stages do not reopen them without new
+evidence.
+
+## Execution Rules
+
+1. Pin the audit to the revision recorded in Stage 0. If the worktree or HEAD
+   changes, record the change and rerun every affected stage; do not silently
+   combine evidence from different implementations.
+2. Use codebase graph search and call/data-flow traces before broad source
+   search. Read the exact implementation, focused tests, and canonical contract
+   before confirming a finding.
+3. Record test-policy observations during every behavior pass. Stage 12 owns the
+   suite-wide conclusion but must not rediscover the suite from scratch.
+4. Record cross-area observations as candidates for the stage that owns the
+   conclusion. Avoid producing duplicate findings from several review passes.
+5. Treat baseline failures as evidence, not automatic blockers. Continue when
+   read-only inspection remains sound, and state the limitation. Stop only when
+   the repository cannot be identified, required sources are unavailable, or a
+   failure makes later evidence unreliable.
+6. Do not exercise a suspected destructive, credentialed, paid, or live-service
+   path merely to prove a defect. Use source reasoning, existing safe fakes, or
+   a narrowly controlled offline reproduction.
+7. Escalate a credible active data-loss, secret-exposure, or unsafe-cleanup
+   defect immediately. Preserve the evidence and do not wait for final
+   synthesis before reporting it.
+8. A stage is complete only when its exit gate is met. A package test passing is
+   evidence, not proof that the review is complete.
+
+## Sequence Overview
+
+| Stage | Focus | Depends on | Primary result |
+| --- | --- | --- | --- |
+| 0 | Pin revision and establish baseline | None | Reproducible audit record |
+| 1 | Contract, boundary, and lifecycle map | 0 | Review matrices and ownership map |
+| 2 | Runner and manifest state machine | 1 | Lifecycle and dual-ledger conclusions |
+| 3 | Paths, artifacts, and filesystem safety | 1-2 | State/path authority and mutation conclusions |
+| 4 | Publish, remote commit, and cleanup | 2-3 | Commit-boundary and destructive-operation conclusions |
+| 5 | Restore and remote/previous state | 2-4 | Restore authority and recovery conclusions |
+| 6 | Configuration and application composition | 1-5 | Validation and wiring conclusions |
+| 7 | External adapters and shared support | 3, 6 | Boundary, cancellation, and resource conclusions |
+| 8 | Prepare and transcript-processing stages | 2-3, 6-7 | Ordinary stage-contract conclusions |
+| 9 | Extraction vertical slice | 2-3, 6-7 | Promotion, provenance, and resume conclusions |
+| 10 | Analyze and artifact dependency slice | 3, 6, 8-9 | Dependency and source-resolution conclusions |
+| 11 | Cross-codebase duplication, simplicity, efficiency, and comments | 2-10 | Classified maintainability candidates |
+| 12 | Test-suite policy audit | 2-11 | Risk-based suite sufficiency assessment |
+| 13 | Synthesis and audit closeout | 0-12 | Final deduplicated audit report |
+
+Stages are intentionally ordered. Later stages may resolve candidates raised by
+earlier ones, but they must not invalidate an earlier stage silently. Return to
+the owning stage, update its coverage record, and note the new evidence.
+
+## Stage 0: Pin Revision And Establish Baseline
+
+### Entry
+
+- Repository root and `docs/development.md` are available.
+- The audit plan and canonical policy documents can be read.
+
+### Execute
+
+1. Record `git rev-parse HEAD`, branch/detached state, `git status --short`,
+   `go version`, `go env GOOS GOARCH`, and the current date.
+2. Confirm that the code knowledge graph represents the recorded repository and
+   revision; refresh the index if it is missing or stale.
+3. Capture the package/file/test inventory, entry points, architecture
+   boundaries, high fan-in symbols, complexity signals, and similarity signals.
+4. Run the default offline baseline and record wall time and failures:
+
+   ```sh
+   go test -count=1 ./...
+   go test -race -count=1 ./...
+   go vet ./...
+   ```
+
+5. Build into an external temporary directory so validation does not add a
+   workspace binary:
+
+   ```sh
+   audit_build_dir="$(mktemp -d)"
+   go build -o "$audit_build_dir/narratio" ./cmd/narratio
+   go test -coverprofile="$audit_build_dir/coverage.out" ./...
+   ```
+
+6. Inventory the repository's CI/release validation, maintained examples, fuzz
+   tests, golden data, opt-in tests, and generated-test update mechanisms.
+
+### Output
+
+- Baseline and inventory sections in `audit-findings.md`.
+- Initial coverage ledger containing Stages 0-13.
+- Unconfirmed metric-driven candidates, clearly labeled as such.
+
+### Exit Gate
+
+- Revision and environment are reproducible.
+- Every baseline command has a recorded result.
+- Graph freshness is known.
+- Any limitation that affects later stages has an owner and disposition.
+
+## Stage 1: Build The Contract, Boundary, And Lifecycle Map
+
+### Entry
+
+- Stage 0 is complete.
+
+### Execute
+
+1. Read the architecture, internal overview, testing policy, focused internal
+   documents, and the relevant CLI/configuration/operations/integration
+   contracts using the development guide's routing rules.
+2. Map each package and important interface to its owned policy. Mark every
+   cross-package dependency that appears to reverse or blur the intended
+   direction for later confirmation.
+3. Build a stage-contract matrix with canonical order, declared inputs,
+   outputs, configuration, adapters, skip behavior, resume validation,
+   materialization boundary, manifest effects, and downstream invalidation.
+4. Build the lifecycle matrix required by the audit plan: first run,
+   already-succeeded skip, self-skip, failure, interruption, forced replacement,
+   non-resumable result, and successful rerun.
+5. Assign each of the ten cross-boundary scenarios in the audit plan to its
+   primary execution stage and list supporting packages/tests.
+6. Seed the risk-to-test matrix with the intended test owner for each
+   architectural invariant. Do not judge sufficiency yet.
+
+### Output
+
+- Package ownership, stage-contract, lifecycle, scenario, and preliminary
+  risk-to-test matrices.
+- `ARC` and `RSK` candidates for apparent disagreements, without deciding from
+  documentation alone which artifact is wrong.
+
+### Exit Gate
+
+- Every area in the audit plan's inspection map has an assigned stage.
+- Every architectural invariant has an implementation owner and intended test
+  owner.
+- Unknown or contradictory contracts are explicitly recorded.
+
+## Stage 2: Audit The Runner And Manifest State Machine
+
+### Entry
+
+- Stage 1 matrices are complete.
+
+### Execute
+
+1. Trace the entry paths into full-run and single-stage execution through
+   `internal/app/planner.go`, `runner.go`, `run_stage.go`, and related helpers.
+2. Inspect `internal/manifest` models, validation, session/run creation,
+   loading, normalization, atomic saves, and all transition methods.
+3. Walk every lifecycle-matrix cell through both manifests. Verify clearing
+   versus retention of outputs, diagnostics, generated configuration, metadata,
+   errors, actions, timestamps, and downstream state.
+4. Reason about failures before and after each session-manifest and run-manifest
+   save. Determine which disagreement states are possible and how a later
+   invocation interprets them.
+5. Review force, changed-result, self-skip, failed-result, and non-resumable
+   invalidation separately. Confirm behavior at the first and last canonical
+   stage.
+6. Review session lock acquisition/release and concurrent invocation behavior,
+   while leaving path implementation details to Stage 3.
+7. Classify the runner's complexity and repeated session/run persistence paths:
+   state-machine clarity, justified explicitness, candidate local helpers, and
+   comments that preserve ordering rationale.
+8. Review focused app/manifest tests against the matrix and add observations to
+   the risk-to-test ledger.
+
+### Validation
+
+```sh
+go test -count=1 ./internal/app ./internal/manifest
+go test -race -count=1 ./internal/app ./internal/manifest
+```
+
+### Exit Gate
+
+- Every lifecycle cell has a source-backed conclusion for both manifests.
+- Cross-boundary scenarios 1, 2, and the lock portion of 10 are resolved or
+  carry explicit questions.
+- All runner/manifest candidates are confirmed, rejected, or assigned to a
+  named later stage.
+
+## Stage 3: Audit Paths, Artifacts, And Filesystem Safety
+
+### Entry
+
+- Stages 1-2 are complete.
+
+### Execute
+
+1. Review `internal/artifacts`, `internal/artifactpolicy`, `internal/pathsafe`,
+   `internal/fileops`, and local-store filesystem code.
+2. Inventory canonical path and key helpers, then search callers for ad hoc
+   reconstruction, double normalization, mixed slash/filesystem semantics, or
+   policy implemented outside its owner.
+3. Trace built-in, configured, extraction, previous-session, and current-state
+   artifact resolution. Verify identity, checksum, contract, provenance,
+   deterministic ordering, and typed missing-state behavior.
+4. Review atomic file writes, copies, directory promotion, temp cleanup,
+   permission preservation, close/sync/rename errors, existing-destination
+   behavior, same-filesystem assumptions, and platform sensitivity.
+5. Walk traversal, absolute path, broad root, symlink component, inspected-root
+   replacement, non-regular file, and time-of-check/time-of-use scenarios.
+6. Confirm that low-level file/storage helpers receive explicit destinations
+   and do not infer stage, campaign, session, run, or publish policy.
+7. Inspect lock-file implementation and cleanup errors to finish scenario 10.
+8. Record focused test ownership and gaps without duplicating Stage 2's state
+   conclusions.
+
+### Validation
+
+```sh
+go test -count=1 ./internal/artifacts ./internal/artifactpolicy ./internal/pathsafe ./internal/fileops
+go test -race -count=1 ./internal/artifacts ./internal/fileops
+```
+
+### Exit Gate
+
+- Every canonical path/key family has one identified owner.
+- Every material filesystem mutation has documented confinement and atomicity
+  conclusions.
+- Scenario 10 is resolved.
+- Safety checks that appear repetitive are classified before any simplification
+  recommendation is made.
+
+## Stage 4: Audit Publish, Remote Commit, And Cleanup
+
+### Entry
+
+- Stages 2-3 are complete.
+
+### Execute
+
+1. Trace publish from stage selection through object-store calls, manifest
+   metadata, commit-marker publication, run completion, and post-publish
+   cleanup.
+2. Verify prerequisite stage-state checks, selected/configured/extraction
+   output resolution, required versus optional outputs, static and remote
+   locks, run-file exclusions, previous-cache inclusion, and deterministic
+   upload order.
+3. Enumerate failures before and after every upload. Prove that
+   `current/run_id.txt` is written last and is the only remote-current commit
+   point.
+4. Review retry/idempotency behavior, existing remote objects, partial uploads,
+   pointer/manifest disagreement, and status/restore interpretation after each
+   partial outcome.
+5. Trace automatic and manual cleanup gates. Confirm publish execution,
+   `uploaded`, `current_pointer_written`, explicit policy, and confined targets
+   are all required at the correct boundary.
+6. Confirm that `--force` cannot override publish locks or cleanup safety.
+7. Review duplication between publish planning, artifact destination policy,
+   operator views, and cleanup metadata only after ownership is established.
+
+### Validation
+
+```sh
+go test -count=1 ./internal/stage ./internal/app ./internal/artifacts ./internal/adapters/storage
+```
+
+### Exit Gate
+
+- Cross-boundary scenarios 5 and 7 are resolved for every relevant failure
+  boundary.
+- Remote-current authority and local-cleanup eligibility have explicit truth
+  tables.
+- Publish findings distinguish stage policy from storage mechanics.
+
+## Stage 5: Audit Restore And Remote/Previous State
+
+### Entry
+
+- Stages 2-4 are complete.
+
+### Execute
+
+1. Trace restore discovery, planning, execution, reporting, audio
+   materialization, and previous-cache planning through `internal/app`,
+   `internal/artifacts`, `internal/previouscache`, `internal/audio`, and storage.
+2. Confirm remote pointer/manifest identity and campaign/session/run authority,
+   including missing and inconsistent current state.
+3. Verify remote-to-local confinement, deterministic action ordering,
+   `download`/`skip_same`/`conflict` decisions, force semantics, and dry-run
+   purity.
+4. Walk failures during download, checksum or manifest validation, atomic
+   install, report persistence, and the manifest-last boundary. Record the
+   intentional lack of rollback and retry consequences.
+5. Review audio spool/cache identity, cache-hit verification, partial download
+   behavior, and duplicate remote/filesystem work.
+6. Review previous-session requirement planning, required/optional behavior,
+   identity checks, published-path fallback, and deterministic local mapping.
+7. Confirm which mechanics are shared with status/validate/operator commands
+   and which caller-specific missing-state policies must remain separate.
+
+### Validation
+
+```sh
+go test -count=1 ./internal/app ./internal/previouscache ./internal/audio ./internal/artifacts ./internal/adapters/storage
+```
+
+### Exit Gate
+
+- Cross-boundary scenarios 4 and 6 are resolved through retry/recovery.
+- Restore authority, manifest-last installation, and partial-write behavior are
+  explicit.
+- Previous-cache conclusions are ready for the prepare and analyze passes.
+
+## Stage 6: Audit Configuration And Application Composition
+
+### Entry
+
+- Stage 1 is complete and Stages 2-5 have identified the policies that
+  configuration and composition must supply.
+
+### Execute
+
+1. Review `internal/config`, `cmd/narratio`, application command dispatch,
+   configuration selection, secret-file environment loading, and production
+   collaborator construction.
+2. Trace discovery, precedence, strict YAML decoding, defaults, empty values,
+   normalization, session templating, and validation order across pipeline,
+   campaign, and session configuration.
+3. Verify cross-field constraints for stage enablement, paths, timeouts,
+   concurrency, artifacts, Notarius, Scriptorium, publish, storage, cleanup,
+   audio, and previous-session behavior.
+4. Compare validation logic with maintained examples and the public
+   configuration contract. Record contract drift rather than silently choosing
+   code or docs.
+5. Check that filesystem secrets are loaded before the boundary that consumes
+   them and are excluded from logs, manifests, reports, generated files, and
+   errors.
+6. Review conditional construction of expensive/external collaborators and
+   cleanup of anything with a lifecycle. Confirm test injection cannot create a
+   behavior different from production composition.
+7. Classify repeated validators, path checks, timeout parsing, constructor
+   wrappers, and single-stage command wrappers by policy owner.
+
+### Validation
+
+```sh
+go test -count=1 ./internal/config ./internal/app ./cmd/narratio
+go vet ./...
+```
+
+### Exit Gate
+
+- Every operator-visible field used by audited behavior has a traced default,
+  normalization, validation, and consumer.
+- Composition conclusions cover enabled and disabled stages without requiring
+  live services or credentials.
+- Maintained examples have an explicit validity conclusion.
+
+## Stage 7: Audit External Adapters And Shared Support
+
+### Entry
+
+- Stages 3 and 6 are complete.
+
+### Execute
+
+1. Review `internal/adapters`, `internal/audio`, `internal/logging`,
+   `internal/contracts`, and `internal/artifactmodel` at their public package
+   boundaries.
+2. For each HTTP, subprocess, notification, and object-storage adapter, compare
+   implementation with its integration contract and trace all production
+   callers.
+3. Verify context cancellation, timeout ownership, process termination and
+   waiting, goroutine/channel closure, HTTP response-body closure, retries,
+   malformed responses, streaming, pagination, not-found mapping, and local
+   file cleanup.
+4. Confirm command argument construction, working directory, environment,
+   generated configuration, stdout/stderr separation, output validation, and
+   external error adaptation stay inside the owning adapter.
+5. Compare subprocess implementations to the shared subprocess package. Classify
+   repeated constructor/config/log/output mechanics separately from
+   adapter-specific protocol policy.
+6. Review fakes for realistic state and concurrency behavior, but defer their
+   suite-wide value judgment to Stage 12.
+7. Check shared models for avoidable conversions, stable serialization,
+   validation ownership, and redaction-sensitive diagnostic fields.
+
+### Validation
+
+```sh
+go test -count=1 ./internal/adapters/... ./internal/audio ./internal/logging ./internal/contracts ./internal/artifactmodel
+go test -race -count=1 ./internal/adapters/... ./internal/audio
+```
+
+### Exit Gate
+
+- Every external resource has an explicit acquisition, cancellation, and
+  release conclusion.
+- Transport types and protocol policy have not leaked into stages.
+- Adapter duplication candidates identify the correct shared or specific
+  owner.
+
+## Stage 8: Audit Prepare And Transcript-Processing Stages
+
+### Entry
+
+- Stages 2-3 and 6-7 are complete.
+
+### Execute
+
+1. Review `prepare`, `transcribe`, `merge`, `polish`, `normalize`, `trim`, and
+   `render` as vertical slices from resolved configuration and manifest input
+   through adapter call, run-local output, validation, canonical
+   materialization, and recorded result.
+2. Verify each implementation against the Stage 1 contract matrix and focused
+   internal document. Record any undeclared input, output, diagnostic, config,
+   adapter, or skip/failure behavior.
+3. For prepare, confirm local/S3 exclusivity, stable input copying,
+   previous-cache clearing/hydration, and deterministic manifest input records.
+4. For transcribe, confirm unique speaker identities, bounded runtime
+   concurrency, cancellation, deterministic result ordering, adapter-returned
+   path identity, and partial failure behavior.
+5. For transformation/render stages, confirm manifest-first resolution,
+   run-local paths, schema/report validation, disabled/default behavior,
+   canonical promotion, and diagnostic-versus-artifact classification.
+6. Compare similar stage implementations for shared mechanisms only after
+   listing meaningful differences. Avoid a generic stage framework.
+7. Add stage-focused test ownership, gaps, and redundancy candidates to the
+   risk-to-test matrix.
+
+### Validation
+
+```sh
+go test -count=1 ./internal/stage ./internal/audio ./internal/previouscache ./internal/adapters/whisperx ./internal/adapters/seriatim ./internal/adapters/audita ./internal/adapters/scriptorium
+go test -race -count=1 ./internal/stage ./internal/audio
+```
+
+### Exit Gate
+
+- Every reviewed stage has a completed contract-matrix row.
+- Cross-boundary scenario 8 is resolved for transcription and subprocess-backed
+  transformation stages.
+- Similarity candidates are classified as intentional explicitness, local
+  helper candidates, or shared-owner findings.
+
+## Stage 9: Audit The Extraction Vertical Slice
+
+### Entry
+
+- Stages 2-3 and 6-7 are complete.
+
+### Execute
+
+1. Trace extraction from configuration validation and composition through
+   transcript resolution, invocation fingerprint, Notarius execution, receipt
+   and lane validation, directory promotion, manifest recording, catalog
+   hydration, resume validation, analyze, and publish consumers.
+2. Verify run-local isolation, regular-file and confined-index requirements,
+   required-lane policy, contract/provenance construction, checksum timing,
+   immutable destination identity, and no-replacement promotion.
+3. Enumerate failures before and after subprocess completion, receipt parsing,
+   payload inspection, promotion, and manifest persistence. Determine what
+   remains diagnostic, durable, advertised, and reusable.
+4. Walk every resume validation branch. Distinguish obsolete/missing outcomes
+   that trigger rerun from unsafe conditions that must stop execution.
+5. Evaluate the fingerprint's intentionally observable and unobservable inputs
+   against documentation and force guidance.
+6. Review the dense validation code for named sub-decisions and comments while
+   preserving the visible security proof and check ordering.
+7. Confirm focused tests cover immediate reuse, cross-invocation reuse,
+   configuration change, payload tampering, provenance mismatch, symlinks/root
+   replacement, failure residue, and downstream invalidation at the correct
+   layers.
+
+### Validation
+
+```sh
+go test -count=1 ./internal/stage ./internal/artifacts ./internal/fileops ./internal/adapters/notarius ./internal/app
+```
+
+### Exit Gate
+
+- Cross-boundary scenario 3 is resolved, including transitive-input limits.
+- Promotion, advertisement, and resume each have a distinct authority and
+  failure conclusion.
+- Every proposed simplification states which security or compatibility checks
+  it preserves.
+
+## Stage 10: Audit Analyze And Artifact Dependencies
+
+### Entry
+
+- Stages 3, 6, 8, and 9 are complete.
+
+### Execute
+
+1. Trace all analyze source families from configuration validation through
+   runtime catalog registration, availability, resolution, Scriptorium
+   execution/reuse, materialization, metadata, and publish selection.
+2. Verify enabled, selected, executable, reused, generated, and unavailable
+   states are distinct and deterministic.
+3. Review configured-artifact dependency validation and runtime topological
+   ordering for cycles, missing dependencies, stable ordering, and consistency
+   between configuration and execution.
+4. Confirm required/optional behavior and guidance for built-in transcripts,
+   prepared stable inputs, configured artifacts, extraction sources, and
+   previous-session sources.
+5. Prove previous-session resolution is local-only during analyze and that
+   disabled artifacts are reused only under the documented conditions.
+6. Inspect repeated resolution branches, parameter width, nested lookup, and
+   ordering work for a smaller representation or indexed plan without merging
+   distinct source policies.
+7. Review tests for each state transition and source family at the narrowest
+   stable owner, noting semantic duplication across config, artifacts, stage,
+   publish, and assembled runner tests.
+
+### Validation
+
+```sh
+go test -count=1 ./internal/stage ./internal/artifacts ./internal/artifactpolicy ./internal/config ./internal/adapters/scriptorium ./internal/app
+```
+
+### Exit Gate
+
+- Cross-boundary scenario 9 is resolved for every source family and selection
+  state.
+- Dependency ordering and source availability have explicit determinism and
+  complexity conclusions.
+- Config, artifact-policy, catalog, stage, and publish ownership is unambiguous
+  or represented by an `ARC` finding.
+
+## Stage 11: Audit Duplication, Simplicity, Efficiency, And Comments
+
+### Entry
+
+- Behavior stages 2-10 are complete, so structural candidates can be judged
+  against known contracts.
+
+### Execute
+
+1. Rerun graph similarity, complexity, fan-in/fan-out, call-path, loop-depth,
+   scan-in-loop, and change-coupling analyses on production code. Add targeted
+   text/static searches for patterns the graph cannot represent.
+2. Revisit all `DUP`, `SIM`, `EFF`, and `COM` candidates collected earlier.
+   Search for additional occurrences and trace all callers before assigning an
+   owner.
+3. For duplication, classify coincidental syntax, shared mechanism, duplicated
+   policy, or deliberately explicit security/state logic. Propose only the
+   narrowest helper that improves ownership and comprehension.
+4. For complexity, sketch the smaller control flow or data model and verify it
+   leaves state transitions, validation order, and commit boundaries visible.
+5. For efficiency, state the input scale or call frequency, current and proposed
+   complexity/I/O behavior, expected benefit, and benchmark or measurement
+   needed. Reject micro-optimizations without a credible workload.
+6. Review standard-library usage, errors, slices/maps, allocations, copying,
+   sorting, serialization, filesystem passes, adapter initialization, remote
+   calls, goroutines/channels, and interface breadth across the complete codebase.
+7. Review comments only after simplification decisions. Recommend why-comments
+   for remaining invariants, compatibility limits, safety checks, partial
+   failure, and ordering; flag comments that restate code or no longer match it.
+8. Check dependencies and platform assumptions for clear correctness,
+   portability, complexity, or maintenance consequences.
+
+### Validation
+
+- Run focused package tests for any behavior used to disprove or confirm a
+  candidate.
+- Run existing benchmarks where relevant. Propose a benchmark rather than
+  inventing performance claims when representative measurement is absent.
+
+### Exit Gate
+
+- Every structural candidate is confirmed, rejected with a reason, or merged
+  into a stronger root-cause finding.
+- No helper recommendation creates a generic workflow abstraction or moves
+  policy into a low-level utility.
+- Every efficiency finding has a credible workload and validation method.
+- Every comment finding states the non-obvious rationale that should be
+  preserved.
+
+## Stage 12: Audit The Test Suite Against Policy
+
+### Entry
+
+- Stages 2-11 have populated the risk-to-test matrix and test observations.
+
+### Execute
+
+1. Complete the risk-to-test matrix. For every consequential invariant, list
+   the current tests, proper owner, protected defect, missing failure modes, and
+   overlap with other layers.
+2. Review tests by behavior cluster rather than filename: parsing/validation,
+   domain/state, filesystem, adapters, orchestration, CLI, integration, and
+   representative assembled workflows.
+3. Classify gaps for data integrity, destructive operations, compatibility,
+   security, concurrency, idempotency, recovery, cancellation, and partial
+   success. Confirm the gap is not credibly protected elsewhere.
+4. Classify redundancy and brittleness: private constants/defaults, exact error
+   wording, incidental formatting/paths, mock choreography, oversized
+   snapshots, helper-level duplication, and the same policy repeated across
+   layers.
+5. Review doubles using the policy order: real deterministic collaborator,
+   stateful fake, stub, then mock when interaction is contractual. Check that
+   fakes model the failure and state semantics used by the tests.
+6. Inspect test helpers and large test functions for simplification and
+   meaningful table-driven boundaries without creating a fixture framework
+   whose maintenance cost exceeds its value.
+7. Review determinism and isolation: credentials, network access, paid APIs,
+   environment, working directory, clocks, randomness, ports, temp paths,
+   process-global state, ordering, cleanup, and parallel execution.
+8. Use coverage to investigate consequential weak branches, not as a score.
+   Review heavily covered behavior for marginal-value duplication as well.
+9. Identify focused fuzz opportunities for parsers, YAML/JSON normalization,
+   source IDs, confined paths, remote/local mapping, and manifest decoding.
+10. Compare local requirements with `.woodpecker/` and other automation. Record
+    missing enforcement as a risk/cost decision, not an assumption that every
+    diagnostic command belongs in CI.
+11. Investigate order dependence and flakiness with bounded runs, recording
+    runtime and any reproducible seed:
+
+    ```sh
+    go test -shuffle=on -count=3 ./...
+    go test -race -shuffle=on -count=1 ./...
+    ```
+
+### Exit Gate
+
+- Every important risk has a sufficiency conclusion and one intended test
+  owner.
+- Every proposed test addition names the realistic defect and marginal value.
+- Every deletion/consolidation names the stronger remaining protection.
+- Default-suite determinism, offline behavior, runtime, flakiness, and CI
+  enforcement have explicit conclusions.
+
+## Stage 13: Synthesize And Close The Audit
+
+### Entry
+
+- Stages 0-12 meet their exit gates or have explicitly accepted limitations.
+
+### Execute
+
+1. Reconcile candidates and findings across stages. Merge shared root causes and
+   remove repeated symptoms while retaining all affected locations and
+   contracts.
+2. Recheck every confirmed finding against current source, callers, tests, and
+   canonical documentation. Downgrade or reject anything supported only by a
+   metric or hypothetical preference.
+3. Rank impact, likelihood, confidence, and remediation scope separately. Order
+   the recommended backlog by dependency: correctness/data safety first,
+   architectural ownership next, then simplification/duplication, tests,
+   efficiency, and comments where they remain necessary.
+4. Record positive conclusions for high-risk areas where the current design and
+   tests are sufficient. The report should not imply that only defective areas
+   were reviewed.
+5. Reconcile the area coverage ledger, lifecycle matrix, cross-boundary scenario
+   matrix, and risk-to-test matrix with the audit plan's completion criteria.
+6. Record any accepted risks, ambiguous contracts, environmental limitations,
+   and deferred investigations with an explicit rationale and owner.
+7. Check whether HEAD or the worktree changed since Stage 0. Rerun affected
+   stages or clearly pin the report to the original revision.
+8. Validate the report and roadmap document links and run `git diff --check`.
+   If implementation changed during the audit, rerun the full Stage 0 validation
+   baseline against the final audited revision.
+
+### Final Deliverable
+
+`docs/roadmap/audit-findings.md` must contain:
+
+- an executive assessment without unsupported quality scores;
+- the audited revision and validation baseline;
+- coverage and scenario completion summaries;
+- confirmed findings ordered by dependency and risk;
+- rejected candidate themes where their recurrence would otherwise waste work;
+- the test-suite sufficiency assessment;
+- positive conclusions and accepted risks; and
+- a recommended remediation order, without implementing the remediation.
+
+### Exit Gate
+
+- Every completion criterion in the audit plan is satisfied or explicitly
+  marked limited with rationale.
+- Every finding is evidence-backed, deduplicated, actionable, and assigned a
+  stable ID.
+- No production change is included in the audit output.
+- The report is sufficient to prepare a separate remediation sequence without
+  repeating discovery.