From b04fe98c9e7320a5ef152c52f2c6b405f1db8395 Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Thu, 19 Nov 2026 15:55:46 +0000 Subject: [PATCH] Record full CommandKit-native CLI cutover direction --- .../commandkit-migration-discussion.md | 132 +++++++++++------- 1 file changed, 84 insertions(+), 48 deletions(-) diff --git a/docs/roadmap/commandkit-migration-discussion.md b/docs/roadmap/commandkit-migration-discussion.md index d3356780..c69be59b 100644 --- a/docs/roadmap/commandkit-migration-discussion.md +++ b/docs/roadmap/commandkit-migration-discussion.md @@ -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