198 lines
10 KiB
Markdown
198 lines
10 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:** 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.
|
|
|
|
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
|
|
|
|
### 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.
|
|
Adopting both libraries together reduces transitional code, but does not make
|
|
those compatibility decisions automatic.
|
|
|
|
### 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. |
|
|
| Published receipts, debug artifact lifecycle, and mapping application outcomes to process results | Notarius, integrated with CommandKit presentation. |
|
|
|
|
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.
|
|
|
|
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:
|
|
|
|
- `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.
|
|
|
|
### Intended Sequencing
|
|
|
|
1. Resolve CommandKit compatibility and 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. Command Surface And Flag Compatibility
|
|
|
|
**Discussion / decision:** Pending.
|
|
|
|
- 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?
|
|
|
|
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.
|
|
|
|
## 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 shared loaders preserve configuration discovery, explicit selections,
|
|
overrides, and main-source-relative companions 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.
|
|
|
|
- Which outputs should use standard formatted reports, and which should use
|
|
deliberate raw output, including the published run-result receipt?
|
|
- 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?
|
|
- 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).
|
|
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.
|
|
|
|
## 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 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 selected flag, stream,
|
|
outcome, receipt, and debug contracts? Which parser/formatter implementation
|
|
tests can retire with the removed machinery?
|
|
- 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?
|
|
|
|
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.
|
|
|
|
## 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.
|