Add a feature roadmap and staged implementation plan to refactor shared D&D module assets

2026-07-06 12:03:49 -05:00
parent 47cf7e76ec
commit 7861d040df
4 changed files with 445 additions and 74 deletions
--- a/docs/roadmap/implementation.md
+++ b/docs/roadmap/implementation.md
@@ -1,19 +1,277 @@
-# Completed Shared Asset Layout Follow-Up
+# D&D Shared Helper Refactor Implementation Plan

-The shared prompt and asset layout reorganization is complete.
+## Summary

-Implemented behavior is documented in canonical current-behavior docs:
+Implement the target state defined in
+[D&D Shared Module Helper Roadmap](dnd.md). This is an internal refactor: do not
+change module keys, prompt IDs, prompt versions, Scriptorium-visible message
+order, response schema IDs or names, CLI/config semantics, manifest shape,
+diagnostics redaction policy, or D&D scene/spell interpretation behavior.

- [Internal Overview](../internal/overview.md)
- [Internal LLM Runtime](../internal/llm.md)
- [Internal Modules](../internal/modules.md)
+The intended package split is:

-## Implemented Outcomes
+- `internal/modules/sharedassets`: generic prompt filesystem composition and
+  non-domain-specific asset plumbing only;
+- `internal/modules/sharedassets/dnd`: reusable D&D prompt assets, prompt input
+  helpers, reference slot helpers, reference rendering, and D&D shared prompt
+  hash parts;
+- concrete D&D modules: stage contracts, module registration, module-local
+  prompt definitions, response schemas, validators, and response
+  interpretation.

- module-owned prompts and schemas use shallow module-local asset trees;
- reusable D&D prompt fragments live under `internal/modules/sharedassets`;
- shared prompt filesystem composition is centralized in `sharedassets`;
- D&D scene and spell modules no longer carry duplicated prompt filesystem
-  helper implementations.
+## Stage 1: Add Generic Defensive-Copy Helper

-Remaining future work belongs in [Future Work](future.md).
+- Add `CloneReferenceSlots` to `internal/framework/contracts`.
+- The helper must:
+  - return `nil` for an empty input slice;
+  - allocate a new slot slice;
+  - deep-copy each `AcceptedMediaTypes` slice;
+  - preserve all other `ReferenceSlot` fields exactly.
+- Add focused tests in `internal/framework/contracts` proving nil/empty
+  behavior, deep-copy behavior, and full field preservation.
+- Do not import any concrete module package from `contracts`.
+
+## Stage 2: Make Shared Prompt FS Composition Domain-Neutral
+
+- Refactor `internal/modules/sharedassets.ModulePromptFS` so the parent package
+  no longer knows about D&D prompt filenames or embedded D&D assets.
+- Add a generic shared prompt file descriptor:
+
+```go
+type SharedPromptFile struct {
+    Name string
+    FS   fs.FS
+    Path string
+}
+```
+
+- Change `ModulePromptFS` to this shape:
+
+```go
+func ModulePromptFS(
+    moduleDir string,
+    moduleFS fs.FS,
+    files []ModulePromptFile,
+    sharedFiles ...SharedPromptFile,
+) (fs.FS, error)
+```
+
+- Keep existing `ModulePromptFile` semantics:
+  - `Name` is mounted directly under `assets/prompts/<moduleDir>/`;
+  - `Path` is read from the module embedded filesystem.
+- Mount each `SharedPromptFile` under
+  `assets/prompts/<moduleDir>/sharedassets/<Name>`.
+- Validate all names and paths with contextual errors:
+  - `moduleDir` must be a valid non-root fs path;
+  - module prompt `Name` must be a single filename with no path separators;
+  - shared prompt `Name` must be a single filename with no path separators;
+  - `moduleFS` and each shared file `FS` must be non-nil;
+  - missing module or shared files must return errors naming the source path.
+- Preserve the in-memory FS behavior currently covered by tests, including
+  readable intermediate directories and root `.` support.
+- Update `internal/modules/sharedassets` tests so they use test-owned shared
+  prompt files from `fstest.MapFS`, not production D&D prompt assets.
+- Remove D&D-specific helpers, constants, and embedded asset dependencies from
+  the parent `sharedassets` package.
+
+## Stage 3: Create `sharedassets/dnd`
+
+- Create `internal/modules/sharedassets/dnd` with package name `dnd`.
+- Move the current D&D shared prompt files into:
+
+```text
+internal/modules/sharedassets/dnd/assets/prompts/common-dnd-system.md
+internal/modules/sharedassets/dnd/assets/prompts/common-dnd-transcript.md
+internal/modules/sharedassets/dnd/assets/prompts/common-dnd-references.md
+```
+
+- Add `assets.go` in the D&D package with `go:embed assets/prompts/*.md`.
+- Expose D&D shared asset helpers:
+
+```go
+func SharedPromptFiles() []sharedassets.SharedPromptFile
+func CommonHashParts() []llm.AssetHashPart
+func ReferenceHashParts() []llm.AssetHashPart
+func ModulePromptFS(moduleDir string, moduleFS fs.FS, files []sharedassets.ModulePromptFile) (fs.FS, error)
+```
+
+- `SharedPromptFiles` must return a new slice each call.
+- `CommonHashParts` must include `common-dnd-system.md` and
+  `common-dnd-transcript.md`.
+- `ReferenceHashParts` must include `common-dnd-references.md`.
+- `ModulePromptFS` must call `sharedassets.ModulePromptFS` with
+  `SharedPromptFiles()...`.
+- Do not expose a D&D package registration function unless a concrete caller
+  needs top-level D&D shared prompt files outside module-local prompt
+  composition. The D&D prompt definitions should continue to load shared files
+  through `./sharedassets/...` inside each module prompt directory.
+
+## Stage 4: Add D&D Reference And Prompt Input Helpers
+
+- In `internal/modules/sharedassets/dnd`, add D&D reference helpers:
+
+```go
+type ReferenceSlotDescriptions struct {
+    Glossary string
+    Party    string
+    Players  string
+    Roster   string
+}
+
+func ReferenceMediaTypes() []string
+func ReferenceSlots(descriptions ReferenceSlotDescriptions) []contracts.ReferenceSlot
+```
+
+- `ReferenceMediaTypes` must return a defensive copy of:
+  - `application/json`
+  - `application/x-yaml`
+  - `application/yaml`
+  - `text/markdown`
+  - `text/plain`
+- `ReferenceSlots` must return slots in the same order currently exposed by
+  both D&D modules: `glossary`, `party`, `players`, `roster`.
+- Slot names and alias semantics must remain unchanged.
+- Slot descriptions should be supplied by each concrete module through
+  `ReferenceSlotDescriptions` so current module metadata text can be preserved.
+- `ReferenceSlots` must use `contracts.CloneReferenceSlots` or equivalent
+  defensive-copy behavior before returning.
+
+- Add prompt input helpers:
+
+```go
+func PromptInputs(sourceInput contracts.LLMInputMaterial, references contracts.ReferenceSet) contracts.LLMInputSet
+func TranscriptPromptMaterial(material contracts.LLMInputMaterial) contracts.LLMInputMaterial
+func ReferencePromptMaterial(name string, slot contracts.ResolvedReferenceSlot) contracts.LLMInputMaterial
+func ReferencePromptInput(slot contracts.ResolvedReferenceSlot) []byte
+```
+
+- `PromptInputs` must return inputs named `transcript`, `players`, `party`, and
+  `glossary`.
+- If `party` has no items and `roster` has items, `PromptInputs` must use the
+  `roster` slot content for the `party` input.
+- `PromptInputs` must not include a `roster` prompt input.
+- `TranscriptPromptMaterial` must clone the source input and set `Name` to
+  `transcript`.
+- `ReferencePromptMaterial` must use media type `text/plain`; for a single
+  reference item it must propagate that item's digest and origin URI.
+- `ReferencePromptInput` behavior must match current D&D module behavior:
+  - empty slot renders as a single space;
+  - one item renders as raw item content;
+  - multiple items are copied, sorted deterministically by origin URI, digest,
+    then content, and rendered with the same heading/metadata format currently
+    used by `dnd/scenes` and `dnd/spells`.
+
+- Add focused tests under `internal/modules/sharedassets/dnd` for all helper
+  behavior. These tests may assert rendering of helper-owned fixture inputs, but
+  must not assert exact production embedded prompt prose.
+
+## Stage 5: Update D&D Modules To Use Shared Helpers
+
+- Update `internal/modules/chunk/dnd/scenes`:
+  - import `internal/modules/sharedassets/dnd`;
+  - replace local accepted media type and slot cloning logic with
+    `dnd.ReferenceSlots`;
+  - preserve existing scene-specific slot descriptions;
+  - replace local prompt input/reference rendering helpers with
+    `dnd.PromptInputs`;
+  - replace `sharedassets.ModulePromptFS` with `dnd.ModulePromptFS`;
+  - replace `sharedassets.CommonHashParts` and `ReferenceHashParts` with the
+    D&D package equivalents.
+- Update `internal/modules/extract/dnd/spells` the same way, preserving current
+  extractor-specific slot descriptions.
+- Delete local duplicated helper functions that become unused:
+  - `acceptedReferenceMediaTypes`;
+  - `cloneReferenceSlots`;
+  - `transcriptPromptInput`;
+  - `referencePromptMaterial`;
+  - `referencePromptInput`.
+- Keep module-local schema loading, prompt IDs, prompt versions, validators,
+  request validation, response conversion, and manifest metadata ownership in
+  each concrete module.
+
+## Stage 6: Update Asset Registration And Tests
+
+- Update production prompt asset registration in `internal/cli` as needed:
+  - remove any call that registers D&D shared prompt files from the generic
+    `sharedassets` package;
+  - ensure `dnd/scenes` and `dnd/spells` prompt registration still makes their
+    module-local `./sharedassets/common-dnd-*.md` files available.
+- Update production prompt asset tests so they assert module-local shared asset
+  paths such as:
+  - `dnd.scenes/sharedassets/common-dnd-system.md`
+  - `dnd.spells/sharedassets/common-dnd-system.md`
+- Remove expectations for top-level `common-dnd-*.md` prompt files unless a
+  genuine top-level registration remains necessary.
+- Move reference rendering tests from concrete D&D modules into
+  `internal/modules/sharedassets/dnd`.
+- Keep concrete D&D module tests focused on:
+  - module specs and registry behavior;
+  - LLM request prompt ID/version/profile/session fields;
+  - transcript and reference input propagation;
+  - Scriptorium prompt preparation;
+  - diagnostics redaction;
+  - manifest metadata;
+  - scene/spell response interpretation.
+- Follow the prompt asset testing policy in `docs/policy/development.md`: do
+  not assert exact production embedded prompt prose.
+
+## Stage 7: Update Documentation
+
+- Update canonical internal docs for implemented behavior:
+  - `docs/internal/modules.md`: mention that common D&D prompt/reference helper
+    behavior lives under `internal/modules/sharedassets/dnd`;
+  - `docs/internal/overview.md`: mention the package only if the overview lists
+    shared module-support packages.
+- Do not add user-facing documentation unless visible behavior changes.
+- Update `docs/roadmap/dnd.md` after implementation so it no longer presents
+  this refactor as future work.
+- Replace this file with a concise completed-note document once the work is
+  implemented.
+
+## Validation
+
+Run focused tests after each meaningful stage:
+
+```sh
+go test ./internal/framework/contracts
+go test ./internal/modules/sharedassets
+go test ./internal/modules/sharedassets/dnd
+go test ./internal/modules/chunk/dnd/scenes
+go test ./internal/modules/extract/dnd/spells
+go test ./internal/cli
+```
+
+Run full validation before completion:
+
+```sh
+go test ./...
+go vet ./...
+go build ./cmd/notarius
+```
+
+Run inspection searches:
+
+```sh
+rg -n "common-dnd|CommonHashParts|ReferenceHashParts|referencePromptInput|cloneReferenceSlots|acceptedReferenceMediaTypes" internal/modules internal/framework
+rg -n "Divide the provided transcript|Extract Dungeons & Dragons spell-cast artifacts|A transcript of a Dungeons & Dragons gameplay session|Roster reference|Glossary reference" internal/**/*_test.go
+```
+
+Expected inspection outcomes:
+
+- D&D shared prompt files and hash helpers are owned by
+  `internal/modules/sharedassets/dnd`;
+- parent `sharedassets` has no hard-coded `common-dnd-*` knowledge;
+- concrete D&D modules no longer carry duplicated reference rendering logic;
+- tests do not assert exact production embedded prompt prose.
+
+## Non-Goals
+
+- Do not change D&D prompt wording except for file moves required by this
+  refactor.
+- Do not change prompt IDs, prompt versions, profile defaults, Scriptorium
+  message order, schema files, schema metadata, module keys, capabilities,
+  manifest shapes, or diagnostics policy.
+- Do not move scene boundary logic, spell artifact logic, validators, or schema
+  loading into the shared D&D package.
+- Do not make framework, core, or CLI packages depend on
+  `internal/modules/sharedassets/dnd`.