Compare commits
29 Commits
e46c8182f1
...
88a0eaacf5
| Author | SHA1 | Date | |
|---|---|---|---|
| 88a0eaacf5 | |||
| 1806bfaf7f | |||
| f91871ba0f | |||
| 69961180a2 | |||
| f605fa0c1a | |||
| 1e0d4d0788 | |||
| dcc1103358 | |||
| daa08e6156 | |||
| fa348e9376 | |||
| 7d92867ba7 | |||
| 398562a2ca | |||
| efc7905798 | |||
| 8143732741 | |||
| cb90d63a2b | |||
| 52fa8ac918 | |||
| f6b6c7196b | |||
| a7d718970f | |||
| e63b334887 | |||
| 562eb540b8 | |||
| 870fc7b739 | |||
| 9f0d11d897 | |||
| 663dce1a9c | |||
| b83b778751 | |||
| daab85ae7e | |||
| fb3c95d462 | |||
| ca0380b208 | |||
| 3b2c47d236 | |||
| 4765586004 | |||
| 5fdd92b297 |
52
assets/configs/audita/config.yml
Normal file
52
assets/configs/audita/config.yml
Normal file
@@ -0,0 +1,52 @@
|
|||||||
|
# Ansible managed
|
||||||
|
version: 1
|
||||||
|
|
||||||
|
pipeline:
|
||||||
|
modules: ['glossary', 'homophones', 'glossary', 'spoken_word', 'grammar']
|
||||||
|
|
||||||
|
output:
|
||||||
|
schema: audita-v1
|
||||||
|
|
||||||
|
llm:
|
||||||
|
proposal:
|
||||||
|
base_url: https://inference.ai.rakestrawhome.com/v1
|
||||||
|
model: google/gemma-4-31b-it
|
||||||
|
api_key_env: AUDITA_LLM_API_KEY
|
||||||
|
timeout: 900s
|
||||||
|
max_retries: 3
|
||||||
|
|
||||||
|
validation:
|
||||||
|
base_url: https://inference.ai.rakestrawhome.com/v1
|
||||||
|
model: google/gemma-4-31b-it
|
||||||
|
api_key_env: AUDITA_VALIDATION_LLM_API_KEY
|
||||||
|
timeout: 900s
|
||||||
|
max_retries: 3
|
||||||
|
|
||||||
|
concurrency:
|
||||||
|
total_llm: 4
|
||||||
|
proposal_llm: 4
|
||||||
|
validation_llm: 4
|
||||||
|
|
||||||
|
chunking:
|
||||||
|
target_sections: 8
|
||||||
|
max_section_tokens: 6144
|
||||||
|
min_section_tokens: 2048
|
||||||
|
|
||||||
|
normalization:
|
||||||
|
max_segment_gap: 3s
|
||||||
|
ellipsis_gap: 3s
|
||||||
|
max_segment_duration: 240s
|
||||||
|
max_segment_tokens: 2048
|
||||||
|
|
||||||
|
thresholds:
|
||||||
|
glossary: 0.8
|
||||||
|
homophones: 0.8
|
||||||
|
spoken_word: 0.8
|
||||||
|
grammar: 0.8
|
||||||
|
|
||||||
|
context:
|
||||||
|
description: "The following transcript was recorded during a Dungeons & Dragons game session. It may contain some unrelaed pre-session or post-session banter, in addition to actual D&D gameplay."
|
||||||
|
|
||||||
|
diagnostics:
|
||||||
|
work_dir: /tmp/audita
|
||||||
|
retention: auto
|
||||||
160
assets/configs/narratio/pipeline.yml
Normal file
160
assets/configs/narratio/pipeline.yml
Normal file
@@ -0,0 +1,160 @@
|
|||||||
|
workspace:
|
||||||
|
root: /var/lib/narratio
|
||||||
|
cleanup_after_publish: true
|
||||||
|
|
||||||
|
secrets:
|
||||||
|
env_dir: /usr/local/etc/narratio/secrets
|
||||||
|
|
||||||
|
campaigns:
|
||||||
|
root: /usr/local/etc/narratio/campaigns
|
||||||
|
default_campaign_id: dilfs
|
||||||
|
|
||||||
|
storage:
|
||||||
|
backend: s3
|
||||||
|
s3:
|
||||||
|
endpoint: "https://s3.us-east-005.backblazeb2.com"
|
||||||
|
bucket: "rakestraw-assets"
|
||||||
|
root_prefix: "dnd"
|
||||||
|
region: "us-east-1"
|
||||||
|
force_path_style: True
|
||||||
|
access_key_id_env: OBJECT_STORAGE_KEY_ID
|
||||||
|
secret_access_key_env: OBJECT_STORAGE_KEY
|
||||||
|
|
||||||
|
whisperx:
|
||||||
|
transcribe_url: https://transcription.ai.rakestrawhome.com/transcribe
|
||||||
|
|
||||||
|
publish:
|
||||||
|
enabled: true
|
||||||
|
upload_run: true
|
||||||
|
outputs:
|
||||||
|
- source: narratio.transcript.final
|
||||||
|
required: true
|
||||||
|
- source: narratio.transcript.final_trimmed
|
||||||
|
required: true
|
||||||
|
- source: narratio.transcript.final_markdown
|
||||||
|
required: true
|
||||||
|
- source: narratio.transcript.final_trimmed_markdown
|
||||||
|
required: true
|
||||||
|
- source: narratio.artifact.session_recap
|
||||||
|
dest: artifacts/session_recap.md
|
||||||
|
required: true
|
||||||
|
- source: narratio.artifact.hostile_rumors
|
||||||
|
dest: artifacts/hostile_rumors.md
|
||||||
|
required: true
|
||||||
|
- source: narratio.artifact.deranged_rumors
|
||||||
|
dest: artifacts/deranged_rumors.md
|
||||||
|
required: false
|
||||||
|
|
||||||
|
scriptorium:
|
||||||
|
binary: scriptorium
|
||||||
|
config_path: /usr/local/etc/scriptorium/config.yml
|
||||||
|
timeout: 10m
|
||||||
|
render_debug: false
|
||||||
|
artifacts:
|
||||||
|
|
||||||
|
session_recap:
|
||||||
|
enabled: true
|
||||||
|
prompt_id: dnd.session_recap
|
||||||
|
profile_id: claude-fable-latest
|
||||||
|
output_path: artifacts/session_recap.md
|
||||||
|
timeout: 10m
|
||||||
|
inputs:
|
||||||
|
transcript:
|
||||||
|
source: narratio.transcript.final_trimmed
|
||||||
|
required: true
|
||||||
|
players:
|
||||||
|
source: narratio.input.players
|
||||||
|
required: true
|
||||||
|
party:
|
||||||
|
source: narratio.input.party
|
||||||
|
required: true
|
||||||
|
# recap:
|
||||||
|
# source: narratio.previous_session.artifact.session_recap
|
||||||
|
# required: false
|
||||||
|
|
||||||
|
scene_map:
|
||||||
|
enabled: false
|
||||||
|
prompt_id: dnd.scene_map
|
||||||
|
profile_id: claude-haiku-latest
|
||||||
|
output_path: artifacts/scene_map.json
|
||||||
|
timeout: 10m
|
||||||
|
inputs:
|
||||||
|
transcript:
|
||||||
|
source: narratio.transcript.final_trimmed
|
||||||
|
required: true
|
||||||
|
players:
|
||||||
|
source: narratio.input.players
|
||||||
|
required: true
|
||||||
|
party:
|
||||||
|
source: narratio.input.party
|
||||||
|
required: true
|
||||||
|
|
||||||
|
character_meta_analysis_alan:
|
||||||
|
enabled: false
|
||||||
|
prompt_id: dnd.character_meta_analysis
|
||||||
|
profile_id: claude-fable-latest
|
||||||
|
output_path: artifacts/character_meta_analysis_alan.md
|
||||||
|
timeout: 10m
|
||||||
|
inputs:
|
||||||
|
transcript:
|
||||||
|
source: narratio.transcript.final_trimmed
|
||||||
|
required: true
|
||||||
|
players:
|
||||||
|
source: narratio.input.players
|
||||||
|
required: true
|
||||||
|
party:
|
||||||
|
source: narratio.input.party
|
||||||
|
required: true
|
||||||
|
recap:
|
||||||
|
source: narratio.previous_session.artifact.session_recap
|
||||||
|
required: false
|
||||||
|
vars:
|
||||||
|
character_name: "Alan"
|
||||||
|
character_class: "Druid"
|
||||||
|
|
||||||
|
character_meta_analysis_hrank:
|
||||||
|
enabled: false
|
||||||
|
prompt_id: dnd.character_meta_analysis
|
||||||
|
profile_id: claude-fable-latest
|
||||||
|
output_path: artifacts/character_meta_analysis_hrank.md
|
||||||
|
timeout: 10m
|
||||||
|
inputs:
|
||||||
|
transcript:
|
||||||
|
source: narratio.transcript.final_trimmed
|
||||||
|
required: true
|
||||||
|
players:
|
||||||
|
source: narratio.input.players
|
||||||
|
required: true
|
||||||
|
party:
|
||||||
|
source: narratio.input.party
|
||||||
|
required: true
|
||||||
|
recap:
|
||||||
|
source: narratio.previous_session.artifact.session_recap
|
||||||
|
required: false
|
||||||
|
vars:
|
||||||
|
character_name: "Hrank"
|
||||||
|
character_class: "Cleric"
|
||||||
|
|
||||||
|
hostile_rumors:
|
||||||
|
enabled: true
|
||||||
|
prompt_id: dnd.hostile_rumors
|
||||||
|
output_path: artifacts/hostile_rumors.md
|
||||||
|
timeout: 10m
|
||||||
|
depends_on:
|
||||||
|
- session_recap
|
||||||
|
inputs:
|
||||||
|
recap:
|
||||||
|
source: narratio.artifact.session_recap
|
||||||
|
required: true
|
||||||
|
|
||||||
|
deranged_rumors:
|
||||||
|
enabled: true
|
||||||
|
prompt_id: dnd.deranged_rumors
|
||||||
|
output_path: artifacts/deranged_rumors.md
|
||||||
|
timeout: 10m
|
||||||
|
depends_on:
|
||||||
|
- session_recap
|
||||||
|
inputs:
|
||||||
|
recap:
|
||||||
|
source: narratio.artifact.session_recap
|
||||||
|
required: true
|
||||||
154
assets/configs/notarius/config.yml
Normal file
154
assets/configs/notarius/config.yml
Normal file
@@ -0,0 +1,154 @@
|
|||||||
|
version: 4
|
||||||
|
|
||||||
|
output:
|
||||||
|
directory: /var/lib/notarius/output
|
||||||
|
|
||||||
|
debug:
|
||||||
|
directory: /var/lib/notarius/debug
|
||||||
|
|
||||||
|
cache:
|
||||||
|
chunk_plans:
|
||||||
|
mode: auto
|
||||||
|
directory: /var/lib/notarius/cache/chunk_plans
|
||||||
|
checkpoints:
|
||||||
|
enabled: true
|
||||||
|
directory: /var/lib/notarius/cache/checkpoints
|
||||||
|
|
||||||
|
pipelines:
|
||||||
|
dnd-session:
|
||||||
|
llm_profile: dnd-extraction
|
||||||
|
# llm_profile: rakestrawhome-gemma-4-31b
|
||||||
|
input: seriatim
|
||||||
|
# Stable campaign context is shared by every module that accepts these slots.
|
||||||
|
references:
|
||||||
|
party: /usr/local/etc/notarius/campaigns/centaurs/party.yml
|
||||||
|
glossary: /usr/local/etc/notarius/campaigns/centaurs/glossary.yml
|
||||||
|
chunk:
|
||||||
|
module: dnd/scenes
|
||||||
|
retries: 2
|
||||||
|
output:
|
||||||
|
module: json
|
||||||
|
options:
|
||||||
|
include_chunk_map: true
|
||||||
|
evidence_context:
|
||||||
|
enabled: true
|
||||||
|
window_units: 3
|
||||||
|
lanes:
|
||||||
|
- item-occurrences
|
||||||
|
- item-registry
|
||||||
|
- location-registry
|
||||||
|
- location-occurrences
|
||||||
|
- npc-registry
|
||||||
|
- spells
|
||||||
|
- combat-turns
|
||||||
|
- npc-occurrences
|
||||||
|
- enemy-events
|
||||||
|
steps:
|
||||||
|
# Establish session-wide reference artifacts before their consumers.
|
||||||
|
- id: describe-session
|
||||||
|
artifacts:
|
||||||
|
item-registry:
|
||||||
|
extract:
|
||||||
|
module: dnd/item-registry
|
||||||
|
retries: 2
|
||||||
|
merge: appendorder
|
||||||
|
normalize: dnd/item-registry
|
||||||
|
npc-registry:
|
||||||
|
extract:
|
||||||
|
module: dnd/npc-registry
|
||||||
|
retries: 2
|
||||||
|
merge: appendorder
|
||||||
|
normalize:
|
||||||
|
module: dnd/npc-registry
|
||||||
|
retries: 2
|
||||||
|
location-registry:
|
||||||
|
extract:
|
||||||
|
module: dnd/location-registry
|
||||||
|
retries: 2
|
||||||
|
merge: appendorder
|
||||||
|
normalize:
|
||||||
|
module: dnd/location-registry
|
||||||
|
retries: 2
|
||||||
|
scene-descriptions:
|
||||||
|
extract:
|
||||||
|
module: dnd/scene-descriptions
|
||||||
|
retries: 2
|
||||||
|
merge: appendorder
|
||||||
|
normalize: dnd/scene-descriptions
|
||||||
|
- id: extract-events
|
||||||
|
# Accepted registry artifacts and scene-description eligibility artifacts
|
||||||
|
# are supplied in memory to their compatible consumers in this step.
|
||||||
|
references:
|
||||||
|
location_registry:
|
||||||
|
artifact:
|
||||||
|
step: describe-session
|
||||||
|
lane: location-registry
|
||||||
|
npc_registry:
|
||||||
|
artifact:
|
||||||
|
step: describe-session
|
||||||
|
lane: npc-registry
|
||||||
|
scene_descriptions:
|
||||||
|
artifact:
|
||||||
|
step: describe-session
|
||||||
|
lane: scene-descriptions
|
||||||
|
item_registry:
|
||||||
|
artifact:
|
||||||
|
step: describe-session
|
||||||
|
lane: item-registry
|
||||||
|
artifacts:
|
||||||
|
item-occurrences:
|
||||||
|
extract:
|
||||||
|
module: dnd/item-occurrences
|
||||||
|
retries: 2
|
||||||
|
merge: appendorder
|
||||||
|
normalize: dnd/item-occurrences
|
||||||
|
spells:
|
||||||
|
extract:
|
||||||
|
module: dnd/spells
|
||||||
|
retries: 2
|
||||||
|
merge: appendorder
|
||||||
|
normalize:
|
||||||
|
module: dnd/spells
|
||||||
|
combat-turns:
|
||||||
|
extract:
|
||||||
|
module: dnd/combat-turns
|
||||||
|
retries: 2
|
||||||
|
merge: appendorder
|
||||||
|
normalize: dnd/combat-turns
|
||||||
|
npc-occurrences:
|
||||||
|
extract:
|
||||||
|
module: dnd/npc-occurrences
|
||||||
|
retries: 2
|
||||||
|
merge: appendorder
|
||||||
|
normalize: dnd/npc-occurrences
|
||||||
|
location-occurrences:
|
||||||
|
extract:
|
||||||
|
module: dnd/location-occurrences
|
||||||
|
retries: 2
|
||||||
|
merge: appendorder
|
||||||
|
normalize: dnd/location-occurrences
|
||||||
|
- id: track-enemies
|
||||||
|
references:
|
||||||
|
npc_registry:
|
||||||
|
artifact:
|
||||||
|
step: describe-session
|
||||||
|
lane: npc-registry
|
||||||
|
scene_descriptions:
|
||||||
|
artifact:
|
||||||
|
step: describe-session
|
||||||
|
lane: scene-descriptions
|
||||||
|
combat_turns:
|
||||||
|
artifact:
|
||||||
|
step: extract-events
|
||||||
|
lane: combat-turns
|
||||||
|
npc_occurrences:
|
||||||
|
artifact:
|
||||||
|
step: extract-events
|
||||||
|
lane: npc-occurrences
|
||||||
|
artifacts:
|
||||||
|
enemy-events:
|
||||||
|
extract:
|
||||||
|
module: dnd/enemy-events
|
||||||
|
retries: 2
|
||||||
|
merge: appendorder
|
||||||
|
normalize: dnd/enemy-events
|
||||||
5
assets/configs/scriptorium/config.yml
Normal file
5
assets/configs/scriptorium/config.yml
Normal file
@@ -0,0 +1,5 @@
|
|||||||
|
# Ansible managed
|
||||||
|
|
||||||
|
prompt_dir: /usr/local/etc/scriptorium/library/prompts
|
||||||
|
profile_dir: /usr/local/etc/scriptorium/library/profiles
|
||||||
|
schema_dir: /usr/local/etc/scriptorium/library/schemas
|
||||||
@@ -0,0 +1,70 @@
|
|||||||
|
# Decision 0002: Shared, Readable Pipeline Filesystem Policy
|
||||||
|
|
||||||
|
Status: accepted
|
||||||
|
|
||||||
|
Date: 2026-09-14
|
||||||
|
|
||||||
|
## Context
|
||||||
|
|
||||||
|
The D&D pipeline may be invoked either by its dedicated `narratio` service
|
||||||
|
account or by a human operator who is already a member of the `narratio`
|
||||||
|
group. Both identities need a consistent view of application configuration and
|
||||||
|
shared writable state. Notarius versions before v0.7.0 imposed private cache
|
||||||
|
modes that prevented this deployment model, but v0.7.0 delegates cache access
|
||||||
|
policy to deployment provisioning.
|
||||||
|
|
||||||
|
The pipeline processes D&D campaign material. This deployment does not treat
|
||||||
|
configuration, transcripts, caches, generated artifacts, logs, or other
|
||||||
|
pipeline content as secret. API keys and similar credentials are the sole
|
||||||
|
confidential category and must remain isolated from ordinary content.
|
||||||
|
|
||||||
|
## Decision
|
||||||
|
|
||||||
|
The suite uses `narratio` as both its service identity and shared operator
|
||||||
|
group. A human account that is already a member of that group is a supported
|
||||||
|
pipeline invocation identity. Selecting operators and managing their group
|
||||||
|
membership remain separate deployment concerns.
|
||||||
|
|
||||||
|
Application configuration directories and files are owned by
|
||||||
|
`narratio:narratio` and are world-readable. Directories normally use `0755`
|
||||||
|
and files use `0644`. They remain Ansible-managed even though the service
|
||||||
|
account owns them; operators do not edit managed configuration in place.
|
||||||
|
Standalone application roles expose generic owner, group, and mode variables
|
||||||
|
and retain independently useful defaults. The opinionated pipeline role
|
||||||
|
selects the suite ownership policy through those interfaces.
|
||||||
|
|
||||||
|
Shared writable roots use `narratio:narratio` ownership and mode `2775`.
|
||||||
|
Setgid preserves the shared group, while managed default ACLs preserve owner
|
||||||
|
and group write access and world read/traverse access for newly created
|
||||||
|
content regardless of an invoking account's ordinary umask. Ordinary files
|
||||||
|
are expected to converge to the corresponding non-executable mode `0664`.
|
||||||
|
Application source trees and installed binaries remain root-owned and
|
||||||
|
world-readable or executable as appropriate.
|
||||||
|
|
||||||
|
Credential material belongs only beneath the suite's eventual `secrets/`
|
||||||
|
directory. That directory is not world-accessible; its expected directory and
|
||||||
|
file modes are `0750` and `0640`, respectively, with
|
||||||
|
`narratio:narratio` ownership so both supported invocation identities can read
|
||||||
|
shared credentials. Configuration may contain credential reference names but
|
||||||
|
never raw credential values.
|
||||||
|
|
||||||
|
Version-controlled campaign and prompt assets may remain root-managed because
|
||||||
|
Git is authoritative, but they are world-readable. The suite does not add
|
||||||
|
confidentiality controls to non-secret D&D content.
|
||||||
|
|
||||||
|
## Consequences
|
||||||
|
|
||||||
|
The pipeline can run under the service account or an existing human member of
|
||||||
|
the shared group without maintaining separate configuration or cache trees.
|
||||||
|
The deployment must provision setgid and default ACL behavior on shared
|
||||||
|
writable roots; directory modes alone do not guarantee group write access for
|
||||||
|
content created under an arbitrary user umask.
|
||||||
|
|
||||||
|
The broad readability of transcript-derived content is intentional. Hosts
|
||||||
|
requiring confidential campaign data need a different deployment policy and
|
||||||
|
are outside this MVP contract. Secret delivery remains future work and must
|
||||||
|
honor the separate restricted subtree rather than tightening unrelated files.
|
||||||
|
|
||||||
|
Existing content with incompatible ownership or ACLs is not recursively
|
||||||
|
migrated unless a feature expressly selects that behavior. Fresh convergence
|
||||||
|
and newly created content follow this policy.
|
||||||
@@ -6,3 +6,8 @@ change. Number records sequentially, for example
|
|||||||
`0001-application-and-suite-role-boundaries.md`.
|
`0001-application-and-suite-role-boundaries.md`.
|
||||||
|
|
||||||
Do not create a decision record for routine implementation choices.
|
Do not create a decision record for routine implementation choices.
|
||||||
|
|
||||||
|
## Records
|
||||||
|
|
||||||
|
- [0001: Minimal, Module-Driven Ansible](0001-minimal-module-driven-ansible.md)
|
||||||
|
- [0002: Shared, Readable Pipeline Filesystem Policy](0002-shared-readable-pipeline-filesystem-policy.md)
|
||||||
|
|||||||
@@ -14,6 +14,9 @@ Repositories inside this directory:
|
|||||||
role.
|
role.
|
||||||
- `assets/narratio-prompts`: PromptKit-compatible prompts and schemas deployed
|
- `assets/narratio-prompts`: PromptKit-compatible prompts and schemas deployed
|
||||||
for Scriptorium by the pipeline role.
|
for Scriptorium by the pipeline role.
|
||||||
|
- `assets/configs`: snapshots of application configuration from a test machine;
|
||||||
|
treat them as non-authoritative operational references that may use obsolete
|
||||||
|
syntax or installation-specific values.
|
||||||
- `rakestraw-ansible`: working deployment repository containing the
|
- `rakestraw-ansible`: working deployment repository containing the
|
||||||
`pipeline_dnd` proof of concept; treat it as read-only reference unless the
|
`pipeline_dnd` proof of concept; treat it as read-only reference unless the
|
||||||
task explicitly includes it.
|
task explicitly includes it.
|
||||||
@@ -49,4 +52,7 @@ machine-readable inventory of paths and remotes.
|
|||||||
contracts.
|
contracts.
|
||||||
- Asset repositories: authoritative campaign and prompt-library content and
|
- Asset repositories: authoritative campaign and prompt-library content and
|
||||||
layout.
|
layout.
|
||||||
|
- Reference configurations under `assets/configs`: evidence of prior
|
||||||
|
operational choices, never an application contract or a source to copy
|
||||||
|
verbatim.
|
||||||
- Individual Ansible repositories: implementation and repository-local tests.
|
- Individual Ansible repositories: implementation and repository-local tests.
|
||||||
|
|||||||
@@ -0,0 +1,353 @@
|
|||||||
|
# Feature 0007: D&D Asset Deployment and Scriptorium Integration
|
||||||
|
|
||||||
|
Status: done
|
||||||
|
|
||||||
|
## Summary
|
||||||
|
|
||||||
|
Extend the standalone D&D pipeline role to deploy the authoritative campaign
|
||||||
|
registry and Narratio prompt library, then connect those assets to Narratio
|
||||||
|
and Scriptorium through the application roles' existing public interfaces.
|
||||||
|
The result is an assembled suite in which Narratio can resolve a deployed
|
||||||
|
campaign and Scriptorium can discover the deployed D&D prompts and schemas.
|
||||||
|
|
||||||
|
## Problem or Opportunity
|
||||||
|
|
||||||
|
Feature 0006 composes and configures all five applications, but intentionally
|
||||||
|
leaves the suite's content roots empty. A consumer still has to deploy the
|
||||||
|
`campaigns` and `narratio-prompts` repositories separately and override
|
||||||
|
application configuration before the installed tools can find that content.
|
||||||
|
|
||||||
|
Both authoritative content repositories are now present in the workspace.
|
||||||
|
Their layouts make the required integration concrete: the campaign repository
|
||||||
|
is already organized as Narratio's campaign registry, while the prompt
|
||||||
|
repository contains top-level `prompts/` and `schemas/` trees. The prompt
|
||||||
|
repository does not contain execution profiles, so this feature must not
|
||||||
|
invent or configure a profile directory on its behalf.
|
||||||
|
|
||||||
|
Inspection also found four stale references in the current prompt content.
|
||||||
|
The character-analysis and session-recap definitions name a shared Markdown
|
||||||
|
file that does not exist under that name, and the two JSON-schema prompts name
|
||||||
|
schema paths that do not match the repository's `schemas/` layout. Deploying
|
||||||
|
those definitions without correcting their source would leave known-broken
|
||||||
|
suite content.
|
||||||
|
|
||||||
|
Both campaign definitions also retain an `inputs.players_file` field that
|
||||||
|
Narratio 2.0 rejects, and both `party.yml` documents use Narratio's legacy
|
||||||
|
list format. Narratio's canonical party model now obtains player identity from
|
||||||
|
a versioned `party_file`; the obsolete field must be removed and the party
|
||||||
|
documents migrated before either deployed campaign can pass native
|
||||||
|
configuration validation.
|
||||||
|
|
||||||
|
## Governing Policies
|
||||||
|
|
||||||
|
- [The Ansible house style](../../ansible.md) governs the role interface,
|
||||||
|
direct desired-state tasks, privilege escalation, and downstream role
|
||||||
|
configuration.
|
||||||
|
- [The testing house style](../../testing.md) governs focused native outcome
|
||||||
|
coverage and clean repeated convergence.
|
||||||
|
- [The MVP roadmap](../mvp.md) assigns campaign and prompt deployment to the
|
||||||
|
pipeline role, fixes the campaign registry location, and requires the
|
||||||
|
prompt library to track upstream until it publishes releases.
|
||||||
|
- [Decision 0001](../../decisions/0001-minimal-module-driven-ansible.md)
|
||||||
|
requires module-owned convergence without supplemental state or redundant
|
||||||
|
verification.
|
||||||
|
|
||||||
|
## Scope
|
||||||
|
|
||||||
|
- Add suite-owned repository URL, revision, and installation-root variables
|
||||||
|
for campaign and prompt content.
|
||||||
|
- Default both repositories to their authoritative Gitea origins and the
|
||||||
|
`main` branch, while allowing a caller to select another branch, tag,
|
||||||
|
commit, origin, or local Git fixture.
|
||||||
|
- Check out the campaign repository directly at
|
||||||
|
`/usr/local/share/narratio/campaigns` by default.
|
||||||
|
- Check out the prompt repository directly at
|
||||||
|
`/usr/local/share/narratio/prompt-library` by default.
|
||||||
|
- Treat both Git checkouts as root-managed, remotely authoritative content
|
||||||
|
that is updated during ordinary role convergence.
|
||||||
|
- Pass the selected campaign root to the Narratio role.
|
||||||
|
- Pass `<prompt-library-root>/prompts` and
|
||||||
|
`<prompt-library-root>/schemas` to the Scriptorium role as its native prompt
|
||||||
|
and schema directories.
|
||||||
|
- Leave Scriptorium's profile directory unset; the prompt repository does not
|
||||||
|
provide profiles.
|
||||||
|
- Remove the obsolete `inputs.players_file` declaration from both campaign
|
||||||
|
definitions while retaining their `party_file` inputs.
|
||||||
|
- Migrate both legacy party lists to the `narratio.party.v1` document shape,
|
||||||
|
preserving their supported character, player, class, and level data.
|
||||||
|
- Correct the two invalid shared-content references and the two invalid schema
|
||||||
|
paths in the authoritative `narratio-prompts` repository.
|
||||||
|
- Align pipeline-role defaults, argument specifications, dependency metadata,
|
||||||
|
README documentation, and focused integration coverage with the expanded
|
||||||
|
suite contract.
|
||||||
|
|
||||||
|
## Non-goals
|
||||||
|
|
||||||
|
- Defining Scriptorium execution profiles, model backends, API endpoints, or
|
||||||
|
credentials.
|
||||||
|
- Selecting the final D&D prompt/profile combinations used by Narratio stages
|
||||||
|
and artifacts.
|
||||||
|
- Defining the broader opinionated Audita, Narratio, Notarius, Seriatim, or
|
||||||
|
Scriptorium processing policy; that remains a later pipeline feature.
|
||||||
|
- Enabling Notarius or defining its D&D pipelines.
|
||||||
|
- Managing human operators or their group membership.
|
||||||
|
- Delivering secrets or environment files.
|
||||||
|
- Supporting non-Git asset sources, archive downloads, local overlay trees,
|
||||||
|
per-campaign selection, or merges of multiple campaign repositories.
|
||||||
|
- Making managed-host edits coexist with the authoritative repositories.
|
||||||
|
- Purging untracked files, maintaining asset manifests, recording deployed
|
||||||
|
commits in sidecar state, or adding independent drift/integrity checks.
|
||||||
|
- Adding an asset-specific release mechanism before either content repository
|
||||||
|
publishes releases.
|
||||||
|
- Running a real LLM request, WhisperX request, or end-to-end transcript.
|
||||||
|
- Re-testing the standalone roles' installation and configuration matrices.
|
||||||
|
- Incorporating the pipeline role into `rakestraw.dnd` or publishing a role or
|
||||||
|
collection release.
|
||||||
|
|
||||||
|
## Target End State
|
||||||
|
|
||||||
|
Applying `rakestraw.dnd_pipeline` on a supported host installs the application
|
||||||
|
suite and converges two root-managed Git working trees. The campaign checkout
|
||||||
|
itself is Narratio's campaign registry, so its top-level campaign directories
|
||||||
|
are immediately addressable by campaign ID. The prompt-library checkout
|
||||||
|
contains its native `prompts/` and `schemas/` subdirectories without copied or
|
||||||
|
rearranged content.
|
||||||
|
|
||||||
|
Narratio's managed pipeline configuration uses the same suite-selected
|
||||||
|
campaign root that the pipeline role populates. Scriptorium's managed
|
||||||
|
configuration points its `prompt_dir` and `schema_dir` fields to the
|
||||||
|
corresponding subdirectories of the suite-selected prompt root. Its
|
||||||
|
`profile_dir` remains omitted unless a caller or later suite-policy feature
|
||||||
|
provides one.
|
||||||
|
|
||||||
|
By default, each convergence fetches and reconciles the `main` branch of both
|
||||||
|
content repositories. A caller that needs reproducibility can select an
|
||||||
|
immutable commit through the corresponding revision variable. Ordinary Git
|
||||||
|
module change detection reports content updates, and an immediate repeat with
|
||||||
|
unchanged upstream state reports no changes.
|
||||||
|
|
||||||
|
The corrected prompt repository is internally consistent with its installed
|
||||||
|
layout: shared content files named by prompt definitions exist relative to the
|
||||||
|
definitions, and schema paths resolve relative to Scriptorium's configured
|
||||||
|
schema root. No compatibility links or installation-time content rewrites are
|
||||||
|
needed.
|
||||||
|
|
||||||
|
## Repository Ownership
|
||||||
|
|
||||||
|
- `ansible-role-dnd-pipeline` owns the suite asset variables, Git checkout
|
||||||
|
tasks, application-role variable wiring, documentation, and integration
|
||||||
|
coverage. It is the primary implementation repository.
|
||||||
|
- `assets/narratio-prompts` owns prompt definitions and their internal content
|
||||||
|
and schema references. It changes only to correct the four discovered stale
|
||||||
|
references; the pipeline role does not patch content at deployment time.
|
||||||
|
- `assets/campaigns` owns the campaign registry content and layout. It changes
|
||||||
|
only to remove the obsolete `players_file` fields and migrate the two party
|
||||||
|
documents to Narratio's current native schema; the pipeline role does not
|
||||||
|
rewrite campaign content at deployment time.
|
||||||
|
- `ansible-role-narratio` and `ansible-role-scriptorium` remain unchanged and
|
||||||
|
are read-only authorities for their public configuration variables.
|
||||||
|
- `../narratio` and `../scriptorium` remain read-only authorities for native
|
||||||
|
content discovery and validation behavior.
|
||||||
|
- `rakestraw-ansible` is a read-only historical reference. Its older
|
||||||
|
`/usr/local/etc` asset layout and monolithic deployment tasks are not copied.
|
||||||
|
- `ansible-workspace-dnd` owns this roadmap, the later staged implementation
|
||||||
|
plan, the settled MVP decisions, and aggregate status.
|
||||||
|
- `ansible-collection-dnd` remains unchanged until collection assembly is
|
||||||
|
selected.
|
||||||
|
|
||||||
|
## Constraints and Settled Decisions
|
||||||
|
|
||||||
|
- The public additions are:
|
||||||
|
|
||||||
|
| Variable | Default | Purpose |
|
||||||
|
| --- | --- | --- |
|
||||||
|
| `dnd_pipeline_campaigns_repository_url` | `https://gitea.maximumdirect.net/eric/campaigns.git` | Authoritative campaign Git origin |
|
||||||
|
| `dnd_pipeline_campaigns_revision` | `main` | Campaign branch, tag, or commit |
|
||||||
|
| `dnd_pipeline_campaigns_root` | `/usr/local/share/narratio/campaigns` | Campaign checkout and Narratio registry root |
|
||||||
|
| `dnd_pipeline_prompt_library_repository_url` | `https://gitea.maximumdirect.net/eric/narratio-prompts.git` | Authoritative prompt-library Git origin |
|
||||||
|
| `dnd_pipeline_prompt_library_revision` | `main` | Prompt-library branch, tag, or commit |
|
||||||
|
| `dnd_pipeline_prompt_library_root` | `/usr/local/share/narratio/prompt-library` | Prompt-library checkout root |
|
||||||
|
|
||||||
|
- Both repositories currently have no release tags. Tracking `main` is the
|
||||||
|
deliberate suite default; callers can opt into commit pinning without a
|
||||||
|
separate update switch.
|
||||||
|
- `ansible.builtin.git` owns checkout creation, fetch/update behavior, tracked
|
||||||
|
content convergence, and change reporting. The role does not run Git
|
||||||
|
commands, compare commits, or persist revision state separately.
|
||||||
|
- `update: true` and `force: true` express that the configured remote revision
|
||||||
|
owns tracked content. The role does not separately remove untracked files.
|
||||||
|
- The role performs the privileged content operations with task-level
|
||||||
|
`become: true`.
|
||||||
|
- The Narratio dependency creates the campaign root as `root:narratio` mode
|
||||||
|
`0755`. The pipeline role reuses that root rather than duplicating its
|
||||||
|
directory task.
|
||||||
|
- The pipeline role creates the prompt-library root as `root:narratio` mode
|
||||||
|
`0755` before checkout. Repository files retain their Git modes and remain
|
||||||
|
operator-readable; no recursive permission normalization is required.
|
||||||
|
- The pipeline role passes `dnd_pipeline_campaigns_root` as
|
||||||
|
`narratio_campaigns_root`,
|
||||||
|
`dnd_pipeline_prompt_library_root ~ '/prompts'` as
|
||||||
|
`scriptorium_prompt_dir`, and
|
||||||
|
`dnd_pipeline_prompt_library_root ~ '/schemas'` as
|
||||||
|
`scriptorium_schema_dir` through ordinary dependency metadata.
|
||||||
|
- `scriptorium_profile_dir` is not set by this feature. The default profile IDs
|
||||||
|
named by prompt definitions do not create profile definitions, and selecting
|
||||||
|
usable suite profiles belongs with the later D&D application-policy work.
|
||||||
|
- The prompt source corrections use the paths actually present in the
|
||||||
|
repository: `../common/previous_recap.user.md`,
|
||||||
|
`analyze/scene_map.schema.json`, and `trim/bounds.schema.json`.
|
||||||
|
- The campaign source corrections remove `inputs.players_file` from
|
||||||
|
`centaurs/campaign.yml` and `dilfs/campaign.yml`. The existing
|
||||||
|
`inputs.party_file` field remains the canonical party source.
|
||||||
|
- Each party document uses `schema_version: narratio.party.v1` and a
|
||||||
|
`characters` map. Stable character IDs are the lowercase underscore forms
|
||||||
|
of their names: `krek`, `rick_oathbreaker`, `tlann`,
|
||||||
|
`torvass_oathbreaker`, `hrank_greenfield`, `alan_hohey`, `svend_balderk`,
|
||||||
|
and `popov`.
|
||||||
|
- Each character retains its player name, display name, class, and level in
|
||||||
|
the corresponding native nested fields. Legacy `category: pc` is implicit
|
||||||
|
in membership in the canonical character map. Legacy free-form notes are
|
||||||
|
retained as adjacent YAML comments because `narratio.party.v1` has no note
|
||||||
|
field. Popov's evident `pladin` typo is corrected to `paladin` during the
|
||||||
|
otherwise mechanical migration.
|
||||||
|
- The now-unused `players.yml` files are not deleted or otherwise repurposed
|
||||||
|
by this feature.
|
||||||
|
- The existing dependency-management switch is not expanded. With
|
||||||
|
`dnd_pipeline_manage_build_dependencies: true`, the composed application
|
||||||
|
roles install Git before pipeline tasks execute. A caller that disables
|
||||||
|
dependency management remains responsible for providing Git as well as Go.
|
||||||
|
- Repository URLs and revisions are data, not secrets. No credentials are
|
||||||
|
added to role defaults or tests.
|
||||||
|
|
||||||
|
## Simplest Viable Implementation
|
||||||
|
|
||||||
|
The production change should remain a small extension of the composition
|
||||||
|
role:
|
||||||
|
|
||||||
|
1. Remove the obsolete `players_file` field from both campaign definitions
|
||||||
|
and migrate both party documents to `narratio.party.v1`.
|
||||||
|
2. Correct the four stale paths in the prompt source repository.
|
||||||
|
3. Add and type the six asset variables.
|
||||||
|
4. Map the campaign root and prompt/schema directories into the existing
|
||||||
|
Narratio and Scriptorium dependency variables.
|
||||||
|
5. Declare the prompt-library root with `ansible.builtin.file`.
|
||||||
|
6. Converge the campaign and prompt repositories with two
|
||||||
|
`ansible.builtin.git` tasks.
|
||||||
|
7. Update consumer documentation and extend the existing integration driver
|
||||||
|
with the asset-specific native outcomes and clean repeat.
|
||||||
|
|
||||||
|
No preliminary `stat`, remote revision query, registered-result conditional,
|
||||||
|
handler, checksum, manifest, or post-checkout permission sweep is required.
|
||||||
|
The file and Git modules already own the selected desired states.
|
||||||
|
|
||||||
|
## Rationale and Alternatives
|
||||||
|
|
||||||
|
Checking each repository out directly at its installed root preserves the
|
||||||
|
upstream layout and makes updates a single module-owned operation. Copying
|
||||||
|
files from a separate checkout would add a second synchronization boundary,
|
||||||
|
and installing compatibility links for stale prompt references would encode
|
||||||
|
source defects into deployment logic. Correcting those paths at their source
|
||||||
|
is smaller and makes the asset repository useful outside this role as well.
|
||||||
|
|
||||||
|
The dedicated `/usr/local/share/narratio/prompt-library` root makes the
|
||||||
|
relationship clear without producing a confusing `prompts/prompts` path.
|
||||||
|
Its `prompts/` and `schemas/` children map directly to Scriptorium's native
|
||||||
|
configuration fields. `/usr/local/share` is appropriate for host-wide,
|
||||||
|
root-managed, architecture-independent application data and is consistent
|
||||||
|
with the already selected campaign location.
|
||||||
|
|
||||||
|
One suite root variable per content repository keeps the Git destination and
|
||||||
|
application configuration coupled. Hard-coding each path independently would
|
||||||
|
permit accidental divergence, while exposing separate checkout and installed
|
||||||
|
paths would add flexibility for which no consumer requirement exists.
|
||||||
|
|
||||||
|
Tracking `main` matches the prompt-library policy already selected for the MVP
|
||||||
|
and is also the practical campaign default while that repository has no
|
||||||
|
releases. A single revision variable still permits immutable deployments.
|
||||||
|
Adding an update boolean would create overlapping modes without improving that
|
||||||
|
choice: selecting a commit already fixes content, and selecting a branch
|
||||||
|
expresses the intent to follow it.
|
||||||
|
|
||||||
|
## Acceptance Criteria
|
||||||
|
|
||||||
|
### Required Asset Behavior
|
||||||
|
|
||||||
|
- Applying the pipeline role checks out the configured campaign repository at
|
||||||
|
`dnd_pipeline_campaigns_root` and the configured prompt repository at
|
||||||
|
`dnd_pipeline_prompt_library_root`.
|
||||||
|
- The default origins, revisions, and roots match the fixed public interface.
|
||||||
|
- A caller can replace either origin, revision, or root through its suite
|
||||||
|
variable without editing role tasks or dependency metadata.
|
||||||
|
- Narratio's managed configuration names the exact campaign root populated by
|
||||||
|
the pipeline role.
|
||||||
|
- Scriptorium's managed configuration names the deployed `prompts/` and
|
||||||
|
`schemas/` directories and does not acquire a profile directory from this
|
||||||
|
feature.
|
||||||
|
- Both deployed campaign definitions and their versioned party documents
|
||||||
|
conform to Narratio 2.0's canonical party-input contract and pass native
|
||||||
|
validation by campaign ID.
|
||||||
|
- The two prompt definitions that use previous-recap content load the existing
|
||||||
|
`previous_recap.user.md` file, and both JSON-schema definitions resolve
|
||||||
|
paths beneath the configured schema directory.
|
||||||
|
- The managed content roots are root-owned and operator-readable. Runtime and
|
||||||
|
operator accounts do not receive write access through this feature.
|
||||||
|
- Upstream changes to a selected branch are applied by a later role run;
|
||||||
|
selecting an immutable commit produces stable content.
|
||||||
|
- An immediate repeated role application with unchanged inputs and upstream
|
||||||
|
state reports no changes.
|
||||||
|
- The role contains no content copies, deployment-time prompt rewrites,
|
||||||
|
redundant state probes, revision sidecars, checksums, or production
|
||||||
|
self-validation.
|
||||||
|
- Only `ansible-role-dnd-pipeline`, `assets/campaigns`,
|
||||||
|
`assets/narratio-prompts`, and workspace planning/status documentation
|
||||||
|
change.
|
||||||
|
|
||||||
|
### Required Validation
|
||||||
|
|
||||||
|
- YAML syntax checking and production-profile ansible-lint pass for the role
|
||||||
|
and its test playbooks.
|
||||||
|
- The integration driver uses explicit repository URL and revision inputs for
|
||||||
|
controlled local Git fixtures rather than depending on mutable network
|
||||||
|
state.
|
||||||
|
- Narratio natively validates its managed pipeline configuration with a
|
||||||
|
campaign selected by ID from the deployed registry.
|
||||||
|
- Scriptorium natively inspects a deployed prompt through its managed
|
||||||
|
configuration, including a representative definition that uses the repaired
|
||||||
|
shared-content path.
|
||||||
|
- A representative JSON-schema prompt has a schema path that resolves beneath
|
||||||
|
the configured deployed schema directory.
|
||||||
|
- The asset-enabled baseline is followed immediately by a convergence that
|
||||||
|
reports no changes.
|
||||||
|
- Existing suite version-forwarding coverage remains intact; the feature does
|
||||||
|
not repeat standalone application installation matrices.
|
||||||
|
- Tests do not assert current default revisions as immutable facts, enumerate
|
||||||
|
every asset as a snapshot, inspect Git internals, trace task execution, or
|
||||||
|
re-test `ansible.builtin.file` and `ansible.builtin.git` behavior.
|
||||||
|
|
||||||
|
## Dependencies and Follow-up Work
|
||||||
|
|
||||||
|
Feature 0006 and all five standalone roles are complete. The managed host must
|
||||||
|
be able to reach the selected content repositories unless callers provide
|
||||||
|
local origins. The narrow campaign and prompt source corrections must be
|
||||||
|
committed before an integration test pins or checks out their resulting
|
||||||
|
revisions.
|
||||||
|
|
||||||
|
The next suite-policy feature should select actual Scriptorium profiles and
|
||||||
|
backends together with Narratio prompt IDs, artifacts, and other opinionated
|
||||||
|
D&D application settings. Operator access, secret delivery, end-to-end
|
||||||
|
processing validation, and collection assembly also remain separate work.
|
||||||
|
|
||||||
|
Before a suite or collection release, both asset repositories need an explicit
|
||||||
|
release policy. If they begin publishing immutable releases, the suite should
|
||||||
|
replace its branch defaults with compatible released revisions.
|
||||||
|
|
||||||
|
Feature 0007 was completed by campaign commit `d1193e8`, prompt-library commit
|
||||||
|
`c7e1845`, pipeline-role commits `a6ce224` and `cbfd601`, and final test-quality
|
||||||
|
remediation commit `7572fa3`. The complete integration suite and post-remediation
|
||||||
|
review passed with no remaining findings.
|
||||||
|
|
||||||
|
## Potential Future Hardening
|
||||||
|
|
||||||
|
- Verify signed asset releases when the repositories publish them.
|
||||||
|
- Protect managed checkouts against hostile repository ownership changes.
|
||||||
|
- Provide a controlled offline mirror or packaged asset artifact.
|
||||||
@@ -0,0 +1,475 @@
|
|||||||
|
# Feature 0008: Opinionated D&D Processing Configuration
|
||||||
|
|
||||||
|
Status: done
|
||||||
|
|
||||||
|
## Summary
|
||||||
|
|
||||||
|
Turn the installed application suite and deployed D&D assets into a coherent
|
||||||
|
processing configuration. The pipeline role will supply deliberately
|
||||||
|
opinionated Audita and Narratio policy, split Narratio's suite-owned processing
|
||||||
|
and artifact definitions into explicit ConfigKit fragments, and provide a
|
||||||
|
named `testing` profile for inexpensive prompt and model iteration without
|
||||||
|
changing production policy.
|
||||||
|
|
||||||
|
## Problem or Opportunity
|
||||||
|
|
||||||
|
Features 0006 and 0007 install the five applications, connect their standard
|
||||||
|
paths, and deploy valid campaigns, prompts, and schemas. The assembled role
|
||||||
|
still leaves most optional application policy unset. Narratio can validate its
|
||||||
|
minimal root document and discover content, but it does not yet describe the
|
||||||
|
D&D trimming, rendering, recap, rumor, scene-map, or per-character analysis
|
||||||
|
workflow.
|
||||||
|
|
||||||
|
A current test-machine configuration provides useful evidence of the intended
|
||||||
|
workflow, but it cannot be copied. It includes pre-Narratio-2.0 syntax,
|
||||||
|
installation-specific storage and inference settings, obsolete paths,
|
||||||
|
campaign-specific character entries, and redundant artifact dependencies.
|
||||||
|
The current application repositories remain authoritative for supported
|
||||||
|
configuration.
|
||||||
|
|
||||||
|
Narratio 2.0 also provides two useful composition mechanisms that the suite
|
||||||
|
has not yet adopted: additive root imports for independently owned base
|
||||||
|
fragments and a fixed `profiles/testing.yml` overlay. Using both will make the
|
||||||
|
production policy reviewable and make inexpensive development runs easy to
|
||||||
|
select without editing the production configuration.
|
||||||
|
|
||||||
|
## Governing Policies
|
||||||
|
|
||||||
|
- [The Ansible house style](../../ansible.md) governs the suite-owned public
|
||||||
|
interface, templates, direct desired-state tasks, and omission of
|
||||||
|
unselected application defaults.
|
||||||
|
- [The testing house style](../../testing.md) governs native behavioral
|
||||||
|
validation, explicit testing inputs, and clean repeated convergence.
|
||||||
|
- [The MVP roadmap](../mvp.md) assigns opinionated cross-application and D&D
|
||||||
|
policy to the pipeline role while keeping standalone application roles
|
||||||
|
generic.
|
||||||
|
- [Decision 0001](../../decisions/0001-minimal-module-driven-ansible.md)
|
||||||
|
requires direct module-owned convergence without supplemental state or
|
||||||
|
redundant verification.
|
||||||
|
|
||||||
|
## Scope
|
||||||
|
|
||||||
|
- Supply the complete reviewed Audita configuration as deliberate D&D suite
|
||||||
|
policy, including its context, schema, module sequence, endpoint, models,
|
||||||
|
credential environment-variable names, timeouts, retries, concurrency,
|
||||||
|
chunking, normalization, thresholds, and diagnostics settings.
|
||||||
|
- Configure Narratio's normalization, trimming, and Markdown rendering stages
|
||||||
|
through its current public contract, explicitly pinning only the schemas,
|
||||||
|
identifiers, enablement choices, and paths that form the D&D suite's
|
||||||
|
cross-stage contract.
|
||||||
|
- Use the deployed `dnd.session_bounds` prompt for transcript-bound detection.
|
||||||
|
- Define each ordinary Narratio Scriptorium artifact in its own managed YAML
|
||||||
|
fragment:
|
||||||
|
- session recap;
|
||||||
|
- hostile rumors;
|
||||||
|
- deranged rumors; and
|
||||||
|
- scene map.
|
||||||
|
- Define per-character gameplay analysis as one Narratio artifact-family
|
||||||
|
fragment over `party.characters`, not as campaign-specific artifact entries.
|
||||||
|
- Supply only the inputs declared by each current prompt definition.
|
||||||
|
- Let each production prompt select its own declared Promptkit default profile
|
||||||
|
unless the roadmap records a concrete reason for a suite override.
|
||||||
|
- Manage a valid `profiles/testing.yml` Narratio overlay that selects an
|
||||||
|
inexpensive Scriptorium profile while leaving the base production policy
|
||||||
|
and inherited Audita configuration unchanged.
|
||||||
|
- Expose the suite-owned testing-profile choice through normal Ansible
|
||||||
|
inventory precedence.
|
||||||
|
- Compose the base fragments through an explicit ordered
|
||||||
|
`narratio_configkit_imports` list in the standalone Narratio role's root
|
||||||
|
configuration.
|
||||||
|
- Create and manage the required `conf.d`, `artifacts`,
|
||||||
|
`artifact-families`, and `profiles` directories and their suite-owned files
|
||||||
|
under `/usr/local/etc/narratio`.
|
||||||
|
- Document production and testing invocations, the imported layout, public
|
||||||
|
variables, and the boundary with later pipeline features.
|
||||||
|
- Extend focused integration coverage for both base and `testing` resolution,
|
||||||
|
representative artifact relationships, party-driven family expansion, and
|
||||||
|
immediate clean repeated convergence.
|
||||||
|
|
||||||
|
## Non-goals
|
||||||
|
|
||||||
|
- Enabling Narratio's Notarius stage or installing the uploaded Notarius
|
||||||
|
pipeline. Its multi-stage D&D extraction, campaign reference bindings,
|
||||||
|
output descriptors, and runtime directories remain a separate feature.
|
||||||
|
- Configuring S3 or other remote storage, publishing outputs, upload behavior,
|
||||||
|
or cleanup-after-publish.
|
||||||
|
- Selecting a default campaign. Campaign choice remains an inventory or
|
||||||
|
invocation decision.
|
||||||
|
- Delivering API keys, object-storage credentials, environment files, or a
|
||||||
|
general secret-management mechanism.
|
||||||
|
- Selecting human operators or managing their Narratio group membership.
|
||||||
|
- Adding a scheduler, service, or automated invocation.
|
||||||
|
- Running WhisperX, Audita model calls, Scriptorium model calls, Notarius, or
|
||||||
|
a complete transcript during integration tests.
|
||||||
|
- Copying the test-machine configuration verbatim or preserving its obsolete
|
||||||
|
Narratio, campaign, Scriptorium, or credential paths.
|
||||||
|
- Duplicating prompt content, prompt schemas, built-in Promptkit profiles, or
|
||||||
|
application validation rules in the pipeline role.
|
||||||
|
- Modifying the standalone application roles or upstream application source.
|
||||||
|
- Collection assembly, role releases, asset release policy, upgrade/removal
|
||||||
|
behavior, or end-to-end production validation.
|
||||||
|
|
||||||
|
## Target End State
|
||||||
|
|
||||||
|
The standalone Narratio role continues to own
|
||||||
|
`/usr/local/etc/narratio/pipeline.yml`. That root document contains the
|
||||||
|
installation paths already supplied by the pipeline role and an explicit list
|
||||||
|
of suite-owned relative imports. The pipeline role owns the imported files:
|
||||||
|
|
||||||
|
```text
|
||||||
|
/usr/local/etc/narratio/
|
||||||
|
├── pipeline.yml
|
||||||
|
├── conf.d/
|
||||||
|
│ └── processing.yml
|
||||||
|
├── artifacts/
|
||||||
|
│ ├── session-recap.yml
|
||||||
|
│ ├── hostile-rumors.yml
|
||||||
|
│ ├── deranged-rumors.yml
|
||||||
|
│ └── scene-map.yml
|
||||||
|
├── artifact-families/
|
||||||
|
│ └── character-meta-analysis.yml
|
||||||
|
└── profiles/
|
||||||
|
└── testing.yml
|
||||||
|
```
|
||||||
|
|
||||||
|
Each base artifact or family key is declared by exactly one fragment. The
|
||||||
|
root uses explicit `path` imports rather than globs; Narratio therefore loads
|
||||||
|
only the files selected by current suite policy, even if an obsolete file is
|
||||||
|
left on a previously managed host. Imported maps remain additive and no two
|
||||||
|
base sources claim the same leaf.
|
||||||
|
|
||||||
|
The production configuration uses the deployed prompt definitions and their
|
||||||
|
frontier-oriented default profiles. Audita uses the selected
|
||||||
|
`https://inference.ai.rakestrawhome.com/v1` endpoint and
|
||||||
|
`google/gemma-4-31b-it` proposal and validation model. Narratio's canonical
|
||||||
|
processing paths and schemas are suite-owned contracts rather than incidental
|
||||||
|
copies of application defaults. Session recap consumes the final trimmed
|
||||||
|
transcript and may consume the previous session's recap. Hostile and deranged
|
||||||
|
rumors consume the current recap, allowing Narratio to infer their dependency
|
||||||
|
without a duplicate `depends_on` declaration. Scene map is configured as an
|
||||||
|
available, normally disabled artifact. Character analysis is an available
|
||||||
|
party-driven family whose generated members receive `character.name` and
|
||||||
|
`character.class_summary` through family member variables.
|
||||||
|
|
||||||
|
The installed `testing` profile is a valid overlay selected with
|
||||||
|
`--profile testing`. It selects `gemini-flash-latest` for each Scriptorium
|
||||||
|
artifact and artifact family while inheriting the base topology, paths,
|
||||||
|
prompts, inputs, outputs, and enabled state. Audita inherits the same endpoint
|
||||||
|
and model in both modes for now, so the overlay does not restate its base
|
||||||
|
configuration. The testing profile neither imports files nor contains
|
||||||
|
credentials. Operators can validate, inspect, or run the same session under
|
||||||
|
base or testing policy without modifying an Ansible-managed file.
|
||||||
|
|
||||||
|
## Repository Ownership
|
||||||
|
|
||||||
|
- `ansible-role-dnd-pipeline` owns the suite variables, Narratio fragment and
|
||||||
|
testing-profile templates, direct directory/file convergence, dependency
|
||||||
|
variable wiring, consumer documentation, and integration coverage. It is
|
||||||
|
the only implementation repository expected to change.
|
||||||
|
- `ansible-role-narratio` remains unchanged. It owns the root pipeline
|
||||||
|
template and the public `narratio_configkit_imports` and stage variables
|
||||||
|
through which the suite composes it.
|
||||||
|
- `ansible-role-audita` remains unchanged. It owns Audita's field-specific
|
||||||
|
configuration interface; the pipeline role selects only intentional D&D
|
||||||
|
policy through that interface.
|
||||||
|
- `ansible-role-scriptorium`, `assets/narratio-prompts`, and `../promptkit`
|
||||||
|
remain unchanged authorities for source-directory configuration, prompt
|
||||||
|
contracts, and built-in production/testing profile choices.
|
||||||
|
- `../audita` and `../narratio` remain unchanged authorities for current
|
||||||
|
application configuration and native inspection behavior.
|
||||||
|
- `ansible-role-notarius` and `../notarius` are read-only inputs for the later
|
||||||
|
D&D extraction feature.
|
||||||
|
- `rakestraw-ansible` and the uploaded test-machine configurations are
|
||||||
|
historical and operational references, not application contracts.
|
||||||
|
- `ansible-workspace-dnd` owns this roadmap, the later implementation plan,
|
||||||
|
settled MVP decisions, and aggregate status.
|
||||||
|
|
||||||
|
## Constraints and Settled Decisions
|
||||||
|
|
||||||
|
- Standalone application roles remain generic. Every concrete value added by
|
||||||
|
this feature must represent policy deliberately owned by the D&D suite.
|
||||||
|
- Application defaults observed in documentation or the uploaded files are
|
||||||
|
not copied merely to restate them. An explicit suite value must preserve a
|
||||||
|
chosen outcome across upstream default changes.
|
||||||
|
- The pipeline explicitly owns a value when another stage, artifact, prompt,
|
||||||
|
or future publishing rule relies on its schema, identifier, enabled state,
|
||||||
|
or path. Behavior confined to Narratio inherits Narratio's application
|
||||||
|
default unless the suite has independently selected that behavior as policy.
|
||||||
|
- The pipeline role does not duplicate Narratio's root template. It acts as a
|
||||||
|
caller: the standalone role renders the root and the pipeline role deploys
|
||||||
|
the suite-owned fragments named by that root.
|
||||||
|
- Every ordinary artifact and every artifact family has its own source and
|
||||||
|
installed file. General stage policy may share `conf.d/processing.yml`.
|
||||||
|
- Imports are explicit relative `path` entries. Globs are not used because
|
||||||
|
the role does not need directory discovery and must not activate stale
|
||||||
|
files accidentally.
|
||||||
|
- The imported files cannot contain `configkit`, nested imports, or profile
|
||||||
|
directives. The `testing` overlay cannot import or stack other profiles.
|
||||||
|
- Suite-managed configuration directories are `root:narratio` mode `0750`;
|
||||||
|
files are `root:narratio` mode `0640`, matching the established Narratio
|
||||||
|
configuration boundary.
|
||||||
|
- The role declares directory and template state directly. It does not
|
||||||
|
inspect files first, validate production configuration during convergence,
|
||||||
|
keep manifests, or track fragment digests.
|
||||||
|
- The base artifact definitions omit `profile_id` when the deployed prompt's
|
||||||
|
declared default is the selected production policy.
|
||||||
|
- Artifact inputs must match the current prompt contracts:
|
||||||
|
- session recap: required `transcript`, optional `recap`;
|
||||||
|
- hostile and deranged rumors: required `recap`;
|
||||||
|
- scene map: required `transcript`; and
|
||||||
|
- character analysis family: required `transcript`, optional `recap`, plus
|
||||||
|
member variables for `character_name` and `character_class`.
|
||||||
|
- A `narratio.artifact.session_recap` input already creates the rumor
|
||||||
|
dependency. The base fragments do not repeat that edge with `depends_on`.
|
||||||
|
- Scene map and character analysis are configured but disabled by default;
|
||||||
|
Narratio's explicit artifact selection may still run their concrete entries.
|
||||||
|
- The character family uses `for_each: party.characters`, an output path with
|
||||||
|
exactly one `{character_id}` token, and member selectors
|
||||||
|
`character.name` and `character.class_summary`. It contains no hard-coded
|
||||||
|
campaign character names.
|
||||||
|
- Production and testing policy never embeds secret values. Credential
|
||||||
|
delivery remains a later feature.
|
||||||
|
- The testing profile is a single valid overlay at the native fixed location.
|
||||||
|
It overrides each Scriptorium artifact and family `profile_id` with the
|
||||||
|
suite's `gemini-flash-latest` testing-profile variable rather than
|
||||||
|
duplicating complete definitions. Audita deliberately uses the same base
|
||||||
|
endpoint and models under both configurations.
|
||||||
|
- Each fixed artifact or family fragment has one complete native-mapping
|
||||||
|
variable: `dnd_pipeline_narratio_session_recap_artifact`,
|
||||||
|
`dnd_pipeline_narratio_hostile_rumors_artifact`,
|
||||||
|
`dnd_pipeline_narratio_deranged_rumors_artifact`,
|
||||||
|
`dnd_pipeline_narratio_scene_map_artifact`, and
|
||||||
|
`dnd_pipeline_narratio_character_analysis_family`. The file names, imports,
|
||||||
|
and top-level source keys remain fixed suite topology; callers customize the
|
||||||
|
mapping and disable an available source with `enabled: false` rather than
|
||||||
|
removing its managed fragment or import.
|
||||||
|
|
||||||
|
## Selected Narratio Coordination Policy
|
||||||
|
|
||||||
|
The pipeline role pins the following effective Narratio fields because they
|
||||||
|
connect processing stages, prompt contracts, or stable suite outputs. A value
|
||||||
|
that currently equals an application default is still intentional suite policy
|
||||||
|
when an upstream change would otherwise break that connection.
|
||||||
|
|
||||||
|
| Native Narratio field | D&D suite default | Coordination purpose |
|
||||||
|
| --- | --- | --- |
|
||||||
|
| `pipeline.seriatim.output_schema` | `seriatim-intermediate` | Establishes the merge-stage transcript contract. |
|
||||||
|
| `pipeline.audita.output_schema` | `audita-v1` | Matches the Audita configuration and adapter output contract. |
|
||||||
|
| `pipeline.normalize.output_path` | `transcripts/final.json` | Provides the canonical normalized transcript source. |
|
||||||
|
| `pipeline.normalize.output_schema` | `seriatim-intermediate` | Provides the canonical schema consumed by later stages. |
|
||||||
|
| `pipeline.trim.enabled` | `true` | Makes the trimmed transcript part of the selected D&D workflow. |
|
||||||
|
| `pipeline.trim.output_path` | `transcripts/final.trimmed.json` | Provides the canonical transcript consumed by D&D artifacts. |
|
||||||
|
| `pipeline.trim.bounds.prompt_id` | `dnd.session_bounds` | Selects the deployed D&D bounds prompt. |
|
||||||
|
| `pipeline.trim.bounds.transcript_input_name` | `transcript` | Matches that prompt's declared input contract. |
|
||||||
|
| `pipeline.trim.bounds.output_path` | `artifacts/session_bounds.json` | Provides a stable bounds artifact location. |
|
||||||
|
| `pipeline.render.enabled` | `true` | Selects rendered transcripts as a suite outcome. |
|
||||||
|
| `pipeline.render.format` | `markdown` | Selects the suite's rendered transcript format. |
|
||||||
|
|
||||||
|
The fixed artifact mappings own these output paths:
|
||||||
|
|
||||||
|
| Source | D&D suite output |
|
||||||
|
| --- | --- |
|
||||||
|
| `session_recap` | `artifacts/session_recap.md` |
|
||||||
|
| `hostile_rumors` | `artifacts/hostile_rumors.md` |
|
||||||
|
| `deranged_rumors` | `artifacts/deranged_rumors.md` |
|
||||||
|
| `scene_map` | `artifacts/scene_map.json` |
|
||||||
|
| `character_meta_analysis` family | `artifacts/character_meta_analysis/{character_id}.md` |
|
||||||
|
|
||||||
|
The processing fragment omits Narratio-local choices such as reports,
|
||||||
|
timeouts, debug rendering, work-directory retention, render title, timestamp,
|
||||||
|
segment-ID, and metadata presentation, and the bounds prompt profile. Narratio
|
||||||
|
continues to supply those defaults. Likewise, the Narratio Audita adapter does
|
||||||
|
not repeat Audita's endpoint, models, module sequence, tuning, or diagnostic
|
||||||
|
settings: it uses the pipeline-managed Audita configuration file. The Audita
|
||||||
|
output schema is the deliberate exception because it spans that application
|
||||||
|
boundary, and one suite value must feed both configurations.
|
||||||
|
|
||||||
|
Audita does not choose a fixed final transcript path in this integration.
|
||||||
|
Narratio supplies the run-specific `--output` path when invoking Audita and
|
||||||
|
then normalizes the result to the canonical path above. The role therefore
|
||||||
|
does not invent a separate Audita output-path setting.
|
||||||
|
|
||||||
|
## Selected Audita and Testing Policy
|
||||||
|
|
||||||
|
The pipeline role deliberately owns all of the following Audita values. They
|
||||||
|
are suite defaults, not assertions about Audita's upstream defaults, and each
|
||||||
|
remains replaceable through the corresponding suite-prefixed role variable.
|
||||||
|
|
||||||
|
| Native Audita field | D&D suite default |
|
||||||
|
| --- | --- |
|
||||||
|
| `pipeline.modules` | `[glossary, homophones, glossary, spoken_word, grammar]` |
|
||||||
|
| `output.schema` | `audita-v1` |
|
||||||
|
| `llm.proposal.base_url` | `https://inference.ai.rakestrawhome.com/v1` |
|
||||||
|
| `llm.proposal.model` | `google/gemma-4-31b-it` |
|
||||||
|
| `llm.proposal.api_key_env` | `AUDITA_LLM_API_KEY` |
|
||||||
|
| `llm.proposal.timeout` | `900s` |
|
||||||
|
| `llm.proposal.max_retries` | `3` |
|
||||||
|
| `llm.validation.base_url` | `https://inference.ai.rakestrawhome.com/v1` |
|
||||||
|
| `llm.validation.model` | `google/gemma-4-31b-it` |
|
||||||
|
| `llm.validation.api_key_env` | `AUDITA_VALIDATION_LLM_API_KEY` |
|
||||||
|
| `llm.validation.timeout` | `900s` |
|
||||||
|
| `llm.validation.max_retries` | `3` |
|
||||||
|
| `concurrency.total_llm` | `4` |
|
||||||
|
| `concurrency.proposal_llm` | `4` |
|
||||||
|
| `concurrency.validation_llm` | `4` |
|
||||||
|
| `chunking.target_sections` | `8` |
|
||||||
|
| `chunking.max_section_tokens` | `6144` |
|
||||||
|
| `chunking.min_section_tokens` | `2048` |
|
||||||
|
| `normalization.max_segment_gap` | `3s` |
|
||||||
|
| `normalization.ellipsis_gap` | `3s` |
|
||||||
|
| `normalization.max_segment_duration` | `240s` |
|
||||||
|
| `normalization.max_segment_tokens` | `2048` |
|
||||||
|
| `thresholds.glossary` | `0.8` |
|
||||||
|
| `thresholds.homophones` | `0.8` |
|
||||||
|
| `thresholds.spoken_word` | `0.8` |
|
||||||
|
| `thresholds.grammar` | `0.8` |
|
||||||
|
| `context.description` | `The following transcript was recorded during a Dungeons & Dragons game session. It may contain some unrelated pre-session or post-session banter, in addition to actual D&D gameplay.` |
|
||||||
|
| `diagnostics.work_dir` | `/tmp/audita` |
|
||||||
|
| `diagnostics.retention` | `auto` |
|
||||||
|
|
||||||
|
The repeated `glossary` entry is intentional and preserves the selected
|
||||||
|
multi-pass module sequence. Environment-variable names are configuration, not
|
||||||
|
secret values; the later secret-delivery feature will provide their contents.
|
||||||
|
|
||||||
|
The testing overlay uses one suite variable whose default is
|
||||||
|
`gemini-flash-latest` for every Scriptorium artifact and artifact family.
|
||||||
|
Callers may replace that profile normally. Audita uses the production endpoint
|
||||||
|
and models in testing until the suite deliberately selects alternatives; the
|
||||||
|
overlay omits identical Audita fields rather than writing them twice. These
|
||||||
|
model choices are expected to evolve rapidly and can be updated as ordinary
|
||||||
|
suite policy without changing the fragment architecture.
|
||||||
|
|
||||||
|
## Simplest Viable Implementation
|
||||||
|
|
||||||
|
The production change should remain a small configuration extension:
|
||||||
|
|
||||||
|
1. Add only the suite variables required by the selected Audita policy,
|
||||||
|
selected Narratio coordination policy, fragment mappings, and
|
||||||
|
testing-profile override; align the argument specification.
|
||||||
|
2. Pass the Audita choices and explicit Narratio import list through the
|
||||||
|
existing dependency interfaces.
|
||||||
|
3. Create the four Narratio configuration subdirectories with one
|
||||||
|
`ansible.builtin.file` loop.
|
||||||
|
4. Render the processing fragment, four artifact fragments, one family
|
||||||
|
fragment, and testing overlay with one `ansible.builtin.template` loop.
|
||||||
|
5. Update the README and extend the existing integration driver with native
|
||||||
|
base/testing validation and a clean repeat.
|
||||||
|
|
||||||
|
No preliminary `stat`, configuration assembly fact, handler, validation
|
||||||
|
command, checksum, manifest, or fragment cleanup task is required. Explicit
|
||||||
|
imports make an obsolete unreferenced file inert without destructive directory
|
||||||
|
reconciliation.
|
||||||
|
|
||||||
|
## Rationale and Alternatives
|
||||||
|
|
||||||
|
ConfigKit fragments preserve the application's native composition model and
|
||||||
|
give each artifact a focused review boundary. Rendering one monolithic
|
||||||
|
Narratio mapping through the standalone root variable would produce a valid
|
||||||
|
file but would discard that operational and editorial advantage. Reimplementing
|
||||||
|
the entire root template in the pipeline role would duplicate the standalone
|
||||||
|
role and create competing configuration ownership.
|
||||||
|
|
||||||
|
Explicit imports are preferred to globs because the suite already knows every
|
||||||
|
managed fragment. A glob would add discovery behavior and could keep a removed
|
||||||
|
artifact active through a stale file. Deleting and recreating the directory on
|
||||||
|
every run would harm idempotence and caller safety merely to compensate for
|
||||||
|
that avoidable ambiguity.
|
||||||
|
|
||||||
|
One testing overlay is preferable to a second complete configuration tree.
|
||||||
|
Profiles replace only selected leaves after base composition, so topology and
|
||||||
|
paths cannot drift between production and development. The selected
|
||||||
|
`gemini-flash-latest` default provides immediate value while remaining one
|
||||||
|
ordinary role-default change when model economics evolve.
|
||||||
|
|
||||||
|
The uploaded Notarius pipeline is concrete and valid, but adding it here would
|
||||||
|
combine a ten-lane extraction contract, campaign-reference mapping, output
|
||||||
|
descriptor mapping, runtime directories, and model policy with an already
|
||||||
|
coherent Narratio/Scriptorium feature. Keeping it separate makes both reviews
|
||||||
|
smaller and preserves a clear acceptance boundary.
|
||||||
|
|
||||||
|
## Acceptance Criteria
|
||||||
|
|
||||||
|
### Required Configuration Behavior
|
||||||
|
|
||||||
|
- The pipeline role produces the documented imported configuration layout
|
||||||
|
with one file per artifact and artifact family.
|
||||||
|
- The root pipeline document contains the exact explicit relative imports and
|
||||||
|
no glob imports.
|
||||||
|
- Base Narratio configuration validates natively for either deployed campaign.
|
||||||
|
- The effective base configuration uses the selected Seriatim, Audita,
|
||||||
|
normalization, trimming, bounds, and rendering contracts and the canonical
|
||||||
|
artifact output paths documented above.
|
||||||
|
- `narratio config artifacts` reports a valid recap-to-rumor graph and expands
|
||||||
|
the character-analysis family for the selected campaign.
|
||||||
|
- The recap, rumor, scene-map, and character-family definitions use only inputs
|
||||||
|
and variables supported by their deployed prompt definitions and Narratio's
|
||||||
|
current source vocabulary.
|
||||||
|
- The two rumor dependencies are inferred from their recap input sources and
|
||||||
|
are not duplicated as explicit ordering edges.
|
||||||
|
- Scene map and the character-analysis family are available but disabled by
|
||||||
|
default; recap and both rumor artifacts are enabled.
|
||||||
|
- Production artifacts inherit their selected profiles from the prompt
|
||||||
|
definitions unless an expressly agreed suite override is documented.
|
||||||
|
- Audita's managed configuration contains the selected D&D policy and remains
|
||||||
|
valid through Audita's native validator.
|
||||||
|
- The same suite-owned `audita-v1` schema is supplied to Audita's managed
|
||||||
|
configuration and Narratio's Audita adapter; Narratio supplies Audita's
|
||||||
|
run-specific output path rather than relying on a second fixed path.
|
||||||
|
- `profiles/testing.yml` is a valid, independently selectable Narratio profile
|
||||||
|
that selects the configured inexpensive Scriptorium profile for every
|
||||||
|
artifact and family and inherits base workflow structure.
|
||||||
|
- The testing profile does not repeat Audita configuration while production
|
||||||
|
and testing deliberately share the same Audita endpoint and models.
|
||||||
|
- Base and testing configuration can be compared with
|
||||||
|
`narratio config diff default testing` without requiring a model call.
|
||||||
|
- All suite-managed configuration remains readable by the `narratio` group and
|
||||||
|
is not made writable by runtime or human operator accounts.
|
||||||
|
- An immediate repeated role application with unchanged inputs reports no
|
||||||
|
changes.
|
||||||
|
- The role contains no configuration probes, production self-validation,
|
||||||
|
fragment manifests, duplicate root template, secrets, Notarius integration,
|
||||||
|
storage, or publishing behavior.
|
||||||
|
|
||||||
|
### Required Validation
|
||||||
|
|
||||||
|
- YAML syntax checking and production-profile ansible-lint pass for the role
|
||||||
|
and test playbooks.
|
||||||
|
- The complete existing pipeline integration entry point continues to install
|
||||||
|
the pinned role combination and validate asset discovery.
|
||||||
|
- Audita natively validates the role-managed D&D configuration.
|
||||||
|
- Narratio natively validates both base and `testing` configuration with an
|
||||||
|
explicitly selected deployed campaign.
|
||||||
|
- Narratio's native artifact inspection demonstrates one enabled ordinary
|
||||||
|
artifact, one inferred dependency, and representative family expansion.
|
||||||
|
- A test explicitly supplies a representative testing Scriptorium profile and
|
||||||
|
observes its effective selection; it does not assert that the same value
|
||||||
|
remains the role's current default.
|
||||||
|
- Scriptorium can resolve the representative production and testing profiles
|
||||||
|
through its native inspection interface without making a provider request.
|
||||||
|
- The immediate repeat reports `changed=0` and `failed=0`.
|
||||||
|
- Tests do not snapshot full rendered files, enumerate every character or
|
||||||
|
artifact, inspect template/file task results, test filesystem metadata, or
|
||||||
|
reproduce ConfigKit, Narratio, Audita, Scriptorium, or Promptkit validation.
|
||||||
|
|
||||||
|
## Dependencies and Follow-up Work
|
||||||
|
|
||||||
|
Features 0001 through 0007 and the standalone-role test-suite simplification
|
||||||
|
are complete. Feature 0008 depends on the current Narratio 2.0 ConfigKit
|
||||||
|
contract, the canonical party files deployed by Feature 0007, and prompt
|
||||||
|
definitions whose production default profiles are available from Promptkit.
|
||||||
|
|
||||||
|
Feature 0010 should adapt the validated D&D Notarius pipeline, remove its
|
||||||
|
hard-coded campaign references in favor of Narratio invocation bindings,
|
||||||
|
declare its runtime-directory policy, map its accepted outputs into Narratio,
|
||||||
|
and enable extraction after Feature 0009 establishes shared filesystem and
|
||||||
|
execution policy. Later features should address storage/publishing and secret
|
||||||
|
delivery together, optional operator selection and membership management,
|
||||||
|
collection assembly, and an end-to-end workflow that can use actual external
|
||||||
|
services.
|
||||||
|
|
||||||
|
## Potential Future Hardening
|
||||||
|
|
||||||
|
- Use ConfigKit source inspection in operational diagnostics to show which
|
||||||
|
managed fragment supplied an effective value.
|
||||||
|
- Add a controlled cleanup policy for obsolete suite fragments if accumulated
|
||||||
|
inert files become an operational problem.
|
||||||
@@ -0,0 +1,266 @@
|
|||||||
|
# Feature 0009: Shared Pipeline Filesystem and Execution
|
||||||
|
|
||||||
|
Status: done
|
||||||
|
|
||||||
|
## Summary
|
||||||
|
|
||||||
|
Establish one coherent filesystem and invocation policy for the D&D suite.
|
||||||
|
Standalone application roles will expose sensible generic configuration
|
||||||
|
ownership and mode controls, while the pipeline role will use those controls
|
||||||
|
to make configuration service-owned and world-readable and to make writable
|
||||||
|
state safely shareable by the service account and existing human members of
|
||||||
|
its group.
|
||||||
|
|
||||||
|
## Problem or Opportunity
|
||||||
|
|
||||||
|
The current standalone roles hard-code their configuration ownership and
|
||||||
|
modes. Those defaults are reasonable in isolation, but the pipeline cannot
|
||||||
|
select its intended `narratio:narratio` ownership without adding a second
|
||||||
|
convergence pass that would fight the dependency roles and report changes on
|
||||||
|
every run.
|
||||||
|
|
||||||
|
Narratio's writable roots already use setgid mode `2775`, but directory mode
|
||||||
|
alone does not preserve group write access when different invocation identities
|
||||||
|
have different umasks. Notarius v0.7.0 has removed its application-enforced
|
||||||
|
private cache modes, so deployment provisioning can now establish a consistent
|
||||||
|
shared policy before Notarius integration begins.
|
||||||
|
|
||||||
|
## Governing Policies
|
||||||
|
|
||||||
|
- [The Ansible house style](../../ansible.md) governs the generic role
|
||||||
|
interfaces, direct module-driven convergence, and suite overrides.
|
||||||
|
- [The testing house style](../../testing.md) governs behavioral access tests
|
||||||
|
and clean repeated convergence.
|
||||||
|
- [The MVP roadmap](../mvp.md) assigns operator access and cross-application
|
||||||
|
policy to the pipeline role while keeping standalone roles independently
|
||||||
|
useful.
|
||||||
|
- [Decision 0001](../../decisions/0001-minimal-module-driven-ansible.md)
|
||||||
|
requires direct idempotent modules without preliminary state inspection.
|
||||||
|
- [Decision 0002](../../decisions/0002-shared-readable-pipeline-filesystem-policy.md)
|
||||||
|
defines the service ownership, shared writable state, world-readable content,
|
||||||
|
and restricted credential boundary implemented by this feature.
|
||||||
|
|
||||||
|
## Scope
|
||||||
|
|
||||||
|
- Add configuration owner, group, directory-mode, and file-mode variables to
|
||||||
|
the Audita, Notarius, Narratio, and Scriptorium roles.
|
||||||
|
- Preserve standalone defaults appropriate to each application rather than
|
||||||
|
embedding D&D suite policy in those roles.
|
||||||
|
- Add suite-level runtime identity and configuration-mode variables to the
|
||||||
|
pipeline role and pass them explicitly to all four configuration-bearing
|
||||||
|
dependencies.
|
||||||
|
- Run the Narratio dependency before the other application dependencies so it
|
||||||
|
creates the selected service account and group before they write
|
||||||
|
service-owned configuration.
|
||||||
|
- Converge suite application configuration as `narratio:narratio`, with
|
||||||
|
directory mode `0755` and file mode `0644` by default.
|
||||||
|
- Keep `/var/lib/narratio`, `/var/spool/narratio`, and
|
||||||
|
`/var/cache/narratio` as `narratio:narratio` mode `2775` shared writable
|
||||||
|
roots.
|
||||||
|
- Install the Ubuntu `acl` package, declare a pinned `ansible.posix`
|
||||||
|
collection dependency, and manage access and default ACL entries that retain
|
||||||
|
owner/group write and world read/traverse access beneath shared roots.
|
||||||
|
- Support invocation as either the service account or an existing human
|
||||||
|
member of the selected runtime group.
|
||||||
|
- Document the standalone defaults, pipeline overrides, expected group
|
||||||
|
membership, world-readable non-secret boundary, and reserved restricted
|
||||||
|
`secrets/` policy.
|
||||||
|
- Add focused integration coverage for public configuration-mode overrides,
|
||||||
|
cross-identity access, and immediate clean repeated convergence.
|
||||||
|
|
||||||
|
## Non-goals
|
||||||
|
|
||||||
|
- Upgrading Notarius, adding its ConfigKit import interface, deploying its
|
||||||
|
D&D pipeline, creating `/var/cache/notarius`, or enabling Narratio's
|
||||||
|
extraction stage; those belong to Feature 0010.
|
||||||
|
- Changing any application's native configuration fields or runtime behavior.
|
||||||
|
- Selecting human operators or changing their group membership.
|
||||||
|
- Creating or populating a `secrets/` directory, delivering credentials, or
|
||||||
|
defining secret injection.
|
||||||
|
- Making application configuration group-writable or supporting manual edits
|
||||||
|
to Ansible-managed configuration.
|
||||||
|
- Changing ownership of root-managed source checkouts, installed binaries,
|
||||||
|
campaign assets, or prompt assets.
|
||||||
|
- Recursively migrating pre-existing runtime content with incompatible modes
|
||||||
|
or ACLs.
|
||||||
|
- Running transcript processing, calling external services, or adding
|
||||||
|
scheduling and service management.
|
||||||
|
|
||||||
|
## Target End State
|
||||||
|
|
||||||
|
Each standalone role exposes the same four concepts using its application
|
||||||
|
prefix. Its defaults remain appropriate for an independent installation:
|
||||||
|
|
||||||
|
| Role | Configuration owner | Configuration group | Directory mode | File mode |
|
||||||
|
| --- | --- | --- | --- | --- |
|
||||||
|
| Audita | `root` | `root` | `0755` | `0644` |
|
||||||
|
| Notarius | `root` | `root` | `0755` | `0644` |
|
||||||
|
| Scriptorium | `root` | `root` | `0755` | `0644` |
|
||||||
|
| Narratio | `root` | `narratio` | `0750` | `0640` |
|
||||||
|
|
||||||
|
For example, the Notarius variables are
|
||||||
|
`notarius_config_owner`, `notarius_config_group`,
|
||||||
|
`notarius_config_directory_mode`, and `notarius_config_file_mode`; the other
|
||||||
|
roles use their corresponding prefixes. Each role uses these variables in the
|
||||||
|
ordinary directory and template tasks that already own its configuration. No
|
||||||
|
role adds a follow-up permission-repair task or preliminary inspection.
|
||||||
|
|
||||||
|
The pipeline role defines `dnd_pipeline_runtime_user` and
|
||||||
|
`dnd_pipeline_runtime_group`, both defaulting to `narratio`, plus
|
||||||
|
`dnd_pipeline_config_directory_mode: "0755"` and
|
||||||
|
`dnd_pipeline_config_file_mode: "0644"`. It passes those values as the four
|
||||||
|
roles' configuration owner, group, and mode inputs. Narratio executes first in
|
||||||
|
dependency order and creates the selected identity before another dependency
|
||||||
|
references it.
|
||||||
|
|
||||||
|
The resulting application configuration beneath
|
||||||
|
`/usr/local/etc/{audita,notarius,narratio,scriptorium}` is owned by
|
||||||
|
`narratio:narratio` and is world-readable. It remains under Ansible control;
|
||||||
|
neither the service account nor human operators are expected to edit managed
|
||||||
|
files in place.
|
||||||
|
|
||||||
|
The three existing Narratio writable roots are `narratio:narratio` mode
|
||||||
|
`2775`. Their access and default ACLs are equivalent to `u::rwx`, `g::rwx`,
|
||||||
|
`o::r-x`, and `m::rwx`. Inherited permissions remain subject to the mode
|
||||||
|
requested for each new file type, so ordinary files are non-executable while
|
||||||
|
remaining group-writable and world-readable. A later feature applies the same
|
||||||
|
policy when it introduces another shared root such as
|
||||||
|
`/var/cache/notarius`.
|
||||||
|
|
||||||
|
A human account already belonging to `narratio` can use the same configuration
|
||||||
|
and writable roots as the service account. This feature does not choose that
|
||||||
|
account. Credential files are absent; the reserved future
|
||||||
|
`/usr/local/etc/narratio/secrets` subtree uses the distinct `0750` directory
|
||||||
|
and `0640` file policy when a credential-delivery feature creates it.
|
||||||
|
|
||||||
|
## Repository Ownership
|
||||||
|
|
||||||
|
- `ansible-role-audita`, `ansible-role-notarius`, and
|
||||||
|
`ansible-role-scriptorium` own their generic configuration ownership and
|
||||||
|
mode variables, standalone defaults, documentation, and focused integration
|
||||||
|
coverage.
|
||||||
|
- `ansible-role-narratio` owns the equivalent generic controls while retaining
|
||||||
|
its existing standalone relationship to the service group it creates.
|
||||||
|
- `ansible-role-dnd-pipeline` owns dependency ordering, the suite runtime
|
||||||
|
identity and configuration-mode defaults, explicit dependency overrides,
|
||||||
|
the `acl` package and `ansible.posix` dependency, shared-root ACL
|
||||||
|
convergence, consumer documentation, and cross-identity integration
|
||||||
|
coverage.
|
||||||
|
- `ansible-workspace-dnd` owns this roadmap, Decision 0002, the later staged
|
||||||
|
implementation plan, and aggregate status.
|
||||||
|
- The five application source repositories are unchanged; their runtime
|
||||||
|
contracts are not needed to implement configuration-file ownership.
|
||||||
|
|
||||||
|
## Constraints and Settled Decisions
|
||||||
|
|
||||||
|
- Standalone application roles remain independently usable. Their defaults do
|
||||||
|
not assume that a `narratio` account exists unless the role itself creates
|
||||||
|
it.
|
||||||
|
- The pipeline role selects suite policy by passing public role variables; it
|
||||||
|
does not reapply ownership after dependencies have completed.
|
||||||
|
- Configuration owner and group variables are strings, while mode variables
|
||||||
|
use the quoted four-digit strings expected by Ansible file-management
|
||||||
|
modules.
|
||||||
|
- The pipeline's selected runtime user and group are the configuration owner
|
||||||
|
and group. Supporting different configuration and runtime identities would
|
||||||
|
require a concrete later use case.
|
||||||
|
- Application configuration is world-readable but not group-writable. Shared
|
||||||
|
writable roots and their ordinary content are group-writable and
|
||||||
|
world-readable.
|
||||||
|
- The role uses `ansible.builtin.apt` for the `acl` package and
|
||||||
|
`ansible.posix.acl` for access/default ACL state. The collection dependency
|
||||||
|
is pinned in the pipeline role's manifest and installed by its integration
|
||||||
|
driver.
|
||||||
|
- ACL management covers only the three existing writable roots and their
|
||||||
|
inheritance policy. It does not recursively rewrite existing descendants.
|
||||||
|
- A `secrets/` subtree is a documented future boundary, not state created by
|
||||||
|
this feature.
|
||||||
|
- Tests exercise the public operating contract and one representative
|
||||||
|
cross-identity workflow. They do not enumerate every path or restate every
|
||||||
|
module argument.
|
||||||
|
|
||||||
|
## Simplest Viable Implementation
|
||||||
|
|
||||||
|
1. Add four defaults, four argument-specification entries, and direct task
|
||||||
|
substitutions to each configuration-bearing standalone role; update its
|
||||||
|
README and focused integration inputs without adding new task flow.
|
||||||
|
2. Reorder the pipeline dependencies so Narratio creates the service identity
|
||||||
|
first, add four suite policy variables, and pass them directly to each
|
||||||
|
configuration-bearing role.
|
||||||
|
3. Add the pinned `ansible.posix` requirement, install `acl`, and apply the
|
||||||
|
selected access/default ACL entries to the three existing writable roots
|
||||||
|
with ordinary state-management modules.
|
||||||
|
4. Update pipeline consumer documentation and extend its integration driver
|
||||||
|
with one representative human group member, native configuration
|
||||||
|
inspection, shared-write behavior, and a clean repeat.
|
||||||
|
|
||||||
|
No task gathers preliminary filesystem or account state. Existing `file`,
|
||||||
|
`template`, `apt`, and `acl` modules own convergence and change reporting.
|
||||||
|
|
||||||
|
## Rationale and Alternatives
|
||||||
|
|
||||||
|
Public ownership and mode variables let each standalone role express its own
|
||||||
|
sensible installation while allowing a composing role to select different
|
||||||
|
policy through normal Ansible precedence. A corrective pipeline task would
|
||||||
|
fight the dependency templates and make every otherwise unchanged run report
|
||||||
|
changes.
|
||||||
|
|
||||||
|
Setgid alone preserves group identity but does not guarantee group-write bits
|
||||||
|
for files created under an arbitrary human user's umask. A managed default ACL
|
||||||
|
expresses the required inherited state directly. A wrapper command that sets a
|
||||||
|
umask would add another invocation path and would not protect direct use of the
|
||||||
|
installed applications.
|
||||||
|
|
||||||
|
Mode `2775`, rather than `2770`, is deliberate: D&D transcript content is not
|
||||||
|
treated as secret in this deployment. Only API keys and similar credentials
|
||||||
|
belong in the separately restricted future subtree.
|
||||||
|
|
||||||
|
## Acceptance Criteria
|
||||||
|
|
||||||
|
- Each configuration-bearing standalone role exposes and documents owner,
|
||||||
|
group, directory-mode, and file-mode variables with the standalone defaults
|
||||||
|
listed above.
|
||||||
|
- Each role applies those inputs through the tasks that already create its
|
||||||
|
configuration directory and file, without a second convergence pass.
|
||||||
|
- The pipeline role runs Narratio first and explicitly selects
|
||||||
|
`narratio:narratio`, `0755` directories, and `0644` files for all application
|
||||||
|
configuration.
|
||||||
|
- The deployed configuration for Audita, Notarius, Narratio, and Scriptorium
|
||||||
|
is owned by `narratio:narratio`, is readable by other local users, and
|
||||||
|
contains no credential values.
|
||||||
|
- The three existing Narratio writable roots are `narratio:narratio` mode
|
||||||
|
`2775` and have access/default ACLs that preserve group write and world
|
||||||
|
read/traverse access for new content.
|
||||||
|
- The pipeline role declares a pinned `ansible.posix` dependency and installs
|
||||||
|
the required Ubuntu `acl` package.
|
||||||
|
- The service account and a representative existing human member of the
|
||||||
|
`narratio` group can use the same configuration and exchange ordinary
|
||||||
|
writable-state content.
|
||||||
|
- The role does not create users other than the established service account,
|
||||||
|
alter human group membership, create a secrets directory, or migrate
|
||||||
|
existing descendants recursively.
|
||||||
|
- Syntax checking and production-profile lint pass in every changed role.
|
||||||
|
- Focused standalone-role integration checks and the complete pipeline
|
||||||
|
integration entry point pass.
|
||||||
|
- An immediate repeated application in every changed role reports no changes.
|
||||||
|
- Tests observe the shared operating contract without snapshotting defaults,
|
||||||
|
enumerating implementation steps, or testing trusted module behavior.
|
||||||
|
|
||||||
|
## Dependencies and Follow-up Work
|
||||||
|
|
||||||
|
Features 0001 through 0008 and the standalone-role test-suite simplification
|
||||||
|
are complete. Notarius v0.7.0's deployment-owned cache permissions remove the
|
||||||
|
application blocker that previously prevented this policy, but Feature 0009
|
||||||
|
does not otherwise depend on or modify the Notarius application.
|
||||||
|
|
||||||
|
Feature 0010 applies this policy to `/var/cache/notarius` while adding the D&D
|
||||||
|
extraction integration. Later work may add optional operator-selection and
|
||||||
|
group-membership variables or deliver credentials beneath the restricted
|
||||||
|
`secrets/` subtree.
|
||||||
|
|
||||||
|
## Potential Future Hardening
|
||||||
|
|
||||||
|
- Offer a non-world-readable deployment profile if a concrete environment
|
||||||
|
later treats campaign material as confidential.
|
||||||
|
- Select a recursive migration policy if supported upgrades must normalize
|
||||||
|
pre-existing descendants rather than only managed roots and new content.
|
||||||
@@ -0,0 +1,544 @@
|
|||||||
|
# Feature 0010: D&D Notarius Extraction Integration
|
||||||
|
|
||||||
|
Status: ready
|
||||||
|
|
||||||
|
## Summary
|
||||||
|
|
||||||
|
Enable Narratio's Notarius stage with the maintained ten-lane D&D extraction
|
||||||
|
pipeline. The pipeline role will supply the opinionated Notarius pipeline,
|
||||||
|
bind campaign-owned inputs through Narratio's invocation boundary, and declare
|
||||||
|
the exact lane contracts Narratio may accept as extraction sources. It uses
|
||||||
|
the service ownership and shared-access foundation established by Feature
|
||||||
|
0009.
|
||||||
|
|
||||||
|
## Problem or Opportunity
|
||||||
|
|
||||||
|
Features 0006 through 0008 install and configure the five applications,
|
||||||
|
deploy the D&D content, and define the transcript-processing and Scriptorium
|
||||||
|
workflow. Narratio still leaves its Notarius stage disabled, and Notarius's
|
||||||
|
managed configuration contains no pipeline. A run can therefore produce a
|
||||||
|
cleaned and trimmed transcript but cannot yet extract the structured D&D
|
||||||
|
registries and events implemented by Notarius.
|
||||||
|
|
||||||
|
The uploaded test-machine configuration demonstrates the intended multi-step
|
||||||
|
pipeline, but it embeds campaign-specific filesystem paths and explicit
|
||||||
|
runtime roots. The current Notarius v0.7.0 complete example and Narratio 2.0
|
||||||
|
integration boundary provide the maintained replacement. Narratio 2.0 names
|
||||||
|
Notarius v0.6.0 as its subprocess baseline, while Notarius v0.7.0 expressly
|
||||||
|
preserves that subprocess receipt and extraction-artifact contract. The
|
||||||
|
Notarius upgrade therefore changes deployment configuration without requiring
|
||||||
|
a Narratio adapter change. Narratio must prepare invocation-local campaign
|
||||||
|
references and own the run-specific output staging directory; generated
|
||||||
|
registry and event handoffs remain internal to Notarius. Notarius v0.7.0 also
|
||||||
|
replaces configuration version 4 with a strict, ConfigKit-backed version 5
|
||||||
|
contract and makes cache access policy a deployment responsibility.
|
||||||
|
|
||||||
|
## Governing Policies
|
||||||
|
|
||||||
|
- [The Ansible house style](../../ansible.md) governs the suite-owned public
|
||||||
|
interface, direct desired-state configuration, and reliance on the
|
||||||
|
standalone roles' native templates.
|
||||||
|
- [The testing house style](../../testing.md) governs focused native contract
|
||||||
|
validation and immediate clean repeated convergence.
|
||||||
|
- [The MVP roadmap](../mvp.md) assigns opinionated D&D policy and
|
||||||
|
cross-application coordination to the pipeline role while keeping the
|
||||||
|
standalone application roles generic.
|
||||||
|
- [Decision 0001](../../decisions/0001-minimal-module-driven-ansible.md)
|
||||||
|
requires module-owned convergence without redundant inspection or
|
||||||
|
supplemental state.
|
||||||
|
- [Decision 0002](../../decisions/0002-shared-readable-pipeline-filesystem-policy.md)
|
||||||
|
defines the service ownership, shared operator access, world-readable
|
||||||
|
content, and restricted credential boundary.
|
||||||
|
- [Feature 0008](0008-opinionated-dnd-processing-configuration.md) establishes
|
||||||
|
the trimmed transcript, ConfigKit layout, and `testing` overlay into which
|
||||||
|
this feature integrates.
|
||||||
|
- [Feature 0009](0009-shared-pipeline-filesystem-and-execution.md) establishes
|
||||||
|
the runtime identity, configuration ownership interfaces, and inherited
|
||||||
|
shared-access policy extended by this feature.
|
||||||
|
|
||||||
|
## Scope
|
||||||
|
|
||||||
|
- Update the standalone Notarius role for Notarius v0.7.0 and configuration
|
||||||
|
version 5 while preserving its generic, independently usable interface.
|
||||||
|
- Advance the pipeline role's selected Notarius application version to v0.7.0
|
||||||
|
and pin its Notarius role dependency to the reviewed revision that provides
|
||||||
|
the version 5 interface.
|
||||||
|
- Expose Notarius's native `configkit.imports` field through one optional
|
||||||
|
`notarius_configkit_imports` role variable; the role continues to own only
|
||||||
|
its root configuration and does not manage caller-selected fragments.
|
||||||
|
- Supply one complete `dnd-session` Notarius pipeline as deliberate D&D suite
|
||||||
|
policy in a suite-managed imported fragment at
|
||||||
|
`/usr/local/etc/notarius/pipelines/dnd-session.yml`.
|
||||||
|
- Adapt the maintained Notarius v0.7.0 complete D&D pipeline using canonical
|
||||||
|
version 5 module-binding objects, including:
|
||||||
|
- the embedded `dnd-extraction` PromptKit workload profile;
|
||||||
|
- Seriatim input and scene-based chunking;
|
||||||
|
- the ordered `describe-session`, `extract-events`, and `track-enemies`
|
||||||
|
steps;
|
||||||
|
- all ten maintained D&D artifact lanes and their generated handoffs; and
|
||||||
|
- JSON output with the chunk map and selected evidence context.
|
||||||
|
- Remove every campaign-specific filesystem reference from the Notarius
|
||||||
|
pipeline definition.
|
||||||
|
- Enable Narratio's Notarius stage and select `dnd-session`.
|
||||||
|
- Bind `party`, `players`, and `glossary` to Narratio's prepared campaign
|
||||||
|
sources at invocation time.
|
||||||
|
- Define Narratio acceptance descriptors for all ten maintained lane outputs.
|
||||||
|
- Make the pipeline map, Narratio reference map, and Narratio output map
|
||||||
|
ordinary suite variables so callers can compose or replace native mappings
|
||||||
|
through inventory precedence.
|
||||||
|
- Make the selected pipeline ID an ordinary suite variable and keep it
|
||||||
|
coordinated with the default pipeline map.
|
||||||
|
- Enable Notarius caching to the maximum currently available extent: use
|
||||||
|
`auto` chunk-plan caching and enable checkpoint recording. Narratio does not
|
||||||
|
yet request checkpoint reuse with Notarius's `--resume` flag.
|
||||||
|
- Provision `/var/cache/notarius` as a shared FHS cache root owned by
|
||||||
|
`narratio:narratio` with mode `2775`, and configure Notarius to create its
|
||||||
|
chunk-plan and checkpoint stores beneath that root.
|
||||||
|
- Apply Feature 0009's established access and default ACL policy to the new
|
||||||
|
cache root so content created by either supported invocation identity remains
|
||||||
|
group-writable and world-readable.
|
||||||
|
- Keep Notarius enabled under the existing `testing` overlay. Testing and
|
||||||
|
production select the same Notarius pipeline and workload profile until the
|
||||||
|
suite chooses a distinct testing profile strategy.
|
||||||
|
- Document the reference boundary, lane-to-source mapping, runtime-state
|
||||||
|
policy, production/testing behavior, and supported caller customization.
|
||||||
|
- Extend focused integration coverage for native Notarius validation,
|
||||||
|
Narratio base/testing resolution, representative reference and output
|
||||||
|
wiring, and immediate clean repeated convergence.
|
||||||
|
|
||||||
|
## Non-goals
|
||||||
|
|
||||||
|
- Changing any application's native configuration fields or duplicating a
|
||||||
|
standalone role's root configuration template in the pipeline role.
|
||||||
|
- Making the standalone Notarius role manage imported fragments; fragment
|
||||||
|
deployment remains the responsibility of the caller that selects an
|
||||||
|
import.
|
||||||
|
- Copying the uploaded test-machine configuration verbatim.
|
||||||
|
- Installing a filesystem PromptKit profile for Notarius. Notarius v0.7.0
|
||||||
|
already embeds the selected production `dnd-extraction` fallback profile.
|
||||||
|
- Defining a second Notarius pipeline solely to select an inexpensive testing
|
||||||
|
model, or otherwise adding profile inheritance that Notarius does not
|
||||||
|
natively provide.
|
||||||
|
- Binding a spell catalog before the campaign registry declares one.
|
||||||
|
- Publishing, rendering, or otherwise consuming the new extraction sources in
|
||||||
|
Scriptorium artifacts.
|
||||||
|
- Selecting a default campaign.
|
||||||
|
- Delivering API keys, provider credentials, environment files, or a general
|
||||||
|
secret-management mechanism.
|
||||||
|
- Running Notarius extraction, making model calls, or processing a complete
|
||||||
|
transcript during integration tests.
|
||||||
|
- Managing output retention, cache cleanup, or debug retention.
|
||||||
|
- Adding checkpoint-resume control to Narratio or changing Narratio's
|
||||||
|
subprocess invocation to pass `--resume` or `--config-profile`.
|
||||||
|
- Installing a systemd service, timer, scheduler, or other unattended
|
||||||
|
invocation mechanism.
|
||||||
|
- Selecting human operator accounts or changing their membership in the
|
||||||
|
`narratio` group.
|
||||||
|
- Revising the general configuration ownership, dependency ordering, ACL
|
||||||
|
dependency, or existing shared roots established by Feature 0009.
|
||||||
|
- Delivering or populating the future restricted `secrets/` directory.
|
||||||
|
- Modifying upstream application source, embedded Notarius prompts, schemas,
|
||||||
|
modules, codecs, or validators.
|
||||||
|
- Collection assembly, role releases, storage/publishing, upgrade/removal
|
||||||
|
behavior, or end-to-end production validation.
|
||||||
|
|
||||||
|
## Target End State
|
||||||
|
|
||||||
|
The standalone Notarius role continues to own the version 5 root document at
|
||||||
|
`/usr/local/etc/notarius/config.yml`. Its public interface exposes the native
|
||||||
|
`configkit.imports` list, and the pipeline role selects the explicit relative
|
||||||
|
import `pipelines/dnd-session.yml`. The pipeline role owns that fragment and
|
||||||
|
renders the complete `dnd_pipeline_notarius_pipelines` map into it, producing
|
||||||
|
one native `dnd-session` definition by default. The definition follows the
|
||||||
|
Notarius v0.7.0 maintained complete D&D topology:
|
||||||
|
|
||||||
|
```text
|
||||||
|
Seriatim transcript
|
||||||
|
-> dnd/scenes chunking
|
||||||
|
-> describe-session
|
||||||
|
item-registry
|
||||||
|
npc-registry
|
||||||
|
location-registry
|
||||||
|
scene-descriptions
|
||||||
|
-> extract-events
|
||||||
|
item-occurrences
|
||||||
|
spells
|
||||||
|
combat-turns
|
||||||
|
npc-occurrences
|
||||||
|
location-occurrences
|
||||||
|
-> track-enemies
|
||||||
|
enemy-events
|
||||||
|
-> JSON bundle, chunk map, and evidence context
|
||||||
|
```
|
||||||
|
|
||||||
|
Feature 0009 already makes application configuration service-owned and
|
||||||
|
world-readable. The Notarius root document and new suite fragment retain that
|
||||||
|
`narratio:narratio`, `0755` directory, and `0644` file policy through the
|
||||||
|
standalone role's established ownership and mode interface.
|
||||||
|
|
||||||
|
The `extract-events` step consumes the four generated outputs from
|
||||||
|
`describe-session` under their declared internal reference slots. The
|
||||||
|
`track-enemies` step consumes the generated NPC registry and scene
|
||||||
|
descriptions from `describe-session` and the generated combat turns and NPC
|
||||||
|
occurrences from `extract-events`. Those handoffs are part of the Notarius
|
||||||
|
pipeline and never appear in Narratio's CLI reference map.
|
||||||
|
|
||||||
|
Narratio's effective base configuration enables Notarius, selects the managed
|
||||||
|
configuration and `dnd-session`, and supplies three campaign-owned references:
|
||||||
|
|
||||||
|
| Notarius selector | Prepared Narratio source |
|
||||||
|
| --- | --- |
|
||||||
|
| `party` | `narratio.input.party` |
|
||||||
|
| `players` | `narratio.input.players` |
|
||||||
|
| `glossary` | `narratio.input.glossary` |
|
||||||
|
|
||||||
|
Narratio snapshots those inputs for each invocation and passes their absolute
|
||||||
|
paths with `--reference`. No campaign path appears in Notarius configuration.
|
||||||
|
The optional `spell_catalog` binding is absent because neither deployed
|
||||||
|
campaign currently declares `inputs.spell_catalog_file`. A caller that adds
|
||||||
|
that campaign input can extend the suite reference map with
|
||||||
|
`spell_catalog: narratio.input.spell_catalog` without changing either
|
||||||
|
application role.
|
||||||
|
|
||||||
|
Narratio accepts all ten configured lanes using these exact v1 contracts and
|
||||||
|
registers each accepted payload as `narratio.extraction.<output-key>`:
|
||||||
|
|
||||||
|
| Narratio output key | Lane ID | Schema ID | Module key |
|
||||||
|
| --- | --- | --- | --- |
|
||||||
|
| `item_registry` | `item-registry` | `notarius.dnd.item_registry` | `dnd/item-registry` |
|
||||||
|
| `npc_registry` | `npc-registry` | `notarius.dnd.npc_registry` | `dnd/npc-registry` |
|
||||||
|
| `location_registry` | `location-registry` | `notarius.dnd.location_registry` | `dnd/location-registry` |
|
||||||
|
| `scene_descriptions` | `scene-descriptions` | `notarius.dnd.scene_descriptions` | `dnd/scene-descriptions` |
|
||||||
|
| `item_occurrences` | `item-occurrences` | `notarius.dnd.item_occurrences` | `dnd/item-occurrences` |
|
||||||
|
| `spells` | `spells` | `notarius.dnd.spells` | `dnd/spells` |
|
||||||
|
| `combat_turns` | `combat-turns` | `notarius.dnd.combat_turns` | `dnd/combat-turns` |
|
||||||
|
| `npc_occurrences` | `npc-occurrences` | `notarius.dnd.npc_occurrences` | `dnd/npc-occurrences` |
|
||||||
|
| `location_occurrences` | `location-occurrences` | `notarius.dnd.location_occurrences` | `dnd/location-occurrences` |
|
||||||
|
| `enemy_events` | `enemy-events` | `notarius.dnd.enemy_events` | `dnd/enemy-events` |
|
||||||
|
|
||||||
|
Every entry requires `media_type: application/json` and
|
||||||
|
`schema_version: v1`. Narratio validates the received descriptor before
|
||||||
|
registering the source; it does not infer contracts from filenames.
|
||||||
|
|
||||||
|
Narratio supplies its run-specific staging root through Notarius's
|
||||||
|
`--output-dir` override, so the suite does not set Notarius's global
|
||||||
|
`output.directory`. Reconstructible Notarius state uses the FHS cache layout:
|
||||||
|
|
||||||
|
```text
|
||||||
|
/var/cache/notarius/
|
||||||
|
├── chunk-plans/
|
||||||
|
└── checkpoints/
|
||||||
|
```
|
||||||
|
|
||||||
|
The pipeline role creates the root as `narratio:narratio` mode `2775`, sets
|
||||||
|
chunk-plan mode to `auto`, enables checkpoint recording, and configures both
|
||||||
|
child paths. Notarius creates cache entries with conventional maximum creation
|
||||||
|
modes and leaves their effective modes to deployment provisioning, process
|
||||||
|
umask, setgid inheritance, and default ACLs. The suite applies a default ACL
|
||||||
|
that retains owner and group write access and world read/traverse access for
|
||||||
|
new cache content. Narratio and its Notarius subprocess may run as the
|
||||||
|
dedicated `narratio` account or as a human member of the `narratio` group.
|
||||||
|
Chunk plans are reused automatically; checkpoints are recorded but are not
|
||||||
|
reused because Narratio does not pass `--resume`. The debug root remains
|
||||||
|
unset. The selected Notarius process working directory is
|
||||||
|
`/usr/local/etc/notarius`, matching the managed configuration location; no
|
||||||
|
relative profile or reference paths depend on it.
|
||||||
|
|
||||||
|
The cache root receives the same setgid and default-ACL policy that Feature
|
||||||
|
0009 applies to Narratio's existing shared roots. Non-secret content created
|
||||||
|
beneath it remains writable by the shared group and readable by other local
|
||||||
|
users. The suite does not create or populate a `secrets/` directory.
|
||||||
|
|
||||||
|
The base Narratio configuration and the `testing` ConfigKit overlay both run
|
||||||
|
the extraction stage using Notarius's embedded `dnd-extraction` profile. The
|
||||||
|
testing overlay continues to override only the Scriptorium profile selections;
|
||||||
|
it does not disable or restate Notarius. A later feature may select a distinct
|
||||||
|
inexpensive Notarius testing profile without changing the pipeline topology.
|
||||||
|
|
||||||
|
## Repository Ownership
|
||||||
|
|
||||||
|
- `ansible-role-dnd-pipeline` owns the D&D pipeline map and imported fragment,
|
||||||
|
Narratio integration mappings, Notarius dependency-variable wiring, the new
|
||||||
|
cache root and its inherited shared-access policy, testing-overlay choice,
|
||||||
|
consumer documentation, and suite integration coverage.
|
||||||
|
- `ansible-role-notarius` owns the generic Notarius v0.7.0 installation,
|
||||||
|
version 5 root configuration, optional ConfigKit import interface, focused
|
||||||
|
role documentation, and role-local integration coverage. It does not own or
|
||||||
|
render the suite's imported D&D fragment.
|
||||||
|
- `ansible-role-audita`, `ansible-role-narratio`, and
|
||||||
|
`ansible-role-scriptorium` remain unchanged. The Narratio role owns its generic
|
||||||
|
Notarius adapter fields and ConfigKit-aware root configuration.
|
||||||
|
- `../notarius` is the read-only authority for configuration version 5, the
|
||||||
|
maintained D&D pipeline, embedded profile, module handoffs, and lane
|
||||||
|
contracts.
|
||||||
|
- `../narratio` is the read-only authority for prepared campaign sources,
|
||||||
|
subprocess invocation, output acceptance, and profile overlay behavior.
|
||||||
|
- `assets/configs/notarius/config.yml` is an operational reference only. Its
|
||||||
|
useful topology is adapted, while its campaign paths and runtime roots are
|
||||||
|
not copied.
|
||||||
|
- `assets/campaigns` remains unchanged and continues to own the campaign
|
||||||
|
registry inputs that Narratio prepares.
|
||||||
|
- `ansible-workspace-dnd` owns this roadmap, the later implementation plan,
|
||||||
|
settled MVP decisions, and aggregate status.
|
||||||
|
|
||||||
|
## Constraints and Settled Decisions
|
||||||
|
|
||||||
|
- This feature advances the standalone role default and pipeline application
|
||||||
|
selection from Notarius v0.6.0 to v0.7.0. Narratio remains at v2.0.0.
|
||||||
|
- Narratio v2.0.0 documents Notarius v0.6.0 as its invocation baseline, but
|
||||||
|
Notarius v0.7.0 preserves the subprocess receipt and extraction-artifact
|
||||||
|
contracts. Version 5 configuration migration is confined to the Notarius
|
||||||
|
role and the suite-owned Notarius fragment.
|
||||||
|
- The pipeline dependency manifest must pin the reviewed standalone Notarius
|
||||||
|
role revision that implements this v0.7.0/configuration-version-5 contract.
|
||||||
|
- Feature 0009 has already established the runtime identity, dependency order,
|
||||||
|
standalone ownership interfaces, configuration modes, `acl` package, and
|
||||||
|
pinned `ansible.posix` dependency used here.
|
||||||
|
- The pipeline role relies on the standalone roles for application
|
||||||
|
installation and both root configuration documents. It manages only the
|
||||||
|
suite-owned Notarius and Narratio fragments selected through those public
|
||||||
|
interfaces.
|
||||||
|
- The standalone Notarius role defaults to configuration version 5 and exposes
|
||||||
|
`notarius_configkit_imports` as the complete native import list. A null value
|
||||||
|
omits the `configkit` section and leaves composition with Notarius.
|
||||||
|
- The pipeline role passes the fixed import
|
||||||
|
`pipelines/dnd-session.yml` to the standalone role and manages that imported
|
||||||
|
file as suite-owned configuration. It does not pass the pipeline map into
|
||||||
|
the standalone role's root-level `notarius_pipelines` field.
|
||||||
|
- `/var/cache/notarius` uses the Feature 0009 runtime identity, mode `2775`,
|
||||||
|
and access/default ACL entries equivalent to `u::rwx`, `g::rwx`, `o::r-x`,
|
||||||
|
and `m::rwx`.
|
||||||
|
- `dnd_pipeline_notarius_pipelines` is a complete native map whose default
|
||||||
|
contains `dnd-session`. Callers may replace it or compose additional
|
||||||
|
pipeline definitions with Jinja's `combine` filter in inventory.
|
||||||
|
- `dnd_pipeline_narratio_notarius_pipeline_id` defaults to `dnd-session`.
|
||||||
|
Callers that replace that key are responsible for selecting a matching ID.
|
||||||
|
- `dnd_pipeline_narratio_notarius_references` is the complete native Narratio
|
||||||
|
reference map. It defaults to `party`, `players`, and `glossary`; its values
|
||||||
|
are prepared source IDs, never filesystem paths.
|
||||||
|
- `dnd_pipeline_narratio_notarius_outputs` is the complete native Narratio
|
||||||
|
output map. It defaults to all ten lanes because the suite claims to consume
|
||||||
|
the complete maintained D&D extraction workflow.
|
||||||
|
- `dnd_pipeline_notarius_cache_root` defaults to `/var/cache/notarius`,
|
||||||
|
`dnd_pipeline_notarius_cache_chunk_plans_mode` defaults to `auto`, and
|
||||||
|
`dnd_pipeline_notarius_cache_checkpoints_enabled` defaults to `true`. They
|
||||||
|
are intentional, inventory-overridable suite policy. The two application
|
||||||
|
cache directories derive from that root rather than becoming independent
|
||||||
|
suite variables.
|
||||||
|
- The pipeline defaults to `llm_profile: dnd-extraction` and relies on
|
||||||
|
Notarius's embedded fallback. It does not set `promptkit.profile_file`,
|
||||||
|
`promptkit.profile_dir`, a local backend, or credentials.
|
||||||
|
- The pipeline uses the version 5 `input: {module: seriatim}` binding,
|
||||||
|
`dnd/scenes` chunking with two retries, and the three ordered steps documented
|
||||||
|
above. Extract, merge, and normalize bindings use canonical objects with
|
||||||
|
`module:`; retries and generated reference handoffs match the maintained
|
||||||
|
Notarius complete example.
|
||||||
|
- JSON output enables `include_chunk_map` and evidence context with a
|
||||||
|
three-unit window. Evidence context includes item occurrences, item
|
||||||
|
registry, location registry, location occurrences, NPC registry, spells,
|
||||||
|
combat turns, NPC occurrences, and enemy events, matching the maintained
|
||||||
|
example.
|
||||||
|
- Notarius pipeline YAML contains no external file references. Narratio owns
|
||||||
|
all campaign input materialization for the orchestrated path.
|
||||||
|
- Narratio's Notarius binary and configuration paths remain the established
|
||||||
|
`/usr/local/bin/notarius` and `/usr/local/etc/notarius/config.yml`.
|
||||||
|
- The suite uses the runtime user and group selected by Feature 0009 for the
|
||||||
|
Notarius cache and configuration fragment.
|
||||||
|
- Narratio's Notarius working directory is explicitly
|
||||||
|
`/usr/local/etc/notarius`; the timeout inherits Narratio's native three-hour
|
||||||
|
default because the suite has selected no different policy.
|
||||||
|
- Narratio owns per-run Notarius output staging. The suite provisions
|
||||||
|
`/var/cache/notarius` for the shared `narratio` identity, and Notarius owns
|
||||||
|
its child cache stores. The role does not create `/var/lib/notarius`, set a
|
||||||
|
global output root, or provision a debug root.
|
||||||
|
- Checkpoint enablement records reusable state but does not cause Narratio to
|
||||||
|
reuse it. Resume remains an explicit Notarius invocation action and requires
|
||||||
|
a later Narratio integration decision.
|
||||||
|
- The production configuration enables Notarius. The existing `testing`
|
||||||
|
overlay inherits that enabled stage and the same `dnd-extraction` profile;
|
||||||
|
it does not override Notarius merely to avoid model calls.
|
||||||
|
- All maps use native application shapes and remain replaceable through normal
|
||||||
|
inventory precedence. The suite does not create field-by-field aliases for
|
||||||
|
every nested lane or module option.
|
||||||
|
- Directory and ACL tasks declare only the shared roots required by the
|
||||||
|
applications, using ordinary state-management modules with task-level
|
||||||
|
privilege escalation. No `stat`, command, handler, checksum, manifest, or
|
||||||
|
production validation task accompanies them.
|
||||||
|
|
||||||
|
## Simplest Viable Implementation
|
||||||
|
|
||||||
|
The production changes remain direct configuration management:
|
||||||
|
|
||||||
|
1. Update the standalone Notarius role's version and configuration-version
|
||||||
|
defaults and add the nullable native ConfigKit import field to defaults,
|
||||||
|
argument specification, root template, and documentation. Cover that public
|
||||||
|
behavior with focused native validation and a clean repeat.
|
||||||
|
2. Advance the pipeline's Notarius application selection and standalone-role
|
||||||
|
dependency pin, then add the selected Notarius pipeline map, shared FHS
|
||||||
|
cache policy, and three suite-level Narratio integration mappings to
|
||||||
|
pipeline-role defaults and the argument specification.
|
||||||
|
3. Pass the fixed import and cache choices to `rakestraw.notarius`, and pass
|
||||||
|
Notarius enablement, selected ID, working directory, references, and outputs
|
||||||
|
to `rakestraw.narratio`.
|
||||||
|
4. Create the Notarius pipeline-fragment directory and cache root with ordinary
|
||||||
|
`ansible.builtin.file` tasks, render the suite-owned pipeline map into one
|
||||||
|
imported fragment, and extend Feature 0009's access/default ACL task to the
|
||||||
|
new root.
|
||||||
|
5. Update both role READMEs and extend focused integration coverage with native
|
||||||
|
configuration validation, effective-configuration inspection, inspection
|
||||||
|
as a supported group member, and clean repeats.
|
||||||
|
|
||||||
|
The standalone roles' template operations continue to own both root
|
||||||
|
configuration files. The pipeline role adds one Notarius pipeline-fragment
|
||||||
|
template but does not duplicate the root document or change the existing
|
||||||
|
Narratio testing-overlay template for this feature.
|
||||||
|
|
||||||
|
## Rationale and Alternatives
|
||||||
|
|
||||||
|
Using Notarius's maintained complete example preserves the upstream module
|
||||||
|
topology and contract while keeping suite policy explicit. Maintaining a
|
||||||
|
smaller custom pipeline would make the role responsible for deciding which
|
||||||
|
D&D artifacts no longer matter. Copying the uploaded file would instead
|
||||||
|
preserve obsolete host paths and bypass Narratio's verified reference
|
||||||
|
boundary.
|
||||||
|
|
||||||
|
Rendering one native map into a ConfigKit-imported fragment keeps configuration
|
||||||
|
ownership clear and preserves the inventory-composition workflow already
|
||||||
|
selected for Notarius. It also follows Notarius v0.7.0's maintained composition
|
||||||
|
shape without making the generic role own D&D content. Field-specific variables
|
||||||
|
for every lane, step, and retry would create a large parallel schema with little
|
||||||
|
consumer value. One complete map is easier to replace, combine, validate, and
|
||||||
|
compare with Notarius documentation.
|
||||||
|
|
||||||
|
`/var/cache/notarius` follows the filesystem hierarchy's intended location for
|
||||||
|
reconstructible application state and is preferable to the uploaded
|
||||||
|
`/var/lib/notarius/cache` layout. Assigning the root to the dedicated
|
||||||
|
`narratio` account and group gives unattended and human-initiated runs one
|
||||||
|
reusable cache. Mode `2775` preserves the shared group, and the default ACL
|
||||||
|
prevents an invoking account's umask from accidentally removing group write or
|
||||||
|
world read access from new content. Notarius v0.7.0 respects this deployment
|
||||||
|
policy rather than replacing it with application-owned private modes.
|
||||||
|
Narratio's staging root remains separate because output bundles are run
|
||||||
|
results, not cache data.
|
||||||
|
|
||||||
|
The `testing` overlay cannot natively replace a nested Notarius pipeline's
|
||||||
|
`llm_profile`; that configuration lives in a separate application file.
|
||||||
|
Duplicating the full pipeline or managing a second Notarius root configuration
|
||||||
|
would add substantial configuration drift for one model choice. Testing
|
||||||
|
therefore inherits production extraction for now; a distinct testing strategy
|
||||||
|
can be selected later if it becomes a concrete need.
|
||||||
|
|
||||||
|
## Acceptance Criteria
|
||||||
|
|
||||||
|
### Required Configuration Behavior
|
||||||
|
|
||||||
|
- The pipeline role installs a Notarius configuration that natively validates
|
||||||
|
the `dnd-session` pipeline without provider credentials or a model call.
|
||||||
|
- The pipeline role selects Notarius v0.7.0 and its dependency manifest pins
|
||||||
|
the reviewed standalone-role revision that supplies the version 5 interface.
|
||||||
|
- The standalone Notarius role supports an explicitly selected v0.7.0,
|
||||||
|
emits configuration version 5 with its compatible defaults, and can render
|
||||||
|
a caller-supplied native ConfigKit import list.
|
||||||
|
- The root Notarius configuration imports the suite-owned
|
||||||
|
`pipelines/dnd-session.yml` fragment, and that fragment contains the complete
|
||||||
|
pipeline map selected through inventory.
|
||||||
|
- The pipeline contains the maintained Seriatim input, D&D scene chunker,
|
||||||
|
three ordered steps, ten lanes, generated handoffs, JSON chunk map, and
|
||||||
|
selected evidence-context policy.
|
||||||
|
- The Notarius configuration contains no campaign-specific reference paths,
|
||||||
|
PromptKit operator-profile path, fixed output root, or debug root.
|
||||||
|
- The Notarius configuration selects `auto` chunk-plan caching, enables
|
||||||
|
checkpoints, and uses `/var/cache/notarius/chunk-plans` and
|
||||||
|
`/var/cache/notarius/checkpoints` respectively.
|
||||||
|
- The deployed cache root is `narratio:narratio` mode `2775`; its access and
|
||||||
|
default ACLs preserve group write and world read/traverse access without
|
||||||
|
depending on Notarius to enforce entry modes. Checkpoints are recorded; the
|
||||||
|
roadmap does not claim Narratio reuses them.
|
||||||
|
- The Notarius root configuration and suite-owned imported fragment retain
|
||||||
|
Feature 0009's `narratio:narratio`, `0755` directory, and `0644` file policy.
|
||||||
|
No secret value appears in either file.
|
||||||
|
- Narratio's effective base configuration enables Notarius, selects
|
||||||
|
`dnd-session`, and uses the installed binary, configuration, and working
|
||||||
|
directory.
|
||||||
|
- Narratio maps `party`, `players`, and `glossary` to the three documented
|
||||||
|
prepared campaign sources and contains no default `spell_catalog` binding.
|
||||||
|
- Narratio declares all ten documented output entries with exact lane, media,
|
||||||
|
schema, version, and module identities.
|
||||||
|
- Narratio natively validates the effective base configuration for either
|
||||||
|
deployed campaign without a model call.
|
||||||
|
- `narratio config show` or the equivalent native inspection surface exposes
|
||||||
|
the enabled stage, selected pipeline, representative reference, and
|
||||||
|
representative output contract.
|
||||||
|
- The effective `testing` profile keeps Notarius enabled with the same pipeline
|
||||||
|
and profile while retaining the existing Scriptorium testing overrides.
|
||||||
|
- A caller can compose an additional Notarius pipeline into
|
||||||
|
`dnd_pipeline_notarius_pipelines` and select it through the corresponding
|
||||||
|
Narratio pipeline-ID variable without changing the role.
|
||||||
|
- A caller can add the optional spell-catalog source by extending the native
|
||||||
|
Narratio reference map after providing that campaign input.
|
||||||
|
- An immediate repeated role application with unchanged inputs reports no
|
||||||
|
changes.
|
||||||
|
- The production role contains no new configuration probes, validation
|
||||||
|
commands, runtime state beyond the required cache root, state bookkeeping,
|
||||||
|
duplicated root templates, secrets, extraction invocation, storage, or
|
||||||
|
publishing behavior.
|
||||||
|
|
||||||
|
### Required Validation
|
||||||
|
|
||||||
|
- YAML syntax checking and production-profile ansible-lint pass for the role
|
||||||
|
and test playbooks.
|
||||||
|
- The standalone-role integration suite explicitly selects Notarius v0.7.0,
|
||||||
|
validates a representative imported version 5 configuration through the
|
||||||
|
native CLI, and retains immediate clean repeated convergence without
|
||||||
|
asserting that v0.7.0 remains the default forever.
|
||||||
|
- The complete existing pipeline integration entry point continues to install
|
||||||
|
the pinned role combination and validate both deployed campaigns.
|
||||||
|
- A representative human account in the `narratio` group can execute native
|
||||||
|
Notarius configuration inspection through the same files used by the service
|
||||||
|
account.
|
||||||
|
- Notarius natively validates the role-managed `dnd-session` configuration.
|
||||||
|
- Notarius `config effective` exposes the composed imported pipeline and a
|
||||||
|
representative cache override without parsing managed YAML directly.
|
||||||
|
- Narratio natively validates both base and `testing` configurations with an
|
||||||
|
explicitly selected deployed campaign.
|
||||||
|
- Focused native inspection observes a representative generated Notarius
|
||||||
|
handoff and representative Narratio reference and output mappings rather
|
||||||
|
than reproducing the full application validators in shell assertions.
|
||||||
|
- A test explicitly supplies a small additional or replacement Notarius
|
||||||
|
pipeline mapping and observes that selected behavior; it does not assert
|
||||||
|
that `dnd-session` remains the role's current default forever.
|
||||||
|
- A representative test explicitly overrides one cache choice and observes
|
||||||
|
the effective Notarius configuration; it does not freeze all current cache
|
||||||
|
defaults or test Notarius's cache implementation.
|
||||||
|
- The immediate repeat reports `changed=0` and `failed=0`.
|
||||||
|
- Tests do not execute extraction, call an LLM, snapshot complete rendered
|
||||||
|
files, enumerate every nested option as an implementation lock, inspect
|
||||||
|
template task results, test filesystem metadata, or reproduce Ansible,
|
||||||
|
Notarius, Narratio, ConfigKit, or PromptKit behavior.
|
||||||
|
|
||||||
|
## Dependencies and Follow-up Work
|
||||||
|
|
||||||
|
Features 0001 through 0009 and the standalone-role test-suite simplification
|
||||||
|
are complete, so the shared filesystem and execution prerequisite is
|
||||||
|
satisfied. Implementation depends on the current Notarius v0.7.0 maintained
|
||||||
|
D&D configuration and ConfigKit contract, the compatible Narratio v2.0.0
|
||||||
|
subprocess boundary, campaign sources deployed by Feature 0007, and trimmed
|
||||||
|
transcript policy defined by Feature 0008.
|
||||||
|
|
||||||
|
The next suite feature should select which extraction sources feed new or
|
||||||
|
existing Scriptorium artifacts, or address pipeline-wide credential delivery
|
||||||
|
if real end-to-end execution requires it first. Later work should cover
|
||||||
|
storage and publishing, optional operator selection and membership management,
|
||||||
|
collection assembly, release pinning, and an end-to-end workflow using actual
|
||||||
|
external services. A separate feature may add inexpensive Notarius testing
|
||||||
|
extraction if a concrete workflow justifies a second operator profile or
|
||||||
|
application configuration.
|
||||||
|
|
||||||
|
## Potential Future Hardening
|
||||||
|
|
||||||
|
- Add explicit cache and debug retention policy once operational use provides
|
||||||
|
concrete retention requirements.
|
||||||
|
- Define credential delivery beneath the restricted `secrets/` subtree. No
|
||||||
|
further Notarius cache-permission feature is required for shared invocation.
|
||||||
|
- Pin content repositories to immutable releases when their upstream projects
|
||||||
|
begin publishing them.
|
||||||
@@ -1,14 +1,613 @@
|
|||||||
# Implementation Plan
|
# Implementation Plan 0010: D&D Notarius Extraction Integration
|
||||||
|
|
||||||
Status: pending
|
Status: ready
|
||||||
|
|
||||||
No implementation plan is currently active. Feature 0006 was implemented in
|
Target executor: GPT-5.6-Terra
|
||||||
`ansible-role-dnd-pipeline` commits `b515968` and `61869d1`, independently
|
|
||||||
reviewed, and finalized by remediation commit `4ea4358`.
|
|
||||||
|
|
||||||
Its durable scope and rationale remain in
|
Feature roadmap:
|
||||||
[the Feature 0006 roadmap](features/0006-pipeline-role-composition-foundation.md),
|
`docs/roadmap/features/0010-dnd-notarius-extraction-integration.md`
|
||||||
and its final review record remains in [the remediation record](remediation.md).
|
|
||||||
|
|
||||||
Select and approve the next unit of work before replacing this notice with a
|
Active plan location: `docs/roadmap/implementation.md`
|
||||||
new staged implementation plan.
|
|
||||||
|
## Objective
|
||||||
|
|
||||||
|
Upgrade the generic Notarius role to the v0.7.0 configuration contract, then
|
||||||
|
have the D&D pipeline role deploy the maintained ten-lane extraction pipeline,
|
||||||
|
enable it through Narratio, bind prepared campaign references, accept all ten
|
||||||
|
lane contracts, and provision the shared FHS cache policy established by
|
||||||
|
Feature 0009.
|
||||||
|
|
||||||
|
The feature roadmap remains authoritative for scope, rationale, target end
|
||||||
|
state, and acceptance criteria. Decisions 0001 and 0002 remain authoritative
|
||||||
|
for direct Ansible convergence and the shared-readable filesystem boundary.
|
||||||
|
|
||||||
|
## Execution Rules
|
||||||
|
|
||||||
|
- Execute stages in numeric order.
|
||||||
|
- Before each stage, confirm its preconditions and the working-tree state of
|
||||||
|
its owning repository.
|
||||||
|
- Before each stage, reread every document listed in that stage's Required
|
||||||
|
Policy Review. Do not rely on policy recalled from an earlier stage.
|
||||||
|
- Preserve unrelated and pre-existing changes. Stop if an owning repository is
|
||||||
|
unexpectedly dirty at a stage boundary.
|
||||||
|
- Keep `ansible-role-notarius` generic. ConfigKit import support is a native
|
||||||
|
application interface; the D&D pipeline, campaign bindings, cache policy,
|
||||||
|
and Narratio coordination belong only to `ansible-role-dnd-pipeline`.
|
||||||
|
- Use the Notarius v0.7.0 maintained complete pipeline as the topology and
|
||||||
|
contract authority. Remove external path references, but retain generated
|
||||||
|
artifact handoffs and canonical version 5 binding objects.
|
||||||
|
- Trust the existing application-role templates and Ansible modules. Do not
|
||||||
|
add production validation commands, preliminary probes, manual comparisons,
|
||||||
|
handlers, checksums, manifests, state files, or corrective permission tasks.
|
||||||
|
- Create only the shared Notarius cache root. Notarius owns creation of its
|
||||||
|
configured `chunk-plans` and `checkpoints` children during actual use.
|
||||||
|
- Keep the existing Narratio `testing` overlay unchanged so it inherits the
|
||||||
|
enabled Notarius stage and `dnd-extraction` workload profile.
|
||||||
|
- Do not add credentials, a PromptKit profile file, campaign paths, a global
|
||||||
|
Notarius output or debug root, checkpoint resume, extraction execution,
|
||||||
|
model calls, storage, publishing, services, schedules, or user-membership
|
||||||
|
management.
|
||||||
|
- Test public behavior through the installed applications' native inspection
|
||||||
|
and validation interfaces. Do not snapshot complete configuration files,
|
||||||
|
parse production task results, inspect filesystem metadata, or reproduce
|
||||||
|
application and Ansible validators in assertions.
|
||||||
|
- Run every stage's validation before committing it. Commit each completed
|
||||||
|
stage when it leaves the owning repository valid, using the plain-English
|
||||||
|
commit intent specified by that stage.
|
||||||
|
- Do not begin a dependent stage after an earlier stage fails validation.
|
||||||
|
- The pipeline integration suite installs role dependencies from their
|
||||||
|
canonical Git origins. The Stage 1 Notarius-role commit must therefore be
|
||||||
|
reachable from its canonical origin before Stage 2 begins. If it is not,
|
||||||
|
stop after Stage 1 and report the commit hash for publication; do not use a
|
||||||
|
branch, local path, or weakened dependency test as a substitute.
|
||||||
|
|
||||||
|
## Starting State and Preconditions
|
||||||
|
|
||||||
|
- The workspace control repository contains the reviewed Feature 0010 roadmap
|
||||||
|
and this implementation plan on `main` in a clean planning commit descended
|
||||||
|
from `f91871ba0f90da19592eb56824f5abb9e7868285`.
|
||||||
|
- Features 0001 through 0009 and the standalone-role test-suite simplification
|
||||||
|
are complete.
|
||||||
|
- The implementation repositories are clean on `main` at these reviewed
|
||||||
|
starting commits:
|
||||||
|
|
||||||
|
| Repository | Starting commit |
|
||||||
|
| --- | --- |
|
||||||
|
| `ansible-role-notarius` | `e9ae2dc34023e1e8462bf0991de62b97d8c0e0ee` |
|
||||||
|
| `ansible-role-dnd-pipeline` | `b15fe8dcf57a53784bc3b0b8bf04aa97d39edb3f` |
|
||||||
|
|
||||||
|
- The Notarius-role starting commit matches `origin/main`. The pipeline role
|
||||||
|
is intentionally ahead of its canonical origin and must not be reset or
|
||||||
|
replaced.
|
||||||
|
- `../notarius` is clean at the immutable `v0.7.0` tag,
|
||||||
|
`4e77725b24cb62bd1f96ee31b4d17b4a2ed68ba7`.
|
||||||
|
- `../narratio` is clean at the immutable `v2.0.0` tag,
|
||||||
|
`ed4623bc415901134c765fe9cf06d59aa7891500`.
|
||||||
|
- Notarius v0.7.0 preserves the subprocess receipt and extraction-artifact
|
||||||
|
contracts consumed by Narratio v2.0.0 while requiring Notarius
|
||||||
|
configuration version 5.
|
||||||
|
- The workspace `.venv` provides Ansible Core 2.21.3 and ansible-lint 26.8.0.
|
||||||
|
- The local integration environment remains an accepted proxy for Ubuntu
|
||||||
|
26.04, supports task-level privilege escalation, and provides ordinary POSIX
|
||||||
|
ACL behavior.
|
||||||
|
|
||||||
|
## Repository Scope
|
||||||
|
|
||||||
|
Repositories that change:
|
||||||
|
|
||||||
|
- `ansible-role-notarius`: v0.7.0 selection, configuration version 5,
|
||||||
|
nullable native ConfigKit imports, generic documentation, and focused
|
||||||
|
integration coverage.
|
||||||
|
- `ansible-role-dnd-pipeline`: compatible Notarius role and application pins,
|
||||||
|
opinionated D&D pipeline configuration, Narratio integration, shared cache
|
||||||
|
root, documentation, and focused integration coverage.
|
||||||
|
- `ansible-workspace-dnd`: implementation progress and review handoff only
|
||||||
|
after the role stages are complete.
|
||||||
|
|
||||||
|
Repositories that may be inspected but must remain unchanged:
|
||||||
|
|
||||||
|
- `../notarius` and `../narratio`, which are read-only application authorities.
|
||||||
|
- `ansible-role-narratio`, whose generic Notarius adapter already exposes all
|
||||||
|
fields required by this feature.
|
||||||
|
- `ansible-role-audita`, `ansible-role-seriatim`,
|
||||||
|
`ansible-role-scriptorium`, and `ansible-collection-dnd`.
|
||||||
|
- `assets/campaigns`, `assets/narratio-prompts`, and `assets/configs`.
|
||||||
|
- `rakestraw-ansible` and every other repository in `workspace.yml`.
|
||||||
|
|
||||||
|
## Stage 1: Upgrade the Generic Notarius Role
|
||||||
|
|
||||||
|
Status: complete (`14a38e04e35ef524d6a97fa7fb5a04981a0a2161`)
|
||||||
|
|
||||||
|
### Objective
|
||||||
|
|
||||||
|
Make the standalone role install Notarius v0.7.0, render configuration version
|
||||||
|
5, and expose the application's native ConfigKit import list without adding
|
||||||
|
D&D-specific policy.
|
||||||
|
|
||||||
|
### Required Policy Review
|
||||||
|
|
||||||
|
Before beginning this stage, read:
|
||||||
|
|
||||||
|
- `AGENTS.md`
|
||||||
|
- `docs/orientation.md`
|
||||||
|
- `docs/conventions.md`
|
||||||
|
- `docs/ansible.md`
|
||||||
|
- `docs/testing.md`
|
||||||
|
- `docs/roadmap/features/0010-dnd-notarius-extraction-integration.md`
|
||||||
|
- `docs/decisions/0001-minimal-module-driven-ansible.md`
|
||||||
|
- `../notarius/docs/releases/v0.7.0.md`
|
||||||
|
- `../notarius/docs/config.md`
|
||||||
|
- `../notarius/docs/cli.md`
|
||||||
|
- `../notarius/examples/dnd-complete.config.yml`
|
||||||
|
- `../notarius/examples/pipelines/dnd-session.yml`
|
||||||
|
- `ansible-role-notarius/defaults/main.yml`
|
||||||
|
- `ansible-role-notarius/meta/argument_specs.yml`
|
||||||
|
- `ansible-role-notarius/templates/config.yml.j2`
|
||||||
|
- `ansible-role-notarius/tests/integration`
|
||||||
|
- `ansible-role-notarius/tests/verify-config.yml`
|
||||||
|
- `ansible-role-notarius/README.md`
|
||||||
|
|
||||||
|
### Preconditions
|
||||||
|
|
||||||
|
- `ansible-role-notarius` is clean at its stated starting commit.
|
||||||
|
- The repository's existing `tests/integration` entry point passes before
|
||||||
|
modification.
|
||||||
|
- The v0.7.0 upstream files listed above remain at the reviewed immutable tag.
|
||||||
|
|
||||||
|
### Owning Repository
|
||||||
|
|
||||||
|
`ansible-role-notarius`
|
||||||
|
|
||||||
|
### Required Changes
|
||||||
|
|
||||||
|
1. Advance `notarius_version` from `v0.6.0` to `v0.7.0` and
|
||||||
|
`notarius_config_version` from `4` to `5`. Do not change the established
|
||||||
|
source-build task flow or other generic defaults.
|
||||||
|
2. Add `notarius_configkit_imports: null` as one optional public variable and
|
||||||
|
add a matching argument-specification entry using a list of native mapping
|
||||||
|
objects. Do not create field aliases for import entries or add role-owned
|
||||||
|
merge behavior.
|
||||||
|
3. Render a top-level `configkit.imports` section only when
|
||||||
|
`notarius_configkit_imports is not none`. Serialize the supplied list with
|
||||||
|
an established Ansible/Jinja data filter; do not manually construct YAML or
|
||||||
|
alter `notarius_pipelines`.
|
||||||
|
4. Keep every other optional field governed by its current null-omission
|
||||||
|
behavior. The role manages only its root configuration and must not create
|
||||||
|
any caller-selected imported fragment.
|
||||||
|
5. Update the README's version, configuration version, variable list, and
|
||||||
|
configuration discussion. Explain that ConfigKit imports are caller-owned
|
||||||
|
native composition inputs and that relative imports resolve from the
|
||||||
|
managed root configuration directory. Do not mention the D&D suite's fixed
|
||||||
|
fragment or cache policy as a standalone default.
|
||||||
|
6. Migrate the integration fixture from configuration version 4 shorthand to
|
||||||
|
canonical version 5 module-binding objects. Use a test-owned imported
|
||||||
|
fragment to exercise `notarius_configkit_imports`; fixture creation is test
|
||||||
|
setup and must not become a production role task.
|
||||||
|
7. Exercise an explicitly selected `notarius_version: v0.7.0`, caller-side
|
||||||
|
composition of two small pipeline maps, an intentional falsey cache value,
|
||||||
|
a representative cache override, and the existing caller-supplied Go
|
||||||
|
executable/missing-binary recovery behavior. Use v0.7.0 for cases that need
|
||||||
|
a configuration-compatible executable.
|
||||||
|
8. Validate the representative imported pipeline with
|
||||||
|
`notarius config validate --pipeline <id>` and observe composition and the
|
||||||
|
cache override through `notarius config effective` or another native
|
||||||
|
inspection command. Remove direct managed-file assertions from
|
||||||
|
`tests/verify-config.yml`; delete that playbook if it has no remaining
|
||||||
|
behavioral purpose.
|
||||||
|
9. Retain an immediate identical repeat that reports `changed=0` and
|
||||||
|
`failed=0`. Do not assert that v0.7.0 remains the role default, test
|
||||||
|
ConfigKit itself, or add production validation and state inspection.
|
||||||
|
|
||||||
|
### Validation
|
||||||
|
|
||||||
|
Run from `ansible-role-notarius`:
|
||||||
|
|
||||||
|
```text
|
||||||
|
tests/integration
|
||||||
|
git diff --check
|
||||||
|
git status --short
|
||||||
|
```
|
||||||
|
|
||||||
|
Expected result: syntax and production-profile lint pass; the explicitly
|
||||||
|
selected v0.7.0 binary reports its selected version; native Notarius commands
|
||||||
|
validate and inspect the representative composed version 5 configuration;
|
||||||
|
missing-binary recovery still works with the caller's Go executable; all
|
||||||
|
immediate repeats report `changed=0` and `failed=0`; and only intended role,
|
||||||
|
test, and README files are modified.
|
||||||
|
|
||||||
|
### Completion Criteria
|
||||||
|
|
||||||
|
- Defaults, argument specification, template, README, and tests expose one
|
||||||
|
coherent generic ConfigKit import interface.
|
||||||
|
- The root document is version 5 and no D&D pipeline or caller-owned fragment
|
||||||
|
is embedded in the standalone role.
|
||||||
|
- Tests observe native application behavior and do not snapshot defaults or
|
||||||
|
re-test Ansible module guarantees.
|
||||||
|
- The repository is valid and the stage is committed.
|
||||||
|
|
||||||
|
### Commit
|
||||||
|
|
||||||
|
Commit intent: `Upgrade the Notarius role to version 0.7.0`
|
||||||
|
|
||||||
|
## Stage 2: Implement the Suite Notarius Integration
|
||||||
|
|
||||||
|
### Objective
|
||||||
|
|
||||||
|
Add the pipeline role's complete D&D Notarius configuration, Narratio wiring,
|
||||||
|
and shared cache convergence using the reviewed standalone-role interface.
|
||||||
|
|
||||||
|
### Required Policy Review
|
||||||
|
|
||||||
|
Before beginning this stage, read:
|
||||||
|
|
||||||
|
- `AGENTS.md`
|
||||||
|
- `docs/orientation.md`
|
||||||
|
- `docs/conventions.md`
|
||||||
|
- `docs/ansible.md`
|
||||||
|
- `docs/testing.md`
|
||||||
|
- `docs/roadmap/features/0010-dnd-notarius-extraction-integration.md`
|
||||||
|
- `docs/decisions/0001-minimal-module-driven-ansible.md`
|
||||||
|
- `docs/decisions/0002-shared-readable-pipeline-filesystem-policy.md`
|
||||||
|
- the committed Stage 1 changes in `ansible-role-notarius`
|
||||||
|
- `../notarius/docs/releases/v0.7.0.md`
|
||||||
|
- `../notarius/docs/config.md`
|
||||||
|
- `../notarius/docs/consumers/dnd-pipeline.md`
|
||||||
|
- `../notarius/examples/dnd-complete.config.yml`
|
||||||
|
- `../notarius/examples/pipelines/dnd-session.yml`
|
||||||
|
- `../narratio/docs/integrations/notarius.md`
|
||||||
|
- `../narratio/examples/pipeline.full.annotated.yml`
|
||||||
|
- `ansible-role-dnd-pipeline/defaults/main.yml`
|
||||||
|
- `ansible-role-dnd-pipeline/meta/argument_specs.yml`
|
||||||
|
- `ansible-role-dnd-pipeline/meta/main.yml`
|
||||||
|
- `ansible-role-dnd-pipeline/requirements.yml`
|
||||||
|
- `ansible-role-dnd-pipeline/tasks/main.yml`
|
||||||
|
- `ansible-role-dnd-pipeline/templates/testing.yml.j2`
|
||||||
|
- `ansible-role-dnd-pipeline/tests/integration`
|
||||||
|
|
||||||
|
### Preconditions
|
||||||
|
|
||||||
|
- Stage 1 is committed, validated, and clean.
|
||||||
|
- The Stage 1 commit is reachable from the canonical
|
||||||
|
`ansible-role-notarius` Git origin. Stop and report the hash if a fresh Git
|
||||||
|
or Galaxy fetch cannot resolve it.
|
||||||
|
- `ansible-role-dnd-pipeline` is clean at its stated starting commit or an
|
||||||
|
expected reviewed descendant.
|
||||||
|
- Its existing `tests/integration` entry point passes before modification.
|
||||||
|
|
||||||
|
### Owning Repository
|
||||||
|
|
||||||
|
`ansible-role-dnd-pipeline`
|
||||||
|
|
||||||
|
### Required Changes
|
||||||
|
|
||||||
|
1. Set `dnd_pipeline_notarius_version: v0.7.0` and pin the
|
||||||
|
`rakestraw.notarius` entry in `requirements.yml` to the exact Stage 1
|
||||||
|
commit. Retain the canonical Git URL and every unrelated dependency pin.
|
||||||
|
2. Add these required, defaulted suite variables and matching argument
|
||||||
|
specifications:
|
||||||
|
`dnd_pipeline_notarius_pipelines` as a complete native map,
|
||||||
|
`dnd_pipeline_notarius_cache_root` as a path,
|
||||||
|
`dnd_pipeline_notarius_cache_chunk_plans_mode` as a string,
|
||||||
|
`dnd_pipeline_notarius_cache_checkpoints_enabled` as a boolean,
|
||||||
|
`dnd_pipeline_narratio_notarius_pipeline_id` as a string,
|
||||||
|
`dnd_pipeline_narratio_notarius_references` as a complete native map, and
|
||||||
|
`dnd_pipeline_narratio_notarius_outputs` as a complete native map.
|
||||||
|
3. Default the pipeline map to one `dnd-session` entry adapted from the
|
||||||
|
Notarius v0.7.0 maintained fragment. Preserve its embedded
|
||||||
|
`dnd-extraction` profile ID, Seriatim input, `dnd/scenes` chunker with two
|
||||||
|
retries, three ordered steps, ten lanes, canonical object bindings,
|
||||||
|
generated artifact handoffs, JSON chunk map, and nine-lane evidence-context
|
||||||
|
selection with a three-unit window.
|
||||||
|
4. Remove every external `path` reference from the adapted pipeline: omit the
|
||||||
|
example's `party`, `glossary`, and binding-local `spell_catalog` paths.
|
||||||
|
Retain only generated `artifact` references between steps. Do not install a
|
||||||
|
PromptKit profile file or set global output/debug roots.
|
||||||
|
5. Default the selected pipeline ID to `dnd-session`. Default the Narratio
|
||||||
|
reference map to `party: narratio.input.party`,
|
||||||
|
`players: narratio.input.players`, and
|
||||||
|
`glossary: narratio.input.glossary`; do not add `spell_catalog` until a
|
||||||
|
deployed campaign supplies that optional input.
|
||||||
|
6. Default the Narratio output map to all ten exact lane, media type, schema
|
||||||
|
ID, schema version, and module-key descriptors recorded in the feature
|
||||||
|
roadmap and Narratio's maintained example. Keep both maps replaceable as
|
||||||
|
whole native values through normal inventory precedence.
|
||||||
|
7. Default the cache root to `/var/cache/notarius`, chunk-plan mode to `auto`,
|
||||||
|
and checkpoint recording to `true`. Derive
|
||||||
|
`/var/cache/notarius/chunk-plans` and
|
||||||
|
`/var/cache/notarius/checkpoints` in dependency wiring rather than adding
|
||||||
|
independent suite variables.
|
||||||
|
8. Pass the fixed relative import `pipelines/dnd-session.yml`, selected cache
|
||||||
|
settings, and derived child paths to `rakestraw.notarius`. Leave its
|
||||||
|
root-level `notarius_pipelines` unset so the standalone role continues to
|
||||||
|
own only the root document.
|
||||||
|
9. Pass `narratio_notarius_enabled: true`, the selected pipeline ID,
|
||||||
|
`/usr/local/etc/notarius` working directory, and the reference/output maps
|
||||||
|
to `rakestraw.narratio`. Retain the established binary and configuration
|
||||||
|
paths, leave its native three-hour timeout in control, and do not change the
|
||||||
|
Narratio role or testing-overlay template.
|
||||||
|
10. Create `/var/cache/notarius` directly as the selected runtime user and
|
||||||
|
group with mode `2775` before ACL convergence. Add that root to both
|
||||||
|
existing access and default ACL loops; do not create its child stores or
|
||||||
|
add a second ACL implementation.
|
||||||
|
11. Create `/usr/local/etc/notarius/pipelines` directly with the suite
|
||||||
|
configuration owner, group, and directory mode. Add one template that
|
||||||
|
serializes only `pipelines: dnd_pipeline_notarius_pipelines` to
|
||||||
|
`dnd-session.yml` with the suite file metadata. Do not duplicate the
|
||||||
|
standalone root template or manually render every nested map field.
|
||||||
|
12. Keep production convergence limited to the existing role dependencies,
|
||||||
|
one cache-root file operation, the existing ACL loops, one configuration
|
||||||
|
directory operation, and one template operation. Do not add commands,
|
||||||
|
`stat`, handlers, validation tasks, state bookkeeping, secrets, extraction,
|
||||||
|
or retention behavior.
|
||||||
|
|
||||||
|
### Validation
|
||||||
|
|
||||||
|
Run from `ansible-role-dnd-pipeline`:
|
||||||
|
|
||||||
|
```text
|
||||||
|
tests/integration
|
||||||
|
git diff --check
|
||||||
|
git status --short
|
||||||
|
```
|
||||||
|
|
||||||
|
Expected result: isolated dependency installation resolves the exact Stage 1
|
||||||
|
commit; syntax and production-profile lint pass; the five applications install
|
||||||
|
successfully; Notarius natively validates the imported `dnd-session` pipeline;
|
||||||
|
Narratio validates the assembled base and testing configurations; the baseline
|
||||||
|
repeat reports `changed=0` and `failed=0`; and only intended pipeline-role
|
||||||
|
files are modified.
|
||||||
|
|
||||||
|
### Completion Criteria
|
||||||
|
|
||||||
|
- The suite installs Notarius v0.7.0 through the exact reviewed role revision.
|
||||||
|
- The complete path-free D&D pipeline is owned by one suite fragment and is
|
||||||
|
imported through the standalone role's public interface.
|
||||||
|
- Narratio enables and selects the pipeline with the three prepared campaign
|
||||||
|
references and all ten exact accepted outputs.
|
||||||
|
- The FHS cache root and inherited access policy use direct module-owned
|
||||||
|
convergence; child stores remain application-owned.
|
||||||
|
- The unchanged testing overlay inherits Notarius enablement and pipeline
|
||||||
|
selection.
|
||||||
|
- The repository is valid and the stage is committed.
|
||||||
|
|
||||||
|
### Commit
|
||||||
|
|
||||||
|
Commit intent: `Integrate Notarius extraction into the D&D pipeline`
|
||||||
|
|
||||||
|
## Stage 3: Document and Exercise the Integration Contract
|
||||||
|
|
||||||
|
### Objective
|
||||||
|
|
||||||
|
Document the suite's Notarius policy and add the smallest behavioral coverage
|
||||||
|
that proves native composition, Narratio coordination, shared access,
|
||||||
|
customization, and immediate idempotence.
|
||||||
|
|
||||||
|
### Required Policy Review
|
||||||
|
|
||||||
|
Before beginning this stage, read:
|
||||||
|
|
||||||
|
- `AGENTS.md`
|
||||||
|
- `docs/orientation.md`
|
||||||
|
- `docs/conventions.md`
|
||||||
|
- `docs/ansible.md`
|
||||||
|
- `docs/testing.md`
|
||||||
|
- `docs/roadmap/features/0010-dnd-notarius-extraction-integration.md`
|
||||||
|
- `docs/decisions/0002-shared-readable-pipeline-filesystem-policy.md`
|
||||||
|
- the committed Stage 1 and Stage 2 changes
|
||||||
|
- `../notarius/docs/cli.md`
|
||||||
|
- `../notarius/docs/consumers/dnd-pipeline.md`
|
||||||
|
- `../narratio/docs/cli.md`
|
||||||
|
- `../narratio/docs/integrations/notarius.md`
|
||||||
|
- `ansible-role-dnd-pipeline/README.md`
|
||||||
|
- `ansible-role-dnd-pipeline/tests/integration`
|
||||||
|
- `ansible-role-dnd-pipeline/tests/converge.yml`
|
||||||
|
|
||||||
|
### Preconditions
|
||||||
|
|
||||||
|
- Stages 1 and 2 are committed, validated, and clean.
|
||||||
|
- The pipeline's isolated dependency installation resolves the Stage 1 commit.
|
||||||
|
- The deployed baseline can be restored through the existing integration
|
||||||
|
driver's cleanup path.
|
||||||
|
|
||||||
|
### Owning Repository
|
||||||
|
|
||||||
|
`ansible-role-dnd-pipeline`
|
||||||
|
|
||||||
|
### Required Changes
|
||||||
|
|
||||||
|
1. Update the README's compatible-version table to Notarius v0.7.0 and replace
|
||||||
|
the statement that Notarius remains disabled with the implemented
|
||||||
|
extraction behavior.
|
||||||
|
2. Document the seven new suite variables, the fixed root import and fragment
|
||||||
|
path, caller-side map replacement/composition with Jinja `combine`, the
|
||||||
|
prepared-reference boundary, all ten accepted output sources, and the
|
||||||
|
optional future `spell_catalog` extension. Distinguish native maps from
|
||||||
|
field-specific scalar controls.
|
||||||
|
3. Document `/var/cache/notarius`, `auto` chunk plans, recorded-but-not-resumed
|
||||||
|
checkpoints, derived child paths, `2775` setgid/default-ACL policy, and use
|
||||||
|
by either the service account or an existing member of the runtime group.
|
||||||
|
Retain the world-readable non-secret policy and the deferred restricted
|
||||||
|
credential boundary.
|
||||||
|
4. Document that base and `testing` configurations use the same
|
||||||
|
`dnd-extraction` profile and pipeline. Do not claim that testing avoids
|
||||||
|
Notarius model calls during a real run; integration tests perform only
|
||||||
|
offline configuration inspection.
|
||||||
|
5. Extend the baseline integration path to run
|
||||||
|
`notarius config validate --pipeline dnd-session` and inspect
|
||||||
|
`notarius config effective`. Observe one generated artifact handoff and one
|
||||||
|
cache setting from the native effective output without reading the managed
|
||||||
|
YAML file or enumerating every pipeline option.
|
||||||
|
6. Use Narratio's native `config validate` for both `centaurs` and `dilfs` in
|
||||||
|
the base configuration and at least one campaign under `testing`. Use
|
||||||
|
`config show` or another native inspection surface to observe Notarius
|
||||||
|
enablement, the selected pipeline, one prepared reference, and one output
|
||||||
|
descriptor. Keep the existing check that the testing overlay changes only
|
||||||
|
its intended Scriptorium profile selections.
|
||||||
|
7. As the existing uniquely named operator fixture in the runtime group, run
|
||||||
|
one native Notarius validation or inspection command against the same root
|
||||||
|
and imported fragment used by the service account. Add one actual
|
||||||
|
service/operator read-write exchange beneath `/var/cache/notarius`, or move
|
||||||
|
the existing representative exchange there, to exercise the new shared
|
||||||
|
root without parsing ACLs or mode bits. Do not add an exhaustive root or
|
||||||
|
identity matrix.
|
||||||
|
8. Add one alternate convergence case that supplies two small version 5
|
||||||
|
pipeline maps and composes them into
|
||||||
|
`dnd_pipeline_notarius_pipelines` with Jinja `combine`, selects a matching
|
||||||
|
alternate pipeline ID, and overrides one cache choice. Observe the two
|
||||||
|
pipeline IDs and effective cache choice through native Notarius inspection,
|
||||||
|
then require one immediate identical repeat with `changed=0` and
|
||||||
|
`failed=0`.
|
||||||
|
9. Retain the baseline clean repeat, immutable local asset inputs, isolated
|
||||||
|
dependency installation, cleanup safety, and existing representative
|
||||||
|
application checks. Restore the default deployment during cleanup.
|
||||||
|
10. Do not run extraction, contact an LLM or WhisperX endpoint, snapshot a
|
||||||
|
complete rendered document, assert every nested pipeline field, test
|
||||||
|
filesystem metadata, or reproduce Notarius, Narratio, ConfigKit, PromptKit,
|
||||||
|
or Ansible behavior.
|
||||||
|
|
||||||
|
### Validation
|
||||||
|
|
||||||
|
Run from `ansible-role-dnd-pipeline`:
|
||||||
|
|
||||||
|
```text
|
||||||
|
tests/integration
|
||||||
|
git diff --check
|
||||||
|
git status --short
|
||||||
|
```
|
||||||
|
|
||||||
|
Expected result: isolated role and collection installation, syntax checking,
|
||||||
|
and production-profile lint pass; native Notarius validation and effective
|
||||||
|
inspection prove composition and representative policy; Narratio validates
|
||||||
|
both campaigns and the testing profile; a supported group member can inspect
|
||||||
|
the same Notarius configuration and exchange representative cache content;
|
||||||
|
the combined-map/cache override is observable; all immediate repeats report
|
||||||
|
`changed=0` and `failed=0`; and documentation matches the public interface.
|
||||||
|
|
||||||
|
### Completion Criteria
|
||||||
|
|
||||||
|
- Documentation describes the implemented suite policy, public customization
|
||||||
|
boundary, shared cache, testing behavior, and deliberate exclusions.
|
||||||
|
- Tests protect role-owned integration behavior without freezing complete
|
||||||
|
defaults or testing module internals.
|
||||||
|
- Both deployed campaigns validate, and the base and testing configurations
|
||||||
|
retain the enabled Notarius stage.
|
||||||
|
- Baseline and representative override applications converge cleanly on their
|
||||||
|
immediate repeats.
|
||||||
|
- The repository is valid and the stage is committed.
|
||||||
|
|
||||||
|
### Commit
|
||||||
|
|
||||||
|
Commit intent: `Document and test the D&D Notarius integration`
|
||||||
|
|
||||||
|
## Stage 4: Record the Implementation for Review
|
||||||
|
|
||||||
|
### Objective
|
||||||
|
|
||||||
|
Record the completed implementation and validation evidence in the workspace
|
||||||
|
without declaring the feature complete before independent review.
|
||||||
|
|
||||||
|
### Required Policy Review
|
||||||
|
|
||||||
|
Before beginning this stage, read:
|
||||||
|
|
||||||
|
- `AGENTS.md`
|
||||||
|
- `docs/orientation.md`
|
||||||
|
- `docs/conventions.md`
|
||||||
|
- `docs/planning.md`
|
||||||
|
- `docs/roadmap/features/0010-dnd-notarius-extraction-integration.md`
|
||||||
|
- `docs/roadmap/implementation.md`
|
||||||
|
- `docs/status.md`
|
||||||
|
|
||||||
|
### Preconditions
|
||||||
|
|
||||||
|
- Stages 1 through 3 are committed and their owning repositories are clean.
|
||||||
|
- Both complete integration entry points pass at the committed revisions.
|
||||||
|
- The workspace control repository is clean at the planning commit.
|
||||||
|
|
||||||
|
### Owning Repository
|
||||||
|
|
||||||
|
`ansible-workspace-dnd`
|
||||||
|
|
||||||
|
### Required Changes
|
||||||
|
|
||||||
|
1. Update this plan's Progress Notes with the three implementation commit
|
||||||
|
hashes and concise validation results.
|
||||||
|
2. Update `docs/status.md` so Feature 0010 is `in_progress`, its evidence names
|
||||||
|
the implementation commits, and the current focus is independent review of
|
||||||
|
the completed implementation.
|
||||||
|
3. Keep the feature roadmap `ready`; do not mark Feature 0010 `done`, clean the
|
||||||
|
durable roadmap, or create `docs/roadmap/remediation.md`. Those actions
|
||||||
|
belong to the independent review and closeout workflow.
|
||||||
|
4. Do not change implementation repositories or unrelated workspace policy in
|
||||||
|
this stage.
|
||||||
|
|
||||||
|
### Validation
|
||||||
|
|
||||||
|
Run from the workspace root:
|
||||||
|
|
||||||
|
```text
|
||||||
|
git diff --check
|
||||||
|
./scripts/status
|
||||||
|
git status --short
|
||||||
|
```
|
||||||
|
|
||||||
|
Expected result: the status report identifies only the intended workspace
|
||||||
|
tracking edits before commit; both implementation repositories are clean; and
|
||||||
|
the dashboard and progress notes point to the exact completed stage commits.
|
||||||
|
|
||||||
|
### Completion Criteria
|
||||||
|
|
||||||
|
- The implementation and validation evidence is traceable across repositories.
|
||||||
|
- Feature 0010 remains awaiting independent review rather than being marked
|
||||||
|
complete.
|
||||||
|
- The workspace control repository is valid and the stage is committed.
|
||||||
|
|
||||||
|
### Commit
|
||||||
|
|
||||||
|
Commit intent: `Record the D&D Notarius integration implementation`
|
||||||
|
|
||||||
|
## Final Validation and Handoff
|
||||||
|
|
||||||
|
After Stage 4, rerun both owning repositories' complete integration entry
|
||||||
|
points:
|
||||||
|
|
||||||
|
```text
|
||||||
|
cd ansible-role-notarius && tests/integration
|
||||||
|
cd ../ansible-role-dnd-pipeline && tests/integration
|
||||||
|
```
|
||||||
|
|
||||||
|
Then, from the workspace root, run:
|
||||||
|
|
||||||
|
```text
|
||||||
|
git diff --check
|
||||||
|
./scripts/status
|
||||||
|
```
|
||||||
|
|
||||||
|
The final handoff must:
|
||||||
|
|
||||||
|
- identify the Stage 1 through Stage 4 commit hashes and confirm each changed
|
||||||
|
repository has a clean working tree;
|
||||||
|
- confirm syntax and production-profile lint pass in both changed roles;
|
||||||
|
- confirm the standalone role installs an explicitly selected Notarius v0.7.0,
|
||||||
|
validates and inspects composed version 5 configuration natively, and
|
||||||
|
immediately converges cleanly;
|
||||||
|
- confirm the pipeline installs the exact immutable Notarius-role commit,
|
||||||
|
validates the complete D&D pipeline and both Narratio campaign resolutions,
|
||||||
|
preserves Notarius under `testing`, supports the representative shared-user
|
||||||
|
path, and immediately converges cleanly;
|
||||||
|
- confirm no upstream application, asset, collection, unrelated standalone
|
||||||
|
role, secret, external service, or real human account was modified;
|
||||||
|
- summarize any deviation, blocker, or deferred work, including any pause
|
||||||
|
required to publish the Stage 1 dependency commit;
|
||||||
|
- report any production complexity beyond the planned public variables,
|
||||||
|
dependency wiring, one imported fragment, one cache-root task, and extension
|
||||||
|
of the existing ACL loops, together with the acceptance criterion that
|
||||||
|
required it; and
|
||||||
|
- leave Feature 0010 `in_progress` for independent review rather than marking
|
||||||
|
it `done`.
|
||||||
|
|
||||||
|
## Progress Notes
|
||||||
|
|
||||||
|
No implementation stages have begun. Record only concise stage commit hashes,
|
||||||
|
validation results, and blockers here during execution; preserve detailed
|
||||||
|
evidence in the implementation commits and final handoff.
|
||||||
|
|||||||
@@ -14,9 +14,11 @@ Build independently usable Ansible roles for the five Narratio applications
|
|||||||
and compose them through a suite-level role developed in its own repository.
|
and compose them through a suite-level role developed in its own repository.
|
||||||
The `rakestraw.dnd` collection exposes that role as `rakestraw.dnd.pipeline`.
|
The `rakestraw.dnd` collection exposes that role as `rakestraw.dnd.pipeline`.
|
||||||
The suite-level role installs and configures the complete D&D transcript
|
The suite-level role installs and configures the complete D&D transcript
|
||||||
processing pipeline on a single supported host. Human operators invoke
|
processing pipeline on a single supported host. Operators or unattended
|
||||||
Narratio commands directly to process D&D session recordings and produce
|
automation invoke Narratio commands either under the dedicated `narratio`
|
||||||
transcripts and related artifacts.
|
runtime identity or under a human account that belongs to the `narratio`
|
||||||
|
group, processing D&D session recordings into transcripts and related
|
||||||
|
artifacts.
|
||||||
|
|
||||||
## Locked Decisions
|
## Locked Decisions
|
||||||
|
|
||||||
@@ -186,38 +188,78 @@ application-role releases in one source repository.
|
|||||||
|
|
||||||
- The pipeline role installs Narratio's PromptKit-compatible prompt library
|
- The pipeline role installs Narratio's PromptKit-compatible prompt library
|
||||||
from the `narratio-prompts` Git repository. The Scriptorium role owns its
|
from the `narratio-prompts` Git repository. The Scriptorium role owns its
|
||||||
native prompt, profile, and schema directory configuration, while the
|
native prompt and schema directory configuration, while the pipeline role
|
||||||
pipeline role owns populating those locations with suite integration
|
owns populating those locations with suite integration content.
|
||||||
content.
|
|
||||||
- The upstream repository is
|
- The upstream repository is
|
||||||
`https://gitea.maximumdirect.net/eric/narratio-prompts`.
|
`https://gitea.maximumdirect.net/eric/narratio-prompts.git`.
|
||||||
- For the MVP, the pipeline role tracks and pulls the latest upstream commit.
|
- The repository is checked out at
|
||||||
|
`/usr/local/share/narratio/prompt-library` by default. Scriptorium's prompt
|
||||||
|
and schema directories are the checkout's `prompts/` and `schemas/`
|
||||||
|
subdirectories.
|
||||||
|
- The repository does not currently contain execution profiles. The pipeline
|
||||||
|
role does not set Scriptorium's profile directory until a later suite-policy
|
||||||
|
feature selects and deploys profiles.
|
||||||
|
- For the MVP, the pipeline role tracks and pulls the repository's `main`
|
||||||
|
branch. The origin, revision, and checkout root are configurable, and a
|
||||||
|
caller may select an immutable commit when required.
|
||||||
- Pinning the prompt library to a version or release is deferred until the
|
- Pinning the prompt library to a version or release is deferred until the
|
||||||
upstream repository provides versioned releases.
|
upstream repository provides versioned releases.
|
||||||
|
|
||||||
|
### Campaign registry content
|
||||||
|
|
||||||
|
- The pipeline role checks out the `campaigns` Git repository directly into
|
||||||
|
Narratio's campaign registry root. The upstream repository is
|
||||||
|
`https://gitea.maximumdirect.net/eric/campaigns.git`.
|
||||||
|
- The default campaign root remains
|
||||||
|
`/usr/local/share/narratio/campaigns`, and the pipeline role passes that same
|
||||||
|
value to the Narratio application role.
|
||||||
|
- For the MVP, the pipeline role tracks and pulls the repository's `main`
|
||||||
|
branch. The origin, revision, and campaign root are configurable, and a
|
||||||
|
caller may select an immutable commit when required.
|
||||||
|
- Both asset checkouts are root-managed and remotely authoritative. Operators
|
||||||
|
may read the content but do not edit it on the managed host. Ordinary Git
|
||||||
|
module convergence owns tracked-content updates; the role does not maintain
|
||||||
|
separate revision state or purge untracked files.
|
||||||
|
|
||||||
### Accounts, ownership, and operator access
|
### Accounts, ownership, and operator access
|
||||||
|
|
||||||
- The standalone Narratio role creates a dedicated system `narratio` user and
|
- The standalone Narratio role creates a dedicated system `narratio` user and
|
||||||
`narratio` group. The account uses `/var/lib/narratio` as its default home
|
`narratio` group. The account uses `/var/lib/narratio` as its default home
|
||||||
and has a non-login shell.
|
and has a non-login shell.
|
||||||
- The `narratio` account owns Narratio's writable runtime directories.
|
- The `narratio` account owns the suite's application configuration and
|
||||||
|
writable runtime directories; `narratio` is also the shared operator group.
|
||||||
- Application source trees and installed binaries are owned by `root` and are
|
- Application source trees and installed binaries are owned by `root` and are
|
||||||
not writable by operators or the runtime account.
|
not writable by operators or the runtime account.
|
||||||
- Ordinary human users run `narratio run` and other Narratio commands directly.
|
- The supported operational model runs `narratio run` and other processing
|
||||||
- Those operators receive the required access by membership in the `narratio`
|
commands either as the dedicated `narratio` account or as a human account
|
||||||
group.
|
that is already a member of the `narratio` group. The suite does not yet
|
||||||
- Narratio's configuration directory is owned by `root:narratio` with mode
|
select those human accounts or manage their membership.
|
||||||
`0750`, and its pipeline file is owned by `root:narratio` with mode `0640`.
|
- Application configuration directories and files are owned by
|
||||||
Configuration remains under Ansible control rather than being routinely
|
`narratio:narratio`, use modes `0755` and `0644`, respectively, and are
|
||||||
edited by operators on the host.
|
world-readable. Configuration remains under Ansible control rather than
|
||||||
- The Narratio workspace, spool, and cache roots are owned by
|
being routinely edited by operators on the host.
|
||||||
`narratio:narratio` with mode `2775`, preserving the group on created content
|
- Workspace, spool, and cache roots are owned by `narratio:narratio` with mode
|
||||||
and granting the shared write access needed for direct operator invocations.
|
`2775`. Setgid and managed default ACLs preserve shared group write access
|
||||||
|
and world read/traverse access for newly created directories and files even
|
||||||
|
when invocation identities have different ordinary umasks.
|
||||||
|
- The pipeline role installs the host `acl` package and uses the declared,
|
||||||
|
pinned `ansible.posix` collection to manage access and default ACL entries on
|
||||||
|
those shared writable roots.
|
||||||
- The campaign registry root is owned by `root:narratio` with mode `0755`.
|
- The campaign registry root is owned by `root:narratio` with mode `0755`.
|
||||||
Its content is readable by operators but is populated by the suite role and
|
Its content is world-readable but is populated by the suite role and is not
|
||||||
is not edited directly on the managed host.
|
edited directly on the managed host.
|
||||||
- The standalone role does not select human operators. The suite role owns the
|
- Configuration, transcripts, caches, generated artifacts, logs, campaign
|
||||||
operator list and adds those accounts to the `narratio` group.
|
data, and prompt assets are deliberately non-secret D&D content and remain
|
||||||
|
world-readable. API keys and similar credentials are the sole confidential
|
||||||
|
category.
|
||||||
|
- Debug output is not enabled by the MVP. Any later debug feature must either
|
||||||
|
produce world-readable non-secret D&D diagnostics or identify and justify a
|
||||||
|
narrower application contract before deployment.
|
||||||
|
- Credential material will live beneath a restricted `secrets/` subdirectory
|
||||||
|
owned by `narratio:narratio`, with directories mode `0750` and files mode
|
||||||
|
`0640`. Ordinary configuration contains only credential reference names.
|
||||||
|
- [Decision 0002](../decisions/0002-shared-readable-pipeline-filesystem-policy.md)
|
||||||
|
records the complete rationale and boundary for this policy.
|
||||||
|
|
||||||
### Narratio configuration
|
### Narratio configuration
|
||||||
|
|
||||||
@@ -239,6 +281,44 @@ application-role releases in one source repository.
|
|||||||
them owns their deployment.
|
them owns their deployment.
|
||||||
- Credential fields contain environment-variable names, never secret values.
|
- Credential fields contain environment-variable names, never secret values.
|
||||||
Secret delivery remains suite-level policy.
|
Secret delivery remains suite-level policy.
|
||||||
|
- The standalone Narratio role owns the root pipeline document. The pipeline
|
||||||
|
role owns its D&D-specific imported processing, artifact, and artifact-family
|
||||||
|
fragments under `/usr/local/etc/narratio` and selects them through an
|
||||||
|
explicit ordered `configkit.imports` list.
|
||||||
|
- Each ordinary artifact and artifact family is defined in a separate managed
|
||||||
|
file. Explicit imports are preferred to directory globs so removed or stale
|
||||||
|
files do not remain active implicitly.
|
||||||
|
- The pipeline role manages a native `profiles/testing.yml` overlay for
|
||||||
|
inexpensive development and asset iteration. Production retains its
|
||||||
|
frontier-oriented model/profile policy; callers select the testing overlay
|
||||||
|
explicitly with Narratio's `--profile testing` interface.
|
||||||
|
- Base fragments and the testing overlay contain configuration and
|
||||||
|
environment-variable or secret-reference names only. They never contain raw
|
||||||
|
credentials.
|
||||||
|
- The D&D suite deliberately supplies Audita's complete reviewed processing
|
||||||
|
policy, including the current module sequence and tuning, `audita-v1`
|
||||||
|
output, the `https://inference.ai.rakestrawhome.com/v1` endpoint, and
|
||||||
|
`google/gemma-4-31b-it` for proposal and validation. Those values remain
|
||||||
|
inventory-overrideable and are suite policy rather than copies of upstream
|
||||||
|
defaults.
|
||||||
|
- The Narratio `testing` profile selects `gemini-flash-latest` for its
|
||||||
|
Scriptorium artifacts and families. Audita initially uses the same endpoint
|
||||||
|
and models in production and testing; identical values are inherited rather
|
||||||
|
than duplicated in the overlay.
|
||||||
|
- The D&D suite enables Notarius's `auto` chunk-plan cache and checkpoint
|
||||||
|
cache beneath `/var/cache/notarius`. That FHS cache root is owned by the
|
||||||
|
`narratio` account and group with mode `2775` and the suite's shared default
|
||||||
|
ACL policy. Notarius v0.7.0 leaves cache-entry access to that deployment
|
||||||
|
policy. Chunk plans are reused automatically; checkpoints are recorded but
|
||||||
|
Narratio does not yet request their reuse.
|
||||||
|
- The standalone Notarius role exposes Notarius v0.7.0's native ConfigKit
|
||||||
|
import list while remaining independent of D&D content. The pipeline role
|
||||||
|
owns an imported `pipelines/dnd-session.yml` fragment containing its
|
||||||
|
opinionated, inventory-composable D&D pipeline map; the standalone role
|
||||||
|
continues to own only the version 5 root document.
|
||||||
|
- The Narratio `testing` profile keeps the Notarius stage enabled and inherits
|
||||||
|
the same D&D pipeline and extraction profile as production until a distinct
|
||||||
|
testing extraction policy is selected.
|
||||||
|
|
||||||
### Execution model
|
### Execution model
|
||||||
|
|
||||||
@@ -255,19 +335,26 @@ later design decision changes them:
|
|||||||
- `/usr/local/etc/narratio` for Narratio configuration
|
- `/usr/local/etc/narratio` for Narratio configuration
|
||||||
- `/usr/local/etc/audita/config.yml` for Audita configuration
|
- `/usr/local/etc/audita/config.yml` for Audita configuration
|
||||||
- `/usr/local/etc/notarius/config.yml` for Notarius configuration
|
- `/usr/local/etc/notarius/config.yml` for Notarius configuration
|
||||||
|
- `/usr/local/etc/notarius/pipelines` for suite-owned imported Notarius
|
||||||
|
pipeline definitions
|
||||||
- `/usr/local/etc/scriptorium/config.yml` for Scriptorium configuration
|
- `/usr/local/etc/scriptorium/config.yml` for Scriptorium configuration
|
||||||
|
- `/usr/local/etc/narratio/secrets` for future restricted credential material
|
||||||
- `/usr/local/share/narratio/campaigns` for version-controlled campaign data
|
- `/usr/local/share/narratio/campaigns` for version-controlled campaign data
|
||||||
|
- `/usr/local/share/narratio/prompt-library` for version-controlled prompts
|
||||||
|
and schemas
|
||||||
- `/usr/local/src/<app>` for root-owned application source checkouts
|
- `/usr/local/src/<app>` for root-owned application source checkouts
|
||||||
- `/usr/local/bin/<app>` for root-owned application binaries
|
- `/usr/local/bin/<app>` for root-owned application binaries
|
||||||
- `/var/lib/narratio` for durable workspace and session state
|
- `/var/lib/narratio` for durable workspace and session state
|
||||||
- `/var/spool/narratio` for spool data
|
- `/var/spool/narratio` for spool data
|
||||||
- `/var/cache/narratio` for cached data
|
- `/var/cache/narratio` for cached data
|
||||||
|
- `/var/cache/notarius` for suite-provisioned Notarius chunk-plan and
|
||||||
|
checkpoint caches
|
||||||
|
|
||||||
The Narratio role creates and configures the campaign root; the pipeline role
|
The Narratio role creates and configures the campaign root; the pipeline role
|
||||||
populates it from the selected campaign source. `/usr/local/share` assumes Git
|
populates it from the selected campaign source. `/usr/local/share` assumes Git
|
||||||
is authoritative and operators do not edit campaign content directly on the
|
is authoritative and operators do not edit campaign content directly on the
|
||||||
managed host. The exact prompt-library checkout and installed-content paths
|
managed host. The prompt-library checkout retains its upstream `prompts/` and
|
||||||
remain to be designed.
|
`schemas/` layout at the fixed root above.
|
||||||
|
|
||||||
## Deferred Beyond the MVP
|
## Deferred Beyond the MVP
|
||||||
|
|
||||||
@@ -276,6 +363,7 @@ remain to be designed.
|
|||||||
- Installation from prebuilt application release artifacts
|
- Installation from prebuilt application release artifacts
|
||||||
- Deploying or managing WhisperX
|
- Deploying or managing WhisperX
|
||||||
- Versioned Narratio prompt-library releases and pinning
|
- Versioned Narratio prompt-library releases and pinning
|
||||||
|
- Versioned campaign-content releases and default release pinning
|
||||||
- A role-managed scheduler or persistent Narratio service
|
- A role-managed scheduler or persistent Narratio service
|
||||||
- Cryptographic artifact verification, supply-chain hardening, and protection
|
- Cryptographic artifact verification, supply-chain hardening, and protection
|
||||||
against adversarial source or dependency infrastructure
|
against adversarial source or dependency infrastructure
|
||||||
@@ -290,10 +378,8 @@ The following areas require investigation and decisions before implementation:
|
|||||||
|
|
||||||
- The mechanism used to incorporate the independently developed pipeline role
|
- The mechanism used to incorporate the independently developed pipeline role
|
||||||
into collection releases
|
into collection releases
|
||||||
- The prompt-library destination and its integration with Scriptorium
|
|
||||||
- The campaign repository's checkout revision and deployment/update policy
|
|
||||||
- Secret injection and storage
|
- Secret injection and storage
|
||||||
- Suite-level operator-selection variables
|
- Optional suite-level operator-selection and group-membership management
|
||||||
- Upgrade, downgrade, and removal behavior
|
- Upgrade, downgrade, and removal behavior
|
||||||
- Collection bootstrap and end-to-end validation details beyond the locked
|
- Collection bootstrap and end-to-end validation details beyond the locked
|
||||||
dependency and testing policies above
|
dependency and testing policies above
|
||||||
|
|||||||
@@ -1,119 +1,90 @@
|
|||||||
# Feature 0006 Remediation Review
|
# Feature 0009 Remediation Review
|
||||||
|
|
||||||
Status: resolved
|
Status: resolved
|
||||||
|
|
||||||
Reviewed implementation commits:
|
Reviewed implementation commits:
|
||||||
|
|
||||||
- `b515968 Compose the D&D pipeline roles`
|
- `66ebea9 Make Audita configuration ownership configurable`
|
||||||
- `61869d1 Add focused pipeline composition coverage`
|
- `e9ae2dc Make Notarius configuration ownership configurable`
|
||||||
|
- `8b4c86e Make Scriptorium configuration ownership configurable`
|
||||||
|
- `eeb1105 Make Narratio configuration ownership configurable`
|
||||||
|
- `901ae35 Apply shared configuration ownership to the D&D pipeline`
|
||||||
|
- `dddc5ee Manage shared pipeline access with ACLs`
|
||||||
|
- `f53da82 Test shared pipeline access across users`
|
||||||
|
- `608d5be Document the shared pipeline execution model`
|
||||||
|
|
||||||
Remediation commit:
|
## Review Summary
|
||||||
|
|
||||||
- `4ea4358 Clean up pipeline composition review findings`
|
The production architecture and behavioral coverage implement Feature 0009 as
|
||||||
|
planned. The four standalone roles expose generic configuration ownership and
|
||||||
|
mode controls, and the pipeline selects its opinionated service-owned,
|
||||||
|
world-readable policy through those interfaces. Narratio establishes the
|
||||||
|
runtime identity first. The pipeline then installs ACL support and directly
|
||||||
|
converges access and default ACLs on the three existing shared roots. Focused
|
||||||
|
integration coverage exercises actual cross-identity configuration access and
|
||||||
|
bidirectional writes under a restrictive umask while preserving immediate clean
|
||||||
|
convergence.
|
||||||
|
|
||||||
The production architecture matches Feature 0006: the role contains only its
|
No production code or test-suite remediation is required. One small consumer
|
||||||
public defaults and argument specification, five pinned role dependencies,
|
documentation inconsistency remains.
|
||||||
the approved variable forwarding, and fixed Narratio path wiring. Its task
|
|
||||||
file is empty, and it does not duplicate downstream tasks, templates, state
|
|
||||||
inspection, or validation. The complete integration entry point passes.
|
|
||||||
|
|
||||||
The review identified two repository-quality findings.
|
## Finding 1: Operator Support Is Documented Inconsistently
|
||||||
|
|
||||||
## Finding 1: Remove the Misleading Placeholder README Sentence
|
|
||||||
|
|
||||||
Severity: low
|
Severity: low
|
||||||
|
|
||||||
`ansible-role-dnd-pipeline/README.md` still ends with the original placeholder
|
`ansible-role-dnd-pipeline/README.md:201-217` first lists "operator access" as
|
||||||
sentence claiming that the role installs the full production pipeline “plus
|
deferred, then correctly states that invocation by an existing member of the
|
||||||
supporting assets.” Feature 0006 expressly defers campaign and prompt assets,
|
selected runtime group is supported. The likely deferred concern is operator
|
||||||
operator policy, secrets, and the opinionated D&D configuration layer. The
|
selection and group-membership management, not operator access itself.
|
||||||
sentence is both redundant with the rewritten introduction and inaccurate for
|
|
||||||
the implemented foundation.
|
|
||||||
|
|
||||||
The supported-platform summary also names Ubuntu 26.04 without recording the
|
The adjacent YAML fragment defines an otherwise unexplained
|
||||||
roadmap's `amd64` and `arm64` boundary.
|
`operator_group_members` variable but shows no consumer task or role that uses
|
||||||
|
it. As written, copying the example does not manage any membership and may lead
|
||||||
|
a reader to believe that the pipeline role consumes that variable.
|
||||||
|
|
||||||
### Required Remediation
|
### Required Remediation
|
||||||
|
|
||||||
- Remove the retained placeholder sentence.
|
- Replace "operator access" in the deferred list with the precise deferred
|
||||||
- State the supported `amd64` and `arm64` architectures in the rewritten
|
behavior: operator selection and group-membership management.
|
||||||
platform summary.
|
- Replace the inert variable fragment with a concise, complete consumer-side
|
||||||
- Make no broader README expansion; the existing dependency, interface,
|
example that actually adds a selected account to the runtime group, or omit
|
||||||
deferral, and validation documentation is otherwise aligned.
|
the example and state the prerequisite directly.
|
||||||
|
- Keep human account and membership management outside the production pipeline
|
||||||
|
role.
|
||||||
|
|
||||||
### Resolution
|
## Resolution
|
||||||
|
|
||||||
The retained sentence was removed, and the introduction now records the
|
Resolved in pipeline-role commit `b15fe8d`. The deferred-work summary now
|
||||||
supported `amd64` and `arm64` architectures without expanding the role's
|
names operator selection and group-membership management rather than operator
|
||||||
claimed scope.
|
access. The shared-filesystem section retains existing-group-member invocation
|
||||||
|
as supported behavior and provides a complete consumer-owned
|
||||||
|
`ansible.builtin.user` example that adds a selected account to the runtime
|
||||||
|
group. No production role behavior changed.
|
||||||
|
|
||||||
## Finding 2: Give the Isolated Dependency Path Resolution Priority
|
## Required Validation
|
||||||
|
|
||||||
Severity: low
|
After the documentation correction, run:
|
||||||
|
|
||||||
`ansible-role-dnd-pipeline/tests/integration` installs the five pinned Git
|
|
||||||
roles into `$test_tmp/roles`, but sets `ANSIBLE_ROLES_PATH` with the workspace
|
|
||||||
parent before that isolated directory:
|
|
||||||
|
|
||||||
```sh
|
|
||||||
export ANSIBLE_ROLES_PATH="$(dirname "$repository_root"):$test_tmp/roles"
|
|
||||||
```
|
|
||||||
|
|
||||||
No conflicting canonical role directories currently exist in the workspace,
|
|
||||||
so the reviewed run used the installed dependencies and passed. Nevertheless,
|
|
||||||
the ordering does not preserve the test's stated invariant if a
|
|
||||||
`rakestraw.<application>` directory is later present in the parent path:
|
|
||||||
Ansible would resolve that checkout before the exact version installed from
|
|
||||||
`requirements.yml`. Feature 0006 requires the integration suite to exercise
|
|
||||||
the same pinned dependency combination delivered to consumers.
|
|
||||||
|
|
||||||
### Required Remediation
|
|
||||||
|
|
||||||
Put the fresh dependency path first while retaining the workspace parent only
|
|
||||||
as the fallback that resolves the pipeline role under test:
|
|
||||||
|
|
||||||
```sh
|
|
||||||
export ANSIBLE_ROLES_PATH="$test_tmp/roles:$(dirname "$repository_root")"
|
|
||||||
```
|
|
||||||
|
|
||||||
Do not add dependency-content comparisons, source-revision assertions, or
|
|
||||||
other verification machinery. Ordinary Ansible role lookup with the correct
|
|
||||||
path precedence is sufficient.
|
|
||||||
|
|
||||||
### Resolution
|
|
||||||
|
|
||||||
The integration driver now places its private dependency directory first and
|
|
||||||
uses the workspace parent only as the fallback for the pipeline role under
|
|
||||||
test. No additional dependency verification was added.
|
|
||||||
|
|
||||||
## Final Validation
|
|
||||||
|
|
||||||
From `ansible-role-dnd-pipeline`, run:
|
|
||||||
|
|
||||||
```text
|
```text
|
||||||
tests/integration
|
cd ansible-role-dnd-pipeline && tests/integration
|
||||||
git diff --check
|
git diff --check
|
||||||
git status --short --branch
|
|
||||||
```
|
```
|
||||||
|
|
||||||
Expected result: dependency bootstrap, syntax checking, production lint,
|
The expected result remains successful native configuration checks,
|
||||||
baseline native checks, Narratio configuration validation, both immediate
|
representative cross-identity access, and immediate repeats with `changed=0`
|
||||||
clean repeats, the explicit Seriatim `v1.4.0` outcome, and baseline cleanup all
|
and `failed=0`.
|
||||||
pass. The role repository contains only the intended remediation changes.
|
|
||||||
|
|
||||||
## Review Validation Evidence
|
## Review Validation Evidence
|
||||||
|
|
||||||
During review, `tests/integration` completed successfully. It installed
|
The independent review inspected the complete diffs for all eight stage
|
||||||
`community.general` 13.3.0 and all five exact Git role revisions into private
|
commits and confirmed that every dependency pin resolves to the intended
|
||||||
temporary paths, passed syntax checking and production-profile ansible-lint,
|
standalone-role commit. `git diff --check` passed across all five changed role
|
||||||
validated the assembled applications through their native interfaces, and
|
repositories. The complete pipeline `tests/integration` entry point passed its
|
||||||
reported `changed=0` and `failed=0` on both required immediate repeats. The
|
isolated dependency installation, syntax check, production-profile lint,
|
||||||
cleanup trap restored the baseline Seriatim `v1.5.0` deployment. `git diff
|
native application checks, cross-identity access exercise, configurable
|
||||||
--check` also passed before this review record was written.
|
profile and version cases, and immediate clean repeats. All repositories were
|
||||||
|
clean before this review document was revised.
|
||||||
|
|
||||||
After remediation, `bash -n tests/integration`, `git diff --check`, and the
|
After remediation, the complete pipeline integration entry point and
|
||||||
complete `tests/integration` entry point passed again. The rerun installed the
|
`git diff --check` passed again. The test fixture was removed and the baseline
|
||||||
exact pinned dependencies into fresh private paths, passed syntax and
|
Seriatim version and pipeline configuration were restored during cleanup.
|
||||||
production-profile lint, completed all native checks, reported `changed=0` and
|
|
||||||
`failed=0` on both required repeats, and restored the baseline suite. No
|
|
||||||
Feature 0006 findings remain.
|
|
||||||
|
|||||||
@@ -1,10 +1,11 @@
|
|||||||
# Workspace Status
|
# Workspace Status
|
||||||
|
|
||||||
Last updated: 2026-09-10
|
Last updated: 2026-09-15
|
||||||
|
|
||||||
Current milestone: M1-03 suite-level pipeline role
|
Current milestone: M1-03 suite-level pipeline role
|
||||||
|
|
||||||
Current focus: Select the next suite-level pipeline role feature.
|
Current focus: Publish the completed Notarius role revision required to resume
|
||||||
|
Feature 0010.
|
||||||
|
|
||||||
| ID | Deliverable | Owner | State | Evidence or next step |
|
| ID | Deliverable | Owner | State | Evidence or next step |
|
||||||
| --- | --- | --- | --- | --- |
|
| --- | --- | --- | --- | --- |
|
||||||
@@ -15,7 +16,7 @@ Current focus: Select the next suite-level pipeline role feature.
|
|||||||
| M0-05 | Suite-level role repository | ansible-role-dnd-pipeline | done | Repository created and added to `workspace.yml` |
|
| M0-05 | Suite-level role repository | ansible-role-dnd-pipeline | done | Repository created and added to `workspace.yml` |
|
||||||
| M1-01 | Remaining MVP design decisions | workspace | done | Feature 0003 roadmap fixes the Notarius configuration interface |
|
| M1-01 | Remaining MVP design decisions | workspace | done | Feature 0003 roadmap fixes the Notarius configuration interface |
|
||||||
| M1-02 | Standalone application roles | role repositories | done | All five standalone roles implemented and independently reviewed |
|
| M1-02 | Standalone application roles | role repositories | done | All five standalone roles implemented and independently reviewed |
|
||||||
| M1-03 | Suite-level pipeline role | ansible-role-dnd-pipeline | in_progress | Composition foundation complete; select the next suite-policy feature |
|
| M1-03 | Suite-level pipeline role | ansible-role-dnd-pipeline | blocked | Publish the completed Notarius role revision, then resume Feature 0010 |
|
||||||
| M1-04 | Collection assembly | ansible-collection-dnd | proposed | Select and implement the pipeline-role incorporation mechanism |
|
| M1-04 | Collection assembly | ansible-collection-dnd | proposed | Select and implement the pipeline-role incorporation mechanism |
|
||||||
| F0001 | Install Seriatim from pinned source | ansible-role-seriatim | done | Implementation, integration coverage, and final remediation completed through `fb8dc41` |
|
| F0001 | Install Seriatim from pinned source | ansible-role-seriatim | done | Implementation, integration coverage, and final remediation completed through `fb8dc41` |
|
||||||
| F0002 | Install and configure Audita | ansible-role-audita | done | Field-specific configuration completed in `e61f02f` and `847c4c3`; full suite passed |
|
| F0002 | Install and configure Audita | ansible-role-audita | done | Field-specific configuration completed in `e61f02f` and `847c4c3`; full suite passed |
|
||||||
@@ -23,6 +24,10 @@ Current focus: Select the next suite-level pipeline role feature.
|
|||||||
| F0004 | Install and configure Scriptorium | ansible-role-scriptorium | done | Implemented and validated through remediation commit `8f47aa8` |
|
| F0004 | Install and configure Scriptorium | ansible-role-scriptorium | done | Implemented and validated through remediation commit `8f47aa8` |
|
||||||
| F0005 | Install and configure Narratio | ansible-role-narratio | done | Implemented and validated through remediation commit `7feff47` |
|
| F0005 | Install and configure Narratio | ansible-role-narratio | done | Implemented and validated through remediation commit `7feff47` |
|
||||||
| F0006 | Establish pipeline-role composition | ansible-role-dnd-pipeline | done | Implemented and validated through remediation commit `4ea4358` |
|
| F0006 | Establish pipeline-role composition | ansible-role-dnd-pipeline | done | Implemented and validated through remediation commit `4ea4358` |
|
||||||
|
| F0007 | Deploy D&D campaigns and prompt assets | ansible-role-dnd-pipeline, campaigns, and narratio-prompts | done | Implemented and validated through remediation commit `7572fa3` |
|
||||||
|
| F0008 | Define opinionated D&D processing configuration | ansible-role-dnd-pipeline | done | Implemented and independently reviewed through remediation commit `3e253d7` |
|
||||||
|
| F0009 | Establish shared pipeline filesystem and execution | configuration-bearing application roles and ansible-role-dnd-pipeline | done | Implemented and independently reviewed through remediation commit `b15fe8d` |
|
||||||
|
| F0010 | Integrate D&D Notarius extraction | ansible-role-notarius and ansible-role-dnd-pipeline | blocked | Stage 1 completed in Notarius role commit `14a38e04e35ef524d6a97fa7fb5a04981a0a2161`; publish it to the canonical origin before Stage 2 |
|
||||||
| A0001 | Audit completed standalone-role test suites | workspace and standalone roles | done | Findings recorded in `docs/roadmap/test-suite-audit-findings.md` |
|
| A0001 | Audit completed standalone-role test suites | workspace and standalone roles | done | Findings recorded in `docs/roadmap/test-suite-audit-findings.md` |
|
||||||
| R0001 | Simplify completed standalone-role test suites | workspace and standalone roles | done | Role commits `e08c63c`, `d2d0b9d`, and `cfecf37` passed implementation and independent review |
|
| R0001 | Simplify completed standalone-role test suites | workspace and standalone roles | done | Role commits `e08c63c`, `d2d0b9d`, and `cfecf37` passed implementation and independent review |
|
||||||
|
|
||||||
|
|||||||
Reference in New Issue
Block a user