Simplify CommandKit overrides and add party file selection
This commit is contained in:
@@ -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
|
||||||
|
|||||||
Reference in New Issue
Block a user