claude-dev-env 8.108.3 → 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.
@@ -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, matched without regard to case. Inline code spans and fenced
447
- blocks are skipped, so output quoted there never counts.
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(UNPROVEN_ADMISSION_PATTERN, each_prose, re.IGNORECASE):
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
@@ -4,12 +4,14 @@
4
4
 
5
5
  unlisted file lines > limit -> file finding
6
6
  unpointed section > detail limit -> section finding
7
+ agent file no pointer, or unlinked line > words -> prose finding, unless skipped
7
8
  listed file lines null, lines > limit -> file finding
8
9
  lines N, lines > limit and lines > N -> grown finding
9
10
  section heading not recorded -> section finding
10
11
  CI ratchet changed file below its record N -> record the new count, or null
11
12
  changed file lost a recorded section -> drop it from the entry
12
13
  changed file within budget -> remove the entry
14
+ changed agent file -> report only the prose findings it added
13
15
  """
14
16
 
15
17
  from __future__ import annotations
@@ -17,6 +19,8 @@ from __future__ import annotations
17
19
  import json
18
20
  from collections import Counter
19
21
  from collections.abc import Iterable
22
+ from dataclasses import replace
23
+ from pathlib import PurePosixPath
20
24
 
21
25
  from context_budget.model import (
22
26
  BaselineEntry,
@@ -25,15 +29,26 @@ from context_budget.model import (
25
29
  FileMeasure,
26
30
  SectionScan,
27
31
  )
28
- from context_budget.sections import baseline_entry_for, measure_file
32
+ from context_budget.sections import (
33
+ baseline_entry_for,
34
+ is_path_skipped,
35
+ measure_file,
36
+ prose_word_count,
37
+ scan_prose,
38
+ )
29
39
  from hooks_constants.context_budget_constants import (
40
+ ALL_PROSE_RULE_FILE_NAMES,
30
41
  FILE_FINDING_TEMPLATE,
31
42
  FILE_SCOPE,
32
43
  GROWN_FINDING_TEMPLATE,
33
44
  GROWN_PAST_PRIOR_TEMPLATE,
34
45
  KEBAB_SEPARATOR,
35
46
  LINES_KEY,
47
+ NO_POINTER_FINDING_TEMPLATE,
48
+ NO_POINTER_SCOPE,
36
49
  NON_KEBAB_CHARACTER_PATTERN,
50
+ PROSE_LINE_FINDING_TEMPLATE,
51
+ PROSE_LINE_SCOPE_PREFIX,
37
52
  RATCHET_LOWER_TEMPLATE,
38
53
  RATCHET_REMOVE_TEMPLATE,
39
54
  SECTION_FINDING_TEMPLATE,
@@ -153,23 +168,76 @@ def _file_scope_findings(
153
168
  return all_findings, all_new_sections
154
169
 
155
170
 
171
+ def _is_prose_rule_path(policy: BudgetPolicy, relative_path: str) -> bool:
172
+ is_agent_file = PurePosixPath(relative_path).name in ALL_PROSE_RULE_FILE_NAMES
173
+ return is_agent_file and not is_path_skipped(policy, relative_path)
174
+
175
+
176
+ def _prose_findings(
177
+ policy: BudgetPolicy, relative_path: str, text: str
178
+ ) -> tuple[BudgetFinding, ...]:
179
+ if not _is_prose_rule_path(policy, relative_path):
180
+ return ()
181
+ scan = scan_prose(text, policy.prose_line_word_limit)
182
+ all_findings: list[BudgetFinding] = []
183
+ if scan.has_detail_line and not scan.has_pointer_line:
184
+ all_findings.append(
185
+ BudgetFinding(
186
+ relative_path,
187
+ NO_POINTER_SCOPE,
188
+ NO_POINTER_FINDING_TEMPLATE.format(path=relative_path),
189
+ )
190
+ )
191
+ for each_line in scan.all_long_unlinked_lines:
192
+ excerpt = each_line.strip()
193
+ all_findings.append(
194
+ BudgetFinding(
195
+ relative_path,
196
+ PROSE_LINE_SCOPE_PREFIX + excerpt,
197
+ PROSE_LINE_FINDING_TEMPLATE.format(
198
+ path=relative_path,
199
+ excerpt=excerpt,
200
+ count=prose_word_count(each_line),
201
+ limit=policy.prose_line_word_limit,
202
+ ),
203
+ )
204
+ )
205
+ return tuple(all_findings)
206
+
207
+
208
+ def _prose_findings_added_since(
209
+ policy: BudgetPolicy, relative_path: str, text: str, prior_text: str | None
210
+ ) -> tuple[BudgetFinding, ...]:
211
+ all_findings = _prose_findings(policy, relative_path, text)
212
+ if prior_text is None or prior_text == text:
213
+ return all_findings
214
+ return _introduced(
215
+ all_findings, _prose_findings(policy, relative_path, prior_text), has_grown=False
216
+ )
217
+
218
+
156
219
  def file_findings(
157
220
  policy: BudgetPolicy, relative_path: str, text: str, ratchet_prior_text: str | None
158
221
  ) -> tuple[BudgetFinding, ...]:
159
- """Check one file against its kind and the over-budget list.
222
+ """Check one file against its kind, the over-budget list, and the prose rule.
160
223
 
161
224
  Args:
162
225
  policy: Budget policy.
163
226
  relative_path: Repository-relative POSIX path.
164
227
  text: Current file text.
165
228
  ratchet_prior_text: Prior text when the CI ratchet applies, else None.
229
+ A changed file reports only the prose findings its prior text
230
+ lacked. An unchanged or new file reports every prose finding.
166
231
 
167
232
  Returns:
168
- Findings in file-then-section order.
233
+ Findings in file, section, then prose order. Prose findings apply to
234
+ AGENTS.md and CLAUDE.md files whatever kind the policy gives them,
235
+ except a kind the policy skips.
169
236
  """
237
+ prose_findings = _prose_findings_added_since(policy, relative_path, text, ratchet_prior_text)
170
238
  measure = measure_file(policy, relative_path, text)
171
239
  if measure is None:
172
- return ()
240
+ return prose_findings
173
241
  recorded = policy.baseline_entry_by_path.get(relative_path)
174
242
  is_ratchet_due = ratchet_prior_text is not None and ratchet_prior_text != text
175
243
  grown_template = (
@@ -182,6 +250,7 @@ def file_findings(
182
250
  *all_findings,
183
251
  *(_section_finding(relative_path, each, policy.section_detail_line_limit)
184
252
  for each in all_new_sections),
253
+ *prose_findings,
185
254
  )
186
255
 
187
256
 
@@ -192,12 +261,9 @@ def _with_prior_as_baseline(
192
261
  prior_entry = None if prior_measure is None else baseline_entry_for(prior_measure)
193
262
  if prior_entry is None:
194
263
  return policy
195
- return BudgetPolicy(
196
- policy.section_detail_line_limit,
197
- policy.all_kinds,
198
- policy.all_hooks,
199
- {**policy.baseline_entry_by_path, relative_path: prior_entry},
200
- policy.baseline_characters_by_hook_name,
264
+ return replace(
265
+ policy,
266
+ baseline_entry_by_path={**policy.baseline_entry_by_path, relative_path: prior_entry},
201
267
  is_baseline_the_prior_text=True,
202
268
  )
203
269
 
@@ -14,6 +14,8 @@ from __future__ import annotations
14
14
  from collections.abc import Mapping
15
15
  from dataclasses import dataclass, field
16
16
 
17
+ from hooks_constants.context_budget_constants import DEFAULT_PROSE_LINE_WORD_LIMIT
18
+
17
19
 
18
20
  class ContextBudgetPolicyError(ValueError):
19
21
  """Raised when a policy file does not match the documented shape."""
@@ -79,6 +81,7 @@ class BudgetPolicy:
79
81
  baseline_characters_by_hook_name: Over-budget hooks by name.
80
82
  is_baseline_the_prior_text: Whether the baseline entry was measured from
81
83
  the file's prior text because the repository has no policy file.
84
+ prose_line_word_limit: Words an unlinked agent-file detail line may hold.
82
85
  """
83
86
 
84
87
  section_detail_line_limit: int
@@ -87,6 +90,7 @@ class BudgetPolicy:
87
90
  baseline_entry_by_path: Mapping[str, BaselineEntry] = field(default_factory=dict)
88
91
  baseline_characters_by_hook_name: Mapping[str, int] = field(default_factory=dict)
89
92
  is_baseline_the_prior_text: bool = False
93
+ prose_line_word_limit: int = DEFAULT_PROSE_LINE_WORD_LIMIT
90
94
 
91
95
 
92
96
  @dataclass(frozen=True)
@@ -119,6 +123,21 @@ class FileMeasure:
119
123
  all_over_limit_sections: tuple[SectionScan, ...]
120
124
 
121
125
 
126
+ @dataclass(frozen=True)
127
+ class ProseScan:
128
+ """Prose measurements of one Markdown body.
129
+
130
+ Attributes:
131
+ has_detail_line: Whether the body holds any detail line.
132
+ has_pointer_line: Whether any body line holds a relative link or an @import line.
133
+ all_long_unlinked_lines: Detail lines with no relative link over the word limit.
134
+ """
135
+
136
+ has_detail_line: bool
137
+ has_pointer_line: bool
138
+ all_long_unlinked_lines: tuple[str, ...]
139
+
140
+
122
141
  @dataclass(frozen=True)
123
142
  class BudgetFinding:
124
143
  """One budget violation.
@@ -33,6 +33,7 @@ from hooks_constants.context_budget_constants import (
33
33
  CHANGE_RAISES_FILE,
34
34
  CHANGE_RAISES_HOOK,
35
35
  CHANGE_RAISES_LINE_LIMIT,
36
+ CHANGE_RAISES_PROSE_LIMIT,
36
37
  CHANGE_RAISES_SECTION_LIMIT,
37
38
  CHANGE_RECORDS_FILE_LINES,
38
39
  FILE_SCOPE,
@@ -78,6 +79,12 @@ def _limit_changes(
78
79
  prior=prior_section_limit, current=current_section_limit
79
80
  )
80
81
  )
82
+ prior_prose_limit = prior_policy.prose_line_word_limit
83
+ current_prose_limit = current_policy.prose_line_word_limit
84
+ if current_prose_limit > prior_prose_limit:
85
+ all_changes.append(
86
+ CHANGE_RAISES_PROSE_LIMIT.format(prior=prior_prose_limit, current=current_prose_limit)
87
+ )
81
88
  current_kind_by_name = {each.name: each for each in current_policy.all_kinds}
82
89
  all_prior_kind_names = tuple(
83
90
  each.name for each in prior_policy.all_kinds if each.name in current_kind_by_name
@@ -23,6 +23,7 @@ from hooks_constants.context_budget_constants import (
23
23
  BASELINE_KEY,
24
24
  CHAR_LIMIT_KEY,
25
25
  COMMAND_KEY,
26
+ DEFAULT_PROSE_LINE_WORD_LIMIT,
26
27
  DEFAULT_SECTION_DETAIL_LINE_LIMIT,
27
28
  GIT_MARKER_NAME,
28
29
  HOOKS_KEY,
@@ -34,6 +35,7 @@ from hooks_constants.context_budget_constants import (
34
35
  POLICY_ERROR_BAD_FIELD,
35
36
  POLICY_ERROR_DUPLICATE_HOOK_NAME,
36
37
  POLICY_ERROR_NOT_OBJECT,
38
+ PROSE_LINE_WORD_LIMIT_KEY,
37
39
  SECTION_DETAIL_LINE_LIMIT_KEY,
38
40
  SECTION_RULE_KEY,
39
41
  SECTIONS_KEY,
@@ -176,6 +178,10 @@ def parse_policy(policy_text: str) -> BudgetPolicy:
176
178
  raw_policy.get(SECTION_DETAIL_LINE_LIMIT_KEY, DEFAULT_SECTION_DETAIL_LINE_LIMIT),
177
179
  SECTION_DETAIL_LINE_LIMIT_KEY,
178
180
  ),
181
+ prose_line_word_limit=_integer(
182
+ raw_policy.get(PROSE_LINE_WORD_LIMIT_KEY, DEFAULT_PROSE_LINE_WORD_LIMIT),
183
+ PROSE_LINE_WORD_LIMIT_KEY,
184
+ ),
179
185
  all_kinds=tuple(
180
186
  _parse_kind(each) for each in _items(raw_policy.get(KINDS_KEY, []), KINDS_KEY)
181
187
  ),
@@ -6,12 +6,13 @@
6
6
  Step one. detail line
7
7
  | a | b | table row, not detail
8
8
  - [ref](reference/x.md) pure link item, not detail; relative link is a pointer
9
+ @AGENTS.md import line; a pointer for the prose rule only
9
10
  """
10
11
 
11
12
  from __future__ import annotations
12
13
 
13
14
  from collections.abc import Sequence
14
- from dataclasses import dataclass
15
+ from dataclasses import dataclass, field
15
16
  from fnmatch import fnmatchcase
16
17
 
17
18
  from context_budget.model import (
@@ -19,14 +20,18 @@ from context_budget.model import (
19
20
  BudgetPolicy,
20
21
  ContextKind,
21
22
  FileMeasure,
23
+ ProseScan,
22
24
  SectionScan,
23
25
  )
26
+ from hooks_constants.ask_user_question_shape import count_prose_words
24
27
  from hooks_constants.context_budget_constants import (
25
28
  ALL_NON_RELATIVE_TARGET_PREFIXES,
26
29
  ATX_HEADING_PATTERN,
27
30
  FENCE_OPEN_PATTERN,
28
31
  FRONTMATTER_DELIMITER,
32
+ IMPORT_DIRECTIVE_PATTERN,
29
33
  LINK_TARGET_PATTERN,
34
+ LIST_MARKER_PATTERN,
30
35
  PATH_SEPARATOR,
31
36
  PURE_LINK_LIST_ITEM_PATTERN,
32
37
  RECURSIVE_GLOB_SEGMENT,
@@ -67,6 +72,13 @@ def path_matches_pattern(pattern: str, relative_path: str) -> bool:
67
72
  return _segments_match(pattern.split(PATH_SEPARATOR), relative_path.split(PATH_SEPARATOR))
68
73
 
69
74
 
75
+ def _first_matching_kind(policy: BudgetPolicy, relative_path: str) -> ContextKind | None:
76
+ for each_kind in policy.all_kinds:
77
+ if any(path_matches_pattern(each, relative_path) for each in each_kind.all_patterns):
78
+ return each_kind
79
+ return None
80
+
81
+
70
82
  def context_kind_for_path(policy: BudgetPolicy, relative_path: str) -> ContextKind | None:
71
83
  """Return the measured kind of a path; the first matching kind wins.
72
84
 
@@ -77,10 +89,22 @@ def context_kind_for_path(policy: BudgetPolicy, relative_path: str) -> ContextKi
77
89
  Returns:
78
90
  The matching kind, or None when no kind matches or the match is skipped.
79
91
  """
80
- for each_kind in policy.all_kinds:
81
- if any(path_matches_pattern(each, relative_path) for each in each_kind.all_patterns):
82
- return each_kind if each_kind.line_limit is not None else None
83
- return None
92
+ kind = _first_matching_kind(policy, relative_path)
93
+ return kind if kind is not None and kind.line_limit is not None else None
94
+
95
+
96
+ def is_path_skipped(policy: BudgetPolicy, relative_path: str) -> bool:
97
+ """Return whether the first kind that matches a path has no line limit.
98
+
99
+ Args:
100
+ policy: Budget policy holding the ordered kind table.
101
+ relative_path: Repository-relative POSIX path.
102
+
103
+ Returns:
104
+ True when the matching kind is a skipped kind, else False.
105
+ """
106
+ kind = _first_matching_kind(policy, relative_path)
107
+ return kind is not None and kind.line_limit is None
84
108
 
85
109
 
86
110
  def _body_lines(text: str) -> list[str]:
@@ -123,6 +147,9 @@ class _SectionWalk:
123
147
  detail_line_count: int = 0
124
148
  has_pointer: bool = False
125
149
  opening_marker: str | None = None
150
+ has_detail_line: bool = False
151
+ has_import_line: bool = False
152
+ all_unlinked_detail_lines: list[str] = field(default_factory=list)
126
153
 
127
154
  def close_section(self) -> None:
128
155
  self.all_scans.append(SectionScan(self.heading, self.detail_line_count, self.has_pointer))
@@ -145,8 +172,18 @@ class _SectionWalk:
145
172
  self.detail_line_count = 0
146
173
  self.has_pointer = False
147
174
  else:
148
- self.detail_line_count += int(_is_detail_line(line))
149
- self.has_pointer = self.has_pointer or _line_has_pointer(line)
175
+ self.read_body_line(line)
176
+
177
+ def read_body_line(self, line: str) -> None:
178
+ is_detail = _is_detail_line(line)
179
+ has_link = _line_has_pointer(line)
180
+ is_import = IMPORT_DIRECTIVE_PATTERN.match(line) is not None
181
+ self.detail_line_count += int(is_detail)
182
+ self.has_pointer = self.has_pointer or has_link
183
+ self.has_detail_line = self.has_detail_line or is_detail
184
+ self.has_import_line = self.has_import_line or is_import
185
+ if is_detail and not has_link and not is_import:
186
+ self.all_unlinked_detail_lines.append(line)
150
187
 
151
188
 
152
189
  def scan_sections(text: str) -> tuple[SectionScan, ...]:
@@ -161,6 +198,10 @@ def scan_sections(text: str) -> tuple[SectionScan, ...]:
161
198
  Returns:
162
199
  One scan per section in document order, starting with ``(top)``.
163
200
  """
201
+ return tuple(_walk_body(text).all_scans)
202
+
203
+
204
+ def _walk_body(text: str) -> _SectionWalk:
164
205
  walk = _SectionWalk([])
165
206
  for each_line in _body_lines(text):
166
207
  if walk.opening_marker is not None:
@@ -168,7 +209,46 @@ def scan_sections(text: str) -> tuple[SectionScan, ...]:
168
209
  else:
169
210
  walk.read_open(each_line)
170
211
  walk.close_section()
171
- return tuple(walk.all_scans)
212
+ return walk
213
+
214
+
215
+ def prose_word_count(line: str) -> int:
216
+ """Count the words of one Markdown line after its list marker.
217
+
218
+ Args:
219
+ line: One line of Markdown text.
220
+
221
+ Returns:
222
+ The number of words in the line's text.
223
+ """
224
+ return count_prose_words(LIST_MARKER_PATTERN.sub("", line))
225
+
226
+
227
+ def scan_prose(text: str, word_limit: int) -> ProseScan:
228
+ """Measure the prose rule's inputs for one Markdown body.
229
+
230
+ Fenced lines, tables, and pure link items are not detail lines. A line
231
+ counts as pointed when it holds a relative link or an @import line.
232
+
233
+ Args:
234
+ text: Full file text; leading frontmatter is removed.
235
+ word_limit: Words an unlinked detail line may hold.
236
+
237
+ Returns:
238
+ Whether the body has a detail line, whether any line links to a relative
239
+ target or holds an @import line, and the unlinked detail lines over the
240
+ word limit.
241
+ """
242
+ walk = _walk_body(text)
243
+ return ProseScan(
244
+ walk.has_detail_line,
245
+ walk.has_import_line or any(each_scan.has_pointer for each_scan in walk.all_scans),
246
+ tuple(
247
+ each_line
248
+ for each_line in walk.all_unlinked_detail_lines
249
+ if prose_word_count(each_line) > word_limit
250
+ ),
251
+ )
172
252
 
173
253
 
174
254
  def measure_file(policy: BudgetPolicy, relative_path: str, text: str) -> FileMeasure | None:
@@ -69,3 +69,15 @@ def section_text(heading: str, detail_count: int, pointer_line: str = "") -> str
69
69
  if pointer_line:
70
70
  all_lines.append(pointer_line)
71
71
  return "\n".join(all_lines) + "\n"
72
+
73
+
74
+ def words_text(word_count: int) -> str:
75
+ """Return one line of plain words.
76
+
77
+ Args:
78
+ word_count: Number of words to write.
79
+
80
+ Returns:
81
+ The words separated by single spaces, without a newline.
82
+ """
83
+ return " ".join(["word"] * word_count)
@@ -2,7 +2,7 @@
2
2
 
3
3
  from __future__ import annotations
4
4
 
5
- from context_budget.tests.budget_support import SKILL_PATH, policy_text, section_text
5
+ from context_budget.tests.budget_support import SKILL_PATH, policy_text, section_text, words_text
6
6
  from context_budget.findings import edit_findings, file_findings
7
7
  from context_budget.policy_file import default_policy, parse_policy
8
8
 
@@ -118,3 +118,108 @@ def test_edit_of_an_unlisted_over_budget_file_is_allowed_when_it_shrinks_under_a
118
118
  "file",
119
119
  "Alpha",
120
120
  ]
121
+
122
+
123
+ AGENT_PATH = "shared_utils/files/AGENTS.md"
124
+ LONG_LINE = words_text(26)
125
+ POINTER_LINE = "Read [the plan](reference/plan.md)."
126
+
127
+
128
+ def test_agent_file_with_no_relative_link_fails_the_pointer_rule() -> None:
129
+ policy = parse_policy(policy_text())
130
+
131
+ all_findings = file_findings(policy, AGENT_PATH, "Selection records own icon choice.\n", None)
132
+
133
+ assert [each.scope for each in all_findings] == ["no pointer line"]
134
+ assert (
135
+ "shared_utils/files/AGENTS.md: context-budget: file has no pointer line"
136
+ in all_findings[0].message
137
+ )
138
+
139
+
140
+ def test_agent_file_fails_on_an_unlinked_line_over_the_word_limit_only() -> None:
141
+ policy = parse_policy(policy_text())
142
+ exact_line = words_text(25)
143
+
144
+ over_limit = file_findings(policy, AGENT_PATH, f"{LONG_LINE}\n{POINTER_LINE}\n", None)
145
+ at_limit = file_findings(policy, AGENT_PATH, f"{exact_line}\n{POINTER_LINE}\n", None)
146
+
147
+ assert [each.scope for each in over_limit] == [f"prose line: {LONG_LINE}"]
148
+ assert "26 words" in over_limit[0].message
149
+ assert at_limit == ()
150
+
151
+
152
+ def test_claude_file_gets_the_same_rule_and_a_skill_file_does_not() -> None:
153
+ policy = parse_policy(policy_text())
154
+
155
+ claude_findings = file_findings(policy, "app/CLAUDE.md", f"{LONG_LINE}\n{POINTER_LINE}\n", None)
156
+
157
+ assert [each.scope for each in claude_findings] == [f"prose line: {LONG_LINE}"]
158
+ assert file_findings(policy, SKILL_PATH, f"{LONG_LINE}\n", None) == ()
159
+
160
+
161
+ def test_blank_agent_file_passes_the_pointer_rule() -> None:
162
+ policy = parse_policy(policy_text())
163
+
164
+ assert file_findings(policy, AGENT_PATH, "\n", None) == ()
165
+ assert file_findings(policy, AGENT_PATH, "", None) == ()
166
+
167
+
168
+ def test_edit_that_adds_a_long_unlinked_line_introduces_its_finding_once() -> None:
169
+ policy = parse_policy(policy_text())
170
+ prior_text = f"{POINTER_LINE}\n"
171
+ post_text = f"{prior_text}{LONG_LINE}\n"
172
+
173
+ introduced = edit_findings(policy, AGENT_PATH, prior_text, post_text, False)
174
+
175
+ assert [each.scope for each in introduced] == [f"prose line: {LONG_LINE}"]
176
+ assert edit_findings(policy, AGENT_PATH, post_text, f"{post_text}Short line.\n", False) == ()
177
+
178
+
179
+ def test_changed_file_reports_only_prose_findings_its_prior_text_lacked() -> None:
180
+ policy = parse_policy(policy_text())
181
+ prior_text = f"{POINTER_LINE}\n{LONG_LINE}\n"
182
+ kept_text = f"{prior_text}Short line.\n"
183
+ added_line = words_text(27)
184
+ added_text = f"{kept_text}{added_line}\n"
185
+ long_line_scopes = [f"prose line: {LONG_LINE}"]
186
+
187
+ assert file_findings(policy, AGENT_PATH, kept_text, prior_text) == ()
188
+ added_findings = file_findings(policy, AGENT_PATH, added_text, prior_text)
189
+ assert [each.scope for each in added_findings] == [f"prose line: {added_line}"]
190
+ assert [each.scope for each in file_findings(policy, AGENT_PATH, kept_text, None)] == (
191
+ long_line_scopes
192
+ )
193
+ assert [
194
+ each.scope for each in file_findings(policy, AGENT_PATH, prior_text, prior_text)
195
+ ] == long_line_scopes
196
+
197
+
198
+ def test_claude_file_that_only_imports_agents_md_passes_the_pointer_rule() -> None:
199
+ policy = parse_policy(policy_text())
200
+
201
+ assert file_findings(policy, "app/CLAUDE.md", "@AGENTS.md\n", None) == ()
202
+
203
+
204
+ def test_import_line_satisfies_the_pointer_rule_but_not_the_word_limit() -> None:
205
+ policy = parse_policy(policy_text())
206
+
207
+ all_findings = file_findings(policy, "app/CLAUDE.md", f"@AGENTS.md\n{LONG_LINE}\n", None)
208
+
209
+ assert [each.scope for each in all_findings] == [f"prose line: {LONG_LINE}"]
210
+
211
+
212
+ def test_import_line_does_not_exempt_a_section_from_the_section_rule() -> None:
213
+ policy = parse_policy(policy_text())
214
+ text = section_text("Alpha", 7, "@reference/alpha.md")
215
+
216
+ assert [each.scope for each in file_findings(policy, SKILL_PATH, text, None)] == ["Alpha"]
217
+
218
+
219
+ def test_skipped_kind_hides_an_agent_file_from_the_prose_rule() -> None:
220
+ policy = parse_policy(policy_text())
221
+ text = "Selection records own icon choice.\n"
222
+
223
+ assert file_findings(policy, "pkg/skills-archived/AGENTS.md", text, None) == ()
224
+ live_findings = file_findings(policy, "pkg/live/AGENTS.md", text, None)
225
+ assert [each.scope for each in live_findings] == ["no pointer line"]
@@ -173,3 +173,22 @@ def test_appending_a_kind_and_tightening_limits_passes(tmp_path: Path) -> None:
173
173
  parse_policy(json.dumps(raw_current)),
174
174
  tmp_path,
175
175
  ) == ()
176
+
177
+
178
+ def test_raising_the_prose_line_word_limit_is_a_loosening_change(tmp_path: Path) -> None:
179
+ raw_prior = json.loads(policy_text())
180
+ raw_prior["prose_line_word_limit"] = 25
181
+ raw_current = json.loads(policy_text())
182
+ raw_current["prose_line_word_limit"] = 40
183
+ prior_policy = parse_policy(json.dumps(raw_prior))
184
+
185
+ raised = policy_shrink_findings(
186
+ "p", prior_policy, parse_policy(json.dumps(raw_current)), tmp_path
187
+ )
188
+ raw_current["prose_line_word_limit"] = 10
189
+ lowered = policy_shrink_findings(
190
+ "p", prior_policy, parse_policy(json.dumps(raw_current)), tmp_path
191
+ )
192
+
193
+ assert "prose_line_word_limit rises from 25 to 40" in raised[0].message
194
+ assert lowered == ()
@@ -60,3 +60,14 @@ def test_repository_root_accepts_a_git_file_and_policy_reads_from_it(tmp_path: P
60
60
  find_repository_root(tmp_path / "x.md") is None
61
61
  or find_repository_root(tmp_path / "x.md") != repository_root
62
62
  )
63
+
64
+
65
+ def test_prose_line_word_limit_defaults_to_25_and_reads_its_key() -> None:
66
+ raw_policy = json.loads(policy_text())
67
+
68
+ assert parse_policy(json.dumps(raw_policy)).prose_line_word_limit == 25
69
+ raw_policy["prose_line_word_limit"] = 12
70
+ assert parse_policy(json.dumps(raw_policy)).prose_line_word_limit == 12
71
+ raw_policy["prose_line_word_limit"] = "twelve"
72
+ with pytest.raises(ContextBudgetPolicyError):
73
+ parse_policy(json.dumps(raw_policy))
@@ -0,0 +1,144 @@
1
+ """Grade the prose rule on labeled agent and Claude instruction files.
2
+
3
+ Each case's label comes from the rule's text. A case is positive when the
4
+ prose rule must report a finding for its file. The scope strings are spelled
5
+ out here so the eval grades the findings the rule reports.
6
+ """
7
+
8
+ from __future__ import annotations
9
+
10
+ from dataclasses import dataclass
11
+
12
+ import pytest
13
+
14
+ from context_budget.findings import file_findings
15
+ from context_budget.policy_file import default_policy
16
+ from context_budget.tests.budget_support import words_text
17
+
18
+ NO_POINTER_SCOPE = "no pointer line"
19
+ LONG_LINE_SCOPE_PREFIX = "prose line: "
20
+ POINTER_LINE = "Read [the plan](reference/plan.md)."
21
+
22
+
23
+ @dataclass(frozen=True)
24
+ class LabeledCase:
25
+ """One file and whether the prose rule must reject it.
26
+
27
+ Attributes:
28
+ name: Test id.
29
+ path: Repository-relative POSIX path.
30
+ text: File text.
31
+ should_fail: Whether the prose rule must report a finding.
32
+ """
33
+
34
+ name: str
35
+ path: str
36
+ text: str
37
+ should_fail: bool
38
+
39
+
40
+ ALL_LABELED_CASES = (
41
+ LabeledCase("blank-agents-file", "app/AGENTS.md", "", False),
42
+ LabeledCase("import-only-agents-file", "app/AGENTS.md", "@CLAUDE.md\n", False),
43
+ LabeledCase("relative-import-claude-file", "app/CLAUDE.md", "@../AGENTS.md\n", False),
44
+ LabeledCase(
45
+ "link-index",
46
+ "app/AGENTS.md",
47
+ "# Index\n- [Plan](reference/plan.md)\n- [Rules](reference/rules.md)\n",
48
+ False,
49
+ ),
50
+ LabeledCase("one-pointer-line", "app/AGENTS.md", f"{POINTER_LINE}\n", False),
51
+ LabeledCase(
52
+ "prose-without-pointer",
53
+ "app/AGENTS.md",
54
+ "Selection records own icon choice.\n",
55
+ True,
56
+ ),
57
+ LabeledCase(
58
+ "long-unlinked-line-with-pointer",
59
+ "app/AGENTS.md",
60
+ f"{words_text(26)}\n{POINTER_LINE}\n",
61
+ True,
62
+ ),
63
+ LabeledCase(
64
+ "line-at-word-limit",
65
+ "app/AGENTS.md",
66
+ f"{words_text(25)}\n{POINTER_LINE}\n",
67
+ False,
68
+ ),
69
+ LabeledCase(
70
+ "long-line-with-its-own-link",
71
+ "app/CLAUDE.md",
72
+ f"{words_text(26)} [plan](reference/plan.md)\n",
73
+ False,
74
+ ),
75
+ LabeledCase(
76
+ "import-with-long-unlinked-line",
77
+ "app/CLAUDE.md",
78
+ f"@AGENTS.md\n{words_text(26)}\n",
79
+ True,
80
+ ),
81
+ LabeledCase("mention-is-not-an-import", "app/AGENTS.md", "@reviewer please review\n", True),
82
+ LabeledCase(
83
+ "long-list-item-with-link",
84
+ "app/AGENTS.md",
85
+ f"- {words_text(30)} [plan](reference/plan.md)\n",
86
+ False,
87
+ ),
88
+ LabeledCase(
89
+ "long-line-inside-fence",
90
+ "app/AGENTS.md",
91
+ f"```\n{words_text(30)}\n```\n{POINTER_LINE}\n",
92
+ False,
93
+ ),
94
+ LabeledCase(
95
+ "long-table-row",
96
+ "app/AGENTS.md",
97
+ f"| {words_text(30)} |\n{POINTER_LINE}\n",
98
+ False,
99
+ ),
100
+ LabeledCase(
101
+ "short-intro-lines-with-pointer",
102
+ "app/AGENTS.md",
103
+ f"Holds shared helpers.\nCallers copy and publish trees.\n{POINTER_LINE}\n",
104
+ False,
105
+ ),
106
+ LabeledCase("not-an-agent-file", "docs/notes.md", f"{words_text(40)}\n", False),
107
+ LabeledCase(
108
+ "import-and-pointer-claude-file",
109
+ "app/CLAUDE.md",
110
+ f"@AGENTS.md\n{POINTER_LINE}\n",
111
+ False,
112
+ ),
113
+ LabeledCase(
114
+ "wordy-paragraph-with-pointer",
115
+ "app/AGENTS.md",
116
+ f"{words_text(52)}\n{POINTER_LINE}\n",
117
+ True,
118
+ ),
119
+ )
120
+
121
+
122
+ def _prose_rule_fails(each_case: LabeledCase) -> bool:
123
+ all_findings = file_findings(default_policy(), each_case.path, each_case.text, None)
124
+ return any(
125
+ each_finding.scope == NO_POINTER_SCOPE
126
+ or each_finding.scope.startswith(LONG_LINE_SCOPE_PREFIX)
127
+ for each_finding in all_findings
128
+ )
129
+
130
+
131
+ @pytest.mark.parametrize("each_case", ALL_LABELED_CASES, ids=lambda each_case: each_case.name)
132
+ def test_prose_rule_grades_each_labeled_case_as_labeled(each_case: LabeledCase) -> None:
133
+ assert _prose_rule_fails(each_case) == each_case.should_fail
134
+
135
+
136
+ def test_prose_rule_confusion_matrix_has_perfect_precision_and_recall() -> None:
137
+ all_outcomes = [
138
+ (each_case.should_fail, _prose_rule_fails(each_case)) for each_case in ALL_LABELED_CASES
139
+ ]
140
+
141
+ false_positives = sum(not each_label and each_grade for each_label, each_grade in all_outcomes)
142
+ false_negatives = sum(each_label and not each_grade for each_label, each_grade in all_outcomes)
143
+
144
+ assert (false_positives, false_negatives) == (0, 0)
@@ -9,10 +9,17 @@ from context_budget.tests.budget_support import (
9
9
  fixture_text,
10
10
  policy_text,
11
11
  section_text,
12
+ words_text,
12
13
  )
13
14
  from context_budget.findings import file_findings
14
15
  from context_budget.policy_file import default_policy, parse_policy
15
- from context_budget.sections import context_kind_for_path, path_matches_pattern, scan_sections
16
+ from context_budget.sections import (
17
+ context_kind_for_path,
18
+ is_path_skipped,
19
+ path_matches_pattern,
20
+ scan_prose,
21
+ scan_sections,
22
+ )
16
23
 
17
24
 
18
25
  def test_calibration_old_orchestrator_fails_on_oversee_delegated_work() -> None:
@@ -72,6 +79,14 @@ def test_first_matching_kind_wins_and_a_skipped_kind_hides_the_path() -> None:
72
79
  assert context_kind_for_path(policy, "docs/notes.md") is None
73
80
 
74
81
 
82
+ def test_path_is_skipped_only_when_its_first_matching_kind_has_no_line_limit() -> None:
83
+ policy = parse_policy(policy_text())
84
+
85
+ assert is_path_skipped(policy, "pkg/skills-archived/old/SKILL.md") is True
86
+ assert is_path_skipped(policy, "pkg/live/SKILL.md") is False
87
+ assert is_path_skipped(policy, "docs/notes.md") is False
88
+
89
+
75
90
  def test_section_rule_counts_detail_and_skips_tables_link_lists_and_frontmatter() -> None:
76
91
  text = (
77
92
  "---\nname: x\ndescription: y\nmore: z\nand: w\nkeys: v\nhere: u\nlast: t\n---\n"
@@ -110,3 +125,76 @@ def test_relative_link_is_a_pointer_and_external_or_anchor_links_are_not() -> No
110
125
 
111
126
  assert scan_sections(pointed)[1].has_pointer is True
112
127
  assert scan_sections(external)[1].has_pointer is False
128
+
129
+
130
+ def test_scan_prose_collects_unlinked_detail_lines_over_the_word_limit() -> None:
131
+ long_unlinked = words_text(26)
132
+ exact_unlinked = words_text(25)
133
+ text = f"# Index\n{long_unlinked}\n{exact_unlinked}\nRead [the plan](reference/plan.md).\n"
134
+
135
+ scan = scan_prose(text, 25)
136
+
137
+ assert scan.all_long_unlinked_lines == (long_unlinked,)
138
+ assert scan.has_detail_line is True
139
+ assert scan.has_pointer_line is True
140
+
141
+
142
+ def test_scan_prose_ignores_fenced_code_tables_and_lines_that_link() -> None:
143
+ long_words = words_text(30)
144
+ text = "\n".join(
145
+ [
146
+ "```",
147
+ long_words,
148
+ "```",
149
+ f"| {long_words} |",
150
+ f"- [{long_words}](reference/plan.md)",
151
+ f"{long_words} [plan](reference/plan.md)",
152
+ ]
153
+ )
154
+
155
+ scan = scan_prose(text + "\n", 25)
156
+
157
+ assert scan.all_long_unlinked_lines == ()
158
+ assert scan.has_pointer_line is True
159
+
160
+
161
+ def test_scan_prose_counts_words_after_a_list_marker() -> None:
162
+ twenty_five = words_text(25)
163
+
164
+ assert scan_prose(f"- {twenty_five}\n", 25).all_long_unlinked_lines == ()
165
+ assert scan_prose(f"- {twenty_five} more\n", 25).all_long_unlinked_lines == (
166
+ f"- {twenty_five} more",
167
+ )
168
+
169
+
170
+ def test_scan_prose_does_not_count_a_lone_dash_as_a_word() -> None:
171
+ twenty_five = words_text(25)
172
+
173
+ assert scan_prose(f"{twenty_five} -\n", 25).all_long_unlinked_lines == ()
174
+
175
+
176
+ def test_scan_prose_reports_a_file_with_no_relative_link() -> None:
177
+ scan = scan_prose("Selection records own icon choice.\n", 25)
178
+
179
+ assert scan.has_detail_line is True
180
+ assert scan.has_pointer_line is False
181
+
182
+
183
+ def test_scan_prose_of_blank_or_heading_only_text_has_no_detail_line() -> None:
184
+ assert scan_prose("", 25).has_detail_line is False
185
+ assert scan_prose("# Only a heading\n", 25).has_detail_line is False
186
+
187
+
188
+ def test_import_line_counts_as_a_pointer_and_a_mention_does_not() -> None:
189
+ assert scan_prose("@AGENTS.md\n", 25).has_pointer_line is True
190
+ assert scan_prose(" @../shared/AGENTS.md\n", 25).has_pointer_line is True
191
+ assert scan_prose("@reviewer\n", 25).has_pointer_line is False
192
+ assert scan_prose("@reviewer review this\n", 25).has_pointer_line is False
193
+ assert scan_prose("@https://example.com/guide\n", 25).has_pointer_line is False
194
+ assert scan_prose("@MAILTO:team@example.com\n", 25).has_pointer_line is False
195
+
196
+
197
+ def test_import_line_is_not_a_section_pointer() -> None:
198
+ all_scans = scan_sections("## Plan\n@reference/plan.md\n")
199
+
200
+ assert all_scans[1].has_pointer is False
@@ -10,6 +10,7 @@ GIT_MARKER_NAME = ".git"
10
10
  UTF8_ENCODING = "utf-8"
11
11
 
12
12
  SECTION_DETAIL_LINE_LIMIT_KEY = "section_detail_line_limit"
13
+ PROSE_LINE_WORD_LIMIT_KEY = "prose_line_word_limit"
13
14
  KINDS_KEY = "kinds"
14
15
  HOOKS_KEY = "hooks"
15
16
  BASELINE_KEY = "baseline"
@@ -26,6 +27,8 @@ LINES_KEY = "lines"
26
27
  SECTIONS_KEY = "sections"
27
28
 
28
29
  DEFAULT_SECTION_DETAIL_LINE_LIMIT = 6
30
+ DEFAULT_PROSE_LINE_WORD_LIMIT = 25
31
+ ALL_PROSE_RULE_FILE_NAMES: frozenset[str] = frozenset({"AGENTS.md", "CLAUDE.md"})
29
32
  ALL_DEFAULT_KIND_SPECS: tuple[tuple[str, tuple[str, ...], int, bool], ...] = (
30
33
  ("skill entry", ("**/SKILL.md",), 200, True),
31
34
  ("agent instructions", ("**/AGENTS.md", "**/CLAUDE.md"), 60, True),
@@ -34,6 +37,8 @@ ALL_DEFAULT_KIND_SPECS: tuple[tuple[str, tuple[str, ...], int, bool], ...] = (
34
37
 
35
38
  TOP_SECTION_HEADING = "(top)"
36
39
  FILE_SCOPE = "file"
40
+ NO_POINTER_SCOPE = "no pointer line"
41
+ PROSE_LINE_SCOPE_PREFIX = "prose line: "
37
42
  FRONTMATTER_DELIMITER = "---"
38
43
  TABLE_ROW_PREFIX = "|"
39
44
  PATH_SEPARATOR = "/"
@@ -43,6 +48,9 @@ ATX_HEADING_PATTERN = re.compile(r"^ {0,3}#{1,6}(?:[ \t]+(?P<text>.*?))?(?:[ \t]
43
48
  FENCE_OPEN_PATTERN = re.compile(r"^ {0,3}(?P<marker>`{3,}|~{3,})")
44
49
  PURE_LINK_LIST_ITEM_PATTERN = re.compile(r"^\s*(?:[-*+]|\d+[.)])\s+\[[^\]]*\]\([^)]*\)\s*$")
45
50
  LINK_TARGET_PATTERN = re.compile(r"\[[^\]]*\]\(\s*<?(?P<target>[^)\s>]+)")
51
+ IMPORT_DIRECTIVE_PATTERN = re.compile(
52
+ r"^\s*@(?!(?:https?|mailto):)(?=\S*[./])\S+\s*$", re.IGNORECASE
53
+ )
46
54
  ALL_NON_RELATIVE_TARGET_PREFIXES: tuple[str, ...] = (
47
55
  "http:",
48
56
  "https:",
@@ -51,6 +59,7 @@ ALL_NON_RELATIVE_TARGET_PREFIXES: tuple[str, ...] = (
51
59
  "//",
52
60
  )
53
61
  NON_KEBAB_CHARACTER_PATTERN = re.compile(r"[^a-z0-9]+")
62
+ LIST_MARKER_PATTERN = re.compile(r"^\s*(?:[-*+]|\d+[.)])\s+")
54
63
 
55
64
  ENV_COMMAND_NAME = "env"
56
65
  ENV_ASSIGNMENT_SEPARATOR = "="
@@ -75,6 +84,14 @@ SECTION_FINDING_TEMPLATE = (
75
84
  "Move it to a reference file, for example reference/{kebab}.md, "
76
85
  "and replace the section with a one-line pointer to it. Cutting the section down to the limit keeps the detail inline and is not the fix."
77
86
  )
87
+ NO_POINTER_FINDING_TEMPLATE = (
88
+ MESSAGE_PREFIX + "file has no pointer line (a relative Markdown link or an @import line). "
89
+ "Add a one-line pointer to a reference file."
90
+ )
91
+ PROSE_LINE_FINDING_TEMPLATE = (
92
+ MESSAGE_PREFIX + 'line "{excerpt}" has {count} words and no pointer (limit {limit}). '
93
+ "Move the detail to a reference file and replace the line with a one-line pointer to it."
94
+ )
78
95
  FILE_FINDING_TEMPLATE = (
79
96
  MESSAGE_PREFIX + "file has {count} lines ({kind} limit {limit}). "
80
97
  "Move detail sections to reference files and leave one-line pointers."
@@ -122,6 +139,7 @@ CHANGE_ADDS_SECTION = 'baseline adds section "{heading}" to "{subject}"'
122
139
  CHANGE_ADDS_HOOK = 'baseline adds hook "{subject}"'
123
140
  CHANGE_RAISES_HOOK = 'baseline raises hook "{subject}" from {prior} to {current} characters'
124
141
  CHANGE_RAISES_SECTION_LIMIT = SECTION_DETAIL_LINE_LIMIT_KEY + " rises from {prior} to {current}"
142
+ CHANGE_RAISES_PROSE_LIMIT = PROSE_LINE_WORD_LIMIT_KEY + " rises from {prior} to {current}"
125
143
  CHANGE_RAISES_LINE_LIMIT = 'kind "{subject}" line_limit rises from {prior} to {current}'
126
144
  CHANGE_DISABLES_SECTION_RULE = 'kind "{subject}" turns its section rule off'
127
145
  CHANGE_DELETES_KIND = 'kind "{subject}" is deleted'
@@ -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
- UNPROVEN_ADMISSION_PATTERN = r"\b(?:not (?:(?:yet|been|fully) )*(?:proven|tested|verified)|unproven|untested|unverified)\b"
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 = (
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "claude-dev-env",
3
- "version": "8.108.3",
3
+ "version": "8.109.1",
4
4
  "description": "Claude Code development standards — rules, hooks, agents, commands, and skills",
5
5
  "type": "module",
6
6
  "bin": {