@oscaner-skills/cdd-engine 3.0.0 → 3.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (143) hide show
  1. package/{src-next/bin.ts → dist/bin.js} +18 -21
  2. package/dist/contract/declare.js +998 -0
  3. package/dist/contract/doc.js +565 -0
  4. package/dist/contract/frontmatter.js +209 -0
  5. package/dist/contract/home-extractors.js +379 -0
  6. package/dist/contract/invariants.js +1030 -0
  7. package/dist/contract/judge.js +109 -0
  8. package/dist/contract/lint.js +206 -0
  9. package/dist/contract/project.js +371 -0
  10. package/dist/contract/skill-anatomy.js +156 -0
  11. package/dist/contract/translate.js +85 -0
  12. package/dist/face/artifacts.js +189 -0
  13. package/dist/face/board-view.js +522 -0
  14. package/dist/face/capsule.js +141 -0
  15. package/dist/face/cli.js +891 -0
  16. package/dist/face/declare.js +241 -0
  17. package/dist/face/gate.js +158 -0
  18. package/dist/face/graph-view.js +66 -0
  19. package/dist/face/host.js +211 -0
  20. package/dist/face/lifecycle.js +603 -0
  21. package/dist/face/preview.js +136 -0
  22. package/dist/face/projection.js +259 -0
  23. package/dist/face/route-render.js +162 -0
  24. package/dist/face/termination.js +482 -0
  25. package/dist/face/words.js +220 -0
  26. package/{src-next/infra/config.ts → dist/infra/config.js} +19 -24
  27. package/{src-next/infra/doc-roots.ts → dist/infra/doc-roots.js} +3 -13
  28. package/dist/infra/git.js +37 -0
  29. package/dist/infra/process.js +22 -0
  30. package/{src-next/infra/root.ts → dist/infra/root.js} +25 -36
  31. package/dist/infra/runtime.js +85 -0
  32. package/dist/infra/workspace.js +276 -0
  33. package/dist/render/brief.js +82 -0
  34. package/dist/render/issue-body.js +129 -0
  35. package/dist/render/skeleton.js +434 -0
  36. package/dist/render/templates.js +520 -0
  37. package/dist/session/faces.js +38 -0
  38. package/dist/session/graph.js +309 -0
  39. package/dist/session/handoff-schema.js +295 -0
  40. package/dist/session/ledger.js +762 -0
  41. package/dist/session/next.js +211 -0
  42. package/dist/session/preflight.js +194 -0
  43. package/dist/session/round-naming.js +73 -0
  44. package/dist/session/run.js +441 -0
  45. package/dist/session/state.js +8 -0
  46. package/dist/session/wave.js +92 -0
  47. package/package.json +5 -5
  48. package/src-next/__tests__/bin.test.ts +0 -128
  49. package/src-next/__tests__/dead-decl.guard.test.ts +0 -39
  50. package/src-next/__tests__/floor.guard.test.ts +0 -69
  51. package/src-next/__tests__/issue-body.guard.test.ts +0 -66
  52. package/src-next/__tests__/phase-suffix.guard.test.ts +0 -72
  53. package/src-next/__tests__/smoke.integration.test.ts +0 -185
  54. package/src-next/__tests__/support/strip-comments.ts +0 -99
  55. package/src-next/__tests__/zero-dep.test.ts +0 -94
  56. package/src-next/contract/__tests__/__snapshots__/project.schema.overall-spec.snap +0 -256
  57. package/src-next/contract/__tests__/__snapshots__/project.schema.phase-spec.snap +0 -165
  58. package/src-next/contract/__tests__/__snapshots__/project.schema.plan.snap +0 -190
  59. package/src-next/contract/__tests__/__snapshots__/project.schema.single-spec.snap +0 -106
  60. package/src-next/contract/__tests__/__snapshots__/project.shape.overall-spec.snap +0 -240
  61. package/src-next/contract/__tests__/__snapshots__/project.shape.phase-spec.snap +0 -165
  62. package/src-next/contract/__tests__/__snapshots__/project.shape.plan.snap +0 -190
  63. package/src-next/contract/__tests__/__snapshots__/project.shape.single-spec.snap +0 -100
  64. package/src-next/contract/__tests__/declare.test.ts +0 -481
  65. package/src-next/contract/__tests__/doc.test.ts +0 -527
  66. package/src-next/contract/__tests__/dockey.guard.test.ts +0 -58
  67. package/src-next/contract/__tests__/edge-conditions.guard.test.ts +0 -81
  68. package/src-next/contract/__tests__/frontmatter.test.ts +0 -164
  69. package/src-next/contract/__tests__/judge.test.ts +0 -1111
  70. package/src-next/contract/__tests__/lint.test.ts +0 -324
  71. package/src-next/contract/__tests__/project.test.ts +0 -460
  72. package/src-next/contract/__tests__/structure-pin.test.ts +0 -186
  73. package/src-next/contract/__tests__/translate.test.ts +0 -96
  74. package/src-next/contract/declare.ts +0 -1071
  75. package/src-next/contract/doc.ts +0 -816
  76. package/src-next/contract/frontmatter.ts +0 -233
  77. package/src-next/contract/home-extractors.ts +0 -397
  78. package/src-next/contract/invariants.ts +0 -1413
  79. package/src-next/contract/judge.ts +0 -151
  80. package/src-next/contract/lint.ts +0 -239
  81. package/src-next/contract/project.ts +0 -656
  82. package/src-next/contract/skill-anatomy.ts +0 -301
  83. package/src-next/contract/translate.ts +0 -113
  84. package/src-next/face/__tests__/board-view.test.ts +0 -1151
  85. package/src-next/face/__tests__/capsule.test.ts +0 -300
  86. package/src-next/face/__tests__/channel-closure.guard.test.ts +0 -129
  87. package/src-next/face/__tests__/cli.test.ts +0 -4897
  88. package/src-next/face/__tests__/face.test.ts +0 -289
  89. package/src-next/face/__tests__/graph-view.test.ts +0 -61
  90. package/src-next/face/__tests__/host.test.ts +0 -24
  91. package/src-next/face/__tests__/install-rows.guard.test.ts +0 -58
  92. package/src-next/face/__tests__/negation.ts +0 -6
  93. package/src-next/face/__tests__/preview.test.ts +0 -374
  94. package/src-next/face/__tests__/projection.test.ts +0 -303
  95. package/src-next/face/__tests__/repo-root.guard.test.ts +0 -120
  96. package/src-next/face/__tests__/termination.test.ts +0 -650
  97. package/src-next/face/__tests__/words.guard.test.ts +0 -93
  98. package/src-next/face/artifacts.ts +0 -248
  99. package/src-next/face/board-view.ts +0 -652
  100. package/src-next/face/capsule.ts +0 -163
  101. package/src-next/face/cli.ts +0 -1028
  102. package/src-next/face/declare.ts +0 -323
  103. package/src-next/face/gate.ts +0 -171
  104. package/src-next/face/graph-view.ts +0 -74
  105. package/src-next/face/host.ts +0 -302
  106. package/src-next/face/lifecycle.ts +0 -725
  107. package/src-next/face/preview.ts +0 -151
  108. package/src-next/face/projection.ts +0 -285
  109. package/src-next/face/route-render.ts +0 -185
  110. package/src-next/face/termination.ts +0 -573
  111. package/src-next/face/words.ts +0 -314
  112. package/src-next/infra/__tests__/infra.test.ts +0 -333
  113. package/src-next/infra/__tests__/root.test.ts +0 -56
  114. package/src-next/infra/git.ts +0 -39
  115. package/src-next/infra/process.ts +0 -34
  116. package/src-next/infra/runtime.ts +0 -132
  117. package/src-next/infra/workspace.ts +0 -322
  118. package/src-next/render/__tests__/render.test.ts +0 -550
  119. package/src-next/render/__tests__/skeleton.test.ts +0 -684
  120. package/src-next/render/brief.ts +0 -121
  121. package/src-next/render/issue-body.ts +0 -162
  122. package/src-next/render/skeleton.ts +0 -502
  123. package/src-next/render/templates.ts +0 -645
  124. package/src-next/session/__tests__/graph.test.ts +0 -277
  125. package/src-next/session/__tests__/handoff-plane.guard.test.ts +0 -48
  126. package/src-next/session/__tests__/handoff-schema.test.ts +0 -310
  127. package/src-next/session/__tests__/ledger.test.ts +0 -745
  128. package/src-next/session/__tests__/next.test.ts +0 -460
  129. package/src-next/session/__tests__/preflight.test.ts +0 -545
  130. package/src-next/session/__tests__/round-naming.test.ts +0 -142
  131. package/src-next/session/__tests__/run.test.ts +0 -1026
  132. package/src-next/session/__tests__/wave-line-phase.guard.test.ts +0 -49
  133. package/src-next/session/__tests__/wave.test.ts +0 -476
  134. package/src-next/session/faces.ts +0 -110
  135. package/src-next/session/graph.ts +0 -411
  136. package/src-next/session/handoff-schema.ts +0 -373
  137. package/src-next/session/ledger.ts +0 -1076
  138. package/src-next/session/next.ts +0 -293
  139. package/src-next/session/preflight.ts +0 -271
  140. package/src-next/session/round-naming.ts +0 -84
  141. package/src-next/session/run.ts +0 -610
  142. package/src-next/session/state.ts +0 -30
  143. package/src-next/session/wave.ts +0 -139
@@ -0,0 +1,762 @@
1
+ // packages/cdd-engine/src-next/session/ledger.ts
2
+ // T9 — the session ledger (design spec §6.1): ONE class owns the four on-disk
3
+ // session artifacts — progress (the fixed key set), handoff (build/name/persist),
4
+ // crash (the lane-crash recovery record) and round (the round carrier). The write
5
+ // authority is the engine alone: every artifact write routes through the ledger's
6
+ // single persist point, so the engine owns the on-disk record of every round.
7
+ //
8
+ // · progress — `progress.json`, the fixed top-level key set (plan + the five
9
+ // failure-category counters, verbatim from engine-config) + the per-key rows
10
+ // (scalar task or the group key string, each carrying its rounds {}).
11
+ // · handoff — the canonical family naming (engine-config handoff namespace), the
12
+ // carrier skeleton (the schema-required identity keys), the single-author write.
13
+ // · crash — `crash-<lane>-<round>.json`, the recovery record (the same-command
14
+ // resume decision source — the resume command + the dead child's tails, never the
15
+ // handoff carrier's union).
16
+ // · round — the round carrier: the handoff presented as the Round the dispatch
17
+ // next-router judges. A fix round carries the SOURCE review's findings (the
18
+ // `--reviews` input content, C5-1), never its own; the consecutive-S1 run is
19
+ // walked from the round history (the review-cycle soft-cap basis).
20
+ //
21
+ // Module-level exports are types / constant data / the class — zero behavior-
22
+ // carrying bare functions (the plan's zero-bare-function discipline).
23
+ var _a;
24
+ import { createHash } from "node:crypto";
25
+ import { readFileSync } from "node:fs";
26
+ import { BriefRenderer } from "../render/brief.js";
27
+ import { targetFaces } from "./faces.js";
28
+ import { HandoffSchema, } from "./handoff-schema.js";
29
+ import { NextStepRouter } from "./next.js";
30
+ import { EMPTY_RUN_STATE } from "./run.js";
31
+ // ---------------------------------------------------------------------------
32
+ // progress — the fixed key set
33
+ // ---------------------------------------------------------------------------
34
+ /** The fixed counter key set — the five engine-config failure-category counters, verbatim. */
35
+ export const PROGRESS_COUNTER_ZERO = {
36
+ timeoutCount: 0,
37
+ contractViolationCount: 0,
38
+ engineSelfWrittenCount: 0,
39
+ engineRecoveryCount: 0,
40
+ harnessAbortCount: 0,
41
+ };
42
+ /**
43
+ * ReviewRefs — the review-reference face (T25): the two-layer bindings (`docRevision`
44
+ * — the doc hash from its content · `briefRevision` — the rendered brief's hash from
45
+ * the plan it renders from) and the same-ref predicate (the SAME identity already
46
+ * bound is refused, never silently re-reviewed). The face is the ledger's review-ref
47
+ * derivation point — typed data, zero prose.
48
+ */
49
+ export class ReviewRefs {
50
+ /** The doc-revision two-layer binding — the doc path + the content-hash revision
51
+ * (sha1 of the reviewed file content — the second layer of the doc ref). */
52
+ docRevision(doc, content) {
53
+ return { kind: "doc-revision", doc, doc_hash: this.#hash(content) };
54
+ }
55
+ /** The brief-revision two-layer binding (D30) — the plan path the brief renders
56
+ * from + the RENDERED brief content's hash (the wave line's reviewed identity). */
57
+ briefRevision(plan, briefContent) {
58
+ return { kind: "brief-revision", plan, brief_hash: this.#hash(briefContent) };
59
+ }
60
+ /** The ref-identity predicate — two refs are the SAME ref when same-kind AND their
61
+ * two-layer identity matches (the layer-1 path + the layer-2 hash). Two refs of
62
+ * different kinds are never the same ref (a doc-revision never equals a
63
+ * brief-revision — the kind IS part of the identity). */
64
+ sameRef(a, b) {
65
+ if (a.kind === "doc-revision" && b.kind === "doc-revision")
66
+ return a.doc === b.doc && a.doc_hash === b.doc_hash;
67
+ if (a.kind === "brief-revision" && b.kind === "brief-revision")
68
+ return a.plan === b.plan && a.brief_hash === b.brief_hash;
69
+ return false;
70
+ }
71
+ /** The content-hash revision — sha1 hex of the reviewed content. */
72
+ #hash(content) {
73
+ // The revision hash is a content digest (a fingerprint of the reviewed bytes),
74
+ // never a commit ref — the full sha1 hex stays unsliced so the bind basis covers
75
+ // the whole content, not a truncated prefix.
76
+ return createHash("sha1").update(content).digest("hex");
77
+ }
78
+ }
79
+ // ---------------------------------------------------------------------------
80
+ // the ledger
81
+ // ---------------------------------------------------------------------------
82
+ /**
83
+ * Ledger — the session's on-disk single author. One instance per workspace;
84
+ * every artifact write (progress / handoff / crash) routes through the same
85
+ * private persist point, so the engine owns the record of every round.
86
+ */
87
+ export class Ledger {
88
+ /** The one dispatch workspace this ledger records. */
89
+ #workspace;
90
+ /** The handoff-family records, keyed by `op.type` — the naming truth the ledger fills. */
91
+ #families;
92
+ /** The C5 next router — the closure-side judge of the round carriers (stateless;
93
+ * the `closedWaves()` read face and the wave gate share the same router). */
94
+ #router = new NextStepRouter();
95
+ /** The handoff-schema face — the conclusion single source (`conclusionOf`), one
96
+ * instance per ledger (the round verdict derives from the face's own plane at
97
+ * judgment time · D27). */
98
+ #handoffSchema = new HandoffSchema();
99
+ /** The review-reference face (T25) — the refKind classification + the same-ref
100
+ * reject, one instance per ledger (the run's bound refs). */
101
+ #refs = new ReviewRefs();
102
+ /** The task-brief renderer (D30) — the wave line's judgment-input derivation:
103
+ * the wave's reviewed basis is the RENDERED brief's content, never the whole
104
+ * plan (a backfill touching other tasks must not void a reviewed wave). */
105
+ #brief = new BriefRenderer();
106
+ constructor(workspace, config) {
107
+ this.#workspace = workspace;
108
+ this.#families = config.handoffNamespace().families;
109
+ }
110
+ /** The review-reference face — the refKind three-type derivation + binding (T25). */
111
+ refs() {
112
+ return this.#refs;
113
+ }
114
+ /** The ledger's repo-basis value object — the ONE conversion exit every persisted
115
+ * path field normalizes through (T1 `RepoRoot` · P9 T4 §2.7). The basis is the
116
+ * workspace root's OWN value object (built once at the root's boundary) — never
117
+ * re-wrapped here (branch-review-1 F2: one basis, one form). */
118
+ #basis() {
119
+ return this.#workspace.root.basis;
120
+ }
121
+ /** Normalize a path value to the canonical repoRoot-relative `RepoPath` — the
122
+ * comparison/write side of the shapes fix (a persisted relative value and an
123
+ * incoming absolute argv value compare on ONE basis). */
124
+ #rel(value) {
125
+ return this.#basis().relativize(value);
126
+ }
127
+ /** Erase a (possibly relative) path value to the absolute syscall string for a
128
+ * read (a legacy relative persisted value resolves against the basis, never
129
+ * `process.cwd()`). */
130
+ #abs(value) {
131
+ return this.#basis().resolve(this.#basis().relativize(value));
132
+ }
133
+ // ---- the single author's write/read primitives ----
134
+ /** Persist a JSON artifact — the ledger's single write point (engine sole author). */
135
+ #persist(name, data) {
136
+ this.#workspace.writeJson(name, data);
137
+ }
138
+ /** Read a JSON artifact; null when missing/corrupt (the ledger's read face keeps the
139
+ * collapsed contract — the tri-state discrimination lives at the read-back
140
+ * reconstruct, which reports a malformed draft's true cause). */
141
+ #read(name) {
142
+ const read = this.#workspace.readJson(name);
143
+ return read.kind === "ok" ? read.value : null;
144
+ }
145
+ // -------------------------------------------------------------------------
146
+ // progress — the fixed key set
147
+ // -------------------------------------------------------------------------
148
+ /** The base progress object — the fixed key set at zero, for a fresh session. */
149
+ emptyProgress() {
150
+ return { ...PROGRESS_COUNTER_ZERO, waves: [] };
151
+ }
152
+ /** Read progress.json; null when missing/corrupt (the ledger never invents state). */
153
+ readProgress() {
154
+ return this.#read("progress.json");
155
+ }
156
+ /** Write progress.json — the progress single-author write. */
157
+ writeProgress(data) {
158
+ this.#persist("progress.json", data);
159
+ }
160
+ /** The ledger-row lookup single point — a scalar key (or the single-task wave key
161
+ * `"1"`) resolves the `{ task }` row; a multi-task wave key (`"1,2"`) the `{ wave }` row. */
162
+ rowFor(data, key) {
163
+ return data.waves.find((row) => row.wave === String(key));
164
+ }
165
+ /** The fresh row for an absent key — always the wave form (a single trivial
166
+ * wave `"1"` is still the `{ wave: "1" }` row — one row form, T26). */
167
+ entryFor(key) {
168
+ return { wave: String(key) };
169
+ }
170
+ /** One mode's recorded cycle numbers on a row — the raw identity list, normalizing a
171
+ * legacy numeric count (`fix: 1`) to its assumed contiguous identity (`[1]`, the old
172
+ * 1:1 assumption). Absent/empty → `[]`. */
173
+ #cyclesOf(row, mode) {
174
+ const raw = row?.rounds?.[mode];
175
+ if (raw === undefined)
176
+ return [];
177
+ return Array.isArray(raw) ? raw : Array.from({ length: raw }, (_unused, index) => index + 1);
178
+ }
179
+ /** The last completed round of a dispatch key + mode — 0 when none on record (the
180
+ * round COUNT: the length of the recorded cycle set — for a contiguous review line
181
+ * this equals the latest cycle, but the identity is the cycle list, never the count). */
182
+ roundCount(key, mode) {
183
+ const data = this.readProgress();
184
+ if (data === null)
185
+ return 0;
186
+ return this.#cyclesOf(this.rowFor(data, key), mode).length;
187
+ }
188
+ /** Whether a dispatch key + mode has a round recorded for a given CYCLE — the
189
+ * identity test the round-read gate uses (a fix cycle that skipped a number is
190
+ * present at its own number, not at its ordinal — D28). */
191
+ roundRecorded(key, mode, cycle) {
192
+ const data = this.readProgress();
193
+ if (data === null)
194
+ return false;
195
+ return this.#cyclesOf(this.rowFor(data, key), mode).includes(cycle);
196
+ }
197
+ /** Record a completed round — the on-disk done record (the ledger edge of the
198
+ * ExecutionState carrier: TaskGraph in memory, the ledger on disk). The round's
199
+ * CYCLE is its identity (fix-K ⟷ review-K · D28), so a skipped cycle records its
200
+ * own number, never a flattened ordinal. The production caller passes the frame's
201
+ * own `round`; the default (the next cycle after the latest) records a sequential
202
+ * round. Creates the row on demand; the write is idempotent per cycle (a re-record
203
+ * of the same cycle does not double it). */
204
+ recordRound(key, mode, cycle) {
205
+ const data = this.readProgress() ?? this.emptyProgress();
206
+ let row = this.rowFor(data, key);
207
+ if (row === undefined) {
208
+ row = this.entryFor(key);
209
+ data.waves.push(row);
210
+ }
211
+ const cycles = [...this.#cyclesOf(row, mode)];
212
+ const recorded = cycle ?? (cycles.length > 0 ? Math.max(...cycles) + 1 : 1);
213
+ if (!cycles.includes(recorded))
214
+ cycles.push(recorded);
215
+ cycles.sort((a, b) => a - b);
216
+ row.rounds = { ...row.rounds, [mode]: cycles };
217
+ this.writeProgress(data);
218
+ return cycles.length;
219
+ }
220
+ /** Record a line's reviewed identity — the identity-aware gate's basis (written
221
+ * when the review round completes: the line reopens on drift from this recorded
222
+ * revision, and BLOCKs revision-aware when unchanged). The kind IS part of the
223
+ * identity: a doc line binds a doc-revision (T7), a wave line a brief-revision
224
+ * (D30) — one row, one reviewed identity. */
225
+ recordReviewedRevision(key, revision) {
226
+ const data = this.readProgress() ?? this.emptyProgress();
227
+ let row = this.rowFor(data, key);
228
+ if (row === undefined) {
229
+ row = this.entryFor(key);
230
+ data.waves.push(row);
231
+ }
232
+ row.reviewedRevision = revision;
233
+ this.writeProgress(data);
234
+ }
235
+ /** Record a wave line's reviewed BRIEF revision (D30) — the RENDERED brief's
236
+ * content hash for the wave's tasks: the wave's true judgment input is the brief
237
+ * (§5: the wave's task sections + the plan's `## Constraints`), never the whole
238
+ * plan. A backfill touching OTHER tasks leaves this brief byte-identical, so the
239
+ * reviewed wave is not spuriously reopened (the backfill's whole point). An
240
+ * underivable brief records nothing (present facts only — the legacy face holds). */
241
+ recordReviewedBrief(waveKey, planPath) {
242
+ const revision = this.#briefRevision(waveKey, planPath);
243
+ if (revision !== null)
244
+ this.recordReviewedRevision(waveKey, revision);
245
+ }
246
+ /** The wave line's reviewed-basis revision (D30) — the RENDERED brief's content
247
+ * hash for the wave's tasks (the `plan` layer is the plan the brief renders from,
248
+ * the `brief_hash` layer the brief's own digest). Null when the plan is unreadable
249
+ * or a requested task is absent (present facts only). */
250
+ #briefRevision(waveKey, planPath) {
251
+ try {
252
+ const tasks = waveKey.split(",").map((part) => Number(part));
253
+ // The plan layer is stored repoRoot-relative (P9 T4 §2.7) — one basis with
254
+ // every persisted path field; the read erases to absolute at the syscall edge.
255
+ const brief = this.#brief.render(readFileSync(this.#abs(planPath), "utf8"), tasks);
256
+ return this.#refs.briefRevision(this.#rel(planPath), brief);
257
+ }
258
+ catch {
259
+ return null;
260
+ }
261
+ }
262
+ /** A line's recorded reviewed identity — null when none on record (a line with no
263
+ * reviewed identity keeps the legacy closed face). Callers narrow by `kind`: a doc
264
+ * line binds a doc-revision, a wave line a brief-revision (the kinds never mix). */
265
+ reviewedRevisionOf(key) {
266
+ const data = this.readProgress();
267
+ if (data === null)
268
+ return null;
269
+ return this.rowFor(data, key)?.reviewedRevision ?? null;
270
+ }
271
+ /** The doc line's recorded reviewed doc revision — the doc-revision narrowing of
272
+ * `reviewedRevisionOf` (null when none on record, or when a non-doc kind sits on
273
+ * the row — a doc line is never a wave line). */
274
+ reviewedDocRevisionOf(key) {
275
+ const reviewed = this.reviewedRevisionOf(key);
276
+ return reviewed !== null && reviewed.kind === "doc-revision" ? reviewed : null;
277
+ }
278
+ /** The doc line's identity verdict (T7) — the current doc revision vs the line's
279
+ * recorded reviewed revision: the ONE shared comparison across the session
280
+ * plane's reopen decision and the face plane's drift gate (both planes
281
+ * out-source the read + the same-ref ruling here — a single error policy).
282
+ * `drift` → the target moved past the reviewed identity (the line reopens);
283
+ * `same` → unchanged (the revision-aware BLOCK). Null when no reviewed revision
284
+ * is on record or the doc is unreadable (the legacy closed face keeps its
285
+ * generic message — only present facts land). */
286
+ docLineVerdict(key, doc) {
287
+ const reviewed = this.reviewedDocRevisionOf(key);
288
+ if (reviewed === null)
289
+ return null;
290
+ try {
291
+ // Both sides on ONE basis (P9 T4 §2.7): the recorded ref is repoRoot-relative;
292
+ // the incoming target (an absolute argv-erasure) is relativized here so the
293
+ // false-drift comparison never reads one document as two.
294
+ const rel = this.#rel(doc);
295
+ const current = this.#refs.docRevision(rel, readFileSync(this.#abs(doc), "utf8"));
296
+ return this.#refs.sameRef(reviewed, current) ? "same" : "drift";
297
+ }
298
+ catch {
299
+ return null;
300
+ }
301
+ }
302
+ /** The review-gate method (T8 · §3.5) — the doc line's review request judgment +
303
+ * the phase advance, doc-revision FIRST: the shared docLineVerdict comparison is
304
+ * the PRIMARY criterion — a drifted doc OPENS the review lead regardless of the
305
+ * round/route state (fix / backfill / user-decision are one case: the stuck
306
+ * "next round is fix after an aborted fix" gate never freezes a revised doc);
307
+ * an unchanged doc yields the `same` verdict (review Convergence anti-spin:
308
+ * the callers' reject/reopen decision — the derived pending fix opens the fix
309
+ * face only, while the no-pending face falls back to the legacy rounds/routes
310
+ * judgment: a completed-fix line's C5-1 route reopens the review lead). The OPEN
311
+ * side performs no disk advance: the round + the revision snapshot land with the
312
+ * round's completion (Ledger#recordRound + the T7 write-back), so a BLOCKED
313
+ * re-review resumes the same round (nothing pre-binds). `unbound` (no identity on
314
+ * record / an unreadable doc) keeps the legacy round/route judgment. The
315
+ * judgment order change is the whole gate: the old rounds/routes-first read made
316
+ * the round/route state shadow the doc movement (the pre-T8 stuck path). */
317
+ reviewGate(key, doc, type) {
318
+ const verdict = this.docLineVerdict(key, doc);
319
+ if (verdict === "drift")
320
+ return { kind: "open" };
321
+ if (verdict === "same") {
322
+ const reviewed = this.reviewedDocRevisionOf(key);
323
+ if (reviewed === null)
324
+ return { kind: "unbound" };
325
+ return { kind: "same", pending: this.#pendingFix(key, type), reviewed };
326
+ }
327
+ return { kind: "unbound" };
328
+ }
329
+ /** The wave line's active C5 Route — the next C5 hop the dispatch engine would run
330
+ * on this wave. A wave with no implement round yet is dispatched whole (`next-wave`
331
+ * carrying the wave key — the engine's `implement`-phase action, rendered as the
332
+ * implement literal); a recorded implement holding no review yet, or a re-review
333
+ * after a blocker-carrying fix, is the review hop; a review awaiting a fix (its own
334
+ * blockers outstanding) is the one-way fix hop carrying the source review's handoff
335
+ * path. Null when the wave line holds no open hop (drained / deferred by the soft
336
+ * cap). The D16/T11 revision precheck belongs HERE, not in a per-consumer copy: a
337
+ * completed wave review bound the RENDERED BRIEF it judged to the row (run.ts
338
+ * bookkeep `#recordReviewedWaveBrief` → `#briefRevision`), and a drifted BRIEF
339
+ * reopens the wave at review regardless of the fix-awaited round state (the
340
+ * stale-revision findings are voided — new revision, new review). Same revision + a
341
+ * pending fix stays at fix (Review Convergence anti-spin); a null record (legacy wave
342
+ * row) keeps the pure round-count derivation. The final leg reads the latest fix
343
+ * round's C5 route under EMPTY_RUN_STATE — the close-side is inert for the
344
+ * review/closure query (only the fix round's own blockers can yield review). The
345
+ * `waveLinePhase` judge below derives its phase word from this route (one walk), and
346
+ * the board's `next:` derivation reads the route itself (D40 — the active hop, never
347
+ * a bare face handoff). */
348
+ waveLineRoute(waveKey) {
349
+ const implemented = this.roundCount(waveKey, "implement");
350
+ if (implemented === 0)
351
+ return { kind: "next-wave", tasks: waveKey };
352
+ const data = this.readProgress();
353
+ const row = data === null ? undefined : this.rowFor(data, waveKey);
354
+ const latestReview = row === undefined ? 0 : this.#latestCycleOfRow(row, "review");
355
+ if (latestReview === 0)
356
+ return { kind: "review" };
357
+ // The latest recorded round is a fix iff a fix is recorded at the latest review's
358
+ // CYCLE (D28 identity — fix-K ⟷ review-K); otherwise it is the latest review itself
359
+ // (its route carries the awaited `fix`). The prior "no fix at the latest review cycle
360
+ // ⇒ pending fix" short-circuit read a re-review-closed line (`review=[1,2] · fix=[1]`)
361
+ // as forever at `fix`, missing the closing review-2 — the router read below is the
362
+ // single judge (the `waveLineRoute` twin of `#rowClosed`).
363
+ const fixRecorded = row !== undefined && this.#cyclesOf(row, "fix").includes(latestReview);
364
+ const carried = this.round(fixRecorded ? "fix" : "review", "wave", { tasks: waveKey }, latestReview);
365
+ if (carried === null)
366
+ return null;
367
+ const route = this.#router.next(EMPTY_RUN_STATE, carried);
368
+ if (route?.kind === "review")
369
+ return { kind: "review" };
370
+ if (route?.kind === "fix") {
371
+ // The fix-awaited face — a drifted wave BRIEF reopens at review (D30/D16), else fix.
372
+ const reviewed = this.reviewedRevisionOf(waveKey);
373
+ if (reviewed !== null && this.#briefDrift(waveKey, reviewed))
374
+ return { kind: "review" };
375
+ return {
376
+ kind: "fix",
377
+ reviews: this.handoffPath("review", "wave", { tasks: waveKey, round: latestReview }),
378
+ };
379
+ }
380
+ return null;
381
+ }
382
+ /** The wave line's open phase — the SINGLE derivation the wave gate AND the
383
+ * lifecycle's frame frontier both read (D26: one fact, one place, read at judgment
384
+ * time), mapped from `waveLineRoute`'s active C5 hop: the not-yet-implemented wave
385
+ * reads `implement`, the review hop `review`, the one-way fix hop `fix`, a drained /
386
+ * soft-capped line null. */
387
+ waveLinePhase(waveKey) {
388
+ const route = this.waveLineRoute(waveKey);
389
+ if (route === null)
390
+ return null;
391
+ if (route.kind === "next-wave")
392
+ return "implement";
393
+ if (route.kind === "review")
394
+ return "review";
395
+ if (route.kind === "fix")
396
+ return "fix";
397
+ return null;
398
+ }
399
+ /** The wave line's brief-drift verdict (D30) — the wave's CURRENT rendered brief
400
+ * vs the recorded reviewed brief. `true` when the wave's judgment input moved past
401
+ * the reviewed basis (the wave reopens at review). A plan edit OUTSIDE the wave's
402
+ * task sections + `## Constraints` leaves the brief byte-identical → `false`
403
+ * (the append-only backfill case the whole-plan hash wrongly flagged). An
404
+ * underivable brief (unreadable plan / absent task) is not a drift (present
405
+ * facts only). A row bound to a non-brief kind (a doc kind, only via a corrupt
406
+ * hand-write) is not a wave brief — no drift. */
407
+ #briefDrift(waveKey, reviewed) {
408
+ if (reviewed.kind !== "brief-revision")
409
+ return false;
410
+ const current = this.#briefRevision(waveKey, reviewed.plan);
411
+ if (current === null)
412
+ return false;
413
+ return !this.#refs.sameRef(reviewed, current);
414
+ }
415
+ /** The pending-fix derivation — the "doc same + not APPROVED" face (T8): the
416
+ * latest review round has an outstanding fix AND its conclusion was not an
417
+ * approval. The identity test is the operable leg (D28): the latest review cycle
418
+ * is ABSENT from the fix cycle set (`roundRecorded(key, "fix", reviews)`) — a
419
+ * membership test, never a `reviews > fixes` count comparison, which would read a
420
+ * phantom pending fix when a cycle was skipped (a drift-voided review-1 → the first
421
+ * fix is cycle 2, present at its own number, not ordinal 1). The status read keeps
422
+ * the derivation's second leg explicit, degrading to the conservative pending on a
423
+ * missing carrier (a recorded round is a present fact — the same-doc re-review
424
+ * stays refused until its fix lands). A completed fix (the latest review cycle IS
425
+ * in the fix set) is NOT the pending face — the completed-fix line's re-review
426
+ * reopens through the fix round's C5 route (the legacy judgment). */
427
+ #pendingFix(key, type) {
428
+ const reviews = this.roundCount(key, "review");
429
+ if (reviews === 0 || this.roundRecorded(key, "fix", reviews))
430
+ return false;
431
+ const carried = this.round("review", type, { round: reviews }, reviews);
432
+ // `carried.status` is the review round's DERIVED conclusion — `round()` sets it
433
+ // through the `HandoffSchema.conclusionOf` single source (the findings carrier
434
+ // stores no status field · D27), never a second read of the carrier here.
435
+ return carried === null || carried.status === undefined || carried.status !== "APPROVED";
436
+ }
437
+ /** Read one counter — a failure-category count on record (0 when the file is missing). */
438
+ counterOf(key) {
439
+ return this.readProgress()?.[key] ?? 0;
440
+ }
441
+ /** Increment the timeout counter — the terminated-round write point (one TIMEOUT
442
+ * round lands, the count goes up by one). The counter's only writer. */
443
+ incrementTimeoutCount() {
444
+ const data = this.readProgress() ?? this.emptyProgress();
445
+ data.timeoutCount += 1;
446
+ this.writeProgress(data);
447
+ return data.timeoutCount;
448
+ }
449
+ // -------------------------------------------------------------------------
450
+ // closedWaves — the closure single read face (v1.20)
451
+ // -------------------------------------------------------------------------
452
+ /**
453
+ * The session's closed task ids — the C5 closure single read face (v1.20): a task
454
+ * is closed exactly when the C5 route of its LATEST recorded round lies on the
455
+ * closure side ({done, next-wave} — the SAME terminal predicate the lifecycle's
456
+ * #markTerminal applies). The retired "any ledger row is done" row-read is gone:
457
+ * an implement-only row NEVER closes (a recorded implement round is not a closure
458
+ * verdict — the structural root of the phantom-closure fix), and a historical
459
+ * merged-wave row naturalizes through its own review/fix pair (the wave row's C5
460
+ * route, never a per-member read). The frontier consumers (the wave gate · the
461
+ * board face) read this face — one closed set, one source.
462
+ */
463
+ closedWaves() {
464
+ const closed = new Set();
465
+ const data = this.readProgress();
466
+ if (data === null)
467
+ return closed;
468
+ for (const row of data.waves) {
469
+ if (this.#rowClosed("wave", { tasks: row.wave }, row)) {
470
+ for (const id of row.wave.split(",").map((part) => Number(part)))
471
+ closed.add(id);
472
+ }
473
+ }
474
+ return closed;
475
+ }
476
+ /** Whether one LINE is closed — the line-level closure judge the board's `next:`
477
+ * derivation and its branch row consume (and `closedWaves()` reads through the
478
+ * same core). The C5 route of the line's LATEST recorded round must lie on the
479
+ * closure side ({done, next-wave}). The key is the line-type constant the round
480
+ * records under ("spec" / "plan" / "branch"); a row with no review round yet
481
+ * (implement-only or absent) holds the line open. One judge, one source: the
482
+ * board never re-derives closure in the face (zero second judge). */
483
+ lineClosed(key, type) {
484
+ const data = this.readProgress();
485
+ if (data === null)
486
+ return false;
487
+ const row = this.rowFor(data, key);
488
+ if (row === undefined)
489
+ return false;
490
+ return this.#rowClosed(type, type === "wave" ? { tasks: String(key) } : {}, row);
491
+ }
492
+ /** The single-target line's active C5 Route — the next C5 hop the dispatch engine
493
+ * would run on this line (the doc/branch faces: the review-lead round judges the
494
+ * live tree; a fix-awaited review, a re-review after a blocker-carrying fix). A line
495
+ * with no review-lead round yet is the review-lead hop (`{kind:"review"}` — the
496
+ * renderer keys the literal off the target type); a review round with findings is
497
+ * the one-way fix hop (carrying the review's handoff); a fix round that still carries
498
+ * blockers is the re-review hop. Null when the line holds no open hop (a clean review
499
+ * / a blocker-free fix closed it — the closure-side routes are not an "active hop").
500
+ * The pending-fix test is the latest review's IDENTITY membership in the fix cycle
501
+ * set (D28) — a count comparison would flatten a skipped cycle into a phantom pending
502
+ * fix. The doc-revision gate is NOT part of this walk — the callers run their own
503
+ * reviewGate first (doc-drift-first ordering). `linePhase` maps this route to its
504
+ * phase word (one walk), and the board's `next:` derivation reads the route itself
505
+ * (D40 — the active hop, never a bare face handoff). */
506
+ lineRoute(key, type) {
507
+ const reviewLead = targetFaces[type].product.reviewLead;
508
+ const reviews = this.roundCount(key, reviewLead);
509
+ if (reviews === 0)
510
+ return { kind: "review" };
511
+ if (!this.roundRecorded(key, "fix", reviews)) {
512
+ const route = this.#lineRoundRoute("review", type, reviews);
513
+ return route?.kind === "fix" ? route : null;
514
+ }
515
+ const route = this.#lineRoundRoute("fix", type, reviews);
516
+ return route?.kind === "review" ? route : null;
517
+ }
518
+ /** The single-target line's open phase — the rounds/routes walk the lifecycle's
519
+ * frame frontier (run.ts #nextLinePhase) and the CLI gate (gate.ts #linePhase)
520
+ * BOTH consume (one judge, one source — the retired twin copies), mapped from
521
+ * `lineRoute`'s active C5 hop: the review-lead hop reads the face's own review-lead
522
+ * mode word (branch→branch-review, the others→review), the fix hop `"fix"`, a closed
523
+ * line null. */
524
+ linePhase(key, type) {
525
+ const route = this.lineRoute(key, type);
526
+ if (route === null)
527
+ return null;
528
+ return route.kind === "review" ? targetFaces[type].product.reviewLead : "fix";
529
+ }
530
+ /** One single-target line round's C5 route — the review-lead / fix round read back
531
+ * through the ledger and judged by the router (null when unreadable). Single-target
532
+ * lines key their handoff params `{ round }` (the run.ts / gate.ts shaping) — the
533
+ * same #roundRoute the closure judge reads, one walk. */
534
+ #lineRoundRoute(op, type, round) {
535
+ return this.#roundRoute(op, type, { round }, round);
536
+ }
537
+ /** Whether a C5 route lies on the closure side — the `{done, next-wave}` terminal
538
+ * predicate SINGLE SOURCE (D40): the lifecycle's #markTerminal, `#rowClosed` and
539
+ * every closure consumer read it here, never a re-typed literal. */
540
+ static routeClosed(route) {
541
+ return route !== null && (route.kind === "done" || route.kind === "next-wave");
542
+ }
543
+ /** Whether one progress row's line is closed — the LATEST recorded round's C5 route
544
+ * lies on the closure side ({done, next-wave}). The latest recorded round is a fix
545
+ * iff a fix is recorded at the latest review's CYCLE (D28 identity — fix-K ⟷
546
+ * review-K); otherwise it is the latest review itself. The prior `Math.min(latestFix,
547
+ * latestReview)` form was WRONG on a re-review-closed line: with `review=[1,2] ·
548
+ * fix=[1]` (review-1 → fix-1 → review-2) it read the STALE fix-1 (whose route is
549
+ * `review`) and missed the closing review-2 (whose route is `done`) — reading the
550
+ * line forever open at fix. The latest recorded round is `review@2` here. A row with
551
+ * no review round yet (implement-only or scheduled) holds the line open. The row's
552
+ * review-lead mode rides the faces table (branch→branch-review, the others→review),
553
+ * so the wave/spec/plan/branch lines share ONE judge. */
554
+ #rowClosed(type, params, row) {
555
+ const latestReview = this.#latestCycleOfRow(row, targetFaces[type].product.reviewLead);
556
+ if (latestReview === 0)
557
+ return false;
558
+ const fixRecorded = this.#cyclesOf(row, "fix").includes(latestReview);
559
+ return _a.routeClosed(this.#roundRoute(fixRecorded ? "fix" : "review", type, params, latestReview));
560
+ }
561
+ /** The latest recorded cycle of a row + mode — 0 when none (the identity read; a
562
+ * skipped cycle reports its own number, never the count). */
563
+ #latestCycleOfRow(row, mode) {
564
+ const cycles = this.#cyclesOf(row, mode);
565
+ return cycles.length > 0 ? Math.max(...cycles) : 0;
566
+ }
567
+ /** The C5 route of one recorded round — null when the round is unreadable (a
568
+ * line whose round was never read cannot be judged closed: only present facts). */
569
+ #roundRoute(op, type, params, round) {
570
+ const carried = this.round(op, type, params, round);
571
+ if (carried === null)
572
+ return null;
573
+ return this.#router.next(EMPTY_RUN_STATE, carried);
574
+ }
575
+ // -------------------------------------------------------------------------
576
+ // handoff — naming / carrier / single-author persist
577
+ // -------------------------------------------------------------------------
578
+ /** The family record of an op/type pair — the engine-config handoff namespace data
579
+ * (loud on an unknown family: the naming table is the single truth, never a second list). */
580
+ #family(op, type) {
581
+ const family = this.#families[`${op}.${type}`];
582
+ if (family === undefined)
583
+ throw new Error(`unknown handoff family: ${op}.${type}`);
584
+ return family;
585
+ }
586
+ /** The handoff FACE of an op/type pair — the family's `schema` selector (work when
587
+ * the family declares none). The face-aware read/write/bookkeep spine (T2): a
588
+ * findings-face round rides the findings writable subset, a work-face round rides
589
+ * the findings-free work subset — never the caller's guess. */
590
+ handoffFaceOf(op, type) {
591
+ return this.#family(op, type).schema ?? "work";
592
+ }
593
+ /** The canonical handoff file name — the family's `{placeholder}` pattern, filled. */
594
+ handoffName(op, type, params = {}) {
595
+ return this.#family(op, type)
596
+ .name.replaceAll("{tasks}", params.tasks ?? "")
597
+ .replaceAll("{round}", String(params.round ?? ""));
598
+ }
599
+ /** The canonical on-disk handoff path. */
600
+ handoffPath(op, type, params = {}) {
601
+ return this.#workspace.resolve(this.handoffName(op, type, params));
602
+ }
603
+ buildHandoff(face, init = {}) {
604
+ const carrier = { artifacts: init.artifacts ?? {} };
605
+ if (face === "findings" || init.findings !== undefined)
606
+ carrier.findings = init.findings;
607
+ return carrier;
608
+ }
609
+ /** Persist a handoff payload at the canonical name — the single-author full-replace
610
+ * write (never a merge: the engine owns the file). Returns the written path. */
611
+ persistHandoff(op, type, params, data) {
612
+ this.#persist(this.handoffName(op, type, params), data);
613
+ return this.handoffPath(op, type, params);
614
+ }
615
+ /** Read a handoff carrier; null when missing/corrupt. */
616
+ readHandoff(op, type, params) {
617
+ return this.#read(this.handoffName(op, type, params));
618
+ }
619
+ // -------------------------------------------------------------------------
620
+ // crash — the lane crash → recovery record
621
+ // -------------------------------------------------------------------------
622
+ /** The crash record file name — `crash-<lane>-<round>.json`. */
623
+ crashName(lane, round) {
624
+ return `crash-${lane}-${round}.json`;
625
+ }
626
+ /** The crash record path. */
627
+ crashPath(lane, round) {
628
+ return this.#workspace.resolve(this.crashName(lane, round));
629
+ }
630
+ /** Write a lane-crash recovery record — the resume decision source (the resume
631
+ * command + the dead child's tails), never the handoff carrier. Returns the record. */
632
+ writeCrash(lane, round, record) {
633
+ this.#persist(this.crashName(lane, round), record);
634
+ return record;
635
+ }
636
+ /** Read a crash record; null when absent/unreadable (a recordless failure round keeps
637
+ * the no-next failure face). */
638
+ readCrash(lane, round) {
639
+ return this.#read(this.crashName(lane, round));
640
+ }
641
+ // -------------------------------------------------------------------------
642
+ // round — the round carrier
643
+ // -------------------------------------------------------------------------
644
+ /** The handoff findings presented as round findings — entries with an unknown severity
645
+ * are dropped (never invented into the judgment domain). */
646
+ #findingsOf(carrier) {
647
+ if (!Array.isArray(carrier.findings))
648
+ return [];
649
+ const findings = [];
650
+ for (const entry of carrier.findings) {
651
+ const severity = entry?.severity;
652
+ if (severity !== "blocker" && severity !== "warn" && severity !== "nit")
653
+ continue;
654
+ const summary = entry?.summary;
655
+ findings.push({ severity, summary: typeof summary === "string" ? summary : undefined });
656
+ }
657
+ return findings;
658
+ }
659
+ /** The blocker count of a handoff carrier's findings — the C5-1 severity count. */
660
+ #blockerCountOf(carrier) {
661
+ if (!Array.isArray(carrier.findings))
662
+ return 0;
663
+ return carrier.findings.filter((entry) => entry?.severity === "blocker").length;
664
+ }
665
+ /** The consecutive-S1 run — how many review rounds ending at `round` (newest first) each
666
+ * carried >=1 blocker finding. The run stops at the first clean review or an unreadable
667
+ * round history (missing/corrupt handoff degrades the count to the conservative baseline,
668
+ * never a throw). */
669
+ #consecutiveS1Run(type, params, round) {
670
+ let run = 0;
671
+ for (let index = round; index >= 1; index--) {
672
+ const carrier = this.readHandoff("review", type, { ...params, round: index });
673
+ if (carrier === null)
674
+ break;
675
+ if (this.#blockerCountOf(carrier) === 0)
676
+ break;
677
+ run += 1;
678
+ }
679
+ return run;
680
+ }
681
+ /** The progress key a round's dispatch records under — the same line-identity key
682
+ * the lifecycle records with (run.ts #lineKey): the wave task key (the only
683
+ * params-bearing face — every other line keys by its line-type constant:
684
+ * `"branch"` / `"spec"` / `"plan"`). */
685
+ #roundKey(type, params) {
686
+ return type === "wave" ? (params.tasks ?? "") : type;
687
+ }
688
+ /** The recorded mode one op's round records its cycle under — the review leg reads
689
+ * the face table's review-lead mode (the single source: branch→branch-review, the
690
+ * others→review), matching `recordRound(frame.key, frame.phase, frame.round)`; the
691
+ * implement/fix legs their own name. */
692
+ #recordedMode(op, type) {
693
+ return op === "review" ? targetFaces[type].product.reviewLead : op;
694
+ }
695
+ /** Read a round's concluding record as the Round the dispatch next-router judges.
696
+ * A round is present ONLY when `recordRound` recorded it (the round verdict's
697
+ * single source): an unrecorded round returns null whatever draft sits on disk —
698
+ * a rejected child's leftover draft is never read back as a completed round
699
+ * (the §2.8 gate; without it a BLOCKED round with a stale draft rendered a
700
+ * contradictory `status: BLOCKED · next: done`). A fix round carries the SOURCE
701
+ * review's findings (C5-1: the `--reviews` input content, never its own
702
+ * carrier); the consecutive-S1 run is walked from the review history.
703
+ * Missing/corrupt evaluated handoff → null too — a fix round whose source review
704
+ * is unreadable is never a zero-findings fabrication: a round whose blocker set
705
+ * was never read must not be judged clean. */
706
+ round(op, type, params, round) {
707
+ // §2.8 — the round-read gate: only a recorded round is a round. The test is the
708
+ // round's IDENTITY (its cycle number), not a count: a fix that skipped a cycle
709
+ // (a drift-voided review → the first fix is cycle 2, not ordinal 1) is present at
710
+ // cycle 2 (D28). A count comparison would flatten that to 1 and refuse the read.
711
+ if (!this.roundRecorded(this.#roundKey(type, params), this.#recordedMode(op, type), round)) {
712
+ return null;
713
+ }
714
+ if (op === "implement") {
715
+ const carrier = this.readHandoff("implement", type, params);
716
+ if (carrier === null)
717
+ return null;
718
+ return {
719
+ phase: "implement",
720
+ findings: [],
721
+ consecutiveS1: 0,
722
+ };
723
+ }
724
+ if (op === "review") {
725
+ const reviewParams = { ...params, round };
726
+ const carrier = this.readHandoff("review", type, reviewParams);
727
+ if (carrier === null)
728
+ return null;
729
+ return {
730
+ phase: "review",
731
+ // The conclusion is DERIVED from the review carrier's own findings at judgment
732
+ // time (D27 · the findings carrier holds no status field) — the single source
733
+ // shared with the fix leg below (`HandoffSchema.conclusionOf`).
734
+ status: this.#handoffSchema.conclusionOf("findings", carrier),
735
+ findings: this.#findingsOf(carrier),
736
+ reviewsPath: this.handoffPath("review", type, reviewParams),
737
+ consecutiveS1: this.#consecutiveS1Run(type, params, round),
738
+ };
739
+ }
740
+ // op === "fix" — the C5-1 fingerprint: the fix round judges the source review's input
741
+ // findings. Missing/corrupt source review OR fix carrier → null (no round on record),
742
+ // matching the review branch's contract: a fix whose blocker set was never read must
743
+ // not be judged a clean zero-findings round — the next-hop derivation cannot close a
744
+ // line it could not read.
745
+ const reviewParams = { ...params, round };
746
+ const reviewCarrier = this.readHandoff("review", type, reviewParams);
747
+ const fixCarrier = this.readHandoff("fix", type, reviewParams);
748
+ if (reviewCarrier === null || fixCarrier === null)
749
+ return null;
750
+ return {
751
+ phase: "fix",
752
+ // The fix round's conclusion derives from ITS OWN carrier's declared plane (the
753
+ // work face reads its status; a docs-fix findings face rolls its findings up) —
754
+ // the same `conclusionOf` single source (D27).
755
+ status: this.#handoffSchema.conclusionOf(this.handoffFaceOf("fix", type), fixCarrier),
756
+ findings: this.#findingsOf(reviewCarrier),
757
+ reviewsPath: this.handoffPath("review", type, reviewParams),
758
+ consecutiveS1: this.#consecutiveS1Run(type, params, round),
759
+ };
760
+ }
761
+ }
762
+ _a = Ledger;