96 lines
4.5 KiB
Markdown
96 lines
4.5 KiB
Markdown
# 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.
|