## Phase 8: Runtime validator framework and deterministic validators
### Purpose
Wire validator-chain execution into the runner using deterministic validators first. This phase establishes the safety model before any real LLM proposal generation is introduced.
### Scope
Implement:
- Runtime validator interfaces if the existing contracts need refinement.
- Validation request/result models.
- Validator cardinality enforcement:
- one decision per candidate proposal index
- missing indexes are errors
- duplicate indexes are errors
- unknown indexes are errors
- Deterministic validators:
- confidence threshold
- original-text presence
- non-empty correction
- identical text/no-effect rejection
- protected glossary term logic, if it can be implemented deterministically from current glossary schema
- Validator ordering.
- Runner integration so candidate proposals pass through validators before application.
- Module report fields for validator approvals/rejections.
Do not implement:
- LLM-backed validators.
- Real modules.
- Real LLM proposal generation.
- Prompt/response diagnostics.
### Expected behavior at end of phase
Fake modules can generate deterministic proposals, those proposals can be filtered by deterministic validators, and only approved proposals are applied.
### Definition of done
- Validator chains run in the production runner.
- Deterministic validators are implemented and tested.
- Validator cardinality enforcement is tested.
- Rejected proposals appear in module reports with stable reasons.
- Approved proposals are applied through existing proposal application semantics.
- No real LLM calls occur.
-`go test ./...` passes.
## Phase 9: Structured LLM client and scheduler infrastructure
### Purpose
Implement the provider-neutral LLM infrastructure needed by both proposal generation and LLM-backed validators, without yet implementing real modules.
### Scope
Implement:
-`StructuredLLMClient` interface refinement if needed.
- OpenAI-compatible chat completions client.
- Structured JSON response support.
- Request/response types for structured calls.
- Retry handling for malformed structured output.
- Per-request timeout behavior.
- Context cancellation.
- Primary LLM config resolution.
- Validation LLM config resolution and inheritance from primary settings.
- Optional API key behavior for self-hosted endpoints.
- Redaction of credentials in all diagnostics and reports.
- LLM scheduler/semaphore for bounded backend concurrency.
- Unit tests using fake HTTP servers or fake client implementations.
- Prompt/response diagnostics writer primitives that can later be used by modules and validators.
Do not implement:
- Real correction modules.
- LLM-backed validators.
- Prompt text for domain modules.
- End-to-end transcript polishing.
### Expected behavior at end of phase
The codebase has a tested OpenAI-compatible structured-output client and scheduler, but the CLI still does not perform real LLM polishing unless later phases wire modules into the runner.
### Definition of done
- Structured LLM client is implemented and tested.
- Scheduler enforces configured concurrency.
- Primary and validation LLM settings resolve correctly.
- Timeout and retry behavior are tested.
- Malformed structured responses fail cleanly or retry according to config.
- Prompt/response diagnostic primitives exist.
- API keys are not leaked.
- No real module behavior is introduced.
-`go test ./...` passes.
## Phase 10: LLM-backed validators
### Purpose
Implement the LLM-backed validator layer used by the Python implementation, and wire it into the runtime validator framework.
### Scope
Implement:
- LLM validator request and response models.
- Shared batching logic for validation prompts using validation token limits.
- Prompt builders for LLM validators.
- LLM-backed validation categories needed for parity, such as:
- spoken-form plausibility
- meaning reversal detection
- editorial review
- grammar review
- spoken-word review
- Validator prompt/response diagnostics.
- Validation LLM scheduler usage.
- Validator error handling and report integration.
- Fake LLM tests for approval, rejection, malformed output, missing decision, duplicate decision, and retry cases.
Do not implement:
- Real correction modules, except for minimal fake/test modules needed to exercise validators.
- Full default pipeline behavior.
- Domain proposal prompts.
### Expected behavior at end of phase
The runner can execute a mixed deterministic + LLM validator chain against proposals produced by fake modules. LLM validators use the structured LLM client and write diagnostics.
Create the reusable proposal-generation layer used by all real modules, and establish the real module registry without yet requiring all modules to be fully implemented.
### Scope
Implement:
- Shared LLM proposal generation helper.
- Proposal prompt request/response models.
- Structured correction set response parsing.
- Proposal index assignment.
- Module prompt/response diagnostics.
- Module registry package for real module keys.
- Module construction from run specs.
- Clean unsupported-module behavior.
- Shared module test harness using fake LLM responses.
- One minimal real module may be implemented as a proof of the proposal-generation path if that keeps the phase coherent, but only if it does not blur scope.
Do not implement:
- All real modules.
- Full default pipeline parity.
- Prompt improvements beyond faithful porting of Python behavior.
### Expected behavior at end of phase
The framework can support real LLM proposal generation, and modules can be registered and instantiated consistently. At least the infrastructure for real modules exists, even if most modules are implemented in later phases.
### Definition of done
- Shared proposal-generation helper exists.
- Proposal prompt/response diagnostics are written for module proposal calls.
- Module registry resolves known module keys deterministically.
Implement the first production module in the Go runtime path. Grammar is a good first real module because it exercises LLM proposal generation and validator chains while remaining constrained to punctuation, capitalization, and spacing cleanup.
### Scope
Implement:
-`grammar` module package.
- Grammar prompt builder ported from the Python implementation.
- Grammar structured response model.
- Grammar replacement policy.
- Grammar validator chain.
- Grammar confidence threshold handling.
- Prompt/response diagnostics.
- Module-level report integration.
- CLI support for `--modules grammar`.
- Fake LLM tests.
- Optional real LLM smoke test gated so normal `go test ./...` does not require credentials.
Do not implement:
- Glossary module.
- Homophones module.
- Spoken-word module.
- Default full module sequence as active parity claim.
### Expected behavior at end of phase
Running `audita process ... --modules grammar` should perform real grammar-stage transcript polishing using the configured LLM endpoint.
### Definition of done
- Grammar module runs in the production runner.
- Grammar module generates structured proposals through the LLM client.
- Grammar validator chain runs.
- Approved grammar proposals are applied.
- Applied/skipped grammar changes appear in reports.
- Prompt/response diagnostics are written.
-`--modules grammar` works end-to-end.
- Default pipeline is not yet claimed complete.
-`go test ./...` passes without requiring external LLM credentials.
## Phase 13: Glossary module and protected-term behavior
### Purpose
Implement the glossary correction module and the glossary-derived protection behavior needed by downstream modules.
### Scope
Implement:
-`glossary` module package.
- Glossary prompt builder ported from Python.
- Glossary structured response model.
- Glossary replacement policy.
- Glossary confidence threshold handling.
- Glossary validator chain.
- Protected-term extraction from parsed glossary.
- Protected-term validator behavior used by other modules where applicable.
- Prompt/response diagnostics.
- CLI support for `--modules glossary`.
- Fake LLM tests.
- Tests for repeated glossary stages using `glossary,glossary`.
Do not implement:
- Homophones module.
- Spoken-word module.
- Default full pipeline parity claim.
### Expected behavior at end of phase
Running `audita process ... --modules glossary` should perform real glossary-supported corrections. Repeated glossary stages should work and be reported as separate module instances.
### Definition of done
- Glossary module runs in the production runner.
- Glossary terms and aliases are used in prompts and validators.
- Protected-term behavior is implemented and tested.
- Repeated glossary module instances are reported correctly.
- Applied/skipped glossary changes appear in reports.
- Prompt/response diagnostics are written.
-`go test ./...` passes without requiring external LLM credentials.
## Phase 14: Homophones module
### Purpose
Implement conservative homophone and mistranscription correction behavior.
### Scope
Implement:
-`homophones` module package.
- Homophones prompt builder ported from Python.
- Homophones structured response model.
- Homophones replacement policy.
- Homophones confidence threshold handling.
- Homophones validator chain.
- Prompt/response diagnostics.
- CLI support for `--modules homophones`.
- Fake LLM tests.
- Tests for interaction with glossary/protected terms where relevant.
Do not implement:
- Spoken-word module.
- Default full pipeline parity claim unless spoken-word is already complete.
### Expected behavior at end of phase
Running `audita process ... --modules homophones` should perform real conservative homophone/mistranscription corrections using the configured LLM endpoint.
### Definition of done
- Homophones module runs in the production runner.
- Homophones proposals are generated through structured LLM calls.
- Validator chain is enforced.
- Protected-term behavior is respected where applicable.
- Applied/skipped homophone changes appear in reports.
- Prompt/response diagnostics are written.
-`go test ./...` passes without requiring external LLM credentials.
## Phase 15: Spoken-word module
### Purpose
Implement conservative dysfluency cleanup while preserving substantive meaning.
### Scope
Implement:
-`spoken_word` module package.
- Spoken-word prompt builder ported from Python.
- Spoken-word structured response model.
- Spoken-word replacement policy.
- Spoken-word confidence threshold handling.
- Spoken-word validator chain.
- Strong semantic guardrails using LLM-backed validators.
- Prompt/response diagnostics.
- CLI support for `--modules spoken_word`.
- Fake LLM tests.
- Tests for rejection of meaning-changing cleanup.
Do not implement:
- Prompt redesign beyond faithful porting.
- New stylistic rewriting behavior not present in the Python implementation.
### Expected behavior at end of phase
Running `audita process ... --modules spoken_word` should perform real conservative dysfluency cleanup, with guardrails against semantic changes.
### Definition of done
- Spoken-word module runs in the production runner.
- Spoken-word proposals are generated through structured LLM calls.
- Applied/skipped spoken-word changes appear in reports.
- Prompt/response diagnostics are written.
-`go test ./...` passes without requiring external LLM credentials.
## Phase 16: Default full pipeline integration
### Purpose
Enable and harden the full default module sequence in the Go runtime path.
### Scope
Implement:
- Default runtime sequence:
-`glossary`
-`homophones`
-`glossary`
-`spoken_word`
-`grammar`
- End-to-end execution through all real modules.
- Accurate resolved module instance names.
- Module-level report aggregation.
- Full run-level applied/skipped summaries.
- Skip-aware retention behavior using actual skipped correction data.
- Failure behavior with partial module progress.
- PipelineRunError or equivalent partial-progress error type if not already implemented.
- Diagnostics for each module instance.
- Tests for successful full pipeline using fake LLM.
- Tests for mid-pipeline failure preserving partial report and diagnostics.
Do not implement:
- Python archive removal.
- Side-by-side rollout tooling beyond what is needed for tests.
### Expected behavior at end of phase
Running `audita process transcript.json --glossary glossary.yaml --output corrected.json` should execute the full Go module pipeline and produce a corrected transcript.
### Definition of done
- Default module sequence runs end-to-end.
- All real modules participate in runtime path.
- Reports include all module instances.
- Applied/skipped changes are aggregated at run level.
- Failed runs retain useful partial reports and diagnostics.
-`auto` retention keeps successful runs with skipped corrections.
