Defer execution overrides to a reusable CommandKit binding

This commit is contained in:
2026-11-20 01:17:56 +00:00
parent 87142508e3
commit 8824ce330f

View File

@@ -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