From a84a6383ec75dd29458d15f531ddda6b95df7136 Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Thu, 10 Sep 2026 14:06:00 +0000 Subject: [PATCH] Plan the pipeline role composition foundation --- .gitignore | 2 + docs/orientation.md | 7 +- ...06-pipeline-role-composition-foundation.md | 382 +++++++++++++++++ docs/roadmap/implementation.md | 385 +++++++++++++++++- docs/roadmap/mvp.md | 23 +- docs/status.md | 9 +- workspace.yml | 18 +- 7 files changed, 804 insertions(+), 22 deletions(-) create mode 100644 docs/roadmap/features/0006-pipeline-role-composition-foundation.md diff --git a/.gitignore b/.gitignore index d23c505..f5452a0 100644 --- a/.gitignore +++ b/.gitignore @@ -7,6 +7,8 @@ /ansible-role-scriptorium/ /ansible-role-seriatim/ /rakestraw-ansible/ +/assets/campaigns/ +/assets/narratio-prompts/ # Local tool state. /.codebase-memory/ diff --git a/docs/orientation.md b/docs/orientation.md index 5cf0718..4f39658 100644 --- a/docs/orientation.md +++ b/docs/orientation.md @@ -10,6 +10,10 @@ Repositories inside this directory: suite-level role exposed by the collection as `rakestraw.dnd.pipeline`. - `ansible-role-{narratio,notarius,audita,seriatim,scriptorium}`: standalone 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 `pipeline_dnd` proof of concept; treat it as read-only reference unless the task explicitly includes it. @@ -18,7 +22,6 @@ Relevant upstream repositories are siblings of this directory: - `../{narratio,notarius,audita,seriatim,scriptorium}`: application source and authoritative application contracts. -- `../narratio-prompts`: pipeline prompt-library content. Use [the workspace inventory](../workspace.yml) as the complete 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. - Application repositories: CLI, configuration, build, and integration contracts. +- Asset repositories: authoritative campaign and prompt-library content and + layout. - Individual Ansible repositories: implementation and repository-local tests. diff --git a/docs/roadmap/features/0006-pipeline-role-composition-foundation.md b/docs/roadmap/features/0006-pipeline-role-composition-foundation.md new file mode 100644 index 0000000..7f0d63f --- /dev/null +++ b/docs/roadmap/features/0006-pipeline-role-composition-foundation.md @@ -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. diff --git a/docs/roadmap/implementation.md b/docs/roadmap/implementation.md index f97dfeb..16417ee 100644 --- a/docs/roadmap/implementation.md +++ b/docs/roadmap/implementation.md @@ -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 -`ansible-role-narratio` commits `3be78d8` and `0e8ad9f`, independently -reviewed, and finalized by remediation commit `7feff47`. +Target executor: GPT-5.6-Terra -Its durable scope and rationale remain in -[the Feature 0005 roadmap](features/0005-narratio-source-installation-and-configuration.md), -and its final review record remains in [the remediation record](remediation.md). +Feature roadmap: +[Feature 0006: Pipeline Role Composition Foundation](features/0006-pipeline-role-composition-foundation.md) -Select and approve the next unit of work before replacing this notice with a -new staged implementation plan. +Active plan location: `docs/roadmap/implementation.md` + +## Objective + +Implement the independently developed `rakestraw.dnd_pipeline` role defined by +Feature 0006. Compose the five completed standalone application roles through +ordinary dependency metadata, install them reproducibly from a Git dependency +manifest, expose the approved suite-level variables, and wire Narratio to the +standard downstream application paths. + +The feature roadmap remains authoritative for scope, rationale, target end +state, public variables, dependency revisions, and acceptance criteria. + +## Execution Rules + +- Execute Stage 1 and Stage 2 in numeric order. +- Immediately before each stage, read every document in that stage's Required + Policy Review, then confirm its preconditions and the owning repository's + working-tree state. +- Modify only `ansible-role-dnd-pipeline`. Treat the workspace control + repository, standalone application roles, application sources, asset + repositories, collection, and proof of concept as read-only during + out-of-band implementation. +- Preserve unrelated changes. Stop if the pipeline-role repository is + unexpectedly dirty at a stage boundary. +- Use ordinary role dependency metadata. Do not copy downstream tasks or + templates, add a loader role, or surround role invocation with state probes + or result inspection. +- Define only the nine suite-owned variables fixed by the feature roadmap. Do + not alias the complete standalone interfaces or add raw downstream-variable + maps, path overrides, component switches, content settings, operator + settings, or secret settings. +- Pass the common build-dependency switch, Go channel, and Go executable to + all five dependencies. Pass each selected application version only to its + corresponding dependency. +- Pass the required WhisperX URL and the roadmap's fixed downstream binary and + configuration paths to Narratio. Install Notarius without enabling it in + Narratio. +- Trust each dependency to establish its documented state. Do not test or + reimplement APT, Snap, Git, file, template, account, or build behavior in + production pipeline-role logic. +- Keep behavioral tests at the composition boundary. Prove that the assembled + applications are usable, Narratio accepts the assembled configuration, a + suite version override reaches its application role, and an immediate + repeat is clean. Do not rerun the standalone roles' behavior matrices. +- Do not assert current default versions, exact dependency pins, task order, + task traces, file metadata, package state, checkout state, or other trusted + module postconditions in behavioral tests. +- Use fully qualified collection names. Run each stage's validation before + committing it, and do not begin Stage 2 if Stage 1 fails validation. +- Commit each completed stage with its specified plain-English message. Do not + push during out-of-band implementation. +- Test cleanup may reapply the baseline pipeline role and remove only the + integration driver's private temporary directory. Do not delete campaign, + prompt, runtime, or other caller content. + +## Starting State and Preconditions + +- `ansible-role-dnd-pipeline` is clean on `main` at + `1a66d177cdd5d948c94c291b718c779dbbfd1f91`, tracking `origin/main` without + divergence. +- This plan, the ready Feature 0006 roadmap, and the corresponding workspace + documentation and status updates are committed before out-of-band execution + begins. +- The exact dependency commits fixed by Feature 0006 are reachable from their + declared remote repositories before Stage 1 begins. At plan preparation, + all five commits are local-only and must be pushed: + + | Dependency | Required commit | Current `origin/main` | + | --- | --- | --- | + | Audita role | `d2d0b9d00b3b491ce7613ccfc8f686f3d1fa0896` | `3a8c21f0e61c62dbb603ba0f3fdfab1fd3b1de09` | + | Narratio role | `7feff4728a5968b6b1dd87e83add9fa1a9066b18` | `b97a317f9ec9f15675e81c65af3f4a1ad8176886` | + | Notarius role | `cfecf37261f2595d45113235c591ee102d6f181f` | `f8a3e113ef4975b2c2745cb3f08500b2206c3f21` | + | Seriatim role | `e08c63c0b078658bdfa2d10a2e6e1e4f9372a075` | `fb8dc4100c029e25c4ab507645d75df0d739fe66` | + | Scriptorium role | `8f47aa802a5e0c9dae9c0f43a1c70b3512b2c8b2` | `2cd69a4b2ead23b44f1aab51fd1b1f14ac326af2` | + +- The local controller and managed-host proxy are Ubuntu 26.04 `x86_64`, with + gathered facts and passwordless task-level privilege escalation available. +- Workspace tooling is available in `../.venv/bin` from the pipeline-role + repository: Ansible Core 2.21.3 and ansible-lint 26.8.0. +- `community.general` 13.3.0 and Go Snap channel `1.26/stable` are available. +- The five application binaries and their current managed state may already + exist from standalone-role development. The integration suite must converge + from that state without treating prior installation as test evidence or + deleting unrelated content. +- Seriatim tag `v1.4.0` remains available for the explicit suite-level version + override case and reports `seriatim version v1.4.0` through its native + version command. +- Narratio can validate the baseline assembled pipeline without contacting the + syntactically valid test WhisperX URL. Notarius remains disabled, and no + campaign, prompt library, credentials, or session input is required for + configuration validation. + +## Repository Scope + +Repository that changes: + +- `ansible-role-dnd-pipeline`: public interface, dependency metadata and + manifests, documentation, and focused repository-local integration suite. + +Repositories that may be inspected but must remain unchanged: + +- `ansible-workspace-dnd`: authoritative roadmap, plan, policies, inventory, + and status. +- `ansible-role-{audita,narratio,notarius,seriatim,scriptorium}`: authoritative + dependency interfaces and reviewed implementations. +- `../{audita,narratio,notarius,seriatim,scriptorium}`: authoritative native + application contracts. +- `assets/campaigns` and `assets/narratio-prompts`: future content inputs, + outside this feature. +- `ansible-collection-dnd`: future collection assembly target. +- `rakestraw-ansible`: historical style and deployment reference. +- Every other repository in `workspace.yml`. + +## Stage 1: Compose the Five Application Roles + +### Objective + +Create a complete standalone pipeline role whose metadata installs the five +applications with the approved suite interface, dependency pins, and +cross-application path wiring, then demonstrate baseline native usability and +clean repeated convergence. + +### Required Policy Review + +Before beginning this stage, read: + +- `AGENTS.md` +- `docs/orientation.md` +- `docs/conventions.md` +- `docs/ansible.md` +- `docs/testing.md` + +### Preconditions + +- The starting revision and tool versions above remain valid. +- `ansible-role-dnd-pipeline` has no uncommitted changes. +- The workspace planning commit containing this plan exists. +- Every required dependency commit is fetchable from its roadmap-declared Git + URL. Confirm this through a fresh `ansible-galaxy role install`; do not + substitute local role directories for the remote dependency test. +- Existing managed application and runtime paths contain no test-created + corruption that prevents ordinary role convergence. Preserve any campaign, + prompt, session, or other caller content already present. + +### Owning Repository + +`ansible-role-dnd-pipeline` + +### Required Changes + +1. Retain the existing license and create the conventional role structure: + `defaults/main.yml`, `meta/main.yml`, `meta/argument_specs.yml`, + `tasks/main.yml`, `requirements.yml`, `collections/requirements.yml`, + `ansible.cfg`, and focused files under `tests/`. +2. Declare role name `dnd_pipeline`, namespace `rakestraw`, author Eric + Rakestraw, license `CC0-1.0`, Ubuntu 26.04 support, Ansible Core 2.18 or + newer, the canonical issue tracker, and appropriate pipeline tags. +3. Define exactly the Feature 0006 Fixed Public Interface in defaults and + matching argument specifications: + - default the five `dnd_pipeline_*_version` variables to their roadmap + releases; + - default `dnd_pipeline_manage_build_dependencies` to `true`; + - default `dnd_pipeline_go_snap_channel` to `1.26/stable`; + - default `dnd_pipeline_go_binary` to `/snap/bin/go`; and + - require `dnd_pipeline_whisperx_transcribe_url` as a string without + inventing a default. +4. Add a root `requirements.yml` containing the five Git role dependencies in + the roadmap's canonical names and at the exact reviewed commits. Add + `collections/requirements.yml` pinning `community.general` to `13.3.0`. +5. Declare these dependencies in `meta/main.yml`, in this order: Seriatim, + Audita, Notarius, Scriptorium, Narratio. Map each suite version to the + corresponding application `*_version` variable and map the common + dependency-management, Go channel, and Go executable values to all five + roles. +6. In the Narratio dependency declaration, additionally pass: + - `dnd_pipeline_whisperx_transcribe_url` as + `narratio_whisperx_transcribe_url`; + - `/usr/local/bin/seriatim` as `narratio_seriatim_binary`; + - `/usr/local/bin/audita` and `/usr/local/etc/audita/config.yml` as the + corresponding Narratio Audita values; + - `/usr/local/bin/notarius` and `/usr/local/etc/notarius/config.yml` as the + corresponding Narratio Notarius path values; and + - `/usr/local/bin/scriptorium` and + `/usr/local/etc/scriptorium/config.yml` as the corresponding Narratio + Scriptorium values. + Do not set `narratio_notarius_enabled` or supply D&D processing policy. +7. Keep `tasks/main.yml` empty except for its YAML document marker if Ansible + requires the file. Dependency metadata is the complete production + implementation for this feature; do not add wrapper tasks, assertions, + probes, facts, handlers, or post-dependency validation. +8. Replace the placeholder README with concise documentation covering the + supported platform, dependency bootstrap commands, canonical installed + role names, all nine suite variables, required WhisperX URL, compatible + default application set, common dependency opt-out and Go behavior, + standard cross-application paths, direct use of unmapped standalone role + variables, Notarius's disabled state, later collection name, deferred + content/operators/secrets, and actual integration-test behavior. +9. Add a baseline local integration harness with one executable + `tests/integration` entry point. Use strict shell options, + repository-relative paths, a mode-`0700` private temporary directory, an + isolated roles path, an isolated collections path, syntax checking, + production-profile ansible-lint, and best-effort cleanup that reapplies the + baseline role and removes only the private temporary directory. +10. Install `community.general` from `collections/requirements.yml` and install + all five roles from `requirements.yml` into the fresh isolated roles path. + Resolve the pipeline role itself from the working repository without + replacing any dependency with a workspace sibling checkout. +11. Apply the pipeline role without play-level escalation and supply only a + syntactically valid local test value for + `dnd_pipeline_whisperx_transcribe_url`. Exercise the installed applications + with concise native smoke or configuration commands without asserting + their current default versions. Validate the assembled Narratio pipeline + natively as the `narratio` application account without contacting + WhisperX. +12. Immediately apply the identical baseline invocation again and require the + aggregate recap to report `changed=0` and `failed=0`. +13. Do not assert downstream file existence, ownership, permissions, package + state, Git state, dependency order, exact default versions, complete + configuration content, or individual task results. Successful native use + and clean repeated convergence are the stage's behavioral evidence. + +### Validation + +From `ansible-role-dnd-pipeline`, run: + +```text +tests/integration +git diff --check +git status --short +``` + +Expected result: both manifests install into fresh isolated paths; syntax and +lint pass; the real pipeline role composes all five dependencies; their native +smoke/configuration commands and Narratio's assembled configuration validation +succeed; the immediate repeat reports `changed=0` and `failed=0`; cleanup +leaves the baseline suite usable; and only intended Stage 1 files are modified. + +### Completion Criteria + +- Defaults and argument specifications implement exactly the nine-variable + suite interface, with only the WhisperX URL required. +- Git and collection manifests use the exact approved names, URLs, revisions, + and collection version. +- Dependency metadata contains the five roles in the settled order and passes + only the approved coordinated values and Narratio path wiring. +- The production role contains no duplicated downstream implementation or + additional task machinery. +- README and metadata accurately describe the role, bootstrap procedure, + public interface, composition boundary, and current non-goals. +- Fresh dependency bootstrap, static validation, baseline native behavior, and + immediate clean convergence pass. +- No repository outside `ansible-role-dnd-pipeline` changes. + +### Commit + +Commit intent: `Compose the D&D pipeline roles` + +## Stage 2: Add Focused Composition Coverage + +### Objective + +Prove through one representative override that suite-owned version selection +reaches the appropriate application role, while retaining the lean baseline +composition test and restoring the approved default suite afterward. + +### Required Policy Review + +Before beginning this stage, read: + +- `AGENTS.md` +- `docs/orientation.md` +- `docs/conventions.md` +- `docs/ansible.md` +- `docs/testing.md` + +### Preconditions + +- Stage 1 is committed and `ansible-role-dnd-pipeline` is otherwise clean. +- Stage 1's complete integration entry point passes. +- The isolated dependency bootstrap still resolves all five exact Git commits. +- Applying the baseline pipeline inputs can restore the compatible default + suite after the representative version override. + +### Owning Repository + +`ansible-role-dnd-pipeline` + +### Required Changes + +1. Retain the Stage 1 baseline native smoke/configuration checks and immediate + clean repeat. Extend the existing integration entry point rather than + introducing another framework, scenario tree, or cross-repository helper. +2. Add one representative convergence that explicitly sets + `dnd_pipeline_seriatim_version: v1.4.0` while supplying the same test + WhisperX URL. +3. Execute Seriatim's native version interface and require + `seriatim version v1.4.0`. This proves suite-variable forwarding; do not + inspect role defaults, dependency metadata, the source checkout, or task + results to establish it. +4. Immediately repeat the same explicit-version invocation and require the + aggregate recap to report `changed=0` and `failed=0`. +5. Ensure the cleanup trap reapplies the baseline pipeline role without the + version override so the managed host returns to the approved compatible + default suite on success or failure when possible. +6. Do not add version assertions for the other applications, a common-Go + forwarding probe, missing-binary recovery, configuration branch cases, + platform matrices, dependency-order checks, file or package assertions, or + an end-to-end transcript run. Those behaviors are either already owned by + standalone suites or explicitly deferred by Feature 0006. +7. Update the README validation section only as needed so it accurately + describes the baseline composition, native validation, clean repeats, and + one explicit Seriatim version-selection case. + +### Validation + +From `ansible-role-dnd-pipeline`, run: + +```text +tests/integration +git diff --check +git status --short +``` + +Expected result: fresh dependency bootstrap and all Stage 1 checks still pass; +the suite-level Seriatim override installs `v1.4.0` as observed through native +version output; both required repeat runs report `changed=0` and `failed=0`; +cleanup restores the baseline compatible suite; and only intended Stage 2 test +and documentation changes are present. + +### Completion Criteria + +- One explicit non-default application revision proves the suite's version + forwarding behavior through a native application outcome. +- Baseline composition, assembled Narratio validation, and both clean-repeat + cases remain successful. +- Test cleanup restores the baseline suite without deleting caller content. +- Tests remain focused on composition and do not reproduce standalone-role + coverage or freeze current defaults and implementation details. +- README test documentation remains accurate. +- No repository outside `ansible-role-dnd-pipeline` changes. + +### Commit + +Commit intent: `Add focused pipeline composition coverage` + +## Final Validation and Handoff + +After Stage 2, from `ansible-role-dnd-pipeline`, run: + +```text +tests/integration +git log --oneline -2 +git status --short --branch +cd .. +./scripts/status +``` + +Report both pipeline-role commit hashes, dependency-bootstrap evidence, static +and behavioral validation results, clean-repeat evidence, baseline restoration, +any deviation or remaining concern, and any complexity beyond dependency +metadata with the acceptance criterion that required it. + +Do not edit workspace planning files, mark Feature 0006 `done`, modify asset or +dependency repositories, or push during out-of-band implementation. Completion +requires subsequent independent review. + +## Progress Notes + +- No stages completed. diff --git a/docs/roadmap/mvp.md b/docs/roadmap/mvp.md index e3e7056..f88f7a8 100644 --- a/docs/roadmap/mvp.md +++ b/docs/roadmap/mvp.md @@ -108,6 +108,15 @@ role will manage the native configuration needed to connect to it. cross-application configuration, D&D campaign deployment, prompt-library deployment, operator access, the pipeline-wide secret-delivery policy, and 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 dependencies. This is an intentional choice for the controlled project 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 plain collection installation is not assumed to resolve arbitrary Git role 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 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: -- Standalone role Galaxy names and the dependency-manifest/bootstrap layout - The mechanism used to incorporate the independently developed pipeline role into collection releases - The prompt-library destination and its integration with Scriptorium +- The campaign repository's checkout revision and deployment/update policy - Secret injection and storage - Suite-level operator-selection variables - Upgrade, downgrade, and removal behavior diff --git a/docs/status.md b/docs/status.md index c992aed..d7aa7e4 100644 --- a/docs/status.md +++ b/docs/status.md @@ -1,10 +1,10 @@ # 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 | | --- | --- | --- | --- | --- | @@ -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` | | 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-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 | | 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 | | 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` | | 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` | | R0001 | Simplify completed standalone-role test suites | workspace and standalone roles | done | Role commits `e08c63c`, `d2d0b9d`, and `cfecf37` passed implementation and independent review | diff --git a/workspace.yml b/workspace.yml index 899b2a9..4f00b45 100644 --- a/workspace.yml +++ b/workspace.yml @@ -51,6 +51,18 @@ repositories: category: reference 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 path: ../narratio remote: https://gitea.maximumdirect.net/eric/narratio.git @@ -80,9 +92,3 @@ repositories: remote: https://gitea.maximumdirect.net/eric/scriptorium.git category: application 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