claude-dev-env 1.69.1 → 1.70.0

package/rules/claude-md-orphan-file.md

@@ -0,0 +1,24 @@
+# Orphan File Reference in a Per-Directory CLAUDE.md
+
+**When this applies:** Any Write, Edit, or MultiEdit to a file named `CLAUDE.md` that lists files in a markdown table whose first column names each file in backticks.
+
+## Rule
+
+Every bare filename a per-directory `CLAUDE.md` table names in its first column points at a file that exists in the directory subtree the `CLAUDE.md` describes. A first-column cell naming a file that exists nowhere in that subtree points a reader at something that is not there: the listing claims a file the directory does not hold.
+
+When you add a table row, the file it names already exists in this directory or a subdirectory of it. When you remove a file, drop the row that named it.
+
+## What the gate checks
+
+The `claude_md_orphan_file_blocker.py` hook runs on every Write, Edit, and MultiEdit whose target basename is `CLAUDE.md`. It:
+
+1. Reads the content the tool would leave on disk. For a Write that is the full `content`. For an Edit or MultiEdit it reconstructs the post-edit file — the existing on-disk file with the replacements applied — and also notes which orphans the file already held before the edit, so a pre-existing orphan on an untouched line is excluded and only an orphan the edit introduces is reported; when the existing file cannot be read, it scans the raw `new_string` fragment(s) instead.
+2. Skips any line inside a fenced code block (between a ``` or `~~~` fence pair), since an example table there is documentation, not a live listing.
+3. Takes the first column of each remaining markdown table row and keeps the cells that name a bare filename: wrapped in backticks, no path separator, not a slash-command, and ending in a known file extension (`.py`, `.md`, `.json`, `.mjs`, `.js`, `.ts`, `.ps1`, `.cmd`, `.ahk`, `.yml`, `.yaml`, `.sh`, `.txt`, `.cfg`, `.toml`, `.ini`).
+4. Blocks the write when a named file exists nowhere under the scan root — the `CLAUDE.md` directory's parent, which covers the directory, its subdirectories, and its siblings. A filesystem error that halts the whole subtree walk fails open (the write proceeds), so an unreadable tree never blocks a write.
+
+The check stays quiet for a target that is not a `CLAUDE.md`, for a table cell that holds a path, a subdirectory ending in `/`, or a slash-command, for a table row inside a fenced code block, and for a table whose content names an explicit relative-path source (a `../` token), since that table documents files that sit outside the subtree by design.
+
+## Why this is a hook, not a lint pass
+
+A table row that names an absent file reads as a contract: a reader trusts the listing to map the directory. A wrong row sends the reader looking for a file that is not there and erodes trust in every other row. Catching it as each row is written keeps the table and the directory in step.

package/skills/autoconverge/workflow/autoconverge_report_constants/render_report_constants.py

@@ -92,6 +92,16 @@ TIMELINE_TERMINAL_BAR_LABEL = "terminal"
 
 CAUSE_MUTED_STYLE = "color:#94a3b8;"
 
+ISSUE_ICON_BY_CATEGORY = {
+    "bug": "\U0001f41e",
+    "code-standard": "\U0001f4cf",
+}
+DEFAULT_ISSUE_ICON = "\U0001f41e"
+
+SCORECARD_LABEL_CAUGHT = "caught"
+SCORECARD_LABEL_ROUNDS = "rounds"
+SCORECARD_LABEL_REMAINING = "left"
+
 GITHUB_PR_URL_TEMPLATE = "https://github.com/{owner}/{repo}/pull/{number}"
 
 SUMMARY_PR_COORDINATES_TEMPLATE = "owner={owner} repo={repo} PR #{pr_number} ({url})"
@@ -128,12 +138,13 @@ Write so a non-programmer understands every line. The reader has never seen the
 - problemScenes/fixScenes example (a DIFFERENT project, to teach the style not the answer). Problem scene: trigger "export stops at batch 90", condition "you restart it", result "starts again at batch 1", caption "A halted export threw away the 90 batches it had already finished and began again." Mirroring fix scene: trigger "export stops at batch 90", condition "you restart it", result "continues at batch 91", caption "A restarted export now picks up at the next unfinished batch."
 - GROUP near-duplicate findings into issue CLASSES: the same KIND of problem across different files or lines becomes ONE class with a count. Example: seven "Missing return type annotation on test function" findings become one class with count 7.
 - TRANSLATE reviewer jargon into plain everyday English. Examples: "CodingGuidelineID 1000000 / Repository guideline (Types)" -> "a typing rule the project enforces"; "missing return type annotation / Add -> None" -> "a test did not declare what it returns"; "Banned identifier result" -> "a vague variable name the project bans"; a magic-value finding -> "a raw number or string that should be a named value".
-- plainName: a short plain symptom a non-programmer recognizes - name what BROKE or what a person would notice, not the internal component. Carry NO tool token, rule id, file path, line number, severity code (P0/P1/P2), or bot name. Good: "The install command quietly did nothing". Weak: "Entry-point guard misfires under symlinked bin invocation".
+- TRANSLATE internal-mechanism nouns the same way. "guard", "hook", "checker", "validator", "gate", "parser", "entry-point", "AST" each name a part of the machine a non-programmer never sees. Replace each with the everyday check it performs or, better, the effect it had: "the guard blocked the save" -> "saving the file was blocked"; "the hook fired" -> "the project's automatic check ran". Never leave a bare "guard", "hook", or "checker" in a sentence a reader sees.
+- plainName: a short plain symptom a non-programmer recognizes - name what BROKE or what a person would notice, not the internal component. Carry NO tool token, rule id, file path, line number, severity code (P0/P1/P2), bot name, or internal-mechanism noun (guard, hook, checker, validator, gate, parser, AST, annotation). Lead with the visible effect. Good: "The install command quietly did nothing"; "Saving a file was blocked by mistake". Weak: "Entry-point guard misfires under symlinked bin invocation"; "The guard wrongly flagged a field".
 - cause is the field that matters most. Sentence 1: the observable impact - what a person saw go wrong, or would have. Sentence 2: the cause in everyday terms. At most 2 sentences, no paragraphs.
 - In cause describe the CONSEQUENCE, never the internal mechanism. Do not narrate control flow, comparisons, or internal state. Banned phrasings: "a check returned false", "two forms of the path", "treated the run as a non-run", "the values did not match", "a guard misfired". Say what that meant for the person instead.
 - Prefer concrete everyday words: "the install command" and "on Mac and Linux" over "the launcher", "the entry-point guard", or "the symlink". Read each sentence as if aloud to a non-programmer; if they would not follow it, rewrite it.
 - cause worked example (a DIFFERENT problem, to show the style, not the answer). WEAK, do not write like this: "A cached value's timestamp was compared across mismatched time zones, so the freshness check evaluated false and the entry was treated as stale and re-fetched on every request." STRONG, write like this: "Every page re-downloaded the same data from scratch instead of reusing the copy it already had, so pages loaded slower than needed. The app misjudged its saved copy as out of date."
-- medium picks how the before/after panels are drawn: 'terminal' when the user-visible effect is command-line behavior; 'code' when the finding is best shown as a small before/after code snippet (e.g. a missing return type: before "def test_x():" / after "def test_x() -> None:"); 'text' otherwise.
+- medium picks how the before/after panels are drawn: 'terminal' when the user-visible effect is command-line behavior; 'code' when the finding is best shown as a small before/after code snippet (e.g. a missing return type: before "def test_x():" / after "def test_x() -> None:"); 'text' otherwise. PREFER 'terminal' or 'text' so the panels show what a PERSON sees; reserve 'code' for the rare finding whose fix truly is a one-line code change a reader would recognize. When in doubt, choose 'text' and describe the effect in plain words, not source code.
 - beforeLines and afterLines are the literal short lines to show in each panel - what a person sees. For a terminal: include the prompt + command + the (missing or present) output. For code: 1 to 4 lines before, 1 to 4 lines after. Keep every line short. Never fabricate exact output text that is not implied by the finding - if the exact text is unknown, show the shape (e.g. "(no output - nothing installed)"). Leave both arrays empty to fall back to the cause line alone.
 - Lead with category 'bug' classes, then 'code-standard'. Create one class per distinct KIND of problem, however many that is; never merge different kinds or drop classes to hit a number.
 - status is 'fixed' unless the fix summaries or the deferred code-standard note mark the class deferred, in which case status is 'deferred'.
@@ -148,6 +159,7 @@ HTML_DOCTYPE = "<!DOCTYPE html>"
 HTML_HEAD_TEMPLATE = """\
 <head>
 <meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
 <title>PR #{pr_number} Convergence Summary</title>
 <link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700;800&family=JetBrains+Mono:wght@400;500&display=swap" rel="stylesheet">
 {style_block}
@@ -156,9 +168,10 @@ HTML_HEAD_TEMPLATE = """\
 HTML_STYLE_BLOCK = """\
 <style>
   * { box-sizing: border-box; margin: 0; padding: 0; }
+  html { -webkit-text-size-adjust: 100%; text-size-adjust: 100%; }
   body { font-family: 'Inter', -apple-system, BlinkMacSystemFont, sans-serif; background: #f1f5f9; color: #334155; line-height: 1.6; padding: 48px 20px; }
   .container { max-width: 860px; margin: 0 auto; }
-  h1 { font-size: 30px; font-weight: 800; color: #0f172a; letter-spacing: -0.5px; }
+  h1 { font-size: clamp(22px, 6vw, 30px); font-weight: 800; color: #0f172a; letter-spacing: -0.5px; line-height: 1.2; }
   .subtitle { color: #64748b; font-size: 14px; margin: 6px 0 26px; }
   h2 { font-size: 13px; font-weight: 700; text-transform: uppercase; letter-spacing: 0.6px; color: #94a3b8; margin: 40px 0 16px; }
 
@@ -168,6 +181,14 @@ HTML_STYLE_BLOCK = """\
   .verdict .vtext { font-size: 16px; font-weight: 700; color:#0f172a; }
   .verdict .vsub { font-size: 13px; font-weight: 500; color:#15803d; }
 
+  /* scorecard */
+  .scorecard { display: grid; grid-template-columns: repeat(3, 1fr); gap: 12px; margin-top: 14px; }
+  .stat { background:#fff; border:1px solid #e2e8f0; border-radius:12px; padding:16px 14px; text-align:center; }
+  .stat-num { font-size: clamp(26px, 8vw, 34px); font-weight:800; color:#0f172a; line-height:1.1; }
+  .stat-label { font-size:12px; font-weight:600; text-transform:uppercase; letter-spacing:.5px; color:#94a3b8; margin-top:4px; }
+  .stat.good { border-color:#22c55e; background:linear-gradient(135deg,#f0fdf4,#dcfce7); }
+  .stat.good .stat-num { color:#16a34a; }
+
   /* problem / fix scenes */
   .pf-grid { display: grid; grid-template-columns: 1fr 1fr; gap: 16px; }
   .pf { border-radius: 12px; padding: 18px 20px; border:1px solid #e2e8f0; background:#fff; }
@@ -186,8 +207,10 @@ HTML_STYLE_BLOCK = """\
   .scene-cap:last-child { margin-bottom:0; }
 
   /* bug class */
-  .bug-head { display:flex; align-items:baseline; justify-content:space-between; gap:12px; margin:32px 0 12px; }
+  .bug-head { display:flex; align-items:center; justify-content:space-between; gap:12px; margin:32px 0 12px; }
   .bug-head:first-of-type { margin-top:8px; }
+  .bug-title { display:flex; align-items:center; gap:8px; min-width:0; }
+  .bug-icon { font-size:18px; line-height:1; flex:0 0 auto; }
   .bug-name { font-size:16px; font-weight:700; color:#0f172a; }
   .bug-count { font-size:12px; font-weight:600; color:#64748b; background:#f1f5f9; border:1px solid #e2e8f0; border-radius:20px; padding:3px 11px; white-space:nowrap; flex:0 0 auto; }
 
@@ -222,5 +245,13 @@ HTML_STYLE_BLOCK = """\
 
   footer { margin-top:40px; padding-top:16px; border-top:1px solid #e2e8f0; color:#94a3b8; font-size:12px; }
   footer code { background:#e2e8f0; padding:1px 6px; border-radius:4px; font-family:'JetBrains Mono',monospace; }
-  @media (max-width:680px){ .pf-grid,.term-grid{grid-template-columns:1fr;} }
+  @media (max-width:680px){
+    body{ padding:24px 14px; }
+    .pf-grid,.term-grid{ grid-template-columns:1fr; }
+    .scorecard{ gap:8px; }
+    .stat{ padding:12px 8px; }
+    .stat-label{ font-size:11px; }
+    .bug-head{ flex-wrap:wrap; gap:6px; }
+    h2{ margin:28px 0 12px; }
+  }
 </style>"""

package/skills/autoconverge/workflow/render_report.py

@@ -16,6 +16,7 @@ from autoconverge_report_constants.render_report_constants import (
     CAUSE_MUTED_STYLE,
     DEFAULT_FINDING_CATEGORY,
     DEFAULT_FINDING_SEVERITY,
+    DEFAULT_ISSUE_ICON,
     GITHUB_PR_URL_TEMPLATE,
     HTML_DOCTYPE,
     HTML_HEAD_TEMPLATE,
@@ -30,6 +31,7 @@ from autoconverge_report_constants.render_report_constants import (
     ISSUE_CLASS_FIELD_PLAINNAME,
     ISSUE_CLASS_FIELD_SEVERITY,
     ISSUE_CLASS_FIELD_STATUS,
+    ISSUE_ICON_BY_CATEGORY,
     JOURNAL_SIBLING_SUBAGENTS,
     JOURNAL_SIBLING_WORKFLOWS,
     LABEL_CONVERGENCE_SUMMARY,
@@ -43,6 +45,9 @@ from autoconverge_report_constants.render_report_constants import (
     SCENE_FIELD_CONDITION,
     SCENE_FIELD_RESULT,
     SCENE_FIELD_TRIGGER,
+    SCORECARD_LABEL_CAUGHT,
+    SCORECARD_LABEL_REMAINING,
+    SCORECARD_LABEL_ROUNDS,
     SEVERITY_SORT_RANK,
     SHORT_SHA_LENGTH,
     STATUS_LABEL_BY_VALUE,
@@ -456,6 +461,30 @@ def _render_verdict_banner(
     )
 
 
+def _render_scorecard(run_data: RunData, round_count: int) -> str:
+    """Return the at-a-glance scorecard: findings caught, rounds, and zero remaining.
+
+    Args:
+        run_data: Aggregated metrics from the journal.
+        round_count: Total number of convergence rounds.
+
+    Returns:
+        An HTML .scorecard grid of three .stat tiles; the remaining tile is marked
+        .good and reads zero, since the report renders only on a converged run.
+    """
+    remaining_count = 0
+    return (
+        '<div class="scorecard">'
+        f'<div class="stat"><div class="stat-num">{run_data.total_finding_count}</div>'
+        f'<div class="stat-label">{SCORECARD_LABEL_CAUGHT}</div></div>'
+        f'<div class="stat"><div class="stat-num">{round_count}</div>'
+        f'<div class="stat-label">{SCORECARD_LABEL_ROUNDS}</div></div>'
+        f'<div class="stat good"><div class="stat-num">{remaining_count}</div>'
+        f'<div class="stat-label">{SCORECARD_LABEL_REMAINING}</div></div>'
+        "</div>"
+    )
+
+
 def _render_scene_row(scene: dict, is_problem: bool) -> str:
     """Return one .scene row plus its caption for a problem-or-fix scene.
 
@@ -642,20 +671,26 @@ def _issue_class_sort_key(issue_class: dict) -> tuple[int, int]:
 
 
 def _render_issue_class_heading(issue_class: dict) -> str:
-    """Return the per-class heading with the plain bug name and an occurrence count.
+    """Return the per-class heading with a category icon, plain name, and count.
 
     Args:
         issue_class: One issue-class dict from the summary.
 
     Returns:
-        An HTML .bug-head block with the plain bug name and a finding-count chip.
+        An HTML .bug-head block: a category icon and the plain bug name grouped in
+        a .bug-title span, plus a finding-count chip.
     """
     plain_name = html.escape(str(issue_class.get(ISSUE_CLASS_FIELD_PLAINNAME, "")))
     count = _coerce_count(issue_class.get(ISSUE_CLASS_FIELD_COUNT, 0))
     count_phrase = html.escape(_pluralize(count, "finding", "findings"))
+    category = str(issue_class.get(ISSUE_CLASS_FIELD_CATEGORY, CATEGORY_BUG))
+    icon = ISSUE_ICON_BY_CATEGORY.get(category, DEFAULT_ISSUE_ICON)
     return (
         '<div class="bug-head">'
+        '<span class="bug-title">'
+        f'<span class="bug-icon">{icon}</span>'
         f'<span class="bug-name">{plain_name}</span>'
+        "</span>"
         f'<span class="bug-count">{count_phrase}</span>'
         "</div>"
     )
@@ -792,9 +827,10 @@ def _render_summary_body(
         final_sha_short: First eight characters of the final commit sha.
 
     Returns:
-        An HTML body fragment: verdict banner, problem/fix cards, then a single
-        caught section that opens with a run-stats lead line and holds the
-        issue-class before/after panels, followed by the collapsed appendix.
+        An HTML body fragment: verdict banner, an at-a-glance scorecard,
+        problem/fix cards, then a single caught section that opens with a
+        run-stats lead line and holds the issue-class before/after panels,
+        followed by the collapsed appendix.
     """
     convergence_summary = run_data.convergence_summary
     if convergence_summary is None:
@@ -803,12 +839,14 @@ def _render_summary_body(
     verdict_banner = _render_verdict_banner(
         convergence_summary, run_data, final_sha_short
     )
+    scorecard = _render_scorecard(run_data, round_count)
     pf_grid = _render_pf_grid(convergence_summary)
     caught_lead = _render_caught_lead(convergence_summary, run_data, round_count)
     issue_panels = _render_issue_class_panels(convergence_summary)
     appendix = _render_appendix(run_data.all_distinct_findings)
     return (
         f"{verdict_banner}"
+        f"{scorecard}"
         f"<h2>What this PR does</h2>{pf_grid}"
         f"<h2>What was caught &mdash; and how it looked</h2>{caught_lead}{issue_panels}"
         f"{appendix}"

package/skills/autoconverge/workflow/test_render_report.py

@@ -138,6 +138,49 @@ def test_cli_renders_verdict_banner_with_python_computed_vsub(tmp_path: Path) ->
     assert "final commit 7c2f420c" in html_content
 
 
+def test_cli_renders_scorecard_with_caught_rounds_and_zero_remaining(
+    tmp_path: Path,
+) -> None:
+    """Should render an at-a-glance scorecard: findings caught, rounds, and zero left."""
+    out_path = tmp_path / "report-scorecard.html"
+
+    completed = _render_cli(FIXTURE_JOURNAL, out_path)
+    assert completed.returncode == 0, f"CLI failed:\n{completed.stderr}"
+
+    html_content = out_path.read_text(encoding="utf-8")
+    assert 'class="scorecard"' in html_content
+    assert 'class="stat good"' in html_content
+    assert f'<div class="stat-num">{EXPECTED_TOTAL_FINDINGS}</div>' in html_content
+    assert f'<div class="stat-num">{EXPECTED_ROUND_COUNT}</div>' in html_content
+    assert '<div class="stat-num">0</div>' in html_content
+    assert ">caught</div>" in html_content
+    assert ">rounds</div>" in html_content
+    assert ">left</div>" in html_content
+
+
+def test_render_issue_class_heading_carries_a_category_icon() -> None:
+    """Should prefix the plain name with the icon matching the issue category."""
+    bug_heading = render_report._render_issue_class_heading(
+        {"plainName": "A plain symptom", "count": 2, "category": "bug"}
+    )
+    assert 'class="bug-title"' in bug_heading
+    assert 'class="bug-icon"' in bug_heading
+    assert render_report.ISSUE_ICON_BY_CATEGORY["bug"] in bug_heading
+
+    standard_heading = render_report._render_issue_class_heading(
+        {"plainName": "A standard symptom", "count": 1, "category": "code-standard"}
+    )
+    assert render_report.ISSUE_ICON_BY_CATEGORY["code-standard"] in standard_heading
+
+
+def test_render_issue_class_heading_uses_default_icon_for_unknown_category() -> None:
+    """Should fall back to the default icon when the category has no mapped icon."""
+    heading = render_report._render_issue_class_heading(
+        {"plainName": "An unmapped symptom", "count": 1, "category": "mystery"}
+    )
+    assert render_report.DEFAULT_ISSUE_ICON in heading
+
+
 def test_cli_renders_problem_and_fix_scene_cards(tmp_path: Path) -> None:
     """Should draw problem and fix scene cards with trigger, result, and caption."""
     out_path = tmp_path / "report-scenes.html"