audita/docs/roadmap/feature-request-narratio.md

Independent output destinations for Narratio integration

Request

Allow CLI callers to independently select destinations for:

• the completed transcript;
• ordinary reports; and
• debug captures, including retained working material.

Narratio would like to use the existing --output, --report-dir, and --work-dir controls together, with --debug supplied when it explicitly requests debug capture. This request concerns external CLI behavior only.

Current CLI limitation

The CLI contract documents that --report-dir selects the report directory for stdout transcript output, but has no effect with file transcript output. Reports then accompany the transcript file. This prevents Narratio from directing the transcript and ordinary reports to independent locations in the same invocation.

The existing transcript and debug destination controls already provide much of the requested separation.

Desired behavior

• With --output FILE --report-dir DIR, write the transcript to FILE and any ordinary reports produced to DIR.
• Continue supporting --report-dir DIR when the transcript goes to stdout.
• Apply the selected report destination to reports produced on unsuccessful runs as well as successful runs. This does not require reports for failure conditions that would not otherwise produce them.
• Allow the debug destination to be selected independently of both the transcript and ordinary report destinations. Audita may retain its own filenames and nested directory structure beneath that destination.
• Keep debug enablement separate from destination selection. Narratio needs to select a debug destination while leaving capture enablement to Audita's configuration or defaults, and to pass --debug when explicitly requesting capture. Narratio does not need an additional debug-disable mechanism.
• Preserve existing defaults when destination overrides are omitted. Selecting a report or debug destination does not itself enable that category of output.

Production Narratio runs use Audita's default ordinary reporting behavior. They do not pass --reporting=false or enable debug unless requested. Narratio captures stdout and stderr itself; this request does not require a separate Audita flag for redirecting those streams.

Supporting rationale

Narratio's planned workspace separates products and diagnostics. Operators inspect completed transcripts under transcripts/ and other completed products under artifacts/. Logs and Debug have run-specific storage and convenient latest-attempt views organized by stage.

Independent destinations let Narratio supply a transcript staging path, a run-specific polish log directory for ordinary reports, and a separate run-specific polish debug directory. Reports can be inspected at their selected location as they are produced, including after failures, without Narratio relocating them from the transcript directory. Normal reporting can remain enabled without mixing diagnostic files with completed products.

Narratio owns these destinations and their operator-facing views. Audita owns the report and debug formats and its internal working-state lifecycle. This request does not prescribe Audita's internal design, cache locations, retention policies, or how it organizes material within a debug capture.

Observable outcome

A caller can select three distinct destinations in one invocation. The transcript appears at the selected output file, ordinary reports appear at the selected report directory, and enabled debug captures appear beneath the selected debug root. The same report placement applies to whatever reports Audita produces before an unsuccessful exit.