# 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.