Document independent output destinations

docs/roadmap/narratio-feature.md

@@ -0,0 +1,133 @@
+# Independent Output Destinations for Narratio
+
+**Last updated:** 2026-10-03
+
+**Status:** Proposed; not implemented. This roadmap records the intended external
+behavior and work needed to reach it. The [Narratio request](feature-request-narratio.md)
+provides the consumer context.
+
+## Purpose
+
+Allow one `audita process` invocation to place the completed transcript,
+ordinary reports, and enabled debug captures at independently selected
+locations. Narratio can then keep completed products, ordinary run diagnostics,
+and detailed debug evidence in its own workspace without relocating Audita's
+files after the run. Audita continues to own report formats and its debug
+working-state lifecycle; Narratio owns its destination paths and operator views.
+
+## Current Baseline
+
+- `--output FILE` writes the transcript to `FILE`, or stdout when omitted.
+- Ordinary reporting is enabled by default. With file output, `errors.yml`,
+  `recoveries.yml`, and `report.md` go beside the transcript. With stdout output,
+  `--report-dir DIR` or `reporting.stdout_dir` selects their directory. The
+  current selection logic ignores `--report-dir` when `--output` is supplied.
+- Reports are initialized before input processing, then updated on completion or
+  failure where possible. Early configuration or destination failures can occur
+  before report initialization and therefore leave no report files.
+- `--work-dir DIR` already overrides the debug root independently. It does not
+  enable debug capture. Capture is enabled by `diagnostics.debug` or an explicit
+  `--debug`; when enabled, Audita retains a `run-<id>` directory beneath the
+  selected root. Debug remains optional, including after unsuccessful runs.
+- The output session already receives distinct transcript and report paths and
+  checks active destinations for conflicts with each other and protected inputs.
+  The limitation is primarily in CLI report-directory selection, not in report
+  encoding or the output session's basic shape.
+
+The current contracts are in [CLI](../cli.md), [configuration](../config.md),
+[operations](../operations.md), [subprocess guidance](../integrations/subprocess.md),
+and [output files](../integrations/output-files.md).
+
+## Targeted Behavior
+
+An explicit `--report-dir DIR` selects the destination for ordinary reports
+whether the transcript goes to `--output FILE` or stdout. With all three paths
+selected, Audita writes the transcript to `FILE`, any enabled ordinary reports
+to `DIR`, and any enabled debug captures beneath the `--work-dir` root. The
+report and debug destinations may be different from the transcript's parent
+and from each other.
+
+| Selection | Transcript | Ordinary reports when enabled | Debug when enabled |
+| --- | --- | --- | --- |
+| No destination override | stdout | `reporting.stdout_dir` (default `.`) | `diagnostics.work_dir` (default `/tmp/audita`) |
+| `--output FILE` only | `FILE` | Parent of `FILE` | Configured/default debug root |
+| `--report-dir DIR` only | stdout | `DIR` | Configured/default debug root |
+| `--output FILE --report-dir DIR --work-dir ROOT` | `FILE` | `DIR` | Beneath `ROOT` |
+
+An explicit CLI report directory takes precedence over file-output placement.
+Without that explicit flag, `reporting.stdout_dir` remains a setting for stdout
+output only. This preserves existing file-output defaults and avoids changing
+the meaning of a configuration field outside Narratio's CLI request. A config
+file or overlay can continue to enable or disable ordinary reporting and debug
+capture under the existing precedence rules. Selecting `--report-dir` or
+`--work-dir` alone does not enable either category. An explicit `--debug` can
+enable capture; no new debug-disable control is needed.
+
+The selected report directory applies to whatever reports Audita currently
+produces on both successful and unsuccessful runs. It does not make new failure
+conditions produce reports, change early-failure behavior, or guarantee that an
+unwritable destination yields a complete bundle. Existing per-file replacement,
+failed-status finalization, output ordering, exit codes, and redacted path
+announcements remain the governing contracts.
+
+Active destinations retain existing safety rules: report files must not collide
+with the transcript or protected inputs, and their directory must satisfy the
+current preflight requirements. With reporting disabled, the report directory
+is inactive and should not be probed merely because it was selected. With debug
+disabled, the debug root is inactive and should not be created merely because it
+was selected. No new rule requires the three roots to be distinct if their
+actual output files do not conflict.
+
+Audita continues to write stdout and stderr under its existing stream contract.
+Narratio captures those streams itself. Audita retains its report filenames and
+its nested debug layout.
+
+## Work Needed
+
+- Make CLI destination selection distinguish an explicit `--report-dir` from a
+  `reporting.stdout_dir` value supplied by defaults, a file, or an overlay.
+  Continue applying the existing ConfigKit flag override for inspection and
+  precedence; use explicit flag presence when deciding whether reports for file
+  output move away from the transcript's parent. Do not rename or broaden the
+  configuration field for this feature.
+- Pass the selected directory to the existing output session for both stdout
+  and file transcript output. Reuse current collision checks, preflight,
+  initialization, finalization, and failure handling. Preserve independent
+  `--work-dir`/debug wiring and correct any coupling found during the work.
+- Update process help, the CLI and configuration references, operations, and
+  subprocess guidance. State clearly that debug can be enabled by configuration
+  as well as `--debug`, and that a chosen debug root does not enable capture.
+  Keep report schemas in their existing canonical owner; no schema change is
+  expected.
+- Replace tests that assert `--report-dir` is ignored with tests of explicit
+  precedence and preserved defaults. Add a representative CLI/subprocess case
+  using three distinct destinations, plus a failure after report initialization
+  that leaves available reports in the selected directory. Cover inactive
+  reporting/debug destinations and existing collision protection at the
+  narrowest useful test boundary. Validation should follow the
+  [testing policy](../policy/testing.md), without duplicating every case across
+  layers.
+
+## Acceptance Criteria
+
+- A CLI caller can provide `--output FILE --report-dir DIR --work-dir ROOT` in
+  one invocation. The transcript appears at `FILE`, enabled ordinary reports at
+  `DIR`, and enabled debug captures beneath `ROOT`.
+- The same explicit report directory works with stdout transcript output and
+  applies to reports produced after an unsuccessful run.
+- Omitted overrides preserve the current stdout and file-output placement;
+  disabled reporting and debug do not create their respective artifacts solely
+  because destination flags were supplied.
+- Existing protection against conflicting destinations and source overwrites,
+  report/debug formats, output lifecycle, streams, and exit behavior still hold.
+- Current documentation and focused tests describe and verify the new CLI
+  contract. No Narratio-specific path convention or Audita-managed latest-run
+  view is introduced.
+
+## Scope Boundary
+
+This request changes external CLI destination selection. It does not call for
+new output formats, config-file fields, a relocation or retention service,
+changes to cache ownership, additional stream-redirection flags, or new debug
+capture controls. Future release versioning follows Audita's release policy;
+this roadmap does not itself schedule or publish a release.