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.

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.