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 source/normalization/chunking artifacts.
• Redacted invocation/effective-config diagnostics metadata artifacts.
• Process report output (--report-json and run-dir report.json) with diagnostics artifact references.
• 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).

Newly completed

• Phase 6: Reports and diagnostics (deterministic runtime scope).

Implemented Phase 6 behavior in current runtime:

• run directory creation and process-level diagnostics artifact writing
• source transcript artifacts
• normalized transcript artifact
• normalization summary artifact
• chunking summary artifact
• invocation metadata artifact
• redacted effective-config artifact
• run-dir report.json plus optional external --report-json
• failure error.log
• report-level diagnostics artifact path references
• retention decision model with skip-aware hook:
  • always keeps all runs
  • never keeps successful runs
  • auto keeps failed runs and successful runs with skipped corrections
  • failed runs are always retained

Current runtime note:

• successful runs generally have no skipped corrections because module execution is not implemented yet, so auto usually removes clean successful run directories.

Pending

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

Scope notes for later phases

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. Module prompt/response diagnostics are intentionally deferred until module execution and LLM call phases.

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.