@riddledc/riddle-proof 0.5.31 → 0.5.33

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";
     }
@@ -862,7 +865,7 @@ async function executeWorkflow(params, pluginConfig, resolvedConfig) {
     }
     state = readState(config.statePath);
     const continuedStage = params.continue_from_checkpoint ? checkpointContinueStage(state) : null;
-    if (params.continue_from_checkpoint && !continuedStage) {
+    if (params.continue_from_checkpoint && !params.advance_stage && !continuedStage) {
       const recommended = recommendedAdvanceStage(state);
       return checkpoint(
         state?.active_checkpoint_stage || recommended || "recon",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@riddledc/riddle-proof",
-  "version": "0.5.31",
+  "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')):

package/runtime/tests/recon_verify_smoke.py

@@ -1200,17 +1200,19 @@ def run_verify_requests_supervisor_assessment():
         artifact_contract = after_verify['proof_assessment_request']['artifact_contract']
         assert artifact_contract['required']['baseline_context'] is True
         assert artifact_contract['required']['screenshot'] is True
+        assert artifact_contract['required']['visual_delta'] is True
         artifact_production = after_verify['proof_assessment_request']['artifact_production']
         assert artifact_production['image_output_count'] >= 1
         assert artifact_production['proof_evidence_present'] is False
         artifact_usage = after_verify['proof_assessment_request']['artifact_usage']
-        assert artifact_usage['missing_required_signals'] == []
+        assert artifact_usage['missing_required_signals'] == ['visual_delta']
         assert 'after-capture' in artifact_usage['supervisor_review_signals']
         assert 'baseline_context' in artifact_usage['required_signals']
         assert 'route_semantics' in artifact_usage['available_signals']
+        assert 'visual_delta.status=unmeasured' in after_verify['proof_assessment_request']['hard_blockers'][0]
         assert after_verify['proof_assessment_request']['evidence_bundle']['artifact_contract']['required']['screenshot'] is True
         assert after_verify['proof_assessment_request']['evidence_bundle']['artifact_production']['image_output_count'] >= 1
-        assert after_verify['proof_assessment_request']['evidence_bundle']['artifact_usage']['missing_required_signals'] == []
+        assert after_verify['proof_assessment_request']['evidence_bundle']['artifact_usage']['missing_required_signals'] == ['visual_delta']
         assert 'capture success is not proof' in '\n'.join(after_verify['proof_assessment_request']['instructions'])
         assert after_verify['verify_decision_request']['continue_with_stage'] is None
         assert after_verify['verify_results']['baseline']['before']['source'] == 'recon'
@@ -1573,6 +1575,62 @@ def run_ship_missing_supervisor_gate():
         shutil.rmtree(tempdir, ignore_errors=True)
 
 
+def run_ship_blocks_unmeasured_visual_delta():
+    tempdir = Path(tempfile.mkdtemp(prefix='riddle-proof-ship-visual-delta-'))
+    state_path = tempdir / 'state.json'
+    try:
+        state = base_state(tempdir, reference='before')
+        state.update({
+            'recon_status': 'ready_for_proof_plan',
+            'author_status': 'ready',
+            'proof_plan_status': 'ready',
+            'implementation_status': 'changes_detected',
+            'verification_mode': 'visual',
+            'verify_status': 'evidence_captured',
+            'before_cdn': 'https://cdn.example.com/before.png',
+            'after_cdn': 'https://cdn.example.com/after.png',
+            'proof_assessment': {
+                'decision': 'ready_to_ship',
+                'summary': 'The screenshots look good.',
+                'source': 'supervising_agent',
+            },
+            'proof_assessment_source': 'supervising_agent',
+            'evidence_bundle': {
+                'verification_mode': 'visual',
+                'artifact_contract': {
+                    'required': {
+                        'baseline_context': True,
+                        'route_semantics': True,
+                        'screenshot': True,
+                        'visual_delta': True,
+                    },
+                },
+                'after': {
+                    'screenshot_url': 'https://cdn.example.com/after.png',
+                    'observation': {'valid': True, 'reason': 'ok'},
+                    'visual_delta': {
+                        'status': 'unmeasured',
+                        'passed': None,
+                        'reason': 'No measured before/after visual delta was found in proof evidence.',
+                    },
+                },
+            },
+        })
+        write_state(state_path, state)
+        os.environ['RIDDLE_PROOF_STATE_FILE'] = str(state_path)
+
+        try:
+            load_module('ship_blocks_unmeasured_visual_delta', SHIP_PATH)
+        except SystemExit as exc:
+            message = str(exc)
+            assert 'visual_delta.status=unmeasured' in message, message
+            assert 'blocks ready_to_ship' in message, message
+            return {'ok': True, 'error': message}
+        raise AssertionError('ship should have failed when visual delta was unmeasured')
+    finally:
+        shutil.rmtree(tempdir, ignore_errors=True)
+
+
 def run_ship_accepts_structured_after_evidence():
     tempdir = Path(tempfile.mkdtemp(prefix='riddle-proof-ship-structured-'))
     state_path = tempdir / 'state.json'
@@ -1829,6 +1887,7 @@ if __name__ == '__main__':
         'verify_capture_retry': run_verify_capture_retry(),
         'missing_baseline_guard': run_verify_missing_baseline(),
         'ship_supervisor_gate': run_ship_missing_supervisor_gate(),
+        'ship_blocks_unmeasured_visual_delta': run_ship_blocks_unmeasured_visual_delta(),
         'ship_structured_after_evidence': run_ship_accepts_structured_after_evidence(),
         'ship_discord_thread_target': run_ship_discord_thread_target(),
         'ship_filters_tool_noise_when_staging': run_ship_filters_tool_noise_when_staging(),