@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,545 +0,0 @@
1
- // packages/cdd-engine/src-next/session/__tests__/preflight.test.ts
2
- // P4.1 T1 — PreFlight suite: the lifecycle pre-flight seam (design §1) — the
3
- // tree-clean + graph + wave + doc-contract dispatch gates converge into ONE
4
- // single-entry gate:
5
- // · the dirty-tree hard gate — implement/review/fix on a dirty working tree
6
- // BLOCKs (the CDD_BLOCKED guidance) BEFORE any wave/doc judgment, child zero;
7
- // · the gate order — tree-clean → graph → wave → doc-contract, one verdict
8
- // carries the run gate list (the judgeable order);
9
- // · the graph gate — a plan whose DependsOn edges fail validates refuses;
10
- // · the wave gate — the three-verb split/wrong-phase refusals ride the seam;
11
- // · the doc-contract gate — the doc faces judge the target doc's structure;
12
- // · the unreadable-doc skip — an absent doc carries no doc-contract judgment;
13
- // · the lifecycle wiring — a refused frame never reaches the child dispatch.
14
- // Fixtures are hermetic git repos (the dirty/clean tree) + a memory fs for the
15
- // doc-contract backstop (the contract's context seam reads through it).
16
-
17
- import { spawnSync } from "node:child_process";
18
- import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
19
- import { tmpdir } from "node:os";
20
- import path from "node:path";
21
- import { describe, expect, it } from "vitest";
22
- import type { DocFs } from "../../contract/invariants.ts";
23
- import { Contract } from "../../contract/judge.ts";
24
- import type { DocKey } from "../../contract/project.ts";
25
- import { Words } from "../../face/words.ts";
26
- import { ConfigLoader } from "../../infra/config.ts";
27
- import { GitClient } from "../../infra/git.ts";
28
- import type { RepoPath } from "../../infra/root.ts";
29
- import { Workspace, WorkspaceRoot } from "../../infra/workspace.ts";
30
- import { targetFaces } from "../faces.ts";
31
- import { Ledger } from "../ledger.ts";
32
- import type { PreFlightContext, PreFlightVerdict } from "../preflight.ts";
33
- import { PreFlight } from "../preflight.ts";
34
- import type { DispatchStep, OpenFrame } from "../run.ts";
35
- import { EMPTY_RUN_STATE, Lifecycle } from "../run.ts";
36
- import { WaveGate } from "../wave.ts";
37
-
38
- // ---------------------------------------------------------------------------
39
- // fixtures
40
- // ---------------------------------------------------------------------------
41
-
42
- /** A hermetic git repo — the tree-clean gate's judgment surface. The `.kairos` +
43
- * `/docs/` gitignore keeps the fixture's synthetic writes (the engine workspace
44
- * mirror + the docs) out of the tree — same as the consumer setup the kairos README
45
- * documents. Pass an explicit ignore content to shape it (the no-`.kairos`-ignore
46
- * consumer regression). */
47
- const gitRepo = (ignore = ".kairos\n/docs/\n"): { repoRoot: string; cleanup: () => void } => {
48
- const repoRoot = mkdtempSync(path.join(tmpdir(), "preflight-"));
49
- spawnSync("git", ["init", "-q"], { cwd: repoRoot });
50
- spawnSync("git", ["config", "user.email", "preflight@test"], { cwd: repoRoot });
51
- spawnSync("git", ["config", "user.name", "preflight-test"], { cwd: repoRoot });
52
- writeFileSync(path.join(repoRoot, ".gitignore"), ignore, "utf8");
53
- writeFileSync(path.join(repoRoot, "seed.txt"), "seed\n", "utf8");
54
- spawnSync("git", ["add", "-A"], { cwd: repoRoot });
55
- spawnSync("git", ["commit", "-q", "-m", "seed"], { cwd: repoRoot });
56
- return { repoRoot, cleanup: () => rmSync(repoRoot, { recursive: true, force: true }) };
57
- };
58
-
59
- /** Dirty the fixture repo — an uncommitted change (`git status --porcelain` non-empty). */
60
- const dirty = (repoRoot: string): void => {
61
- writeFileSync(path.join(repoRoot, "dirty.txt"), "dirty\n", "utf8");
62
- };
63
-
64
- /** A plan literal over `### Task N:` blocks + `- **DependsOn**:` values (the
65
- * front-matter head the plan parser reads). */
66
- const planDoc = (blocks: readonly (readonly string[])[]): string => {
67
- return [
68
- "---",
69
- "title: Test Plan",
70
- "doc-type: plan",
71
- "version: v1.0",
72
- "date: 2026-10-09",
73
- "spec: docs/kairos/specs/x-design.md",
74
- "parent-program: docs/kairos/specs/x-overall.md",
75
- "parent-version: v1.0",
76
- "---",
77
- "",
78
- "## Constraints",
79
- "",
80
- "- delta",
81
- "",
82
- ...blocks.flat(),
83
- ].join("\n");
84
- };
85
-
86
- const task = (id: number, dependsOn: string): readonly string[] => {
87
- return [
88
- `### Task ${id}: task ${id}`,
89
- "- **Objective**: objective",
90
- "- **Files**: a.ts",
91
- "- **Consumes**: x",
92
- "- **Produces**: y",
93
- "- **Steps**:",
94
- " - step — checkable: green",
95
- "- **Acceptance**: ok",
96
- `- **DependsOn**: ${dependsOn}`,
97
- ];
98
- };
99
-
100
- /** The hermetic PreFlight — real git + the real contract + the shared wave gate. */
101
- const preflightOf = (fs?: DocFs): PreFlight => {
102
- return new PreFlight({
103
- git: new GitClient(),
104
- contract: new Contract(),
105
- words: new Words(),
106
- waveGate: new WaveGate(),
107
- fs,
108
- });
109
- };
110
-
111
- /** A memory fs — every path resolves into the judged doc's own content (the
112
- * context-seam backstop: chain/sibling reads return the judged content, so the
113
- * doc-contract gate's judgment is the doc's own structure, not its neighbors). */
114
- const memoryFs = (content: string): DocFs => {
115
- return {
116
- exists: () => true,
117
- read: () => content,
118
- // The sibling scan resolves the `parent-program:` target basename — the
119
- // judged doc's family lists it.
120
- list: (_p: string) => ["x-overall.md"],
121
- };
122
- };
123
-
124
- /** A conforming phase-spec — every current + P4.1-T2 phase-spec element present
125
- * (the front-matter head (since T6) + the version lineage + a Change-history
126
- * table + the design skeleton), so the doc-contract gate passes it (zero
127
- * structural findings). */
128
- const CONFORMING_SPEC = [
129
- "---",
130
- "title: Test Spec",
131
- "doc-type: phase-spec",
132
- "version: v1.0",
133
- "date: 2026-10-09",
134
- "status: Draft",
135
- "author: x",
136
- "parent-program: docs/kairos/specs/x-overall.md",
137
- "parent-version: v1.0",
138
- "depends-on: P1",
139
- "---",
140
- "",
141
- "## Design",
142
- "",
143
- "Design intro — the double-layer skeleton semantics.",
144
- "",
145
- "### 1. 数据面",
146
- "#### 1.1 登记表",
147
- "- text",
148
- "",
149
- "### Acceptance criteria",
150
- "",
151
- "- `c`",
152
- "",
153
- "## Constraints",
154
- "",
155
- "- delta",
156
- "",
157
- "## Change history",
158
- "",
159
- "| Version | date | summary | author |",
160
- "|---|---|---|---|",
161
- "| v1.0 | 2026-10-09 | initial | [human] |",
162
- ].join("\n");
163
-
164
- /** A defective phase-spec — the required sections/head keys missing, so the
165
- * doc-contract gate refuses it (the negative case). */
166
- const DEFECTIVE_SPEC = [
167
- "---",
168
- "title: Test Spec",
169
- "doc-type: phase-spec",
170
- "version: v1.0",
171
- "status: Draft",
172
- "---",
173
- "",
174
- "## Design",
175
- ].join("\n");
176
-
177
- // ---------------------------------------------------------------------------
178
- // the seam's context builders
179
- // ---------------------------------------------------------------------------
180
-
181
- /** The wave-face context — the plan + the requested group over a fresh ledger. */
182
- const waveCtx = (
183
- repoRoot: string,
184
- blocks: readonly (readonly string[])[],
185
- tasks: number[],
186
- verb: PreFlightContext["verb"],
187
- ): PreFlightContext => {
188
- const workspace = new Workspace(
189
- new WorkspaceRoot(path.join(repoRoot, ".kairos", "cdd"), "session"),
190
- "preflight-slug",
191
- ).ensure();
192
- const ledger = new Ledger(workspace, new ConfigLoader());
193
- return {
194
- verb,
195
- type: "wave",
196
- repoRoot,
197
- planText: planDoc(blocks),
198
- tasks: new Set(tasks),
199
- ledger,
200
- doc: null,
201
- };
202
- };
203
-
204
- /** The doc-face context — the target doc judged by the doc-contract gate. `docKey`
205
- * is the doc's declared type (spec §12 · D34); null models a present doc carrying
206
- * no `doc-type:` key (the seam BLOCKs). */
207
- const docCtx = (
208
- repoRoot: string,
209
- docKey: DocKey | null,
210
- verb: PreFlightContext["verb"],
211
- ): PreFlightContext => {
212
- const workspace = new Workspace(
213
- new WorkspaceRoot(path.join(repoRoot, ".kairos", "cdd"), "session"),
214
- "preflight-slug",
215
- ).ensure();
216
- const ledger = new Ledger(workspace, new ConfigLoader());
217
- return {
218
- verb,
219
- type: docKey === "plan" ? "plan" : "spec",
220
- repoRoot,
221
- planText: null,
222
- tasks: null,
223
- ledger,
224
- doc: {
225
- docKey,
226
- path: `docs/kairos/specs/${docKey === "plan" ? "plan" : "spec"}.md` as RepoPath,
227
- },
228
- };
229
- };
230
-
231
- // ---------------------------------------------------------------------------
232
- // the dirty-tree hard gate — three verbs × dirty → BLOCK
233
- // ---------------------------------------------------------------------------
234
-
235
- describe("PreFlight — the clean-tree hard gate (implement/review/fix)", () => {
236
- it("a dirty tree BLOCKs implement/review/fix with the dirty-tree gate before any other judgment", async () => {
237
- const { repoRoot, cleanup } = gitRepo();
238
- try {
239
- dirty(repoRoot);
240
- const preflight = preflightOf();
241
- const plan = [task(1, "none"), task(2, "1")];
242
- for (const verb of ["implement", "review", "fix"] as const) {
243
- const verdict = await preflight.vet(waveCtx(repoRoot, plan, [1], verb));
244
- expect(verdict.ok).toBe(false);
245
- expect(verdict.gate).toBe("tree-clean");
246
- expect(verdict.reason).toBe("dirty-tree");
247
- expect(verdict.message).toContain("commit or discard");
248
- expect(verdict.order).toEqual(["tree-clean"]);
249
- }
250
- } finally {
251
- cleanup();
252
- }
253
- });
254
-
255
- it("the dirty-tree gate runs FIRST — a dirty tree BLOCKs even when the wave/doc judgments would refuse too", async () => {
256
- const { repoRoot, cleanup } = gitRepo();
257
- try {
258
- dirty(repoRoot);
259
- const preflight = preflightOf();
260
- // dangling DependsOn (the graph gate would refuse) + a defective doc: the dirty
261
- // tree still owns the verdict — the gate sequence stops at tree-clean.
262
- const badPlan = [task(1, "none"), task(2, "99")];
263
- const verdict = await preflight.vet(docCtx(repoRoot, "phase-spec", "review"));
264
- expect(verdict.ok).toBe(false);
265
- expect(verdict.gate).toBe("tree-clean");
266
- expect(verdict.order).toEqual(["tree-clean"]);
267
- const waveVerdict = await preflight.vet(waveCtx(repoRoot, badPlan, [1, 2], "implement"));
268
- expect(waveVerdict.gate).toBe("tree-clean");
269
- } finally {
270
- cleanup();
271
- }
272
- });
273
-
274
- it("the workspace self-publishes its .gitignore — a consumer repo WITHOUT a .kairos ignore stays clean across dispatches (P4.1 F1 regression)", async () => {
275
- // The consumer-repo shape: no `.kairos` in the root .gitignore (the fixture's
276
- // default mask is overridden). The scene's workspace ensure self-publishes
277
- // `.kairos/.gitignore` (namespace root, content `*`) BEFORE the gate reads
278
- // the tree, so git's own judgment is clean — the engine's run artifacts never
279
- // read as uncommitted user work, with zero engine-side exclusion in isClean.
280
- const { repoRoot, cleanup } = gitRepo("/docs/\n");
281
- try {
282
- const workspace = new Workspace(
283
- new WorkspaceRoot(repoRoot, ".kairos/cdd"),
284
- "preflight-slug",
285
- ).ensure();
286
- workspace.writeJson("implement-1.json", { status: "APPROVED" });
287
- // The self-published keep-out marker sits at the namespace root
288
- expect(readFileSync(path.join(repoRoot, ".kairos", ".gitignore"), "utf8")).toBe("*\n");
289
- const ctx = waveCtx(repoRoot, [task(1, "none")], [1], "review");
290
- ctx.ledger!.recordRound("1", "implement"); // the first dispatch's progress — review now opens
291
- const preflight = preflightOf();
292
- const verdict = await preflight.vet(ctx);
293
- expect(verdict.ok).toBe(true);
294
- expect(verdict.order).toEqual(["tree-clean", "graph", "wave"]);
295
- // A genuinely dirty USER file still refuses — the ignore is the workspace's
296
- // own self-published marker, never a pass for the user's uncommitted work.
297
- dirty(repoRoot);
298
- const refused = await preflight.vet(waveCtx(repoRoot, [task(1, "none")], [1], "implement"));
299
- expect(refused.ok).toBe(false);
300
- expect(refused.gate).toBe("tree-clean");
301
- expect(refused.reason).toBe("dirty-tree");
302
- // The bonus semantics: a user who git-TRACKS the workspace keeps seeing its
303
- // changes — `.gitignore` affects only untracked files, so the tracked
304
- // workspace surface rides the gate like any other user file. Force-add the
305
- // ignored workspace (the `*` marker hides it from a plain add) to model the
306
- // tracked case.
307
- rmSync(path.join(repoRoot, "dirty.txt"));
308
- spawnSync("git", ["add", "-f", ".kairos"], { cwd: repoRoot });
309
- spawnSync("git", ["add", "-A", ":!dirty.txt"], { cwd: repoRoot });
310
- spawnSync("git", ["commit", "-q", "-m", "track the workspace"], { cwd: repoRoot });
311
- // A change to the TRACKED workspace surface (implement-1.json was force-added
312
- // into the commit above) rides the gate like any user file — the ignore covers
313
- // only untracked paths.
314
- workspace.writeJson("implement-1.json", { status: "APPROVED", modified: true });
315
- const tracked = await preflightOf().vet(
316
- waveCtx(repoRoot, [task(1, "none")], [1], "implement"),
317
- );
318
- expect(tracked.ok).toBe(false);
319
- expect(tracked.gate).toBe("tree-clean");
320
- } finally {
321
- cleanup();
322
- }
323
- });
324
- });
325
-
326
- // ---------------------------------------------------------------------------
327
- // the gate order composition — the judgeable gate order
328
- // ---------------------------------------------------------------------------
329
-
330
- describe("PreFlight — the gate order composition (tree-clean → graph → wave → doc-contract)", () => {
331
- it("a clean wave dispatch passes through tree-clean → graph → wave in order", async () => {
332
- const { repoRoot, cleanup } = gitRepo();
333
- try {
334
- const preflight = preflightOf();
335
- const verdict = await preflight.vet(
336
- waveCtx(repoRoot, [task(1, "none"), task(2, "1")], [1], "implement"),
337
- );
338
- expect(verdict.ok).toBe(true);
339
- expect(verdict.order).toEqual(["tree-clean", "graph", "wave"]);
340
- } finally {
341
- cleanup();
342
- }
343
- });
344
-
345
- it("a clean doc dispatch passes through tree-clean → doc-contract in order", async () => {
346
- const { repoRoot, cleanup } = gitRepo();
347
- try {
348
- const preflight = preflightOf(memoryFs(CONFORMING_SPEC));
349
- const verdict = await preflight.vet(docCtx(repoRoot, "phase-spec", "review"));
350
- expect(verdict.ok).toBe(true);
351
- expect(verdict.order).toEqual(["tree-clean", "doc-contract"]);
352
- } finally {
353
- cleanup();
354
- }
355
- });
356
- });
357
-
358
- // ---------------------------------------------------------------------------
359
- // the graph gate
360
- // ---------------------------------------------------------------------------
361
-
362
- describe("PreFlight — the graph gate", () => {
363
- it("a dangling DependsOn edge BLOCKs the dispatch with the named edge issues", async () => {
364
- const { repoRoot, cleanup } = gitRepo();
365
- try {
366
- const preflight = preflightOf();
367
- const verdict = await preflight.vet(
368
- waveCtx(repoRoot, [task(1, "none"), task(2, "99")], [1, 2], "implement"),
369
- );
370
- expect(verdict.ok).toBe(false);
371
- expect(verdict.gate).toBe("graph");
372
- expect(verdict.reason).toBe("graph");
373
- expect(verdict.message).toContain("edge violation");
374
- expect((verdict.details ?? []).length).toBeGreaterThan(0);
375
- } finally {
376
- cleanup();
377
- }
378
- });
379
- });
380
-
381
- // ---------------------------------------------------------------------------
382
- // the wave gate
383
- // ---------------------------------------------------------------------------
384
-
385
- describe("PreFlight — the wave gate inside the seam", () => {
386
- it("a split/subset --tasks rides the WaveGate split BLOCK (the word-table row)", async () => {
387
- const { repoRoot, cleanup } = gitRepo();
388
- try {
389
- const preflight = preflightOf();
390
- // two independent tasks open the single root wave {1,2} — a {1} request splits
391
- const verdict = await preflight.vet(
392
- waveCtx(repoRoot, [task(1, "none"), task(2, "none")], [1], "review"),
393
- );
394
- expect(verdict.ok).toBe(false);
395
- expect(verdict.gate).toBe("wave");
396
- expect(verdict.reason).toBe("split");
397
- expect(verdict.message).toContain("derived wave");
398
- // the wave gate ran AFTER tree-clean + graph
399
- expect(verdict.order).toEqual(["tree-clean", "graph", "wave"]);
400
- } finally {
401
- cleanup();
402
- }
403
- });
404
-
405
- it("a wrong-phase request rides the WaveGate wrong-phase BLOCK", async () => {
406
- const { repoRoot, cleanup } = gitRepo();
407
- try {
408
- const preflight = preflightOf();
409
- const ctx = waveCtx(repoRoot, [task(1, "none")], [1], "implement");
410
- ctx.ledger!.recordRound("1", "implement"); // the open wave now sits at review
411
- const verdict = await preflight.vet(ctx);
412
- expect(verdict.ok).toBe(false);
413
- expect(verdict.gate).toBe("wave");
414
- expect(verdict.reason).toBe("wrong-phase");
415
- expect(verdict.message).toContain("at review");
416
- } finally {
417
- cleanup();
418
- }
419
- });
420
- });
421
-
422
- // ---------------------------------------------------------------------------
423
- // the doc-contract gate
424
- // ---------------------------------------------------------------------------
425
-
426
- describe("PreFlight — the doc-contract gate (Contract.validate over the doc face)", () => {
427
- it("a doc face whose target carries structural findings BLOCKs with the named findings", async () => {
428
- const { repoRoot, cleanup } = gitRepo();
429
- try {
430
- const preflight = preflightOf(memoryFs(DEFECTIVE_SPEC));
431
- const verdict = await preflight.vet(docCtx(repoRoot, "phase-spec", "review"));
432
- expect(verdict.ok).toBe(false);
433
- expect(verdict.gate).toBe("doc-contract");
434
- expect(verdict.reason).toBe("doc-contract");
435
- expect((verdict.details ?? []).length).toBeGreaterThan(0);
436
- } finally {
437
- cleanup();
438
- }
439
- });
440
-
441
- it("an unreadable target doc skips the doc-contract judgment (no judgment, no BLOCK)", async () => {
442
- const { repoRoot, cleanup } = gitRepo();
443
- try {
444
- const preflight = preflightOf({
445
- exists: () => false,
446
- read: () => null,
447
- list: () => [],
448
- });
449
- const verdict = await preflight.vet(docCtx(repoRoot, "phase-spec", "review"));
450
- expect(verdict.ok).toBe(true);
451
- expect(verdict.order).toEqual(["tree-clean", "doc-contract"]);
452
- } finally {
453
- cleanup();
454
- }
455
- });
456
-
457
- it("a present doc carrying no Doc type declaration BLOCKs — zero filename-suffix fallback (spec §12 · D34)", async () => {
458
- const { repoRoot, cleanup } = gitRepo();
459
- try {
460
- const preflight = preflightOf(memoryFs(CONFORMING_SPEC));
461
- const verdict = await preflight.vet(docCtx(repoRoot, null, "review"));
462
- expect(verdict.ok).toBe(false);
463
- expect(verdict.gate).toBe("doc-contract");
464
- expect(verdict.reason).toBe("doc-contract");
465
- expect(verdict.message).toContain("declares no `doc-type:` key");
466
- expect(verdict.order).toEqual(["tree-clean", "doc-contract"]);
467
- } finally {
468
- cleanup();
469
- }
470
- });
471
-
472
- it("an unparseable front-matter BLOCKs with the REAL YAML failure — never the no-doc-type misread (D1 · #341)", async () => {
473
- const { repoRoot, cleanup } = gitRepo();
474
- try {
475
- const malformed = [
476
- "---",
477
- "title: Test Spec",
478
- "doc-type: phase-spec",
479
- "version: v1.0",
480
- "status: Draft",
481
- "author: [human] · Claude Opus 5",
482
- "---",
483
- "",
484
- "## Design",
485
- ].join("\n");
486
- const preflight = preflightOf(memoryFs(malformed));
487
- const verdict = await preflight.vet(docCtx(repoRoot, "phase-spec", "review"));
488
- expect(verdict.ok).toBe(false);
489
- expect(verdict.gate).toBe("doc-contract");
490
- expect(verdict.reason).toBe("doc-contract");
491
- // the misread dies — the wording reports the parse position, never "no doc-type"
492
- expect(verdict.message).toContain("not valid YAML");
493
- expect(verdict.message).toMatch(/on line \d+, column \d+/);
494
- expect(verdict.message).not.toContain("declares no `doc-type:` key");
495
- } finally {
496
- cleanup();
497
- }
498
- });
499
- });
500
-
501
- // ---------------------------------------------------------------------------
502
- // the lifecycle wiring — a refused frame never reaches the child dispatch
503
- // ---------------------------------------------------------------------------
504
-
505
- describe("PreFlight — the lifecycle dispatch-entry wiring (child zero dispatch)", () => {
506
- it("advance() refuses a preflight-blocked frame without dispatching the child", async () => {
507
- const { repoRoot, cleanup } = gitRepo();
508
- try {
509
- const calls: OpenFrame[] = [];
510
- const dispatch: DispatchStep = async (frame) => {
511
- calls.push(frame);
512
- return { status: "APPROVED", findings: [] };
513
- };
514
- const blocked: PreFlightVerdict = {
515
- ok: false,
516
- gate: "tree-clean",
517
- reason: "dirty-tree",
518
- message: "the working tree is dirty",
519
- order: ["tree-clean"],
520
- };
521
- const run = new Lifecycle({
522
- face: targetFaces.spec,
523
- state: EMPTY_RUN_STATE,
524
- ledger: new Ledger(
525
- new Workspace(
526
- new WorkspaceRoot(path.join(repoRoot, ".kairos", "cdd"), "session"),
527
- "preflight-slug",
528
- ).ensure(),
529
- new ConfigLoader(),
530
- ),
531
- dispatch,
532
- target: { kind: "spec", doc: "docs/kairos/specs/x.md" },
533
- preflight: { gate: () => blocked },
534
- });
535
- const step = await run.advance();
536
- expect(step).not.toBeNull();
537
- expect(step!.preflight).toEqual(blocked);
538
- expect(step!.route).toBeNull();
539
- expect(calls).toEqual([]); // child zero dispatch
540
- expect(await run.advance()).not.toBeNull(); // the refused frame re-offers (resume)
541
- } finally {
542
- cleanup();
543
- }
544
- });
545
- });
@@ -1,142 +0,0 @@
1
- // packages/cdd-engine/src-next/session/__tests__/round-naming.test.ts
2
- // P11 T4 — the RoundNaming colocated pins: the frame → artifact-name derivations
3
- // (report / evidence / brief) the lifecycle's read-back and the dry-run preview
4
- // share, and the family-op mapping those stems key on. The class touches no disk
5
- // (resolve is pure path arithmetic), so the workspace is constructed inline.
6
-
7
- import path from "node:path";
8
- import { describe, expect, it } from "vitest";
9
- import { Workspace, WorkspaceRoot } from "../../infra/workspace.ts";
10
- import type { OpType } from "../ledger.ts";
11
- import { RoundNaming } from "../round-naming.ts";
12
- import type { OpenFrame } from "../run.ts";
13
-
14
- const ROOT = "/repo";
15
- const WORKSPACE = new Workspace(new WorkspaceRoot(ROOT, ".kairos/cdd"), "p3");
16
- const NAMING = new RoundNaming(WORKSPACE);
17
- const inWorkspace = (name: string): string => path.join(ROOT, ".kairos/cdd", "p3", name);
18
-
19
- /** A frame built from the wave implement frame's shape; `over` supplies the face. */
20
- const frame = (over: Partial<OpenFrame>): OpenFrame => ({
21
- type: "wave",
22
- phase: "implement",
23
- round: 1,
24
- target: { kind: "wave", tasks: [1] },
25
- params: { tasks: "1" },
26
- key: "1",
27
- ...over,
28
- });
29
-
30
- describe("RoundNaming — the frame → prescribed artifact names (report / evidence / brief)", () => {
31
- it("derives the brief path of a wave's task group", () => {
32
- expect(NAMING.brief("1,2")).toBe(inWorkspace("tasks-1,2-brief.md"));
33
- });
34
-
35
- it("derives the report path per face — the wave/branch family stems and the doc line's round-keyed stem", () => {
36
- // the wave implement round carries no round token (the line keys implement alone)
37
- expect(NAMING.report(frame({ type: "wave", phase: "implement" }))).toBe(
38
- inWorkspace("tasks-1-implement-report.md"),
39
- );
40
- // a wave review round books its own round-keyed report
41
- expect(
42
- NAMING.report(
43
- frame({ type: "wave", phase: "review", round: 2, params: { tasks: "1", round: 2 } }),
44
- ),
45
- ).toBe(inWorkspace("tasks-1-review-2-report.md"));
46
- // the branch review rides the review op (branch-review → review), never the raw phase
47
- expect(
48
- NAMING.report(
49
- frame({
50
- type: "branch",
51
- phase: "branch-review",
52
- round: 3,
53
- target: { kind: "branch" },
54
- params: { round: 3 },
55
- key: "branch",
56
- }),
57
- ),
58
- ).toBe(inWorkspace("branch-review-3-report.md"));
59
- expect(
60
- NAMING.report(
61
- frame({
62
- type: "branch",
63
- phase: "fix",
64
- round: 1,
65
- target: { kind: "branch" },
66
- params: { round: 1 },
67
- key: "branch",
68
- }),
69
- ),
70
- ).toBe(inWorkspace("branch-fix-1-report.md"));
71
- // the doc line keys the {type}-{op}-{round} stem
72
- expect(
73
- NAMING.report(
74
- frame({
75
- type: "spec",
76
- phase: "review",
77
- round: 1,
78
- target: { kind: "spec", doc: "s.md" },
79
- params: { round: 1 },
80
- }),
81
- ),
82
- ).toBe(inWorkspace("spec-review-1-report.md"));
83
- expect(
84
- NAMING.report(
85
- frame({
86
- type: "plan",
87
- phase: "fix",
88
- round: 2,
89
- target: { kind: "plan", doc: "p.md" },
90
- params: { round: 2 },
91
- }),
92
- ),
93
- ).toBe(inWorkspace("plan-fix-2-report.md"));
94
- });
95
-
96
- it("derives the evidence name/path on the work faces only — the review and doc faces prescribe none", () => {
97
- // the task families key the line; the branch line names the family alone
98
- expect(NAMING.evidenceName(frame({ type: "wave", phase: "implement" }))).toBe(
99
- "tasks-1-test-evidence.json",
100
- );
101
- expect(NAMING.evidence(frame({ type: "wave", phase: "implement" }))).toBe(
102
- inWorkspace("tasks-1-test-evidence.json"),
103
- );
104
- expect(
105
- NAMING.evidenceName(
106
- frame({ type: "wave", phase: "fix", round: 2, params: { tasks: "1", round: 2 } }),
107
- ),
108
- ).toBe("tasks-1-test-evidence.json");
109
- expect(
110
- NAMING.evidenceName(
111
- frame({ type: "branch", phase: "fix", target: { kind: "branch" }, params: { round: 1 } }),
112
- ),
113
- ).toBe("branch-test-evidence.json");
114
- // off the work faces the evidence slot is empty (only present facts ride)
115
- expect(
116
- NAMING.evidence(
117
- frame({ type: "wave", phase: "review", round: 1, params: { tasks: "1", round: 1 } }),
118
- ),
119
- ).toBe("");
120
- expect(
121
- NAMING.evidenceName(
122
- frame({ type: "spec", phase: "review", target: { kind: "spec", doc: "s.md" } }),
123
- ),
124
- ).toBe("");
125
- expect(
126
- NAMING.evidence(frame({ type: "plan", phase: "fix", target: { kind: "plan", doc: "p.md" } })),
127
- ).toBe("");
128
- });
129
-
130
- it("maps the frame phase to the handoff-family op — branch-review rides the review family", () => {
131
- expect(NAMING.op(frame({ phase: "implement" }))).toBe("implement");
132
- expect(NAMING.op(frame({ phase: "review" }))).toBe("review");
133
- expect(NAMING.op(frame({ phase: "fix" }))).toBe("fix");
134
- const branchReview = NAMING.op(frame({ type: "branch", phase: "branch-review" })) as OpType;
135
- expect(branchReview).toBe("review");
136
- });
137
-
138
- it("carries the evidence family prefix — tasks for the wave families, branch for the branch line", () => {
139
- expect(NAMING.prefix(frame({ type: "wave" }))).toBe("tasks");
140
- expect(NAMING.prefix(frame({ type: "branch" }))).toBe("branch");
141
- });
142
- });