@oscaner-skills/cdd-engine 3.0.0 → 3.1.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 (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 +149 -0
  15. package/dist/face/cli.js +893 -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 +702 -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 +504 -0
  25. package/dist/face/words.js +258 -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 +453 -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,1026 +0,0 @@
1
- // packages/cdd-engine/src-next/session/__tests__/run.test.ts
2
- // T8 Lifecycle suite (design spec §3.3) — the parameterized single lifecycle:
3
- // · the faces table — one row per target type (task / branch / spec / plan) with
4
- // the audit descriptor, the review-lead mode and the batch next semantics (the
5
- // design spec §3.3 divergence parameters);
6
- // · the four-type end-to-end small loops — advance() as one dispatch step
7
- // (frontier → dispatch → bookkeeping → next routing) over a hermetic ledger,
8
- // driven to the line's closure;
9
- // · the capsule interaction seam — the CapsuleFace interface the step renders
10
- // through at the interaction point (non-hard consumption: the step advances
11
- // output-less without a capsule; T10's Capsule satisfies the same shape).
12
- // Fixtures are plan literals parsed through the plan parser + a hermetic temp
13
- // workspace — the ledger round reads hit the on-disk handoffs exactly as the
14
- // production loop does.
15
-
16
- import { createHash } from "node:crypto";
17
- import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
18
- import { tmpdir } from "node:os";
19
- import path from "node:path";
20
- import { describe, expect, it } from "vitest";
21
- import { PlanDocType } from "../../contract/doc.ts";
22
- import { ConfigLoader } from "../../infra/config.ts";
23
- import { Workspace, WorkspaceRoot } from "../../infra/workspace.ts";
24
- import { BriefRenderer } from "../../render/brief.ts";
25
- import { type TargetFace, type TargetType, targetFaces } from "../faces.ts";
26
- import { TaskGraph } from "../graph.ts";
27
- import { Ledger } from "../ledger.ts";
28
- import { REVIEW_CYCLE_CAP, SOFT_CAP_SUGGESTION } from "../next.ts";
29
- import type { CapsuleFace, DispatchOutcome, DispatchStep, OpenFrame, StepResult } from "../run.ts";
30
- import { EMPTY_RUN_STATE, Lifecycle } from "../run.ts";
31
-
32
- const DOC = "docs/kairos/specs/x-design.md";
33
-
34
- /** A hermetic ledger fixture — a fresh temp workspace (the ledger tests' pattern).
35
- * `repo` exposes the temp root so the T11 wiring cases can place a real plan file
36
- * the reviewed-revision write-back hashes. */
37
- const fixture = (): {
38
- ledger: Ledger;
39
- workspace: Workspace;
40
- repo: string;
41
- cleanup: () => void;
42
- } => {
43
- const repo = mkdtempSync(path.join(tmpdir(), "run-"));
44
- const workspace = new Workspace(
45
- new WorkspaceRoot(path.join(repo, ".kairos", "cdd"), "session"),
46
- "test-slug",
47
- );
48
- const ledger = new Ledger(workspace, new ConfigLoader());
49
- return { ledger, workspace, repo, cleanup: () => rmSync(repo, { recursive: true, force: true }) };
50
- };
51
-
52
- /** A plan document over `### Task N:` blocks + `- **DependsOn**:` values (the
53
- * front-matter head the plan parser reads). */
54
- const planDoc = (blocks: readonly (readonly string[])[]): string => {
55
- return [
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
- "---",
65
- "",
66
- "## Constraints",
67
- "",
68
- "- delta",
69
- "",
70
- ...blocks.flat(),
71
- ].join("\n");
72
- };
73
-
74
- /** One task block with its `- **DependsOn**:` edge. */
75
- const task = (id: number, dependsOn: string): readonly string[] => {
76
- return [`### Task ${id}: task ${id}`, `- **DependsOn**: ${dependsOn}`];
77
- };
78
-
79
- /** Parse a fixture and build the TaskGraph — the task face's run state. */
80
- const taskGraph = (blocks: readonly (readonly string[])[]): TaskGraph => {
81
- return new TaskGraph(new PlanDocType("plan").parse(planDoc(blocks).split("\n")));
82
- };
83
-
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. */
87
- const stub = (
88
- script: (frame: OpenFrame) => DispatchOutcome,
89
- ): {
90
- step: DispatchStep;
91
- calls: OpenFrame[];
92
- } => {
93
- const calls: OpenFrame[] = [];
94
- return {
95
- calls,
96
- step: async (frame) => {
97
- calls.push(frame);
98
- return script(frame);
99
- },
100
- };
101
- };
102
-
103
- /** The approved-implement outcome — the canonical work-round result. */
104
- const APPROVED_IMPLEMENT: DispatchOutcome = {
105
- status: "APPROVED",
106
- carrier: { artifacts: { brief: "/tmp/brief.md" } },
107
- };
108
-
109
- const finding = (severity: "blocker" | "warn" | "nit") => ({ severity, summary: "drift" });
110
-
111
- /** The D30 wave-line reviewed-basis hash — the RENDERED brief's sha1 for a wave's
112
- * tasks (the wave gate binds the brief, never the whole plan). */
113
- const briefHash = (planPath: string, tasks: string): string => {
114
- const brief = new BriefRenderer().render(
115
- readFileSync(planPath, "utf8"),
116
- tasks.split(",").map(Number),
117
- );
118
- return createHash("sha1").update(brief).digest("hex");
119
- };
120
- const phasesOf = (steps: readonly StepResult[]): readonly (string | null)[] =>
121
- steps.map((step) => step.frame.phase);
122
-
123
- describe("the faces table — one row per target type", () => {
124
- it("declares the four CLI `--type` values in the single table", () => {
125
- expect(Object.keys(targetFaces)).toEqual(["wave", "branch", "spec", "plan"]);
126
- for (const type of Object.keys(targetFaces) as TargetType[]) {
127
- expect(targetFaces[type].type).toBe(type);
128
- }
129
- });
130
-
131
- it("task — the task-graph audit, the review lead, batch continuation", () => {
132
- const face = targetFaces.wave as TargetFace;
133
- expect(face.audit).toEqual({ kind: "task-graph" });
134
- expect(face.product.reviewLead).toBe("review");
135
- expect(face.nextSemantics.batch).toBe(true);
136
- });
137
-
138
- it("branch — the branch-tree audit, the branch-review lead, no batch", () => {
139
- const face = targetFaces.branch as TargetFace;
140
- expect(face.audit).toEqual({ kind: "branch-tree" });
141
- expect(face.product.reviewLead).toBe("branch-review");
142
- expect(face.nextSemantics.batch).toBe(false);
143
- });
144
-
145
- it("spec/plan — the doc-path audit, the review lead, no batch", () => {
146
- for (const type of ["spec", "plan"] as const) {
147
- const face = targetFaces[type];
148
- expect(face.audit).toEqual({ kind: "doc-path" });
149
- expect(face.product.reviewLead).toBe("review");
150
- expect(face.nextSemantics.batch).toBe(false);
151
- }
152
- });
153
- });
154
-
155
- describe("the task small loop — implement → review → the next ready group", () => {
156
- it("runs one dispatch per advance across the frontier to the exhausted null", async () => {
157
- const { ledger, cleanup } = fixture();
158
- try {
159
- const graph = taskGraph([task(1, "none"), task(2, "1")]);
160
- const dispatch = stub((frame) =>
161
- frame.phase === "implement" ? APPROVED_IMPLEMENT : { status: "APPROVED", findings: [] },
162
- );
163
- const run = new Lifecycle({
164
- face: targetFaces.wave,
165
- state: graph,
166
- ledger,
167
- dispatch: dispatch.step,
168
- });
169
-
170
- const step1 = await run.advance();
171
- expect(step1).not.toBeNull();
172
- expect(step1!.frame.phase).toBe("implement");
173
- expect(step1!.frame.target).toEqual({ kind: "wave", tasks: [1] });
174
- expect(step1!.frame.params).toEqual({ tasks: "1" });
175
- expect(step1!.round).toBe(1);
176
- expect(step1!.route).toEqual({ kind: "review" });
177
-
178
- const step2 = await run.advance();
179
- expect(step2!.frame.phase).toBe("review");
180
- expect(step2!.frame.round).toBe(1);
181
- expect(step2!.route).toEqual({ kind: "next-wave", tasks: "2" });
182
-
183
- const step3 = await run.advance();
184
- expect(step3!.frame.phase).toBe("implement");
185
- expect(step3!.frame.target).toEqual({ kind: "wave", tasks: [2] });
186
-
187
- const step4 = await run.advance();
188
- expect(step4!.frame.phase).toBe("review");
189
- expect(step4!.frame.round).toBe(1);
190
- expect(step4!.route).toEqual({ kind: "done" });
191
-
192
- expect(await run.advance()).toBeNull();
193
-
194
- expect(dispatch.calls.map((f) => f.phase)).toEqual([
195
- "implement",
196
- "review",
197
- "implement",
198
- "review",
199
- ]);
200
- expect(dispatch.calls.map((f) => f.target)).toEqual([
201
- { kind: "wave", tasks: [1] },
202
- { kind: "wave", tasks: [1] },
203
- { kind: "wave", tasks: [2] },
204
- { kind: "wave", tasks: [2] },
205
- ]);
206
- // the progress record + the done-set carry the loop forward
207
- expect(graph.doneTasks()).toEqual(new Set([1, 2]));
208
- expect(run.face()).toBe(targetFaces.wave);
209
- } finally {
210
- cleanup();
211
- }
212
- });
213
-
214
- it("a review with blockers routes the fix, the re-review and the closure", async () => {
215
- const { ledger, cleanup } = fixture();
216
- try {
217
- const graph = taskGraph([task(1, "none")]);
218
- let reviews = 0;
219
- const dispatch = stub((frame) => {
220
- if (frame.phase === "implement") return APPROVED_IMPLEMENT;
221
- if (frame.phase === "fix") return { status: "APPROVED" };
222
- reviews += 1;
223
- return {
224
- status: "APPROVED",
225
- findings: reviews === 1 ? [finding("blocker")] : [],
226
- };
227
- });
228
- const run = new Lifecycle({
229
- face: targetFaces.wave,
230
- state: graph,
231
- ledger,
232
- dispatch: dispatch.step,
233
- });
234
-
235
- const implement = await run.advance();
236
- expect(implement!.route).toEqual({ kind: "review" });
237
-
238
- const review1 = await run.advance();
239
- expect(review1!.frame.phase).toBe("review");
240
- expect(review1!.frame.round).toBe(1);
241
- expect(review1!.route!.kind).toBe("fix");
242
- // the closed review leaves the task not done — the re-review awaits
243
- expect(graph.doneTasks()).toEqual(new Set());
244
-
245
- const fix = await run.advance();
246
- expect(fix!.frame.phase).toBe("fix");
247
- expect(fix!.frame.round).toBe(1);
248
- // the C5-1 re-review: the fix round carries the source review's blocker and
249
- // routes the fix's delta span (base + head — the branch literal's full range)
250
- expect(fix!.route).toEqual({ kind: "review" });
251
- expect(graph.doneTasks()).toEqual(new Set());
252
-
253
- const review2 = await run.advance();
254
- expect(review2!.frame.phase).toBe("review");
255
- expect(review2!.frame.round).toBe(2);
256
- expect(review2!.route).toEqual({ kind: "done" });
257
- expect(graph.doneTasks()).toEqual(new Set([1]));
258
-
259
- expect(await run.advance()).toBeNull();
260
- expect(phasesOf([review1!, fix!, review2!])).toEqual(["review", "fix", "review"]);
261
- } finally {
262
- cleanup();
263
- }
264
- });
265
-
266
- it("a warn/nit review closes through the fix — the REVIEW_FIX closure, no re-review", async () => {
267
- const { ledger, cleanup } = fixture();
268
- try {
269
- const graph = taskGraph([task(1, "none")]);
270
- const dispatch = stub((frame) => {
271
- if (frame.phase === "implement") return APPROVED_IMPLEMENT;
272
- if (frame.phase === "fix") return { status: "APPROVED" };
273
- return { status: "APPROVED", findings: [finding("nit")] };
274
- });
275
- const run = new Lifecycle({
276
- face: targetFaces.wave,
277
- state: graph,
278
- ledger,
279
- dispatch: dispatch.step,
280
- });
281
-
282
- await run.advance();
283
- await run.advance(); // the nit review
284
- const fix = await run.advance();
285
- expect(fix!.frame.phase).toBe("fix");
286
- expect(fix!.route).toEqual({ kind: "done" });
287
- expect(graph.doneTasks()).toEqual(new Set([1]));
288
- expect(await run.advance()).toBeNull();
289
- } finally {
290
- cleanup();
291
- }
292
- });
293
-
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 () => {
295
- const { ledger, cleanup } = fixture();
296
- try {
297
- // The three-wave chain: {1} → {2} → {3}. Each review finds warn/nit; every fix
298
- // clears them (blocker=0 → close). The closure routing must render next-wave
299
- // for wave {1} and {2} (the run continues) and `done` ONLY for the terminal
300
- // wave {3} — the close() ready-batch the router judges must be the LEADGER's
301
- // cross-invocation closed set, not the per-invocation cursor.
302
- const graph = taskGraph([task(1, "none"), task(2, "1"), task(3, "2")]);
303
- const dispatch = stub((frame) => {
304
- if (frame.phase === "implement") return APPROVED_IMPLEMENT;
305
- if (frame.phase === "fix") return { status: "APPROVED" };
306
- return { status: "APPROVED", findings: [finding("warn")] };
307
- });
308
- const run = new Lifecycle({
309
- face: targetFaces.wave,
310
- state: graph,
311
- ledger,
312
- dispatch: dispatch.step,
313
- });
314
-
315
- // wave {1}: implement → review(warn) → fix(clean) → next-wave {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" });
319
- // wave {2}: implement → review(warn) → fix(clean) → next-wave {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" });
323
- // wave {3} (terminal): implement → review(warn) → fix(clean) → done
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();
328
- expect(graph.doneTasks()).toEqual(new Set([1, 2, 3]));
329
- } finally {
330
- cleanup();
331
- }
332
- });
333
-
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 () => {
335
- const { ledger, cleanup } = fixture();
336
- try {
337
- // The user routing matrix (v1.29), wave type W1: review → (blocker>0) → fix →
338
- // re-review → … → re-review → (blocker=0 & warn+nit>0) → fix → NEXT-WAVE. The
339
- // blocker loop lives INSIDE wave {1}; once the fix round's source blockers clear
340
- // (the re-review carries only warn), the closure routes wave {2} — never done.
341
- const graph = taskGraph([task(1, "none"), task(2, "1")]);
342
- const dispatch = stub((frame) => {
343
- if (frame.phase === "implement") return APPROVED_IMPLEMENT;
344
- if (frame.phase === "fix") return { status: "APPROVED" };
345
- const wave = frame.target.kind === "wave" ? frame.target.tasks.join(",") : "";
346
- if (wave === "1")
347
- return {
348
- status: "APPROVED",
349
- findings: frame.round === 1 ? [finding("blocker")] : [finding("warn")],
350
- };
351
- return { status: "APPROVED", findings: [] }; // wave {2} clean → the terminal done
352
- });
353
- const run = new Lifecycle({
354
- face: targetFaces.wave,
355
- state: graph,
356
- ledger,
357
- dispatch: dispatch.step,
358
- });
359
-
360
- // wave {1}: implement → review(blocker) → fix → re-review(warn) → fix → next-wave
361
- await run.advance(); // implement 1
362
- const review1 = await run.advance();
363
- expect(review1!.frame.round).toBe(1);
364
- expect(review1!.route!.kind).toBe("fix");
365
- const fix1 = await run.advance();
366
- expect(fix1!.route!.kind).toBe("review"); // source blockers remain → re-review
367
- const review2 = await run.advance();
368
- expect(review2!.frame.round).toBe(2);
369
- expect(review2!.route!.kind).toBe("fix"); // warn rides the fix hop
370
- const fix2 = await run.advance();
371
- expect(fix2!.route).toEqual({ kind: "next-wave", tasks: "2" }); // ← the W1 matrix row
372
- // wave {2} (terminal): implement → review(clean) → done
373
- await run.advance(); // implement 2
374
- const review3 = await run.advance();
375
- expect(review3!.route).toEqual({ kind: "done" });
376
- expect(await run.advance()).toBeNull();
377
- expect(graph.doneTasks()).toEqual(new Set([1, 2]));
378
- } finally {
379
- cleanup();
380
- }
381
- });
382
-
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 () => {
384
- const { ledger, cleanup } = fixture();
385
- try {
386
- // The blocker/non-blocker axis, not the mix: wave {1}'s first review carries a
387
- // blocker AND a warn → the fix routes the re-review; wave {1}'s re-review is
388
- // warn+nit only (blocker-free) → its fix closes to wave {2} (next-wave, never
389
- // done). The severity MIX never alters the table.
390
- const graph = taskGraph([task(1, "none"), task(2, "1")]);
391
- const dispatch = stub((frame) => {
392
- if (frame.phase === "implement") return APPROVED_IMPLEMENT;
393
- if (frame.phase === "fix") return { status: "APPROVED" };
394
- const wave = frame.target.kind === "wave" ? frame.target.tasks.join(",") : "";
395
- if (wave !== "1") return { status: "APPROVED", findings: [] };
396
- return {
397
- status: "APPROVED",
398
- findings:
399
- frame.round === 1
400
- ? [finding("blocker"), finding("warn")]
401
- : [finding("warn"), finding("nit")],
402
- };
403
- });
404
- const run = new Lifecycle({
405
- face: targetFaces.wave,
406
- state: graph,
407
- ledger,
408
- dispatch: dispatch.step,
409
- });
410
-
411
- await run.advance(); // implement 1
412
- const review1 = await run.advance();
413
- expect(review1!.route!.kind).toBe("fix"); // any mix with a blocker → fix
414
- const fix1 = await run.advance();
415
- expect(fix1!.route).toEqual({ kind: "review" }); // blockers remain → re-review
416
- const review2 = await run.advance();
417
- expect(review2!.frame.round).toBe(2);
418
- expect(review2!.route!.kind).toBe("fix"); // the warn+nit re-review still fixes
419
- const fix2 = await run.advance();
420
- expect(fix2!.route).toEqual({ kind: "next-wave", tasks: "2" }); // blocker-free mix closes
421
- // wave {2} (terminal): implement → review(clean) → done
422
- await run.advance(); // implement 2
423
- expect((await run.advance())!.route).toEqual({ kind: "done" });
424
- expect(await run.advance()).toBeNull();
425
- } finally {
426
- cleanup();
427
- }
428
- });
429
-
430
- it("MIXED warn+nit on a single-task line closes through the fix to done — the S2 mix (v1.29)", async () => {
431
- const { ledger, cleanup } = fixture();
432
- try {
433
- const dispatch = stub((frame) => {
434
- if (frame.phase === "fix") return { status: "APPROVED" };
435
- return { status: "APPROVED", findings: [finding("warn"), finding("nit")] };
436
- });
437
- const run = new Lifecycle({
438
- face: targetFaces.spec,
439
- state: EMPTY_RUN_STATE,
440
- ledger,
441
- dispatch: dispatch.step,
442
- target: { kind: "spec", doc: DOC },
443
- });
444
- await run.advance(); // review (warn + nit)
445
- const fix = await run.advance();
446
- expect(fix!.frame.round).toBe(1);
447
- expect(fix!.route).toEqual({ kind: "done" });
448
- expect(await run.advance()).toBeNull();
449
- } finally {
450
- cleanup();
451
- }
452
- });
453
-
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 () => {
455
- const { ledger, cleanup } = fixture();
456
- try {
457
- // The user routing matrix (v1.29), single-task type S1 (spec/plan/branch): review
458
- // → (blocker>0) → fix → re-review → … → re-review → (blocker=0 & warn+nit>0) →
459
- // fix → DONE — the blocker loop terminates with a final warn fix on an exhausted
460
- // run (the single-target face: batch semantics off → close renders done).
461
- const dispatch = stub((frame) => {
462
- if (frame.phase === "fix") return { status: "APPROVED" };
463
- return {
464
- status: "APPROVED",
465
- findings: frame.round === 1 ? [finding("blocker")] : [finding("warn")],
466
- };
467
- });
468
- const run = new Lifecycle({
469
- face: targetFaces.spec,
470
- state: EMPTY_RUN_STATE,
471
- ledger,
472
- dispatch: dispatch.step,
473
- target: { kind: "spec", doc: DOC },
474
- });
475
-
476
- await run.advance(); // review 1 (blocker)
477
- const fix1 = await run.advance();
478
- expect(fix1!.route!.kind).toBe("review"); // source blockers remain → re-review
479
- const review2 = await run.advance();
480
- expect(review2!.frame.round).toBe(2);
481
- expect(review2!.route!.kind).toBe("fix"); // warn rides the fix hop
482
- const fix2 = await run.advance();
483
- expect(fix2!.frame.round).toBe(2); // sources review round 2 (the C5-1 fix number)
484
- expect(fix2!.route).toEqual({ kind: "done" }); // ← the S1 matrix row (exhausted)
485
- expect(await run.advance()).toBeNull();
486
- } finally {
487
- cleanup();
488
- }
489
- });
490
-
491
- it("a BLOCKED review round never closes the task — the C5 route is the single terminal verdict", async () => {
492
- const { ledger, cleanup } = fixture();
493
- try {
494
- const graph = taskGraph([task(1, "none")]);
495
- const dispatch = stub((frame) =>
496
- frame.phase === "implement" ? APPROVED_IMPLEMENT : { status: "BLOCKED" },
497
- );
498
- const run = new Lifecycle({
499
- face: targetFaces.wave,
500
- state: graph,
501
- ledger,
502
- dispatch: dispatch.step,
503
- });
504
-
505
- await run.advance();
506
- const blocked = await run.advance();
507
- expect(blocked!.frame.phase).toBe("review");
508
- // BLOCKED → no next line (the CDD_BLOCKED channel owns the face) and no
509
- // done-marking — a failed round is not a closure, whatever its findings hold
510
- expect(blocked!.route).toBeNull();
511
- expect(graph.doneTasks()).toEqual(new Set());
512
- } finally {
513
- cleanup();
514
- }
515
- });
516
-
517
- it("a BLOCKED mid-run wave LOCKS the successor — wave {2} is unreachable while wave {1} holds an unclosed review (v1.29)", async () => {
518
- const { ledger, cleanup } = fixture();
519
- try {
520
- // The strict-wave discipline as a lock: wave {1}'s review BLOCKs (no next, no
521
- // done-marking) → the frontier still opens wave {1} at review, so the resume
522
- // re-runs the SAME review. Wave {2} (dep 1) never front-of-line — a locked wave
523
- // in front denies the successor, exactly the "must close in order" guarantee.
524
- const graph = taskGraph([task(1, "none"), task(2, "1")]);
525
- const dispatch = stub((frame) =>
526
- frame.phase === "implement" ? APPROVED_IMPLEMENT : { status: "BLOCKED" },
527
- );
528
- const run = new Lifecycle({
529
- face: targetFaces.wave,
530
- state: graph,
531
- ledger,
532
- dispatch: dispatch.step,
533
- });
534
-
535
- await run.advance(); // implement 1
536
- const blocked = await run.advance(); // review 1 BLOCKED → no next, no closure
537
- expect(blocked!.frame.target).toEqual({ kind: "wave", tasks: [1] });
538
- expect(blocked!.route).toBeNull();
539
- expect(graph.doneTasks()).toEqual(new Set());
540
- // resume: the same wave/phase re-opens — wave {2} stays locked behind it
541
- const again = await run.advance();
542
- expect(again).not.toBeNull();
543
- expect(again!.frame.target).toEqual({ kind: "wave", tasks: [1] });
544
- expect(again!.frame.phase).toBe("review");
545
- expect(again!.route).toBeNull();
546
- expect(graph.doneTasks()).toEqual(new Set());
547
- } finally {
548
- cleanup();
549
- }
550
- });
551
-
552
- it("REVIEW_CYCLE_CAP consecutive blocker reviews hit the soft cap — the line stops for the user, not done (v1.29)", async () => {
553
- const { ledger, cleanup } = fixture();
554
- try {
555
- // REVIEW_CYCLE_CAP: the fix round's consecutive-S1 run (walked from the review
556
- // history) reaches the cap → the router defers to the user (soft-cap). The line is
557
- // neither closed (done/next-wave) nor failed — it HOLDS for adjudication: the
558
- // next frame opens nothing (the route is not "review"), the wave is not done.
559
- // The walk is cap-driven so a cap change needs no test edit.
560
- const graph = taskGraph([task(1, "none")]);
561
- const dispatch = stub((frame) => {
562
- if (frame.phase === "implement") return APPROVED_IMPLEMENT;
563
- if (frame.phase === "fix") return { status: "APPROVED" };
564
- return { status: "APPROVED", findings: [finding("blocker")] };
565
- });
566
- const run = new Lifecycle({
567
- face: targetFaces.wave,
568
- state: graph,
569
- ledger,
570
- dispatch: dispatch.step,
571
- });
572
-
573
- await run.advance(); // implement 1
574
- for (let cycle = 1; cycle < REVIEW_CYCLE_CAP; cycle += 1) {
575
- await run.advance(); // review cycle (blocker) → fix
576
- const fix = await run.advance();
577
- expect(fix!.route!.kind).toBe("review"); // S1 run cycle < cap → re-review
578
- }
579
- await run.advance(); // review cap (blocker) → fix
580
- const capFix = await run.advance();
581
- expect(capFix!.route!.kind).toBe("soft-cap"); // S1 run == cap → user adjudicates
582
- expect(capFix!.route).toEqual({ kind: "soft-cap", message: SOFT_CAP_SUGGESTION });
583
- // the line HOLDS: neither closed (not done), nor re-reviewing (the cap defers)
584
- expect(graph.doneTasks()).toEqual(new Set());
585
- expect(await run.advance()).toBeNull();
586
- } finally {
587
- cleanup();
588
- }
589
- });
590
- });
591
-
592
- describe("the spec/plan small loop — review → fix → re-review → closure", () => {
593
- for (const type of ["spec", "plan"] as const) {
594
- it(`drives the ${type} line to the closure without a task frontier`, async () => {
595
- const { ledger, cleanup } = fixture();
596
- try {
597
- let reviews = 0;
598
- const dispatch = stub((frame) => {
599
- if (frame.phase === "fix") return { status: "APPROVED" };
600
- reviews += 1;
601
- return {
602
- status: "APPROVED",
603
- findings: reviews === 1 ? [finding("blocker")] : [],
604
- };
605
- });
606
- const run = new Lifecycle({
607
- face: targetFaces[type],
608
- state: EMPTY_RUN_STATE,
609
- ledger,
610
- dispatch: dispatch.step,
611
- target: { kind: type, doc: DOC },
612
- });
613
-
614
- const review1 = await run.advance();
615
- expect(review1!.frame.phase).toBe("review");
616
- expect(review1!.frame.round).toBe(1);
617
- expect(review1!.route!.kind).toBe("fix");
618
-
619
- const fix = await run.advance();
620
- expect(fix!.frame.phase).toBe("fix");
621
- expect(fix!.frame.round).toBe(1);
622
- expect(fix!.route!.kind).toBe("review");
623
-
624
- const review2 = await run.advance();
625
- expect(review2!.frame.phase).toBe("review");
626
- expect(review2!.frame.round).toBe(2);
627
- expect(review2!.route).toEqual({ kind: "done" });
628
-
629
- expect(await run.advance()).toBeNull();
630
- // the canonical doc handoff names are on record (round increments ride the family)
631
- expect(ledger.readHandoff("review", type, { round: 1 })).not.toBeNull();
632
- expect(ledger.readHandoff("fix", type, { round: 1 })).not.toBeNull();
633
- expect(ledger.readHandoff("review", type, { round: 2 })).not.toBeNull();
634
- } finally {
635
- cleanup();
636
- }
637
- });
638
- }
639
-
640
- it("a clean first review closes the doc line with a single advance", async () => {
641
- const { ledger, cleanup } = fixture();
642
- try {
643
- const dispatch = stub(() => ({ status: "APPROVED", findings: [] }));
644
- const run = new Lifecycle({
645
- face: targetFaces.spec,
646
- state: EMPTY_RUN_STATE,
647
- ledger,
648
- dispatch: dispatch.step,
649
- target: { kind: "spec", doc: DOC },
650
- });
651
- const step = await run.advance();
652
- expect(step!.frame.phase).toBe("review");
653
- expect(step!.route).toEqual({ kind: "done" });
654
- expect(await run.advance()).toBeNull();
655
- } finally {
656
- cleanup();
657
- }
658
- });
659
- });
660
-
661
- describe("T2 — the bookkeep fallback rides the frame's declared face", () => {
662
- it("the work fallback builds a findings-free carrier — the persisted implement handoff carries zero findings keys (the work face)", async () => {
663
- const { ledger, cleanup } = fixture();
664
- try {
665
- const graph = taskGraph([task(1, "none")]);
666
- const dispatch = stub(() => APPROVED_IMPLEMENT);
667
- const run = new Lifecycle({
668
- face: targetFaces.wave,
669
- state: graph,
670
- ledger,
671
- dispatch: dispatch.step,
672
- });
673
- await run.advance();
674
- const carrier = ledger.readHandoff("implement", "wave", { tasks: "1" });
675
- expect(carrier).not.toBeNull();
676
- expect(Object.keys(carrier!)).not.toContain("findings");
677
- } finally {
678
- cleanup();
679
- }
680
- });
681
-
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 () => {
683
- const { ledger, cleanup } = fixture();
684
- try {
685
- const dispatch = stub((frame) =>
686
- frame.phase === "fix"
687
- ? { status: "APPROVED" }
688
- : { status: "APPROVED", findings: [finding("blocker")] },
689
- );
690
- const run = new Lifecycle({
691
- face: targetFaces.spec,
692
- state: EMPTY_RUN_STATE,
693
- ledger,
694
- dispatch: dispatch.step,
695
- target: { kind: "spec", doc: DOC },
696
- });
697
- expect((await run.advance())!.route!.kind).toBe("fix");
698
- await run.advance();
699
- const carrier = ledger.readHandoff("fix", "spec", { round: 1 });
700
- expect(carrier).not.toBeNull();
701
- // the fix-doc family is the findings face — the fallback carrier declares the
702
- // findings key (empty: the fix outcome advances no new findings of its own)
703
- expect(Object.keys(carrier!)).toContain("findings");
704
- expect(carrier!.findings).toEqual([]);
705
- } finally {
706
- cleanup();
707
- }
708
- });
709
-
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 () => {
711
- const { ledger, cleanup } = fixture();
712
- try {
713
- const graph = taskGraph([task(1, "none")]);
714
- const dispatch = stub((frame) => {
715
- if (frame.phase === "implement") return APPROVED_IMPLEMENT;
716
- if (frame.phase === "fix") return { status: "APPROVED" };
717
- return { status: "APPROVED", findings: [finding("blocker")] };
718
- });
719
- const run = new Lifecycle({
720
- face: targetFaces.wave,
721
- state: graph,
722
- ledger,
723
- dispatch: dispatch.step,
724
- });
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
728
- const fixCarrier = ledger.readHandoff("fix", "wave", { tasks: "1", round: 1 });
729
- expect(fixCarrier).not.toBeNull();
730
- // the wave fix lands on the work face — the persisted fix carrier carries zero
731
- // findings keys, even though its source review was a finding-bearing blocker
732
- expect(Object.keys(fixCarrier!)).not.toContain("findings");
733
- const reviewCarrier = ledger.readHandoff("review", "wave", { tasks: "1", round: 1 });
734
- expect(reviewCarrier).not.toBeNull();
735
- // the review face keeps the findings key — the two legs diverge by face
736
- expect(Object.keys(reviewCarrier!)).toContain("findings");
737
- } finally {
738
- cleanup();
739
- }
740
- });
741
- });
742
-
743
- describe("the branch small loop — branch-review → fix → closure", () => {
744
- it("drives the branch line over the live tree (the r{round} family names)", async () => {
745
- const { ledger, cleanup } = fixture();
746
- try {
747
- let reviews = 0;
748
- const dispatch = stub((frame) => {
749
- if (frame.phase === "fix") return { status: "APPROVED" };
750
- reviews += 1;
751
- return {
752
- status: "APPROVED",
753
- findings: reviews === 1 ? [finding("warn")] : [],
754
- };
755
- });
756
- const run = new Lifecycle({
757
- face: targetFaces.branch,
758
- state: EMPTY_RUN_STATE,
759
- ledger,
760
- dispatch: dispatch.step,
761
- target: { kind: "branch" },
762
- });
763
-
764
- const review1 = await run.advance();
765
- expect(review1!.frame.phase).toBe("branch-review");
766
- expect(review1!.frame.round).toBe(1);
767
- expect(review1!.frame.params).toEqual({ round: 1 });
768
- expect(review1!.route!.kind).toBe("fix");
769
-
770
- const fix = await run.advance();
771
- expect(fix!.frame.phase).toBe("fix");
772
- expect(fix!.frame.round).toBe(1);
773
- // the warn/nit input closes — the closure round, no re-review preview
774
- expect(fix!.route).toEqual({ kind: "done" });
775
-
776
- expect(await run.advance()).toBeNull();
777
- // the canonical branch family names ride the spine {round} increment (find #9 —
778
- // `branch-review-{round}.json` — the range token left the file name)
779
- expect(ledger.readHandoff("review", "branch", { round: 1 })).not.toBeNull();
780
- expect(ledger.readHandoff("fix", "branch", { round: 1 })).not.toBeNull();
781
- } finally {
782
- cleanup();
783
- }
784
- });
785
-
786
- it("a branch target face without its fixed target holds the line", async () => {
787
- const { ledger, cleanup } = fixture();
788
- try {
789
- const run = new Lifecycle({
790
- face: targetFaces.branch,
791
- state: EMPTY_RUN_STATE,
792
- ledger,
793
- dispatch: stub((_frame) => ({ status: "APPROVED", findings: [] })).step,
794
- });
795
- expect(await run.advance()).toBeNull();
796
- } finally {
797
- cleanup();
798
- }
799
- });
800
-
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 () => {
802
- const { ledger, cleanup } = fixture();
803
- try {
804
- // The blocker-first line: review-1 finds a blocker → fix-1 keeps it (the fix
805
- // carrier's source review still blocks) → the re-review of the fix's delta is
806
- // review-2 → it finds nothing → the line closes.
807
- const findingsByRound: string[][] = [["blocker"], []];
808
- const dispatch = stub((frame) => {
809
- if (frame.phase === "review" || frame.phase === "branch-review") {
810
- const findings = (findingsByRound[frame.round - 1] ?? ["blocker"]).map((severity) =>
811
- finding(severity as "blocker"),
812
- );
813
- return { status: "REVIEW_FIX", findings };
814
- }
815
- if (frame.phase === "fix") {
816
- return { status: "APPROVED" };
817
- }
818
- return { status: "APPROVED" };
819
- });
820
- const run = new Lifecycle({
821
- face: targetFaces.branch,
822
- state: EMPTY_RUN_STATE,
823
- ledger,
824
- dispatch: dispatch.step,
825
- target: { kind: "branch" },
826
- });
827
-
828
- // review-1 → fix-1
829
- const review1 = await run.advance();
830
- expect(review1!.frame.phase).toBe("branch-review");
831
- expect(review1!.frame.round).toBe(1);
832
- expect(review1!.route!.kind).toBe("fix");
833
- const fix1 = await run.advance();
834
- expect(fix1!.frame.phase).toBe("fix");
835
- expect(fix1!.frame.round).toBe(1);
836
-
837
- // the re-review advances the SAME line to round 2 — the stable `branch` key
838
- // accumulates (the old range-key: the new head would have opened a fresh
839
- // progress row and reset the round to 1)
840
- const review2 = await run.advance();
841
- expect(review2!.frame.phase).toBe("branch-review");
842
- expect(review2!.frame.round).toBe(2);
843
- expect(review2!.route!.kind).toBe("done");
844
-
845
- expect(await run.advance()).toBeNull();
846
- // the spine file names accumulate too — branch-review-1.json AND
847
- // branch-review-2.json exist (find #9: the round rides the name, never the range)
848
- expect(ledger.readHandoff("review", "branch", { round: 1 })).not.toBeNull();
849
- expect(ledger.readHandoff("review", "branch", { round: 2 })).not.toBeNull();
850
- expect(ledger.readHandoff("fix", "branch", { round: 1 })).not.toBeNull();
851
- } finally {
852
- cleanup();
853
- }
854
- });
855
- });
856
-
857
- describe("the capsule interaction seam — non-hard consumption", () => {
858
- it("advances output-less without a capsule; the attached seam renders the round facts", async () => {
859
- const { ledger, cleanup } = fixture();
860
- try {
861
- const graph = taskGraph([task(1, "none")]);
862
- const dispatch = stub(() => APPROVED_IMPLEMENT);
863
- const run = new Lifecycle({
864
- face: targetFaces.wave,
865
- state: graph,
866
- ledger,
867
- dispatch: dispatch.step,
868
- });
869
-
870
- const silent = await run.advance();
871
- expect(silent!.capsuleLines).toEqual([]);
872
-
873
- const capsule: CapsuleFace = {
874
- emit: (status, blocker, handoff) => [`${status}: ${blocker} · ${handoff}`],
875
- };
876
- run.attachCapsule(capsule);
877
- const rendered = await run.advance();
878
- expect(rendered!.capsuleLines.length).toBeGreaterThan(0);
879
- expect(rendered!.capsuleLines[0]).toContain("APPROVED");
880
- } finally {
881
- cleanup();
882
- }
883
- });
884
-
885
- it("the interaction seam accepts a plain route-less emit — the interface shape is pinned", () => {
886
- // Compile-time pins — this file fails under `tsc --noEmit` if the seam surface
887
- // drifts from the face/capsule contact (T10's Capsule satisfies the same type).
888
- const seam: CapsuleFace["emit"] = (status, blocker, handoff) => [
889
- `${status} ${blocker} ${handoff}`,
890
- ];
891
- expect(seam("APPROVED", "0", "/ws/h.json")).toEqual(["APPROVED 0 /ws/h.json"]);
892
- });
893
- });
894
-
895
- describe("T11/D30 — the wave review writes the reviewed BRIEF revision into the wave row", () => {
896
- it("a completed wave review binds the lifecycle's RENDERED-brief revision to the wave line (D30)", async () => {
897
- const { ledger, repo, cleanup } = fixture();
898
- try {
899
- const planPath = path.join(repo, "plan.md");
900
- writeFileSync(planPath, planDoc([task(1, "none")]));
901
- const graph = taskGraph([task(1, "none")]);
902
- // the review approves on its first pass — the wave closes, but the revision
903
- // write-back lands in the bookkeep step BEFORE the closure route marks done
904
- const dispatch = stub((frame) =>
905
- frame.phase === "implement" ? APPROVED_IMPLEMENT : { status: "APPROVED", findings: [] },
906
- );
907
- const run = new Lifecycle({
908
- face: targetFaces.wave,
909
- state: graph,
910
- ledger,
911
- dispatch: dispatch.step,
912
- planPath,
913
- });
914
- await run.advance(); // implement
915
- await run.advance(); // review — the completion records the wave's RENDERED brief revision
916
- const recorded = ledger.reviewedRevisionOf("1");
917
- expect(recorded).not.toBeNull();
918
- // D30 — the wave line binds its OWN ref kind (brief-revision), never the doc
919
- // line's doc-revision: `plan` is the render-from pointer, `brief_hash` the
920
- // RENDERED brief's digest (NOT the whole plan's — a plan edit outside this
921
- // wave's tasks leaves the brief byte-identical and must not void the wave)
922
- expect(recorded!.kind).toBe("brief-revision");
923
- if (recorded!.kind !== "brief-revision") throw new Error("unreachable");
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");
928
- expect(recorded!.brief_hash).toBe(briefHash(planPath, "1"));
929
- // the doc-line narrowing reader never surfaces a brief ref (a wave line is not
930
- // a doc line)
931
- expect(ledger.reviewedDocRevisionOf("1")).toBeNull();
932
- } finally {
933
- cleanup();
934
- }
935
- });
936
-
937
- it("a plan-less lifecycle records no wave revision — the null #planPath leaves the legacy wave row", async () => {
938
- const { ledger, cleanup } = fixture();
939
- try {
940
- const graph = taskGraph([task(1, "none")]);
941
- const dispatch = stub((frame) =>
942
- frame.phase === "implement" ? APPROVED_IMPLEMENT : { status: "APPROVED", findings: [] },
943
- );
944
- const run = new Lifecycle({
945
- face: targetFaces.wave,
946
- state: graph,
947
- ledger,
948
- dispatch: dispatch.step,
949
- // no planPath — the wave review completes with no plan fact on record
950
- });
951
- await run.advance();
952
- await run.advance();
953
- expect(ledger.reviewedRevisionOf("1")).toBeNull();
954
- } finally {
955
- cleanup();
956
- }
957
- });
958
-
959
- it("a wave-backfill edit reopens the wave at REVIEW on the lifecycle frontier — the gate's peer (D26 · D30)", async () => {
960
- const { ledger, repo, cleanup } = fixture();
961
- try {
962
- const planPath = path.join(repo, "plan.md");
963
- writeFileSync(planPath, planDoc([task(1, "none")]));
964
- const graph = taskGraph([task(1, "none")]);
965
- const dispatch = stub((frame) =>
966
- frame.phase === "implement"
967
- ? APPROVED_IMPLEMENT
968
- : { status: "APPROVED", findings: [finding("blocker")] },
969
- );
970
- const run = new Lifecycle({
971
- face: targetFaces.wave,
972
- state: graph,
973
- ledger,
974
- dispatch: dispatch.step,
975
- planPath,
976
- });
977
- await run.advance(); // implement
978
- const review = await run.advance(); // review — the blocker awaits its fix; the brief revision binds
979
- expect(review!.frame.phase).toBe("review");
980
- expect(review!.route!.kind).toBe("fix");
981
- // the wave's OWN task section moves mid-flight (an orchestrator fill/fix) — the
982
- // recorded brief now drifts from the wave's current brief
983
- writeFileSync(planPath, planDoc([task(1, "none"), [" - extra step — checkable: green"]]));
984
- // the frontier re-offers the wave at REVIEW, never a stale `fix` — the drifted
985
- // brief voids the findings bound to the old revision. Without the single-source
986
- // derivation the frontier held `fix` while the gate accepted `review` (the
987
- // deadlock). The gate-side twin lives in wave.test.ts.
988
- const reopened = await run.advance();
989
- expect(reopened!.frame.phase).toBe("review");
990
- } finally {
991
- cleanup();
992
- }
993
- });
994
-
995
- it("an OUTSIDE-wave plan edit does NOT reopen the wave — the backfill's whole point (D30)", async () => {
996
- const { ledger, repo, cleanup } = fixture();
997
- try {
998
- const planPath = path.join(repo, "plan.md");
999
- writeFileSync(planPath, planDoc([task(1, "none"), task(2, "1")]));
1000
- const graph = taskGraph([task(1, "none"), task(2, "1")]);
1001
- const dispatch = stub((frame) =>
1002
- frame.phase === "implement"
1003
- ? APPROVED_IMPLEMENT
1004
- : { status: "APPROVED", findings: [finding("blocker")] },
1005
- );
1006
- const run = new Lifecycle({
1007
- face: targetFaces.wave,
1008
- state: graph,
1009
- ledger,
1010
- dispatch: dispatch.step,
1011
- planPath,
1012
- });
1013
- await run.advance(); // implement wave {1}
1014
- await run.advance(); // review — binds wave {1}'s brief; the blocker awaits its fix
1015
- // the plan gains a task OUTSIDE wave {1} (an append-only backfill) — the
1016
- // Constraints + Task 1 sections are byte-identical, so wave {1}'s brief is
1017
- // unchanged and the pending fix MUST survive (the whole-plan hash wrongly
1018
- // reopened it; D30 binds the brief)
1019
- writeFileSync(planPath, planDoc([task(1, "none"), task(2, "1"), task(3, "1,2")]));
1020
- const kept = await run.advance();
1021
- expect(kept!.frame.phase).toBe("fix");
1022
- } finally {
1023
- cleanup();
1024
- }
1025
- });
1026
- });