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 Release-summary and migration-guidance triage is complete. Standalone
Scriptorium, Audita, Notarius, and Narratio adoption are complete after independent Scriptorium, Audita, Notarius, and Narratio adoption are complete after independent
review. Coordinated suite integration is implemented and awaits independent review. Coordinated suite integration and its three review remediations are
review; check it off only after review and closeout. 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 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 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 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. - [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 ## 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 rerunning the long integration harness. Independent review remains required
before marking this feature done. No tagged release was created. 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 ## Upstream References
- [Audita v2 migration](https://gitea.maximumdirect.net/eric/audita/src/tag/v2.0.1/docs/migrations/v2.md) - [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 deployment, live processing, session migration, and tagged release remain
deferred. 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 ## Open Questions
None. The user approved application-owned retry/repair/deadline defaults with 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 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 The production wiring implements the approved coordinated versions, Audita
- Pipeline release commit and tag backend/profile assets, credential lists, overlay paths, and nullable retry
`7c2bad827702fdcf78f8f77ece7d6270756bc3c5` controls. The collection's imported pipeline tree exactly matches the source
- Collection subtree import role. The following test-policy and operator-documentation issues were found
`da348eb8bd9878a58404a37dbcf22ad6562ac5c9` and have now been addressed as recorded below.
- Collection release commit and tag Git history preserves the previously resolved Feature 0013 remediation record.
`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 ## Finding 1: New assertions freeze unconfigured suite defaults
Feature 0013 implements the release architecture and public consumer path. Priority: P2
The five application-role tags identify the exact reviewed commits selected by Owners: pipeline role and collection tests.
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`.
All seven repositories and tags are public and synchronized with their local Locations:
counterparts. The collection's non-draft, non-prerelease Gitea release carries - `ansible-role-dnd-pipeline/tests/integration:172`–173.
one correctly named archive. Its manifest declares `rakestraw.dnd` 0.1.0, the - `ansible-collection-dnd/tests/integration:104`–105 and 108–109.
expected Ansible baseline and collection dependencies, and its file payload
matches a fresh build from the tagged collection tree.
One low-severity documentation issue remains. The pipeline README now implies The new baseline assertions require specific Audita profile IDs and Narratio
that collection snapshots may be imported only from role releases. That credential lists, but the cases do not explicitly supply the corresponding
strengthens the settled maintenance contract beyond the requested release selection/list variables. Supplying synthetic values in `dnd_pipeline_secrets`
feature and contradicts the documented development workflow, which also does not select the credential lists. These assertions therefore fail when
permits a reviewed, pushed commit. 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 ## Finding 2: Upgrade guidance confuses configuration with session migration
“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`.
That wording accurately describes the particular snapshot used for collection Priority: P2
release 0.1.0, but it reads as the general maintenance rule. The durable Owners: pipeline README and consumer deployment guidance.
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 Locations:
unnecessary pipeline-role release merely to assemble and test a development - `ansible-role-dnd-pipeline/README.md:166`–168 and 337–338.
collection snapshot. It does not affect runtime behavior, the released - `rakestraw-ansible/docs/pipeline-dnd.md:86`–104.
dependency pins, subtree fidelity, or consumer installation.
### 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 Required correction:
concise language saying that collection maintainers import a reviewed, - Describe Audita's change as a configuration/backend/profile migration.
pushed commit or immutable tag as a snapshot. - Link Narratio v3's exact operations section
- Make no role, manifest, default, task, template, handler, or test change. `#migrating-manifest-overlay-provenance`; briefly explain backup and
- Commit and push the pipeline documentation correction before importing it `effective_config.selected_profile` → `selected_overlay` (or removal as
into the collection. upstream permits), preserving stage/checkpoint state and leaving immutable
- Refresh `roles/pipeline` through the documented squashed subtree command remote snapshots unchanged. Do not add automatic migration or forced reruns.
using the pushed pipeline documentation commit as the remote revision. Do - Correct or remove the stale claim that Notarius v0.8.1 selects PromptKit
not edit the collection's subtree copy directly. v0.10.0. Its tagged release specifies v0.11.2; prefer linking upstream release
- Confirm that the resulting collection subtree Git tree exactly matches the notes over duplicating dependency/catalog versions.
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 Validation This is a missing operator handoff, not a request for additional runtime code.
Run: ## Finding 3: Documentation makes managed secret files mandatory
```text Priority: P2
cd ansible-role-dnd-pipeline Owners: pipeline README and consumer deployment guidance.
git diff --check
cd ../ansible-collection-dnd Locations:
../.venv/bin/ansible-galaxy collection build --output-path "$(mktemp -d)" - `ansible-role-dnd-pipeline/README.md:160`–163.
git diff --check - `rakestraw-ansible/docs/pipeline-dnd.md:69`–71.
```
Also compare the imported `roles/pipeline` tree with a disposable clone of the The new text requires each credential to be supplied through
selected pushed pipeline commit. The full application, pipeline, and `dnd_pipeline_secrets`. Runtime behavior does not require that: Narratio can
collection integration suites do not need to be rerun because the remediation resolve listed names from its process environment or existing secret files.
changes documentation only and preserves all Ansible and dependency content. 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 This is an unintended documentation-level strengthening of the requirements.
`5e695f3`.
The authoritative pipeline README now states that collection maintainers may ## Review Validation
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 Shell syntax, changed-commit whitespace checks, pipeline syntax checking with
repositories. No Ansible content or dependency selection changed, so the locally available collections, production-profile lint, and collection build
integration suites were not rerun. The seven `v0.1.0` tags, published passed. Source and imported pipeline Git tree hashes match exactly. Reviewed
collection release, and release attachment remain unchanged. 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 Fix authoritative pipeline files first, then publish and re-import the corrected
Feature 0013 roadmap and implementation notes. pipeline revision through the existing public Gitea subtree workflow. Do not
- All seven Gitea repositories report public visibility and `main` as their edit its collection copy directly. Update collection-owned tests and consumer
default branch. pins/links to the corrected public snapshot as needed. Preserve all agreed
- The pipeline `v0.1.0` tree ID and the collection tag's application versions, configuration defaults, and runtime behavior. Validate
`roles/pipeline` tree ID are both affected tests in proportion to the changes; no operational deployment,
`44a9d2b010012d8a63720b3a4ed07e9f255a5dae`. credentials, live inference, or session migration is required.
- 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.
No runtime code-quality issue, release-architecture gap, test-policy violation, ## Resolution Evidence
or other inadvertent requirement strengthening was found.
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 milestone: Operational D&D pipeline deployment
Current focus: Feature 0022 implementation is complete and awaiting independent Current focus: Feature 0022's three review findings are resolved; closeout is
review. The coordinated pipeline and collection revisions are public; the pending. The corrected pipeline and collection revisions are public; the
consumer commit remains local. No operational deployment or tagged release was consumer commit remains local. No operational deployment or tagged release was
performed. Features 0018 through 0021 are complete after independent review. performed. Features 0018 through 0021 are complete after independent review.
See the [upgrade sequence](roadmap/application-upgrade-sequence.md) and 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 | | 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 | | 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 | | 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` | | A0001 | Audit completed standalone-role test suites | workspace and standalone roles | done | Findings recorded in `docs/roadmap/test-suite-audit-findings.md` |
| R0001 | Simplify completed standalone-role test suites | workspace and standalone roles | done | Role commits `e08c63c`, `d2d0b9d`, and `cfecf37` passed implementation and independent review | | R0001 | Simplify completed standalone-role test suites | workspace and standalone roles | done | Role commits `e08c63c`, `d2d0b9d`, and `cfecf37` passed implementation and independent review |