audita/docs/rewrite-notes.md

# Audita Go Rewrite Notes

## Current implementation status
The Go rewrite is currently in a deterministic foundation stage.

Implemented:
- CLI command surface for `audita process`.
- Config/env/flag loading and validation.
- Transcript/glossary schema parsing and validation.
- Deterministic normalization with summary stats.
- Deterministic chunking with summary stats.
- Per-run diagnostics directory plus normalization/chunking artifacts.
- Minimal process report output (`--report-json` and run-dir `report.json`).
- Framework foundation packages for contracts and proposal preview/apply semantics.
- Broad deterministic and CLI/subprocess test coverage for the implemented phases (`go test ./...`).

Not yet implemented in runtime pipeline:
- Module runner orchestration.
- Real correction modules.
- Validator-chain execution.
- Structured LLM client integration.
- End-to-end transcript polishing behavior.

## Phase status (completed / partial / pending)

### Completed
- Phase 1: Go CLI skeleton.
- Phase 2: Schemas and file I/O.
- Phase 3: Deterministic normalization.
- Phase 4: Chunking and token estimation (deterministic implementation present).
- Phase 5: Proposal model and application semantics (foundation package implemented and tested).

### Partial
- Phase 6: Reports and diagnostics.

What is complete:
- run directory creation
- source/normalized/chunking artifacts
- report writing
- failure `error.log`
- retention mode parsing/validation

What is still incomplete vs original plan:
- redacted invocation/config metadata artifacts are not written yet
- module prompt/response diagnostics are not present (no module execution yet)
- `auto` retention semantics currently behave like `never` for successful runs

### Pending
- Phase 7+: runner orchestration, validators in runtime path, LLM client, bounded concurrency, real modules, full compatibility and side-by-side rollout phases.

## Deviations from original phase plan
1. Proposal foundation (`internal/framework/proposals`) and framework contracts (`internal/framework/contracts`) were implemented before full runner orchestration.
2. Chunking was integrated directly into the current CLI runtime path before module execution exists.
3. Reporting currently uses a process-level status report with `phase: "phase3-chunking"`, rather than module-level pipeline reports.
4. Work-dir retention `auto` is intentionally deferred and currently simplified.

## Next recommended implementation phase
Implement **Phase 7 (pipeline runner with fake modules)** next.

Concrete target for next phase:
1. Add a production runner package wired from `internal/cli/run.go`.
2. Resolve configured module keys into run specs using existing contracts helper.
3. Execute fake or deterministic in-repo modules sequentially over a working transcript.
4. Run proposal application through `internal/framework/proposals` for each stage.
5. Emit module-level applied/skipped results into report structures.
6. Preserve current stdout/stderr behavior and diagnostics retention behavior.

Rationale:
- This uses already-implemented deterministic pieces.
- It closes the biggest current gap: no actual module pipeline execution.
- It enables validator and LLM phases to be added incrementally afterward.

## Guidance for Codex-style prompts
When requesting the next implementation steps, use narrow prompts such as:
- "Implement runner orchestration using existing contracts and proposal apply package, no LLM calls yet."
- "Add module-level report structs and wire them into process report."
- "Keep CLI contract unchanged and ensure `go test ./...` passes."

Avoid broad prompts like "finish the rewrite"; they blur phase boundaries and make review harder.

## Compatibility reminders
Keep these constraints unchanged while implementing later phases:
- Preserve subprocess-safe stdout/stderr behavior.
- Preserve CLI-over-env precedence.
- Preserve deterministic safety-first proposal application semantics.
- Do not claim module or LLM behavior exists until it is actually in runtime path.