@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.
@@ -83,6 +83,30 @@ export class MarkdownPrimitives {
83
83
  // ---------------------------------------------------------------------------
84
84
  // the DocType base — parse + projection consumption + chain root
85
85
  // ---------------------------------------------------------------------------
86
+ /**
87
+ * The document-syntax rejection — a structural break of a document's OWN grammar
88
+ * (a reserved task section declared twice today), thrown by the parse face and
89
+ * materialized as a `Finding` by the judgment face. It carries the three faces a
90
+ * finding needs (the anchored field, the one-line message and the actionable
91
+ * fix), so the consumer never re-derives them from a message string. It sits
92
+ * beside the `DocType` base because the parse face is its only thrower: a
93
+ * doc-type's grammar break is a value, never a bare `Error`.
94
+ */
95
+ export class DocSyntaxError extends Error {
96
+ /** The anchored field the break sits on (an anchor token or a section name). */
97
+ field;
98
+ /** The one-line finding message — what is structurally wrong. */
99
+ message;
100
+ /** The actionable fix. */
101
+ fix;
102
+ constructor(field, message, fix) {
103
+ super(message);
104
+ this.name = "DocSyntaxError";
105
+ this.field = field;
106
+ this.message = message;
107
+ this.fix = fix;
108
+ }
109
+ }
86
110
  /**
87
111
  * The abstract doc-type base. Each subclass binds its registry-derived projection
88
112
  * face (slices + shape) and implements parse — pure structural extraction into a
@@ -7,9 +7,10 @@
7
7
  // index over the declared strategy set — zero switch-case, zero hand-written
8
8
  // judgment branches in this module (the plan's coordinator semantics: the
9
9
  // polymorphic strategy family judges, the coordinator assembles).
10
+ var _a;
10
11
  import { Words } from "../face/words.js";
11
12
  import { declaredRegistries } from "./declare.js";
12
- import { docTypeParsers } from "./doc.js";
13
+ import { DocSyntaxError, docTypeParsers } from "./doc.js";
13
14
  import { NodeFs } from "./invariants.js";
14
15
  import { MarkdownTree } from "./markdown-tree.js";
15
16
  import { DOC_KEYS, Projector } from "./project.js";
@@ -53,7 +54,7 @@ export class Contract {
53
54
  /** The row source — the ONE canonicalize seam (split + canonicalize once). */
54
55
  #rowSource;
55
56
  constructor() {
56
- this.#strategies = Contract.policy();
57
+ this.#strategies = _a.policy();
57
58
  this.#projector = new Projector(declaredRegistries);
58
59
  this.#translator = new Translator(new Words());
59
60
  this.#rowSource = new RowSource(this.#translator);
@@ -83,7 +84,18 @@ export class Contract {
83
84
  * and JudgeContext.head (§2.2's delivery seam — the chain facts the head carries
84
85
  * are the same record the invariants judge). The source stays intact. */
85
86
  validate(input) {
86
- const context = this.#contextOf(input);
87
+ return this.#docFindings(input);
88
+ }
89
+ /** The doc-scope judgment body — the context construction (the ONLY caught step)
90
+ * plus every declared strategy of the input's doc key. */
91
+ #docFindings(input) {
92
+ let context;
93
+ try {
94
+ context = this.#contextOf(input);
95
+ }
96
+ catch (error) {
97
+ return [_a.#syntaxFinding(input, error)];
98
+ }
87
99
  const findings = [];
88
100
  for (const strategy of this.#strategies[input.docKey]) {
89
101
  findings.push(...strategy.evaluate(context));
@@ -95,7 +107,18 @@ export class Contract {
95
107
  * `scope: "ledger"` declaration applicable to the input's doc key. Two arguments,
96
108
  * one judgment — the doc-scope rules never run here (and vice versa). */
97
109
  validateLedger(input, ledger) {
98
- const context = this.#contextOf(input);
110
+ return this.#ledgerFindings(input, ledger);
111
+ }
112
+ /** The ledger-scope judgment body — the context construction (the ONLY caught
113
+ * step) plus every declared `scope: "ledger"` rule of the input's doc key. */
114
+ #ledgerFindings(input, ledger) {
115
+ let context;
116
+ try {
117
+ context = this.#contextOf(input);
118
+ }
119
+ catch (error) {
120
+ return [_a.#syntaxFinding(input, error)];
121
+ }
99
122
  const findings = [];
100
123
  for (const declaration of RULE_REGISTRY) {
101
124
  if (declaration.scope !== "ledger")
@@ -107,6 +130,23 @@ export class Contract {
107
130
  }
108
131
  return findings;
109
132
  }
133
+ /** The document-syntax face of a judgment — the parse face throws a typed
134
+ * `DocSyntaxError`, the judgment materializes exactly ONE Finding bound to the
135
+ * contract path (never a registered rule, never a new gate). The catch wraps the
136
+ * `#contextOf` call ALONE (spec §2.2's seam): it never catches the strategy loop,
137
+ * so a `DocSyntaxError` from a strategy is a programming break that rethrows
138
+ * instead of discarding the findings this judgment already collected. */
139
+ static #syntaxFinding(input, error) {
140
+ if (!(error instanceof DocSyntaxError))
141
+ throw error;
142
+ return {
143
+ path: input.path,
144
+ field: error.field,
145
+ message: error.message,
146
+ fix: error.fix,
147
+ kind: "doc-syntax",
148
+ };
149
+ }
110
150
  /** The assembled judgment context — the shared split/parse/translate seam of both
111
151
  * entries (one context construction, one canonicalize pass). */
112
152
  #contextOf(input) {
@@ -135,3 +175,4 @@ export class Contract {
135
175
  };
136
176
  }
137
177
  }
178
+ _a = Contract;
@@ -43,6 +43,17 @@ import { DOC_TYPE_VALUES } from "./declare.js";
43
43
  * The judge's policy composition and the board's declaration domain read THIS
44
44
  * tuple; a value drift is impossible (one array). */
45
45
  export const DOC_KEYS = DOC_TYPE_VALUES;
46
+ /** The task-heading accessor — a module-scope `this`-typed function expression, so
47
+ * every projection carries the SAME function instance (the projection-identity
48
+ * assertion compares two independent projections with `toEqual`, which compares
49
+ * function values by identity) while each call still reads that projection's own
50
+ * `slices` (the registry slice table stays the one fact source). An arrow would
51
+ * bind no `this`; a hand-written `RegExp` here would declare a second copy.
52
+ * `check:no-bare-functions` only matches line-leading `function`, so the const
53
+ * binding is inside the discipline. */
54
+ const taskHeadingPatternOf = function () {
55
+ return this.slices.find((slice) => slice.anchor === "### Task N:")?.valuePattern;
56
+ };
46
57
  /**
47
58
  * The projection carrier — the registered registries' single derivation surface.
48
59
  * Constructed on the declared registries (the domain's `declaredRegistries`),
@@ -195,7 +206,7 @@ export class Projector {
195
206
  : new RegExp(element.valuePattern),
196
207
  });
197
208
  }
198
- return { docType: registry.docType, slices };
209
+ return { docType: registry.docType, slices, taskHeadingPattern: taskHeadingPatternOf };
199
210
  }
200
211
  /** Project one registry onto its anchor-lexicon face. */
201
212
  #projectDocTokens(registry) {
@@ -8,6 +8,7 @@
8
8
  // The parse is split out of the tree facade (markdown-tree.ts) so the block
9
9
  // grammar, the document index and the selector engine each own one concern.
10
10
  import { TASK_ID_VALUE_PATTERN } from "./declare.js";
11
+ import { DocSyntaxError } from "./doc.js";
11
12
  /**
12
13
  * TaskBlockGrammar — the task-block structural constants. They live with the ONE
13
14
  * block parse, so the grammar has exactly one home.
@@ -276,8 +277,9 @@ export class TaskBlocksParser {
276
277
  for (const field of block.fields) {
277
278
  if (!TaskBlockGrammar.RESERVED.includes(field.key))
278
279
  continue;
280
+ const anchor = `#### ${field.key}`;
279
281
  if (seen.has(field.key)) {
280
- throw new Error(`task ${block.id} carries the reserved section "#### ${field.key}" more than once`);
282
+ throw new DocSyntaxError(anchor, `task ${block.id} carries the reserved section "${anchor}" more than once`, `keep one "${anchor}" section per task block — merge the duplicate bodies into the first one`);
281
283
  }
282
284
  seen.add(field.key);
283
285
  }
@@ -36,7 +36,6 @@
36
36
  // bare functions (the plan's zero-bare-function discipline).
37
37
  import { readFileSync } from "node:fs";
38
38
  import path from "node:path";
39
- import { PlanDocType } from "../contract/doc.js";
40
39
  import { FrontMatterExtractor } from "../contract/frontmatter.js";
41
40
  import { DOC_KEYS } from "../contract/project.js";
42
41
  import { ConfigLoader } from "../infra/config.js";
@@ -45,7 +44,6 @@ import { ENGINE_RUNTIME } from "../infra/runtime.js";
45
44
  import { SlugIndex } from "../infra/slug-index.js";
46
45
  import { Workspace, WorkspaceRoot } from "../infra/workspace.js";
47
46
  import { CarrierIntegrity } from "../session/carrier-integrity.js";
48
- import { TaskGraph } from "../session/graph.js";
49
47
  import { Ledger, RoundRecords } from "../session/ledger.js";
50
48
  import { PipelineFrontier } from "../session/pipeline.js";
51
49
  import { PROGRESS_LEGEND, PROGRESS_MARKERS } from "./graph-view.js";
@@ -433,20 +431,28 @@ export class BoardView {
433
431
  // -------------------------------------------------------------------------
434
432
  // the render face (spec §5.3) — the entry document → board layout + next render
435
433
  // -------------------------------------------------------------------------
436
- /** render(index, entry, repoRoot, words, host, channels, holding, next) — the
437
- * entry document's board (spec §3.1): the entry's declared `doc-type:` picks the
438
- * shape — `overall` → the program board, every other type → the node board. The
439
- * index supplies every related node (`program:` → overall; same slug → spec /
440
- * plan), so no filename grammar participates. `next` is the INJECTED `NextHop`
441
- * the node board's `next:` row renders (null = the board holds no derivable hop,
442
- * the `(none)` degradation). The argv channel is threaded into the shared
443
- * `RouteRenderer` (the SAME channel the capsule's route render reads, so the
434
+ /** render(readTable, plan, index, entry, repoRoot, words, host, channels, holding,
435
+ * next) — the entry document's board (spec §3.1): the entry's declared `doc-type:`
436
+ * picks the shape — `overall` → the program board, every other type → the node
437
+ * board. The index supplies every related node (`program:` → overall; same slug →
438
+ * spec / plan), so no filename grammar participates. `next` is the INJECTED
439
+ * `NextHop` the node board's `next:` row renders (null = the board holds no
440
+ * derivable hop, the `(none)` degradation). The argv channel is threaded into the
441
+ * shared `RouteRenderer` (the SAME channel the capsule's route render reads, so the
444
442
  * board's `next:` and the engine's `next:` literal compose their argv from ONE
445
443
  * flag-spelling source). A present doc line carrying a violation renders the
446
- * matching `(BLOCKED)` marker and the board exits 2 (spec §3.1 — the board's
447
- * reject face is exit 2, never the dispatch CDD_BLOCKED channel). Pure reads —
448
- * zero tree writes, zero ledger writes, zero child dispatch. */
449
- static render(index, entry, repoRoot, words, host, channels = {}, holding = { kind: "absent" }, next = null) {
444
+ * matching `(BLOCKED)` marker and the board exits 2 (spec §3.1 — the board's reject
445
+ * face is exit 2, never the dispatch CDD_BLOCKED channel). Pure reads — zero tree
446
+ * writes, zero ledger writes, zero child dispatch.
447
+ *
448
+ * `readTable` is the caller's ORDERED per-phase plan value table (spec §2.1 ·
449
+ * §2.4): `Cli#runBoard` builds it once, in `index.phaseSpecsOf` row order, so an
450
+ * overall board's every phase cell and every `CDD_WARN:` line reads the SAME value
451
+ * the wave segment reads. A single-document board is a table of length 1 — its one
452
+ * row is the argv face's read (solo `--plan`) or the derived face's (`--spec`).
453
+ * The board therefore holds no plan-reading seam of its own: the ONE read point is
454
+ * the injected `PlanSource`, and a value is never re-read here. */
455
+ static render(readTable, plan, index, entry, repoRoot, words, host, channels = {}, holding = { kind: "absent" }, next = null) {
450
456
  const lines = [`cdd board: ${entry.slug ?? "(none)"}`, ""];
451
457
  // The repo-basis value object — constructed ONCE at this boundary, the ONE
452
458
  // conversion exit the doc cells and the `next:` render normalize their embedded
@@ -455,8 +461,12 @@ export class BoardView {
455
461
  // one form).
456
462
  const root = new RepoRoot(repoRoot);
457
463
  const exitCode = entry.docType === "overall"
458
- ? BoardView.#programBoard(lines, index, entry, root)
459
- : BoardView.#nodeBoard(lines, index, entry, root, words, host, channels, holding, next);
464
+ ? BoardView.#programBoard(readTable, plan, lines, index, entry, root, words)
465
+ : BoardView.#nodeBoard(
466
+ // A node board is ONE document: the caller's single row. An empty table
467
+ // means no document was read at all — the seam's own undeclared value is
468
+ // that read result (no file is opened, so this mints no second read).
469
+ readTable[0] ?? plan.readFor(null), plan, lines, index, entry, root, words, host, channels, holding, next);
460
470
  lines.push("", PROGRESS_LEGEND.board);
461
471
  return { lines, exitCode };
462
472
  }
@@ -465,15 +475,18 @@ export class BoardView {
465
475
  * (`program:` → overall; same slug → spec / plan); a missing link renders
466
476
  * `(none)` and stays exit 0, while a violated line renders its marker and exits
467
477
  * 2. The repo-basis `root` is threaded alone (F2) — its `absolute` feeds the
468
- * fs-facing helpers, its value object the path renders. */
469
- static #nodeBoard(lines, index, entry, root, words, host, channels, holding, next) {
478
+ * fs-facing helpers, its value object the path renders. `read` is the caller's
479
+ * ONE plan value (spec §2.1): the plan row, the wave row and the `! no-spec`
480
+ * spec row all take their facts from it, so the document the board names and
481
+ * the document it read are one fact. */
482
+ static #nodeBoard(read, plan, lines, index, entry, root, words, host, channels, holding, next) {
470
483
  const repoRoot = root.absolute;
471
484
  const sources = BoardView.#nodeSources(index, entry);
472
485
  const nodeSlug = BoardView.#validSlug(entry);
473
- const ledger = nodeSlug === null ? null : BoardView.#ledgerOf(nodeSlug, repoRoot);
486
+ const ledger = nodeSlug === null ? null : BoardView.#ledgerOf(plan, nodeSlug, repoRoot);
474
487
  const progress = ledger?.readProgress() ?? null;
475
488
  const overallSlug = BoardView.#validSlug(sources.overall);
476
- const overallLedger = overallSlug === null ? null : BoardView.#ledgerOf(overallSlug, repoRoot);
489
+ const overallLedger = overallSlug === null ? null : BoardView.#ledgerOf(plan, overallSlug, repoRoot);
477
490
  const overallProgress = overallLedger?.readProgress() ?? null;
478
491
  // The tree's dispatch fact + the node workspace's orphan drafts + the node's
479
492
  // crashed rounds render before the line rows (a reader answers "is anyone working
@@ -487,25 +500,40 @@ export class BoardView {
487
500
  lines.push(row);
488
501
  if (holding.kind !== "absent" || orphans.length > 0 || crashes.length > 0)
489
502
  lines.push("");
503
+ // The two identity marks the read-value ladder consults (spec §2.7's first two
504
+ // layers): a non-empty mark keeps the EXISTING `#docCell` accounting and exit 2 —
505
+ // identity breakage outranks the read value, so neither the plan row nor the spec
506
+ // row asks a `PlanRead` accessor, and no `! no-spec` literal (the orphan fold or
507
+ // the degraded wave row) can appear beside a broken identity.
508
+ const specMark = BoardView.#entryMark(index, sources.spec, "identity") ??
509
+ (sources.programMissing ? MARK_PROGRAM_MISSING : null);
510
+ const planMark = BoardView.#entryMark(index, sources.plan, "plan");
511
+ const planIdentityClean = planMark === null;
512
+ const identityClean = planIdentityClean && specMark === null;
490
513
  const docRows = [
491
514
  {
492
515
  label: "overall",
493
516
  entry: sources.overall,
494
517
  line: BoardView.#lineOf("overall", "overall", sources.overall, overallProgress, overallLedger),
495
518
  mark: BoardView.#entryMark(index, sources.overall, "identity"),
519
+ override: null,
496
520
  },
497
521
  {
498
522
  label: "spec",
499
523
  entry: sources.spec,
500
524
  line: BoardView.#lineOf("spec", BoardView.#lineWordOf(sources.spec), sources.spec, progress, ledger),
501
- mark: BoardView.#entryMark(index, sources.spec, "identity") ??
502
- (sources.programMissing ? MARK_PROGRAM_MISSING : null),
525
+ mark: specMark,
526
+ // The reverse-lookup orphan's spec row (spec §2.7 ①): the identity-clean
527
+ // row bypasses `#entryMark` / `#docCell` accounting — landing in the mark
528
+ // channel would make it `blocked: true` and flip the orphan board to exit 2.
529
+ override: identityClean ? read.specLine(words) : null,
503
530
  },
504
531
  {
505
532
  label: "plan",
506
533
  entry: sources.plan,
507
534
  line: BoardView.#lineOf("plan", "plan", sources.plan, progress, ledger),
508
- mark: BoardView.#entryMark(index, sources.plan, "plan"),
535
+ mark: planMark,
536
+ override: BoardView.#planCellOf(read, sources.plan, planMark, words),
509
537
  },
510
538
  ];
511
539
  // The doc-name column is fixed-width: every name is padded to the widest one, so
@@ -515,24 +543,42 @@ export class BoardView {
515
543
  .map((row) => path.basename(row.entry.path).length));
516
544
  let blocked = false;
517
545
  for (const row of docRows) {
546
+ if (row.override !== null) {
547
+ lines.push(` ${row.label.padEnd(LABEL_WIDTH)}${row.override}`.trimEnd());
548
+ continue;
549
+ }
518
550
  const cell = BoardView.#docCell(row.entry, row.line, nameWidth, row.mark);
519
551
  lines.push(` ${row.label.padEnd(LABEL_WIDTH)}${cell.text}`.trimEnd());
520
552
  blocked ||= cell.blocked;
521
553
  }
522
- const waves = BoardView.#waveLines(sources.plan?.path ?? null, progress, ledger);
523
- if (waves.length === 0) {
524
- lines.push(` ${"wave".padEnd(LABEL_WIDTH)}(none)`);
554
+ // The doc face asks the READ first and the assembler second (spec §2.4): a
555
+ // degradation literal is the value's, the healthy row stays byte-identical to
556
+ // today's (`waves()` + `graph.report(ledger.closedWaves())` + `#rowRounds` +
557
+ // `LineCarriers`). `waves()` being empty is never the `(none)` signal. The ONE
558
+ // literal an identity break bans is `! no-spec` (`spec-absent` beside a rendered
559
+ // `(BLOCKED)` marker); `! unparseable` / `! unreadable` / `(empty plan)` still
560
+ // render, so a reader can tell a missing plan from a plan that does not read.
561
+ const specAbsent = read.orphan()?.cause === "spec-absent";
562
+ const degraded = specAbsent && !planIdentityClean ? null : read.degradedWaveRow(words);
563
+ if (degraded !== null) {
564
+ lines.push(` ${"wave".padEnd(LABEL_WIDTH)}${degraded}`);
525
565
  }
526
566
  else {
527
- // The marker column is fixed-width: every wave label is padded to the widest
528
- // label so the ✔/▶/○ markers align into one column (spec §5.3 · D40).
529
- const labelWidth = Math.max(...waves.map((wave) => wave.label.length));
530
- waves.forEach((wave, index) => {
531
- const prefix = index === 0 ? ` ${"wave".padEnd(LABEL_WIDTH)}` : " ".repeat(2 + LABEL_WIDTH);
532
- const cell = BoardView.summaryCell(wave.rounds, wave.carriers);
533
- const label = wave.label.padEnd(labelWidth);
534
- lines.push(`${prefix}${label} ${wave.marker ?? ""}${cell === "" ? "" : ` ${cell}`}`.trimEnd());
535
- });
567
+ const waves = BoardView.#waveLines(read, progress, ledger);
568
+ if (waves.length === 0) {
569
+ lines.push(` ${"wave".padEnd(LABEL_WIDTH)}(none)`);
570
+ }
571
+ else {
572
+ // The marker column is fixed-width: every wave label is padded to the widest
573
+ // label so the ✔/▶/○ markers align into one column (spec §5.3 · D40).
574
+ const labelWidth = Math.max(...waves.map((wave) => wave.label.length));
575
+ waves.forEach((wave, index) => {
576
+ const prefix = index === 0 ? ` ${"wave".padEnd(LABEL_WIDTH)}` : " ".repeat(2 + LABEL_WIDTH);
577
+ const cell = BoardView.summaryCell(wave.rounds, wave.carriers);
578
+ const label = wave.label.padEnd(labelWidth);
579
+ lines.push(`${prefix}${label} ${wave.marker ?? ""}${cell === "" ? "" : ` ${cell}`}`.trimEnd());
580
+ });
581
+ }
536
582
  }
537
583
  const branchLine = BoardView.#roundsLine("branch", "branch", progress, ledger);
538
584
  // The branch line's mark is the SAME drift-aware judgment its pipeline facts read
@@ -564,19 +610,27 @@ export class BoardView {
564
610
  * index (`program:` grouping — no overall child-list array). A phase row's primary
565
611
  * key is its `slug:`, annotated with the truncated `title:`; any overall/phase
566
612
  * violation renders its marker and exits 2 (spec §3.1 — zero silent fallback). */
567
- static #programBoard(lines, index, entry, root) {
613
+ static #programBoard(readTable, plan, lines, index, entry, root, words) {
568
614
  const repoRoot = root.absolute;
569
615
  const overallSlug = BoardView.#validSlug(entry);
570
- const ledger = overallSlug === null ? null : BoardView.#ledgerOf(overallSlug, repoRoot);
616
+ const ledger = overallSlug === null ? null : BoardView.#ledgerOf(plan, overallSlug, repoRoot);
571
617
  const overallLine = BoardView.#lineOf("overall", "overall", entry, ledger?.readProgress() ?? null, ledger);
572
618
  const overallDoc = BoardView.#docCell(entry, overallLine, path.basename(entry.path).length, BoardView.#entryMark(index, entry, "identity"));
573
619
  lines.push(` ${"overall".padEnd(LABEL_WIDTH)}${overallDoc.text}`);
574
620
  lines.push("");
575
621
  let blocked = overallDoc.blocked;
576
622
  const phases = overallSlug === null ? [] : index.phaseSpecsOf(overallSlug);
577
- for (const phase of phases) {
623
+ for (const [pos, phase] of phases.entries()) {
624
+ // The phase's ONE plan value: `Cli#runBoard` builds the table in THIS row order
625
+ // (spec §2.1), so the cell and the `CDD_WARN:` line can never describe two
626
+ // different documents. A short table is a BROKEN caller contract — the board
627
+ // never mints a second read to cover it (`PlanRead#document()` sets the same
628
+ // posture), so the invariant answers by throwing.
629
+ if (pos >= readTable.length)
630
+ throw new Error("cdd: the board's per-phase plan table is shorter than its phase list");
631
+ const read = readTable[pos];
578
632
  const phaseSlug = BoardView.#validSlug(phase);
579
- const phaseLedger = phaseSlug === null ? null : BoardView.#ledgerOf(phaseSlug, repoRoot);
633
+ const phaseLedger = phaseSlug === null ? null : BoardView.#ledgerOf(plan, phaseSlug, repoRoot);
580
634
  const phaseProgress = phaseLedger?.readProgress() ?? null;
581
635
  const specLine = BoardView.#lineOf("spec", "phase-spec", phase, phaseProgress, phaseLedger);
582
636
  const planEntry = phaseSlug === null ? null : index.planOf(phaseSlug);
@@ -590,8 +644,10 @@ export class BoardView {
590
644
  // The phase's wave summary token (spec §5.3): the wave segment's first wave
591
645
  // number + an ellipsis (`wave W1…`) — the phase's wave progress at a glance,
592
646
  // derived from the SAME wave segment the phase board renders (no second read).
593
- const waves = BoardView.#waveLines(planEntry?.path ?? null, phaseProgress, phaseLedger);
594
- const waveCell = waves.length === 0 ? "" : `${waves[0].label.split(" ")[0]}…`;
647
+ // The READ owns the degradation literal (spec §2.4): `cell(words)` answers
648
+ // `""` only for a true undeclared phase, and null hands the healthy cell back
649
+ // to today's derivation.
650
+ const waveCell = read.cell(words) ?? BoardView.#waveCellOf(read, phaseProgress, phaseLedger);
595
651
  const parts = [];
596
652
  const cells = [
597
653
  ["spec", BoardView.summaryCell(specLine.rounds, specLine.carriers)],
@@ -610,6 +666,44 @@ export class BoardView {
610
666
  lines.push(" next: done");
611
667
  return blocked ? 2 : 0;
612
668
  }
669
+ /** The plan row's cell content when the READ owns the row — the STATUS-FIRST
670
+ * ladder of spec §2.1 · §2.7 (identity → read value → index):
671
+ *
672
+ * ① `mark !== null` (`slug: invalid` / `duplicated` / `missing`) → null: the
673
+ * row goes back to `#docCell`, which renders the marker and keeps exit 2.
674
+ * Identity breakage outranks the read value, so no accessor is asked.
675
+ * ② a non-ready read, or the `spec-absent` orphan → `planLine(words)` — the repo
676
+ * relative path plus the mark, never `#docCell`. Reason: a plan whose BODY
677
+ * breaks the grammar is still an indexed document (the index reads front
678
+ * matter only), so an index-first ladder would render `name version · status`
679
+ * and drop the `! unparseable` mark this phase's AC pins. The `slug-absent`
680
+ * read lands here too and its accessor answers null — the row then falls back
681
+ * to `#docCell`'s `MARK_SLUG_MISSING`, exit 2 untouched.
682
+ * ③ a healthy `ready` whose path IS this node's indexed plan entry → null: the
683
+ * row is today's `#docCell` bytes. A healthy `ready` the index does not name
684
+ * as this node's plan renders the bare path instead of `(none)` or another
685
+ * document's header — the registered `slug`-is-identity consequence.
686
+ *
687
+ * Null therefore means "`#docCell` owns this row", never "nothing to show". */
688
+ static #planCellOf(read, planEntry, mark, words) {
689
+ if (mark !== null)
690
+ return null;
691
+ const unread = read.kind !== "ready" || read.orphan()?.cause === "spec-absent";
692
+ if (unread)
693
+ return read.planLine(words);
694
+ const docPath = read.path();
695
+ // `DocEntry.path` is the absolute syscall form and the read's path is repo
696
+ // relative — `rel` is the ONE comparable identity (`entryAt`'s own key).
697
+ const indexed = planEntry !== null && planEntry.rel === docPath;
698
+ return indexed ? null : read.planLine(words);
699
+ }
700
+ /** The healthy program-face wave cell — the wave segment's first wave number plus
701
+ * an ellipsis (`W1…`, spec §5.3), derived from the SAME wave segment the phase
702
+ * board renders. Only a `cell(words) === null` (healthy) value reaches here. */
703
+ static #waveCellOf(read, progress, ledger) {
704
+ const first = BoardView.#waveLines(read, progress, ledger)[0];
705
+ return first === undefined ? "" : `${first.label.split(" ")[0]}…`;
706
+ }
613
707
  /** The phase-spec's `program:` gate (spec §2.2): a phase-spec naming no overall
614
708
  * (or carrying no `program:` at all) is a hard cancellation of the node. */
615
709
  static #programMissing(index, entry) {
@@ -654,48 +748,44 @@ export class BoardView {
654
748
  return { text: cells.join(" "), blocked: false };
655
749
  }
656
750
  /** The node's ledger — the progress.json read face the render's closure/next
657
- * derivation consumes (each node reads its OWN workspace). */
658
- static #ledgerOf(nodeSlug, repoRoot) {
751
+ * derivation consumes (each node reads its OWN workspace). The plan read seam is
752
+ * the caller's per-command instance, threaded down unchanged: the board never
753
+ * mints a second `PlanSource`. */
754
+ static #ledgerOf(plan, nodeSlug, repoRoot) {
659
755
  const root = new WorkspaceRoot(repoRoot, ENGINE_RUNTIME.handoffNamespace.workspaceRoot);
660
- return new Ledger(new Workspace(root, nodeSlug), new ConfigLoader());
756
+ return new Ledger(new Workspace(root, nodeSlug), new ConfigLoader(), plan);
661
757
  }
662
- /** pipelineFacts(index, entry, root) — the board's FACTS about the pipeline (spec
663
- * §5.2): the node's ledger and the pipeline frontier's declared input (the spec
664
- * word and path, the plan path, the guarded plan read). The board reports facts
665
- * only — the per-face observations and the four face-order rules live in the
758
+ /** pipelineFacts(read, plan, index, entry, root) — the board's FACTS about the
759
+ * pipeline (spec §5.2): the node's ledger and the pipeline frontier's declared
760
+ * input (the spec word and path, the plan path, the plan read). The board reports
761
+ * facts only — the per-face observations and the four face-order rules live in the
666
762
  * session plane's `PipelineFrontier`. Null when the node holds no legal slug (no
667
- * workspace to observe). */
668
- static pipelineFacts(index, entry, root) {
763
+ * workspace to observe).
764
+ *
765
+ * `read` is the caller's ONE plan read (the same `PlanSource` instance): the
766
+ * frontier's graph input is the value's own `graph()`, and the declared `planPath`
767
+ * is that same value's `stationPath()` — the document the board read and the path
768
+ * the frontier receives are ONE fact, with no fallback to `index.planOf(slug)`.
769
+ * The wave segment reads the same value through `#waveLines`; the board has no
770
+ * second plan read point. */
771
+ static pipelineFacts(read, plan, index, entry, root) {
669
772
  const nodeSlug = BoardView.#validSlug(entry);
670
773
  if (nodeSlug === null)
671
774
  return null;
672
- const ledger = BoardView.#ledgerOf(nodeSlug, root.absolute);
775
+ const ledger = BoardView.#ledgerOf(plan, nodeSlug, root.absolute);
673
776
  const sources = BoardView.#nodeSources(index, entry);
674
777
  const specPath = sources.spec?.path ?? null;
675
- const planPath = sources.plan?.path ?? null;
778
+ // The path the frontier receives IS the path of the document this read opened —
779
+ // never a second index-derived candidate that could name another file.
780
+ const planPath = read.stationPath();
676
781
  // The identity line's OWN word — the document's DECLARED `doc-type:` — keys the
677
782
  // line and names the pipeline station (`single-spec` closes onto its `done` row).
678
783
  const specType = BoardView.#lineWordOf(sources.spec);
679
784
  return {
680
785
  ledger,
681
- input: { specType, specPath, planPath, planGraph: BoardView.planGraph(planPath) },
786
+ input: { specType, specPath, planPath, plan: read },
682
787
  };
683
788
  }
684
- /** The plan's task graph — the ONE guarded plan read behind the board's own wave
685
- * segment. `readFileSync` throwing on an unreadable plan is caught here: a null
686
- * plan path or an unreadable/absent file yields null, honoring the wave face's
687
- * "degradation, never a throw" contract. The pipeline frontier itself reads no
688
- * file — the composition root injects this read's result as its `planGraph` cell. */
689
- static planGraph(planPath) {
690
- if (planPath === null)
691
- return null;
692
- try {
693
- return new TaskGraph(new PlanDocType("plan").parse(readFileSync(planPath, "utf8").split("\n")));
694
- }
695
- catch {
696
- return null;
697
- }
698
- }
699
789
  /** The branch line — a docless line whose rounds ride the `branch` row. */
700
790
  static #roundsLine(label, key, progress, ledger) {
701
791
  const rounds = BoardView.#rowRounds(progress, key);
@@ -722,15 +812,19 @@ export class BoardView {
722
812
  /** The node's wave segment — one line per derived wave (its ✔/▶/○ marker rides the
723
813
  * SAME `TaskGraph.report(closedWaves())` read the board and the pre-flight gate
724
814
  * share — the same source GraphView renders from), the wave's own `progress.json`
725
- * row spread alongside. No plan → empty segment (degradation, never a throw). */
726
- static #waveLines(planPath, progress, ledger) {
727
- const graph = BoardView.planGraph(planPath);
815
+ * row spread alongside. The batch list is the READ's own `waves()` (spec §2.4) and
816
+ * the graph is only the `report(...)` input; both are the read's eager derivation
817
+ * (spec §2.1), never a second file read. A non-ready read has no graph and the
818
+ * segment is empty. */
819
+ static #waveLines(read, progress, ledger) {
820
+ const graph = read.graph();
728
821
  if (graph === null)
729
822
  return [];
823
+ const waves = read.waves();
730
824
  const report = graph.report(ledger === null ? new Set() : ledger.closedWaves());
731
825
  const done = new Set(report.done);
732
- const currentIndex = report.waves.findIndex((wave) => wave.some((id) => !done.has(id)));
733
- return report.waves.map((wave, index) => {
826
+ const currentIndex = waves.findIndex((wave) => wave.some((id) => !done.has(id)));
827
+ return waves.map((wave, index) => {
734
828
  const closed = wave.every((id) => done.has(id));
735
829
  const marker = closed
736
830
  ? PROGRESS_MARKERS.done
@@ -763,10 +857,18 @@ export class BoardView {
763
857
  // biome-ignore lint/complexity/noStaticOnlyClass: the board's assembly fact surface — the zero-bare-function discipline admits no standalone functions here.
764
858
  export class BoardNext {
765
859
  /** The board's ONE `NextHop` — null when the entry holds no legal slug (no
766
- * workspace to observe) or the board is the program board (cross-phase never
767
- * participates in next, spec §6.5). */
768
- static of(index, entry, root) {
769
- const facts = entry.docType === "overall" ? null : BoardView.pipelineFacts(index, entry, root);
860
+ * workspace to observe), when the board is the program board (cross-phase never
861
+ * participates in next, spec §6.5), or when the plan read carries no evidence to
862
+ * route on (spec §2.3): an `unreadable` plan and a `spec-absent` orphan
863
+ * short-circuit to the existing hop-less shape (` next: (none)`, no `reason:`
864
+ * row). The predicate is the SAME pair §2.3 uses, never a third condition;
865
+ * `undeclared` is NOT in it ("spec written, no plan yet" is the standing
866
+ * `kairos:cdd-plan` route) and `slug-absent` is not either (the identity channel
867
+ * owns its exit code). */
868
+ static of(read, plan, index, entry, root) {
869
+ if (read.kind === "unreadable" || read.orphan()?.cause === "spec-absent")
870
+ return null;
871
+ const facts = entry.docType === "overall" ? null : BoardView.pipelineFacts(read, plan, index, entry, root);
770
872
  return facts === null ? null : BoardNext.#hopOf(facts, root);
771
873
  }
772
874
  /** The session plane's ONE assembly, called with the board's facts and the face