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

Implementation Plan 0006: Establish Pipeline Role Composition

Status: ready

Target executor: GPT-5.6-Terra

Feature roadmap: Feature 0006: Pipeline Role Composition Foundation

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:

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:

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:

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

• Stage 1 complete — ansible-role-dnd-pipeline commit b515968; fresh dependency bootstrap and full tests/integration passed. No deviations.