Record full CommandKit-native CLI cutover direction
This commit is contained in:
@@ -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
|
||||
|
||||
|
||||
Reference in New Issue
Block a user