claude-dev-env 8.76.0 → 8.77.0

package/hooks/blocking/reply_length_gate.py

@@ -57,6 +57,7 @@ later pass, so this gate denies it and the model resends a shorter one.
 
 from __future__ import annotations
 
+import json
 import os
 import re
 import sys
@@ -75,9 +76,14 @@ from visual_reply_rules import (
     second_reply_violation,
     visual_violation,
     widget_anchor_violation,
+    widget_flowchart_advice,
 )
 from hooks_constants.hook_block_logger import log_hook_block
 from hooks_constants.pre_tool_use_stdin import read_hook_input_dictionary_from_stdin
+from hooks_constants.hook_specific_output_keys import (
+    HOOK_EVENT_NAME_KEY,
+    HOOK_SPECIFIC_OUTPUT_KEY,
+)
 from hooks_constants.reply_length_gate_constants import (
     ALL_CHECKED_TOOL_NAMES,
     ALL_DECISION_CARD_PROSE_KEYS,
@@ -101,6 +107,7 @@ from hooks_constants.reply_length_gate_constants import (
     EM_DASH_MESSAGE,
     EM_DASH_PATTERN,
     FENCED_BLOCK_PATTERN,
+    ADDITIONAL_CONTEXT_KEY,
     HOOK_EVENT_NAME,
     INLINE_CODE_PATTERN,
     LINE_BREAK_PATTERN,
@@ -322,6 +329,18 @@ def tool_violation(
     return None if violation is None else (violation, reply_text)
 
 
+def write_flowchart_advice(tool_name: object, all_tool_input: dict[str, object]) -> None:
+    """Print the flowchart advice for an allowed widget call that is not a flowchart."""
+    mode_rules = active_mode_rules()
+    if not isinstance(tool_name, str) or mode_rules is None:
+        return
+    advice = widget_flowchart_advice(tool_name, all_tool_input, mode_rules)
+    if advice is None:
+        return
+    hook_event_output = {HOOK_EVENT_NAME_KEY: HOOK_EVENT_NAME, ADDITIONAL_CONTEXT_KEY: advice}
+    sys.stdout.write(json.dumps({HOOK_SPECIFIC_OUTPUT_KEY: hook_event_output}))
+
+
 def main() -> int:
     hook_input = read_hook_input_dictionary_from_stdin()
     if hook_input is None:
@@ -332,6 +351,7 @@ def main() -> int:
         return ALLOW_EXIT_CODE
     checked = tool_violation(tool_name, tool_input, hook_input.get(TRANSCRIPT_PATH_KEY))
     if checked is None:
+        write_flowchart_advice(tool_name, tool_input)
         return ALLOW_EXIT_CODE
     violation, reply_text = checked
     block_reason = violation + RETRY_INSTRUCTION

package/hooks/blocking/test_reply_length_gate.py

@@ -635,13 +635,21 @@ def test_should_deny_an_anchor_link_inside_widget_code(
     assert "does not open in the Claude app" in stderr_text
 
 
-def test_should_allow_widget_code_with_no_anchor(
+def test_should_allow_widget_code_with_no_anchor_and_advise_a_flowchart(
     monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
 ) -> None:
-    exit_code, _ = run_gate(
-        monkeypatch, capsys, WIDGET_TOOL_NAME, {"widget_code": "<div>Three steps</div>"}
+    hook_input = {
+        "hook_event_name": "PreToolUse",
+        "tool_name": WIDGET_TOOL_NAME,
+        "tool_input": {"widget_code": "<div>Three steps</div>"},
+    }
+    monkeypatch.setattr(
+        "sys.stdin", io.TextIOWrapper(io.BytesIO(json.dumps(hook_input).encode("utf-8")))
     )
+    exit_code = reply_length_gate.main()
     assert exit_code == 0
+    advice_output = json.loads(capsys.readouterr().out)
+    assert "Redraw this widget as one SVG flowchart" in advice_output["hookSpecificOutput"]["additionalContext"]
 
 
 def test_should_skip_the_mode_checks_when_the_switch_turns_the_mode_off(

package/hooks/features/conduct-gates.md

@@ -30,7 +30,7 @@ Preconditions:
 
 - Run each command from the repository root with Python and pytest available. The tests create transcript and payload fixtures.
 
-- **Reply length.** Input is a reply with four sentences, a plain pull request number, an abbreviation, two sentences with no widget this turn, or widget code with an anchor link. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_reply_length_gate.py -q`. The adjacent test observes a denial and its count, link, or mode reason.
+- **Reply length.** Input is a reply with four sentences, a plain pull request number, an abbreviation, two sentences with no widget this turn, or widget code with an anchor link. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_reply_length_gate.py -q`. The adjacent test observes a denial and its count, link, or mode reason. Widget code with no flowchart passes with a flowchart reminder in `additionalContext`.
 - **Edit marker.** Input is an update message with strikethrough or an edit note. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_edit_marker_gate.py -q`. The adjacent test observes a denial; clean replacement text passes.
 - **Handoff close.** Input is an issue comment that says the issue is closed and that the found defect belongs to another issue. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_issue_close_handoff_gate.py -q`. The adjacent test observes a denial; a close with a plain cross-reference and a routing comment on an open issue both pass.
 - **Session title.** Input is a set session title call with no leading emoji or a name over 25 characters. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_session_title_format_gate.py -q`. The adjacent test observes a denial that names the broken rule; a well-formed title passes.

package/hooks/hooks_constants/reply_length_gate_constants.py

@@ -88,3 +88,5 @@ BANNED_WORD_MESSAGE = 'Banned word "{banned_word}". Delete it and name the evide
 LONG_SENTENCE_MESSAGE = (
     'Sentence too long: {word_count} words, limit {word_limit}: "{sentence_preview}".'
 )
+
+ADDITIONAL_CONTEXT_KEY = "additionalContext"

package/hooks/hooks_constants/test_visual_reply_rules_constants.py

@@ -26,6 +26,7 @@ def test_rule_key_constants_name_rules_in_the_shipped_rule_list() -> None:
         constants.NO_PICTURE_RULE_KEY,
         constants.ABBREVIATIONS_RULE_KEY,
         constants.ONE_ITEM_RULE_KEY,
+        constants.FLOWCHART_RULE_KEY,
     } <= all_shipped_keys
     assert constants.ALLOWED_CAPITALIZED_WORDS_KEY in rules_document
     assert constants.LOWERCASE_ABBREVIATIONS_KEY in rules_document

package/hooks/hooks_constants/visual_reply_rules_constants.py

@@ -36,6 +36,15 @@ TRACKER_NUMBER_PATTERN = re.compile(
     r"\b(?:issues?|items?|cards?|tickets?|tasks?)\s*#?\d+", re.IGNORECASE
 )
 WIDGET_ANCHOR_PATTERN = re.compile(r"<a\b[^>]*\bhref\s*=", re.IGNORECASE)
+FLOWCHART_RULE_KEY = "not_flowchart"
+WIDGET_CODE_KEY = "widget_code"
+WIDGET_INPUT_KEY = "input"
+FLOWCHART_SVG_PATTERN = re.compile(r"<svg\b", re.IGNORECASE)
+FLOWCHART_ARROW_PATTERN = re.compile(r"marker-end", re.IGNORECASE)
+FLOWCHART_MARKER_BLOCK_PATTERN = re.compile(r"<marker\b[^>]*(?<!/)>.*?</marker>", re.IGNORECASE | re.DOTALL)
+FLOWCHART_DIAMOND_PATTERN = re.compile(
+    r"<polygon\b|<path\b[^>]*\bd=[\"']M[^\"']*L[^\"']*L[^\"']*L[^\"']*Z[\"']", re.IGNORECASE
+)
 
 TRANSCRIPT_ENCODING = "utf-8"
 ENTRY_TYPE_KEY = "type"
@@ -57,6 +66,7 @@ ABBREVIATION_MESSAGE = 'Abbreviation "{abbreviation}" in the text. {reminder}'
 TRACKER_NUMBER_MESSAGE = 'Tracker number "{reference}" in the text. {reminder}'
 NO_VISUAL_MESSAGE = "This reply has {sentence_count} sentences and no visual this turn. {reminder}"
 SECOND_REPLY_MESSAGE = "A reply already went out this turn. {reminder}"
+NOT_FLOWCHART_MESSAGE = "This widget is not a flowchart. {reminder}"
 WIDGET_ANCHOR_MESSAGE = (
     "A link sits inside the widget code, and a widget link does not open in the Claude app."
     " Remove the anchor and put the page link in the reply text."

package/hooks/test_context_budget_hooks.py

@@ -24,6 +24,7 @@ CONTEXT_OUTPUT_PATTERN = re.compile(r"additionalContext|ADDITIONAL_CONTEXT|addit
 UNMEASURED_REASON_BY_SCRIPT = {
     "blocking/pre_tool_use_dispatcher.py": "relays its hosted hooks' output",
     "blocking/bash_pre_tool_use_dispatcher.py": "relays its hosted hooks' output",
+    "blocking/reply_length_gate.py": "advises only on a widget while visual reply mode is on",
     "lifecycle/nested_project_hooks.py": "relays a nested project's own hooks",
     "routing/thread_spawn_pace_hook.py": "quotes a usage reading capped by its own constant",
     "session/issue_tracker_session_starter.py": "emits only for a repository the user's "

package/hooks/test_visual_reply_rules.py

@@ -8,6 +8,7 @@ _hooks_directory = str(Path(__file__).resolve().parent)
 if _hooks_directory not in sys.path:
     sys.path.insert(0, _hooks_directory)
 
+from hooks_constants.visual_reply_rules_constants import RULES_FILE_PATH
 from visual_reply_rules import (
     abbreviation_violation,
     load_rules,
@@ -17,6 +18,7 @@ from visual_reply_rules import (
     visual_shown_this_turn,
     visual_violation,
     widget_anchor_violation,
+    widget_flowchart_advice,
 )
 
 SHIPPED_RULES = load_rules()
@@ -162,3 +164,46 @@ def test_second_reply_violation_denies_only_after_a_delivered_reply(tmp_path: Pa
     )
     assert second_reply_violation(str(transcript_path), SHIPPED_RULES) is not None
     assert second_reply_violation(str(tmp_path / "missing.jsonl"), SHIPPED_RULES) is None
+
+
+FLOWCHART_CODE = (
+    '<svg><path d="M0 20L40 0L80 20L40 40Z"/>'
+    '<path d="M80 20H120" marker-end="url(#a)"/></svg>'
+)
+
+
+def test_widget_flowchart_advice_should_pass_an_svg_with_a_diamond_and_arrows() -> None:
+    rules = load_rules()
+    assert rules is not None
+    nested_input = {"input": {"widget_code": FLOWCHART_CODE}}
+    assert widget_flowchart_advice("mcp__hearthbot__post_widget", nested_input, rules) is None
+
+
+def test_widget_flowchart_advice_should_advise_on_cards_and_shapes_without_a_decision() -> None:
+    rules = load_rules()
+    assert rules is not None
+    card_input = {"widget_code": "<div class='card'>Merged</div>"}
+    no_diamond_input = {"widget_code": '<svg><path marker-end="url(#a)"/></svg>'}
+    arrowhead_only_input = {
+        "widget_code": '<svg><marker id="a"><polygon points="0 0,9 5,0 9"/></marker>'
+        '<rect/><path marker-end="url(#a)"/></svg>'
+    }
+    for each_input in (card_input, no_diamond_input, arrowhead_only_input):
+        reason = widget_flowchart_advice("mcp__hearthbot__post_widget", each_input, rules)
+        assert reason is not None and "diamond" in reason
+    assert widget_flowchart_advice("mcp__hearthbot__reply", card_input, rules) is None
+
+
+def test_widget_flowchart_advice_should_stay_quiet_when_the_rule_list_has_no_flowchart_rule(
+    tmp_path: Path,
+) -> None:
+    shipped_document = json.loads(RULES_FILE_PATH.read_text(encoding="utf-8"))
+    shipped_document["rules"] = [
+        each for each in shipped_document["rules"] if each["key"] != "not_flowchart"
+    ]
+    rules_path = tmp_path / "rules.json"
+    rules_path.write_text(json.dumps(shipped_document), encoding="utf-8")
+    rules = load_rules(rules_path)
+    assert rules is not None
+    card_input = {"widget_code": "<div class='card'>Merged</div>"}
+    assert widget_flowchart_advice("mcp__hearthbot__post_widget", card_input, rules) is None

package/hooks/visual_reply_rules.py

@@ -58,6 +58,14 @@ from hooks_constants.visual_reply_rules_constants import (
     TRANSCRIPT_ENCODING,
     USER_ENTRY_TYPE,
     WIDGET_ANCHOR_MESSAGE,
+    FLOWCHART_ARROW_PATTERN,
+    FLOWCHART_DIAMOND_PATTERN,
+    FLOWCHART_MARKER_BLOCK_PATTERN,
+    FLOWCHART_RULE_KEY,
+    FLOWCHART_SVG_PATTERN,
+    NOT_FLOWCHART_MESSAGE,
+    WIDGET_CODE_KEY,
+    WIDGET_INPUT_KEY,
     WIDGET_ANCHOR_PATTERN,
     WIDGET_TOOL_NAME_SUFFIX,
 )
@@ -153,6 +161,35 @@ def widget_anchor_violation(tool_name: str, all_tool_input: dict[str, object]) -
     return WIDGET_ANCHOR_MESSAGE if WIDGET_ANCHOR_PATTERN.search(serialized_input) else None
 
 
+def widget_flowchart_advice(
+    tool_name: str, all_tool_input: dict[str, object], rules: VisualReplyRules
+) -> str | None:
+    """Return the advice for widget code that is not a flowchart, else None.
+
+    The gate passes this advice to the session and still allows the call.
+
+    A flowchart widget is one SVG with at least one arrow marker and one
+    diamond shape for a yes or no check. Shapes inside a ``<marker>`` block
+    are arrowheads, so they never count as the diamond::
+
+        <svg><path d="M0 0L9 5L0 9L-9 5Z"/><path marker-end="url(#a)"/></svg>
+    """
+    all_rule_keys = {each.key for each in rules.all_rules}
+    if not tool_name.endswith(WIDGET_TOOL_NAME_SUFFIX) or FLOWCHART_RULE_KEY not in all_rule_keys:
+        return None
+    widget_code = all_tool_input.get(WIDGET_CODE_KEY)
+    if widget_code is None:
+        widget_input = all_tool_input.get(WIDGET_INPUT_KEY)
+        widget_code = widget_input.get(WIDGET_CODE_KEY) if isinstance(widget_input, dict) else None
+    code_text = FLOWCHART_MARKER_BLOCK_PATTERN.sub(
+        "", widget_code if isinstance(widget_code, str) else ""
+    )
+    all_shape_patterns = (FLOWCHART_SVG_PATTERN, FLOWCHART_ARROW_PATTERN, FLOWCHART_DIAMOND_PATTERN)
+    if all(each_pattern.search(code_text) for each_pattern in all_shape_patterns):
+        return None
+    return NOT_FLOWCHART_MESSAGE.format(reminder=rules.reminder(FLOWCHART_RULE_KEY))
+
+
 def _parsed_entries(all_transcript_lines: Iterable[str]) -> list[dict[str, object]]:
     all_entries = []
     for each_line in all_transcript_lines:

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "claude-dev-env",
-    "version": "8.76.0",
+    "version": "8.77.0",
     "description": "Claude Code development standards — rules, hooks, agents, commands, and skills",
     "type": "module",
     "bin": {

package/rules/visual-reply-rules.json

@@ -8,7 +8,7 @@
     {
       "key": "no_picture",
       "label": "No picture",
-      "reminder": "Show the item as one visual first, a widget or a published page. Then send one reply of one to three short sentences that states the outcome and each fact the user needs, and links the page."
+      "reminder": "Show the item as one visual first, a widget or a published page. Prefer a flowchart that runs left to right, with boxes for steps, a diamond for each yes or no check, and arrows between them. Then send one reply of one to three short sentences that states the outcome and each fact the user needs, and links the page."
     },
     {
       "key": "too_many_words",
@@ -25,6 +25,11 @@
       "label": "Wall of text",
       "reminder": "Put each point, and each step the reader takes, on its own line."
     },
+    {
+      "key": "not_flowchart",
+      "label": "No flowchart",
+      "reminder": "Redraw this widget as one SVG flowchart that runs left to right, with boxes for steps, a diamond for each yes or no check, and arrows between them, unless the item has no steps or checks."
+    },
     {
       "key": "use_flowchart",
       "label": "Use the flowchart",