@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,745 +0,0 @@
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
- lastSample: null,
317
- };
318
- ledger.writeCrash("implement", 1, record);
319
- expect(ledger.readCrash("implement", 1)).toEqual(record);
320
- // a recordless failure round stays recordless — the no-next failure face
321
- expect(ledger.readCrash("implement", 2)).toBeNull();
322
- } finally {
323
- cleanup();
324
- }
325
- });
326
- });
327
-
328
- describe("round — the round carrier", () => {
329
- it("reads a review round's carrier — phase, normalized findings, the handoff path, the S1 walk", () => {
330
- const { ledger, workspace, cleanup } = fixture();
331
- try {
332
- ledger.persistHandoff(
333
- "review",
334
- "wave",
335
- { tasks: "7,9", round: 1 },
336
- {
337
- tasks: [7, 9],
338
- phase: "review",
339
- findings: [
340
- { severity: "blocker", summary: "defect" },
341
- { severity: "warn", summary: "smell" },
342
- { severity: "bogus", summary: "never invented into the judgment domain" },
343
- ],
344
- },
345
- );
346
- // §2.8 — the round-read gate: only a recorded round is a round
347
- ledger.recordRound("7,9", "review");
348
- const carrier = ledger.round("review", "wave", { tasks: "7,9" }, 1);
349
- expect(carrier).not.toBeNull();
350
- expect(carrier!.phase).toBe("review");
351
- expect(carrier!.findings).toEqual([
352
- { severity: "blocker", summary: "defect" },
353
- { severity: "warn", summary: "smell" },
354
- ]);
355
- expect(carrier!.reviewsPath).toBe(workspace.resolve("tasks-7,9-review-1.json"));
356
- expect(carrier!.consecutiveS1).toBe(1);
357
- } finally {
358
- cleanup();
359
- }
360
- });
361
-
362
- it("fix rounds carry the SOURCE review's findings, never their own carrier (C5-1)", () => {
363
- const { ledger, workspace, cleanup } = fixture();
364
- try {
365
- ledger.persistHandoff(
366
- "review",
367
- "wave",
368
- { tasks: "7,9", round: 1 },
369
- { findings: [{ severity: "blocker", summary: "the input findings" }] },
370
- );
371
- ledger.persistHandoff(
372
- "fix",
373
- "wave",
374
- { tasks: "7,9", round: 1 },
375
- { phase: "fix", findings: [] },
376
- );
377
- ledger.recordRound("7,9", "fix");
378
- const carrier = ledger.round("fix", "wave", { tasks: "7,9" }, 1);
379
- expect(carrier).not.toBeNull();
380
- expect(carrier!.phase).toBe("fix");
381
- // the judgment findings are the source review's input, never the fix's own empty carrier
382
- expect(carrier!.findings).toEqual([{ severity: "blocker", summary: "the input findings" }]);
383
- expect(carrier!.reviewsPath).toBe(workspace.resolve("tasks-7,9-review-1.json"));
384
- expect(carrier!.consecutiveS1).toBe(1);
385
- } finally {
386
- cleanup();
387
- }
388
- });
389
-
390
- it("an unrecorded round is null — a rejected child's leftover draft is never read back (§2.8)", () => {
391
- const { ledger, cleanup } = fixture();
392
- try {
393
- // a fix draft sits on disk (the child's rejected write) but recordRound never counted it
394
- ledger.persistHandoff(
395
- "fix",
396
- "wave",
397
- { tasks: "7,9", round: 1 },
398
- { phase: "fix", findings: [] },
399
- );
400
- ledger.persistHandoff(
401
- "review",
402
- "wave",
403
- { tasks: "7,9", round: 1 },
404
- { findings: [{ severity: "blocker" }] },
405
- );
406
- // the fix round was never recorded → null whatever the disk draft says
407
- expect(ledger.round("fix", "wave", { tasks: "7,9" }, 1)).toBeNull();
408
- // recorded → the same read returns the carrier
409
- ledger.recordRound("7,9", "fix");
410
- expect(ledger.round("fix", "wave", { tasks: "7,9" }, 1)).not.toBeNull();
411
- } finally {
412
- cleanup();
413
- }
414
- });
415
-
416
- it("a fix round whose source review is unreadable is null — never a zero-findings fabrication", () => {
417
- const { ledger, cleanup } = fixture();
418
- try {
419
- // the fix carrier is on record but the source review it judges (C5-1) is missing
420
- ledger.persistHandoff(
421
- "fix",
422
- "wave",
423
- { tasks: "7,9", round: 1 },
424
- { phase: "fix", findings: [] },
425
- );
426
- ledger.recordRound("7,9", "fix");
427
- // missing source review → no round on record (matching the review branch): the next-hop
428
- // derivation cannot close a line whose blocker set was never read
429
- expect(ledger.round("fix", "wave", { tasks: "7,9" }, 1)).toBeNull();
430
- } finally {
431
- cleanup();
432
- }
433
- });
434
-
435
- it("a fix round whose own carrier is missing is null too — unreadable either side", () => {
436
- const { ledger, cleanup } = fixture();
437
- try {
438
- ledger.persistHandoff(
439
- "review",
440
- "wave",
441
- { tasks: "1", round: 1 },
442
- { findings: [{ severity: "blocker" }] },
443
- );
444
- ledger.recordRound("1", "fix");
445
- expect(ledger.round("fix", "wave", { tasks: "1" }, 1)).toBeNull();
446
- } finally {
447
- cleanup();
448
- }
449
- });
450
-
451
- it("walks the consecutive-S1 run newest-first, stopping at the first clean review", () => {
452
- const { ledger, cleanup } = fixture();
453
- try {
454
- for (const roundNumber of [1, 2]) {
455
- ledger.persistHandoff(
456
- "review",
457
- "wave",
458
- { tasks: "7,9", round: roundNumber },
459
- { findings: [{ severity: "blocker" }] },
460
- );
461
- ledger.recordRound("7,9", "review");
462
- }
463
- const twoS1 = ledger.round("review", "wave", { tasks: "7,9" }, 2);
464
- expect(twoS1!.consecutiveS1).toBe(2);
465
- // a clean review at round 3 resets the run
466
- ledger.persistHandoff(
467
- "review",
468
- "wave",
469
- { tasks: "7,9", round: 3 },
470
- { findings: [{ severity: "warn" }] },
471
- );
472
- ledger.recordRound("7,9", "review");
473
- expect(ledger.round("review", "wave", { tasks: "7,9" }, 3)!.consecutiveS1).toBe(0);
474
- } finally {
475
- cleanup();
476
- }
477
- });
478
-
479
- it("an unreadable round history degrades the run to the conservative baseline, never a throw", () => {
480
- const { ledger, cleanup } = fixture();
481
- try {
482
- ledger.persistHandoff(
483
- "review",
484
- "wave",
485
- { tasks: "1", round: 1 },
486
- { findings: [{ severity: "blocker" }] },
487
- );
488
- // rounds 1 + 2 are recorded, but round 2's file is missing → the read is null, never a throw
489
- ledger.recordRound("1", "review");
490
- ledger.recordRound("1", "review");
491
- expect(ledger.round("review", "wave", { tasks: "1" }, 2)).toBeNull();
492
- } finally {
493
- cleanup();
494
- }
495
- });
496
- });
497
-
498
- describe("review references — the refKind face (T25 · P5)", () => {
499
- it("the RefKind union carries the two review kinds (doc-revision · brief-revision) and the commit-bearing kinds stay retired", () => {
500
- // The type probe: the two review kinds ARE members (D30 — doc-revision is the
501
- // spec/plan line, brief-revision the wave line), and the retired commit kinds
502
- // are absent (the wave-atomic + no-commit-identity rulings — R5 · P7).
503
- const docMember: "doc-revision" extends RefKind ? true : false = true;
504
- const briefMember: "brief-revision" extends RefKind ? true : false = true;
505
- const noCommitSet: "commit-set-ledger" extends RefKind ? true : false = false;
506
- const noCommitRange: "commit-range" extends RefKind ? true : false = false;
507
- const noGraphNode: "graph-node" extends RefKind ? true : false = false;
508
- expect(docMember).toBe(true);
509
- expect(briefMember).toBe(true);
510
- expect(noCommitSet).toBe(false);
511
- expect(noCommitRange).toBe(false);
512
- expect(noGraphNode).toBe(false);
513
- });
514
-
515
- it("the doc-revision two-layer binding — the doc path + the content-hash revision", () => {
516
- const { ledger, cleanup } = fixture();
517
- try {
518
- const refs = ledger.refs();
519
- const docRef = refs.docRevision("docs/kairos/specs/x-design.md", "revision one");
520
- expect(docRef.kind).toBe("doc-revision");
521
- expect(docRef.doc).toBe("docs/kairos/specs/x-design.md");
522
- // the doc-revision content hash stays a full sha1 hex — a non-ref digest,
523
- // unsliced (a bare 8-char digest slice would narrow the bind basis to
524
- // birthday-collision range)
525
- expect(docRef.doc_hash).toMatch(/^[0-9a-f]{40}$/);
526
- // the same content hashes the same revision — the two-layer convergence
527
- const docRefAgain = refs.docRevision("docs/kairos/specs/x-design.md", "revision one");
528
- expect(docRefAgain.doc_hash).toBe(docRef.doc_hash);
529
- // a different revision hashes differently — the revision layer is content-bound
530
- const edited = refs.docRevision("docs/kairos/specs/x-design.md", "revision two");
531
- expect(edited.doc_hash).not.toBe(docRef.doc_hash);
532
- } finally {
533
- cleanup();
534
- }
535
- });
536
-
537
- it("the same-ref ruling — the SAME doc revision is the same ref, a different doc/revision is not", () => {
538
- const { ledger, cleanup } = fixture();
539
- try {
540
- const refs = ledger.refs();
541
- const docRef = refs.docRevision("docs/kairos/specs/x-design.md", "revision one");
542
- // the identical ref (same doc + same hash) is the SAME ref
543
- const duplicate = refs.docRevision("docs/kairos/specs/x-design.md", "revision one");
544
- expect(refs.sameRef(docRef, duplicate)).toBe(true);
545
- // a different revision of the same doc is NOT the same ref
546
- const edited = refs.docRevision("docs/kairos/specs/x-design.md", "revision two");
547
- expect(refs.sameRef(docRef, edited)).toBe(false);
548
- // a different doc is never the same ref
549
- const otherDoc = refs.docRevision("docs/kairos/specs/y-design.md", "revision one");
550
- expect(refs.sameRef(docRef, otherDoc)).toBe(false);
551
- } finally {
552
- cleanup();
553
- }
554
- });
555
-
556
- it("the cross-kind ruling — a doc-revision and a brief-revision are never the same ref", () => {
557
- const { ledger, cleanup } = fixture();
558
- try {
559
- const refs = ledger.refs();
560
- const docRef = refs.docRevision("docs/kairos/plans/x-p3.md", "the plan body");
561
- // a brief-revision is a distinct ref KIND — the wave line's identity is never
562
- // the doc line's, even when the plan path layer and the hash layer coincide
563
- const briefRef = refs.briefRevision("docs/kairos/plans/x-p3.md", "the plan body");
564
- expect(briefRef.kind).toBe("brief-revision");
565
- expect(refs.sameRef(docRef, briefRef)).toBe(false);
566
- expect(refs.sameRef(briefRef, docRef)).toBe(false);
567
- // the same-kind brief-revision is still the same ref (the guard is the kind,
568
- // not a blanket refusal)
569
- const briefRefAgain = refs.briefRevision("docs/kairos/plans/x-p3.md", "the plan body");
570
- expect(refs.sameRef(briefRef, briefRefAgain)).toBe(true);
571
- } finally {
572
- cleanup();
573
- }
574
- });
575
- });
576
-
577
- describe("the T7 doc-line identity record — reviewedDocRevision (the reopen-compare basis)", () => {
578
- it("records + reads the reviewed doc revision on the doc line's progress row", () => {
579
- const { ledger, workspace, cleanup } = fixture();
580
- try {
581
- const doc = "docs/kairos/specs/x-design.md";
582
- const revision = ledger.refs().docRevision(doc, "revision one");
583
- expect(ledger.reviewedDocRevisionOf(doc)).toBeNull();
584
- ledger.recordReviewedRevision(doc, revision);
585
- expect(ledger.reviewedDocRevisionOf(doc)).toEqual(revision);
586
- // a fresh ledger over the same workspace reads the on-disk record back
587
- const reload = new Ledger(workspace, new ConfigLoader());
588
- expect(reload.reviewedDocRevisionOf(doc)).toEqual(revision);
589
- expect(reload.reviewedDocRevisionOf("docs/other.md")).toBeNull();
590
- } finally {
591
- cleanup();
592
- }
593
- });
594
-
595
- it("a reviewed doc revision RE-records on drift — the reopen's new identity basis", () => {
596
- const { ledger, cleanup } = fixture();
597
- try {
598
- const doc = "docs/kairos/plans/x-p3.md";
599
- const first = ledger.refs().docRevision(doc, "v1.0 body");
600
- const second = ledger.refs().docRevision(doc, "v1.1 body");
601
- ledger.recordReviewedRevision(doc, first);
602
- expect(ledger.reviewedDocRevisionOf(doc)).toEqual(first);
603
- // a later review round records its own revision — the line gate compares the
604
- // target against the LATEST reviewed identity
605
- ledger.recordReviewedRevision(doc, second);
606
- expect(ledger.reviewedDocRevisionOf(doc)).toEqual(second);
607
- } finally {
608
- cleanup();
609
- }
610
- });
611
-
612
- it("docLineVerdict — the shared identity comparison: same vs drift vs the null faces", () => {
613
- const { ledger, workspace, cleanup } = fixture();
614
- try {
615
- const doc = path.join(workspace.path, "docs", "x-p1.md");
616
- mkdirSync(path.dirname(doc), { recursive: true });
617
- writeFileSync(doc, "v1.0 body", "utf8");
618
- // an absent reviewed identity → null (the legacy closed face — no comparison)
619
- expect(ledger.docLineVerdict("1", doc)).toBeNull();
620
- ledger.recordReviewedRevision("1", ledger.refs().docRevision(doc, "v1.0 body"));
621
- // the recorded identity matches the current doc → "same" (the revision-aware BLOCK)
622
- expect(ledger.docLineVerdict("1", doc)).toBe("same");
623
- // the doc moved past the reviewed identity → "drift" (the line reopens)
624
- writeFileSync(doc, "v1.1 body", "utf8");
625
- expect(ledger.docLineVerdict("1", doc)).toBe("drift");
626
- // an unreadable doc → null (only present facts land — no invented identity)
627
- rmSync(doc);
628
- expect(ledger.docLineVerdict("1", doc)).toBeNull();
629
- } finally {
630
- cleanup();
631
- }
632
- });
633
- });
634
-
635
- describe("the review gate — the D28 phantom-pending-fix suppression", () => {
636
- it("a drift-voided review-1 (fix cycle 2) is NOT a pending fix — the identity membership, never a count", () => {
637
- const { ledger, workspace, cleanup } = fixture();
638
- try {
639
- const doc = path.join(workspace.path, "docs", "x-spec.md");
640
- mkdirSync(path.dirname(doc), { recursive: true });
641
- writeFileSync(doc, "the reviewed body", "utf8");
642
- // the drift-voided review-1 shape: review cycles [1, 2] with the fix at cycle 2.
643
- // A `fixes(1) < reviews(2)` count comparison reads a phantom pending fix and
644
- // re-opens the line forever; the identity membership (2 ∈ {2}) suppresses it.
645
- const data = ledger.readProgress() ?? ledger.emptyProgress();
646
- data.waves.push({ wave: "spec", rounds: { review: [1, 2], fix: [2] } });
647
- ledger.writeProgress(data);
648
- ledger.recordReviewedRevision("spec", ledger.refs().docRevision(doc, "the reviewed body"));
649
- const verdict = ledger.reviewGate("spec", doc, "spec");
650
- // the unchanged doc stays "same" with NO pending fix (the fix cycle 2 landed)
651
- expect(verdict.kind).toBe("same");
652
- if (verdict.kind === "same") expect(verdict.pending).toBe(false);
653
- } finally {
654
- cleanup();
655
- }
656
- });
657
-
658
- it("a review with no fix yet IS the pending face — the review's own fix is outstanding", () => {
659
- const { ledger, workspace, cleanup } = fixture();
660
- try {
661
- const doc = path.join(workspace.path, "docs", "y-spec.md");
662
- mkdirSync(path.dirname(doc), { recursive: true });
663
- writeFileSync(doc, "the reviewed body", "utf8");
664
- const data = ledger.readProgress() ?? ledger.emptyProgress();
665
- data.waves.push({ wave: "spec", rounds: { review: [1] } });
666
- ledger.writeProgress(data);
667
- ledger.recordReviewedRevision("spec", ledger.refs().docRevision(doc, "the reviewed body"));
668
- // the review round carries a blocker (non-APPROVED) → the fix awaits
669
- ledger.persistHandoff(
670
- "review",
671
- "spec",
672
- { round: 1 },
673
- { findings: [{ severity: "blocker", summary: "defect" }] },
674
- );
675
- const verdict = ledger.reviewGate("spec", doc, "spec");
676
- expect(verdict.kind).toBe("same");
677
- if (verdict.kind === "same") expect(verdict.pending).toBe(true);
678
- } finally {
679
- cleanup();
680
- }
681
- });
682
- });
683
-
684
- describe("lineClosed — the single line-closure judge (the board + closedWaves core)", () => {
685
- /** Seed a line row's raw `rounds` plane on the fixture's `test-slug` workspace. */
686
- const seedRow = (ledger: Ledger, key: string, rounds: Record<string, number[]>): void => {
687
- const data = ledger.readProgress() ?? ledger.emptyProgress();
688
- data.waves.push({ wave: key, rounds });
689
- ledger.writeProgress(data);
690
- };
691
-
692
- it("a skipped-cycle fix (`{review:[1,2], fix:[2]}`) is CLOSED — the identity read, never a count", () => {
693
- const { ledger, cleanup } = fixture();
694
- try {
695
- // The drift-voided review-1 shape: the first fix is cycle 2 (fix-K ⟷ review-K).
696
- // A count-based judge computes `fixes(1)`, reads the nonexistent fix cycle 1 and
697
- // reads the line OPEN; the identity judge reads the fix at its own cycle 2.
698
- seedRow(ledger, "plan", { review: [1, 2], fix: [2] });
699
- const params = { round: 2 };
700
- ledger.persistHandoff("review", "plan", params, { findings: [] });
701
- // the docs-fix face is a findings carrier (fix.plan schema) — an empty rollup is APPROVED
702
- ledger.persistHandoff("fix", "plan", params, { findings: [] });
703
-
704
- expect(ledger.lineClosed("plan", "plan")).toBe(true);
705
- } finally {
706
- cleanup();
707
- }
708
- });
709
-
710
- it("a line whose latest fix round carries blockers stays OPEN — the C5 route, not the mere presence", () => {
711
- const { ledger, cleanup } = fixture();
712
- try {
713
- seedRow(ledger, "plan", { review: [1, 2], fix: [2] });
714
- const params = { round: 2 };
715
- // the fix's source review carries a blocker → the C5 route is a re-review, not closure
716
- ledger.persistHandoff("review", "plan", params, {
717
- findings: [{ severity: "blocker", summary: "survives" }],
718
- });
719
- ledger.persistHandoff("fix", "plan", params, { findings: [] });
720
-
721
- expect(ledger.lineClosed("plan", "plan")).toBe(false);
722
- } finally {
723
- cleanup();
724
- }
725
- });
726
-
727
- it("a line with no review round yet is OPEN — an implement-only row never closes", () => {
728
- const { ledger, cleanup } = fixture();
729
- try {
730
- seedRow(ledger, "plan", { implement: [1] });
731
- expect(ledger.lineClosed("plan", "plan")).toBe(false);
732
- } finally {
733
- cleanup();
734
- }
735
- });
736
-
737
- it("an absent row (or absent progress) is OPEN — present facts only", () => {
738
- const { ledger, cleanup } = fixture();
739
- try {
740
- expect(ledger.lineClosed("plan", "plan")).toBe(false);
741
- } finally {
742
- cleanup();
743
- }
744
- });
745
- });