Prepare a staged implementation plan to address the audit findings.

docs/roadmap/audit.md

@@ -0,0 +1,104 @@
+# Implementation Plan Summary
+
+This is a concise, plain-language summary of
+[`implementation.md`](implementation.md). It describes the intended real-world
+outcome of each stage without reproducing its implementation details.
+
+1. **Stage 1 — Collaborative workspace permissions:** Treat ordinary Narratio and
+   Notarius data as shareable and make managed workspaces group-writable, while
+   retaining private handling for API keys.
+2. **Stage 2 — Safe identifiers:** Reject campaign, session, run, artifact, and
+   source identifiers that could escape their intended filesystem namespace, and
+   use fuzz tests to cover platform-specific path tricks.
+3. **Stage 3 — Durable file replacement:** Consolidate duplicated atomic-write
+   functions into one shared mechanism that fully persists a replacement before
+   reporting success.
+4. **Stage 4 — Confined writes and downloads:** Rewrite destination mutations so
+   symlinks or concurrent directory replacement cannot redirect writes,
+   promotions, or downloads outside the intended root.
+5. **Stage 5 — Safe deletion and crash-recoverable locks:** Confine recursive
+   cleanup to its authorized root and replace stale lock-file existence checks
+   with operating-system locks released automatically after process death.
+6. **Stage 6 — Protected API-key reads:** Read API keys only from private,
+   bounded, regular files without following symlinks or exposing key material in
+   errors.
+7. **Stage 7 — Bounded external results:** Prevent external adapters from causing
+   memory or disk exhaustion by validating regular result files and enforcing
+   generous, clearly reported per-adapter size limits.
+8. **Stage 8 — Complete subprocess termination:** Ensure cancellation, timeout,
+   or a safety-limit failure terminates and reaps an external command's entire
+   process tree rather than only its parent process.
+9. **Stage 9 — Safe subprocess diagnostics:** Redact known credentials from
+   stdout/stderr, cap persisted diagnostics, and terminate runaway producers when
+   those caps are reached.
+10. **Stage 10 — Safe publish inputs:** Ensure publishing reads and uploads only
+    verified regular files declared within the selected run, even during
+    filesystem races.
+11. **Stage 11 — Consistent run identity:** Resolve one campaign/session/run
+    identity for an invocation, reject conflicting authorities, and prevent stale
+    identity fields from leaking into a later run.
+12. **Stage 12 — Reliable failure recording:** Consolidate terminal-failure
+    persistence so handled errors reliably update authoritative session state and
+    preserve any secondary persistence failures.
+13. **Stage 13 — Immutable remote-state model:** Define a versioned immutable
+    remote snapshot selected by a small pointer, while isolating old-format read
+    compatibility so it can be removed after migration.
+14. **Stage 14 — Transactional publication:** Upload and verify a complete
+    immutable snapshot before one final pointer change makes it current, using an
+    exact source-to-destination mapping instead of basename guesses.
+15. **Stage 15 — Safe remote locking and pagination:** Use provider-enforced
+    conditional writes so publishers cannot overwrite another owner's lock, and
+    fail instead of looping when object-store pagination stops making progress.
+16. **Stage 16 — Retryable cleanup:** Persist post-publication cleanup as a
+    durable obligation so interrupted or failed deletion is retried and never
+    mistaken for completed cleanup.
+17. **Stage 17 — Snapshot-consistent restore:** Make restore and status use one
+    selected immutable snapshot throughout the operation, and prevent `--force`
+    from overwriting unsafe directory or non-file conflicts.
+18. **Stage 18 — Race-safe, portable restore:** Serialize restore against runner
+    reuse, leave durable evidence of incomplete restores, and replace unsafe
+    producer-machine absolute paths with validated local references.
+19. **Stage 19 — Correct audio-cache reuse:** Reuse downloaded audio only when its
+    local bytes and recorded metadata match the selected remote object version.
+20. **Stage 20 — One previous-session resolver:** Give restore, prepare, run, and
+    dry-run one consistent view of required and optional previous-session inputs,
+    while avoiding ambiguous matches and duplicate downloads.
+21. **Stage 21 — Strict configuration:** Reject multiple YAML documents, invalid
+    durations, implicit storage backends, and unmet previous-session expectations,
+    while separating configuration tests by responsibility.
+22. **Stage 22 — Truthful product settings and temp-file ownership:** Remove
+    configuration fields that do nothing, reject unsupported notification
+    settings, and guarantee cleanup of remote-configuration temporary files.
+23. **Stage 23 — Streaming WhisperX transport:** Stream uploads instead of
+    buffering entire audio files, reject unsupported endpoint schemes, and make
+    retries, cancellation, fake-server recording, and race tests reliable.
+24. **Stage 24 — Correct prepare/transcribe transitions:** Prevent stale previous
+    data, cancelled or partial transcription work, and duplicate source identity
+    from being recorded as successful current output.
+25. **Stage 25 — Authoritative output paths:** Require adapters to honor the
+    stage-requested output destination and consolidate duplicate singleton
+    transcript resolution without confusing it with multi-source discovery.
+26. **Stage 26 — Shared extraction evidence:** Consolidate duplicated
+    extraction-bundle validation into one typed proof while allowing resume and
+    catalog consumers to apply their distinct policies.
+27. **Stage 27 — Transcript-aware extraction reuse:** Include the direct
+    transcript's identity in extraction freshness checks so changed input cannot
+    reuse stale structured artifacts.
+28. **Stage 28 — One effective artifact selection:** Resolve configured and
+    explicitly selected artifacts once, then use that same typed set for
+    prerequisites, extraction catalogs, analyze inputs, and execution planning.
+29. **Stage 29 — Predictable analyze planning:** Represent optional and required
+    analyze inputs explicitly, produce deterministic dependency errors, and give
+    operators correct remediation commands.
+30. **Stage 30 — Contract cleanup:** Remove dead or misleading interfaces and
+    helpers, move static Audita configuration to its proper owner, and correct
+    stale contract comments.
+31. **Stage 31 — Enforced automated validation:** Require tests, race checks, vet,
+    builds, and example validation for changes and releases, while consolidating
+    redundant broad tests without losing focused coverage.
+32. **Stage 32 — Documentation and closure:** Reconcile normative documentation
+    with the completed behavior and verify that every planned remediation has one
+    completed, traceable implementation stage.
+
+Every stage's purpose was readily determinable from the implementation plan; no
+stage required an uncertainty note.