@riddledc/riddle-proof 0.5.15 → 0.5.17

package/package.json

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

package/runtime/lib/util.py

@@ -566,6 +566,41 @@ def git(cmd, cwd):
     return sp.run(cmd, shell=True, cwd=cwd, capture_output=True, text=True)
 
 
+def run_project_build(project_dir, build_cmd, timeout=600, clean_cache_dir='.next'):
+    """Build once with existing cache, then retry clean if the cached build fails."""
+    attempts = []
+    for clean_first in (False, True):
+        if clean_first and clean_cache_dir:
+            cache_path = os.path.join(project_dir, clean_cache_dir)
+            if os.path.exists(cache_path):
+                sp.run(
+                    'rm -rf ' + shell_quote(clean_cache_dir),
+                    shell=True,
+                    cwd=project_dir,
+                    capture_output=True,
+                    text=True,
+                )
+        result = sp.run(build_cmd, shell=True, cwd=project_dir, capture_output=True, text=True, timeout=timeout)
+        attempts.append({
+            'clean_first': clean_first,
+            'returncode': int(result.returncode),
+            'stderr': (result.stderr or '')[:500],
+        })
+        if result.returncode == 0:
+            return {
+                'result': result,
+                'clean_retry_used': clean_first,
+                'attempts': attempts,
+            }
+        if not clean_cache_dir or clean_first:
+            break
+    return {
+        'result': result,
+        'clean_retry_used': False,
+        'attempts': attempts,
+    }
+
+
 def load_package_json(project_dir):
     package_json = os.path.join(project_dir, 'package.json')
     if not os.path.exists(package_json):

package/runtime/lib/verify.py

@@ -20,6 +20,7 @@ from util import (
     load_state,
     prepare_server_preview,
     record_successful_capture_hint,
+    run_project_build,
     save_state,
     should_use_static_preview,
     summarize_capture_artifacts,
@@ -624,6 +625,111 @@ def collect_supporting_artifacts(payload):
     }
 
 
+def artifact_contract_for_mode(verification_mode):
+    mode = normalized_verification_mode(verification_mode)
+    return {
+        'verification_mode': mode,
+        'required': {
+            'baseline_context': True,
+            'route_semantics': True,
+            'screenshot': screenshot_required_for_mode(mode),
+            'proof_evidence': proof_evidence_required_for_mode(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,
+            'json_artifacts': True,
+            'image_outputs': True,
+        },
+    }
+
+
+def artifact_production_summary(payload, supporting):
+    artifact_summary = summarize_capture_artifacts(payload)
+    return {
+        'output_names': [str(item.get('name') or '') for item in (artifact_summary.get('outputs') or [])[:20]],
+        'screenshot_names': [str(item.get('name') or '') for item in (artifact_summary.get('screenshots') or [])[:10]],
+        'artifact_json': list(artifact_summary.get('artifact_json') or []),
+        'artifact_error_names': sorted((artifact_summary.get('artifact_errors') or {}).keys()),
+        'image_output_count': len(supporting.get('image_outputs') or []),
+        'data_output_count': len(supporting.get('data_outputs') or []),
+        'other_output_count': len(supporting.get('other_outputs') or []),
+        'console_entries': int(supporting.get('console_entries') or 0),
+        'structured_result_keys': list(supporting.get('structured_result_keys') or []),
+        'proof_evidence_present': bool(supporting.get('proof_evidence_present')),
+        'has_structured_payload': bool(supporting.get('has_structured_payload')),
+    }
+
+
+def artifact_signal_availability(state, after_observation, supporting, visual_delta, required_baseline_present, semantic_context):
+    details = (after_observation or {}).get('details') or {}
+    route = (semantic_context or {}).get('route') or {}
+    return {
+        'baseline_context': bool(required_baseline_present),
+        'route_semantics': bool(route.get('after_observed_path') or details.get('observed_path')),
+        'screenshot': bool(details.get('has_screenshot')),
+        'page_state': bool(
+            details.get('visible_text_sample')
+            or details.get('headings')
+            or details.get('buttons')
+            or details.get('links')
+            or details.get('semantic_anchor_count')
+        ),
+        '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')),
+        'console_summary': bool(supporting.get('console_entries')),
+        'json_artifacts': bool(supporting.get('data_outputs')),
+        'image_outputs': bool(supporting.get('image_outputs')),
+        'assertions': bool(state.get('parsed_assertions')),
+        'success_criteria': bool((state.get('success_criteria') or '').strip()),
+    }
+
+
+def artifact_usage_summary(state, after_observation, supporting, visual_delta, required_baseline_present, semantic_context, evidence_basis):
+    contract = artifact_contract_for_mode(state.get('verification_mode'))
+    available = artifact_signal_availability(
+        state,
+        after_observation,
+        supporting,
+        visual_delta,
+        required_baseline_present,
+        semantic_context,
+    )
+    capture_quality = []
+    details = (after_observation or {}).get('details') or {}
+    if details.get('has_screenshot'):
+        capture_quality.append('screenshot')
+    if available.get('page_state'):
+        capture_quality.append('page_state')
+    if available.get('console_summary'):
+        capture_quality.append('console_summary')
+    if available.get('structured_payload'):
+        capture_quality.append('structured_payload')
+    if available.get('proof_evidence'):
+        capture_quality.append('proof_evidence')
+    if available.get('visual_delta'):
+        capture_quality.append('visual_delta')
+
+    required_signals = [key for key, enabled in (contract.get('required') or {}).items() if enabled]
+    preferred_signals = [key for key, enabled in (contract.get('preferred') or {}).items() if enabled]
+    optional_signals = [key for key, enabled in (contract.get('optional') or {}).items() if enabled]
+
+    return {
+        'required_signals': required_signals,
+        'preferred_signals': preferred_signals,
+        'optional_signals': optional_signals,
+        'available_signals': [key for key, enabled in available.items() if enabled],
+        'missing_required_signals': [key for key in required_signals if not available.get(key)],
+        'capture_quality_signals': capture_quality,
+        'supervisor_review_signals': list(evidence_basis or []),
+    }
+
+
 def evaluate_capture_quality(payload, expected_path, verification_mode='proof'):
     payload = enrich_capture_payload(payload)
     mode = normalized_verification_mode(verification_mode)
@@ -862,6 +968,17 @@ def build_evidence_bundle(state, results, after_payload, after_observation, requ
         else {'status': 'not_applicable', 'passed': None, 'reason': 'Verification mode does not require visual delta gating.'}
     )
     semantic_context = build_semantic_context(state, results, after_observation, expected_path)
+    artifact_contract = artifact_contract_for_mode(state.get('verification_mode'))
+    artifact_production = artifact_production_summary(after_payload, supporting)
+    artifact_usage = artifact_usage_summary(
+        state,
+        after_observation,
+        supporting,
+        visual_delta,
+        required_baseline_present,
+        semantic_context,
+        [],
+    )
     return {
         'verification_mode': normalized_verification_mode(state.get('verification_mode')),
         'reference': state.get('requested_reference') or state.get('reference', 'both'),
@@ -869,6 +986,9 @@ def build_evidence_bundle(state, results, after_payload, after_observation, requ
         'required_baseline_present': required_baseline_present,
         'baseline': results.get('baseline') or {},
         'semantic_context': semantic_context,
+        'artifact_contract': artifact_contract,
+        'artifact_production': artifact_production,
+        'artifact_usage': artifact_usage,
         'after': {
             'screenshot_url': state.get('after_cdn') or '',
             'observation': after_observation,
@@ -909,6 +1029,26 @@ def build_supervisor_assessment_request(state, payload, after_observation, requi
     if has_success_criteria:
         evidence_basis.append('success-criteria')
 
+    artifact_contract = (evidence_bundle or {}).get('artifact_contract') if isinstance(evidence_bundle, dict) else None
+    if not isinstance(artifact_contract, dict):
+        artifact_contract = artifact_contract_for_mode(verification_mode)
+    artifact_production = (evidence_bundle or {}).get('artifact_production') if isinstance(evidence_bundle, dict) else None
+    if not isinstance(artifact_production, dict):
+        artifact_production = artifact_production_summary(payload, supporting)
+    artifact_usage = artifact_usage_summary(
+        state,
+        after_observation,
+        supporting,
+        visual_delta,
+        required_baseline_present,
+        semantic_context,
+        evidence_basis,
+    )
+    if isinstance(evidence_bundle, dict):
+        evidence_bundle['artifact_contract'] = artifact_contract
+        evidence_bundle['artifact_production'] = artifact_production
+        evidence_bundle['artifact_usage'] = artifact_usage
+
     return {
         'status': 'needs_supervising_agent_assessment',
         'verification_mode': verification_mode,
@@ -920,6 +1060,9 @@ def build_supervisor_assessment_request(state, payload, after_observation, requi
         'semantic_context': semantic_context,
         'evidence_bundle': evidence_bundle or {},
         'evidence_basis': evidence_basis,
+        'artifact_contract': artifact_contract,
+        'artifact_production': artifact_production,
+        'artifact_usage': artifact_usage,
         '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.',
@@ -1028,14 +1171,17 @@ if existing_prod:
 
 # AFTER (always from after worktree)
 record_verify_phase('build', 'running', 'Building after worktree for verify capture.')
-print('Cleaning after .next cache...')
-sp.run('rm -rf .next', shell=True, cwd=after_dir, capture_output=True)
-
 print('Building after worktree...')
-br = sp.run(build_cmd, shell=True, cwd=after_dir, capture_output=True, text=True, timeout=600)
+build_attempt = run_project_build(after_dir, build_cmd, timeout=600, clean_cache_dir='.next')
+br = build_attempt.get('result')
+if build_attempt.get('clean_retry_used'):
+    print('Verify build recovered after cleaning .next cache.')
 if br.returncode != 0:
     record_verify_phase('build', 'failed', 'After build failed: ' + br.stderr[:300])
     raise SystemExit('After build failed: ' + br.stderr[:500])
+if build_attempt.get('attempts'):
+    s['verify_build_attempts'] = build_attempt['attempts']
+    s['verify_build_clean_retry_used'] = bool(build_attempt.get('clean_retry_used'))
 record_verify_phase('build', 'completed', 'After worktree build completed.')
 
 after_payload = {}

package/runtime/tests/recon_verify_smoke.py

@@ -508,6 +508,38 @@ def base_state(tempdir: Path, *, reference='before', prod_url=''):
     }
 
 
+def run_project_build_retries_after_clean_failure():
+    tempdir = Path(tempfile.mkdtemp(prefix='riddle-proof-build-retry-'))
+    cache_dir = tempdir / '.next'
+    cache_dir.mkdir(parents=True, exist_ok=True)
+    util = load_module('util_build_retry', UTIL_PATH)
+    original_run = util.sp.run
+    calls = []
+
+    def fake_run(cmd, *args, **kwargs):
+        calls.append(cmd)
+        if cmd == 'npm run build':
+            build_attempts = calls.count('npm run build')
+            if build_attempts == 1:
+                return sp.CompletedProcess(cmd, 1, '', 'stale cache')
+            return sp.CompletedProcess(cmd, 0, 'ok', '')
+        if cmd == 'rm -rf .next':
+            shutil.rmtree(cache_dir, ignore_errors=True)
+            return sp.CompletedProcess(cmd, 0, '', '')
+        raise AssertionError(f'unexpected command: {cmd}')
+
+    try:
+        util.sp.run = fake_run
+        result = util.run_project_build(str(tempdir), 'npm run build', timeout=30, clean_cache_dir='.next')
+        assert result['clean_retry_used'] is True
+        assert result['result'].returncode == 0
+        assert calls == ['npm run build', 'rm -rf .next', 'npm run build']
+        assert not cache_dir.exists()
+    finally:
+        util.sp.run = original_run
+        shutil.rmtree(tempdir)
+
+
 def run_recon_then_author_request():
     tempdir = Path(tempfile.mkdtemp(prefix='riddle-proof-supervisor-request-'))
     state_path = tempdir / 'state.json'
@@ -758,6 +790,20 @@ def run_verify_requests_supervisor_assessment():
         assert semantic_context['after']['headings'] == ['Pricing'], semantic_context
         assert 'semantic-context' in after_verify['proof_assessment_request']['evidence_basis']
         assert after_verify['proof_assessment_request']['evidence_bundle']['semantic_context']['after']['buttons'] == ['Buy Now']
+        artifact_contract = after_verify['proof_assessment_request']['artifact_contract']
+        assert artifact_contract['required']['baseline_context'] is True
+        assert artifact_contract['required']['screenshot'] 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 '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 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 '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'
@@ -1257,6 +1303,7 @@ if __name__ == '__main__':
         'capture_artifact_enrichment': run_capture_artifact_enrichment(),
         'capture_diagnostics_redaction': run_capture_diagnostics_redact_sensitive_values(),
         'apply_auth_context': run_apply_auth_context_passes_supported_auth_payloads(),
+        'run_project_build_retries_after_clean_failure': run_project_build_retries_after_clean_failure(),
         'verify_quality_ignores_proof_telemetry_console_text': run_verify_quality_ignores_proof_telemetry_console_text(),
         'recon_then_author_request': run_recon_then_author_request(),
         'recon_route_literal_preference': run_recon_prefers_route_literals_over_import_paths(),