768 lines
41 KiB
Markdown
768 lines
41 KiB
Markdown
# CommandKit migration notepad
|
|
|
|
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 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
|
|
|
|
### 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.
|
|
|
|
ConfigKit owns configuration policy and the lifecycle through the final,
|
|
fully resolved configuration handoff. Narratio supplies its configuration
|
|
schema, domain defaults, validation, and genuine configuration-resolution
|
|
rules through ConfigKit's supported extension points. Those callbacks operate
|
|
within ConfigKit's lifecycle and provenance model.
|
|
|
|
Narratio owns interpreting the handed-off configuration and using it for
|
|
pipeline orchestration, artifact selection, manifests, resume, publishing,
|
|
restore, and cleanup. CommandKit owns CLI mechanics and presentation;
|
|
`ckconfig` exposes ConfigKit's inspection features through native adapters.
|
|
Narratio provides neutral command declarations, selection, and acquisition
|
|
wiring rather than an intervening configuration or inspection policy layer.
|
|
|
|
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.
|
|
|
|
### Configuration handoff and domain interpretation
|
|
|
|
The completed ConfigKit result is authoritative configuration. Consume it
|
|
without post-handoff mutation. Any genuine configuration defaulting,
|
|
normalization, or resolution must complete within ConfigKit's supported
|
|
lifecycle before handoff, with native evidence. If a required capability is
|
|
missing, identify the specific upstream gap instead of implementing a second
|
|
configuration system in Narratio.
|
|
|
|
Domain interpretation produces separate domain objects. For example, Narratio
|
|
can interpret artifact-family declarations and a party roster to produce a
|
|
concrete artifact catalog, execution plan, and publication actions. It must
|
|
not write those products back into the resolved configuration or present them
|
|
as a replacement effective configuration. Domain derivation remains Narratio's
|
|
responsibility; it does not need to be moved into configuration callbacks merely
|
|
to appear in standard inspection output.
|
|
|
|
Standard inspection uses the genuine ConfigKit result through native
|
|
`ckconfig` adapters. Do not construct a separate effective inspection document,
|
|
combine it with another result's authoring evidence, or add custom path or
|
|
provenance reconciliation. Native inspection and override semantics are
|
|
upstream contracts that Narratio exposes neutrally.
|
|
|
|
### Command organization
|
|
|
|
Use one general execution command and command families for artifacts, session
|
|
operations, and configuration:
|
|
|
|
```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. 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.
|
|
|
|
Use `artifacts regenerate SESSION` for forced extraction through analysis
|
|
without publication, sharing execution logic with `run`. It regenerates the
|
|
complete configured extraction bundle. `--artifacts` selects analysis targets
|
|
and their required prerequisites, not extraction lanes.
|
|
|
|
Use `artifacts list` for configured artifact definitions, producers, and
|
|
dependencies, including generated family members from the selected pipeline,
|
|
campaign, and party context. Bare `artifacts` displays native group help.
|
|
`session artifacts SESSION` retains session-specific availability and
|
|
publication reporting.
|
|
|
|
Narratio owns the `artifacts` family; `ckconfig` owns the standard `config`
|
|
family. Replace the proposed `config artifacts` and top-level
|
|
`regenerate-artifacts` spellings without compatibility aliases.
|
|
|
|
### Configuration scopes and views
|
|
|
|
Expose four scopes corresponding to Narratio's configuration domains. Use `app`
|
|
as the native default scope.
|
|
|
|
| Scope | Native ConfigKit configuration result |
|
|
| --- | --- |
|
|
| `app` | Resolved application/pipeline configuration |
|
|
| `campaign` | The selected campaign's settings |
|
|
| `session` | The selected session's settings, with applicable configuration defaults resolved within ConfigKit's lifecycle |
|
|
| `party` | The party configuration selected by `--party-file` or the campaign default |
|
|
|
|
Expose standard `show`, `diff`, `sources`, `explain`, and `validate` behavior
|
|
through native `ckconfig` adapters for each scope's ConfigKit result. Effective
|
|
values, provenance, history, validation findings, and path behavior come from
|
|
that result and the upstream integration. Narratio supplies domain validation
|
|
through the supported ConfigKit lifecycle, not a separate inspection policy.
|
|
|
|
Remove the earlier requirement that app show/diff include expanded artifacts
|
|
and generated publish rules. They display and compare whatever the genuine
|
|
ConfigKit result contains. Domain products derived after handoff are not added
|
|
to standard inspection, and differences between those products are not added
|
|
to native configuration comparisons. A separate raw-versus-resolved mode is
|
|
not part of the design.
|
|
|
|
Use `artifacts list` as a Narratio-owned domain catalog of concrete artifact
|
|
definitions and dependencies derived from the handed-off configuration and
|
|
selected party. Planning commands describe derived execution and publication
|
|
work. These domain views do not redefine ConfigKit's effective configuration.
|
|
`session artifacts SESSION` reports session-specific availability and
|
|
publication state. Future input discovery can extend the domain catalog
|
|
separately from this migration.
|
|
|
|
Acquire only the context needed for the selected scope's native configuration
|
|
load. Applicable campaign defaults for session configuration resolve before
|
|
handoff. Standard app inspection does not acquire campaign/party context solely
|
|
to expand runtime artifacts. Domain catalog and planning operations acquire
|
|
the additional context needed for domain work. Campaign inspection does not
|
|
require a session. Scope discovery and help do not load configuration. Report
|
|
missing required context explicitly rather than presenting an incomplete load
|
|
as a complete configuration result.
|
|
|
|
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 |
|
|
| `--party-file PATH` | Explicit party roster file in place of the campaign default |
|
|
| `--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. Check that assertion against
|
|
the effective configuration after loading and resolution; mismatches fail
|
|
clearly.
|
|
For inspection, the file can supply identity when no identity selector is
|
|
given; session-oriented commands retain their required positional identity.
|
|
|
|
The campaign supplies the default party file. `--party-file` selects an alternate
|
|
roster for the invocation without editing the campaign or its usual roster.
|
|
Resolve CLI-relative paths from the invocation directory and load an explicit
|
|
file exactly; a missing or invalid selected file fails rather than falling back
|
|
to the campaign default. Apply the same selection throughout inspection,
|
|
players derivation, artifact expansion, planning, and execution. Source evidence
|
|
identifies the selected roster and its imports.
|
|
|
|
Comparisons expose `--against-campaign`, `--against-campaign-file`,
|
|
`--against-session`, `--against-session-file`, and `--against-party-file`
|
|
alongside CommandKit's native right-side configuration selectors. Omitted
|
|
right-side selectors use normal defaults rather than inheriting left-side
|
|
values, including each side's campaign-default party file.
|
|
|
|
### Configuration inspection capabilities
|
|
|
|
Enable the full applicable native inspection capabilities across the four
|
|
configuration scopes:
|
|
|
|
- path-selected show using JSON Pointer syntax;
|
|
- explanation and path discovery, including available history and provenance;
|
|
- detailed validation findings with native severity and code filters;
|
|
- detailed comparisons with before/after values and presence information; and
|
|
- native `diff --check`, including status `3` when differences exist.
|
|
|
|
These capabilities use upstream operations and evidence from the scope's native
|
|
result. Filtering findings changes presentation, not validation success.
|
|
ConfigKit owns the relationship between effective, historical, explainable,
|
|
and overridable paths; Narratio does not add a writable-path registry,
|
|
reinterpret explicitness, or manufacture provenance for domain products.
|
|
|
|
### Native inspection overrides; execution overrides deferred
|
|
|
|
Enable native `ckconfig` field overrides only for the `app` inspection scope.
|
|
Campaign, session, and party scopes retain their inspection capabilities;
|
|
alternate inputs use `--campaign-file`, `--session-file`, and `--party-file`.
|
|
|
|
Defer field overrides on Narratio's execution and planning commands until
|
|
CommandKit provides a reusable binding. Do not build a local assignment parser,
|
|
flag binding, or equivalent machinery. Operators use configuration files and
|
|
overlays to select execution settings. This optional convenience is not a
|
|
dependency of the migration.
|
|
|
|
Within standard inspection, `ckconfig` supplies the `POINTER=JSON` binding and
|
|
ConfigKit applies its native override mechanism. Do not introduce additional
|
|
protected-field lists, custom merge semantics, or an override acceptance policy.
|
|
|
|
Use these flag spellings:
|
|
|
|
| Flag | Target |
|
|
| --- | --- |
|
|
| `--set POINTER=JSON` | App/pipeline configuration on native app inspection only |
|
|
| `--against-set POINTER=JSON` | Right-side app/pipeline configuration on app comparisons |
|
|
|
|
Declare native override support only for `app`. Other inspection scopes do not
|
|
accept `--set`; native `--scope all` also rejects overrides because not every
|
|
selected scope supports them. Aggregate inspection without overrides remains
|
|
available as supported by each operation. Do not add scope-specific `--set-*`
|
|
or `--against-set-*` aliases, cross-scope override dispatch, or scope prefixes
|
|
inside JSON Pointers.
|
|
|
|
The additional convenience of modifying a discovered input without preparing a
|
|
file does not justify field overrides for the other domains in this migration.
|
|
File selection can supply the same effective domain values, although its
|
|
authoring and provenance differ from late CLI overrides. This decision removes
|
|
the need to compose overrides across supporting domains or reconcile generic
|
|
and explicitly targeted override flags.
|
|
|
|
ConfigKit applies overrides after typed defaults and decoding, before its
|
|
resolution and semantic validation callbacks. Preserve native explicit empty,
|
|
false, zero, and null values, mapping merge and whole-sequence replacement, and
|
|
duplicate/overlapping-path rejection. Earlier parsing and decoding failures
|
|
remain errors. CommandKit's last-value convention for singleton flags does not
|
|
replace ConfigKit's conflict rules for override records.
|
|
|
|
Override paths and acceptance follow ConfigKit's native input semantics for
|
|
application configuration. Standard inspection does not promise that every
|
|
displayed path accepts an override. Narratio passes explicit assignments to
|
|
ConfigKit without translating runtime catalog paths into input paths or
|
|
patching domain products after handoff.
|
|
|
|
Inspection overrides leave source files unchanged and do not carry into later
|
|
planning or execution. Run metadata and prepared configuration record settings
|
|
selected through files and overlays using established secret-safe
|
|
representations. Reuse remains based on semantic evidence.
|
|
|
|
### Identity assertions and credential overrides
|
|
|
|
Narratio checks the effective campaign/session identity against any explicitly
|
|
asserted identity after loading and resolution so an operation targeting one
|
|
session cannot silently use another session's workspace, lock, manifest, or
|
|
remote destination. This is an ordinary domain consistency check, independent
|
|
of the selected source. Alternate campaign and session values come from file
|
|
selection rather than field overrides. Native app inspection overrides retain
|
|
upstream acceptance without a protected-field list.
|
|
|
|
When no identity is asserted, such as inspection of an explicit session file
|
|
without `--session`, the effective document supplies its identity.
|
|
Session-oriented commands retain their required positional assertion.
|
|
|
|
Credential-related app fields accept native inspection overrides and use
|
|
ConfigKit's ordinary typed-secret handling and normal configuration validation. Safe
|
|
inspection, diagnostics, and persistence remain separate output
|
|
responsibilities; they do not justify additional restrictions on which app
|
|
fields may be overridden.
|
|
|
|
### Reports and machine-readable output
|
|
|
|
Use CommandKit's native reporting system throughout. Produce one structured
|
|
result per invocation where the command has a meaningful result, keeping
|
|
progress and diagnostics separate. Standard ckconfig commands retain their
|
|
native report shapes; Narratio defines report values for its domain operations.
|
|
|
|
| Command family | Report content |
|
|
| --- | --- |
|
|
| `run`, `artifacts regenerate` | Campaign/session identity, selected stages, execution or reuse outcomes, generated artifacts, and completion status |
|
|
| `session plan` | Selected stages, planned execution/reuse decisions and reasons, artifact targets, and prerequisites |
|
|
| `session status` | Local stage state and available remote publication information |
|
|
| Artifact catalogs | Source identities, producers, dependencies, and session-specific availability/publication where applicable |
|
|
| `session validate` | Overall outcome and individual findings |
|
|
| `session restore`, `session clean` | Planned or completed actions, conflicts, and dry-run status |
|
|
| Session initialization and lock mutations | Concise confirmation identifying the affected session, destination, or lock |
|
|
|
|
Support native `--format text|yaml|json` conventions. Start with native automatic
|
|
presentation, including YAML for structured values. Add a custom text template
|
|
only when representative output demonstrates a substantial readability benefit.
|
|
The template presents the same report value rather than a separate information
|
|
model; recreating the existing handwritten text output is not a goal.
|
|
|
|
Long-running operations emit progress through the diagnostic channel and their
|
|
final report through the result channel, allowing JSON results to be captured
|
|
without progress mixed into the document. A streaming JSON event protocol is
|
|
deferred as a separate interface.
|
|
|
|
When execution stops after meaningful domain work, report what completed and
|
|
where work stopped alongside the failed command outcome. Preserve the success
|
|
of earlier durable work. Failures before meaningful domain work, such as invalid
|
|
arguments, need only the native error; do not manufacture an empty run report.
|
|
Report-delivery failure follows CommandKit's native handling and does not undo
|
|
completed pipeline work.
|
|
|
|
Define public report values separately from internal structs and durable
|
|
manifests. Expose information useful to operators and callers without making
|
|
the entire internal state or manifest schema the CLI contract. Document
|
|
application-owned report fields as a public interface. An additional schema
|
|
version mechanism is not part of the initial design; review native report
|
|
changes during dependency upgrades.
|
|
|
|
`--format` controls the command report, not the format of generated artifacts.
|
|
For example, session initialization still writes its YAML configuration when
|
|
the confirmation report uses JSON.
|
|
|
|
### Diagnostics and invocation lifecycle
|
|
|
|
Adopt CommandKit's native visibility rules. Ordinary mode shows results and
|
|
failures; warnings and information require verbose/debug mode. Progress requires
|
|
`--progress` or debug mode. Quiet suppresses successful results and progress
|
|
while retaining failures. Conditions that materially affect the result also
|
|
belong in its structured report rather than depending solely on warning
|
|
visibility.
|
|
|
|
Classify Narratio's messages by their purpose:
|
|
|
|
| Category | Examples |
|
|
| --- | --- |
|
|
| Result | Final execution summary, plan, status, or configuration report |
|
|
| Failure | Failed stage, invalid configuration, or unavailable required input |
|
|
| Warning | Recoverable problem worth investigating |
|
|
| Information | Configuration selection or successful credential-bootstrap summary |
|
|
| Progress | Stage started/completed, artifact completed, or prior work reused |
|
|
| Debug | Additional safe acquisition or execution detail |
|
|
|
|
CommandKit owns console presentation: results go to stdout and diagnostics and
|
|
progress go to stderr. Domain operations return results and errors without
|
|
independently printing duplicate terminal failures at several layers. Preserve
|
|
downstream stdout/stderr in existing captured diagnostic logs; console output
|
|
provides concise context and useful log locations instead of automatically
|
|
replaying downstream output.
|
|
|
|
Durable logs and checkpoints retain their own policies. Quiet does not disable
|
|
logging or persistence. Debug increases diagnostic visibility without
|
|
automatically enabling downstream prompt-rendering/debug artifacts. Reporting
|
|
modes do not change pipeline selection, execution, or retention.
|
|
|
|
Keep startup lightweight and acquire dependencies only when needed:
|
|
|
|
1. Parse the command and validate syntax and input combinations.
|
|
2. Bootstrap credentials when the operation needs configuration.
|
|
3. Load the required configuration through ConfigKit's completed lifecycle,
|
|
then derive the domain context needed by the operation.
|
|
4. Acquire execution resources and perform the operation.
|
|
5. Finalize domain state, release resources, present the result, and return the
|
|
outcome.
|
|
|
|
Help, version, completion, and scope discovery do not bootstrap secrets, load
|
|
configuration, contact storage, or initialize stage adapters. Configuration-
|
|
dependent validation happens after loading; syntactic errors fail before it.
|
|
Session inspection may perform the already-agreed remote reads when needed.
|
|
|
|
The process boundary supplies an invocation context canceled by Ctrl-C or
|
|
termination. Propagate that context through CommandKit and Narratio operations.
|
|
On cancellation, stop scheduling further work, cancel active operations, and
|
|
let existing adapters perform their resource/subprocess shutdown. Attempt the
|
|
appropriate terminal manifest update and release held locks, preserve completed
|
|
checkpoints, and report meaningful partial results. Report persistence or
|
|
shutdown errors alongside the originating cancellation. Cancellation does not
|
|
invoke the pipeline cleanup stage or delete resumable work. Abrupt process
|
|
death is not guaranteed to permit finalization.
|
|
|
|
Use native outcome classification: success is `0`; operational failure,
|
|
cancellation, and output failure use `1`; invalid invocation or identifiable
|
|
configuration input uses `2`; `diff --check` uses `3` when differences exist.
|
|
Use public configuration-error classification support rather than matching
|
|
error strings. Failure explanations identify the affected operation and useful
|
|
next steps while retaining underlying error identity for programmatic access.
|
|
|
|
Include native completion for command paths, flags, static stage/scope values,
|
|
and appropriate file/directory selectors. Dynamic campaign and artifact
|
|
suggestions requiring configuration loading or storage access remain deferred.
|
|
|
|
### Delivery and migration guidance
|
|
|
|
Deliver one complete native CLI cutover through a single end-to-end
|
|
implementation sprint. Optimize the work sequence and commits for efficiently
|
|
reaching the intended final state. Intermediate commits may leave the overall
|
|
application incomplete, incoherent, or noncompiling; they are not independently
|
|
shippable units and do not require standalone application validation. Do not
|
|
introduce temporary compatibility machinery merely to keep each intermediate
|
|
commit working. Report intermediate status accurately, use focused checks when
|
|
useful, and require a coherent, compilable, fully validated final application.
|
|
|
|
Useful work boundaries are core invocation/domain commands; configuration
|
|
handoff, native scopes and inspection overrides, and file selection;
|
|
reports, diagnostics, cancellation, and completion; and integration
|
|
verification, removal of superseded CLI machinery, and documentation. These
|
|
are organizational boundaries, not mandatory buildable milestones or a
|
|
supported dual interface. The subsequent implementation plan determines the
|
|
most efficient order and dependencies.
|
|
|
|
Use CommandKit v0.7.0 and ckconfig v0.9.0 as the initial roadmap baseline.
|
|
Review relevant public contract changes before deliberately selecting a later
|
|
release. Before finalizing implementation details, verify native ConfigKit
|
|
loader and `ckconfig` adapter integration and composition of independently owned
|
|
domain and standard configuration command families. Address required upstream
|
|
capability gaps upstream rather than compensating with custom effective views,
|
|
provenance reconciliation, or replacement configuration behavior.
|
|
|
|
Remove the current post-load configuration mutation and the split between
|
|
runtime inspection snapshots and authoring evidence. Separate domain products
|
|
from the authoritative configuration handoff while preserving their intended
|
|
processing behavior. Do not retain those inspection projections merely to
|
|
reproduce existing output. Safe persisted configuration and domain artifacts
|
|
remain useful records, but do not replace the result used by native inspection.
|
|
|
|
Retain Narratio's stage sequencing, resume authority, publication semantics,
|
|
restore safety, and cleanup rules. Changes required for the agreed ownership
|
|
boundary, inspection, reporting, and cancellation behavior are in scope.
|
|
Workspace reorganization, downstream-tool adoption, and Scriptorium requirements
|
|
inspection remain separate work.
|
|
|
|
Validate the integration through representative behavioral acceptance cases:
|
|
|
|
- Native arguments and selectors reach the intended Narratio operation.
|
|
- Standard configuration commands expose genuine ConfigKit results through
|
|
native adapters, with upstream value, provenance, and path semantics.
|
|
- Domain catalog and plan generation consume handed-off configuration without
|
|
modifying it or replacing the native inspection result.
|
|
- App inspection, planning, and execution use the same configuration loading
|
|
semantics for equivalent file and overlay selections. Inspection overrides
|
|
apply only to the inspection invocation.
|
|
- Explicit party-file selection consistently feeds roster inspection, derived
|
|
players, artifact expansion, planning, and execution; comparison sides remain
|
|
independent.
|
|
- Field overrides are limited to native app inspection. Other scopes and
|
|
aggregate inspection retain native behavior when overrides are unsupported;
|
|
execution and planning commands expose no generic `--set` binding.
|
|
- Reports remain separate from diagnostics and preserve meaningful partial
|
|
results.
|
|
- Help and completion avoid configuration and service acquisition.
|
|
- Cancellation reaches active work, preserves completed checkpoints, and
|
|
permits terminal persistence and lock release.
|
|
- Existing consequential pipeline behavior remains protected.
|
|
|
|
Use real CommandKit and ConfigKit with controlled external boundaries. Update
|
|
or retire tests enforcing superseded CLI conventions while retaining domain
|
|
behavior coverage. Final verification uses the repository's established checks
|
|
without requiring live services or model calls; do not duplicate upstream
|
|
generic parser or configuration tests. Dependency attribution is part of the
|
|
adoption work.
|
|
|
|
Provide workflow-oriented release migration guidance: an old-to-new command
|
|
table plus explanations of removed shortcuts, identity/file selectors including
|
|
party-file selection, inspection-only app overrides, native flag repetition and
|
|
placement, native configuration inspection and its distinction from domain
|
|
catalogs and plans, configuration comparisons, structured output, diagnostic
|
|
visibility, exit classifications, and cancellation. Identify affected examples,
|
|
operator procedures, scripts, and downstream callers.
|
|
Update canonical documentation and maintained examples as implementation lands;
|
|
release notes summarize and link to those contracts rather than duplicate the
|
|
command reference.
|
|
|
|
Select the Narratio release number under the release policy once the final
|
|
compatibility impact is known. No version or publication action is selected by
|
|
these planning decisions. Consolidate the agreed target behavior, boundaries,
|
|
migration impact, and acceptance criteria into a feature roadmap before preparing
|
|
the detailed implementation plan.
|
|
|
|
## 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. The core and ckconfig versions above are the initial
|
|
roadmap baseline; revisit these references if that baseline deliberately 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
|
|
|
|
No unresolved discussion decisions remain. Execution and planning field
|
|
overrides are deferred until CommandKit provides a reusable binding; Narratio
|
|
will not implement its own. Native app inspection overrides remain in scope.
|
|
|
|
Consumer probes against the reviewed releases confirmed native inspection,
|
|
app-only override capabilities, independent comparisons, and lazy acquisition.
|
|
The inability to extend the generated `config` group is resolved by the
|
|
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). The consolidated
|
|
[roadmap](commandkit.md) is ready for implementation planning.
|
|
|
|
## 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.
|
|
|
|
The later artifacts-family decision supersedes the regeneration and catalog
|
|
command locations recorded here.
|
|
|
|
### 2026-11-19 — Configuration scopes and views agreed
|
|
|
|
The later configuration-ownership revision supersedes the expanded app
|
|
inspection view recorded below. The four scopes remain, with standard
|
|
inspection exposing their native ConfigKit results.
|
|
|
|
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.
|
|
|
|
The later override-scope revision supersedes campaign-only party selection by
|
|
adding an explicit party-file selector while retaining the campaign default.
|
|
|
|
### 2026-11-19 — Configuration capabilities and overrides agreed
|
|
|
|
The cross-domain override decision below is superseded by the later
|
|
override-scope revision. Inspection capabilities and native app override
|
|
semantics remain accepted. The subsequent execution-override deferral supersedes
|
|
the inspection/planning/execution parity requirement recorded here.
|
|
|
|
Accepted full applicable inspection capabilities and native overrides across
|
|
all four configuration domains, with parity across inspection, planning, and
|
|
execution. Selected verb-first `--set-app`, `--set-campaign`, `--set-session`,
|
|
and `--set-party` spellings and corresponding `--against-set-*` comparison
|
|
flags, alongside native `--set` and `--against-set`.
|
|
|
|
Clarified that overrides have no Narratio-specific protected fields or custom
|
|
merge semantics. Identity assertions are checked against effective values after
|
|
native overrides and resolution; they do not make identity fields immutable.
|
|
Credential overrides use native typed-secret handling. Safe output and
|
|
persistence do not impose additional override restrictions.
|
|
|
|
### 2026-11-19 — Reporting agreed
|
|
|
|
Accepted native structured reporting with one meaningful result document per
|
|
invocation, separate diagnostics/progress, and native ckconfig report shapes.
|
|
Custom text templates require a demonstrated readability benefit. Domain
|
|
reports describe partial execution on failure without undoing durable work;
|
|
early failures need no empty report. Report models remain separate from
|
|
manifests and generated artifact formats, with documented public fields and no
|
|
additional schema version mechanism initially. Streaming JSON events remain
|
|
deferred. Diagnostics and invocation lifecycle are the next discussion topic.
|
|
|
|
### 2026-11-19 — Diagnostics and invocation lifecycle agreed
|
|
|
|
Accepted native diagnostic categories, visibility, and outcome classification,
|
|
with CommandKit owning console presentation separately from durable logs.
|
|
Startup acquires only the resources needed by the selected operation. Process
|
|
signals cancel the invocation context, preserving completed checkpoints and
|
|
allowing ordinary terminal persistence and lock release without triggering
|
|
pipeline cleanup. Accepted static and filesystem completion, with dynamic
|
|
campaign/artifact suggestions deferred. Delivery and migration guidance remain
|
|
open.
|
|
|
|
### 2026-11-19 — Delivery and migration agreed
|
|
|
|
Accepted one complete native cutover, the reviewed release baseline, explicit
|
|
public API fit checks, domain-behavior preservation, focused integration
|
|
verification, and workflow-oriented migration guidance. Release version
|
|
selection and publication remain separate from planning.
|
|
|
|
The user specified a single end-to-end implementation sprint. Intermediate
|
|
commits need not leave the overall application coherent or compilable; their
|
|
purpose is to support efficient progress toward the final state. Coherence,
|
|
compilation, and full validation are required at completion, without imposing
|
|
independently shippable or fully validated intermediate milestones. All
|
|
currently discussed decision areas are settled for roadmap consolidation.
|
|
|
|
### 2026-11-19 — Override scope simplified and party-file selection added
|
|
|
|
Revisited the need for field overrides outside application configuration.
|
|
Accepted native `--set` and `--against-set` only for `app`, retaining inspection
|
|
of all four scopes and using file selectors for alternate campaign, session,
|
|
and party inputs. Removed the proposed scope-specific override flag families
|
|
and their cross-domain composition requirements. Native aggregate inspection
|
|
rejects overrides when the selected scopes do not all support them.
|
|
|
|
Added `--party-file` and independent `--against-party-file` selection. The
|
|
campaign continues to supply the default roster; an explicit file supplies the
|
|
invocation's roster consistently across inspection, derivation, planning, and
|
|
execution.
|
|
|
|
No identified workflow requires non-app field overrides. Their convenience does
|
|
not justify the additional interface and integration machinery. The intent is
|
|
to meaningfully reduce complexity while retaining native app override behavior
|
|
and ordinary file-backed configuration composition. This revision supersedes
|
|
the earlier all-domain override and campaign-only party-selection decisions.
|
|
|
|
The later execution-override decision limits field overrides to native app
|
|
inspection until a reusable upstream binding is available.
|
|
|
|
### 2026-11-19 — Configuration ownership and native inspection clarified
|
|
|
|
Accepted ConfigKit's completed result as authoritative configuration, with
|
|
Narratio's schema, defaults, validation, and genuine resolution rules supplied
|
|
through ConfigKit's supported lifecycle. Narratio consumes the handoff without
|
|
mutation and produces separate domain catalogs, plans, and execution objects.
|
|
CommandKit's `ckconfig` integration neutrally exposes the native ConfigKit
|
|
features; Narratio does not reinterpret or improve their inspection semantics.
|
|
|
|
Superseded the requirement that app show/diff contain expanded artifacts and
|
|
generated publish rules. Standard inspection uses native results and adapters;
|
|
domain catalogs and planning commands expose the work derived from those
|
|
results. Remove post-load configuration mutation and separate inspection
|
|
snapshots rather than reconcile them with retained authoring evidence. Native
|
|
path and override semantics remain upstream contracts, not a Narratio design
|
|
problem.
|
|
|
|
The user identified the configuration/inspection split as a boundary violation.
|
|
The agreed correction is to restore ownership, not add machinery to make
|
|
different representations appear consistent. A potential ADR recording this
|
|
boundary is the next discussion topic.
|
|
|
|
### 2026-11-19 — Artifacts command family agreed
|
|
|
|
Accepted `artifacts list` for the configured domain catalog and
|
|
`artifacts regenerate SESSION` for forced extraction through analysis.
|
|
Bare `artifacts` displays help. Session-specific availability and
|
|
publication remain under `session artifacts SESSION`.
|
|
|
|
These commands replace `config artifacts` and top-level `regenerate-artifacts`
|
|
without aliases. Narratio owns the complete artifacts family, avoiding the
|
|
native configuration group's extension gap and keeping domain reports separate
|
|
from configuration inspection. The execution override binding remains the next
|
|
discussion topic.
|
|
|
|
### 2026-11-19 — Execution overrides deferred
|
|
|
|
Deferred field overrides on execution and planning commands until CommandKit
|
|
provides a reusable binding. Narratio will not build the proposed local binding
|
|
or other override machinery. Files and overlays provide execution settings;
|
|
native `ckconfig` overrides remain available for app inspection only.
|
|
|
|
Execution overrides are an optional operator convenience, not a core workflow
|
|
requirement or a migration dependency. This settles the remaining binding
|
|
decision and supersedes the earlier override-parity requirement.
|
|
|
|
### 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.
|