@oscaner-skills/cdd-engine 4.10.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.
@@ -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";
@@ -75,6 +73,51 @@ const PHASE_TITLE_MAX = 60;
75
73
  /** The label column of the board's line rows — ` ` + the label padded to this
76
74
  * width (`overall` is the longest verb at 7), so every value starts in one column. */
77
75
  const LABEL_WIDTH = 9;
76
+ /** One board line's carrier facts — the `+N` count's WHOLE read face (spec §2.7 ·
77
+ * §2.10). The record's path comes from the ledger's ONE accessor, bound to this
78
+ * line's type + key; ownership excludes a legacy record whose path a later round of
79
+ * the same line overwrote (present facts, no comparison); the read is the ONE checked
80
+ * seam against the record's own digest. A line with no ledger (no workspace to
81
+ * observe) resolves no path, so every record counts zero. */
82
+ export class LineCarriers {
83
+ #records;
84
+ #pathOf;
85
+ constructor(records, pathOf) {
86
+ this.#records = records;
87
+ this.#pathOf = pathOf;
88
+ }
89
+ /** The judgment over one line's records, with the caller supplying each record's
90
+ * carrier path — the board's own derivation is `ofLedger` below. */
91
+ static of(records, pathOf) {
92
+ return new LineCarriers(records, pathOf);
93
+ }
94
+ /** The board's derivation — the ledger's ONE accessor, bound to this line's type +
95
+ * key. No ledger (no workspace to observe) resolves no path for every record. */
96
+ static ofLedger(ledger, type, key, records) {
97
+ return LineCarriers.of(records, (record) => ledger?.carrierPathOf(type, key, record) ?? "");
98
+ }
99
+ /** One record's graded findings count — zero for a record that resolves no path or
100
+ * whose path a later round overwrote; a tampered carrier THROWS (the checked read). */
101
+ countOf(record) {
102
+ const path = this.#pathOf(record);
103
+ if (path === "" || !RoundRecords.ownerOf(this.#records, record, this.#pathOf))
104
+ return 0;
105
+ const text = CarrierIntegrity.read(path, record.carrierDigest ?? null);
106
+ return text === null ? 0 : LineCarriers.#findingsCountOf(text);
107
+ }
108
+ /** The `findings` array length of one carrier's bytes — zero when the payload holds
109
+ * none (a work-plane carrier declares no findings) or is not JSON. */
110
+ static #findingsCountOf(text) {
111
+ try {
112
+ const value = JSON.parse(text);
113
+ const findings = value?.findings;
114
+ return Array.isArray(findings) ? findings.length : 0;
115
+ }
116
+ catch {
117
+ return 0;
118
+ }
119
+ }
120
+ }
78
121
  /**
79
122
  * BoardView — the entry-document → board face. The identity index (`SlugIndex`)
80
123
  * is the ONLY node source: the entry document's declared `doc-type:` picks the
@@ -189,14 +232,17 @@ export class BoardView {
189
232
  /** One doc line — the header facts read from the indexed entry + the row's round
190
233
  * RECORDS keyed by the line's `progress.json` key, resolved with the line's DECLARED
191
234
  * word as the retired-key alias basis (a charter's pre-rename `spec` row is its own
192
- * `overall` line). */
193
- static #lineOf(label, key, entry, progress) {
235
+ * `overall` line). The ledger is the one that OWNS `progress` — a node board reads
236
+ * the overall line from the program's workspace, never the node's. */
237
+ static #lineOf(label, key, entry, progress, ledger) {
238
+ const rounds = BoardView.#rowRounds(progress, key, entry?.docType ?? null);
194
239
  return {
195
240
  label,
196
241
  version: entry?.version ?? null,
197
242
  status: entry?.status ?? null,
198
243
  docType: entry?.docType ?? null,
199
- rounds: BoardView.#rowRounds(progress, key, entry?.docType ?? null),
244
+ rounds,
245
+ carriers: LineCarriers.ofLedger(ledger, key, key, rounds),
200
246
  marker: null,
201
247
  };
202
248
  }
@@ -205,24 +251,24 @@ export class BoardView {
205
251
  * the ANOMALY face expands one token per failed attempt. Tokens are verb-major in
206
252
  * `VERB_ORDER`, a verb's success token before its failures, those in stored order. The
207
253
  * range form (`review 1–10 ✓`) never renders: the aggregation IS the count. */
208
- static summaryCell(records) {
254
+ static summaryCell(records, carriers) {
209
255
  const tokens = [];
210
256
  const extra = [...new Set(records.map((record) => record.op))].filter((op) => !VERB_ORDER.includes(op));
211
257
  for (const verb of [...VERB_ORDER, ...extra]) {
212
258
  const faces = BoardView.#judgementRuns(records.filter((record) => record.op === verb));
213
- tokens.push(...BoardView.#verbTokens(verb, faces));
259
+ tokens.push(...BoardView.#verbTokens(verb, faces, carriers));
214
260
  }
215
261
  return tokens.join(" · ");
216
262
  }
217
263
  /** One verb's tokens — its success token (absent at zero successes) followed by one
218
264
  * token per failed attempt, so a failure never drifts to the line's tail (P24 §12). */
219
- static #verbTokens(verb, faces) {
265
+ static #verbTokens(verb, faces, carriers) {
220
266
  const tokens = [];
221
- const success = BoardView.#successToken(verb, faces);
267
+ const success = BoardView.#successToken(verb, faces, carriers);
222
268
  if (success !== null)
223
269
  tokens.push(success);
224
270
  for (const record of faces.failures) {
225
- tokens.push(BoardView.#failureToken(verb, record, faces.successes));
271
+ tokens.push(BoardView.#failureToken(verb, record, faces.successes, carriers));
226
272
  }
227
273
  return tokens;
228
274
  }
@@ -232,7 +278,7 @@ export class BoardView {
232
278
  * `{succeeded}/{attempts}` ratio — never a superscript — once it has one (P24 §12).
233
279
  * Its `+N` counts the SUCCESS records' carriers alone; a failed attempt's findings
234
280
  * already ride that attempt's own token. */
235
- static #successToken(verb, faces) {
281
+ static #successToken(verb, faces, carriers) {
236
282
  const count = faces.successes.length;
237
283
  if (count === 0)
238
284
  return null;
@@ -240,49 +286,30 @@ export class BoardView {
240
286
  const body = faces.failures.length === 0
241
287
  ? `${count}${BoardView.attemptSuffix(last)}`
242
288
  : `${count}/${count + faces.failures.length}`;
243
- return BoardView.#summaryToken(verb, body, JUDGEMENT_MARKERS.passed, faces.successes);
289
+ return BoardView.#summaryToken(verb, body, JUDGEMENT_MARKERS.passed, faces.successes, carriers);
244
290
  }
245
291
  /** One failed attempt's token — `{verb} {cycle}{aN} ✗{+N}`, the cycle naming the round
246
292
  * that failed rather than a re-counted segment, and `✗→✓` when the SAME cycle's next
247
293
  * attempt (`attempt + 1`) completed: recovery reads exactly that one edge — a later
248
294
  * cycle's success and a further same-cycle attempt are historical failures. The `+N`
249
295
  * counts this record's own carrier alone, never erased by a later success (P24 §12). */
250
- static #failureToken(verb, record, successes) {
296
+ static #failureToken(verb, record, successes, carriers) {
251
297
  const recovered = successes.some((other) => other.cycle === record.cycle && other.attempt === record.attempt + 1);
252
298
  const mark = recovered ? JUDGEMENT_MARKERS.recovered : JUDGEMENT_MARKERS.failed;
253
299
  const body = `${record.cycle}${BoardView.attemptSuffix(record)}`;
254
- return BoardView.#summaryToken(verb, body, mark, [record]);
300
+ return BoardView.#summaryToken(verb, body, mark, [record], carriers);
255
301
  }
256
302
  /** One token of a verb's success face or of one failed attempt, `{verb} {body} {mark}`
257
303
  * (P24 §12). The `+N` suffix counts the run's graded FINDINGS, read from each round's
258
- * own carrier (`carrierPath` → the handoff's `findings` array, spec §5.3) — never the
259
- * round's hard/soft contract violations, which are a different fact. A record with no
260
- * carrier (a legacy row, or a work-plane round whose carrier declares no findings)
261
- * contributes zero. */
262
- static #summaryToken(verb, body, mark, run) {
263
- const findings = run.reduce((total, record) => total + BoardView.#findingsCountOf(record), 0);
304
+ * own carrier (`LineCarriers` — the derived path + the record's own digest, spec
305
+ * §2.10) — never the round's hard/soft contract violations, which are a different
306
+ * fact. A record that resolves no carrier (a legacy row, or a work-plane round whose
307
+ * carrier declares no findings) contributes zero. */
308
+ static #summaryToken(verb, body, mark, run, carriers) {
309
+ const findings = run.reduce((total, record) => total + carriers.countOf(record), 0);
264
310
  const suffix = findings === 0 ? "" : `+${findings}`;
265
311
  return `${verb} ${body} ${mark}${suffix}`;
266
312
  }
267
- /** One round's findings count — the `findings` array length of the carrier the round
268
- * persisted (the judge plane's declared field). Zero when the record carries no
269
- * carrier path or the file is absent (present facts only). P31 §2.2 — the read goes
270
- * through the ONE checked seam: a carrier whose bytes no longer match the recorded
271
- * digest THROWS (`carrier-mismatch` rides the CLI's blocked channel), never a
272
- * silent zero. */
273
- static #findingsCountOf(record) {
274
- const text = CarrierIntegrity.readFor(record);
275
- if (text === null)
276
- return 0;
277
- try {
278
- const value = JSON.parse(text);
279
- const findings = value?.findings;
280
- return Array.isArray(findings) ? findings.length : 0;
281
- }
282
- catch {
283
- return 0;
284
- }
285
- }
286
313
  /** attemptSuffix(record) — the re-dispatch superscript: `attempt === 1` renders
287
314
  * nothing (an `a1` never appears), otherwise `a{attempt}`. */
288
315
  static attemptSuffix(record) {
@@ -328,7 +355,7 @@ export class BoardView {
328
355
  * bytes the preview face and the gate print (one vocabulary, never a board
329
356
  * literal). The orphan rows are the drafts no recorded round owns — the board
330
357
  * lists them, never writes or deletes them. */
331
- static inFlightRows(state, orphans, words) {
358
+ static inFlightRows(state, orphans, words, crashes = []) {
332
359
  const rows = [];
333
360
  if (state.kind === "held") {
334
361
  const record = state.record;
@@ -352,25 +379,80 @@ export class BoardView {
352
379
  }
353
380
  for (const orphan of orphans)
354
381
  rows.push(` orphan: ${orphan} — no recorded round owns it`);
382
+ rows.push(...crashes);
355
383
  return rows;
356
384
  }
385
+ /** crashedRows(records) — the node's CRASHED rounds as ONE board line, one token per
386
+ * round: `crashed: {op} {cycle}·a{attempt} {cause} · {op} {cycle}·a{attempt} {cause}`.
387
+ * A round crashed when its booked verdict withheld the target action AND at least one
388
+ * of its violations is HARD; the cause is the FIRST hard entry in record order — the
389
+ * round's own narrative never re-orders it. The tokens read `(cycle, attempt)` — the
390
+ * session's own sequence, never the progress file's write order (spec §2.13) — and one
391
+ * round identity yields ONE token even when a recovery re-booked it. The ` · ` is the
392
+ * INTER-TOKEN separator alone (a cause stays space-separated, so a token never splits),
393
+ * and zero crashed rounds render no line at all. The row is an observation only: it
394
+ * joins no aggregation, the counts, the legend and the `next:` hop stay byte-identical
395
+ * with and without it (spec §5.3 — a failed round is never hidden, never re-counted). */
396
+ static crashedRows(records) {
397
+ const tokens = BoardView.#crashTokens(records);
398
+ return tokens.length === 0 ? [] : [` crashed: ${tokens.join(" · ")}`];
399
+ }
400
+ /** The crashed rounds as ordered, de-duplicated tokens — the ONE line's cells. */
401
+ static #crashTokens(records) {
402
+ const seen = new Set();
403
+ const tokens = [];
404
+ for (const record of BoardView.#byRound(records.filter((entry) => BoardView.#crashed(entry)))) {
405
+ const identity = `${record.op}:${record.cycle}:${record.attempt}`;
406
+ if (seen.has(identity))
407
+ continue;
408
+ seen.add(identity);
409
+ const cause = record.violations.find((violation) => violation.grade === "hard");
410
+ tokens.push(`${record.op} ${record.cycle}·a${record.attempt} ${cause.cause}`);
411
+ }
412
+ return tokens;
413
+ }
414
+ /** The records in board order — `(cycle, attempt)`, the round identity's own sequence.
415
+ * A copy: the caller's array (a progress row's records) stays untouched. */
416
+ static #byRound(records) {
417
+ return [...records].sort((left, right) => left.cycle - right.cycle || left.attempt - right.attempt);
418
+ }
419
+ /** Whether one round crashed — the verdict withheld the target action AND a HARD
420
+ * violation is booked (a soft-only failure stays the anomaly face's `✗` token). */
421
+ static #crashed(record) {
422
+ return (record.verdict?.targetAction === false &&
423
+ record.violations.some((violation) => violation.grade === "hard"));
424
+ }
425
+ /** The node's every booked round — one flat read over the progress rows' records
426
+ * (the normalizer folds the legacy forms), so the crash scan needs no key grammar.
427
+ * An absent progress row carries no rounds. */
428
+ static #nodeRecordsOf(progress) {
429
+ return progress === null ? [] : progress.waves.flatMap((row) => RoundRecords.of(row));
430
+ }
357
431
  // -------------------------------------------------------------------------
358
432
  // the render face (spec §5.3) — the entry document → board layout + next render
359
433
  // -------------------------------------------------------------------------
360
- /** render(index, entry, repoRoot, words, host, channels, holding, next) — the
361
- * entry document's board (spec §3.1): the entry's declared `doc-type:` picks the
362
- * shape — `overall` → the program board, every other type → the node board. The
363
- * index supplies every related node (`program:` → overall; same slug → spec /
364
- * plan), so no filename grammar participates. `next` is the INJECTED `NextHop`
365
- * the node board's `next:` row renders (null = the board holds no derivable hop,
366
- * the `(none)` degradation). The argv channel is threaded into the shared
367
- * `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
368
442
  * board's `next:` and the engine's `next:` literal compose their argv from ONE
369
443
  * flag-spelling source). A present doc line carrying a violation renders the
370
- * matching `(BLOCKED)` marker and the board exits 2 (spec §3.1 — the board's
371
- * reject face is exit 2, never the dispatch CDD_BLOCKED channel). Pure reads —
372
- * zero tree writes, zero ledger writes, zero child dispatch. */
373
- 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) {
374
456
  const lines = [`cdd board: ${entry.slug ?? "(none)"}`, ""];
375
457
  // The repo-basis value object — constructed ONCE at this boundary, the ONE
376
458
  // conversion exit the doc cells and the `next:` render normalize their embedded
@@ -379,8 +461,12 @@ export class BoardView {
379
461
  // one form).
380
462
  const root = new RepoRoot(repoRoot);
381
463
  const exitCode = entry.docType === "overall"
382
- ? BoardView.#programBoard(lines, index, entry, root)
383
- : 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);
384
470
  lines.push("", PROGRESS_LEGEND.board);
385
471
  return { lines, exitCode };
386
472
  }
@@ -389,41 +475,65 @@ export class BoardView {
389
475
  * (`program:` → overall; same slug → spec / plan); a missing link renders
390
476
  * `(none)` and stays exit 0, while a violated line renders its marker and exits
391
477
  * 2. The repo-basis `root` is threaded alone (F2) — its `absolute` feeds the
392
- * fs-facing helpers, its value object the path renders. */
393
- 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) {
394
483
  const repoRoot = root.absolute;
395
484
  const sources = BoardView.#nodeSources(index, entry);
396
485
  const nodeSlug = BoardView.#validSlug(entry);
397
- const ledger = nodeSlug === null ? null : BoardView.#ledgerOf(nodeSlug, repoRoot);
398
- // The tree's dispatch fact + the node workspace's orphan drafts render before the
399
- // line rows (a reader answers "is anyone working here?" before reading progress).
486
+ const ledger = nodeSlug === null ? null : BoardView.#ledgerOf(plan, nodeSlug, repoRoot);
487
+ const progress = ledger?.readProgress() ?? null;
488
+ const overallSlug = BoardView.#validSlug(sources.overall);
489
+ const overallLedger = overallSlug === null ? null : BoardView.#ledgerOf(plan, overallSlug, repoRoot);
490
+ const overallProgress = overallLedger?.readProgress() ?? null;
491
+ // The tree's dispatch fact + the node workspace's orphan drafts + the node's
492
+ // crashed rounds render before the line rows (a reader answers "is anyone working
493
+ // here?" before reading progress).
400
494
  const orphans = ledger?.orphanHandoffs() ?? [];
401
- for (const row of BoardView.inFlightRows(holding, orphans, words))
495
+ // The node's OWN rounds — the overall document's records belong to the program
496
+ // board, never to this node's crash observation (a parent's failed round is not
497
+ // this node's work). `crashedRows` dedupes by round identity itself.
498
+ const crashes = BoardView.crashedRows(BoardView.#nodeRecordsOf(progress));
499
+ for (const row of BoardView.inFlightRows(holding, orphans, words, crashes))
402
500
  lines.push(row);
403
- if (holding.kind !== "absent" || orphans.length > 0)
501
+ if (holding.kind !== "absent" || orphans.length > 0 || crashes.length > 0)
404
502
  lines.push("");
405
- const progress = ledger?.readProgress() ?? null;
406
- const overallSlug = BoardView.#validSlug(sources.overall);
407
- const overallProgress = overallSlug === null ? null : BoardView.#ledgerOf(overallSlug, repoRoot).readProgress();
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;
408
513
  const docRows = [
409
514
  {
410
515
  label: "overall",
411
516
  entry: sources.overall,
412
- line: BoardView.#lineOf("overall", "overall", sources.overall, overallProgress),
517
+ line: BoardView.#lineOf("overall", "overall", sources.overall, overallProgress, overallLedger),
413
518
  mark: BoardView.#entryMark(index, sources.overall, "identity"),
519
+ override: null,
414
520
  },
415
521
  {
416
522
  label: "spec",
417
523
  entry: sources.spec,
418
- line: BoardView.#lineOf("spec", BoardView.#lineWordOf(sources.spec), sources.spec, progress),
419
- mark: BoardView.#entryMark(index, sources.spec, "identity") ??
420
- (sources.programMissing ? MARK_PROGRAM_MISSING : null),
524
+ line: BoardView.#lineOf("spec", BoardView.#lineWordOf(sources.spec), sources.spec, progress, ledger),
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,
421
530
  },
422
531
  {
423
532
  label: "plan",
424
533
  entry: sources.plan,
425
- line: BoardView.#lineOf("plan", "plan", sources.plan, progress),
426
- mark: BoardView.#entryMark(index, sources.plan, "plan"),
534
+ line: BoardView.#lineOf("plan", "plan", sources.plan, progress, ledger),
535
+ mark: planMark,
536
+ override: BoardView.#planCellOf(read, sources.plan, planMark, words),
427
537
  },
428
538
  ];
429
539
  // The doc-name column is fixed-width: every name is padded to the widest one, so
@@ -433,26 +543,44 @@ export class BoardView {
433
543
  .map((row) => path.basename(row.entry.path).length));
434
544
  let blocked = false;
435
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
+ }
436
550
  const cell = BoardView.#docCell(row.entry, row.line, nameWidth, row.mark);
437
551
  lines.push(` ${row.label.padEnd(LABEL_WIDTH)}${cell.text}`.trimEnd());
438
552
  blocked ||= cell.blocked;
439
553
  }
440
- const waves = BoardView.#waveLines(sources.plan?.path ?? null, progress, ledger);
441
- if (waves.length === 0) {
442
- 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}`);
443
565
  }
444
566
  else {
445
- // The marker column is fixed-width: every wave label is padded to the widest
446
- // label so the ✔/▶/○ markers align into one column (spec §5.3 · D40).
447
- const labelWidth = Math.max(...waves.map((wave) => wave.label.length));
448
- waves.forEach((wave, index) => {
449
- const prefix = index === 0 ? ` ${"wave".padEnd(LABEL_WIDTH)}` : " ".repeat(2 + LABEL_WIDTH);
450
- const cell = BoardView.summaryCell(wave.rounds);
451
- const label = wave.label.padEnd(labelWidth);
452
- lines.push(`${prefix}${label} ${wave.marker ?? ""}${cell === "" ? "" : ` ${cell}`}`.trimEnd());
453
- });
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
+ }
454
582
  }
455
- const branchLine = BoardView.#roundsLine("branch", "branch", progress);
583
+ const branchLine = BoardView.#roundsLine("branch", "branch", progress, ledger);
456
584
  // The branch line's mark is the SAME drift-aware judgment its pipeline facts read
457
585
  // (`Ledger#lineStateAt`, identity document = the plan): a drifted plan reopens the
458
586
  // branch face, so the mark can never print `✔ closed` while `next:` names the
@@ -463,7 +591,7 @@ export class BoardView {
463
591
  : branchState === "reopened"
464
592
  ? `${PROGRESS_MARKERS.current} open`
465
593
  : `${PROGRESS_MARKERS.pending} open`;
466
- const branchRounds = BoardView.summaryCell(branchLine.rounds);
594
+ const branchRounds = BoardView.summaryCell(branchLine.rounds, branchLine.carriers);
467
595
  lines.push(` ${"branch".padEnd(LABEL_WIDTH)}${branchMark}${branchRounds === "" ? "" : ` ${branchRounds}`}`.trimEnd());
468
596
  lines.push("");
469
597
  if (next === null) {
@@ -482,24 +610,32 @@ export class BoardView {
482
610
  * index (`program:` grouping — no overall child-list array). A phase row's primary
483
611
  * key is its `slug:`, annotated with the truncated `title:`; any overall/phase
484
612
  * violation renders its marker and exits 2 (spec §3.1 — zero silent fallback). */
485
- static #programBoard(lines, index, entry, root) {
613
+ static #programBoard(readTable, plan, lines, index, entry, root, words) {
486
614
  const repoRoot = root.absolute;
487
615
  const overallSlug = BoardView.#validSlug(entry);
488
- const ledger = overallSlug === null ? null : BoardView.#ledgerOf(overallSlug, repoRoot);
489
- const overallLine = BoardView.#lineOf("overall", "overall", entry, ledger?.readProgress() ?? null);
616
+ const ledger = overallSlug === null ? null : BoardView.#ledgerOf(plan, overallSlug, repoRoot);
617
+ const overallLine = BoardView.#lineOf("overall", "overall", entry, ledger?.readProgress() ?? null, ledger);
490
618
  const overallDoc = BoardView.#docCell(entry, overallLine, path.basename(entry.path).length, BoardView.#entryMark(index, entry, "identity"));
491
619
  lines.push(` ${"overall".padEnd(LABEL_WIDTH)}${overallDoc.text}`);
492
620
  lines.push("");
493
621
  let blocked = overallDoc.blocked;
494
622
  const phases = overallSlug === null ? [] : index.phaseSpecsOf(overallSlug);
495
- 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];
496
632
  const phaseSlug = BoardView.#validSlug(phase);
497
- const phaseLedger = phaseSlug === null ? null : BoardView.#ledgerOf(phaseSlug, repoRoot);
633
+ const phaseLedger = phaseSlug === null ? null : BoardView.#ledgerOf(plan, phaseSlug, repoRoot);
498
634
  const phaseProgress = phaseLedger?.readProgress() ?? null;
499
- const specLine = BoardView.#lineOf("spec", "phase-spec", phase, phaseProgress);
635
+ const specLine = BoardView.#lineOf("spec", "phase-spec", phase, phaseProgress, phaseLedger);
500
636
  const planEntry = phaseSlug === null ? null : index.planOf(phaseSlug);
501
- const planLine = BoardView.#lineOf("plan", "plan", planEntry, phaseProgress);
502
- const branchLine = BoardView.#roundsLine("branch", "branch", phaseProgress);
637
+ const planLine = BoardView.#lineOf("plan", "plan", planEntry, phaseProgress, phaseLedger);
638
+ const branchLine = BoardView.#roundsLine("branch", "branch", phaseProgress, phaseLedger);
503
639
  const mark = BoardView.#entryMark(index, phase, "identity") ??
504
640
  (BoardView.#programMissing(index, phase) ? MARK_PROGRAM_MISSING : null);
505
641
  const planMark = BoardView.#entryMark(index, planEntry, "plan");
@@ -508,14 +644,16 @@ export class BoardView {
508
644
  // The phase's wave summary token (spec §5.3): the wave segment's first wave
509
645
  // number + an ellipsis (`wave W1…`) — the phase's wave progress at a glance,
510
646
  // derived from the SAME wave segment the phase board renders (no second read).
511
- const waves = BoardView.#waveLines(planEntry?.path ?? null, phaseProgress, phaseLedger);
512
- 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);
513
651
  const parts = [];
514
652
  const cells = [
515
- ["spec", BoardView.summaryCell(specLine.rounds)],
516
- ["plan", BoardView.summaryCell(planLine.rounds)],
653
+ ["spec", BoardView.summaryCell(specLine.rounds, specLine.carriers)],
654
+ ["plan", BoardView.summaryCell(planLine.rounds, planLine.carriers)],
517
655
  ["wave", waveCell],
518
- ["branch", BoardView.summaryCell(branchLine.rounds)],
656
+ ["branch", BoardView.summaryCell(branchLine.rounds, branchLine.carriers)],
519
657
  ];
520
658
  for (const [key, cell] of cells)
521
659
  if (cell !== "")
@@ -528,6 +666,44 @@ export class BoardView {
528
666
  lines.push(" next: done");
529
667
  return blocked ? 2 : 0;
530
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
+ }
531
707
  /** The phase-spec's `program:` gate (spec §2.2): a phase-spec naming no overall
532
708
  * (or carrying no `program:` at all) is a hard cancellation of the node. */
533
709
  static #programMissing(index, entry) {
@@ -566,62 +742,60 @@ export class BoardView {
566
742
  const cells = [name];
567
743
  if (meta !== "")
568
744
  cells.push(meta);
569
- const rounds = BoardView.summaryCell(line.rounds);
745
+ const rounds = BoardView.summaryCell(line.rounds, line.carriers);
570
746
  if (rounds !== "")
571
747
  cells.push(rounds);
572
748
  return { text: cells.join(" "), blocked: false };
573
749
  }
574
750
  /** The node's ledger — the progress.json read face the render's closure/next
575
- * derivation consumes (each node reads its OWN workspace). */
576
- 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) {
577
755
  const root = new WorkspaceRoot(repoRoot, ENGINE_RUNTIME.handoffNamespace.workspaceRoot);
578
- return new Ledger(new Workspace(root, nodeSlug), new ConfigLoader());
756
+ return new Ledger(new Workspace(root, nodeSlug), new ConfigLoader(), plan);
579
757
  }
580
- /** pipelineFacts(index, entry, root) — the board's FACTS about the pipeline (spec
581
- * §5.2): the node's ledger and the pipeline frontier's declared input (the spec
582
- * word and path, the plan path, the guarded plan read). The board reports facts
583
- * 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
584
762
  * session plane's `PipelineFrontier`. Null when the node holds no legal slug (no
585
- * workspace to observe). */
586
- 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) {
587
772
  const nodeSlug = BoardView.#validSlug(entry);
588
773
  if (nodeSlug === null)
589
774
  return null;
590
- const ledger = BoardView.#ledgerOf(nodeSlug, root.absolute);
775
+ const ledger = BoardView.#ledgerOf(plan, nodeSlug, root.absolute);
591
776
  const sources = BoardView.#nodeSources(index, entry);
592
777
  const specPath = sources.spec?.path ?? null;
593
- 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();
594
781
  // The identity line's OWN word — the document's DECLARED `doc-type:` — keys the
595
782
  // line and names the pipeline station (`single-spec` closes onto its `done` row).
596
783
  const specType = BoardView.#lineWordOf(sources.spec);
597
784
  return {
598
785
  ledger,
599
- input: { specType, specPath, planPath, planGraph: BoardView.planGraph(planPath) },
786
+ input: { specType, specPath, planPath, plan: read },
600
787
  };
601
788
  }
602
- /** The plan's task graph — the ONE guarded plan read behind the board's own wave
603
- * segment. `readFileSync` throwing on an unreadable plan is caught here: a null
604
- * plan path or an unreadable/absent file yields null, honoring the wave face's
605
- * "degradation, never a throw" contract. The pipeline frontier itself reads no
606
- * file — the composition root injects this read's result as its `planGraph` cell. */
607
- static planGraph(planPath) {
608
- if (planPath === null)
609
- return null;
610
- try {
611
- return new TaskGraph(new PlanDocType("plan").parse(readFileSync(planPath, "utf8").split("\n")));
612
- }
613
- catch {
614
- return null;
615
- }
616
- }
617
789
  /** The branch line — a docless line whose rounds ride the `branch` row. */
618
- static #roundsLine(label, key, progress) {
790
+ static #roundsLine(label, key, progress, ledger) {
791
+ const rounds = BoardView.#rowRounds(progress, key);
619
792
  return {
620
793
  label,
621
794
  version: null,
622
795
  status: null,
623
796
  docType: null,
624
- rounds: BoardView.#rowRounds(progress, key),
797
+ rounds,
798
+ carriers: LineCarriers.ofLedger(ledger, key, key, rounds),
625
799
  marker: null,
626
800
  };
627
801
  }
@@ -638,27 +812,34 @@ export class BoardView {
638
812
  /** The node's wave segment — one line per derived wave (its ✔/▶/○ marker rides the
639
813
  * SAME `TaskGraph.report(closedWaves())` read the board and the pre-flight gate
640
814
  * share — the same source GraphView renders from), the wave's own `progress.json`
641
- * row spread alongside. No plan → empty segment (degradation, never a throw). */
642
- static #waveLines(planPath, progress, ledger) {
643
- 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();
644
821
  if (graph === null)
645
822
  return [];
823
+ const waves = read.waves();
646
824
  const report = graph.report(ledger === null ? new Set() : ledger.closedWaves());
647
825
  const done = new Set(report.done);
648
- const currentIndex = report.waves.findIndex((wave) => wave.some((id) => !done.has(id)));
649
- return report.waves.map((wave, index) => {
826
+ const currentIndex = waves.findIndex((wave) => wave.some((id) => !done.has(id)));
827
+ return waves.map((wave, index) => {
650
828
  const closed = wave.every((id) => done.has(id));
651
829
  const marker = closed
652
830
  ? PROGRESS_MARKERS.done
653
831
  : index === currentIndex
654
832
  ? PROGRESS_MARKERS.current
655
833
  : PROGRESS_MARKERS.pending;
834
+ const key = wave.join(",");
835
+ const rounds = BoardView.#rowRounds(progress, key);
656
836
  return {
657
- label: `W${index + 1} {${wave.join(",")}}`,
837
+ label: `W${index + 1} {${key}}`,
658
838
  version: null,
659
839
  status: null,
660
840
  docType: null,
661
- rounds: BoardView.#rowRounds(progress, wave.join(",")),
841
+ rounds,
842
+ carriers: LineCarriers.ofLedger(ledger, "wave", key, rounds),
662
843
  marker,
663
844
  };
664
845
  });
@@ -676,10 +857,18 @@ export class BoardView {
676
857
  // biome-ignore lint/complexity/noStaticOnlyClass: the board's assembly fact surface — the zero-bare-function discipline admits no standalone functions here.
677
858
  export class BoardNext {
678
859
  /** The board's ONE `NextHop` — null when the entry holds no legal slug (no
679
- * workspace to observe) or the board is the program board (cross-phase never
680
- * participates in next, spec §6.5). */
681
- static of(index, entry, root) {
682
- 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);
683
872
  return facts === null ? null : BoardNext.#hopOf(facts, root);
684
873
  }
685
874
  /** The session plane's ONE assembly, called with the board's facts and the face