@oscaner-skills/cdd-engine 4.3.0 → 4.5.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.
@@ -22,6 +22,8 @@ import { PlanDocType } from "../contract/doc.js";
22
22
  import { PlanTaskBlocksReader } from "../contract/task-blocks.js";
23
23
  import { Ledger, } from "./ledger.js";
24
24
  import { NextStepRouter } from "./next.js";
25
+ import { PipelineFrontier } from "./pipeline.js";
26
+ import { ReviewedIdentity } from "./reviewed-identity.js";
25
27
  /** The empty run state — a target line with no task frontier (branch/spec/plan):
26
28
  * the frontier query faces are always empty (a single-target line never continues
27
29
  * a batch) and markDone is a no-op. */
@@ -143,8 +145,23 @@ export class Lifecycle {
143
145
  * keep their existing behavior). */
144
146
  #preflight;
145
147
  /** The workspace plan path — the `next:` implement literal's required `--plan`
146
- * 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. */
147
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;
148
165
  /** The pipeline-station discrimination the hop derivation injects (P22 §5.2) —
149
166
  * the SAME face read the capsule/board use (`BoardView.docClassOf`). The
150
167
  * composition root passes it; the session-plane default keys by target type
@@ -160,16 +177,20 @@ export class Lifecycle {
160
177
  this.#capsule = opts.capsule ?? null;
161
178
  this.#preflight = opts.preflight ?? null;
162
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);
163
184
  this.#docClassOf = opts.docClassOf ?? Lifecycle.#docClassByType;
164
185
  }
165
186
  /** The session-plane default discrimination — the target type's own pipeline key.
166
- * Every target type but the standalone `single-spec` IS a pipeline key (the
167
- * `PipelineKey` derivation), so the map is the identity plus the one terminal row
168
- * (a single-spec carries no pipeline seam). The declaration-reading judgment (a
169
- * doc's `doc-type:`) belongs to the face plane; the composition root injects it as
170
- * `BoardView.docClassOf`. */
187
+ * Every declared target type IS a pipeline key (the `PipelineKey` derivation), so
188
+ * the map is the identity: a standalone `single-spec` reads as `single-spec` and its
189
+ * closure hands off to `cdd-plan` like any other spec line. The declaration-reading
190
+ * judgment (a doc's `doc-type:`) belongs to the face plane; the composition root
191
+ * injects it as `BoardView.docClassOf`. */
171
192
  static #docClassByType(target) {
172
- return target.type === "single-spec" ? "terminal" : target.type;
193
+ return target.type;
173
194
  }
174
195
  /** The face row this instance drives. */
175
196
  face() {
@@ -185,10 +206,10 @@ export class Lifecycle {
185
206
  * cursor pre-checks the next step against the requested verb before it advances
186
207
  * (a mismatch must not consume the round: advance() dispatches on entry — the
187
208
  * {16,22,24} bug's loop reordered lookahead-after-dispatch and spent the next
188
- * phase's round in the same invocation). The returned `hop` is the SAME `NextHop`
189
- * object the board and the CLI rejection message read (P22 §5.2's fourth read
190
- * face): one derivation over this line's facts, never a lookahead-only copy.
191
- * Null = the run is exhausted / capped (no open frame → no line to name). */
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). */
192
213
  peekNext() {
193
214
  const frame = this.#openFrame();
194
215
  if (frame === null)
@@ -237,7 +258,7 @@ export class Lifecycle {
237
258
  frame,
238
259
  round,
239
260
  route,
240
- capsuleLines: this.#capsuleLines(frame, outcome, failed ? null : this.#hopOf(frame, route)),
261
+ capsuleLines: this.#capsuleLines(frame, outcome, failed ? null : this.#roundHop(frame, route)),
241
262
  termination: outcome.termination,
242
263
  };
243
264
  }
@@ -463,36 +484,41 @@ export class Lifecycle {
463
484
  violations: outcome.violations ?? [],
464
485
  carrierPath,
465
486
  }, frame.type);
466
- // The completed-review revision write-back is gated on the round's VERDICT (a
467
- // hard-failed review must not bind the current revision — that would silently
468
- // close the drift identity the review never judged). The doc line and the wave
469
- // line each bind their OWN reviewed revision (T7 doc · T11 wave / D16 / D30): a
470
- // completed review binds the CURRENT revision of the reviewed input — read at
471
- // bookkeep, the clean-tree dispatch gate keeps the read-only review's input
472
- // stable across the round. For a doc line that input is the target doc (the
473
- // whole-content doc-revision). For a wave line it is the RENDERED BRIEF —
474
- // `#recordReviewedWaveBrief` → `recordReviewedBrief(String(frame.key),
475
- // #planPath)` hashes the brief the plan renders to, holding #planPath only as
476
- // the plan the brief renders FROM (the render-from POINTER, not the hashed
477
- // identity; the wave gate derives the plan path FROM this record, so
478
- // cli.ts/preflight.ts stay untouched). The two legs do NOT share one gate —
479
- // each ref kind carries its own reviewed identity. An unreadable input records
480
- // nothing (present facts only); a null plan path (no plan fact) leaves a legacy
481
- // wave row — null stays backward compatible.
482
- if (record.verdict.targetAction &&
483
- (frame.phase === "review" || frame.phase === "branch-review")) {
484
- if (frame.target.kind === "plan" || frame.target.kind === "spec")
485
- this.#recordReviewedDocRevision(frame);
486
- else if (frame.target.kind === "wave")
487
- this.#recordReviewedWaveBrief(frame);
488
- else if (frame.target.kind === "branch")
489
- this.#recordReviewedBranchRevision(frame);
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":
506
+ this.#recordReviewedDocRevision(frame);
507
+ break;
508
+ case "brief":
509
+ this.#recordReviewedWaveBrief(frame);
510
+ break;
511
+ case "branch":
512
+ this.#recordReviewedBranchRevision(frame);
513
+ break;
514
+ }
490
515
  }
491
516
  return this.#ledger.roundCount(frame.key, frame.phase, frame.type);
492
517
  }
493
- /** The reviewed-revision write-back — bind the reviewed input's revision to the
494
- * line record (the T7 doc + D30 wave identity gates' reopen-compare basis). The
495
- * doc face binds its target doc's whole-content revision; the wave face binds its
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
520
+ * doc face binds its target doc's BODY revision (the front matter and
521
+ * `## Change history` projected away, P26 T1); the wave face binds its
496
522
  * RENDERED BRIEF's revision (D30 — the wave's true judgment input is the brief,
497
523
  * never the whole plan: transcript edits outside the wave's task sections must not
498
524
  * void a reviewed wave). An unreadable input records nothing — the line keeps the
@@ -503,8 +529,9 @@ export class Lifecycle {
503
529
  this.#recordDocRevisionOf(frame.key, frame.target.doc, frame.type);
504
530
  }
505
531
  /** The wave line's reviewed-brief write-back (D30) — bind the RENDERED brief's
506
- * revision for the wave's tasks to the row (the D30 wave-gate reopen basis). Null
507
- * plan path / underivable brief records nothing (present facts only). */
532
+ * revision for the wave's tasks to the row (the D30 wave-gate reopen basis) on a
533
+ * completed review or fix round. Null plan path / underivable brief records nothing
534
+ * (present facts only). */
508
535
  #recordReviewedWaveBrief(frame) {
509
536
  if (frame.target.kind !== "wave" || this.#planPath === null)
510
537
  return;
@@ -519,7 +546,7 @@ export class Lifecycle {
519
546
  return;
520
547
  this.#recordDocRevisionOf(frame.key, this.#planPath, frame.type);
521
548
  }
522
- /** The doc-revision write-back body — read the reviewed document and bind its
549
+ /** The doc-revision write-back body — read the round's document and bind its
523
550
  * current revision to the line row (the ONE read + hash + record path the doc and
524
551
  * branch legs share; each passes its own path source). An unreadable input records
525
552
  * nothing — the line keeps the legacy closed face (present facts only). */
@@ -594,14 +621,15 @@ export class Lifecycle {
594
621
  #routeState() {
595
622
  return this.#face.nextSemantics.batch ? this.#state : EMPTY_RUN_STATE;
596
623
  }
597
- /** The line's ONE next-hop object (§5.2) — this lifecycle's facts handed to the
598
- * ONE derivation (`Ledger#nextHopOf`): the recorded round's route, the line's
599
- * completed records, the drift-aware gate and the injected station
600
- * discrimination. The nullable route is handed over UNJUDGED — the assembly owns
601
- * the exit-side decision (a closed line's `null` route is where the drift reopen
602
- * lands), so the frontier face reads the same object the board and the gate read.
603
- * The failure face's absent hop is the CALLER's fact (`advance` passes null for a
604
- * BLOCKED/TIMEOUT round), never a second short-circuit here. */
624
+ /** The line's OWN next-hop object — the LINE FRONTIER assembly: this lifecycle's
625
+ * frame facts handed to the ONE derivation (`Ledger#nextHopOf`): the recorded
626
+ * round's route, the line's completed records, the drift-aware gate and the
627
+ * injected station discrimination. The nullable route is handed over UNJUDGED — the
628
+ * assembly owns the exit-side decision (a closed line's `null` route is where the
629
+ * drift reopen lands). Serves `peekNext` and the capsule's spec-less degradation
630
+ * only; the capsule's ordinary hop is the pipeline frontier's assembly
631
+ * (`#roundHop`). The failure face's absent hop is the CALLER's fact (`advance`
632
+ * passes null for a BLOCKED/TIMEOUT round), never a second short-circuit here. */
605
633
  #hopOf(frame, route) {
606
634
  const target = this.#routeTarget(frame);
607
635
  return this.#ledger.nextHopOf({
@@ -613,6 +641,9 @@ export class Lifecycle {
613
641
  // The wave closure's NEXT-line fact (P21 §4.2) rides the derivation's input
614
642
  // face — the retired render-side patch parameter is gone, the fact is not.
615
643
  nextLineOpen: frame.type === "wave" ? this.#branchLineOpen() : undefined,
644
+ // The wave line's OWN drift fact (D30): the reason cell's second source. Only
645
+ // the wave face injects it — every doc line reads its gate verdict instead.
646
+ briefDrift: frame.type === "wave" ? this.#ledger.briefDrifted(String(frame.key)) : undefined,
616
647
  docClassOf: (candidate) => this.#docClassOf(candidate),
617
648
  });
618
649
  }
@@ -625,25 +656,40 @@ export class Lifecycle {
625
656
  return this.#planPath;
626
657
  return null;
627
658
  }
659
+ /** The round's rendered hop — the PIPELINE frontier's ONE assembly when the node
660
+ * holds a spec document (the object the board's `next:` row renders, so the two
661
+ * faces state one hop), this line's own frame-keyed assembly otherwise. The
662
+ * degradation key is `#specPath === null` and nothing else: a plan-only phase is the
663
+ * ordinary spec-less shape, and there the frontier's rules anchor on an absent
664
+ * identity face (rule 3) — it would print a transition the line has already taken. */
665
+ #roundHop(frame, route) {
666
+ if (this.#specPath === null)
667
+ return this.#hopOf(frame, route);
668
+ return this.#frontier.hopOf(this.#pipelineInput(), { docClassOf: (c) => this.#docClassOf(c) });
669
+ }
670
+ /** The pipeline frontier's four declared cells — assembled once from the injected
671
+ * facts so no second judge is introduced here. */
672
+ #pipelineInput() {
673
+ return {
674
+ specType: this.#specType,
675
+ specPath: this.#specPath,
676
+ planPath: this.#planPath,
677
+ planGraph: this.#planGraph,
678
+ };
679
+ }
628
680
  /** Whether the branch line has a dispatchable open round — the wave closure's
629
- * NEXT-line fact (P21 §4.2), read HERE (the ledger-holding side) from the two
630
- * already-registered ledger faces: the branch row's drift-aware gate (the plan
631
- * moved past its reviewed doc-revision) or a still-active C5 hop. `undefined` when
632
- * no plan fact exists (the wave row keeps its plain station). */
681
+ * NEXT-line fact (P21 §4.2), delegated to the pipeline frontier's ONE judge (the
682
+ * shared hop assembly's sixth cell). The lifecycle now holds no copy of the gate /
683
+ * route combination. */
633
684
  #branchLineOpen() {
634
- if (this.#planPath === null)
635
- return undefined;
636
- const gate = this.#ledger.reviewGate("branch", this.#planPath, "branch");
637
- if (gate.kind === "open")
638
- return true;
639
- return this.#ledger.lineRoute("branch", "branch") !== null;
685
+ return this.#frontier.branchLineOpen(this.#planPath);
640
686
  }
641
687
  /** The capsule lines of one step — empty unless a capsule is attached (the non-hard
642
688
  * interaction point). A success round carries the handoff carrier path; a failure
643
689
  * round (TIMEOUT / BLOCKED) carries the crash record as its handoff cell, emitted
644
690
  * only when that record exists (a no-host BLOCKED writes none). The fix round's
645
691
  * disposition summary is handed to the capsule as its `summary` — the render places
646
- * it between the status line and the trailing `next:` literal (P22 §10). */
692
+ * it between the status line and the `next:` row (P22 §10). */
647
693
  #capsuleLines(frame, outcome, hop) {
648
694
  const summary = outcome.dispositionsSummary;
649
695
  if (this.#capsule === null)
@@ -31,7 +31,7 @@
31
31
  //
32
32
  // Module-level exports are types / the class — zero behavior-carrying bare
33
33
  // functions (the plan's zero-bare-function discipline).
34
- import { MAX_TASKS_PER_WAVE } from "./next.js";
34
+ import { MAX_TASKS_PER_WAVE, WAVE_GATE_REASON } from "./next.js";
35
35
  /**
36
36
  * WaveGate — the three-verb unified wave gate (implement / review / fix share the
37
37
  * single gate). One OOP method: vet(requested, verb) judges the request against
@@ -65,7 +65,7 @@ export class WaveGate {
65
65
  if (!this.#appendedSinceClosure(ledger, closed, closedMembers, openMembers)) {
66
66
  return {
67
67
  ok: false,
68
- reason: "mixed-batch",
68
+ reason: WAVE_GATE_REASON.mixedBatch,
69
69
  message: this.#fill(wordsGate.mixedBatch, {
70
70
  batch: batch.join(","),
71
71
  closed: closedMembers.join(","),
@@ -85,7 +85,7 @@ export class WaveGate {
85
85
  if (open.length > MAX_TASKS_PER_WAVE) {
86
86
  return {
87
87
  ok: false,
88
- reason: "wave-too-wide",
88
+ reason: WAVE_GATE_REASON.waveTooWide,
89
89
  message: this.#fill(wordsGate.waveTooWide, {
90
90
  tasks: openKey,
91
91
  max: String(MAX_TASKS_PER_WAVE),
@@ -100,7 +100,7 @@ export class WaveGate {
100
100
  if (asked.length > MAX_TASKS_PER_WAVE) {
101
101
  return {
102
102
  ok: false,
103
- reason: "too-many-tasks",
103
+ reason: WAVE_GATE_REASON.tooManyTasks,
104
104
  message: this.#fill(wordsGate.tooManyTasks, {
105
105
  tasks: requestedKey,
106
106
  count: String(asked.length),
@@ -116,7 +116,7 @@ export class WaveGate {
116
116
  if (!exact) {
117
117
  return {
118
118
  ok: false,
119
- reason: "split",
119
+ reason: WAVE_GATE_REASON.split,
120
120
  message: this.#fill(wordsGate.split, { requested: requestedKey, open: openKey }),
121
121
  open,
122
122
  phases: this.#phasesOf(ledger, open),
@@ -130,7 +130,7 @@ export class WaveGate {
130
130
  if (phase !== verb) {
131
131
  return {
132
132
  ok: false,
133
- reason: "wrong-phase",
133
+ reason: WAVE_GATE_REASON.wrongPhase,
134
134
  message: this.#fill(wordsGate.wrongPhase, { phase: phase ?? "held" }),
135
135
  open,
136
136
  phases,
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@oscaner-skills/cdd-engine",
3
- "version": "4.3.0",
3
+ "version": "4.5.0",
4
4
  "description": "CDD engine CLIs: task runner, docs reviewer, branch reviewer, harness selector.",
5
5
  "type": "module",
6
6
  "engines": {