audita/docs/roadmap/narratio-feature.md

Independent Output Destinations for Narratio

Last updated: 2026-10-03

Status: Proposed; not implemented. This roadmap records the intended external behavior and the reasons for it. The implementation plan owns the ordered work; the Narratio request 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, configuration, operations, subprocess guidance, and output files.

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.

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.