Add roadmap documents for the initial architecture

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

@@ -0,0 +1,131 @@
+# Checkpoint 5: D&D Spells Extractor
+
+## Status
+
+This document describes planned work, not implemented behavior.
+
+## Goal
+
+Implement the first useful extraction module: D&D spell casts from a Seriatim
+transcript source document.
+
+This checkpoint should produce the first meaningful vertical slice from real
+source input to validated artifact output.
+
+## Scope
+
+In scope:
+
+- D&D spell artifact schema and Go structs;
+- structured response schema asset;
+- prompt assets;
+- `internal/extractors/dnd/spells`;
+- source-reference and schema validators in the extractor chain;
+- fake LLM tests;
+- CLI-level integration test if the CLI path is ready.
+
+Out of scope:
+
+- D&D item extraction;
+- NPC extraction;
+- combat extraction;
+- cross-slice deduplication beyond simple deterministic merging;
+- broad D&D rules validation.
+
+## Proposed Stages
+
+### Stage 1: Spell Artifact Schema
+
+Define the D&D spell artifact model.
+
+Initial shape:
+
+```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"`
+}
+```
+
+Keep this schema inside the D&D spells extractor or a D&D artifact package, not
+inside core framework packages.
+
+### 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.
+
+Prompts should:
+
+- describe the generic source-unit input format;
+- explain that source references must use source-unit IDs;
+- avoid relying on transcript-specific fields except as optional metadata;
+- request only spell-cast artifacts.
+
+### Stage 4: Extractor Implementation
+
+Implement `internal/extractors/dnd/spells`.
+
+The extractor should:
+
+- satisfy the framework `Extractor` contract;
+- build LLM messages from a source document or source slice;
+- call the structured LLM client;
+- return artifact candidates with source references;
+- attach its validator chain.
+
+### Stage 5: Validators And Tests
+
+Wire deterministic validators:
+
+- 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;
+- 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 extract ./transcript.json --input seriatim --extractors dnd.spells --output ./artifacts.json
+```
+
+The test should use fake LLM wiring and fixture input.
+
+## Done Criteria
+
+- `go test ./...` passes.
+- Seriatim input can flow through the runner into the D&D spells extractor.
+- Spell artifacts include valid source references.
+- D&D concepts are contained in extractor/artifact packages and docs.
+- The first meaningful vertical slice is available through tests, and through
+  CLI if the CLI path is ready.
+
+## Review Questions
+
+- Is the spell extractor domain-specific without making the framework
+  D&D-specific?
+- Are source references valid and useful for downstream validation?
+- Is prompt/schema ownership clear?
+- Does this vertical slice reveal contract changes needed before adding items,
+  NPCs, or combat?