@oscaner-skills/cdd-engine 4.12.0 → 4.13.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/face/cli.js CHANGED
@@ -68,6 +68,7 @@ import { HoldingError, InFlight } from "../session/inflight.js";
68
68
  import { Ledger } from "../session/ledger.js";
69
69
  import { NextStepRouter } from "../session/next.js";
70
70
  import { PreFlight } from "../session/preflight.js";
71
+ import { ArtifactRegistry } from "../session/round-artifacts.js";
71
72
  import { EMPTY_RUN_STATE, Lifecycle } from "../session/run.js";
72
73
  import { CliArtifacts } from "./artifacts.js";
73
74
  import { BoardNext, BoardView } from "./board-view.js";
@@ -137,6 +138,19 @@ export class Cli {
137
138
  /** The pure-command domain (T8 — the split contract's artifacts face,
138
139
  * face/artifacts.ts): the schema/issue/base run bodies. */
139
140
  #artifacts;
141
+ /** The artifact matrix of this invocation — constructed ONCE per command and handed
142
+ * down to the scene's ledger / router / lifecycle, the board's node ledgers and the
143
+ * seal sweep. It binds no workspace (the matrix is naming knowledge; the workspace is
144
+ * the read-time coordinate), so ONE instance serves every node a command observes.
145
+ * The doc domain answers through the command's identity index, which is bound ONTO
146
+ * this instance at `#indexOf` — the same object, never a second registry. */
147
+ #matrix;
148
+ /** The command's ONE identity index — built once per repo root at `#indexOf`, so no
149
+ * two read faces of a command scan the doc roots twice. */
150
+ #index = null;
151
+ /** The repo root `#index` was built over — the memo's key (a Cli may serve several
152
+ * commands, and a fixture several repos). */
153
+ #indexRoot = null;
140
154
  /** The harness plugin bootstrap (P20 — face/init.ts): the repo-independent
141
155
  * install/update sequence face. */
142
156
  #init;
@@ -175,11 +189,16 @@ export class Cli {
175
189
  });
176
190
  this.#authority = opts.authority ?? new DispatchAuthority();
177
191
  this.#gate = new CliGate({ brief: this.#brief, authority: this.#authority });
192
+ // The invocation's ONE matrix — the command preamble's construction point. The
193
+ // declared domain is bound onto this same instance at `#indexOf` (an injected one
194
+ // included), so no face ever holds a registry the doc reads do not answer through.
195
+ this.#matrix = opts.artifacts ?? new ArtifactRegistry();
178
196
  this.#artifacts = new CliArtifacts({
179
197
  io: this.#io,
180
198
  projector: this.#projector,
181
199
  issue: this.#issue,
182
200
  stdinRead: this.#stdinRead,
201
+ matrix: this.#matrix,
183
202
  usage: (node, message) => this.#usage(node, message),
184
203
  });
185
204
  // The synchronous writer — the step header must land before the spawned
@@ -210,6 +229,12 @@ export class Cli {
210
229
  async runArgv(raw) {
211
230
  try {
212
231
  this.#exitCode = 0;
232
+ // One COMMAND, one index: the memo below serves a single invocation (its two
233
+ // call points — the command preamble and the scene — must read one snapshot),
234
+ // and the next invocation re-scans. A memo carried across commands would answer
235
+ // from a snapshot taken before the documents this command writes or observes.
236
+ this.#index = null;
237
+ this.#indexRoot = null;
213
238
  await this.#program.parseAsync([...raw], { from: "user" });
214
239
  return this.#exitCode;
215
240
  }
@@ -327,6 +352,21 @@ export class Cli {
327
352
  this.#exitCode = await this.#init.run(request);
328
353
  });
329
354
  }
355
+ /** The command's ONE identity index — the doc-domain binding point. `board` · the
356
+ * scene assembly · `base` each call this once, and a second call inside one command
357
+ * reuses the memo (a command never scans the doc roots twice). The matrix's declared
358
+ * domain is bound onto the SAME registry instance here — the base face, the ledgers,
359
+ * the lifecycle and the board all keep holding it, so a doc read can not fall on a
360
+ * table that never learned the index. */
361
+ #indexOf(repoRoot) {
362
+ if (this.#index !== null && this.#indexRoot === repoRoot)
363
+ return this.#index;
364
+ const index = SlugIndex.build(repoRoot);
365
+ this.#index = index;
366
+ this.#indexRoot = repoRoot;
367
+ this.#matrix.bindDocIndex(index);
368
+ return index;
369
+ }
330
370
  /** `cdd board --plan <path> / --spec <path>` — the entry document's progress board
331
371
  * (spec §3.1): a PURE READ — zero preflight gate, zero tree writes, zero ledger
332
372
  * writes, zero child dispatch. At least one path flag is required (missing →
@@ -347,10 +387,6 @@ export class Cli {
347
387
  if (repoRoot === null)
348
388
  return 1;
349
389
  const root = new RepoRoot(repoRoot);
350
- // The board's plan read seam — ONE instance per command, threaded down the
351
- // static render chain (the board's ledgers read their brief revisions through
352
- // it; a node workspace never mints its own).
353
- const planSource = new PlanSource(root);
354
390
  const planRel = planArg === undefined ? null : this.#relativizePath(root, planArg);
355
391
  const specRel = specArg === undefined ? null : this.#relativizePath(root, specArg);
356
392
  // The not-found face reads ZERO documents (spec §3.1): a path outside the two
@@ -365,6 +401,15 @@ export class Cli {
365
401
  planMissing ? `--plan ${planArg}` : null,
366
402
  specMissing ? `--spec ${specArg}` : null,
367
403
  ]);
404
+ // The command's ONE identity index — built BEFORE the read seam, which is handed
405
+ // it: the plan read asks the same scan the board renders from (a second index
406
+ // would be a second snapshot of the disk, and §2.7's "clean surface" answer must
407
+ // describe the one the board names).
408
+ const index = this.#indexOf(repoRoot);
409
+ // The board's plan read seam — ONE instance per command, threaded down the
410
+ // static render chain (the board's ledgers read their brief revisions through
411
+ // it; a node workspace never mints its own).
412
+ const planSource = new PlanSource(root, index);
368
413
  // ② the read (spec §2.4): ONLY a solo `--plan` reads X's bytes. When `--spec` is
369
414
  // present the board's value comes from `readFor(specEntry)` (§2.1: `--spec` wins),
370
415
  // so X's bytes are never opened — its `--plan` duties stay the ① existence probe
@@ -374,7 +419,6 @@ export class Cli {
374
419
  const soloPlanRead = specRel === null && planRel !== null ? planSource.readPath(planRel) : null;
375
420
  if (soloPlanRead !== null && soloPlanRead.failure()?.cause === "io")
376
421
  return this.#boardCannotRead(`--plan ${planArg}`);
377
- const index = SlugIndex.build(repoRoot);
378
422
  const planEntry = planRel === null ? null : index.entryAt(planRel);
379
423
  const specEntry = specRel === null ? null : index.entryAt(specRel);
380
424
  const unmatched = [
@@ -399,7 +443,13 @@ export class Cli {
399
443
  const host = HostDetect.detect(process.env);
400
444
  // The in-flight fact is TREE-level: the board inspects it (read-only — the gate
401
445
  // and the board share `InFlight.inspect()`, never a second liveness judgment).
402
- const inflight = new InFlight(new WorkspaceRoot(repoRoot, this.#config.handoffNamespace().workspaceRoot), entry.slug ?? "");
446
+ const workspaceRoot = new WorkspaceRoot(repoRoot, this.#config.handoffNamespace().workspaceRoot);
447
+ // The board's ONE matrix instance — the invocation's registry, the same table the
448
+ // node ledgers and the seal sweep read, so the board renders facts and holds no
449
+ // name rule of its own. Each node ledger resolves against ITS OWN workspace (the
450
+ // registry carries no directory), so a parent row never reads a child's names.
451
+ const artifacts = this.#matrix;
452
+ const inflight = new InFlight(workspaceRoot, entry.slug ?? "");
403
453
  // The board's `next:` line renders ONE injected `NextHop` (P22 §5.2 · P24 §11):
404
454
  // the pipeline FACTS come from the board face, and the ONE hop assembly (the four
405
455
  // face-order rules + the six hop cells) lives in the session plane's
@@ -412,7 +462,15 @@ export class Cli {
412
462
  // otherwise).
413
463
  const readTable = this.#boardReadTable(planSource, index, entry, soloPlanRead);
414
464
  const read = readTable[0] ?? planSource.readFor(entry);
415
- const next = BoardNext.of(read, planSource, index, entry, root);
465
+ // The board's artifact observation is ONE value: the matrix seam plus the
466
+ // `--artifacts` switch. Both the hop assembly and the render read it, so the
467
+ // board can never print a `next:` computed against one registry and an `art:`
468
+ // block read through another.
469
+ const projection = {
470
+ registry: artifacts,
471
+ showAll: parsed.args.artifacts === "true",
472
+ };
473
+ const next = BoardNext.of(read, planSource, index, entry, root, projection);
416
474
  // The read's own diagnostics (spec §2.4): stderr, one line per bad read, printed
417
475
  // BEFORE the board. `warnLine` answers null for a healthy plan and for the normal
418
476
  // `undeclared` gap, so the line count is exactly (bad plans + `spec-absent`
@@ -422,7 +480,7 @@ export class Cli {
422
480
  if (warn !== null)
423
481
  this.#io.stderr(`${warn}\n`);
424
482
  }
425
- const board = BoardView.render(readTable, planSource, index, entry, repoRoot, this.#words, host, ARGV_CHANNEL, await inflight.inspect(), next);
483
+ const board = BoardView.render(readTable, planSource, index, entry, repoRoot, this.#words, host, ARGV_CHANNEL, await inflight.inspect(), next, projection);
426
484
  for (const line of board.lines)
427
485
  this.#io.stdout(`${line}\n`);
428
486
  return board.exitCode;
@@ -537,15 +595,20 @@ export class Cli {
537
595
  if (repoRoot === null)
538
596
  return 1;
539
597
  const root = new RepoRoot(repoRoot);
598
+ // The identity index FIRST: the plan read seam below is handed THIS scan, so the
599
+ // phase's plan row, the same-slug spec link and the phase list all speak one
600
+ // snapshot of the doc roots.
601
+ const index = this.#indexOf(repoRoot);
540
602
  // The plan read seam — ONE instance per command, built here in the command
541
- // preamble (the repo root exists now; `Cli.create` runs before it does) and
542
- // passed down as a parameter: the scene, the pre-flight context and the ledger
543
- // all read their plan through this ONE seam.
544
- const planSource = new PlanSource(root);
603
+ // preamble (the repo root and the index exist now; `Cli.create` runs before they
604
+ // do) and passed down as a parameter: the scene, the pre-flight context and the
605
+ // ledger all read their plan through this ONE seam.
606
+ const planSource = new PlanSource(root, index);
545
607
  const parsed = this.#funnel(root, raw);
546
- const scene = await this.#sceneOf(verb, type, node, root, planSource, parsed);
547
- if (scene === null)
608
+ const assembled = await this.#sceneOf(verb, type, node, root, planSource, parsed);
609
+ if (assembled === null)
548
610
  return 1;
611
+ const { scene, artifacts } = assembled;
549
612
  // THE pre-flight seam (P4.1 T1 · design §1): the STRUCTURE gates —
550
613
  // tree-clean → in-flight → graph → plan-ledger → doc-contract — ONE call, the
551
614
  // whole sequence lives in the seam (session/preflight.ts), the CLI orchestrates
@@ -627,7 +690,7 @@ export class Cli {
627
690
  const recovery = !parsed.dryRun &&
628
691
  parsed.args.recover === "true" &&
629
692
  this.#authority.structureRefusal(preflight) === null
630
- ? await this.#recoverRun(verb, type, scene, parsed, inflight)
693
+ ? await this.#recoverRun(verb, type, scene, parsed, inflight, artifacts)
631
694
  : null;
632
695
  if (recovery !== null && recovery.kind === "blocked") {
633
696
  this.#io.stderr(`${this.#words.station("blocked")} ${recovery.message}\n`);
@@ -705,7 +768,7 @@ export class Cli {
705
768
  scene.briefPath = this.#gate.renderBrief(scene, parsed, text, doc);
706
769
  }
707
770
  const statuses = [];
708
- const dispatch = await this.#dispatchOf(scene, parsed, recovery?.harness ?? null);
771
+ const { step: dispatch, harness } = await this.#dispatchOf(scene, parsed, recovery?.harness ?? null, artifacts);
709
772
  const run = new Lifecycle({
710
773
  face: scene.face,
711
774
  state: scene.state,
@@ -769,7 +832,18 @@ export class Cli {
769
832
  // derivation), and the early return means no write point below ever runs
770
833
  // (`renderBrief` skipped above, `#bookkeep`/`#reject` never reached).
771
834
  if (parsed.dryRun) {
772
- for (const line of new Preview({ scene }).render(verb, frame))
835
+ // The artifact-identity gate is a PURE read (the matrix's names + the strict
836
+ // sidecar schema), so the preview asks the SAME judgment the real dispatch
837
+ // applies and prints its reason verbatim — a dry run that stayed silent here
838
+ // would forecast a dispatch the real run refuses.
839
+ const refused = harness === null ? null : harness.artifactRefusal(frame);
840
+ const preview = new Preview({ scene, words: this.#words });
841
+ if (refused !== null) {
842
+ for (const line of preview.artifactBlock(verb, refused))
843
+ this.#io.stdout(`${line}\n`);
844
+ return 1;
845
+ }
846
+ for (const line of preview.render(verb, frame))
773
847
  this.#io.stdout(`${line}\n`);
774
848
  return 0;
775
849
  }
@@ -844,17 +918,22 @@ export class Cli {
844
918
  * retired synthetic approval (`() => ({ status: "APPROVED", findings: [] })`)
845
919
  * has no remaining caller: a preview books no round and fabricates no
846
920
  * conclusion. */
847
- async #dispatchOf(scene, parsed, recovered = null) {
921
+ async #dispatchOf(scene, parsed, recovered, artifacts) {
848
922
  if (this.#dispatch !== null)
849
- return this.#dispatch;
850
- const harness = recovered ?? this.#lifecycleOf(scene, parsed);
923
+ return { step: this.#dispatch, harness: null };
924
+ const harness = recovered ?? this.#lifecycleOf(scene, parsed, artifacts);
851
925
  // The abort fold already ran at the composition root's `--recover` judgment
852
926
  // (`#recoverRun`) when a harness was handed in; the injected/default face keeps
853
927
  // its own fold here, so the takeover always precedes this dispatch's own record.
854
928
  if (recovered === null && !parsed.dryRun && parsed.args.recover === "true") {
855
929
  await harness.foldAbort();
856
930
  }
857
- return harness.step();
931
+ // The harness itself rides back so the `--dry-run` branch can ask it the
932
+ // artifact-identity gate's PURE read (the same judgment `step()` applies), and
933
+ // the preview can print the real run's refusal instead of forecasting a dispatch
934
+ // it would refuse. The injected `#dispatch` seam has no harness — a hermetic
935
+ // caller already replaced the whole dispatch, so there is no gate to ask.
936
+ return { step: harness.step(), harness };
858
937
  }
859
938
  /** The `--recover` judgment (spec §2.1①–③) — the two legs, judged in order and
860
939
  * allowed to stack:
@@ -869,8 +948,8 @@ export class Cli {
869
948
  * `N+1` dispatch third — it lives here, not in `step()`'s internals. `fix --recover`
870
949
  * and `implement --recover` take leg ① only (never a reopen), wave lines likewise
871
950
  * (their reopen face stays P29's brief-drift). */
872
- async #recoverRun(verb, type, scene, parsed, inflight) {
873
- const harness = this.#lifecycleOf(scene, parsed);
951
+ async #recoverRun(verb, type, scene, parsed, inflight, artifacts) {
952
+ const harness = this.#lifecycleOf(scene, parsed, artifacts);
874
953
  const stale = (await inflight.staleState()) !== null;
875
954
  if (stale)
876
955
  await harness.foldAbort();
@@ -901,19 +980,19 @@ export class Cli {
901
980
  return false;
902
981
  if (!ledger.pendingFix(identity.key, type))
903
982
  return false;
904
- const completed = ledger.completedCycles(identity.key, "review", type);
983
+ const completed = ledger.completedCycles(identity.key, "review");
905
984
  if (completed.length === 0)
906
985
  return false;
907
986
  // The next review cycle is the latest completed review's + 1 — allocated BEFORE
908
987
  // the stamp lands (the spec's fixed action order), and it is exactly the cycle the
909
988
  // following dispatch allocates (the register's cycle count is unchanged by a stamp).
910
989
  const latest = Math.max(...completed);
911
- return ledger.supersedeReview(identity.key, type, latest, latest + 1);
990
+ return ledger.supersedeReview(identity.key, latest, latest + 1);
912
991
  }
913
992
  /** The invocation's lifecycle harness — the production dispatch face, held by the
914
993
  * composition root so the abort fold can ride the SAME instance that dispatches
915
994
  * (the takeover precedes the stamp, spec §2.1④). */
916
- #lifecycleOf(scene, parsed) {
995
+ #lifecycleOf(scene, parsed, artifacts) {
917
996
  return new CliLifecycle({
918
997
  env: process.env,
919
998
  sync: this.#sync,
@@ -934,6 +1013,8 @@ export class Cli {
934
1013
  // The explicit takeover flag (`--recover`): the ONLY path that displaces a
935
1014
  // standing in-flight record — and only when its holder is dead.
936
1015
  recover: parsed.args.recover === "true",
1016
+ // The same matrix instance the scene's ledger and router hold.
1017
+ artifacts,
937
1018
  });
938
1019
  }
939
1020
  /** The branch scope anchor (BASE_BRANCH) — the base artifact's branch name read
@@ -941,7 +1022,8 @@ export class Cli {
941
1022
  * writes). "" when the artifact is absent or malformed (the slot stays empty and
942
1023
  * the assembler drops it — the wave/branch review then judges the live tree). */
943
1024
  #baseBranchOf(scene) {
944
- const read = scene.workspace.readJson("base.json");
1025
+ const name = this.#matrix.render({ domain: "workspace", tasks: null }, "base");
1026
+ const read = scene.workspace.readJson(name);
945
1027
  const artifact = read.kind === "ok" ? read.value : null;
946
1028
  return typeof artifact?.base === "string" ? artifact.base : "";
947
1029
  }
@@ -1046,12 +1128,15 @@ export class Cli {
1046
1128
  // The identity index — the ONE slug judgment (spec §2.1/§2.2). The workspace
1047
1129
  // key is the target document's declared `slug:`; the same index supplies the
1048
1130
  // same-slug spec link and the duplicate gates.
1049
- const index = SlugIndex.build(repoRoot);
1131
+ const index = this.#indexOf(repoRoot);
1050
1132
  let slug;
1051
1133
  let plan;
1052
1134
  let specLink = null;
1053
1135
  let overallLink = null;
1054
1136
  let target = null;
1137
+ /** The slug's declared identity document, when the face looks one up — the plan
1138
+ * and branch lines carry it as the round context's spec anchor. */
1139
+ let specDoc = null;
1055
1140
  switch (type) {
1056
1141
  case "wave": {
1057
1142
  if (planPath === null || planRel === null)
@@ -1098,15 +1183,15 @@ export class Cli {
1098
1183
  case "branch": {
1099
1184
  // The plan-doc seam (shared by the plan + branch lines): the target plan
1100
1185
  // must exist (a required fact for both — the branch review/fix faces carry
1101
- // `--plan`), its text is read ONCE, and the same-slug identity document
1102
- // (the index's `identityDoc` — never a path scalar) supplies the round
1103
- // context's extra read input. The link is rebased to repoRoot-relative
1104
- // (D46 · T3) so every round-context path token speaks ONE basis (the child
1105
- // is spawned at cwd = repoRoot). The plan review judges the plan doc; the
1106
- // branch line carries no commit identity (the audit target is the branch
1107
- // itself, its workspace identity is the plan path, and the review's scope
1108
- // anchor BASE_BRANCH is engine-injected from the base artifact) — both
1109
- // faces carry the plan + its same-slug spec anchor.
1186
+ // `--plan`), its text is read ONCE, and the same-slug identity document (the
1187
+ // index's SET answer — never a path scalar) supplies the round context's
1188
+ // extra read input. Its PATH is read through the doc domain after the
1189
+ // workspace exists (below), so the path and the identity come from one read.
1190
+ // The plan review judges the plan doc; the branch line carries no commit
1191
+ // identity (the audit target is the branch itself, its workspace identity is
1192
+ // the plan path, and the review's scope anchor BASE_BRANCH is engine-injected
1193
+ // from the base artifact) — both faces carry the plan + its same-slug spec
1194
+ // anchor.
1110
1195
  if (planPath === null || planRel === null)
1111
1196
  this.#usage(node, `cdd ${verb} --type ${type}: missing required --plan <path>`);
1112
1197
  plan = this.#argvPlanOf(node, planSource, planRel);
@@ -1114,11 +1199,10 @@ export class Cli {
1114
1199
  if (resolved === null)
1115
1200
  return null;
1116
1201
  slug = resolved;
1117
- const specEntry = index.identityDoc(slug);
1118
- specLink = specEntry === null ? null : root.relativize(specEntry.path);
1202
+ specDoc = this.#specDocOf(index, slug);
1119
1203
  // The plan/branch line reads the same-slug identity document's `program:` —
1120
1204
  // the parent charter (INPUT_OVERALL) the reviewer judges the plan against.
1121
- const overallEntry = specEntry?.program == null ? null : index.overallOf(specEntry.program);
1205
+ const overallEntry = specDoc?.program == null ? null : index.overallOf(specDoc.program);
1122
1206
  overallLink = overallEntry === null ? null : root.relativize(overallEntry.path);
1123
1207
  target = type === "plan" ? { kind: "plan", doc: planPath } : { kind: "branch" };
1124
1208
  break;
@@ -1131,41 +1215,63 @@ export class Cli {
1131
1215
  // normalization is the ONE heal path, covering `base.json` alongside
1132
1216
  // `progress.json` (a second healing point is gone).
1133
1217
  const workspace = new Workspace(rootPath, slug);
1134
- const ledger = new Ledger(workspace, config, planSource);
1218
+ // The artifact matrix — the invocation's ONE instance (the command preamble's),
1219
+ // handed down: the ledger, the router, the lifecycle's seal sweep and the board all
1220
+ // read the same table, so no face can spell an artifact name of its own.
1221
+ const artifacts = this.#matrix;
1222
+ const ledger = new Ledger(workspace, config, planSource, artifacts);
1135
1223
  // The run state degrades to the empty state on a non-ready plan: the scene is
1136
1224
  // assembled BEFORE the pre-flight verdict, and the refusal leg (Task 4's
1137
1225
  // doc-contract leg) stops the dispatch before any `state` consumer runs. No
1138
1226
  // try/catch: the read has already happened, so assembly has no throw point.
1139
1227
  const graph = plan.graph();
1140
1228
  const state = type === "wave" && graph !== null ? graph : EMPTY_RUN_STATE;
1229
+ // The identity document the pipeline frontier names — the plan/branch faces already
1230
+ // looked it up; the wave and doc-target faces look it up from their own slug.
1231
+ specDoc ??= this.#specDocOf(index, slug);
1232
+ // ONE read of that document, through the doc domain: a duplicated identity
1233
+ // (`invalid(found)`) supplies NO path — the slug carrier has already refused that
1234
+ // shape, so this face never picks a first document to hand downstream.
1235
+ const identityRead = specDoc === null || specDoc.docType === null
1236
+ ? null
1237
+ : artifacts.read({ domain: "doc", slug, docType: specDoc.docType }, specDoc.docType, workspace);
1238
+ const identityPath = identityRead?.kind === "ok" ? identityRead.path : null;
1239
+ // The spec link is the SAME read's path rebased to repoRoot-relative (D46 · T3), so
1240
+ // every round-context path token speaks ONE basis (the child spawns at cwd = the
1241
+ // repo root) and the anchor and the frontier can never name two documents.
1242
+ if (type === "plan" || type === "branch") {
1243
+ specLink = identityPath === null ? null : root.relativize(identityPath);
1244
+ }
1141
1245
  // The pipeline frontier's four declared cells (§11) — the composition root's ONE
1142
- // collection point. The identity word + path come from the document index (never
1143
- // the argv `--type` spelling): every non-plan declared document owns the identity
1144
- // slot, so `phase-spec` / `single-spec` / `overall` all reach the same assembly.
1145
- // The plan path is the read value's OWN frontier path (`stationPath()`): a
1146
- // command has ONE plan path carrier, so the authority's verdict and this line's
1246
+ // collection point. The identity word + path come from the document index's read
1247
+ // (never the argv `--type` spelling): every non-plan declared document owns the
1248
+ // identity slot, so `phase-spec` / `single-spec` / `overall` all reach the same
1249
+ // assembly. The plan path is the read value's OWN frontier path (`stationPath()`):
1250
+ // a command has ONE plan path carrier, so the authority's verdict and this line's
1147
1251
  // hop can never name two different documents.
1148
- const identity = index.identityDoc(slug);
1149
1252
  const pipeline = {
1150
- specType: identity?.docType ?? null,
1151
- specPath: identity?.path ?? null,
1253
+ specType: specDoc?.docType ?? null,
1254
+ specPath: identityPath,
1152
1255
  planPath: plan.stationPath(),
1153
1256
  plan,
1154
1257
  };
1155
1258
  return {
1156
- workspace,
1157
- ledger,
1158
- planPath,
1159
- plan,
1160
- type,
1161
- face,
1162
- target,
1163
- state,
1164
- router: new NextStepRouter(),
1165
- pipeline,
1166
- briefPath: null,
1167
- specLink,
1168
- overallLink,
1259
+ scene: {
1260
+ workspace,
1261
+ ledger,
1262
+ planPath,
1263
+ plan,
1264
+ type,
1265
+ face,
1266
+ target,
1267
+ state,
1268
+ router: new NextStepRouter(artifacts),
1269
+ pipeline,
1270
+ briefPath: null,
1271
+ specLink,
1272
+ overallLink,
1273
+ },
1274
+ artifacts,
1169
1275
  };
1170
1276
  }
1171
1277
  /** The argv-face plan read (the wave / plan / branch lines) — ONE read through the
@@ -1179,6 +1285,17 @@ export class Cli {
1179
1285
  this.#usage(node, `cannot read file: ${rel}`);
1180
1286
  return plan;
1181
1287
  }
1288
+ /** The slug's declared identity document — the sole index entry of an identity class
1289
+ * (`null` when the slug names none, or when it carries two: an ambiguous set is the
1290
+ * doc domain `read`'s refusal, and this face never picks a first). The returned
1291
+ * entry supplies the declared `docType:` and `program:`; its PATH comes from the doc
1292
+ * domain's read, so a filename is never an identity. */
1293
+ #specDocOf(index, slug) {
1294
+ const docs = index
1295
+ .docsOf(slug)
1296
+ .filter((entry) => entry.docType !== null && entry.docType !== "plan");
1297
+ return docs.length === 1 ? docs[0] : null;
1298
+ }
1182
1299
  /** The plan-carrier target's workspace key (the wave / plan / branch lines) — the
1183
1300
  * document's declared `slug:` (spec §2.1 · §2.4), taken from the plan READ rather
1184
1301
  * than a second text hand-off: a `ready` read supplies its parsed front-matter
@@ -1373,7 +1490,7 @@ export class Cli {
1373
1490
  // (and rejection carrier) the work verbs use. `base` carries no pre-flight gate,
1374
1491
  // so a missing / illegal / duplicated slug or an unreadable target stops HERE:
1375
1492
  // CDD_BLOCKED + exit 1 (never a filename-derived key).
1376
- const slug = this.#targetSlugText(SlugIndex.build(repoRoot), planPath, this.#readTarget(root, planPath));
1493
+ const slug = this.#targetSlugText(this.#indexOf(repoRoot), planPath, this.#readTarget(root, planPath));
1377
1494
  if (slug === null)
1378
1495
  return 1;
1379
1496
  // The workspace is not built here (P11 · §4.2): `base set` builds it through
@@ -21,7 +21,6 @@
21
21
  // algorithm lives in the single CommandTreeBuilder class (face/projection.ts).
22
22
  import { InvalidArgumentError } from "commander";
23
23
  import { MAX_TASKS_PER_WAVE } from "../contract/wave-width.js";
24
- import { ENGINE_DOC_ROOTS } from "../infra/doc-roots.js";
25
24
  import { HOST_IDS } from "./host.js";
26
25
  /** The argv channel table — the CLI flag/type/enum single source (the engine-config
27
26
  * argv channel verbatim: flag spellings, value types and enum domains ride these
@@ -94,6 +93,11 @@ export const ARGV_CHANNEL = {
94
93
  scope: "program",
95
94
  help: "show this help",
96
95
  },
96
+ artifacts: {
97
+ flag: "--artifacts",
98
+ type: "bool",
99
+ help: "expand the board's artifact inventory — one row per observed review round (a troubleshooting view, off by default)",
100
+ },
97
101
  output: {
98
102
  flag: "--output",
99
103
  type: "enum",
@@ -145,13 +149,13 @@ export const CLI_COMMANDS = [
145
149
  {
146
150
  name: "implement",
147
151
  description: `run the task implement phase — at most ${MAX_TASKS_PER_WAVE} tasks per wave`,
148
- example: `cdd implement --tasks 1,2 --plan ${ENGINE_DOC_ROOTS.plans}/p3.md`,
152
+ example: "cdd implement --tasks 1,2 --plan <path>",
149
153
  keys: [{ key: "tasks", required: true }, { key: "plan", required: true }, { key: "recover" }],
150
154
  },
151
155
  {
152
156
  name: "review",
153
157
  description: "run a review — wave | branch | phase-spec | overall | plan | single-spec",
154
- example: `cdd review --type phase-spec --spec ${ENGINE_DOC_ROOTS.specs}/p3-design.md`,
158
+ example: "cdd review --type phase-spec --spec <path>",
155
159
  keys: [
156
160
  { key: "type", required: true },
157
161
  { key: "tasks" },
@@ -177,7 +181,7 @@ export const CLI_COMMANDS = [
177
181
  {
178
182
  name: "base",
179
183
  description: "read/write base.json (single CDD --plan target)",
180
- example: `cdd base set --plan ${ENGINE_DOC_ROOTS.plans}/p3.md --base develop --source plan-field`,
184
+ example: "cdd base set --plan <path> --base develop --source plan-field",
181
185
  keys: [],
182
186
  leaves: [
183
187
  {
@@ -227,8 +231,8 @@ export const CLI_COMMANDS = [
227
231
  {
228
232
  name: "board",
229
233
  description: "render the progress board from a --plan or --spec entry (overall/phase-spec/single-spec/plan/wave/branch)",
230
- example: `cdd board --plan ${ENGINE_DOC_ROOTS.plans}/p3.md`,
231
- keys: [{ key: "plan" }, { key: "spec" }],
234
+ example: "cdd board --plan <path>",
235
+ keys: [{ key: "plan" }, { key: "spec" }, { key: "artifacts" }],
232
236
  },
233
237
  {
234
238
  name: "init",