@trac3er/oh-my-god 2.1.9 → 2.2.3

package/hooks/firewall.py

@@ -26,6 +26,8 @@ setup_crash_handler("firewall", fail_closed=True)
 
 try:
     from policy_engine import evaluate_bash_command, to_pretool_hook_output, scan_mutation_command, ask, deny  # pyright: ignore[reportImplicitRelativeImport]
+    from runtime.compliance_governor import classify_bash_command_mode
+    from runtime.context_engine import _extract_clarification
     from runtime.defense_state import DefenseState
     from runtime.session_health import compute_session_health
     from runtime.mutation_gate import check_mutation_allowed
@@ -125,47 +127,17 @@ def _read_council_signal(project_dir: str, run_id: str) -> str:
 
 def _read_clarification_state(project_dir: str, run_id: str) -> dict[str, object]:
     if not run_id:
-        return {
-            "requires_clarification": False,
-            "intent_class": "",
-            "clarification_prompt": "",
-            "confidence": 0.0,
-        }
+        return _extract_clarification({})
     path = Path(project_dir) / ".omg" / "state" / "intent_gate" / f"{run_id}.json"
     if not path.exists():
-        return {
-            "requires_clarification": False,
-            "intent_class": "",
-            "clarification_prompt": "",
-            "confidence": 0.0,
-        }
+        return _extract_clarification({})
     try:
         payload = json.loads(path.read_text(encoding="utf-8"))
     except (OSError, json.JSONDecodeError):
-        return {
-            "requires_clarification": False,
-            "intent_class": "",
-            "clarification_prompt": "",
-            "confidence": 0.0,
-        }
+        return _extract_clarification({})
     if not isinstance(payload, dict):
-        return {
-            "requires_clarification": False,
-            "intent_class": "",
-            "clarification_prompt": "",
-            "confidence": 0.0,
-        }
-    prompt = " ".join(str(payload.get("clarification_prompt", "")).split())
-    try:
-        confidence = float(payload.get("confidence", 0.0))
-    except (TypeError, ValueError):
-        confidence = 0.0
-    return {
-        "requires_clarification": bool(payload.get("requires_clarification") is True),
-        "intent_class": str(payload.get("intent_class", "")).strip(),
-        "clarification_prompt": prompt,
-        "confidence": round(max(0.0, min(1.0, confidence)), 2),
-    }
+        return _extract_clarification({})
+    return _extract_clarification(payload)
 
 
 def _clarification_reason(clarification_prompt: str) -> str:
@@ -175,6 +147,18 @@ def _clarification_reason(clarification_prompt: str) -> str:
     return "Clarification required before mutation: provide the missing intent details."
 
 
+def _clarification_external_reason(clarification_prompt: str) -> str:
+    prompt = " ".join(str(clarification_prompt or "").split())
+    if prompt:
+        return f"Clarification required before external execution: {prompt}"
+    return "Clarification required before external execution: provide the missing intent details."
+
+
+def _strict_ambiguity_mode_enabled() -> bool:
+    token = str(os.environ.get("OMG_STRICT_AMBIGUITY_MODE", "1")).strip().lower()
+    return token not in {"0", "false", "off", "no"}
+
+
 def _to_float(value: Any, default: float) -> float:
     try:
         return float(value)
@@ -266,8 +250,11 @@ gate_result = check_mutation_allowed(
     run_id=run_id or None,
     metadata=metadata if isinstance(metadata, dict) else None,
 )
-is_mutation_capable = str(gate_result.get("reason", "")) != "tool is read-only for mutation gate"
+bash_mode = classify_bash_command_mode(cmd)
+is_mutation_capable = bash_mode == "mutation"
+is_external_execution = bash_mode == "external"
 clarification_state = _read_clarification_state(get_project_dir(), run_id)
+strict_ambiguity_mode = _strict_ambiguity_mode_enabled()
 if is_mutation_capable:
     defense_decision = _mutating_defense_decision(
         project_dir=get_project_dir(),
@@ -277,8 +264,12 @@ if is_mutation_capable:
     if defense_decision is not None:
         decision = defense_decision
 
-if clarification_state.get("requires_clarification") is True and is_mutation_capable:
-    deny_decision(_clarification_reason(str(clarification_state.get("clarification_prompt", ""))))
+if strict_ambiguity_mode and clarification_state.get("requires_clarification") is True and (is_mutation_capable or is_external_execution):
+    prompt = str(clarification_state.get("clarification_prompt", ""))
+    if is_external_execution:
+        deny_decision(_clarification_external_reason(prompt))
+    else:
+        deny_decision(_clarification_reason(prompt))
     sys.exit(0)
 
 if is_mutation_capable and gate_result.get("status") == "blocked":

package/hooks/pre-compact.py

@@ -32,6 +32,12 @@ except ImportError:
     except Exception:
         collect_protected_context = None
 
+try:
+    from runtime.context_limits import get_model_limits, compaction_trigger
+except Exception:
+    get_model_limits = None
+    compaction_trigger = None
+
 
 MAX_SNAPSHOT_BYTES = int(os.environ.get("OMG_PRECOMPACT_MAX_SNAPSHOT_BYTES", "262144"))
 GIT_DIFF_TIMEOUT_SEC = int(os.environ.get("OMG_PRECOMPACT_GIT_DIFF_TIMEOUT_SEC", "1"))
@@ -225,6 +231,51 @@ def _load_context_budget_config(project_dir):
     return defaults
 
 
+def _detect_model_id(data):
+    if isinstance(data, dict):
+        model = data.get("model")
+        if isinstance(model, dict):
+            for key in ("id", "display_name", "name"):
+                value = str(model.get(key, "") or "").strip()
+                if value:
+                    return value
+        elif isinstance(model, str) and model.strip():
+            return model.strip()
+
+        context = data.get("context")
+        if isinstance(context, dict):
+            nested_model = context.get("model")
+            if isinstance(nested_model, dict):
+                for key in ("id", "display_name", "name"):
+                    value = str(nested_model.get(key, "") or "").strip()
+                    if value:
+                        return value
+            elif isinstance(nested_model, str) and nested_model.strip():
+                return nested_model.strip()
+
+    for key in ("CLAUDE_MODEL", "OMG_MODEL_ID", "OPENAI_MODEL"):
+        value = os.environ.get(key, "").strip()
+        if value:
+            return value
+
+    return ""
+
+
+def _host_aware_compaction_threshold(data):
+    model_id = _detect_model_id(data)
+    if get_model_limits is not None and compaction_trigger is not None:
+        limits = get_model_limits(model_id)
+        trigger = int(compaction_trigger(model_id))
+    else:
+        limits = {"class_label": "128k-class"}
+        trigger = 80_000
+    return {
+        "model_id": model_id,
+        "class_label": str(limits.get("class_label", "128k-class")),
+        "trigger_tokens": trigger,
+    }
+
+
 # ---------------------------------------------------------------------------
 # Main hook execution (side-effects — only runs when invoked as script)
 # ---------------------------------------------------------------------------
@@ -236,6 +287,7 @@ def main():
         sys.exit(0)
 
     project_dir = _resolve_project_dir()
+    compaction_limits = _host_aware_compaction_threshold(data)
     ts = datetime.now().strftime("%Y%m%d_%H%M%S")
     state_dir = resolve_state_dir(project_dir, "state", "")
     snapshot_dir = os.path.join(state_dir, "snapshots", ts)
@@ -278,6 +330,12 @@ def main():
         f"# Handoff -- {datetime.now().strftime('%Y-%m-%d %H:%M')}",
         "Auto-generated before context compaction.",
     ]
+    model_label = compaction_limits["model_id"] or "unknown"
+    parts.append(
+        "## Compaction Budget\n"
+        f"Model: {model_label} ({compaction_limits['class_label']})\n"
+        f"Trigger: {compaction_limits['trigger_tokens']} tokens"
+    )
     if profile:
         parts.append("<!-- section: working-state -->")
         parts.append("## Project\n" + profile)
@@ -378,23 +436,28 @@ def main():
             if turns:
                 config = _load_context_budget_config(project_dir)
                 result = _apply_hybrid_summarization(turns, config)
+                summaries = result.get("summaries", [])
+                discarded_raw = result.get("discarded_count", 0)
+                discarded_count = discarded_raw if isinstance(discarded_raw, int) else 0
+                full_turns = result.get("full_turns", [])
                 # Format as additionalContext supplement
                 summary_parts = []
-                if result["summaries"]:
+                if isinstance(summaries, list) and summaries:
                     summary_parts.append("## Conversation Context (Hybrid Summary)")
-                    for s in result["summaries"]:
-                        summary_parts.append(s)
-                    if result["discarded_count"] > 0:
+                    for s in summaries:
+                        if isinstance(s, str):
+                            summary_parts.append(s)
+                    if discarded_count > 0:
                         summary_parts.append(
-                            f"({result['discarded_count']} oldest turns discarded — see memory/handoff)"
+                            f"({discarded_count} oldest turns discarded — see memory/handoff)"
                         )
-                    summary_text = "\n".join(summary_parts)
+                    _summary_text = "\n".join(summary_parts)
                     # Output as JSON if no protected context was already output
                     print(
                         f"[OMG pre-compact] Hybrid summarization: "
-                        f"{len(result['full_turns'])} full, "
-                        f"{len(result['summaries'])} batches, "
-                        f"{result['discarded_count']} discarded",
+                        f"{len(full_turns) if isinstance(full_turns, list) else 0} full, "
+                        f"{len(summaries)} batches, "
+                        f"{discarded_count} discarded",
                         file=sys.stderr,
                     )
     except Exception:

package/hooks/prompt-enhancer.py

@@ -258,6 +258,14 @@ def _build_intent_gate_state(prompt_text, payload):
     run_id = _resolve_run_id(payload, source_prompt_hash)
     signal_hits = _count_signals(INTENT_MAP[intent_class]["signals"], prompt_text)
     confidence = min(0.99, 0.76 + (signal_hits * 0.07) + (0.06 if intent_class == "ambiguous_config" else 0.0))
+    governance_payload = {}
+    if score_complexity is not None:
+        try:
+            governance_raw = score_complexity(prompt_text).get("governance")
+            if isinstance(governance_raw, dict):
+                governance_payload = governance_raw
+        except Exception:
+            governance_payload = {}
 
     return {
         "schema": "IntentGateClarificationState",
@@ -269,7 +277,7 @@ def _build_intent_gate_state(prompt_text, payload):
         "missing_slots": missing_slots,
         "clarification_prompt": clarification_prompt,
         "source_prompt_hash": source_prompt_hash,
-        "governance": score_complexity(prompt_text).get("governance", {}),
+        "governance": governance_payload,
         "updated_at": datetime.now(timezone.utc).isoformat(),
     }
 
@@ -310,6 +318,12 @@ if detected_intent in ("fix", "implement", "refactor"):
     parts.append(
         "@verify: After EVERY change run build/lint/test. Show exit code."
     )
+    methodology_run_id = _resolve_run_id(data, _hash_prompt(prompt))
+    parts.append(
+        "@methodology: "
+        f"run_id={methodology_run_id} require plan+lock+done_when before mutation; "
+        "verify done_when after run."
+    )
 
 _gov_payload: dict[str, object] | None = None
 if score_complexity is not None and detected_intent in (

package/hooks/stop_dispatcher.py

@@ -34,6 +34,7 @@ from hooks._common import (  # noqa: E402
     setup_crash_handler,
     should_skip_stop_hooks,
     STOP_CHECK_MAX_MS,
+    STOP_DISPATCHER_TOTAL_MAX_MS,
 )
 from hooks.state_migration import resolve_state_file  # noqa: E402
 
@@ -144,6 +145,14 @@ def _is_internal_control_path(file_path: str) -> bool:
     return any(p.lower() in fl for p in INTERNAL_CONTROL_PATH_PATTERNS)
 
 
+_RALPH_DEFAULT_TIMEOUT_MINUTES = 10
+
+
+def _watchdog_check(start_time):
+    """Return True if the dispatcher has exceeded its wall-clock budget."""
+    return (time.time() - start_time) >= (STOP_DISPATCHER_TOTAL_MAX_MS / 1000)
+
+
 try:
     from hooks.shadow_manager import has_recent_evidence  # type: ignore
 except Exception:  # intentional: optional feature — shadow_manager may not exist
@@ -636,7 +645,7 @@ def check_bare_done(data, project_dir):
 
 
 def _proof_chain_strict_enabled() -> bool:
-    return os.environ.get("OMG_PROOF_CHAIN_STRICT", "0").strip() == "1"
+    return os.environ.get("OMG_PROOF_CHAIN_STRICT", "1").strip() != "0"
 
 
 def _load_test_delta_from_evidence(project_dir: str, run_id: str | None) -> dict[str, object]:
@@ -728,7 +737,7 @@ def check_tdd_proof_chain(data, project_dir):
     advisories = data.setdefault("_stop_advisories", [])
     advisories.append(
         "[OMG advisory] tdd proof chain incomplete: active lock evidence or waiver artifact is missing. "
-        "Set OMG_PROOF_CHAIN_STRICT=1 to hard-block completion."
+        "Production default is fail-closed; OMG_PROOF_CHAIN_STRICT=0 downgrades to advisory."
     )
     return []
 
@@ -836,24 +845,63 @@ def format_ralph_block_reason(state, project_dir):
         f"If truly done, run: /OMG:ralph-stop"
     )
 
+def persist_ralph_question(project_dir, question_text):
+    """Persist a pending clarification question in the Ralph loop state.
+
+    Called when any hook or the context engine detects ambiguity during a
+    Ralph iteration.  The next stop-hook check will emit the question via
+    block_decision and end the turn — no tool action may proceed.
+    """
+    ralph_path = os.path.join(project_dir, ".omg", "state", "ralph-loop.json")
+    if not os.path.exists(ralph_path):
+        return
+    try:
+        with open(ralph_path, "r", encoding="utf-8") as f:
+            state = json.load(f)
+    except (json.JSONDecodeError, OSError):
+        return
+    state["question_pending"] = True
+    state["question_text"] = str(question_text).strip()[:500]
+    state["question_emitted_at"] = datetime.now(timezone.utc).isoformat()
+    atomic_json_write(ralph_path, state)
+
+
 def check_ralph_loop(project_dir, data):
+    """Check Ralph loop state and return (block_reasons, advisories, is_question).
+
+    When *is_question* is True the block is a clarification question and the
+    caller MUST use block_reason="clarification_required" so that the turn
+    ends without any further tool action.
+    """
     del data
 
     if not get_feature_flag("ralph_loop"):
-        return [], []
+        return [], [], False
     ralph_path = os.path.join(project_dir, ".omg", "state", "ralph-loop.json")
     if not os.path.exists(ralph_path):
-        return [], []
+        return [], [], False
     try:
         with open(ralph_path, "r", encoding="utf-8") as f:
             state = json.load(f)
     except (json.JSONDecodeError, OSError):
-        return [], []
+        return [], [], False
     if not state.get("active"):
-        return [], []
-    
+        return [], [], False
+
+    # --- Pending clarification question: block and end turn immediately ---
+    if state.get("question_pending"):
+        question_text = str(state.get("question_text", "")).strip()
+        if not question_text:
+            question_text = "Clarification required before continuing Ralph loop"
+        # Do NOT increment iteration — the loop is paused on the question
+        return [question_text], [], True
+
     # Check if Ralph loop has expired
-    timeout_minutes = int(os.environ.get("OMG_RALPH_TIMEOUT_MINUTES", "30"))
+    _raw_timeout = os.environ.get("OMG_RALPH_TIMEOUT_MINUTES", "")
+    try:
+        timeout_minutes = int(_raw_timeout) if _raw_timeout.strip() else _RALPH_DEFAULT_TIMEOUT_MINUTES
+    except (ValueError, TypeError):
+        timeout_minutes = _RALPH_DEFAULT_TIMEOUT_MINUTES
     started_at_str = state.get("started_at")
     if started_at_str:
         try:
@@ -863,7 +911,7 @@ def check_ralph_loop(project_dir, data):
             if elapsed.total_seconds() > timeout_minutes * 60:
                 state["active"] = False
                 atomic_json_write(ralph_path, state)
-                return [], [f"Ralph loop expired after {timeout_minutes} minutes. Stopping."]
+                return [], [f"Ralph loop expired after {timeout_minutes} minutes. Stopping."], False
         except (ValueError, TypeError):
             pass
     
@@ -872,11 +920,11 @@ def check_ralph_loop(project_dir, data):
     if iteration >= max_iter:
         state["active"] = False
         atomic_json_write(ralph_path, state)
-        return [], ["Ralph loop reached max iterations. Stopping."]
+        return [], ["Ralph loop reached max iterations. Stopping."], False
     state["iteration"] = iteration + 1
     atomic_json_write(ralph_path, state)
     reason = format_ralph_block_reason(state, project_dir)
-    return [reason], []
+    return [reason], [], False
 
 
 def check_planning_gate(project_dir):
@@ -980,41 +1028,63 @@ def check_todo_continuation(data: dict[str, object]) -> dict[str, str] | None:
 
 
 def main():
+    _watchdog_start = time.time()
+
     data = json_input()
 
     # Unified guard: stop-hook loop, context-limit, and re-entry detection
     if should_skip_stop_hooks(data):
         sys.exit(0)
 
+    # Watchdog: bail out if we already burned too much wall-clock time
+    if _watchdog_check(_watchdog_start):
+        print("[OMG] stop_dispatcher: wall-clock watchdog expired", file=sys.stderr)
+        sys.exit(0)
+
     project_dir = _resolve_project_dir()
     data["_stop_ctx"] = _build_context(project_dir)
     data["_stop_advisories"] = []
 
     # P1: Ralph loop check (implemented in Task 18)
-    block_reasons, advisories = check_ralph_loop(project_dir, data)
+    block_reasons, advisories, is_question = check_ralph_loop(project_dir, data)
     if advisories:
         data["_stop_advisories"].extend(advisories)
     if block_reasons:
-        record_stop_block(project_dir, reason="ralph_loop")
-        block_decision(block_reasons[0])
+        # Clarification questions use a distinct block_reason so the turn
+        # ends cleanly — no tool action may follow a question emission.
+        br = "clarification_required" if is_question else "ralph_loop"
+        block_decision(block_reasons[0], block_reason=br, project_dir=project_dir)
+        return
+
+    if _watchdog_check(_watchdog_start):
+        print("[OMG] stop_dispatcher: wall-clock watchdog expired", file=sys.stderr)
+        sys.exit(0)
 
     # P2: Planning enforcement (implemented in Task 22)
     block_reasons, advisories = check_planning_gate(project_dir)
     if block_reasons:
-        record_stop_block(project_dir, reason="planning_gate")
-        block_decision(block_reasons[0])
+        block_decision(block_reasons[0], block_reason="planning_gate", project_dir=project_dir)
+        return
     advisories.extend(check_scope_drift(project_dir))
     if advisories:
         data["_stop_advisories"].extend(advisories)
 
+    if _watchdog_check(_watchdog_start):
+        print("[OMG] stop_dispatcher: wall-clock watchdog expired", file=sys.stderr)
+        sys.exit(0)
+
     # P3: Todo continuation enforcement (Task 1.6)
     _p3_start = time.monotonic()
     todo_result = check_todo_continuation(data)
     _p3_elapsed = (time.monotonic() - _p3_start) * 1000
     check_performance_budget("check_todo_continuation", _p3_elapsed, STOP_CHECK_MAX_MS)
     if todo_result and todo_result.get("decision") == "block":
-        record_stop_block(project_dir, reason="todo_continuation")
-        block_decision(todo_result["reason"])
+        block_decision(todo_result["reason"], block_reason="todo_continuation", project_dir=project_dir)
+        return
+
+    if _watchdog_check(_watchdog_start):
+        print("[OMG] stop_dispatcher: wall-clock watchdog expired", file=sys.stderr)
+        sys.exit(0)
 
     blocks = []
     for check_fn in [
@@ -1030,6 +1100,9 @@ def main():
         _test_validator_check,
         _quality_runner_check,
     ]:
+        if _watchdog_check(_watchdog_start):
+            print("[OMG] stop_dispatcher: wall-clock watchdog expired during quality checks", file=sys.stderr)
+            sys.exit(0)
         if check_fn is None:
             continue
         try:
@@ -1045,8 +1118,8 @@ def main():
         print("\n".join(advisories), file=sys.stderr)
 
     if blocks:
-        record_stop_block(project_dir, reason="quality_check")
-        block_decision("\n\n---\n\n".join(blocks))
+        block_decision("\n\n---\n\n".join(blocks), block_reason="quality_check", project_dir=project_dir)
+        return
 
     check_simplifier(data, project_dir)
     reset_stop_block_tracker(project_dir)

package/hooks/test-validator.py

@@ -23,10 +23,13 @@ from collections import Counter
 from datetime import datetime, timezone
 
 HOOKS_DIR = os.path.dirname(__file__)
+PROJECT_ROOT = os.path.dirname(HOOKS_DIR)
 if HOOKS_DIR not in sys.path:
     sys.path.insert(0, HOOKS_DIR)
+if PROJECT_ROOT not in sys.path:
+    sys.path.insert(0, PROJECT_ROOT)
 
-from _common import _resolve_project_dir, should_skip_stop_hooks
+from hooks._common import _resolve_project_dir, should_skip_stop_hooks
 
 # --- Builtins excluded from parameterized-gap detection ---
 _BUILTIN_FUNCS = frozenset({
@@ -36,6 +39,9 @@ _BUILTIN_FUNCS = frozenset({
     "expect", "require", "import", "open", "super", "getattr", "setattr",
     "hasattr", "sorted", "enumerate", "zip", "map", "filter", "min", "max",
 })
+_MUTATION_TOOLS = frozenset({"write", "edit", "multiedit", "bash"})
+_SKIP_DIR_SEGMENTS = frozenset({"build", "dist", "node_modules", ".git"})
+_TEST_DIR_NAMES = frozenset({"tests", "test", "__tests__"})
 
 
 def analyze_test_content(content, filename="test.py"):
@@ -267,6 +273,31 @@ def persist_metrics(project_dir, analysis):
         pass  # Crash isolation: never fail the hook
 
 
+def _is_test_file(rel_path):
+    """
+    Heuristic: is this path likely a test file (vs source module)?
+
+    Excludes build artifacts and source modules that happen to start with
+    ``test_`` but live outside test directories (e.g. ``runtime/test_intent_lock.py``).
+    """
+    parts = rel_path.replace("\\", "/").split("/")
+    # Skip build artifacts and vendored code
+    if any(seg in _SKIP_DIR_SEGMENTS for seg in parts[:-1]):
+        return False
+    basename = parts[-1].lower() if parts else ""
+    # Standard test file patterns (checked against basename)
+    if any(p in basename for p in (".test.", ".spec.", "_test.", ".tests.")):
+        return True
+    # __tests__ directory anywhere in path
+    if "__tests__" in rel_path:
+        return True
+    # test_ prefix: only match if file is in a test directory or at repo root
+    if basename.startswith("test_"):
+        parent_dirs = {p.lower() for p in parts[:-1]}
+        return not parent_dirs or bool(parent_dirs & _TEST_DIR_NAMES)
+    return False
+
+
 def check_test_quality(data, project_dir):
     """Core test-quality validation. Returns list of block-reason strings."""
     import subprocess
@@ -279,8 +310,7 @@ def check_test_quality(data, project_dir):
             capture_output=True, text=True, timeout=10, cwd=project_dir
         )
         for f in result.stdout.strip().split("\n"):
-            if f and any(p in f.lower() for p in
-                         [".test.", ".spec.", "_test.", "test_", "__tests__", ".tests."]):
+            if f and _is_test_file(f):
                 full = os.path.join(project_dir, f)
                 if os.path.exists(full):
                     test_files.append(full)
@@ -344,6 +374,44 @@ def check_test_quality(data, project_dir):
     return []
 
 
+def check_methodology_contract(data):
+    if not isinstance(data, dict):
+        return []
+
+    tool_name = str(data.get("tool_name", "")).strip().lower()
+    if tool_name not in _MUTATION_TOOLS:
+        return []
+
+    tool_input = data.get("tool_input")
+    if not isinstance(tool_input, dict):
+        return ["METHODOLOGY: mutation-capable flow requires metadata with done_when criteria"]
+
+    exemption = str(tool_input.get("exemption", "")).strip().lower()
+    if exemption == "docs":
+        return []
+
+    metadata = tool_input.get("metadata")
+    if not isinstance(metadata, dict):
+        return ["METHODOLOGY: mutation-capable flow requires metadata with done_when criteria"]
+
+    done_when = metadata.get("done_when")
+    if isinstance(done_when, str) and done_when.strip():
+        return []
+    if isinstance(done_when, list):
+        if any(str(item).strip() for item in done_when):
+            return []
+    if isinstance(done_when, dict):
+        criteria = done_when.get("criteria")
+        if isinstance(criteria, str) and criteria.strip():
+            return []
+        if isinstance(criteria, list) and any(str(item).strip() for item in criteria):
+            return []
+        if str(done_when.get("summary", "")).strip():
+            return []
+
+    return ["METHODOLOGY: done_when criteria required before mutation-capable execution"]
+
+
 # Standalone execution (backward compat: invoked directly by hook runner)
 if __name__ == "__main__":
     try:
@@ -356,6 +424,7 @@ if __name__ == "__main__":
 
     project_dir = _resolve_project_dir()
     blocks = check_test_quality(data, project_dir)
+    blocks.extend(check_methodology_contract(data))
     if blocks:
         json.dump({"decision": "block", "reason": blocks[0]}, sys.stdout)
     sys.exit(0)

package/hooks/tool-ledger.py

@@ -53,8 +53,19 @@ entry = {
     "ts": datetime.now(timezone.utc).isoformat(),
     "pid": os.getpid(),
     "tool": tool_name,
+    "surface_tags": [],
 }
 
+if isinstance(tool_input, dict):
+    lane_name = tool_input.get("lane_name", tool_input.get("lane"))
+    if isinstance(lane_name, str) and lane_name.strip():
+        entry["lane"] = lane_name.strip().lower()
+        entry["surface_tags"].append("governed_tools")
+    governed_tool = tool_input.get("tool_name")
+    if isinstance(governed_tool, str) and governed_tool.strip() and governed_tool != tool_name:
+        entry["governed_tool"] = governed_tool.strip()
+        entry["surface_tags"].append("governed_tools")
+
 # Link ledger entries to OMG v1 run/evidence artifacts when available.
 run_id = os.environ.get("OMG_RUN_ID")
 if not run_id:
@@ -69,6 +80,7 @@ if run_id:
     entry["run_id"] = run_id
 
 if tool_name == "Bash":
+    entry["surface_tags"].append("hooks")
     entry["command"] = tool_input.get("command", "")[:500]
     if isinstance(tool_response, dict):
         entry["exit_code"] = tool_response.get("exitCode", tool_response.get("exit_code"))
@@ -107,6 +119,10 @@ if run_id:
     ev_path = os.path.join(project_dir, ".omg", "evidence", f"{run_id}.json")
     if os.path.exists(ev_path):
         entry["evidence_path"] = os.path.relpath(ev_path, project_dir)
+        entry["evidence_links"] = [entry["evidence_path"]]
+
+if not entry["surface_tags"]:
+    entry.pop("surface_tags", None)
 
 # ── Latency tracking: duration_ms ──
 # Prefer startTime/endTime from hook stdin (ISO8601), fall back to wall clock.