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