Complete Phase 10 LLM validators

docs/architecture.md

@@ -26,18 +26,20 @@ Implemented today:
 - Bounded LLM scheduler/semaphore infrastructure with context-aware permit handling.
 - Runtime primary/validation LLM effective-config resolution helpers with validation inheritance.
 - Generic JSON prompt/response diagnostics writer primitives with secret redaction.
+- LLM-backed validator models, prompt builders, batching, and runtime execution.
+- Runner wiring for LLM validators via the internal structured LLM abstraction and scheduler hooks.
+- LLM validator diagnostics artifacts and report-level decision metadata paths.
 
 Not implemented in CLI runtime path today:
 - Real module execution pipeline (`glossary`, `homophones`, `spoken_word`, `grammar`).
 - Structured LLM proposal generation.
-- LLM-backed validators.
-- Runtime module/validator usage of the LLM scheduler infrastructure.
+- Shared module proposal-generation framework and module registry for real modules.
 - End-to-end transcript polishing with real module behavior.
 
 Phase sequencing note:
 - Phase 9 LLM infrastructure is complete (structured client, scheduler, effective config resolution, diagnostics primitives);
-- runtime wiring from modules/validators/runner into this LLM infrastructure remains future module/validator phase work;
-- LLM-backed validators remain Phase 10 work.
+- Phase 10 LLM-backed validator runtime integration is complete;
+- shared module proposal-generation and module registry work remain Phase 11.
 
 ## Actual Go package layout
 
@@ -93,6 +95,10 @@ internal/framework/runner/
 internal/framework/validators/
   models.go
   deterministic.go
+  llm_models.go
+  llm_prompt_builders.go
+  llm_batching.go
+  llm_validators.go
 
 internal/framework/llm/
   instructor_client.go
@@ -122,14 +128,14 @@ Current runtime flow (`internal/cli/run.go`):
 11. Write chunking summary artifact.
 12. Optionally execute runner modules sequentially when an injected module registry/factory is available (used by deterministic tests today).
 13. Output working transcript to `--output` file or stdout.
-14. Build process report (`phase` currently set to `phase8-validators`).
+14. Build process report (`phase` currently set to `phase10-llm-validators`).
 15. Optionally write `--report-json`; always write run-dir `report.json`.
 16. Apply work-dir retention.
 
 Important behavior details:
 - Glossary is validated but not yet used for real correction module logic.
 - Default production CLI behavior remains deterministic normalization/chunking output because no real module implementations are registered yet.
-- No LLM calls occur.
+- No real LLM calls occur in the default production runtime path because no real modules are registered yet.
 - Success path is generally quiet on stderr.
 - Source IDs are preserved into a canonical transcript before normalization; normalization then reassigns output IDs sequentially from `1`.
 
@@ -193,8 +199,8 @@ Current caveat:
 - API-key redaction in adapter-returned errors.
 
 Current runtime boundary:
-- the CLI/runner runtime path does not instantiate this adapter yet;
-- no production LLM requests are performed by `audita process`.
+- the default CLI runtime path still does not instantiate real production modules, so no default end-to-end LLM polishing occurs.
+- LLM calls are exercised only when test/injected modules and validators are provided.
 
 `internal/framework/llm` also provides:
 - a bounded `Scheduler` for controlled concurrent LLM calls with reliable permit release;
@@ -256,6 +262,24 @@ These primitives are wired into the production runner and report model. Real mod
 `internal/framework/runner` executes validator chains in order for each module and applies only validator-approved proposals.
 Validator rejections are reported distinctly from proposal-application skips.
 
+## Implemented LLM-backed validator infrastructure
+`internal/framework/validators` now includes LLM-backed validator support:
+- typed request/response models for structured LLM validation;
+- prompt builders for:
+  - spoken-form plausibility
+  - meaning reversal detection
+  - editorial review
+  - grammar review
+  - spoken-word review
+- deterministic batching by `validation_max_prompt_tokens`;
+- strict cardinality validation of structured LLM decisions (missing/duplicate/unknown indexes fail);
+- safe failure behavior for malformed/invalid structured responses.
+
+`internal/framework/runner` wires LLM validators into existing validator chains using:
+- the internal structured LLM client abstraction (`contracts.StructuredLLMClient`);
+- bounded scheduler hooks for validator call execution;
+- diagnostics writer hooks for machine-readable prompt/response artifacts with secret redaction.
+
 ## Reports and diagnostics (implemented)
 Current per-run artifacts include:
 - `source-transcript.json`
@@ -285,6 +309,7 @@ Current process reports also include:
 - module-level results (when runner modules execute), including applied/skipped proposal changes;
 - run-level module summary totals and failed module instance metadata.
 - module-level validator decisions and validator rejections.
+- optional decision-level diagnostic artifact paths for validator LLM interactions when available.
 
 Retention modes implemented in `ApplyRetention`:
 - `always`: keep all run directories.
@@ -296,7 +321,7 @@ Current runtime note:
 - real module execution is not implemented yet, so normal successful runs generally have no skipped corrections and `auto` typically removes clean successful run directories.
 
 Intentionally deferred to module/LLM phases:
-- module prompt/response diagnostics artifacts are not produced yet because module execution and LLM calls are not in the runtime path.
+- module proposal-generation prompt/response diagnostics remain tied to later real-module phases.
 
 ## Current tests and quality posture
 Implemented tests currently cover:
@@ -311,8 +336,9 @@ Implemented tests currently cover:
 - runner sequencing and failure behavior with deterministic fake modules (`internal/framework/runner/*_test.go`)
 - CLI runner integration through injected fake module factories (`internal/cli/run_test.go`)
 - validator models, cardinality enforcement, and deterministic validators (`internal/framework/validators/*_test.go`)
+- LLM-backed validator batching, prompt builders, structured-response safety, scheduler hooks, and diagnostics redaction (`internal/framework/validators/*_test.go`, `internal/framework/runner/*_test.go`)
 
-Not covered yet (because not implemented): real LLM validator/runtime integration and production module behavior.
+Not covered yet (because not implemented): shared module proposal generation, real module implementations, and full transcript-polishing runtime behavior.
 
 ## Intended final architecture (not yet implemented)
 The intended end-state still matches the rewrite plan: