8.1 KiB
Feature 0018: Adopt Scriptorium v0.15.0 in the Standalone Role
Status: done
Summary
Update the standalone Scriptorium role from v0.13.0 to v0.15.0 and expose its new application-configuration settings using our existing nullable-variable conventions. This is the first feature in the agreed application upgrade sequence.
Problem or Opportunity
Although v0.15.0 primarily changes licensing and dependency versions, the intervening v0.14.0 adopted ConfigKit and added application imports, overlays, inspection, and transient retry controls. A version bump alone would leave new configuration settings unavailable through the role's public interface.
The current role already emits {} for an unconfigured installation, omits
null optional fields, serializes mappings, and retains explicit falsey values.
Those practices remain compatible with the stricter upstream configuration
contract; no new production validation or migration mechanism is needed.
Scope
- Adopt v0.15.0 as the standalone role's default source version.
- Expose ConfigKit imports and the application transient-retry setting.
- Confirm existing configuration variables and representative backend mappings remain usable with the new application version.
- Update role documentation and focused offline integration coverage.
- Record completion and the role revision for later coordinated integration.
Non-goals
- Changing pipeline, collection, consumer, or other application-role pins.
- D&D model choices, production/testing policy, or new provider credentials.
- Deploying prompt/profile/schema libraries or managing arbitrary overlay files.
- Selecting a runtime overlay for callers, managing a service, or adding HTTP request/CLI-only controls such as execution reports and run deadlines to YAML.
- Upstream application changes, paid inference, or operational host deployment.
- Relicensing this Ansible role or copying upstream source/license material into the role repository merely because the installed application changed.
Target End State
Installation and Existing Configuration
scriptorium_version defaults to v0.15.0. Retain the existing source checkout,
Go build, ownership, and permission behavior and the caller-selected version
interface. No build-toolchain change is required: the current Go 1.26 selection
satisfies the release's Go requirement.
Existing application fields keep their public variable names. Optional variables
remain null by default and are omitted; explicit supported zero/empty values
are serialized without truthiness checks. An installation with no application
settings still receives {}, not an empty file.
New Public Variables
| Variable | Default | Rendered field |
|---|---|---|
scriptorium_configkit_imports |
null |
configkit.imports |
scriptorium_transient_retries |
null |
transient_retries |
Imports are a native list of mapping entries, consistent with the other roles' ConfigKit interfaces. Serialize the supplied list without reinterpreting path, glob, or optional-entry semantics. Emit the parent section only when selected. The caller owns referenced fragment and overlay files; ordinary inventory can compose the list without a second raw-configuration interface.
Transient retries is an optional integer. Null means omit and inherit the application/PromptKit default; zero explicitly disables additional transient attempts. The standalone role does not freeze the upstream default or add a retry budget of its own. Argument specifications and documentation describe both variables consistently.
Compatibility Guidance
Document the distinction between ConfigKit overlays/ selected by
--config-overlay and PromptKit LLM profiles. Imports are configuration-root
relative, while application path values retain their process-working-directory
semantics. Link upstream for detailed validation and precedence rules.
Call out stricter YAML acceptance and changed retry behavior, plus the removal of legacy DeepSeek catalog IDs, without installing compatibility aliases or inventing role-side configuration guards. New fields should only be supplied when selecting an application version that supports them.
Mention that Scriptorium v0.15.0's application grant is GPL-3.0-or-later and link its tagged licensing notices. Do not conflate the application's grant with the role's license or introduce legal approval as a deployment gate.
Repository Ownership
ansible-role-scriptorium: default version, variables, argument specification, template, README, and repository-local tests.- Workspace: feature roadmap, staged plan, progress, and review evidence.
- Scriptorium application: read-only tagged configuration/release contracts.
- Pipeline, collection, consumer, and asset repositories remain unchanged.
Constraints and Settled Decisions
Follow the Ansible house style, testing house style, MVP roadmap, and upgrade sequence. Review the tagged v0.15.0 contract rather than assuming later application changes apply.
The existing suite continues installing its current Scriptorium role/application pins until final integration. Standalone adoption is not suite publication.
Simplest Viable Implementation
Update the version default and extend the existing defaults, argument specification, and single configuration template with the two optional fields. Include both in the empty-document condition. Reuse the existing source/build and file/template tasks unchanged. No additional runtime tasks are needed.
Acceptance Criteria
- The default role installs v0.15.0 and native offline configuration validation accepts the default and representative managed configurations.
- Representative non-null and falsey values remain correctly rendered; the new retry field preserves explicit zero and is omitted when unset.
- A caller-supplied import is composed successfully by native configuration inspection using a small externally supplied test fragment. An optional test overlay can demonstrate native composition without adding role-owned overlay management or retesting ConfigKit's complete precedence/error matrix.
- Existing offline profile/backend inspection remains useful and passes. Application validation alone does not prove PromptKit source validity.
- Immediate repeated role application reports no changes. Tests assert supplied configuration outcomes, not today's upstream/default version, catalog contents, task arrangement, or file-module postconditions.
- Syntax/lint and repository integration checks pass without provider calls, real secrets, or operational controller access.
- Suite and consumer pins remain unchanged, and completion identifies the role commit available for the final integration feature.
Dependencies and Follow-up Work
Git history preserves the completed staged plan. Audita adoption is next. The eventual suite integration feature owns propagation of the new role revision, deployment settings, and coordinated upgrade guidance.
Completion and Review Evidence
Completed in role commits 61dcafe, 2fce529, and b174c8c. Implementation
reported passing integration tests, including native configuration validation,
offline profile inspection, imports, explicit retry zero, and clean repeat
convergence. Independent review found no code-quality issues, implementation
gaps, or unnecessarily strengthened requirements requiring remediation.
Independent syntax, production-profile lint, shell syntax, whitespace, native configuration validation, and focused template checks passed. The review used recorded integration evidence without rerunning host-mutating suites. No new production tasks or suite/collection/consumer pin changes were introduced. No operational deployment is claimed.