Record full CommandKit-native CLI cutover direction

This commit is contained in:
2026-11-19 15:55:46 +00:00
parent 8feece01db
commit b04fe98c9e

View File

@@ -6,9 +6,11 @@ Working notepad for the CommandKit decisions that will be incorporated into the
[master PromptKit-native migration roadmap](promptkit.md). Record the proposal,
open questions, evidence, and decisions here as we discuss them.
**Direction agreed:** Adopt CommandKit as part of the same migration as modern
PromptKit, in separate, reviewable implementation steps. Bring CommandKit design
decisions forward and complete adoption before the overall cutover.
**Direction agreed:** Make a full cutover to a CommandKit-native application as
part of the same migration as modern PromptKit, in separate, reviewable
implementation steps. Adopt CommandKit's public-facing conventions and
recommendations to the fullest extent. Bring its design decisions forward and
complete adoption before the overall cutover.
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
@@ -23,6 +25,29 @@ with U1 (dependencies), U9 (records/reporting), and U10 (CommandKit adoption).
## Agreed Proposal
### Guiding Rule: Full Native Cutover
Backward compatibility with the existing CLI conventions is a non-goal. Use
CommandKit's native command, input, help/version, reporting, error, and outcome
conventions as the design baseline. This mirrors the PromptKit-native direction.
Existing command names, flags, aliases, parsing behavior, report shapes, and exit
conventions are migration evidence, not requirements to preserve. Do not add
legacy aliases, compatibility shims, parallel parsers, or reporting wrappers
solely to reproduce the old CLI. Any application-specific behavior should serve
an actual Notarius need and fit the native conventions.
Provide migration guidance in release documentation, explaining the new commands
and conventions and the actions operators or subprocess callers must take.
Documenting the transition replaces a requirement to keep the old CLI working.
Update canonical CLI and consumer documentation when the behavior lands.
Application responsibilities such as producing artifacts, reporting publication
outcomes, and managing checkpoint/debug storage remain meaningful. Their existing
CLI expression is not protected by an implicit compatibility exception. This
guiding rule does not itself choose stored artifact or checkpoint formats; those
remain separate application decisions in the master roadmap.
### Why Adopt Together
- Source assembly and preflight are already changing. CommandKit integrations
@@ -36,8 +61,8 @@ with U1 (dependencies), U9 (records/reporting), and U10 (CommandKit adoption).
The added work is principally CLI composition and contract migration: dispatch,
flag parsing, configuration selection, reporting, and process-status mapping.
Adopting both libraries together reduces transitional code, but does not make
those compatibility decisions automatic.
Choose their native forms deliberately and document the transition, rather than
spending migration effort recreating existing CLI conventions.
### Ownership And Scope
@@ -47,28 +72,31 @@ those compatibility decisions automatic.
| Standard configuration and PromptKit inspection commands | ckconfig and ckprompt, supplied with application loaders and request builders. |
| Configuration composition and model execution | ConfigKit and PromptKit, using the native boundaries already selected. |
| Pipeline execution and listing, pipeline-specific preflight, artifact publication, checkpoints, and domain outcomes | Notarius application handlers and framework. |
| Published receipts, debug artifact lifecycle, and mapping application outcomes to process results | Notarius, integrated with CommandKit presentation. |
| Receipt content, debug artifact lifecycle, and application outcome meaning | Notarius, expressed through CommandKit's reporting and outcome conventions. |
Keep adoption focused on these responsibilities. Optional upstream capabilities
can be installed individually; adoption does not require enabling every preview,
smoke, completion, or inspection feature. Exact command exposure remains open.
Evaluate the full standard capability set and adopt applicable upstream commands
and recommendations directly. Optional capability selection remains open; assess
its usefulness rather than limiting the initial surface to commands Notarius
already has.
Pipeline and domain code should remain independent of CommandKit. Native
PromptKit observations supply execution facts; Notarius attaches application
meaning and selects report content. CommandKit supplies presentation mechanics.
Two boundaries already identified for deliberate treatment are:
Two application needs already identified for deliberate treatment are:
- `run --json` publishes a defined receipt after successful output publication.
Retain a deliberate machine protocol; a generic report format is not a reason
to change its schema or publication timing.
- `--debug` requests durable debug artifacts. Artifact capture and reporting
verbosity remain distinct choices, even when a command exposes both.
- The current `run --json` publishes a receipt after output publication. Determine
the needed result information and express it through an appropriate native
output facility. The old flag, envelope, formatting, and stream conventions are
not compatibility requirements; reports must still describe the actual outcome.
- The current `--debug` requests durable artifacts. Retain the distinction between
artifact capture and reporting verbosity, while choosing native controls and
meanings rather than requiring that flag to retain its old behavior.
### Intended Sequencing
1. Resolve CommandKit compatibility and command scope alongside the dependency
baseline, bringing U10 forward.
1. Resolve compatible dependency versions and native command scope alongside the
dependency baseline, bringing U10 forward.
2. Introduce CommandKit composition alongside native source assembly. Connect
shared loaders and standard inspection while retaining application
orchestration responsibilities.
@@ -96,21 +124,23 @@ PromptKit v0.23.2 and ConfigKit v1.2.1 targets. Confirm the selected release set
and attribution when this choice is resolved; do not infer final pins from the
current sibling checkouts.
## 2. Command Surface And Flag Compatibility
## 2. Native Command Surface And Inputs
**Discussion / decision:** Pending.
**Discussion / decision:** Full native cutover agreed; concrete command and input
choices pending. Preserving the existing CLI is not a selection criterion.
- Map the existing command surface to native standard commands and application
handlers. Which names, aliases, flags, and inspection report shapes should be
preserved, changed deliberately, or retired?
- How should typed inputs preserve omitted versus explicitly supplied values,
repeated reference options, and reasoning-effort inherit/replace/clear behavior?
- Which help/version, argument, and invalid-invocation behaviors are meaningful
compatibility requirements, and which are incidental to the existing parser?
- How should Notarius workflows be exposed through native standard commands and
application handlers, including upstream naming and flag recommendations?
- Which application input semantics are needed, such as reference selection and
reasoning-effort inheritance or clearing, and how should native typed inputs
express them, including omitted versus explicitly supplied values?
- Which existing commands and custom parsing can disappear once standard
help/version, argument handling, and invalid-invocation behavior are adopted?
Use the [CLI reference](../cli.md) as the inventory of current contracts. Coordinate
flag changes with the master roadmap's retry and worker configuration decisions;
do not silently choose those policies as a consequence of changing the parser.
Use the [CLI reference](../cli.md) to identify current workflows and write
migration guidance, not as a compatibility constraint. Coordinate native inputs
with the master roadmap's retry and worker policy decisions; their domain meaning
is separate from how the CLI expresses them.
## 3. Application Composition, Loaders, And Preflight
@@ -118,8 +148,9 @@ do not silently choose those policies as a consequence of changing the parser.
- How should command declarations, application handlers, and invocation state be
composed without introducing another general CLI or LLM wrapper?
- How should shared loaders preserve configuration discovery, explicit selections,
overrides, and main-source-relative companions across execution and inspection?
- How should native command selections and overrides reach shared loaders while
retaining the selected ConfigKit source composition and main-source-relative
companion behavior across execution and inspection?
- Where should pipeline-specific validation attach to standard configuration
validation, and what state should be acquired only when a command needs it?
@@ -133,28 +164,29 @@ the CLI wiring must preserve that ownership.
**Discussion / decision:** Pending.
- Which outputs should use standard formatted reports, and which should use
deliberate raw output, including the published run-result receipt?
- How should native reports and output modes express application results? Where
does an application data requirement justify raw output rather than a standard
report, independently of the old CLI's output conventions?
- How should syntax, configuration, pipeline, and publication outcomes map to
process status and user-facing explanations? How should presentation failures
remain distinguishable from the underlying operation outcome?
native outcome/status conventions and user-facing explanations? How should
presentation failures remain distinguishable from the operation outcome?
- Which application scope and minimal projections connect native observations
to progress, terminal summaries, manifests, and receipts without duplicate
execution accounting?
Review stream ownership, output publication timing, and failure delivery against
the [run-result contract](../integrations/run-result.md) and
[CLI failure mapping](../internal/cli.md#failure-mapping-and-terminal-reporting).
Review the current [run-result contract](../integrations/run-result.md) and
[CLI failure mapping](../internal/cli.md#failure-mapping-and-terminal-reporting)
to understand application needs and caller migration impact. Their existing CLI
shapes and status mappings do not override the native-cutover direction.
Item 6 of the [PromptKit discussion record](promptkit-architecture-discussion.md#6-inspection-and-execution-bookkeeping)
provides the agreed bookkeeping boundary; concrete durable compatibility remains
part of U9.
provides the bookkeeping boundary; U9 still owns concrete durable record choices.
## 5. Debug Capture And Optional Diagnostics
**Discussion / decision:** Pending.
- How should artifact-capture options interact with quiet/verbose/debug reporting
selections while retaining their separate meanings?
- How should artifact-capture controls fit alongside native quiet/verbose/debug
reporting selections without requiring the existing `--debug` behavior?
- How should requested debug artifact writes, failures, disclosure, and retention
connect to command completion and native callbacks?
- For selected preview, request-validation, or smoke capabilities, what native
@@ -168,19 +200,23 @@ explicitly opt-in. Native inspection alone must not become a model call.
**Discussion / decision:** Pending.
- Which focused command and subprocess tests protect the selected flag, stream,
outcome, receipt, and debug contracts? Which parser/formatter implementation
tests can retire with the removed machinery?
- Which focused command and subprocess tests protect the new native command,
output, outcome, receipt, and debug behavior? Which tests of superseded CLI
contracts and parser/formatter implementation can retire?
- Which representative assembled workflows prove that execution, inspection,
and preflight use the same intended configuration without duplicating lower-level
coverage? Keep the default suite offline and independent of real credentials.
- How should CommandKit steps replace the master roadmap's deferred Phase 7,
and which migration examples, documentation, and ADRs need coordinated updates?
- What release-documentation guidance will show operators and subprocess callers
how to migrate their workflows and integrations to the new conventions?
After discussion, reconcile the master roadmap's U1/U9/U10 entries, sequencing,
removals, and acceptance criteria. Preserve other unresolved choices explicitly.
Then mark this document as the discussion record and keep implementation status
in the master roadmap.
removals, and acceptance criteria, including its treatment of existing inspection
commands and machine-output compatibility. Carry forward the explicit non-goal
of CLI backward compatibility and release migration guidance. Preserve other
unresolved choices explicitly. Then mark this document as the discussion record
and keep implementation status in the master roadmap.
## Evidence And Reading