Start CommandKit migration discussion notepad
This commit is contained in:
197
docs/roadmap/commandkit-migration-discussion.md
Normal file
197
docs/roadmap/commandkit-migration-discussion.md
Normal file
@@ -0,0 +1,197 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user