@oscaner-skills/cdd-engine 4.13.0 → 4.15.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.
@@ -19,13 +19,16 @@ import path from "node:path";
19
19
  import process from "node:process";
20
20
  import { printParseErrorCode } from "jsonc-parser";
21
21
  import { CompletionCriteria, FixDispositions } from "../contract/completion-criterion.js";
22
+ import { NodeFs } from "../contract/invariants.js";
23
+ import { PinAudit } from "../contract/pins.js";
24
+ import { regradeNote } from "../contract/review-criteria.js";
22
25
  import { PlanTaskBlocksReader } from "../contract/task-blocks.js";
23
26
  import { CarrierSeal } from "../infra/carrier-seal.js";
24
27
  import { GitClient } from "../infra/git.js";
25
28
  import { ProcessFacts } from "../infra/proc.js";
26
29
  import { RoundLog } from "../infra/round-log.js";
27
30
  import { BriefRenderer } from "../render/brief.js";
28
- import { TemplateAssembler } from "../render/templates.js";
31
+ import { pinLensOf, TemplateAssembler } from "../render/templates.js";
29
32
  import { ABSENT_READ, ArtifactReads } from "../session/artifact-reads.js";
30
33
  import { CarrierIntegrity, CarrierMismatchError } from "../session/carrier-integrity.js";
31
34
  import { TargetFaceTable } from "../session/faces.js";
@@ -126,6 +129,13 @@ export class CliLifecycle {
126
129
  * when the channel opened — the record face must see a channel that never opened,
127
130
  * not only the stderr notice. */
128
131
  #logUnavailable = null;
132
+ /** The pin gate of this dispatch (P37 §7.2) — built on first use so the resolution
133
+ * index is walked once per process, never once per read. */
134
+ #pinIndex = null;
135
+ /** The existence read of the dispatch-input gate (P38 §2.1) — the ONE fact the
136
+ * `target-absent` reason takes from the filesystem. Injected like `git` / `proc` /
137
+ * `env` so a test judges the gate without touching the real tree. */
138
+ #fs;
129
139
  constructor(opts) {
130
140
  this.#env = opts.env ?? process.env;
131
141
  this.#scene = opts.scene;
@@ -139,6 +149,7 @@ export class CliLifecycle {
139
149
  this.#sync = opts.sync ?? new Terminator();
140
150
  this.#template = opts.template ?? new TemplateAssembler();
141
151
  this.#brief = opts.brief ?? new BriefRenderer();
152
+ this.#fs = opts.fs ?? new NodeFs();
142
153
  this.#words = opts.words ?? new Words();
143
154
  this.#io = opts.io ?? {
144
155
  stdout: (t) => process.stdout.write(t),
@@ -540,8 +551,10 @@ export class CliLifecycle {
540
551
  // the child, so a tampered input never reaches a child (the read-back and the CLI
541
552
  // catch are the fallbacks, never the gate). It runs BEFORE the ruling gate: the
542
553
  // integrity diagnostic is the fact, and a sidecar judged against tampered bytes
543
- // would name a ruling reason for a carrier whose bytes simply changed.
544
- const carrierRefusal = this.#carrierRefusal(frame);
554
+ // would name a ruling reason for a carrier whose bytes simply changed. It also runs
555
+ // before the dispatch-input gate below — the FIRST of the three pre-dispatch
556
+ // judgments, and the order the `--dry-run` face mirrors.
557
+ const carrierRefusal = this.carrierRefusal(frame);
545
558
  if (carrierRefusal !== null) {
546
559
  this.#sealRoundCarriers(frame);
547
560
  this.#blocked(carrierRefusal, false);
@@ -554,13 +567,27 @@ export class CliLifecycle {
554
567
  // round-context cell), so the `misplaced` / `invalid` / `ok` answers can never
555
568
  // disagree between them — not even across a writer that lands mid-dispatch.
556
569
  const artifactCell = this.#artifactCellOf(frame);
570
+ // P38 §2.1 — the dispatch-input gate: does this round stand at all (every required
571
+ // cell supplied, every read path on disk)? It runs BEFORE the artifact gate, which
572
+ // judges the quality of those inputs. The values are composed ONCE here and read by
573
+ // both the gate and the prompt render: one value, two consumers, never two
574
+ // compositions that could answer differently.
575
+ const values = this.#valuesOf(frame, artifactCell);
576
+ const inputRefusal = this.#inputRefusalOf(values, frame, "dispatch");
577
+ if (inputRefusal !== null) {
578
+ // Same exit shape as the two gates beside it: the preflight already opened this
579
+ // round's own two names, so a refusal seals them before it blocks.
580
+ this.#sealRoundCarriers(frame);
581
+ this.#blocked(inputRefusal, false);
582
+ return { status: "BLOCKED", violations: [RoundViolation.hard(inputRefusal)] };
583
+ }
557
584
  const artifactRefusal = this.#artifactRefusalOf(artifactCell);
558
585
  if (artifactRefusal !== null) {
559
586
  this.#sealRoundCarriers(frame);
560
587
  this.#blocked(artifactRefusal, false);
561
588
  return { status: "BLOCKED", violations: [RoundViolation.hard(artifactRefusal)] };
562
589
  }
563
- const prompt = this.#template.render(this.#valuesOf(frame, artifactCell));
590
+ const prompt = this.#template.render(values);
564
591
  const row = HOSTS[host];
565
592
  const cliName = row.cli;
566
593
  const args = [...row.invoke.split(" ").filter((part) => part.length > 0)];
@@ -795,8 +822,10 @@ export class CliLifecycle {
795
822
  * environment · BASE_BRANCH scope anchor). Every declared token supplied — a mode's
796
823
  * non-consumed slots stay empty and are NOT emitted by the assembler
797
824
  * (empty-valued keys are dropped), so each mode's round context carries only the
798
- * facts the mode reads. The review criteria/lens are NOT values — they fold into
799
- * the review type's fixed prefix (§3.7). */
825
+ * facts the mode reads — with the one declared exception: the `INPUT_RULINGS` cell
826
+ * is `absent: "none"`, so its line is always present and an empty value renders the
827
+ * bare literal `none` (§2.3 reversal ③). The review criteria/lens are NOT values —
828
+ * they fold into the review type's fixed prefix (§3.7). */
800
829
  #valuesOf(frame, artifactCell) {
801
830
  const scene = this.#scene;
802
831
  const op = this.#opOf(frame);
@@ -826,8 +855,11 @@ export class CliLifecycle {
826
855
  // from the REVIEWED carrier's identity and the strict schema read composed beside
827
856
  // it (`#artifactReadOf`), handed in as the dispatch's ONE judgment: the gate that
828
857
  // 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.
858
+ // WAS: an absent, unattributable or refused sidecar left the slot empty and the
859
+ // assembler dropped the line. NOW: P38 §2.3 reversal ③ — the cell is declared
860
+ // `absent: "none"`, so the line is always present and an empty value renders the
861
+ // bare literal `none` (the round reads "no ruling was recorded" instead of a
862
+ // missing row).
831
863
  INPUT_RULINGS: this.#rulingsInputOf(artifactCell),
832
864
  // The kind-named judged-doc anchors (the semantic retirement of the generic
833
865
  // INPUT_DOC): the plan line carries the plan document as its judged doc
@@ -835,31 +867,40 @@ export class CliLifecycle {
835
867
  // front-matter link target, the plan→spec conformance anchor); the branch line
836
868
  // carries the plan document (its plan-conformance reference) plus the same
837
869
  // design-spec reference, while the live tree against BASE_BRANCH is the judged
838
- // object; the spec-shaped doc targets (phase-spec · single-spec) carry their
839
- // spec document (INPUT_SPEC, the judged doc); the overall line's ONE charter
840
- // anchor is INPUT_OVERALL, so its INPUT_SPEC stays empty (C2 — the charter is
841
- // never its own spec). Empty off the off-faces (the slots are dropped by the
842
- // assembler).
870
+ // object; the wave line carries the same-slug identity document and its
871
+ // `program:` charter (P37 §4.1) so a code review reads the phase contract it is
872
+ // judged against; the spec-shaped doc targets (phase-spec · single-spec) carry
873
+ // their spec document (INPUT_SPEC, the judged doc); the overall line's ONE
874
+ // charter anchor is INPUT_OVERALL, so its INPUT_SPEC stays empty (C2 — the
875
+ // charter is never its own spec). Empty off the off-faces (the slots are dropped
876
+ // by the assembler).
843
877
  INPUT_PLAN: frame.type === "plan"
844
878
  ? this.#rel(docPath ?? "")
845
879
  : frame.type === "branch"
846
880
  ? this.#rel(scene.planPath ?? "")
847
881
  : "",
848
- INPUT_SPEC: frame.type === "plan" || frame.type === "branch"
882
+ INPUT_SPEC: frame.type === "plan" || frame.type === "branch" || frame.type === "wave"
849
883
  ? this.#rel(scene.specLink ?? "")
850
- : frame.type === "wave" || frame.type === "overall"
884
+ : frame.type === "overall"
851
885
  ? ""
852
886
  : // the spec-shaped doc targets (phase-spec · single-spec) carry the judged
853
887
  // document; the overall line's charter anchor is INPUT_OVERALL below.
854
888
  this.#rel(docPath ?? ""),
855
889
  // The parent charter of the spec the face reads (INPUT_OVERALL) — the overall
856
890
  // line's ONE charter anchor (the judged charter itself); the phase-spec line
857
- // carries its own `program:`; plan/branch carry the same-slug identity doc's
858
- // `program:`; empty off those faces and when the named program is absent (the
859
- // assembler drops the empty slot).
891
+ // carries its own `program:`; plan / branch / wave carry the same-slug identity
892
+ // doc's `program:` (the wave arm landed at P37 §4.1); empty off those faces and
893
+ // when the named program is absent. WAS: that empty value always dropped the
894
+ // slot. NOW: P38 §2.3 reversal ① — where the `program:` arm hits, the empty value
895
+ // is `target-absent` at the dispatch-input gate (the declaration names a charter
896
+ // that did not resolve); the drop remains only on the faces the cell does not
897
+ // serve (the `overall`-only arm).
860
898
  INPUT_OVERALL: frame.type === "overall"
861
899
  ? this.#rel(docPath ?? "")
862
- : frame.type === "phase-spec" || frame.type === "plan" || frame.type === "branch"
900
+ : frame.type === "phase-spec" ||
901
+ frame.type === "plan" ||
902
+ frame.type === "branch" ||
903
+ frame.type === "wave"
863
904
  ? this.#rel(scene.overallLink ?? "")
864
905
  : "",
865
906
  // The branch/wave tree-review scope anchor (BASE_BRANCH) — engine-injected
@@ -1071,6 +1112,13 @@ export class CliLifecycle {
1071
1112
  if (readBack.problems.length > 0) {
1072
1113
  return this.#reject(frame, path, `the handoff draft at ${path} violates the ${plane} schema: ${readBack.problems.join("; ")}`);
1073
1114
  }
1115
+ // P37 §7.2 — the pin read-back corpora ② and ③ are judged HERE, before the local
1116
+ // findings projection and before `conclusionOf`, so that ONE `rollup` reads them,
1117
+ // `DraftedOutcome.findings` projects them and `#materialize` persists them. The
1118
+ // judgment lives here and the write there: a warn injected at the writer would
1119
+ // reach the carrier while the round still concluded `APPROVED`.
1120
+ if (plane === "judge")
1121
+ this.#injectPinFindings(frame, draft);
1074
1122
  // T2 — the plane-aware read: the judge plane ALONE reads `draft.findings` (its
1075
1123
  // own declared required field — rolled up to the conclusion); the work plane
1076
1124
  // derives its status from the draft's declared status, never the findings slot
@@ -1078,6 +1126,16 @@ export class CliLifecycle {
1078
1126
  // The conclusion rides the ONE source (`HandoffSchema.conclusionOf`) the ledger
1079
1127
  // legs read too — the reconstruct never rules a work status by a second path.
1080
1128
  const findings = plane === "judge" ? (Array.isArray(draft.findings) ? draft.findings : []) : [];
1129
+ // P37 §2.2 — the blocker evidence gate: a blocker that cannot state its scenario is
1130
+ // refused on THIS read-back path (the same one `CDD_BLOCKED` line every schema
1131
+ // refusal rides — no second reporter, no `--dry-run` claim). The round produces no
1132
+ // conclusion instead of a BLOCKED one.
1133
+ // Rule zero (class-size limit): this file is well past the limit and predates it —
1134
+ // splitting it is P39's work (design spec D95 ②), not this round's.
1135
+ const grading = schema.gradingViolations(findings);
1136
+ if (grading.length > 0) {
1137
+ return this.#reject(frame, path, this.#gradingRefusal(grading));
1138
+ }
1081
1139
  // A validated draft's conclusion is total: the judge plane rolls up its own
1082
1140
  // required findings, and the work plane's `status` passed the `required` gate above
1083
1141
  // — so the `?? "BLOCKED"` never fires here (a work draft without a status never
@@ -1091,6 +1149,11 @@ export class CliLifecycle {
1091
1149
  let summary;
1092
1150
  try {
1093
1151
  summary = this.#dispositionsSummary(frame, plane, materialized.carrier);
1152
+ // P37 §5.2 — the downgrade note rides the SAME capsule `summary` slot: the
1153
+ // `emit` signature and key set do not move, and a round with no downgrade leaves
1154
+ // the slot undefined, so the stdout of an ordinary review round is byte-identical
1155
+ // to before this phase.
1156
+ summary ??= this.#downgradeNote(frame, plane, materialized.carrier);
1094
1157
  }
1095
1158
  catch (raw) {
1096
1159
  if (!(raw instanceof CarrierMismatchError))
@@ -1108,6 +1171,98 @@ export class CliLifecycle {
1108
1171
  violations: materialized.violations,
1109
1172
  };
1110
1173
  }
1174
+ /** P37 §7.2 — the two read-back corpora of the pin gate, injected as REAL warn-level
1175
+ * findings into `draft.findings`. The row's LENS is the judged face's own declared
1176
+ * `pinLens` (`render/templates.ts#pinLensOf`), never a literal here: the child's
1177
+ * prompt declares a lens menu per face, and an engine row outside that menu would
1178
+ * be unreadable as "the engine wrote it" to every later reader. They are not a
1179
+ * refusal: no `CDD_BLOCKED` is printed, and the round keeps its conclusions — a warn
1180
+ * reaches `rollup`, so a review round with a dead pin concludes `REVIEW_FIX` instead
1181
+ * of `APPROVED`. Nothing here is a second reporting surface: the rows enter the same
1182
+ * `findings[]`, are projected by the same `findingsOf`, and are keyed by the same
1183
+ * `#findingsList` at materialize. */
1184
+ #injectPinFindings(frame, draft) {
1185
+ const lens = pinLensOf(frame.type);
1186
+ const injected = [
1187
+ ...this.#documentPinRows(frame, lens),
1188
+ ...this.#contractPinRows(draft, lens, _a.#judgedDocOf(frame)),
1189
+ ];
1190
+ if (injected.length === 0)
1191
+ return;
1192
+ const rows = Array.isArray(draft.findings) ? draft.findings : [];
1193
+ draft.findings = [...rows, ...injected];
1194
+ }
1195
+ /** The document this round judges (§7.3 condition ①'s subject) — a repo-relative
1196
+ * path for the two doc-target kinds, `null` for a wave / branch round: those audit
1197
+ * no document body, so a `Create:` declaration has no identity key to match and its
1198
+ * pending path stays a finding (design spec §7.2's `standards` arm). */
1199
+ static #judgedDocOf(frame) {
1200
+ const target = frame.target;
1201
+ return target.kind === "spec" || target.kind === "plan" ? target.doc : null;
1202
+ }
1203
+ /** Corpus ② — the JUDGED document's own body (the three doc targets only; a wave /
1204
+ * branch / plan round judges no document body). The path comes from `frame.target`
1205
+ * (`{ kind: "spec", doc }`, resolved at the CLI seam), and the body is read through
1206
+ * this class's own repo read: `#reconstruct` builds no second `SlugIndex` and adds no
1207
+ * field to `DispatchScene`. */
1208
+ #documentPinRows(frame, lens) {
1209
+ if (frame.target.kind !== "spec")
1210
+ return [];
1211
+ const doc = frame.target.doc;
1212
+ let body;
1213
+ try {
1214
+ body = readFileSync(path.resolve(this.#repoRootValue().absolute, doc), "utf8");
1215
+ }
1216
+ catch {
1217
+ return [];
1218
+ }
1219
+ return this.#pinAudit()
1220
+ .scanText(body, this.#rel(doc))
1221
+ .map((finding) => _a.#pinRow(finding.summary, lens));
1222
+ }
1223
+ /** Corpus ③ — each finding's `contract.path` (design spec §2.3). `PinAudit`'s
1224
+ * markdown scan never carries this cell: the anchor is a declared coordinate, judged
1225
+ * on its own. A missing path appends one warn per offending finding. The judged
1226
+ * document rides in as the time face's subject (§7.3): a `Create:` declaration of
1227
+ * the judged document's own plan is pending, not dead. */
1228
+ #contractPinRows(draft, lens, judged) {
1229
+ const rows = Array.isArray(draft.findings) ? draft.findings : [];
1230
+ const audit = this.#pinAudit();
1231
+ const rel = judged === null ? null : this.#rel(judged);
1232
+ const out = [];
1233
+ for (const row of rows) {
1234
+ const pin = row?.contract?.path;
1235
+ if (typeof pin !== "string" || pin.trim().length === 0)
1236
+ continue;
1237
+ if (audit.pathResolves(pin.trim(), rel))
1238
+ continue;
1239
+ out.push(_a.#pinRow(`the pin \`${pin.trim()}\` resolves nowhere — the finding's \`contract.path\` anchor names no path in the tree`, lens));
1240
+ }
1241
+ return out;
1242
+ }
1243
+ /** One injected pin finding — a warn under the judged face's own declared pin lens,
1244
+ * the tier §7.2 pins and the lens its menu can carry. */
1245
+ static #pinRow(summary, lens) {
1246
+ return { severity: "warn", lens, summary };
1247
+ }
1248
+ /** The one audit instance of this dispatch — the resolution index is built once and
1249
+ * shared by both corpora (and by every round this instance drives). */
1250
+ #pinAudit() {
1251
+ this.#pinIndex ??= new PinAudit(this.#repoRootValue().absolute);
1252
+ return this.#pinIndex;
1253
+ }
1254
+ /** The blocker-evidence refusal (design spec §2.2): the first word after
1255
+ * `CDD_BLOCKED:` is the criteria row's `id` — written as a LITERAL here, because the
1256
+ * gate's pin is the printed byte, not an import of the registry — followed by every
1257
+ * offending finding's `id` and `summary` (all of them, never one of two). */
1258
+ #gradingRefusal(violations) {
1259
+ const labels = violations.map((violation) => {
1260
+ const summary = violation.summary?.trim() ?? "";
1261
+ const quoted = summary.length === 0 ? "" : ` "${summary}"`;
1262
+ return `${violation.id ?? "unkeyed"}${quoted}`;
1263
+ });
1264
+ return `grading-impact-missing: finding(s) graded blocker carry no \`impact.scenario\` — ${labels.join("; ")}`;
1265
+ }
1111
1266
  /** The fix round's ONE summary line (design spec §3.4) — computed from the PERSISTED
1112
1267
  * carrier's dispositions and the REQUESTING carrier's input set (the same pair the
1113
1268
  * fix criterion judges), never stored: no record field, no carrier key, no capsule
@@ -1124,14 +1279,65 @@ export class CliLifecycle {
1124
1279
  const counts = new FixDispositions().summaryOf(carrier, requester.findings);
1125
1280
  return FIX_DISPOSITIONS_SUMMARY.replace("{fixed}", String(counts.fixed)).replace("{rejected}", String(counts.rejected));
1126
1281
  }
1282
+ /** P37 §5.1 · §5.2 — the capsule's downgrade note. The current round's findings are
1283
+ * judged against the NEAREST EARLIER review record on this line whose findings
1284
+ * projection is non-empty (a clean implement / fix record between the two never
1285
+ * resets the reference); a lowered grade against a non-empty earlier scenario prints
1286
+ * the stated `regrade` reason, and one that states none prints the mark. Display
1287
+ * only: the note is the capsule's `summary` line, never a finding row, never a carrier
1288
+ * entry, and it never moves the round's conclusion. */
1289
+ #downgradeNote(frame, plane, carrier) {
1290
+ if (plane !== "judge")
1291
+ return undefined;
1292
+ const current = this.#handoffSchema.findingsOf(carrier.findings);
1293
+ if (current.length === 0)
1294
+ return undefined;
1295
+ const prior = this.#priorFindings(frame);
1296
+ return regradeNote(HandoffSchema.downgrades(prior, current).length, HandoffSchema.regradeReasons(prior, current));
1297
+ }
1298
+ /** The "previous round" of §5.1 — the nearest earlier REVIEW record on this line
1299
+ * whose findings projection is non-empty. `id` is never the match key (it is the
1300
+ * engine-written row number), so the reference is a whole findings set, not a row
1301
+ * picked by position. The read is the ledger's ONE checked carrier read. */
1302
+ #priorFindings(frame) {
1303
+ const current = { cycle: frame.round, attempt: frame.attempt ?? 1 };
1304
+ const earlier = this.#scene.ledger
1305
+ .recordsOf(frame.key)
1306
+ .filter((record) => record.op === "review")
1307
+ .filter((record) => _a.#before(record, current))
1308
+ .sort((left, right) => left.cycle === right.cycle ? right.attempt - left.attempt : right.cycle - left.cycle);
1309
+ for (const record of earlier) {
1310
+ const previous = this.#scene.ledger.readHandoff("review", frame.type, {
1311
+ tasks: frame.params.tasks,
1312
+ round: record.cycle,
1313
+ attempt: record.attempt,
1314
+ });
1315
+ if (previous === null)
1316
+ continue;
1317
+ const findings = this.#handoffSchema.findingsOf(previous.findings);
1318
+ if (findings.length > 0)
1319
+ return findings;
1320
+ }
1321
+ return [];
1322
+ }
1323
+ /** Whether `record` precedes the current round — the `(cycle, attempt)` order the
1324
+ * round identity itself uses. */
1325
+ static #before(record, current) {
1326
+ return record.cycle === current.cycle
1327
+ ? record.attempt < current.attempt
1328
+ : record.cycle < current.cycle;
1329
+ }
1127
1330
  /** The requesting review carrier's path — the fix round's `--reviews` input, or the
1128
1331
  * same-cycle review record's carrier identity through the ledger's ONE accessor
1129
1332
  * (the recorded path, then the read ladder a pre-P31 row needs), or the ledger's
1130
1333
  * resolved family name when the line records no review for this cycle. A record
1131
- * that resolves no carrier reads `null` — the UNRECORDED face, which the criterion
1132
- * books as a visible skip instead of failing the round on a hard absent-carrier
1133
- * refusal. Record-present means the record's own final wins: a draft sitting beside
1134
- * it never becomes the judged input. */
1334
+ * that resolves no carrier reads `null`. Record-present means the record's own final
1335
+ * wins: a draft sitting beside it never becomes the judged input.
1336
+ *
1337
+ * WAS: a `null` here was the UNRECORDED face, which the criterion booked as a visible
1338
+ * skip and the fix round dispatched without a review input. NOW: P38 §2.3 reversal ② —
1339
+ * `INPUT_REVIEWS` is `always`-required, so that value is `empty-value` at the
1340
+ * dispatch-input gate and the round stops before the child exists. */
1135
1341
  #reviewsPath(frame) {
1136
1342
  if (this.#reviews !== null)
1137
1343
  return this.#reviews;
@@ -1175,8 +1381,15 @@ export class CliLifecycle {
1175
1381
  * sidecar seam (`session/artifact-reads.ts`), BY DESIGN: this one feeds the digest
1176
1382
  * read of the carrier's own bytes, that one feeds the schema's `carrier` comparison
1177
1383
  * and the sidecar's id set. The two are different reads of different files, not two
1178
- * names for one fact. */
1179
- #carrierRefusal(frame) {
1384
+ * names for one fact.
1385
+ *
1386
+ * A PURE read, so it is also the `--dry-run` face's first pre-dispatch entry, beside
1387
+ * `inputRefusal` / `artifactRefusal` and in the order `#runDispatch` applies the three
1388
+ * (carrier-integrity → dispatch-input → artifact-identity): the preview renders the
1389
+ * returned reason verbatim, so a dry run can never forecast a dispatch the real run
1390
+ * would refuse — the tampered carrier included, whichever other gate the frame also
1391
+ * fails. */
1392
+ carrierRefusal(frame) {
1180
1393
  if (this.#opOf(frame) !== "fix")
1181
1394
  return null;
1182
1395
  const carrier = this.#reviewsPath(frame);
@@ -1203,7 +1416,9 @@ export class CliLifecycle {
1203
1416
  }
1204
1417
  /** The fix round's ruling sidecar as the round-context value — the repo-relative
1205
1418
  * sidecar path alone, the empty string otherwise (off the fix face and when the
1206
- * sidecar is absent — the assembler drops the empty line).
1419
+ * sidecar is absent). WAS: the empty value made the assembler drop the whole line.
1420
+ * NOW: P38 §2.3 reversal ③ — the cell is declared `absent: "none"`, so the line is
1421
+ * always present and an empty value renders the bare literal `none`.
1207
1422
  *
1208
1423
  * One input, one reading: the round context names WHERE the rulings live, exactly as
1209
1424
  * `INPUT_REVIEWS` names the carrier it qualifies (spec §2.10). The ruling bodies stay
@@ -1229,6 +1444,89 @@ export class CliLifecycle {
1229
1444
  artifactRefusal(frame) {
1230
1445
  return this.#artifactRefusalOf(this.#artifactCellOf(frame));
1231
1446
  }
1447
+ /** The `dispatch-input` gate as a PURE read (P38 §2.1) — whether THIS round can stand
1448
+ * at all: every cell its layout requires was supplied, and every read path it names
1449
+ * is on disk. It sits beside `artifactRefusal` for the same reason (one judgment, two
1450
+ * consumers): the `--dry-run` face renders this answer verbatim, so a preview can
1451
+ * never forecast a dispatch the real run would refuse. Nothing here writes and no
1452
+ * document is parsed at dispatch — exigibility reads the two DECLARED scene cells.
1453
+ *
1454
+ * `mode` defaults to `dispatch`: the preview's one weaker arm (`preview: satisfied`)
1455
+ * must be asked for by name, so no caller silently takes it. */
1456
+ inputRefusal(frame, mode = "dispatch") {
1457
+ return this.#inputRefusalOf(this.#valuesOf(frame, this.#artifactCellOf(frame)), frame, mode);
1458
+ }
1459
+ /** The dispatch-input judgment over the values about to be rendered (§2.1–§2.3) — the
1460
+ * definition is given by the declaration, never by a second table: the judged cells
1461
+ * are `layoutOf(values)`, the same row selection the renderer reads. Every failing
1462
+ * cell becomes one segment, all of them reported in one pass (`; `-joined), so a
1463
+ * refused round is repaired once instead of one cell per dispatch. */
1464
+ #inputRefusalOf(values, frame, mode) {
1465
+ const row = values.ROLE;
1466
+ const segments = [];
1467
+ for (const decl of this.#template.layoutOf(values)) {
1468
+ const token = TemplateAssembler.slotOf(decl.line);
1469
+ if (token === undefined)
1470
+ continue;
1471
+ const hits = decl.requiredOn.filter((arm) => this.#armHits(arm, frame));
1472
+ if (hits.length === 0)
1473
+ continue;
1474
+ const satisfied = mode === "preview" && this.#answeredByNaming(decl, token, frame);
1475
+ const value = values[token] ?? "";
1476
+ if (value === "") {
1477
+ if (satisfied)
1478
+ continue;
1479
+ segments.push({ row, token, reason: _a.#emptyReasonOf(hits) });
1480
+ continue;
1481
+ }
1482
+ if (decl.path !== true || satisfied)
1483
+ continue;
1484
+ // The value is a repoRoot-relative read path (§1.1) — the ONE erasure point turns
1485
+ // it absolute before the existence read, so a dispatch started from a subdirectory
1486
+ // never reads every landed path as absent.
1487
+ const absolute = this.#repoRootValue().resolve(value);
1488
+ if (!this.#fs.exists(absolute))
1489
+ segments.push({ row, token, reason: "target-absent" });
1490
+ }
1491
+ return segments.length === 0 ? null : this.#words.dispatchInput({ segments });
1492
+ }
1493
+ /** Whether one declared arm is exigible on this frame (§1.3) — the type hit plus, when
1494
+ * the arm carries one, its structural precondition. Both preconditions read the two
1495
+ * DECLARED scene cells (`program` · `docType`), never the resolved links: a declared
1496
+ * program whose charter does not resolve and a program never declared are different
1497
+ * facts, and only the declaration can tell them apart. */
1498
+ #armHits(arm, frame) {
1499
+ const typed = arm.types === "always" || arm.types.includes(frame.type);
1500
+ if (!typed)
1501
+ return false;
1502
+ if (arm.when === "program")
1503
+ return this.#scene.program != null;
1504
+ if (arm.when === "identity")
1505
+ return this.#scene.docType != null;
1506
+ return true;
1507
+ }
1508
+ /** The reason an exigible cell's EMPTY value earns (§2.2's closed set): an arm whose
1509
+ * precondition is the declared `program:` that hit means the charter the declaration
1510
+ * names did not resolve (`target-absent`); every other empty value is the engine's own
1511
+ * omission (`empty-value`). The two `when` legs are told apart by this word alone. */
1512
+ static #emptyReasonOf(hits) {
1513
+ return hits.some((arm) => arm.when === "program") ? "target-absent" : "empty-value";
1514
+ }
1515
+ /** Whether the preview's `satisfied` answer applies to this cell (§2.4) — the ONLY
1516
+ * reader of `preview: "satisfied"`. The naming line that writes this cell's artifact
1517
+ * is the answer's source: the brief is the one cell `renderBrief` writes at dispatch
1518
+ * alone, so a wave that names its task group names its brief, and a wave that names
1519
+ * none falls back to the empty-value arm. The exemption covers the existence leg too:
1520
+ * a preview never asks a file it would not write. The token guard is the second half
1521
+ * of one rule: the assembler refuses any OTHER cell declaring `satisfied` at
1522
+ * construction (#assertPreviewAnswer), so a declaration the naming row cannot answer
1523
+ * never reaches a preview. */
1524
+ #answeredByNaming(decl, token, frame) {
1525
+ if (decl.preview !== "satisfied" || token !== TemplateAssembler.NAMED_BRIEF_CELL)
1526
+ return false;
1527
+ const tasks = frame.params.tasks ?? "";
1528
+ return tasks !== "" && this.#naming.briefName(tasks) !== "";
1529
+ }
1232
1530
  /** The dispatch's artifact judgment — computed ONCE, then consumed by the gate and by
1233
1531
  * the prompt's round-context cell. Off the fix face there is nothing to read (no
1234
1532
  * requesting carrier, no sidecar), so the cell is the no-sidecar value; otherwise the
@@ -1576,11 +1874,15 @@ export class CliLifecycle {
1576
1874
  return `cdd review --type ${frame.type} --spec ${this.#docOf(frame)}`;
1577
1875
  case "fix": {
1578
1876
  // The `--reviews` input is the SAME carrier the fix prompt names (P31 §2.3): one
1579
- // four-layer resolution, never a second family spelling spliced here. The
1580
- // fallback fires only when the recorded face resolves to `null` (a legacy record
1581
- // with no carrier on disk) — the never-null guard keeps a command shape, and
1582
- // `#reviewFamilyPath` is the one home of the cycle-only rule (§2.10): a fix
1583
- // retried at attempt 2 would otherwise ask for a `-a2` name review never wrote.
1877
+ // four-layer resolution, never a second family spelling spliced here. The `??`
1878
+ // arm is a DEFENSIVE never-taken guard that keeps the command a string: the shape
1879
+ // it would cover — a recorded cycle whose carrier resolves to `null` (a legacy
1880
+ // record with no carrier on disk) — is refused by the dispatch-input gate as
1881
+ // `INPUT_REVIEWS · empty-value` before any command exists (P38 §2.3 reversal ②),
1882
+ // and the composed-but-absent sibling is refused there as `target-absent`. If
1883
+ // `#reviewsPath` ever answers `null` again, `#reviewFamilyPath` is the one home of
1884
+ // the cycle-only rule (§2.10): a fix retried at attempt 2 would otherwise ask for
1885
+ // a `-a2` name review never wrote.
1584
1886
  const findings = this.#reviewsPath(frame) ?? this.#reviewFamilyPath(frame);
1585
1887
  const target = frame.target.kind === "plan"
1586
1888
  ? `--plan ${frame.target.doc}`
@@ -78,10 +78,12 @@ 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
81
+ /** The read-only refusal block for a pre-dispatch gate — one of the three the real
82
+ * dispatch applies before the round exists REFUSED this dispatch (a `carrier-mismatch`
83
+ * on a tampered requesting carrier; a dispatch-input cell the frame requires but left
84
+ * empty or absent; a `misplaced` sidecar / unreadable one / a schema violation), so the
85
+ * preview prints the gate's OWN reason verbatim: one read, two faces, and a dry run can
86
+ * never forecast a dispatch the real run would refuse. Exit 1 at the caller; nothing is
85
87
  * written, moved or deleted (the repair is the orchestrator's). */
86
88
  artifactBlock(verb, reason) {
87
89
  const [head, ...sections] = reason.split("\n");
@@ -129,6 +129,15 @@ export const CAPSULE_WORDS = {
129
129
  * spec §3.3): the round still concludes, and this line names what was booked.
130
130
  * Fill slot: {message}. */
131
131
  softViolation: "round soft violation: {message}",
132
+ /** The `dispatch-input` refusal rows (P38 §2.2) — the station word, the one segment
133
+ * template (`{row} · {token} · {reason}`) and the segment separator. One line names
134
+ * every failing cell, so a refused round is repaired in one pass instead of one
135
+ * cell per dispatch. */
136
+ dispatchInput: {
137
+ station: "dispatch-input",
138
+ segment: "{row} · {token} · {reason}",
139
+ separator: "; ",
140
+ },
132
141
  /** The `misplaced = block` report (spec §2.4) — the reason word plus the four
133
142
  * sections: the rendered name, every name found in its place, the identity itself
134
143
  * and the repair the orchestrator owns. Fill slots: {kind} / {derived} /
@@ -354,6 +363,18 @@ export class Words {
354
363
  softViolation(message) {
355
364
  return CAPSULE_WORDS.softViolation.replace("{message}", message);
356
365
  }
366
+ /** The `dispatch-input` refusal (P38 §2.2) — the station word plus every failing
367
+ * cell's segment, `; ` between segments and ` · ` inside one. The `CDD_BLOCKED: `
368
+ * prefix is the block channel's, never this row's, so a dry-run consumer and a real
369
+ * dispatch read the same bytes. */
370
+ dispatchInput(facts) {
371
+ const row = CAPSULE_WORDS.dispatchInput;
372
+ const segments = facts.segments.map((segment) => row.segment
373
+ .replace("{row}", segment.row)
374
+ .replace("{token}", segment.token)
375
+ .replace("{reason}", segment.reason));
376
+ return [row.station, segments.join(row.separator)].join(CAPSULE_WORDS.separator);
377
+ }
357
378
  /** The `misplaced = block` report (spec §2.4) — the reason word over the four
358
379
  * fact sections. Every candidate is printed (never a first pick) and the identity
359
380
  * section is the SAME identity the rendered name came from, so `derived:` and