@oscaner-skills/cdd-engine 3.0.1 → 4.0.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.
@@ -1,19 +1,17 @@
1
1
  // packages/cdd-engine/src-next/face/board-view.ts
2
- // The board face — the slug → node-tree progress board. The file system is the
3
- // ONLY truth: the node set comes from scanning the declared spec/plan doc roots
4
- // (single-sourced at ENGINE_RUNTIME.docRoots), the artifact existence
5
- // from existsSync, the header facts from the doc's header block — the overall's
6
- // declared Phase inventory / File paths tables are NEVER parsed (measured stale).
7
- // No on-disk-absent parent node is ever synthesized (`-p4.1` present with `-p4`
8
- // missing mounts `p4.1` directly at the program root).
2
+ // The board face — the entry document → node progress board. The front-matter
3
+ // identity index (`SlugIndex`) is the ONLY node source: the entry document's
4
+ // `doc-type:` picks the board shape (overall → program board; phase-spec /
5
+ // single-spec / plan → node board), and every related node resolves through the
6
+ // index by slug (`program:` → overall; same slug → paired spec / plan). Identity
7
+ // comes from the front-matter `slug:` alone: zero file-name derivation, zero path
8
+ // guessing.
9
9
  //
10
- // This module carries the slug facts: the phase scan, the doc-tree reverse
11
- // derivation read-through, the header `{version, status, docType}` read, the
12
- // per-node progress projection, and the render face (the phase/program board
13
- // layouts + the `next:` derivation). The doc type is the DECLARED fact — the
14
- // front-matter `doc-type:` head key (spec §12 · D34) — never a
15
- // filename-suffix derivation; an absent key reads null and the consumer
16
- // blocks (zero dual-read fallback).
10
+ // This module carries the header `{version, status, docType}` read, the per-node
11
+ // progress projection, and the render face (the phase/program board layouts + the
12
+ // `next:` derivation). The doc type is the DECLARED fact — the front-matter
13
+ // `doc-type:` head key (spec §12 · D34) — never a filename-suffix derivation; an
14
+ // absent key reads null and the consumer blocks (zero dual-read fallback).
17
15
  //
18
16
  // D40 — the board's `next:` derivation walks the phase's faces in line order
19
17
  // (spec → plan → wave → branch) and, for the FIRST non-closed face, derives that
@@ -28,15 +26,15 @@
28
26
  //
29
27
  // Module-level exports are types / constants / the class — zero behavior-carrying
30
28
  // bare functions (the plan's zero-bare-function discipline).
31
- import { readdirSync, readFileSync } from "node:fs";
32
- import path from "node:path";
29
+ import { readFileSync } from "node:fs";
33
30
  import { PlanDocType } from "../contract/doc.js";
34
31
  import { FrontMatterExtractor } from "../contract/frontmatter.js";
35
32
  import { DOC_KEYS } from "../contract/project.js";
36
33
  import { ConfigLoader } from "../infra/config.js";
37
34
  import { RepoRoot } from "../infra/root.js";
38
35
  import { ENGINE_RUNTIME } from "../infra/runtime.js";
39
- import { PHASE_SUFFIX_BARE, Workspace, WorkspaceRoot } from "../infra/workspace.js";
36
+ import { SlugIndex } from "../infra/slug-index.js";
37
+ import { Workspace, WorkspaceRoot } from "../infra/workspace.js";
40
38
  import { TaskGraph } from "../session/graph.js";
41
39
  import { Ledger } from "../session/ledger.js";
42
40
  import { NextStepRouter } from "../session/next.js";
@@ -50,68 +48,24 @@ const VERB_ORDER = ["implement", "review", "branch-review", "fix"];
50
48
  * fabricated type). Derived from the ONE DocKey declaration (contract/project.ts
51
49
  * re-exports declare.ts's canonical tuple) — never a second copy (spec §3.2 ③). */
52
50
  const DOC_TYPE_DOMAIN = DOC_KEYS;
51
+ /** The board's blocked-marker vocabulary (spec §3.1) — one anchor + one `(BLOCKED)`
52
+ * suffix per violation class, never a merged prose. */
53
+ const MARK_SLUG_MISSING = "slug: missing (BLOCKED)";
54
+ const MARK_SLUG_INVALID = "slug: invalid (BLOCKED)";
55
+ const MARK_SLUG_DUPLICATED = "slug: duplicated (BLOCKED)";
56
+ const MARK_PROGRAM_MISSING = "program: missing (BLOCKED)";
57
+ const MARK_DOC_TYPE_MISSING = "doc-type: missing (BLOCKED)";
58
+ /** The program board's phase-title annotation cap — the `title:` note renders
59
+ * truncated to this many characters (an ellipsis marks the cut). */
60
+ const PHASE_TITLE_MAX = 60;
53
61
  /**
54
- * BoardView — the slug → node-tree board face. The static fact readers of this
55
- * task's slice: the phase scan over the specs doc root and the artifact header
56
- * read. Pure reads — zero tree writes, zero ledger writes, zero child dispatch.
62
+ * BoardView — the entry-document → board face. The identity index (`SlugIndex`)
63
+ * is the ONLY node source: the entry document's declared `doc-type:` picks the
64
+ * board shape and every related node resolves by slug. Pure reads — zero tree
65
+ * writes, zero ledger writes, zero child dispatch.
57
66
  */
58
67
  // biome-ignore lint/complexity/noStaticOnlyClass: the board fact-read surface — the zero-bare-function discipline admits no standalone predicate functions.
59
68
  export class BoardView {
60
- /** scanPhases(programSlug, repoRoot) — the phase-suffix set under the program:
61
- * every specs-dir entry whose stem is `<programSlug>-p<major>(.<minor>)*`
62
- * (optionally followed by a `-design`/`-overall` doc tail — `Workspace.slugFromDoc`
63
- * strips it) contributes its suffix, sorted by the dot-separated numeric path
64
- * (2 < 10, `p4.1` after `p4`). No parent node is synthesized — only the
65
- * suffixes actually found on disk return. */
66
- static scanPhases(programSlug, repoRoot) {
67
- const specsDir = path.join(repoRoot, ENGINE_RUNTIME.docRoots.specs);
68
- let entries;
69
- try {
70
- entries = readdirSync(specsDir);
71
- }
72
- catch {
73
- return [];
74
- }
75
- const prefix = `${programSlug}-`;
76
- const suffixes = new Set();
77
- for (const entry of entries) {
78
- if (!/\.md$/.test(entry) || !entry.startsWith(prefix))
79
- continue;
80
- const slug = Workspace.slugFromDoc(entry);
81
- if (slug === programSlug || !slug.startsWith(prefix))
82
- continue;
83
- const suffix = slug.slice(prefix.length);
84
- if (PHASE_SUFFIX_BARE.test(suffix))
85
- suffixes.add(`-${suffix}`);
86
- }
87
- return [...suffixes].sort((a, b) => {
88
- const numsOf = (s) => s
89
- .slice(2) // strip the leading `-p`
90
- .split(".")
91
- .map((part) => Number.parseInt(part, 10));
92
- const aNums = numsOf(a);
93
- const bNums = numsOf(b);
94
- for (let i = 0; i < Math.min(aNums.length, bNums.length); i++) {
95
- if (aNums[i] !== bNums[i])
96
- return aNums[i] - bNums[i];
97
- }
98
- return aNums.length - bNums.length;
99
- });
100
- }
101
- /** readHeader(docPath) — the artifact's header facts: the front-matter head
102
- * record (spec §2.2's structured channel), read RAW through the shared
103
- * `FrontMatterExtractor` — the version/status/doc-type scalars ride the
104
- * head keys, never a header-line marker scan (spec §12 · D34 — the doc's
105
- * declared facts live in the head record, no marker grammar). An absent file
106
- * yields nulls on every fact — never a fabricated value. */
107
- static readHeader(docPath) {
108
- const { head } = FrontMatterExtractor.split(BoardView.#read(docPath) ?? "");
109
- return {
110
- version: head.version,
111
- status: head.status,
112
- docType: BoardView.#docTypeOf(head.docType),
113
- };
114
- }
115
69
  /** readDocType(root, rel) — the doc's declared type alone (the front-matter
116
70
  * `doc-type:` key, spec §12 · D34): the ONE declaration reading face shared
117
71
  * by the board and the capsule's doc-class discrimination. An absent file, a
@@ -143,51 +97,58 @@ export class BoardView {
143
97
  // -------------------------------------------------------------------------
144
98
  // the progress projection (spec §5) — the per-node progress.json single-source read
145
99
  // -------------------------------------------------------------------------
146
- /** projectNodes(programSlug, repoRoot) — the program's node set projected: the
147
- * overall node (`<program>-overall`) followed by each on-disk phase node
148
- * (`<program>-p<N>`, the file-system-only phase scan). Each node projects its
149
- * OWN workspace `progress.json` — a pure read, zero new data, zero new judgment. */
150
- static projectNodes(programSlug, repoRoot) {
151
- const nodes = [
152
- `${programSlug}-overall`,
153
- ...BoardView.scanPhases(programSlug, repoRoot).map((suffix) => `${programSlug}${suffix}`),
154
- ];
155
- return nodes.map((slug) => BoardView.projectNode(slug, repoRoot));
100
+ /** The node's identity chain, resolved through the index by slug (spec §2.2):
101
+ * the identity document (an overall/single/phase spec), the same-slug plan, and
102
+ * the program overall the identity's `program:` names. An entry that is itself
103
+ * a plan contributes the plan and resolves its spec by the same slug. The
104
+ * `programMissing` fact is the phase-spec hard gate: a `program:` that names no
105
+ * on-disk overall (or no `program:` at all). Zero filename derivation. */
106
+ static #nodeSources(index, entry) {
107
+ const slug = BoardView.#validSlug(entry);
108
+ const isPlan = entry.docType === "plan";
109
+ const spec = slug === null ? (isPlan ? null : entry) : isPlan ? index.identityDoc(slug) : entry;
110
+ const plan = isPlan ? entry : slug === null ? null : index.planOf(slug);
111
+ const overall = spec?.docType === "phase-spec" && spec.program !== null
112
+ ? index.overallOf(spec.program)
113
+ : null;
114
+ return {
115
+ spec,
116
+ plan,
117
+ overall,
118
+ programMissing: spec !== null && BoardView.#programMissing(index, spec),
119
+ };
156
120
  }
157
- /** projectNode(nodeSlug, repoRoot) — one node's progress projection. The node's
158
- * workspace is `<repoRoot>/.kairos/cdd/<nodeSlug>/`; its `progress.json` rows are
159
- * the ONLY progress source (the rounds ride their cycle-NUMBER arrays — D28
160
- * identity; the retired numeric form is out-of-format and renders no count). The
161
- * node's doc header facts derive from the file system alone (absent doc → nulls,
162
- * never synthesized); the wave segment derives from the node's plan (no plan →
163
- * empty segment, no throw). Pure reads — zero tree writes, zero ledger writes,
164
- * zero child dispatch. */
165
- static projectNode(nodeSlug, repoRoot) {
166
- const root = new WorkspaceRoot(repoRoot, ENGINE_RUNTIME.handoffNamespace.workspaceRoot);
167
- const ledger = new Ledger(new Workspace(root, nodeSlug), new ConfigLoader());
168
- const progress = ledger.readProgress();
169
- const overall = BoardView.#isOverallNode(nodeSlug);
170
- const programStem = overall ? nodeSlug.slice(0, -"-overall".length) : nodeSlug;
171
- const docs = Workspace.docsOfSlug(programStem, repoRoot);
172
- const lines = [];
173
- if (overall) {
174
- lines.push(BoardView.#docLine("overall", "spec", docs.overall, progress));
175
- }
176
- else {
177
- lines.push(BoardView.#docLine("spec", "spec", docs.spec, progress));
178
- lines.push(BoardView.#docLine("plan", "plan", docs.plan, progress));
179
- }
180
- const primary = lines[0];
181
- const waveLines = overall ? [] : BoardView.#waveLines(docs.plan, progress, ledger);
182
- lines.push(BoardView.#roundsLine("branch", "branch", progress));
121
+ /** The entry's valid slug — the workspace key, or null when the declaration is
122
+ * absent or illegal (an illegal value is a violation, never a directory name). */
123
+ static #validSlug(entry) {
124
+ if (entry === null)
125
+ return null;
126
+ return SlugIndex.isLegalSlug(entry.slug) ? entry.slug : null;
127
+ }
128
+ /** The line's violation marker (spec §3.1) — slug missing / illegal / duplicated,
129
+ * then the missing type declaration. The duplicate probe reads the SAME index
130
+ * judgment the dispatch pre-flight consumes (one fact, one place). */
131
+ static #entryMark(index, entry, role) {
132
+ if (entry === null)
133
+ return null;
134
+ if (entry.slug === null)
135
+ return MARK_SLUG_MISSING;
136
+ if (!SlugIndex.isLegalSlug(entry.slug))
137
+ return MARK_SLUG_INVALID;
138
+ if (entry.docType === null)
139
+ return MARK_DOC_TYPE_MISSING;
140
+ return index.duplicatedRolesOf(entry.slug).includes(role) ? MARK_SLUG_DUPLICATED : null;
141
+ }
142
+ /** One doc line — the header facts read from the indexed entry + the row's
143
+ * rounds keyed by the line's `progress.json` key. */
144
+ static #lineOf(label, key, entry, progress) {
183
145
  return {
184
- label: nodeSlug,
185
- version: primary.version,
186
- status: primary.status,
187
- docType: primary.docType,
188
- rounds: primary.rounds,
189
- ...(waveLines.length > 0 ? { waveLines } : {}),
190
- lines,
146
+ label,
147
+ version: entry?.version ?? null,
148
+ status: entry?.status ?? null,
149
+ docType: entry?.docType ?? null,
150
+ rounds: BoardView.#rowRounds(progress, key),
151
+ marker: null,
191
152
  };
192
153
  }
193
154
  /** roundsCell(rounds) — the line's `implement×N · review×N · fix×N` cell text. Each
@@ -204,81 +165,65 @@ export class BoardView {
204
165
  }
205
166
  return cells.join(" · ");
206
167
  }
207
- /** Whether a node slug names the program's overall node (its workspace unit is
208
- * `<program>-overall`, the overall doc's own review line keyed `spec`). A label
209
- * test on the node slug — NOT a filename→doc-type derivation (D34): the overall
210
- * node is fixed at the program root, never inferred from a doc filename. */
211
- static #isOverallNode(nodeSlug) {
212
- return /-overall$/.test(nodeSlug);
213
- }
214
168
  // -------------------------------------------------------------------------
215
- // the render face (spec §5.3) — the slug → board layout + the next derivation
169
+ // the render face (spec §5.3) — the entry document → board layout + next derivation
216
170
  // -------------------------------------------------------------------------
217
- /** Whether the slug names anything on disk — the file-system-only existence test
218
- * (the board's "no matching file → exit 2, never a wall on a ghost slug"). A
219
- * program slug matches its overall or any on-disk phase; a phase slug matches its
220
- * overall anchor, spec or plan. */
221
- static hasNode(slug, repoRoot) {
222
- if (Workspace.phaseSuffixOf(slug) !== null) {
223
- const docs = Workspace.docsOfSlug(slug, repoRoot);
224
- return docs.overall !== null || docs.spec !== null || docs.plan !== null;
225
- }
226
- return (Workspace.docsOfSlug(slug, repoRoot).overall !== null ||
227
- BoardView.scanPhases(slug, repoRoot).length > 0);
228
- }
229
- /** render(slug, repoRoot, words, host, channels) — the slug's progress board
230
- * (spec §5.3): the phase form (`overall/spec/plan/wave/branch` + one line per
231
- * derived wave + the fixed legend + the `next:` line) or the program form (the
232
- * overall line with its own rounds + one summary line per phase + `next: done` —
233
- * cross-phase never participates in next). The argv channel is threaded into the
234
- * shared `RouteRenderer` (the SAME channel the capsule's route render reads, so
235
- * the board's `next:` and the engine's `next:` literal compose their argv from
236
- * ONE flag-spelling source — never a second hard-coded format string). A present
237
- * doc line carrying no `doc-type:` key renders its `doc-type:
238
- * missing (BLOCKED)` marker and the board exits 2 (spec §12 · D34 — the consumer
239
- * blocks, zero filename fallback). Pure reads — zero tree writes, zero ledger
240
- * writes, zero child dispatch. */
241
- static render(slug, repoRoot, words, host, channels = {}) {
242
- const lines = [`cdd board: ${slug}`, ""];
171
+ /** render(index, entry, repoRoot, words, host, channels) — the entry document's
172
+ * board (spec §3.1): the entry's declared `doc-type:` picks the shape —
173
+ * `overall` → the program board, every other type → the node board. The
174
+ * index supplies every related node (`program:` → overall; same slug → spec /
175
+ * plan), so no filename grammar participates. The argv channel is threaded into
176
+ * the shared `RouteRenderer` (the SAME channel the capsule's route render reads,
177
+ * so the board's `next:` and the engine's `next:` literal compose their argv from
178
+ * ONE flag-spelling source). A present doc line carrying a violation renders the
179
+ * matching `(BLOCKED)` marker and the board exits 2 (spec §3.1 — the board's
180
+ * reject face is exit 2, never the dispatch CDD_BLOCKED channel). Pure reads —
181
+ * zero tree writes, zero ledger writes, zero child dispatch. */
182
+ static render(index, entry, repoRoot, words, host, channels = {}) {
183
+ const lines = [`cdd board: ${entry.slug ?? "(none)"}`, ""];
243
184
  // The repo-basis value object — constructed ONCE at this boundary, the ONE
244
185
  // conversion exit the doc cells and the `next:` render normalize their embedded
245
186
  // paths through (T1 `RepoRoot` · D47). The raw string is threaded no further:
246
187
  // the board renders read the basis through `root.absolute` (F2 — one basis,
247
188
  // one form).
248
189
  const root = new RepoRoot(repoRoot);
249
- const exitCode = Workspace.phaseSuffixOf(slug) !== null
250
- ? BoardView.#phaseBoard(lines, slug, root, words, host, channels)
251
- : BoardView.#programBoard(lines, slug, root);
190
+ const exitCode = entry.docType === "overall"
191
+ ? BoardView.#programBoard(lines, index, entry, root)
192
+ : BoardView.#nodeBoard(lines, index, entry, root, words, host, channels);
252
193
  lines.push("", PROGRESS_LEGEND.board);
253
194
  return { lines, exitCode };
254
195
  }
255
- /** The phase board render — the overall/spec/plan/wave/branch rows + the next
256
- * derivation. Returns the exit code (2 when a present doc line carries no type
257
- * declaration). The repo-basis `root` is threaded alone (F2) — its `absolute`
258
- * feeds the fs-facing helpers, its value object the path renders. */
259
- static #phaseBoard(lines, slug, root, words, host, channels) {
196
+ /** The node board render — the overall/spec/plan/wave/branch rows + the next
197
+ * derivation (spec §3.1.1). The node's identity chain comes from the index
198
+ * (`program:` → overall; same slug → spec / plan); a missing link renders
199
+ * `(none)` and stays exit 0, while a violated line renders its marker and exits
200
+ * 2. The repo-basis `root` is threaded alone (F2) — its `absolute` feeds the
201
+ * fs-facing helpers, its value object the path renders. */
202
+ static #nodeBoard(lines, index, entry, root, words, host, channels) {
260
203
  const repoRoot = root.absolute;
261
- const suffix = Workspace.phaseSuffixOf(slug);
262
- const program = slug.slice(0, slug.length - suffix.length);
263
- const docs = Workspace.docsOfSlug(slug, repoRoot);
264
- const node = BoardView.projectNode(slug, repoRoot);
265
- const overall = BoardView.projectNode(`${program}-overall`, repoRoot);
266
- // Select each line by its label (never a positional index with a non-null
267
- // assertion — a reorder of node.lines must not silently swap the facts).
268
- const specLine = node.lines.find((line) => line.label === "spec");
269
- const planLine = node.lines.find((line) => line.label === "plan");
270
- const branchLine = node.lines.find((line) => line.label === "branch");
204
+ const sources = BoardView.#nodeSources(index, entry);
205
+ const nodeSlug = BoardView.#validSlug(entry);
206
+ const ledger = nodeSlug === null ? null : BoardView.#ledgerOf(nodeSlug, repoRoot);
207
+ const progress = ledger?.readProgress() ?? null;
208
+ const overallSlug = BoardView.#validSlug(sources.overall);
209
+ const overallProgress = overallSlug === null ? null : BoardView.#ledgerOf(overallSlug, repoRoot).readProgress();
210
+ const overallLine = BoardView.#lineOf("overall", "spec", sources.overall, overallProgress);
211
+ const specLine = BoardView.#lineOf("spec", "spec", sources.spec, progress);
212
+ const planLine = BoardView.#lineOf("plan", "plan", sources.plan, progress);
213
+ const branchLine = BoardView.#roundsLine("branch", "branch", progress);
271
214
  let blocked = false;
272
- const overallDoc = BoardView.#docCell(docs.overall, overall.lines[0], root);
215
+ const overallDoc = BoardView.#docCell(sources.overall, overallLine, root, BoardView.#entryMark(index, sources.overall, "identity"));
273
216
  lines.push(` overall ${overallDoc.text}`);
274
217
  blocked ||= overallDoc.blocked;
275
- const specDoc = BoardView.#docCell(docs.spec, specLine, root);
218
+ const specMark = BoardView.#entryMark(index, sources.spec, "identity") ??
219
+ (sources.programMissing ? MARK_PROGRAM_MISSING : null);
220
+ const specDoc = BoardView.#docCell(sources.spec, specLine, root, specMark);
276
221
  lines.push(` spec ${specDoc.text}`);
277
222
  blocked ||= specDoc.blocked;
278
- const planDoc = BoardView.#docCell(docs.plan, planLine, root);
223
+ const planDoc = BoardView.#docCell(sources.plan, planLine, root, BoardView.#entryMark(index, sources.plan, "plan"));
279
224
  lines.push(` plan ${planDoc.text}`);
280
225
  blocked ||= planDoc.blocked;
281
- const waves = node.waveLines ?? [];
226
+ const waves = BoardView.#waveLines(sources.plan?.path ?? null, progress, ledger);
282
227
  if (waves.length === 0) {
283
228
  lines.push(" wave (none)");
284
229
  }
@@ -293,91 +238,114 @@ export class BoardView {
293
238
  lines.push(`${prefix}${label} ${wave.marker ?? ""}${cell === "" ? "" : ` ${cell}`}`.trimEnd());
294
239
  });
295
240
  }
296
- const ledger = BoardView.#ledgerOf(slug, repoRoot);
297
- const branchClosed = ledger.lineClosed("branch", "branch");
241
+ const branchClosed = ledger?.lineClosed("branch", "branch") ?? false;
298
242
  const branchRounds = BoardView.roundsCell(branchLine.rounds);
299
243
  lines.push(` branch ${branchClosed ? `${PROGRESS_MARKERS.done} closed` : `${PROGRESS_MARKERS.pending} open`}${branchRounds === "" ? "" : ` ${branchRounds}`}`.trimEnd());
300
244
  lines.push("");
301
- lines.push(` next: ${BoardView.#nextOf(ledger, node, docs, words, host, channels, root)}`);
245
+ const next = ledger === null
246
+ ? "(none)"
247
+ : BoardView.#nextOf(ledger, waves, sources, words, host, channels, root);
248
+ lines.push(` next: ${next}`);
302
249
  return blocked ? 2 : 0;
303
250
  }
304
251
  /** The program board render — the overall line (its own rounds) + one summary line
305
- * per on-disk phase + `next: done` (cross-phase never participates in next, spec
306
- * §6.5). Returns the exit code (2 when the overall doc OR any present phase doc
307
- * carries no type declaration — the phase board's BLOCK propagates here, spec §12 ·
308
- * D34: zero silent fallback). */
309
- static #programBoard(lines, slug, root) {
252
+ * per phase-spec whose `program:` names this overall + `next: done` (cross-phase
253
+ * never participates in next, spec §6.5). The phase set derives from the ONE
254
+ * index (`program:` grouping — no overall child-list array). A phase row's primary
255
+ * key is its `slug:`, annotated with the truncated `title:`; any overall/phase
256
+ * violation renders its marker and exits 2 (spec §3.1 — zero silent fallback). */
257
+ static #programBoard(lines, index, entry, root) {
310
258
  const repoRoot = root.absolute;
311
- const nodes = BoardView.projectNodes(slug, repoRoot);
312
- const overall = nodes[0];
313
- const overallDoc = BoardView.#docCell(Workspace.docsOfSlug(slug, repoRoot).overall, overall.lines[0], root);
259
+ const overallSlug = BoardView.#validSlug(entry);
260
+ const ledger = overallSlug === null ? null : BoardView.#ledgerOf(overallSlug, repoRoot);
261
+ const overallLine = BoardView.#lineOf("overall", "spec", entry, ledger?.readProgress() ?? null);
262
+ const overallDoc = BoardView.#docCell(entry, overallLine, root, BoardView.#entryMark(index, entry, "identity"));
314
263
  lines.push(` overall ${overallDoc.text}`);
315
264
  lines.push("");
316
265
  let blocked = overallDoc.blocked;
317
- for (const node of nodes.slice(1)) {
318
- const label = node.label.slice(slug.length).replace(/^-p/, "P");
319
- const spec = node.lines.find((line) => line.label === "spec");
320
- const plan = node.lines.find((line) => line.label === "plan");
321
- const branch = node.lines.find((line) => line.label === "branch");
322
- // The phase line's doc-cell read: a present phase spec/plan without its
323
- // A present spec/plan without its `doc-type:` key blocks the SAME way the
324
- // phase board does — the marker renders on the phase line and the program
325
- // board exits 2.
326
- const docs = Workspace.docsOfSlug(node.label, repoRoot);
327
- const phaseBlocked = BoardView.#docCell(docs.spec, spec, root).blocked ||
328
- BoardView.#docCell(docs.plan, plan, root).blocked;
329
- blocked ||= phaseBlocked;
330
- const status = phaseBlocked ? "doc-type: missing (BLOCKED)" : (spec?.status ?? "Pending");
266
+ const phases = overallSlug === null ? [] : index.phaseSpecsOf(overallSlug);
267
+ for (const phase of phases) {
268
+ const phaseSlug = BoardView.#validSlug(phase);
269
+ const phaseLedger = phaseSlug === null ? null : BoardView.#ledgerOf(phaseSlug, repoRoot);
270
+ const phaseProgress = phaseLedger?.readProgress() ?? null;
271
+ const specLine = BoardView.#lineOf("spec", "spec", phase, phaseProgress);
272
+ const planEntry = phaseSlug === null ? null : index.planOf(phaseSlug);
273
+ const planLine = BoardView.#lineOf("plan", "plan", planEntry, phaseProgress);
274
+ const branchLine = BoardView.#roundsLine("branch", "branch", phaseProgress);
275
+ const mark = BoardView.#entryMark(index, phase, "identity") ??
276
+ (BoardView.#programMissing(index, phase) ? MARK_PROGRAM_MISSING : null);
277
+ const planMark = BoardView.#entryMark(index, planEntry, "plan");
278
+ blocked ||= mark !== null || planMark !== null;
279
+ const status = mark ?? phase.status ?? "Pending";
331
280
  // The phase's wave summary token (spec §5.3): the wave segment's first wave
332
281
  // number + an ellipsis (`wave W1…`) — the phase's wave progress at a glance,
333
282
  // derived from the SAME wave segment the phase board renders (no second read).
334
- const waves = node.waveLines ?? [];
283
+ const waves = BoardView.#waveLines(planEntry?.path ?? null, phaseProgress, phaseLedger);
335
284
  const waveCell = waves.length === 0 ? "" : `${waves[0].label.split(" ")[0]}…`;
336
285
  const parts = [];
337
286
  const cells = [
338
- ["spec", BoardView.roundsCell(spec?.rounds ?? {})],
339
- ["plan", BoardView.roundsCell(plan?.rounds ?? {})],
287
+ ["spec", BoardView.roundsCell(specLine.rounds)],
288
+ ["plan", BoardView.roundsCell(planLine.rounds)],
340
289
  ["wave", waveCell],
341
- ["branch", BoardView.roundsCell(branch?.rounds ?? {})],
290
+ ["branch", BoardView.roundsCell(branchLine.rounds)],
342
291
  ];
343
292
  for (const [key, cell] of cells)
344
293
  if (cell !== "")
345
294
  parts.push(`${key} ${cell}`);
346
295
  const tail = parts.join(" · ");
347
- lines.push(` phase ${label} ${status}${tail === "" ? "" : ` ${tail}`}`);
296
+ const note = BoardView.#titleNote(phase.title);
297
+ lines.push(` phase ${phase.slug ?? "(none)"} ${status}${tail === "" ? "" : ` ${tail}`}${note === "" ? "" : ` title: ${note}`}`);
348
298
  }
349
299
  lines.push("");
350
300
  lines.push(" next: done");
351
301
  return blocked ? 2 : 0;
352
302
  }
303
+ /** The phase-spec's `program:` gate (spec §2.2): a phase-spec naming no overall
304
+ * (or carrying no `program:` at all) is a hard cancellation of the node. */
305
+ static #programMissing(index, entry) {
306
+ if (entry.docType !== "phase-spec")
307
+ return false;
308
+ return entry.program === null || index.overallOf(entry.program) === null;
309
+ }
310
+ /** The phase row's `title:` annotation — trimmed and truncated to
311
+ * `PHASE_TITLE_MAX` characters (an ellipsis marks the cut). An absent/blank
312
+ * title notes nothing. */
313
+ static #titleNote(title) {
314
+ if (title === null)
315
+ return "";
316
+ const trimmed = title.trim();
317
+ if (trimmed === "")
318
+ return "";
319
+ return trimmed.length <= PHASE_TITLE_MAX
320
+ ? trimmed
321
+ : `${trimmed.slice(0, PHASE_TITLE_MAX - 1)}…`;
322
+ }
353
323
  /** One doc line's cell text — the doc path, the header facts and the line's
354
- * rounds (spec §5.3: `overall <path> v2.33 · Draft review×4`); a present doc
355
- * carrying no `doc-type:` key renders its `doc-type: missing
356
- * (BLOCKED)` marker in place of the facts (blocked = true). An absent doc renders
357
- * `(none)` (degradation, never a throw). The doc path renders repoRoot-relative
358
- * through the ONE value object (D47 — `docsOfSlug` derives it absolute; the board
359
- * emits the ONE shape). */
360
- static #docCell(docPath, line, root) {
361
- if (docPath === null)
324
+ * rounds (spec §5.3: `overall <path> v2.33 · Draft review×4`); a violated
325
+ * line renders its `(BLOCKED)` marker in place of the facts (blocked = true).
326
+ * An absent doc renders `(none)` (degradation, never a throw). The doc path
327
+ * renders repoRoot-relative through the ONE value object (D47). */
328
+ static #docCell(entry, line, root, mark) {
329
+ if (entry === null)
362
330
  return { text: "(none)", blocked: false };
363
- const rel = root.relativize(docPath);
364
- if (line.docType === null) {
365
- const facts = [];
366
- if (line.version !== null)
367
- facts.push(line.version);
368
- if (line.status !== null)
369
- facts.push(line.status);
331
+ const rel = root.relativize(entry.path);
332
+ const facts = [];
333
+ if (line.version !== null)
334
+ facts.push(line.version);
335
+ if (line.status !== null)
336
+ facts.push(line.status);
337
+ if (mark !== null) {
370
338
  const head = facts.length === 0 ? "" : `${facts.join(" · ")} `;
371
- return { text: `${rel} ${head}doc-type: missing (BLOCKED)`, blocked: true };
339
+ return { text: `${rel} ${head}${mark}`, blocked: true };
372
340
  }
373
- const facts = [rel];
341
+ const cells = [rel];
374
342
  const meta = [line.version, line.status].filter((part) => part !== null).join(" · ");
375
343
  if (meta !== "")
376
- facts.push(meta);
344
+ cells.push(meta);
377
345
  const rounds = BoardView.roundsCell(line.rounds);
378
346
  if (rounds !== "")
379
- facts.push(rounds);
380
- return { text: facts.join(" "), blocked: false };
347
+ cells.push(rounds);
348
+ return { text: cells.join(" "), blocked: false };
381
349
  }
382
350
  /** The node's ledger — the progress.json read face the render's closure/next
383
351
  * derivation consumes (each node reads its OWN workspace). */
@@ -399,24 +367,25 @@ export class BoardView {
399
367
  * entered (an absent doc) renders the PRECEDING entered face's exit (so a
400
368
  * just-closed spec hands off to `cdd-plan`, never the absent plan's `cdd-dev`); all
401
369
  * faces closed renders the last face's exit (the pipeline terminus). */
402
- static #nextOf(ledger, node, docs, words, host, channels, root) {
370
+ static #nextOf(ledger, waves, sources, words, host, channels, root) {
403
371
  const renderer = new RouteRenderer(words, channels, host, root);
404
- const waves = node.waveLines ?? [];
372
+ const specPath = sources.spec?.path ?? null;
373
+ const planPath = sources.plan?.path ?? null;
405
374
  // The plan's open frontier wave — the SAME ready batch the dispatch engine's
406
375
  // task-graph frontier yields (frontier over closedWaves()).
407
- const waveKey = BoardView.#waveFrontierKey(ledger, docs.plan);
376
+ const waveKey = BoardView.#waveFrontierKey(ledger, planPath);
408
377
  // The observed faces keyed by their `PIPELINE_FACES` key — the router owns the
409
378
  // order, so the board re-declares none (it only reports facts).
410
379
  const report = {
411
380
  "phase-spec": {
412
381
  closed: ledger.lineClosed("spec", "spec"),
413
- active: docs.spec === null ? null : ledger.lineRoute("spec", "spec"),
414
- target: docs.spec === null ? null : { type: "spec", id: docs.spec },
382
+ active: specPath === null ? null : ledger.lineRoute("spec", "spec"),
383
+ target: specPath === null ? null : { type: "spec", id: specPath },
415
384
  },
416
385
  plan: {
417
386
  closed: ledger.lineClosed("plan", "plan"),
418
- active: docs.plan === null ? null : ledger.lineRoute("plan", "plan"),
419
- target: docs.plan === null ? null : { type: "plan", id: docs.plan, plan: docs.plan },
387
+ active: planPath === null ? null : ledger.lineRoute("plan", "plan"),
388
+ target: planPath === null ? null : { type: "plan", id: planPath, plan: planPath },
420
389
  },
421
390
  wave: {
422
391
  // The wave face is exhausted (skipped) only when the plan yields a wave set
@@ -424,12 +393,12 @@ export class BoardView {
424
393
  // face (nothing was closed), so it stays the frontier and hands off.
425
394
  closed: waves.length > 0 && waves.every((wave) => wave.marker === PROGRESS_MARKERS.done),
426
395
  active: waveKey === null ? null : ledger.waveLineRoute(waveKey),
427
- target: docs.plan === null ? null : { type: "wave", id: waveKey ?? "", plan: docs.plan },
396
+ target: planPath === null ? null : { type: "wave", id: waveKey ?? "", plan: planPath },
428
397
  },
429
398
  branch: {
430
399
  closed: ledger.lineClosed("branch", "branch"),
431
400
  active: ledger.lineRoute("branch", "branch"),
432
- target: { type: "branch", id: "branch", plan: docs.plan ?? undefined },
401
+ target: { type: "branch", id: "branch", plan: planPath ?? undefined },
433
402
  },
434
403
  };
435
404
  const next = NextStepRouter.walk(report);
@@ -460,14 +429,6 @@ export class BoardView {
460
429
  return null;
461
430
  }
462
431
  }
463
- /** One doc line — the header facts read from the doc (absent → nulls) + the row's
464
- * rounds keyed by the line's `progress.json` key. */
465
- static #docLine(label, key, docPath, progress) {
466
- const header = docPath === null
467
- ? { version: null, status: null, docType: null }
468
- : BoardView.readHeader(docPath);
469
- return { label, ...header, rounds: BoardView.#rowRounds(progress, key), marker: null };
470
- }
471
432
  /** The branch line — a docless line whose rounds ride the `branch` row. */
472
433
  static #roundsLine(label, key, progress) {
473
434
  return {
@@ -499,7 +460,7 @@ export class BoardView {
499
460
  const graph = BoardView.#planGraph(planPath);
500
461
  if (graph === null)
501
462
  return [];
502
- const report = graph.report(ledger.closedWaves());
463
+ const report = graph.report(ledger === null ? new Set() : ledger.closedWaves());
503
464
  const done = new Set(report.done);
504
465
  const currentIndex = report.waves.findIndex((wave) => wave.some((id) => !done.has(id)));
505
466
  return report.waves.map((wave, index) => {