Files
scriptorium/docs/roadmap/promptkit-v0.23.2-adoption.md

253 lines
16 KiB
Markdown
Raw Normal View History

2026-11-18 15:08:38 +00:00
# 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
2026-11-18 15:11:58 +00:00
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.
2026-11-18 15:08:38 +00:00
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 and the collection-discovery model
below. New CLI capabilities, including
2026-11-18 15:08:38 +00:00
[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.
CommandKit adoption (`go.maximumdirect.net/commandkit`), including the
`ckconfig` and `ckprompt` integrations, is planned after this migration and
belongs to a separate roadmap. Its standardized operator interfaces are
expected to replace Scriptorium's current inspection interfaces. This roadmap
keeps those existing commands in maintenance-only scope and adds no
CommandKit dependencies or advance integration scaffolding.
2026-11-18 15:08:38 +00:00
## 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.
### Independently Maintained Collections
Scriptorium provides a neutral application interface over PromptKit, including
CLI subprocess execution for consumers with limited prompting needs. One
installation may load dozens of collections, each maintained in a separate
Git repository with its own maintainer and update cadence. Operators can place
those checkouts beneath a selected directory and make their prompts available
through the same Scriptorium invocation model.
Use ConfigKit imports in a selected framework source to discover collection
entry files. Establish `collection.yml` and `collection.yaml` as equivalent
Scriptorium conventions for the collection-root entry file, and select both
spellings through the installation's import declarations. Each entry file
declares its own namespace under PromptKit's native `collections` mapping and
uses relative imports to assemble its profiles, prompts, and other definition
files. The checkout directory name does not determine the namespace; callers
select resources by their exact qualified IDs.
The application selects the discovery source through its existing framework
source selection. ConfigKit owns entry-file discovery, relative imports, and
composition; PromptKit owns the resulting collection and resource semantics.
Load the repository entry files rather than treating every YAML file in each
checkout as an independent framework input. PromptKit's `DirectoryInputs`
remains useful for curated configuration trees where all YAML files are
intended contributions. Adding another checkout with a matching entry file
must make that collection available on the next CLI invocation without adding
a per-collection source registration or changing the discovery configuration.
2026-11-18 15:08:38 +00:00
### 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
2026-11-18 15:11:58 +00:00
accept a legacy version selector and then ignore it.
2026-11-18 15:08:38 +00:00
Keep the existing `config` and `inspect` commands functional and accurate
against the selected upstream APIs. Limit inspection work to required import,
API, type, selector, and semantic adaptations. Do not expand capabilities,
redesign command syntax or report presentation, or build reusable inspection
abstractions for the later CommandKit adoption. Necessary output changes should
be the smallest accurate adaptation, with proportionate test and documentation
updates.
2026-11-18 15:08:38 +00:00
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. Reuse existing native writers and make only required adjustments to
local inspection projections. Preserve existing disclosure boundaries;
captured prompt messages becoming available upstream is not reason to add them
automatically to existing prompt inspection output. Adoption of CommandKit's
report formats and disclosure behavior belongs to the later roadmap.
2026-11-18 15:08:38 +00:00
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
2026-11-18 15:11:58 +00:00
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.
2026-11-18 15:08:38 +00:00
## 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.
- **Demonstrate collection discovery and composition.** Add complete,
copyable assets under `examples/` showing application selection of a
framework discovery file, ConfigKit imports matching both collection-root
filename spellings, and multiple independently namespaced collection
directories. Include a representative collection with multiple profile and
prompt definitions in separate files, relative entry-file imports,
sibling profile inheritance, and qualified prompt-to-profile references.
Supply synthetic input fixtures and offline CLI rendering examples that
exercise the discovery-to-selection flow. Keep the example collections in
the repository so validation does not require cloning external repositories.
2026-11-18 15:08:38 +00:00
- **Adapt the existing interfaces.** Update CLI argument mapping,
formatters, captured framework source records and list-index explanation
paths, HTTP DTOs, and terminal report projections. Inspection changes are
limited to the maintenance-only adaptations above; inspection formatter
cleanup, presentation improvements, and CommandKit command standardization
are outside this migration. Keep explicit zero overrides and optional-value
presence. Check that the restricted HTTP
2026-11-18 15:08:38 +00:00
artifact reader transfers ownership of returned artifacts and bytes under
the new public contract without changing Scriptorium's containment policy.
2026-11-18 15:11:58 +00:00
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.
2026-11-18 15:08:38 +00:00
- **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
2026-11-18 15:11:58 +00:00
prompt versions and catalog references, and the changed CLI contract.
Document the collection entry-file convention and discovery configuration
in the [configuration reference](../config.md), with links to the maintained
examples. Explain the checkout layout and independently managed updates in
[operations](../operations.md), and demonstrate qualified prompt/profile
selection and offline rendering in the [CLI reference](../cli.md).
Distinguish collection-owned namespaces from checkout directory names and
explain how entry-file imports select the collection's internal resources.
2026-11-18 15:11:58 +00:00
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. For existing inspection commands, correct
documentation affected by required API and semantic changes without expanding
their operator workflows or documenting future CommandKit behavior as current.
Refresh current contributor and architecture references to the selected
upstream release,
2026-11-18 15:08:38 +00:00
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. Verify both collection entry-file spellings, multiple loaded
collections, relative imports, and discovery of an added collection without
editing the installation's source configuration. Include unrelated YAML
outside the authored import selections to verify that entry-file discovery
does not treat an entire repository as framework configuration.
Update affected inspection tests to cover required adaptations, accurate
optional-value handling, and preserved disclosure boundaries. Reuse existing
coverage and keep new inspection checks focused on migration regressions;
do not build a broader report or command suite ahead of CommandKit adoption.
Protect behavior likely to regress in this cutover:
2026-11-18 15:08:38 +00:00
explicit zero overrides, shared backend admission, timeout attribution,
safe output, and unchanged HTTP artifact policy. No live inference is
needed to validate the migration.