@oscaner-skills/cdd-engine 4.11.0 → 4.13.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.
@@ -21,7 +21,6 @@
21
21
  // algorithm lives in the single CommandTreeBuilder class (face/projection.ts).
22
22
  import { InvalidArgumentError } from "commander";
23
23
  import { MAX_TASKS_PER_WAVE } from "../contract/wave-width.js";
24
- import { ENGINE_DOC_ROOTS } from "../infra/doc-roots.js";
25
24
  import { HOST_IDS } from "./host.js";
26
25
  /** The argv channel table — the CLI flag/type/enum single source (the engine-config
27
26
  * argv channel verbatim: flag spellings, value types and enum domains ride these
@@ -94,6 +93,11 @@ export const ARGV_CHANNEL = {
94
93
  scope: "program",
95
94
  help: "show this help",
96
95
  },
96
+ artifacts: {
97
+ flag: "--artifacts",
98
+ type: "bool",
99
+ help: "expand the board's artifact inventory — one row per observed review round (a troubleshooting view, off by default)",
100
+ },
97
101
  output: {
98
102
  flag: "--output",
99
103
  type: "enum",
@@ -145,13 +149,13 @@ export const CLI_COMMANDS = [
145
149
  {
146
150
  name: "implement",
147
151
  description: `run the task implement phase — at most ${MAX_TASKS_PER_WAVE} tasks per wave`,
148
- example: `cdd implement --tasks 1,2 --plan ${ENGINE_DOC_ROOTS.plans}/p3.md`,
152
+ example: "cdd implement --tasks 1,2 --plan <path>",
149
153
  keys: [{ key: "tasks", required: true }, { key: "plan", required: true }, { key: "recover" }],
150
154
  },
151
155
  {
152
156
  name: "review",
153
157
  description: "run a review — wave | branch | phase-spec | overall | plan | single-spec",
154
- example: `cdd review --type phase-spec --spec ${ENGINE_DOC_ROOTS.specs}/p3-design.md`,
158
+ example: "cdd review --type phase-spec --spec <path>",
155
159
  keys: [
156
160
  { key: "type", required: true },
157
161
  { key: "tasks" },
@@ -177,7 +181,7 @@ export const CLI_COMMANDS = [
177
181
  {
178
182
  name: "base",
179
183
  description: "read/write base.json (single CDD --plan target)",
180
- example: `cdd base set --plan ${ENGINE_DOC_ROOTS.plans}/p3.md --base develop --source plan-field`,
184
+ example: "cdd base set --plan <path> --base develop --source plan-field",
181
185
  keys: [],
182
186
  leaves: [
183
187
  {
@@ -227,8 +231,8 @@ export const CLI_COMMANDS = [
227
231
  {
228
232
  name: "board",
229
233
  description: "render the progress board from a --plan or --spec entry (overall/phase-spec/single-spec/plan/wave/branch)",
230
- example: `cdd board --plan ${ENGINE_DOC_ROOTS.plans}/p3.md`,
231
- keys: [{ key: "plan" }, { key: "spec" }],
234
+ example: "cdd board --plan <path>",
235
+ keys: [{ key: "plan" }, { key: "spec" }, { key: "artifacts" }],
232
236
  },
233
237
  {
234
238
  name: "init",
package/dist/face/gate.js CHANGED
@@ -121,10 +121,13 @@ export class CliGate {
121
121
  }
122
122
  /** Render the task group brief into the workspace (the implement dispatch's input)
123
123
  * — the brief mirrors the current plan (its task sections + the `## Constraints`
124
- * section, re-extracted at every dispatch). */
125
- renderBrief(scene, parsed) {
124
+ * section, re-extracted at every dispatch). The document text and the parsed
125
+ * document arrive NARROWED: the caller (`Cli#runWork`'s `ready` branch) supplies
126
+ * both from the ONE plan read, so this face has no null branch — no `!`, no
127
+ * `?? ""` faking a read failure as an empty document. */
128
+ renderBrief(scene, parsed, text, doc) {
126
129
  const tasks = this.tasksOf(parsed);
127
- const content = this.#brief.render(scene.planText, tasks);
130
+ const content = this.#brief.render(text, doc, tasks);
128
131
  // The real run's workspace is built by the single write point (`Cli#runWork`'s
129
132
  // ensure, P11 · §4.2) BEFORE this render; the write still rides the workspace's
130
133
  // own text-write face (the `writeJson` mkdir-before-write pattern), never a
@@ -26,8 +26,8 @@ import { ProcessFacts } from "../infra/proc.js";
26
26
  import { RoundLog } from "../infra/round-log.js";
27
27
  import { BriefRenderer } from "../render/brief.js";
28
28
  import { TemplateAssembler } from "../render/templates.js";
29
+ import { ABSENT_READ, ArtifactReads } from "../session/artifact-reads.js";
29
30
  import { CarrierIntegrity, CarrierMismatchError } from "../session/carrier-integrity.js";
30
- import { CarrierRulings } from "../session/carrier-rulings.js";
31
31
  import { TargetFaceTable } from "../session/faces.js";
32
32
  import { HandoffSchema } from "../session/handoff-schema.js";
33
33
  import { InFlight } from "../session/inflight.js";
@@ -49,6 +49,9 @@ const STRUCTURE_CHANGED = "the plan's structure changed inside this round (the T
49
49
  * (`interrupted`, the vocabulary's new literal) and prose. One entry, one cause: the
50
50
  * fold records WHY the round has no conclusion, never a second diagnosis. */
51
51
  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");
52
+ /** The no-sidecar cell — off the fix face, an unattributable carrier, or a matrix
53
+ * `absent`: the slot stays empty and the gate has nothing to refuse. */
54
+ const NO_ARTIFACT = { kind: "read", value: ABSENT_READ };
52
55
  /**
53
56
  * CliLifecycle — the lifecycle's dispatch-seam production default (the split contract's
54
57
  * lifecycle face; face/cli.ts re-exports it as HarnessDispatch so the composition
@@ -99,6 +102,12 @@ export class CliLifecycle {
99
102
  /** Whether this invocation asked to take over a dead holder's record (the
100
103
  * `--recover` flag — the only takeover path). */
101
104
  #recover;
105
+ /** The artifact matrix this dispatch holds — the composition root's single instance,
106
+ * handed to the seal sweep so the carrier set is read out of ONE table, and read by
107
+ * the rulings face for the sidecar's name. Required: a dispatch that holds no table
108
+ * can not answer "is there a sidecar", and the old nullable field let that wiring bug
109
+ * read as a legal `absent` (the visibility rule's exact inversion). */
110
+ #artifacts;
102
111
  /** The HEAD the current dispatch started from (null off a repo / before a spawn) —
103
112
  * the postmortem baseline of `commitsSince` AND the in-flight record's
104
113
  * `dispatchBase` cell (the killed round's group baseline a takeover restores, §2.2). */
@@ -126,6 +135,7 @@ export class CliLifecycle {
126
135
  this.#git = opts.git ?? new GitClient();
127
136
  this.#proc = opts.proc ?? ProcessFacts;
128
137
  this.#recover = opts.recover ?? false;
138
+ this.#artifacts = opts.artifacts;
129
139
  this.#sync = opts.sync ?? new Terminator();
130
140
  this.#template = opts.template ?? new TemplateAssembler();
131
141
  this.#brief = opts.brief ?? new BriefRenderer();
@@ -202,7 +212,7 @@ export class CliLifecycle {
202
212
  dispatchBase: record.dispatchBase,
203
213
  verdict: { treeClean: true, targetAction: false },
204
214
  violations: [ABORT_INTERRUPTED],
205
- }, "wave");
215
+ });
206
216
  // P31 T5 §2.4 — the killed round's carrier names close with its abort record: the
207
217
  // draft the dead child may have left writable and the final it never materialized.
208
218
  // The identity is the record's OWN (op / cycle / attempt), never a re-derivation
@@ -303,10 +313,11 @@ export class CliLifecycle {
303
313
  * records, the persisted carrier, the round's baseline) plus the work plane's
304
314
  * evidence gate, and the graded entries decide the verdict: a round with no hard
305
315
  * entry is done. The judgment's two provider cells are supplied HERE, the single
306
- * point: `records` is the key's in-register history read with the line's DECLARED
307
- * word, and `reviewsPath` is the fix route's `--reviews` carrier or the ledger's
308
- * RESOLVED review-carrier fallback — the retired twin's name when the canonical
309
- * file is absent, never the never-minted canonical spelling.
316
+ * point: `records` is the key's in-register history read LITERALLY on that key (the
317
+ * row is the row — a retired spelling reads as absent, P36 §3), and `reviewsPath` is
318
+ * the fix route's `--reviews` carrier, the requester record's own carrier path, or
319
+ * the ledger's resolved review-carrier name — canonical, or the round's landed
320
+ * `final`, never a historical twin's spelling.
310
321
  *
311
322
  * A death face (a killed child, a non-zero exit, a rejected draft) already carries
312
323
  * its authored hard entry and needs no second judgment — the criterion table and
@@ -366,7 +377,7 @@ export class CliLifecycle {
366
377
  const judged = await CompletionCriteria.of(this.#opOf(frame)).judge({
367
378
  record: this.#judgedRecordOf(frame, outcome),
368
379
  row: this.#rowOf(frame),
369
- records: scene.ledger.recordsOf(frame.key, frame.type),
380
+ records: scene.ledger.recordsOf(frame.key),
370
381
  carrier: outcome.carrier ?? null,
371
382
  reviewsPath: this.#reviewsPath(frame),
372
383
  git: this.#git,
@@ -382,24 +393,25 @@ export class CliLifecycle {
382
393
  /** The plan tasks whose `Files` declaration names no path — the verification-wave
383
394
  * cell. The PLAN document is the only source (never the diff): an absent plan, a
384
395
  * plan path pointing at no document or an unreadable one declares no empty row, so
385
- * a wave can never read as verification on a plan this dispatch could not see. */
396
+ * a wave can never read as verification on a plan this dispatch could not see. A
397
+ * document the grammar refuses is the same shape: it declares no row either (the
398
+ * refusal leg speaks before the dispatch, and this cell never becomes a second,
399
+ * louder reporter of a broken plan). */
386
400
  #emptyFileTasks() {
387
401
  const planPath = this.#scene.planPath;
388
402
  if (planPath === null)
389
403
  return new Set();
390
- let content;
391
404
  try {
392
- content = readFileSync(planPath, "utf8");
405
+ const empty = new Set();
406
+ for (const block of this.#blocks.parse(readFileSync(planPath, "utf8"))) {
407
+ if (this.#blocks.filePathsOf(block).length === 0)
408
+ empty.add(block.id);
409
+ }
410
+ return empty;
393
411
  }
394
412
  catch {
395
413
  return new Set();
396
414
  }
397
- const empty = new Set();
398
- for (const block of this.#blocks.parse(content)) {
399
- if (this.#blocks.filePathsOf(block).length === 0)
400
- empty.add(block.id);
401
- }
402
- return empty;
403
415
  }
404
416
  /** The round IDENTITY the criterion judges from — its op / cycle / attempt and the
405
417
  * group baseline. Deliberately verdict-free AND path-free: the carrier a round
@@ -421,8 +433,7 @@ export class CliLifecycle {
421
433
  #rowOf(frame) {
422
434
  const ledger = this.#scene.ledger;
423
435
  const data = ledger.readProgress();
424
- return ((data === null ? undefined : Ledger.rowFor(data, frame.key, frame.type)) ??
425
- ledger.entryFor(frame.key));
436
+ return ((data === null ? undefined : Ledger.rowFor(data, frame.key)) ?? ledger.entryFor(frame.key));
426
437
  }
427
438
  /** The evidence gate as a graded entry (design spec §3.3) — the work plane's wave /
428
439
  * branch rounds write the evidence file at the round identity's own name
@@ -538,14 +549,18 @@ export class CliLifecycle {
538
549
  }
539
550
  // P31 T2 — the ruling sidecar gate: a sidecar the strict schema refuses stops the
540
551
  // round HERE, before the in-flight record is acquired and before any child exists
541
- // (a written-but-invisible ruling is the defect this gate removes).
542
- const rulingsRefusal = this.#rulingsRefusal(frame);
543
- if (rulingsRefusal !== null) {
552
+ // (a written-but-invisible ruling is the defect this gate removes). The judgment is
553
+ // ONE value computed here and handed to BOTH consumers (the gate and the prompt's
554
+ // round-context cell), so the `misplaced` / `invalid` / `ok` answers can never
555
+ // disagree between them — not even across a writer that lands mid-dispatch.
556
+ const artifactCell = this.#artifactCellOf(frame);
557
+ const artifactRefusal = this.#artifactRefusalOf(artifactCell);
558
+ if (artifactRefusal !== null) {
544
559
  this.#sealRoundCarriers(frame);
545
- this.#blocked(rulingsRefusal, false);
546
- return { status: "BLOCKED", violations: [RoundViolation.hard(rulingsRefusal)] };
560
+ this.#blocked(artifactRefusal, false);
561
+ return { status: "BLOCKED", violations: [RoundViolation.hard(artifactRefusal)] };
547
562
  }
548
- const prompt = this.#template.render(this.#valuesOf(frame));
563
+ const prompt = this.#template.render(this.#valuesOf(frame, artifactCell));
549
564
  const row = HOSTS[host];
550
565
  const cliName = row.cli;
551
566
  const args = [...row.invoke.split(" ").filter((part) => part.length > 0)];
@@ -705,14 +720,23 @@ export class CliLifecycle {
705
720
  * plan-less scene and when the plan is unreadable. */
706
721
  #briefHashOf(frame) {
707
722
  const scene = this.#scene;
708
- if (frame.type !== "wave" || frame.target.kind !== "wave" || scene.planPath === null)
723
+ const plan = scene.plan;
724
+ if (frame.type !== "wave" || frame.target.kind !== "wave")
725
+ return null;
726
+ const text = plan.text();
727
+ const doc = plan.doc();
728
+ const planPath = plan.stationPath();
729
+ if (text === null || doc === null || planPath === null)
709
730
  return null;
710
731
  try {
711
- const plan = readFileSync(scene.planPath, "utf8");
712
- const body = this.#brief.taskBody(plan, frame.target.tasks);
713
- return scene.ledger.refs().briefRevision(this.#rel(scene.planPath), body).brief_hash;
732
+ const body = this.#brief.taskBody(text, doc, frame.target.tasks);
733
+ return scene.ledger.refs().briefRevision(this.#rel(planPath), body).brief_hash;
714
734
  }
715
735
  catch {
736
+ // The ONLY throw point left is the brief's own out-of-bounds gate
737
+ // (`task N not found in the plan` — a legal scene when the plan was amended
738
+ // after the wave compiled): the round then records no hash, the same failure
739
+ // face `Ledger#briefRevision` keeps.
716
740
  return null;
717
741
  }
718
742
  }
@@ -773,7 +797,7 @@ export class CliLifecycle {
773
797
  * (empty-valued keys are dropped), so each mode's round context carries only the
774
798
  * facts the mode reads. The review criteria/lens are NOT values — they fold into
775
799
  * the review type's fixed prefix (§3.7). */
776
- #valuesOf(frame) {
800
+ #valuesOf(frame, artifactCell) {
777
801
  const scene = this.#scene;
778
802
  const op = this.#opOf(frame);
779
803
  const role = this.#roleOf(frame);
@@ -798,10 +822,13 @@ export class CliLifecycle {
798
822
  // would be a short-circuit).
799
823
  INPUT_REVIEWS: op === "fix" ? this.#rel(this.#reviewsPath(frame) ?? "") : "",
800
824
  // P31 T2 — the ruling sidecar rides the fix input side alone (the review round's
801
- // own context has no sidecar yet). The path derives from the requesting carrier
802
- // by the ONE `.json` → `.rulings.json` rule; an absent sidecar leaves the slot
803
- // empty, so the assembler drops the line entirely.
804
- INPUT_RULINGS: this.#rulingsInputOf(frame),
825
+ // own context has no sidecar yet). The path is the matrix's `rulings` row rendered
826
+ // from the REVIEWED carrier's identity and the strict schema read composed beside
827
+ // it (`#artifactReadOf`), handed in as the dispatch's ONE judgment: the gate that
828
+ // just approved this dispatch and this slot are the same value, never two reads.
829
+ // An absent, unattributable or refused sidecar leaves the slot empty and the
830
+ // assembler drops the line.
831
+ INPUT_RULINGS: this.#rulingsInputOf(artifactCell),
805
832
  // The kind-named judged-doc anchors (the semantic retirement of the generic
806
833
  // INPUT_DOC): the plan line carries the plan document as its judged doc
807
834
  // (INPUT_PLAN) AND its design-spec reference (INPUT_SPEC — the `spec:`
@@ -899,7 +926,7 @@ export class CliLifecycle {
899
926
  * draft of a retried round) is already closed when it is reopened here: the window
900
927
  * is the two names, never a third file. */
901
928
  #openRoundCarriers(frame) {
902
- CarrierSeal.sweep(this.#scene.workspace.path, []);
929
+ CarrierSeal.sweep(this.#scene.workspace.path, [], this.#artifacts);
903
930
  for (const name of this.#roundCarrierNames(frame))
904
931
  CarrierSeal.unseal(name);
905
932
  }
@@ -1091,7 +1118,7 @@ export class CliLifecycle {
1091
1118
  #dispositionsSummary(frame, plane, carrier) {
1092
1119
  if (plane !== "work" || this.#opOf(frame) !== "fix")
1093
1120
  return undefined;
1094
- const requester = FixDispositions.requesterInputOf(this.#scene.ledger.recordsOf(frame.key, frame.type), frame.round, this.#reviewsPath(frame), this.#repoRootValue().absolute);
1121
+ const requester = FixDispositions.requesterInputOf(this.#scene.ledger.recordsOf(frame.key), frame.round, this.#reviewsPath(frame), this.#repoRootValue().absolute);
1095
1122
  if (requester.kind !== "read")
1096
1123
  return undefined;
1097
1124
  const counts = new FixDispositions().summaryOf(carrier, requester.findings);
@@ -1132,7 +1159,7 @@ export class CliLifecycle {
1132
1159
  * requesting carrier's path and its digest. */
1133
1160
  #requesterRecord(frame) {
1134
1161
  const reviewed = this.#scene.ledger
1135
- .recordsOf(frame.key, frame.type)
1162
+ .recordsOf(frame.key)
1136
1163
  .filter((record) => record.op === "review" && record.cycle === frame.round);
1137
1164
  return reviewed.reduce((newest, record) => (newest === null || record.attempt >= newest.attempt ? record : newest), null);
1138
1165
  }
@@ -1142,7 +1169,13 @@ export class CliLifecycle {
1142
1169
  * already existed before this dispatch (`INPUT_REVIEWS` is its own input), so every
1143
1170
  * other phase has no gate to set. A carrier with no recorded digest — a legacy round,
1144
1171
  * or a resolved path no record declared — is read as present facts: no comparison,
1145
- * no refusal. */
1172
+ * no refusal.
1173
+ *
1174
+ * The repo-relative carrier → absolute erasure is spelled here, and again inside the
1175
+ * sidecar seam (`session/artifact-reads.ts`), BY DESIGN: this one feeds the digest
1176
+ * read of the carrier's own bytes, that one feeds the schema's `carrier` comparison
1177
+ * and the sidecar's id set. The two are different reads of different files, not two
1178
+ * names for one fact. */
1146
1179
  #carrierRefusal(frame) {
1147
1180
  if (this.#opOf(frame) !== "fix")
1148
1181
  return null;
@@ -1169,92 +1202,86 @@ export class CliLifecycle {
1169
1202
  return this.#requesterRecord(frame)?.carrierDigest ?? null;
1170
1203
  }
1171
1204
  /** The fix round's ruling sidecar as the round-context value — the repo-relative
1172
- * sidecar path when a conforming sidecar sits beside the requesting carrier, plus the
1173
- * ruling bodies it carries, the empty string otherwise (off the fix face, with no
1174
- * resolved carrier, and when the sidecar is absent — the assembler drops the empty
1175
- * line). The strict judgment is the dispatch gate's `#rulingsRefusal`; this cell
1176
- * names the file the round may read AND states the verdicts (§2.5 AC: the rendered
1177
- * text matches the sidecar), so a ruling is never merely a path the child must
1178
- * re-open to discover. */
1179
- #rulingsInputOf(frame) {
1180
- if (this.#opOf(frame) !== "fix")
1181
- return "";
1182
- const carrier = this.#reviewsPath(frame);
1183
- if (carrier === null)
1184
- return "";
1185
- const verdict = this.#rulingsVerdict(frame, carrier);
1186
- if (verdict.kind !== "ok")
1187
- return "";
1188
- const sidecar = this.#rel(CarrierRulings.pathFor(carrier));
1189
- return [sidecar, ...verdict.rulings.map((ruling) => this.#rulingLine(ruling))].join("\n");
1190
- }
1191
- /** One rendering of a recorded ruling — the finding id it answers and the ruling's
1192
- * own text VERBATIM (never re-worded: the sidecar is the orchestrator's words, and
1193
- * the round context quotes them). Indented under the sidecar path's bullet so the
1194
- * cell reads as one input. */
1195
- #rulingLine(ruling) {
1196
- return ` - \`${ruling.finding}\` — ${ruling.ruling}`;
1197
- }
1198
- /** The pre-dispatch ruling gate — the strict sidecar verdict's refusal reason, or null
1199
- * when the round may proceed (no fix face, no resolved carrier, an absent sidecar, or
1200
- * a conforming one). A refusal is HARD and lands before the in-flight record and the
1201
- * child, so a broken ruling set can never be dispatched unnoticed (§2.6).
1205
+ * sidecar path alone, the empty string otherwise (off the fix face and when the
1206
+ * sidecar is absent — the assembler drops the empty line).
1202
1207
  *
1203
- * A `carrier-mismatch` from the sidecar's id read is the integrity refusal, never a
1204
- * ruling reason: a tampered carrier is not judged (its id set is not a fact this
1205
- * round may read), so the diagnostic names the bytes that changed. */
1206
- #rulingsRefusal(frame) {
1208
+ * One input, one reading: the round context names WHERE the rulings live, exactly as
1209
+ * `INPUT_REVIEWS` names the carrier it qualifies (spec §2.10). The ruling bodies stay
1210
+ * in the sidecar — the child opens the file — so the prompt tail carries no text whose
1211
+ * length the orchestrator's ruling set decides, and the sidecar keeps its single
1212
+ * source. The path is the artifact matrix's `rulings` render of the REVIEWED round's
1213
+ * identity, never a tail replacement on the carrier's name: the carrier's own spelling
1214
+ * (draft or final) can no longer move it.
1215
+ *
1216
+ * The judgment is the dispatch's OWN cell — the value the gate just read — so the cell
1217
+ * can never name a ruling set the refusal is about to reject. */
1218
+ #rulingsInputOf(cell) {
1219
+ if (cell.kind !== "read")
1220
+ return "";
1221
+ const { read } = cell.value;
1222
+ return read.kind === "ok" ? this.#rel(read.path) : "";
1223
+ }
1224
+ /** The artifact-identity gate as a PURE read — the `--dry-run` face's entry to the
1225
+ * same judgment the real dispatch applies before it takes the in-flight record and
1226
+ * before any child exists. The preview renders the returned reason verbatim, so a
1227
+ * dry run can never forecast a dispatch the real run would refuse (one read, two
1228
+ * faces). Nothing here writes: the read is the matrix's plus the strict schema's. */
1229
+ artifactRefusal(frame) {
1230
+ return this.#artifactRefusalOf(this.#artifactCellOf(frame));
1231
+ }
1232
+ /** The dispatch's artifact judgment — computed ONCE, then consumed by the gate and by
1233
+ * the prompt's round-context cell. Off the fix face there is nothing to read (no
1234
+ * requesting carrier, no sidecar), so the cell is the no-sidecar value; otherwise the
1235
+ * one read is taken here, and a tampered requesting carrier becomes the integrity arm
1236
+ * instead of a read (its id set is not a fact this round may read). */
1237
+ #artifactCellOf(frame) {
1207
1238
  if (this.#opOf(frame) !== "fix")
1208
- return null;
1209
- const carrier = this.#reviewsPath(frame);
1210
- if (carrier === null)
1211
- return null;
1212
- let verdict;
1239
+ return NO_ARTIFACT;
1213
1240
  try {
1214
- verdict = this.#rulingsVerdict(frame, carrier);
1241
+ return { kind: "read", value: this.#artifactReadOf(frame, "rulings") };
1215
1242
  }
1216
1243
  catch (raw) {
1217
1244
  if (!(raw instanceof CarrierMismatchError))
1218
1245
  throw raw;
1219
- return raw.message;
1220
- }
1221
- return verdict.kind === "invalid" ? `rulings sidecar — ${verdict.reason}` : null;
1222
- }
1223
- /** The strict sidecar verdict over the requesting carrier's CHECKED id set — one call
1224
- * shape for the gate and the round-context cell, so neither can read the ids by a
1225
- * path the other does not take. */
1226
- #rulingsVerdict(frame, carrier) {
1227
- return CarrierRulings.verdict(carrier, this.#carrierFindingIds(frame, carrier));
1228
- }
1229
- /** The requesting carrier's engine-written finding ids (`F1`, `F2` …) — the id set a
1230
- * ruling must name. The read is the ONE checked carrier read (`CarrierIntegrity.read`,
1231
- * the digest its review round recorded): a tampered carrier is never observed at all —
1232
- * the mismatch throws and the integrity refusal wins over any ruling reason. An absent
1233
- * or unparseable carrier declares no ids, so any ruling beside it is refused by the
1234
- * strict schema instead of being accepted against an empty set. */
1235
- #carrierFindingIds(frame, carrier) {
1236
- const ids = new Set();
1237
- let carrierJson;
1238
- try {
1239
- const bytes = CarrierIntegrity.read(path.resolve(this.#repoRootValue().absolute, carrier), this.#requesterDigest(frame));
1240
- if (bytes === null)
1241
- return ids;
1242
- carrierJson = JSON.parse(bytes);
1243
- }
1244
- catch (raw) {
1245
- if (raw instanceof CarrierMismatchError)
1246
- throw raw;
1247
- return ids;
1248
- }
1249
- const findings = carrierJson?.findings;
1250
- if (!Array.isArray(findings))
1251
- return ids;
1252
- for (const finding of findings) {
1253
- const id = finding?.id;
1254
- if (typeof id === "string")
1255
- ids.add(id);
1246
+ return { kind: "mismatch", message: raw.message };
1256
1247
  }
1257
- return ids;
1248
+ }
1249
+ /** The ONE artifact read of this round's `kind` — delegated to the frame-free seam
1250
+ * (`session/artifact-reads.ts`), so this face keeps only the frame-level facts: the
1251
+ * requesting carrier and the digest its record remembered. The board reads the SAME
1252
+ * seam with its own workspace, so the prompt cell, the gate and the board can never
1253
+ * compose two different judgments (spec §2.3). */
1254
+ #artifactReadOf(frame, kind) {
1255
+ return new ArtifactReads(this.#artifacts, this.#scene.workspace).read(kind, this.#reviewsPath(frame) ?? "", this.#requesterDigest(frame));
1256
+ }
1257
+ /** The pre-dispatch artifact gate over the dispatch's ONE cell — the refusal reason of
1258
+ * this round's resolved `rulings` kind, or null when the round may proceed (no fix
1259
+ * face, no resolved carrier, an absent sidecar, or one conforming). A refusal is HARD
1260
+ * and lands before the in-flight record and the child, so a broken ruling set can
1261
+ * never be dispatched unnoticed (§2.4).
1262
+ *
1263
+ * Two refusal shapes, two words: a name that attributes to the identity but is NOT
1264
+ * its rendered name is `artifact-identity` (the four-section report — every candidate
1265
+ * listed, never a pick), while a present-but-unreadable file or a schema violation
1266
+ * keeps today's `rulings sidecar — <reason>` (the reason verbatim from the read).
1267
+ *
1268
+ * A `carrier-mismatch` from the sidecar's id read is the integrity refusal, never a
1269
+ * ruling reason: a tampered carrier is not judged (its id set is not a fact this
1270
+ * round may read), so the diagnostic names the bytes that changed. */
1271
+ #artifactRefusalOf(cell) {
1272
+ if (cell.kind === "mismatch")
1273
+ return cell.message;
1274
+ const read = cell.value.read;
1275
+ if (read.kind === "invalid")
1276
+ return `rulings sidecar — ${read.reason}`;
1277
+ if (read.kind !== "misplaced")
1278
+ return null;
1279
+ return this.#words.artifactIdentity({
1280
+ kind: "rulings",
1281
+ derived: this.#rel(this.#scene.workspace.resolve(read.derived)),
1282
+ found: read.found.map((name) => this.#rel(this.#scene.workspace.resolve(name))),
1283
+ identity: read.identity,
1284
+ });
1258
1285
  }
1259
1286
  /** The read-back rejection face — CDD_BLOCKED reason + the crash record (the
1260
1287
  * same-command resume's decision source: the attempted handoff + the resume
@@ -78,6 +78,15 @@ export class Preview {
78
78
  lines.push(this.#words.inFlightWords().corruptLocked);
79
79
  return lines;
80
80
  }
81
+ /** The read-only artifact-identity block — the dispatch gate REFUSED this dispatch
82
+ * (`misplaced` sidecar / unreadable one / a schema violation), so the preview prints
83
+ * the gate's OWN reason verbatim: one read, two faces, and a dry run can never
84
+ * forecast a dispatch the real run would refuse. Exit 1 at the caller; nothing is
85
+ * written, moved or deleted (the repair is the orchestrator's). */
86
+ artifactBlock(verb, reason) {
87
+ const [head, ...sections] = reason.split("\n");
88
+ return [`cdd ${verb}: preview (no repo changes)`, ` refused: ${head ?? ""}`, ...sections];
89
+ }
81
90
  /** The `lock:` row's value — the holder's identity facts, the lock-without-record
82
91
  * shape, or the free state (one row, three facts). */
83
92
  #lockValueOf(state) {
@@ -18,7 +18,7 @@
18
18
  // The route-borne prose (the fix readback suffix · the soft-cap message) rides
19
19
  // declared constants from session/next.ts, rendered by reference, never restated.
20
20
  // Module-level exports are the class — zero behavior-carrying bare functions.
21
- import { FIX_READBACK_SUFFIX, NEXT_HOP_REASON } from "../session/next.js";
21
+ import { FIX_READBACK_SLOT, FIX_READBACK_SUFFIX, NEXT_HOP_REASON, } from "../session/next.js";
22
22
  import { REFS } from "./host.js";
23
23
  /**
24
24
  * RouteRenderer — the single route → `next:` literal face (D40). One instance holds
@@ -153,7 +153,13 @@ export class RouteRenderer {
153
153
  * <readback>` (the readback suffix the declared constant, rendered by reference).
154
154
  * Every embedded path value (the doc-id for the doc shapes · `--reviews`)
155
155
  * is normalized to the repoRoot-relative shape (D47); the wave face's `<type-arg>`
156
- * is a task key, not a path — passed through as-is. */
156
+ * is a task key, not a path — passed through as-is.
157
+ *
158
+ * The readback sentence's PATH is a value the route carries (`Route.rulings`, rendered
159
+ * by the router from the carrier's own round identity): this face fills the declared
160
+ * slot and derives nothing. A route with no `rulings` value — a carrier the matrix
161
+ * cannot place — omits the sentence whole, so the line never prints an empty slot nor
162
+ * falls back to the naming rule the sentence used to teach. */
157
163
  #fixText(route, target) {
158
164
  if (route.reviews === undefined)
159
165
  return this.#words.routeWord("fix");
@@ -161,22 +167,32 @@ export class RouteRenderer {
161
167
  const type = target?.type ?? null;
162
168
  const id = target?.id ?? "";
163
169
  const reviews = this.#rel(route.reviews);
170
+ const readback = this.#readbackOf(route);
164
171
  if (type === "wave") {
165
- return `${verb} ${this.#flag("type")} wave ${this.#flag("tasks")} ${id} ${this.#flag("plan")} ${this.#planOf(target)} ${this.#flag("reviews")} ${reviews} ${FIX_READBACK_SUFFIX}`;
172
+ return `${verb} ${this.#flag("type")} wave ${this.#flag("tasks")} ${id} ${this.#flag("plan")} ${this.#planOf(target)} ${this.#flag("reviews")} ${reviews}${readback}`;
166
173
  }
167
174
  if (type === "plan") {
168
- return `${verb} ${this.#flag("type")} plan ${this.#flag("plan")} ${this.#rel(id)} ${this.#flag("reviews")} ${reviews} ${FIX_READBACK_SUFFIX}`;
175
+ return `${verb} ${this.#flag("type")} plan ${this.#flag("plan")} ${this.#rel(id)} ${this.#flag("reviews")} ${reviews}${readback}`;
169
176
  }
170
177
  if (type === "branch") {
171
178
  // The branch fix literal carries the workspace-identity `--plan` (isomorphic
172
179
  // with the wave fix branch — a plan-less target resolves to the empty
173
180
  // ref.short() directory, the workspace double identity).
174
- return `${verb} ${this.#flag("type")} branch ${this.#flag("plan")} ${this.#planOf(target)} ${this.#flag("reviews")} ${reviews} ${FIX_READBACK_SUFFIX}`;
181
+ return `${verb} ${this.#flag("type")} branch ${this.#flag("plan")} ${this.#planOf(target)} ${this.#flag("reviews")} ${reviews}${readback}`;
175
182
  }
176
183
  if (type === null)
177
- return `${verb} ${this.#flag("reviews")} ${reviews} ${FIX_READBACK_SUFFIX}`;
184
+ return `${verb} ${this.#flag("reviews")} ${reviews}${readback}`;
178
185
  // phase-spec · overall · single-spec — the declared shapes ride `--spec`.
179
- return `${verb} ${this.#flag("type")} ${type} ${this.#flag("spec")} ${this.#rel(id)} ${this.#flag("reviews")} ${reviews} ${FIX_READBACK_SUFFIX}`;
186
+ return `${verb} ${this.#flag("type")} ${type} ${this.#flag("spec")} ${this.#rel(id)} ${this.#flag("reviews")} ${reviews}${readback}`;
187
+ }
188
+ /** The fix readback sentence with the route's sidecar path in its value slot — the
189
+ * empty string when the route carries none (zero slot, zero sentence). The path is
190
+ * normalized through the ONE basis, exactly as the gate's `derived:` row is, so the
191
+ * two faces print one path byte for byte. */
192
+ #readbackOf(route) {
193
+ if (route.rulings === undefined)
194
+ return "";
195
+ return ` ${FIX_READBACK_SUFFIX.replace(FIX_READBACK_SLOT, this.#rel(route.rulings))}`;
180
196
  }
181
197
  /** The face-to-face handoff render — the pipeline entry: a `ref` fills the declared
182
198
  * instruction phrase (`route to {ref} skill`, the word table's `handoffRef` row)