Plan the standalone Scriptorium upgrade
This commit is contained in:
@@ -1,9 +1,214 @@
|
||||
# Implementation Plan
|
||||
# Implementation Plan 0018: Standalone Scriptorium v0.15.0 Adoption
|
||||
|
||||
No implementation plan is currently active. Select and agree on the next unit
|
||||
of work before replacing this notice with its staged plan.
|
||||
Status: ready
|
||||
|
||||
Feature 0017 is complete and independently reviewed with no remediation
|
||||
findings. Its scope and completion evidence are recorded in
|
||||
[the feature roadmap](features/0017-notarius-testing-overlay.md) and
|
||||
[workspace status](../status.md). Git history preserves the completed plan.
|
||||
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
|
||||
|
||||
### 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. 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.
|
||||
|
||||
Reference in New Issue
Block a user