@oscaner-skills/cdd-engine 2.0.0 → 3.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.
Files changed (84) hide show
  1. package/README.md +2 -2
  2. package/README.zh-CN.md +2 -2
  3. package/package.json +4 -3
  4. package/src-next/__tests__/dead-decl.guard.test.ts +39 -0
  5. package/src-next/__tests__/floor.guard.test.ts +69 -0
  6. package/src-next/__tests__/issue-body.guard.test.ts +66 -0
  7. package/src-next/__tests__/phase-suffix.guard.test.ts +72 -0
  8. package/src-next/__tests__/smoke.integration.test.ts +60 -77
  9. package/src-next/__tests__/support/strip-comments.ts +99 -0
  10. package/src-next/__tests__/zero-dep.test.ts +6 -46
  11. package/src-next/contract/__tests__/__snapshots__/project.schema.overall-spec.snap +39 -21
  12. package/src-next/contract/__tests__/__snapshots__/project.schema.phase-spec.snap +40 -28
  13. package/src-next/contract/__tests__/__snapshots__/project.schema.plan.snap +40 -23
  14. package/src-next/contract/__tests__/__snapshots__/project.schema.single-spec.snap +38 -21
  15. package/src-next/contract/__tests__/__snapshots__/project.shape.overall-spec.snap +21 -6
  16. package/src-next/contract/__tests__/__snapshots__/project.shape.phase-spec.snap +22 -12
  17. package/src-next/contract/__tests__/__snapshots__/project.shape.plan.snap +23 -8
  18. package/src-next/contract/__tests__/__snapshots__/project.shape.single-spec.snap +21 -6
  19. package/src-next/contract/__tests__/declare.test.ts +251 -12
  20. package/src-next/contract/__tests__/doc.test.ts +214 -45
  21. package/src-next/contract/__tests__/dockey.guard.test.ts +58 -0
  22. package/src-next/contract/__tests__/edge-conditions.guard.test.ts +81 -0
  23. package/src-next/contract/__tests__/frontmatter.test.ts +164 -0
  24. package/src-next/contract/__tests__/judge.test.ts +410 -172
  25. package/src-next/contract/__tests__/lint.test.ts +49 -39
  26. package/src-next/contract/__tests__/project.test.ts +60 -19
  27. package/src-next/contract/__tests__/structure-pin.test.ts +186 -0
  28. package/src-next/contract/declare.ts +179 -91
  29. package/src-next/contract/doc.ts +227 -164
  30. package/src-next/contract/frontmatter.ts +233 -0
  31. package/src-next/contract/home-extractors.ts +397 -0
  32. package/src-next/contract/invariants.ts +214 -69
  33. package/src-next/contract/judge.ts +28 -19
  34. package/src-next/contract/lint.ts +5 -41
  35. package/src-next/contract/project.ts +103 -43
  36. package/src-next/contract/skill-anatomy.ts +39 -11
  37. package/src-next/face/__tests__/board-view.test.ts +318 -115
  38. package/src-next/face/__tests__/capsule.test.ts +49 -25
  39. package/src-next/face/__tests__/channel-closure.guard.test.ts +28 -1
  40. package/src-next/face/__tests__/cli.test.ts +1091 -837
  41. package/src-next/face/__tests__/face.test.ts +5 -5
  42. package/src-next/face/__tests__/install-rows.guard.test.ts +58 -0
  43. package/src-next/face/__tests__/preview.test.ts +374 -0
  44. package/src-next/face/__tests__/projection.test.ts +5 -3
  45. package/src-next/face/__tests__/repo-root.guard.test.ts +120 -0
  46. package/src-next/face/__tests__/termination.test.ts +650 -0
  47. package/src-next/face/artifacts.ts +90 -37
  48. package/src-next/face/board-view.ts +128 -138
  49. package/src-next/face/capsule.ts +30 -16
  50. package/src-next/face/cli.ts +306 -97
  51. package/src-next/face/declare.ts +15 -18
  52. package/src-next/face/gate.ts +19 -18
  53. package/src-next/face/host.ts +6 -30
  54. package/src-next/face/lifecycle.ts +213 -188
  55. package/src-next/face/preview.ts +151 -0
  56. package/src-next/face/projection.ts +4 -1
  57. package/src-next/face/route-render.ts +39 -14
  58. package/src-next/face/termination.ts +573 -0
  59. package/src-next/face/words.ts +20 -2
  60. package/src-next/infra/__tests__/infra.test.ts +49 -3
  61. package/src-next/infra/__tests__/root.test.ts +56 -0
  62. package/src-next/infra/doc-roots.ts +29 -0
  63. package/src-next/infra/root.ts +73 -0
  64. package/src-next/infra/runtime.ts +12 -65
  65. package/src-next/infra/workspace.ts +95 -5
  66. package/src-next/render/__tests__/render.test.ts +92 -41
  67. package/src-next/render/__tests__/skeleton.test.ts +282 -64
  68. package/src-next/render/issue-body.ts +5 -2
  69. package/src-next/render/skeleton.ts +155 -90
  70. package/src-next/render/templates.ts +51 -56
  71. package/src-next/session/__tests__/graph.test.ts +11 -4
  72. package/src-next/session/__tests__/ledger.test.ts +3 -2
  73. package/src-next/session/__tests__/next.test.ts +100 -8
  74. package/src-next/session/__tests__/preflight.test.ts +79 -25
  75. package/src-next/session/__tests__/round-naming.test.ts +142 -0
  76. package/src-next/session/__tests__/run.test.ts +140 -128
  77. package/src-next/session/__tests__/wave.test.ts +11 -4
  78. package/src-next/session/ledger.ts +96 -24
  79. package/src-next/session/next.ts +116 -15
  80. package/src-next/session/preflight.ts +41 -10
  81. package/src-next/session/round-naming.ts +84 -0
  82. package/src-next/session/run.ts +24 -20
  83. package/templates/report/issue-body.json +0 -46
  84. package/src-next/face/__tests__/sync-runner.test.ts +0 -70
@@ -1,7 +1,7 @@
1
1
  // packages/cdd-engine/src-next/face/board-view.ts
2
2
  // The board face — the slug → node-tree progress board. The file system is the
3
- // ONLY truth: the node set comes from scanning `docs/kairos/{specs,plans}` (the
4
- // doc roots single-sourced at ENGINE_RUNTIME.docRoots), the artifact existence
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
5
  // from existsSync, the header facts from the doc's header block — the overall's
6
6
  // declared Phase inventory / File paths tables are NEVER parsed (measured stale).
7
7
  // No on-disk-absent parent node is ever synthesized (`-p4.1` present with `-p4`
@@ -11,8 +11,8 @@
11
11
  // derivation read-through, the header `{version, status, docType}` read, the
12
12
  // per-node progress projection, and the render face (the phase/program board
13
13
  // layouts + the `next:` derivation). The doc type is the DECLARED fact — the
14
- // `- **Doc type**:` header declaration line (spec §12 · D34) — never a
15
- // filename-suffix derivation; a missing declaration reads null and the consumer
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
16
  // blocks (zero dual-read fallback).
17
17
  //
18
18
  // D40 — the board's `next:` derivation walks the phase's faces in line order
@@ -29,31 +29,33 @@
29
29
  // Module-level exports are types / constants / the class — zero behavior-carrying
30
30
  // bare functions (the plan's zero-bare-function discipline).
31
31
 
32
- import { existsSync, readdirSync, readFileSync } from "node:fs";
32
+ import { readdirSync, readFileSync } from "node:fs";
33
33
  import path from "node:path";
34
- import { MarkdownPrimitives, PlanDocType } from "../contract/doc.ts";
34
+ import { PlanDocType } from "../contract/doc.ts";
35
+ import { FrontMatterExtractor } from "../contract/frontmatter.ts";
35
36
  import type { DocKey } from "../contract/project.ts";
37
+ import { DOC_KEYS } from "../contract/project.ts";
36
38
  import { ConfigLoader } from "../infra/config.ts";
39
+ import { type RepoPath, RepoRoot } from "../infra/root.ts";
37
40
  import { ENGINE_RUNTIME } from "../infra/runtime.ts";
38
- import { type SlugDocs, Workspace, WorkspaceRoot } from "../infra/workspace.ts";
39
- import type { RouteTarget } from "../session/faces.ts";
41
+ import { PHASE_SUFFIX_BARE, type SlugDocs, Workspace, WorkspaceRoot } from "../infra/workspace.ts";
40
42
  import { TaskGraph } from "../session/graph.ts";
41
43
  import { Ledger, type ProgressData } from "../session/ledger.ts";
42
- import { NextStepRouter, type PipelineKey, type Route } from "../session/next.ts";
44
+ import { NextStepRouter, type PipelineFaceReport } from "../session/next.ts";
43
45
  import { PROGRESS_LEGEND, PROGRESS_MARKERS } from "./graph-view.ts";
44
46
  import { type RouteChannelRow, RouteRenderer } from "./route-render.ts";
45
47
  import type { Words } from "./words.ts";
46
48
 
47
- /** One board node's header facts — the `**Version**` / `**Status**` / `**Doc type**`
48
- * marker values read from the doc's header block (each null when the doc or the
49
- * marker is absent). */
49
+ /** One board node's header facts — the `version:` / `status:` / `doc-type:`
50
+ * front-matter key values read from the doc's head record (each null when the
51
+ * doc or the key is absent). */
50
52
  export interface BoardNodeHeader {
51
- /** The doc's declared version (the `**Version**` header value). */
53
+ /** The doc's declared version (the front-matter `version:` value). */
52
54
  version: string | null;
53
- /** The doc's declared status (the `**Status**` header value). */
55
+ /** The doc's declared status (the front-matter `status:` value). */
54
56
  status: string | null;
55
- /** The doc's declared type (the `**Doc type**` header declaration — spec §12 ·
56
- * D34); null when the declaration is absent or outside the DocKey domain. */
57
+ /** The doc's declared type (the front-matter `doc-type:` key — spec §12 ·
58
+ * D34); null when the key is absent or outside the DocKey domain. */
57
59
  docType: DocKey | null;
58
60
  }
59
61
 
@@ -62,7 +64,7 @@ export interface BoardNodeHeader {
62
64
  const VERB_ORDER: readonly string[] = ["implement", "review", "branch-review", "fix"];
63
65
 
64
66
  /** One rendered board — the stdout lines + the process exit code (0 on a clean
65
- * board, 2 when a present doc line carried no `- **Doc type**:` declaration). */
67
+ * board, 2 when a present doc line carried no `doc-type:` declaration). */
66
68
  export interface BoardRender {
67
69
  /** The board's stdout lines (the header, the body, the legend) — joined with `\n`. */
68
70
  lines: readonly string[];
@@ -112,10 +114,11 @@ export interface BoardProgress {
112
114
  lines: BoardLine[];
113
115
  }
114
116
 
115
- /** The DocKey domain of the `- **Doc type**:` declaration — the declared value must
117
+ /** The DocKey domain of the `doc-type:` declaration — the declared value must
116
118
  * be one of the four keys; anything else reads null (present facts, never a
117
- * fabricated type). */
118
- const DOC_TYPE_DOMAIN: readonly DocKey[] = ["overall-spec", "plan", "phase-spec", "single-spec"];
119
+ * fabricated type). Derived from the ONE DocKey declaration (contract/project.ts
120
+ * re-exports declare.ts's canonical tuple) — never a second copy (spec §3.2 ③). */
121
+ const DOC_TYPE_DOMAIN: readonly DocKey[] = DOC_KEYS;
119
122
 
120
123
  /**
121
124
  * BoardView — the slug → node-tree board face. The static fact readers of this
@@ -145,7 +148,7 @@ export class BoardView {
145
148
  const slug = Workspace.slugFromDoc(entry);
146
149
  if (slug === programSlug || !slug.startsWith(prefix)) continue;
147
150
  const suffix = slug.slice(prefix.length);
148
- if (/^p\d+(?:\.\d+)*$/.test(suffix)) suffixes.add(`-${suffix}`);
151
+ if (PHASE_SUFFIX_BARE.test(suffix)) suffixes.add(`-${suffix}`);
149
152
  }
150
153
  return [...suffixes].sort((a, b) => {
151
154
  const numsOf = (s: string) =>
@@ -162,31 +165,50 @@ export class BoardView {
162
165
  });
163
166
  }
164
167
 
165
- /** readHeader(docPath) — the artifact's header facts: the header block is the
166
- * doc-type-shared marker face, scanned LOCALLY (title line → the first heading)
167
- * with no parser selection (spec §12 · D34 — a marker scan needs no doc-type
168
- * knowledge; the filename→parser derivation is retired). The extraction is LOCAL
169
- * marker slicing — the DocType/MarkdownPrimitives `markerValue`/`markerLine`
170
- * helpers are `protected` members unreachable from this independent class —
171
- * except the version token, which reads the shared grammar's public static
172
- * (`MarkdownPrimitives.versionTokensOf`, one grammar home). An absent file or
173
- * a missing marker yields null — never a fabricated value. */
168
+ /** readHeader(docPath) — the artifact's header facts: the front-matter head
169
+ * record (spec §2.2's structured channel), read RAW through the shared
170
+ * `FrontMatterExtractor` — the version/status/doc-type scalars ride the
171
+ * head keys, never a header-line marker scan (spec §12 · D34 — the doc's
172
+ * declared facts live in the head record, no marker grammar). An absent file
173
+ * yields nulls on every fact — never a fabricated value. */
174
174
  static readHeader(docPath: string): BoardNodeHeader {
175
- const headerLines = BoardView.#headerLinesOf(docPath);
176
- const status = BoardView.#headerValue(headerLines, "**Status**");
177
- const versionLine = BoardView.#headerLine(headerLines, "**Version**");
178
- const version =
179
- versionLine === null ? null : (MarkdownPrimitives.versionTokensOf(versionLine)[0] ?? null);
180
- return { version, status, docType: BoardView.#docTypeOf(headerLines) };
175
+ const { head } = FrontMatterExtractor.split(BoardView.#read(docPath) ?? "");
176
+ return {
177
+ version: head.version,
178
+ status: head.status,
179
+ docType: BoardView.#docTypeOf(head.docType),
180
+ };
181
181
  }
182
182
 
183
- /** readDocType(docPath) — the doc's declared type alone (the `- **Doc type**:`
184
- * header declaration, spec §12 · D34): the ONE declaration reading face shared
183
+ /** readDocType(root, rel) — the doc's declared type alone (the front-matter
184
+ * `doc-type:` key, spec §12 · D34): the ONE declaration reading face shared
185
185
  * by the board and the capsule's doc-class discrimination. An absent file, a
186
- * missing declaration or an out-of-domain value reads null — the consumer
187
- * blocks (zero filename-suffix fallback, zero dual-read layer). */
188
- static readDocType(docPath: string): DocKey | null {
189
- return BoardView.#docTypeOf(BoardView.#headerLinesOf(docPath));
186
+ * missing key or an out-of-domain value reads null — the consumer
187
+ * blocks (zero filename-suffix fallback, zero dual-read layer). The path is the
188
+ * repoRoot-relative branded `RepoPath`, erased to the absolute syscall form
189
+ * through the ONE value object (`root.resolve`) just before the read — the brand
190
+ * is REAL (the absolute state is unrepresentable as a `RepoPath`, T4 §2.2), the
191
+ * same shape as `artifacts.readText(node, root, file)`). */
192
+ static readDocType(root: RepoRoot, rel: RepoPath): DocKey | null {
193
+ return BoardView.#docTypeOf(
194
+ FrontMatterExtractor.split(BoardView.#read(root.resolve(rel)) ?? "").head.docType,
195
+ );
196
+ }
197
+
198
+ /** The doc file's raw text — an absent/unreadable file reads null (the reads
199
+ * above degrade to null facts, never a throw). */
200
+ static #read(docPath: string): string | null {
201
+ try {
202
+ return readFileSync(docPath, "utf8");
203
+ } catch {
204
+ return null;
205
+ }
206
+ }
207
+
208
+ /** The declared doc type constrained to the DocKey domain (null otherwise). */
209
+ static #docTypeOf(declared: string | null): DocKey | null {
210
+ if (declared === null) return null;
211
+ return (DOC_TYPE_DOMAIN as readonly string[]).includes(declared) ? (declared as DocKey) : null;
190
212
  }
191
213
 
192
214
  // -------------------------------------------------------------------------
@@ -291,7 +313,7 @@ export class BoardView {
291
313
  * shared `RouteRenderer` (the SAME channel the capsule's route render reads, so
292
314
  * the board's `next:` and the engine's `next:` literal compose their argv from
293
315
  * ONE flag-spelling source — never a second hard-coded format string). A present
294
- * doc line carrying no `- **Doc type**:` declaration renders its `doc-type:
316
+ * doc line carrying no `doc-type:` key renders its `doc-type:
295
317
  * missing (BLOCKED)` marker and the board exits 2 (spec §12 · D34 — the consumer
296
318
  * blocks, zero filename fallback). Pure reads — zero tree writes, zero ledger
297
319
  * writes, zero child dispatch. */
@@ -303,25 +325,33 @@ export class BoardView {
303
325
  channels: Readonly<Record<string, RouteChannelRow>> = {},
304
326
  ): BoardRender {
305
327
  const lines: string[] = [`cdd board: ${slug}`, ""];
328
+ // The repo-basis value object — constructed ONCE at this boundary, the ONE
329
+ // conversion exit the doc cells and the `next:` render normalize their embedded
330
+ // paths through (T1 `RepoRoot` · D47). The raw string is threaded no further:
331
+ // the board renders read the basis through `root.absolute` (F2 — one basis,
332
+ // one form).
333
+ const root = new RepoRoot(repoRoot);
306
334
  const exitCode =
307
335
  Workspace.phaseSuffixOf(slug) !== null
308
- ? BoardView.#phaseBoard(lines, slug, repoRoot, words, host, channels)
309
- : BoardView.#programBoard(lines, slug, repoRoot);
336
+ ? BoardView.#phaseBoard(lines, slug, root, words, host, channels)
337
+ : BoardView.#programBoard(lines, slug, root);
310
338
  lines.push("", PROGRESS_LEGEND.board);
311
339
  return { lines, exitCode };
312
340
  }
313
341
 
314
342
  /** The phase board render — the overall/spec/plan/wave/branch rows + the next
315
343
  * derivation. Returns the exit code (2 when a present doc line carries no type
316
- * declaration). */
344
+ * declaration). The repo-basis `root` is threaded alone (F2) — its `absolute`
345
+ * feeds the fs-facing helpers, its value object the path renders. */
317
346
  static #phaseBoard(
318
347
  lines: string[],
319
348
  slug: string,
320
- repoRoot: string,
349
+ root: RepoRoot,
321
350
  words: Words,
322
351
  host: string,
323
352
  channels: Readonly<Record<string, RouteChannelRow>>,
324
353
  ): number {
354
+ const repoRoot = root.absolute;
325
355
  const suffix = Workspace.phaseSuffixOf(slug)!;
326
356
  const program = slug.slice(0, slug.length - suffix.length);
327
357
  const docs = Workspace.docsOfSlug(slug, repoRoot);
@@ -334,15 +364,15 @@ export class BoardView {
334
364
  const branchLine = node.lines.find((line) => line.label === "branch");
335
365
  let blocked = false;
336
366
 
337
- const overallDoc = BoardView.#docCell(docs.overall, overall.lines[0]!);
367
+ const overallDoc = BoardView.#docCell(docs.overall, overall.lines[0]!, root);
338
368
  lines.push(` overall ${overallDoc.text}`);
339
369
  blocked ||= overallDoc.blocked;
340
370
 
341
- const specDoc = BoardView.#docCell(docs.spec, specLine!);
371
+ const specDoc = BoardView.#docCell(docs.spec, specLine!, root);
342
372
  lines.push(` spec ${specDoc.text}`);
343
373
  blocked ||= specDoc.blocked;
344
374
 
345
- const planDoc = BoardView.#docCell(docs.plan, planLine!);
375
+ const planDoc = BoardView.#docCell(docs.plan, planLine!, root);
346
376
  lines.push(` plan ${planDoc.text}`);
347
377
  blocked ||= planDoc.blocked;
348
378
 
@@ -371,7 +401,7 @@ export class BoardView {
371
401
  );
372
402
 
373
403
  lines.push("");
374
- lines.push(` next: ${BoardView.#nextOf(ledger, node, docs, words, host, channels)}`);
404
+ lines.push(` next: ${BoardView.#nextOf(ledger, node, docs, words, host, channels, root)}`);
375
405
  return blocked ? 2 : 0;
376
406
  }
377
407
 
@@ -380,12 +410,14 @@ export class BoardView {
380
410
  * §6.5). Returns the exit code (2 when the overall doc OR any present phase doc
381
411
  * carries no type declaration — the phase board's BLOCK propagates here, spec §12 ·
382
412
  * D34: zero silent fallback). */
383
- static #programBoard(lines: string[], slug: string, repoRoot: string): number {
413
+ static #programBoard(lines: string[], slug: string, root: RepoRoot): number {
414
+ const repoRoot = root.absolute;
384
415
  const nodes = BoardView.projectNodes(slug, repoRoot);
385
416
  const overall = nodes[0]!;
386
417
  const overallDoc = BoardView.#docCell(
387
418
  Workspace.docsOfSlug(slug, repoRoot).overall,
388
419
  overall.lines[0]!,
420
+ root,
389
421
  );
390
422
  lines.push(` overall ${overallDoc.text}`);
391
423
  lines.push("");
@@ -396,12 +428,13 @@ export class BoardView {
396
428
  const plan = node.lines.find((line) => line.label === "plan");
397
429
  const branch = node.lines.find((line) => line.label === "branch");
398
430
  // The phase line's doc-cell read: a present phase spec/plan without its
399
- // `- **Doc type**:` declaration blocks the SAME way the phase board does —
400
- // the marker renders on the phase line and the program board exits 2.
431
+ // A present spec/plan without its `doc-type:` key blocks the SAME way the
432
+ // phase board does — the marker renders on the phase line and the program
433
+ // board exits 2.
401
434
  const docs = Workspace.docsOfSlug(node.label, repoRoot);
402
435
  const phaseBlocked =
403
- BoardView.#docCell(docs.spec, spec!).blocked ||
404
- BoardView.#docCell(docs.plan, plan!).blocked;
436
+ BoardView.#docCell(docs.spec, spec!, root).blocked ||
437
+ BoardView.#docCell(docs.plan, plan!, root).blocked;
405
438
  blocked ||= phaseBlocked;
406
439
  const status = phaseBlocked ? "doc-type: missing (BLOCKED)" : (spec?.status ?? "Pending");
407
440
  // The phase's wave summary token (spec §5.3): the wave segment's first wave
@@ -427,19 +460,26 @@ export class BoardView {
427
460
 
428
461
  /** One doc line's cell text — the doc path, the header facts and the line's
429
462
  * rounds (spec §5.3: `overall <path> v2.33 · Draft review×4`); a present doc
430
- * carrying no `- **Doc type**:` declaration renders its `doc-type: missing
463
+ * carrying no `doc-type:` key renders its `doc-type: missing
431
464
  * (BLOCKED)` marker in place of the facts (blocked = true). An absent doc renders
432
- * `(none)` (degradation, never a throw). */
433
- static #docCell(docPath: string | null, line: BoardLine): { text: string; blocked: boolean } {
465
+ * `(none)` (degradation, never a throw). The doc path renders repoRoot-relative
466
+ * through the ONE value object (D47 — `docsOfSlug` derives it absolute; the board
467
+ * emits the ONE shape). */
468
+ static #docCell(
469
+ docPath: string | null,
470
+ line: BoardLine,
471
+ root: RepoRoot,
472
+ ): { text: string; blocked: boolean } {
434
473
  if (docPath === null) return { text: "(none)", blocked: false };
474
+ const rel = root.relativize(docPath);
435
475
  if (line.docType === null) {
436
476
  const facts: string[] = [];
437
477
  if (line.version !== null) facts.push(line.version);
438
478
  if (line.status !== null) facts.push(line.status);
439
479
  const head = facts.length === 0 ? "" : `${facts.join(" · ")} `;
440
- return { text: `${docPath} ${head}doc-type: missing (BLOCKED)`, blocked: true };
480
+ return { text: `${rel} ${head}doc-type: missing (BLOCKED)`, blocked: true };
441
481
  }
442
- const facts: string[] = [docPath];
482
+ const facts: string[] = [rel];
443
483
  const meta = [line.version, line.status].filter((part) => part !== null).join(" · ");
444
484
  if (meta !== "") facts.push(meta);
445
485
  const rounds = BoardView.roundsCell(line.rounds);
@@ -454,19 +494,20 @@ export class BoardView {
454
494
  return new Ledger(new Workspace(root, nodeSlug), new ConfigLoader());
455
495
  }
456
496
 
457
- /** The board's `next:` derivation (spec §6.5 · §18.2 · D40 deep-solve) — walk the
458
- * phase's lines in order (spec → plan → wave → branch) and, for the FIRST line not
459
- * yet closed, derive that line's ACTIVE C5 hop from the SAME state→next chain the
460
- * dispatch engine walks (`Ledger#lineRoute` for the doc/branch lines; the plan
461
- * frontier + `Ledger#waveLineRoute` for the wave line) before feeding it to the ONE
462
- * resolver (`NextStepRouter.resolve`) and the ONE renderer (`RouteRenderer`). A line
463
- * still in flight therefore renders its next C5 hop — a fresh wave's
464
- * `implement --plan <plan> --tasks <ids>`, an in-flight wave's `review`/`fix`, a
465
- * fresh doc line's `review --type <type> …` — never the face-to-face handoff of an
466
- * exhausted line (`resolve(null, …)` is the retired shallow form: it dropped the
467
- * line's C5 frontier and rendered the next face's entry for an open line). A line
468
- * with no active hop (a not-yet-started doc line, a plan-less wave face) hands off
469
- * to the next pipeline entry; every line closed → the bare terminal `done`. */
497
+ /** The board's `next:` derivation (spec §6.5 · §18.2 · D40 deep-solve) — the board
498
+ * OBSERVES each phase face's state (closed · its ACTIVE C5 hop from the SAME
499
+ * state→next chain the dispatch engine walks — `Ledger#lineRoute` for the doc/branch
500
+ * lines, the plan frontier + `Ledger#waveLineRoute` for the wave line — and the
501
+ * render target) as a keyed report and hands it to the ONE router
502
+ * (`NextStepRouter.walk`) + the ONE renderer (`RouteRenderer`). The board forks
503
+ * ZERO transition rule: the face order and the frontier/entrance/anchor decision are
504
+ * the router's (D26 — one fact, one place). A line still in flight renders its next
505
+ * C5 hop (a fresh wave's `implement --plan <plan> --tasks <ids>`, an in-flight
506
+ * wave's `review`/`fix`, a fresh doc line's `review --type <type> …`); a face
507
+ * ENTERED but with no active hop renders its own pipeline exit; a face NOT yet
508
+ * entered (an absent doc) renders the PRECEDING entered face's exit (so a
509
+ * just-closed spec hands off to `cdd-plan`, never the absent plan's `cdd-dev`); all
510
+ * faces closed renders the last face's exit (the pipeline terminus). */
470
511
  static #nextOf(
471
512
  ledger: Ledger,
472
513
  node: BoardProgress,
@@ -474,51 +515,42 @@ export class BoardView {
474
515
  words: Words,
475
516
  host: string,
476
517
  channels: Readonly<Record<string, RouteChannelRow>>,
518
+ root: RepoRoot,
477
519
  ): string {
478
- const renderer = new RouteRenderer(words, channels, host);
520
+ const renderer = new RouteRenderer(words, channels, host, root);
479
521
  const waves = node.waveLines ?? [];
480
- const planTarget: RouteTarget | null =
481
- docs.plan === null ? null : { type: "plan", id: docs.plan, plan: docs.plan };
482
522
  // The plan's open frontier wave — the SAME ready batch the dispatch engine's
483
523
  // task-graph frontier yields (frontier over closedWaves()).
484
524
  const waveKey = BoardView.#waveFrontierKey(ledger, docs.plan);
485
- const lines: Array<{
486
- key: PipelineKey;
487
- closed: boolean;
488
- active: Route | null;
489
- target: RouteTarget | null;
490
- }> = [
491
- {
492
- key: "phase-spec",
525
+ // The observed faces keyed by their `PIPELINE_FACES` key — the router owns the
526
+ // order, so the board re-declares none (it only reports facts).
527
+ const report: PipelineFaceReport = {
528
+ "phase-spec": {
493
529
  closed: ledger.lineClosed("spec", "spec"),
494
530
  active: docs.spec === null ? null : ledger.lineRoute("spec", "spec"),
495
531
  target: docs.spec === null ? null : { type: "spec", id: docs.spec },
496
532
  },
497
- {
498
- key: "plan",
533
+ plan: {
499
534
  closed: ledger.lineClosed("plan", "plan"),
500
535
  active: docs.plan === null ? null : ledger.lineRoute("plan", "plan"),
501
- target: planTarget,
536
+ target: docs.plan === null ? null : { type: "plan", id: docs.plan, plan: docs.plan },
502
537
  },
503
- {
538
+ wave: {
504
539
  // The wave face is exhausted (skipped) only when the plan yields a wave set
505
540
  // and every wave is done — an empty wave segment (no plan) is not an exhausted
506
541
  // face (nothing was closed), so it stays the frontier and hands off.
507
- key: "wave",
508
542
  closed: waves.length > 0 && waves.every((wave) => wave.marker === PROGRESS_MARKERS.done),
509
543
  active: waveKey === null ? null : ledger.waveLineRoute(waveKey),
510
544
  target: docs.plan === null ? null : { type: "wave", id: waveKey ?? "", plan: docs.plan },
511
545
  },
512
- {
513
- key: "branch",
546
+ branch: {
514
547
  closed: ledger.lineClosed("branch", "branch"),
515
548
  active: ledger.lineRoute("branch", "branch"),
516
549
  target: { type: "branch", id: "branch", plan: docs.plan ?? undefined },
517
550
  },
518
- ];
519
- const frontier = lines.find((line) => !line.closed);
520
- if (frontier === undefined) return renderer.render({ kind: "done" }, planTarget);
521
- return renderer.render(NextStepRouter.resolve(frontier.active, frontier.key), frontier.target);
551
+ };
552
+ const next = NextStepRouter.walk(report);
553
+ return renderer.render(next.route, next.target);
522
554
  }
523
555
 
524
556
  /** The plan's open frontier wave key — the ready batch over the node's `closedWaves()`
@@ -617,46 +649,4 @@ export class BoardView {
617
649
  };
618
650
  });
619
651
  }
620
-
621
- /** The doc's header-block lines — an absent file scans empty; a present one
622
- * yields the lines between the `# Title` and the first heading (the same block
623
- * the doc-type parsers expose as `headerLines`, read without one). The leading
624
- * line is dropped only when it IS the document title (a rank-1 heading) — a doc
625
- * whose first line is already metadata keeps it (the marker scan needs no title). */
626
- static #headerLinesOf(docPath: string): readonly string[] {
627
- if (!existsSync(docPath)) return [];
628
- const lines = readFileSync(docPath, "utf8").split("\n");
629
- const body = /^#\s/.test(lines[0] ?? "") ? lines.slice(1) : lines;
630
- const header: string[] = [];
631
- for (const line of body) {
632
- if (/^#+\s/.test(line)) break;
633
- header.push(line);
634
- }
635
- return header;
636
- }
637
-
638
- /** The declared doc type of the header block — the `**Doc type**` marker value
639
- * constrained to the DocKey domain (null otherwise). */
640
- static #docTypeOf(headerLines: readonly string[]): DocKey | null {
641
- const declared = BoardView.#headerValue(headerLines, "**Doc type**");
642
- if (declared === null) return null;
643
- return (DOC_TYPE_DOMAIN as readonly string[]).includes(declared) ? (declared as DocKey) : null;
644
- }
645
-
646
- /** The first header line carrying the marker — the local line-level extraction
647
- * (null when no header line carries the marker). */
648
- static #headerLine(headerLines: readonly string[], marker: string): string | null {
649
- for (const line of headerLines) if (line.includes(marker)) return line;
650
- return null;
651
- }
652
-
653
- /** The one-marker value slice — the local header extraction (the `- **Key**:
654
- * value` prefix form; null when no header line carries the marker). */
655
- static #headerValue(headerLines: readonly string[], marker: string): string | null {
656
- const line = BoardView.#headerLine(headerLines, marker);
657
- if (line === null) return null;
658
- const index = line.indexOf(marker);
659
- const payload = line.slice(index + marker.length).trim();
660
- return payload.replace(/^:\s*/, "").trim();
661
- }
662
652
  }
@@ -14,7 +14,7 @@
14
14
  // either a caller-rendered string or the C5 Route rendered through the route-word
15
15
  // table as a COMPLETE EXECUTABLE command (P4.1 T4 — the v1.39 semantic-literal
16
16
  // reversal): `implement --plan <path> --tasks 17` · `review --type spec --spec
17
- // <path>` · `fix --type spec --spec <path> --findings <handoff> (read file back to
17
+ // <path>` · `fix --type spec --spec <path> --reviews <handoff> (read file back to
18
18
  // confirm)` · `done` (the bare terminal word) · the soft-cap message verbatim.
19
19
  // The argv is composed from the frame facts (the RouteTarget's type + id + plan)
20
20
  // through the argv-channel flag spellings (the same channel the CLI parse reads —
@@ -35,7 +35,7 @@
35
35
  // the capsule plugs into the lifecycle's attachCapsule contact, byte-identically.
36
36
  // Module-level exports are the class — zero behavior-carrying bare functions.
37
37
 
38
- import path from "node:path";
38
+ import { type RepoPath, RepoRoot } from "../infra/root.ts";
39
39
  import type { RouteTarget } from "../session/faces.ts";
40
40
  import { NextStepRouter, type PipelineKey, type Route } from "../session/next.ts";
41
41
  import { BoardView } from "./board-view.ts";
@@ -62,19 +62,20 @@ export class Capsule {
62
62
  readonly #words: Words;
63
63
  /** The ONE route → `next:` literal renderer (D40 — shared with the board). */
64
64
  readonly #route: RouteRenderer;
65
- /** The repo root the doc-target ids resolve against (the declaration read's
66
- * path base; `""` keeps a relative id relative — the hermetic-test default). */
67
- readonly #repoRoot: string;
65
+ /** The repo-basis value object the doc-target ids + the `handoff:` cell resolve
66
+ * through (T1 `RepoRoot` · D47 — the ONE conversion exit; `null` keeps a relative
67
+ * id relative · the hermetic-test default). */
68
+ readonly #root: RepoRoot | null;
68
69
 
69
70
  constructor(
70
71
  words: Words,
71
72
  channels: Readonly<Record<string, CapsuleChannelRow>> = {},
72
73
  host = "",
73
- repoRoot = "",
74
+ root: RepoRoot | null = null,
74
75
  ) {
75
76
  this.#words = words;
76
- this.#repoRoot = repoRoot;
77
- this.#route = new RouteRenderer(words, channels, host);
77
+ this.#root = root;
78
+ this.#route = new RouteRenderer(words, channels, host, root);
78
79
  }
79
80
 
80
81
  /** emit(status, blocker, handoff, next, target) → the capsule stdout lines: the
@@ -92,7 +93,14 @@ export class Capsule {
92
93
  target?: RouteTarget | null,
93
94
  ): string[] {
94
95
  const words = this.#words;
95
- const cells: Record<CapsuleKey, string> = { status, blocker, handoff };
96
+ // The `handoff:` cell is a path value — normalized to the repoRoot-relative
97
+ // shape through the ONE value object (D47 · the ONE basis; `handoffPath` sources
98
+ // it absolute).
99
+ const cells: Record<CapsuleKey, string> = {
100
+ status,
101
+ blocker,
102
+ handoff: this.#rel(handoff),
103
+ };
96
104
  const capsuleLine = words
97
105
  .capsuleKeys()
98
106
  .map((kind) => `${kind}: ${cells[kind]}`)
@@ -126,14 +134,17 @@ export class Capsule {
126
134
 
127
135
  /** The target → doc-class verdict of the unified next face — the doc-class
128
136
  * discrimination face (D33): the spec doc's class reads its DECLARED type (the
129
- * `- **Doc type**:` header declaration, spec §12 · D34 — BoardView.readDocType,
137
+ * front-matter `doc-type:` key, spec §12 · D34 — BoardView.readDocType,
130
138
  * the one declaration reading face), never the filename suffix; the task-face
131
- * targets key by type. `blocked` — the declaration is missing (the caller
139
+ * targets key by type. `blocked` — the key is missing (the caller
132
140
  * renders the BLOCKED face); `terminal` — no pipeline seam carries the declared
133
141
  * class (`single-spec`, the table's five keys exclude it — the bare word). */
134
142
  #docClassOf(target: RouteTarget): "blocked" | "terminal" | PipelineKey {
135
143
  if (target.type === "spec") {
136
- const declared = BoardView.readDocType(this.#docPathOf(target.id));
144
+ // The read face takes the value object + the repoRoot-relative id (T4 §2.2);
145
+ // a `null` root (the hermetic default) keeps the value as its own basis. The
146
+ // `#rel` branded return needs no cast here (F3).
147
+ const declared = BoardView.readDocType(this.#root ?? new RepoRoot(""), this.#rel(target.id));
137
148
  return declared === null ? "blocked" : declared === "single-spec" ? "terminal" : declared;
138
149
  }
139
150
  if (target.type === "plan") return "plan";
@@ -141,9 +152,12 @@ export class Capsule {
141
152
  return "branch";
142
153
  }
143
154
 
144
- /** The doc-target id's file path — the id resolved against the capsule's repo
145
- * root (an absolute id passes through; a relative one joins the root). */
146
- #docPathOf(id: string): string {
147
- return path.isAbsolute(id) ? id : this.#repoRoot === "" ? id : path.join(this.#repoRoot, id);
155
+ /** One path value normalized to the branded repoRoot-relative `RepoPath` through
156
+ * the ONE value object (D47); a `null` root (the hermetic default) passes the
157
+ * value through as its own basis. The branded return type carries the §2.2 brand
158
+ * to the read face (`BoardView.readDocType`) with NO call-site cast (branch-
159
+ * review-1 F3). */
160
+ #rel(value: string): RepoPath {
161
+ return this.#root === null ? (value as RepoPath) : this.#root.relativize(value);
148
162
  }
149
163
  }