scriptorium/docs/roadmap/upgrade-kit.md

Promptkit v0.11 Adoption

Status And Intent

Accepted feature direction, recorded on 2026-09-26. Implementation is complete to the pre-release boundary; version selection, release-candidate validation, and publication remain separate release preparation. The baseline descriptions below record the state when this roadmap was written, not current behavior. Upgrade directly from Promptkit v0.9.0 to v0.11.0, including the intervening v0.10.0 catalog transition. This document defines the desired end state and the changes from the current baseline. The historical plan at git show 43eea5c7c41d2a8134b3dece60f3af5c98b8fd1c:docs/roadmap/implementation.md owns sequencing, concrete interface choices, verification steps, and unresolved implementation decisions.

The target is complete definition compatibility, controllable transient retries, an optional whole-run deadline, and modest opt-in execution diagnostics. This is a focused adapter and configuration update, not another architecture migration. Optional diagnostics are included in the desired feature set. “Optional” means callers opt in, not that diagnostics may be silently omitted from the completed adoption or appear in default output.

ADR 0004 and the architecture policy govern scope. Promptkit remains the parser, validator, execution engine, and owner of framework defaults. Scriptorium remains a simple executable application for independent prompt executions, with shared operational state where required for backend limits.

Baseline And Upstream Changes

Scriptorium currently selects Promptkit v0.9.0 and the v1.0.0 backend catalog modules. It already supports CLI execution, rendering, prompt/profile inspection, HTTP execution, configured backends, and presence-aware execution overrides. It does not expose transient retry settings, a whole-run deadline, or execution observers. CLI execution currently supplies a background context.

The upstream review covered the local tagged release v0.11.0 at commit db05b56166ca2d8650dfaf660e1cf0eed3932e1d. Its canonical references are:

• v0.10.0 migration guide;
• v0.11.0 release notes;
• definition formats;
• execution and retry integration contract;
• consumer guide; and
• observation declarations.

A diagnostic run using a temporary module file compiled Scriptorium against v0.11.0. The existing test suite reported one failing profile-inspection case that selects the removed deepseek-4-flash profile; other packages passed. This establishes an initial migration issue, not proof of complete behavioral compatibility or coverage of the new capabilities. The diagnostic did not change the repository dependency pin.

Neither intervening release adds declarative prompt/profile fields requiring new adapter plumbing. The definition-facing changes concern catalog contents and resolution precedence. Retry and observer APIs are execution controls; their adoption is a deliberate case-by-case choice under ADR 0004.

Dependency And Definition Compatibility

Target End State

Scriptorium uses tagged Promptkit v0.11.0 through its supported root package, with the catalog versions selected by that release:

• promptkit-backend-openrouter/v2 v2.20260922.1;
• promptkit-backend-rakestrawhome/v2 v2.20260922.0.

Valid definitions for the selected Promptkit version remain usable through Scriptorium's existing sources and adapters, subject to its established HTTP artifact and deployment boundaries. Rendering and inspection remain offline operations that do not generate model output.

The maintained names promptkit-openrouter-standard and promptkit-openrouter-auto work wherever a profile ID is accepted, including prompt defaults, explicit selection, inheritance, and profile inspection. They are opt-in choices, not new Scriptorium defaults. Ordinary custom-source precedence remains intact.

A stable maintained name is not a frozen model/settings selection. External catalog entries can change or disappear across upgrades; inheriting from one does not create a frozen copy. Complete application-owned profiles remain the appropriate choice when an application owns its model and settings.

Change From Baseline

The module graph and active definition fixtures reflect the released v0.11 catalogs rather than v0.9's catalogs. The selected catalog removes deepseek-3-2, deepseek-4-flash, and deepseek-4-pro; newer DeepSeek names are not compatibility aliases. Migration guidance offers an available catalog profile, a maintained Promptkit name, or a complete application-owned definition. Application-owned examples retain fixed settings where that is their purpose.

Definition conformance and focused resolution coverage protect Scriptorium's adapter boundary without duplicating the upstream parser or catalog. Existing dependency boundaries also apply to the new /v2 module paths.

Controllable Transient Retries

Target End State

Expose transient_retries in application configuration, with a CLI execution override and an HTTP request override. Preserve value presence throughout:

Value	Meaning
Omitted	Inherit the engine setting, ultimately Promptkit's default.
Zero	Disable additional transient attempts.
Positive integer	Permit that many additional transient attempts.
Negative integer	Invalid configuration or request.

Adopt Promptkit's default of two additional attempts rather than silently pinning the previous single-attempt behavior. Users must be able to select zero explicitly. Request overrides take precedence over application configuration; omission must not accidentally become an explicit zero.

Promptkit alone owns eligible statuses, attempt execution, backoff, Retry-After, and capacity coordination. Scriptorium adds no outer model retry loop. Transient retries and structural repairs have distinct budgets: each generation, including each repair generation, receives its transient budget. Retries do not imply exactly-once generation or complete billing knowledge.

Change From Baseline

Application settings reach promptkit.Config.TransientRetries, including the shared server engine, and request overrides reach promptkit.RunRequest.TransientRetries. This adds execution controls, not prompt/profile schema fields or provider model parameters. Strict decoding and presence-aware mapping preserve inheritance and explicit zero. User and operations guidance makes the changed default, latency/cost implications, and independent repair budget visible. Cancellation and shared backend limits remain effective during retrying executions.

Optional Whole-Run Deadline

Target End State

Callers can opt into a total execution deadline independently of the existing generation timeout. No new default deadline is imposed. Existing timeout controls must not silently change meaning: in v0.11.0 they apply per generation attempt, whereas a whole-run deadline bounds the overall operation, including preparation, capacity waiting, retry delays, attempts, and repairs as supported by the upstream context contract.

Expose this choice through CLI execution and HTTP execution. Derive any timeout context from the caller's existing context, so a caller cancellation or earlier deadline still wins. This is a cancellation boundary, not a guarantee of instantaneous interruption of arbitrary callback or filesystem code.

Change From Baseline

CLI execution can carry a selected deadline instead of always using an unbounded background context. HTTP execution can shorten the incoming context without losing parent cancellation or changing server lifecycle behavior. Total-run duration handling is separate from existing attempt-timeout conversion. The interval covers the engine invocation, not adapter parsing, engine creation, or output writing. Provider retry timing can exceed local backoff limits; per-attempt timeouts do not cap that complete invocation.

Opt-In Execution Reports

Target End State

Provide a modest terminal execution report for CLI and HTTP callers who opt in. Capture selected metadata through RunRequest.Observer, including attempt, retry, repair, timing, outcome, and presence-aware usage information. Reports should be available for completed successful and failed execution invocations when Promptkit supplies terminal observations. Do not invent execution data for failures that occur before invocation.

Keep generated CLI content on stdout or the existing output path. Execution reports use a separate destination. Ordinary CLI output and HTTP response shapes remain unchanged when reporting is not requested.

The report has a Scriptorium-owned schema rather than serializing upstream events directly: ExecutionEvent has no stable JSON contract. Preserve unknown usage versus reported zero, and incomplete versus complete observed totals. Existing successful-result usage semantics remain unchanged. A terminal total is an aggregate, not another attempt to add to the bill; no report is a billing ledger.

Change From Baseline

Both adapters have opt-in reporting and explicit application-owned report DTOs. Per-request collection adds no shared mutable report state, durable storage, callback I/O, or event archive. Operational failures can carry reports without manufacturing partial RunResult values. Default output remains unchanged.

Reports exclude prompt and response bodies, credentials, headers, endpoint URLs, provider diagnostic text, and raw errors. Selected identifiers remain potentially sensitive even when observations are content-free. Reports are concise terminal metadata, not a general telemetry framework, event stream, or durable history.

Errors And Compatibility

Preserve existing CLI exit classifications and HTTP 502 / llm_failed classification for generation failures. Keep safe public messages rather than exposing provider error bodies or parsing diagnostic strings.

Promptkit adds ErrTransport, ErrMalformedResponse, ErrRetriesExhausted, and RetryExhaustedError. Use their public identities to support optional structured failure details in execution diagnostics, including actual attempts where available. Retry exhaustion and the final cause are distinct facts; do not lose the underlying failure category by flattening them into one label.

Capacity and validation behavior remains intact. Whole-run deadline and caller cancellation outcomes are deliberate adapter classifications, distinct from a provider-attempt timeout while the caller context is still live. The implementation plan owns the exact presentation choices. Existing generation-error codes do not need a breaking replacement for this upgrade.

Licensing And Distribution Review

Promptkit v0.11.0 changes from GPLv3 to LGPL-3.0-or-later. Scriptorium's current binary workflow produces statically linked Go executables, and upstream's license summary explicitly calls out distribution considerations for that model. Catalog and other dependency licenses remain separate.

Before distributing the upgraded binaries, resolve the applicable notices, license texts, source availability, and any required materials or permissions for recombination with a modified library. Record the chosen distribution approach and make any corresponding packaging/documentation changes. This roadmap is not a legal determination or a complete compliance checklist.

Do not automatically relicense Scriptorium, assume that library source alone settles every distribution requirement, or alter historical release contents. Licensing review is a concrete adoption prerequisite, not a new blanket manual approval gate for every future release.

Documentation And Delivery

Current documentation links to the selected v0.11.0 contracts once implemented. CLI, HTTP, configuration, and operations documents own their respective new behavior; internal docs explain adapter mapping; release notes summarize compatibility impact. Historical release notes and ADR decision content remain unchanged. Current examples and migration guidance reflect the selected version.

The upgrade merits a minor Scriptorium release, not a compatibility patch, with prominent migration guidance for removed profiles, changed retry behavior, the explicit single-attempt option, and timeout layering. Any later decision to defer part of the target leaves that feature visibly incomplete until delivered.

Use the existing release policy and runbook. This roadmap authorizes no publication. No new ADR is needed unless a later decision changes the established product or compatibility boundaries.

Completion Criteria

• The tagged dependency and selected catalog modules are adopted without unsupported imports or local dependency substitutions.
• Existing definition conformance tests and focused maintained-profile tests pass; removed profile IDs have explicit migration guidance, not silent aliases.
• Retry settings preserve omission and zero across configuration, CLI, and HTTP; Promptkit remains the sole retry/capacity implementation.
• Optional total deadlines bound the caller operation without redefining per-attempt timeouts or disabling parent cancellation.
• Opt-in terminal reports provide safe, isolated, presence-aware execution metadata without changing default output or creating durable workflow state. Any deferred reporting work remains visibly incomplete.
• Existing error classifications remain compatible, with deliberate handling of the new public identities and context outcomes.
• The licensing/distribution approach is resolved before upgraded binary distribution, and any required materials are included in the chosen workflow.
• Affected current contracts, examples, and migration guidance match implemented behavior. Relevant tests remain offline and credential-free, and normal development validation passes. Release-candidate validation and the version-matched note remain release preparation.

Concrete interface decisions and the selected distribution approach are recorded in that completed historical plan. They do not expand the product into conversations, follow-up messages, application-owned semantic retry loops, prepared-handle coordination, or multi-step workflows.