ansible-workspace-dnd/docs/roadmap/features/0006-pipeline-role-composition-foundation.md

# Feature 0006: Pipeline Role Composition Foundation

Status: ready

## Summary

Establish `ansible-role-dnd-pipeline` as the independently developed
suite-level role that composes the five completed application roles. The
feature provides a reproducible dependency manifest, a small suite-owned
public interface, compatible application-version selection, and the native
cross-application paths Narratio needs to find the installed tools.

This is the foundation of the complete D&D deployment, not the complete
deployment itself. Campaign data, the prompt library, operator access, secret
delivery, and opinionated D&D processing policy remain later pipeline-role
features.

## Problem or Opportunity

The five standalone application roles are implemented, tested, and
independently usable. The `ansible-role-dnd-pipeline` repository still contains
only its initial README and license, so consumers must currently discover,
install, version, and invoke every role separately and manually connect their
paths.

The suite needs one composition boundary before it can add D&D-specific
content and policy. Establishing that boundary first keeps later work focused:
subsequent features can add suite behavior without reopening how dependencies
are named, installed, invoked, or configured.

## Governing Policies

- [The Ansible house style](../../ansible.md) governs role composition, public
  variables, task structure, and the use of downstream role interfaces.
- [The testing house style](../../testing.md) governs repository-local
  validation. Tests exercise the assembled role through native outcomes and
  clean repeated convergence without reproducing the standalone suites.
- [The MVP roadmap](../mvp.md) fixes the supported platform, independently
  released application roles, Git-hosted role dependencies, source-build
  model, and suite/collection boundary.
- [Decision 0001](../../decisions/0001-minimal-module-driven-ansible.md)
  requires the smallest direct composition and rejects supplemental state or
  verification machinery without a selected requirement.

## Scope

- Turn `ansible-role-dnd-pipeline` into a conventional standalone Ansible role
  with defaults, argument specifications, metadata, dependency manifests,
  documentation, and focused integration coverage.
- Install the five standalone roles from their Git repositories under the
  canonical names `rakestraw.audita`, `rakestraw.narratio`,
  `rakestraw.notarius`, `rakestraw.seriatim`, and `rakestraw.scriptorium`.
- Pin the development dependency manifest to the reviewed commits that
  completed the five standalone roles. Preserve the existing release policy
  that replaces development commits with immutable role tags before a
  released suite or collection is published.
- Invoke all five application roles as declared role dependencies in a fixed,
  readable order.
- Select one known-compatible default application release for each component:
  Audita `v0.9.1`, Narratio `v2.0.0`, Notarius `v0.6.0`, Seriatim `v1.5.0`,
  and Scriptorium `v0.13.0`.
- Expose one suite-level dependency-management choice, Go Snap channel, and Go
  executable, then pass those values to every application role.
- Require a suite-level WhisperX transcription URL and pass it to the Narratio
  role.
- Configure Narratio with the standard binary and configuration paths managed
  by the composed roles so the orchestrator can find Seriatim, Audita,
  Notarius, and Scriptorium.
- Keep dependency metadata, defaults, argument specifications, README, and
  focused repository-local tests aligned with the public contract.

## Non-goals

- Checking out or deploying the `campaigns` repository, including its
  revision and update policy.
- Installing the `narratio-prompts` prompt library or selecting its filesystem
  layout.
- Defining PromptKit profiles, Scriptorium backends, Notarius pipelines,
  Narratio artifacts, publish outputs, or detailed Audita policy.
- Enabling Notarius in the Narratio pipeline before a usable Notarius pipeline
  definition is supplied.
- Selecting human operators or changing their group membership.
- Defining, storing, templating, or injecting secret values or environment
  files.
- Running a real recording through the end-to-end D&D workflow.
- Bundling the role into `rakestraw.dnd`; collection incorporation remains the
  next repository boundary after the standalone pipeline role is functional.
- Publishing or tagging any role or collection release.
- Duplicating every public variable from every application role behind a
  `dnd_pipeline_` alias.
- Reimplementing application installation, configuration templates, account
  creation, or platform validation in the pipeline role.
- Supporting partial component installation, per-component enable switches,
  removal, or migration from the legacy proof-of-concept role.
- Probing downstream state, inspecting task results, or validating a
  successful downstream operation during production convergence.
- Testing every application-role behavior again at the suite level.

## Target End State

A consumer first installs the pipeline role's declared Git role dependencies,
then applies `rakestraw.dnd_pipeline` with a WhisperX transcription URL. The
role invokes the five standalone roles, which install their selected sources,
binaries, native configuration, and Narratio runtime state using their own
public contracts.

The pipeline role selects the five compatible application versions as one
set. A caller may replace an individual selection through the corresponding
suite variable without editing the dependency declaration or addressing the
application role directly. Shared dependency management, Go channel, and Go
executable choices likewise flow consistently to all five roles.

Narratio's managed pipeline document names the installed Seriatim, Audita,
Notarius, and Scriptorium executable paths and the managed configuration paths
for the configured applications. Notarius remains installed but is not enabled
as a Narratio stage by this foundation feature. All other optional application
settings retain their standalone-role defaults unless a caller supplies the
underlying application role variable directly.

The pipeline role does not own or reproduce downstream templates. It composes
the roles through their public variables and lets each role converge its own
state. An immediate second pipeline-role application reports no changes.

This intentionally minimal interface is a foundation, not the pipeline role's
final policy surface. Later features will give the pipeline role concrete,
opinionated D&D defaults for Audita, Narratio, Notarius, Seriatim, and
Scriptorium through the standalone roles' existing field-specific variables.
Those values will remain overrideable through ordinary inventory precedence.
The suite will add only policy it deliberately owns, rather than copying every
upstream application default.

## Repository Ownership

- `ansible-role-dnd-pipeline` owns the dependency manifest, suite public
  interface, dependency declarations, cross-application path wiring,
  repository documentation, and focused integration suite. This is the only
  implementation repository changed by the feature.
- `ansible-role-{audita,narratio,notarius,seriatim,scriptorium}` are read-only
  dependency sources and the authorities for their respective public role
  interfaces. Their reviewed commits define the development dependency set.
- `../{audita,narratio,notarius,seriatim,scriptorium}` remain read-only
  authorities for application behavior.
- `rakestraw-ansible` is a read-only style and historical deployment-policy
  reference. Its monolithic installation and templating are not copied.
- `assets/campaigns` and `assets/narratio-prompts` are read-only authorities
  for the content and layouts that later pipeline-role features will deploy.
  Their availability in the workspace does not bring content deployment into
  this composition-foundation feature.
- `ansible-collection-dnd` remains unchanged until collection assembly is
  selected as a later feature.
- `ansible-workspace-dnd` owns this roadmap, the eventual staged plan, the
  settled MVP decisions, and aggregate status.

## Constraints and Settled Decisions

- The standalone role is named `dnd_pipeline` in the `rakestraw` Galaxy
  namespace. It will later be incorporated into the collection under the
  shorter consumer-facing name `rakestraw.dnd.pipeline`.
- Git dependencies are installed with these canonical role names:

  | Role | Repository | Development revision |
  | --- | --- | --- |
  | `rakestraw.audita` | `https://gitea.maximumdirect.net/eric/ansible-role-audita.git` | `d2d0b9d00b3b491ce7613ccfc8f686f3d1fa0896` |
  | `rakestraw.narratio` | `https://gitea.maximumdirect.net/eric/ansible-role-narratio.git` | `7feff4728a5968b6b1dd87e83add9fa1a9066b18` |
  | `rakestraw.notarius` | `https://gitea.maximumdirect.net/eric/ansible-role-notarius.git` | `cfecf37261f2595d45113235c591ee102d6f181f` |
  | `rakestraw.seriatim` | `https://gitea.maximumdirect.net/eric/ansible-role-seriatim.git` | `e08c63c0b078658bdfa2d10a2e6e1e4f9372a075` |
  | `rakestraw.scriptorium` | `https://gitea.maximumdirect.net/eric/ansible-role-scriptorium.git` | `8f47aa802a5e0c9dae9c0f43a1c70b3512b2c8b2` |

- Commit pins are appropriate for active development because the role
  repositories do not yet publish release tags. A release must use immutable
  role tags under the policy already fixed in the MVP roadmap.
- `requirements.yml` is the consumer and test bootstrap manifest for the five
  Git roles. `collections/requirements.yml` declares the pinned
  `community.general` dependency needed transitively by those roles.
- `meta/main.yml` declares the five application roles as dependencies and maps
  the suite-owned inputs to their existing public variables. It does not use
  an implementation-specific loader role.
- Dependencies execute in this order: Seriatim, Audita, Notarius,
  Scriptorium, then Narratio. The order makes the downstream tools conceptually
  available before the orchestrator, but the role does not add probes or
  runtime validation to enforce the order's postconditions.
- Repeated Git, APT, and Snap declarations inside the five roles are accepted.
  Their modules are idempotent, and consolidating them would weaken standalone
  role ownership for no selected benefit.
- The suite owns only choices that must be coordinated across applications or
  recorded as a compatible set. It does not alias the complete downstream
  interfaces. Unmapped application-specific variables retain their ordinary
  Ansible behavior and may be supplied directly by advanced callers.
- The preceding boundary governs this composition foundation only; it does not
  make the finished pipeline role policy-neutral. Later D&D-configuration
  features will supply opinionated values directly through the downstream
  roles' public variables, preserving inventory overrides without introducing
  parallel templates or complete shadow interfaces.
- The feature uses the standard application paths fixed by the MVP and current
  standalone roles:

  | Purpose | Path |
  | --- | --- |
  | Seriatim executable | `/usr/local/bin/seriatim` |
  | Audita executable | `/usr/local/bin/audita` |
  | Audita configuration | `/usr/local/etc/audita/config.yml` |
  | Notarius executable | `/usr/local/bin/notarius` |
  | Notarius configuration | `/usr/local/etc/notarius/config.yml` |
  | Scriptorium executable | `/usr/local/bin/scriptorium` |
  | Scriptorium configuration | `/usr/local/etc/scriptorium/config.yml` |

- Relocating those coordinated paths is not a requirement for this feature.
  If a real deployment needs relocation, a later feature may introduce a
  small set of coherent suite path variables rather than exposing mismatched
  per-role overrides.
- Notarius is installed because it is part of the suite, but
  `narratio_notarius_enabled` remains null until a later feature supplies a
  complete D&D Notarius pipeline and explicitly enables it.
- Tasks requiring elevated access remain owned by the downstream roles and
  use their task-level `become: true`; the pipeline role does not require
  play-level escalation.

## Fixed Public Interface

| Variable | Default | Purpose |
| --- | --- | --- |
| `dnd_pipeline_audita_version` | `v0.9.1` | Audita application revision selected for the compatible set |
| `dnd_pipeline_narratio_version` | `v2.0.0` | Narratio application revision selected for the compatible set |
| `dnd_pipeline_notarius_version` | `v0.6.0` | Notarius application revision selected for the compatible set |
| `dnd_pipeline_seriatim_version` | `v1.5.0` | Seriatim application revision selected for the compatible set |
| `dnd_pipeline_scriptorium_version` | `v0.13.0` | Scriptorium application revision selected for the compatible set |
| `dnd_pipeline_manage_build_dependencies` | `true` | Whether every application role manages Git and Go |
| `dnd_pipeline_go_snap_channel` | `1.26/stable` | Go Snap channel passed to every application role |
| `dnd_pipeline_go_binary` | `/snap/bin/go` | Go executable passed to every application role |
| `dnd_pipeline_whisperx_transcribe_url` | required | External WhisperX HTTP endpoint passed to Narratio |

Argument specifications type and document each value. The WhisperX URL is
required because neither Narratio nor the suite has a valid universal
endpoint. The suite version variables select application source revisions;
they are separate from the Git revisions pinning the Ansible role
dependencies.

The role intentionally has no raw map of arbitrary downstream variables and
no parallel configuration template. Application-specific choices that are not
part of this interface continue to use the standalone roles' documented
variables.

## Simplest Viable Implementation

The implementation is primarily metadata:

1. Define the nine suite variables above in defaults and argument
   specifications, omitting a default for the required WhisperX URL.
2. Declare the five named role dependencies in `meta/main.yml`, in the settled
   order, and pass each dependency its selected version plus the common
   dependency-management and Go values.
3. Pass the WhisperX URL and standard downstream binary/configuration paths to
   the Narratio dependency.
4. Add the Git-role and collection dependency manifests used by consumers and
   tests.
5. Document installation, variables, dependency bootstrap, the boundary with
   application-specific variables, and an ordinary playbook example.
6. Add a focused integration driver that installs dependencies in an isolated
   roles path, applies the real pipeline role, observes the assembled native
   application outcome, and requires immediate clean repeated convergence.

No custom tasks are required merely to prove that role dependencies ran. The
pipeline role should not inspect downstream binaries, files, packages,
checkouts, or registered task results during production convergence. It should
not copy downstream defaults into facts or introduce an abstraction around
ordinary role dependency metadata.

## Rationale and Alternatives

Using declared role dependencies reflects the actual ownership boundary: each
application role remains responsible for its own installation and native
configuration, while the pipeline role selects and connects them. Rewriting
or including copies of downstream tasks would couple the suite to their
implementations and discard the independent-release model already selected.

A small suite-prefixed interface makes coordinated decisions explicit without
creating five complete shadow interfaces. Version selection belongs here
because the suite promises a compatible application set. Build dependency and
Go choices are common because all five roles use the same source-build model.
The WhisperX endpoint belongs here because it is required to construct the
Narratio configuration and is deployment-specific.

The standard downstream paths are suite policy rather than configurable inputs
for this first composition feature. Exposing every source, binary, and
configuration path would add aliases and cross-variable consistency rules
without a demonstrated consumer need. Advanced callers can still use
unmapped application variables where they do not conflict with coordinated
suite policy.

Keeping content, operators, secrets, and D&D processing definitions out of
this feature avoids combining several unsettled interfaces with dependency
composition. Those features can build on a running, natively valid application
suite and receive focused roadmaps of their own.

## Acceptance Criteria

### Required Role Behavior

- A documented bootstrap command installs all five standalone roles from
  `requirements.yml` under their canonical names and installs the pinned
  collection dependency.
- Applying the pipeline role with a valid
  `dnd_pipeline_whisperx_transcribe_url` invokes all five standalone roles and
  reaches their ordinary managed end state on Ubuntu 26.04 `amd64` or `arm64`.
- The default suite selections install Audita `v0.9.1`, Narratio `v2.0.0`,
  Notarius `v0.6.0`, Seriatim `v1.5.0`, and Scriptorium `v0.13.0` as one
  compatible development set.
- A caller can change each application revision through its corresponding
  `dnd_pipeline_*_version` variable.
- The common dependency-management switch, Go channel, and Go executable are
  passed to all five roles without duplicating their installation tasks.
- Narratio receives the required WhisperX URL and the standard executable and
  configuration paths for all four downstream applications.
- Notarius is installed but is not enabled in the Narratio pipeline by this
  feature.
- An immediate repeated role application with unchanged inputs reports no
  changes.
- The role contains no copied application tasks or templates, downstream state
  probes, role-private state, custom dependency loader, or production
  self-validation.
- Defaults, argument specifications, dependency metadata, manifests, and
  README remain aligned with the fixed interface.
- No implementation repository other than `ansible-role-dnd-pipeline` is
  modified.

### Required Validation

- YAML syntax checking and production-profile ansible-lint pass for the role
  and its test playbooks.
- The integration driver installs the five Git dependencies into a fresh,
  isolated role path from the same manifest documented for consumers.
- One baseline application runs the real pipeline role with a test WhisperX
  URL, exercises each installed application through a practical native smoke
  or configuration command, validates Narratio's assembled configuration
  natively, and is followed immediately by a role application reporting no
  changes.
- One representative application explicitly selects Seriatim `v1.4.0`
  through `dnd_pipeline_seriatim_version` and observes that selection through
  Seriatim's native version interface. This proves suite forwarding without
  asserting that any release remains the default or promising that arbitrary
  component combinations are compatible.
- Tests do not repeat the standalone roles' missing-binary, custom-Go,
  template-branch, file-metadata, package, Git, or platform matrices.
- Tests do not assert dependency task order, exact current default values,
  role-variable counts, individual task results, or trusted-module
  postconditions.

## Dependencies and Follow-up Work

The five application-role implementations and public interfaces are complete.
The managed host must be able to reach their application source repositories,
Ubuntu Snap infrastructure, Go module sources, and the caller-supplied
WhisperX service.

After this foundation is implemented and reviewed, later pipeline-role
features must settle and implement:

- prompt-library checkout and Scriptorium integration;
- campaign checkout, revision policy, and deployment;
- D&D-specific Audita, Notarius, Scriptorium, and Narratio policy;
- operator-selection and group-membership behavior;
- pipeline-wide secret delivery; and
- an end-to-end pipeline validation scenario.

Collection assembly remains a separate feature after the standalone pipeline
role has a stable contract. Before any released dependency manifest or
collection is published, the standalone roles must receive immutable release
tags and the development commit pins must be replaced by those tags.

The D&D-policy follow-up must inspect the asset repositories and current
application contracts, select concrete suite defaults for all five
applications, and document how callers override them. It should reuse the
standalone roles' field-specific variables rather than adding pipeline-owned
configuration templates or duplicating every downstream setting behind a new
alias.

## Potential Future Hardening

- Verify signed role or application releases.
- Apply an allowlist to dependency or application repository origins.
- Add policy for hosts whose installed dependency roles differ from the
  manifest used by the controller.