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

Record resolution of the suite upgrade review findings

Browse Source
This commit is contained in:
Eric Rakestraw
2026-09-29 15:10:17 +00:00
parent fec2f89b48
commit 6829439807
5 changed files with 143 additions and 126 deletions
Download Patch File Download Diff File Expand all files Collapse all files

6
docs/roadmap/application-upgrade-sequence.md
View File

@@ -32,14 +32,14 @@ Seriatim is unchanged by this sequence.
Release-summary and migration-guidance triage is complete. Standalone
Scriptorium, Audita, Notarius, and Narratio adoption are complete after independent
review. Coordinated suite integration is implemented and awaits independent
review; check it off only after review and closeout.
review. Coordinated suite integration and its three review remediations are
implemented; check it off after closeout.
- [x] [Feature 0018: Scriptorium adoption](features/0018-scriptorium-v0-15-adoption.md) — complete through role `b174c8c`; independent review found no remediation issues.
- [x] [Feature 0019: Audita adoption](features/0019-audita-v2-adoption.md) — complete through role `c3dd59f`; independent review found no remediation issues.
- [x] [Feature 0020: Notarius adoption](features/0020-notarius-v0-8-adoption.md) — complete through role `6aef48b`; independent review found no remediation issues; suite unchanged.
- [x] [Feature 0021: Narratio adoption](features/0021-narratio-v3-adoption.md) — complete through role `3c0700b`; independent review found no remediation issues; suite unchanged.
- [ ] [Feature 0022: Coordinated suite integration](features/0022-coordinated-suite-upgrade.md) — implementation complete at public pipeline `ea8b09e`, public collection `3d77eb3`, and local consumer `f694dad`; independent review pending.
- [ ] [Feature 0022: Coordinated suite integration](features/0022-coordinated-suite-upgrade.md) — three review findings resolved at public pipeline `37b1cf6`, public collection `b3bc045`, and local consumer `15f0f4e`; closeout pending.
## Adoption Boundaries

12
docs/roadmap/features/0022-coordinated-suite-upgrade.md
View File

@@ -269,6 +269,18 @@ line was checked with `bash -n`, JSON parsing, and `git diff --check` without
rerunning the long integration harness. Independent review remains required
before marking this feature done. No tagged release was created.
## Remediation Follow-up
The three independent-review findings are resolved; see
[remediation evidence](../remediation.md). Public pipeline `37b1cf6` and
collection `b3bc045` remove default-identity assertions and correct migration
and credential guidance. Local consumer `15f0f4e` selects the corrected public
snapshot. Shell/whitespace checks, pipeline and installed-collection syntax and
lint, collection build/install, and real-inventory consumer target/syntax checks
passed. Full host-mutating convergence was not rerun for these documentation
and test-only changes. Application versions/defaults and runtime behavior are
unchanged. Feature closeout remains pending.
## Upstream References
- [Audita v2 migration](https://gitea.maximumdirect.net/eric/audita/src/tag/v2.0.1/docs/migrations/v2.md)

8
docs/roadmap/implementation.md
View File

@@ -424,6 +424,14 @@ had started.
deployment, live processing, session migration, and tagged release remain
deferred.
## Remediation Follow-up
The independent review's three findings are resolved in public pipeline
`37b1cf6`, public collection `b3bc045`, and local consumer `15f0f4e`.
See [remediation.md](remediation.md) for per-finding evidence and validation
limits. Runtime implementation and application defaults are unchanged;
feature closeout remains pending.
## Open Questions
None. The user approved application-owned retry/repair/deadline defaults with

237
docs/roadmap/remediation.md
View File

@@ -1,147 +1,144 @@
# Feature 0013 Remediation Review
# Feature 0022 Remediation Review
Status: resolved
Reviewed implementation and release state:
Reviewed on 2026-09-29:
- Pipeline `8ea8621` and `ea8b09e`.
- Collection subtree import through `a78c309` and assembly `3d77eb3`.
- Consumer `f694dad`.
- 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`
The production wiring implements the approved coordinated versions, Audita
backend/profile assets, credential lists, overlay paths, and nullable retry
controls. The collection's imported pipeline tree exactly matches the source
role. The following test-policy and operator-documentation issues were found
and have now been addressed as recorded below.
Git history preserves the previously resolved Feature 0013 remediation record.
## Review Summary
## Finding 1: New assertions freeze unconfigured suite defaults
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`.
Priority: P2
Owners: pipeline role and collection tests.
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.
Locations:
- `ansible-role-dnd-pipeline/tests/integration:172`–173.
- `ansible-collection-dnd/tests/integration:104`–105 and 108–109.
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.
The new baseline assertions require specific Audita profile IDs and Narratio
credential lists, but the cases do not explicitly supply the corresponding
selection/list variables. Supplying synthetic values in `dnd_pipeline_secrets`
does not select the credential lists. These assertions therefore fail when
legitimate defaults change, even if installation and caller overrides work.
## Finding 1: Pipeline Documentation Narrows Subtree Imports to Releases
Required correction: remove redundant default-identity assertions from the
baseline smoke case, or explicitly supply the relevant public inputs and
assert those values. The pipeline already has a useful custom-credential
override case; prefer reusing its coverage. Keep native validation and clean
repeats. Do not replace literals by reading role defaults into expectations;
that would still test implementation identity rather than caller behavior.
Severity: low
This strengthens acceptance beyond the user's state-based testing policy.
The approved plan explicitly asked for supplied-value tests, not default
snapshots.
`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`.
## Finding 2: Upgrade guidance confuses configuration with session migration
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.
Priority: P2
Owners: pipeline README and consumer deployment guidance.
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.
Locations:
- `ansible-role-dnd-pipeline/README.md:166`–168 and 337–338.
- `rakestraw-ansible/docs/pipeline-dnd.md:86`–104.
### Required Remediation
The pipeline links “Audita's v2 manifest migration” to Audita's configuration
migration guide, but does not identify Narratio's actual session-manifest
migration. The consumer likewise refers to “Audita manifests” and only
generically warns about Narratio manifests. The roadmap specifically requires
guidance on backing up and migrating local provenance while preserving
progress and immutable snapshots. Existing Narratio manifests containing
`effective_config.selected_profile` are rejected by v3.
- 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.
Required correction:
- Describe Audita's change as a configuration/backend/profile migration.
- Link Narratio v3's exact operations section
`#migrating-manifest-overlay-provenance`; briefly explain backup and
`effective_config.selected_profile` → `selected_overlay` (or removal as
upstream permits), preserving stage/checkpoint state and leaving immutable
remote snapshots unchanged. Do not add automatic migration or forced reruns.
- Correct or remove the stale claim that Notarius v0.8.1 selects PromptKit
v0.10.0. Its tagged release specifies v0.11.2; prefer linking upstream release
notes over duplicating dependency/catalog versions.
### Required Validation
This is a missing operator handoff, not a request for additional runtime code.
Run:
## Finding 3: Documentation makes managed secret files mandatory
```text
cd ansible-role-dnd-pipeline
git diff --check
Priority: P2
Owners: pipeline README and consumer deployment guidance.
cd ../ansible-collection-dnd
../.venv/bin/ansible-galaxy collection build --output-path "$(mktemp -d)"
git diff --check
```
Locations:
- `ansible-role-dnd-pipeline/README.md:160`–163.
- `rakestraw-ansible/docs/pipeline-dnd.md:69`–71.
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.
The new text requires each credential to be supplied through
`dnd_pipeline_secrets`. Runtime behavior does not require that: Narratio can
resolve listed names from its process environment or existing secret files.
The README's existing managed-credentials section already describes environment
precedence and an empty default secrets map.
## Resolution
Required correction: require the credential names in the forwarding lists,
but describe managed secret files as the suite-supported provisioning option,
not the only permitted source. Preserve the consumer's chosen Vault workflow
without imposing it on every standalone suite user. No code or new tests are
needed for this wording correction.
Resolved in pipeline commit `78afffe` and collection subtree import
`5e695f3`.
This is an unintended documentation-level strengthening of the requirements.
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`.
## Review Validation
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.
Shell syntax, changed-commit whitespace checks, pipeline syntax checking with
locally available collections, production-profile lint, and collection build
passed. Source and imported pipeline Git tree hashes match exactly. Reviewed
the recorded successful role/collection integration and consumer syntax runs;
did not rerun host-mutating convergence. A fresh dependency installation stalled
and was stopped, so this review does not independently establish a complete
fresh public dependency installation. No operational host was contacted.
## Review Validation Evidence
## Remediation Boundaries
- 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.
Fix authoritative pipeline files first, then publish and re-import the corrected
pipeline revision through the existing public Gitea subtree workflow. Do not
edit its collection copy directly. Update collection-owned tests and consumer
pins/links to the corrected public snapshot as needed. Preserve all agreed
application versions, configuration defaults, and runtime behavior. Validate
affected tests in proportion to the changes; no operational deployment,
credentials, live inference, or session migration is required.
No runtime code-quality issue, release-architecture gap, test-policy violation,
or other inadvertent requirement strengthening was found.
## Resolution Evidence
All three findings were addressed on 2026-09-29:
- Finding 1: pipeline `37b1cf6` removes redundant baseline credential-list
assertions while preserving custom-input coverage; collection `d9abb62`
removes default profile-ID and credential-list assertions. Native profile
inspection, configuration validation, and immediate clean-repeat checks remain.
- Findings 2 and 3: pipeline `37b1cf6` and consumer `15f0f4e` distinguish
Audita configuration migration from Narratio session migration, link the
exact provenance procedure, preserve progress and immutable snapshots,
and allow environment or file-based credential provisioning. The stale
Notarius dependency/catalog claim is replaced by tagged release guidance.
- The public pipeline revision is
`37b1cf6fab71c6a1212e49357c2e825cb0237a00`; collection subtree import and
public revision `b3bc0457efb7ea14ed11789978edd440537860fc` contain its exact
Git tree. Both remote branch heads were independently checked with
`git ls-remote`. Consumer `15f0f4e` selects that collection and links the
corrected source README; the consumer commit remains local.
- Shell syntax and whitespace checks passed. Pipeline and installed-collection
syntax checks and production-profile lint passed. Collection build and
disposable artifact installation passed. Consumer real-inventory host
listing selected only `pipeline-dnd`, and syntax checking passed without
deployment or Vault decryption.
- Validation used the previously downloaded public role dependencies and
available local collections. Full host-mutating integration was not rerun:
production code/defaults are unchanged, test changes remove assertions and
unused parsing, and prior full-run evidence remains applicable to unchanged
behavior. No operational system or session state was modified.

6
docs/status.md
View File

@@ -4,8 +4,8 @@ Last updated: 2026-09-29
Current milestone: Operational D&D pipeline deployment
Current focus: Feature 0022 implementation is complete and awaiting independent
review. The coordinated pipeline and collection revisions are public; the
Current focus: Feature 0022's three review findings are resolved; closeout is
pending. The corrected pipeline and collection revisions are public; the
consumer commit remains local. No operational deployment or tagged release was
performed. Features 0018 through 0021 are complete after independent review.
See the [upgrade sequence](roadmap/application-upgrade-sequence.md) and
@@ -43,7 +43,7 @@ See the [upgrade sequence](roadmap/application-upgrade-sequence.md) and
| F0019 | Adopt Audita v2.0.1 | Audita role and workspace | done | Role `c3dd59f`, following `6137ff2` and `52f67fe`, passed independent review with no findings; [roadmap](roadmap/features/0019-audita-v2-adoption.md) records validation; suite pins unchanged |
| F0020 | Adopt Notarius v0.8.1 | Notarius role and workspace | done | Role `6aef48b`, following `b1b922c` and `380b6a3`, passed independent review with no findings; [feature roadmap](roadmap/features/0020-notarius-v0-8-adoption.md) records evidence; suite pins unchanged |
| F0021 | Adopt Narratio v3.0.0 | Narratio role and workspace | done | Role `3c0700b`, following `a28f22c` and `45f6836`, passed independent review with no findings; [feature roadmap](roadmap/features/0021-narratio-v3-adoption.md) records evidence; suite pins unchanged |
| F0022 | Integrate the reviewed application upgrades | Pipeline role, collection, consumer, and workspace | in_progress | Implementation complete; public pipeline `ea8b09e`, public collection `3d77eb3`, local consumer `f694dad`; [evidence](roadmap/features/0022-coordinated-suite-upgrade.md) awaits independent review |
| F0022 | Integrate the reviewed application upgrades | Pipeline role, collection, consumer, and workspace | in_progress | Three review findings resolved; public pipeline `37b1cf6`, public collection `b3bc045`, local consumer `15f0f4e`; [remediation evidence](roadmap/remediation.md); closeout pending |
| 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 |