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

Complete the first suite release

Browse Source
This commit is contained in:
Eric Rakestraw
2026-09-17 23:52:46 +00:00
parent 06e1b35f25
commit eda361fa5d
4 changed files with 128 additions and 974 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
docs/roadmap/features/0013-first-coordinated-suite-release.md
View File

@@ -1,6 +1,6 @@
# Feature 0013: Publish the First Coordinated Suite Release # Feature 0013: Publish the First Coordinated Suite Release
Status: in_progress Status: done
## Summary ## Summary

830
docs/roadmap/implementation.md
View File

@@ -1,828 +1,8 @@
# Implementation Plan 0013: Publish the First Coordinated Suite Release # Implementation Plan
Status: proposed Status: pending
Target executor: GPT-5.6-Terra Feature 0013 is complete. There is no active implementation plan.
Feature roadmap: Select the next unit of work and agree on its numbered feature roadmap before
`docs/roadmap/features/0013-first-coordinated-suite-release.md` replacing this notice with a staged implementation plan.
Active plan location: `docs/roadmap/implementation.md`
## Objective
Publish the reviewed five application roles, standalone pipeline role, and
`rakestraw.dnd` collection as their first `v0.1.0` releases. Replace
development commit pins with immutable role tags, import the released pipeline
tag into the collection, attach the exact Galaxy-built collection archive to
the public Gitea collection release, and prove that a consumer can install and
converge the suite using public Gitea inputs alone.
The Feature 0013 roadmap remains authoritative for scope, rationale, target
state, and acceptance criteria. This plan does not authorize runtime behavior
changes or release machinery beyond the selected initial publication.
## Execution Rules
- Execute stages in numeric order.
- Before each stage, confirm its preconditions and the working-tree state of
every repository that stage owns.
- Before each stage, reread every document listed in its Required Policy
Review. Do not rely on policy recalled from an earlier stage.
- Preserve unrelated and pre-existing changes. Stop if a repository has
unexpected changes or has diverged from the stated release candidate.
- Do not change application-role code, defaults, tests, or documentation merely
to create a release. The five application-role tags must identify the exact
reviewed commits fixed by the feature roadmap.
- Do not make unresolved product or architecture decisions during execution.
Stop and report the decision required.
- Use the existing repository-local integration entry points. Do not add tests
that snapshot tag names, manifest text, defaults, task traces, or module
behavior.
- Do not add a release script, CI workflow, changelog generator, checksum,
signature, lock file, provenance file, or other persistent release
machinery.
- Create ordinary lightweight `v0.1.0` Git tags. Once a tag has been pushed,
treat it as immutable: never move, replace, or delete it to repair a failure.
- Push a release candidate's commit before pushing its tag. Confirm the public
remote advertises the expected commit or tag before a dependent stage uses
it.
- Use the public Gitea repository URL, never a sibling checkout, as the source
for the collection subtree import.
- Use `curl` with the Gitea REST API for the collection release and attachment;
`tea` is not installed and must not be added for this feature. Obtain
authentication from the existing Git credential helper, keep shell tracing
disabled, never print credentials, and unset credential variables after the
API operations.
- Build temporary artifacts beneath a directory created by `mktemp -d`. Do not
add the collection archive or API payloads to any repository.
- Run every stage's validation before its release commit or external
publication step. Do not continue after a validation failure.
- Use the plain-English commit intents stated below. A tag-only stage has no
commit because its target repositories must remain byte-for-byte unchanged.
- If publication succeeds only partially, do not undo successful immutable
publication. Stop, report the exact external state, and resume only the
missing operation when safe.
## Starting State and Preconditions
- Feature 0012 and its remediation are complete.
- The Feature 0013 roadmap and this implementation plan have been reviewed and
committed in the workspace repository before execution begins.
- All repositories are on `main`, have no unexpected worktree changes, and are
not behind `origin/main`.
- The five application-role repositories are at these exact reviewed commits,
which also match their current public `origin/main` revisions:
| Repository | Release commit |
| --- | --- |
| `ansible-role-audita` | `66ebea9a47ce82bfdbdc5e2855f3dfaaff8e2a16` |
| `ansible-role-narratio` | `292d8669e7aad5cfe80b0c469d22b6177e8cf0f1` |
| `ansible-role-notarius` | `14a38e04e35ef524d6a97fa7fb5a04981a0a2161` |
| `ansible-role-seriatim` | `e08c63c0b078658bdfa2d10a2e6e1e4f9372a075` |
| `ansible-role-scriptorium` | `8b4c86e48e7d8655e479b26dc510bf01683a0c8f` |
- `ansible-role-dnd-pipeline` begins at
`600eb21cd967831607c087f1773063636ff2c31b`; its local branch contains the
completed pipeline work that has not yet been published to `origin/main`.
- `ansible-collection-dnd` begins at
`da67b34aa97e4a72794128deed10d1add4cd3897`; its local branch contains the
completed collection work that has not yet been published to `origin/main`.
- No participating local or remote repository already has a `v0.1.0` tag, and
no Gitea collection release named for `v0.1.0` exists. If any does exist at
execution time, verify whether it is exact resumable state; otherwise stop
rather than overwrite it.
- The workspace `.venv` supplies the tested `ansible-galaxy`,
`ansible-playbook`, and `ansible-lint` executables used by the existing test
drivers. Git, `curl`, `jq`, `sudo`, and the required Go Snap are available.
- The host remains the approved MVP proxy for Ubuntu 26.04, and the existing
integration suites are allowed to converge their documented local test
paths.
- The existing Git credential helper can authenticate Git pushes and Gitea API
requests for repositories beneath
`https://gitea.maximumdirect.net/eric/`. Do not persist those credentials in
a repository or plan.
## Repository Scope
- `ansible-role-audita`, `ansible-role-narratio`, `ansible-role-notarius`,
`ansible-role-seriatim`, and `ansible-role-scriptorium` receive only their
exact `v0.1.0` tags. Their tracked content must not change.
- `ansible-role-dnd-pipeline` owns its tag-pinned role manifest, release-facing
README wording, release commit, and `v0.1.0` tag.
- `ansible-collection-dnd` owns the released pipeline subtree import,
tag-pinned unified manifest, release installation documentation, collection
release commit and tag, built archive, and public Gitea release attachment.
- `ansible-workspace-dnd` owns implementation progress, the compatibility
record, and the review handoff.
- Application source repositories, `assets/campaigns`,
`assets/narratio-prompts`, `assets/configs`, and `rakestraw-ansible` are
read-only inputs and must remain unchanged.
## Stage 1: Validate the Five Application-Role Release Candidates
### Objective
Establish that the exact five reviewed application-role commits remain clean,
public, and suitable for immutable release tags without changing them.
### Required Policy Review
Before beginning this stage, read:
- `AGENTS.md`
- `docs/orientation.md`
- `docs/conventions.md`
- `docs/ansible.md`
- `docs/testing.md`
- `docs/planning.md`
- `docs/roadmap/features/0013-first-coordinated-suite-release.md`
### Preconditions
- The workspace planning commit is present.
- Each application-role repository is clean and checked out at the exact
commit listed in Starting State.
- Each application's `origin/main` resolves to the same listed commit.
- Neither a local nor public `v0.1.0` tag exists in any application-role
repository.
### Owning Repositories
- `ansible-role-audita`
- `ansible-role-narratio`
- `ansible-role-notarius`
- `ansible-role-seriatim`
- `ansible-role-scriptorium`
### Required Work
1. Fetch each repository's remote refs without modifying its branch and verify
its clean state, exact HEAD, exact `origin/main`, and absence of `v0.1.0`
locally and remotely.
2. Run each repository's existing `tests/integration` entry point. These
drivers already own syntax checking, production-profile lint where
applicable, behavior validation, selected-version behavior, and immediate
clean convergence.
3. Do not edit a role to make a failing candidate releasable. Stop and report
any failure for separate remediation.
4. Confirm that all five worktrees remain clean and at the fixed release
commits after validation.
### Validation
Run from the workspace root:
```text
(cd ansible-role-audita && tests/integration && git diff --check)
(cd ansible-role-narratio && tests/integration && git diff --check)
(cd ansible-role-notarius && tests/integration && git diff --check)
(cd ansible-role-seriatim && tests/integration && git diff --check)
(cd ansible-role-scriptorium && tests/integration && git diff --check)
```
Expected result: every existing role suite passes, including its native
application checks and immediate clean repeat; every repository remains clean
at its roadmap-fixed commit.
### Completion Criteria
- All five exact candidates pass their existing test suites.
- All five candidates match public `origin/main`.
- No local or public application-role `v0.1.0` tag exists yet.
- No tracked content changed.
### Commit
Commit intent: none; this is a read-only validation stage.
## Stage 2: Publish the Five Application-Role Tags
### Objective
Expose each validated application role from its public Gitea repository at the
immutable version selected by the compatibility baseline.
### Required Policy Review
Before beginning this stage, read:
- `AGENTS.md`
- `docs/orientation.md`
- `docs/conventions.md`
- `docs/planning.md`
- `docs/roadmap/features/0013-first-coordinated-suite-release.md`
### Preconditions
- Stage 1 completed without findings.
- Each role is still clean, its HEAD and `origin/main` still equal the fixed
release commit, and `v0.1.0` is still absent locally and remotely.
- Authenticated pushes to every application-role origin are available.
### Owning Repositories
- `ansible-role-audita`
- `ansible-role-narratio`
- `ansible-role-notarius`
- `ansible-role-seriatim`
- `ansible-role-scriptorium`
### Required Work
1. Create a lightweight `v0.1.0` tag in each repository at the exact commit
fixed by the feature roadmap; do not tag an inferred current branch tip.
2. Push only that tag to the corresponding `origin`.
3. After every push, use `git ls-remote --tags origin refs/tags/v0.1.0` to
confirm that Gitea advertises the exact expected commit.
4. Do not create Gitea release objects for the application roles. The public
immutable Git tags are their selected release interface.
### Validation
Run the equivalent of the following for every repository, substituting the
fixed roadmap commit:
```text
git -C <repository> tag v0.1.0 <fixed-release-commit>
git -C <repository> push origin refs/tags/v0.1.0
git -C <repository> ls-remote --tags origin refs/tags/v0.1.0
```
Expected result: each public `refs/tags/v0.1.0` resolves to its exact fixed
commit, and all five repositories remain clean and otherwise unchanged.
### Completion Criteria
- All five public application-role tags exist at their specified commits.
- No tag was moved, replaced, or deleted.
- No application-role tracked content or branch changed.
### Commit
Commit intent: none; this stage publishes tags against existing commits.
## Stage 3: Release the Standalone Pipeline Role
### Objective
Convert the authoritative pipeline role from development commit pins to the
five published role tags, validate that released dependency set, and publish
the standalone pipeline role as `v0.1.0`.
### Required Policy Review
Before beginning this stage, read:
- `AGENTS.md`
- `docs/orientation.md`
- `docs/conventions.md`
- `docs/ansible.md`
- `docs/testing.md`
- `docs/planning.md`
- `docs/roadmap/features/0013-first-coordinated-suite-release.md`
- `ansible-role-dnd-pipeline/README.md`
### Preconditions
- Stage 2's five public tags resolve to the exact roadmap-fixed commits.
- `ansible-role-dnd-pipeline` is clean at `600eb21cd967831607c087f1773063636ff2c31b`,
is not behind its upstream, and has no local or remote `v0.1.0` tag.
- The completed local pipeline commits are ready to be pushed as part of the
release candidate.
### Owning Repository
`ansible-role-dnd-pipeline`
### Required Changes
1. In `requirements.yml`, replace each of the five full development commit
values with `v0.1.0`. Do not change role names, public Gitea sources, SCM
selection, ordering, or `collections/requirements.yml`.
2. Update the README's standalone and collection-facing release wording so it
describes the tag-pinned role dependencies and no longer claims the initial
collection release is necessarily unpublished. Keep the existing public
interfaces and ordinary installation commands; do not duplicate the full
collection release procedure.
3. Do not change defaults, metadata dependencies, tasks, templates, handlers,
tests, or runtime behavior.
4. Run the existing pipeline integration driver. Its dependency installation
must resolve the five roles from their public Gitea `v0.1.0` tags. Do not
add assertions that merely inspect the manifest or tags.
5. Commit the validated manifest and documentation change, push `main`, then
create `v0.1.0` at that exact pushed commit and push the tag.
6. Confirm through `git ls-remote` that public `origin/main` and public
`refs/tags/v0.1.0` both resolve to the release commit.
### Validation
Run:
```text
cd ansible-role-dnd-pipeline
bash -n tests/integration
tests/integration
git diff --check
```
Expected result: the existing full pipeline suite installs the public tagged
application roles into its isolated role path, passes syntax and production
lint, validates the representative native application behavior, and reports a
clean immediate repeat. Only `requirements.yml` and release-facing README
wording differ before the release commit.
After committing and pushing, verify the public branch and tag with:
```text
git ls-remote origin refs/heads/main refs/tags/v0.1.0
```
### Completion Criteria
- The pipeline manifest selects all five `v0.1.0` application-role tags.
- Existing pipeline validation passes without new release-specific tests.
- The release commit is present on public `origin/main`.
- Public pipeline tag `v0.1.0` resolves to that exact commit.
- The pipeline worktree is clean.
### Commit
Commit intent: `Prepare the pipeline role for its first release`
## Stage 4: Prepare the Collection Release Candidate
### Objective
Import the public pipeline release into the collection, align the unified
consumer manifest, document the public release installation path, and produce
a validated collection release candidate.
### Required Policy Review
Before beginning this stage, read:
- `AGENTS.md`
- `docs/orientation.md`
- `docs/conventions.md`
- `docs/ansible.md`
- `docs/testing.md`
- `docs/planning.md`
- `docs/roadmap/features/0013-first-coordinated-suite-release.md`
- `ansible-collection-dnd/README.md`
### Preconditions
- The public pipeline `v0.1.0` tag exists at the validated Stage 3 release
commit.
- `ansible-collection-dnd` is clean at
`da67b34aa97e4a72794128deed10d1add4cd3897`, is not behind upstream, and has
no local or remote `v0.1.0` tag or Gitea release.
- Public application-role tags and the public pipeline tag are resolvable
without sibling repositories.
### Owning Repository
`ansible-collection-dnd`
### Required Changes
1. Run the documented remote-only squashed subtree update using the public
pipeline repository and literal revision `v0.1.0`:
```text
git subtree pull --prefix=roles/pipeline \
https://gitea.maximumdirect.net/eric/ansible-role-dnd-pipeline.git \
v0.1.0 --squash -m "Import pipeline role v0.1.0"
```
Accept the ordinary subtree-generated history. Do not edit imported role
behavior beneath `roles/pipeline`.
2. Verify the imported tree against a disposable clone of the public pipeline
`v0.1.0` tag, excluding only the clone's `.git` metadata.
3. In the collection's root `requirements.yml`, replace all five development
commit values with `v0.1.0`. Preserve role names, Gitea sources, SCM,
ordering, and the exact `ansible.posix` 2.2.0 and `community.general` 13.3.0
versions.
4. Update the collection README to describe release `0.1.0`, its five
application-role `v0.1.0` pins, pipeline `v0.1.0`, and the public install
path. The consumer instructions must fetch the tagged root manifest and
install this exact attachment URL after dependencies:
```text
https://gitea.maximumdirect.net/eric/ansible-collection-dnd/releases/download/v0.1.0/rakestraw-dnd-0.1.0.tar.gz
```
Use this Gitea tagged raw-file URL for `requirements.yml`:
```text
https://gitea.maximumdirect.net/eric/ansible-collection-dnd/raw/tag/v0.1.0/requirements.yml
```
Do not require a workspace checkout or ask consumers to build the released
collection.
5. Retain `galaxy.yml` version `0.1.0`, the existing native collection
dependencies, build exclusions, runtime metadata, subtree workflow, and
standalone pipeline authority.
6. Do not add a changelog, release script, checksum, copied-manifest test, or
other release scaffolding. Change `tests/integration` only if an actual
release-candidate failure requires a minimal repair; the tag substitutions
should flow through its existing public behavior.
7. Run the complete existing collection integration suite after all candidate
changes. Commit the collection-owned manifest and README changes separately
from the subtree-generated import, then push both commits on `main`.
### Validation
Validate the subtree source with a disposable directory and public clone:
```text
release_tmp=$(mktemp -d)
git clone --depth 1 --branch v0.1.0 \
https://gitea.maximumdirect.net/eric/ansible-role-dnd-pipeline.git \
"$release_tmp/pipeline"
diff -qr --exclude=.git "$release_tmp/pipeline" roles/pipeline
```
Then run:
```text
bash -n tests/integration
tests/integration
git diff --check
```
Expected result: the imported subtree exactly represents public pipeline
`v0.1.0`; the root and imported dependency manifests select the same five
role tags and native collection versions; the collection suite builds and
installs `rakestraw-dnd-0.1.0.tar.gz` into isolated paths, resolves
`rakestraw.dnd.pipeline`, passes its representative native checks, and reports
`changed=0 failed=0` on the immediate repeat.
### Completion Criteria
- Git history contains the squashed remote subtree import from pipeline
`v0.1.0`.
- The root manifest and imported pipeline manifests describe the same released
dependency set.
- Release installation documentation uses public Gitea URLs and contains no
development-workspace dependency.
- The complete existing collection integration suite passes.
- Both collection commits are on public `origin/main`, and the worktree is
clean.
### Commits
Expected subtree-generated commit intent: `Import pipeline role v0.1.0`
Collection-owned commit intent: `Prepare the D&D collection for its first release`
## Stage 5: Publish the Collection Tag and Artifact
### Objective
Create the immutable collection source release, build its exact Galaxy
artifact, and publish that artifact through the public Gitea collection
release.
### Required Policy Review
Before beginning this stage, read:
- `AGENTS.md`
- `docs/orientation.md`
- `docs/conventions.md`
- `docs/ansible.md`
- `docs/testing.md`
- `docs/planning.md`
- `docs/roadmap/features/0013-first-coordinated-suite-release.md`
- `ansible-collection-dnd/README.md`
### Preconditions
- Stage 4 validation passed and the complete release candidate is clean and
present on public `origin/main`.
- `galaxy.yml` declares `0.1.0`.
- No local or remote collection `v0.1.0` tag and no collection Gitea
`v0.1.0` release exists.
- The existing Git credential helper can authenticate the Gitea REST API.
### Owning Repository
`ansible-collection-dnd`
### Required Work
1. Record the clean release-candidate commit and build
`rakestraw-dnd-0.1.0.tar.gz` from that exact tree into a private temporary
directory with the workspace `.venv` `ansible-galaxy` executable.
2. Confirm the archive name and that the repository remains clean. The Stage 4
integration suite already owns detailed archive-boundary behavior; do not
add another persistent archive-content test.
3. Create lightweight tag `v0.1.0` at the recorded release commit, push only
that tag, and verify the public tag resolves to the same commit.
4. Through Gitea's REST API, create the non-draft, non-prerelease collection
release for tag `v0.1.0` with title `rakestraw.dnd 0.1.0`. Its concise body
must identify:
- pipeline role `v0.1.0`;
- all five application roles at `v0.1.0`;
- `ansible.posix` 2.2.0 and `community.general` 13.3.0;
- Ubuntu 26.04 with `amd64` and `arm64` support; and
- the tagged manifest plus release-attachment installation flow.
5. Upload the already-built archive through the release-asset API with exact
filename `rakestraw-dnd-0.1.0.tar.gz`. Do not rebuild after tagging or upload
a file from a different tree.
6. Retrieve the public release by tag and confirm it advertises the expected
tag, release title, and one attachment with the exact filename and public
browser-download URL. Trust the successful API upload; do not add a
checksum or signature requirement.
7. Keep API credentials only in shell variables sourced from the credential
helper, with command tracing disabled. Unset them immediately after the API
requests and remove the temporary build directory after Stage 6 consumes or
redownloads the public artifact.
Use these Gitea API boundaries:
```text
POST /api/v1/repos/eric/ansible-collection-dnd/releases
POST /api/v1/repos/eric/ansible-collection-dnd/releases/{release-id}/assets
GET /api/v1/repos/eric/ansible-collection-dnd/releases/tags/v0.1.0
```
Build with:
```text
release_tmp=$(mktemp -d)
../.venv/bin/ansible-galaxy collection build --output-path "$release_tmp"
```
### Validation
Verify the source tag and public release through Git and the unauthenticated
public API:
```text
git ls-remote origin refs/tags/v0.1.0
curl -fsS \
https://gitea.maximumdirect.net/api/v1/repos/eric/ansible-collection-dnd/releases/tags/v0.1.0 \
| jq '{tag_name, name, draft, prerelease, assets: [.assets[].name]}'
```
Expected result: the public tag resolves to the clean validated collection
commit; the release is neither draft nor prerelease; and it exposes exactly
the expected collection archive name at the public release-download URL.
### Completion Criteria
- Public collection tag `v0.1.0` identifies the validated release commit.
- Public Gitea release `rakestraw.dnd 0.1.0` exists for that tag.
- Its attachment is the exact archive built from the tagged tree and is named
`rakestraw-dnd-0.1.0.tar.gz`.
- No archive, API payload, or credential has entered Git.
- The collection worktree remains clean.
### Commit
Commit intent: none; this stage publishes the already committed candidate.
## Stage 6: Validate the Public Consumer Path
### Objective
Prove from isolated Ansible paths that the public tagged manifest and public
collection attachment are sufficient to resolve and converge
`rakestraw.dnd.pipeline` without any sibling role or unpublished artifact.
### Required Policy Review
Before beginning this stage, read:
- `AGENTS.md`
- `docs/orientation.md`
- `docs/conventions.md`
- `docs/ansible.md`
- `docs/testing.md`
- `docs/planning.md`
- `docs/roadmap/features/0013-first-coordinated-suite-release.md`
### Preconditions
- The seven public `v0.1.0` tags and collection release attachment are
available without authentication for reads.
- Stage 5's public API validation passed.
- No normal user Ansible path is needed for the smoke validation.
### Owning Repository
No repository changes are expected. The public
`ansible-collection-dnd@v0.1.0` release is the subject under validation.
### Required Work
1. Create a private temporary directory and set `ANSIBLE_ROLES_PATH` and
`ANSIBLE_COLLECTIONS_PATH` to new children of that directory, replacing
rather than extending normal user paths.
2. Clone collection tag `v0.1.0` from public Gitea into the temporary directory
only to obtain the released `requirements.yml`, inventory, and minimal
convergence play. Do not use the workspace collection checkout.
3. Download the public release attachment through this exact URL and validate
that it is a readable gzip tar archive:
```text
https://gitea.maximumdirect.net/eric/ansible-collection-dnd/releases/download/v0.1.0/rakestraw-dnd-0.1.0.tar.gz
```
4. Install the cloned tag's unified requirements into the isolated paths, then
install the downloaded archive with `--no-deps`. Do not substitute the local
Stage 5 artifact.
5. Syntax-check and apply the released collection's minimal convergence play
with a synthetic local WhisperX URL and synthetic credential contents. Let
the release use its public default campaign and prompt-library repositories;
do not point either asset at a sibling checkout.
6. Apply the same play immediately a second time and require an overall recap
containing `changed=0` and `failed=0`.
7. Do not repeat the collection suite's native application matrix here. This
stage tests only the public download, dependency bootstrap, FQCN resolution,
and clean consumer convergence boundary.
8. Remove the temporary directory. If this post-publication smoke fails, do
not move or delete any release tag or replace the published attachment;
report the failure for remediation.
### Validation
Run the equivalent of:
```text
consumer_tmp=$(mktemp -d)
export ANSIBLE_ROLES_PATH="$consumer_tmp/roles"
export ANSIBLE_COLLECTIONS_PATH="$consumer_tmp/collections"
git clone --depth 1 --branch v0.1.0 \
https://gitea.maximumdirect.net/eric/ansible-collection-dnd.git \
"$consumer_tmp/source"
curl -fL \
https://gitea.maximumdirect.net/eric/ansible-collection-dnd/releases/download/v0.1.0/rakestraw-dnd-0.1.0.tar.gz \
-o "$consumer_tmp/rakestraw-dnd-0.1.0.tar.gz"
tar -tzf "$consumer_tmp/rakestraw-dnd-0.1.0.tar.gz" >/dev/null
.venv/bin/ansible-galaxy install -r "$consumer_tmp/source/requirements.yml"
.venv/bin/ansible-galaxy collection install \
"$consumer_tmp/rakestraw-dnd-0.1.0.tar.gz" --no-deps
```
Use the released `tests/inventory` and `tests/converge.yml` for syntax and two
applications. Supply only the required WhisperX URL and distinctive synthetic
values for `AUDITA_LLM_API_KEY` and `OPENROUTER_API_KEY`; do not use real
credentials or invoke an external model or transcription service.
Expected result: dependency installation logs resolve the application roles
from public `v0.1.0` tags; Ansible resolves the installed
`rakestraw.dnd.pipeline` FQCN from the downloaded collection archive; the first
application succeeds; and the immediate repeat reports `changed=0 failed=0`.
### Completion Criteria
- The public manifest and public artifact download successfully without a
workspace path.
- All dependencies and the collection install into isolated paths.
- The released FQCN syntax-checks and converges successfully.
- The immediate repeat is clean.
- No real credential or external inference call is used.
- No repository changes were made.
### Commit
Commit intent: none; this is a read-only public-release smoke validation.
## Stage 7: Record the Implementation and Hand Off for Review
### Objective
Record the exact published compatibility baseline and leave every repository
clean for independent review without prematurely marking Feature 0013 done.
### Required Policy Review
Before beginning this stage, read:
- `AGENTS.md`
- `docs/orientation.md`
- `docs/conventions.md`
- `docs/planning.md`
- `docs/roadmap/features/0013-first-coordinated-suite-release.md`
### Preconditions
- Stages 1 through 6 completed successfully.
- Every release commit and all seven tags are present on public Gitea.
- The public collection release and attachment passed the remote-only smoke
validation.
- All nested repositories are clean.
### Owning Repository
Workspace root (`ansible-workspace-dnd`)
### Required Changes
1. Change Feature 0013's roadmap status from `ready` to `in_progress`; do not
mark it `done` before independent implementation review.
2. Update `docs/status.md` so Feature 0013 remains `in_progress`, the current
focus is independent review, and the evidence names the pipeline and
collection release commits, all seven public tags, and the collection
release URL.
3. Add concise Progress Notes to this plan recording completed stages, release
commit hashes, public tag verification, the collection release URL, and the
remote-only smoke result. Do not copy command logs into the document.
4. Do not create or revise `docs/roadmap/remediation.md`; findings belong to
the subsequent independent review.
5. Run workspace integrity checks, commit the tracking changes, and push the
workspace branch.
### Validation
Run:
```text
git diff --check
./scripts/status
git status --short --branch
```
Expected result: the status dashboard and feature documents agree that the
release is implemented and awaiting review; every nested repository is clean
and synchronized with its upstream; the workspace contains only the intended
tracking changes before its commit and is clean after the commit and push.
### Completion Criteria
- Workspace documentation records the exact release evidence concisely.
- Feature 0013 remains open pending independent review.
- The workspace implementation record is committed and pushed.
- Every repository is clean and no participating branch or tag is only local.
### Commit
Commit intent: `Record the first suite release implementation`
## Final Validation and Handoff
- Confirm the five application-role public tags still resolve to the exact
roadmap-fixed commits.
- Confirm the public pipeline and collection tags resolve to their recorded
release commits.
- Confirm the public collection API record exposes the expected non-draft,
non-prerelease release and archive attachment.
- Confirm Stage 1's application-role suites, Stage 3's pipeline suite, Stage
4's collection suite, and Stage 6's remote-only consumer smoke all passed.
- Run `./scripts/status` and confirm every repository is clean, no repository
is behind upstream, and no release commit or tag remains unpushed.
- Report all resulting commit hashes, tag targets, the public collection
release URL, validation commands, and any deviations from this plan.
- Report any complexity added beyond the plan and the acceptance criterion
that required it.
- Do not mark Feature 0013 `done`; implementation results require independent
review first.
## Progress Notes
- Stage 1 complete: all five application-role integration suites passed; each
clean candidate matches its roadmap-fixed public `origin/main` commit, and
no local or public `v0.1.0` application-role tag existed before publication.
- Stage 2 complete: public lightweight `v0.1.0` tags for Audita, Narratio,
Notarius, Seriatim, and Scriptorium resolve to their five roadmap-fixed
release commits.
- Stage 3 complete: `ansible-role-dnd-pipeline`
`7c2bad827702fdcf78f8f77ece7d6270756bc3c5` passed its full tag-pinned
integration suite and is public on both `main` and `v0.1.0`.
- Stage 4 complete: `ansible-collection-dnd` imported public pipeline
`v0.1.0` in `da348eb8bd9878a58404a37dbcf22ad6562ac5c9`; release candidate
`63e8f3fb090a583226c7435bd900e10d41a30b89` passed the isolated collection
suite and is public on `main`.
- Stage 5 complete: public collection tag `v0.1.0` resolves to
`63e8f3fb090a583226c7435bd900e10d41a30b89`; the non-draft, non-prerelease
`rakestraw.dnd 0.1.0` Gitea release exposes the exact
`rakestraw-dnd-0.1.0.tar.gz` attachment.
- Stage 6 complete: an unauthenticated temporary clone and release-attachment
download installed all dependencies and `rakestraw.dnd.pipeline` into
isolated paths; the immediate repeat reported `changed=0` and `failed=0`.
- Stage 7 complete: `ansible-workspace-dnd`
`539c75cb188db5e8cadc38c5ec5283e60f73a23b` records and publishes the
implementation evidence while Feature 0013 remains `in_progress` for
independent review.
- Published compatibility baseline: Audita
`66ebea9a47ce82bfdbdc5e2855f3dfaaff8e2a16`, Narratio
`292d8669e7aad5cfe80b0c469d22b6177e8cf0f1`, Notarius
`14a38e04e35ef524d6a97fa7fb5a04981a0a2161`, Seriatim
`e08c63c0b078658bdfa2d10a2e6e1e4f9372a075`, Scriptorium
`8b4c86e48e7d8655e479b26dc510bf01683a0c8f`, pipeline
`7c2bad827702fdcf78f8f77ece7d6270756bc3c5`, and collection
`63e8f3fb090a583226c7435bd900e10d41a30b89` are publicly verified at
`v0.1.0`.
- Public release: [rakestraw.dnd
0.1.0](https://gitea.maximumdirect.net/eric/ansible-collection-dnd/releases/tag/v0.1.0).
- Deviations: the first pipeline-suite run was interrupted by a transient DNS
failure and passed unchanged on retry. Six repositories were unexpectedly
private and were made public after explicit user authorization, as required
by the public-install acceptance criterion. The Stage 6 command was rerun
without its inline cleanup after the execution guard rejected that command
before it started; the exact temporary roots were removed separately after
the smoke passed.

264
docs/roadmap/remediation.md
View File

@@ -1,173 +1,147 @@
# Feature 0012 Remediation Review # Feature 0013 Remediation Review
Status: resolved Status: resolved
Reviewed implementation commits: Reviewed implementation and release state:
- `600eb21 Document standalone and collection pipeline usage` - Application-role `v0.1.0` tags at the five roadmap-fixed commits
- `3f7f82e Establish the D&D collection foundation` - Pipeline release commit and tag
- `c84aa0d Merge commit '5dbae8a' as 'roles/pipeline'` `7c2bad827702fdcf78f8f77ece7d6270756bc3c5`
- `10ad31c Test the assembled D&D collection` - Collection subtree import
`da348eb8bd9878a58404a37dbcf22ad6562ac5c9`
- Collection release commit and tag
`63e8f3fb090a583226c7435bd900e10d41a30b89`
- Public `rakestraw.dnd 0.1.0` Gitea release and
`rakestraw-dnd-0.1.0.tar.gz` attachment
- Workspace implementation record through
`06e1b35f25589a3a6ff3fd2884208c86c4fee9c4`
## Review Summary ## Review Summary
Feature 0012 implements the principal target architecture. The standalone Feature 0013 implements the release architecture and public consumer path.
pipeline repository remains authoritative, and collection history records its The five application-role tags identify the exact reviewed commits selected by
exact `600eb21` snapshot as a squashed subtree at `roles/pipeline`. The the roadmap. The standalone pipeline and collection manifests use those
collection has valid Galaxy and runtime metadata, exact native collection immutable tags, and the native collection dependencies remain pinned to
dependencies, one unified bootstrap manifest for the five Git-hosted roles, `ansible.posix` 2.2.0 and `community.general` 13.3.0. The collection subtree's
focused build exclusions, and an isolated artifact-level integration entry Git tree exactly matches public pipeline tag `v0.1.0`.
point. The collection builds as `rakestraw.dnd` 0.1.0 and exposes
`rakestraw.dnd.pipeline`.
Two low-severity issues were found and are now resolved. The collection's All seven repositories and tags are public and synchronized with their local
subtree maintenance examples derived a commit from the local sibling counterparts. The collection's non-draft, non-prerelease Gitea release carries
repository but told Git to fetch that commit from a remote which did not one correctly named archive. Its manifest declares `rakestraw.dnd` 0.1.0, the
contain it at review time. Separately, the collection integration driver expected Ansible baseline and collection dependencies, and its file payload
repeated secret-redaction assertions already owned by the standalone pipeline matches a fresh build from the tagged collection tree.
suite; those assertions did not validate collection assembly and strengthened
the collection test contract beyond the selected packaging boundary.
## Finding 1: Subtree Maintenance Commands Mix Local and Remote Sources One low-severity documentation issue remains. The pipeline README now implies
that collection snapshots may be imported only from role releases. That
strengthens the settled maintenance contract beyond the requested release
feature and contradicts the documented development workflow, which also
permits a reviewed, pushed commit.
## Finding 1: Pipeline Documentation Narrows Subtree Imports to Releases
Severity: low Severity: low
`ansible-collection-dnd/README.md:51-63` obtains `pipeline_commit` from `ansible-role-dnd-pipeline/README.md:51-53` says that collection maintainers
`../ansible-role-dnd-pipeline`, but passes the Gitea URL as the repository “import a reviewed release as a snapshot.” The same sentence is present in the
argument to both `git subtree add` and `git subtree pull`. The reviewed faithfully imported collection copy at
pipeline commit was seven commits ahead of `origin/main` at review time; the `ansible-collection-dnd/roles/pipeline/README.md:51-53`.
remote advertised `b15fe8d`, not imported commit `600eb21`. The documented
command therefore could not reproduce the current import.
The collection artifact already contains the imported role, so consumers do That wording accurately describes the particular snapshot used for collection
not run these commands or need a sibling checkout. The commands are the release 0.1.0, but it reads as the general maintenance rule. The durable
maintainer-facing assembly interface and should also be portable outside this architecture deliberately permits the collection to import any reviewed
workspace. The durable contract should therefore use Gitea exclusively: first pipeline commit that has been pushed to Gitea during development. An immutable
push the reviewed pipeline commit or tag to the authoritative repository, then pipeline tag is required only when preparing a released compatibility set.
identify that remote revision explicitly and import it from the same URL. The collection's own maintenance section correctly accepts a pushed commit or
immutable tag.
This is an inadvertent requirement strengthening: it could force an otherwise
unnecessary pipeline-role release merely to assemble and test a development
collection snapshot. It does not affect runtime behavior, the released
dependency pins, subtree fidelity, or consumer installation.
### Required Remediation ### Required Remediation
- Remove the sibling-repository `git rev-parse` commands from both subtree - In the authoritative pipeline README, replace the release-only wording with
examples. concise language saying that collection maintainers import a reviewed,
- Define an explicit `pipeline_revision` placeholder representing a reviewed pushed commit or immutable tag as a snapshot.
commit or immutable tag that has already been pushed to Gitea, and pass that - Make no role, manifest, default, task, template, handler, or test change.
revision with the authoritative Gitea URL to both `git subtree add` and - Commit and push the pipeline documentation correction before importing it
`git subtree pull`. into the collection.
- State concisely that a pipeline revision must be committed, reviewed, and - Refresh `roles/pipeline` through the documented squashed subtree command
pushed to the authoritative repository before collection assembly imports using the pushed pipeline documentation commit as the remote revision. Do
it. Do not prescribe a branch name or require a release tag during active not edit the collection's subtree copy directly.
development; a pushed full commit ID remains valid. - Confirm that the resulting collection subtree Git tree exactly matches the
- Do not add a configured remote, sibling-path assumption, synchronization selected pushed pipeline commit outside Git metadata.
script, lock file, or private provenance state. - Do not move or replace any `v0.1.0` tag, modify the published Gitea release,
- Do not rewrite subtree history or reimport the current role. This is a or replace its attachment. Those immutable artifacts correctly describe the
collection-owned documentation correction only. historical 0.1.0 source state.
- Confirm that Gitea contains the selected pipeline revision, then validate - Do not create a new role or collection release solely for this
the corrected initial command in a disposable Git repository without using maintainer-facing wording correction.
the local sibling repository as the subtree source.
## Finding 2: The Collection Test Duplicates Secret-Redaction Coverage ### Required Validation
Severity: low Run:
`ansible-collection-dnd/tests/integration:19-20` defines two synthetic values
solely so lines 74-75 can search the first convergence log for them. Secret-safe
task output is pipeline behavior established by Feature 0011 and already
covered by `ansible-role-dnd-pipeline/tests/integration`. The collection owns
artifact construction, bootstrap installation, FQCN resolution, representative
assembled behavior, and clean repeated convergence; it does not own a second
credential-redaction contract.
The implementation plan required synthetic credentials so native
configuration could be exercised without real provider values, but it did not
require the collection to retest Feature 0011 redaction. These two assertions
are therefore an inadvertent strengthening by the implementing agent and
conflict with the roadmap's instruction to keep detailed pipeline feature
coverage in the standalone role.
The native Seriatim, Audita, Notarius, Scriptorium, and Narratio checks are not
part of this finding. They are state-based, inexpensive, and implement the
roadmap's express requirement for representative native validation of the
assembled suite.
### Required Remediation
- Retain distinctive synthetic credential contents in the collection
convergence variables; no real credential or live provider call may enter
the suite.
- Remove the two shell variables used only for log searching and remove the two
secret-content grep assertions.
- Retain isolated dependency installation, archive boundary checks, FQCN
syntax and lint validation, the selected native application checks, and the
immediate `changed=0 failed=0` repeat.
- Do not replace the removed assertions with another collection-level
credential, log, file-content, or implementation-trace test.
## Resolution
Resolved in collection commits `556b6ed` and `da67b34`.
The collection README now uses an explicit `PUSHED_COMMIT_OR_TAG` revision and
the authoritative Gitea URL for both initial and subsequent subtree imports.
It states that the selected revision must be committed, reviewed, and pushed
before collection assembly. The examples no longer inspect or depend on a
sibling checkout. A disposable repository successfully imported the exact
commit advertised by Gitea through the documented remote-only command shape.
The collection integration driver retains its distinctive synthetic
credential inputs but no longer defines separate values solely for log
searching or duplicates the standalone pipeline suite's two redaction
assertions. Its artifact, dependency, FQCN, native application, and clean
repeat coverage remain unchanged.
## Required Validation
After remediation, run:
```text ```text
cd ansible-collection-dnd cd ansible-role-dnd-pipeline
bash -n tests/integration git diff --check
tests/integration
cd ../ansible-collection-dnd
../.venv/bin/ansible-galaxy collection build --output-path "$(mktemp -d)"
git diff --check git diff --check
``` ```
The result must demonstrate isolated dependency bootstrap, collection build Also compare the imported `roles/pipeline` tree with a disposable clone of the
and artifact installation, FQCN resolution, the retained native application selected pushed pipeline commit. The full application, pipeline, and
checks, and immediate clean convergence. The built artifact must still include collection integration suites do not need to be rerun because the remediation
`roles/pipeline/tasks/main.yml` and exclude the selected development-only changes documentation only and preserves all Ansible and dependency content.
subtree content.
Validate the corrected subtree example against Gitea in a disposable Git ## Resolution
repository without modifying the real collection history or relying on the
local sibling repository as the source. The standalone pipeline integration Resolved in pipeline commit `78afffe` and collection subtree import
suite does not need to be rerun for these collection-only documentation and `5e695f3`.
test-scope changes.
The authoritative pipeline README now states that collection maintainers may
import either a reviewed, pushed commit or an immutable tag. The pipeline
commit was pushed before the collection imported that exact Gitea revision
through the documented squashed subtree workflow. The imported subtree and
pipeline source have the same Git tree ID,
`37f619ac24d2303847c4b9ea60db1f9fc1bf9d0e`.
A fresh collection build succeeded, and `git diff --check` passed in both
repositories. No Ansible content or dependency selection changed, so the
integration suites were not rerun. The seven `v0.1.0` tags, published
collection release, and release attachment remain unchanged.
## Review Validation Evidence ## Review Validation Evidence
The review compared the complete standalone pipeline repository with - Every local and remote `v0.1.0` tag resolves to the commit recorded in the
`roles/pipeline`; the trees are byte-for-byte identical outside Git metadata. Feature 0013 roadmap and implementation notes.
The root bootstrap manifest's role and collection sections exactly match the - All seven Gitea repositories report public visibility and `main` as their
two imported pipeline manifests, and `galaxy.yml` declares the same native default branch.
collection versions. - The pipeline `v0.1.0` tree ID and the collection tag's
`roles/pipeline` tree ID are both
`44a9d2b010012d8a63720b3a4ed07e9f255a5dae`.
- The tagged raw collection manifest matches the repository manifest, and its
role and collection selections match the released pipeline manifests.
- The public release API reports tag `v0.1.0`, title
`rakestraw.dnd 0.1.0`, `draft: false`, `prerelease: false`, and one
`rakestraw-dnd-0.1.0.tar.gz` attachment.
- The published archive has the same file list, `MANIFEST.json`, `FILES.json`,
and file payload hashes as a fresh collection build from the tagged tree.
It contains the pipeline entry point and omits the selected development-only
subtree files.
- A fresh unauthenticated clone and release-attachment download installed the
five public role tags and the collection into isolated Ansible paths. The
installed `rakestraw.dnd.pipeline` role converged successfully and its
immediate repeat reported `changed=0` and `failed=0`.
- The complete repository-local collection integration suite independently
passed isolated bootstrap, collection build and installation, syntax check,
production-profile lint, native application validation, and immediate clean
convergence.
- `git diff --check` passes for the pipeline, collection, and workspace
implementation ranges. All workspace repositories are clean and synchronized
with their upstream branches before this review finding is recorded.
A fresh collection build produced No runtime code-quality issue, release-architecture gap, test-policy violation,
`rakestraw-dnd-0.1.0.tar.gz`. The archive contains the pipeline task entry or other inadvertent requirement strengthening was found.
point and omits the selected nested tests, Ansible configuration, dependency
manifests, and Git ignore file. Installing that artifact into a temporary
collection path made `rakestraw.dnd.pipeline` discoverable. A separate
isolated bootstrap installed the unified requirements, after which syntax
checking and production-profile ansible-lint passed.
`bash -n ansible-collection-dnd/tests/integration`, manifest consistency
checks, `git diff --check`, and collection repository integrity checks also
passed during review.
After remediation, the remote-only subtree command successfully imported the
revision advertised by Gitea into a disposable repository, and a fresh
collection build succeeded. The complete collection integration entry point
then passed isolated dependency installation, artifact construction and
installation, syntax checking, production-profile lint, all retained native
application checks, and two recaps with `changed=0` and `failed=0`. The
standalone pipeline suite was not rerun because neither remediation changed
the authoritative pipeline role.

6
docs/status.md
View File

@@ -2,9 +2,9 @@
Last updated: 2026-09-17 Last updated: 2026-09-17
Current milestone: First coordinated suite release Current milestone: First coordinated suite release complete
Current focus: Independently review the Feature 0013 implementation. Current focus: Select the next unit of work.
| ID | Deliverable | Owner | State | Evidence or next step | | ID | Deliverable | Owner | State | Evidence or next step |
| --- | --- | --- | --- | --- | | --- | --- | --- | --- | --- |
@@ -29,7 +29,7 @@ Current focus: Independently review the Feature 0013 implementation.
| F0010 | Integrate D&D Notarius extraction | ansible-role-notarius and ansible-role-dnd-pipeline | done | Implemented and independently reviewed through remediation commit `bbf01e1` | | F0010 | Integrate D&D Notarius extraction | ansible-role-notarius and ansible-role-dnd-pipeline | done | Implemented and independently reviewed through remediation commit `bbf01e1` |
| F0011 | Deliver pipeline credentials and Notarius reuse | ansible-role-narratio and ansible-role-dnd-pipeline | done | Implemented and independently reviewed through remediation commit `de1b191` | | F0011 | Deliver pipeline credentials and Notarius reuse | ansible-role-narratio and ansible-role-dnd-pipeline | done | Implemented and independently reviewed through remediation commit `de1b191` |
| F0012 | Assemble the D&D collection | ansible-collection-dnd and ansible-role-dnd-pipeline | done | Pipeline `600eb21` assembled and validated through collection remediation commit `da67b34` | | F0012 | Assemble the D&D collection | ansible-collection-dnd and ansible-role-dnd-pipeline | done | Pipeline `600eb21` assembled and validated through collection remediation commit `da67b34` |
| F0013 | Publish the first coordinated suite release | all Ansible repositories and workspace | in_progress | Public `v0.1.0` tags: Audita `66ebea9`, Narratio `292d866`, Notarius `14a38e0`, Seriatim `e08c63c`, Scriptorium `8b4c86e`, pipeline `7c2bad8`, collection `63e8f3f`; [collection release](https://gitea.maximumdirect.net/eric/ansible-collection-dnd/releases/tag/v0.1.0) | | F0013 | Publish the first coordinated suite release | all Ansible repositories and workspace | done | Public [`rakestraw.dnd` 0.1.0 release](https://gitea.maximumdirect.net/eric/ansible-collection-dnd/releases/tag/v0.1.0); documentation remediation completed in pipeline `78afffe` and collection `5e695f3` |
| 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 |