claude-dev-env 2.0.2 → 2.2.0

package/CLAUDE.md

@@ -43,7 +43,7 @@ Run every multi-step code task in two phases:
 1. **Coders** — one coder agent per scoped assignment writes the code. A coder that hits a decision it can't reasonably solve consults the advisor (see beginning of this file).
 2. **Verification** — when the coders finish, the main session spawns the `code-verifier` agent in a fresh context, but you must first verify that their work is based on upstream's origin main (aka: the commit live on github). It derives and runs the checks itself rather than trusting coder reports: the task's named gates, tests against baselines recorded before the coders ran, and a two-way diff-vs-assignment reading (every task item maps to a hunk, every hunk maps to a task item, nothing missing). A finding must cite a failing command or a named task item. Before it emits the verdict, it puts the draft through one strongest-tier validation subagent — selected per the advisor protocol's host detection and tier ladder — that tries to refute it, and it re-checks and corrects any part the validator overturns. Source: the fresh-context review step in Claude Code best practices (https://code.claude.com/docs/en/best-practices) — the agent doing the work isn't the one grading it.
 
-Repair agents run only on reported findings; the verifier re-checks after each repair. Work lands (commit, push, draft PR) only on a clean verdict — enforced by the `verified_commit_gate` hook, which blocks `git commit`/`git push` unless a hook-minted verdict covers the current branch diff. The one exemption is mechanical, not discretionary: a diff whose every changed file is non-code or has an unchanged Python AST once docstrings are stripped (docs, docstrings, comments).
+Repair agents run only on reported findings; the verifier re-checks after each repair. Work lands (commit, push, draft PR) only on a clean verdict — enforced by the `verified_commit_gate` hook, which blocks `git commit`/`git push` unless a hook-minted verdict covers the current branch diff. One exemption is mechanical, not discretionary: a diff whose every changed file is non-code or has an unchanged Python AST once docstrings are stripped (docs, docstrings, comments). One escape hatch is manual and narrow: appending `# verify-skip` as a trailing shell comment (outside every quoted region) to the blocked commit or push command bypasses the gate for that one command — allowed only when the branch surface is the same code a code-verifier already passed clean and the gate is blocking on a verdict that doesn't cover it (an unminted verdict, staging churn, a reverted concurrent write); any real code change since the clean verdict runs a fresh verification instead. Full rule: `~/.claude/rules/verified-commit-gate-skip.md`.
 
 ## Sub-agent Output Validation
 

package/hooks/blocking/CLAUDE.md

@@ -8,6 +8,7 @@ PreToolUse hooks that deny (block) tool calls when a rule is violated. The main
 |---|---|
 | `config/` | Shared constants for the verified-commit gate family (`verified_commit_constants.py`) |
 | `tdd_enforcer_parts/` | Concern modules the `tdd_enforcer.py` entry hook wires together: path classification, content analysis, candidate-path resolution, freshness, git-tracking restore detection, decisions, and constants |
+| `verified_commit_gate_parts/` | Concern modules the `verified_commit_gate.py` entry hook wires together: command tokenization, directory-change resolution, gated git-invocation resolution, deny-reason resolution, and deny-payload assembly |
 | `claude_md_orphan_file_blocker_parts/` | Concern modules the `claude_md_orphan_file_blocker.py` entry hook wires together: reference extraction, subtree scan, scan plan, decision, and constants |
 | `package_inventory_stale_blocker_parts/` | Concern modules the `package_inventory_stale_blocker.py` entry hook wires together: inventory detection, decision, and constants |
 | `inventory_intent_records/` | The shared per-session pending-intent store both inventory blockers read to break the file/row add-order deadlock |

package/hooks/blocking/code_rules_shared.py

@@ -31,11 +31,11 @@ from hooks_constants.code_rules_enforcer_constants import (  # noqa: E402
     STRICT_TEST_FILE_BASENAME_PATTERN,
 )
 from hooks_constants.harness_scratchpad_constants import (  # noqa: E402
+    CLAUDE_SESSION_ID_ENVIRONMENT_VARIABLE_NAME,
     HARNESS_SCRATCHPAD_LEAF_DIRECTORY_NAME,
-    HARNESS_SCRATCHPAD_PATH_SEPARATOR_REPLACEMENT,
+    HARNESS_SCRATCHPAD_USER_DIRECTORY_NAME,
     HARNESS_SCRATCHPAD_USER_DIRECTORY_PREFIX,
     HOOK_PAYLOAD_SESSION_ID_KEY,
-    HOOK_PAYLOAD_WORKING_DIRECTORY_KEY,
 )
 from hooks_constants.unused_module_import_constants import (  # noqa: E402
     TYPE_CHECKING_IDENTIFIER,
@@ -275,78 +275,157 @@ def is_ephemeral_script_path(file_path: str) -> bool:
     return False
 
 
-def _resolve_session_scratchpad_root(hook_payload: dict) -> str | None:
-    """Rebuild the harness session scratchpad directory from a PreToolUse payload.
+def _session_id_for_scratchpad(hook_payload: dict) -> str:
+    """Return the session id from the payload, or the harness environment value.
+
+    Args:
+        hook_payload: The PreToolUse payload that may carry ``session_id``.
+
+    Returns:
+        The payload session id when present, otherwise the
+        ``CLAUDE_CODE_SESSION_ID`` environment value, or an empty string when
+        neither source carries one.
+    """
+    payload_session_id = hook_payload.get(HOOK_PAYLOAD_SESSION_ID_KEY, "")
+    if isinstance(payload_session_id, str) and payload_session_id:
+        return payload_session_id
+    return os.environ.get(CLAUDE_SESSION_ID_ENVIRONMENT_VARIABLE_NAME, "")
 
-    ::
 
-        payload.cwd = /home/user/project    payload.session_id = 5f2c...
-                          |                            |
-        <tempdir>/claude-<uid>/-home-user-project/5f2c.../scratchpad
-                     |               |
-                  os.getuid()   cwd with each "/" turned to "-"
+def _is_harness_user_directory(directory_name: str) -> bool:
+    """Return whether a path component is the harness user directory.
 
-    No environment variable carries this path, so it is rebuilt from the three
-    signals a hook can read: the POSIX user id and the ``cwd`` and ``session_id``
-    fields the harness puts in every PreToolUse payload. The rebuilt directory
-    is returned only when it exists on disk, so a wrong guess or a non-POSIX
-    platform yields None and the gates keep full enforcement.
+    The harness names this directory ``claude`` on Windows and ``claude-<uid>``
+    on POSIX, so both the exact name and the prefixed form count.
 
     Args:
-        hook_payload: The PreToolUse payload carrying ``cwd`` and ``session_id``.
+        directory_name: A single path component below the temp-directory root.
 
     Returns:
-        The scratchpad directory path when it exists on disk, else None.
+        True when the component is the harness user directory.
     """
-    get_user_id = getattr(os, "getuid", None)
-    if get_user_id is None:
-        return None
-    session_id = hook_payload.get(HOOK_PAYLOAD_SESSION_ID_KEY, "")
-    working_directory = hook_payload.get(HOOK_PAYLOAD_WORKING_DIRECTORY_KEY, "")
-    if not isinstance(session_id, str) or not session_id:
-        return None
-    if not isinstance(working_directory, str) or not working_directory:
-        return None
-    mangled_working_directory = working_directory.replace("\\", "/").replace(
-        "/", HARNESS_SCRATCHPAD_PATH_SEPARATOR_REPLACEMENT
-    )
-    user_directory_name = f"{HARNESS_SCRATCHPAD_USER_DIRECTORY_PREFIX}{get_user_id()}"
-    scratchpad_root = os.path.join(
-        tempfile.gettempdir(),
-        user_directory_name,
-        mangled_working_directory,
-        session_id,
-        HARNESS_SCRATCHPAD_LEAF_DIRECTORY_NAME,
+    return (
+        directory_name == HARNESS_SCRATCHPAD_USER_DIRECTORY_NAME
+        or directory_name.startswith(HARNESS_SCRATCHPAD_USER_DIRECTORY_PREFIX)
     )
-    if not os.path.isdir(scratchpad_root):
+
+
+def _relative_parts_under_temp_root(
+    real_target: str, real_temp_root: str
+) -> tuple[str, ...]:
+    """Return real_target's path components below real_temp_root, or empty when outside.
+
+    Args:
+        real_target: The resolved candidate path.
+        real_temp_root: The resolved temp-directory root.
+
+    Returns:
+        The path components between the temp root and the target, or an empty
+        tuple when the target sits outside the temp directory or on another
+        drive.
+    """
+    try:
+        relative_path = os.path.relpath(real_target, real_temp_root)
+    except ValueError:
+        return ()
+    all_relative_parts = Path(relative_path).parts
+    if all_relative_parts and all_relative_parts[0] == os.path.pardir:
+        return ()
+    return all_relative_parts
+
+
+def _existing_scratchpad_root(
+    all_relative_parts: tuple[str, ...], real_temp_root: str, session_id: str
+) -> str | None:
+    """Return the on-disk scratchpad root matching the harness shape, or None.
+
+    ::
+
+        <temp-root>/<user-dir>/<mangled-cwd>/<session-id>/scratchpad/<file>
+                        |                          |           |
+                  claude user dir            session id     leaf name
+
+    Args:
+        all_relative_parts: The target's path components below the temp root.
+        real_temp_root: The resolved temp-directory root.
+        session_id: The session id the scratchpad's parent segment must equal.
+
+    Returns:
+        The scratchpad directory path when the shape matches and that directory
+        exists on disk, otherwise None.
+    """
+    if not all_relative_parts or not _is_harness_user_directory(all_relative_parts[0]):
         return None
-    return scratchpad_root
+    for each_session_index in range(2, len(all_relative_parts) - 1):
+        leaf_index = each_session_index + 1
+        if all_relative_parts[each_session_index] != session_id:
+            continue
+        if all_relative_parts[leaf_index] != HARNESS_SCRATCHPAD_LEAF_DIRECTORY_NAME:
+            continue
+        scratchpad_root = os.path.join(
+            real_temp_root, *all_relative_parts[: leaf_index + 1]
+        )
+        if os.path.isdir(scratchpad_root):
+            return scratchpad_root
+    return None
 
 
 def is_under_session_scratchpad(file_path: str, hook_payload: dict) -> bool:
     """Return True when file_path resolves under the harness session scratchpad.
 
     One-off scripts written to the session scratchpad are throwaway tooling
-    outside every repo, so the TDD and CODE_RULES gates skip them. Both
-    file_path and the rebuilt scratchpad root are resolved through the real
-    filesystem (symlinks followed) before the containment test, so a symlink
-    into the scratchpad exempts and a symlink out of it does not.
+    outside every repo, so the TDD and CODE_RULES gates skip them.
+
+    The match keys on the session id — from the payload, or the
+    ``CLAUDE_CODE_SESSION_ID`` environment variable — and on the temp-directory
+    path shape ``<user-dir>/<mangled-cwd>/<session-id>/scratchpad``, so it holds
+    on Windows and POSIX alike. file_path resolves through the real filesystem
+    (symlinks followed) before the shape test, and the scratchpad directory must
+    exist on disk, so a crafted path that never existed keeps full enforcement.
 
     Args:
         file_path: The path the write targets.
-        hook_payload: The PreToolUse payload carrying ``cwd`` and ``session_id``.
+        hook_payload: The PreToolUse payload carrying the session id.
 
     Returns:
         True when file_path's real path sits at or under the session scratchpad.
     """
     if not file_path:
         return False
-    scratchpad_root = _resolve_session_scratchpad_root(hook_payload)
-    if scratchpad_root is None:
+    session_id = _session_id_for_scratchpad(hook_payload)
+    if not session_id:
         return False
     real_target = os.path.realpath(file_path)
-    real_root = os.path.realpath(scratchpad_root)
-    return real_target == real_root or real_target.startswith(real_root + os.sep)
+    real_temp_root = os.path.realpath(tempfile.gettempdir())
+    all_relative_parts = _relative_parts_under_temp_root(real_target, real_temp_root)
+    return (
+        _existing_scratchpad_root(all_relative_parts, real_temp_root, session_id)
+        is not None
+    )
+
+
+def is_ephemeral_path(file_path: str, hook_payload: dict | None = None) -> bool:
+    """Return True when file_path is a throwaway scratch path exempt from repo gates.
+
+    Combines the two throwaway-path families a repo gate skips: the root-anchored
+    ephemeral scratch directories (``/tmp`` and ``$CLAUDE_JOB_DIR/tmp``) and the
+    harness session scratchpad. The session scratchpad match reads the session id
+    from the payload when one is supplied, and from the harness environment
+    variable otherwise, so a caller that holds no payload still gets the match.
+    One call answers path exemption for both families, so a gate that skips
+    throwaway paths need not repeat the two checks itself.
+
+    Args:
+        file_path: The candidate path to classify.
+        hook_payload: The PreToolUse payload carrying the session id, or None to
+            read the session id from the environment alone.
+
+    Returns:
+        True when the path is ephemeral scratch or under the session scratchpad.
+    """
+    if is_ephemeral_script_path(file_path):
+        return True
+    return is_under_session_scratchpad(file_path, hook_payload or {})
 
 
 def is_migration_file(file_path: str) -> bool:

package/hooks/blocking/config/CLAUDE.md

@@ -12,6 +12,8 @@ A Python package that holds shared constants for the verified-commit gate family
 |---|---|
 | `__init__.py` | Declares this as a regular package (not a namespace package) so it resolves first on `sys.path` |
 | `verified_commit_constants.py` | All tunables for the gate: directory names, regex patterns for detecting verdict paths and obfuscation attempts, timeout values, git subcommand sets, bypass marker, and corrective messages |
+| `verified_commit_context_constants.py` | `VERIFY_SKIP_ADDITIONAL_CONTEXT`, the ``# verify-skip`` usage rule the gate attaches to a deny payload's `additionalContext` |
+| `verified_commit_gate_output_constants.py` | `PRE_TOOL_USE_HOOK_EVENT_NAME` and `DENY_PERMISSION_DECISION` (the deny payload's event name and decision string), `GATE_HOOK_MODULE_NAME` (the gate's own module name for block logging), and `REGEX_ALTERNATION_SEPARATOR` (the `\|` join for the directory-change verb alternation in `gated_invocations.py`) |
 
 ## Key constants in `verified_commit_constants.py`
 

package/hooks/blocking/config/verified_commit_context_constants.py

@@ -0,0 +1,21 @@
+"""The additionalContext text the verified-commit gate attaches to a deny.
+
+The gate injects this next to the blocked tool result so the agent learns,
+at the moment of the block, when the '# verify-skip' marker is legitimate
+and when a fresh verification is required instead.
+"""
+
+VERIFY_SKIP_ADDITIONAL_CONTEXT = (
+    "The verified-commit gate honors a one-command escape hatch: appending the "
+    "marker '# verify-skip' as a trailing shell comment (outside every quoted "
+    "region) to the blocked command bypasses the gate for that command only. "
+    "It is allowed only when the branch surface is the "
+    "same code a code-verifier already passed clean and the gate is "
+    "blocking on a verdict that does not cover it (an unminted verdict, "
+    "staging churn, or a reverted concurrent write) — confirm the verified "
+    "suite still passes and the diff holds nothing beyond the clean verdict "
+    "before using it. Any real code change since that clean verdict, a "
+    "first verification, or unrepaired findings all require a fresh "
+    "verification by the code-verifier agent instead. Full rule: "
+    "~/.claude/rules/verified-commit-gate-skip.md."
+)

package/hooks/blocking/config/verified_commit_gate_output_constants.py

@@ -0,0 +1,14 @@
+"""Output-shape constants for the verified-commit gate's deny payload.
+
+Shared by ``verified_commit_gate.py`` and its ``verified_commit_gate_parts``
+package so the PreToolUse event name, the deny decision string, the hook's
+own module name for block logging, and the regex-alternation join separator
+live in one place.
+"""
+
+from __future__ import annotations
+
+PRE_TOOL_USE_HOOK_EVENT_NAME = "PreToolUse"
+DENY_PERMISSION_DECISION = "deny"
+GATE_HOOK_MODULE_NAME = "verified_commit_gate.py"
+REGEX_ALTERNATION_SEPARATOR = "|"

package/hooks/blocking/conftest.py

@@ -33,6 +33,27 @@ _DECOY_CONFIG_CONSTANTS_SOURCE = (
 )
 
 
+def _copy_mirrored_packages(mirrored_hooks_directory: Path, mirrored_blocking_directory: Path) -> None:
+    """Copy the ``config``, gate-parts, and ``hooks_constants`` packages into the mirror."""
+    shutil.copytree(_BLOCKING_SOURCE_DIRECTORY / "config", mirrored_blocking_directory / "config")
+    shutil.copytree(
+        _BLOCKING_SOURCE_DIRECTORY / "verified_commit_gate_parts",
+        mirrored_blocking_directory / "verified_commit_gate_parts",
+        ignore=shutil.ignore_patterns("tests", "__pycache__"),
+    )
+    shutil.copytree(_HOOKS_CONSTANTS_SOURCE_DIRECTORY, mirrored_hooks_directory / "hooks_constants")
+
+
+def _write_decoy_config_package(mirrored_hooks_directory: Path) -> None:
+    """Write the decoy ``config`` package that must never win resolution."""
+    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"
+    )
+
+
 def _build_shadowed_hook_tree(tmp_path: Path) -> tuple[Path, Path]:
     """Mirror the hook tree with a decoy ``config`` package beside ``blocking``.
 
@@ -51,22 +72,20 @@ def _build_shadowed_hook_tree(tmp_path: Path) -> tuple[Path, Path]:
         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",
-    )
+    _copy_mirrored_packages(mirrored_hooks_directory, mirrored_blocking_directory)
+    _write_decoy_config_package(mirrored_hooks_directory)
+    return mirrored_hooks_directory, mirrored_blocking_directory
 
-    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"
+
+def _probe_command(mirrored_hooks_directory: Path, mirrored_blocking_directory: Path) -> str:
+    """Build the ``sys.path`` preamble that shadows ``blocking`` with the decoy config."""
+    return textwrap.dedent(
+        f"""\
+        import sys
+        sys.path.insert(0, {str(mirrored_blocking_directory)!r})
+        sys.path.insert(0, {str(mirrored_hooks_directory)!r})
+        """
     )
-    return mirrored_hooks_directory, mirrored_blocking_directory
 
 
 @pytest.fixture
@@ -75,15 +94,8 @@ def run_under_config_shadow(
 ) -> 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.
+    ``run_under_config_shadow("import verified_commit_gate")`` returns 0 once
+    the bootstrap seeds the real module, nonzero while the decoy config wins.
 
     Args:
         tmp_path: Pytest's per-test temporary directory, fixture-injected.
@@ -93,16 +105,10 @@ def run_under_config_shadow(
         subprocess result.
     """
     mirrored_hooks_directory, mirrored_blocking_directory = _build_shadowed_hook_tree(tmp_path)
+    sys_path_preamble = _probe_command(mirrored_hooks_directory, mirrored_blocking_directory)
 
     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)],

package/hooks/blocking/convergence_gate_blocker.py

@@ -18,9 +18,81 @@ _hooks_dir = str(Path(__file__).resolve().parent.parent)
 if _hooks_dir not in sys.path:
     sys.path.insert(0, _hooks_dir)
 
+from hooks_constants.convergence_gate_blocker_constants import (  # noqa: E402
+    COMMAND_SEPARATOR_PATTERN,
+    GH_PR_READY_ANCHOR_PATTERN,
+    PR_URL_OWNER_REPO_NUMBER_PATTERN,
+    REPO_OVERRIDE_FLAG_PATTERN,
+)
 from hooks_constants.hook_block_logger import log_hook_block  # noqa: E402
 
 
+def _ready_command_segment(command: str) -> str:
+    """Return the ``gh pr ready`` invocation, clipped at the next command separator.
+
+    ::
+
+        gh pr ready 161 && gh pr comment 999 --repo other-owner/other-repo
+        ^^^^^^^^^^^^^^^^                            clipped -> returned segment
+
+    Scanning only this segment keeps a ``--repo`` flag or PR URL that belongs to
+    a chained command from binding the gate to the wrong PR.
+    """
+    ready_match = re.search(GH_PR_READY_ANCHOR_PATTERN, command)
+    if ready_match is None:
+        return command
+    ready_tail = command[ready_match.start() :]
+    separator_match = re.search(COMMAND_SEPARATOR_PATTERN, ready_tail)
+    if separator_match is None:
+        return ready_tail
+    return ready_tail[: separator_match.start()]
+
+
+def _parse_pr_url(command: str) -> tuple[str, str, int] | None:
+    """Return (owner, repo, pr_number) from a full PR URL in the command."""
+    url_match = re.search(PR_URL_OWNER_REPO_NUMBER_PATTERN, command)
+    if url_match is None:
+        return None
+    return url_match.group("owner"), url_match.group("repo"), int(url_match.group("number"))
+
+
+def _parse_repo_flag(command: str) -> tuple[str, str] | None:
+    """Return (owner, repo) from a --repo/-R flag in the command."""
+    flag_match = re.search(REPO_OVERRIDE_FLAG_PATTERN, command)
+    if flag_match is None:
+        return None
+    return flag_match.group("owner"), flag_match.group("repo")
+
+
+def _resolve_target_identity(command: str, cwd: str | None) -> tuple[str, str, int] | None:
+    """Resolve the (owner, repo, pr_number) the gate keys its evidence to.
+
+    A full PR URL in the command yields all three. A --repo/-R flag yields
+    the repository while the PR number resolves from the command number or
+    the cwd. With neither present, both the repository and the number
+    resolve from the cwd.
+    """
+    ready_segment = _ready_command_segment(command)
+    pr_url_identity = _parse_pr_url(ready_segment)
+    if pr_url_identity is not None:
+        return pr_url_identity
+
+    pr_number = _resolve_pr_number(ready_segment, cwd)
+    if pr_number is None:
+        return None
+
+    repo_flag_identity = _parse_repo_flag(ready_segment)
+    if repo_flag_identity is not None:
+        flag_owner, flag_repo = repo_flag_identity
+        return flag_owner, flag_repo, pr_number
+
+    cwd_identity = _resolve_owner_repo(cwd)
+    if cwd_identity is None:
+        return None
+    cwd_owner, cwd_repo = cwd_identity
+    return cwd_owner, cwd_repo, pr_number
+
+
 def _resolve_pr_number(command: str, cwd: str | None) -> int | None:
     direct_match = re.search(r"\bgh\s+pr\s+ready\s+(\d+)", command)
     if direct_match:
@@ -107,19 +179,15 @@ def main() -> None:
         sys.exit(0)
 
     command = hook_input.get("tool_input", {}).get("command", "")
-    gh_pr_ready_pattern = re.compile(r"\bgh\s+pr\s+ready\b(?![^&|;\n]*--undo)")
+    gh_pr_ready_pattern = re.compile(GH_PR_READY_ANCHOR_PATTERN)
     if not gh_pr_ready_pattern.search(command):
         sys.exit(0)
 
     cwd = hook_input.get("cwd")
-    pr_number = _resolve_pr_number(command, cwd)
-    if pr_number is None:
-        sys.exit(0)
-
-    owner_repo = _resolve_owner_repo(cwd)
-    if owner_repo is None:
+    target_identity = _resolve_target_identity(command, cwd)
+    if target_identity is None:
         sys.exit(0)
-    owner, repo = owner_repo
+    owner, repo, pr_number = target_identity
 
     completed_process = _run_convergence_check(
         check_convergence_script, owner, repo, pr_number, cwd

package/hooks/blocking/plain_language_blocker.py

@@ -19,6 +19,7 @@ _hooks_dir = str(Path(__file__).resolve().parent.parent)
 if _hooks_dir not in sys.path:
     sys.path.insert(0, _hooks_dir)
 
+from blocking.code_rules_shared import is_ephemeral_path  # noqa: E402
 from hooks_constants.hook_block_logger import log_hook_block  # noqa: E402
 from hooks_constants.plain_language_blocker_constants import (  # noqa: E402
     ALL_SOFTWARE_TERMS,
@@ -324,6 +325,13 @@ def evaluate(payload_by_key: dict[str, object]) -> str | None:
     if not isinstance(raw_tool_name, str) or not isinstance(raw_tool_input, dict):
         return None
 
+    if raw_tool_name in ALL_WRITE_EDIT_TOOL_NAMES:
+        target_file_path = raw_tool_input.get("file_path", "")
+        if isinstance(target_file_path, str) and is_ephemeral_path(
+            target_file_path, payload_by_key
+        ):
+            return None
+
     prose_text = _collect_prose_for_tool(raw_tool_name, raw_tool_input)
     if not prose_text:
         return None

package/hooks/blocking/state_description_blocker.py

@@ -19,8 +19,9 @@ _hooks_dir = str(Path(__file__).resolve().parent.parent)
 if _hooks_dir not in sys.path:
     sys.path.insert(0, _hooks_dir)
 
-from hooks_constants.pre_tool_use_stdin import read_hook_input_dictionary_from_stdin  # noqa: E402
+from blocking.code_rules_shared import is_ephemeral_path  # noqa: E402
 from hooks_constants.hook_block_logger import log_hook_block  # noqa: E402
+from hooks_constants.pre_tool_use_stdin import read_hook_input_dictionary_from_stdin  # noqa: E402
 from hooks_constants.state_description_blocker_constants import (  # noqa: E402
     ALL_BLOCK_COMMENT_EXTENSIONS,
     ALL_BLOCK_COMMENT_ONLY_EXTENSIONS,
@@ -297,6 +298,8 @@ def evaluate(payload_by_key: dict[str, object]) -> str | None:
     file_path = tool_input.get("file_path", "")
     if not isinstance(file_path, str) or not file_path:
         return None
+    if is_ephemeral_path(file_path, payload_by_key):
+        return None
     if not (is_markdown_file(file_path) or is_comment_bearing_file(file_path)):
         return None