notarius/docs/roadmap/implementation.md

Shared Prompt And Asset Layout Implementation Plan

Summary

Implement the asset layout defined in Shared Prompt And Asset Layout Roadmap. This is a structural reorganization only: prompt semantics, prompt IDs, prompt versions, response schema IDs, schema names, runtime module contracts, diagnostics policy, and manifest provenance shape must remain unchanged.

Stage 1: Introduce Shared Assets Package

• Create internal/modules/sharedassets as the cross-module shared asset package.
• Move the existing shared D&D prompt fragments from internal/modules/dnd/promptassets into internal/modules/sharedassets.
• Rename shared prompt files exactly as:
  • common-dnd-system.md
  • common-dnd-transcript.md
  • common-dnd-references.md
• Implement the shared package with the same responsibilities as the current shared prompt package:
  • embed shared prompt files;
  • register them with llm.AssetRegistry;
  • expose hash-part helpers for common shared prompts and reference prompts.
• Keep Scriptorium-visible prompt paths under the shared prompt root as common-dnd-*.md; do not preserve the old shared/*.md Scriptorium paths.
• Update production prompt asset collection in internal/cli and D&D module prompt tests to import internal/modules/sharedassets.
• Do not delete the old internal/modules/dnd/promptassets package until all callers have been updated and tests compile.

Stage 2: Flatten Module Asset Trees

• Move dnd/spells module-owned prompt assets to:
  • internal/modules/extract/dnd/spells/assets/prompts/dnd.spells.yaml
  • internal/modules/extract/dnd/spells/assets/prompts/task.md
  • internal/modules/extract/dnd/spells/assets/prompts/instructions.md
• Move dnd/scenes module-owned prompt assets to:
  • internal/modules/chunk/dnd/scenes/assets/prompts/dnd.scenes.yaml
  • internal/modules/chunk/dnd/scenes/assets/prompts/task.md
  • internal/modules/chunk/dnd/scenes/assets/prompts/instructions.md
• Keep module schemas under each module's existing shallow schema directory:
  • assets/schemas/dnd_spells.v1.json
  • assets/schemas/dnd_scenes.v1.json
• Update each module's go:embed patterns to include only the new shallow prompt and schema paths.
• Update each module's prompt registration root from the old assets/scriptorium/prompts tree to assets/prompts.
• Update prompt hash inputs to point at the new module prompt paths and the new shared asset hash parts.

Stage 3: Update Scriptorium Prompt Definitions

• Update dnd.spells.yaml and dnd.scenes.yaml to use the new shallow content_file paths.
• Shared prompt references must point to:
  • ./common-dnd-system.md
  • ./common-dnd-transcript.md
  • ./common-dnd-references.md
• Module prompt references must point to:
  • ./task.md
  • ./instructions.md
• Keep all existing prompt IDs, prompt versions, default profiles, inputs, cache-control settings, output schema paths, validation modes, and repair attempts unchanged.
• Confirm the flattened module prompt roots and shared prompt roots combine into one Scriptorium prompt filesystem without duplicate asset paths.

Stage 4: Remove Old Package And Update Docs

• Delete internal/modules/dnd/promptassets after all imports and asset references are gone.
• Update canonical current-behavior docs to describe the new convention:
  • module-owned prompts and schemas live under each module's shallow assets/prompts and assets/schemas directories;
  • shared reusable prompt fragments live under internal/modules/sharedassets;
  • framework and CLI code may collect assets, but modules still own prompt intent, prompt IDs, schemas, and interpretation.
• Keep roadmap docs as future/target-state material only; do not describe completed behavior in docs/roadmap/ until the implementation is complete.

Stage 5: Verification

• Update focused tests that assert asset paths, prepared prompt message content, prompt hash metadata, or import paths.
• Add or preserve coverage proving:
  • production prompt asset registration includes shared assets, dnd/scenes assets, and dnd/spells assets;
  • Scriptorium can prepare both D&D prompts using the moved assets;
  • prompt and schema hashes remain present in module manifest metadata;
  • raw source input, references, prompt text, and schema JSON still do not leak into default diagnostics or manifests.
• Run focused validation:

go test ./internal/framework/llm
go test ./internal/modules/chunk/dnd/scenes ./internal/modules/extract/dnd/spells
go test ./internal/cli

• Run full validation:

go test ./...
go vet ./...
go build ./cmd/notarius

Assumptions

• This migration is allowed to change internal asset paths because prompt assets are embedded implementation details, not public API.
• Prompt IDs, versions, schema IDs, schema names, runtime request contracts, and output manifest shape are stable and must not change in this pass.
• internal/modules/sharedassets may contain D&D-specific reusable prompt fragments when filenames make the domain scope explicit.
• Shared assets should contain durable operating rules and reusable framing, not module-specific extraction, chunking, normalization, or validation semantics.