Migrate internal architecture docs to docs/internal

docs/internal/diagnostics-reporting.md

@@ -0,0 +1,79 @@
+# Audita Diagnostics and Reporting
+
+## Scope
+
+This document describes diagnostics artifacts, process report mapping, and correction ledger generation.
+
+## Run Directory Ownership
+
+`internal/core/diagnostics` owns run-directory creation, artifact writes, and retention decisions.
+
+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)
+
+## Process Report Mapping
+
+`internal/framework/processreport` maps runner/CLI execution facts into `reporting.ProcessReport`.
+
+Report metadata fields include:
+- `report_schema_name` (`audita-process-report`)
+- `report_schema_version` (`v1`)
+- `output_schema`
+- `config_version` (when file config exists)
+
+The report includes:
+- top-level status/error phase/error message;
+- normalization/chunking summaries;
+- diagnostics metadata paths;
+- per-module results and module summary.
+
+## Correction Ledger
+
+`internal/framework/processreport/BuildCorrectionLedger` flattens run results into `correction-ledger.json` entries.
+
+Dispositions:
+- `applied`
+- `skipped`
+- `rejected`
+- `failed`
+
+Validator decisions are split into deterministic and LLM-backed groups using validator metadata classification.
+
+## 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.
+
+## 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.
+
+## Key Tests
+
+- `internal/core/diagnostics/*_test.go`
+- `internal/framework/processreport/*_test.go`
+- `internal/core/reporting/report_test.go`
+- `internal/cli/run_test.go`
+- `cmd/audita/main_integration_test.go`