291 lines
17 KiB
Markdown
291 lines
17 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.
|
||
|
||
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.
|
||
Application-specific commands, wiring, and reporting details remain open below.
|
||
|
||
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. |
|
||
|
||
Adopt the standard capability suite selected in item 1, including upstream
|
||
commands and recommendations beyond the existing Notarius surface. The remaining
|
||
discussion determines application-specific inputs, wiring, and result content.
|
||
|
||
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. Incorporate item 1's selected dependency baseline and standard capabilities,
|
||
and resolve native application command design, 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:** Versions and standard capability scope agreed. Adopt
|
||
the set below, including the move to PromptKit v0.23.3. Application-specific
|
||
command design and reporting details remain with the subsequent topics. These
|
||
are selected migration targets; the application dependencies have not changed.
|
||
|
||
### Selected Versions
|
||
|
||
| Module | Version | Role |
|
||
| --- | --- | --- |
|
||
| `go.maximumdirect.net/commandkit` | `v0.7.0` | Native command declarations, inputs, help/version, reporting, and completion. |
|
||
| `go.maximumdirect.net/ckconfig` | `v0.9.0` | Standard configuration commands and ConfigKit diagnostic classification. |
|
||
| `go.maximumdirect.net/ckprompt` | `v0.10.0` | Standard PromptKit inspection, validation, preparation, and smoke diagnostics. |
|
||
| `go.maximumdirect.net/configkit` | `v1.2.1` | Shared configuration dependency for the application and integrations. |
|
||
| `go.maximumdirect.net/promptkit` | `v0.23.3` | Native model execution, including corrected timeout/cancellation reporting. |
|
||
|
||
The CommandKit integration releases form a documented compatible set using
|
||
PromptKit v0.23.2. Select v0.23.3 explicitly for its timeout attribution and
|
||
cancellation/error identity fixes. It retains the same dependencies and requires
|
||
no configuration or request API migration from v0.23.2. The Go consumer minimum
|
||
remains 1.27. Verify the assembled dependency set through the migration's normal
|
||
integration checks and update attribution when the dependency changes land.
|
||
|
||
The version review used locally available release tags and tagged dependency
|
||
manifests. Remote release lookup was unavailable, so it did not establish whether
|
||
newer tags existed remotely. These are deliberate selected versions, not a claim
|
||
that every module is the latest published release.
|
||
|
||
Evidence: [integration version guidance](../../../commandkit/docs/consumers/guide.md#module-selection)
|
||
and [PromptKit v0.23.3 release notes](../../../promptkit/docs/releases/v0.23.3.md).
|
||
|
||
### Selected Standard Capabilities
|
||
|
||
| Area | Adopt in the cutover |
|
||
| --- | --- |
|
||
| Core CLI | Native help, `version`, typed flags and operands, supplied-value semantics, standard outcomes, and command declaration/dispatch. |
|
||
| Reporting | Native `--format` with text/YAML/JSON, `--quiet`, `--verbose`, `--debug`, and `--progress`, including upstream visibility and failure behavior. |
|
||
| Configuration | `config scopes`, `validate`, `show`, `sources`, `explain`, and `diff`, for application and PromptKit configuration. |
|
||
| Resource discovery | PromptKit listings for prompts, profiles, backends, namespaces, and collections, with native filters and selectors. |
|
||
| Resource inspection | Native prompt, profile, and backend reports, plus requirements discovery. |
|
||
| Concrete request checks | Requirements validation and prepared-request preview using native inputs, variables, profiles, and execution overrides. |
|
||
| Provider diagnostics | Reachability, authentication, text-inference, structured-output, and aggregate smoke tests. |
|
||
| Convenience features | Bash, Zsh, and Fish completion, useful declaration hints, and upstream PromptKit convenience aliases. |
|
||
|
||
Use the [upstream CLI conventions](../../../commandkit/docs/cli.md) directly.
|
||
Providing the standard capability suite means supplying application loaders and
|
||
callbacks, not recreating those commands locally. Upstream convenience aliases
|
||
are selected native features; this does not reintroduce legacy Notarius aliases.
|
||
|
||
### Wiring Boundaries And Follow-Up
|
||
|
||
- Keep configuration validation, requirements discovery, and concrete request
|
||
validation distinct. Pipeline preflight remains application-owned. Concrete
|
||
preparation may read inputs and schemas and check credentials even though it
|
||
makes no model call.
|
||
- Install smoke commands for explicit invocation. Their availability does not
|
||
introduce provider calls during startup, ordinary validation, or offline tests.
|
||
- Enable application configuration overrides through ConfigKit. The selected
|
||
PromptKit configuration scope does not support arbitrary `--set` overrides;
|
||
use supported request-level controls rather than implementing a local equivalent.
|
||
- Retain application handlers for pipeline execution and discovery, with native
|
||
commands, inputs, and result presentation to be designed in items 2–5.
|
||
|
||
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
|
||
reconciliation, incorporate these versions into U1, replace U10's open standard
|
||
capability selection with this decision, and retain the unresolved application
|
||
wiring and presentation details explicitly.
|
||
|
||
## 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.
|