diff --git a/docs/roadmap/commandkit-migration-discussion.md b/docs/roadmap/commandkit-migration-discussion.md index e0aa4ed1..c7db053b 100644 --- a/docs/roadmap/commandkit-migration-discussion.md +++ b/docs/roadmap/commandkit-migration-discussion.md @@ -13,11 +13,11 @@ 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. +its details in U10. That sequencing has not yet been revised. Item 6 selects how +to incorporate the agreed decisions into its dependency baseline, implementation +phases, removal inventory, and acceptance criteria while preserving remaining +choices explicitly. 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. @@ -25,10 +25,17 @@ Item 2 selects the application command structure and input conventions. Item 3 selects native composition, shared loaders, and application preflight. Item 4 selects native reporting, machine output, and outcomes. Item 5 selects conditional debug capture through the shared `--debug` flag, native diagnostics, and a run/ -operation bundle with a `latest` symlink. Capture depth, exact run-report fields, -and other concrete record details remain open below. Item 6 selects verification, -migration guidance, and incorporation into the master roadmap; that incorporation -is still pending. +operation bundle with a `latest` symlink. Item 6 selects verification, migration +guidance, and incorporation into the master roadmap; that incorporation is still +pending. + +The major architectural decisions are settled. Remaining choices are the exact +capture inventory and depth (item 5), run-report fields/versioning and durable +record formats (item 4/U9), and explicit-empty debug-directory handling plus any +demonstrated need for verbosity without capture (item 5). Function signatures, +bundle filenames other than `latest`, and similar implementation details do not +reopen the selected architecture. Broader PromptKit choices remain with the +master roadmap. The PromptKit architecture and checkpoint decisions remain in force. This discussion develops the CommandKit portion of that migration and its interactions @@ -124,9 +131,9 @@ roadmap. The master roadmap has not yet been updated. **Discussion / decision:** Versions and standard capability scope agreed. Adopt the set below, including the move to PromptKit v0.23.3. Items 2–3 select -application commands and composition; subsequent topics address reporting and -debug capture. These are selected migration targets; the application dependencies -have not changed. +application commands and composition; items 4–5 select reporting and debug +capture principles. These are selected migration targets; the application +dependencies have not changed. ### Selected Versions @@ -183,13 +190,14 @@ are selected native features; this does not reintroduce legacy Notarius aliases. 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. + commands, inputs, and result presentation as selected 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. +capability selection with this decision, and incorporate the application wiring +and presentation decisions from items 2–5. Preserve the remaining record and +debug choices explicitly as directed by item 6. ## 2. Native Command Surface And Inputs @@ -309,7 +317,7 @@ with PromptKit's individual-request `--llm-input-file` bindings. ### Preparing Pipeline Inspection Content -**Follow-up clarification:** Leverage ConfigKit for the composed, decoded +**Selected design:** Use ConfigKit for the composed, decoded configuration, defaults, imports, overlay, inheritance, overrides, and native provenance/redacted inspection. Feed that loaded configuration through the same application resolution used by validation and execution to obtain selected @@ -322,7 +330,8 @@ Generic effective configuration and source explanations remain available through `config show` and `config explain`. ConfigKit's safe inspection facilities do not automatically redact an arbitrary application report; select appropriate report content rather than dumping the raw typed configuration. Item 3 selects loader -wiring; detailed report content remains with item 4. +wiring; item 4 selects reporting conventions and identifies remaining run-report +contract choices. ### Removals And Remaining Work @@ -335,7 +344,8 @@ native `config show`, `config profile` with `promptkit show profile`, and bespok Application handlers still validate meaningful input combinations and translate typed inputs into pipeline selections. Native `--debug` supplies reporting behavior and conditional artifact capture as selected in item 5. -Items 3–4 own loader behavior, exact report content, and outcome presentation. +Items 3–4 select loader behavior, report content categories, and outcome +presentation; exact run-report fields and durable formats remain with U9. Evidence: [CommandKit command/input conventions](../../../commandkit/docs/cli.md#registered-command-syntax), [reusable PromptKit flags](../../../commandkit/docs/consumers/guide.md#request-builders-and-loading), @@ -492,8 +502,8 @@ requests; share concrete request-building functions when useful without simulating pipeline execution to populate an inspection command. Output publication, checkpoints, debug capture, and execution records belong to -the run path. Loaders do not initialize those resources; debug allocation timing -remains with item 5. Remove command-specific loading paths, copied configuration +the run path. Loaders do not initialize those resources; item 5 selects debug +allocation timing. Remove command-specific loading paths, copied configuration and resource inspection, eager runtime setup, and duplicated preflight orchestration. No broader application/package reorganization is required by this decision. @@ -652,9 +662,10 @@ policy, and optional diagnostics agreed. Use `--debug` for native verbosity and durable capture with `/tmp/notarius-debug` as the default root. Operator-owned data handling and convenient diagnostic representation are agreed. Replace the summary/trace hierarchy with a compact run index, configuration and composition -snapshots, and operation records; maintain a `latest` symlink at the debug root. Convenience -guides capture depth; the precise inventory and serialized fields remain under -discussion. Implementation is pending. +snapshots, and operation records; maintain a `latest` symlink at the debug root. +Convenience guides capture depth; the precise inventory and serialized fields +remain under discussion. Explicit-empty directory handling and any demonstrated +need for verbosity without capture also remain open. Implementation is pending. ### Shared Debug Control With Conditional Capture @@ -1022,8 +1033,9 @@ that implementation acceptance checks have already passed. ## Evidence And Reading -These are starting points for discussion, not a completed CommandKit migration -audit. Sibling links assume the local repositories remain available. +These sources support the discussion and selected decisions; they do not +constitute a completed implementation audit. Sibling links assume the local +repositories remain available. - [Notarius CLI implementation overview](../internal/cli.md) and [configuration internals](../internal/configuration.md).