@oscaner-skills/cdd-engine 4.11.0 → 4.12.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";
@@ -347,6 +347,10 @@ export class Cli {
347
347
  if (repoRoot === null)
348
348
  return 1;
349
349
  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);
350
354
  const planRel = planArg === undefined ? null : this.#relativizePath(root, planArg);
351
355
  const specRel = specArg === undefined ? null : this.#relativizePath(root, specArg);
352
356
  // The not-found face reads ZERO documents (spec §3.1): a path outside the two
@@ -361,6 +365,15 @@ export class Cli {
361
365
  planMissing ? `--plan ${planArg}` : null,
362
366
  specMissing ? `--spec ${specArg}` : null,
363
367
  ]);
368
+ // ② the read (spec §2.4): ONLY a solo `--plan` reads X's bytes. When `--spec` is
369
+ // present the board's value comes from `readFor(specEntry)` (§2.1: `--spec` wins),
370
+ // so X's bytes are never opened — its `--plan` duties stay the ① existence probe
371
+ // and the ③ `no docs match` attribution. An io failure here is the ONE
372
+ // `cannot read` face: exit 2, no board, no cause tail (`DocFs.read` carries no
373
+ // errno, so a suffix would be an invented literal).
374
+ const soloPlanRead = specRel === null && planRel !== null ? planSource.readPath(planRel) : null;
375
+ if (soloPlanRead !== null && soloPlanRead.failure()?.cause === "io")
376
+ return this.#boardCannotRead(`--plan ${planArg}`);
364
377
  const index = SlugIndex.build(repoRoot);
365
378
  const planEntry = planRel === null ? null : index.entryAt(planRel);
366
379
  const specEntry = specRel === null ? null : index.entryAt(specRel);
@@ -392,12 +405,49 @@ export class Cli {
392
405
  // face-order rules + the six hop cells) lives in the session plane's
393
406
  // `PipelineFrontier` — the same assembly the capsule renders, so the board and the
394
407
  // 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);
408
+ // The board's ONE ordered plan value table (spec §2.1 · §2.4): an overall board
409
+ // reads one value per `index.phaseSpecsOf` row, so every phase cell and every
410
+ // `CDD_WARN:` line speaks the same read; a single-document board is a table of
411
+ // length 1 (the argv face's read when `--plan` stands alone, the derived face's
412
+ // otherwise).
413
+ const readTable = this.#boardReadTable(planSource, index, entry, soloPlanRead);
414
+ const read = readTable[0] ?? planSource.readFor(entry);
415
+ const next = BoardNext.of(read, planSource, index, entry, root);
416
+ // The read's own diagnostics (spec §2.4): stderr, one line per bad read, printed
417
+ // BEFORE the board. `warnLine` answers null for a healthy plan and for the normal
418
+ // `undeclared` gap, so the line count is exactly (bad plans + `spec-absent`
419
+ // orphans + `slug-absent` facts) — never "non-ready phases".
420
+ for (const row of readTable) {
421
+ const warn = row.warnLine(this.#words);
422
+ if (warn !== null)
423
+ this.#io.stderr(`${warn}\n`);
424
+ }
425
+ const board = BoardView.render(readTable, planSource, index, entry, repoRoot, this.#words, host, ARGV_CHANNEL, await inflight.inspect(), next);
397
426
  for (const line of board.lines)
398
427
  this.#io.stdout(`${line}\n`);
399
428
  return board.exitCode;
400
429
  }
430
+ /** The board's ordered per-phase plan value table (spec §2.1 · §2.4) — the ONE
431
+ * construction point of the board's `PlanRead`s. An overall board reads each
432
+ * `phaseSpecsOf` row in index order through the derived face; any other board is
433
+ * one document, whose value the caller already read (the argv face when `--plan`
434
+ * stands alone) or reads here through the derived face. */
435
+ #boardReadTable(planSource, index, entry, soloPlanRead) {
436
+ const slug = entry.slug;
437
+ if (entry.docType !== "overall")
438
+ return [soloPlanRead ?? planSource.readFor(entry)];
439
+ if (slug === null || !SlugIndex.isLegalSlug(slug))
440
+ return [];
441
+ return index.phaseSpecsOf(slug).map((phase) => planSource.readFor(phase));
442
+ }
443
+ /** The board's read-failure face (spec §2.4 ②) — ONE stderr line, exit 2, no board:
444
+ * the named plan's bytes did not read. The message names no cause on purpose: the
445
+ * read seam returns `string | null` and carries no errno, and the `io` / `syntax`
446
+ * distinction rides the `CDD_WARN:` line instead. */
447
+ #boardCannotRead(flag) {
448
+ this.#io.stderr(`cdd board: cannot read ${flag}\n`);
449
+ return 2;
450
+ }
401
451
  /** The board's not-found face (spec §3.1) — the ONE stderr line + exit 2 the
402
452
  * pre-scan membership/existence probe and the post-scan entry lookup share. */
403
453
  #boardNotFound(parts) {
@@ -487,8 +537,13 @@ export class Cli {
487
537
  if (repoRoot === null)
488
538
  return 1;
489
539
  const root = new RepoRoot(repoRoot);
540
+ // 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);
490
545
  const parsed = this.#funnel(root, raw);
491
- const scene = await this.#sceneOf(verb, type, node, root, parsed);
546
+ const scene = await this.#sceneOf(verb, type, node, root, planSource, parsed);
492
547
  if (scene === null)
493
548
  return 1;
494
549
  // THE pre-flight seam (P4.1 T1 · design §1): the STRUCTURE gates —
@@ -515,7 +570,7 @@ export class Cli {
515
570
  const preflight = await this.#preflight.vet({
516
571
  type,
517
572
  repoRoot: scene.workspace.root.repoRoot,
518
- planText: scene.planText,
573
+ plan: scene.plan,
519
574
  ledger: scene.ledger,
520
575
  doc: TargetFaceTable.isDocShape(type)
521
576
  ? {
@@ -547,14 +602,17 @@ export class Cli {
547
602
  let group = null;
548
603
  if (type === "wave") {
549
604
  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`);
605
+ // The requested ids against the plan's own task set. A non-ready plan (no
606
+ // readable document) judges no membership here — the doc-contract refusal leg
607
+ // owns that verdict; an empty set here is NOT "skip", so the guard stays
608
+ // outside the `doc !== null` block.
609
+ const doc = scene.plan.doc();
610
+ if (doc !== null) {
611
+ const planIds = doc.taskBlocks.map((block) => block.id);
612
+ for (const id of group) {
613
+ if (!planIds.includes(id)) {
614
+ this.#usage(node, `cdd ${verb}: task ${id} not found in the plan`);
615
+ }
558
616
  }
559
617
  }
560
618
  for (const id of scene.ledger.closedWaves())
@@ -638,11 +696,14 @@ export class Cli {
638
696
  // The unconditional extract (§4.1): every wave-face dispatch re-renders the
639
697
  // brief from the CURRENT plan text — implement, review and fix alike (a
640
698
  // 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).
699
+ // it" reuse). The doc/branch faces carry no wave brief (the plan read is the
700
+ // derived same-slug document there, so the wave face is the only caller).
642
701
  // The preview skips it — the brief is a WRITE (`Workspace#writeText`), and the
643
702
  // 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);
703
+ if (!parsed.dryRun && type === "wave" && scene.plan.kind === "ready") {
704
+ const { text, doc } = scene.plan.document();
705
+ scene.briefPath = this.#gate.renderBrief(scene, parsed, text, doc);
706
+ }
646
707
  const statuses = [];
647
708
  const dispatch = await this.#dispatchOf(scene, parsed, recovery?.harness ?? null);
648
709
  const run = new Lifecycle({
@@ -662,10 +723,9 @@ export class Cli {
662
723
  },
663
724
  target: scene.target ?? undefined,
664
725
  capsule: new Capsule(this.#words, ARGV_CHANNEL, HostDetect.detect(process.env), scene.workspace.root.basis),
665
- planPath: scene.pipeline.planPath,
726
+ plan: scene.plan,
666
727
  specType: scene.pipeline.specType,
667
728
  specPath: scene.pipeline.specPath,
668
- planGraph: scene.pipeline.planGraph,
669
729
  // The hop derivation's pipeline-station discrimination (§5.2) — the ONE
670
730
  // declaration-reading judgment, injected so the session plane never imports a
671
731
  // face class.
@@ -864,6 +924,7 @@ export class Cli {
864
924
  workspace: scene.workspace,
865
925
  ledger: scene.ledger,
866
926
  planPath: scene.planPath,
927
+ plan: scene.plan,
867
928
  briefPath: scene.briefPath,
868
929
  baseBranch: this.#baseBranchOf(scene),
869
930
  specLink: scene.specLink,
@@ -916,15 +977,17 @@ export class Cli {
916
977
  command: (hop) => this.#gate.hopCommand(scene, hop, this.#words),
917
978
  });
918
979
  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);
980
+ if (rejection.reason === "split" && scene.plan.kind === "ready") {
981
+ this.#renderWaveBoard(scene, scene.plan);
921
982
  }
922
983
  this.#renderChecked(preflight);
923
984
  }
924
985
  /** The wave-board hint of a split refusal — the derived graph the refusal is
925
986
  * about, rendered on the stderr detail channel. */
926
- #renderWaveBoard(scene, planText) {
927
- const graph = new TaskGraph(new PlanDocType("plan").parse(planText.split("\n")));
987
+ #renderWaveBoard(scene, read) {
988
+ const graph = read.graph();
989
+ if (graph === null)
990
+ return;
928
991
  const closed = scene.ledger.closedWaves();
929
992
  // The graph title's plan path renders repoRoot-relative (D47 · the ONE shape;
930
993
  // `scene.planPath` is argv-origin) — normalized through the scene's OWN basis
@@ -965,7 +1028,7 @@ export class Cli {
965
1028
  * null, which the caller turns into the BLOCKED exit (§2.6). The path-typed argv
966
1029
  * values ride the input funnel (T3 · `#funnel`) so the scene consumes canonical
967
1030
  * repoRoot-relative `RepoPath`s. */
968
- async #sceneOf(verb, type, node, root, parsed) {
1031
+ async #sceneOf(verb, type, node, root, planSource, parsed) {
969
1032
  const config = this.#config;
970
1033
  const face = targetFaces[type];
971
1034
  const repoRoot = root.absolute;
@@ -985,7 +1048,7 @@ export class Cli {
985
1048
  // same-slug spec link and the duplicate gates.
986
1049
  const index = SlugIndex.build(repoRoot);
987
1050
  let slug;
988
- let planText = null;
1051
+ let plan;
989
1052
  let specLink = null;
990
1053
  let overallLink = null;
991
1054
  let target = null;
@@ -993,8 +1056,8 @@ export class Cli {
993
1056
  case "wave": {
994
1057
  if (planPath === null || planRel === null)
995
1058
  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);
1059
+ plan = this.#argvPlanOf(node, planSource, planRel);
1060
+ const resolved = this.#targetSlug(index, planRel, plan);
998
1061
  if (resolved === null)
999
1062
  return null;
1000
1063
  slug = resolved;
@@ -1009,17 +1072,23 @@ export class Cli {
1009
1072
  // it (CDD_BLOCKED + exit 1, never a filename-derived key). The T7 null-verdict
1010
1073
  // face covers the other shape — a document ON DISK that declares no
1011
1074
  // `doc-type:` / `slug:`.
1012
- const resolved = this.#targetSlug(index, specRel, this.#readTarget(root, specRel));
1075
+ const specEntry = index.entryAt(specRel);
1076
+ const resolved = this.#targetSlugText(index, specRel, this.#readTarget(root, specRel));
1013
1077
  if (resolved === null)
1014
1078
  return null;
1015
1079
  slug = resolved;
1016
1080
  target = { kind: "spec", doc: specPath };
1081
+ // The plan face of a doc round is the SAME derived document every other face
1082
+ // derives (`plans/<the identity doc's slug>.md`), read through the derived
1083
+ // entry — so the doc round and the plan round speak one document. The read
1084
+ // is derived on EVERY face, never re-pointed at an index-registered file
1085
+ // name: identity is the slug, the path is derived from it.
1086
+ plan = planSource.readFor(specEntry);
1017
1087
  // The judged document's own `program:` — the parent charter (INPUT_OVERALL)
1018
1088
  // the phase-spec reviewer judges the phase against. A document without
1019
1089
  // `program:` (an overall charter or a single-spec) leaves the slot null; an
1020
1090
  // off-disk target reads null here and the existing slug-ref invariant reports
1021
1091
  // it (never a second reporter).
1022
- const specEntry = index.entryAt(specRel);
1023
1092
  const overallEntry = specEntry?.program == null ? null : index.overallOf(specEntry.program);
1024
1093
  overallLink = overallEntry === null ? null : root.relativize(overallEntry.path);
1025
1094
  break;
@@ -1040,8 +1109,8 @@ export class Cli {
1040
1109
  // faces carry the plan + its same-slug spec anchor.
1041
1110
  if (planPath === null || planRel === null)
1042
1111
  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);
1112
+ plan = this.#argvPlanOf(node, planSource, planRel);
1113
+ const resolved = this.#targetSlug(index, planRel, plan);
1045
1114
  if (resolved === null)
1046
1115
  return null;
1047
1116
  slug = resolved;
@@ -1062,32 +1131,32 @@ export class Cli {
1062
1131
  // normalization is the ONE heal path, covering `base.json` alongside
1063
1132
  // `progress.json` (a second healing point is gone).
1064
1133
  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;
1134
+ const ledger = new Ledger(workspace, config, planSource);
1135
+ // The run state degrades to the empty state on a non-ready plan: the scene is
1136
+ // assembled BEFORE the pre-flight verdict, and the refusal leg (Task 4's
1137
+ // doc-contract leg) stops the dispatch before any `state` consumer runs. No
1138
+ // try/catch: the read has already happened, so assembly has no throw point.
1139
+ const graph = plan.graph();
1140
+ const state = type === "wave" && graph !== null ? graph : EMPTY_RUN_STATE;
1069
1141
  // The pipeline frontier's four declared cells (§11) — the composition root's ONE
1070
1142
  // collection point. The identity word + path come from the document index (never
1071
1143
  // the argv `--type` spelling): every non-plan declared document owns the identity
1072
1144
  // 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).
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
1147
+ // hop can never name two different documents.
1078
1148
  const identity = index.identityDoc(slug);
1079
- const hopPlanPath = planPath ?? index.planOf(slug)?.path ?? null;
1080
1149
  const pipeline = {
1081
1150
  specType: identity?.docType ?? null,
1082
1151
  specPath: identity?.path ?? null,
1083
- planPath: hopPlanPath,
1084
- planGraph: state instanceof TaskGraph ? state : BoardView.planGraph(hopPlanPath),
1152
+ planPath: plan.stationPath(),
1153
+ plan,
1085
1154
  };
1086
1155
  return {
1087
1156
  workspace,
1088
1157
  ledger,
1089
1158
  planPath,
1090
- planText,
1159
+ plan,
1091
1160
  type,
1092
1161
  face,
1093
1162
  target,
@@ -1099,15 +1168,45 @@ export class Cli {
1099
1168
  overallLink,
1100
1169
  };
1101
1170
  }
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) {
1171
+ /** The argv-face plan read (the wave / plan / branch lines) — ONE read through the
1172
+ * command preamble's `PlanSource`. An `io` failure keeps today's usage byte (the
1173
+ * same `#usage` seam the retired `readText` rode): the workspace key has no
1174
+ * source, so the run stops here, BEFORE any identity is derived or any workspace
1175
+ * gets built — never a fabricated slug. */
1176
+ #argvPlanOf(node, planSource, rel) {
1177
+ const plan = planSource.readPath(rel);
1178
+ if (plan.failure()?.cause === "io")
1179
+ this.#usage(node, `cannot read file: ${rel}`);
1180
+ return plan;
1181
+ }
1182
+ /** The plan-carrier target's workspace key (the wave / plan / branch lines) — the
1183
+ * document's declared `slug:` (spec §2.1 · §2.4), taken from the plan READ rather
1184
+ * than a second text hand-off: a `ready` read supplies its parsed front-matter
1185
+ * head, and a `syntax` read (the grammar refused the plan, its front matter read
1186
+ * out) supplies the index's own entry, so the scene still assembles and the
1187
+ * doc-contract refusal leg can speak. An `io` failure never reaches here — it
1188
+ * stops at `#argvPlanOf`. A missing / illegal / duplicated slug (identity or plan)
1189
+ * renders the CDD_BLOCKED station and returns null (exit 1 at the caller — never
1190
+ * the board's exit 2). The workspace key therefore stays a `string`: no `slug!`,
1191
+ * no `slug ?? ""`. */
1192
+ #targetSlug(index, rel, read) {
1193
+ const head = read.doc()?.head ?? null;
1194
+ const parseError = head?.parseError ?? null;
1195
+ if (parseError !== null)
1196
+ return this.#parseErrorBlocked(parseError);
1197
+ const slug = head !== null ? head.slug : (index.entryAt(rel)?.slug ?? null);
1198
+ // The four-way identity gate (present · legal · indexed · unique) is the ONE
1199
+ // `SlugIndex` judgment the pre-flight gate also reads — this carrier supplies
1200
+ // only the CDD_BLOCKED channel, never a second spelling of the rule.
1201
+ return this.#slugVerdictOf(index, rel, slug);
1202
+ }
1203
+ /** The text-carrier target's workspace key (the doc faces and `base`) — ONE read
1204
+ * face shared by the three work verbs' spec shapes and `base`: an unreadable
1205
+ * target, a missing `slug:`, an illegal value, or a slug the index judges
1206
+ * duplicated each render the CDD_BLOCKED station and return null (exit 1 at the
1207
+ * caller). The caller passes the document text it already holds — the identity
1208
+ * read never opens the file a second time. */
1209
+ #targetSlugText(index, rel, content) {
1111
1210
  // An unreadable target document declares no identity — the workspace key has
1112
1211
  // no source, so the dispatch face refuses on the SAME carrier as a missing
1113
1212
  // `slug:` (never a filename-derived directory).
@@ -1116,20 +1215,30 @@ export class Cli {
1116
1215
  const head = FrontMatterExtractor.split(content).head;
1117
1216
  const parseError = head.parseError;
1118
1217
  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);
1218
+ return this.#parseErrorBlocked(parseError);
1219
+ return this.#slugVerdictOf(index, rel, head.slug);
1220
+ }
1221
+ /** The identity carriers' shared tail — the ONE named-key verdict pair: the four-way
1222
+ * `SlugIndex` judgment and its CDD_BLOCKED channel. Both carriers differ only in
1223
+ * where their `slug` comes from (a plan read's front matter, a target document's
1224
+ * text); the verdict and the refusal are one fact, never two spellings. */
1225
+ #slugVerdictOf(index, rel, slug) {
1226
+ const verdict = index.slugVerdict(rel, slug);
1129
1227
  return verdict.kind === "accepted"
1130
1228
  ? verdict.slug
1131
1229
  : this.#slugBlocked(this.#words.slugRefusal(verdict));
1132
1230
  }
1231
+ /** The front-matter parse break's refusal — ONE message construction for the two
1232
+ * identity carriers (a broken head is unjudgeable whichever face reads it). The
1233
+ * bytes are the pre-existing `frontmatterParse` route word, unchanged. */
1234
+ #parseErrorBlocked(parseError) {
1235
+ return this.#slugBlocked(this.#words
1236
+ .routeWord("frontmatterParse")
1237
+ .replace("{reason}", parseError.reason)
1238
+ .replace("{line}", String(parseError.line))
1239
+ .replace("{column}", String(parseError.column))
1240
+ .replace("{source}", parseError.source));
1241
+ }
1133
1242
  /** Read a dispatch target's text — null when the file is absent or unreadable.
1134
1243
  * The null is NOT a degradation: every caller hands it to `#targetSlug`, which
1135
1244
  * refuses the target on the slug carrier (CDD_BLOCKED + exit 1). A document
@@ -1264,7 +1373,7 @@ export class Cli {
1264
1373
  // (and rejection carrier) the work verbs use. `base` carries no pre-flight gate,
1265
1374
  // so a missing / illegal / duplicated slug or an unreadable target stops HERE:
1266
1375
  // CDD_BLOCKED + exit 1 (never a filename-derived key).
1267
- const slug = this.#targetSlug(SlugIndex.build(repoRoot), planPath, this.#readTarget(root, planPath));
1376
+ const slug = this.#targetSlugText(SlugIndex.build(repoRoot), planPath, this.#readTarget(root, planPath));
1268
1377
  if (slug === null)
1269
1378
  return 1;
1270
1379
  // The workspace is not built here (P11 · §4.2): `base set` builds it through
package/dist/face/gate.js CHANGED
@@ -121,10 +121,13 @@ export class CliGate {
121
121
  }
122
122
  /** Render the task group brief into the workspace (the implement dispatch's input)
123
123
  * — the brief mirrors the current plan (its task sections + the `## Constraints`
124
- * section, re-extracted at every dispatch). */
125
- renderBrief(scene, parsed) {
124
+ * section, re-extracted at every dispatch). The document text and the parsed
125
+ * document arrive NARROWED: the caller (`Cli#runWork`'s `ready` branch) supplies
126
+ * both from the ONE plan read, so this face has no null branch — no `!`, no
127
+ * `?? ""` faking a read failure as an empty document. */
128
+ renderBrief(scene, parsed, text, doc) {
126
129
  const tasks = this.tasksOf(parsed);
127
- const content = this.#brief.render(scene.planText, tasks);
130
+ const content = this.#brief.render(text, doc, tasks);
128
131
  // The real run's workspace is built by the single write point (`Cli#runWork`'s
129
132
  // ensure, P11 · §4.2) BEFORE this render; the write still rides the workspace's
130
133
  // own text-write face (the `writeJson` mkdir-before-write pattern), never a
@@ -382,24 +382,25 @@ export class CliLifecycle {
382
382
  /** The plan tasks whose `Files` declaration names no path — the verification-wave
383
383
  * cell. The PLAN document is the only source (never the diff): an absent plan, a
384
384
  * plan path pointing at no document or an unreadable one declares no empty row, so
385
- * a wave can never read as verification on a plan this dispatch could not see. */
385
+ * a wave can never read as verification on a plan this dispatch could not see. A
386
+ * document the grammar refuses is the same shape: it declares no row either (the
387
+ * refusal leg speaks before the dispatch, and this cell never becomes a second,
388
+ * louder reporter of a broken plan). */
386
389
  #emptyFileTasks() {
387
390
  const planPath = this.#scene.planPath;
388
391
  if (planPath === null)
389
392
  return new Set();
390
- let content;
391
393
  try {
392
- content = readFileSync(planPath, "utf8");
394
+ const empty = new Set();
395
+ for (const block of this.#blocks.parse(readFileSync(planPath, "utf8"))) {
396
+ if (this.#blocks.filePathsOf(block).length === 0)
397
+ empty.add(block.id);
398
+ }
399
+ return empty;
393
400
  }
394
401
  catch {
395
402
  return new Set();
396
403
  }
397
- const empty = new Set();
398
- for (const block of this.#blocks.parse(content)) {
399
- if (this.#blocks.filePathsOf(block).length === 0)
400
- empty.add(block.id);
401
- }
402
- return empty;
403
404
  }
404
405
  /** The round IDENTITY the criterion judges from — its op / cycle / attempt and the
405
406
  * group baseline. Deliberately verdict-free AND path-free: the carrier a round
@@ -705,14 +706,23 @@ export class CliLifecycle {
705
706
  * plan-less scene and when the plan is unreadable. */
706
707
  #briefHashOf(frame) {
707
708
  const scene = this.#scene;
708
- if (frame.type !== "wave" || frame.target.kind !== "wave" || scene.planPath === null)
709
+ const plan = scene.plan;
710
+ if (frame.type !== "wave" || frame.target.kind !== "wave")
711
+ return null;
712
+ const text = plan.text();
713
+ const doc = plan.doc();
714
+ const planPath = plan.stationPath();
715
+ if (text === null || doc === null || planPath === null)
709
716
  return null;
710
717
  try {
711
- const plan = readFileSync(scene.planPath, "utf8");
712
- const body = this.#brief.taskBody(plan, frame.target.tasks);
713
- return scene.ledger.refs().briefRevision(this.#rel(scene.planPath), body).brief_hash;
718
+ const body = this.#brief.taskBody(text, doc, frame.target.tasks);
719
+ return scene.ledger.refs().briefRevision(this.#rel(planPath), body).brief_hash;
714
720
  }
715
721
  catch {
722
+ // The ONLY throw point left is the brief's own out-of-bounds gate
723
+ // (`task N not found in the plan` — a legal scene when the plan was amended
724
+ // after the wave compiled): the round then records no hash, the same failure
725
+ // face `Ledger#briefRevision` keeps.
716
726
  return null;
717
727
  }
718
728
  }
@@ -145,6 +145,21 @@ export const CAPSULE_WORDS = {
145
145
  "discard the ones that are broken",
146
146
  ],
147
147
  },
148
+ /** The plan-read rows (spec §2.1 · §2.4 · §2.7) — the vocabulary the `PlanRead`
149
+ * value emits: the two read-failure marks, the healthy-but-empty mark, the
150
+ * orphan mark, the program face's undeclared cell and the two orphan
151
+ * diagnostics.
152
+ * `planReadWord(cause)` reads only `io` / `syntax`; the remaining rows are
153
+ * peers, never members of the failure vocabulary. */
154
+ planRead: {
155
+ io: "! unreadable",
156
+ syntax: "! unparseable",
157
+ empty: "(empty plan)",
158
+ orphan: "! no-spec",
159
+ orphanSpec: "the plan's slug \"{slug}\" names no design spec — {specPath} is absent (every plan is written for one phase; add that phase spec or fix the plan's `slug:`)",
160
+ slugMissing: "the plan declares no `slug:` key — add `slug: <workspace-key>` to the plan's front-matter and re-run",
161
+ cellEmpty: "",
162
+ },
148
163
  /** The cut-short round's late-landing hint — every kill / timeout / crash message
149
164
  * carries it: the child may have written more after the engine stopped watching. */
150
165
  lateLanding: "a late write may land after the round was cut short — check the working tree before starting the review",
@@ -376,6 +391,42 @@ export class Words {
376
391
  return CAPSULE_WORDS.lateLanding;
377
392
  }
378
393
  // -------------------------------------------------------------------------
394
+ // plan-read — the `PlanRead` value's word port
395
+ // -------------------------------------------------------------------------
396
+ /** One read-failure mark (`io` / `syntax`) — the failure vocabulary, and only it. */
397
+ planReadWord(cause) {
398
+ return CAPSULE_WORDS.planRead[cause];
399
+ }
400
+ /** The healthy plan carrying no task block yet — never folded into the failure
401
+ * vocabulary (a healthy empty state is not a read failure). */
402
+ planEmptyWord() {
403
+ return CAPSULE_WORDS.planRead.empty;
404
+ }
405
+ /** The orphan mark the doc face, the program cell and the plan row fold into. */
406
+ planOrphanWord() {
407
+ return CAPSULE_WORDS.planRead.orphan;
408
+ }
409
+ /** The `spec-absent` orphan diagnostic — the plan's slug and the derived spec path,
410
+ * both filled here (the row lives in the table only). */
411
+ planOrphanSpec(slug, specPath) {
412
+ return CAPSULE_WORDS.planRead.orphanSpec
413
+ .replace("{slug}", slug)
414
+ .replace("{specPath}", specPath);
415
+ }
416
+ /** The `slug-absent` diagnostic — the plan parses but declares no identity key. */
417
+ planSlugMissing() {
418
+ return CAPSULE_WORDS.planRead.slugMissing;
419
+ }
420
+ /** The program face's undeclared cell — `""` belongs to that one semantic. */
421
+ get cellEmpty() {
422
+ return CAPSULE_WORDS.planRead.cellEmpty;
423
+ }
424
+ /** The stderr diagnostic prefix — delegated to the `warn` station row (one
425
+ * source, no second `CDD_WARN:` literal). */
426
+ get warnPrefix() {
427
+ return CAPSULE_WORDS.stations.warn;
428
+ }
429
+ // -------------------------------------------------------------------------
379
430
  // locale — the word-table locale face (the langs projection + the label rows)
380
431
  // -------------------------------------------------------------------------
381
432
  /** The locale key set — the word table's declared languages (the `langs`