claude-dev-env 8.109.0 → 8.109.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/docs/rule-guides/proof-before-pull-request.md +1 -1
- package/hooks/blocking/pr_lifecycle_skill_gate.py +2 -0
- package/hooks/blocking/pull_request_proof.py +43 -4
- package/hooks/blocking/test_pull_request_proof.py +79 -0
- package/hooks/hooks_constants/pull_request_proof_constants.py +16 -1
- package/package.json +1 -1
|
@@ -36,7 +36,7 @@ When you cannot prove it, leave the pull request unopened. Tell the owner in thr
|
|
|
36
36
|
|
|
37
37
|
## Enforcement
|
|
38
38
|
|
|
39
|
-
`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.
|
|
39
|
+
`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. The same denial covers a proof line that opens with "not run", "not exercised" or "not executed" (a "yet" or "been" may follow the "not") or says "has not been run". A proof line with a merge word (merge, merged, merges or merging, so post-merge too) is denied with its own reason: run the check on the branch, and put a file or command name that contains merge in backticks. A step that needs the merged code to exist goes under a "Not covered" heading at the same level as the proof heading, as a line that opens with "not run". `UNPROVEN_ADMISSION_PATTERN` and `MERGE_WORD_PATTERN` list the shapes. 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.
|
|
40
40
|
|
|
41
41
|
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.
|
|
42
42
|
|
|
@@ -331,6 +331,8 @@ def decision_for(all_payload_fields: dict[str, object]) -> dict[str, object] | N
|
|
|
331
331
|
|
|
332
332
|
pr-lifecycle skill not loaded -> DENY_REASON
|
|
333
333
|
new pull request with no proof section -> MISSING_PROOF_REASON
|
|
334
|
+
proof says not run -> UNPROVEN_PROOF_REASON
|
|
335
|
+
proof prose holds a merge word -> DEFERRED_PROOF_REASON
|
|
334
336
|
new pull request with no existing-work section -> MISSING_EXISTING_WORK_REASON
|
|
335
337
|
feature pull request with no eval section -> MISSING_EVAL_SECTION_REASON
|
|
336
338
|
changed page whose proof shows no picture -> MISSING_LOOK_REASON
|
|
@@ -21,6 +21,8 @@ from hooks_constants.pull_request_proof_constants import (
|
|
|
21
21
|
ALL_VISIBLE_FILE_SUFFIXES,
|
|
22
22
|
CHANGED_FILES_SEPARATOR,
|
|
23
23
|
COMMAND_MARKER,
|
|
24
|
+
DEFERRED_PROOF_REASON,
|
|
25
|
+
MERGE_WORD_PATTERN,
|
|
24
26
|
ALL_BASE_FLAGS,
|
|
25
27
|
ALL_DEFAULT_BRANCH_REFERENCES,
|
|
26
28
|
ALL_HEAD_FLAGS,
|
|
@@ -443,15 +445,46 @@ def unproven_admission(section: str) -> str | None:
|
|
|
443
445
|
|
|
444
446
|
The markers are not proven, not tested and not verified, each with any
|
|
445
447
|
run of yet, been or fully after the not, plus unproven, untested and
|
|
446
|
-
unverified
|
|
447
|
-
|
|
448
|
+
unverified. A line or list item that opens with "not run", "not ran",
|
|
449
|
+
"not exercised" or "not executed", each with any run of yet or been after
|
|
450
|
+
the not, is one too, and so is "has not been run", "have not been exercised"
|
|
451
|
+
or "hasn't been executed", with "yet" allowed before "been". Case is
|
|
452
|
+
ignored.
|
|
453
|
+
Inline code spans and fenced blocks are skipped, so output quoted there
|
|
454
|
+
never counts.
|
|
448
455
|
"""
|
|
456
|
+
return _first_prose_match(section, UNPROVEN_ADMISSION_PATTERN)
|
|
457
|
+
|
|
458
|
+
|
|
459
|
+
def _first_prose_match(section: str, pattern: str) -> str | None:
|
|
449
460
|
for each_line, each_prose in _prose_lines(section):
|
|
450
|
-
if re.search(
|
|
461
|
+
if re.search(pattern, each_prose, re.IGNORECASE):
|
|
451
462
|
return each_line.strip()
|
|
452
463
|
return None
|
|
453
464
|
|
|
454
465
|
|
|
466
|
+
def merge_word_line(section: str) -> str | None:
|
|
467
|
+
"""Return the first prose line of a proof section that holds a merge word, or None.
|
|
468
|
+
|
|
469
|
+
::
|
|
470
|
+
|
|
471
|
+
"I check the publish after the merge." -> that line
|
|
472
|
+
"A session verifies it after merging." -> that line
|
|
473
|
+
"Post-merge, a session confirms it." -> that line
|
|
474
|
+
"Ran `git merge origin/main`, then `python run.py`." -> None
|
|
475
|
+
"Verified on the branch." -> None
|
|
476
|
+
|
|
477
|
+
The words are merge, merged, merges and merging, matched without regard to
|
|
478
|
+
case, so post-merge counts. Inline code spans and fenced blocks are skipped,
|
|
479
|
+
so a command or file name that holds the word passes when it sits in
|
|
480
|
+
backticks.
|
|
481
|
+
|
|
482
|
+
Args:
|
|
483
|
+
section: The text under the 'Proof in practice' heading.
|
|
484
|
+
"""
|
|
485
|
+
return _first_prose_match(section, MERGE_WORD_PATTERN)
|
|
486
|
+
|
|
487
|
+
|
|
455
488
|
def missing_proof_reason(all_payload_fields: Mapping[str, object]) -> str | None:
|
|
456
489
|
"""Return a deny reason when a new pull request's body has no proof, else None.
|
|
457
490
|
|
|
@@ -464,6 +497,8 @@ def missing_proof_reason(all_payload_fields: Mapping[str, object]) -> str | None
|
|
|
464
497
|
proof whose only command is `python -q -m unittest` -> TEST_ONLY_PROOF_REASON
|
|
465
498
|
proof with `pytest` and `python run.py` -> None
|
|
466
499
|
proof whose prose says "Not proven here: the run" -> UNPROVEN_PROOF_REASON
|
|
500
|
+
proof whose prose says "Not run: the live publish" -> UNPROVEN_PROOF_REASON
|
|
501
|
+
proof prose that says "I verify it after the merge" -> DEFERRED_PROOF_REASON
|
|
467
502
|
gh pr create --fill -> MISSING_BODY_REASON
|
|
468
503
|
gh pr edit, git push, any other tool -> None
|
|
469
504
|
|
|
@@ -479,7 +514,8 @@ def missing_proof_reason(all_payload_fields: Mapping[str, object]) -> str | None
|
|
|
479
514
|
A pipe into tee, tail, head, grep or cat keeps a test run a test run.
|
|
480
515
|
A section whose prose says part of the change is not proven, untested or
|
|
481
516
|
unverified is denied, with the line quoted; unproven_admission lists the
|
|
482
|
-
markers.
|
|
517
|
+
markers. A prose line with a merge word is denied in the proof section;
|
|
518
|
+
merge_word_line lists the words.
|
|
483
519
|
|
|
484
520
|
Args:
|
|
485
521
|
all_payload_fields: The parsed PreToolUse input.
|
|
@@ -495,6 +531,9 @@ def missing_proof_reason(all_payload_fields: Mapping[str, object]) -> str | None
|
|
|
495
531
|
admission = unproven_admission(section)
|
|
496
532
|
if admission is not None:
|
|
497
533
|
return UNPROVEN_PROOF_REASON.format(admission=admission)
|
|
534
|
+
deferral = merge_word_line(section)
|
|
535
|
+
if deferral is not None:
|
|
536
|
+
return DEFERRED_PROOF_REASON.format(deferral=deferral)
|
|
498
537
|
return None
|
|
499
538
|
|
|
500
539
|
|
|
@@ -13,6 +13,7 @@ if str(HOOKS_DIRECTORY) not in sys.path:
|
|
|
13
13
|
from blocking import pull_request_proof as gate
|
|
14
14
|
from hooks_constants.pull_request_proof_constants import (
|
|
15
15
|
COMPARE_FILE_LIST_LIMIT,
|
|
16
|
+
DEFERRED_PROOF_REASON,
|
|
16
17
|
MISSING_BODY_REASON,
|
|
17
18
|
MISSING_EVAL_SECTION_REASON,
|
|
18
19
|
MISSING_EXISTING_WORK_REASON,
|
|
@@ -686,3 +687,81 @@ def test_is_create_call_should_name_shell_and_mcp_creates() -> None:
|
|
|
686
687
|
assert gate.is_create_call(_mcp_create("b"))
|
|
687
688
|
assert not gate.is_create_call(_shell("gh pr edit 7 --body b"))
|
|
688
689
|
assert not gate.is_create_call({"tool_name": "Read", "tool_input": {"file_path": "a.py"}})
|
|
690
|
+
|
|
691
|
+
|
|
692
|
+
@pytest.mark.parametrize(
|
|
693
|
+
"admission",
|
|
694
|
+
[
|
|
695
|
+
"Not run: the first publish on the live remote.",
|
|
696
|
+
"- Not run: a push race between live sessions.",
|
|
697
|
+
"1. Not run: the live publish.",
|
|
698
|
+
"The live publish has not yet been run.",
|
|
699
|
+
"It hasn't been run on the target.",
|
|
700
|
+
"The dialer path has not been exercised here.",
|
|
701
|
+
],
|
|
702
|
+
)
|
|
703
|
+
def test_each_unrun_wording_in_proof_prose_should_be_denied(admission: str) -> None:
|
|
704
|
+
body = f"## Proof in practice\nRan `python run.py`.\n{admission}\n"
|
|
705
|
+
assert gate.missing_proof_reason(_mcp_create(body)) == UNPROVEN_PROOF_REASON.format(admission=admission)
|
|
706
|
+
|
|
707
|
+
|
|
708
|
+
@pytest.mark.parametrize(
|
|
709
|
+
"merge_line",
|
|
710
|
+
[
|
|
711
|
+
"I check the first live publish after the merge.",
|
|
712
|
+
"The seed step happens once merged.",
|
|
713
|
+
"Post-merge, a session confirms the publish.",
|
|
714
|
+
"A session verifies it after merging.",
|
|
715
|
+
"After it merges, I verify the publish.",
|
|
716
|
+
"I will verify the publish on merge.",
|
|
717
|
+
"I verify the live publish post merge.",
|
|
718
|
+
"Verified the output after merging main into the branch.",
|
|
719
|
+
],
|
|
720
|
+
)
|
|
721
|
+
def test_each_merge_word_in_proof_prose_should_be_denied(merge_line: str) -> None:
|
|
722
|
+
body = f"## Proof in practice\nRan `python run.py`.\n{merge_line}\n"
|
|
723
|
+
assert gate.missing_proof_reason(_mcp_create(body)) == DEFERRED_PROOF_REASON.format(deferral=merge_line)
|
|
724
|
+
|
|
725
|
+
|
|
726
|
+
@pytest.mark.parametrize(
|
|
727
|
+
"prose",
|
|
728
|
+
[
|
|
729
|
+
"The gate does not run on edits.",
|
|
730
|
+
"With the change, the hook is not run on edits.",
|
|
731
|
+
"Without the change, the hook was not run for edits.",
|
|
732
|
+
"Before this change the gate had not run on edits.",
|
|
733
|
+
"Ran `git merge origin/main`, then `python run.py`.",
|
|
734
|
+
"Confirmed the hold label stays until the PR lands.",
|
|
735
|
+
"Not run-dependent.",
|
|
736
|
+
"Without the change the publish failed; with it the publish passed.",
|
|
737
|
+
],
|
|
738
|
+
)
|
|
739
|
+
def test_proof_prose_without_an_unrun_line_or_a_merge_word_should_pass(prose: str) -> None:
|
|
740
|
+
body = f"## Proof in practice\nRan `python run.py`.\n{prose}\n"
|
|
741
|
+
assert gate.missing_proof_reason(_mcp_create(body)) is None
|
|
742
|
+
|
|
743
|
+
|
|
744
|
+
def test_not_covered_heading_nested_under_the_proof_heading_should_stay_proof_text() -> None:
|
|
745
|
+
line = "Not run: an older shape."
|
|
746
|
+
body = f"## Proof in practice\nRan `python run.py`.\n\n### Not covered\n{line}\n"
|
|
747
|
+
assert gate.missing_proof_reason(_mcp_create(body)) == UNPROVEN_PROOF_REASON.format(admission=line)
|
|
748
|
+
|
|
749
|
+
|
|
750
|
+
def test_proof_made_only_of_a_nested_not_covered_line_should_be_denied() -> None:
|
|
751
|
+
line = "Not run: `python publish.py`"
|
|
752
|
+
body = f"## Proof in practice\n### Not covered\n{line}\n"
|
|
753
|
+
assert gate.missing_proof_reason(_mcp_create(body)) == UNPROVEN_PROOF_REASON.format(admission=line)
|
|
754
|
+
|
|
755
|
+
|
|
756
|
+
def test_merge_step_under_a_same_level_not_covered_heading_should_pass() -> None:
|
|
757
|
+
body = (
|
|
758
|
+
"## Proof in practice\nRan `python run.py`.\n\n## Not covered\n\n"
|
|
759
|
+
"Not run: the publish check that follows the merge.\n"
|
|
760
|
+
)
|
|
761
|
+
assert gate.missing_proof_reason(_mcp_create(body)) is None
|
|
762
|
+
|
|
763
|
+
|
|
764
|
+
def test_merge_word_line_should_return_the_line_or_none() -> None:
|
|
765
|
+
assert gate.merge_word_line("Ran `python run.py`.\nChecked after the merge.\n") == "Checked after the merge."
|
|
766
|
+
assert gate.merge_word_line("Ran `git merge main`.\n") is None
|
|
767
|
+
assert gate.merge_word_line("```\nmerged ok\n```\n") is None
|
|
@@ -63,7 +63,15 @@ TEST_ONLY_PROOF_REASON = (
|
|
|
63
63
|
" command in backticks and quote the output lines that show the difference. Keep the"
|
|
64
64
|
" test run in the section as extra evidence. Read " + PROOF_GUIDE_PATH + " for the full rule."
|
|
65
65
|
)
|
|
66
|
-
|
|
66
|
+
_LIST_MARKER = r"^\s*(?:(?:[-*>]|\d+[.)])\s*)*"
|
|
67
|
+
NOT_RUN_LINE_PATTERN = _LIST_MARKER + r"not (?:(?:yet|been) )*(?:run|ran|exercised|executed)(?![\w-])"
|
|
68
|
+
UNPROVEN_ADMISSION_PATTERN = (
|
|
69
|
+
r"\b(?:not (?:(?:yet|been|fully) )*(?:proven|tested|verified)|unproven|untested|unverified)\b"
|
|
70
|
+
r"|"
|
|
71
|
+
+ NOT_RUN_LINE_PATTERN
|
|
72
|
+
+ r"|\b(?:has|have)(?: not|n't) (?:yet )?been (?:run|exercised|executed)(?![\w-])"
|
|
73
|
+
)
|
|
74
|
+
MERGE_WORD_PATTERN = r"\bmerg(?:e|ed|es|ing)\b"
|
|
67
75
|
INLINE_CODE_SPAN_PATTERN = r"`[^`\n]*`"
|
|
68
76
|
BLOCKQUOTE_MARKERS = "> "
|
|
69
77
|
ALL_CODE_FENCE_MARKERS = ("```", "~~~")
|
|
@@ -75,6 +83,13 @@ UNPROVEN_PROOF_REASON = (
|
|
|
75
83
|
" target, move the line under a 'Not covered' heading at the same level as the proof"
|
|
76
84
|
" heading. Read " + PROOF_GUIDE_PATH + " for the full rule."
|
|
77
85
|
)
|
|
86
|
+
DEFERRED_PROOF_REASON = (
|
|
87
|
+
"This pull request's 'Proof in practice' section mentions a merge: \"{deferral}\". Run that"
|
|
88
|
+
" check on the branch before the review request and quote its output. Put a file or"
|
|
89
|
+
" command name that contains merge in backticks. A step that needs the merged code to"
|
|
90
|
+
" exist goes under a 'Not covered' heading at the same level as the proof heading, as"
|
|
91
|
+
" a line that opens with 'Not run:'. Read " + PROOF_GUIDE_PATH + " for the full rule."
|
|
92
|
+
)
|
|
78
93
|
EXISTING_WORK_HEADING_PATTERN = r"^(#{1,6})[ \t]+existing work[ \t]*#*[ \t]*$"
|
|
79
94
|
EXISTING_WORK_GUIDE_PATH = "~/.claude/docs/rule-guides/explore-thoroughly.md"
|
|
80
95
|
MISSING_EXISTING_WORK_REASON = (
|