From 87142508e3c6705ee40136c139f49a6b51f03ab1 Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Fri, 20 Nov 2026 01:09:33 +0000 Subject: [PATCH] Record artifacts command family and pending override binding --- docs/roadmap/commandkit-notepad.md | 74 +++++++++++++++++++++--------- 1 file changed, 52 insertions(+), 22 deletions(-) diff --git a/docs/roadmap/commandkit-notepad.md b/docs/roadmap/commandkit-notepad.md index 69f631b..fcc3f20 100644 --- a/docs/roadmap/commandkit-notepad.md +++ b/docs/roadmap/commandkit-notepad.md @@ -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