@oscaner-skills/cdd-engine 4.7.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,6 +18,7 @@ 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";
@@ -26,7 +27,7 @@ import { TemplateAssembler } from "../render/templates.js";
26
27
  import { TargetFaceTable } from "../session/faces.js";
27
28
  import { HandoffSchema } from "../session/handoff-schema.js";
28
29
  import { InFlight } from "../session/inflight.js";
29
- import { Ledger, RoundViolation, } from "../session/ledger.js";
30
+ import { Ledger, RoundRecords, RoundViolation, } from "../session/ledger.js";
30
31
  import { RoundNaming } from "../session/round-naming.js";
31
32
  import { PlanStructure } from "../session/run.js";
32
33
  import { DISPATCH, HOSTS, HostDetect, REFS } from "./host.js";
@@ -40,6 +41,10 @@ const STDOUT_TAIL_MAX = 40;
40
41
  * set or a task's `DependsOn` set moved inside the round (design spec §7.3). The
41
42
  * vanished / unreadable document cases name their own damage instead. */
42
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");
43
48
  /**
44
49
  * CliLifecycle — the lifecycle's dispatch-seam production default (the split contract's
45
50
  * lifecycle face; face/cli.ts re-exports it as HarnessDispatch so the composition
@@ -72,6 +77,9 @@ export class CliLifecycle {
72
77
  * frame derives here (the report/evidence/brief names + the family op), so the
73
78
  * lifecycle and the dry-run preview name the same artifacts by one rule. */
74
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();
75
83
  /** The handoff-schema face — stateless, one shared instance (the read-back
76
84
  * validator + the injected prompt text). */
77
85
  #handoffSchema = new HandoffSchema();
@@ -85,10 +93,11 @@ export class CliLifecycle {
85
93
  * (`ProcessFacts.startOf`; injected by the tests to span a long session). */
86
94
  #proc;
87
95
  /** Whether this invocation asked to take over a dead holder's record (the
88
- * `--steal-stale` flag — the only takeover path). */
89
- #stealStale;
96
+ * `--recover` flag — the only takeover path). */
97
+ #recover;
90
98
  /** The HEAD the current dispatch started from (null off a repo / before a spawn) —
91
- * 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). */
92
101
  #dispatchBase = null;
93
102
  /** The commits added after `#dispatchBase` (computed once the child returned). */
94
103
  #commitsSince = [];
@@ -112,7 +121,7 @@ export class CliLifecycle {
112
121
  opts.inflight ?? new InFlight(opts.scene.workspace.root, opts.scene.workspace.slug);
113
122
  this.#git = opts.git ?? new GitClient();
114
123
  this.#proc = opts.proc ?? ProcessFacts;
115
- this.#stealStale = opts.stealStale ?? false;
124
+ this.#recover = opts.recover ?? false;
116
125
  this.#sync = opts.sync ?? new Terminator();
117
126
  this.#template = opts.template ?? new TemplateAssembler();
118
127
  this.#brief = opts.brief ?? new BriefRenderer();
@@ -134,6 +143,65 @@ export class CliLifecycle {
134
143
  step() {
135
144
  return (frame) => this.#dispatch(frame);
136
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
+ }
137
205
  /** One dispatch — the round's work, the observation facts every record carries (the
138
206
  * dispatch baseline HEAD captured before the spawn, the dispatch-after
139
207
  * `treeClean` observation) and the TERMINAL VERDICT the round is booked under
@@ -221,10 +289,14 @@ export class CliLifecycle {
221
289
  ],
222
290
  };
223
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);
224
296
  const violations = [
225
297
  ...(outcome.violations ?? []),
226
- ...(await this.#criterionViolations(frame, outcome)),
227
- ...this.#evidenceViolations(frame),
298
+ ...(await this.#criterionViolations(frame, outcome, evidence)),
299
+ ...evidence,
228
300
  ...this.#structureViolations(frame),
229
301
  ...logEntries,
230
302
  ];
@@ -237,8 +309,13 @@ export class CliLifecycle {
237
309
  };
238
310
  }
239
311
  /** The verb's completion-criterion verdict as graded entries — the criterion's own
240
- * hard violation plus its SOFT observations (design spec §3.2/§3.3). */
241
- 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) {
242
319
  const scene = this.#scene;
243
320
  const judged = await CompletionCriteria.of(this.#opOf(frame)).judge({
244
321
  record: this.#judgedRecordOf(frame, outcome),
@@ -248,12 +325,36 @@ export class CliLifecycle {
248
325
  reviewsPath: this.#reviewsPath(frame),
249
326
  git: this.#git,
250
327
  repoRoot: scene.workspace.root.repoRoot,
328
+ emptyFileTasks: this.#emptyFileTasks(),
329
+ evidenceOk: evidence.length === 0,
251
330
  });
252
331
  return [
253
332
  ...(judged.violation === null ? [] : [judged.violation]),
254
333
  ...(judged.observations ?? []),
255
334
  ];
256
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
+ }
257
358
  /** The round IDENTITY the criterion judges from — its op / cycle / attempt, the
258
359
  * group baseline and the carrier path the round writes. Deliberately verdict-free:
259
360
  * this judgment PRODUCES the verdict, so a verdict cell here would be a
@@ -381,7 +482,7 @@ export class CliLifecycle {
381
482
  // A sibling dispatch that won the lock in between makes `acquire` throw
382
483
  // `HoldingError` (carrying the holder's facts), which rides the CLI's held BLOCK.
383
484
  this.#dispatchBase = await this.#git.head(this.#scene.workspace.root.repoRoot);
384
- await this.#inflight.acquire(await this.#recordOf(frame), { stealStale: this.#stealStale });
485
+ await this.#inflight.acquire(await this.#recordOf(frame), { recover: this.#recover });
385
486
  // The round's own log file — created BEFORE the spawn (append stream open, zero
386
487
  // bytes), so the channel exists from the dispatch's first millisecond. A create
387
488
  // failure is a named soft observation and the round continues on the CPU leg
@@ -488,6 +589,7 @@ export class CliLifecycle {
488
589
  attempt: frame.attempt ?? 1,
489
590
  briefHash: this.#briefHashOf(frame),
490
591
  plan: scene.planPath === null ? null : this.#rel(scene.planPath),
592
+ dispatchBase: this.#dispatchBase,
491
593
  sampledAt: null,
492
594
  verdict: null,
493
595
  };
@@ -835,7 +937,7 @@ export class CliLifecycle {
835
937
  const requester = FixDispositions.requesterInputOf(this.#scene.ledger.recordsOf(frame.key, frame.type), frame.round, this.#reviewsPath(frame), this.#repoRootValue().absolute);
836
938
  if (requester.kind !== "read")
837
939
  return undefined;
838
- const counts = new FixDispositions().summaryOf(carrier, requester.summaries);
940
+ const counts = new FixDispositions().summaryOf(carrier, requester.findings);
839
941
  return FIX_DISPOSITIONS_SUMMARY.replace("{fixed}", String(counts.fixed)).replace("{rejected}", String(counts.rejected));
840
942
  }
841
943
  /** The requesting review carrier's path — the fix round's `--reviews` input, or the
@@ -1076,10 +1178,16 @@ export class CliLifecycle {
1076
1178
  }
1077
1179
  return Object.keys(out).length > 0 ? out : undefined;
1078
1180
  }
1079
- /** The draft findings as a plain list (the materialized carrier keeps them
1080
- * 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. */
1081
1186
  #findingsList(findings) {
1082
- 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);
1083
1191
  }
1084
1192
  /** The same-command resume string — the crash record's `next`, mirroring the
1085
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)
@@ -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",
@@ -121,7 +121,7 @@ const FIX_SHELL = [
121
121
  WORK_CAPABILITY,
122
122
  ...FIX_TYPED_INSTRUCTIONS,
123
123
  "**fix:** read `INPUT_REVIEWS` (open findings) + the plan context (`INPUT_WAVE_BRIEF` on a wave line — the complete plan mirror; `INPUT_PLAN` on the plan/branch lines — the plan document; `INPUT_SPEC` on the spec line — the spec document). Fix ALL findings (blocker/warn/nit), verifying against `INPUT_REVIEWS` none remain open. Fix + write the draft at `OUTPUT_HANDOFF` per `## Handoff schema` in one process; draft write failure → `status: BLOCKED`; retry = full re-run (idempotent).",
124
- '**Dispositions:** every requested finding needs a disposition keyed by its own summary text (verbatim), valued `{ "status": "fixed" | "rejected", "reason"?: "…" }` — a missing or mis-keyed disposition fails the round.',
124
+ '**Dispositions:** every requested finding needs a disposition keyed by its `id` exactly as the requesting carrier prints it (`F1`, `F2`, … — the summary is description only), valued `{ "status": "fixed" | "rejected", "reason"?: "…" }` — a missing or mis-keyed disposition fails the round.',
125
125
  EVIDENCE_ITEM,
126
126
  ...LICENSE_ITEMS,
127
127
  // T5 (v0.3) — The work plane's ONE strict-schema sentence: every top-level draft
@@ -144,7 +144,9 @@ const DOCS_FIX_SHELL = [
144
144
  ...FRAME_ITEMS,
145
145
  WORK_CAPABILITY,
146
146
  "**docs-fix:** apply `INPUT_REVIEWS` (all severities) directly to the judged doc — `INPUT_PLAN` on a plan-doc line, `INPUT_SPEC` on a spec-doc line — removing fixed findings; record the path in `artifacts.doc` and report the round in `status` (APPROVED once every finding is applied, else BLOCKED + the reason in `notes`). Fix + write the draft at `OUTPUT_HANDOFF` per `## Handoff schema` in one process; retry = full re-run (idempotent).",
147
- '**Dispositions:** every requested finding needs a disposition keyed by its own summary text (verbatim), valued `{ "status": "fixed" | "rejected", "reason"?: "…" }` — a missing or mis-keyed disposition fails the round.',
147
+ "**Change-history rows:** a new `## Change history` row bumps the front-matter `version:` in the same edit — the header version is the lineage's newest numeric version, and the two can never disagree.",
148
+ "**Table cells:** never hard-wrap a table cell — a wrapped continuation parses as a row whose cell count disagrees with the header, and the lineage row it was meant to be stops registering.",
149
+ '**Dispositions:** every requested finding needs a disposition keyed by its `id` exactly as the requesting carrier prints it (`F1`, `F2`, … — the summary is description only), valued `{ "status": "fixed" | "rejected", "reason"?: "…" }` — a missing or mis-keyed disposition fails the round.',
148
150
  ...LICENSE_ITEMS,
149
151
  // The generic strict-schema sentence — the SAME one the work shells carry: the
150
152
  // injected declaration is the draft's single field source, zero per-mode field
@@ -267,6 +269,13 @@ export const reviewGuideOf = (key) => {
267
269
  const text = REVIEW_BODY_TEXT[key];
268
270
  return SEVERITY_RUBRIC.replaceAll(SEVERITY_RUBRIC_SLOTS.artifact, text.artifact).replaceAll(SEVERITY_RUBRIC_SLOTS.audience, text.audience);
269
271
  };
272
+ /** The closed-wave discipline's ONE sentence (P30 §2.7) — the document review axes'
273
+ * shared body: a finding on an already-closed task block's content face is answered
274
+ * by the document, never by moving the work. Both document criteria bodies select
275
+ * it, so the duty cannot fork between the plan variant and the spec shapes; the
276
+ * engine routes nothing on it (no finding classification, no dispatch branch) — it is
277
+ * prompt text, judged by the reviewer. */
278
+ export const CLOSED_WAVE_DISCIPLINE = "Closed waves are history: a finding on the content face of an already-closed task block is answered by amending the document to align with the delivered split — never by carrying work into or out of a closed task, and a finding that would rewrite the historical split is not raised.";
270
279
  /** The spec-shaped documents' narrative criteria body — the phase-spec line's URC
271
280
  * + its program-conformance clause, the ONE body both spec-shaped target rows
272
281
  * select (the filled rubric is what differs per row). The charter's own criteria
@@ -276,7 +285,7 @@ export const reviewGuideOf = (key) => {
276
285
  * today's tree happens to have: a line number is not a pin, a prose count is the
277
286
  * guard's business, and a present-tense description of today's shape belongs to the
278
287
  * plan. Nothing gates the writing moment — the review is where a violation surfaces. */
279
- const docNarrativeAxes = (guide) => `Follow URC: single-cycle, lens-tagged findings (completeness/consistency/clarity) + the writing-plans self-check + verification evidence — the reviewer runs the repository's typecheck and test commands and self-reports the dual evidence + Claimed→pin: every behavior claim (usage-line attribution · semantic contract · byte face) must cite a colocated pin by module path + symbol name — a line number is not a pin; a count ("N places" · "N rows" · "N modules") must be stated as pinned by the named guard or test; a present-tense description of today's shape belongs to the plan — in a design spec a measurement input is a lens-tagged finding unless restated as a condition that must hold — the review checks every claim against its pin, claim by claim; a pinless claim is a lens-tagged finding + program conformance — judge the phase against its parent overall at \`INPUT_OVERALL\` (the charter its \`program:\` names): the phase must sit inside the scope the overall's Phase inventory registered for it, and a phase that reaches beyond it is a completeness finding. ${guide}`;
288
+ const docNarrativeAxes = (guide) => `Follow URC: single-cycle, lens-tagged findings (completeness/consistency/clarity) + the writing-plans self-check + verification evidence — the reviewer runs the repository's typecheck and test commands and self-reports the dual evidence + Claimed→pin: every behavior claim (usage-line attribution · semantic contract · byte face) must cite a colocated pin by module path + symbol name — a line number is not a pin; a count ("N places" · "N rows" · "N modules") must be stated as pinned by the named guard or test; a present-tense description of today's shape belongs to the plan — in a design spec a measurement input is a lens-tagged finding unless restated as a condition that must hold — the review checks every claim against its pin, claim by claim; a pinless claim is a lens-tagged finding + program conformance — judge the phase against its parent overall at \`INPUT_OVERALL\` (the charter its \`program:\` names): the phase must sit inside the scope the overall's Phase inventory registered for it, and a phase that reaches beyond it is a completeness finding. ${CLOSED_WAVE_DISCIPLINE} ${guide}`;
280
289
  /** The charter's criteria body — the six things a program charter owns, and only
281
290
  * those. It carries none of the implementation-face evidence duty the narrative
282
291
  * body carries (running the repository's commands, pinning every claim): a charter
@@ -306,7 +315,7 @@ export const REVIEWS = {
306
315
  },
307
316
  plan: {
308
317
  lensEnum: ["completeness", "decomposition", "buildability"],
309
- axesGuide: `Follow URC: single-cycle, lens-tagged findings (completeness/decomposition/buildability) + spec conformance — the plan is judged against its design spec at \`INPUT_SPEC\` (the plan's \`spec\` front-matter target): every spec requirement must map to a task, and a spec requirement with no owning task is a completeness finding + the writing-plans self-check + verification evidence — the reviewer runs the repository's typecheck and test commands and self-reports the dual evidence + Claimed→pin: every behavior claim (usage-line attribution · semantic contract · byte face) must cite a colocated pin (path:line + the assertion face) — the review checks every claim against its pin, claim by claim; a pinless claim is a lens-tagged finding. ${reviewGuideOf("plan")}`,
318
+ axesGuide: `Follow URC: single-cycle, lens-tagged findings (completeness/decomposition/buildability) + spec conformance — the plan is judged against its design spec at \`INPUT_SPEC\` (the plan's \`spec\` front-matter target): every spec requirement must map to a task, and a spec requirement with no owning task is a completeness finding + the writing-plans self-check + verification evidence — the reviewer runs the repository's typecheck and test commands and self-reports the dual evidence + Claimed→pin: every behavior claim (usage-line attribution · semantic contract · byte face) must cite a colocated pin (path:line + the assertion face) — the review checks every claim against its pin, claim by claim; a pinless claim is a lens-tagged finding. ${CLOSED_WAVE_DISCIPLINE} ${reviewGuideOf("plan")}`,
310
319
  },
311
320
  };
312
321
  /** The criteria-body selection — the ONE target → criteria map. Four targets select