@oscaner-skills/cdd-engine 4.6.0 → 4.8.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -33,6 +33,15 @@ export class PlanTaskBlocksReader {
33
33
  static STEP_LINE = TaskBlockGrammar.STEP_LINE;
34
34
  /** The `— checkable:` clause separator. */
35
35
  static CHECKABLE = TaskBlockGrammar.CHECKABLE;
36
+ /** The placeholder spellings a `Files` value line may carry INSTEAD of a path — the
37
+ * wave's "this task changes no file" declaration: a blank value, the bare `none`
38
+ * and the parenthetical `(none)`. Matched case-insensitively on the trimmed,
39
+ * bullet- and label-stripped remainder, and token by token for a quoted one. */
40
+ static FILE_PLACEHOLDERS = new Set(["", "none", "(none)"]);
41
+ /** The optional line label a `Files` row may carry (`- Modify: …` · `- Test: …`) —
42
+ * stripped so the value's own token is what remains; a line without one keeps its
43
+ * whole remainder. */
44
+ static FILE_ROW_LABEL = /^[A-Za-z][\w ()/.+-]*?:\s+/;
36
45
  /** A dependency id token — the declared `DependsOn id` value domain (the SAME
37
46
  * source string the registry element carries). */
38
47
  static ID_TOKEN = new RegExp(TASK_ID_VALUE_PATTERN);
@@ -62,4 +71,41 @@ export class PlanTaskBlocksReader {
62
71
  section(content, heading) {
63
72
  return MarkdownTree.parse(content).sectionText(heading);
64
73
  }
74
+ /** The path tokens one block's `Files` declaration names — the read face behind the
75
+ * implement criterion's verification-wave cell (P30 §2.4). An empty result is a
76
+ * REAL claim ("this task changes no file"), so the read fails SAFE: an absent
77
+ * section, a blank value, a bare bullet and the `(none)` placeholder declare zero
78
+ * paths, while an unrecognized remainder is returned as one token — text this
79
+ * reader does not understand never reads as "no paths". */
80
+ filePathsOf(block) {
81
+ const field = block.fields.find((entry) => entry.key === "Files");
82
+ if (field === undefined)
83
+ return [];
84
+ const tokens = [];
85
+ for (const line of field.lines) {
86
+ for (const token of PlanTaskBlocksReader.#fileTokensOf(line))
87
+ tokens.push(token);
88
+ }
89
+ return tokens;
90
+ }
91
+ /** One `Files` value line's tokens — the quoted spans when the line quotes its paths
92
+ * (the plan convention), else the whole stripped remainder. The bullet marker is
93
+ * stripped with its trailing whitespace OR at the line's end, so a bare `-` bullet
94
+ * (a row that declares no path at all) reads as an empty value. */
95
+ static #fileTokensOf(line) {
96
+ const remainder = line
97
+ .replace(/^[-*+](?:\s+|$)/, "")
98
+ .replace(PlanTaskBlocksReader.FILE_ROW_LABEL, "")
99
+ .trim();
100
+ if (PlanTaskBlocksReader.FILE_PLACEHOLDERS.has(remainder.toLowerCase()))
101
+ return [];
102
+ const spans = [...remainder.matchAll(/`([^`]+)`/g)]
103
+ .map((match) => (match[1] ?? "").trim())
104
+ .filter((token) => token.length > 0);
105
+ // A line that quotes its paths declares exactly those; a quoted placeholder
106
+ // (`` `(none)` ``) declares none of them.
107
+ if (spans.length === 0)
108
+ return [remainder];
109
+ return spans.filter((token) => !PlanTaskBlocksReader.FILE_PLACEHOLDERS.has(token.toLowerCase()));
110
+ }
65
111
  }
package/dist/face/cli.js CHANGED
@@ -82,6 +82,11 @@ import { CommandTreeBuilder } from "./projection.js";
82
82
  import { Terminator } from "./termination.js";
83
83
  import { Words } from "./words.js";
84
84
  export { CliLifecycle as HarnessDispatch } from "./lifecycle.js";
85
+ /** The `--recover` double-gap refusal (P30 §2.1③) — NEITHER leg holds: no stale
86
+ * in-flight record stands on this tree, and the line is not at drift ∧ pending-fix.
87
+ * The command dispatches nothing: a flag that silently degrades into an ordinary
88
+ * dispatch is exactly the silent fallback §2.1③ forbids. */
89
+ const RECOVER_NOTHING = "--recover has nothing to take over and nothing to reopen — no stale in-flight record stands on this tree (①), and this line is not at drift ∧ pending-fix (②); nothing was dispatched";
85
90
  /**
86
91
  * The Cli — the command face's parse/run surface over the assembled object graph.
87
92
  * runArgv() parses through the commander program and rejects unknown flags (the
@@ -516,7 +521,7 @@ export class Cli {
516
521
  // The explicit takeover flag — VOID under --dry-run: the preview face never
517
522
  // acquires, so a takeover there would have no write channel at all. The
518
523
  // preview still judges the same gate, sees the same holder facts, and exits 1.
519
- stealStale: !parsed.dryRun && parsed.args.stealStale === "true",
524
+ recover: !parsed.dryRun && parsed.args.recover === "true",
520
525
  });
521
526
  // The per-invocation batch cursor: the in-memory done set mirrors the on-disk
522
527
  // ledger's closed waves (the C5 closure single face) — NOT a "every non-group
@@ -546,6 +551,20 @@ export class Cli {
546
551
  scene.state.markDone(id);
547
552
  }
548
553
  const expected = verb === "implement" ? "implement" : verb === "fix" ? "fix" : scene.face.product.reviewLead;
554
+ // THE `--recover` judgment (P30 §2.1①–③), at the composition root and BEFORE the
555
+ // dispatch verdict: the takeover lands first, the supersede stamp second and the
556
+ // `N+1` review dispatch third — the order is fixed HERE, never inside `step()`.
557
+ // A STRUCTURE refusal keeps its own face: the recovery legs are skipped, so a dirty
558
+ // tree or a live holder is never displaced by an argument.
559
+ const recovery = !parsed.dryRun &&
560
+ parsed.args.recover === "true" &&
561
+ this.#authority.structureRefusal(preflight) === null
562
+ ? await this.#recoverRun(verb, type, scene, parsed, inflight)
563
+ : null;
564
+ if (recovery !== null && recovery.kind === "blocked") {
565
+ this.#io.stderr(`${this.#words.station("blocked")} ${recovery.message}\n`);
566
+ return 1;
567
+ }
549
568
  // THE dispatch verdict (P27 §2.2) — ONE authority over the three legs, in
550
569
  // priority order: the structure leg (the pre-flight verdict just judged), the
551
570
  // upstream station leg, then this line's own phase. A refusal is ONE verdict —
@@ -615,7 +634,7 @@ export class Cli {
615
634
  if (!parsed.dryRun && type === "wave" && scene.planText !== null)
616
635
  scene.briefPath = this.#gate.renderBrief(scene, parsed);
617
636
  const statuses = [];
618
- const dispatch = this.#dispatchOf(scene, parsed);
637
+ const dispatch = await this.#dispatchOf(scene, parsed, recovery?.harness ?? null);
619
638
  const run = new Lifecycle({
620
639
  face: scene.face,
621
640
  state: scene.state,
@@ -755,10 +774,77 @@ export class Cli {
755
774
  * retired synthetic approval (`() => ({ status: "APPROVED", findings: [] })`)
756
775
  * has no remaining caller: a preview books no round and fabricates no
757
776
  * conclusion. */
758
- #dispatchOf(scene, parsed) {
777
+ async #dispatchOf(scene, parsed, recovered = null) {
759
778
  if (this.#dispatch !== null)
760
779
  return this.#dispatch;
761
- const harness = new CliLifecycle({
780
+ const harness = recovered ?? this.#lifecycleOf(scene, parsed);
781
+ // The abort fold already ran at the composition root's `--recover` judgment
782
+ // (`#recoverRun`) when a harness was handed in; the injected/default face keeps
783
+ // its own fold here, so the takeover always precedes this dispatch's own record.
784
+ if (recovered === null && !parsed.dryRun && parsed.args.recover === "true") {
785
+ await harness.foldAbort();
786
+ }
787
+ return harness.step();
788
+ }
789
+ /** The `--recover` judgment (spec §2.1①–③) — the two legs, judged in order and
790
+ * allowed to stack:
791
+ * ① the ABORT leg — a stale in-flight record is taken over and, when it still
792
+ * names the killed round, folded into the ledger (`foldAbort`);
793
+ * ② the REOPEN leg — `review` on a doc / branch line only, at drift ∧ pending-fix,
794
+ * with no round in flight: the old review is stamped `supersededBy` and the
795
+ * dispatch that follows allocates `N+1`;
796
+ * ③ neither → the double-gap BLOCKED, naming both missing conditions, and no
797
+ * dispatch at all.
798
+ * The ORDER is the ruling (§2.1④): the abort fold first, the stamp second, the
799
+ * `N+1` dispatch third — it lives here, not in `step()`'s internals. `fix --recover`
800
+ * and `implement --recover` take leg ① only (never a reopen), wave lines likewise
801
+ * (their reopen face stays P29's brief-drift). */
802
+ async #recoverRun(verb, type, scene, parsed, inflight) {
803
+ const harness = this.#lifecycleOf(scene, parsed);
804
+ const stale = (await inflight.staleState()) !== null;
805
+ if (stale)
806
+ await harness.foldAbort();
807
+ const reopened = await this.#reopenLeg(verb, type, scene, inflight);
808
+ if (stale || reopened)
809
+ return { kind: "allowed", harness };
810
+ return { kind: "blocked", message: RECOVER_NOTHING };
811
+ }
812
+ /** The reopen leg (spec §2.3) — its three conditions judged here, and the stamp
813
+ * written when all hold: ① `reviewGate` open (the doc drifted), ② a fix still owed
814
+ * (`pendingFix`), ③ no round in flight (a live holder was refused upstream; a stale
815
+ * one was already taken over). Trigger face pinned: `review` on a doc / branch line
816
+ * ONLY — `fix` / `implement` and the wave line never reopen. Returns whether the
817
+ * supersede stamp landed. */
818
+ async #reopenLeg(verb, type, scene, inflight) {
819
+ if (verb !== "review")
820
+ return false;
821
+ if (type !== "branch" && !TargetFaceTable.isDocShape(type))
822
+ return false;
823
+ const identity = this.#gate.lineIdentity(scene);
824
+ if (identity.key === null || identity.doc === null)
825
+ return false;
826
+ const state = await inflight.inspect();
827
+ if (state.kind !== "absent" || existsSync(inflight.lockPath()))
828
+ return false;
829
+ const ledger = scene.ledger;
830
+ if (ledger.reviewGate(identity.key, identity.doc, type).kind !== "open")
831
+ return false;
832
+ if (!ledger.pendingFix(identity.key, type))
833
+ return false;
834
+ const completed = ledger.completedCycles(identity.key, "review", type);
835
+ if (completed.length === 0)
836
+ return false;
837
+ // The next review cycle is the latest completed review's + 1 — allocated BEFORE
838
+ // the stamp lands (the spec's fixed action order), and it is exactly the cycle the
839
+ // following dispatch allocates (the register's cycle count is unchanged by a stamp).
840
+ const latest = Math.max(...completed);
841
+ return ledger.supersedeReview(identity.key, type, latest, latest + 1);
842
+ }
843
+ /** The invocation's lifecycle harness — the production dispatch face, held by the
844
+ * composition root so the abort fold can ride the SAME instance that dispatches
845
+ * (the takeover precedes the stamp, spec §2.1④). */
846
+ #lifecycleOf(scene, parsed) {
847
+ return new CliLifecycle({
762
848
  env: process.env,
763
849
  sync: this.#sync,
764
850
  template: this.#template,
@@ -774,11 +860,10 @@ export class Cli {
774
860
  overallLink: scene.overallLink,
775
861
  },
776
862
  reviews: parsed.paths.reviews,
777
- // The explicit takeover flag (`--steal-stale`): the ONLY path that displaces a
863
+ // The explicit takeover flag (`--recover`): the ONLY path that displaces a
778
864
  // standing in-flight record — and only when its holder is dead.
779
- stealStale: parsed.args.stealStale === "true",
865
+ recover: parsed.args.recover === "true",
780
866
  });
781
- return harness.step();
782
867
  }
783
868
  /** The branch scope anchor (BASE_BRANCH) — the base artifact's branch name read
784
869
  * from the line's own workspace (`base.json`, the same `base get` source the CLI
@@ -60,8 +60,8 @@ export const ARGV_CHANNEL = {
60
60
  help: "the base artifact's source channel",
61
61
  },
62
62
  force: { flag: "--force", type: "bool", help: "override the existing base artifact" },
63
- stealStale: {
64
- flag: "--steal-stale",
63
+ recover: {
64
+ flag: "--recover",
65
65
  type: "bool",
66
66
  help: "take over a standing in-flight record whose holder is dead (the only takeover path)",
67
67
  },
@@ -146,11 +146,7 @@ export const CLI_COMMANDS = [
146
146
  name: "implement",
147
147
  description: `run the task implement phase — at most ${MAX_TASKS_PER_WAVE} tasks per wave`,
148
148
  example: `cdd implement --tasks 1,2 --plan ${ENGINE_DOC_ROOTS.plans}/p3.md`,
149
- keys: [
150
- { key: "tasks", required: true },
151
- { key: "plan", required: true },
152
- { key: "stealStale" },
153
- ],
149
+ keys: [{ key: "tasks", required: true }, { key: "plan", required: true }, { key: "recover" }],
154
150
  },
155
151
  {
156
152
  name: "review",
@@ -162,7 +158,7 @@ export const CLI_COMMANDS = [
162
158
  { key: "plan" },
163
159
  { key: "spec" },
164
160
  { key: "round" },
165
- { key: "stealStale" },
161
+ { key: "recover" },
166
162
  ],
167
163
  },
168
164
  {
@@ -175,7 +171,7 @@ export const CLI_COMMANDS = [
175
171
  { key: "reviews" },
176
172
  { key: "spec" },
177
173
  { key: "plan" },
178
- { key: "stealStale" },
174
+ { key: "recover" },
179
175
  ],
180
176
  },
181
177
  {
@@ -18,14 +18,16 @@ import { existsSync, readFileSync } from "node:fs";
18
18
  import process from "node:process";
19
19
  import { printParseErrorCode } from "jsonc-parser";
20
20
  import { CompletionCriteria, FixDispositions } from "../contract/completion-criterion.js";
21
+ import { PlanTaskBlocksReader } from "../contract/task-blocks.js";
21
22
  import { GitClient } from "../infra/git.js";
22
23
  import { ProcessFacts } from "../infra/proc.js";
23
24
  import { RoundLog } from "../infra/round-log.js";
25
+ import { BriefRenderer } from "../render/brief.js";
24
26
  import { TemplateAssembler } from "../render/templates.js";
25
27
  import { TargetFaceTable } from "../session/faces.js";
26
28
  import { HandoffSchema } from "../session/handoff-schema.js";
27
29
  import { InFlight } from "../session/inflight.js";
28
- import { Ledger, RoundViolation, } from "../session/ledger.js";
30
+ import { Ledger, RoundRecords, RoundViolation, } from "../session/ledger.js";
29
31
  import { RoundNaming } from "../session/round-naming.js";
30
32
  import { PlanStructure } from "../session/run.js";
31
33
  import { DISPATCH, HOSTS, HostDetect, REFS } from "./host.js";
@@ -39,6 +41,10 @@ const STDOUT_TAIL_MAX = 40;
39
41
  * set or a task's `DependsOn` set moved inside the round (design spec §7.3). The
40
42
  * vanished / unreadable document cases name their own damage instead. */
41
43
  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";
44
+ /** The abort fold's ONE hard entry (spec §2.2) — the killed round's grade, cause
45
+ * (`interrupted`, the vocabulary's new literal) and prose. One entry, one cause: the
46
+ * fold records WHY the round has no conclusion, never a second diagnosis. */
47
+ const ABORT_INTERRUPTED = RoundViolation.hard("the dispatch was interrupted outside the engine — its in-flight record named a dead holder at takeover, so the round concluded nothing (the same command re-offers it)", "interrupted");
42
48
  /**
43
49
  * CliLifecycle — the lifecycle's dispatch-seam production default (the split contract's
44
50
  * lifecycle face; face/cli.ts re-exports it as HarnessDispatch so the composition
@@ -60,6 +66,9 @@ export class CliLifecycle {
60
66
  #io;
61
67
  #scene;
62
68
  #reviews;
69
+ /** The brief projection face — the wave frame's reviewed-basis hash rides the same
70
+ * task-only assembly the ledger binds (one projection, two callers). */
71
+ #brief;
63
72
  /** The single word table (the promotion WARN wording + its station) — one instance,
64
73
  * injected at the composition root, so the lifecycle never re-types a user-facing
65
74
  * line. */
@@ -68,6 +77,9 @@ export class CliLifecycle {
68
77
  * frame derives here (the report/evidence/brief names + the family op), so the
69
78
  * lifecycle and the dry-run preview name the same artifacts by one rule. */
70
79
  #naming;
80
+ /** The plan's task-block read face — the `Files` declaration the implement
81
+ * criterion's verification cell derives from (P30 §2.4). */
82
+ #blocks = new PlanTaskBlocksReader();
71
83
  /** The handoff-schema face — stateless, one shared instance (the read-back
72
84
  * validator + the injected prompt text). */
73
85
  #handoffSchema = new HandoffSchema();
@@ -81,10 +93,11 @@ export class CliLifecycle {
81
93
  * (`ProcessFacts.startOf`; injected by the tests to span a long session). */
82
94
  #proc;
83
95
  /** Whether this invocation asked to take over a dead holder's record (the
84
- * `--steal-stale` flag — the only takeover path). */
85
- #stealStale;
96
+ * `--recover` flag — the only takeover path). */
97
+ #recover;
86
98
  /** The HEAD the current dispatch started from (null off a repo / before a spawn) —
87
- * the postmortem baseline of `commitsSince`. */
99
+ * the postmortem baseline of `commitsSince` AND the in-flight record's
100
+ * `dispatchBase` cell (the killed round's group baseline a takeover restores, §2.2). */
88
101
  #dispatchBase = null;
89
102
  /** The commits added after `#dispatchBase` (computed once the child returned). */
90
103
  #commitsSince = [];
@@ -108,9 +121,10 @@ export class CliLifecycle {
108
121
  opts.inflight ?? new InFlight(opts.scene.workspace.root, opts.scene.workspace.slug);
109
122
  this.#git = opts.git ?? new GitClient();
110
123
  this.#proc = opts.proc ?? ProcessFacts;
111
- this.#stealStale = opts.stealStale ?? false;
124
+ this.#recover = opts.recover ?? false;
112
125
  this.#sync = opts.sync ?? new Terminator();
113
126
  this.#template = opts.template ?? new TemplateAssembler();
127
+ this.#brief = opts.brief ?? new BriefRenderer();
114
128
  this.#words = opts.words ?? new Words();
115
129
  this.#io = opts.io ?? {
116
130
  stdout: (t) => process.stdout.write(t),
@@ -129,6 +143,65 @@ export class CliLifecycle {
129
143
  step() {
130
144
  return (frame) => this.#dispatch(frame);
131
145
  }
146
+ /** The `--recover` abort leg (spec §2.1①/§2.2) — take over a stale in-flight record
147
+ * and, when the record can still name the killed round, fold that round into the
148
+ * ledger as an abort: `targetAction: false` plus ONE hard `interrupted` entry, the
149
+ * record's own cycle / attempt / `dispatchBase`. The group baseline therefore returns
150
+ * to before the killed round, so a recovery commit lands inside the next dispatch's
151
+ * window instead of being invisible.
152
+ *
153
+ * The three stale morphologies are judged HERE, exactly as `acquire({ recover })`
154
+ * judges them: a dead holder's readable record, a corrupt record with a leftover
155
+ * lock, a lock with no record behind it. Only the first carries a record back, so
156
+ * only it is booked — the other two have no op / cycle / baseline to read, and an
157
+ * invented identity is worse than no record (zero invention, same discipline as the
158
+ * `treeClean` pin below). A live holder is never displaced.
159
+ *
160
+ * Writes NO `crash-*.json` and promotes no draft: the crash record is the death face's
161
+ * (`#reject`), and this is the postmortem fold of a dispatch killed outside the
162
+ * engine — the two paths never mix. Returns whether an abort record was written. */
163
+ async foldAbort() {
164
+ const stale = await this.#inflight.staleState();
165
+ if (stale === null)
166
+ return false;
167
+ if (stale.kind === "held") {
168
+ const record = await this.#inflight.steal(InFlight.STEAL_REASON.deadHolder);
169
+ return record === null ? false : this.#bookAbort(record);
170
+ }
171
+ // The two record-less morphologies: the takeover is the whole effect (no op /
172
+ // cycle / baseline is readable, and an invented identity would be worse).
173
+ await this.#inflight.steal(stale.kind === "corrupt"
174
+ ? InFlight.STEAL_REASON.corruptRecord
175
+ : InFlight.STEAL_REASON.lockOnly);
176
+ return false;
177
+ }
178
+ /** Book one taken-over record as the killed round's abort fact — the cells are the
179
+ * record's OWN (op from its phase through the ledger's one mode mapping, cycle /
180
+ * attempt / baseline verbatim). `treeClean` is pinned TRUE explicitly: the fold makes
181
+ * no dispatch-after observation, so leaving the ledger's default to be re-read would
182
+ * let two implementations book different facts (`#softOf` folds
183
+ * `treeClean === false` into a dirty-tree observation).
184
+ *
185
+ * A record that cannot name its whole identity — the row key, the op, the cycle or the
186
+ * attempt — is NOT booked: the takeover happens, and no identity is made up for it. An
187
+ * allocated cycle or a defaulted attempt would be invented facts, and either could
188
+ * overwrite a real round's record on the same `(op, cycle, attempt)`. */
189
+ #bookAbort(record) {
190
+ const op = RoundRecords.opOf(record.phase ?? "");
191
+ const { wave: key, cycle, attempt } = record;
192
+ if (op === null || key === null || cycle === null || attempt === null)
193
+ return false;
194
+ this.#scene.ledger.recordRound(key, {
195
+ op,
196
+ cycle,
197
+ attempt,
198
+ dispatchBase: record.dispatchBase,
199
+ verdict: { treeClean: true, targetAction: false },
200
+ violations: [ABORT_INTERRUPTED],
201
+ carrierPath: null,
202
+ }, "wave");
203
+ return true;
204
+ }
132
205
  /** One dispatch — the round's work, the observation facts every record carries (the
133
206
  * dispatch baseline HEAD captured before the spawn, the dispatch-after
134
207
  * `treeClean` observation) and the TERMINAL VERDICT the round is booked under
@@ -216,10 +289,14 @@ export class CliLifecycle {
216
289
  ],
217
290
  };
218
291
  }
292
+ // The evidence gate is judged ONCE: its graded entries ride the verdict AND its
293
+ // result feeds the criterion's read-only `evidenceOk` cell (P30 §2.4) — the round
294
+ // pays for one evidence read, never two.
295
+ const evidence = this.#evidenceViolations(frame);
219
296
  const violations = [
220
297
  ...(outcome.violations ?? []),
221
- ...(await this.#criterionViolations(frame, outcome)),
222
- ...this.#evidenceViolations(frame),
298
+ ...(await this.#criterionViolations(frame, outcome, evidence)),
299
+ ...evidence,
223
300
  ...this.#structureViolations(frame),
224
301
  ...logEntries,
225
302
  ];
@@ -232,8 +309,13 @@ export class CliLifecycle {
232
309
  };
233
310
  }
234
311
  /** 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) {
312
+ * hard violation plus its SOFT observations (design spec §3.2/§3.3).
313
+ *
314
+ * The verification cells (P30 §2.4) are filled HERE, the single point: the wave's
315
+ * empty-`Files` task ids come from the plan document the dispatch already reads
316
+ * (`#emptyFileTasks`), and `evidenceOk` is the evidence judgment the round already
317
+ * ran — the gate's own result, never a second disk read. */
318
+ async #criterionViolations(frame, outcome, evidence) {
237
319
  const scene = this.#scene;
238
320
  const judged = await CompletionCriteria.of(this.#opOf(frame)).judge({
239
321
  record: this.#judgedRecordOf(frame, outcome),
@@ -243,12 +325,36 @@ export class CliLifecycle {
243
325
  reviewsPath: this.#reviewsPath(frame),
244
326
  git: this.#git,
245
327
  repoRoot: scene.workspace.root.repoRoot,
328
+ emptyFileTasks: this.#emptyFileTasks(),
329
+ evidenceOk: evidence.length === 0,
246
330
  });
247
331
  return [
248
332
  ...(judged.violation === null ? [] : [judged.violation]),
249
333
  ...(judged.observations ?? []),
250
334
  ];
251
335
  }
336
+ /** The plan tasks whose `Files` declaration names no path — the verification-wave
337
+ * cell. The PLAN document is the only source (never the diff): an absent plan, a
338
+ * plan path pointing at no document or an unreadable one declares no empty row, so
339
+ * a wave can never read as verification on a plan this dispatch could not see. */
340
+ #emptyFileTasks() {
341
+ const planPath = this.#scene.planPath;
342
+ if (planPath === null)
343
+ return new Set();
344
+ let content;
345
+ try {
346
+ content = readFileSync(planPath, "utf8");
347
+ }
348
+ catch {
349
+ return new Set();
350
+ }
351
+ const empty = new Set();
352
+ for (const block of this.#blocks.parse(content)) {
353
+ if (this.#blocks.filePathsOf(block).length === 0)
354
+ empty.add(block.id);
355
+ }
356
+ return empty;
357
+ }
252
358
  /** The round IDENTITY the criterion judges from — its op / cycle / attempt, the
253
359
  * group baseline and the carrier path the round writes. Deliberately verdict-free:
254
360
  * this judgment PRODUCES the verdict, so a verdict cell here would be a
@@ -376,7 +482,7 @@ export class CliLifecycle {
376
482
  // A sibling dispatch that won the lock in between makes `acquire` throw
377
483
  // `HoldingError` (carrying the holder's facts), which rides the CLI's held BLOCK.
378
484
  this.#dispatchBase = await this.#git.head(this.#scene.workspace.root.repoRoot);
379
- await this.#inflight.acquire(await this.#recordOf(frame), { stealStale: this.#stealStale });
485
+ await this.#inflight.acquire(await this.#recordOf(frame), { recover: this.#recover });
380
486
  // The round's own log file — created BEFORE the spawn (append stream open, zero
381
487
  // bytes), so the channel exists from the dispatch's first millisecond. A create
382
488
  // failure is a named soft observation and the round continues on the CPU leg
@@ -483,6 +589,7 @@ export class CliLifecycle {
483
589
  attempt: frame.attempt ?? 1,
484
590
  briefHash: this.#briefHashOf(frame),
485
591
  plan: scene.planPath === null ? null : this.#rel(scene.planPath),
592
+ dispatchBase: this.#dispatchBase,
486
593
  sampledAt: null,
487
594
  verdict: null,
488
595
  };
@@ -506,18 +613,20 @@ export class CliLifecycle {
506
613
  return null;
507
614
  }
508
615
  }
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. */
616
+ /** The wave frame's reviewed-basis hash at acquire time — `ReviewRefs.briefRevision`
617
+ * over the SAME task-only projection the ledger binds (`BriefRenderer#taskBody` of
618
+ * the plan for this wave's tasks — P29 §2.2, `## Constraints` excluded). Computed
619
+ * independently of the ledger's records, so a wave's FIRST dispatch (no
620
+ * `brief-revision` row yet) still carries the hash. Null off the wave face, on a
621
+ * plan-less scene and when the plan is unreadable. */
514
622
  #briefHashOf(frame) {
515
623
  const scene = this.#scene;
516
- if (frame.type !== "wave" || scene.planPath === null || scene.briefPath === null)
624
+ if (frame.type !== "wave" || frame.target.kind !== "wave" || scene.planPath === null)
517
625
  return null;
518
626
  try {
519
- const brief = readFileSync(scene.briefPath, "utf8");
520
- return scene.ledger.refs().briefRevision(this.#rel(scene.planPath), brief).brief_hash;
627
+ const plan = readFileSync(scene.planPath, "utf8");
628
+ const body = this.#brief.taskBody(plan, frame.target.tasks);
629
+ return scene.ledger.refs().briefRevision(this.#rel(scene.planPath), body).brief_hash;
521
630
  }
522
631
  catch {
523
632
  return null;
@@ -828,7 +937,7 @@ export class CliLifecycle {
828
937
  const requester = FixDispositions.requesterInputOf(this.#scene.ledger.recordsOf(frame.key, frame.type), frame.round, this.#reviewsPath(frame), this.#repoRootValue().absolute);
829
938
  if (requester.kind !== "read")
830
939
  return undefined;
831
- const counts = new FixDispositions().summaryOf(carrier, requester.summaries);
940
+ const counts = new FixDispositions().summaryOf(carrier, requester.findings);
832
941
  return FIX_DISPOSITIONS_SUMMARY.replace("{fixed}", String(counts.fixed)).replace("{rejected}", String(counts.rejected));
833
942
  }
834
943
  /** The requesting review carrier's path — the fix round's `--reviews` input, or the
@@ -1069,10 +1178,16 @@ export class CliLifecycle {
1069
1178
  }
1070
1179
  return Object.keys(out).length > 0 ? out : undefined;
1071
1180
  }
1072
- /** The draft findings as a plain list (the materialized carrier keeps them
1073
- * verbatim; the schema validated their shape before this ran). */
1181
+ /** The draft findings as the carrier's list — the child's rows kept VERBATIM except
1182
+ * for the ONE engine-owned column: `id`, stamped from the carrier position (`F1`,
1183
+ * `F2` …) and overwriting whatever the child wrote (P30 §2.5 — the disposition
1184
+ * primary key belongs to the engine, never to the audited prose). This is the only
1185
+ * write point of a finding id in the engine. */
1074
1186
  #findingsList(findings) {
1075
- return Array.isArray(findings) ? findings : [];
1187
+ const rows = Array.isArray(findings) ? findings : [];
1188
+ return rows.map((row, index) => typeof row === "object" && row !== null && !Array.isArray(row)
1189
+ ? { ...row, id: `F${index + 1}` }
1190
+ : row);
1076
1191
  }
1077
1192
  /** The same-command resume string — the crash record's `next`, mirroring the
1078
1193
  * CLI's dispatchable form of this frame (re-run the same command per the BLOCKED
@@ -69,7 +69,7 @@ export class Preview {
69
69
  /** The read-only held block — the in-flight gate REFUSED this dispatch: the preview
70
70
  * renders the gate's own holder facts as a `lock:` row (the dead holder carries the
71
71
  * takeover hint), exits 1 at the caller, and touches nothing: no acquire, no steal,
72
- * no release. The `--steal-stale` flag has no write channel here. */
72
+ * no release. The `--recover` flag has no write channel here. */
73
73
  heldBlock(verb, state) {
74
74
  const lines = [`cdd ${verb}: preview (no repo changes)`, ` lock: ${this.#lockValueOf(state)}`];
75
75
  if (state.kind === "held" && !state.alive)
@@ -81,7 +81,7 @@ export class RouteRenderer {
81
81
  return this.#words.routeWord("done");
82
82
  }
83
83
  /** renderReason(hop) → the `reason:` VALUE of one derived NextHop — the named fact
84
- * that selected the hop (one of the seven `NEXT_HOP_REASON` tokens), rendered as a
84
+ * that selected the hop (one of the eight `NEXT_HOP_REASON` tokens), rendered as a
85
85
  * row of its OWN so the dispatchable `next:` literal keeps its exact bytes. A
86
86
  * hop-absent round renders no row at all: the caller gates on the SAME hop object
87
87
  * its `next:` render reads, so the two rows can never disagree. The station word
@@ -113,7 +113,7 @@ export const CAPSULE_WORDS = {
113
113
  inFlight: {
114
114
  free: "free — no dispatch holds this tree",
115
115
  held: "held — pid {pid}",
116
- stale: "stale holder — pid {pid} (re-run with --steal-stale to take over)",
116
+ stale: "stale holder — pid {pid} (re-run with --recover to take over)",
117
117
  corruptLocked: "unreadable record — lock on disk",
118
118
  corruptUnlocked: "unreadable record — no lock behind",
119
119
  },
@@ -133,9 +133,9 @@ export const CAPSULE_WORDS = {
133
133
  * corrupt shapes and the three canonical recovery sentences. */
134
134
  inFlight: {
135
135
  held: "a dispatch is already in flight — pid {pid} · command: {command} · started: {startedAt} · running for {uptime} · wave: {wave} · slug: {slug}",
136
- stealable: "the holding process is gone — re-run the same command with --steal-stale to take the in-flight record over",
137
- corruptLocked: "the in-flight record is unreadable and its lock is still on disk — re-run with --steal-stale to take it over",
138
- corruptUnlocked: "the in-flight record is unreadable and no lock is left behind — re-run with --steal-stale to take it over",
136
+ stealable: "the holding process is gone — re-run the same command with --recover to take the in-flight record over",
137
+ corruptLocked: "the in-flight record is unreadable and its lock is still on disk — re-run with --recover to take it over",
138
+ corruptUnlocked: "the in-flight record is unreadable and no lock is left behind — re-run with --recover to take it over",
139
139
  lockHeld: "held by pid {pid} · command: {command} · started: {startedAt} · wave: {wave} · slug: {slug}",
140
140
  lockOnly: "held by an unreadable in-flight record — the lock is still on disk",
141
141
  free: "free — no dispatch holds this tree",
@@ -7,7 +7,9 @@
7
7
  // the plan's `## Constraints` section (the complete plan mirror). The checkable
8
8
  // gate blocks step surfaces that carry a step
9
9
  // with no checkable clause; a requested task with no matching heading blocks the
10
- // whole render (the group-level out-of-bounds contract).
10
+ // whole render (the group-level out-of-bounds contract). The task sections are
11
+ // also exposed alone (`taskBody`) — the wave's reviewed-basis projection (P29
12
+ // §2.2), so the child's bytes and the reopen fingerprint share one assembly.
11
13
  import { PlanDocType } from "../contract/doc.js";
12
14
  import { PlanTaskBlocksReader } from "../contract/task-blocks.js";
13
15
  /**
@@ -54,19 +56,27 @@ export class BriefRenderer {
54
56
  }
55
57
  return { data, missing };
56
58
  }
57
- /** Render the brief content — the requested task sections + the plan's
58
- * `## Constraints` section (the complete plan mirror). Any requested task without
59
- * a heading blocks the whole render (out-of-bounds). */
60
- render(planContent, tasks) {
59
+ /** The task-only projection — the wave's reviewed-basis content face: the requested
60
+ * `### Task N:` sections and nothing else. `render` appends the plan's
61
+ * `## Constraints` on top of this projection for the child; the reviewed-brief hash
62
+ * (`Ledger#briefRevision` / `#briefDrifted`) covers this projection alone (P29 §2.2
63
+ * — a Constraints reword is dispatch input, never a brief drift). One assembly,
64
+ * two consumers: zero second slicing logic. */
65
+ taskBody(planContent, tasks) {
61
66
  const { data, missing } = this.extract(planContent, tasks);
62
67
  if (missing.length > 0) {
63
68
  throw new Error(`task${missing.length > 1 ? "s" : ""} ${missing.join(", ")} not found in the plan`);
64
69
  }
65
70
  const lines = planContent.split("\n");
66
- const sections = data.map((task) => this.#slice(lines, task.range));
71
+ return data.map((task) => this.#slice(lines, task.range)).join("\n\n");
72
+ }
73
+ /** Render the brief content — the task-only projection + the plan's `## Constraints`
74
+ * section (the complete plan mirror the child reads). Any requested task without a
75
+ * heading blocks the whole render (out-of-bounds). */
76
+ render(planContent, tasks) {
77
+ const body = this.taskBody(planContent, tasks);
67
78
  const constraints = this.#reader.section(planContent, "Constraints");
68
- const body = constraints === "" ? sections.join("\n\n") : `${sections.join("\n\n")}\n\n${constraints}`;
69
- return `${body}\n`;
79
+ return constraints === "" ? `${body}\n` : `${body}\n\n${constraints}\n`;
70
80
  }
71
81
  /** The AST-range slice of one task block — the block's own lines verbatim, its
72
82
  * `####` children included (the retired `^#` scan cut a block at its first child