@oscaner-skills/cdd-engine 4.2.0 → 4.3.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.
Files changed (55) hide show
  1. package/README.md +38 -9
  2. package/README.zh-CN.md +43 -9
  3. package/dist/contract/completion-criterion.js +351 -0
  4. package/dist/contract/declare.js +181 -43
  5. package/dist/contract/doc.js +84 -271
  6. package/dist/contract/frontmatter.js +2 -1
  7. package/dist/contract/home-extractors.js +49 -316
  8. package/dist/contract/invariants.js +400 -296
  9. package/dist/contract/judge.js +74 -49
  10. package/dist/contract/lint.js +3 -2
  11. package/dist/contract/liveness-signal.js +103 -0
  12. package/dist/contract/markdown-document.js +410 -0
  13. package/dist/contract/markdown-tree-types.js +6 -0
  14. package/dist/contract/markdown-tree.js +137 -0
  15. package/dist/contract/project.js +1 -1
  16. package/dist/contract/rules.js +106 -0
  17. package/dist/contract/selector-engine.js +332 -0
  18. package/dist/contract/selector-spec.js +74 -0
  19. package/dist/contract/skill-anatomy.js +29 -1
  20. package/dist/contract/task-block-grammar.js +285 -0
  21. package/dist/contract/task-blocks.js +65 -0
  22. package/dist/contract/translate.js +21 -0
  23. package/dist/contract/wave-width.js +15 -0
  24. package/dist/face/board-view.js +401 -131
  25. package/dist/face/capsule.js +66 -89
  26. package/dist/face/cli.js +116 -35
  27. package/dist/face/declare.js +36 -18
  28. package/dist/face/gate.js +117 -40
  29. package/dist/face/init.js +1 -1
  30. package/dist/face/lifecycle.js +540 -123
  31. package/dist/face/preview.js +43 -10
  32. package/dist/face/route-render.js +51 -21
  33. package/dist/face/termination.js +135 -261
  34. package/dist/face/words.js +134 -12
  35. package/dist/infra/atomic.js +15 -0
  36. package/dist/infra/git.js +25 -0
  37. package/dist/infra/proc.js +150 -0
  38. package/dist/infra/round-log.js +104 -0
  39. package/dist/infra/runtime.js +16 -4
  40. package/dist/infra/workspace.js +7 -2
  41. package/dist/render/brief.js +15 -17
  42. package/dist/render/skeleton.js +41 -28
  43. package/dist/render/templates.js +128 -84
  44. package/dist/session/faces.js +47 -20
  45. package/dist/session/graph.js +13 -37
  46. package/dist/session/handoff-schema.js +16 -8
  47. package/dist/session/inflight.js +282 -0
  48. package/dist/session/ledger.js +581 -136
  49. package/dist/session/line-identity.js +33 -0
  50. package/dist/session/next.js +138 -80
  51. package/dist/session/preflight.js +276 -68
  52. package/dist/session/round-naming.js +56 -8
  53. package/dist/session/run.js +317 -78
  54. package/dist/session/wave.js +94 -14
  55. package/package.json +13 -3
@@ -8,25 +8,29 @@
8
8
  // guessing.
9
9
  //
10
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).
11
+ // progress projection, the render face (the phase/program board layouts) and the
12
+ // pipeline OBSERVATION (`#pipelineFacts`). The doc type is the DECLARED fact — the
13
+ // front-matter `doc-type:` head key (spec §12 · D34) — never a filename-suffix
14
+ // derivation; an absent key reads null and the consumer blocks (zero dual-read
15
+ // fallback).
15
16
  //
16
- // D40 — the board's `next:` derivation walks the phase's faces in line order
17
- // (spec → plan → wave → branch) and, for the FIRST non-closed face, derives that
18
- // line's ACTIVE C5 hop from the SAME state→next chain the dispatch engine walks
19
- // (the wave face's frontier → `Ledger#waveLinePhase`; the doc/branch faces'
20
- // `Ledger#linePhase`) before feeding it to the ONE resolver (`NextStepRouter.resolve`)
21
- // and the ONE renderer (`RouteRenderer`, shared with the capsule). A line still in
22
- // flight therefore renders its next C5 hop (`implement --tasks 12,13,14`), never the
23
- // face-to-face handoff of an exhausted line; a fully drained line hands off to the
24
- // next pipeline entry. Each wave line's label carries the wave's task scope in braces
25
- // (`W1 {5,11}`) with the ✔/▶/○ marker column fixed-width aligned.
17
+ // P22 §5.2 — the board's `next:` line renders an INJECTED `NextHop` and judges
18
+ // nothing: the pipeline traversal (the four face-order rules) lives on the
19
+ // assembly face (`face/cli.ts`), the ONE derivation is `NextStepRouter#nextHop`,
20
+ // and the ONE literal renderer is `RouteRenderer` (shared with the capsule). The
21
+ // board only OBSERVES each face's facts (`#pipelineFacts`) and renders.
26
22
  //
27
- // Module-level exports are types / constants / the class — zero behavior-carrying
23
+ // P22 §5.3 — the default layout aggregates each line's rounds BY VERB into
24
+ // `{label} {count}{attempt} {mark}` tokens (the judgement glyph is mandatory, the
25
+ // findings count rides a `+N` suffix, a re-dispatch carries its `a{attempt}`
26
+ // superscript); range forms never render (there is no `--verbose` in this phase).
27
+ // Each wave line's label carries the wave's task scope in braces (`W1 {5,11}`)
28
+ // with the ✔/▶/○ marker column fixed-width aligned.
29
+ //
30
+ // Module-level exports are types / constants / the classes — zero behavior-carrying
28
31
  // bare functions (the plan's zero-bare-function discipline).
29
32
  import { readFileSync } from "node:fs";
33
+ import path from "node:path";
30
34
  import { PlanDocType } from "../contract/doc.js";
31
35
  import { FrontMatterExtractor } from "../contract/frontmatter.js";
32
36
  import { DOC_KEYS } from "../contract/project.js";
@@ -36,13 +40,17 @@ import { ENGINE_RUNTIME } from "../infra/runtime.js";
36
40
  import { SlugIndex } from "../infra/slug-index.js";
37
41
  import { Workspace, WorkspaceRoot } from "../infra/workspace.js";
38
42
  import { TaskGraph } from "../session/graph.js";
39
- import { Ledger } from "../session/ledger.js";
40
- import { NextStepRouter } from "../session/next.js";
43
+ import { Ledger, RoundRecords } from "../session/ledger.js";
44
+ import { NextStepRouter, PIPELINE_FACES, PIPELINE_NEXT, } from "../session/next.js";
41
45
  import { PROGRESS_LEGEND, PROGRESS_MARKERS } from "./graph-view.js";
42
46
  import { RouteRenderer } from "./route-render.js";
43
- /** The verb render order of a line's `×N` cell — the stable display order the board's
44
- * round cells follow (an unexpected verb appends after these, never dropped). */
47
+ /** The verb render order of a line's rounds tokens — the stable display order the
48
+ * board's aggregated cells follow (an unexpected verb appends after these, never
49
+ * dropped). */
45
50
  const VERB_ORDER = ["implement", "review", "branch-review", "fix"];
51
+ /** The judgement glyphs of one aggregated token (spec §5.3 — the mark is MANDATORY:
52
+ * `✓` a completed round, `✗` a round that failed its target action). */
53
+ const JUDGEMENT_MARKERS = { passed: "✓", failed: "✗" };
46
54
  /** The DocKey domain of the `doc-type:` declaration — the declared value must
47
55
  * be one of the four keys; anything else reads null (present facts, never a
48
56
  * fabricated type). Derived from the ONE DocKey declaration (contract/project.ts
@@ -58,6 +66,9 @@ const MARK_DOC_TYPE_MISSING = "doc-type: missing (BLOCKED)";
58
66
  /** The program board's phase-title annotation cap — the `title:` note renders
59
67
  * truncated to this many characters (an ellipsis marks the cut). */
60
68
  const PHASE_TITLE_MAX = 60;
69
+ /** The label column of the board's line rows — ` ` + the label padded to this
70
+ * width (`overall` is the longest verb at 7), so every value starts in one column. */
71
+ const LABEL_WIDTH = 9;
61
72
  /**
62
73
  * BoardView — the entry-document → board face. The identity index (`SlugIndex`)
63
74
  * is the ONLY node source: the entry document's declared `doc-type:` picks the
@@ -78,6 +89,28 @@ export class BoardView {
78
89
  static readDocType(root, rel) {
79
90
  return BoardView.#docTypeOf(FrontMatterExtractor.split(BoardView.#read(root.resolve(rel)) ?? "").head.docType);
80
91
  }
92
+ /** docClassOf(root, target) — the pipeline-station discrimination of one render
93
+ * target (spec §5.2 · D33): a doc shape's class reads its DECLARED type (the
94
+ * front-matter `doc-type:` key — the ONE declaration reading face above), never
95
+ * the filename suffix or the `--type` spelling; the node shapes key by their own
96
+ * type. `blocked` — the key is missing (the renderer prints the BLOCKED face);
97
+ * `terminal` — no pipeline seam carries the declared class (`single-spec`, the
98
+ * `PipelineKey` derivation excludes it). This is the injected seam of the ONE hop
99
+ * derivation: `session/next.ts` never imports a face class, and every read face
100
+ * shares this ONE judgment. The basis is REQUIRED — an unrooted resolve would read
101
+ * the target against `process.cwd()`, so an engine invoked from a subdirectory
102
+ * could report a declared line as `doc-class-blocked`; the root is always the value
103
+ * object the read face holds. */
104
+ static docClassOf(root, target) {
105
+ if (target.type === "plan")
106
+ return "plan";
107
+ if (target.type === "wave")
108
+ return "wave";
109
+ if (target.type === "branch")
110
+ return "branch";
111
+ const declared = BoardView.readDocType(root, root.relativize(target.id));
112
+ return declared === null ? "blocked" : declared === "single-spec" ? "terminal" : declared;
113
+ }
81
114
  /** The doc file's raw text — an absent/unreadable file reads null (the reads
82
115
  * above degrade to null facts, never a throw). */
83
116
  static #read(docPath) {
@@ -139,47 +172,161 @@ export class BoardView {
139
172
  return MARK_DOC_TYPE_MISSING;
140
173
  return index.duplicatedRolesOf(entry.slug).includes(role) ? MARK_SLUG_DUPLICATED : null;
141
174
  }
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. */
175
+ /** The identity document's line word — its DECLARED `doc-type:` (spec §12 · D34), the
176
+ * ONE word the line keys under (`run.ts`'s `#lineKey`) and the word the pipeline
177
+ * station follows. `phase-spec` is the degradation default for an absent or
178
+ * undeclared document (that line renders `(none)` / its BLOCKED marker anyway) — it
179
+ * is never a translation of a declared word. */
180
+ static #lineWordOf(entry) {
181
+ return entry?.docType ?? "phase-spec";
182
+ }
183
+ /** One doc line — the header facts read from the indexed entry + the row's round
184
+ * RECORDS keyed by the line's `progress.json` key, resolved with the line's DECLARED
185
+ * word as the retired-key alias basis (a charter's pre-rename `spec` row is its own
186
+ * `overall` line). */
144
187
  static #lineOf(label, key, entry, progress) {
145
188
  return {
146
189
  label,
147
190
  version: entry?.version ?? null,
148
191
  status: entry?.status ?? null,
149
192
  docType: entry?.docType ?? null,
150
- rounds: BoardView.#rowRounds(progress, key),
193
+ rounds: BoardView.#rowRounds(progress, key, entry?.docType ?? null),
151
194
  marker: null,
152
195
  };
153
196
  }
154
- /** roundsCell(rounds) — the line's `implement×N · review×N · fix×N` cell text. Each
155
- * `×N` is the CYCLE-NUMBER array's element count (D28 identity — `[1,3]` → `×2`),
156
- * never the stored number: a non-array (the retired numeric form) contributes no
157
- * cell. Verbs render in the fixed board order; an out-of-order verb appends after. */
158
- static roundsCell(rounds) {
159
- const cells = [];
160
- const verbs = [...VERB_ORDER, ...Object.keys(rounds).filter((v) => !VERB_ORDER.includes(v))];
161
- for (const verb of verbs) {
162
- const value = rounds[verb];
163
- if (Array.isArray(value) && value.length > 0)
164
- cells.push(`${verb}×${value.length}`);
197
+ /** summaryCell(records) — the line's aggregated rounds cell (spec §5.3): one token
198
+ * per verb × judgement run (`{label} {count}{attempt} {mark}`), joined by ` · `.
199
+ * The count is the run's round count, the attempt superscript belongs to the run's
200
+ * LAST record (a re-dispatch: `fix 1 ✗ · fix 1a2 ✓`), the mark is the run's verdict
201
+ * (`✓` completed / `✗` failed — never omitted), and the run's graded findings ride
202
+ * the `+N` suffix (omitted at 0). The range form (`review 1–10 ✓`) never renders:
203
+ * the aggregation IS the count. */
204
+ static summaryCell(records) {
205
+ const tokens = [];
206
+ const extra = [...new Set(records.map((record) => record.op))].filter((op) => !VERB_ORDER.includes(op));
207
+ for (const verb of [...VERB_ORDER, ...extra]) {
208
+ const ofVerb = records.filter((record) => record.op === verb);
209
+ for (const run of BoardView.#judgementRuns(ofVerb)) {
210
+ tokens.push(BoardView.#summaryToken(verb, run));
211
+ }
212
+ }
213
+ return tokens.join(" · ");
214
+ }
215
+ /** One aggregated token of a verb × judgement run. The `+N` suffix counts the
216
+ * run's graded FINDINGS, read from each round's own carrier (`carrierPath` → the
217
+ * handoff's `findings` array, spec §5.3) — never the round's hard/soft contract
218
+ * violations, which are a different fact. A record with no carrier (a legacy row,
219
+ * or a work-plane round whose carrier declares no findings) contributes zero. */
220
+ static #summaryToken(verb, run) {
221
+ const mark = run[0].verdict.targetAction ? JUDGEMENT_MARKERS.passed : JUDGEMENT_MARKERS.failed;
222
+ const findings = run.reduce((total, record) => total + BoardView.#findingsCountOf(record), 0);
223
+ const suffix = findings === 0 ? "" : `+${findings}`;
224
+ return `${verb} ${run.length}${BoardView.attemptSuffix(run[run.length - 1])} ${mark}${suffix}`;
225
+ }
226
+ /** One round's findings count — the `findings` array length of the carrier the round
227
+ * persisted (the judge plane's declared field). Zero when the record carries no
228
+ * carrier path or the file is absent/unreadable/unparseable (present facts only,
229
+ * never a throw on a read face). */
230
+ static #findingsCountOf(record) {
231
+ const at = record.carrierPath;
232
+ if (at === null)
233
+ return 0;
234
+ const text = BoardView.#read(at);
235
+ if (text === null)
236
+ return 0;
237
+ try {
238
+ const value = JSON.parse(text);
239
+ const findings = value?.findings;
240
+ return Array.isArray(findings) ? findings.length : 0;
241
+ }
242
+ catch {
243
+ return 0;
165
244
  }
166
- return cells.join(" · ");
245
+ }
246
+ /** attemptSuffix(record) — the re-dispatch superscript: `attempt === 1` renders
247
+ * nothing (an `a1` never appears), otherwise `a{attempt}`. */
248
+ static attemptSuffix(record) {
249
+ return record.attempt === 1 ? "" : `a${record.attempt}`;
250
+ }
251
+ /** The judgement runs of one verb — contiguous records sharing a verdict, in the
252
+ * stored (chronological) order, so a re-dispatch's `✗ → ✓` pair renders as two
253
+ * tokens and an unbroken green history collapses into one (spec §5.3). */
254
+ static #judgementRuns(records) {
255
+ const runs = [];
256
+ for (const record of records) {
257
+ const last = runs[runs.length - 1];
258
+ if (last !== undefined && last[0].verdict.targetAction === record.verdict.targetAction) {
259
+ last.push(record);
260
+ }
261
+ else {
262
+ runs.push([record]);
263
+ }
264
+ }
265
+ return runs;
266
+ }
267
+ /** nextLine(hop, renderer) — the board's `next:` row rendered from the INJECTED
268
+ * hop through the shared hop renderer (`RouteRenderer#renderHop`), so the board's
269
+ * line and the capsule's line are byte-identical by construction. Every embedded
270
+ * path value renders repoRoot-relative (the renderer's own basis). A hop the
271
+ * renderer renders as no line degrades to the same `(none)` bytes the absent-hop
272
+ * row carries — the row is never built from a null value. */
273
+ static nextLine(hop, renderer) {
274
+ const value = renderer.renderHop(hop) ?? "(none)";
275
+ return ` next: ${value}`;
276
+ }
277
+ /** inFlightRows(state, orphans, words) — the tree's dispatch fact + the
278
+ * workspace's orphan handoff drafts, as board lines. The held row names the
279
+ * holder's IDENTITY facts alone (the operating verb, the round's cycle + attempt
280
+ * cells a takeover has to answer for, the wave key and the pid, spec §5.3): the
281
+ * child's command line, its start instant and its plan path are dispatch
282
+ * narrative, not board facts. A DEAD holder adds the takeover hint. The free and
283
+ * corrupt rows are the word table's declared rows — the board's hint is the same
284
+ * bytes the preview face and the gate print (one vocabulary, never a board
285
+ * literal). The orphan rows are the drafts no recorded round owns — the board
286
+ * lists them, never writes or deletes them. */
287
+ static inFlightRows(state, orphans, words) {
288
+ const rows = [];
289
+ if (state.kind === "held") {
290
+ const record = state.record;
291
+ const dead = state.alive ? "" : ` — ${words.inFlightWords().stealable}`;
292
+ const identity = [
293
+ `pid ${record.pid}`,
294
+ `op: ${record.phase ?? "dispatch"}`,
295
+ record.cycle === null ? null : `cycle: ${record.cycle}`,
296
+ record.attempt === null ? null : `attempt: ${record.attempt}`,
297
+ `slug: ${record.slug}`,
298
+ `wave: ${record.wave ?? "none"}`,
299
+ ].filter((cell) => cell !== null);
300
+ rows.push(` in-flight: ${identity.join(" · ")}${dead}`);
301
+ }
302
+ else if (state.kind === "corrupt") {
303
+ const inFlight = words.inFlightWords();
304
+ rows.push(` in-flight: ${state.locked ? inFlight.corruptLocked : inFlight.corruptUnlocked}`);
305
+ }
306
+ else {
307
+ rows.push(` in-flight: ${words.checkedWords().inFlight.free}`);
308
+ }
309
+ for (const orphan of orphans)
310
+ rows.push(` orphan: ${orphan} — no recorded round owns it`);
311
+ return rows;
167
312
  }
168
313
  // -------------------------------------------------------------------------
169
- // the render face (spec §5.3) — the entry document → board layout + next derivation
314
+ // the render face (spec §5.3) — the entry document → board layout + next render
170
315
  // -------------------------------------------------------------------------
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
316
+ /** render(index, entry, repoRoot, words, host, channels, holding, next) — the
317
+ * entry document's board (spec §3.1): the entry's declared `doc-type:` picks the
318
+ * shape — `overall` → the program board, every other type → the node board. The
174
319
  * 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
320
+ * plan), so no filename grammar participates. `next` is the INJECTED `NextHop`
321
+ * the node board's `next:` row renders (null = the board holds no derivable hop,
322
+ * the `(none)` degradation). The argv channel is threaded into the shared
323
+ * `RouteRenderer` (the SAME channel the capsule's route render reads, so the
324
+ * board's `next:` and the engine's `next:` literal compose their argv from ONE
325
+ * flag-spelling source). A present doc line carrying a violation renders the
179
326
  * matching `(BLOCKED)` marker and the board exits 2 (spec §3.1 — the board's
180
327
  * reject face is exit 2, never the dispatch CDD_BLOCKED channel). Pure reads —
181
328
  * zero tree writes, zero ledger writes, zero child dispatch. */
182
- static render(index, entry, repoRoot, words, host, channels = {}) {
329
+ static render(index, entry, repoRoot, words, host, channels = {}, holding = { kind: "absent" }, next = null) {
183
330
  const lines = [`cdd board: ${entry.slug ?? "(none)"}`, ""];
184
331
  // The repo-basis value object — constructed ONCE at this boundary, the ONE
185
332
  // conversion exit the doc cells and the `next:` render normalize their embedded
@@ -189,63 +336,98 @@ export class BoardView {
189
336
  const root = new RepoRoot(repoRoot);
190
337
  const exitCode = entry.docType === "overall"
191
338
  ? BoardView.#programBoard(lines, index, entry, root)
192
- : BoardView.#nodeBoard(lines, index, entry, root, words, host, channels);
339
+ : BoardView.#nodeBoard(lines, index, entry, root, words, host, channels, holding, next);
193
340
  lines.push("", PROGRESS_LEGEND.board);
194
341
  return { lines, exitCode };
195
342
  }
196
343
  /** 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
344
+ * render (spec §3.1.1). The node's identity chain comes from the index
198
345
  * (`program:` → overall; same slug → spec / plan); a missing link renders
199
346
  * `(none)` and stays exit 0, while a violated line renders its marker and exits
200
347
  * 2. The repo-basis `root` is threaded alone (F2) — its `absolute` feeds the
201
348
  * fs-facing helpers, its value object the path renders. */
202
- static #nodeBoard(lines, index, entry, root, words, host, channels) {
349
+ static #nodeBoard(lines, index, entry, root, words, host, channels, holding, next) {
203
350
  const repoRoot = root.absolute;
204
351
  const sources = BoardView.#nodeSources(index, entry);
205
352
  const nodeSlug = BoardView.#validSlug(entry);
206
353
  const ledger = nodeSlug === null ? null : BoardView.#ledgerOf(nodeSlug, repoRoot);
354
+ // The tree's dispatch fact + the node workspace's orphan drafts render before the
355
+ // line rows (a reader answers "is anyone working here?" before reading progress).
356
+ const orphans = ledger?.orphanHandoffs() ?? [];
357
+ for (const row of BoardView.inFlightRows(holding, orphans, words))
358
+ lines.push(row);
359
+ if (holding.kind !== "absent" || orphans.length > 0)
360
+ lines.push("");
207
361
  const progress = ledger?.readProgress() ?? null;
208
362
  const overallSlug = BoardView.#validSlug(sources.overall);
209
363
  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);
364
+ const docRows = [
365
+ {
366
+ label: "overall",
367
+ entry: sources.overall,
368
+ line: BoardView.#lineOf("overall", "overall", sources.overall, overallProgress),
369
+ mark: BoardView.#entryMark(index, sources.overall, "identity"),
370
+ },
371
+ {
372
+ label: "spec",
373
+ entry: sources.spec,
374
+ line: BoardView.#lineOf("spec", BoardView.#lineWordOf(sources.spec), sources.spec, progress),
375
+ mark: BoardView.#entryMark(index, sources.spec, "identity") ??
376
+ (sources.programMissing ? MARK_PROGRAM_MISSING : null),
377
+ },
378
+ {
379
+ label: "plan",
380
+ entry: sources.plan,
381
+ line: BoardView.#lineOf("plan", "plan", sources.plan, progress),
382
+ mark: BoardView.#entryMark(index, sources.plan, "plan"),
383
+ },
384
+ ];
385
+ // The doc-name column is fixed-width: every name is padded to the widest one, so
386
+ // the version column aligns down the block (spec §5.3).
387
+ const nameWidth = Math.max(0, ...docRows
388
+ .filter((row) => row.entry !== null)
389
+ .map((row) => path.basename(row.entry.path).length));
214
390
  let blocked = false;
215
- const overallDoc = BoardView.#docCell(sources.overall, overallLine, root, BoardView.#entryMark(index, sources.overall, "identity"));
216
- lines.push(` overall ${overallDoc.text}`);
217
- blocked ||= overallDoc.blocked;
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);
221
- lines.push(` spec ${specDoc.text}`);
222
- blocked ||= specDoc.blocked;
223
- const planDoc = BoardView.#docCell(sources.plan, planLine, root, BoardView.#entryMark(index, sources.plan, "plan"));
224
- lines.push(` plan ${planDoc.text}`);
225
- blocked ||= planDoc.blocked;
391
+ for (const row of docRows) {
392
+ const cell = BoardView.#docCell(row.entry, row.line, nameWidth, row.mark);
393
+ lines.push(` ${row.label.padEnd(LABEL_WIDTH)}${cell.text}`.trimEnd());
394
+ blocked ||= cell.blocked;
395
+ }
226
396
  const waves = BoardView.#waveLines(sources.plan?.path ?? null, progress, ledger);
227
397
  if (waves.length === 0) {
228
- lines.push(" wave (none)");
398
+ lines.push(` ${"wave".padEnd(LABEL_WIDTH)}(none)`);
229
399
  }
230
400
  else {
231
401
  // The marker column is fixed-width: every wave label is padded to the widest
232
- // label so the ✔/▶/○ markers align into one column (spec §5.2 · D40).
402
+ // label so the ✔/▶/○ markers align into one column (spec §5.3 · D40).
233
403
  const labelWidth = Math.max(...waves.map((wave) => wave.label.length));
234
404
  waves.forEach((wave, index) => {
235
- const prefix = index === 0 ? " wave " : " ";
236
- const cell = BoardView.roundsCell(wave.rounds);
405
+ const prefix = index === 0 ? ` ${"wave".padEnd(LABEL_WIDTH)}` : " ".repeat(2 + LABEL_WIDTH);
406
+ const cell = BoardView.summaryCell(wave.rounds);
237
407
  const label = wave.label.padEnd(labelWidth);
238
408
  lines.push(`${prefix}${label} ${wave.marker ?? ""}${cell === "" ? "" : ` ${cell}`}`.trimEnd());
239
409
  });
240
410
  }
241
- const branchClosed = ledger?.lineClosed("branch", "branch") ?? false;
242
- const branchRounds = BoardView.roundsCell(branchLine.rounds);
243
- lines.push(` branch ${branchClosed ? `${PROGRESS_MARKERS.done} closed` : `${PROGRESS_MARKERS.pending} open`}${branchRounds === "" ? "" : ` ${branchRounds}`}`.trimEnd());
411
+ const branchLine = BoardView.#roundsLine("branch", "branch", progress);
412
+ // The branch line's mark is the SAME drift-aware judgment its pipeline facts read
413
+ // (`Ledger#lineStateAt`, identity document = the plan): a drifted plan reopens the
414
+ // branch face, so the mark can never print `✔ closed` while `next:` names the
415
+ // review the gate accepts — the reopened line renders as the CURRENT face (`▶`).
416
+ const branchState = ledger?.lineStateAt("branch", "branch", sources.plan?.path ?? null) ?? "open";
417
+ const branchMark = branchState === "closed"
418
+ ? `${PROGRESS_MARKERS.done} closed`
419
+ : branchState === "reopened"
420
+ ? `${PROGRESS_MARKERS.current} open`
421
+ : `${PROGRESS_MARKERS.pending} open`;
422
+ const branchRounds = BoardView.summaryCell(branchLine.rounds);
423
+ lines.push(` ${"branch".padEnd(LABEL_WIDTH)}${branchMark}${branchRounds === "" ? "" : ` ${branchRounds}`}`.trimEnd());
244
424
  lines.push("");
245
- const next = ledger === null
246
- ? "(none)"
247
- : BoardView.#nextOf(ledger, waves, sources, words, host, channels, root);
248
- lines.push(` next: ${next}`);
425
+ if (next === null) {
426
+ lines.push(" next: (none)");
427
+ }
428
+ else {
429
+ lines.push(BoardView.nextLine(next, new RouteRenderer(words, channels, host, root)));
430
+ }
249
431
  return blocked ? 2 : 0;
250
432
  }
251
433
  /** The program board render — the overall line (its own rounds) + one summary line
@@ -258,9 +440,9 @@ export class BoardView {
258
440
  const repoRoot = root.absolute;
259
441
  const overallSlug = BoardView.#validSlug(entry);
260
442
  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"));
263
- lines.push(` overall ${overallDoc.text}`);
443
+ const overallLine = BoardView.#lineOf("overall", "overall", entry, ledger?.readProgress() ?? null);
444
+ const overallDoc = BoardView.#docCell(entry, overallLine, path.basename(entry.path).length, BoardView.#entryMark(index, entry, "identity"));
445
+ lines.push(` ${"overall".padEnd(LABEL_WIDTH)}${overallDoc.text}`);
264
446
  lines.push("");
265
447
  let blocked = overallDoc.blocked;
266
448
  const phases = overallSlug === null ? [] : index.phaseSpecsOf(overallSlug);
@@ -268,7 +450,7 @@ export class BoardView {
268
450
  const phaseSlug = BoardView.#validSlug(phase);
269
451
  const phaseLedger = phaseSlug === null ? null : BoardView.#ledgerOf(phaseSlug, repoRoot);
270
452
  const phaseProgress = phaseLedger?.readProgress() ?? null;
271
- const specLine = BoardView.#lineOf("spec", "spec", phase, phaseProgress);
453
+ const specLine = BoardView.#lineOf("spec", "phase-spec", phase, phaseProgress);
272
454
  const planEntry = phaseSlug === null ? null : index.planOf(phaseSlug);
273
455
  const planLine = BoardView.#lineOf("plan", "plan", planEntry, phaseProgress);
274
456
  const branchLine = BoardView.#roundsLine("branch", "branch", phaseProgress);
@@ -284,10 +466,10 @@ export class BoardView {
284
466
  const waveCell = waves.length === 0 ? "" : `${waves[0].label.split(" ")[0]}…`;
285
467
  const parts = [];
286
468
  const cells = [
287
- ["spec", BoardView.roundsCell(specLine.rounds)],
288
- ["plan", BoardView.roundsCell(planLine.rounds)],
469
+ ["spec", BoardView.summaryCell(specLine.rounds)],
470
+ ["plan", BoardView.summaryCell(planLine.rounds)],
289
471
  ["wave", waveCell],
290
- ["branch", BoardView.roundsCell(branchLine.rounds)],
472
+ ["branch", BoardView.summaryCell(branchLine.rounds)],
291
473
  ];
292
474
  for (const [key, cell] of cells)
293
475
  if (cell !== "")
@@ -320,29 +502,25 @@ export class BoardView {
320
502
  ? trimmed
321
503
  : `${trimmed.slice(0, PHASE_TITLE_MAX - 1)}…`;
322
504
  }
323
- /** One doc line's cell text — the doc path, the header facts and the line's
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) {
505
+ /** One doc line's cell text — the doc NAME (directory omitted, spec §5.3), the
506
+ * header facts and the line's aggregated rounds (`spec prog-p1-design.md v0.14 ·
507
+ * Draft review 2 ✓`). The name is padded to the block's name column so the
508
+ * version column aligns; a violated line renders its `(BLOCKED)` marker in place
509
+ * of the rounds (blocked = true). An absent doc renders `(none)` (degradation,
510
+ * never a throw). */
511
+ static #docCell(entry, line, nameWidth, mark) {
329
512
  if (entry === null)
330
513
  return { text: "(none)", blocked: false };
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);
514
+ const name = path.basename(entry.path).padEnd(nameWidth);
515
+ const meta = [line.version, line.status].filter((part) => part !== null).join(" · ");
337
516
  if (mark !== null) {
338
- const head = facts.length === 0 ? "" : `${facts.join(" · ")} `;
339
- return { text: `${rel} ${head}${mark}`, blocked: true };
517
+ const head = meta === "" ? "" : `${meta} `;
518
+ return { text: `${name} ${head}${mark}`, blocked: true };
340
519
  }
341
- const cells = [rel];
342
- const meta = [line.version, line.status].filter((part) => part !== null).join(" · ");
520
+ const cells = [name];
343
521
  if (meta !== "")
344
522
  cells.push(meta);
345
- const rounds = BoardView.roundsCell(line.rounds);
523
+ const rounds = BoardView.summaryCell(line.rounds);
346
524
  if (rounds !== "")
347
525
  cells.push(rounds);
348
526
  return { text: cells.join(" "), blocked: false };
@@ -353,34 +531,37 @@ export class BoardView {
353
531
  const root = new WorkspaceRoot(repoRoot, ENGINE_RUNTIME.handoffNamespace.workspaceRoot);
354
532
  return new Ledger(new Workspace(root, nodeSlug), new ConfigLoader());
355
533
  }
356
- /** The board's `next:` derivation (spec §6.5 · §18.2 · D40 deep-solve) — the board
357
- * OBSERVES each phase face's state (closed · its ACTIVE C5 hop from the SAME
358
- * state→next chain the dispatch engine walks — `Ledger#lineRoute` for the doc/branch
359
- * lines, the plan frontier + `Ledger#waveLineRoute` for the wave line — and the
360
- * render target) as a keyed report and hands it to the ONE router
361
- * (`NextStepRouter.walk`) + the ONE renderer (`RouteRenderer`). The board forks
362
- * ZERO transition rule: the face order and the frontier/entrance/anchor decision are
363
- * the router's (D26 — one fact, one place). A line still in flight renders its next
364
- * C5 hop (a fresh wave's `implement --plan <plan> --tasks <ids>`, an in-flight
365
- * wave's `review`/`fix`, a fresh doc line's `review --type <type> …`); a face
366
- * ENTERED but with no active hop renders its own pipeline exit; a face NOT yet
367
- * entered (an absent doc) renders the PRECEDING entered face's exit (so a
368
- * just-closed spec hands off to `cdd-plan`, never the absent plan's `cdd-dev`); all
369
- * faces closed renders the last face's exit (the pipeline terminus). */
370
- static #nextOf(ledger, waves, sources, words, host, channels, root) {
371
- const renderer = new RouteRenderer(words, channels, host, root);
534
+ /** pipelineFacts(index, entry, root) — the board's per-face OBSERVATION of the
535
+ * pipeline (spec §5.2): each face's closed fact, its ACTIVE C5 hop (the SAME
536
+ * state→next chain the dispatch engine walks — `Ledger#lineRoute` for the
537
+ * doc/branch lines, the plan frontier + `Ledger#waveLineRoute` for the wave line)
538
+ * and its render target, keyed by the ONE `PIPELINE_FACES` key set. The board
539
+ * reports facts; the traversal (the four face-order rules) and the ONE hop
540
+ * derivation belong to the assembly face. Null when the node holds no legal slug
541
+ * (no workspace to observe). */
542
+ static pipelineFacts(index, entry, root) {
543
+ const nodeSlug = BoardView.#validSlug(entry);
544
+ if (nodeSlug === null)
545
+ return null;
546
+ const ledger = BoardView.#ledgerOf(nodeSlug, root.absolute);
547
+ const sources = BoardView.#nodeSources(index, entry);
548
+ const progress = ledger.readProgress();
549
+ const waves = BoardView.#waveLines(sources.plan?.path ?? null, progress, ledger);
372
550
  const specPath = sources.spec?.path ?? null;
373
551
  const planPath = sources.plan?.path ?? null;
552
+ // The identity line's OWN word — the document's DECLARED `doc-type:` — keys the
553
+ // line and names the pipeline station (`single-spec` closes onto its `done` row).
554
+ const specType = BoardView.#lineWordOf(sources.spec);
374
555
  // The plan's open frontier wave — the SAME ready batch the dispatch engine's
375
556
  // task-graph frontier yields (frontier over closedWaves()).
376
557
  const waveKey = BoardView.#waveFrontierKey(ledger, planPath);
377
- // The observed faces keyed by their `PIPELINE_FACES` key — the router owns the
378
- // order, so the board re-declares none (it only reports facts).
379
558
  const report = {
559
+ // The report KEY is the pipeline POSITION (the first face — `PIPELINE_FACES`);
560
+ // the line's type/key/target cells are the declaration the document carries.
380
561
  "phase-spec": {
381
- closed: ledger.lineClosed("spec", "spec"),
382
- active: specPath === null ? null : ledger.lineRoute("spec", "spec"),
383
- target: specPath === null ? null : { type: "spec", id: specPath },
562
+ closed: ledger.lineClosed(specType, specType),
563
+ active: specPath === null ? null : ledger.lineRoute(specType, specType),
564
+ target: specPath === null ? null : { type: specType, id: specPath },
384
565
  },
385
566
  plan: {
386
567
  closed: ledger.lineClosed("plan", "plan"),
@@ -396,13 +577,15 @@ export class BoardView {
396
577
  target: planPath === null ? null : { type: "wave", id: waveKey ?? "", plan: planPath },
397
578
  },
398
579
  branch: {
399
- closed: ledger.lineClosed("branch", "branch"),
580
+ // The branch line's closure is judged AT its identity document (the plan): a
581
+ // plan revision past the one the completed branch review bound reopens the
582
+ // face, so the mark above and this frontier cell read ONE judgment.
583
+ closed: ledger.lineStateAt("branch", "branch", planPath) === "closed",
400
584
  active: ledger.lineRoute("branch", "branch"),
401
585
  target: { type: "branch", id: "branch", plan: planPath ?? undefined },
402
586
  },
403
587
  };
404
- const next = NextStepRouter.walk(report);
405
- return renderer.render(next.route, next.target);
588
+ return { ledger, report };
406
589
  }
407
590
  /** The plan's open frontier wave key — the ready batch over the node's `closedWaves()`
408
591
  * set, the SAME derivation the dispatch engine's task-graph frontier walks (T26, the
@@ -440,17 +623,15 @@ export class BoardView {
440
623
  marker: null,
441
624
  };
442
625
  }
443
- /** The node's row rounds for one key — array-form ONLY (a non-array verb value —
444
- * the retired numeric form — is dropped: zero count renders, no compatibility
445
- * layer). An absent row/verb yields an empty map. */
446
- static #rowRounds(progress, key) {
447
- const row = progress?.waves.find((candidate) => candidate.wave === key);
448
- const rounds = {};
449
- for (const [verb, value] of Object.entries(row?.rounds ?? {})) {
450
- if (Array.isArray(value))
451
- rounds[verb] = [...value];
452
- }
453
- return rounds;
626
+ /** The node's round RECORDS for one key — read through the ledger's ONE row lookup
627
+ * (`Ledger.rowFor`: the retired `spec` row reads as the line its workspace DECLARES)
628
+ * and the ONE record normalizer (`RoundRecords.of`, legacy forms folded); the
629
+ * aggregation and the judgement glyphs read these records, never a pre-grouped cycle
630
+ * map. Failed rounds stay on the board (they consumed an identity slot); an absent row
631
+ * yields an empty list. */
632
+ static #rowRounds(progress, key, identity = null) {
633
+ const row = progress === null ? undefined : Ledger.rowFor(progress, key, identity);
634
+ return RoundRecords.of(row);
454
635
  }
455
636
  /** The node's wave segment — one line per derived wave (its ✔/▶/○ marker rides the
456
637
  * SAME `TaskGraph.report(closedWaves())` read the board and the pre-flight gate
@@ -481,3 +662,92 @@ export class BoardView {
481
662
  });
482
663
  }
483
664
  }
665
+ /**
666
+ * BoardNext — the board's next-hop assembly face (P22 §5.2): the retired router
667
+ * `walk`'s four face-order rules, re-homed at the board's CONSTRUCTION face. The
668
+ * board (`BoardView`) only REPORTS each pipeline face's facts; `BoardNext` decides
669
+ * the next pipeline step (iterating the ONE `PIPELINE_FACES` order imported from
670
+ * the session plane, never a second order declaration) and hands the result to the
671
+ * ONE derivation (`Ledger#nextHopOf` → `NextStepRouter#nextHop`), so the board's
672
+ * `next:` and the capsule's `next:` render ONE object. The composition root's board
673
+ * assembly point (`face/cli.ts` `#runBoard`) constructs it.
674
+ */
675
+ // biome-ignore lint/complexity/noStaticOnlyClass: the board's assembly fact surface — the zero-bare-function discipline admits no standalone functions here.
676
+ export class BoardNext {
677
+ /** The board's ONE `NextHop` — null when the entry holds no legal slug (no
678
+ * workspace to observe) or the board is the program board (cross-phase never
679
+ * participates in next, spec §6.5). */
680
+ static of(index, entry, root) {
681
+ const facts = entry.docType === "overall" ? null : BoardView.pipelineFacts(index, entry, root);
682
+ return facts === null ? null : BoardNext.#hopOf(facts, root);
683
+ }
684
+ /** The derivation's input face — the walked route + target, the ledger's own
685
+ * round facts and the declaration-reading station discrimination. The
686
+ * `verdict → face` assembly lives in the ONE derivation (`Ledger#nextHopOf`), so
687
+ * this face fills facts only. */
688
+ static #hopOf(facts, root) {
689
+ const next = BoardNext.#pipeline(facts.report);
690
+ const target = next.target;
691
+ return facts.ledger.nextHopOf({
692
+ type: target?.type ?? "branch",
693
+ key: target?.type === "wave" ? target.id : (target?.type ?? "branch"),
694
+ route: next.route,
695
+ target,
696
+ doc: target === null ? null : target.type === "branch" ? (target.plan ?? null) : target.id,
697
+ docClassOf: (candidate) => BoardView.docClassOf(root, candidate),
698
+ });
699
+ }
700
+ /** The pipeline's face-to-face traversal (D40 · P22 §5.2) — the four face-order
701
+ * rules over the ONE `PIPELINE_FACES` order the caller REPORTS facts against:
702
+ * · the FRONTIER face (first not-closed) with an active C5 hop renders that hop
703
+ * (the in-flight work — `review` / `fix` / `implement` / `next-wave`);
704
+ * · the frontier has no active hop but IS entered (a target is present) → its
705
+ * OWN pipeline exit entry;
706
+ * · the frontier is NOT entered (no target — an absent doc) → the transition
707
+ * INTO it: the PRECEDING entered face's exit entry (a just-closed spec hands
708
+ * off to `cdd-plan`, never the absent plan's `cdd-dev`); none preceding → the
709
+ * FIRST face's exit entry;
710
+ * · every face closed → the LAST entered face's exit entry (the terminus —
711
+ * `cdd-close` for a phase slug).
712
+ * The order stays `PIPELINE_FACES`' (imported, never re-declared here). */
713
+ static #pipeline(report) {
714
+ const states = PIPELINE_FACES.map((key) => report[key]);
715
+ const frontierIndex = states.findIndex((face) => !face.closed);
716
+ if (frontierIndex === -1) {
717
+ const terminalIndex = BoardNext.#lastEnteredIndex(states);
718
+ const terminal = terminalIndex === -1 ? null : states[terminalIndex];
719
+ return terminal === null
720
+ ? { route: { kind: "done" }, target: null }
721
+ : { route: BoardNext.#exitRoute(terminalIndex, terminal), target: terminal.target };
722
+ }
723
+ const frontier = states[frontierIndex];
724
+ if (frontier.active !== null)
725
+ return { route: frontier.active, target: frontier.target };
726
+ const anchorIndex = frontier.target !== null
727
+ ? frontierIndex
728
+ : Math.max(0, BoardNext.#lastEnteredIndex(states.slice(0, frontierIndex)));
729
+ const anchor = states[anchorIndex];
730
+ return { route: BoardNext.#exitRoute(anchorIndex, anchor), target: anchor.target };
731
+ }
732
+ /** The anchor face's OWN pipeline exit — the row its render TARGET declares
733
+ * (`PIPELINE_NEXT[target.type]`, the SAME one table the capsule's `done` face reads
734
+ * through the ONE derivation). The identity face's target type IS the document's
735
+ * declared word, so a `single-spec` closes onto its `done` row, never the phase-spec
736
+ * line's `cdd-plan` ref; every node face's target type is its face key, so the lookup
737
+ * is the face key there. A face with no target (never entered) falls back to its
738
+ * pipeline face's row. */
739
+ static #exitRoute(faceIndex, state) {
740
+ if (state.target === null)
741
+ return NextStepRouter.handoff(PIPELINE_FACES[faceIndex]);
742
+ return { kind: "handoff", entry: PIPELINE_NEXT[state.target.type] };
743
+ }
744
+ /** The index of the last OBSERVED face carrying a render target — the last face the
745
+ * pipeline has REACHED (a face with no target was never entered). -1 when none is. */
746
+ static #lastEnteredIndex(states) {
747
+ for (let i = states.length - 1; i >= 0; i--) {
748
+ if (states[i].target !== null)
749
+ return i;
750
+ }
751
+ return -1;
752
+ }
753
+ }