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

Implementation Plan 0018: Standalone Scriptorium v0.15.0 Adoption

Status: ready

Target executor: GPT-5.6-Terra

Feature roadmap: 0018-scriptorium-v0-15-adoption.md

Objective and Boundaries

Adopt Scriptorium v0.15.0 in its standalone role, expose ConfigKit imports and transient retries, and validate the resulting configuration offline. The approved feature roadmap owns scope, rationale, and acceptance criteria. This plan does not advance the coordinated upgrade sequence beyond its Scriptorium feature.

Only ansible-role-scriptorium and workspace planning records may change. Upstream applications and all other roles, collection, consumer, and asset repositories are read-only. In particular, do not update suite application defaults, role dependency manifests, collection subtrees, or deployment pins.

Execution Rules and Starting State

• Execute the consecutive stages below in order. Before each stage reread its listed policy documents, inspect the owning working trees, and preserve unrelated changes. All policy paths below are workspace-relative.
• The role currently defaults to v0.13.0; the selected target is v0.15.0, with ConfigKit v0.4.2 and PromptKit v0.11.2. Consult tagged application documentation rather than assuming newer checkout behavior belongs to this feature.
• Use workspace .venv/bin Ansible tools and the role's existing integration entry point. Missing PATH entries or an operational controller are not blockers. Existing Go 1.26 satisfies upstream's Go requirement.
• The integration script performs local development-host convergence with sudo. Read its fixture and cleanup behavior before execution. Do not connect to the operational controller or pipeline host, supply real keys, or call providers.
• Trust module state management. No new production tasks, runtime validation, probes, state files, custom retry implementation, or migration automation are required. Tests may inspect rendered configuration to verify role-owned output.
• Keep null optional fields omitted and serialize native values safely. Do not freeze upstream defaults or enforce additional selector/import restrictions.
• Commit validated stages with the plain-English intent given below. No push, release tag, collection assembly, or deployment is required by this plan.
• If validation reveals a real incompatibility, report its evidence and resolve only what falls within the roadmap. Do not silently weaken useful tests or broaden scope. Record validation and commit IDs in Progress Notes.

Stage 1: Adopt the New Application Version

Required Policy Review

Read AGENTS.md, docs/orientation.md, docs/conventions.md, docs/ansible.md, docs/testing.md, and the Feature 0018 roadmap.

Owning Repository and Preconditions

ansible-role-scriptorium. Inspect its current defaults, tasks, template, argument specifications, README, and tests/integration. Read the upstream v0.14.0 migration notes and v0.15.0 configuration/release references linked by the roadmap. Confirm the target tag without modifying upstream worktrees.

Required Changes

1. Set scriptorium_version: v0.15.0 and update its README default example. Keep the source/build/dependency and filesystem tasks unchanged.
2. Add native config validate --config <managed-file> checks to the existing integration script for default and representative configurations. Retain existing offline profile/backend inspection, because application validation alone does not construct a PromptKit engine.
3. Preserve existing caller-supplied build-executable and missing-binary coverage. Do not add an assertion that v0.15.0 must always be the default or require a new historical-version matrix. Limit fixture corrections to actual changed application contracts.

Validation and Completion Criteria

From ansible-role-scriptorium, run:

tests/integration
git diff --check

The new version builds; default and representative configurations validate; offline profile inspection succeeds; immediate repeat convergence is clean. The existing script already includes syntax checking and linting.

Commit

Adopt Scriptorium v0.15.0 in the standalone role.

Stage 2: Expose Imports and Transient Retries

Required Policy Review

Read AGENTS.md, docs/orientation.md, docs/conventions.md, docs/ansible.md, docs/testing.md, and the Feature 0018 roadmap.

Owning Repository and Preconditions

ansible-role-scriptorium. Stage 1 is committed and validated. Review the tagged configuration reference's import resolution, null, and retry semantics.

Required Changes

1. Add defaults scriptorium_configkit_imports: null and scriptorium_transient_retries: null. Add optional argument specifications: imports is a list of dictionaries, retries is an integer. Use native mappings for import entries; do not recreate ConfigKit's nested schema in the role.
2. Extend templates/config.yml.j2 to render configkit.imports when imports is not none, and top-level transient_retries when retries is not none. Use existing serialization conventions. Include both variables in the empty-document condition so either field alone prevents output of {}. With all application variables null, retain the minimal {} document.
3. Extend the existing integration fixture with a caller-owned configuration fragment under a temporary configuration root. Select that root using scriptorium_config_path. Supply imports through the role's public variable; use a relative path entry naming the fragment.
4. In that focused case, render only imports and scriptorium_transient_retries: 0 through application variables. Put one representative setting, such as server.addr: 127.0.0.1:18081, in the external fragment. Do not also define that setting in the main file: ordinary imports reject field conflicts. Native config show should expose the imported setting and retry zero. Inspect the rendered root to verify that the supplied import was serialized.
5. Reapply the same role inputs immediately and require a clean recap. For the default case, verify omission of the two new fields in the rendered YAML, not exact native defaults in resolved output. Reuse existing test structure; no additional overlay scenario is required for this role's import interface.
6. Ensure the temporary configuration and fragment live under the script's existing disposable fixture directory and cleanup restores the default role configuration. No production task should create the test fragment or manage arbitrary import/overlay content.
7. Document the new public variables and one concise inventory import example. Explain null omission, zero retry behavior, caller-owned files, and that newer fields must be left unset when selecting older unsupported binaries.

Validation and Completion Criteria

From the role repository run:

tests/integration
git diff --check

Native validation accepts the new configuration. Native inspection resolves the explicitly supplied fragment and retry setting without provider calls. Default omission and repeated convergence pass. No tests assert exact task layout, default version/model, or file-module ownership/existence postconditions.

Commit

Expose Scriptorium imports and transient retry settings.

Stage 3: Document Compatibility and Record the Review Handoff

Required Policy Review

Read AGENTS.md, docs/orientation.md, docs/conventions.md, docs/ansible.md, docs/testing.md, docs/planning.md, the Feature 0018 roadmap, and docs/roadmap/application-upgrade-sequence.md.

Owning Repositories and Preconditions

ansible-role-scriptorium and workspace. Stages 1-2 are validated and committed.

Required Changes

1. Finish the role README's upgrade guidance: strict YAML/empty-document behavior, ConfigKit imports and --config-overlay versus PromptKit LLM profiles, configuration-source versus application-value path semantics, and changed transport retry behavior. Link tagged upstream contracts for full detail.
2. Mention removed legacy DeepSeek catalog IDs without adding compatibility aliases. Note Scriptorium v0.15.0's GPL-3.0-or-later application grant and link its licensing notices; leave the role's own license untouched. Do not introduce a legal approval gate or copy license files into this installer role.
3. Update the README validation summary to match actual coverage. Do not claim provider connectivity, live service operation, or suite compatibility testing.
4. Record role commits and validation evidence in this plan and workspace status. Mark Feature 0018 in_progress pending independent review. In the sequence document, note implementation is awaiting review, leaving its checkbox open. Do not begin Audita work or mark this feature done automatically.
5. Confirm this feature changed no pipeline/collection/consumer pins. Inspect existing changes without reverting unrelated work by the user or other tasks.

Validation and Completion Criteria

Run git diff --check in the role and workspace. Check new local Markdown links and examples against the selected application contract. Reuse Stage 2 integration results for documentation-only changes; no second full suite or operational deployment is needed. The handoff names the role revision for later integration.

Commits

Role, if documentation remains uncommitted: Document Scriptorium v0.15 compatibility.

Workspace: Record the standalone Scriptorium upgrade for review.

Final Validation and Handoff

Report owning commits, tests performed, and any deviations or blockers. Confirm the feature's working trees are clean. State explicitly that the existing suite compatibility set remains unchanged and that no operational deployment occurred. Independent review and closeout precede the next application adoption feature.

Progress Notes

Roadmap and implementation plan approved by the user. Implementation has not started.

Open Questions

None required for the approved standalone scope. Suite retry policy and later deployment choices belong to the final integration feature, not this role update.