From 760a172b34576bb49f111fda5447ee1a62422452 Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Mon, 28 Sep 2026 14:06:57 +0000 Subject: [PATCH] Prepare the Notarius upgrade implementation sprint --- docs/roadmap/application-upgrade-sequence.md | 2 +- .../features/0020-notarius-v0-8-adoption.md | 155 ++++++++++++ docs/roadmap/implementation.md | 224 +++++++++++++++++- docs/status.md | 4 +- 4 files changed, 374 insertions(+), 11 deletions(-) create mode 100644 docs/roadmap/features/0020-notarius-v0-8-adoption.md diff --git a/docs/roadmap/application-upgrade-sequence.md b/docs/roadmap/application-upgrade-sequence.md index e0e426c..cce49f8 100644 --- a/docs/roadmap/application-upgrade-sequence.md +++ b/docs/roadmap/application-upgrade-sequence.md @@ -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. diff --git a/docs/roadmap/features/0020-notarius-v0-8-adoption.md b/docs/roadmap/features/0020-notarius-v0-8-adoption.md new file mode 100644 index 0000000..b2b304e --- /dev/null +++ b/docs/roadmap/features/0020-notarius-v0-8-adoption.md @@ -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/.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) diff --git a/docs/roadmap/implementation.md b/docs/roadmap/implementation.md index 815eff6..ad78087 100644 --- a/docs/roadmap/implementation.md +++ b/docs/roadmap/implementation.md @@ -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/.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. diff --git a/docs/status.md b/docs/status.md index df961c8..282801e 100644 --- a/docs/status.md +++ b/docs/status.md @@ -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 |