@oscaner-skills/cdd-engine 4.2.0 → 4.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (55) hide show
  1. package/README.md +38 -9
  2. package/README.zh-CN.md +43 -9
  3. package/dist/contract/completion-criterion.js +351 -0
  4. package/dist/contract/declare.js +181 -43
  5. package/dist/contract/doc.js +84 -271
  6. package/dist/contract/frontmatter.js +2 -1
  7. package/dist/contract/home-extractors.js +49 -316
  8. package/dist/contract/invariants.js +400 -296
  9. package/dist/contract/judge.js +74 -49
  10. package/dist/contract/lint.js +3 -2
  11. package/dist/contract/liveness-signal.js +103 -0
  12. package/dist/contract/markdown-document.js +410 -0
  13. package/dist/contract/markdown-tree-types.js +6 -0
  14. package/dist/contract/markdown-tree.js +137 -0
  15. package/dist/contract/project.js +1 -1
  16. package/dist/contract/rules.js +106 -0
  17. package/dist/contract/selector-engine.js +332 -0
  18. package/dist/contract/selector-spec.js +74 -0
  19. package/dist/contract/skill-anatomy.js +29 -1
  20. package/dist/contract/task-block-grammar.js +285 -0
  21. package/dist/contract/task-blocks.js +65 -0
  22. package/dist/contract/translate.js +21 -0
  23. package/dist/contract/wave-width.js +15 -0
  24. package/dist/face/board-view.js +401 -131
  25. package/dist/face/capsule.js +66 -89
  26. package/dist/face/cli.js +116 -35
  27. package/dist/face/declare.js +36 -18
  28. package/dist/face/gate.js +117 -40
  29. package/dist/face/init.js +1 -1
  30. package/dist/face/lifecycle.js +540 -123
  31. package/dist/face/preview.js +43 -10
  32. package/dist/face/route-render.js +51 -21
  33. package/dist/face/termination.js +135 -261
  34. package/dist/face/words.js +134 -12
  35. package/dist/infra/atomic.js +15 -0
  36. package/dist/infra/git.js +25 -0
  37. package/dist/infra/proc.js +150 -0
  38. package/dist/infra/round-log.js +104 -0
  39. package/dist/infra/runtime.js +16 -4
  40. package/dist/infra/workspace.js +7 -2
  41. package/dist/render/brief.js +15 -17
  42. package/dist/render/skeleton.js +41 -28
  43. package/dist/render/templates.js +128 -84
  44. package/dist/session/faces.js +47 -20
  45. package/dist/session/graph.js +13 -37
  46. package/dist/session/handoff-schema.js +16 -8
  47. package/dist/session/inflight.js +282 -0
  48. package/dist/session/ledger.js +581 -136
  49. package/dist/session/line-identity.js +33 -0
  50. package/dist/session/next.js +138 -80
  51. package/dist/session/preflight.js +276 -68
  52. package/dist/session/round-naming.js +56 -8
  53. package/dist/session/run.js +317 -78
  54. package/dist/session/wave.js +94 -14
  55. package/package.json +13 -3
@@ -11,20 +11,34 @@
11
11
  // The root Cli holds the lifecycle instances and composes through them via its .action
12
12
  // thin shells — zero bare functions; every collaborator stays injectable (the tests
13
13
  // substitute the hermetic ones).
14
+ var _a;
14
15
  // The module exports the shared seams + the lifecycle class — zero behavior-carrying
15
16
  // bare functions.
17
+ import { existsSync, readFileSync } from "node:fs";
16
18
  import process from "node:process";
17
19
  import { printParseErrorCode } from "jsonc-parser";
20
+ import { CompletionCriteria, FixDispositions } from "../contract/completion-criterion.js";
21
+ import { GitClient } from "../infra/git.js";
22
+ import { ProcessFacts } from "../infra/proc.js";
23
+ import { RoundLog } from "../infra/round-log.js";
18
24
  import { TemplateAssembler } from "../render/templates.js";
25
+ import { TargetFaceTable } from "../session/faces.js";
19
26
  import { HandoffSchema } from "../session/handoff-schema.js";
27
+ import { InFlight } from "../session/inflight.js";
28
+ import { Ledger, RoundViolation, } from "../session/ledger.js";
20
29
  import { RoundNaming } from "../session/round-naming.js";
30
+ import { PlanStructure } from "../session/run.js";
21
31
  import { DISPATCH, HOSTS, HostDetect, REFS } from "./host.js";
22
32
  import { TerminationPolicy, Terminator, } from "./termination.js";
23
- import { Words } from "./words.js";
33
+ import { FIX_DISPOSITIONS_SUMMARY, Words } from "./words.js";
24
34
  /** The crash-record stdout-tail cap (P11 T2) — the child's last STDOUT_TAIL_MAX
25
35
  * non-empty stdout lines ride the crash record's `stdoutTail` (the diagnostic
26
36
  * channel; the child's Return is prose, never the round's content). */
27
37
  const STDOUT_TAIL_MAX = 40;
38
+ /** The structure-face change message — the round's graded entry when the plan's Task id
39
+ * set or a task's `DependsOn` set moved inside the round (design spec §7.3). The
40
+ * vanished / unreadable document cases name their own damage instead. */
41
+ const STRUCTURE_CHANGED = "the plan's structure changed inside this round (the Task id set or a task's DependsOn set) — the structure face belongs to the orchestrator and lands as its own commit";
28
42
  /**
29
43
  * CliLifecycle — the lifecycle's dispatch-seam production default (the split contract's
30
44
  * lifecycle face; face/cli.ts re-exports it as HarnessDispatch so the composition
@@ -37,6 +51,9 @@ const STDOUT_TAIL_MAX = 40;
37
51
  * BLOCKED outcome over the CDD_BLOCKED channel (never a thrown dispatch).
38
52
  */
39
53
  export class CliLifecycle {
54
+ /** The workspace-relative directory every round log lands in — built by
55
+ * `RoundLog.create` on first use, never by the workspace's own mkdir. */
56
+ static LOGS_DIR = "logs";
40
57
  #env;
41
58
  #sync;
42
59
  #template;
@@ -54,14 +71,44 @@ export class CliLifecycle {
54
71
  /** The handoff-schema face — stateless, one shared instance (the read-back
55
72
  * validator + the injected prompt text). */
56
73
  #handoffSchema = new HandoffSchema();
74
+ /** The in-flight record handle of this dispatch's workspace root — the ONE write
75
+ * point of the running dispatch (acquire before the spawn, release at the normal
76
+ * end; a crash leaves the record behind). */
77
+ #inflight;
78
+ /** The git read face — the crash record's `dispatchBase` / `commitsSince` facts. */
79
+ #git;
80
+ /** The recorded side of the liveness judgment — the holder pid's own start instant
81
+ * (`ProcessFacts.startOf`; injected by the tests to span a long session). */
82
+ #proc;
83
+ /** Whether this invocation asked to take over a dead holder's record (the
84
+ * `--steal-stale` flag — the only takeover path). */
85
+ #stealStale;
86
+ /** The HEAD the current dispatch started from (null off a repo / before a spawn) —
87
+ * the postmortem baseline of `commitsSince`. */
88
+ #dispatchBase = null;
89
+ /** The commits added after `#dispatchBase` (computed once the child returned). */
90
+ #commitsSince = [];
57
91
  /** The current dispatch's child-stdout diagnostic tail (the crash-record channel,
58
92
  * P11 T2) — set in #dispatch after the child returns, read by #reject. The child's
59
93
  * Return is prose; the engine never parses it — this is the failure channel only. */
60
94
  #stdoutTail = [];
95
+ /** The current dispatch's round log path (repoRoot-relative), null when the round has
96
+ * no log channel — the crash record's postmortem pointer (one file to open instead
97
+ * of reading `ps` from outside). */
98
+ #roundLogPath = null;
99
+ /** The current dispatch's log-channel failure (a SOFT entry naming the path), null
100
+ * when the channel opened — the record face must see a channel that never opened,
101
+ * not only the stderr notice. */
102
+ #logUnavailable = null;
61
103
  constructor(opts) {
62
104
  this.#env = opts.env ?? process.env;
63
105
  this.#scene = opts.scene;
64
106
  this.#naming = new RoundNaming(opts.scene.workspace);
107
+ this.#inflight =
108
+ opts.inflight ?? new InFlight(opts.scene.workspace.root, opts.scene.workspace.slug);
109
+ this.#git = opts.git ?? new GitClient();
110
+ this.#proc = opts.proc ?? ProcessFacts;
111
+ this.#stealStale = opts.stealStale ?? false;
65
112
  this.#sync = opts.sync ?? new Terminator();
66
113
  this.#template = opts.template ?? new TemplateAssembler();
67
114
  this.#words = opts.words ?? new Words();
@@ -82,10 +129,237 @@ export class CliLifecycle {
82
129
  step() {
83
130
  return (frame) => this.#dispatch(frame);
84
131
  }
85
- /** One dispatch — prompt from the template plane + the frame, host child via
86
- * the harness-contract rows, the child's write-back read in (the draft at
87
- * OUTPUT_HANDOFF is the round's content; the child's Return is prose, never parsed). */
132
+ /** One dispatch — the round's work, the observation facts every record carries (the
133
+ * dispatch baseline HEAD captured before the spawn, the dispatch-after
134
+ * `treeClean` observation) and the TERMINAL VERDICT the round is booked under
135
+ * (design spec §3.1: the verdict is written first, the violation family splits the
136
+ * gate second — never the child's exit code). A hard verdict is the round's
137
+ * failure face: `targetAction: false`, the concluded status is BLOCKED (so the
138
+ * invocation exits non-zero and the same command re-offers the round), and the ONE
139
+ * `CDD_BLOCKED` line names the round's own log file (§4.1). A soft entry is
140
+ * bookkeeping only — it never touches the exit code. */
88
141
  async #dispatch(frame) {
142
+ // The round's STRUCTURE baseline (design spec §7.3): taken HERE — after the
143
+ // pre-flight gate (which ran before the step was handed over) and before the
144
+ // spawn — so the close-time comparison judges this round's OWN plan edit only.
145
+ // It rides the frame and nowhere else (no progress key, no carrier slot, no
146
+ // in-flight field).
147
+ const baseline = PlanStructure.of(this.#scene.planPath);
148
+ const carried = {
149
+ ...frame,
150
+ structure: baseline.kind === "ok" ? baseline.structure : null,
151
+ };
152
+ const drafted = await this.#runDispatch(carried);
153
+ const terminal = drafted.status === "BLOCKED" || drafted.status === "TIMEOUT";
154
+ const observed = {
155
+ ...drafted,
156
+ dispatchBase: this.#dispatchBase,
157
+ treeClean: await this.#git.isClean(this.#scene.workspace.root.repoRoot),
158
+ };
159
+ const judged = await this.#verdictOf(carried, observed);
160
+ // The death faces author their own entry AND emit their own line (`#reject`), so
161
+ // only a hard verdict concluded HERE adds the shared line.
162
+ if (judged.violations.some((violation) => violation.grade === "hard") && !terminal) {
163
+ this.#blocked(this.#hardReason(judged.violations), false);
164
+ }
165
+ this.#warnSoft(judged.violations);
166
+ return {
167
+ ...observed,
168
+ // A hard round's conclusion is the failure: no hard entry can leave a round
169
+ // reading as approved. A soft-only round keeps its handoff conclusion, and a
170
+ // round whose handoff was never written concludes APPROVED on its criterion
171
+ // alone (the missing carrier is bookkeeping, never a gate).
172
+ status: this.#concludedStatus(judged.verdict, observed.status),
173
+ verdict: judged.verdict,
174
+ violations: judged.violations,
175
+ };
176
+ }
177
+ /** The round's concluded status under its verdict — a done round keeps its handoff
178
+ * conclusion (APPROVED when the handoff was never written: the completion criterion
179
+ * concluded it), and a hard-failed round concludes BLOCKED — or keeps TIMEOUT, the
180
+ * terminated round's own conveyed face (the §4.3 judging order is unchanged). */
181
+ #concludedStatus(verdict, drafted) {
182
+ if (verdict.targetAction)
183
+ return drafted ?? "APPROVED";
184
+ return drafted === "TIMEOUT" ? "TIMEOUT" : "BLOCKED";
185
+ }
186
+ /** The terminal verdict of one dispatched round (design spec §3.1/§3.2) — the
187
+ * completion criterion of the round's verb judge its OWN facts (the group's
188
+ * records, the persisted carrier, the round's baseline) plus the work plane's
189
+ * evidence gate, and the graded entries decide the verdict: a round with no hard
190
+ * entry is done. The judgment's two provider cells are supplied HERE, the single
191
+ * point: `records` is the key's in-register history read with the line's DECLARED
192
+ * word, and `reviewsPath` is the fix route's `--reviews` carrier or the ledger's
193
+ * RESOLVED review-carrier fallback — the retired twin's name when the canonical
194
+ * file is absent, never the never-minted canonical spelling.
195
+ *
196
+ * A death face (a killed child, a non-zero exit, a rejected draft) already carries
197
+ * its authored hard entry and needs no second judgment — the criterion table and
198
+ * the violation family never judge the same round twice. */
199
+ async #verdictOf(frame, outcome) {
200
+ const treeClean = outcome.treeClean ?? true;
201
+ // The log channel's own failure is booked on every face: a round whose record
202
+ // face never opened is not a silent absence (§3.3), and a dead round carries the
203
+ // fact too.
204
+ const logEntries = this.#logUnavailable === null ? [] : [this.#logUnavailable];
205
+ if (outcome.status === "BLOCKED" || outcome.status === "TIMEOUT") {
206
+ const authored = outcome.violations ?? [];
207
+ return {
208
+ verdict: { treeClean, targetAction: false },
209
+ // A failure is never a silent absence (§3.3): a concluded BLOCKED round that
210
+ // authored no entry books one here (`contract-violation`, the existing cause).
211
+ violations: [
212
+ ...(authored.length > 0
213
+ ? authored
214
+ : [RoundViolation.hard(`the round concluded ${outcome.status}`)]),
215
+ ...logEntries,
216
+ ],
217
+ };
218
+ }
219
+ const violations = [
220
+ ...(outcome.violations ?? []),
221
+ ...(await this.#criterionViolations(frame, outcome)),
222
+ ...this.#evidenceViolations(frame),
223
+ ...this.#structureViolations(frame),
224
+ ...logEntries,
225
+ ];
226
+ return {
227
+ verdict: {
228
+ treeClean,
229
+ targetAction: !violations.some((violation) => violation.grade === "hard"),
230
+ },
231
+ violations,
232
+ };
233
+ }
234
+ /** The verb's completion-criterion verdict as graded entries — the criterion's own
235
+ * hard violation plus its SOFT observations (design spec §3.2/§3.3). */
236
+ async #criterionViolations(frame, outcome) {
237
+ const scene = this.#scene;
238
+ const judged = await CompletionCriteria.of(this.#opOf(frame)).judge({
239
+ record: this.#judgedRecordOf(frame, outcome),
240
+ row: this.#rowOf(frame),
241
+ records: scene.ledger.recordsOf(frame.key, frame.type),
242
+ carrier: outcome.carrier ?? null,
243
+ reviewsPath: this.#reviewsPath(frame),
244
+ git: this.#git,
245
+ repoRoot: scene.workspace.root.repoRoot,
246
+ });
247
+ return [
248
+ ...(judged.violation === null ? [] : [judged.violation]),
249
+ ...(judged.observations ?? []),
250
+ ];
251
+ }
252
+ /** The round IDENTITY the criterion judges from — its op / cycle / attempt, the
253
+ * group baseline and the carrier path the round writes. Deliberately verdict-free:
254
+ * this judgment PRODUCES the verdict, so a verdict cell here would be a
255
+ * self-fulfilling input. The group's already-recorded verdicts arrive through
256
+ * `CompletionContext.records`, never through this cell. */
257
+ #judgedRecordOf(frame, outcome) {
258
+ const op = this.#opOf(frame);
259
+ return {
260
+ op,
261
+ cycle: frame.round,
262
+ attempt: frame.attempt ?? 1,
263
+ dispatchBase: outcome.dispatchBase ?? null,
264
+ carrierPath: outcome.carrier === undefined
265
+ ? null
266
+ : this.#scene.ledger.handoffPath(op, frame.type, frame.params),
267
+ };
268
+ }
269
+ /** The progress row the round belongs to (the criterion's context cell) — the key's
270
+ * row when it exists, else the fresh entry form of that key. */
271
+ #rowOf(frame) {
272
+ const ledger = this.#scene.ledger;
273
+ const data = ledger.readProgress();
274
+ return ((data === null ? undefined : Ledger.rowFor(data, frame.key, frame.type)) ??
275
+ ledger.entryFor(frame.key));
276
+ }
277
+ /** The evidence gate as a graded entry (design spec §3.3) — the work plane's wave /
278
+ * branch rounds write the canonical `{family-prefix}-{key}-test-evidence.json`; a
279
+ * missing / malformed / schema-violating file is HARD. The tri-state read reports
280
+ * each cause truly (D27): a corrupt file is never misreported as absent. */
281
+ #evidenceViolations(frame) {
282
+ if (HandoffSchema.planeOf(this.#opOf(frame)) !== "work")
283
+ return [];
284
+ if (TargetFaceTable.isDocShape(frame.type))
285
+ return [];
286
+ const scene = this.#scene;
287
+ const evidencePath = scene.workspace.resolve(this.#naming.evidenceName(frame));
288
+ const read = scene.workspace.readJson(this.#naming.evidenceName(frame));
289
+ if (read.kind === "malformed") {
290
+ return [this.#hard(`the test evidence at ${evidencePath} is malformed JSON`)];
291
+ }
292
+ if (read.kind === "missing") {
293
+ return [this.#hard(`the test evidence at ${evidencePath} was not written`)];
294
+ }
295
+ const problems = this.#handoffSchema.evidenceViolations(read.value);
296
+ if (problems.length === 0)
297
+ return [];
298
+ return [
299
+ this.#hard(`the test evidence at ${evidencePath} violates the contract: ${problems.join("; ")}`),
300
+ ];
301
+ }
302
+ /** The round's OWN plan-structure edit as a graded entry (design spec §7.3) — the
303
+ * close-time comparison against the dispatch-time snapshot: a changed Task-id set
304
+ * or a changed `DependsOn` set is a HARD entry under the existing
305
+ * `contract-violation` cause (zero new violation enum), because the structure face
306
+ * belongs to the orchestrator and lands as its own commit. A content-only amendment
307
+ * differs on neither face and judges nothing.
308
+ *
309
+ * The two sides are judged apart. An ABSENT baseline (no plan fact, or a document
310
+ * already unreadable at dispatch) judges nothing — there is nothing to compare
311
+ * against. A PRESENT baseline with a missing / unreadable current side is the
312
+ * round's own damage: the document the dispatch read is gone or damaged inside this
313
+ * round, which is the structure face's most extreme edit and is judged hard rather
314
+ * than skipped. */
315
+ #structureViolations(frame) {
316
+ const baseline = frame.structure ?? null;
317
+ if (baseline === null)
318
+ return [];
319
+ const current = PlanStructure.of(this.#scene.planPath);
320
+ if (current.kind === "ok") {
321
+ if (!current.structure.differsFrom(baseline))
322
+ return [];
323
+ return [this.#hard(STRUCTURE_CHANGED)];
324
+ }
325
+ return [
326
+ this.#hard(current.kind === "absent"
327
+ ? "the plan document disappeared inside this round — the structure face belongs to the orchestrator and lands as its own commit"
328
+ : `the plan document became unreadable inside this round (${current.reason}) — the structure face belongs to the orchestrator and lands as its own commit`),
329
+ ];
330
+ }
331
+ /** One self-authored HARD entry — the ledger's existing `contract-violation` cause,
332
+ * zero new violation enum (design spec §3.3). */
333
+ #hard(message) {
334
+ return RoundViolation.hard(message);
335
+ }
336
+ /** The hard entries' one-line reason (the `CDD_BLOCKED` line's message). */
337
+ #hardReason(violations) {
338
+ return violations
339
+ .filter((violation) => violation.grade === "hard")
340
+ .map((violation) => violation.message)
341
+ .join("; ");
342
+ }
343
+ /** Warn once per round about its SOFT entries (design spec §3.3 — soft is
344
+ * bookkeeping only, so it never touches the verdict, the exit code or the gate). */
345
+ #warnSoft(violations) {
346
+ const soft = violations
347
+ .filter((violation) => violation.grade === "soft")
348
+ .map((violation) => violation.message);
349
+ if (soft.length === 0)
350
+ return;
351
+ this.#io.stderr(`${this.#words.station("warn")} ${this.#words.softViolation(soft.join("; "))}\n`);
352
+ }
353
+ /** One dispatch's round work — prompt from the template plane + the frame, host
354
+ * child via the harness-contract rows, the child's write-back read in (the draft
355
+ * at OUTPUT_HANDOFF is the round's content; the child's Return is prose, never
356
+ * parsed). */
357
+ async #runDispatch(frame) {
358
+ // The baseline belongs to THIS dispatch alone: cleared at entry, so an early
359
+ // return (no host harness) records "no baseline" rather than a previous round's.
360
+ this.#dispatchBase = null;
361
+ this.#roundLogPath = null;
362
+ this.#logUnavailable = null;
89
363
  const host = this.detectHost();
90
364
  if (host === "") {
91
365
  this.#io.stderr("CDD_BLOCKED: no host harness detected (run cdd from within a supported harness)\n");
@@ -96,26 +370,54 @@ export class CliLifecycle {
96
370
  const cliName = row.cli;
97
371
  const args = [...row.invoke.split(" ").filter((part) => part.length > 0)];
98
372
  const ref = this.#skillRef(host, frame);
373
+ // The dispatch's ONE write point: publish the intent BEFORE the child exists, so
374
+ // any later crash / kill / timeout leaves a record naming who was running. The
375
+ // gates read `InFlight.inspect()` only — this call is the real dispatch's alone.
376
+ // A sibling dispatch that won the lock in between makes `acquire` throw
377
+ // `HoldingError` (carrying the holder's facts), which rides the CLI's held BLOCK.
378
+ this.#dispatchBase = await this.#git.head(this.#scene.workspace.root.repoRoot);
379
+ await this.#inflight.acquire(await this.#recordOf(frame), { stealStale: this.#stealStale });
380
+ // The round's own log file — created BEFORE the spawn (append stream open, zero
381
+ // bytes), so the channel exists from the dispatch's first millisecond. A create
382
+ // failure is a named soft observation and the round continues on the CPU leg
383
+ // alone (the log leg is null, never a kill authorization).
384
+ const roundLog = await this.#openRoundLog(frame);
385
+ // The postmortem pointer of THIS round — the log the child's bytes land in (absent
386
+ // when the channel could not be opened: the record then carries the honest null).
387
+ this.#roundLogPath = roundLog === null ? null : this.#rel(roundLog.path);
99
388
  // The child receives ONE prompt argument — per the host's promptForm data column
100
389
  // (§3.5): the ref-prefixed form embeds the slash ref at the start of the single
101
390
  // prompt positional (claude -p consumes the whole first positional as the prompt;
102
391
  // a standalone ref arg after the flags would be swallowed, losing everything after
103
392
  // the ref) — the prompt assembly is data, never a code assumption.
104
- const result = await this.#sync.run({
105
- command: cliName,
106
- args: [...args, this.#childPrompt(row.promptForm, ref, prompt)],
107
- // The two paths the dispatch needs share ONE source (this workspace, held only
108
- // here): the child's spawn directory is the repo root, and the heartbeat lands
109
- // in this dispatch's workspace. The same `cwd` is also the tree-leg scan root,
110
- // and the heartbeat path is the sampler's own write — the scan root ≡ child cwd
111
- // correspondence is structural, never a convention.
112
- cwd: this.#scene.workspace.root.repoRoot,
113
- heartbeatPath: this.#scene.workspace.resolve("liveness.json"),
114
- policy: TerminationPolicy.of(frame.phase),
115
- // The host row's own child env — the TTL pin the terminator layers over the
116
- // inherited env at spawn (the host difference is data, never a dispatcher branch).
117
- env: row.env,
118
- });
393
+ let result;
394
+ try {
395
+ result = await this.#sync.run({
396
+ command: cliName,
397
+ args: [...args, this.#childPrompt(row.promptForm, ref, prompt)],
398
+ // The child's spawn directory is the repo root; the in-flight record handle
399
+ // carries the sampler's own write path (the record is the ONE trail, and its
400
+ // path is the tree leg's exclusion). The same `cwd` is also the tree-leg scan
401
+ // root, so the scan root ≡ child cwd correspondence is structural.
402
+ cwd: this.#scene.workspace.root.repoRoot,
403
+ inflight: this.#inflight,
404
+ policy: TerminationPolicy.of(frame.phase),
405
+ // The host row's own child env — the TTL pin the terminator layers over the
406
+ // inherited env at spawn (the host difference is data, never a dispatcher branch).
407
+ env: row.env,
408
+ log: roundLog ?? undefined,
409
+ });
410
+ }
411
+ finally {
412
+ // Drain → close BEFORE any read-back judgment: the append stream's tail bytes can
413
+ // land after the exit event, so the postmortem face is only complete after close.
414
+ if (roundLog !== null)
415
+ await roundLog.close();
416
+ }
417
+ // The postmortem pair's second leg: what the (possibly crashed) child added on top
418
+ // of the dispatch baseline. Computed ONCE here, so every reject path below writes
419
+ // the same facts without a second git read.
420
+ this.#commitsSince = await this.#git.commitsSince(this.#scene.workspace.root.repoRoot, this.#dispatchBase);
119
421
  // The child's stdout rides the diagnostic channel — #reject reads it into the
120
422
  // crash record on either failure face. Child Return is prose: the engine never
121
423
  // parses it; the round's content is the OUTPUT_HANDOFF draft, read in #reconstruct.
@@ -148,7 +450,78 @@ export class CliLifecycle {
148
450
  // this branch sits AFTER the termination leg, so the termination is null
149
451
  { exitCode: result.code, cause: "child-exit", termination: null });
150
452
  }
151
- return this.#reconstruct(frame);
453
+ // The normal end: the child finished on its own and its handoff was read back —
454
+ // the ONE release point. The read-back's own refusals (a malformed / schema-
455
+ // violating draft) still release: the CHILD did not die, the round's artifacts were
456
+ // judged. The record survives only the round-ending paths above (a non-zero child
457
+ // exit, a kill, a timeout) and an uncaught throw — i.e. the process-death paths the
458
+ // record exists for.
459
+ const outcome = this.#reconstruct(frame);
460
+ await this.#inflight.release();
461
+ return outcome;
462
+ }
463
+ /** The in-flight record of one frame — the identity facts written before the spawn.
464
+ * `pid` is the dispatching engine process, the command is the same-command resume
465
+ * form, and the brief hash is computed NOW from the rendered brief (the ledger's ONE
466
+ * hash face — never a new hash surface).
467
+ * `startedAt` is the recorded pid's OWN start instant (`ProcessFacts.startOf`), the
468
+ * instant `ProcessFacts.live` compares against: the dispatch instant drifts away
469
+ * from it, and on a session older than the tolerance that drift would judge a live
470
+ * holder dead — the one direction the guard must never take. The dispatch instant
471
+ * is only the fallback when the process table cannot answer, and an unreadable
472
+ * start time then folds to "alive" on the read side (never to a takeover). */
473
+ async #recordOf(frame) {
474
+ const scene = this.#scene;
475
+ return {
476
+ pid: process.pid,
477
+ command: this.#resumeOf(frame),
478
+ slug: scene.workspace.slug,
479
+ startedAt: (await this.#proc.startOf(process.pid)) ?? Date.now(),
480
+ wave: frame.type === "wave" ? (frame.params.tasks ?? null) : null,
481
+ phase: frame.phase,
482
+ cycle: frame.round,
483
+ attempt: frame.attempt ?? 1,
484
+ briefHash: this.#briefHashOf(frame),
485
+ plan: scene.planPath === null ? null : this.#rel(scene.planPath),
486
+ sampledAt: null,
487
+ verdict: null,
488
+ };
489
+ }
490
+ /** Open one round's log file — the per-round channel the child's stdout/stderr
491
+ * land in, under the workspace's `logs/` directory (which no other writer creates).
492
+ * A create failure is a named soft observation and the round continues on the CPU
493
+ * leg alone (the log leg stays null); a fault AFTER the channel is live marks the
494
+ * log leg dead and is reported through the same channel — never a second notice. */
495
+ async #openRoundLog(frame) {
496
+ const name = this.#naming.logName(this.#opOf(frame), frame.type, frame.params, frame.attempt ?? 1);
497
+ const target = this.#scene.workspace.resolve(`${_a.LOGS_DIR}/${name}`);
498
+ try {
499
+ return await RoundLog.create(target, () => this.#io.stderr(`${this.#words.station("warn")} round log write failed at ${this.#rel(target)}\n`));
500
+ }
501
+ catch {
502
+ this.#io.stderr(`${this.#words.station("warn")} round log unavailable at ${this.#rel(target)}\n`);
503
+ // The record sees the same fact the stderr notice names (design spec §3.3): a
504
+ // soft entry, so the round concludes and the derived count carries it.
505
+ this.#logUnavailable = RoundViolation.soft(`the round log could not be created at ${this.#rel(target)} — the round ran on CPU evidence alone`);
506
+ return null;
507
+ }
508
+ }
509
+ /** The wave frame's brief hash at acquire time — `ReviewRefs.briefRevision` over the
510
+ * brief file this dispatch rendered (the SAME hash face the ledger binds as the
511
+ * reviewed revision). Computed independently of the ledger's records, so a wave's
512
+ * FIRST dispatch (no `brief-revision` row yet) still carries the hash. Null off the
513
+ * wave face and when the brief is not on disk yet. */
514
+ #briefHashOf(frame) {
515
+ const scene = this.#scene;
516
+ if (frame.type !== "wave" || scene.planPath === null || scene.briefPath === null)
517
+ return null;
518
+ try {
519
+ const brief = readFileSync(scene.briefPath, "utf8");
520
+ return scene.ledger.refs().briefRevision(this.#rel(scene.planPath), brief).brief_hash;
521
+ }
522
+ catch {
523
+ return null;
524
+ }
152
525
  }
153
526
  /** The work-mode of a frame phase — branch-review rides the review family. The
154
527
  * mapping itself lives in `RoundNaming` (the artifact stems key on it); this is
@@ -156,11 +529,11 @@ export class CliLifecycle {
156
529
  #opOf(frame) {
157
530
  return this.#naming.op(frame);
158
531
  }
159
- /** The dispatch-table work-mode (ROLE) of a frame — the spec/plan fix faces ride
532
+ /** The dispatch-table work-mode (ROLE) of a frame — the doc shapes' fix faces ride
160
533
  * the docs-fix mode; everything else maps by its phase (§3.5's four-mode table). */
161
534
  #roleOf(frame) {
162
535
  if (frame.phase === "fix") {
163
- return frame.type === "spec" || frame.type === "plan" ? "docs-fix" : "fix";
536
+ return TargetFaceTable.isDocShape(frame.type) ? "docs-fix" : "fix";
164
537
  }
165
538
  return frame.phase === "implement" ? "implement" : "review";
166
539
  }
@@ -230,9 +603,7 @@ export class CliLifecycle {
230
603
  // v1.9: INPUT_REVIEWS is fix/docs-fix only — the source review's handoff
231
604
  // carrier; a review writes its own draft (INPUT_REVIEWS === OUTPUT_HANDOFF
232
605
  // would be a short-circuit).
233
- INPUT_REVIEWS: op === "fix"
234
- ? this.#rel(this.#reviews ?? scene.ledger.handoffPath("review", frame.type, params))
235
- : "",
606
+ INPUT_REVIEWS: op === "fix" ? this.#rel(this.#reviewsPath(frame) ?? "") : "",
236
607
  // The kind-named judged-doc anchors (the semantic retirement of the generic
237
608
  // INPUT_DOC): the plan/branch lines carry the plan document (INPUT_PLAN — the
238
609
  // doc path on a plan line, the plan path on a branch line, whose review/fix
@@ -246,18 +617,23 @@ export class CliLifecycle {
246
617
  : frame.type === "branch"
247
618
  ? this.#rel(scene.planPath ?? "")
248
619
  : "",
249
- INPUT_SPEC: frame.type === "spec"
620
+ INPUT_SPEC: frame.type === "plan" || frame.type === "branch"
621
+ ? this.#rel(scene.specLink ?? "")
622
+ : frame.type === "wave"
623
+ ? ""
624
+ : // the doc shapes (phase-spec · overall · single-spec) carry the judged
625
+ // document — the charter line's own charter is its spec anchor.
626
+ this.#rel(docPath ?? ""),
627
+ // The parent charter of the spec the face reads (INPUT_OVERALL) — the same
628
+ // value condition as INPUT_SPEC, one face (the phase-spec line = its own
629
+ // `program:`; plan/branch = the same-slug identity doc's `program:`; the
630
+ // overall line itself = the judged charter); empty off those faces and when
631
+ // the named program is absent (the assembler drops the empty slot).
632
+ INPUT_OVERALL: frame.type === "overall"
250
633
  ? this.#rel(docPath ?? "")
251
- : frame.type === "plan" || frame.type === "branch"
252
- ? this.#rel(scene.specLink ?? "")
634
+ : frame.type === "phase-spec" || frame.type === "plan" || frame.type === "branch"
635
+ ? this.#rel(scene.overallLink ?? "")
253
636
  : "",
254
- // The parent charter of the spec the face reads (INPUT_OVERALL) — the same
255
- // value condition as INPUT_SPEC, one face (spec = its own `program:`; plan/
256
- // branch = the same-slug identity doc's `program:`); empty off those faces and
257
- // when the spec names no program (the assembler drops the empty slot).
258
- INPUT_OVERALL: frame.type === "spec" || frame.type === "plan" || frame.type === "branch"
259
- ? this.#rel(scene.overallLink ?? "")
260
- : "",
261
637
  // The branch/wave tree-review scope anchor (BASE_BRANCH) — engine-injected
262
638
  // from the base artifact at dispatch; empty off those faces (spec/plan reviews
263
639
  // carry none, and the empty slot is dropped by the assembler).
@@ -362,7 +738,7 @@ export class CliLifecycle {
362
738
  verdict: termination.lastSample?.verdict ?? "none",
363
739
  count: findings.length,
364
740
  });
365
- this.#io.stderr(`${this.#words.station("warn")} ${text}\n`);
741
+ this.#io.stderr(`${this.#words.station("warn")} ${text} — ${this.#words.lateLandingHint()}\n`);
366
742
  return { ...outcome, termination };
367
743
  }
368
744
  /** The read-back reconstruct — the child's draft at OUTPUT_HANDOFF is the round's
@@ -370,13 +746,13 @@ export class CliLifecycle {
370
746
  * subset (projection ② of session/handoff-schema.ts — the SAME declared objects
371
747
  * the prompt injected), then build the final carrier the lifecycle persists in
372
748
  * place (agent draft → finalized, full-replace at the same path — the engine
373
- * remains the carrier's single author). A missing or schema-violating draft →
374
- * BLOCK over the CDD_BLOCKED channel + a crash record + the draft untouched
375
- * (on failure, no overwrite — the child's work is never clobbered; resume re-runs the same
376
- * command, which re-offers the round). The test-evidence file (work-plane wave /
377
- * branch rounds only) is read back with the same stakes: a missing/violating file
378
- * rewrites the carrier to BLOCKED (persisted — the child's work is kept, marked
379
- * bad), the second fix for a prose-only claim.
749
+ * remains the carrier's single author). A malformed or schema-violating draft is a
750
+ * contract violation at the read-back face (the draft untouched — the child's work
751
+ * is never clobbered; resume re-runs the same command, which re-offers the round).
752
+ * A MISSING draft is not a rejection: the completion criterion owns it (§3.3) — an
753
+ * implement round continues on its commits with a soft observation, a review/fix
754
+ * round fails on its carrier criterion — so no carrier is materialized and the
755
+ * verdict is written against the null status.
380
756
  *
381
757
  * `prefetched` is the terminated-review promotion's already-probed draft — the ONE
382
758
  * draft parse stays single-sourced (`#readDraft`), and the promotion rides this
@@ -400,13 +776,8 @@ export class CliLifecycle {
400
776
  // jsonc-parser tolerates the lenient dialect while a real break (a missing
401
777
  // brace, …) still reports malformed.
402
778
  const draftRead = this.#readDraft(frame);
403
- if (draftRead.kind === "missing") {
404
- return this.#reject(frame, path, `the handoff draft was not written at ${path}`, {
405
- exitCode: 0,
406
- cause: "handoff-absent",
407
- termination: null,
408
- });
409
- }
779
+ if (draftRead.kind === "missing")
780
+ return { status: null };
410
781
  if (draftRead.kind === "malformed") {
411
782
  // The lenient face carries the parser's precise error codes (D39) — surface
412
783
  // them in the rejection so a genuinely corrupt draft is diagnosable, not just
@@ -435,51 +806,65 @@ export class CliLifecycle {
435
806
  // — so the `?? "BLOCKED"` never fires here (a work draft without a status never
436
807
  // reaches this line; the absent→undefined case exists only for on-disk legacy
437
808
  // carriers the ledger reads back, never a schema-validated draft).
438
- let status = schema.conclusionOf(plane, draft) ?? "BLOCKED";
439
- let reason = null;
440
- // The evidence gate (v1.9) — the work plane's wave / branch rounds (implement/fix
441
- // task+branch) write the canonical `{family-prefix}-{key}-test-evidence.json` under
442
- // the workspace (§3.7 naming: tasks- for the task families, branch- for the branch
443
- // fix); the doc rounds (review/docs-fix) carry no evidence file. The read-back is
444
- // REAL — a missing/malformed/schema-violating file rewrites the draft to BLOCKED
445
- // (each cause reported truly — the tri-state read, D27).
446
- if (plane === "work" && (frame.type === "wave" || frame.type === "branch")) {
447
- const evidenceName = this.#naming.evidenceName(frame);
448
- const evidencePath = scene.workspace.resolve(evidenceName);
449
- const evidenceRead = scene.workspace.readJson(evidenceName);
450
- // The SAME tri-state discrimination as the draft leg (D27): a PRESENT-but-corrupt
451
- // evidence file reports its true cause, never the misleading "missing" — only a
452
- // genuinely absent file (or a schema-violating present one) rides the schema
453
- // verdict below.
454
- if (evidenceRead.kind === "malformed") {
455
- status = "BLOCKED";
456
- reason = `the test evidence at ${evidencePath} is malformed JSON`;
457
- }
458
- else {
459
- const evidence = evidenceRead.kind === "ok" ? evidenceRead.value : null;
460
- const evidenceProblems = schema.evidenceViolations(evidence);
461
- if (evidenceProblems.length > 0) {
462
- status = "BLOCKED";
463
- reason = `the test evidence at ${evidencePath} violates the contract: ${evidenceProblems.join("; ")}`;
464
- }
465
- }
466
- }
809
+ const status = schema.conclusionOf(plane, draft) ?? "BLOCKED";
810
+ const carrier = this.#materialize(frame, plane, draft, status);
467
811
  return {
468
812
  status,
469
813
  findings: plane === "judge" ? schema.findingsOf(findings) : undefined,
470
- carrier: this.#materialize(frame, plane, draft, status, reason),
814
+ carrier,
815
+ dispositionsSummary: this.#dispositionsSummary(frame, plane, carrier),
471
816
  };
472
817
  }
818
+ /** The fix round's ONE summary line (design spec §3.4) — computed from the PERSISTED
819
+ * carrier's dispositions and the REQUESTING carrier's input set (the same pair the
820
+ * fix criterion judges), never stored: no record field, no carrier key, no capsule
821
+ * key, no second read face. Undefined off the fix face and when the input set
822
+ * cannot be located or read (the round fails on grounds the line cannot describe).
823
+ * The criterion supplies the counts; the `FIX_DISPOSITIONS_SUMMARY` template — the
824
+ * presentation plane's byte fact — renders the row here. */
825
+ #dispositionsSummary(frame, plane, carrier) {
826
+ if (plane !== "work" || this.#opOf(frame) !== "fix")
827
+ return undefined;
828
+ const requester = FixDispositions.requesterInputOf(this.#scene.ledger.recordsOf(frame.key, frame.type), frame.round, this.#reviewsPath(frame), this.#repoRootValue().absolute);
829
+ if (requester.kind !== "read")
830
+ return undefined;
831
+ const counts = new FixDispositions().summaryOf(carrier, requester.summaries);
832
+ return FIX_DISPOSITIONS_SUMMARY.replace("{fixed}", String(counts.fixed)).replace("{rejected}", String(counts.rejected));
833
+ }
834
+ /** The requesting review carrier's path — the fix round's `--reviews` input, or the
835
+ * ledger's resolved review handoff path when the route carried none (the ONE
836
+ * resolution the round context's INPUT_REVIEWS and the disposition summary share).
837
+ * A migrated line resolves the carrier that EXISTS — the retired twin's name, never
838
+ * the never-minted canonical spelling.
839
+ *
840
+ * A same-cycle review record that RECORDED no carrier path, with no carrier at
841
+ * either spelling on disk, leaves the requester input UNRECORDED: the answer is
842
+ * null, and the fix criterion books its visible skip (design spec §3.4's legacy
843
+ * row) instead of failing the round on a hard absent-carrier refusal. An absent
844
+ * record is a different fact — it keeps the resolved path, so the criterion reports
845
+ * the missing requesting carrier it truly is. */
846
+ #reviewsPath(frame) {
847
+ if (this.#reviews !== null)
848
+ return this.#reviews;
849
+ const resolved = this.#scene.ledger.resolveHandoffPath("review", frame.type, frame.params);
850
+ if (existsSync(resolved))
851
+ return resolved;
852
+ const legacy = this.#scene.ledger
853
+ .recordsOf(frame.key, frame.type)
854
+ .some((record) => record.op === "review" && record.cycle === frame.round && record.carrierPath === null);
855
+ return legacy ? null : resolved;
856
+ }
473
857
  /** The read-back rejection face — CDD_BLOCKED reason + the crash record (the
474
858
  * same-command resume's decision source: the attempted handoff + the resume
475
859
  * command) + NO carrier (the bookkeep leaves the draft untouched). The crash
476
- * record carries the caller's REAL death facts: an absent draft is the
477
- * `handoff-absent` read-back face (exit 0), a present-but-unqualified draft
478
- * (malformed JSON / schema) is `contract-violation` (the default), a dead
479
- * child passes its own exit code + `child-exit`, and a terminated round passes
480
- * its whole `termination` fact (cause + last sample) — one record shape, four
481
- * truthful callers (the record is the postmortem artifact; a misreported death
482
- * sends a maintainer hunting the wrong fault).
860
+ * record carries the caller's REAL death facts: a present-but-unqualified draft
861
+ * (malformed JSON / schema) is `contract-violation` (the default), a dead child
862
+ * passes its own exit code + `child-exit`, and a terminated round passes its whole
863
+ * `termination` fact (cause + last sample) — one record shape, three truthful
864
+ * callers (the record is the postmortem artifact; a misreported death sends a
865
+ * maintainer hunting the wrong fault). A MISSING draft is not this face: the
866
+ * completion criterion owns it, so no rejection — and no crash record — ever fires
867
+ * for an absent draft.
483
868
  *
484
869
  * The returned status derives from the death facts alone (§4.3 — no status
485
870
  * parameter): a termination rides it → `TIMEOUT`; otherwise → `BLOCKED` (the
@@ -490,6 +875,7 @@ export class CliLifecycle {
490
875
  cause: "contract-violation",
491
876
  termination: null,
492
877
  }) {
878
+ const cause = this.#causeOf(death);
493
879
  this.#writeCrash(frame, path, reason, death, false);
494
880
  // A terminated round extends its ONE CDD_BLOCKED line with the idle time and the
495
881
  // last sample's verdict (the crash record carries the full sample).
@@ -499,21 +885,42 @@ export class CliLifecycle {
499
885
  idleMs: death.termination.idleMs,
500
886
  verdict: death.termination.lastSample?.verdict ?? "none",
501
887
  });
502
- this.#io.stderr(`CDD_BLOCKED: ${reason}${detail}\n`);
888
+ // Every cut-short round (kill · timeout · crash) carries the late-landing hint: the
889
+ // child may still write after the engine stopped watching, and the recovery starts
890
+ // from the working tree, never from the assumption that nothing landed.
891
+ this.#blocked(`${reason}${detail}`, true);
892
+ // The rejected round's own HARD entry — the verdict is `targetAction: false` and the
893
+ // failure is named, never a silent absence (§3.3). The cause rides the death facts'
894
+ // existing vocabulary (no new enum row).
895
+ const violations = [RoundViolation.hard(reason, cause)];
503
896
  if (death.termination === null)
504
- return { status: "BLOCKED" };
505
- return { status: "TIMEOUT", termination: death.termination };
897
+ return { status: "BLOCKED", violations };
898
+ return { status: "TIMEOUT", termination: death.termination, violations };
899
+ }
900
+ /** The crash cause of one death fact — the termination's own cause when present,
901
+ * else the caller's. One derivation, two readers (the crash record and the round's
902
+ * hard entry). */
903
+ #causeOf(death) {
904
+ return death.termination?.cause ?? death.cause;
905
+ }
906
+ /** The ONE `CDD_BLOCKED` line (§3.3): the hard verdict and the rejected / cut-short
907
+ * rounds share it, and every line names the round's own log file (§4.1) — a
908
+ * diagnose-one-round job is one path away, never a `ps` read from outside. The
909
+ * late-landing hint is a CUT-SHORT fact alone (a hard round's child finished). */
910
+ #blocked(reason, cutShort) {
911
+ const log = this.#roundLogPath === null ? "" : ` — log: ${this.#roundLogPath}`;
912
+ const hint = cutShort ? ` — ${this.#words.lateLandingHint()}` : "";
913
+ this.#io.stderr(`CDD_BLOCKED: ${reason}${log}${hint}\n`);
506
914
  }
507
915
  /** Write the lane's crash record — the postmortem artifact and same-command
508
916
  * resume's decision source. One writer serves both the rejection face
509
917
  * (`promoted: false`) and the termination branch's promotion (`promoted: true`):
510
918
  * the record shape is identical, only the promotion fact differs. */
511
919
  #writeCrash(frame, path, reason, death, promoted) {
512
- const op = this.#opOf(frame);
513
920
  // The cause rides the termination fact when one is present (one of the three
514
921
  // causes or the `unknown` fallback); without it, the caller's own cause.
515
- const cause = death.termination?.cause ?? death.cause;
516
- this.#scene.ledger.writeCrash(`${op}.${frame.type}`, frame.round, {
922
+ const cause = this.#causeOf(death);
923
+ this.#scene.ledger.writeCrash(this.#naming.crashName(frame), {
517
924
  exitCode: death.exitCode,
518
925
  stderrTail: [reason],
519
926
  stdoutTail: this.#stdoutTail,
@@ -522,25 +929,31 @@ export class CliLifecycle {
522
929
  attemptedHandoff: this.#rel(path),
523
930
  next: this.#resumeOf(frame),
524
931
  cause,
525
- // The last sample rides WITH the termination (in memory, zero re-read of the
526
- // heartbeat file) — null on every non-terminated face.
932
+ // The postmortem's observation pair: the round's own log file (one file to open
933
+ // instead of reading `ps` from outside) and its last sample, which rides WITH the
934
+ // termination (in memory, zero re-read of the in-flight record) — null on every
935
+ // non-terminated face.
936
+ logPath: this.#roundLogPath,
527
937
  lastSample: death.termination?.lastSample ?? null,
528
938
  promoted,
529
939
  idleMs: death.termination?.idleMs ?? null,
940
+ // The postmortem's git facts: the HEAD the dispatch started from and whatever
941
+ // the (possibly crashed) child committed before it died.
942
+ dispatchBase: this.#dispatchBase,
943
+ commitsSince: this.#commitsSince,
530
944
  });
531
- // P14 — the sole contractViolationCount write seam: observe the FINAL crash
532
- // cause (termination override wins). Never keyed off status === "BLOCKED".
533
- if (cause === "handoff-absent" || cause === "contract-violation") {
534
- this.#scene.ledger.incrementContractViolationCount();
535
- }
945
+ // P22 — the crash record is the postmortem, never a counter write: the soft
946
+ // counter derives from the round records (`Ledger#softViolations`), and a hard
947
+ // crash reads as the round's failed verdict (design spec §3.3).
536
948
  }
537
949
  /** Build the final carrier — the validated writable fields from the draft (the
538
950
  * engine-seated identity rides the canonical file name, never inline: phase/tasks
539
951
  * are not declared and never written — v1.30), persisted by the bookkeep
540
- * full-replace at the SAME path (agent draft → finalized). The evidence override
541
- * rewrites the status to BLOCKED + the reason note (the child's work preserved,
542
- * marked bad). */
543
- #materialize(frame, plane, draft, status, reason) {
952
+ * full-replace at the SAME path (agent draft → finalized). The ROUND VERDICT is a
953
+ * separate fact (`#verdictOf`): a hard round fails on its record + exit code, while
954
+ * the carrier keeps the child's own declared status (the engine never rewrites a
955
+ * declaration to encode a judgment). */
956
+ #materialize(frame, plane, draft, status) {
544
957
  const ledger = this.#scene.ledger;
545
958
  const notes = [];
546
959
  // The §8.7 classification ruling — the SAME judgment the read-back validator makes
@@ -577,13 +990,10 @@ export class CliLifecycle {
577
990
  const draftNotes = Array.isArray(draft.notes) ? [...draft.notes] : [];
578
991
  if (plane === "work") {
579
992
  carrier.status = status;
580
- // The evidence-contract override (work-plane wave / branch rounds only — the
581
- // evidence gate reads that round's evidence file) rewrites the persisted
582
- // conclusion to BLOCKED.
583
- if (reason !== null) {
584
- carrier.status = "BLOCKED";
585
- draftNotes.push(reason);
586
- }
993
+ // The fix dispositions ride the carrier VERBATIM (the child's declaration, never
994
+ // an engine rewrite) — the schema pinned the slot's object shape.
995
+ if (draft.dispositions !== undefined)
996
+ carrier.dispositions = draft.dispositions;
587
997
  }
588
998
  if (notes.length > 0 || draftNotes.length > 0)
589
999
  carrier.notes = [...notes, ...draftNotes];
@@ -679,21 +1089,27 @@ export class CliLifecycle {
679
1089
  // engine-injected at dispatch), so no range rides the command.
680
1090
  return `cdd review --type branch --plan ${plan}`;
681
1091
  case "review":
682
- if (frame.type === "spec")
683
- return `cdd review --type spec --spec ${this.#docOf(frame)}`;
1092
+ if (frame.type === "wave")
1093
+ return `cdd review --type wave --tasks ${frame.params.tasks ?? ""} --plan ${plan}`;
1094
+ if (frame.type === "branch")
1095
+ return `cdd review --type branch --plan ${plan}`;
684
1096
  if (frame.type === "plan")
685
1097
  return `cdd review --type plan --plan ${this.#docOf(frame)}`;
686
- return `cdd review --type wave --tasks ${frame.params.tasks ?? ""} --plan ${plan}`;
1098
+ // phase-spec · overall · single-spec — the document under review rides
1099
+ // the retained `--spec` flag.
1100
+ return `cdd review --type ${frame.type} --spec ${this.#docOf(frame)}`;
687
1101
  case "fix": {
688
- const findings = scene.ledger.handoffPath("review", frame.type, frame.params);
689
- const target = frame.target.kind === "plan" || frame.target.kind === "spec"
690
- ? `--${frame.type === "spec" ? "spec" : "plan"} ${frame.target.doc}`
691
- : // The branch fix carries no refs — the source findings ride the
692
- // --reviews handoff; the workspace-identity `--plan` still rides
693
- // (the plan is the branch line's identity, zero orchestrator fallback).
694
- frame.target.kind === "branch"
695
- ? `--plan ${plan}`
696
- : `--tasks ${frame.params.tasks ?? ""} --plan ${plan}`;
1102
+ const findings = scene.ledger.resolveHandoffPath("review", frame.type, frame.params);
1103
+ const target = frame.target.kind === "plan"
1104
+ ? `--plan ${frame.target.doc}`
1105
+ : frame.target.kind === "spec"
1106
+ ? `--spec ${frame.target.doc}`
1107
+ : // The branch fix carries no refs — the source findings ride the
1108
+ // --reviews handoff; the workspace-identity `--plan` still rides
1109
+ // (the plan is the branch line's identity, zero orchestrator fallback).
1110
+ frame.target.kind === "branch"
1111
+ ? `--plan ${plan}`
1112
+ : `--tasks ${frame.params.tasks ?? ""} --plan ${plan}`;
697
1113
  return `cdd fix --type ${frame.type} ${target} --reviews ${findings}`;
698
1114
  }
699
1115
  }
@@ -704,3 +1120,4 @@ export class CliLifecycle {
704
1120
  return frame.target.kind === "plan" || frame.target.kind === "spec" ? frame.target.doc : "";
705
1121
  }
706
1122
  }
1123
+ _a = CliLifecycle;