Prepare the Notarius upgrade implementation sprint

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/<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)