claude-dev-env 8.126.6 → 8.127.0

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.
@@ -23,6 +23,8 @@ Apply the bar to each pull request, including each stack level. The bar only say
23
23
  - Over 400 lines, look for a seam that passes the four tests. When none passes, keep the slice whole and state the reason in the pull request body.
24
24
  - Over 1,000 lines, put that reason under a `## Why one pull request` heading.
25
25
 
26
+ The pull request lifecycle gate refuses a create over 1,000 changed lines against its base, with generated files and lockfiles left out. Create each stacked level with `--base` set to the branch below it, so each counts only its own lines. A body with a `## Why one pull request` heading and the reason under it passes.
27
+
26
28
  Sources: [Google small CLs](https://google.github.io/eng-practices/review/developer/small-cls.html) and [SmartBear code review practices](https://smartbear.com/learn/code-review/best-practices-for-peer-code-review/).
27
29
 
28
30
  ## Split a pull request that is already open
@@ -46,6 +46,8 @@ When you cannot prove it, leave the pull request unopened. Tell the owner in thr
46
46
 
47
47
  `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 each create spelling `hooks/blocking/followup_pr_dedupe.py` reads, and on each `mcp__*__create_pull_request` tool. The spellings are `gh pr create`, `gh pr new`, `gh` with a root `-R` or `--repo` before `pr`, a `GH_REPO=` prefix, and the `pull_request.py create` script run by any `python`, `python3.x`, `py` or `uv run` launcher, with interpreter options or a path to the script. 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 line passes only for a workflow file the branch adds, when the body's "After merge" heading plans that file's first run; `pull_request_proof.py` and `hooks_constants/pull_request_proof_constants.py` hold the exact conditions. Otherwise 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. A body edit through `update_pull_request`, `gh pr edit` or the `pull_request.py edit` script gets the same checks on its proof section that a new pull request gets, so an edit cannot swap in a proof that a new pull request would be denied. An edit with no proof section passes. The gate also denies a new pull request whose "What this does" section holds no flowchart: a closed `mermaid` block whose first line starts with `flowchart` and that joins two nodes with an arrow. A body edit meets the same check when its body carries a "What this does" heading. A body the gate cannot read passes, such as an inline multi-line `--body`, a body from standard input, or a body written through `gh api`. A `--body-file` that is not a regular file (a pipe, a device or a directory) counts as no body: a create is denied with the request for the body, and an edit passes. Merges and pushes pass.
48
48
 
49
+ The gate also measures each new pull request against its own base, which is the `--base` branch the create names, else the repository's default branch. `hooks/blocking/oversized_change.py` counts the lines added and deleted since the head left that base, with git in the session directory, or with the GitHub compare API when git cannot tell. A file `.gitattributes` marks `linguist-generated` and a lockfile such as `uv.lock` or `package-lock.json` count zero, and so does a binary file. The compare API leaves out only lockfiles. A stacked level created with `--base <parent-branch>` counts only its own lines. Over 1,000 lines, the gate denies the create and points to `~/.claude/skills/pr-lifecycle/reference/split-a-pull-request.md`. A body with a "Why one pull request" heading, at any level, with the reason under it, passes. When git and the compare API cannot read the size, when the compare API returns its 300-file cap and lists 1,000 lines or fewer, or when no base resolves, the create passes. A body edit is not measured.
50
+
49
51
  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. A page the branch only moves to another folder or name that ends the same way, with every byte kept (`R100` in `git diff --name-status`), changes nothing people see, so the gate leaves it out; a moved page that also changed, or a file that becomes a page by a change of name ending, still needs the picture. When git in the session directory cannot list the branch's changed files, the gate asks for the picture as well. The gate looks for the picture first, so a proof section that holds one passes this check with no git read.
50
52
 
51
53
  The gate's git, GitHub CLI and web reads share one budget, counted from the gate start: the proof and picture reads have a deadline at 12 s, and the follow-up reads at 20 s. A stopped child read gets 1 s more to close its pipes, and a scan finishes the line it is parsing before it stops. The registered timeout in `hooks.json` is 30 s, and the budget test in `test_gate_run_reads.py` reserves two such graces and a 5 s margin inside it. A read the budget cuts short comes back unanswered, and the check that asked for it decides from that. A deny from such a run ends with a sentence that says the reads ran out of time, so a second run may pass. The transcript scans answer to the same deadlines: the `pr-lifecycle` scan to 12 s and the build-eval scan to 20 s. A scan reads the clock before each file block and before each line, and a line over 16 MiB ends the scan as a passed deadline does. A scan the deadline stops counts as not found, and its deny says to load the skill, or call build-eval, again. A transcript that cannot seek to its end is first copied forward into memory, and a copy that passes 64 MiB ends the scan as a passed deadline does. On POSIX a stopped child read is killed with its process group, and a process that left that group by starting its own session is outside it. On Windows the child joins a job object right after it starts, and the gate ends the job, which also ends a grandchild that still holds the pipe after the child exited. When no job could be made or ended, a bounded `taskkill /T /F` runs instead. A process the child starts before it joins the job is outside the job. A follow-up create is refused when the read of open pull requests gives no answer in time, or when the create names no repository and the origin remote cannot be read.
@@ -43,6 +43,7 @@ def started_child(
43
43
  all_command_words: Sequence[str],
44
44
  working_directory: str | None,
45
45
  all_environment_variables: Mapping[str, str] | None,
46
+ takes_standard_input: bool = False,
46
47
  ) -> subprocess.Popen[str] | None:
47
48
  """Start one read-only child with its output piped, or None when it cannot start.
48
49
 
@@ -50,13 +51,14 @@ def started_child(
50
51
  all_command_words: The program and its arguments.
51
52
  working_directory: The directory the child runs in, or None for the gate's own.
52
53
  all_environment_variables: The child's whole environment, or None for the gate's own.
54
+ takes_standard_input: Whether the child's input is a pipe the caller writes, else empty.
53
55
  """
54
56
  try:
55
57
  return subprocess.Popen(
56
58
  list(all_command_words),
57
59
  cwd=working_directory or None,
58
60
  env=dict(all_environment_variables) if all_environment_variables is not None else None,
59
- stdin=subprocess.DEVNULL,
61
+ stdin=subprocess.PIPE if takes_standard_input else subprocess.DEVNULL,
60
62
  stdout=subprocess.PIPE,
61
63
  stderr=subprocess.DEVNULL,
62
64
  text=True,
@@ -271,6 +271,7 @@ def child_stdout(
271
271
  read_slice: ReadSlice,
272
272
  working_directory: str | None = None,
273
273
  all_environment_variables: Mapping[str, str] | None = None,
274
+ standard_input: str | None = None,
274
275
  ) -> str | None:
275
276
  """Run one read-only child and return its output, or None when it gives no answer.
276
277
 
@@ -287,26 +288,33 @@ def child_stdout(
287
288
  read_slice: The slice whose deadline the read answers to.
288
289
  working_directory: The directory the child runs in, or None for the gate's own.
289
290
  all_environment_variables: The child's whole environment, or None for the gate's own.
291
+ standard_input: The text written to the child's input, or None for an empty input.
290
292
  """
291
293
  allowance = read_allowance(own_timeout_seconds, read_slice)
292
294
  if allowance is None:
293
295
  _note_read_cut_short()
294
296
  return None
295
- child = started_child(all_command_words, working_directory, all_environment_variables)
297
+ child = started_child(
298
+ all_command_words, working_directory, all_environment_variables, standard_input is not None
299
+ )
296
300
  if child is None:
297
301
  return None
298
302
  job = job_holding(child)
299
303
  try:
300
- return _answer_within(child, allowance, own_timeout_seconds, job)
304
+ return _answer_within(child, allowance, own_timeout_seconds, job, standard_input)
301
305
  finally:
302
306
  close_job(job)
303
307
 
304
308
 
305
309
  def _answer_within(
306
- child: subprocess.Popen[str], allowance: float, own_timeout_seconds: float, job: int | None
310
+ child: subprocess.Popen[str],
311
+ allowance: float,
312
+ own_timeout_seconds: float,
313
+ job: int | None,
314
+ standard_input: str | None,
307
315
  ) -> str | None:
308
316
  try:
309
- printed_text = child.communicate(timeout=allowance)[0]
317
+ printed_text = child.communicate(input=standard_input, timeout=allowance)[0]
310
318
  except subprocess.TimeoutExpired:
311
319
  stop_child(child, job)
312
320
  _note_read_timed_out()
@@ -0,0 +1,310 @@
1
+ """Deny a new pull request that changes more than 1,000 lines against its own base, unless its body says why it stays one.
2
+
3
+ ::
4
+
5
+ branch changes 1,500 lines against main, plain body -> OVERSIZED_PULL_REQUEST_REASON
6
+ same branch, body has a 'Why one pull request' section -> None
7
+ stacked level, --base parent, 200 lines of its own -> None
8
+ compare API at its file cap, listed files over the bar -> OVERSIZED_PULL_REQUEST_REASON
9
+ compare API at its file cap, listed files under the bar -> None
10
+ size unreadable or no base -> None
11
+
12
+ Generated files, marked ``linguist-generated`` in ``.gitattributes``, and
13
+ lockfiles are left out. A binary file counts zero lines.
14
+ """
15
+
16
+ from __future__ import annotations
17
+
18
+ import json
19
+ import sys
20
+ from collections.abc import Iterator, Mapping
21
+ from pathlib import Path
22
+
23
+ hooks_directory = str(Path(__file__).resolve().parent.parent)
24
+ if hooks_directory not in sys.path:
25
+ sys.path.insert(0, hooks_directory)
26
+
27
+ from blocking.gate_run_reads import answer_once
28
+ from blocking.pull_request_proof import (
29
+ CreateCall,
30
+ _all_section_texts,
31
+ _cached_head_reference,
32
+ _compare_lines,
33
+ _create_calls,
34
+ _first_merge_base,
35
+ _git_lines,
36
+ _git_output,
37
+ _merge_base_and_head,
38
+ checkout_is_for,
39
+ )
40
+ from hooks_constants.pull_request_proof_constants import (
41
+ COMPARE_FILE_LIST_LIMIT,
42
+ REMOTE_BRANCH_PREFIX,
43
+ )
44
+ from hooks_constants.oversized_change_constants import (
45
+ ALL_GENERATED_ATTRIBUTE_VALUES,
46
+ ALL_LOCKFILE_NAMES,
47
+ BINARY_NUMSTAT_COUNT,
48
+ MEASURED_LINE_BAR,
49
+ CHECK_ATTR_FIELD_COUNT,
50
+ COMPARE_LINE_COUNT_QUERY,
51
+ LINGUIST_GENERATED_ATTRIBUTE,
52
+ NUMSTAT_FIELD_COUNT,
53
+ NUMSTAT_FIELD_SEPARATOR,
54
+ ONE_PULL_REQUEST_HEADING_PATTERN,
55
+ OVERSIZED_PULL_REQUEST_REASON,
56
+ RENAME_DETECTION_LIMIT_OPTION,
57
+ )
58
+
59
+
60
+ def oversized_pull_request_reason(all_payload_fields: Mapping[str, object]) -> str | None:
61
+ """Return a deny reason when a new pull request changes more lines than the bar, else None.
62
+
63
+ ::
64
+
65
+ create, 1,500 changed lines, no 'Why one pull request' section -> OVERSIZED_PULL_REQUEST_REASON
66
+ create, 1,500 changed lines, the section states a reason -> None
67
+ create, 900 changed lines -> None
68
+ create whose size git and the compare API cannot read -> None
69
+ a body edit, a merge, any other tool -> None
70
+
71
+ A body that holds the section passes with no read. Each create is measured
72
+ against its own base, so a stacked level counts only its own lines.
73
+
74
+ Args:
75
+ all_payload_fields: The parsed PreToolUse input.
76
+ """
77
+ working_directory = str(all_payload_fields.get("cwd") or "")
78
+ for each_call in _create_calls(all_payload_fields):
79
+ if each_call.body is None or any(
80
+ _all_section_texts(each_call.body, ONE_PULL_REQUEST_HEADING_PATTERN)
81
+ ):
82
+ continue
83
+ measured_line_count = _measured_line_count_for_create(each_call, working_directory)
84
+ if measured_line_count is not None and measured_line_count > MEASURED_LINE_BAR:
85
+ return OVERSIZED_PULL_REQUEST_REASON.format(
86
+ measured_line_count=measured_line_count, measured_line_bar=MEASURED_LINE_BAR
87
+ )
88
+ return None
89
+
90
+
91
+ def _measured_line_count_for_create(create_call: CreateCall, working_directory: str) -> int | None:
92
+ repository, base_branch, head_branch = (
93
+ create_call.repository,
94
+ create_call.base,
95
+ create_call.head,
96
+ )
97
+ return answer_once(
98
+ ("changed line count", working_directory, repository, base_branch, head_branch),
99
+ lambda: _read_measured_line_count(working_directory, repository, base_branch, head_branch),
100
+ )
101
+
102
+
103
+ def _read_measured_line_count(
104
+ working_directory: str, repository: str | None, base_branch: str | None, head_branch: str | None
105
+ ) -> int | None:
106
+ measured_line_count = None
107
+ if working_directory and checkout_is_for(working_directory, repository):
108
+ measured_line_count = local_measured_line_count(working_directory, base_branch, head_branch)
109
+ if measured_line_count is None:
110
+ measured_line_count = remote_measured_line_count(repository, base_branch, head_branch)
111
+ return measured_line_count
112
+
113
+
114
+ def local_measured_line_count(
115
+ working_directory: str, base_branch: str | None, head_branch: str | None
116
+ ) -> int | None:
117
+ """Return the lines the head branch adds and deletes since it left its base, or None when git cannot tell.
118
+
119
+ ::
120
+
121
+ feature adds 1,200 lines to tool.py over main -> 1200
122
+ stacked level, base "parent", 200 lines of its own -> 200
123
+ feature also adds a 5,000-line linguist-generated file -> 1200
124
+ base names a branch the clone does not hold -> None
125
+
126
+ The head is the checked-out branch, or the named branch or its origin copy.
127
+ The base is ``origin/<base>`` or ``<base>``, else the first of origin/HEAD,
128
+ origin/main and main. A rename counts only its edited lines.
129
+
130
+ Args:
131
+ working_directory: The session directory the hook payload names.
132
+ base_branch: The base branch the create call names, or None.
133
+ head_branch: The head branch the create call names, or None.
134
+ """
135
+ merge_base_and_head = _merge_base_and_head_for_base(working_directory, base_branch, head_branch)
136
+ if merge_base_and_head is None:
137
+ return None
138
+ merge_base, head_reference = merge_base_and_head
139
+ numstat_output = _numstat_output(working_directory, merge_base, head_reference)
140
+ if numstat_output is None:
141
+ return None
142
+ count_by_path = _counts_without_lockfiles(numstat_output)
143
+ if count_by_path is None:
144
+ return None
145
+ if sum(count_by_path.values()) <= MEASURED_LINE_BAR:
146
+ return sum(count_by_path.values())
147
+ all_generated_paths = _generated_paths(working_directory, head_reference, list(count_by_path))
148
+ if all_generated_paths is None:
149
+ return None
150
+ return sum(
151
+ each_count
152
+ for each_path, each_count in count_by_path.items()
153
+ if each_path not in all_generated_paths
154
+ )
155
+
156
+
157
+ def _numstat_output(working_directory: str, merge_base: str, head_reference: str) -> str | None:
158
+ return _git_output(
159
+ working_directory,
160
+ "diff",
161
+ "--numstat",
162
+ "--no-relative",
163
+ "-z",
164
+ "-M",
165
+ RENAME_DETECTION_LIMIT_OPTION,
166
+ merge_base,
167
+ head_reference,
168
+ )
169
+
170
+
171
+ def _counts_without_lockfiles(numstat_output: str) -> dict[str, int] | None:
172
+ count_by_path = _numstat_counts(numstat_output)
173
+ if count_by_path is None:
174
+ return None
175
+ return {
176
+ each_path: each_count
177
+ for each_path, each_count in count_by_path.items()
178
+ if not _is_lockfile(each_path)
179
+ }
180
+
181
+
182
+ def _merge_base_and_head_for_base(
183
+ working_directory: str, base_branch: str | None, head_branch: str | None
184
+ ) -> tuple[str, str] | None:
185
+ if not base_branch:
186
+ return _merge_base_and_head(working_directory, head_branch)
187
+ head_reference = _cached_head_reference(working_directory, head_branch)
188
+ if head_reference is None:
189
+ return None
190
+ merge_base = _first_merge_base(
191
+ working_directory, head_reference, (REMOTE_BRANCH_PREFIX + base_branch, base_branch)
192
+ )
193
+ return None if merge_base is None else (merge_base, head_reference)
194
+
195
+
196
+ def _numstat_counts(numstat_output: str) -> dict[str, int] | None:
197
+ count_by_path: dict[str, int] = {}
198
+ all_fields = iter(numstat_output.split("\0"))
199
+ for each_field in all_fields:
200
+ if not each_field:
201
+ return count_by_path
202
+ all_counts_and_path = each_field.split(NUMSTAT_FIELD_SEPARATOR, NUMSTAT_FIELD_COUNT - 1)
203
+ if len(all_counts_and_path) != NUMSTAT_FIELD_COUNT:
204
+ return None
205
+ added_text, deleted_text, listed_path = all_counts_and_path
206
+ path = listed_path or _new_path_of_rename(all_fields)
207
+ line_count = _numstat_line_count(added_text, deleted_text)
208
+ if not path or line_count is None:
209
+ return None
210
+ count_by_path[path] = count_by_path.get(path, 0) + line_count
211
+ return count_by_path
212
+
213
+
214
+ def _new_path_of_rename(all_fields: Iterator[str]) -> str | None:
215
+ next(all_fields, None)
216
+ return next(all_fields, None)
217
+
218
+
219
+ def _numstat_line_count(added_text: str, deleted_text: str) -> int | None:
220
+ if added_text == BINARY_NUMSTAT_COUNT and deleted_text == BINARY_NUMSTAT_COUNT:
221
+ return 0
222
+ if not added_text.isdigit() or not deleted_text.isdigit():
223
+ return None
224
+ return int(added_text) + int(deleted_text)
225
+
226
+
227
+ def _generated_paths(
228
+ working_directory: str, head_reference: str, all_paths: list[str]
229
+ ) -> set[str] | None:
230
+ if not all_paths:
231
+ return set()
232
+ all_top_level_lines = _git_lines(working_directory, "rev-parse", "--show-toplevel")
233
+ if not all_top_level_lines:
234
+ return None
235
+ check_attr_output = _generated_attribute_output(
236
+ all_top_level_lines[0], head_reference, all_paths
237
+ )
238
+ if check_attr_output is None:
239
+ return None
240
+ all_fields = check_attr_output.split("\0")
241
+ return {
242
+ all_fields[each_index]
243
+ for each_index in range(
244
+ 0, len(all_fields) - CHECK_ATTR_FIELD_COUNT + 1, CHECK_ATTR_FIELD_COUNT
245
+ )
246
+ if all_fields[each_index + 2] in ALL_GENERATED_ATTRIBUTE_VALUES
247
+ }
248
+
249
+
250
+ def _generated_attribute_output(
251
+ top_level_directory: str, head_reference: str, all_paths: list[str]
252
+ ) -> str | None:
253
+ standard_input = "".join(each_path + "\0" for each_path in all_paths)
254
+ for each_source_arguments in (("--source=" + head_reference,), ()):
255
+ check_attr_output = _git_output(
256
+ top_level_directory,
257
+ "check-attr",
258
+ "-z",
259
+ "--stdin",
260
+ *each_source_arguments,
261
+ LINGUIST_GENERATED_ATTRIBUTE,
262
+ standard_input=standard_input,
263
+ )
264
+ if check_attr_output is not None:
265
+ return check_attr_output
266
+ return None
267
+
268
+
269
+ def _is_lockfile(path: str) -> bool:
270
+ return path.rsplit("/", 1)[-1] in ALL_LOCKFILE_NAMES
271
+
272
+
273
+ def remote_measured_line_count(
274
+ repository: str | None, base_branch: str | None, head_branch: str | None
275
+ ) -> int | None:
276
+ """Return the lines the GitHub compare API reports between base and head, or None when it cannot tell.
277
+
278
+ ::
279
+
280
+ compare lists tool.py +1200 -0 -> 1200
281
+ compare lists only uv.lock +3000 -0 -> 0
282
+ compare returns 300 files listing 5000 lines -> 5000
283
+ compare returns 300 files listing 500 lines -> None
284
+ repository or head missing -> None
285
+
286
+ The base is the named base branch, else the repository's default branch.
287
+ The compare API does not read ``.gitattributes``, so only lockfiles are left out.
288
+ At its file cap the listed files are a lower bound, so the count stands only over the bar.
289
+
290
+ Args:
291
+ repository: The owner/name the create call names, or None.
292
+ base_branch: The base branch the create call names, or None.
293
+ head_branch: The head branch the create call names, or None.
294
+ """
295
+ all_lines = _compare_lines(repository, base_branch, head_branch, COMPARE_LINE_COUNT_QUERY)
296
+ if not all_lines or not all_lines[0].isdigit():
297
+ return None
298
+ measured_line_count = 0
299
+ for each_line in all_lines[1:]:
300
+ try:
301
+ path, added_count, deleted_count = json.loads(each_line)
302
+ except (ValueError, TypeError):
303
+ return None
304
+ if not isinstance(added_count, int) or not isinstance(deleted_count, int):
305
+ return None
306
+ if not _is_lockfile(str(path)):
307
+ measured_line_count += added_count + deleted_count
308
+ if int(all_lines[0]) >= COMPARE_FILE_LIST_LIMIT and measured_line_count <= MEASURED_LINE_BAR:
309
+ return None
310
+ return measured_line_count
@@ -94,6 +94,7 @@ from blocking.gate_run_reads import (
94
94
  from hooks_constants.gate_fault import gate_fault_reason
95
95
  from hooks_constants.gate_run_reads_constants import READS_RAN_OUT_SENTENCE
96
96
  from blocking import pull_request_proof as proof
97
+ from blocking.oversized_change import oversized_pull_request_reason
97
98
  from hooks_constants.pull_request_proof_constants import MISSING_BUILD_EVAL_REASON
98
99
  from transcript_skill_scan import (
99
100
  invokes_skill_with_argument,
@@ -394,6 +395,7 @@ def decision_for(all_payload_fields: dict[str, object]) -> dict[str, object] | N
394
395
  feature pull request with no eval section -> MISSING_EVAL_SECTION_REASON
395
396
  changed page whose proof shows no picture -> MISSING_LOOK_REASON
396
397
  feature pull request, no /claude-api build-eval -> MISSING_BUILD_EVAL_REASON
398
+ new pull request over 1,000 lines, no 'Why one pull request' -> OVERSIZED_PULL_REQUEST_REASON
397
399
  second follow-up pull request for one parent -> DUPLICATE_FOLLOWUP_REASON_TEMPLATE
398
400
  follow-up read of open pull requests unanswered -> UNANSWERED_FOLLOWUP_REASON_TEMPLATE
399
401
  follow-up with no repository, origin unread -> UNREAD_ORIGIN_FOLLOWUP_REASON_TEMPLATE
@@ -443,6 +445,7 @@ def _first_broken_rule_reason(all_fields: dict[str, object], run: GateRun) -> st
443
445
  or proof.missing_eval_section_reason(all_fields)
444
446
  or proof.missing_look_reason(all_fields)
445
447
  or _missing_build_eval_reason(all_fields, run)
448
+ or oversized_pull_request_reason(all_fields)
446
449
  or duplicate_followup_reason(all_fields)
447
450
  )
448
451
 
@@ -5,7 +5,7 @@ from __future__ import annotations
5
5
  import json
6
6
  import re
7
7
  import sys
8
- from collections.abc import Iterator, Mapping
8
+ from collections.abc import Iterator, Mapping, Sequence
9
9
  from typing import NamedTuple
10
10
  from pathlib import Path
11
11
 
@@ -135,15 +135,18 @@ def _lines_until_heading(all_lines: list[str], heading_level: int) -> list[str]:
135
135
  return all_lines
136
136
 
137
137
 
138
- def _section_text(body: str, heading_pattern: str) -> str | None:
138
+ def _all_section_texts(body: str, heading_pattern: str) -> Iterator[str]:
139
139
  all_lines = body.splitlines()
140
140
  all_fenced_flags = fenced_line_flags(all_lines)
141
141
  for each_index, each_line in enumerate(all_lines):
142
142
  heading_level = None if all_fenced_flags[each_index] else _heading_level(each_line, heading_pattern)
143
143
  if heading_level is not None:
144
144
  all_section_lines = _lines_until_heading(all_lines[each_index + 1 :], heading_level)
145
- return LINE_SEPARATOR.join(all_section_lines).strip()
146
- return None
145
+ yield LINE_SEPARATOR.join(all_section_lines).strip()
146
+
147
+
148
+ def _section_text(body: str, heading_pattern: str) -> str | None:
149
+ return next(_all_section_texts(body, heading_pattern), None)
147
150
 
148
151
 
149
152
  def proof_section(body: str) -> str | None:
@@ -670,9 +673,12 @@ class ChangedFile(NamedTuple):
670
673
  is_pure_rename: bool
671
674
 
672
675
 
673
- def _git_output(working_directory: str, *all_git_arguments: str) -> str | None:
676
+ def _git_output(working_directory: str, *all_git_arguments: str, standard_input: str | None = None) -> str | None:
674
677
  return child_stdout(
675
- ["git", "-C", working_directory, *all_git_arguments], GIT_TIMEOUT_SECONDS, ReadSlice.PROOF_AND_LOOK
678
+ ["git", "-C", working_directory, *all_git_arguments],
679
+ GIT_TIMEOUT_SECONDS,
680
+ ReadSlice.PROOF_AND_LOOK,
681
+ standard_input=standard_input,
676
682
  )
677
683
 
678
684
 
@@ -681,14 +687,26 @@ def _git_lines(working_directory: str, *all_git_arguments: str) -> list[str] | N
681
687
  return output.splitlines() if output is not None else None
682
688
 
683
689
 
684
- def _first_merge_base(working_directory: str, head_reference: str) -> str | None:
685
- for each_base_reference in ALL_DEFAULT_BRANCH_REFERENCES:
690
+ def _first_merge_base(
691
+ working_directory: str,
692
+ head_reference: str,
693
+ all_base_references: Sequence[str] = ALL_DEFAULT_BRANCH_REFERENCES,
694
+ ) -> str | None:
695
+ for each_base_reference in all_base_references:
686
696
  all_merge_base_lines = _git_lines(working_directory, "merge-base", head_reference, each_base_reference)
687
697
  if all_merge_base_lines:
688
698
  return all_merge_base_lines[0]
689
699
  return None
690
700
 
691
701
 
702
+ def _cached_head_reference(working_directory: str, head_branch: object) -> str | None:
703
+ named_head = head_branch if isinstance(head_branch, str) else None
704
+ return answer_once(
705
+ ("head reference", working_directory, named_head),
706
+ lambda: _head_reference(working_directory, named_head),
707
+ )
708
+
709
+
692
710
  def _head_reference(working_directory: str, head_branch: object) -> str | None:
693
711
  if not isinstance(head_branch, str) or not head_branch:
694
712
  return "HEAD"
@@ -745,7 +763,7 @@ def _merge_base_and_head(working_directory: str, head_branch: object) -> tuple[s
745
763
  def _read_merge_base_and_head(working_directory: str, head_branch: str | None) -> tuple[str, str] | None:
746
764
  if not working_directory:
747
765
  return None
748
- head_reference = _head_reference(working_directory, head_branch)
766
+ head_reference = _cached_head_reference(working_directory, head_branch)
749
767
  if head_reference is None:
750
768
  return None
751
769
  merge_base = _first_merge_base(working_directory, head_reference)
@@ -26,6 +26,12 @@ def test_started_child_should_pipe_the_output_of_a_child_that_starts() -> None:
26
26
  assert child.communicate(timeout=10)[0] == "answer\n"
27
27
 
28
28
 
29
+ def test_started_child_should_take_input_when_asked() -> None:
30
+ child = started_child([sys.executable, "-c", "import sys; print(sys.stdin.read())"], None, None, True)
31
+ assert child is not None
32
+ assert child.communicate(input="given", timeout=10)[0] == "given\n"
33
+
34
+
29
35
  def test_started_child_should_return_none_for_a_program_that_cannot_start(tmp_path: Path) -> None:
30
36
  assert started_child([str(tmp_path / "no-such-program")], None, None) is None
31
37
 
@@ -214,6 +214,13 @@ def test_child_stdout_should_return_the_output_of_a_child_that_answers() -> None
214
214
  assert not run.was_read_cut_short
215
215
 
216
216
 
217
+ def test_child_stdout_should_write_the_given_input_to_its_child() -> None:
218
+ echo_input = [sys.executable, "-c", "import sys; print(sys.stdin.read())"]
219
+ with gate_run():
220
+ assert child_stdout(echo_input, 5, ReadSlice.PROOF_AND_LOOK, standard_input="given") == "given\n"
221
+ assert child_stdout(echo_input, 5, ReadSlice.PROOF_AND_LOOK) == "\n"
222
+
223
+
217
224
  def test_child_stdout_should_start_its_child_with_the_environment_it_is_given() -> None:
218
225
  read_variable = [sys.executable, "-c", "import os; print(os.environ.get('GATE_READ_PROBE', 'unset'))"]
219
226
  environment = {**os.environ, "GATE_READ_PROBE": "given"}
@@ -0,0 +1,307 @@
1
+ """Behavior tests for the size check on a new pull request."""
2
+
3
+ import json
4
+ import subprocess
5
+ import sys
6
+ from pathlib import Path
7
+
8
+ import pytest
9
+
10
+ HOOKS_DIRECTORY = Path(__file__).resolve().parent.parent
11
+ if str(HOOKS_DIRECTORY) not in sys.path:
12
+ sys.path.insert(0, str(HOOKS_DIRECTORY))
13
+
14
+ from blocking import gate_run_reads
15
+ from blocking import oversized_change as size
16
+ from blocking import pull_request_proof as proof
17
+ from hooks_constants.oversized_change_constants import OVERSIZED_PULL_REQUEST_REASON
18
+
19
+ GIT_IDENTITY = ["-c", "user.name=Test", "-c", "user.email=test@example.com"]
20
+ PLAIN_BODY = "## What this does\nAdds a tool.\n"
21
+ ONE_PULL_REQUEST_BODY = (
22
+ PLAIN_BODY + "\n### Why one pull request\nThe schema and its reader must land together.\n"
23
+ )
24
+ EMPTY_ONE_PULL_REQUEST_BODY = PLAIN_BODY + "\n## Why one pull request\n\n## Risk\nLow.\n"
25
+
26
+
27
+ def _git(repository_path: Path, *all_arguments: str) -> None:
28
+ subprocess.run(["git", "-C", str(repository_path), *GIT_IDENTITY, *all_arguments], check=True)
29
+
30
+
31
+ def _commit_lines(repository_path: Path, file_name: str, line_count: int) -> None:
32
+ (repository_path / file_name).write_text(
33
+ "".join(f"line {i}\n" for i in range(line_count)), encoding="utf-8"
34
+ )
35
+ _git(repository_path, "add", ".")
36
+ _git(repository_path, "commit", "-q", "-m", f"add {file_name}")
37
+
38
+
39
+ def _clone_on_branch(tmp_path: Path, branch_name: str) -> Path:
40
+ origin_path = tmp_path / "origin"
41
+ clone_path = tmp_path / "clone"
42
+ subprocess.run(["git", "init", "-q", "-b", "main", str(origin_path)], check=True)
43
+ _commit_lines(origin_path, "README.md", 3)
44
+ subprocess.run(["git", "clone", "-q", str(origin_path), str(clone_path)], check=True)
45
+ _git(clone_path, "checkout", "-q", "-b", branch_name)
46
+ return clone_path
47
+
48
+
49
+ def _create(clone_path: Path, body: str, extra_flags: str = "") -> dict[str, object]:
50
+ (clone_path.parent / "body.md").write_text(body, encoding="utf-8")
51
+ return {
52
+ "tool_name": "Bash",
53
+ "tool_input": {
54
+ "command": f"gh pr create --title t --body-file ../body.md {extra_flags}".strip()
55
+ },
56
+ "cwd": str(clone_path),
57
+ }
58
+
59
+
60
+ @pytest.fixture
61
+ def large_branch(tmp_path: Path) -> Path:
62
+ clone_path = _clone_on_branch(tmp_path, "feature")
63
+ _commit_lines(clone_path, "tool.py", 1500)
64
+ return clone_path
65
+
66
+
67
+ def test_should_deny_a_create_over_the_bar_with_no_reason_section(large_branch: Path) -> None:
68
+ reason = size.oversized_pull_request_reason(_create(large_branch, PLAIN_BODY))
69
+ assert reason == OVERSIZED_PULL_REQUEST_REASON.format(
70
+ measured_line_count=1500, measured_line_bar=1000
71
+ )
72
+
73
+
74
+ def test_should_pass_a_create_over_the_bar_whose_body_says_why_it_stays_one(
75
+ large_branch: Path,
76
+ ) -> None:
77
+ assert size.oversized_pull_request_reason(_create(large_branch, ONE_PULL_REQUEST_BODY)) is None
78
+
79
+
80
+ def test_should_deny_when_the_reason_section_is_empty(large_branch: Path) -> None:
81
+ reason = size.oversized_pull_request_reason(_create(large_branch, EMPTY_ONE_PULL_REQUEST_BODY))
82
+ assert reason == OVERSIZED_PULL_REQUEST_REASON.format(
83
+ measured_line_count=1500, measured_line_bar=1000
84
+ )
85
+
86
+
87
+ def test_should_pass_a_create_under_the_bar(tmp_path: Path) -> None:
88
+ clone_path = _clone_on_branch(tmp_path, "feature")
89
+ _commit_lines(clone_path, "tool.py", 900)
90
+ assert size.oversized_pull_request_reason(_create(clone_path, PLAIN_BODY)) is None
91
+
92
+
93
+ def test_should_count_a_stacked_level_against_its_own_base(tmp_path: Path) -> None:
94
+ clone_path = _clone_on_branch(tmp_path, "parent")
95
+ _commit_lines(clone_path, "library.py", 1500)
96
+ _git(clone_path, "push", "-q", "origin", "parent")
97
+ _git(clone_path, "checkout", "-q", "-b", "child")
98
+ _commit_lines(clone_path, "caller.py", 200)
99
+ assert (
100
+ size.oversized_pull_request_reason(_create(clone_path, PLAIN_BODY, "--base parent")) is None
101
+ )
102
+ assert size.local_measured_line_count(str(clone_path), "parent", None) == 200
103
+ assert (
104
+ size.oversized_pull_request_reason(_create(clone_path, PLAIN_BODY, "--base main"))
105
+ is not None
106
+ )
107
+
108
+
109
+ def test_should_leave_out_linguist_generated_files_and_lockfiles(tmp_path: Path) -> None:
110
+ clone_path = _clone_on_branch(tmp_path, "feature")
111
+ (clone_path / ".gitattributes").write_text(
112
+ "schema/*.json linguist-generated\n", encoding="utf-8"
113
+ )
114
+ (clone_path / "schema").mkdir()
115
+ _commit_lines(clone_path, "schema/types.json", 3000)
116
+ _commit_lines(clone_path, "uv.lock", 2000)
117
+ _commit_lines(clone_path, "tool.py", 40)
118
+ assert size.local_measured_line_count(str(clone_path), None, None) == 41
119
+ assert size.oversized_pull_request_reason(_create(clone_path, PLAIN_BODY)) is None
120
+
121
+
122
+ def test_should_count_only_the_edited_lines_of_a_rename(large_branch: Path) -> None:
123
+ _git(large_branch, "push", "-q", "origin", "feature")
124
+ _git(large_branch, "checkout", "-q", "-b", "move")
125
+ _git(large_branch, "mv", "tool.py", "moved_tool.py")
126
+ _git(large_branch, "commit", "-q", "-m", "move")
127
+ assert size.local_measured_line_count(str(large_branch), "feature", None) == 0
128
+
129
+
130
+ def test_should_pass_a_body_edit(large_branch: Path) -> None:
131
+ (large_branch.parent / "body.md").write_text(PLAIN_BODY, encoding="utf-8")
132
+ payload = {
133
+ "tool_name": "Bash",
134
+ "tool_input": {"command": "gh pr edit 7 --body-file ../body.md"},
135
+ "cwd": str(large_branch),
136
+ }
137
+ assert size.oversized_pull_request_reason(payload) is None
138
+
139
+
140
+ def test_should_pass_when_no_base_can_be_resolved(large_branch: Path) -> None:
141
+ assert size.local_measured_line_count(str(large_branch), "no-such-branch", None) is None
142
+ assert (
143
+ size.oversized_pull_request_reason(
144
+ _create(large_branch, PLAIN_BODY, "--base no-such-branch")
145
+ )
146
+ is None
147
+ )
148
+
149
+
150
+ def test_remote_count_should_sum_files_and_leave_out_lockfiles(
151
+ monkeypatch: pytest.MonkeyPatch,
152
+ ) -> None:
153
+ all_compare_lines = [
154
+ "2",
155
+ json.dumps(["tool.py", 1100, 100]),
156
+ json.dumps(["web/package-lock.json", 900, 0]),
157
+ ]
158
+ monkeypatch.setattr(size, "_compare_lines", lambda *all_arguments: all_compare_lines)
159
+ assert size.remote_measured_line_count("o/r", "main", "feature") == 1200
160
+
161
+
162
+ def test_remote_count_should_be_unknown_at_the_compare_file_cap_under_the_bar(
163
+ monkeypatch: pytest.MonkeyPatch,
164
+ ) -> None:
165
+ monkeypatch.setattr(
166
+ size, "_compare_lines", lambda *all_arguments: ["300", json.dumps(["a.py", 500, 0])]
167
+ )
168
+ assert size.remote_measured_line_count("o/r", "main", "feature") is None
169
+
170
+
171
+ def test_remote_count_should_return_the_listed_lines_at_the_file_cap_when_they_pass_the_bar(
172
+ monkeypatch: pytest.MonkeyPatch,
173
+ ) -> None:
174
+ monkeypatch.setattr(
175
+ size, "_compare_lines", lambda *all_arguments: ["300", json.dumps(["a.py", 5000, 0])]
176
+ )
177
+ assert size.remote_measured_line_count("o/r", "main", "feature") == 5000
178
+
179
+
180
+ def _generated_schema_branch(tmp_path: Path) -> Path:
181
+ clone_path = _clone_on_branch(tmp_path, "feature")
182
+ (clone_path / ".gitattributes").write_text(
183
+ "schema/*.json linguist-generated\n", encoding="utf-8"
184
+ )
185
+ (clone_path / "schema").mkdir()
186
+ (clone_path / "sub").mkdir()
187
+ _commit_lines(clone_path, "schema/types.json", 3000)
188
+ _commit_lines(clone_path, "sub/tool.py", 40)
189
+ return clone_path
190
+
191
+
192
+ def test_should_leave_out_generated_files_when_the_session_sits_in_a_subdirectory(
193
+ tmp_path: Path,
194
+ ) -> None:
195
+ clone_path = _generated_schema_branch(tmp_path)
196
+ assert size.local_measured_line_count(str(clone_path), None, None) == 41
197
+ assert size.local_measured_line_count(str(clone_path / "sub"), None, None) == 41
198
+
199
+
200
+ def test_should_read_attributes_of_a_path_list_longer_than_the_argument_limit(
201
+ tmp_path: Path,
202
+ ) -> None:
203
+ clone_path = _clone_on_branch(tmp_path, "feature")
204
+ deep_directory = Path(*["d" * 200] * 15)
205
+ (clone_path / deep_directory).mkdir(parents=True)
206
+ (clone_path / ".gitattributes").write_text("*.json linguist-generated\n", encoding="utf-8")
207
+ for each_index in range(700):
208
+ (clone_path / deep_directory / f"{each_index:04d}{'n' * 150}.json").write_text(
209
+ "x\nx\n", encoding="utf-8"
210
+ )
211
+ _commit_lines(clone_path, "tool.py", 40)
212
+ assert size.local_measured_line_count(str(clone_path), None, None) == 41
213
+
214
+
215
+ def test_should_ask_git_for_the_head_once_when_the_proof_check_already_did(
216
+ large_branch: Path, monkeypatch: pytest.MonkeyPatch
217
+ ) -> None:
218
+ all_started_commands: list[list[str]] = []
219
+ start_child = gate_run_reads.started_child
220
+
221
+ def recording_start(all_command_words: list[str], *all_arguments: object) -> object:
222
+ all_started_commands.append(list(all_command_words))
223
+ return start_child(all_command_words, *all_arguments)
224
+
225
+ monkeypatch.setattr(gate_run_reads, "started_child", recording_start)
226
+ with gate_run_reads.gate_run():
227
+ assert proof.visible_changed_files(str(large_branch), "feature") == []
228
+ assert size.local_measured_line_count(str(large_branch), None, "feature") == 1500
229
+ assert sum("--show-current" in each_command for each_command in all_started_commands) == 1
230
+
231
+
232
+ def test_should_read_worktree_attributes_when_git_cannot_read_them_from_the_head(
233
+ tmp_path: Path, monkeypatch: pytest.MonkeyPatch
234
+ ) -> None:
235
+ clone_path = _generated_schema_branch(tmp_path)
236
+ read_git = size._git_output
237
+
238
+ def git_without_attribute_source(
239
+ working_directory: str, *all_arguments: str, **all_options: object
240
+ ) -> str | None:
241
+ if any(each_argument.startswith("--source=") for each_argument in all_arguments):
242
+ return None
243
+ return read_git(working_directory, *all_arguments, **all_options)
244
+
245
+ monkeypatch.setattr(size, "_git_output", git_without_attribute_source)
246
+ assert size.local_measured_line_count(str(clone_path), None, None) == 41
247
+
248
+
249
+ def test_should_measure_remotely_when_the_create_names_another_repository(
250
+ large_branch: Path, monkeypatch: pytest.MonkeyPatch
251
+ ) -> None:
252
+ monkeypatch.setattr(size, "remote_measured_line_count", lambda *all_arguments: None)
253
+ payload = _create(large_branch, PLAIN_BODY, "--repo other-owner/other-repository")
254
+ assert size.oversized_pull_request_reason(payload) is None
255
+
256
+
257
+ def test_should_find_the_merge_base_once_when_the_proof_check_already_did(
258
+ large_branch: Path, monkeypatch: pytest.MonkeyPatch
259
+ ) -> None:
260
+ all_started_commands: list[list[str]] = []
261
+ start_child = gate_run_reads.started_child
262
+
263
+ def recording_start(all_command_words: list[str], *all_arguments: object) -> object:
264
+ all_started_commands.append(list(all_command_words))
265
+ return start_child(all_command_words, *all_arguments)
266
+
267
+ monkeypatch.setattr(gate_run_reads, "started_child", recording_start)
268
+ with gate_run_reads.gate_run():
269
+ assert proof.visible_changed_files(str(large_branch), None) == []
270
+ assert size.local_measured_line_count(str(large_branch), None, None) == 1500
271
+ assert sum("merge-base" in each_command for each_command in all_started_commands) == 1
272
+
273
+
274
+ def test_should_count_only_the_edited_lines_of_renames_past_the_rename_limit(
275
+ large_branch: Path,
276
+ ) -> None:
277
+ _commit_lines(large_branch, "other_tool.py", 100)
278
+ _git(large_branch, "push", "-q", "origin", "feature")
279
+ _git(large_branch, "checkout", "-q", "-b", "move")
280
+ _git(large_branch, "config", "diff.renameLimit", "1")
281
+ for each_name in ("tool.py", "other_tool.py"):
282
+ _git(large_branch, "mv", each_name, "moved_" + each_name)
283
+ with (large_branch / ("moved_" + each_name)).open("a", encoding="utf-8") as moved_file:
284
+ moved_file.write("one more line\n")
285
+ _git(large_branch, "commit", "-q", "-am", "move")
286
+ assert size.local_measured_line_count(str(large_branch), "feature", None) == 2
287
+
288
+
289
+ def test_should_pass_when_a_later_reason_section_states_the_reason(large_branch: Path) -> None:
290
+ body = (
291
+ EMPTY_ONE_PULL_REQUEST_BODY
292
+ + "\n## Why one pull request\nThe schema and its reader land together.\n"
293
+ )
294
+ assert size.oversized_pull_request_reason(_create(large_branch, body)) is None
295
+
296
+
297
+ def test_should_pass_a_reason_heading_that_ends_in_punctuation(large_branch: Path) -> None:
298
+ body = PLAIN_BODY + "\n## Why one pull request?\nThe schema and its reader land together.\n"
299
+ assert size.oversized_pull_request_reason(_create(large_branch, body)) is None
300
+
301
+
302
+ def test_should_count_the_whole_branch_when_git_diffs_relative_to_the_session_folder(
303
+ tmp_path: Path,
304
+ ) -> None:
305
+ clone_path = _generated_schema_branch(tmp_path)
306
+ _git(clone_path, "config", "diff.relative", "true")
307
+ assert size.local_measured_line_count(str(clone_path / "sub"), None, None) == 41
@@ -28,6 +28,7 @@ from hooks_constants.gate_run_reads_constants import (
28
28
  PROOF_AND_LOOK_READS_SECONDS,
29
29
  READS_RAN_OUT_SENTENCE,
30
30
  )
31
+ from hooks_constants.oversized_change_constants import OVERSIZED_PULL_REQUEST_REASON
31
32
  from hooks_constants.pr_lifecycle_skill_gate_constants import DENY_REASON, SCAN_RAN_OUT_SENTENCE
32
33
  from hooks_constants.pull_request_proof_constants import (
33
34
  MISSING_BUILD_EVAL_REASON,
@@ -866,3 +867,49 @@ def test_fault_before_the_call_is_known_governed_should_not_become_a_deny(
866
867
  monkeypatch.setattr(gate, "_matches_shell_command", matcher_that_raises)
867
868
  with pytest.raises(RuntimeError, match="matcher fault"):
868
869
  gate.decision_for(_payload("ls", _transcript(tmp_path)))
870
+
871
+
872
+ def _clone_with_branch_lines(tmp_path: Path, line_count: int, body: str = "## Summary\nNo proof yet.\n") -> Path:
873
+ origin_path = tmp_path / "origin"
874
+ clone_path = tmp_path / "clone"
875
+ git_identity = ["-c", "user.name=Test", "-c", "user.email=test@example.com"]
876
+ subprocess.run(["git", "init", "-q", "-b", "main", str(origin_path)], check=True)
877
+ (origin_path / "README.md").write_text("base\n", encoding="utf-8")
878
+ subprocess.run(["git", "-C", str(origin_path), "add", "."], check=True)
879
+ subprocess.run(["git", "-C", str(origin_path), *git_identity, "commit", "-q", "-m", "base"], check=True)
880
+ subprocess.run(["git", "clone", "-q", str(origin_path), str(clone_path)], check=True)
881
+ subprocess.run(["git", "-C", str(clone_path), "checkout", "-q", "-b", "feature"], check=True)
882
+ (clone_path / "tool.py").write_text("".join(f"x = {i}\n" for i in range(line_count)), encoding="utf-8")
883
+ subprocess.run(["git", "-C", str(clone_path), "add", "."], check=True)
884
+ subprocess.run(["git", "-C", str(clone_path), *git_identity, "commit", "-q", "-m", "change"], check=True)
885
+ (tmp_path / "body.md").write_text(body, encoding="utf-8")
886
+ return clone_path
887
+
888
+
889
+ def _body_file_create(clone_path: Path) -> dict[str, object]:
890
+ return {
891
+ "tool_name": "Bash",
892
+ "tool_input": {"command": "gh pr create --title t --body-file ../body.md"},
893
+ "cwd": str(clone_path),
894
+ }
895
+
896
+
897
+ def test_should_read_the_proof_of_an_oversized_create_before_its_size(tmp_path: Path) -> None:
898
+ decision = gate.decision_for(_body_file_create(_clone_with_branch_lines(tmp_path, 1500)))
899
+ assert decision is not None
900
+ assert decision["hookSpecificOutput"]["permissionDecisionReason"] == MISSING_PROOF_REASON
901
+
902
+
903
+ def test_should_deny_an_oversized_create_whose_other_sections_pass(tmp_path: Path) -> None:
904
+ body = PROVEN_FOLLOWUP_BODY.replace("Follow-up to #1731", "Adds a guard.")
905
+ decision = gate.decision_for(_body_file_create(_clone_with_branch_lines(tmp_path, 1500, body)))
906
+ assert decision is not None
907
+ assert decision["hookSpecificOutput"]["permissionDecisionReason"] == OVERSIZED_PULL_REQUEST_REASON.format(
908
+ measured_line_count=1500, measured_line_bar=1000
909
+ )
910
+
911
+
912
+ def test_should_read_the_proof_of_a_create_under_the_size_bar(tmp_path: Path) -> None:
913
+ decision = gate.decision_for(_body_file_create(_clone_with_branch_lines(tmp_path, 20)))
914
+ assert decision is not None
915
+ assert decision["hookSpecificOutput"]["permissionDecisionReason"] == MISSING_PROOF_REASON
@@ -1745,3 +1745,44 @@ def test_chained_creates_should_read_the_compare_api_once_per_distinct_head(
1745
1745
  with gate_run():
1746
1746
  assert gate.missing_look_reason(_shell(command, tmp_path)) is None
1747
1747
  assert all_endpoints == ["repos/o/r/compare/main...x", "repos/o/r/compare/main...y"]
1748
+
1749
+
1750
+ def _run_git(repository_path: Path, *all_arguments: str) -> None:
1751
+ identity = ["-c", "user.name=Test", "-c", "user.email=test@example.com"]
1752
+ subprocess.run(["git", "-C", str(repository_path), *identity, *all_arguments], check=True)
1753
+
1754
+
1755
+ def _commit_file(repository_path: Path, file_name: str) -> None:
1756
+ (repository_path / file_name).write_text("x\n", encoding="utf-8")
1757
+ _run_git(repository_path, "add", ".")
1758
+ _run_git(repository_path, "commit", "-q", "-m", f"add {file_name}")
1759
+
1760
+
1761
+ def _repository_on_branch(tmp_path: Path) -> Path:
1762
+ origin_path = tmp_path / "origin"
1763
+ clone_path = tmp_path / "clone"
1764
+ subprocess.run(["git", "init", "-q", "-b", "main", str(origin_path)], check=True)
1765
+ _commit_file(origin_path, "README.md")
1766
+ subprocess.run(["git", "clone", "-q", str(origin_path), str(clone_path)], check=True)
1767
+ _run_git(clone_path, "checkout", "-q", "-b", "parent")
1768
+ return clone_path
1769
+
1770
+
1771
+ def test_first_merge_base_should_try_the_candidate_references_in_order(
1772
+ tmp_path: Path,
1773
+ ) -> None:
1774
+ clone_path = _repository_on_branch(tmp_path)
1775
+ _commit_file(clone_path, "library.py")
1776
+ parent_commit = subprocess.run(
1777
+ ["git", "-C", str(clone_path), "rev-parse", "HEAD"],
1778
+ check=True,
1779
+ capture_output=True,
1780
+ text=True,
1781
+ ).stdout.strip()
1782
+ _run_git(clone_path, "checkout", "-q", "-b", "child")
1783
+ _commit_file(clone_path, "caller.py")
1784
+ assert (
1785
+ gate._first_merge_base(str(clone_path), "HEAD", ("no-such-branch", "parent"))
1786
+ == parent_commit
1787
+ )
1788
+ assert gate._first_merge_base(str(clone_path), "HEAD") != parent_commit
@@ -19,7 +19,7 @@ This family stops a chat reply, edited message, or tool call when its payload br
19
19
  - `blocking/step_note_gate.py` requires a status line before a tool call while its opt-in flag is on.
20
20
  - `blocking/wakeup_cap_gate.py` keeps a self-wakeup inside the 1-hour prompt cache. A wake over the step-down (57 minutes for `send_later` and Routines, 3480 seconds for `ScheduleWakeup`) and at most 60 minutes away runs with its delay rewritten to the step-down. A wake over 60 minutes away, or a cron with more than 57 minutes between wakes, is denied with a reason that says to stack wakes under the cap. A Routine that starts a fresh session on each firing passes.
21
21
  - `blocking/verify_before_acting.py` blocks a completed mutating call when the agent's reasoning contains an unchecked claim. For an `Agent` or `Task` spawn it adds the same quote as an advisory note and does not block.
22
- - `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. The scan reads the transcript newest line first, so the first load or compaction boundary it meets decides. Every create spelling the shared listing in `blocking/followup_pr_dedupe.py` reads counts as a pull request action. Read-only `gh pr` subcommands (`view`, `list`, `checks`, `diff`, `status`) pass without it, unless a later argument names another `gh pr` subcommand.
22
+ - `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. The scan reads the transcript newest line first, so the first load or compaction boundary it meets decides. Every create spelling the shared listing in `blocking/followup_pr_dedupe.py` reads counts as a pull request action. Read-only `gh pr` subcommands (`view`, `list`, `checks`, `diff`, `status`) pass without it, unless a later argument names another `gh pr` subcommand. It also denies a new pull request over 1,000 changed lines against its own base unless the body has a `Why one pull request` section; `blocking/oversized_change.py` counts the lines and leaves out `linguist-generated` files and lockfiles.
23
23
  - `blocking/resolve_thread_reply_gate.py` denies a review thread resolve until the agent's own transcript shows a reply on that same thread that posted after the last user prompt and that no successful resolve of the thread has spent. A resolve is a `resolve_review_thread` call, which names the thread by `threadID`; a `pull_request_review_write` call with method `resolve_thread`, which names it by `threadId`; a shell command with a `gh api graphql` `resolveReviewThread` mutation, which names it by a literal `PRRT_` id; or a shell call to `pulls/<n>/ccr/comments/<id>/resolve`, which names it by a comment id. A graphql resolve that names no `PRRT_` id is denied. A reply is an `add_reply_to_pull_request_comment` call, or a `gh api` call to a comment's `replies` endpoint or to `addPullRequestReviewThreadReply`, which names its thread by `PRRT_` id. A shell command that is one plain `review_reply_post.py request` call is a reply on the comment its `--comment-id` names and on the thread its `--thread-id` names. The launcher is absent, or is `python`, `python3`, `python3.<n>` or `py`, with or without `.exe`, bare or by an absolute path that starts with `/` or with a drive letter and `:/`. The script's parser accepts any prefix of an option name, so each word after `request` must be `--pull`, `--comment-id`, `--thread-id`, `--body-file` or `--wait-seconds` with a value that starts with no `-`, or the bare `--supersede`, each given once. A command that holds `;`, `&`, `|`, a redirect, a subshell, a substitution, a variable, `#`, a brace, a glob, `~`, `!`, a backslash or a line break is no reply. So a `cd dir &&` prefix, an environment prefix, a launcher option such as `python3 -u` or `py -3`, a launcher by a relative path such as `.venv/bin/python`, `uv run`, a line continuation, a backslash path, a pipe to `tail`, and a quoted value that holds `(`, `[` or `~` all count for nothing; run the plain form. A file of the same name, or a launcher of the same name at an absolute path, that exits 0 without posting still counts. A reply and a resolve by comment id match when they name the same comment, or when a successful tool result in the transcript, such as `pull_request_read` `get_review_comments`, lists the comment under the thread by its `discussion_r` anchor or `databaseId`. A reply whose result is an error does not count. A background task notice is no user prompt, so a reply before it still counts. A call runs in the background when its `run_in_background` input is truthy, or when it is a `Bash` or `PowerShell` call whose result holds a line that starts `Command running in background with ID:`, `Command was manually backgrounded by user with ID:` or `Command did not complete within`. Those words in the result of any other tool, such as a reply tool that returns the comment body, change nothing. Such a reply counts only once a notice names its tool use id and a completed status before its summary, and ends its summary with `completed (exit code 0)`. The notice is read from a user entry or from a `queued_command` attachment, and a text that holds two notices vouches for no call. Any other `queued_command` attachment, such as a prompt the user sent mid-turn or a message another agent queued, ends the turn as a user prompt does, so a reply before it does not count and the agent replies again before it resolves. With no readable transcript, the resolve passes.
24
24
  - `blocking/verify_before_commit_gate.py` denies a `git commit` in a repository with a `.claude/skills/verify` or `.agents/skills/verify` directory until the `verify` skill loads after the last user prompt, through a Skill call whose result comes back without an error, or the `/verify` command in that prompt. It reads the committed paths from the staged diff, the tracked changes for `-a`, and the paths of each `git add` earlier in the same command, and passes a commit whose paths are all docs, images, test files, or `.json`, `.jsonl`, `.yaml`, `.yml`, or `.csv` files under a `docs` folder.
25
25
  - `blocking/build_eval_before_eval_write_gate.py` denies a write to an eval file until a Skill call named exactly `claude-api` with args `build-eval`, or the `/claude-api build-eval` command, appears in the transcript.
@@ -0,0 +1,46 @@
1
+ """Constants for the size check on a new pull request."""
2
+
3
+ MEASURED_LINE_BAR = 1000
4
+ ONE_PULL_REQUEST_HEADING_PATTERN = r"^(#{1,6})[ \t]+why one pull request[?:.]?[ \t]*#*[ \t]*$"
5
+ SPLIT_GUIDE_PATH = "~/.claude/skills/pr-lifecycle/reference/split-a-pull-request.md"
6
+ OVERSIZED_PULL_REQUEST_REASON = (
7
+ "This pull request changes {measured_line_count} lines against its base, over the"
8
+ " {measured_line_bar}-line bar. Lockfiles are left out of the count, and a local count"
9
+ " also leaves out files marked linguist-generated in .gitattributes."
10
+ " Split it into stacked pull requests, each created with --base set to the branch below it,"
11
+ " as " + SPLIT_GUIDE_PATH + " describes. When the change must stay one pull request,"
12
+ " add a 'Why one pull request' heading to the body and state the reason under it."
13
+ )
14
+ LINGUIST_GENERATED_ATTRIBUTE = "linguist-generated"
15
+ ALL_GENERATED_ATTRIBUTE_VALUES = frozenset({"set", "true"})
16
+ CHECK_ATTR_FIELD_COUNT = 3
17
+ ALL_LOCKFILE_NAMES = frozenset(
18
+ {
19
+ "package-lock.json",
20
+ "npm-shrinkwrap.json",
21
+ "yarn.lock",
22
+ "pnpm-lock.yaml",
23
+ "bun.lockb",
24
+ "bun.lock",
25
+ "poetry.lock",
26
+ "Pipfile.lock",
27
+ "uv.lock",
28
+ "pdm.lock",
29
+ "Cargo.lock",
30
+ "Gemfile.lock",
31
+ "composer.lock",
32
+ "go.sum",
33
+ "flake.lock",
34
+ "packages.lock.json",
35
+ "Podfile.lock",
36
+ "pubspec.lock",
37
+ "mix.lock",
38
+ }
39
+ )
40
+ NUMSTAT_FIELD_SEPARATOR = "\t"
41
+ NUMSTAT_FIELD_COUNT = 3
42
+ BINARY_NUMSTAT_COUNT = "-"
43
+ RENAME_DETECTION_LIMIT_OPTION = "-l1000"
44
+ COMPARE_LINE_COUNT_QUERY = (
45
+ "(.files | length | tostring), (.files[] | [.filename, .additions, .deletions] | @json)"
46
+ )
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "claude-dev-env",
3
- "version": "8.126.6",
3
+ "version": "8.127.0",
4
4
  "description": "Claude Code development standards — rules, hooks, agents, commands, and skills",
5
5
  "type": "module",
6
6
  "bin": {