diff --git a/docs/roadmap/commandkit-notepad.md b/docs/roadmap/commandkit-notepad.md index 2dc6614..b580c84 100644 --- a/docs/roadmap/commandkit-notepad.md +++ b/docs/roadmap/commandkit-notepad.md @@ -87,7 +87,7 @@ same execution-selection options, including stage/range, force, and artifacts. Use positional session IDs on session-oriented commands and remove their duplicate `--session-id` spelling. Campaign and configuration selection remain -flags. Configuration inspection selectors will be settled with scope design. +flags. Configuration inspection selector spelling remains to be settled. Remove `run-stage`, `analyze`, and `publish`. Single-stage execution uses `run --stage`; forced regeneration adds `--force` explicitly. Move top-level @@ -101,8 +101,50 @@ publication. It regenerates the complete configured extraction bundle; extraction lanes. The command name makes regeneration explicit. `config artifacts` remains a Narratio-specific catalog alongside the standard -ckconfig operations. Its final placement and view will be confirmed with the -configuration scope discussion. +ckconfig operations, with the view defined below. + +### Configuration scopes and views + +Expose four scopes corresponding to Narratio's configuration domains. Use `app` +as the native default scope. + +| Scope | Effective configuration | +| --- | --- | +| `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 | + +Use effective values for `show` and `diff`, native provenance for `sources` and +`explain`, and domain validation for `validate`. Inspection reflects imports, +overlays, inheritance, defaults, and applicable Narratio resolution. A separate +raw-versus-resolved mode is not part of the initial design. + +`app` show/diff includes the concrete artifacts and publish rules execution +receives. Provenance must distinguish authored and derived values accurately; +a generated artifact must not appear to have been literally declared in a +source file. Use native evidence without inventing source origins. + +Keep `config artifacts` as a focused catalog of definitions and dependencies +derived from the same effective pipeline. `session artifacts SESSION` reports +session-specific availability and publication state. Future input discovery can +extend the configuration catalog separately from this migration. + +Acquire only the context needed for the selected scope. Party-driven pipeline +expansion requires the selected campaign and party; effective session settings +require the session and applicable campaign context. Campaign inspection does +not require a session. Scope discovery and help do not load configuration. +Report missing required context explicitly rather than presenting a partially +resolved view as complete. + +Retain CommandKit's operation-specific `--scope all` behavior. Do not silently +omit a selected scope whose required context is missing. + +Comparisons use independently resolved left and right selections through native +selectors and their `--against-*` counterparts. Permit comparisons across +overlays, configuration files, and campaigns; the existing same-campaign +restriction is not retained. Session acquisition policy and exact application +selector spellings remain open below. ## Reviewed upstream baseline @@ -131,23 +173,16 @@ baseline. They remain current-behavior documents until the migration lands. ## Open decisions -### Configuration scopes and views +### Session acquisition and selector spelling -Which named scopes should be available initially: one effective pipeline scope, -or also campaign, session, and party scopes? Define the selectors and acquisition -needed for each, including which inspections should work without a session or -remote access. +Decide whether configuration inspection uses normal remote session discovery +when no local source exists, or requires an explicit remote selection. Define +the read-only boundary, including network reads and any local materialization. -Narratio distinguishes the authored configuration from the resolved domain -view containing concrete artifact families and generated publish rules. Settle -what each standard inspection operation exposes, keeping safe effective values -and truthful native provenance available without confusing their meanings. - -The initial proposal is to use the resolved, credential-safe domain view for -show and diff, native evidence for source/explanation operations, and an -application-specific artifact catalog. Decide the catalog's placement and how -campaign and party context participate in comparisons, including independent -left and right selectors. +Choose consistent flags for campaign/session identities versus explicit files +and their right-side comparison equivalents. Session-oriented commands retain +their agreed positional IDs; standard configuration commands use selectors +suited to the native ckconfig command structure. ### Optional configuration capabilities @@ -232,6 +267,16 @@ forced analysis/publication commands from the target CLI. Retained `regenerate-artifacts` because it expresses a useful multi-stage regeneration workflow. Configuration scopes and views are the next discussion topic. +### 2026-11-19 — Configuration scopes and views agreed + +Accepted `app`, `campaign`, `session`, and `party` scopes, with `app` as default. +Show/diff exposes effective values and source/explanation operations use native +provenance. Concrete artifacts remain visible in the effective pipeline and the +separate configuration catalog; session artifact inspection owns availability. +Accepted context-dependent acquisition, explicit missing-context errors, native +aggregate-scope behavior, and independently resolved comparisons across +campaigns. Session acquisition policy and selector spelling are next. + ### Continuing the discussion For each topic, record the question, the agreed outcome, its rationale, and any