@oscaner-skills/cdd-engine 4.6.0 → 4.8.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.
@@ -137,8 +137,8 @@ const RETIRED_SPEC_LINE_KEYS = new Set([
137
137
  ]);
138
138
  /**
139
139
  * ReviewRefs — the review-reference face (T25): the two-layer bindings (`docRevision`
140
- * — the doc hash from its content · `briefRevision` — the rendered brief's hash from
141
- * the plan it renders from) and the same-ref predicate (the SAME identity already
140
+ * — the doc hash from its content · `briefRevision` — the wave's task-only projection
141
+ * hash from the plan it renders from) and the same-ref predicate (the SAME identity already
142
142
  * bound is refused, never silently re-reviewed). The face is the ledger's review-ref
143
143
  * derivation point — typed data, zero prose.
144
144
  */
@@ -153,8 +153,10 @@ export class ReviewRefs {
153
153
  const projected = new DocBodyProjection().project(body);
154
154
  return { kind: "doc-revision", doc, doc_hash: this.#hash(projected) };
155
155
  }
156
- /** The brief-revision two-layer binding (D30) — the plan path the brief renders
157
- * from + the RENDERED brief content's hash (the wave line's reviewed identity). */
156
+ /** The brief-revision two-layer binding (D30, narrowed by P29 §2.2) — the plan path
157
+ * the brief renders from + the hash of the brief's TASK-ONLY projection (the wave
158
+ * line's reviewed identity; `## Constraints` is dispatch input, not a fingerprint
159
+ * byte). */
158
160
  briefRevision(plan, briefContent) {
159
161
  return { kind: "brief-revision", plan, brief_hash: this.#hash(briefContent) };
160
162
  }
@@ -205,9 +207,11 @@ export class Ledger {
205
207
  * through the same face). Injected with this ledger's own ref face, so the
206
208
  * same-ref predicate keeps one definition. */
207
209
  #identity = new LineIdentity(this.#refs);
208
- /** The task-brief renderer (D30) — the wave line's judgment-input derivation:
209
- * the wave's reviewed basis is the RENDERED brief's content, never the whole
210
- * plan (a backfill touching other tasks must not void a reviewed wave). */
210
+ /** The task-brief renderer (D30 · P29 §2.2) — the wave line's judgment-input
211
+ * derivation: the wave's reviewed basis is the TASK-ONLY projection
212
+ * (`BriefRenderer#taskBody`), never the whole plan and never the `## Constraints`
213
+ * dispatch input (a backfill touching other tasks, or a Constraints reword, must
214
+ * not void a reviewed wave). */
211
215
  #brief = new BriefRenderer();
212
216
  /** The round-naming single source over this ledger's workspace — the crash
213
217
  * artifact names derive here (zero second derivation). */
@@ -414,27 +418,27 @@ export class Ledger {
414
418
  row.reviewedRevision = revision;
415
419
  this.writeProgress(data);
416
420
  }
417
- /** Record a wave line's reviewed BRIEF revision (D30) — the RENDERED brief's
418
- * content hash for the wave's tasks: the wave's true judgment input is the brief
419
- * (§5: the wave's task sections + the plan's `## Constraints`), never the whole
420
- * plan. A backfill touching OTHER tasks leaves this brief byte-identical, so the
421
- * reviewed wave is not spuriously reopened (the backfill's whole point). An
421
+ /** Record a wave line's reviewed BRIEF revision (D30) — the hash of the wave's
422
+ * TASK-ONLY projection (P29 §2.2: the task sections, `## Constraints` excluded).
423
+ * A backfill touching OTHER tasks leaves this projection byte-identical, and so
424
+ * does a Constraints reword, so the reviewed wave is not spuriously reopened. An
422
425
  * underivable brief records nothing (present facts only — the legacy face holds). */
423
426
  recordReviewedBrief(waveKey, planPath) {
424
427
  const revision = this.#briefRevision(waveKey, planPath);
425
428
  if (revision !== null)
426
429
  this.recordReviewedRevision(waveKey, revision);
427
430
  }
428
- /** The wave line's reviewed-basis revision (D30) — the RENDERED brief's content
429
- * hash for the wave's tasks (the `plan` layer is the plan the brief renders from,
430
- * the `brief_hash` layer the brief's own digest). Null when the plan is unreadable
431
+ /** The wave line's reviewed-basis revision (D30) — the hash of the wave's TASK-ONLY
432
+ * projection (`BriefRenderer#taskBody`: the task sections, `## Constraints`
433
+ * excluded — P29 §2.2). The `plan` layer is the plan the brief renders from, the
434
+ * `brief_hash` layer the projection's own digest. Null when the plan is unreadable
431
435
  * or a requested task is absent (present facts only). */
432
436
  #briefRevision(waveKey, planPath) {
433
437
  try {
434
438
  const tasks = waveKey.split(",").map((part) => Number(part));
435
439
  // The plan layer is stored repoRoot-relative (P9 T4 §2.7) — one basis with
436
440
  // every persisted path field; the read erases to absolute at the syscall edge.
437
- const brief = this.#brief.render(readFileSync(this.#abs(planPath), "utf8"), tasks);
441
+ const brief = this.#brief.taskBody(readFileSync(this.#abs(planPath), "utf8"), tasks);
438
442
  return this.#refs.briefRevision(this.#rel(planPath), brief);
439
443
  }
440
444
  catch {
@@ -492,6 +496,19 @@ export class Ledger {
492
496
  * is on record or the doc is unreadable (the legacy closed face keeps its
493
497
  * generic message — only present facts land). */
494
498
  docLineVerdict(key, doc, identity = null) {
499
+ const pair = this.#docRevisionPair(key, doc, identity);
500
+ if (pair === null)
501
+ return null;
502
+ return this.#identity.verdict(pair.reviewed, { ref: pair.current }) === "same"
503
+ ? "same"
504
+ : "drift";
505
+ }
506
+ /** The doc line's two revision sides — the recorded reviewed revision and the one
507
+ * the document holds NOW (null when no reviewed revision is on record or the doc is
508
+ * unreadable). ONE read for TWO consumers: the drift verdict (`docLineVerdict`) and
509
+ * the refusal's mandatory diagnosis (`docDriftHashes`), so the two can never
510
+ * compare different bytes. */
511
+ #docRevisionPair(key, doc, identity) {
495
512
  const reviewed = this.reviewedDocRevisionOf(key, identity);
496
513
  if (reviewed === null)
497
514
  return null;
@@ -501,12 +518,35 @@ export class Ledger {
501
518
  // false-drift comparison never reads one document as two.
502
519
  const rel = this.#rel(doc);
503
520
  const current = this.#refs.docRevision(rel, readFileSync(this.#abs(doc), "utf8"));
504
- return this.#identity.verdict(reviewed, { ref: current }) === "same" ? "same" : "drift";
521
+ return { reviewed, current };
505
522
  }
506
523
  catch {
507
524
  return null;
508
525
  }
509
526
  }
527
+ /** The doc line's drift diagnosis (§2.5) — the layer's line key (the document path
528
+ * the review bound, on the ONE persisted basis) and both hash ends. Null when there
529
+ * is no recorded revision or the document is unreadable: a diagnosis never invents
530
+ * a fact. */
531
+ docDriftHashes(key, doc, identity = null) {
532
+ const pair = this.#docRevisionPair(key, doc, identity);
533
+ if (pair === null)
534
+ return null;
535
+ return {
536
+ line: pair.reviewed.doc,
537
+ recorded: pair.reviewed.doc_hash,
538
+ current: pair.current.doc_hash,
539
+ };
540
+ }
541
+ /** The wave line's drift diagnosis (§2.5) — the line key is the wave batch key, the
542
+ * hashes are the recorded vs current TASK-ONLY brief projections. Null when the row
543
+ * holds no brief identity or the plan's task section is underivable. */
544
+ briefDriftHashes(waveKey) {
545
+ const pair = this.#briefRevisionPair(waveKey);
546
+ if (pair === null)
547
+ return null;
548
+ return { line: waveKey, recorded: pair.reviewed.brief_hash, current: pair.current.brief_hash };
549
+ }
510
550
  /** The review-gate method (T8 · §3.5) — the doc line's review request judgment +
511
551
  * the phase advance: the shared docLineVerdict comparison reports the drift, and
512
552
  * the REOPEN's scope is the callers' ONE judgment (`Ledger#docReopens` — an
@@ -540,7 +580,7 @@ export class Ledger {
540
580
  * blockers outstanding) is the one-way fix hop carrying the source review's handoff
541
581
  * path. Null when the wave line holds no open hop (drained / deferred by the soft
542
582
  * cap). The D16/T11 revision precheck belongs HERE, not in a per-consumer copy: a
543
- * completed wave review bound the RENDERED BRIEF it judged to the row (run.ts
583
+ * completed wave review bound the BRIEF's task-only projection to the row (run.ts
544
584
  * bookkeep `#recordReviewedWaveBrief` → `#briefRevision`), and a drifted BRIEF
545
585
  * reopens the wave at review regardless of the fix-awaited round state (the
546
586
  * stale-revision findings are voided — new revision, new review). Same revision + a
@@ -601,24 +641,37 @@ export class Ledger {
601
641
  return "fix";
602
642
  return null;
603
643
  }
604
- /** The wave line's brief-drift verdict (D30) — the wave's CURRENT rendered brief
605
- * vs the recorded reviewed brief. `true` when the wave's judgment input moved past
606
- * the reviewed basis (the wave reopens at review). A plan edit OUTSIDE the wave's
607
- * task sections + `## Constraints` leaves the brief byte-identical → `false`
608
- * (the append-only backfill case the whole-plan hash wrongly flagged). An
609
- * underivable brief (unreadable plan / absent task) is not a drift (present
610
- * facts only). A row bound to a non-brief kind (a doc kind, only via a corrupt
611
- * hand-write) is not a wave brief — no drift. The ONE public read of the fact:
612
- * `waveLineRoute`'s D30 leg and the next-hop assembly's reason-only `briefDrift`
613
- * cell both come through here. */
644
+ /** The wave line's brief-drift verdict (D30) — the wave's CURRENT task-only
645
+ * projection (P29 §2.2) vs the recorded reviewed projection. `true` when the
646
+ * wave's judgment input moved past the reviewed basis (the wave reopens at
647
+ * review). A plan edit outside the wave's task sections — a `## Constraints`
648
+ * reword included, since Constraints is dispatch input rather than a fingerprint
649
+ * byte — leaves the task-only projection byte-identical → `false` (the
650
+ * append-only backfill case the whole-plan hash wrongly flagged). An underivable
651
+ * brief (unreadable plan / absent task) is not a drift (present facts only). A
652
+ * row bound to a non-brief kind (a doc kind, only via a corrupt hand-write) is
653
+ * not a wave brief — no drift. The ONE public read of the fact: `waveLineRoute`'s
654
+ * D30 leg and the next-hop assembly's reason-only `briefDrift` cell both come
655
+ * through here. */
614
656
  briefDrifted(waveKey) {
657
+ const pair = this.#briefRevisionPair(waveKey);
658
+ if (pair === null)
659
+ return false;
660
+ return this.#identity.verdict(pair.reviewed, { ref: pair.current }) === "drift";
661
+ }
662
+ /** The wave line's two brief-projection sides — the recorded task-only revision and
663
+ * the one the plan renders NOW (null when the row holds no brief identity or the
664
+ * plan is unreadable / a requested task is absent). ONE read for TWO consumers: the
665
+ * drift predicate (`briefDrifted`) and the refusal's diagnosis
666
+ * (`briefDriftHashes`), so neither can hash a different projection. */
667
+ #briefRevisionPair(waveKey) {
615
668
  const reviewed = this.reviewedRevisionOf(waveKey);
616
669
  if (reviewed === null || reviewed.kind !== "brief-revision")
617
- return false;
670
+ return null;
618
671
  const current = this.#briefRevision(waveKey, reviewed.plan);
619
672
  if (current === null)
620
- return false;
621
- return this.#identity.verdict(reviewed, { ref: current }) === "drift";
673
+ return null;
674
+ return { reviewed, current };
622
675
  }
623
676
  /** The pending-fix derivation — the "doc same + not APPROVED" face (T8): the
624
677
  * latest review round has an outstanding fix AND its conclusion was not an
@@ -635,7 +688,10 @@ export class Ledger {
635
688
  * (a recorded round is a present fact — the same-doc re-review stays refused until
636
689
  * its fix lands). A completed fix (the latest review cycle IS in the fix
637
690
  * completion set) is NOT the pending face — the completed-fix line's re-review
638
- * reopens through the fix round's C5 route (the legacy judgment). */
691
+ * reopens through the fix round's C5 route (the legacy judgment).
692
+ *
693
+ * A SUPERSEDED review (P30 §2.3) is not a candidate: the reopen replaced its
694
+ * judgment, so the fix it awaited is no longer owed. */
639
695
  #pendingFix(key, type) {
640
696
  const data = this.readProgress();
641
697
  if (data === null)
@@ -643,7 +699,7 @@ export class Ledger {
643
699
  const row = _a.rowFor(data, key, type);
644
700
  if (row === undefined)
645
701
  return false;
646
- const reviews = this.#latestCompletedCycleOfRow(row, "review");
702
+ const reviews = this.#latestLiveCycleOfRow(row, "review");
647
703
  if (reviews === 0)
648
704
  return false;
649
705
  if (this.#completedCyclesOfRow(row, "fix").includes(reviews))
@@ -654,6 +710,12 @@ export class Ledger {
654
710
  // stores no status field · D27), never a second read of the carrier here.
655
711
  return carried === null || carried.status === undefined || carried.status !== "APPROVED";
656
712
  }
713
+ /** The line's derived pending-fix fact — the PUBLIC read face of `#pendingFix`
714
+ * (the `--recover` reopen's condition ②, P30 §2.3). One derivation, two readers;
715
+ * never a second walk from the face. */
716
+ pendingFix(key, type) {
717
+ return this.#pendingFix(key, type);
718
+ }
657
719
  /** Read one counter — a failure-category count on record (0 when the file is
658
720
  * missing). The RETIRED key derives from the round records: the soft entries of
659
721
  * every row plus the one each dirty-tree observation derives (design spec §3.3) —
@@ -778,7 +840,7 @@ export class Ledger {
778
840
  if (row === undefined)
779
841
  return { kind: "review" };
780
842
  const reviewLead = targetFaces[type].product.reviewLead;
781
- const reviews = this.#latestCompletedCycleOfRow(row, reviewLead);
843
+ const reviews = this.#latestLiveCycleOfRow(row, reviewLead);
782
844
  if (reviews === 0)
783
845
  return { kind: "review" };
784
846
  if (!this.#completedCyclesOfRow(row, "fix").includes(reviews)) {
@@ -814,9 +876,10 @@ export class Ledger {
814
876
  * `reviewGate`); the injected `briefDrift` cell never moves a route — a wave's
815
877
  * exit-side station (`handoff`) is never rewritten into a review;
816
878
  * · the REASON cell adds the caller-injected wave brief-drift fact to that
817
- * verdict, so a drifted wave names `doc-drift` without a second judgment.
879
+ * verdict, so a drifted wave names `brief-drift` without a second judgment —
880
+ * the document's own movement keeps `doc-drift` (§2.3: two facts, two tokens).
818
881
  * The ONE exception to the route being the caller's is the drift-reopened doc
819
- * line: the gate's `drift` verdict IS its reopen, and the closure-side route the
882
+ * line: the gate's `docDrift` verdict IS its reopen, and the closure-side route the
820
883
  * count table recorded predates the document movement — so the assembly hands the
821
884
  * derivation the reopened review hop in that case. A presentation-level
822
885
  * substitution: the count table's judgment (`NextStepRouter#next`) stays the only
@@ -837,13 +900,14 @@ export class Ledger {
837
900
  // The face axis is the ONE verdict this assembly reads (spec §5.2's doc-class
838
901
  // discrimination): no target carries no judgeable class (the bare terminal).
839
902
  const verdict = input.target === null ? "terminal" : input.docClassOf(input.target);
840
- // The REASON cell's drift value — `drift` above plus the caller-injected wave
841
- // brief-drift fact. The two are kept apart: only `drift` drives the route
842
- // substitution, so a wave's exit-side station keeps its bytes while its `reason:`
843
- // row still names the movement.
903
+ // The REASON cell's drift values — the doc verdict plus the caller-injected wave
904
+ // brief-drift fact, each landing on ITS own boolean (§2.3). The two are kept
905
+ // apart: only `docDrift` drives the route substitution, so a wave's exit-side
906
+ // station keeps its bytes while its `reason:` row still names the movement — and
907
+ // names it with the brief's own token, never the document's.
844
908
  return this.#router.nextHop({
845
909
  target: input.target,
846
- gate: { drift: drift || (input.briefDrift ?? false) },
910
+ gate: { docDrift: drift, briefDrift: input.briefDrift ?? false },
847
911
  verdict,
848
912
  route,
849
913
  nextLineOpen: input.nextLineOpen,
@@ -905,6 +969,44 @@ export class Ledger {
905
969
  const cycles = this.#completedCyclesOfRow(row, mode);
906
970
  return cycles.length > 0 ? Math.max(...cycles) : 0;
907
971
  }
972
+ /** The latest completed cycle of a row + mode that no later round SUPERSEDED — the
973
+ * active-hop read of a reopenable line (P30 §2.3: `--recover` replaced the old
974
+ * review's judgment, so it may no longer lead this line's hop). Deliberately a
975
+ * SEPARATE reader from `#latestCompletedCycleOfRow`: closure is a ledger-wide-order
976
+ * fact, and a supersede must never make a closed line look open (`#rowClosed` and the
977
+ * wave-line closure judgment keep the unfiltered read). 0 when none. */
978
+ #latestLiveCycleOfRow(row, mode) {
979
+ const op = RoundRecords.opOf(mode);
980
+ if (op === null)
981
+ return 0;
982
+ const cycles = RoundRecords.of(row)
983
+ .filter((record) => record.op === op && record.verdict.targetAction && record.supersededBy === undefined)
984
+ .map((record) => record.cycle);
985
+ return cycles.length > 0 ? Math.max(...cycles) : 0;
986
+ }
987
+ /** Stamp a completed review round as SUPERSEDED (P30 §2.3) — the `--recover` reopen'
988
+ * s ONE write. It writes no fake completed fix: the old review keeps its own verdict
989
+ * and gains `supersededBy: { cycle, cause: "recover" }`, and the fix identity stays
990
+ * with its requesting review's cycle (D28 unchanged). Idempotent: a second stamp of
991
+ * the same record is a no-op rewrite. Returns whether a completed review of that
992
+ * cycle was stamped. */
993
+ supersedeReview(key, type, cycle, byCycle) {
994
+ const data = this.readProgress();
995
+ if (data === null)
996
+ return false;
997
+ const row = _a.rowFor(data, key, type);
998
+ if (row === undefined)
999
+ return false;
1000
+ const records = [...RoundRecords.of(row)];
1001
+ const index = records.findIndex((record) => record.op === "review" && record.cycle === cycle && record.verdict.targetAction);
1002
+ const target = records[index];
1003
+ if (target === undefined)
1004
+ return false;
1005
+ records[index] = { ...target, supersededBy: { cycle: byCycle, cause: "recover" } };
1006
+ row.rounds = records;
1007
+ this.writeProgress(data);
1008
+ return true;
1009
+ }
908
1010
  /** One mode's completed cycles on a row — the row-level twin of `completedCycles`. */
909
1011
  #completedCyclesOfRow(row, mode) {
910
1012
  const op = RoundRecords.opOf(mode);
@@ -5,8 +5,9 @@
5
5
  // single identity face all three read:
6
6
  // · spec / plan — the document's `doc-revision` (a hash of the BODY: front matter
7
7
  // and `## Change history` are projected away, P26 T1);
8
- // · wave — the RENDERED brief's `brief-revision` (its task sections plus the
9
- // plan's `## Constraints` — a plan edit elsewhere is not a drift);
8
+ // · wave — the RENDERED brief's `brief-revision` over its TASK-ONLY
9
+ // projection (P29 §2.2: `## Constraints` is dispatch input, never a
10
+ // fingerprint byte — a plan edit elsewhere is not a drift);
10
11
  // · branch — its plan document's `doc-revision` (the SAME kind, no new ref
11
12
  // kind, no commit sha — the ledger keeps no second code identity).
12
13
  //
@@ -99,6 +99,9 @@ export const DISPATCH_REASON = {
99
99
  closedLine: { token: "closed-line", leg: "line" },
100
100
  faceClosed: { token: "face-closed", leg: "line" },
101
101
  // station — the signs a `next:` hop is named by
102
+ /** A wave line's TASK-ONLY projection moved past the one its review bound. */
103
+ briefDrift: { token: "brief-drift", leg: "station" },
104
+ /** A document's revision moved past the one its review bound. */
102
105
  docDrift: { token: "doc-drift", leg: "station" },
103
106
  softCap: { token: "soft-cap", leg: "station" },
104
107
  taskOpen: { token: "task-open", leg: "station" },
@@ -114,8 +117,12 @@ export const WAVE_GATE_REASON = {
114
117
  wrongPhase: DISPATCH_REASON.wrongPhase.token,
115
118
  };
116
119
  /** The named accessors for `NextHop.reason` — every value is the table's own token
117
- * (one spelling source; the hop reason domain spans both the line and station legs). */
120
+ * (one spelling source; the hop reason domain spans both the line and station legs).
121
+ * `briefDrift` and `docDrift` are TWO facts, never one: a wave brief's task-only
122
+ * projection vs a document's revision (§2.3), so a reader never has to guess which
123
+ * identity moved from the token alone. */
118
124
  export const NEXT_HOP_REASON = {
125
+ briefDrift: DISPATCH_REASON.briefDrift.token,
119
126
  docDrift: DISPATCH_REASON.docDrift.token,
120
127
  pendingFix: DISPATCH_REASON.pendingFix.token,
121
128
  closedLine: DISPATCH_REASON.closedLine.token,
@@ -281,15 +288,19 @@ export class NextStepRouter {
281
288
  }
282
289
  /** The named fact behind the hop — one `NEXT_HOP_REASON` row, in this order: the
283
290
  * soft cap · a pending fix · a drift-reopened line (its reviewed identity moved —
284
- * a doc revision or a wave's brief revision) · an open line advancing · an
285
- * unjudgeable doc class · a closed face · the closed line's handoff. Drift never
286
- * outranks a pending fix (an unclosed line's blocker keeps the fix hop). */
291
+ * the wave brief's task-only projection, or a document's revision) · an open line
292
+ * advancing · an unjudgeable doc class · a closed face · the closed line's handoff.
293
+ * Drift never outranks a pending fix (an unclosed line's blocker keeps the fix hop),
294
+ * and the two drift kinds never share a token: the wave brief's movement is
295
+ * `brief-drift`, a document revision's is `doc-drift` (§2.3). */
287
296
  #reasonOf(input, route, verdict) {
288
297
  if (route?.kind === "soft-cap")
289
298
  return NEXT_HOP_REASON.softCap;
290
299
  if (route?.kind === "fix")
291
300
  return NEXT_HOP_REASON.pendingFix;
292
- if (route?.kind === "review" && input.gate.drift)
301
+ if (route?.kind === "review" && input.gate.briefDrift)
302
+ return NEXT_HOP_REASON.briefDrift;
303
+ if (route?.kind === "review" && input.gate.docDrift)
293
304
  return NEXT_HOP_REASON.docDrift;
294
305
  if (route !== null && this.hopOf(route, _a.#faceOf(verdict)) !== null)
295
306
  return NEXT_HOP_REASON.taskOpen;
@@ -79,7 +79,7 @@ export class PreFlight {
79
79
  gates.push("in-flight");
80
80
  const inFlight = await ctx.inflight.inspect();
81
81
  checked.push(this.#inFlightRow(inFlight));
82
- const held = this.#inFlightRefusal(inFlight, ctx.stealStale === true);
82
+ const held = this.#inFlightRefusal(inFlight, ctx.recover === true);
83
83
  if (held !== null) {
84
84
  return this.#refusal({
85
85
  ok: false,
@@ -223,9 +223,9 @@ export class PreFlight {
223
223
  }
224
224
  /** The in-flight gate's refusal — the three-state judgment + the explicit takeover
225
225
  * flag. A live holder is always refused (the flag never crosses "alive"); a dead
226
- * holder or a corrupt-record-with-lock passes only under `stealStale`; a corrupt
226
+ * holder or a corrupt-record-with-lock passes only under `recover`; a corrupt
227
227
  * record with no lock behind it is no holder at all (pass, named on the row). */
228
- #inFlightRefusal(state, stealStale) {
228
+ #inFlightRefusal(state, recover) {
229
229
  if (state.kind === "held") {
230
230
  if (state.alive) {
231
231
  return {
@@ -233,14 +233,14 @@ export class PreFlight {
233
233
  message: this.#words.inFlightBlocked(state.record, true),
234
234
  };
235
235
  }
236
- if (stealStale)
236
+ if (recover)
237
237
  return null;
238
238
  return {
239
239
  reason: "held",
240
240
  message: this.#words.inFlightBlocked(state.record, false),
241
241
  };
242
242
  }
243
- if (state.kind === "corrupt" && state.locked && !stealStale) {
243
+ if (state.kind === "corrupt" && state.locked && !recover) {
244
244
  return {
245
245
  reason: "corrupt-record",
246
246
  message: this.#words.inFlightWords().corruptLocked,
@@ -518,20 +518,22 @@ export class Lifecycle {
518
518
  /** The reviewed-revision write-back — bind the completed round's input revision to
519
519
  * the line record (the T7 doc + D30 wave identity gates' reopen-compare basis). The
520
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
522
- * RENDERED BRIEF's revision (D30 — the wave's true judgment input is the brief,
523
- * never the whole plan: transcript edits outside the wave's task sections must not
524
- * void a reviewed wave). An unreadable input records nothing — the line keeps the
521
+ * `## Change history` projected away, P26 T1); the wave face binds its TASK-ONLY
522
+ * brief projection's revision (D30 · P29 §2.2 — the wave's true judgment input is
523
+ * the brief's task sections, never the whole plan and never the `## Constraints`
524
+ * dispatch input: transcript edits outside the wave's task sections must not void a
525
+ * reviewed wave). An unreadable input records nothing — the line keeps the
525
526
  * legacy closed face (only present facts land, never an invented identity). */
526
527
  #recordReviewedDocRevision(frame) {
527
528
  if (frame.target.kind !== "plan" && frame.target.kind !== "spec")
528
529
  return;
529
530
  this.#recordDocRevisionOf(frame.key, frame.target.doc, frame.type);
530
531
  }
531
- /** The wave line's reviewed-brief write-back (D30) — bind the RENDERED brief's
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). */
532
+ /** The wave line's reviewed-brief write-back (D30 · P29 §2.2) — bind the wave's
533
+ * TASK-ONLY projection revision (`BriefRenderer#taskBody` — the same face the
534
+ * lifecycle hashes) to the row (the D30 wave-gate reopen basis) on a completed
535
+ * review or fix round. Null plan path / underivable brief records nothing (present
536
+ * facts only). */
535
537
  #recordReviewedWaveBrief(frame) {
536
538
  if (frame.target.kind !== "wave" || this.#planPath === null)
537
539
  return;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@oscaner-skills/cdd-engine",
3
- "version": "4.6.0",
3
+ "version": "4.8.0",
4
4
  "description": "CDD engine CLIs: task runner, docs reviewer, branch reviewer, harness selector.",
5
5
  "type": "module",
6
6
  "engines": {