Confirm PromptKit adoption decisions

This commit is contained in:
2026-10-04 00:16:24 +00:00
parent 15e7c1aed9
commit 82b0f231b6

View File

@@ -2,9 +2,10 @@
## Status And Intent ## Status And Intent
Proposed on 2026-10-03. No implementation is delivered by this document. Drafted on 2026-10-03; source-selection and framework-inspection decisions
The recommendations under Open Decisions need confirmation before preparing a confirmed by the maintainer on 2026-10-04. No implementation is delivered by
decision-complete implementation plan. Release preparation remains separate. this document. No significant decisions remain open within this scope;
implementation sequencing and release preparation remain separate work.
Adopt PromptKit's ConfigKit-native configuration boundary while preserving Adopt PromptKit's ConfigKit-native configuration boundary while preserving
Scriptorium's simple, request-independent execution model. As established in Scriptorium's simple, request-independent execution model. As established in
@@ -13,9 +14,10 @@ definitions for the selected PromptKit version should work without a narrower
Scriptorium field-level format. Library-only APIs are considered separately; Scriptorium field-level format. Library-only APIs are considered separately;
this upgrade does not turn Scriptorium into a workflow application. this upgrade does not turn Scriptorium into a workflow application.
The maintainer's preference for native ConfigKit semantics and a clean cutover The maintainer selected a native source cutover and full framework configuration
informs the recommended source interface below. That interface is a proposed inspection. The latter uses upstream's native redaction in this new interface
product change, not something required merely to compile against PromptKit. only. These are deliberate product choices, not requirements inferred merely
from new library APIs.
## Reviewed Baseline And Upstream Target ## Reviewed Baseline And Upstream Target
@@ -71,16 +73,16 @@ Do not independently preflight domain fields in lower-priority definitions
that the final effective configuration replaces. Syntax and composition that the final effective configuration replaces. Syntax and composition
failures remain upstream loading failures. failures remain upstream loading failures.
The recommended application interface, subject to Open Decision 1, is an The selected application interface is an ordered `promptkit_sources` sequence.
ordered `promptkit_sources` sequence. Each entry selects either a `file` or a Each entry selects either a `file` or a `directory` and contributes one caller
`directory`; each entry contributes one caller underlay, from lowest to underlay, from lowest to highest priority. A directory uses
highest priority. A directory uses `promptkit.DirectoryInputs` and strictly `promptkit.DirectoryInputs` and strictly composes its recursively discovered
composes its recursively discovered YAML files. A file uses `configkit.File` YAML files. A file uses `configkit.File`
with declared imports enabled, so an entry document can compose fragments. with declared imports enabled, so an entry document can compose fragments.
All caller groups follow PromptKit's maintained catalogs and owned defaults. All caller groups follow PromptKit's maintained catalogs and owned defaults.
No separately exposed `Sources.Main` setting is needed for this interface. No separately exposed `Sources.Main` setting is needed for this interface.
For example, the proposed application shape is: For example, the target application shape is:
```yaml ```yaml
promptkit_sources: promptkit_sources:
@@ -96,7 +98,7 @@ 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 file with imports for that layout; do not silently deduplicate, skip files, or
convert composition conflicts into precedence. convert composition conflicts into precedence.
Under this recommendation, `prompt_dir`, `profile_dir`, application `backends`, Under this decision, `prompt_dir`, `profile_dir`, application `backends`,
and their directory flags are replaced, not retained as a second configuration and their directory flags are replaced, not retained as a second configuration
model. Framework backend definitions live with the framework sources rather model. Framework backend definitions live with the framework sources rather
than passing through Scriptorium's scalar backend schema. A repeatable than passing through Scriptorium's scalar backend schema. A repeatable
@@ -134,7 +136,7 @@ zero controls must affect outbound requests as specified upstream.
Partial profiles remain valid when request overrides can complete them. Partial profiles remain valid when request overrides can complete them.
Scriptorium must not introduce a mandatory model, credential, default profile, Scriptorium must not introduce a mandatory model, credential, default profile,
or directory prerequisite that prevents such a request. With the recommended or directory prerequisite that prevents such a request. With the selected
source interface, engine construction may have no prompt collection; missing source interface, engine construction may have no prompt collection; missing
request selections fail through PromptKit's ordinary public errors rather than request selections fail through PromptKit's ordinary public errors rather than
a required `prompt_dir` check. Source selection does not imply provider access a required `prompt_dir` check. Source selection does not imply provider access
@@ -168,7 +170,7 @@ one. CLI invocations naturally construct fresh engines. No file watcher,
reload endpoint, per-request server reconstruction, or durable state is added. reload endpoint, per-request server reconstruction, or durable state is added.
This is not a transactional snapshot of all external files or credentials. This is not a transactional snapshot of all external files or credentials.
### Inspection, Requests, And Presentation ### Definition And Application Inspection
`inspect prompt` and `inspect profile` use the same selected configuration `inspect prompt` and `inspect profile` use the same selected configuration
snapshot as execution. Remove the empty-prompt-filesystem substitution. snapshot as execution. Remove the empty-prompt-filesystem substitution.
@@ -178,10 +180,52 @@ captures all selected definitions, including prompts. A partial target may be
inspected without imposing preparation's completeness requirements. inspected without imposing preparation's completeness requirements.
`config validate`, `show`, `sources`, and `explain` remain application `config validate`, `show`, `sources`, and `explain` remain application
configuration operations without constructing an engine. Under the proposed configuration operations without constructing an engine. Under the selected
source cutover, they show source selections rather than the contents of source cutover, they show source selections rather than the contents of
PromptKit's separately loaded definitions. They are not framework validation. PromptKit's separately loaded definitions. They are not framework validation.
Full framework provenance inspection is addressed in Open Decision 2. 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, Keep CLI/HTTP request independence, presence-aware execution overrides,
generation/whole-run timeout separation, transient retries, execution reports, generation/whole-run timeout separation, transient retries, execution reports,
@@ -210,10 +254,10 @@ inspection.
the applicable local license texts. Preserve unrelated attribution entries the applicable local license texts. Preserve unrelated attribution entries
and historical release documents. and historical release documents.
- **Application settings and CLI:** implement the selected source interface - **Application settings and CLI:** implement the selected source interface
through `internal/config` and shared CLI override mapping. Under the native through `internal/config` and shared CLI override mapping. Retire the backend
recommendation, retire the backend document/runtime conversion and old document/runtime conversion and old directory fields, add ordered source
directory fields, add ordered source selection, and update command help and selection, and update command help and prerequisites. Application validation
prerequisites. Application validation checks its schema and selector shape; checks its schema and selector shape;
framework acquisition and domain validation belong to engine construction. framework acquisition and domain validation belong to engine construction.
- **Shared engine wiring:** replace removed fields/options with upstream - **Shared engine wiring:** replace removed fields/options with upstream
inputs and underlays, retain `SchemaDir`, `TransientRetries`, and runtime inputs and underlays, retain `SchemaDir`, `TransientRetries`, and runtime
@@ -221,13 +265,19 @@ inspection.
rendering, definition inspection, and serving. Preserve identifiable rendering, definition inspection, and serving. Preserve identifiable
PromptKit and ConfigKit causes and safe diagnostics. Remove obsolete PromptKit and ConfigKit causes and safe diagnostics. Remove obsolete
prompt-filesystem inspection scaffolding. 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 - **Definitions and fixtures:** migrate every maintained prompt/profile file
under `examples/` and `testdata/`, and inline definitions and construction under `examples/` and `testdata/`, and inline definitions and construction
helpers in CLI, HTTP, and formatting tests. Replace old inheritance syntax helpers in CLI, HTTP, and formatting tests. Replace old inheritance syntax
and move backend examples into framework definitions if the native cutover and move backend examples into framework definitions. Review old explicit
is selected. Review old explicit zeros for their changed meaning instead of zeros for their changed meaning instead of preserving obsolete expectations
preserving obsolete expectations mechanically. Keep useful feature-adoption mechanically. Keep useful feature-adoption coverage; filenames need not be
coverage; filenames need not be renamed merely to reduce historical naming. renamed merely to reduce historical naming.
- **Focused adoption coverage:** use real ConfigKit/PromptKit boundaries for - **Focused adoption coverage:** use real ConfigKit/PromptKit boundaries for
representative source order, same-group conflicts, file imports, combined representative source order, same-group conflicts, file imports, combined
documents, inherited source-relative content, exact IDs/version selection, documents, inherited source-relative content, exact IDs/version selection,
@@ -235,6 +285,11 @@ inspection.
Verify eager failures for unused final definitions and unchanged captured Verify eager failures for unused final definitions and unchanged captured
message content after file edits on an existing engine. Retain shared-server message content after file edits on an existing engine. Retain shared-server
capacity, retry, cancellation, restricted artifact, output, and error tests. 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 Own integration risks locally without recreating upstream's exhaustive parser
or inheritance matrices; use offline clients or `httptest` for generation. or inheritance matrices; use offline clients or `httptest` for generation.
- **Current documentation and migration guidance:** update owning contracts - **Current documentation and migration guidance:** update owning contracts
@@ -243,7 +298,8 @@ inspection.
README, examples, and applicable consumer guidance. Link to v0.12.0 framework README, examples, and applicable consumer guidance. Link to v0.12.0 framework
contracts rather than copying their specification. Correct statements that contracts rather than copying their specification. Correct statements that
ConfigKit does not participate in framework loading. Explain the selected ConfigKit does not participate in framework loading. Explain the selected
source migration and engine-rebuild requirement, and preserve accepted ADR 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. decision content. Update HTTP docs only where observable behavior changes.
## Compatibility And Release Impact ## Compatibility And Release Impact
@@ -251,7 +307,7 @@ inspection.
This is an intentional breaking adoption, not a patch-only dependency refresh. This is an intentional breaking adoption, not a patch-only dependency refresh.
Users must migrate definitions, inheritance syntax, source assembly, and Users must migrate definitions, inheritance syntax, source assembly, and
assumptions about numeric presence, recursive maps, eager validation, and file assumptions about numeric presence, recursive maps, eager validation, and file
reload. Under the recommended native interface they must also migrate the reload. Under the selected native interface they must also migrate the
application source selectors and move application backend definitions into application source selectors and move application backend definitions into
PromptKit source files. Provide small before/after examples and runnable PromptKit source files. Provide small before/after examples and runnable
offline migration checks when implementation lands; no automatic legacy parser offline migration checks when implementation lands; no automatic legacy parser
@@ -272,9 +328,11 @@ version, notes, and roadmap retirement belong to release preparation.
Adoption is complete when the released dependency graph is selected, the Adoption is complete when the released dependency graph is selected, the
approved source interface reaches the canonical framework boundary without approved source interface reaches the canonical framework boundary without
losing definition semantics, maintained examples and fixtures use v0.12.0, losing definition semantics, maintained examples and fixtures use v0.12.0,
and CLI/HTTP workflows and inspection meet the target above. Run the existing and CLI/HTTP workflows and inspection meet the target above. The new framework
development checks, affected offline examples, and link/diff checks, with inspection family must use captured native reports with its explicitly scoped
focused new integration tests for the actual migration risks. 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, This work does not add conversations, appended/follow-up messages,
prepared-handle coordination, semantic retry workflows, embedded configuration prepared-handle coordination, semantic retry workflows, embedded configuration
@@ -283,51 +341,32 @@ Library availability alone does not justify additional commands, endpoints,
resource controls, recurring upstream probes, or release gates. Deferred resource controls, recurring upstream probes, or release gates. Deferred
interfaces are scope choices for this adoption, not permanent prohibitions. interfaces are scope choices for this adoption, not permanent prohibitions.
## Open Decisions ## Confirmed Decisions
### 1. Native Source Cutover Or Retained Application Selectors? ### Native Source Cutover
**Recommendation:** adopt the ordered `promptkit_sources` file/directory The maintainer accepted the ordered `promptkit_sources` file/directory interface
interface above and move backend definitions out of application settings. and moving backend definitions out of application settings. This exposes
This exposes combined definitions, explicit priority, imports, and full combined definitions, explicit priority, imports, and full presence/null
presence/null semantics through their canonical owner. It removes duplicated semantics through their canonical owner. It removes duplicated backend
backend representation and avoids having to translate absent scalar fields representation and avoids translating absent scalar fields into presence-aware
into new presence-aware overlays. The cost is a deliberate application schema overlays. The deliberate application schema and CLI migration accompanies the
and CLI migration alongside the unavoidable framework format migration. unavoidable framework format migration.
**Viable alternative:** retain `prompt_dir`, `profile_dir`, their flags, and Retaining the old directories and application backend surface was considered
application `backends`. Assemble a prompt-directory underlay, then a but not selected: it would reduce migration while retaining duplicate backend
profile-directory underlay, then application backend overrides. Allow combined configuration, presence/null translation, and a less flexible source interface.
definition documents in either directory. This reduces migration and keeps
familiar directory organization, but requires explicit backend presence/null
mapping to avoid replacing catalog values with incidental Go zeros, and a
separate file-selector design if framework imports are to be usable without
recursive-discovery repetition. It also leaves two backend configuration
surfaces and less flexible source ordering. Do not implement this alternative
as an old parser or a filter on PromptKit definition fields.
### 2. Expose Full Framework Configuration Inspection In This Adoption? ### Native Framework Inspection With A Scoped Redaction Exception
**Recommendation:** defer a new framework `validate/show/sources/explain` The maintainer selected `inspect configuration` using the captured native view,
command family. Keep existing application and per-definition inspection, and including upstream redaction in this new interface only, rather than deferring
document their distinct scopes. PromptKit's new `InspectConfiguration` uses the feature. Provenance and history make layered configuration easier to
fixed redaction of credential-shaped dynamic provider keys, including `token` diagnose, and native writers avoid maintaining a parallel representation.
and `password`. That is broader than the maintainer's established API-key-only
redaction choice and cannot be disabled through the released public view.
Deferral avoids quietly changing that choice or reconstructing private
configuration to bypass upstream writers; it does not limit execution of valid
definitions.
**Viable alternative:** add an explicit `inspect configuration` command family The accepted tradeoff is different provider-parameter visibility between this
using the captured native view, with approval for upstream redaction in this new view and existing profile/prepared inspection. Existing API-key-only
new interface only. Provenance and history would make layered configuration redaction choices remain otherwise unchanged. Deferral or an upstream
easier to diagnose, and native writers minimize maintenance. The drawback is consumer-selectable sensitivity API could avoid that difference, but neither is
different provider-parameter visibility between the new view and existing a prerequisite for this adoption. Do not reconstruct private configuration to
inspection; the exception must be explicit, not applied to other commands. bypass native writers or depend on an unpublished upstream interface.
**Another viable alternative:** first obtain an upstream release with a public
consumer-selectable inspection sensitivity policy, then expose native
framework reports with API-key-only redaction. This preserves the selected
policy and source ownership, but requires separate upstream work and delays
inspection. Do not assume that API exists in v0.12.0 or make core adoption
depend on an unpublished interface.