claude-dev-env 2.0.2 → 2.1.0

package/hooks/blocking/verified_commit_gate_parts/gated_invocations.py

@@ -0,0 +1,205 @@
+"""Find every gated ``git commit``/``git push`` and the directory it targets.
+
+::
+
+    git commit -m x                    -> gated in the session directory
+    cd subdir && git commit -m x       -> gated in session_directory/subdir
+    git -C /repo commit -m x           -> gated in /repo
+    git stash push                     -> not gated (push is an argument)
+
+Walks the ``git`` words and directory-change verbs in a command, in the order
+they appear, so a commit after a ``cd`` gates against the directory the shell
+is actually in when it runs.
+"""
+
+from __future__ import annotations
+
+import re
+
+from config.verified_commit_constants import (
+    DIRECTORY_CHANGE_PATTERN_PREFIX,
+    DIRECTORY_CHANGE_PATTERN_SUFFIX,
+    DIRECTORY_CHANGE_VERBS,
+    GATED_GIT_SUBCOMMANDS,
+    OPTION_WITH_VALUE_STEP,
+    REPO_DIRECTORY_OPTION,
+    VALUE_TAKING_GIT_OPTIONS,
+    WORK_TREE_OPTION,
+)
+from config.verified_commit_gate_output_constants import REGEX_ALTERNATION_SEPARATOR
+from verified_commit_gate_parts.command_tokenization import (
+    collapse_line_continuations,
+    git_word_match_gates,
+    is_inside_quoted_region,
+    quoted_spans,
+    strip_token_quotes,
+)
+from verified_commit_gate_parts.directory_resolution import (
+    directory_change_target,
+    expand_home_prefix,
+    resolve_against,
+    split_option_value,
+    value_after_option,
+)
+
+
+def _record_directory_option(
+    option_name: str,
+    option_value: str | None,
+    repo_directory: str | None,
+    work_tree_directory: str | None,
+) -> tuple[str | None, str | None]:
+    """Fold one value-taking git option into the tracked target directories."""
+    if option_value is None:
+        return repo_directory, work_tree_directory
+    if option_name == REPO_DIRECTORY_OPTION:
+        return expand_home_prefix(option_value), work_tree_directory
+    if option_name == WORK_TREE_OPTION:
+        return repo_directory, expand_home_prefix(option_value)
+    return repo_directory, work_tree_directory
+
+
+def _resolved_option_value(
+    attached_value: str | None, all_following_tokens: list[str], option_index: int
+) -> str | None:
+    """Read a value-taking option's value: attached (``--opt=v``) or the next token.
+
+    An attached value is used as given, even when it is the empty string
+    (``--work-tree=``), so an empty value never falls through to read the
+    following subcommand token as the value.
+
+    Args:
+        attached_value: The ``=``-attached value, or None when none was attached.
+        all_following_tokens: Quote-stripped tokens after the ``git`` word.
+        option_index: Index of the value-taking option token.
+
+    Returns:
+        The attached value when present, otherwise the separate value token.
+    """
+    if attached_value is not None:
+        return attached_value
+    return value_after_option(all_following_tokens, option_index)
+
+
+def gated_invocation_directory(all_following_tokens: list[str]) -> tuple[bool, str | None]:
+    """Walk the quote-stripped tokens after a ``git`` word to its subcommand.
+
+    ``git stash push`` is not gated ("push" is an argument); ``git commit -m
+    x`` is gated ("commit" sits in subcommand position).
+
+    Returns:
+        Whether the subcommand is gated, and its ``-C``/``--work-tree`` directory.
+    """
+    repo_directory: str | None = None
+    work_tree_directory: str | None = None
+    token_index = 0
+    while token_index < len(all_following_tokens):
+        each_token = all_following_tokens[token_index]
+        option_name, attached_value = split_option_value(each_token)
+        if option_name in VALUE_TAKING_GIT_OPTIONS:
+            option_value = _resolved_option_value(
+                attached_value, all_following_tokens, token_index
+            )
+            repo_directory, work_tree_directory = _record_directory_option(
+                option_name, option_value, repo_directory, work_tree_directory
+            )
+            token_index += 1 if attached_value is not None else OPTION_WITH_VALUE_STEP
+            continue
+        if each_token.startswith("-"):
+            token_index += 1
+            continue
+        return each_token.lower() in GATED_GIT_SUBCOMMANDS, repo_directory or work_tree_directory
+    return False, repo_directory or work_tree_directory
+
+
+def _directory_change_verb_pattern() -> re.Pattern[str]:
+    """Build the regex matching any directory-change verb spelling."""
+    verb_alternation = REGEX_ALTERNATION_SEPARATOR.join(
+        re.escape(each_verb) for each_verb in sorted(DIRECTORY_CHANGE_VERBS)
+    )
+    return re.compile(
+        DIRECTORY_CHANGE_PATTERN_PREFIX + verb_alternation + DIRECTORY_CHANGE_PATTERN_SUFFIX,
+        re.IGNORECASE,
+    )
+
+
+def _ordered_gate_matches(command_text: str) -> list[re.Match[str]]:
+    """Collect every ``git`` word and directory-change verb match, in order."""
+    git_word_pattern = re.compile(
+        r"(?:^|(?<=[\s;&|(\"'/\\]))git(?:\.exe)?(?:[\"'](?=\s|$)|(?=\s|$))",
+        re.IGNORECASE,
+    )
+    all_quoted_spans = quoted_spans(command_text)
+    all_directory_change_matches = [
+        each_match
+        for each_match in _directory_change_verb_pattern().finditer(command_text)
+        if not is_inside_quoted_region(each_match.start(), all_quoted_spans)
+    ]
+    all_git_word_matches = [
+        each_match
+        for each_match in git_word_pattern.finditer(command_text)
+        if git_word_match_gates(each_match, command_text, all_quoted_spans)
+    ]
+    return sorted(
+        all_git_word_matches + all_directory_change_matches,
+        key=lambda each_match: each_match.start(),
+    )
+
+
+def _following_tokens(command_text: str, match_end: int) -> list[str]:
+    """Quote-strip the tokens following a ``git`` word match."""
+    command_token_pattern = re.compile(r"\"[^\"]*\"|'[^']*'|\S+")
+    following_text = command_text[match_end:]
+    return [
+        strip_token_quotes(each_token)
+        for each_token in command_token_pattern.findall(following_text)
+    ]
+
+
+def _apply_directory_change(
+    command_text: str, directory_change_match: re.Match[str], active_directory: str
+) -> str:
+    """Resolve the active directory after one ``cd``/``pushd`` match."""
+    changed_directory = directory_change_target(command_text, directory_change_match.end())
+    if changed_directory is None:
+        return active_directory
+    return resolve_against(active_directory, changed_directory)
+
+
+def _target_directory_for_match(
+    command_text: str, git_word_match: re.Match[str], active_directory: str
+) -> str | None:
+    """Resolve the gated directory for one ``git`` word match, or None."""
+    all_following_tokens = _following_tokens(command_text, git_word_match.end())
+    is_gated, flagged_directory = gated_invocation_directory(all_following_tokens)
+    if not is_gated:
+        return None
+    if flagged_directory is None:
+        return active_directory
+    return resolve_against(active_directory, flagged_directory)
+
+
+def gated_repo_directories(command_text: str, fallback_directory: str) -> list[str]:
+    """Collect the directories of every git commit/push found in a command.
+
+    Args:
+        command_text: The raw command string from the tool payload.
+        fallback_directory: The session working directory, used as the
+            active directory until a directory-change verb changes it and
+            when the git call carries no ``-C`` flag.
+
+    Returns:
+        One directory per detected commit/push invocation, in order; empty
+        when the command carries no gated git verb.
+    """
+    command_text = collapse_line_continuations(command_text)
+    active_directory = fallback_directory
+    target_directories: list[str] = []
+    for each_match in _ordered_gate_matches(command_text):
+        if each_match.group().lower().strip("\"'") in DIRECTORY_CHANGE_VERBS:
+            active_directory = _apply_directory_change(command_text, each_match, active_directory)
+            continue
+        target_directory = _target_directory_for_match(command_text, each_match, active_directory)
+        if target_directory is not None:
+            target_directories.append(target_directory)
+    return target_directories

package/hooks/blocking/verified_commit_gate_parts/tests/conftest.py

@@ -0,0 +1,10 @@
+"""Put the blocking and hooks directories on sys.path for the parts tests."""
+
+import sys
+from pathlib import Path
+
+_blocking_directory = str(Path(__file__).resolve().parents[2])
+_hooks_directory = str(Path(__file__).resolve().parents[3])
+for each_bootstrap_directory in (_blocking_directory, _hooks_directory):
+    if each_bootstrap_directory not in sys.path:
+        sys.path.insert(0, each_bootstrap_directory)

package/hooks/blocking/verified_commit_gate_parts/tests/test_command_tokenization.py

@@ -0,0 +1,94 @@
+"""Behavioral tests for the verified-commit gate's command tokenization."""
+
+import re
+
+from verified_commit_gate_parts.command_tokenization import (
+    collapse_line_continuations,
+    command_carries_trailing_marker,
+    containing_quoted_span,
+    git_word_match_gates,
+    is_inside_quoted_region,
+    quoted_spans,
+    strip_token_quotes,
+)
+
+VERIFY_SKIP_MARKER = "# verify-skip"
+
+
+def test_command_carries_trailing_marker_true_for_a_real_trailing_comment() -> None:
+    command_text = f'git commit -m "wire up" {VERIFY_SKIP_MARKER}'
+    assert command_carries_trailing_marker(command_text, VERIFY_SKIP_MARKER)
+
+
+def test_command_carries_trailing_marker_false_when_marker_sits_inside_quotes() -> None:
+    command_text = f'git commit -m "explain the {VERIFY_SKIP_MARKER} hatch"'
+    assert not command_carries_trailing_marker(command_text, VERIFY_SKIP_MARKER)
+
+
+def test_command_carries_trailing_marker_true_with_trailing_words_after_marker() -> None:
+    command_text = f"git commit -m x {VERIFY_SKIP_MARKER} please"
+    assert command_carries_trailing_marker(command_text, VERIFY_SKIP_MARKER)
+
+
+def test_command_carries_trailing_marker_false_when_hash_abuts_a_prior_hash() -> None:
+    command_text = f"git commit -m x #{VERIFY_SKIP_MARKER}"
+    assert not command_carries_trailing_marker(command_text, VERIFY_SKIP_MARKER)
+
+
+def test_command_carries_trailing_marker_false_when_hash_abuts_a_closing_quote() -> None:
+    command_text = f'git commit -m "msg"{VERIFY_SKIP_MARKER}'
+    assert not command_carries_trailing_marker(command_text, VERIFY_SKIP_MARKER)
+
+
+def test_command_carries_trailing_marker_true_when_real_comment_follows_quoted_mention() -> None:
+    command_text = f'git commit -m "see {VERIFY_SKIP_MARKER}" {VERIFY_SKIP_MARKER}'
+    assert command_carries_trailing_marker(command_text, VERIFY_SKIP_MARKER)
+
+
+def test_collapse_line_continuations_joins_a_split_git_word() -> None:
+    assert collapse_line_continuations("git \\\ncommit -m x") == "git commit -m x"
+
+
+def test_quoted_spans_finds_each_quoted_region_in_order() -> None:
+    all_spans = quoted_spans("git commit -m \"first\" -m 'second'")
+    assert len(all_spans) == 2
+    assert all_spans[0][0] < all_spans[1][0]
+
+
+def test_is_inside_quoted_region_true_for_a_position_inside_a_span() -> None:
+    command_text = 'echo "Next: git commit"'
+    all_spans = quoted_spans(command_text)
+    assert is_inside_quoted_region(command_text.index("git"), all_spans)
+
+
+def test_containing_quoted_span_returns_none_outside_any_quotes() -> None:
+    command_text = 'git commit -m "msg"'
+    all_spans = quoted_spans(command_text)
+    assert containing_quoted_span(command_text.index("git"), all_spans) is None
+
+
+def test_strip_token_quotes_removes_unpaired_edge_quote() -> None:
+    assert strip_token_quotes('push"') == "push"
+
+
+def test_git_word_match_gates_true_for_a_bare_git_word() -> None:
+    command_text = "git commit -m x"
+    git_word_match = re.search(r"git", command_text)
+    assert git_word_match is not None
+    assert git_word_match_gates(git_word_match, command_text, quoted_spans(command_text))
+
+
+def test_git_word_match_gates_false_for_git_inside_prose() -> None:
+    command_text = 'echo "Next: git commit"'
+    all_spans = quoted_spans(command_text)
+    git_word_match = re.search(r"git", command_text)
+    assert git_word_match is not None
+    assert not git_word_match_gates(git_word_match, command_text, all_spans)
+
+
+def test_git_word_match_gates_true_for_a_quoted_git_binary_path() -> None:
+    command_text = "& 'C:/x/git.exe' commit -m x"
+    all_spans = quoted_spans(command_text)
+    git_word_match = re.search(r"git", command_text)
+    assert git_word_match is not None
+    assert git_word_match_gates(git_word_match, command_text, all_spans)

package/hooks/blocking/verified_commit_gate_parts/tests/test_deny_payload.py

@@ -0,0 +1,17 @@
+"""Behavioral tests for the verified-commit gate's deny-payload shape."""
+
+from verified_commit_gate_parts.deny_payload import build_deny_payload
+
+
+def test_build_deny_payload_carries_the_deny_decision_and_reason() -> None:
+    deny_payload = build_deny_payload("BLOCKED: needs a verdict")
+    hook_specific_output = deny_payload["hookSpecificOutput"]
+    assert hook_specific_output["hookEventName"] == "PreToolUse"
+    assert hook_specific_output["permissionDecision"] == "deny"
+    assert hook_specific_output["permissionDecisionReason"] == "BLOCKED: needs a verdict"
+
+
+def test_build_deny_payload_carries_the_verify_skip_additional_context() -> None:
+    deny_payload = build_deny_payload("BLOCKED: needs a verdict")
+    additional_context = deny_payload["hookSpecificOutput"]["additionalContext"]
+    assert "# verify-skip" in additional_context

package/hooks/blocking/verified_commit_gate_parts/tests/test_deny_reason.py

@@ -0,0 +1,38 @@
+"""Behavioral tests for the verified-commit gate's deny-reason resolution."""
+
+import subprocess
+from pathlib import Path
+
+from verified_commit_gate_parts.deny_reason import deny_reason_for_directory
+
+
+def _run_git(work_dir: Path, *git_arguments: str) -> None:
+    subprocess.run(
+        ["git", "-C", str(work_dir), *git_arguments],
+        check=True,
+        capture_output=True,
+        text=True,
+    )
+
+
+def _make_repo_with_no_upstream(tmp_path: Path) -> Path:
+    work_dir = tmp_path / "work"
+    work_dir.mkdir()
+    _run_git(work_dir, "init", "--initial-branch=main")
+    _run_git(work_dir, "config", "user.email", "tests@example.com")
+    _run_git(work_dir, "config", "user.name", "Gate Tests")
+    (work_dir / "app.py").write_text(
+        "def add(left: int, right: int) -> int:\n    return left + right\n", encoding="utf-8"
+    )
+    _run_git(work_dir, "add", "-A")
+    _run_git(work_dir, "commit", "-m", "base")
+    return work_dir
+
+
+def test_deny_reason_for_directory_none_when_not_a_git_repo(tmp_path: Path) -> None:
+    assert deny_reason_for_directory(str(tmp_path), "") is None
+
+
+def test_deny_reason_for_directory_none_with_no_resolvable_upstream(tmp_path: Path) -> None:
+    work_dir = _make_repo_with_no_upstream(tmp_path)
+    assert deny_reason_for_directory(str(work_dir), "") is None

package/hooks/blocking/verified_commit_gate_parts/tests/test_directory_resolution.py

@@ -0,0 +1,71 @@
+"""Behavioral tests for the verified-commit gate's directory-change resolution."""
+
+import os
+
+import pytest
+
+from verified_commit_gate_parts.directory_resolution import (
+    argument_tokens_after_verb,
+    directory_change_target,
+    expand_home_prefix,
+    is_absolute_directory,
+    resolve_against,
+    split_option_value,
+    value_after_option,
+)
+
+
+def test_split_option_value_splits_an_equals_form_option() -> None:
+    assert split_option_value("--work-tree=/repo") == ("--work-tree", "/repo")
+
+
+def test_split_option_value_returns_none_value_for_a_bare_option() -> None:
+    assert split_option_value("-C") == ("-C", None)
+
+
+def test_value_after_option_reads_the_next_token() -> None:
+    assert value_after_option(["-C", "/repo", "commit"], 0) == "/repo"
+
+
+def test_value_after_option_returns_none_at_the_end() -> None:
+    assert value_after_option(["-C"], 0) is None
+
+
+def test_expand_home_prefix_expands_a_leading_tilde(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setenv("HOME", "C:/fake-home")
+    monkeypatch.setenv("USERPROFILE", "C:/fake-home")
+    assert expand_home_prefix("~/repo") == os.path.expanduser("~/repo")
+
+
+def test_is_absolute_directory_true_for_a_drive_path() -> None:
+    assert is_absolute_directory("C:/repo")
+
+
+def test_is_absolute_directory_false_for_a_relative_path() -> None:
+    assert not is_absolute_directory("subdir")
+
+
+def test_resolve_against_joins_a_relative_target() -> None:
+    assert resolve_against("/session", "subdir") == os.path.join("/session", "subdir")
+
+
+def test_resolve_against_replaces_with_an_absolute_target() -> None:
+    assert resolve_against("/session", "/repo") == "/repo"
+
+
+def test_argument_tokens_after_verb_stops_at_a_separator() -> None:
+    command_text = "cd subdir; git commit"
+    match_end = command_text.index("cd") + len("cd")
+    assert argument_tokens_after_verb(command_text, match_end) == ["subdir"]
+
+
+def test_directory_change_target_reads_the_destination() -> None:
+    command_text = "cd /repo"
+    match_end = command_text.index("cd") + len("cd")
+    assert directory_change_target(command_text, match_end) == "/repo"
+
+
+def test_directory_change_target_none_for_a_bare_change() -> None:
+    command_text = "cd && git commit"
+    match_end = command_text.index("cd") + len("cd")
+    assert directory_change_target(command_text, match_end) is None

package/hooks/blocking/verified_commit_gate_parts/tests/test_gated_invocations.py

@@ -0,0 +1,61 @@
+"""Behavioral tests for gated git-invocation directory resolution."""
+
+import os
+
+from verified_commit_gate_parts.gated_invocations import (
+    gated_invocation_directory,
+    gated_repo_directories,
+)
+
+
+def test_gated_invocation_directory_true_for_commit_in_subcommand_position() -> None:
+    is_gated, repo_directory = gated_invocation_directory(["commit", "-m", "x"])
+    assert is_gated
+    assert repo_directory is None
+
+
+def test_gated_invocation_directory_false_for_commit_as_an_argument() -> None:
+    is_gated, _ = gated_invocation_directory(["stash", "push"])
+    assert not is_gated
+
+
+def test_gated_invocation_directory_reads_the_dash_c_directory() -> None:
+    is_gated, repo_directory = gated_invocation_directory(["-C", "/repo", "commit"])
+    assert is_gated
+    assert repo_directory == "/repo"
+
+
+def test_gated_repo_directories_finds_a_bare_commit() -> None:
+    assert gated_repo_directories("git commit -m x", "/session") == ["/session"]
+
+
+def test_gated_repo_directories_ignores_a_quoted_prose_mention() -> None:
+    assert gated_repo_directories('echo "Next: git commit"', "/session") == []
+
+
+def test_gated_repo_directories_follows_a_preceding_cd() -> None:
+    assert gated_repo_directories("cd subdir && git commit -m x", "/session") == [
+        os.path.join("/session", "subdir")
+    ]
+
+
+def test_gated_repo_directories_honors_a_dash_c_flag() -> None:
+    assert gated_repo_directories("git -C /repo commit -m x", "/session") == ["/repo"]
+
+
+def test_gated_repo_directories_empty_for_a_non_gated_subcommand() -> None:
+    assert gated_repo_directories("git status", "/session") == []
+
+
+def test_gated_invocation_directory_reads_an_empty_work_tree_value_not_the_subcommand() -> None:
+    is_gated, work_tree_directory = gated_invocation_directory(
+        ["--work-tree=", "commit", "-m", "x"]
+    )
+    assert is_gated
+    assert work_tree_directory == ""
+
+
+def test_gated_repo_directories_gates_an_empty_work_tree_against_the_session() -> None:
+    assert gated_repo_directories("git --work-tree= commit -m x", "/session") == [
+        os.path.join("/session", "")
+    ]

package/hooks/hooks_constants/CLAUDE.md

@@ -20,6 +20,7 @@ Shared constant modules imported by hooks throughout the `hooks/` tree. Each fil
 | `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 |
 | `command_dispatch_constants.py` | Command-word regex, command-key access pattern, tokenization pattern, and anchors for the unanchored command-dispatch meta-gate |
 | `convergence_branch_constants.py` | Branch and worktree naming patterns for the convergence gate |
+| `convergence_gate_blocker_constants.py` | The full-PR-URL and `--repo`/`-R` flag parse patterns that key the convergence gate to the PR its command names |
 | `conventional_pr_title_gate_constants.py` | Bash tool name, gh executable basenames and pr create/edit subcommand tokens, title/repo flag names, semantic-title-CI workflow markers, the Conventional Commits type list and title pattern, the semantic-pull-request action `types:` input pattern, and block-message text for the conventional-PR-title gate |
 | `dead_argparse_argument_constants.py` | Patterns for detecting unused argparse arguments |
 | `dead_config_field_constants.py` | Patterns for detecting unused `*Config` / `*Selectors` dataclass fields |
@@ -32,7 +33,7 @@ Shared constant modules imported by hooks throughout the `hooks/` tree. Each fil
 | `dynamic_stderr_handler.py` | `DynamicStderrHandler` — a logging handler that resolves `sys.stderr` at emit time (for testability) |
 | `gh_pr_author_swap_constants.py` | Constants for the PR-author swap enforcement hooks |
 | `hardcoded_user_path_constants.py` | Patterns for detecting hardcoded home-directory paths |
-| `harness_scratchpad_constants.py` | Fixed path components (`claude-` user-directory prefix, separator replacement, `scratchpad` leaf name) and payload keys that rebuild the harness session scratchpad directory for the code-rules and TDD gate exemptions |
+| `harness_scratchpad_constants.py` | Fixed path components (`claude` / `claude-` user-directory name and prefix, `scratchpad` leaf name), the PreToolUse session-id payload key, and the `CLAUDE_CODE_SESSION_ID` environment variable name that the code-rules and TDD gates use to recognize an existing harness session scratchpad directory |
 | `hook_block_logger.py` | `log_hook_block()` — shared fail-safe logger every blocking hook calls to append a JSON record of each block decision to `~/.claude/logs/hook-blocks.log` |
 | `hook_log_extractor_constants.py` | Neon table name, offset state file path, timeouts, and outcome-type mapping for the hook-log extractor |
 | `hook_prose_detector_consistency_constants.py` | Trigger patterns and corrective messages for the hook-prose consistency checker |
@@ -42,6 +43,8 @@ Shared constant modules imported by hooks throughout the `hooks/` tree. Each fil
 | `local_identity.py` | Loader for local machine values: NAS host, ssh user, and ssh port the ssh enforcer guards (`CLAUDE_NAS_*` / `~/.claude/local-identity.json` with placeholder defaults), the PII commit-scan exempt-repo slug set (`CLAUDE_PII_EXEMPT_REPOS` / `pii_exempt_repositories`), and the per-repository allowlisted-values mapping (`pii_allowlisted_values`, keyed by owner/repo slug) read from the git-ignored local file whose path `CLAUDE_LOCAL_IDENTITY_PATH` may point elsewhere; also composes the ssh enforcer's two deny messages that quote the NAS values |
 | `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 |
+| `mypy_integration_constants.py` | Path markers (``.git``, ``.py``, ``pyproject.toml``) for mypy project-root resolution |
+| `mypy_validator_cache_constants.py` | Cache paths and tunables for the mypy_validator per-session caches |
 | `nas_ssh_binary_enforcer_constants.py` | Bash tool name, ssh-family basenames, OpenSSH binary path suffixes, launcher-wrapper set, shell control-operator tokens and split pattern, leading-assignment and duration patterns, and the batch-mode pattern 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/hooks/hooks_constants/code_rules_path_utils_constants.py

@@ -24,5 +24,6 @@ ALL_CONFIG_DIRECTORY_NAMES = frozenset(
         "usage_pause_constants",
         "codex_review_scripts_constants",
         "dev_env_scripts_constants",
+        "fresh_branch_scripts_constants",
     }
 )

package/hooks/hooks_constants/convergence_gate_blocker_constants.py

@@ -0,0 +1,36 @@
+"""Command-parse patterns for the convergence gate's repo binding.
+
+The convergence gate keys its evidence lookup to the PR that the
+``gh pr ready`` command names. These patterns pull an explicit owner/repo
+out of the command — and, for a full PR URL, the PR number too — so the
+gate binds to the repository the command targets rather than the
+session working directory's repository when the two differ.
+
+The owner/repo and URL patterns run only over the ``gh pr ready`` segment,
+clipped at the first command separator, so a flag or URL that belongs to a
+chained command does not bind the gate to the wrong PR::
+
+    gh pr ready 161 && gh pr comment 999 --repo other-owner/other-repo
+    ^^^^^^^^^^^^^^^^                                    clipped here ^
+    -> ready segment scanned; the chained --repo is out of scope
+
+    gh pr ready 161 --repo sample-owner/target-repo
+                    ^^^^^^ ^^^^^^^^^^^^ ^^^^^^^^^^^
+                    flag   owner        repo         -> REPO_OVERRIDE_FLAG_PATTERN
+    gh pr ready https://github.com/sample-owner/target-repo/pull/161
+                                   ^^^^^^^^^^^^ ^^^^^^^^^^^      ^^^
+                                   owner        repo            number
+                                                -> PR_URL_OWNER_REPO_NUMBER_PATTERN
+"""
+
+GH_PR_READY_ANCHOR_PATTERN: str = r"\bgh\s+pr\s+ready\b(?![^&|;\n]*--undo)"
+
+COMMAND_SEPARATOR_PATTERN: str = r"&&|\|\||;|\||\n"
+
+PR_URL_OWNER_REPO_NUMBER_PATTERN: str = (
+    r"https://github\.com/(?P<owner>[\w.-]+)/(?P<repo>[\w.-]+)/pull/(?P<number>\d+)"
+)
+
+REPO_OVERRIDE_FLAG_PATTERN: str = (
+    r"(?:^|\s)(?:--repo|-R)(?:=|\s+)(?:[\w.-]+/)*(?P<owner>[\w.-]+)/(?P<repo>[\w.-]+)"
+)

package/hooks/hooks_constants/harness_scratchpad_constants.py

@@ -1,17 +1,18 @@
 """Constants for resolving the Claude Code harness session scratchpad directory.
 
 The harness gives each session a throwaway scratch directory it announces in
-the session's system prompt, laid out as
-``<tempdir>/claude-<uid>/<mangled-cwd>/<session-id>/scratchpad``. These constants
-name the fixed path components the code-rules and TDD gates read to rebuild that
-directory from the signals a hook process can see.
-
-The exemption is POSIX-only: without ``os.getuid`` (Windows) it never fires,
-so full enforcement stays in place there.
+the session's system prompt. The layout carries a harness user directory
+(``claude`` on Windows, ``claude-<uid>`` on POSIX), a mangled working-directory
+segment, the session id, and a ``scratchpad`` leaf:
+``<tempdir>/<user-dir>/<mangled-cwd>/<session-id>/scratchpad``. These constants
+name the fixed path components the code-rules, TDD, and doc-language gates match
+to recognize that directory from the signals a hook process reads: the session id in the
+PreToolUse payload or the ``CLAUDE_CODE_SESSION_ID`` environment variable, and
+the temp-directory root.
 """
 
+HARNESS_SCRATCHPAD_USER_DIRECTORY_NAME: str = "claude"
 HARNESS_SCRATCHPAD_USER_DIRECTORY_PREFIX: str = "claude-"
-HARNESS_SCRATCHPAD_PATH_SEPARATOR_REPLACEMENT: str = "-"
 HARNESS_SCRATCHPAD_LEAF_DIRECTORY_NAME: str = "scratchpad"
 HOOK_PAYLOAD_SESSION_ID_KEY: str = "session_id"
-HOOK_PAYLOAD_WORKING_DIRECTORY_KEY: str = "cwd"
+CLAUDE_SESSION_ID_ENVIRONMENT_VARIABLE_NAME: str = "CLAUDE_CODE_SESSION_ID"

package/hooks/hooks_constants/mypy_integration_constants.py

@@ -0,0 +1,16 @@
+"""Path markers used when mypy resolves a target file's project root.
+
+The integration walks ancestors for a ``.git`` entry or a ``pyproject.toml``,
+and filters the check list to ``.py`` files. These names live here so the
+integration module carries no inline path or extension literals.
+"""
+
+__all__ = [
+    "GIT_DIRECTORY_NAME",
+    "PYTHON_SOURCE_SUFFIX",
+    "PYPROJECT_FILENAME",
+]
+
+GIT_DIRECTORY_NAME: str = ".git"
+PYTHON_SOURCE_SUFFIX: str = ".py"
+PYPROJECT_FILENAME: str = "pyproject.toml"