@ikon85/agent-workflow-kit 0.23.0 → 0.25.0

package/.claude/skills/setup-workflow/SKILL.md

@@ -26,7 +26,7 @@ This is a prompt-driven skill, not a deterministic script. Explore, present what
 | `## Agent skills` + `## Prod` in CLAUDE.md **and** AGENTS.md | one-line pointers + deploy target (Sections C/G + Write) |
 | `.github/workflows/agent-workflow-kit-update.yml` | optional tested Kit update pull request for GitHub consumers (Section A2) |
 | `docs/agents/census.md` | optional-census choice, paths, state, and safe disable contract seeded from [census.md](./census.md) (Section A3) |
-| `docs/agents/workflow-capabilities.json` + capability assets | consumer-owned Worktree Lifecycle activation and one-time Memory Lifecycle policy seeds (Sections A4–A5) |
+| `docs/agents/workflow-capabilities.json` + capability assets | consumer-owned Worktree Lifecycle, Memory Lifecycle, and Workflow Advisories choices (Sections A4–A6) |
 
 ## Idempotency contract — read before writing anything
 
@@ -57,7 +57,7 @@ Read the current state; don't assume. For every target file, read its first line
 - `CONTEXT.md`, `CONTEXT-MAP.md`, `docs/adr/` — domain-doc layout.
 - `docs/agents/`, `docs/agents/skills/`, `docs/conventions/` — prior output of this skill.
 - `docs/agents/census.md`, `.census/profile.json`, `.census/active.json` — an existing census choice or consumer-owned census to adopt.
-- `docs/agents/workflow-capabilities.json`, `.claude/settings.json` — existing capability choices/profile and Worktree Lifecycle hook wiring to adopt.
+- `docs/agents/workflow-capabilities.json`, `.claude/settings.json` — existing capability choices/profile plus Worktree Lifecycle and Workflow Advisories hook wiring to adopt.
 - `.memory/active/`, `.memory/archive/`, and `.memory/receipts/` — consumer-owned Memory Lifecycle policies or recovery evidence to adopt without normalization.
 - `gh auth status` (if GitHub) — is `gh` authenticated, and with which scopes?
 
@@ -199,6 +199,25 @@ activation, roots, retention, restore, or pruning grants. Template files have
 no kit-managed or `append-managed` region; a future bounded-region contract
 requires a separate decision.
 
+### 2e. Section A6 — Optional Workflow Advisories
+
+> Workflow Advisories provides non-blocking, low-noise hints and
+> affected-surface checks around large reads, first-impacting edits, refactors,
+> and Stop. Paths, commands, thresholds, timeouts, and output budgets remain
+> consumer-owned.
+
+Read [workflow-advisories.md](./workflow-advisories.md) in full. Reconcile its
+complete `yes / later / no / existing / disable` matrix. If no choice exists,
+ask: *"Should setup activate the portable Workflow Advisories for this
+repository?"* Offer exactly **Yes**, **Later**, and **No**.
+
+- **Yes** — reconcile only `workflowAdvisories` in the shared capability
+  profile and only the exact kit-owned hook commands named by the seed.
+- **Later / No** — record the choice without hook wiring.
+- **Existing** — adopt profile and wiring byte-safely.
+- **Disable** — remove exact kit-owned commands first, then set `enabled:
+  false`; preserve every profile value and unknown key.
+
 ### 3. Section B — Triage labels
 
 > When `triage` processes an incoming issue it applies labels (or your tracker's equivalent). It needs strings you've actually configured, or it creates duplicates.
@@ -284,11 +303,12 @@ pre-existing consumer-owned census file. `yes`, `later`, `no`, and an adopted
 existing census are terminal for ordinary setup reruns. Only an explicit user
 request changes a recorded choice.
 
-For `docs/agents/workflow-capabilities.json`, reconcile only the selected
+For `docs/agents/workflow-capabilities.json`, reconcile only each selected
 capability section. Never replace the whole file: Project Release, Memory
-Lifecycle, Worktree Lifecycle, future sections, and unknown consumer keys share
-this profile. Apply the Worktree Lifecycle transition and hook ownership rules
-from [worktree-lifecycle.md](./worktree-lifecycle.md) transactionally.
+Lifecycle, Worktree Lifecycle, Workflow Advisories, future sections, and
+unknown consumer keys share this profile. Apply the transition and hook
+ownership rules from [worktree-lifecycle.md](./worktree-lifecycle.md) and
+[workflow-advisories.md](./workflow-advisories.md) transactionally.
 
 For Memory Lifecycle, use only the deterministic setup helper from Section A5.
 Do not copy templates with shell commands or edit the capability profile by

package/.claude/skills/setup-workflow/workflow-advisories.md

@@ -0,0 +1,97 @@
+# Workflow Advisories setup contract
+
+Workflow Advisories is one opt-in capability backed by the consumer-owned
+`docs/agents/workflow-capabilities.json` profile. Enabling it activates seven
+non-blocking rows: large-read, baseline, pre-refactor, affected-surface Stop,
+convention freshness, migration-artifact reminder, and LoC forewarning. Every
+threshold, glob, branch rule, source map, command, timeout, and output budget
+stays consumer-owned.
+
+## Choice matrix
+
+| State | Setup action |
+|---|---|
+| `missing` | Ask `yes / later / no`; do not infer or write before the answer. |
+| `yes` | Reconcile the enabled profile and exact kit-owned hook commands. |
+| `later` | Record the retryable deferral; do not activate hooks. |
+| `no` | Record the opt-out; do not activate hooks. |
+| `existing` | Adopt the consumer profile byte-safely and preserve unknown keys. |
+| `disable` | Remove only kit-owned hook wiring, then set `enabled: false`; retain profile values and unknown keys. |
+
+```json workflow-advisories-setup-effects
+[
+  {"state":"missing","choice":null,"operations":[]},
+  {"state":"yes","choice":"yes","operations":["record-choice","reconcile-profile-enabled","reconcile-hook-wiring"]},
+  {"state":"later","choice":"later","operations":["record-choice"]},
+  {"state":"no","choice":"no","operations":["record-choice"]},
+  {"state":"existing","choice":"yes","operations":["adopt-existing"]},
+  {"state":"disable","choice":"yes","operations":["remove-hook-wiring","update-profile-disabled"]}
+]
+```
+
+## Profile shape
+
+Reconcile only `workflowAdvisories`; preserve every sibling section and unknown
+key. Consumer values are never normalized on adoption.
+
+```json
+{
+  "workflowAdvisories": {
+    "choice": "yes",
+    "enabled": true,
+    "largeRead": {"tools": ["Read"], "lineThreshold": 500, "outputBudget": 500},
+    "baseline": {
+      "sourceGlobs": ["src/**"],
+      "branchRegex": "^(?:feat|fix)/",
+      "manifestPath": ".agent/baseline.json",
+      "stateDir": ".claude/logs/advisory-state",
+      "outputBudget": 500
+    },
+    "preRefactor": {
+      "promptMatchers": ["refactor"],
+      "surfaces": [],
+      "timeoutSeconds": 15,
+      "outputBudget": 1000
+    },
+    "stopChecks": {"surfaces": [], "timeoutSeconds": 30, "outputBudget": 1000},
+    "freshness": {"documents": [], "outputBudget": 1000},
+    "migration": {
+      "commandMatchers": [],
+      "artifact": "",
+      "refreshCommand": [],
+      "outputBudget": 500
+    },
+    "locForewarn": {
+      "branchRegex": "^(?:feat|fix)/(\\d+)-",
+      "issueCommand": ["gh", "issue", "view", "{issue}", "--json", "body", "-q", ".body"],
+      "timeoutSeconds": 5,
+      "outputBudget": 500
+    }
+  }
+}
+```
+
+Empty command surfaces are honest inactive defaults. Setup recommends concrete
+project commands from the tools already present, then asks before activating.
+
+## Hook ownership
+
+- PreToolUse on Read:
+  `python3 "$CLAUDE_PROJECT_DIR/.claude/hooks/recon-size-hint.py"`
+- PreToolUse on Edit/Write/MultiEdit:
+  `python3 "$CLAUDE_PROJECT_DIR/.claude/hooks/baseline-capture-hint.py"`
+- UserPromptSubmit:
+  `python3 "$CLAUDE_PROJECT_DIR/.claude/hooks/pre-refactor-sweep.py"`
+- Stop:
+  `"$CLAUDE_PROJECT_DIR/.claude/hooks/typecheck-on-stop.sh"`
+- SessionStart convention freshness:
+  `python3 "$CLAUDE_PROJECT_DIR/.claude/hooks/convention-drift-hint.py"`
+- PostToolUse on Bash migration commands:
+  `python3 "$CLAUDE_PROJECT_DIR/.claude/hooks/migration-snapshot-reminder.py"`
+- SessionStart LoC forewarning:
+  `python3 "$CLAUDE_PROJECT_DIR/.claude/hooks/loc-offender-forewarn.py"`
+
+All adapters are non-blocking. A failed or timed-out configured command remains
+visibly failed in hook context; it is never reported as green. Issue lookup
+failures silence only the LoC forewarning: the existing pre-push gate remains
+the enforcing authority and stays fail-closed.

package/README.md

@@ -332,6 +332,33 @@ still reference. Flags: `--force` (overwrite pre-existing files on `init`),
 
 ## Release notes
 
+### 0.25.0
+
+- added: `.claude/hooks/convention-drift-hint.py`
+- added: `.claude/hooks/loc-offender-forewarn.py`
+- added: `.claude/hooks/migration-snapshot-reminder.py`
+- added: `scripts/workflow-advisories/capabilities.json`
+- changed: `.agents/skills/setup-workflow/workflow-advisories.md`
+- changed: `.claude/hooks/_hook_utils.py`
+- changed: `.claude/hooks/skill-drift-hint.py`
+- changed: `.claude/skills/setup-workflow/workflow-advisories.md`
+- changed: `scripts/loc_offender_gate.py`
+- changed: `scripts/workflow-advisories/core.py`
+
+### 0.24.0
+
+- added: `.agents/skills/setup-workflow/workflow-advisories.md`
+- added: `.claude/hooks/baseline-capture-hint.py`
+- added: `.claude/hooks/pre-refactor-sweep.py`
+- added: `.claude/hooks/recon-size-hint.py`
+- added: `.claude/hooks/typecheck-on-stop.py`
+- added: `.claude/hooks/typecheck-on-stop.sh`
+- added: `.claude/skills/setup-workflow/workflow-advisories.md`
+- added: `scripts/workflow-advisories/core.py`
+- changed: `.agents/skills/setup-workflow/SKILL.md`
+- changed: `.claude/hooks/_hook_utils.py`
+- changed: `.claude/skills/setup-workflow/SKILL.md`
+
 ### 0.23.0
 
 - added: `assets/memory-templates/meta_decision_layer_choice.md`

package/agent-workflow-kit.package.json

@@ -1,5 +1,5 @@
 {
-  "kitVersion": "0.23.0",
+  "kitVersion": "0.25.0",
   "files": [
     {
       "path": ".agents/skills/ask-matt/SKILL.md",
@@ -573,7 +573,7 @@
       "kind": "skill",
       "ownerSkill": "setup-workflow",
       "surface": "codex",
-      "sha256": "247250aa38a81b542600db42cfe4d02eecc1236e8af47df1f4def627f4df0668",
+      "sha256": "96c0c3ba9ed6b194030a8c45be618caf934e9c4ca8415ea19d726af33cd763cb",
       "mode": 420,
       "origin": "kit"
     },
@@ -613,6 +613,15 @@
       "mode": 420,
       "origin": "kit"
     },
+    {
+      "path": ".agents/skills/setup-workflow/workflow-advisories.md",
+      "kind": "skill",
+      "ownerSkill": "setup-workflow",
+      "surface": "codex",
+      "sha256": "81ce0f5573d5f062adbc87149172e74ab322315bf348025c0ff2c27f8d8ec67b",
+      "mode": 420,
+      "origin": "kit"
+    },
     {
       "path": ".agents/skills/setup-workflow/workflow-overview.md",
       "kind": "skill",
@@ -877,10 +886,17 @@
     {
       "path": ".claude/hooks/_hook_utils.py",
       "kind": "hook",
-      "sha256": "58a7a8ad6cd4f1660e95343d7a0c637cf8aee92948a9c554befa5851723b3f48",
+      "sha256": "9ad70fa80a57c7712df78718c578b58295f446c13a0f1863c69680f3889dd387",
       "mode": 420,
       "origin": "kit"
     },
+    {
+      "path": ".claude/hooks/baseline-capture-hint.py",
+      "kind": "hook",
+      "sha256": "8f5cddfbb567afc677cf51f39d37e10804bf03e93d7d2fac7793cb5a42473ed3",
+      "mode": 493,
+      "origin": "kit"
+    },
     {
       "path": ".claude/hooks/branch-context.py",
       "kind": "hook",
@@ -895,6 +911,13 @@
       "mode": 493,
       "origin": "kit"
     },
+    {
+      "path": ".claude/hooks/convention-drift-hint.py",
+      "kind": "hook",
+      "sha256": "f89fc3f3f9d9b7508e3cdeeedd0e522af11ae10e638457da3910bfe4e43579f2",
+      "mode": 493,
+      "origin": "kit"
+    },
     {
       "path": ".claude/hooks/drift-guard.py",
       "kind": "hook",
@@ -923,10 +946,38 @@
       "mode": 493,
       "origin": "kit"
     },
+    {
+      "path": ".claude/hooks/loc-offender-forewarn.py",
+      "kind": "hook",
+      "sha256": "28ba5edb1898345fd852d1f420bb64c5a2e0dfd66aa8d2b752899fc28a6f80dd",
+      "mode": 493,
+      "origin": "kit"
+    },
+    {
+      "path": ".claude/hooks/migration-snapshot-reminder.py",
+      "kind": "hook",
+      "sha256": "693227fae1aa3e782ed5b61a9e8c3fc8c1880a617efd14cb86ca7f38d9a8f204",
+      "mode": 493,
+      "origin": "kit"
+    },
+    {
+      "path": ".claude/hooks/pre-refactor-sweep.py",
+      "kind": "hook",
+      "sha256": "24e8554da18b00f2dbbcf6a3e186f9fb675a4b18471ce60e0ac63000f95a4906",
+      "mode": 493,
+      "origin": "kit"
+    },
+    {
+      "path": ".claude/hooks/recon-size-hint.py",
+      "kind": "hook",
+      "sha256": "3fd702d8875552ce3b79b5db1dda51403031bcacc80901a13553d2f60a2deb9b",
+      "mode": 493,
+      "origin": "kit"
+    },
     {
       "path": ".claude/hooks/skill-drift-hint.py",
       "kind": "hook",
-      "sha256": "4842e1c6dfd1042eb924d9cc36a8aa5d0c5a1e95f71e33a82db3322dc9d13fd0",
+      "sha256": "2ce5c8cfc85dc76cf93abf1cd061440b8030109231a45a0920e36a5f1c06694a",
       "mode": 493,
       "origin": "kit"
     },
@@ -944,6 +995,20 @@
       "mode": 493,
       "origin": "kit"
     },
+    {
+      "path": ".claude/hooks/typecheck-on-stop.py",
+      "kind": "hook",
+      "sha256": "459e5f25f5fe97c62687eff1d3e7e76051ba8390e2b2908fc50c16ea53a95250",
+      "mode": 493,
+      "origin": "kit"
+    },
+    {
+      "path": ".claude/hooks/typecheck-on-stop.sh",
+      "kind": "hook",
+      "sha256": "1bb57f53d53d18af92a8c7ce63f46be0658ae7d675a95d387646b4232001f1bc",
+      "mode": 493,
+      "origin": "kit"
+    },
     {
       "path": ".claude/skills/ask-matt/SKILL.md",
       "kind": "skill",
@@ -1642,7 +1707,7 @@
       "kind": "skill",
       "ownerSkill": "setup-workflow",
       "surface": "claude",
-      "sha256": "247250aa38a81b542600db42cfe4d02eecc1236e8af47df1f4def627f4df0668",
+      "sha256": "96c0c3ba9ed6b194030a8c45be618caf934e9c4ca8415ea19d726af33cd763cb",
       "mode": 420,
       "origin": "kit"
     },
@@ -1682,6 +1747,15 @@
       "mode": 420,
       "origin": "kit"
     },
+    {
+      "path": ".claude/skills/setup-workflow/workflow-advisories.md",
+      "kind": "skill",
+      "ownerSkill": "setup-workflow",
+      "surface": "claude",
+      "sha256": "81ce0f5573d5f062adbc87149172e74ab322315bf348025c0ff2c27f8d8ec67b",
+      "mode": 420,
+      "origin": "kit"
+    },
     {
       "path": ".claude/skills/setup-workflow/workflow-overview.md",
       "kind": "skill",
@@ -2106,7 +2180,7 @@
     {
       "path": "scripts/loc_offender_gate.py",
       "kind": "script",
-      "sha256": "3e96b180bbe922c85ea511da94f118b6d8d8937bc000c8a31b1a88bac211545e",
+      "sha256": "a66650b3b194a00ecc3ba37acae4bbb1aeeb57762d27fb2dfd3bb1fc2734a8a5",
       "mode": 493,
       "origin": "kit"
     },
@@ -2194,6 +2268,20 @@
       "mode": 420,
       "origin": "kit"
     },
+    {
+      "path": "scripts/workflow-advisories/capabilities.json",
+      "kind": "doc",
+      "sha256": "04c731394fa458c141870fb89f2432092b3749955eccbda9b9b8db09636526c9",
+      "mode": 420,
+      "origin": "kit"
+    },
+    {
+      "path": "scripts/workflow-advisories/core.py",
+      "kind": "script",
+      "sha256": "dc47bc20ed1107d230f45ff7158e4fd81d6473be515e03cbd52274f3e87d840d",
+      "mode": 420,
+      "origin": "kit"
+    },
     {
       "path": "scripts/worktree-lifecycle/capabilities.json",
       "kind": "doc",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ikon85/agent-workflow-kit",
-  "version": "0.23.0",
+  "version": "0.25.0",
   "description": "Portable AI-agent workflow skills (plan → execute → land → learn) for Claude Code & Codex — grilling, TDD, diagnosis, two-axis code review, cross-model Codex review, design & domain-modeling, plus a skill router (ask-matt). npx init/update/diff/uninstall.",
   "type": "module",
   "bin": {

package/scripts/loc_offender_gate.py

@@ -10,6 +10,7 @@ from __future__ import annotations
 
 import argparse
 import json
+import re
 import subprocess
 import sys
 from pathlib import Path
@@ -25,6 +26,29 @@ class GateError(RuntimeError):
     """A condition the gate cannot evaluate → fail-closed (exit 1)."""
 
 
+_ISSUE_MARKER_RE = re.compile(r"<!--\s*loc-offender:\s*([^>]+?)\s*-->")
+
+
+def parse_issue_marker(body: str) -> list[str]:
+    """Read the machine marker planted by board-sync at buildability transition."""
+    match = _ISSUE_MARKER_RE.search(body or "")
+    return [
+        path.strip() for path in match.group(1).split(",") if path.strip()
+    ] if match else []
+
+
+def forewarning_context(body: str, max_lines: int, offenders: set[str]) -> str | None:
+    """Render a non-blocking SessionStart warning from the gate-owned contracts."""
+    hits = sorted(set(parse_issue_marker(body)) & offenders)
+    if not hits:
+        return None
+    paths = ", ".join(hits)
+    return (
+        f"LoC offender advisory: {paths} is named by the issue marker and remains "
+        f"above the gate threshold ({max_lines} lines). The pre-push gate stays authoritative."
+    )
+
+
 def _git(args, cwd=None) -> str:
     r = subprocess.run(["git", *args], cwd=cwd, capture_output=True, text=True)
     if r.returncode != 0:

package/scripts/safety-guardrails/core.py

@@ -0,0 +1,221 @@
+"""Profile-driven decisions for independently activatable Safety Guardrails."""
+
+from __future__ import annotations
+
+import json
+import re
+import shlex
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from search import scan as scan_search
+
+
+@dataclass(frozen=True)
+class GuardDecision:
+    action: str
+    message: str = ""
+    log_message: str = ""
+
+
+def load_profile(path: Path) -> dict[str, Any]:
+    document = json.loads(path.read_text(encoding="utf-8"))
+    section = document.get("safetyGuardrails")
+    if not isinstance(section, dict):
+        return {}
+    return section
+
+
+def inactive() -> GuardDecision:
+    return GuardDecision("allow")
+
+
+def _secret_name_is_sensitive(name: str, policy: dict[str, Any]) -> bool:
+    suffixes = tuple(policy.get("safeTemplateSuffixes") or ())
+    if name.startswith(".env"):
+        return not any(name.endswith(suffix) for suffix in suffixes)
+    return name in set(policy.get("sensitiveNames") or ())
+
+
+def _secret_path_is_sensitive(path: str, policy: dict[str, Any]) -> bool:
+    candidate = Path(path)
+    if _secret_name_is_sensitive(candidate.name, policy):
+        return True
+    normalized = str(candidate).replace("\\", "/")
+    return any(fragment in normalized for fragment in policy.get("sensitivePathFragments") or ())
+
+
+def secret_decision(policy: dict[str, Any], payload: dict[str, Any]) -> GuardDecision:
+    if policy.get("enabled") is not True:
+        return inactive()
+    tool = payload.get("tool_name")
+    tool_input = payload.get("tool_input") or {}
+    if tool == "Bash":
+        return _secret_bash_decision(policy, str(tool_input.get("command") or ""))
+    path = str(tool_input.get("file_path") or "")
+    if not path or tool not in {"Read", "Edit", "Write", "MultiEdit"}:
+        return inactive()
+    if tool == "Write" and Path(path).name.startswith(".env"):
+        return inactive()
+    if not _secret_path_is_sensitive(path, policy):
+        return inactive()
+    return GuardDecision(
+        "block",
+        f"BLOCKED: access to sensitive path '{path}' is not allowed.",
+        f"blocked tool={tool} path={path!r}",
+    )
+
+
+_DUMP_COMMANDS = {
+    "cat", "head", "tail", "less", "more", "strings", "nl", "xxd", "od",
+    "bat", "tac", "rev", "grep", "egrep", "fgrep", "rg", "ag", "awk", "sed", "cut",
+}
+_QUIET_GREP = {"grep", "egrep", "fgrep", "rg", "ag"}
+_INSTALL_RE = re.compile(
+    r"\b(?P<manager>npm|pnpm|yarn|bun)\s+(?:install|i|ci)\b"
+)
+_BACKGROUND_RE = re.compile(r"(?<![<>&])&[ \t]*(?:;|$)", re.MULTILINE)
+
+
+def _secret_bash_decision(policy: dict[str, Any], command: str) -> GuardDecision:
+    if not command:
+        return inactive()
+    try:
+        segments = re.split(r"\n|;|&&|\|\||\|", command)
+        for segment in segments:
+            tokens = shlex.split(segment)
+            dumps = set(tokens) & _DUMP_COMMANDS
+            paths = [token for token in tokens if _secret_path_is_sensitive(token, policy)]
+            if not dumps or not paths:
+                continue
+            if dumps <= _QUIET_GREP and any(flag == "--quiet" or flag.startswith("-q") for flag in tokens):
+                continue
+            return GuardDecision(
+                "block",
+                f"BLOCKED: command would print sensitive path '{paths[0]}' to the transcript.",
+                f"blocked bash secret dump path={paths[0]!r}",
+            )
+    except ValueError:
+        return inactive()
+    return inactive()
+
+
+def _effective_cwd(command: str, match_pos: int, fallback: Path) -> Path:
+    target = None
+    for match in re.finditer(r"(?:^|[;&|]\s*)cd\s+([^\s;&|]+)", command):
+        if match.end() <= match_pos:
+            target = match.group(1).strip("'\"")
+    if target is None:
+        return fallback
+    path = Path(target).expanduser()
+    return path if path.is_absolute() else fallback / path
+
+
+def _detected_manager(policy: dict[str, Any], start: Path) -> tuple[str, Path] | None:
+    lockfiles = policy.get("lockfiles") or {}
+    try:
+        current = start.resolve()
+    except OSError:
+        return None
+    while True:
+        for filename, manager in lockfiles.items():
+            candidate = current / filename
+            if candidate.is_file():
+                return str(manager), candidate
+        if current.parent == current:
+            return None
+        current = current.parent
+
+
+def package_manager_decision(
+    policy: dict[str, Any],
+    payload: dict[str, Any],
+    cwd: Path,
+) -> GuardDecision:
+    if policy.get("enabled") is not True or payload.get("tool_name") != "Bash":
+        return inactive()
+    command = str((payload.get("tool_input") or {}).get("command") or "")
+    match = _INSTALL_RE.search(command)
+    if match is None:
+        return inactive()
+    requested = match.group("manager")
+    detected = _detected_manager(policy, _effective_cwd(command, match.start(), cwd))
+    if detected is None or detected[0] == requested:
+        return inactive()
+    manager, lockfile = detected
+    return GuardDecision(
+        "block",
+        f"BLOCKED: `{match.group(0)}` conflicts with {lockfile.name}. "
+        f"Use `{manager} install` in this project.",
+        f"blocked package-manager requested={requested} expected={manager} lock={lockfile}",
+    )
+
+
+def double_background_decision(
+    policy: dict[str, Any],
+    payload: dict[str, Any],
+) -> GuardDecision:
+    if policy.get("enabled") is not True or payload.get("tool_name") != "Bash":
+        return inactive()
+    surface = str(payload.get("surface") or "claude")
+    if surface not in set(policy.get("surfaces") or ()):
+        return inactive()
+    tool_input = payload.get("tool_input") or {}
+    is_background = tool_input.get("run_in_background") is True or (
+        str(tool_input.get("run_in_background") or "").lower() == "true"
+    )
+    command = str(tool_input.get("command") or "")
+    if not is_background or not _BACKGROUND_RE.search(command):
+        return inactive()
+    return GuardDecision(
+        "block",
+        "BLOCKED: run_in_background already detaches and captures this command; "
+        "remove the inner `&` background operator.",
+        "blocked double-background command",
+    )
+
+
+def search_shim_decision(
+    policy: dict[str, Any],
+    payload: dict[str, Any],
+) -> GuardDecision:
+    if (
+        policy.get("enabled") is not True
+        or policy.get("detected") is not True
+        or payload.get("tool_name") != "Bash"
+    ):
+        return inactive()
+    command = str((payload.get("tool_input") or {}).get("command") or "")
+    finding = scan_search(command, set(policy.get("commandNames") or ()))
+    if finding is None:
+        return inactive()
+    reason, pattern = finding
+    return GuardDecision(
+        "block",
+        f"BLOCKED: search shim cannot safely evaluate pattern `{pattern}` ({reason}). "
+        "Use `--fixed-strings` or `command grep`.",
+        f"blocked search-shim breaker reason={reason}",
+    )
+
+
+def evaluate(kind: str, profile: dict[str, Any], payload: dict[str, Any]) -> GuardDecision:
+    if kind == "secrets":
+        return secret_decision(profile.get("secrets") or {}, payload)
+    if kind == "package-manager":
+        return package_manager_decision(
+            profile.get("packageManager") or {},
+            payload,
+            Path.cwd(),
+        )
+    if kind == "double-background":
+        return double_background_decision(
+            profile.get("doubleBackground") or {},
+            payload,
+        )
+    if kind == "search-shim":
+        return search_shim_decision(
+            profile.get("searchShim") or {},
+            payload,
+        )
+    return inactive()