diff --git a/docs/roadmap/features/0013-first-coordinated-suite-release.md b/docs/roadmap/features/0013-first-coordinated-suite-release.md new file mode 100644 index 0000000..9061cdb --- /dev/null +++ b/docs/roadmap/features/0013-first-coordinated-suite-release.md @@ -0,0 +1,285 @@ +# Feature 0013: Publish the First Coordinated Suite Release + +Status: ready + +## Summary + +Publish the reviewed D&D pipeline as the first immutable, remotely installable +release of its five application roles, standalone pipeline role, and +`rakestraw.dnd` collection. The release establishes `v0.1.0` tags in the +projects' public Gitea repositories, replaces development commit pins with +those role tags, and makes the built `rakestraw-dnd-0.1.0.tar.gz` collection +artifact available from the collection's Gitea release. + +## Problem or Opportunity + +The application roles, pipeline role, and collection have been implemented, +reviewed, and tested as one compatible suite. Their current dependency +manifests still select application roles by development commit, however, and +none of the seven Ansible repositories has an immutable release tag. The +collection documentation consequently describes a development build rather +than a published release, and a consumer cannot bootstrap the reviewed suite +entirely from named releases and a published collection artifact. + +The initial release should turn the existing reviewed compatibility set into a +durable public installation boundary without changing application behavior or +introducing release automation. It must prove that the release is consumable +from Gitea alone rather than from sibling repositories or unpublished local +artifacts. + +## Governing Policies + +- [The Ansible house style](../../ansible.md) governs dependency manifests, + collection packaging, and concise consumer documentation. +- [The testing house style](../../testing.md) governs release validation. The + feature reuses behavior-oriented repository suites and adds only validation + specific to the remote publication boundary. +- [The planning policy](../../planning.md) governs the cross-repository + implementation and review workflow. +- [The MVP roadmap](../mvp.md) defines independent role releases, immutable + release pins, the collection as the compatibility record, and public Gitea + as the release source. +- [Feature 0012](0012-collection-assembly.md) defines the authoritative + pipeline subtree, unified consumer manifest, and assembled-artifact testing + boundary that this feature releases without redesigning. + +## Scope + +- Publish `v0.1.0` as the initial release of each standalone application role: + `rakestraw.audita`, `rakestraw.narratio`, `rakestraw.notarius`, + `rakestraw.seriatim`, and `rakestraw.scriptorium`. +- Point those application-role tags at the exact reviewed commits already + selected by the pipeline compatibility manifest. No application-role code + or default changes are part of release preparation. +- Replace the five development commit pins in the authoritative pipeline + role's root dependency manifest with the corresponding immutable `v0.1.0` + role tags. +- Update the pipeline documentation to describe the released dependency pins + and its standalone installation path without changing its role interface or + runtime behavior. +- Validate and publish `v0.1.0` of the standalone pipeline role after its + release manifest and documentation are complete. +- Import the published pipeline `v0.1.0` state into the collection's + `roles/pipeline` subtree using the established remote-only, squashed subtree + workflow. +- Replace the collection's five application-role commit pins with the same + `v0.1.0` tags used by the authoritative pipeline role, retaining the exact + `ansible.posix` and `community.general` version pins already selected. +- Retain collection version `0.1.0` in `galaxy.yml`, update collection + documentation from development-build language to released installation + instructions, and identify the release as the compatibility record for the + seven selected component versions. +- Create and push public, immutable `v0.1.0` tags for all seven Ansible + repositories. +- Build `rakestraw-dnd-0.1.0.tar.gz` from the tagged collection content and + create a concise public Gitea `v0.1.0` collection release whose attachment + is that exact artifact. +- Validate that a clean consumer can obtain the tag-pinned dependency manifest + and collection archive from their public Gitea URLs, install them into + isolated Ansible paths, invoke `rakestraw.dnd.pipeline`, and obtain an + immediate clean repeat. +- Record the completed release and its immutable compatibility set in the + workspace status and durable release-facing documentation. + +## Non-goals + +- Changing application versions, role defaults, pipeline configuration, + filesystem policy, credentials, assets, or deployed runtime behavior. +- Synchronizing future versions of independently released roles. The shared + initial version is a convenient baseline, not a lockstep release policy. +- Publishing the collection to Ansible Galaxy, Automation Hub, or another + package registry. +- Vendoring the five application roles into the collection or changing the + selected pipeline subtree model. +- Adding CI/CD, a release script, a changelog generator, dependency-update + automation, or a general-purpose release framework. +- Adding tests that snapshot manifest text, tag names, defaults, task traces, + or other implementation details. Release validation should exercise the + public installation and deployed behavior. +- Signing tags or artifacts, generating checksums or software bills of + materials, mirroring dependencies, or adding other supply-chain hardening. +- Defining upgrade, downgrade, removal, scheduling, or optional human-operator + account management. + +## Target End State + +Each public application-role repository has an immutable `v0.1.0` tag for the +exact role revision already reviewed as part of the assembled suite: + +| Role | Released revision | +| --- | --- | +| `rakestraw.audita` | `66ebea9a47ce82bfdbdc5e2855f3dfaaff8e2a16` | +| `rakestraw.narratio` | `292d8669e7aad5cfe80b0c469d22b6177e8cf0f1` | +| `rakestraw.notarius` | `14a38e04e35ef524d6a97fa7fb5a04981a0a2161` | +| `rakestraw.seriatim` | `e08c63c0b078658bdfa2d10a2e6e1e4f9372a075` | +| `rakestraw.scriptorium` | `8b4c86e48e7d8655e479b26dc510bf01683a0c8f` | + +The standalone pipeline role has its own immutable public `v0.1.0` tag. Its +role dependency manifest selects all five application roles with +`version: v0.1.0`, and its collection dependency manifest retains +`ansible.posix` 2.2.0 and `community.general` 13.3.0. The pipeline release is +independently installable under `rakestraw.dnd_pipeline`. + +The collection's `roles/pipeline` subtree is a faithful squashed import of the +published pipeline `v0.1.0` release. Its consumer-facing `requirements.yml` +contains the same five role tags and collection versions as the standalone +pipeline manifests. `galaxy.yml` remains version `0.1.0`, and the collection +repository has an immutable `v0.1.0` tag and corresponding public Gitea +release to carry the built artifact. + +The collection release includes the archive produced from that released tree, +named `rakestraw-dnd-0.1.0.tar.gz`. Its public release notes identify the exact +five application-role versions, pipeline-role version, native collection +dependencies, supported platform, and consumer bootstrap steps. A consumer +can fetch the tagged manifest and archive through public Gitea URLs and +install the suite without access to this development workspace. + +## Repository Ownership + +- The five standalone application-role repositories own their respective + `v0.1.0` tags. Their reviewed role content remains unchanged by this + feature. +- `ansible-role-dnd-pipeline` owns its tag-pinned role manifest, standalone + release documentation, and `v0.1.0` tag. +- `ansible-collection-dnd` owns the released pipeline subtree, unified + tag-pinned consumer manifest, collection release documentation, collection + tag, built artifact, and Gitea release attachment. +- `ansible-workspace-dnd` owns this roadmap, cross-repository compatibility + record, active implementation plan, progress tracking, and independent + release review. +- The application source repositories, campaign repository, prompt-library + repository, and `rakestraw-ansible` are unchanged release inputs. + +## Constraints and Settled Decisions + +- Public repositories beneath + `https://gitea.maximumdirect.net/eric/` are the authoritative publication + channel for this release. +- Every Ansible repository uses initial release tag `v0.1.0`. The collection's + Galaxy version remains the corresponding unprefixed `0.1.0`, as required by + collection metadata and artifact naming. +- Tags are immutable release boundaries. A release candidate must be validated + before its tag is created and pushed; published tags must not be moved to + repair a failed release. +- The five application-role tags identify the exact reviewed commits shown in + the target end state. Release metadata must not create otherwise unnecessary + commits in those repositories. +- Released role dependency manifests use tag names, not branches or commit + hashes. Application repositories remain independently versioned after this + shared initial baseline. +- The pipeline repository remains authoritative. Its release must be pushed + to Gitea before the collection imports the `v0.1.0` revision through the + documented remote-only subtree command. +- The collection tag identifies the exact source tree from which the attached + artifact is built. The attached file must not be rebuilt from a later or + dirty tree while retaining the same version. +- The public collection release attachment is the selected binary publication + interface. The repository tag remains the source publication interface. +- Consumer validation must not use sibling checkouts, normal user Ansible + paths, preinstalled project roles, or an unpublished local collection + archive. +- The collection's Gitea release description and existing repository + documentation are + sufficient for the initial release. This feature does not introduce + repository-local changelog files solely to duplicate those notes. + +## Simplest Viable Implementation + +Use ordinary Git tags, one collection Gitea release, existing Ansible +dependency manifests, the established subtree command, and `ansible-galaxy +collection build`. The five application roles need validation and tags only. +The pipeline and collection need small manifest and documentation changes +before their respective release tags are created. + +Reuse the existing repository-local integration entry points as release gates. +The collection integration suite already exercises isolated dependency +bootstrap, archive construction and installation, FQCN resolution, native +application behavior, and clean repeated convergence. Adapt its inputs only as +necessary to consume the release tags, and use a focused final smoke path to +download the published manifest and attached archive from Gitea. Do not add a +second release framework or duplicate the detailed behavior matrices owned by +the standalone repositories. + +Publication is intentionally manual for the first release. The work does not +yet justify release scripts, workflow files, persistent staging state, or a +new packaging service. + +## Rationale and Alternatives + +Immutable role tags give consumers meaningful versions while preserving the +settled model of independently released repositories. Publishing only commit +hashes would be reproducible but would not establish the named release +contract required by the MVP. Publishing branches would not be immutable. + +Using `v0.1.0` for every initial role and the collection makes the first +compatibility baseline easy to understand. Future role releases remain +independent, and future collection releases record whatever combination is +then supported; no synchronized-version policy is implied. + +Attaching the Galaxy-built archive to the public Gitea collection release +provides a direct installation artifact without introducing another registry. +Requiring consumers to clone and build the collection would expose unnecessary +development steps, while publishing to Ansible Galaxy or Automation Hub would +add an unselected distribution channel and account lifecycle. + +Manual publication is appropriate for one initial release and keeps the +release contract visible. Automation can be considered after repeated release +work demonstrates a stable process worth encoding. + +## Acceptance Criteria + +- Each application-role repository advertises a public, immutable `v0.1.0` + tag at the exact reviewed revision listed in this roadmap. +- Each application role's existing syntax, lint, integration, and clean-repeat + validation passes for the candidate being tagged; no role behavior is + changed merely to create the release. +- The pipeline role's released manifest selects all five application roles by + `v0.1.0`, and its collection dependency versions remain unchanged. +- The pipeline's existing validation installs its application-role + dependencies from the public Gitea tags, exercises the role through its + public interface, and passes its immediate clean repeat. +- The pipeline repository advertises a public, immutable `v0.1.0` tag at the + validated release commit. +- The collection subtree matches the published pipeline `v0.1.0` tree outside + repository-specific Git metadata and records the remote Gitea import in Git + history. +- The collection's root manifest uses the same five `v0.1.0` application-role + pins and exact native collection versions as the released pipeline role. +- `ansible-galaxy collection build` from the collection release candidate + produces `rakestraw-dnd-0.1.0.tar.gz`, and the existing artifact-boundary + exclusions remain effective. +- The collection's existing integration suite passes against the release + candidate, including isolated bootstrap, installed-artifact FQCN use, + representative native application checks, and immediate `changed=0` and + `failed=0` convergence. +- The collection repository advertises a public, immutable `v0.1.0` tag and + matching Gitea release. The archive attached to that release is the artifact + built from the tagged tree. +- A clean remote-only smoke validation downloads the public tag-pinned + manifest and public collection attachment, installs into isolated paths, + resolves `rakestraw.dnd.pipeline`, and completes with a clean immediate + repeat without referencing any sibling repository or unpublished artifact. +- Release-facing documentation no longer describes collection `0.1.0` or the + role release tags as future or unpublished, and it gives the complete public + Gitea installation path without requiring the development workspace. +- All participating repositories are clean, their release commits and tags + are present upstream, and workspace status records the published + compatibility baseline. + +## Dependencies and Follow-up Work + +Feature 0012 and its remediation must remain complete. Credentials capable of +pushing commits and tags and creating the public collection Gitea release and +attachment must be available during implementation. + +Potential later features include release automation, publication to an Ansible +registry, independently versioned follow-up releases, optional suite-level +operator membership management, and defined upgrade, downgrade, or removal +behavior. None is required for the initial release. + +## Potential Future Hardening + +- Signed Git tags or release artifacts. +- Published checksums, provenance attestations, or software bills of + materials. +- Automated verification and publication in a controlled CI environment. diff --git a/docs/roadmap/implementation.md b/docs/roadmap/implementation.md index bb7bdee..5c61d32 100644 --- a/docs/roadmap/implementation.md +++ b/docs/roadmap/implementation.md @@ -1,8 +1,787 @@ -# Implementation Plan +# Implementation Plan 0013: Publish the First Coordinated Suite Release -Status: pending +Status: proposed -Feature 0012 is complete. There is no active implementation plan. +Target executor: GPT-5.6-Terra -Select the next unit of work and agree on its numbered feature roadmap before -replacing this notice with a staged 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 + +- Not started. diff --git a/docs/roadmap/mvp.md b/docs/roadmap/mvp.md index 64802eb..637054c 100644 --- a/docs/roadmap/mvp.md +++ b/docs/roadmap/mvp.md @@ -183,10 +183,16 @@ application-role releases in one source repository. - Development dependency manifests may temporarily refer to branches or commits while the roles are changing rapidly. +- The projects' public repositories beneath + `https://gitea.maximumdirect.net/eric/` are the authoritative release + sources. Standalone roles are published through immutable Git tags. - Every released dependency manifest must pin each Git-hosted role dependency to an immutable role release tag. - The collection release is the compatibility record for the exact set of application-role versions it composes. +- A collection release consists of its immutable repository tag, matching + Gitea release, and the `ansible-galaxy collection build` archive produced + from that tagged tree and attached to the Gitea release. - Collection integration tests must install and exercise the same pinned role combination delivered to consumers, starting from an environment in which the dependencies are not already installed. diff --git a/docs/status.md b/docs/status.md index 5e38c58..d99d200 100644 --- a/docs/status.md +++ b/docs/status.md @@ -2,9 +2,9 @@ Last updated: 2026-09-17 -Current milestone: Initial role and collection architecture complete +Current milestone: First coordinated suite release -Current focus: Select the next unit of work. +Current focus: Review the Feature 0013 implementation plan. | ID | Deliverable | Owner | State | Evidence or next step | | --- | --- | --- | --- | --- | @@ -29,6 +29,7 @@ Current focus: Select the next unit of work. | 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 | ready | Review `docs/roadmap/implementation.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 |