@trac3er/oh-my-god 2.0.0 → 2.0.2

package/hooks/_common.py

@@ -0,0 +1,569 @@
+"""Shared utilities for OMG hooks. Pure stdlib — no external deps."""
+import json
+import os
+import sys
+import fcntl
+from datetime import datetime, timezone
+
+# --- Stop-Block Loop Breaker ---
+_STOP_BLOCK_TRACKER = ".omg/state/ledger/.stop-block-tracker.json"
+# Max seconds between blocks to consider it a loop
+_BLOCK_LOOP_WINDOW_SECS = 30
+# How many consecutive blocks before we skip
+_BLOCK_LOOP_THRESHOLD = 2
+# Block reasons that indicate a loop scenario (Guard 5 skip-eligible)
+_LOOP_BLOCK_REASONS = {"planning_gate", "ralph_loop", "quality_check", "block_decision", "unknown"}
+
+# --- Performance Budget Constants ---
+PRE_TOOL_INJECT_MAX_MS = 100
+STOP_CHECK_MAX_MS = 15000
+STOP_DISPATCHER_TOTAL_MAX_MS = 90000
+
+def json_input():
+    """Parse JSON from stdin. Returns dict or exits 0 on parse failure."""
+    try:
+        return json.load(sys.stdin)
+    except (json.JSONDecodeError, EOFError):
+        sys.exit(0)
+
+
+def get_project_dir():
+    """Get project directory from env or cwd."""
+    return os.environ.get("CLAUDE_PROJECT_DIR", os.getcwd())
+
+
+def _resolve_project_dir():
+    """Get and validate project directory; warns if .omg/ missing."""
+    path = get_project_dir()
+    if not os.path.isdir(os.path.join(path, ".omg")):
+        print(f"[OMG] Warning: .omg/ not found in {path}", file=sys.stderr)
+    return path
+
+def deny_decision(reason):
+    """Emit a PreToolUse deny decision to stdout."""
+    json.dump({
+        "hookSpecificOutput": {
+            "hookEventName": "PreToolUse",
+            "permissionDecision": "deny",
+            "permissionDecisionReason": reason,
+        }
+    }, sys.stdout)
+
+
+def block_decision(reason):
+    """Emit a Stop hook block decision to stdout.
+
+    Also records the block for loop detection. Every stop hook that calls
+    block_decision() contributes to the loop breaker counter, so deadlocks
+    are detected regardless of which specific hook triggers the block.
+    """
+    # Record block BEFORE emitting -- ensures tracker is updated even if
+    # the process is killed after emitting the decision.
+    try:
+        record_stop_block()
+    except Exception:
+        pass  # never let tracker failure prevent the block decision
+    json.dump({"decision": "block", "reason": reason}, sys.stdout)
+
+
+def setup_crash_handler(hook_name, fail_closed=False):
+    """Install a crash handler that prevents non-zero exits.
+
+    fail_closed=True: emit deny on crash (for security hooks like firewall, secret-guard)
+    fail_closed=False: silently exit 0 (for non-security hooks)
+    """
+    def _excepthook(exc_type, exc_val, exc_tb):
+        print(f"OMG hook error ({hook_name}): {exc_val}", file=sys.stderr)
+        log_hook_error(hook_name, exc_val)
+        if fail_closed:
+            try:
+                deny_decision(f"OMG {hook_name} crash: {exc_val}. Denying for safety.")
+            except Exception:
+                pass
+        os._exit(0)
+    sys.excepthook = _excepthook
+
+
+def read_file_safe(path, max_bytes=2000):
+    """Read file content safely, returning None on any failure."""
+    try:
+        if not os.path.exists(path):
+            return None
+        with open(path, "r", encoding="utf-8", errors="ignore") as f:
+            text = f.read(max_bytes).strip()
+        return text or None
+    except Exception:
+        return None
+
+
+def log_hook_error(hook_name, error, context=None):
+    """Log hook error to .omg/state/ledger/hook-errors.jsonl with file locking.
+    
+    Args:
+        hook_name: Name of the hook that errored
+        error: Exception or error message
+        context: Optional dict with additional context
+    
+    Silently fails if logging cannot be completed (crash isolation).
+    """
+    try:
+        project_dir = get_project_dir()
+        ledger_dir = os.path.join(project_dir, ".omg", "state", "ledger")
+        os.makedirs(ledger_dir, exist_ok=True)
+        
+        ledger_path = os.path.join(ledger_dir, "hook-errors.jsonl")
+        
+        # Rotation: if file > 100KB, rename to .hook-errors.jsonl.1
+        try:
+            if os.path.exists(ledger_path):
+                size = os.path.getsize(ledger_path)
+                if size > 100 * 1024:  # 100KB
+                    archive = ledger_path + ".1"
+                    if os.path.exists(archive):
+                        try:
+                            os.remove(archive)
+                        except OSError:
+                            pass
+                    try:
+                        os.rename(ledger_path, archive)
+                    except OSError:
+                        pass
+        except Exception:
+            pass
+        
+        # Build entry
+        entry = {
+            "ts": datetime.now(timezone.utc).isoformat(),
+            "hook": hook_name,
+            "error": str(error),
+        }
+        if context:
+            entry["context"] = context
+        
+        # Write with file locking
+        try:
+            fd = open(ledger_path, "a")
+            fcntl.flock(fd.fileno(), fcntl.LOCK_EX)
+            fd.write(json.dumps(entry, separators=(",", ":")) + "\n")
+            fcntl.flock(fd.fileno(), fcntl.LOCK_UN)
+            fd.close()
+        except (ImportError, BlockingIOError):
+            # Fallback: write without locking
+            try:
+                with open(ledger_path, "a") as f:
+                    f.write(json.dumps(entry, separators=(",", ":")) + "\n")
+            except Exception as e:
+                print(f"[OMG] _common.py: {type(e).__name__}: {e}", file=sys.stderr)
+                pass
+        except Exception as e:
+            print(f"[OMG] _common.py: {type(e).__name__}: {e}", file=sys.stderr)
+            pass
+    except Exception as e:
+        print(f"[OMG] _common.py: {type(e).__name__}: {e}", file=sys.stderr)
+        pass
+
+
+def atomic_json_write(path, data):
+    """Atomically write JSON data to a file using temp + rename.
+    
+    Args:
+        path: Target file path
+        data: Data to write as JSON
+    
+    Creates parent directories if needed. Silently fails on error.
+    """
+    try:
+        # Create parent dirs
+        parent = os.path.dirname(path)
+        if parent:
+            os.makedirs(parent, exist_ok=True)
+        
+        # Write to temp file
+        tmp_path = path + ".tmp"
+        with open(tmp_path, "w", encoding="utf-8") as f:
+            json.dump(data, f, separators=(",", ":"))
+        
+        # Atomic rename
+        os.rename(tmp_path, path)
+    except Exception as e:
+        print(f"[OMG] _common.py: {type(e).__name__}: {e}", file=sys.stderr)
+        pass
+
+
+# Feature flags cache — read settings.json once per hook invocation
+_FEATURE_CACHE = {}
+_SETTINGS_PRESET = None
+_MANAGED_PRESET_FLAGS = {
+    "SETUP",
+    "SETUP_WIZARD",
+    "MEMORY_AUTOSTART",
+    "SESSION_ANALYTICS",
+    "CONTEXT_MANAGER",
+    "COST_TRACKING",
+    "MEMORY_SERVER",
+    "GIT_WORKFLOW",
+    "TEST_GENERATION",
+    "DEP_HEALTH",
+    "CODEBASE_VIZ",
+}
+_PRESET_FEATURES = {
+    "safe": {flag: False for flag in _MANAGED_PRESET_FLAGS},
+    "balanced": {
+        "SETUP": True,
+        "SETUP_WIZARD": True,
+        "MEMORY_AUTOSTART": True,
+        "SESSION_ANALYTICS": True,
+        "CONTEXT_MANAGER": True,
+        "COST_TRACKING": True,
+        "MEMORY_SERVER": False,
+        "GIT_WORKFLOW": False,
+        "TEST_GENERATION": False,
+        "DEP_HEALTH": False,
+        "CODEBASE_VIZ": False,
+    },
+    "interop": {
+        "SETUP": True,
+        "SETUP_WIZARD": True,
+        "MEMORY_AUTOSTART": True,
+        "SESSION_ANALYTICS": True,
+        "CONTEXT_MANAGER": True,
+        "COST_TRACKING": True,
+        "MEMORY_SERVER": True,
+        "GIT_WORKFLOW": False,
+        "TEST_GENERATION": False,
+        "DEP_HEALTH": False,
+        "CODEBASE_VIZ": False,
+    },
+    "labs": {
+        "SETUP": True,
+        "SETUP_WIZARD": True,
+        "MEMORY_AUTOSTART": True,
+        "SESSION_ANALYTICS": True,
+        "CONTEXT_MANAGER": True,
+        "COST_TRACKING": True,
+        "MEMORY_SERVER": True,
+        "GIT_WORKFLOW": True,
+        "TEST_GENERATION": True,
+        "DEP_HEALTH": True,
+        "CODEBASE_VIZ": True,
+    },
+}
+_FEATURE_ALIASES = {
+    "SETUP": ("SETUP", "SETUP_WIZARD"),
+    "SETUP_WIZARD": ("SETUP_WIZARD", "SETUP"),
+}
+
+
+def _load_feature_settings():
+    """Populate feature cache from settings.json and return the configured preset."""
+    global _SETTINGS_PRESET
+
+    _FEATURE_CACHE.clear()
+    _SETTINGS_PRESET = None
+    try:
+        settings_path = os.path.join(get_project_dir(), "settings.json")
+        if os.path.exists(settings_path):
+            with open(settings_path, "r", encoding="utf-8") as f:
+                settings = json.load(f)
+            omg = settings.get("_omg", {})
+            if isinstance(omg, dict):
+                features = omg.get("features", {})
+                if isinstance(features, dict):
+                    _FEATURE_CACHE.update(features)
+                preset = omg.get("preset")
+                if isinstance(preset, str) and preset in _PRESET_FEATURES:
+                    _SETTINGS_PRESET = preset
+    except Exception:
+        pass
+
+
+def get_feature_flag(flag_name, default=True):
+    """Get feature flag value with resolution order: env var → settings.json → default.
+    
+    Env var format: OMG_{FLAG_NAME.upper()}_ENABLED
+    Values: "0"/"false"/"no" → False, "1"/"true"/"yes" → True
+    
+    Returns default on any error (missing settings.json, malformed JSON, etc).
+    """
+    # Check environment variable first
+    env_key = f"OMG_{flag_name.upper()}_ENABLED"
+    env_val = os.environ.get(env_key, "").lower()
+    if env_val in ("0", "false", "no"):
+        return False
+    if env_val in ("1", "true", "yes"):
+        return True
+
+    # Check settings.json (cached)
+    if not _FEATURE_CACHE:
+        _load_feature_settings()
+
+    env_preset = os.environ.get("OMG_PRESET", "").lower().strip()
+    lookup_names = _FEATURE_ALIASES.get(flag_name, (flag_name,))
+
+    # Env preset is a session-scoped override for managed flags.
+    if env_preset in _PRESET_FEATURES:
+        for name in lookup_names:
+            if name in _MANAGED_PRESET_FLAGS:
+                return _PRESET_FEATURES[env_preset].get(name, default)
+
+    for name in lookup_names:
+        if name in _FEATURE_CACHE:
+            return _FEATURE_CACHE[name]
+
+    if _SETTINGS_PRESET in _PRESET_FEATURES:
+        for name in lookup_names:
+            if name in _MANAGED_PRESET_FLAGS:
+                return _PRESET_FEATURES[_SETTINGS_PRESET].get(name, default)
+
+    return default
+
+
+# Permission mode helpers
+BYPASS_MODES = frozenset({"bypasspermissions", "dontask"})
+
+
+def is_bypass_mode(data):
+    """Return True if the hook input indicates permission prompts should be skipped.
+
+    Claude Code passes ``permission_mode`` in the hook input.  When the user
+    enables *bypass permissions* or *don't ask* mode, hooks should still
+    enforce hard denials (critical safety) but must NOT emit ``ask`` decisions
+    that would re-introduce confirmation prompts.
+    """
+    if not isinstance(data, dict):
+        return False
+    mode = (data.get("permission_mode") or "").lower().strip()
+    return mode in BYPASS_MODES
+
+
+# --- Subagent & Context-Limit Detection ---
+
+# Stop hook feedback markers injected by Claude Code when a stop hook blocks
+_STOP_HOOK_FEEDBACK_PREFIX = "Stop hook feedback:"
+
+
+def should_skip_stop_hooks(data):
+    """Return True if stop hooks should exit immediately without blocking.
+    
+    Detects four conditions:
+    1. stop_hook_active flag (Claude Code's built-in re-entry guard)
+    2. Stop hook feedback loop (previous block was already injected,
+       agent couldn't respond — blocking again is futile)
+    3. Context-limit / rate-limit stop (blocking these prevents compaction
+       or creates infinite retry loops — must allow stop to proceed)
+    4. File-based loop breaker (if hooks blocked >= 2 times within 90s,
+       agent cannot resolve — likely context-limited)
+    
+    Safe for all stop hooks to call at the top of main().
+    """
+    if not isinstance(data, dict):
+        return False
+
+    # Guard 1: Claude Code's built-in re-entry prevention
+    if data.get("stop_hook_active", False):
+        return True
+
+    # Guard 3: Context-limit and rate-limit stop detection
+    #   When context is exhausted, Claude Code needs to stop so it can compact.
+    #   Blocking these stops causes a deadlock: can't compact because can't stop,
+    #   can't continue because context is full.
+    #   Similarly, rate-limit stops (429/quota) must not be blocked or they loop.
+    stop_reason = str(data.get("stop_reason", data.get("stopReason", ""))).lower()
+    end_turn_reason = str(data.get("end_turn_reason", data.get("endTurnReason", ""))).lower()
+    signal_text = " ".join(
+        str(data.get(k, ""))
+        for k in ("message", "error", "reason", "type", "event")
+    ).lower()
+    context_limit_markers = (
+        "context window",
+        "token limit",
+        "too much context",
+        "context length exceeded",
+        "maximum context length",
+        "prompt is too long",
+        "request too large",
+        "input too long",
+        "context_limit",
+        "context overflow",
+    )
+    if any(marker in signal_text for marker in context_limit_markers):
+        print(
+            "[OMG] Context limit detected: allowing stop so compaction can proceed. "
+            "If this repeats, run /OMG:handoff and resume from .omg/state/handoff.md.",
+            file=sys.stderr,
+        )
+        return True
+
+    # Guard 2: Check transcript for stop-hook feedback loop
+    #   If the last user message is stop hook feedback, the hooks already
+    #   blocked once and the agent tried (and failed) to respond.
+    #   Blocking again creates an unrecoverable loop.
+    transcript_path = data.get("transcript_path", "")
+    if transcript_path and os.path.exists(transcript_path):
+        try:
+            last_user_text = ""
+            with open(transcript_path, "r", encoding="utf-8", errors="ignore") as f:
+                for line in f:
+                    line = line.strip()
+                    if not line:
+                        continue
+                    try:
+                        entry = json.loads(line)
+                    except json.JSONDecodeError:
+                        continue
+                    if entry.get("type") == "user":
+                        msg = entry.get("message", {})
+                        content = msg.get("content", "")
+                        if isinstance(content, str):
+                            last_user_text = content
+                        elif isinstance(content, list):
+                            for block in content:
+                                if isinstance(block, dict) and block.get("type") == "text":
+                                    last_user_text = block.get("text", "")
+                                elif isinstance(block, str):
+                                    last_user_text = block
+            # If last user message is stop hook feedback, we're in a loop
+            if last_user_text.startswith(_STOP_HOOK_FEEDBACK_PREFIX):
+                print("[OMG] Guard 2 triggered: stop-hook feedback loop", file=sys.stderr)
+                return True
+        except Exception:
+            pass  # Fail open — don't skip hooks on read errors
+
+    # Guard 4: File-based loop breaker (safety net)
+    #   If stop hooks have blocked multiple times in quick succession,
+    #   the agent cannot meaningfully resolve the issue (likely context-limited).
+    #   This is the last-resort safety net when Guards 1-3 all fail to detect the loop.
+    if is_stop_block_loop():
+        print("[OMG] Guard 4 triggered: stop-block loop detected, skipping hooks", file=sys.stderr)
+        return True
+
+    # Guard 5: Empty stop_reason + recent block = likely context-limit deadlock
+    #   Claude Code often doesn't set stop_reason/end_turn_reason for context-limit stops.
+    #   If we blocked recently (any count >= 1 within window) AND stop_reason is missing,
+    #   it's almost certainly a deadlock. Allow the stop to proceed.
+    if not stop_reason and not end_turn_reason:
+        try:
+            _pdir = get_project_dir()
+            _tracker_path = os.path.join(_pdir, _STOP_BLOCK_TRACKER)
+            if os.path.exists(_tracker_path):
+                with open(_tracker_path, "r", encoding="utf-8") as _f:
+                    _state = json.load(_f)
+                _elapsed = (datetime.now(timezone.utc) - datetime.fromisoformat(_state["ts"])).total_seconds()
+                if _elapsed < _BLOCK_LOOP_WINDOW_SECS and _state.get("count", 0) >= 1:
+                    _reason = _state.get("reason", "unknown")
+                    if _reason in _LOOP_BLOCK_REASONS:
+                        print(
+                            "[OMG] Guard 5 triggered: context may be exhausted and stop hooks recently blocked. "
+                            "Skipping stop-hook blocks so compaction can run. "
+                            "Tip: /OMG:handoff then continue in a fresh session.",
+                            file=sys.stderr,
+                        )
+                        return True
+        except Exception:
+            pass  # fail open
+    return False
+
+
+# --- Stop-Block Loop Breaker (file-based safety net) ---
+
+def record_stop_block(project_dir=None, reason: str = "unknown", session_id: str = ""):
+    """Record that a stop hook block was issued. Called before block_decision().
+    
+    Args:
+        project_dir: Project directory (auto-detected if None)
+        reason: Human-readable reason for the block (e.g., 'ralph_loop', 'planning_gate', 'quality_check')
+        session_id: Session identifier to prevent cross-session interference
+    """
+    try:
+        pdir = project_dir or get_project_dir()
+        path = os.path.join(pdir, _STOP_BLOCK_TRACKER)
+        state = {
+            "ts": datetime.now(timezone.utc).isoformat(),
+            "count": 1,
+            "session_id": session_id,
+            "reason": reason,
+        }
+        if os.path.exists(path):
+            try:
+                with open(path, "r", encoding="utf-8") as f:
+                    old = json.load(f)
+                elapsed = (datetime.now(timezone.utc) - datetime.fromisoformat(old["ts"])).total_seconds()
+                if elapsed < _BLOCK_LOOP_WINDOW_SECS:
+                    state["count"] = old.get("count", 0) + 1
+                    # Preserve session_id and reason from old state if not overridden
+                    if not session_id:
+                        state["session_id"] = old.get("session_id", "")
+                    if reason == "unknown":
+                        state["reason"] = old.get("reason", "unknown")
+                # else: reset — old block is stale
+            except Exception:
+                pass  # intentional: corrupt file, start fresh
+        atomic_json_write(path, state)
+    except Exception:
+        pass  # intentional: never crash on tracking
+
+
+def is_stop_block_loop(project_dir=None, session_id: str = ""):
+    """Return True if stop hooks have blocked repeatedly within the loop window.
+
+    Safety net for deadlocks: if hooks blocked >= N times within M seconds,
+    the agent clearly cannot resolve the issue (likely context-limited).
+    All stop hooks should allow the stop to proceed.
+    
+    Args:
+        project_dir: Project directory (auto-detected if None)
+        session_id: Current session ID. If provided and tracker has a different session_id,
+                   returns False (cross-session, not a loop).
+    """
+    try:
+        pdir = project_dir or get_project_dir()
+        path = os.path.join(pdir, _STOP_BLOCK_TRACKER)
+        if not os.path.exists(path):
+            return False
+        with open(path, "r", encoding="utf-8") as f:
+            state = json.load(f)
+        
+        # Cross-session check: if tracker has session_id and it differs from current, not a loop
+        tracker_session_id = state.get("session_id", "")
+        if tracker_session_id and session_id and tracker_session_id != session_id:
+            return False  # Different session, not a loop
+        
+        ts = datetime.fromisoformat(state["ts"])
+        elapsed = (datetime.now(timezone.utc) - ts).total_seconds()
+        count = state.get("count", 0)
+        return elapsed < _BLOCK_LOOP_WINDOW_SECS and count >= _BLOCK_LOOP_THRESHOLD
+    except Exception:
+        return False  # fail open — don't skip hooks on errors
+
+
+def reset_stop_block_tracker(project_dir=None):
+    """Reset the stop block tracker. Called on clean (non-blocked) stop."""
+    try:
+        pdir = project_dir or get_project_dir()
+        path = os.path.join(pdir, _STOP_BLOCK_TRACKER)
+        if os.path.exists(path):
+            os.remove(path)
+    except Exception:
+        pass  # intentional: never crash on cleanup
+
+
+def check_performance_budget(hook_name: str, elapsed_ms: float, budget_ms: float) -> bool:
+    """Check if hook execution is within performance budget.
+    
+    Args:
+        hook_name: Name of the hook being checked
+        elapsed_ms: Elapsed time in milliseconds
+        budget_ms: Budget threshold in milliseconds
+    
+    Returns:
+        True if within budget, False if over budget (with warning logged)
+    """
+    if elapsed_ms <= budget_ms:
+        return True
+    # Log warning for budget overrun
+    log_hook_error(
+        hook_name,
+        f"Performance budget exceeded: {elapsed_ms:.1f}ms > {budget_ms}ms",
+        context={"elapsed_ms": elapsed_ms, "budget_ms": budget_ms}
+    )
+    return False

package/hooks/_compression_optimizer.py

@@ -0,0 +1,119 @@
+#!/usr/bin/env python3
+"""Compression guideline optimizer from compression feedback JSONL."""
+from __future__ import annotations
+
+import json
+import os
+from collections import Counter
+from datetime import datetime, timezone
+
+from ._common import get_feature_flag
+
+
+def _new_guidelines() -> dict[str, object]:
+    return {
+        "generated_at": datetime.now(timezone.utc).isoformat(),
+        "always_keep": [],
+        "prefer_keep": [],
+        "compress_ok": [],
+        "drop_ok": [],
+    }
+
+
+def _is_failure_entry(entry: object) -> bool:
+    if not isinstance(entry, dict):
+        return False
+    if entry.get("failed") is True:
+        return True
+    if entry.get("success") is False:
+        return True
+    status = str(entry.get("status", "")).strip().lower()
+    if status in {"failed", "failure", "error"}:
+        return True
+    outcome = str(entry.get("outcome", "")).strip().lower()
+    return outcome in {"failed", "failure", "error"}
+
+
+def _coerce_items(value: object) -> list[str]:
+    if not isinstance(value, list):
+        return []
+    items: list[str] = []
+    for raw in value:
+        if not isinstance(raw, str):
+            continue
+        item = raw.strip()
+        if item:
+            items.append(item)
+    return items
+
+
+def _extract_dropped_items(entry: object) -> list[str]:
+    if not isinstance(entry, dict):
+        return []
+    for key in ("dropped_items", "dropped", "items_dropped", "dropped_context"):
+        items = _coerce_items(entry.get(key))
+        if items:
+            return items
+    return []
+
+
+def _read_feedback(path: str) -> tuple[Counter[str], set[str]]:
+    failure_counts: Counter[str] = Counter()
+    all_dropped_items: set[str] = set()
+
+    if not path or not os.path.exists(path):
+        return failure_counts, all_dropped_items
+
+    try:
+        with open(path, "r", encoding="utf-8") as handle:
+            for line in handle:
+                raw = line.strip()
+                if not raw:
+                    continue
+                try:
+                    entry = json.loads(raw)
+                except json.JSONDecodeError:
+                    continue
+
+                dropped_items = _extract_dropped_items(entry)
+                if not dropped_items:
+                    continue
+
+                all_dropped_items.update(dropped_items)
+                if _is_failure_entry(entry):
+                    failure_counts.update(set(dropped_items))
+    except OSError:
+        return Counter(), set()
+
+    return failure_counts, all_dropped_items
+
+
+def optimize_guidelines(feedback_path: str, output_path: str) -> dict[str, object]:
+    if not get_feature_flag("CONTEXT_MANAGER", default=False):
+        return _new_guidelines()
+
+    guidelines = _new_guidelines()
+    failure_counts, all_items = _read_feedback(feedback_path)
+
+    always_keep = sorted(item for item, count in failure_counts.items() if count >= 3)
+    prefer_keep = sorted(item for item, count in failure_counts.items() if 1 <= count <= 2)
+    compress_ok = sorted(item for item in all_items if failure_counts.get(item, 0) == 0)
+
+    guidelines["always_keep"] = always_keep
+    guidelines["prefer_keep"] = prefer_keep
+    guidelines["compress_ok"] = compress_ok
+
+    if output_path:
+        try:
+            parent = os.path.dirname(output_path)
+            if parent:
+                os.makedirs(parent, exist_ok=True)
+            with open(output_path, "w", encoding="utf-8") as handle:
+                json.dump(guidelines, handle, indent=2)
+        except OSError:
+            pass
+
+    return guidelines
+
+
+__all__ = ["optimize_guidelines"]