@oscaner-skills/cdd-engine 2.0.0 → 3.0.1

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