Complete Phase 19 Go rollout documentation

docs/architecture.md

@@ -2,10 +2,10 @@
 
 ## Scope and intent
 This document describes:
-- the current implemented Go architecture; and
-- the intended final architecture for later rewrite phases.
+- the implemented Go architecture used in production today; and
+- historical rewrite-phase context that explains how the architecture was delivered.
 
-Status labels are explicit so future engineers and LLM agents do not assume unimplemented behavior exists.
+Status labels are explicit so future engineers and LLM agents do not infer missing behavior that is not actually missing.
 
 ## Current implementation status
 Implemented today:
@@ -42,9 +42,6 @@ Implemented today:
 - Explicit runtime support for `--modules homophones` through the production runner path.
 - Explicit runtime support for `--modules spoken_word` through the production runner path.
 
-Not implemented in CLI runtime path today:
-- Rollout and Python retirement work (Phase 19).
-
 Current reality:
 - all production modules exist and are wired into the default runtime path.
 - a normal `audita process` run without `--modules` now executes the full sequence:
@@ -66,7 +63,7 @@ Phase sequencing note:
 - Phase 16 default full pipeline integration is complete;
 - Phase 17 parity fixture suite is complete;
 - Phase 18 operational hardening and subprocess integration are complete;
-- next recommended phase is Phase 19 (documentation, rollout, and Python retirement).
+- Phase 19 documentation/rollout completion is complete.
 
 ## Actual Go package layout
 
@@ -468,8 +465,8 @@ Current runtime note:
 - default non-explicit runs usually have no module-level skipped corrections, so `auto` commonly removes clean successful run directories.
 - explicit grammar/glossary/homophones/spoken_word runs can produce validator rejections and application skips, which are reflected in reports and retention input.
 
-Intentionally deferred to module/LLM phases:
-- real domain proposal prompts and production module implementations remain tied to later module phases.
+Phase note:
+- Earlier-phase documentation deferred module and LLM prompt work; those deferred items were completed by Phases 12-16.
 
 ## Current tests and quality posture
 Implemented tests currently cover:
@@ -507,8 +504,9 @@ The runtime now includes hardened subprocess behavior for parent-process callers
 
 Operational caller guidance is documented in [`docs/subprocess-operations.md`](docs/subprocess-operations.md).
 
-## Remaining work (Phase 19)
-Remaining rewrite work is documentation/rollout/retirement-oriented:
-- repository-level rollout documentation and migration guidance;
-- Python retirement/archival decisions and related documentation cleanup;
-- final release-facing communication of Go-primary operational guidance.
+## Final status (Phase 19 complete)
+- Go Audita is the active implementation.
+- Default full module-sequence runtime is implemented and tested.
+- Parity fixtures and operational hardening coverage are in place.
+- Python is preserved as a legacy/reference implementation in `python/` and is no longer the primary operational path.
+- Migration and rollout guidance is documented in [`docs/migration-from-python.md`](docs/migration-from-python.md).

docs/migration-from-python.md

@@ -0,0 +1,84 @@
+# Migrating from Python Audita to Go Audita
+
+This guide describes the operational migration from the legacy Python Audita implementation to the Go Audita implementation in this repository.
+
+## Status summary
+
+- The Go CLI is now the primary Audita implementation.
+- The Go `audita process` command is intended to replace the Python CLI for normal operation.
+- The Python implementation under [`python/`](../python/) is preserved as a legacy/reference implementation for parity history and troubleshooting context.
+
+## What changes for operators
+
+Use the Go binary as the integration target in orchestrators and parent processes.
+
+Default Go runtime behavior executes the full module sequence:
+1. `glossary`
+2. `homophones`
+3. `glossary`
+4. `spoken_word`
+5. `grammar`
+
+Repeated stages are resolved deterministically in reports (for example `glossary_1`, `glossary_2`).
+
+## Recommended invocation pattern
+
+For orchestrated runs, use explicit output files:
+
+```sh
+audita process <transcript.json> \
+  --glossary <glossary.yaml> \
+  --output <corrected-transcript.json> \
+  --report-json <report.json>
+```
+
+Why:
+- `--output` keeps stdout empty on success, simplifying subprocess integration.
+- `--report-json` provides machine-readable run metadata independent of stderr.
+
+Without `--output`, stdout contains transcript JSON only on successful runs.
+
+## Diagnostics and retention behavior
+
+- Each run creates a diagnostics run directory when initialization succeeds.
+- Failed runs retain diagnostics and include `error.log`.
+- Retention mode is controlled by `AUDITA_WORK_DIR_RETENTION` / `--work-dir-retention`:
+  - `always`: keep all run directories.
+  - `never`: keep successful run directories.
+  - `auto`: keep failed runs and successful runs with skipped/rejected corrections.
+
+For subprocess behavior and pipe-handling guidance, see:
+- [`docs/subprocess-operations.md`](subprocess-operations.md)
+
+## Parity notes and known differences
+
+Python-vs-Go parity fixtures and intentional differences are documented in:
+- [`docs/python-parity.md`](python-parity.md)
+
+Known open parity gaps are tracked there and should be treated as real gaps, not intentional differences. Current documented gaps include:
+- broader direct import/use of Python fixture corpus;
+- a repository-standard Python+Go side-by-side runner command;
+- wider transcript/glossary corpus coverage.
+
+## Testing expectations
+
+- Normal `go test ./...` does not require real LLM credentials.
+- Normal `go test ./...` does not require Python dependencies.
+- Deterministic fake-LLM fixtures are used for routine CI-friendly testing.
+
+## Legacy Python status
+
+The Python implementation remains in-repo as a legacy/reference baseline. It is not the primary operational path.
+
+Do not route new production orchestration to Python unless you are doing explicit parity/debug work.
+
+## Rollout checklist
+
+Use this checklist when switching an environment from Python invocation to Go invocation:
+
+1. Run `go test ./...`.
+2. Build the Go binary (`go build -o ./bin/audita ./cmd/audita`).
+3. Run one representative fixture through `audita process`.
+4. Verify `--report-json` output is written and machine-readable.
+5. Verify failure runs print diagnostics path to stderr and retain diagnostics with `error.log`.
+6. Update orchestrator configuration to call the Go binary and pass `--output` and `--report-json`.

docs/rewrite-notes.md

@@ -29,9 +29,19 @@ The Go rewrite is complete when both of the following are true:
    - Strict stdout/stderr discipline for subprocess callers.
    - No hidden service dependency; the CLI remains the primary integration surface.
 
+## Final status (Phase 19 complete)
+
+The Go rewrite definition of done is met, with documented parity caveats tracked in `docs/python-parity.md`.
+
+- Phase 19 is complete.
+- Go Audita is the active implementation.
+- The default full module pipeline is implemented (`glossary,homophones,glossary,spoken_word,grammar`).
+- Parity fixtures and operational hardening coverage exist in normal `go test ./...`.
+- Python is retained as a legacy/reference implementation and is not the primary operational path.
+
 ## Current implementation status
 
-The Go rewrite now has feature-complete runtime behavior for the module pipeline plus Phase 18 operational hardening coverage.
+The Go rewrite is complete and feature-complete for the intended CLI runtime architecture.
 
 Implemented:
 - CLI command surface for `audita process`.
@@ -97,8 +107,11 @@ Implemented:
   - validation override behavior when validation fields are set.
 - Generic JSON diagnostics primitives for LLM interactions (request metadata, request payload, response payload, optional error payload) with secret redaction.
 
-Not yet implemented:
-- Phase 19 rollout and Python retirement/documentation transition work.
+Phase 19 documentation and rollout items are implemented:
+- Go-first README/build/test/usage guidance.
+- subprocess/orchestrator operational guidance.
+- Python-to-Go migration guidance.
+- explicit legacy/reference Python status documentation.
 
 ## Completed phases
 
@@ -234,10 +247,6 @@ Not implemented in Phase 8 (by design):
 - Prompt/response diagnostics runtime wiring.
 - End-to-end transcript polishing.
 
-## Remaining work plan
-
-Next recommended phase: **Phase 19 (documentation, rollout, and Python retirement)**.
-
 ## Phase 9: Structured LLM client and scheduler infrastructure
 
 ### Status
@@ -656,8 +665,8 @@ Implemented:
   - permit release on error/cancellation.
 - Added focused subprocess-caller operational guidance in `docs/subprocess-operations.md`.
 
-Intentionally deferred:
-- Phase 19 documentation/rollout/Python-retirement transitions.
+Historical note:
+- Phase 19 documentation/rollout/Python-retirement transitions were deferred at the end of Phase 18 and completed in Phase 19.
 
 ## Phase 19: Documentation, rollout, and Python retirement
 
@@ -689,9 +698,23 @@ The repository clearly presents the Go implementation as the active Audita imple
 - Users can build, test, and run the Go implementation from docs alone.
 - `go test ./...` passes.
 
+### Phase 19 completion status
+
+Completed.
+
+Implemented:
+- README is Go-first and documents active full-pipeline runtime behavior.
+- Build/install/test usage guidance is Go-primary and operationally oriented.
+- Subprocess/orchestrator behavior is documented in `docs/subprocess-operations.md`.
+- Migration guidance from Python to Go is documented in `docs/migration-from-python.md`.
+- Python parity notes and open parity gaps remain documented in `docs/python-parity.md`.
+- Python implementation status is explicitly legacy/reference in primary docs and `python/README.md`.
+- Documentation no longer routes normal operations to Python.
+- Normal `go test ./...` remains independent of real LLM credentials and Python dependencies.
+
 ## Cross-phase compatibility requirements
 
-These constraints apply to every remaining phase:
+These constraints were used across implementation phases and remain useful maintenance checks:
 
 - Preserve subprocess-safe stdout/stderr behavior.
 - Preserve CLI-over-env precedence.