claude-dev-env 8.62.1 → 8.64.0

package/hooks/blocking/pull_request_proof.py

@@ -1,4 +1,4 @@
-"""Deny a new pull request whose body carries no 'Proof in practice' section."""
+"""Deny a new pull request whose body lacks a 'Proof in practice' or an 'Existing work' section."""
 
 from __future__ import annotations
 
@@ -18,8 +18,10 @@ from hooks_constants.pull_request_proof_constants import (
     ALL_PYTHON_PROGRAM_NAMES,
     COMMAND_MARKER,
     CREATE_PULL_REQUEST_TOOL_SUFFIX,
+    EXISTING_WORK_HEADING_PATTERN,
     LINE_SEPARATOR,
     MISSING_BODY_REASON,
+    MISSING_EXISTING_WORK_REASON,
     MISSING_PROOF_REASON,
     NEXT_HEADING_PATTERN,
     PROOF_HEADING_PATTERN,
@@ -48,6 +50,16 @@ def _lines_until_heading(all_lines: list[str], heading_level: int) -> list[str]:
     return all_lines
 
 
+def _section_text(body: str, heading_pattern: str) -> str | None:
+    all_lines = body.splitlines()
+    for each_index, each_line in enumerate(all_lines):
+        heading_level = _heading_level(each_line, heading_pattern)
+        if heading_level is not None:
+            all_section_lines = _lines_until_heading(all_lines[each_index + 1 :], heading_level)
+            return LINE_SEPARATOR.join(all_section_lines).strip()
+    return None
+
+
 def proof_section(body: str) -> str | None:
     """Return the text under the body's 'Proof in practice' heading, or None.
 
@@ -58,13 +70,20 @@ def proof_section(body: str) -> str | None:
 
     The section runs to the next heading of the same or a higher level.
     """
-    all_lines = body.splitlines()
-    for each_index, each_line in enumerate(all_lines):
-        heading_level = _heading_level(each_line, PROOF_HEADING_PATTERN)
-        if heading_level is not None:
-            all_section_lines = _lines_until_heading(all_lines[each_index + 1 :], heading_level)
-            return LINE_SEPARATOR.join(all_section_lines).strip()
-    return None
+    return _section_text(body, PROOF_HEADING_PATTERN)
+
+
+def section_under_existing_work(body: str) -> str | None:
+    """Return the text under the body's 'Existing work' heading, or None.
+
+    ::
+
+        "## Existing work\\n`a.py:4` runs it\\n## Notes" -> "`a.py:4` runs it"
+        "## Summary\\nno existing work heading"         -> None
+
+    The section runs to the next heading of the same or a higher level.
+    """
+    return _section_text(body, EXISTING_WORK_HEADING_PATTERN)
 
 
 def _script_arguments(program: str, all_arguments: list[str]) -> list[str] | None:
@@ -139,3 +158,26 @@ def missing_proof_reason(all_payload_fields: Mapping[str, object]) -> str | None
         if not section or COMMAND_MARKER not in section:
             return MISSING_PROOF_REASON
     return None
+
+
+def missing_existing_work_reason(all_payload_fields: Mapping[str, object]) -> str | None:
+    """Return a deny reason when a new pull request's body has no existing-work section, else None.
+
+    ::
+
+        mcp__github__create_pull_request, body has the section -> None
+        mcp__github__create_pull_request, body without it      -> MISSING_EXISTING_WORK_REASON
+        gh pr create --fill                                     -> None
+        gh pr edit, git push, any other tool                    -> None
+
+    The section is an 'Existing work' heading with text under it. A create
+    command whose body this gate cannot read passes here, because
+    missing_proof_reason denies it first.
+
+    Args:
+        all_payload_fields: The parsed PreToolUse input.
+    """
+    for each_body in _create_bodies(all_payload_fields):
+        if each_body is not None and not section_under_existing_work(each_body):
+            return MISSING_EXISTING_WORK_REASON
+    return None

package/hooks/blocking/test_pr_lifecycle_skill_gate.py

@@ -15,7 +15,10 @@ from blocking import pr_lifecycle_skill_gate as gate
 from hooks_constants.pr_lifecycle_skill_gate_constants import DENY_REASON
 from hooks_constants.pull_request_proof_constants import MISSING_PROOF_REASON
 
-PROVEN_FOLLOWUP_BODY = "Follow-up to #1731\n\n## Proof in practice\nRan `python probe.py`.\n"
+PROVEN_FOLLOWUP_BODY = (
+    "Follow-up to #1731\n\n## Existing work\nNothing found in open or merged pull requests.\n\n"
+    "## Proof in practice\nRan `python probe.py`.\n"
+)
 
 
 def _transcript(tmp_path: Path, skill_name: str | None = None, compact: bool = False) -> Path:

package/hooks/blocking/test_pull_request_proof.py

@@ -1,4 +1,4 @@
-"""Behavior tests for the proof-in-practice check on a new pull request."""
+"""Behavior tests for the proof-in-practice and existing-work checks on a new pull request."""
 
 import sys
 from pathlib import Path
@@ -8,10 +8,19 @@ if str(HOOKS_DIRECTORY) not in sys.path:
     sys.path.insert(0, str(HOOKS_DIRECTORY))
 
 from blocking import pull_request_proof as gate
-from hooks_constants.pull_request_proof_constants import MISSING_BODY_REASON, MISSING_PROOF_REASON
+from hooks_constants.pull_request_proof_constants import (
+    MISSING_BODY_REASON,
+    MISSING_EXISTING_WORK_REASON,
+    MISSING_PROOF_REASON,
+)
 
 PROVEN_BODY = "## Summary\nAdds a gate.\n\n## Proof in practice\nRan `python run.py`.\n> denied\n"
 UNPROVEN_BODY = "## Summary\nAdds a gate.\n\n## Verification\nUnit tests pass.\n"
+SEARCHED_BODY = (
+    "## Summary\nAdds a gate.\n\n## Existing work\n`gate.py:12` runs the check; this adds a flag.\n\n"
+    "## Proof in practice\nRan `python run.py`.\n"
+)
+EMPTY_EXISTING_WORK_BODY = "## Existing work\n\n## Proof in practice\nRan `python run.py`.\n"
 
 
 def _shell(command: str, working_directory: Path | None = None) -> dict[str, object]:
@@ -90,3 +99,37 @@ def test_other_pull_request_commands_should_pass() -> None:
 def test_other_tools_should_pass() -> None:
     payload = {"tool_name": "mcp__github__update_pull_request", "tool_input": {"body": "x"}}
     assert gate.missing_proof_reason(payload) is None
+
+
+def test_existing_work_section_should_stop_at_a_heading_of_the_same_level() -> None:
+    assert gate.section_under_existing_work(SEARCHED_BODY) == "`gate.py:12` runs the check; this adds a flag."
+
+
+def test_mcp_create_without_existing_work_should_be_denied() -> None:
+    assert gate.missing_existing_work_reason(_mcp_create(PROVEN_BODY)) == MISSING_EXISTING_WORK_REASON
+
+
+def test_mcp_create_with_an_empty_existing_work_section_should_be_denied() -> None:
+    payload = _mcp_create(EMPTY_EXISTING_WORK_BODY)
+    assert gate.missing_existing_work_reason(payload) == MISSING_EXISTING_WORK_REASON
+
+
+def test_mcp_create_with_existing_work_should_pass() -> None:
+    assert gate.missing_existing_work_reason(_mcp_create(SEARCHED_BODY)) is None
+
+
+def test_gh_create_body_file_without_existing_work_should_be_denied(tmp_path: Path) -> None:
+    (tmp_path / "body.md").write_text(PROVEN_BODY, encoding="utf-8")
+    payload = _shell("gh pr create --draft --body-file body.md", tmp_path)
+    assert gate.missing_existing_work_reason(payload) == MISSING_EXISTING_WORK_REASON
+
+
+def test_unreadable_body_should_leave_the_deny_to_the_proof_check() -> None:
+    payload = _shell("gh pr create --fill")
+    assert gate.missing_existing_work_reason(payload) is None
+    assert gate.missing_proof_reason(payload) == MISSING_BODY_REASON
+
+
+def test_other_pull_request_commands_should_pass_the_existing_work_check() -> None:
+    for each_command in ("gh pr edit 3 --body x", "git push -u origin b", "gh pr view"):
+        assert gate.missing_existing_work_reason(_shell(each_command)) is None

package/hooks/hooks_constants/pull_request_proof_constants.py

@@ -25,3 +25,17 @@ MISSING_PROOF_REASON = (
     " prove the change, leave the pull request unopened and tell the user what you could"
     " not run. Read " + PROOF_GUIDE_PATH + " for the full rule."
 )
+EXISTING_WORK_HEADING_PATTERN = r"^(#{1,6})[ \t]+existing work[ \t]*#*[ \t]*$"
+EXISTING_WORK_GUIDE_PATH = "~/.claude/docs/rule-guides/explore-thoroughly.md"
+MISSING_EXISTING_WORK_REASON = (
+    "This pull request body has no 'Existing work' section. Before you open a pull"
+    " request, search for what already does the change in full or in part: repository"
+    " code, open and merged pull requests, hooks, rules, skills, workflows, trackers and"
+    " production config. Add an 'Existing work' heading to the body. Under it, list each"
+    " piece you found with its link or file:line and what this pull request adds on top"
+    " of it, or state that nothing was found and name the places you searched. When the"
+    " search finds a piece that already does the change, stop and report it to the user"
+    " before you open the pull request. Run the search-before-acting skill and read "
+    + EXISTING_WORK_GUIDE_PATH
+    + " for the full rule."
+)

package/package.json

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

package/rules/explore-thoroughly.md

@@ -1,9 +1,9 @@
 # Explore thoroughly
 
-**When:** Choosing an implementation approach or recommending an architectural direction.
+**When:** Before you log, plan, delegate, or build an ask, or choose an approach.
 
-Read relevant files, map local patterns, and identify constraints before committing to an approach. Scale exploration to risk: inspect nearby files for a small change, broader examples for a new feature, and the full landscape for an architectural decision. Once the files, constraints, and success condition are known, act without repeating settled research.
+Search for what already does the ask, in full or in part. When something exists, stop and report it to the user in four points; run the `search-before-acting` skill. Then read files, patterns, and constraints, scaled to risk. Once the files, constraints, and success condition are known, act without repeating settled research.
 
-**Enforcement:** none, the agent applies it.
+**Enforcement:** the pull request gate denies a body with no "Existing work" section.
 
-**Full text:** [`docs/rule-guides/explore-thoroughly.md`](../docs/rule-guides/explore-thoroughly.md). Read it when setting exploration depth.
+**Full text:** [`docs/rule-guides/explore-thoroughly.md`](../docs/rule-guides/explore-thoroughly.md). Read it for search scope and depth.