eric/ansible-workspace-dnd
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Plan the pipeline role composition foundation

Browse Source
This commit is contained in:
Eric Rakestraw
2026-09-10 14:06:00 +00:00
parent 8e34f56f81
commit a84a6383ec
7 changed files with 804 additions and 22 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
.gitignore vendored
View File

@@ -7,6 +7,8 @@
/ansible-role-scriptorium/ /ansible-role-scriptorium/
/ansible-role-seriatim/ /ansible-role-seriatim/
/rakestraw-ansible/ /rakestraw-ansible/
/assets/campaigns/
/assets/narratio-prompts/
# Local tool state. # Local tool state.
/.codebase-memory/ /.codebase-memory/

7
docs/orientation.md
View File

@@ -10,6 +10,10 @@ Repositories inside this directory:
suite-level role exposed by the collection as `rakestraw.dnd.pipeline`. suite-level role exposed by the collection as `rakestraw.dnd.pipeline`.
- `ansible-role-{narratio,notarius,audita,seriatim,scriptorium}`: standalone - `ansible-role-{narratio,notarius,audita,seriatim,scriptorium}`: standalone
application roles. application roles.
- `assets/campaigns`: D&D campaign registry content deployed by the pipeline
role.
- `assets/narratio-prompts`: PromptKit-compatible prompts and schemas deployed
for Scriptorium by the pipeline role.
- `rakestraw-ansible`: working deployment repository containing the - `rakestraw-ansible`: working deployment repository containing the
`pipeline_dnd` proof of concept; treat it as read-only reference unless the `pipeline_dnd` proof of concept; treat it as read-only reference unless the
task explicitly includes it. task explicitly includes it.
@@ -18,7 +22,6 @@ Relevant upstream repositories are siblings of this directory:
- `../{narratio,notarius,audita,seriatim,scriptorium}`: application source and - `../{narratio,notarius,audita,seriatim,scriptorium}`: application source and
authoritative application contracts. authoritative application contracts.
- `../narratio-prompts`: pipeline prompt-library content.
Use [the workspace inventory](../workspace.yml) as the complete Use [the workspace inventory](../workspace.yml) as the complete
machine-readable inventory of paths and remotes. machine-readable inventory of paths and remotes.
@@ -44,4 +47,6 @@ machine-readable inventory of paths and remotes.
active staged plan or, when no plan is approved, a pending-plan notice. active staged plan or, when no plan is approved, a pending-plan notice.
- Application repositories: CLI, configuration, build, and integration - Application repositories: CLI, configuration, build, and integration
contracts. contracts.
- Asset repositories: authoritative campaign and prompt-library content and
layout.
- Individual Ansible repositories: implementation and repository-local tests. - Individual Ansible repositories: implementation and repository-local tests.

382
docs/roadmap/features/0006-pipeline-role-composition-foundation.md Normal file
View File

@@ -0,0 +1,382 @@
# 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.

385
docs/roadmap/implementation.md
View File

@@ -1,14 +1,379 @@
# Implementation Plan # Implementation Plan 0006: Establish Pipeline Role Composition
Status: pending Status: ready
No implementation plan is currently active. Feature 0005 was implemented in Target executor: GPT-5.6-Terra
`ansible-role-narratio` commits `3be78d8` and `0e8ad9f`, independently
reviewed, and finalized by remediation commit `7feff47`.
Its durable scope and rationale remain in Feature roadmap:
[the Feature 0005 roadmap](features/0005-narratio-source-installation-and-configuration.md), [Feature 0006: Pipeline Role Composition Foundation](features/0006-pipeline-role-composition-foundation.md)
and its final review record remains in [the remediation record](remediation.md).
Select and approve the next unit of work before replacing this notice with a Active plan location: `docs/roadmap/implementation.md`
new staged implementation plan.
## 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
- No stages completed.

23
docs/roadmap/mvp.md
View File

@@ -108,6 +108,15 @@ role will manage the native configuration needed to connect to it.
cross-application configuration, D&D campaign deployment, prompt-library cross-application configuration, D&D campaign deployment, prompt-library
deployment, operator access, the pipeline-wide secret-delivery policy, and deployment, operator access, the pipeline-wide secret-delivery policy, and
end-to-end validation. end-to-end validation.
- Unlike the generic standalone roles, the pipeline role deliberately supplies
opinionated, D&D-specific defaults for all five applications. It expresses
that policy through the standalone roles' existing field-specific variables,
keeps those values overrideable through ordinary inventory precedence, and
does not duplicate the application roles' templates or convergence logic.
- Pipeline defaults represent policy deliberately selected for the D&D suite;
they do not mirror every upstream application default. Settings for which the
suite has selected no policy remain under the application or caller's
control.
- The pipeline role uses the Git-hosted standalone application roles as - The pipeline role uses the Git-hosted standalone application roles as
dependencies. This is an intentional choice for the controlled project dependencies. This is an intentional choice for the controlled project
environment despite the additional repository and dependency structure and environment despite the additional repository and dependency structure and
@@ -116,6 +125,18 @@ role will manage the native configuration needed to connect to it.
that installs both the collection and its standalone role dependencies; a that installs both the collection and its standalone role dependencies; a
plain collection installation is not assumed to resolve arbitrary Git role plain collection installation is not assumed to resolve arbitrary Git role
dependencies by itself. dependencies by itself.
- The standalone application roles use the canonical installed names
`rakestraw.audita`, `rakestraw.narratio`, `rakestraw.notarius`,
`rakestraw.seriatim`, and `rakestraw.scriptorium`.
- The pipeline role supplies a root `requirements.yml` bootstrap manifest for
those Git-hosted roles and a collection requirements manifest for shared
collection dependencies. During active development, the Git roles are
pinned to reviewed commits; released manifests replace those commits with
immutable role release tags.
- The pipeline role composes the five roles through ordinary Ansible role
dependency metadata. It exposes suite-prefixed variables for the small set
of values the suite must coordinate, and does not duplicate every downstream
role variable behind a parallel alias.
This design keeps repository ownership and change blast radius aligned with This design keeps repository ownership and change blast radius aligned with
the independently released applications while retaining a single opinionated the independently released applications while retaining a single opinionated
@@ -267,10 +288,10 @@ remain to be designed.
The following areas require investigation and decisions before implementation: The following areas require investigation and decisions before implementation:
- Standalone role Galaxy names and the dependency-manifest/bootstrap layout
- The mechanism used to incorporate the independently developed pipeline role - The mechanism used to incorporate the independently developed pipeline role
into collection releases into collection releases
- The prompt-library destination and its integration with Scriptorium - The prompt-library destination and its integration with Scriptorium
- The campaign repository's checkout revision and deployment/update policy
- Secret injection and storage - Secret injection and storage
- Suite-level operator-selection variables - Suite-level operator-selection variables
- Upgrade, downgrade, and removal behavior - Upgrade, downgrade, and removal behavior

9
docs/status.md
View File

@@ -1,10 +1,10 @@
# Workspace Status # Workspace Status
Last updated: 2026-09-09 Last updated: 2026-09-10
Current milestone: Select the next MVP unit of work Current milestone: M1-03 suite-level pipeline role
Current focus: Select the next unit of work. Current focus: Review the staged Feature 0006 implementation plan.
| ID | Deliverable | Owner | State | Evidence or next step | | ID | Deliverable | Owner | State | Evidence or next step |
| --- | --- | --- | --- | --- | | --- | --- | --- | --- | --- |
@@ -15,13 +15,14 @@ Current focus: Select the next unit of work.
| M0-05 | Suite-level role repository | ansible-role-dnd-pipeline | done | Repository created and added to `workspace.yml` | | M0-05 | Suite-level role repository | ansible-role-dnd-pipeline | done | Repository created and added to `workspace.yml` |
| M1-01 | Remaining MVP design decisions | workspace | done | Feature 0003 roadmap fixes the Notarius configuration interface | | M1-01 | Remaining MVP design decisions | workspace | done | Feature 0003 roadmap fixes the Notarius configuration interface |
| M1-02 | Standalone application roles | role repositories | done | All five standalone roles implemented and independently reviewed | | M1-02 | Standalone application roles | role repositories | done | All five standalone roles implemented and independently reviewed |
| M1-03 | Suite-level pipeline role | ansible-role-dnd-pipeline | proposed | Begin after standalone role interfaces stabilize | | M1-03 | Suite-level pipeline role | ansible-role-dnd-pipeline | in_progress | Feature 0006 defines the dependency-composition foundation |
| M1-04 | Collection assembly | ansible-collection-dnd | proposed | Select and implement the pipeline-role incorporation mechanism | | M1-04 | Collection assembly | ansible-collection-dnd | proposed | Select and implement the pipeline-role incorporation mechanism |
| F0001 | Install Seriatim from pinned source | ansible-role-seriatim | done | Implementation, integration coverage, and final remediation completed through `fb8dc41` | | F0001 | Install Seriatim from pinned source | ansible-role-seriatim | done | Implementation, integration coverage, and final remediation completed through `fb8dc41` |
| F0002 | Install and configure Audita | ansible-role-audita | done | Field-specific configuration completed in `e61f02f` and `847c4c3`; full suite passed | | F0002 | Install and configure Audita | ansible-role-audita | done | Field-specific configuration completed in `e61f02f` and `847c4c3`; full suite passed |
| F0003 | Install and configure Notarius | ansible-role-notarius | done | Implemented and validated through remediation commit `eb4f511` | | F0003 | Install and configure Notarius | ansible-role-notarius | done | Implemented and validated through remediation commit `eb4f511` |
| F0004 | Install and configure Scriptorium | ansible-role-scriptorium | done | Implemented and validated through remediation commit `8f47aa8` | | F0004 | Install and configure Scriptorium | ansible-role-scriptorium | done | Implemented and validated through remediation commit `8f47aa8` |
| F0005 | Install and configure Narratio | ansible-role-narratio | done | Implemented and validated through remediation commit `7feff47` | | F0005 | Install and configure Narratio | ansible-role-narratio | done | Implemented and validated through remediation commit `7feff47` |
| F0006 | Establish pipeline-role composition | ansible-role-dnd-pipeline | ready | Execute `docs/roadmap/implementation.md` after its review and dependency publication |
| A0001 | Audit completed standalone-role test suites | workspace and standalone roles | done | Findings recorded in `docs/roadmap/test-suite-audit-findings.md` | | A0001 | Audit completed standalone-role test suites | workspace and standalone roles | done | Findings recorded in `docs/roadmap/test-suite-audit-findings.md` |
| R0001 | Simplify completed standalone-role test suites | workspace and standalone roles | done | Role commits `e08c63c`, `d2d0b9d`, and `cfecf37` passed implementation and independent review | | R0001 | Simplify completed standalone-role test suites | workspace and standalone roles | done | Role commits `e08c63c`, `d2d0b9d`, and `cfecf37` passed implementation and independent review |

18
workspace.yml
View File

@@ -51,6 +51,18 @@ repositories:
category: reference category: reference
purpose: Existing deployment repository and pipeline_dnd proof of concept purpose: Existing deployment repository and pipeline_dnd proof of concept
- name: campaigns
path: assets/campaigns
remote: https://gitea.maximumdirect.net/eric/campaigns.git
category: content
purpose: D&D campaign registry content deployed by the pipeline role
- name: narratio-prompts
path: assets/narratio-prompts
remote: https://gitea.maximumdirect.net/eric/narratio-prompts.git
category: content
purpose: PromptKit-compatible prompts and schemas deployed for Scriptorium
- name: narratio - name: narratio
path: ../narratio path: ../narratio
remote: https://gitea.maximumdirect.net/eric/narratio.git remote: https://gitea.maximumdirect.net/eric/narratio.git
@@ -80,9 +92,3 @@ repositories:
remote: https://gitea.maximumdirect.net/eric/scriptorium.git remote: https://gitea.maximumdirect.net/eric/scriptorium.git
category: application category: application
purpose: Scriptorium source and authoritative application contracts purpose: Scriptorium source and authoritative application contracts
- name: narratio-prompts
path: ../narratio-prompts
remote: https://gitea.maximumdirect.net/eric/narratio-prompts.git
category: content
purpose: PromptKit-compatible pipeline prompt library