claude-dev-env 8.75.5 → 8.76.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/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/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/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/package.json

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

package/rules/visual-reply-rules.json

@@ -24,6 +24,11 @@
       "key": "wall_of_text",
       "label": "Wall of text",
       "reminder": "Put each point, and each step the reader takes, on its own line."
+    },
+    {
+      "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": [