claude-dev-env 2.24.0 → 2.25.0

package/hooks/git-hooks/AGENTS.md

@@ -9,7 +9,8 @@ Native git hooks that run outside the Claude Code lifecycle — invoked directly
 | `pre_commit.py` | `pre-commit` | Runs immediate CODE_RULES and terminology validation over staged changes; exits 1 when any staged file has a blocking violation. CI runs package tests for package Python changes. |
 | `pre_push.py` | `pre-push` | Blocks a push that would land a non-`main` local branch onto remote `main` (or `master`), then runs the CODE_RULES gate. An existing branch's gate base is the merge base with the remote default branch; the gate process still diffs that base against checkout HEAD, so the surface matches the pushed tip only when HEAD is that tip. |
 | `pre_push_base_reference.py` | — | Resolves a usable gate base for `pre_push.py`: reads the pushed remote name from git's arguments, then turns a symbolic default-branch head into a reference that git can resolve |
-| `post_commit.py` | `post-commit` | Runs after a commit lands; performs any post-commit bookkeeping |
+| `post_commit.py` | `post-commit` | Runs bookkeeping, then best-effort reminds the agent about its PR |
+| `pull_request_handoff.py` | — | Prints the full PR title and description handoff prompt |
 | `gate_utils.py` | — | Shared helpers: resolves the gate script path, checks that the path is a safe regular file |
 | `test_config.py` | — | Test configuration helpers |
 | `test_gate_utils.py` | — | Tests for `gate_utils.py` |

package/hooks/git-hooks/gate_utils.py

@@ -6,14 +6,29 @@ import os
 import stat
 from pathlib import Path
 
+import git_hooks_constants
 from git_hooks_constants import (
-    ALL_GATE_SCRIPT_RELATIVE_PATH,
     CLAUDE_HOME_DEFAULT_SUBDIRECTORY,
     CLAUDE_HOME_ENV_VAR,
     GATE_PATH_OVERRIDE_ENV_VAR,
 )
 
 
+def load_gate_script_relative_path(
+    constants_module: object | None = None,
+) -> tuple[str, ...]:
+    """Return the gate script path segments from git_hooks_constants.
+
+    Prefer ALL_GATE_SCRIPT_RELATIVE_PATH. Fall back to GATE_SCRIPT_RELATIVE_PATH
+    when an older installed constants module has not been updated yet.
+    """
+    module = git_hooks_constants if constants_module is None else constants_module
+    try:
+        return module.ALL_GATE_SCRIPT_RELATIVE_PATH
+    except AttributeError:
+        return module.GATE_SCRIPT_RELATIVE_PATH
+
+
 def resolve_gate_script_path() -> tuple[Path, Path | None]:
     """Return (gate_path, exact_allowed_override_or_none).
 
@@ -34,7 +49,7 @@ def resolve_gate_script_path() -> tuple[Path, Path | None]:
         claude_home_directory = Path(claude_home_override).resolve()
     else:
         claude_home_directory = Path.home() / CLAUDE_HOME_DEFAULT_SUBDIRECTORY
-    gate_path = claude_home_directory.joinpath(*ALL_GATE_SCRIPT_RELATIVE_PATH)
+    gate_path = claude_home_directory.joinpath(*load_gate_script_relative_path())
     return gate_path, None
 
 

package/hooks/git-hooks/git_hooks_constants/__init__.py

@@ -97,6 +97,9 @@ GIT_REV_PARSE_VERIFY_FLAG: str = "--verify"
 GIT_QUIET_FLAG: str = "--quiet"
 GIT_SYMBOLIC_REFERENCE_SUBCOMMAND: str = "symbolic-ref"
 GIT_COMMAND_TIMEOUT_SECONDS: int = 30
+GH_EXECUTABLE_NAME: str = "gh"
+GH_PR_VIEW_TIMEOUT_SECONDS: int = 5
+GH_PR_VIEW_ARGUMENTS: tuple[str, ...] = ("pr", "view", "--json", "url", "--jq", ".url")
 GIT_FOR_EACH_REF_SUBCOMMAND: str = "for-each-ref"
 GIT_REFERENCE_SHORT_NAME_FORMAT_ARGUMENT: str = "--format=%(refname:short)"
 COMMIT_OBJECT_NAME_SUFFIX: str = "^{commit}"

package/hooks/git-hooks/post_commit.py

@@ -17,7 +17,14 @@ import sys
 from enum import StrEnum
 from pathlib import Path
 
-from git_hooks_constants import GIT_COMMAND_SUCCESS_EXIT_CODE, GIT_EXECUTABLE_NAME
+from git_hooks_constants import (
+    GH_EXECUTABLE_NAME,
+    GH_PR_VIEW_ARGUMENTS,
+    GH_PR_VIEW_TIMEOUT_SECONDS,
+    GIT_COMMAND_SUCCESS_EXIT_CODE,
+    GIT_EXECUTABLE_NAME,
+)
+from pull_request_handoff import build_pull_request_reminder
 
 
 class ParentPointerStatus(StrEnum):
@@ -163,6 +170,24 @@ def update_parent_pointer(
     return ParentPointerStatus.UPDATED, ""
 
 
+def print_pull_request_reminder(repo_dir: Path) -> None:
+    """Print a reminder when the committed repository has an open pull request."""
+    try:
+        result = subprocess.run(
+            [GH_EXECUTABLE_NAME, *GH_PR_VIEW_ARGUMENTS],
+            cwd=repo_dir,
+            check=False,
+            capture_output=True,
+            text=True,
+            timeout=GH_PR_VIEW_TIMEOUT_SECONDS,
+        )
+    except (OSError, subprocess.TimeoutExpired):
+        return
+    pull_request_url = result.stdout.strip()
+    if result.returncode == 0 and pull_request_url:
+        print(build_pull_request_reminder(pull_request_url))
+
+
 def main() -> int:
     """Update a parent repository after a submodule commit."""
     repo_path_text = run_git_from_current_directory("rev-parse", "--show-toplevel")
@@ -172,12 +197,14 @@ def main() -> int:
     repo_dir = Path(repo_path_text).resolve()
     parent_repo = find_parent_repo(repo_dir)
     if parent_repo is None:
+        print_pull_request_reminder(repo_dir)
         return 0
 
     commit_msg = run_git("log", "-1", "--pretty=%s", cwd=repo_dir)
     commit_hash = run_git("rev-parse", "HEAD", cwd=repo_dir)
     short_commit_hash = run_git("rev-parse", "--short", "HEAD", cwd=repo_dir)
     if not commit_hash or not short_commit_hash:
+        print_pull_request_reminder(repo_dir)
         return 0
 
     print()
@@ -195,14 +222,17 @@ def main() -> int:
         print("Parent update failed.")
         if parent_pointer_diagnostic:
             print(f"Git diagnostic: {parent_pointer_diagnostic}")
+        print_pull_request_reminder(repo_dir)
         return 0
     if parent_pointer_status is ParentPointerStatus.UNCHANGED:
         print("Parent already up to date.")
+        print_pull_request_reminder(repo_dir)
         return 0
 
     print("Parent updated successfully.")
     print("================================")
     print()
+    print_pull_request_reminder(repo_dir)
 
     return 0
 

package/hooks/git-hooks/pre_push.py

@@ -87,14 +87,13 @@ from pre_push_base_reference import (
     resolve_remote_name_from_arguments,
     resolve_usable_base_reference,
 )
+from pull_request_handoff import build_pull_request_reminder, get_pull_request_url
 
 
 def _report_unavailable_git(launch_error: Exception) -> int:
     """Report a git that would not run, and hand back the exit code to use."""
     git_command_unavailable_message = GIT_COMMAND_UNAVAILABLE_MESSAGE
-    sys.stderr.write(
-        git_command_unavailable_message.format(error=launch_error) + "\n"
-    )
+    sys.stderr.write(git_command_unavailable_message.format(error=launch_error) + "\n")
     return GATE_INFRASTRUCTURE_FAILURE_EXIT_CODE
 
 
@@ -145,8 +144,7 @@ def is_all_zeros_object_name(object_name: str) -> bool:
     if not stripped_object_name:
         return True
     return all(
-        each_character == all_zeros_object_name_character
-        for each_character in stripped_object_name
+        each_character == all_zeros_object_name_character for each_character in stripped_object_name
     )
 
 
@@ -385,9 +383,7 @@ def resolve_default_branch_merge_base(
     default_branch_reference = resolve_default_branch_reference(remote_name)
     if default_branch_reference is None:
         return None
-    default_branch_prefix = REMOTE_BRANCH_REFERENCE_TEMPLATE.format(
-        remote=remote_name, branch=""
-    )
+    default_branch_prefix = REMOTE_BRANCH_REFERENCE_TEMPLATE.format(remote=remote_name, branch="")
     default_branch_name = default_branch_reference.removeprefix(default_branch_prefix)
     if remote_branch_name == default_branch_name:
         return None
@@ -514,8 +510,6 @@ def invoke_gate(gate_script_path: Path, base_reference: str) -> int:
     return completion.returncode
 
 
-
-
 def main() -> int:
     stdin_read_failure_message = STDIN_READ_FAILURE_MESSAGE
     gate_infrastructure_failure_exit_code = GATE_INFRASTRUCTURE_FAILURE_EXIT_CODE
@@ -576,6 +570,9 @@ def main() -> int:
     code_rules_exit_code = invoke_gate(gate_script_path, usable_base_reference)
     if code_rules_exit_code != 0:
         return code_rules_exit_code
+    pull_request_url = get_pull_request_url(Path.cwd())
+    if pull_request_url:
+        print(build_pull_request_reminder(pull_request_url))
     return 0
 
 

package/hooks/git-hooks/pull_request_handoff.py

@@ -0,0 +1,32 @@
+from __future__ import annotations
+
+import subprocess
+from pathlib import Path
+
+from git_hooks_constants import (
+    GH_EXECUTABLE_NAME,
+    GH_PR_VIEW_ARGUMENTS,
+    GH_PR_VIEW_TIMEOUT_SECONDS,
+)
+
+
+def get_pull_request_url(repo_dir: Path) -> str | None:
+    try:
+        result = subprocess.run(
+            [GH_EXECUTABLE_NAME, *GH_PR_VIEW_ARGUMENTS],
+            cwd=repo_dir,
+            check=False,
+            capture_output=True,
+            text=True,
+            timeout=GH_PR_VIEW_TIMEOUT_SECONDS,
+        )
+    except (OSError, subprocess.SubprocessError):
+        return None
+    if result.returncode != 0:
+        return None
+    return result.stdout.strip() or None
+
+
+def build_pull_request_reminder(url: str) -> str:
+    prompt = "Review this pull request: <PR link>\n\nRead the PR and its full diff. Do not use the branch name, commit message, labels, current title, or a shallow summary.\n\nFind the main thing this adds for a user, caller, or operator.\n\nWrite like the reader is smart but knows nothing about this code. Pretend they asked you to explain it like they are five and feel stupid. If a word needs another sentence to explain it, replace the word — or turn it into a tiny story.\n\nYour job is not a dry API blurb. Your job is an illustrative before/after a person can picture.\n\nGold voice for titles and “What this adds”:\n\nThe theme package has a phone icon somewhere. We need to find it.\n\nBefore: yell “anyone know how to find icons?” and wait for a hand.\n\nAfter: call the finder by its name tag: “icon finder, go.”\n\nThat’s all “operation id” is — the finder’s name tag.\n\nRules for that voice:\n\nStart from a concrete scene (what’s in someone’s hand, what they’re hunting for).\nPrefer Before / After when the change is “how you ask” or “how you look it up.”\nUse picture words: hand it, open, find, check, save, skip, stop, call by name, name tag.\nPrefer spoken results: “found it,” “missing,” “duplicated,” “couldn’t.”\nWhen the diff uses an abstract word (operation id, registry, envelope, adapter, digest, schema), do one of two things:\nDrop it and say what the person does with their hands, or\nKeep it once, then gloss it in the same breath with a name-tag / mailbox / checklist metaphor — like the “finder’s name tag” line above.\nNever leave jargon unexplained. Never write as if the reader already knows the jargon.\nAdd a tiny concrete example in parentheses when a name is abstract (like “the phone icon”).\nFew words. Small words. Clear on first read.\nReturn:\n\nRecommended title\n\nFew words. Small words. Clear on first read.\nSay what you hand it, what it does, and what you get back — or the Before/After of how you ask.\nPrefer picture words and spoken results.\nGood title: “Call the icon finder by its name tag instead of asking around”\nGood title: “Given a theme STP and an asset name, report whether that asset was found, missing, or duplicated”\nBad title: anything that only says operation id / registry / typed envelope / adapter / digest / schema with no picture.\nUse “Add” only if it helps. Do not force it.\nNo vague words like “improve,” “enhance,” or “update.”\nReturn one title only.\nWhy this title fits\n\n1–2 short sentences in the same voice.\nIf needed, one Before / After beat, then what you get back.\nIf this section is needed to decode the title, rewrite the title.\nEvidence\n\nKey files or functions that support the title.\nIf you cannot read the PR or full diff, say so and do not propose a title.\n\nThen write a short, paste-ready PR description.\n\nUse this structure:\n\nWhat this adds\n1–2 short paragraphs in that illustrative voice. Lead with a scene when you can (“The theme package has a phone icon somewhere…”). If the change is a new way to ask, use Before / After. Say what you give it, what it does with its hands, and what you get back. If an abstract machine-word must appear, gloss it immediately (“That’s all X is — …”). Describe the job people can see. Do not describe inner machinery. Mention a check only if it is central to the feature. If there are many changes, keep the main one. Mention others only if they explain the main one.\n\nWhy\nOne short paragraph. Same plain level. Say who needs this and what goes wrong without it (the “yell and wait for a hand” problem). If this is needed to decode the feature, rewrite “What this adds.”\n\nVerification\nList only proof from the PR, CI, or your own checks.\n\nReported in the PR\n\n…\nChecked by you / CI here\n\n…\nRules:\n\nFew words. Small words. Clear on first read. ELI5 I-am-stupid mark.\nDo not invent behavior, tests, or benefits.\nStrip branch names, hashes, draft notes, agent notes, and merge notes.\nNo vague words like “improve,” “enhance,” or “update.”\nIllustrative first. Abstract labels only if glossed in the same breath.\nUse the recommended title and paste-ready description to run `gh pr edit <PR link> --title ... --body-file ...`, then run `gh pr view <PR link> --json title,body` to confirm the saved title and body. Report the saved result."
+    return prompt.replace("<PR link>", url)

package/hooks/git-hooks/test_gate_utils.py

@@ -3,9 +3,11 @@
 from __future__ import annotations
 
 from pathlib import Path
+import types
 
 import gate_utils
 import pytest
+from git_hooks_constants import ALL_GATE_SCRIPT_RELATIVE_PATH
 
 
 def test_resolve_gate_script_path_uses_override_env_var_when_set(
@@ -218,3 +220,39 @@ def test_is_safe_regular_file_rejects_path_outside_claude_home_env_trust_root(
     is_safe = gate_utils.is_safe_regular_file(outside_path, None)
 
     assert not is_safe
+
+def test_git_hooks_constants_exports_canonical_gate_script_relative_path() -> None:
+    assert ALL_GATE_SCRIPT_RELATIVE_PATH == (
+        "_shared",
+        "pr-loop",
+        "scripts",
+        "code_rules_gate.py",
+    )
+
+
+def test_load_gate_script_relative_path_prefers_canonical_name() -> None:
+    constants_module = types.SimpleNamespace(
+        ALL_GATE_SCRIPT_RELATIVE_PATH=("_shared", "pr-loop", "scripts", "code_rules_gate.py"),
+        GATE_SCRIPT_RELATIVE_PATH=("legacy", "path.py"),
+    )
+
+    loaded_path = gate_utils.load_gate_script_relative_path(constants_module)
+
+    assert loaded_path == ("_shared", "pr-loop", "scripts", "code_rules_gate.py")
+
+
+def test_load_gate_script_relative_path_falls_back_to_legacy_name() -> None:
+    constants_module = types.SimpleNamespace(
+        GATE_SCRIPT_RELATIVE_PATH=("_shared", "pr-loop", "scripts", "code_rules_gate.py"),
+    )
+
+    loaded_path = gate_utils.load_gate_script_relative_path(constants_module)
+
+    assert loaded_path == ("_shared", "pr-loop", "scripts", "code_rules_gate.py")
+
+
+def test_gate_utils_module_import_resolves_live_constants() -> None:
+    loaded_path = gate_utils.load_gate_script_relative_path()
+
+    assert loaded_path == ALL_GATE_SCRIPT_RELATIVE_PATH
+

package/hooks/git-hooks/test_post_commit.py

@@ -201,3 +201,90 @@ def test_main_prints_git_failure_diagnostic(
 
     assert post_commit.main() == 0
     assert "Git diagnostic: fatal: fixture commit failure" in capsys.readouterr().out
+
+
+@pytest.mark.parametrize(
+    "completed_process",
+    [
+        subprocess.CompletedProcess(["gh"], 1, "", "no pull request"),
+        subprocess.CompletedProcess(["gh"], 1, "", "auth failed"),
+    ],
+)
+def test_pull_request_reminder_is_silent_without_successful_url(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+    capsys: pytest.CaptureFixture[str],
+    completed_process: subprocess.CompletedProcess[str],
+) -> None:
+    monkeypatch.setattr(post_commit.subprocess, "run", lambda *args, **kwargs: completed_process)
+
+    post_commit.print_pull_request_reminder(tmp_path)
+
+    assert capsys.readouterr().out == ""
+
+
+def test_pull_request_reminder_prints_url(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    monkeypatch.setattr(
+        post_commit.subprocess,
+        "run",
+        lambda *args, **kwargs: subprocess.CompletedProcess(
+            ["gh"], 0, "https://github.com/example/repo/pull/1\n", ""
+        ),
+    )
+
+    post_commit.print_pull_request_reminder(tmp_path)
+
+    output = capsys.readouterr().out
+    assert output.startswith("Review this pull request: https://github.com/example/repo/pull/1\n")
+    assert "<PR link>" not in output
+    assert "Do not use the branch name, commit message, labels, current title" in output
+    assert "gh pr edit https://github.com/example/repo/pull/1" in output
+    assert output.rstrip().endswith("Report the saved result.")
+
+
+@pytest.mark.parametrize("exception", [FileNotFoundError(), subprocess.TimeoutExpired("gh", 5)])
+def test_pull_request_reminder_ignores_missing_gh_and_timeout(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+    capsys: pytest.CaptureFixture[str],
+    exception: Exception,
+) -> None:
+    def raise_exception(*args: object, **kwargs: object) -> None:
+        raise exception
+
+    monkeypatch.setattr(post_commit.subprocess, "run", raise_exception)
+
+    post_commit.print_pull_request_reminder(tmp_path)
+
+    assert capsys.readouterr().out == ""
+
+
+def test_main_runs_pull_request_reminder_after_parent_update(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    events: list[str] = []
+    repo = tmp_path / "repo"
+    parent = tmp_path / "parent"
+    repo.mkdir()
+    parent.mkdir()
+    monkeypatch.setattr(post_commit, "run_git_from_current_directory", lambda *args: str(repo))
+    monkeypatch.setattr(post_commit, "find_parent_repo", lambda repo_dir: parent)
+    monkeypatch.setattr(post_commit, "run_git", lambda *args, cwd: "a" * 40)
+    monkeypatch.setattr(
+        post_commit,
+        "update_parent_pointer",
+        lambda *args: events.append("parent") or (post_commit.ParentPointerStatus.UPDATED, ""),
+    )
+    monkeypatch.setattr(
+        post_commit,
+        "print_pull_request_reminder",
+        lambda repo_dir: events.append("reminder"),
+    )
+
+    assert post_commit.main() == 0
+    assert events == ["parent", "reminder"]

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "claude-dev-env",
-    "version": "2.24.0",
+    "version": "2.25.0",
     "description": "Claude Code development standards — rules, hooks, agents, commands, and skills",
     "type": "module",
     "bin": {