Record artifacts command family and pending override binding

This commit is contained in:
2026-11-20 01:09:33 +00:00
parent 7cc877ea7f
commit 87142508e3

View File

@@ -1,6 +1,6 @@
# CommandKit migration notepad
Status: discussion decisions recorded; ready for roadmap consolidation.
Status: artifacts command family agreed; execution override binding under discussion.
Started 2026-11-19.
Narratio will become a CommandKit-native application. This notepad collects the
@@ -79,13 +79,15 @@ upstream contracts that Narratio exposes neutrally.
### Command organization
Use one general execution command, one regeneration convenience, and command
families for session operations and configuration:
Use one general execution command and command families for artifacts, session
operations, and configuration:
```text
narratio
├── run SESSION
├── regenerate-artifacts SESSION
├── artifacts
│ ├── list
│ └── regenerate SESSION
├── session
│ ├── init SESSION
│ ├── plan SESSION
@@ -104,8 +106,7 @@ narratio
│ ├── show
│ ├── sources
│ ├── explain
│ ├── diff
│ └── artifacts
│ └── diff
├── version
├── completion
└── help
@@ -126,14 +127,20 @@ Remove `run-stage`, `analyze`, and `publish`. Single-stage execution uses
`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.
Use `artifacts regenerate SESSION` for forced extraction through analysis
without publication, sharing execution logic with `run`. It regenerates the
complete configured extraction bundle. `--artifacts` selects analysis targets
and their required prerequisites, not extraction lanes.
`config artifacts` remains a Narratio-specific catalog alongside the standard
ckconfig operations, with the view defined below.
Use `artifacts list` for configured artifact definitions, producers, and
dependencies, including generated family members from the selected pipeline,
campaign, and party context. Bare `artifacts` displays native group help.
`session artifacts SESSION` retains session-specific availability and
publication reporting.
Narratio owns the `artifacts` family; `ckconfig` owns the standard `config`
family. Replace the proposed `config artifacts` and top-level
`regenerate-artifacts` spellings without compatibility aliases.
### Configuration scopes and views
@@ -160,7 +167,7 @@ to standard inspection, and differences between those products are not added
to native configuration comparisons. A separate raw-versus-resolved mode is
not part of the design.
Keep `config artifacts` as a Narratio-owned domain catalog of concrete artifact
Use `artifacts list` as a Narratio-owned domain catalog of concrete artifact
definitions and dependencies derived from the handed-off configuration and
selected party. Planning commands describe derived execution and publication
work. These domain views do not redefine ConfigKit's effective configuration.
@@ -336,7 +343,7 @@ native report shapes; Narratio defines report values for its domain operations.
| Command family | Report content |
| --- | --- |
| `run`, `regenerate-artifacts` | Campaign/session identity, selected stages, execution or reuse outcomes, generated artifacts, and completion status |
| `run`, `artifacts regenerate` | Campaign/session identity, selected stages, execution or reuse outcomes, generated artifacts, and completion status |
| `session plan` | Selected stages, planned execution/reuse decisions and reasons, artifact targets, and prerequisites |
| `session status` | Local stage state and available remote publication information |
| Artifact catalogs | Source identities, producers, dependencies, and session-specific availability/publication where applicable |
@@ -463,8 +470,8 @@ most efficient order and dependencies.
Use CommandKit v0.7.0 and ckconfig v0.9.0 as the initial roadmap baseline.
Review relevant public contract changes before deliberately selecting a later
release. Before finalizing implementation details, verify native ConfigKit
loader and `ckconfig` adapter integration and composition of Narratio-specific
commands alongside standard configuration commands. Address required upstream
loader and `ckconfig` adapter integration and composition of independently owned
domain and standard configuration command families. Address required upstream
capability gaps upstream rather than compensating with custom effective views,
provenance reconciliation, or replacement configuration behavior.
@@ -553,14 +560,21 @@ baseline. They remain current-behavior documents until the migration lands.
## Open decisions
No unresolved discussion decisions are currently recorded. Public API fit
checks and detailed implementation sequencing remain preparation work for the
roadmap and subsequent plan. Release version selection remains deferred to
release preparation.
Decide how execution and planning commands bind app overrides. The reviewed
`ckconfig` release exposes no reusable complete `POINTER=JSON` parser or flag
binding. The proposal is a small shared binding that splits the assignment,
uses ConfigKit's path parser and CommandKit's JSON parser, and passes native
override records to ConfigKit. This proposal is not yet accepted.
Consumer probes against the reviewed releases confirmed native inspection,
app-only override capabilities, independent comparisons, and lazy acquisition.
The inability to extend the generated `config` group is resolved by the
independent `artifacts` family. Detailed implementation sequencing remains
for the subsequent plan; release version selection remains deferred.
The configuration ownership boundary is recorded in
[ADR 0003](../adr/0003-assign-configuration-ownership.md). Roadmap consolidation
is the next planning step.
follows the override-binding decision.
## Discussion and decision record
@@ -586,6 +600,9 @@ 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.
The later artifacts-family decision supersedes the regeneration and catalog
command locations recorded here.
### 2026-11-19 — Configuration scopes and views agreed
The later configuration-ownership revision supersedes the expanded app
@@ -708,6 +725,19 @@ The agreed correction is to restore ownership, not add machinery to make
different representations appear consistent. A potential ADR recording this
boundary is the next discussion topic.
### 2026-11-19 — Artifacts command family agreed
Accepted `artifacts list` for the configured domain catalog and
`artifacts regenerate SESSION` for forced extraction through analysis.
Bare `artifacts` displays help. Session-specific availability and
publication remain under `session artifacts SESSION`.
These commands replace `config artifacts` and top-level `regenerate-artifacts`
without aliases. Narratio owns the complete artifacts family, avoiding the
native configuration group's extension gap and keeping domain reports separate
from configuration inspection. The execution override binding remains the next
discussion topic.
### Continuing the discussion
For each topic, record the question, the agreed outcome, its rationale, and any