claude-dev-env 1.89.0 → 1.92.0

package/hooks/blocking/volatile_path_in_post_blocker.py

@@ -0,0 +1,351 @@
+#!/usr/bin/env python3
+"""PreToolUse hook: block durable GitHub posts that reference volatile paths.
+
+Root cause: a background job posted a PR comment citing an artifact under a job
+scratch directory. Job tmp dirs, worktrees, and system temp locations are
+ephemeral — they are cleaned soon after the run — while a posted comment, PR
+body, issue, or review lives forever. A durable post that points at ephemeral
+scratch breaks the moment that scratch is removed.
+
+Detection strategy: gather the post body text from the tool call, then scan it
+for volatile-path markers. Two tool families carry post bodies: shell ``gh``
+post subcommands (``pr create/comment/edit/review``, ``issue
+create/comment/edit``) and the GitHub MCP post tools (any
+``mcp__plugin_github_github__*`` tool that carries a ``body`` or ``comment``
+parameter). For a ``gh`` command the body comes from ``--body``/``-b`` inline
+strings and from the file named by ``--body-file``/``-F`` (its contents are read
+and scanned, since that content is what gets embedded in the post). The ``gh``
+command is tokenized with ``shlex.split`` and the ``gh`` word must be the first
+command token, so a ``gh pr comment`` that only appears as quoted data inside
+another argument never classifies.
+"""
+
+import json
+import shlex
+import sys
+from pathlib import Path
+
+_hooks_dir = str(Path(__file__).resolve().parent.parent)
+if _hooks_dir not in sys.path:
+    sys.path.insert(0, _hooks_dir)
+
+from blocking._gh_body_arg_utils import (  # noqa: E402
+    all_body_flags,
+    body_file_flag,
+    body_file_short_flag,
+    count_extra_tokens_to_skip_for_split_quoted_value,
+    get_logical_first_line,
+    is_unresolvable_shell_value,
+    match_body_file_equals_prefix,
+    match_body_flag_equals_prefix,
+    strip_surrounding_quotes,
+)
+from hooks_constants.hook_block_logger import log_hook_block  # noqa: E402
+from hooks_constants.volatile_path_in_post_blocker_constants import (  # noqa: E402
+    ALL_GH_POST_SUBCOMMANDS,
+    ALL_MCP_BODY_PARAM_NAMES,
+    ALL_VOLATILE_PATH_MARKERS,
+    BASH_TOOL_NAME,
+    BODY_FILE_ENCODING,
+    CORRECTIVE_MESSAGE,
+    GH_COMMAND_NAME,
+    MCP_GITHUB_TOOL_PREFIX,
+    MINIMUM_POST_SUBCOMMAND_TOKEN_COUNT,
+    TOKEN_JOIN_SEPARATOR,
+)
+
+
+def scan_text_for_volatile_marker(text: str) -> str | None:
+    """Return the first volatile-path marker found in text, or None.
+
+    Backslashes normalize to forward slashes and the text lowercases before the
+    scan, so a marker matches regardless of slash direction or letter case::
+
+        ok:   "See the log table pasted below."        -> None
+        flag: r"C:\\Users\\me\\.claude-editor\\jobs\\x" -> ".claude-editor/jobs/"
+
+    Env-token markers such as ``%TEMP%`` and ``$CLAUDE_JOB_DIR`` match on the
+    same lowercased text.
+
+    Args:
+        text: The post body text to scan.
+
+    Returns:
+        The matched marker string, or None when the text names no volatile path.
+    """
+    normalized_text = text.replace("\\", "/").lower()
+    for each_marker in ALL_VOLATILE_PATH_MARKERS:
+        if each_marker in normalized_text:
+            return each_marker
+    return None
+
+
+def _is_environment_assignment(token: str) -> bool:
+    """Return whether a token is a ``NAME=value`` shell environment assignment."""
+    equals_index = token.find("=")
+    if equals_index <= 0:
+        return False
+    name_part = token[:equals_index]
+    if not (name_part[0].isalpha() or name_part[0] == "_"):
+        return False
+    return all(
+        each_character.isalnum() or each_character == "_"
+        for each_character in name_part
+    )
+
+
+def _tokens_name_gh_post_command(all_command_tokens: list[str]) -> bool:
+    """Return whether the tokens start with an affected ``gh`` post subcommand.
+
+    Leading ``NAME=value`` env assignments are skipped, then the next token must
+    be the literal ``gh`` command word followed by a post noun and verb. Anchoring
+    to the first command word keeps a ``gh pr comment`` mentioned only as quoted
+    argument data from classifying.
+
+    Args:
+        all_command_tokens: The shlex-split tokens of the logical command line.
+
+    Returns:
+        True when the command invokes an affected ``gh`` post subcommand.
+    """
+    command_index = 0
+    while command_index < len(all_command_tokens) and _is_environment_assignment(
+        all_command_tokens[command_index]
+    ):
+        command_index += 1
+    if command_index >= len(all_command_tokens):
+        return False
+    if all_command_tokens[command_index] != GH_COMMAND_NAME:
+        return False
+    remaining_tokens = all_command_tokens[command_index + 1 :]
+    if len(remaining_tokens) < MINIMUM_POST_SUBCOMMAND_TOKEN_COUNT:
+        return False
+    post_noun = remaining_tokens[0]
+    post_verb = remaining_tokens[1]
+    return post_verb in ALL_GH_POST_SUBCOMMANDS.get(post_noun, frozenset())
+
+
+def _reassemble_split_quoted_value(
+    value_token: str, all_following_tokens: list[str]
+) -> tuple[str, int]:
+    """Rejoin a quoted value that ``shlex.split(posix=False)`` split on spaces.
+
+    ``posix=False`` keeps backslashes intact (so Windows paths survive) but
+    splits a quoted value such as ``"dump in %TEMP%"`` into three tokens. This
+    rejoins the value token with the follow-on tokens up to the closing quote,
+    then strips the surrounding quotes so the full body text can be scanned.
+
+    Args:
+        value_token: The first token of the value, following the flag.
+        all_following_tokens: The tokens after ``value_token`` on the line.
+
+    Returns:
+        A ``(full_value, extra_tokens_consumed)`` pair; ``extra_tokens_consumed``
+        counts the follow-on tokens joined into the value.
+    """
+    extra_tokens = count_extra_tokens_to_skip_for_split_quoted_value(
+        all_following_tokens, value_token
+    )
+    if not extra_tokens:
+        return strip_surrounding_quotes(value_token), 0
+    joined_value = value_token + TOKEN_JOIN_SEPARATOR + TOKEN_JOIN_SEPARATOR.join(
+        all_following_tokens[:extra_tokens]
+    )
+    return strip_surrounding_quotes(joined_value), extra_tokens
+
+
+def _extract_flag_value_at(
+    all_command_tokens: list[str], token_index: int
+) -> tuple[bool, str, int] | None:
+    """Return a body/body-file value starting at token_index, or None.
+
+    Args:
+        all_command_tokens: The shlex-split tokens of the logical command line.
+        token_index: The index of the token to inspect.
+
+    Returns:
+        An ``(is_body_file, value, next_index)`` triple when the token opens a
+        body or body-file flag, else None. ``next_index`` is where scanning
+        resumes after the value's tokens.
+    """
+    current_token = all_command_tokens[token_index]
+    following_tokens = all_command_tokens[token_index + 1:]
+    body_equals_prefix = match_body_flag_equals_prefix(current_token)
+    if body_equals_prefix is not None:
+        value, extra = _reassemble_split_quoted_value(
+            current_token[len(body_equals_prefix):], following_tokens
+        )
+        return False, value, token_index + 1 + extra
+    body_file_equals_prefix = match_body_file_equals_prefix(current_token)
+    if body_file_equals_prefix is not None:
+        value, extra = _reassemble_split_quoted_value(
+            current_token[len(body_file_equals_prefix):], following_tokens
+        )
+        return True, value, token_index + 1 + extra
+    if current_token in all_body_flags and following_tokens:
+        value, extra = _reassemble_split_quoted_value(following_tokens[0], following_tokens[1:])
+        return False, value, token_index + 2 + extra
+    if current_token in (body_file_flag, body_file_short_flag) and following_tokens:
+        value, extra = _reassemble_split_quoted_value(following_tokens[0], following_tokens[1:])
+        return True, value, token_index + 2 + extra
+    return None
+
+
+def _collect_body_flag_values(
+    all_command_tokens: list[str],
+) -> tuple[list[str], list[str]]:
+    """Return inline body strings and body-file paths from the command tokens.
+
+    Args:
+        all_command_tokens: The shlex-split tokens of the logical command line.
+
+    Returns:
+        A ``(all_inline_bodies, all_body_file_paths)`` pair, each value stripped
+        of its surrounding quotes and rejoined across split-quote tokens.
+    """
+    all_inline_bodies: list[str] = []
+    all_body_file_paths: list[str] = []
+    token_index = 0
+    while token_index < len(all_command_tokens):
+        extraction = _extract_flag_value_at(all_command_tokens, token_index)
+        if extraction is None:
+            token_index += 1
+            continue
+        is_body_file, value, next_index = extraction
+        if is_body_file:
+            all_body_file_paths.append(value)
+        else:
+            all_inline_bodies.append(value)
+        token_index = next_index
+    return all_inline_bodies, all_body_file_paths
+
+
+def _read_body_file(body_file_path: str) -> str | None:
+    """Return the contents of a body-file path, or None when it cannot be read.
+
+    Args:
+        body_file_path: The path given to ``--body-file``/``-F``.
+
+    Returns:
+        The file text, or None for an unresolvable shell value (such as ``-`` for
+        stdin or a ``$VAR`` path) or an unreadable file.
+    """
+    if is_unresolvable_shell_value(body_file_path):
+        return None
+    try:
+        return Path(body_file_path).read_text(encoding=BODY_FILE_ENCODING)
+    except OSError:
+        return None
+
+
+def extract_gh_post_body_texts(command: str) -> list[str]:
+    """Return every post body text an affected ``gh`` command would send.
+
+    Non-post ``gh`` commands and unparseable command lines yield an empty list.
+    Body-file contents are read from disk so the embedded text is scanned rather
+    than the file path.
+
+    Args:
+        command: The raw Bash tool command string.
+
+    Returns:
+        Inline ``--body`` strings plus the contents of each readable body-file.
+    """
+    logical_line = get_logical_first_line(command)
+    if not logical_line:
+        return []
+    try:
+        all_command_tokens = shlex.split(logical_line, posix=False)
+    except ValueError:
+        return []
+    if not _tokens_name_gh_post_command(all_command_tokens):
+        return []
+    all_inline_bodies, all_body_file_paths = _collect_body_flag_values(
+        all_command_tokens
+    )
+    all_body_texts = list(all_inline_bodies)
+    for each_path in all_body_file_paths:
+        file_text = _read_body_file(each_path)
+        if file_text is not None:
+            all_body_texts.append(file_text)
+    return all_body_texts
+
+
+def extract_mcp_body_texts(all_tool_input: dict[str, object]) -> list[str]:
+    """Return the body and comment strings from a GitHub MCP post tool input.
+
+    Args:
+        all_tool_input: The MCP tool's input mapping.
+
+    Returns:
+        The non-empty string values of the ``body`` and ``comment`` parameters.
+    """
+    all_body_texts: list[str] = []
+    for each_param_name in ALL_MCP_BODY_PARAM_NAMES:
+        param_value = all_tool_input.get(each_param_name)
+        if isinstance(param_value, str) and param_value:
+            all_body_texts.append(param_value)
+    return all_body_texts
+
+
+def _collect_body_texts(tool_name: str, all_tool_input: dict[str, object]) -> list[str]:
+    if tool_name == BASH_TOOL_NAME:
+        command = all_tool_input.get("command", "")
+        if not isinstance(command, str) or not command:
+            return []
+        return extract_gh_post_body_texts(command)
+    if tool_name.startswith(MCP_GITHUB_TOOL_PREFIX):
+        return extract_mcp_body_texts(all_tool_input)
+    return []
+
+
+def _first_volatile_marker(all_body_texts: list[str]) -> str | None:
+    for each_text in all_body_texts:
+        matched_marker = scan_text_for_volatile_marker(each_text)
+        if matched_marker is not None:
+            return matched_marker
+    return None
+
+
+def _emit_block(tool_name: str, matched_marker: str) -> None:
+    deny_payload = {
+        "hookSpecificOutput": {
+            "hookEventName": "PreToolUse",
+            "permissionDecision": "deny",
+            "permissionDecisionReason": CORRECTIVE_MESSAGE,
+        }
+    }
+    log_hook_block(
+        calling_hook_name="volatile_path_in_post_blocker.py",
+        hook_event="PreToolUse",
+        block_reason=CORRECTIVE_MESSAGE,
+        tool_name=tool_name,
+        offending_input_preview=matched_marker,
+    )
+    print(json.dumps(deny_payload))
+    sys.stdout.flush()
+
+
+def main() -> None:
+    """Read the PreToolUse payload and block a post that names a volatile path."""
+    try:
+        hook_input = json.load(sys.stdin)
+    except json.JSONDecodeError:
+        sys.exit(0)
+
+    tool_name = hook_input.get("tool_name", "")
+    tool_input = hook_input.get("tool_input", {})
+    if not isinstance(tool_name, str) or not isinstance(tool_input, dict):
+        sys.exit(0)
+
+    all_body_texts = _collect_body_texts(tool_name, tool_input)
+    matched_marker = _first_volatile_marker(all_body_texts)
+    if matched_marker is None:
+        sys.exit(0)
+
+    _emit_block(tool_name, matched_marker)
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

package/hooks/hooks.json

@@ -7,7 +7,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "python3 -c \"import sys; sys.path.insert(0, r'${CLAUDE_PLUGIN_ROOT}/hooks'); from validators.run_all_validators import main; sys.exit(main())\"",
+            "command": "python3 -c \"import sys; sys.path.insert(0, r'${CLAUDE_PLUGIN_ROOT}/hooks'); from validators.run_all_validators import main; sys.exit(main())\" --pre-tool-use",
             "timeout": 15
           }
         ]
@@ -55,6 +55,16 @@
             "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/gh_body_arg_blocker.py",
             "timeout": 10
           },
+          {
+            "type": "command",
+            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/nas_ssh_binary_enforcer.py",
+            "timeout": 10
+          },
+          {
+            "type": "command",
+            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/volatile_path_in_post_blocker.py",
+            "timeout": 10
+          },
           {
             "type": "command",
             "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/conventional_pr_title_gate.py",
@@ -83,7 +93,7 @@
           {
             "type": "command",
             "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/pr_description_enforcer.py",
-            "timeout": 10
+            "timeout": 30
           },
           {
             "type": "command",
@@ -142,6 +152,16 @@
           }
         ]
       },
+      {
+        "matcher": "mcp__plugin_github_github__.*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/volatile_path_in_post_blocker.py",
+            "timeout": 10
+          }
+        ]
+      },
       {
         "matcher": "Agent",
         "hooks": [
@@ -186,6 +206,16 @@
             "timeout": 10
           }
         ]
+      },
+      {
+        "matcher": "EnterWorktree",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/lifecycle/enter_worktree_origin_prefetch.py",
+            "timeout": 25
+          }
+        ]
       }
     ],
     "SessionStart": [

package/hooks/hooks_constants/CLAUDE.md

@@ -13,6 +13,7 @@ Shared constant modules imported by hooks throughout the `hooks/` tree. Each fil
 | `bot_mention_comment_blocker_constants.py` | Patterns for detecting bot @-mentions in PR comments |
 | `claude_md_orphan_file_blocker_constants.py` | Table patterns, file extensions, scan budget, and block-message text for the CLAUDE.md orphan-file blocker |
 | `code_rules_enforcer_constants.py` | File-extension sets, test-path patterns, advisory line thresholds, boolean-name prefixes |
+| `enter_worktree_prefetch_constants.py` | Tool name, origin-remote ref names, and git-command timeouts for the EnterWorktree origin-prefetch hook |
 | `env_var_table_code_drift_constants.py` | Table patterns, env-var-name and code-file recognizers, scan budget, and block-message text for the env-var-table code-drift blocker |
 | `code_rules_path_utils_constants.py` | Path-matching helpers used by the code-rules check modules |
 | `code_verifier_spawn_preflight_gate_constants.py` | Subagent type, merge-tree command flags, timeouts, and deny-message text for the code-verifier spawn pre-flight gate |
@@ -37,6 +38,7 @@ Shared constant modules imported by hooks throughout the `hooks/` tree. Each fil
 | `js_conventions_constants.py` | Banned identifier set, boolean-prefix pattern, and declaration/JSDoc patterns for the JavaScript convention checks |
 | `messages.py` | Short user-facing notice strings shown when a Stop hook redirects agent behavior |
 | `multi_edit_reconstruction.py` | `apply_edits()` / `edits_for_tool()` — shared helpers that reconstruct the post-edit content of an Edit or MultiEdit, imported by the blockers that judge post-edit content |
+| `nas_ssh_binary_enforcer_constants.py` | Bash tool name, the NAS address pattern, ssh-family basenames, OpenSSH binary path suffixes, launcher-wrapper set, shell control-operator tokens and split pattern, leading-assignment and duration patterns, the batch-mode pattern, and the two deny messages for the NAS ssh binary enforcer |
 | `open_questions_in_plans_blocker_constants.py` | Patterns for detecting unresolved open questions in plan documents |
 | `orphan_css_class_constants.py` | Scan radius and selector patterns for the orphan-CSS-class check |
 | `package_inventory_stale_blocker_constants.py` | Inventory document names, production code extensions, backtick token pattern, smallest inventory size, exempt names, scan budget, and block-message text for the package-inventory stale-entry blocker |
@@ -46,6 +48,7 @@ Shared constant modules imported by hooks throughout the `hooks/` tree. Each fil
 | `pr_converge_bugteam_enforcer_constants.py` | State keys and timing config for the bugteam-parallel enforcer |
 | `pr_converge_bugteam_enforcer_state.py` | State-file helpers for the bugteam enforcer |
 | `pr_description_enforcer_constants.py` | PR-description shape rules and command patterns |
+| `pr_description_proof_of_work_constants.py` | Proof-part detection patterns, gh command tokens, and corrective messages for the proof-of-work comment audit |
 | `pre_tool_use_stdin.py` | `read_hook_input_dictionary_from_stdin()` — shared stdin parser for PreToolUse hooks |
 | `precommit_code_rules_gate_constants.py` | Scope argument and exit-code constants for the precommit gate |
 | `project_paths_reader.py` | Loads `~/.claude/project-paths.json` — the per-user project-path registry |
@@ -65,6 +68,7 @@ Shared constant modules imported by hooks throughout the `hooks/` tree. Each fil
 | `task_list_loop_starter_constants.py` | The one-line task-list instruction and the full session-start directive text for the task-list loop starter hook |
 | `text_stripping.py` | `strip_code_and_quotes()` — shared helper that removes fenced code blocks, inline code, and blockquotes from prose, imported by the Stop-hook prose blockers |
 | `unused_module_import_constants.py` | Patterns for detecting unused module-level imports |
+| `volatile_path_in_post_blocker_constants.py` | Volatile path markers, affected `gh` post subcommands, MCP body param names, and the corrective message for the volatile-path post blocker |
 | `windows_rmtree_blocker_constants.py` | The unsafe `shutil.rmtree` pattern and the safe replacement pattern |
 | `workflow_substitution_slot_blocker_constants.py` | Per-iteration token patterns for the workflow-slot blocker |
 

package/hooks/hooks_constants/code_rules_path_utils_constants.py

@@ -24,6 +24,7 @@ ALL_CONFIG_DIRECTORY_NAMES = frozenset(
         "bugteam_scripts_constants",
         "implement_scripts_constants",
         "log_audit_constants",
+        "usage_pause_constants",
         "dev_env_scripts_constants",
     }
 )

package/hooks/hooks_constants/code_verifier_spawn_preflight_gate_constants.py

@@ -26,6 +26,9 @@ MERGE_TREE_CONFLICT_EXIT_CODE: int = 1
 MERGE_TREE_CLEAN_EXIT_CODE: int = 0
 MERGE_TREE_TIMEOUT_SECONDS: int = 30
 
+ALL_MERGE_HEAD_PROBE_FLAGS: tuple[str, ...] = ("rev-parse", "--verify", "--quiet", "MERGE_HEAD")
+ALL_UNMERGED_PATHS_DIFF_FLAGS: tuple[str, ...] = ("diff", "--name-only", "--diff-filter=U")
+
 ALL_NAME_ONLY_WORKTREE_DIFF_FLAGS: tuple[str, ...] = (
     "-c",
     "core.quotePath=false",

package/hooks/hooks_constants/enter_worktree_prefetch_constants.py

@@ -0,0 +1,18 @@
+"""Configuration constants for the ``enter_worktree_origin_prefetch`` hook.
+
+The hook keeps a freshly created worktree from starting on a stale cached
+``refs/remotes/origin/<default-branch>`` value: it fetches that ref right
+before ``EnterWorktree`` resolves its base.
+"""
+
+from __future__ import annotations
+
+ENTER_WORKTREE_TOOL_NAME: str = "EnterWorktree"
+ENTER_WORKTREE_PATH_INPUT_KEY: str = "path"
+
+ORIGIN_REMOTE_NAME: str = "origin"
+ORIGIN_HEAD_SYMBOLIC_REF: str = "refs/remotes/origin/HEAD"
+ORIGIN_REMOTE_REF_PREFIX: str = "refs/remotes/origin/"
+
+GIT_SYMBOLIC_REF_TIMEOUT_SECONDS: int = 5
+GIT_FETCH_TIMEOUT_SECONDS: int = 15

package/hooks/hooks_constants/nas_ssh_binary_enforcer_constants.py

@@ -0,0 +1,59 @@
+"""Constants for the NAS ssh binary enforcer hook.
+
+Holds the Bash tool name, the NAS host-token pattern, the ssh-family command
+basenames, the Windows OpenSSH binary path suffixes, the launcher-wrapper set, the
+shell control-operator tokens and their split pattern, the leading-assignment and
+launcher-duration patterns, the batch-mode pattern, and the two deny messages.
+"""
+
+import re
+
+BASH_TOOL_NAME = "Bash"
+
+NAS_HOST_TOKEN_PATTERN = re.compile(r"(?:^|@)192\.168\.1\.100(?::|$)")
+"""Match the NAS address only as a connection host.
+
+Anchored to token start or an ``@`` and followed by ``:`` or token end, so the
+address is matched as a bare host (``192.168.1.100``), a ``user@host``
+(``jon@192.168.1.100``), or a ``host:path`` target (``192.168.1.100:/vol1/``,
+``jon@192.168.1.100:/vol1/``). The address inside a remote-command argument
+(``"ping 192.168.1.100"``) or a remote path component on another host
+(``jon@other:/backup/192.168.1.100/``) does not count as a NAS connection.
+"""
+
+ALL_SSH_FAMILY_COMMAND_BASENAMES = frozenset(
+    {"ssh", "scp", "sftp", "ssh.exe", "scp.exe", "sftp.exe"}
+)
+ALL_OPENSSH_BINARY_PATH_SUFFIXES = (
+    "/openssh/ssh.exe",
+    "/openssh/scp.exe",
+    "/openssh/sftp.exe",
+)
+ALL_LAUNCHER_WRAPPER_COMMANDS = frozenset({"timeout", "nohup", "nice", "stdbuf", "setsid", "env"})
+ALL_SHELL_CONTROL_OPERATOR_TOKENS = frozenset({"&&", "||", ";", "|", "&", "|&"})
+CONTROL_OPERATOR_SPLIT_PATTERN = re.compile(r"(&&|\|\||;|\|&|\||(?<!>)&(?!>))")
+LEADING_ASSIGNMENT_PATTERN = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*=")
+LAUNCHER_DURATION_PATTERN = re.compile(r"^\d+[a-z]*$", re.IGNORECASE)
+BATCH_MODE_PATTERN = re.compile(r"batchmode\s*=\s*yes", re.IGNORECASE)
+
+BARE_SSH_BINARY_MESSAGE = (
+    "BLOCKED [nas-ssh-binary]: Git Bash's MSYS ssh reads ~/.ssh/id_ed25519 as "
+    "world-readable through its ACL mapping, rejects the key as bad permissions, "
+    "and falls back to an interactive password prompt that hangs unattended "
+    "sessions against the NAS at 192.168.1.100.\n\n"
+    "Use the Windows OpenSSH binary, which authenticates the key without prompting:\n"
+    '  "/c/Windows/System32/OpenSSH/ssh.exe" -o BatchMode=yes -o ConnectTimeout=10 '
+    '-p 9222 jon@192.168.1.100 "<cmd>"\n\n'
+    "See ~/.claude/rules/nas-ssh-invocation.md for full guidance."
+)
+
+MISSING_BATCH_MODE_MESSAGE = (
+    "BLOCKED [nas-ssh-binary]: this NAS ssh command uses the Windows OpenSSH binary "
+    "but omits -o BatchMode=yes, so an authentication regression falls back to an "
+    "interactive password prompt that hangs unattended sessions against the NAS at "
+    "192.168.1.100.\n\n"
+    "Add -o BatchMode=yes so a key failure exits loudly rather than prompting:\n"
+    '  "/c/Windows/System32/OpenSSH/ssh.exe" -o BatchMode=yes -o ConnectTimeout=10 '
+    '-p 9222 jon@192.168.1.100 "<cmd>"\n\n'
+    "See ~/.claude/rules/nas-ssh-invocation.md for full guidance."
+)

package/hooks/hooks_constants/pr_description_enforcer_constants.py

@@ -41,6 +41,7 @@ ALL_HEAVY_TESTING_HEADERS: frozenset[str] = frozenset(
     {TEST_PLAN_HEADER, TESTING_HEADER, TESTS_HEADER, VERIFICATION_HEADER, VALIDATION_HEADER}
 )
 GH_PR_COMMAND_MIN_TOKEN_COUNT: int = 3
+ALL_PR_NUMBER_BEARING_GH_PR_SUBCOMMANDS: frozenset[str] = frozenset({"edit", "comment", "ready"})
 BODY_FILE_STDIN_SENTINEL: str = "-"
 ATOMIC_WRITE_TEMP_SUFFIX: str = ".tmp"
 SELF_CLOSING_REFERENCE_MESSAGE_PREFIX: str = "PR body references its own PR number #"
@@ -134,6 +135,7 @@ __all__ = [
     "FLESCH_SYLLABLES_PER_WORD_COEFFICIENT",
     "FLESCH_WORDS_PER_SENTENCE_COEFFICIENT",
     "GH_PR_COMMAND_MIN_TOKEN_COUNT",
+    "ALL_PR_NUMBER_BEARING_GH_PR_SUBCOMMANDS",
     "HEADING_LINE_PATTERN",
     "HEAVY_MIN_BODY_CHARS_FOR_CLASSIFICATION",
     "HEAVY_SHAPE",

package/hooks/hooks_constants/pr_description_proof_of_work_constants.py

@@ -0,0 +1,111 @@
+"""Configuration constants for the proof-of-work PR-comment audit.
+
+Holds the proof-part detection patterns, the gap and linkage word lists,
+the gh command tokens the audit runs to read a PR's comments and diff, and
+the corrective messages returned when a proof part is missing or when
+``gh pr ready`` runs with no passing proof comment on the PR.
+"""
+
+from __future__ import annotations
+
+import re
+
+ALL_PROOF_HEADING_KEYWORDS: tuple[str, ...] = ("proof", "verification")
+
+PR_READY_INVOCATION_PATTERN: re.Pattern[str] = re.compile(r"(?:^|[;&|])\s*gh\s+pr\s+ready\b")
+PR_READY_UNDO_FLAG: str = "--undo"
+
+GH_EXECUTABLE: str = "gh"
+GH_API_SUBCOMMAND: str = "api"
+GH_PAGINATE_FLAG: str = "--paginate"
+GH_SLURP_FLAG: str = "--slurp"
+PR_COMMENTS_API_PATH_TEMPLATE: str = "repos/{{owner}}/{{repo}}/issues/{pr_number}/comments"
+ALL_PR_DIFF_SUBCOMMANDS: tuple[str, ...] = ("pr", "diff")
+PR_DIFF_NAME_ONLY_FLAG: str = "--name-only"
+ALL_PR_VIEW_NUMBER_ARGUMENTS: tuple[str, ...] = ("pr", "view", "--json", "number")
+PR_NUMBER_JSON_FIELD: str = "number"
+COMMENT_BODY_JSON_FIELD: str = "body"
+GH_COMMAND_TIMEOUT_SECONDS: int = 6
+MAX_DIFF_SCAN_CHARS: int = 200000
+
+ALL_VISUAL_FILE_SUFFIXES: frozenset[str] = frozenset(
+    {".png", ".jpg", ".jpeg", ".gif", ".webp", ".avif", ".svg", ".ico", ".html", ".css"}
+)
+HEX_COLOR_ADDED_LINE_PATTERN: re.Pattern[str] = re.compile(r"^\+.*#[0-9A-Fa-f]{6}\b", re.MULTILINE)
+IMAGE_EMBED_PATTERN: re.Pattern[str] = re.compile(r"!\[[^\]]*\]\([^)\s]+\)")
+ISSUE_REFERENCE_PATTERN: re.Pattern[str] = re.compile(r"#\d+")
+PLAN_LINKAGE_KEYWORD_PATTERN: re.Pattern[str] = re.compile(
+    r"\b(?:issue|phase|plan|parent|advanc\w*|milestone|part of)\b", re.IGNORECASE
+)
+DIGIT_PATTERN: re.Pattern[str] = re.compile(r"\d")
+ALL_HONEST_GAP_PHRASES: tuple[str, ...] = (
+    "gap",
+    "limitation",
+    "cannot",
+    "does not show",
+    "not shown",
+    "unverified",
+    "not covered",
+)
+
+PROOF_PART_COMMAND_MESSAGE: str = (
+    "proof comment missing a fenced command block showing the exact command(s) run on real data"
+)
+PROOF_PART_MEASURED_MESSAGE: str = (
+    "proof comment missing a measured-value element -- add a table row or bullet fact carrying "
+    "the numbers read from the produced artifact"
+)
+PROOF_PART_PLAN_LINKAGE_MESSAGE: str = (
+    "proof comment missing a plan-linkage sentence -- add one line naming the parent issue or "
+    "phase this PR advances, with its #number"
+)
+PROOF_PART_VISUAL_MESSAGE: str = (
+    "proof comment missing a visual element on a visual change -- embed an image (color "
+    "swatches, before/after screenshots) for values a human cannot read at a glance"
+)
+PROOF_PART_HONEST_GAPS_MESSAGE: str = (
+    "proof comment missing an honest-gaps statement -- say plainly what this offline proof "
+    "cannot show and what covers that gap"
+)
+
+PR_READY_GATE_MESSAGE_TEMPLATE: str = (
+    "BLOCKED: [PROOF_OF_WORK] PR #{pr_number} carries no passing proof-of-work comment. "
+    "Post one comment with a proof or verification heading carrying: "
+    "(1) the exact command(s) run on real data in a fenced code block, "
+    "(2) measured outcomes from the produced artifact as a table row or bullet facts, "
+    "(3) one sentence naming the parent issue or phase this PR advances, with its #number, "
+    "(4) an image embed when the diff touches images, HTML, CSS, or hex color values, and "
+    "(5) an honest statement of what the offline proof cannot show. "
+    "Then re-run gh pr ready."
+)
+
+__all__ = [
+    "ALL_HONEST_GAP_PHRASES",
+    "ALL_PROOF_HEADING_KEYWORDS",
+    "ALL_PR_DIFF_SUBCOMMANDS",
+    "ALL_PR_VIEW_NUMBER_ARGUMENTS",
+    "ALL_VISUAL_FILE_SUFFIXES",
+    "COMMENT_BODY_JSON_FIELD",
+    "DIGIT_PATTERN",
+    "GH_API_SUBCOMMAND",
+    "GH_COMMAND_TIMEOUT_SECONDS",
+    "GH_EXECUTABLE",
+    "GH_PAGINATE_FLAG",
+    "GH_SLURP_FLAG",
+    "HEX_COLOR_ADDED_LINE_PATTERN",
+    "IMAGE_EMBED_PATTERN",
+    "ISSUE_REFERENCE_PATTERN",
+    "MAX_DIFF_SCAN_CHARS",
+    "PLAN_LINKAGE_KEYWORD_PATTERN",
+    "PROOF_PART_COMMAND_MESSAGE",
+    "PROOF_PART_HONEST_GAPS_MESSAGE",
+    "PROOF_PART_MEASURED_MESSAGE",
+    "PROOF_PART_PLAN_LINKAGE_MESSAGE",
+    "PROOF_PART_VISUAL_MESSAGE",
+    "PR_COMMENTS_API_PATH_TEMPLATE",
+    "PR_DIFF_NAME_ONLY_FLAG",
+    "PR_NUMBER_JSON_FIELD",
+    "PR_READY_GATE_MESSAGE_TEMPLATE",
+    "PR_READY_INVOCATION_PATTERN",
+    "PR_READY_UNDO_FLAG",
+]