@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
@@ -0,0 +1,441 @@
1
+ // packages/cdd-engine/src-next/session/run.ts
2
+ // T8 — the parameterized single lifecycle (design spec §3.3): the three old
3
+ // near-isomorphic lifecycles converge into ONE class whose per-type variance is the
4
+ // faces table (faces.ts). advance() runs one dispatch step — one dispatch, one
5
+ // advance:
6
+ //
7
+ // frontier → dispatch → result → bookkeeping → next routing
8
+ //
9
+ // The lifecycle composes the T6 execution state (the frontier dynamic face + the
10
+ // done-set), the T7 NextStepRouter (the C5 next-generation single point) and the T9
11
+ // ledger (progress · handoff · round — the on-disk record of every round). The
12
+ // capsule interaction point (face/capsule — T10) is a seam: the CapsuleFace
13
+ // interface declared here is satisfied by T10's Capsule, and the lifecycle advances
14
+ // without a capsule (non-hard consumption — T8 builds no hard dependency toward
15
+ // T10); the attachCapsule seam only renders the step's round facts when a capsule is
16
+ // connected.
17
+ //
18
+ // Module-level exports are types / the class / one empty-state data const — zero
19
+ // behavior-carrying bare functions (the plan's zero-bare-function discipline).
20
+ import { readFileSync } from "node:fs";
21
+ import { Ledger, } from "./ledger.js";
22
+ import { NextStepRouter } from "./next.js";
23
+ /** The empty run state — a target line with no task frontier (branch/spec/plan):
24
+ * the frontier query faces are always empty (a single-target line never continues
25
+ * a batch) and markDone is a no-op. */
26
+ export const EMPTY_RUN_STATE = {
27
+ doneTasks: () => new Set(),
28
+ readyBatch: () => [],
29
+ frontier: () => [],
30
+ markDone: () => undefined,
31
+ };
32
+ /**
33
+ * Lifecycle — the parameterized single lifecycle over one target-type face. One
34
+ * instance drives one target line. advance() runs one dispatch step:
35
+ *
36
+ * frontier — resolve the open frame from the face's audit descriptor;
37
+ * dispatch — run the injected dispatch instruction, capture the outcome;
38
+ * bookkeep — persist the handoff carrier + record the progress round;
39
+ * close — the recorded round's C5 route is the single closure verdict: the
40
+ * lifecycle marks the task done when the route kind closes the line
41
+ * (terminal ⇔ route.kind ∈ {done, next-wave} — desync-proof, the
42
+ * router's point, never a folded table);
43
+ * route — the delivered C5 next-hop Route, re-judged with the closed task out
44
+ * of the ready batch (a closing review routes `done`, not a phantom
45
+ * next-wave of the just-closed task).
46
+ */
47
+ export class Lifecycle {
48
+ /** The target face this instance drives — the row of the faces table. */
49
+ #face;
50
+ /** The run state the lifecycle reads and marks. */
51
+ #state;
52
+ /** The session ledger — the round + progress single author. */
53
+ #ledger;
54
+ /** The C5 next router — the next-hop single point. */
55
+ #router;
56
+ /** The dispatch instruction — the round's actual work, injected. */
57
+ #dispatch;
58
+ /** The fixed audit target of a branch-tree / doc-path face (the task face
59
+ * resolves it from the frontier). */
60
+ #target;
61
+ /** The attached capsule face — null = the step advances output-less. */
62
+ #capsule;
63
+ /** The dispatch-entry pre-flight gate — null = unguarded (the seam-less callers
64
+ * keep their existing behavior). */
65
+ #preflight;
66
+ /** The workspace plan path — the `next:` implement literal's required `--plan`
67
+ * arg (P4.1 T4 — the task face's implement-consuming fact). */
68
+ #planPath;
69
+ constructor(opts) {
70
+ this.#face = opts.face;
71
+ this.#state = opts.state;
72
+ this.#ledger = opts.ledger;
73
+ this.#dispatch = opts.dispatch;
74
+ this.#router = opts.router ?? new NextStepRouter();
75
+ this.#target = opts.target ?? null;
76
+ this.#capsule = opts.capsule ?? null;
77
+ this.#preflight = opts.preflight ?? null;
78
+ this.#planPath = opts.planPath ?? null;
79
+ }
80
+ /** The face row this instance drives. */
81
+ face() {
82
+ return this.#face;
83
+ }
84
+ /** Attach the capsule face — the interaction point (T10's Capsule plugs in; null
85
+ * detaches and the step advances output-less). Returns this for chaining. */
86
+ attachCapsule(capsule) {
87
+ this.#capsule = capsule;
88
+ return this;
89
+ }
90
+ /** Peek the line's next open frame WITHOUT dispatching — the CLI's per-invocation
91
+ * cursor pre-checks the next step against the requested verb before it advances
92
+ * (a mismatch must not consume the round: advance() dispatches on entry — the
93
+ * {16,22,24} bug's loop reordered lookahead-after-dispatch and spent the next
94
+ * phase's round in the same invocation). Null = the run is exhausted / capped. */
95
+ peekNext() {
96
+ return this.#openFrame();
97
+ }
98
+ /** advance() — one dispatch step: frontier → pre-flight gate → dispatch → result →
99
+ * bookkeeping → next routing. Null when the line holds no open frame (the run is
100
+ * exhausted or a capped line defers to the user). A refused pre-flight gate blocks
101
+ * the dispatch (child zero) and returns the frame as a preflight-blocked step —
102
+ * neither persisted nor recorded (the frontier re-offers it: resume). */
103
+ async advance() {
104
+ const frame = this.#openFrame();
105
+ if (frame === null)
106
+ return null;
107
+ if (this.#preflight !== null) {
108
+ const verdict = this.#preflight.gate(frame);
109
+ if (verdict !== null && !verdict.ok) {
110
+ return {
111
+ frame,
112
+ round: this.#ledger.roundCount(frame.key, frame.phase),
113
+ route: null,
114
+ capsuleLines: [],
115
+ preflight: verdict,
116
+ };
117
+ }
118
+ }
119
+ const outcome = await this.#dispatch(frame);
120
+ const round = this.#bookkeep(frame, outcome);
121
+ // The closure verdict rides the recorded round's C5 route — mark the task done
122
+ // when the route kind says the line closed (the router's single point, never a
123
+ // folded copy of the closure table).
124
+ this.#markTerminal(frame, this.#routeNext(frame));
125
+ // The delivered route re-judges the batch AFTER the done-marking: a closing
126
+ // review empties the ready batch, so the step routes `done` (an exhausted run),
127
+ // not a phantom next-wave of the just-closed task.
128
+ const route = this.#routeNext(frame);
129
+ return {
130
+ frame,
131
+ round,
132
+ route,
133
+ capsuleLines: this.#capsuleLines(frame, outcome, route),
134
+ };
135
+ }
136
+ // -------------------------------------------------------------------------
137
+ // frontier — the open dispatch frame
138
+ // -------------------------------------------------------------------------
139
+ /** Resolve the line's next open frame — null when the line is exhausted. */
140
+ #openFrame() {
141
+ if (this.#face.audit.kind === "task-graph")
142
+ return this.#openWaveFrame();
143
+ const target = this.#target;
144
+ if (target === null)
145
+ return null; // a fixed-target face without its target holds
146
+ return this.#openLineFrame(target);
147
+ }
148
+ /** The task face's next open frame — THE OPEN WAVE as ONE dispatch step (the
149
+ * wave-unitary model · T26): the frontier's whole ready batch is the frame's
150
+ * target — one brief, one child, one commit, one round, one phase train. Null
151
+ * when the frontier holds no open wave. */
152
+ #openWaveFrame() {
153
+ const done = this.#state.doneTasks();
154
+ const ready = this.#state.frontier(done); // the open wave (the whole ready batch, ascending)
155
+ if (ready.length === 0)
156
+ return null;
157
+ const key = ready.join(",");
158
+ const phase = this.#nextWavePhase(key);
159
+ if (phase === null)
160
+ return null;
161
+ const target = { kind: "wave", tasks: ready };
162
+ const round = this.#roundFor(phase, key);
163
+ return {
164
+ type: "wave",
165
+ phase,
166
+ round,
167
+ target,
168
+ params: this.#paramsOf({ type: "wave", phase, target, round }),
169
+ key,
170
+ };
171
+ }
172
+ /** The next phase of one wave line — the SAME single derivation the wave gate reads
173
+ * (`Ledger#waveLinePhase` · D26: one fact, one place). The lifecycle's frame
174
+ * frontier and the three-verb WaveGate must agree on the open wave's phase, or a
175
+ * drift-reopened wave deadlocks (the gate accepts `review` while the frontier
176
+ * demands `fix`). Null when the line is closed (its latest round's C5 route is
177
+ * done / next-wave / soft-cap — the soft cap defers to the user). */
178
+ #nextWavePhase(key) {
179
+ return this.#ledger.waveLinePhase(key);
180
+ }
181
+ /** The branch/spec/plan line's next open frame — the fixed audit target's round
182
+ * sequence (review-lead → fix → re-review → closure). */
183
+ #openLineFrame(target) {
184
+ const key = this.#lineKey(target);
185
+ const reviewLead = this.#face.product.reviewLead;
186
+ const phase = this.#nextLinePhase(key, target, reviewLead);
187
+ if (phase === null)
188
+ return null;
189
+ const round = this.#roundFor(phase, key);
190
+ return {
191
+ type: this.#face.type,
192
+ phase,
193
+ round,
194
+ target,
195
+ params: this.#paramsOf({ type: this.#face.type, phase, target, round }),
196
+ key,
197
+ };
198
+ }
199
+ /** The next phase of a single-target line — the doc-revision gate (lifecycle-side:
200
+ * its reviewGate needs the target doc path) then the ledger's SINGLE rounds/routes
201
+ * judge (`Ledger#linePhase`, D40 — the retired lifecycle twin). A CLOSED doc line
202
+ * reopens through the identity verdict (T7): a drifted doc opens the review lead
203
+ * whatever the round/route state says (the fix-awaited route never freezes a
204
+ * revised doc); an unchanged doc with the pending fix derived opens the fix; the
205
+ * unbound / same-without-pending faces fall through to the shared rounds/routes
206
+ * walk (a completed-fix line reopens review through the fix round's route). */
207
+ #nextLinePhase(key, target, reviewLead) {
208
+ if (target.kind === "plan" || target.kind === "spec") {
209
+ const verdict = this.#ledger.reviewGate(key, target.doc, this.#face.type);
210
+ if (verdict.kind === "open")
211
+ return reviewLead;
212
+ if (verdict.kind === "same" && verdict.pending)
213
+ return "fix";
214
+ }
215
+ return this.#ledger.linePhase(key, this.#face.type);
216
+ }
217
+ /** The round number one phase dispatches under: implement = the fixed family (1);
218
+ * the review-lead = the next increment; fix = the source review-lead round. */
219
+ #roundFor(phase, key) {
220
+ if (phase === "implement")
221
+ return 1;
222
+ if (phase === "fix") {
223
+ const reviews = this.#reviewCount(key);
224
+ return reviews > 0 ? reviews : 1;
225
+ }
226
+ return this.#reviewCount(key) + 1;
227
+ }
228
+ /** The review-lead round count of a key (branch counts its branch-review mode,
229
+ * the others the review mode — the face row's single source). */
230
+ #reviewCount(key) {
231
+ return this.#ledger.roundCount(key, this.#face.product.reviewLead);
232
+ }
233
+ /** The progress key of a single-target line — the line's STABLE key (find #9 ·
234
+ * spec §6.5/§3.7 — `"branch"` per workspace for the branch line, accumulating
235
+ * across re-reviews; the doc line keys by its line-type constant `"spec"`/`"plan"`
236
+ * — the argv path copy never resets the round: a moved argv string (absolute vs
237
+ * relative) must not fork the same line into two ledger rows). The task face
238
+ * never routes here — frames key by the wave key. */
239
+ #lineKey(target) {
240
+ if (target.kind === "plan" || target.kind === "spec")
241
+ return this.#face.type;
242
+ return "branch";
243
+ }
244
+ // -------------------------------------------------------------------------
245
+ // the frame → handoff params shaping
246
+ // -------------------------------------------------------------------------
247
+ /** The handoff params one frame fills — the type's placeholders from the target
248
+ * and round. The round rides the increment families (review / fix / branch-review
249
+ * — the family name carries it); the fixed implement family stays round-less. */
250
+ #paramsOf(frame) {
251
+ switch (frame.type) {
252
+ case "wave": {
253
+ const waveTarget = frame.target;
254
+ const params = { tasks: waveTarget.tasks.join(",") };
255
+ if (frame.phase !== "implement")
256
+ params.round = frame.round;
257
+ return params;
258
+ }
259
+ case "branch":
260
+ return { round: frame.round };
261
+ case "spec":
262
+ case "plan":
263
+ return { round: frame.round };
264
+ }
265
+ }
266
+ // -------------------------------------------------------------------------
267
+ // dispatch → result → bookkeeping
268
+ // -------------------------------------------------------------------------
269
+ /** Bookkeeping — persist the round's handoff carrier and record the progress round.
270
+ * The persisted carrier is either the dispatch's materialized form (the production
271
+ * read-back reconstruct — outcome.carrier, full-replace at the SAME path, so the
272
+ * child's draft becomes the finalized carrier — the two-state single file, the engine is the single
273
+ * author) or the engine-built fallback from the outcome fields (the hermetic /
274
+ * injected dispatchers). A BLOCKED/TIMEOUT round WITHOUT a carrier is neither persisted nor
275
+ * recorded — the child's draft (if any) stays untouched (no-overwrite on failure) and the
276
+ * frontier re-offers the same round (resume = re-run the same command); a BLOCKED
277
+ * round WITH a carrier (e.g. the evidence-contract override — the child's work is
278
+ * preserved as the BLOCKED carrier) is persisted but not counted as a completed
279
+ * round, so the frontier still re-dispatches it. Returns the round count on record
280
+ * (the task done-marking rides the step's C5 route — #markTerminal, after
281
+ * #routeNext). */
282
+ #bookkeep(frame, outcome) {
283
+ const blocked = outcome.status === "BLOCKED" || outcome.status === "TIMEOUT";
284
+ if (outcome.carrier !== undefined || !blocked) {
285
+ const op = this.#opOf(frame.phase);
286
+ // T2 — the engine-built fallback rides the FRAME's declared face (the family's
287
+ // `schema` selector, never the outcome's field presence): a findings-face round
288
+ // (review / docs-fix) builds the findings carrier — its schema-required findings
289
+ // key, empty on a conclusion-only round (a fix advances no new findings); a
290
+ // work-face round builds the findings-free work carrier — zero findings
291
+ // injection. The review finding-severity route reads the round carrier's
292
+ // findings; the conclusion rides only the work face's declared status (the
293
+ // findings face derives its conclusion at judgment time).
294
+ const face = this.#ledger.handoffFaceOf(op, frame.type);
295
+ const carrier = outcome.carrier ??
296
+ (face === "findings"
297
+ ? this.#ledger.buildHandoff("findings", {
298
+ findings: [...(outcome.findings ?? [])],
299
+ })
300
+ : this.#ledger.buildHandoff("work", {}));
301
+ // The work face ALONE persists the conclusion (the child's declared status); the
302
+ // findings carrier holds no status — its conclusion derives at judgment time
303
+ // (`HandoffSchema.conclusionOf` → rollup(findings)), never a stored field (D27).
304
+ if (face === "work" && carrier.status === undefined && outcome.status !== undefined)
305
+ carrier.status = outcome.status;
306
+ this.#ledger.persistHandoff(op, frame.type, frame.params, carrier);
307
+ }
308
+ if (!blocked) {
309
+ // The recorded CYCLE is the frame's own round — its identity (fix-K ⟷ review-K ·
310
+ // D28): a skipped cycle records its own number, never a flattened ordinal.
311
+ const count = this.#ledger.recordRound(frame.key, frame.phase, frame.round);
312
+ // The completed-review revision write-back — the doc line and the wave line
313
+ // each bind their OWN reviewed revision (T7 doc · T11 wave / D16 / D30): a
314
+ // completed review binds the CURRENT revision of the reviewed input — read at
315
+ // bookkeep, the clean-tree dispatch gate keeps the read-only review's input
316
+ // stable across the round. For a doc line that input is the target doc (the
317
+ // whole-content doc-revision). For a wave line it is the RENDERED BRIEF —
318
+ // `#recordReviewedWaveBrief` → `recordReviewedBrief(String(frame.key),
319
+ // #planPath)` hashes the brief the plan renders to, holding #planPath only as
320
+ // the plan the brief renders FROM (the render-from POINTER, not the hashed
321
+ // identity; the wave gate derives the plan path FROM this record, so
322
+ // cli.ts/preflight.ts stay untouched). The two legs do NOT share one gate —
323
+ // each ref kind carries its own reviewed identity. An unreadable input records
324
+ // nothing (present facts only); a null plan path (no plan fact) leaves a legacy
325
+ // wave row — null stays backward compatible.
326
+ if (frame.phase === "review") {
327
+ if (frame.target.kind === "plan" || frame.target.kind === "spec")
328
+ this.#recordReviewedDocRevision(frame);
329
+ else if (frame.target.kind === "wave")
330
+ this.#recordReviewedWaveBrief(frame);
331
+ }
332
+ return count;
333
+ }
334
+ return this.#ledger.roundCount(frame.key, frame.phase);
335
+ }
336
+ /** The reviewed-revision write-back — bind the reviewed input's revision to the
337
+ * line record (the T7 doc + D30 wave identity gates' reopen-compare basis). The
338
+ * doc face binds its target doc's whole-content revision; the wave face binds its
339
+ * RENDERED BRIEF's revision (D30 — the wave's true judgment input is the brief,
340
+ * never the whole plan: transcript edits outside the wave's task sections must not
341
+ * void a reviewed wave). An unreadable input records nothing — the line keeps the
342
+ * legacy closed face (only present facts land, never an invented identity). */
343
+ #recordReviewedDocRevision(frame) {
344
+ if (frame.target.kind !== "plan" && frame.target.kind !== "spec")
345
+ return;
346
+ try {
347
+ const content = readFileSync(frame.target.doc, "utf8");
348
+ this.#ledger.recordReviewedRevision(frame.key, this.#ledger.refs().docRevision(frame.target.doc, content));
349
+ }
350
+ catch {
351
+ // unreadable input — no reviewed identity recorded (present facts only)
352
+ }
353
+ }
354
+ /** The wave line's reviewed-brief write-back (D30) — bind the RENDERED brief's
355
+ * revision for the wave's tasks to the row (the D30 wave-gate reopen basis). Null
356
+ * plan path / underivable brief records nothing (present facts only). */
357
+ #recordReviewedWaveBrief(frame) {
358
+ if (frame.target.kind !== "wave" || this.#planPath === null)
359
+ return;
360
+ this.#ledger.recordReviewedBrief(String(frame.key), this.#planPath);
361
+ }
362
+ /** Mark the wave done when the concluding route says its line closed — the C5
363
+ * verdict is the single closure gate (terminal ⇔ route.kind ∈ {done, next-wave},
364
+ * the v1.20 closure side): a clean review or a blocker-free fix closes the wave
365
+ * (every member task), while a re-review / soft-cap / a null route (BLOCKED,
366
+ * TIMEOUT, a missing base) holds it. Marking the closed wave lets the next
367
+ * frontier pass exclude it. The task-less faces never mark — for them the route
368
+ * IS the gate. */
369
+ #markTerminal(frame, route) {
370
+ if (frame.type !== "wave")
371
+ return;
372
+ if (!Ledger.routeClosed(route))
373
+ return;
374
+ const waveTarget = frame.target;
375
+ for (const id of waveTarget.tasks)
376
+ this.#state.markDone(id);
377
+ }
378
+ /** The handoff-family op of a phase — branch-review rides the review family. */
379
+ #opOf(phase) {
380
+ return phase === "branch-review" ? "review" : phase;
381
+ }
382
+ // -------------------------------------------------------------------------
383
+ // next routing + the capsule interaction
384
+ // -------------------------------------------------------------------------
385
+ /** The next-hop route — the recorded round read back through the ledger (the fix
386
+ * round carries the SOURCE review's findings, C5-1) and judged by the router.
387
+ * Null when the round is unreadable (no invented next hop from absent facts). */
388
+ #routeNext(frame) {
389
+ const op = this.#opOf(frame.phase);
390
+ const carried = this.#ledger.round(op, frame.type, frame.params, frame.round);
391
+ if (carried === null)
392
+ return null;
393
+ return this.#router.next(this.#routeState(), carried);
394
+ }
395
+ /** The execution state the router judges next against — the real run state for
396
+ * the batch faces (task), the empty single-target state for the rest (their
397
+ * nextSemantics.batch is false — a review-approved closes the line, never a batch
398
+ * continuation). */
399
+ #routeState() {
400
+ return this.#face.nextSemantics.batch ? this.#state : EMPTY_RUN_STATE;
401
+ }
402
+ /** The capsule lines of one step — empty unless a capsule is attached (the non-hard
403
+ * interaction point). The blocker cell carries the round's blocker count; the
404
+ * dispatch-ready `next:` literal rides the frame's own RouteTarget identity
405
+ * (type + id — the v1.25 combination point: frame.type + params.tasks + route
406
+ * are all present here). */
407
+ #capsuleLines(frame, outcome, route) {
408
+ if (this.#capsule === null)
409
+ return [];
410
+ const op = this.#opOf(frame.phase);
411
+ const blockers = (outcome.findings ?? []).filter((finding) => finding.severity === "blocker").length;
412
+ const handoff = this.#ledger.handoffPath(op, frame.type, frame.params);
413
+ return this.#capsule.emit(outcome.status, String(blockers), handoff, route, this.#routeTarget(frame));
414
+ }
415
+ /** The frame's RouteTarget — the dispatch-ready literal's target identity (the
416
+ * frame's own facts: the wave task key · the branch line key · the doc path).
417
+ * `type` rides the wave target type; `id` the frame's parameters; `plan` the
418
+ * workspace plan path (the implement literal's required `--plan`). */
419
+ #routeTarget(frame) {
420
+ switch (frame.type) {
421
+ case "wave":
422
+ return { type: "wave", id: frame.params.tasks ?? "", plan: this.#planPath ?? undefined };
423
+ case "branch":
424
+ // The branch line's stable id — the workspace plan path carries the
425
+ // fix/re-review literals' `--plan` (a plan-less `#sceneOf` would resolve
426
+ // to the empty directory · the workspace double identity · zero
427
+ // orchestrator fallback).
428
+ return {
429
+ type: "branch",
430
+ id: "branch",
431
+ plan: this.#planPath ?? undefined,
432
+ };
433
+ case "spec":
434
+ case "plan":
435
+ return {
436
+ type: frame.type,
437
+ id: frame.target.doc,
438
+ };
439
+ }
440
+ }
441
+ }
@@ -0,0 +1,8 @@
1
+ // packages/cdd-engine/src-next/session/state.ts
2
+ // T6 — the execution-state query surface (design spec §3.1): the frontier dynamic
3
+ // face + the ExecutionState query surface. Both are contracts the run carrier
4
+ // implements — TaskGraph today, the round ledger's ProgressLedger later — and the
5
+ // query methods (doneTasks() / readyBatch()) are METHODS on the carrier, never
6
+ // standalone state classes. Module-level exports are interfaces only — zero
7
+ // behavior-carrying bare functions (the plan's zero-bare-function discipline).
8
+ export {};
@@ -0,0 +1,92 @@
1
+ // packages/cdd-engine/src-next/session/wave.ts
2
+ // T24 (v1.21 — the three-verb unified wave gate) — the task-face dispatch
3
+ // pre-flight as ONE gate method. The retired split check (the implement-only
4
+ // strict-wave check + the phase lock) converges into `WaveGate.vet(requested,
5
+ // verb)`: implement / review / fix share the same single wave gate — a
6
+ // half-wave review or a half-wave fix is structurally blocked exactly like a
7
+ // half-wave implement.
8
+ //
9
+ // The gate's only read face is `open = frontier(closedWaves())` — the derived
10
+ // wave over the ledger's C5 closure set (ledger.ts, the same closure predicate as
11
+ // the lifecycle's #markTerminal). The two judgments:
12
+ // 1. requested ≠ open → the split/subset BLOCK (dispatch the full derived wave,
13
+ // with the wave-board hint);
14
+ // 2. the open wave's phase ≠ verb → the wrong-phase BLOCK (run the matching phase).
15
+ // (v1.28 — the heterogeneous-phase row RETIRED: the wave-unitary ledger has ONE row
16
+ // per wave, so mixed per-task phases are structurally impossible — a per-task phase
17
+ // read was the T26 regression {16,22,24} exposed (the row key `16` never matched
18
+ // `{wave:"16,22,24"}`), not a mixed-phase anomaly.)
19
+ // The verdict wording renders the wave-gate vocabulary rows (face/words.ts — the
20
+ // gate's prompt wording rides the word table, never a literal restate). BLOCK
21
+ // messages and the verdict shape are data here; the CLI face renders them.
22
+ //
23
+ // Module-level exports are types / the class — zero behavior-carrying bare
24
+ // functions (the plan's zero-bare-function discipline).
25
+ /**
26
+ * WaveGate — the three-verb unified wave gate (implement / review / fix share the
27
+ * single gate). One OOP method: vet(requested, verb) judges the request against
28
+ * the derived open wave + the ledger's per-task phases; the CLI calls it before
29
+ * ANY task-face dispatch, never a variant gate per verb.
30
+ */
31
+ export class WaveGate {
32
+ /** vet(requested, verb, graph, ledger, words) — the three-verb gate: the verdict
33
+ * row the CLI renders (ok → dispatch; a reason + message → the BLOCK face). */
34
+ vet(requested, verb, graph, ledger, words) {
35
+ const closed = ledger.closedWaves();
36
+ const open = [...graph.frontier(closed)].sort((a, b) => a - b);
37
+ const asked = [...requested].sort((a, b) => a - b);
38
+ const requestedKey = asked.join(",");
39
+ const openKey = open.join(",");
40
+ const wordsGate = words.waveGateWords();
41
+ const exact = asked.length === open.length && asked.every((id, index) => id === open[index]);
42
+ // 1. The split/subset BLOCK — requested ≠ open: a `--tasks` set that splits or
43
+ // mismatches the derived wave is refused for ANY verb (a subset never reorders
44
+ // the wave, never half-approves it). The full-wave hint rides the message.
45
+ if (!exact) {
46
+ return {
47
+ ok: false,
48
+ reason: "split",
49
+ message: this.#fill(wordsGate.split, { requested: requestedKey, open: openKey }),
50
+ open,
51
+ phases: this.#phasesOf(ledger, open),
52
+ };
53
+ }
54
+ // 2. The open wave's phase — the single phase of the wave's own row (wave-unitary:
55
+ // one ledger row per wave, so every member shares the phase; a per-task read
56
+ // never matches the wave row — the T26 migration regression).
57
+ const phases = this.#phasesOf(ledger, open);
58
+ const phase = phases[0]?.phase ?? null;
59
+ if (phase !== verb) {
60
+ return {
61
+ ok: false,
62
+ reason: "wrong-phase",
63
+ message: this.#fill(wordsGate.wrongPhase, { phase: phase ?? "held" }),
64
+ open,
65
+ phases,
66
+ };
67
+ }
68
+ return { ok: true, open, phases };
69
+ }
70
+ /** The open wave's per-task phases — every member resolves the WAVE row's single
71
+ * phase (implement → review → fix → re-review → closure; null = no open round). */
72
+ #phasesOf(ledger, open) {
73
+ const waveKey = open.join(",");
74
+ const phase = this.#phaseOf(ledger, waveKey);
75
+ return open.map((task) => ({ task, phase }));
76
+ }
77
+ /** The ledger-derived open phase of ONE wave row — the SINGLE source (D26): the
78
+ * wave gate and the lifecycle's frame frontier both read this one method
79
+ * (`Ledger#waveLinePhase`), never a per-consumer copy. The wave-unitary read: the
80
+ * same C5 round-pair derivation over the wave's own row key (the per-task read
81
+ * never matched a `{wave:"16,22,24"}` row — the fix). The D16/T11 revision
82
+ * precheck lives in the ledger method (a drifted BRIEF reopens at review; same +
83
+ * pending fix stays at fix). */
84
+ #phaseOf(ledger, waveKey) {
85
+ return ledger.waveLinePhase(waveKey);
86
+ }
87
+ /** The raw fill of one placeholder template — the noun-slot substitution
88
+ * ({requested} / {open} / {phase} / {map}); every slot defined, unknown braces kept. */
89
+ #fill(template, slots) {
90
+ return template.replace(/\{(\w+)\}/g, (whole, name) => slots[name] ?? whole);
91
+ }
92
+ }
package/package.json CHANGED
@@ -1,33 +1,34 @@
1
1
  {
2
2
  "name": "@oscaner-skills/cdd-engine",
3
- "version": "2.0.0",
3
+ "version": "3.0.1",
4
4
  "description": "CDD engine CLIs: task runner, docs reviewer, branch reviewer, harness selector.",
5
5
  "type": "module",
6
6
  "engines": {
7
7
  "node": ">=24"
8
8
  },
9
9
  "files": [
10
- "src-next/",
10
+ "dist/",
11
11
  "templates/"
12
12
  ],
13
- "main": "./src-next/bin.ts",
13
+ "main": "./dist/bin.js",
14
14
  "exports": {
15
- ".": "./src-next/bin.ts",
15
+ ".": "./dist/bin.js",
16
16
  "./package.json": "./package.json"
17
17
  },
18
18
  "bin": {
19
- "cdd": "./src-next/bin.ts"
19
+ "cdd": "./dist/bin.js"
20
20
  },
21
21
  "dependencies": {
22
22
  "commander": "^15.0.0",
23
23
  "execa": "^10.1.1",
24
24
  "jsonc-parser": "^3.3.1",
25
- "simple-git": "^4.0.2"
25
+ "simple-git": "^4.0.2",
26
+ "yaml": "^2.9.1"
26
27
  },
27
28
  "devDependencies": {
28
29
  "@types/node": "^24.19.2",
29
30
  "typescript": "^7.0.2",
30
- "vitest": "^5.0.3"
31
+ "vitest": "^5.0.5"
31
32
  },
32
33
  "repository": {
33
34
  "type": "git",
@@ -9,45 +9,6 @@
9
9
  "kairos:cdd-report",
10
10
  "kairos:cdd-close"
11
11
  ],
12
- "severities": [
13
- "blocker",
14
- "warn",
15
- "nit"
16
- ],
17
- "metaFields": [
18
- { "key": "skill", "label": "Skill" },
19
- { "key": "step", "label": "Step" }
20
- ],
21
- "sectionLabels": {
22
- "bug": {
23
- "en": {
24
- "context": "## Context",
25
- "problem": "## Problem",
26
- "impact": "## Impact",
27
- "suggestedFix": "## Suggested fix"
28
- },
29
- "zh": {
30
- "context": "## 背景",
31
- "problem": "## 问题",
32
- "impact": "## 影响",
33
- "suggestedFix": "## 建议修复"
34
- }
35
- },
36
- "enhancement": {
37
- "en": {
38
- "context": "## Context",
39
- "problem": "## Current behavior",
40
- "impact": "## Desired behavior",
41
- "suggestedFix": "## Suggested approach"
42
- },
43
- "zh": {
44
- "context": "## 背景",
45
- "problem": "## 当前行为",
46
- "impact": "## 期望行为",
47
- "suggestedFix": "## 建议方案"
48
- }
49
- }
50
- },
51
12
  "formFieldDefs": {
52
13
  "bug_report": {
53
14
  "frontmatter": {
@@ -191,12 +152,5 @@
191
152
  }
192
153
  ]
193
154
  }
194
- },
195
- "reportDef": {
196
- "labels": ["kairos", "cdd-engine"]
197
- },
198
- "masterDef": {
199
- "sessionTitle": "## Session",
200
- "harnessRow": "- Harness: <harness>"
201
155
  }
202
156
  }