@sabaiway/agent-workflow-kit 1.49.0 → 2.1.0

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` };
       }
     }
   }

package/tools/review-state.mjs

@@ -30,6 +30,18 @@
 // Informational receipts NEVER satisfy (nor fail) the tree check: plan/diff-mode receipts
 // (artifact ≠ "code") and continuations (fresh:false — agy --continue/--conversation cannot attest
 // a folded tree; only a fresh grounded re-run mints a gate-satisfying receipt).
+// PROBE receipts never satisfy either (BRIDGE-MODES-CATALOG, D3): a CODEX_PROBE=1 / AGY_PROBE=1
+// review runs with the frontier-model/max-effort guard OFF, so the wrappers stamp `probe:true` and
+// this checker drops those receipts — PER RECEIPT, so a normal receipt at the same fingerprint still
+// satisfies, and a backend whose ONLY current receipts are probes fails with its own stated reason
+// (never the stale one). Every receipt from a marker-aware wrapper SELF-DECLARES — `probe` is written
+// on every successful review, true or false — so a NON-BOOLEAN or ABSENT marker is rejected
+// fail-closed: silence is not a declaration, and the probe status of an unmarked receipt is
+// untrustworthy whoever wrote it (the pre-D3 wrappers honoured the probe env vars while writing no
+// marker; a hand-written line is no better evidence). Deliberately NOT keyed on wrapperVersion: the
+// version bumps in a different release phase than the marker lands, so a version floor would reject
+// the very receipts the current wrappers write. Accepted cost (maintainer, 2026-07-15): a pre-D3
+// receipt stops satisfying — re-run the review with a marker-aware bridge.
 //
 // The fingerprint is the ONE canonical uncommitted-state identity — sha256 over: staged diff +
 // unstaged diff + untracked-not-ignored file contents (binary untracked files, symlinks, and
@@ -61,7 +73,14 @@ import { resolveActivityRecipe, planRecipe, DISPLAY_ALIASES } from './recipes.mj
 import { CONFIG_REL, fail, loadConfig } from './orchestration-config.mjs';
 // The NEUTRAL ledger read-core (AD-050): review-state reads the review-ledger ONLY for the degraded
 // exemption, through the neutral core — never review-ledger.mjs (which imports THIS module, the cycle).
-import { resolveLedgerPath, resolveBase, readLedger, filterSegmentRecords, roundSequenceIntact } from './review-ledger-core.mjs';
+import {
+  resolveLedgerPath,
+  resolveBase,
+  readLedger,
+  filterSegmentRecords,
+  roundSequenceIntact,
+  summarizeReviewReceiptsForTree,
+} from './review-ledger-core.mjs';
 
 export const RECEIPTS_BASENAME = 'agent-workflow-review-receipts.jsonl';
 export const PLANS_REL = 'docs/plans';
@@ -290,29 +309,35 @@ export const readReceipts = (path, readFile = readFileSync) => {
   return { receipts, malformed };
 };
 
-// A receipt that can satisfy the tree check: a FRESH code-mode receipt for the current fingerprint.
-// Plan/diff-mode receipts and continuations are informational-only (see the header contract).
-const satisfies = (receipt, fingerprint) =>
-  receipt.fresh === true && receipt.artifact === 'code' && receipt.fingerprint === fingerprint;
-
-// Per-backend receipt status for the current fingerprint:
-//   current    — a satisfying receipt with grounded:true exists (its latest verdict reported);
-//   ungrounded — current-fingerprint fresh receipts exist but every one carries grounded:false;
+// Per-backend receipt status for the current fingerprint, over the ONE shared attesting-receipt
+// predicate (review-ledger-core) that the round cross-check and the round writer read too — two
+// gates disagreeing about what counts as an attestation is the class AD-050 closed:
+//   current    — an ATTESTING receipt exists (fresh code, probe:false, grounded) — its verdict rides;
+//   ungrounded — real (probe:false) current receipts exist but every one carries grounded:false;
+//   probe      — current receipts exist and EVERY one is a well-formed probe (D3);
+//   rejected   — current receipts exist, none attests, and >=1 marker was malformed or absent;
 //   stale      — this backend has receipts, none for the current fingerprint (edited after review);
-//   missing    — no usable receipt from this backend at all.
+//   missing    — no receipt from this backend at all.
+// The counts state what was dropped, so a PASS over a partially-excluded set still says so
+// (No-silent-failures) and the --json surface can show it.
 export const backendReceiptStatus = (receipts, backend, fingerprint) => {
   const own = receipts.filter((r) => r.backend === backend);
-  const current = own.filter((r) => satisfies(r, fingerprint));
-  const grounded = current.filter((r) => r.grounded === true);
-  if (grounded.length > 0) {
-    const latest = grounded[grounded.length - 1];
-    return { state: 'current', verdict: latest.verdict ?? 'unknown', grounded: true, timestamp: latest.timestamp ?? null };
+  const summary = summarizeReviewReceiptsForTree(own, fingerprint);
+  const counts = {
+    probeExcluded: summary.probeExcluded,
+    markerRejected: summary.markerRejected,
+    unmarkedRejected: summary.unmarkedRejected,
+  };
+  if (summary.state === 'current') {
+    return { state: 'current', verdict: summary.receipt.verdict ?? 'unknown', grounded: true, timestamp: summary.receipt.timestamp ?? null, ...counts };
   }
-  if (current.length > 0) {
-    const latest = current[current.length - 1];
-    return { state: 'ungrounded', verdict: latest.verdict ?? 'unknown', grounded: false, timestamp: latest.timestamp ?? null };
+  if (summary.state === 'ungrounded') {
+    return { state: 'ungrounded', verdict: summary.receipt.verdict ?? 'unknown', grounded: false, timestamp: summary.receipt.timestamp ?? null, ...counts };
   }
-  return { state: own.length > 0 ? 'stale' : 'missing', verdict: null, grounded: null, timestamp: null };
+  if (summary.state === 'probe' || summary.state === 'rejected') {
+    return { state: summary.state, verdict: null, grounded: null, timestamp: null, ...counts };
+  }
+  return { state: own.length > 0 ? 'stale' : 'missing', verdict: null, grounded: null, timestamp: null, ...counts };
 };
 
 // ── the degraded exemption (AD-050): read the review-ledger for a recorded current-tree degrade ────
@@ -411,6 +436,17 @@ export const buildState = ({ cwd, env = process.env, detect = detectBackends, ls
   };
 };
 
+// Why a backend's current-tree receipts were all rejected — the two causes read differently and
+// have different recoveries (fix the file vs refresh the bridge), so they are never collapsed.
+const rejectionCause = (b) => {
+  const parts = [];
+  if (b.markerRejected > 0) parts.push(`${b.markerRejected} with a malformed probe marker`);
+  if (b.unmarkedRejected > 0) {
+    parts.push(`${b.unmarkedRejected} with no probe marker — silence is not a declaration, so the probe status is untrustworthy; re-run the review with a bridge that marks its runs`);
+  }
+  return parts.join(' + ');
+};
+
 // The normative --check decision (the header contract, in order). → { code, reason }.
 export const decideCheck = (state) => {
   // A DETECTOR FAILURE is unknown state, not "no reviewer ready" — the advisory tools warn and
@@ -449,23 +485,37 @@ export const decideCheck = (state) => {
   // stays verdict-blind: the exemption proves the degrade was RECORDED, never that the tree converged.
   const exempt = new Set(state.degradedExempt);
   const failing = state.backends.filter((b) => b.state !== 'current' && !exempt.has(b.backend));
+  // A receipt dropped for an untrustworthy probe marker is never silently dropped either (D3): it
+  // cannot fail a tree that other receipts satisfy, but a report over a partially-rejected set says
+  // so. It counts only the exclusions NOT already named per backend — a FAILING `rejected` backend
+  // prints its own cause below, and repeating it in the summary is noise. Every other exclusion (a
+  // partial one on a satisfied backend, or one on a degraded-exempt backend) still needs a voice.
+  const namedPerBackend = new Set(failing.filter((b) => b.state === 'rejected').map((b) => b.backend));
+  const untrustedTotal = state.backends
+    .filter((b) => !namedPerBackend.has(b.backend))
+    .reduce((n, b) => n + (b.markerRejected ?? 0) + (b.unmarkedRejected ?? 0), 0);
+  const markerNote = untrustedTotal > 0
+    ? ` — ${untrustedTotal} receipt(s) rejected: an untrustworthy probe marker (malformed, or absent — silence is not a declaration) — fail-closed; inspect ${state.receiptsPath}`
+    : '';
   if (failing.length === 0) {
     if (exempt.size === 0) {
-      return { code: 0, reason: `every recipe-named backend has a fresh grounded receipt for the current tree (${state.requiredBackends.join(' + ')})${malformedNote}${ledgerNote}` };
+      return { code: 0, reason: `every recipe-named backend has a fresh grounded receipt for the current tree (${state.requiredBackends.join(' + ')})${markerNote}${malformedNote}${ledgerNote}` };
     }
-    return { code: 0, reason: `every recipe-named backend reviewed the current tree (${state.requiredBackends.join(' + ')}) — degraded-exempt (recorded degraded for the current tree in the review ledger): ${[...exempt].join(', ')}${malformedNote}${ledgerNote}` };
+    return { code: 0, reason: `every recipe-named backend reviewed the current tree (${state.requiredBackends.join(' + ')}) — degraded-exempt (recorded degraded for the current tree in the review ledger): ${[...exempt].join(', ')}${markerNote}${malformedNote}${ledgerNote}` };
   }
   const parts = failing.map((b) => {
     if (b.state === 'ungrounded') return `${b.backend}: only ungrounded receipts for the current tree — re-run grounded (--facts)`;
+    if (b.state === 'probe') return `${b.backend}: only probe receipts for the current tree (CODEX_PROBE=1 / AGY_PROBE=1 relaxes the quality guards) — a probe review never attests; re-run a real one`;
+    if (b.state === 'rejected') return `${b.backend}: current-tree receipts rejected — ${rejectionCause(b)} (fail-closed); inspect ${state.receiptsPath}`;
     if (b.state === 'stale') return `${b.backend}: receipts exist but none matches the current tree (edited after review) — run a fresh review`;
     return `${b.backend}: no receipt — run its review wrapper`;
   });
-  return { code: 1, reason: `${parts.join('; ')}${malformedNote}${ledgerNote}` };
+  return { code: 1, reason: `${parts.join('; ')}${markerNote}${malformedNote}${ledgerNote}` };
 };
 
 // ── rendering ───────────────────────────────────────────────────────────────────────
 
-const STATE_GLYPH = { current: '✓', ungrounded: '✗', stale: '✗', missing: '✗' };
+const STATE_GLYPH = { current: '✓', ungrounded: '✗', probe: '✗', rejected: '✗', stale: '✗', missing: '✗' };
 
 const formatHuman = (state, check) => {
   const src = state.resolved.source === 'config' ? `from ${CONFIG_REL}` : 'computed default';
@@ -488,10 +538,17 @@ const formatHuman = (state, check) => {
         ? `current (verdict: ${b.verdict}, grounded, ${b.timestamp ?? '?'})`
         : b.state === 'ungrounded'
           ? `ungrounded for the current tree (verdict: ${b.verdict}) — a grounded fresh run is required`
-          : b.state === 'stale'
-            ? 'stale — no receipt matches the current tree (edited after review)'
-            : 'missing — no receipt from this backend';
-    lines.push(`    ${exempt.has(b.backend) ? '⊘' : STATE_GLYPH[b.state]} ${b.backend}: ${detail}${exemptTag}`);
+          : b.state === 'probe'
+            ? 'only probe receipts for the current tree (quality guards relaxed) — a probe review never attests'
+            : b.state === 'rejected'
+              ? `current-tree receipts rejected — ${rejectionCause(b)} (fail-closed)`
+              : b.state === 'stale'
+                ? 'stale — no receipt matches the current tree (edited after review)'
+                : 'missing — no receipt from this backend';
+    const excludedTag = b.probeExcluded || b.markerRejected || b.unmarkedRejected
+      ? ` [excluded: ${b.probeExcluded} probe, ${b.markerRejected} malformed-marker, ${b.unmarkedRejected} unmarked]`
+      : '';
+    lines.push(`    ${exempt.has(b.backend) ? '⊘' : STATE_GLYPH[b.state]} ${b.backend}: ${detail}${excludedTag}${exemptTag}`);
   }
   lines.push(`  check: ${check.code === 0 ? 'PASS' : 'FAIL'} — ${check.reason}`);
   return lines.join('\n');
@@ -507,7 +564,11 @@ recomputes the canonical uncommitted-state fingerprint (staged + unstaged + untr
 the review-payload domain), reads the receipt file the review wrappers append to
 (<git dir>/${RECEIPTS_BASENAME}; AW_REVIEW_RECEIPTS overrides), and reports per-backend receipt
 presence + verdict + grounding for the CURRENT tree. Plan/diff-mode receipts and continuations
-(fresh:false) are informational-only — they never satisfy the tree check.
+(fresh:false) are informational-only — they never satisfy the tree check, and neither does a PROBE
+receipt (probe:true — a CODEX_PROBE=1 / AGY_PROBE=1 run has the quality guards off). The probe
+filter is per receipt, so a real receipt at the same fingerprint still satisfies. Every marker-aware
+wrapper writes the probe field on EVERY review (true or false), so a malformed OR absent marker is
+rejected fail-closed — silence is not a declaration.
 
 --check exits 0/1 per the normative contract in the tool header: 0 for solo / no plan in flight /
 a clean tree / not-a-git-tree / all recipe-named backends receipted-current-and-grounded OR