From 6ed4ac624a8f6588acedae927d917f67e83952ad Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Fri, 20 Nov 2026 00:32:12 +0000 Subject: [PATCH] Clarify configuration authority and native inspection boundaries --- docs/roadmap/commandkit-adoption.md | 50 +++++++++++++++++++++++++---- 1 file changed, 44 insertions(+), 6 deletions(-) diff --git a/docs/roadmap/commandkit-adoption.md b/docs/roadmap/commandkit-adoption.md index 392f6a0..109200a 100644 --- a/docs/roadmap/commandkit-adoption.md +++ b/docs/roadmap/commandkit-adoption.md @@ -112,6 +112,36 @@ their inclusion does not make provider access a startup or release prerequisite. Preserve native diagnostic findings, including successful invocations whose 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 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 - Adapt `internal/config` loading, explicit overrides, diagnostics, and - application selection to ckconfig. Inspect the native overlay API mapping - and update examples to its selected syntax; do not assume renaming the old - flag alone completes adoption. -- Supply `app` and PromptKit configuration scopes with native comparisons and - independent comparison inputs. Avoid accidentally sharing one side's - selected values or cached engine with the other. + application selection to ckconfig while preserving the + [configuration authority boundary](#configuration-authority-and-native-inspection). + Keep application resolution callbacks inside ConfigKit's lifecycle and + return its completed result to the native adapter. Inspect the native overlay + API mapping and update examples to its selected syntax; do not assume renaming + 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, validation, preparation, and smoke testing through public adapters. - 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, and inspection with consistent applicable selections; app-only inspection 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 the native result representation. Format and destination are independent; quiet suppresses console results while requested files are still written.