ansible-workspace-dnd/docs/roadmap/implementation.md

Implementation Plan 0008: Opinionated D&D Processing Configuration

Status: ready

Target executor: GPT-5.6-Terra

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:

tests/integration

Then inspect the effective managed policy with Audita's native interface:

/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:

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:

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:

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:

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.