@oscaner-skills/cdd-engine 4.2.0 → 4.4.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +38 -9
- package/README.zh-CN.md +44 -10
- package/dist/contract/completion-criterion.js +351 -0
- package/dist/contract/declare.js +181 -43
- package/dist/contract/doc.js +84 -271
- package/dist/contract/frontmatter.js +2 -1
- package/dist/contract/home-extractors.js +49 -316
- package/dist/contract/invariants.js +400 -296
- package/dist/contract/judge.js +74 -49
- package/dist/contract/lint.js +3 -2
- package/dist/contract/liveness-signal.js +103 -0
- package/dist/contract/markdown-document.js +410 -0
- package/dist/contract/markdown-tree-types.js +6 -0
- package/dist/contract/markdown-tree.js +137 -0
- package/dist/contract/project.js +1 -1
- package/dist/contract/rules.js +106 -0
- package/dist/contract/selector-engine.js +332 -0
- package/dist/contract/selector-spec.js +74 -0
- package/dist/contract/skill-anatomy.js +29 -1
- package/dist/contract/task-block-grammar.js +285 -0
- package/dist/contract/task-blocks.js +65 -0
- package/dist/contract/translate.js +21 -0
- package/dist/contract/wave-width.js +15 -0
- package/dist/face/board-view.js +382 -172
- package/dist/face/capsule.js +73 -88
- package/dist/face/cli.js +152 -38
- package/dist/face/declare.js +42 -19
- package/dist/face/gate.js +119 -40
- package/dist/face/init.js +84 -25
- package/dist/face/lifecycle.js +540 -123
- package/dist/face/plugins.js +70 -2
- package/dist/face/preview.js +69 -18
- package/dist/face/route-render.js +60 -21
- package/dist/face/termination.js +135 -261
- package/dist/face/words.js +139 -13
- package/dist/infra/atomic.js +15 -0
- package/dist/infra/git.js +25 -0
- package/dist/infra/proc.js +150 -0
- package/dist/infra/round-log.js +104 -0
- package/dist/infra/runtime.js +16 -4
- package/dist/infra/workspace.js +7 -2
- package/dist/render/brief.js +15 -17
- package/dist/render/skeleton.js +41 -28
- package/dist/render/templates.js +128 -84
- package/dist/session/faces.js +47 -20
- package/dist/session/graph.js +13 -37
- package/dist/session/handoff-schema.js +16 -8
- package/dist/session/inflight.js +282 -0
- package/dist/session/ledger.js +603 -145
- package/dist/session/line-identity.js +33 -0
- package/dist/session/next.js +140 -80
- package/dist/session/pipeline.js +247 -0
- package/dist/session/preflight.js +276 -68
- package/dist/session/reviewed-identity.js +54 -0
- package/dist/session/round-naming.js +56 -8
- package/dist/session/run.js +364 -80
- package/dist/session/wave.js +94 -14
- package/package.json +13 -3
package/dist/session/run.js
CHANGED
|
@@ -18,8 +18,12 @@
|
|
|
18
18
|
// Module-level exports are types / the class / one empty-state data const — zero
|
|
19
19
|
// behavior-carrying bare functions (the plan's zero-bare-function discipline).
|
|
20
20
|
import { readFileSync } from "node:fs";
|
|
21
|
+
import { PlanDocType } from "../contract/doc.js";
|
|
22
|
+
import { PlanTaskBlocksReader } from "../contract/task-blocks.js";
|
|
21
23
|
import { Ledger, } from "./ledger.js";
|
|
22
24
|
import { NextStepRouter } from "./next.js";
|
|
25
|
+
import { PipelineFrontier } from "./pipeline.js";
|
|
26
|
+
import { ReviewedIdentity } from "./reviewed-identity.js";
|
|
23
27
|
/** The empty run state — a target line with no task frontier (branch/spec/plan):
|
|
24
28
|
* the frontier query faces are always empty (a single-target line never continues
|
|
25
29
|
* a batch) and markDone is a no-op. */
|
|
@@ -29,6 +33,83 @@ export const EMPTY_RUN_STATE = {
|
|
|
29
33
|
frontier: () => [],
|
|
30
34
|
markDone: () => undefined,
|
|
31
35
|
};
|
|
36
|
+
/**
|
|
37
|
+
* PlanStructure — one plan document's STRUCTURE face: the task-id set and each task's
|
|
38
|
+
* declared `DependsOn` set (design spec §7.3).
|
|
39
|
+
*
|
|
40
|
+
* It is a per-round DISPATCH baseline, not a stored fact: the lifecycle snapshots it
|
|
41
|
+
* right before the spawn and re-reads it at the round's close, so only the round's OWN
|
|
42
|
+
* structure edit is judged — a content-only amendment (facts, file lists, steps,
|
|
43
|
+
* acceptance detail, cited line numbers) stays legal. The judgment has ONE presentation
|
|
44
|
+
* face (the round's graded `violations`): no doc-contract rule row is registered for it,
|
|
45
|
+
* because the engine's single doc-contract evaluation point is the pre-dispatch gate.
|
|
46
|
+
*/
|
|
47
|
+
export class PlanStructure {
|
|
48
|
+
/** The registered task ids, ascending. */
|
|
49
|
+
#taskIds;
|
|
50
|
+
/** Each task's declared dependency set, keyed by task id. */
|
|
51
|
+
#dependsOn;
|
|
52
|
+
constructor(taskIds, dependsOn) {
|
|
53
|
+
this.#taskIds = taskIds;
|
|
54
|
+
this.#dependsOn = dependsOn;
|
|
55
|
+
}
|
|
56
|
+
/** Read a plan document's two structure faces. `absent` when there is no plan fact
|
|
57
|
+
* (no path, or a path whose document does not exist); `unreadable` when the path
|
|
58
|
+
* exists but the document cannot be read (the reason rides the read result); `ok`
|
|
59
|
+
* with the snapshot otherwise. The three cases stay apart so a caller can tell "there
|
|
60
|
+
* is no plan" from "the plan is damaged" — the two carry different judgments. */
|
|
61
|
+
static of(planPath) {
|
|
62
|
+
if (planPath === null)
|
|
63
|
+
return { kind: "absent" };
|
|
64
|
+
try {
|
|
65
|
+
return { kind: "ok", structure: PlanStructure.parse(readFileSync(planPath, "utf8")) };
|
|
66
|
+
}
|
|
67
|
+
catch (error) {
|
|
68
|
+
// A path with no document is the absent case, never a read failure; every other
|
|
69
|
+
// error is the damaged-document case, its reason carried into the caller's message.
|
|
70
|
+
if (error.code === "ENOENT")
|
|
71
|
+
return { kind: "absent" };
|
|
72
|
+
return { kind: "unreadable", reason: error instanceof Error ? error.message : String(error) };
|
|
73
|
+
}
|
|
74
|
+
}
|
|
75
|
+
/** Parse one plan document into its structure face — the ONE task-block read face. */
|
|
76
|
+
static parse(content) {
|
|
77
|
+
const reader = new PlanTaskBlocksReader();
|
|
78
|
+
const blocks = reader.parse(content);
|
|
79
|
+
const dependsOn = new Map();
|
|
80
|
+
for (const block of blocks)
|
|
81
|
+
dependsOn.set(block.id, reader.dependsOn(block));
|
|
82
|
+
const taskIds = blocks.map((block) => block.id).sort((left, right) => left - right);
|
|
83
|
+
return new PlanStructure(taskIds, dependsOn);
|
|
84
|
+
}
|
|
85
|
+
/** The task-id set, ascending. */
|
|
86
|
+
get taskIds() {
|
|
87
|
+
return this.#taskIds;
|
|
88
|
+
}
|
|
89
|
+
/** One task's declared dependency set ([] when it declares none). */
|
|
90
|
+
dependsOnOf(taskId) {
|
|
91
|
+
return this.#dependsOn.get(taskId) ?? [];
|
|
92
|
+
}
|
|
93
|
+
/** Whether the two snapshots differ on either structure face — SET equality over the
|
|
94
|
+
* task-id set and over every task's dependency set (a task added, removed or rewired
|
|
95
|
+
* differs; a prose edit does not; declaration order is prose, the edge set is the
|
|
96
|
+
* structure). */
|
|
97
|
+
differsFrom(other) {
|
|
98
|
+
if (this.#taskIds.length !== other.#taskIds.length)
|
|
99
|
+
return true;
|
|
100
|
+
if (!this.#taskIds.every((id, index) => id === other.#taskIds[index]))
|
|
101
|
+
return true;
|
|
102
|
+
return this.#taskIds.some((id) => !PlanStructure.#sameIds(this.dependsOnOf(id), other.dependsOnOf(id)));
|
|
103
|
+
}
|
|
104
|
+
/** Set equality of two id lists (order-insensitive). */
|
|
105
|
+
static #sameIds(left, right) {
|
|
106
|
+
if (left.length !== right.length)
|
|
107
|
+
return false;
|
|
108
|
+
const sortedLeft = [...left].sort((a, b) => a - b);
|
|
109
|
+
const sortedRight = [...right].sort((a, b) => a - b);
|
|
110
|
+
return sortedLeft.every((id, index) => id === sortedRight[index]);
|
|
111
|
+
}
|
|
112
|
+
}
|
|
32
113
|
/**
|
|
33
114
|
* Lifecycle — the parameterized single lifecycle over one target-type face. One
|
|
34
115
|
* instance drives one target line. advance() runs one dispatch step:
|
|
@@ -64,8 +145,28 @@ export class Lifecycle {
|
|
|
64
145
|
* keep their existing behavior). */
|
|
65
146
|
#preflight;
|
|
66
147
|
/** The workspace plan path — the `next:` implement literal's required `--plan`
|
|
67
|
-
* arg (P4.1 T4 — the task face's implement-consuming fact)
|
|
148
|
+
* arg (P4.1 T4 — the task face's implement-consuming fact), and the plan cell of
|
|
149
|
+
* the pipeline frontier's input. A `--spec` round fills it from the document index
|
|
150
|
+
* (the same-slug plan the argv does not name); the plan / branch lines carry their
|
|
151
|
+
* argv value. */
|
|
68
152
|
#planPath;
|
|
153
|
+
/** The pipeline frontier's declared identity — the spec line's DECLARED word (the
|
|
154
|
+
* `doc-type:` head key) and its document path. A node with no spec document
|
|
155
|
+
* (`#specPath === null`) keeps this line's own hop assembly: the frontier's rules
|
|
156
|
+
* anchor on an absent identity face, which would print a passed phase's transition. */
|
|
157
|
+
#specType;
|
|
158
|
+
#specPath;
|
|
159
|
+
/** The plan's task graph — the pipeline frontier's guarded plan read, injected by
|
|
160
|
+
* the composition root (the session plane reads no file). */
|
|
161
|
+
#planGraph;
|
|
162
|
+
/** The pipeline frontier — the ONE hop assembly this lifecycle's capsule renders
|
|
163
|
+
* (the same object the board renders). */
|
|
164
|
+
#frontier;
|
|
165
|
+
/** The pipeline-station discrimination the hop derivation injects (P22 §5.2) —
|
|
166
|
+
* the SAME face read the capsule/board use (`BoardView.docClassOf`). The
|
|
167
|
+
* composition root passes it; the session-plane default keys by target type
|
|
168
|
+
* (the CLI is the seam that reads a spec's DECLARED class). */
|
|
169
|
+
#docClassOf;
|
|
69
170
|
constructor(opts) {
|
|
70
171
|
this.#face = opts.face;
|
|
71
172
|
this.#state = opts.state;
|
|
@@ -76,6 +177,20 @@ export class Lifecycle {
|
|
|
76
177
|
this.#capsule = opts.capsule ?? null;
|
|
77
178
|
this.#preflight = opts.preflight ?? null;
|
|
78
179
|
this.#planPath = opts.planPath ?? null;
|
|
180
|
+
this.#specType = opts.specType ?? null;
|
|
181
|
+
this.#specPath = opts.specPath ?? null;
|
|
182
|
+
this.#planGraph = opts.planGraph ?? null;
|
|
183
|
+
this.#frontier = new PipelineFrontier(this.#ledger);
|
|
184
|
+
this.#docClassOf = opts.docClassOf ?? Lifecycle.#docClassByType;
|
|
185
|
+
}
|
|
186
|
+
/** The session-plane default discrimination — the target type's own pipeline key.
|
|
187
|
+
* Every target type but the standalone `single-spec` IS a pipeline key (the
|
|
188
|
+
* `PipelineKey` derivation), so the map is the identity plus the one terminal row
|
|
189
|
+
* (a single-spec carries no pipeline seam). The declaration-reading judgment (a
|
|
190
|
+
* doc's `doc-type:`) belongs to the face plane; the composition root injects it as
|
|
191
|
+
* `BoardView.docClassOf`. */
|
|
192
|
+
static #docClassByType(target) {
|
|
193
|
+
return target.type === "single-spec" ? "terminal" : target.type;
|
|
79
194
|
}
|
|
80
195
|
/** The face row this instance drives. */
|
|
81
196
|
face() {
|
|
@@ -91,9 +206,18 @@ export class Lifecycle {
|
|
|
91
206
|
* cursor pre-checks the next step against the requested verb before it advances
|
|
92
207
|
* (a mismatch must not consume the round: advance() dispatches on entry — the
|
|
93
208
|
* {16,22,24} bug's loop reordered lookahead-after-dispatch and spent the next
|
|
94
|
-
* phase's round in the same invocation).
|
|
209
|
+
* phase's round in the same invocation). The returned `hop` is this line's own
|
|
210
|
+
* LINE FRONTIER assembly (`#hopOf`): the frame-keyed hop the CLI rejection message
|
|
211
|
+
* reads — never the pipeline frontier's assembly, which the capsule and the board
|
|
212
|
+
* share. Null = the run is exhausted / capped (no open frame → no line to name). */
|
|
95
213
|
peekNext() {
|
|
96
|
-
|
|
214
|
+
const frame = this.#openFrame();
|
|
215
|
+
if (frame === null)
|
|
216
|
+
return null;
|
|
217
|
+
const route = frame.type === "wave"
|
|
218
|
+
? this.#ledger.waveLineRoute(String(frame.key))
|
|
219
|
+
: this.#ledger.lineRoute(frame.key, frame.type);
|
|
220
|
+
return { frame, hop: this.#hopOf(frame, route) };
|
|
97
221
|
}
|
|
98
222
|
/** advance() — one dispatch step: frontier → pre-flight gate → dispatch → result →
|
|
99
223
|
* bookkeeping → next routing. Null when the line holds no open frame (the run is
|
|
@@ -109,7 +233,7 @@ export class Lifecycle {
|
|
|
109
233
|
if (verdict !== null && !verdict.ok) {
|
|
110
234
|
return {
|
|
111
235
|
frame,
|
|
112
|
-
round: this.#ledger.roundCount(frame.key, frame.phase),
|
|
236
|
+
round: this.#ledger.roundCount(frame.key, frame.phase, frame.type),
|
|
113
237
|
route: null,
|
|
114
238
|
capsuleLines: [],
|
|
115
239
|
preflight: verdict,
|
|
@@ -126,11 +250,15 @@ export class Lifecycle {
|
|
|
126
250
|
// review empties the ready batch, so the step routes `done` (an exhausted run),
|
|
127
251
|
// not a phantom next-wave of the just-closed task.
|
|
128
252
|
const route = this.#routeNext(frame);
|
|
253
|
+
// The failure face holds NO next object at all (the `next:` line's absence gate
|
|
254
|
+
// is the NextHop's absence, never `hop: null` — that still renders `done` / the
|
|
255
|
+
// soft-cap / the doc-class rows).
|
|
256
|
+
const failed = outcome.status === "BLOCKED" || outcome.status === "TIMEOUT";
|
|
129
257
|
return {
|
|
130
258
|
frame,
|
|
131
259
|
round,
|
|
132
260
|
route,
|
|
133
|
-
capsuleLines: this.#capsuleLines(frame, outcome, route),
|
|
261
|
+
capsuleLines: this.#capsuleLines(frame, outcome, failed ? null : this.#roundHop(frame, route)),
|
|
134
262
|
termination: outcome.termination,
|
|
135
263
|
};
|
|
136
264
|
}
|
|
@@ -161,6 +289,7 @@ export class Lifecycle {
|
|
|
161
289
|
return null;
|
|
162
290
|
const target = { kind: "wave", tasks: ready };
|
|
163
291
|
const round = this.#roundFor(phase, key);
|
|
292
|
+
const attempt = this.#attemptFor(phase, key, round);
|
|
164
293
|
return {
|
|
165
294
|
type: "wave",
|
|
166
295
|
phase,
|
|
@@ -168,8 +297,17 @@ export class Lifecycle {
|
|
|
168
297
|
target,
|
|
169
298
|
params: this.#paramsOf({ type: "wave", phase, target, round }),
|
|
170
299
|
key,
|
|
300
|
+
attempt,
|
|
171
301
|
};
|
|
172
302
|
}
|
|
303
|
+
/** The attempt number one dispatch takes — allocated ONCE here from the row's
|
|
304
|
+
* records (`RoundNaming#attemptOf`, the naming single source) and shared by the
|
|
305
|
+
* round record and the round log's name. */
|
|
306
|
+
#attemptFor(phase, key, round) {
|
|
307
|
+
return this.#ledger
|
|
308
|
+
.naming()
|
|
309
|
+
.attemptOf(this.#ledger.recordsOf(key, this.#face.type), this.#opOf(phase), round);
|
|
310
|
+
}
|
|
173
311
|
/** The next phase of one wave line — the SAME single derivation the wave gate reads
|
|
174
312
|
* (`Ledger#waveLinePhase` · D26: one fact, one place). The lifecycle's frame
|
|
175
313
|
* frontier and the three-verb WaveGate must agree on the open wave's phase, or a
|
|
@@ -188,6 +326,7 @@ export class Lifecycle {
|
|
|
188
326
|
if (phase === null)
|
|
189
327
|
return null;
|
|
190
328
|
const round = this.#roundFor(phase, key);
|
|
329
|
+
const attempt = this.#attemptFor(phase, key, round);
|
|
191
330
|
return {
|
|
192
331
|
type: this.#face.type,
|
|
193
332
|
phase,
|
|
@@ -195,20 +334,34 @@ export class Lifecycle {
|
|
|
195
334
|
target,
|
|
196
335
|
params: this.#paramsOf({ type: this.#face.type, phase, target, round }),
|
|
197
336
|
key,
|
|
337
|
+
attempt,
|
|
198
338
|
};
|
|
199
339
|
}
|
|
200
340
|
/** The next phase of a single-target line — the doc-revision gate (lifecycle-side:
|
|
201
341
|
* its reviewGate needs the target doc path) then the ledger's SINGLE rounds/routes
|
|
202
342
|
* judge (`Ledger#linePhase`, D40 — the retired lifecycle twin). A CLOSED doc line
|
|
203
|
-
* reopens through the identity verdict (T7)
|
|
204
|
-
*
|
|
205
|
-
*
|
|
206
|
-
*
|
|
343
|
+
* reopens through the identity verdict (T7) — the ONE `Ledger#docReopens` judgment,
|
|
344
|
+
* the same one the dispatch gate reads, so an exit-side drift opens the review lead
|
|
345
|
+
* whatever the round/route state says while a still-pending fix keeps its round
|
|
346
|
+
* (drift never outranks it, §5.5 ② — the gate never names a round this frontier
|
|
347
|
+
* would not frame); an unchanged doc with the pending fix derived opens the fix;
|
|
348
|
+
* the unbound / same-without-pending faces fall through to the shared rounds/routes
|
|
207
349
|
* walk (a completed-fix line reopens review through the fix round's route). */
|
|
208
350
|
#nextLinePhase(key, target, reviewLead) {
|
|
209
351
|
if (target.kind === "plan" || target.kind === "spec") {
|
|
210
352
|
const verdict = this.#ledger.reviewGate(key, target.doc, this.#face.type);
|
|
211
|
-
if (
|
|
353
|
+
if (this.#ledger.docReopens(key, this.#face.type, verdict))
|
|
354
|
+
return reviewLead;
|
|
355
|
+
if (verdict.kind === "same" && verdict.pending)
|
|
356
|
+
return "fix";
|
|
357
|
+
}
|
|
358
|
+
// The branch line's identity is its PLAN document (P21 §4.1): a plan revision
|
|
359
|
+
// after the terminal branch review reopens the branch-review lead, an unchanged
|
|
360
|
+
// plan keeps the line closed. Same gate, same judgment — only the doc path is
|
|
361
|
+
// the line's plan (the audit target itself carries no doc).
|
|
362
|
+
if (target.kind === "branch" && this.#planPath !== null) {
|
|
363
|
+
const verdict = this.#ledger.reviewGate(key, this.#planPath, "branch");
|
|
364
|
+
if (this.#ledger.docReopens(key, "branch", verdict))
|
|
212
365
|
return reviewLead;
|
|
213
366
|
if (verdict.kind === "same" && verdict.pending)
|
|
214
367
|
return "fix";
|
|
@@ -216,25 +369,28 @@ export class Lifecycle {
|
|
|
216
369
|
return this.#ledger.linePhase(key, this.#face.type);
|
|
217
370
|
}
|
|
218
371
|
/** The round number one phase dispatches under: implement = the fixed family (1);
|
|
219
|
-
* the review-lead = the next increment
|
|
372
|
+
* the review-lead = the next increment (every in-register cycle consumes a number);
|
|
373
|
+
* fix = the source review-lead's latest COMPLETED cycle (a failed fix never pushes
|
|
374
|
+
* it forward — a retry is fix-K's attempt + 1, never a phantom fix-(K+1)). */
|
|
220
375
|
#roundFor(phase, key) {
|
|
221
376
|
if (phase === "implement")
|
|
222
377
|
return 1;
|
|
223
378
|
if (phase === "fix") {
|
|
224
|
-
const
|
|
225
|
-
return
|
|
379
|
+
const completed = this.#ledger.completedCycles(key, "review", this.#face.type);
|
|
380
|
+
return completed.length > 0 ? Math.max(...completed) : 1;
|
|
226
381
|
}
|
|
227
382
|
return this.#reviewCount(key) + 1;
|
|
228
383
|
}
|
|
229
384
|
/** The review-lead round count of a key (branch counts its branch-review mode,
|
|
230
385
|
* the others the review mode — the face row's single source). */
|
|
231
386
|
#reviewCount(key) {
|
|
232
|
-
return this.#ledger.roundCount(key, this.#face.product.reviewLead);
|
|
387
|
+
return this.#ledger.roundCount(key, this.#face.product.reviewLead, this.#face.type);
|
|
233
388
|
}
|
|
234
389
|
/** The progress key of a single-target line — the line's STABLE key (find #9 ·
|
|
235
390
|
* spec §6.5/§3.7 — `"branch"` per workspace for the branch line, accumulating
|
|
236
|
-
* across re-reviews;
|
|
237
|
-
* — the argv path copy never resets the
|
|
391
|
+
* across re-reviews; a doc line keys by its target-type word (`"phase-spec"` /
|
|
392
|
+
* `"overall"` / `"plan"` / `"single-spec"`) — the argv path copy never resets the
|
|
393
|
+
* round: a moved argv string (absolute vs
|
|
238
394
|
* relative) must not fork the same line into two ledger rows). The task face
|
|
239
395
|
* never routes here — frames key by the wave key. */
|
|
240
396
|
#lineKey(target) {
|
|
@@ -259,30 +415,33 @@ export class Lifecycle {
|
|
|
259
415
|
}
|
|
260
416
|
case "branch":
|
|
261
417
|
return { round: frame.round };
|
|
262
|
-
case "spec":
|
|
418
|
+
case "phase-spec":
|
|
419
|
+
case "overall":
|
|
263
420
|
case "plan":
|
|
421
|
+
case "single-spec":
|
|
264
422
|
return { round: frame.round };
|
|
265
423
|
}
|
|
266
424
|
}
|
|
267
425
|
// -------------------------------------------------------------------------
|
|
268
426
|
// dispatch → result → bookkeeping
|
|
269
427
|
// -------------------------------------------------------------------------
|
|
270
|
-
/** Bookkeeping — persist the round's handoff carrier and record the
|
|
271
|
-
*
|
|
428
|
+
/** Bookkeeping — persist the round's handoff carrier and record the round. The
|
|
429
|
+
* persisted carrier is either the dispatch's materialized form (the production
|
|
272
430
|
* read-back reconstruct — outcome.carrier, full-replace at the SAME path, so the
|
|
273
431
|
* child's draft becomes the finalized carrier — the two-state single file, the engine is the single
|
|
274
|
-
* author) or the
|
|
275
|
-
*
|
|
276
|
-
*
|
|
277
|
-
*
|
|
278
|
-
*
|
|
279
|
-
*
|
|
280
|
-
*
|
|
281
|
-
*
|
|
282
|
-
* #routeNext). */
|
|
432
|
+
* author) or — on the INJECTED face alone (an outcome carrying no verdict) — the
|
|
433
|
+
* engine-built fallback from the outcome fields. A production round that wrote no
|
|
434
|
+
* carrier is booked with `carrierPath: null` and no file at the handoff path: the
|
|
435
|
+
* completion criterion owns the absence (§3.3), and a re-dispatch's draft read must
|
|
436
|
+
* see the child's own draft, never an engine synthesis of it. A failure round
|
|
437
|
+
* WITHOUT a carrier leaves the child's draft untouched (no-overwrite on failure) but
|
|
438
|
+
* is STILL recorded — every dispatched round lands; "completed" is the record's
|
|
439
|
+
* verdict, never a membership test. Returns the in-register round count (the task
|
|
440
|
+
* done-marking rides the step's C5 route — #markTerminal, after #routeNext). */
|
|
283
441
|
#bookkeep(frame, outcome) {
|
|
284
442
|
const blocked = outcome.status === "BLOCKED" || outcome.status === "TIMEOUT";
|
|
285
|
-
|
|
443
|
+
let carrierPath = null;
|
|
444
|
+
if (outcome.carrier !== undefined || (outcome.verdict === undefined && !blocked)) {
|
|
286
445
|
const op = this.#opOf(frame.phase);
|
|
287
446
|
// T2 — the engine-built fallback rides the FRAME's op-derived plane (never the
|
|
288
447
|
// outcome's field presence): a judge-plane round (review) builds the findings
|
|
@@ -304,38 +463,60 @@ export class Lifecycle {
|
|
|
304
463
|
// (`HandoffSchema.conclusionOf` → rollup(findings)), never a stored field (D27).
|
|
305
464
|
if (plane === "work" && carrier.status === undefined && outcome.status !== undefined)
|
|
306
465
|
carrier.status = outcome.status;
|
|
307
|
-
this.#ledger.persistHandoff(op, frame.type, frame.params, carrier);
|
|
466
|
+
carrierPath = this.#ledger.persistHandoff(op, frame.type, frame.params, carrier);
|
|
308
467
|
}
|
|
309
|
-
|
|
310
|
-
|
|
311
|
-
|
|
312
|
-
|
|
313
|
-
|
|
314
|
-
|
|
315
|
-
|
|
316
|
-
|
|
317
|
-
|
|
318
|
-
//
|
|
319
|
-
// `#
|
|
320
|
-
//
|
|
321
|
-
|
|
322
|
-
|
|
323
|
-
|
|
324
|
-
|
|
325
|
-
|
|
326
|
-
|
|
327
|
-
|
|
328
|
-
|
|
468
|
+
// The recorded CYCLE is the frame's own round — its identity (fix-K ⟷ review-K ·
|
|
469
|
+
// D28): a skipped cycle records its own number, never a flattened ordinal. The
|
|
470
|
+
// attempt was allocated once by the frame builder and rides both the record and
|
|
471
|
+
// the round log's name.
|
|
472
|
+
const record = this.#ledger.recordRound(frame.key, {
|
|
473
|
+
op: this.#opOf(frame.phase),
|
|
474
|
+
cycle: frame.round,
|
|
475
|
+
attempt: frame.attempt ?? 1,
|
|
476
|
+
dispatchBase: outcome.dispatchBase ?? null,
|
|
477
|
+
// The verdict is the dispatch's own judgment when it carries one (the
|
|
478
|
+
// production lifecycle's `#verdictOf`); the injected dispatchers keep the
|
|
479
|
+
// status-derived fallback.
|
|
480
|
+
verdict: outcome.verdict ?? {
|
|
481
|
+
treeClean: outcome.treeClean ?? true,
|
|
482
|
+
targetAction: !blocked,
|
|
483
|
+
},
|
|
484
|
+
violations: outcome.violations ?? [],
|
|
485
|
+
carrierPath,
|
|
486
|
+
}, frame.type);
|
|
487
|
+
// The completed-round revision write-back is gated on the round's VERDICT (a
|
|
488
|
+
// hard-failed round must not bind the current revision — that would silently
|
|
489
|
+
// close the drift identity the round never delivered). WHICH reviewed input the
|
|
490
|
+
// round binds is ONE judgment, shared with the preview face:
|
|
491
|
+
// `ReviewedIdentity.legOf(frame.phase, frame.target.kind)`. Its phases — review,
|
|
492
|
+
// branch-review, fix — are declared there once, and its legs are 1:1 with this
|
|
493
|
+
// class's three `#record…` methods (doc · brief · branch). Two facts stay this
|
|
494
|
+
// face's OWN input, never the judgment: the verdict's `targetAction` (a real run
|
|
495
|
+
// alone holds it) and the plan path (the branch leg's render-from pointer). One
|
|
496
|
+
// asymmetry is preserved: on a wave round whose line carries no plan path the
|
|
497
|
+
// real run records nothing while the preview still states the brief leg. The
|
|
498
|
+
// record methods keep their own defensive narrowing; an unreadable input records
|
|
499
|
+
// nothing (present facts only).
|
|
500
|
+
const leg = record.verdict.targetAction
|
|
501
|
+
? ReviewedIdentity.legOf(frame.phase, frame.target.kind)
|
|
502
|
+
: null;
|
|
503
|
+
if (leg !== null) {
|
|
504
|
+
switch (leg) {
|
|
505
|
+
case "doc":
|
|
329
506
|
this.#recordReviewedDocRevision(frame);
|
|
330
|
-
|
|
507
|
+
break;
|
|
508
|
+
case "brief":
|
|
331
509
|
this.#recordReviewedWaveBrief(frame);
|
|
510
|
+
break;
|
|
511
|
+
case "branch":
|
|
512
|
+
this.#recordReviewedBranchRevision(frame);
|
|
513
|
+
break;
|
|
332
514
|
}
|
|
333
|
-
return count;
|
|
334
515
|
}
|
|
335
|
-
return this.#ledger.roundCount(frame.key, frame.phase);
|
|
516
|
+
return this.#ledger.roundCount(frame.key, frame.phase, frame.type);
|
|
336
517
|
}
|
|
337
|
-
/** The reviewed-revision write-back — bind the
|
|
338
|
-
* line record (the T7 doc + D30 wave identity gates' reopen-compare basis). The
|
|
518
|
+
/** The reviewed-revision write-back — bind the completed round's input revision to
|
|
519
|
+
* the line record (the T7 doc + D30 wave identity gates' reopen-compare basis). The
|
|
339
520
|
* doc face binds its target doc's whole-content revision; the wave face binds its
|
|
340
521
|
* RENDERED BRIEF's revision (D30 — the wave's true judgment input is the brief,
|
|
341
522
|
* never the whole plan: transcript edits outside the wave's task sections must not
|
|
@@ -344,22 +525,39 @@ export class Lifecycle {
|
|
|
344
525
|
#recordReviewedDocRevision(frame) {
|
|
345
526
|
if (frame.target.kind !== "plan" && frame.target.kind !== "spec")
|
|
346
527
|
return;
|
|
347
|
-
|
|
348
|
-
const content = readFileSync(frame.target.doc, "utf8");
|
|
349
|
-
this.#ledger.recordReviewedRevision(frame.key, this.#ledger.refs().docRevision(frame.target.doc, content));
|
|
350
|
-
}
|
|
351
|
-
catch {
|
|
352
|
-
// unreadable input — no reviewed identity recorded (present facts only)
|
|
353
|
-
}
|
|
528
|
+
this.#recordDocRevisionOf(frame.key, frame.target.doc, frame.type);
|
|
354
529
|
}
|
|
355
530
|
/** The wave line's reviewed-brief write-back (D30) — bind the RENDERED brief's
|
|
356
|
-
* revision for the wave's tasks to the row (the D30 wave-gate reopen basis)
|
|
357
|
-
* plan path / underivable brief records nothing
|
|
531
|
+
* revision for the wave's tasks to the row (the D30 wave-gate reopen basis) on a
|
|
532
|
+
* completed review or fix round. Null plan path / underivable brief records nothing
|
|
533
|
+
* (present facts only). */
|
|
358
534
|
#recordReviewedWaveBrief(frame) {
|
|
359
535
|
if (frame.target.kind !== "wave" || this.#planPath === null)
|
|
360
536
|
return;
|
|
361
537
|
this.#ledger.recordReviewedBrief(String(frame.key), this.#planPath);
|
|
362
538
|
}
|
|
539
|
+
/** The branch line's reviewed identity (P21 §4.1) — its PLAN document's
|
|
540
|
+
* `doc-revision`, the same ref kind the doc lines bind (no new ref kind, no commit
|
|
541
|
+
* sha). A later plan revision reopens the line; an unchanged plan keeps it closed.
|
|
542
|
+
* An unreadable plan / a null plan path records nothing (present facts only). */
|
|
543
|
+
#recordReviewedBranchRevision(frame) {
|
|
544
|
+
if (this.#planPath === null)
|
|
545
|
+
return;
|
|
546
|
+
this.#recordDocRevisionOf(frame.key, this.#planPath, frame.type);
|
|
547
|
+
}
|
|
548
|
+
/** The doc-revision write-back body — read the round's document and bind its
|
|
549
|
+
* current revision to the line row (the ONE read + hash + record path the doc and
|
|
550
|
+
* branch legs share; each passes its own path source). An unreadable input records
|
|
551
|
+
* nothing — the line keeps the legacy closed face (present facts only). */
|
|
552
|
+
#recordDocRevisionOf(key, path, identity) {
|
|
553
|
+
try {
|
|
554
|
+
const content = readFileSync(path, "utf8");
|
|
555
|
+
this.#ledger.recordReviewedRevision(key, this.#ledger.refs().docRevision(path, content), identity);
|
|
556
|
+
}
|
|
557
|
+
catch {
|
|
558
|
+
// unreadable input — no reviewed identity recorded (present facts only)
|
|
559
|
+
}
|
|
560
|
+
}
|
|
363
561
|
/** Mark the wave done when the concluding route says its line closed — the C5
|
|
364
562
|
* verdict is the single closure gate (terminal ⇔ route.kind ∈ {done, next-wave},
|
|
365
563
|
* the v1.20 closure side): a clean review or a blocker-free fix closes the wave
|
|
@@ -375,6 +573,28 @@ export class Lifecycle {
|
|
|
375
573
|
const waveTarget = frame.target;
|
|
376
574
|
for (const id of waveTarget.tasks)
|
|
377
575
|
this.#state.markDone(id);
|
|
576
|
+
// The closure's OTHER historical fact (P21 §5.1): the plan's task set at the
|
|
577
|
+
// instant this wave closed. It is the append-vs-stall basis the wave gate reads
|
|
578
|
+
// later — recorded here, at the one point that knows the wave just closed, and
|
|
579
|
+
// never re-derived (a later plan revision must not rewrite the history).
|
|
580
|
+
this.#recordPlanSnapshot(frame);
|
|
581
|
+
}
|
|
582
|
+
/** Record the closing wave's plan-task snapshot — the plan's CURRENT task-id set
|
|
583
|
+
* read from the plan document (`#planPath`, the same source the brief renders
|
|
584
|
+
* from) through the contract parse face. An unreadable plan or a null plan path
|
|
585
|
+
* records nothing: the snapshot is a present fact only, never a fabricated `[]`
|
|
586
|
+
* (an absent snapshot reads conservatively as "stall" in the wave gate). */
|
|
587
|
+
#recordPlanSnapshot(frame) {
|
|
588
|
+
if (this.#planPath === null)
|
|
589
|
+
return;
|
|
590
|
+
try {
|
|
591
|
+
const lines = readFileSync(this.#planPath, "utf8").split("\n");
|
|
592
|
+
const parsed = new PlanDocType("plan").parse(lines);
|
|
593
|
+
this.#ledger.recordPlanTasks(String(frame.key), parsed.taskBlocks.map((block) => block.id));
|
|
594
|
+
}
|
|
595
|
+
catch {
|
|
596
|
+
// unreadable plan — skip the snapshot (present facts only)
|
|
597
|
+
}
|
|
378
598
|
}
|
|
379
599
|
/** The handoff-family op of a phase — branch-review rides the review family. */
|
|
380
600
|
#opOf(phase) {
|
|
@@ -400,29 +620,91 @@ export class Lifecycle {
|
|
|
400
620
|
#routeState() {
|
|
401
621
|
return this.#face.nextSemantics.batch ? this.#state : EMPTY_RUN_STATE;
|
|
402
622
|
}
|
|
623
|
+
/** The line's OWN next-hop object — the LINE FRONTIER assembly: this lifecycle's
|
|
624
|
+
* frame facts handed to the ONE derivation (`Ledger#nextHopOf`): the recorded
|
|
625
|
+
* round's route, the line's completed records, the drift-aware gate and the
|
|
626
|
+
* injected station discrimination. The nullable route is handed over UNJUDGED — the
|
|
627
|
+
* assembly owns the exit-side decision (a closed line's `null` route is where the
|
|
628
|
+
* drift reopen lands). Serves `peekNext` and the capsule's spec-less degradation
|
|
629
|
+
* only; the capsule's ordinary hop is the pipeline frontier's assembly
|
|
630
|
+
* (`#roundHop`). The failure face's absent hop is the CALLER's fact (`advance`
|
|
631
|
+
* passes null for a BLOCKED/TIMEOUT round), never a second short-circuit here. */
|
|
632
|
+
#hopOf(frame, route) {
|
|
633
|
+
const target = this.#routeTarget(frame);
|
|
634
|
+
return this.#ledger.nextHopOf({
|
|
635
|
+
type: frame.type,
|
|
636
|
+
key: frame.key,
|
|
637
|
+
route,
|
|
638
|
+
target,
|
|
639
|
+
doc: this.#docOf(frame),
|
|
640
|
+
// The wave closure's NEXT-line fact (P21 §4.2) rides the derivation's input
|
|
641
|
+
// face — the retired render-side patch parameter is gone, the fact is not.
|
|
642
|
+
nextLineOpen: frame.type === "wave" ? this.#branchLineOpen() : undefined,
|
|
643
|
+
// The wave line's OWN drift fact (D30): the reason cell's second source. Only
|
|
644
|
+
// the wave face injects it — every doc line reads its gate verdict instead.
|
|
645
|
+
briefDrift: frame.type === "wave" ? this.#ledger.briefDrifted(String(frame.key)) : undefined,
|
|
646
|
+
docClassOf: (candidate) => this.#docClassOf(candidate),
|
|
647
|
+
});
|
|
648
|
+
}
|
|
649
|
+
/** The line's judged document — the doc lines' own path, the branch line's plan
|
|
650
|
+
* (its identity document, P21 §4.1); null off the doc faces. */
|
|
651
|
+
#docOf(frame) {
|
|
652
|
+
if (frame.target.kind === "plan" || frame.target.kind === "spec")
|
|
653
|
+
return frame.target.doc;
|
|
654
|
+
if (frame.target.kind === "branch")
|
|
655
|
+
return this.#planPath;
|
|
656
|
+
return null;
|
|
657
|
+
}
|
|
658
|
+
/** The round's rendered hop — the PIPELINE frontier's ONE assembly when the node
|
|
659
|
+
* holds a spec document (the object the board's `next:` row renders, so the two
|
|
660
|
+
* faces state one hop), this line's own frame-keyed assembly otherwise. The
|
|
661
|
+
* degradation key is `#specPath === null` and nothing else: a plan-only phase is the
|
|
662
|
+
* ordinary spec-less shape, and there the frontier's rules anchor on an absent
|
|
663
|
+
* identity face (rule 3) — it would print a transition the line has already taken. */
|
|
664
|
+
#roundHop(frame, route) {
|
|
665
|
+
if (this.#specPath === null)
|
|
666
|
+
return this.#hopOf(frame, route);
|
|
667
|
+
return this.#frontier.hopOf(this.#pipelineInput(), { docClassOf: (c) => this.#docClassOf(c) });
|
|
668
|
+
}
|
|
669
|
+
/** The pipeline frontier's four declared cells — assembled once from the injected
|
|
670
|
+
* facts so no second judge is introduced here. */
|
|
671
|
+
#pipelineInput() {
|
|
672
|
+
return {
|
|
673
|
+
specType: this.#specType,
|
|
674
|
+
specPath: this.#specPath,
|
|
675
|
+
planPath: this.#planPath,
|
|
676
|
+
planGraph: this.#planGraph,
|
|
677
|
+
};
|
|
678
|
+
}
|
|
679
|
+
/** Whether the branch line has a dispatchable open round — the wave closure's
|
|
680
|
+
* NEXT-line fact (P21 §4.2), delegated to the pipeline frontier's ONE judge (the
|
|
681
|
+
* shared hop assembly's sixth cell). The lifecycle now holds no copy of the gate /
|
|
682
|
+
* route combination. */
|
|
683
|
+
#branchLineOpen() {
|
|
684
|
+
return this.#frontier.branchLineOpen(this.#planPath);
|
|
685
|
+
}
|
|
403
686
|
/** The capsule lines of one step — empty unless a capsule is attached (the non-hard
|
|
404
|
-
* interaction point). A success round carries the
|
|
405
|
-
*
|
|
406
|
-
*
|
|
407
|
-
*
|
|
408
|
-
*
|
|
409
|
-
|
|
410
|
-
|
|
411
|
-
#capsuleLines(frame, outcome, route) {
|
|
687
|
+
* interaction point). A success round carries the handoff carrier path; a failure
|
|
688
|
+
* round (TIMEOUT / BLOCKED) carries the crash record as its handoff cell, emitted
|
|
689
|
+
* only when that record exists (a no-host BLOCKED writes none). The fix round's
|
|
690
|
+
* disposition summary is handed to the capsule as its `summary` — the render places
|
|
691
|
+
* it between the status line and the `next:` row (P22 §10). */
|
|
692
|
+
#capsuleLines(frame, outcome, hop) {
|
|
693
|
+
const summary = outcome.dispositionsSummary;
|
|
412
694
|
if (this.#capsule === null)
|
|
413
|
-
return [];
|
|
695
|
+
return summary === undefined ? [] : [summary];
|
|
414
696
|
const op = this.#opOf(frame.phase);
|
|
415
697
|
const failure = outcome.status === "BLOCKED" || outcome.status === "TIMEOUT";
|
|
416
|
-
const
|
|
698
|
+
const naming = this.#ledger.naming();
|
|
417
699
|
// The failure face's handoff is the crash record — the engine's own postmortem
|
|
418
700
|
// artifact, its existence the emission condition; the success face keeps the
|
|
419
|
-
// round's handoff carrier path.
|
|
420
|
-
|
|
421
|
-
const
|
|
701
|
+
// round's handoff carrier path. The name derives from the frame through the ONE
|
|
702
|
+
// naming source (`RoundNaming`), the same name the lifecycle wrote it under.
|
|
703
|
+
const crash = failure ? this.#ledger.readCrash(naming.crashName(frame)) : null;
|
|
422
704
|
const handoff = crash !== null
|
|
423
|
-
?
|
|
705
|
+
? naming.crashPath(frame)
|
|
424
706
|
: this.#ledger.handoffPath(op, frame.type, frame.params);
|
|
425
|
-
return this.#capsule.emit(outcome.status,
|
|
707
|
+
return this.#capsule.emit(outcome.status, handoff, hop, crash !== null, summary);
|
|
426
708
|
}
|
|
427
709
|
/** The frame's RouteTarget — the dispatch-ready literal's target identity (the
|
|
428
710
|
* frame's own facts: the wave task key · the branch line key · the doc path).
|
|
@@ -442,8 +724,10 @@ export class Lifecycle {
|
|
|
442
724
|
id: "branch",
|
|
443
725
|
plan: this.#planPath ?? undefined,
|
|
444
726
|
};
|
|
445
|
-
case "spec":
|
|
727
|
+
case "phase-spec":
|
|
728
|
+
case "overall":
|
|
446
729
|
case "plan":
|
|
730
|
+
case "single-spec":
|
|
447
731
|
return {
|
|
448
732
|
type: frame.type,
|
|
449
733
|
id: frame.target.doc,
|