claude-dev-env 1.57.1 → 1.58.0

package/hooks/blocking/test_session_handoff_blocker.py

@@ -0,0 +1,312 @@
+"""Tests for session_handoff_blocker hook response shape."""
+
+import importlib.util
+import json
+import os
+import subprocess
+import sys
+
+HOOK_SCRIPT_PATH = os.path.join(os.path.dirname(__file__), "session_handoff_blocker.py")
+_HOOKS_DIR = os.path.dirname(HOOK_SCRIPT_PATH)
+_HOOKS_ROOT = os.path.join(_HOOKS_DIR, "..")
+_HOOK_CONFIG_DIR = os.path.join(_HOOKS_ROOT, "hooks_constants")
+if _HOOKS_DIR not in sys.path:
+    sys.path.insert(0, _HOOKS_DIR)
+if _HOOKS_ROOT not in sys.path:
+    sys.path.insert(0, _HOOKS_ROOT)
+import session_handoff_blocker
+from hooks_constants.messages import USER_FACING_CONTEXT_REASSURANCE_NOTICE
+
+NEW_SESSION_PROPOSAL_MESSAGE = (
+    "I recommend we continue this in a fresh session to keep things manageable."
+)
+RUNNING_LOW_ON_CONTEXT_MESSAGE = (
+    "We are running low on context, so let me summarize where things stand."
+)
+SHORT_ON_TOKENS_MESSAGE = "I'm getting short on tokens, so I'll wrap up here."
+CONSERVE_CONTEXT_MESSAGE = "To conserve context, let me stop and hand off the remaining work."
+CONTEXT_WINDOW_HANDOFF_MESSAGE = (
+    "The context window is filling up, so I'll wrap up and we can continue later."
+)
+BENIGN_TOPICAL_MESSAGE = "The function accepts a context manager and a token string."
+CLEAN_MESSAGE = "The parser handles every fixture and returns a deduplicated list."
+TECHNICAL_TERMINAL_SESSION_MESSAGE = (
+    "Consider starting a new session in your terminal to pick up the env vars."
+)
+LOAD_TEST_SESSION_MESSAGE = "We can spin up a fresh session for the load test."
+DATABASE_SESSION_MESSAGE = "Open a new database session before running the query."
+HANDOFF_NEW_SESSION_MESSAGE = (
+    "Let's wrap up and continue this in a fresh session to pick this up later."
+)
+LOW_ON_CONTEXT_WITHOUT_CUE_MESSAGE = (
+    "I am low on context for this edge case in the parser."
+)
+SAVE_TOKENS_REPORT_MESSAGE = "To save tokens, I inlined the constant."
+LOW_ON_CONTEXT_WITH_HANDOFF_CUE_MESSAGE = (
+    "I'm low on context, so let me wrap up and hand off."
+)
+NEW_SESSION_TOKEN_MESSAGE = (
+    "To continue this task I need the new session token from the API."
+)
+RESUME_TRAFFIC_FRESH_SESSION_POOL_MESSAGE = (
+    "After deploy, resume traffic in a fresh session pool."
+)
+THIRD_PERSON_RUNS_LOW_DESIGN_MESSAGE = (
+    "The agent should stop when it runs low on context, per the old design."
+)
+DOCUMENT_RUNNING_LOW_MESSAGE = (
+    "Document that agents running low on tokens should not stop."
+)
+USER_ADVICE_NEW_SESSION_MESSAGE = (
+    "To save tokens, you could start a new session for the unrelated task."
+)
+CONTEXT_WINDOW_SUMMARIZE_MESSAGE = (
+    "The context window is getting full, so let me summarize where we are."
+)
+BENIGN_SUMMARIZE_REPORT_MESSAGE = "I should summarize the findings for the report."
+BENIGN_STOP_PLUS_UNRELATED_RUNNING_LOW_MESSAGE = (
+    "Let me pause the animation timer. The job fails when it is running low on tokens."
+)
+BENIGN_STOP_PLUS_USER_DIRECTED_NEW_SESSION_MESSAGE = (
+    "Let me stop the timer. The user can continue this in a fresh session."
+)
+EMPTY_MESSAGE = ""
+
+
+def run_hook_with_message(assistant_message: str) -> subprocess.CompletedProcess:
+    hook_input_payload = json.dumps({"last_assistant_message": assistant_message})
+    return subprocess.run(
+        [sys.executable, HOOK_SCRIPT_PATH],
+        input=hook_input_payload,
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+
+
+def run_hook_with_payload(hook_input_payload: dict) -> subprocess.CompletedProcess:
+    return subprocess.run(
+        [sys.executable, HOOK_SCRIPT_PATH],
+        input=json.dumps(hook_input_payload),
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+
+
+def test_user_facing_notice_matches_config_messages_module():
+    config_messages_path = os.path.join(_HOOK_CONFIG_DIR, "messages.py")
+    specification = importlib.util.spec_from_file_location("messages", config_messages_path)
+    module = importlib.util.module_from_spec(specification)
+    specification.loader.exec_module(module)
+
+    assert module.USER_FACING_CONTEXT_REASSURANCE_NOTICE == USER_FACING_CONTEXT_REASSURANCE_NOTICE
+    assert (
+        session_handoff_blocker.USER_FACING_CONTEXT_REASSURANCE_NOTICE
+        == module.USER_FACING_CONTEXT_REASSURANCE_NOTICE
+    )
+
+
+def test_new_session_proposal_emits_block_with_short_user_notice():
+    completed_process = run_hook_with_message(NEW_SESSION_PROPOSAL_MESSAGE)
+
+    assert completed_process.returncode == 0
+    parsed_response = json.loads(completed_process.stdout)
+
+    assert parsed_response["decision"] == "block"
+    assert parsed_response["systemMessage"] == USER_FACING_CONTEXT_REASSURANCE_NOTICE
+    assert parsed_response["suppressOutput"] is True
+    assert "ample context remaining" in parsed_response["reason"]
+    assert "long-horizon-autonomy" in parsed_response["reason"]
+
+
+def test_running_low_on_context_emits_block():
+    completed_process = run_hook_with_message(RUNNING_LOW_ON_CONTEXT_MESSAGE)
+
+    assert completed_process.returncode == 0
+    parsed_response = json.loads(completed_process.stdout)
+
+    assert parsed_response["decision"] == "block"
+    assert parsed_response["systemMessage"] == USER_FACING_CONTEXT_REASSURANCE_NOTICE
+
+
+def test_short_on_tokens_emits_block():
+    completed_process = run_hook_with_message(SHORT_ON_TOKENS_MESSAGE)
+
+    assert completed_process.returncode == 0
+    parsed_response = json.loads(completed_process.stdout)
+
+    assert parsed_response["decision"] == "block"
+
+
+def test_conserve_context_emits_block():
+    completed_process = run_hook_with_message(CONSERVE_CONTEXT_MESSAGE)
+
+    assert completed_process.returncode == 0
+    parsed_response = json.loads(completed_process.stdout)
+
+    assert parsed_response["decision"] == "block"
+
+
+def test_context_window_co_occurring_handoff_cue_emits_block():
+    completed_process = run_hook_with_message(CONTEXT_WINDOW_HANDOFF_MESSAGE)
+
+    assert completed_process.returncode == 0
+    parsed_response = json.loads(completed_process.stdout)
+
+    assert parsed_response["decision"] == "block"
+
+
+def test_benign_topical_mention_passes_through_with_no_output():
+    completed_process = run_hook_with_message(BENIGN_TOPICAL_MESSAGE)
+
+    assert completed_process.returncode == 0
+    assert completed_process.stdout == ""
+
+
+def test_technical_terminal_session_passes_through_with_no_output():
+    completed_process = run_hook_with_message(TECHNICAL_TERMINAL_SESSION_MESSAGE)
+
+    assert completed_process.returncode == 0
+    assert completed_process.stdout == ""
+
+
+def test_load_test_session_passes_through_with_no_output():
+    completed_process = run_hook_with_message(LOAD_TEST_SESSION_MESSAGE)
+
+    assert completed_process.returncode == 0
+    assert completed_process.stdout == ""
+
+
+def test_database_session_passes_through_with_no_output():
+    completed_process = run_hook_with_message(DATABASE_SESSION_MESSAGE)
+
+    assert completed_process.returncode == 0
+    assert completed_process.stdout == ""
+
+
+def test_new_session_with_handoff_framing_emits_block():
+    completed_process = run_hook_with_message(HANDOFF_NEW_SESSION_MESSAGE)
+
+    assert completed_process.returncode == 0
+    parsed_response = json.loads(completed_process.stdout)
+
+    assert parsed_response["decision"] == "block"
+    assert parsed_response["systemMessage"] == USER_FACING_CONTEXT_REASSURANCE_NOTICE
+
+
+def test_low_on_context_without_handoff_cue_passes_through_with_no_output():
+    completed_process = run_hook_with_message(LOW_ON_CONTEXT_WITHOUT_CUE_MESSAGE)
+
+    assert completed_process.returncode == 0
+    assert completed_process.stdout == ""
+
+
+def test_save_tokens_work_report_passes_through_with_no_output():
+    completed_process = run_hook_with_message(SAVE_TOKENS_REPORT_MESSAGE)
+
+    assert completed_process.returncode == 0
+    assert completed_process.stdout == ""
+
+
+def test_low_on_context_with_handoff_cue_emits_block():
+    completed_process = run_hook_with_message(LOW_ON_CONTEXT_WITH_HANDOFF_CUE_MESSAGE)
+
+    assert completed_process.returncode == 0
+    parsed_response = json.loads(completed_process.stdout)
+
+    assert parsed_response["decision"] == "block"
+    assert parsed_response["systemMessage"] == USER_FACING_CONTEXT_REASSURANCE_NOTICE
+
+
+def test_new_session_token_passes_through_with_no_output():
+    completed_process = run_hook_with_message(NEW_SESSION_TOKEN_MESSAGE)
+
+    assert completed_process.returncode == 0
+    assert completed_process.stdout == ""
+
+
+def test_resume_traffic_fresh_session_pool_passes_through_with_no_output():
+    completed_process = run_hook_with_message(RESUME_TRAFFIC_FRESH_SESSION_POOL_MESSAGE)
+
+    assert completed_process.returncode == 0
+    assert completed_process.stdout == ""
+
+
+def test_third_person_runs_low_description_passes_through_with_no_output():
+    completed_process = run_hook_with_message(THIRD_PERSON_RUNS_LOW_DESIGN_MESSAGE)
+
+    assert completed_process.returncode == 0
+    assert completed_process.stdout == ""
+
+
+def test_document_running_low_instruction_passes_through_with_no_output():
+    completed_process = run_hook_with_message(DOCUMENT_RUNNING_LOW_MESSAGE)
+
+    assert completed_process.returncode == 0
+    assert completed_process.stdout == ""
+
+
+def test_user_directed_new_session_advice_passes_through_with_no_output():
+    completed_process = run_hook_with_message(USER_ADVICE_NEW_SESSION_MESSAGE)
+
+    assert completed_process.returncode == 0
+    assert completed_process.stdout == ""
+
+
+def test_context_window_summarize_handoff_emits_block():
+    completed_process = run_hook_with_message(CONTEXT_WINDOW_SUMMARIZE_MESSAGE)
+
+    assert completed_process.returncode == 0
+    parsed_response = json.loads(completed_process.stdout)
+
+    assert parsed_response["decision"] == "block"
+    assert parsed_response["systemMessage"] == USER_FACING_CONTEXT_REASSURANCE_NOTICE
+
+
+def test_benign_summarize_report_passes_through_with_no_output():
+    completed_process = run_hook_with_message(BENIGN_SUMMARIZE_REPORT_MESSAGE)
+
+    assert completed_process.returncode == 0
+    assert completed_process.stdout == ""
+
+
+def test_benign_stop_with_unrelated_running_low_sentence_passes_through_with_no_output():
+    completed_process = run_hook_with_message(
+        BENIGN_STOP_PLUS_UNRELATED_RUNNING_LOW_MESSAGE
+    )
+
+    assert completed_process.returncode == 0
+    assert completed_process.stdout == ""
+
+
+def test_benign_stop_with_user_directed_new_session_sentence_passes_through_with_no_output():
+    completed_process = run_hook_with_message(
+        BENIGN_STOP_PLUS_USER_DIRECTED_NEW_SESSION_MESSAGE
+    )
+
+    assert completed_process.returncode == 0
+    assert completed_process.stdout == ""
+
+
+def test_clean_message_passes_through_with_no_output():
+    completed_process = run_hook_with_message(CLEAN_MESSAGE)
+
+    assert completed_process.returncode == 0
+    assert completed_process.stdout == ""
+
+
+def test_empty_message_passes_through_with_no_output():
+    completed_process = run_hook_with_message(EMPTY_MESSAGE)
+
+    assert completed_process.returncode == 0
+    assert completed_process.stdout == ""
+
+
+def test_stop_hook_active_short_circuits_with_no_output():
+    completed_process = run_hook_with_payload(
+        {"last_assistant_message": NEW_SESSION_PROPOSAL_MESSAGE, "stop_hook_active": True}
+    )
+
+    assert completed_process.returncode == 0
+    assert completed_process.stdout == ""

package/hooks/hooks.json

@@ -214,6 +214,16 @@
             "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/question_to_user_enforcer.py",
             "timeout": 10
           },
+          {
+            "type": "command",
+            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/intent_only_ending_blocker.py",
+            "timeout": 10
+          },
+          {
+            "type": "command",
+            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/session_handoff_blocker.py",
+            "timeout": 10
+          },
           {
             "type": "command",
             "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/diagnostic/hook_log_stop_wrapper.py",

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/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.1",
+    "version": "1.58.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/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/skills/autoconverge/SKILL.md

@@ -66,8 +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 }`. Every agent the
-workflow spawns runs on Fable 5 (`model: 'fable'`).
+`{ converged, rounds, finalSha, blocker, standardsNote }`.
 
 ## Budget-aware round boundaries
 
@@ -82,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>
@@ -128,4 +176,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.