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

Feature 0012 Remediation Review

Status: resolved

Reviewed implementation commits:

• 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

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.

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.

Finding 1: Subtree Maintenance Commands Mix Local and Remote Sources

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.

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.

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.

Finding 2: The Collection Test Duplicates Secret-Redaction Coverage

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:

cd ansible-collection-dnd
bash -n tests/integration
tests/integration
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.

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.

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.

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.