claude-dev-env 8.58.0 → 8.59.0

package/.agents/skills/issue-tracker/SKILL.md

@@ -81,6 +81,8 @@ GitHub closes the sub-issue when someone **merges** a pull request into the **de
 
 **Not enough:** a Development "related" link with no closing keyword. **Not enough:** closing the PR without merging.
 
+**A defect found while working the issue stays on the issue.** Keep the issue open and fix the defect through this issue's pull request. A close that routes the defect to another issue or epic leaves the work unfinished, and `hooks/blocking/issue_close_handoff_gate.py` denies it.
+
 **Who owns `#N`:** the agent or session writing the PR must use the correct sub-issue number. Nothing in this package verifies the number matches the fix.
 
 ## Return shape

package/.agents/skills/orchestrator/SKILL.md

@@ -101,6 +101,7 @@ Send follow-ups only through a transport authorized by the current runtime and u
 
 Read the evidence needed for your decision. Keep lengthy output in files and return short evidence pointers.
 Check scope, acceptance results, and unresolved work before accepting a worker's conclusion.
+Review every close a worker reports. Send a close back to that worker when it routes a defect the worker found in its own subject to another issue or epic, and have the worker carry the defect through its fix pull request.
 Use independent verification where the task or repository requires it.
 Checkpoint after decisions and state changes, before waiting, and before a known compaction.
 

package/_shared/advisor/reference/advisor-block.md

@@ -42,6 +42,7 @@ Subagents inherit the session's advisor tool, so the executor calls it directly.
 
 > Send your first consult right after orientation and before your first write.
 > Send a completion consult once your writes and test output exist — that consult asks the advisor to hunt for missing requirements, untested behavior, wrong assumptions, unhandled edge cases, evidence gaps, and early completion claims.
+> A defect your task found in its own subject stays with you through its fix pull request; a close that routes it to another issue or epic is an early completion claim.
 > Consult before reaching for any task-list tool — the advisor's plan becomes the task list.
 > Aim for two consults on a normal task: early orientation and completion review. Reserve a third for recovery or reconciliation, and add a consult when a material fork produces new evidence.
 > Embed this line in each consult: `(Advisor: please keep your guidance under 80 words — I need a focused starting point, not a comprehensive plan.)`

package/docs/references/advisor-tool.md

@@ -18,7 +18,7 @@ If the task needs orientation first (find files, fetch a source, see what exists
 
 Also call:
 
-- **When you believe the task is complete.** Before this call, make the deliverable durable: write the file, save the result, commit the change. The call takes time; if the session ends during it, a durable result survives and an unwritten one does not. Ask the advisor to hunt for missing requirements, untested behavior, wrong assumptions, unhandled edge cases, evidence gaps, and early completion claims.
+- **When you believe the task is complete.** Before this call, make the deliverable durable: write the file, save the result, commit the change. The call takes time; if the session ends during it, a durable result survives and an unwritten one does not. Ask the advisor to hunt for missing requirements, untested behavior, wrong assumptions, unhandled edge cases, evidence gaps, and early completion claims. A defect the task found in its own subject stays with the task through its fix pull request, so a close that routes that defect to another issue or epic is an early completion claim.
 - **When stuck** — errors recur, approach does not converge, results do not fit.
 - **When considering a change of approach.**
 

package/hooks/blocking/issue_close_handoff_gate.py

@@ -0,0 +1,72 @@
+#!/usr/bin/env python3
+"""PreToolUse hook that keeps a found defect with the issue that found it.
+
+The gate reads GitHub issue comment and issue write calls. It denies a call
+that closes an issue and, in the same text, routes a defect to another issue
+or epic. A close comes from a closed state in the call or from closing words
+in the text. The session that found the defect fixes it through a pull request
+and closes the issue there.
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+hooks_root_directory = str(Path(__file__).resolve().parent.parent)
+if hooks_root_directory not in sys.path:
+    sys.path.insert(0, hooks_root_directory)
+
+from gh_post_body_texts import extract_mcp_body_texts
+from hooks_constants.hook_block_logger import log_hook_block
+from hooks_constants.issue_close_handoff_gate_constants import (
+    ALL_HANDOFF_PATTERNS,
+    ALL_ISSUE_TOOL_SUFFIXES,
+    ALLOW_EXIT_CODE,
+    BLOCK_EXIT_CODE,
+    BODY_TEXT_SEPARATOR,
+    CLOSE_DECLARATION_PATTERN,
+    CLOSED_STATE,
+    HANDOFF_CLOSE_MESSAGE,
+    HOOK_EVENT_NAME,
+    RETRY_INSTRUCTION,
+    STATE_KEY,
+    TOOL_INPUT_KEY,
+    TOOL_NAME_KEY,
+)
+from hooks_constants.pre_tool_use_stdin import read_hook_input_dictionary_from_stdin
+
+
+def is_handoff_close(all_tool_input: dict[str, object]) -> bool:
+    """Return True when the call closes an issue and routes a defect elsewhere."""
+    body_text = BODY_TEXT_SEPARATOR.join(extract_mcp_body_texts(all_tool_input))
+    if not any(each_pattern.search(body_text) for each_pattern in ALL_HANDOFF_PATTERNS):
+        return False
+    is_closed_state = all_tool_input.get(STATE_KEY) == CLOSED_STATE
+    return is_closed_state or CLOSE_DECLARATION_PATTERN.search(body_text) is not None
+
+
+def main() -> int:
+    hook_input = read_hook_input_dictionary_from_stdin()
+    if hook_input is None:
+        return ALLOW_EXIT_CODE
+    tool_name = hook_input.get(TOOL_NAME_KEY)
+    if not isinstance(tool_name, str) or not tool_name.endswith(ALL_ISSUE_TOOL_SUFFIXES):
+        return ALLOW_EXIT_CODE
+    tool_input = hook_input.get(TOOL_INPUT_KEY)
+    if not isinstance(tool_input, dict) or not is_handoff_close(tool_input):
+        return ALLOW_EXIT_CODE
+    block_reason = HANDOFF_CLOSE_MESSAGE + RETRY_INSTRUCTION
+    log_hook_block(
+        Path(__file__).name,
+        HOOK_EVENT_NAME,
+        block_reason,
+        tool_name=tool_name,
+        offending_input_preview=str(tool_input),
+    )
+    sys.stderr.write(block_reason)
+    return BLOCK_EXIT_CODE
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/hooks/blocking/test_issue_close_handoff_gate.py

@@ -0,0 +1,126 @@
+import io
+import json
+from pathlib import Path
+
+import pytest
+
+import issue_close_handoff_gate
+
+COMMENT_TOOL_NAME = "mcp__github__add_issue_comment"
+WRITE_TOOL_NAME = "mcp__github__issue_write"
+HANDOFF_CLOSE_BODY = (
+    "## Fresh-session reading: criteria met, issue closed\n\n"
+    "Closing on that basis. Reopen if the comparison matters more.\n\n"
+    "Out of scope here and not attributed: the first prompt still grew by 30k."
+    " The first-prompt growth belongs to #20."
+)
+REOPEN_BODY = (
+    "## Reopened: the reading came before any message\n\n"
+    "The growth after the first message moves the open question to #20 for context."
+    " The issue stays open until the transcript is read."
+)
+
+
+def run_gate(
+    monkeypatch: pytest.MonkeyPatch,
+    capsys: pytest.CaptureFixture[str],
+    tool_name: str,
+    tool_input: dict[str, object],
+) -> tuple[int, str]:
+    hook_input = {
+        "hook_event_name": "PreToolUse",
+        "tool_name": tool_name,
+        "tool_input": tool_input,
+    }
+    monkeypatch.setattr(
+        "sys.stdin", io.TextIOWrapper(io.BytesIO(json.dumps(hook_input).encode("utf-8")))
+    )
+    exit_code = issue_close_handoff_gate.main()
+    return exit_code, capsys.readouterr().err
+
+
+@pytest.fixture(autouse=True)
+def isolated_home(monkeypatch: pytest.MonkeyPatch, tmp_path: Path) -> None:
+    monkeypatch.setenv("HOME", str(tmp_path))
+    monkeypatch.setenv("USERPROFILE", str(tmp_path))
+
+
+def test_should_deny_a_closing_comment_that_routes_the_found_defect_to_another_issue(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    exit_code, stderr_text = run_gate(
+        monkeypatch, capsys, COMMENT_TOOL_NAME, {"issue_number": 10, "body": HANDOFF_CLOSE_BODY}
+    )
+    assert exit_code == 2
+    assert "owns it through the fix pull request" in stderr_text
+
+
+def test_should_deny_a_closed_state_write_whose_comment_hands_the_defect_off(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    exit_code, _ = run_gate(
+        monkeypatch,
+        capsys,
+        WRITE_TOOL_NAME,
+        {"state": "closed", "body": "Done. The leftover growth is tracked in #20."},
+    )
+    assert exit_code == 2
+
+
+def test_should_deny_a_close_that_calls_the_defect_a_separate_finding(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    exit_code, _ = run_gate(
+        monkeypatch,
+        capsys,
+        COMMENT_TOOL_NAME,
+        {"body": "Closing this issue. The jump is a separate finding for the epic."},
+    )
+    assert exit_code == 2
+
+
+def test_should_allow_a_comment_that_routes_work_while_the_issue_stays_open(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    exit_code, stderr_text = run_gate(monkeypatch, capsys, COMMENT_TOOL_NAME, {"body": REOPEN_BODY})
+    assert exit_code == 0
+    assert stderr_text == ""
+
+
+def test_should_allow_a_close_with_a_plain_cross_reference(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    exit_code, _ = run_gate(
+        monkeypatch,
+        capsys,
+        WRITE_TOOL_NAME,
+        {"state": "closed", "body": "Closes #12. #13 tracks the docs."},
+    )
+    assert exit_code == 0
+
+
+def test_should_allow_a_close_with_no_handoff(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    exit_code, _ = run_gate(
+        monkeypatch,
+        capsys,
+        COMMENT_TOOL_NAME,
+        {"body": "Fixed by the merged pull request. Closing this issue."},
+    )
+    assert exit_code == 0
+
+
+def test_should_ignore_tools_outside_the_issue_set(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    exit_code, _ = run_gate(monkeypatch, capsys, "mcp__chat__reply", {"body": HANDOFF_CLOSE_BODY})
+    assert exit_code == 0
+
+
+def test_is_handoff_close_should_need_both_a_close_and_a_handoff() -> None:
+    assert issue_close_handoff_gate.is_handoff_close({"body": HANDOFF_CLOSE_BODY})
+    assert not issue_close_handoff_gate.is_handoff_close({"body": REOPEN_BODY})
+    assert not issue_close_handoff_gate.is_handoff_close(
+        {"state": "closed", "body": "Fixed and verified."}
+    )

package/hooks/features/conduct-gates.md

@@ -6,6 +6,7 @@ This family stops a chat reply, edited message, or tool call when its payload br
 
 - `blocking/reply_length_gate.py` caps chat reply length, denies a configured banned word, and requires a readable link when the text names a pull request number.
 - `blocking/edit_marker_gate.py` rejects strikethrough and edit-note markers in replacement chat text or cards.
+- `blocking/issue_close_handoff_gate.py` denies an issue comment or issue write that closes the issue and routes a found defect to another issue or epic.
 - `blocking/session_title_format_gate.py` denies a session title that breaks the `<emoji> <name>` shape or has a name longer than 25 characters.
 - `blocking/session_title_stop_gate.py` blocks a turn end once when no session title call succeeded in that turn.
 - `blocking/step_note_gate.py` requires a status line before a tool call while its opt-in flag is on.
@@ -16,6 +17,7 @@ This family stops a chat reply, edited message, or tool call when its payload br
 
 - `blocking/reply_length_gate.py` runs on `PreToolUse`, matcher `mcp__hearthbot__reply|mcp__hearthbot__post_message`, timeout `10` seconds in `hooks.json`.
 - `blocking/edit_marker_gate.py` runs on `PreToolUse`, matcher `mcp__.*__update_message`, timeout `10` seconds in `hooks.json`.
+- `blocking/issue_close_handoff_gate.py` runs on `PreToolUse`, matcher `mcp__.*__(add_issue_comment|issue_write|update_issue_comment)`, timeout `10` seconds in `hooks.json`.
 - `blocking/session_title_format_gate.py` runs on `PreToolUse`, matcher `mcp__.*__set_session_title`, timeout `10` seconds in `hooks.json`.
 - `blocking/session_title_stop_gate.py` runs on `Stop`, no matcher, timeout `10` seconds in `hooks.json`.
 - `blocking/step_note_gate.py` runs on `PreToolUse`, matcher `*`, timeout `15` seconds in `hooks.json`.
@@ -30,6 +32,7 @@ Preconditions:
 
 - **Reply length.** Input is a reply with four sentences or a plain pull request number. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_reply_length_gate.py -q`. The adjacent test observes a denial and its count or link reason.
 - **Edit marker.** Input is an update message with strikethrough or an edit note. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_edit_marker_gate.py -q`. The adjacent test observes a denial; clean replacement text passes.
+- **Handoff close.** Input is an issue comment that says the issue is closed and that the found defect belongs to another issue. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_issue_close_handoff_gate.py -q`. The adjacent test observes a denial; a close with a plain cross-reference and a routing comment on an open issue both pass.
 - **Session title.** Input is a set session title call with no leading emoji or a name over 25 characters. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_session_title_format_gate.py -q`. The adjacent test observes a denial that names the broken rule; a well-formed title passes.
 - **Title at turn end.** Input is a remote session transcript whose last turn set no title. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_session_title_stop_gate.py -q`. The adjacent test observes a block; a turn with a successful title call passes.
 - **Step note.** Input is a tool call after a transcript message without a status line while the flag is on. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_step_note_gate.py -q`. The adjacent test observes a block until a status line appears.
@@ -42,4 +45,5 @@ Preconditions:
 - `blocking/verify_before_acting.py` runs after the tool. A block asks the agent to check the claim and undo a contradicted change.
 - The reply gate counts each nonempty list line as a sentence. Link targets and code spans add no words. Its banned words come from `reply-banned-words.json` in the Claude home, or the file `CLAUDE_REPLY_BANNED_WORDS_PATH` names, with built-in defaults.
 - The edit marker gate scans replacement cards as well as the message text.
+- The handoff close gate reads the `body` and `comment` fields of issue tools only. A `gh issue close --comment` command in Bash and a pull request body that closes the issue with `Closes #N` do not reach it.
 - The lifecycle gate counts only invocations after the last compaction, so a compacted session invokes `pr-lifecycle` again. A missing or unreadable transcript allows the call.

package/hooks/hooks.json

@@ -117,6 +117,16 @@
           }
         ]
       },
+      {
+        "matcher": "mcp__.*__(add_issue_comment|issue_write|update_issue_comment)",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/issue_close_handoff_gate.py",
+            "timeout": 10
+          }
+        ]
+      },
       {
         "matcher": "mcp__.*__set_session_title",
         "hooks": [

package/hooks/hooks_constants/advisor_rules_prompt_constants.py

@@ -37,6 +37,7 @@ ALL_ADVISOR_RULE_SENTENCES = (
     "This cadence guides planning and leaves the task free to follow its evidence.",
     "Short reactive tasks may use the single consult that best fits the live decision.",
     "Ask the advisor to hunt for missing requirements, untested behavior, wrong assumptions, unhandled edge cases, evidence gaps, and early completion claims.",
+    "A defect the task found in its own subject stays with the task through its fix pull request, so a close that routes that defect to another issue or epic is an early completion claim.",
     "Give the advice serious weight.",
 )
 

package/hooks/hooks_constants/issue_close_handoff_gate_constants.py

@@ -0,0 +1,46 @@
+"""Constants for the issue close handoff gate PreToolUse hook."""
+
+import re
+
+ALL_ISSUE_TOOL_SUFFIXES: tuple[str, ...] = (
+    "add_issue_comment",
+    "issue_write",
+    "update_issue_comment",
+)
+TOOL_NAME_KEY = "tool_name"
+TOOL_INPUT_KEY = "tool_input"
+STATE_KEY = "state"
+CLOSED_STATE = "closed"
+HOOK_EVENT_NAME = "PreToolUse"
+ALLOW_EXIT_CODE = 0
+BLOCK_EXIT_CODE = 2
+BODY_TEXT_SEPARATOR = "\n"
+ISSUE_REFERENCE = r"(?:#|\bissue\s+)\d+"
+CLOSE_DECLARATION_PATTERN = re.compile(
+    r"\b(?:clos(?:e|es|ed|ing)\s+(?:this|the|it|on|now|issue)\b"
+    r"|issue\s+(?:is\s+)?closed\b)",
+    re.IGNORECASE,
+)
+ALL_HANDOFF_PATTERNS: tuple[re.Pattern[str], ...] = (
+    re.compile(rf"\bbelongs?\s+(?:to|in|with|under)\s+{ISSUE_REFERENCE}", re.IGNORECASE),
+    re.compile(
+        rf"\b(?:rout(?:e|es|ed|ing)|hand(?:s|ed|ing)?\s+off|mov(?:e|es|ed|ing)"
+        rf"|defer(?:s|red|ring)?|punt(?:s|ed|ing)?)\b[^.\n]{{0,80}}?\bto\s+{ISSUE_REFERENCE}",
+        re.IGNORECASE,
+    ),
+    re.compile(
+        rf"\b(?:tracked|handled|owned|covered|continues)\s+(?:in|by|under)\s+{ISSUE_REFERENCE}",
+        re.IGNORECASE,
+    ),
+    re.compile(r"\bseparate\s+finding\b", re.IGNORECASE),
+)
+HANDOFF_CLOSE_MESSAGE = (
+    "This close hands a defect found in the issue's subject to another issue."
+    " The session that found the defect owns it through the fix pull request."
+    " Keep this issue open, fix the defect, and close the issue through that"
+    " pull request."
+)
+RETRY_INSTRUCTION = (
+    " When the other issue owned the work before this issue found it, link it"
+    " as related in a post that does not close this issue."
+)

package/hooks/hooks_constants/test_issue_close_handoff_gate_constants.py

@@ -0,0 +1,17 @@
+from hooks_constants import issue_close_handoff_gate_constants as constants
+
+
+def test_gate_checks_every_issue_comment_and_write_tool() -> None:
+    assert constants.ALL_ISSUE_TOOL_SUFFIXES == (
+        "add_issue_comment",
+        "issue_write",
+        "update_issue_comment",
+    )
+
+
+def test_gate_exit_codes_match_the_hook_contract() -> None:
+    assert (constants.ALLOW_EXIT_CODE, constants.BLOCK_EXIT_CODE) == (0, 2)
+
+
+def test_close_declaration_skips_a_reopen_heading() -> None:
+    assert constants.CLOSE_DECLARATION_PATTERN.search("## Reopened: the reading") is None

package/package.json

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

package/scripts/policy_lint/adapter_configuration.py

@@ -131,6 +131,7 @@ def _names_exempt_registration_path(registered_string: str) -> bool:
         hooks/blocking/step_note_gate.py                 -> exempt
         hooks/blocking/reply_length_gate.py              -> exempt
         hooks/blocking/edit_marker_gate.py               -> exempt
+        hooks/blocking/issue_close_handoff_gate.py       -> exempt
         hooks/blocking/verify_before_acting.py           -> exempt
         hooks/blocking/session_title_format_gate.py      -> exempt
         hooks/blocking/session_title_stop_gate.py        -> exempt

package/scripts/policy_lint/config/constants.py

@@ -67,6 +67,7 @@ ALL_ACTION_BOUNDARY_EXEMPT_REGISTRATION_PATHS = (
     "blocking/step_note_gate.py",
     "blocking/reply_length_gate.py",
     "blocking/edit_marker_gate.py",
+    "blocking/issue_close_handoff_gate.py",
     "blocking/verify_before_acting.py",
     "blocking/session_title_format_gate.py",
     "blocking/session_title_stop_gate.py",

package/scripts/tests/test_adapter_configuration.py

@@ -82,6 +82,14 @@ def test_new_edit_marker_gate_registration_is_clean(tmp_path: Path) -> None:
     assert adapters.hook_configuration_diagnostics(current_document, tmp_path) == ()
 
 
+def test_new_issue_close_handoff_gate_registration_is_clean(tmp_path: Path) -> None:
+    current_document = _hook_document(
+        ["hooks/blocking/issue_close_handoff_gate.py"],
+        '{"hooks": {}}',
+    )
+    assert adapters.hook_configuration_diagnostics(current_document, tmp_path) == ()
+
+
 def test_new_verify_before_acting_registration_is_clean(tmp_path: Path) -> None:
     current_document = _hook_document(
         ["hooks/blocking/verify_before_acting.py"],