From 8feece01db581d40538e2f4b86107e4adac99454 Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Thu, 19 Nov 2026 15:51:31 +0000 Subject: [PATCH] Start CommandKit migration discussion notepad --- .../commandkit-migration-discussion.md | 197 ++++++++++++++++++ 1 file changed, 197 insertions(+) create mode 100644 docs/roadmap/commandkit-migration-discussion.md diff --git a/docs/roadmap/commandkit-migration-discussion.md b/docs/roadmap/commandkit-migration-discussion.md new file mode 100644 index 00000000..d3356780 --- /dev/null +++ b/docs/roadmap/commandkit-migration-discussion.md @@ -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.