claude-dev-env 8.75.5 → 8.77.0

package/docs/templates/artifact-page/README.md

@@ -1,14 +1,17 @@
 # Artifact page template
 
-Two templates live here. Pick the one that fits the ask before you write a line.
+Three templates live here. Pick the one that fits the ask before you write a line.
 
 | Ask | Template |
 |---|---|
-| A tracker, board, review page or dashboard that people read and click | `template.html` |
+| A status or progress report on one piece of work: what is done, where it is stuck, and what comes next. Prefer it for every such report unless the person asks for another shape | `status-flowchart.html` |
+| A tracker, board, review page or dashboard that lists many items for people to read and click | `template.html` |
 | A picture of how things connect: a map, a flow, who calls what, old next to new. Also any ask for "only visuals" or "no words" | `diagram.html` |
 
 `diagram.html` draws the content in inline SVG: boxes for things, arrows for links, and color for state. Labels are a few words. Text in bordered cards is a tracker, so it never answers a visual-only ask.
 
+`status-flowchart.html` reads left to right. Done steps are green boxes, each yes-or-no check is a diamond, a stuck step is an amber box under its check with a dashed recheck loop back to it, and the next step is a dashed box. A click on any shape opens its detail from the `detail-data` block below the chart. Replace the `<title>`, the `h1`, the svg `aria-label`, the shapes, the arrows and the `detail-data` entries with the work being reported. Keep each label to three words or fewer, in plain words with no abbreviations or item numbers.
+
 Render the page and look at the screenshot before you publish. Headless Chromium renders at least 500 pixels wide, so take the screenshot at 800 wide.
 
 `template.html` is the reference page for any artifact an agent builds: a tracker, a board, a review page, a dashboard. Start from it, keep its structure and house style, and replace the sample data and the parts the new page does not need.

package/docs/templates/artifact-page/status-flowchart.html

@@ -0,0 +1,98 @@
+<title>Status Flowchart</title>
+<style>
+:root{--bg:#f3f5f8;--surface:#ffffff;--fg:#18202c;--line:#7d8798;--ok:#16653d;--ok-soft:#e1f3e8;--warn:#7a4800;--warn-soft:#fdf0d6;--here:#2245a2;--here-soft:#e5ebfb;--font:"Segoe UI",system-ui,-apple-system,sans-serif}
+@media (prefers-color-scheme:dark){:root:not([data-theme="light"]){--bg:#11151b;--surface:#1a2029;--fg:#e8ebf1;--line:#7c879c;--ok:#72d6a3;--ok-soft:#163326;--warn:#f2bc63;--warn-soft:#382b13;--here:#a9c0ff;--here-soft:#1f2a46;color-scheme:dark}}
+:root[data-theme="dark"]{--bg:#11151b;--surface:#1a2029;--fg:#e8ebf1;--line:#7c879c;--ok:#72d6a3;--ok-soft:#163326;--warn:#f2bc63;--warn-soft:#382b13;--here:#a9c0ff;--here-soft:#1f2a46;color-scheme:dark}
+body{background:var(--bg);color:var(--fg);font:16px/1.45 var(--font);margin:0;padding-inline:16px;padding-block:20px 40px}
+.wrap{max-width:1120px;margin:0 auto;display:grid;gap:14px}
+h1{font-size:22px;margin:0;text-wrap:balance}
+.scroll{overflow-x:auto;background:var(--surface);border:1.5px solid var(--line);border-radius:14px}
+svg{display:block;width:100%;min-width:820px;height:auto;color:var(--fg)}
+svg text{font:600 15px var(--font);fill:currentColor}
+svg .lbl{font:700 13px var(--font)}
+.n{cursor:pointer}
+.n:focus{outline:none}
+.n:focus-visible .s,.n.on .s{stroke:var(--here);stroke-width:4}
+.n:hover .s{stroke:var(--here)}
+.s{stroke-width:2.5}
+.done .s{fill:var(--ok-soft);stroke:var(--ok)}
+.wait .s{fill:var(--warn-soft);stroke:var(--warn)}
+.ask .s{fill:var(--surface);stroke:var(--line)}
+.next .s{fill:var(--surface);stroke:var(--line);stroke-dasharray:6 5}
+.start .s{fill:var(--here-soft);stroke:var(--here)}
+.e{stroke:var(--line);stroke-width:2.5;fill:none}
+.e.loop{stroke:var(--warn);stroke-dasharray:5 5}
+.y{fill:var(--ok)!important}.no{fill:var(--warn)!important}
+.det{background:var(--surface);border:2px solid var(--here);border-radius:14px;padding:12px 16px;display:grid;gap:4px;min-height:64px}
+.det b{font-size:18px}
+.det p{margin:0;max-width:70ch}
+.key{display:flex;flex-wrap:wrap;gap:6px 16px;font-size:14px;font-weight:600}
+.key span{display:inline-flex;align-items:center;gap:6px}
+.key i{width:16px;height:12px;border-radius:3px;border:2px solid}
+@media (prefers-reduced-motion:no-preference){.s{transition:stroke .12s}}
+</style>
+
+<div class="wrap">
+  <h1>Broker install fix: where it stands</h1>
+  <div class="key">
+    <span><i style="background:var(--ok-soft);border-color:var(--ok)"></i>Done</span>
+    <span><i style="background:var(--warn-soft);border-color:var(--warn)"></i>Stuck here now</span>
+    <span><i style="border-color:var(--line);border-style:dashed"></i>Next</span>
+  </div>
+  <div class="scroll">
+    <svg viewBox="0 0 1100 320" role="group" aria-label="Broker install fix flowchart. Main merged and tests pass. Two checks are stuck: GitHub still shows a conflict, and no checks ran. The merge waits for both.">
+      <defs>
+        <marker id="status-arrow" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse"><path d="M0 0L10 5L0 10z" fill="currentColor" opacity=".7"/></marker>
+        <marker id="status-arrow-stuck" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse"><path d="M0 0L10 5L0 10z" style="fill:var(--warn)"/></marker>
+      </defs>
+
+      <line class="e" x1="125" y1="95" x2="168" y2="95" marker-end="url(#status-arrow)"/>
+      <line class="e" x1="302" y1="95" x2="345" y2="95" marker-end="url(#status-arrow)"/>
+      <line class="e" x1="479" y1="95" x2="512" y2="95" marker-end="url(#status-arrow)"/>
+      <line class="e" x1="668" y1="95" x2="712" y2="95" marker-end="url(#status-arrow)"/>
+      <text class="lbl y" x="690" y="85" text-anchor="middle">yes</text>
+      <line class="e" x1="868" y1="95" x2="922" y2="95" marker-end="url(#status-arrow)"/>
+      <text class="lbl y" x="895" y="85" text-anchor="middle">yes</text>
+
+      <line class="e" x1="590" y1="150" x2="590" y2="208" marker-end="url(#status-arrow)"/>
+      <text class="lbl no" x="602" y="185">no</text>
+      <line class="e" x1="790" y1="150" x2="790" y2="208" marker-end="url(#status-arrow)"/>
+      <text class="lbl no" x="802" y="185">no</text>
+
+      <path class="e loop" d="M520 240 H496 V130 H560" marker-end="url(#status-arrow-stuck)"/>
+      <text class="lbl no" x="488" y="186" text-anchor="end">recheck</text>
+      <path class="e loop" d="M720 240 H694 V130 H760" marker-end="url(#status-arrow-stuck)"/>
+
+      <g class="n start" tabindex="0" data-k="start"><rect class="s" x="15" y="67" width="110" height="56" rx="28"/><text x="70" y="100" text-anchor="middle">Start fix</text></g>
+      <g class="n done" tabindex="0" data-k="merge"><rect class="s" x="170" y="67" width="132" height="56" rx="10"/><text x="236" y="100" text-anchor="middle">&#10003; Merge main</text></g>
+      <g class="n done" tabindex="0" data-k="tests"><rect class="s" x="347" y="67" width="132" height="56" rx="10"/><text x="413" y="100" text-anchor="middle">&#10003; 12 tests</text></g>
+      <g class="n ask" tabindex="0" data-k="q1"><polygon class="s" points="590,40 668,95 590,150 512,95"/><text x="590" y="91" text-anchor="middle">Conflict</text><text x="590" y="110" text-anchor="middle">cleared?</text></g>
+      <g class="n ask" tabindex="0" data-k="q2"><polygon class="s" points="790,40 868,95 790,150 712,95"/><text x="790" y="91" text-anchor="middle">Checks</text><text x="790" y="110" text-anchor="middle">ran?</text></g>
+      <g class="n next" tabindex="0" data-k="end"><rect class="s" x="924" y="67" width="150" height="56" rx="28"/><text x="999" y="100" text-anchor="middle">Merge</text></g>
+      <g class="n wait" tabindex="0" data-k="w1"><rect class="s" x="520" y="210" width="140" height="60" rx="10"/><text x="590" y="236" text-anchor="middle">&#8987; Still shows</text><text x="590" y="256" text-anchor="middle">conflict</text></g>
+      <g class="n wait" tabindex="0" data-k="w2"><rect class="s" x="720" y="210" width="140" height="60" rx="10"/><text x="790" y="246" text-anchor="middle">&#8987; Checks missing</text></g>
+    </svg>
+  </div>
+  <div class="det" id="det" aria-live="polite"></div>
+</div>
+
+<script type="application/json" id="detail-data">
+{
+ "start":{"t":"Start fix","p":"Broker shared install path. A helper fixed it, then a hook blocked its commit. I committed and pushed."},
+ "merge":{"t":"Merge main: done","p":"Main merged in and pushed. 0 commits behind main. The test merge has no conflicts."},
+ "tests":{"t":"12 tests: done","p":"All 12 broker tests pass on the new commit."},
+ "q1":{"t":"Conflict cleared?","p":"GitHub's own merge check. It must clear before the merge."},
+ "w1":{"t":"Stuck: GitHub still shows a conflict","p":"No change after 15 minutes of checks every 30 seconds. My test merge shows no conflict."},
+ "q2":{"t":"Checks ran?","p":"A merge needs every check to pass on the current commit."},
+ "w2":{"t":"Stuck: no checks on the new commit","p":"The only check runs are from October 3. Main and the branch have no workflow files."},
+ "end":{"t":"Merge: next","p":"I hold the merge until both stuck items clear."}
+}
+</script>
+<script>
+const D=JSON.parse(document.getElementById('detail-data').textContent);
+const det=document.getElementById('det');
+const nodes=[...document.querySelectorAll('.n')];
+function show(g){const d=D[g.dataset.k];if(!d)return;nodes.forEach(n=>n.classList.toggle('on',n===g));det.innerHTML='';const b=document.createElement('b');b.textContent=d.t;const p=document.createElement('p');p.textContent=d.p;det.append(b,p)}
+nodes.forEach(g=>{g.setAttribute('role','button');g.addEventListener('click',()=>show(g));g.addEventListener('keydown',e=>{if(e.key==='Enter'||e.key===' '){e.preventDefault();show(g)}})});
+const first=nodes.find(n=>n.classList.contains('wait'))||nodes[0];if(first)show(first);
+</script>

package/docs/templates/html-plan/README.md

@@ -1,6 +1,6 @@
 # html-plan page template
 
-Build a complex visual, such as a multi-part plan or evidence, from the html-plan skill. Load `house.css` from this folder after the plugin's `htmlplan.css`. The older [artifact page template](../artifact-page/README.md) stays available; use it when the request names it.
+Build a complex visual, such as a multi-part plan or evidence, from the html-plan skill. A status or progress report prefers the [status flowchart](../artifact-page/status-flowchart.html), unless the person asks for another shape. Load `house.css` from this folder after the plugin's `htmlplan.css`. The older [artifact page template](../artifact-page/README.md) stays available; use it when the request names it.
 
 ## Get the skill
 

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/features/session-context.md

@@ -9,7 +9,7 @@ This family injects reminders and task guidance when an agent starts, resumes, s
 - `session/working_style_prompt.py` injects the session's working style at session start.
 - `session/advisor_rules_prompt.py` injects advisor guidance when the built-in advisor is enabled.
 - `session/orchestrator_auto_starter.py` injects an orchestrator directive when its environment flag is enabled.
-- `session/artifact_template_pointer.py` routes an agent that starts an artifact page by scope. One flow or one comparison is an inline SVG flowchart with minimal text. A multi-part plan or evidence is an html-plan page from `docs/templates/html-plan/README.md`. When the request names the older artifact page template, it points at `docs/templates/artifact-page/README.md`, which names the tracker template and the diagram template and which ask each fits.
+- `session/artifact_template_pointer.py` routes an agent that starts an artifact page by scope. A status or progress report prefers the status flowchart from `docs/templates/artifact-page/status-flowchart.html`, unless the person asks for another shape. One flow or one comparison is an inline SVG flowchart with minimal text. A multi-part plan or evidence is an html-plan page from `docs/templates/html-plan/README.md`. When the request names the older artifact page template, it points at `docs/templates/artifact-page/README.md`, which names the tracker template and the diagram template and which ask each fits.
 - `advisory/auto_mode_denial_quick_fix.py` proposes one `autoMode.allow` entry and a PowerShell block that writes it after an auto mode denial. It never retries the denied call.
 
 ## When it fires
@@ -30,7 +30,7 @@ Preconditions:
 - **Working style.** Input is a SessionStart event. Run `python -m pytest packages/claude-dev-env/hooks/session/test_working_style_prompt.py -q`. The adjacent test observes the fixed context text.
 - **Advisor guidance.** Input is SessionStart with `advisorModel` set. Run `python -m pytest packages/claude-dev-env/hooks/session/test_advisor_rules_prompt.py -q`. The adjacent test observes guidance only when the advisor setting is enabled.
 - **Orchestrator start.** Input is SessionStart with its opt-in flag set. Run `python -m pytest packages/claude-dev-env/hooks/session/test_orchestrator_auto_starter.py -q`. The adjacent test observes an orchestrator directive.
-- **Artifact template pointer.** Input is an `Artifact` quickstart call. Run `python -m pytest packages/claude-dev-env/hooks/session/test_artifact_template_pointer.py -q`. The adjacent test observes the html-plan path ahead of the template path in `additionalContext`, and silence on a publish call or another skill.
+- **Artifact template pointer.** Input is an `Artifact` quickstart call. Run `python -m pytest packages/claude-dev-env/hooks/session/test_artifact_template_pointer.py -q`. The adjacent test observes the status flowchart path first, the html-plan path ahead of the template path in `additionalContext`, and silence on a publish call or another skill.
 - **Denial quick fix.** Input is a `PermissionDenied` event with a bracketed rule label and a classifier verdict. Run `python -m pytest packages/claude-dev-env/hooks/advisory/test_auto_mode_denial_quick_fix.py -q`. The adjacent test observes the named rule, the allow entry, and the PowerShell block; a denial with no verdict gets a note and no block.
 
 ## Gotchas

package/hooks/hooks_constants/artifact_template_pointer_constants.py

@@ -10,10 +10,10 @@ __all__ = [
     "ARTIFACT_TEMPLATE_PATH",
     "ARTIFACT_TOOL_NAME",
     "HTML_PLAN_TEMPLATE_README_PATH",
-    "POINTER_ALTERNATIVE_PREFIX",
-    "POINTER_TEXT_PREFIX",
+    "POINTER_TEXT_TEMPLATE",
     "SKILL_NAME_INPUT_KEY",
     "SKILL_TOOL_NAME",
+    "STATUS_FLOWCHART_TEMPLATE_PATH",
     "ALL_ARTIFACT_DESIGN_SKILL_NAMES",
 ]
 
@@ -26,12 +26,17 @@ ALL_ARTIFACT_DESIGN_SKILL_NAMES = frozenset({"artifact-design"})
 TEMPLATES_DIRECTORY = Path(__file__).resolve().parents[2] / "docs" / "templates"
 ARTIFACT_TEMPLATE_PATH = TEMPLATES_DIRECTORY / "artifact-page" / "README.md"
 HTML_PLAN_TEMPLATE_README_PATH = TEMPLATES_DIRECTORY / "html-plan" / "README.md"
-POINTER_TEXT_PREFIX = (
-    "Pick the visual by scope. For one flow or one comparison, draw an inline SVG"
-    " flowchart artifact with minimal text, using the artifact-diagramming skill."
-    " For a multi-part plan or evidence, build an html-plan page following "
-)
-POINTER_ALTERNATIVE_PREFIX = (
-    ". When the request names the older artifact page template,"
-    " pick the one that fits the ask from "
+STATUS_FLOWCHART_TEMPLATE_PATH = TEMPLATES_DIRECTORY / "artifact-page" / "status-flowchart.html"
+POINTER_TEXT_TEMPLATE = (
+    "For a status or progress report on one piece of work, prefer the status"
+    " flowchart: done steps, yes-or-no checks, stuck steps with recheck loops, and"
+    " the next step, each opening its detail on click. Build it from"
+    " {path_of_status_flowchart} for every such report, multi-part ones included,"
+    " unless the person asks for another shape. For any other visual, pick by"
+    " scope. For one flow or one comparison, draw an inline SVG flowchart artifact"
+    " with minimal text, using the artifact-diagramming skill. For a multi-part"
+    " plan or evidence that is not a status report, build an html-plan page"
+    " following {path_of_plan_readme}. When"
+    " the request names the older artifact page template, pick the one that fits"
+    " the ask from {path_of_page_readme}."
 )

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_artifact_template_pointer_constants.py

@@ -1,5 +1,8 @@
 """Behavioral tests for the artifact template pointer's path."""
 
+import json
+import re
+
 from hooks_constants import artifact_template_pointer_constants
 
 
@@ -13,6 +16,29 @@ def test_html_plan_readme_path_names_the_packaged_readme_and_house_stylesheet()
     assert artifact_template_pointer_constants.HTML_PLAN_TEMPLATE_README_PATH.parent.joinpath("house.css").is_file()
 
 
+def test_status_flowchart_path_names_the_packaged_template_file() -> None:
+    template_text = artifact_template_pointer_constants.STATUS_FLOWCHART_TEMPLATE_PATH.read_text(
+        encoding="utf-8"
+    )
+    assert "<svg" in template_text
+    assert "detail-data" in template_text
+
+
+def test_status_flowchart_gives_every_shape_a_detail_entry() -> None:
+    template_text = artifact_template_pointer_constants.STATUS_FLOWCHART_TEMPLATE_PATH.read_text(
+        encoding="ascii"
+    )
+    all_shape_keys = set(re.findall(r'data-k="([^"]+)"', template_text))
+    detail_block = re.search(
+        r'<script type="application/json" id="detail-data">(.*?)</script>', template_text, re.DOTALL
+    )
+    assert detail_block is not None
+    all_detail_keys = set(json.loads(detail_block.group(1)))
+
+    assert all_shape_keys
+    assert all_shape_keys == all_detail_keys
+
+
 def test_every_exported_name_resolves_to_a_module_attribute() -> None:
     all_missing_names = [
         each_name

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/session/artifact_template_pointer.py

@@ -1,8 +1,11 @@
 #!/usr/bin/env python3
 """PreToolUse hook: route an agent about to build an artifact page by scope.
 
-Registered on ``Artifact|Skill``. It adds one line of ``additionalContext``
-when a session starts a new artifact page. One flow or one comparison is an
+Registered on ``Artifact|Skill``. It adds one paragraph of ``additionalContext``
+when a session starts a new artifact page. A status or progress report
+prefers the status flowchart from
+``docs/templates/artifact-page/status-flowchart.html``, unless the person asks
+for another shape. One flow or one comparison is an
 inline SVG flowchart with minimal text. A multi-part plan or evidence is an
 html-plan page from ``docs/templates/html-plan/README.md``, and
 ``docs/templates/artifact-page/README.md`` stays the alternative:
@@ -34,10 +37,10 @@ from hooks_constants.artifact_template_pointer_constants import (
     ARTIFACT_TEMPLATE_PATH,
     ARTIFACT_TOOL_NAME,
     HTML_PLAN_TEMPLATE_README_PATH,
-    POINTER_ALTERNATIVE_PREFIX,
-    POINTER_TEXT_PREFIX,
+    POINTER_TEXT_TEMPLATE,
     SKILL_NAME_INPUT_KEY,
     SKILL_TOOL_NAME,
+    STATUS_FLOWCHART_TEMPLATE_PATH,
 )
 from hooks_constants.hook_specific_output_keys import (
     HOOK_EVENT_NAME_KEY,
@@ -81,9 +84,10 @@ def decide_hook_output(all_hook_fields: dict[str, object]) -> dict[str, object]
     return {
         HOOK_SPECIFIC_OUTPUT_KEY: {
             HOOK_EVENT_NAME_KEY: PRE_TOOL_USE_EVENT_NAME,
-            ADDITIONAL_CONTEXT_KEY: (
-                f"{POINTER_TEXT_PREFIX}{HTML_PLAN_TEMPLATE_README_PATH}"
-                f"{POINTER_ALTERNATIVE_PREFIX}{ARTIFACT_TEMPLATE_PATH}."
+            ADDITIONAL_CONTEXT_KEY: POINTER_TEXT_TEMPLATE.format(
+                path_of_status_flowchart=STATUS_FLOWCHART_TEMPLATE_PATH,
+                path_of_plan_readme=HTML_PLAN_TEMPLATE_README_PATH,
+                path_of_page_readme=ARTIFACT_TEMPLATE_PATH,
             ),
         }
     }

package/hooks/session/test_artifact_template_pointer.py

@@ -13,6 +13,7 @@ import artifact_template_pointer
 from hooks_constants.artifact_template_pointer_constants import (
     ARTIFACT_TEMPLATE_PATH,
     HTML_PLAN_TEMPLATE_README_PATH,
+    STATUS_FLOWCHART_TEMPLATE_PATH,
 )
 
 HOOK_SCRIPT = Path(__file__).resolve().parent / "artifact_template_pointer.py"
@@ -50,13 +51,29 @@ def test_pointer_routes_a_simple_visual_to_a_flowchart_ahead_of_html_plan() -> N
     )
     assert hook_output is not None
     pointer_text = hook_output["hookSpecificOutput"]["additionalContext"]
-    assert pointer_text.index("one flow or one comparison") < pointer_text.index("flowchart")
-    assert pointer_text.index("flowchart") < pointer_text.index("multi-part plan or evidence")
+    simple_visual_position = pointer_text.index("one flow or one comparison")
+    simple_flowchart_position = pointer_text.index("flowchart", simple_visual_position)
+    assert simple_flowchart_position < pointer_text.index("multi-part plan or evidence")
     assert pointer_text.index("multi-part plan or evidence") < pointer_text.index(
         str(HTML_PLAN_TEMPLATE_README_PATH)
     )
 
 
+def test_pointer_prefers_the_status_flowchart_for_a_status_visual_first() -> None:
+    hook_output = artifact_template_pointer.decide_hook_output(
+        _payload("Artifact", {"action": "quickstart", "intent": "other"})
+    )
+    assert hook_output is not None
+    pointer_text = hook_output["hookSpecificOutput"]["additionalContext"]
+    assert pointer_text.index("status or progress") < pointer_text.index(
+        str(STATUS_FLOWCHART_TEMPLATE_PATH)
+    )
+    assert pointer_text.index(str(STATUS_FLOWCHART_TEMPLATE_PATH)) < pointer_text.index(
+        "one flow or one comparison"
+    )
+    assert "another shape" in pointer_text
+
+
 def test_artifact_design_skill_gets_the_template_pointer() -> None:
     hook_output = artifact_template_pointer.decide_hook_output(
         _payload("Skill", {"skill": "artifact-design"})

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.75.5",
+    "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",
@@ -24,6 +24,16 @@
       "key": "wall_of_text",
       "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",
+      "reminder": "Show the status as the status flowchart from docs/templates/artifact-page/status-flowchart.html: done steps, yes-or-no checks, stuck steps with recheck loops, and the next step, each opening its detail on click, unless the person asked for another shape."
     }
   ],
   "allowed_capitalized_words": [