Files
narratio/docs/roadmap/commandkit-notepad.md

16 KiB

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.

Command organization

Use one general execution command, one regeneration convenience, and command families for session operations and configuration:

narratio
├── run SESSION
├── regenerate-artifacts SESSION
├── session
│   ├── init SESSION
│   ├── plan SESSION
│   ├── validate SESSION
│   ├── status SESSION
│   ├── restore SESSION
│   ├── clean [SESSION | --all]
│   ├── artifacts SESSION
│   └── locks
│       ├── list SESSION
│       ├── add SESSION SOURCE
│       └── remove SESSION SOURCE
├── config
│   ├── scopes
│   ├── validate
│   ├── show
│   ├── sources
│   ├── explain
│   ├── diff
│   └── artifacts
├── version
├── completion
└── help

run SESSION selects the full pipeline by default. --from and --through select an inclusive contiguous range. Add --stage for one stage, mutually exclusive with the range selectors; it selects the same stage as both endpoints. --force independently requests forced execution. session plan accepts the same execution-selection options, including stage/range, force, and artifacts.

Use positional session IDs on session-oriented commands and remove their duplicate --session-id spelling. Campaign and configuration selection remain flags, with spelling defined below.

Remove run-stage, analyze, and publish. Single-stage execution uses run --stage; forced regeneration adds --force explicitly. Move top-level clean to session clean. Use the explicit session locks list operation so the bare locks group displays native help.

Keep regenerate-artifacts as an application-owned command sharing execution logic. Its useful domain intent is forced extraction through analysis without publication. It regenerates the complete configured extraction bundle; --artifacts selects analysis targets and their required prerequisites, not extraction lanes. The command name makes regeneration explicit.

config artifacts remains a Narratio-specific catalog alongside the standard ckconfig operations, with the view defined below.

Configuration scopes and views

Expose four scopes corresponding to Narratio's configuration domains. Use app as the native default scope.

Scope Effective configuration
app Pipeline configuration, including campaign-dependent artifact expansion and generated publish rules
campaign The selected campaign's settings
session The selected session's settings, including applicable campaign defaults
party The selected campaign's canonical party roster

Use effective values for show and diff, native provenance for sources and explain, and domain validation for validate. Inspection reflects imports, overlays, inheritance, defaults, and applicable Narratio resolution. A separate raw-versus-resolved mode is not part of the initial design.

app show/diff includes the concrete artifacts and publish rules execution receives. Provenance must distinguish authored and derived values accurately; a generated artifact must not appear to have been literally declared in a source file. Use native evidence without inventing source origins.

Keep config artifacts as a focused catalog of definitions and dependencies derived from the same effective pipeline. session artifacts SESSION reports session-specific availability and publication state. Future input discovery can extend the configuration catalog separately from this migration.

Acquire only the context needed for the selected scope. Party-driven pipeline expansion requires the selected campaign and party; effective session settings require the session and applicable campaign context. Campaign inspection does not require a session. Scope discovery and help do not load configuration. Report missing required context explicitly rather than presenting a partially resolved view as complete.

Retain CommandKit's operation-specific --scope all behavior. Do not silently omit a selected scope whose required context is missing.

Comparisons use independently resolved left and right selections through native selectors and their --against-* counterparts. Permit comparisons across overlays, configuration files, and campaigns; the existing same-campaign restriction is not retained.

Session acquisition and selectors

Inspection and execution use the same session-selection rules. Load an explicit session file exactly when supplied; otherwise use normal local discovery, then configured remote discovery when no local session exists and its identity is known. Missing or invalid explicit files are errors. Invalid content, access failures, and identity mismatches do not trigger fallback to another source.

Remote discovery prefers the authored session-root configuration and falls back to the committed prepared snapshot only when the authored object is absent. Configuration inspection permits these network reads without requiring a separate remote opt-in. It creates no local runtime state: no workspace initialization, restored files, execution locks, or manifest changes. Source inspection identifies local, remote-authored, and committed-snapshot origins. Forced-local or forced-remote selection is not part of the initial design.

Selector Meaning
--config PATH Pipeline configuration root for every scope
--overlay NAME Pipeline overlay
--campaign ID Campaign identity
--campaign-file PATH Explicit campaign configuration file
--session ID Session identity on configuration inspection commands
--session-file PATH Explicit session configuration file
--secrets-dir PATH Credential-bootstrap directory selection

Changing scope does not change the meaning of --config. Session-oriented commands retain their positional session identity and can also select an explicit source using --session-file.

Identity and file selectors are complementary: the file selects the source and an accompanying ID asserts the intended identity. Mismatches fail clearly. For inspection, the file can supply identity when no identity selector is given; session-oriented commands retain their required positional identity. Select the party through its campaign; an independent --party-file selector is not part of this migration.

Comparisons expose --against-campaign, --against-campaign-file, --against-session, and --against-session-file alongside CommandKit's native right-side configuration selectors. Omitted right-side selectors use normal defaults rather than inheriting left-side values.

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:

Narratio's existing CLI reference and configuration internals provide the current baseline. They remain current-behavior documents until the migration lands.

Open decisions

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.

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.

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.

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.

2026-11-19 — Command organization agreed

Accepted the proposed command tree, run --stage selector, positional session IDs, shared selection syntax for planning, explicit lock listing, and movement of cleanup under session. Removed the separate single-stage and implicitly forced analysis/publication commands from the target CLI. Retained regenerate-artifacts because it expresses a useful multi-stage regeneration workflow. Configuration scopes and views are the next discussion topic.

2026-11-19 — Configuration scopes and views agreed

Accepted app, campaign, session, and party scopes, with app as default. Show/diff exposes effective values and source/explanation operations use native provenance. Concrete artifacts remain visible in the effective pipeline and the separate configuration catalog; session artifact inspection owns availability. Accepted context-dependent acquisition, explicit missing-context errors, native aggregate-scope behavior, and independently resolved comparisons across campaigns. Session acquisition policy and selector spelling are next.

2026-11-19 — Session acquisition and selectors agreed

Accepted shared inspection/execution discovery with automatic remote fallback, read-only acquisition without local runtime state, and explicit source provenance. Accepted distinct identity/file selectors, identity assertions when both are supplied, campaign-owned party selection, and independent right-side comparison selectors. Optional configuration capabilities and overrides are the next discussion topic.

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.