claude-dev-env 8.102.1 → 8.103.0

package/.agents/skills/pull-request/reference/body-sections.md

@@ -7,7 +7,8 @@ A reviewer reads the body in place of the code. The body says what the change do
 | `## What this does` | Two or three plain sentences: the behavior before, the behavior after, and who notices. Written for a reviewer who has not read the worker's conversation. |
 | `## What changed` | One bullet per area of the diff, in plain words. |
 | `## Existing work` | What already did part of the job, with a link or file and line, and what this change adds. Or the places searched. |
-| `## Proof in practice` | Each command in backticks, the output without the change and with it, and anything still unproven. |
+| `## Proof in practice` | Each command in backticks, and the output without the change and with it. The run on the target the change exists to fix is here before the pull request opens. |
+| `## Not covered` | Optional. A condition the change does not target and the runs left out, such as an older data shape. |
 | `## Eval` | Only for a `feat` title. The eval's cases and grader, the command, and its result. |
 | `## Risk` | What could break, for whom, and how anyone would notice. `Low` and one reason for a doc or test change. |
 | `## How to revert` | The exact undo step, and any data or state a plain revert leaves behind. |

package/bin/install.prompt-context.test.mjs

@@ -35,13 +35,14 @@ test('reinstall drops the retired style reminder and keeps one skill reminder ho
     mergeHooksIntoSettings(settings, hooksConfig, 'C:/Users/example/.claude', 'python');
 
     const userPromptHooks = settings.hooks.UserPromptSubmit.flatMap(eachGroup => eachGroup.hooks);
-    assert.equal(userPromptHooks.length, 6);
+    assert.equal(userPromptHooks.length, 7);
     assert.equal(userPromptHooks[0].command, userCommand);
     assert.match(userPromptHooks[1].command, /session\/skill_loaded_reminder\.py$/);
     assert.match(userPromptHooks[2].command, /lifecycle\/nested_project_hooks\.py$/);
     assert.match(userPromptHooks[3].command, /blocking\/chat_reply_gate\.py$/);
     assert.match(userPromptHooks[4].command, /session\/tracking_nudge\.py$/);
     assert.match(userPromptHooks[5].command, /session\/plugin_change_warning\.py$/);
+    assert.match(userPromptHooks[6].command, /blocking\/turn_review_gate\.py$/);
     assert.ok(userPromptHooks.every(eachHook => !eachHook.command.includes('style_reminder_prompt')));
 
     const firstMerge = JSON.stringify(settings);

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

@@ -30,14 +30,14 @@ For a change to Claude Code behavior, such as a hook, skill, rule, setting, prom
 - 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.
+Report it in the pull request body under "Proof in practice". List each command you ran, quote the output lines that show the effect, and state the difference between the runs with and without the change. The run on the target the change exists to fix belongs in this section before the pull request opens. List a condition the change does not target, such as an older data shape, under a "Not covered" heading at the same level.
 
 When you cannot prove it, leave the pull request unopened. Tell the owner 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. The gate also denies a section whose only commands run a test runner, such as `pytest`, `python -m unittest`, `uv run pytest`, `npm test`, `npx vitest`, `jest`, `go test` or `cargo test`. Quotes around a runner word, interpreter flags before `-m`, and `coverage run -m unittest` are still test runs. A command is an inline backticked span or a `$ ` line inside a fenced block. A span that starts with a path and line, such as `gate.py:12`, is not a command. A span that holds one path or file name, such as `src/x.py`, is not a command unless that span runs a test runner, such as `py.test` or `pytest.exe`. A test run piped into `tee`, `tail`, `head`, `grep` or `cat` is still a test run. The deny quotes the line "Unit tests are welcome as extra evidence. The live run is the proof." and asks for a run of the changed thing the way its user runs it, without the change and with it. A section with one command that is not a test run passes. A `gh pr create` with no `--body` or `--body-file` is denied with a request for the body. Edits, merges, and pushes pass.
+`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. The gate also denies a section whose only commands run a test runner, such as `pytest`, `python -m unittest`, `uv run pytest`, `npm test`, `npx vitest`, `jest`, `go test` or `cargo test`. Quotes around a runner word, interpreter flags before `-m`, and `coverage run -m unittest` are still test runs. A command is an inline backticked span or a `$ ` line inside a fenced block. A span that starts with a path and line, such as `gate.py:12`, is not a command. A span that holds one path or file name, such as `src/x.py`, is not a command unless that span runs a test runner, such as `py.test` or `pytest.exe`. A test run piped into `tee`, `tail`, `head`, `grep` or `cat` is still a test run. The deny quotes the line "Unit tests are welcome as extra evidence. The live run is the proof." and asks for a run of the changed thing the way its user runs it, without the change and with it. The gate also denies a section whose prose says part of the change is not proven, not tested or not verified, with "yet", "been" or "fully" allowed after the "not", or says unproven, untested or unverified. The deny quotes that line, and asks for the run before the pull request opens, or for the line under a "Not covered" heading when the change does not target it. Words inside backticks or a fenced block are quoted output and do not count. A section with one command that is not a test run, and no such line, passes. A `gh pr create` with no `--body` or `--body-file` is denied with a request for the body. Edits, merges, and pushes pass.
 
 When the checked-out branch changes a file people see (`.html`, `.htm`, `.css`, `.scss`, `.tsx`, `.jsx`, `.vue`, `.svelte`), the gate also denies a body whose proof section holds no picture: a markdown image, an image URL, or an Artifact page link that shows the screenshots. Render the change, read the screenshot, and put it in the section, so the reader sees what you looked at. When git in the session directory cannot list the branch's changed files, the gate asks for the picture as well.
 
-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.
+The gate checks that the section is there, names a command, and admits no unproven part. Whether the run proves the change stays a judgment for the author and the reviewer.

package/hooks/blocking/pull_request_proof.py

@@ -56,7 +56,12 @@ from hooks_constants.pull_request_proof_constants import (
     FENCED_COMMAND_PROMPT,
     INLINE_COMMAND_PATTERN,
     TEST_ONLY_PROOF_REASON,
+    ALL_CODE_FENCE_MARKERS,
+    BLOCKQUOTE_MARKERS,
+    INLINE_CODE_SPAN_PATTERN,
     UNITTEST_MODULE_NAME,
+    UNPROVEN_ADMISSION_PATTERN,
+    UNPROVEN_PROOF_REASON,
     ALL_PASSTHROUGH_PROGRAM_NAMES,
     PATH_WITH_LINE_PATTERN,
     SINGLE_FILE_NAME_PATTERN,
@@ -332,14 +337,31 @@ def _line_commands(line: str, is_inside_fence: bool) -> list[str]:
     return []
 
 
-def _proof_commands(section: str) -> list[str]:
-    all_commands: list[str] = []
-    is_inside_fence = False
+def _fence_marker(line: str) -> str | None:
+    fence_text = line.strip().lstrip(BLOCKQUOTE_MARKERS).strip()
+    for each_marker in ALL_CODE_FENCE_MARKERS:
+        if fence_text.startswith(each_marker) and each_marker not in fence_text[len(each_marker) :]:
+            return each_marker
+    return None
+
+
+def _lines_with_fence_state(section: str) -> Iterator[tuple[str, bool]]:
+    open_marker: str | None = None
     for each_line in section.splitlines():
-        if each_line.strip().startswith(CODE_FENCE_MARKER):
-            is_inside_fence = not is_inside_fence
+        line_marker = _fence_marker(each_line)
+        if line_marker is not None and open_marker is None:
+            open_marker = line_marker
             continue
-        all_commands.extend(_line_commands(each_line, is_inside_fence))
+        if line_marker is not None and line_marker == open_marker:
+            open_marker = None
+            continue
+        yield each_line, open_marker is not None
+
+
+def _proof_commands(section: str) -> list[str]:
+    all_commands: list[str] = []
+    for each_line, each_is_inside_fence in _lines_with_fence_state(section):
+        all_commands.extend(_line_commands(each_line, each_is_inside_fence))
     return [each_command for each_command in all_commands if _reads_as_command(each_command)]
 
 
@@ -401,6 +423,35 @@ def _proof_runs_only_tests(section: str) -> bool:
     return bool(all_commands) and all(_command_runs_tests(each_command) for each_command in all_commands)
 
 
+def _prose_lines(section: str) -> Iterator[tuple[str, str]]:
+    for each_line, each_is_inside_fence in _lines_with_fence_state(section):
+        if not each_is_inside_fence:
+            yield each_line, re.sub(INLINE_CODE_SPAN_PATTERN, "", each_line.replace(CODE_FENCE_MARKER, "`"))
+
+
+def unproven_admission(section: str) -> str | None:
+    """Return the first prose line of a proof section that says something is not proven, or None.
+
+    ::
+
+        "Not proven here: a fresh Convert run."   -> "Not proven here: a fresh Convert run."
+        "The live run is untested."               -> "The live run is untested."
+        "It has not been tested on the target."   -> "It has not been tested on the target."
+        "`not proven` printed by the probe"       -> None
+        "> Not proven here: the live run."        -> "> Not proven here: the live run."
+        "Ran `python run.py`, quoted below."      -> None
+
+    The markers are not proven, not tested and not verified, each with any
+    run of yet, been or fully after the not, plus unproven, untested and
+    unverified, matched without regard to case. Inline code spans and fenced
+    blocks are skipped, so output quoted there never counts.
+    """
+    for each_line, each_prose in _prose_lines(section):
+        if re.search(UNPROVEN_ADMISSION_PATTERN, each_prose, re.IGNORECASE):
+            return each_line.strip()
+    return None
+
+
 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.
 
@@ -412,6 +463,7 @@ def missing_proof_reason(all_payload_fields: Mapping[str, object]) -> str | None
         proof whose only command is `py.test`                   -> TEST_ONLY_PROOF_REASON
         proof whose only command is `python -q -m unittest`     -> TEST_ONLY_PROOF_REASON
         proof with `pytest` and `python run.py`                 -> None
+        proof whose prose says "Not proven here: the run"      -> UNPROVEN_PROOF_REASON
         gh pr create --fill                                     -> MISSING_BODY_REASON
         gh pr edit, git push, any other tool                    -> None
 
@@ -425,6 +477,9 @@ def missing_proof_reason(all_payload_fields: Mapping[str, object]) -> str | None
     the section is denied. Quotes around a runner word still count. Interpreter
     flags before -m unittest still count. coverage run -m unittest counts.
     A pipe into tee, tail, head, grep or cat keeps a test run a test run.
+    A section whose prose says part of the change is not proven, untested or
+    unverified is denied, with the line quoted; unproven_admission lists the
+    markers.
 
     Args:
         all_payload_fields: The parsed PreToolUse input.
@@ -437,6 +492,9 @@ def missing_proof_reason(all_payload_fields: Mapping[str, object]) -> str | None
             return MISSING_PROOF_REASON
         if _proof_runs_only_tests(section):
             return TEST_ONLY_PROOF_REASON
+        admission = unproven_admission(section)
+        if admission is not None:
+            return UNPROVEN_PROOF_REASON.format(admission=admission)
     return None
 
 

package/hooks/blocking/test_pull_request_proof.py

@@ -18,6 +18,7 @@ from hooks_constants.pull_request_proof_constants import (
     MISSING_EXISTING_WORK_REASON,
     MISSING_PROOF_REASON,
     TEST_ONLY_PROOF_REASON,
+    UNPROVEN_PROOF_REASON,
     UNREADABLE_CHANGES_REASON,
 )
 
@@ -111,6 +112,92 @@ def test_proof_with_a_test_run_and_file_references_should_be_denied() -> None:
     assert gate.missing_proof_reason(_mcp_create(body)) == TEST_ONLY_PROOF_REASON
 
 
+def test_proof_that_says_its_target_run_is_not_proven_should_be_denied() -> None:
+    body = (
+        "## Proof in practice\nRan `python verify.py theme`.\n> PASS\n\n"
+        "Not proven here: a fresh Convert run of Bear Penguin that rewrites the record.\n"
+    )
+    assert gate.missing_proof_reason(_mcp_create(body)) == UNPROVEN_PROOF_REASON.format(
+        admission="Not proven here: a fresh Convert run of Bear Penguin that rewrites the record."
+    )
+
+
+@pytest.mark.parametrize(
+    "admission", ["unproven", "not yet tested", "Untested", "unverified", "not verified", "not been tested", "not fully verified"]
+)
+def test_each_unproven_marker_in_proof_prose_should_be_denied(admission: str) -> None:
+    admission_line = f"The live dialer path is {admission}."
+    body = f"## Proof in practice\nRan `python run.py`.\n{admission_line}\n"
+    assert gate.missing_proof_reason(_mcp_create(body)) == UNPROVEN_PROOF_REASON.format(admission=admission_line)
+
+
+def test_unproven_line_moved_under_a_not_covered_heading_should_pass() -> None:
+    body = (
+        "## Proof in practice\nRan `python run.py`.\n> PASS\n\n"
+        "## Not covered\n\nNot proven here: a run on an older session.\n"
+    )
+    assert gate.missing_proof_reason(_mcp_create(body)) is None
+
+
+def test_unproven_words_inside_quoted_output_should_pass() -> None:
+    body = (
+        "## Proof in practice\nRan `python run.py`, which printed `unverified sender denied`.\n"
+        "```\n$ python run.py\nstatus: not proven\n```\n"
+    )
+    assert gate.missing_proof_reason(_mcp_create(body)) is None
+
+
+def test_unproven_admission_after_a_one_line_triple_backtick_span_should_be_denied() -> None:
+    body = (
+        "## Proof in practice\nRan `python run.py`.\n```python run.py``` -> PASS\n"
+        "Not proven here: the live run on the target.\n"
+    )
+    assert gate.missing_proof_reason(_mcp_create(body)) == UNPROVEN_PROOF_REASON.format(
+        admission="Not proven here: the live run on the target."
+    )
+
+
+def test_test_run_after_a_one_line_triple_backtick_span_should_be_denied() -> None:
+    body = "## Proof in practice\n```pytest``` ok\nRan `pytest tests/`.\n"
+    assert gate.missing_proof_reason(_mcp_create(body)) == TEST_ONLY_PROOF_REASON
+
+
+def test_unproven_words_in_a_fence_inside_a_blockquote_should_pass() -> None:
+    body = "## Proof in practice\nRan `python run.py`.\n> ```\n> status: not proven\n> ```\n"
+    assert gate.missing_proof_reason(_mcp_create(body)) is None
+
+
+def test_unproven_words_in_a_tilde_fence_should_pass() -> None:
+    body = "## Proof in practice\nRan `python run.py`.\n~~~\nstatus: not proven\n~~~\n"
+    assert gate.missing_proof_reason(_mcp_create(body)) is None
+
+
+def test_tilde_line_inside_a_backtick_fence_keeps_the_fence_open() -> None:
+    body = "## Proof in practice\nRan `python run.py`.\n```\n~~~\nstatus: not proven\n```\n"
+    assert gate.missing_proof_reason(_mcp_create(body)) is None
+
+
+def test_admission_after_a_backtick_fence_holding_a_tilde_line_should_be_denied() -> None:
+    body = "## Proof in practice\nRan `python run.py`.\n```\n~~~\n```\nNot proven here: the live run.\n"
+    assert gate.missing_proof_reason(_mcp_create(body)) == UNPROVEN_PROOF_REASON.format(
+        admission="Not proven here: the live run."
+    )
+
+
+def test_unproven_deny_quotes_the_line_as_written() -> None:
+    body = "## Proof in practice\nRan `python run.py`.\nNot proven here: the `convert.py` run on the target.\n"
+    assert gate.missing_proof_reason(_mcp_create(body)) == UNPROVEN_PROOF_REASON.format(
+        admission="Not proven here: the `convert.py` run on the target."
+    )
+
+
+def test_unproven_admission_inside_a_blockquote_should_be_denied() -> None:
+    body = "## Proof in practice\nRan `python run.py`.\n> Not proven here: the live dialer run.\n"
+    assert gate.missing_proof_reason(_mcp_create(body)) == UNPROVEN_PROOF_REASON.format(
+        admission="> Not proven here: the live dialer run."
+    )
+
+
 def test_proof_with_a_test_run_piped_into_tee_should_be_denied() -> None:
     body = "## Proof in practice\nRan `pytest x | tee log`.\n"
     assert gate.missing_proof_reason(_mcp_create(body)) == TEST_ONLY_PROOF_REASON

package/hooks/blocking/test_turn_review_findings.py

@@ -0,0 +1,25 @@
+from turn_review_findings import finding_lines
+
+CHANGED_PATH = "src/service.py"
+
+
+def test_should_read_a_json_finding_on_a_changed_path() -> None:
+    review_text = (
+        'Review done.\n[{"file": "src/service.py", "line": 208, "summary": "drops the retry"},'
+        ' {"file": "src/other.py", "line": 3, "summary": "unchanged file"}]'
+    )
+    assert finding_lines(review_text, [CHANGED_PATH]) == ["src/service.py:208 drops the retry"]
+
+
+def test_should_read_a_prose_finding_that_opens_with_a_changed_path() -> None:
+    review_text = (
+        "- `src/service.py:208` - drops the retry\nThe change at src/service.py:12 is fine."
+    )
+    assert finding_lines(review_text, [CHANGED_PATH]) == [
+        "- `src/service.py:208` - drops the retry"
+    ]
+
+
+def test_should_report_nothing_for_a_review_that_opens_with_none() -> None:
+    review_text = "(none)\n- `src/service.py:208` - looked at the retry, it stays"
+    assert finding_lines(review_text, [CHANGED_PATH]) == []