@riddledc/riddle-proof 0.5.32 → 0.5.33

package/dist/{chunk-R4BPJNAM.js → chunk-A5AWVY5A.js}

@@ -322,6 +322,54 @@ function normalizedProofAssessment(state = {}) {
     source: source || null
   };
 }
+var VISUAL_FIRST_MODES = /* @__PURE__ */ new Set([
+  "visual",
+  "render",
+  "interaction",
+  "ui",
+  "layout",
+  "screenshot",
+  "canvas",
+  "animation"
+]);
+function objectValue(value) {
+  return value && typeof value === "object" && !Array.isArray(value) ? value : {};
+}
+function normalizedVerificationMode(state = {}) {
+  const bundle = objectValue(state?.evidence_bundle);
+  const bundleMode = String(bundle.verification_mode || "").trim().toLowerCase();
+  if (bundleMode) return bundleMode;
+  return String(state?.verification_mode || "proof").trim().toLowerCase() || "proof";
+}
+function visualDeltaRequiredForState(state = {}) {
+  const bundle = objectValue(state?.evidence_bundle);
+  const contract = objectValue(bundle.artifact_contract);
+  const required = objectValue(contract.required);
+  return required.visual_delta === true || VISUAL_FIRST_MODES.has(normalizedVerificationMode(state));
+}
+function visualDeltaForState(state = {}) {
+  const bundle = objectValue(state?.evidence_bundle);
+  const after = objectValue(bundle.after);
+  const afterDelta = objectValue(after.visual_delta);
+  if (Object.keys(afterDelta).length) return afterDelta;
+  const request = objectValue(state?.proof_assessment_request);
+  return objectValue(request.visual_delta);
+}
+function visualDeltaShipGateReason(state = {}) {
+  if (!visualDeltaRequiredForState(state)) return null;
+  const visualDelta = visualDeltaForState(state);
+  if (visualDelta.status === "measured" && visualDelta.passed === true) return null;
+  const status = String(visualDelta.status || "missing");
+  if (status === "unmeasured") {
+    return "visual_delta.status=unmeasured blocks ready_to_ship for visual/UI proof";
+  }
+  if (status === "measured" && visualDelta.passed === false) {
+    return "visual_delta.status=measured but visual_delta.passed=false blocks ready_to_ship for visual/UI proof";
+  }
+  const reason = String(visualDelta.reason || "").trim();
+  if (reason) return `visual_delta.status=${status} blocks ready_to_ship for visual/UI proof: ${reason}`;
+  return `visual_delta.status=${status} blocks ready_to_ship for visual/UI proof`;
+}
 function requiredBaselineLabelsForState(state = {}) {
   const reference = normalizedReference(state);
   const labels = [];
@@ -337,6 +385,10 @@ function validateShipGate(state = {}) {
   const afterCdn = String(state?.after_cdn || "").trim();
   const verifyStatus = String(state?.verify_status || "").trim();
   const proofAssessment = normalizedProofAssessment(state);
+  const verificationMode = normalizedVerificationMode(state);
+  const visualDelta = visualDeltaForState(state);
+  const visualDeltaRequired = visualDeltaRequiredForState(state);
+  const visualDeltaBlocker = visualDeltaShipGateReason(state);
   const reasons = [];
   if (!["before", "prod", "both"].includes(reference)) {
     reasons.push(`reference must be before, prod, or both; got ${reference}`);
@@ -365,19 +417,26 @@ function validateShipGate(state = {}) {
   if (proofAssessment.decision !== "ready_to_ship") {
     reasons.push("proof_assessment.decision must be ready_to_ship before ship");
   }
+  if (visualDeltaBlocker) {
+    reasons.push(visualDeltaBlocker);
+  }
   return {
     ok: reasons.length === 0,
     reasons,
     required_baselines: requiredBaselines,
     evidence: {
       reference,
+      verification_mode: verificationMode || null,
       prod_url: prodUrl || null,
       before_cdn: beforeCdn || null,
       prod_cdn: prodCdn || null,
       after_cdn: afterCdn || null,
       verify_status: verifyStatus || null,
       proof_assessment_decision: proofAssessment.decision,
-      proof_assessment_source: proofAssessment.source
+      proof_assessment_source: proofAssessment.source,
+      visual_delta_required: visualDeltaRequired,
+      visual_delta_status: typeof visualDelta.status === "string" ? visualDelta.status : null,
+      visual_delta_passed: typeof visualDelta.passed === "boolean" ? visualDelta.passed : null
     }
   };
 }
@@ -691,23 +750,36 @@ function mergeStateFromParams(statePath, params) {
       state.proof_assessment_source = null;
     } else {
       const parsed = JSON.parse(raw);
-      state.proof_assessment = {
+      const assessment = {
         ...parsed,
         source: (parsed?.source || "supervising_agent").toString()
       };
+      const readyBlocker = assessment?.decision === "ready_to_ship" ? visualDeltaShipGateReason({ ...state, proof_assessment: assessment, proof_assessment_source: assessment.source }) : null;
+      if (readyBlocker) {
+        assessment.blocked_decision = assessment.decision;
+        assessment.decision = "needs_richer_proof";
+        if (assessment.recommended_stage === "ship") assessment.recommended_stage = "verify";
+        if (assessment.continue_with_stage === "ship") assessment.continue_with_stage = "verify";
+        const blockers = Array.isArray(assessment.blockers) ? assessment.blockers : [];
+        assessment.blockers = [...blockers, readyBlocker];
+      }
+      state.proof_assessment = assessment;
       state.proof_assessment_source = state.proof_assessment.source;
-      if (typeof parsed?.decision === "string") {
-        state.proof_decision = parsed.decision;
+      if (typeof state.proof_assessment?.decision === "string") {
+        state.proof_decision = state.proof_assessment.decision;
       }
       if (typeof parsed?.summary === "string") {
         state.proof_assessment_summary = normalizeOptionalString(parsed.summary) || null;
       }
-      if (parsed?.decision === "ready_to_ship") {
+      if (state.proof_assessment?.decision === "ready_to_ship") {
         state.merge_recommendation = "ready-to-ship";
-      } else if (typeof parsed?.decision === "string" && parsed.decision.trim()) {
+      } else if (typeof state.proof_assessment?.decision === "string" && state.proof_assessment.decision.trim()) {
         state.merge_recommendation = "do-not-merge";
       }
       appendProofSummaryLine(state, `Supervising proof assessment: ${state.proof_assessment.decision || "unknown"}`);
+      if (readyBlocker) {
+        appendProofSummaryLine(state, `Ready-to-ship assessment blocked: ${readyBlocker}`);
+      }
       if (state.proof_assessment_summary) {
         appendProofSummaryLine(state, `Assessment summary: ${state.proof_assessment_summary}`);
       }
@@ -848,6 +920,9 @@ export {
   setStageDecisionRequest,
   checkpointContinueStage,
   invalidateVerifyEvidence,
+  visualDeltaRequiredForState,
+  visualDeltaForState,
+  visualDeltaShipGateReason,
   requiredBaselineLabelsForState,
   validateShipGate,
   buildCheckpointContract,

package/dist/{chunk-LIDYNU7Q.js → chunk-CHKYSZLU.js}

@@ -1,3 +1,6 @@
+import {
+  visualDeltaShipGateReason
+} from "./chunk-A5AWVY5A.js";
 import {
   appendRunEvent,
   appendStageHeartbeat,
@@ -291,6 +294,26 @@ function proofAssessmentContinuation(result, payload) {
   const proof_assessment_json = jsonParam(payload);
   return { ...baseContinuation(result), proof_assessment_json };
 }
+function proofAssessmentVisualBlocker(state, payload) {
+  if (!proofAssessmentRequestsShip(payload)) return null;
+  const source = nonEmptyString(payload.source) || "supervising_agent";
+  return visualDeltaShipGateReason({
+    ...state || {},
+    proof_assessment: { ...payload, source },
+    proof_assessment_source: source
+  });
+}
+function blockedProofAssessmentPayload(payload, blocker) {
+  const blockers = Array.isArray(payload.blockers) ? payload.blockers.filter((item) => typeof item === "string") : [];
+  return {
+    ...payload,
+    blocked_decision: payload.decision || "ready_to_ship",
+    decision: "needs_richer_proof",
+    recommended_stage: payload.recommended_stage === "ship" ? "verify" : payload.recommended_stage || "verify",
+    continue_with_stage: payload.continue_with_stage === "ship" ? "verify" : payload.continue_with_stage || "verify",
+    blockers: [...blockers, blocker]
+  };
+}
 function contextFor(request, state, result) {
   return {
     request,
@@ -660,6 +683,20 @@ async function routeCheckpoint(request, state, result, agent, input) {
       summary: assessment.summary,
       details: { payload }
     });
+    const visualBlocker = proofAssessmentVisualBlocker({
+      ...context.fullRiddleState || {},
+      verification_mode: context.fullRiddleState?.verification_mode || request.verification_mode
+    }, payload);
+    if (visualBlocker) {
+      recordEvent(state, {
+        kind: "agent.proof_assessment.blocked",
+        checkpoint,
+        stage: "verify",
+        summary: visualBlocker,
+        details: { payload }
+      });
+      return { next: proofAssessmentContinuation(result, blockedProofAssessmentPayload(payload, visualBlocker)) };
+    }
     if (effectiveShipMode(request, input.config) !== "ship" && proofAssessmentRequestsShip(payload)) {
       return {
         terminal: terminalResult(

package/dist/engine-harness.cjs

@@ -340,6 +340,44 @@ function normalizedProofAssessment(state = {}) {
     source: source || null
   };
 }
+function objectValue(value) {
+  return value && typeof value === "object" && !Array.isArray(value) ? value : {};
+}
+function normalizedVerificationMode(state = {}) {
+  const bundle = objectValue(state?.evidence_bundle);
+  const bundleMode = String(bundle.verification_mode || "").trim().toLowerCase();
+  if (bundleMode) return bundleMode;
+  return String(state?.verification_mode || "proof").trim().toLowerCase() || "proof";
+}
+function visualDeltaRequiredForState(state = {}) {
+  const bundle = objectValue(state?.evidence_bundle);
+  const contract = objectValue(bundle.artifact_contract);
+  const required = objectValue(contract.required);
+  return required.visual_delta === true || VISUAL_FIRST_MODES.has(normalizedVerificationMode(state));
+}
+function visualDeltaForState(state = {}) {
+  const bundle = objectValue(state?.evidence_bundle);
+  const after = objectValue(bundle.after);
+  const afterDelta = objectValue(after.visual_delta);
+  if (Object.keys(afterDelta).length) return afterDelta;
+  const request = objectValue(state?.proof_assessment_request);
+  return objectValue(request.visual_delta);
+}
+function visualDeltaShipGateReason(state = {}) {
+  if (!visualDeltaRequiredForState(state)) return null;
+  const visualDelta = visualDeltaForState(state);
+  if (visualDelta.status === "measured" && visualDelta.passed === true) return null;
+  const status = String(visualDelta.status || "missing");
+  if (status === "unmeasured") {
+    return "visual_delta.status=unmeasured blocks ready_to_ship for visual/UI proof";
+  }
+  if (status === "measured" && visualDelta.passed === false) {
+    return "visual_delta.status=measured but visual_delta.passed=false blocks ready_to_ship for visual/UI proof";
+  }
+  const reason = String(visualDelta.reason || "").trim();
+  if (reason) return `visual_delta.status=${status} blocks ready_to_ship for visual/UI proof: ${reason}`;
+  return `visual_delta.status=${status} blocks ready_to_ship for visual/UI proof`;
+}
 function requiredBaselineLabelsForState(state = {}) {
   const reference = normalizedReference(state);
   const labels = [];
@@ -355,6 +393,10 @@ function validateShipGate(state = {}) {
   const afterCdn = String(state?.after_cdn || "").trim();
   const verifyStatus = String(state?.verify_status || "").trim();
   const proofAssessment = normalizedProofAssessment(state);
+  const verificationMode = normalizedVerificationMode(state);
+  const visualDelta = visualDeltaForState(state);
+  const visualDeltaRequired = visualDeltaRequiredForState(state);
+  const visualDeltaBlocker = visualDeltaShipGateReason(state);
   const reasons = [];
   if (!["before", "prod", "both"].includes(reference)) {
     reasons.push(`reference must be before, prod, or both; got ${reference}`);
@@ -383,19 +425,26 @@ function validateShipGate(state = {}) {
   if (proofAssessment.decision !== "ready_to_ship") {
     reasons.push("proof_assessment.decision must be ready_to_ship before ship");
   }
+  if (visualDeltaBlocker) {
+    reasons.push(visualDeltaBlocker);
+  }
   return {
     ok: reasons.length === 0,
     reasons,
     required_baselines: requiredBaselines,
     evidence: {
       reference,
+      verification_mode: verificationMode || null,
       prod_url: prodUrl || null,
       before_cdn: beforeCdn || null,
       prod_cdn: prodCdn || null,
       after_cdn: afterCdn || null,
       verify_status: verifyStatus || null,
       proof_assessment_decision: proofAssessment.decision,
-      proof_assessment_source: proofAssessment.source
+      proof_assessment_source: proofAssessment.source,
+      visual_delta_required: visualDeltaRequired,
+      visual_delta_status: typeof visualDelta.status === "string" ? visualDelta.status : null,
+      visual_delta_passed: typeof visualDelta.passed === "boolean" ? visualDelta.passed : null
     }
   };
 }
@@ -541,23 +590,36 @@ function mergeStateFromParams(statePath, params) {
       state.proof_assessment_source = null;
     } else {
       const parsed = JSON.parse(raw);
-      state.proof_assessment = {
+      const assessment = {
         ...parsed,
         source: (parsed?.source || "supervising_agent").toString()
       };
+      const readyBlocker = assessment?.decision === "ready_to_ship" ? visualDeltaShipGateReason({ ...state, proof_assessment: assessment, proof_assessment_source: assessment.source }) : null;
+      if (readyBlocker) {
+        assessment.blocked_decision = assessment.decision;
+        assessment.decision = "needs_richer_proof";
+        if (assessment.recommended_stage === "ship") assessment.recommended_stage = "verify";
+        if (assessment.continue_with_stage === "ship") assessment.continue_with_stage = "verify";
+        const blockers = Array.isArray(assessment.blockers) ? assessment.blockers : [];
+        assessment.blockers = [...blockers, readyBlocker];
+      }
+      state.proof_assessment = assessment;
       state.proof_assessment_source = state.proof_assessment.source;
-      if (typeof parsed?.decision === "string") {
-        state.proof_decision = parsed.decision;
+      if (typeof state.proof_assessment?.decision === "string") {
+        state.proof_decision = state.proof_assessment.decision;
       }
       if (typeof parsed?.summary === "string") {
         state.proof_assessment_summary = normalizeOptionalString(parsed.summary) || null;
       }
-      if (parsed?.decision === "ready_to_ship") {
+      if (state.proof_assessment?.decision === "ready_to_ship") {
         state.merge_recommendation = "ready-to-ship";
-      } else if (typeof parsed?.decision === "string" && parsed.decision.trim()) {
+      } else if (typeof state.proof_assessment?.decision === "string" && state.proof_assessment.decision.trim()) {
         state.merge_recommendation = "do-not-merge";
       }
       appendProofSummaryLine(state, `Supervising proof assessment: ${state.proof_assessment.decision || "unknown"}`);
+      if (readyBlocker) {
+        appendProofSummaryLine(state, `Ready-to-ship assessment blocked: ${readyBlocker}`);
+      }
       if (state.proof_assessment_summary) {
         appendProofSummaryLine(state, `Assessment summary: ${state.proof_assessment_summary}`);
       }
@@ -679,7 +741,7 @@ function summarizeState(state) {
     state: selected
   };
 }
-var import_node_fs, import_node_crypto, import_node_path, import_node_url, import_meta, WORKFLOW_STAGE_ORDER, CHECKPOINT_CONTRACT_VERSION, BUNDLED_RIDDLE_PROOF_DIR, RIDDLE_PROOF_DIR_CANDIDATES, CHECKPOINT_CONTRACT_SPECS;
+var import_node_fs, import_node_crypto, import_node_path, import_node_url, import_meta, WORKFLOW_STAGE_ORDER, CHECKPOINT_CONTRACT_VERSION, BUNDLED_RIDDLE_PROOF_DIR, RIDDLE_PROOF_DIR_CANDIDATES, VISUAL_FIRST_MODES, CHECKPOINT_CONTRACT_SPECS;
 var init_proof_run_core = __esm({
   "src/proof-run-core.ts"() {
     "use strict";
@@ -698,6 +760,16 @@ var init_proof_run_core = __esm({
     RIDDLE_PROOF_DIR_CANDIDATES = [
       BUNDLED_RIDDLE_PROOF_DIR
     ];
+    VISUAL_FIRST_MODES = /* @__PURE__ */ new Set([
+      "visual",
+      "render",
+      "interaction",
+      "ui",
+      "layout",
+      "screenshot",
+      "canvas",
+      "animation"
+    ]);
     CHECKPOINT_CONTRACT_SPECS = {
       setup_review: {
         purpose: "Inspect prepared workspace state before moving into recon."
@@ -1624,6 +1696,9 @@ async function executeWorkflow(params, pluginConfig, resolvedConfig) {
     if (reasons.some((reason) => reason.includes("proof_assessment"))) {
       return "resume with riddle_proof_review using decision=ready_to_ship only after the screenshots and semantic evidence visibly prove the request; otherwise choose needs_implementation or needs_richer_proof";
     }
+    if (reasons.some((reason) => reason.includes("visual_delta"))) {
+      return "rerun verify with a measured before/after visual delta, or choose needs_richer_proof instead of ready_to_ship for this visual proof";
+    }
     if (reasons.some((reason) => reason.includes("after_cdn") || reason.includes("verify_status"))) {
       return "rerun verify with stronger proof framing so after evidence is captured before shipping";
     }
@@ -3028,6 +3103,7 @@ function setRunStatus(state, status, at = timestamp()) {
 }
 
 // src/engine-harness.ts
+init_proof_run_core();
 var DEFAULT_MAX_ITERATIONS = 12;
 var DEFAULT_STAGE_ITERATION_LIMITS = {
   setup: 2,
@@ -3292,6 +3368,26 @@ function proofAssessmentContinuation(result, payload) {
   const proof_assessment_json = jsonParam(payload);
   return { ...baseContinuation(result), proof_assessment_json };
 }
+function proofAssessmentVisualBlocker(state, payload) {
+  if (!proofAssessmentRequestsShip(payload)) return null;
+  const source = nonEmptyString(payload.source) || "supervising_agent";
+  return visualDeltaShipGateReason({
+    ...state || {},
+    proof_assessment: { ...payload, source },
+    proof_assessment_source: source
+  });
+}
+function blockedProofAssessmentPayload(payload, blocker) {
+  const blockers = Array.isArray(payload.blockers) ? payload.blockers.filter((item) => typeof item === "string") : [];
+  return {
+    ...payload,
+    blocked_decision: payload.decision || "ready_to_ship",
+    decision: "needs_richer_proof",
+    recommended_stage: payload.recommended_stage === "ship" ? "verify" : payload.recommended_stage || "verify",
+    continue_with_stage: payload.continue_with_stage === "ship" ? "verify" : payload.continue_with_stage || "verify",
+    blockers: [...blockers, blocker]
+  };
+}
 function contextFor(request, state, result) {
   return {
     request,
@@ -3661,6 +3757,20 @@ async function routeCheckpoint(request, state, result, agent, input) {
       summary: assessment.summary,
       details: { payload }
     });
+    const visualBlocker = proofAssessmentVisualBlocker({
+      ...context.fullRiddleState || {},
+      verification_mode: context.fullRiddleState?.verification_mode || request.verification_mode
+    }, payload);
+    if (visualBlocker) {
+      recordEvent(state, {
+        kind: "agent.proof_assessment.blocked",
+        checkpoint,
+        stage: "verify",
+        summary: visualBlocker,
+        details: { payload }
+      });
+      return { next: proofAssessmentContinuation(result, blockedProofAssessmentPayload(payload, visualBlocker)) };
+    }
     if (effectiveShipMode(request, input.config) !== "ship" && proofAssessmentRequestsShip(payload)) {
       return {
         terminal: terminalResult(

package/dist/engine-harness.js

@@ -2,7 +2,8 @@ import {
   createDisabledRiddleProofAgentAdapter,
   readRiddleProofRunStatus,
   runRiddleProofEngineHarness
-} from "./chunk-LIDYNU7Q.js";
+} from "./chunk-CHKYSZLU.js";
+import "./chunk-A5AWVY5A.js";
 import "./chunk-7ZJAUEUN.js";
 import "./chunk-TMMKRKY5.js";
 export {

package/dist/index.cjs

@@ -340,6 +340,44 @@ function normalizedProofAssessment(state = {}) {
     source: source || null
   };
 }
+function objectValue(value) {
+  return value && typeof value === "object" && !Array.isArray(value) ? value : {};
+}
+function normalizedVerificationMode(state = {}) {
+  const bundle = objectValue(state?.evidence_bundle);
+  const bundleMode = String(bundle.verification_mode || "").trim().toLowerCase();
+  if (bundleMode) return bundleMode;
+  return String(state?.verification_mode || "proof").trim().toLowerCase() || "proof";
+}
+function visualDeltaRequiredForState(state = {}) {
+  const bundle = objectValue(state?.evidence_bundle);
+  const contract = objectValue(bundle.artifact_contract);
+  const required = objectValue(contract.required);
+  return required.visual_delta === true || VISUAL_FIRST_MODES.has(normalizedVerificationMode(state));
+}
+function visualDeltaForState(state = {}) {
+  const bundle = objectValue(state?.evidence_bundle);
+  const after = objectValue(bundle.after);
+  const afterDelta = objectValue(after.visual_delta);
+  if (Object.keys(afterDelta).length) return afterDelta;
+  const request = objectValue(state?.proof_assessment_request);
+  return objectValue(request.visual_delta);
+}
+function visualDeltaShipGateReason(state = {}) {
+  if (!visualDeltaRequiredForState(state)) return null;
+  const visualDelta = visualDeltaForState(state);
+  if (visualDelta.status === "measured" && visualDelta.passed === true) return null;
+  const status = String(visualDelta.status || "missing");
+  if (status === "unmeasured") {
+    return "visual_delta.status=unmeasured blocks ready_to_ship for visual/UI proof";
+  }
+  if (status === "measured" && visualDelta.passed === false) {
+    return "visual_delta.status=measured but visual_delta.passed=false blocks ready_to_ship for visual/UI proof";
+  }
+  const reason = String(visualDelta.reason || "").trim();
+  if (reason) return `visual_delta.status=${status} blocks ready_to_ship for visual/UI proof: ${reason}`;
+  return `visual_delta.status=${status} blocks ready_to_ship for visual/UI proof`;
+}
 function requiredBaselineLabelsForState(state = {}) {
   const reference = normalizedReference(state);
   const labels = [];
@@ -355,6 +393,10 @@ function validateShipGate(state = {}) {
   const afterCdn = String(state?.after_cdn || "").trim();
   const verifyStatus = String(state?.verify_status || "").trim();
   const proofAssessment = normalizedProofAssessment(state);
+  const verificationMode = normalizedVerificationMode(state);
+  const visualDelta = visualDeltaForState(state);
+  const visualDeltaRequired = visualDeltaRequiredForState(state);
+  const visualDeltaBlocker = visualDeltaShipGateReason(state);
   const reasons = [];
   if (!["before", "prod", "both"].includes(reference)) {
     reasons.push(`reference must be before, prod, or both; got ${reference}`);
@@ -383,19 +425,26 @@ function validateShipGate(state = {}) {
   if (proofAssessment.decision !== "ready_to_ship") {
     reasons.push("proof_assessment.decision must be ready_to_ship before ship");
   }
+  if (visualDeltaBlocker) {
+    reasons.push(visualDeltaBlocker);
+  }
   return {
     ok: reasons.length === 0,
     reasons,
     required_baselines: requiredBaselines,
     evidence: {
       reference,
+      verification_mode: verificationMode || null,
       prod_url: prodUrl || null,
       before_cdn: beforeCdn || null,
       prod_cdn: prodCdn || null,
       after_cdn: afterCdn || null,
       verify_status: verifyStatus || null,
       proof_assessment_decision: proofAssessment.decision,
-      proof_assessment_source: proofAssessment.source
+      proof_assessment_source: proofAssessment.source,
+      visual_delta_required: visualDeltaRequired,
+      visual_delta_status: typeof visualDelta.status === "string" ? visualDelta.status : null,
+      visual_delta_passed: typeof visualDelta.passed === "boolean" ? visualDelta.passed : null
     }
   };
 }
@@ -541,23 +590,36 @@ function mergeStateFromParams(statePath, params) {
       state.proof_assessment_source = null;
     } else {
       const parsed = JSON.parse(raw);
-      state.proof_assessment = {
+      const assessment = {
         ...parsed,
         source: (parsed?.source || "supervising_agent").toString()
       };
+      const readyBlocker = assessment?.decision === "ready_to_ship" ? visualDeltaShipGateReason({ ...state, proof_assessment: assessment, proof_assessment_source: assessment.source }) : null;
+      if (readyBlocker) {
+        assessment.blocked_decision = assessment.decision;
+        assessment.decision = "needs_richer_proof";
+        if (assessment.recommended_stage === "ship") assessment.recommended_stage = "verify";
+        if (assessment.continue_with_stage === "ship") assessment.continue_with_stage = "verify";
+        const blockers = Array.isArray(assessment.blockers) ? assessment.blockers : [];
+        assessment.blockers = [...blockers, readyBlocker];
+      }
+      state.proof_assessment = assessment;
       state.proof_assessment_source = state.proof_assessment.source;
-      if (typeof parsed?.decision === "string") {
-        state.proof_decision = parsed.decision;
+      if (typeof state.proof_assessment?.decision === "string") {
+        state.proof_decision = state.proof_assessment.decision;
       }
       if (typeof parsed?.summary === "string") {
         state.proof_assessment_summary = normalizeOptionalString(parsed.summary) || null;
       }
-      if (parsed?.decision === "ready_to_ship") {
+      if (state.proof_assessment?.decision === "ready_to_ship") {
         state.merge_recommendation = "ready-to-ship";
-      } else if (typeof parsed?.decision === "string" && parsed.decision.trim()) {
+      } else if (typeof state.proof_assessment?.decision === "string" && state.proof_assessment.decision.trim()) {
         state.merge_recommendation = "do-not-merge";
       }
       appendProofSummaryLine(state, `Supervising proof assessment: ${state.proof_assessment.decision || "unknown"}`);
+      if (readyBlocker) {
+        appendProofSummaryLine(state, `Ready-to-ship assessment blocked: ${readyBlocker}`);
+      }
       if (state.proof_assessment_summary) {
         appendProofSummaryLine(state, `Assessment summary: ${state.proof_assessment_summary}`);
       }
@@ -679,7 +741,7 @@ function summarizeState(state) {
     state: selected
   };
 }
-var import_node_fs, import_node_crypto, import_node_path, import_node_url, import_meta, WORKFLOW_STAGE_ORDER, CHECKPOINT_CONTRACT_VERSION, BUNDLED_RIDDLE_PROOF_DIR, RIDDLE_PROOF_DIR_CANDIDATES, CHECKPOINT_CONTRACT_SPECS;
+var import_node_fs, import_node_crypto, import_node_path, import_node_url, import_meta, WORKFLOW_STAGE_ORDER, CHECKPOINT_CONTRACT_VERSION, BUNDLED_RIDDLE_PROOF_DIR, RIDDLE_PROOF_DIR_CANDIDATES, VISUAL_FIRST_MODES, CHECKPOINT_CONTRACT_SPECS;
 var init_proof_run_core = __esm({
   "src/proof-run-core.ts"() {
     "use strict";
@@ -698,6 +760,16 @@ var init_proof_run_core = __esm({
     RIDDLE_PROOF_DIR_CANDIDATES = [
       BUNDLED_RIDDLE_PROOF_DIR
     ];
+    VISUAL_FIRST_MODES = /* @__PURE__ */ new Set([
+      "visual",
+      "render",
+      "interaction",
+      "ui",
+      "layout",
+      "screenshot",
+      "canvas",
+      "animation"
+    ]);
     CHECKPOINT_CONTRACT_SPECS = {
       setup_review: {
         purpose: "Inspect prepared workspace state before moving into recon."
@@ -1624,6 +1696,9 @@ async function executeWorkflow(params, pluginConfig, resolvedConfig) {
     if (reasons.some((reason) => reason.includes("proof_assessment"))) {
       return "resume with riddle_proof_review using decision=ready_to_ship only after the screenshots and semantic evidence visibly prove the request; otherwise choose needs_implementation or needs_richer_proof";
     }
+    if (reasons.some((reason) => reason.includes("visual_delta"))) {
+      return "rerun verify with a measured before/after visual delta, or choose needs_richer_proof instead of ready_to_ship for this visual proof";
+    }
     if (reasons.some((reason) => reason.includes("after_cdn") || reason.includes("verify_status"))) {
       return "rerun verify with stronger proof framing so after evidence is captured before shipping";
     }
@@ -3584,6 +3659,7 @@ var import_node_child_process2 = require("child_process");
 var import_node_fs3 = require("fs");
 var import_node_path3 = __toESM(require("path"), 1);
 var import_node_crypto2 = __toESM(require("crypto"), 1);
+init_proof_run_core();
 var DEFAULT_MAX_ITERATIONS = 12;
 var DEFAULT_STAGE_ITERATION_LIMITS = {
   setup: 2,
@@ -3848,6 +3924,26 @@ function proofAssessmentContinuation(result, payload) {
   const proof_assessment_json = jsonParam(payload);
   return { ...baseContinuation(result), proof_assessment_json };
 }
+function proofAssessmentVisualBlocker(state, payload) {
+  if (!proofAssessmentRequestsShip(payload)) return null;
+  const source = nonEmptyString(payload.source) || "supervising_agent";
+  return visualDeltaShipGateReason({
+    ...state || {},
+    proof_assessment: { ...payload, source },
+    proof_assessment_source: source
+  });
+}
+function blockedProofAssessmentPayload(payload, blocker) {
+  const blockers = Array.isArray(payload.blockers) ? payload.blockers.filter((item) => typeof item === "string") : [];
+  return {
+    ...payload,
+    blocked_decision: payload.decision || "ready_to_ship",
+    decision: "needs_richer_proof",
+    recommended_stage: payload.recommended_stage === "ship" ? "verify" : payload.recommended_stage || "verify",
+    continue_with_stage: payload.continue_with_stage === "ship" ? "verify" : payload.continue_with_stage || "verify",
+    blockers: [...blockers, blocker]
+  };
+}
 function contextFor(request, state, result) {
   return {
     request,
@@ -4217,6 +4313,20 @@ async function routeCheckpoint(request, state, result, agent, input) {
       summary: assessment.summary,
       details: { payload }
     });
+    const visualBlocker = proofAssessmentVisualBlocker({
+      ...context.fullRiddleState || {},
+      verification_mode: context.fullRiddleState?.verification_mode || request.verification_mode
+    }, payload);
+    if (visualBlocker) {
+      recordEvent(state, {
+        kind: "agent.proof_assessment.blocked",
+        checkpoint,
+        stage: "verify",
+        summary: visualBlocker,
+        details: { payload }
+      });
+      return { next: proofAssessmentContinuation(result, blockedProofAssessmentPayload(payload, visualBlocker)) };
+    }
     if (effectiveShipMode(request, input.config) !== "ship" && proofAssessmentRequestsShip(payload)) {
       return {
         terminal: terminalResult(

package/dist/index.js

@@ -13,7 +13,8 @@ import {
   createDisabledRiddleProofAgentAdapter,
   readRiddleProofRunStatus,
   runRiddleProofEngineHarness
-} from "./chunk-LIDYNU7Q.js";
+} from "./chunk-CHKYSZLU.js";
+import "./chunk-A5AWVY5A.js";
 import {
   runRiddleProof
 } from "./chunk-F6VFKS7K.js";