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](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.