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

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

- [x] Stage 1 complete — `ansible-role-dnd-pipeline` commit `bc6df2a`; full
  integration and native Audita validation passed. No deviations.
- [x] Stage 2 complete — `ansible-role-dnd-pipeline` commit `7ca812c`; full
  integration, native base/testing Narratio validation, artifact inspection,
  and profile diff passed. No deviations.
- [x] Stage 3 complete — `ansible-role-dnd-pipeline` commit `c1fa8ba`; full
  integration passed with native Audita, Narratio, and Scriptorium coverage,
  explicit testing-profile override, and clean repeats. No deviations.