Complete the pipeline composition foundation
This commit is contained in:
@@ -1,382 +1,14 @@
|
||||
# Implementation Plan 0006: Establish Pipeline Role Composition
|
||||
# Implementation Plan
|
||||
|
||||
Status: ready
|
||||
Status: pending
|
||||
|
||||
Target executor: GPT-5.6-Terra
|
||||
No implementation plan is currently active. Feature 0006 was implemented in
|
||||
`ansible-role-dnd-pipeline` commits `b515968` and `61869d1`, independently
|
||||
reviewed, and finalized by remediation commit `4ea4358`.
|
||||
|
||||
Feature roadmap:
|
||||
[Feature 0006: Pipeline Role Composition Foundation](features/0006-pipeline-role-composition-foundation.md)
|
||||
Its durable scope and rationale remain in
|
||||
[the Feature 0006 roadmap](features/0006-pipeline-role-composition-foundation.md),
|
||||
and its final review record remains in [the remediation record](remediation.md).
|
||||
|
||||
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
|
||||
|
||||
- [x] Stage 1 complete — `ansible-role-dnd-pipeline` commit `b515968`; fresh
|
||||
dependency bootstrap and full `tests/integration` passed. No deviations.
|
||||
- [x] Stage 2 complete — `ansible-role-dnd-pipeline` commit `61869d1`; fresh
|
||||
dependency bootstrap and full `tests/integration` passed. No deviations.
|
||||
Select and approve the next unit of work before replacing this notice with a
|
||||
new staged implementation plan.
|
||||
|
||||
Reference in New Issue
Block a user