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

Close out the standalone Notarius upgrade

Browse Source
This commit is contained in:
Eric Rakestraw
2026-09-28 14:36:06 +00:00
parent a0414244bb
commit e93ebea771
4 changed files with 27 additions and 251 deletions
Download Patch File Download Diff File Expand all files Collapse all files

247
docs/roadmap/implementation.md
View File

@@ -1,241 +1,12 @@
# Implementation Plan 0020: Adopt Notarius v0.8.1
# Implementation Plan
Status: implemented — independent review pending
No implementation plan is currently active. Agree on the next feature roadmap
before preparing its staged plan.
Target executor: GPT-5.6-Terra
Feature 0020 is complete and independently reviewed with no remediation
findings. See [its roadmap](features/0020-notarius-v0-8-adoption.md) for
completion evidence. Git history preserves the completed plan.
Feature roadmap: [Feature 0020](features/0020-notarius-v0-8-adoption.md)
## Objective
Update the standalone Notarius role to v0.8.1 and expose its optional transport
retry setting. The feature roadmap owns scope, rationale, and acceptance
criteria. Suite adoption remains deferred to coordinated integration.
## Execution Rules and Preconditions
- Execute stages in order. Reread each stage's required policies immediately
before beginning it, including applicable repository instructions.
- Confirm working-tree state before editing and preserve unrelated changes.
Commit each valid completed stage with a plain English message. Do not push.
- Only `ansible-role-notarius` and workspace planning/status documents may
change. Inspect `../notarius` read-only at tags v0.8.0 and v0.8.1.
- Keep pipeline, collection, consumer, assets, and other roles unchanged.
Retain the suite's Notarius v0.7.1 application and existing dependency pins;
do not import the new standalone role into the collection.
- No new production tasks, state probes, migration aliases, role-managed
overlay assets, or cache cleanup are needed. Preserve the existing build
and configuration convergence flow.
- Use workspace `.venv/bin` tools. A missing executable on PATH does not mean
Ansible is unavailable. The existing integration script selects these tools
and installs its declared collection dependency.
- Integration runs locally with sudo, not on a controller or pipeline host.
The existing harness modifies local source, binary, and configuration paths
and restores baseline configuration on exit. Confirm those test locations
are disposable before running. Source/dependency downloads are needed;
credentials, provider calls, and operational deployment are not.
- Report genuine environment limitations and checks completed. Do not invent
new acceptance gates or expand scope to overcome an unrelated limitation.
## Stage 1: Update the Application and Public Configuration Interface
Completion: complete (2026-09-28).
### Required Policy Review
Read workspace `AGENTS.md`, `docs/orientation.md`, `docs/conventions.md`,
`docs/ansible.md`, and `docs/planning.md`, plus applicable role instructions.
### Owning Repositories and Preconditions
`ansible-role-notarius` owns implementation; workspace owns progress.
Feature 0020 is approved. Inspect existing defaults, argument specifications,
template, and tasks, plus tagged upstream configuration and release notes.
### Required Changes
1. Mark F0020 `in_progress` in workspace status when implementation starts.
2. Set `notarius_version` to `v0.8.1` in role `defaults/main.yml`. Preserve
schema version 5, Go selection, paths, ownership, and existing interfaces.
3. Add `notarius_promptkit_transient_retries: null`. Declare it as an optional
integer in `meta/argument_specs.yml`.
4. In `templates/config.yml.j2`, emit `promptkit.transient_retries` when the
variable `is not none`, preserving integer zero. Add it to the enclosing
PromptKit section condition so retry-only configuration works. It is a
sibling of `profile_dir`, `profile_file`, and `local_backend`.
5. Document the variable, native field, null omission, and zero semantics in
the README public interface. Do not duplicate the upstream retry default
or add custom validation.
### Validation
From the workspace root:
```sh
ANSIBLE_ROLES_PATH="$PWD" .venv/bin/ansible-playbook -i ansible-role-notarius/tests/inventory --syntax-check ansible-role-notarius/tests/converge.yml
ANSIBLE_ROLES_PATH="$PWD" .venv/bin/ansible-lint ansible-role-notarius/tests/converge.yml ansible-role-notarius/tests/prepare-import.yml
git -C ansible-role-notarius diff --check
git diff --check
```
Static checks must pass. Review the diff for consistent defaults, argument
specification, template, and documentation, with no production task or suite
pin changes. Behavioral rendering validation follows in Stage 2.
### Completion and Commit
The new standalone interface is consistent and static checks pass. Commit the
role as `Update Notarius and expose transport retries`; commit workspace
progress separately as `Record the Notarius upgrade in progress`.
## Stage 2: Test Optional Retry Rendering and Retain Existing Outcomes
Completion: complete (2026-09-28).
### Required Policy Review
Read workspace `AGENTS.md`, `docs/orientation.md`, `docs/conventions.md`,
`docs/ansible.md`, and `docs/testing.md`, plus applicable role instructions.
### Owning Repository and Preconditions
`ansible-role-notarius`. Stage 1 is committed and static checks pass. Read the
existing integration script and fixtures. Confirm the local test environment
is suitable as described above. Extend the harness rather than introducing a
parallel framework.
### Required Changes
1. In the baseline case, explicitly supply null for the retry variable and
inspect rendered YAML for absence of `promptkit.transient_retries`. Do not
use effective configuration to prove omission: it can include application
defaults. Retain native validation and the immediate clean repeat.
2. Add one retry-only case before the older-version selection: supply integer
zero while other PromptKit variables remain null. Check the rendered
nested value, run native `config validate`, and inspect `config effective`
for zero. Immediately repeat identical inputs and require an overall
zero-change recap. This protects falsey rendering and parent inclusion.
3. Supply retry zero in the existing representative configuration case and
verify it through native effective configuration. Preserve import/pipeline
composition, cache false/bypass behavior, and the clean repeat. Reuse
concise assertions; parsed YAML is suitable for nested omission/value
checks. Do not snapshot complete documents.
4. Retain explicit v0.7.0 selection and supplied-Go/missing-binary recovery.
Leave the new retry field unset in those older-release invocations; do not
leak inputs from preceding cases. Keep the default-version smoke check
informational rather than asserting today's default version indefinitely.
5. Do not add overlay migration tests, provider calls, retry-exhaustion
matrices, checkpoint invalidation tests, or checks of module-owned file
metadata. These are not behavior newly owned by the role.
### Validation
From the workspace root:
```sh
bash -n ansible-role-notarius/tests/integration
ansible-role-notarius/tests/integration
git -C ansible-role-notarius diff --check
```
The harness includes syntax/lint. Require native offline acceptance of the
managed configurations, supplied retry outcomes, retained version/Go/import
behavior, and clean immediate repeats. Do not add a file-existence check after
a successful template operation.
### Completion and Commit
Existing meaningful cases and focused retry cases pass without live provider
calls. Save command/results for handoff. Commit the role as `Test optional
Notarius transport retries`.
## Stage 3: Document Compatibility and Prepare Independent Review
Completion: complete (2026-09-28).
### Required Policy Review
Read workspace `AGENTS.md`, `docs/orientation.md`, `docs/conventions.md`,
`docs/ansible.md`, `docs/testing.md`, and `docs/planning.md`, plus applicable
role instructions.
### Owning Repositories and Preconditions
`ansible-role-notarius` and workspace. Stages 1 and 2 are committed and their
checks pass. This is documentation/handoff, not suite integration or closeout.
### Required Changes
1. Update the role README's release and upgrade guidance. Explain
`--config-overlay` and `overlays/<name>.yml` replacing the retired ConfigKit
selector/directory. Distinguish these from unchanged PromptKit LLM-profile
sources, pipeline `llm_profile`, and `--llm-profile`.
2. Explain that callers own overlay files and invocation. Suite testing-file
and Narratio-selector migration await coordinated integration. Do not add
role variables or file-moving tasks for this.
3. Describe transport retries as additional eligible transient attempts per
generation, separate from pipeline/validator retries. Null inherits native
behavior; zero disables additional attempts. Link tagged upstream guidance
instead of prescribing new D&D retry budgets.
4. Note v0.8.1's profile-source checkpoint identity change: old matching
checkpoints are not reused; source-keyed chunk plans and published output
are unaffected. No deletion, forced stages, or automated migration.
5. Record role commits and validation evidence in the feature roadmap;
update this plan's progress notes, `docs/status.md`, and
`docs/roadmap/application-upgrade-sequence.md` concisely. Leave F0020
`in_progress`, awaiting independent review. Do not describe the revision as
reviewed or check off the sequence item yet.
### Validation
Review documentation against tagged upstream contracts and implemented
variables. From the workspace root:
```sh
git -C ansible-role-notarius diff --check
git diff --check
scripts/status
```
Confirm only the role and workspace changed; suite/collection/consumer pins
remain untouched. Reuse Stage 2 evidence for documentation-only changes;
rerun affected checks if implementation changes.
### Completion and Commit
Documentation describes the standalone contract and deferred integration.
Commit the role as `Document the Notarius overlay upgrade`, then workspace
tracking as `Record Notarius upgrade validation`.
## Final Validation and Handoff
Report commit hashes, checks and outcomes, environment limitations or
deviations, and final working-tree state. Identify any added complexity and
its requirement. Leave the feature awaiting independent review; closeout will
record the reviewed revision. Narratio adoption is next, then suite integration.
Do not publish or deploy from this plan.
## Progress Notes
Plan approved.
- Stage 1: role commit `b1b922c`. Syntax check and production-profile lint
passed for the role's integration playbooks. Role and workspace
`git diff --check` passed. The role diff contains only defaults, argument
specifications, the configuration template, and README; no production task
or suite pin changed.
- Stage 2: `bash -n` and the local integration harness passed. Parsed rendered
YAML confirms null omission and retry-only zero; native validation and
effective configuration confirm zero in both retry-only and representative
cases. Existing v0.7.0 selection, supplied-Go recovery, imports, pipelines,
cache behavior, and clean immediate repeats passed. Role `git diff --check`
passed.
- Stage 3: role commits `b1b922c`, `380b6a3`, and `6aef48b` provide the
implementation and documentation. The README was checked against tagged
v0.8.0/v0.8.1 upstream guidance. Documentation-only changes reused Stage 2
integration evidence; role and workspace `git diff --check` and
`scripts/status` passed. F0020 remains open for independent review.
## Open Questions
None.
Narratio v3 standalone adoption is next in the agreed
[application upgrade sequence](application-upgrade-sequence.md). Suite and
consumer pins remain unchanged until coordinated integration.