@oscaner-skills/cdd-engine 4.12.0 → 4.14.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,15 +19,17 @@ 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 { PinAudit } from "../contract/pins.js";
23
+ import { regradeNote } from "../contract/review-criteria.js";
22
24
  import { PlanTaskBlocksReader } from "../contract/task-blocks.js";
23
25
  import { CarrierSeal } from "../infra/carrier-seal.js";
24
26
  import { GitClient } from "../infra/git.js";
25
27
  import { ProcessFacts } from "../infra/proc.js";
26
28
  import { RoundLog } from "../infra/round-log.js";
27
29
  import { BriefRenderer } from "../render/brief.js";
28
- import { TemplateAssembler } from "../render/templates.js";
30
+ import { pinLensOf, TemplateAssembler } from "../render/templates.js";
31
+ import { ABSENT_READ, ArtifactReads } from "../session/artifact-reads.js";
29
32
  import { CarrierIntegrity, CarrierMismatchError } from "../session/carrier-integrity.js";
30
- import { CarrierRulings } from "../session/carrier-rulings.js";
31
33
  import { TargetFaceTable } from "../session/faces.js";
32
34
  import { HandoffSchema } from "../session/handoff-schema.js";
33
35
  import { InFlight } from "../session/inflight.js";
@@ -49,6 +51,9 @@ const STRUCTURE_CHANGED = "the plan's structure changed inside this round (the T
49
51
  * (`interrupted`, the vocabulary's new literal) and prose. One entry, one cause: the
50
52
  * fold records WHY the round has no conclusion, never a second diagnosis. */
51
53
  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");
54
+ /** The no-sidecar cell — off the fix face, an unattributable carrier, or a matrix
55
+ * `absent`: the slot stays empty and the gate has nothing to refuse. */
56
+ const NO_ARTIFACT = { kind: "read", value: ABSENT_READ };
52
57
  /**
53
58
  * CliLifecycle — the lifecycle's dispatch-seam production default (the split contract's
54
59
  * lifecycle face; face/cli.ts re-exports it as HarnessDispatch so the composition
@@ -99,6 +104,12 @@ export class CliLifecycle {
99
104
  /** Whether this invocation asked to take over a dead holder's record (the
100
105
  * `--recover` flag — the only takeover path). */
101
106
  #recover;
107
+ /** The artifact matrix this dispatch holds — the composition root's single instance,
108
+ * handed to the seal sweep so the carrier set is read out of ONE table, and read by
109
+ * the rulings face for the sidecar's name. Required: a dispatch that holds no table
110
+ * can not answer "is there a sidecar", and the old nullable field let that wiring bug
111
+ * read as a legal `absent` (the visibility rule's exact inversion). */
112
+ #artifacts;
102
113
  /** The HEAD the current dispatch started from (null off a repo / before a spawn) —
103
114
  * the postmortem baseline of `commitsSince` AND the in-flight record's
104
115
  * `dispatchBase` cell (the killed round's group baseline a takeover restores, §2.2). */
@@ -117,6 +128,9 @@ export class CliLifecycle {
117
128
  * when the channel opened — the record face must see a channel that never opened,
118
129
  * not only the stderr notice. */
119
130
  #logUnavailable = null;
131
+ /** The pin gate of this dispatch (P37 §7.2) — built on first use so the resolution
132
+ * index is walked once per process, never once per read. */
133
+ #pinIndex = null;
120
134
  constructor(opts) {
121
135
  this.#env = opts.env ?? process.env;
122
136
  this.#scene = opts.scene;
@@ -126,6 +140,7 @@ export class CliLifecycle {
126
140
  this.#git = opts.git ?? new GitClient();
127
141
  this.#proc = opts.proc ?? ProcessFacts;
128
142
  this.#recover = opts.recover ?? false;
143
+ this.#artifacts = opts.artifacts;
129
144
  this.#sync = opts.sync ?? new Terminator();
130
145
  this.#template = opts.template ?? new TemplateAssembler();
131
146
  this.#brief = opts.brief ?? new BriefRenderer();
@@ -202,7 +217,7 @@ export class CliLifecycle {
202
217
  dispatchBase: record.dispatchBase,
203
218
  verdict: { treeClean: true, targetAction: false },
204
219
  violations: [ABORT_INTERRUPTED],
205
- }, "wave");
220
+ });
206
221
  // P31 T5 §2.4 — the killed round's carrier names close with its abort record: the
207
222
  // draft the dead child may have left writable and the final it never materialized.
208
223
  // The identity is the record's OWN (op / cycle / attempt), never a re-derivation
@@ -303,10 +318,11 @@ export class CliLifecycle {
303
318
  * records, the persisted carrier, the round's baseline) plus the work plane's
304
319
  * evidence gate, and the graded entries decide the verdict: a round with no hard
305
320
  * 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.
321
+ * point: `records` is the key's in-register history read LITERALLY on that key (the
322
+ * row is the row — a retired spelling reads as absent, P36 §3), and `reviewsPath` is
323
+ * the fix route's `--reviews` carrier, the requester record's own carrier path, or
324
+ * the ledger's resolved review-carrier name — canonical, or the round's landed
325
+ * `final`, never a historical twin's spelling.
310
326
  *
311
327
  * A death face (a killed child, a non-zero exit, a rejected draft) already carries
312
328
  * its authored hard entry and needs no second judgment — the criterion table and
@@ -366,7 +382,7 @@ export class CliLifecycle {
366
382
  const judged = await CompletionCriteria.of(this.#opOf(frame)).judge({
367
383
  record: this.#judgedRecordOf(frame, outcome),
368
384
  row: this.#rowOf(frame),
369
- records: scene.ledger.recordsOf(frame.key, frame.type),
385
+ records: scene.ledger.recordsOf(frame.key),
370
386
  carrier: outcome.carrier ?? null,
371
387
  reviewsPath: this.#reviewsPath(frame),
372
388
  git: this.#git,
@@ -422,8 +438,7 @@ export class CliLifecycle {
422
438
  #rowOf(frame) {
423
439
  const ledger = this.#scene.ledger;
424
440
  const data = ledger.readProgress();
425
- return ((data === null ? undefined : Ledger.rowFor(data, frame.key, frame.type)) ??
426
- ledger.entryFor(frame.key));
441
+ return ((data === null ? undefined : Ledger.rowFor(data, frame.key)) ?? ledger.entryFor(frame.key));
427
442
  }
428
443
  /** The evidence gate as a graded entry (design spec §3.3) — the work plane's wave /
429
444
  * branch rounds write the evidence file at the round identity's own name
@@ -539,14 +554,18 @@ export class CliLifecycle {
539
554
  }
540
555
  // P31 T2 — the ruling sidecar gate: a sidecar the strict schema refuses stops the
541
556
  // round HERE, before the in-flight record is acquired and before any child exists
542
- // (a written-but-invisible ruling is the defect this gate removes).
543
- const rulingsRefusal = this.#rulingsRefusal(frame);
544
- if (rulingsRefusal !== null) {
557
+ // (a written-but-invisible ruling is the defect this gate removes). The judgment is
558
+ // ONE value computed here and handed to BOTH consumers (the gate and the prompt's
559
+ // round-context cell), so the `misplaced` / `invalid` / `ok` answers can never
560
+ // disagree between them — not even across a writer that lands mid-dispatch.
561
+ const artifactCell = this.#artifactCellOf(frame);
562
+ const artifactRefusal = this.#artifactRefusalOf(artifactCell);
563
+ if (artifactRefusal !== null) {
545
564
  this.#sealRoundCarriers(frame);
546
- this.#blocked(rulingsRefusal, false);
547
- return { status: "BLOCKED", violations: [RoundViolation.hard(rulingsRefusal)] };
565
+ this.#blocked(artifactRefusal, false);
566
+ return { status: "BLOCKED", violations: [RoundViolation.hard(artifactRefusal)] };
548
567
  }
549
- const prompt = this.#template.render(this.#valuesOf(frame));
568
+ const prompt = this.#template.render(this.#valuesOf(frame, artifactCell));
550
569
  const row = HOSTS[host];
551
570
  const cliName = row.cli;
552
571
  const args = [...row.invoke.split(" ").filter((part) => part.length > 0)];
@@ -783,7 +802,7 @@ export class CliLifecycle {
783
802
  * (empty-valued keys are dropped), so each mode's round context carries only the
784
803
  * facts the mode reads. The review criteria/lens are NOT values — they fold into
785
804
  * the review type's fixed prefix (§3.7). */
786
- #valuesOf(frame) {
805
+ #valuesOf(frame, artifactCell) {
787
806
  const scene = this.#scene;
788
807
  const op = this.#opOf(frame);
789
808
  const role = this.#roleOf(frame);
@@ -808,41 +827,49 @@ export class CliLifecycle {
808
827
  // would be a short-circuit).
809
828
  INPUT_REVIEWS: op === "fix" ? this.#rel(this.#reviewsPath(frame) ?? "") : "",
810
829
  // P31 T2 — the ruling sidecar rides the fix input side alone (the review round's
811
- // own context has no sidecar yet). The path derives from the requesting carrier
812
- // by the ONE `.json` → `.rulings.json` rule; an absent sidecar leaves the slot
813
- // empty, so the assembler drops the line entirely.
814
- INPUT_RULINGS: this.#rulingsInputOf(frame),
830
+ // own context has no sidecar yet). The path is the matrix's `rulings` row rendered
831
+ // from the REVIEWED carrier's identity and the strict schema read composed beside
832
+ // it (`#artifactReadOf`), handed in as the dispatch's ONE judgment: the gate that
833
+ // just approved this dispatch and this slot are the same value, never two reads.
834
+ // An absent, unattributable or refused sidecar leaves the slot empty and the
835
+ // assembler drops the line.
836
+ INPUT_RULINGS: this.#rulingsInputOf(artifactCell),
815
837
  // The kind-named judged-doc anchors (the semantic retirement of the generic
816
838
  // INPUT_DOC): the plan line carries the plan document as its judged doc
817
839
  // (INPUT_PLAN) AND its design-spec reference (INPUT_SPEC — the `spec:`
818
840
  // front-matter link target, the plan→spec conformance anchor); the branch line
819
841
  // carries the plan document (its plan-conformance reference) plus the same
820
842
  // design-spec reference, while the live tree against BASE_BRANCH is the judged
821
- // object; the spec-shaped doc targets (phase-spec · single-spec) carry their
822
- // spec document (INPUT_SPEC, the judged doc); the overall line's ONE charter
823
- // anchor is INPUT_OVERALL, so its INPUT_SPEC stays empty (C2 — the charter is
824
- // never its own spec). Empty off the off-faces (the slots are dropped by the
825
- // assembler).
843
+ // object; the wave line carries the same-slug identity document and its
844
+ // `program:` charter (P37 §4.1) so a code review reads the phase contract it is
845
+ // judged against; the spec-shaped doc targets (phase-spec · single-spec) carry
846
+ // their spec document (INPUT_SPEC, the judged doc); the overall line's ONE
847
+ // charter anchor is INPUT_OVERALL, so its INPUT_SPEC stays empty (C2 — the
848
+ // charter is never its own spec). Empty off the off-faces (the slots are dropped
849
+ // by the assembler).
826
850
  INPUT_PLAN: frame.type === "plan"
827
851
  ? this.#rel(docPath ?? "")
828
852
  : frame.type === "branch"
829
853
  ? this.#rel(scene.planPath ?? "")
830
854
  : "",
831
- INPUT_SPEC: frame.type === "plan" || frame.type === "branch"
855
+ INPUT_SPEC: frame.type === "plan" || frame.type === "branch" || frame.type === "wave"
832
856
  ? this.#rel(scene.specLink ?? "")
833
- : frame.type === "wave" || frame.type === "overall"
857
+ : frame.type === "overall"
834
858
  ? ""
835
859
  : // the spec-shaped doc targets (phase-spec · single-spec) carry the judged
836
860
  // document; the overall line's charter anchor is INPUT_OVERALL below.
837
861
  this.#rel(docPath ?? ""),
838
862
  // The parent charter of the spec the face reads (INPUT_OVERALL) — the overall
839
863
  // line's ONE charter anchor (the judged charter itself); the phase-spec line
840
- // carries its own `program:`; plan/branch carry the same-slug identity doc's
841
- // `program:`; empty off those faces and when the named program is absent (the
842
- // assembler drops the empty slot).
864
+ // carries its own `program:`; plan / branch / wave carry the same-slug identity
865
+ // doc's `program:` (the wave arm landed at P37 §4.1); empty off those faces and
866
+ // when the named program is absent (the assembler drops the empty slot).
843
867
  INPUT_OVERALL: frame.type === "overall"
844
868
  ? this.#rel(docPath ?? "")
845
- : frame.type === "phase-spec" || frame.type === "plan" || frame.type === "branch"
869
+ : frame.type === "phase-spec" ||
870
+ frame.type === "plan" ||
871
+ frame.type === "branch" ||
872
+ frame.type === "wave"
846
873
  ? this.#rel(scene.overallLink ?? "")
847
874
  : "",
848
875
  // The branch/wave tree-review scope anchor (BASE_BRANCH) — engine-injected
@@ -909,7 +936,7 @@ export class CliLifecycle {
909
936
  * draft of a retried round) is already closed when it is reopened here: the window
910
937
  * is the two names, never a third file. */
911
938
  #openRoundCarriers(frame) {
912
- CarrierSeal.sweep(this.#scene.workspace.path, []);
939
+ CarrierSeal.sweep(this.#scene.workspace.path, [], this.#artifacts);
913
940
  for (const name of this.#roundCarrierNames(frame))
914
941
  CarrierSeal.unseal(name);
915
942
  }
@@ -1054,6 +1081,13 @@ export class CliLifecycle {
1054
1081
  if (readBack.problems.length > 0) {
1055
1082
  return this.#reject(frame, path, `the handoff draft at ${path} violates the ${plane} schema: ${readBack.problems.join("; ")}`);
1056
1083
  }
1084
+ // P37 §7.2 — the pin read-back corpora ② and ③ are judged HERE, before the local
1085
+ // findings projection and before `conclusionOf`, so that ONE `rollup` reads them,
1086
+ // `DraftedOutcome.findings` projects them and `#materialize` persists them. The
1087
+ // judgment lives here and the write there: a warn injected at the writer would
1088
+ // reach the carrier while the round still concluded `APPROVED`.
1089
+ if (plane === "judge")
1090
+ this.#injectPinFindings(frame, draft);
1057
1091
  // T2 — the plane-aware read: the judge plane ALONE reads `draft.findings` (its
1058
1092
  // own declared required field — rolled up to the conclusion); the work plane
1059
1093
  // derives its status from the draft's declared status, never the findings slot
@@ -1061,6 +1095,16 @@ export class CliLifecycle {
1061
1095
  // The conclusion rides the ONE source (`HandoffSchema.conclusionOf`) the ledger
1062
1096
  // legs read too — the reconstruct never rules a work status by a second path.
1063
1097
  const findings = plane === "judge" ? (Array.isArray(draft.findings) ? draft.findings : []) : [];
1098
+ // P37 §2.2 — the blocker evidence gate: a blocker that cannot state its scenario is
1099
+ // refused on THIS read-back path (the same one `CDD_BLOCKED` line every schema
1100
+ // refusal rides — no second reporter, no `--dry-run` claim). The round produces no
1101
+ // conclusion instead of a BLOCKED one.
1102
+ // Rule zero (class-size limit): this file is well past the limit and predates it —
1103
+ // splitting it is P39's work (design spec D95 ②), not this round's.
1104
+ const grading = schema.gradingViolations(findings);
1105
+ if (grading.length > 0) {
1106
+ return this.#reject(frame, path, this.#gradingRefusal(grading));
1107
+ }
1064
1108
  // A validated draft's conclusion is total: the judge plane rolls up its own
1065
1109
  // required findings, and the work plane's `status` passed the `required` gate above
1066
1110
  // — so the `?? "BLOCKED"` never fires here (a work draft without a status never
@@ -1074,6 +1118,11 @@ export class CliLifecycle {
1074
1118
  let summary;
1075
1119
  try {
1076
1120
  summary = this.#dispositionsSummary(frame, plane, materialized.carrier);
1121
+ // P37 §5.2 — the downgrade note rides the SAME capsule `summary` slot: the
1122
+ // `emit` signature and key set do not move, and a round with no downgrade leaves
1123
+ // the slot undefined, so the stdout of an ordinary review round is byte-identical
1124
+ // to before this phase.
1125
+ summary ??= this.#downgradeNote(frame, plane, materialized.carrier);
1077
1126
  }
1078
1127
  catch (raw) {
1079
1128
  if (!(raw instanceof CarrierMismatchError))
@@ -1091,6 +1140,98 @@ export class CliLifecycle {
1091
1140
  violations: materialized.violations,
1092
1141
  };
1093
1142
  }
1143
+ /** P37 §7.2 — the two read-back corpora of the pin gate, injected as REAL warn-level
1144
+ * findings into `draft.findings`. The row's LENS is the judged face's own declared
1145
+ * `pinLens` (`render/templates.ts#pinLensOf`), never a literal here: the child's
1146
+ * prompt declares a lens menu per face, and an engine row outside that menu would
1147
+ * be unreadable as "the engine wrote it" to every later reader. They are not a
1148
+ * refusal: no `CDD_BLOCKED` is printed, and the round keeps its conclusions — a warn
1149
+ * reaches `rollup`, so a review round with a dead pin concludes `REVIEW_FIX` instead
1150
+ * of `APPROVED`. Nothing here is a second reporting surface: the rows enter the same
1151
+ * `findings[]`, are projected by the same `findingsOf`, and are keyed by the same
1152
+ * `#findingsList` at materialize. */
1153
+ #injectPinFindings(frame, draft) {
1154
+ const lens = pinLensOf(frame.type);
1155
+ const injected = [
1156
+ ...this.#documentPinRows(frame, lens),
1157
+ ...this.#contractPinRows(draft, lens, _a.#judgedDocOf(frame)),
1158
+ ];
1159
+ if (injected.length === 0)
1160
+ return;
1161
+ const rows = Array.isArray(draft.findings) ? draft.findings : [];
1162
+ draft.findings = [...rows, ...injected];
1163
+ }
1164
+ /** The document this round judges (§7.3 condition ①'s subject) — a repo-relative
1165
+ * path for the two doc-target kinds, `null` for a wave / branch round: those audit
1166
+ * no document body, so a `Create:` declaration has no identity key to match and its
1167
+ * pending path stays a finding (design spec §7.2's `standards` arm). */
1168
+ static #judgedDocOf(frame) {
1169
+ const target = frame.target;
1170
+ return target.kind === "spec" || target.kind === "plan" ? target.doc : null;
1171
+ }
1172
+ /** Corpus ② — the JUDGED document's own body (the three doc targets only; a wave /
1173
+ * branch / plan round judges no document body). The path comes from `frame.target`
1174
+ * (`{ kind: "spec", doc }`, resolved at the CLI seam), and the body is read through
1175
+ * this class's own repo read: `#reconstruct` builds no second `SlugIndex` and adds no
1176
+ * field to `DispatchScene`. */
1177
+ #documentPinRows(frame, lens) {
1178
+ if (frame.target.kind !== "spec")
1179
+ return [];
1180
+ const doc = frame.target.doc;
1181
+ let body;
1182
+ try {
1183
+ body = readFileSync(path.resolve(this.#repoRootValue().absolute, doc), "utf8");
1184
+ }
1185
+ catch {
1186
+ return [];
1187
+ }
1188
+ return this.#pinAudit()
1189
+ .scanText(body, this.#rel(doc))
1190
+ .map((finding) => _a.#pinRow(finding.summary, lens));
1191
+ }
1192
+ /** Corpus ③ — each finding's `contract.path` (design spec §2.3). `PinAudit`'s
1193
+ * markdown scan never carries this cell: the anchor is a declared coordinate, judged
1194
+ * on its own. A missing path appends one warn per offending finding. The judged
1195
+ * document rides in as the time face's subject (§7.3): a `Create:` declaration of
1196
+ * the judged document's own plan is pending, not dead. */
1197
+ #contractPinRows(draft, lens, judged) {
1198
+ const rows = Array.isArray(draft.findings) ? draft.findings : [];
1199
+ const audit = this.#pinAudit();
1200
+ const rel = judged === null ? null : this.#rel(judged);
1201
+ const out = [];
1202
+ for (const row of rows) {
1203
+ const pin = row?.contract?.path;
1204
+ if (typeof pin !== "string" || pin.trim().length === 0)
1205
+ continue;
1206
+ if (audit.pathResolves(pin.trim(), rel))
1207
+ continue;
1208
+ out.push(_a.#pinRow(`the pin \`${pin.trim()}\` resolves nowhere — the finding's \`contract.path\` anchor names no path in the tree`, lens));
1209
+ }
1210
+ return out;
1211
+ }
1212
+ /** One injected pin finding — a warn under the judged face's own declared pin lens,
1213
+ * the tier §7.2 pins and the lens its menu can carry. */
1214
+ static #pinRow(summary, lens) {
1215
+ return { severity: "warn", lens, summary };
1216
+ }
1217
+ /** The one audit instance of this dispatch — the resolution index is built once and
1218
+ * shared by both corpora (and by every round this instance drives). */
1219
+ #pinAudit() {
1220
+ this.#pinIndex ??= new PinAudit(this.#repoRootValue().absolute);
1221
+ return this.#pinIndex;
1222
+ }
1223
+ /** The blocker-evidence refusal (design spec §2.2): the first word after
1224
+ * `CDD_BLOCKED:` is the criteria row's `id` — written as a LITERAL here, because the
1225
+ * gate's pin is the printed byte, not an import of the registry — followed by every
1226
+ * offending finding's `id` and `summary` (all of them, never one of two). */
1227
+ #gradingRefusal(violations) {
1228
+ const labels = violations.map((violation) => {
1229
+ const summary = violation.summary?.trim() ?? "";
1230
+ const quoted = summary.length === 0 ? "" : ` "${summary}"`;
1231
+ return `${violation.id ?? "unkeyed"}${quoted}`;
1232
+ });
1233
+ return `grading-impact-missing: finding(s) graded blocker carry no \`impact.scenario\` — ${labels.join("; ")}`;
1234
+ }
1094
1235
  /** The fix round's ONE summary line (design spec §3.4) — computed from the PERSISTED
1095
1236
  * carrier's dispositions and the REQUESTING carrier's input set (the same pair the
1096
1237
  * fix criterion judges), never stored: no record field, no carrier key, no capsule
@@ -1101,12 +1242,60 @@ export class CliLifecycle {
1101
1242
  #dispositionsSummary(frame, plane, carrier) {
1102
1243
  if (plane !== "work" || this.#opOf(frame) !== "fix")
1103
1244
  return undefined;
1104
- const requester = FixDispositions.requesterInputOf(this.#scene.ledger.recordsOf(frame.key, frame.type), frame.round, this.#reviewsPath(frame), this.#repoRootValue().absolute);
1245
+ const requester = FixDispositions.requesterInputOf(this.#scene.ledger.recordsOf(frame.key), frame.round, this.#reviewsPath(frame), this.#repoRootValue().absolute);
1105
1246
  if (requester.kind !== "read")
1106
1247
  return undefined;
1107
1248
  const counts = new FixDispositions().summaryOf(carrier, requester.findings);
1108
1249
  return FIX_DISPOSITIONS_SUMMARY.replace("{fixed}", String(counts.fixed)).replace("{rejected}", String(counts.rejected));
1109
1250
  }
1251
+ /** P37 §5.1 · §5.2 — the capsule's downgrade note. The current round's findings are
1252
+ * judged against the NEAREST EARLIER review record on this line whose findings
1253
+ * projection is non-empty (a clean implement / fix record between the two never
1254
+ * resets the reference); a lowered grade against a non-empty earlier scenario prints
1255
+ * the stated `regrade` reason, and one that states none prints the mark. Display
1256
+ * only: the note is the capsule's `summary` line, never a finding row, never a carrier
1257
+ * entry, and it never moves the round's conclusion. */
1258
+ #downgradeNote(frame, plane, carrier) {
1259
+ if (plane !== "judge")
1260
+ return undefined;
1261
+ const current = this.#handoffSchema.findingsOf(carrier.findings);
1262
+ if (current.length === 0)
1263
+ return undefined;
1264
+ const prior = this.#priorFindings(frame);
1265
+ return regradeNote(HandoffSchema.downgrades(prior, current).length, HandoffSchema.regradeReasons(prior, current));
1266
+ }
1267
+ /** The "previous round" of §5.1 — the nearest earlier REVIEW record on this line
1268
+ * whose findings projection is non-empty. `id` is never the match key (it is the
1269
+ * engine-written row number), so the reference is a whole findings set, not a row
1270
+ * picked by position. The read is the ledger's ONE checked carrier read. */
1271
+ #priorFindings(frame) {
1272
+ const current = { cycle: frame.round, attempt: frame.attempt ?? 1 };
1273
+ const earlier = this.#scene.ledger
1274
+ .recordsOf(frame.key)
1275
+ .filter((record) => record.op === "review")
1276
+ .filter((record) => _a.#before(record, current))
1277
+ .sort((left, right) => left.cycle === right.cycle ? right.attempt - left.attempt : right.cycle - left.cycle);
1278
+ for (const record of earlier) {
1279
+ const previous = this.#scene.ledger.readHandoff("review", frame.type, {
1280
+ tasks: frame.params.tasks,
1281
+ round: record.cycle,
1282
+ attempt: record.attempt,
1283
+ });
1284
+ if (previous === null)
1285
+ continue;
1286
+ const findings = this.#handoffSchema.findingsOf(previous.findings);
1287
+ if (findings.length > 0)
1288
+ return findings;
1289
+ }
1290
+ return [];
1291
+ }
1292
+ /** Whether `record` precedes the current round — the `(cycle, attempt)` order the
1293
+ * round identity itself uses. */
1294
+ static #before(record, current) {
1295
+ return record.cycle === current.cycle
1296
+ ? record.attempt < current.attempt
1297
+ : record.cycle < current.cycle;
1298
+ }
1110
1299
  /** The requesting review carrier's path — the fix round's `--reviews` input, or the
1111
1300
  * same-cycle review record's carrier identity through the ledger's ONE accessor
1112
1301
  * (the recorded path, then the read ladder a pre-P31 row needs), or the ledger's
@@ -1142,7 +1331,7 @@ export class CliLifecycle {
1142
1331
  * requesting carrier's path and its digest. */
1143
1332
  #requesterRecord(frame) {
1144
1333
  const reviewed = this.#scene.ledger
1145
- .recordsOf(frame.key, frame.type)
1334
+ .recordsOf(frame.key)
1146
1335
  .filter((record) => record.op === "review" && record.cycle === frame.round);
1147
1336
  return reviewed.reduce((newest, record) => (newest === null || record.attempt >= newest.attempt ? record : newest), null);
1148
1337
  }
@@ -1152,7 +1341,13 @@ export class CliLifecycle {
1152
1341
  * already existed before this dispatch (`INPUT_REVIEWS` is its own input), so every
1153
1342
  * other phase has no gate to set. A carrier with no recorded digest — a legacy round,
1154
1343
  * or a resolved path no record declared — is read as present facts: no comparison,
1155
- * no refusal. */
1344
+ * no refusal.
1345
+ *
1346
+ * The repo-relative carrier → absolute erasure is spelled here, and again inside the
1347
+ * sidecar seam (`session/artifact-reads.ts`), BY DESIGN: this one feeds the digest
1348
+ * read of the carrier's own bytes, that one feeds the schema's `carrier` comparison
1349
+ * and the sidecar's id set. The two are different reads of different files, not two
1350
+ * names for one fact. */
1156
1351
  #carrierRefusal(frame) {
1157
1352
  if (this.#opOf(frame) !== "fix")
1158
1353
  return null;
@@ -1179,92 +1374,86 @@ export class CliLifecycle {
1179
1374
  return this.#requesterRecord(frame)?.carrierDigest ?? null;
1180
1375
  }
1181
1376
  /** The fix round's ruling sidecar as the round-context value — the repo-relative
1182
- * sidecar path when a conforming sidecar sits beside the requesting carrier, plus the
1183
- * ruling bodies it carries, the empty string otherwise (off the fix face, with no
1184
- * resolved carrier, and when the sidecar is absent — the assembler drops the empty
1185
- * line). The strict judgment is the dispatch gate's `#rulingsRefusal`; this cell
1186
- * names the file the round may read AND states the verdicts (§2.5 AC: the rendered
1187
- * text matches the sidecar), so a ruling is never merely a path the child must
1188
- * re-open to discover. */
1189
- #rulingsInputOf(frame) {
1190
- if (this.#opOf(frame) !== "fix")
1191
- return "";
1192
- const carrier = this.#reviewsPath(frame);
1193
- if (carrier === null)
1194
- return "";
1195
- const verdict = this.#rulingsVerdict(frame, carrier);
1196
- if (verdict.kind !== "ok")
1197
- return "";
1198
- const sidecar = this.#rel(CarrierRulings.pathFor(carrier));
1199
- return [sidecar, ...verdict.rulings.map((ruling) => this.#rulingLine(ruling))].join("\n");
1200
- }
1201
- /** One rendering of a recorded ruling — the finding id it answers and the ruling's
1202
- * own text VERBATIM (never re-worded: the sidecar is the orchestrator's words, and
1203
- * the round context quotes them). Indented under the sidecar path's bullet so the
1204
- * cell reads as one input. */
1205
- #rulingLine(ruling) {
1206
- return ` - \`${ruling.finding}\` — ${ruling.ruling}`;
1207
- }
1208
- /** The pre-dispatch ruling gate — the strict sidecar verdict's refusal reason, or null
1209
- * when the round may proceed (no fix face, no resolved carrier, an absent sidecar, or
1210
- * a conforming one). A refusal is HARD and lands before the in-flight record and the
1211
- * child, so a broken ruling set can never be dispatched unnoticed (§2.6).
1377
+ * sidecar path alone, the empty string otherwise (off the fix face and when the
1378
+ * sidecar is absent — the assembler drops the empty line).
1212
1379
  *
1213
- * A `carrier-mismatch` from the sidecar's id read is the integrity refusal, never a
1214
- * ruling reason: a tampered carrier is not judged (its id set is not a fact this
1215
- * round may read), so the diagnostic names the bytes that changed. */
1216
- #rulingsRefusal(frame) {
1380
+ * One input, one reading: the round context names WHERE the rulings live, exactly as
1381
+ * `INPUT_REVIEWS` names the carrier it qualifies (spec §2.10). The ruling bodies stay
1382
+ * in the sidecar — the child opens the file — so the prompt tail carries no text whose
1383
+ * length the orchestrator's ruling set decides, and the sidecar keeps its single
1384
+ * source. The path is the artifact matrix's `rulings` render of the REVIEWED round's
1385
+ * identity, never a tail replacement on the carrier's name: the carrier's own spelling
1386
+ * (draft or final) can no longer move it.
1387
+ *
1388
+ * The judgment is the dispatch's OWN cell — the value the gate just read — so the cell
1389
+ * can never name a ruling set the refusal is about to reject. */
1390
+ #rulingsInputOf(cell) {
1391
+ if (cell.kind !== "read")
1392
+ return "";
1393
+ const { read } = cell.value;
1394
+ return read.kind === "ok" ? this.#rel(read.path) : "";
1395
+ }
1396
+ /** The artifact-identity gate as a PURE read — the `--dry-run` face's entry to the
1397
+ * same judgment the real dispatch applies before it takes the in-flight record and
1398
+ * before any child exists. The preview renders the returned reason verbatim, so a
1399
+ * dry run can never forecast a dispatch the real run would refuse (one read, two
1400
+ * faces). Nothing here writes: the read is the matrix's plus the strict schema's. */
1401
+ artifactRefusal(frame) {
1402
+ return this.#artifactRefusalOf(this.#artifactCellOf(frame));
1403
+ }
1404
+ /** The dispatch's artifact judgment — computed ONCE, then consumed by the gate and by
1405
+ * the prompt's round-context cell. Off the fix face there is nothing to read (no
1406
+ * requesting carrier, no sidecar), so the cell is the no-sidecar value; otherwise the
1407
+ * one read is taken here, and a tampered requesting carrier becomes the integrity arm
1408
+ * instead of a read (its id set is not a fact this round may read). */
1409
+ #artifactCellOf(frame) {
1217
1410
  if (this.#opOf(frame) !== "fix")
1218
- return null;
1219
- const carrier = this.#reviewsPath(frame);
1220
- if (carrier === null)
1221
- return null;
1222
- let verdict;
1411
+ return NO_ARTIFACT;
1223
1412
  try {
1224
- verdict = this.#rulingsVerdict(frame, carrier);
1413
+ return { kind: "read", value: this.#artifactReadOf(frame, "rulings") };
1225
1414
  }
1226
1415
  catch (raw) {
1227
1416
  if (!(raw instanceof CarrierMismatchError))
1228
1417
  throw raw;
1229
- return raw.message;
1230
- }
1231
- return verdict.kind === "invalid" ? `rulings sidecar — ${verdict.reason}` : null;
1232
- }
1233
- /** The strict sidecar verdict over the requesting carrier's CHECKED id set — one call
1234
- * shape for the gate and the round-context cell, so neither can read the ids by a
1235
- * path the other does not take. */
1236
- #rulingsVerdict(frame, carrier) {
1237
- return CarrierRulings.verdict(carrier, this.#carrierFindingIds(frame, carrier));
1238
- }
1239
- /** The requesting carrier's engine-written finding ids (`F1`, `F2` …) — the id set a
1240
- * ruling must name. The read is the ONE checked carrier read (`CarrierIntegrity.read`,
1241
- * the digest its review round recorded): a tampered carrier is never observed at all —
1242
- * the mismatch throws and the integrity refusal wins over any ruling reason. An absent
1243
- * or unparseable carrier declares no ids, so any ruling beside it is refused by the
1244
- * strict schema instead of being accepted against an empty set. */
1245
- #carrierFindingIds(frame, carrier) {
1246
- const ids = new Set();
1247
- let carrierJson;
1248
- try {
1249
- const bytes = CarrierIntegrity.read(path.resolve(this.#repoRootValue().absolute, carrier), this.#requesterDigest(frame));
1250
- if (bytes === null)
1251
- return ids;
1252
- carrierJson = JSON.parse(bytes);
1253
- }
1254
- catch (raw) {
1255
- if (raw instanceof CarrierMismatchError)
1256
- throw raw;
1257
- return ids;
1418
+ return { kind: "mismatch", message: raw.message };
1258
1419
  }
1259
- const findings = carrierJson?.findings;
1260
- if (!Array.isArray(findings))
1261
- return ids;
1262
- for (const finding of findings) {
1263
- const id = finding?.id;
1264
- if (typeof id === "string")
1265
- ids.add(id);
1266
- }
1267
- return ids;
1420
+ }
1421
+ /** The ONE artifact read of this round's `kind` — delegated to the frame-free seam
1422
+ * (`session/artifact-reads.ts`), so this face keeps only the frame-level facts: the
1423
+ * requesting carrier and the digest its record remembered. The board reads the SAME
1424
+ * seam with its own workspace, so the prompt cell, the gate and the board can never
1425
+ * compose two different judgments (spec §2.3). */
1426
+ #artifactReadOf(frame, kind) {
1427
+ return new ArtifactReads(this.#artifacts, this.#scene.workspace).read(kind, this.#reviewsPath(frame) ?? "", this.#requesterDigest(frame));
1428
+ }
1429
+ /** The pre-dispatch artifact gate over the dispatch's ONE cell — the refusal reason of
1430
+ * this round's resolved `rulings` kind, or null when the round may proceed (no fix
1431
+ * face, no resolved carrier, an absent sidecar, or one conforming). A refusal is HARD
1432
+ * and lands before the in-flight record and the child, so a broken ruling set can
1433
+ * never be dispatched unnoticed (§2.4).
1434
+ *
1435
+ * Two refusal shapes, two words: a name that attributes to the identity but is NOT
1436
+ * its rendered name is `artifact-identity` (the four-section report — every candidate
1437
+ * listed, never a pick), while a present-but-unreadable file or a schema violation
1438
+ * keeps today's `rulings sidecar — <reason>` (the reason verbatim from the read).
1439
+ *
1440
+ * A `carrier-mismatch` from the sidecar's id read is the integrity refusal, never a
1441
+ * ruling reason: a tampered carrier is not judged (its id set is not a fact this
1442
+ * round may read), so the diagnostic names the bytes that changed. */
1443
+ #artifactRefusalOf(cell) {
1444
+ if (cell.kind === "mismatch")
1445
+ return cell.message;
1446
+ const read = cell.value.read;
1447
+ if (read.kind === "invalid")
1448
+ return `rulings sidecar — ${read.reason}`;
1449
+ if (read.kind !== "misplaced")
1450
+ return null;
1451
+ return this.#words.artifactIdentity({
1452
+ kind: "rulings",
1453
+ derived: this.#rel(this.#scene.workspace.resolve(read.derived)),
1454
+ found: read.found.map((name) => this.#rel(this.#scene.workspace.resolve(name))),
1455
+ identity: read.identity,
1456
+ });
1268
1457
  }
1269
1458
  /** The read-back rejection face — CDD_BLOCKED reason + the crash record (the
1270
1459
  * 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) {