From b4b618a9131fc30ff2024982a386a58b7e94e6ba Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Thu, 19 Nov 2026 16:01:02 +0000 Subject: [PATCH] Record agreed CommandKit command organization --- docs/roadmap/commandkit-notepad.md | 90 ++++++++++++++++++++++++------ 1 file changed, 73 insertions(+), 17 deletions(-) diff --git a/docs/roadmap/commandkit-notepad.md b/docs/roadmap/commandkit-notepad.md index d6dd1da..2dc6614 100644 --- a/docs/roadmap/commandkit-notepad.md +++ b/docs/roadmap/commandkit-notepad.md @@ -45,6 +45,65 @@ inspection and early pipeline dependency checks remain separate feature work using an eventual Scriptorium external contract. CommandKit adoption can proceed independently. +### Command organization + +Use one general execution command, one regeneration convenience, and command +families for session operations and configuration: + +```text +narratio +├── run SESSION +├── regenerate-artifacts SESSION +├── session +│ ├── init SESSION +│ ├── plan SESSION +│ ├── validate SESSION +│ ├── status SESSION +│ ├── restore SESSION +│ ├── clean [SESSION | --all] +│ ├── artifacts SESSION +│ └── locks +│ ├── list SESSION +│ ├── add SESSION SOURCE +│ └── remove SESSION SOURCE +├── config +│ ├── scopes +│ ├── validate +│ ├── show +│ ├── sources +│ ├── explain +│ ├── diff +│ └── artifacts +├── version +├── completion +└── help +``` + +`run SESSION` selects the full pipeline by default. `--from` and `--through` +select an inclusive contiguous range. Add `--stage` for one stage, mutually +exclusive with the range selectors; it selects the same stage as both endpoints. +`--force` independently requests forced execution. `session plan` accepts the +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. + +Remove `run-stage`, `analyze`, and `publish`. Single-stage execution uses +`run --stage`; forced regeneration adds `--force` explicitly. Move top-level +`clean` to `session clean`. Use the explicit `session locks list` operation so +the bare locks group displays native help. + +Keep `regenerate-artifacts` as an application-owned command sharing execution +logic. Its useful domain intent is forced extraction through analysis without +publication. It regenerates the complete configured extraction bundle; +`--artifacts` selects analysis targets and their required prerequisites, not +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. + ## Reviewed upstream baseline The initial review covered these released modules: @@ -72,19 +131,7 @@ baseline. They remain current-behavior documents until the migration lands. ## Open decisions -### 1. Domain command organization - -Which commands and conveniences should the native CLI expose? Review `run`, -`run-stage`, `analyze`, `publish`, `regenerate-artifacts`, `clean`, and the -`session` family for operator usefulness. Decide how session IDs, stage bounds, -and artifact selections should be expressed using native typed inputs. - -CommandKit aliases redirect command paths; they do not inject flags or -operands. Retained conveniences that select a stage or force a range therefore -need application-owned commands sharing domain execution logic. Decide which -are worth keeping on that basis, without a compatibility requirement. - -### 2. Configuration scopes and views +### Configuration scopes and views Which named scopes should be available initially: one effective pipeline scope, or also campaign, session, and party scopes? Define the selectors and acquisition @@ -102,7 +149,7 @@ application-specific artifact catalog. Decide the catalog's placement and how campaign and party context participate in comparisons, including independent left and right selectors. -### 3. Optional configuration capabilities +### Optional configuration capabilities Determine the useful scope of path-selected show, path explanation, detailed validation findings, comparison details/check mode, and temporary `--set` @@ -115,7 +162,7 @@ ability to parse an override does not establish Narratio's intended loading contract. Avoid an inspection result that purports to describe execution while silently using different resolution rules. -### 4. Reports and machine-readable output +### Reports and machine-readable output Design useful report values for planning, status, artifact inventories, validation, restore, cleanup, and execution summaries. Apply native text, YAML, @@ -128,7 +175,7 @@ results from diagnostic/progress messages. Decide what stability Narratio will promise for application-owned report fields; do not accidentally make durable manifest schemas the CLI response contract. -### 5. Diagnostics and invocation lifecycle +### Diagnostics and invocation lifecycle Classify existing messages into CommandKit's result, failure, warning, information, progress, and debug categories. Use native visibility rules, @@ -146,7 +193,7 @@ Completion can suggest commands, static values such as stage names, and filesystem paths. Decide which declarations receive those hints; dynamic campaign/artifact discovery would need a separately supported capability. -### 6. Delivery and migration guidance +### Delivery and migration guidance Choose implementation work units that lead to one complete native cutover. Intermediate development steps need not become a supported dual CLI. @@ -176,6 +223,15 @@ provide release migration guidance, and treat existing CLI compatibility as a non-goal. This settles the earlier question of whether to preserve legacy CLI conventions. +### 2026-11-19 — Command organization agreed + +Accepted the proposed command tree, `run --stage` selector, positional session +IDs, shared selection syntax for planning, explicit lock listing, and movement +of cleanup under `session`. Removed the separate single-stage and implicitly +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. + ### Continuing the discussion For each topic, record the question, the agreed outcome, its rationale, and any