@oscaner-skills/cdd-engine 4.11.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
@@ -47,13 +47,13 @@ import path from "node:path";
47
47
  import process from "node:process";
48
48
  import { CommanderError } from "commander";
49
49
  import { declaredRegistries } from "../contract/declare.js";
50
- import { PlanDocType } from "../contract/doc.js";
51
50
  import { FrontMatterExtractor } from "../contract/frontmatter.js";
52
51
  import { Contract } from "../contract/judge.js";
53
52
  import { Projector } from "../contract/project.js";
54
53
  import { Translator } from "../contract/translate.js";
55
54
  import { ConfigLoader } from "../infra/config.js";
56
55
  import { GitClient } from "../infra/git.js";
56
+ import { PlanSource } from "../infra/plan-source.js";
57
57
  import { RepoRoot } from "../infra/root.js";
58
58
  import { SlugIndex } from "../infra/slug-index.js";
59
59
  import { Workspace, WorkspaceRoot } from "../infra/workspace.js";
@@ -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 →
@@ -361,7 +401,24 @@ export class Cli {
361
401
  planMissing ? `--plan ${planArg}` : null,
362
402
  specMissing ? `--spec ${specArg}` : null,
363
403
  ]);
364
- const index = SlugIndex.build(repoRoot);
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);
413
+ // ② the read (spec §2.4): ONLY a solo `--plan` reads X's bytes. When `--spec` is
414
+ // present the board's value comes from `readFor(specEntry)` (§2.1: `--spec` wins),
415
+ // so X's bytes are never opened — its `--plan` duties stay the ① existence probe
416
+ // and the ③ `no docs match` attribution. An io failure here is the ONE
417
+ // `cannot read` face: exit 2, no board, no cause tail (`DocFs.read` carries no
418
+ // errno, so a suffix would be an invented literal).
419
+ const soloPlanRead = specRel === null && planRel !== null ? planSource.readPath(planRel) : null;
420
+ if (soloPlanRead !== null && soloPlanRead.failure()?.cause === "io")
421
+ return this.#boardCannotRead(`--plan ${planArg}`);
365
422
  const planEntry = planRel === null ? null : index.entryAt(planRel);
366
423
  const specEntry = specRel === null ? null : index.entryAt(specRel);
367
424
  const unmatched = [
@@ -386,18 +443,69 @@ export class Cli {
386
443
  const host = HostDetect.detect(process.env);
387
444
  // The in-flight fact is TREE-level: the board inspects it (read-only — the gate
388
445
  // and the board share `InFlight.inspect()`, never a second liveness judgment).
389
- 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 ?? "");
390
453
  // The board's `next:` line renders ONE injected `NextHop` (P22 §5.2 · P24 §11):
391
454
  // the pipeline FACTS come from the board face, and the ONE hop assembly (the four
392
455
  // face-order rules + the six hop cells) lives in the session plane's
393
456
  // `PipelineFrontier` — the same assembly the capsule renders, so the board and the
394
457
  // capsule state one hop. Neither face judges anything here.
395
- const next = BoardNext.of(index, entry, root);
396
- const board = BoardView.render(index, entry, repoRoot, this.#words, host, ARGV_CHANNEL, await inflight.inspect(), next);
458
+ // The board's ONE ordered plan value table (spec §2.1 · §2.4): an overall board
459
+ // reads one value per `index.phaseSpecsOf` row, so every phase cell and every
460
+ // `CDD_WARN:` line speaks the same read; a single-document board is a table of
461
+ // length 1 (the argv face's read when `--plan` stands alone, the derived face's
462
+ // otherwise).
463
+ const readTable = this.#boardReadTable(planSource, index, entry, soloPlanRead);
464
+ const read = readTable[0] ?? planSource.readFor(entry);
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);
474
+ // The read's own diagnostics (spec §2.4): stderr, one line per bad read, printed
475
+ // BEFORE the board. `warnLine` answers null for a healthy plan and for the normal
476
+ // `undeclared` gap, so the line count is exactly (bad plans + `spec-absent`
477
+ // orphans + `slug-absent` facts) — never "non-ready phases".
478
+ for (const row of readTable) {
479
+ const warn = row.warnLine(this.#words);
480
+ if (warn !== null)
481
+ this.#io.stderr(`${warn}\n`);
482
+ }
483
+ const board = BoardView.render(readTable, planSource, index, entry, repoRoot, this.#words, host, ARGV_CHANNEL, await inflight.inspect(), next, projection);
397
484
  for (const line of board.lines)
398
485
  this.#io.stdout(`${line}\n`);
399
486
  return board.exitCode;
400
487
  }
488
+ /** The board's ordered per-phase plan value table (spec §2.1 · §2.4) — the ONE
489
+ * construction point of the board's `PlanRead`s. An overall board reads each
490
+ * `phaseSpecsOf` row in index order through the derived face; any other board is
491
+ * one document, whose value the caller already read (the argv face when `--plan`
492
+ * stands alone) or reads here through the derived face. */
493
+ #boardReadTable(planSource, index, entry, soloPlanRead) {
494
+ const slug = entry.slug;
495
+ if (entry.docType !== "overall")
496
+ return [soloPlanRead ?? planSource.readFor(entry)];
497
+ if (slug === null || !SlugIndex.isLegalSlug(slug))
498
+ return [];
499
+ return index.phaseSpecsOf(slug).map((phase) => planSource.readFor(phase));
500
+ }
501
+ /** The board's read-failure face (spec §2.4 ②) — ONE stderr line, exit 2, no board:
502
+ * the named plan's bytes did not read. The message names no cause on purpose: the
503
+ * read seam returns `string | null` and carries no errno, and the `io` / `syntax`
504
+ * distinction rides the `CDD_WARN:` line instead. */
505
+ #boardCannotRead(flag) {
506
+ this.#io.stderr(`cdd board: cannot read ${flag}\n`);
507
+ return 2;
508
+ }
401
509
  /** The board's not-found face (spec §3.1) — the ONE stderr line + exit 2 the
402
510
  * pre-scan membership/existence probe and the post-scan entry lookup share. */
403
511
  #boardNotFound(parts) {
@@ -487,10 +595,20 @@ export class Cli {
487
595
  if (repoRoot === null)
488
596
  return 1;
489
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);
602
+ // The plan read seam — ONE instance per command, built here in the command
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);
490
607
  const parsed = this.#funnel(root, raw);
491
- const scene = await this.#sceneOf(verb, type, node, root, parsed);
492
- if (scene === null)
608
+ const assembled = await this.#sceneOf(verb, type, node, root, planSource, parsed);
609
+ if (assembled === null)
493
610
  return 1;
611
+ const { scene, artifacts } = assembled;
494
612
  // THE pre-flight seam (P4.1 T1 · design §1): the STRUCTURE gates —
495
613
  // tree-clean → in-flight → graph → plan-ledger → doc-contract — ONE call, the
496
614
  // whole sequence lives in the seam (session/preflight.ts), the CLI orchestrates
@@ -515,7 +633,7 @@ export class Cli {
515
633
  const preflight = await this.#preflight.vet({
516
634
  type,
517
635
  repoRoot: scene.workspace.root.repoRoot,
518
- planText: scene.planText,
636
+ plan: scene.plan,
519
637
  ledger: scene.ledger,
520
638
  doc: TargetFaceTable.isDocShape(type)
521
639
  ? {
@@ -547,14 +665,17 @@ export class Cli {
547
665
  let group = null;
548
666
  if (type === "wave") {
549
667
  group = new Set(this.#gate.tasksOf(parsed));
550
- const planIds = scene.planText !== null
551
- ? new PlanDocType("plan")
552
- .parse(scene.planText.split("\n"))
553
- .taskBlocks.map((block) => block.id)
554
- : [];
555
- for (const id of group) {
556
- if (!planIds.includes(id)) {
557
- this.#usage(node, `cdd ${verb}: task ${id} not found in the plan`);
668
+ // The requested ids against the plan's own task set. A non-ready plan (no
669
+ // readable document) judges no membership here — the doc-contract refusal leg
670
+ // owns that verdict; an empty set here is NOT "skip", so the guard stays
671
+ // outside the `doc !== null` block.
672
+ const doc = scene.plan.doc();
673
+ if (doc !== null) {
674
+ const planIds = doc.taskBlocks.map((block) => block.id);
675
+ for (const id of group) {
676
+ if (!planIds.includes(id)) {
677
+ this.#usage(node, `cdd ${verb}: task ${id} not found in the plan`);
678
+ }
558
679
  }
559
680
  }
560
681
  for (const id of scene.ledger.closedWaves())
@@ -569,7 +690,7 @@ export class Cli {
569
690
  const recovery = !parsed.dryRun &&
570
691
  parsed.args.recover === "true" &&
571
692
  this.#authority.structureRefusal(preflight) === null
572
- ? await this.#recoverRun(verb, type, scene, parsed, inflight)
693
+ ? await this.#recoverRun(verb, type, scene, parsed, inflight, artifacts)
573
694
  : null;
574
695
  if (recovery !== null && recovery.kind === "blocked") {
575
696
  this.#io.stderr(`${this.#words.station("blocked")} ${recovery.message}\n`);
@@ -638,13 +759,16 @@ export class Cli {
638
759
  // The unconditional extract (§4.1): every wave-face dispatch re-renders the
639
760
  // brief from the CURRENT plan text — implement, review and fix alike (a
640
761
  // mid-run plan amendment reflects into the next dispatch; no "exists → leave
641
- // it" reuse). The doc/branch faces carry no wave brief (planText is null there).
762
+ // it" reuse). The doc/branch faces carry no wave brief (the plan read is the
763
+ // derived same-slug document there, so the wave face is the only caller).
642
764
  // The preview skips it — the brief is a WRITE (`Workspace#writeText`), and the
643
765
  // preview names the same path through RoundNaming instead of rendering it.
644
- if (!parsed.dryRun && type === "wave" && scene.planText !== null)
645
- scene.briefPath = this.#gate.renderBrief(scene, parsed);
766
+ if (!parsed.dryRun && type === "wave" && scene.plan.kind === "ready") {
767
+ const { text, doc } = scene.plan.document();
768
+ scene.briefPath = this.#gate.renderBrief(scene, parsed, text, doc);
769
+ }
646
770
  const statuses = [];
647
- const dispatch = await this.#dispatchOf(scene, parsed, recovery?.harness ?? null);
771
+ const { step: dispatch, harness } = await this.#dispatchOf(scene, parsed, recovery?.harness ?? null, artifacts);
648
772
  const run = new Lifecycle({
649
773
  face: scene.face,
650
774
  state: scene.state,
@@ -662,10 +786,9 @@ export class Cli {
662
786
  },
663
787
  target: scene.target ?? undefined,
664
788
  capsule: new Capsule(this.#words, ARGV_CHANNEL, HostDetect.detect(process.env), scene.workspace.root.basis),
665
- planPath: scene.pipeline.planPath,
789
+ plan: scene.plan,
666
790
  specType: scene.pipeline.specType,
667
791
  specPath: scene.pipeline.specPath,
668
- planGraph: scene.pipeline.planGraph,
669
792
  // The hop derivation's pipeline-station discrimination (§5.2) — the ONE
670
793
  // declaration-reading judgment, injected so the session plane never imports a
671
794
  // face class.
@@ -709,7 +832,18 @@ export class Cli {
709
832
  // derivation), and the early return means no write point below ever runs
710
833
  // (`renderBrief` skipped above, `#bookkeep`/`#reject` never reached).
711
834
  if (parsed.dryRun) {
712
- 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))
713
847
  this.#io.stdout(`${line}\n`);
714
848
  return 0;
715
849
  }
@@ -784,17 +918,22 @@ export class Cli {
784
918
  * retired synthetic approval (`() => ({ status: "APPROVED", findings: [] })`)
785
919
  * has no remaining caller: a preview books no round and fabricates no
786
920
  * conclusion. */
787
- async #dispatchOf(scene, parsed, recovered = null) {
921
+ async #dispatchOf(scene, parsed, recovered, artifacts) {
788
922
  if (this.#dispatch !== null)
789
- return this.#dispatch;
790
- const harness = recovered ?? this.#lifecycleOf(scene, parsed);
923
+ return { step: this.#dispatch, harness: null };
924
+ const harness = recovered ?? this.#lifecycleOf(scene, parsed, artifacts);
791
925
  // The abort fold already ran at the composition root's `--recover` judgment
792
926
  // (`#recoverRun`) when a harness was handed in; the injected/default face keeps
793
927
  // its own fold here, so the takeover always precedes this dispatch's own record.
794
928
  if (recovered === null && !parsed.dryRun && parsed.args.recover === "true") {
795
929
  await harness.foldAbort();
796
930
  }
797
- 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 };
798
937
  }
799
938
  /** The `--recover` judgment (spec §2.1①–③) — the two legs, judged in order and
800
939
  * allowed to stack:
@@ -809,8 +948,8 @@ export class Cli {
809
948
  * `N+1` dispatch third — it lives here, not in `step()`'s internals. `fix --recover`
810
949
  * and `implement --recover` take leg ① only (never a reopen), wave lines likewise
811
950
  * (their reopen face stays P29's brief-drift). */
812
- async #recoverRun(verb, type, scene, parsed, inflight) {
813
- const harness = this.#lifecycleOf(scene, parsed);
951
+ async #recoverRun(verb, type, scene, parsed, inflight, artifacts) {
952
+ const harness = this.#lifecycleOf(scene, parsed, artifacts);
814
953
  const stale = (await inflight.staleState()) !== null;
815
954
  if (stale)
816
955
  await harness.foldAbort();
@@ -841,19 +980,19 @@ export class Cli {
841
980
  return false;
842
981
  if (!ledger.pendingFix(identity.key, type))
843
982
  return false;
844
- const completed = ledger.completedCycles(identity.key, "review", type);
983
+ const completed = ledger.completedCycles(identity.key, "review");
845
984
  if (completed.length === 0)
846
985
  return false;
847
986
  // The next review cycle is the latest completed review's + 1 — allocated BEFORE
848
987
  // the stamp lands (the spec's fixed action order), and it is exactly the cycle the
849
988
  // following dispatch allocates (the register's cycle count is unchanged by a stamp).
850
989
  const latest = Math.max(...completed);
851
- return ledger.supersedeReview(identity.key, type, latest, latest + 1);
990
+ return ledger.supersedeReview(identity.key, latest, latest + 1);
852
991
  }
853
992
  /** The invocation's lifecycle harness — the production dispatch face, held by the
854
993
  * composition root so the abort fold can ride the SAME instance that dispatches
855
994
  * (the takeover precedes the stamp, spec §2.1④). */
856
- #lifecycleOf(scene, parsed) {
995
+ #lifecycleOf(scene, parsed, artifacts) {
857
996
  return new CliLifecycle({
858
997
  env: process.env,
859
998
  sync: this.#sync,
@@ -864,6 +1003,7 @@ export class Cli {
864
1003
  workspace: scene.workspace,
865
1004
  ledger: scene.ledger,
866
1005
  planPath: scene.planPath,
1006
+ plan: scene.plan,
867
1007
  briefPath: scene.briefPath,
868
1008
  baseBranch: this.#baseBranchOf(scene),
869
1009
  specLink: scene.specLink,
@@ -873,6 +1013,8 @@ export class Cli {
873
1013
  // The explicit takeover flag (`--recover`): the ONLY path that displaces a
874
1014
  // standing in-flight record — and only when its holder is dead.
875
1015
  recover: parsed.args.recover === "true",
1016
+ // The same matrix instance the scene's ledger and router hold.
1017
+ artifacts,
876
1018
  });
877
1019
  }
878
1020
  /** The branch scope anchor (BASE_BRANCH) — the base artifact's branch name read
@@ -880,7 +1022,8 @@ export class Cli {
880
1022
  * writes). "" when the artifact is absent or malformed (the slot stays empty and
881
1023
  * the assembler drops it — the wave/branch review then judges the live tree). */
882
1024
  #baseBranchOf(scene) {
883
- 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);
884
1027
  const artifact = read.kind === "ok" ? read.value : null;
885
1028
  return typeof artifact?.base === "string" ? artifact.base : "";
886
1029
  }
@@ -916,15 +1059,17 @@ export class Cli {
916
1059
  command: (hop) => this.#gate.hopCommand(scene, hop, this.#words),
917
1060
  });
918
1061
  this.#io.stderr(`cdd ${verb}: cannot dispatch a ${expected} round — ${message}\n`);
919
- if (rejection.reason === "split" && scene.planText !== null) {
920
- this.#renderWaveBoard(scene, scene.planText);
1062
+ if (rejection.reason === "split" && scene.plan.kind === "ready") {
1063
+ this.#renderWaveBoard(scene, scene.plan);
921
1064
  }
922
1065
  this.#renderChecked(preflight);
923
1066
  }
924
1067
  /** The wave-board hint of a split refusal — the derived graph the refusal is
925
1068
  * about, rendered on the stderr detail channel. */
926
- #renderWaveBoard(scene, planText) {
927
- const graph = new TaskGraph(new PlanDocType("plan").parse(planText.split("\n")));
1069
+ #renderWaveBoard(scene, read) {
1070
+ const graph = read.graph();
1071
+ if (graph === null)
1072
+ return;
928
1073
  const closed = scene.ledger.closedWaves();
929
1074
  // The graph title's plan path renders repoRoot-relative (D47 · the ONE shape;
930
1075
  // `scene.planPath` is argv-origin) — normalized through the scene's OWN basis
@@ -965,7 +1110,7 @@ export class Cli {
965
1110
  * null, which the caller turns into the BLOCKED exit (§2.6). The path-typed argv
966
1111
  * values ride the input funnel (T3 · `#funnel`) so the scene consumes canonical
967
1112
  * repoRoot-relative `RepoPath`s. */
968
- async #sceneOf(verb, type, node, root, parsed) {
1113
+ async #sceneOf(verb, type, node, root, planSource, parsed) {
969
1114
  const config = this.#config;
970
1115
  const face = targetFaces[type];
971
1116
  const repoRoot = root.absolute;
@@ -983,18 +1128,21 @@ export class Cli {
983
1128
  // The identity index — the ONE slug judgment (spec §2.1/§2.2). The workspace
984
1129
  // key is the target document's declared `slug:`; the same index supplies the
985
1130
  // same-slug spec link and the duplicate gates.
986
- const index = SlugIndex.build(repoRoot);
1131
+ const index = this.#indexOf(repoRoot);
987
1132
  let slug;
988
- let planText = null;
1133
+ let plan;
989
1134
  let specLink = null;
990
1135
  let overallLink = null;
991
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;
992
1140
  switch (type) {
993
1141
  case "wave": {
994
1142
  if (planPath === null || planRel === null)
995
1143
  this.#usage(node, `cdd ${verb} --type wave: missing required --plan <path>`);
996
- planText = this.#artifacts.readText(node, root, planRel);
997
- const resolved = this.#targetSlug(index, planRel, planText);
1144
+ plan = this.#argvPlanOf(node, planSource, planRel);
1145
+ const resolved = this.#targetSlug(index, planRel, plan);
998
1146
  if (resolved === null)
999
1147
  return null;
1000
1148
  slug = resolved;
@@ -1009,17 +1157,23 @@ export class Cli {
1009
1157
  // it (CDD_BLOCKED + exit 1, never a filename-derived key). The T7 null-verdict
1010
1158
  // face covers the other shape — a document ON DISK that declares no
1011
1159
  // `doc-type:` / `slug:`.
1012
- const resolved = this.#targetSlug(index, specRel, this.#readTarget(root, specRel));
1160
+ const specEntry = index.entryAt(specRel);
1161
+ const resolved = this.#targetSlugText(index, specRel, this.#readTarget(root, specRel));
1013
1162
  if (resolved === null)
1014
1163
  return null;
1015
1164
  slug = resolved;
1016
1165
  target = { kind: "spec", doc: specPath };
1166
+ // The plan face of a doc round is the SAME derived document every other face
1167
+ // derives (`plans/<the identity doc's slug>.md`), read through the derived
1168
+ // entry — so the doc round and the plan round speak one document. The read
1169
+ // is derived on EVERY face, never re-pointed at an index-registered file
1170
+ // name: identity is the slug, the path is derived from it.
1171
+ plan = planSource.readFor(specEntry);
1017
1172
  // The judged document's own `program:` — the parent charter (INPUT_OVERALL)
1018
1173
  // the phase-spec reviewer judges the phase against. A document without
1019
1174
  // `program:` (an overall charter or a single-spec) leaves the slot null; an
1020
1175
  // off-disk target reads null here and the existing slug-ref invariant reports
1021
1176
  // it (never a second reporter).
1022
- const specEntry = index.entryAt(specRel);
1023
1177
  const overallEntry = specEntry?.program == null ? null : index.overallOf(specEntry.program);
1024
1178
  overallLink = overallEntry === null ? null : root.relativize(overallEntry.path);
1025
1179
  break;
@@ -1029,27 +1183,26 @@ export class Cli {
1029
1183
  case "branch": {
1030
1184
  // The plan-doc seam (shared by the plan + branch lines): the target plan
1031
1185
  // must exist (a required fact for both — the branch review/fix faces carry
1032
- // `--plan`), its text is read ONCE, and the same-slug identity document
1033
- // (the index's `identityDoc` — never a path scalar) supplies the round
1034
- // context's extra read input. The link is rebased to repoRoot-relative
1035
- // (D46 · T3) so every round-context path token speaks ONE basis (the child
1036
- // is spawned at cwd = repoRoot). The plan review judges the plan doc; the
1037
- // branch line carries no commit identity (the audit target is the branch
1038
- // itself, its workspace identity is the plan path, and the review's scope
1039
- // anchor BASE_BRANCH is engine-injected from the base artifact) — both
1040
- // 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.
1041
1195
  if (planPath === null || planRel === null)
1042
1196
  this.#usage(node, `cdd ${verb} --type ${type}: missing required --plan <path>`);
1043
- planText = this.#artifacts.readText(node, root, planRel);
1044
- const resolved = this.#targetSlug(index, planRel, planText);
1197
+ plan = this.#argvPlanOf(node, planSource, planRel);
1198
+ const resolved = this.#targetSlug(index, planRel, plan);
1045
1199
  if (resolved === null)
1046
1200
  return null;
1047
1201
  slug = resolved;
1048
- const specEntry = index.identityDoc(slug);
1049
- specLink = specEntry === null ? null : root.relativize(specEntry.path);
1202
+ specDoc = this.#specDocOf(index, slug);
1050
1203
  // The plan/branch line reads the same-slug identity document's `program:` —
1051
1204
  // the parent charter (INPUT_OVERALL) the reviewer judges the plan against.
1052
- const overallEntry = specEntry?.program == null ? null : index.overallOf(specEntry.program);
1205
+ const overallEntry = specDoc?.program == null ? null : index.overallOf(specDoc.program);
1053
1206
  overallLink = overallEntry === null ? null : root.relativize(overallEntry.path);
1054
1207
  target = type === "plan" ? { kind: "plan", doc: planPath } : { kind: "branch" };
1055
1208
  break;
@@ -1062,52 +1215,115 @@ export class Cli {
1062
1215
  // normalization is the ONE heal path, covering `base.json` alongside
1063
1216
  // `progress.json` (a second healing point is gone).
1064
1217
  const workspace = new Workspace(rootPath, slug);
1065
- const ledger = new Ledger(workspace, config);
1066
- const state = type === "wave"
1067
- ? new TaskGraph(new PlanDocType("plan").parse(planText.split("\n")))
1068
- : EMPTY_RUN_STATE;
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);
1223
+ // The run state degrades to the empty state on a non-ready plan: the scene is
1224
+ // assembled BEFORE the pre-flight verdict, and the refusal leg (Task 4's
1225
+ // doc-contract leg) stops the dispatch before any `state` consumer runs. No
1226
+ // try/catch: the read has already happened, so assembly has no throw point.
1227
+ const graph = plan.graph();
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
+ }
1069
1245
  // The pipeline frontier's four declared cells (§11) — the composition root's ONE
1070
- // collection point. The identity word + path come from the document index (never
1071
- // the argv `--type` spelling): every non-plan declared document owns the identity
1072
- // slot, so `phase-spec` / `single-spec` / `overall` all reach the same assembly.
1073
- // The plan path is the argv value on the plan / branch lines and the index's
1074
- // same-slug plan on a `--spec` round whose argv names none — a spec round that
1075
- // dropped it would leave the frontier blind to the plan face and the capsule
1076
- // printing this line's own exit. The graph is the ONE guarded plan read (the wave
1077
- // run's already-parsed state stands in; the session plane reads no file).
1078
- const identity = index.identityDoc(slug);
1079
- const hopPlanPath = planPath ?? index.planOf(slug)?.path ?? null;
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
1251
+ // hop can never name two different documents.
1080
1252
  const pipeline = {
1081
- specType: identity?.docType ?? null,
1082
- specPath: identity?.path ?? null,
1083
- planPath: hopPlanPath,
1084
- planGraph: state instanceof TaskGraph ? state : BoardView.planGraph(hopPlanPath),
1253
+ specType: specDoc?.docType ?? null,
1254
+ specPath: identityPath,
1255
+ planPath: plan.stationPath(),
1256
+ plan,
1085
1257
  };
1086
1258
  return {
1087
- workspace,
1088
- ledger,
1089
- planPath,
1090
- planText,
1091
- type,
1092
- face,
1093
- target,
1094
- state,
1095
- router: new NextStepRouter(),
1096
- pipeline,
1097
- briefPath: null,
1098
- specLink,
1099
- 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,
1100
1275
  };
1101
1276
  }
1102
- /** The dispatch target's workspace key — the document's declared `slug:`
1103
- * (spec §2.1 · §2.4). ONE read face shared by the three work verbs and `base`:
1104
- * an unreadable target, a missing `slug:`, an illegal value, or a slug the index
1105
- * judges duplicated (identity or plan) each render the CDD_BLOCKED station and
1106
- * return null (exit 1 at the caller — never the board's exit 2). The duplicate
1107
- * judgment reads the SAME `SlugIndex` the board renders, so the two faces never
1108
- * diverge (one fact, two carriers). The caller passes the document text it
1109
- * already holds — the identity read never opens the file a second time. */
1110
- #targetSlug(index, rel, content) {
1277
+ /** The argv-face plan read (the wave / plan / branch lines) — ONE read through the
1278
+ * command preamble's `PlanSource`. An `io` failure keeps today's usage byte (the
1279
+ * same `#usage` seam the retired `readText` rode): the workspace key has no
1280
+ * source, so the run stops here, BEFORE any identity is derived or any workspace
1281
+ * gets built — never a fabricated slug. */
1282
+ #argvPlanOf(node, planSource, rel) {
1283
+ const plan = planSource.readPath(rel);
1284
+ if (plan.failure()?.cause === "io")
1285
+ this.#usage(node, `cannot read file: ${rel}`);
1286
+ return plan;
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
+ }
1299
+ /** The plan-carrier target's workspace key (the wave / plan / branch lines) — the
1300
+ * document's declared `slug:` (spec §2.1 · §2.4), taken from the plan READ rather
1301
+ * than a second text hand-off: a `ready` read supplies its parsed front-matter
1302
+ * head, and a `syntax` read (the grammar refused the plan, its front matter read
1303
+ * out) supplies the index's own entry, so the scene still assembles and the
1304
+ * doc-contract refusal leg can speak. An `io` failure never reaches here — it
1305
+ * stops at `#argvPlanOf`. A missing / illegal / duplicated slug (identity or plan)
1306
+ * renders the CDD_BLOCKED station and returns null (exit 1 at the caller — never
1307
+ * the board's exit 2). The workspace key therefore stays a `string`: no `slug!`,
1308
+ * no `slug ?? ""`. */
1309
+ #targetSlug(index, rel, read) {
1310
+ const head = read.doc()?.head ?? null;
1311
+ const parseError = head?.parseError ?? null;
1312
+ if (parseError !== null)
1313
+ return this.#parseErrorBlocked(parseError);
1314
+ const slug = head !== null ? head.slug : (index.entryAt(rel)?.slug ?? null);
1315
+ // The four-way identity gate (present · legal · indexed · unique) is the ONE
1316
+ // `SlugIndex` judgment the pre-flight gate also reads — this carrier supplies
1317
+ // only the CDD_BLOCKED channel, never a second spelling of the rule.
1318
+ return this.#slugVerdictOf(index, rel, slug);
1319
+ }
1320
+ /** The text-carrier target's workspace key (the doc faces and `base`) — ONE read
1321
+ * face shared by the three work verbs' spec shapes and `base`: an unreadable
1322
+ * target, a missing `slug:`, an illegal value, or a slug the index judges
1323
+ * duplicated each render the CDD_BLOCKED station and return null (exit 1 at the
1324
+ * caller). The caller passes the document text it already holds — the identity
1325
+ * read never opens the file a second time. */
1326
+ #targetSlugText(index, rel, content) {
1111
1327
  // An unreadable target document declares no identity — the workspace key has
1112
1328
  // no source, so the dispatch face refuses on the SAME carrier as a missing
1113
1329
  // `slug:` (never a filename-derived directory).
@@ -1116,20 +1332,30 @@ export class Cli {
1116
1332
  const head = FrontMatterExtractor.split(content).head;
1117
1333
  const parseError = head.parseError;
1118
1334
  if (parseError !== null)
1119
- return this.#slugBlocked(this.#words
1120
- .routeWord("frontmatterParse")
1121
- .replace("{reason}", parseError.reason)
1122
- .replace("{line}", String(parseError.line))
1123
- .replace("{column}", String(parseError.column))
1124
- .replace("{source}", parseError.source));
1125
- // The four-way identity gate (present · legal · indexed · unique) is the ONE
1126
- // `SlugIndex` judgment the pre-flight gate also reads — this carrier supplies
1127
- // only the CDD_BLOCKED channel, never a second spelling of the rule.
1128
- const verdict = index.slugVerdict(rel, head.slug);
1335
+ return this.#parseErrorBlocked(parseError);
1336
+ return this.#slugVerdictOf(index, rel, head.slug);
1337
+ }
1338
+ /** The identity carriers' shared tail — the ONE named-key verdict pair: the four-way
1339
+ * `SlugIndex` judgment and its CDD_BLOCKED channel. Both carriers differ only in
1340
+ * where their `slug` comes from (a plan read's front matter, a target document's
1341
+ * text); the verdict and the refusal are one fact, never two spellings. */
1342
+ #slugVerdictOf(index, rel, slug) {
1343
+ const verdict = index.slugVerdict(rel, slug);
1129
1344
  return verdict.kind === "accepted"
1130
1345
  ? verdict.slug
1131
1346
  : this.#slugBlocked(this.#words.slugRefusal(verdict));
1132
1347
  }
1348
+ /** The front-matter parse break's refusal — ONE message construction for the two
1349
+ * identity carriers (a broken head is unjudgeable whichever face reads it). The
1350
+ * bytes are the pre-existing `frontmatterParse` route word, unchanged. */
1351
+ #parseErrorBlocked(parseError) {
1352
+ return this.#slugBlocked(this.#words
1353
+ .routeWord("frontmatterParse")
1354
+ .replace("{reason}", parseError.reason)
1355
+ .replace("{line}", String(parseError.line))
1356
+ .replace("{column}", String(parseError.column))
1357
+ .replace("{source}", parseError.source));
1358
+ }
1133
1359
  /** Read a dispatch target's text — null when the file is absent or unreadable.
1134
1360
  * The null is NOT a degradation: every caller hands it to `#targetSlug`, which
1135
1361
  * refuses the target on the slug carrier (CDD_BLOCKED + exit 1). A document
@@ -1264,7 +1490,7 @@ export class Cli {
1264
1490
  // (and rejection carrier) the work verbs use. `base` carries no pre-flight gate,
1265
1491
  // so a missing / illegal / duplicated slug or an unreadable target stops HERE:
1266
1492
  // CDD_BLOCKED + exit 1 (never a filename-derived key).
1267
- const slug = this.#targetSlug(SlugIndex.build(repoRoot), planPath, this.#readTarget(root, planPath));
1493
+ const slug = this.#targetSlugText(this.#indexOf(repoRoot), planPath, this.#readTarget(root, planPath));
1268
1494
  if (slug === null)
1269
1495
  return 1;
1270
1496
  // The workspace is not built here (P11 · §4.2): `base set` builds it through