narratio/docs/roadmap/audit-sequence.md

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