Clarify configuration authority and native inspection boundaries

This commit is contained in:
2026-11-20 00:32:12 +00:00
parent c7b9c30c43
commit 6ed4ac624a

View File

@@ -112,6 +112,36 @@ their inclusion does not make provider access a startup or release prerequisite.
Preserve native diagnostic findings, including successful invocations whose Preserve native diagnostic findings, including successful invocations whose
reports describe unsupported or unsuccessful checks. reports describe unsupported or unsuccessful checks.
### Configuration Authority And Native Inspection
The migration preserves these two boundaries:
1. **ConfigKit's completed result is authoritative configuration.** Scriptorium
supplies its schema, domain defaults, validation, and genuine application
configuration-resolution logic through ConfigKit's supported extension
points. Those callbacks operate within ConfigKit's lifecycle and evidence
model, including recording resolution changes through the supported APIs.
Scriptorium consumes the completed result without subsequently revising what
effective configuration means. Runtime conversion and request construction
may consume resolved values; they do not introduce another configuration
merge, defaulting, or normalization pass. This follows the configuration
boundary established in [ADR 0005](../adr/0005-configkit-boundary.md).
2. **Standard inspection exposes that result through native adapters.**
Scriptorium selects and acquires the requested configuration and declares
supported capabilities. Use `ckconfig.FromConfigKit` for the application
result and `ckprompt.ConfigScope` for PromptKit's captured configuration
inspection within the native `ckconfig` family. Scriptorium does not assemble
a different effective document, reconcile separate explanation trees, or
reinterpret upstream path semantics. Effective values, sources, explanations,
metadata, and comparisons come from the acquired upstream result through
those adapters. CommandKit owns their standard presentation.
Application selection and supported configuration overrides feed the loading
lifecycle before its completed result is exposed. Adapting loaders or supplying
scopes below does not authorize a second configuration-resolution or inspection
model. The `app` and `promptkit` scopes retain their respective upstream evidence;
they are not combined into a synthetic effective configuration.
### Configuration, Collections, And Request Context ### Configuration, Collections, And Request Context
Expose application configuration through `app` and captured framework Expose application configuration through `app` and captured framework
@@ -255,12 +285,15 @@ metadata without inventing prompt versions, variable defaults, or input schemas.
### 2. Adapt Loading And Install Native Inspection ### 2. Adapt Loading And Install Native Inspection
- Adapt `internal/config` loading, explicit overrides, diagnostics, and - Adapt `internal/config` loading, explicit overrides, diagnostics, and
application selection to ckconfig. Inspect the native overlay API mapping application selection to ckconfig while preserving the
and update examples to its selected syntax; do not assume renaming the old [configuration authority boundary](#configuration-authority-and-native-inspection).
flag alone completes adoption. Keep application resolution callbacks inside ConfigKit's lifecycle and
- Supply `app` and PromptKit configuration scopes with native comparisons and return its completed result to the native adapter. Inspect the native overlay
independent comparison inputs. Avoid accidentally sharing one side's API mapping and update examples to its selected syntax; do not assume renaming
selected values or cached engine with the other. the old flag alone completes adoption.
- Install the native application and PromptKit configuration adapters with
native comparisons and independent comparison inputs. Avoid accidentally
sharing one side's selected values or cached engine with the other.
- Compose ckprompt inventories, named inspection, requirements discovery, - Compose ckprompt inventories, named inspection, requirements discovery,
validation, preparation, and smoke testing through public adapters. validation, preparation, and smoke testing through public adapters.
- Share request construction where applicable, starting from upstream seed - Share request construction where applicable, starting from upstream seed
@@ -315,6 +348,11 @@ scenarios rather than exhaustive upstream behavior matrices:
- Multiple imported collections work across execution, preview, discovery, - Multiple imported collections work across execution, preview, discovery,
and inspection with consistent applicable selections; app-only inspection and inspection with consistent applicable selections; app-only inspection
works without an engine. Comparison sides remain independent. works without an engine. Comparison sides remain independent.
- Application callback changes appear consistently in ConfigKit's completed
values and inspection evidence. Runtime conversion preserves those values,
and standard inspection exposes the acquired result through native adapters,
including native explanation and path behavior. Reuse existing boundary
tests where they already provide this coverage.
- Default output is the artifact; structured output and separate reports use - Default output is the artifact; structured output and separate reports use
the native result representation. Format and destination are independent; the native result representation. Format and destination are independent;
quiet suppresses console results while requested files are still written. quiet suppresses console results while requested files are still written.