narratio/docs/roadmap/implementation.md

# Audit Remediation Implementation Plan

## Purpose and status

This document is the executable roadmap for remediating the confirmed findings in
[`audit-findings.md`](audit-findings.md) and the concrete gaps found during the
post-implementation code review. It is written for a `gpt-5.6-terra` coding agent
that will implement exactly one pending stage per prompt, in order.

The audit is an immutable requirements and evidence ledger. Do not edit
`audit-findings.md` or reinterpret its accepted findings. Stages 1–32 completed
the original audit-remediation plan and are summarized below instead of retaining
their now-obsolete implementation instructions. The repository history and audit
remain the detailed evidence for that work.

Stages 33–35 address follow-up review findings in the completed implementation.
They are implementation gaps in the original remediation rather than new entries
in the immutable audit ledger. They do not require the implementing agent to read
the full audit or any audit line range.

## Stage status and completed summaries

| Stage | Outcome or pending work | Source | Status |
| ---: | --- | --- | --- |
| 1 | Aligned architecture policy and filesystem modes with collaborative, group-owned workspaces while preserving private API-key handling. | RSK-004 | Completed |
| 2 | Enforced portable safe-segment identifiers and added path/source fuzz coverage. | COR-002, TST-013 | Completed |
| 3 | Consolidated crash-durable atomic file replacement behind shared file-operation primitives. | RSK-002, DUP-001, DUP-005 | Completed |
| 4 | Added confined, no-follow destination and download/install operations. | COR-003, DUP-003, TST-003 | Completed |
| 5 | Confined recursive cleanup and replaced existence-based sentinel locks with OS-held locks. | RSK-003 | Completed |
| 6 | Made API-key acquisition private, bounded, regular-file-only, and no-follow. | RSK-010 | Completed |
| 7 | Bounded and verified externally produced adapter and stage result files. | RSK-013, TST-007 | Completed |
| 8 | Added owned subprocess-tree cancellation, timeout, and forced termination. | RSK-011 | Completed |
| 9 | Added streaming secret redaction and bounded subprocess diagnostic capture. | RSK-012 | Completed |
| 10 | Confined publish archive reads to validated workspace sources. | COR-005 | Completed |
| 11 | Established singular manifest and run identity ownership. | COR-001, TST-006 | Completed |
| 12 | Centralized handled terminal-failure persistence and removed competing failure paths. | RSK-001, TST-002, SIM-001, COM-001 | Completed |
| 13 | Introduced immutable remote commit manifests, a final current pointer, and an isolated removable legacy reader. | ARC-003 | Completed |
| 14 | Switched publishing to immutable commits, deterministic mappings, and a final pointer update. | COR-004, COR-011, DUP-002, TST-004 | Completed |
| 15 | Made remote locks generation-safe and rejected non-progressing storage pagination. | RSK-005, RSK-014 | Completed |
| 16 | Persisted retryable post-commit cleanup obligations. | COR-006, COR-007 | Completed |
| 17 | Bound restore and status to one verified committed snapshot and rejected conflicting state. | COR-008, COR-009, TST-005 | Completed |
| 18 | Serialized restore transitions, persisted interrupted-restore state, and made restored paths portable. | RSK-006, RSK-008 | Completed |
| 19 | Bound reusable audio cache entries to remote object identity. | RSK-007 | Completed |
| 20 | Unified previous-source readiness and eliminated duplicate transfers. | COR-010, EFF-001 | Completed |
| 21 | Tightened configuration parsing, validation, value domains, and test expectations. | COR-012–COR-015, TST-011, TST-014 | Completed |
| 22 | Made product configuration truthful and assigned lifecycle ownership for downloaded temporary files. | COR-024, RSK-009, ARC-004 | Completed |
| 23 | Streamed WhisperX uploads and made its transport bounded, retry-correct, and race-safe. | COR-016, EFF-002, TST-001 | Completed |
| 24 | Corrected prepare/transcribe transition, retry, and optional-output semantics. | COR-017–COR-019, TST-008 | Completed |
| 25 | Enforced authoritative output paths and shared singleton resolution. | ARC-006, DUP-006 | Completed |
| 26 | Centralized typed extraction-bundle evidence. | DUP-007 | Completed |
| 27 | Bound extraction reuse to direct transcript identity and explicit freshness evidence. | COR-020, TST-009 | Completed |
| 28 | Established one effective artifact set and deterministic catalog bootstrap behavior. | COR-022, ARC-007, DUP-008 | Completed |
| 29 | Made analyze input resolution typed, optional, actionable, and deterministic. | COR-021, COR-023, RSK-015, SIM-003, TST-010 | Completed |
| 30 | Removed misleading contracts and placed static Audita policy in adapter construction. | ARC-001, ARC-005, SIM-004, COM-003, COM-006 | Completed |
| 31 | Enforced repository-wide CI/release validation and streamlined redundant test matrices. | TST-012, TST-015 | Completed |
| 32 | Reconciled lifecycle/analyze documentation and closed the original audit traceability inventory. | COM-002, COM-005 | Completed |
| 33 | Confine diagnostic log destinations and eliminate pathname-based tail reads. | Follow-up review | Completed |
| 34 | Dispose of owned subprocess descendants after natural leader exit. | Follow-up review | Completed |
| 35 | Bound remote current-state and lock control-plane reads. | Follow-up review | Pending |

Completed stages must not be reimplemented wholesale. A pending stage may adjust
their code only where its stated remediation requires it.

## Governing decisions

The following decisions are settled requirements, not questions for the
implementing agent:

1. Ordinary Narratio and Notarius campaign/session data is deliberately
   shareable, not private or sensitive. Group-owned, group-writable workspaces are
   an operational requirement. API keys are the only sensitive data handled by
   these applications and must remain private.
2. On POSIX systems, Narratio-managed ordinary workspace directories and files
   should converge on setgid `02775` and `0664` respectively, inheriting the
   workspace's existing group. API-key directories and files must be `0700` and
   `0600`. Do not add ownership-changing behavior or assume Narratio may `chown`.
   Windows behavior must preserve the same collaboration/security intent using
   the platform's available guarantees and explicit operational guidance.
3. Remote current-state publication uses an immutable run-scoped commit manifest
   selected by one final pointer update. Readers may accept coherent legacy state,
   but all compatibility code must remain isolated behind a clearly named
   boundary, covered by dedicated tests, and carry an in-code removal comment.
   New writers must never produce the legacy format.
4. Explicit notification no-op is supported. Configured notification backends or
   recipients are rejected until a real provider exists.
5. External-data limits are runaway safeguards, not normal operating limits.
   Each limit must be a named, centrally discoverable constant in the package that
   owns the contract and at least an order of magnitude above expected ordinary
   data. Every limit error must identify the enforcing adapter or contract, the
   configured byte limit, and what exceeded it. Hard whole-disk protection remains
   an operations concern implemented with filesystem, service, container, or
   volume quotas rather than output-root polling.
6. Narratio owns the complete process group or job created for every external
   command. Leader completion does not transfer ownership of surviving
   descendants. `Run` must not return while an owned descendant can continue
   running, including when the leader exits successfully or closes its streams.
7. Diagnostic tails are derived only from content that passed through the
   streaming redactor. Diagnostic files use the same confined, no-follow mutation
   guarantees as other workspace destinations; a pathname must not be reopened to
   obtain an error tail after execution.
8. Remote current pointers, commit manifests, selected session manifests, and
   lock documents are bounded while being read. Object metadata may reject an
   oversized value early but cannot replace enforcement against the actual byte
   stream. Limits for these small control-plane contracts are separate from limits
   for intentionally large artifact payloads.
9. Retain every accepted-risk disposition in the audit. In particular, do not
   turn abrupt process-death detection into a distributed liveness system, add
   rollback of arbitrary external side effects, or introduce generic speculative
   abstractions rejected by the audit.
10. CI must run ordinary tests, the full race suite, vet, build, and example/docs
    checks on every change and release path; shuffled tests run on a schedule. Add
    native macOS/Windows jobs only when authoritative Woodpecker runner labels and
    usable runners are available. Do not invent labels. Cross-compilation is
    useful but does not count as native filesystem or process evidence.

## Instructions for every pending stage

For each implementation prompt, the coding agent must:

1. Read `docs/development.md`, then the current-behavior documents and source
   files named by that stage. Follow the task-specific reading guide in
   `docs/development.md`. Stages 33–35 do not require reading
   `audit-findings.md`; do not reread or modify the immutable audit ledger.
2. Inspect the current tree before editing. Earlier stages may have changed names
   and ownership boundaries. Use the repository knowledge graph first for code
   discovery and call tracing, then text search for documentation, string
   literals, configuration, and evidence the graph cannot supply.
3. Confirm the worktree state and preserve unrelated user changes. Do not rewrite
   or amend earlier commits unless explicitly instructed.
4. Implement the stage completely, including production code, focused regression
   tests, platform-specific implementations where applicable, current-behavior
   documentation, and removal of code made obsolete by the stage. Do not leave a
   second competing path or defer required tests to a later stage unless this plan
   explicitly says so.
5. Prefer typed, owner-specific contracts and existing package ownership. Keep
   policy at the owner and reusable mechanism in `internal/fileops`, storage, or
   the relevant adapter package. Do not create a generic abstraction solely
   because two call sites look similar.
6. Treat path, race, process-lifecycle, and size checks as production behavior.
   Validation followed by an unsafe pathname operation or unbounded read is not a
   completed fix. Unsupported safe behavior must fail closed with an actionable
   error.
7. Run focused tests while developing, then run at minimum:

   ```sh
   go test ./...
   go test -race ./...
   go vet ./...
   go build ./...
   go test ./internal/doccheck
   go test ./internal/config -run '^TestExamplesLoadAndValidate$'
   ```

   Run the platform build/test checks named by the stage. Do not require live
   cloud or third-party services.
8. Compare the final diff with the stage goal and exit criteria. Update only that
   stage's row in the status table from `Pending` to `Completed`, adding the
   implementing commit hash if the workflow supplies one. Do not mark a stage
   complete while a required check is failing or required behavior is missing.

## Stage 33 — Confine diagnostic log destinations and eliminate pathname-based tail reads

**Read first:** `docs/policy/architecture.md`, `docs/policy/testing.md`,
`docs/internal/adapters.md`, `docs/internal/workspace.md`, and the current
subprocess diagnostic and confined file-operation implementations and tests.

**Depends on:** Completed Stages 3, 4, and 9.

**Goal:** Prevent diagnostic log setup from following a replaceable leaf symlink
or mutating a file outside the intended workspace, and ensure error diagnostics
cannot be redirected to read unrelated or secret content after a command runs.

**Work:**

- Replace direct diagnostic `os.Create` use with the established confined,
  no-follow destination mechanism. Validate the leaf as part of the mutation,
  reject symlink and non-regular destinations, preserve group-workspace modes, and
  retain the platform-specific safety guarantees established by Stage 4. A prior
  ancestor check followed by an ordinary pathname create is not sufficient.
- Remove pathname reopening from diagnostic-tail construction. Retain a small,
  bounded per-stream tail from bytes that have already passed through streaming
  redaction, preferably in the diagnostic writer itself, and obtain failure
  diagnostics from that retained state after redaction has been flushed. Do not
  read the log path again in the error path.
- Preserve stdout/stderr file behavior, shared-path behavior, byte caps, split-
  chunk secret redaction, capture-limit signaling, and group collaboration modes.
  Do not create an unbounded in-memory copy of either stream.
- Keep API-key values out of persisted logs and every returned error even if a
  workspace peer renames or replaces a diagnostic pathname while the process is
  running.
- Remove obsolete pathname-tail helpers and update current-behavior documentation
  only if the existing documentation describes the replaced mechanism.

**Tests and exit criteria:** Add adversarial tests proving that an existing log
leaf symlink is rejected without truncating its target; a non-regular leaf is
rejected; pathname replacement after the log is opened cannot inject foreign
content into a returned error; and a known credential remains absent from files
and errors across split writes. Cover separate and shared stdout/stderr paths,
exact diagnostic caps, and cap-plus-one behavior. Run focused subprocess and
file-operation tests under `-race`, plus Linux, macOS, and Windows cross-builds for
affected packages. Native platform tests remain conditional on available runners.

**Status:** Completed.

## Stage 34 — Dispose of owned subprocess descendants after natural leader exit

**Read first:** `docs/policy/architecture.md`, `docs/policy/testing.md`,
`docs/internal/adapters.md`, the subprocess run/process-tree implementations for
Unix and Windows, and all process-tree test helpers.

**Depends on:** Completed Stage 8 and Stage 33.

**Goal:** Close the lifecycle gap in which `cmd.Wait` can complete before a
descendant in Narratio's process group or Windows job exits, allowing that
descendant to outlive `Run` after either a successful or failed leader exit.

**Work:**

- Route the normal `cmd.Wait` completion branch through bounded owned-tree
  disposal before `Run` returns. Apply the ownership rule for successful exits,
  non-zero exits, and `exec.ErrWaitDelay`, not only cancellation, timeout, or
  diagnostic-cap paths.
- On Unix, detect and gracefully terminate any remaining process-group members,
  wait only for the existing bounded grace period, then forcefully terminate
  survivors. Treat an already-empty group as success and avoid imposing the grace
  delay on ordinary commands with no descendants.
- On Windows, preserve job-object kill-on-close semantics and ensure natural
  leader completion closes/disposes the job before return. Keep handles and
  goroutines bounded on every exit path.
- Consolidate terminal cleanup so races among context cancellation, capture-limit
  signaling, and leader completion cannot skip disposal or produce unsafe double
  ownership. Preserve timeout/cancellation classification and join actionable
  cleanup failures without hiding the original command result.
- Treat a descendant that deliberately leaves the owned process group or job as
  outside this stage; do not build a system-wide process discovery mechanism.

**Tests and exit criteria:** Extend the real subprocess helper with cases where a
leader exits zero while a descendant (a) retains inherited streams and (b)
redirects or closes them, plus a non-zero leader case. Prove `Run` completes
within bounded time and no descendant reaches a delayed sentinel after return.
Retain cancellation, timeout, and capture-limit coverage and run the subprocess
suite repeatedly, shuffled, and under `-race`. Cross-build the affected packages
for Linux, macOS, and Windows; run native platform tests only where runners are
actually available.

**Status:** Completed.

## Stage 35 — Bound remote current-state and lock control-plane reads

**Read first:** `docs/policy/architecture.md`, `docs/policy/testing.md`,
`docs/internal/storage.md`, `docs/internal/artifacts.md`,
`docs/internal/command-restore.md`, the current-state commit reader, remote lock
loader, object-store contract and implementations, and their stateful fakes and
tests.

**Depends on:** Completed Stages 13–17.

**Goal:** Prevent corrupt, misconfigured, or hostile object storage from forcing
unbounded temporary-disk or memory consumption before small remote control-plane
objects can be parsed or verified.

**Work:**

- Inventory the new-protocol read paths for the mutable current pointer, immutable
  commit manifest, selected session manifest, and remote lock document. Include
  the isolated legacy current-state reader only where it accepts equivalent small
  control objects. Do not apply these limits to intentionally large published
  artifact payloads.
- Define generous, documented, centrally discoverable constants in the packages
  that own each control-plane contract. Use separate policy constants where the
  credible sizes differ; do not embed numeric limits at call sites or replace the
  owner policies with one unexplained global limit.
- Stream each object through an enforcing `limit+1` read before parsing or
  retaining it. Reject oversized metadata before transfer when available, but
  still enforce the limit against actual bytes because metadata can be missing,
  stale, or inaccurate. Avoid downloading these small objects unboundedly to a
  temporary file and then calling `os.ReadFile` or `io.ReadAll`.
- Preserve immutable commit checksum, declared-size, generation/ETag, identity,
  and pointer-selection validation. Ensure the metadata used for validation
  belongs to the opened object version; do not weaken coherence while removing
  the temporary download path.
- Every over-limit error must identify the responsible control-plane contract,
  object category, key or safe storage context, and configured byte limit without
  including credentials. Maintain cancellation and reader-close behavior on all
  exits.
- Factor a bounded storage-read mechanism only if it has a clear storage-layer
  invariant; retain the owner-specific constants and errors in the artifact and
  remote-lock owners.

**Tests and exit criteria:** Add exact-limit and limit-plus-one cases for each
object category, including inaccurate/absent size metadata, short reads,
cancellation, malformed JSON/YAML, checksum or generation mismatch, and readers
that verify they are closed. Prove oversized current-state downloads do not create
unbounded temporary files and oversized lock documents are rejected without
unbounded allocation. Retain coherent legacy-reader tests and stateful S3/fake
ordering and conditional-write tests. Run focused storage, artifacts, app, restore,
and publish tests under `-race`, followed by the complete repository validation.

**Status:** Completed.

## Finding traceability inventory

This inventory remains the closed traceability record for Stages 1–32. A pending
follow-up stage may strengthen the implementation of an original stage, but does
not change the immutable finding disposition or create a second audit finding.

| Finding(s) | Primary stage |
| --- | ---: |
| COR-001 | 11 |
| COR-002 | 2 |
| COR-003 | 4 |
| COR-004 | 14 |
| COR-005 | 10 |
| COR-006, COR-007 | 16 |
| COR-008, COR-009 | 17 |
| COR-010 | 20 |
| COR-011 | 14 |
| COR-012, COR-013, COR-014, COR-015 | 21 |
| COR-016 | 23 |
| COR-017, COR-018, COR-019 | 24 |
| COR-020 | 27 |
| COR-021, COR-023 | 29 |
| COR-022 | 28 |
| COR-024 | 22 |
| RSK-001 | 12 |
| RSK-002 | 3 |
| RSK-003 | 5 |
| RSK-004 | 1 |
| RSK-005 | 15 |
| RSK-006, RSK-008 | 18 |
| RSK-007 | 19 |
| RSK-009 | 22 |
| RSK-010 | 6 |
| RSK-011 | 8 |
| RSK-012 | 9 |
| RSK-013 | 7 |
| RSK-014 | 15 |
| RSK-015 | 29 |
| EFF-001 | 20 |
| EFF-002 | 23 |
| ARC-001 | 30 |
| ARC-003 | 13 |
| ARC-004 | 22 |
| ARC-005 | 30 |
| ARC-006 | 25 |
| ARC-007 | 28 |
| TST-001 | 23 |
| TST-002 | 12 |
| TST-003 | 4 |
| TST-004 | 14 |
| TST-005 | 17 |
| TST-006 | 11 |
| TST-007 | 7 |
| TST-008 | 24 |
| TST-009 | 27 |
| TST-010 | 28 |
| TST-011, TST-014 | 21 |
| TST-012, TST-015 | 31 |
| TST-013 | 2 |
| DUP-001, DUP-005 | 3 |
| DUP-002 | 14 |
| DUP-003 | 4 |
| DUP-006 | 25 |
| DUP-007 | 26 |
| DUP-008 | 28 |
| SIM-001 | 12 |
| SIM-003 | 29 |
| SIM-004 | 30 |
| COM-001 | 12 |
| COM-002, COM-005 | 32 |
| COM-003, COM-006 | 30 |

The remaining confirmed IDs have non-independent dispositions and must not receive
separate implementation work: ARC-002 and COM-004 are merged into COM-002;
SIM-002 is merged into DUP-007; DUP-004 is rejected. Their audit rationale remains
authoritative.

## Follow-up review traceability

| Review finding | Remediation stage | Source |
| --- | ---: | --- |
| Diagnostic leaf symlinks and pathname-reopened tails bypass confinement/redaction guarantees | 33 | Post-implementation review |
| Unix descendants survive natural leader exit | 34 | Post-implementation review |
| Remote current-state and lock control objects are read without acquisition limits | 35 | Post-implementation review |

## Open Questions

None. The remediation behavior and ownership decisions are specified above.
Native macOS/Windows runtime validation remains contingent on external runner
availability, but cross-build requirements and the rule against inventing runner
labels make implementation decision-complete.