Simplify CommandKit overrides and add party file selection

This commit is contained in:
2026-11-19 18:53:26 +00:00
parent 86ec48d2e4
commit 084e6d178b

View File

@@ -114,7 +114,7 @@ as the native default scope.
| `app` | Pipeline configuration, including campaign-dependent artifact expansion and generated publish rules | | `app` | Pipeline configuration, including campaign-dependent artifact expansion and generated publish rules |
| `campaign` | The selected campaign's settings | | `campaign` | The selected campaign's settings |
| `session` | The selected session's settings, including applicable campaign defaults | | `session` | The selected session's settings, including applicable campaign defaults |
| `party` | The selected campaign's canonical party roster | | `party` | The canonical party roster selected by `--party-file` or the campaign default |
Use effective values for `show` and `diff`, native provenance for `sources` and Use effective values for `show` and `diff`, native provenance for `sources` and
`explain`, and domain validation for `validate`. Inspection reflects imports, `explain`, and domain validation for `validate`. Inspection reflects imports,
@@ -170,6 +170,7 @@ Forced-local or forced-remote selection is not part of the initial design.
| `--campaign-file PATH` | Explicit campaign configuration file | | `--campaign-file PATH` | Explicit campaign configuration file |
| `--session ID` | Session identity on configuration inspection commands | | `--session ID` | Session identity on configuration inspection commands |
| `--session-file PATH` | Explicit session configuration file | | `--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 | | `--secrets-dir PATH` | Credential-bootstrap directory selection |
Changing scope does not change the meaning of `--config`. Session-oriented Changing scope does not change the meaning of `--config`. Session-oriented
@@ -178,17 +179,24 @@ explicit source using `--session-file`.
Identity and file selectors are complementary: the file selects the source and Identity and file selectors are complementary: the file selects the source and
an accompanying ID asserts the intended identity. Check that assertion against an accompanying ID asserts the intended identity. Check that assertion against
the effective configuration after native overrides and resolution; mismatches the effective configuration after loading and resolution; mismatches fail
fail clearly. clearly.
For inspection, the file can supply identity when no identity selector is For inspection, the file can supply identity when no identity selector is
given; session-oriented commands retain their required positional identity. given; session-oriented commands retain their required positional identity.
Select the party through its campaign; an independent `--party-file` selector
is not part of this migration. 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`, Comparisons expose `--against-campaign`, `--against-campaign-file`,
`--against-session`, and `--against-session-file` alongside CommandKit's native `--against-session`, `--against-session-file`, and `--against-party-file`
right-side configuration selectors. Omitted right-side selectors use normal alongside CommandKit's native right-side configuration selectors. Omitted
defaults rather than inheriting left-side values. right-side selectors use normal defaults rather than inheriting left-side
values, including each side's campaign-default party file.
### Configuration inspection capabilities ### Configuration inspection capabilities
@@ -206,32 +214,40 @@ inspection. Filtering findings changes presentation, not validation success.
Expose available evidence for derived fields without manufacturing source Expose available evidence for derived fields without manufacturing source
history. history.
### Native configuration overrides ### Native application configuration overrides
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`.
Support invocation-local overrides for all four domains, with equivalent
configuration selections available to inspection, planning, and execution.
CommandKit supplies the `POINTER=JSON` flag grammar; ConfigKit applies its native CommandKit supplies the `POINTER=JSON` flag grammar; ConfigKit applies its native
override mechanism. Do not introduce additional protected-field lists, custom override mechanism to application configuration. Do not introduce additional
merge semantics, or a separate override acceptance policy. protected-field lists, custom merge semantics, or a separate override acceptance
policy within that scope.
Use these flag spellings: Use these flag spellings:
| Flag | Target | | Flag | Target |
| --- | --- | | --- | --- |
| `--set POINTER=JSON` | Selected inspection scope; `app` on execution commands | | `--set POINTER=JSON` | App/pipeline configuration on app inspection, planning, and execution |
| `--set-app POINTER=JSON` | App/pipeline configuration explicitly | | `--against-set POINTER=JSON` | Right-side app/pipeline configuration on app comparisons |
| `--set-campaign POINTER=JSON` | Campaign configuration explicitly |
| `--set-session POINTER=JSON` | Session configuration explicitly |
| `--set-party POINTER=JSON` | Party configuration explicitly |
Explicitly targeted flags also support overriding a configuration on which the Declare native override support only for `app`. Other inspection scopes do not
selected inspection view depends, such as inspecting expanded pipeline accept `--set`; native `--scope all` also rejects overrides because not every
artifacts with a party override. Comparisons use native `--against-set` and selected scope supports them. Aggregate inspection without overrides remains
the corresponding `--against-set-app`, `--against-set-campaign`, available as supported by each operation. Do not add scope-specific `--set-*`
`--against-set-session`, and `--against-set-party` flags for the right side. or `--against-set-*` aliases, cross-scope override dispatch, or scope prefixes
Retain native aggregate-scope behavior rather than inventing scope prefixes
inside JSON Pointers. 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.
Apply overrides after typed defaults and decoding, before application Apply overrides after typed defaults and decoding, before application
resolution and semantic validation. Preserve native explicit empty, false, resolution and semantic validation. Preserve native explicit empty, false,
zero, and null values, mapping merge and whole-sequence replacement, and zero, and null values, mapping merge and whole-sequence replacement, and
@@ -239,8 +255,8 @@ duplicate/overlapping-path rejection. Earlier parsing and decoding failures
remain errors. CommandKit's last-value convention for singleton flags does not remain errors. CommandKit's last-value convention for singleton flags does not
replace ConfigKit's conflict rules for override records. replace ConfigKit's conflict rules for override records.
Override paths address the configuration accepted by the loader. They do not Override paths address application configuration accepted by its loader. They
provide an independent patch mechanism over the final expanded artifact do not provide an independent patch mechanism over the final expanded artifact
catalog. Ordinary Narratio derivation and validation determine the effective catalog. Ordinary Narratio derivation and validation determine the effective
result, regardless of whether values came from files, inheritance, overlays, result, regardless of whether values came from files, inheritance, overlays,
or CLI overrides. or CLI overrides.
@@ -253,21 +269,23 @@ of an override alone does not force execution.
### Identity assertions and credential overrides ### Identity assertions and credential overrides
Identity fields are not immutable or excluded from overrides. ConfigKit applies Narratio checks the effective campaign/session identity against any explicitly
their overrides normally. Narratio then checks the effective identity against asserted identity after loading and resolution so an operation targeting one
any explicitly asserted campaign/session identity so an operation targeting one
session cannot silently use another session's workspace, lock, manifest, or session cannot silently use another session's workspace, lock, manifest, or
remote destination. This is an ordinary domain consistency check, independent remote destination. This is an ordinary domain consistency check, independent
of how the value was supplied. 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.
When no identity is asserted, such as inspection of an explicit session file When no identity is asserted, such as inspection of an explicit session file
without `--session`, the effective document can supply its overridden identity. without `--session`, the effective document supplies its identity.
Session-oriented commands retain their required positional assertion. Session-oriented commands retain their required positional assertion.
Credential-related fields accept native overrides and use ConfigKit's ordinary Credential-related app fields accept native overrides and use ConfigKit's
typed-secret handling and normal configuration validation. Safe inspection, ordinary typed-secret handling and normal configuration validation. Safe
diagnostics, and persistence remain separate output responsibilities; they do inspection, diagnostics, and persistence remain separate output
not justify additional restrictions on which fields may be overridden. responsibilities; they do not justify additional restrictions on which app
fields may be overridden.
### Reports and machine-readable output ### Reports and machine-readable output
@@ -394,19 +412,20 @@ commit working. Report intermediate status accurately, use focused checks when
useful, and require a coherent, compilable, fully validated final application. useful, and require a coherent, compilable, fully validated final application.
Useful work boundaries are core invocation/domain commands; configuration Useful work boundaries are core invocation/domain commands; configuration
scopes, inspection, and overrides; reports, diagnostics, cancellation, and scopes, file selection, inspection, and app overrides; reports, diagnostics,
completion; and integration verification, removal of superseded CLI machinery, cancellation, and completion; and integration verification, removal of
and documentation. These are organizational boundaries, not mandatory buildable superseded CLI machinery, and documentation. These are organizational
milestones or a supported dual interface. The subsequent implementation plan boundaries, not mandatory buildable milestones or a supported dual interface.
determines the most efficient order and dependencies. 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. 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 Review relevant public contract changes before deliberately selecting a later
release. Before finalizing implementation details, verify public API support release. Before finalizing implementation details, verify public API support
for effective views with truthful provenance, overrides across supporting for effective views with truthful provenance and Narratio-specific commands
configuration domains, and Narratio-specific commands alongside standard alongside standard configuration commands. Address shared-capability gaps
configuration commands. Address shared-capability gaps upstream where upstream where appropriate rather than silently recreating CommandKit behavior
appropriate rather than silently recreating CommandKit behavior locally. locally.
Retain Narratio's stage sequencing, resume authority, publication semantics, Retain Narratio's stage sequencing, resume authority, publication semantics,
restore safety, and cleanup rules. Changes required for the agreed overrides, restore safety, and cleanup rules. Changes required for the agreed overrides,
@@ -417,8 +436,13 @@ separate work.
Validate the integration through representative behavioral acceptance cases: Validate the integration through representative behavioral acceptance cases:
- Native arguments and selectors reach the intended Narratio operation. - Native arguments and selectors reach the intended Narratio operation.
- Inspection, planning, and execution resolve equivalent configuration - App inspection, planning, and execution resolve equivalent application
selections and overrides. configuration selections and overrides.
- 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.
- Reports remain separate from diagnostics and preserve meaningful partial - Reports remain separate from diagnostics and preserve meaningful partial
results. results.
- Help and completion avoid configuration and service acquisition. - Help and completion avoid configuration and service acquisition.
@@ -434,10 +458,11 @@ generic parser or configuration tests. Dependency attribution is part of the
adoption work. adoption work.
Provide workflow-oriented release migration guidance: an old-to-new command Provide workflow-oriented release migration guidance: an old-to-new command
table plus explanations of removed shortcuts, identity/file selectors, native table plus explanations of removed shortcuts, identity/file selectors including
flag repetition and placement, configuration scopes and comparisons, structured party-file selection, app-only field overrides, native flag repetition and
output, diagnostic visibility, exit classifications, and cancellation. Identify placement, configuration scopes and comparisons, structured output, diagnostic
affected examples, operator procedures, scripts, and downstream callers. visibility, exit classifications, and cancellation. Identify affected examples,
operator procedures, scripts, and downstream callers.
Update canonical documentation and maintained examples as implementation lands; Update canonical documentation and maintained examples as implementation lands;
release notes summarize and link to those contracts rather than duplicate the release notes summarize and link to those contracts rather than duplicate the
command reference. command reference.
@@ -523,8 +548,15 @@ both are supplied, campaign-owned party selection, and independent right-side
comparison selectors. Optional configuration capabilities and overrides are comparison selectors. Optional configuration capabilities and overrides are
the next discussion topic. 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 ### 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.
Accepted full applicable inspection capabilities and native overrides across Accepted full applicable inspection capabilities and native overrides across
all four configuration domains, with parity across inspection, planning, and all four configuration domains, with parity across inspection, planning, and
execution. Selected verb-first `--set-app`, `--set-campaign`, `--set-session`, execution. Selected verb-first `--set-app`, `--set-campaign`, `--set-session`,
@@ -573,6 +605,26 @@ compilation, and full validation are required at completion, without imposing
independently shippable or fully validated intermediate milestones. All independently shippable or fully validated intermediate milestones. All
currently discussed decision areas are settled for roadmap consolidation. 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.
### Continuing the discussion ### Continuing the discussion
For each topic, record the question, the agreed outcome, its rationale, and any For each topic, record the question, the agreed outcome, its rationale, and any