From 6829439807f67dcbe292033ffb93d86c7a6e8ae0 Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Tue, 29 Sep 2026 15:10:17 +0000 Subject: [PATCH] Record resolution of the suite upgrade review findings --- docs/roadmap/application-upgrade-sequence.md | 6 +- .../0022-coordinated-suite-upgrade.md | 12 + docs/roadmap/implementation.md | 8 + docs/roadmap/remediation.md | 237 +++++++++--------- docs/status.md | 6 +- 5 files changed, 143 insertions(+), 126 deletions(-) diff --git a/docs/roadmap/application-upgrade-sequence.md b/docs/roadmap/application-upgrade-sequence.md index 5c9cfa8..3d63420 100644 --- a/docs/roadmap/application-upgrade-sequence.md +++ b/docs/roadmap/application-upgrade-sequence.md @@ -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 diff --git a/docs/roadmap/features/0022-coordinated-suite-upgrade.md b/docs/roadmap/features/0022-coordinated-suite-upgrade.md index 75b40b3..319dd6d 100644 --- a/docs/roadmap/features/0022-coordinated-suite-upgrade.md +++ b/docs/roadmap/features/0022-coordinated-suite-upgrade.md @@ -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) diff --git a/docs/roadmap/implementation.md b/docs/roadmap/implementation.md index 1f2ca87..fb4a24b 100644 --- a/docs/roadmap/implementation.md +++ b/docs/roadmap/implementation.md @@ -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 diff --git a/docs/roadmap/remediation.md b/docs/roadmap/remediation.md index 7dffb6c..6661c4c 100644 --- a/docs/roadmap/remediation.md +++ b/docs/roadmap/remediation.md @@ -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. diff --git a/docs/status.md b/docs/status.md index 6986c4f..bd3323b 100644 --- a/docs/status.md +++ b/docs/status.md @@ -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 |