# 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`.