Document validation defaults and cleanup roadmap

docs/internal/llm.md

@@ -19,9 +19,10 @@ structured output. The response also carries the raw structured output bytes
 returned by the runtime so modules can preserve raw payloads in pipeline stage
 outputs.
 
-Modules that call the LLM own their prompts, schemas, prompt IDs, validators,
-and domain-specific interpretation. Provider adapters should not contain
-domain-specific prompt logic.
+Modules that call the LLM own their prompts, schemas, prompt IDs, and
+domain-specific interpretation. Validator packages own approve/reject policy,
+and central catalog mappings decide which validators run by default. Provider
+adapters should not contain domain-specific prompt logic.
 
 Prompt input materials carry source or reference bytes with optional origin
 metadata. The Scriptorium-backed runtime receives them as named artifacts rather
@@ -43,9 +44,11 @@ The runtime records the actual selected Scriptorium profile, provider, and model
 used during execution. Manifest population does not rely on a precomputed
 profile ID before pipeline execution.
 
-Explicit profile validation and `--llm-profile` overrides apply to LLM-capable
-pipeline stages: chunk, extract, merge, and normalize. Input, output, and
-validator bindings are not part of the current production LLM profile scope.
+Explicit profile validation applies to LLM-capable pipeline stages: chunk,
+extract, merge, normalize, and LLM-backed validators with explicit
+`llm_profile` values. Input, output, and deterministic validators do not call
+the LLM. The `--llm-profile` run flag overrides effective chunk, extract, merge,
+and normalize bindings; it does not override validator-specific profiles.
 
 ## Scriptorium Adapter
 

docs/internal/modules.md

@@ -5,6 +5,9 @@ contract from `internal/framework/contracts`, exposes a `ModuleSpec`, and
 registers itself with the matching pipeline registry.
 
 The CLI production catalog currently registers only the modules listed here.
+Validator implementations live under `internal/validators` and are registered
+separately from modules. Production default validator chains are central CLI
+catalog policy; module packages do not own their default validation chains.
 
 ## Contract Pattern
 
@@ -181,6 +184,12 @@ metadata under `artifact_lanes[].metadata.extractor`. Durable raw output
 details belong in the
 [D&D spell raw output contract](../integrations/dnd-spell-artifacts.md).
 
+The production catalog validates `dnd/spells` raw extract output with generic
+JSON validators followed by D&D spell validators under
+`internal/validators/extract/dnd/spells`. The extractor itself remains
+responsible for prompt, schema, and raw output production rather than
+approve/reject policy.
+
 The `dnd/scenes` chunker and `dnd/spells` extractor declare optional `players`,
 `party`, and `glossary` reference slots accepting UTF-8 plain text, Markdown,
 YAML, or JSON. They also accept `roster` as a deprecated compatibility alias for

docs/internal/pipeline.md

@@ -75,7 +75,8 @@ prompt execution metadata.
 
 `pipeline.Registries` holds concrete constructors for execution. A
 `pipeline.ModuleCatalog` exposes module specs for config validation and
-resolution.
+resolution. The catalog also exposes validator specs and central default
+validator-chain mappings without constructing modules or validators.
 
 Every production module registers a `ModuleSpec` with:
 
@@ -91,6 +92,14 @@ instances. Input, validate, and output specs must not declare reference slots.
 
 Capability checks prevent incompatible pipeline composition before a run starts.
 
+Every production validator registers a `ValidatorSpec` with:
+
+- `Key`: validator key used in config and manifests;
+- `ExecutionClass`: `deterministic` or `llm_backed`.
+
+Default validator chains are keyed by workflow stage and module key. Production
+currently registers a default chain for `extract` module `dnd/spells` only.
+
 ## Runner Input And Output
 
 `pipeline.RunInput` carries:
@@ -118,8 +127,8 @@ The runner:
 2. builds the input adapter and parses the raw input into a source document;
 3. validates the source document;
 4. builds the chunker and produces source chunks, retrying when configured;
-5. validates source chunks against framework invariants and any registered raw
-   chunk validators;
+5. validates source chunks against framework invariants and the resolved chunk
+   validator chain;
 6. runs each selected artifact lane in sorted resolved order;
 7. builds the output encoder and validates logical output file names.
 8. passes accepted normalized raw outputs, rejected output records, warnings,
@@ -181,25 +190,38 @@ Within an artifact lane, the runner:
 
 ## Validators
 
-The current runner handoff is raw-output based. Extractors, mergers, and
+The runner handoff is raw-output based. Chunkers, extractors, mergers, and
 normalizers do not advertise validator chains through their module interfaces.
-Runner-side raw validation chains receive the raw module output plus stage,
-lane, module, source, chunk, schema, session, reference, LLM client/profile,
-binding option, and run metadata context. Merge validators also receive the
-ordered extract outputs used by the merge, and normalize validators receive the
-accepted merge output. Empty raw validation chains approve output by default.
-Response-schema provenance may include in-memory JSON schema bytes for
-validators. Those bytes are omitted from manifests, diagnostics, and encoded
-output files.
+Resolved validation chains receive the raw module output plus stage, lane,
+module, source, chunk, schema, session, reference, LLM client/profile, binding
+option, and run metadata context. Chunk validators receive the chunk result
+collection, merge validators receive the ordered extract outputs used by the
+merge, and normalize validators receive the accepted merge output. Empty chains
+approve output by default. Response-schema provenance may include in-memory JSON
+schema bytes for validators. Those bytes are omitted from manifests,
+diagnostics, and encoded output files.
 
 Resolved validator chains come from central default mappings unless a
 stage-local config override is set on `chunk`, lane `extract`, lane `merge`, or
 lane `normalize`. Explicit empty overrides are valid and are recorded as empty
-chains in manifests.
+chains in manifests. Explicit non-empty overrides replace the default chain and
+preserve configured order.
+
+The production default chain for `extract` module `dnd/spells` is:
+
+1. `generic/valid_json`
+2. `generic/valid_json_schema`
+3. `extract/dnd/spells/shape`
+4. `extract/dnd/spells/source_refs`
+5. `extract/dnd/spells/source_relatedness`
+
+No other production module currently has a default validator chain.
 
 Validator rejection is a non-fatal run outcome: the rejected output is recorded
 in `RunOutput.Rejected` and does not pass to the next stage. Validator execution
 errors are framework-level errors and retry according to the relevant binding.
+Warning-only validators return approved results with warnings; those warnings
+are promoted only from successful attempts whose outputs are used.
 
 ## Warnings And Failures