From 6b027873a518df884ce41d35ec1699b705002c37 Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Thu, 19 Nov 2026 16:15:25 +0000 Subject: [PATCH] Record session acquisition and selector decisions --- docs/roadmap/commandkit-notepad.md | 67 +++++++++++++++++++++++------- 1 file changed, 53 insertions(+), 14 deletions(-) diff --git a/docs/roadmap/commandkit-notepad.md b/docs/roadmap/commandkit-notepad.md index b580c84..8ba1ece 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 selector spelling remains to be settled. +flags, with spelling defined below. Remove `run-stage`, `analyze`, and `publish`. Single-stage execution uses `run --stage`; forced regeneration adds `--force` explicitly. Move top-level @@ -143,8 +143,49 @@ 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. +restriction is not retained. + +### Session acquisition and selectors + +Inspection and execution use the same session-selection rules. Load an explicit +session file exactly when supplied; otherwise use normal local discovery, then +configured remote discovery when no local session exists and its identity is +known. Missing or invalid explicit files are errors. Invalid content, access +failures, and identity mismatches do not trigger fallback to another source. + +Remote discovery prefers the authored session-root configuration and falls back +to the committed prepared snapshot only when the authored object is absent. +Configuration inspection permits these network reads without requiring a +separate remote opt-in. It creates no local runtime state: no workspace +initialization, restored files, execution locks, or manifest changes. Source +inspection identifies local, remote-authored, and committed-snapshot origins. +Forced-local or forced-remote selection is not part of the initial design. + +| Selector | Meaning | +| --- | --- | +| `--config PATH` | Pipeline configuration root for every scope | +| `--overlay NAME` | Pipeline overlay | +| `--campaign ID` | Campaign identity | +| `--campaign-file PATH` | Explicit campaign configuration file | +| `--session ID` | Session identity on configuration inspection commands | +| `--session-file PATH` | Explicit session configuration file | +| `--secrets-dir PATH` | Credential-bootstrap directory selection | + +Changing scope does not change the meaning of `--config`. Session-oriented +commands retain their positional session identity and can also select an +explicit source using `--session-file`. + +Identity and file selectors are complementary: the file selects the source and +an accompanying ID asserts the intended identity. 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. + +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. ## Reviewed upstream baseline @@ -173,17 +214,6 @@ baseline. They remain current-behavior documents until the migration lands. ## Open decisions -### Session acquisition and selector spelling - -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. - -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 Determine the useful scope of path-selected show, path explanation, detailed @@ -277,6 +307,15 @@ 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. +### 2026-11-19 — Session acquisition and selectors agreed + +Accepted shared inspection/execution discovery with automatic remote fallback, +read-only acquisition without local runtime state, and explicit source +provenance. Accepted distinct identity/file selectors, identity assertions when +both are supplied, campaign-owned party selection, and independent right-side +comparison selectors. Optional configuration capabilities and overrides are +the next discussion topic. + ### Continuing the discussion For each topic, record the question, the agreed outcome, its rationale, and any