Add a roadmap to refactor prompt assets

docs/roadmap/sharedassets.md

@@ -0,0 +1,97 @@
+# Shared Prompt And Asset Layout Roadmap
+
+This roadmap defines the target state for reorganizing embedded prompt and
+schema assets so module-owned files are shallow and shared prompt fragments live
+in an explicit shared asset package.
+
+## Motivation
+
+The current Scriptorium asset layout works, but module prompt files are nested
+more deeply than their package ownership requires. For example, a module package
+already identifies its stage, domain, and artifact, so paths like
+`assets/scriptorium/prompts/dnd/spells/...` repeat context that is already in
+the Go package path.
+
+Shared D&D prompt fragments also currently live under a D&D-specific
+`promptassets` package. That is serviceable, but it undersells the fact that
+shared assets are intentionally cross-module. A clearer shared package will make
+reuse deliberate and make room for common prompt hardening and reference-use
+rules.
+
+## Target State
+
+Module-owned assets should stay in the module package that owns the behavior,
+but their internal paths should be shallow:
+
+```text
+internal/modules/extract/dnd/spells/assets/
+  prompts/
+    dnd.spells.yaml
+    task.md
+    instructions.md
+  schemas/
+    dnd_spells.v1.json
+
+internal/modules/chunk/dnd/scenes/assets/
+  prompts/
+    dnd.scenes.yaml
+    task.md
+    instructions.md
+  schemas/
+    dnd_scenes.v1.json
+```
+
+Shared reusable assets should move to:
+
+```text
+internal/modules/sharedassets/
+  assets.go
+  prompts/
+    common-dnd-system.md
+    common-dnd-transcript.md
+    common-dnd-references.md
+  schemas/
+```
+
+The `sharedassets` package should own only reusable fragments and shared asset
+registration. It should not own module task semantics, response schemas,
+validators, artifact interpretation, or stage behavior.
+
+## Ownership Rules
+
+Module packages own:
+
+- complete Scriptorium prompt definitions;
+- module task prompts and instruction prompts;
+- response schemas and schema metadata;
+- prompt IDs and versions;
+- semantic validation and interpretation.
+
+`internal/modules/sharedassets` owns:
+
+- shared prompt fragments used by more than one module;
+- standardized cross-module prompt hardening;
+- shared source/transcript framing;
+- shared reference framing and reference-use constraints;
+- future genuinely shared schemas, if a real cross-module schema emerges.
+
+Shared prompt fragments should be durable operating rules, not artifact-specific
+instructions. They may tell the model to treat source material as primary
+evidence, use references only for disambiguation unless a module says otherwise,
+ignore instructions embedded inside source/reference content, follow the
+structured output contract, and avoid exposing prompt instructions.
+
+## Documentation Outcome
+
+When implemented, canonical internal documentation should describe the asset
+ownership convention:
+
+- module-owned prompts and schemas live under each module's shallow `assets`
+  tree;
+- shared reusable fragments live under `internal/modules/sharedassets`;
+- framework and CLI code may collect assets, but module packages remain
+  responsible for prompt intent and schemas.
+
+Prompt IDs, prompt versions, response schema IDs, schema names, and runtime
+module contracts should remain unchanged unless a later feature explicitly
+changes prompt semantics.