Clarify settled CommandKit decisions and remaining choices

This commit is contained in:
2026-11-20 00:51:58 +00:00
parent 3c73ccfad0
commit cbf3d1acc2

View File

@@ -13,11 +13,11 @@ recommendations to the fullest extent. Bring its design decisions forward and
complete adoption before the overall cutover. complete adoption before the overall cutover.
The master roadmap currently places CommandKit in a subsequent Phase 7 and leaves The master roadmap currently places CommandKit in a subsequent Phase 7 and leaves
its details in U10. That sequencing has not yet been revised. Once the relevant its details in U10. That sequencing has not yet been revised. Item 6 selects how
details below are settled, fold them into the master roadmap, including its to incorporate the agreed decisions into its dependency baseline, implementation
dependency baseline, implementation phases, removal inventory, and acceptance phases, removal inventory, and acceptance criteria while preserving remaining
criteria. No application or dependency changes have been implemented through choices explicitly. No application or dependency changes have been implemented
this discussion. through this discussion.
Item 1 selects the dependency versions and standard capabilities, including Item 1 selects the dependency versions and standard capabilities, including
PromptKit v0.23.3 in place of the master roadmap's initial v0.23.2 target. PromptKit v0.23.3 in place of the master roadmap's initial v0.23.2 target.
@@ -25,10 +25,17 @@ Item 2 selects the application command structure and input conventions. Item 3
selects native composition, shared loaders, and application preflight. Item 4 selects native composition, shared loaders, and application preflight. Item 4
selects native reporting, machine output, and outcomes. Item 5 selects conditional selects native reporting, machine output, and outcomes. Item 5 selects conditional
debug capture through the shared `--debug` flag, native diagnostics, and a run/ debug capture through the shared `--debug` flag, native diagnostics, and a run/
operation bundle with a `latest` symlink. Capture depth, exact run-report fields, operation bundle with a `latest` symlink. Item 6 selects verification, migration
and other concrete record details remain open below. Item 6 selects verification, guidance, and incorporation into the master roadmap; that incorporation is still
migration guidance, and incorporation into the master roadmap; that incorporation pending.
is still pending.
The major architectural decisions are settled. Remaining choices are the exact
capture inventory and depth (item 5), run-report fields/versioning and durable
record formats (item 4/U9), and explicit-empty debug-directory handling plus any
demonstrated need for verbosity without capture (item 5). Function signatures,
bundle filenames other than `latest`, and similar implementation details do not
reopen the selected architecture. Broader PromptKit choices remain with the
master roadmap.
The PromptKit architecture and checkpoint decisions remain in force. This The PromptKit architecture and checkpoint decisions remain in force. This
discussion develops the CommandKit portion of that migration and its interactions discussion develops the CommandKit portion of that migration and its interactions
@@ -124,9 +131,9 @@ roadmap. The master roadmap has not yet been updated.
**Discussion / decision:** Versions and standard capability scope agreed. Adopt **Discussion / decision:** Versions and standard capability scope agreed. Adopt
the set below, including the move to PromptKit v0.23.3. Items 2–3 select the set below, including the move to PromptKit v0.23.3. Items 2–3 select
application commands and composition; subsequent topics address reporting and application commands and composition; items 4–5 select reporting and debug
debug capture. These are selected migration targets; the application dependencies capture principles. These are selected migration targets; the application
have not changed. dependencies have not changed.
### Selected Versions ### Selected Versions
@@ -183,13 +190,14 @@ are selected native features; this does not reintroduce legacy Notarius aliases.
PromptKit configuration scope does not support arbitrary `--set` overrides; PromptKit configuration scope does not support arbitrary `--set` overrides;
use supported request-level controls rather than implementing a local equivalent. use supported request-level controls rather than implementing a local equivalent.
- Retain application handlers for pipeline execution and discovery, with native - Retain application handlers for pipeline execution and discovery, with native
commands, inputs, and result presentation to be designed in items 2–5. commands, inputs, and result presentation as selected in items 2–5.
No upstream feature request has been identified as a blocker for this scope. No upstream feature request has been identified as a blocker for this scope.
Evaluate any later demonstrated gap on its actual application need. On roadmap Evaluate any later demonstrated gap on its actual application need. On roadmap
reconciliation, incorporate these versions into U1, replace U10's open standard reconciliation, incorporate these versions into U1, replace U10's open standard
capability selection with this decision, and retain the unresolved application capability selection with this decision, and incorporate the application wiring
wiring and presentation details explicitly. and presentation decisions from items 2–5. Preserve the remaining record and
debug choices explicitly as directed by item 6.
## 2. Native Command Surface And Inputs ## 2. Native Command Surface And Inputs
@@ -309,7 +317,7 @@ with PromptKit's individual-request `--llm-input-file` bindings.
### Preparing Pipeline Inspection Content ### Preparing Pipeline Inspection Content
**Follow-up clarification:** Leverage ConfigKit for the composed, decoded **Selected design:** Use ConfigKit for the composed, decoded
configuration, defaults, imports, overlay, inheritance, overrides, and native configuration, defaults, imports, overlay, inheritance, overrides, and native
provenance/redacted inspection. Feed that loaded configuration through the same provenance/redacted inspection. Feed that loaded configuration through the same
application resolution used by validation and execution to obtain selected application resolution used by validation and execution to obtain selected
@@ -322,7 +330,8 @@ Generic effective configuration and source explanations remain available through
`config show` and `config explain`. ConfigKit's safe inspection facilities do not `config show` and `config explain`. ConfigKit's safe inspection facilities do not
automatically redact an arbitrary application report; select appropriate report automatically redact an arbitrary application report; select appropriate report
content rather than dumping the raw typed configuration. Item 3 selects loader content rather than dumping the raw typed configuration. Item 3 selects loader
wiring; detailed report content remains with item 4. wiring; item 4 selects reporting conventions and identifies remaining run-report
contract choices.
### Removals And Remaining Work ### Removals And Remaining Work
@@ -335,7 +344,8 @@ native `config show`, `config profile` with `promptkit show profile`, and bespok
Application handlers still validate meaningful input combinations and translate Application handlers still validate meaningful input combinations and translate
typed inputs into pipeline selections. Native `--debug` supplies reporting typed inputs into pipeline selections. Native `--debug` supplies reporting
behavior and conditional artifact capture as selected in item 5. behavior and conditional artifact capture as selected in item 5.
Items 3–4 own loader behavior, exact report content, and outcome presentation. Items 3–4 select loader behavior, report content categories, and outcome
presentation; exact run-report fields and durable formats remain with U9.
Evidence: [CommandKit command/input conventions](../../../commandkit/docs/cli.md#registered-command-syntax), Evidence: [CommandKit command/input conventions](../../../commandkit/docs/cli.md#registered-command-syntax),
[reusable PromptKit flags](../../../commandkit/docs/consumers/guide.md#request-builders-and-loading), [reusable PromptKit flags](../../../commandkit/docs/consumers/guide.md#request-builders-and-loading),
@@ -492,8 +502,8 @@ requests; share concrete request-building functions when useful without
simulating pipeline execution to populate an inspection command. simulating pipeline execution to populate an inspection command.
Output publication, checkpoints, debug capture, and execution records belong to Output publication, checkpoints, debug capture, and execution records belong to
the run path. Loaders do not initialize those resources; debug allocation timing the run path. Loaders do not initialize those resources; item 5 selects debug
remains with item 5. Remove command-specific loading paths, copied configuration allocation timing. Remove command-specific loading paths, copied configuration
and resource inspection, eager runtime setup, and duplicated preflight and resource inspection, eager runtime setup, and duplicated preflight
orchestration. No broader application/package reorganization is required by this orchestration. No broader application/package reorganization is required by this
decision. decision.
@@ -652,9 +662,10 @@ policy, and optional diagnostics agreed. Use `--debug` for native verbosity and
durable capture with `/tmp/notarius-debug` as the default root. Operator-owned durable capture with `/tmp/notarius-debug` as the default root. Operator-owned
data handling and convenient diagnostic representation are agreed. Replace the data handling and convenient diagnostic representation are agreed. Replace the
summary/trace hierarchy with a compact run index, configuration and composition summary/trace hierarchy with a compact run index, configuration and composition
snapshots, and operation records; maintain a `latest` symlink at the debug root. Convenience snapshots, and operation records; maintain a `latest` symlink at the debug root.
guides capture depth; the precise inventory and serialized fields remain under Convenience guides capture depth; the precise inventory and serialized fields
discussion. Implementation is pending. remain under discussion. Explicit-empty directory handling and any demonstrated
need for verbosity without capture also remain open. Implementation is pending.
### Shared Debug Control With Conditional Capture ### Shared Debug Control With Conditional Capture
@@ -1022,8 +1033,9 @@ that implementation acceptance checks have already passed.
## Evidence And Reading ## Evidence And Reading
These are starting points for discussion, not a completed CommandKit migration These sources support the discussion and selected decisions; they do not
audit. Sibling links assume the local repositories remain available. constitute a completed implementation audit. Sibling links assume the local
repositories remain available.
- [Notarius CLI implementation overview](../internal/cli.md) and - [Notarius CLI implementation overview](../internal/cli.md) and
[configuration internals](../internal/configuration.md). [configuration internals](../internal/configuration.md).