109 lines
6.1 KiB
Markdown
109 lines
6.1 KiB
Markdown
# 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](implementation.md)
|
|
owns the ordered work; 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.
|
|
|
|
## 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.
|