claude-dev-env 8.60.0 → 8.61.0

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

@@ -22,6 +22,11 @@ User-level rule: applies to **every** git repo that uses GitHub with `gh`. Small
 
 ### Pull request submission rules
 
+**Prove the change where it runs before you open the pull request.** The body carries a
+"Proof in practice" section with each command you ran and its quoted output. A hook denies
+a new pull request without one. Read `~/.claude/docs/rule-guides/proof-before-pull-request.md`
+before you plan the proof run.
+
 **Open every pull request ready for review.** Pass `--draft` only when the owner asks
 for a draft.
 

package/bin/merge_profile_settings.mjs

@@ -65,6 +65,12 @@ export const DECLARED_PROFILE_SETTINGS = Object.freeze([
                 + '(mcp__claude-code-remote__set_session_title or mcp__ccd_session_mgmt__set_session_title) is allowed, '
                 + 'and so is a live test run of the account broker with '
                 + '`python ~/.claude/scripts/account_broker.py run`: the user installed both tools for these sessions',
+            'Moving instruction files out of the always-loaded rules folder of a Claude config directory '
+                + '(`~/.claude/rules` or a profile\'s `rules` folder) into a sibling on-demand folder in the same '
+                + 'config directory, and moving them back, is allowed when the task is to trim session-start context: '
+                + 'each file keeps its contents and stays on disk, and the move reverses with one more move. '
+                + 'This covers a plain move or rename with an index file that says when to open each moved file. '
+                + 'It does not cover deleting or editing a rule, or any change to settings, hooks or permissions.',
         ],
     },
 ]);

package/docs/rule-guides/proof-before-pull-request.md

@@ -0,0 +1,37 @@
+Back to the [rule entry](../../rules/proof-before-pull-request.md).
+
+# Proof before a pull request
+
+**When this applies:** Every session that builds a change and opens a pull request, in every project.
+
+## Rule
+
+Before you open a pull request, prove the change does its job where it will run.
+
+What counts as proof:
+- You ran the changed thing the way its user runs it, and you saw the effect it exists to produce. A hook fires in a live Claude Code session and changes what that session does. A script runs from its launcher on inputs like the ones it will meet. A skill or rule changes what a fresh agent does with an ordinary request.
+- You saw the failure first. Run the same scenario without your change and record what goes wrong. The proof is the difference between the two runs.
+- You covered the conditions the change will meet. That includes the case it should leave alone, and for session behavior a fresh session, a resumed session, a later turn, and a session after compaction.
+- The session under test got an ordinary request, worded as a task the way Jon would ask for it.
+
+Unit tests are welcome as extra evidence. The live run is the proof. A test you edited until it passed proves nothing.
+
+For a change to Claude Code behavior, such as a hook, skill, rule, setting, prompt or output style:
+- Spawn every session through the account broker, with the stream saved to a file:
+  python ~/.claude/scripts/account_broker.py run --product claude --report <broker-report.json> -- claude -p "<request>" --model claude-opus-5-5 --effort <level> --output-format stream-json --verbose > <stream.jsonl>
+- Run each later turn the same way with `--resume <session id>`. The broker resumes a session on the account that started it when that account has room.
+- Keep `--model` and `--effort` on every call. Without them the headless run uses claude-sonnet-5-5. Confirm the served model in the result's `modelUsage`.
+- Start the broker from your own shell, with your environment as is. The broker reads the account meters with your session's credentials and starts Claude without your session's variables.
+- Leave out `--bare` and `claude plugin eval`. Both drop the hooks and settings the user runs with.
+- Read the broker report for the account it chose. Read the stream for the hook events and their output, `permission_denials`, the final result, and the token usage on the result event.
+- When the broker exits 3 with action "wait", no account has room. Treat that as a blocked proof and report its reason and `resets_at`. Spawn Claude only through the broker.
+
+Report it in the pull request body under "Proof in practice". List each command you ran, quote the output lines that show the effect, state the difference between the runs with and without the change, and name anything still unproven.
+
+When you cannot prove it, leave the pull request unopened. Tell Jon in three short sentences what you could not run and which tool would make it possible. A blocked proof is an acceptable result, because it shows where tooling is missing.
+
+## Enforcement
+
+`hooks/blocking/pull_request_proof.py` reads the body of each new pull request before it opens. `pr_lifecycle_skill_gate.py` runs it on `gh pr create`, the `pull_request.py create` script, and each `mcp__*__create_pull_request` tool. The gate denies the call when the body has no "Proof in practice" heading, or when the text under that heading names no command in backticks. A `gh pr create` with no `--body` or `--body-file` is denied with a request for the body. Edits, merges, and pushes pass.
+
+The gate checks that the section is there and names a command. Whether the run proves the change stays a judgment for the author and the reviewer.

package/hooks/blocking/followup_pr_dedupe.py

@@ -79,7 +79,12 @@ def _option_value(all_arguments: list[str], all_option_names: frozenset[str]) ->
     return None
 
 
-def _body_from_arguments(all_arguments: list[str], working_directory: str) -> str | None:
+def body_from_arguments(all_arguments: list[str], working_directory: str) -> str | None:
+    """Return the body a gh-style argument list passes, or None when it passes none.
+
+    ``--body`` text comes back as given. A ``--body-file`` path is read from
+    the working directory. Standard input and an unreadable file give None.
+    """
     inline_body = _option_value(all_arguments, ALL_BODY_OPTIONS)
     if inline_body is not None:
         return inline_body
@@ -125,7 +130,7 @@ def _segment_draft(all_segment_tokens: list[str], working_directory: str) -> Pul
     program, all_arguments = segment_program_and_arguments(all_segment_tokens)
     if program != "gh" or all_arguments[: len(ALL_GH_CREATE_WORDS)] != ALL_GH_CREATE_WORDS:
         return None
-    body = _body_from_arguments(all_arguments, working_directory)
+    body = body_from_arguments(all_arguments, working_directory)
     repository = _repository_from_arguments(all_arguments, working_directory)
     if body is None or repository is None:
         return None

package/hooks/blocking/pr_lifecycle_skill_gate.py

@@ -53,6 +53,7 @@ from hooks_constants.hook_specific_output_keys import (
 from hooks_constants.pre_tool_use_stdin import read_hook_input_dictionary_from_stdin
 from hooks_constants.setup_project_paths_constants import DECODE_ERRORS_POLICY, UTF8_ENCODING
 from blocking.followup_pr_dedupe import duplicate_followup_reason
+from blocking.pull_request_proof import missing_proof_reason
 from transcript_skill_scan import is_skill_loaded_after_last_compaction
 
 
@@ -198,7 +199,7 @@ def _subagent_transcript_path(all_payload_fields: dict[str, object]) -> str | No
 
 
 def decision_for(all_payload_fields: dict[str, object]) -> dict[str, object] | None:
-    """Return a deny for an unloaded skill or a second follow-up pull request for one parent.
+    """Return a deny for an unloaded skill, a new pull request with no proof, or a second follow-up.
 
     Args:
         all_payload_fields: The parsed PreToolUse input.
@@ -207,6 +208,9 @@ def decision_for(all_payload_fields: dict[str, object]) -> dict[str, object] | N
         return None
     if _is_skill_unloaded(all_payload_fields):
         return _deny(DENY_REASON)
+    proof_reason = missing_proof_reason(all_payload_fields)
+    if proof_reason is not None:
+        return _deny(proof_reason)
     duplicate_reason = duplicate_followup_reason(all_payload_fields)
     return None if duplicate_reason is None else _deny(duplicate_reason)
 

package/hooks/blocking/pull_request_proof.py

@@ -0,0 +1,141 @@
+"""Deny a new pull request whose body carries no 'Proof in practice' section."""
+
+from __future__ import annotations
+
+import re
+import sys
+from collections.abc import Mapping
+from pathlib import Path
+
+hooks_directory = str(Path(__file__).resolve().parent.parent)
+if hooks_directory not in sys.path:
+    sys.path.insert(0, hooks_directory)
+
+from blocking.followup_pr_dedupe import body_from_arguments
+from hooks_constants.pr_lifecycle_skill_gate_constants import SHELL_TOOL_NAMES
+from hooks_constants.pull_request_proof_constants import (
+    ALL_GH_CREATE_WORDS,
+    ALL_PYTHON_PROGRAM_NAMES,
+    COMMAND_MARKER,
+    CREATE_PULL_REQUEST_TOOL_SUFFIX,
+    LINE_SEPARATOR,
+    MISSING_BODY_REASON,
+    MISSING_PROOF_REASON,
+    NEXT_HEADING_PATTERN,
+    PROOF_HEADING_PATTERN,
+    PULL_REQUEST_SCRIPT_CREATE_WORD,
+    PULL_REQUEST_SCRIPT_NAME,
+)
+from hooks_constants.pytest_invocation import unquoted_token
+from hooks_constants.shell_command_pipeline import pipeline_segments_for_command
+from hooks_constants.shell_command_segments import token_basename
+from hooks_constants.shell_command_wrappers import (
+    all_wrapped_command_texts,
+    segment_program_and_arguments,
+)
+
+
+def _heading_level(line: str, heading_pattern: str) -> int | None:
+    heading = re.match(heading_pattern, line.strip(), re.IGNORECASE)
+    return None if heading is None else len(heading.group(1))
+
+
+def _lines_until_heading(all_lines: list[str], heading_level: int) -> list[str]:
+    for each_index, each_line in enumerate(all_lines):
+        next_level = _heading_level(each_line, NEXT_HEADING_PATTERN)
+        if next_level is not None and next_level <= heading_level:
+            return all_lines[:each_index]
+    return all_lines
+
+
+def proof_section(body: str) -> str | None:
+    """Return the text under the body's 'Proof in practice' heading, or None.
+
+    ::
+
+        "## Proof in practice\\nran `x`\\n## Notes" -> "ran `x`"
+        "## Summary\\nno proof heading"             -> 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
+
+
+def _script_arguments(program: str, all_arguments: list[str]) -> list[str] | None:
+    if program == PULL_REQUEST_SCRIPT_NAME:
+        return all_arguments
+    if program not in ALL_PYTHON_PROGRAM_NAMES or not all_arguments:
+        return None
+    script_name = token_basename(unquoted_token(all_arguments[0]))
+    return all_arguments[1:] if script_name == PULL_REQUEST_SCRIPT_NAME else None
+
+
+def _script_create_arguments(program: str, all_arguments: list[str]) -> list[str] | None:
+    all_script_arguments = _script_arguments(program, all_arguments)
+    if all_script_arguments is None or all_script_arguments[:1] != [PULL_REQUEST_SCRIPT_CREATE_WORD]:
+        return None
+    return all_script_arguments[1:]
+
+
+def _create_arguments(all_segment_tokens: list[str]) -> list[str] | None:
+    program, all_arguments = segment_program_and_arguments(all_segment_tokens)
+    if program == "gh" and all_arguments[: len(ALL_GH_CREATE_WORDS)] == ALL_GH_CREATE_WORDS:
+        return all_arguments[len(ALL_GH_CREATE_WORDS) :]
+    return _script_create_arguments(program, all_arguments)
+
+
+def _shell_create_bodies(command: str, working_directory: str) -> list[str | None]:
+    return [
+        body_from_arguments(all_create_arguments, working_directory)
+        for each_text in all_wrapped_command_texts(command)
+        for each_segment, _each_following_operator in pipeline_segments_for_command(each_text)
+        if (all_create_arguments := _create_arguments(each_segment)) is not None
+    ]
+
+
+def _create_bodies(all_payload_fields: Mapping[str, object]) -> list[str | None]:
+    tool_name = all_payload_fields.get("tool_name")
+    tool_input = all_payload_fields.get("tool_input")
+    if not isinstance(tool_name, str) or not isinstance(tool_input, dict):
+        return []
+    if tool_name.endswith(CREATE_PULL_REQUEST_TOOL_SUFFIX):
+        body = tool_input.get("body")
+        return [body if isinstance(body, str) else ""]
+    command = tool_input.get("command")
+    if tool_name not in SHELL_TOOL_NAMES or not isinstance(command, str):
+        return []
+    working_directory = all_payload_fields.get("cwd")
+    return _shell_create_bodies(
+        command, working_directory if isinstance(working_directory, str) else ""
+    )
+
+
+def missing_proof_reason(all_payload_fields: Mapping[str, object]) -> str | None:
+    """Return a deny reason when a new pull request's body has no proof, else None.
+
+    ::
+
+        gh pr create --body-file body.md, body has the section -> None
+        mcp__github__create_pull_request, body without it      -> MISSING_PROOF_REASON
+        gh pr create --fill                                     -> MISSING_BODY_REASON
+        gh pr edit, git push, any other tool                    -> None
+
+    The proof section is a 'Proof in practice' heading whose text names at
+    least one command in backticks.
+
+    Args:
+        all_payload_fields: The parsed PreToolUse input.
+    """
+    for each_body in _create_bodies(all_payload_fields):
+        if each_body is None:
+            return MISSING_BODY_REASON
+        section = proof_section(each_body)
+        if not section or COMMAND_MARKER not in section:
+            return MISSING_PROOF_REASON
+    return None

package/hooks/blocking/test_followup_pr_dedupe.py

@@ -84,3 +84,11 @@ def test_powershell_body_file_is_denied(tmp_path: Path) -> None:
     }
     reason = dedupe.duplicate_followup_reason(payload, _reader([OPEN_FOLLOWUP]))
     assert reason is not None and "pull request #1769" in reason
+
+
+def test_body_from_arguments_reads_inline_text_and_body_files(tmp_path: Path) -> None:
+    (tmp_path / "body.md").write_text("From the file.", encoding="utf-8")
+    assert dedupe.body_from_arguments(["--body", "Inline."], "") == "Inline."
+    assert dedupe.body_from_arguments(["--body-file", "body.md"], str(tmp_path)) == "From the file."
+    assert dedupe.body_from_arguments(["--body-file", "-"], str(tmp_path)) is None
+    assert dedupe.body_from_arguments(["--fill"], str(tmp_path)) is None

package/hooks/blocking/test_pr_lifecycle_skill_gate.py

@@ -13,6 +13,9 @@ if str(HOOKS_DIRECTORY) not in sys.path:
 from blocking import followup_pr_dedupe as gate_dedupe
 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"
 
 
 def _transcript(tmp_path: Path, skill_name: str | None = None, compact: bool = False) -> Path:
@@ -61,7 +64,7 @@ def test_unloaded_pull_request_command_is_denied(tmp_path: Path) -> None:
 
 def test_loaded_skill_allows_action_silently(tmp_path: Path) -> None:
     path = _transcript(tmp_path, "plugin:pr-lifecycle")
-    assert _run_main(_payload("gh pr create", path)) == (0, "")
+    assert _run_main(_payload("gh pr view", path)) == (0, "")
 
 
 def test_user_slash_command_loads_skill(tmp_path: Path) -> None:
@@ -127,7 +130,7 @@ def test_agent_id_with_path_separator_is_not_followed(tmp_path: Path) -> None:
 
 
 def test_unreadable_or_missing_transcript_allows_silently(tmp_path: Path) -> None:
-    payload = _payload("gh pr create", tmp_path / "missing.jsonl")
+    payload = _payload("gh pr view", tmp_path / "missing.jsonl")
     assert _run_main(payload) == (0, "")
     payload.pop("transcript_path")
     assert _run_main(payload) == (0, "")
@@ -237,7 +240,7 @@ def test_hook_has_its_own_pre_tool_use_registration() -> None:
 def test_loaded_skill_still_denies_a_second_followup_for_one_parent(tmp_path: Path) -> None:
     payload = {
         "tool_name": "mcp__github__create_pull_request",
-        "tool_input": {"owner": "jl-cmd", "repo": "claude-dev-env", "body": "Follow-up to #1731"},
+        "tool_input": {"owner": "jl-cmd", "repo": "claude-dev-env", "body": PROVEN_FOLLOWUP_BODY},
         "transcript_path": str(_transcript(tmp_path, "pr-lifecycle")),
     }
     open_followup = {"number": 1769, "html_url": "https://github.com/jl-cmd/claude-dev-env/pull/1769", "body": "Follow-up to #1731"}
@@ -251,8 +254,14 @@ def test_loaded_skill_still_denies_a_second_followup_for_one_parent(tmp_path: Pa
 def test_loaded_skill_allows_a_followup_when_the_read_fails(tmp_path: Path) -> None:
     payload = {
         "tool_name": "mcp__github__create_pull_request",
-        "tool_input": {"owner": "jl-cmd", "repo": "claude-dev-env", "body": "Follow-up to #1731"},
+        "tool_input": {"owner": "jl-cmd", "repo": "claude-dev-env", "body": PROVEN_FOLLOWUP_BODY},
         "transcript_path": str(_transcript(tmp_path, "pr-lifecycle")),
     }
     with patch.object(gate_dedupe, "read_open_pull_requests", side_effect=OSError("offline")):
         assert gate.decision_for(payload) is None
+
+
+def test_loaded_skill_still_denies_a_new_pull_request_without_proof(tmp_path: Path) -> None:
+    exit_code, output = _run_main(_payload("gh pr create --body 'Adds a gate.'", _transcript(tmp_path, "pr-lifecycle")))
+    assert exit_code == 0
+    assert json.loads(output)["hookSpecificOutput"]["permissionDecisionReason"] == MISSING_PROOF_REASON

package/hooks/blocking/test_pull_request_proof.py

@@ -0,0 +1,92 @@
+"""Behavior tests for the proof-in-practice check on a new pull request."""
+
+import sys
+from pathlib import Path
+
+HOOKS_DIRECTORY = Path(__file__).resolve().parent.parent
+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
+
+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"
+
+
+def _shell(command: str, working_directory: Path | None = None) -> dict[str, object]:
+    return {
+        "tool_name": "Bash",
+        "tool_input": {"command": command},
+        "cwd": str(working_directory or ""),
+    }
+
+
+def _mcp_create(body: object) -> dict[str, object]:
+    return {
+        "tool_name": "mcp__github__create_pull_request",
+        "tool_input": {"owner": "o", "repo": "r", "title": "t", "body": body},
+    }
+
+
+def test_proof_section_should_stop_at_a_heading_of_the_same_level() -> None:
+    body = "### Proof in practice\nran `a`\n#### Child\nkept\n### Local checks\ndropped"
+    assert gate.proof_section(body) == "ran `a`\n#### Child\nkept"
+
+
+def test_proof_section_should_return_none_without_the_heading() -> None:
+    assert gate.proof_section(UNPROVEN_BODY) is None
+
+
+def test_mcp_create_without_proof_should_be_denied() -> None:
+    assert gate.missing_proof_reason(_mcp_create(UNPROVEN_BODY)) == MISSING_PROOF_REASON
+
+
+def test_mcp_create_with_no_body_should_be_denied() -> None:
+    assert gate.missing_proof_reason(_mcp_create(None)) == MISSING_PROOF_REASON
+
+
+def test_mcp_create_with_proof_should_pass() -> None:
+    assert gate.missing_proof_reason(_mcp_create(PROVEN_BODY)) is None
+
+
+def test_heading_with_no_command_should_be_denied() -> None:
+    body = "## Proof in practice\nIt works.\n"
+    assert gate.missing_proof_reason(_mcp_create(body)) == MISSING_PROOF_REASON
+
+
+def test_gh_create_body_file_with_proof_should_pass(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_proof_reason(payload) is None
+
+
+def test_gh_create_body_file_without_proof_should_be_denied(tmp_path: Path) -> None:
+    (tmp_path / "body.md").write_text(UNPROVEN_BODY, encoding="utf-8")
+    payload = _shell("gh pr create -F body.md", tmp_path)
+    assert gate.missing_proof_reason(payload) == MISSING_PROOF_REASON
+
+
+def test_gh_create_with_fill_should_ask_for_a_body() -> None:
+    assert gate.missing_proof_reason(_shell("gh pr create --fill")) == MISSING_BODY_REASON
+
+
+def test_wrapped_gh_create_should_be_read() -> None:
+    payload = _shell("bash -c 'gh pr create --body \"no proof\"'")
+    assert gate.missing_proof_reason(payload) == MISSING_PROOF_REASON
+
+
+def test_pull_request_script_create_should_be_read(tmp_path: Path) -> None:
+    (tmp_path / "body.md").write_text(UNPROVEN_BODY, encoding="utf-8")
+    payload = _shell("python3 scripts/pull_request.py create --body-file body.md", tmp_path)
+    assert gate.missing_proof_reason(payload) == MISSING_PROOF_REASON
+
+
+def test_other_pull_request_commands_should_pass() -> None:
+    for each_command in ("gh pr edit 3 --body x", "git push -u origin b", "gh pr view"):
+        assert gate.missing_proof_reason(_shell(each_command)) is 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

package/hooks/hooks_constants/pull_request_proof_constants.py

@@ -0,0 +1,27 @@
+"""Constants for the proof-in-practice check on a new pull request."""
+
+PROOF_HEADING_PATTERN = r"^(#{1,6})[ \t]+proof in practice[ \t]*#*[ \t]*$"
+NEXT_HEADING_PATTERN = r"^(#{1,6})[ \t]+\S"
+COMMAND_MARKER = "`"
+LINE_SEPARATOR = "\n"
+ALL_GH_CREATE_WORDS = ["pr", "create"]
+PULL_REQUEST_SCRIPT_NAME = "pull_request.py"
+PULL_REQUEST_SCRIPT_CREATE_WORD = "create"
+ALL_PYTHON_PROGRAM_NAMES = frozenset({"python", "python3", "py"})
+CREATE_PULL_REQUEST_TOOL_SUFFIX = "__create_pull_request"
+PROOF_GUIDE_PATH = "~/.claude/docs/rule-guides/proof-before-pull-request.md"
+MISSING_BODY_REASON = (
+    "Pass the pull request body with --body or --body-file so this gate can read its"
+    " 'Proof in practice' section. Read " + PROOF_GUIDE_PATH + " for what counts as proof."
+)
+MISSING_PROOF_REASON = (
+    "This pull request body has no 'Proof in practice' section with the commands you ran."
+    " Before you open a pull request, run the changed thing the way its user runs it,"
+    " run the same scenario without the change, and quote the output lines that show"
+    " the difference. For a hook, skill, rule, setting, prompt or output style, spawn"
+    " each test session through the account broker. Then add a 'Proof in practice'"
+    " heading to the body that lists each command in backticks, quotes the output, states"
+    " the difference between the runs, and names anything still unproven. When you cannot"
+    " 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."
+)

package/package.json

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

package/rules/proof-before-pull-request.md

@@ -0,0 +1,7 @@
+# Proof before a pull request
+
+**When:** Before you open a pull request.
+
+Run the change where it runs, with and without it, and quote both results under "Proof in practice" in the body. A hook denies a body without one. Unproven: leave it unopened and tell the user.
+
+**Full text:** [`docs/rule-guides/proof-before-pull-request.md`](../docs/rule-guides/proof-before-pull-request.md).

package/rules/question-presentation.md

@@ -1,12 +1,9 @@
 # Present questions clearly
 
-Before asking for input, give a short formatted brief in chat. Put the context and the effect of each choice there. Add a visual or artifact only when it helps the decision.
+Before asking, give a short formatted chat brief with context and each choice's effect. Add helpful visuals or artifacts.
 
-For Codex, when a visual comparison helps, discover callable tools for Page creation, visualization upload, and Page opening. Create the comparison, upload its visualization, and open its Page in the current task before asking. If a tool is unavailable, creation, upload, or opening fails, or opening queues, put the comparison in chat before asking. Inline Visualize references appear only in final replies. Use the user's submitted answer for the decision. An async dispatch acknowledgement or saved visual supplies context only. Wait for the answer before work that depends on it.
+For Codex visual comparisons, find Page creation, visualization upload, and Page opening tools. Create the comparison, upload its visualization, and open its Page here before asking. If tools are missing, steps fail, or opening queues, compare in chat before asking. Put inline Visualize references only in final replies. An async acknowledgement or saved visual is context only; wait for and use the submitted answer before dependent work.
 
-Ask one short, self-contained question with two or three clear choices. Use short labels, and keep each supported choice description to one short sentence. Use the same labels in the chat brief, comparison, and picker.
+Ask one short, self-contained question with two or three choices. Give each a short label and one short sentence. Reuse labels in the brief, comparison, and picker.
 
-Discover the current session's native question tool and its schema. Claude may expose `AskUserQuestion`.
-Codex may expose `request_user_input_async` or `request_user_input`. Follow the tool's mode restrictions.
-Put the question in its declared title or question field and choices in its declared string or object fields.
-When no native tool is usable, ask the short question and choices in chat.
+Find the native question tool and schema. Claude may use `AskUserQuestion`; Codex may use `request_user_input_async` or `request_user_input`. Honor mode rules. Put the question in its title or question field and choices in string or object fields. If unusable, ask in chat.

package/scripts/tests/test_rule_load_scopes.py

@@ -18,6 +18,7 @@ ALWAYS_ON_RULE_NAMES = frozenset(
         "filesystem-search.md",
         "memory-stores-durable-facts.md",
         "no-contrast-framing.md",
+        "proof-before-pull-request.md",
         "question-presentation.md",
         "research-mode.md",
         "request-scope.md",