# PromptKit v0.23.2 Adoption ## Status And Scope Accepted direction; not yet implemented. Upgrade the existing Scriptorium product in one native cutover. Use the released PromptKit and ConfigKit APIs for framework and configuration mechanisms that they already own. Provide migration guidance for configuration, definitions, and CLI usage, not a second application schema, a legacy definition reader, or compatibility aliases. Refactor the early-beta HTTP API directly, without an HTTP migration or backward-compatibility requirement. The [definition boundary](../adr/0004-definition-boundary.md) and [configuration boundary](../adr/0005-configkit-boundary.md) remain in effect. The existing CLI and HTTP surfaces should be able to use valid definitions for the selected PromptKit release without copying its schema or maintaining a narrower application-specific subset. This roadmap covers the changes to existing surfaces needed for the migration. New CLI capabilities, including [Narratio's requirements inspection](narratio-feature-request.md), concrete request validation, inventory, backend inspection, configuration diffs, and smoke diagnostics, are deferred to a separate roadmap. It does not add HTTP operations for those capabilities or introduce continuation, coordination, prepared-handle workflows, or prepared-content capture. ## Baseline And Target The reviewed Scriptorium baseline is `1b1d967fc78e9c514a478b27debf1fadbc772283`. It uses `gitea.maximumdirect.net/eric/promptkit` v0.12.0. Application configuration already uses native ConfigKit v1.2.0, but framework inputs, inspection records, and diagnostics still use old-path ConfigKit v0.5.0. The old PromptKit module also selects two external catalog modules and go-yaml v4.0.0-rc.6. Prompt versions are selectors in both executable interfaces and appear in prepared, inspection, and execution output. The completed [v0.12.0 roadmap](promptkit.md) records the prior migration. The target is `go.maximumdirect.net/promptkit` v0.23.2, commit `382ccfb14b9630fd8f48c8364dbe2b6159637d71`, and `go.maximumdirect.net/configkit` v1.2.1, commit `51ef3144158db1a09fabdbd1c7ae59908c84923b`, with stable go-yaml v4.0.0. The existing Go 1.27.0 consumer minimum and Go 1.27.4 release toolchain already satisfy this selection. - [PromptKit release notes](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/382ccfb14b9630fd8f48c8364dbe2b6159637d71/docs/releases/v0.23.2.md) - [PromptKit migration guide](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/382ccfb14b9630fd8f48c8364dbe2b6159637d71/docs/consumers/configuration-migration.md) - [PromptKit framework formats](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/382ccfb14b9630fd8f48c8364dbe2b6159637d71/docs/formats.md) - [PromptKit consumer API guide](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/382ccfb14b9630fd8f48c8364dbe2b6159637d71/docs/consumers/pkg-promptkit.md) - [ConfigKit v1.2.1 release notes](https://forge.maximumdirect.net/base-layer/configkit/src/commit/51ef3144158db1a09fabdbd1c7ae59908c84923b/docs/releases/v1.2.1.md) ## Targeted End State ### One Configuration Mechanism, Separate Schemas ConfigKit resolves the application document; Scriptorium owns its schema, defaults, domain rules, source selection, and override mapping. The app uses one native schema and decoder. Existing fields can remain where they still express the right application setting, without a separate legacy mode. PromptKit loads its framework sources separately using the same released ConfigKit types. Application-only configuration inspection still does not construct a PromptKit engine or require framework resources. Scriptorium selects ordered framework files and directories and supplies them through PromptKit's supported public APIs. The application config file is not itself a framework source. Preserve the application selectors, explicit override behavior, and source grouping where they already map directly to upstream inputs. PromptKit and ConfigKit determine how those inputs compose and how relative framework resources resolve. Scriptorium does not infer namespaces, rewrite IDs, flatten source origins, or supply a second merge policy. Adopt PromptKit's default OpenRouter bundle as its lowest-priority underlay. Caller definitions remain able to replace bundled records by ordinary composition. Scriptorium does not recreate the former catalogs, maintained profile aliases, or a local implicit profile selection. Bundle availability is not a readiness check or a promise of a fixed provider model. ### Existing Commands And Execution Execution, rendering, and prompt inspection select a prompt by exact ID, including a qualified collection ID where appropriate. Remove the CLI version selector and the corresponding version members from the CLI and HTTP request, response, inspection, and report contracts where they exist. Do not accept a legacy version selector and then ignore it. Continue to distinguish framework configuration, resolved resources, and request preparation. Framework configuration inspection reports the upstream captured result, with native provenance, normalization, and redaction where currently used. Profile inspection reports the resolved profile, preserving unset versus explicitly supplied values, rather than reconstructing backend-completed settings. Render shows request-completed settings. Use native reports or writers when their content matches the existing interface's purpose; retain focused projections where Scriptorium owns the format or disclosure boundary. In particular, captured prompt messages becoming available upstream is not reason to add them automatically to existing prompt inspection output. PromptKit owns preparation, provider calls, retries, capacity, validation, and repair. Preserve the configured shared server engine and established backend admission behavior. Use PromptKit's native operation timeout for the existing whole-run budget where it can preserve the execution boundary and support the intended CLI and HTTP outcomes. A provider-attempt timeout is still distinct from the whole-run deadline; caller cancellation still applies. Keep the existing context wrapper if delegation would change those semantics rather than introducing two independent timers. CLI process behavior, HTTP decoding, limits, restricted artifact loading, safe diagnostics, and application-owned execution reports remain adapter responsibilities. ### HTTP Contract Serve one ID-only HTTP execution contract. Choose the route, request and response shapes, and status mapping that best fit the single-run model. There is no need to preserve `POST /v1/runs` or to introduce a successor route solely to signal incompatibility. No HTTP compatibility routes, legacy payload adapters, or client migration procedures are needed. Retain operational boundaries such as configured size limits, restricted artifact access, credential handling, and shared backend admission; these serve the application independently of wire compatibility. ## Work Needed From The Baseline - **Converge the module graph and engine wiring.** Move runtime and test imports to the vanity paths. Replace old ConfigKit input, path, provenance, and diagnostic types at the CLI construction and inspection boundaries. Remove the obsolete diagnostic branches and the legacy module and catalog dependencies. Keep distinctions between application and framework error presentation where they remain useful. Use public typed causes and sentinel categories, including for construction, deadlines, and artifact failures. Reconcile commit-pinned attribution and license notices against the resulting runtime graph under the [OSS policy](../policy/oss.md), distinguishing linked dependencies from upstream maintainer tooling. - **Migrate maintained configuration and definitions in place.** Convert version-keyed prompts and other keyed resource maps to explicit-ID lists; choose one definition per ID or give separately selectable former versions distinct IDs. Convert framework source controls to `config:`, write `required: true` where a missing import is an error, and use version 2 only where an optional framework source header is supplied. Use sibling `extends: {id: ...}` and update exact references when using collections. Review same-ID whole-record replacement, backend fallback from null profile fields, self-contained schemas, and source-local message files. Retain existing application discovery, overlays, and path semantics where still appropriate; they do not need to change solely to make an old file fail. Review maintained examples and real-engine test fixtures together. - **Adapt the existing interfaces.** Update CLI argument mapping, formatters, captured framework source records and list-index explanation paths, HTTP DTOs, and terminal report projections. Keep explicit zero overrides and optional-value presence. Check that the restricted HTTP artifact reader transfers ownership of returned artifacts and bytes under the new public contract without changing Scriptorium's containment policy. Preserve established CLI outcomes outside the intentional cutover changes. Validate the HTTP adapter against its new contract and the application boundaries above, not against old wire shapes. - **Give operators a migration path in documentation.** Update the [consumer migration guide](../consumers/upgrading-promptkit.md) with before-and-after application and framework examples, directions for old prompt versions and catalog references, and the changed CLI contract. Explain semantic changes that can survive a syntactic conversion, particularly replacement, null fallback, and schema resolution. Document the new HTTP contract directly in the [API reference](../api.md) and update its maintained examples. Update the canonical configuration, CLI, subprocess, and internal references where their implementation changes. Refresh current contributor and architecture references to the selected upstream release, leaving historical release records intact. Record release impact as an intentional incompatible change under the [release policy](../policy/release.md#versioning-and-compatibility); this roadmap does not select or publish a release. - **Verify the migrated boundary, not a second upstream test suite.** Use the repository's baseline Go checks and representative offline examples and real-engine adapter tests. Exercise native source composition, qualified selection, source-local resources, captured inspection, render and execution, and representative failures for obsolete formats and selectors. Protect behavior likely to regress in this cutover: explicit zero overrides, shared backend admission, timeout attribution, safe output, and unchanged HTTP artifact policy. No live inference is needed to validate the migration.