Remove completed PromptKit planning documents

This commit is contained in:
2026-11-19 15:21:14 +00:00
parent 3105f4d62f
commit d97e2b8e30
3 changed files with 0 additions and 790 deletions

View File

@@ -1,379 +0,0 @@
# Implement the PromptKit v0.23.2 adoption
The [feature roadmap](promptkit-v0.23.2-adoption.md) owns the target and scope.
Start from `247b67312ef1a0552a898c558dfe4639572b0691` plus the planning
commit. Follow the [development guide](../development.md), the applicable
repository policies, and [ADR 0004](../adr/0004-definition-boundary.md) and
[ADR 0005](../adr/0005-configkit-boundary.md). Use the pinned upstream
references in the feature roadmap, not either sibling checkout's moving HEAD.
For final verification, the selected PromptKit release is v0.23.3 at commit
`804a4d32b23aa2e7973400bb0a322a7016574c9f`. The maintainer approved this
patch update after v0.23.2 exposed an in-flight HTTP timeout attribution bug;
it supersedes the earlier PromptKit pin below. ConfigKit remains v1.2.1.
Execute these stages in order as one sprint. Intermediate stages may leave
unresolved imports, outdated fixtures, or failing tests that a later stage
explicitly addresses. Do not add shims or split the migration into separately
buildable products. Focused checks are useful when their dependencies are
ready; the completed tree is what must pass all validation. Keep the change
to the existing product and the collection discovery example and workflow.
Do not add deferred commands, endpoints, CommandKit dependencies or
scaffolding, or conversation and coordination features.
## Stage 1: Unify dependencies and framework source wiring
**Status: Complete.**
1. Update `go.mod` to require `go.maximumdirect.net/promptkit v0.23.2` and
`go.maximumdirect.net/configkit v1.2.1`. Remove the old PromptKit and
ConfigKit requirements and both old catalog requirements. Replace Go
imports throughout production code and tests with the public vanity paths.
Retain Scriptorium's module path, Go 1.27.0 minimum, and Go 1.27.4 release
toolchain. Use ordinary Go module commands with `GOWORK=off` to generate
checksums and select stable `go.yaml.in/yaml/v4 v4.0.0`; complete
`go mod tidy` once code and tests have been converted. Use published
modules, with no committed replacements, workspace, or vendor tree.
2. In `internal/adapter/cli/run.go`, convert `newEngine` to
`configkit.Input` and `configkit.Underlay`. Keep one underlay per
`promptkit_sources` selection in resolved order. A file contributes
`configkit.Input{Source: configkit.File(path), Imports: true}`. For a
directory, call `promptkit.DirectoryInputs(path)` and pass the inputs as
one strict-composition group with the helper's settings unchanged.
Keep `Sources.Main` unset; neither the application YAML nor the last
selector is implicitly a framework main. Pass through schema directory,
engine retry defaults, and injected options as before. Leave the upstream
OpenRouter bundle enabled; do not supply local copies or aliases.
3. In `application_config.go` and `framework_sources.go`, retire the
old-path diagnostic branches. Use `errors.As` for
`*configkit.LoadError` and `configkit.WriteDiagnostics` for typed errors
and both warning paths. Preserve the constructor's wrapped cause and
originating command context; use a safe fallback for other errors. Keep
the distinct application and engine load operations and their warning
timing. Stage 3 handles the inspection-specific path and record types.
4. Keep the current native application schema and overrides in
`internal/config`: ordered main discovery, explicit file selection,
imports, overlay, collection policy, working-directory-relative selector
paths, presence, and schema/domain validation. No field rename or
second schema is needed: the obsolete formats are removed, while fields
already matching the target keep their meaning. Application inspection
continues to use one ConfigKit result without opening framework sources.
5. Retarget the existing dependency guard in
`internal/adapter/dependency_test.go` and its fixtures to the vanity
public/internal boundary. Keep the existing protections against direct
catalog imports and restored framework packages. The final module audit,
rather than matching historical prose or test fixtures, checks that no old
module remains selected.
## Stage 2: Migrate CLI execution, rendering, and terminal reports
**Status: Complete.**
1. In `internal/adapter/cli/run.go` remove `--prompt-version`, the stored
value, and associated usage text from `run` and `render`. Remove the
version from `buildRunRequestFromConfig` and the run summary. Forward
exact prompt and profile IDs, including namespaced IDs, without splitting,
qualifying, or otherwise rewriting them. Preserve existing unrelated
flags, explicit numeric zero, reasoning effort presence, session IDs,
transient retry presence, optional inputs, and profile defaults.
2. Keep `run` on `Engine.Run` and `render` on `Engine.Prepare`. For
`run`, keep parsing and nonnegative validation of the Go duration
`--run-timeout`. Put that duration in `RunRequest.OperationTimeout`
before invoking the runner and remove the adapter-created timeout
context. Pass the caller context (`context.Background()` in the current
CLI). The engine owns the budget for preparation, admission, retries,
generation, and validation; parsing, construction, and file writes stay
outside. Do not put the budget on `render` or change the per-attempt
`--timeout` setting.
3. For a failed CLI run use `errors.Is(err, promptkit.ErrOperationTimeout)`
to select the existing safe deadline diagnostic and exit 1. Do not use
a bare deadline cause as proof the whole operation timed out: provider
failures can carry one. Keep completed output, exit 2 for completed
invalid output, other runtime failures at exit 1, and the existing
artifact/report write ordering and failure handling. Do not override a
returned successful result based on a later context check. No local timer
is needed: the pinned upstream API attributes its own expiration and
fixes the outcome before terminal observation.
4. In `internal/format/prepared_run.go` keep native prepared JSON and
remove the version line from text. In `internal/report/report.go`
remove the version field and projection from the terminal report shared by
CLI and HTTP; do not add ancestry or content fields. Keep usage presence,
outcomes, retry/attempt counters, duration, and opt-in report behavior.
Use PromptKit's terminal event rather than reclassifying or synthesizing it.
5. Adapt the existing CLI, preparation-format, and report tests to assert
ID-only mapping, rejection of the removed flag, no version in current
output, explicit zero presence, deadline vs provider failure, and unchanged
report rules. Reuse existing coverage of output files and status handling.
Migrate inline framework fixtures in Stage 5.
## Stage 3: Adapt existing inspection commands in place
**Status: Complete.**
1. In `internal/adapter/cli/inspect.go` call
`Engine.InspectPrompt(ctx, id)`. Remove the version flag, config member,
usage text, and output field. Leave the command families, format flags,
exit behavior, and full-source engine construction in place. Do not
introduce list, requirement, validation, or diagnostic commands.
2. In `internal/format/inspection.go`, keep the current narrow prompt
projection and output names other than the retired version. Map
`PromptID`, `PromptHash`, `DefaultProfileID`, declared `Inputs`,
and the new `PromptOutputInspection` fields. Map optional fields as
optional: omit absent metadata in JSON/text rather than inventing an
empty value, while showing present empty strings, zero/false values, or
an empty input list. Do not emit captured message text, description or
session fields that were not previously projected.
3. Map `ProfileInspection` directly into the existing profile formatter:
retain `profile_id` and the separate optional `api_key_required` field.
Rename the existing nested `effective_model_params` section to
`profile_model_params` in JSON and text to avoid implying completion.
Keep the existing member names in that section, mapping upstream
`Backend` to `backend_id`. Use the upstream optional pointers; omit
nil members and show present zeros, empty strings, or an empty provider
map. Do not fill missing values from the backend or perform preparation.
No new renderer, format, or extra settings projection is needed.
4. In `framework_config.go`, use `configkit.ParsePath`,
`configkit.Path`, `configkit.SourceInfo`, and the current
`Layer`, `SourceKind`, and import location fields. Keep the small
current source DTO, its field names, and captured order; pass through
native layer values without translating them to the old generation.
Keep the native effective and explanation writers and their redaction.
Validate constructs the engine; show, sources, and explain use its
captured view. For list indexes use paths such as
`/collections/support/profiles/0/model`, not paths keyed by profile ID.
Keep existing explicit-root, invalid, and unknown pointer handling.
5. Adapt only affected tests: prompt/profile optional values, lack of
message disclosure, absence of backend completion in profile inspection,
and framework captured paths, diagnostics, and existing redaction. Do
not expand the application `config` projection or add blanket redaction
for provider parameters. Leave the CommandKit transition for later.
## Stage 4: Refactor the single-run HTTP API
**Status: Complete.**
1. Keep `POST /v1/runs` as the single route: the operation is still a run
and there is no parallel version to distinguish. This is a direct
contract replacement at that path, not a promise of old-client
compatibility. Update `internal/adapter/http/dto.go` and `handler.go`
rather than layering a second handler. Drop request `prompt_version`.
Retain the other current request members and their types: `prompt_id`,
`profile_id`, `session_id`, `inputs`, `vars`, `model`,
`include_raw_output`, `include_execution_report`,
`transient_retries`, and `run_timeout_seconds`. Keep input references
and model overrides in their existing nested shapes. Strictly decode a
single request, so the removed selector and raw `api_key` are unknown
fields. Leave prompt/definition validation and input necessity to
PromptKit after transport validation; do not require a profile when the
prompt defaults one or trim nonblank IDs.
2. Return the existing `artifact`, `validation`, and `metadata`
envelopes on completed runs (including failed output validation) at
200. Keep artifact body as text, not the Go library's base64 artifact
JSON. Retain opt-in `raw_model_output` and opt-in terminal
`execution` on applicable responses. In metadata omit
`prompt_version` and eliminate redundant `model_name`, `endpoint`,
`validation_mode`, `validation_status`, and `repair_attempts_used`:
consume these values from `metadata.model_params` or `validation`.
Keep `metadata.selected_backend_id` as the backend identity and drop
the duplicate `metadata.model_params.backend_id`; upstream guarantees
equality for real results and endpoint-only profiles have no backend ID.
Retain remaining DTO keys, types, timing/usage, and optional fields
for this cutover. Keep the error envelope `{error:{code,message}}`
with the existing optional terminal report where applicable. Do not
serialize raw PromptKit requests/results, causes, or resolved secrets.
3. Map validated `run_timeout_seconds` to
`RunRequest.OperationTimeout` and invoke the shared runner with
`r.Context()`, not a second timeout context. Retain int64 range and
duration-overflow checks, absence/null/zero as no new deadline, and
request/response IO outside the budget. Preserve the current status/code
mapping in the baseline [API table](../api.md#error-responses) as the
starting contract (including 400 for malformed inputs, 404 for missing
IDs and route, 405 for wrong method, 413 for size limits, 500 for
operational validation/unclassified errors, 502 for generation failure,
and 503 for capacity). Resolve these cases explicitly:
- `ErrOperationTimeout`, or a failed run wrapping
`context.DeadlineExceeded` when the parent context itself expired:
504 `deadline_exceeded`.
- A failed run wrapping `context.Canceled` when the parent context is
canceled: 408 `request_canceled`. Check the typed operation timeout
first; do not replace a completed outcome based on a later context
race. A provider-only timeout remains 502 while the parent is live.
- Specific selection, credential, and restricted-reader causes precede
broader PromptKit fallback categories. Use errors.Is/errors.As and
safe messages, not provider status passthrough or string matching.
4. Keep the one engine created by `serve`, request-local reports, current
body and complete encoded response limits, and compact 413 overflow
fallback. Keep file-root requirement, lexical containment with existing
symlink behavior, configured artifact limit, and inline inputs.
Verify that `artifact_reader.go` returns detached mutable body
storage and retains no aliases that can mutate a returned artifact;
fix only if needed by the ownership handoff. Do not implement a new
filesystem threat model or rebuild backend pools per request.
5. Update `handler_test.go`, `artifact_reader_test.go` as needed, and
`examples/http-run.json`. Exercise removed selector/duplicate output
fields, presence-sensitive mapping, safe errors, namespace selection,
limits, and unchanged file policy. Adapt the retry-wait and capacity-wait
deadline tests to exercise a real PromptKit engine and verify typed budget
attribution and capacity release. Use controlled offline doubles or
loopback, with no real keys or paid calls. Use representative canceled
parent and provider-only deadline cases; a fake runner alone is not
evidence that the engine honors a mapped operation budget.
## Stage 5: Migrate maintained definitions and existing test fixtures
**Status: Complete.**
1. Convert selected files under `examples/prompts/`,
`examples/profiles/`, and `examples/framework/` and inline or
on-disk framework fixtures across CLI and HTTP tests. Replace keyed
backends, profiles, and version-keyed prompts with lists of `id`
records at their existing resource destinations. Keep the repository's
existing prompt IDs where there is one intended record. For tests with
distinct formerly version-selected prompts, choose distinct IDs only
when both definitions still serve a test; delete expectations about
version ambiguity. Keep role/cache, inputs, schemas, and validation
behavior as appropriate. Leave source-local message files relative to
their owning definition file.
2. Replace framework `configkit:` controls with native `config:`,
express required imports with `required: true`, and use optional
source header `version: 2` if one is needed. Replace resource
inheritance with `extends: {id: <sibling-id>}`. Review overlays for
whole-record replacement at the same ID and replace obsolete catalog
references with an intended current bundle profile or a complete local
profile. Prefer already selected local profiles in offline fixtures;
do not infer alias mappings or a default model. Check meaningful null
endpoint/credential/map cases against new backend fallback semantics
and keep schemas self-contained. Preserve application composition and
collection selector examples (`examples/config.collections.yml`
demonstrates app source selector composition, not checkout discovery).
3. Update scripts such as `examples/render-v0.9-features.sh` and active
sample invocations to drop version selectors. Adapt remaining native
framework fixtures and assertions from the previous stages. Retain
obsolete YAML only as deliberate negative or historical material.
Add a representative adapter-boundary test for an obsolete version-keyed
definition being rejected by upstream, without matching upstream prose.
Check a valid current definition reaches preparation/execution without a
Scriptorium field filter; do not copy PromptKit's format test matrix.
## Stage 6: Demonstrate discovery of independent collection checkouts
**Status: Complete.**
1. Add `examples/config.discovery.yml` selecting
`./examples/discovery/framework.yml` as a file under
`promptkit_sources`. The framework file declares two **optional**
`config.imports` globs: `collections/*/collection.yml` and
`collections/*/collection.yaml`. Omit `required: true` on each.
These paths are relative to that file; `*` selects one checkout level
in this example, not a new Scriptorium layout restriction. Leave
discovery in native ConfigKit declarations: no Python or Go scanner,
implicit path search, special per-collection registration, or auto-mount
by checkout name.
2. Under `examples/discovery/collections/`, add `support-repo` with
`collection.yml` declaring `collections.support` and a separate
`review-repo` with `collection.yaml` declaring `collections.review`.
Give support at least `base` and `fast` profiles and `answer` and
`summarize` prompts, each a separate YAML record file with an `id`.
The entry file uses explicit relative `config.imports` with
`placement: sequence-item`, destinations
`[collections, support, profiles]` or
`[collections, support, prompts]`, and `required: true` for its own
named required fragments. Use `fast` extending `base`, a synthetic
endpoint/model and `default_profile: support/fast`. Give review its
own profile and prompt (reuse a local ID to demonstrate namespace
separation if useful). Have `support/answer` read a message file
beside its own definition and use the named input `transcript` with
`examples/fixtures/transcript.md`. Include unrelated YAML that would be
unsuitable as a framework input and is not selected by the imports.
3. Run the maintained config through `inspect configuration validate`
and `render --prompt support/answer --profile support/fast` with
`--input transcript=./examples/fixtures/transcript.md`; render a review
prompt too. Add a focused real-engine CLI
test using a scratch checkout tree with the same discovery declarations:
each spelling by itself works, both work together, and placing a
second checkout after one invocation makes it selectable on a new
invocation without editing config. Assert qualified selection and
rendered content from the source-local message/inherited profile.
Confirm unrelated YAML is ignored by successfully loading and preparing
the real fixture. Test through the CLI command/engine boundary, not
through a mock glob implementation. Do not promise hot reload of a
running server.
## Stage 7: Update canonical docs and component notices
**Status: Complete.**
1. Put before/after application and framework examples in
[upgrading-promptkit.md](../consumers/upgrading-promptkit.md). Explain
that unchanged app fields still work through the one native schema,
how to rewrite the selected framework files, how to replace old
version selectors and catalog IDs, whole-record replacement, null
fallback, and self-contained schemas. Do not add HTTP migration
instructions. Describe the final contract in [api.md](../api.md)
including the removal of redundant metadata, deadline/status distinctions,
and updated request example. Keep the HTTP example current.
2. In [config.md](../config.md) explain native discovery selections and
both optional filename globs with a link to the maintained example.
In [operations.md](../operations.md) describe checkout placement and
independent updates; in [cli.md](../cli.md) demonstrate the discovery
example and qualified rendering. Use the actual Stage 6 IDs and input
path. Update CLI flags, inspection field semantics and list-index
explanation examples, render/report details, and subprocess guidance
as affected. Do not describe deferred CommandKit behavior as current.
3. Refresh README where affected, `docs/development.md`,
`docs/internal/{overview,adapters,sources}.md`,
the Scriptorium-specific dependency text in
`docs/policy/architecture.md`, and affected current consumer guides.
Use the new public module links and one ConfigKit generation with
two schemas; distinguish changed implementation from existing policy.
Leave historical release notes, ADR decisions, and completed roadmaps
intact. Do not select, tag, or publish a Scriptorium release here.
4. Under the [OSS policy](../policy/oss.md), update
`docs/oss/attribution.md` for PromptKit and a single ConfigKit entry
at the exact selected commits from the feature roadmap. Remove obsolete
catalog and legacy ConfigKit entries. Inspect the final runtime
dependency list and upstream notice files; expect jsonschema v6.0.3,
x/text v0.44.0, and go-yaml v4.0.0. Use the selected versions'
copyright and license notices and commit-pinned links (the selected
PromptKit attribution is a starting point to verify). Remove stale
YAML v3 attribution if no runtime or incorporated material uses it.
Keep applicable verbatim local license texts and companion links.
Distinguish tool-only graph entries such as upstream ReleaseKit and its
tooling dependencies from Scriptorium's runtime. This is attribution
maintenance, not a project license or release procedure change.
## Stage 8: Verify the complete cutover
**Status: Complete.**
1. Use the selected Go 1.27.4 toolchain. Finish `GOWORK=off go mod tidy`
after all imports and fixtures are in place and confirm
`GOWORK=off go mod tidy -diff` is empty. Inspect `go list -m all` for
the pinned modules, stable YAML, and absence of both legacy modules
and the catalogs. Use `go list -deps ./cmd/scriptorium` to distinguish
linked packages from graph-only tooling. Confirm no replacements,
workspaces, vendored code, or dependency on unpublished sources.
2. Run the [baseline Go checks](../development.md#baseline-validation)
using prepared dependencies and the deterministic offline test suite:
`go test ./...`, `go test -race ./...`, `go vet ./...`, and
`go build ./cmd/scriptorium`. Put binaries outside the repository.
Build the two existing Linux release targets (amd64 and arm64,
`CGO_ENABLED=0`, `-trimpath`, `-ldflags '-s -w'`) without running
publication. Check `gofmt` and `git diff --check`.
3. Use a freshly built binary for maintained config and render commands,
including simple, full, composed with its local overlay, inherited,
application source-list collection/overlay, and discovered collections.
Exercise app inspection without a framework load and framework validate,
show, sources, and explain with a real current path. Verify synthetic
data only, one appropriate output on stdout, and no provider calls for
render/inspection. Covered CLI/HTTP run tests should use a deterministic
fake provider or injected client. Check shell examples and affected
links, including pinned attribution targets.
4. Review the complete diff against the feature roadmap: one native load
per domain, ID-only execution, no legacy routes or translators, no
extra inspection surface, optional discovery for both spellings,
consistent disclosure and transport boundaries, and current docs.
Check for stale active references rather than rewriting history or
deleting deliberate rejection fixtures. Report verification results and
any material blockers; do not convert these sprint checks into new
permanent release gates.

View File

@@ -1,260 +0,0 @@
# PromptKit v0.23.2 Adoption
## Status And Scope
Implemented. The original v0.23.2 target below was superseded for final
verification by PromptKit v0.23.3 at commit
`804a4d32b23aa2e7973400bb0a322a7016574c9f`, with the maintainer's approval,
to correct in-flight HTTP operation-timeout attribution. ConfigKit remains
v1.2.1. This roadmap upgrades 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 and the collection-discovery model
below. 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.
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.
## 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. When using a
separate glob for each spelling, leave each glob optional (omit
`required: true`) so either spelling can have zero matches. An installation
using only one spelling still discovers its collections. 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.
### 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.
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.
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.
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.
- **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.
- **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
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.
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.
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,
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 collection discovery with either entry-file spelling
alone and with both spellings across multiple checkouts. Verify 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:
explicit zero overrides, shared backend admission, timeout attribution,
safe output, and unchanged HTTP artifact policy. No live inference is
needed to validate the migration.

View File

@@ -1,151 +0,0 @@
# PromptKit Adoption Review Findings
Review baseline: Scriptorium `c5e54edaa5f6621d504cf510b4b5b5c1e4d1cfd4`,
with the approved PromptKit v0.23.3 pin and ConfigKit v1.2.1. Stage numbers
refer to the [implementation plan](implementation.md).
## R1: Bound the HTTP timeout regression tests (Stage 4)
**Complete.** The tests use independent parent deadlines and capture the
target invocation's error without sharing a channel. All three passed
twice under the race detector.
In [handler_test.go](../../internal/adapter/http/handler_test.go),
`TestHandlerDeadlineDuringBuiltInGeneration` runs the handler synchronously
while the fake provider waits on a channel that is released only after the
handler returns. If the operation timeout stops reaching PromptKit, the test
can wait for the unrelated provider/transport timeout or the suite watchdog
instead of promptly failing. The retry- and capacity-wait tests likewise rely
on the behavior being tested to return control. The added
`observeRunnerFailures` helper also sends all failures to a shared,
one-slot channel before allowing each runner invocation to return. An
unexpected failure of the first request in the capacity test can fill that
slot and block the second request from returning the failure the test needs
to inspect.
Use a test-only fallback deadline or bounded synchronization independent of
the operation budget, and capture the error of the specific observed
invocation without a blocking send shared by concurrent requests. Keep the
real engine and loopback provider, the assertion on
`ErrOperationTimeout`, and the existing status, observation, and
capacity-release checks. This is a test liveness fix, not a new production
timeout or release gate.
## R2: Describe source-relative message paths without a colocation rule (Stage 7)
**Complete.** The migration guide describes source-relative resolution and
links to PromptKit's path rules. A render with a message in a subdirectory
confirmed that no colocation is required.
The [upgrade guide](../consumers/upgrading-promptkit.md) instructs users to
keep message files beside their owning definitions. PromptKit resolves
`content_file` against the field's declaring source within its rooted
filesystem; it does not require the file to be in the same directory. A
freshly built Scriptorium binary rendered a valid `content_file:
./messages/request.md` without moving the file beside its framework YAML.
The current wording can lead operators to rearrange valid layouts during
migration.
Describe source-relative resolution and link to the pinned PromptKit format
contract for containment rules. A colocated file can remain an example, not
a requirement. No loader or path-policy change is needed.
## R3: Link the Go Text patent grant notice (Stage 7)
**Complete.** The attribution entry links `PATENTS` at the selected Go Text
commit. The notice exists in the pinned module, and the local BSD text and
upstream `LICENSE` link are unchanged.
The [attribution entry](../oss/attribution.md#golangorgxtext) for
`golang.org/x/text v0.44.0` links `LICENSE` but omits `PATENTS`. Build
dependency inspection confirms Go Text is part of the executable. Its
selected module contains the separate patent grant at upstream commit
`6070ac32abcdd1670599eeb3ee4d513c8184a513`; PromptKit's attribution for
that same revision links it. The [OSS policy](../policy/oss.md#license-texts-and-upstream-links)
calls for applicable companion texts to be directly reachable.
Add a `PATENTS` link at the already selected Go Text commit. Retain the
verified local BSD text and existing `LICENSE` link. No separate local
patent notice or change to the project license is needed under the
adopted attribution format.
## R4: Distinguish discovery peers from ordered framework layers (Stages 6–7)
**Complete.** The migration guide and configuration reference distinguish
peer conflicts from ordered replacement. The same two definitions were
verified to conflict as peers and replace as separate selectors.
The [upgrade guide](../consumers/upgrading-promptkit.md) says a later source
selecting the same ID replaces the whole record. That holds for a later
framework underlay, not for two checkout entries selected by the same
discovery file. Scriptorium turns each resolved `promptkit_sources` selector
into one underlay. The entries discovered by the imports of that selector
are composed as peers; their filename, glob, or checkout order is not
override precedence.
The built binary rejected two discovered checkout entries defining
`shared/fast` with `compose.conflict`. Selecting the very same entry files
as two ordered `promptkit_sources` items instead succeeded: the later
record's model was selected and `max_tokens`, absent from that record, did
not carry forward from the earlier one. This is the intended distinction, but
the migration wording can lead operators to put an intended override in
a discovery peer, which prevents the engine from loading.
Qualify whole-record replacement in the upgrade guide and explain in the
[checkout discovery reference](../config.md#collection-checkout-discovery)
that same-ID conflicts within one discovery underlay fail. For an intentional
override, select a separate, later framework source using the existing
application selector list. No scanner, de-duplication, new namespace
restriction, or change to composition is needed.
## R5: Replay framework explanation history once (Stage 3)
**Complete.** Framework inspection calls the native explanation writer
once. The framework inspection tests passed, including path errors,
redaction, and writer failures.
[Framework configuration inspection](../../internal/adapter/cli/framework_config.go)
calls `view.Explain(path)` to check existence, discards the complete
explanation, then calls `view.WriteExplanation`. The pinned native writer
calls `Explain` itself. A successful request therefore replays the same
captured history and builds the same redacted value snapshots twice. If
`H` is the work to construct that explanation and `W` the work to render
it, the command does roughly `2H + W` work instead of `H + W`. This is a
constant-factor cost, not a new quadratic algorithm, but it repeats a
history- and value-sized operation and its allocations. The legacy wrapper
already used two calls; the native inspection path need not retain them.
Delegate once to `view.WriteExplanation`, as app configuration inspection
already does with its native writer. A direct probe with the selected
PromptKit and ConfigKit releases confirmed that this writes a known path,
returns an error without output for an unknown path, and preserves writer
errors. Keep JSON Pointer parsing, native redaction, and the existing exit
and stream behavior; no new formatter or replay algorithm is needed.
## R6: Prevent artifact read-limit overflow (Stage 4)
**Complete.** The read cap no longer overflows at `math.MaxInt64`.
The new test failed before the fix and now verifies that a small file keeps
its full body and size at that limit. The existing size-limit tests, full
Go suite, race suite, vet, and build passed.
[The restricted HTTP artifact reader](../../internal/adapter/http/artifact_reader.go)
allows the same nonnegative `int64` limit as application configuration
and the CLI. It computes `maxBytes + 1` for `io.LimitReader` to detect
oversized files. At the valid setting `9223372036854775807`
(`math.MaxInt64`), that addition wraps to a negative number. The limited
reader then immediately returns EOF, so a nonempty file is accepted as an
empty artifact. A loopback check confirmed HTTP 200 at this setting while
the outgoing prompt silently lost the file content. The same synthetic
request included the file at zero and at the ordinary positive limit.
The defect predates the migration and remains in the reader retained
by Stage 4.
Use overflow-safe byte-limit arithmetic: for example, retain the capped
`limit + 1` read for smaller positive limits and skip the increment at
`math.MaxInt64`, or limit the read first and probe separately for an extra
byte. Accepted files should still require linear time and buffer space in
the bytes read; normal limits should continue to reject oversized files
without a full read. Add a boundary test using a small nonempty file.
Do not reduce the accepted configuration range or change containment
or the zero-limit semantics.