wicked-garden 12.27.0

package/hooks/scripts/pre_tool.py

@@ -0,0 +1,1278 @@
+#!/usr/bin/env python3
+"""
+PreToolUse hook — wicked-garden unified pre-tool dispatcher.
+
+Consolidates: crew pretool_taskcreate, crew pretool_planmode, mem block_memory_md,
+              crew gate preflight (Bash approve calls).
+
+Dispatches by tool_name from hook payload:
+  TaskCreate    → validate event metadata envelope + crew initiative injection
+  TaskUpdate    → validate event metadata envelope on updates
+  EnterPlanMode → deny and redirect to crew workflow
+  Write / Edit  → MEMORY.md write guard (AGENTS.md writes allowed, synced via PostToolUse)
+  Bash          → crew gate preflight (phase_manager.py approve calls) +
+                  worktree cwd-leak guard (#878, hooks/scripts/worktree_guard.py)
+
+Always fails open — any unhandled exception returns permissionDecision: "allow".
+"""
+
+import json
+import os
+import re
+import sys
+import time
+from pathlib import Path
+
+# Add shared scripts directory to path
+_PLUGIN_ROOT = Path(os.environ.get("CLAUDE_PLUGIN_ROOT", Path(__file__).resolve().parents[2]))
+sys.path.insert(0, str(_PLUGIN_ROOT / "scripts"))
+# Allow importing sibling hook modules (e.g. worktree_guard) in any context.
+sys.path.append(str(Path(__file__).resolve().parent))
+
+
+# ---------------------------------------------------------------------------
+# 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
+
+
+# ---------------------------------------------------------------------------
+# Response helpers
+# ---------------------------------------------------------------------------
+
+def _allow(updated_input=None, system_message=None) -> str:
+    output = {
+        "hookSpecificOutput": {
+            "hookEventName": "PreToolUse",
+            "permissionDecision": "allow",
+        }
+    }
+    if updated_input is not None:
+        output["hookSpecificOutput"]["updatedInput"] = updated_input
+    if system_message:
+        output["systemMessage"] = system_message
+    return json.dumps(output)
+
+
+def _deny(reason: str) -> str:
+    return json.dumps({
+        "hookSpecificOutput": {
+            "hookEventName": "PreToolUse",
+            "permissionDecision": "deny",
+            "permissionDecisionReason": reason,
+        }
+    })
+
+
+# ---------------------------------------------------------------------------
+# Handler: TaskCreate
+# (inject crew initiative metadata, one-time crew suggestion)
+# ---------------------------------------------------------------------------
+
+def _find_active_crew_project():
+    """Return (project_data_dict, project_name, initiative_name).
+
+    Scoped to the current workspace (CLAUDE_PROJECT_NAME or cwd basename).
+    Only returns projects whose ``workspace`` field matches.
+    Uses DomainStore exclusively — operates local-only in hook mode.
+
+    ``initiative_name`` is the project name (used to tag task metadata
+    with a coarse grouping). Custom display names can be set via the
+    optional ``initiative`` field on project.json.
+    """
+    workspace = os.environ.get("CLAUDE_PROJECT_NAME") or Path.cwd().name
+    try:
+        from _domain_store import DomainStore
+        ds = DomainStore("wicked-crew", hook_mode=True)
+        projects = ds.list("projects") or []
+        for p in sorted(projects, key=lambda x: x.get("updated_at", x.get("created_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 not in ("complete", "done", ""):
+                name = p.get("name", "")
+                initiative = p.get("initiative") or name
+                return p, name, initiative
+    except Exception:
+        pass
+
+    return None, None, None
+
+
+def _validate_event_metadata(tool_input: dict) -> "str | None":
+    """Validate the metadata envelope on TaskCreate / TaskUpdate.
+
+    Returns an error string on failure, or None on pass. Loads phases.json
+    for phase enum validation. Fail-silent on import errors — an
+    un-importable schema module must never break task creation.
+    """
+    try:
+        from _event_schema import validate_metadata
+    except Exception:
+        return None  # schema module unavailable; fail open
+
+    metadata = tool_input.get("metadata") or {}
+    phases = set(_load_phases_config_hook().keys())
+    status = tool_input.get("status")
+    return validate_metadata(
+        metadata, valid_phases=phases or None, status=status,
+    )
+
+
+def _task_metadata_mode() -> str:
+    """``off`` | ``warn`` | ``strict`` — mirrors gate enforcement convention."""
+    mode = (os.environ.get("WG_TASK_METADATA") or "warn").strip().lower()
+    return mode if mode in ("off", "warn", "strict") else "warn"
+
+
+def _handle_task_create(tool_input: dict) -> str:
+    """Inject crew initiative metadata and validate the event envelope."""
+    mode = _task_metadata_mode()
+    err = None if mode == "off" else _validate_event_metadata(tool_input)
+
+    if err and mode == "strict":
+        _log("pretool", "info", "task.metadata.blocked", detail={"reason": err})
+        return _deny(f"[wicked-garden] task metadata invalid: {err}")
+
+    _data, project_name, initiative_name = _find_active_crew_project()
+
+    if project_name:
+        metadata = tool_input.get("metadata") or {}
+        if not metadata.get("initiative"):
+            metadata["initiative"] = initiative_name
+            tool_input["metadata"] = metadata
+        system_message = None
+        if err and mode == "warn":
+            _log("pretool", "warn", "task.metadata.deprecated", detail={"reason": err})
+            system_message = f"[wicked-garden] DEPRECATION: task metadata: {err}"
+        return _allow(updated_input=tool_input, system_message=system_message)
+
+    # No active project — show one-time suggestion via SessionState
+    system_message = None
+    if err and mode == "warn":
+        _log("pretool", "warn", "task.metadata.deprecated", detail={"reason": err})
+        system_message = f"[wicked-garden] DEPRECATION: task metadata: {err}"
+    try:
+        from _session import SessionState
+        state = SessionState.load()
+        if not state.task_suggest_shown:
+            state.update(task_suggest_shown=True)
+            suggest = "Creating tasks? Consider `/wicked-garden:crew:start` for quality gates."
+            return _allow(
+                system_message=(system_message + "\n" + suggest) if system_message else suggest
+            )
+    except Exception:
+        pass
+
+    return _allow(system_message=system_message)
+
+
+def _handle_task_update(tool_input: dict) -> str:
+    """Validate the event envelope on TaskUpdate (metadata merges).
+
+    TaskUpdate metadata is a merge patch — an empty/absent metadata is valid
+    (the caller is updating status or subject only). Validation only fires
+    when metadata is present and contains an event_type claim.
+    """
+    mode = _task_metadata_mode()
+    if mode == "off":
+        return _allow()
+
+    metadata = tool_input.get("metadata") or {}
+    if not metadata.get("event_type"):
+        return _allow()  # pure status/subject update
+
+    err = _validate_event_metadata(tool_input)
+    if err and mode == "strict":
+        _log("pretool", "info", "task.metadata.blocked", detail={"reason": err})
+        return _deny(f"[wicked-garden] task metadata invalid: {err}")
+    if err and mode == "warn":
+        _log("pretool", "warn", "task.metadata.deprecated", detail={"reason": err})
+        return _allow(
+            system_message=f"[wicked-garden] DEPRECATION: task metadata: {err}"
+        )
+    return _allow()
+
+
+# ---------------------------------------------------------------------------
+# Handler: EnterPlanMode
+# (deny native plan mode, redirect to crew workflow)
+# ---------------------------------------------------------------------------
+
+def _handle_enter_plan_mode(tool_input: dict) -> str:
+    """Block native plan mode — redirect to crew workflow instead.
+
+    wicked-garden uses crew projects for planning, not Claude's built-in
+    plan mode. Always deny and point to /wicked-garden:crew:start.
+    """
+    try:
+        data, project_name, _ = _find_active_crew_project()
+        if project_name and data:
+            current_phase = data.get("current_phase", "")
+            return _deny(
+                f"Do not use native plan mode. A crew project '{project_name}' is already active "
+                f"(phase: {current_phase}). Continue working within the crew workflow. "
+                f"Use `/wicked-garden:crew:execute` to proceed or `/wicked-garden:crew:status` to check progress."
+            )
+    except Exception:
+        pass
+
+    return _deny(
+        "Do not use native plan mode. This project uses wicked-garden crew workflows for planning. "
+        "Use `/wicked-garden:crew:start` to create a new crew project with outcome clarification, "
+        "phased execution, and quality gates."
+    )
+
+
+# ---------------------------------------------------------------------------
+# Handler: Write / Edit
+# (MEMORY.md and AGENTS.md write guard)
+# ---------------------------------------------------------------------------
+
+# Claude Code auto-memory directory pattern
+_AUTO_MEMORY_MARKER = ".claude/projects/"
+
+
+def _handle_write_guard(tool_input: dict) -> str:
+    """Block direct writes to MEMORY.md, auto-memory directory, and AGENTS.md.
+
+    Also warns when an active crew project is in build or review phase and the
+    file path is not on the orchestrator allowlist. This enforces the
+    orchestrator-only principle (Issue #251): orchestrators should write only
+    to project state files, not directly produce implementation artifacts.
+
+    Issue #442: Also blocks Write/Edit during build phase when the
+    challenge-artifacts gate has not cleared (complexity >= 4). Respects
+    ``WG_CHALLENGE_GATE=off`` as a scoped bypass. (The legacy global
+    ``CREW_GATE_ENFORCEMENT=legacy`` switch was removed in #466 — v6 gate
+    enforcement is unconditional; use ``git revert`` to roll back.)
+
+    TODO (Issue #329): When Claude Code supports updatedInput for PreToolUse hooks
+    to redirect tool calls, change the MEMORY.md deny into an updatedInput redirect
+    that rewrites the Write/Edit call into a wicked-brain:memory invocation instead.
+    This would be less disruptive than a hard deny — the intent to persist data would
+    still succeed, just through the correct channel.
+    """
+    file_path = tool_input.get("file_path", "")
+
+    # AGENTS.md is a cross-tool instruction file shared with Codex, Cursor, Amp, etc.
+    # Writes are allowed — a PostToolUse hook keeps CLAUDE.md and AGENTS.md in sync.
+
+    # Theme 9: bare endswith("MEMORY.md") would match e.g. "notMEMORY.md".
+    # Use Path().name for a true basename check, which is platform-agnostic
+    # (works for both POSIX and Windows separators).
+    try:
+        _basename = Path(file_path).name
+    except (TypeError, ValueError):
+        _basename = ""
+    is_memory_md = _basename == "MEMORY.md"
+    is_auto_memory = _AUTO_MEMORY_MARKER in file_path and "/memory/" in file_path
+
+    if is_memory_md or is_auto_memory:
+        return _deny(
+            "Do not write to MEMORY.md or the auto memory directory. "
+            "This project uses wicked-garden memory for persistence. "
+            "Use wicked-brain:memory to save decisions, patterns, and gotchas instead."
+        )
+
+    # Issue #442: challenge-artifacts gate for build-phase writes
+    challenge_block = _check_challenge_gate(file_path)
+    if challenge_block:
+        return _deny(challenge_block)
+
+    # Issue #734 Part B: bus-emit lint for orphan writes to load-bearing
+    # state artifacts. WG_BUS_EMIT_LINT=warn (default) emits a systemMessage;
+    # =strict denies the write; =off disables. Fail-open on any error.
+    lint_action, lint_msg = _check_bus_emit_lint(file_path)
+    if lint_action == "deny":
+        return _deny(lint_msg)
+
+    # Orchestrator-only warning (Issue #251): warn when writing outside allowlist
+    # during build or review phases. Fail open — always allow, but emit systemMessage.
+    warning = _check_orchestrator_write(file_path)
+
+    # Combine lint warn + orchestrator warn into a single systemMessage
+    # rather than letting the second overwrite the first.
+    messages: list[str] = []
+    if lint_action == "warn" and lint_msg:
+        messages.append(lint_msg)
+    if warning:
+        messages.append(warning)
+    if messages:
+        return _allow(system_message="\n\n".join(messages))
+
+    return _allow()
+
+
+# ---------------------------------------------------------------------------
+# Challenge gate (Issue #442)
+# ---------------------------------------------------------------------------
+
+def _challenge_gate_bypassed() -> bool:
+    """Respect ``WG_CHALLENGE_GATE=off`` as a scoped bypass.
+
+    Only the scoped flag disables the challenge gate. The global
+    ``CREW_GATE_ENFORCEMENT=legacy`` switch was removed in #466 — v6 gate
+    enforcement is unconditional. Rollback is a ``git revert``, not a
+    runtime toggle.
+    """
+    if (os.environ.get("WG_CHALLENGE_GATE") or "").strip().lower() == "off":
+        return True
+    return False
+
+
+def _check_challenge_gate(file_path: str) -> str:
+    """Return a deny-reason if the challenge gate blocks this Write/Edit.
+
+    Only fires when ALL of the following are true:
+      * an active crew project exists in the current workspace
+      * the project is in the ``build`` phase
+      * the project complexity_score is >= the configured threshold
+        (``WG_CHALLENGE_MIN_COMPLEXITY`` env var, default 4)
+      * ``phases/design/challenge-artifacts.md`` is missing or invalid
+      * the file being written is NOT on the orchestrator allowlist
+        (we still allow orchestrator state writes so the project can
+        self-recover — the contrarian itself needs to be able to write
+        the artifact)
+
+    Any unexpected error → returns "" (fail-open). This mirrors the
+    always-fail-open contract the rest of this file upholds.
+    """
+    if _challenge_gate_bypassed():
+        return ""
+
+    # Contrarian must be able to write the challenge artifact itself — never
+    # block on the artifact's own path. Also never block state writes.
+    if "challenge-artifacts.md" in file_path:
+        return ""
+    if _is_allowlisted(file_path):
+        return ""
+
+    try:
+        data, project_name, _ = _find_active_crew_project()
+        if not project_name or not data:
+            return ""
+
+        current_phase = (data.get("current_phase") or "").lower()
+        if current_phase != "build":
+            return ""
+
+        complexity = int(data.get("complexity_score", 0) or 0)
+
+        # Import here so pre_tool.py stays robust if the crew module is
+        # missing / malformed. Fail-open on any import or attribute error.
+        try:
+            scripts_crew = _PLUGIN_ROOT / "scripts" / "crew"
+            if str(scripts_crew) not in sys.path:
+                sys.path.insert(0, str(scripts_crew))
+            from challenge_manifest import (  # type: ignore
+                is_required,
+                artifact_satisfies_gate,
+            )
+        except Exception:
+            return ""
+
+        if not is_required(complexity, phase="build"):
+            return ""
+
+        # Resolve the project directory to look up the artifact
+        try:
+            from _paths import get_local_path
+            base = get_local_path("wicked-crew", "projects")
+            project_id = data.get("id") or project_name
+            project_dir = base / project_id
+        except Exception:
+            return ""
+
+        if not (project_dir / "project.json").exists():
+            return ""
+
+        ok, reason = artifact_satisfies_gate(project_dir, phase="design")
+        if ok:
+            return ""
+
+        _log(
+            "pretool",
+            "info",
+            "challenge.gate.blocked",
+            detail={"project": project_name, "reason": reason},
+        )
+
+        return (
+            f"[wicked-garden] Challenge gate is unresolved for crew project "
+            f"'{project_name}' (complexity={complexity}). {reason} "
+            f"Invoke the contrarian specialist to produce and clear "
+            f"phases/design/challenge-artifacts.md before continuing build. "
+            f"Run `wicked-garden:crew:contrarian` or dispatch Task("
+            f"subagent_type='wicked-garden:crew:contrarian'). "
+            f"To bypass temporarily, set WG_CHALLENGE_GATE=off."
+        )
+    except Exception:
+        return ""
+
+
+# ---------------------------------------------------------------------------
+# Orchestrator allowlist (Issue #251)
+# ---------------------------------------------------------------------------
+
+# Paths that the orchestrator is permitted to write directly.
+# .something-wicked/ contains project state, status.md files are orchestrator output.
+_ORCHESTRATOR_ALLOWLIST = [
+    ".something-wicked/",
+]
+
+_ORCHESTRATOR_ALLOWLIST_SUFFIXES = [
+    "status.md",
+]
+
+_ORCHESTRATOR_PHASES = {"build", "review"}
+
+
+def _is_allowlisted(file_path: str) -> bool:
+    """Return True if file_path is on the orchestrator write allowlist.
+
+    Theme 9: ``endswith("status.md")`` would false-match ``bogusstatus.md``.
+    Suffix entries match against the basename (Path.name) so the check
+    requires the exact filename, not a tail-substring.
+    """
+    for fragment in _ORCHESTRATOR_ALLOWLIST:
+        if fragment in file_path:
+            return True
+    try:
+        basename = Path(file_path).name
+    except (TypeError, ValueError):
+        return False
+    for suffix in _ORCHESTRATOR_ALLOWLIST_SUFFIXES:
+        if basename == suffix:
+            return True
+    return False
+
+
+def _check_orchestrator_write(file_path: str) -> str:
+    """Return a warning message if the write appears to be orchestrator inline work.
+
+    Only warns — never denies. Returns empty string if no warning needed.
+    """
+    if _is_allowlisted(file_path):
+        return ""
+
+    # Check if there is an active crew project in build or review phase
+    try:
+        data, project_name, _ = _find_active_crew_project()
+        if not project_name or not data:
+            return ""
+
+        current_phase = data.get("current_phase", "")
+        if current_phase.lower() not in _ORCHESTRATOR_PHASES:
+            return ""
+
+        return (
+            f"[wicked-garden] Orchestrator principle: The active crew project "
+            f"'{project_name}' is in '{current_phase}' phase. "
+            f"Orchestrators should not write implementation files directly. "
+            f"Delegate to implementer, researcher, or specialist subagents via Task(). "
+            f"Allowed direct writes: .something-wicked/ paths and status.md files."
+        )
+    except Exception:
+        return ""
+
+
+# ---------------------------------------------------------------------------
+# Handler: Bash
+# (crew gate preflight — intercepts phase_manager.py approve calls)
+# ---------------------------------------------------------------------------
+
+# Regex to extract project and phase from phase_manager.py approve invocations.
+# Matches forms like:
+#   phase_manager.py myproject approve --phase build
+#   phase_manager.py myproject approve --phase build --override-gate
+_APPROVE_RE = re.compile(
+    r"phase_manager\.py\s+(\S+)\s+approve(?:\s+.*?)?(?:--phase\s+(\S+))?",
+    re.DOTALL,
+)
+
+
+# ---------------------------------------------------------------------------
+# Bus-emit lint (Issue #734 Part B)
+# ---------------------------------------------------------------------------
+#
+# Detects orphan writes to load-bearing crew state artifacts that are not
+# accompanied by a recent ``wicked-bus`` event on the project's chain. The
+# resume projector (#734 Part A) and any future bus-as-truth subscriber
+# rely on emits to stay current — silent writes leave projections stale
+# and force callers back to file polling.
+#
+# Configuration:
+#   WG_BUS_EMIT_LINT=warn|strict|off   (default: warn)
+#   WG_BUS_EMIT_LINT_WINDOW_SEC=<int>  (default: 60)
+#
+# Detection mechanism: query the daemon's projections.db ``event_log`` table
+# for any event ingested in the last N seconds whose chain_id starts with
+# ``{active_project_id}.``. Read-only sqlite URI mode keeps the projector
+# untouched. ANY error fail-opens — the lint is advisory unless strict.
+
+#: Filenames (basename match, platform-agnostic) that mark a path as
+#: load-bearing crew state. Each is a post-audit-#735 high-priority gap.
+#: Basename matching avoids the "Windows backslash vs POSIX forward-slash"
+#: bug — Path(file_path).name is the same on every platform.
+_BUS_EMIT_LINT_TARGET_BASENAMES = frozenset({
+    "gate-result.json",
+    "dispatch-log.jsonl",
+    "conditions-manifest.json",
+    "reviewer-report.md",
+})
+
+#: A file with a target basename only counts as crew state if its parent
+#: chain contains a ``phases`` directory — the wicked-crew artifact
+#: convention. This prevents a scratch file like
+#: ``/tmp/notes/gate-result.json`` from triggering the lint.
+_BUS_EMIT_LINT_PARENT_MARKERS = ("phases",)
+
+#: Event types that semantically pair with the target artifacts. A "recent
+#: emit" only counts if its event_type is in this set — otherwise an
+#: unrelated ``wicked.project.created`` at session start would buy 60s of
+#: silent orphan-write passes, which is exactly the false-negative the
+#: lint exists to catch.
+#:
+#: Pairing rationale per target:
+#:   gate-result.json        ← wicked.gate.decided
+#:   conditions-manifest.json ← wicked.gate.decided (CONDITIONAL branch)
+#:   dispatch-log.jsonl      ← wicked.dispatch.log_entry_appended (Part C)
+#:   reviewer-report.md      ← wicked.consensus.report_created /
+#:                             wicked.consensus.evidence_recorded (Part C)
+#:
+#: Phase + project lifecycle events stay in the set because callers may
+#: write multiple state files in the wake of a single phase/project event.
+_BUS_EMIT_LINT_PAIR_EVENTS = (
+    "wicked.gate.decided",
+    "wicked.gate.blocked",
+    "wicked.rework.triggered",
+    "wicked.phase.transitioned",
+    "wicked.project.completed",
+    # Part C of #734 — new emits paired with their target artifact writes
+    "wicked.dispatch.log_entry_appended",
+    "wicked.consensus.report_created",
+    "wicked.consensus.evidence_recorded",
+)
+
+
+def _bus_emit_lint_mode() -> str:
+    """Return ``'off' | 'warn' | 'strict'`` (default ``'warn'``)."""
+    raw = (os.environ.get("WG_BUS_EMIT_LINT") or "warn").strip().lower()
+    return raw if raw in ("off", "warn", "strict") else "warn"
+
+
+def _bus_emit_lint_window_sec() -> int:
+    """Return the recent-emit window in seconds (default 60)."""
+    try:
+        return max(1, int(os.environ.get("WG_BUS_EMIT_LINT_WINDOW_SEC") or "60"))
+    except (TypeError, ValueError):
+        return 60
+
+
+def _is_bus_emit_lint_target(file_path: str) -> bool:
+    """True iff file_path's basename matches a target AND it lives under a
+    crew-style ``phases/`` parent chain.
+
+    Basename-based to be Windows-safe (``C:\\proj\\phases\\build\\gate-result.json``
+    matches the same as the POSIX form). The parent-marker check prevents a
+    scratch file like ``/tmp/notes/gate-result.json`` from triggering the
+    lint just because the basename collides.
+    """
+    try:
+        p = Path(file_path)
+    except (TypeError, ValueError):
+        return False
+    if p.name not in _BUS_EMIT_LINT_TARGET_BASENAMES:
+        return False
+    # Walk parent components looking for a wicked-crew style marker. Use
+    # ``parts`` (Path.parts) so the comparison is OS-native.
+    parts = p.parts
+    return any(marker in parts for marker in _BUS_EMIT_LINT_PARENT_MARKERS)
+
+
+def _resolve_daemon_db_path() -> "str | None":
+    """Find the daemon DB. Honors ``WG_DAEMON_DB`` first (matches daemon/db.py)."""
+    candidates = [
+        os.environ.get("WG_DAEMON_DB"),
+        os.environ.get("WG_PROJECTOR_DB_PATH"),  # legacy alias
+        str(Path.home() / ".something-wicked"
+            / "wicked-garden-daemon" / "projections.db"),
+    ]
+    for c in candidates:
+        if c and Path(c).is_file():
+            return c
+    return None
+
+
+def _has_recent_bus_emit(project_id: str, window_sec: int) -> bool:
+    """Query event_log for a recent SEMANTICALLY-PAIRED emit on this project's chain.
+
+    Returns ``True`` on any error or missing DB — fail-open per this file's
+    convention (mirrors ``_check_challenge_gate``'s "any unexpected error
+    → return '' (fail-open)" docstring). The lint stays silent when we
+    cannot verify; users running without the daemon don't get false
+    positives. The lint only fires when we CAN verify and find no
+    matching emit.
+
+    "Semantically paired" means the event_type is in
+    :data:`_BUS_EMIT_LINT_PAIR_EVENTS` — gate / phase / project lifecycle
+    events. An unrelated ``wicked.project.created`` at session start MUST
+    NOT buy a 60-second window of silent orphan-write passes; that would
+    be the exact false-negative the lint exists to catch.
+
+    Caveat — daemon projection race: ``emit_event()`` is fire-and-forget
+    and the daemon's consumer ingests into ``event_log`` on its polling
+    loop. A caller that emits and then writes within milliseconds may be
+    flagged because the projection has not yet caught up. The 60s default
+    window is sized to absorb realistic poll intervals; production users
+    can widen via ``WG_BUS_EMIT_LINT_WINDOW_SEC`` if their daemon polls
+    more slowly.
+
+    Read-only URI mode keeps us honest about not mutating the projector.
+    """
+    db_path = _resolve_daemon_db_path()
+    if not db_path:
+        return True  # fail-open — daemon not running / no projector
+    try:
+        import sqlite3
+        import time as _time
+        uri = Path(db_path).absolute().as_uri() + "?mode=ro"
+        conn = sqlite3.connect(uri, uri=True)
+        try:
+            since = int(_time.time()) - window_sec
+            # LIKE escape: '_' and '%' in project_id would otherwise match
+            # unrelated chains. Same idiom as scripts/crew/resume_projector.py
+            # — see brain memory "sqlite-like-wildcard-escape-gotcha".
+            escaped = (
+                project_id
+                .replace("!", "!!")
+                .replace("_", "!_")
+                .replace("%", "!%")
+            )
+            placeholders = ",".join("?" for _ in _BUS_EMIT_LINT_PAIR_EVENTS)
+            params = (
+                f"{escaped}.%",
+                since,
+                *_BUS_EMIT_LINT_PAIR_EVENTS,
+            )
+            row = conn.execute(
+                f"""SELECT 1 FROM event_log
+                    WHERE chain_id LIKE ? ESCAPE '!'
+                      AND ingested_at >= ?
+                      AND event_type IN ({placeholders})
+                    LIMIT 1""",
+                params,
+            ).fetchone()
+            return row is not None
+        finally:
+            conn.close()
+    except Exception:
+        # sqlite3.Error, OSError on connect, anything unexpected — same
+        # fail-open convention as the missing-DB case above.
+        return True
+
+
+def _check_bus_emit_lint(file_path: str) -> "tuple[str, str]":
+    """Return ``(action, message)``.
+
+    ``action``:
+      * ``'allow'`` — no message; lint disabled, not a target, no active
+        project, or recent emit found
+      * ``'warn'`` — caller should attach ``message`` as systemMessage
+      * ``'deny'`` — strict mode, no recent emit; caller should deny
+
+    Fail-open on any unexpected error.
+    """
+    try:
+        mode = _bus_emit_lint_mode()
+        if mode == "off":
+            return "allow", ""
+        if not _is_bus_emit_lint_target(file_path):
+            return "allow", ""
+
+        data, project_name, _ = _find_active_crew_project()
+        if not data or not project_name:
+            return "allow", ""
+
+        project_id = data.get("id") or project_name
+        window = _bus_emit_lint_window_sec()
+        if _has_recent_bus_emit(project_id, window):
+            return "allow", ""
+
+        msg = (
+            f"[bus-emit lint] writing to {file_path} but no wicked-bus "
+            f"event was emitted on chain '{project_id}.*' in the last "
+            f"{window}s. The resume projector (#734) and future bus-as-truth "
+            f"subscribers (#732) rely on emits to track state — silent "
+            f"writes leave projections stale. "
+            f"Bypass: WG_BUS_EMIT_LINT=off | "
+            f"adjust window: WG_BUS_EMIT_LINT_WINDOW_SEC=<sec>"
+        )
+        if mode == "strict":
+            return "deny", msg
+        return "warn", msg
+    except Exception:
+        return "allow", ""
+
+
+def _parse_frontmatter(text: str) -> dict:
+    """Extract YAML frontmatter fields using simple regex — no YAML library.
+
+    Parses only the first ``---`` block. Returns a dict of key → raw string
+    values. Multi-line values and lists are NOT parsed; only flat scalar
+    ``key: value`` pairs are extracted.
+    """
+    fm: dict = {}
+    match = re.match(r"^---\s*\n(.*?)\n---", text, re.DOTALL)
+    if not match:
+        return fm
+    block = match.group(1)
+    for line in block.splitlines():
+        kv = re.match(r"^(\w[\w_-]*):\s*(.*)", line)
+        if kv:
+            fm[kv.group(1)] = kv.group(2).strip()
+    return fm
+
+
+def _safe_read_text(path: Path) -> str:
+    """Read file text; return '' on any error."""
+    try:
+        return path.read_text(encoding="utf-8", errors="replace")
+    except Exception:
+        return ""
+
+
+def _safe_read_json(path: Path):
+    """Read and parse JSON; return None on any error."""
+    try:
+        return json.loads(path.read_text(encoding="utf-8", errors="replace"))
+    except Exception:
+        return None
+
+
+def _load_phases_config_hook() -> dict:
+    """Load phases.json from .claude-plugin/ relative to plugin root.
+
+    Returns the ``phases`` sub-dict, or an empty dict on any error.
+    This is a local copy of the logic in phase_manager.py so the hook
+    stays stdlib-only and avoids importing phase_manager (which has
+    side-effects at import time like reading env vars at module level).
+    """
+    try:
+        config_path = _PLUGIN_ROOT / ".claude-plugin" / "phases.json"
+        if config_path.exists():
+            data = _safe_read_json(config_path)
+            if isinstance(data, dict):
+                return data.get("phases", {})
+    except Exception:
+        pass
+    return {}
+
+
+def _get_project_id_for(project_arg: str) -> str:
+    """Resolve project ID from a project name / slug argument.
+
+    The phase_manager CLI accepts a project name or ID.  We look inside the
+    wicked-crew projects directory for a project.json whose ``name`` or ``id``
+    matches ``project_arg``.  Falls back to using ``project_arg`` verbatim as
+    the directory name (which works when the CLI was given the raw ID).
+    """
+    try:
+        from _paths import get_local_path
+        base = get_local_path("wicked-crew", "projects")
+        # Validate before using as a path component
+        if re.match(r'^[a-zA-Z0-9_-]{1,64}$', project_arg):
+            direct = base / project_arg
+            if direct.is_dir():
+                return project_arg
+
+        # Scan all project directories for a name match
+        if base.exists():
+            for p in base.iterdir():
+                if not p.is_dir():
+                    continue
+                pjson = _safe_read_json(p / "project.json")
+                if pjson and (pjson.get("name") == project_arg or pjson.get("id") == project_arg):
+                    return p.name
+    except Exception:
+        pass
+    return project_arg
+
+
+def _get_phase_plan(project_dir: Path) -> list:
+    """Return the phase_plan list from project.json, or [] on failure."""
+    pjson = _safe_read_json(project_dir / "project.json")
+    if isinstance(pjson, dict):
+        return [str(p) for p in pjson.get("phase_plan", [])]
+    return []
+
+
+def _get_project_complexity(project_dir: Path) -> int:
+    """Return complexity_score from project.json, or 0 on failure."""
+    pjson = _safe_read_json(project_dir / "project.json")
+    if isinstance(pjson, dict):
+        return int(pjson.get("complexity_score", 0))
+    return 0
+
+
+def _check_skipped_phases(phase_dir_base: Path, phase_plan: list, current_phase: str) -> str:
+    """Return error message if any planned phase before current_phase has no directory.
+
+    A missing phase directory means the phase was silently skipped without
+    going through the proper skip flow (which records a skip reason).
+    """
+    try:
+        idx = phase_plan.index(current_phase)
+    except ValueError:
+        return ""  # current phase not in plan — can't assess
+
+    for prev in phase_plan[:idx]:
+        if not (phase_dir_base / prev).is_dir():
+            return (
+                f"phase '{prev}' has no execution directory — it appears to have been "
+                f"silently skipped without a recorded skip reason. "
+                f"Use /wicked-garden:crew:approve on '{prev}' first, or record a valid "
+                f"skip reason via phase_manager.py {prev} skip."
+            )
+    return ""
+
+
+def _check_deliverables(phase_dir: Path, phase_name: str, phases_config: dict) -> str:
+    """Return error message if any required deliverable is missing or too small."""
+    phase = phases_config.get(phase_name, {})
+    raw_deliverables = phase.get("required_deliverables", [])
+
+    for entry in raw_deliverables:
+        if isinstance(entry, str):
+            entry = {"file": entry, "min_bytes": 100, "frontmatter": []}
+        elif not isinstance(entry, dict):
+            continue
+
+        fname = entry.get("file", "")
+        min_bytes = int(entry.get("min_bytes", 100))
+        required_fm = entry.get("frontmatter", [])
+
+        if not fname:
+            continue
+
+        fpath = phase_dir / fname
+        if not fpath.exists():
+            return (
+                f"required deliverable '{fname}' is missing from phases/{phase_name}/. "
+                f"Complete the phase work before approving."
+            )
+
+        size = fpath.stat().st_size
+        if size < min_bytes:
+            return (
+                f"required deliverable '{fname}' is too small ({size} bytes, "
+                f"minimum {min_bytes} bytes). The file may be a stub or incomplete."
+            )
+
+        # Check frontmatter fields
+        if required_fm:
+            text = _safe_read_text(fpath)
+            fm = _parse_frontmatter(text)
+            for field in required_fm:
+                if field not in fm or not fm[field]:
+                    return (
+                        f"required deliverable '{fname}' is missing frontmatter field "
+                        f"'{field}'. Add the field to the YAML frontmatter block."
+                    )
+
+    return ""
+
+
+def _check_test_coverage(phase_dir_base: Path, phase_name: str, phases_config: dict) -> str:
+    """Return error message if test coverage ratio is below threshold."""
+    phase = phases_config.get(phase_name, {})
+    min_coverage = phase.get("min_test_coverage")
+
+    # Only enforce for phases that declare a coverage requirement
+    if min_coverage is None:
+        return ""
+
+    # --- Find the planned count from test-strategy ---
+    planned = 0
+    for strategy_fname in ("test-plan.md", "test-strategy.md"):
+        strategy_path = phase_dir_base / "test-strategy" / strategy_fname
+        if strategy_path.exists():
+            fm = _parse_frontmatter(_safe_read_text(strategy_path))
+            raw = fm.get("case_count", "")
+            if raw:
+                try:
+                    planned = int(re.sub(r"[^\d]", "", raw))
+                except ValueError:
+                    pass
+            if planned:
+                break
+
+    if not planned:
+        return ""  # Can't assess without a planned count
+
+    # --- Find the executed count from test-results ---
+    executed = 0
+    results_path = phase_dir_base / phase_name / "test-results.md"
+    if results_path.exists():
+        text = _safe_read_text(results_path)
+        fm = _parse_frontmatter(text)
+
+        # Try frontmatter fields first
+        for key in ("executed", "pass_count", "total_count", "test_count"):
+            if key in fm:
+                try:
+                    executed = int(re.sub(r"[^\d]", "", fm[key]))
+                    break
+                except ValueError:
+                    pass
+
+        # Fallback: count test entries in markdown body (lines starting with - [ ] or - [x])
+        if not executed:
+            executed = len(re.findall(r"- \[[ xX]\]", text))
+
+    if not executed:
+        return ""  # Can't assess without an executed count
+
+    ratio = executed / planned
+    if ratio < min_coverage:
+        pct_actual = int(ratio * 100)
+        pct_required = int(min_coverage * 100)
+        return (
+            f"test coverage is {pct_actual}% ({executed}/{planned} tests executed), "
+            f"but {pct_required}% is required for phase '{phase_name}'. "
+            f"Run the missing tests and update test-results.md before approving."
+        )
+
+    return ""
+
+
+def _check_conditions_resolved(phase_dir_base: Path, phase_plan: list, current_phase: str,
+                                phases_config: dict) -> str:
+    """Return error message if any prior phase has unresolved conditions."""
+    try:
+        idx = phase_plan.index(current_phase)
+    except ValueError:
+        return ""
+
+    for prev in phase_plan[:idx]:
+        prev_cfg = phases_config.get(prev, {})
+        if not prev_cfg.get("conditions_manifest_required", False):
+            continue
+
+        manifest_path = phase_dir_base / prev / "conditions-manifest.json"
+        if not manifest_path.exists():
+            continue  # No manifest = no conditional gate was issued
+
+        manifest = _safe_read_json(manifest_path)
+        if not isinstance(manifest, (list, dict)):
+            continue
+
+        conditions = manifest if isinstance(manifest, list) else manifest.get("conditions", [])
+        unresolved = [c for c in conditions if isinstance(c, dict) and not c.get("resolved_at")]
+        if unresolved:
+            labels = [c.get("id") or c.get("description", "unknown") for c in unresolved[:3]]
+            extra = f" (and {len(unresolved) - 3} more)" if len(unresolved) > 3 else ""
+            return (
+                f"phase '{prev}' has {len(unresolved)} unresolved condition(s): "
+                f"{', '.join(labels)}{extra}. "
+                f"Resolve all conditions in phases/{prev}/conditions-manifest.json "
+                f"before approving '{current_phase}'."
+            )
+
+    return ""
+
+
+def _check_specialist_engagement(phase_dir: Path, phase_name: str, phases_config: dict,
+                                  complexity: int) -> str:
+    """Return error message if required specialists are missing and complexity >= 5."""
+    phase = phases_config.get(phase_name, {})
+    required = phase.get("required_specialists", [])
+
+    if not required or complexity < 5:
+        return ""
+
+    # Site W9 of bus-cutover wave-2 (#746): the engagement file
+    # was refactored from JSON-array (read-modify-write) to JSONL
+    # (append-only) in W9a.  Read the JSONL form preferentially; fall
+    # back to the legacy .json form for production projects that
+    # haven't yet had their first post-W9a engagement recorded.  The
+    # next engagement append starts the .jsonl file fresh; both readers
+    # eventually converge on JSONL as projects exercise the hook.
+    engaged_domains: set = set()
+    engagement_jsonl = phase_dir / "specialist-engagement.jsonl"
+    engagement_json = phase_dir / "specialist-engagement.json"
+    if engagement_jsonl.exists():
+        try:
+            for line in engagement_jsonl.read_text(encoding="utf-8").splitlines():
+                line = line.strip()
+                if not line:
+                    continue
+                try:
+                    entry = json.loads(line)
+                except json.JSONDecodeError:
+                    continue
+                if isinstance(entry, dict):
+                    engaged_domains.add(entry.get("domain", ""))
+        except OSError:
+            pass  # fail-open: file unreadable → treat as no engagement
+    elif engagement_json.exists():
+        # Legacy backward-compat read for pre-W9a projects.
+        entries = _safe_read_json(engagement_json)
+        if isinstance(entries, list):
+            engaged_domains = {
+                e.get("domain", "") for e in entries if isinstance(e, dict)
+            }
+
+    missing = [s for s in required if s not in engaged_domains]
+    if missing:
+        return (
+            f"required specialist(s) did not engage for phase '{phase_name}': "
+            f"{', '.join(missing)}. "
+            f"This project has complexity {complexity} (>= 5), so specialist engagement "
+            f"is mandatory. Invoke the missing specialists via Task() before approving."
+        )
+
+    return ""
+
+
+def _warn_reviewer_report(phase_dir: Path, phase_name: str, complexity: int) -> str:
+    """Return a warning (non-blocking) if reviewer-report.md is missing for high-complexity phases."""
+    if complexity < 5:
+        return ""
+    report_path = phase_dir / "reviewer-report.md"
+    if not report_path.exists():
+        return (
+            f"[wicked-garden] Warning: phases/{phase_name}/reviewer-report.md is missing "
+            f"for a complexity-{complexity} project. The async reviewer (Tier 2) should "
+            f"have written this. Proceeding with approve, but consider running "
+            f"/wicked-garden:crew:gate to generate a reviewer report."
+        )
+    return ""
+
+
+def _crew_gate_preflight(command: str) -> dict:
+    """Run deterministic file-based gate checks before phase_manager.py approve executes.
+
+    Returns {"ok": True} to allow, or {"ok": False, "reason": "..."} to block.
+    All checks complete in <100ms (file stat + small reads only).
+    Fails open on any unexpected error.
+    """
+    # ------------------------------------------------------------------ #
+    # FAST EARLY-EXIT: skip if not an approve call                        #
+    # ------------------------------------------------------------------ #
+    if "phase_manager.py" not in command or "approve" not in command:
+        return {"ok": True}
+
+    # ------------------------------------------------------------------ #
+    # v6.0: strict enforcement always active (D3 — no legacy bypass)     #
+    # ------------------------------------------------------------------ #
+
+    # ------------------------------------------------------------------ #
+    # Parse project and phase from command                                 #
+    # ------------------------------------------------------------------ #
+    m = _APPROVE_RE.search(command)
+    if not m:
+        return {"ok": True}  # Unrecognised form — fail open
+
+    project_arg = m.group(1)
+    phase_name = m.group(2)
+
+    if not project_arg:
+        return {"ok": True}
+
+    # If --phase was not explicit, try to derive from session state
+    if not phase_name:
+        try:
+            from _session import SessionState
+            state = SessionState.load()
+            if state.active_project and isinstance(state.active_project, dict):
+                phase_name = state.active_project.get("current_phase")
+        except Exception:
+            pass
+
+    if not phase_name:
+        return {"ok": True}  # Can't validate without knowing the phase
+
+    # ------------------------------------------------------------------ #
+    # Resolve paths                                                        #
+    # ------------------------------------------------------------------ #
+    try:
+        project_id = _get_project_id_for(project_arg)
+        from _paths import get_local_path
+        base = get_local_path("wicked-crew", "projects")
+        project_dir = base / project_id
+        phase_dir = project_dir / "phases" / phase_name
+        phase_dir_base = project_dir / "phases"
+    except Exception:
+        return {"ok": True}  # Path resolution failure — fail open
+
+    # If project.json doesn't exist, we have no ground truth — fail open.
+    # This handles the case where phase_manager.py is invoked on a project
+    # that doesn't yet have local state (e.g. first run, or different workspace).
+    if not (project_dir / "project.json").exists():
+        return {"ok": True}
+
+    phases_config = _load_phases_config_hook()
+    phase_plan = _get_phase_plan(project_dir)
+    complexity = _get_project_complexity(project_dir)
+
+    # ------------------------------------------------------------------ #
+    # Check a: Skipped phase detection                                     #
+    # ------------------------------------------------------------------ #
+    if phase_plan:
+        msg = _check_skipped_phases(phase_dir_base, phase_plan, phase_name)
+        if msg:
+            return {"ok": False, "reason": f"Cannot approve {phase_name}: {msg}"}
+
+    # ------------------------------------------------------------------ #
+    # Check b: Phase directory exists                                      #
+    # ------------------------------------------------------------------ #
+    if not phase_dir.is_dir():
+        return {
+            "ok": False,
+            "reason": (
+                f"Cannot approve {phase_name}: phases/{phase_name}/ directory does not exist. "
+                f"The phase has not produced any output. Execute the phase before approving."
+            ),
+        }
+
+    # ------------------------------------------------------------------ #
+    # Check c: Required deliverables present + frontmatter valid          #
+    # ------------------------------------------------------------------ #
+    msg = _check_deliverables(phase_dir, phase_name, phases_config)
+    if msg:
+        return {"ok": False, "reason": f"Cannot approve {phase_name}: {msg}"}
+
+    # ------------------------------------------------------------------ #
+    # Check d: Test coverage ratio                                         #
+    # ------------------------------------------------------------------ #
+    msg = _check_test_coverage(phase_dir_base, phase_name, phases_config)
+    if msg:
+        return {"ok": False, "reason": f"Cannot approve {phase_name}: {msg}"}
+
+    # ------------------------------------------------------------------ #
+    # Check e: Conditions resolved in prior phases                        #
+    # ------------------------------------------------------------------ #
+    if phase_plan:
+        msg = _check_conditions_resolved(phase_dir_base, phase_plan, phase_name, phases_config)
+        if msg:
+            return {"ok": False, "reason": f"Cannot approve {phase_name}: {msg}"}
+
+    # ------------------------------------------------------------------ #
+    # Check f: Specialist engagement (blocks if complexity >= 5)          #
+    # ------------------------------------------------------------------ #
+    msg = _check_specialist_engagement(phase_dir, phase_name, phases_config, complexity)
+    if msg:
+        return {"ok": False, "reason": f"Cannot approve {phase_name}: {msg}"}
+
+    # ------------------------------------------------------------------ #
+    # Check g: Reviewer report (warn only)                                #
+    # ------------------------------------------------------------------ #
+    warning = _warn_reviewer_report(phase_dir, phase_name, complexity)
+
+    return {"ok": True, "_warning": warning}
+
+
+def _handle_bash(tool_input: dict, cwd: str = "") -> str:
+    """Bash preflight: crew gate check + worktree cwd-leak guard (#878)."""
+    command = tool_input.get("command", "") or ""
+
+    # Crew gate preflight first — a hard deny here blocks regardless of cwd.
+    # Fast path — non-approve Bash commands take <1ms.
+    result = _crew_gate_preflight(command)
+    if not result.get("ok"):
+        return _deny(result.get("reason", "Gate preflight check failed."))
+    warning = result.get("_warning", "") or None
+
+    # Worktree cwd-leak guard (#878): when an isolated-worktree agent runs a
+    # Bash command, anchor it in the worktree (cd <root> && ...) so a leaked
+    # persistent cwd cannot land commits in the main repo. Fail-open by design.
+    try:
+        from worktree_guard import evaluate as _wt_evaluate
+        decision = _wt_evaluate(command, cwd)
+    except Exception:
+        decision = None
+    if decision:
+        if decision.get("action") == "deny":
+            return _deny(decision["reason"])
+        if decision.get("action") == "rewrite":
+            updated = dict(tool_input)
+            updated["command"] = decision["command"]
+            return _allow(updated_input=updated, system_message=warning)
+
+    return _allow(system_message=warning)
+
+
+# ---------------------------------------------------------------------------
+# Main dispatcher
+# ---------------------------------------------------------------------------
+
+def main():
+    _t0 = time.monotonic()
+
+    try:
+        raw = sys.stdin.read()
+        input_data = json.loads(raw) if raw.strip() else {}
+    except Exception:
+        print(_allow())
+        return
+
+    try:
+        tool_name = input_data.get("tool_name", "")
+        tool_input = input_data.get("tool_input", {}) or {}
+
+        _log("pretool", "debug", "hook.start", detail={"tool": tool_name})
+
+        if tool_name == "TaskCreate":
+            result = _handle_task_create(tool_input)
+            _log("pretool", "debug", "hook.end", ms=int((time.monotonic() - _t0) * 1000))
+            print(result)
+            return
+
+        if tool_name == "TaskUpdate":
+            result = _handle_task_update(tool_input)
+            _log("pretool", "debug", "hook.end", ms=int((time.monotonic() - _t0) * 1000))
+            print(result)
+            return
+
+        if tool_name == "EnterPlanMode":
+            result = _handle_enter_plan_mode(tool_input)
+            _log("pretool", "debug", "hook.end", ms=int((time.monotonic() - _t0) * 1000))
+            print(result)
+            return
+
+        if tool_name in ("Write", "Edit"):
+            result = _handle_write_guard(tool_input)
+            _log("pretool", "debug", "hook.end", ms=int((time.monotonic() - _t0) * 1000))
+            print(result)
+            return
+
+        if tool_name == "Bash":
+            result = _handle_bash(tool_input, input_data.get("cwd", "") or "")
+            _log("pretool", "debug", "hook.end", ms=int((time.monotonic() - _t0) * 1000))
+            print(result)
+            return
+
+        # All other tools — allow
+        _log("pretool", "debug", "hook.end", ms=int((time.monotonic() - _t0) * 1000))
+        print(_allow())
+
+    except Exception as e:
+        print(f"[wicked-garden] pre_tool error: {e}", file=sys.stderr)
+        # Always fail open on error
+        print(_allow())
+
+
+if __name__ == "__main__":
+    main()