From c3087aeda64bacc59b19a8c19b7f5f47d5966109 Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Mon, 11 May 2026 13:35:15 +0000 Subject: [PATCH] Complete Phase 3 proposal foundation --- README.md | 29 +++++++++++--------- docs/rewrite-notes.md | 61 +++---------------------------------------- internal/cli/run.go | 2 +- 3 files changed, 22 insertions(+), 70 deletions(-) diff --git a/README.md b/README.md index d088bc9..c8a5e0e 100644 --- a/README.md +++ b/README.md @@ -2,28 +2,33 @@ Audita is a transcript polishing CLI. The Go implementation at the repository root is canonical going forward, and is being delivered compatibility-first against the frozen Python reference in `python/`. -## Current Status: Phase 2 Foundation +## Current Status: Phase 3 Deterministic Foundation -The current `audita process` implementation now includes deterministic input handling and normalization foundations: +The current `audita process` implementation includes deterministic input handling and foundation behavior: - typed transcript parsing for both accepted top-level forms (`[]` and `{ "segments": [...] }`); - typed glossary YAML parsing; - transcript and glossary schema validation with actionable errors; - deterministic same-speaker normalization; - sequential normalized segment IDs starting at `1`; +- deterministic token estimation; +- contiguous transcript chunking and section summaries; - normalized transcript JSON output; -- minimal structured `--report-json` output including normalization summary fields; +- minimal structured `--report-json` output including normalization and chunking summary fields; - minimal normalization diagnostics artifacts in per-run work directories; +- chunking diagnostics artifacts in per-run work directories; - subprocess-safe stdout/stderr behavior. -Still not implemented in Phase 2: +The repository also now contains deterministic proposal foundation packages (models, preview, application, skip reporting, and framework contracts) with fixture/golden tests. -- transcript-polishing correction modules; -- chunking/proposal generation and application; -- deterministic and LLM validators; -- structured LLM client execution; -- module pipeline execution; -- full long-term diagnostics retention/reporting model. +Still not implemented in the Go CLI runtime path: + +- real module execution pipeline; +- real `glossary`, `homophones`, `spoken_word`, or `grammar` module behavior; +- LLM proposal generation; +- validator-chain execution; +- concrete structured LLM client implementation; +- final end-to-end transcript polishing behavior. ## Quick Start (Go) @@ -40,13 +45,13 @@ go run ./cmd/audita --help go run ./cmd/audita process --help ``` -Run Phase 2 normalization flow: +Run current deterministic flow: ```sh go run ./cmd/audita process transcript.json --glossary glossary.yaml --output corrected.json ``` -Without `--output`, normalized transcript JSON is written to stdout. +Without `--output`, transcript JSON is written to stdout. ## Repository Notes diff --git a/docs/rewrite-notes.md b/docs/rewrite-notes.md index 467f4fa..0745bda 100644 --- a/docs/rewrite-notes.md +++ b/docs/rewrite-notes.md @@ -591,64 +591,11 @@ Before accepting a phase implementation, check: - Does `go test ./...` pass? - Is the code idiomatic Go rather than Python-shaped Go? -## Phase 2 Status (Go Implementation) +## Historical checkpoint note -The Go rewrite has completed Phase 2 with the following capabilities: - -### Implemented Features: - -1. **Typed Schema Validation**: - - Transcript validation supports both bare segment arrays and objects with `segments` field - - Glossary validation matches the existing YAML format - - Comprehensive field validation and error reporting - -2. **Deterministic Normalization**: - - Chronological sorting of segments - - Same-speaker adjacent segment merging with configurable gap thresholds - - Ellipsis insertion for gaps above the ellipsis threshold - - Configurable maximum segment duration and token limits - - Sequential ID reassignment starting at 1 - - Category preservation during merging - -3. **Process Output**: - - Output is normalized transcript JSON (not raw passthrough) - - Canonical transcript shape as specified in architecture docs - - Proper stdout/stderr discipline preserved from Phase 1 - -4. **Enhanced Reporting**: - - Success reports include normalization statistics - - Failure reports include error phase and concise messages - - No secrets leaked to reports - -5. **Minimal Diagnostics**: - - Per-run work directories with unique timestamps - - Source transcript artifacts (raw and parsed) - - Normalized transcript artifacts - - Normalization summary artifacts - - Authoritative report.json in run directory - - Error logs on failure - - Basic retention policy implementation - -### Not Yet Implemented (Future Phases): - -- Chunking and token-bounded section building -- LLM proposal generation and structured output -- Validator chains and decision logging -- Module execution pipeline -- Full diagnostics retention policy -- Skipped correction detection for auto retention -- Real module implementations (glossary, homophones, spoken_word, grammar) - -### Compatibility Notes: - -The Go implementation maintains the public CLI contract from the Python implementation: -- `audita process transcript.json --glossary glossary.yaml --output corrected.json` -- stdout contains transcript JSON when --output is omitted -- stderr contains logs and errors only -- --report-json writes machine-readable reports -- Nonzero exit codes on failure - -The normalization behavior is deterministic and matches the architectural specifications, but may differ from Python-era behavior in edge cases until full module implementation is complete. +Earlier "Phase 2 status" notes are intentionally superseded by +`Current Go rewrite status (Phase 3 foundation)` near the top of this document. +Use that section as the authoritative current-state snapshot. ## When to consider an HTTP API diff --git a/internal/cli/run.go b/internal/cli/run.go index 0917882..caff920 100644 --- a/internal/cli/run.go +++ b/internal/cli/run.go @@ -494,7 +494,7 @@ func hasHelpFlag(args []string) bool { } func writeRootUsage(w io.Writer) { - fmt.Fprintln(w, "Audita is a transcript polishing CLI.") + fmt.Fprintln(w, "Audita is a transcript processing CLI.") fmt.Fprintln(w) fmt.Fprintln(w, "Usage:") fmt.Fprintln(w, " audita [options]")