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

# Implementation Plan 0006: Establish Pipeline Role Composition

Status: ready

Target executor: GPT-5.6-Terra

Feature roadmap:
[Feature 0006: Pipeline Role Composition Foundation](features/0006-pipeline-role-composition-foundation.md)

Active plan location: `docs/roadmap/implementation.md`

## Objective

Implement the independently developed `rakestraw.dnd_pipeline` role defined by
Feature 0006. Compose the five completed standalone application roles through
ordinary dependency metadata, install them reproducibly from a Git dependency
manifest, expose the approved suite-level variables, and wire Narratio to the
standard downstream application paths.

The feature roadmap remains authoritative for scope, rationale, target end
state, public variables, dependency revisions, and acceptance criteria.

## Execution Rules

- Execute Stage 1 and Stage 2 in numeric order.
- Immediately before each stage, read every document in that stage's Required
  Policy Review, then confirm its preconditions and the owning repository's
  working-tree state.
- Modify only `ansible-role-dnd-pipeline`. Treat the workspace control
  repository, standalone application roles, application sources, asset
  repositories, collection, and proof of concept as read-only during
  out-of-band implementation.
- Preserve unrelated changes. Stop if the pipeline-role repository is
  unexpectedly dirty at a stage boundary.
- Use ordinary role dependency metadata. Do not copy downstream tasks or
  templates, add a loader role, or surround role invocation with state probes
  or result inspection.
- Define only the nine suite-owned variables fixed by the feature roadmap. Do
  not alias the complete standalone interfaces or add raw downstream-variable
  maps, path overrides, component switches, content settings, operator
  settings, or secret settings.
- Pass the common build-dependency switch, Go channel, and Go executable to
  all five dependencies. Pass each selected application version only to its
  corresponding dependency.
- Pass the required WhisperX URL and the roadmap's fixed downstream binary and
  configuration paths to Narratio. Install Notarius without enabling it in
  Narratio.
- Trust each dependency to establish its documented state. Do not test or
  reimplement APT, Snap, Git, file, template, account, or build behavior in
  production pipeline-role logic.
- Keep behavioral tests at the composition boundary. Prove that the assembled
  applications are usable, Narratio accepts the assembled configuration, a
  suite version override reaches its application role, and an immediate
  repeat is clean. Do not rerun the standalone roles' behavior matrices.
- Do not assert current default versions, exact dependency pins, task order,
  task traces, file metadata, package state, checkout state, or other trusted
  module postconditions in behavioral tests.
- Use fully qualified collection names. Run each stage's validation before
  committing it, and do not begin Stage 2 if Stage 1 fails validation.
- Commit each completed stage with its specified plain-English message. Do not
  push during out-of-band implementation.
- Test cleanup may reapply the baseline pipeline role and remove only the
  integration driver's private temporary directory. Do not delete campaign,
  prompt, runtime, or other caller content.

## Starting State and Preconditions

- `ansible-role-dnd-pipeline` is clean on `main` at
  `1a66d177cdd5d948c94c291b718c779dbbfd1f91`, tracking `origin/main` without
  divergence.
- This plan, the ready Feature 0006 roadmap, and the corresponding workspace
  documentation and status updates are committed before out-of-band execution
  begins.
- The exact dependency commits fixed by Feature 0006 are reachable from their
  declared remote repositories before Stage 1 begins. At plan preparation,
  all five commits are local-only and must be pushed:

  | Dependency | Required commit | Current `origin/main` |
  | --- | --- | --- |
  | Audita role | `d2d0b9d00b3b491ce7613ccfc8f686f3d1fa0896` | `3a8c21f0e61c62dbb603ba0f3fdfab1fd3b1de09` |
  | Narratio role | `7feff4728a5968b6b1dd87e83add9fa1a9066b18` | `b97a317f9ec9f15675e81c65af3f4a1ad8176886` |
  | Notarius role | `cfecf37261f2595d45113235c591ee102d6f181f` | `f8a3e113ef4975b2c2745cb3f08500b2206c3f21` |
  | Seriatim role | `e08c63c0b078658bdfa2d10a2e6e1e4f9372a075` | `fb8dc4100c029e25c4ab507645d75df0d739fe66` |
  | Scriptorium role | `8f47aa802a5e0c9dae9c0f43a1c70b3512b2c8b2` | `2cd69a4b2ead23b44f1aab51fd1b1f14ac326af2` |

- The local controller and managed-host proxy are Ubuntu 26.04 `x86_64`, with
  gathered facts and passwordless task-level privilege escalation available.
- Workspace tooling is available in `../.venv/bin` from the pipeline-role
  repository: Ansible Core 2.21.3 and ansible-lint 26.8.0.
- `community.general` 13.3.0 and Go Snap channel `1.26/stable` are available.
- The five application binaries and their current managed state may already
  exist from standalone-role development. The integration suite must converge
  from that state without treating prior installation as test evidence or
  deleting unrelated content.
- Seriatim tag `v1.4.0` remains available for the explicit suite-level version
  override case and reports `seriatim version v1.4.0` through its native
  version command.
- Narratio can validate the baseline assembled pipeline without contacting the
  syntactically valid test WhisperX URL. Notarius remains disabled, and no
  campaign, prompt library, credentials, or session input is required for
  configuration validation.

## Repository Scope

Repository that changes:

- `ansible-role-dnd-pipeline`: public interface, dependency metadata and
  manifests, documentation, and focused repository-local integration suite.

Repositories that may be inspected but must remain unchanged:

- `ansible-workspace-dnd`: authoritative roadmap, plan, policies, inventory,
  and status.
- `ansible-role-{audita,narratio,notarius,seriatim,scriptorium}`: authoritative
  dependency interfaces and reviewed implementations.
- `../{audita,narratio,notarius,seriatim,scriptorium}`: authoritative native
  application contracts.
- `assets/campaigns` and `assets/narratio-prompts`: future content inputs,
  outside this feature.
- `ansible-collection-dnd`: future collection assembly target.
- `rakestraw-ansible`: historical style and deployment reference.
- Every other repository in `workspace.yml`.

## Stage 1: Compose the Five Application Roles

### Objective

Create a complete standalone pipeline role whose metadata installs the five
applications with the approved suite interface, dependency pins, and
cross-application path wiring, then demonstrate baseline native usability and
clean repeated convergence.

### Required Policy Review

Before beginning this stage, read:

- `AGENTS.md`
- `docs/orientation.md`
- `docs/conventions.md`
- `docs/ansible.md`
- `docs/testing.md`

### Preconditions

- The starting revision and tool versions above remain valid.
- `ansible-role-dnd-pipeline` has no uncommitted changes.
- The workspace planning commit containing this plan exists.
- Every required dependency commit is fetchable from its roadmap-declared Git
  URL. Confirm this through a fresh `ansible-galaxy role install`; do not
  substitute local role directories for the remote dependency test.
- Existing managed application and runtime paths contain no test-created
  corruption that prevents ordinary role convergence. Preserve any campaign,
  prompt, session, or other caller content already present.

### Owning Repository

`ansible-role-dnd-pipeline`

### Required Changes

1. Retain the existing license and create the conventional role structure:
   `defaults/main.yml`, `meta/main.yml`, `meta/argument_specs.yml`,
   `tasks/main.yml`, `requirements.yml`, `collections/requirements.yml`,
   `ansible.cfg`, and focused files under `tests/`.
2. Declare role name `dnd_pipeline`, namespace `rakestraw`, author Eric
   Rakestraw, license `CC0-1.0`, Ubuntu 26.04 support, Ansible Core 2.18 or
   newer, the canonical issue tracker, and appropriate pipeline tags.
3. Define exactly the Feature 0006 Fixed Public Interface in defaults and
   matching argument specifications:
   - default the five `dnd_pipeline_*_version` variables to their roadmap
     releases;
   - default `dnd_pipeline_manage_build_dependencies` to `true`;
   - default `dnd_pipeline_go_snap_channel` to `1.26/stable`;
   - default `dnd_pipeline_go_binary` to `/snap/bin/go`; and
   - require `dnd_pipeline_whisperx_transcribe_url` as a string without
     inventing a default.
4. Add a root `requirements.yml` containing the five Git role dependencies in
   the roadmap's canonical names and at the exact reviewed commits. Add
   `collections/requirements.yml` pinning `community.general` to `13.3.0`.
5. Declare these dependencies in `meta/main.yml`, in this order: Seriatim,
   Audita, Notarius, Scriptorium, Narratio. Map each suite version to the
   corresponding application `*_version` variable and map the common
   dependency-management, Go channel, and Go executable values to all five
   roles.
6. In the Narratio dependency declaration, additionally pass:
   - `dnd_pipeline_whisperx_transcribe_url` as
     `narratio_whisperx_transcribe_url`;
   - `/usr/local/bin/seriatim` as `narratio_seriatim_binary`;
   - `/usr/local/bin/audita` and `/usr/local/etc/audita/config.yml` as the
     corresponding Narratio Audita values;
   - `/usr/local/bin/notarius` and `/usr/local/etc/notarius/config.yml` as the
     corresponding Narratio Notarius path values; and
   - `/usr/local/bin/scriptorium` and
     `/usr/local/etc/scriptorium/config.yml` as the corresponding Narratio
     Scriptorium values.
   Do not set `narratio_notarius_enabled` or supply D&D processing policy.
7. Keep `tasks/main.yml` empty except for its YAML document marker if Ansible
   requires the file. Dependency metadata is the complete production
   implementation for this feature; do not add wrapper tasks, assertions,
   probes, facts, handlers, or post-dependency validation.
8. Replace the placeholder README with concise documentation covering the
   supported platform, dependency bootstrap commands, canonical installed
   role names, all nine suite variables, required WhisperX URL, compatible
   default application set, common dependency opt-out and Go behavior,
   standard cross-application paths, direct use of unmapped standalone role
   variables, Notarius's disabled state, later collection name, deferred
   content/operators/secrets, and actual integration-test behavior.
9. Add a baseline local integration harness with one executable
   `tests/integration` entry point. Use strict shell options,
   repository-relative paths, a mode-`0700` private temporary directory, an
   isolated roles path, an isolated collections path, syntax checking,
   production-profile ansible-lint, and best-effort cleanup that reapplies the
   baseline role and removes only the private temporary directory.
10. Install `community.general` from `collections/requirements.yml` and install
    all five roles from `requirements.yml` into the fresh isolated roles path.
    Resolve the pipeline role itself from the working repository without
    replacing any dependency with a workspace sibling checkout.
11. Apply the pipeline role without play-level escalation and supply only a
    syntactically valid local test value for
    `dnd_pipeline_whisperx_transcribe_url`. Exercise the installed applications
    with concise native smoke or configuration commands without asserting
    their current default versions. Validate the assembled Narratio pipeline
    natively as the `narratio` application account without contacting
    WhisperX.
12. Immediately apply the identical baseline invocation again and require the
    aggregate recap to report `changed=0` and `failed=0`.
13. Do not assert downstream file existence, ownership, permissions, package
    state, Git state, dependency order, exact default versions, complete
    configuration content, or individual task results. Successful native use
    and clean repeated convergence are the stage's behavioral evidence.

### Validation

From `ansible-role-dnd-pipeline`, run:

```text
tests/integration
git diff --check
git status --short
```

Expected result: both manifests install into fresh isolated paths; syntax and
lint pass; the real pipeline role composes all five dependencies; their native
smoke/configuration commands and Narratio's assembled configuration validation
succeed; the immediate repeat reports `changed=0` and `failed=0`; cleanup
leaves the baseline suite usable; and only intended Stage 1 files are modified.

### Completion Criteria

- Defaults and argument specifications implement exactly the nine-variable
  suite interface, with only the WhisperX URL required.
- Git and collection manifests use the exact approved names, URLs, revisions,
  and collection version.
- Dependency metadata contains the five roles in the settled order and passes
  only the approved coordinated values and Narratio path wiring.
- The production role contains no duplicated downstream implementation or
  additional task machinery.
- README and metadata accurately describe the role, bootstrap procedure,
  public interface, composition boundary, and current non-goals.
- Fresh dependency bootstrap, static validation, baseline native behavior, and
  immediate clean convergence pass.
- No repository outside `ansible-role-dnd-pipeline` changes.

### Commit

Commit intent: `Compose the D&D pipeline roles`

## Stage 2: Add Focused Composition Coverage

### Objective

Prove through one representative override that suite-owned version selection
reaches the appropriate application role, while retaining the lean baseline
composition test and restoring the approved default suite afterward.

### Required Policy Review

Before beginning this stage, read:

- `AGENTS.md`
- `docs/orientation.md`
- `docs/conventions.md`
- `docs/ansible.md`
- `docs/testing.md`

### Preconditions

- Stage 1 is committed and `ansible-role-dnd-pipeline` is otherwise clean.
- Stage 1's complete integration entry point passes.
- The isolated dependency bootstrap still resolves all five exact Git commits.
- Applying the baseline pipeline inputs can restore the compatible default
  suite after the representative version override.

### Owning Repository

`ansible-role-dnd-pipeline`

### Required Changes

1. Retain the Stage 1 baseline native smoke/configuration checks and immediate
   clean repeat. Extend the existing integration entry point rather than
   introducing another framework, scenario tree, or cross-repository helper.
2. Add one representative convergence that explicitly sets
   `dnd_pipeline_seriatim_version: v1.4.0` while supplying the same test
   WhisperX URL.
3. Execute Seriatim's native version interface and require
   `seriatim version v1.4.0`. This proves suite-variable forwarding; do not
   inspect role defaults, dependency metadata, the source checkout, or task
   results to establish it.
4. Immediately repeat the same explicit-version invocation and require the
   aggregate recap to report `changed=0` and `failed=0`.
5. Ensure the cleanup trap reapplies the baseline pipeline role without the
   version override so the managed host returns to the approved compatible
   default suite on success or failure when possible.
6. Do not add version assertions for the other applications, a common-Go
   forwarding probe, missing-binary recovery, configuration branch cases,
   platform matrices, dependency-order checks, file or package assertions, or
   an end-to-end transcript run. Those behaviors are either already owned by
   standalone suites or explicitly deferred by Feature 0006.
7. Update the README validation section only as needed so it accurately
   describes the baseline composition, native validation, clean repeats, and
   one explicit Seriatim version-selection case.

### Validation

From `ansible-role-dnd-pipeline`, run:

```text
tests/integration
git diff --check
git status --short
```

Expected result: fresh dependency bootstrap and all Stage 1 checks still pass;
the suite-level Seriatim override installs `v1.4.0` as observed through native
version output; both required repeat runs report `changed=0` and `failed=0`;
cleanup restores the baseline compatible suite; and only intended Stage 2 test
and documentation changes are present.

### Completion Criteria

- One explicit non-default application revision proves the suite's version
  forwarding behavior through a native application outcome.
- Baseline composition, assembled Narratio validation, and both clean-repeat
  cases remain successful.
- Test cleanup restores the baseline suite without deleting caller content.
- Tests remain focused on composition and do not reproduce standalone-role
  coverage or freeze current defaults and implementation details.
- README test documentation remains accurate.
- No repository outside `ansible-role-dnd-pipeline` changes.

### Commit

Commit intent: `Add focused pipeline composition coverage`

## Final Validation and Handoff

After Stage 2, from `ansible-role-dnd-pipeline`, run:

```text
tests/integration
git log --oneline -2
git status --short --branch
cd ..
./scripts/status
```

Report both pipeline-role commit hashes, dependency-bootstrap evidence, static
and behavioral validation results, clean-repeat evidence, baseline restoration,
any deviation or remaining concern, and any complexity beyond dependency
metadata with the acceptance criterion that required it.

Do not edit workspace planning files, mark Feature 0006 `done`, modify asset or
dependency repositories, or push during out-of-band implementation. Completion
requires subsequent independent review.

## Progress Notes

- [x] Stage 1 complete — `ansible-role-dnd-pipeline` commit `b515968`; fresh
  dependency bootstrap and full `tests/integration` passed. No deviations.
- [x] Stage 2 complete — `ansible-role-dnd-pipeline` commit `61869d1`; fresh
  dependency bootstrap and full `tests/integration` passed. No deviations.