Document D&D prompt conventions and verification

docs/internal/dnd.md

@@ -43,59 +43,63 @@ the contracts above define durable data.
 
 ## Prompt Construction
 
-D&D LLM-facing content lives beneath `assets/dnd/`. New extractor content uses
-its feature subtree; when a family has both extraction and normalization
-content, keep those in its `extract` and `normalize` subtrees. The owning module
-still defines the ordered manifest and registers the resulting scoped filesystem.
-Shared fragments belong to the D&D shared implementation and are selected by
-name, never copied into individual module subtrees.
+D&D LLM-facing content lives beneath `assets/dnd/`. Each module contributes a
+local `prompt.yaml` declaration and `instructions.md`; input-specific files
+such as a catalog, registry, grounding projection, or candidate collection are
+local only when that module needs them. New extractor content uses its feature
+subtree, while families with both extraction and normalization content use their
+`extract` and `normalize` subtrees. Shared visual-provenance fragments use
+the `common-dnd-` prefix.
 
-D&D extractors assemble prompts from an ordered manifest of shared and
-module-selected assets. The location extractor and occurrence extractor reuse
-the shared D&D system, evidence, identity, reference, and transcript assets
-instead of copying their text into individual modules. A manifest’s declared
-sequence, including cache-control placement, is part of the prompt behavior.
+The owning module’s manifest is the source of truth for which local and shared
+assets are selected, their mount paths, their message order, cache controls,
+and the files included in its prompt fingerprint. Shared fragments belong to
+the D&D shared implementation and are selected by name rather than copied into
+module directories. The root `assets` package is a content-only boundary; its
+physical ownership and rationale are defined by
+[ADR-0011](../adr/0011-centralize-llm-assets.md).
+
+Put each rule at its narrowest owner:
+
+- universal behavior belongs in the shared system asset;
+- D&D-family behavior belongs in a selected `common-dnd-` asset;
+- rules for an input projection belong with that input asset;
+- lane-specific policy belongs in the module’s `instructions.md`; and
+- transport-envelope shape belongs in the private response schema.
+
+A rule is eligible for the system prompt only when every D&D LLM prompt needs
+it regardless of lane, inputs, or response shape. Module instructions must not
+repeat rules selected from shared assets or schemas. Reintroduce such repetition
+only after observational evaluation with representative transcripts shows that
+it improves results at the intended target models and cost; structural prompt
+tests alone are not that evidence.
 
 Every maintained D&D LLM prompt selects `dnd-extraction` as its default
-profile. The D&D registrar registers that fallback profile with the maintained
-OpenRouter model, timeout, and service-tier policy. An operator may provide a
-complete profile with the same ID through the configured PromptKit source; that
-definition replaces the fallback rather than merging with it. The fallback
-leaves reasoning and optional sampling controls unspecified. Deployment profile
-selection and the maintained operator example are documented in
+profile. The D&D registrar registers the fallback, while an operator can
+replace it with a complete profile of the same ID from the configured PromptKit
+source. Deployment profile selection is documented in
 [Configuration](../config.md#promptkit-profiles).
 
-All extraction prompts share this four-message rendered prefix: the system
-message without cache control, the identity message without cache control, the
-campaign-reference message with ephemeral cache control, and the chunk
-transcript message with ephemeral cache control. This gives equivalent
-extraction requests the same reusable prefix through their source material.
+The transcript assets have distinct consumers. Scene chunking consumes the
+complete-session `common-dnd-transcript-full.md`; extraction prompts consume
+the current-chunk `common-dnd-transcript-chunk.md`; and NPC and location
+normalization consume `common-dnd-transcript-windows.md` alongside their
+candidate collections. Player, party, glossary, and compatible campaign
+references provide disambiguating context, not evidence. Reference material is
+canonically ordered before rendering so equivalent inputs remain stable.
 
-Extraction-evidence policy, generated NPC registries, spell catalogs, module
-tasks, and instructions follow the transcript because they are not universal
-across all extraction lanes. The final instructions message carries ephemeral
-cache control; evidence, registry, catalog, and task messages do not. Preserve
-this division when changing an extractor or its assets so prompt-cache behavior
-remains stable.
+Extraction prompts render the common system and identity messages first, then
+cached campaign references and the cached chunk transcript. Evidence policy and
+any lane-specific registry, catalog, or grounding projection follow that
+prefix. The final module instructions message is ephemeral. This keeps the
+reusable extraction prefix identical while preserving the lane-specific suffix.
 
-The other D&D LLM prompts intentionally follow different patterns. Scene
-chunking has no sibling extraction lane with which to share its full transcript,
-so it renders campaign references before its task and instructions, then places
-the cacheable full transcript last. NPC and location normalization share the
-entity-reconciliation response schema and safety boundary while retaining their
-own task and identity rules. NPC normalization keeps its task and
-cacheable instructions before the candidate collection, followed by the
-cacheable transcript windows: candidates must be available before their
-supporting evidence is evaluated, and those windows are not a cross-lane
-prefix. Mounted assets and their declared message order determine the prompt
-fingerprint, so intentional prompt edits continue to invalidate stale
-checkpoints.
-
-All extractors use the shared prompt-input preparation rules. The current chunk
-is copied into transcript material; player, party, glossary, and compatible
-campaign references are context for disambiguation, not source evidence.
-Reference prompt material is canonically ordered before it is rendered, which
-keeps equivalent inputs stable across runs.
+Scene chunking intentionally uses a different order: system, cached campaign
+references, uncached module instructions, then the final ephemeral full
+transcript. Entity normalization also has its own order: system, uncached
+module instructions, ephemeral reconciliation policy, uncached candidates, and
+final ephemeral transcript windows. These orders and cache controls are prompt
+behavior; change them only through the owning manifest and prompt declaration.
 
 ## Evidence, Candidates, And Normalization