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

Prepare the Notarius upgrade implementation sprint

Browse Source
This commit is contained in:
Eric Rakestraw
2026-09-28 14:06:57 +00:00
parent 8111f66de5
commit 760a172b34
4 changed files with 374 additions and 11 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -37,7 +37,7 @@ is created; check it off after independent review and 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.
- [ ] Notarius adoption — feature roadmap not yet created.
- [ ] [Feature 0020: Notarius adoption](features/0020-notarius-v0-8-adoption.md) — roadmap and staged plan approved; ready for implementation.
- [ ] Narratio adoption — feature roadmap not yet created.
- [ ] Suite integration — feature roadmap not yet created.

155
docs/roadmap/features/0020-notarius-v0-8-adoption.md Normal file
View File

@@ -0,0 +1,155 @@
# Feature 0020: Adopt Notarius v0.8.1 in the Standalone Role
Status: ready
## Summary
Update the standalone Notarius role from v0.7.1 to v0.8.1, expose the new
PromptKit transient-retry setting, and document the ConfigKit overlay rename.
This is the third feature in the agreed
[application upgrade sequence](../application-upgrade-sequence.md).
## Problem or Opportunity
Notarius v0.8.0 renamed configuration selection to `--config-overlay` and
`overlays/<name>.yml`, removing the previous flag and lookup directory. It also
introduced configurable provider transport retries. v0.8.1 updates ConfigKit
and PromptKit to v0.4.2 and v0.11.2 without further intentional configuration or
subprocess-contract changes.
The standalone role currently renders schema version 5, supports native imports
and caller-supplied pipelines, and leaves profile assets externally managed.
Those boundaries remain appropriate. The suite, however, still uses the old
downstream selector; its application and dependency pins must not advance yet.
## Scope
- Default the standalone role to Notarius v0.8.1.
- Expose `promptkit.transient_retries` through one nullable role variable.
- Verify existing imports, pipeline composition, profile-source settings, and
cache configuration remain compatible with the target release.
- Update standalone compatibility guidance and focused offline tests.
- Record the reviewed role revision for later coordinated suite integration.
## Non-goals
- Updating suite, collection, consumer, or other application-role pins.
- Migrating suite-owned testing files or Narratio's downstream selector.
- Deploying arbitrary overlay or LLM-profile assets in the generic role.
- Choosing D&D model, retry, timeout, or credential policy.
- Automatic renames, compatibility aliases, cache deletion, forced extraction,
or production validation tasks.
- Upstream application changes, live inference, or operational deployment.
## Target End State
### Installation and Configuration
`notarius_version` defaults to `v0.8.1`. Configuration remains schema version 5.
Preserve existing build, dependency, path, and owner/group/mode interfaces.
The existing Go selection remains unchanged.
Add `notarius_promptkit_transient_retries: null`, documented and declared as an
optional integer in argument specifications. When non-null, serialize it as
`promptkit.transient_retries`. Include it in the parent-section condition so a
retry-only configuration renders correctly. Null means omit the field; zero
disables additional transient attempts. Do not copy PromptKit's default into
role defaults, add a second retry mechanism, or reinterpret existing module
and validator retry settings.
Keep all existing supported native configuration variables. Preserve caller
mapping/list composition and omission of unset optional settings. The role does
not resolve, inspect, or rewrite caller-owned profile or overlay files.
### Overlay Migration Guidance
Document `--config-overlay` and the conventional `overlays/` directory for
operators invoking the new application. The old `--config-profile` and ConfigKit
`profiles/` lookup no longer work. This does not rename PromptKit LLM-profile
sources: `notarius_promptkit_profile_dir`, `notarius_promptkit_profile_file`,
pipeline `llm_profile`, and `--llm-profile` retain their separate meanings.
Caller-owned configuration overlay files must be migrated by their owner. In
this workspace the D&D suite owns its testing overlay, so that migration belongs
to final integration together with Narratio's new selector. Do not add generic
file-moving tasks or broaden this feature to fix the old suite in place.
### Retry and Checkpoint Compatibility
Explain that transport retries are additional attempts per generation and are
separate from pipeline/validator retries. Omission inherits upstream behavior;
operators may explicitly select zero. Later suite planning will review combined
retry and timeout budgets rather than copying old values mechanically.
Document v0.8.1's changed profile-source checkpoint identity: old matching
checkpoint identities are not reused, while source-keyed chunk plans and
published output are unaffected. Leave cache lifecycle with Notarius and do not
delete data or force Narratio stages as part of installing the role.
## Repository Ownership
- `ansible-role-notarius`: version default, optional retry field, argument
specification, template, documentation, and repository-local tests.
- Workspace: feature roadmap, staged plan, progress, and independent review.
- Notarius application: read-only tagged configuration/release contracts.
- Pipeline, collection, consumer, other roles, and assets remain unchanged.
## Constraints and Settled Decisions
Follow the [Ansible house style](../../ansible.md),
[testing house style](../../testing.md), [MVP roadmap](../mvp.md), and
[upgrade sequence](../application-upgrade-sequence.md). Use v0.8.1's contract,
including the intervening v0.8.0 migration notes, not assumptions from a newer
application checkout.
Retain meaningful tests that explicitly install v0.7.0 to prove caller-selected
version behavior. Leave the new retry field unset in those older-version cases;
do not change them merely because the role default advances.
## Simplest Viable Implementation
Update the application version and add one optional variable, argument-spec
entry, and conditional template field. Extend the existing integration fixture
with explicit retry zero and native configuration inspection. No new production
tasks, state probes, compatibility framework, or role-managed assets are needed.
## Rationale and Alternatives
The role manages persistent configuration; application invocation owns overlay
selection. Adding an overlay-selection variable or file-migration tasks here
would confuse those responsibilities. Documenting the breaking invocation
change and coordinating it later preserves independently usable roles and the
existing suite compatibility set.
## Acceptance Criteria
- The default role installs v0.8.1, and native offline validation accepts the
baseline and representative managed configurations.
- Null retry selection is omitted; explicitly supplied zero is rendered and
visible through native effective-configuration inspection. A retry-only
configuration produces its enclosing PromptKit section.
- Existing useful coverage for native import/pipeline composition, profile
configuration, cache settings, selected application version, and supplied Go
executable remains valid. Do not add a comprehensive upstream schema matrix.
- Immediate repeat convergence reports no changes. Tests assert supplied values
and role outcomes, not today's version/catalog defaults or module postconditions.
- Documentation accurately distinguishes configuration overlays from LLM
profiles and describes retry/checkpoint upgrade consequences.
- Syntax/lint and repository integration checks pass without live provider
calls or operational-host access.
- Suite, collection, and consumer pins stay unchanged; the reviewed standalone
revision is recorded for final integration.
## Dependencies and Follow-up Work
The roadmap is approved; execution is defined in the
[implementation plan](../implementation.md). Narratio v3 standalone adoption
follows independent review and closeout. Final integration
owns the coordinated overlay/credential/configuration migration and public suite
dependency updates. No open product decision is required for this narrow scope.
## Upstream References
- [v0.8.1 configuration](https://gitea.maximumdirect.net/eric/notarius/src/tag/v0.8.1/docs/config.md)
- [v0.8.0 migration notes](https://gitea.maximumdirect.net/eric/notarius/src/tag/v0.8.0/docs/releases/v0.8.0.md)
- [v0.8.1 release notes](https://gitea.maximumdirect.net/eric/notarius/src/tag/v0.8.1/docs/releases/v0.8.1.md)

224
docs/roadmap/implementation.md
View File

@@ -1,12 +1,218 @@
# Implementation Plan
# Implementation Plan 0020: Adopt Notarius v0.8.1
No implementation plan is currently active. Agree on the next feature roadmap
before preparing its staged plan.
Status: ready
Feature 0019 is complete and independently reviewed with no remediation
findings. See [its roadmap](features/0019-audita-v2-adoption.md) for completion
evidence. Git history preserves the completed plan.
Target executor: GPT-5.6-Terra
Notarius standalone adoption is next in the agreed
[application upgrade sequence](application-upgrade-sequence.md). Suite and
consumer pins remain unchanged until coordinated integration.
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
### 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
### 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
### 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; implementation has not started.
## Open Questions
None.

4
docs/status.md
View File

@@ -4,7 +4,8 @@ Last updated: 2026-09-28
Current milestone: Operational D&D pipeline deployment
Current focus: Prepare the Notarius v0.8.1 standalone adoption roadmap next.
Current focus: Implement Feature 0020's Notarius v0.8.1 standalone adoption.
The feature roadmap and staged implementation plan are approved.
Features 0018 and 0019 are complete after independent review with no remediation
findings. Follow the agreed
[application upgrade sequence](roadmap/application-upgrade-sequence.md):
@@ -42,6 +43,7 @@ is complete.
| F0017 | Compose the Notarius testing overlay | Narratio role, pipeline role, collection, consumer, and workspace | done | Published through Narratio `330afe7`, Notarius `a82a83d`, pipeline `c56a942`, collection `ce5b838`, and consumer `0ced48c`; independent review found no remediation issues; validation evidence is in the feature roadmap |
| F0018 | Adopt Scriptorium v0.15.0 | Scriptorium role and workspace | done | Role commits `61dcafe`, `2fce529`, and `b174c8c` passed independent review with no findings; feature roadmap 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 | ready | [Feature roadmap](roadmap/features/0020-notarius-v0-8-adoption.md) and [staged plan](roadmap/implementation.md) approved; suite pins and testing overlay migration remain deferred |
| 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 |