223 lines
10 KiB
Markdown
223 lines
10 KiB
Markdown
# 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](features/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](application-upgrade-sequence.md)
|
|
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
|
|
|
|
Completion: complete (2026-09-28).
|
|
|
|
### 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:
|
|
|
|
```sh
|
|
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:
|
|
|
|
```sh
|
|
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.
|
|
|
|
- Stage 1: role commit `61dcafe`. `ansible-role-scriptorium/tests/integration`
|
|
passed, including
|
|
syntax checking, production-profile lint, native validation of default and
|
|
representative configurations, offline profile inspection, missing-binary
|
|
recovery with a caller-supplied Go executable, and clean repeat convergence.
|
|
`git diff --check` passed in the role repository.
|
|
|
|
## 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.
|