@oscaner-skills/cdd-engine 1.0.0 → 2.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (99) hide show
  1. package/README.md +9 -8
  2. package/README.zh-CN.md +9 -8
  3. package/package.json +15 -22
  4. package/src-next/__tests__/bin.test.ts +128 -0
  5. package/src-next/__tests__/smoke.integration.test.ts +202 -0
  6. package/src-next/__tests__/zero-dep.test.ts +134 -0
  7. package/src-next/bin.ts +61 -0
  8. package/src-next/contract/__tests__/__snapshots__/project.schema.overall-spec.snap +238 -0
  9. package/src-next/contract/__tests__/__snapshots__/project.schema.phase-spec.snap +153 -0
  10. package/src-next/contract/__tests__/__snapshots__/project.schema.plan.snap +173 -0
  11. package/src-next/contract/__tests__/__snapshots__/project.schema.single-spec.snap +89 -0
  12. package/src-next/contract/__tests__/__snapshots__/project.shape.overall-spec.snap +225 -0
  13. package/src-next/contract/__tests__/__snapshots__/project.shape.phase-spec.snap +155 -0
  14. package/src-next/contract/__tests__/__snapshots__/project.shape.plan.snap +175 -0
  15. package/src-next/contract/__tests__/__snapshots__/project.shape.single-spec.snap +85 -0
  16. package/src-next/contract/__tests__/declare.test.ts +242 -0
  17. package/src-next/contract/__tests__/doc.test.ts +358 -0
  18. package/src-next/contract/__tests__/judge.test.ts +873 -0
  19. package/src-next/contract/__tests__/lint.test.ts +314 -0
  20. package/src-next/contract/__tests__/project.test.ts +419 -0
  21. package/src-next/contract/__tests__/translate.test.ts +96 -0
  22. package/src-next/contract/declare.ts +983 -0
  23. package/src-next/contract/doc.ts +753 -0
  24. package/src-next/contract/invariants.ts +1268 -0
  25. package/src-next/contract/judge.ts +142 -0
  26. package/src-next/contract/lint.ts +275 -0
  27. package/src-next/contract/project.ts +596 -0
  28. package/src-next/contract/skill-anatomy.ts +273 -0
  29. package/src-next/contract/translate.ts +113 -0
  30. package/src-next/face/__tests__/board-view.test.ts +948 -0
  31. package/src-next/face/__tests__/capsule.test.ts +276 -0
  32. package/src-next/face/__tests__/channel-closure.guard.test.ts +102 -0
  33. package/src-next/face/__tests__/cli.test.ts +4643 -0
  34. package/src-next/face/__tests__/face.test.ts +289 -0
  35. package/src-next/face/__tests__/graph-view.test.ts +61 -0
  36. package/src-next/face/__tests__/host.test.ts +24 -0
  37. package/src-next/face/__tests__/negation.ts +6 -0
  38. package/src-next/face/__tests__/projection.test.ts +301 -0
  39. package/src-next/face/__tests__/sync-runner.test.ts +70 -0
  40. package/src-next/face/__tests__/words.guard.test.ts +93 -0
  41. package/src-next/face/artifacts.ts +195 -0
  42. package/src-next/face/board-view.ts +662 -0
  43. package/src-next/face/capsule.ts +149 -0
  44. package/src-next/face/cli.ts +819 -0
  45. package/src-next/face/declare.ts +326 -0
  46. package/src-next/face/gate.ts +170 -0
  47. package/src-next/face/graph-view.ts +74 -0
  48. package/src-next/face/host.ts +326 -0
  49. package/src-next/face/lifecycle.ts +700 -0
  50. package/src-next/face/projection.ts +282 -0
  51. package/src-next/face/route-render.ts +160 -0
  52. package/src-next/face/words.ts +296 -0
  53. package/src-next/infra/__tests__/infra.test.ts +287 -0
  54. package/src-next/infra/config.ts +42 -0
  55. package/src-next/infra/git.ts +39 -0
  56. package/src-next/infra/process.ts +34 -0
  57. package/src-next/infra/runtime.ts +185 -0
  58. package/src-next/infra/workspace.ts +232 -0
  59. package/src-next/render/__tests__/render.test.ts +499 -0
  60. package/src-next/render/__tests__/skeleton.test.ts +466 -0
  61. package/src-next/render/brief.ts +121 -0
  62. package/src-next/render/issue-body.ts +159 -0
  63. package/src-next/render/skeleton.ts +437 -0
  64. package/src-next/render/templates.ts +650 -0
  65. package/src-next/session/__tests__/graph.test.ts +270 -0
  66. package/src-next/session/__tests__/handoff-plane.guard.test.ts +48 -0
  67. package/src-next/session/__tests__/handoff-schema.test.ts +310 -0
  68. package/src-next/session/__tests__/ledger.test.ts +744 -0
  69. package/src-next/session/__tests__/next.test.ts +368 -0
  70. package/src-next/session/__tests__/preflight.test.ts +491 -0
  71. package/src-next/session/__tests__/run.test.ts +1014 -0
  72. package/src-next/session/__tests__/wave-line-phase.guard.test.ts +49 -0
  73. package/src-next/session/__tests__/wave.test.ts +469 -0
  74. package/src-next/session/faces.ts +110 -0
  75. package/src-next/session/graph.ts +411 -0
  76. package/src-next/session/handoff-schema.ts +373 -0
  77. package/src-next/session/ledger.ts +1004 -0
  78. package/src-next/session/next.ts +192 -0
  79. package/src-next/session/preflight.ts +240 -0
  80. package/src-next/session/run.ts +606 -0
  81. package/src-next/session/state.ts +30 -0
  82. package/src-next/session/wave.ts +139 -0
  83. package/templates/report/issue-body.json +18 -20
  84. package/dist/chunks/branch.mjs +0 -480
  85. package/dist/chunks/docs.mjs +0 -253
  86. package/dist/chunks/task.mjs +0 -913
  87. package/dist/cli.mjs +0 -5457
  88. package/dist/documents/schema/add-phase-protocol.json +0 -126
  89. package/dist/documents/schema/overall.json +0 -361
  90. package/dist/documents/schema/phase-spec.json +0 -145
  91. package/dist/documents/schema/plan.json +0 -191
  92. package/dist/documents/schema/skill-anatomy.json +0 -233
  93. package/dist/resources/harness-registry.json +0 -49
  94. package/dist/shared/cdd-engine.liioziig.mjs +0 -184
  95. package/templates/engine-config.json +0 -302
  96. package/templates/schema/cache-profile-schema.json +0 -23
  97. package/templates/schema/docs-handoff-schema.json +0 -129
  98. package/templates/schema/task-handoff-schema.json +0 -332
  99. package/templates/template-contract.json +0 -231
@@ -0,0 +1,744 @@
1
+ // packages/cdd-engine/src-next/session/__tests__/ledger.test.ts
2
+ // T9 Ledger suite (design spec §6.1) — the four-in-one session ledger:
3
+ // · progress — the fixed key set (emptyProgress), read/write round-trips, the
4
+ // row lookup pair (rowFor/entryFor — the task/group key dichotomy), the round
5
+ // record (roundCount/recordRound — the on-disk done record), the counters;
6
+ // · handoff — the data-sourced family naming, the carrier skeleton (build), the
7
+ // single-author persist (full-replace — the engine owns the file verbatim);
8
+ // · crash — the lane-crash recovery record round-trip (crash-<lane>-<round>.json);
9
+ // · round — the carrier read-back: review findings normalized with severity, the
10
+ // fix round carrying the SOURCE review's findings (C5-1), and the consecutive-S1
11
+ // walk (the review-cycle soft-cap basis).
12
+ // Fixtures live under mkdtemp (hermetic); the naming asserts read the living
13
+ // engine-config (the external contract JSONs — allowed steady-data reads, never the
14
+ // old tree's derived products).
15
+
16
+ import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
17
+ import { tmpdir } from "node:os";
18
+ import path from "node:path";
19
+ import { describe, expect, it } from "vitest";
20
+ import { ConfigLoader } from "../../infra/config.ts";
21
+ import { Workspace, WorkspaceRoot } from "../../infra/workspace.ts";
22
+ import { Ledger, type ProgressData, type RefKind } from "../ledger.ts";
23
+
24
+ /** A hermetic ledger fixture — a fresh temp workspace under a temp repo root. */
25
+ const fixture = (): { ledger: Ledger; workspace: Workspace; cleanup: () => void } => {
26
+ const repo = mkdtempSync(path.join(tmpdir(), "ledger-"));
27
+ const workspace = new Workspace(
28
+ new WorkspaceRoot(path.join(repo, ".kairos", "cdd"), "session"),
29
+ "test-slug",
30
+ );
31
+ const ledger = new Ledger(workspace, new ConfigLoader());
32
+ return { ledger, workspace, cleanup: () => rmSync(repo, { recursive: true, force: true }) };
33
+ };
34
+
35
+ describe("progress — the fixed key set", () => {
36
+ it("emptyProgress carries the fixed key set at zero (the counter arm + an empty rows list)", () => {
37
+ const { ledger, cleanup } = fixture();
38
+ try {
39
+ expect(ledger.emptyProgress()).toEqual({
40
+ timeoutCount: 0,
41
+ contractViolationCount: 0,
42
+ engineSelfWrittenCount: 0,
43
+ engineRecoveryCount: 0,
44
+ harnessAbortCount: 0,
45
+ waves: [],
46
+ });
47
+ } finally {
48
+ cleanup();
49
+ }
50
+ });
51
+
52
+ it("readProgress is null before the first write — the ledger never invents state", () => {
53
+ const { ledger, cleanup } = fixture();
54
+ try {
55
+ expect(ledger.readProgress()).toBeNull();
56
+ } finally {
57
+ cleanup();
58
+ }
59
+ });
60
+
61
+ it("writeProgress + readProgress round-trip the typed data plane", () => {
62
+ const { ledger, cleanup } = fixture();
63
+ try {
64
+ ledger.writeProgress({ ...ledger.emptyProgress(), plan: "docs/plan.md" });
65
+ expect(ledger.readProgress()?.plan).toBe("docs/plan.md");
66
+ } finally {
67
+ cleanup();
68
+ }
69
+ });
70
+
71
+ it("rowFor/entryFor — the single wave-row form (±T26): every dispatch is a wave", () => {
72
+ const { ledger, cleanup } = fixture();
73
+ try {
74
+ const data = ledger.emptyProgress();
75
+ data.waves.push(ledger.entryFor("1"));
76
+ data.waves.push(ledger.entryFor("1,2"));
77
+ expect(ledger.rowFor(data, "1")).toEqual({ wave: "1" }); // single-task wave ≡ the task row
78
+ expect(ledger.rowFor(data, "1,2")).toEqual({ wave: "1,2" });
79
+ expect(ledger.rowFor(data, "missing")).toBeUndefined();
80
+ } finally {
81
+ cleanup();
82
+ }
83
+ });
84
+
85
+ it("roundCount starts 0; recordRound persists the per-key per-mode done record", () => {
86
+ const { ledger, workspace, cleanup } = fixture();
87
+ try {
88
+ expect(ledger.roundCount("1,2", "review")).toBe(0);
89
+ expect(ledger.recordRound("1,2", "review")).toBe(1);
90
+ expect(ledger.recordRound("1,2", "review")).toBe(2);
91
+ expect(ledger.recordRound("1,2", "fix")).toBe(1);
92
+ // a fresh ledger over the same workspace reads the persisted counts back (on-disk record)
93
+ const reload = new Ledger(workspace, new ConfigLoader());
94
+ expect(reload.roundCount("1,2", "review")).toBe(2);
95
+ expect(reload.roundCount("1,2", "fix")).toBe(1);
96
+ expect(reload.roundCount("7", "review")).toBe(0);
97
+ } finally {
98
+ cleanup();
99
+ }
100
+ });
101
+
102
+ it("counterOf reads a failure-category count (0 default); writeProgress persists it", () => {
103
+ const { ledger, cleanup } = fixture();
104
+ try {
105
+ expect(ledger.counterOf("timeoutCount")).toBe(0);
106
+ ledger.writeProgress({ ...ledger.emptyProgress(), timeoutCount: 3 });
107
+ expect(ledger.counterOf("timeoutCount")).toBe(3);
108
+ expect(ledger.counterOf("harnessAbortCount")).toBe(0);
109
+ } finally {
110
+ cleanup();
111
+ }
112
+ });
113
+ });
114
+
115
+ describe("progress — the D28 round-identity face (cycles, not counts)", () => {
116
+ /** Write a progress row's raw `rounds` plane — the migration fixture (a legacy
117
+ * numeric count or the current cycle list written straight to disk). */
118
+ const seedRounds = (ledger: Ledger, rounds: Record<string, number | number[]>): void => {
119
+ const data = ledger.readProgress() ?? ledger.emptyProgress();
120
+ data.waves.push({ wave: "7,9", rounds: rounds as ProgressData["waves"][number]["rounds"] });
121
+ ledger.writeProgress(data);
122
+ };
123
+
124
+ it("#cyclesOf migrates a legacy numeric count to its contiguous identity — `{fix: 1}` ≡ `[1]`", () => {
125
+ const { ledger, cleanup } = fixture();
126
+ try {
127
+ seedRounds(ledger, { fix: 1 }); // the pre-D28 numeric shape on disk
128
+ expect(ledger.roundCount("7,9", "fix")).toBe(1);
129
+ expect(ledger.roundRecorded("7,9", "fix", 1)).toBe(true);
130
+ expect(ledger.roundRecorded("7,9", "fix", 2)).toBe(false);
131
+ } finally {
132
+ cleanup();
133
+ }
134
+ });
135
+
136
+ it("a legacy count of N normalizes to the cycle list [1..N] — `{review: 2}` ≡ `[1, 2]`", () => {
137
+ const { ledger, cleanup } = fixture();
138
+ try {
139
+ seedRounds(ledger, { review: 2 });
140
+ expect(ledger.roundCount("7,9", "review")).toBe(2);
141
+ expect(ledger.roundRecorded("7,9", "review", 1)).toBe(true);
142
+ expect(ledger.roundRecorded("7,9", "review", 2)).toBe(true);
143
+ expect(ledger.roundRecorded("7,9", "review", 3)).toBe(false);
144
+ } finally {
145
+ cleanup();
146
+ }
147
+ });
148
+
149
+ it("an already-migrated cycle list is preserved verbatim — `{review: [1, 2]}` stays `[1, 2]`", () => {
150
+ const { ledger, cleanup } = fixture();
151
+ try {
152
+ seedRounds(ledger, { review: [1, 2] });
153
+ expect(ledger.roundCount("7,9", "review")).toBe(2);
154
+ expect(ledger.roundRecorded("7,9", "review", 2)).toBe(true);
155
+ } finally {
156
+ cleanup();
157
+ }
158
+ });
159
+
160
+ it("recordRound records the CYCLE (its identity), defaulting to latest+1 — a skipped cycle keeps its own number", () => {
161
+ const { ledger, cleanup } = fixture();
162
+ try {
163
+ // an explicit cycle records its OWN number (fix-2 = the fix that addressed review-2)
164
+ expect(ledger.recordRound("7,9", "fix", 2)).toBe(1);
165
+ expect(ledger.roundRecorded("7,9", "fix", 2)).toBe(true);
166
+ expect(ledger.roundRecorded("7,9", "fix", 1)).toBe(false); // cycle 1 was skipped — never fabricated
167
+ // a default recordRound appends the next cycle after the latest (2 → 3)
168
+ expect(ledger.recordRound("7,9", "fix")).toBe(2);
169
+ expect(ledger.roundRecorded("7,9", "fix", 3)).toBe(true);
170
+ // a re-record of an existing cycle is idempotent (never doubled)
171
+ expect(ledger.recordRound("7,9", "fix", 2)).toBe(2);
172
+ expect(ledger.roundCount("7,9", "fix")).toBe(2);
173
+ } finally {
174
+ cleanup();
175
+ }
176
+ });
177
+
178
+ it("the round() read gate tests IDENTITY, not a count — `{review:[1,2], fix:[2]}` reads fix cycle 2 back", () => {
179
+ const { ledger, cleanup } = fixture();
180
+ try {
181
+ // the drift-voided review-1 shape: the first fix is cycle 2 (fix-K ⟷ review-K)
182
+ seedRounds(ledger, { review: [1, 2], fix: [2] });
183
+ ledger.persistHandoff(
184
+ "review",
185
+ "wave",
186
+ { tasks: "7,9", round: 2 },
187
+ { findings: [{ severity: "blocker", summary: "survives" }] },
188
+ );
189
+ ledger.persistHandoff("fix", "wave", { tasks: "7,9", round: 2 }, { artifacts: {} });
190
+ // the old `roundCount < round` comparison (1 < 2) refused this read → a HARD_ERROR
191
+ // on a fix that legitimately concluded; the identity gate reads it back
192
+ expect(ledger.round("fix", "wave", { tasks: "7,9" }, 2)).not.toBeNull();
193
+ // an unrecorded cycle is still refused (identity, not ordinal)
194
+ expect(ledger.round("fix", "wave", { tasks: "7,9" }, 1)).toBeNull();
195
+ } finally {
196
+ cleanup();
197
+ }
198
+ });
199
+ });
200
+
201
+ describe("handoff — naming / carrier / single-author persist", () => {
202
+ it("family names come data-sourced from the handoff namespace", () => {
203
+ const { ledger, cleanup } = fixture();
204
+ try {
205
+ expect(ledger.handoffName("implement", "wave", { tasks: "7,9" })).toBe(
206
+ "tasks-7,9-implement.json",
207
+ );
208
+ expect(ledger.handoffName("review", "wave", { tasks: "7,9", round: 2 })).toBe(
209
+ "tasks-7,9-review-2.json",
210
+ );
211
+ expect(ledger.handoffName("fix", "wave", { tasks: "7,9", round: 1 })).toBe(
212
+ "tasks-7,9-fix-1.json",
213
+ );
214
+ expect(ledger.handoffName("review", "spec", { round: 1 })).toBe("spec-review-1.json");
215
+ expect(ledger.handoffName("fix", "plan", { round: 1 })).toBe("plan-fix-1.json");
216
+ // find #9 — the branch family name is the spine `branch-{op}-{round}.json`
217
+ // (the range token left the file name — the branch line holds no commit identity)
218
+ expect(ledger.handoffName("review", "branch", { round: 1 })).toBe("branch-review-1.json");
219
+ expect(ledger.handoffName("fix", "branch", { round: 2 })).toBe("branch-fix-2.json");
220
+ } finally {
221
+ cleanup();
222
+ }
223
+ });
224
+
225
+ it("buildHandoff carries ONLY the schema-declared writable fields — identity rides the file name, never phase/tasks inline (v1.30)", () => {
226
+ const { ledger, cleanup } = fixture();
227
+ try {
228
+ const carrier = ledger.buildHandoff("work", { artifacts: { brief: "/tmp/brief.md" } });
229
+ // the carrier's plane is the schema's declared fields — no inline phase/tasks
230
+ // identity (the canonical file name `tasks-7,9-review-1.json` carries it; inline
231
+ // identity seeded the mimicking precedence the reserved gate then had to refuse)
232
+ expect("phase" in carrier).toBe(false);
233
+ expect("tasks" in carrier).toBe(false);
234
+ // T1 — the work carrier physically carries no findings key (the per-face typing)
235
+ expect("findings" in carrier).toBe(false);
236
+ expect(carrier.artifacts).toEqual({ brief: "/tmp/brief.md" });
237
+ expect(ledger.buildHandoff("work", {}).artifacts).toEqual({});
238
+ } finally {
239
+ cleanup();
240
+ }
241
+ });
242
+
243
+ it("persistHandoff writes the canonical file verbatim — the single-author full-replace write", () => {
244
+ const { ledger, workspace, cleanup } = fixture();
245
+ try {
246
+ const written = ledger.persistHandoff(
247
+ "review",
248
+ "wave",
249
+ { tasks: "7,9", round: 1 },
250
+ { tasks: [7, 9], phase: "review", findings: [{ severity: "blocker" }] },
251
+ );
252
+ expect(written).toBe(workspace.resolve("tasks-7,9-review-1.json"));
253
+ expect(JSON.parse(readFileSync(written, "utf8"))).toEqual({
254
+ tasks: [7, 9],
255
+ phase: "review",
256
+ findings: [{ severity: "blocker" }],
257
+ });
258
+ // The engine is the sole author: a second persist FULLY replaces — the stale finding
259
+ // never survives a merge.
260
+ const second = ledger.persistHandoff(
261
+ "review",
262
+ "wave",
263
+ { tasks: "7,9", round: 1 },
264
+ { tasks: [7, 9], phase: "review", findings: [] },
265
+ );
266
+ expect(JSON.parse(readFileSync(second, "utf8"))).toEqual({
267
+ tasks: [7, 9],
268
+ phase: "review",
269
+ findings: [],
270
+ });
271
+ } finally {
272
+ cleanup();
273
+ }
274
+ });
275
+
276
+ it("readHandoff returns the carrier; missing → null", () => {
277
+ const { ledger, cleanup } = fixture();
278
+ try {
279
+ expect(ledger.readHandoff("review", "wave", { tasks: "7,9", round: 1 })).toBeNull();
280
+ ledger.persistHandoff(
281
+ "review",
282
+ "wave",
283
+ { tasks: "7,9", round: 1 },
284
+ { findings: [{ severity: "warn" }] },
285
+ );
286
+ expect(ledger.readHandoff("review", "wave", { tasks: "7,9", round: 1 })).toEqual({
287
+ findings: [{ severity: "warn" }],
288
+ });
289
+ } finally {
290
+ cleanup();
291
+ }
292
+ });
293
+ });
294
+
295
+ describe("crash — the lane-crash recovery record", () => {
296
+ it("names the record crash-<lane>-<round>.json at the canonical path", () => {
297
+ const { ledger, workspace, cleanup } = fixture();
298
+ try {
299
+ expect(ledger.crashName("implement", 2)).toBe("crash-implement-2.json");
300
+ expect(ledger.crashPath("implement", 2)).toBe(workspace.resolve("crash-implement-2.json"));
301
+ } finally {
302
+ cleanup();
303
+ }
304
+ });
305
+
306
+ it("writeCrash → readCrash round-trips the recovery record (the resume decision source)", () => {
307
+ const { ledger, cleanup } = fixture();
308
+ try {
309
+ const record = {
310
+ exitCode: 1,
311
+ stderrTail: ["engine error: boom"],
312
+ stdoutTail: [],
313
+ attemptedHandoff: "tasks-1-implement.json",
314
+ next: "cdd implement --tasks 1",
315
+ cause: "child-exit" as const,
316
+ };
317
+ ledger.writeCrash("implement", 1, record);
318
+ expect(ledger.readCrash("implement", 1)).toEqual(record);
319
+ // a recordless failure round stays recordless — the no-next failure face
320
+ expect(ledger.readCrash("implement", 2)).toBeNull();
321
+ } finally {
322
+ cleanup();
323
+ }
324
+ });
325
+ });
326
+
327
+ describe("round — the round carrier", () => {
328
+ it("reads a review round's carrier — phase, normalized findings, the handoff path, the S1 walk", () => {
329
+ const { ledger, workspace, cleanup } = fixture();
330
+ try {
331
+ ledger.persistHandoff(
332
+ "review",
333
+ "wave",
334
+ { tasks: "7,9", round: 1 },
335
+ {
336
+ tasks: [7, 9],
337
+ phase: "review",
338
+ findings: [
339
+ { severity: "blocker", summary: "defect" },
340
+ { severity: "warn", summary: "smell" },
341
+ { severity: "bogus", summary: "never invented into the judgment domain" },
342
+ ],
343
+ },
344
+ );
345
+ // §2.8 — the round-read gate: only a recorded round is a round
346
+ ledger.recordRound("7,9", "review");
347
+ const carrier = ledger.round("review", "wave", { tasks: "7,9" }, 1);
348
+ expect(carrier).not.toBeNull();
349
+ expect(carrier!.phase).toBe("review");
350
+ expect(carrier!.findings).toEqual([
351
+ { severity: "blocker", summary: "defect" },
352
+ { severity: "warn", summary: "smell" },
353
+ ]);
354
+ expect(carrier!.findingsPath).toBe(workspace.resolve("tasks-7,9-review-1.json"));
355
+ expect(carrier!.consecutiveS1).toBe(1);
356
+ } finally {
357
+ cleanup();
358
+ }
359
+ });
360
+
361
+ it("fix rounds carry the SOURCE review's findings, never their own carrier (C5-1)", () => {
362
+ const { ledger, workspace, cleanup } = fixture();
363
+ try {
364
+ ledger.persistHandoff(
365
+ "review",
366
+ "wave",
367
+ { tasks: "7,9", round: 1 },
368
+ { findings: [{ severity: "blocker", summary: "the input findings" }] },
369
+ );
370
+ ledger.persistHandoff(
371
+ "fix",
372
+ "wave",
373
+ { tasks: "7,9", round: 1 },
374
+ { phase: "fix", findings: [] },
375
+ );
376
+ ledger.recordRound("7,9", "fix");
377
+ const carrier = ledger.round("fix", "wave", { tasks: "7,9" }, 1);
378
+ expect(carrier).not.toBeNull();
379
+ expect(carrier!.phase).toBe("fix");
380
+ // the judgment findings are the source review's input, never the fix's own empty carrier
381
+ expect(carrier!.findings).toEqual([{ severity: "blocker", summary: "the input findings" }]);
382
+ expect(carrier!.findingsPath).toBe(workspace.resolve("tasks-7,9-review-1.json"));
383
+ expect(carrier!.consecutiveS1).toBe(1);
384
+ } finally {
385
+ cleanup();
386
+ }
387
+ });
388
+
389
+ it("an unrecorded round is null — a rejected child's leftover draft is never read back (§2.8)", () => {
390
+ const { ledger, cleanup } = fixture();
391
+ try {
392
+ // a fix draft sits on disk (the child's rejected write) but recordRound never counted it
393
+ ledger.persistHandoff(
394
+ "fix",
395
+ "wave",
396
+ { tasks: "7,9", round: 1 },
397
+ { phase: "fix", findings: [] },
398
+ );
399
+ ledger.persistHandoff(
400
+ "review",
401
+ "wave",
402
+ { tasks: "7,9", round: 1 },
403
+ { findings: [{ severity: "blocker" }] },
404
+ );
405
+ // the fix round was never recorded → null whatever the disk draft says
406
+ expect(ledger.round("fix", "wave", { tasks: "7,9" }, 1)).toBeNull();
407
+ // recorded → the same read returns the carrier
408
+ ledger.recordRound("7,9", "fix");
409
+ expect(ledger.round("fix", "wave", { tasks: "7,9" }, 1)).not.toBeNull();
410
+ } finally {
411
+ cleanup();
412
+ }
413
+ });
414
+
415
+ it("a fix round whose source review is unreadable is null — never a zero-findings fabrication", () => {
416
+ const { ledger, cleanup } = fixture();
417
+ try {
418
+ // the fix carrier is on record but the source review it judges (C5-1) is missing
419
+ ledger.persistHandoff(
420
+ "fix",
421
+ "wave",
422
+ { tasks: "7,9", round: 1 },
423
+ { phase: "fix", findings: [] },
424
+ );
425
+ ledger.recordRound("7,9", "fix");
426
+ // missing source review → no round on record (matching the review branch): the next-hop
427
+ // derivation cannot close a line whose blocker set was never read
428
+ expect(ledger.round("fix", "wave", { tasks: "7,9" }, 1)).toBeNull();
429
+ } finally {
430
+ cleanup();
431
+ }
432
+ });
433
+
434
+ it("a fix round whose own carrier is missing is null too — unreadable either side", () => {
435
+ const { ledger, cleanup } = fixture();
436
+ try {
437
+ ledger.persistHandoff(
438
+ "review",
439
+ "wave",
440
+ { tasks: "1", round: 1 },
441
+ { findings: [{ severity: "blocker" }] },
442
+ );
443
+ ledger.recordRound("1", "fix");
444
+ expect(ledger.round("fix", "wave", { tasks: "1" }, 1)).toBeNull();
445
+ } finally {
446
+ cleanup();
447
+ }
448
+ });
449
+
450
+ it("walks the consecutive-S1 run newest-first, stopping at the first clean review", () => {
451
+ const { ledger, cleanup } = fixture();
452
+ try {
453
+ for (const roundNumber of [1, 2]) {
454
+ ledger.persistHandoff(
455
+ "review",
456
+ "wave",
457
+ { tasks: "7,9", round: roundNumber },
458
+ { findings: [{ severity: "blocker" }] },
459
+ );
460
+ ledger.recordRound("7,9", "review");
461
+ }
462
+ const twoS1 = ledger.round("review", "wave", { tasks: "7,9" }, 2);
463
+ expect(twoS1!.consecutiveS1).toBe(2);
464
+ // a clean review at round 3 resets the run
465
+ ledger.persistHandoff(
466
+ "review",
467
+ "wave",
468
+ { tasks: "7,9", round: 3 },
469
+ { findings: [{ severity: "warn" }] },
470
+ );
471
+ ledger.recordRound("7,9", "review");
472
+ expect(ledger.round("review", "wave", { tasks: "7,9" }, 3)!.consecutiveS1).toBe(0);
473
+ } finally {
474
+ cleanup();
475
+ }
476
+ });
477
+
478
+ it("an unreadable round history degrades the run to the conservative baseline, never a throw", () => {
479
+ const { ledger, cleanup } = fixture();
480
+ try {
481
+ ledger.persistHandoff(
482
+ "review",
483
+ "wave",
484
+ { tasks: "1", round: 1 },
485
+ { findings: [{ severity: "blocker" }] },
486
+ );
487
+ // rounds 1 + 2 are recorded, but round 2's file is missing → the read is null, never a throw
488
+ ledger.recordRound("1", "review");
489
+ ledger.recordRound("1", "review");
490
+ expect(ledger.round("review", "wave", { tasks: "1" }, 2)).toBeNull();
491
+ } finally {
492
+ cleanup();
493
+ }
494
+ });
495
+ });
496
+
497
+ describe("review references — the refKind face (T25 · P5)", () => {
498
+ it("the RefKind union carries the two review kinds (doc-revision · brief-revision) and the commit-bearing kinds stay retired", () => {
499
+ // The type probe: the two review kinds ARE members (D30 — doc-revision is the
500
+ // spec/plan line, brief-revision the wave line), and the retired commit kinds
501
+ // are absent (the wave-atomic + no-commit-identity rulings — R5 · P7).
502
+ const docMember: "doc-revision" extends RefKind ? true : false = true;
503
+ const briefMember: "brief-revision" extends RefKind ? true : false = true;
504
+ const noCommitSet: "commit-set-ledger" extends RefKind ? true : false = false;
505
+ const noCommitRange: "commit-range" extends RefKind ? true : false = false;
506
+ const noGraphNode: "graph-node" extends RefKind ? true : false = false;
507
+ expect(docMember).toBe(true);
508
+ expect(briefMember).toBe(true);
509
+ expect(noCommitSet).toBe(false);
510
+ expect(noCommitRange).toBe(false);
511
+ expect(noGraphNode).toBe(false);
512
+ });
513
+
514
+ it("the doc-revision two-layer binding — the doc path + the content-hash revision", () => {
515
+ const { ledger, cleanup } = fixture();
516
+ try {
517
+ const refs = ledger.refs();
518
+ const docRef = refs.docRevision("docs/kairos/specs/x-design.md", "revision one");
519
+ expect(docRef.kind).toBe("doc-revision");
520
+ expect(docRef.doc).toBe("docs/kairos/specs/x-design.md");
521
+ // the doc-revision content hash stays a full sha1 hex — a non-ref digest,
522
+ // unsliced (a bare 8-char digest slice would narrow the bind basis to
523
+ // birthday-collision range)
524
+ expect(docRef.doc_hash).toMatch(/^[0-9a-f]{40}$/);
525
+ // the same content hashes the same revision — the two-layer convergence
526
+ const docRefAgain = refs.docRevision("docs/kairos/specs/x-design.md", "revision one");
527
+ expect(docRefAgain.doc_hash).toBe(docRef.doc_hash);
528
+ // a different revision hashes differently — the revision layer is content-bound
529
+ const edited = refs.docRevision("docs/kairos/specs/x-design.md", "revision two");
530
+ expect(edited.doc_hash).not.toBe(docRef.doc_hash);
531
+ } finally {
532
+ cleanup();
533
+ }
534
+ });
535
+
536
+ it("the same-ref ruling — the SAME doc revision is the same ref, a different doc/revision is not", () => {
537
+ const { ledger, cleanup } = fixture();
538
+ try {
539
+ const refs = ledger.refs();
540
+ const docRef = refs.docRevision("docs/kairos/specs/x-design.md", "revision one");
541
+ // the identical ref (same doc + same hash) is the SAME ref
542
+ const duplicate = refs.docRevision("docs/kairos/specs/x-design.md", "revision one");
543
+ expect(refs.sameRef(docRef, duplicate)).toBe(true);
544
+ // a different revision of the same doc is NOT the same ref
545
+ const edited = refs.docRevision("docs/kairos/specs/x-design.md", "revision two");
546
+ expect(refs.sameRef(docRef, edited)).toBe(false);
547
+ // a different doc is never the same ref
548
+ const otherDoc = refs.docRevision("docs/kairos/specs/y-design.md", "revision one");
549
+ expect(refs.sameRef(docRef, otherDoc)).toBe(false);
550
+ } finally {
551
+ cleanup();
552
+ }
553
+ });
554
+
555
+ it("the cross-kind ruling — a doc-revision and a brief-revision are never the same ref", () => {
556
+ const { ledger, cleanup } = fixture();
557
+ try {
558
+ const refs = ledger.refs();
559
+ const docRef = refs.docRevision("docs/kairos/plans/x-p3.md", "the plan body");
560
+ // a brief-revision is a distinct ref KIND — the wave line's identity is never
561
+ // the doc line's, even when the plan path layer and the hash layer coincide
562
+ const briefRef = refs.briefRevision("docs/kairos/plans/x-p3.md", "the plan body");
563
+ expect(briefRef.kind).toBe("brief-revision");
564
+ expect(refs.sameRef(docRef, briefRef)).toBe(false);
565
+ expect(refs.sameRef(briefRef, docRef)).toBe(false);
566
+ // the same-kind brief-revision is still the same ref (the guard is the kind,
567
+ // not a blanket refusal)
568
+ const briefRefAgain = refs.briefRevision("docs/kairos/plans/x-p3.md", "the plan body");
569
+ expect(refs.sameRef(briefRef, briefRefAgain)).toBe(true);
570
+ } finally {
571
+ cleanup();
572
+ }
573
+ });
574
+ });
575
+
576
+ describe("the T7 doc-line identity record — reviewedDocRevision (the reopen-compare basis)", () => {
577
+ it("records + reads the reviewed doc revision on the doc line's progress row", () => {
578
+ const { ledger, workspace, cleanup } = fixture();
579
+ try {
580
+ const doc = "docs/kairos/specs/x-design.md";
581
+ const revision = ledger.refs().docRevision(doc, "revision one");
582
+ expect(ledger.reviewedDocRevisionOf(doc)).toBeNull();
583
+ ledger.recordReviewedRevision(doc, revision);
584
+ expect(ledger.reviewedDocRevisionOf(doc)).toEqual(revision);
585
+ // a fresh ledger over the same workspace reads the on-disk record back
586
+ const reload = new Ledger(workspace, new ConfigLoader());
587
+ expect(reload.reviewedDocRevisionOf(doc)).toEqual(revision);
588
+ expect(reload.reviewedDocRevisionOf("docs/other.md")).toBeNull();
589
+ } finally {
590
+ cleanup();
591
+ }
592
+ });
593
+
594
+ it("a reviewed doc revision RE-records on drift — the reopen's new identity basis", () => {
595
+ const { ledger, cleanup } = fixture();
596
+ try {
597
+ const doc = "docs/kairos/plans/x-p3.md";
598
+ const first = ledger.refs().docRevision(doc, "v1.0 body");
599
+ const second = ledger.refs().docRevision(doc, "v1.1 body");
600
+ ledger.recordReviewedRevision(doc, first);
601
+ expect(ledger.reviewedDocRevisionOf(doc)).toEqual(first);
602
+ // a later review round records its own revision — the line gate compares the
603
+ // target against the LATEST reviewed identity
604
+ ledger.recordReviewedRevision(doc, second);
605
+ expect(ledger.reviewedDocRevisionOf(doc)).toEqual(second);
606
+ } finally {
607
+ cleanup();
608
+ }
609
+ });
610
+
611
+ it("docLineVerdict — the shared identity comparison: same vs drift vs the null faces", () => {
612
+ const { ledger, workspace, cleanup } = fixture();
613
+ try {
614
+ const doc = path.join(workspace.path, "docs", "x-p1.md");
615
+ mkdirSync(path.dirname(doc), { recursive: true });
616
+ writeFileSync(doc, "v1.0 body", "utf8");
617
+ // an absent reviewed identity → null (the legacy closed face — no comparison)
618
+ expect(ledger.docLineVerdict("1", doc)).toBeNull();
619
+ ledger.recordReviewedRevision("1", ledger.refs().docRevision(doc, "v1.0 body"));
620
+ // the recorded identity matches the current doc → "same" (the revision-aware BLOCK)
621
+ expect(ledger.docLineVerdict("1", doc)).toBe("same");
622
+ // the doc moved past the reviewed identity → "drift" (the line reopens)
623
+ writeFileSync(doc, "v1.1 body", "utf8");
624
+ expect(ledger.docLineVerdict("1", doc)).toBe("drift");
625
+ // an unreadable doc → null (only present facts land — no invented identity)
626
+ rmSync(doc);
627
+ expect(ledger.docLineVerdict("1", doc)).toBeNull();
628
+ } finally {
629
+ cleanup();
630
+ }
631
+ });
632
+ });
633
+
634
+ describe("the review gate — the D28 phantom-pending-fix suppression", () => {
635
+ it("a drift-voided review-1 (fix cycle 2) is NOT a pending fix — the identity membership, never a count", () => {
636
+ const { ledger, workspace, cleanup } = fixture();
637
+ try {
638
+ const doc = path.join(workspace.path, "docs", "x-spec.md");
639
+ mkdirSync(path.dirname(doc), { recursive: true });
640
+ writeFileSync(doc, "the reviewed body", "utf8");
641
+ // the drift-voided review-1 shape: review cycles [1, 2] with the fix at cycle 2.
642
+ // A `fixes(1) < reviews(2)` count comparison reads a phantom pending fix and
643
+ // re-opens the line forever; the identity membership (2 ∈ {2}) suppresses it.
644
+ const data = ledger.readProgress() ?? ledger.emptyProgress();
645
+ data.waves.push({ wave: "spec", rounds: { review: [1, 2], fix: [2] } });
646
+ ledger.writeProgress(data);
647
+ ledger.recordReviewedRevision("spec", ledger.refs().docRevision(doc, "the reviewed body"));
648
+ const verdict = ledger.reviewGate("spec", doc, "spec");
649
+ // the unchanged doc stays "same" with NO pending fix (the fix cycle 2 landed)
650
+ expect(verdict.kind).toBe("same");
651
+ if (verdict.kind === "same") expect(verdict.pending).toBe(false);
652
+ } finally {
653
+ cleanup();
654
+ }
655
+ });
656
+
657
+ it("a review with no fix yet IS the pending face — the review's own fix is outstanding", () => {
658
+ const { ledger, workspace, cleanup } = fixture();
659
+ try {
660
+ const doc = path.join(workspace.path, "docs", "y-spec.md");
661
+ mkdirSync(path.dirname(doc), { recursive: true });
662
+ writeFileSync(doc, "the reviewed body", "utf8");
663
+ const data = ledger.readProgress() ?? ledger.emptyProgress();
664
+ data.waves.push({ wave: "spec", rounds: { review: [1] } });
665
+ ledger.writeProgress(data);
666
+ ledger.recordReviewedRevision("spec", ledger.refs().docRevision(doc, "the reviewed body"));
667
+ // the review round carries a blocker (non-APPROVED) → the fix awaits
668
+ ledger.persistHandoff(
669
+ "review",
670
+ "spec",
671
+ { round: 1 },
672
+ { findings: [{ severity: "blocker", summary: "defect" }] },
673
+ );
674
+ const verdict = ledger.reviewGate("spec", doc, "spec");
675
+ expect(verdict.kind).toBe("same");
676
+ if (verdict.kind === "same") expect(verdict.pending).toBe(true);
677
+ } finally {
678
+ cleanup();
679
+ }
680
+ });
681
+ });
682
+
683
+ describe("lineClosed — the single line-closure judge (the board + closedWaves core)", () => {
684
+ /** Seed a line row's raw `rounds` plane on the fixture's `test-slug` workspace. */
685
+ const seedRow = (ledger: Ledger, key: string, rounds: Record<string, number[]>): void => {
686
+ const data = ledger.readProgress() ?? ledger.emptyProgress();
687
+ data.waves.push({ wave: key, rounds });
688
+ ledger.writeProgress(data);
689
+ };
690
+
691
+ it("a skipped-cycle fix (`{review:[1,2], fix:[2]}`) is CLOSED — the identity read, never a count", () => {
692
+ const { ledger, cleanup } = fixture();
693
+ try {
694
+ // The drift-voided review-1 shape: the first fix is cycle 2 (fix-K ⟷ review-K).
695
+ // A count-based judge computes `fixes(1)`, reads the nonexistent fix cycle 1 and
696
+ // reads the line OPEN; the identity judge reads the fix at its own cycle 2.
697
+ seedRow(ledger, "plan", { review: [1, 2], fix: [2] });
698
+ const params = { round: 2 };
699
+ ledger.persistHandoff("review", "plan", params, { findings: [] });
700
+ // the docs-fix face is a findings carrier (fix.plan schema) — an empty rollup is APPROVED
701
+ ledger.persistHandoff("fix", "plan", params, { findings: [] });
702
+
703
+ expect(ledger.lineClosed("plan", "plan")).toBe(true);
704
+ } finally {
705
+ cleanup();
706
+ }
707
+ });
708
+
709
+ it("a line whose latest fix round carries blockers stays OPEN — the C5 route, not the mere presence", () => {
710
+ const { ledger, cleanup } = fixture();
711
+ try {
712
+ seedRow(ledger, "plan", { review: [1, 2], fix: [2] });
713
+ const params = { round: 2 };
714
+ // the fix's source review carries a blocker → the C5 route is a re-review, not closure
715
+ ledger.persistHandoff("review", "plan", params, {
716
+ findings: [{ severity: "blocker", summary: "survives" }],
717
+ });
718
+ ledger.persistHandoff("fix", "plan", params, { findings: [] });
719
+
720
+ expect(ledger.lineClosed("plan", "plan")).toBe(false);
721
+ } finally {
722
+ cleanup();
723
+ }
724
+ });
725
+
726
+ it("a line with no review round yet is OPEN — an implement-only row never closes", () => {
727
+ const { ledger, cleanup } = fixture();
728
+ try {
729
+ seedRow(ledger, "plan", { implement: [1] });
730
+ expect(ledger.lineClosed("plan", "plan")).toBe(false);
731
+ } finally {
732
+ cleanup();
733
+ }
734
+ });
735
+
736
+ it("an absent row (or absent progress) is OPEN — present facts only", () => {
737
+ const { ledger, cleanup } = fixture();
738
+ try {
739
+ expect(ledger.lineClosed("plan", "plan")).toBe(false);
740
+ } finally {
741
+ cleanup();
742
+ }
743
+ });
744
+ });