234 lines
13 KiB
Markdown
234 lines
13 KiB
Markdown
# CommandKit Migration Discussion
|
|
|
|
## Purpose And Status
|
|
|
|
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:** 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
|
|
details below are settled, fold them into the master roadmap, including its
|
|
dependency baseline, implementation phases, removal inventory, and acceptance
|
|
criteria. No application or dependency changes have been implemented through
|
|
this discussion.
|
|
|
|
The PromptKit architecture and checkpoint decisions remain in force. This
|
|
discussion develops the CommandKit portion of that migration and its interactions
|
|
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
|
|
can consume the same application and native engine loaders.
|
|
- ckconfig and ckprompt can replace standard inspection commands directly,
|
|
avoiding an intermediate adaptation of commands that would soon be replaced.
|
|
- Native execution facts and application outcomes can feed the intended reporting
|
|
facilities while duplicate LLM bookkeeping is removed.
|
|
- Configuration and command migration can be documented and verified as one
|
|
coherent transition.
|
|
|
|
The added work is principally CLI composition and contract migration: dispatch,
|
|
flag parsing, configuration selection, reporting, and process-status mapping.
|
|
Choose their native forms deliberately and document the transition, rather than
|
|
spending migration effort recreating existing CLI conventions.
|
|
|
|
### Ownership And Scope
|
|
|
|
| Concern | Selected owner |
|
|
| --- | --- |
|
|
| Command hosting, standard input/help mechanics, common report formatting and visibility | CommandKit. |
|
|
| 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. |
|
|
| Receipt content, debug artifact lifecycle, and application outcome meaning | Notarius, expressed through CommandKit's reporting and outcome conventions. |
|
|
|
|
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 application needs already identified for deliberate treatment are:
|
|
|
|
- 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 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.
|
|
3. Develop native execution and accounting against the intended CLI boundary,
|
|
with pipeline and domain tests independent of CommandKit.
|
|
4. Complete command and reporting migration before final end-to-end verification
|
|
and migration documentation.
|
|
|
|
This is the agreed sequencing direction, not a replacement phase plan. Concrete
|
|
work units and their placement in the master roadmap follow the discussion below.
|
|
|
|
## 1. Adoption Scope And Dependency Baseline
|
|
|
|
**Discussion / decision:** Detailed choices pending.
|
|
|
|
- Which compatible tagged CommandKit, ckconfig, and ckprompt versions should join
|
|
the final PromptKit/ConfigKit dependency set?
|
|
- Which standard capabilities belong in the initial cutover, and which can remain
|
|
optional future additions?
|
|
- Are any actual Notarius requirements unsupported upstream, warranting a feature
|
|
request rather than retention of duplicate local mechanics?
|
|
|
|
The previously reviewed integrations already align with the roadmap's initial
|
|
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. Native Command Surface And Inputs
|
|
|
|
**Discussion / decision:** Full native cutover agreed; concrete command and input
|
|
choices pending. Preserving the existing CLI is not a selection criterion.
|
|
|
|
- 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) 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
|
|
|
|
**Discussion / decision:** Pending.
|
|
|
|
- How should command declarations, application handlers, and invocation state be
|
|
composed without introducing another general CLI or LLM wrapper?
|
|
- 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?
|
|
|
|
Retain the selected offline preflight boundary: it checks application composition
|
|
and known native resources without synthesizing a stage request or requiring
|
|
provider credentials. Help/version should not require runtime configuration or
|
|
provider work. Model-executing roles share one native engine within an execution;
|
|
the CLI wiring must preserve that ownership.
|
|
|
|
## 4. Reports, Machine Output, And Outcomes
|
|
|
|
**Discussion / decision:** Pending.
|
|
|
|
- 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
|
|
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 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 bookkeeping boundary; U9 still owns concrete durable record choices.
|
|
|
|
## 5. Debug Capture And Optional Diagnostics
|
|
|
|
**Discussion / decision:** Pending.
|
|
|
|
- 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
|
|
request builders and explicit execution choices should the application supply?
|
|
|
|
Keep debug creation and physical storage in Notarius. Ordinary records exclude
|
|
sensitive response/history content, and provider smoke diagnostics remain
|
|
explicitly opt-in. Native inspection alone must not become a model call.
|
|
|
|
## 6. Verification, Migration, And Roadmap Incorporation
|
|
|
|
**Discussion / decision:** Pending.
|
|
|
|
- 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, 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
|
|
|
|
These are starting points for discussion, not a completed CommandKit migration
|
|
audit. Sibling links assume the local repositories remain available.
|
|
|
|
- [Notarius CLI implementation overview](../internal/cli.md) and
|
|
[configuration internals](../internal/configuration.md).
|
|
- [CommandKit consumer guide](../../../commandkit/docs/consumers/guide.md), including
|
|
module selection, typed inputs, raw/formatted output, reporting, and loaders.
|
|
- [ckconfig integration](../../../commandkit/integrations/ckconfig/README.md) and
|
|
[ckprompt integration](../../../commandkit/integrations/ckprompt/README.md).
|
|
- [Audita command composition](../../../audita/internal/cli/app_wiring.go), showing
|
|
application handlers and upstream integrations in one CommandKit application.
|