Plan D&D spells extractor implementation

docs/roadmap/6-dnd-spells-extractor.md

@@ -23,7 +23,7 @@ In scope:
 - module metadata/capability requirements for pipeline validation;
 - source-reference and schema validators in the extractor chain;
 - fake LLM tests;
-- CLI-level integration test if the CLI path is ready.
+- runner-level integration tests with fake infrastructure.
 
 Out of scope:
 
@@ -31,89 +31,71 @@ Out of scope:
 - NPC extraction;
 - combat extraction;
 - cross-slice deduplication beyond simple deterministic merging;
-- broad D&D rules validation.
+- broad D&D rules validation;
+- a `notarius run` command.
 
-## Proposed Stages
+## Target End State
 
-### Stage 1: Spell Artifact Schema
+The repository should contain a real D&D spells extract-stage module at
+`internal/modules/extract/dnd/spells`.
 
-Define the D&D spell artifact model.
+The spells module should be registered under the stable extractor key
+`dnd/spells`. It should be selectable as a named artifact lane in pipeline
+configuration, for example a lane named `spells` whose extractor module is
+`dnd/spells`.
 
-Initial shape:
+The module should translate generic source chunks into spell-cast artifact
+candidates with this spell payload:
 
-```go
-type SpellCast struct {
-    Player               string      `json:"player"`
-    Spell                string      `json:"spell"`
-    Effect               string      `json:"effect"`
-    NarrativeDescription string      `json:"narrative_description"`
-    SourceRefs           []SourceRef `json:"source_refs"`
-}
-```
+- `caster`;
+- `spell`;
+- `effect`;
+- `narrative_description`.
 
-Keep this schema inside the D&D spells extract module or a D&D artifact package,
-not inside core framework packages.
+The LLM structured response should also include source references for each
+spell cast. The extractor should copy those references into the generic
+artifact envelope rather than duplicating source references inside the durable
+spell payload.
 
-### Stage 2: Structured Response Schema
-
-Add a structured response schema asset for spell extraction.
-
-The schema should require:
-
-- spell-cast array;
-- non-empty player, spell, effect, and narrative description fields;
-- at least one source reference per spell cast.
-
-### Stage 3: Prompt Assets
-
-Add embedded prompt assets for D&D spell extraction.
+The caster is the in-world character or creature casting the spell, not the
+table speaker. Speaker metadata from transcript source units may be used as
+optional prompt context when present, but it should not be a required or durable
+field in the spell payload.
 
 Prompts should:
 
 - describe the generic source-unit input format;
-- explain that source references must use source-unit IDs;
+- explain that source references must use source-unit IDs exactly;
 - avoid relying on transcript-specific fields except as optional metadata;
-- request only spell-cast artifacts.
+- request only D&D spell-cast artifacts.
 
-### Stage 4: Process Module Implementation
+The extractor should attach deterministic validators by default. Validation
+should cover:
 
-Implement `internal/modules/extract/dnd/spells`.
+- spell payload shape;
+- non-empty required spell fields;
+- at least one source reference per spell cast;
+- source references that validate against the source document.
 
-The extractor should:
+The module should declare flat capabilities for pipeline validation. Initial
+capabilities should require chunked transcript source material and provide a
+D&D spell-cast artifact capability.
 
-- satisfy the framework `Extractor` contract;
-- declare module metadata for pipeline-profile validation;
-- build LLM messages from a source document or source chunk;
-- call the structured LLM client;
-- return artifact candidates with source references;
-- attach its validator chain.
+Implementation staging belongs in
+[`implementation.md`](implementation.md).
 
-### Stage 5: Validators And Tests
+## Fixtures And Tests
 
-Wire deterministic validators:
+The checkpoint should add synthetic fixtures and focused tests for:
 
-- schema/shape validation;
-- source-reference validation;
-- required-field validation if not covered by schema handling.
-
-Add tests using a fake structured LLM client:
-
-- successful spell extraction;
-- empty result;
-- invalid source reference rejection;
+- successful spell extraction with a fake structured LLM client;
+- empty spell-cast results;
 - malformed structured output handling;
-- stable output ordering.
-
-### Stage 6: CLI Integration
-
-If the CLI path is ready, add an end-to-end test using:
-
-```sh
-notarius run dnd-session --input ./transcript.json --only spells
-```
-
-The test should use fake LLM wiring, fixture input, and a named pipeline profile
-with a `spells` artifact lane.
+- invalid source-reference rejection;
+- stable output ordering;
+- pipeline-profile selection of a `spells` artifact lane;
+- runner integration from Seriatim input through the spells extractor using
+  fake chunk and output modules.
 
 ## Done Criteria
 
@@ -123,8 +105,8 @@ with a `spells` artifact lane.
 - D&D concepts are contained in extract module/artifact packages and docs.
 - The spells module can be selected as a named artifact lane in pipeline
   configuration.
-- The first meaningful vertical slice is available through tests, and through
-  CLI if the CLI path is ready.
+- The first meaningful vertical slice is available through tests.
+- No CLI `run` behavior is documented or implemented until the CLI path exists.
 
 ## Review Questions