@oscaner-skills/cdd-engine 3.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 (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 +141 -0
  15. package/dist/face/cli.js +891 -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 +603 -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 +482 -0
  25. package/dist/face/words.js +220 -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 +441 -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,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,476 +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 (the
45
- * front-matter head the plan parser reads). */
46
- const planDoc = (blocks: readonly (readonly string[])[]): string => {
47
- return [
48
- "---",
49
- "title: Test Plan",
50
- "doc-type: plan",
51
- "version: v1.0",
52
- "date: 2026-10-09",
53
- "spec: docs/kairos/specs/x-design.md",
54
- "parent-program: docs/kairos/specs/x-overall.md",
55
- "parent-version: v1.0",
56
- "---",
57
- "",
58
- "## Constraints",
59
- "",
60
- "- delta",
61
- "",
62
- ...blocks.flat(),
63
- ].join("\n");
64
- };
65
-
66
- const task = (id: number, dependsOn: string): readonly string[] => {
67
- return [`### Task ${id}: task ${id}`, `- **DependsOn**: ${dependsOn}`];
68
- };
69
-
70
- /** Parse a fixture and build the TaskGraph — the gate's frontier source. */
71
- const graphOf = (blocks: readonly (readonly string[])[]): TaskGraph => {
72
- return new TaskGraph(new PlanDocType("plan").parse(planDoc(blocks).split("\n")));
73
- };
74
-
75
- const gate = new WaveGate();
76
- const words = new Words();
77
-
78
- /** A clean APPROVED review carrier — the C5 closure record for a task line. */
79
- const cleanReviewCarrier = (ledger: Ledger, tasks: string, round: number): void => {
80
- ledger.recordRound(tasks, "review");
81
- ledger.persistHandoff(
82
- "review",
83
- "wave",
84
- { tasks, round },
85
- { tasks: tasks.split(",").map(Number), phase: "review", findings: [] },
86
- );
87
- };
88
-
89
- /** An open wave's pending-fix state — the wave line at fix (implement + reviewed
90
- * into a blocker, fix awaiting): the T11 gate's baseline phase derivation. */
91
- const pendingFix = (ledger: Ledger, tasks: string, round: number): void => {
92
- ledger.recordRound(tasks, "implement");
93
- ledger.recordRound(tasks, "review");
94
- ledger.persistHandoff(
95
- "review",
96
- "wave",
97
- { tasks, round },
98
- {
99
- tasks: tasks.split(",").map(Number),
100
- phase: "review",
101
- findings: [{ severity: "blocker", lens: "plan", summary: "stale findings" }],
102
- },
103
- );
104
- };
105
-
106
- describe("WaveGate.vet — the split/subset BLOCK (three-verb shared)", () => {
107
- it("a `--tasks` splitting the derived wave BLOCKs — implement, review and fix alike", () => {
108
- const { ledger, cleanup } = fixture();
109
- try {
110
- const graph = graphOf([task(1, "none"), task(2, "1")]); // the open wave = {1}
111
- for (const verb of ["implement", "review", "fix"] as const) {
112
- const verdict = gate.vet(new Set([1, 2]), verb, graph, ledger, words);
113
- expect(verdict.ok).toBe(false);
114
- expect(verdict.reason).toBe("split");
115
- expect(verdict.open).toEqual([1]);
116
- expect(verdict.message).toContain("derived wave");
117
- }
118
- } finally {
119
- cleanup();
120
- }
121
- });
122
-
123
- it("a backend task request before its dependency closes BLOCKs (the wave still opens at the dep)", () => {
124
- const { ledger, cleanup } = fixture();
125
- try {
126
- const graph = graphOf([task(1, "none"), task(2, "1")]);
127
- const verdict = gate.vet(new Set([2]), "implement", graph, ledger, words);
128
- expect(verdict.ok).toBe(false);
129
- expect(verdict.reason).toBe("split");
130
- expect(verdict.message).toContain("(1)");
131
- } finally {
132
- cleanup();
133
- }
134
- });
135
- });
136
-
137
- describe("WaveGate.vet — the wrong-phase BLOCK", () => {
138
- it("an open wave at the review phase refuses an implement dispatch (run the review first)", () => {
139
- const { ledger, cleanup } = fixture();
140
- try {
141
- const graph = graphOf([task(1, "none")]);
142
- ledger.recordRound(1, "implement"); // task 1 implemented → its phase is review
143
- const verdict = gate.vet(new Set([1]), "implement", graph, ledger, words);
144
- expect(verdict.ok).toBe(false);
145
- expect(verdict.reason).toBe("wrong-phase");
146
- expect(verdict.message).toContain("at review");
147
- } finally {
148
- cleanup();
149
- }
150
- });
151
-
152
- it("a clean-closed wave refuses any further verb — the line sits in no open phase", () => {
153
- const { ledger, cleanup } = fixture();
154
- try {
155
- const graph = graphOf([task(1, "none")]);
156
- ledger.recordRound(1, "implement");
157
- cleanReviewCarrier(ledger, "1", 1); // review approved → task 1 closed
158
- // closedWaves now contains 1 → frontier over it is empty → the wave gate sees
159
- // an empty open wave; a requested {1} mismatches ({1} ≠ {}) → the split BLOCK.
160
- const verdict = gate.vet(new Set([1]), "review", graph, ledger, words);
161
- expect(verdict.ok).toBe(false);
162
- expect(verdict.reason).toBe("split");
163
- expect(verdict.open).toEqual([]);
164
- } finally {
165
- cleanup();
166
- }
167
- });
168
- });
169
-
170
- describe("WaveGate.vet — the open wave's phase is EXACTLY the requested verb", () => {
171
- it("an open wave at the review phase approves a review dispatch", () => {
172
- const { ledger, cleanup } = fixture();
173
- try {
174
- const graph = graphOf([task(1, "none")]);
175
- ledger.recordRound(1, "implement");
176
- const verdict = gate.vet(new Set([1]), "review", graph, ledger, words);
177
- expect(verdict.ok).toBe(true);
178
- expect(verdict.open).toEqual([1]);
179
- } finally {
180
- cleanup();
181
- }
182
- });
183
-
184
- it("an unimplemented root wave approves the implement dispatch", () => {
185
- const { ledger, cleanup } = fixture();
186
- try {
187
- const graph = graphOf([task(1, "none"), task(2, "none")]);
188
- const verdict = gate.vet(new Set([1, 2]), "implement", graph, ledger, words);
189
- expect(verdict.ok).toBe(true);
190
- expect(verdict.open).toEqual([1, 2]);
191
- } finally {
192
- cleanup();
193
- }
194
- });
195
- });
196
-
197
- describe("WaveGate.vet — the wave-unitary phase read (v1.28 regression)", () => {
198
- it("a multi-task wave's phase derives from ITS wave row — review after implement passes the gate", () => {
199
- const { ledger, cleanup } = fixture();
200
- try {
201
- const graph = graphOf([task(1, "none"), task(2, "none")]); // the open wave = {1,2}
202
- ledger.recordRound("1,2", "implement"); // the WAVE row — never per-member rows
203
- const verdict = gate.vet(new Set([1, 2]), "review", graph, ledger, words);
204
- expect(verdict.ok).toBe(true);
205
- expect(verdict.open).toEqual([1, 2]);
206
- // every member shares the wave's single phase (the {16,22,24} shape)
207
- expect(verdict.phases).toEqual([
208
- { task: 1, phase: "review" },
209
- { task: 2, phase: "review" },
210
- ]);
211
- } finally {
212
- cleanup();
213
- }
214
- });
215
-
216
- it("a multi-task wave at review refuses an implement dispatch (wrong-phase, not split)", () => {
217
- const { ledger, cleanup } = fixture();
218
- try {
219
- const graph = graphOf([task(1, "none"), task(2, "none")]);
220
- ledger.recordRound("1,2", "implement");
221
- const verdict = gate.vet(new Set([1, 2]), "implement", graph, ledger, words);
222
- expect(verdict.ok).toBe(false);
223
- expect(verdict.reason).toBe("wrong-phase");
224
- expect(verdict.message).toContain("at review");
225
- } finally {
226
- cleanup();
227
- }
228
- });
229
- });
230
-
231
- describe("ledger.closedWaves — the C5 closure single read face", () => {
232
- it("an implement-only task is never closed (implement rounds carry no closure verdict)", () => {
233
- const { ledger, cleanup } = fixture();
234
- try {
235
- ledger.recordRound(1, "implement");
236
- expect(ledger.closedWaves()).toEqual(new Set());
237
- } finally {
238
- cleanup();
239
- }
240
- });
241
-
242
- it("a clean review closes the task — the C5 route is the closure predicate", () => {
243
- const { ledger, cleanup } = fixture();
244
- try {
245
- ledger.recordRound(1, "implement");
246
- cleanReviewCarrier(ledger, "1", 1);
247
- expect(ledger.closedWaves()).toEqual(new Set([1]));
248
- } finally {
249
- cleanup();
250
- }
251
- });
252
-
253
- it("a review with blocker findings holds the task open (the fix awaits — not a closure)", () => {
254
- const { ledger, cleanup } = fixture();
255
- try {
256
- ledger.recordRound(1, "implement");
257
- ledger.persistHandoff(
258
- "review",
259
- "wave",
260
- { tasks: "1", round: 1 },
261
- { findings: [{ severity: "blocker", summary: "defect" }] },
262
- );
263
- ledger.recordRound(1, "review");
264
- expect(ledger.closedWaves()).toEqual(new Set());
265
- } finally {
266
- cleanup();
267
- }
268
- });
269
-
270
- it("a merged-wave row naturalizes through ITS OWN review/fix pair (never a per-member read)", () => {
271
- const { ledger, cleanup } = fixture();
272
- try {
273
- // The historical merged-wave row carries the review+fix pair — the pair's C5 route
274
- // decides both members, without per-member implement rows.
275
- ledger.recordRound("4,12", "review");
276
- ledger.persistHandoff(
277
- "review",
278
- "wave",
279
- { tasks: "4,12", round: 1 },
280
- { tasks: [4, 12], phase: "review", findings: [] },
281
- );
282
- expect(ledger.closedWaves()).toEqual(new Set([4, 12]));
283
- } finally {
284
- cleanup();
285
- }
286
- });
287
-
288
- it("a LEGACY fix carrier WITHOUT a status still closes the wave — absent status is not a fabricated failure", () => {
289
- const { ledger, cleanup } = fixture();
290
- try {
291
- // The regression pin: a work-face fix carrier written before the status field
292
- // existed holds no `status`. `conclusionOf("work", carrier)` returns undefined
293
- // (no conclusion declared), and the router treats undefined as NOT a failure —
294
- // so the fix round's clean source review closes the wave. A stricter
295
- // absent→BLOCKED reading would fabricate a failure and strand every such wave
296
- // open (the closedWaves regression this pin guards).
297
- ledger.recordRound("7,9", "implement");
298
- ledger.recordRound("7,9", "review");
299
- ledger.persistHandoff(
300
- "review",
301
- "wave",
302
- { tasks: "7,9", round: 1 },
303
- { tasks: [7, 9], phase: "review", findings: [{ severity: "nit", summary: "cosmetic" }] },
304
- );
305
- ledger.recordRound("7,9", "fix");
306
- // the legacy fix carrier — artifacts only, NO status key
307
- ledger.persistHandoff("fix", "wave", { tasks: "7,9", round: 1 }, { artifacts: {} });
308
- expect(ledger.closedWaves()).toEqual(new Set([7, 9]));
309
- } finally {
310
- cleanup();
311
- }
312
- });
313
-
314
- it("a re-review-closed wave (review=[1,2] · fix=[1]) is CLOSED — the latest recorded round wins", () => {
315
- const { ledger, cleanup } = fixture();
316
- try {
317
- // The regression pin (P8 {5,11}): review-1 raises a blocker → fix-1 carries the
318
- // source review's findings → re-review-2 approves clean. The latest recorded round
319
- // is review@2 (route `done`), NOT the stale fix@1 (route `review`). The prior judge
320
- // read the fix at `Math.min(latestFix, latestReview)` = min(1,2) = 1 → the stale
321
- // fix-1 → `review` → read the wave forever open at fix (the wave gate then refused
322
- // the next wave). The identity read (a fix at the latest review's cycle) fixes it.
323
- ledger.recordRound("5,11", "implement");
324
- ledger.persistHandoff(
325
- "review",
326
- "wave",
327
- { tasks: "5,11", round: 1 },
328
- { findings: [{ severity: "blocker", summary: "defect" }] },
329
- );
330
- ledger.recordRound("5,11", "review");
331
- ledger.recordRound("5,11", "fix");
332
- ledger.persistHandoff("fix", "wave", { tasks: "5,11", round: 1 }, { artifacts: {} });
333
- ledger.recordRound("5,11", "review", 2);
334
- ledger.persistHandoff(
335
- "review",
336
- "wave",
337
- { tasks: "5,11", round: 2 },
338
- { tasks: [5, 11], phase: "review", findings: [] },
339
- );
340
- expect(ledger.closedWaves()).toEqual(new Set([5, 11]));
341
- expect(ledger.waveLinePhase("5,11")).toBeNull();
342
- } finally {
343
- cleanup();
344
- }
345
- });
346
- });
347
-
348
- describe("WaveGate.vet — the brief-revision-aware pending-fix resolution (T11 · D16 · D30)", () => {
349
- it("a wave-backfill edit reopens the fix-pending wave at review — the reviewed BRIEF revision is the drift basis", () => {
350
- const { ledger, repo, cleanup } = fixture();
351
- try {
352
- const graph = graphOf([task(1, "none")]);
353
- const planPath = path.join(repo, "plan.md");
354
- writeFileSync(planPath, planDoc([task(1, "none")]));
355
- pendingFix(ledger, "1", 1);
356
- // the completed wave review bound the THEN-current BRIEF revision to the row
357
- // (run.ts bookkeep → Ledger#recordReviewedBrief — the D30 identity gate)
358
- ledger.recordReviewedBrief("1", planPath);
359
- // the wave's OWN task section moves mid-flight — the recorded brief now drifts
360
- // from the wave's current brief
361
- writeFileSync(planPath, planDoc([task(1, "none"), [" - extra step — checkable: green"]]));
362
- const verdict = gate.vet(new Set([1]), "review", graph, ledger, words);
363
- // the phase resolves at review — the drifted brief is re-reviewed on ITS
364
- // current text (the pending fix's findings reference the stale revision)
365
- expect(verdict.ok).toBe(true);
366
- expect(verdict.phases).toEqual([{ task: 1, phase: "review" }]);
367
- } finally {
368
- cleanup();
369
- }
370
- });
371
-
372
- it("an OUTSIDE-wave plan edit keeps the wave at fix — the append-only backfill no longer voids a reviewed wave (D30)", () => {
373
- const { ledger, repo, cleanup } = fixture();
374
- try {
375
- const graph = graphOf([task(1, "none"), task(2, "1")]);
376
- const planPath = path.join(repo, "plan.md");
377
- writeFileSync(planPath, planDoc([task(1, "none"), task(2, "1")]));
378
- pendingFix(ledger, "1", 1);
379
- ledger.recordReviewedBrief("1", planPath);
380
- // an append-only backfill adds a task OUTSIDE wave {1} — wave {1}'s brief
381
- // (Task 1 + Constraints) is byte-identical, so the pending fix survives
382
- writeFileSync(planPath, planDoc([task(1, "none"), task(2, "1"), task(3, "1,2")]));
383
- const verdict = gate.vet(new Set([1]), "review", graph, ledger, words);
384
- expect(verdict.ok).toBe(false);
385
- expect(verdict.reason).toBe("wrong-phase");
386
- expect(verdict.message).toContain("at fix");
387
- } finally {
388
- cleanup();
389
- }
390
- });
391
-
392
- it("the anti-spin pin — same brief revision + a pending fix stays at fix (Review Convergence unbroken)", () => {
393
- const { ledger, repo, cleanup } = fixture();
394
- try {
395
- const graph = graphOf([task(1, "none")]);
396
- const planPath = path.join(repo, "plan.md");
397
- writeFileSync(planPath, planDoc([task(1, "none")]));
398
- pendingFix(ledger, "1", 1);
399
- ledger.recordReviewedBrief("1", planPath);
400
- // the plan has NOT moved — the recorded brief revision still matches
401
- const verdict = gate.vet(new Set([1]), "review", graph, ledger, words);
402
- expect(verdict.ok).toBe(false);
403
- expect(verdict.reason).toBe("wrong-phase");
404
- expect(verdict.message).toContain("at fix");
405
- } finally {
406
- cleanup();
407
- }
408
- });
409
-
410
- it("the null legacy pin — a wave row with no reviewed-revision record keeps the round-count BLOCK (backward compatible)", () => {
411
- const { ledger, cleanup } = fixture();
412
- try {
413
- const graph = graphOf([task(1, "none")]);
414
- pendingFix(ledger, "1", 1); // no reviewedRevision on record — the legacy face
415
- const verdict = gate.vet(new Set([1]), "review", graph, ledger, words);
416
- expect(verdict.ok).toBe(false);
417
- expect(verdict.reason).toBe("wrong-phase");
418
- expect(verdict.message).toContain("at fix");
419
- } finally {
420
- cleanup();
421
- }
422
- });
423
- });
424
-
425
- describe("Ledger#waveLinePhase — the D28 phantom-pending-fix suppression", () => {
426
- it("a drift-voided review-1 with the fix at cycle 2 is NOT a phantom pending fix (identity, never a count)", () => {
427
- const { ledger, cleanup } = fixture();
428
- try {
429
- // The W10 scenario: review-1 was voided by drift, so the first landed fix is
430
- // cycle 2 (fix-K ⟷ review-K). The cycle set is review [1, 2] · fix [2] — the
431
- // fix's COUNT (1) trails the review count (2), which the retired
432
- // `fixes < reviews` comparison read as a phantom pending fix → the wave would
433
- // re-open at fix forever. The identity membership (2 ∈ {2}) suppresses it.
434
- ledger.recordRound("1", "implement");
435
- ledger.recordRound("1", "review");
436
- ledger.recordRound("1", "review");
437
- ledger.recordRound("1", "fix", 2);
438
- // review-2 is clean and fix-2 closed it — the wave line is closed, not pending
439
- ledger.persistHandoff(
440
- "review",
441
- "wave",
442
- { tasks: "1", round: 2 },
443
- { tasks: [1], phase: "review", findings: [] },
444
- );
445
- ledger.persistHandoff("fix", "wave", { tasks: "1", round: 2 }, { artifacts: {} });
446
- expect(ledger.roundRecorded("1", "fix", 2)).toBe(true);
447
- expect(ledger.roundRecorded("1", "fix", 1)).toBe(false); // cycle 1 never landed
448
- // the closed line derives no open phase — no phantom "fix"
449
- expect(ledger.waveLinePhase("1")).toBeNull();
450
- } finally {
451
- cleanup();
452
- }
453
- });
454
-
455
- it("a fix round that still routes review keeps the wave at review — the identity read never over-closes", () => {
456
- const { ledger, cleanup } = fixture();
457
- try {
458
- // the drift-voided shape again, but the source review-2 carries a blocker, so the
459
- // fix round's C5 route is a re-review — the wave legitimately stays at review
460
- ledger.recordRound("1", "implement");
461
- ledger.recordRound("1", "review");
462
- ledger.recordRound("1", "review");
463
- ledger.recordRound("1", "fix", 2);
464
- ledger.persistHandoff(
465
- "review",
466
- "wave",
467
- { tasks: "1", round: 2 },
468
- { tasks: [1], phase: "review", findings: [{ severity: "blocker", summary: "open" }] },
469
- );
470
- ledger.persistHandoff("fix", "wave", { tasks: "1", round: 2 }, { artifacts: {} });
471
- expect(ledger.waveLinePhase("1")).toBe("review");
472
- } finally {
473
- cleanup();
474
- }
475
- });
476
- });
@@ -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
- };