claude-dev-env 8.109.7 → 8.110.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.
Files changed (28) hide show
  1. package/.agents/agents/reference/pr-description-illustrative-voice.md +1 -0
  2. package/.agents/skills/pull-request/reference/body-sections.md +2 -2
  3. package/bin/install-pstack-plugin.mjs +80 -14
  4. package/bin/install-pstack-plugin.test.mjs +111 -40
  5. package/bin/install.mjs +23 -20
  6. package/bin/install.test.mjs +22 -17
  7. package/docs/rule-guides/proof-before-pull-request.md +1 -1
  8. package/hooks/blocking/body_flowchart.py +152 -0
  9. package/hooks/blocking/pr_lifecycle_skill_gate.py +5 -0
  10. package/hooks/blocking/pull_request_proof.py +67 -2
  11. package/hooks/blocking/reply_length_gate.py +17 -1
  12. package/hooks/blocking/test_body_flowchart.py +99 -0
  13. package/hooks/blocking/test_pr_lifecycle_skill_gate.py +6 -2
  14. package/hooks/blocking/test_pull_request_proof.py +98 -0
  15. package/hooks/blocking/test_reply_length_gate.py +120 -0
  16. package/hooks/features/conduct-gates.md +1 -1
  17. package/hooks/hooks_constants/body_flowchart_constants.py +18 -0
  18. package/hooks/hooks_constants/pull_request_proof_constants.py +8 -0
  19. package/hooks/hooks_constants/reply_length_gate_constants.py +1 -0
  20. package/hooks/hooks_constants/test_visual_reply_rules_constants.py +1 -0
  21. package/hooks/hooks_constants/visual_reply_rules_constants.py +19 -0
  22. package/hooks/test_visual_reply_rules.py +93 -0
  23. package/hooks/visual_reply_rules.py +61 -1
  24. package/package.json +1 -1
  25. package/rules/visual-reply-rules.json +5 -0
  26. package/scripts/durable_post_lint.py +15 -0
  27. package/scripts/durable_post_lint_config/config/constants.py +5 -0
  28. package/scripts/test_durable_post_lint.py +140 -1
@@ -0,0 +1,152 @@
1
+ """Find fenced lines and the mermaid flowchart in a pull request body."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from collections.abc import Iterator
6
+ from typing import NamedTuple
7
+
8
+ from hooks_constants.body_flowchart_constants import (
9
+ BACKTICK_FENCE_CHARACTER,
10
+ EDGE_LABEL_PATTERN,
11
+ FENCE_MARKER_GROUP,
12
+ FENCE_PREFIX_CHARACTERS,
13
+ FENCE_OPEN_PATTERN,
14
+ FLOWCHART_EDGE_PATTERN,
15
+ FLOWCHART_FIRST_LINE_PATTERN,
16
+ FRONT_MATTER_DELIMITER,
17
+ INFO_STRING_GROUP,
18
+ INFO_TAIL_GROUP,
19
+ MERMAID_COMMENT_PREFIX,
20
+ MERMAID_INFO_STRING,
21
+ NODE_TEXT_PATTERN,
22
+ TRAILING_COMMENT_PATTERN,
23
+ )
24
+
25
+
26
+ def _opening_fence(line: str) -> tuple[str, str] | None:
27
+ fence_match = FENCE_OPEN_PATTERN.match(line)
28
+ if fence_match is None:
29
+ return None
30
+ marker = fence_match.group(FENCE_MARKER_GROUP)
31
+ info_text = fence_match.group(INFO_STRING_GROUP) + fence_match.group(INFO_TAIL_GROUP)
32
+ if marker[0] == BACKTICK_FENCE_CHARACTER and BACKTICK_FENCE_CHARACTER in info_text:
33
+ return None
34
+ return marker, fence_match.group(INFO_STRING_GROUP)
35
+
36
+
37
+ def _closes_fence(line: str, open_fence: str) -> bool:
38
+ stripped_line = line.lstrip(FENCE_PREFIX_CHARACTERS).rstrip()
39
+ return len(stripped_line) >= len(open_fence) and set(stripped_line) == {open_fence[0]}
40
+
41
+
42
+ def _closing_index(all_lines: list[str], start_index: int, open_fence: str) -> int | None:
43
+ return next(
44
+ (each_index for each_index in range(start_index, len(all_lines)) if _closes_fence(all_lines[each_index], open_fence)),
45
+ None,
46
+ )
47
+
48
+
49
+ class FenceSpan(NamedTuple):
50
+ open_index: int
51
+ close_index: int | None
52
+ info_string: str
53
+
54
+
55
+ def _fence_spans(all_lines: list[str]) -> Iterator[FenceSpan]:
56
+ line_index = 0
57
+ while line_index < len(all_lines):
58
+ opening = _opening_fence(all_lines[line_index])
59
+ if opening is None:
60
+ line_index += 1
61
+ continue
62
+ marker, info_string = opening
63
+ close_index = _closing_index(all_lines, line_index + 1, marker)
64
+ yield FenceSpan(line_index, close_index, info_string)
65
+ if close_index is None:
66
+ return
67
+ line_index = close_index + 1
68
+
69
+
70
+ def fenced_line_flags(all_lines: list[str]) -> list[bool]:
71
+ """Return one flag per line: whether the line is a fence line or sits between two.
72
+
73
+ ::
74
+
75
+ ["a", "```", "# b", "```", "c"] -> [False, True, True, True, False]
76
+ ["a", "```", "# b"] -> [False, False, False]
77
+
78
+ A fence that never closes turns every flag to False, so one stray fence
79
+ leaves the body readable as plain text. A closing fence is a run of the
80
+ opening fence character at least as long as the opening run.
81
+
82
+ Args:
83
+ all_lines: The body split into lines.
84
+ """
85
+ all_flags = [False] * len(all_lines)
86
+ for each_span in _fence_spans(all_lines):
87
+ close_index = each_span.close_index
88
+ if close_index is None:
89
+ return [False] * len(all_lines)
90
+ all_flags[each_span.open_index : close_index + 1] = [True] * (close_index - each_span.open_index + 1)
91
+ return all_flags
92
+
93
+
94
+ def _closed_mermaid_blocks(section: str) -> Iterator[list[str]]:
95
+ all_lines = section.splitlines()
96
+ for each_span in _fence_spans(all_lines):
97
+ if each_span.close_index is not None and each_span.info_string.lower() == MERMAID_INFO_STRING:
98
+ yield [
99
+ each_line.lstrip(FENCE_PREFIX_CHARACTERS).rstrip()
100
+ for each_line in all_lines[each_span.open_index + 1 : each_span.close_index]
101
+ ]
102
+
103
+
104
+ def _without_labels(line: str) -> str:
105
+ return EDGE_LABEL_PATTERN.sub("", NODE_TEXT_PATTERN.sub("", TRAILING_COMMENT_PATTERN.sub("", line)))
106
+
107
+
108
+ def _without_front_matter(all_block_lines: list[str]) -> list[str]:
109
+ if not all_block_lines or all_block_lines[0] != FRONT_MATTER_DELIMITER:
110
+ return all_block_lines
111
+ closing_offset = next(
112
+ (each_index for each_index, each_line in enumerate(all_block_lines[1:], start=1) if each_line == FRONT_MATTER_DELIMITER),
113
+ None,
114
+ )
115
+ return [] if closing_offset is None else all_block_lines[closing_offset + 1 :]
116
+
117
+
118
+ def _is_flowchart(all_block_lines: list[str]) -> bool:
119
+ all_diagram_lines = [
120
+ each_line
121
+ for each_line in _without_front_matter(all_block_lines)
122
+ if each_line and not each_line.startswith(MERMAID_COMMENT_PREFIX)
123
+ ]
124
+ if not all_diagram_lines:
125
+ return False
126
+ if FLOWCHART_FIRST_LINE_PATTERN.match(all_diagram_lines[0]) is None:
127
+ return False
128
+ return any(
129
+ FLOWCHART_EDGE_PATTERN.search(_without_labels(each_line)) is not None
130
+ for each_line in all_diagram_lines
131
+ )
132
+
133
+
134
+ def section_has_flowchart(section: str) -> bool:
135
+ """Return whether a section holds a closed mermaid block that draws a flowchart.
136
+
137
+ ::
138
+
139
+ "```mermaid\\nflowchart LR\\n a --> b\\n```" -> True
140
+ "```mermaid\\nflowchart LR; a --> b\\n```" -> True
141
+ "```mermaid\\nsequenceDiagram\\n a->>b: hi\\n```" -> False
142
+ "```mermaid\\nflowchart LR\\n a\\n```" -> False
143
+ "```mermaid\\nflowchart LR\\n a --> b" -> False
144
+
145
+ The block opens with a fence whose info string is mermaid. Its first line,
146
+ after any front matter, starts with flowchart, and a line joins two nodes
147
+ with an arrow.
148
+
149
+ Args:
150
+ section: The text under one pull request description heading.
151
+ """
152
+ return any(_is_flowchart(each_block) for each_block in _closed_mermaid_blocks(section))
@@ -71,6 +71,7 @@ from blocking.pull_request_proof import (
71
71
  is_feature_pull_request,
72
72
  missing_eval_section_reason,
73
73
  missing_existing_work_reason,
74
+ missing_flowchart_reason,
74
75
  missing_look_reason,
75
76
  missing_proof_reason,
76
77
  )
@@ -336,6 +337,7 @@ def decision_for(all_payload_fields: dict[str, object]) -> dict[str, object] | N
336
337
  proof, or a body edit, holds a merge word -> DEFERRED_PROOF_REASON
337
338
  body edit whose proof has no command or only tests -> MISSING_PROOF_REASON or TEST_ONLY_PROOF_REASON
338
339
  new pull request with no existing-work section -> MISSING_EXISTING_WORK_REASON
340
+ pull request with no flowchart in What this does -> MISSING_FLOWCHART_REASON
339
341
  feature pull request with no eval section -> MISSING_EVAL_SECTION_REASON
340
342
  changed page whose proof shows no picture -> MISSING_LOOK_REASON
341
343
  feature pull request, no /claude-api build-eval -> MISSING_BUILD_EVAL_REASON
@@ -354,6 +356,9 @@ def decision_for(all_payload_fields: dict[str, object]) -> dict[str, object] | N
354
356
  search_reason = missing_existing_work_reason(all_payload_fields)
355
357
  if search_reason is not None:
356
358
  return deny_decision(search_reason)
359
+ flowchart_reason = missing_flowchart_reason(all_payload_fields)
360
+ if flowchart_reason is not None:
361
+ return deny_decision(flowchart_reason)
357
362
  eval_reason = missing_eval_section_reason(all_payload_fields)
358
363
  if eval_reason is not None:
359
364
  return deny_decision(eval_reason)
@@ -14,6 +14,7 @@ hooks_directory = str(Path(__file__).resolve().parent.parent)
14
14
  if hooks_directory not in sys.path:
15
15
  sys.path.insert(0, hooks_directory)
16
16
 
17
+ from blocking.body_flowchart import fenced_line_flags, section_has_flowchart
17
18
  from blocking.followup_pr_dedupe import body_from_arguments, create_tool_fields, title_from_arguments
18
19
  from hooks_constants.pr_lifecycle_skill_gate_constants import SHELL_TOOL_NAMES, UPDATE_PULL_REQUEST_TOOL_SUFFIX
19
20
  from hooks_constants.pull_request_proof_constants import (
@@ -50,6 +51,7 @@ from hooks_constants.pull_request_proof_constants import (
50
51
  REPOSITORY_ENDPOINT_TEMPLATE,
51
52
  REPOSITORY_FLAG_ASSIGNMENT_PREFIX,
52
53
  UNREADABLE_CHANGES_REASON,
54
+ WHAT_THIS_DOES_HEADING_PATTERN,
53
55
  EVAL_HEADING_PATTERN,
54
56
  EXISTING_WORK_HEADING_PATTERN,
55
57
  FEATURE_TITLE_PATTERN,
@@ -58,6 +60,7 @@ from hooks_constants.pull_request_proof_constants import (
58
60
  MISSING_BODY_REASON,
59
61
  MISSING_EVAL_SECTION_REASON,
60
62
  MISSING_EXISTING_WORK_REASON,
63
+ MISSING_FLOWCHART_REASON,
61
64
  MISSING_LOOK_REASON,
62
65
  MISSING_PROOF_REASON,
63
66
  NEW_WORKFLOW_PATH_PATTERN,
@@ -118,8 +121,9 @@ def _heading_level(line: str, heading_pattern: str) -> int | None:
118
121
 
119
122
 
120
123
  def _lines_until_heading(all_lines: list[str], heading_level: int) -> list[str]:
124
+ all_fenced_flags = fenced_line_flags(all_lines)
121
125
  for each_index, each_line in enumerate(all_lines):
122
- next_level = _heading_level(each_line, NEXT_HEADING_PATTERN)
126
+ next_level = None if all_fenced_flags[each_index] else _heading_level(each_line, NEXT_HEADING_PATTERN)
123
127
  if next_level is not None and next_level <= heading_level:
124
128
  return all_lines[:each_index]
125
129
  return all_lines
@@ -127,8 +131,9 @@ def _lines_until_heading(all_lines: list[str], heading_level: int) -> list[str]:
127
131
 
128
132
  def _section_text(body: str, heading_pattern: str) -> str | None:
129
133
  all_lines = body.splitlines()
134
+ all_fenced_flags = fenced_line_flags(all_lines)
130
135
  for each_index, each_line in enumerate(all_lines):
131
- heading_level = _heading_level(each_line, heading_pattern)
136
+ heading_level = None if all_fenced_flags[each_index] else _heading_level(each_line, heading_pattern)
132
137
  if heading_level is not None:
133
138
  all_section_lines = _lines_until_heading(all_lines[each_index + 1 :], heading_level)
134
139
  return LINE_SEPARATOR.join(all_section_lines).strip()
@@ -148,6 +153,21 @@ def proof_section(body: str) -> str | None:
148
153
  return _section_text(body, PROOF_HEADING_PATTERN)
149
154
 
150
155
 
156
+ def what_this_does_section(body: str) -> str | None:
157
+ """Return the text under the body's 'What this does' heading, or None.
158
+
159
+ ::
160
+
161
+ "## What this does\\nBefore, after.\\n## Risk" -> "Before, after."
162
+ "## Summary\\nno what-this-does heading" -> None
163
+
164
+ The section runs to the next heading of the same or a higher level. A line
165
+ that starts with a hash inside a fenced block is code, not a heading. When any fence
166
+ in the body never closes, every fence reads as plain text.
167
+ """
168
+ return _section_text(body, WHAT_THIS_DOES_HEADING_PATTERN)
169
+
170
+
151
171
  def section_under_existing_work(body: str) -> str | None:
152
172
  """Return the text under the body's 'Existing work' heading, or None.
153
173
 
@@ -664,6 +684,51 @@ def missing_existing_work_reason(all_payload_fields: Mapping[str, object]) -> st
664
684
  return None
665
685
 
666
686
 
687
+ def has_flowchart_under_what_this_does(body: str) -> bool:
688
+ """Return whether the body's 'What this does' section holds a mermaid flowchart.
689
+
690
+ ::
691
+
692
+ "## What this does\\n```mermaid\\nflowchart LR\\n a --> b\\n```" -> True
693
+ "## What this does\\nwords only" -> False
694
+ "## Summary\\nno what-this-does heading" -> False
695
+
696
+ Args:
697
+ body: The pull request body.
698
+ """
699
+ section = what_this_does_section(body)
700
+ return section is not None and section_has_flowchart(section)
701
+
702
+
703
+ def missing_flowchart_reason(all_payload_fields: Mapping[str, object]) -> str | None:
704
+ """Return a deny reason when a pull request body has no flowchart under 'What this does', else None.
705
+
706
+ ::
707
+
708
+ MCP create, flowchart under the heading -> None
709
+ MCP create, text only under the heading -> MISSING_FLOWCHART_REASON
710
+ MCP create, no 'What this does' heading -> MISSING_FLOWCHART_REASON
711
+ update_pull_request, heading and no flowchart -> MISSING_FLOWCHART_REASON
712
+ update_pull_request, no 'What this does' heading -> None
713
+ a create with --fill, any other tool -> None
714
+
715
+ A new pull request needs the flowchart. A body edit needs it only when the
716
+ body carries the heading, so an edit to an older body passes. A create
717
+ command whose body this gate cannot read passes here, because
718
+ missing_proof_reason denies it first.
719
+
720
+ Args:
721
+ all_payload_fields: The parsed PreToolUse input.
722
+ """
723
+ for each_body in _create_bodies(all_payload_fields):
724
+ if each_body is not None and not has_flowchart_under_what_this_does(each_body):
725
+ return MISSING_FLOWCHART_REASON
726
+ for each_body in _edit_bodies(all_payload_fields):
727
+ if what_this_does_section(each_body) is not None and not has_flowchart_under_what_this_does(each_body):
728
+ return MISSING_FLOWCHART_REASON
729
+ return None
730
+
731
+
667
732
  class ChangedFile(NamedTuple):
668
733
  path: str
669
734
  old_path: str
@@ -70,6 +70,10 @@ in the turn. A turn sends one reply, so a reply after a delivered reply in
70
70
  the same turn is denied. A widget may hold no anchor link, since a widget
71
71
  link does not open in the Claude app.
72
72
 
73
+ A reply that reports results, a markdown table or three or more figures outside
74
+ links and code, needs one picture: an image file in ``attached_outputs``, or a
75
+ markdown image. This check runs whether or not the visual mode is on.
76
+
73
77
  A length limit is a smell elsewhere in this package, recorded and fixed in a
74
78
  later pass. A posted reply reaches the user the moment it sends and has no
75
79
  later pass, so this gate denies it and the model resends a shorter one.
@@ -97,6 +101,7 @@ from visual_reply_rules import (
97
101
  abbreviation_violation,
98
102
  load_rules,
99
103
  mode_enabled,
104
+ results_picture_violation,
100
105
  second_reply_violation,
101
106
  successful_result_text,
102
107
  visual_violation,
@@ -127,6 +132,7 @@ from hooks_constants.reply_length_gate_constants import (
127
132
  ALL_DECISION_OPTION_LENGTH_KEYS,
128
133
  ALL_DECISION_OPTION_PROSE_KEYS,
129
134
  ALL_DEFAULT_BANNED_WORDS,
135
+ ALL_EDIT_TOOL_NAMES,
130
136
  ALL_EVIDENCE_PATTERNS,
131
137
  ALL_QUESTION_CARD_PROSE_KEYS,
132
138
  ALL_QUESTION_OPTION_PROSE_KEYS,
@@ -580,7 +586,17 @@ def _text_violation(
580
586
  reply_text = all_tool_input.get(TEXT_KEY)
581
587
  if not isinstance(reply_text, str):
582
588
  return None
583
- violation = reply_violation(reply_text, transcript_path, mode_rules)
589
+ all_checks = [lambda: reply_violation(reply_text, transcript_path, mode_rules)]
590
+ if tool_name not in ALL_EDIT_TOOL_NAMES:
591
+ all_checks.append(
592
+ lambda: results_picture_violation(
593
+ prose_outside_links(reply_text),
594
+ reply_text,
595
+ all_tool_input,
596
+ mode_rules if mode_rules is not None else load_rules(),
597
+ )
598
+ )
599
+ violation = collected_violations(all_checks)
584
600
  return None if violation is None else (violation, reply_text)
585
601
 
586
602
 
@@ -0,0 +1,99 @@
1
+ """Behavior tests for the mermaid flowchart reader of a pull request description section."""
2
+
3
+ import sys
4
+ from pathlib import Path
5
+
6
+ import pytest
7
+
8
+ HOOKS_DIRECTORY = Path(__file__).resolve().parent.parent
9
+ if str(HOOKS_DIRECTORY) not in sys.path:
10
+ sys.path.insert(0, str(HOOKS_DIRECTORY))
11
+
12
+ from blocking.body_flowchart import fenced_line_flags, section_has_flowchart
13
+
14
+
15
+ def _block(*all_lines: str, fence: str = "```") -> str:
16
+ return "\n".join([f"{fence}mermaid", *all_lines, fence])
17
+
18
+
19
+ @pytest.mark.parametrize(
20
+ "block",
21
+ [
22
+ _block("flowchart LR", " a --> b"),
23
+ _block("flowchart TD", " a[Start] -->|yes| b[End]"),
24
+ _block("flowchart LR", " a --> b --> c"),
25
+ _block("flowchart LR", " a --- b"),
26
+ _block("flowchart LR", " a -.-> b"),
27
+ _block("flowchart LR", " a ==> b"),
28
+ _block("flowchart LR; a --> b"),
29
+ "````mermaid\nflowchart LR\n a --> b\n`````",
30
+ "> ```mermaid\n> flowchart LR\n> a --> b\n> ```",
31
+ _block("---", "title: Flow", "---", "flowchart LR", " a --> b"),
32
+ "1. Flow:\n\n ```mermaid\n flowchart LR\n a --> b\n ```",
33
+ "```js```\n\n" + _block("flowchart LR", " a --> b"),
34
+ _block("flowchart LR", " a === b"),
35
+ _block("flowchart LR", " a -.- b"),
36
+ _block("flowchart LR", " a -..-> b"),
37
+ _block("flowchart LR", ' a["run --output x"] --> b[End]'),
38
+ _block("flowchart LR", " subgraph one", " a --> b", " end"),
39
+ _block("%% a note", "flowchart LR", "", " a --> b"),
40
+ _block("flowchart LR", " a --> b", fence="~~~"),
41
+ "Before the chart.\n\n" + _block("flowchart LR", " a --> b") + "\n\nAfter it.",
42
+ ],
43
+ )
44
+ def should_accept_a_closed_mermaid_flowchart_with_an_arrow(block: str) -> None:
45
+ assert section_has_flowchart(block)
46
+
47
+
48
+ @pytest.mark.parametrize(
49
+ "section",
50
+ [
51
+ "",
52
+ "Plain sentences and no chart.",
53
+ _block("sequenceDiagram", " a->>b: hi"),
54
+ _block("graph LR", " a --> b"),
55
+ _block("classDiagram", " a --> b"),
56
+ _block("flowchart LR"),
57
+ _block("---", "title: Flow", "---"),
58
+ _block("---", "flowchart LR", " a --> b"),
59
+ _block("flowchart LR", " a %% --> b"),
60
+ _block("flowchart LR", " only_node"),
61
+ _block("flowchart LR", " a", " b"),
62
+ _block("flowchart LR", " a --> "),
63
+ _block("flowchart LR", " a -->|label|"),
64
+ _block("flowchart LR", ' a["run --output x"]'),
65
+ _block("flowchart LR", " a[Start --> End]"),
66
+ _block("a --> b", "flowchart LR"),
67
+ "```text\nflowchart LR\n a --> b\n```",
68
+ "```mermaid\nflowchart LR\n a --> b",
69
+ "````text\n```mermaid\nflowchart LR\n a --> b\n```\n````",
70
+ "```mermaid\nflowchart LR\n a --> b\n``",
71
+ ],
72
+ )
73
+ def should_reject_a_section_without_a_closed_mermaid_flowchart_edge(section: str) -> None:
74
+ assert not section_has_flowchart(section)
75
+
76
+
77
+ def should_find_a_flowchart_after_a_block_of_another_diagram_type() -> None:
78
+ section = (
79
+ _block("sequenceDiagram", " a->>b: hi") + "\n\n" + _block("flowchart LR", " a --> b")
80
+ )
81
+ assert section_has_flowchart(section)
82
+
83
+
84
+ @pytest.mark.parametrize(
85
+ ("all_lines", "expected_flags"),
86
+ [
87
+ (["a", "```", "# b", "```", "c"], [False, True, True, True, False]),
88
+ (["a", "```", "# b"], [False, False, False]),
89
+ (["```", "x", "```", "# h", "~~~", "y", "~~~"], [True, True, True, False, True, True, True]),
90
+ (["````", "```", "# h", "```", "````", "# after"], [True, True, True, True, True, False]),
91
+ (["```", "x", "```", "```", "dangling"], [False] * 5),
92
+ (["> ```", "> # h", "> ```"], [True, True, True]),
93
+ (["plain", "# heading"], [False, False]),
94
+ ],
95
+ )
96
+ def should_flag_each_line_of_a_closed_fence_and_none_when_a_fence_stays_open(
97
+ all_lines: list[str], expected_flags: list[bool]
98
+ ) -> None:
99
+ assert fenced_line_flags(all_lines) == expected_flags
@@ -20,8 +20,12 @@ from hooks_constants.pull_request_proof_constants import (
20
20
  UNPROVEN_PROOF_REASON,
21
21
  )
22
22
 
23
+ WHAT_THIS_DOES_SECTION = (
24
+ "## What this does\nDraws the flow before and after.\n\n"
25
+ "```mermaid\nflowchart LR\n before --> after\n```\n\n"
26
+ )
23
27
  PROVEN_FOLLOWUP_BODY = (
24
- "Follow-up to #1731\n\n## Existing work\nNothing found in open or merged pull requests.\n\n"
28
+ "Follow-up to #1731\n\n" + WHAT_THIS_DOES_SECTION + "## Existing work\nNothing found in open or merged pull requests.\n\n"
25
29
  "## Proof in practice\nRan `python probe.py`.\n"
26
30
  )
27
31
 
@@ -370,7 +374,7 @@ def test_loaded_skill_denies_a_body_edit_that_adds_an_unrun_proof_line(tmp_path:
370
374
 
371
375
 
372
376
  EVALUATED_BODY = (
373
- "## Existing work\nNothing found in open or merged pull requests.\n\n"
377
+ WHAT_THIS_DOES_SECTION + "## Existing work\nNothing found in open or merged pull requests.\n\n"
374
378
  "## Proof in practice\nRan `python probe.py`.\n\n"
375
379
  "## Eval\nTen labeled cases, exact-match grader. Ran `python eval.py`: 10/10.\n"
376
380
  )
@@ -19,6 +19,7 @@ from hooks_constants.pull_request_proof_constants import (
19
19
  MISSING_BODY_REASON,
20
20
  MISSING_EVAL_SECTION_REASON,
21
21
  MISSING_EXISTING_WORK_REASON,
22
+ MISSING_FLOWCHART_REASON,
22
23
  MISSING_PROOF_REASON,
23
24
  TEST_ONLY_PROOF_REASON,
24
25
  UNPROVEN_PROOF_REASON,
@@ -346,6 +347,103 @@ def test_other_pull_request_commands_should_pass_the_existing_work_check() -> No
346
347
  assert gate.missing_existing_work_reason(_shell(each_command)) is None
347
348
 
348
349
 
350
+ FLOWCHART_BLOCK = "```mermaid\nflowchart LR\n before --> after\n```"
351
+ CHARTED_BODY = f"## What this does\nDraws the flow.\n\n{FLOWCHART_BLOCK}\n\n## Risk\nLow.\n"
352
+ CREATE_WITH_BODY_FILE = "gh pr create --title 't' --body-file body.md"
353
+
354
+
355
+ def _mcp_update(body: object) -> dict[str, object]:
356
+ return {
357
+ "tool_name": "mcp__github__update_pull_request",
358
+ "tool_input": {"owner": "o", "repo": "r", "pullNumber": 1, "body": body},
359
+ }
360
+
361
+
362
+ def test_what_this_does_section_should_stop_at_a_heading_of_the_same_level() -> None:
363
+ body = "### What this does\nBefore.\n#### Child\nkept\n### Risk\ndropped"
364
+ assert gate.what_this_does_section(body) == "Before.\n#### Child\nkept"
365
+
366
+
367
+ def test_what_this_does_section_should_return_none_without_the_heading() -> None:
368
+ assert gate.what_this_does_section(UNPROVEN_BODY) is None
369
+
370
+
371
+ def test_what_this_does_section_should_not_end_at_a_hash_line_inside_a_fenced_block() -> None:
372
+ body = f"## What this does\n```bash\n# old flow\nx\n```\n{FLOWCHART_BLOCK}\n## Risk\nLow.\n"
373
+ assert gate.has_flowchart_under_what_this_does(body)
374
+
375
+
376
+ def test_unclosed_fence_should_not_swallow_the_next_heading() -> None:
377
+ body = "## Proof in practice\nRan `python probe.py`.\n```\nout\n## Not covered\nnot run: x"
378
+ assert gate.proof_section(body) == "Ran `python probe.py`.\n```\nout"
379
+
380
+
381
+ def test_what_this_does_heading_inside_a_fenced_block_should_not_start_the_section() -> None:
382
+ body = f"```\n## What this does\n```\n\n{CHARTED_BODY}"
383
+ assert gate.has_flowchart_under_what_this_does(body)
384
+
385
+
386
+ def test_has_flowchart_under_what_this_does_should_read_only_that_section() -> None:
387
+ assert gate.has_flowchart_under_what_this_does(CHARTED_BODY)
388
+ assert not gate.has_flowchart_under_what_this_does(f"## What this does\nWords.\n\n## Risk\n{FLOWCHART_BLOCK}\n")
389
+ assert not gate.has_flowchart_under_what_this_does(f"{FLOWCHART_BLOCK}\n")
390
+
391
+
392
+ def test_mcp_create_with_a_flowchart_under_what_this_does_should_pass() -> None:
393
+ assert gate.missing_flowchart_reason(_mcp_create(CHARTED_BODY)) is None
394
+
395
+
396
+ def test_mcp_create_with_text_only_under_what_this_does_should_be_denied() -> None:
397
+ body = "## What this does\nDraws the flow in words.\n\n## Risk\nLow.\n"
398
+ assert gate.missing_flowchart_reason(_mcp_create(body)) == MISSING_FLOWCHART_REASON
399
+
400
+
401
+ def test_mcp_create_without_a_what_this_does_heading_should_be_denied() -> None:
402
+ assert gate.missing_flowchart_reason(_mcp_create(SEARCHED_BODY)) == MISSING_FLOWCHART_REASON
403
+
404
+
405
+ def test_mcp_create_with_the_flowchart_under_another_heading_should_be_denied() -> None:
406
+ body = f"## What this does\nWords.\n\n## Risk\n{FLOWCHART_BLOCK}\n"
407
+ assert gate.missing_flowchart_reason(_mcp_create(body)) == MISSING_FLOWCHART_REASON
408
+
409
+
410
+ def test_mcp_create_with_a_sequence_diagram_should_be_denied() -> None:
411
+ body = "## What this does\n```mermaid\nsequenceDiagram\n a->>b: hi\n```\n"
412
+ assert gate.missing_flowchart_reason(_mcp_create(body)) == MISSING_FLOWCHART_REASON
413
+
414
+
415
+ def test_body_file_create_without_a_flowchart_should_be_denied(tmp_path: Path) -> None:
416
+ (tmp_path / "body.md").write_text("## What this does\nWords only.\n", encoding="utf-8")
417
+ assert gate.missing_flowchart_reason(_shell(CREATE_WITH_BODY_FILE, tmp_path)) == MISSING_FLOWCHART_REASON
418
+
419
+
420
+ def test_body_file_create_with_a_flowchart_should_pass(tmp_path: Path) -> None:
421
+ (tmp_path / "body.md").write_text(CHARTED_BODY, encoding="utf-8")
422
+ assert gate.missing_flowchart_reason(_shell(CREATE_WITH_BODY_FILE, tmp_path)) is None
423
+
424
+
425
+ def test_flowchart_check_should_skip_an_unreadable_shell_body_and_deny_an_empty_mcp_body() -> None:
426
+ assert gate.missing_flowchart_reason(_shell("gh pr create --fill")) is None
427
+ assert gate.missing_flowchart_reason(_mcp_create(None)) == MISSING_FLOWCHART_REASON
428
+
429
+
430
+ def test_edit_with_the_heading_and_no_flowchart_should_be_denied() -> None:
431
+ body = "## What this does\nWords only.\n"
432
+ assert gate.missing_flowchart_reason(_mcp_update(body)) == MISSING_FLOWCHART_REASON
433
+
434
+
435
+ def test_edit_with_a_flowchart_should_pass() -> None:
436
+ assert gate.missing_flowchart_reason(_mcp_update(CHARTED_BODY)) is None
437
+
438
+
439
+ def test_edit_of_an_older_body_without_the_heading_should_pass() -> None:
440
+ assert gate.missing_flowchart_reason(_mcp_update(SEARCHED_BODY)) is None
441
+
442
+
443
+ def test_other_tools_should_pass_the_flowchart_check() -> None:
444
+ assert gate.missing_flowchart_reason(_shell("git push origin main")) is None
445
+
446
+
349
447
  def _repository_with_change(tmp_path: Path, changed_file_name: str) -> Path:
350
448
  origin_path = tmp_path / "origin"
351
449
  clone_path = tmp_path / "clone"