claude-dev-env 1.90.0 → 1.92.1

package/CLAUDE.md

@@ -4,30 +4,9 @@ The user is short on time and appreciates brevity in replies. When you reply, al
 
 The user delegates execution to you and expects zero manual steps unless strictly necessary. Execute every command you can directly. Only instruct the user to do something manually when you are technically unable to do it yourself. When a task involves credentials or other sensitive input, display a minimal secure UI (e.g., a password dialog) to collect it rather than asking the user to paste it into chat or run the command themselves. When direction is ambiguous, use AskUserQuestion to clarify before acting.
 
-You have access to an `advisor` tool backed by a stronger reviewer model. It takes NO parameters — when you call advisor(), your entire conversation history is automatically forwarded. They see the task, every tool call you've made, every result you've seen.
-
-Call advisor BEFORE substantive work — before writing, before committing to an interpretation, before building on an assumption. If the task requires orientation first (finding files, fetching a source, seeing what's there), do that, then call advisor. Orientation is not substantive work. Writing, editing, and declaring an answer are.
-
-Also call advisor:
-- When you believe the task is complete. BEFORE this call, make your deliverable durable: write the file, save the result, commit the change. The advisor call takes time; if the session ends during it, a durable result persists and an unwritten one doesn't.
-- When stuck — errors recurring, approach not converging, results that don't fit.
-- When considering a change of approach.
-
-On tasks longer than a few steps, call advisor at least once before committing to an approach and once before declaring done. On short reactive tasks where the next action is dictated by tool output you just read, you don't need to keep calling — the advisor adds most of its value on the first call, before the approach crystallizes.
-
-ALWAYS call the AskUserQuestion tool if you have a question for the user. Provide content-appropriate default options, with a flag for the recommended one.
-
 ## Timeless Documentation (all `.md` files)
 
-Every Markdown file I write or edit describes the system's **current** state only. The test: a reader a year out, with zero prior context, finds every sentence true and complete without knowing what came before. State what **is**, not what changed — git history records change; docs record the contract.
-
-- No historical/transitional language (`previously`, `now uses`, `instead of`, `migrated from`, `used to`, `no longer`, `as of`, `originally`, version-transition narration).
-- No references to the conversation that produced the doc (`as discussed`, `Option A`, `after Round 3`).
-
-Full banned-pattern set + enforcement: `~/.claude/rules/no-historical-clutter.md` (hook `state-description-blocker`) and `~/.claude/rules/self-contained-docs.md`.
-
-## GOTCHAS
-ALWAYS start each session with a /loop 15m populate or update the task list based on remaining todos.
+Docs describe the current state only. Full rule set and enforcement: `~/.claude/rules/no-historical-clutter.md` (hook `state-description-blocker`) and `~/.claude/rules/self-contained-docs.md`.
 
 ## Choosing Edit vs Write
 
@@ -76,8 +55,6 @@ When changing how skills, rules, or hooks install or sync in this repo (for exam
 
 ## Additional Non-overlapping Rules
 
-- **task_scope:** Match every action to what was explicitly requested. When intent is ambiguous, research official docs and present options via AskUserQuestion before making any changes. Proceed with edits only on explicit instruction.
-- **confirm_implementation_forks:** When two or more viable paths would satisfy the goal and the choice changes the deliverable — its scope, completeness, deferred work, dependencies, or a hard-to-reverse contract — stop and ask which path via AskUserQuestion before implementing. A path that defers work or leaves a placeholder creating a follow-up task is itself a fork to surface, not a default to take silently. Phrase the question in plain language with only the detail needed to decide. See [`confirm-implementation-forks`](rules/confirm-implementation-forks.md).
 - **disambiguate_overloaded_terms:** When a word in the request has two different technical meanings — "conflict" (git-merge versus functional/behavioral), "sync" (fast-forward versus commit), and the like — confirm which one is meant via AskUserQuestion before analyzing or acting.
 
 ## Serena (Code Intelligence MCP)
@@ -100,31 +77,3 @@ Before any coding task, call the `initial_instructions` tool to load the Serena
 1. **Serena** — symbol-level navigation (declarations, references, implementations, rename)
 2. **es.exe** — file-system search by name/path/extension/size/date (Everything CLI)
 3. **Grep/Glob** — content and pattern matching
-
-## Everything Search (es.exe CLI)
-
-Search files by name, path, extension, size, or date with the Everything command-line tool `es.exe`. It reads the same live index the desktop app keeps, so results return instantly.
-
-### Invocation and scope tokens
-Run `es.exe` with a scoped query — a project path, an `ext:`/`dm:`/`size:` filter, or a name pattern. The `es_exe_path_rewriter` hook resolves a `{project-name}` placeholder or a bare registry key from `~/.claude/project-paths.json` into its quoted absolute path before the command runs (it allows and rewrites, never blocks).
-
-### Hard limits
-- Scope every search. A bare whole-drive scan or a network-share sweep is out of bounds.
-
-### Fallback order
-1. **es.exe** — file-system search by name/path/extension/size/date
-2. **Debug** — try to find out why es.exe isn't working, and then prompt user for next-steps if you can't self-heal.
-3. **Grep** — file-content search (Grep owns content)
-4. **Glob** — relative-path pattern matching within the current project
-
-### Search syntax quick reference
-- `ext:py` — find by extension (multiple: `ext:ts | ext:js`)
-- `path:src\components` — match against full path
-- `*.config.*` — wildcards
-- `size:>10mb` — size filter
-- `dm:today` / `dm:thisweek` — date modified filter
-- `-n 50` — limit results; `-sort dm` — sort by date modified
-- `foo bar` — AND, `foo | bar` — OR, `!foo` — NOT
-- `"exact phrase"` — literal match
-
-Full operator reference: `skills/everything-search/SKILL.md`.

package/agents/clean-coder.md

@@ -159,7 +159,7 @@ Use logging for application and runtime output. `print()` is allowed when stdout
 
 ### Comment preservation
 
-Existing comments on lines that remain otherwise unchanged stay exactly as you found them. The hook enforces both directions: the gate fires on a new inline `#` or `//` in production code, and the gate also fires when an existing comment disappears from a line you touched. New code self-documents via names; new docstrings on functions, methods, classes, and modules remain allowed.
+Existing comments on lines you leave otherwise unchanged stay exactly as you found them. The hook treats the two directions differently: the gate fires and blocks the edit on a new inline `#` or `//` in production code, while an existing comment disappearing from a line you touched prints a stderr advisory and lets the edit through. New code self-documents via names; new docstrings on functions, methods, classes, and modules stay allowed.
 
 ### Centralized configuration
 
@@ -338,7 +338,7 @@ These gates are checked by `code_rules_enforcer.py`. Satisfying each gate lets y
 | Rule | What this rule looks for |
 |------|--------------------------|
 | Self-documenting names only | New `#` or `//` in production code (shebangs, `# type:`, `# noqa`, eslint-directives, docstrings exempt) |
-| Comment preservation | Removal of existing comments on lines that remain otherwise unchanged |
+| Comment preservation | Advisory — removal of existing comments on lines you leave otherwise unchanged prints a stderr advisory and does not block |
 | Imports at top | `import` statements placed inside function bodies |
 | Logging format | `log_*(f"...")` — replace with `log_*("...", arg)` |
 | File length | Advisory at 400 lines (soft), strong nudge at 1000 — emitted to stderr; the write proceeds |

package/agents/code-verifier.md

@@ -3,7 +3,6 @@ name: code-verifier
 description: Post-hoc verification agent for the two-phase code workflow. Spawned by the main session after coder agents finish. Runs every check itself in a fresh context — named gates, tests against recorded baselines, two-way diff-vs-task reading — and ends with a fenced verdict block the verifier_verdict_minter hook turns into the commit-gate verdict. Read and execute only; it never edits files.
 tools: Read, Grep, Glob, Bash
 model: sonnet
-effort: medium
 color: orange
 ---
 

package/agents/test_agent_frontmatter.py

@@ -0,0 +1,78 @@
+"""Behavior tests for agent-definition YAML frontmatter.
+
+Every agent `.md` in this directory opens with a frontmatter block the Claude
+Code subagent loader reads. The loader accepts a fixed key set; an unrecognized
+top-level key breaks the spawn — the subagent starts with a broken definition,
+idles, and dies without a report::
+
+    ok:   name / description / tools / model / color
+    flag: effort            <- unrecognized, subagent dies delivering nothing
+
+The accepted set is the one `agents/CLAUDE.md` documents (name, description,
+tools, color) plus the `model` pin the working agents carry (clean-coder pins
+opus, pr-description-writer pins haiku). Top-level keys are read with a line
+scan so an agent whose `description` embeds informal `<example>` prose is not
+mistaken for one carrying extra keys.
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+import pytest
+import yaml
+
+ACCEPTED_FRONTMATTER_KEYS = frozenset(
+    {"name", "description", "tools", "model", "color"}
+)
+FRONTMATTER_FENCE = "---"
+FRONTMATTER_SEGMENT_COUNT = 3
+CODE_VERIFIER_AGENT_NAME = "code-verifier"
+TOP_LEVEL_KEY_PATTERN = re.compile(r"^([a-z][a-z0-9_]*):", re.MULTILINE)
+
+
+def _agent_definition_paths() -> list[Path]:
+    agents_directory = Path(__file__).parent
+    all_markdown_files = sorted(agents_directory.glob("*.md"))
+    return [
+        each_markdown_file
+        for each_markdown_file in all_markdown_files
+        if each_markdown_file.read_text(encoding="utf-8").startswith(FRONTMATTER_FENCE)
+    ]
+
+
+def _frontmatter_block(agent_definition_path: Path) -> str:
+    agent_text = agent_definition_path.read_text(encoding="utf-8")
+    fence_segments = agent_text.split(FRONTMATTER_FENCE, FRONTMATTER_SEGMENT_COUNT - 1)
+    return fence_segments[1]
+
+
+def _top_level_keys(frontmatter_block: str) -> set[str]:
+    return set(TOP_LEVEL_KEY_PATTERN.findall(frontmatter_block))
+
+
+@pytest.mark.parametrize(
+    "agent_definition_path",
+    _agent_definition_paths(),
+    ids=lambda each_path: each_path.name,
+)
+def test_agent_frontmatter_uses_only_accepted_keys(
+    agent_definition_path: Path,
+) -> None:
+    declared_keys = _top_level_keys(_frontmatter_block(agent_definition_path))
+    unaccepted_keys = declared_keys - ACCEPTED_FRONTMATTER_KEYS
+    assert not unaccepted_keys, (
+        f"{agent_definition_path.name} carries frontmatter keys the subagent "
+        f"loader does not accept: {sorted(unaccepted_keys)}"
+    )
+
+
+def test_code_verifier_frontmatter_parses_and_names_the_agent() -> None:
+    agents_directory = Path(__file__).parent
+    code_verifier_block = _frontmatter_block(
+        agents_directory / f"{CODE_VERIFIER_AGENT_NAME}.md"
+    )
+    parsed_frontmatter = yaml.safe_load(code_verifier_block)
+    assert parsed_frontmatter["name"] == CODE_VERIFIER_AGENT_NAME
+    assert set(parsed_frontmatter) <= ACCEPTED_FRONTMATTER_KEYS

package/audit-rubrics/category_rubrics/category-j-code-rules-compliance.md

@@ -24,7 +24,7 @@
 | J5 | Abbreviations | `ctx`, `cfg`, `msg`, `btn`, `idx`, `cnt`, `elem`, `val`, `tmp`, `str`, `num`, `arr`, `obj`, `fn`, `cb`, `req`, `res`. (Loop counters `i`/`j`/`k` and `e` for exceptions are exempt.) |
 | J6 | Vague names | `result`, `data`, `output`, `response`, `value`, `item`, `temp`, `info`, `stuff`, `thing`. Vague prefixes: `handle`, `process`, `manage`, `do`. |
 | J7 | Type hints | Missing type annotation on a parameter or return; presence of `Any` or `# type: ignore`. |
-| J8 | New inline comments | New `#` or `//` comments in production code added by this diff. (Existing comments are NEVER removed — Comment Preservation rule.) |
+| J8 | New inline comments | New `#` or `//` comments in production code added by this diff. (Removing an existing comment is a Comment Preservation concern the hook flags with a stderr advisory rather than a block.) |
 | J9 | Logging format | `log_*(f"...")` rather than `log_*("...", arg)`. |
 | J10 | Imports inside functions | `import` statements placed inside function bodies. |
 | J11 | sys.path.insert dedup | `sys.path.insert(0, X)` must be guarded by `if X not in sys.path:` (test files exempt). |

package/audit-rubrics/prompts/category-j-code-rules-compliance.md

@@ -69,7 +69,7 @@ A `test_*.py` name or a `.mjs` extension takes the line out of the write-time ga
 **J8. New inline comments**
 - Every `#` or `//` comment line **added** by this diff in production code — flag, except for exempt markers (shebangs, `# type:`, `# noqa`, `# pylint:`, `# pragma:`, `// @ts-`, `// eslint-`, `// prettier-`, `/// `).
 - Module/function/class docstrings are always allowed.
-- Existing comments are NEVER removed (Comment Preservation rule); if the diff removes an existing comment, that is a separate violation outside J8 (also blocked by the hook).
+- Existing comments are NEVER removed (Comment Preservation rule); if the diff removes an existing comment, that is a separate violation outside J8 (the hook emits a stderr advisory for it rather than blocking).
 - Test files are exempt.
 - Adversarial probes: (a) is there any `# type:` or marker comment that is actually inert prose rather than a real type-checker / linter directive? (b) is any docstring carrying inline-comment content (line-level explanations rather than module/function description)? (c) does any newly-added blank line between code stanzas function as a comment substitute, suggesting the author wanted to add a comment but couldn't?
 

package/bin/install.mjs

@@ -147,6 +147,7 @@ const INSTALL_GROUPS = {
     core: {
         description: 'Development standards, hooks, agents, commands',
         skills: [
+            'orchestrator', 'orchestrator-refresh',
             'anthropic-plan', 'everything-search',
             'pr-review-responder',
             'recall', 'remember', 'task-build', 'verified-build'

package/docs/CODE_RULES.md

@@ -4,9 +4,9 @@ Compact reference for agents. ⚡ marks rules enforced by `code_rules_enforcer.p
 
 ---
 
-## COMMENT PRESERVATION (ABSOLUTE RULE)
+## COMMENT PRESERVATION
 
-**NEVER remove existing comments.** Existing comments are SACRED. Only evaluate comments on lines you are actively changing. Do not add new inline comments in production code — write self-documenting code. Docstrings (module/class/function) are always allowed. Test files are exempt. The hook enforces both directions: it blocks new inline comments AND blocks deletion of existing ones.
+**Keep existing comments in place.** Only evaluate comments on lines you are actively changing. Do not add new inline comments in production code — write self-documenting code. Docstrings (module/class/function) are always allowed. Test files are exempt. The hook treats the two directions differently: adding a new inline comment blocks the edit, while removing an existing comment prints a stderr advisory and lets the edit through.
 
 ---
 

package/hooks/blocking/CLAUDE.md

@@ -24,7 +24,7 @@ The check modules it calls are the `code_rules_<concern>.py` files below.
 | `code_rules_banned_identifiers.py` | Banned short names (`ctx`, `cfg`, `msg`, etc.), banned prefixes (`handle_`, `process_`, etc.) |
 | `code_rules_boolean_mustcheck.py` | Boolean naming (`is_`/`has_`/… prefixes) and must-check return values |
 | `code_rules_command_dispatch.py` | A `hooks/blocking/` command classifier matching a multi-word command regex without a start anchor or first-word tokenization |
-| `code_rules_comments.py` | No new inline comments; no deletion of existing ones |
+| `code_rules_comments.py` | No new inline comments; advisory on deletion of existing ones |
 | `code_rules_constants_config.py` | Constants must live in `config/`; file-global constant use-count |
 | `code_rules_dead_argparse_argument.py` | Argparse arguments with no references in the same file |
 | `code_rules_dead_config_field.py` | `*Config` / `*Selectors` dataclass fields with no live references |
@@ -78,10 +78,11 @@ The check modules it calls are the `code_rules_<concern>.py` files below.
 | `hook_prose_detector_consistency.py` | PreToolUse (Write/Edit) | Hook docstrings/messages that claim a trigger the detector cannot fire on |
 | `intent_only_ending_blocker.py` | Stop | Responses that end on a plan or intent without doing the work |
 | `open_questions_in_plans_blocker.py` | PreToolUse (Write/Edit) | Plan documents with unresolved open questions |
+| `nas_ssh_binary_enforcer.py` | PreToolUse (Bash) | A bare `ssh`/`scp`/`sftp` command word targeting the NAS at `192.168.1.100` (Git Bash's MSYS ssh stalls on an interactive password prompt), or the full `System32/OpenSSH` binary to that host without `-o BatchMode=yes` |
 | `package_inventory_stale_blocker.py` | PreToolUse (Write) | A new production code file created in a directory whose `README.md`/`CLAUDE.md` inventory (or a parent skill's `SKILL.md` Layout table mapping the `scripts/` subdirectory) names two or more sibling files but no entry for the new file |
 | `plain_language_blocker.py` | PreToolUse (Write/Edit/AskUserQuestion) | Heavy or jargon words in user-facing prose |
 | `pr_converge_bugteam_enforcer.py` | PreToolUse | Enforces that bugteam runs in parallel with bugbot in pr-converge loops |
-| `pr_description_enforcer.py` | PreToolUse (Bash) | `gh pr create`/`edit`/`comment` bodies that fail the Anthropic claude-code style audit |
+| `pr_description_enforcer.py` | PreToolUse (Bash) | `gh pr create`/`edit`/`comment` bodies that fail the Anthropic claude-code style audit, proof-shaped `gh pr comment` bodies missing proof-of-work parts, and `gh pr ready` while the PR carries no passing proof comment |
 | `precommit_code_rules_gate.py` | PreToolUse (Bash) | Staged changes that fail the CODE_RULES gate at commit time |
 | `pytest_testpaths_orphan_blocker.py` | PreToolUse (Write/Edit/MultiEdit) | New `test_*.py` files created under a directory absent from a package's explicit pytest `testpaths` allowlist |
 | `question_to_user_enforcer.py` | Stop | User-directed questions not routed through `AskUserQuestion` |
@@ -111,8 +112,10 @@ The check modules it calls are the `code_rules_<concern>.py` files below.
 | `pr_description_body_audit.py` | Body audit logic for `pr_description_enforcer.py` |
 | `pr_description_command_parser.py` | `gh` command parsing for `pr_description_enforcer.py` |
 | `pr_description_pr_number.py` | PR number extraction logic |
+| `pr_description_proof_of_work.py` | Proof-of-work comment audit and `gh pr ready` gate logic for `pr_description_enforcer.py` |
 | `pr_description_readability.py` | Readability checks on PR description bodies |
 | `verification_verdict_store.py` | Reads and writes verdict files under `~/.claude/verification/` |
+| `verified_commit_config_bootstrap.py` | Binds `config.verified_commit_constants` to the sibling `config/` file by explicit location, so the gate family resolves its constants regardless of a foreign `config` package's `sys.path` order |
 
 ## Conventions
 

package/hooks/blocking/code_rules_comments.py

@@ -147,7 +147,7 @@ def check_comment_changes(old_content: str, new_content: str, file_path: str) ->
 
     Inline comments (after code on same line): BLOCK when added.
     Standalone comment lines: NUDGE (print advisory) when added.
-    Existing comments being removed: BLOCK (comment preservation principle).
+    Existing comments being removed: NUDGE (print advisory) — comment preservation is advisory.
 
     When the file is Python and either *old_content* or *new_content* cannot
     be tokenized (common for mid-edit Edit fragments), the comparison is
@@ -188,7 +188,7 @@ def check_comment_changes(old_content: str, new_content: str, file_path: str) ->
         code_was_removed = new_line_count < old_line_count - len(removed_comments)
         if not code_was_removed:
             sample = next(iter(removed_comments))
-            issues.append(f"Existing comment removed: {sample[:60]} - NEVER delete existing comments")
+            print(f"[CODE_RULES advisory] Existing comment removed: {sample[:60]} - comment preservation is advisory", file=sys.stderr)
 
     return issues
 

package/hooks/blocking/code_verifier_spawn_preflight_gate.py

@@ -43,9 +43,11 @@ from verification_verdict_store import (  # noqa: E402
 )
 
 from hooks_constants.code_verifier_spawn_preflight_gate_constants import (  # noqa: E402
+    ALL_MERGE_HEAD_PROBE_FLAGS,
     ALL_MERGE_TREE_COMMAND_FLAGS,
     ALL_NAME_ONLY_WORKTREE_DIFF_FLAGS,
     ALL_UNIFIED_ZERO_DIFF_FLAGS,
+    ALL_UNMERGED_PATHS_DIFF_FLAGS,
     CODE_RULES_SECTION_HEADER,
     CODE_VERIFIER_SUBAGENT_TYPE,
     DENY_REASON_LEAD,
@@ -145,9 +147,49 @@ def _run_trial_merge(repo_root: str, base_ref: str) -> tuple[int, str] | None:
     return completed_process.returncode, completed_process.stdout
 
 
+def _merge_in_progress(repo_root: str) -> bool:
+    """Decide whether an unfinished merge is recorded in the work tree.
+
+    Args:
+        repo_root: The repository top-level directory.
+
+    Returns:
+        True when ``MERGE_HEAD`` resolves — a merge is started but not yet
+        committed; False when no merge is in progress or git fails.
+    """
+    return run_git(repo_root, *ALL_MERGE_HEAD_PROBE_FLAGS) is not None
+
+
+def _staged_merge_conflicts(repo_root: str) -> list[str] | None:
+    """Return the unmerged paths of an in-progress merge from the index.
+
+    A merge whose conflicts are fully resolved and staged leaves zero unmerged
+    index entries, so the resolved state is committable and this returns an
+    empty list. A merge with conflicts still open returns those paths, so the
+    caller keeps denying until the resolution is staged.
+
+    Args:
+        repo_root: The repository top-level directory.
+
+    Returns:
+        The still-unmerged paths (empty when the resolution is fully staged),
+        or None when git fails — the caller fails OPEN on None.
+    """
+    unmerged_text = run_git(repo_root, *ALL_UNMERGED_PATHS_DIFF_FLAGS)
+    if unmerged_text is None:
+        return None
+    return [each_line for each_line in unmerged_text.splitlines() if each_line]
+
+
 def _conflicting_files(repo_root: str, base_ref: str) -> list[str] | None:
     """Return the files that conflict when HEAD trial-merges against the base.
 
+    While a merge is in progress the branch tip has not yet recorded the
+    resolution, so the trial-merge of the base against HEAD would re-report
+    conflicts the staged index already fixed. In that state the index is the
+    authority: an empty unmerged set is a committable resolution, and any
+    remaining unmerged path is a live conflict.
+
     Args:
         repo_root: The repository top-level directory.
         base_ref: The base ref to trial-merge HEAD against.
@@ -158,6 +200,8 @@ def _conflicting_files(repo_root: str, base_ref: str) -> list[str] | None:
         timeout, or an exit code that is neither clean nor conflict) — the
         caller fails OPEN on None.
     """
+    if _merge_in_progress(repo_root):
+        return _staged_merge_conflicts(repo_root)
     merge_outcome = _run_trial_merge(repo_root, base_ref)
     if merge_outcome is None:
         return None

package/hooks/blocking/config/verified_commit_constants.py

@@ -86,6 +86,8 @@ TEST_FILE_SUFFIX = "_test.py"
 CONFTEST_FILE_NAME = "conftest.py"
 MINIMUM_STATUS_FIELD_COUNT = 2
 ALL_FALLBACK_BASE_REFERENCES = ("origin/main", "origin/master")
+DETACHED_HEAD_LABEL = "HEAD"
+BRANCH_REMOTE_CONFIG_KEY_TEMPLATE = "branch.{branch_name}.remote"
 ALL_TOOLING_STATE_PREFIXES = (
     ".claude/verification/",
     ".claude/worktrees/",

package/hooks/blocking/conftest.py

@@ -0,0 +1,115 @@
+"""Pytest fixture that reproduces foreign-``config`` shadowing for the gate family.
+
+The verified-commit gate hooks import shared constants as
+``from config.verified_commit_constants import ...``. This fixture mirrors the
+installed layout that breaks that import -- a real ``hooks/blocking`` package
+beside a decoy ``hooks/config`` regular package -- and runs a caller-supplied
+driver as a subprocess whose ``sys.path`` places the decoy ahead of
+``blocking``, the ordering under which the wrong ``config`` wins resolution.
+"""
+
+import shutil
+import subprocess
+import sys
+import textwrap
+from collections.abc import Callable
+from pathlib import Path
+
+import pytest
+
+_BLOCKING_SOURCE_DIRECTORY = Path(__file__).resolve().parent
+_HOOKS_CONSTANTS_SOURCE_DIRECTORY = _BLOCKING_SOURCE_DIRECTORY.parent / "hooks_constants"
+_SUBPROCESS_TIMEOUT_SECONDS = 60
+_MIRRORED_BLOCKING_FILE_NAMES = (
+    "verified_commit_gate.py",
+    "verification_verdict_store.py",
+    "verifier_verdict_minter.py",
+    "verdict_directory_write_blocker.py",
+    "verified_commit_config_bootstrap.py",
+)
+_DECOY_CONFIG_INIT_SOURCE = '"""Foreign config package that must never win resolution."""\n'
+_DECOY_CONFIG_CONSTANTS_SOURCE = (
+    '"""Stale stand-in carrying none of the real gate constants."""\n\nIS_DECOY_CONFIG = True\n'
+)
+
+
+def _build_shadowed_hook_tree(tmp_path: Path) -> tuple[Path, Path]:
+    """Mirror the hook tree with a decoy ``config`` package beside ``blocking``.
+
+    Args:
+        tmp_path: The directory the mirrored tree is built under.
+
+    Returns:
+        The mirrored ``hooks`` directory and its ``blocking`` subdirectory.
+    """
+    mirrored_hooks_directory = tmp_path / "hooks"
+    mirrored_blocking_directory = mirrored_hooks_directory / "blocking"
+    mirrored_blocking_directory.mkdir(parents=True)
+
+    for each_file_name in _MIRRORED_BLOCKING_FILE_NAMES:
+        source_file = _BLOCKING_SOURCE_DIRECTORY / each_file_name
+        if source_file.exists():
+            shutil.copy2(source_file, mirrored_blocking_directory / each_file_name)
+
+    shutil.copytree(
+        _BLOCKING_SOURCE_DIRECTORY / "config",
+        mirrored_blocking_directory / "config",
+    )
+    shutil.copytree(
+        _HOOKS_CONSTANTS_SOURCE_DIRECTORY,
+        mirrored_hooks_directory / "hooks_constants",
+    )
+
+    decoy_config_directory = mirrored_hooks_directory / "config"
+    decoy_config_directory.mkdir()
+    (decoy_config_directory / "__init__.py").write_text(_DECOY_CONFIG_INIT_SOURCE, encoding="utf-8")
+    (decoy_config_directory / "verified_commit_constants.py").write_text(
+        _DECOY_CONFIG_CONSTANTS_SOURCE, encoding="utf-8"
+    )
+    return mirrored_hooks_directory, mirrored_blocking_directory
+
+
+@pytest.fixture
+def run_under_config_shadow(
+    tmp_path: Path,
+) -> Callable[[str], subprocess.CompletedProcess[str]]:
+    """Return a runner that executes a driver under a foreign-``config`` sys.path.
+
+    ::
+
+        completed = run_under_config_shadow("import verified_commit_gate")
+        ok:   completed.returncode == 0 once the bootstrap seeds the real module
+        flag: nonzero with ModuleNotFoundError while the decoy config wins
+
+    The runner prefixes the driver with a ``sys.path`` preamble that puts the
+    mirrored ``hooks`` directory (holding the decoy ``config``) ahead of
+    ``blocking``, then runs the probe with the active interpreter.
+
+    Args:
+        tmp_path: Pytest's per-test temporary directory, fixture-injected.
+
+    Returns:
+        A function taking driver source text and returning the finished
+        subprocess result.
+    """
+    mirrored_hooks_directory, mirrored_blocking_directory = _build_shadowed_hook_tree(tmp_path)
+
+    def run_driver(driver_body: str) -> subprocess.CompletedProcess[str]:
+        probe_script = tmp_path / "probe.py"
+        sys_path_preamble = textwrap.dedent(
+            f"""\
+            import sys
+            sys.path.insert(0, {str(mirrored_blocking_directory)!r})
+            sys.path.insert(0, {str(mirrored_hooks_directory)!r})
+            """
+        )
+        probe_script.write_text(sys_path_preamble + textwrap.dedent(driver_body), encoding="utf-8")
+        return subprocess.run(
+            [sys.executable, str(probe_script)],
+            check=False,
+            capture_output=True,
+            text=True,
+            timeout=_SUBPROCESS_TIMEOUT_SECONDS,
+        )
+
+    return run_driver