From 8824ce330f6b09ba9ecc224a00ac1d1f4f8c96ef Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Fri, 20 Nov 2026 01:17:56 +0000 Subject: [PATCH] Defer execution overrides to a reusable CommandKit binding --- docs/roadmap/commandkit-notepad.md | 91 ++++++++++++++++++------------ 1 file changed, 54 insertions(+), 37 deletions(-) diff --git a/docs/roadmap/commandkit-notepad.md b/docs/roadmap/commandkit-notepad.md index fcc3f20..0651e81 100644 --- a/docs/roadmap/commandkit-notepad.md +++ b/docs/roadmap/commandkit-notepad.md @@ -1,6 +1,6 @@ # CommandKit migration notepad -Status: artifacts command family agreed; execution override binding under discussion. +Status: discussion decisions recorded; ready for roadmap consolidation. Started 2026-11-19. Narratio will become a CommandKit-native application. This notepad collects the @@ -261,24 +261,27 @@ 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 application configuration overrides +### Native inspection overrides; execution overrides deferred -Support invocation-local field overrides only for the `app` scope, with -equivalent application configuration selections available to app inspection, -planning, and execution. Campaign, session, and party scopes retain their -inspection capabilities; alternate inputs use `--campaign-file`, -`--session-file`, and `--party-file`. +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`. -CommandKit supplies the `POINTER=JSON` flag grammar; ConfigKit applies its native -override mechanism to application configuration. Do not introduce additional -protected-field lists, custom merge semantics, or a separate override acceptance -policy within that scope. +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 app inspection, planning, and execution | +| `--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 @@ -308,11 +311,10 @@ 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. -Overrides leave source configuration files unchanged. Normal run metadata and -prepared configuration may record the effective settings through established -secret-safe representations. Reuse decisions continue to depend on semantic -evidence: result-affecting changes can require regeneration, while the presence -of an override alone does not force execution. +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 @@ -321,15 +323,15 @@ 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. App overrides retain native acceptance -without a protected-field list. +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 overrides and use ConfigKit's -ordinary typed-secret handling and normal configuration validation. Safe +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. @@ -460,7 +462,7 @@ 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, file selection, and app overrides; +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 @@ -484,9 +486,9 @@ 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, overrides, reporting, and cancellation behavior are in -scope. Workspace reorganization, downstream-tool adoption, and Scriptorium -requirements inspection remain separate work. +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: @@ -495,13 +497,15 @@ Validate the integration through representative behavioral acceptance cases: 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 resolve equivalent application - configuration selections and overrides. +- 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. -- Override capability is limited to app; other scopes and aggregate inspection - retain native behavior when overrides are unsupported. +- 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. @@ -518,7 +522,7 @@ 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, app-only field overrides, native flag repetition and +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, @@ -560,11 +564,9 @@ baseline. They remain current-behavior documents until the migration lands. ## Open decisions -Decide how execution and planning commands bind app overrides. The reviewed -`ckconfig` release exposes no reusable complete `POINTER=JSON` parser or flag -binding. The proposal is a small shared binding that splits the assignment, -uses ConfigKit's path parser and CommandKit's JSON parser, and passes native -override records to ConfigKit. This proposal is not yet accepted. +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. @@ -574,7 +576,7 @@ 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 -follows the override-binding decision. +is the next planning step. ## Discussion and decision record @@ -633,7 +635,8 @@ adding an explicit party-file selector while retaining the campaign default. The cross-domain override decision below is superseded by the later override-scope revision. Inspection capabilities and native app override -semantics remain accepted. +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 @@ -703,6 +706,9 @@ 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 @@ -738,6 +744,17 @@ 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