claude-dev-env 8.57.0 → 8.59.0

package/.agents/skills/correction/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: correction
+description: Turn a correction the user just made into a short handoff brief they paste into a corrections intake. Use when the user types /correction followed by what the agent got wrong.
+argument-hint: "<what the agent got wrong, in the user's words>"
+---
+
+# /correction
+
+The user corrected an agent and wants the fix to stick. Write one brief they can paste into the place that turns corrections into lasting fixes.
+
+`$ARGUMENTS` is the user's statement of the correction. Fill the other fields from this session: the transcript, the files and pull requests it touched, and the messages it sent. When the session does not settle a field, write `unknown` there.
+
+Print the brief as one fenced `text` block, and nothing after it:
+
+```text
+Correction: <$ARGUMENTS, word for word>
+Asked: <what the user asked for, quoted where a message carries it>
+Agent did: <what the agent did, with the reply, file, or command that shows it>
+Corrected to: <what the user wanted instead, or the fix already made>
+Where: <repository, branch or pull request, files, tool, or thread>
+Evidence: <file:line, log line, or quoted message that shows the miss>
+Repeat: <yes, with the earlier time it happened | no | unknown>
+```
+
+Keep each field to one or two lines. Leave out the layer and the fix design; the intake decides those.

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/bin/ever-shipped-skills.mjs

@@ -21,6 +21,7 @@ export const EVER_SHIPPED_SKILL_NAMES = new Set([
     'context7-mcp',
     'copilot-finding-triage',
     'copilot-review',
+    'correction',
     'deep-research',
     'descriptions',
     'e-code-review',

package/bin/ever-shipped-skills.test.mjs

@@ -41,6 +41,10 @@ test('EVER_SHIPPED_SKILL_NAMES includes the pull request lifecycle skill', () =>
     assert.equal(EVER_SHIPPED_SKILL_NAMES.has('pr-lifecycle'), true);
 });
 
+test('EVER_SHIPPED_SKILL_NAMES includes the correction skill', () => {
+    assert.equal(EVER_SHIPPED_SKILL_NAMES.has('correction'), true);
+});
+
 test('EVER_SHIPPED_SKILL_NAMES includes the windows scheduled task skill', () => {
     assert.equal(EVER_SHIPPED_SKILL_NAMES.has('windows-scheduled-task'), true);
 });

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/docs/templates/artifact-page/README.md

@@ -16,7 +16,7 @@
 | Readable text | Text is 16px or larger and uses the full text color. Gray stays on lines and borders only. Text holds a 7:1 contrast ratio against its background. |
 | Touch targets | Buttons and chips are 40px or taller, with a visible focus ring. |
 | Copy fallback | The copy button uses the clipboard API and falls back to a hidden text area, then says when the copy is blocked. |
-| Review rounds | Parts changed since the viewer's last look carry a thin bar on their left edge, and changed cards a "Changed" label. [review-rounds.md](review-rounds.md) holds the data fields and behavior. |
+| Review rounds | Only the parts changed since the viewer's last look carry a thin bar and a "Changed" label. [review-rounds.md](review-rounds.md) holds the data fields and behavior. |
 
 ## House rules for a page built from it
 
@@ -24,3 +24,13 @@
 - A page that needs extra files publishes them beside the page through the Artifact `files` field, and links them by relative path.
 - A page that needs live data or saved answers declares the matching runtime capability. `localStorage` holds only per-viewer conveniences.
 - Render the page at 400px in light and dark, and exercise every control, before publishing.
+
+## Convert an existing page
+
+Ask an agent: "convert <artifact link> to our format."
+
+1. Read the published page with the Artifact tool's `read` action, and keep its data and every working control.
+2. Map each part to its piece in `template.html`: status groups to board lanes, records to picture cards, filters to tabs and chips, and the data to the JSON data block.
+3. Apply the house rules above and the template's color tokens.
+4. Check that text is 16px or larger, text contrast is 7:1 or better, and the page has no horizontal scroll at 390px, in light and dark.
+5. Publish to the same link as a new version, so the reviewer keeps one URL.

package/docs/templates/artifact-page/review-rounds.md

@@ -1,6 +1,6 @@
 # Marking what changed between review rounds
 
-A page that a reviewer reads more than once shows what changed since their last look. The template marks each changed card and each changed part with a thin bar on its left edge, gives each changed card a small "Changed" label, and gives each changed board chip a dot in the same color. There is no diff and no list of changes.
+A page that a reviewer reads more than once shows what changed since their last look. The template marks only the parts that changed: each one gets a thin bar on its left edge and a small "Changed" label at its start. The card around them stays as it is, and its board chip gets a dot in the same color. There is no diff and no list of changes.
 
 ## Data
 
@@ -8,7 +8,7 @@ A page that a reviewer reads more than once shows what changed since their last
 |---|---|---|
 | `round` | top of the data block | The review round this revision answers. Add one each time the page is republished after feedback. |
 | `changed_round` | an item | The round in which this item last changed. |
-| `changed_parts` | an item, optional | The parts that changed: `title`, `next`, `summary`, `steps`, `links`. With no list, only the card is marked. |
+| `changed_parts` | an item | The parts that changed: `title`, `next`, `summary`, `steps`, `links`. An item with no list gets no mark. |
 
 When a revision answers feedback, set `round` to the new number and stamp each item it changed with that number and the parts it touched. Leave older stamps in place; they stop showing once the reviewer has seen their round.
 
@@ -21,6 +21,6 @@ When a revision answers feedback, set `round` to the new number and stamp each i
 
 ## Other pages
 
-Any element with `data-changed-round="N"` takes the bar. An element that holds a `data-change-slot` child gets the "Changed" label in that child; other elements get a screen reader label.
+Stamp the smallest element that changed with `data-changed-round="N"`; it takes the bar and the "Changed" label, and a `<details>` element takes the label in its summary. Never stamp a whole card or section. An element with `data-change-mark="dot"` takes the dot and a screen reader label in place of the bar and label.
 
 The `--change` and `--change-ink` tokens hold the mark colors in light and dark. Keep the label text at 7:1 or better against `--change`, and the bar at 3:1 or better against `--surface` and `--bg`.

package/docs/templates/artifact-page/template.html

@@ -100,12 +100,9 @@ details.what[open] summary::before { content: "▾" }
 .step .num { flex: none; width: 30px; height: 30px; border-radius: 50%; background: var(--warn); color: var(--surface); display: grid; place-items: center; font-weight: 800 }
 .lchip.changed::before { content: ""; width: 10px; height: 10px; border-radius: 50%; background: var(--change); flex: none }
 .changed { box-shadow: inset 4px 0 0 var(--change); padding-left: 12px; border-radius: 4px }
-.card.changed { box-shadow: inset 6px 0 0 var(--change); padding-left: 0; border-radius: 16px }
-.card.changed .band, .card.changed > .body { padding-left: 18px }
-.card.changed .body .changed { padding-left: 12px }
 .next.changed { border-radius: 12px }
 .lchip.changed { box-shadow: none; border-radius: 999px; padding-left: 10px; border-color: var(--change); display: inline-flex; align-items: center; gap: 6px }
-.pill-changed { display: inline-flex; align-items: center; min-height: 28px; padding: 0 10px; border-radius: 999px; background: var(--change); color: var(--change-ink); font-size: 16px; font-weight: 800 }
+.pill-changed { display: inline-flex; align-items: center; min-height: 28px; padding: 0 10px; border-radius: 999px; background: var(--change); color: var(--change-ink); font-size: 16px; font-weight: 800; margin-right: 8px; vertical-align: middle; flex: none; white-space: nowrap }
 .sr { position: absolute; width: 1px; height: 1px; overflow: hidden; clip-path: inset(50%); white-space: nowrap }
 .empty { background: var(--surface); border: 2px dashed var(--edge); border-radius: 14px; padding: 20px; font-weight: 600 }
 @media (hover: hover) { .lchip:hover, .fchip:hover, .tab:hover, .copy:hover { border-color: var(--accent) } }
@@ -336,17 +333,16 @@ function changeBaseline() {
   return baseline;
 }
 function stampChange(node, it, part) {
-  if (it.changed_round && (!part || [].concat(it.changed_parts || []).includes(part))) node.dataset.changedRound = it.changed_round;
+  const parts = [].concat(it.changed_parts || []);
+  if (it.changed_round && (part ? parts.includes(part) : parts.length)) node.dataset.changedRound = it.changed_round;
   return node;
 }
 function markChanges() {
   for (const node of document.querySelectorAll("[data-changed-round]")) {
     if (Number(node.dataset.changedRound) <= CHANGE_BASELINE || node.classList.contains("changed")) continue;
     node.classList.add("changed");
-    const slot = node.querySelector("[data-change-slot]");
-    if (slot) { slot.prepend(el("span", "pill-changed", "Changed")); continue; }
     const label = node.querySelector(":scope > summary") || node;
-    label.prepend(el("span", "sr", "Changed. "));
+    label.prepend(node.dataset.changeMark === "dot" ? el("span", "sr", "Changed. ") : el("span", "pill-changed", "Changed"));
   }
 }
 function save() { try { localStorage.setItem("work-tracker-view", JSON.stringify({ tab: state.tab, owner: state.owner })); } catch (e) {} }
@@ -379,6 +375,7 @@ function renderBoard(items) {
       const chips = el("div", "lchips");
       for (const it of mine) {
         const b = stampChange(el("button", "lchip", it.title), it);
+        b.dataset.changeMark = "dot";
         b.setAttribute("aria-label", "Go to " + it.title);
         b.onclick = () => jumpTo(it);
         chips.append(b);
@@ -438,10 +435,9 @@ function copyButton(it) {
 }
 function itemCard(it) {
   const key = stageOf(it), s = STAGE_BY_KEY[key], owner = ownerByKey[it.owner] || { name: it.owner };
-  const card = stampChange(el("article", "card " + key), it);
+  const card = el("article", "card " + key);
   card.id = slug(it);
   const band = el("div", "band " + key);
-  band.dataset.changeSlot = "";
   band.append(el("span", null, s.icon), el("span", null, s.label));
   const proj = el("span", "proj");
   proj.append(el("span", null, (owner.icon || "📁")), el("span", null, owner.name));

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.57.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"],