Files
notarius/docs/roadmap/commandkit-migration-discussion.md

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.