# 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.