From 8ba001750e6b9691bad12a18c041a3763a9b0fee Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Thu, 19 Nov 2026 15:54:26 +0000 Subject: [PATCH] Record CommandKit migration direction and open decisions --- docs/roadmap/commandkit-notepad.md | 188 +++++++++++++++++++++++++++++ 1 file changed, 188 insertions(+) create mode 100644 docs/roadmap/commandkit-notepad.md diff --git a/docs/roadmap/commandkit-notepad.md b/docs/roadmap/commandkit-notepad.md new file mode 100644 index 0000000..d6dd1da --- /dev/null +++ b/docs/roadmap/commandkit-notepad.md @@ -0,0 +1,188 @@ +# CommandKit migration notepad + +Status: working discussion notes. Started 2026-11-19. + +Narratio will become a CommandKit-native application. This notepad collects the +agreed direction, open questions, and subsequent decisions before they are +consolidated into a feature roadmap. It is not an implementation plan or a +description of current Narratio behavior. + +## Agreed direction + +### Full native cutover + +Adopt CommandKit's public-facing conventions and recommendations to the fullest +extent. Backward compatibility with Narratio's existing CLI conventions is a +non-goal. Provide migration guidance in release documentation so operators can +update their commands and scripts. + +Use native command declarations, typed inputs, routing, help, version, +reporting, and outcome handling. Adopt upstream parsing and presentation +semantics rather than building compatibility parsers, legacy output modes, or +status translations to reproduce the existing CLI. + +Consequently, differences in repeated-flag handling, option placement, help, +version output, configuration comparison syntax, and exit classification are +migration topics to explain, not legacy behavior to preserve. Existing command +names and shortcuts may survive when they remain useful domain operations; +their historical existence alone does not require retaining them. + +### Modules and ownership + +Plan adoption of CommandKit core and its ConfigKit integration, `ckconfig`. +Use the standard inspection capabilities where they apply to Narratio's +configuration. Generated help and shell completion belong in the direction +for the cutover. + +Narratio continues to own pipeline orchestration, configuration-domain +resolution, artifact selection, manifests, resume, publishing, restore, and +cleanup. CommandKit owns CLI mechanics and presentation through its public +APIs. Application-owned declarations and providers connect those boundaries. + +Keep `ckprompt` and direct PromptKit engine ownership outside this migration. +Narratio delegates prompt execution to Scriptorium. Prompt-requirements +inspection and early pipeline dependency checks remain separate feature work +using an eventual Scriptorium external contract. CommandKit adoption can +proceed independently. + +## Reviewed upstream baseline + +The initial review covered these released modules: + +| Module | Version | Relevant capability | +| --- | --- | --- | +| `go.maximumdirect.net/commandkit` | v0.7.0 | Typed commands and inputs, presence tracking, aliases, help/version, completion, reporting, and outcomes | +| `go.maximumdirect.net/ckconfig` | v0.9.0 | Configuration scopes, validation, safe display, sources, explanation, comparison, and optional overrides | +| `go.maximumdirect.net/ckprompt` | v0.10.0 | PromptKit inspection and request tooling; reviewed for context, outside adoption scope | + +Core v0.7.0 and ckconfig v0.9.0 require Go 1.27.0; ckconfig selects ConfigKit +v1.2.1. Narratio already declares those Go and ConfigKit versions. CommandKit +identifies itself as alpha. Select exact released versions when preparing the +roadmap and revisit these references if that baseline changes. + +Upstream references: + +- [Consumer guide and module selection](https://forge.maximumdirect.net/base-layer/commandkit/src/commit/d330d7637f2e7507eca931a899397222c82bc892/docs/consumers/guide.md) +- [Core CLI conventions](https://forge.maximumdirect.net/base-layer/commandkit/src/commit/b57bfe176cff05a892e6cb07ebb5f350239e55d4/docs/cli.md) +- [ConfigKit integration public contracts](https://forge.maximumdirect.net/base-layer/commandkit/src/commit/9962368f0c1ea1f6ad010638e94621091105d745/integrations/ckconfig/contracts.go) + +Narratio's existing [CLI reference](../cli.md) and +[configuration internals](../internal/configuration.md) provide the current +baseline. They remain current-behavior documents until the migration lands. + +## Open decisions + +### 1. Domain command organization + +Which commands and conveniences should the native CLI expose? Review `run`, +`run-stage`, `analyze`, `publish`, `regenerate-artifacts`, `clean`, and the +`session` family for operator usefulness. Decide how session IDs, stage bounds, +and artifact selections should be expressed using native typed inputs. + +CommandKit aliases redirect command paths; they do not inject flags or +operands. Retained conveniences that select a stage or force a range therefore +need application-owned commands sharing domain execution logic. Decide which +are worth keeping on that basis, without a compatibility requirement. + +### 2. Configuration scopes and views + +Which named scopes should be available initially: one effective pipeline scope, +or also campaign, session, and party scopes? Define the selectors and acquisition +needed for each, including which inspections should work without a session or +remote access. + +Narratio distinguishes the authored configuration from the resolved domain +view containing concrete artifact families and generated publish rules. Settle +what each standard inspection operation exposes, keeping safe effective values +and truthful native provenance available without confusing their meanings. + +The initial proposal is to use the resolved, credential-safe domain view for +show and diff, native evidence for source/explanation operations, and an +application-specific artifact catalog. Decide the catalog's placement and how +campaign and party context participate in comparisons, including independent +left and right selectors. + +### 3. Optional configuration capabilities + +Determine the useful scope of path-selected show, path explanation, detailed +validation findings, comparison details/check mode, and temporary `--set` +overrides. Prefer the native capabilities wherever the provider can faithfully +support them. + +Overrides require a domain decision: which configurations accept them, and do +execution commands accept the same overrides as inspection? The integration's +ability to parse an override does not establish Narratio's intended loading +contract. Avoid an inspection result that purports to describe execution while +silently using different resolution rules. + +### 4. Reports and machine-readable output + +Design useful report values for planning, status, artifact inventories, +validation, restore, cleanup, and execution summaries. Apply native text, YAML, +and JSON presentation consistently. Decide where a text template improves +operator readability and where native structured presentation is sufficient. + +CommandKit does not transform raw application output into structured reports. +Identify any output that genuinely needs raw bytes and distinguish final +results from diagnostic/progress messages. Decide what stability Narratio will +promise for application-owned report fields; do not accidentally make durable +manifest schemas the CLI response contract. + +### 5. Diagnostics and invocation lifecycle + +Classify existing messages into CommandKit's result, failure, warning, +information, progress, and debug categories. Use native visibility rules, +including their suppression behavior, and ensure failures communicate the +actionable context. Coordinate this with existing durable logs and stage +diagnostics so the CLI does not emit duplicate messages. + +Define where configuration acquisition and secrets bootstrap occur so help, +version, completion, and invalid syntax do not unnecessarily initialize runtime +services. Narratio owns process startup, signal handling, cancellation, and +exit; decide how that lifecycle supplies CommandKit invocations while retaining +session locking and failure persistence. + +Completion can suggest commands, static values such as stage names, and +filesystem paths. Decide which declarations receive those hints; dynamic +campaign/artifact discovery would need a separately supported capability. + +### 6. Delivery and migration guidance + +Choose implementation work units that lead to one complete native cutover. +Intermediate development steps need not become a supported dual CLI. + +Once the target command/report surface is settled, identify affected examples, +operator procedures, scripts, and downstream callers. Release guidance should +map old workflows to their native equivalents and explain parsing, output, +diagnostic, and exit-status changes. Select the release version under the +repository's release policy when the compatibility impact is concrete. + +Record appropriate validation for domain behavior and CLI integration in the +eventual plan. Dependency attribution and canonical documentation updates belong +to the adoption work. No release version or publication action is selected here. + +## Discussion and decision record + +### 2026-11-19 — Initial direction + +Accepted the direction of adopting core and ckconfig while keeping direct +PromptKit integration and Scriptorium requirements work separate. The initial +review identified command design, configuration views, reporting, and lifecycle +as the main discussion areas. + +The user established full CommandKit-native cutover as the guiding decision: +adopt upstream public conventions and recommendations to the fullest extent, +provide release migration guidance, and treat existing CLI compatibility as a +non-goal. This settles the earlier question of whether to preserve legacy CLI +conventions. + +### Continuing the discussion + +For each topic, record the question, the agreed outcome, its rationale, and any +remaining dependency or follow-up. Date decisions and update the corresponding +open topic so settled issues are not repeatedly reopened. Distinguish proposals +from accepted decisions. + +Once the relevant decisions are settled, consolidate the target behavior, scope, +compatibility impact, and acceptance criteria into the feature roadmap. Keep +implementation sequencing for the subsequent plan.