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 governs role composition, public variables, task structure, and the use of downstream role interfaces.
• The testing house style governs repository-local validation. Tests exercise the assembled role through native outcomes and clean repeated convergence without reproducing the standalone suites.
• The MVP roadmap fixes the supported platform, independently released application roles, Git-hosted role dependencies, source-build model, and suite/collection boundary.
• Decision 0001 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.