diff --git a/docs/roadmap/glossary-stages.md b/docs/roadmap/glossary-stages.md index c7d2202..65a9439 100644 --- a/docs/roadmap/glossary-stages.md +++ b/docs/roadmap/glossary-stages.md @@ -123,6 +123,84 @@ appropriate filesystem context, and an underlay places its contributions in a lower-priority tier. Resolve that provisioning choice below without changing ConfigKit's import semantics. +### Shared Libraries and Campaign Vocabulary — Resolved + +As a campaign maintainer, I can compose a reusable, versioned D&D glossary +library with campaign-specific vocabulary without editing the shared definitions. +I can select different combinations for focused correction passes while +protecting the selected vocabulary throughout the pipeline. + +Use stable, descriptive collection names independent of filenames. For example: + +| Shared collections | Campaign collections | +| --- | --- | +| `dnd5e.spells` | `campaign.party` | +| `forgotten_realms.places` | `campaign.npcs` | +| `dnd5e.creatures` | `campaign.places` | + +These are literal mapping keys. Dots are a naming convention, not nested lookup +or another reference language; this convention does not restrict other valid +collection names. A shared document declares the same key wherever it is used. + +One practical project layout is: + +```text +campaign/ + audita.yml + glossaries/ + shared/ + dnd5e/ + spells.yml + creatures.yml + forgotten-realms/ + places.yml + campaign/ + party.yml + npcs.yml + places.yml +``` + +The recursive import above discovers both groups through ConfigKit. A vendored +library release or pinned checkout inside the configuration tree lets each +campaign adopt shared updates deliberately and independently. Library distribution +and revision management remain outside Audita; it consumes local configuration +sources through native imports. This layout fits the native import-root model +without adding cross-directory discovery conventions. + +Importing collections makes them available; selections determine their use. +For example, the campaign can select the following vocabulary and focused passes: + +```yaml +glossaries: + - dnd5e.spells + - forgotten_realms.places + - campaign.party + - campaign.npcs + - campaign.places + +pipeline: + stages: + - module: glossary + glossaries: [campaign.party, campaign.npcs] + - module: glossary + glossaries: [dnd5e.spells] + - module: glossary + glossaries: [forgotten_realms.places, campaign.places] + - module: grammar +``` + +With `protected_terms` omitted, root protection derives from that selection. +Each glossary stage exempts its active vocabulary; grammar protects the complete +selection. An available but unselected collection such as `dnd5e.creatures` does +not automatically enter prompt inputs or protected vocabulary. Imported sources +still undergo normal ConfigKit composition and validation. + +Add new campaign vocabulary in campaign collections and select it alongside the +shared collections. Intentional adaptations of shared definitions use native +ConfigKit inheritance or explicit layering, without changing the shared source. +The precise entry-identity and adaptation contracts remain open below; directory +order must never silently choose which definition wins. + ### Derived Runtime Representations — Resolved Keep the resolved configuration intact. Audita derives separate runtime views @@ -478,6 +556,16 @@ into feature implementation. ## Acceptance Direction +Include a shared-library scenario with two campaigns consuming the same reusable +library and maintaining different local party, NPC, and place collections. +Verify independent selections and focused stages, inherited protection and +active-term exemptions, and provenance identifying shared versus campaign +definitions. Demonstrate an intentional adaptation through the selected native +inheritance/layering contract without modifying the shared source or the other +campaign's configuration. Cover an imported but unselected collection remaining +absent from prompt/protection views. Maintained examples should show deliberate +library revision adoption without introducing package-management code in Audita. + Use distinct party and spell fixtures with controlled model responses to show that each stage receives its intended correction and protection selections, that overrides do not leak into other stages, and that the second stage sees