wicked-garden 12.27.0

package/hooks/scripts/bootstrap.py

@@ -0,0 +1,1797 @@
+#!/usr/bin/env python3
+"""
+SessionStart hook — wicked-garden unified bootstrap.
+
+Consolidates: crew session_start, mem session_start,
+search session_start, smaht session_start.
+
+Flow:
+1. Read config from ~/.something-wicked/wicked-garden/config.json
+2. If missing or setup_complete=false: emit setup instructions, return
+3. Load dynamic agents
+4. Load active crew project
+5. Run memory decay
+6. Check onboarding status → imperative directive if needed
+7. Assemble session briefing
+8. Return {"continue": true, "systemMessage": "<briefing>"}
+
+Always fails open — any unhandled exception returns {"continue": true}.
+"""
+
+import json
+import os
+import subprocess
+import sys
+import time
+from datetime import datetime, timezone
+from pathlib import Path
+
+# Add shared scripts directory to path so hook can import shared modules
+_PLUGIN_ROOT = Path(os.environ.get("CLAUDE_PLUGIN_ROOT", Path(__file__).resolve().parents[2]))
+sys.path.insert(0, str(_PLUGIN_ROOT / "scripts"))
+
+from _brain_port import resolve_port
+
+# ---------------------------------------------------------------------------
+# Ops logger wrapper — fail-silent, never crashes the hook
+# ---------------------------------------------------------------------------
+
+def _log(domain, level, event, ok=True, ms=None, detail=None):
+    """Ops logger — fail-silent, never crashes the hook."""
+    try:
+        from _logger import log
+        log(domain, level, event, ok=ok, ms=ms, detail=detail)
+    except Exception:
+        pass
+
+
+# ---------------------------------------------------------------------------
+# Shared module imports — each wrapped so missing modules degrade gracefully
+# ---------------------------------------------------------------------------
+
+def _load_session_state():
+    try:
+        from _session import SessionState
+        return SessionState.load()
+    except Exception:
+        return None
+
+
+def _save_session_state(state):
+    try:
+        state.save()
+    except Exception:
+        pass
+
+
+def _check_prior_guard_findings():
+    """Load the most recent guard-pipeline findings and render a briefing note.
+
+    Reads ${TMPDIR}/wicked-guard/*/findings.json files written by stop.py's
+    guard pipeline (Issue #448).  Returns a briefing string or None.
+
+    Fail-open — never blocks bootstrap.
+    """
+    try:
+        import tempfile
+        guard_root = Path(tempfile.gettempdir()) / "wicked-guard"
+        if not guard_root.is_dir():
+            return None
+
+        newest = None  # type: ignore
+        newest_mtime = 0.0
+        for session_dir in guard_root.iterdir():
+            if not session_dir.is_dir():
+                continue
+            f = session_dir / "findings.json"
+            if not f.is_file():
+                continue
+            try:
+                mt = f.stat().st_mtime
+            except OSError:
+                continue
+            if mt > newest_mtime:
+                newest_mtime = mt
+                newest = f
+
+        if newest is None:
+            return None
+
+        # Only surface if report is recent (<24h) — stale reports are noise.
+        if (time.time() - newest_mtime) > 86400:
+            return None
+
+        with open(newest, "r", encoding="utf-8") as fh:
+            report = json.load(fh)
+
+        total = int(report.get("total_findings", 0) or 0)
+        if total == 0:
+            return None
+
+        by_sev = report.get("findings_by_severity", {}) or {}
+        profile = report.get("profile", "?")
+        lines = [
+            f"[Guard] Last session's {profile} guard pipeline surfaced {total} finding(s) "
+            f"(block={by_sev.get('block', 0)} warn={by_sev.get('warn', 0)} info={by_sev.get('info', 0)}). "
+            f"Report: {newest}"
+        ]
+        # Show up to 5 non-info findings for visibility
+        shown = 0
+        for check in report.get("checks", []) or []:
+            for f in check.get("findings", []) or []:
+                if shown >= 5:
+                    break
+                sev = f.get("severity", "info")
+                if sev == "info":
+                    continue
+                msg = f.get("message", "")[:140]
+                loc = ""
+                if f.get("file"):
+                    loc = f" @ {f['file']}"
+                    if f.get("line"):
+                        loc += f":{f['line']}"
+                lines.append(f"  - [{sev}] {f.get('rule_id', '?')}: {msg}{loc}")
+                shown += 1
+            if shown >= 5:
+                break
+        return "\n".join(lines)
+    except Exception:
+        return None
+
+
+def _probe_plugin_readiness():
+    """Dynamically discover installed plugins and probe their hook readiness.
+
+    Scans the plugin cache for installed plugins (excluding ourselves), finds
+    their hooks.json, and runs a lightweight test of each hook command.
+    Returns a list of dicts for plugins whose hooks fail, e.g.:
+        [{"name": "semgrep", "hook": "PostToolUse", "error": "No SEMGREP_APP_TOKEN found"}]
+
+    Runs with a tight timeout (2s per probe) and fails open — never blocks bootstrap.
+    """
+    unready = []
+    try:
+        # Discover plugin cache directories
+        cache_dirs = [
+            Path.home() / ".claude" / "plugins" / "cache",
+            Path(os.environ.get("CLAUDE_CONFIG_DIR", "")) / "plugins" / "cache" if os.environ.get("CLAUDE_CONFIG_DIR") else None,
+        ]
+        # Also check alt-configs location
+        alt_config = Path.home() / "alt-configs" / ".claude" / "plugins" / "cache"
+        if alt_config.exists():
+            cache_dirs.append(alt_config)
+
+        our_name = "wicked-garden"
+        seen_plugins = set()
+
+        for cache_dir in cache_dirs:
+            if cache_dir is None or not cache_dir.exists():
+                continue
+            # Walk plugin org/name directories
+            for org_dir in cache_dir.iterdir():
+                if not org_dir.is_dir():
+                    continue
+                for plugin_dir in org_dir.iterdir():
+                    if not plugin_dir.is_dir():
+                        continue
+                    # Find the actual plugin root (may be versioned)
+                    hooks_candidates = list(plugin_dir.rglob("hooks/hooks.json"))
+                    for hooks_file in hooks_candidates:
+                        plugin_root = hooks_file.parent.parent
+                        # Read plugin.json to get name
+                        pj = plugin_root / ".claude-plugin" / "plugin.json"
+                        if not pj.exists():
+                            pj = plugin_root / "plugin.json"
+                        plugin_name = plugin_dir.name
+                        if pj.exists():
+                            try:
+                                plugin_name = json.loads(pj.read_text()).get("name", plugin_dir.name)
+                            except Exception:
+                                pass
+
+                        # Skip ourselves and already-checked plugins
+                        if plugin_name == our_name or plugin_name in seen_plugins:
+                            continue
+                        seen_plugins.add(plugin_name)
+
+                        # Read their hooks.json
+                        try:
+                            hooks_data = json.loads(hooks_file.read_text())
+                        except Exception:
+                            continue
+
+                        # Probe each hook command with a dry-run (empty stdin, 2s timeout)
+                        for event, entries in hooks_data.get("hooks", {}).items():
+                            for entry in entries:
+                                for hook in entry.get("hooks", []):
+                                    cmd = hook.get("command", "")
+                                    if not cmd or hook.get("type") != "command":
+                                        continue
+                                    # Extract the base binary name for the probe
+                                    parts = cmd.split()
+                                    if not parts:
+                                        continue
+                                    binary = parts[0]
+                                    # Skip if binary references plugin root (needs env var)
+                                    if "${CLAUDE_PLUGIN_ROOT}" in cmd:
+                                        continue
+                                    # Quick probe: just check if the binary is available and
+                                    # runs without error when given empty input
+                                    try:
+                                        result = subprocess.run(
+                                            parts + ["--help"] if len(parts) == 1 else parts[:2] + ["--version"],
+                                            capture_output=True, text=True, timeout=2,
+                                            input="",
+                                        )
+                                        # If the command itself isn't found, skip — that's a
+                                        # different problem (missing install, not unready)
+                                    except FileNotFoundError:
+                                        continue  # Binary not installed — not our problem
+                                    except subprocess.TimeoutExpired:
+                                        continue  # Timed out — assume it works but is slow
+                                    except Exception:
+                                        continue
+
+                                    # For env-var-gated tools, check common auth patterns
+                                    # by looking at stderr for auth/token messages
+                                    if result.returncode != 0:
+                                        stderr = result.stderr.lower()
+                                        auth_signals = ["token", "login", "auth", "credential", "api_key", "api key"]
+                                        if any(sig in stderr for sig in auth_signals):
+                                            # Extract a short error message
+                                            err_lines = [l.strip() for l in result.stderr.strip().split("\n") if l.strip()]
+                                            short_err = err_lines[-1][:120] if err_lines else "auth required"
+                                            unready.append({
+                                                "name": plugin_name,
+                                                "hook": event,
+                                                "command": cmd[:80],
+                                                "error": short_err,
+                                            })
+                                            break  # One failure per plugin is enough
+                                    break  # Only test first hook per event
+                            if any(u["name"] == plugin_name for u in unready):
+                                break  # Already flagged this plugin
+    except Exception:
+        pass  # Fail open — probe errors never block bootstrap
+    return unready
+
+
+def _suggest_auth_fix(probe_result):
+    """Dynamically extract or infer an auth fix command from a probe failure.
+
+    Looks for common patterns in the error message (e.g., "please login", "run X login",
+    "set SOME_TOKEN") and returns the fix command. No hardcoded tool list — works by
+    parsing the error text that the tool itself produced.
+
+    Returns a fix command string, or None if no fix can be inferred.
+    """
+    error = probe_result.get("error", "")
+    name = probe_result.get("name", "")
+    cmd_base = probe_result.get("command", "").split()[0] if probe_result.get("command") else name
+
+    # Pattern 1: error says "run '<tool> login'" or "please login"
+    # e.g., "please login to Semgrep" → "semgrep login"
+    import re
+    login_match = re.search(r"(?:run|please)\s+['\"]?(\w[\w-]*\s+(?:login|auth\s+login))['\"]?", error, re.IGNORECASE)
+    if login_match:
+        return login_match.group(1)
+
+    # Pattern 2: error mentions a specific env var
+    # e.g., "No SEMGREP_APP_TOKEN found" → "export SEMGREP_APP_TOKEN=<your-token>"
+    env_match = re.search(r"(?:no|missing|set|need)\s+(\w+_(?:TOKEN|KEY|SECRET|API_KEY))\b", error, re.IGNORECASE)
+    if env_match:
+        var = env_match.group(1)
+        return f"export {var}=<your-token>  # or: {cmd_base} login"
+
+    # Pattern 3: generic "login" or "auth" mention
+    if "login" in error.lower() or "auth" in error.lower():
+        return f"{cmd_base} login"
+
+    return None
+
+
+def _load_agents():
+    """Load dynamic agents from disk. Returns (agent_count, agents_dict)."""
+    try:
+        from _agents import AgentLoader
+        loader = AgentLoader()
+        agents = loader.load_disk_agents(_PLUGIN_ROOT / "agents")
+        return len(agents), agents
+    except Exception as e:
+        print(f"[wicked-garden] agent load error: {e}", file=sys.stderr)
+        return 0, {}
+
+
+def _resolve_capabilities(agents, config=None):
+    """Run capability resolution for pre-loaded agents.
+
+    Returns dict[agent_name, tool_list] or empty dict on any error.
+    Fails open — never blocks bootstrap.
+    """
+    try:
+        from _capability_resolver import resolve_all_agents, discover_mcp_servers
+
+        mcp_servers = discover_mcp_servers()
+        return resolve_all_agents(agents, config, mcp_servers)
+    except Exception as e:
+        print(f"[wicked-garden] capability resolution error: {e}", file=sys.stderr)
+        return {}
+
+
+def _find_active_crew_project(workspace: str = ""):
+    """Return (project_data, project_name) for most recently updated active crew project
+    scoped to the given workspace.
+
+    Only returns projects whose ``workspace`` field matches the current folder.
+    Projects without a workspace field (legacy) are never auto-selected.
+
+    Uses DomainStore for consistent data access. Falls back to filesystem
+    scan if DomainStore fails (legacy compat for one release).
+    """
+    try:
+        from _domain_store import DomainStore
+        ds = DomainStore("wicked-crew", hook_mode=True)
+        projects = ds.list("projects") or []
+        # Sort by updated_at descending, return first non-archived, non-complete
+        # that matches the current workspace
+        for p in sorted(projects, key=lambda x: x.get("updated_at", ""), reverse=True):
+            if p.get("archived"):
+                continue
+            # Workspace scoping — skip projects from other workspaces
+            if workspace and p.get("workspace", "") != workspace:
+                continue
+            phase = p.get("current_phase", "")
+            if phase and phase != "complete":
+                return p, p.get("name")
+        return None, None
+    except Exception:
+        pass
+
+    # Legacy fallback: direct filesystem scan (remove after one release)
+    return _find_active_crew_project_legacy(workspace)
+
+
+def _find_active_crew_project_legacy(workspace: str = ""):
+    """Filesystem-based crew project scan. Legacy fallback."""
+    projects_dir = Path.home() / ".something-wicked" / "wicked-crew" / "projects"
+    if not projects_dir.exists():
+        return None, None
+
+    for pf in sorted(
+        projects_dir.glob("*/project.json"),
+        key=lambda p: p.stat().st_mtime,
+        reverse=True,
+    ):
+        try:
+            data = json.loads(pf.read_text())
+            if data.get("archived"):
+                continue
+            # Workspace scoping — skip projects from other workspaces
+            if workspace and data.get("workspace", "") != workspace:
+                continue
+            phase = data.get("current_phase", "")
+            if phase and phase != "complete":
+                return data, data.get("name", pf.parent.name)
+        except (json.JSONDecodeError, OSError):
+            continue
+
+    return None, None
+
+
+def _brain_api(action, params=None, timeout=3):
+    """Call brain API. Returns parsed JSON or None."""
+    try:
+        import urllib.request
+        port = resolve_port()
+        payload = json.dumps({"action": action, "params": params or {}}).encode("utf-8")
+        req = urllib.request.Request(
+            f"http://localhost:{port}/api",
+            data=payload,
+            headers={"Content-Type": "application/json"},
+            method="POST",
+        )
+        with urllib.request.urlopen(req, timeout=timeout) as resp:  # nosem: python.lang.security.audit.dynamic-urllib-use-detected.dynamic-urllib-use-detected -- URL is f"http://localhost:{port}/api" with int-validated port from resolve_port()
+            return json.loads(resp.read().decode("utf-8"))
+    except Exception:
+        return None
+
+
+def _run_memory_decay():
+    """Run memory decay maintenance via brain lint. Returns a summary string or None."""
+    try:
+        result = _brain_api("lint", {}, timeout=5)
+        if result and (result.get("archived", 0) > 0 or result.get("deleted", 0) > 0):
+            return f"Memory: {result.get('archived', 0)} archived, {result.get('deleted', 0)} cleaned"
+        return None
+    except Exception:
+        return None
+
+
+def _check_search_staleness():
+    """Check brain index health. Returns a briefing note or None.
+
+    Brain is the unified knowledge layer — no legacy SQLite fallback.
+    Fails open — any exception returns None so the session always continues.
+    """
+    stats = _brain_api("stats", {}, timeout=2)
+    if stats is None:
+        # Deterministic auto-start — server lifecycle is a hook job, not a
+        # model directive. ensure_server is lock-safe and fails open.
+        try:
+            from _brain_port import ensure_server
+            if ensure_server():
+                stats = _brain_api("stats", {}, timeout=2)
+        except Exception:
+            pass
+    if stats is None:
+        return (
+            "Brain server unreachable and auto-start failed — run "
+            "`wicked-brain-call --start` to see the cause. Brain skills "
+            "auto-start the server on every call; do NOT skip brain usage."
+        )
+    if stats.get("total", 0) == 0:
+        return "Brain index is empty — run `wicked-brain:ingest` to index your codebase"
+    return None  # Brain is healthy
+
+
+def _check_onboarding_status():
+    """Check if the current project has been onboarded (search index + memories).
+
+    Returns (has_index, has_memories, directive_or_none).
+    Fails open when the brain is unreachable: transient API errors must not be
+    interpreted as "this project was never onboarded". Per-install setup state
+    is enforced separately by _check_setup_gate in prompt_submit.py — that
+    flag is user-level (~/.something-wicked/wicked-garden/config.json), not
+    per-project, so it cannot answer the per-project onboarding question here.
+    """
+    project = os.environ.get("CLAUDE_PROJECT_NAME") or Path.cwd().name
+    cwd = str(Path.cwd())
+
+    has_index = False
+    has_memories = False  # default: assume not onboarded (fail-closed for new projects)
+
+    # Check search index — brain is the knowledge layer
+    stats = _brain_api("stats", {}, timeout=2)
+    brain_reachable = stats is not None
+    if stats and stats.get("total", 0) > 0:
+        has_index = True
+
+    # If brain is unreachable, we cannot determine onboarding state — fail open.
+    # Brain unavailability is surfaced separately by _check_brain_dependency.
+    if not brain_reachable:
+        return False, True, None
+
+    # Check for any stored memories (broad: any brain result, not just /mem- paths).
+    # If brain has an index with content (has_index=True), that alone is sufficient
+    # evidence that the project has been set up — skip the memory search.
+    if has_index:
+        has_memories = True  # indexed brain content ≡ project was onboarded
+    else:
+        result = _brain_api("search", {"query": "project memory onboarding", "limit": 5}, timeout=3)
+        if result is None:
+            # Brain went unreachable between calls — fail open.
+            return False, True, None
+        if isinstance(result, list) and result:
+            has_memories = True
+        elif isinstance(result, dict) and result.get("results"):
+            has_memories = True
+
+    directive = None
+    if not has_index and not has_memories:
+        # Neither index nor memories → first-time setup required
+        directive = (
+            f"[Action Required] Project '{project}' has not been onboarded.\n"
+            "You MUST immediately invoke the Skill tool with skill='wicked-garden:setup' "
+            "to launch the interactive onboarding wizard.\n"
+            "Do NOT ask the user for confirmation — invoke the skill now.\n"
+            "Do NOT respond with text first — invoke the skill as your first action."
+        )
+    elif not has_index and has_memories:
+        # Memories exist but brain index is gone → rebuild only
+        directive = (
+            f"[Onboarding] IMPORTANT: Project '{project}' has memories but no search index. "
+            "You MUST run /wicked-garden:search:index now to build the search index."
+        )
+
+    return has_index, has_memories, directive
+
+
+def _read_config():
+    """Read config from ~/.something-wicked/wicked-garden/config.json."""
+    config_path = Path.home() / ".something-wicked" / "wicked-garden" / "config.json"
+    if not config_path.exists():
+        return None
+    try:
+        return json.loads(config_path.read_text())
+    except (json.JSONDecodeError, OSError):
+        return None
+
+
+# v9.2.11 deleted _MEMORY_INSTRUCTIONS. v9.2.10 stopped APPENDING it to the
+# briefing (CLAUDE.md "Memory Management" section already overrides the
+# system-level auto-memory instructions); v9.2.11 confirmed zero imports
+# across hooks/, scripts/, tests/, commands/ and removed the dead constant.
+# Same cleanup pattern as the v9.2.10 yolo test deletion — a constant kept
+# alive only by a test that asserts it exists is a tautology.
+
+_DANGEROUS_MODE_WARNING = (
+    "[Question Mode] Dangerous mode is active (skipDangerousModePermissionPrompt). "
+    "AskUserQuestion is BROKEN in this mode — it auto-completes with empty answers. "
+    "You MUST use plain text questions instead: present numbered options, "
+    "then STOP and wait for the user to reply before proceeding."
+)
+
+
+# ---------------------------------------------------------------------------
+# Dangerous mode detection
+# ---------------------------------------------------------------------------
+
+def _detect_dangerous_mode():
+    """Check if Claude Code is running in dangerous mode.
+
+    Dangerous mode (skipDangerousModePermissionPrompt=true) breaks
+    AskUserQuestion by auto-completing it with empty answers.
+    """
+    try:
+        settings_path = Path.home() / ".claude" / "settings.json"
+        if settings_path.exists():
+            settings = json.loads(settings_path.read_text())
+            return bool(settings.get("skipDangerousModePermissionPrompt"))
+    except Exception:
+        pass
+    return False
+
+
+
+# ---------------------------------------------------------------------------
+# wicked-brain dependency check
+# ---------------------------------------------------------------------------
+
+def _check_brain_dependency():
+    """Check whether the wicked-brain plugin is installed.
+
+    Scans ~/.claude/settings.json and .claude/settings.json (project-level)
+    for 'wicked-brain' in their enabledPlugins keys.
+
+    If found:
+        - Returns (True, None) — no briefing note needed.
+        - Also attempts a lightweight server health probe on the default port
+          and returns (True, note) where note describes the offline state if
+          the server is not reachable.
+
+    If NOT found:
+        - Returns (False, note) — note contains the install instruction.
+
+    Always fails open — any exception returns (None, None) so the session
+    is never blocked.
+    """
+    try:
+        # Settings file locations to check (global first, then project-local)
+        settings_candidates = [
+            Path.home() / ".claude" / "settings.json",
+            Path(".claude") / "settings.json",
+        ]
+
+        # Also honour CLAUDE_CONFIG_DIR if set
+        config_dir_env = os.environ.get("CLAUDE_CONFIG_DIR")
+        if config_dir_env:
+            settings_candidates.append(Path(config_dir_env) / "settings.json")
+
+        brain_installed = False
+
+        # Check 1: enabledPlugins in settings.json (plugin-style install)
+        for settings_path in settings_candidates:
+            try:
+                if not settings_path.exists():
+                    continue
+                settings = json.loads(settings_path.read_text(encoding="utf-8"))
+                enabled = settings.get("enabledPlugins", {})
+                if isinstance(enabled, dict) and "wicked-brain" in enabled:
+                    brain_installed = True
+                    break
+                if isinstance(enabled, list) and "wicked-brain" in enabled:
+                    brain_installed = True
+                    break
+            except (json.JSONDecodeError, OSError):
+                continue
+
+        # Check 2: loose skill installs at ~/.claude/skills/wicked-brain-*
+        # Users can install wicked-brain skills directly without the plugin wrapper.
+        if not brain_installed:
+            try:
+                skills_dir = Path.home() / ".claude" / "skills"
+                if skills_dir.exists():
+                    for entry in skills_dir.iterdir():
+                        if entry.is_dir() and entry.name.startswith("wicked-brain"):
+                            brain_installed = True
+                            break
+            except OSError:
+                pass  # fail open
+
+        # Check 3: CLAUDE_CONFIG_DIR skills directory
+        if not brain_installed and config_dir_env:
+            try:
+                alt_skills_dir = Path(config_dir_env) / "skills"
+                if alt_skills_dir.exists():
+                    for entry in alt_skills_dir.iterdir():
+                        if entry.is_dir() and entry.name.startswith("wicked-brain"):
+                            brain_installed = True
+                            break
+            except OSError:
+                pass  # fail open
+
+        if not brain_installed:
+            note = (
+                "[wicked-brain] optional layer not installed.\n"
+                "Add it for cross-session memory + cited search: claude plugin install wicked-brain --scope project\n"
+                "The toolkit works without it — you lose the memory/context layer "
+                "(cross-session recall, brain-backed search, smaht:briefing)."
+            )
+            return False, note
+
+        # wicked-brain is installed — probe server health and auto-start on
+        # miss. _brain_api returns None on any error (server not running,
+        # connection refused, timeout, parse error); ensure_server is the
+        # deterministic fix for the "not running" case and fails open.
+        server_note = None
+        if _brain_api("health", {}, timeout=1) is None:
+            started = False
+            try:
+                from _brain_port import ensure_server
+                started = ensure_server()
+            except Exception:
+                pass
+            if started:
+                server_note = "[wicked-brain] Server was down — auto-started for this session."
+            else:
+                server_note = (
+                    "[wicked-brain] Plugin installed but the server could not be "
+                    "auto-started. Diagnose with `wicked-brain-call --start` "
+                    "(log: {brain}/_meta/server.log). Brain skills auto-start the "
+                    "server on every call — do NOT skip brain usage."
+                )
+
+        return True, server_note
+
+    except Exception:
+        return None, None  # Fail open — never block session start
+
+
+# ---------------------------------------------------------------------------
+# wicked-vault dependency check (required evidence backend)
+# ---------------------------------------------------------------------------
+
+def _check_vault_dependency():
+    """Return a briefing note if wicked-vault is not resolvable, else None.
+
+    wicked-vault is a required peer (sibling to wicked-bus / wicked-brain /
+    wicked-testing): every archetype produces-gate re-derives against it via
+    ``scripts/qe/vault_gate.py``. When it is absent those gates fail closed,
+    so we surface a one-line install pointer at SessionStart.
+
+    Fast + stdlib-only (no subprocess to npx): checks PATH and loose skill
+    installs only. Always fails open — never blocks the session.
+    """
+    try:
+        import shutil
+
+        # WICKED_VAULT_BIN explicitly set (even empty kill-switch) → operator
+        # is driving resolution deliberately; don't nag.
+        if "WICKED_VAULT_BIN" in os.environ:
+            return None
+
+        if shutil.which("wicked-vault"):
+            return None
+
+        # Loose skill installs land as skills/wicked-vault-*/ under each CLI
+        # config root (npx wicked-vault-install). PATH miss + skills present
+        # still means the CLI runs via npx, so treat skills as "installed".
+        skill_roots = [Path.home() / ".claude" / "skills"]
+        cfg = os.environ.get("CLAUDE_CONFIG_DIR")
+        if cfg:
+            skill_roots.append(Path(cfg) / "skills")
+        for root in skill_roots:
+            try:
+                if root.exists():
+                    for entry in root.iterdir():
+                        if entry.is_dir() and entry.name.startswith("wicked-vault"):
+                            return None
+            except OSError:
+                continue  # fail open
+
+        return (
+            "[wicked-vault] REQUIRED but not installed.\n"
+            "Install now: npx wicked-vault-install  (or: npm i -g wicked-vault)\n"
+            "wicked-vault is the evidence backend wicked-loom re-runs every "
+            "gate's verifier against — without it, produces-gates fail closed."
+        )
+    except Exception:
+        return None  # Fail open — never block session start
+
+
+def _check_loom_dependency():
+    """Return a briefing note if loom peer-resolution is unavailable, else None.
+
+    After the Phase B absorption (ECOSYSTEM-RATIONALIZATION.md §5a), the
+    wicked-loom peer-resolution surface (resolve/doctor/compose/gate) is
+    internal to wicked-garden — absorbed into scripts/loom/. External
+    installation of the standalone wicked-loom npm package is no longer
+    required.
+
+    This function returns None (no warning) when the absorbed internal module
+    is present, which is always the case in a properly installed wicked-garden.
+    The legacy external-binary checks are retained as a fallback for
+    environments that may be running a partial or development install.
+
+    Always fails open — never blocks the session start.
+    """
+    try:
+        # Primary check: internal absorbed module (scripts/loom/).
+        # In a properly installed wicked-garden this always resolves.
+        _scripts_dir = Path(__file__).resolve().parents[2] / "scripts"
+        if (_scripts_dir / "loom" / "__init__.py").exists():
+            return None  # Absorbed internally — no external install needed.
+
+        # Kill-switch / operator override: don't nag when deliberately managed.
+        if "WICKED_LOOM_BIN" in os.environ:
+            return None
+        if os.environ.get("WICKED_LOOM_CUTOVER", "").strip().lower() == "off":
+            return None
+
+        # Legacy external-binary check (development / partial installs only).
+        if shutil.which("wicked-loom"):
+            return None
+
+        skill_roots = [Path.home() / ".claude" / "skills"]
+        cfg = os.environ.get("CLAUDE_CONFIG_DIR")
+        if cfg:
+            skill_roots.append(Path(cfg) / "skills")
+        for root in skill_roots:
+            try:
+                if root.exists():
+                    for entry in root.iterdir():
+                        if entry.is_dir() and entry.name.startswith("wicked-loom"):
+                            return None
+            except OSError:
+                continue  # fail open
+
+        # No loom surface found — surface a note (never a block).
+        return (
+            "[loom] Peer-resolution runtime not found.\n"
+            "wicked-loom is now absorbed into wicked-garden — reinstall "
+            "wicked-garden to restore the peer-resolution surface.\n"
+            "Without it the produces-gate fails closed."
+        )
+    except Exception:
+        return None  # Fail open — never block session start
+
+
+# ---------------------------------------------------------------------------
+# wicked-bus dependency check (required event backbone)
+# ---------------------------------------------------------------------------
+
+def _check_bus_dependency():
+    """Return a briefing note if wicked-bus is not installed, else None.
+
+    wicked-bus is a required peer (sibling to wicked-brain / wicked-vault /
+    wicked-testing): the garden's archetype events flow through it. When it
+    is absent, cross-plugin event wiring is silently dropped, so we surface a
+    one-line install pointer at SessionStart.
+
+    Detection mirrors ``_check_brain_dependency`` — wicked-bus installs as a
+    Claude Code *plugin*, not an npx CLI, so we verify by presence:
+      1. ``enabledPlugins`` in ~/.claude/settings.json, project-local
+         .claude/settings.json, and CLAUDE_CONFIG_DIR/settings.json.
+      2. Loose skill installs at ``skills/wicked-bus-*`` under the home and
+         CLAUDE_CONFIG_DIR skills directories.
+
+    Fast + stdlib-only (no subprocess). Always fails open — never blocks the
+    session.
+    """
+    try:
+        # Settings file locations to check (global first, then project-local)
+        settings_candidates = [
+            Path.home() / ".claude" / "settings.json",
+            Path(".claude") / "settings.json",
+        ]
+
+        # Also honour CLAUDE_CONFIG_DIR if set
+        config_dir_env = os.environ.get("CLAUDE_CONFIG_DIR")
+        if config_dir_env:
+            settings_candidates.append(Path(config_dir_env) / "settings.json")
+
+        bus_installed = False
+
+        # Check 1: enabledPlugins in settings.json (plugin-style install)
+        for settings_path in settings_candidates:
+            try:
+                if not settings_path.exists():
+                    continue
+                settings = json.loads(settings_path.read_text(encoding="utf-8"))
+                enabled = settings.get("enabledPlugins", {})
+                if isinstance(enabled, dict) and "wicked-bus" in enabled:
+                    bus_installed = True
+                    break
+                if isinstance(enabled, list) and "wicked-bus" in enabled:
+                    bus_installed = True
+                    break
+            except (json.JSONDecodeError, OSError):
+                continue
+
+        # Check 2: loose skill installs at skills/wicked-bus-* under the home
+        # and CLAUDE_CONFIG_DIR skills directories.
+        if not bus_installed:
+            skill_roots = [Path.home() / ".claude" / "skills"]
+            if config_dir_env:
+                skill_roots.append(Path(config_dir_env) / "skills")
+            for root in skill_roots:
+                try:
+                    if root.exists():
+                        for entry in root.iterdir():
+                            if entry.is_dir() and entry.name.startswith("wicked-bus"):
+                                bus_installed = True
+                                break
+                except OSError:
+                    continue  # fail open
+                if bus_installed:
+                    break
+
+        if not bus_installed:
+            return (
+                "[wicked-bus] optional layer not installed.\n"
+                "Add it for the cross-session audit trail: /plugin install wicked-bus\n"
+                "The toolkit works without it — events are simply not recorded "
+                "(emission is already fire-and-forget / fail-open)."
+            )
+
+        return None
+    except Exception:
+        return None  # Fail open — never block session start
+
+
+# ---------------------------------------------------------------------------
+# Discovery: contextual command suggestions based on project type (Issue #322)
+# ---------------------------------------------------------------------------
+
+def _check_facilitator_context(project_name: str | None) -> str | None:
+    """Return a briefing line for unresolved action items aged >= 2 sessions.
+
+    Lazily imports ``scripts.delivery.process_memory`` so environments that
+    do not ship that module (pre-#447 plugin installs) continue to boot.
+    Returns a short ``[ProcessMemory]`` line when the project has any
+    aging AIs, or ``None`` when:
+
+    - No active project was detected (nothing to surface for).
+    - ``delivery.process_memory`` is not importable (fail-open).
+    - The project has no unresolved action items at the aging threshold.
+    - Any exception is raised while reading the memory file.
+
+    Matches the fail-open pattern used by ``_run_quality_telemetry`` and
+    the guard pipeline in ``stop.py``.
+    """
+    if not project_name:
+        return None
+    try:
+        # Lazy import — absence must NOT break bootstrap on legacy installs.
+        sys.path.insert(0, str(_PLUGIN_ROOT / "scripts" / "delivery"))
+        try:
+            import process_memory as _pm  # type: ignore
+        except ImportError as exc:
+            print(
+                f"[wicked-garden] process_memory not importable ({exc!r}); "
+                "skipping facilitator context",
+                file=sys.stderr,
+            )
+            return None
+
+        ctx = _pm.facilitator_context(project_name)
+        aging = ctx.get("aging_action_items", []) if isinstance(ctx, dict) else []
+        if not aging:
+            return None
+
+        # Show up to 3 AIs inline so the line stays readable; rest are
+        # countable via the summary prefix and fully visible via
+        # process-memory.md on disk.
+        shown = aging[:3]
+        preview = ", ".join(
+            f"{ai.get('id', '?')} \"{(ai.get('title') or '')[:60]}\""
+            for ai in shown
+        )
+        more = f" (+{len(aging) - len(shown)} more)" if len(aging) > len(shown) else ""
+        return (
+            f"[ProcessMemory] {len(aging)} unresolved action item(s) "
+            f">=2 sessions old: {preview}{more}"
+        )
+    except Exception as exc:
+        # Fail-open: never block session start on process-memory errors.
+        print(
+            f"[wicked-garden] facilitator_context error: {exc!r}",
+            file=sys.stderr,
+        )
+        return None
+
+
+def _probe_onedrive_path() -> str | None:
+    """Detect if cwd is under a OneDrive or CloudStorage path with spaces.
+
+    On macOS, OneDrive-synced directories live under paths like:
+        ~/Library/CloudStorage/OneDrive - CompanyName/...
+    The spaces cause failures when paths are not properly quoted.
+
+    Returns the resolved canonical base path (via Path.resolve()), or None
+    if cwd is not under a OneDrive/CloudStorage directory.
+    Fails open — any error returns None.
+    """
+    try:
+        cwd = Path.cwd()
+        cwd_str = str(cwd)
+        if "OneDrive" in cwd_str or "CloudStorage" in cwd_str:
+            resolved = cwd.resolve()
+            return str(resolved)
+    except Exception:
+        pass
+    return None
+
+
+# Critical v6 skills — if these files exist on disk under the plugin root
+# but a Skill() call fails with "Unknown skill", the plugin cache is stale
+# and needs `/reload-plugins`. Issue #434.
+_CRITICAL_V11_SKILLS = (
+    "skills/archetype/SKILL.md",
+)
+
+
+# v9.2.10 — first-session-per-project gating for informational briefing notices.
+# Both `[Setup]` and `[Quick Start]` are useful exactly once per project; on
+# every subsequent session they are pure noise. The sentinel file lives under
+# the wicked-garden local store (per-project automatically because
+# `get_local_path` resolves under the active project's slug), so a fresh
+# project sees the notices on its first session and never again.
+
+_BOOTSTRAP_NOTICE_FILE = "shown.json"
+_NOTICE_SETUP = "setup_reconfigure"
+_NOTICE_QUICK_START = "quick_start"
+
+
+def _notice_path() -> "Path | None":
+    """Resolve the per-project sentinel file path. None on resolution failure."""
+    try:
+        # Lazy import — keeps bootstrap fail-open if scripts/ is unreachable.
+        sys.path.insert(0, str(_PLUGIN_ROOT / "scripts"))
+        from _domain_store import get_local_path  # type: ignore
+        return get_local_path("wicked-garden", "bootstrap-notices") / _BOOTSTRAP_NOTICE_FILE
+    except Exception:
+        return None
+
+
+def _notice_already_shown(notice_id: str) -> bool:
+    """Return True if `notice_id` has been emitted for this project before."""
+    p = _notice_path()
+    if p is None or not p.exists():
+        return False
+    try:
+        data = json.loads(p.read_text(encoding="utf-8"))
+        return notice_id in data
+    except (json.JSONDecodeError, OSError):
+        return False
+
+
+def _record_notice_shown(notice_id: str) -> None:
+    """Record `notice_id` as shown. Best-effort; failures don't block bootstrap."""
+    p = _notice_path()
+    if p is None:
+        return
+    try:
+        p.parent.mkdir(parents=True, exist_ok=True)
+        data = {}
+        if p.exists():
+            try:
+                data = json.loads(p.read_text(encoding="utf-8"))
+            except (json.JSONDecodeError, OSError):
+                data = {}
+        data[notice_id] = {"shown_at": datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")}
+        p.write_text(json.dumps(data), encoding="utf-8")
+    except OSError:
+        pass  # fail open
+
+
+def _check_critical_skills() -> str | None:
+    """Verify critical v6 skill files are present in the plugin root.
+
+    Claude Code's skill registry is cached at plugin-install time. When the
+    plugin ships a new skill mid-version, the cache lags until the user runs
+    `/reload-plugins`. We can't query the live registry from a hook — but we
+    can check the files exist on disk and emit a diagnostic directive so an
+    "Unknown skill" error surfaces a fix path instead of being cryptic.
+
+    Returns a directive string ONLY when one or more critical skills are
+    missing from disk (a real install problem). The previous "happy path"
+    message — "skills are present; if Skill() fails, run /reload-plugins" —
+    fired every session even with a clean install and was chronic noise. A
+    user who has hit a cache-stale failure once knows the fix; emitting it
+    on every healthy session adds no signal. v9.2.10 dropped that branch.
+
+    Fails open on errors.
+    """
+    try:
+        plugin_root = os.environ.get("CLAUDE_PLUGIN_ROOT")
+        if not plugin_root:
+            return None
+        root = Path(plugin_root)
+        missing = [s for s in _CRITICAL_V11_SKILLS if not (root / s).exists()]
+        if not missing:
+            return None  # healthy install — nothing to say
+        return (
+            "[Skills] Critical v6 skill files are missing from the plugin root:\n"
+            + "\n".join(f"  - {s}" for s in missing)
+            + "\nThe plugin install is incomplete. Reinstall with "
+            "`claude plugin install wicked-garden --scope project`."
+        )
+    except Exception:
+        return None  # fail open — never block bootstrap
+
+
+def _suggest_commands_for_project() -> str | None:
+    """Detect project type from files in cwd and suggest 2-3 relevant commands.
+
+    Lightweight: checks only for a few marker files (no directory walks).
+    Returns a formatted suggestion string, or None if no suggestions apply.
+    """
+    try:
+        cwd = Path.cwd()
+        suggestions = []
+
+        # Detect project signals from marker files
+        has_package_json = (cwd / "package.json").exists()
+        has_pyproject = (cwd / "pyproject.toml").exists() or (cwd / "setup.py").exists()
+        has_dockerfile = (cwd / "Dockerfile").exists() or (cwd / "docker-compose.yml").exists()
+        has_terraform = (cwd / "main.tf").exists() or (cwd / "terraform").is_dir()
+        has_tests = (
+            (cwd / "tests").is_dir() or (cwd / "test").is_dir()
+            or (cwd / "__tests__").is_dir() or (cwd / "spec").is_dir()
+        )
+        has_csv_data = any(cwd.glob("*.csv")) or (cwd / "data").is_dir()
+        has_ci = (cwd / ".github" / "workflows").is_dir()
+
+        # Always useful
+        suggestions.append("`wicked-brain:search` — semantic code search")
+        suggestions.append("`/wicked-garden:engineering:review` — structured code review")
+
+        # Project-type-specific
+        if has_tests:
+            suggestions.append("`/wicked-testing:plan` — generate test plan and scenarios")
+        if has_dockerfile or has_terraform:
+            suggestions.append("`/wicked-garden:platform:security` — security review")
+        if has_csv_data:
+            suggestions.append("`/wicked-garden:data:analyze` — interactive data analysis with DuckDB")
+        if has_ci:
+            suggestions.append("`/wicked-garden:platform:actions` — GitHub Actions optimization")
+
+        # Cap at 3 suggestions
+        suggestions = suggestions[:3]
+
+        if not suggestions:
+            return None
+
+        return (
+            "[Quick Start] Available commands for this project:\n"
+            + "\n".join(f"  - {s}" for s in suggestions)
+        )
+    except Exception:
+        return None
+
+
+# ---------------------------------------------------------------------------
+# #506 — WG_GATE_RESULT_STRICT_AFTER pre-flip monitoring
+#
+# Surfaces a visible warning as the strict-mode cutover approaches so
+# operators aren't surprised when orphan gate-results start rejecting.
+# Thresholds (T = days until flip, computed in UTC):
+#   T > 7       silent
+#   7 >= T >= 1 stderr WARN, every SessionStart
+#   T == 0      stderr INFO, one-time per session (latched via
+#               SessionState.strict_mode_active_announced)
+#   T < 0       stderr INFO, same one-time latch (post-flip banner)
+#
+# Fail-open: malformed dates fall back to the module default and the
+# signal is skipped silently rather than blocking bootstrap.
+# ---------------------------------------------------------------------------
+
+
+def _check_pre_flip_notice(state, today=None) -> None:
+    """Emit pre-flip / post-flip monitoring signals on stderr.
+
+    Arguments:
+        state: The loaded SessionState (or None). When None, the
+            post-flip banner still fires but won't latch — next
+            SessionStart in the same session may re-fire, which is
+            the expected degrade.
+        today: ``datetime.date`` override for deterministic tests.
+            Production callers pass ``None`` and the helper uses
+            today's UTC date.
+    """
+    try:
+        # Lazy import — keeps hook cheap; dispatch_log is in the crew
+        # scripts dir which is already on sys.path via the hook bootstrap.
+        sys.path.insert(0, str(_PLUGIN_ROOT / "scripts" / "crew"))
+        from dispatch_log import (  # type: ignore
+            DEFAULT_STRICT_AFTER,
+            _get_strict_after_date,
+        )
+    except Exception:
+        return  # fail-open: module unavailable, skip the signal
+
+    try:
+        from datetime import datetime, timezone
+
+        flip_date = _get_strict_after_date()
+        if today is None:
+            today = datetime.now(timezone.utc).date()
+        delta_days = (flip_date - today).days
+        raw_env_val = os.environ.get("WG_GATE_RESULT_STRICT_AFTER", "").strip()
+        # Display the user-supplied value when it parsed; otherwise show
+        # the effective default. A malformed env-var produces the fallback
+        # WARN in ``_get_strict_after_date`` already — we don't duplicate.
+        if raw_env_val and flip_date.isoformat() == raw_env_val:
+            raw_env = raw_env_val
+        else:
+            raw_env = flip_date.isoformat()
+
+        if delta_days > 7:
+            return  # silent
+
+        if 1 <= delta_days <= 7:
+            sys.stderr.write(
+                f"[PreFlipNotice] Strict-mode activation in {delta_days} "
+                f"days (WG_GATE_RESULT_STRICT_AFTER={raw_env}). "
+                "Orphan gate-result files will start rejecting.\n"
+            )
+            return
+
+        # delta_days <= 0 → post-flip; emit one-time-per-session INFO.
+        already = bool(getattr(state, "strict_mode_active_announced", False)) \
+            if state is not None else False
+        if already:
+            return
+        sys.stderr.write(
+            f"[StrictMode] Strict-mode active (flipped on "
+            f"{flip_date.isoformat()}). Any orphan gate-result now rejects.\n"
+        )
+        if state is not None:
+            try:
+                state.update(strict_mode_active_announced=True)
+            except Exception:  # pragma: no cover — defensive
+                pass  # session-state write failure: banner may re-fire, acceptable
+    except Exception:
+        # Signal computation errors must never block bootstrap.
+        return
+
+
+# ---------------------------------------------------------------------------
+# #544 — wicked-testing peer-plugin probe (AC-1 through AC-6)
+# ---------------------------------------------------------------------------
+
+# Module-level list of blocking notices to inject into session briefing.
+# Populated by _probe_wicked_testing(); consumed by main() before building
+# the briefing. At most one entry per session (the probe runs once).
+_wt_blocking_notices: list = []
+
+
+def _probe_wicked_testing(state) -> None:
+    """Run the wicked-testing availability probe once per session.
+
+    Caches the result in SessionState.extras["wicked_testing_probe"] so
+    crew_command_gate() can read it without re-running the subprocess.
+
+    Session cache semantics:
+      - Probe runs exactly once at SessionStart (first call after fresh state).
+      - SessionState is cleared on session reset (session_ended path above),
+        so a new session always re-probes. No cross-session persistence.
+      - Re-entrant guard: if the probe key is already present, return early.
+
+    Fail-open boundary: exceptions that escape this function are caught by
+    the calling try/except in main() which returns {"continue": true}.
+    This matches every other probe in bootstrap.py.
+
+    CH-02 hardening: the exception handler logs actionable detail, NOT just
+    the bare exception string. crew_command_gate() closes the fail-open gap
+    at the crew layer by treating an absent probe key as missing.
+    """
+    try:
+        # Re-entrant guard: probe runs at most once per session.
+        extras = getattr(state, "extras", None) or {}
+        if "wicked_testing_probe" in extras:
+            return
+
+        # Import the probe from the scripts/ directory (already on sys.path
+        # from the top of bootstrap.py).
+        from _wicked_testing_probe import probe
+
+        result = probe(state)
+
+        missing = result["status"] != "ok"
+        new_extras = {**extras, "wicked_testing_probe": result}
+
+        if state is not None:
+            state.update(
+                wicked_testing_missing=missing,
+                extras=new_extras,
+            )
+
+        # Emit a blocking notice into the session briefing (once per session).
+        # crew_command_gate() only emits a pointer back, suppressing the full
+        # notice on repeat invocations within the same session (AC-2).
+        if result["status"] == "missing":
+            _wt_blocking_notices.append(
+                "[wicked-testing] wicked-testing is not installed.\n"
+                "wicked-testing required — run: npx wicked-testing install\n"
+                "Crew commands (start, execute, just-finish) are blocked until "
+                "wicked-testing is installed."
+            )
+        elif result["status"] == "out-of-range":
+            ver = result.get("version", "unknown")
+            pin = result.get("pin", "unknown")
+            _wt_blocking_notices.append(
+                f"[wicked-testing] wicked-testing {ver} does not satisfy required range {pin}.\n"
+                "wicked-testing required — run: npx wicked-testing install\n"
+                "Crew commands (start, execute, just-finish) are blocked until "
+                "the correct version is installed."
+            )
+        elif result["status"] == "error":
+            err = result.get("error", "unknown error")
+            _wt_blocking_notices.append(
+                f"[wicked-testing] probe error: {err}\n"
+                "Crew commands are blocked. If this is a transient error, "
+                "restart the session. Use WG_SKIP_WICKED_TESTING_CHECK=1 for "
+                "offline dev mode (CONTRIBUTING.md)."
+            )
+        # "ok" and "skipped" → silent (AC-6, AC-5)
+
+    except Exception as exc:
+        # CH-02 hardening: log actionable context so operators can diagnose.
+        # Include what failed and where (not just the bare exception string).
+        print(
+            f"[wicked-garden] wicked-testing probe failed: "
+            f"exception={exc!r} "
+            f"probe_module='_wicked_testing_probe' "
+            f"action='npx wicked-testing --version' "
+            f"note='crew_command_gate will treat absent probe key as missing'",
+            file=sys.stderr,
+        )
+        # Fail-open at this boundary: do NOT block bootstrap.
+        # crew_command_gate() is fail-closed for the absent-key case (CH-02).
+        if state is not None:
+            try:
+                state.update(wicked_testing_missing=False)
+            except Exception:
+                pass  # session-state write failure — acceptable
+
+
+# ---------------------------------------------------------------------------
+# Registry allowlist validation
+#
+# Walks in-code allowlists (phase fallback agents, gate-policy reviewers,
+# bus event handlers, agent skill references) and confirms each referenced
+# asset exists on disk / in catalog.  Catches the "invisible gap" failure
+# mode where probe traffic passes but the first request that hits the
+# missing asset blows up with a cryptic error.
+#
+# Fail-OPEN per the hook contract: any exception, any timeout, any malformed
+# allowlist surfaces as a session-briefing warning — never blocks bootstrap.
+# Findings categorised as `missing` / `malformed` / `invalid_id` are blocking
+# (CI-fail) but the bootstrap path only WARNs.  External (drop-in plugin)
+# and skipped checks are advisory.
+# ---------------------------------------------------------------------------
+
+
+def _run_registry_validation() -> str | None:
+    """Run the aggregated registry validator and return a briefing line.
+
+    Returns a multi-line string when findings exist, or None when the
+    registry is fully clean (or the validator is unavailable).  Caller
+    is expected to append the result to `mode_notes` so it surfaces as
+    a SessionStart [Registry] warning.
+
+    Fail-open boundary: any exception returns None.  Validator timing
+    is bounded by file IO (no subprocess, no network), so we trust it
+    to complete inside the bootstrap budget.
+    """
+    try:
+        # _validate_registry lives in scripts/ which is already on sys.path
+        # via the top-of-file insertion.
+        from _validate_registry import run_all_checks, format_briefing
+
+        report = run_all_checks()
+        return format_briefing(report)
+    except Exception as exc:
+        # Fail-open: validator import or run failure must NOT block bootstrap.
+        # Log to stderr so operators can see why the [Registry] line is absent
+        # but otherwise carry on.
+        print(
+            f"[wicked-garden] registry validation skipped: "
+            f"{type(exc).__name__}: {exc}",
+            file=sys.stderr,
+        )
+        return None
+
+
+# ---------------------------------------------------------------------------
+# CH-02: SessionStart legacy reeval-log scan
+#
+# Scans known crew project directories for reeval-log.jsonl and amendments.jsonl
+# files containing legacy 'qe-evaluator' reviewer names or trigger prefixes.
+# Advisory only — does NOT block session startup.
+# If legacy entries are found, adds a structured migration notice to mode_notes.
+# ---------------------------------------------------------------------------
+
+def _scan_for_legacy_reeval_entries() -> str | None:
+    """Scan crew project dirs for reeval-log.jsonl / amendments.jsonl with legacy qe-evaluator entries.
+
+    Light scan — greps for literal strings; does not parse full JSON.
+    Fails open — any exception returns None so session is never blocked.
+
+    Returns a formatted migration notice string when legacy entries are found,
+    or None when the tree is clean or unreadable.
+    """
+    try:
+        projects_root = Path.home() / ".something-wicked" / "wicked-garden" / "projects"
+        if not projects_root.exists():
+            return None
+
+        _LEGACY_STRINGS = ('"reviewer": "qe-evaluator"', '"trigger": "qe-evaluator:')
+        dirty_files: list[str] = []
+
+        for log_file in projects_root.rglob("phases/*/reeval-log.jsonl"):
+            try:
+                text = log_file.read_text(encoding="utf-8", errors="replace")
+                if any(s in text for s in _LEGACY_STRINGS):
+                    dirty_files.append(str(log_file))
+            except OSError:
+                continue
+
+        for log_file in projects_root.rglob("phases/*/amendments.jsonl"):
+            try:
+                text = log_file.read_text(encoding="utf-8", errors="replace")
+                if any(s in text for s in _LEGACY_STRINGS):
+                    dirty_files.append(str(log_file))
+            except OSError:
+                continue
+
+        if not dirty_files:
+            return None
+
+        file_list = "\n".join(f"  - {f}" for f in dirty_files[:10])
+        more = f"\n  ... and {len(dirty_files) - 10} more" if len(dirty_files) > 10 else ""
+        return (
+            "[Migration Required] Legacy 'qe-evaluator' entries detected in reeval-log.jsonl "
+            "or amendments.jsonl. These will cause errors when crew gates run.\n"
+            f"Affected files:\n{file_list}{more}\n"
+            "Run the migration script before starting a crew workflow:\n"
+            "  python scripts/crew/migrate_qe_evaluator_name.py --project-dir PATH/TO/PROJECT\n"
+            "See docs/MIGRATION-v7.md for full guidance."
+        )
+    except Exception:
+        return None  # fail open — never block session start
+
+
+# ---------------------------------------------------------------------------
+# Main
+# ---------------------------------------------------------------------------
+
+def main():
+    _t0 = time.monotonic()
+    _log("bootstrap", "debug", "hook.start")
+
+    try:
+        sys.stdin.read()  # consume hook payload (not needed for SessionStart)
+    except Exception:
+        pass
+
+    # Export CLAUDE_PLUGIN_ROOT to CLAUDE_ENV_FILE so Bash tool calls can access it.
+    # Hooks receive CLAUDE_PLUGIN_ROOT from the plugin runtime, but Bash tool calls
+    # do not inherit it.  Writing to CLAUDE_ENV_FILE bridges the gap.
+    env_file = os.environ.get("CLAUDE_ENV_FILE")
+    plugin_root = os.environ.get("CLAUDE_PLUGIN_ROOT")
+    if env_file and plugin_root:
+        try:
+            with open(env_file, "a") as f:
+                f.write(f'export CLAUDE_PLUGIN_ROOT="{plugin_root}"\n')
+        except OSError:
+            pass
+
+    try:
+        # 1. Read config
+        config = _read_config()
+
+        if config is None or not config.get("setup_complete", False):
+            # Clear stale session state before early return.  Without this,
+            # setup_in_progress=True from a crashed/killed previous session
+            # survives and lets prompt_submit bypass the setup gate.
+            _stale = _load_session_state()
+            if _stale is not None:
+                if _stale.session_ended:
+                    _stale.delete()
+                    _stale = _load_session_state()
+                if _stale is not None:
+                    _stale.update(
+                        setup_in_progress=False,
+                        setup_complete=False,
+                        setup_confirmed=False,
+                    )
+
+            print(json.dumps({
+                "hookSpecificOutput": {
+                    "hookEventName": "SessionStart",
+                    "additionalContext": (
+                        "[Action Required] wicked-garden is not configured for this project.\n"
+                        "You MUST immediately invoke the Skill tool with skill='wicked-garden:setup' "
+                        "to launch the interactive setup wizard.\n"
+                        "Do NOT ask the user for confirmation — invoke the skill now.\n"
+                        "Do NOT respond with text first — invoke the skill as your first action."
+                    ),
+                },
+            }))
+            return
+
+        # Clear one-time task suggestion flag from crew
+        flag = Path.home() / ".something-wicked" / "wicked-crew" / ".task_suggest_shown"
+        flag.unlink(missing_ok=True)
+
+        # 2. Load session state — if stale from a previous session, start fresh.
+        state = _load_session_state()
+        if state is not None and state.session_ended:
+            state.delete()
+            state = _load_session_state()  # fresh defaults
+        if state is not None:
+            state.update(
+                setup_complete=True,
+                turn_count=0,
+                session_ended=False,
+            )
+
+        # 2a. Probe OneDrive / spaces-in-paths (Issue #321)
+        onedrive_path = _probe_onedrive_path()
+        if onedrive_path and state is not None:
+            state.update(onedrive_base_path=onedrive_path)
+
+        _log("bootstrap", "normal", "storage.local", ok=True)
+
+        # 2b. Initialize event store schema (fire-and-forget)
+        try:
+            from _event_store import EventStore
+            EventStore.ensure_schema()
+            _log("bootstrap", "debug", "event_store.schema", ok=True)
+        except Exception:
+            pass  # event store is optional — never block session start
+
+        # 2c. #506 — pre-flip monitoring signal for WG_GATE_RESULT_STRICT_AFTER.
+        # Fail-open: never blocks bootstrap. Emits stderr WARN at T-7..T-1,
+        # stderr INFO once per session post-flip.
+        _check_pre_flip_notice(state)
+
+        # 2d. Probe wicked-testing availability (AC-1 through AC-6, #544).
+        # Runs once per session; result cached in SessionState.extras.
+        # Fail-open: any unhandled exception in _probe_wicked_testing() returns
+        # gracefully so bootstrap continues. The crew layer (crew_command_gate)
+        # is fail-closed — it treats an absent probe key as missing (CH-02).
+        _probe_wicked_testing(state)
+
+        # 2e. CH-02 safeguard: scan for legacy qe-evaluator entries in reeval-log.jsonl
+        # and amendments.jsonl. Advisory only — does NOT block session startup.
+        # Emits a migration notice when legacy entries are found so the user is
+        # informed at a clean session boundary (not mid-gate).
+        _legacy_reeval_notice = _scan_for_legacy_reeval_entries()
+        if _legacy_reeval_notice and state is not None:
+            state.update(legacy_reeval_entries_detected=True)
+
+        # 3. Load dynamic agents
+        agents_loaded, agents_dict = _load_agents()
+        if state is not None:
+            state.update(agents_loaded=agents_loaded)
+
+        # 3b. Resolve tool-capabilities for agents that declare them
+        resolutions = _resolve_capabilities(agents_dict, config)
+        if resolutions and state is not None:
+            state.update(resolved_capabilities=resolutions)
+
+        # 4. Load last crew project for this workspace
+        workspace = os.environ.get("CLAUDE_PROJECT_NAME") or Path.cwd().name
+        project_data, project_name = _find_active_crew_project(workspace)
+
+        # 6. Run memory decay
+        decay_summary = _run_memory_decay()
+
+        # 6b. Check search index staleness and auto-reindex if needed
+        search_staleness_note = _check_search_staleness()
+        mode_notes = []
+        # Inject wicked-testing blocking notices first (high-priority, AC-2).
+        # These were populated by _probe_wicked_testing() in step 2d above.
+        for _wt_notice in _wt_blocking_notices:
+            mode_notes.append(_wt_notice)
+        # CH-02: inject legacy reeval-log migration notice when legacy entries are found.
+        if _legacy_reeval_notice:
+            mode_notes.append(_legacy_reeval_notice)
+        # Required-peer check: wicked-vault (the evidence backend for gates).
+        _vault_note = _check_vault_dependency()
+        if _vault_note:
+            mode_notes.append(_vault_note)
+        # Required-peer check: wicked-bus (the event backbone for archetype events).
+        _bus_note = _check_bus_dependency()
+        if _bus_note:
+            mode_notes.append(_bus_note)
+        # Required-peer check: wicked-loom (the orchestration runtime garden drives).
+        _loom_note = _check_loom_dependency()
+        if _loom_note:
+            mode_notes.append(_loom_note)
+        if onedrive_path:
+            mode_notes.append(
+                f"[Path] OneDrive directory detected. Resolved base: {onedrive_path}. "
+                "Always quote paths with spaces."
+            )
+        if search_staleness_note:
+            mode_notes.append(f"[Search] {search_staleness_note}")
+
+        # 6c. Surface prior session's guard-pipeline findings (Issue #448)
+        guard_note = _check_prior_guard_findings()
+        if guard_note:
+            mode_notes.append(guard_note)
+
+        # 7. Check onboarding status (search index + memories)
+        has_index, has_memories, onboarding_directive = _check_onboarding_status()
+        _log("bootstrap", "normal", "onboarding.status",
+             ok=(has_memories and has_index),
+             detail={"has_memories": has_memories, "has_index": has_index})
+
+        # Persist onboarding gate flags so prompt_submit can enforce them
+        if state is not None:
+            if not has_memories:
+                state.update(
+                    needs_onboarding=True,
+                    onboarding_complete=False,
+                )
+            else:
+                state.update(
+                    needs_onboarding=False,
+                    onboarding_complete=True,
+                )
+
+        # 7b. Probe installed plugin hooks for readiness
+        unready_plugins = _probe_plugin_readiness()
+        if unready_plugins and state is not None:
+            state.update(unready_plugins=[p["name"] for p in unready_plugins])
+        if unready_plugins:
+            plugin_lines = []
+            for p in unready_plugins:
+                fix_cmd = _suggest_auth_fix(p)
+                plugin_lines.append(f"  - **{p['name']}**: {p['error']}")
+                if fix_cmd:
+                    plugin_lines.append(f"    Fix: `{fix_cmd}`")
+            mode_notes.append(
+                f"[Plugins] {len(unready_plugins)} plugin(s) installed but not ready:\n"
+                + "\n".join(plugin_lines)
+                + "\n  After authenticating, run `/wicked-garden:platform:health` to re-probe."
+            )
+
+        # 7c. Detect dangerous mode (AskUserQuestion broken)
+        dangerous_mode = _detect_dangerous_mode()
+        if state is not None:
+            state.update(dangerous_mode=dangerous_mode)
+
+        # 7c.1. Critical v6 skill smoke-test (issue #434)
+        skills_note = _check_critical_skills()
+        if skills_note:
+            mode_notes.append(skills_note)
+
+        # 7c.2. Registry allowlist validation — surface drift between
+        # in-code allowlists (phases, reviewers, bus handlers, skill refs)
+        # and the assets they reference.  Fail-OPEN: validator errors are
+        # swallowed inside _run_registry_validation, returning None so the
+        # briefing simply omits the [Registry] line on failure.  Findings
+        # are advisory at the session-start surface — they do NOT block.
+        registry_note = _run_registry_validation()
+        if registry_note:
+            mode_notes.append(registry_note)
+
+        # 7d. Check wicked-brain dependency (opt-in memory/context layer)
+        brain_available, brain_note = _check_brain_dependency()
+        if state is not None and brain_available is not None:
+            state.update(brain_available=brain_available)
+        if brain_note:
+            # brain is an opt-in toolkit layer, not a hard requirement — surface
+            # the install pointer informationally, never block the session.
+            mode_notes.append(brain_note)
+
+        # 7e. Brain auto-init and auto-ingest
+        #     If brain is installed but has no content for this project, emit
+        #     a directive so the agent auto-runs init + ingest on first use.
+        #     If the server isn't reachable, emit a start directive instead.
+        if brain_available:
+            stats = _brain_api("stats", {}, timeout=2)
+            if stats is None:
+                # The dependency check above already attempted a deterministic
+                # auto-start; re-probe once in case readiness landed late.
+                try:
+                    from _brain_port import ensure_server
+                    if ensure_server():
+                        stats = _brain_api("stats", {}, timeout=2)
+                except Exception:
+                    pass
+            if stats is None:
+                mode_notes.append(
+                    "[wicked-brain] Plugin installed but the server did not respond "
+                    "after auto-start. Diagnose with `wicked-brain-call --start`, "
+                    "then run the brain pipeline: ingest → retag → compile."
+                )
+            elif stats.get("total", 0) == 0:
+                mode_notes.append(
+                    "[wicked-brain] Brain is empty for this project. "
+                    "You MUST run the full brain pipeline now as background agents:\n"
+                    "  1. `wicked-brain:init` — initialize the brain if needed\n"
+                    "  2. `wicked-brain:ingest` with the current working directory\n"
+                    "  3. `wicked-brain:retag` — expand keywords into semantic tags\n"
+                    "  4. `wicked-brain:compile` — synthesize wiki articles from chunks\n"
+                    "Run these sequentially in a background agent. "
+                    "Do NOT wait for completion before responding to the user."
+                )
+
+        # 8. Assemble session briefing
+        # --- Status block (user-facing) ---
+        project = os.environ.get("CLAUDE_PROJECT_NAME") or Path.cwd().name
+
+        onboarding_parts = []
+        if has_index:
+            onboarding_parts.append("search index")
+        if has_memories:
+            onboarding_parts.append("memories")
+        if onboarding_parts:
+            onboarding_status = "Complete (" + " + ".join(onboarding_parts) + ")"
+        else:
+            onboarding_status = "Not started"
+
+        status_lines = [
+            f"wicked-garden | {project}",
+            "  Storage:     local",
+            f"  Onboarding:  {onboarding_status}",
+        ]
+
+        # Show last crew project for this workspace as informational only.
+        # Do NOT auto-activate — the user must explicitly start/resume a project.
+        if project_data:
+            name = project_data.get("name", project_name or "unknown")
+            phase = project_data.get("current_phase", "unknown")
+            status_lines.append(f"  Last crew:   {name} ({phase})")
+
+            # Store as reference info only — NOT as active_project
+            if state is not None:
+                # active_project_id: only set when project is in a non-complete, non-skipped phase
+                active_phase = project_data.get("current_phase", "")
+                is_active = active_phase not in ("", "complete", "done", "archived")
+                state.update(active_project_id=project_name if is_active else None)
+
+                # v9.2.4: also write active_chain_id so smaht's chain-aware
+                # event scoring (CLAUDE.md "Chain-aware smaht scoring") actually
+                # works. Field declared in v9.2.3, producer was missing — events
+                # got the 0.1 baseline instead of the documented 0.8+ chain
+                # boost. Format mirrors the chain_id convention in CLAUDE.md
+                # "Native Tasks as Dual-Purpose Event Queue":
+                #   {slug}.root            for the root chain
+                #   {slug}.{phase}         per active phase
+                # Cleared (set None) when the project is not active so events
+                # in unrelated sessions don't accidentally inherit the chain.
+                if is_active:
+                    chain_id = f"{project_name}.{active_phase}" if active_phase != "clarify" else f"{project_name}.root"
+                    state.update(active_chain_id=chain_id)
+                else:
+                    state.update(active_chain_id=None)
+
+                # v9.2.5: also write active_project (the dict snapshot, distinct
+                # from active_project_id which is the slug). Read by:
+                #   - post_tool.py:1428-1431 (tracks current_phase + current_specialist
+                #     for QE change-tracking nudge)
+                #   - pre_compact.py (WIP recovery dump shows "Active Project" section)
+                # Producer was missing — both consumers got None and silently fell
+                # through their default branches. Same bug class as active_chain_id
+                # (declared, read, never written). Same fix: write in bootstrap when
+                # the project is active.
+                if is_active:
+                    state.update(active_project=dict(project_data))
+                else:
+                    state.update(active_project=None)
+
+                # #459 telemetry producer: anchor complexity_at_session_open
+                # from the active project's complexity_score so session-close
+                # drift capture has a delta baseline.  Only set when not
+                # already populated this session (first SessionStart wins).
+                try:
+                    raw_complexity = project_data.get("complexity_score", 0)
+                    complexity_val = int(raw_complexity) if raw_complexity is not None else 0
+                    updates = {"complexity_score": complexity_val}
+                    if getattr(state, "complexity_at_session_open", None) is None:
+                        updates["complexity_at_session_open"] = complexity_val
+                    state.update(**updates)
+                except (TypeError, ValueError):
+                    # Malformed complexity_score — fail-open, don't block bootstrap.
+                    pass
+
+            # Enable memory compliance directives for crew sessions.
+            # task_completed.py reads this flag to decide whether to emit
+            # per-task memory prompts; stop.py reads it for session summary.
+            if state is not None:
+                state.update(memory_compliance_required=True)
+
+        briefing_parts = ["\n".join(status_lines)]
+
+        # --- Solo-mode HITL banner (#651) ---
+        # Emit once per session when the active crew project has solo_mode: true.
+        if project_data and project_data.get("solo_mode"):
+            briefing_parts.append(
+                "[SOLO MODE ACTIVE] Council gates replaced with inline human review "
+                "for this project. Gate artifacts are preserved. "
+                "Merge-gate council pattern is unchanged."
+            )
+
+        # --- Mode-specific warnings/notes ---
+        for note in mode_notes:
+            briefing_parts.append(note)
+
+        if decay_summary:
+            briefing_parts.append(f"[Memory] {decay_summary}")
+
+        # NOTE (v9.2.10): the per-session _MEMORY_INSTRUCTIONS append was
+        # removed. CLAUDE.md's "Memory Management" section already covers
+        # what the briefing was telling Claude. v9.2.11 deleted the constant
+        # itself after confirming zero imports.
+
+        if dangerous_mode:
+            briefing_parts.append(_DANGEROUS_MODE_WARNING)
+
+        # [Setup] and [Quick Start] are first-session-per-project notices.
+        # Once shown for a project, they are recorded in the per-project
+        # sentinel file and suppressed on every subsequent bootstrap. v9.2.10.
+        if not onboarding_directive:
+            if not _notice_already_shown(_NOTICE_SETUP):
+                briefing_parts.append(
+                    "[Setup] Run `/wicked-garden:setup --reconfigure` to change connection or re-onboard."
+                )
+                _record_notice_shown(_NOTICE_SETUP)
+
+        # Discovery: show 2-3 contextual command suggestions based on project files.
+        # Also gated on first-session-per-project since the suggestions don't change
+        # session-to-session.
+        if not onboarding_directive and has_memories:
+            if not _notice_already_shown(_NOTICE_QUICK_START):
+                discovery_lines = _suggest_commands_for_project()
+                if discovery_lines:
+                    briefing_parts.append(discovery_lines)
+                    _record_notice_shown(_NOTICE_QUICK_START)
+
+        # Facilitator context: surface aging action items from process_memory.
+        # Additive briefing line (issue #461) — runs last of the informational
+        # notes and is independent of onboarding or setup state.
+        fc_note = _check_facilitator_context(project_name)
+        if fc_note:
+            briefing_parts.append(fc_note)
+
+        # Onboarding directive goes LAST for highest priority
+        if onboarding_directive:
+            briefing_parts.append(onboarding_directive)
+
+        # 9. Persist final session state
+        if state is not None:
+            _save_session_state(state)
+
+        _log("bootstrap", "debug", "hook.end", ms=int((time.monotonic() - _t0) * 1000))
+        print(json.dumps({
+            "hookSpecificOutput": {
+                "hookEventName": "SessionStart",
+                "additionalContext": "\n".join(briefing_parts),
+            },
+        }))
+
+    except Exception as e:
+        print(f"[wicked-garden] bootstrap error: {e}", file=sys.stderr)
+        print(json.dumps({}))
+
+
+if __name__ == "__main__":
+    main()