diff --git a/assets/configs/audita/config.yml b/assets/configs/audita/config.yml new file mode 100644 index 0000000..d71f1ea --- /dev/null +++ b/assets/configs/audita/config.yml @@ -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 diff --git a/assets/configs/narratio/pipeline.yml b/assets/configs/narratio/pipeline.yml new file mode 100644 index 0000000..f7eaef9 --- /dev/null +++ b/assets/configs/narratio/pipeline.yml @@ -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 diff --git a/assets/configs/notarius/config.yml b/assets/configs/notarius/config.yml new file mode 100644 index 0000000..b563215 --- /dev/null +++ b/assets/configs/notarius/config.yml @@ -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 diff --git a/assets/configs/scriptorium/config.yml b/assets/configs/scriptorium/config.yml new file mode 100644 index 0000000..466957d --- /dev/null +++ b/assets/configs/scriptorium/config.yml @@ -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 diff --git a/docs/orientation.md b/docs/orientation.md index 4f39658..4a73531 100644 --- a/docs/orientation.md +++ b/docs/orientation.md @@ -14,6 +14,9 @@ Repositories inside this directory: role. - `assets/narratio-prompts`: PromptKit-compatible prompts and schemas deployed 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 `pipeline_dnd` proof of concept; treat it as read-only reference unless the task explicitly includes it. @@ -49,4 +52,7 @@ machine-readable inventory of paths and remotes. contracts. - Asset repositories: authoritative campaign and prompt-library content and 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. diff --git a/docs/roadmap/features/0008-opinionated-dnd-processing-configuration.md b/docs/roadmap/features/0008-opinionated-dnd-processing-configuration.md new file mode 100644 index 0000000..aa07daf --- /dev/null +++ b/docs/roadmap/features/0008-opinionated-dnd-processing-configuration.md @@ -0,0 +1,473 @@ +# Feature 0008: Opinionated D&D Processing Configuration + +Status: ready + +## 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 0009 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. Later features should address storage/publishing and +secret delivery together, operator access, 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. diff --git a/docs/roadmap/implementation.md b/docs/roadmap/implementation.md index 6e237a7..d449635 100644 --- a/docs/roadmap/implementation.md +++ b/docs/roadmap/implementation.md @@ -1,13 +1,503 @@ -# Implementation Plan +# Implementation Plan 0008: Opinionated D&D Processing Configuration -Status: pending +Status: ready -No implementation plan is currently active. Feature 0007 was implemented and -independently reviewed through pipeline-role remediation commit `7572fa3`. -Its durable scope, decisions, and acceptance criteria remain in -[Feature 0007](features/0007-dnd-asset-deployment-and-scriptorium-integration.md), -and the completed review record remains in [the remediation -document](remediation.md). +Target executor: GPT-5.6-Terra -Select and approve the next feature roadmap before replacing this notice with -a new staged implementation plan. +Feature roadmap: +`docs/roadmap/features/0008-opinionated-dnd-processing-configuration.md` + +Active plan location: `docs/roadmap/implementation.md` + +## Objective + +Extend `ansible-role-dnd-pipeline` with the deliberately opinionated Audita +policy, Narratio processing contracts, individually composed D&D artifacts, +party-driven character-analysis family, and selectable `testing` profile +defined by Feature 0008. Preserve the standalone roles as generic application +installers and validate the assembled behavior through native application +interfaces without making provider requests. + +The feature roadmap remains authoritative for scope, rationale, target state, +and acceptance criteria. + +## 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 and report if an application contract differs from the feature roadmap + in a way that requires a product or architecture decision. Do not silently + substitute legacy test-machine syntax. +- Keep standalone application roles and the two asset repositories unchanged. + All production changes belong to `ansible-role-dnd-pipeline`. +- Start from direct role defaults, dependency variables, one directory loop, + and one template loop. Do not add configuration probes, assembly facts, + handlers, validation tasks, checksums, manifests, cleanup machinery, or a + duplicate Narratio root template. +- Trust `ansible.builtin.file`, `ansible.builtin.template`, the standalone + roles, and ConfigKit to provide their documented convergence behavior. +- Do not put credentials or credential values in role defaults, templates, + documentation, or tests. Environment-variable names are configuration and + may be managed. +- Do not run WhisperX, a model provider, a complete transcript, or any other + external processing workload during validation. +- Run every stage's validation before committing it. +- Commit each completed stage when it leaves the repository valid, using the + plain-English commit intent specified by that stage. +- Do not begin a dependent stage after an earlier stage fails validation. + +## Starting State and Preconditions + +- `ansible-role-dnd-pipeline` is on `main` at reviewed Feature 0007 commit + `7572fa37cfc8` and has a clean working tree. +- Features 0001 through 0007 and the standalone-role test simplification are + complete. +- The workspace control repository's Feature 0008 roadmap and this plan must + be committed before implementation begins. +- `assets/campaigns` and `assets/narratio-prompts` are available as local, + clean reference repositories. Their current revisions supply representative + campaign parties and the six D&D prompt contracts used by this feature. +- The authoritative application repositories are available at + `../audita`, `../narratio`, `../promptkit`, and `../scriptorium`. +- The workspace `.venv` provides `ansible-playbook` 2.21.3 and `ansible-lint` + 26.8.0. The role's existing integration driver installs its pinned Galaxy + dependencies into private temporary paths. +- The integration host is an acceptable proxy for Ubuntu 26.04 and permits + task-level privilege escalation. + +## Repository Scope + +- `ansible-role-dnd-pipeline` is the only implementation repository that may + change. It owns suite defaults, the argument specification, dependency + wiring, Narratio fragment templates, convergence tasks, integration tests, + and consumer documentation. +- `ansible-role-{audita,narratio,notarius,scriptorium,seriatim}` may be + inspected for their public interfaces but must remain unchanged. +- `assets/campaigns`, `assets/narratio-prompts`, `../audita`, `../narratio`, + `../promptkit`, and `../scriptorium` may be inspected as authoritative + contracts but must remain unchanged. +- `rakestraw-ansible` and `assets/configs` are read-only historical or + operational references, not contracts to reproduce. +- The workspace control repository changes only before or after the sprint for + planning and progress management; implementation stages do not edit it. + +## Stage 1: Apply the D&D Audita Policy + +### Objective + +Expose the selected suite-prefixed Audita settings and pass them through the +standalone Audita role so the installed Audita configuration represents the +complete reviewed D&D 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/0008-opinionated-dnd-processing-configuration.md` +- `ansible-role-audita/defaults/main.yml` +- `ansible-role-audita/meta/argument_specs.yml` +- `ansible-role-audita/README.md` +- `../audita/docs/config.md` + +### Preconditions + +- `ansible-role-dnd-pipeline` is clean at `7572fa37cfc8`. +- Every selected Audita field in the feature roadmap still has a corresponding + standalone-role variable with the same native meaning. +- No secret value is required to render or natively validate the configuration. + +### Owning Repository + +`ansible-role-dnd-pipeline` + +### Required Changes + +1. Add one `dnd_pipeline_`-prefixed default for every Audita field in the + roadmap's **Selected Audita and Testing Policy** table. Use the exact + selected values, including the repeated `glossary` module, endpoint and + models, environment-variable names, falsey-capable numeric values, + durations, context description, and diagnostic policy. +2. Use a single `dnd_pipeline_audita_output_schema` default of `audita-v1` as + the suite source of truth. Stage 2 will also use that value for Narratio's + adapter boundary. +3. Add matching entries to `meta/argument_specs.yml` with native Ansible types: + lists remain lists, integers remain integers, threshold values remain + numeric, and durations, URLs, model names, environment-variable names, the + context description, schema, and retention policy remain strings. These are + concrete suite policy and are required within this role's defaulted public + interface. +4. In `meta/main.yml`, pass every suite Audita variable to the existing + corresponding `audita_*` dependency variable. Do not also pass these values + as Narratio Audita command-line overrides; Narratio already receives the + managed Audita configuration path. +5. Do not change `ansible-role-audita`, add role-private state, or add runtime + tests to `tasks/main.yml`. Rendering and validation remain owned by the + standalone role and the integration suite respectively. + +### Validation + +Run from `ansible-role-dnd-pipeline`: + +```text +tests/integration +``` + +Then inspect the effective managed policy with Audita's native interface: + +```text +/usr/local/bin/audita config validate --config /usr/local/etc/audita/config.yml +``` + +Expected result: the existing suite integration passes, Audita natively accepts +the rendered configuration, the repeated module order and all selected D&D +values are effective, no provider request occurs, and the driver's immediate +repeat reports `changed=0` and `failed=0`. + +### Completion Criteria + +- Every selected Audita value has one documented suite-prefixed source and one + corresponding standalone-role dependency assignment. +- No Audita application default outside the selected table has been copied + into the pipeline role. +- The role remains syntax-clean, lint-clean, natively valid, and idempotent. + +### Commit + +Commit intent: `Add the D&D Audita configuration defaults` + +## Stage 2: Compose the Narratio Processing and Artifact Configuration + +### Objective + +Deploy the explicit Narratio ConfigKit layout, pin only the suite-owned +coordination contracts, define each artifact and family independently, and +provide the selectable testing overlay. + +### 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/0008-opinionated-dnd-processing-configuration.md` +- `ansible-role-narratio/defaults/main.yml` +- `ansible-role-narratio/templates/pipeline.yml.j2` +- `ansible-role-narratio/meta/argument_specs.yml` +- `../narratio/docs/config.md` +- `../narratio/docs/cli.md` +- the current prompt manifests under `assets/narratio-prompts/prompts/trim` + and `assets/narratio-prompts/prompts/analyze` + +### Preconditions + +- Stage 1 is committed and validated. +- Narratio still supports explicit relative ConfigKit imports, additive + disjoint base fragments, the fixed `profiles/testing.yml` overlay, + `party.characters` artifact families, and the source identifiers selected + in the roadmap. +- The deployed prompt manifests still declare the input names recorded in the + roadmap. + +### Owning Repository + +`ansible-role-dnd-pipeline` + +### Required Changes + +1. Add field-specific suite defaults and argument-spec entries for exactly the + selected Narratio coordination values: + `seriatim-intermediate` Seriatim output, `transcripts/final.json` + normalization with `seriatim-intermediate`, enabled trimming to + `transcripts/final.trimmed.json`, `dnd.session_bounds` with input + `transcript` and output `artifacts/session_bounds.json`, and enabled + Markdown rendering. Reuse `dnd_pipeline_audita_output_schema` for the + Narratio Audita output schema. Do not expose or render Narratio-local + reports, timeouts, debug settings, work retention, title, presentation + flags, or bounds profile settings. +2. Add the five complete native-mapping defaults and matching dictionary + argument specifications fixed by the roadmap: + `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`. +3. Give those mappings the exact base topology selected by the roadmap: + recap and both rumor artifacts enabled; scene map and character family + disabled but fully executable when explicitly selected; current trimmed + transcript inputs for recap, scene map, and the family; an optional + previous-session recap input for recap and the family; current recap inputs + for both rumors; no redundant `depends_on`; no base `profile_id`; and the + canonical output paths. The family uses `for_each: party.characters`, key + `character_meta_analysis`, and member variables `character_name` from + `character.name` and `character_class` from `character.class_summary`. +4. Add one string default and argument-spec entry for the testing Scriptorium + profile, defaulting to `gemini-flash-latest`. The testing overlay must set + only `profile_id` for all four ordinary artifacts and the one family; it + must not duplicate base definitions, imports, Audita settings, credentials, + or processing topology. +5. Add templates for `conf.d/processing.yml`, each of the four artifact files, + `artifact-families/character-meta-analysis.yml`, and + `profiles/testing.yml`. Each artifact/family template emits its fixed + top-level source key and serializes the corresponding complete mapping with + Ansible/Jinja YAML filters. Do not hand-build scalar quoting or merge a + second raw override interface. +6. Extend `tasks/main.yml` with one `ansible.builtin.file` loop that directly + manages `conf.d`, `artifacts`, `artifact-families`, and `profiles` below + `/usr/local/etc/narratio` as `root:narratio` mode `0750`, and one + `ansible.builtin.template` loop that directly manages the seven files as + `root:narratio` mode `0640`. Apply `become: true` to both tasks. Do not add + `stat`, handlers, notifications, validation commands, cleanup, or ownership + probes. +7. In the Narratio dependency entry in `meta/main.yml`, pass an exact ordered + list of relative `path` imports for the processing file, four artifacts, + and family file. Also pass only the coordination values that belong in the + standalone root document or otherwise cannot be supplied by the fragment. + Do not define the same ConfigKit leaf in both root and an import. Keep file + names, imports, and top-level keys fixed rather than exposing a second + topology override. +8. Keep the endpoint, models, modules, tuning, and diagnostic settings solely + in Audita's managed configuration. The Narratio processing fragment adds + only `audita.output_schema`; Narratio continues to supply Audita's + run-specific `--output` path. + +### Validation + +Run from `ansible-role-dnd-pipeline`: + +```text +tests/integration +/usr/bin/sudo -u narratio /usr/local/bin/narratio config validate --config /usr/local/etc/narratio/pipeline.yml --campaign centaurs +/usr/bin/sudo -u narratio /usr/local/bin/narratio config validate --config /usr/local/etc/narratio/pipeline.yml --campaign centaurs --profile testing +/usr/bin/sudo -u narratio /usr/local/bin/narratio config artifacts --config /usr/local/etc/narratio/pipeline.yml --campaign centaurs +/usr/bin/sudo -u narratio /usr/local/bin/narratio config diff default testing --config /usr/local/etc/narratio/pipeline.yml --campaign centaurs +``` + +Expected result: base and testing configurations validate without external +calls; artifact inspection shows the enabled recap, inferred recap-to-rumor +dependencies, disabled selectable scene map, and one disabled generated +character artifact per campaign member; the semantic diff contains only the +testing profile selections; the existing integration remains clean on its +immediate repeat. + +### Completion Criteria + +- The installed tree and explicit import order exactly match the roadmap. +- No base leaf is claimed by more than one ConfigKit source. +- All artifact inputs match their prompt manifests and all output paths match + the selected suite contract. +- Production prompt profiles remain inherited and the testing overlay changes + only the five selected `profile_id` leaves. +- The implementation consists of direct defaults, templates, dependency + wiring, one directory task, and one template task without additional + convergence machinery. + +### Commit + +Commit intent: `Add the Narratio D&D processing configuration` + +## Stage 3: Exercise the Assembled Configuration Behavior + +### Objective + +Extend the existing integration driver with the smallest representative set of +native state-based checks that protects Feature 0008 and its clean convergence. + +### 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/0008-opinionated-dnd-processing-configuration.md` +- `ansible-role-dnd-pipeline/tests/integration` +- `ansible-role-dnd-pipeline/tests/converge.yml` +- `../narratio/docs/cli.md` + +### Preconditions + +- Stages 1 and 2 are committed and validated. +- Both local asset repositories remain clean and can be installed through the + existing immutable `file://` test inputs. +- Native Audita, Narratio, and Scriptorium inspection commands can exercise + configuration without contacting a provider. + +### Owning Repository + +`ansible-role-dnd-pipeline` + +### Required Changes + +1. Retain the current integration driver's private dependency installation, + immutable local asset revisions, native application checks, selected-version + behavior, cleanup boundary, and immediate clean repeats. +2. Extend the baseline with native Audita validation and native Narratio base + and `testing` validation for one deployed campaign. Do not parse rendered + files or repeat module-managed file ownership and mode assertions. +3. Use `narratio config artifacts` for one representative enabled artifact, + one inferred rumor dependency, and representative party-family expansion. + Do not enumerate every artifact or campaign character. +4. Use `narratio config diff default testing` to establish that the overlay is + independently selectable and changes Scriptorium profile selection without + duplicating the base topology. +5. Explicitly override the suite testing-profile variable with the driver's + existing `endpoint-profile` fixture and observe that effective selection. + Also use Scriptorium's native inspection interface to resolve one production + prompt profile and the explicit testing fixture without provider traffic. + Do not assert that `gemini-flash-latest` remains the role's default. +6. Keep one immediate unchanged repeat after the representative Feature 0008 + inputs and require `changed=0` and `failed=0`. Avoid task-result assertions, + snapshots, exact default documents, implementation counts, or tests of + ConfigKit and trusted Ansible module behavior. + +### Validation + +Run from `ansible-role-dnd-pipeline`: + +```text +tests/integration +``` + +Expected result: syntax checking and production-profile lint pass; all five +applications and both asset repositories converge; Audita and both Narratio +profiles validate natively; representative production/testing Scriptorium +profiles resolve without provider calls; the artifact graph and family +expansion are observed through Narratio; the explicit profile override is +effective; and the immediate repeat reports `changed=0` and `failed=0`. + +### Completion Criteria + +- Each new test protects a user-visible Feature 0008 behavior and remains valid + after an internal task or template refactor. +- No test freezes the current role default, snapshots a complete file, tests a + trusted module, or invokes an external processing service. +- The complete integration driver passes from a clean dependency installation. + +### Commit + +Commit intent: `Test the D&D processing configuration` + +## Stage 4: Document Production and Testing Operation + +### Objective + +Document the role's opinionated policy, supported customization boundary, +installed composition layout, and native production/testing inspection +workflow for consumers. + +### 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/0008-opinionated-dnd-processing-configuration.md` +- `ansible-role-dnd-pipeline/README.md` +- `../narratio/docs/cli.md` + +### Preconditions + +- Stages 1 through 3 are committed and validated. +- Variable names, installed paths, source keys, and native commands in the + implementation are final and match the roadmap. + +### Owning Repository + +`ansible-role-dnd-pipeline` + +### Required Changes + +1. Update the README variable reference for the new Audita, Narratio + coordination, artifact/family mapping, and testing-profile variables. Make + clear that concrete defaults are deliberate D&D suite policy rather than a + mirror of application defaults. +2. Document the root/import ownership boundary and exact installed + `conf.d`, `artifacts`, `artifact-families`, and `profiles` layout. +3. Explain that each artifact/family mapping is replaceable as one native + mapping while the file, import, and top-level key remain fixed. Document + `enabled: false` as the way to retain but normally disable a source. +4. Document base validation, `--profile testing`, artifact inspection, and + `config diff default testing` with commands that require neither a provider + request nor edits to managed files. +5. Explain that production artifacts inherit prompt-owned profiles, the + testing profile defaults to `gemini-flash-latest`, and callers can explicitly + replace the testing profile through inventory. Do not document the current + default as a compatibility guarantee. +6. State the intentional boundaries: Audita owns its endpoint/model/tuning + configuration; Narratio supplies its run-specific Audita output path; API + keys, Notarius enablement, storage/publishing, operator access, scheduling, + and end-to-end external execution remain deferred. + +### Validation + +Run from `ansible-role-dnd-pipeline`: + +```text +tests/integration +git diff --check HEAD +``` + +Expected result: the complete behavioral suite remains green and idempotent; +documentation matches the implemented variables, paths, and CLI; and no +whitespace errors are reported. + +### Completion Criteria + +- A consumer can identify what the suite deliberately owns, what remains an + application default, how to replace each supported policy value, and how to + select and inspect testing behavior. +- Documentation does not promise deferred behavior or expose credentials. +- The repository remains fully validated after documentation changes. + +### Commit + +Commit intent: `Document D&D processing profiles and artifacts` + +## Final Validation and Handoff + +Run from `ansible-role-dnd-pipeline` after all four stages: + +```text +tests/integration +git diff --check HEAD +git status --short +``` + +The final handoff must: + +- confirm the full integration driver passes and its immediate repeat reports + `changed=0` and `failed=0`; +- identify the four implementation commit hashes and confirm the pipeline-role + working tree is clean; +- confirm every inspected standalone role, application, and asset repository + remains unchanged; +- summarize any deviation from this plan, unresolved finding, or deferred + work; +- report any implementation complexity beyond the planned defaults, + dependency assignments, templates, two task loops, tests, and documentation, + together with the acceptance criterion that required it; and +- leave Feature 0008 `ready` or `in_progress` for independent review rather + than marking it `done`. + +## Progress Notes + +No implementation stages have begun. Record only concise stage commit hashes +and blockers here during execution; preserve detailed evidence in the stage +commits and final handoff. diff --git a/docs/roadmap/mvp.md b/docs/roadmap/mvp.md index 925c7b2..cdf148d 100644 --- a/docs/roadmap/mvp.md +++ b/docs/roadmap/mvp.md @@ -263,6 +263,30 @@ application-role releases in one source repository. them owns their deployment. - Credential fields contain environment-variable names, never secret values. 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. ### Execution model diff --git a/docs/status.md b/docs/status.md index 82f7968..66a1b1f 100644 --- a/docs/status.md +++ b/docs/status.md @@ -1,10 +1,10 @@ # Workspace Status -Last updated: 2026-09-10 +Last updated: 2026-09-11 Current milestone: M1-03 suite-level pipeline role -Current focus: Select the next unit of work. +Current focus: Begin the approved Feature 0008 implementation sprint. | ID | Deliverable | Owner | State | Evidence or next step | | --- | --- | --- | --- | --- | @@ -24,6 +24,7 @@ Current focus: Select the next unit of work. | 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` | | 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 | ready | Execute the approved stages in `docs/roadmap/implementation.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 |