diff --git a/docs/roadmap/features/0013-first-coordinated-suite-release.md b/docs/roadmap/features/0013-first-coordinated-suite-release.md index bb0a66d..0dd4415 100644 --- a/docs/roadmap/features/0013-first-coordinated-suite-release.md +++ b/docs/roadmap/features/0013-first-coordinated-suite-release.md @@ -1,6 +1,6 @@ # Feature 0013: Publish the First Coordinated Suite Release -Status: in_progress +Status: done ## Summary diff --git a/docs/roadmap/implementation.md b/docs/roadmap/implementation.md index 97dbd74..30fedfa 100644 --- a/docs/roadmap/implementation.md +++ b/docs/roadmap/implementation.md @@ -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: -`docs/roadmap/features/0013-first-coordinated-suite-release.md` - -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 tag v0.1.0 -git -C push origin refs/tags/v0.1.0 -git -C 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. +Select the next unit of work and agree on its numbered feature roadmap before +replacing this notice with a staged implementation plan. diff --git a/docs/roadmap/remediation.md b/docs/roadmap/remediation.md index bf7f896..7dffb6c 100644 --- a/docs/roadmap/remediation.md +++ b/docs/roadmap/remediation.md @@ -1,173 +1,147 @@ -# Feature 0012 Remediation Review +# Feature 0013 Remediation Review Status: resolved -Reviewed implementation commits: +Reviewed implementation and release state: -- `600eb21 Document standalone and collection pipeline usage` -- `3f7f82e Establish the D&D collection foundation` -- `c84aa0d Merge commit '5dbae8a' as 'roles/pipeline'` -- `10ad31c Test the assembled D&D collection` +- Application-role `v0.1.0` tags at the five roadmap-fixed commits +- Pipeline release commit and tag + `7c2bad827702fdcf78f8f77ece7d6270756bc3c5` +- 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 -Feature 0012 implements the principal target architecture. The standalone -pipeline repository remains authoritative, and collection history records its -exact `600eb21` snapshot as a squashed subtree at `roles/pipeline`. The -collection has valid Galaxy and runtime metadata, exact native collection -dependencies, one unified bootstrap manifest for the five Git-hosted roles, -focused build exclusions, and an isolated artifact-level integration entry -point. The collection builds as `rakestraw.dnd` 0.1.0 and exposes -`rakestraw.dnd.pipeline`. +Feature 0013 implements the release architecture and public consumer path. +The five application-role tags identify the exact reviewed commits selected by +the roadmap. The standalone pipeline and collection manifests use those +immutable tags, and the native collection dependencies remain pinned to +`ansible.posix` 2.2.0 and `community.general` 13.3.0. The collection subtree's +Git tree exactly matches public pipeline tag `v0.1.0`. -Two low-severity issues were found and are now resolved. The collection's -subtree maintenance examples derived a commit from the local sibling -repository but told Git to fetch that commit from a remote which did not -contain it at review time. Separately, the collection integration driver -repeated secret-redaction assertions already owned by the standalone pipeline -suite; those assertions did not validate collection assembly and strengthened -the collection test contract beyond the selected packaging boundary. +All seven repositories and tags are public and synchronized with their local +counterparts. The collection's non-draft, non-prerelease Gitea release carries +one correctly named archive. Its manifest declares `rakestraw.dnd` 0.1.0, the +expected Ansible baseline and collection dependencies, and its file payload +matches a fresh build from the tagged collection tree. -## 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 -`ansible-collection-dnd/README.md:51-63` obtains `pipeline_commit` from -`../ansible-role-dnd-pipeline`, but passes the Gitea URL as the repository -argument to both `git subtree add` and `git subtree pull`. The reviewed -pipeline commit was seven commits ahead of `origin/main` at review time; the -remote advertised `b15fe8d`, not imported commit `600eb21`. The documented -command therefore could not reproduce the current import. +`ansible-role-dnd-pipeline/README.md:51-53` says that collection maintainers +“import a reviewed release as a snapshot.” The same sentence is present in the +faithfully imported collection copy at +`ansible-collection-dnd/roles/pipeline/README.md:51-53`. -The collection artifact already contains the imported role, so consumers do -not run these commands or need a sibling checkout. The commands are the -maintainer-facing assembly interface and should also be portable outside this -workspace. The durable contract should therefore use Gitea exclusively: first -push the reviewed pipeline commit or tag to the authoritative repository, then -identify that remote revision explicitly and import it from the same URL. +That wording accurately describes the particular snapshot used for collection +release 0.1.0, but it reads as the general maintenance rule. The durable +architecture deliberately permits the collection to import any reviewed +pipeline commit that has been pushed to Gitea during development. An immutable +pipeline tag is required only when preparing a released compatibility set. +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 -- Remove the sibling-repository `git rev-parse` commands from both subtree - examples. -- Define an explicit `pipeline_revision` placeholder representing a reviewed - commit or immutable tag that has already been pushed to Gitea, and pass that - revision with the authoritative Gitea URL to both `git subtree add` and - `git subtree pull`. -- State concisely that a pipeline revision must be committed, reviewed, and - pushed to the authoritative repository before collection assembly imports - it. Do not prescribe a branch name or require a release tag during active - development; a pushed full commit ID remains valid. -- Do not add a configured remote, sibling-path assumption, synchronization - script, lock file, or private provenance state. -- Do not rewrite subtree history or reimport the current role. This is a - collection-owned documentation correction only. -- Confirm that Gitea contains the selected pipeline revision, then validate - the corrected initial command in a disposable Git repository without using - the local sibling repository as the subtree source. +- In the authoritative pipeline README, replace the release-only wording with + concise language saying that collection maintainers import a reviewed, + pushed commit or immutable tag as a snapshot. +- Make no role, manifest, default, task, template, handler, or test change. +- Commit and push the pipeline documentation correction before importing it + into the collection. +- Refresh `roles/pipeline` through the documented squashed subtree command + using the pushed pipeline documentation commit as the remote revision. Do + not edit the collection's subtree copy directly. +- Confirm that the resulting collection subtree Git tree exactly matches the + selected pushed pipeline commit outside Git metadata. +- Do not move or replace any `v0.1.0` tag, modify the published Gitea release, + or replace its attachment. Those immutable artifacts correctly describe the + historical 0.1.0 source state. +- Do not create a new role or collection release solely for this + maintainer-facing wording correction. -## Finding 2: The Collection Test Duplicates Secret-Redaction Coverage +### Required Validation -Severity: low - -`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: +Run: ```text -cd ansible-collection-dnd -bash -n tests/integration -tests/integration +cd ansible-role-dnd-pipeline +git diff --check + +cd ../ansible-collection-dnd +../.venv/bin/ansible-galaxy collection build --output-path "$(mktemp -d)" git diff --check ``` -The result must demonstrate isolated dependency bootstrap, collection build -and artifact installation, FQCN resolution, the retained native application -checks, and immediate clean convergence. The built artifact must still include -`roles/pipeline/tasks/main.yml` and exclude the selected development-only -subtree content. +Also compare the imported `roles/pipeline` tree with a disposable clone of the +selected pushed pipeline commit. The full application, pipeline, and +collection integration suites do not need to be rerun because the remediation +changes documentation only and preserves all Ansible and dependency content. -Validate the corrected subtree example against Gitea in a disposable Git -repository without modifying the real collection history or relying on the -local sibling repository as the source. The standalone pipeline integration -suite does not need to be rerun for these collection-only documentation and -test-scope changes. +## Resolution + +Resolved in pipeline commit `78afffe` and collection subtree import +`5e695f3`. + +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 -The review compared the complete standalone pipeline repository with -`roles/pipeline`; the trees are byte-for-byte identical outside Git metadata. -The root bootstrap manifest's role and collection sections exactly match the -two imported pipeline manifests, and `galaxy.yml` declares the same native -collection versions. +- Every local and remote `v0.1.0` tag resolves to the commit recorded in the + Feature 0013 roadmap and implementation notes. +- All seven Gitea repositories report public visibility and `main` as their + default branch. +- 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 -`rakestraw-dnd-0.1.0.tar.gz`. The archive contains the pipeline task entry -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. +No runtime code-quality issue, release-architecture gap, test-policy violation, +or other inadvertent requirement strengthening was found. diff --git a/docs/status.md b/docs/status.md index a1f3b8a..df34036 100644 --- a/docs/status.md +++ b/docs/status.md @@ -2,9 +2,9 @@ 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 | | --- | --- | --- | --- | --- | @@ -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` | | 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` | -| 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` | | R0001 | Simplify completed standalone-role test suites | workspace and standalone roles | done | Role commits `e08c63c`, `d2d0b9d`, and `cfecf37` passed implementation and independent review |