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
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