@riddledc/riddle-proof 0.5.12 → 0.5.14

package/package.json

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

package/runtime/lib/recon.py

@@ -244,7 +244,7 @@ def score_route_candidate(path, tokens):
 def choose_target_path(explicit_path, prod_url, route_hints, tokens=None, explicit_source=''):
     explicit = (explicit_path or '').strip()
     explicit_source = (explicit_source or '').strip()
-    is_meaningful_explicit = bool(explicit) and (explicit != '/' or explicit_source in ('user', 'tool_param', 'supervising_agent'))
+    is_meaningful_explicit = bool(explicit) and (explicit != '/' or bool(explicit_source))
     if is_meaningful_explicit:
         return explicit if explicit.startswith('/') else '/' + explicit
     candidates = route_candidates(route_hints, prod_url)
@@ -719,7 +719,7 @@ initial_target_path = choose_target_path(s.get('server_path', ''), s.get('prod_u
 selected_route = next((item for item in route_options if item.get('path') == initial_target_path), None)
 initial_hypothesis = {
     'target_path': initial_target_path,
-    'path_source': 'state.server_path' if (s.get('server_path') or '').strip() and (s.get('server_path') != '/' or server_path_source) else ((selected_route or {}).get('reason') or 'fallback root'),
+    'path_source': ('state.server_path:' + server_path_source) if (s.get('server_path') or '').strip() and (s.get('server_path') != '/' or server_path_source) else ((selected_route or {}).get('reason') or 'fallback root'),
     'reference': requested_reference,
     'mode': s.get('mode', 'server'),
     'wait_for_selector': (s.get('wait_for_selector') or '').strip(),
@@ -783,6 +783,25 @@ elif plan_history:
         'changes': diff_plan(plan_history[-1], current_plan),
         'reason': 'Resumed recon with the current state inputs.',
     })
+
+capture_hint = s.get('capture_hint') if isinstance(s.get('capture_hint'), dict) else {}
+selected_hint = capture_hint.get('selected') if isinstance(capture_hint.get('selected'), dict) else {}
+if capture_hint.get('applied') and selected_hint:
+    fallback_changes = {}
+    hinted_path = str(selected_hint.get('server_path') or '').strip()
+    hinted_selector = str(selected_hint.get('wait_for_selector') or '').strip()
+    if hinted_path and current_plan.get('target_path') != hinted_path:
+        fallback_changes['server_path'] = {'from': hinted_path, 'to': current_plan.get('target_path')}
+    if hinted_selector and current_plan.get('wait_for_selector') != hinted_selector:
+        fallback_changes['wait_for_selector'] = {'from': hinted_selector, 'to': current_plan.get('wait_for_selector')}
+    if fallback_changes:
+        capture_hint['fallback_triggered'] = True
+        capture_hint['fallback_reason'] = (
+            str(previous_assessment.get('decision') or '').strip() if has_previous_assessment else 'plan_refined'
+        ) or 'plan_refined'
+        capture_hint['fallback_changes'] = fallback_changes
+        s['capture_hint'] = capture_hint
+
 plan_history.append(current_plan)
 
 summary_bits = []

package/runtime/lib/setup.py

@@ -9,6 +9,7 @@ local temp storage by default:
 import json, subprocess as sp, os, sys, shutil, time, tempfile
 sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
 from util import load_state, save_state, git, shell_quote
+from util import apply_capture_hint
 
 s = load_state()
 repo = s['repo']
@@ -474,6 +475,9 @@ s['branch'] = branch
 s['target_branch'] = target_branch
 s['ship_target_branch'] = target_branch
 s['worktree_root'] = WORKTREE_ROOT
+capture_hint = apply_capture_hint(s)
+if capture_hint and capture_hint.get('applied_fields'):
+    print('Applied last-good capture hint: ' + ', '.join(capture_hint.get('applied_fields') or []))
 save_state(s)
 print('Prepared workspace via ' + setup.get('source', 'workspace_core') + ': ' + repo_dir)
 os.makedirs(WORKTREE_ROOT, exist_ok=True)

package/runtime/lib/util.py

@@ -1,6 +1,6 @@
 """Shared helpers for Riddle Proof pipeline."""
 
-import json, subprocess as sp, os, shlex, time
+import hashlib, json, os, re, shlex, subprocess as sp, tempfile, time
 from urllib.parse import urljoin
 from urllib.request import urlopen
 
@@ -18,6 +18,8 @@ CAPTURE_ARTIFACT_JSON_LIMIT = 256 * 1024
 _JSON_ARTIFACT_CACHE = {}
 CAPTURE_DIAGNOSTIC_VERSION = 'riddle-proof.capture-diagnostic.v1'
 DEBUG_STRING_LIMIT = 2000
+CAPTURE_HINT_CACHE_VERSION = 'riddle-proof.capture-hints.v1'
+CAPTURE_HINT_CACHE_LIMIT = 12
 SENSITIVE_KEY_FRAGMENTS = (
     'authorization',
     'apikey',
@@ -29,6 +31,14 @@ SENSITIVE_KEY_FRAGMENTS = (
     'secret',
     'token',
 )
+HINT_TOKEN_STOPWORDS = {
+    'about', 'after', 'agent', 'agents', 'around', 'before', 'browser', 'change',
+    'changes', 'clarify', 'component', 'copy', 'debug', 'default', 'evidence',
+    'flow', 'homepage', 'improve', 'just', 'main', 'make', 'need', 'normal',
+    'page', 'proof', 'report', 'results', 'review', 'run', 'screen', 'script',
+    'small', 'status', 'text', 'tiny', 'update', 'user', 'verify', 'visible',
+    'workflow',
+}
 
 
 def load_state():
@@ -41,6 +51,206 @@ def save_state(s):
         json.dump(s, f, indent=2)
 
 
+def request_shape_tokens(state, limit=8):
+    haystack = ' '.join([
+        str(state.get('change_request') or ''),
+        str(state.get('context') or ''),
+        str(state.get('success_criteria') or ''),
+    ]).lower()
+    tokens = []
+    for word in re.findall(r'[a-z0-9]+', haystack):
+        if len(word) < 4 or word in HINT_TOKEN_STOPWORDS or word in tokens:
+            continue
+        tokens.append(word)
+        if len(tokens) >= limit:
+            break
+    return tokens
+
+
+def capture_hint_cache_path(state):
+    repo_key = str(state.get('repo') or state.get('repo_dir') or '').strip()
+    if not repo_key:
+        return ''
+    digest = hashlib.sha1(repo_key.encode('utf-8')).hexdigest()
+    return os.path.join(tempfile.gettempdir(), '.riddle-proof-capture-hints', digest + '.json')
+
+
+def load_capture_hint_cache(state):
+    cache_path = capture_hint_cache_path(state)
+    if not cache_path or not os.path.exists(cache_path):
+        return ({'version': CAPTURE_HINT_CACHE_VERSION, 'hints': []}, cache_path)
+    try:
+        with open(cache_path) as f:
+            payload = json.load(f)
+    except Exception:
+        return ({'version': CAPTURE_HINT_CACHE_VERSION, 'hints': []}, cache_path)
+    if not isinstance(payload, dict):
+        return ({'version': CAPTURE_HINT_CACHE_VERSION, 'hints': []}, cache_path)
+    hints = payload.get('hints') if isinstance(payload.get('hints'), list) else []
+    payload['version'] = CAPTURE_HINT_CACHE_VERSION
+    payload['hints'] = hints
+    return payload, cache_path
+
+
+def select_capture_hint(state):
+    payload, cache_path = load_capture_hint_cache(state)
+    hints = payload.get('hints') or []
+    current_tokens = request_shape_tokens(state)
+    current_mode = str(state.get('verification_mode') or '').strip().lower()
+    scored = []
+    for hint in hints:
+        if not isinstance(hint, dict):
+            continue
+        server_path = str(hint.get('server_path') or '').strip()
+        wait_for_selector = str(hint.get('wait_for_selector') or '').strip()
+        if not server_path and not wait_for_selector:
+            continue
+        hint_mode = str(hint.get('verification_mode') or '').strip().lower()
+        hint_tokens = [
+            str(item).strip().lower()
+            for item in (hint.get('request_tokens') or [])
+            if str(item).strip()
+        ]
+        matched_tokens = [token for token in current_tokens if token in hint_tokens]
+        score = len(matched_tokens) * 3
+        if current_mode and hint_mode == current_mode:
+            score += 2
+        if score <= 0:
+            continue
+        scored.append({
+            'score': score,
+            'matched_tokens': matched_tokens,
+            'selection_reason': 'token_overlap_and_mode' if matched_tokens and current_mode and hint_mode == current_mode else (
+                'token_overlap' if matched_tokens else 'verification_mode_match'
+            ),
+            'hint': hint,
+        })
+
+    if not scored:
+        return None
+
+    scored.sort(
+        key=lambda item: (
+            int(item['score']),
+            str(item['hint'].get('saved_at') or ''),
+        ),
+        reverse=True,
+    )
+    selected = scored[0]
+    return {
+        'cache_path': cache_path,
+        'available_count': len(hints),
+        'score': selected['score'],
+        'matched_tokens': selected['matched_tokens'],
+        'selection_reason': selected['selection_reason'],
+        'hint': selected['hint'],
+    }
+
+
+def apply_capture_hint(state):
+    selected = select_capture_hint(state)
+    if not selected:
+        return None
+
+    hint = selected['hint']
+    applied_fields = []
+    server_path = str(hint.get('server_path') or '').strip()
+    wait_for_selector = str(hint.get('wait_for_selector') or '').strip()
+
+    if server_path and not str(state.get('server_path') or '').strip():
+        state['server_path'] = server_path
+        state['server_path_source'] = 'hint_cache'
+        applied_fields.append('server_path')
+    if wait_for_selector and not str(state.get('wait_for_selector') or '').strip():
+        state['wait_for_selector'] = wait_for_selector
+        state['wait_for_selector_source'] = 'hint_cache'
+        applied_fields.append('wait_for_selector')
+
+    if not applied_fields:
+        return None
+
+    state['capture_hint'] = {
+        'source': 'hint_cache',
+        'cache_path': selected['cache_path'],
+        'applied': True,
+        'applied_fields': applied_fields,
+        'matched_tokens': selected['matched_tokens'],
+        'selection_reason': selected['selection_reason'],
+        'available_count': selected['available_count'],
+        'selected': {
+            'saved_at': str(hint.get('saved_at') or ''),
+            'verification_mode': str(hint.get('verification_mode') or ''),
+            'server_path': server_path,
+            'wait_for_selector': wait_for_selector,
+            'observed_path': str(hint.get('observed_path') or ''),
+            'proof_profile_name': str(hint.get('proof_profile_name') or ''),
+            'request_tokens': hint.get('request_tokens') or [],
+        },
+        'fallback_triggered': False,
+    }
+    return state['capture_hint']
+
+
+def record_successful_capture_hint(state, server_path='', wait_for_selector='', observed_path='', source_stage='verify', success_signal=''):
+    server_path = str(server_path or '').strip()
+    wait_for_selector = str(wait_for_selector or '').strip()
+    if not server_path and not wait_for_selector:
+        return {'status': 'skipped_missing_inputs'}
+
+    payload, cache_path = load_capture_hint_cache(state)
+    hints = payload.get('hints') or []
+    request_tokens = request_shape_tokens(state)
+    entry = {
+        'saved_at': time.strftime('%Y-%m-%dT%H:%M:%SZ', time.gmtime()),
+        'verification_mode': str(state.get('verification_mode') or '').strip().lower(),
+        'request_tokens': request_tokens,
+        'request_sample': compact_debug_value(str(state.get('change_request') or '')[:240]),
+        'server_path': server_path,
+        'wait_for_selector': wait_for_selector,
+        'observed_path': str(observed_path or '').strip(),
+        'proof_profile_name': str(((state.get('proof_profile') or {}).get('name')) or '').strip(),
+        'source_stage': str(source_stage or '').strip(),
+        'success_signal': str(success_signal or '').strip(),
+    }
+
+    deduped = []
+    for hint in hints:
+        if not isinstance(hint, dict):
+            continue
+        if (
+            str(hint.get('verification_mode') or '').strip().lower() == entry['verification_mode']
+            and str(hint.get('server_path') or '').strip() == entry['server_path']
+            and str(hint.get('wait_for_selector') or '').strip() == entry['wait_for_selector']
+            and list(hint.get('request_tokens') or []) == entry['request_tokens']
+        ):
+            continue
+        deduped.append(hint)
+
+    next_payload = {
+        'version': CAPTURE_HINT_CACHE_VERSION,
+        'repo': str(state.get('repo') or state.get('repo_dir') or '').strip(),
+        'updated_at': entry['saved_at'],
+        'hints': [entry] + deduped[:CAPTURE_HINT_CACHE_LIMIT - 1],
+    }
+    try:
+        os.makedirs(os.path.dirname(cache_path), exist_ok=True)
+        with open(cache_path, 'w') as f:
+            json.dump(next_payload, f, indent=2)
+    except Exception as exc:
+        return {
+            'status': 'error',
+            'cache_path': cache_path,
+            'error': str(exc)[:240],
+        }
+
+    return {
+        'status': 'saved',
+        'cache_path': cache_path,
+        'entry': entry,
+        'hint_count': len(next_payload['hints']),
+    }
+
+
 def compact_debug_value(value, limit=DEBUG_STRING_LIMIT):
     if isinstance(value, str) and len(value) > limit:
         return value[:limit] + '... [truncated]'

package/runtime/lib/verify.py

@@ -19,6 +19,7 @@ from util import (
     invoke_retry,
     load_state,
     prepare_server_preview,
+    record_successful_capture_hint,
     save_state,
     should_use_static_preview,
     summarize_capture_artifacts,
@@ -1139,6 +1140,16 @@ if proof_evidence_required_for_mode(s.get('verification_mode')):
 
 has_good_evidence = required_baseline_present and after_observation.get('valid') and not proof_evidence_blocker
 
+if has_good_evidence:
+    s['capture_hint_saved'] = record_successful_capture_hint(
+        s,
+        server_path=expected_path or s.get('server_path') or '/',
+        wait_for_selector=s.get('wait_for_selector') or '',
+        observed_path=observed_path,
+        source_stage='verify',
+        success_signal='evidence_captured',
+    )
+
 if has_good_evidence:
     supervisor_request = build_supervisor_assessment_request(s, after_payload, after_observation, required_baseline_present, expected_path, evidence_bundle)
     s['verify_status'] = 'evidence_captured'

package/runtime/tests/recon_verify_smoke.py

@@ -207,6 +207,30 @@ class FakeRiddle:
                         'largeVisibleElements': [{'tag': 'button', 'text': 'Reset Game'}],
                     }),
                 }
+            if (
+                'preview.example.com' in script
+                and '/pricing' not in script
+                and '/games/tic-tac-toe' not in script
+                and '/wrong' not in script
+            ):
+                return {
+                    'ok': True,
+                    'screenshots': [{'url': 'https://cdn.example.com/home-before.png'}],
+                    'outputs': [{'name': 'before.png', 'url': 'https://cdn.example.com/home-before.png'}],
+                    'console': state_console({
+                        'bodyTextLength': 180,
+                        'visibleTextSample': 'Riddle Proof homepage hero Start Free',
+                        'interactiveElements': 4,
+                        'visibleInteractiveElements': 4,
+                        'pathname': '/',
+                        'title': 'Riddle',
+                        'buttons': ['Start Free'],
+                        'headings': ['Riddle Proof'],
+                        'links': [],
+                        'canvasCount': 0,
+                        'largeVisibleElements': [{'tag': 'button', 'text': 'Start Free'}],
+                    }),
+                }
             raise AssertionError(f'unexpected riddle_script payload: {script}')
         raise AssertionError(f'unexpected invoke_retry tool: {tool}')
 
@@ -581,6 +605,53 @@ def run_recon_prefers_route_literals_over_import_paths():
         shutil.rmtree(tempdir, ignore_errors=True)
 
 
+def run_recon_prefers_hint_root_over_single_route_literal():
+    tempdir = Path(tempfile.mkdtemp(prefix='riddle-proof-hint-root-'))
+    state_path = tempdir / 'state.json'
+    try:
+        route_snippet = "export const routes = [{ path: '/docs/riddle-proof/markdown', element: <Docs /> }];\n"
+        state = base_state(tempdir, reference='before')
+        make_project(tempdir / 'before', route_snippet)
+        make_project(tempdir / 'after', route_snippet)
+        state.update({
+            'server_path': '/',
+            'server_path_source': 'hint_cache',
+            'capture_hint': {
+                'source': 'hint_cache',
+                'applied_fields': ['server_path'],
+                'selected': {'server_path': '/'},
+            },
+            'change_request': 'Make a tiny harmless homepage copy tweak',
+            'success_criteria': 'The homepage hero copy reflects the tiny tweak.',
+        })
+        write_state(state_path, state)
+        os.environ['RIDDLE_PROOF_STATE_FILE'] = str(state_path)
+
+        fake = FakeRiddle()
+        load_util_with_fake(fake)
+        load_module('recon_hint_root_preference', RECON_PATH)
+        after_recon = json.loads(state_path.read_text())
+
+        current_plan = after_recon['recon_results']['current_plan']
+        candidate_paths = [item['path'] for item in current_plan['route_candidates']]
+        assert current_plan['target_path'] == '/', current_plan
+        assert current_plan['path_source'] == 'state.server_path:hint_cache', current_plan
+        assert '/docs/riddle-proof/markdown' in candidate_paths, candidate_paths
+        details = after_recon['recon_results']['attempt_history'][-1]['observations']['before']['details']
+        assert details['observed_path'] == '/'
+        assert 'Start Free' in details['visible_text_sample'], details
+        assert details['buttons'] == ['Start Free'], details
+
+        return {
+            'ok': True,
+            'target_path': current_plan['target_path'],
+            'path_source': current_plan['path_source'],
+            'candidate_paths': candidate_paths,
+        }
+    finally:
+        shutil.rmtree(tempdir, ignore_errors=True)
+
+
 def run_author_applies_supervisor_packet():
     tempdir = Path(tempfile.mkdtemp(prefix='riddle-proof-supervisor-apply-'))
     state_path = tempdir / 'state.json'
@@ -1182,6 +1253,7 @@ if __name__ == '__main__':
         '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(),
+        'recon_hint_root_preference': run_recon_prefers_hint_root_over_single_route_literal(),
         'author_applies_supervisor_packet': run_author_applies_supervisor_packet(),
         'verify_requests_supervisor_assessment': run_verify_requests_supervisor_assessment(),
         'verify_structured_evidence_without_screenshot': run_verify_structured_evidence_without_screenshot(),