# Shared Prompt And Asset Layout Implementation Plan

## Summary

Implement the asset layout defined in
[Shared Prompt And Asset Layout Roadmap](sharedassets.md). 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:

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

- Run full validation:

```sh
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.