notarius/docs/roadmap/dnd.md

D&D Shared Module Helper Roadmap

This roadmap defines the target state for consolidating Dungeons & Dragons helper code that is currently duplicated across the implemented D&D modules. The refactor should preserve runtime behavior: module keys, prompt IDs, prompt versions, Scriptorium-visible prompt files, message order, response schemas, reference slot compatibility, manifests, diagnostics policy, and CLI/config semantics should not change.

Motivation

The dnd/scenes chunker and dnd/spells extractor now share several D&D prompt and reference conventions:

• prompt inputs named transcript, players, party, and glossary;
• deprecated roster reference bindings mapped to the party prompt input;
• D&D reference media-type declarations;
• deterministic rendering of one or more reference files into prompt input materials;
• shared D&D prompt fragments currently under internal/modules/sharedassets;
• prompt hash inclusion for shared D&D prompt fragments.

Keeping this logic duplicated makes future D&D modules more likely to drift. It also makes small prompt-contract changes expensive because each module must update the same reference-slot, prompt-input, and test helper behavior.

Target Package Boundary

D&D-specific shared helpers should live under:

internal/modules/sharedassets/dnd

The package name should be dnd. This keeps generic shared asset plumbing in internal/modules/sharedassets while giving D&D-specific prompt and reference policy a clear home.

internal/modules/sharedassets should continue to own:

• generic shared prompt asset registration;
• ModulePromptFS and related prompt filesystem layout helpers;
• non-domain-specific embedded asset plumbing;
• future prompt assets only when they are truly domain-neutral.

internal/modules/sharedassets/dnd should own D&D-specific reusable helpers:

• D&D shared prompt fragments;
• accepted reference media types for D&D reference slots;
• reference slot definitions for players, party, glossary, and the deprecated roster alias;
• prompt input assembly for D&D modules that use the shared prompt fragments;
• deterministic reference material rendering;
• shared D&D prompt hash parts.

Concrete D&D modules should continue to own:

• stage contracts and module registration;
• module keys and provided/required capabilities;
• prompt IDs and prompt versions;
• module-local prompt definitions, task prompts, and instruction prompts;
• response schema definitions and schema metadata;
• artifact interpretation, scene interpretation, validators, and output conversion.

Framework, core, and CLI packages must not import internal/modules/sharedassets/dnd.

The intended asset layout is:

internal/modules/sharedassets/
  assets.go
  prompt_fs.go

internal/modules/sharedassets/dnd/
  assets.go
  prompt_inputs.go
  references.go
  assets/
    prompts/
      common-dnd-system.md
      common-dnd-transcript.md
      common-dnd-references.md

The parent sharedassets package should have no hard-coded knowledge of common-dnd-* files. It should provide generic composition primitives that a domain package such as sharedassets/dnd can use.

Desired End State

The dnd/scenes and dnd/spells modules should remain small owners of their stage-specific behavior. Shared D&D helpers should remove duplicated mechanics without hiding module semantics.

After the refactor:

• both modules should call one shared helper to build the D&D prompt input set from source input and resolved references;
• both modules should use one shared source of truth for D&D reference slots and accepted media types;
• D&D shared prompt files should live in internal/modules/sharedassets/dnd beside the code that owns the D&D prompt contract;
• generic shared asset plumbing should compose caller-provided shared prompt files without knowing which domain owns them;
• deprecated roster bindings should continue to work as an alias for party;
• reference rendering behavior should remain deterministic and covered by tests in the shared D&D helper package;
• real prompt asset tests should remain decoupled from exact embedded prompt prose;
• D&D module tests should focus on module contracts, request construction, response interpretation, validators, diagnostics, and manifest metadata rather than duplicate reference rendering details.

Documentation Outcome

Current-behavior docs should describe the D&D shared helper package only where it helps future maintainers understand ownership:

• Internal Modules should mention that common D&D prompt/reference helper behavior lives under internal/modules/sharedassets/dnd.
• Internal Overview may mention the package if it lists shared module-support packages.

User-facing docs should not describe internal helper placement unless behavior visible to users changes. This refactor should not change visible behavior.

Resolved Decisions

Should generic reference-slot cloning move to contracts?

Decision: move generic cloning to internal/framework/contracts, for example as CloneReferenceSlots. The operation is not D&D-specific and exists because contracts.ReferenceSlot contains mutable slices. Keeping the clone helper with the contract type makes defensive copying easier to reuse in future modules without introducing domain imports.

Should shared D&D prompt hash parts move into sharedassets/dnd?

Decision: move D&D shared prompt hash helpers into internal/modules/sharedassets/dnd. The hash parts are D&D-specific prompt provenance, and placing them beside the D&D prompt contract reduces drift.

Should D&D shared prompt assets move into sharedassets/dnd?

Decision: move D&D shared prompt assets into internal/modules/sharedassets/dnd/assets/prompts. The current common-dnd-system.md, common-dnd-transcript.md, and common-dnd-references.md files are not truly generic; they are part of the D&D prompt contract. Keeping the files beside D&D reference slots, prompt input assembly, reference rendering, and prompt hash helpers gives the package clear ownership of reusable D&D prompt behavior.

The parent internal/modules/sharedassets package may still contain prompt assets in the future, but only when they are genuinely domain-neutral.