Record resolution of the suite upgrade review findings
This commit is contained in:
@@ -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.
|
||||
|
||||
Reference in New Issue
Block a user