@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.
Files changed (58) hide show
  1. package/README.md +38 -9
  2. package/README.zh-CN.md +44 -10
  3. package/dist/contract/completion-criterion.js +351 -0
  4. package/dist/contract/declare.js +181 -43
  5. package/dist/contract/doc.js +84 -271
  6. package/dist/contract/frontmatter.js +2 -1
  7. package/dist/contract/home-extractors.js +49 -316
  8. package/dist/contract/invariants.js +400 -296
  9. package/dist/contract/judge.js +74 -49
  10. package/dist/contract/lint.js +3 -2
  11. package/dist/contract/liveness-signal.js +103 -0
  12. package/dist/contract/markdown-document.js +410 -0
  13. package/dist/contract/markdown-tree-types.js +6 -0
  14. package/dist/contract/markdown-tree.js +137 -0
  15. package/dist/contract/project.js +1 -1
  16. package/dist/contract/rules.js +106 -0
  17. package/dist/contract/selector-engine.js +332 -0
  18. package/dist/contract/selector-spec.js +74 -0
  19. package/dist/contract/skill-anatomy.js +29 -1
  20. package/dist/contract/task-block-grammar.js +285 -0
  21. package/dist/contract/task-blocks.js +65 -0
  22. package/dist/contract/translate.js +21 -0
  23. package/dist/contract/wave-width.js +15 -0
  24. package/dist/face/board-view.js +382 -172
  25. package/dist/face/capsule.js +73 -88
  26. package/dist/face/cli.js +152 -38
  27. package/dist/face/declare.js +42 -19
  28. package/dist/face/gate.js +119 -40
  29. package/dist/face/init.js +84 -25
  30. package/dist/face/lifecycle.js +540 -123
  31. package/dist/face/plugins.js +70 -2
  32. package/dist/face/preview.js +69 -18
  33. package/dist/face/route-render.js +60 -21
  34. package/dist/face/termination.js +135 -261
  35. package/dist/face/words.js +139 -13
  36. package/dist/infra/atomic.js +15 -0
  37. package/dist/infra/git.js +25 -0
  38. package/dist/infra/proc.js +150 -0
  39. package/dist/infra/round-log.js +104 -0
  40. package/dist/infra/runtime.js +16 -4
  41. package/dist/infra/workspace.js +7 -2
  42. package/dist/render/brief.js +15 -17
  43. package/dist/render/skeleton.js +41 -28
  44. package/dist/render/templates.js +128 -84
  45. package/dist/session/faces.js +47 -20
  46. package/dist/session/graph.js +13 -37
  47. package/dist/session/handoff-schema.js +16 -8
  48. package/dist/session/inflight.js +282 -0
  49. package/dist/session/ledger.js +603 -145
  50. package/dist/session/line-identity.js +33 -0
  51. package/dist/session/next.js +140 -80
  52. package/dist/session/pipeline.js +247 -0
  53. package/dist/session/preflight.js +276 -68
  54. package/dist/session/reviewed-identity.js +54 -0
  55. package/dist/session/round-naming.js +56 -8
  56. package/dist/session/run.js +364 -80
  57. package/dist/session/wave.js +94 -14
  58. package/package.json +13 -3
@@ -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). Null = the run is exhausted / capped. */
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
- return this.#openFrame();
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): a drifted doc opens the review lead
204
- * whatever the round/route state says (the fix-awaited route never freezes a
205
- * revised doc); an unchanged doc with the pending fix derived opens the fix; the
206
- * unbound / same-without-pending faces fall through to the shared rounds/routes
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 (verdict.kind === "open")
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; fix = the source review-lead round. */
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 reviews = this.#reviewCount(key);
225
- return reviews > 0 ? reviews : 1;
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; the doc line keys by its line-type constant `"spec"`/`"plan"`
237
- * — the argv path copy never resets the round: a moved argv string (absolute vs
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 progress round.
271
- * The persisted carrier is either the dispatch's materialized form (the production
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 engine-built fallback from the outcome fields (the hermetic /
275
- * injected dispatchers). A BLOCKED/TIMEOUT round WITHOUT a carrier is neither persisted nor
276
- * recorded — the child's draft (if any) stays untouched (no-overwrite on failure) and the
277
- * frontier re-offers the same round (resume = re-run the same command); a BLOCKED
278
- * round WITH a carrier (e.g. the evidence-contract override — the child's work is
279
- * preserved as the BLOCKED carrier) is persisted but not counted as a completed
280
- * round, so the frontier still re-dispatches it. Returns the round count on record
281
- * (the task done-marking rides the step's C5 route — #markTerminal, after
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
- if (outcome.carrier !== undefined || !blocked) {
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
- if (!blocked) {
310
- // The recorded CYCLE is the frame's own round — its identity (fix-K ⟷ review-K ·
311
- // D28): a skipped cycle records its own number, never a flattened ordinal.
312
- const count = this.#ledger.recordRound(frame.key, frame.phase, frame.round);
313
- // The completed-review revision write-back — the doc line and the wave line
314
- // each bind their OWN reviewed revision (T7 doc · T11 wave / D16 / D30): a
315
- // completed review binds the CURRENT revision of the reviewed input — read at
316
- // bookkeep, the clean-tree dispatch gate keeps the read-only review's input
317
- // stable across the round. For a doc line that input is the target doc (the
318
- // whole-content doc-revision). For a wave line it is the RENDERED BRIEF —
319
- // `#recordReviewedWaveBrief` → `recordReviewedBrief(String(frame.key),
320
- // #planPath)` hashes the brief the plan renders to, holding #planPath only as
321
- // the plan the brief renders FROM (the render-from POINTER, not the hashed
322
- // identity; the wave gate derives the plan path FROM this record, so
323
- // cli.ts/preflight.ts stay untouched). The two legs do NOT share one gate —
324
- // each ref kind carries its own reviewed identity. An unreadable input records
325
- // nothing (present facts only); a null plan path (no plan fact) leaves a legacy
326
- // wave row — null stays backward compatible.
327
- if (frame.phase === "review") {
328
- if (frame.target.kind === "plan" || frame.target.kind === "spec")
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
- else if (frame.target.kind === "wave")
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 reviewed input's revision to 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
- try {
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). Null
357
- * plan path / underivable brief records nothing (present facts only). */
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 real blocker count and the
405
- * handoff carrier path. A failure round (TIMEOUT / BLOCKED) carries no blocker
406
- * cell (its count would be a filler); its handoff cell is the crash record and is
407
- * emitted only when that record exists (a no-host BLOCKED writes none). The
408
- * dispatch-ready `next:` literal rides the frame's own RouteTarget identity
409
- * (type + id — the v1.25 combination point: frame.type + params.tasks + route
410
- * are all present here). */
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 lane = `${op}.${frame.type}`;
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
- const crash = failure ? this.#ledger.readCrash(lane, frame.round) : null;
421
- const blockers = (outcome.findings ?? []).filter((finding) => finding.severity === "blocker").length;
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
- ? this.#ledger.crashPath(lane, frame.round)
705
+ ? naming.crashPath(frame)
424
706
  : this.#ledger.handoffPath(op, frame.type, frame.params);
425
- return this.#capsule.emit(outcome.status, String(blockers), handoff, route, this.#routeTarget(frame), crash !== null);
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,