claude-dev-env 1.69.2 → 1.71.0

package/hooks/git-hooks/pre_push.py

@@ -1,20 +1,30 @@
 #!/usr/bin/env python3
-"""Git pre-push hook: run the CODE_RULES gate over commits about to be pushed.
+"""Git pre-push hook: guard the push destination, then run the CODE_RULES gate.
 
 Installed to the user's shared git-hooks directory via the claude-dev-env
 installer; git invokes this file as `pre-push` (the installer strips the
 `_` and `.py` suffix when copying into the live hooks path).
 
 Protocol: git pre-push provides remote name and URL as argv, then writes
-`<local-ref> <local-sha> <remote-ref> <remote-sha>` lines on stdin. The
-first non-zero remote-sha is used as the gate `--base`, so violations are
-scoped to commits that are not already on the remote. When every remote
-object name is zero (new branch) or stdin is empty, the gate falls back
-to the remote's default branch symbolic ref.
+`<local-ref> <local-sha> <remote-ref> <remote-sha>` lines on stdin.
+
+Destination guard: any line that pushes a local branch onto a protected
+remote branch (`main` or `master`) whose name differs from the local
+branch is blocked before the gate runs. This catches a branch that tracks
+`origin/main` under `push.default=upstream`, where a bare `git push`
+resolves to `main`. The guard runs whether or not the CODE_RULES gate is
+installed; deletions and same-name pushes pass.
+
+Gate base: the first non-zero remote-sha is used as the gate `--base`, so
+violations are scoped to commits that are not already on the remote. When
+every remote object name is zero (new branch) or stdin is empty, the gate
+falls back to the remote's default branch symbolic ref.
 
 Exit codes:
-  0 - commits to be pushed pass the gate (or the gate is not installed).
-  1 - one or more commits introduce blocking violations.
+  0 - the push destination is allowed and its commits pass the gate (or
+      the gate is not installed).
+  1 - the push would land a non-protected local branch onto a protected
+      remote branch, or a commit introduces a blocking violation.
   2 - unexpected invocation failure (e.g., subprocess could not launch).
 """
 
@@ -25,16 +35,22 @@ import sys
 from pathlib import Path
 
 from git_hooks_constants import (
+    ALL_PROTECTED_BRANCH_PUSH_NAMES,
     ALL_ZEROS_OBJECT_NAME_CHARACTER,
     BASE_REFERENCE_ARGUMENT,
     DEFAULT_REMOTE_BASE_REFERENCE,
     GATE_INFRASTRUCTURE_FAILURE_EXIT_CODE,
     INVOKE_GATE_FAILURE_MESSAGE,
+    LOCAL_BRANCH_REFERENCE_PREFIX,
+    LOCAL_REFERENCE_FIELD_INDEX,
     LOCAL_SHA_FIELD_INDEX,
     MALFORMED_STDIN_LINE_MESSAGE,
     NO_PARSEABLE_STDIN_LINES_MESSAGE,
     NO_PARSEABLE_STDIN_LINES_SENTINEL,
     PRE_PUSH_GATE_SCRIPT_NOT_FOUND_MESSAGE,
+    PROTECTED_BRANCH_PUSH_BLOCK_EXIT_CODE,
+    PROTECTED_BRANCH_PUSH_BLOCK_MESSAGE,
+    REMOTE_REFERENCE_FIELD_INDEX,
     STDIN_LINE_FIELD_COUNT,
     STDIN_READ_FAILURE_MESSAGE,
     STDIN_REMOTE_OBJECT_FIELD_INDEX,
@@ -88,6 +104,36 @@ def resolve_base_reference_from_stdin(stdin_text: str) -> str | None:
     return default_remote_base_reference
 
 
+def find_protected_branch_push_violation(stdin_text: str) -> tuple[str, str] | None:
+    stdin_line_field_count = STDIN_LINE_FIELD_COUNT
+    local_reference_field_index = LOCAL_REFERENCE_FIELD_INDEX
+    local_sha_field_index = LOCAL_SHA_FIELD_INDEX
+    remote_reference_field_index = REMOTE_REFERENCE_FIELD_INDEX
+    local_branch_reference_prefix = LOCAL_BRANCH_REFERENCE_PREFIX
+    protected_branch_push_names = ALL_PROTECTED_BRANCH_PUSH_NAMES
+    for each_line in stdin_text.splitlines():
+        stripped_line = each_line.strip()
+        if not stripped_line:
+            continue
+        fields = stripped_line.split()
+        if len(fields) < stdin_line_field_count:
+            continue
+        if is_all_zeros_object_name(fields[local_sha_field_index]):
+            continue
+        local_branch_name = fields[local_reference_field_index].removeprefix(
+            local_branch_reference_prefix
+        )
+        remote_branch_name = fields[remote_reference_field_index].removeprefix(
+            local_branch_reference_prefix
+        )
+        if (
+            remote_branch_name in protected_branch_push_names
+            and local_branch_name != remote_branch_name
+        ):
+            return (local_branch_name, remote_branch_name)
+    return None
+
+
 def invoke_gate(gate_script_path: Path, base_reference: str) -> int:
     base_reference_argument = BASE_REFERENCE_ARGUMENT
     invoke_gate_failure_message = INVOKE_GATE_FAILURE_MESSAGE
@@ -118,13 +164,8 @@ def main() -> int:
     pre_push_gate_script_not_found_message = PRE_PUSH_GATE_SCRIPT_NOT_FOUND_MESSAGE
     no_parseable_stdin_lines_message = NO_PARSEABLE_STDIN_LINES_MESSAGE
     no_parseable_stdin_lines_sentinel = NO_PARSEABLE_STDIN_LINES_SENTINEL
-    gate_script_path, exact_allowed_path = resolve_gate_script_path()
-    if not is_safe_regular_file(gate_script_path, exact_allowed_path):
-        print(
-            pre_push_gate_script_not_found_message.format(path=gate_script_path),
-            file=sys.stderr,
-        )
-        return 0
+    protected_branch_push_block_message = PROTECTED_BRANCH_PUSH_BLOCK_MESSAGE
+    protected_branch_push_block_exit_code = PROTECTED_BRANCH_PUSH_BLOCK_EXIT_CODE
     try:
         stdin_text = sys.stdin.read()
     except OSError as read_error:
@@ -133,6 +174,24 @@ def main() -> int:
             file=sys.stderr,
         )
         return gate_infrastructure_failure_exit_code
+    protected_branch_push_violation = find_protected_branch_push_violation(stdin_text)
+    if protected_branch_push_violation is not None:
+        local_branch_name, remote_branch_name = protected_branch_push_violation
+        print(
+            protected_branch_push_block_message.format(
+                local_branch=local_branch_name,
+                remote_branch=remote_branch_name,
+            ),
+            file=sys.stderr,
+        )
+        return protected_branch_push_block_exit_code
+    gate_script_path, exact_allowed_path = resolve_gate_script_path()
+    if not is_safe_regular_file(gate_script_path, exact_allowed_path):
+        print(
+            pre_push_gate_script_not_found_message.format(path=gate_script_path),
+            file=sys.stderr,
+        )
+        return 0
     base_reference = resolve_base_reference_from_stdin(stdin_text)
     if base_reference is None:
         return 0

package/hooks/git-hooks/test_pre_push.py

@@ -321,3 +321,121 @@ def test_invoke_gate_uses_resolved_path(
     assert exit_code == 0
     executed_path = recorded_path_file.read_text(encoding="utf-8")
     assert executed_path == str(resolved_path)
+
+
+def test_find_protected_branch_push_violation_flags_feature_branch_to_main() -> None:
+    stdin_text = (
+        f"refs/heads/feat/example {NON_ZERO_LOCAL_SHA} refs/heads/main {NON_ZERO_REMOTE_SHA_ONE}\n"
+    )
+
+    violation = pre_push.find_protected_branch_push_violation(stdin_text)
+
+    assert violation == ("feat/example", "main")
+
+
+def test_find_protected_branch_push_violation_flags_feature_branch_to_master() -> None:
+    stdin_text = (
+        f"refs/heads/topic {NON_ZERO_LOCAL_SHA} refs/heads/master {NON_ZERO_REMOTE_SHA_ONE}\n"
+    )
+
+    violation = pre_push.find_protected_branch_push_violation(stdin_text)
+
+    assert violation == ("topic", "master")
+
+
+def test_find_protected_branch_push_violation_allows_main_onto_main() -> None:
+    stdin_text = (
+        f"refs/heads/main {NON_ZERO_LOCAL_SHA} refs/heads/main {NON_ZERO_REMOTE_SHA_ONE}\n"
+    )
+
+    violation = pre_push.find_protected_branch_push_violation(stdin_text)
+
+    assert violation is None
+
+
+def test_find_protected_branch_push_violation_allows_feature_onto_own_ref() -> None:
+    stdin_text = (
+        f"refs/heads/feat/example {NON_ZERO_LOCAL_SHA} refs/heads/feat/example {NON_ZERO_REMOTE_SHA_ONE}\n"
+    )
+
+    violation = pre_push.find_protected_branch_push_violation(stdin_text)
+
+    assert violation is None
+
+
+def test_find_protected_branch_push_violation_ignores_deletion_of_main() -> None:
+    stdin_text = (
+        f"(delete) {ALL_ZEROS_OBJECT_NAME} refs/heads/main {NON_ZERO_REMOTE_SHA_ONE}\n"
+    )
+
+    violation = pre_push.find_protected_branch_push_violation(stdin_text)
+
+    assert violation is None
+
+
+def test_main_blocks_feature_branch_push_onto_main(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    passing_gate_path = tmp_path / "gate.py"
+    passing_gate_path.write_text("import sys\nsys.exit(0)\n", encoding="utf-8")
+    monkeypatch.setenv("CODE_RULES_GATE_PATH", str(passing_gate_path))
+    monkeypatch.setattr(
+        sys,
+        "stdin",
+        io.StringIO(
+            f"refs/heads/feat/example {NON_ZERO_LOCAL_SHA} refs/heads/main {NON_ZERO_REMOTE_SHA_ONE}\n"
+        ),
+    )
+
+    exit_code = pre_push.main()
+
+    assert exit_code == git_hooks_constants.PROTECTED_BRANCH_PUSH_BLOCK_EXIT_CODE
+    captured = capsys.readouterr()
+    assert "feat/example" in captured.err
+    assert "main" in captured.err
+
+
+def test_main_blocks_protected_push_even_when_gate_script_missing(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    monkeypatch.setenv(
+        "CODE_RULES_GATE_PATH",
+        str(tmp_path / "does_not_exist.py"),
+    )
+    monkeypatch.setattr(
+        sys,
+        "stdin",
+        io.StringIO(
+            f"refs/heads/feat/example {NON_ZERO_LOCAL_SHA} refs/heads/main {NON_ZERO_REMOTE_SHA_ONE}\n"
+        ),
+    )
+
+    exit_code = pre_push.main()
+
+    assert exit_code == git_hooks_constants.PROTECTED_BRANCH_PUSH_BLOCK_EXIT_CODE
+    captured = capsys.readouterr()
+    assert "feat/example" in captured.err
+
+
+def test_main_allows_main_onto_main_push(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    passing_gate_path = tmp_path / "gate.py"
+    passing_gate_path.write_text("import sys\nsys.exit(0)\n", encoding="utf-8")
+    monkeypatch.setenv("CODE_RULES_GATE_PATH", str(passing_gate_path))
+    monkeypatch.setattr(
+        sys,
+        "stdin",
+        io.StringIO(
+            f"refs/heads/main {NON_ZERO_LOCAL_SHA} refs/heads/main {NON_ZERO_REMOTE_SHA_ONE}\n"
+        ),
+    )
+
+    exit_code = pre_push.main()
+
+    assert exit_code == 0

package/hooks/hooks.json

@@ -70,6 +70,11 @@
             "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/workflow_substitution_slot_blocker.py",
             "timeout": 10
           },
+          {
+            "type": "command",
+            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/claude_md_orphan_file_blocker.py",
+            "timeout": 10
+          },
           {
             "type": "command",
             "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/open_questions_in_plans_blocker.py",

package/hooks/hooks_constants/CLAUDE.md

@@ -11,6 +11,7 @@ Shared constant modules imported by hooks throughout the `hooks/` tree. Each fil
 | `banned_identifiers_constants.py` | The set of banned short identifiers and banned function-name prefixes |
 | `blocking_check_limits.py` | Max issue counts and preview lengths for blocking hooks |
 | `bot_mention_comment_blocker_constants.py` | Patterns for detecting bot @-mentions in PR comments |
+| `claude_md_orphan_file_blocker_constants.py` | Table patterns, file extensions, scan budget, and block-message text for the CLAUDE.md orphan-file blocker |
 | `code_rules_enforcer_constants.py` | File-extension sets, test-path patterns, advisory line thresholds, boolean-name prefixes |
 | `code_rules_path_utils_constants.py` | Path-matching helpers used by the code-rules check modules |
 | `convergence_branch_constants.py` | Branch and worktree naming patterns for the convergence gate |

package/hooks/hooks_constants/claude_md_orphan_file_blocker_constants.py

@@ -0,0 +1,107 @@
+"""Constants for the per-directory CLAUDE.md orphan-file-reference blocker.
+
+A per-directory ``CLAUDE.md`` documents the files reachable from its own
+directory in a markdown table whose first column names each file in backticks.
+When a first-column cell names a bare filename that exists nowhere under the scan
+root (the CLAUDE.md directory's parent, covering the directory, its
+subdirectories, and its siblings), the table points a reader at a file that is
+not there. This module holds the patterns that find those cells, the filename
+extensions that mark a cell as a file reference, the region-boundary marker that
+scopes a prose region to one section, the relative-path marker that exempts a
+cross-directory table block, the directory names the subtree walk prunes, the
+subtree scan budget, and the block-message text the hook emits.
+"""
+
+import re
+
+__all__ = [
+    "CLAUDE_MD_FILENAME",
+    "TABLE_ROW_PATTERN",
+    "CODE_FENCE_PATTERN",
+    "FIRST_COLUMN_BACKTICK_PATTERN",
+    "SEPARATOR_CELL_PATTERN",
+    "REGION_BOUNDARY_PATTERN",
+    "RELATIVE_PATH_SOURCE_PATTERN",
+    "ALL_REFERENCED_FILE_EXTENSIONS",
+    "ALL_NOISE_DIRECTORY_NAMES",
+    "MAX_SUBTREE_FILES_SCANNED",
+    "MAX_ORPHAN_FILE_ISSUES",
+    "ORPHAN_FILE_MESSAGE_TEMPLATE",
+    "ORPHAN_FILE_SYSTEM_MESSAGE",
+    "ORPHAN_FILE_ADDITIONAL_CONTEXT",
+]
+
+CLAUDE_MD_FILENAME: str = "CLAUDE.md"
+
+TABLE_ROW_PATTERN: re.Pattern[str] = re.compile(r"^\s*\|")
+
+CODE_FENCE_PATTERN: re.Pattern[str] = re.compile(r"^\s*(?:```|~~~)")
+
+FIRST_COLUMN_BACKTICK_PATTERN: re.Pattern[str] = re.compile(r"`([^`]+)`")
+
+SEPARATOR_CELL_PATTERN: re.Pattern[str] = re.compile(r"^[\s:\-]+$")
+
+REGION_BOUNDARY_PATTERN: re.Pattern[str] = re.compile(r"^\s*#")
+
+RELATIVE_PATH_SOURCE_PATTERN: re.Pattern[str] = re.compile(r"\.\.[\\/]")
+
+ALL_REFERENCED_FILE_EXTENSIONS: frozenset[str] = frozenset(
+    {
+        ".py",
+        ".md",
+        ".json",
+        ".mjs",
+        ".js",
+        ".ts",
+        ".ps1",
+        ".cmd",
+        ".ahk",
+        ".yml",
+        ".yaml",
+        ".sh",
+        ".txt",
+        ".cfg",
+        ".toml",
+        ".ini",
+    }
+)
+
+ALL_NOISE_DIRECTORY_NAMES: frozenset[str] = frozenset(
+    {
+        ".git",
+        "__pycache__",
+        "node_modules",
+        ".pytest_cache",
+        ".ruff_cache",
+    }
+)
+
+MAX_SUBTREE_FILES_SCANNED: int = 5000
+
+MAX_ORPHAN_FILE_ISSUES: int = 20
+
+ORPHAN_FILE_MESSAGE_TEMPLATE: str = (
+    "CLAUDE.md table references files that exist nowhere under {directory}: "
+    "{missing}. A per-directory CLAUDE.md table names files in its own directory "
+    "subtree; a first-column cell naming a file absent from that subtree points a "
+    "reader at something that is not there. Drop the row, or correct the cell to "
+    "name a file that exists in this directory, a subdirectory of it, or a sibling "
+    "directory under its parent."
+)
+
+ORPHAN_FILE_SYSTEM_MESSAGE: str = (
+    "CLAUDE.md table names a file that does not exist in its directory subtree - "
+    "drop the row or name an existing file"
+)
+
+ORPHAN_FILE_ADDITIONAL_CONTEXT: str = (
+    "Each first-column table cell wrapped in backticks that ends in a known file "
+    "extension must name a file present under the scan root: this CLAUDE.md's own "
+    "directory, a subdirectory of it, or a sibling directory under its parent. "
+    "Cells holding a path with a slash, a subdirectory ending in '/', or a "
+    "slash-command are out of scope. A table whose own block names an explicit "
+    "relative-path source (a '../' token) documents files outside the subtree and "
+    "is out of scope. For each missing file:\n"
+    "  - delete the table row, or\n"
+    "  - rename the cell to an existing file under the scan root."
+)

package/package.json

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

package/rules/CLAUDE.md

@@ -9,6 +9,7 @@ Rule files installed into `~/.claude/rules/` by `bin/install.mjs`. Claude Code l
 | `agent-spawn-protocol.md` | Protocol for spawning subagents: context sufficiency check, prompt generation via `/prompt-generator`, then spawn |
 | `ask-user-question-required.md` | Every user-directed question goes through the `AskUserQuestion` tool — no plain-text questions |
 | `bdd.md` | BDD discovery-driven development workflow and Example Mapping reference |
+| `claude-md-orphan-file.md` | Every backticked bare filename in a per-directory `CLAUDE.md` table's first column names a file in that directory's subtree |
 | `cleanup-temp-files.md` | Remove temporary files created during a task when the task is complete |
 | `code-reviews.md` | Mandatory protocol for responding to GitHub PR review feedback |
 | `code-standards.md` | Pointer to `CODE_RULES.md` as the single source of truth |

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/rules/docstring-prose-matches-implementation.md

@@ -1,6 +1,6 @@
 # Docstring Prose Matches Implementation
 
-**When this applies:** Any Write or Edit to a public function, method, class, or module whose docstring prose makes an enumerable claim about behavior — a list of inputs the code handles, the conditions it treats as a match, the cases it skips, or the order of its steps.
+**When this applies:** Any Write or Edit to a public function, method, class, or module whose docstring prose makes an enumerable claim about behavior — a list of inputs the code handles, the conditions it treats as a match, the cases it skips, or the order of its steps. It applies equally to a skill's companion `SKILL.md` (or any sibling `.md`) that describes a producer the skill's `scripts/` carry out: a doc sentence that claims a produced artifact's ordering or content is the prose this rule governs, and it tracks the producer function's own docstring and body.
 
 ## Rule
 
@@ -17,6 +17,7 @@ Read the body and the docstring side by side:
 - **Shared fallback routes.** A summary that scopes a fallback call to one condition names every condition that reaches that call. When the body routes to the same fallback from two or more early-return guards (`if a is None: fallback(); return` and `if random() < p: fallback(); return`), the prose enumerates both guards. The `check_docstring_fallback_branch_coverage` gate blocks the single-condition form of this drift at Write/Edit time.
 - **Step order.** A docstring that says `A then B then C` matches the call order in the body.
 - **Predicate breadth.** A boolean helper whose prose promises a narrow check accepts only the inputs the prose names — no broader input class the name and prose do not mention.
+- **Companion-doc ordering and content claims.** A `SKILL.md` (or sibling `.md`) sentence that names a produced artifact and claims its order (`sorted`, `alphabetical`, `in sorted order`) or its content (`the at-risk names`, `just the current set`) matches the producer function's docstring and body for that same artifact. A producer that builds the artifact by merging stored names with new names and appending — preserving file order, not re-sorting the union — leaves a doc that still says `sorted` drifted on both counts: the order claim is wrong, and the content claim hides the merged-in prior entries. When the producer's ordering or union changes, the same change updates the companion doc. The two move together in one commit, even when the producer edit does not touch the `.md` file.
 
 When the body changes the set of behaviors it applies, the same edit updates the prose enumeration. The two move together in one commit.
 
@@ -39,6 +40,8 @@ A docstring that enumerates "attribute read, augmented-assignment target, class-
 
 This drift class is sub-bucket **O6** in `packages/claude-dev-env/audit-rubrics/category_rubrics/category-o-docstring-vs-impl-drift.md` (free-form `Note:` / `Returns:` / responsibility-list claims). The audit teammate lists every prose enumeration in a changed docstring and verifies each item against the body, and lists every union member / suppressor / step in the body and verifies each appears in the prose. A union member or suppressor in the body that the prose omits is an O6 finding. The single-condition shared-fallback shape of this drift is gated deterministically by `check_docstring_fallback_branch_coverage` (`packages/claude-dev-env/hooks/blocking/code_rules_docstrings.py`); the audit lane covers every O6 shape the gate cannot match.
 
+When a changed PR touches a producer function whose ordering or union shifts, the O8 audit lane also reads that skill's companion `SKILL.md` and sibling `.md` docs for any sentence naming the same produced artifact. A doc sentence that claims the artifact is `sorted` or holds `just the at-risk names` while the producer merges prior names and appends without re-sorting is an O8 finding, even when the PR diff never touched the `.md` file — the behavior change orphaned the doc claim.
+
 ## Why
 
 A docstring enumeration earns its place by being trustworthy. A complete list lets a reader reason about the function without scanning the body; a list missing one item is worse than no list, because it asserts completeness it does not have. Naming this standard makes the gap a first-class finding at write time and at audit, rather than a surprise a reader hits months later.

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>"""