@oscaner-skills/cdd-engine 4.2.0 → 4.4.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 (58) hide show
  1. package/README.md +38 -9
  2. package/README.zh-CN.md +44 -10
  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 +382 -172
  25. package/dist/face/capsule.js +73 -88
  26. package/dist/face/cli.js +152 -38
  27. package/dist/face/declare.js +42 -19
  28. package/dist/face/gate.js +119 -40
  29. package/dist/face/init.js +84 -25
  30. package/dist/face/lifecycle.js +540 -123
  31. package/dist/face/plugins.js +70 -2
  32. package/dist/face/preview.js +69 -18
  33. package/dist/face/route-render.js +60 -21
  34. package/dist/face/termination.js +135 -261
  35. package/dist/face/words.js +139 -13
  36. package/dist/infra/atomic.js +15 -0
  37. package/dist/infra/git.js +25 -0
  38. package/dist/infra/proc.js +150 -0
  39. package/dist/infra/round-log.js +104 -0
  40. package/dist/infra/runtime.js +16 -4
  41. package/dist/infra/workspace.js +7 -2
  42. package/dist/render/brief.js +15 -17
  43. package/dist/render/skeleton.js +41 -28
  44. package/dist/render/templates.js +128 -84
  45. package/dist/session/faces.js +47 -20
  46. package/dist/session/graph.js +13 -37
  47. package/dist/session/handoff-schema.js +16 -8
  48. package/dist/session/inflight.js +282 -0
  49. package/dist/session/ledger.js +603 -145
  50. package/dist/session/line-identity.js +33 -0
  51. package/dist/session/next.js +140 -80
  52. package/dist/session/pipeline.js +247 -0
  53. package/dist/session/preflight.js +276 -68
  54. package/dist/session/reviewed-identity.js +54 -0
  55. package/dist/session/round-naming.js +56 -8
  56. package/dist/session/run.js +364 -80
  57. package/dist/session/wave.js +94 -14
  58. package/package.json +13 -3
@@ -8,25 +8,34 @@
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 in the session
19
+ // plane (`session/pipeline.ts` `PipelineFrontier`), the ONE derivation is
20
+ // `NextStepRouter#nextHop`, and the ONE literal renderer is `RouteRenderer` (shared
21
+ // with the capsule). The board only OBSERVES each face's facts (`pipelineFacts`)
22
+ // and renders.
26
23
  //
27
- // Module-level exports are types / constants / the class — zero behavior-carrying
24
+ // P22 §5.3 — the default layout aggregates each line's rounds BY VERB (the judgement
25
+ // glyph is mandatory, the findings count rides a `+N` suffix, a plain token carries the
26
+ // last record's `a{attempt}` superscript); range forms never render (there is no
27
+ // `--verbose` in this phase). P24 §12 splits that aggregation into two shapes: the
28
+ // success face merges per verb — an `{ok}/{attempts}` ratio with NO superscript once
29
+ // the verb has a failed attempt — and the anomaly face expands one token per failed
30
+ // attempt, each naming its own cycle and, past the first, its own `a{attempt}`
31
+ // (`fix 12 ✗→✓` when that cycle's next attempt completed). Each wave line's label
32
+ // carries the wave's task scope in braces (`W1 {5,11}`) with the ✔/▶/○ marker
33
+ // column fixed-width aligned.
34
+ //
35
+ // Module-level exports are types / constants / the classes — zero behavior-carrying
28
36
  // bare functions (the plan's zero-bare-function discipline).
29
37
  import { readFileSync } from "node:fs";
38
+ import path from "node:path";
30
39
  import { PlanDocType } from "../contract/doc.js";
31
40
  import { FrontMatterExtractor } from "../contract/frontmatter.js";
32
41
  import { DOC_KEYS } from "../contract/project.js";
@@ -36,13 +45,17 @@ import { ENGINE_RUNTIME } from "../infra/runtime.js";
36
45
  import { SlugIndex } from "../infra/slug-index.js";
37
46
  import { Workspace, WorkspaceRoot } from "../infra/workspace.js";
38
47
  import { TaskGraph } from "../session/graph.js";
39
- import { Ledger } from "../session/ledger.js";
40
- import { NextStepRouter } from "../session/next.js";
48
+ import { Ledger, RoundRecords } from "../session/ledger.js";
49
+ import { PipelineFrontier } from "../session/pipeline.js";
41
50
  import { PROGRESS_LEGEND, PROGRESS_MARKERS } from "./graph-view.js";
42
51
  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). */
52
+ /** The verb render order of a line's rounds tokens — the stable display order the
53
+ * board's aggregated cells follow (an unexpected verb appends after these, never
54
+ * dropped). */
45
55
  const VERB_ORDER = ["implement", "review", "branch-review", "fix"];
56
+ /** The judgement glyphs of one aggregated token (spec §5.3 — the mark is MANDATORY:
57
+ * `✓` a completed round, `✗` a round that failed its target action). */
58
+ const JUDGEMENT_MARKERS = { passed: "✓", failed: "✗", recovered: "✗→✓" };
46
59
  /** The DocKey domain of the `doc-type:` declaration — the declared value must
47
60
  * be one of the four keys; anything else reads null (present facts, never a
48
61
  * fabricated type). Derived from the ONE DocKey declaration (contract/project.ts
@@ -58,6 +71,9 @@ const MARK_DOC_TYPE_MISSING = "doc-type: missing (BLOCKED)";
58
71
  /** The program board's phase-title annotation cap — the `title:` note renders
59
72
  * truncated to this many characters (an ellipsis marks the cut). */
60
73
  const PHASE_TITLE_MAX = 60;
74
+ /** The label column of the board's line rows — ` ` + the label padded to this
75
+ * width (`overall` is the longest verb at 7), so every value starts in one column. */
76
+ const LABEL_WIDTH = 9;
61
77
  /**
62
78
  * BoardView — the entry-document → board face. The identity index (`SlugIndex`)
63
79
  * is the ONLY node source: the entry document's declared `doc-type:` picks the
@@ -78,6 +94,28 @@ export class BoardView {
78
94
  static readDocType(root, rel) {
79
95
  return BoardView.#docTypeOf(FrontMatterExtractor.split(BoardView.#read(root.resolve(rel)) ?? "").head.docType);
80
96
  }
97
+ /** docClassOf(root, target) — the pipeline-station discrimination of one render
98
+ * target (spec §5.2 · D33): a doc shape's class reads its DECLARED type (the
99
+ * front-matter `doc-type:` key — the ONE declaration reading face above), never
100
+ * the filename suffix or the `--type` spelling; the node shapes key by their own
101
+ * type. `blocked` — the key is missing (the renderer prints the BLOCKED face);
102
+ * `terminal` — no pipeline seam carries the declared class (`single-spec`, the
103
+ * `PipelineKey` derivation excludes it). This is the injected seam of the ONE hop
104
+ * derivation: `session/next.ts` never imports a face class, and every read face
105
+ * shares this ONE judgment. The basis is REQUIRED — an unrooted resolve would read
106
+ * the target against `process.cwd()`, so an engine invoked from a subdirectory
107
+ * could report a declared line as `doc-class-blocked`; the root is always the value
108
+ * object the read face holds. */
109
+ static docClassOf(root, target) {
110
+ if (target.type === "plan")
111
+ return "plan";
112
+ if (target.type === "wave")
113
+ return "wave";
114
+ if (target.type === "branch")
115
+ return "branch";
116
+ const declared = BoardView.readDocType(root, root.relativize(target.id));
117
+ return declared === null ? "blocked" : declared === "single-spec" ? "terminal" : declared;
118
+ }
81
119
  /** The doc file's raw text — an absent/unreadable file reads null (the reads
82
120
  * above degrade to null facts, never a throw). */
83
121
  static #read(docPath) {
@@ -139,47 +177,200 @@ export class BoardView {
139
177
  return MARK_DOC_TYPE_MISSING;
140
178
  return index.duplicatedRolesOf(entry.slug).includes(role) ? MARK_SLUG_DUPLICATED : null;
141
179
  }
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. */
180
+ /** The identity document's line word — its DECLARED `doc-type:` (spec §12 · D34), the
181
+ * ONE word the line keys under (`run.ts`'s `#lineKey`) and the word the pipeline
182
+ * station follows. `phase-spec` is the degradation default for an absent or
183
+ * undeclared document (that line renders `(none)` / its BLOCKED marker anyway) — it
184
+ * is never a translation of a declared word. */
185
+ static #lineWordOf(entry) {
186
+ return entry?.docType ?? "phase-spec";
187
+ }
188
+ /** One doc line — the header facts read from the indexed entry + the row's round
189
+ * RECORDS keyed by the line's `progress.json` key, resolved with the line's DECLARED
190
+ * word as the retired-key alias basis (a charter's pre-rename `spec` row is its own
191
+ * `overall` line). */
144
192
  static #lineOf(label, key, entry, progress) {
145
193
  return {
146
194
  label,
147
195
  version: entry?.version ?? null,
148
196
  status: entry?.status ?? null,
149
197
  docType: entry?.docType ?? null,
150
- rounds: BoardView.#rowRounds(progress, key),
198
+ rounds: BoardView.#rowRounds(progress, key, entry?.docType ?? null),
151
199
  marker: null,
152
200
  };
153
201
  }
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}`);
202
+ /** summaryCell(records) — the line's aggregated rounds cell (P24 §12): the SUCCESS
203
+ * face of each verb merges into at most one token (never rendered at zero successes),
204
+ * the ANOMALY face expands one token per failed attempt. Tokens are verb-major in
205
+ * `VERB_ORDER`, a verb's success token before its failures, those in stored order. The
206
+ * range form (`review 1–10 ✓`) never renders: the aggregation IS the count. */
207
+ static summaryCell(records) {
208
+ const tokens = [];
209
+ const extra = [...new Set(records.map((record) => record.op))].filter((op) => !VERB_ORDER.includes(op));
210
+ for (const verb of [...VERB_ORDER, ...extra]) {
211
+ const faces = BoardView.#judgementRuns(records.filter((record) => record.op === verb));
212
+ tokens.push(...BoardView.#verbTokens(verb, faces));
213
+ }
214
+ return tokens.join(" · ");
215
+ }
216
+ /** One verb's tokens — its success token (absent at zero successes) followed by one
217
+ * token per failed attempt, so a failure never drifts to the line's tail (P24 §12). */
218
+ static #verbTokens(verb, faces) {
219
+ const tokens = [];
220
+ const success = BoardView.#successToken(verb, faces);
221
+ if (success !== null)
222
+ tokens.push(success);
223
+ for (const record of faces.failures) {
224
+ tokens.push(BoardView.#failureToken(verb, record, faces.successes));
225
+ }
226
+ return tokens;
227
+ }
228
+ /** One verb's success token — absent when no round of the verb succeeded (a
229
+ * failure-only verb renders its `✗` tokens alone), the plain count plus the LAST
230
+ * success's attempt superscript when the verb has no failed attempt, and the
231
+ * `{succeeded}/{attempts}` ratio — never a superscript — once it has one (P24 §12).
232
+ * Its `+N` counts the SUCCESS records' carriers alone; a failed attempt's findings
233
+ * already ride that attempt's own token. */
234
+ static #successToken(verb, faces) {
235
+ const count = faces.successes.length;
236
+ if (count === 0)
237
+ return null;
238
+ const last = faces.successes[count - 1];
239
+ const body = faces.failures.length === 0
240
+ ? `${count}${BoardView.attemptSuffix(last)}`
241
+ : `${count}/${count + faces.failures.length}`;
242
+ return BoardView.#summaryToken(verb, body, JUDGEMENT_MARKERS.passed, faces.successes);
243
+ }
244
+ /** One failed attempt's token — `{verb} {cycle}{aN} ✗{+N}`, the cycle naming the round
245
+ * that failed rather than a re-counted segment, and `✗→✓` when the SAME cycle's next
246
+ * attempt (`attempt + 1`) completed: recovery reads exactly that one edge — a later
247
+ * cycle's success and a further same-cycle attempt are historical failures. The `+N`
248
+ * counts this record's own carrier alone, never erased by a later success (P24 §12). */
249
+ static #failureToken(verb, record, successes) {
250
+ const recovered = successes.some((other) => other.cycle === record.cycle && other.attempt === record.attempt + 1);
251
+ const mark = recovered ? JUDGEMENT_MARKERS.recovered : JUDGEMENT_MARKERS.failed;
252
+ const body = `${record.cycle}${BoardView.attemptSuffix(record)}`;
253
+ return BoardView.#summaryToken(verb, body, mark, [record]);
254
+ }
255
+ /** One token of a verb's success face or of one failed attempt, `{verb} {body} {mark}`
256
+ * (P24 §12). The `+N` suffix counts the run's graded FINDINGS, read from each round's
257
+ * own carrier (`carrierPath` → the handoff's `findings` array, spec §5.3) — never the
258
+ * round's hard/soft contract violations, which are a different fact. A record with no
259
+ * carrier (a legacy row, or a work-plane round whose carrier declares no findings)
260
+ * contributes zero. */
261
+ static #summaryToken(verb, body, mark, run) {
262
+ const findings = run.reduce((total, record) => total + BoardView.#findingsCountOf(record), 0);
263
+ const suffix = findings === 0 ? "" : `+${findings}`;
264
+ return `${verb} ${body} ${mark}${suffix}`;
265
+ }
266
+ /** One round's findings count — the `findings` array length of the carrier the round
267
+ * persisted (the judge plane's declared field). Zero when the record carries no
268
+ * carrier path or the file is absent/unreadable/unparseable (present facts only,
269
+ * never a throw on a read face). */
270
+ static #findingsCountOf(record) {
271
+ const at = record.carrierPath;
272
+ if (at === null)
273
+ return 0;
274
+ const text = BoardView.#read(at);
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
+ /** attemptSuffix(record) — the re-dispatch superscript: `attempt === 1` renders
287
+ * nothing (an `a1` never appears), otherwise `a{attempt}`. */
288
+ static attemptSuffix(record) {
289
+ return record.attempt === 1 ? "" : `a${record.attempt}`;
290
+ }
291
+ /** The judgement faces of one verb — the success face and the anomaly face, each in
292
+ * the stored (chronological) order: successes merge into ONE token per verb while
293
+ * failed attempts expand one token each (P24 §12). */
294
+ static #judgementRuns(records) {
295
+ return {
296
+ successes: records.filter((record) => record.verdict.targetAction),
297
+ failures: records.filter((record) => !record.verdict.targetAction),
298
+ };
299
+ }
300
+ /** nextLine(hop, renderer) — the board's `next:` row rendered from the INJECTED
301
+ * hop through the shared hop renderer (`RouteRenderer#renderHop`), so the board's
302
+ * line and the capsule's line are byte-identical by construction. Every embedded
303
+ * path value renders repoRoot-relative (the renderer's own basis). A hop the
304
+ * renderer renders as no line degrades to the same `(none)` bytes the absent-hop
305
+ * row carries — the row is never built from a null value. */
306
+ static nextLine(hop, renderer) {
307
+ const value = renderer.renderHop(hop) ?? "(none)";
308
+ return ` next: ${value}`;
309
+ }
310
+ /** reasonLine(hop) — the board's `reason:` row under `next:`: the hop's OWN named
311
+ * fact (`NextHop.reason`), the same field the capsule's `renderReason` row prints,
312
+ * so the two faces state one value by construction. The PREFIX is this face's own
313
+ * layout literal (` reason: ` — the same 11-column shape `nextLine` uses); the
314
+ * capsule takes its prefix from the word table instead, so each face keeps its own
315
+ * prefix and only the token is shared. A row exists only for an existing hop: the
316
+ * absent hop renders ` next: (none)` and NO reason row at all (the caller's
317
+ * null-next branch), never a half-built one. */
318
+ static reasonLine(hop) {
319
+ return ` reason: ${hop.reason}`;
320
+ }
321
+ /** inFlightRows(state, orphans, words) — the tree's dispatch fact + the
322
+ * workspace's orphan handoff drafts, as board lines. The held row names the
323
+ * holder's IDENTITY facts alone (the operating verb, the round's cycle + attempt
324
+ * cells a takeover has to answer for, the wave key and the pid, spec §5.3): the
325
+ * child's command line, its start instant and its plan path are dispatch
326
+ * narrative, not board facts. A DEAD holder adds the takeover hint. The free and
327
+ * corrupt rows are the word table's declared rows — the board's hint is the same
328
+ * bytes the preview face and the gate print (one vocabulary, never a board
329
+ * literal). The orphan rows are the drafts no recorded round owns — the board
330
+ * lists them, never writes or deletes them. */
331
+ static inFlightRows(state, orphans, words) {
332
+ const rows = [];
333
+ if (state.kind === "held") {
334
+ const record = state.record;
335
+ const dead = state.alive ? "" : ` — ${words.inFlightWords().stealable}`;
336
+ const identity = [
337
+ `pid ${record.pid}`,
338
+ `op: ${record.phase ?? "dispatch"}`,
339
+ record.cycle === null ? null : `cycle: ${record.cycle}`,
340
+ record.attempt === null ? null : `attempt: ${record.attempt}`,
341
+ `slug: ${record.slug}`,
342
+ `wave: ${record.wave ?? "none"}`,
343
+ ].filter((cell) => cell !== null);
344
+ rows.push(` in-flight: ${identity.join(" · ")}${dead}`);
165
345
  }
166
- return cells.join(" · ");
346
+ else if (state.kind === "corrupt") {
347
+ const inFlight = words.inFlightWords();
348
+ rows.push(` in-flight: ${state.locked ? inFlight.corruptLocked : inFlight.corruptUnlocked}`);
349
+ }
350
+ else {
351
+ rows.push(` in-flight: ${words.checkedWords().inFlight.free}`);
352
+ }
353
+ for (const orphan of orphans)
354
+ rows.push(` orphan: ${orphan} — no recorded round owns it`);
355
+ return rows;
167
356
  }
168
357
  // -------------------------------------------------------------------------
169
- // the render face (spec §5.3) — the entry document → board layout + next derivation
358
+ // the render face (spec §5.3) — the entry document → board layout + next render
170
359
  // -------------------------------------------------------------------------
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
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
174
363
  * 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
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
368
+ * board's `next:` and the engine's `next:` literal compose their argv from ONE
369
+ * flag-spelling source). A present doc line carrying a violation renders the
179
370
  * matching `(BLOCKED)` marker and the board exits 2 (spec §3.1 — the board's
180
371
  * reject face is exit 2, never the dispatch CDD_BLOCKED channel). Pure reads —
181
372
  * zero tree writes, zero ledger writes, zero child dispatch. */
182
- static render(index, entry, repoRoot, words, host, channels = {}) {
373
+ static render(index, entry, repoRoot, words, host, channels = {}, holding = { kind: "absent" }, next = null) {
183
374
  const lines = [`cdd board: ${entry.slug ?? "(none)"}`, ""];
184
375
  // The repo-basis value object — constructed ONCE at this boundary, the ONE
185
376
  // conversion exit the doc cells and the `next:` render normalize their embedded
@@ -189,63 +380,100 @@ export class BoardView {
189
380
  const root = new RepoRoot(repoRoot);
190
381
  const exitCode = entry.docType === "overall"
191
382
  ? BoardView.#programBoard(lines, index, entry, root)
192
- : BoardView.#nodeBoard(lines, index, entry, root, words, host, channels);
383
+ : BoardView.#nodeBoard(lines, index, entry, root, words, host, channels, holding, next);
193
384
  lines.push("", PROGRESS_LEGEND.board);
194
385
  return { lines, exitCode };
195
386
  }
196
387
  /** 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
388
+ * render (spec §3.1.1). The node's identity chain comes from the index
198
389
  * (`program:` → overall; same slug → spec / plan); a missing link renders
199
390
  * `(none)` and stays exit 0, while a violated line renders its marker and exits
200
391
  * 2. The repo-basis `root` is threaded alone (F2) — its `absolute` feeds the
201
392
  * fs-facing helpers, its value object the path renders. */
202
- static #nodeBoard(lines, index, entry, root, words, host, channels) {
393
+ static #nodeBoard(lines, index, entry, root, words, host, channels, holding, next) {
203
394
  const repoRoot = root.absolute;
204
395
  const sources = BoardView.#nodeSources(index, entry);
205
396
  const nodeSlug = BoardView.#validSlug(entry);
206
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).
400
+ const orphans = ledger?.orphanHandoffs() ?? [];
401
+ for (const row of BoardView.inFlightRows(holding, orphans, words))
402
+ lines.push(row);
403
+ if (holding.kind !== "absent" || orphans.length > 0)
404
+ lines.push("");
207
405
  const progress = ledger?.readProgress() ?? null;
208
406
  const overallSlug = BoardView.#validSlug(sources.overall);
209
407
  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);
408
+ const docRows = [
409
+ {
410
+ label: "overall",
411
+ entry: sources.overall,
412
+ line: BoardView.#lineOf("overall", "overall", sources.overall, overallProgress),
413
+ mark: BoardView.#entryMark(index, sources.overall, "identity"),
414
+ },
415
+ {
416
+ label: "spec",
417
+ 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),
421
+ },
422
+ {
423
+ label: "plan",
424
+ entry: sources.plan,
425
+ line: BoardView.#lineOf("plan", "plan", sources.plan, progress),
426
+ mark: BoardView.#entryMark(index, sources.plan, "plan"),
427
+ },
428
+ ];
429
+ // The doc-name column is fixed-width: every name is padded to the widest one, so
430
+ // the version column aligns down the block (spec §5.3).
431
+ const nameWidth = Math.max(0, ...docRows
432
+ .filter((row) => row.entry !== null)
433
+ .map((row) => path.basename(row.entry.path).length));
214
434
  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;
435
+ for (const row of docRows) {
436
+ const cell = BoardView.#docCell(row.entry, row.line, nameWidth, row.mark);
437
+ lines.push(` ${row.label.padEnd(LABEL_WIDTH)}${cell.text}`.trimEnd());
438
+ blocked ||= cell.blocked;
439
+ }
226
440
  const waves = BoardView.#waveLines(sources.plan?.path ?? null, progress, ledger);
227
441
  if (waves.length === 0) {
228
- lines.push(" wave (none)");
442
+ lines.push(` ${"wave".padEnd(LABEL_WIDTH)}(none)`);
229
443
  }
230
444
  else {
231
445
  // 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).
446
+ // label so the ✔/▶/○ markers align into one column (spec §5.3 · D40).
233
447
  const labelWidth = Math.max(...waves.map((wave) => wave.label.length));
234
448
  waves.forEach((wave, index) => {
235
- const prefix = index === 0 ? " wave " : " ";
236
- const cell = BoardView.roundsCell(wave.rounds);
449
+ const prefix = index === 0 ? ` ${"wave".padEnd(LABEL_WIDTH)}` : " ".repeat(2 + LABEL_WIDTH);
450
+ const cell = BoardView.summaryCell(wave.rounds);
237
451
  const label = wave.label.padEnd(labelWidth);
238
452
  lines.push(`${prefix}${label} ${wave.marker ?? ""}${cell === "" ? "" : ` ${cell}`}`.trimEnd());
239
453
  });
240
454
  }
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());
455
+ const branchLine = BoardView.#roundsLine("branch", "branch", progress);
456
+ // The branch line's mark is the SAME drift-aware judgment its pipeline facts read
457
+ // (`Ledger#lineStateAt`, identity document = the plan): a drifted plan reopens the
458
+ // branch face, so the mark can never print `✔ closed` while `next:` names the
459
+ // review the gate accepts — the reopened line renders as the CURRENT face (`▶`).
460
+ const branchState = ledger?.lineStateAt("branch", "branch", sources.plan?.path ?? null) ?? "open";
461
+ const branchMark = branchState === "closed"
462
+ ? `${PROGRESS_MARKERS.done} closed`
463
+ : branchState === "reopened"
464
+ ? `${PROGRESS_MARKERS.current} open`
465
+ : `${PROGRESS_MARKERS.pending} open`;
466
+ const branchRounds = BoardView.summaryCell(branchLine.rounds);
467
+ lines.push(` ${"branch".padEnd(LABEL_WIDTH)}${branchMark}${branchRounds === "" ? "" : ` ${branchRounds}`}`.trimEnd());
244
468
  lines.push("");
245
- const next = ledger === null
246
- ? "(none)"
247
- : BoardView.#nextOf(ledger, waves, sources, words, host, channels, root);
248
- lines.push(` next: ${next}`);
469
+ if (next === null) {
470
+ lines.push(" next: (none)");
471
+ }
472
+ else {
473
+ const renderer = new RouteRenderer(words, channels, host, root);
474
+ lines.push(BoardView.nextLine(next, renderer));
475
+ lines.push(BoardView.reasonLine(next));
476
+ }
249
477
  return blocked ? 2 : 0;
250
478
  }
251
479
  /** The program board render — the overall line (its own rounds) + one summary line
@@ -258,9 +486,9 @@ export class BoardView {
258
486
  const repoRoot = root.absolute;
259
487
  const overallSlug = BoardView.#validSlug(entry);
260
488
  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}`);
489
+ const overallLine = BoardView.#lineOf("overall", "overall", entry, ledger?.readProgress() ?? null);
490
+ const overallDoc = BoardView.#docCell(entry, overallLine, path.basename(entry.path).length, BoardView.#entryMark(index, entry, "identity"));
491
+ lines.push(` ${"overall".padEnd(LABEL_WIDTH)}${overallDoc.text}`);
264
492
  lines.push("");
265
493
  let blocked = overallDoc.blocked;
266
494
  const phases = overallSlug === null ? [] : index.phaseSpecsOf(overallSlug);
@@ -268,7 +496,7 @@ export class BoardView {
268
496
  const phaseSlug = BoardView.#validSlug(phase);
269
497
  const phaseLedger = phaseSlug === null ? null : BoardView.#ledgerOf(phaseSlug, repoRoot);
270
498
  const phaseProgress = phaseLedger?.readProgress() ?? null;
271
- const specLine = BoardView.#lineOf("spec", "spec", phase, phaseProgress);
499
+ const specLine = BoardView.#lineOf("spec", "phase-spec", phase, phaseProgress);
272
500
  const planEntry = phaseSlug === null ? null : index.planOf(phaseSlug);
273
501
  const planLine = BoardView.#lineOf("plan", "plan", planEntry, phaseProgress);
274
502
  const branchLine = BoardView.#roundsLine("branch", "branch", phaseProgress);
@@ -284,10 +512,10 @@ export class BoardView {
284
512
  const waveCell = waves.length === 0 ? "" : `${waves[0].label.split(" ")[0]}…`;
285
513
  const parts = [];
286
514
  const cells = [
287
- ["spec", BoardView.roundsCell(specLine.rounds)],
288
- ["plan", BoardView.roundsCell(planLine.rounds)],
515
+ ["spec", BoardView.summaryCell(specLine.rounds)],
516
+ ["plan", BoardView.summaryCell(planLine.rounds)],
289
517
  ["wave", waveCell],
290
- ["branch", BoardView.roundsCell(branchLine.rounds)],
518
+ ["branch", BoardView.summaryCell(branchLine.rounds)],
291
519
  ];
292
520
  for (const [key, cell] of cells)
293
521
  if (cell !== "")
@@ -320,29 +548,25 @@ export class BoardView {
320
548
  ? trimmed
321
549
  : `${trimmed.slice(0, PHASE_TITLE_MAX - 1)}…`;
322
550
  }
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) {
551
+ /** One doc line's cell text — the doc NAME (directory omitted, spec §5.3), the
552
+ * header facts and the line's aggregated rounds (`spec prog-p1-design.md v0.14 ·
553
+ * Draft review 2 ✓`). The name is padded to the block's name column so the
554
+ * version column aligns; a violated line renders its `(BLOCKED)` marker in place
555
+ * of the rounds (blocked = true). An absent doc renders `(none)` (degradation,
556
+ * never a throw). */
557
+ static #docCell(entry, line, nameWidth, mark) {
329
558
  if (entry === null)
330
559
  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);
560
+ const name = path.basename(entry.path).padEnd(nameWidth);
561
+ const meta = [line.version, line.status].filter((part) => part !== null).join(" · ");
337
562
  if (mark !== null) {
338
- const head = facts.length === 0 ? "" : `${facts.join(" · ")} `;
339
- return { text: `${rel} ${head}${mark}`, blocked: true };
563
+ const head = meta === "" ? "" : `${meta} `;
564
+ return { text: `${name} ${head}${mark}`, blocked: true };
340
565
  }
341
- const cells = [rel];
342
- const meta = [line.version, line.status].filter((part) => part !== null).join(" · ");
566
+ const cells = [name];
343
567
  if (meta !== "")
344
568
  cells.push(meta);
345
- const rounds = BoardView.roundsCell(line.rounds);
569
+ const rounds = BoardView.summaryCell(line.rounds);
346
570
  if (rounds !== "")
347
571
  cells.push(rounds);
348
572
  return { text: cells.join(" "), blocked: false };
@@ -353,73 +577,34 @@ export class BoardView {
353
577
  const root = new WorkspaceRoot(repoRoot, ENGINE_RUNTIME.handoffNamespace.workspaceRoot);
354
578
  return new Ledger(new Workspace(root, nodeSlug), new ConfigLoader());
355
579
  }
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);
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
584
+ * session plane's `PipelineFrontier`. Null when the node holds no legal slug (no
585
+ * workspace to observe). */
586
+ static pipelineFacts(index, entry, root) {
587
+ const nodeSlug = BoardView.#validSlug(entry);
588
+ if (nodeSlug === null)
589
+ return null;
590
+ const ledger = BoardView.#ledgerOf(nodeSlug, root.absolute);
591
+ const sources = BoardView.#nodeSources(index, entry);
372
592
  const specPath = sources.spec?.path ?? null;
373
593
  const planPath = sources.plan?.path ?? null;
374
- // The plan's open frontier wave — the SAME ready batch the dispatch engine's
375
- // task-graph frontier yields (frontier over closedWaves()).
376
- 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
- const report = {
380
- "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 },
384
- },
385
- plan: {
386
- closed: ledger.lineClosed("plan", "plan"),
387
- active: planPath === null ? null : ledger.lineRoute("plan", "plan"),
388
- target: planPath === null ? null : { type: "plan", id: planPath, plan: planPath },
389
- },
390
- wave: {
391
- // The wave face is exhausted (skipped) only when the plan yields a wave set
392
- // and every wave is done — an empty wave segment (no plan) is not an exhausted
393
- // face (nothing was closed), so it stays the frontier and hands off.
394
- closed: waves.length > 0 && waves.every((wave) => wave.marker === PROGRESS_MARKERS.done),
395
- active: waveKey === null ? null : ledger.waveLineRoute(waveKey),
396
- target: planPath === null ? null : { type: "wave", id: waveKey ?? "", plan: planPath },
397
- },
398
- branch: {
399
- closed: ledger.lineClosed("branch", "branch"),
400
- active: ledger.lineRoute("branch", "branch"),
401
- target: { type: "branch", id: "branch", plan: planPath ?? undefined },
402
- },
594
+ // The identity line's OWN word — the document's DECLARED `doc-type:` — keys the
595
+ // line and names the pipeline station (`single-spec` closes onto its `done` row).
596
+ const specType = BoardView.#lineWordOf(sources.spec);
597
+ return {
598
+ ledger,
599
+ input: { specType, specPath, planPath, planGraph: BoardView.planGraph(planPath) },
403
600
  };
404
- const next = NextStepRouter.walk(report);
405
- return renderer.render(next.route, next.target);
406
- }
407
- /** The plan's open frontier wave key — the ready batch over the node's `closedWaves()`
408
- * set, the SAME derivation the dispatch engine's task-graph frontier walks (T26, the
409
- * wave-unitary model). Null when the plan is absent or no wave remains open — the wave
410
- * face then holds no active hop (a not-yet-started wave line hands off to the next face). */
411
- static #waveFrontierKey(ledger, planPath) {
412
- const graph = BoardView.#planGraph(planPath);
413
- if (graph === null)
414
- return null;
415
- const frontier = graph.frontier(ledger.closedWaves());
416
- return frontier.length === 0 ? null : frontier.join(",");
417
- }
418
- /** The plan's task graph — the ONE guarded plan read shared by the wave frontier
419
- * key and the wave segment (`readFileSync` throwing on an unreadable plan is
420
- * caught here: a null plan path or an unreadable/absent file yields null, honoring
421
- * the wave face's "degradation, never a throw" contract). */
422
- static #planGraph(planPath) {
601
+ }
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) {
423
608
  if (planPath === null)
424
609
  return null;
425
610
  try {
@@ -440,24 +625,22 @@ export class BoardView {
440
625
  marker: null,
441
626
  };
442
627
  }
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;
628
+ /** The node's round RECORDS for one key — read through the ledger's ONE row lookup
629
+ * (`Ledger.rowFor`: the retired `spec` row reads as the line its workspace DECLARES)
630
+ * and the ONE record normalizer (`RoundRecords.of`, legacy forms folded); the
631
+ * aggregation and the judgement glyphs read these records, never a pre-grouped cycle
632
+ * map. Failed rounds stay on the board (they consumed an identity slot); an absent row
633
+ * yields an empty list. */
634
+ static #rowRounds(progress, key, identity = null) {
635
+ const row = progress === null ? undefined : Ledger.rowFor(progress, key, identity);
636
+ return RoundRecords.of(row);
454
637
  }
455
638
  /** The node's wave segment — one line per derived wave (its ✔/▶/○ marker rides the
456
639
  * SAME `TaskGraph.report(closedWaves())` read the board and the pre-flight gate
457
640
  * share — the same source GraphView renders from), the wave's own `progress.json`
458
641
  * row spread alongside. No plan → empty segment (degradation, never a throw). */
459
642
  static #waveLines(planPath, progress, ledger) {
460
- const graph = BoardView.#planGraph(planPath);
643
+ const graph = BoardView.planGraph(planPath);
461
644
  if (graph === null)
462
645
  return [];
463
646
  const report = graph.report(ledger === null ? new Set() : ledger.closedWaves());
@@ -481,3 +664,30 @@ export class BoardView {
481
664
  });
482
665
  }
483
666
  }
667
+ /**
668
+ * BoardNext — the board's hop entry point (P22 §5.2 · P24 §11): the board (`BoardView`)
669
+ * REPORTS the pipeline facts, and the session plane's `PipelineFrontier` both decides
670
+ * the next pipeline step and ASSEMBLES the hop (`PipelineFrontier#hopOf`, the ONE
671
+ * assembly the capsule renders too), so the board's `next:` and the capsule's `next:`
672
+ * render one object by construction. This class fills no cell and makes no judgment:
673
+ * it hands the facts over and returns what the assembly answered. The composition
674
+ * root's board assembly point (`face/cli.ts` `#runBoard`) constructs it.
675
+ */
676
+ // biome-ignore lint/complexity/noStaticOnlyClass: the board's assembly fact surface — the zero-bare-function discipline admits no standalone functions here.
677
+ export class BoardNext {
678
+ /** 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);
683
+ return facts === null ? null : BoardNext.#hopOf(facts, root);
684
+ }
685
+ /** The session plane's ONE assembly, called with the board's facts and the face
686
+ * plane's declaration-reading station port. The board contributes no cell of its
687
+ * own — the hop is whatever the assembly answers. */
688
+ static #hopOf(facts, root) {
689
+ return new PipelineFrontier(facts.ledger).hopOf(facts.input, {
690
+ docClassOf: (candidate) => BoardView.docClassOf(root, candidate),
691
+ });
692
+ }
693
+ }