@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.
- package/{src-next/bin.ts → dist/bin.js} +18 -21
- package/dist/contract/declare.js +998 -0
- package/dist/contract/doc.js +565 -0
- package/dist/contract/frontmatter.js +209 -0
- package/dist/contract/home-extractors.js +379 -0
- package/dist/contract/invariants.js +1030 -0
- package/dist/contract/judge.js +109 -0
- package/dist/contract/lint.js +206 -0
- package/dist/contract/project.js +371 -0
- package/dist/contract/skill-anatomy.js +156 -0
- package/dist/contract/translate.js +85 -0
- package/dist/face/artifacts.js +189 -0
- package/dist/face/board-view.js +522 -0
- package/dist/face/capsule.js +141 -0
- package/dist/face/cli.js +891 -0
- package/dist/face/declare.js +241 -0
- package/dist/face/gate.js +158 -0
- package/dist/face/graph-view.js +66 -0
- package/dist/face/host.js +211 -0
- package/dist/face/lifecycle.js +603 -0
- package/dist/face/preview.js +136 -0
- package/dist/face/projection.js +259 -0
- package/dist/face/route-render.js +162 -0
- package/dist/face/termination.js +482 -0
- package/dist/face/words.js +220 -0
- package/{src-next/infra/config.ts → dist/infra/config.js} +19 -24
- package/{src-next/infra/doc-roots.ts → dist/infra/doc-roots.js} +3 -13
- package/dist/infra/git.js +37 -0
- package/dist/infra/process.js +22 -0
- package/{src-next/infra/root.ts → dist/infra/root.js} +25 -36
- package/dist/infra/runtime.js +85 -0
- package/dist/infra/workspace.js +276 -0
- package/dist/render/brief.js +82 -0
- package/dist/render/issue-body.js +129 -0
- package/dist/render/skeleton.js +434 -0
- package/dist/render/templates.js +520 -0
- package/dist/session/faces.js +38 -0
- package/dist/session/graph.js +309 -0
- package/dist/session/handoff-schema.js +295 -0
- package/dist/session/ledger.js +762 -0
- package/dist/session/next.js +211 -0
- package/dist/session/preflight.js +194 -0
- package/dist/session/round-naming.js +73 -0
- package/dist/session/run.js +441 -0
- package/dist/session/state.js +8 -0
- package/dist/session/wave.js +92 -0
- package/package.json +5 -5
- package/src-next/__tests__/bin.test.ts +0 -128
- package/src-next/__tests__/dead-decl.guard.test.ts +0 -39
- package/src-next/__tests__/floor.guard.test.ts +0 -69
- package/src-next/__tests__/issue-body.guard.test.ts +0 -66
- package/src-next/__tests__/phase-suffix.guard.test.ts +0 -72
- package/src-next/__tests__/smoke.integration.test.ts +0 -185
- package/src-next/__tests__/support/strip-comments.ts +0 -99
- package/src-next/__tests__/zero-dep.test.ts +0 -94
- package/src-next/contract/__tests__/__snapshots__/project.schema.overall-spec.snap +0 -256
- package/src-next/contract/__tests__/__snapshots__/project.schema.phase-spec.snap +0 -165
- package/src-next/contract/__tests__/__snapshots__/project.schema.plan.snap +0 -190
- package/src-next/contract/__tests__/__snapshots__/project.schema.single-spec.snap +0 -106
- package/src-next/contract/__tests__/__snapshots__/project.shape.overall-spec.snap +0 -240
- package/src-next/contract/__tests__/__snapshots__/project.shape.phase-spec.snap +0 -165
- package/src-next/contract/__tests__/__snapshots__/project.shape.plan.snap +0 -190
- package/src-next/contract/__tests__/__snapshots__/project.shape.single-spec.snap +0 -100
- package/src-next/contract/__tests__/declare.test.ts +0 -481
- package/src-next/contract/__tests__/doc.test.ts +0 -527
- package/src-next/contract/__tests__/dockey.guard.test.ts +0 -58
- package/src-next/contract/__tests__/edge-conditions.guard.test.ts +0 -81
- package/src-next/contract/__tests__/frontmatter.test.ts +0 -164
- package/src-next/contract/__tests__/judge.test.ts +0 -1111
- package/src-next/contract/__tests__/lint.test.ts +0 -324
- package/src-next/contract/__tests__/project.test.ts +0 -460
- package/src-next/contract/__tests__/structure-pin.test.ts +0 -186
- package/src-next/contract/__tests__/translate.test.ts +0 -96
- package/src-next/contract/declare.ts +0 -1071
- package/src-next/contract/doc.ts +0 -816
- package/src-next/contract/frontmatter.ts +0 -233
- package/src-next/contract/home-extractors.ts +0 -397
- package/src-next/contract/invariants.ts +0 -1413
- package/src-next/contract/judge.ts +0 -151
- package/src-next/contract/lint.ts +0 -239
- package/src-next/contract/project.ts +0 -656
- package/src-next/contract/skill-anatomy.ts +0 -301
- package/src-next/contract/translate.ts +0 -113
- package/src-next/face/__tests__/board-view.test.ts +0 -1151
- package/src-next/face/__tests__/capsule.test.ts +0 -300
- package/src-next/face/__tests__/channel-closure.guard.test.ts +0 -129
- package/src-next/face/__tests__/cli.test.ts +0 -4897
- package/src-next/face/__tests__/face.test.ts +0 -289
- package/src-next/face/__tests__/graph-view.test.ts +0 -61
- package/src-next/face/__tests__/host.test.ts +0 -24
- package/src-next/face/__tests__/install-rows.guard.test.ts +0 -58
- package/src-next/face/__tests__/negation.ts +0 -6
- package/src-next/face/__tests__/preview.test.ts +0 -374
- package/src-next/face/__tests__/projection.test.ts +0 -303
- package/src-next/face/__tests__/repo-root.guard.test.ts +0 -120
- package/src-next/face/__tests__/termination.test.ts +0 -650
- package/src-next/face/__tests__/words.guard.test.ts +0 -93
- package/src-next/face/artifacts.ts +0 -248
- package/src-next/face/board-view.ts +0 -652
- package/src-next/face/capsule.ts +0 -163
- package/src-next/face/cli.ts +0 -1028
- package/src-next/face/declare.ts +0 -323
- package/src-next/face/gate.ts +0 -171
- package/src-next/face/graph-view.ts +0 -74
- package/src-next/face/host.ts +0 -302
- package/src-next/face/lifecycle.ts +0 -725
- package/src-next/face/preview.ts +0 -151
- package/src-next/face/projection.ts +0 -285
- package/src-next/face/route-render.ts +0 -185
- package/src-next/face/termination.ts +0 -573
- package/src-next/face/words.ts +0 -314
- package/src-next/infra/__tests__/infra.test.ts +0 -333
- package/src-next/infra/__tests__/root.test.ts +0 -56
- package/src-next/infra/git.ts +0 -39
- package/src-next/infra/process.ts +0 -34
- package/src-next/infra/runtime.ts +0 -132
- package/src-next/infra/workspace.ts +0 -322
- package/src-next/render/__tests__/render.test.ts +0 -550
- package/src-next/render/__tests__/skeleton.test.ts +0 -684
- package/src-next/render/brief.ts +0 -121
- package/src-next/render/issue-body.ts +0 -162
- package/src-next/render/skeleton.ts +0 -502
- package/src-next/render/templates.ts +0 -645
- package/src-next/session/__tests__/graph.test.ts +0 -277
- package/src-next/session/__tests__/handoff-plane.guard.test.ts +0 -48
- package/src-next/session/__tests__/handoff-schema.test.ts +0 -310
- package/src-next/session/__tests__/ledger.test.ts +0 -745
- package/src-next/session/__tests__/next.test.ts +0 -460
- package/src-next/session/__tests__/preflight.test.ts +0 -545
- package/src-next/session/__tests__/round-naming.test.ts +0 -142
- package/src-next/session/__tests__/run.test.ts +0 -1026
- package/src-next/session/__tests__/wave-line-phase.guard.test.ts +0 -49
- package/src-next/session/__tests__/wave.test.ts +0 -476
- package/src-next/session/faces.ts +0 -110
- package/src-next/session/graph.ts +0 -411
- package/src-next/session/handoff-schema.ts +0 -373
- package/src-next/session/ledger.ts +0 -1076
- package/src-next/session/next.ts +0 -293
- package/src-next/session/preflight.ts +0 -271
- package/src-next/session/round-naming.ts +0 -84
- package/src-next/session/run.ts +0 -610
- package/src-next/session/state.ts +0 -30
- 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,22 +1,22 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@oscaner-skills/cdd-engine",
|
|
3
|
-
"version": "3.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
|
-
"
|
|
10
|
+
"dist/",
|
|
11
11
|
"templates/"
|
|
12
12
|
],
|
|
13
|
-
"main": "./
|
|
13
|
+
"main": "./dist/bin.js",
|
|
14
14
|
"exports": {
|
|
15
|
-
".": "./
|
|
15
|
+
".": "./dist/bin.js",
|
|
16
16
|
"./package.json": "./package.json"
|
|
17
17
|
},
|
|
18
18
|
"bin": {
|
|
19
|
-
"cdd": "./
|
|
19
|
+
"cdd": "./dist/bin.js"
|
|
20
20
|
},
|
|
21
21
|
"dependencies": {
|
|
22
22
|
"commander": "^15.0.0",
|