@sabaiway/agent-workflow-kit 1.49.0 → 2.0.0

package/tools/manifest/validate.mjs

@@ -60,6 +60,31 @@ export const settingValueValid = (entry, value) => {
   }
 };
 
+// ── `modeCatalog` vocabulary (BRIDGE-MODES-CATALOG, D2/D4/D6) ────────────────────────
+// Every `modeCatalog` string the mode renderer prints is ONE capped line: the surface is a
+// terminal-width discovery list, and a control character would break the line (or a pasted form).
+export const CATALOG_LINE_MAX = 200;
+// The closed entry taxonomy (D4): a `primary` is a mode you drive; a `continuation` resumes one; an
+// `env-hook` MODIFIES named parents (an env var is never a fake role).
+export const CATALOG_KINDS = new Set(['primary', 'continuation', 'env-hook']);
+// `enforced` is claimable only for an OS-/code-enforced fact (a runtime bound rides in `condition`);
+// everything a prompt merely asks for is `advisory` (D6).
+export const CATALOG_ENFORCEMENT = new Set(['enforced', 'advisory']);
+// The AD-033 `contract` fields that carry invocation descriptors — the only referenceable ones.
+export const CATALOG_CONTRACT_FIELDS = new Set(['invocations', 'continue']);
+// The operand-slot grammar the RENDERER speaks: `<angle>` and `[bracket]` placeholders, with an
+// optional `@` riding WITH the slot (`@<facts-file>` is one operand a user types, not a bare
+// `<facts-file>` behind a stray character). Production owns it here; the bridge test suites keep
+// their own local copy ON PURPOSE — they ship as standalone bridge payload and must not import the
+// kit, so their regex is an INDEPENDENT drift oracle across the package boundary, not a duplicate.
+export const CATALOG_SLOT_RE = /@?<[^<>]+>|\[[^[\]]*\]/g;
+export const extractCatalogOperandSlots = (form) => (typeof form === 'string' ? form.match(CATALOG_SLOT_RE) ?? [] : []);
+
+const CATALOG_KEY_RE = /^[A-Za-z][A-Za-z0-9._-]*$/;
+const ENV_HOOK_KEY_RE = /^[A-Z][A-Z0-9_]*$/;
+// eslint-disable-next-line no-control-regex
+const CONTROL_CHAR_RE = /[\x00-\x1f\x7f]/;
+
 const hasTraversal = (p) => p.split(/[\\/]/).includes('..');
 const isUnresolved = (s) => /\{\{|\}\}|\$\{/.test(s);
 
@@ -124,6 +149,292 @@ export const readAuthoritativeVersion = (skillDir) => {
   return { version: null, from: 'no package.json or SKILL.md' };
 };
 
+// Validate a PRESENT `modeCatalog` block against `roles` (BRIDGE-MODES-CATALOG, D1/D2/D4/D6). It is
+// the USER-FACING mode catalog the `bridge-modes` renderer prints verbatim and composes invocation
+// forms from — RELATED TO, never shadowing, the AD-033 `contract` (the internal driving contract):
+// a contract-backed entry composes BY REFERENCE and never restates a descriptor; a contract-FREE
+// primary (a raw prompt mode) and an env-hook carry a literal one — the stated exception to
+// no-duplication, because for them the catalog IS canonical. Errors are appended, never thrown.
+const validateModeCatalog = (catalog, roles, errors) => {
+  const oneLine = (label, value) => {
+    if (typeof value !== 'string' || !value) {
+      errors.push(`${label} must be a non-empty string`);
+      return false;
+    }
+    if (CONTROL_CHAR_RE.test(value)) {
+      errors.push(`${label} must not carry control characters`);
+      return false;
+    }
+    if (value.length > CATALOG_LINE_MAX) {
+      errors.push(`${label} must be one line of at most ${CATALOG_LINE_MAX} characters`);
+      return false;
+    }
+    return true;
+  };
+  const stringList = (label, value) => {
+    if (!Array.isArray(value) || value.length === 0) {
+      errors.push(`${label} must be a non-empty array of one-line strings`);
+      return;
+    }
+    value.forEach((v, i) => oneLine(`${label}[${i}]`, v));
+  };
+
+  // The key index is built FIRST: `parents[]` and `customHooks[]` resolve ACROSS entries, so a
+  // forward reference resolves exactly like a backward one (declaration order is not a contract).
+  const byKey = new Map();
+  for (const entry of catalog) {
+    if (entry == null || typeof entry !== 'object' || Array.isArray(entry)) continue;
+    if (typeof entry.key === 'string' && entry.key && !byKey.has(entry.key)) byKey.set(entry.key, entry);
+  }
+
+  const seenKeys = new Set();
+  const claimedRefs = new Set(); // "<role>.<field>[<index>]" — one contract invocation, at most one entry
+  catalog.forEach((entry, i) => {
+    const at = `\`modeCatalog[${i}]\``;
+    if (entry == null || typeof entry !== 'object' || Array.isArray(entry)) {
+      errors.push(`${at} must be an object`);
+      return;
+    }
+    const isEnvHook = entry.kind === 'env-hook';
+
+    if (typeof entry.key !== 'string' || !CATALOG_KEY_RE.test(entry.key)) {
+      errors.push(`${at}.key must be a bare token (a letter, then letters/digits/._-)`);
+    } else if (!oneLine(`${at}.key`, entry.key)) {
+      // The key IS the mode's printed identity — it obeys the same one-line contract as any other
+      // rendered string (the token regex already bars control characters; this bars a giant key).
+    } else if (seenKeys.has(entry.key)) {
+      errors.push(`duplicate modeCatalog key "${entry.key}" (${at})`);
+    } else {
+      seenKeys.add(entry.key);
+      if (isEnvHook && !ENV_HOOK_KEY_RE.test(entry.key)) {
+        errors.push(`${at}.key must be an UPPER_SNAKE_CASE env-var name (an env-hook's key IS its env var)`);
+      }
+    }
+    if (!CATALOG_KINDS.has(entry.kind)) {
+      errors.push(`${at}.kind must be one of primary|continuation|env-hook`);
+      return; // every rule below is keyed on the kind
+    }
+
+    oneLine(`${at}.purpose`, entry.purpose);
+    stringList(`${at}.whenToUse`, entry.whenToUse);
+    if (Object.hasOwn(entry, 'whenNotTo')) stringList(`${at}.whenNotTo`, entry.whenNotTo);
+
+    let role = null;
+    if (isEnvHook) {
+      if (Object.hasOwn(entry, 'role')) errors.push(`${at}.role is not allowed on an env-hook (it names parents[], never a role)`);
+      if (!Array.isArray(entry.parents) || entry.parents.length === 0) {
+        errors.push(`${at}.parents is required for an env-hook (the catalog keys it modifies)`);
+      } else {
+        const seenParents = new Set();
+        for (const p of entry.parents) {
+          const target = typeof p === 'string' ? byKey.get(p) : undefined;
+          if (target === undefined) {
+            errors.push(`${at}.parents names ${JSON.stringify(p)} which is no modeCatalog key`);
+            continue;
+          }
+          if (p === entry.key) {
+            errors.push(`${at}.parents must not name the env-hook itself`);
+            continue;
+          }
+          if (seenParents.has(p)) {
+            errors.push(`duplicate parent ${JSON.stringify(p)} (${at})`);
+            continue;
+          }
+          seenParents.add(p);
+          if (target.kind === 'env-hook') {
+            errors.push(`${at}.parents names ${JSON.stringify(p)}, which is an env-hook — a hook modifies a mode, never another hook`);
+            continue;
+          }
+          // The linkage is SYMMETRIC. The forward rule below stops a customHook from lying about a
+          // hook that does not target it; this is the reverse: a hook that claims a mode must be
+          // declared BY that mode, or the mode's rendered detail silently omits a hook that really
+          // changes how it runs — an incomplete discovery surface is the failure this block exists
+          // to prevent.
+          if (!Array.isArray(target.customHooks) || !target.customHooks.includes(entry.key)) {
+            errors.push(`${at}.parents names ${JSON.stringify(p)}, which does not list ${JSON.stringify(entry.key)} in its customHooks[]`);
+          }
+        }
+      }
+    } else {
+      if (Object.hasOwn(entry, 'parents')) errors.push(`${at}.parents is only allowed on an env-hook`);
+      if (!Object.hasOwn(entry, 'role')) errors.push(`${at}.role is required for a ${entry.kind} entry`);
+      else if (typeof entry.role !== 'string' || !Object.hasOwn(roles, entry.role)) {
+        errors.push(`${at}.role ${JSON.stringify(entry.role)} is no role of this manifest`);
+      } else {
+        role = entry.role;
+      }
+    }
+
+    // `submode` is the EXPLICIT parser-arm binding (D4) — the drift test set-equals these against the
+    // wrapper's real mode arms, so the binding is never parsed back out of the key.
+    const roleModes = role != null && Array.isArray(roles[role]?.modes) ? roles[role].modes : null;
+    if (Object.hasOwn(entry, 'submode')) {
+      if (typeof entry.submode !== 'string' || !entry.submode) errors.push(`${at}.submode must be a non-empty string (it names a parser mode arm)`);
+      else if (entry.kind !== 'primary') errors.push(`${at}.submode is only allowed on a primary entry (only a primary binds a parser mode arm)`);
+      else if (roleModes == null || roleModes.length === 0) errors.push(`${at}.submode is only allowed when the entry's role declares modes[]`);
+      else if (!roleModes.includes(entry.submode)) errors.push(`${at}.submode ${JSON.stringify(entry.submode)} is no declared mode of role "${role}"`);
+    } else if (entry.kind === 'primary' && roleModes != null && roleModes.length > 0) {
+      errors.push(`${at}.submode is required (a primary whose role declares modes[] binds one)`);
+    }
+
+    const contract = role != null ? roles[role]?.contract : null;
+    const contractBacked = !isEnvHook && contract != null && typeof contract === 'object' && !Array.isArray(contract);
+    // The kind BINDS the contract field it may claim: a primary DRIVES a mode (`invocations`), a
+    // continuation RESUMES one (`continue`). Crossing them would render a resume form as a drive
+    // form (or the reverse) — a lie in exactly the surface the catalog exists to make honest.
+    const requiredField = entry.kind === 'primary' ? 'invocations' : 'continue';
+    // A continuation has nothing to be canonical ABOUT: D6's literal-descriptor exception covers a
+    // contract-free PRIMARY (a raw prompt mode) and an env-hook only. A role with no `continue`
+    // contract simply has no continuation to catalog.
+    if (entry.kind === 'continuation' && !contractBacked) {
+      errors.push(`${at}: a continuation must be contract-backed (the literal-descriptor exception covers contract-free primaries and env-hooks only)`);
+    }
+    // The invocation forms this entry really renders — the domain every operand slot must live in.
+    const forms = [];
+    if (contractBacked) {
+      if (Object.hasOwn(entry, 'descriptor')) errors.push(`${at}.descriptor is only allowed on a contract-free primary or an env-hook (a contract-backed entry composes BY REFERENCE)`);
+      if (!Array.isArray(entry.invocationRefs) || entry.invocationRefs.length === 0) {
+        errors.push(`${at}.invocationRefs is required (non-empty) for a contract-backed entry`);
+      } else {
+        entry.invocationRefs.forEach((ref, j) => {
+          const rat = `${at}.invocationRefs[${j}]`;
+          if (ref == null || typeof ref !== 'object' || Array.isArray(ref)) {
+            errors.push(`${rat} must be a {contractField, index} object`);
+            return;
+          }
+          if (!CATALOG_CONTRACT_FIELDS.has(ref.contractField)) {
+            errors.push(`${rat}.contractField must be one of invocations|continue`);
+            return;
+          }
+          if (ref.contractField !== requiredField) {
+            errors.push(`${rat}.contractField must be "${requiredField}" for a ${entry.kind} entry (a primary drives, a continuation resumes)`);
+            return;
+          }
+          if (!Number.isSafeInteger(ref.index) || ref.index < 0) {
+            errors.push(`${rat}.index must be a non-negative integer`);
+            return;
+          }
+          const declared = contract[ref.contractField];
+          const form = Array.isArray(declared) ? declared[ref.index] : undefined;
+          if (typeof form !== 'string' || !form) {
+            errors.push(`${rat} does not resolve (roles.${role}.contract.${ref.contractField}[${ref.index}])`);
+            return;
+          }
+          // A REFERENCED form is printed exactly like a literal descriptor, so it obeys the same
+          // one-line contract. The AD-033 `contract` block is otherwise validator-TOLERATED (its
+          // shape is drift-guarded by the bridge tests, not here) — this checks only the invocations
+          // a catalog entry causes to be PRINTED, and the label names the contract as their home.
+          if (!oneLine(`${rat} → roles.${role}.contract.${ref.contractField}[${ref.index}]`, form)) return;
+          const claim = `${role}.${ref.contractField}[${ref.index}]`;
+          if (claimedRefs.has(claim)) errors.push(`duplicate modeCatalog invocation reference ${claim} (${at})`);
+          else claimedRefs.add(claim);
+          forms.push(form);
+        });
+      }
+    } else {
+      if (Object.hasOwn(entry, 'invocationRefs')) errors.push(`${at}.invocationRefs is only allowed on a contract-backed entry`);
+      if (!Object.hasOwn(entry, 'descriptor')) errors.push(`${at}.descriptor is required (a contract-free entry is canonical for its own invocation form)`);
+      else if (oneLine(`${at}.descriptor`, entry.descriptor)) forms.push(entry.descriptor);
+    }
+
+    // Descriptor honesty (D2), BOTH ways. The render labels an unfilled form a TEMPLATE and names
+    // each required operand, so the declared slots and the placeholders the forms really carry must
+    // be the SAME set: an invented slot names an operand with nowhere to go, and an UNDECLARED
+    // placeholder is worse — the render shows a form as if it were ready to run while the reader has
+    // no idea what to put there or whether it is required. `required` is deliberately NOT inferred
+    // from the bracket shape (`<extra flags...>` is legitimately optional): the grammar fixes a
+    // slot's IDENTITY, the catalog fixes its semantics.
+    const renderedSlots = new Set(forms.flatMap((f) => extractCatalogOperandSlots(f)));
+    const hasOperands = Object.hasOwn(entry, 'operands');
+    if (forms.length > 0 && renderedSlots.size > 0 && !hasOperands) {
+      errors.push(`${at}.operands is required because its invocation forms contain rendered operand slots`);
+    }
+    if (hasOperands) {
+      if (!Array.isArray(entry.operands) || entry.operands.length === 0) {
+        errors.push(`${at}.operands must be an array of typed operand slots`);
+      } else {
+        const seenSlots = new Set();
+        entry.operands.forEach((op, j) => {
+          const oat = `${at}.operands[${j}]`;
+          if (op == null || typeof op !== 'object' || Array.isArray(op)) {
+            errors.push(`${oat} must be a {slot, required, description} object`);
+            return;
+          }
+          const slotOk = oneLine(`${oat}.slot`, op.slot);
+          if (typeof op.required !== 'boolean') errors.push(`${oat}.required must be a boolean`);
+          oneLine(`${oat}.description`, op.description);
+          if (!slotOk) return;
+          if (seenSlots.has(op.slot)) errors.push(`duplicate operand slot "${op.slot}" (${oat})`);
+          else seenSlots.add(op.slot);
+          // Checked only once the forms really resolved (else the error is noise).
+          if (forms.length > 0 && !renderedSlots.has(op.slot)) {
+            errors.push(`${oat}.slot "${op.slot}" is not a rendered placeholder in this entry's invocation forms`);
+          }
+        });
+        if (forms.length > 0) {
+          for (const slot of renderedSlots) {
+            if (!seenSlots.has(slot)) errors.push(`${at}.operands is missing rendered slot "${slot}"`);
+          }
+        }
+      }
+    }
+
+    if (Object.hasOwn(entry, 'guardrails')) {
+      if (!Array.isArray(entry.guardrails) || entry.guardrails.length === 0) {
+        errors.push(`${at}.guardrails must be an array of typed guardrail entries`);
+      } else {
+        entry.guardrails.forEach((g, j) => {
+          const gat = `${at}.guardrails[${j}]`;
+          if (g == null || typeof g !== 'object' || Array.isArray(g)) {
+            errors.push(`${gat} must be a {value, enforcement, condition?, source} object`);
+            return;
+          }
+          oneLine(`${gat}.value`, g.value);
+          if (!CATALOG_ENFORCEMENT.has(g.enforcement)) errors.push(`${gat}.enforcement must be one of enforced|advisory`);
+          if (Object.hasOwn(g, 'condition')) oneLine(`${gat}.condition`, g.condition);
+          oneLine(`${gat}.source`, g.source);
+        });
+      }
+    }
+
+    if (Object.hasOwn(entry, 'customHooks')) {
+      if (!Array.isArray(entry.customHooks) || entry.customHooks.length === 0) {
+        errors.push(`${at}.customHooks must be a non-empty array of modeCatalog keys`);
+      } else {
+        const seenHooks = new Set();
+        for (const hook of entry.customHooks) {
+          const target = typeof hook === 'string' ? byKey.get(hook) : undefined;
+          if (target === undefined) {
+            errors.push(`${at}.customHooks names ${JSON.stringify(hook)} which is no modeCatalog key`);
+            continue;
+          }
+          if (seenHooks.has(hook)) {
+            errors.push(`duplicate customHook "${hook}" (${at})`);
+            continue;
+          }
+          seenHooks.add(hook);
+          if (hook === entry.key) {
+            // The raw-mode carve-out (D4): a contract-free primary IS its own escape, so it names
+            // itself rather than repeating an escape it does not have.
+            if (contractBacked || entry.kind !== 'primary') {
+              errors.push(`${at}.customHooks may name this entry itself only on a contract-free primary (the raw mode)`);
+            }
+            continue;
+          }
+          if (target.kind !== 'env-hook') {
+            errors.push(`${at}.customHooks names ${JSON.stringify(hook)}, which is neither an env-hook nor this entry itself`);
+            continue;
+          }
+          // A customHook can never LIE about a hook that does not target this mode.
+          if (!Array.isArray(target.parents) || !target.parents.includes(entry.key)) {
+            errors.push(`${at}.customHooks names env-hook "${hook}", which does not list ${JSON.stringify(entry.key)} in its parents[]`);
+          }
+        }
+      }
+    }
+  });
+};
+
 export const validateManifest = (skillDir) => {
   const manifestPath = join(skillDir, 'capability.json');
   let raw;
@@ -377,6 +688,22 @@ export const validateManifest = (skillDir) => {
     }
   }
 
+  // `modeCatalog` (BRIDGE-MODES-CATALOG, D1): the user-facing mode catalog. ADDITIVE-OPTIONAL —
+  // an absent block is VALID (a bridge predating the catalog stays valid; the mode renders a stated
+  // "no catalog" line, never invalid-manifest and never an empty silent list). A PRESENT block is
+  // typed-validated like `settings`: the renderer prints its strings verbatim and composes runnable
+  // forms from its refs, so a malformed entry would render a lying discovery surface.
+  // Presence is keyed on the KEY, never on non-null: an explicit `modeCatalog: null` is a PRESENT
+  // malformed block, not an absence (absence is "this bridge predates the catalog"). An EMPTY array
+  // is likewise invalid — it would render as "this bridge has no modes", which is never true and is
+  // exactly the silent empty list D1 forbids; a bridge with nothing to say omits the block.
+  if (Object.hasOwn(manifest, 'modeCatalog')) {
+    const modeCatalog = manifest.modeCatalog;
+    if (!Array.isArray(modeCatalog)) errors.push('`modeCatalog` must be an array of mode entries');
+    else if (modeCatalog.length === 0) errors.push('`modeCatalog` must not be empty — a declared catalog states at least one mode (omit the block instead)');
+    else validateModeCatalog(modeCatalog, roles, errors);
+  }
+
   if (!isStub) {
     const auth = readAuthoritativeVersion(skillDir);
     if (auth.version == null) errors.push(`could not resolve an authoritative version (${auth.from})`);

package/tools/review-ledger-core.mjs

@@ -348,6 +348,80 @@ export const filterSegmentRecords = (records, { activity, loop, base }) =>
 // (no duplicate, gap, or out-of-order round). Checks the EXISTING sequence, not just the incoming
 // round: a ledger like [2] / [1,1] / [2,1] (reachable only by hand-editing the git-dir file — the
 // stated residual) must fail closed rather than be trusted to compute the "latest" round (codex R3).
+// ── the attesting-receipt predicate (BRIDGE-MODES-CATALOG, D3) ─────────────────────────
+// The ONE place that decides whether a review receipt may attest a tree. It lives in this neutral
+// core because all three consumers — review-state.mjs (the receipt gate), review-ledger.mjs (the
+// round cross-check) and review-ledger-write.mjs (the round writer) — need it, and the core imports
+// none of them: the same DAG reason this module exists at all. Two gates disagreeing about what
+// counts as an attestation is exactly the class AD-050 closed; a second copy would re-open it.
+export const REVIEW_RECEIPT_CLASS = Object.freeze({
+  NOT_CURRENT: 'not-current',
+  ATTESTING: 'attesting',
+  UNGROUNDED: 'ungrounded',
+  PROBE: 'probe',
+  UNMARKED: 'unmarked',
+  MALFORMED_MARKER: 'malformed-marker',
+});
+
+// Classify ONE receipt against a tree fingerprint. Order is load-bearing: identity first (is this
+// even about the current tree?), then the probe marker (may it attest at all?), then grounding.
+export const classifyReviewReceiptForTree = (receipt, fingerprint) => {
+  if (!isPlainObject(receipt) || receipt.fresh !== true || receipt.artifact !== 'code' || receipt.fingerprint !== fingerprint) {
+    return REVIEW_RECEIPT_CLASS.NOT_CURRENT;
+  }
+  if (!Object.hasOwn(receipt, 'probe')) return REVIEW_RECEIPT_CLASS.UNMARKED;
+  if (typeof receipt.probe !== 'boolean') return REVIEW_RECEIPT_CLASS.MALFORMED_MARKER;
+  if (receipt.probe === true) return REVIEW_RECEIPT_CLASS.PROBE;
+  if (receipt.grounded !== true) return REVIEW_RECEIPT_CLASS.UNGROUNDED;
+  return REVIEW_RECEIPT_CLASS.ATTESTING;
+};
+
+// Summarize one backend's receipts for a tree → { state, receipt, counts… }. `receipt` is the LATEST
+// ATTESTING one — never simply the last line: a probe (or a forged marker) written after a real
+// review must never become the authoritative verdict, which is precisely how a late probe SHIP could
+// override an earlier real REWORK and let both gates report convergence.
+export const summarizeReviewReceiptsForTree = (receipts, fingerprint) => {
+  const classified = receipts
+    .map((receipt) => ({ receipt, classification: classifyReviewReceiptForTree(receipt, fingerprint) }))
+    .filter(({ classification }) => classification !== REVIEW_RECEIPT_CLASS.NOT_CURRENT);
+  const rowsFor = (classification) => classified.filter((row) => row.classification === classification);
+  const attesting = rowsFor(REVIEW_RECEIPT_CLASS.ATTESTING);
+  const ungrounded = rowsFor(REVIEW_RECEIPT_CLASS.UNGROUNDED);
+  const probe = rowsFor(REVIEW_RECEIPT_CLASS.PROBE);
+  const unmarked = rowsFor(REVIEW_RECEIPT_CLASS.UNMARKED);
+  const malformedMarker = rowsFor(REVIEW_RECEIPT_CLASS.MALFORMED_MARKER);
+  const counts = {
+    currentCount: classified.length,
+    ungroundedCount: ungrounded.length,
+    probeExcluded: probe.length,
+    markerRejected: malformedMarker.length,
+    unmarkedRejected: unmarked.length,
+  };
+  if (attesting.length > 0) return { state: 'current', receipt: attesting[attesting.length - 1].receipt, ...counts };
+  if (ungrounded.length > 0) return { state: 'ungrounded', receipt: ungrounded[ungrounded.length - 1].receipt, ...counts };
+  if (classified.length > 0) {
+    return { state: malformedMarker.length > 0 || unmarked.length > 0 ? 'rejected' : 'probe', receipt: null, ...counts };
+  }
+  return { state: 'none', receipt: null, ...counts };
+};
+
+// Why this backend has no attestation — one stated sentence, never a silent "no receipt". The four
+// causes have DIFFERENT recoveries (run a real review / refresh the bridge / fix the receipt source /
+// re-run grounded), so they are never collapsed into one message.
+export const describeMissingReviewAttestation = (summary) => {
+  if (summary.state === 'current') return null;
+  const exclusions = [
+    summary.probeExcluded > 0 ? `${summary.probeExcluded} probe receipt(s)` : null,
+    summary.markerRejected > 0 ? `${summary.markerRejected} receipt(s) with a malformed probe marker` : null,
+    summary.unmarkedRejected > 0 ? `${summary.unmarkedRejected} receipt(s) with no probe marker` : null,
+  ].filter(Boolean);
+  const exclusionSuffix = exclusions.length > 0 ? `; excluded ${exclusions.join(', ')}` : '';
+  if (summary.state === 'ungrounded') return `only ungrounded normal receipts exist for the current tree${exclusionSuffix}`;
+  if (summary.state === 'probe') return 'only probe receipts exist for the current tree — a probe review never attests';
+  if (summary.state === 'rejected') return `current-tree receipts have untrustworthy probe markers${exclusionSuffix}`;
+  return 'no fresh code receipt exists for the current tree';
+};
+
 export const roundSequenceIntact = (records) => {
   const nums = records.filter((r) => r.kind === 'round').map((r) => r.round);
   return nums.every((n, i) => n === i + 1);

package/tools/review-ledger-write.mjs

@@ -18,8 +18,10 @@
 //                   round VANISHED unclassified (D6 — no-repro-no-fold; `refuted` is the honest
 //                   phantom lane); refuses while the changed source surface exceeds the diff cap
 //                   without a recorded segment size-cap override (D4). Integrity binding (Decision 7):
-//                   each NON-degraded backend needs a grounded code receipt for the current tree, so a
-//                   round cannot be recorded for a tree no bridge reviewed.
+//                   each NON-degraded backend needs an ATTESTING code receipt for the current tree
+//                   (the shared review-ledger-core predicate: grounded AND probe:false — a probe,
+//                   unmarked or malformed marker never attests), so a round cannot be recorded for a
+//                   tree no bridge really reviewed.
 //   recordTriage  — the classification that BREAKS the deadlock: each surviving blocking finding of a
 //                   SEGMENT round classified fixable-bug / inherent-layer-residual / escalate /
 //                   refuted (v4). No teeth (a triage is exactly what lets the next round proceed),
@@ -51,6 +53,9 @@ import {
   decideStop,
   validateRecord,
 } from './review-ledger.mjs';
+// The SHARED attesting-receipt predicate (D3) — read straight from the neutral core, the same one
+// review-state and the round cross-check use: one definition of "this receipt may attest a tree".
+import { summarizeReviewReceiptsForTree, describeMissingReviewAttestation } from './review-ledger-core.mjs';
 // The NEUTRAL shared changed-surface computation (BUGFREE-2 / D4): the D4 diff-cap and the
 // fold-completeness coverage gate consume ONE computation, so they can never drift. The writer
 // imports the NEUTRAL module, never the runner (the sole-tree-toucher boundary, codex R2 — an
@@ -253,17 +258,20 @@ export const recordRound = (params, deps = {}) => {
   const v = validateRecord(record);
   if (!v.ok) throw stop(`refusing to record a malformed round: ${v.reason}`);
 
-  // Integrity binding: each NON-degraded backend needs a grounded code receipt for this tree — a
-  // round cannot be recorded for a tree no bridge reviewed. A degraded backend minted no receipt.
+  // Integrity binding: each NON-degraded backend needs an ATTESTING receipt for this tree — a round
+  // cannot be recorded for a tree no bridge really reviewed. A degraded backend minted no receipt.
+  // The predicate is the SHARED one (review-ledger-core), the same review-state and the round
+  // cross-check read — a probe receipt never counted as a review, and the stated reason names WHICH
+  // exclusion applied, because the recoveries differ (run a real review / refresh the bridge / fix
+  // the receipt source / re-run grounded) and a silent "no receipt" would hide that.
   const receiptsPath = deps.receiptsPath ?? resolveReceiptsPath(cwd, env);
   const { receipts } = receiptsPath ? readReceipts(receiptsPath, deps.readFile) : { receipts: [] };
   for (const b of backends) {
     if (b.degraded) continue;
-    const own = receipts.filter(
-      (r) => r.backend === b.backend && r.fingerprint === fingerprint && r.artifact === 'code' && r.fresh === true && r.grounded === true,
-    );
-    if (own.length === 0) {
-      throw stop(`refusing to record a round for ${b.backend}: no grounded code receipt for the current tree — run its review wrapper (codex-review code / agy-review code --facts @f) first, or mark the backend degraded with a reason`);
+    const own = receipts.filter((r) => r.backend === b.backend);
+    const failure = describeMissingReviewAttestation(summarizeReviewReceiptsForTree(own, fingerprint));
+    if (failure !== null) {
+      throw stop(`refusing to record a round for ${b.backend}: no grounded code receipt for the current tree can attest this round — ${failure}; run its real review (codex-review code / agy-review code --facts @f), or mark the backend degraded with a reason`);
     }
   }
 
@@ -518,7 +526,8 @@ record   appends one review round. The JSON payload carries { loop, round, origi
          segment size-cap override (D4); while the segment lacks a quality-green gate-run at the
          current fingerprint (D5 — run the FULL matrix first: run-gates.mjs --record; a --only
          subset or a tree-changed run never satisfies; red PROCESS gates never block); or when a
-         non-degraded backend lacks a grounded code receipt for the current tree.
+         non-degraded backend lacks an ATTESTING code receipt for the current tree (grounded AND
+         probe:false — a probe, unmarked or malformed marker never attests).
 classify appends one triage record. The JSON payload carries { loop, round, classifications } (each
          { findingKey, class, accepted, testId, note }). A fixable-bug REQUIRES a testId — the
          red→green test that pins the fold, formatted "<test-file>#<test-name-pattern>" (write it

package/tools/review-ledger.mjs

@@ -19,8 +19,10 @@
 //           no reviewer ready); when no plan is in flight (the review-state naming convention);
 //           when the tree is clean (nothing to review); when the cwd is not a git work tree; and
 //           when the in-flight plan-execution SEGMENT is `converged` or `resolved-residual` (its
-//           latest round's non-degraded backends carry grounded code receipts for the recorded
-//           fingerprint, and a recorded 0/0 is ship-class-consistent with those receipts).
+//           latest round's non-degraded backends carry ATTESTING code receipts for the recorded
+//           fingerprint — the shared review-ledger-core predicate: grounded AND probe:false, a
+//           probe/unmarked/malformed marker never attests — and a recorded 0/0 is
+//           ship-class-consistent with those receipts).
 //   exit 1  for any DIRTY in-flight plan-execution segment that is neither `converged` nor
 //           `resolved-residual` — `triage-required`, `continue`, OR no round/receipt recorded in
 //           the CURRENT segment (a dirty active plan with an empty/stale/other-segment ledger is a
@@ -83,6 +85,8 @@ import {
   filterLoopRecords,
   filterSegmentRecords,
   roundSequenceIntact,
+  summarizeReviewReceiptsForTree,
+  describeMissingReviewAttestation,
 } from './review-ledger-core.mjs';
 export {
   LEDGER_BASENAME,
@@ -270,22 +274,27 @@ export const decideStop = (records, { cap = REVIEW_CAP, currentFingerprint = nul
 // ── receipt cross-check (integrity binding, Decision 7) ──────────────────────────────────────────
 
 // receiptCrossCheck(round, receipts, fingerprint) → { ok, reason }. For each NON-degraded backend of
-// `round`: a grounded code receipt must exist for (backend, fingerprint) — a round cannot pass for a
-// tree no bridge reviewed — AND a recorded ship-class 0/0 must not coexist with a non-ship receipt
+// `round`: an ATTESTING receipt must exist for (backend, fingerprint) — a round cannot pass for a
+// tree no bridge really reviewed — AND a recorded ship-class 0/0 must not coexist with a non-ship
 // verdict. A degraded backend minted no receipt (it ran no real review) and is exempt.
+// The attesting predicate is the SHARED one (review-ledger-core), the same review-state reads: this
+// gate used to filter raw fields and take `own[own.length - 1]`, so a probe receipt landing AFTER a
+// real one became the authoritative verdict — a late probe SHIP could bury a real REWORK and let
+// BOTH gates report convergence (D3). The summary's `receipt` is the latest ATTESTING one, never
+// simply the last line.
 export const receiptCrossCheck = (round, receipts, fingerprint) => {
   for (const b of round.backends) {
     if (b.degraded) continue;
-    const own = receipts.filter(
-      (r) => r.backend === b.backend && r.fingerprint === fingerprint && r.artifact === 'code' && r.fresh === true && r.grounded === true,
-    );
-    if (own.length === 0) {
-      return { ok: false, reason: `no grounded code receipt for ${b.backend} at the recorded fingerprint (a recorded round must bind to a real review)` };
+    const own = receipts.filter((r) => r.backend === b.backend);
+    const summary = summarizeReviewReceiptsForTree(own, fingerprint);
+    const failure = describeMissingReviewAttestation(summary);
+    if (failure !== null) {
+      return { ok: false, reason: `no grounded code receipt for ${b.backend} at the recorded fingerprint can attest this review round — ${failure}` };
     }
     if (b.blockers === 0 && b.majors === 0) {
-      const latest = own[own.length - 1];
-      if (!isShipVerdict(latest.verdict)) {
-        return { ok: false, reason: `${b.backend} recorded 0 blockers/0 majors but its receipt verdict "${latest.verdict}" is not ship-class` };
+      const { verdict } = summary.receipt;
+      if (!isShipVerdict(verdict)) {
+        return { ok: false, reason: `${b.backend} recorded 0 blockers/0 majors but its attesting receipt verdict "${verdict}" is not ship-class` };
       }
     }
   }