@riddledc/riddle-proof 0.5.32 → 0.5.33

package/dist/proof-run-core.cjs

@@ -50,6 +50,9 @@ __export(proof_run_core_exports, {
   setStageDecisionRequest: () => setStageDecisionRequest,
   summarizeState: () => summarizeState,
   validateShipGate: () => validateShipGate,
+  visualDeltaForState: () => visualDeltaForState,
+  visualDeltaRequiredForState: () => visualDeltaRequiredForState,
+  visualDeltaShipGateReason: () => visualDeltaShipGateReason,
   workflowFile: () => workflowFile,
   writeState: () => writeState
 });
@@ -378,6 +381,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 = [];
@@ -393,6 +444,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}`);
@@ -421,19 +476,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
     }
   };
 }
@@ -747,23 +809,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}`);
       }
@@ -907,6 +982,9 @@ function summarizeState(state) {
   setStageDecisionRequest,
   summarizeState,
   validateShipGate,
+  visualDeltaForState,
+  visualDeltaRequiredForState,
+  visualDeltaShipGateReason,
   workflowFile,
   writeState
 });

package/dist/proof-run-core.d.cts

@@ -70,6 +70,7 @@ interface ShipGateValidation {
     required_baselines: string[];
     evidence: {
         reference: string;
+        verification_mode: string | null;
         prod_url: string | null;
         before_cdn: string | null;
         prod_cdn: string | null;
@@ -77,6 +78,9 @@ interface ShipGateValidation {
         verify_status: string | null;
         proof_assessment_decision: string | null;
         proof_assessment_source: string | null;
+        visual_delta_required: boolean;
+        visual_delta_status: string | null;
+        visual_delta_passed: boolean | null;
     };
 }
 declare function resolveRiddleProofDir(config?: PluginConfig): string;
@@ -192,6 +196,9 @@ declare function invalidateVerifyEvidence(state?: any): {
     hadProofAssessment: boolean;
     hadProofAssessmentRequest: boolean;
 };
+declare function visualDeltaRequiredForState(state?: any): boolean;
+declare function visualDeltaForState(state?: any): Record<string, any>;
+declare function visualDeltaShipGateReason(state?: any): string | null;
 declare function requiredBaselineLabelsForState(state?: any): string[];
 declare function validateShipGate(state?: any): ShipGateValidation;
 declare function buildCheckpointContract(state: any, request: {
@@ -283,4 +290,4 @@ declare function summarizeState(state: any): {
     };
 };
 
-export { BUNDLED_RIDDLE_PROOF_DIR, CHECKPOINT_CONTRACT_VERSION, type CheckpointInputContract, type PluginConfig, RIDDLE_PROOF_DIR_CANDIDATES, type ShipGateValidation, WORKFLOW_STAGE_ORDER, type WorkflowAction, type WorkflowParams, type WorkflowStage, buildCheckpointContract, buildSetupArgs, checkpointContinueStage, clearStageDecisionRequest, ensureAction, ensureStageLoopState, invalidateVerifyEvidence, mergeStateFromParams, readState, recordStageAttempt, requiredBaselineLabelsForState, resolveConfig, resolveRiddleProofDir, setStageDecisionRequest, summarizeState, validateShipGate, workflowFile, writeState };
+export { BUNDLED_RIDDLE_PROOF_DIR, CHECKPOINT_CONTRACT_VERSION, type CheckpointInputContract, type PluginConfig, RIDDLE_PROOF_DIR_CANDIDATES, type ShipGateValidation, WORKFLOW_STAGE_ORDER, type WorkflowAction, type WorkflowParams, type WorkflowStage, buildCheckpointContract, buildSetupArgs, checkpointContinueStage, clearStageDecisionRequest, ensureAction, ensureStageLoopState, invalidateVerifyEvidence, mergeStateFromParams, readState, recordStageAttempt, requiredBaselineLabelsForState, resolveConfig, resolveRiddleProofDir, setStageDecisionRequest, summarizeState, validateShipGate, visualDeltaForState, visualDeltaRequiredForState, visualDeltaShipGateReason, workflowFile, writeState };

package/dist/proof-run-core.d.ts

@@ -70,6 +70,7 @@ interface ShipGateValidation {
     required_baselines: string[];
     evidence: {
         reference: string;
+        verification_mode: string | null;
         prod_url: string | null;
         before_cdn: string | null;
         prod_cdn: string | null;
@@ -77,6 +78,9 @@ interface ShipGateValidation {
         verify_status: string | null;
         proof_assessment_decision: string | null;
         proof_assessment_source: string | null;
+        visual_delta_required: boolean;
+        visual_delta_status: string | null;
+        visual_delta_passed: boolean | null;
     };
 }
 declare function resolveRiddleProofDir(config?: PluginConfig): string;
@@ -192,6 +196,9 @@ declare function invalidateVerifyEvidence(state?: any): {
     hadProofAssessment: boolean;
     hadProofAssessmentRequest: boolean;
 };
+declare function visualDeltaRequiredForState(state?: any): boolean;
+declare function visualDeltaForState(state?: any): Record<string, any>;
+declare function visualDeltaShipGateReason(state?: any): string | null;
 declare function requiredBaselineLabelsForState(state?: any): string[];
 declare function validateShipGate(state?: any): ShipGateValidation;
 declare function buildCheckpointContract(state: any, request: {
@@ -283,4 +290,4 @@ declare function summarizeState(state: any): {
     };
 };
 
-export { BUNDLED_RIDDLE_PROOF_DIR, CHECKPOINT_CONTRACT_VERSION, type CheckpointInputContract, type PluginConfig, RIDDLE_PROOF_DIR_CANDIDATES, type ShipGateValidation, WORKFLOW_STAGE_ORDER, type WorkflowAction, type WorkflowParams, type WorkflowStage, buildCheckpointContract, buildSetupArgs, checkpointContinueStage, clearStageDecisionRequest, ensureAction, ensureStageLoopState, invalidateVerifyEvidence, mergeStateFromParams, readState, recordStageAttempt, requiredBaselineLabelsForState, resolveConfig, resolveRiddleProofDir, setStageDecisionRequest, summarizeState, validateShipGate, workflowFile, writeState };
+export { BUNDLED_RIDDLE_PROOF_DIR, CHECKPOINT_CONTRACT_VERSION, type CheckpointInputContract, type PluginConfig, RIDDLE_PROOF_DIR_CANDIDATES, type ShipGateValidation, WORKFLOW_STAGE_ORDER, type WorkflowAction, type WorkflowParams, type WorkflowStage, buildCheckpointContract, buildSetupArgs, checkpointContinueStage, clearStageDecisionRequest, ensureAction, ensureStageLoopState, invalidateVerifyEvidence, mergeStateFromParams, readState, recordStageAttempt, requiredBaselineLabelsForState, resolveConfig, resolveRiddleProofDir, setStageDecisionRequest, summarizeState, validateShipGate, visualDeltaForState, visualDeltaRequiredForState, visualDeltaShipGateReason, workflowFile, writeState };

package/dist/proof-run-core.js

@@ -19,9 +19,12 @@ import {
   setStageDecisionRequest,
   summarizeState,
   validateShipGate,
+  visualDeltaForState,
+  visualDeltaRequiredForState,
+  visualDeltaShipGateReason,
   workflowFile,
   writeState
-} from "./chunk-R4BPJNAM.js";
+} from "./chunk-A5AWVY5A.js";
 export {
   BUNDLED_RIDDLE_PROOF_DIR,
   CHECKPOINT_CONTRACT_VERSION,
@@ -43,6 +46,9 @@ export {
   setStageDecisionRequest,
   summarizeState,
   validateShipGate,
+  visualDeltaForState,
+  visualDeltaRequiredForState,
+  visualDeltaShipGateReason,
   workflowFile,
   writeState
 };

package/dist/proof-run-engine.cjs

@@ -363,6 +363,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 = [];
@@ -378,6 +426,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}`);
@@ -406,19 +458,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
     }
   };
 }
@@ -732,23 +791,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}`);
       }
@@ -1622,6 +1694,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";
     }

package/dist/proof-run-engine.js

@@ -14,7 +14,7 @@ import {
   validateShipGate,
   workflowFile,
   writeState
-} from "./chunk-R4BPJNAM.js";
+} from "./chunk-A5AWVY5A.js";
 
 // src/proof-run-engine.ts
 import { execFileSync } from "child_process";
@@ -770,6 +770,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";
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@riddledc/riddle-proof",
-  "version": "0.5.32",
+  "version": "0.5.33",
   "description": "Reusable Riddle Proof contracts and helpers for evidence-backed agent changes.",
   "license": "MIT",
   "author": "RiddleDC",

package/runtime/lib/ship.py

@@ -9,6 +9,10 @@ from util import load_state, save_state, invoke, git
 
 DISCORD_API = 'https://discord.com/api/v10'
 SHIP_NOISE_PATHS = ('.codex', '.oc-smoke')
+VISUAL_FIRST_MODES = {
+    'visual', 'render', 'interaction', 'ui', 'layout', 'screenshot',
+    'canvas', 'animation',
+}
 
 
 def read_json_file(path):
@@ -293,7 +297,11 @@ def record_ship_report(state, marked_ready=None):
 def proof_assessment_is_ready(state):
     assessment = state.get('proof_assessment') or {}
     source = str(assessment.get('source') or state.get('proof_assessment_source') or '').strip().lower()
-    return source in ('supervising_agent', 'supervisor') and assessment.get('decision') == 'ready_to_ship'
+    return (
+        source in ('supervising_agent', 'supervisor')
+        and assessment.get('decision') == 'ready_to_ship'
+        and not visual_delta_ship_blocker(state)
+    )
 
 
 def effective_merge_recommendation(state):
@@ -310,6 +318,49 @@ def after_evidence_bundle(state):
     return after if isinstance(after, dict) else {}
 
 
+def normalized_verification_mode(state):
+    bundle = state.get('evidence_bundle') or {}
+    if isinstance(bundle, dict) and str(bundle.get('verification_mode') or '').strip():
+        return str(bundle.get('verification_mode')).strip().lower()
+    return str(state.get('verification_mode') or 'proof').strip().lower() or 'proof'
+
+
+def visual_delta_required_for_ship(state):
+    bundle = state.get('evidence_bundle') or {}
+    contract = bundle.get('artifact_contract') if isinstance(bundle, dict) else {}
+    required = contract.get('required') if isinstance(contract, dict) else {}
+    if isinstance(required, dict) and required.get('visual_delta') is True:
+        return True
+    return normalized_verification_mode(state) in VISUAL_FIRST_MODES
+
+
+def visual_delta_for_state(state):
+    after = after_evidence_bundle(state)
+    visual_delta = after.get('visual_delta') if isinstance(after, dict) else None
+    if isinstance(visual_delta, dict):
+        return visual_delta
+    request = state.get('proof_assessment_request') or {}
+    visual_delta = request.get('visual_delta') if isinstance(request, dict) else None
+    return visual_delta if isinstance(visual_delta, dict) else {}
+
+
+def visual_delta_ship_blocker(state):
+    if not visual_delta_required_for_ship(state):
+        return ''
+    visual_delta = visual_delta_for_state(state)
+    if visual_delta.get('status') == 'measured' and visual_delta.get('passed') is True:
+        return ''
+    status = str(visual_delta.get('status') or 'missing')
+    if status == 'unmeasured':
+        return 'visual_delta.status=unmeasured blocks ready_to_ship for visual/UI proof'
+    if status == 'measured' and visual_delta.get('passed') is False:
+        return 'visual_delta.status=measured but visual_delta.passed=false blocks ready_to_ship for visual/UI proof'
+    reason = str(visual_delta.get('reason') or '').strip()
+    if reason:
+        return f'visual_delta.status={status} blocks ready_to_ship for visual/UI proof: {reason}'
+    return f'visual_delta.status={status} blocks ready_to_ship for visual/UI proof'
+
+
 def state_has_after_evidence(state):
     if (state.get('after_cdn') or '').strip():
         return True
@@ -581,6 +632,9 @@ if reference in ('prod', 'both'):
         raise SystemExit('prod_url is required when reference=' + reference + ' before ship.')
     if not prod_cdn:
         raise SystemExit('prod_cdn is required before ship. Run recon/verify again and preserve the approved prod baseline.')
+visual_delta_blocker = visual_delta_ship_blocker(s)
+if visual_delta_blocker:
+    raise SystemExit(visual_delta_blocker + '. Rerun verify with measured before/after visual delta or return a non-shipping proof assessment.')
 if proof_source not in ('supervising_agent', 'supervisor') or proof_assessment.get('decision') != 'ready_to_ship':
     raise SystemExit('Supervising-agent proof_assessment.decision=ready_to_ship is required before ship.')
 

package/runtime/lib/verify.py

@@ -559,6 +559,34 @@ def visual_delta_applies(verification_mode):
     return screenshot_required_for_mode(verification_mode)
 
 
+def visual_delta_passes_ship_gate(visual_delta):
+    return (
+        isinstance(visual_delta, dict)
+        and visual_delta.get('status') == 'measured'
+        and visual_delta.get('passed') is True
+    )
+
+
+def visual_delta_blocker_for_mode(verification_mode, visual_delta):
+    if not visual_delta_applies(verification_mode):
+        return ''
+    if visual_delta_passes_ship_gate(visual_delta):
+        return ''
+    if not isinstance(visual_delta, dict):
+        status = 'missing'
+        reason = 'No visual_delta object was found in proof evidence.'
+    else:
+        status = str(visual_delta.get('status') or 'missing')
+        reason = str(visual_delta.get('reason') or '').strip()
+    if status == 'unmeasured':
+        return 'visual_delta.status=unmeasured blocks ready_to_ship for visual/UI proof; capture a measured before/after visual delta or choose needs_richer_proof.'
+    if status == 'measured' and isinstance(visual_delta, dict) and visual_delta.get('passed') is False:
+        return 'visual_delta.status=measured but visual_delta.passed=false blocks ready_to_ship for visual/UI proof; the measured change did not clear the threshold.'
+    if reason:
+        return f'visual_delta.status={status} blocks ready_to_ship for visual/UI proof: {reason}'
+    return f'visual_delta.status={status} blocks ready_to_ship for visual/UI proof.'
+
+
 def list_value(value):
     return value if isinstance(value, list) else []
 
@@ -684,11 +712,11 @@ def artifact_contract_for_mode(verification_mode):
             'route_semantics': True,
             'screenshot': screenshot_required_for_mode(mode),
             'proof_evidence': proof_evidence_required_for_mode(mode),
+            'visual_delta': visual_delta_applies(mode),
         },
         'preferred': {
             'page_state': True,
             'structured_payload': mode in STRUCTURED_FIRST_MODES or proof_evidence_required_for_mode(mode),
-            'visual_delta': visual_delta_applies(mode),
         },
         'optional': {
             'console_summary': True,
@@ -731,7 +759,7 @@ def artifact_signal_availability(state, after_observation, supporting, visual_de
         ),
         'structured_payload': bool(supporting.get('has_structured_payload')),
         'proof_evidence': bool(supporting.get('proof_evidence_present')),
-        'visual_delta': bool((visual_delta or {}).get('status') not in ('', None, 'not_applicable')),
+        'visual_delta': visual_delta_passes_ship_gate(visual_delta),
         'console_summary': bool(supporting.get('console_entries')),
         'json_artifacts': bool(supporting.get('data_outputs')),
         'image_outputs': bool(supporting.get('image_outputs')),
@@ -1097,6 +1125,8 @@ def build_supervisor_assessment_request(state, payload, after_observation, requi
         evidence_bundle['artifact_contract'] = artifact_contract
         evidence_bundle['artifact_production'] = artifact_production
         evidence_bundle['artifact_usage'] = artifact_usage
+    visual_delta_blocker = visual_delta_blocker_for_mode(verification_mode, visual_delta)
+    hard_blockers = [visual_delta_blocker] if visual_delta_blocker else []
 
     return {
         'status': 'needs_supervising_agent_assessment',
@@ -1112,14 +1142,15 @@ def build_supervisor_assessment_request(state, payload, after_observation, requi
         'artifact_contract': artifact_contract,
         'artifact_production': artifact_production,
         'artifact_usage': artifact_usage,
+        'hard_blockers': hard_blockers,
         'instructions': [
             'The supervising agent owns proof assessment. Inspect the recon baseline(s), after evidence, and any structured artifacts together.',
             'Decide whether the evidence is ready_to_ship or should continue internally through author, implement, or recon.',
+            'Hard blockers cannot be overridden by supervisor judgment; if hard_blockers is non-empty, do not choose ready_to_ship.',
             'Do not mark ready_to_ship if the before/prod baseline is blank, shell-only, generic, or not visibly tied to the requested feature.',
             'Use semantic_context.route plus headings/buttons/text anchors to ground route and content judgment before treating a screenshot as wrong-route.',
             'For visual/UI modes, use screenshots plus after_observation.details.visible_text_sample, headings, buttons, links, canvas_count, and large_visible_elements to explain what the proof actually shows.',
-            'For visual/UI polish, capture success is not proof. If visual_delta.status=measured and visual_delta.passed=false, choose needs_implementation or needs_richer_proof instead of ready_to_ship.',
-            'If visual_delta.status=unmeasured for visual/UI proof, only choose ready_to_ship when the screenshots and page-state details let you name a clearly legible before/after change; otherwise request richer proof or another implementation pass.',
+            'For visual/UI polish, capture success is not proof. If visual_delta.status is unmeasured, missing, not_applicable, or measured with passed=false, choose needs_implementation or needs_richer_proof instead of ready_to_ship.',
             'For data/audio/log/metrics/custom modes, judge the structured evidence bundle and proof_evidence_sample directly; screenshots are optional supporting context.',
             'The summary must name the concrete change, the target route/UI, what changed in after evidence, and why the stop condition is satisfied.',
             'Only set escalation_target=human when you conclude the workflow has hit a real wall or is not converging.',
@@ -1374,6 +1405,9 @@ s['evidence_bundle'] = evidence_bundle
 visual_delta = ((evidence_bundle.get('after') or {}).get('visual_delta') or {})
 if visual_delta.get('status') != 'not_applicable':
     summary_lines.append('Visual delta gate: ' + compact_value(visual_delta, limit=700))
+visual_delta_blocker = visual_delta_blocker_for_mode(s.get('verification_mode'), visual_delta)
+if visual_delta_blocker:
+    summary_lines.append('Visual delta hard gate: ' + visual_delta_blocker)
 
 proof_evidence_blocker = ''
 if proof_evidence_required_for_mode(s.get('verification_mode')):