Record native operator interface ownership and align documentation
This commit is contained in:
53
docs/adr/0006-adopt-commandkit-native-operator-interfaces.md
Normal file
53
docs/adr/0006-adopt-commandkit-native-operator-interfaces.md
Normal 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.
|
||||||
@@ -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
|
||||||
|
|||||||
@@ -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
|
||||||
|
|||||||
@@ -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
|
||||||
|
|||||||
Reference in New Issue
Block a user