eric/scriptorium
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 9 Wiki Activity

Plan the ConfigKit configuration cutover

Browse Source
This commit is contained in:
Eric Rakestraw
2026-09-26 17:50:00 +00:00
parent 43eea5c7c4
commit c016af04b7
2 changed files with 454 additions and 487 deletions
Download Patch File Download Diff File Expand all files Collapse all files

61
docs/roadmap/configkit.md
View File

@@ -4,9 +4,9 @@
Accepted feature direction, drafted on 2026-09-26; not implemented. This
roadmap defines the target behavior and changes from the reviewed baseline.
A separate implementation plan will own sequencing and concrete implementation
steps. The existing `implementation.md` concerns the completed Promptkit upgrade
and is not an implementation plan for this work.
The [implementation plan](implementation.md) owns sequencing, concrete interfaces,
verification steps, and implementation status. This document owns the desired
end state and the policy choices behind it.
The user is adopting ConfigKit across an application suite to standardize
configuration semantics. Scriptorium will make a clean cutover to ConfigKit's
@@ -102,9 +102,10 @@ backend restrictions are introduced merely to adopt the library.
## Discovery, Imports, Overlays, And Paths
Source discovery remains Scriptorium-owned. The target retains the documented
explicit `--config` selection and ordered system-location search. If neither
implicit candidate exists, loading uses defaults only; a selected file that
fails loading is not silently replaced with defaults. No implicit
explicit `--config` selection and ordered system-location search. An explicitly
empty config path is invalid rather than an implicit request for a default file.
If neither implicit candidate exists, loading uses defaults only; a selected
file that fails loading is not silently replaced with defaults. No implicit
working-directory configuration search, environment overlay, or directory scan
is added.
@@ -150,15 +151,17 @@ resolve API-key values. Application validation is not a promise that every
Promptkit backend or definition is valid or that a provider is reachable.
Command-specific execution prerequisites remain with the relevant command;
inspection can explain an incomplete application configuration without requiring
an executable prompt selection. The implementation plan will specify command
names, flag availability, output streams, and exit behavior without adding a
second CLI framework or an HTTP configuration endpoint.
an executable prompt selection. The interface is a CLI configuration command
family, not a second CLI framework or an HTTP configuration endpoint; the
implementation plan specifies its concrete commands and mappings.
Safe diagnostics must not restore raw parser errors or configuration values
that ConfigKit deliberately suppresses. Effective output and explanation use
the upstream redacted renderers; they are inspection output, not guaranteed
reloadable configuration. Dynamic-value sensitivity needs the explicit choice
recorded under Open Questions before inspection is implemented.
reloadable configuration. Under the maintainer's selected policy, backend
`extra_params` are visible in effective output and explanation, including
historical values. There is no blanket container masking, sensitive-key heuristic,
or new selective-redaction configuration surface.
## Credential Boundary And Deferred Features
@@ -169,6 +172,14 @@ optional/required and selected-credential behavior. This departure from the
secret-reference feature is an ownership decision, not compatibility plumbing.
Raw API-key fields remain unsupported under the existing architecture policy.
API-key values are the only secrets requiring ConfigKit redaction in this
adoption. The application configuration holds environment-variable names, not
those values, so inspection neither resolves nor contains the actual keys.
Reference names remain visible. Do not tag `api_key_env` as secret merely to
hide its name, add an eager key lookup, or mask unrelated application settings.
The existing raw-key prohibition and Promptkit boundary provide the protection
without introducing a redundant credential-bearing configuration field.
Secrets-directory bootstrap and application schema versioning are deferred until
there is a concrete application need. Their availability in ConfigKit does not
make them mandatory. Hot reload, runtime resource replacement, remote imports,
@@ -189,8 +200,9 @@ prohibitions on future explicitly requested work.
contracts remain linked rather than copied into a competing specification.
- Add proportionate integration coverage for the cutover: defaults-only input,
explicit values and nulls, imports/conflicts, overlays, CLI precedence,
inspection agreement and redaction, dynamic backend parameters, unchanged
credential ownership, and representative execution/server startup.
inspection agreement and API-key non-disclosure, visible dynamic backend
parameters, unchanged credential ownership, and representative
execution/server startup.
ConfigKit owns exhaustive parser and composition tests; Scriptorium tests its
adoption and application boundaries.
- Pin the published dependency and maintain ConfigKit and YAML attribution under
@@ -206,21 +218,10 @@ execution and inspection, the selected user-facing features work, and migrated
examples and regression coverage demonstrate the documented semantics. It does
not require adopting every ConfigKit feature or changing Promptkit definitions.
## Open Questions
## Resolved Inspection Policy
### Sensitivity Of Arbitrary Backend Parameters
ConfigKit redacts classified paths; it cannot infer secrets in arbitrary
provider-specific `extra_params`. The new inspection surface needs an explicit
classification policy, including superseded values shown in explanation.
Recommended: classify each backend's entire `extra_params` container as sensitive
for inspection. That avoids guessing provider-specific secret names and covers
historical values without restricting which parameters may be passed to Promptkit.
The tradeoff is that benign provider options are also hidden.
Alternative: maintain an explicit application classification of sensitive paths,
leaving other parameter values visible. This gives more useful inspection but
requires a clear mechanism for classifying arbitrary provider options and ongoing
maintenance; key-name heuristics alone are not a reliable substitute. This is an
inspection-policy choice, not authority to reject new backend parameter keys.
On 2026-09-26 the maintainer selected no redaction for `extra_params` and limited
the relevant secret to the API key. Inspection therefore preserves parameter
values and environment-reference names, while actual API-key values remain
outside the application configuration pipeline. Visibility is intentional;
this is not a promise to detect secrets placed inside arbitrary parameter values.