diff --git a/docs/roadmap/narratio-feature.md b/docs/roadmap/narratio-feature.md new file mode 100644 index 0000000..64971fb --- /dev/null +++ b/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-` 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.