Finalize codebase audit findings

docs/roadmap/audit-plan.md

@@ -0,0 +1,332 @@
+# Codebase Audit Plan
+
+Status: proposed
+
+## Purpose
+
+This audit will evaluate Narratio for correctness, efficiency, maintainability,
+and test-suite value. It will identify defects and credible risks, duplicated or
+near-duplicated behavior, code that can be made smaller or more idiomatic, and
+complex code whose remaining invariants need focused explanation.
+
+The audit is investigative. It should produce evidence-backed findings and a
+prioritized remediation backlog, not make opportunistic production changes as
+it proceeds. The [Audit Sequence](audit-sequence.md) assigns this scope to
+concrete execution stages.
+
+## Authoritative Baseline
+
+Review implemented behavior against its canonical owner rather than treating
+the current implementation or tests as the specification:
+
+- [Architecture](../policy/architecture.md) for system boundaries, dependency
+  direction, state and path ownership, safety properties, and pipeline
+  invariants;
+- [Internal Overview](../internal/overview.md) and its focused internal
+  documents for implemented ownership and mechanics;
+- [Testing Policy](../policy/testing.md) for risk-based sufficiency, durable
+  boundaries, test-double guidance, and test lifecycle decisions;
+- the [CLI](../cli.md), [Configuration](../config.md),
+  [Operations](../operations.md), and [integration contracts](../integrations/)
+  for externally observable behavior; and
+- the [Documentation Policy](../policy/documentation.md) for canonical ownership
+  and the distinction between current and proposed behavior.
+
+Where code, tests, and documentation disagree, record the disagreement. Do not
+assume which one is wrong until the canonical contract and caller expectations
+have been traced.
+
+## Audit Principles
+
+1. Review correctness before cleanup. A shorter implementation is not an
+   improvement if it weakens a state transition, safety check, or external
+   contract.
+2. Trace behavior across boundaries. Narratio's most important properties often
+   emerge from the interaction of application orchestration, stages, manifests,
+   artifact resolution, filesystem operations, and adapters.
+3. Distinguish repeated syntax from repeated policy. Extract a helper only when
+   the behavior has one stable owner and the shared abstraction makes that
+   ownership clearer. Similar stage code may be intentionally explicit.
+4. Prefer narrow, idiomatic Go over generic frameworks. In particular, proposed
+   refactors must preserve the explicit canonical stage sequence and must not
+   turn Narratio into a workflow engine or a second configuration system for
+   downstream tools.
+5. Optimize credible work. Flag repeated I/O, hashing, serialization, remote
+   calls, subprocess work, allocation, or poor asymptotic behavior when the
+   relevant path can matter. Require a benchmark or workload argument for
+   performance changes whose benefit is not evident.
+6. Treat comments as explanations of intent. Recommend comments for invariants,
+   ordering constraints, non-obvious failure policy, or security reasoning—not
+   as narration of ordinary Go or a substitute for simplifying code.
+7. Judge tests as a suite. A test can be locally reasonable and still add no
+   marginal protection, while a compact test can be inadequate for a
+   consequential cross-component failure.
+
+## Evidence And Finding Standard
+
+Begin from a cleanly identified revision and record toolchain and platform
+assumptions. Use the code knowledge graph to find ownership, callers, callees,
+similarity candidates, high-complexity functions, and weakly protected
+boundaries. Confirm every candidate by reading the implementation, its focused
+tests, and the applicable contract. Text search and static analysis supplement
+the graph for literals, configuration, generated files, and patterns that are
+not modeled reliably.
+
+Each finding should record:
+
+- category: correctness defect, correctness risk, duplication, simplification,
+  efficiency, architectural boundary, comment/clarity, or test-suite issue;
+- source locations and the affected contract or invariant;
+- concrete evidence and a realistic failure or maintenance scenario;
+- impact, likelihood, confidence, and estimated remediation scope separately;
+- the smallest plausible improvement and its intended owner;
+- tests that already protect the behavior, tests that should change or be
+  added, and tests that may become redundant; and
+- dependencies on, or conflicts with, other findings.
+
+Do not report a metric alone as a finding. Complexity, similarity, coverage,
+fan-in, file size, and test count are prioritization signals that require manual
+confirmation. Consolidate findings that share one root cause.
+
+## Cross-Cutting Review Lenses
+
+### Correctness And Pipeline Semantics
+
+Construct an explicit lifecycle matrix for every stage outcome: first run,
+already-succeeded skip, self-skip, failure, interruption, forced replacement,
+non-resumable result, and successful rerun. Trace how each outcome changes the
+session manifest, invocation manifest, downstream stage state, artifacts,
+diagnostics, and cleanup eligibility.
+
+Across the pipeline, verify:
+
+- the registry exposes one deterministic canonical order;
+- each stage's declared inputs, outputs, configuration, adapters, and manifest
+  effects agree with its implementation and focused documentation;
+- inputs are resolved through manifest and artifact contracts rather than
+  incidental directory contents;
+- run-local outputs are fully validated before canonical materialization;
+- failure, cancellation, or process interruption cannot advertise partial work
+  as successful;
+- force and changed outcomes invalidate exactly the intended succeeded
+  downstream work;
+- repeated execution is idempotent where promised, and ordering is stable
+  wherever maps, directory reads, remote listings, or dependency graphs are
+  involved;
+- session, campaign, run, source, checksum, contract, and external provenance
+  identities cannot be confused across runs; and
+- errors preserve useful causes and do not expose secrets or private content.
+
+Use fault-oriented reasoning at durability boundaries: fail immediately before
+and after manifest saves, canonical renames, external process completion,
+uploads, current-manifest publication, the current-run commit marker, restore
+manifest installation, and cleanup. Determine which state is authoritative and
+whether the next invocation recovers safely.
+
+### Duplication And Helper Ownership
+
+Search for exact and semantic duplication in production and tests, including:
+
+- repeated stage setup, input resolution, output validation, run-local
+  materialization, metadata construction, and error adaptation;
+- repeated manifest create/load/save and session/run transition handling;
+- repeated adapter construction, timeout parsing, command execution, generated
+  configuration, log handling, and output checks;
+- repeated source-ID, destination, remote-key, and path validation policy;
+- repeated sorting, deduplication, checksum, copy, and atomic-write mechanics;
+  and
+- repeated test fixtures and assertions that encode the same policy at several
+  layers.
+
+For each candidate, decide whether it is coincidental similarity, a repeated
+mechanism, or duplicated policy. Recommend extraction only when the helper can
+have a clear package owner, a narrow contract, and callers that become easier
+to understand. Prefer an unexported local helper when sharing is package-local.
+Do not create a broad utility package, force unlike stage results into one data
+model, or move policy into storage/file-operation helpers.
+
+Initial similarity and complexity signals should seed, but not predetermine,
+inspection of the single-stage command wrappers, session/run manifest
+persistence pairs, adapter constructors, Scriptorium operations, stage fakes,
+and common stage materialization paths.
+
+### Simplification, Go Idioms, And Efficiency
+
+Review long or branch-heavy functions for separable decisions, state
+transitions, or data transformations. Pay particular attention to orchestration,
+configuration validation, artifact dependency resolution, resume verification,
+restore/previous-cache planning, and analyze/publish selection logic. A useful
+refactor should reduce cognitive load while leaving the important ordering
+visible.
+
+Check for:
+
+- unnecessary nesting, defensive branches made unreachable by earlier
+  validation, repeated normalization, and overly wide parameter lists;
+- interfaces defined for hypothetical extensibility rather than a demonstrated
+  consumer boundary;
+- manual slice, map, string, error, and filesystem logic with a clearer standard
+  library form;
+- incorrect or inconsistent `errors.Is`/`errors.As`, wrapping, context
+  propagation, deferred cleanup, response-body closure, process waiting, and
+  goroutine/channel ownership;
+- redundant filesystem scans, `stat`/checksum passes, whole-file buffering,
+  copying, YAML/JSON round trips, sorting, remote listings, downloads, uploads,
+  or adapter initialization;
+- linear searches nested in loops and repeated dependency or artifact lookup
+  that should use an indexed map or a single planning pass;
+- unbounded concurrency, leaked work after cancellation, serialized independent
+  work, and nondeterministic result collection; and
+- obsolete dependencies, portability assumptions, and platform-sensitive path
+  or atomic-rename behavior.
+
+Keep correctness and diagnosability ahead of micro-optimization. When a simpler
+algorithm changes performance characteristics, specify the representative
+input size and validation method.
+
+### Comments And Local Explanation
+
+Review high fan-in, high-complexity, security-sensitive, and commit-boundary
+code after likely simplifications have been identified. Add a comment
+recommendation when a maintainer needs to know why:
+
+- state transitions or persistence operations occur in a specific order;
+- a stale record intentionally retains data while another transition clears it;
+- a path is checked more than once to resist traversal, symlink replacement, or
+  time-of-check/time-of-use hazards;
+- an artifact is accepted only with particular manifest, checksum, contract, or
+  provenance evidence;
+- a partial operation is intentionally not rolled back;
+- a remote pointer or local manifest must be installed last; or
+- concurrency, cancellation, compatibility, or downstream-tool behavior makes
+  an apparently simpler approach unsafe.
+
+Prefer a named helper, typed state, or smaller control flow when that removes the
+need for explanation. Check existing comments for stale claims as well as
+missing rationale.
+
+### Test Suite Against The Canonical Policy
+
+Build a risk-to-test matrix rather than auditing tests file by file in
+isolation. For each important behavior, identify its proper owner—parser,
+validator, domain package, adapter, orchestrator, CLI, integration, or end to
+end—and identify all tests that claim to protect it.
+
+Evaluate:
+
+- protection of data integrity, destructive operations, compatibility,
+  security, concurrency, idempotency, recovery, and partial failure;
+- manifest transitions, force/invalidation, resume validation, atomic
+  materialization, publish commit order, restore install order, and cleanup
+  gates as assembled behaviors;
+- realistic HTTP, subprocess, filesystem, and object-store boundary behavior,
+  including cancellation and malformed responses;
+- whether higher-level tests intentionally sample lower-level behavior or
+  redundantly reproduce its full policy;
+- whether tests assert durable outcomes or private constants, exact error text,
+  incidental paths, call choreography, or oversized snapshots;
+- whether real fast collaborators could replace elaborate doubles, and whether
+  stateful fakes are realistic enough for the risk they protect;
+- fixture/helper duplication, oversized test cases, and setup that obscures the
+  behavior under test without introducing a heavyweight test framework;
+- deterministic, offline, credential-free, order-independent execution and
+  safe handling of environment and process-global state;
+- focused fuzz candidates in parsing, normalization, source IDs, remote/local
+  path mapping, manifest decoding, and configuration boundaries; and
+- the presence and value of a small number of representative assembled
+  workflows.
+
+Use coverage only to locate unexpectedly weak consequential branches. Also
+inspect packages with extensive coverage for redundant tests and refactoring
+friction. For every proposed addition, deletion, or consolidation, state the
+realistic defect and marginal confidence involved.
+
+The audit baseline should include the repository's canonical commands plus
+targeted diagnostic runs where supported:
+
+```sh
+go test ./...
+go test -race ./...
+go vet ./...
+go build ./cmd/narratio
+```
+
+Use focused repeated or shuffled runs to investigate state leakage and
+flakiness, and collect package/branch coverage for diagnosis. Review continuous
+integration to determine whether the appropriate offline validation is enforced;
+do not turn coverage percentage into a gate merely for this audit.
+
+## Area-By-Area Inspection Map
+
+| Area | Primary locations | What to inspect |
+| --- | --- | --- |
+| Process and application boundary | `cmd/narratio`, `internal/app` | Command dispatch, configuration selection, production composition, secret loading, lock lifetime, object-store initialization, context/error propagation, and separation of CLI reporting from orchestration policy. Review operator commands for consistent current-state authority and shared read-only mechanics. |
+| Stage registry and runner | `internal/stage/placeholders.go`, `internal/stage/stage.go`, `internal/app/planner.go`, `internal/app/runner.go`, `internal/app/run_stage.go` | Canonical order, action decisions, resume/force/self-skip/failure transitions, downstream invalidation, session/run manifest consistency, resource lifecycle, cleanup triggering, and opportunities to decompose the runner without hiding its state machine. |
+| Configuration | `internal/config` | Strict decoding, discovery and precedence, centralized defaults, normalization, templating, validation order, unknown fields, empty-value behavior, secret references, cross-field constraints, path confinement, deterministic errors, duplicated validator policy, and compatibility with maintained examples. |
+| Prepare and audio | `internal/stage/prepare.go`, `internal/audio`, `internal/previouscache` | Local/S3 exclusivity, cache and spool identity, partial downloads, checksum/reuse policy, previous-session required/optional planning, deterministic input records, clearing semantics, traversal safety, and avoiding repeated remote or filesystem work. |
+| Transcript stages | `internal/stage/transcribe.go`, `merge.go`, `polish.go`, `normalize.go`, `trim.go`, `render.go` | Contract parity across similar stages, bounded concurrency and cancellation, deterministic speaker/input ordering, run-local validation and canonical promotion, report/diagnostic classification, disabled behavior, and narrow opportunities for shared mechanics. |
+| Extraction | `internal/stage/extract.go`, `extract_resume.go`, `internal/adapters/notarius`, `internal/fileops/directory.go` | External receipt and lane validation, configuration fingerprint limits, immutable promotion, symlink/root replacement defenses, provenance and checksum checks, immediate and cross-invocation reuse, obsolete versus unsafe outcomes, failure residue, and whether dense verification logic can be clarified without weakening it. |
+| Analyze and artifact dependencies | `internal/stage/analyze.go`, `internal/artifacts`, `internal/artifactpolicy` | Source-family validation, runtime catalog state, enabled/selected/reused distinctions, topological ordering and cycle handling, required/optional inputs, local-only previous sources, deterministic metadata, repeated lookup/scanning, and ownership shared with config and publish. |
+| Publish and cleanup | `internal/stage/publish.go`, `internal/app/post_publish_cleanup.go`, `internal/app/cleanup_targets.go` | Prerequisite success, output selection, locks, required/optional behavior, exclusion rules, deterministic upload set, retry/idempotency implications, current-manifest then commit-marker ordering, metadata gates, and destructive path confinement. |
+| Manifest state | `internal/manifest` | Validation and backward compatibility, atomic persistence, timestamps, session/run identity, transition truth table, clearing versus retaining payload, create/load/save duplication, failure during dual-manifest updates, and whether state mutation has a single owner. |
+| Artifacts, paths, and policy | `internal/artifacts`, `internal/artifactpolicy`, `internal/pathsafe` | Canonical helper coverage, ad hoc reconstruction by callers, source-ID ownership, manifest-first resolution, extraction/current-state identity, destination normalization, stable ordering, typed missing-state errors, symlink/traversal defenses, and duplicate policy across config/stages/app. |
+| Restore | `internal/app/restore*.go`, `internal/previouscache`, `internal/audio` | Remote authority, confined mapping, deterministic plan actions, local conflict and force behavior, dry-run purity, temp-file installation, manifest-last ordering, partial failure/retry behavior, report accuracy, cache reuse, and shared current-state mechanics. |
+| File operations | `internal/fileops`, `internal/pathsafe`, local-store code in `internal/artifacts` | Atomic-write and promotion guarantees, permissions, close/sync/rename error handling, temp cleanup, same-filesystem assumptions, replacement policy, regular-file-only traversal, symlink and root-swap resistance, lock cleanup, and portability. |
+| External adapters and storage | `internal/adapters`, `internal/audio` | Transport isolation, shared subprocess mechanics versus adapter-specific policy, command/config duplication, quoting and working directories, timeouts/cancellation, stdout/stderr separation, HTTP body and retry behavior, S3 pagination/streaming/not-found mapping, credential independence, and external error adaptation. |
+| Shared models and diagnostics | `internal/artifactmodel`, `internal/contracts`, `internal/logging` | Serialization and validation invariants, unnecessary conversions, ownership of shared types, stable diagnostic structure, redaction, and whether small shared packages remain cohesive. |
+| Tests, examples, and automation | all `*_test.go`, `examples/`, `.woodpecker/` | Risk ownership, semantic duplication, fixture cost, policy-coupled assertions, realistic boundary tests, end-to-end sufficiency, default-suite isolation, example validation, diagnostic coverage, flakiness, runtime cost, and enforcement of canonical validation. |
+
+## Narratio-Specific Cross-Boundary Scenarios
+
+In addition to package-local review, trace these complete scenarios because a
+modular pipeline can look correct within every package while violating an
+end-to-end invariant:
+
+1. A stage succeeds, its result becomes non-resumable, the rerun fails, and a
+   later invocation decides what remains usable.
+2. An upstream forced or changed outcome interacts with already-succeeded,
+   self-skipped, and disabled downstream stages.
+3. Extraction produces a valid immutable bundle, then configuration or
+   transitive Notarius inputs change before analyze or publish.
+4. Previous-session state is published, restored or prepared into the local
+   cache, and consumed by analyze without an unintended remote read.
+5. Publish fails at each upload boundary, especially between current manifest
+   and current-run pointer, followed by status, restore, and retry.
+6. Restore encounters identical files, conflicting files, unsafe remote keys,
+   cache hits, and a failure immediately before manifest installation.
+7. Automatic or manual cleanup is requested after skipped, failed, locked,
+   partially uploaded, and fully committed publish outcomes.
+8. Cancellation reaches bounded transcription work, HTTP requests,
+   subprocesses, object storage, and manifest reporting without leaks or false
+   success.
+9. A configured artifact is disabled, unselected, reused, generated from
+   another artifact, sourced from extraction, or sourced from a previous
+   session, then filtered for publish.
+10. The same session is invoked concurrently, including lock contention and
+    cleanup/release failures.
+
+## Completion Criteria
+
+The audit is complete when:
+
+- every area in the inspection map has been reviewed against its canonical
+  contracts and focused tests;
+- the stage lifecycle matrix and cross-boundary scenarios have explicit
+  conclusions;
+- duplication candidates have been classified rather than merely counted;
+- simplification and performance recommendations explain their correctness
+  constraints and expected benefit;
+- comment recommendations identify the non-obvious rationale to preserve;
+- the test suite has a risk-based sufficiency assessment, including gaps,
+  redundancy, durability, execution properties, and automation;
+- findings are deduplicated, evidence-backed, and ranked by risk and dependency;
+  and
+- unresolved questions and intentionally accepted risks are recorded rather
+  than silently omitted.
+
+## Execution
+
+The [Audit Sequence](audit-sequence.md) is the canonical owner of execution
+order, stage boundaries, checkpoints, validation, and audit deliverables. This
+document remains the canonical owner of audit scope, review criteria, and the
+finding standard.

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.