Consolidate the CommandKit adoption roadmap

This commit is contained in:
2026-11-20 02:17:59 +00:00
parent 8824ce330f
commit e476c08ea4
2 changed files with 375 additions and 5 deletions

370
docs/roadmap/commandkit.md Normal file
View File

@@ -0,0 +1,370 @@
# CommandKit Adoption
Status: agreed target; implementation pending.
This roadmap consolidates the [migration discussion](commandkit-notepad.md).
It defines the intended end state and required work. Detailed implementation
sequencing belongs in a subsequent plan.
## Objective And Scope
Make Narratio a CommandKit-native application, adopting upstream command,
configuration-inspection, reporting, and invocation conventions. Deliver one
complete cutover. Backward compatibility with the existing CLI is a non-goal;
release documentation will explain the migration.
Adopt `go.maximumdirect.net/commandkit` v0.7.0 and
`go.maximumdirect.net/ckconfig` v0.9.0 as the initial baseline. They fit Narratio's
existing ConfigKit v1.2.1 and Go 1.27.0 minimum. Review relevant public contract
changes before deliberately selecting later releases.
Preserve consequential pipeline behavior: canonical stage sequencing, semantic
resume evidence, publication boundaries, restore safety, and cleanup rules.
Changes needed for the agreed configuration ownership, CLI, reports, and
cancellation behavior are in scope.
## Current Baseline
The [CLI reference](../cli.md), [configuration internals](../internal/configuration.md),
and [internal overview](../internal/overview.md) describe the implementation.
The migration starts from these differences:
- `internal/app` owns handwritten routing, flag parsing, help, output, and exit
handling. CommandKit and ckconfig are not dependencies yet.
- ConfigKit already loads configuration, but subsequent campaign/session
composition and artifact-family expansion modify runtime configuration.
Expansion adds concrete artifacts and publish rules to the pipeline object.
- Show and diff use a safe final-domain projection frozen as a separate native
result; provenance comes from retained authoring results. App inspection
acquires campaign/party context for expansion, and comparisons require the
same campaign.
- Session selection and operations exist, but their CLI wiring needs the agreed
identity/file distinction, native scopes, and explicit party-file selection.
- The command dispatcher starts with `context.Background()`. The runner releases
locks on failure, but stage failures return no run summary and bypass its
successful finalization path. Signal propagation, partial reporting, and
terminal persistence need coordinated changes.
Consumer probes against the selected upstream releases confirmed native scope
inspection, app-only overrides, independent comparisons, and lazy acquisition.
Two upstream limits are already accommodated: the generated `config` group
cannot accept Narratio subcommands, and execution commands have no reusable
override binding. The design uses a separate `artifacts` family and defers
execution overrides. Neither limitation blocks adoption.
## Target Behavior
### Ownership And Configuration Handoff
Follow [ADR 0003](../adr/0003-assign-configuration-ownership.md): ConfigKit owns
configuration through the completed handoff; Narratio consumes it without
mutation and derives domain objects; CommandKit and ckconfig own CLI mechanics
and native inspection.
Supply schemas, defaults, configuration validation, and genuine resolution
rules through ConfigKit's supported lifecycle. Applicable campaign defaults for
session configuration complete there. Native inspection uses the actual result,
including its values, provenance, history, and validation evidence.
Derive party/player projections, concrete artifact catalogs, execution plans,
and publication actions as separate domain products. Keep their validation in
the appropriate domain operation. Do not put these products back into the
configuration, manufacture inspection evidence for them, or move domain work
into configuration callbacks merely to include it in `config show`.
Safe persisted configuration and domain records may continue serving preparation
and resume. They do not replace the native inspection result. Resume remains
based on result-affecting semantic evidence, not configuration provenance or a
blanket effective-digest cache key.
### Command Organization
```text
narratio
├── run SESSION
├── artifacts
│ ├── list
│ └── regenerate 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
├── version
├── completion
└── help
```
`run SESSION` selects the full pipeline by default. `--from` and `--through`
select an inclusive contiguous range. `--stage` selects one stage and is mutually
exclusive with range selectors. `--force` is independent. `session plan` accepts
the same stage/range, force, and artifact selections.
`artifacts regenerate SESSION` forces extraction through analysis without
publication, sharing execution logic with `run`. It regenerates the complete
configured extraction bundle; `--artifacts` selects analysis targets and their
prerequisites, not extraction lanes.
`artifacts list` reports configured definitions, producers, and dependencies,
including family members derived from the selected pipeline, campaign, and
party. `session artifacts SESSION` reports availability and publication state.
Planning exposes derived execution and publication work. These are domain views,
separate from native configuration inspection.
Remove `run-stage`, `analyze`, and `publish`; single-stage work uses
`run --stage`, adding `--force` when requested. Move top-level `clean` to
`session clean` and `regenerate-artifacts` to `artifacts regenerate`.
Replace `config artifacts` with `artifacts list`. Use explicit `session locks list`.
Bare command groups display native help. Do not retain compatibility aliases or
duplicate `--session-id` flags for positional session arguments.
### Configuration Scopes And Selection
Expose four native ckconfig scopes, with `app` as the default:
| Scope | Configuration inspected |
| --- | --- |
| `app` | Resolved application/pipeline configuration |
| `campaign` | Selected campaign settings |
| `session` | Selected session settings, including applicable configuration defaults |
| `party` | Party configuration selected explicitly or through the campaign default |
Enable applicable native show, path selection/discovery, sources, explanation
and history, validation findings and filters, and detailed comparison. Filtering
findings does not change validation success. Retain native per-operation
`--scope all` behavior, reporting missing required context rather than silently
omitting scopes. There is no additional raw/resolved view or Narratio-owned
path/provenance reconciliation.
Acquire only the context required by the selected scope. App inspection does
not acquire campaign/party context solely for artifact expansion. Campaign
inspection does not require a session. Catalog and planning commands acquire
the context needed for their domain work.
| Selector | Meaning |
| --- | --- |
| `--config PATH` | Pipeline configuration root, regardless of scope |
| `--overlay NAME` | Pipeline overlay |
| `--campaign ID` | Campaign identity |
| `--campaign-file PATH` | Explicit campaign file |
| `--session ID` | Session identity for configuration inspection |
| `--session-file PATH` | Explicit session file |
| `--party-file PATH` | Explicit party file in place of the campaign default |
| `--secrets-dir PATH` | Credential-bootstrap directory |
Session-oriented domain commands use positional session identity and may also
select `--session-file`. A file selects the source; an explicit identity asserts
the intended effective identity after resolution. Inspection may obtain identity
from the file when no identity is asserted. Mismatches fail clearly.
Resolve explicit CLI-relative paths from the invocation directory. An explicit
party file supplies the roster consistently for inspection, players, artifact
expansion, planning, and execution; missing or invalid explicit files fail
without falling back to the campaign default. Native source evidence identifies
the selected file and its imports.
Diff resolves both sides independently, permitting different files, overlays,
and campaigns. Add `--against-campaign`, `--against-campaign-file`,
`--against-session`, `--against-session-file`, and `--against-party-file` alongside
native `--against-config` and `--against-overlay`. Omitted right-side selectors
use normal defaults, including that side's campaign-default roster; they do not
inherit left-side values.
### Session Acquisition
Share selection rules between inspection and execution: load an explicit file
exactly; otherwise use normal local discovery, then remote discovery when no
local session exists and identity is known. Invalid content, access failures,
and identity mismatches do not trigger fallback. Remote discovery prefers the
authored session-root configuration, using the committed prepared snapshot only
when the authored object is absent.
Inspection may perform these network reads without a separate opt-in. It does
not initialize a workspace, restore files, acquire execution locks, or change
manifests. Source inspection distinguishes local, remote-authored, and committed
snapshot origins. No forced-local or forced-remote selector is needed initially.
### Overrides
Enable native `--set POINTER=JSON` only for app inspection and `--against-set`
for its comparison side. ConfigKit owns assignment acceptance, ordering, merge,
conflict, path, and typed-secret semantics. Do not add protected-field lists,
translate domain catalog paths, or promise that every displayed path is
overridable. Normal configuration validation and secret-safe output still apply.
Campaign, session, and party use file selectors rather than field overrides.
Native aggregate inspection rejects overrides because not every scope supports
them; aggregate operations without overrides retain upstream behavior. Do not
add scope-specific override flags or cross-scope dispatch.
Inspection overrides affect that invocation only. Defer field overrides on
execution and planning until CommandKit supplies a reusable binding. Narratio
will not build its own parser, binding, or equivalent machinery. Files and
overlays select execution settings; this convenience is not an adoption
dependency.
### Reports And Diagnostics
Use native reporting and ckconfig report shapes. Domain operations return one
structured result where meaningful, with public report values separate from
internal state and manifests:
| Operation | Useful report content |
| --- | --- |
| Run/regenerate | Identities, selected stages, execution/reuse, artifacts, completion |
| Plan | Execution/reuse decisions and reasons, targets, prerequisites |
| Status | Local stage state and available remote publication information |
| Artifact inspection | Source identities, producers, dependencies; availability/publication for session views |
| Session validation | Overall outcome and findings |
| Restore/clean | Planned/completed actions, conflicts, dry-run status |
| Initialization/lock mutations | Concise confirmation of the affected session, destination, or lock |
Use native automatic presentation, including YAML for structured values, and
`--format text|yaml|json`. Add text templates only where representative output
shows a substantial readability benefit, presenting the same report data.
Document public report fields without adding a schema-version mechanism.
Report format does not change generated artifact formats, including session YAML.
CommandKit owns console presentation: results on stdout, diagnostics/progress
on stderr. Ordinary mode shows results and failures; warnings/information require
verbose/debug; progress requires `--progress` or debug. Quiet suppresses successful
results and progress while preserving failures. Material conditions also appear
in the result, independent of diagnostic visibility.
Keep downstream streams in existing captured logs and provide concise console
context and log locations without automatic replay. Quiet does not disable logs
or persistence; debug does not automatically enable downstream debug artifacts.
Visibility options do not change pipeline selection, execution, or retention.
Failures after meaningful work return partial results alongside the failed
outcome, preserving earlier durable successes. Early input failures need no
empty report. Native report-delivery failures do not undo completed work.
### Invocation Lifecycle
Parse and check input combinations before credential bootstrap. Load required
configuration, derive domain context, then acquire execution resources. Finalize
state and release resources before completing the invocation. Configuration-
dependent checks occur after loading. Help, version, completion, and scope
discovery do not bootstrap secrets, load configuration, contact storage, or
initialize adapters.
The process boundary supplies a context canceled by Ctrl-C or termination.
Propagate it to active operations and existing adapter shutdown paths; stop
scheduling further work. Attempt appropriate terminal manifest persistence and
lock release, preserve completed checkpoints, and report meaningful partial
results. Retain persistence or shutdown errors alongside the original failure.
Cancellation does not run the cleanup stage or delete resumable work. Abrupt
process death does not guarantee finalization.
Use native outcomes: `0` success; `1` operational failure, cancellation, or output
failure; `2` invalid invocation or identifiable configuration input; `3` changed
`diff --check`. Use public error classification and retain underlying error
identity, avoiding error-string matching and duplicate terminal failures.
Provide native completion for command paths, flags, static stage/scope choices,
and applicable file/directory selectors.
## Required Work
These work areas describe scope, not mandatory buildable milestones.
1. **Replace the command boundary.** Add the selected dependencies and native
application/command declarations. Wire typed inputs to domain operations,
introduce the artifacts family and revised selectors, and remove superseded
routing, parsers, help, output, and shortcuts. Retain shared bounded execution
for run, planning, and regeneration where applicable.
2. **Correct the configuration handoff.** Review post-load composition: move
genuine configuration defaults/resolution into supported ConfigKit callbacks;
derive catalogs, player projections, and publication actions separately.
Adapt planning, stages, adapters, prepared records, and semantic evidence to
consume those products without mutating completed configuration. Remove
replacement inspection snapshots and their separate evidence path while
retaining records needed for preparation and resume.
3. **Integrate native scopes and acquisition.** Expose genuine results through
`ckconfig.FromConfigKit`, register the four scopes and their selectors, and
enable app-only inspection overrides. Share local/remote selection with
execution, add party-file selection, and remove the same-campaign diff
restriction. Keep each comparison side independent and acquisition lazy.
4. **Integrate presentation and lifecycle.** Define domain report values, route
diagnostics through CommandKit, and replace ad hoc status handling. Propagate
signal cancellation and adapt runner failure/finalization paths to preserve
partial results and attempt terminal persistence. Add native completion.
5. **Complete integration and migration.** Update behavioral tests, remove
obsolete CLI machinery and expectations, review dependency attribution, and
update canonical documentation, examples, and affected scripts with the
implementation. Prepare workflow-oriented release migration guidance.
## Verification And Completion
Use real CommandKit and ConfigKit with controlled external boundaries. Cover
the integration risks without duplicating upstream parser/configuration tests:
- Native commands and selectors invoke the intended operation; stage/range,
force, analysis-target selection, and complete-bundle regeneration retain
their agreed meanings.
- Native inspection uses genuine results and evidence. Catalog/plan derivation
does not mutate them. Equivalent files and overlays have the same loading
semantics across inspection, planning, and execution; inspection overrides
remain invocation-local and unavailable on execution commands.
- Required context, identity assertions, exact-file errors, local/remote
fallback, and source labels behave consistently without inspection creating
runtime state. Party selection reaches each consumer, and diff sides remain
independent. App-only and aggregate override behavior follows ckconfig.
- Structured results remain separate from diagnostics, retain meaningful partial
work, and use native outcomes. Lazy commands avoid configuration/services;
cancellation reaches active work, preserves checkpoints, and permits terminal
persistence and lock release, including their failure reporting.
- Existing consequential stage, resume, publication, restore, and cleanup
behavior remains protected. Safe inspection, diagnostics, and persistence
preserve the established secret-handling boundary.
Update or retire tests enforcing replaced CLI conventions while retaining useful
domain coverage. Default verification remains offline and independent of live
services, real credentials, and paid model calls. Run the repository's established
final checks from [Development](../development.md#validation): tests, race-enabled
tests, vet, and build, including documentation and maintained-example checks.
Carry out implementation as one end-to-end sprint. Intermediate commits may be
incomplete, incoherent, or noncompiling; use focused checks where useful and
report their state accurately. Do not add compatibility scaffolding to make each
commit independently shippable. Completion requires the coherent, compilable,
validated final application and its documentation.
## Migration And Deferred Work
Release guidance will include an old-to-new command table and explain identity
versus file selectors, party-file selection, inspection-only overrides, native
flag repetition/placement, inspection versus domain views, comparison defaults,
structured output, diagnostic visibility, exit classifications, and cancellation.
Update the [CLI](../cli.md), [configuration](../config.md),
[operations](../operations.md), relevant internal/integration documentation,
and [maintained examples](../../examples/README.md) when implementation lands.
Release notes summarize the impact and link to those canonical contracts.
Select the release number under [release policy](../policy/release.md) once the
final compatibility impact is known; this roadmap does not authorize publication.
Execution/planning overrides await a reusable upstream binding. Dynamic
campaign/artifact completion and streaming JSON events are deferred. Direct
ckprompt/PromptKit ownership, downstream-tool adoption, workspace reorganization,
and Scriptorium-backed input discovery and early dependency checks remain
separate work. The catalog exposes Narratio's configured knowledge; this
migration does not promise to discover prompt requirements or prove that every
configured pipeline can complete.
No significant design decisions remain open. Implementation sequencing and
release selection do not block preparation of the implementation plan.