2026-11-19 15:54:26 +00:00
# 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.
2026-11-19 16:01:02 +00:00
### Command organization
Use one general execution command, one regeneration convenience, and command
families for session operations and configuration:
```text
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
2026-11-19 16:12:21 +00:00
flags. Configuration inspection selector spelling remains to be settled.
2026-11-19 16:01:02 +00:00
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
2026-11-19 16:12:21 +00:00
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 policy and exact application
selector spellings remain open below.
2026-11-19 16:01:02 +00:00
2026-11-19 15:54:26 +00:00
## 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
2026-11-19 16:12:21 +00:00
### Session acquisition and selector spelling
2026-11-19 15:54:26 +00:00
2026-11-19 16:12:21 +00:00
Decide whether configuration inspection uses normal remote session discovery
when no local source exists, or requires an explicit remote selection. Define
the read-only boundary, including network reads and any local materialization.
2026-11-19 15:54:26 +00:00
2026-11-19 16:12:21 +00:00
Choose consistent flags for campaign/session identities versus explicit files
and their right-side comparison equivalents. Session-oriented commands retain
their agreed positional IDs; standard configuration commands use selectors
suited to the native ckconfig command structure.
2026-11-19 15:54:26 +00:00
2026-11-19 16:01:02 +00:00
### Optional configuration capabilities
2026-11-19 15:54:26 +00:00
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.
2026-11-19 16:01:02 +00:00
### Reports and machine-readable output
2026-11-19 15:54:26 +00:00
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.
2026-11-19 16:01:02 +00:00
### Diagnostics and invocation lifecycle
2026-11-19 15:54:26 +00:00
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.
2026-11-19 16:01:02 +00:00
### Delivery and migration guidance
2026-11-19 15:54:26 +00:00
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 16:01:02 +00:00
### 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 16:12:21 +00:00
### 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 15:54:26 +00:00
### 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.