@oscaner-skills/cdd-engine 2.0.0 → 3.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (84) hide show
  1. package/README.md +2 -2
  2. package/README.zh-CN.md +2 -2
  3. package/package.json +4 -3
  4. package/src-next/__tests__/dead-decl.guard.test.ts +39 -0
  5. package/src-next/__tests__/floor.guard.test.ts +69 -0
  6. package/src-next/__tests__/issue-body.guard.test.ts +66 -0
  7. package/src-next/__tests__/phase-suffix.guard.test.ts +72 -0
  8. package/src-next/__tests__/smoke.integration.test.ts +60 -77
  9. package/src-next/__tests__/support/strip-comments.ts +99 -0
  10. package/src-next/__tests__/zero-dep.test.ts +6 -46
  11. package/src-next/contract/__tests__/__snapshots__/project.schema.overall-spec.snap +39 -21
  12. package/src-next/contract/__tests__/__snapshots__/project.schema.phase-spec.snap +40 -28
  13. package/src-next/contract/__tests__/__snapshots__/project.schema.plan.snap +40 -23
  14. package/src-next/contract/__tests__/__snapshots__/project.schema.single-spec.snap +38 -21
  15. package/src-next/contract/__tests__/__snapshots__/project.shape.overall-spec.snap +21 -6
  16. package/src-next/contract/__tests__/__snapshots__/project.shape.phase-spec.snap +22 -12
  17. package/src-next/contract/__tests__/__snapshots__/project.shape.plan.snap +23 -8
  18. package/src-next/contract/__tests__/__snapshots__/project.shape.single-spec.snap +21 -6
  19. package/src-next/contract/__tests__/declare.test.ts +251 -12
  20. package/src-next/contract/__tests__/doc.test.ts +214 -45
  21. package/src-next/contract/__tests__/dockey.guard.test.ts +58 -0
  22. package/src-next/contract/__tests__/edge-conditions.guard.test.ts +81 -0
  23. package/src-next/contract/__tests__/frontmatter.test.ts +164 -0
  24. package/src-next/contract/__tests__/judge.test.ts +410 -172
  25. package/src-next/contract/__tests__/lint.test.ts +49 -39
  26. package/src-next/contract/__tests__/project.test.ts +60 -19
  27. package/src-next/contract/__tests__/structure-pin.test.ts +186 -0
  28. package/src-next/contract/declare.ts +179 -91
  29. package/src-next/contract/doc.ts +227 -164
  30. package/src-next/contract/frontmatter.ts +233 -0
  31. package/src-next/contract/home-extractors.ts +397 -0
  32. package/src-next/contract/invariants.ts +214 -69
  33. package/src-next/contract/judge.ts +28 -19
  34. package/src-next/contract/lint.ts +5 -41
  35. package/src-next/contract/project.ts +103 -43
  36. package/src-next/contract/skill-anatomy.ts +39 -11
  37. package/src-next/face/__tests__/board-view.test.ts +318 -115
  38. package/src-next/face/__tests__/capsule.test.ts +49 -25
  39. package/src-next/face/__tests__/channel-closure.guard.test.ts +28 -1
  40. package/src-next/face/__tests__/cli.test.ts +1091 -837
  41. package/src-next/face/__tests__/face.test.ts +5 -5
  42. package/src-next/face/__tests__/install-rows.guard.test.ts +58 -0
  43. package/src-next/face/__tests__/preview.test.ts +374 -0
  44. package/src-next/face/__tests__/projection.test.ts +5 -3
  45. package/src-next/face/__tests__/repo-root.guard.test.ts +120 -0
  46. package/src-next/face/__tests__/termination.test.ts +650 -0
  47. package/src-next/face/artifacts.ts +90 -37
  48. package/src-next/face/board-view.ts +128 -138
  49. package/src-next/face/capsule.ts +30 -16
  50. package/src-next/face/cli.ts +306 -97
  51. package/src-next/face/declare.ts +15 -18
  52. package/src-next/face/gate.ts +19 -18
  53. package/src-next/face/host.ts +6 -30
  54. package/src-next/face/lifecycle.ts +213 -188
  55. package/src-next/face/preview.ts +151 -0
  56. package/src-next/face/projection.ts +4 -1
  57. package/src-next/face/route-render.ts +39 -14
  58. package/src-next/face/termination.ts +573 -0
  59. package/src-next/face/words.ts +20 -2
  60. package/src-next/infra/__tests__/infra.test.ts +49 -3
  61. package/src-next/infra/__tests__/root.test.ts +56 -0
  62. package/src-next/infra/doc-roots.ts +29 -0
  63. package/src-next/infra/root.ts +73 -0
  64. package/src-next/infra/runtime.ts +12 -65
  65. package/src-next/infra/workspace.ts +95 -5
  66. package/src-next/render/__tests__/render.test.ts +92 -41
  67. package/src-next/render/__tests__/skeleton.test.ts +282 -64
  68. package/src-next/render/issue-body.ts +5 -2
  69. package/src-next/render/skeleton.ts +155 -90
  70. package/src-next/render/templates.ts +51 -56
  71. package/src-next/session/__tests__/graph.test.ts +11 -4
  72. package/src-next/session/__tests__/ledger.test.ts +3 -2
  73. package/src-next/session/__tests__/next.test.ts +100 -8
  74. package/src-next/session/__tests__/preflight.test.ts +79 -25
  75. package/src-next/session/__tests__/round-naming.test.ts +142 -0
  76. package/src-next/session/__tests__/run.test.ts +140 -128
  77. package/src-next/session/__tests__/wave.test.ts +11 -4
  78. package/src-next/session/ledger.ts +96 -24
  79. package/src-next/session/next.ts +116 -15
  80. package/src-next/session/preflight.ts +41 -10
  81. package/src-next/session/round-naming.ts +84 -0
  82. package/src-next/session/run.ts +24 -20
  83. package/templates/report/issue-body.json +0 -46
  84. package/src-next/face/__tests__/sync-runner.test.ts +0 -70
@@ -49,12 +49,19 @@ const fixture = (): {
49
49
  return { ledger, workspace, repo, cleanup: () => rmSync(repo, { recursive: true, force: true }) };
50
50
  };
51
51
 
52
- /** A plan document over `### Task N:` blocks + `- **DependsOn**:` values. */
52
+ /** A plan document over `### Task N:` blocks + `- **DependsOn**:` values (the
53
+ * front-matter head the plan parser reads). */
53
54
  const planDoc = (blocks: readonly (readonly string[])[]): string => {
54
55
  return [
55
- "# Test Plan",
56
- "**Spec:** [x-design.md](docs/kairos/specs/x-design.md)",
57
- "- **Parent program**: [x-overall.md v1.0](docs/kairos/specs/x-overall.md)",
56
+ "---",
57
+ "title: Test Plan",
58
+ "doc-type: plan",
59
+ "version: v1.0",
60
+ "date: 2026-10-09",
61
+ "spec: docs/kairos/specs/x-design.md",
62
+ "parent-program: docs/kairos/specs/x-overall.md",
63
+ "parent-version: v1.0",
64
+ "---",
58
65
  "",
59
66
  "## Constraints",
60
67
  "",
@@ -74,7 +81,9 @@ const taskGraph = (blocks: readonly (readonly string[])[]): TaskGraph => {
74
81
  return new TaskGraph(new PlanDocType("plan").parse(planDoc(blocks).split("\n")));
75
82
  };
76
83
 
77
- /** A dispatch stub — records every dispatched frame and answers per phase. */
84
+ /** A dispatch stub — records every dispatched frame and answers per phase. The
85
+ * script stays synchronous (the fixtures are plain outcome builders); the step
86
+ * itself is the async seam the lifecycle awaits. */
78
87
  const stub = (
79
88
  script: (frame: OpenFrame) => DispatchOutcome,
80
89
  ): {
@@ -84,7 +93,7 @@ const stub = (
84
93
  const calls: OpenFrame[] = [];
85
94
  return {
86
95
  calls,
87
- step: (frame) => {
96
+ step: async (frame) => {
88
97
  calls.push(frame);
89
98
  return script(frame);
90
99
  },
@@ -94,7 +103,7 @@ const stub = (
94
103
  /** The approved-implement outcome — the canonical work-round result. */
95
104
  const APPROVED_IMPLEMENT: DispatchOutcome = {
96
105
  status: "APPROVED",
97
- artifacts: { brief: "/tmp/brief.md" },
106
+ carrier: { artifacts: { brief: "/tmp/brief.md" } },
98
107
  };
99
108
 
100
109
  const finding = (severity: "blocker" | "warn" | "nit") => ({ severity, summary: "drift" });
@@ -144,7 +153,7 @@ describe("the faces table — one row per target type", () => {
144
153
  });
145
154
 
146
155
  describe("the task small loop — implement → review → the next ready group", () => {
147
- it("runs one dispatch per advance across the frontier to the exhausted null", () => {
156
+ it("runs one dispatch per advance across the frontier to the exhausted null", async () => {
148
157
  const { ledger, cleanup } = fixture();
149
158
  try {
150
159
  const graph = taskGraph([task(1, "none"), task(2, "1")]);
@@ -158,7 +167,7 @@ describe("the task small loop — implement → review → the next ready group"
158
167
  dispatch: dispatch.step,
159
168
  });
160
169
 
161
- const step1 = run.advance();
170
+ const step1 = await run.advance();
162
171
  expect(step1).not.toBeNull();
163
172
  expect(step1!.frame.phase).toBe("implement");
164
173
  expect(step1!.frame.target).toEqual({ kind: "wave", tasks: [1] });
@@ -166,21 +175,21 @@ describe("the task small loop — implement → review → the next ready group"
166
175
  expect(step1!.round).toBe(1);
167
176
  expect(step1!.route).toEqual({ kind: "review" });
168
177
 
169
- const step2 = run.advance();
178
+ const step2 = await run.advance();
170
179
  expect(step2!.frame.phase).toBe("review");
171
180
  expect(step2!.frame.round).toBe(1);
172
181
  expect(step2!.route).toEqual({ kind: "next-wave", tasks: "2" });
173
182
 
174
- const step3 = run.advance();
183
+ const step3 = await run.advance();
175
184
  expect(step3!.frame.phase).toBe("implement");
176
185
  expect(step3!.frame.target).toEqual({ kind: "wave", tasks: [2] });
177
186
 
178
- const step4 = run.advance();
187
+ const step4 = await run.advance();
179
188
  expect(step4!.frame.phase).toBe("review");
180
189
  expect(step4!.frame.round).toBe(1);
181
190
  expect(step4!.route).toEqual({ kind: "done" });
182
191
 
183
- expect(run.advance()).toBeNull();
192
+ expect(await run.advance()).toBeNull();
184
193
 
185
194
  expect(dispatch.calls.map((f) => f.phase)).toEqual([
186
195
  "implement",
@@ -202,7 +211,7 @@ describe("the task small loop — implement → review → the next ready group"
202
211
  }
203
212
  });
204
213
 
205
- it("a review with blockers routes the fix, the re-review and the closure", () => {
214
+ it("a review with blockers routes the fix, the re-review and the closure", async () => {
206
215
  const { ledger, cleanup } = fixture();
207
216
  try {
208
217
  const graph = taskGraph([task(1, "none")]);
@@ -223,17 +232,17 @@ describe("the task small loop — implement → review → the next ready group"
223
232
  dispatch: dispatch.step,
224
233
  });
225
234
 
226
- const implement = run.advance();
235
+ const implement = await run.advance();
227
236
  expect(implement!.route).toEqual({ kind: "review" });
228
237
 
229
- const review1 = run.advance();
238
+ const review1 = await run.advance();
230
239
  expect(review1!.frame.phase).toBe("review");
231
240
  expect(review1!.frame.round).toBe(1);
232
241
  expect(review1!.route!.kind).toBe("fix");
233
242
  // the closed review leaves the task not done — the re-review awaits
234
243
  expect(graph.doneTasks()).toEqual(new Set());
235
244
 
236
- const fix = run.advance();
245
+ const fix = await run.advance();
237
246
  expect(fix!.frame.phase).toBe("fix");
238
247
  expect(fix!.frame.round).toBe(1);
239
248
  // the C5-1 re-review: the fix round carries the source review's blocker and
@@ -241,20 +250,20 @@ describe("the task small loop — implement → review → the next ready group"
241
250
  expect(fix!.route).toEqual({ kind: "review" });
242
251
  expect(graph.doneTasks()).toEqual(new Set());
243
252
 
244
- const review2 = run.advance();
253
+ const review2 = await run.advance();
245
254
  expect(review2!.frame.phase).toBe("review");
246
255
  expect(review2!.frame.round).toBe(2);
247
256
  expect(review2!.route).toEqual({ kind: "done" });
248
257
  expect(graph.doneTasks()).toEqual(new Set([1]));
249
258
 
250
- expect(run.advance()).toBeNull();
259
+ expect(await run.advance()).toBeNull();
251
260
  expect(phasesOf([review1!, fix!, review2!])).toEqual(["review", "fix", "review"]);
252
261
  } finally {
253
262
  cleanup();
254
263
  }
255
264
  });
256
265
 
257
- it("a warn/nit review closes through the fix — the REVIEW_FIX closure, no re-review", () => {
266
+ it("a warn/nit review closes through the fix — the REVIEW_FIX closure, no re-review", async () => {
258
267
  const { ledger, cleanup } = fixture();
259
268
  try {
260
269
  const graph = taskGraph([task(1, "none")]);
@@ -270,19 +279,19 @@ describe("the task small loop — implement → review → the next ready group"
270
279
  dispatch: dispatch.step,
271
280
  });
272
281
 
273
- run.advance();
274
- run.advance(); // the nit review
275
- const fix = run.advance();
282
+ await run.advance();
283
+ await run.advance(); // the nit review
284
+ const fix = await run.advance();
276
285
  expect(fix!.frame.phase).toBe("fix");
277
286
  expect(fix!.route).toEqual({ kind: "done" });
278
287
  expect(graph.doneTasks()).toEqual(new Set([1]));
279
- expect(run.advance()).toBeNull();
288
+ expect(await run.advance()).toBeNull();
280
289
  } finally {
281
290
  cleanup();
282
291
  }
283
292
  });
284
293
 
285
- it("a MID-RUN warn/nit wave routes the next wave after its fix — an early `done` is the {16,22,24}/rt/C5 regression (v1.29)", () => {
294
+ it("a MID-RUN warn/nit wave routes the next wave after its fix — an early `done` is the {16,22,24}/rt/C5 regression (v1.29)", async () => {
286
295
  const { ledger, cleanup } = fixture();
287
296
  try {
288
297
  // The three-wave chain: {1} → {2} → {3}. Each review finds warn/nit; every fix
@@ -304,25 +313,25 @@ describe("the task small loop — implement → review → the next ready group"
304
313
  });
305
314
 
306
315
  // wave {1}: implement → review(warn) → fix(clean) → next-wave {2}
307
- expect(run.advance()!.frame.target).toEqual({ kind: "wave", tasks: [1] });
308
- expect(run.advance()!.route!.kind).toBe("fix");
309
- expect(run.advance()!.route).toEqual({ kind: "next-wave", tasks: "2" });
316
+ expect((await run.advance())!.frame.target).toEqual({ kind: "wave", tasks: [1] });
317
+ expect((await run.advance())!.route!.kind).toBe("fix");
318
+ expect((await run.advance())!.route).toEqual({ kind: "next-wave", tasks: "2" });
310
319
  // wave {2}: implement → review(warn) → fix(clean) → next-wave {3}
311
- expect(run.advance()!.frame.target).toEqual({ kind: "wave", tasks: [2] });
312
- expect(run.advance()!.route!.kind).toBe("fix");
313
- expect(run.advance()!.route).toEqual({ kind: "next-wave", tasks: "3" });
320
+ expect((await run.advance())!.frame.target).toEqual({ kind: "wave", tasks: [2] });
321
+ expect((await run.advance())!.route!.kind).toBe("fix");
322
+ expect((await run.advance())!.route).toEqual({ kind: "next-wave", tasks: "3" });
314
323
  // wave {3} (terminal): implement → review(warn) → fix(clean) → done
315
- expect(run.advance()!.frame.target).toEqual({ kind: "wave", tasks: [3] });
316
- expect(run.advance()!.route!.kind).toBe("fix");
317
- expect(run.advance()!.route).toEqual({ kind: "done" });
318
- expect(run.advance()).toBeNull();
324
+ expect((await run.advance())!.frame.target).toEqual({ kind: "wave", tasks: [3] });
325
+ expect((await run.advance())!.route!.kind).toBe("fix");
326
+ expect((await run.advance())!.route).toEqual({ kind: "done" });
327
+ expect(await run.advance()).toBeNull();
319
328
  expect(graph.doneTasks()).toEqual(new Set([1, 2, 3]));
320
329
  } finally {
321
330
  cleanup();
322
331
  }
323
332
  });
324
333
 
325
- it("a MID-RUN wave's blocker loop closes to the NEXT wave after the blocker clears through a warn re-review — the full W1 three-type route (v1.29)", () => {
334
+ it("a MID-RUN wave's blocker loop closes to the NEXT wave after the blocker clears through a warn re-review — the full W1 three-type route (v1.29)", async () => {
326
335
  const { ledger, cleanup } = fixture();
327
336
  try {
328
337
  // The user routing matrix (v1.29), wave type W1: review → (blocker>0) → fix →
@@ -349,29 +358,29 @@ describe("the task small loop — implement → review → the next ready group"
349
358
  });
350
359
 
351
360
  // wave {1}: implement → review(blocker) → fix → re-review(warn) → fix → next-wave
352
- run.advance(); // implement 1
353
- const review1 = run.advance();
361
+ await run.advance(); // implement 1
362
+ const review1 = await run.advance();
354
363
  expect(review1!.frame.round).toBe(1);
355
364
  expect(review1!.route!.kind).toBe("fix");
356
- const fix1 = run.advance();
365
+ const fix1 = await run.advance();
357
366
  expect(fix1!.route!.kind).toBe("review"); // source blockers remain → re-review
358
- const review2 = run.advance();
367
+ const review2 = await run.advance();
359
368
  expect(review2!.frame.round).toBe(2);
360
369
  expect(review2!.route!.kind).toBe("fix"); // warn rides the fix hop
361
- const fix2 = run.advance();
370
+ const fix2 = await run.advance();
362
371
  expect(fix2!.route).toEqual({ kind: "next-wave", tasks: "2" }); // ← the W1 matrix row
363
372
  // wave {2} (terminal): implement → review(clean) → done
364
- run.advance(); // implement 2
365
- const review3 = run.advance();
373
+ await run.advance(); // implement 2
374
+ const review3 = await run.advance();
366
375
  expect(review3!.route).toEqual({ kind: "done" });
367
- expect(run.advance()).toBeNull();
376
+ expect(await run.advance()).toBeNull();
368
377
  expect(graph.doneTasks()).toEqual(new Set([1, 2]));
369
378
  } finally {
370
379
  cleanup();
371
380
  }
372
381
  });
373
382
 
374
- it("MIXED-severity reviews ride the same routing — a [blocker, warn] review re-reviews, a [warn, nit] re-review closes to the next wave (v1.29)", () => {
383
+ it("MIXED-severity reviews ride the same routing — a [blocker, warn] review re-reviews, a [warn, nit] re-review closes to the next wave (v1.29)", async () => {
375
384
  const { ledger, cleanup } = fixture();
376
385
  try {
377
386
  // The blocker/non-blocker axis, not the mix: wave {1}'s first review carries a
@@ -399,26 +408,26 @@ describe("the task small loop — implement → review → the next ready group"
399
408
  dispatch: dispatch.step,
400
409
  });
401
410
 
402
- run.advance(); // implement 1
403
- const review1 = run.advance();
411
+ await run.advance(); // implement 1
412
+ const review1 = await run.advance();
404
413
  expect(review1!.route!.kind).toBe("fix"); // any mix with a blocker → fix
405
- const fix1 = run.advance();
414
+ const fix1 = await run.advance();
406
415
  expect(fix1!.route).toEqual({ kind: "review" }); // blockers remain → re-review
407
- const review2 = run.advance();
416
+ const review2 = await run.advance();
408
417
  expect(review2!.frame.round).toBe(2);
409
418
  expect(review2!.route!.kind).toBe("fix"); // the warn+nit re-review still fixes
410
- const fix2 = run.advance();
419
+ const fix2 = await run.advance();
411
420
  expect(fix2!.route).toEqual({ kind: "next-wave", tasks: "2" }); // blocker-free mix closes
412
421
  // wave {2} (terminal): implement → review(clean) → done
413
- run.advance(); // implement 2
414
- expect(run.advance()!.route).toEqual({ kind: "done" });
415
- expect(run.advance()).toBeNull();
422
+ await run.advance(); // implement 2
423
+ expect((await run.advance())!.route).toEqual({ kind: "done" });
424
+ expect(await run.advance()).toBeNull();
416
425
  } finally {
417
426
  cleanup();
418
427
  }
419
428
  });
420
429
 
421
- it("MIXED warn+nit on a single-task line closes through the fix to done — the S2 mix (v1.29)", () => {
430
+ it("MIXED warn+nit on a single-task line closes through the fix to done — the S2 mix (v1.29)", async () => {
422
431
  const { ledger, cleanup } = fixture();
423
432
  try {
424
433
  const dispatch = stub((frame) => {
@@ -430,19 +439,19 @@ describe("the task small loop — implement → review → the next ready group"
430
439
  state: EMPTY_RUN_STATE,
431
440
  ledger,
432
441
  dispatch: dispatch.step,
433
- target: { kind: "doc", doc: DOC },
442
+ target: { kind: "spec", doc: DOC },
434
443
  });
435
- run.advance(); // review (warn + nit)
436
- const fix = run.advance();
444
+ await run.advance(); // review (warn + nit)
445
+ const fix = await run.advance();
437
446
  expect(fix!.frame.round).toBe(1);
438
447
  expect(fix!.route).toEqual({ kind: "done" });
439
- expect(run.advance()).toBeNull();
448
+ expect(await run.advance()).toBeNull();
440
449
  } finally {
441
450
  cleanup();
442
451
  }
443
452
  });
444
453
 
445
- it("the SINGLE-TASK line's blocker loop closes through a warn re-review to done — the full S1 three-type route (v1.29)", () => {
454
+ it("the SINGLE-TASK line's blocker loop closes through a warn re-review to done — the full S1 three-type route (v1.29)", async () => {
446
455
  const { ledger, cleanup } = fixture();
447
456
  try {
448
457
  // The user routing matrix (v1.29), single-task type S1 (spec/plan/branch): review
@@ -461,25 +470,25 @@ describe("the task small loop — implement → review → the next ready group"
461
470
  state: EMPTY_RUN_STATE,
462
471
  ledger,
463
472
  dispatch: dispatch.step,
464
- target: { kind: "doc", doc: DOC },
473
+ target: { kind: "spec", doc: DOC },
465
474
  });
466
475
 
467
- run.advance(); // review 1 (blocker)
468
- const fix1 = run.advance();
476
+ await run.advance(); // review 1 (blocker)
477
+ const fix1 = await run.advance();
469
478
  expect(fix1!.route!.kind).toBe("review"); // source blockers remain → re-review
470
- const review2 = run.advance();
479
+ const review2 = await run.advance();
471
480
  expect(review2!.frame.round).toBe(2);
472
481
  expect(review2!.route!.kind).toBe("fix"); // warn rides the fix hop
473
- const fix2 = run.advance();
482
+ const fix2 = await run.advance();
474
483
  expect(fix2!.frame.round).toBe(2); // sources review round 2 (the C5-1 fix number)
475
484
  expect(fix2!.route).toEqual({ kind: "done" }); // ← the S1 matrix row (exhausted)
476
- expect(run.advance()).toBeNull();
485
+ expect(await run.advance()).toBeNull();
477
486
  } finally {
478
487
  cleanup();
479
488
  }
480
489
  });
481
490
 
482
- it("a BLOCKED review round never closes the task — the C5 route is the single terminal verdict", () => {
491
+ it("a BLOCKED review round never closes the task — the C5 route is the single terminal verdict", async () => {
483
492
  const { ledger, cleanup } = fixture();
484
493
  try {
485
494
  const graph = taskGraph([task(1, "none")]);
@@ -493,8 +502,8 @@ describe("the task small loop — implement → review → the next ready group"
493
502
  dispatch: dispatch.step,
494
503
  });
495
504
 
496
- run.advance();
497
- const blocked = run.advance();
505
+ await run.advance();
506
+ const blocked = await run.advance();
498
507
  expect(blocked!.frame.phase).toBe("review");
499
508
  // BLOCKED → no next line (the CDD_BLOCKED channel owns the face) and no
500
509
  // done-marking — a failed round is not a closure, whatever its findings hold
@@ -505,7 +514,7 @@ describe("the task small loop — implement → review → the next ready group"
505
514
  }
506
515
  });
507
516
 
508
- it("a BLOCKED mid-run wave LOCKS the successor — wave {2} is unreachable while wave {1} holds an unclosed review (v1.29)", () => {
517
+ it("a BLOCKED mid-run wave LOCKS the successor — wave {2} is unreachable while wave {1} holds an unclosed review (v1.29)", async () => {
509
518
  const { ledger, cleanup } = fixture();
510
519
  try {
511
520
  // The strict-wave discipline as a lock: wave {1}'s review BLOCKs (no next, no
@@ -523,13 +532,13 @@ describe("the task small loop — implement → review → the next ready group"
523
532
  dispatch: dispatch.step,
524
533
  });
525
534
 
526
- run.advance(); // implement 1
527
- const blocked = run.advance(); // review 1 BLOCKED → no next, no closure
535
+ await run.advance(); // implement 1
536
+ const blocked = await run.advance(); // review 1 BLOCKED → no next, no closure
528
537
  expect(blocked!.frame.target).toEqual({ kind: "wave", tasks: [1] });
529
538
  expect(blocked!.route).toBeNull();
530
539
  expect(graph.doneTasks()).toEqual(new Set());
531
540
  // resume: the same wave/phase re-opens — wave {2} stays locked behind it
532
- const again = run.advance();
541
+ const again = await run.advance();
533
542
  expect(again).not.toBeNull();
534
543
  expect(again!.frame.target).toEqual({ kind: "wave", tasks: [1] });
535
544
  expect(again!.frame.phase).toBe("review");
@@ -540,7 +549,7 @@ describe("the task small loop — implement → review → the next ready group"
540
549
  }
541
550
  });
542
551
 
543
- it("REVIEW_CYCLE_CAP consecutive blocker reviews hit the soft cap — the line stops for the user, not done (v1.29)", () => {
552
+ it("REVIEW_CYCLE_CAP consecutive blocker reviews hit the soft cap — the line stops for the user, not done (v1.29)", async () => {
544
553
  const { ledger, cleanup } = fixture();
545
554
  try {
546
555
  // REVIEW_CYCLE_CAP: the fix round's consecutive-S1 run (walked from the review
@@ -561,19 +570,19 @@ describe("the task small loop — implement → review → the next ready group"
561
570
  dispatch: dispatch.step,
562
571
  });
563
572
 
564
- run.advance(); // implement 1
573
+ await run.advance(); // implement 1
565
574
  for (let cycle = 1; cycle < REVIEW_CYCLE_CAP; cycle += 1) {
566
- run.advance(); // review cycle (blocker) → fix
567
- const fix = run.advance();
575
+ await run.advance(); // review cycle (blocker) → fix
576
+ const fix = await run.advance();
568
577
  expect(fix!.route!.kind).toBe("review"); // S1 run cycle < cap → re-review
569
578
  }
570
- run.advance(); // review cap (blocker) → fix
571
- const capFix = run.advance();
579
+ await run.advance(); // review cap (blocker) → fix
580
+ const capFix = await run.advance();
572
581
  expect(capFix!.route!.kind).toBe("soft-cap"); // S1 run == cap → user adjudicates
573
582
  expect(capFix!.route).toEqual({ kind: "soft-cap", message: SOFT_CAP_SUGGESTION });
574
583
  // the line HOLDS: neither closed (not done), nor re-reviewing (the cap defers)
575
584
  expect(graph.doneTasks()).toEqual(new Set());
576
- expect(run.advance()).toBeNull();
585
+ expect(await run.advance()).toBeNull();
577
586
  } finally {
578
587
  cleanup();
579
588
  }
@@ -582,7 +591,7 @@ describe("the task small loop — implement → review → the next ready group"
582
591
 
583
592
  describe("the spec/plan small loop — review → fix → re-review → closure", () => {
584
593
  for (const type of ["spec", "plan"] as const) {
585
- it(`drives the ${type} line to the closure without a task frontier`, () => {
594
+ it(`drives the ${type} line to the closure without a task frontier`, async () => {
586
595
  const { ledger, cleanup } = fixture();
587
596
  try {
588
597
  let reviews = 0;
@@ -599,25 +608,25 @@ describe("the spec/plan small loop — review → fix → re-review → closure"
599
608
  state: EMPTY_RUN_STATE,
600
609
  ledger,
601
610
  dispatch: dispatch.step,
602
- target: { kind: "doc", doc: DOC },
611
+ target: { kind: type, doc: DOC },
603
612
  });
604
613
 
605
- const review1 = run.advance();
614
+ const review1 = await run.advance();
606
615
  expect(review1!.frame.phase).toBe("review");
607
616
  expect(review1!.frame.round).toBe(1);
608
617
  expect(review1!.route!.kind).toBe("fix");
609
618
 
610
- const fix = run.advance();
619
+ const fix = await run.advance();
611
620
  expect(fix!.frame.phase).toBe("fix");
612
621
  expect(fix!.frame.round).toBe(1);
613
622
  expect(fix!.route!.kind).toBe("review");
614
623
 
615
- const review2 = run.advance();
624
+ const review2 = await run.advance();
616
625
  expect(review2!.frame.phase).toBe("review");
617
626
  expect(review2!.frame.round).toBe(2);
618
627
  expect(review2!.route).toEqual({ kind: "done" });
619
628
 
620
- expect(run.advance()).toBeNull();
629
+ expect(await run.advance()).toBeNull();
621
630
  // the canonical doc handoff names are on record (round increments ride the family)
622
631
  expect(ledger.readHandoff("review", type, { round: 1 })).not.toBeNull();
623
632
  expect(ledger.readHandoff("fix", type, { round: 1 })).not.toBeNull();
@@ -628,7 +637,7 @@ describe("the spec/plan small loop — review → fix → re-review → closure"
628
637
  });
629
638
  }
630
639
 
631
- it("a clean first review closes the doc line with a single advance", () => {
640
+ it("a clean first review closes the doc line with a single advance", async () => {
632
641
  const { ledger, cleanup } = fixture();
633
642
  try {
634
643
  const dispatch = stub(() => ({ status: "APPROVED", findings: [] }));
@@ -637,12 +646,12 @@ describe("the spec/plan small loop — review → fix → re-review → closure"
637
646
  state: EMPTY_RUN_STATE,
638
647
  ledger,
639
648
  dispatch: dispatch.step,
640
- target: { kind: "doc", doc: DOC },
649
+ target: { kind: "spec", doc: DOC },
641
650
  });
642
- const step = run.advance();
651
+ const step = await run.advance();
643
652
  expect(step!.frame.phase).toBe("review");
644
653
  expect(step!.route).toEqual({ kind: "done" });
645
- expect(run.advance()).toBeNull();
654
+ expect(await run.advance()).toBeNull();
646
655
  } finally {
647
656
  cleanup();
648
657
  }
@@ -650,7 +659,7 @@ describe("the spec/plan small loop — review → fix → re-review → closure"
650
659
  });
651
660
 
652
661
  describe("T2 — the bookkeep fallback rides the frame's declared face", () => {
653
- it("the work fallback builds a findings-free carrier — the persisted implement handoff carries zero findings keys (the work face)", () => {
662
+ it("the work fallback builds a findings-free carrier — the persisted implement handoff carries zero findings keys (the work face)", async () => {
654
663
  const { ledger, cleanup } = fixture();
655
664
  try {
656
665
  const graph = taskGraph([task(1, "none")]);
@@ -661,7 +670,7 @@ describe("T2 — the bookkeep fallback rides the frame's declared face", () => {
661
670
  ledger,
662
671
  dispatch: dispatch.step,
663
672
  });
664
- run.advance();
673
+ await run.advance();
665
674
  const carrier = ledger.readHandoff("implement", "wave", { tasks: "1" });
666
675
  expect(carrier).not.toBeNull();
667
676
  expect(Object.keys(carrier!)).not.toContain("findings");
@@ -670,7 +679,7 @@ describe("T2 — the bookkeep fallback rides the frame's declared face", () => {
670
679
  }
671
680
  });
672
681
 
673
- it("the docs-fix fallback carries the findings face — the persisted fix handoff HAS the findings key (a work-shaped fallback would fail this)", () => {
682
+ it("the docs-fix fallback carries the findings face — the persisted fix handoff HAS the findings key (a work-shaped fallback would fail this)", async () => {
674
683
  const { ledger, cleanup } = fixture();
675
684
  try {
676
685
  const dispatch = stub((frame) =>
@@ -683,10 +692,10 @@ describe("T2 — the bookkeep fallback rides the frame's declared face", () => {
683
692
  state: EMPTY_RUN_STATE,
684
693
  ledger,
685
694
  dispatch: dispatch.step,
686
- target: { kind: "doc", doc: DOC },
695
+ target: { kind: "spec", doc: DOC },
687
696
  });
688
- expect(run.advance()!.route!.kind).toBe("fix");
689
- run.advance();
697
+ expect((await run.advance())!.route!.kind).toBe("fix");
698
+ await run.advance();
690
699
  const carrier = ledger.readHandoff("fix", "spec", { round: 1 });
691
700
  expect(carrier).not.toBeNull();
692
701
  // the fix-doc family is the findings face — the fallback carrier declares the
@@ -698,7 +707,7 @@ describe("T2 — the bookkeep fallback rides the frame's declared face", () => {
698
707
  }
699
708
  });
700
709
 
701
- it("T6 — probe A: the wave-fix fallback also rides the work face — the persisted WAVE fix handoff carries zero findings keys (the fix leg of the zero-findings write path)", () => {
710
+ it("T6 — probe A: the wave-fix fallback also rides the work face — the persisted WAVE fix handoff carries zero findings keys (the fix leg of the zero-findings write path)", async () => {
702
711
  const { ledger, cleanup } = fixture();
703
712
  try {
704
713
  const graph = taskGraph([task(1, "none")]);
@@ -713,9 +722,9 @@ describe("T2 — the bookkeep fallback rides the frame's declared face", () => {
713
722
  ledger,
714
723
  dispatch: dispatch.step,
715
724
  });
716
- run.advance(); // implement 1 — the work face
717
- run.advance(); // review 1 (blocker) → routes the fix hop
718
- run.advance(); // fix 1 — the WAVE fix face is the work face
725
+ await run.advance(); // implement 1 — the work face
726
+ await run.advance(); // review 1 (blocker) → routes the fix hop
727
+ await run.advance(); // fix 1 — the WAVE fix face is the work face
719
728
  const fixCarrier = ledger.readHandoff("fix", "wave", { tasks: "1", round: 1 });
720
729
  expect(fixCarrier).not.toBeNull();
721
730
  // the wave fix lands on the work face — the persisted fix carrier carries zero
@@ -732,7 +741,7 @@ describe("T2 — the bookkeep fallback rides the frame's declared face", () => {
732
741
  });
733
742
 
734
743
  describe("the branch small loop — branch-review → fix → closure", () => {
735
- it("drives the branch line over the live tree (the r{round} family names)", () => {
744
+ it("drives the branch line over the live tree (the r{round} family names)", async () => {
736
745
  const { ledger, cleanup } = fixture();
737
746
  try {
738
747
  let reviews = 0;
@@ -752,19 +761,19 @@ describe("the branch small loop — branch-review → fix → closure", () => {
752
761
  target: { kind: "branch" },
753
762
  });
754
763
 
755
- const review1 = run.advance();
764
+ const review1 = await run.advance();
756
765
  expect(review1!.frame.phase).toBe("branch-review");
757
766
  expect(review1!.frame.round).toBe(1);
758
767
  expect(review1!.frame.params).toEqual({ round: 1 });
759
768
  expect(review1!.route!.kind).toBe("fix");
760
769
 
761
- const fix = run.advance();
770
+ const fix = await run.advance();
762
771
  expect(fix!.frame.phase).toBe("fix");
763
772
  expect(fix!.frame.round).toBe(1);
764
773
  // the warn/nit input closes — the closure round, no re-review preview
765
774
  expect(fix!.route).toEqual({ kind: "done" });
766
775
 
767
- expect(run.advance()).toBeNull();
776
+ expect(await run.advance()).toBeNull();
768
777
  // the canonical branch family names ride the spine {round} increment (find #9 —
769
778
  // `branch-review-{round}.json` — the range token left the file name)
770
779
  expect(ledger.readHandoff("review", "branch", { round: 1 })).not.toBeNull();
@@ -774,7 +783,7 @@ describe("the branch small loop — branch-review → fix → closure", () => {
774
783
  }
775
784
  });
776
785
 
777
- it("a branch target face without its fixed target holds the line", () => {
786
+ it("a branch target face without its fixed target holds the line", async () => {
778
787
  const { ledger, cleanup } = fixture();
779
788
  try {
780
789
  const run = new Lifecycle({
@@ -783,13 +792,13 @@ describe("the branch small loop — branch-review → fix → closure", () => {
783
792
  ledger,
784
793
  dispatch: stub((_frame) => ({ status: "APPROVED", findings: [] })).step,
785
794
  });
786
- expect(run.advance()).toBeNull();
795
+ expect(await run.advance()).toBeNull();
787
796
  } finally {
788
797
  cleanup();
789
798
  }
790
799
  });
791
800
 
792
- it("round ACCUMULATES across a branch re-review loop — review-1 → fix-1 → review-2 → close (find #9 · lineKey fixed `branch`, the old range-key reset every re-review)", () => {
801
+ it("round ACCUMULATES across a branch re-review loop — review-1 → fix-1 → review-2 → close (find #9 · lineKey fixed `branch`, the old range-key reset every re-review)", async () => {
793
802
  const { ledger, cleanup } = fixture();
794
803
  try {
795
804
  // The blocker-first line: review-1 finds a blocker → fix-1 keeps it (the fix
@@ -817,23 +826,23 @@ describe("the branch small loop — branch-review → fix → closure", () => {
817
826
  });
818
827
 
819
828
  // review-1 → fix-1
820
- const review1 = run.advance();
829
+ const review1 = await run.advance();
821
830
  expect(review1!.frame.phase).toBe("branch-review");
822
831
  expect(review1!.frame.round).toBe(1);
823
832
  expect(review1!.route!.kind).toBe("fix");
824
- const fix1 = run.advance();
833
+ const fix1 = await run.advance();
825
834
  expect(fix1!.frame.phase).toBe("fix");
826
835
  expect(fix1!.frame.round).toBe(1);
827
836
 
828
837
  // the re-review advances the SAME line to round 2 — the stable `branch` key
829
838
  // accumulates (the old range-key: the new head would have opened a fresh
830
839
  // progress row and reset the round to 1)
831
- const review2 = run.advance();
840
+ const review2 = await run.advance();
832
841
  expect(review2!.frame.phase).toBe("branch-review");
833
842
  expect(review2!.frame.round).toBe(2);
834
843
  expect(review2!.route!.kind).toBe("done");
835
844
 
836
- expect(run.advance()).toBeNull();
845
+ expect(await run.advance()).toBeNull();
837
846
  // the spine file names accumulate too — branch-review-1.json AND
838
847
  // branch-review-2.json exist (find #9: the round rides the name, never the range)
839
848
  expect(ledger.readHandoff("review", "branch", { round: 1 })).not.toBeNull();
@@ -846,7 +855,7 @@ describe("the branch small loop — branch-review → fix → closure", () => {
846
855
  });
847
856
 
848
857
  describe("the capsule interaction seam — non-hard consumption", () => {
849
- it("advances output-less without a capsule; the attached seam renders the round facts", () => {
858
+ it("advances output-less without a capsule; the attached seam renders the round facts", async () => {
850
859
  const { ledger, cleanup } = fixture();
851
860
  try {
852
861
  const graph = taskGraph([task(1, "none")]);
@@ -858,14 +867,14 @@ describe("the capsule interaction seam — non-hard consumption", () => {
858
867
  dispatch: dispatch.step,
859
868
  });
860
869
 
861
- const silent = run.advance();
870
+ const silent = await run.advance();
862
871
  expect(silent!.capsuleLines).toEqual([]);
863
872
 
864
873
  const capsule: CapsuleFace = {
865
874
  emit: (status, blocker, handoff) => [`${status}: ${blocker} · ${handoff}`],
866
875
  };
867
876
  run.attachCapsule(capsule);
868
- const rendered = run.advance();
877
+ const rendered = await run.advance();
869
878
  expect(rendered!.capsuleLines.length).toBeGreaterThan(0);
870
879
  expect(rendered!.capsuleLines[0]).toContain("APPROVED");
871
880
  } finally {
@@ -884,7 +893,7 @@ describe("the capsule interaction seam — non-hard consumption", () => {
884
893
  });
885
894
 
886
895
  describe("T11/D30 — the wave review writes the reviewed BRIEF revision into the wave row", () => {
887
- it("a completed wave review binds the lifecycle's RENDERED-brief revision to the wave line (D30)", () => {
896
+ it("a completed wave review binds the lifecycle's RENDERED-brief revision to the wave line (D30)", async () => {
888
897
  const { ledger, repo, cleanup } = fixture();
889
898
  try {
890
899
  const planPath = path.join(repo, "plan.md");
@@ -902,8 +911,8 @@ describe("T11/D30 — the wave review writes the reviewed BRIEF revision into th
902
911
  dispatch: dispatch.step,
903
912
  planPath,
904
913
  });
905
- run.advance(); // implement
906
- run.advance(); // review — the completion records the wave's RENDERED brief revision
914
+ await run.advance(); // implement
915
+ await run.advance(); // review — the completion records the wave's RENDERED brief revision
907
916
  const recorded = ledger.reviewedRevisionOf("1");
908
917
  expect(recorded).not.toBeNull();
909
918
  // D30 — the wave line binds its OWN ref kind (brief-revision), never the doc
@@ -912,7 +921,10 @@ describe("T11/D30 — the wave review writes the reviewed BRIEF revision into th
912
921
  // wave's tasks leaves the brief byte-identical and must not void the wave)
913
922
  expect(recorded!.kind).toBe("brief-revision");
914
923
  if (recorded!.kind !== "brief-revision") throw new Error("unreachable");
915
- expect(recorded!.plan).toBe(planPath);
924
+ // P9 T4 — the persisted plan layer speaks the ONE canonical shape (repoRoot-
925
+ // relative), so the fixture's basis (`<repo>/.kairos/cdd`) relativizes the
926
+ // plan to `../../plan.md` (the ledger normalizes on write + comparison).
927
+ expect(recorded!.plan).toBe("../../plan.md");
916
928
  expect(recorded!.brief_hash).toBe(briefHash(planPath, "1"));
917
929
  // the doc-line narrowing reader never surfaces a brief ref (a wave line is not
918
930
  // a doc line)
@@ -922,7 +934,7 @@ describe("T11/D30 — the wave review writes the reviewed BRIEF revision into th
922
934
  }
923
935
  });
924
936
 
925
- it("a plan-less lifecycle records no wave revision — the null #planPath leaves the legacy wave row", () => {
937
+ it("a plan-less lifecycle records no wave revision — the null #planPath leaves the legacy wave row", async () => {
926
938
  const { ledger, cleanup } = fixture();
927
939
  try {
928
940
  const graph = taskGraph([task(1, "none")]);
@@ -936,15 +948,15 @@ describe("T11/D30 — the wave review writes the reviewed BRIEF revision into th
936
948
  dispatch: dispatch.step,
937
949
  // no planPath — the wave review completes with no plan fact on record
938
950
  });
939
- run.advance();
940
- run.advance();
951
+ await run.advance();
952
+ await run.advance();
941
953
  expect(ledger.reviewedRevisionOf("1")).toBeNull();
942
954
  } finally {
943
955
  cleanup();
944
956
  }
945
957
  });
946
958
 
947
- it("a wave-backfill edit reopens the wave at REVIEW on the lifecycle frontier — the gate's peer (D26 · D30)", () => {
959
+ it("a wave-backfill edit reopens the wave at REVIEW on the lifecycle frontier — the gate's peer (D26 · D30)", async () => {
948
960
  const { ledger, repo, cleanup } = fixture();
949
961
  try {
950
962
  const planPath = path.join(repo, "plan.md");
@@ -962,8 +974,8 @@ describe("T11/D30 — the wave review writes the reviewed BRIEF revision into th
962
974
  dispatch: dispatch.step,
963
975
  planPath,
964
976
  });
965
- run.advance(); // implement
966
- const review = run.advance(); // review — the blocker awaits its fix; the brief revision binds
977
+ await run.advance(); // implement
978
+ const review = await run.advance(); // review — the blocker awaits its fix; the brief revision binds
967
979
  expect(review!.frame.phase).toBe("review");
968
980
  expect(review!.route!.kind).toBe("fix");
969
981
  // the wave's OWN task section moves mid-flight (an orchestrator fill/fix) — the
@@ -973,14 +985,14 @@ describe("T11/D30 — the wave review writes the reviewed BRIEF revision into th
973
985
  // brief voids the findings bound to the old revision. Without the single-source
974
986
  // derivation the frontier held `fix` while the gate accepted `review` (the
975
987
  // deadlock). The gate-side twin lives in wave.test.ts.
976
- const reopened = run.advance();
988
+ const reopened = await run.advance();
977
989
  expect(reopened!.frame.phase).toBe("review");
978
990
  } finally {
979
991
  cleanup();
980
992
  }
981
993
  });
982
994
 
983
- it("an OUTSIDE-wave plan edit does NOT reopen the wave — the backfill's whole point (D30)", () => {
995
+ it("an OUTSIDE-wave plan edit does NOT reopen the wave — the backfill's whole point (D30)", async () => {
984
996
  const { ledger, repo, cleanup } = fixture();
985
997
  try {
986
998
  const planPath = path.join(repo, "plan.md");
@@ -998,14 +1010,14 @@ describe("T11/D30 — the wave review writes the reviewed BRIEF revision into th
998
1010
  dispatch: dispatch.step,
999
1011
  planPath,
1000
1012
  });
1001
- run.advance(); // implement wave {1}
1002
- run.advance(); // review — binds wave {1}'s brief; the blocker awaits its fix
1013
+ await run.advance(); // implement wave {1}
1014
+ await run.advance(); // review — binds wave {1}'s brief; the blocker awaits its fix
1003
1015
  // the plan gains a task OUTSIDE wave {1} (an append-only backfill) — the
1004
1016
  // Constraints + Task 1 sections are byte-identical, so wave {1}'s brief is
1005
1017
  // unchanged and the pending fix MUST survive (the whole-plan hash wrongly
1006
1018
  // reopened it; D30 binds the brief)
1007
1019
  writeFileSync(planPath, planDoc([task(1, "none"), task(2, "1"), task(3, "1,2")]));
1008
- const kept = run.advance();
1020
+ const kept = await run.advance();
1009
1021
  expect(kept!.frame.phase).toBe("fix");
1010
1022
  } finally {
1011
1023
  cleanup();