claude-dev-env 8.96.3 → 8.96.5

package/.agents/skills/pr-lifecycle/SKILL.md

@@ -24,7 +24,7 @@ User-level rule: applies to **every** git repo that uses GitHub with `gh`. Small
 
 **Prove the change where it runs before opening a PR.** Read `~/.claude/docs/rule-guides/proof-before-pull-request.md` for the body and hook requirements. A `feat` PR also needs an "Eval" section and a session that invoked `/claude-api build-eval`; read `~/.claude/docs/rule-guides/features-start-with-an-eval.md` before you build the feature.
 
-**Open PRs ready for review; use `--draft` when the owner requests it.** Before you commit copied files or open a PR, search open PRs for the same paths with `gh pr list --search "<path>"`, so you do not duplicate a peer's PR. Each pre-existing failure or remaining defect the PR body names links a tracked issue.
+**Open PRs ready for review; use `--draft` when the owner requests it.** Before you commit copied files or open a PR, list the open PRs that change a file whose path starts with yours, then read each hit, with `gh pr list --state open --limit 1000 --json number,files --jq '.[] | select(any(.files[]; .path | startswith("<path>"))) | .number'`, so you do not duplicate a peer's PR. Each pre-existing failure or remaining defect the PR body names links a tracked issue.
 
 **A release bot's PR body is machine input. Leave it alone.** Release automation reads
 back the body of its own merged pull request to decide it owns that merge. Rewriting the

package/.agents/skills/pull-request/SKILL.md

@@ -81,9 +81,10 @@ draft. Record the target before any write.
 
 ### 2. Author the title and body
 
-For create and full body rewrite, write the title and a body file, or invoke
-`pstack:poteto-agent` with the diff-specific writing instructions to draft
-them. A comment or
+For create, run `pull_request.py template --body-file <path> --title <title>`
+first. It appends each heading the linter and proof gate require that the file
+lacks. Then fill the body, or invoke `pstack:poteto-agent` with the
+diff-specific writing instructions to draft it. A comment or
 review may use a supplied body file when it does not rewrite the pull request
 description.
 

package/.agents/skills/pull-request/scripts/github_pr_command_constants/config/constants.py

@@ -6,6 +6,20 @@ ACTION_COMMENT = "comment"
 ACTION_CREATE = "create"
 ACTION_EDIT = "edit"
 ACTION_REVIEW = "review"
+ACTION_TEMPLATE = "template"
+
+ALL_BODY_TEMPLATE_HEADINGS: tuple[str, ...] = (
+    "Why",
+    "Existing work",
+    "Proof in practice",
+    "Verification",
+)
+FEATURE_BODY_TEMPLATE_HEADING = "Eval"
+FEATURE_TITLE_PATTERN: re.Pattern[str] = re.compile(r"^\s*feat(\([^)]*\))?!?:")
+BODY_TEMPLATE_HEADING_FORMAT = "## {heading}"
+BODY_TEMPLATE_ENCODING = "utf-8"
+BODY_TEMPLATE_LINE_END = "\n"
+BODY_TEMPLATE_BLOCK_SEPARATOR = "\n\n"
 
 LINTER_ACTION_COMMENT = "pr-comment"
 LINTER_ACTION_CREATE = "pr-create"

package/.agents/skills/pull-request/scripts/pull_request.py

@@ -18,7 +18,15 @@ from github_pr_command_constants.config.constants import (
     ACTION_EDIT,
     ACTION_FAILED_MESSAGE,
     ACTION_REVIEW,
+    ACTION_TEMPLATE,
+    ALL_BODY_TEMPLATE_HEADINGS,
     ALL_DURABLE_POST_LINTER_RELATIVE_PATH_PARTS,
+    BODY_TEMPLATE_BLOCK_SEPARATOR,
+    BODY_TEMPLATE_ENCODING,
+    BODY_TEMPLATE_HEADING_FORMAT,
+    BODY_TEMPLATE_LINE_END,
+    FEATURE_BODY_TEMPLATE_HEADING,
+    FEATURE_TITLE_PATTERN,
     ALL_GITHUB_AUTHORIZATION_ENVIRONMENT_KEYS,
     ALL_LINTER_ACTIONS_BY_COMMAND,
     ALL_REVIEW_FLAGS_BY_EVENT,
@@ -62,9 +70,53 @@ def _build_parser() -> argparse.ArgumentParser:
         choices=tuple(ALL_REVIEW_FLAGS_BY_EVENT),
         default=REVIEW_EVENT_COMMENT,
     )
+    template = all_actions.add_parser(ACTION_TEMPLATE, allow_abbrev=False)
+    template.add_argument("--body-file", required=True, type=Path)
+    template.add_argument("--title", default="")
     return parser
 
 
+def _template_headings(title: str) -> list[str]:
+    all_headings = [
+        BODY_TEMPLATE_HEADING_FORMAT.format(heading=each_heading)
+        for each_heading in ALL_BODY_TEMPLATE_HEADINGS
+    ]
+    if FEATURE_TITLE_PATTERN.match(title):
+        all_headings.append(BODY_TEMPLATE_HEADING_FORMAT.format(heading=FEATURE_BODY_TEMPLATE_HEADING))
+    return all_headings
+
+
+def write_body_template(body_file: Path, title: str) -> list[str]:
+    """Append each required heading the body file lacks and return the added headings.
+
+    ::
+
+        new file, title "fix: x"   -> ["## Why", "## Existing work", "## Proof in practice", "## Verification"]
+        new file, title "feat: x"  -> the same plus "## Eval"
+        file already has them all  -> [] and the file is unchanged
+
+    Args:
+        body_file: The pull request body file, created when absent.
+        title: The pull request title, which decides whether the Eval heading is required.
+
+    Returns:
+        The heading lines appended to the file.
+    """
+    body_text = body_file.read_text(encoding=BODY_TEMPLATE_ENCODING) if body_file.is_file() else ""
+    all_present_lines = {each_line.strip() for each_line in body_text.splitlines()}
+    all_missing_headings = [
+        each_heading for each_heading in _template_headings(title) if each_heading not in all_present_lines
+    ]
+    if not all_missing_headings:
+        return []
+    all_body_blocks = [body_text.rstrip(), *all_missing_headings] if body_text.strip() else all_missing_headings
+    body_file.write_text(
+        BODY_TEMPLATE_BLOCK_SEPARATOR.join(all_body_blocks) + BODY_TEMPLATE_LINE_END,
+        encoding=BODY_TEMPLATE_ENCODING,
+    )
+    return all_missing_headings
+
+
 def _configured_managed_root(all_environment: Mapping[str, str]) -> Path:
     configured_root_text = all_environment.get(CONFIG_DIR_OVERRIDE_ENVIRONMENT_KEY, "").strip()
     if not configured_root_text:
@@ -253,6 +305,10 @@ def main(
 ) -> int:
     """Run one validated pull request action."""
     arguments = _build_parser().parse_args(list(all_arguments))
+    if arguments.action == ACTION_TEMPLATE:
+        for each_heading in write_body_template(arguments.body_file, arguments.title):
+            sys.stdout.write(each_heading + "\n")
+        return 0
     completed_lint = command_runner(
         _linter_arguments(arguments, all_environment), check=False, shell=False
     )

package/.agents/skills/pull-request/scripts/test_pull_request.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import os
+import re
 import subprocess
 import sys
 import threading
@@ -462,3 +463,84 @@ def should_hand_the_head_branch_to_the_linter_on_create(body_file: Path) -> None
         linter_command[linter_command.index("--head-branch") + 1]
         == "release-please--branches--main--components--package"
     )
+
+
+PROOF_CONSTANTS_PATH = (
+    _SCRIPTS_DIRECTORY.parents[3] / "hooks/hooks_constants/pull_request_proof_constants.py"
+)
+
+
+def _proof_heading_patterns() -> dict[str, str]:
+    constants_text = PROOF_CONSTANTS_PATH.read_text(encoding="utf-8")
+    all_names = ("PROOF_HEADING_PATTERN", "EXISTING_WORK_HEADING_PATTERN", "EVAL_HEADING_PATTERN")
+    all_patterns: dict[str, str] = {}
+    for each_line in constants_text.splitlines():
+        each_name, _, each_value = each_line.partition(" = ")
+        if each_name in all_names:
+            all_patterns[each_name] = each_value.strip()[2:-1]
+    return all_patterns
+
+
+def _run_template(body_path: Path, title: str) -> tuple[int, Mock]:
+    command_runner = Mock()
+    exit_code = pull_request.main(
+        ["template", "--body-file", str(body_path), "--title", title],
+        all_environment={},
+        command_runner=command_runner,
+    )
+    return exit_code, command_runner
+
+
+def _body_has_heading(body_text: str, heading_pattern: str) -> bool:
+    return any(
+        re.match(heading_pattern, each_line.strip(), re.IGNORECASE)
+        for each_line in body_text.splitlines()
+    )
+
+
+def should_write_a_template_that_clears_the_linter_and_proof_headings(tmp_path: Path) -> None:
+    body_path = tmp_path / BODY_FILENAME
+    exit_code, command_runner = _run_template(body_path, PR_TITLE)
+    body_text = body_path.read_text(encoding="utf-8")
+    lint = subprocess.run(
+        [
+            sys.executable,
+            str(LINTER_PATH),
+            "--action",
+            "pr-create",
+            "--title",
+            PR_TITLE,
+            "--body-file",
+            str(body_path),
+            "--repository",
+            REPOSITORY,
+        ],
+        capture_output=True,
+        check=False,
+        text=True,
+    )
+    assert exit_code == 0
+    assert command_runner.call_count == 0
+    assert "missing-pr-description-heading" not in lint.stdout + lint.stderr
+    assert all(
+        _body_has_heading(body_text, each_pattern)
+        for each_pattern in _proof_heading_patterns().values()
+    )
+
+
+def should_add_the_eval_heading_only_for_a_feature_title(tmp_path: Path) -> None:
+    fix_body_path = tmp_path / "fix.md"
+    _run_template(fix_body_path, "fix(hooks): narrow the gate")
+    eval_pattern = _proof_heading_patterns()["EVAL_HEADING_PATTERN"]
+    assert not _body_has_heading(fix_body_path.read_text(encoding="utf-8"), eval_pattern)
+
+
+def should_keep_written_text_and_add_only_missing_headings(tmp_path: Path) -> None:
+    body_path = tmp_path / BODY_FILENAME
+    body_path.write_text("## Why\nThe gate bounced twice.\n", encoding="utf-8")
+    _run_template(body_path, PR_TITLE)
+    first_text = body_path.read_text(encoding="utf-8")
+    _run_template(body_path, PR_TITLE)
+    assert first_text.startswith("## Why\nThe gate bounced twice.\n")
+    assert first_text.count("## Why") == 1
+    assert body_path.read_text(encoding="utf-8") == first_text

package/docs/rule-guides/session-title.md

@@ -31,4 +31,4 @@ The name has 25 characters or fewer and names the main change or outcome in conc
 
 ## Enforcement
 
-`hooks/blocking/session_title_format_gate.py` denies a malformed title. `hooks/blocking/session_title_turn_gate.py` is a Stop hook. It holds the end of a turn until a title call in that turn comes back without an error. It applies when the transcript shows the title tool. A held turn whose title call failed may end, so a failing title tool cannot hold it forever.
+`hooks/blocking/session_title_format_gate.py` denies a malformed title. `hooks/blocking/session_title_turn_gate.py` is a Stop hook. It holds the end of a turn until a title call in that turn comes back without an error. A turn that called no tool other than the title tool may end when an earlier turn already set the title. It applies when the transcript shows the title tool. A held turn whose title call failed may end, so a failing title tool cannot hold it forever.

package/hooks/blocking/session_title_turn_gate.py

@@ -7,9 +7,12 @@ a Stop hook block lands as an attachment, so a held turn stays the same turn.
 A title call on a sidechain entry belongs to a subagent and does not count.
 The turn may end once a tool whose name ends in __set_session_title ran in it
 and its result came back without an error. A title the format gate denied
-does not count. A held turn (``stop_hook_active`` true) whose title call
-failed may end, so a title tool that keeps failing cannot hold it forever. A
-held turn with no title call stays held, whichever Stop gate held it.
+does not count. A turn that called no tool other than the title tool may also
+end once an earlier main-chain turn set the title, since that title still
+shows and a text-only turn starts no new task. A held turn
+(``stop_hook_active`` true) whose title call failed may end, so a title tool
+that keeps failing cannot hold it forever. A held turn with no title call
+stays held, whichever Stop gate held it.
 
 The session has the title tool when a transcript record names it::
 
@@ -153,8 +156,8 @@ def _apply_tool_listing(
         all_available_names.pop(each_removed_name, None)
 
 
-def _turn_entries(all_entries: list[dict[str, object]]) -> list[dict[str, object]]:
-    last_prompt_index = max(
+def _last_prompt_index(all_entries: list[dict[str, object]]) -> int:
+    return max(
         (
             each_index
             for each_index, each_entry in enumerate(all_entries)
@@ -162,11 +165,18 @@ def _turn_entries(all_entries: list[dict[str, object]]) -> list[dict[str, object
         ),
         default=-1,
     )
-    return [
-        each_entry
-        for each_entry in all_entries[last_prompt_index + 1 :]
-        if not each_entry.get(SIDECHAIN_FLAG_KEY)
-    ]
+
+
+def _main_chain(all_entries: list[dict[str, object]]) -> list[dict[str, object]]:
+    return [each_entry for each_entry in all_entries if not each_entry.get(SIDECHAIN_FLAG_KEY)]
+
+
+def _turn_entries(all_entries: list[dict[str, object]]) -> list[dict[str, object]]:
+    return _main_chain(all_entries[_last_prompt_index(all_entries) + 1 :])
+
+
+def _earlier_entries(all_entries: list[dict[str, object]]) -> list[dict[str, object]]:
+    return _main_chain(all_entries[: max(_last_prompt_index(all_entries), 0)])
 
 
 def _title_call_ids(all_turn_entries: list[dict[str, object]]) -> set[object]:
@@ -205,13 +215,44 @@ def title_set_this_turn(all_entries: list[dict[str, object]]) -> bool:
     Returns:
         True when this turn set the title.
     """
-    all_turn_entries = _turn_entries(all_entries)
-    all_title_call_ids = _title_call_ids(all_turn_entries)
+    return _title_succeeded_in(_turn_entries(all_entries))
+
+
+def title_set_before_this_turn(all_entries: list[dict[str, object]]) -> bool:
+    """Return True when a main-chain title call before the latest prompt came back without an error.
+
+    Args:
+        all_entries: The transcript entries, oldest first.
+
+    Returns:
+        True when an earlier turn set the title the session still shows.
+    """
+    return _title_succeeded_in(_earlier_entries(all_entries))
+
+
+def turn_ran_a_tool(all_entries: list[dict[str, object]]) -> bool:
+    """Return True when this turn called any tool other than the title tool.
+
+    Args:
+        all_entries: The transcript entries, oldest first.
+
+    Returns:
+        True when the turn did work beyond answering in text.
+    """
+    return any(
+        not TITLE_TOOL_NAME_PATTERN.match(str(each_block.get(BLOCK_NAME_KEY)))
+        for each_entry in _turn_entries(all_entries)
+        for each_block in _tool_use_blocks(each_entry)
+    )
+
+
+def _title_succeeded_in(all_scoped_entries: list[dict[str, object]]) -> bool:
+    all_title_call_ids = _title_call_ids(all_scoped_entries)
     return any(
         each_block.get(ENTRY_TYPE_KEY) == TOOL_RESULT_BLOCK_TYPE
         and each_block.get(TOOL_USE_ID_KEY) in all_title_call_ids
         and not each_block.get(IS_ERROR_KEY)
-        for each_entry in all_turn_entries
+        for each_entry in all_scoped_entries
         if each_entry.get(ENTRY_TYPE_KEY) == USER_ENTRY_TYPE
         for each_block in _content_blocks(each_entry)
     )
@@ -226,6 +267,7 @@ def turn_block_reason(
 
         no title tool in the transcript                         -> None
         title set this turn                                     -> None
+        only title calls this turn, earlier turn set the title  -> None
         held turn whose title call failed (stop_hook_active)    -> None
         no title call this turn                                 -> reason
 
@@ -239,6 +281,8 @@ def turn_block_reason(
     all_title_tools = available_title_tools(all_entries)
     if not all_title_tools or title_set_this_turn(all_entries):
         return None
+    if title_set_before_this_turn(all_entries) and not turn_ran_a_tool(all_entries):
+        return None
     if is_stop_hook_active and title_attempted_this_turn(all_entries):
         return None
     return TURN_BLOCK_REASON.format(tool_name=TITLE_TOOL_DISPLAY_SEPARATOR.join(all_title_tools))

package/hooks/blocking/test_session_title_turn_gate.py

@@ -167,6 +167,53 @@ def test_should_hold_when_the_title_was_set_only_in_an_earlier_turn(
     assert block_output["decision"] == "block"
 
 
+@pytest.mark.parametrize(
+    "all_turn_tail",
+    [
+        [REPLY],
+        [title_call("t2"), title_result("t2", is_error=True), REPLY],
+    ],
+)
+def test_should_pass_a_tool_free_turn_after_an_earlier_title(
+    monkeypatch: pytest.MonkeyPatch,
+    capsys: pytest.CaptureFixture[str],
+    tmp_path: Path,
+    all_turn_tail: list[dict[str, object]],
+) -> None:
+    all_entries = [
+        TOOL_LISTING,
+        PROMPT,
+        title_call("t1"),
+        title_result("t1"),
+        REPLY,
+        PROMPT,
+        *all_turn_tail,
+    ]
+    assert run_gate(monkeypatch, capsys, tmp_path, all_entries) == (0, "")
+
+
+@pytest.mark.parametrize(
+    "all_earlier_title_entries",
+    [
+        [],
+        [title_call("t1"), title_result("t1", is_error=True)],
+        [
+            {**title_call("s1"), "isSidechain": True},
+            {**title_result("s1"), "isSidechain": True},
+        ],
+    ],
+)
+def test_should_hold_a_tool_free_turn_without_an_earlier_title(
+    monkeypatch: pytest.MonkeyPatch,
+    capsys: pytest.CaptureFixture[str],
+    tmp_path: Path,
+    all_earlier_title_entries: list[dict[str, object]],
+) -> None:
+    all_entries = [TOOL_LISTING, PROMPT, *all_earlier_title_entries, REPLY, PROMPT, REPLY]
+    stdout_text = run_gate(monkeypatch, capsys, tmp_path, all_entries)[1]
+    assert json.loads(stdout_text)["decision"] == "block"
+
+
 def test_should_start_a_turn_at_an_image_only_prompt(
     monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str], tmp_path: Path
 ) -> None:
@@ -181,6 +228,8 @@ def test_should_start_a_turn_at_an_image_only_prompt(
         title_result("t1"),
         REPLY,
         image_prompt,
+        WORK_CALL,
+        WORK_RESULT,
         REPLY,
     ]
     stdout_text = run_gate(monkeypatch, capsys, tmp_path, all_entries)[1]

package/hooks/features/conduct-gates.md

@@ -12,7 +12,7 @@ This family stops a chat reply, edited message, or tool call when its payload br
 - `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_turn_gate.py` holds the end of a turn in a session that has a `__set_session_title` tool until a title call in that turn comes back without an error. A held turn whose title call failed may end.
+- `blocking/session_title_turn_gate.py` holds the end of a turn in a session that has a `__set_session_title` tool until a title call in that turn comes back without an error. A turn that called no tool other than the title tool may end when an earlier turn already set the title. A held turn whose title call failed may end.
 - `blocking/step_note_gate.py` requires a status line before a tool call while its opt-in flag is on.
 - `blocking/verify_before_acting.py` blocks a completed mutating call when the agent's reasoning contains an unchecked claim.
 - `blocking/pr_lifecycle_skill_gate.py` denies a commit, push, pull request action, or merge until the `pr-lifecycle` skill appears in the transcript since the last compaction.

package/package.json

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