audita/docs/operations.md

Audita Operations

This document owns runtime workflow, physical artifact placement, retention, and recovery. Use the CLI reference for invocation and stream/exit semantics, configuration for settings, and output-file contracts for logical formats.

Normal Workflow

1. Choose a configuration and validate it using the configuration commands.
2. Prepare input files conforming to the input contract.
3. Run the processing command, choosing explicit output and report destinations when those files must survive run-directory cleanup.
4. Inspect the corrected transcript and process report. Review rejected or skipped corrections when the report indicates them; successful execution does not mean every proposed correction was applied.

Processing creates a run directory, loads and normalizes the inputs, chunks the transcript, executes the correction pipeline, writes results, and applies retention. Early configuration failures happen before run-directory creation. Failures after initialization attempt to preserve diagnostic evidence; individual artifact writes can fail, so a run directory need not contain every listed file.

Output Files

The caller chooses transcript and optional external report destinations using the CLI. These are separate from the per-run diagnostic directory unless the caller deliberately places them inside it. Choose existing, writable parent directories. Output/report files can be overwritten by subsequent runs using the same destinations.

A later report or cleanup failure can occur after transcript output was written. Inspect the process result and available report before treating the files as a completed run. Retention of the diagnostic directory does not archive caller-selected output files elsewhere.

Diagnostics Directory

The diagnostics configuration selects the parent work directory. Runs create children named like run-<unix-nanoseconds>. The runtime creates the work directory if needed. Report paths may be relative when the supplied work directory is relative; resolve them using the invocation's working directory.

Artifact in the run directory	Purpose
source-transcript.json	Original transcript input
source-transcript-parsed.json	Parsed source representation
normalized-transcript.json	Transcript after normalization
normalization-summary.json	Normalization counters
chunking-summary.json	Section/token summary
invocation.json	Invocation metadata
effective-config.redacted.yaml	Redacted ConfigKit configuration snapshot
config-origins.yaml	Safe configuration origin and resolution metadata
selected-profiles.yaml	Safe selected role profiles and model controls
report.json	Run's process report
correction-ledger.json	Correction dispositions
utilization-diagnostics.json	Backend execution and domain timing observations
llm-execution.json	Safe logical-call and execution event records
error.log	Failure details when written

LLM request, response, and error diagnostics are also written within the run directory. Their nested naming and payloads are debugging details. Prefer paths provided by the report and its decision/warning records over reconstructing those paths. The report describes intended artifact locations, not proof that every write succeeded or that the files still exist after retention.

Retention Behavior

Configuration owns accepted retention values and the default. Current lifecycle behavior is:

Run outcome / selection	Directory outcome
Failed run	Retained regardless of selection
Successful run, always	Retained
Successful run, auto	Retained if corrections were skipped or rejected; otherwise removed
Successful run, never	Currently retained, the same outcome as always

The name never does not currently mean deletion. Warnings alone do not trigger retention under auto unless they also produce skipped or rejected corrections. An external report outside the run directory survives automatic cleanup, but its artifact paths can then point to removed files.

Artifact Handling

Run artifacts can contain full transcripts, glossary-related context, and LLM prompts/responses. Configured-key redaction does not anonymize those contents. Choose a work directory whose ownership and permissions fit the transcript data, and retain or share artifacts intentionally. Credential-supply mechanisms are owned by configuration.

For a debugging run, select retained diagnostics using the retention flag. Copy needed artifacts before removing completed run directories manually. Avoid deleting a directory while its run is active. Audita does not provide a separate archival/backup or remote artifact storage facility.

Failure Inspection and Recovery

1. Read stderr and the exit classification defined by the CLI.
2. Locate the external report, or the run directory identified by the error when available. If a late error omits the path, inspect the selected work directory.
3. Read the available report and error log. Use report status and error fields to identify the failed phase, then inspect referenced artifacts.
4. Correct the concrete input, configuration, endpoint, or filesystem issue and rerun the command with diagnostics retained if further investigation is needed.

Each invocation starts a new run. There is no implemented resume/checkpoint API; recovery is a rerun, not continuation from an artifact. Failures during early configuration or directory creation may leave no report or diagnostic files.