claude-dev-env 1.57.2 → 1.59.0

package/hooks/hooks_constants/duplicate_function_body_constants.py

@@ -0,0 +1,17 @@
+"""Constants for the cross-file duplicate-function-body scan in ``code_rules_enforcer``.
+
+The scan flags a top-level function whose body is structurally identical to a
+top-level function already defined in a sibling ``.py`` module in the same
+directory. This catches the Reuse-before-create / DRY violation where a helper
+is copy-pasted across several modules instead of imported from one shared home.
+"""
+
+MINIMUM_DUPLICATE_BODY_STATEMENTS: int = 3
+MAX_DUPLICATE_BODY_ISSUES: int = 25
+DUNDER_INIT_FILENAME: str = "__init__.py"
+PYTHON_SOURCE_SUFFIX: str = ".py"
+DUPLICATE_BODY_GUIDANCE: str = (
+    "this function body is identical to one in a sibling module; "
+    "extract a single shared helper (for example in hooks_constants/) and "
+    "import it from both modules instead of copying it (Reuse before create / DRY)"
+)

package/hooks/hooks_constants/hook_prose_detector_consistency_constants.py

@@ -0,0 +1,30 @@
+"""Configuration constants for the hook_prose_detector_consistency PreToolUse hook."""
+
+WRITE_TOOL_NAME: str = "Write"
+EDIT_TOOL_NAME: str = "Edit"
+
+HOOK_MODULE_PATH_SEGMENT: str = "/hooks/"
+PYTHON_FILE_SUFFIX: str = ".py"
+CONSTANTS_MODULE_SUFFIX: str = "_constants.py"
+TEST_MODULE_PREFIX: str = "test_"
+
+PATH_SEPARATOR_CLASS_PATTERN: str = (
+    r"\[[^\]/]*\\\\[^\]/]*\]|\[[^\]]*\\\\?/[^\]]*\]|\[[^\]]*/\\\\?[^\]]*\]"
+)
+OVERSTATED_OUTPUT_KEY_PHRASE_PATTERN: str = r"output[- ]key\s+segment"
+
+CORRECTIVE_MESSAGE: str = (
+    "BLOCKED [hook-prose-detector-consistency]: A hook module's user-facing prose "
+    "(its docstring lead narrative or CORRECTIVE_MESSAGE) claims the hook blocks an "
+    "'output-key segment', but the module's detector keys off a path separator only "
+    "(it matches a token next to `\\` or `/`). A quoted structured-output key alone "
+    "never triggers a block, so the prose overstates the contract: an author whose "
+    "only per-iteration token is an output key would never see this message, and an "
+    "author who does see it is told an output key caused a block it cannot cause.\n\n"
+    "Describe only the trigger the detector implements: a per-iteration path segment "
+    "next to a path separator. Drop 'or output-key segment' (or restate it as 'a "
+    "per-iteration path segment') so the message and docstring match what the regex "
+    "catches.\n\n"
+    "Invariant: a hook's docstring and corrective message describe exactly the shapes "
+    "its detector flags -- no broader trigger surface than the regex enforces."
+)

package/hooks/hooks_constants/messages.py

@@ -5,3 +5,7 @@ USER_FACING_TDD_NOTICE = "TDD gate held - writing the failing test first..."
 USER_FACING_ASKUSERQUESTION_NOTICE = (
     "Agent asked the user in prose - rerouting through AskUserQuestion..."
 )
+USER_FACING_INTENT_ENDING_NOTICE = "Agent ended on a promise - doing the work now..."
+USER_FACING_CONTEXT_REASSURANCE_NOTICE = (
+    "Agent moved to wrap up early - continuing the work..."
+)

package/hooks/hooks_constants/session_handoff_blocker_constants.py

@@ -0,0 +1,10 @@
+"""Shared compiled patterns for the session_handoff_blocker hook."""
+
+import re
+
+FIRST_PERSON_SUBJECT_PATTERN = re.compile(
+    r"\b(?:i['’]?m|i['’]?ll|i\s+will|i\s+am|i\s+need\s+to|i\s+should"
+    r"|i\s+recommend|i\s+suggest|let\s+me|let['’]?s"
+    r"|we\s+(?:should|can|could)|we['’]?ll|we\s+are|we\s+will)\b",
+    re.IGNORECASE,
+)

package/hooks/hooks_constants/subprocess_budget_completeness_constants.py

@@ -0,0 +1,5 @@
+"""Configuration constants for the subprocess_budget_completeness PreToolUse hook."""
+
+ALL_BUDGET_NAME_MARKERS: tuple[str, ...] = ("worst_case", "_budget", "budget_seconds")
+SUBPROCESS_TIMEOUT_KEYWORD: str = "timeout"
+BUDGET_ENTRY_POINT_FUNCTION_NAME: str = "main"

package/hooks/hooks_constants/workflow_substitution_slot_blocker_constants.py

@@ -0,0 +1,22 @@
+"""Configuration constants for the workflow_substitution_slot_blocker PreToolUse hook."""
+
+WRITE_TOOL_NAME: str = "Write"
+EDIT_TOOL_NAME: str = "Edit"
+MULTI_EDIT_TOOL_NAME: str = "MultiEdit"
+
+WORKFLOW_FILE_SUFFIX: str = ".workflow.js"
+
+CORRECTIVE_MESSAGE: str = (
+    "BLOCKED [workflow-substitution-slot]: A bare per-iteration index token "
+    "(for example `cand_i`) appears as a per-iteration path segment inside a "
+    ".workflow.js agent-prompt block that loops over an index. A bare `_i` "
+    "token reads as a fixed literal, so an agent can create one literal "
+    "directory and overwrite it across every iteration -- collapsing an "
+    "N-iteration gate into one.\n\n"
+    "Mark the index as a substitution slot with the angle-bracket convention "
+    "this template already uses for per-call values (`<plate.svg>`, `<glow_hex>`): "
+    "write `cand_<i>` instead of `cand_i`, or spell out 'replace <i> with the "
+    "iteration index 0, 1, 2' in the step text.\n\n"
+    "Convention: every per-call substitution slot in a .workflow.js template is "
+    "marked with angle brackets, so an agent fills in a fresh value per call."
+)

package/hooks/workflow/auto_formatter.py

@@ -46,7 +46,7 @@ JS_EXTENSIONS = {".js", ".ts", ".tsx", ".jsx", ".mjs", ".cjs"}
 JSON_EXTENSIONS = {".json"}
 PLUGIN_ROOT = os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
 HOOKS_DIR = os.path.join(PLUGIN_ROOT, "hooks") + os.sep
-PYTHON_FORMAT_TIMEOUT_SECONDS = 15
+PYTHON_FORMAT_TIMEOUT_SECONDS = 12
 JS_FORMAT_TIMEOUT_SECONDS = 30
 PRETTIER_CONFIG_NAMES = {
     ".prettierrc",
@@ -76,6 +76,20 @@ def has_prettier_config(file_path: str) -> bool:
     return False
 
 
+def budgeted_python_format_seconds() -> int:
+    """Return the wall-clock budget for the two-subprocess happy path.
+
+    The Python branch breaks out of each loop the moment a command runs, so
+    the common case spends one fix subprocess plus one format subprocess. This
+    is a budget for that assumed path, not a guaranteed upper bound: when a
+    command is missing or times out the loops fall through to the next entry,
+    so a degraded run can spend more than this budget.
+    """
+    fix_phase_seconds = PYTHON_FORMAT_TIMEOUT_SECONDS
+    format_phase_seconds = PYTHON_FORMAT_TIMEOUT_SECONDS
+    return fix_phase_seconds + format_phase_seconds
+
+
 def is_untracked_in_git(file_path: str) -> bool:
     """Check if file is untracked (brand new) by git."""
     containing_directory = str(Path(file_path).parent)
@@ -115,6 +129,17 @@ def main() -> None:
     suffix = Path(file_path).suffix.lower()
 
     if suffix in PYTHON_EXTENSIONS:
+        for each_fix_command in [
+            ["ruff", "check", "--fix", file_path],
+            [sys.executable, "-m", "ruff", "check", "--fix", file_path],
+        ]:
+            try:
+                subprocess.run(each_fix_command, capture_output=True, text=True, timeout=PYTHON_FORMAT_TIMEOUT_SECONDS, check=False)
+                break
+            except FileNotFoundError:
+                continue
+            except subprocess.TimeoutExpired:
+                break
         for each_formatter_command in [
             ["ruff", "format", file_path],
             [sys.executable, "-m", "ruff", "format", file_path],

package/hooks/workflow/test_auto_formatter.py

@@ -0,0 +1,134 @@
+"""Tests for the auto_formatter hook.
+
+Exercises the real hook against real ruff inside a real git repository. A
+brand-new (untracked) Python file carrying an unused import is fixed in
+place, while the same file arriving through the Edit tool is left untouched
+so the fix stays scoped to newly created files.
+
+The sandbox is rooted under the user's home directory via ``tempfile.mkdtemp``
+rather than the OS temp directory, matching the sibling workflow-hook tests.
+"""
+
+import functools
+import importlib.util
+import json
+import os
+import shutil
+import stat
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+from typing import Generator
+
+import pytest
+
+HOOK_SCRIPT_PATH = os.path.join(os.path.dirname(__file__), "auto_formatter.py")
+HOOKS_JSON_PATH = os.path.join(
+    os.path.dirname(os.path.dirname(os.path.dirname(__file__))), "hooks", "hooks.json"
+)
+AUTO_FORMATTER_COMMAND_FRAGMENT = "workflow/auto_formatter.py"
+UNUSED_IMPORT_SOURCE = "import os\n\n\nVALUE = 1\n"
+HOOK_RUN_TIMEOUT_SECONDS = 60
+
+
+def _strip_read_only_and_retry(removal_function, target_path, *_exc_info):
+    try:
+        os.chmod(target_path, stat.S_IWRITE)
+        removal_function(target_path)
+    except OSError:
+        pass
+
+
+def _force_rmtree(target_path: str) -> None:
+    handler_kw = (
+        {"onexc": _strip_read_only_and_retry}
+        if sys.version_info >= (3, 12)
+        else {"onerror": _strip_read_only_and_retry}
+    )
+    try:
+        shutil.rmtree(target_path, **handler_kw)
+    except OSError:
+        pass
+
+
+@functools.lru_cache(maxsize=1)
+def _get_sandbox_parent_directory() -> str:
+    return tempfile.mkdtemp(prefix="pytest_auto_formatter_", dir=str(Path.home()))
+
+
+@pytest.fixture(scope="session", autouse=True)
+def _cleanup_sandbox_parent_directory() -> Generator[None, None, None]:
+    yield
+    if _get_sandbox_parent_directory.cache_info().currsize:
+        _force_rmtree(_get_sandbox_parent_directory())
+        _get_sandbox_parent_directory.cache_clear()
+
+
+@pytest.fixture
+def git_repository() -> Generator[Path, None, None]:
+    repository_path = Path(tempfile.mkdtemp(dir=_get_sandbox_parent_directory()))
+    subprocess.run(["git", "init"], cwd=repository_path, capture_output=True, check=True)
+    yield repository_path
+    _force_rmtree(str(repository_path))
+
+
+def _run_hook(tool_name: str, file_path: Path) -> subprocess.CompletedProcess[str]:
+    hook_input = json.dumps({"tool_name": tool_name, "tool_input": {"file_path": str(file_path)}})
+    return subprocess.run(
+        [sys.executable, HOOK_SCRIPT_PATH],
+        input=hook_input,
+        capture_output=True,
+        text=True,
+        timeout=HOOK_RUN_TIMEOUT_SECONDS,
+        check=False,
+    )
+
+
+class TestRuffFixOnNewFiles:
+    def should_remove_unused_import_from_new_untracked_python_file(
+        self, git_repository: Path
+    ) -> None:
+        new_file = git_repository / "brand_new.py"
+        new_file.write_text(UNUSED_IMPORT_SOURCE, encoding="utf-8")
+
+        completed_hook = _run_hook("Write", new_file)
+
+        assert completed_hook.returncode == 0
+        assert "import os" not in new_file.read_text(encoding="utf-8")
+
+    def should_leave_file_arriving_through_edit_untouched(self, git_repository: Path) -> None:
+        edited_file = git_repository / "edited.py"
+        edited_file.write_text(UNUSED_IMPORT_SOURCE, encoding="utf-8")
+
+        completed_hook = _run_hook("Edit", edited_file)
+
+        assert completed_hook.returncode == 0
+        assert "import os" in edited_file.read_text(encoding="utf-8")
+
+
+def _load_auto_formatter_module() -> object:
+    module_spec = importlib.util.spec_from_file_location("auto_formatter", HOOK_SCRIPT_PATH)
+    assert module_spec is not None and module_spec.loader is not None
+    auto_formatter_module = importlib.util.module_from_spec(module_spec)
+    module_spec.loader.exec_module(auto_formatter_module)
+    return auto_formatter_module
+
+
+def _registered_auto_formatter_timeout() -> int:
+    with open(HOOKS_JSON_PATH, encoding="utf-8") as hooks_file:
+        hooks_configuration = json.load(hooks_file)
+    for each_event in hooks_configuration["hooks"].values():
+        for each_matcher in each_event:
+            for each_hook in each_matcher["hooks"]:
+                if AUTO_FORMATTER_COMMAND_FRAGMENT in each_hook["command"]:
+                    return int(each_hook["timeout"])
+    raise AssertionError("auto_formatter hook is not registered in hooks.json")
+
+
+class TestPythonFormatTimeoutBudget:
+    def should_keep_both_sequential_python_subprocesses_under_the_harness_budget(self) -> None:
+        auto_formatter_module = _load_auto_formatter_module()
+        budgeted_total = auto_formatter_module.budgeted_python_format_seconds()
+
+        assert budgeted_total < _registered_auto_formatter_timeout()

package/package.json

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

package/rules/conservative-action.md

@@ -13,6 +13,7 @@ Proceed with edits, file modifications, or implementations only when the user ex
 - If the user asks a question, answer the question. Do not also fix the thing they asked about.
 - If the user describes a problem, investigate and recommend. Do not jump to implementation.
 - If the user says "do it", "go ahead", "make the change", or similarly explicit language, proceed with action.
+- Once the user has explicitly asked and you have what you need, act — do not re-open settled facts or decisions, and do not re-survey options you will not pursue. This rule governs the ambiguous case; the clear case belongs to `long-horizon-autonomy`.
 - When in doubt, ask: "Would you like me to make this change, or just show you the approach?"
 
 ## Why

package/rules/docstring-prose-matches-implementation.md

@@ -0,0 +1,43 @@
+# 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.
+
+## Rule
+
+When a docstring enumerates the behaviors a body applies, the enumeration covers every behavior the body applies. A reader trusts the list to be complete: an item the code applies but the prose omits is a silent gap that misleads every future reader and reviewer.
+
+The gate validator `check_docstring_args_match_signature` covers the `Args:` section parameter names. Free-form prose — `"a field counts as read when ..."`, `"resolves to shared temp only"`, `"strip ceremony, then drop blockquotes"` — has no signature to compare against, so the gate cannot catch its drift. This rule is the judgment standard for that prose. It carries documented-but-pending hook coverage; the audit lane below is the enforcement until a deterministic gate check exists.
+
+## What to check before you write the docstring
+
+Read the body and the docstring side by side:
+
+- **Read-source / match-source unions.** A body that computes `read_names = a | b | c` (or any union of "what counts") names each union member in the prose enumeration. A union member the code applies but the prose omits is a gap.
+- **Suppressor / skip lists.** A body with several early returns that suppress the check names each suppressor in the prose.
+- **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.
+
+When the body changes the set of behaviors it applies, the same edit updates the prose enumeration. The two move together in one commit.
+
+## Worked example
+
+A `@dataclass` dead-field check builds its set of "field counts as read" sources by union:
+
+```python
+read_names = (
+    attribute_read_names
+    | dynamic_literal_names
+    | _match_pattern_attribute_names(tree)
+    | _exported_names(tree)
+)
+```
+
+A docstring that enumerates "attribute read, augmented-assignment target, class-pattern keyword, literal `getattr`/`attrgetter`" but omits the `__all__` source (`_exported_names`) is drifted: a field whose name appears in `__all__` is treated as read, and the prose hides that. The fix adds the missing source to the enumeration so the list matches the union.
+
+## Enforcement (audit lane)
+
+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.
+
+## 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/rules/hook-prose-matches-detector.md

@@ -0,0 +1,26 @@
+---
+paths: **/hooks/**/*.py
+---
+
+# Hook Prose Matches Its Detector
+
+**When this applies:** Any Write or Edit to a hook module (`.py` under `hooks/`) or its `*_constants.py` companion.
+
+**Hook enforcement:** `hook-prose-detector-consistency` (PreToolUse on Write|Edit) blocks a hook whose user-facing prose claims a trigger its detector never fires on. See `hooks.json` for registration.
+
+## Rule
+
+A hook's docstring lead narrative and its `CORRECTIVE_MESSAGE` describe exactly the shapes the detector flags — no broader trigger surface than the regex enforces. An author reads the corrective message to learn what they did wrong; an author reads the docstring to learn what the hook guards. When either claims a trigger the detector cannot fire on, both audiences are misled: an author whose only token is that shape never sees the block, and an author who does see the block is told the wrong cause.
+
+## The path-shape blocker case
+
+A path-shape blocker detects a per-iteration token only when the token sits next to a path separator (its detection regex keys off a `[\\/]`-style character class). Such a hook must not claim it blocks an "output-key segment": a quoted structured-output key alone, with no looped path, is never flagged. The `*_constants.py` companion holds the corrective message and not the detector, so the phrase "output-key segment" describing a blocked trigger is itself the violation there, regardless of which file holds the regex.
+
+| Prohibited claim | Why it overstates | Correct phrasing |
+|---|---|---|
+| "appears as a path or output-key segment" | the detector keys off a path separator only | "appears as a per-iteration path segment" |
+| docstring: "blocks a bare token like `cand_i`" | a bare prose token next to no separator is not flagged | "blocks a per-iteration path like `${work}\cand_i\plate.svg`" |
+
+## The test
+
+After writing a hook, ask: **would a token that matches every word of this message actually trip the detector?** When the message names a shape the regex skips, rewrite the message to name only what the regex catches.

package/rules/long-horizon-autonomy.md

@@ -0,0 +1,43 @@
+# Long-Horizon Autonomy
+
+Source: [Anthropic - Prompting Claude Fable 5](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-fable-5)
+
+**When this applies:** Long, multi-step, or unwatched runs — autonomous pipelines, background jobs, convergence loops, and any task that spans many tool calls or a long stretch where the user is away. The behaviors below carry a run to completion rather than letting it stall, drift, or stop early.
+
+## Act on what you have
+
+When you have enough to act, act. Do not re-derive facts already settled in the conversation, re-open a decision the user already made, or narrate options you will not pursue in user-facing text. When you weigh a choice, give a recommendation, not a full survey. This shapes user-facing messages, not your private reasoning.
+
+This is the autonomous-run partner to `conservative-action`: that rule covers the ambiguous case (research and recommend first); this one covers the clear case (once the evidence is in hand, act).
+
+## Do not end a turn on a promise
+
+Pause for the user only when the work truly needs them: a destructive or irreversible action, a real scope change, or input only they can give. When you hit one, ask through `AskUserQuestion` and end the turn. Do not end on a promise about work you have not done.
+
+Before you end any turn, read your last paragraph. If it is a plan, an analysis, a list of next steps, or a statement of intent ("I'll run the tests", "next I'll wire it up"), do that work with tool calls before you stop. End the turn only when the task is done or you are blocked on input only the user can give.
+
+In an autonomous pipeline the user cannot answer mid-task. For reversible actions that follow from the original request, act without asking; save any follow-up offers for after the task is done.
+
+## Delegate and keep working
+
+Hand independent subtasks to subagents and keep working while they run; let them run in the background rather than block until each one returns. Reuse a long-lived subagent across related subtasks so its context carries forward and saves repeated reads. Step in when a subagent drifts off track or is missing context.
+
+## Verify your work at intervals
+
+On a long build, set a checkpoint cadence and hold to it. At each interval, check the work so far against the task's stated goals with a fresh-context verifier subagent. A separate verifier in a clean context catches what self-review misses.
+
+## Ground every progress claim
+
+Before you report progress, check each claim against a tool result from this session. State only what the evidence backs; name anything unverified as unverified. If tests fail, say so with the output; if a step was skipped, say that.
+
+## Re-ground the final message
+
+Terse shorthand between tool calls is fine — that is you thinking. The final message is for a reader who saw none of it. After a long or unwatched run, write it as a fresh briefing: the outcome in one sentence, then the one or two things you need from the reader, each explained as if new. Drop the working vocabulary, arrow chains, and stacked-hyphen compounds; give each file, commit, or flag its own plain clause. When short and clear pull apart, choose clear.
+
+## Keep going on context
+
+A remaining-context or token count is not a reason to stop. Do not pause, summarize, or float a fresh session on account of context limits; keep working. When the user must see content word-for-word (a partial deliverable, a direct answer to a mid-run question), surface it through the channel the harness gives for that, not by ending the turn.
+
+## Why
+
+A capable model under-delivers on long runs for predictable reasons: it overplans when it could act, stops on a promise, blocks on subagents, skips its own verification, fabricates progress, buries the result in working shorthand, or quits early over a context count. Each section above removes one of those failure modes so the run finishes.

package/rules/no-inline-destructive-literals.md

@@ -0,0 +1,11 @@
+# No Inline Destructive-Command Literals in Bash
+
+The `destructive_command_blocker` PreToolUse hook matches destructive patterns (`rm -rf`, `git reset --hard`, `dd`, `mkfs`, `chmod -R`, fork bombs) as raw text anywhere in a Bash-tool command, with no quote-awareness — so a destructive literal carried only as DATA (a commit message, a PR/issue/review-comment body, an echoed string, a `python -c`/`node -e`/`awk` argument, a heredoc) trips the confirmation prompt even though the shell never executes it. In a background or auto-mode run no human can answer that prompt, so the call stalls.
+
+Keep destructive literals out of the Bash command string:
+
+- Commit messages and PR/issue/review-comment bodies that describe destructive-command behavior go in a file passed by path — `git commit -F <file>`, `gh ... --body-file <file>` (see [`gh-body-file`](gh-body-file.md)) — never `git commit -m` / `gh ... -b`.
+- To exercise or verify `destructive_command_blocker` (or any hook) behavior, run the committed test suite (`python -m pytest <test_file>`), which passes the command strings as in-language data, not as a shell command — never an inline `python -c` harness.
+- Genuine cleanup targets the OS temp dir or `$CLAUDE_JOB_DIR/tmp` (auto-allowed as ephemeral), never a repository or worktree path.
+
+The `destructive_command_blocker` hook is the enforcement surface; this rule is how to keep a non-executing mention from tripping it.

package/rules/workflow-substitution-slots.md

@@ -0,0 +1,7 @@
+# Workflow Substitution Slot Rule
+
+In a `.workflow.js` agent-prompt template, every per-call or per-iteration value an agent must fill in is marked with the angle-bracket convention — `<plate.svg>`, `<object.svg>`, `<glow_hex>`, `cand_<i>`. A bare token such as `cand_i` reads as a fixed literal, so an agent can create one literal directory named `cand_i` and overwrite it across every iteration of a loop, collapsing an N-iteration gate into a single run.
+
+When a loop builds a per-iteration path or output key, write the index as a slot — `cand_<i>` — or spell out `replace <i> with the iteration index 0, 1, 2` in the step text. Every per-call value in a `.workflow.js` template carries angle brackets so an agent fills in a fresh value per call.
+
+`workflow_substitution_slot_blocker.py` (PreToolUse on Write/Edit) blocks a `.workflow.js` write whose looped content carries a bare `<word>_<i|j|k>` token as a per-iteration path segment, and returns the corrective message.

package/skills/autoconverge/SKILL.md

@@ -66,7 +66,7 @@ own. The workflow runs in the background and notifies this session on
 completion. Watch live progress with `/workflows`.
 
 The workflow returns
-`{ converged, rounds, finalSha, blocker, standardsNote }`.
+`{ converged, rounds, finalSha, blocker, standardsNote, copilotNote }`.
 
 ## Budget-aware round boundaries
 
@@ -81,15 +81,64 @@ round records nothing resumable and replays dirty.
 
 ## Teardown (on workflow completion)
 
-1. **When `converged` is true:** rewrite the PR description and clean the
+1. **When `converged` is true — build and publish the closing report.**
+   Skip this entire step (report, gist, comment, Chrome open) when the workflow
+   returned a non-null `blocker`. Per-round live-dashboard refresh is out of scope
+   here; this step builds the one-shot closing report and the seam (marker comment +
+   gist URL) a future live-dashboard reuses.
+
+   a. **Resolve the journal path.** Glob
+      `~/.claude/projects/**/workflows/wf_<runId>.json` (where `runId` is the run id
+      the `Workflow` result returned) and take the match.
+
+   b. **Build the report.**
+      ```
+      python "<skill>/workflow/render_report.py" \
+        --journal "<journal>" \
+        --out "$CLAUDE_JOB_DIR/tmp/autoconverge-report-<prNumber>.html" \
+        --pr <owner>/<repo>#<n> \
+        --final-sha <finalSha> \
+        --rounds <rounds> \
+        --repo <worktree>
+      ```
+      Capture the output path from stdout.
+
+   c. **Publish as a secret gist** by reusing `doc-gist` (do not reimplement gist
+      creation):
+      ```
+      python "$HOME/.claude/skills/doc-gist/scripts/gist_upload.py" \
+        --input "<html path>" \
+        --no-open \
+        --description "autoconverge report PR #<n>"
+      ```
+      Capture the htmlpreview URL from stdout. The gist is secret by default; pass
+      no public flag.
+
+   d. **Post one idempotent PR comment.** List the PR's issue comments; if one
+      carries the marker `<!-- autoconverge-report -->`, edit it in place, otherwise
+      create a new one. The body begins with `<!-- autoconverge-report -->`, then
+      the htmlpreview link, headline counts (findings by severity, rounds, tests
+      added), and the full finding list as `file:line — P# — title` grouped by
+      severity. Honor the gh-body-file rule: write a BOM-free temp file and pass
+      `--body-file` to `gh issue comment`/`gh issue comment edit`, or use the
+      GitHub MCP `add_issue_comment` tool (body as a structured parameter, no
+      `--body` flag).
+
+   e. **Open the report in Chrome.**
+      ```
+      Start-Process chrome -ArgumentList '--new-window', '<report path>'
+      ```
+      Tolerate a missing Chrome without aborting the rest of teardown.
+
+2. **When `converged` is true:** rewrite the PR description and clean the
    working tree — see
    [`bugteam/reference/teardown-publish-permissions.md` § Step 4 and § Step 4.5](../bugteam/reference/teardown-publish-permissions.md).
    The workflow already marked the PR ready.
 
-2. **Always revoke project permissions** (including on a blocker exit):
+3. **Always revoke project permissions** (including on a blocker exit):
    `python "$HOME/.claude/skills/bugteam/scripts/revoke_project_claude_permissions.py"`
 
-3. **Print the final report:**
+4. **Print the final report:**
 
    ```
    /autoconverge exit: <converged | blocked>
@@ -97,6 +146,7 @@ round records nothing resumable and replays dirty.
    Final commit: <finalSha>
    Blocker: <blocker>        # only when blocked
    Standards: <standardsNote> # only when a round deferred code-standard findings
+   Copilot: <copilotNote>     # only when Copilot was down or out of quota
    ```
 
 ## What the workflow does each round
@@ -107,6 +157,13 @@ shape and the exact convergence definition, and
 run ends short of ready. Hard-won failure lessons live in
 [`reference/gotchas.md`](reference/gotchas.md).
 
+Every agent prompt carries a headless-safety preamble: the run is unattended, so
+agents never inline a destructive-command literal (`rm -rf`, `git reset --hard`,
+`dd`) into a Bash command — the `destructive_command_blocker` hook matches those
+patterns as raw text, and a confirmation prompt no human can answer would stall
+the run. Agents verify destructive-blocker behavior through the committed test
+suite (`python -m pytest`) and keep scratch work in ephemeral temp dirs.
+
 - **Converge:** `parallel([Bugbot lens, code-review lens, bug-audit lens])` on
   the current HEAD, full `origin/main...HEAD` diff. Dedup findings; one
   `clean-coder` applies all fixes in a single commit, pushes, replies to and
@@ -119,7 +176,10 @@ run ends short of ready. Hard-won failure lessons live in
   any bot threads with a deferral note, and reports the deferral in
   `standardsNote`.
 - **Copilot gate:** request a Copilot review, poll up to three times; findings
-  route back into Converge, a no-show after the cap is a blocker.
+  route back into Converge. When Copilot is down or out of quota — it posts an
+  out-of-usage notice (the requester hit their quota) on the HEAD, or surfaces no
+  review at all after the cap — the gate logs a notice and the run marks the PR
+  ready with the Copilot gate bypassed. `copilotNote` records the bypass.
 - **Convergence check:** `check_convergence.py` is the authoritative gate; on a
   full pass the workflow marks `draft=false`.
 
@@ -127,4 +187,6 @@ run ends short of ready. Hard-won failure lessons live in
 
 - `SKILL.md` — this hub.
 - `workflow/converge.mjs` — the convergence workflow script.
-- `reference/` — convergence definition, stop conditions, gotchas.
+- `workflow/render_report.py` — builds the closing convergence insights HTML report.
+- `workflow/autoconverge_report_constants/` — named constants for the report builder.
+- `reference/` — convergence definition, stop conditions, gotchas, closing report.

package/skills/autoconverge/reference/closing-report.md

@@ -0,0 +1,44 @@
+# Closing Report
+
+When an autoconverge run converges (the workflow returns `converged: true`), the main session generates a convergence insights HTML report and publishes it as a secret gist with an idempotent PR comment linking to it.
+
+## Data source
+
+The report reads two file types written by the workflow during the run:
+
+- **Run journal** — `~/.claude/projects/**/workflows/wf_<runId>.json` — the PR args, round log lines, `workflowProgress` array (one entry per agent step), and the final result.
+- **Agent transcripts** — `~/.claude/projects/**/subagents/workflows/<runId>/agent-<agentId>.jsonl` — one file per agent; each line is a JSON object; the renderer extracts the last `StructuredOutput` tool_use from each file.
+
+`converge.mjs` is not modified. The report is a pure reader of files the workflow already writes.
+
+## Building the report
+
+```
+python "<skill>/workflow/render_report.py" \
+  --journal "<journal path>" \
+  --out "<output path>.html" \
+  --pr <owner>/<repo>#<n> \
+  --final-sha <sha> \
+  --rounds <N> \
+  --repo <worktree path>
+```
+
+The script reads the journal and transcripts, computes aggregated metrics (findings by severity, round, and theme; fix commits; tests added per round), and writes a self-contained HTML report. It prints the output path to stdout and exits 0 on success.
+
+All aggregation is deterministic: `generated_date` comes from the journal `timestamp`, not the system clock, so the same inputs always produce the same HTML.
+
+## Publishing
+
+After rendering, the main session:
+
+1. **Uploads the HTML as a secret gist** using `doc-gist/scripts/gist_upload.py --no-open`. Captures the htmlpreview URL from stdout.
+2. **Posts one idempotent PR comment** marked with `<!-- autoconverge-report -->`. If a comment with that marker already exists on the PR, it is edited in place; otherwise a new comment is created. The comment body has the gist URL and a summary of findings by severity, rounds, and tests added, followed by the full finding list grouped by severity (`file:line — P# — title`). Write the body to a BOM-free temp file and pass `--body-file` to `gh issue comment` (never `--body`), or use the GitHub MCP `add_issue_comment` tool.
+3. **Opens the report** with `Start-Process chrome -ArgumentList '--new-window', '<report path>'`. A missing Chrome does not abort teardown.
+
+## Live-dashboard seam
+
+The marker comment and gist together form a seam for future per-round dashboard refreshes: a live-dashboard step re-renders with the same `render_report_html` function (pure, no side effects), runs `gh gist edit` on the same gist, and edits the same marker comment. That per-round refresh path is out of scope here; this document describes the one-shot closing report only.
+
+## Scope
+
+The closing report runs only when `converged === true`. On a blocker exit (`blocker: "budget"` or similar), the report, gist, comment, and Chrome open are all skipped.

package/skills/autoconverge/reference/convergence.md

@@ -42,7 +42,9 @@ tracks CONVERGE passes only and is never the cap.
   to three times, 360 seconds apart.
 - Copilot findings → fix them and return to CONVERGE on the new HEAD.
 - Copilot clean or approved → move to the convergence check.
-- No review after three polls → blocker.
+- Copilot down or out of quota (an out-of-usage notice, or no review after three
+  polls) → log a notice and move to the convergence check with the Copilot gate
+  bypassed.
 
 **Convergence check**:
 
@@ -67,13 +69,15 @@ the current HEAD:
 2. The Bugbot review body on HEAD reports no findings (checked when a Bugbot
    review is present).
 3. A CLEAN bugteam audit review sits on HEAD.
-4. The Copilot review on HEAD is clean or approved.
+4. The Copilot review on HEAD is clean or approved (bypassed when Copilot is down
+   or out of quota this run).
 5. Zero unresolved bot review threads anywhere on the PR — counting Cursor,
    Claude, and Copilot authored threads where `isResolved` is false (`isOutdated`
    threads are excluded by the gate, but the fix lens still verifies and resolves
    them during the round).
 6. The PR is mergeable (`mergeable` true and `mergeable_state` clean).
-7. No requested reviewers are still pending.
+7. No requested reviewers are still pending (bypassed when Copilot is down or out
+   of quota this run).
 
 ## Audit-trail design