Refactor validators into built-in registry chains

docs/validators.md

@@ -0,0 +1,111 @@
+# Audita Validators
+
+This document describes Audita's built-in validator registry and module validator chains.
+
+## Scope
+
+Validator chains are built-in runtime behavior.
+
+Current 1.0 boundary:
+- built-in validator keys and built-in module chains are stable runtime identifiers;
+- thresholds and batching knobs remain configurable where already supported;
+- arbitrary user-defined validator chains are deferred.
+
+## Built-in validator keys
+
+### Deterministic validators
+
+- `confidence_threshold`
+  - checks proposal confidence against module-specific configured threshold.
+- `original_text_presence`
+  - ensures target segment exists and `original_text` exists in current working segment text.
+- `non_empty_corrected_text`
+  - rejects blank/whitespace-only `corrected_text`.
+- `no_effect`
+  - rejects proposals where `original_text == corrected_text`.
+- `protected_terms`
+  - protects glossary-derived terms from unsafe mutations in non-glossary modules.
+  - glossary stages use glossary-specific protection logic but still report this same stable key.
+
+### LLM-backed validators
+
+- `spoken_form_plausibility`
+  - checks whether proposed spoken-form change remains plausible in transcript context.
+- `meaning_reversal_review`
+  - checks for likely meaning reversal or semantic contradiction.
+- `editorial_review`
+  - performs conservative editorial safety review.
+- `grammar_review`
+  - checks grammar-stage proposals for grammar-focused safety constraints.
+- `spoken_word_review`
+  - checks spoken-word-stage proposals for dysfluency-cleanup safety constraints.
+
+## Built-in module chains
+
+Current built-in chains resolved from `internal/validators/chains.go`:
+
+- `glossary`
+  - `no_effect`
+  - `original_text_presence`
+  - `confidence_threshold`
+  - `protected_terms`
+  - `non_empty_corrected_text`
+  - `spoken_form_plausibility`
+  - `meaning_reversal_review`
+
+- `homophones`
+  - `no_effect`
+  - `original_text_presence`
+  - `confidence_threshold`
+  - `protected_terms`
+  - `non_empty_corrected_text`
+  - `spoken_form_plausibility`
+  - `meaning_reversal_review`
+
+- `spoken_word`
+  - `no_effect`
+  - `original_text_presence`
+  - `confidence_threshold`
+  - `protected_terms`
+  - `non_empty_corrected_text`
+  - `spoken_word_review`
+  - `meaning_reversal_review`
+
+- `grammar`
+  - `no_effect`
+  - `original_text_presence`
+  - `confidence_threshold`
+  - `protected_terms`
+  - `non_empty_corrected_text`
+  - `grammar_review`
+  - `meaning_reversal_review`
+
+## Execution semantics
+
+- modules execute serially;
+- section proposal work can run concurrently within a module;
+- deterministic validators run before LLM-backed validators;
+- malformed/missing/duplicate/unknown LLM validator decisions fail safely;
+- approved proposals are applied once per module after section work settles.
+
+## Validator rejections vs proposal-application skips
+
+- validator rejection:
+  - proposal is denied by validator-chain review and appears in validator rejection reporting with validator key and reason code.
+- proposal-application skip:
+  - proposal passed validators but could not be applied under replacement-policy semantics (for example no matching span at apply time).
+
+These are separate outcomes and are reported separately.
+
+## Reporting and diagnostics identity
+
+- report validator decision/rejection entries use stable validator keys in `validator_name`.
+- validator LLM diagnostics include validator identity in interaction metadata and structured response schema metadata.
+
+## Configurable knobs that remain supported
+
+- per-module confidence thresholds (`thresholds.*` / equivalent env+CLI overrides)
+- validation batching limits (`validation_max_prompt_tokens` / equivalent env+CLI overrides)
+- validation LLM model/base URL/timeout/retries/concurrency settings
+
+These tune validator behavior without exposing arbitrary user-defined chains.