@riddledc/riddle-proof 0.5.32 → 0.5.34

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
 });
@@ -119,6 +122,11 @@ function ensureAction(action) {
 function workflowFile(riddleProofDir, action) {
   return import_node_path.default.join(riddleProofDir, "pipelines", `riddle-proof-${action}.lobster`);
 }
+function asJsonString(value) {
+  if (value === void 0 || value === null || value === "") return "";
+  if (typeof value === "string") return value;
+  return JSON.stringify(value);
+}
 function buildSetupArgs(params, config) {
   if (!params.repo) throw new Error("repo is required for setup/run");
   if (!params.change_request) throw new Error("change_request is required for setup/run");
@@ -134,8 +142,13 @@ function buildSetupArgs(params, config) {
     prod_url: params.prod_url || "",
     capture_script: captureScript,
     success_criteria: params.success_criteria || "",
-    assertions_json: params.assertions_json || "",
+    assertions_json: params.assertions_json || asJsonString(params.assertions),
     verification_mode: params.verification_mode || "proof",
+    resume_session: params.resume_session || "",
+    target_image_url: params.target_image_url || "",
+    target_image_hash: params.target_image_hash || "",
+    viewport_matrix_json: params.viewport_matrix_json || asJsonString(params.viewport_matrix),
+    deterministic_setup_json: params.deterministic_setup_json || asJsonString(params.deterministic_setup),
     reference: requestedReference,
     base_branch: params.base_branch || "main",
     before_ref: params.before_ref || "",
@@ -378,6 +391,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 +454,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 +486,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
     }
   };
 }
@@ -646,6 +718,11 @@ function mergeStateFromParams(statePath, params) {
     "success_criteria",
     "assertions_json",
     "verification_mode",
+    "resume_session",
+    "target_image_url",
+    "target_image_hash",
+    "viewport_matrix_json",
+    "deterministic_setup_json",
     "base_branch",
     "before_ref",
     "context",
@@ -747,23 +824,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}`);
       }
@@ -864,7 +954,10 @@ function summarizeState(state) {
     explicit_stage_gate: Boolean(state.explicit_stage_gate),
     last_requested_advance_stage: state.last_requested_advance_stage || null,
     recon_results: state.recon_results || null,
-    verify_results: state.verify_results || null
+    verify_results: state.verify_results || null,
+    proof_session: state.proof_session || null,
+    parent_proof_session: state.parent_proof_session || null,
+    proof_session_artifact_url: state.proof_session_artifact_url || null
   };
   const parts = [
     state.workspace_ready ? "workspace ready" : "workspace not ready",
@@ -907,6 +1000,9 @@ function summarizeState(state) {
   setStageDecisionRequest,
   summarizeState,
   validateShipGate,
+  visualDeltaForState,
+  visualDeltaRequiredForState,
+  visualDeltaShipGateReason,
   workflowFile,
   writeState
 });

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

@@ -10,8 +10,16 @@ interface WorkflowParams {
     prod_url?: string;
     capture_script?: string;
     success_criteria?: string;
+    assertions?: unknown;
     assertions_json?: string;
     verification_mode?: string;
+    resume_session?: string;
+    target_image_url?: string;
+    target_image_hash?: string;
+    viewport_matrix?: unknown;
+    viewport_matrix_json?: string;
+    deterministic_setup?: unknown;
+    deterministic_setup_json?: string;
     reference?: "prod" | "before" | "both";
     base_branch?: string;
     before_ref?: string;
@@ -70,6 +78,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 +86,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;
@@ -98,6 +110,11 @@ declare function buildSetupArgs(params: WorkflowParams, config: ReturnType<typeo
     success_criteria: string;
     assertions_json: string;
     verification_mode: string;
+    resume_session: string;
+    target_image_url: string;
+    target_image_hash: string;
+    viewport_matrix_json: string;
+    deterministic_setup_json: string;
     reference: "prod" | "before" | "both";
     base_branch: string;
     before_ref: string;
@@ -192,6 +209,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: {
@@ -280,7 +300,10 @@ declare function summarizeState(state: any): {
         last_requested_advance_stage: any;
         recon_results: any;
         verify_results: any;
+        proof_session: any;
+        parent_proof_session: any;
+        proof_session_artifact_url: 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

@@ -10,8 +10,16 @@ interface WorkflowParams {
     prod_url?: string;
     capture_script?: string;
     success_criteria?: string;
+    assertions?: unknown;
     assertions_json?: string;
     verification_mode?: string;
+    resume_session?: string;
+    target_image_url?: string;
+    target_image_hash?: string;
+    viewport_matrix?: unknown;
+    viewport_matrix_json?: string;
+    deterministic_setup?: unknown;
+    deterministic_setup_json?: string;
     reference?: "prod" | "before" | "both";
     base_branch?: string;
     before_ref?: string;
@@ -70,6 +78,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 +86,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;
@@ -98,6 +110,11 @@ declare function buildSetupArgs(params: WorkflowParams, config: ReturnType<typeo
     success_criteria: string;
     assertions_json: string;
     verification_mode: string;
+    resume_session: string;
+    target_image_url: string;
+    target_image_hash: string;
+    viewport_matrix_json: string;
+    deterministic_setup_json: string;
     reference: "prod" | "before" | "both";
     base_branch: string;
     before_ref: string;
@@ -192,6 +209,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: {
@@ -280,7 +300,10 @@ declare function summarizeState(state: any): {
         last_requested_advance_stage: any;
         recon_results: any;
         verify_results: any;
+        proof_session: any;
+        parent_proof_session: any;
+        proof_session_artifact_url: 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-4YCWZVBN.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

@@ -104,6 +104,11 @@ function ensureAction(action) {
 function workflowFile(riddleProofDir, action) {
   return import_node_path.default.join(riddleProofDir, "pipelines", `riddle-proof-${action}.lobster`);
 }
+function asJsonString(value) {
+  if (value === void 0 || value === null || value === "") return "";
+  if (typeof value === "string") return value;
+  return JSON.stringify(value);
+}
 function buildSetupArgs(params, config) {
   if (!params.repo) throw new Error("repo is required for setup/run");
   if (!params.change_request) throw new Error("change_request is required for setup/run");
@@ -119,8 +124,13 @@ function buildSetupArgs(params, config) {
     prod_url: params.prod_url || "",
     capture_script: captureScript,
     success_criteria: params.success_criteria || "",
-    assertions_json: params.assertions_json || "",
+    assertions_json: params.assertions_json || asJsonString(params.assertions),
     verification_mode: params.verification_mode || "proof",
+    resume_session: params.resume_session || "",
+    target_image_url: params.target_image_url || "",
+    target_image_hash: params.target_image_hash || "",
+    viewport_matrix_json: params.viewport_matrix_json || asJsonString(params.viewport_matrix),
+    deterministic_setup_json: params.deterministic_setup_json || asJsonString(params.deterministic_setup),
     reference: requestedReference,
     base_branch: params.base_branch || "main",
     before_ref: params.before_ref || "",
@@ -363,6 +373,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 +436,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 +468,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
     }
   };
 }
@@ -631,6 +700,11 @@ function mergeStateFromParams(statePath, params) {
     "success_criteria",
     "assertions_json",
     "verification_mode",
+    "resume_session",
+    "target_image_url",
+    "target_image_hash",
+    "viewport_matrix_json",
+    "deterministic_setup_json",
     "base_branch",
     "before_ref",
     "context",
@@ -732,23 +806,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}`);
       }
@@ -849,7 +936,10 @@ function summarizeState(state) {
     explicit_stage_gate: Boolean(state.explicit_stage_gate),
     last_requested_advance_stage: state.last_requested_advance_stage || null,
     recon_results: state.recon_results || null,
-    verify_results: state.verify_results || null
+    verify_results: state.verify_results || null,
+    proof_session: state.proof_session || null,
+    parent_proof_session: state.parent_proof_session || null,
+    proof_session_artifact_url: state.proof_session_artifact_url || null
   };
   const parts = [
     state.workspace_ready ? "workspace ready" : "workspace not ready",
@@ -1622,6 +1712,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.d.cts

@@ -83,6 +83,9 @@ declare function executeWorkflow(params: WorkflowParams, pluginConfig: any, reso
         last_requested_advance_stage: any;
         recon_results: any;
         verify_results: any;
+        proof_session: any;
+        parent_proof_session: any;
+        proof_session_artifact_url: any;
     } | null;
     pr_state: {
         status: string;
@@ -172,6 +175,9 @@ declare function executeWorkflow(params: WorkflowParams, pluginConfig: any, reso
         last_requested_advance_stage: any;
         recon_results: any;
         verify_results: any;
+        proof_session: any;
+        parent_proof_session: any;
+        proof_session_artifact_url: any;
     } | null;
     pr_state: {
         status: string;
@@ -259,6 +265,9 @@ declare function executeWorkflow(params: WorkflowParams, pluginConfig: any, reso
         last_requested_advance_stage: any;
         recon_results: any;
         verify_results: any;
+        proof_session: any;
+        parent_proof_session: any;
+        proof_session_artifact_url: any;
     } | null;
     pr_state: any;
     cleanup: Record<string, unknown> | null;
@@ -339,6 +348,9 @@ declare function executeWorkflow(params: WorkflowParams, pluginConfig: any, reso
         last_requested_advance_stage: any;
         recon_results: any;
         verify_results: any;
+        proof_session: any;
+        parent_proof_session: any;
+        proof_session_artifact_url: any;
     } | null;
     approval: any;
     error: any;
@@ -422,6 +434,9 @@ declare function executeWorkflow(params: WorkflowParams, pluginConfig: any, reso
         last_requested_advance_stage: any;
         recon_results: any;
         verify_results: any;
+        proof_session: any;
+        parent_proof_session: any;
+        proof_session_artifact_url: any;
     } | null;
     decisionRequest: any;
     checkpointContract: any;
@@ -509,6 +524,9 @@ declare function executeWorkflow(params: WorkflowParams, pluginConfig: any, reso
         last_requested_advance_stage: any;
         recon_results: any;
         verify_results: any;
+        proof_session: any;
+        parent_proof_session: any;
+        proof_session_artifact_url: any;
     };
     state_path: string;
     ok?: undefined;
@@ -594,6 +612,9 @@ declare function executeWorkflow(params: WorkflowParams, pluginConfig: any, reso
         last_requested_advance_stage: any;
         recon_results: any;
         verify_results: any;
+        proof_session: any;
+        parent_proof_session: any;
+        proof_session_artifact_url: any;
     } | null;
     shipReport: any;
     checkpointContract: Record<string, unknown>;
@@ -674,6 +695,9 @@ declare function executeWorkflow(params: WorkflowParams, pluginConfig: any, reso
         last_requested_advance_stage: any;
         recon_results: any;
         verify_results: any;
+        proof_session: any;
+        parent_proof_session: any;
+        proof_session_artifact_url: any;
     } | null;
     approval: null;
     autoApproved: any;