@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
@@ -0,0 +1,522 @@
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
+ import { readdirSync, readFileSync } from "node:fs";
32
+ import path from "node:path";
33
+ import { PlanDocType } from "../contract/doc.js";
34
+ import { FrontMatterExtractor } from "../contract/frontmatter.js";
35
+ import { DOC_KEYS } from "../contract/project.js";
36
+ import { ConfigLoader } from "../infra/config.js";
37
+ import { RepoRoot } from "../infra/root.js";
38
+ import { ENGINE_RUNTIME } from "../infra/runtime.js";
39
+ import { PHASE_SUFFIX_BARE, Workspace, WorkspaceRoot } from "../infra/workspace.js";
40
+ import { TaskGraph } from "../session/graph.js";
41
+ import { Ledger } from "../session/ledger.js";
42
+ import { NextStepRouter } from "../session/next.js";
43
+ import { PROGRESS_LEGEND, PROGRESS_MARKERS } from "./graph-view.js";
44
+ import { RouteRenderer } from "./route-render.js";
45
+ /** The verb render order of a line's `×N` cell — the stable display order the board's
46
+ * round cells follow (an unexpected verb appends after these, never dropped). */
47
+ const VERB_ORDER = ["implement", "review", "branch-review", "fix"];
48
+ /** The DocKey domain of the `doc-type:` declaration — the declared value must
49
+ * be one of the four keys; anything else reads null (present facts, never a
50
+ * fabricated type). Derived from the ONE DocKey declaration (contract/project.ts
51
+ * re-exports declare.ts's canonical tuple) — never a second copy (spec §3.2 ③). */
52
+ const DOC_TYPE_DOMAIN = DOC_KEYS;
53
+ /**
54
+ * BoardView — the slug → node-tree board face. The static fact readers of this
55
+ * task's slice: the phase scan over the specs doc root and the artifact header
56
+ * read. Pure reads — zero tree writes, zero ledger writes, zero child dispatch.
57
+ */
58
+ // biome-ignore lint/complexity/noStaticOnlyClass: the board fact-read surface — the zero-bare-function discipline admits no standalone predicate functions.
59
+ export class BoardView {
60
+ /** scanPhases(programSlug, repoRoot) — the phase-suffix set under the program:
61
+ * every specs-dir entry whose stem is `<programSlug>-p<major>(.<minor>)*`
62
+ * (optionally followed by a `-design`/`-overall` doc tail — `Workspace.slugFromDoc`
63
+ * strips it) contributes its suffix, sorted by the dot-separated numeric path
64
+ * (2 < 10, `p4.1` after `p4`). No parent node is synthesized — only the
65
+ * suffixes actually found on disk return. */
66
+ static scanPhases(programSlug, repoRoot) {
67
+ const specsDir = path.join(repoRoot, ENGINE_RUNTIME.docRoots.specs);
68
+ let entries;
69
+ try {
70
+ entries = readdirSync(specsDir);
71
+ }
72
+ catch {
73
+ return [];
74
+ }
75
+ const prefix = `${programSlug}-`;
76
+ const suffixes = new Set();
77
+ for (const entry of entries) {
78
+ if (!/\.md$/.test(entry) || !entry.startsWith(prefix))
79
+ continue;
80
+ const slug = Workspace.slugFromDoc(entry);
81
+ if (slug === programSlug || !slug.startsWith(prefix))
82
+ continue;
83
+ const suffix = slug.slice(prefix.length);
84
+ if (PHASE_SUFFIX_BARE.test(suffix))
85
+ suffixes.add(`-${suffix}`);
86
+ }
87
+ return [...suffixes].sort((a, b) => {
88
+ const numsOf = (s) => s
89
+ .slice(2) // strip the leading `-p`
90
+ .split(".")
91
+ .map((part) => Number.parseInt(part, 10));
92
+ const aNums = numsOf(a);
93
+ const bNums = numsOf(b);
94
+ for (let i = 0; i < Math.min(aNums.length, bNums.length); i++) {
95
+ if (aNums[i] !== bNums[i])
96
+ return aNums[i] - bNums[i];
97
+ }
98
+ return aNums.length - bNums.length;
99
+ });
100
+ }
101
+ /** readHeader(docPath) — the artifact's header facts: the front-matter head
102
+ * record (spec §2.2's structured channel), read RAW through the shared
103
+ * `FrontMatterExtractor` — the version/status/doc-type scalars ride the
104
+ * head keys, never a header-line marker scan (spec §12 · D34 — the doc's
105
+ * declared facts live in the head record, no marker grammar). An absent file
106
+ * yields nulls on every fact — never a fabricated value. */
107
+ static readHeader(docPath) {
108
+ const { head } = FrontMatterExtractor.split(BoardView.#read(docPath) ?? "");
109
+ return {
110
+ version: head.version,
111
+ status: head.status,
112
+ docType: BoardView.#docTypeOf(head.docType),
113
+ };
114
+ }
115
+ /** readDocType(root, rel) — the doc's declared type alone (the front-matter
116
+ * `doc-type:` key, spec §12 · D34): the ONE declaration reading face shared
117
+ * by the board and the capsule's doc-class discrimination. An absent file, a
118
+ * missing key or an out-of-domain value reads null — the consumer
119
+ * blocks (zero filename-suffix fallback, zero dual-read layer). The path is the
120
+ * repoRoot-relative branded `RepoPath`, erased to the absolute syscall form
121
+ * through the ONE value object (`root.resolve`) just before the read — the brand
122
+ * is REAL (the absolute state is unrepresentable as a `RepoPath`, T4 §2.2), the
123
+ * same shape as `artifacts.readText(node, root, file)`). */
124
+ static readDocType(root, rel) {
125
+ return BoardView.#docTypeOf(FrontMatterExtractor.split(BoardView.#read(root.resolve(rel)) ?? "").head.docType);
126
+ }
127
+ /** The doc file's raw text — an absent/unreadable file reads null (the reads
128
+ * above degrade to null facts, never a throw). */
129
+ static #read(docPath) {
130
+ try {
131
+ return readFileSync(docPath, "utf8");
132
+ }
133
+ catch {
134
+ return null;
135
+ }
136
+ }
137
+ /** The declared doc type constrained to the DocKey domain (null otherwise). */
138
+ static #docTypeOf(declared) {
139
+ if (declared === null)
140
+ return null;
141
+ return DOC_TYPE_DOMAIN.includes(declared) ? declared : null;
142
+ }
143
+ // -------------------------------------------------------------------------
144
+ // the progress projection (spec §5) — the per-node progress.json single-source read
145
+ // -------------------------------------------------------------------------
146
+ /** projectNodes(programSlug, repoRoot) — the program's node set projected: the
147
+ * overall node (`<program>-overall`) followed by each on-disk phase node
148
+ * (`<program>-p<N>`, the file-system-only phase scan). Each node projects its
149
+ * OWN workspace `progress.json` — a pure read, zero new data, zero new judgment. */
150
+ static projectNodes(programSlug, repoRoot) {
151
+ const nodes = [
152
+ `${programSlug}-overall`,
153
+ ...BoardView.scanPhases(programSlug, repoRoot).map((suffix) => `${programSlug}${suffix}`),
154
+ ];
155
+ return nodes.map((slug) => BoardView.projectNode(slug, repoRoot));
156
+ }
157
+ /** projectNode(nodeSlug, repoRoot) — one node's progress projection. The node's
158
+ * workspace is `<repoRoot>/.kairos/cdd/<nodeSlug>/`; its `progress.json` rows are
159
+ * the ONLY progress source (the rounds ride their cycle-NUMBER arrays — D28
160
+ * identity; the retired numeric form is out-of-format and renders no count). The
161
+ * node's doc header facts derive from the file system alone (absent doc → nulls,
162
+ * never synthesized); the wave segment derives from the node's plan (no plan →
163
+ * empty segment, no throw). Pure reads — zero tree writes, zero ledger writes,
164
+ * zero child dispatch. */
165
+ static projectNode(nodeSlug, repoRoot) {
166
+ const root = new WorkspaceRoot(repoRoot, ENGINE_RUNTIME.handoffNamespace.workspaceRoot);
167
+ const ledger = new Ledger(new Workspace(root, nodeSlug), new ConfigLoader());
168
+ const progress = ledger.readProgress();
169
+ const overall = BoardView.#isOverallNode(nodeSlug);
170
+ const programStem = overall ? nodeSlug.slice(0, -"-overall".length) : nodeSlug;
171
+ const docs = Workspace.docsOfSlug(programStem, repoRoot);
172
+ const lines = [];
173
+ if (overall) {
174
+ lines.push(BoardView.#docLine("overall", "spec", docs.overall, progress));
175
+ }
176
+ else {
177
+ lines.push(BoardView.#docLine("spec", "spec", docs.spec, progress));
178
+ lines.push(BoardView.#docLine("plan", "plan", docs.plan, progress));
179
+ }
180
+ const primary = lines[0];
181
+ const waveLines = overall ? [] : BoardView.#waveLines(docs.plan, progress, ledger);
182
+ lines.push(BoardView.#roundsLine("branch", "branch", progress));
183
+ return {
184
+ label: nodeSlug,
185
+ version: primary.version,
186
+ status: primary.status,
187
+ docType: primary.docType,
188
+ rounds: primary.rounds,
189
+ ...(waveLines.length > 0 ? { waveLines } : {}),
190
+ lines,
191
+ };
192
+ }
193
+ /** roundsCell(rounds) — the line's `implement×N · review×N · fix×N` cell text. Each
194
+ * `×N` is the CYCLE-NUMBER array's element count (D28 identity — `[1,3]` → `×2`),
195
+ * never the stored number: a non-array (the retired numeric form) contributes no
196
+ * cell. Verbs render in the fixed board order; an out-of-order verb appends after. */
197
+ static roundsCell(rounds) {
198
+ const cells = [];
199
+ const verbs = [...VERB_ORDER, ...Object.keys(rounds).filter((v) => !VERB_ORDER.includes(v))];
200
+ for (const verb of verbs) {
201
+ const value = rounds[verb];
202
+ if (Array.isArray(value) && value.length > 0)
203
+ cells.push(`${verb}×${value.length}`);
204
+ }
205
+ return cells.join(" · ");
206
+ }
207
+ /** Whether a node slug names the program's overall node (its workspace unit is
208
+ * `<program>-overall`, the overall doc's own review line keyed `spec`). A label
209
+ * test on the node slug — NOT a filename→doc-type derivation (D34): the overall
210
+ * node is fixed at the program root, never inferred from a doc filename. */
211
+ static #isOverallNode(nodeSlug) {
212
+ return /-overall$/.test(nodeSlug);
213
+ }
214
+ // -------------------------------------------------------------------------
215
+ // the render face (spec §5.3) — the slug → board layout + the next derivation
216
+ // -------------------------------------------------------------------------
217
+ /** Whether the slug names anything on disk — the file-system-only existence test
218
+ * (the board's "no matching file → exit 2, never a wall on a ghost slug"). A
219
+ * program slug matches its overall or any on-disk phase; a phase slug matches its
220
+ * overall anchor, spec or plan. */
221
+ static hasNode(slug, repoRoot) {
222
+ if (Workspace.phaseSuffixOf(slug) !== null) {
223
+ const docs = Workspace.docsOfSlug(slug, repoRoot);
224
+ return docs.overall !== null || docs.spec !== null || docs.plan !== null;
225
+ }
226
+ return (Workspace.docsOfSlug(slug, repoRoot).overall !== null ||
227
+ BoardView.scanPhases(slug, repoRoot).length > 0);
228
+ }
229
+ /** render(slug, repoRoot, words, host, channels) — the slug's progress board
230
+ * (spec §5.3): the phase form (`overall/spec/plan/wave/branch` + one line per
231
+ * derived wave + the fixed legend + the `next:` line) or the program form (the
232
+ * overall line with its own rounds + one summary line per phase + `next: done` —
233
+ * cross-phase never participates in next). The argv channel is threaded into the
234
+ * shared `RouteRenderer` (the SAME channel the capsule's route render reads, so
235
+ * the board's `next:` and the engine's `next:` literal compose their argv from
236
+ * ONE flag-spelling source — never a second hard-coded format string). A present
237
+ * doc line carrying no `doc-type:` key renders its `doc-type:
238
+ * missing (BLOCKED)` marker and the board exits 2 (spec §12 · D34 — the consumer
239
+ * blocks, zero filename fallback). Pure reads — zero tree writes, zero ledger
240
+ * writes, zero child dispatch. */
241
+ static render(slug, repoRoot, words, host, channels = {}) {
242
+ const lines = [`cdd board: ${slug}`, ""];
243
+ // The repo-basis value object — constructed ONCE at this boundary, the ONE
244
+ // conversion exit the doc cells and the `next:` render normalize their embedded
245
+ // paths through (T1 `RepoRoot` · D47). The raw string is threaded no further:
246
+ // the board renders read the basis through `root.absolute` (F2 — one basis,
247
+ // one form).
248
+ const root = new RepoRoot(repoRoot);
249
+ const exitCode = Workspace.phaseSuffixOf(slug) !== null
250
+ ? BoardView.#phaseBoard(lines, slug, root, words, host, channels)
251
+ : BoardView.#programBoard(lines, slug, root);
252
+ lines.push("", PROGRESS_LEGEND.board);
253
+ return { lines, exitCode };
254
+ }
255
+ /** The phase board render — the overall/spec/plan/wave/branch rows + the next
256
+ * derivation. Returns the exit code (2 when a present doc line carries no type
257
+ * declaration). The repo-basis `root` is threaded alone (F2) — its `absolute`
258
+ * feeds the fs-facing helpers, its value object the path renders. */
259
+ static #phaseBoard(lines, slug, root, words, host, channels) {
260
+ const repoRoot = root.absolute;
261
+ const suffix = Workspace.phaseSuffixOf(slug);
262
+ const program = slug.slice(0, slug.length - suffix.length);
263
+ const docs = Workspace.docsOfSlug(slug, repoRoot);
264
+ const node = BoardView.projectNode(slug, repoRoot);
265
+ const overall = BoardView.projectNode(`${program}-overall`, repoRoot);
266
+ // Select each line by its label (never a positional index with a non-null
267
+ // assertion — a reorder of node.lines must not silently swap the facts).
268
+ const specLine = node.lines.find((line) => line.label === "spec");
269
+ const planLine = node.lines.find((line) => line.label === "plan");
270
+ const branchLine = node.lines.find((line) => line.label === "branch");
271
+ let blocked = false;
272
+ const overallDoc = BoardView.#docCell(docs.overall, overall.lines[0], root);
273
+ lines.push(` overall ${overallDoc.text}`);
274
+ blocked ||= overallDoc.blocked;
275
+ const specDoc = BoardView.#docCell(docs.spec, specLine, root);
276
+ lines.push(` spec ${specDoc.text}`);
277
+ blocked ||= specDoc.blocked;
278
+ const planDoc = BoardView.#docCell(docs.plan, planLine, root);
279
+ lines.push(` plan ${planDoc.text}`);
280
+ blocked ||= planDoc.blocked;
281
+ const waves = node.waveLines ?? [];
282
+ if (waves.length === 0) {
283
+ lines.push(" wave (none)");
284
+ }
285
+ else {
286
+ // The marker column is fixed-width: every wave label is padded to the widest
287
+ // label so the ✔/▶/○ markers align into one column (spec §5.2 · D40).
288
+ const labelWidth = Math.max(...waves.map((wave) => wave.label.length));
289
+ waves.forEach((wave, index) => {
290
+ const prefix = index === 0 ? " wave " : " ";
291
+ const cell = BoardView.roundsCell(wave.rounds);
292
+ const label = wave.label.padEnd(labelWidth);
293
+ lines.push(`${prefix}${label} ${wave.marker ?? ""}${cell === "" ? "" : ` ${cell}`}`.trimEnd());
294
+ });
295
+ }
296
+ const ledger = BoardView.#ledgerOf(slug, repoRoot);
297
+ const branchClosed = ledger.lineClosed("branch", "branch");
298
+ const branchRounds = BoardView.roundsCell(branchLine.rounds);
299
+ lines.push(` branch ${branchClosed ? `${PROGRESS_MARKERS.done} closed` : `${PROGRESS_MARKERS.pending} open`}${branchRounds === "" ? "" : ` ${branchRounds}`}`.trimEnd());
300
+ lines.push("");
301
+ lines.push(` next: ${BoardView.#nextOf(ledger, node, docs, words, host, channels, root)}`);
302
+ return blocked ? 2 : 0;
303
+ }
304
+ /** The program board render — the overall line (its own rounds) + one summary line
305
+ * per on-disk phase + `next: done` (cross-phase never participates in next, spec
306
+ * §6.5). Returns the exit code (2 when the overall doc OR any present phase doc
307
+ * carries no type declaration — the phase board's BLOCK propagates here, spec §12 ·
308
+ * D34: zero silent fallback). */
309
+ static #programBoard(lines, slug, root) {
310
+ const repoRoot = root.absolute;
311
+ const nodes = BoardView.projectNodes(slug, repoRoot);
312
+ const overall = nodes[0];
313
+ const overallDoc = BoardView.#docCell(Workspace.docsOfSlug(slug, repoRoot).overall, overall.lines[0], root);
314
+ lines.push(` overall ${overallDoc.text}`);
315
+ lines.push("");
316
+ let blocked = overallDoc.blocked;
317
+ for (const node of nodes.slice(1)) {
318
+ const label = node.label.slice(slug.length).replace(/^-p/, "P");
319
+ const spec = node.lines.find((line) => line.label === "spec");
320
+ const plan = node.lines.find((line) => line.label === "plan");
321
+ const branch = node.lines.find((line) => line.label === "branch");
322
+ // The phase line's doc-cell read: a present phase spec/plan without its
323
+ // A present spec/plan without its `doc-type:` key blocks the SAME way the
324
+ // phase board does — the marker renders on the phase line and the program
325
+ // board exits 2.
326
+ const docs = Workspace.docsOfSlug(node.label, repoRoot);
327
+ const phaseBlocked = BoardView.#docCell(docs.spec, spec, root).blocked ||
328
+ BoardView.#docCell(docs.plan, plan, root).blocked;
329
+ blocked ||= phaseBlocked;
330
+ const status = phaseBlocked ? "doc-type: missing (BLOCKED)" : (spec?.status ?? "Pending");
331
+ // The phase's wave summary token (spec §5.3): the wave segment's first wave
332
+ // number + an ellipsis (`wave W1…`) — the phase's wave progress at a glance,
333
+ // derived from the SAME wave segment the phase board renders (no second read).
334
+ const waves = node.waveLines ?? [];
335
+ const waveCell = waves.length === 0 ? "" : `${waves[0].label.split(" ")[0]}…`;
336
+ const parts = [];
337
+ const cells = [
338
+ ["spec", BoardView.roundsCell(spec?.rounds ?? {})],
339
+ ["plan", BoardView.roundsCell(plan?.rounds ?? {})],
340
+ ["wave", waveCell],
341
+ ["branch", BoardView.roundsCell(branch?.rounds ?? {})],
342
+ ];
343
+ for (const [key, cell] of cells)
344
+ if (cell !== "")
345
+ parts.push(`${key} ${cell}`);
346
+ const tail = parts.join(" · ");
347
+ lines.push(` phase ${label} ${status}${tail === "" ? "" : ` ${tail}`}`);
348
+ }
349
+ lines.push("");
350
+ lines.push(" next: done");
351
+ return blocked ? 2 : 0;
352
+ }
353
+ /** One doc line's cell text — the doc path, the header facts and the line's
354
+ * rounds (spec §5.3: `overall <path> v2.33 · Draft review×4`); a present doc
355
+ * carrying no `doc-type:` key renders its `doc-type: missing
356
+ * (BLOCKED)` marker in place of the facts (blocked = true). An absent doc renders
357
+ * `(none)` (degradation, never a throw). The doc path renders repoRoot-relative
358
+ * through the ONE value object (D47 — `docsOfSlug` derives it absolute; the board
359
+ * emits the ONE shape). */
360
+ static #docCell(docPath, line, root) {
361
+ if (docPath === null)
362
+ return { text: "(none)", blocked: false };
363
+ const rel = root.relativize(docPath);
364
+ if (line.docType === null) {
365
+ const facts = [];
366
+ if (line.version !== null)
367
+ facts.push(line.version);
368
+ if (line.status !== null)
369
+ facts.push(line.status);
370
+ const head = facts.length === 0 ? "" : `${facts.join(" · ")} `;
371
+ return { text: `${rel} ${head}doc-type: missing (BLOCKED)`, blocked: true };
372
+ }
373
+ const facts = [rel];
374
+ const meta = [line.version, line.status].filter((part) => part !== null).join(" · ");
375
+ if (meta !== "")
376
+ facts.push(meta);
377
+ const rounds = BoardView.roundsCell(line.rounds);
378
+ if (rounds !== "")
379
+ facts.push(rounds);
380
+ return { text: facts.join(" "), blocked: false };
381
+ }
382
+ /** The node's ledger — the progress.json read face the render's closure/next
383
+ * derivation consumes (each node reads its OWN workspace). */
384
+ static #ledgerOf(nodeSlug, repoRoot) {
385
+ const root = new WorkspaceRoot(repoRoot, ENGINE_RUNTIME.handoffNamespace.workspaceRoot);
386
+ return new Ledger(new Workspace(root, nodeSlug), new ConfigLoader());
387
+ }
388
+ /** The board's `next:` derivation (spec §6.5 · §18.2 · D40 deep-solve) — the board
389
+ * OBSERVES each phase face's state (closed · its ACTIVE C5 hop from the SAME
390
+ * state→next chain the dispatch engine walks — `Ledger#lineRoute` for the doc/branch
391
+ * lines, the plan frontier + `Ledger#waveLineRoute` for the wave line — and the
392
+ * render target) as a keyed report and hands it to the ONE router
393
+ * (`NextStepRouter.walk`) + the ONE renderer (`RouteRenderer`). The board forks
394
+ * ZERO transition rule: the face order and the frontier/entrance/anchor decision are
395
+ * the router's (D26 — one fact, one place). A line still in flight renders its next
396
+ * C5 hop (a fresh wave's `implement --plan <plan> --tasks <ids>`, an in-flight
397
+ * wave's `review`/`fix`, a fresh doc line's `review --type <type> …`); a face
398
+ * ENTERED but with no active hop renders its own pipeline exit; a face NOT yet
399
+ * entered (an absent doc) renders the PRECEDING entered face's exit (so a
400
+ * just-closed spec hands off to `cdd-plan`, never the absent plan's `cdd-dev`); all
401
+ * faces closed renders the last face's exit (the pipeline terminus). */
402
+ static #nextOf(ledger, node, docs, words, host, channels, root) {
403
+ const renderer = new RouteRenderer(words, channels, host, root);
404
+ const waves = node.waveLines ?? [];
405
+ // The plan's open frontier wave — the SAME ready batch the dispatch engine's
406
+ // task-graph frontier yields (frontier over closedWaves()).
407
+ const waveKey = BoardView.#waveFrontierKey(ledger, docs.plan);
408
+ // The observed faces keyed by their `PIPELINE_FACES` key — the router owns the
409
+ // order, so the board re-declares none (it only reports facts).
410
+ const report = {
411
+ "phase-spec": {
412
+ closed: ledger.lineClosed("spec", "spec"),
413
+ active: docs.spec === null ? null : ledger.lineRoute("spec", "spec"),
414
+ target: docs.spec === null ? null : { type: "spec", id: docs.spec },
415
+ },
416
+ plan: {
417
+ closed: ledger.lineClosed("plan", "plan"),
418
+ active: docs.plan === null ? null : ledger.lineRoute("plan", "plan"),
419
+ target: docs.plan === null ? null : { type: "plan", id: docs.plan, plan: docs.plan },
420
+ },
421
+ wave: {
422
+ // The wave face is exhausted (skipped) only when the plan yields a wave set
423
+ // and every wave is done — an empty wave segment (no plan) is not an exhausted
424
+ // face (nothing was closed), so it stays the frontier and hands off.
425
+ closed: waves.length > 0 && waves.every((wave) => wave.marker === PROGRESS_MARKERS.done),
426
+ active: waveKey === null ? null : ledger.waveLineRoute(waveKey),
427
+ target: docs.plan === null ? null : { type: "wave", id: waveKey ?? "", plan: docs.plan },
428
+ },
429
+ branch: {
430
+ closed: ledger.lineClosed("branch", "branch"),
431
+ active: ledger.lineRoute("branch", "branch"),
432
+ target: { type: "branch", id: "branch", plan: docs.plan ?? undefined },
433
+ },
434
+ };
435
+ const next = NextStepRouter.walk(report);
436
+ return renderer.render(next.route, next.target);
437
+ }
438
+ /** The plan's open frontier wave key — the ready batch over the node's `closedWaves()`
439
+ * set, the SAME derivation the dispatch engine's task-graph frontier walks (T26, the
440
+ * wave-unitary model). Null when the plan is absent or no wave remains open — the wave
441
+ * face then holds no active hop (a not-yet-started wave line hands off to the next face). */
442
+ static #waveFrontierKey(ledger, planPath) {
443
+ const graph = BoardView.#planGraph(planPath);
444
+ if (graph === null)
445
+ return null;
446
+ const frontier = graph.frontier(ledger.closedWaves());
447
+ return frontier.length === 0 ? null : frontier.join(",");
448
+ }
449
+ /** The plan's task graph — the ONE guarded plan read shared by the wave frontier
450
+ * key and the wave segment (`readFileSync` throwing on an unreadable plan is
451
+ * caught here: a null plan path or an unreadable/absent file yields null, honoring
452
+ * the wave face's "degradation, never a throw" contract). */
453
+ static #planGraph(planPath) {
454
+ if (planPath === null)
455
+ return null;
456
+ try {
457
+ return new TaskGraph(new PlanDocType("plan").parse(readFileSync(planPath, "utf8").split("\n")));
458
+ }
459
+ catch {
460
+ return null;
461
+ }
462
+ }
463
+ /** One doc line — the header facts read from the doc (absent → nulls) + the row's
464
+ * rounds keyed by the line's `progress.json` key. */
465
+ static #docLine(label, key, docPath, progress) {
466
+ const header = docPath === null
467
+ ? { version: null, status: null, docType: null }
468
+ : BoardView.readHeader(docPath);
469
+ return { label, ...header, rounds: BoardView.#rowRounds(progress, key), marker: null };
470
+ }
471
+ /** The branch line — a docless line whose rounds ride the `branch` row. */
472
+ static #roundsLine(label, key, progress) {
473
+ return {
474
+ label,
475
+ version: null,
476
+ status: null,
477
+ docType: null,
478
+ rounds: BoardView.#rowRounds(progress, key),
479
+ marker: null,
480
+ };
481
+ }
482
+ /** The node's row rounds for one key — array-form ONLY (a non-array verb value —
483
+ * the retired numeric form — is dropped: zero count renders, no compatibility
484
+ * layer). An absent row/verb yields an empty map. */
485
+ static #rowRounds(progress, key) {
486
+ const row = progress?.waves.find((candidate) => candidate.wave === key);
487
+ const rounds = {};
488
+ for (const [verb, value] of Object.entries(row?.rounds ?? {})) {
489
+ if (Array.isArray(value))
490
+ rounds[verb] = [...value];
491
+ }
492
+ return rounds;
493
+ }
494
+ /** The node's wave segment — one line per derived wave (its ✔/▶/○ marker rides the
495
+ * SAME `TaskGraph.report(closedWaves())` read the board and the pre-flight gate
496
+ * share — the same source GraphView renders from), the wave's own `progress.json`
497
+ * row spread alongside. No plan → empty segment (degradation, never a throw). */
498
+ static #waveLines(planPath, progress, ledger) {
499
+ const graph = BoardView.#planGraph(planPath);
500
+ if (graph === null)
501
+ return [];
502
+ const report = graph.report(ledger.closedWaves());
503
+ const done = new Set(report.done);
504
+ const currentIndex = report.waves.findIndex((wave) => wave.some((id) => !done.has(id)));
505
+ return report.waves.map((wave, index) => {
506
+ const closed = wave.every((id) => done.has(id));
507
+ const marker = closed
508
+ ? PROGRESS_MARKERS.done
509
+ : index === currentIndex
510
+ ? PROGRESS_MARKERS.current
511
+ : PROGRESS_MARKERS.pending;
512
+ return {
513
+ label: `W${index + 1} {${wave.join(",")}}`,
514
+ version: null,
515
+ status: null,
516
+ docType: null,
517
+ rounds: BoardView.#rowRounds(progress, wave.join(",")),
518
+ marker,
519
+ };
520
+ });
521
+ }
522
+ }
@@ -0,0 +1,141 @@
1
+ // packages/cdd-engine/src-next/face/capsule.ts
2
+ // T10 — the single capsule face (design spec §3.2: the `status · blocker · handoff
3
+ // · next:` word-face steady state). Capsule#emit renders the ALL-OP single stdout
4
+ // face — the capsule the orchestrator greps / routes on without opening the handoff:
5
+ //
6
+ // status: <status> · blocker: <blocker> · handoff: <handoff>
7
+ // next: <suggestion> (optional — the C5 route / a caller-rendered text)
8
+ //
9
+ // The byte face is v1-pinned: the key words (status · blocker · handoff) are
10
+ // pin-enforced by the CapsuleKey type and the emit signature — a data-only change
11
+ // cannot reshape them. What rides the injected Words table (the single word-table
12
+ // instance) is the `·` separator, the `next:` station anchor and the route/status
13
+ // vocabulary — a second table is excluded by construction. The `next:` value is
14
+ // either a caller-rendered string or the C5 Route rendered through the route-word
15
+ // table as a COMPLETE EXECUTABLE command (P4.1 T4 — the v1.39 semantic-literal
16
+ // reversal): `implement --plan <path> --tasks 17` · `review --type spec --spec
17
+ // <path>` · `fix --type spec --spec <path> --reviews <handoff> (read file back to
18
+ // confirm)` · `done` (the bare terminal word) · the soft-cap message verbatim.
19
+ // The argv is composed from the frame facts (the RouteTarget's type + id + plan)
20
+ // through the argv-channel flag spellings (the same channel the CLI parse reads —
21
+ // the render source is the declared channel, never a second hard-coded format
22
+ // string); the type flag renders ONLY where the verb's type discriminates
23
+ // (review/fix multi-type — implement is the single-type wave verb, so its literal
24
+ // never carries `--type` — the declaration's `parsed.args.type ?? "wave"` default
25
+ // semantics unchanged). The route-borne prose — the readback suffix · the soft-cap
26
+ // message — rides declared constants from session/next.ts, rendered by reference,
27
+ // never restated.
28
+ //
29
+ // D40 — the render delegates to the shared `RouteRenderer` (the ONE route →
30
+ // `next:` literal face, also consumed by the board); the capsule adds only the
31
+ // `done` face's doc-class discrimination (a spec doc's declared class decides the
32
+ // pipeline entry — or the BLOCKED face when the declaration is absent, spec §12).
33
+ //
34
+ // The class satisfies the session/run.ts CapsuleFace seam (T8's interaction point) —
35
+ // the capsule plugs into the lifecycle's attachCapsule contact, byte-identically.
36
+ // Module-level exports are the class — zero behavior-carrying bare functions.
37
+ import { RepoRoot } from "../infra/root.js";
38
+ import { NextStepRouter } from "../session/next.js";
39
+ import { BoardView } from "./board-view.js";
40
+ import { RouteRenderer } from "./route-render.js";
41
+ /**
42
+ * Capsule — the single capsule output face. emit(status, blocker, handoff, next)
43
+ * renders one round's facts into the byte-pinned `status · blocker · handoff` line
44
+ * plus the optional `next:` line. The key words are the CapsuleKey literals the
45
+ * kind loop renders (pin-enforced by the emit signature); the separator, station
46
+ * and route/status words ride the injected Words instance. The complete executable
47
+ * `next:` literal composes its full argv from the route + the additive optional
48
+ * RouteTarget (the frame's own facts) through the argv-channel flag spellings
49
+ * (P4.1 T4; same channel source parse reads — the 4-param signature stays
50
+ * byte-pinned, the target is an optional 5th, the channel an optional 2nd).
51
+ */
52
+ export class Capsule {
53
+ /** The single word table — the capsule's whole vocabulary source. */
54
+ #words;
55
+ /** The ONE route → `next:` literal renderer (D40 — shared with the board). */
56
+ #route;
57
+ /** The repo-basis value object the doc-target ids + the `handoff:` cell resolve
58
+ * through (T1 `RepoRoot` · D47 — the ONE conversion exit; `null` keeps a relative
59
+ * id relative · the hermetic-test default). */
60
+ #root;
61
+ constructor(words, channels = {}, host = "", root = null) {
62
+ this.#words = words;
63
+ this.#root = root;
64
+ this.#route = new RouteRenderer(words, channels, host, root);
65
+ }
66
+ /** emit(status, blocker, handoff, next, target) → the capsule stdout lines: the
67
+ * pinned `status · blocker · handoff` capsule line, then the optional `next:`
68
+ * line (a caller-rendered text, a C5 Route rendered as the complete executable
69
+ * command, or null/absent → no line). The additive optional RouteTarget supplies
70
+ * the frame's own type + id + plan for the executable literal (P4.1 T4); without
71
+ * it the route renders its bare classifier fallbacks (the 4-param signature stays
72
+ * byte-pinned). */
73
+ emit(status, blocker, handoff, next, target) {
74
+ const words = this.#words;
75
+ // The `handoff:` cell is a path value — normalized to the repoRoot-relative
76
+ // shape through the ONE value object (D47 · the ONE basis; `handoffPath` sources
77
+ // it absolute).
78
+ const cells = {
79
+ status,
80
+ blocker,
81
+ handoff: this.#rel(handoff),
82
+ };
83
+ const capsuleLine = words
84
+ .capsuleKeys()
85
+ .map((kind) => `${kind}: ${cells[kind]}`)
86
+ .join(words.capsuleSeparator());
87
+ const lines = [capsuleLine];
88
+ if (next !== undefined && next !== null) {
89
+ const text = typeof next === "string" ? next : this.#routeText(next, target);
90
+ lines.push(`${words.station("next")} ${text}`);
91
+ }
92
+ return lines;
93
+ }
94
+ /** The route → `next:` text render — the shared RouteRenderer (D40) unless the
95
+ * `done` face's doc-class discrimination fires (a spec doc's declared class decides
96
+ * the pipeline entry — or the BLOCKED face when the declaration is absent, spec
97
+ * §12 · D34). The capsule resolves the doc-class, then hands the resulting Route
98
+ * (a `handoff` carrying the entry, or the bare `done`) to the same renderer. */
99
+ #routeText(route, target) {
100
+ if (route.kind === "done" && target != null) {
101
+ const verdict = this.#docClassOf(target);
102
+ if (verdict === "blocked") {
103
+ return `${this.#words.station("blocked")} ${this.#words.routeWord("docType")}`;
104
+ }
105
+ // The declared doc-class (or a bare terminal) picks the pipeline entry — the
106
+ // same resolver + renderer the board consumes.
107
+ const key = verdict === "terminal" ? null : verdict;
108
+ return this.#route.render(NextStepRouter.resolve({ kind: "done" }, key), target);
109
+ }
110
+ return this.#route.render(route, target);
111
+ }
112
+ /** The target → doc-class verdict of the unified next face — the doc-class
113
+ * discrimination face (D33): the spec doc's class reads its DECLARED type (the
114
+ * front-matter `doc-type:` key, spec §12 · D34 — BoardView.readDocType,
115
+ * the one declaration reading face), never the filename suffix; the task-face
116
+ * targets key by type. `blocked` — the key is missing (the caller
117
+ * renders the BLOCKED face); `terminal` — no pipeline seam carries the declared
118
+ * class (`single-spec`, the table's five keys exclude it — the bare word). */
119
+ #docClassOf(target) {
120
+ if (target.type === "spec") {
121
+ // The read face takes the value object + the repoRoot-relative id (T4 §2.2);
122
+ // a `null` root (the hermetic default) keeps the value as its own basis. The
123
+ // `#rel` branded return needs no cast here (F3).
124
+ const declared = BoardView.readDocType(this.#root ?? new RepoRoot(""), this.#rel(target.id));
125
+ return declared === null ? "blocked" : declared === "single-spec" ? "terminal" : declared;
126
+ }
127
+ if (target.type === "plan")
128
+ return "plan";
129
+ if (target.type === "wave")
130
+ return "wave";
131
+ return "branch";
132
+ }
133
+ /** One path value normalized to the branded repoRoot-relative `RepoPath` through
134
+ * the ONE value object (D47); a `null` root (the hermetic default) passes the
135
+ * value through as its own basis. The branded return type carries the §2.2 brand
136
+ * to the read face (`BoardView.readDocType`) with NO call-site cast (branch-
137
+ * review-1 F3). */
138
+ #rel(value) {
139
+ return this.#root === null ? value : this.#root.relativize(value);
140
+ }
141
+ }