ansible-workspace-dnd/docs/roadmap/features/0020-notarius-v0-8-adoption.md

Feature 0020: Adopt Notarius v0.8.1 in the Standalone Role

Status: done

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.

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, testing house style, MVP roadmap, and upgrade sequence. 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

Implementation and independent review are complete. Git history preserves the completed staged plan. Narratio v3 standalone adoption is next. Final integration owns the coordinated overlay/credential/configuration migration and public suite dependency updates. No open product decision is required for this narrow scope.

Implementation Evidence

• Standalone role commits: b1b922c (v0.8.1 default and optional retry interface), 380b6a3 (integration coverage), and 6aef48b (upgrade guidance). No production tasks or suite dependencies changed.
• Syntax check and production-profile lint passed. bash -n and the local integration harness passed with native offline configuration validation, rendered/effective retry checks, older-version and supplied-Go behavior, import and pipeline composition, and clean immediate repeats. Role and workspace whitespace checks passed.
• Independent review of all three role commits found no required remediation or unjustified strengthening of requirements. Syntax, production-profile lint, shell syntax, whitespace checks, and installed v0.8.1 native configuration validation passed again during review. The review used the recorded successful integration run rather than rerunning its host-mutating scenarios. No remediation document was changed.
• Reviewed standalone revision: 6aef48b. Narratio adoption and coordinated suite migration remain separate follow-up work; suite pins are unchanged.

Upstream References

• v0.8.1 configuration
• v0.8.0 migration notes
• v0.8.1 release notes