ansible-workspace-dnd/docs/roadmap/implementation.md

Implementation Plan 0020: Adopt Notarius v0.8.1

Status: ready

Target executor: GPT-5.6-Terra

Feature roadmap: Feature 0020

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:

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:

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:

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.

Open Questions

None.