diff --git a/docs/adr/0006-adopt-commandkit-native-operator-interfaces.md b/docs/adr/0006-adopt-commandkit-native-operator-interfaces.md new file mode 100644 index 0000000..8751d18 --- /dev/null +++ b/docs/adr/0006-adopt-commandkit-native-operator-interfaces.md @@ -0,0 +1,53 @@ +# ADR 0006: Adopt CommandKit's Native Operator Interfaces + +## Status + +Accepted. Complements [ADR 0004](0004-definition-boundary.md) and +[ADR 0005](0005-configkit-boundary.md). Both remain accepted and are not +superseded. + +## Date + +2026-11-19. + +## Context + +Scriptorium is adopting CommandKit's native operator interfaces within the +PromptKit and ConfigKit boundaries established by ADRs 0004 and 0005. + +## Decision + +Scriptorium adopts CommandKit's native operator interfaces. + +ConfigKit owns configuration policy and everything in the configuration +lifecycle before the final, fully resolved configuration handoff. Application +schema and domain callbacks operate through ConfigKit's supported extension +points within that lifecycle. + +PromptKit owns prompt definitions, preparation, execution, validation, and +inspection semantics. Its configuration is resolved through ConfigKit, with +PromptKit supplying its domain schema and rules through ConfigKit's supported +extension points. + +Scriptorium owns the domain. After the handoff, it interprets the resolved +configuration values and uses them to perform useful work that satisfies the +user's request. It does not revise what constitutes effective configuration. +It supplies requests through PromptKit's supported APIs and uses the returned +results without redefining their meaning. + +CommandKit's `ckconfig` and `ckprompt` integrations expose upstream ConfigKit +and PromptKit features. Scriptorium neutrally makes those features available +through the native interfaces, preserving upstream semantics. + +## Alternatives Considered + +Retaining custom configuration and prompt inspection would duplicate upstream +behavior and create another owner for its semantics. Use the native integrations +instead. + +## Consequences + +Standard inspection exposes the upstream result without constructing a different +effective document, reconciling separate explanation trees, or reinterpreting +upstream paths. The [adoption roadmap](../roadmap/commandkit-adoption.md) tracks +implementation. diff --git a/docs/policy/architecture.md b/docs/policy/architecture.md index 6888534..c40824a 100644 --- a/docs/policy/architecture.md +++ b/docs/policy/architecture.md @@ -2,7 +2,7 @@ **Base Policy Version:** 1.3 -**Last Updated**: 2026-11-17 +**Last Updated**: 2026-11-19 **Upstream Source:** https://gitea.maximumdirect.net/eric/policy/src/commit/593c9b52273c5c879785ae9e995d21026df467b4/docs/policy/architecture.md @@ -53,23 +53,27 @@ Scriptorium consumes [PromptKit v0.23.3](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/804a4d32b23aa2e7973400bb0a322a7016574c9f/docs/consumers/pkg-promptkit.md) through its supported public root package. Promptkit owns prompt execution, preparation, prompt and profile formats, built-in profiles, model-client -behavior, validation, and framework defaults. Scriptorium owns application -configuration, executable CLI and HTTP adapters, prepared-run and -definition-inspection presentation, captured-configuration inspection -exposure, process behavior, and HTTP deployment policy. The [format +behavior, validation, inspection semantics, and framework defaults. Scriptorium +owns the application domain, executable CLI and HTTP adapters, process behavior, +and HTTP deployment policy. It interprets resolved configuration and uses +PromptKit's supported APIs and results to satisfy user requests. The [format reference](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/804a4d32b23aa2e7973400bb0a322a7016574c9f/docs/formats.md) and [outbound integration contract](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/804a4d32b23aa2e7973400bb0a322a7016574c9f/docs/integrations/openai-compatible-chat.md) remain Promptkit's contracts. -Scriptorium uses ConfigKit v1.2.1 for strict application YAML decoding, -resolution, and validation flow. Scriptorium retains its application schema, -defaults, normalization, validation rules, source selection, and CLI override -mapping. PromptKit uses the same ConfigKit generation to decode and assemble -framework sources under its separate schema and format contract; Scriptorium -selects the inputs but does not parse PromptKit definitions. ConfigKit is a -loading mechanism, not the owner of either domain schema or HTTP artifact -containment. The [configuration contract](../config.md) owns externally -observable application behavior, while Promptkit owns framework formats. +ConfigKit v1.2.1 owns configuration policy and the lifecycle through the final, +fully resolved configuration handoff. Scriptorium supplies application schema +and domain callbacks through ConfigKit's supported extension points and consumes +the completed result without redefining effective configuration. PromptKit's +configuration is also resolved through ConfigKit, with PromptKit supplying its +domain schema and rules. The [configuration contract](../config.md) owns +externally observable application behavior; PromptKit owns framework formats. + +As decided in [ADR 0006](../adr/0006-adopt-commandkit-native-operator-interfaces.md), +Scriptorium adopts CommandKit's native `ckconfig` and `ckprompt` interfaces to +neutrally expose upstream features and semantics. The current CLI still uses +custom presentation; the [adoption roadmap](../roadmap/commandkit-adoption.md) +tracks its replacement. This decision complements ADRs 0004 and 0005. The CLI exposes Promptkit's captured framework configuration inspection. Its `show` and `explain` reports use Promptkit's native redaction for classified diff --git a/docs/roadmap/commandkit-adoption.md b/docs/roadmap/commandkit-adoption.md index 109200a..40f931a 100644 --- a/docs/roadmap/commandkit-adoption.md +++ b/docs/roadmap/commandkit-adoption.md @@ -9,6 +9,10 @@ sequence, incorporating the decisions in the record. The [Narratio proposal](narratio-feature-request.md) supplies consumer acceptance scenarios for requirements discovery. +[ADR 0006](../adr/0006-adopt-commandkit-native-operator-interfaces.md) records +the native-interface adoption and ownership boundaries, complementing ADRs 0004 +and 0005. + Make Scriptorium a CommandKit-native executable interface over PromptKit, including ckconfig and ckprompt. Most subprocess consumers should be able to select a stored prompt and consume its resulting artifact directly. Operators @@ -62,10 +66,12 @@ Use supported public APIs and released dependencies under the existing CommandKit owns command declarations, dispatch, common parsing, help, reporting, and outcome mechanics. ckconfig and ckprompt supply their standard families. -ConfigKit owns configuration processing; PromptKit owns definition parsing, -preparation, execution, validation, and domain results. Scriptorium owns -application configuration and source selection, application commands, process -lifecycle, and artifact delivery. +ConfigKit owns configuration policy through the fully resolved handoff, +including resolution of PromptKit's configuration using PromptKit's schema and +rules. PromptKit owns definition, preparation, execution, validation, and +inspection semantics. Scriptorium owns the application domain: it interprets +resolved values and uses upstream APIs and results to satisfy user requests. +Application commands, process lifecycle, and artifact delivery remain local. This preserves Scriptorium's request-independent execution model and support for valid definitions under [ADR 0004](../adr/0004-definition-boundary.md). @@ -114,7 +120,9 @@ reports describe unsupported or unsuccessful checks. ### Configuration Authority And Native Inspection -The migration preserves these two boundaries: +The migration implements the ownership decision in +[ADR 0006](../adr/0006-adopt-commandkit-native-operator-interfaces.md) through +these two boundaries: 1. **ConfigKit's completed result is authoritative configuration.** Scriptorium supplies its schema, domain defaults, validation, and genuine application diff --git a/docs/roadmap/commandkit-notepad.md b/docs/roadmap/commandkit-notepad.md index 4f679ae..566baf9 100644 --- a/docs/roadmap/commandkit-notepad.md +++ b/docs/roadmap/commandkit-notepad.md @@ -1,9 +1,9 @@ # CommandKit migration notepad -Status: design direction agreed; ready for feature-roadmap preparation. This -working record captures the decisions for Scriptorium's CommandKit migration. -The remaining integration details below belong in the roadmap alongside -implementation sequencing and validation. +Status: discussion record incorporated into the +[adoption roadmap](commandkit-adoption.md) and +[ADR 0006](../adr/0006-adopt-commandkit-native-operator-interfaces.md). +The roadmap owns implementation work; the ADR records the ownership decision. ## Product context @@ -49,11 +49,11 @@ use `ckconfig` and `ckprompt` for their standardized operator interfaces. Scriptorium should retire the corresponding custom inspection machinery as those interfaces take over. -PromptKit continues to own preparation and execution semantics. ConfigKit -continues to own configuration resolution. Scriptorium supplies application -configuration and source selection, generation and server commands, process -lifecycle, and application-specific artifact handling. CommandKit adoption -does not introduce workflow or conversation state. +ConfigKit owns configuration policy through the fully resolved handoff, +including PromptKit configuration resolution. PromptKit owns prompting and +inspection semantics. Scriptorium interprets resolved values and uses upstream +APIs and results to satisfy user requests. CommandKit adoption does not introduce +workflow or conversation state. ADR 0006 records these boundaries. Prefer shared upstream capabilities over new Scriptorium-specific equivalents. If a required shared capability is missing, discuss an upstream request before @@ -320,13 +320,11 @@ flag and loader mappings, and sequence replacement and removal of CLI code. Define appropriate verification for the selected behavior and update canonical documentation, examples, and release migration guidance as implementation lands. -## Preparing the roadmap +## Roadmap handoff -Fold the agreed decisions and remaining integration details into a feature -roadmap. Preserve the selected upstream conventions and explicit non-goals. -Record any concrete new issue found during preparation without reopening settled -product choices merely to preserve the old CLI. This notepad remains the -discussion record until its decisions have been incorporated into that roadmap. +The [adoption roadmap](commandkit-adoption.md) incorporates these decisions and +integration details. Keep implementation status there; retain this notepad as +the discussion record. [upstream-guide]: https://forge.maximumdirect.net/base-layer/commandkit/src/commit/d330d7637f2e7507eca931a899397222c82bc892/docs/consumers/guide.md [upstream-cli]: https://forge.maximumdirect.net/base-layer/commandkit/src/commit/d330d7637f2e7507eca931a899397222c82bc892/docs/cli.md