Record native operator interface ownership and align documentation

This commit is contained in:
2026-11-20 00:49:27 +00:00
parent 6ed4ac624a
commit bcb1a76e34
4 changed files with 97 additions and 34 deletions

View File

@@ -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.

View File

@@ -2,7 +2,7 @@
**Base Policy Version:** 1.3 **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 **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) [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, through its supported public root package. Promptkit owns prompt execution,
preparation, prompt and profile formats, built-in profiles, model-client preparation, prompt and profile formats, built-in profiles, model-client
behavior, validation, and framework defaults. Scriptorium owns application behavior, validation, inspection semantics, and framework defaults. Scriptorium
configuration, executable CLI and HTTP adapters, prepared-run and owns the application domain, executable CLI and HTTP adapters, process behavior,
definition-inspection presentation, captured-configuration inspection and HTTP deployment policy. It interprets resolved configuration and uses
exposure, process behavior, and HTTP deployment policy. The [format 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) 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) and [outbound integration contract](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/804a4d32b23aa2e7973400bb0a322a7016574c9f/docs/integrations/openai-compatible-chat.md)
remain Promptkit's contracts. remain Promptkit's contracts.
Scriptorium uses ConfigKit v1.2.1 for strict application YAML decoding, ConfigKit v1.2.1 owns configuration policy and the lifecycle through the final,
resolution, and validation flow. Scriptorium retains its application schema, fully resolved configuration handoff. Scriptorium supplies application schema
defaults, normalization, validation rules, source selection, and CLI override and domain callbacks through ConfigKit's supported extension points and consumes
mapping. PromptKit uses the same ConfigKit generation to decode and assemble the completed result without redefining effective configuration. PromptKit's
framework sources under its separate schema and format contract; Scriptorium configuration is also resolved through ConfigKit, with PromptKit supplying its
selects the inputs but does not parse PromptKit definitions. ConfigKit is a domain schema and rules. The [configuration contract](../config.md) owns
loading mechanism, not the owner of either domain schema or HTTP artifact externally observable application behavior; PromptKit owns framework formats.
containment. The [configuration contract](../config.md) owns externally
observable application behavior, while 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 The CLI exposes Promptkit's captured framework configuration inspection. Its
`show` and `explain` reports use Promptkit's native redaction for classified `show` and `explain` reports use Promptkit's native redaction for classified

View File

@@ -9,6 +9,10 @@ sequence, incorporating the decisions in the
record. The [Narratio proposal](narratio-feature-request.md) supplies consumer record. The [Narratio proposal](narratio-feature-request.md) supplies consumer
acceptance scenarios for requirements discovery. 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, Make Scriptorium a CommandKit-native executable interface over PromptKit,
including ckconfig and ckprompt. Most subprocess consumers should be able to including ckconfig and ckprompt. Most subprocess consumers should be able to
select a stored prompt and consume its resulting artifact directly. Operators 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, CommandKit owns command declarations, dispatch, common parsing, help, reporting,
and outcome mechanics. ckconfig and ckprompt supply their standard families. and outcome mechanics. ckconfig and ckprompt supply their standard families.
ConfigKit owns configuration processing; PromptKit owns definition parsing, ConfigKit owns configuration policy through the fully resolved handoff,
preparation, execution, validation, and domain results. Scriptorium owns including resolution of PromptKit's configuration using PromptKit's schema and
application configuration and source selection, application commands, process rules. PromptKit owns definition, preparation, execution, validation, and
lifecycle, and artifact delivery. 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 This preserves Scriptorium's request-independent execution model and support
for valid definitions under [ADR 0004](../adr/0004-definition-boundary.md). 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 ### 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 1. **ConfigKit's completed result is authoritative configuration.** Scriptorium
supplies its schema, domain defaults, validation, and genuine application supplies its schema, domain defaults, validation, and genuine application

View File

@@ -1,9 +1,9 @@
# CommandKit migration notepad # CommandKit migration notepad
Status: design direction agreed; ready for feature-roadmap preparation. This Status: discussion record incorporated into the
working record captures the decisions for Scriptorium's CommandKit migration. [adoption roadmap](commandkit-adoption.md) and
The remaining integration details below belong in the roadmap alongside [ADR 0006](../adr/0006-adopt-commandkit-native-operator-interfaces.md).
implementation sequencing and validation. The roadmap owns implementation work; the ADR records the ownership decision.
## Product context ## Product context
@@ -49,11 +49,11 @@ use `ckconfig` and `ckprompt` for their standardized operator interfaces.
Scriptorium should retire the corresponding custom inspection machinery as Scriptorium should retire the corresponding custom inspection machinery as
those interfaces take over. those interfaces take over.
PromptKit continues to own preparation and execution semantics. ConfigKit ConfigKit owns configuration policy through the fully resolved handoff,
continues to own configuration resolution. Scriptorium supplies application including PromptKit configuration resolution. PromptKit owns prompting and
configuration and source selection, generation and server commands, process inspection semantics. Scriptorium interprets resolved values and uses upstream
lifecycle, and application-specific artifact handling. CommandKit adoption APIs and results to satisfy user requests. CommandKit adoption does not introduce
does not introduce workflow or conversation state. workflow or conversation state. ADR 0006 records these boundaries.
Prefer shared upstream capabilities over new Scriptorium-specific equivalents. Prefer shared upstream capabilities over new Scriptorium-specific equivalents.
If a required shared capability is missing, discuss an upstream request before 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 Define appropriate verification for the selected behavior and update canonical
documentation, examples, and release migration guidance as implementation lands. 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 The [adoption roadmap](commandkit-adoption.md) incorporates these decisions and
roadmap. Preserve the selected upstream conventions and explicit non-goals. integration details. Keep implementation status there; retain this notepad as
Record any concrete new issue found during preparation without reopening settled the discussion record.
product choices merely to preserve the old CLI. This notepad remains the
discussion record until its decisions have been incorporated into that roadmap.
[upstream-guide]: https://forge.maximumdirect.net/base-layer/commandkit/src/commit/d330d7637f2e7507eca931a899397222c82bc892/docs/consumers/guide.md [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 [upstream-cli]: https://forge.maximumdirect.net/base-layer/commandkit/src/commit/d330d7637f2e7507eca931a899397222c82bc892/docs/cli.md