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
**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

View File

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

View File

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