# Codebase Audit Findings

Status: in progress

This document is the working ledger and final report for the audit defined by
the [audit plan](audit-plan.md) and [audit sequence](audit-sequence.md). The
audit is investigative: candidate findings below are not remediation changes.

## Audit Identity And Baseline

| Field | Value |
| --- | --- |
| Audited revision | `74e2d21de5fb2ada0be5ef3fe9333e0d48ac7fb3` (`Close the completed roadmap documents`) |
| Branch | `main`, attached worktree |
| Initial worktree state | Untracked `docs/roadmap/audit-plan.md` and `docs/roadmap/audit-sequence.md`; no production or test changes |
| Audit date | 2026-08-10 UTC |
| Toolchain | `go version go1.26.5 linux/amd64` |
| Platform | `GOOS=linux`, `GOARCH=amd64` |
| Repository root | `/home/eric/Workspace/narratio` |

The two initial untracked files are the audit specification supplied for this
run. Adding this ledger and tracking those documents changes documentation
only; all implementation and test evidence remains pinned to the revision
above. If implementation or tests change, affected audit stages must be rerun
and this section must record the new revision.

### Baseline Commands

| Command | Result | Wall time | Evidence or limitation |
| --- | --- | --- | --- |
| `go test -count=1 ./...` | pass | 3.34 s | All 23 packages passed; `cmd/narratio` has no test files. |
| `go test -race -count=1 ./...` | fail | 55.65 s | Race in `internal/adapters/whisperx.(*FakeClient).Transcribe` at `fake.go:45`, reached concurrently by `TestTranscribeStageTranscribesPreparedAudio`; candidate `TST-001`. All packages reported before `internal/stage` passed. |
| `go vet ./...` | pass | 0.47 s | No diagnostics. |
| `go build -o "$audit_build_dir/narratio" ./cmd/narratio` | pass | 1.03 s | Built outside the repository in `/tmp/tmp.x11pJL7014`. |
| `go test -coverprofile="$audit_build_dir/coverage.out" ./...` | pass | 11.05 s | Diagnostic coverage only; no percentage is treated as a gate. |

Coverage ranged from 69.8% (`internal/manifest`) to 100% (`internal/logging`)
among tested packages. `cmd/narratio` reported 0% because it has no tests. The
remaining package results ranged from 70.1% to 88.1%. Stage 12 owns the
risk-based interpretation; these numbers are inventory signals only.

### Code Graph Freshness And Structural Inventory

The `narratio` graph was rebuilt in `moderate` mode after the revision was
pinned. Its branch record reports the exact audited HEAD, `main`, and the
repository root above. The index contains 2,407 nodes and 13,181 edges across
224 modeled files: 1,494 functions, 136 methods, 226 structs, 12 interfaces,
and 20 modeled package nodes. The moderate filter excluded documentation,
examples, `.git`, `.codex`, and `cmd/narratio`; the executable entry point was
therefore verified through `go list` and direct inspection instead of graph
evidence. Internal production code is represented at the pinned revision.

Repository inventory at that revision:

- 23 Go packages, including `cmd/narratio`;
- 221 tracked Go files and 95 tracked `_test.go` files;
- 278 tracked files total;
- one process entry point, `cmd/narratio/main.go`, delegating to
  `internal/app.Execute`;
- 11 canonical stages returned by `internal/stage.All`; and
- 12 modeled interfaces, of which 11 are Narratio boundaries and one is the
  private AWS S3 client seam.

Graph call tracing from `internal/app.Execute` confirms command dispatch into
run, single-stage, clean, and session-helper paths, followed by configuration,
artifact/path, manifest, stage, storage, restore, and cleanup owners. The
production import inventory shows no lower-level package importing
`internal/app`; apparent graph rollups such as `stage -> app`, `adapters -> app`,
and `config -> app` came from test relationships or graph classification and
are rejected as production dependency reversals at this mapping stage.

### Metric Signals For Later Review

These are prioritization signals, not findings:

| Signal | Evidence | Assigned review |
| --- | --- | --- |
| High fan-in | `app.Error` (207), stage `Run` symbols (151), `app.Execute` (108), `stage.sessionPathsForEnv` (105), `manifest.New` (72), `manifest.MarkStageSucceeded` (56), `app.executeStages` (48), `artifacts.S3SessionPrefix` (41), and `artifacts.SessionWorkDirForCampaign` (37) | Owning behavior stages, then Stage 11 |
| High complexity | `app.executeStages` cyclomatic 54/cognitive 96; `previouscache.BuildPlan` 22/38; `analyzeStage.Run` 20/27; `audita.NewSubprocessRunner` 17/25; `app.SessionInit` 20/21 | Stages 2, 5, 7, 10, then 11 |
| Exact similarity | `app.Analyze`/`app.Publish`, `manifest.Load`/`LoadRun`, `manifest.Create`/`CreateRun`, adapter constructors, and Seriatim fake methods | Owning behavior stages, then Stage 11 |
| Test-heavy hotspot noise | Several test functions and fakes rank highly in transitive-depth and fan-in results | Stage 12; do not infer production risk from the metric |

### Automation And Fixture Inventory

- `.woodpecker/release.yml` is tag-only release automation. It cross-builds
  Linux, macOS, and Windows binaries with Go 1.25, then publishes release
  assets. It does not run tests, race tests, vet, or example validation.
- `examples/` contains 19 maintained files: pipeline, campaign, session,
  template, stable-input, and placeholder-audio fixtures. Configuration tests
  are documented as their validation owner.
- No fuzz tests, golden files, golden-update switches, opt-in/live test tags, or
  `go:generate` test mechanisms were found.
- Platform build constraints exist for the native no-replace directory tests
  and unsupported-platform fallback in `internal/fileops`.

## Execution Coverage Ledger

| Stage | Status | Evidence and result |
| --- | --- | --- |
| 0: baseline | complete | Revision/environment pinned; graph refreshed; inventories and every prescribed baseline command recorded. `TST-001` owns the non-blocking race limitation. |
| 1: contract and boundary map | complete | Canonical contracts and focused internal docs read; ownership, stage-contract, lifecycle, scenario, area, and preliminary risk-to-test matrices recorded below. |
| 2: runner and manifest | complete | Full/single-stage entry paths, every lifecycle outcome, both manifest models/transitions, save disagreement states, canonical invalidation boundaries, and runner lock lifetime reviewed. Focused app/manifest test and race commands passed. Confirmed `COR-001` and `RSK-001`; assigned `DUP-001`, `SIM-001`, `COM-001`, `TST-002`, and lock-release details to later stages. |
| 3: paths and filesystem | not_started | Assigned path, lock, artifact, and mutation questions below. |
| 4: publish and cleanup | not_started | Assigned remote commit and cleanup scenarios below. |
| 5: restore and previous state | not_started | Assigned restore and previous-cache scenarios below. |
| 6: configuration and composition | not_started | Assigned configuration, CLI composition, and process-boundary areas below. |
| 7: adapters and shared support | not_started | Assigned external-boundary and cancellation areas below. |
| 8: ordinary stages | not_started | Assigned prepare/transcript behavior and disabled-outcome questions below. |
| 9: extraction | not_started | Assigned extraction promotion, provenance, and resume scenario below. |
| 10: analyze and dependencies | not_started | Assigned artifact dependency/source and selection scenario below. |
| 11: maintainability | not_started | Seeded by graph complexity, similarity, and fan-in signals only. |
| 12: test policy | not_started | Seeded by intended owners and baseline execution observations. |
| 13: synthesis | not_started | No final ranking or accepted-risk decisions yet. |

## Area Coverage And Ownership

Every area in the audit plan has a primary execution owner. `assigned` means it
has been mapped but not behaviorally audited.

| Inspection area | Canonical implementation owner | Primary audit stage | Status |
| --- | --- | --- | --- |
| Process and application boundary | `cmd/narratio`, `internal/app` | 6 (runner lifecycle portions in 2; publish/restore portions in 4-5) | assigned |
| Stage registry and runner | `internal/stage`, `internal/app` | 2 | reviewed |
| Configuration | `internal/config` | 6 | assigned |
| Prepare and audio | `internal/stage`, `internal/audio`, `internal/previouscache` | 8 | assigned |
| Transcript stages | `internal/stage` plus tool adapters | 8 | assigned |
| Extraction | `internal/stage`, Notarius adapter, `internal/fileops` | 9 | assigned |
| Analyze and artifact dependencies | `internal/stage`, `internal/artifacts`, `internal/artifactpolicy` | 10 | assigned |
| Publish and cleanup | `internal/stage`, `internal/app` | 4 | assigned |
| Manifest state | `internal/manifest`, transition policy in `internal/app` | 2 | reviewed |
| Artifacts, paths, and policy | `internal/artifacts`, `internal/artifactpolicy`, `internal/pathsafe` | 3 (resolution consumption revisited in 10) | assigned |
| Restore | `internal/app`, `internal/artifacts`, `internal/previouscache`, `internal/audio` | 5 | assigned |
| File operations | `internal/fileops`, `internal/pathsafe`, local artifact store | 3 (promotion vertical slice in 9) | assigned |
| External adapters and storage | `internal/adapters`, `internal/audio` | 7 | assigned |
| Shared models and diagnostics | `internal/artifactmodel`, `internal/contracts`, `internal/logging` | 7 (maintainability revisited in 11) | assigned |
| Tests, examples, and automation | package test owners, `examples/`, `.woodpecker/` | 12 | assigned |

## Package And Interface Ownership Map

| Package | Owned contract or policy | Important boundaries | Audit owner |
| --- | --- | --- | --- |
| `cmd/narratio` | Process entry and exit; CLI delegates behavior to app | `main -> app.Execute` | 6 |
| `internal/app` | Command dispatch, composition, locking, planning, lifecycle, restore, cleanup, reporting | `Execute`, `executeStages`; consumes stage/artifact/manifest/adapter contracts | 2, 4-6 |
| `internal/config` | Strict discovery, defaults, resolve, template, and validation rules | Config models and load/resolve/validate functions | 6 |
| `internal/stage` | Canonical order and stage behavior | `Stage`, `ResumeValidator`, `Env`; adapter interfaces are injected | 2, 4, 8-10 |
| `internal/manifest` | Session/run models, transitions, validation, atomic persistence | `Store`; transition methods record but do not choose policy | 2 |
| `internal/artifacts` | Artifact identity/resolution, paths/keys, local store, remote current-state mechanics | `Store`; consumes explicit storage keys | 3, 5, 10 |
| `internal/artifactpolicy` | Configured source/destination identity and safety policy | Narrow validators used by config, artifacts, app, and stages | 3, 10 |
| `internal/artifactmodel` | Shared serialized artifact, contract, and provenance models | Data contract only | 3, 7 |
| `internal/pathsafe` | Confined relative path and destination mechanics | Narrow validation helpers; no stage policy | 3 |
| `internal/fileops` | Atomic files, copies, hashing, no-replace directory promotion | Filesystem mechanics receive explicit paths | 3, 9 |
| `internal/previouscache` | Deterministic previous-session requirement planning/materialization | Uses explicit object-store and artifact contracts | 5, 8, 10 |
| `internal/audio` | S3 audio spool/cache materialization | Uses `storage.ObjectStore`; no stage ordering | 5, 8 |
| `internal/contracts` | Bounds and shared JSON validation models | Data contract only | 7, 8 |
| `internal/logging` | Shared logger construction | `slog` composition | 7, 11 |
| `internal/adapters/whisperx` | WhisperX HTTP protocol | `Client` | 7 |
| `internal/adapters/seriatim` | Merge/normalize/trim/render subprocess protocol | `Runner` | 7 |
| `internal/adapters/audita` | Audita subprocess protocol | `Runner` | 7 |
| `internal/adapters/scriptorium` | Scriptorium run/render subprocess protocol | `Runner` | 7 |
| `internal/adapters/notarius` | Notarius invocation and receipt boundary | `Runner` | 7 (vertical behavior in 9) |
| `internal/adapters/notify` | Notification transport | `Sender` | 7 |
| `internal/adapters/storage` | Explicit bucket-relative object-store operations and S3 mechanics | `ObjectStore`; private `s3API` test seam | 7 |
| `internal/adapters/subprocess` | Shared bounded subprocess/config/log mechanics | Concrete helper package, not stage policy | 7 |

The graph reported no inbound production callers of `Stage.Declares`; text
search found definitions and test stubs but no production invocation. This
reduces the current impact of `ARC-001` but makes the interface's intended owner
and future use an explicit question rather than resolving the mismatch.

## Stage Contract Matrix

The table separates declared/static contracts from dynamic behavior. All
executed stages use the runner's session/run transitions. Unless noted, a
successful result records returned outputs, diagnostics, generated
configuration, and metadata; a different effective executed outcome can stale
succeeded downstream work, while force pre-stales succeeded downstream work.

| Order and stage | Inputs and outputs | Configuration and adapters | Skip/resume behavior | Materialization and manifest effects |
| --- | --- | --- | --- | --- |
| 1 `prepare` | Config, stable inputs, one audio mode, optional previous requirements -> canonical `inputs/**`, `audio/**`, optional `previous/**`, `manifest.inputs` | All resolved config; storage for S3/current previous state; audio/artifact/previous-cache services | No stage-specific resume validator or explicit self-skip | Writes canonical session inputs and deterministic input records; unlike processing stages, `Declares` labels produced canonical files as inputs. |
| 2 `transcribe` | Prepared FLAC files -> raw per-speaker JSON | WhisperX URL/language/retry/timeout/concurrency; `whisperx.Client` | Ordinary succeeded-record skip; no validator/self-skip | Bounded concurrent run-local writes, validation, then canonical transcript materialization. |
| 3 `merge` | Raw transcripts, speakers, autocorrect -> base transcript, optional report | Seriatim merge fields; `seriatim.Runner` | Ordinary succeeded-record skip | Normalized scratch inputs and run-local results validate before canonical transcript/report materialization. |
| 4 `polish` | Base transcript, glossary -> polished transcript, optional report | Audita fields/credential reference; `audita.Runner` | Ordinary succeeded-record skip | Run-local output, report, logs, and generated config; validates before canonical materialization. |
| 5 `normalize` | Polished transcript -> final transcript, optional report | Normalize plus Seriatim fields; `seriatim.Runner` | Ordinary succeeded-record skip | Manifest-first input; run-local validation then configurable canonical output/report. |
| 6 `trim` | Final transcript -> final-trimmed transcript and, when enabled, bounds | Trim, bounds, Scriptorium, and Seriatim fields; both runners when enabled | Disabled trim copies input and still succeeds; no explicit self-skip or resume validator | Run-local bounds/trim result validates then materializes; debug render is diagnostic, not output. |
| 7 `extract` | Final-trimmed source -> immutable index and configured lane outputs | Notarius executable/config/pipeline/timeout/output contracts; `notarius.Runner` | Disabled is explicit `notarius_disabled` self-skip; only current `ResumeValidator`; obsolete reruns, unsafe validation errors | Validates run-local receipt/bundle completely, promotes to unique immutable bundle, records checksums/contracts/provenance; identical repeated self-skip is stable. |
| 8 `render` | Final and final-trimmed JSON -> two Markdown transcripts | Render and Seriatim fields; `seriatim.Runner` | Disabled returns a zero-disposition result with skip metadata, therefore runner-level success rather than explicit self-skip; no validator | Run-local text validates non-empty before canonical materialization when enabled. |
| 9 `analyze` | Dynamic built-in, prepared, extraction, configured, and previous sources -> selected configured artifact outputs | Scriptorium artifact graph/selection; `scriptorium.Runner` | Missing config or no executable artifacts returns success with skip metadata; no validator | Topological run-local generation/reuse, validation, canonical outputs, deterministic metadata; static `Declares` omits dynamic outputs and several input families. |
| 10 `publish` | Session/run state, selected output rules, locks, previous cache -> remote run/output/current objects | Publish/storage/selection fields; `storage.ObjectStore` | Disabled publish or run upload returns success with skip metadata; force cannot bypass locks; no validator | Deterministic uploads; `current/manifest.json` before `current/run_id.txt`; commit metadata gates cleanup. Static prerequisites omit extract because disabled extraction is valid and lane resolution enforces required extraction state when selected. |
| 11 `notify` | No implemented persisted pipeline input/output | Optional `notify.Sender`; default no-op | Ordinary succeeded-record skip; no explicit self-skip or validator | Placeholder metadata and optional notification call; no returned output. `Declares` nevertheless advertises placeholder input/output paths. |

Configuration, adapters, skip policy, and dynamic outputs are not represented
by `IODecl`; their current canonical owners are the focused stage,
configuration, and integration contracts. Whether `IODecl` should remain a
partial display type or become an enforceable declaration is deferred as
`ARC-001`.

## Lifecycle Matrix

This began as the intended contract map and is now source-backed for both
durable ledgers by the Stage 2 review.

| Outcome | Session manifest intent | Invocation manifest intent | Downstream and next-invocation intent |
| --- | --- | --- | --- |
| First run | Pending/non-succeeded stage becomes running, then succeeded/failed/skipped; executing clears older result payload first | New run record; action `run`; terminal status records this invocation | Success enables later stages; failure stops current execution and an effective outcome change may stale succeeded downstream records. |
| Already-succeeded skip | Existing succeeded session record and payload remain unchanged, subject to resume validation | Action/status record a skip and stable reason for this invocation | Reusable result remains authoritative; pipeline continues. |
| Explicit self-skip | Session stage becomes skipped, clears older result payload, and may record bounded current skip details | Action was `run`, outcome is skipped with reason | Reconsidered later; a changed effective upstream outcome stales succeeded downstream work; identical extraction disabled skip is stable. |
| Failure | Current stage becomes failed with error; current output/log/config/metadata payload is cleared | Action `run`, failed outcome and overall failed run | Current execution stops; affected succeeded downstream work is intended to stale; later invocation reruns non-succeeded stages. |
| Interruption | Model admits `interrupted`, but production never writes it; process death leaves the last durable status `running` and the running transition has already cleared the target's prior result details | The run remains non-terminal at its last durable per-stage state; no load or startup reconciliation changes it | Non-succeeded session stages execute on the next included plan, so continuation is conservative; the old invocation record remains inaccurate under confirmed `RSK-001`. |
| Forced replacement | Target execution starts fresh; succeeded downstream records are pre-marked stale; current target payload clears on running | Force flag and `run` action recorded | Replacement result determines later execution; locks and safety policy remain authoritative. |
| Non-resumable success | Prior success becomes stale while retaining details long enough for diagnosis/validation, then running clears them | Current invocation records execution after validation rejects skip | Obsolete result reruns; unsafe inability to decide stops without silently replacing current success. |
| Successful rerun | Target becomes succeeded with only new outputs/diagnostics/config/metadata | Current invocation records its own new success; earlier run manifests remain unchanged | A rerun after a non-succeeded state stales succeeded downstream work; force already stales it before execution. The runner does not compare output contents; identical repeated self-skip is the narrow no-invalidation case. |

Stage 2 verified the matrix. The runner treats the session manifest as the only
cross-invocation decision source and each run manifest as a record of one
invocation. The resulting field behavior is:

- entering `running` clears the session stage's former outputs, logs, generated
  configuration, metadata, completion, and error; success installs only the
  current result and clears the stage error, while failure and self-skip clear
  result data before bounded current skip diagnostics are reapplied;
- staling deliberately retains prior result data and timestamps for diagnosis,
  changes status/error/updated time, and prevents the result from being reused;
- an already-succeeded skip does not mutate the session record; the run record
  separately stores action `skip`, status `skipped`, and reason
  `already_succeeded` without copying the reusable outputs;
- an executed self-skip stores action `run` and status `skipped` in the run
  record, so it remains distinguishable from an idempotent skip;
- a stage failure marks the session stage and run stage failed, records the
  error in both ledgers, makes the run overall failed, and stops execution;
- force is stored at run level and pre-stales all succeeded canonical
  downstream stages; non-resumable validation first stales and saves the target
  and succeeded downstream stages, then executes; and a successful execution
  following any non-succeeded prior state stales remaining succeeded downstream
  work; and
- the session-level `last_error` is retained as historical information after a
  later success. No production reader treats it as current status; stage and
  run status are the operative fields.

The invalidation helper derives position from the complete canonical registry,
not the selected plan. Consequently a single-stage replacement has the same
downstream effect as that stage in a full run. `prepare` can invalidate every
later succeeded stage and `notify` has no downstream target. Only succeeded
records need explicit staling: failed, skipped, stale, pending, running, and
interrupted records already execute on the next included plan.

### Runner Entry, Lock, And Persistence Conclusions

`Run` validates the assembled configuration and selection, builds the full
canonical plan, and delegates to `executeStages`. `RunStage`, `Analyze`, and
`Publish` select one canonical stage; the latter two force it. Single-stage
execution still uses the same lifecycle, session lock, invalidation, dual
manifests, cleanup check, and final run transition as a full run.

The session lock is acquired after layout creation and before the session
manifest is loaded, then held through stage execution, all manifest saves,
post-publish cleanup, and the final run save. A competing same-session runner
therefore cannot enter manifest decision-making while the first holds the lock.
The deferred release error is discarded. Whether close/unlink failures can
leave a blocking or misleading lock requires the filesystem implementation
review assigned to Stage 3; the assembled runner suite has no concurrent-runner
or release-failure case.

Both manifest stores use temp-file write, file sync, close, and same-directory
rename, so an error before rename leaves the prior individual file in place.
There is no atomic transaction or reconciliation protocol across the two
manifest files. The runner saves the run record first when
announcing execution, then saves the session record; for terminal outcomes it
saves the session authority first, then the run audit. The possible durable
states and their later interpretation are:

| Failure boundary | Durable state | Later invocation behavior |
| --- | --- | --- |
| New session or identity save fails before initial run save | No run record; session is absent or remains at its prior contents. An identity-save attempt mutates the in-memory identity and `updated_at`, but none of it becomes durable. | The command stops before a stage. A later invocation loads/creates from the last durable session state. |
| Initial run save fails after session identity save | Session points at the new run ID, but that run's audit file may not exist. | Session stage states still govern reuse; a later invocation creates a different run ID. |
| Resume validation reports unsafe/indeterminate | Session success is preserved, but the already-created run remains overall `running`. | The prior success remains authoritative and validation is attempted again; the abandoned run is never reconciled. |
| Saving non-resumable staleness fails | Run remains initially `running`; session remains at the prior success. No stage executes. | Validation is attempted again without silently replacing the prior success. |
| Saving an ordinary skip to the run file fails | Session remains succeeded; the run file remains at its preceding state. | The stage is safely reconsidered as another skip. |
| Run `running` save fails | Session is unchanged and the stage does not execute. | Session authority makes the next decision conservatively. |
| Session `running` save fails after the run save | Run stage is `running`; session remains at its prior state and the stage does not execute. Forced downstream staleness is not durable. | A non-succeeded target retries; a prior success skips unless force/resume validation again requires replacement. |
| Terminal session save fails after stage work | Both durable records remain `running`, although the stage may already have external or canonical effects. | The session stage reruns because `running` is not reusable. Stage-owned idempotency remains essential. |
| Terminal run save fails after terminal session save | Session has the authoritative success, skip, failure, and downstream state; run stays `running`. | Execution resumes safely from the session, but the historical run remains inaccurate. |
| Post-publish cleanup fails | Session stage outcomes remain terminal; a successful run save marks the invocation failed, while a failed run save leaves its prior overall `running` state. | A later invocation decides stages from the session and re-enters the cleanup gate; Stage 4 owns whether that retry is safe for every cleanup state. |
| Final overall run save fails | Session and per-stage run records are terminal, but overall run status remains `running`. | A later invocation skips or reruns from session state and does not repair the old run. |

Save errors are returned with both the stage error and persistence error when
both exist. The session store is injectable, but run persistence is a concrete
`LocalStore` outside the `manifest.Store` interface. This leaves the run-side
failure rows above unexercised by focused runner tests and makes centralized
terminalization/reconciliation harder to test.

### Lifecycle Scenario Conclusions

- Scenario 1 is functionally safe for reuse: a non-resumable success and its
  succeeded downstream records are persisted stale before execution; a failed
  rerun leaves the target failed and downstream stale; an ordinary retry runs
  both. An inability to validate preserves the prior success rather than
  replacing it. `RSK-001` records the inaccurate invocation audit left by that
  controlled error.
- Scenario 2 is conservative and source-backed: force pre-stales succeeded
  downstream work; failure and a changed effective outcome stale it; a changed
  self-skip stales it; and an identical repeated self-skip does not. Here
  identical means prior status skipped, zero outputs, and the same reason;
  diagnostic/metadata differences are not compared. Disabled stages represented
  as success remain reusable success, while an explicitly skipped downstream
  stage is naturally reconsidered because only success is ever skipped. The
  runner-level distinction is coherent; `ARC-002` remains assigned to Stages 4
  and 8 for the stage-specific contract and wording.
- The lock portion of Scenario 10 is resolved at the application boundary:
  acquisition occurs before manifest access and the lock spans the entire
  mutation lifetime. Stage 3 must decide the ignored-release and underlying
  lock-file questions.

## Cross-Boundary Scenario Assignments

| Scenario | Primary audit stage | Supporting packages and focused tests |
| --- | --- | --- |
| 1. Success becomes non-resumable, rerun fails, later reuse decision | 2 | `internal/app`, `internal/manifest`, `stage.ResumeValidator`; `runner_test.go`, `extract_lifecycle_test.go`, manifest transition tests |
| 2. Forced/changed upstream outcome with succeeded, self-skipped, disabled downstream | 2 | `internal/app`, `internal/stage`, `internal/manifest`; run-control, runner, extraction-lifecycle tests; disabled-stage detail revisited in 8 |
| 3. Extraction bundle followed by configuration/transitive-input change | 9 | Extract/resume, Notarius adapter, artifacts/fileops tests; downstream resolution revisited in 10 |
| 4. Published/restored/prepared previous state consumed locally by analyze | 5 | `internal/app`, `internal/previouscache`, `internal/audio`, `internal/artifacts`; restore/prepare tests; analyze consumption revisited in 10 |
| 5. Publish failure at every upload boundary, then status/restore/retry | 4 | Publish stage, storage fake/adapter, app status/restore; publish and operator-helper tests; restore interpretation revisited in 5 |
| 6. Restore identical/conflict/unsafe/cache/pre-manifest-install cases | 5 | Restore discovery/plan/execute/report, artifacts, previouscache, audio; restore test suite |
| 7. Cleanup after skipped/failed/locked/partial/committed publish | 4 | Publish metadata, post-publish cleanup, cleanup targets, pathsafe; publish/cleanup tests |
| 8. Cancellation through workers, HTTP, subprocess, storage, manifests | 7 | Adapter and subprocess tests; transcribe/stage tests in 8; runner reporting in 2 |
| 9. Disabled/unselected/reused/generated/extraction/previous source then publish filtering | 10 | Analyze, artifact catalog/resolver/policy, publish tests; config ownership in 6 and publish result in 4 |
| 10. Concurrent same-session invocation and lock cleanup failures | 3 | Runner lock lifetime in 2; local artifact store, path/file cleanup and lock tests in 3 |

## Preliminary Risk-To-Test Matrix

This matrix identifies intended owners only. It makes no sufficiency judgment.

| Architectural invariant or risk | Implementation owner | Intended test owner |
| --- | --- | --- |
| One deterministic canonical stage order | `internal/stage`, planner in `internal/app` | `internal/app/planner_test.go`, narrow registry tests |
| Session manifest is cross-invocation authority; run manifest is immutable invocation audit | `internal/app`, `internal/manifest` | Manifest transition tests plus assembled runner/run-stage tests |
| First run, skip, self-skip, failure, force, invalidation, and rerun transitions | `internal/app`, `internal/manifest` | App lifecycle tests as primary; manifest helpers own field mutation |
| Obsolete versus unsafe resume validation | Stage-specific `ResumeValidator`, runner | Extract resume tests plus runner integration tests |
| Run-local validation before canonical materialization | Individual stages and `run_local.go` | Focused stage package behavioral tests; fileops owns atomic mechanism |
| Strict config, defaults, identity, and cross-field validation | `internal/config` | Config package tests; example load/validation test samples assembly |
| Canonical path/key ownership and traversal confinement | Artifacts, artifactpolicy, pathsafe | Owning package tests; app/stage tests only for assembled policy |
| Immutable extraction promotion and provenance/checksum validation | Extract, fileops, artifacts, Notarius adapter | Fileops mechanism, extract behavior, artifact hydration, adapter contract tests |
| Deterministic artifact dependency and source resolution | Artifacts, artifactpolicy, analyze | Artifact/package tests and analyze package behavior tests |
| Previous-session consumption remains local in analyze | Previouscache/prepare/artifacts/analyze | Previouscache and prepare tests; one analyze boundary test for no remote call |
| Remote current pointer is publish's final commit point | Publish stage | Publish tests with stateful object-store fake; storage tests own transport only |
| Restore is confined, deterministic, conflict-safe, and installs manifest last | Restore app modules, artifacts/previouscache/audio | Restore plan/execution/workflow tests plus low-level path/file tests |
| Cleanup requires explicit scope and committed publish metadata | App cleanup modules, pathsafe | Cleanup-target and post-publish integration tests |
| Session single-writer lock and safe release | Local artifact store, app lifetime | Artifact local-store tests plus assembled concurrent runner tests |
| Adapter cancellation, error adaptation, and resource closure | Each adapter and shared subprocess package | Focused adapter boundary tests; stage tests sample propagation |
| Bounded deterministic transcription concurrency | Transcribe stage and WhisperX client | Stage concurrency/result-order tests; HTTP adapter retry/cancel tests |
| Secrets never persist or appear in diagnostics | Config/app composition and each adapter/logging boundary | Owning config/adapter tests plus selected assembled redaction checks |
| Default suite remains deterministic, offline, and credential-free | Every package; automation | Stage 12 repository-wide execution and test-policy audit |

Stage 2 test observations for this matrix:

| Risk | Existing focused protection | Gap or disposition |
| --- | --- | --- |
| Normal lifecycle and payload clearing | Manifest helper tests plus runner/run-stage/extraction-lifecycle tests cover first success, existing-success skip, force, failure, self-skip, repeated self-skip, unsafe and obsolete resume validation, retry, and canonical downstream invalidation. | Strong behavior coverage for successful persistence; no finding. |
| Session/run invocation identity | Per-invocation runner test asserts distinct run IDs, manifest paths, and the latest session `run_id`. | It does not assert refreshed local/spool/remote derived fields or reject loaded identity conflicts; required by `COR-001`. |
| Partial persistence and handled pre-stage errors | Session manifest is injectable and the unsafe-resume test proves old success is preserved. | Run persistence is concrete; no disagreement-boundary tests and no terminal run assertion on resume error; candidate `TST-002`. |
| Interruption and restart | Non-succeeded action logic and retry tests indirectly prove `running` is rerunnable. | No kill/reload normalization, reconciliation, or abandoned-run status test; confirmed `RSK-001`. |
| Same-session concurrency | Artifact store has focused lock tests. | No assembled concurrent runner or release-failure test; Stage 3 owns the mechanism and sufficiency decision. |

## Confirmed Findings

### `COR-001`: session identity initialization preserves stale invocation paths and accepts conflicting identity

- Category: confirmed correctness defect.
- Locations/invariant: `internal/app/runner.go` in `ensureManifestIdentity` and
  `syncRunManifestIdentityFromSession`; consumers include prepare's work/spool
  resolution, publish's run prefix, and post-publish cleanup. The session and
  invocation manifests must describe one internally consistent campaign,
  session, and run.
- Evidence: every invocation replaces `Manifest.RunID`, but
  `LocalWorkDir`, `LocalSpoolDir`, and `S3RunPrefix` are computed only when
  empty. A second invocation therefore records run B while retaining paths and
  the remote prefix derived from run A, and copies those stale values into run
  B's manifest. The same helper fills an empty campaign but neither rejects nor
  reconciles a loaded campaign/session that conflicts with the configured
  manifest path. `TestExecuteStagesCreatesRunManifestPerInvocation` proves IDs
  and run-manifest paths differ but does not assert the dependent identities.
- Realistic scenario: a forced second prepare writes through run A's work/spool
  identity; a forced second publish can target run A's remote prefix while its
  manifests claim run B. A misplaced or incorrectly restored manifest can also
  make the runner hold session A's lock while stages derive paths from the
  manifest's session B identity.
- Impact/likelihood/confidence: high integrity impact; stale derived identity
  occurs on every ordinary second invocation after the fields are initialized,
  while a conflicting loaded identity is less common; high confidence from the
  assignment guards and direct consumers.
- Estimated remediation scope and owner: small-to-medium application/manifest
  change. Define whether run-scoped locations belong in the session manifest,
  recompute them as one identity unit whenever the run changes, and reject
  configured/persisted campaign or session conflicts before stage execution.
- Test changes: extend the existing per-invocation test to load both manifests
  and assert every run-derived field against run B; add a loaded-identity
  mismatch test that proves no stage or cross-session path is touched. Stages 3
  and 4 should add the path and remote-prefix boundary assertions after their
  focused review.
- Dependencies: Stage 3 owns exact path confinement consequences, Stage 4 owns
  publish/cleanup impact, Stage 5 owns restored-manifest provenance, and Stage
  6 owns configuration identity validation. They should reference this root
  finding rather than create duplicates.

### `RSK-001`: invocation audit records can remain indefinitely `running`

- Category: confirmed correctness/operational risk.
- Locations/invariant: `internal/app/runner.go` in `executeStages`,
  `internal/manifest/store.go` normalization, and the unused production
  `StatusInterrupted` model value. Every completed or handled invocation should
  have an intelligible terminal audit outcome, while process interruption must
  remain safely resumable.
- Evidence: the initial run manifest is saved with overall status `running`.
  A resume-validator error returns directly without marking it failed; terminal
  session-save and run-save failures leave the last run state running; and a
  process death after either running save has the same effect. Neither load
  normalizer converts running records to interrupted, and later invocations
  consult only the session manifest and never reconcile older run manifests.
  `StatusInterrupted` has no production writer. The existing resume-validation
  error test checks preservation of the session success but not the run record.
- Realistic scenario: extraction resume validation encounters an unsafe or
  unreadable receipt. The command returns a controlled error, the reusable
  session result is correctly preserved, and the run audit file remains
  `running` forever. A kill or persistence failure can leave analogous dual-
  ledger disagreement.
- Impact/likelihood/confidence: medium operator/audit impact and low risk of
  unsafe reuse because non-succeeded session stages rerun; moderate likelihood
  over the life of a long-running pipeline; high confidence.
- Estimated remediation scope and owner: medium application/manifest change.
  Terminalize handled post-creation errors when persistence is available and
  define an explicit startup/status reconciliation policy for abandoned
  running records. Preserve the current conservative session-authority rule.
- Test changes: extend the resume-validation error integration test to assert a
  terminal failed run; add interruption/restart and injectable session/run-save
  boundary cases. Filesystem crash durability itself remains a Stage 3 concern.
- Dependencies: `SIM-001` may provide one failure-finalization path and
  `TST-002` records the missing persistence seam. Stage 5 should check how
  status/restore presents abandoned runs; Stage 13 should decide whether true
  process interruption is accepted risk after handled errors are fixed.

## Candidate Register

The remaining candidates require inspection by their named owners. Stage 2
promoted `COR-001` and `RSK-001` into the confirmed register above.

### `ARC-001`: `IODecl` is not a complete or consistently classified stage contract

- Category: architectural boundary/ownership candidate.
- Evidence: `prepare.Declares` lists files it produces under `Inputs`;
  `analyze.Declares` omits dynamic input families and has no outputs;
  `publish.Declares` exposes only the manifest; and `notify.Declares` advertises
  placeholder paths although its result has no persisted output. No production
  caller of `Declares` was found.
- Contract tension: architecture says every stage declares required inputs,
  produced output state, configuration, adapters, lifecycle, and failure
  behavior; the Go interface declares only partial static artifacts.
- Realistic risk: a future planner, validator, or operator view could treat the
  interface as authoritative and make incorrect dependency or readiness
  decisions. Current likelihood appears low because the method has no
  production caller.
- Confirmation owners: Stages 8-10 for dynamic contracts, then Stage 11 for
  interface purpose/simplification. Smallest plausible outcome may be clearer
  naming/documentation, a complete contract, or removal; do not choose yet.

### `ARC-002`: disabled-stage “skip” terminology spans two different durable outcomes

- Category: architectural/lifecycle ownership candidate.
- Evidence: production use of `StageDispositionSkipped` was found only in
  extraction. Disabled render, absent/no-op analyze, and disabled publish return
  zero-disposition results with skip metadata, which the runner treats as
  success. Focused and operator docs use “skip” for several of these cases,
  while manifest docs reserve self-skip for a durable skipped state.
- Realistic risk: maintainers or operator features may assume all disabled
  outcomes clear state, are reconsidered, and invalidate downstream work in the
  same way. Conversely, changing them to explicit self-skip could break valid
  pipeline continuation or cleanup semantics.
- Confirmation owners: Stage 2 for runner truth table, Stage 4 for publish and
  cleanup, Stage 8 for ordinary disabled stages. Treat wording and behavior as
  unresolved until those flows are traced. Stage 2 confirmed that the two
  outcomes are deliberate and internally distinguishable at runner level.

### `TST-001`: full race baseline fails in the concurrent transcribe test

- Category: test-suite execution candidate.
- Evidence: the race detector reported concurrent slice access in
  `internal/adapters/whisperx/fake.go:45` from transcribe workers in
  `TestTranscribeStageTranscribesPreparedAudio`.
- Observed impact: the canonical full race command exits nonzero, weakening its
  signal for other packages. The report currently points to a test fake, not a
  production data race.
- Confirmation owners: Stage 8 should inspect the worker/fake contract; Stage
  12 should classify suite impact and the smallest durable fix. Do not change
  the fake during this investigative stage.

### `TST-002`: runner tests cannot exercise invocation-manifest save failures

- Category: test-suite sufficiency candidate.
- Evidence: `Env.ManifestStore` injects only session `Create`, `Load`, and
  `Save`; `executeStages` constructs a concrete `manifest.LocalStore` for run
  creation and every `SaveRun`. Focused tests cover normal and stage-failure
  transitions but no save disagreement row. The existing resume-validation
  error test also omits the surviving run status.
- Realistic risk: future ordering or error-path changes can advertise a handled
  invocation as running, lose the audit half of a terminal transition, or
  weaken conservative retry behavior without an assembled test failing.
- Confirmation owner: Stage 12 should decide the smallest persistence seam and
  representative boundary cases; avoid exhaustive choreography tests for every
  mechanically identical save call.

### `DUP-001`: session save duplicates the shared atomic JSON writer

- Category: duplicated mechanism candidate.
- Evidence: `LocalStore.Save` contains its own temp/create/write/sync/close/
  context-check/rename sequence, while `SaveRun` delegates the same mechanism
  to `writeJSONAtomically`. Error prefixes differ, but the durability mechanism
  is otherwise repeated.
- Realistic risk: a future durability, cleanup, permission, or platform fix may
  reach only one manifest type, creating different guarantees for the two
  ledgers.
- Confirmation owners: Stage 3 should compare filesystem guarantees and Stage
  11 should decide whether sharing the helper preserves useful error context.

### `SIM-001`: runner terminalization and persistence ordering lack a narrow owner

- Category: simplification candidate.
- Evidence: `executeStages` is 274 lines with cyclomatic complexity 54 and
  cognitive complexity 96. Much of the length is justified visible state-
  machine ordering, but session-first terminal save, run-first running save,
  result mapping, identity sync, and compound error handling are repeated
  inline. The resume-validation return bypasses run terminalization.
- Realistic risk: adding another pre-stage or terminal error path can repeat the
  abandoned-run behavior in `RSK-001`; extracting too broadly could instead
  hide the critical order.
- Confirmation owner: Stage 11 should consider a small terminal failure helper
  or typed transition operation only after Stages 3-10 settle ordering needs.

### `COM-001`: dual-ledger save order and partial-failure policy lack rationale

- Category: comment/clarity candidate.
- Evidence: the runner visibly saves run-before-session for `running` and
  session-before-run for terminal outcomes, but no local comment explains which
  file is authoritative, why the order differs, or how partial state is meant
  to be interpreted.
- Realistic risk: a maintainer may make the calls symmetrical or reorder them,
  inadvertently allowing a stage to execute without a durable running session
  transition or preferring an audit record over resume authority.
- Confirmation owner: Stage 11, after any `SIM-001` restructuring. Prefer a
  named operation that makes the invariant obvious; add a concise rationale
  only where code structure cannot.

## Candidate Classification Log

| Candidate signal | Classification | Reason |
| --- | --- | --- |
| Graph rollups `stage -> app`, `adapters -> app`, `config -> app` | rejected as a production reversal at Stage 1 | `go list` production imports contain no lower-level import of `internal/app`; graph connections include tests and ambiguous package grouping. Reopen only with a concrete production edge. |
| Similar wrapper/manifest/adapter functions | deferred metric signals, not findings | Similarity alone does not establish duplicated policy; owning behavior stages must first establish contracts. |
| Coverage percentages | deferred diagnostic signals, not findings | Stage 12 must reason from risk and test ownership, not a numeric target. |
| Session `last_error` survives a later stage success | rejected as a current-state defect at Stage 2 | No production reader was found; current status and per-stage error are authoritative, so the field can serve as historical context. Reopen only if an operator surface treats it as the active error. |
| Minimal loaded-manifest status/timestamp validation | rejected as a standalone Stage 2 finding | Unknown/non-succeeded statuses fail conservatively into execution, nil maps/records are normalized, and no realistic unsafe caller was established. Configured-versus-persisted identity conflict is separately confirmed in `COR-001`. |
| Ignored runner lock-release error | assigned to Stage 3 | The application discards the error, but whether close/unlink failure preserves an OS lock or merely a harmless lock file depends on the local-store implementation and platform semantics. |
| Two durable meanings of “skip” | runner portion confirmed, stage-contract conclusion deferred | Run action/status distinguishes idempotent skip from executed self-skip. Stages 4 and 8 must determine whether successful disabled outcomes and their wording are intentional. |

## Unresolved Questions And Follow-Up

- Should startup/status reconcile abandoned `running` invocation records, mark
  them interrupted, or retain them as an explicitly accepted audit limitation?
- Do Stage 3 path mechanics and Stage 4 publish/cleanup behavior confirm every
  concrete consequence of the stale run-derived fields in `COR-001`?
- Can any `ReleaseSessionLock` error retain exclusion or make a subsequent
  acquisition unsafe, and how should the runner surface such a deferred error?
- Are disabled render/analyze/publish outcomes intentionally successful so
  pipeline continuation and optional outputs work, and do all operator views
  describe that distinction accurately?
- Is `IODecl` intended only for display/tests, or should it own enforceable
  dependency declarations?
- Does publish's omission of extract from its static prerequisite list combine
  safely with every configured extraction output rule and disabled extraction?
- Which native CI runner limitations explain the absence of validation jobs in
  the tag-only release workflow? Stage 12 owns the automation conclusion.

No accepted risks or final audit conclusions are recorded yet.

## Completed-Stage Evidence

### Stage 0

- Contracts and records: development guide, audit plan and sequence, all policy
  documents, repository/branch/toolchain state.
- Graph evidence: refreshed moderate index at exact HEAD; architecture,
  interface, complexity, similarity, fan-in, and `Execute` call trace queries.
- Commands: every baseline command listed above; Go/package/file/test and
  automation inventories.
- Candidates: `TST-001`; metric signals assigned to later owners.
- Explicit no-finding conclusion: no production dependency reversal into
  `internal/app` was found in the package import inventory.
- Limitation disposition: the graph excludes the executable entry point, which
  was verified directly; the race failure is owned by Stages 8 and 12 and does
  not prevent read-only audit work.

### Stage 1

- Contracts reviewed: architecture, testing and documentation policy; internal
  overview and every focused internal document; CLI, configuration,
  operations, and every integration contract.
- Code/evidence reviewed: canonical registry and stage declarations; all
  modeled interfaces; production import graph; application dispatch trace;
  explicit self-skip usages; interrupted-state usages; focused test ownership
  references.
- Outputs: package/interface ownership, area coverage, stage contract,
  lifecycle, cross-boundary scenario, and preliminary risk-to-test matrices.
- Candidates: `ARC-001`, `ARC-002`, `RSK-001`; no candidate was confirmed from
  mapping evidence alone.
- Explicit no-finding conclusion: the canonical stage order agrees across the
  registry, internal overview, CLI, and operations contract.
- Follow-up: all unresolved behavior has a named owner in Stages 2-12; every
  area and invariant has an implementation owner and intended test owner.

### Stage 2

- Contracts and code reviewed: planner and full/single-stage entry points;
  `executeStages`, run-control and identity helpers; session/run manifest
  models, creation, loading, validation, normalization, atomic persistence, and
  every transition method; runner lock lifetime; focused internal manifest
  documentation and Stage 1 matrices.
- Graph/source evidence: call traces into full and selected execution; all
  identity-field consumers; manifest transition/save callers; status and
  `last_error` usages; runner complexity and atomic-save similarity; complete
  focused test-function inventory.
- Validation: `go test -count=1 ./internal/app ./internal/manifest` passed
  (`internal/app` 0.708 s, `internal/manifest` 0.010 s; 1.60 s command wall
  time). `go test -race -count=1 ./internal/app ./internal/manifest` passed
  (`internal/app` 45.842 s, `internal/manifest` 1.026 s).
- Conclusions: every lifecycle cell and dual-save boundary is recorded above;
  scenarios 1 and 2 are resolved at runner level; lock acquisition/lifetime is
  resolved and release mechanics assigned to Stage 3. Confirmed `COR-001` and
  `RSK-001`; added `DUP-001`, `SIM-001`, `COM-001`, and `TST-002` for named
  later owners.
- Explicit no-finding conclusions: canonical invalidation works at both first
  and last stage and is independent of selected-plan width; stale transitions
  intentionally retain diagnosis data while running/failure/skip clear it;
  session authority makes all enumerated disagreement states retry or reuse
  conservatively; the runner's two skip forms are durably distinguishable.