@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,49 +0,0 @@
1
- // packages/cdd-engine/src-next/session/__tests__/wave-line-phase.guard.test.ts
2
- // D26 — the wave-line phase single-source guard. The wave line's open phase has ONE
3
- // derivation (`Ledger#waveLinePhase`), read at judgment time by BOTH consumers: the
4
- // wave gate (`WaveGate` via `wave.ts #phaseOf`) and the lifecycle's frame frontier
5
- // (`run.ts #nextWavePhase`). A per-consumer copy of the derivation is a drift seed —
6
- // the gate could accept `review` while the frontier demands `fix`, deadlocking a
7
- // drift-reopened wave. This guard pins the delegation at the source: each consumer's
8
- // phase method BODY must return the ledger's single source directly, never a
9
- // re-derived local (a file-wide `waveLinePhase(` match would pass on any stray call
10
- // site — the pin anchors to the delegating method).
11
- //
12
- // Zero module-level bare functions — the read helper is `const` (the zero-`function`
13
- // declaration discipline).
14
-
15
- import { readFileSync } from "node:fs";
16
- import { fileURLToPath } from "node:url";
17
- import { describe, expect, it } from "vitest";
18
-
19
- /** The consumer faces whose phase derivation must delegate to the single source —
20
- * each pinned to its delegating METHOD body (signature … `return <ledger>.waveLinePhase(<arg>)`),
21
- * so a re-derived local inside the method fails the pin. */
22
- const CONSUMERS: Readonly<Record<string, { file: string; delegation: RegExp }>> = {
23
- "the wave gate (wave.ts #phaseOf)": {
24
- file: fileURLToPath(new URL("../wave.ts", import.meta.url)),
25
- delegation:
26
- /#phaseOf\(ledger: Ledger, waveKey: string\): DispatchPhase \| null \{\s*return ledger\.waveLinePhase\(waveKey\);/,
27
- },
28
- "the lifecycle frontier (run.ts #nextWavePhase)": {
29
- file: fileURLToPath(new URL("../run.ts", import.meta.url)),
30
- delegation:
31
- /#nextWavePhase\(key: string\): DispatchPhase \| null \{\s*return this\.#ledger\.waveLinePhase\(key\);/,
32
- },
33
- } as const;
34
-
35
- describe("D26 — the wave-line phase single source", () => {
36
- it("the wave gate and the lifecycle frontier both delegate to Ledger#waveLinePhase (zero per-consumer copy)", () => {
37
- for (const [label, { file, delegation }] of Object.entries(CONSUMERS)) {
38
- const source = readFileSync(file, "utf8");
39
- // the consumer's phase METHOD returns the ledger's single source directly —
40
- // anchored to the delegating body, not a file-wide call-site match
41
- expect(source, `${label} delegates to Ledger#waveLinePhase`).toMatch(delegation);
42
- }
43
- // the single source lives in the ledger — the delegation target exists
44
- const ledger = readFileSync(fileURLToPath(new URL("../ledger.ts", import.meta.url)), "utf8");
45
- expect(ledger, "Ledger#waveLinePhase is the declared single source").toMatch(
46
- /waveLinePhase\(waveKey: string\): RoundPhase \| null/,
47
- );
48
- });
49
- });
@@ -1,469 +0,0 @@
1
- // packages/cdd-engine/src-next/session/__tests__/wave.test.ts
2
- // T24 (v1.21) — WaveGate suite: the three-verb unified wave gate over a hermetic
3
- // ledger + task graph:
4
- // · the only read face — open = frontier(closedWaves()) (the C5 closure set);
5
- // · the split/subset BLOCK — a `--tasks` set that splits or mismatches the derived
6
- // wave (implement AND review AND fix share the same refusal);
7
- // · the wrong-phase BLOCK — the open wave is at a phase ≠ the requested verb;
8
- // · (v1.28) the phase read is WAVE-keyed — one ledger row per wave, every member
9
- // shares the wave's phase (the multi-task regression: the per-task read missed
10
- // a `{wave:"1,2"}` row and froze every multi-task wave at "implement", blocking
11
- // review/fix forever — {16,22,24} exposed it);
12
- // · the approved verdict — requested == open at the verb's phase.
13
- // Fixtures are plan literals parsed through the plan parser + a hermetic temp
14
- // workspace (the pattern the run/ledger suites share).
15
-
16
- import { mkdtempSync, 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 { PlanDocType } from "../../contract/doc.ts";
21
- import { Words } from "../../face/words.ts";
22
- import { ConfigLoader } from "../../infra/config.ts";
23
- import { Workspace, WorkspaceRoot } from "../../infra/workspace.ts";
24
- import { TaskGraph } from "../graph.ts";
25
- import { Ledger } from "../ledger.ts";
26
- import { WaveGate } from "../wave.ts";
27
-
28
- /** A hermetic ledger fixture — a fresh temp workspace (the run tests' pattern).
29
- * `repo` exposes the temp root so the T11 plan-drift cases can place a real plan
30
- * file the revision gate reads back. */
31
- const fixture = (): { ledger: Ledger; repo: string; cleanup: () => void } => {
32
- const repo = mkdtempSync(path.join(tmpdir(), "wave-"));
33
- const workspace = new Workspace(
34
- new WorkspaceRoot(path.join(repo, ".kairos", "cdd"), "session"),
35
- "wave-slug",
36
- );
37
- return {
38
- ledger: new Ledger(workspace, new ConfigLoader()),
39
- repo,
40
- cleanup: () => rmSync(repo, { recursive: true, force: true }),
41
- };
42
- };
43
-
44
- /** A plan document over `### Task N:` blocks + `- **DependsOn**:` values. */
45
- const planDoc = (blocks: readonly (readonly string[])[]): string => {
46
- return [
47
- "# Test Plan",
48
- "**Spec:** [x-design.md](docs/kairos/specs/x-design.md)",
49
- "- **Parent program**: [x-overall.md v1.0](docs/kairos/specs/x-overall.md)",
50
- "",
51
- "## Constraints",
52
- "",
53
- "- delta",
54
- "",
55
- ...blocks.flat(),
56
- ].join("\n");
57
- };
58
-
59
- const task = (id: number, dependsOn: string): readonly string[] => {
60
- return [`### Task ${id}: task ${id}`, `- **DependsOn**: ${dependsOn}`];
61
- };
62
-
63
- /** Parse a fixture and build the TaskGraph — the gate's frontier source. */
64
- const graphOf = (blocks: readonly (readonly string[])[]): TaskGraph => {
65
- return new TaskGraph(new PlanDocType("plan").parse(planDoc(blocks).split("\n")));
66
- };
67
-
68
- const gate = new WaveGate();
69
- const words = new Words();
70
-
71
- /** A clean APPROVED review carrier — the C5 closure record for a task line. */
72
- const cleanReviewCarrier = (ledger: Ledger, tasks: string, round: number): void => {
73
- ledger.recordRound(tasks, "review");
74
- ledger.persistHandoff(
75
- "review",
76
- "wave",
77
- { tasks, round },
78
- { tasks: tasks.split(",").map(Number), phase: "review", findings: [] },
79
- );
80
- };
81
-
82
- /** An open wave's pending-fix state — the wave line at fix (implement + reviewed
83
- * into a blocker, fix awaiting): the T11 gate's baseline phase derivation. */
84
- const pendingFix = (ledger: Ledger, tasks: string, round: number): void => {
85
- ledger.recordRound(tasks, "implement");
86
- ledger.recordRound(tasks, "review");
87
- ledger.persistHandoff(
88
- "review",
89
- "wave",
90
- { tasks, round },
91
- {
92
- tasks: tasks.split(",").map(Number),
93
- phase: "review",
94
- findings: [{ severity: "blocker", lens: "plan", summary: "stale findings" }],
95
- },
96
- );
97
- };
98
-
99
- describe("WaveGate.vet — the split/subset BLOCK (three-verb shared)", () => {
100
- it("a `--tasks` splitting the derived wave BLOCKs — implement, review and fix alike", () => {
101
- const { ledger, cleanup } = fixture();
102
- try {
103
- const graph = graphOf([task(1, "none"), task(2, "1")]); // the open wave = {1}
104
- for (const verb of ["implement", "review", "fix"] as const) {
105
- const verdict = gate.vet(new Set([1, 2]), verb, graph, ledger, words);
106
- expect(verdict.ok).toBe(false);
107
- expect(verdict.reason).toBe("split");
108
- expect(verdict.open).toEqual([1]);
109
- expect(verdict.message).toContain("derived wave");
110
- }
111
- } finally {
112
- cleanup();
113
- }
114
- });
115
-
116
- it("a backend task request before its dependency closes BLOCKs (the wave still opens at the dep)", () => {
117
- const { ledger, cleanup } = fixture();
118
- try {
119
- const graph = graphOf([task(1, "none"), task(2, "1")]);
120
- const verdict = gate.vet(new Set([2]), "implement", graph, ledger, words);
121
- expect(verdict.ok).toBe(false);
122
- expect(verdict.reason).toBe("split");
123
- expect(verdict.message).toContain("(1)");
124
- } finally {
125
- cleanup();
126
- }
127
- });
128
- });
129
-
130
- describe("WaveGate.vet — the wrong-phase BLOCK", () => {
131
- it("an open wave at the review phase refuses an implement dispatch (run the review first)", () => {
132
- const { ledger, cleanup } = fixture();
133
- try {
134
- const graph = graphOf([task(1, "none")]);
135
- ledger.recordRound(1, "implement"); // task 1 implemented → its phase is review
136
- const verdict = gate.vet(new Set([1]), "implement", graph, ledger, words);
137
- expect(verdict.ok).toBe(false);
138
- expect(verdict.reason).toBe("wrong-phase");
139
- expect(verdict.message).toContain("at review");
140
- } finally {
141
- cleanup();
142
- }
143
- });
144
-
145
- it("a clean-closed wave refuses any further verb — the line sits in no open phase", () => {
146
- const { ledger, cleanup } = fixture();
147
- try {
148
- const graph = graphOf([task(1, "none")]);
149
- ledger.recordRound(1, "implement");
150
- cleanReviewCarrier(ledger, "1", 1); // review approved → task 1 closed
151
- // closedWaves now contains 1 → frontier over it is empty → the wave gate sees
152
- // an empty open wave; a requested {1} mismatches ({1} ≠ {}) → the split BLOCK.
153
- const verdict = gate.vet(new Set([1]), "review", graph, ledger, words);
154
- expect(verdict.ok).toBe(false);
155
- expect(verdict.reason).toBe("split");
156
- expect(verdict.open).toEqual([]);
157
- } finally {
158
- cleanup();
159
- }
160
- });
161
- });
162
-
163
- describe("WaveGate.vet — the open wave's phase is EXACTLY the requested verb", () => {
164
- it("an open wave at the review phase approves a review dispatch", () => {
165
- const { ledger, cleanup } = fixture();
166
- try {
167
- const graph = graphOf([task(1, "none")]);
168
- ledger.recordRound(1, "implement");
169
- const verdict = gate.vet(new Set([1]), "review", graph, ledger, words);
170
- expect(verdict.ok).toBe(true);
171
- expect(verdict.open).toEqual([1]);
172
- } finally {
173
- cleanup();
174
- }
175
- });
176
-
177
- it("an unimplemented root wave approves the implement dispatch", () => {
178
- const { ledger, cleanup } = fixture();
179
- try {
180
- const graph = graphOf([task(1, "none"), task(2, "none")]);
181
- const verdict = gate.vet(new Set([1, 2]), "implement", graph, ledger, words);
182
- expect(verdict.ok).toBe(true);
183
- expect(verdict.open).toEqual([1, 2]);
184
- } finally {
185
- cleanup();
186
- }
187
- });
188
- });
189
-
190
- describe("WaveGate.vet — the wave-unitary phase read (v1.28 regression)", () => {
191
- it("a multi-task wave's phase derives from ITS wave row — review after implement passes the gate", () => {
192
- const { ledger, cleanup } = fixture();
193
- try {
194
- const graph = graphOf([task(1, "none"), task(2, "none")]); // the open wave = {1,2}
195
- ledger.recordRound("1,2", "implement"); // the WAVE row — never per-member rows
196
- const verdict = gate.vet(new Set([1, 2]), "review", graph, ledger, words);
197
- expect(verdict.ok).toBe(true);
198
- expect(verdict.open).toEqual([1, 2]);
199
- // every member shares the wave's single phase (the {16,22,24} shape)
200
- expect(verdict.phases).toEqual([
201
- { task: 1, phase: "review" },
202
- { task: 2, phase: "review" },
203
- ]);
204
- } finally {
205
- cleanup();
206
- }
207
- });
208
-
209
- it("a multi-task wave at review refuses an implement dispatch (wrong-phase, not split)", () => {
210
- const { ledger, cleanup } = fixture();
211
- try {
212
- const graph = graphOf([task(1, "none"), task(2, "none")]);
213
- ledger.recordRound("1,2", "implement");
214
- const verdict = gate.vet(new Set([1, 2]), "implement", graph, ledger, words);
215
- expect(verdict.ok).toBe(false);
216
- expect(verdict.reason).toBe("wrong-phase");
217
- expect(verdict.message).toContain("at review");
218
- } finally {
219
- cleanup();
220
- }
221
- });
222
- });
223
-
224
- describe("ledger.closedWaves — the C5 closure single read face", () => {
225
- it("an implement-only task is never closed (implement rounds carry no closure verdict)", () => {
226
- const { ledger, cleanup } = fixture();
227
- try {
228
- ledger.recordRound(1, "implement");
229
- expect(ledger.closedWaves()).toEqual(new Set());
230
- } finally {
231
- cleanup();
232
- }
233
- });
234
-
235
- it("a clean review closes the task — the C5 route is the closure predicate", () => {
236
- const { ledger, cleanup } = fixture();
237
- try {
238
- ledger.recordRound(1, "implement");
239
- cleanReviewCarrier(ledger, "1", 1);
240
- expect(ledger.closedWaves()).toEqual(new Set([1]));
241
- } finally {
242
- cleanup();
243
- }
244
- });
245
-
246
- it("a review with blocker findings holds the task open (the fix awaits — not a closure)", () => {
247
- const { ledger, cleanup } = fixture();
248
- try {
249
- ledger.recordRound(1, "implement");
250
- ledger.persistHandoff(
251
- "review",
252
- "wave",
253
- { tasks: "1", round: 1 },
254
- { findings: [{ severity: "blocker", summary: "defect" }] },
255
- );
256
- ledger.recordRound(1, "review");
257
- expect(ledger.closedWaves()).toEqual(new Set());
258
- } finally {
259
- cleanup();
260
- }
261
- });
262
-
263
- it("a merged-wave row naturalizes through ITS OWN review/fix pair (never a per-member read)", () => {
264
- const { ledger, cleanup } = fixture();
265
- try {
266
- // The historical merged-wave row carries the review+fix pair — the pair's C5 route
267
- // decides both members, without per-member implement rows.
268
- ledger.recordRound("4,12", "review");
269
- ledger.persistHandoff(
270
- "review",
271
- "wave",
272
- { tasks: "4,12", round: 1 },
273
- { tasks: [4, 12], phase: "review", findings: [] },
274
- );
275
- expect(ledger.closedWaves()).toEqual(new Set([4, 12]));
276
- } finally {
277
- cleanup();
278
- }
279
- });
280
-
281
- it("a LEGACY fix carrier WITHOUT a status still closes the wave — absent status is not a fabricated failure", () => {
282
- const { ledger, cleanup } = fixture();
283
- try {
284
- // The regression pin: a work-face fix carrier written before the status field
285
- // existed holds no `status`. `conclusionOf("work", carrier)` returns undefined
286
- // (no conclusion declared), and the router treats undefined as NOT a failure —
287
- // so the fix round's clean source review closes the wave. A stricter
288
- // absent→BLOCKED reading would fabricate a failure and strand every such wave
289
- // open (the closedWaves regression this pin guards).
290
- ledger.recordRound("7,9", "implement");
291
- ledger.recordRound("7,9", "review");
292
- ledger.persistHandoff(
293
- "review",
294
- "wave",
295
- { tasks: "7,9", round: 1 },
296
- { tasks: [7, 9], phase: "review", findings: [{ severity: "nit", summary: "cosmetic" }] },
297
- );
298
- ledger.recordRound("7,9", "fix");
299
- // the legacy fix carrier — artifacts only, NO status key
300
- ledger.persistHandoff("fix", "wave", { tasks: "7,9", round: 1 }, { artifacts: {} });
301
- expect(ledger.closedWaves()).toEqual(new Set([7, 9]));
302
- } finally {
303
- cleanup();
304
- }
305
- });
306
-
307
- it("a re-review-closed wave (review=[1,2] · fix=[1]) is CLOSED — the latest recorded round wins", () => {
308
- const { ledger, cleanup } = fixture();
309
- try {
310
- // The regression pin (P8 {5,11}): review-1 raises a blocker → fix-1 carries the
311
- // source review's findings → re-review-2 approves clean. The latest recorded round
312
- // is review@2 (route `done`), NOT the stale fix@1 (route `review`). The prior judge
313
- // read the fix at `Math.min(latestFix, latestReview)` = min(1,2) = 1 → the stale
314
- // fix-1 → `review` → read the wave forever open at fix (the wave gate then refused
315
- // the next wave). The identity read (a fix at the latest review's cycle) fixes it.
316
- ledger.recordRound("5,11", "implement");
317
- ledger.persistHandoff(
318
- "review",
319
- "wave",
320
- { tasks: "5,11", round: 1 },
321
- { findings: [{ severity: "blocker", summary: "defect" }] },
322
- );
323
- ledger.recordRound("5,11", "review");
324
- ledger.recordRound("5,11", "fix");
325
- ledger.persistHandoff("fix", "wave", { tasks: "5,11", round: 1 }, { artifacts: {} });
326
- ledger.recordRound("5,11", "review", 2);
327
- ledger.persistHandoff(
328
- "review",
329
- "wave",
330
- { tasks: "5,11", round: 2 },
331
- { tasks: [5, 11], phase: "review", findings: [] },
332
- );
333
- expect(ledger.closedWaves()).toEqual(new Set([5, 11]));
334
- expect(ledger.waveLinePhase("5,11")).toBeNull();
335
- } finally {
336
- cleanup();
337
- }
338
- });
339
- });
340
-
341
- describe("WaveGate.vet — the brief-revision-aware pending-fix resolution (T11 · D16 · D30)", () => {
342
- it("a wave-backfill edit reopens the fix-pending wave at review — the reviewed BRIEF revision is the drift basis", () => {
343
- const { ledger, repo, cleanup } = fixture();
344
- try {
345
- const graph = graphOf([task(1, "none")]);
346
- const planPath = path.join(repo, "plan.md");
347
- writeFileSync(planPath, planDoc([task(1, "none")]));
348
- pendingFix(ledger, "1", 1);
349
- // the completed wave review bound the THEN-current BRIEF revision to the row
350
- // (run.ts bookkeep → Ledger#recordReviewedBrief — the D30 identity gate)
351
- ledger.recordReviewedBrief("1", planPath);
352
- // the wave's OWN task section moves mid-flight — the recorded brief now drifts
353
- // from the wave's current brief
354
- writeFileSync(planPath, planDoc([task(1, "none"), [" - extra step — checkable: green"]]));
355
- const verdict = gate.vet(new Set([1]), "review", graph, ledger, words);
356
- // the phase resolves at review — the drifted brief is re-reviewed on ITS
357
- // current text (the pending fix's findings reference the stale revision)
358
- expect(verdict.ok).toBe(true);
359
- expect(verdict.phases).toEqual([{ task: 1, phase: "review" }]);
360
- } finally {
361
- cleanup();
362
- }
363
- });
364
-
365
- it("an OUTSIDE-wave plan edit keeps the wave at fix — the append-only backfill no longer voids a reviewed wave (D30)", () => {
366
- const { ledger, repo, cleanup } = fixture();
367
- try {
368
- const graph = graphOf([task(1, "none"), task(2, "1")]);
369
- const planPath = path.join(repo, "plan.md");
370
- writeFileSync(planPath, planDoc([task(1, "none"), task(2, "1")]));
371
- pendingFix(ledger, "1", 1);
372
- ledger.recordReviewedBrief("1", planPath);
373
- // an append-only backfill adds a task OUTSIDE wave {1} — wave {1}'s brief
374
- // (Task 1 + Constraints) is byte-identical, so the pending fix survives
375
- writeFileSync(planPath, planDoc([task(1, "none"), task(2, "1"), task(3, "1,2")]));
376
- const verdict = gate.vet(new Set([1]), "review", graph, ledger, words);
377
- expect(verdict.ok).toBe(false);
378
- expect(verdict.reason).toBe("wrong-phase");
379
- expect(verdict.message).toContain("at fix");
380
- } finally {
381
- cleanup();
382
- }
383
- });
384
-
385
- it("the anti-spin pin — same brief revision + a pending fix stays at fix (Review Convergence unbroken)", () => {
386
- const { ledger, repo, cleanup } = fixture();
387
- try {
388
- const graph = graphOf([task(1, "none")]);
389
- const planPath = path.join(repo, "plan.md");
390
- writeFileSync(planPath, planDoc([task(1, "none")]));
391
- pendingFix(ledger, "1", 1);
392
- ledger.recordReviewedBrief("1", planPath);
393
- // the plan has NOT moved — the recorded brief revision still matches
394
- const verdict = gate.vet(new Set([1]), "review", graph, ledger, words);
395
- expect(verdict.ok).toBe(false);
396
- expect(verdict.reason).toBe("wrong-phase");
397
- expect(verdict.message).toContain("at fix");
398
- } finally {
399
- cleanup();
400
- }
401
- });
402
-
403
- it("the null legacy pin — a wave row with no reviewed-revision record keeps the round-count BLOCK (backward compatible)", () => {
404
- const { ledger, cleanup } = fixture();
405
- try {
406
- const graph = graphOf([task(1, "none")]);
407
- pendingFix(ledger, "1", 1); // no reviewedRevision on record — the legacy face
408
- const verdict = gate.vet(new Set([1]), "review", graph, ledger, words);
409
- expect(verdict.ok).toBe(false);
410
- expect(verdict.reason).toBe("wrong-phase");
411
- expect(verdict.message).toContain("at fix");
412
- } finally {
413
- cleanup();
414
- }
415
- });
416
- });
417
-
418
- describe("Ledger#waveLinePhase — the D28 phantom-pending-fix suppression", () => {
419
- it("a drift-voided review-1 with the fix at cycle 2 is NOT a phantom pending fix (identity, never a count)", () => {
420
- const { ledger, cleanup } = fixture();
421
- try {
422
- // The W10 scenario: review-1 was voided by drift, so the first landed fix is
423
- // cycle 2 (fix-K ⟷ review-K). The cycle set is review [1, 2] · fix [2] — the
424
- // fix's COUNT (1) trails the review count (2), which the retired
425
- // `fixes < reviews` comparison read as a phantom pending fix → the wave would
426
- // re-open at fix forever. The identity membership (2 ∈ {2}) suppresses it.
427
- ledger.recordRound("1", "implement");
428
- ledger.recordRound("1", "review");
429
- ledger.recordRound("1", "review");
430
- ledger.recordRound("1", "fix", 2);
431
- // review-2 is clean and fix-2 closed it — the wave line is closed, not pending
432
- ledger.persistHandoff(
433
- "review",
434
- "wave",
435
- { tasks: "1", round: 2 },
436
- { tasks: [1], phase: "review", findings: [] },
437
- );
438
- ledger.persistHandoff("fix", "wave", { tasks: "1", round: 2 }, { artifacts: {} });
439
- expect(ledger.roundRecorded("1", "fix", 2)).toBe(true);
440
- expect(ledger.roundRecorded("1", "fix", 1)).toBe(false); // cycle 1 never landed
441
- // the closed line derives no open phase — no phantom "fix"
442
- expect(ledger.waveLinePhase("1")).toBeNull();
443
- } finally {
444
- cleanup();
445
- }
446
- });
447
-
448
- it("a fix round that still routes review keeps the wave at review — the identity read never over-closes", () => {
449
- const { ledger, cleanup } = fixture();
450
- try {
451
- // the drift-voided shape again, but the source review-2 carries a blocker, so the
452
- // fix round's C5 route is a re-review — the wave legitimately stays at review
453
- ledger.recordRound("1", "implement");
454
- ledger.recordRound("1", "review");
455
- ledger.recordRound("1", "review");
456
- ledger.recordRound("1", "fix", 2);
457
- ledger.persistHandoff(
458
- "review",
459
- "wave",
460
- { tasks: "1", round: 2 },
461
- { tasks: [1], phase: "review", findings: [{ severity: "blocker", summary: "open" }] },
462
- );
463
- ledger.persistHandoff("fix", "wave", { tasks: "1", round: 2 }, { artifacts: {} });
464
- expect(ledger.waveLinePhase("1")).toBe("review");
465
- } finally {
466
- cleanup();
467
- }
468
- });
469
- });
@@ -1,110 +0,0 @@
1
- // packages/cdd-engine/src-next/session/faces.ts
2
- // T8 — the target-type faces data table (design spec §3.3: the parameterized single
3
- // lifecycle). The three old near-isomorphic lifecycles (task / branch / docs)
4
- // converge into ONE lifecycle class whose per-type variance lives in this table:
5
- // each target type (task | branch | spec | plan) carries its audit target, the
6
- // product face (the review-lead round mode) and the next-hop consumption semantics.
7
- // The lifecycle reads the row through the same class — a new target type is a table
8
- // row, never a lifecycle edit.
9
- //
10
- // Module-level exports are types / the table const — zero behavior-carrying bare
11
- // functions (the plan's zero-bare-function discipline).
12
-
13
- import type { RoundPhase } from "./ledger.ts";
14
-
15
- /** The target types the parameterized lifecycle serves (the CLI `--type` vocabulary).
16
- * `wave` (T26 · the wave-unitary model): the task-graph face whose dispatch unit
17
- * is the derived wave — the type name is the UNIT, not the graph's node granularity
18
- * (the audit source stays "task-graph" · the plan's task nodes keep the task name). */
19
- export type TargetType = "wave" | "branch" | "spec" | "plan";
20
-
21
- /** The dispatch phases a lifecycle drives — the round-carrier phase vocabulary,
22
- * single-typed against the ledger's RoundPhase (no second phase union). */
23
- export type DispatchPhase = RoundPhase;
24
-
25
- /** The review-lead round modes — the review-family increments whose rounds carry
26
- * the fix round's source number. */
27
- export type ReviewLead = "review" | "branch-review";
28
-
29
- /** The audit-target descriptor — how a face's lifecycle resolves the open item. */
30
- export type AuditFace =
31
- /** task: the open item resolves from the TaskGraph frontier (a task id). */
32
- | { kind: "task-graph" }
33
- /** branch: the open item is the branch line itself (the live tree — no diff range). */
34
- | { kind: "branch-tree" }
35
- /** spec/plan: the open item is the audit document path. */
36
- | { kind: "doc-path" };
37
-
38
- /** The target identity a dispatch-ready `next:` literal renders (v1.25 · P4.1 T4) —
39
- * the frame's OWN facts (verb + target-type + id), never a router judgment: the wave
40
- * task key · the branch line key · the doc path. The optional `plan` carries the
41
- * plan path the implement literal's required `--plan` fills (the wave/task-face
42
- * frame's only implement-consuming fact). */
43
- export interface RouteTarget {
44
- /** The target-type word of the literal (`wave` / `branch` / `spec` / `plan`). */
45
- type: TargetType;
46
- /** The target id — the wave key `"1,2"` · the branch line key `"branch"` · the doc path. */
47
- id: string;
48
- /** The plan path (the implement literal's required `--plan` arg) — present only
49
- * on the task face (the doc faces carry their own id path). */
50
- plan?: string;
51
- }
52
-
53
- /**
54
- * One row of the faces table — the parameterized lifecycle's per-type variance
55
- * (the design spec §3.3 divergence parameters: audit target / product face / next
56
- * semantics). The row is data the lifecycle consumes; a fourth target type lands
57
- * as a new row, never a lifecycle branch.
58
- */
59
- export interface TargetFace {
60
- /** The target-type identity (one row per CLI `--type` value). */
61
- type: TargetType;
62
- /** The audit target — how the open dispatch item resolves. */
63
- audit: AuditFace;
64
- /** The product face — the review-lead round mode the line's rounds count under.
65
- * The phase progression itself is the universal three-role shape (opening work →
66
- * review lead → fix → re-review) every type shares — the parameterized
67
- * lifecycle's variance is the audit descriptor + this mode + the next semantics,
68
- * never the phase order (design spec §3.3: the review/fix/implement process is
69
- * homogeneous). */
70
- product: {
71
- /** The review-lead round mode — the review-family increment whose count the
72
- * fix round sources its number from (branch runs branch-review; the others
73
- * review). */
74
- reviewLead: ReviewLead;
75
- };
76
- /** The next consumption semantics — how a C5 Route is consumed on this face. */
77
- nextSemantics: {
78
- /** Whether a `next-wave` route advances the task batch (task only — the
79
- * branch/spec/plan lines are single-target with an empty ready batch). */
80
- batch: boolean;
81
- };
82
- }
83
-
84
- /** The four target-type faces — one row per CLI `--type` value (the single table). */
85
- export const targetFaces: Record<TargetType, TargetFace> = {
86
- wave: {
87
- type: "wave",
88
- audit: { kind: "task-graph" },
89
- product: { reviewLead: "review" },
90
- nextSemantics: { batch: true },
91
- },
92
- branch: {
93
- type: "branch",
94
- audit: { kind: "branch-tree" },
95
- product: { reviewLead: "branch-review" },
96
- nextSemantics: { batch: false },
97
- },
98
- spec: {
99
- type: "spec",
100
- audit: { kind: "doc-path" },
101
- product: { reviewLead: "review" },
102
- nextSemantics: { batch: false },
103
- },
104
- plan: {
105
- type: "plan",
106
- audit: { kind: "doc-path" },
107
- product: { reviewLead: "review" },
108
- nextSemantics: { batch: false },
109
- },
110
- };