diff --git a/docs/roadmap/commandkit-notepad.md b/docs/roadmap/commandkit-notepad.md index 1cdcea8..dd6e6a5 100644 --- a/docs/roadmap/commandkit-notepad.md +++ b/docs/roadmap/commandkit-notepad.md @@ -114,7 +114,7 @@ as the native default scope. | `app` | Pipeline configuration, including campaign-dependent artifact expansion and generated publish rules | | `campaign` | The selected campaign's settings | | `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 `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 | | `--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 @@ -178,17 +179,24 @@ 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 native overrides and resolution; mismatches -fail clearly. +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. -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`, -`--against-session`, and `--against-session-file` alongside CommandKit's native -right-side configuration selectors. Omitted right-side selectors use normal -defaults rather than inheriting left-side values. +`--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 @@ -206,32 +214,40 @@ inspection. Filtering findings changes presentation, not validation success. Expose available evidence for derived fields without manufacturing source 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 -override mechanism. Do not introduce additional protected-field lists, custom -merge semantics, or a separate override acceptance policy. +override mechanism to application configuration. Do not introduce additional +protected-field lists, custom merge semantics, or a separate override acceptance +policy within that scope. Use these flag spellings: | Flag | Target | | --- | --- | -| `--set POINTER=JSON` | Selected inspection scope; `app` on execution commands | -| `--set-app POINTER=JSON` | App/pipeline configuration explicitly | -| `--set-campaign POINTER=JSON` | Campaign configuration explicitly | -| `--set-session POINTER=JSON` | Session configuration explicitly | -| `--set-party POINTER=JSON` | Party configuration explicitly | +| `--set POINTER=JSON` | App/pipeline configuration on app inspection, planning, and execution | +| `--against-set POINTER=JSON` | Right-side app/pipeline configuration on app comparisons | -Explicitly targeted flags also support overriding a configuration on which the -selected inspection view depends, such as inspecting expanded pipeline -artifacts with a party override. Comparisons use native `--against-set` and -the corresponding `--against-set-app`, `--against-set-campaign`, -`--against-set-session`, and `--against-set-party` flags for the right side. -Retain native aggregate-scope behavior rather than inventing scope prefixes +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. + Apply overrides after typed defaults and decoding, before application resolution and semantic validation. Preserve native explicit empty, false, 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 replace ConfigKit's conflict rules for override records. -Override paths address the configuration accepted by the loader. They do not -provide an independent patch mechanism over the final expanded artifact +Override paths address application configuration accepted by its loader. They +do not provide an independent patch mechanism over the final expanded artifact catalog. Ordinary Narratio derivation and validation determine the effective result, regardless of whether values came from files, inheritance, overlays, or CLI overrides. @@ -253,21 +269,23 @@ of an override alone does not force execution. ### Identity assertions and credential overrides -Identity fields are not immutable or excluded from overrides. ConfigKit applies -their overrides normally. Narratio then checks the effective identity against -any explicitly asserted campaign/session identity so an operation targeting one +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 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 -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. -Credential-related fields accept native 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 fields may be overridden. +Credential-related app fields accept native 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 @@ -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 work boundaries are core invocation/domain commands; configuration -scopes, inspection, and overrides; 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. +scopes, file selection, inspection, and app overrides; 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 public API support -for effective views with truthful provenance, overrides across supporting -configuration domains, and Narratio-specific commands alongside standard -configuration commands. Address shared-capability gaps upstream where -appropriate rather than silently recreating CommandKit behavior locally. +for effective views with truthful provenance and Narratio-specific commands +alongside standard configuration commands. Address shared-capability gaps +upstream where appropriate rather than silently recreating CommandKit behavior +locally. Retain Narratio's stage sequencing, resume authority, publication semantics, 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: - Native arguments and selectors reach the intended Narratio operation. -- Inspection, planning, and execution resolve equivalent configuration - selections and overrides. +- App inspection, planning, and execution resolve equivalent application + 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 results. - 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. Provide workflow-oriented release migration guidance: an old-to-new command -table plus explanations of removed shortcuts, identity/file selectors, native -flag repetition and placement, configuration scopes and comparisons, structured -output, diagnostic visibility, exit classifications, and cancellation. Identify -affected examples, operator procedures, scripts, and downstream callers. +table plus explanations of removed shortcuts, identity/file selectors including +party-file selection, app-only field overrides, native flag repetition and +placement, configuration scopes and 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. @@ -523,8 +548,15 @@ 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. + 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`, @@ -573,6 +605,26 @@ 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. + ### Continuing the discussion For each topic, record the question, the agreed outcome, its rationale, and any