Refresh documentation and policies and simplify releases

docs/internal/diagnostics-reporting.md

@@ -1,74 +1,69 @@
-# Audita Diagnostics and Reporting
+# Diagnostics and Report Assembly
 
 ## Scope
 
-This document describes diagnostics artifacts, process report mapping, and correction ledger generation.
+This document owns implementation flow and collaborators. Physical artifacts and
+retention belong to [operations](../operations.md). Serialized reports, ledger
+records, and utilization shapes belong to the
+[output-file contract](../integrations/output-files.md).
 
-## Run Directory Ownership
+## Run Directory and Artifact Writers
 
-`internal/core/diagnostics` owns run-directory creation, artifact writes, and retention decisions.
+`internal/core/diagnostics` creates run directories, writes snapshots and metadata,
+and evaluates retention. CLI orchestration supplies the selected configuration,
+paths, run outcome, and correction-presence information. Artifact names are
+centralized in diagnostics; their operator-facing inventory is in
+[operations](../operations.md#diagnostics-directory).
 
-Stable artifact names include:
-- `source-transcript.json`
-- `source-transcript-parsed.json`
-- `normalized-transcript.json`
-- `normalization-summary.json`
-- `chunking-summary.json`
-- `utilization-diagnostics.json`
-- `correction-ledger.json`
-- `invocation.json`
-- `effective-config.json`
-- `report.json`
-- `error.log` (failure)
+Snapshot writes are attempted at the relevant processing phases. Several diagnostic
+writes are best-effort, so report metadata can identify a location without proving
+that a file was written. The CLI distinguishes primary processing errors from
+secondary diagnostic/report write errors.
 
 ## Process Report Mapping
 
-`internal/framework/processreport` maps runner/CLI execution facts into `reporting.ProcessReport`.
+`internal/framework/processreport.Build` maps invocation facts, normalization and
+chunking summaries, and runner output into `reporting.ProcessReport`. Core reporting
+owns the Go data structures and JSON writer. The builder attaches diagnostic
+metadata when a run-directory path is available.
 
-Report metadata fields include:
-- `report_schema_name` (`audita-process-report`)
-- `report_schema_version` (`v1`)
-- `output_schema`
-- `config_version` (when file config exists)
+Module mapping copies outcomes from runner results, collects summary counts, and
+preserves available partial module results on failure. The CLI failure path does
+not pass normalization or chunking summaries to report construction even when
+some earlier processing completed. Consumer interpretation belongs to the
+[process-report contract](../integrations/output-files.md#process-report).
 
-The report includes:
-- top-level status/error phase/error message;
-- normalization/chunking summaries;
-- diagnostics metadata paths;
-- per-module results and module summary.
+## Correction Ledger and Utilization
 
-## Correction Ledger
+`BuildCorrectionLedger` flattens module changes, rejections, and failures into
+ledger entries. It associates validator records by proposal index within each
+module, separates execution classes through validator metadata, and sorts entries
+by module instance, proposal index, and disposition.
 
-`internal/framework/processreport/BuildCorrectionLedger` flattens run results into `correction-ledger.json` entries.
+Runner instrumentation collects utilization; CLI orchestration writes it when
+run output is available. Report assembly does not independently measure calls.
+For the serialized forms see [ledger](../integrations/output-files.md#correction-ledger)
+and [utilization](../integrations/output-files.md#utilization-diagnostics).
 
-Dispositions:
-- `applied`
-- `skipped`
-- `rejected`
-- `failed`
+## CLI Coordination and Retention
 
-Validator decisions are split into deterministic and LLM-backed groups using validator metadata classification.
+CLI orchestration writes caller-selected reports and run-local artifacts before
+asking diagnostics to apply retention. `HasSkippedCorrections` derives the
+retention input from runner outcomes. Keep the exact lifecycle definition in
+[operations](../operations.md#retention-behavior), not in another internal table.
 
-## Report Write Paths
-
-- run directory always attempts to write `report.json` when possible;
-- optional `--report-json` writes an external report file;
-- on failure paths, report writing is best-effort and does not mask primary run errors.
-
-## Retention Interaction
-
-Current retention behavior:
-- failed runs are retained;
-- `always` keeps successful runs;
-- `auto` removes only clean successful runs;
-- `never` currently retains successful runs in current implementation.
+On a processing failure, secondary report-write errors do not replace the original
+error. On the success path, an external report-write failure returns before the
+run-local report write; retention errors occur later. This ordering explains why
+artifacts and process exit status must be assessed together.
 
 ## Redaction
 
-Redacted data expectations:
-- effective config artifact uses config redaction;
-- diagnostics payloads and surfaced errors use LLM secret redaction;
-- reports should not include raw API key values.
+Effective configuration uses config redaction. LLM diagnostic and error paths
+use `llm.ConfiguredSecrets` and the runtime's redaction helpers. Keep these separate
+mechanisms aligned with the [architecture requirement](../policy/architecture.md#errors-and-secret-handling).
+Operational handling of transcript-bearing artifacts belongs to
+[operations](../operations.md#artifact-handling).
 
 ## Key Tests