Record agreed CommandKit command organization

This commit is contained in:
2026-11-19 16:01:02 +00:00
parent 8ba001750e
commit b4b618a913

View File

@@ -45,6 +45,65 @@ inspection and early pipeline dependency checks remain separate feature work
using an eventual Scriptorium external contract. CommandKit adoption can using an eventual Scriptorium external contract. CommandKit adoption can
proceed independently. 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 ## Reviewed upstream baseline
The initial review covered these released modules: The initial review covered these released modules:
@@ -72,19 +131,7 @@ baseline. They remain current-behavior documents until the migration lands.
## Open decisions ## Open decisions
### 1. Domain command organization ### Configuration scopes and views
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
Which named scopes should be available initially: one effective pipeline scope, Which named scopes should be available initially: one effective pipeline scope,
or also campaign, session, and party scopes? Define the selectors and acquisition 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 campaign and party context participate in comparisons, including independent
left and right selectors. left and right selectors.
### 3. Optional configuration capabilities ### Optional configuration capabilities
Determine the useful scope of path-selected show, path explanation, detailed Determine the useful scope of path-selected show, path explanation, detailed
validation findings, comparison details/check mode, and temporary `--set` 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 contract. Avoid an inspection result that purports to describe execution while
silently using different resolution rules. 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, Design useful report values for planning, status, artifact inventories,
validation, restore, cleanup, and execution summaries. Apply native text, YAML, 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 promise for application-owned report fields; do not accidentally make durable
manifest schemas the CLI response contract. manifest schemas the CLI response contract.
### 5. Diagnostics and invocation lifecycle ### Diagnostics and invocation lifecycle
Classify existing messages into CommandKit's result, failure, warning, Classify existing messages into CommandKit's result, failure, warning,
information, progress, and debug categories. Use native visibility rules, 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 filesystem paths. Decide which declarations receive those hints; dynamic
campaign/artifact discovery would need a separately supported capability. 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. Choose implementation work units that lead to one complete native cutover.
Intermediate development steps need not become a supported dual CLI. 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 non-goal. This settles the earlier question of whether to preserve legacy CLI
conventions. 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 ### 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