@oscaner-skills/cdd-engine 2.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.
- package/README.md +2 -2
- package/README.zh-CN.md +2 -2
- package/{src-next/bin.ts → dist/bin.js} +18 -21
- package/dist/contract/declare.js +998 -0
- package/dist/contract/doc.js +565 -0
- package/dist/contract/frontmatter.js +209 -0
- package/dist/contract/home-extractors.js +379 -0
- package/dist/contract/invariants.js +1030 -0
- package/dist/contract/judge.js +109 -0
- package/dist/contract/lint.js +206 -0
- package/dist/contract/project.js +371 -0
- package/dist/contract/skill-anatomy.js +156 -0
- package/dist/contract/translate.js +85 -0
- package/dist/face/artifacts.js +189 -0
- package/dist/face/board-view.js +522 -0
- package/dist/face/capsule.js +141 -0
- package/dist/face/cli.js +891 -0
- package/dist/face/declare.js +241 -0
- package/dist/face/gate.js +158 -0
- package/dist/face/graph-view.js +66 -0
- package/dist/face/host.js +211 -0
- package/dist/face/lifecycle.js +603 -0
- package/dist/face/preview.js +136 -0
- package/dist/face/projection.js +259 -0
- package/dist/face/route-render.js +162 -0
- package/dist/face/termination.js +482 -0
- package/dist/face/words.js +220 -0
- package/{src-next/infra/config.ts → dist/infra/config.js} +19 -24
- package/dist/infra/doc-roots.js +19 -0
- package/dist/infra/git.js +37 -0
- package/dist/infra/process.js +22 -0
- package/dist/infra/root.js +62 -0
- package/dist/infra/runtime.js +85 -0
- package/dist/infra/workspace.js +276 -0
- package/dist/render/brief.js +82 -0
- package/dist/render/issue-body.js +129 -0
- package/dist/render/skeleton.js +434 -0
- package/dist/render/templates.js +520 -0
- package/dist/session/faces.js +38 -0
- package/dist/session/graph.js +309 -0
- package/dist/session/handoff-schema.js +295 -0
- package/dist/session/ledger.js +762 -0
- package/dist/session/next.js +211 -0
- package/dist/session/preflight.js +194 -0
- package/dist/session/round-naming.js +73 -0
- package/dist/session/run.js +441 -0
- package/dist/session/state.js +8 -0
- package/dist/session/wave.js +92 -0
- package/package.json +8 -7
- package/templates/report/issue-body.json +0 -46
- package/src-next/__tests__/bin.test.ts +0 -128
- package/src-next/__tests__/smoke.integration.test.ts +0 -202
- package/src-next/__tests__/zero-dep.test.ts +0 -134
- package/src-next/contract/__tests__/__snapshots__/project.schema.overall-spec.snap +0 -238
- package/src-next/contract/__tests__/__snapshots__/project.schema.phase-spec.snap +0 -153
- package/src-next/contract/__tests__/__snapshots__/project.schema.plan.snap +0 -173
- package/src-next/contract/__tests__/__snapshots__/project.schema.single-spec.snap +0 -89
- package/src-next/contract/__tests__/__snapshots__/project.shape.overall-spec.snap +0 -225
- package/src-next/contract/__tests__/__snapshots__/project.shape.phase-spec.snap +0 -155
- package/src-next/contract/__tests__/__snapshots__/project.shape.plan.snap +0 -175
- package/src-next/contract/__tests__/__snapshots__/project.shape.single-spec.snap +0 -85
- package/src-next/contract/__tests__/declare.test.ts +0 -242
- package/src-next/contract/__tests__/doc.test.ts +0 -358
- package/src-next/contract/__tests__/judge.test.ts +0 -873
- package/src-next/contract/__tests__/lint.test.ts +0 -314
- package/src-next/contract/__tests__/project.test.ts +0 -419
- package/src-next/contract/__tests__/translate.test.ts +0 -96
- package/src-next/contract/declare.ts +0 -983
- package/src-next/contract/doc.ts +0 -753
- package/src-next/contract/invariants.ts +0 -1268
- package/src-next/contract/judge.ts +0 -142
- package/src-next/contract/lint.ts +0 -275
- package/src-next/contract/project.ts +0 -596
- package/src-next/contract/skill-anatomy.ts +0 -273
- package/src-next/contract/translate.ts +0 -113
- package/src-next/face/__tests__/board-view.test.ts +0 -948
- package/src-next/face/__tests__/capsule.test.ts +0 -276
- package/src-next/face/__tests__/channel-closure.guard.test.ts +0 -102
- package/src-next/face/__tests__/cli.test.ts +0 -4643
- package/src-next/face/__tests__/face.test.ts +0 -289
- package/src-next/face/__tests__/graph-view.test.ts +0 -61
- package/src-next/face/__tests__/host.test.ts +0 -24
- package/src-next/face/__tests__/negation.ts +0 -6
- package/src-next/face/__tests__/projection.test.ts +0 -301
- package/src-next/face/__tests__/sync-runner.test.ts +0 -70
- package/src-next/face/__tests__/words.guard.test.ts +0 -93
- package/src-next/face/artifacts.ts +0 -195
- package/src-next/face/board-view.ts +0 -662
- package/src-next/face/capsule.ts +0 -149
- package/src-next/face/cli.ts +0 -819
- package/src-next/face/declare.ts +0 -326
- package/src-next/face/gate.ts +0 -170
- package/src-next/face/graph-view.ts +0 -74
- package/src-next/face/host.ts +0 -326
- package/src-next/face/lifecycle.ts +0 -700
- package/src-next/face/projection.ts +0 -282
- package/src-next/face/route-render.ts +0 -160
- package/src-next/face/words.ts +0 -296
- package/src-next/infra/__tests__/infra.test.ts +0 -287
- package/src-next/infra/git.ts +0 -39
- package/src-next/infra/process.ts +0 -34
- package/src-next/infra/runtime.ts +0 -185
- package/src-next/infra/workspace.ts +0 -232
- package/src-next/render/__tests__/render.test.ts +0 -499
- package/src-next/render/__tests__/skeleton.test.ts +0 -466
- package/src-next/render/brief.ts +0 -121
- package/src-next/render/issue-body.ts +0 -159
- package/src-next/render/skeleton.ts +0 -437
- package/src-next/render/templates.ts +0 -650
- package/src-next/session/__tests__/graph.test.ts +0 -270
- package/src-next/session/__tests__/handoff-plane.guard.test.ts +0 -48
- package/src-next/session/__tests__/handoff-schema.test.ts +0 -310
- package/src-next/session/__tests__/ledger.test.ts +0 -744
- package/src-next/session/__tests__/next.test.ts +0 -368
- package/src-next/session/__tests__/preflight.test.ts +0 -491
- package/src-next/session/__tests__/run.test.ts +0 -1014
- package/src-next/session/__tests__/wave-line-phase.guard.test.ts +0 -49
- package/src-next/session/__tests__/wave.test.ts +0 -469
- package/src-next/session/faces.ts +0 -110
- package/src-next/session/graph.ts +0 -411
- package/src-next/session/handoff-schema.ts +0 -373
- package/src-next/session/ledger.ts +0 -1004
- package/src-next/session/next.ts +0 -192
- package/src-next/session/preflight.ts +0 -240
- package/src-next/session/run.ts +0 -606
- package/src-next/session/state.ts +0 -30
- 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;
|