@oscaner-skills/cdd-engine 3.0.0 → 3.0.1

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 (143) hide show
  1. package/{src-next/bin.ts → dist/bin.js} +18 -21
  2. package/dist/contract/declare.js +998 -0
  3. package/dist/contract/doc.js +565 -0
  4. package/dist/contract/frontmatter.js +209 -0
  5. package/dist/contract/home-extractors.js +379 -0
  6. package/dist/contract/invariants.js +1030 -0
  7. package/dist/contract/judge.js +109 -0
  8. package/dist/contract/lint.js +206 -0
  9. package/dist/contract/project.js +371 -0
  10. package/dist/contract/skill-anatomy.js +156 -0
  11. package/dist/contract/translate.js +85 -0
  12. package/dist/face/artifacts.js +189 -0
  13. package/dist/face/board-view.js +522 -0
  14. package/dist/face/capsule.js +141 -0
  15. package/dist/face/cli.js +891 -0
  16. package/dist/face/declare.js +241 -0
  17. package/dist/face/gate.js +158 -0
  18. package/dist/face/graph-view.js +66 -0
  19. package/dist/face/host.js +211 -0
  20. package/dist/face/lifecycle.js +603 -0
  21. package/dist/face/preview.js +136 -0
  22. package/dist/face/projection.js +259 -0
  23. package/dist/face/route-render.js +162 -0
  24. package/dist/face/termination.js +482 -0
  25. package/dist/face/words.js +220 -0
  26. package/{src-next/infra/config.ts → dist/infra/config.js} +19 -24
  27. package/{src-next/infra/doc-roots.ts → dist/infra/doc-roots.js} +3 -13
  28. package/dist/infra/git.js +37 -0
  29. package/dist/infra/process.js +22 -0
  30. package/{src-next/infra/root.ts → dist/infra/root.js} +25 -36
  31. package/dist/infra/runtime.js +85 -0
  32. package/dist/infra/workspace.js +276 -0
  33. package/dist/render/brief.js +82 -0
  34. package/dist/render/issue-body.js +129 -0
  35. package/dist/render/skeleton.js +434 -0
  36. package/dist/render/templates.js +520 -0
  37. package/dist/session/faces.js +38 -0
  38. package/dist/session/graph.js +309 -0
  39. package/dist/session/handoff-schema.js +295 -0
  40. package/dist/session/ledger.js +762 -0
  41. package/dist/session/next.js +211 -0
  42. package/dist/session/preflight.js +194 -0
  43. package/dist/session/round-naming.js +73 -0
  44. package/dist/session/run.js +441 -0
  45. package/dist/session/state.js +8 -0
  46. package/dist/session/wave.js +92 -0
  47. package/package.json +5 -5
  48. package/src-next/__tests__/bin.test.ts +0 -128
  49. package/src-next/__tests__/dead-decl.guard.test.ts +0 -39
  50. package/src-next/__tests__/floor.guard.test.ts +0 -69
  51. package/src-next/__tests__/issue-body.guard.test.ts +0 -66
  52. package/src-next/__tests__/phase-suffix.guard.test.ts +0 -72
  53. package/src-next/__tests__/smoke.integration.test.ts +0 -185
  54. package/src-next/__tests__/support/strip-comments.ts +0 -99
  55. package/src-next/__tests__/zero-dep.test.ts +0 -94
  56. package/src-next/contract/__tests__/__snapshots__/project.schema.overall-spec.snap +0 -256
  57. package/src-next/contract/__tests__/__snapshots__/project.schema.phase-spec.snap +0 -165
  58. package/src-next/contract/__tests__/__snapshots__/project.schema.plan.snap +0 -190
  59. package/src-next/contract/__tests__/__snapshots__/project.schema.single-spec.snap +0 -106
  60. package/src-next/contract/__tests__/__snapshots__/project.shape.overall-spec.snap +0 -240
  61. package/src-next/contract/__tests__/__snapshots__/project.shape.phase-spec.snap +0 -165
  62. package/src-next/contract/__tests__/__snapshots__/project.shape.plan.snap +0 -190
  63. package/src-next/contract/__tests__/__snapshots__/project.shape.single-spec.snap +0 -100
  64. package/src-next/contract/__tests__/declare.test.ts +0 -481
  65. package/src-next/contract/__tests__/doc.test.ts +0 -527
  66. package/src-next/contract/__tests__/dockey.guard.test.ts +0 -58
  67. package/src-next/contract/__tests__/edge-conditions.guard.test.ts +0 -81
  68. package/src-next/contract/__tests__/frontmatter.test.ts +0 -164
  69. package/src-next/contract/__tests__/judge.test.ts +0 -1111
  70. package/src-next/contract/__tests__/lint.test.ts +0 -324
  71. package/src-next/contract/__tests__/project.test.ts +0 -460
  72. package/src-next/contract/__tests__/structure-pin.test.ts +0 -186
  73. package/src-next/contract/__tests__/translate.test.ts +0 -96
  74. package/src-next/contract/declare.ts +0 -1071
  75. package/src-next/contract/doc.ts +0 -816
  76. package/src-next/contract/frontmatter.ts +0 -233
  77. package/src-next/contract/home-extractors.ts +0 -397
  78. package/src-next/contract/invariants.ts +0 -1413
  79. package/src-next/contract/judge.ts +0 -151
  80. package/src-next/contract/lint.ts +0 -239
  81. package/src-next/contract/project.ts +0 -656
  82. package/src-next/contract/skill-anatomy.ts +0 -301
  83. package/src-next/contract/translate.ts +0 -113
  84. package/src-next/face/__tests__/board-view.test.ts +0 -1151
  85. package/src-next/face/__tests__/capsule.test.ts +0 -300
  86. package/src-next/face/__tests__/channel-closure.guard.test.ts +0 -129
  87. package/src-next/face/__tests__/cli.test.ts +0 -4897
  88. package/src-next/face/__tests__/face.test.ts +0 -289
  89. package/src-next/face/__tests__/graph-view.test.ts +0 -61
  90. package/src-next/face/__tests__/host.test.ts +0 -24
  91. package/src-next/face/__tests__/install-rows.guard.test.ts +0 -58
  92. package/src-next/face/__tests__/negation.ts +0 -6
  93. package/src-next/face/__tests__/preview.test.ts +0 -374
  94. package/src-next/face/__tests__/projection.test.ts +0 -303
  95. package/src-next/face/__tests__/repo-root.guard.test.ts +0 -120
  96. package/src-next/face/__tests__/termination.test.ts +0 -650
  97. package/src-next/face/__tests__/words.guard.test.ts +0 -93
  98. package/src-next/face/artifacts.ts +0 -248
  99. package/src-next/face/board-view.ts +0 -652
  100. package/src-next/face/capsule.ts +0 -163
  101. package/src-next/face/cli.ts +0 -1028
  102. package/src-next/face/declare.ts +0 -323
  103. package/src-next/face/gate.ts +0 -171
  104. package/src-next/face/graph-view.ts +0 -74
  105. package/src-next/face/host.ts +0 -302
  106. package/src-next/face/lifecycle.ts +0 -725
  107. package/src-next/face/preview.ts +0 -151
  108. package/src-next/face/projection.ts +0 -285
  109. package/src-next/face/route-render.ts +0 -185
  110. package/src-next/face/termination.ts +0 -573
  111. package/src-next/face/words.ts +0 -314
  112. package/src-next/infra/__tests__/infra.test.ts +0 -333
  113. package/src-next/infra/__tests__/root.test.ts +0 -56
  114. package/src-next/infra/git.ts +0 -39
  115. package/src-next/infra/process.ts +0 -34
  116. package/src-next/infra/runtime.ts +0 -132
  117. package/src-next/infra/workspace.ts +0 -322
  118. package/src-next/render/__tests__/render.test.ts +0 -550
  119. package/src-next/render/__tests__/skeleton.test.ts +0 -684
  120. package/src-next/render/brief.ts +0 -121
  121. package/src-next/render/issue-body.ts +0 -162
  122. package/src-next/render/skeleton.ts +0 -502
  123. package/src-next/render/templates.ts +0 -645
  124. package/src-next/session/__tests__/graph.test.ts +0 -277
  125. package/src-next/session/__tests__/handoff-plane.guard.test.ts +0 -48
  126. package/src-next/session/__tests__/handoff-schema.test.ts +0 -310
  127. package/src-next/session/__tests__/ledger.test.ts +0 -745
  128. package/src-next/session/__tests__/next.test.ts +0 -460
  129. package/src-next/session/__tests__/preflight.test.ts +0 -545
  130. package/src-next/session/__tests__/round-naming.test.ts +0 -142
  131. package/src-next/session/__tests__/run.test.ts +0 -1026
  132. package/src-next/session/__tests__/wave-line-phase.guard.test.ts +0 -49
  133. package/src-next/session/__tests__/wave.test.ts +0 -476
  134. package/src-next/session/faces.ts +0 -110
  135. package/src-next/session/graph.ts +0 -411
  136. package/src-next/session/handoff-schema.ts +0 -373
  137. package/src-next/session/ledger.ts +0 -1076
  138. package/src-next/session/next.ts +0 -293
  139. package/src-next/session/preflight.ts +0 -271
  140. package/src-next/session/round-naming.ts +0 -84
  141. package/src-next/session/run.ts +0 -610
  142. package/src-next/session/state.ts +0 -30
  143. package/src-next/session/wave.ts +0 -139
@@ -1,652 +0,0 @@
1
- // packages/cdd-engine/src-next/face/board-view.ts
2
- // The board face — the slug → node-tree progress board. The file system is the
3
- // ONLY truth: the node set comes from scanning the declared spec/plan doc roots
4
- // (single-sourced at ENGINE_RUNTIME.docRoots), the artifact existence
5
- // from existsSync, the header facts from the doc's header block — the overall's
6
- // declared Phase inventory / File paths tables are NEVER parsed (measured stale).
7
- // No on-disk-absent parent node is ever synthesized (`-p4.1` present with `-p4`
8
- // missing mounts `p4.1` directly at the program root).
9
- //
10
- // This module carries the slug facts: the phase scan, the doc-tree reverse
11
- // derivation read-through, the header `{version, status, docType}` read, the
12
- // per-node progress projection, and the render face (the phase/program board
13
- // layouts + the `next:` derivation). The doc type is the DECLARED fact — the
14
- // front-matter `doc-type:` head key (spec §12 · D34) — never a
15
- // filename-suffix derivation; an absent key reads null and the consumer
16
- // blocks (zero dual-read fallback).
17
- //
18
- // D40 — the board's `next:` derivation walks the phase's faces in line order
19
- // (spec → plan → wave → branch) and, for the FIRST non-closed face, derives that
20
- // line's ACTIVE C5 hop from the SAME state→next chain the dispatch engine walks
21
- // (the wave face's frontier → `Ledger#waveLinePhase`; the doc/branch faces'
22
- // `Ledger#linePhase`) before feeding it to the ONE resolver (`NextStepRouter.resolve`)
23
- // and the ONE renderer (`RouteRenderer`, shared with the capsule). A line still in
24
- // flight therefore renders its next C5 hop (`implement --tasks 12,13,14`), never the
25
- // face-to-face handoff of an exhausted line; a fully drained line hands off to the
26
- // next pipeline entry. Each wave line's label carries the wave's task scope in braces
27
- // (`W1 {5,11}`) with the ✔/▶/○ marker column fixed-width aligned.
28
- //
29
- // Module-level exports are types / constants / the class — zero behavior-carrying
30
- // bare functions (the plan's zero-bare-function discipline).
31
-
32
- import { readdirSync, readFileSync } from "node:fs";
33
- import path from "node:path";
34
- import { PlanDocType } from "../contract/doc.ts";
35
- import { FrontMatterExtractor } from "../contract/frontmatter.ts";
36
- import type { DocKey } from "../contract/project.ts";
37
- import { DOC_KEYS } from "../contract/project.ts";
38
- import { ConfigLoader } from "../infra/config.ts";
39
- import { type RepoPath, RepoRoot } from "../infra/root.ts";
40
- import { ENGINE_RUNTIME } from "../infra/runtime.ts";
41
- import { PHASE_SUFFIX_BARE, type SlugDocs, Workspace, WorkspaceRoot } from "../infra/workspace.ts";
42
- import { TaskGraph } from "../session/graph.ts";
43
- import { Ledger, type ProgressData } from "../session/ledger.ts";
44
- import { NextStepRouter, type PipelineFaceReport } from "../session/next.ts";
45
- import { PROGRESS_LEGEND, PROGRESS_MARKERS } from "./graph-view.ts";
46
- import { type RouteChannelRow, RouteRenderer } from "./route-render.ts";
47
- import type { Words } from "./words.ts";
48
-
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). */
52
- export interface BoardNodeHeader {
53
- /** The doc's declared version (the front-matter `version:` value). */
54
- version: string | null;
55
- /** The doc's declared status (the front-matter `status:` value). */
56
- status: string | null;
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. */
59
- docType: DocKey | null;
60
- }
61
-
62
- /** The verb render order of a line's `×N` cell — the stable display order the board's
63
- * round cells follow (an unexpected verb appends after these, never dropped). */
64
- const VERB_ORDER: readonly string[] = ["implement", "review", "branch-review", "fix"];
65
-
66
- /** One rendered board — the stdout lines + the process exit code (0 on a clean
67
- * board, 2 when a present doc line carried no `doc-type:` declaration). */
68
- export interface BoardRender {
69
- /** The board's stdout lines (the header, the body, the legend) — joined with `\n`. */
70
- lines: readonly string[];
71
- /** The board's process exit code: 0 (clean) or 2 (a missing doc-type declaration). */
72
- exitCode: number;
73
- }
74
-
75
- /** One board line's projected data — a doc line (`overall` / `spec` / `plan`), the
76
- * `branch` line, or one derived wave line. Each line carries its own rounds (the
77
- * `progress.json` row of its key) and, for wave lines, the derived ✔/▶/○ marker. */
78
- export interface BoardLine {
79
- /** The line's label — `overall` / `spec` / `plan` / `branch`, or the wave label (`W1`). */
80
- label: string;
81
- /** The line's doc version (null for the branch/wave lines — no doc). */
82
- version: string | null;
83
- /** The line's doc status (null for the branch/wave lines). */
84
- status: string | null;
85
- /** The line's declared doc type (spec §12 · D34; null for the branch/wave lines). */
86
- docType: DocKey | null;
87
- /** The line's completed rounds per verb, each as its cycle-NUMBER array (D28
88
- * identity — `[1,3]` = the 1st and 3rd rounds; never a count). */
89
- rounds: Record<string, number[]>;
90
- /** The derived ✔/▶/○ marker — wave lines only; null otherwise. */
91
- marker: string | null;
92
- }
93
-
94
- /** One node's progress projection (`cdd board` data plane · spec §5) — the node's
95
- * own lines (each a `progress.json` row) plus the derived wave segment. The
96
- * projection is a pure read of the node's OWN workspace `progress.json` (the wave
97
- * markers ride the SAME `closedWaves()` read the pre-flight gate consumes — one
98
- * live fact, zero new judgment). */
99
- export interface BoardProgress {
100
- /** The node label — the node slug (its workspace unit `.kairos/cdd/<slug>/`). */
101
- label: string;
102
- /** The node's primary-doc version (null when the node carries no primary doc). */
103
- version: string | null;
104
- /** The node's primary-doc status. */
105
- status: string | null;
106
- /** The node's primary-doc declared type (spec §12 · D34). */
107
- docType: DocKey | null;
108
- /** The node's own primary-line rounds (the node's primary `progress.json` row). */
109
- rounds: Record<string, number[]>;
110
- /** The wave segment — one line per derived wave (empty when the node has no plan). */
111
- waveLines?: BoardLine[];
112
- /** The node's non-wave lines (overall/spec/plan/branch), each with its own rounds —
113
- * the full per-line breakdown the board layout composes from. */
114
- lines: BoardLine[];
115
- }
116
-
117
- /** The DocKey domain of the `doc-type:` declaration — the declared value must
118
- * be one of the four keys; anything else reads null (present facts, never a
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;
122
-
123
- /**
124
- * BoardView — the slug → node-tree board face. The static fact readers of this
125
- * task's slice: the phase scan over the specs doc root and the artifact header
126
- * read. Pure reads — zero tree writes, zero ledger writes, zero child dispatch.
127
- */
128
- // biome-ignore lint/complexity/noStaticOnlyClass: the board fact-read surface — the zero-bare-function discipline admits no standalone predicate functions.
129
- export class BoardView {
130
- /** scanPhases(programSlug, repoRoot) — the phase-suffix set under the program:
131
- * every specs-dir entry whose stem is `<programSlug>-p<major>(.<minor>)*`
132
- * (optionally followed by a `-design`/`-overall` doc tail — `Workspace.slugFromDoc`
133
- * strips it) contributes its suffix, sorted by the dot-separated numeric path
134
- * (2 < 10, `p4.1` after `p4`). No parent node is synthesized — only the
135
- * suffixes actually found on disk return. */
136
- static scanPhases(programSlug: string, repoRoot: string): string[] {
137
- const specsDir = path.join(repoRoot, ENGINE_RUNTIME.docRoots.specs);
138
- let entries: string[];
139
- try {
140
- entries = readdirSync(specsDir);
141
- } catch {
142
- return [];
143
- }
144
- const prefix = `${programSlug}-`;
145
- const suffixes = new Set<string>();
146
- for (const entry of entries) {
147
- if (!/\.md$/.test(entry) || !entry.startsWith(prefix)) continue;
148
- const slug = Workspace.slugFromDoc(entry);
149
- if (slug === programSlug || !slug.startsWith(prefix)) continue;
150
- const suffix = slug.slice(prefix.length);
151
- if (PHASE_SUFFIX_BARE.test(suffix)) suffixes.add(`-${suffix}`);
152
- }
153
- return [...suffixes].sort((a, b) => {
154
- const numsOf = (s: string) =>
155
- s
156
- .slice(2) // strip the leading `-p`
157
- .split(".")
158
- .map((part) => Number.parseInt(part, 10));
159
- const aNums = numsOf(a);
160
- const bNums = numsOf(b);
161
- for (let i = 0; i < Math.min(aNums.length, bNums.length); i++) {
162
- if (aNums[i] !== bNums[i]) return aNums[i] - bNums[i];
163
- }
164
- return aNums.length - bNums.length;
165
- });
166
- }
167
-
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
- static readHeader(docPath: string): BoardNodeHeader {
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
- }
182
-
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
- * by the board and the capsule's doc-class discrimination. An absent file, a
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;
212
- }
213
-
214
- // -------------------------------------------------------------------------
215
- // the progress projection (spec §5) — the per-node progress.json single-source read
216
- // -------------------------------------------------------------------------
217
-
218
- /** projectNodes(programSlug, repoRoot) — the program's node set projected: the
219
- * overall node (`<program>-overall`) followed by each on-disk phase node
220
- * (`<program>-p<N>`, the file-system-only phase scan). Each node projects its
221
- * OWN workspace `progress.json` — a pure read, zero new data, zero new judgment. */
222
- static projectNodes(programSlug: string, repoRoot: string): BoardProgress[] {
223
- const nodes = [
224
- `${programSlug}-overall`,
225
- ...BoardView.scanPhases(programSlug, repoRoot).map((suffix) => `${programSlug}${suffix}`),
226
- ];
227
- return nodes.map((slug) => BoardView.projectNode(slug, repoRoot));
228
- }
229
-
230
- /** projectNode(nodeSlug, repoRoot) — one node's progress projection. The node's
231
- * workspace is `<repoRoot>/.kairos/cdd/<nodeSlug>/`; its `progress.json` rows are
232
- * the ONLY progress source (the rounds ride their cycle-NUMBER arrays — D28
233
- * identity; the retired numeric form is out-of-format and renders no count). The
234
- * node's doc header facts derive from the file system alone (absent doc → nulls,
235
- * never synthesized); the wave segment derives from the node's plan (no plan →
236
- * empty segment, no throw). Pure reads — zero tree writes, zero ledger writes,
237
- * zero child dispatch. */
238
- static projectNode(nodeSlug: string, repoRoot: string): BoardProgress {
239
- const root = new WorkspaceRoot(repoRoot, ENGINE_RUNTIME.handoffNamespace.workspaceRoot);
240
- const ledger = new Ledger(new Workspace(root, nodeSlug), new ConfigLoader());
241
- const progress = ledger.readProgress();
242
- const overall = BoardView.#isOverallNode(nodeSlug);
243
- const programStem = overall ? nodeSlug.slice(0, -"-overall".length) : nodeSlug;
244
- const docs = Workspace.docsOfSlug(programStem, repoRoot);
245
-
246
- const lines: BoardLine[] = [];
247
- if (overall) {
248
- lines.push(BoardView.#docLine("overall", "spec", docs.overall, progress));
249
- } else {
250
- lines.push(BoardView.#docLine("spec", "spec", docs.spec, progress));
251
- lines.push(BoardView.#docLine("plan", "plan", docs.plan, progress));
252
- }
253
- const primary = lines[0]!;
254
- const waveLines = overall ? [] : BoardView.#waveLines(docs.plan, progress, ledger);
255
- lines.push(BoardView.#roundsLine("branch", "branch", progress));
256
- return {
257
- label: nodeSlug,
258
- version: primary.version,
259
- status: primary.status,
260
- docType: primary.docType,
261
- rounds: primary.rounds,
262
- ...(waveLines.length > 0 ? { waveLines } : {}),
263
- lines,
264
- };
265
- }
266
-
267
- /** roundsCell(rounds) — the line's `implement×N · review×N · fix×N` cell text. Each
268
- * `×N` is the CYCLE-NUMBER array's element count (D28 identity — `[1,3]` → `×2`),
269
- * never the stored number: a non-array (the retired numeric form) contributes no
270
- * cell. Verbs render in the fixed board order; an out-of-order verb appends after. */
271
- static roundsCell(rounds: Record<string, number[]>): string {
272
- const cells: string[] = [];
273
- const verbs = [...VERB_ORDER, ...Object.keys(rounds).filter((v) => !VERB_ORDER.includes(v))];
274
- for (const verb of verbs) {
275
- const value = rounds[verb];
276
- if (Array.isArray(value) && value.length > 0) cells.push(`${verb}×${value.length}`);
277
- }
278
- return cells.join(" · ");
279
- }
280
-
281
- /** Whether a node slug names the program's overall node (its workspace unit is
282
- * `<program>-overall`, the overall doc's own review line keyed `spec`). A label
283
- * test on the node slug — NOT a filename→doc-type derivation (D34): the overall
284
- * node is fixed at the program root, never inferred from a doc filename. */
285
- static #isOverallNode(nodeSlug: string): boolean {
286
- return /-overall$/.test(nodeSlug);
287
- }
288
-
289
- // -------------------------------------------------------------------------
290
- // the render face (spec §5.3) — the slug → board layout + the next derivation
291
- // -------------------------------------------------------------------------
292
-
293
- /** Whether the slug names anything on disk — the file-system-only existence test
294
- * (the board's "no matching file → exit 2, never a wall on a ghost slug"). A
295
- * program slug matches its overall or any on-disk phase; a phase slug matches its
296
- * overall anchor, spec or plan. */
297
- static hasNode(slug: string, repoRoot: string): boolean {
298
- if (Workspace.phaseSuffixOf(slug) !== null) {
299
- const docs = Workspace.docsOfSlug(slug, repoRoot);
300
- return docs.overall !== null || docs.spec !== null || docs.plan !== null;
301
- }
302
- return (
303
- Workspace.docsOfSlug(slug, repoRoot).overall !== null ||
304
- BoardView.scanPhases(slug, repoRoot).length > 0
305
- );
306
- }
307
-
308
- /** render(slug, repoRoot, words, host, channels) — the slug's progress board
309
- * (spec §5.3): the phase form (`overall/spec/plan/wave/branch` + one line per
310
- * derived wave + the fixed legend + the `next:` line) or the program form (the
311
- * overall line with its own rounds + one summary line per phase + `next: done` —
312
- * cross-phase never participates in next). The argv channel is threaded into the
313
- * shared `RouteRenderer` (the SAME channel the capsule's route render reads, so
314
- * the board's `next:` and the engine's `next:` literal compose their argv from
315
- * ONE flag-spelling source — never a second hard-coded format string). A present
316
- * doc line carrying no `doc-type:` key renders its `doc-type:
317
- * missing (BLOCKED)` marker and the board exits 2 (spec §12 · D34 — the consumer
318
- * blocks, zero filename fallback). Pure reads — zero tree writes, zero ledger
319
- * writes, zero child dispatch. */
320
- static render(
321
- slug: string,
322
- repoRoot: string,
323
- words: Words,
324
- host: string,
325
- channels: Readonly<Record<string, RouteChannelRow>> = {},
326
- ): BoardRender {
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);
334
- const exitCode =
335
- Workspace.phaseSuffixOf(slug) !== null
336
- ? BoardView.#phaseBoard(lines, slug, root, words, host, channels)
337
- : BoardView.#programBoard(lines, slug, root);
338
- lines.push("", PROGRESS_LEGEND.board);
339
- return { lines, exitCode };
340
- }
341
-
342
- /** The phase board render — the overall/spec/plan/wave/branch rows + the next
343
- * derivation. Returns the exit code (2 when a present doc line carries no type
344
- * declaration). The repo-basis `root` is threaded alone (F2) — its `absolute`
345
- * feeds the fs-facing helpers, its value object the path renders. */
346
- static #phaseBoard(
347
- lines: string[],
348
- slug: string,
349
- root: RepoRoot,
350
- words: Words,
351
- host: string,
352
- channels: Readonly<Record<string, RouteChannelRow>>,
353
- ): number {
354
- const repoRoot = root.absolute;
355
- const suffix = Workspace.phaseSuffixOf(slug)!;
356
- const program = slug.slice(0, slug.length - suffix.length);
357
- const docs = Workspace.docsOfSlug(slug, repoRoot);
358
- const node = BoardView.projectNode(slug, repoRoot);
359
- const overall = BoardView.projectNode(`${program}-overall`, repoRoot);
360
- // Select each line by its label (never a positional index with a non-null
361
- // assertion — a reorder of node.lines must not silently swap the facts).
362
- const specLine = node.lines.find((line) => line.label === "spec");
363
- const planLine = node.lines.find((line) => line.label === "plan");
364
- const branchLine = node.lines.find((line) => line.label === "branch");
365
- let blocked = false;
366
-
367
- const overallDoc = BoardView.#docCell(docs.overall, overall.lines[0]!, root);
368
- lines.push(` overall ${overallDoc.text}`);
369
- blocked ||= overallDoc.blocked;
370
-
371
- const specDoc = BoardView.#docCell(docs.spec, specLine!, root);
372
- lines.push(` spec ${specDoc.text}`);
373
- blocked ||= specDoc.blocked;
374
-
375
- const planDoc = BoardView.#docCell(docs.plan, planLine!, root);
376
- lines.push(` plan ${planDoc.text}`);
377
- blocked ||= planDoc.blocked;
378
-
379
- const waves = node.waveLines ?? [];
380
- if (waves.length === 0) {
381
- lines.push(" wave (none)");
382
- } else {
383
- // The marker column is fixed-width: every wave label is padded to the widest
384
- // label so the ✔/▶/○ markers align into one column (spec §5.2 · D40).
385
- const labelWidth = Math.max(...waves.map((wave) => wave.label.length));
386
- waves.forEach((wave, index) => {
387
- const prefix = index === 0 ? " wave " : " ";
388
- const cell = BoardView.roundsCell(wave.rounds);
389
- const label = wave.label.padEnd(labelWidth);
390
- lines.push(
391
- `${prefix}${label} ${wave.marker ?? ""}${cell === "" ? "" : ` ${cell}`}`.trimEnd(),
392
- );
393
- });
394
- }
395
-
396
- const ledger = BoardView.#ledgerOf(slug, repoRoot);
397
- const branchClosed = ledger.lineClosed("branch", "branch");
398
- const branchRounds = BoardView.roundsCell(branchLine!.rounds);
399
- lines.push(
400
- ` branch ${branchClosed ? `${PROGRESS_MARKERS.done} closed` : `${PROGRESS_MARKERS.pending} open`}${branchRounds === "" ? "" : ` ${branchRounds}`}`.trimEnd(),
401
- );
402
-
403
- lines.push("");
404
- lines.push(` next: ${BoardView.#nextOf(ledger, node, docs, words, host, channels, root)}`);
405
- return blocked ? 2 : 0;
406
- }
407
-
408
- /** The program board render — the overall line (its own rounds) + one summary line
409
- * per on-disk phase + `next: done` (cross-phase never participates in next, spec
410
- * §6.5). Returns the exit code (2 when the overall doc OR any present phase doc
411
- * carries no type declaration — the phase board's BLOCK propagates here, spec §12 ·
412
- * D34: zero silent fallback). */
413
- static #programBoard(lines: string[], slug: string, root: RepoRoot): number {
414
- const repoRoot = root.absolute;
415
- const nodes = BoardView.projectNodes(slug, repoRoot);
416
- const overall = nodes[0]!;
417
- const overallDoc = BoardView.#docCell(
418
- Workspace.docsOfSlug(slug, repoRoot).overall,
419
- overall.lines[0]!,
420
- root,
421
- );
422
- lines.push(` overall ${overallDoc.text}`);
423
- lines.push("");
424
- let blocked = overallDoc.blocked;
425
- for (const node of nodes.slice(1)) {
426
- const label = node.label.slice(slug.length).replace(/^-p/, "P");
427
- const spec = node.lines.find((line) => line.label === "spec");
428
- const plan = node.lines.find((line) => line.label === "plan");
429
- const branch = node.lines.find((line) => line.label === "branch");
430
- // The phase line's doc-cell read: a present phase spec/plan without its
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.
434
- const docs = Workspace.docsOfSlug(node.label, repoRoot);
435
- const phaseBlocked =
436
- BoardView.#docCell(docs.spec, spec!, root).blocked ||
437
- BoardView.#docCell(docs.plan, plan!, root).blocked;
438
- blocked ||= phaseBlocked;
439
- const status = phaseBlocked ? "doc-type: missing (BLOCKED)" : (spec?.status ?? "Pending");
440
- // The phase's wave summary token (spec §5.3): the wave segment's first wave
441
- // number + an ellipsis (`wave W1…`) — the phase's wave progress at a glance,
442
- // derived from the SAME wave segment the phase board renders (no second read).
443
- const waves = node.waveLines ?? [];
444
- const waveCell = waves.length === 0 ? "" : `${waves[0]!.label.split(" ")[0]}…`;
445
- const parts: string[] = [];
446
- const cells: Array<[string, string]> = [
447
- ["spec", BoardView.roundsCell(spec?.rounds ?? {})],
448
- ["plan", BoardView.roundsCell(plan?.rounds ?? {})],
449
- ["wave", waveCell],
450
- ["branch", BoardView.roundsCell(branch?.rounds ?? {})],
451
- ];
452
- for (const [key, cell] of cells) if (cell !== "") parts.push(`${key} ${cell}`);
453
- const tail = parts.join(" · ");
454
- lines.push(` phase ${label} ${status}${tail === "" ? "" : ` ${tail}`}`);
455
- }
456
- lines.push("");
457
- lines.push(" next: done");
458
- return blocked ? 2 : 0;
459
- }
460
-
461
- /** One doc line's cell text — the doc path, the header facts and the line's
462
- * rounds (spec §5.3: `overall <path> v2.33 · Draft review×4`); a present doc
463
- * carrying no `doc-type:` key renders its `doc-type: missing
464
- * (BLOCKED)` marker in place of the facts (blocked = true). An absent doc renders
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 } {
473
- if (docPath === null) return { text: "(none)", blocked: false };
474
- const rel = root.relativize(docPath);
475
- if (line.docType === null) {
476
- const facts: string[] = [];
477
- if (line.version !== null) facts.push(line.version);
478
- if (line.status !== null) facts.push(line.status);
479
- const head = facts.length === 0 ? "" : `${facts.join(" · ")} `;
480
- return { text: `${rel} ${head}doc-type: missing (BLOCKED)`, blocked: true };
481
- }
482
- const facts: string[] = [rel];
483
- const meta = [line.version, line.status].filter((part) => part !== null).join(" · ");
484
- if (meta !== "") facts.push(meta);
485
- const rounds = BoardView.roundsCell(line.rounds);
486
- if (rounds !== "") facts.push(rounds);
487
- return { text: facts.join(" "), blocked: false };
488
- }
489
-
490
- /** The node's ledger — the progress.json read face the render's closure/next
491
- * derivation consumes (each node reads its OWN workspace). */
492
- static #ledgerOf(nodeSlug: string, repoRoot: string): Ledger {
493
- const root = new WorkspaceRoot(repoRoot, ENGINE_RUNTIME.handoffNamespace.workspaceRoot);
494
- return new Ledger(new Workspace(root, nodeSlug), new ConfigLoader());
495
- }
496
-
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). */
511
- static #nextOf(
512
- ledger: Ledger,
513
- node: BoardProgress,
514
- docs: SlugDocs,
515
- words: Words,
516
- host: string,
517
- channels: Readonly<Record<string, RouteChannelRow>>,
518
- root: RepoRoot,
519
- ): string {
520
- const renderer = new RouteRenderer(words, channels, host, root);
521
- const waves = node.waveLines ?? [];
522
- // The plan's open frontier wave — the SAME ready batch the dispatch engine's
523
- // task-graph frontier yields (frontier over closedWaves()).
524
- const waveKey = BoardView.#waveFrontierKey(ledger, docs.plan);
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": {
529
- closed: ledger.lineClosed("spec", "spec"),
530
- active: docs.spec === null ? null : ledger.lineRoute("spec", "spec"),
531
- target: docs.spec === null ? null : { type: "spec", id: docs.spec },
532
- },
533
- plan: {
534
- closed: ledger.lineClosed("plan", "plan"),
535
- active: docs.plan === null ? null : ledger.lineRoute("plan", "plan"),
536
- target: docs.plan === null ? null : { type: "plan", id: docs.plan, plan: docs.plan },
537
- },
538
- wave: {
539
- // The wave face is exhausted (skipped) only when the plan yields a wave set
540
- // and every wave is done — an empty wave segment (no plan) is not an exhausted
541
- // face (nothing was closed), so it stays the frontier and hands off.
542
- closed: waves.length > 0 && waves.every((wave) => wave.marker === PROGRESS_MARKERS.done),
543
- active: waveKey === null ? null : ledger.waveLineRoute(waveKey),
544
- target: docs.plan === null ? null : { type: "wave", id: waveKey ?? "", plan: docs.plan },
545
- },
546
- branch: {
547
- closed: ledger.lineClosed("branch", "branch"),
548
- active: ledger.lineRoute("branch", "branch"),
549
- target: { type: "branch", id: "branch", plan: docs.plan ?? undefined },
550
- },
551
- };
552
- const next = NextStepRouter.walk(report);
553
- return renderer.render(next.route, next.target);
554
- }
555
-
556
- /** The plan's open frontier wave key — the ready batch over the node's `closedWaves()`
557
- * set, the SAME derivation the dispatch engine's task-graph frontier walks (T26, the
558
- * wave-unitary model). Null when the plan is absent or no wave remains open — the wave
559
- * face then holds no active hop (a not-yet-started wave line hands off to the next face). */
560
- static #waveFrontierKey(ledger: Ledger, planPath: string | null): string | null {
561
- const graph = BoardView.#planGraph(planPath);
562
- if (graph === null) return null;
563
- const frontier = graph.frontier(ledger.closedWaves());
564
- return frontier.length === 0 ? null : frontier.join(",");
565
- }
566
-
567
- /** The plan's task graph — the ONE guarded plan read shared by the wave frontier
568
- * key and the wave segment (`readFileSync` throwing on an unreadable plan is
569
- * caught here: a null plan path or an unreadable/absent file yields null, honoring
570
- * the wave face's "degradation, never a throw" contract). */
571
- static #planGraph(planPath: string | null): TaskGraph | null {
572
- if (planPath === null) return null;
573
- try {
574
- return new TaskGraph(
575
- new PlanDocType("plan").parse(readFileSync(planPath, "utf8").split("\n")),
576
- );
577
- } catch {
578
- return null;
579
- }
580
- }
581
-
582
- /** One doc line — the header facts read from the doc (absent → nulls) + the row's
583
- * rounds keyed by the line's `progress.json` key. */
584
- static #docLine(
585
- label: string,
586
- key: string,
587
- docPath: string | null,
588
- progress: ProgressData | null,
589
- ): BoardLine {
590
- const header =
591
- docPath === null
592
- ? { version: null, status: null, docType: null }
593
- : BoardView.readHeader(docPath);
594
- return { label, ...header, rounds: BoardView.#rowRounds(progress, key), marker: null };
595
- }
596
-
597
- /** The branch line — a docless line whose rounds ride the `branch` row. */
598
- static #roundsLine(label: string, key: string, progress: ProgressData | null): BoardLine {
599
- return {
600
- label,
601
- version: null,
602
- status: null,
603
- docType: null,
604
- rounds: BoardView.#rowRounds(progress, key),
605
- marker: null,
606
- };
607
- }
608
-
609
- /** The node's row rounds for one key — array-form ONLY (a non-array verb value —
610
- * the retired numeric form — is dropped: zero count renders, no compatibility
611
- * layer). An absent row/verb yields an empty map. */
612
- static #rowRounds(progress: ProgressData | null, key: string): Record<string, number[]> {
613
- const row = progress?.waves.find((candidate) => candidate.wave === key);
614
- const rounds: Record<string, number[]> = {};
615
- for (const [verb, value] of Object.entries(row?.rounds ?? {})) {
616
- if (Array.isArray(value)) rounds[verb] = [...value];
617
- }
618
- return rounds;
619
- }
620
-
621
- /** The node's wave segment — one line per derived wave (its ✔/▶/○ marker rides the
622
- * SAME `TaskGraph.report(closedWaves())` read the board and the pre-flight gate
623
- * share — the same source GraphView renders from), the wave's own `progress.json`
624
- * row spread alongside. No plan → empty segment (degradation, never a throw). */
625
- static #waveLines(
626
- planPath: string | null,
627
- progress: ProgressData | null,
628
- ledger: Ledger,
629
- ): BoardLine[] {
630
- const graph = BoardView.#planGraph(planPath);
631
- if (graph === null) return [];
632
- const report = graph.report(ledger.closedWaves());
633
- const done = new Set(report.done);
634
- const currentIndex = report.waves.findIndex((wave) => wave.some((id) => !done.has(id)));
635
- return report.waves.map((wave, index) => {
636
- const closed = wave.every((id) => done.has(id));
637
- const marker = closed
638
- ? PROGRESS_MARKERS.done
639
- : index === currentIndex
640
- ? PROGRESS_MARKERS.current
641
- : PROGRESS_MARKERS.pending;
642
- return {
643
- label: `W${index + 1} {${wave.join(",")}}`,
644
- version: null,
645
- status: null,
646
- docType: null,
647
- rounds: BoardView.#rowRounds(progress, wave.join(",")),
648
- marker,
649
- };
650
- });
651
- }
652
- }