From e476c08ea43656c8139ad0afd6a3805cd4b75b97 Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Fri, 20 Nov 2026 02:17:59 +0000 Subject: [PATCH] Consolidate the CommandKit adoption roadmap --- docs/roadmap/commandkit-notepad.md | 10 +- docs/roadmap/commandkit.md | 370 +++++++++++++++++++++++++++++ 2 files changed, 375 insertions(+), 5 deletions(-) create mode 100644 docs/roadmap/commandkit.md diff --git a/docs/roadmap/commandkit-notepad.md b/docs/roadmap/commandkit-notepad.md index 0651e81..d06e37b 100644 --- a/docs/roadmap/commandkit-notepad.md +++ b/docs/roadmap/commandkit-notepad.md @@ -1,11 +1,11 @@ # CommandKit migration notepad -Status: discussion decisions recorded; ready for roadmap consolidation. +Status: consolidated into the [CommandKit adoption roadmap](commandkit.md). 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 +agreed direction and discussion history. The roadmap owns the consolidated +target and required work; this notepad is not an implementation plan or a description of current Narratio behavior. ## Agreed direction @@ -575,8 +575,8 @@ independent `artifacts` family. Detailed implementation sequencing remains for the subsequent plan; release version selection remains deferred. The configuration ownership boundary is recorded in -[ADR 0003](../adr/0003-assign-configuration-ownership.md). Roadmap consolidation -is the next planning step. +[ADR 0003](../adr/0003-assign-configuration-ownership.md). The consolidated +[roadmap](commandkit.md) is ready for implementation planning. ## Discussion and decision record diff --git a/docs/roadmap/commandkit.md b/docs/roadmap/commandkit.md new file mode 100644 index 0000000..d343988 --- /dev/null +++ b/docs/roadmap/commandkit.md @@ -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.