Plan scene-aware combat extraction

docs/roadmap/scene-aware-combat-extraction.md

@@ -0,0 +1,189 @@
+# Scene-Aware Combat Extraction
+
+## Status
+
+Proposed near-term scope.
+
+## Purpose
+
+Use an accepted D&D scene-description artifact as the eligibility boundary for
+combat-turn extraction. The combat LLM should run only for a chunk whose exact
+scene record has `kind: combat`; every other chunk should be ignored by the
+combat extractor. This work should connect the existing scene-description lane,
+ordered generated-reference handoff, and combat-turn lane without expanding the
+minimal combat-turn artifact contract or introducing D&D policy into generic
+pipeline code.
+
+## Target Workflow
+
+The complete D&D pipeline has two ordered steps:
+
+1. The first step extracts and normalizes NPCs and scene descriptions for the
+   accepted scene chunks.
+2. At the step barrier, the accepted NPC and scene-description artifacts become
+   generated references.
+3. The second step supplies the NPC artifact to its existing consumers and the
+   scene-description artifact to combat-turn extraction.
+4. For each chunk, combat-turn extraction performs its existing LLM extraction
+   only for an exact `combat` classification. Every other chunk produces a
+   deterministic empty artifact without an LLM call.
+
+The scene-description dependency must remain explicit in pipeline
+configuration. The combat extractor must not discover another lane implicitly,
+read output files directly, inspect chunker-private state, or require generic
+chunk materialization to interpret D&D scene classifications.
+
+## Scene-Description Reference Contract
+
+The combat extractor should declare a required structured reference slot named
+`scene_descriptions`. The slot accepts one approved
+`dnd/scene-description-list` artifact using the existing durable scene
+description schema.
+
+The reference may be supplied as:
+
+- a generated artifact from an earlier ordered step; or
+- an external artifact through the existing reference-materialization
+  boundary.
+
+External artifacts must be decoded and validated before source parsing or LLM
+execution. Generated artifacts must cross the existing typed step-handoff
+boundary and be validated before use. A bound artifact that is malformed,
+incompatible, or internally inconsistent is an error; it must not be treated as
+though the slot were unbound.
+
+Pipeline resolution must reject combat extraction when this slot is not bound.
+In an ordered same-run workflow, failure of the configured scene-description
+producer to yield an accepted normalized artifact must fail the run before the
+combat consumer step starts, consistent with existing required generated
+reference semantics.
+
+The prepared reference view should be immutable and safe for concurrent
+extract jobs. Its metadata and checkpoint identity should be content-safe and
+must not expose scene titles, summaries, paths, or source text.
+
+## Chunk Matching And Gating Policy
+
+A scene record authorizes combat extraction for the current chunk only when all
+of the following are true:
+
+- the scene ID exactly equals the current accepted chunk ID;
+- the scene source ID exactly equals the chunk source ID;
+- the scene start and end unit IDs exactly equal the chunk's inclusive source
+  range; and
+- the approved artifact contains exactly one such record.
+
+The normalized scene-description contract already rejects conflicting IDs and
+ranges. The combat extractor must nevertheless require the exact match above at
+its own decision boundary rather than relying on array position, range overlap,
+title, summary, or inferred chronology.
+
+An exact match with `kind: combat` performs the existing combat-turn LLM
+extraction. An exact match with `narrative`, `recap`, or `meta` returns a typed
+`dnd/combat-turn-list` containing an empty `combat_turns` array without making
+an LLM call.
+
+A valid artifact with no exact match, incomplete coverage, or a chunk identity
+or range mismatch also returns the deterministic empty artifact. It must not
+infer combat eligibility from an overlapping or adjacent scene. Emit a bounded,
+content-safe warning for missing or mismatched coverage so operators can
+distinguish an intentional non-combat classification from an unavailable exact
+classification. The warning must not include scene prose or transcript text.
+
+This policy relies on the scene contract's mixed-scene precedence: any chunk in
+which combat is a substantive central activity is classified as `combat`.
+Scene-aware gating must not add a second classification policy.
+
+## Extraction, Validation, And Provenance
+
+The deterministic empty result follows the same typed extractor and validator
+boundaries as an LLM-produced empty result. It is not a rejection, does not
+consume retry budget, and continues through merge and normalization normally.
+The durable combat-turn schema remains unchanged.
+
+Existing combat extraction behavior—including prompt assets, NPC grounding,
+candidate mapping, validators, retries, warnings, and normalization—remains
+unchanged for chunks classified as combat. The scene-description artifact is
+control context only:
+
+- it must not be added to the combat prompt;
+- its title or summary must not become combat evidence;
+- its source references must not be copied into combat turns; and
+- it must not create, repair, or classify a combat turn.
+
+Generated-reference provenance and dependency fingerprints should cover the
+scene artifact through the existing ordered-handoff machinery. External
+references should contribute their existing materialization provenance plus a
+component-local semantic fingerprint sufficient to invalidate combat extract
+checkpoints when a classification or chunk identity changes. Checkpoint reuse
+must never preserve a skipped result after the effective scene classification
+changes.
+
+Run manifests may report bounded module metadata such as the number of approved
+scene records. They must not contain scene prose or duplicate the referenced
+artifact payload.
+
+## Configuration And Documentation
+
+The maintained complete D&D example should bind the normalized
+`scene-descriptions` lane from the first step to the `scene_descriptions` slot
+in the second step. The minimal example should remain unchanged.
+
+When implemented, current-behavior documentation should be updated in its
+canonical locations:
+
+- Configuration owns the new selectable reference slot and binding example.
+- Operations owns the ordered scene-aware workflow.
+- The combat-turn integration contract owns externally observable extraction,
+  empty-result, and provenance behavior.
+- Internal pipeline and module documentation own preparation, handoff, matching,
+  and checkpoint mechanics.
+- `future.md` should remove the completed scene-aware combat item.
+
+## Quality Expectations
+
+Tests should protect behavior and architectural boundaries rather than internal
+helper shape. Coverage should demonstrate:
+
+- exact non-combat matches produce accepted empty combat artifacts without an
+  LLM call;
+- exact combat matches retain the existing LLM path;
+- an unbound required reference is rejected during pipeline resolution;
+- missing and mismatched chunk coverage produces an accepted empty combat
+  artifact without an LLM call and emits a bounded warning;
+- malformed external and generated artifacts fail at the appropriate
+  preparation or handoff boundary;
+- retries are neither consumed nor attempted for deterministic skips;
+- scene artifact changes invalidate relevant checkpoint reuse;
+- no scene prose is exposed through combat prompts, warnings, metadata, or
+  manifests; and
+- the complete maintained configuration resolves and materializes the intended
+  ordered dependency.
+
+Model-output fixtures should remain deterministic test doubles. This feature
+does not require live-provider tests or assertions over probabilistic model
+quality.
+
+## Non-Goals
+
+This scope does not:
+
+- change the durable scene-description or combat-turn schemas;
+- add scene fields to combat-turn artifacts;
+- annotate generic chunks with D&D classifications;
+- make the combat lane depend implicitly on the scene-description lane;
+- skip spell, NPC, NPC-interaction, or scene-description extraction;
+- infer combat from scene titles, summaries, overlap, or campaign references;
+- introduce arbitrary DAG scheduling or concurrent cross-step execution;
+- add prior-run artifact discovery or new reference syntax; or
+- add an LLM-backed validator, repair pass, or generic deduplication stage.
+
+## Completion Criteria
+
+The scope is complete when an explicitly configured ordered D&D pipeline can
+hand an approved scene-description artifact to combat extraction, exact
+`combat` scene matches are the only chunks that invoke the combat LLM, every
+other chunk produces a deterministic empty result, provenance and checkpoint
+identity remain correct, the complete example demonstrates the workflow, and
+the canonical current-behavior documentation reflects the implemented
+contract.