375 lines
22 KiB
Markdown
375 lines
22 KiB
Markdown
# PromptKit v0.12.0 Adoption
|
|
|
|
## Status And Intent
|
|
|
|
Drafted on 2026-10-03; source-selection and framework-inspection decisions
|
|
confirmed by the maintainer on 2026-10-04. The PromptKit v0.12.0 adoption has
|
|
been implemented and delivered after the complete audit passed on 2026-10-04.
|
|
This document remains target and decision context, not an implementation-stage
|
|
log. Release preparation remains separate; no release version has been
|
|
selected or published. No significant decisions remain open within this scope.
|
|
|
|
Adopt PromptKit's ConfigKit-native configuration boundary while preserving
|
|
Scriptorium's simple, request-independent execution model. As established in
|
|
[ADR 0004](../adr/0004-definition-boundary.md), valid prompt and profile
|
|
definitions for the selected PromptKit version should work without a narrower
|
|
Scriptorium field-level format. Library-only APIs are considered separately;
|
|
this upgrade does not turn Scriptorium into a workflow application.
|
|
|
|
The maintainer selected a native source cutover and full framework configuration
|
|
inspection. The latter uses upstream's native redaction in this new interface
|
|
only. These are deliberate product choices, not requirements inferred merely
|
|
from new library APIs.
|
|
|
|
## Reviewed Baseline And Upstream Target
|
|
|
|
The reviewed Scriptorium source is commit
|
|
`bb5006517b6c27dcbe56074f1d97140bf0999c48`; the last release is v0.15.0.
|
|
The completed [ConfigKit adoption](configkit.md) selects ConfigKit
|
|
v0.5.0. PromptKit remains v0.11.2, with the OpenRouter and Rakestrawhome `/v2`
|
|
catalog modules at v2.20260926.0.
|
|
|
|
Application configuration already uses one ConfigKit loading, inheritance,
|
|
resolution, validation, and inspection pipeline. Framework construction still
|
|
passes `prompt_dir` and `profile_dir` into the removed PromptKit directory
|
|
fields and registers application `backends` with `WithBackend`. Profile
|
|
inspection substitutes an empty prompt filesystem to avoid loading prompts.
|
|
Maintained prompt/profile files and inline test fixtures use the old embedded
|
|
`id`, `version`, and `base_profile` syntax.
|
|
|
|
The target is the published PromptKit v0.12.0 release at full commit
|
|
`4b8169da286917fde7875425bb32b799b12c6af3`. The published tag and downloaded
|
|
module identify that same revision. Canonical references are:
|
|
|
|
- [Release notes](https://gitea.maximumdirect.net/eric/promptkit/src/commit/4b8169da286917fde7875425bb32b799b12c6af3/docs/releases/v0.12.0.md).
|
|
- [Framework formats](https://gitea.maximumdirect.net/eric/promptkit/src/commit/4b8169da286917fde7875425bb32b799b12c6af3/docs/formats.md).
|
|
- [Consumer and migration guide](https://gitea.maximumdirect.net/eric/promptkit/src/commit/4b8169da286917fde7875425bb32b799b12c6af3/docs/consumers/pkg-promptkit.md).
|
|
- [Configuration ownership decision](https://gitea.maximumdirect.net/eric/promptkit/src/commit/4b8169da286917fde7875425bb32b799b12c6af3/docs/adr/0001-configuration-boundary.md).
|
|
|
|
PromptKit now also selects ConfigKit v0.5.0, so no further ConfigKit upgrade is
|
|
needed. Go 1.25.5 remains sufficient. Its catalog selections are:
|
|
|
|
| Module | Version | Full source commit |
|
|
| --- | --- | --- |
|
|
| `promptkit-backend-openrouter/v3` | `v3.20260930.0` | `f17d208cb7ad1fb043cda2266cd3011d11b40aa0` |
|
|
| `promptkit-backend-rakestrawhome/v3` | `v3.20260930.0` | `993443d88c451901f4c917fa00c204fd3b54d28d` |
|
|
|
|
This review examined upstream contracts and the affected Scriptorium adapters,
|
|
configuration, presentation, examples, and tests. It did not establish that the
|
|
unmodified application builds against the new, incompatible construction API.
|
|
|
|
## Targeted End State
|
|
|
|
### Framework Ownership And Source Assembly
|
|
|
|
Scriptorium constructs engines through PromptKit's public root package and
|
|
`Config.Sources`. ConfigKit owns source composition, overlays, inheritance,
|
|
presence, null values, and resource origins. PromptKit owns final definition
|
|
validation, catalog contributions, backend completion, content capture,
|
|
preparation, execution, and capacity coordination.
|
|
|
|
An operator-selected source may contain any combination of keyed `backends`,
|
|
`profiles`, and versioned `prompts`. Do not partition or filter documents by
|
|
directory name, filename, or a Scriptorium copy of the framework schema.
|
|
Do not independently preflight domain fields in lower-priority definitions
|
|
that the final effective configuration replaces. Syntax and composition
|
|
failures remain upstream loading failures.
|
|
|
|
The selected application interface is an ordered `promptkit_sources` sequence.
|
|
Each entry selects either a `file` or a `directory` and contributes one caller
|
|
underlay, from lowest to highest priority. A directory uses
|
|
`promptkit.DirectoryInputs` and strictly composes its recursively discovered
|
|
YAML files. A file uses `configkit.File`
|
|
with declared imports enabled, so an entry document can compose fragments.
|
|
All caller groups follow PromptKit's maintained catalogs and owned defaults.
|
|
No separately exposed `Sources.Main` setting is needed for this interface.
|
|
|
|
For example, the target application shape is:
|
|
|
|
```yaml
|
|
promptkit_sources:
|
|
- directory: ./examples/prompts
|
|
- directory: ./examples/profiles
|
|
- file: ./deployment/promptkit.yml
|
|
schema_dir: ./examples/schemas
|
|
```
|
|
|
|
Directories retain the helper's default of disabled imports. Enabling imports
|
|
while also recursively discovering their YAML targets would include those
|
|
files twice in the same group, which ConfigKit rejects. Use a selected entry
|
|
file with imports for that layout; do not silently deduplicate, skip files, or
|
|
convert composition conflicts into precedence.
|
|
|
|
Under this decision, `prompt_dir`, `profile_dir`, application `backends`,
|
|
and their directory flags are replaced, not retained as a second configuration
|
|
model. Framework backend definitions live with the framework sources rather
|
|
than passing through Scriptorium's scalar backend schema. A repeatable
|
|
`--promptkit-source PATH` selects a replacement ordered source list for
|
|
engine-using commands; each path selects a regular file or directory using the
|
|
same rules. Only an explicitly supplied flag overrides the configured list.
|
|
|
|
Application source discovery, its imports and selected overlay, explicit CLI
|
|
override handling, and working-directory-relative application paths remain
|
|
unchanged. `--config-overlay` still selects an application overlay; it does not
|
|
implicitly select a PromptKit layer or profile. Framework priority is explicit
|
|
in the source list, with import/resource containment supplied by upstream for
|
|
each selected root. This is not a new global filesystem sandbox.
|
|
|
|
### Complete Definition Support
|
|
|
|
The target accepts the keyed v0.12.0 formats without compatibility rewriting:
|
|
profile and backend IDs are mapping keys, prompt IDs contain keyed string
|
|
versions, and `extends` replaces `base_profile`. Literal IDs and references
|
|
retain their exact spelling, including punctuation and meaningful whitespace;
|
|
filenames do not establish identities.
|
|
|
|
All supported prompt/profile fields continue to reach PromptKit, including
|
|
inputs, message roles and cache metadata, inline and file content, session
|
|
templates, output validation and repair, backend/endpoint selection,
|
|
credentials by environment name, generation controls, and provider parameters.
|
|
The upstream format reference, not this list, owns the complete contract.
|
|
|
|
Presence must survive the boundary: omission, explicit zero/false/blank, and
|
|
null are not interchangeable. Inheritance and layers recursively combine maps;
|
|
an empty map does not clear inherited entries. Backend defaults apply after
|
|
effective profile inheritance. Changing a model or backend no longer drops
|
|
unrelated explicitly inherited settings. Profile null suppression and explicit
|
|
zero controls must affect outbound requests as specified upstream.
|
|
|
|
Partial profiles remain valid when request overrides can complete them.
|
|
Scriptorium must not introduce a mandatory model, credential, default profile,
|
|
or directory prerequisite that prevents such a request. With the selected
|
|
source interface, engine construction may have no prompt collection; missing
|
|
request selections fail through PromptKit's ordinary public errors rather than
|
|
a required `prompt_dir` check. Source selection does not imply provider access
|
|
or credential availability.
|
|
|
|
### Captured Definitions And Runtime Lifecycle
|
|
|
|
Engine construction validates every final effective definition, including
|
|
unused entries, and captures message-file content and static template syntax.
|
|
Invalid unused definitions or unreadable message resources may therefore fail
|
|
startup or inspection before a request selects them. An overwritten domain
|
|
value is not independently rejected merely because it appears in history.
|
|
|
|
ConfigKit's structural directives now also apply to framework input mappings,
|
|
including dynamic provider maps. Document the reserved `extends` key and the
|
|
difference from literal runtime provider parameters; do not invent a quoting
|
|
escape or a second inheritance resolver.
|
|
|
|
Content files use their effective field's source context, including imported
|
|
and inherited content. Retain those contexts by passing actual upstream
|
|
inputs; do not flatten files into synthetic mappings that lose origins.
|
|
Application paths remain working-directory-relative, whereas framework message
|
|
resources follow PromptKit's source-relative contract. Schema and request
|
|
artifact reads remain preparation-time resources; credentials and provider
|
|
operations retain their documented runtime boundaries.
|
|
|
|
A server retains one constructed engine across its requests, with shared
|
|
backend capacity and queue accounting. Definition/message edits require a new
|
|
engine; for this scope, restarting the server is the supported way to obtain
|
|
one. CLI invocations naturally construct fresh engines. No file watcher,
|
|
reload endpoint, per-request server reconstruction, or durable state is added.
|
|
This is not a transactional snapshot of all external files or credentials.
|
|
|
|
### Definition And Application Inspection
|
|
|
|
`inspect prompt` and `inspect profile` use the same selected configuration
|
|
snapshot as execution. Remove the empty-prompt-filesystem substitution.
|
|
Profile inspection still does not need request inputs, schema reads, model
|
|
calls, or credential values, but constructing its engine now validates and
|
|
captures all selected definitions, including prompts. A partial target may be
|
|
inspected without imposing preparation's completeness requirements.
|
|
|
|
`config validate`, `show`, `sources`, and `explain` remain application
|
|
configuration operations without constructing an engine. Under the selected
|
|
source cutover, they show source selections rather than the contents of
|
|
PromptKit's separately loaded definitions. They are not framework validation.
|
|
The separate framework inspection family below supplies framework validation
|
|
and captured provenance.
|
|
|
|
### Captured Framework Configuration Inspection
|
|
|
|
Add the CLI command family `inspect configuration` with `validate`, `show`,
|
|
`sources`, and `explain` operations. It uses the same application settings,
|
|
source selections, and engine construction as other engine-using commands,
|
|
without requiring a prompt/profile selection or request inputs. Each invocation
|
|
constructs one engine; reporting uses that engine's captured public view rather
|
|
than loading definitions again.
|
|
|
|
- `validate` succeeds when the engine constructs successfully and produces no
|
|
success report. It validates final definitions and captures message resources,
|
|
not provider access, credential availability, or request-specific preparation.
|
|
- `show` writes the captured effective YAML through
|
|
`ConfigurationInspection.WriteEffective`.
|
|
- `sources` presents structured JSON source records from
|
|
`ConfigurationInspection.Sources`, including the source kinds, layers, and
|
|
underlay positions needed to distinguish maintained and operator inputs.
|
|
- `explain --path JSON_POINTER` uses the native explanation view and writer
|
|
for effective values and history. Root and literal mapping-key paths follow
|
|
the same JSON Pointer conventions as application `config explain`; IDs with
|
|
slashes or punctuation must not become dotted-path lookups.
|
|
|
|
Use PromptKit's public `InspectConfiguration` and its native writers and
|
|
records. Surface applicable load diagnostics safely on stderr; successful
|
|
reports go to stdout. Inspection does not resolve credential values, contact
|
|
a provider, or watch/reopen sources after construction. Captured effective
|
|
configuration is distinct from backend-completed `inspect profile` output and
|
|
request-specific prepared output; none substitutes for the others.
|
|
|
|
The maintainer explicitly accepts upstream's credential-shaped provider-key
|
|
redaction for this new family, including effective and historical values.
|
|
Fields such as `token` and `password` can therefore be redacted here while
|
|
remaining visible in existing profile/prepared views. This is not blanket
|
|
redaction of `extra_params`, a change to parameters sent to providers, or a
|
|
change to existing inspection interfaces. Environment-reference names and
|
|
ordinary unclassified content can remain visible. Reports may contain prompt
|
|
text, provider data, paths, and identifiers; native redaction is not a promise
|
|
that the output is safe to disclose.
|
|
|
|
### Requests, Presentation, And Disclosure
|
|
|
|
Keep CLI/HTTP request independence, presence-aware execution overrides,
|
|
generation/whole-run timeout separation, transient retries, execution reports,
|
|
artifact policy, and public error mapping. Preserve existing serialized results
|
|
unless an upstream change actually requires an application contract change.
|
|
Prepared/profile numeric values alone are not proof that a zero control was
|
|
sent; verify upstream presence through generation or recorded outbound requests.
|
|
The dependency change alone does not require a new presence DTO. Continue
|
|
mapping errors by public identity rather than message text.
|
|
|
|
Environment-variable names remain visible; resolved API keys are never
|
|
printed or serialized. Ordinary `extra_params` retain their selected visibility
|
|
where those values are presented. Moving definitions out of application
|
|
settings changes what `config` can inspect, not their sensitivity classification.
|
|
Do not silently adopt broader redaction rules for existing profile/prepared
|
|
inspection.
|
|
|
|
## Work Needed From The Baseline
|
|
|
|
- **Dependencies and attribution:** select released PromptKit v0.12.0, tidy the
|
|
module graph, and use its selected `/v3` catalogs without direct application
|
|
imports. Remove obsolete `/v2` modules and `gopkg.in/yaml.v3` if no remaining
|
|
imports require them. Update PromptKit/catalog component entries and exact
|
|
source, COPYRIGHT, and LICENSE links in `docs/oss/attribution.md`. The reviewed
|
|
grants remain LGPL-3.0-or-later for PromptKit and MIT for the catalogs; reuse
|
|
the applicable local license texts. Preserve unrelated attribution entries
|
|
and historical release documents.
|
|
- **Application settings and CLI:** implement the selected source interface
|
|
through `internal/config` and shared CLI override mapping. Retire the backend
|
|
document/runtime conversion and old directory fields, add ordered source
|
|
selection, and update command help and prerequisites. Application validation
|
|
checks its schema and selector shape;
|
|
framework acquisition and domain validation belong to engine construction.
|
|
- **Shared engine wiring:** replace removed fields/options with upstream
|
|
inputs and underlays, retain `SchemaDir`, `TransientRetries`, and runtime
|
|
collaborator injection, and use the same construction path for execution,
|
|
rendering, definition inspection, and serving. Preserve identifiable
|
|
PromptKit and ConfigKit causes and safe diagnostics. Remove obsolete
|
|
prompt-filesystem inspection scaffolding.
|
|
- **Captured framework inspection:** add the `inspect configuration` family
|
|
with `validate`, `show`, `sources`, and `explain` using the shared engine path
|
|
and its public captured inspection view. Reuse native YAML/explanation writers,
|
|
preserve useful source-layer information in JSON presentation, and keep application
|
|
`config` independent of framework loading. Apply the approved native
|
|
redaction exception only to this new family.
|
|
- **Definitions and fixtures:** migrate every maintained prompt/profile file
|
|
under `examples/` and `testdata/`, and inline definitions and construction
|
|
helpers in CLI, HTTP, and formatting tests. Replace old inheritance syntax
|
|
and move backend examples into framework definitions. Review old explicit
|
|
zeros for their changed meaning instead of preserving obsolete expectations
|
|
mechanically. Keep useful feature-adoption coverage; filenames need not be
|
|
renamed merely to reduce historical naming.
|
|
- **Focused adoption coverage:** use real ConfigKit/PromptKit boundaries for
|
|
representative source order, same-group conflicts, file imports, combined
|
|
documents, inherited source-relative content, exact IDs/version selection,
|
|
null suppression, explicit zero/false, and partial-profile completion.
|
|
Verify eager failures for unused final definitions and unchanged captured
|
|
message content after file edits on an existing engine. Retain shared-server
|
|
capacity, retry, cancellation, restricted artifact, output, and error tests.
|
|
Cover framework inspection's effective YAML, source layers, literal-key
|
|
explanations, diagnostics, and effective/historical native redaction without
|
|
provider calls. Protect the distinction between application validation and
|
|
framework validation, and unchanged visibility in existing profile/prepared
|
|
inspection. Avoid snapshots of incidental writer prose.
|
|
Own integration risks locally without recreating upstream's exhaustive parser
|
|
or inheritance matrices; use offline clients or `httptest` for generation.
|
|
- **Current documentation and migration guidance:** update owning contracts
|
|
in `docs/config.md`, `docs/cli.md`, and `docs/operations.md`, affected internal
|
|
docs, `docs/development.md`, architecture version/ownership references,
|
|
README, examples, and applicable consumer guidance. Link to v0.12.0 framework
|
|
contracts rather than copying their specification. Correct statements that
|
|
ConfigKit does not participate in framework loading. Explain the selected
|
|
source migration, framework-inspection command family and scoped redaction
|
|
exception, and engine-rebuild requirement. Preserve accepted ADR
|
|
decision content. Update HTTP docs only where observable behavior changes.
|
|
|
|
## Compatibility And Release Impact
|
|
|
|
This is an intentional breaking adoption, not a patch-only dependency refresh.
|
|
Users must migrate definitions, inheritance syntax, source assembly, and
|
|
assumptions about numeric presence, recursive maps, eager validation, and file
|
|
reload. Under the selected native interface they must also migrate the
|
|
application source selectors and move application backend definitions into
|
|
PromptKit source files. Provide small before/after examples and runnable
|
|
offline migration checks when implementation lands; no automatic legacy parser
|
|
or catalog alias layer is proposed.
|
|
|
|
PromptKit's maintained profile IDs remain supported, not frozen to fixed model
|
|
settings. Review used external catalog IDs against the selected catalogs; do
|
|
not promise live provider availability or preserve every volatile inventory ID.
|
|
Hashes remain opaque equality values, not cross-version identity guarantees.
|
|
|
|
Under the [release policy](../policy/release.md), the eventual release must be
|
|
a new pre-1.0 minor version. Do not select or publish a release in this work
|
|
set. The previously completed ConfigKit work may share that release; final
|
|
version, notes, and roadmap retirement belong to release preparation.
|
|
|
|
## Completion Criteria And Scope Limits
|
|
|
|
Adoption is complete when the released dependency graph is selected, the
|
|
approved source interface reaches the canonical framework boundary without
|
|
losing definition semantics, maintained examples and fixtures use v0.12.0,
|
|
and CLI/HTTP workflows and inspection meet the target above. The new framework
|
|
inspection family must use captured native reports with its explicitly scoped
|
|
redaction behavior, without changing existing inspection disclosure. Run the
|
|
existing development checks, affected offline examples, and link/diff checks,
|
|
with focused new integration tests for the actual migration risks.
|
|
|
|
This work does not add conversations, appended/follow-up messages,
|
|
prepared-handle coordination, semantic retry workflows, embedded configuration
|
|
bundles, framework internals, or application-owned framework validation.
|
|
Library availability alone does not justify additional commands, endpoints,
|
|
resource controls, recurring upstream probes, or release gates. Deferred
|
|
interfaces are scope choices for this adoption, not permanent prohibitions.
|
|
|
|
## Confirmed Decisions
|
|
|
|
### Native Source Cutover
|
|
|
|
The maintainer accepted the ordered `promptkit_sources` file/directory interface
|
|
and moving backend definitions out of application settings. This exposes
|
|
combined definitions, explicit priority, imports, and full presence/null
|
|
semantics through their canonical owner. It removes duplicated backend
|
|
representation and avoids translating absent scalar fields into presence-aware
|
|
overlays. The deliberate application schema and CLI migration accompanies the
|
|
unavoidable framework format migration.
|
|
|
|
Retaining the old directories and application backend surface was considered
|
|
but not selected: it would reduce migration while retaining duplicate backend
|
|
configuration, presence/null translation, and a less flexible source interface.
|
|
|
|
### Native Framework Inspection With A Scoped Redaction Exception
|
|
|
|
The maintainer selected `inspect configuration` using the captured native view,
|
|
including upstream redaction in this new interface only, rather than deferring
|
|
the feature. Provenance and history make layered configuration easier to
|
|
diagnose, and native writers avoid maintaining a parallel representation.
|
|
|
|
The accepted tradeoff is different provider-parameter visibility between this
|
|
new view and existing profile/prepared inspection. Existing API-key-only
|
|
redaction choices remain otherwise unchanged. Deferral or an upstream
|
|
consumer-selectable sensitivity API could avoid that difference, but neither is
|
|
a prerequisite for this adoption. Do not reconstruct private configuration to
|
|
bypass native writers or depend on an unpublished upstream interface.
|