claude-dev-env 1.55.2 → 1.56.0

package/CLAUDE.md

@@ -50,6 +50,25 @@ Run every multi-step code task in two phases:
 
 Repair agents run only on reported findings; the verifier re-checks after each repair. Work lands (commit, push, draft PR) only on a clean verdict — enforced by the `verified_commit_gate` hook, which blocks `git commit`/`git push` unless a hook-minted verdict covers the current branch diff. The one exemption is mechanical, not discretionary: a diff whose every changed file is non-code or has an unchanged Python AST once docstrings are stripped (docs, docstrings, comments).
 
+## Converge & Review Loop Discipline
+
+- **Worktree isolation:** Run every PR convergence and review loop in an isolated worktree, never a shared checkout that concurrent processes may advance. Verify isolation (the working directory path includes `.claude/worktrees/`) before the first tick or round.
+- **No hedging in findings:** Findings and PR reports state verified facts only — never `likely`, `probably`, `should`, `appears to`. Verify each claim against the code before stating it; the anti-hallucination Stop hook rejects hedged responses.
+- **Tight edit scope:** Edit exactly what the task names — no whole-file rewrites, no renaming public method parameters, no changes beyond the stated task. When the user asks for a "lasting" or "reusable" fix, prefer the durable systemic fix over a one-off edit.
+- **GitHub MCP first:** The GitHub MCP (`mcp__plugin_github_github__*`) is the primary path for PR and review-thread inspection; raw `gh api` is the fallback, not the default — MCP calls work the same from any worktree.
+
+## Sub-agent Output Validation
+
+After any sub-agent returns a PR description, file list, or counts, verify each claim against the actual diff and repo state before using it. Flag and correct any invented paths, fabricated counts, or out-of-scope changes before they land in commits or PR bodies.
+
+## Git Sync Intent
+
+When asked to sync git ("get X onto origin main", "update main"), fast-forward local main to origin — do NOT commit untracked working-tree files unless explicitly told to.
+
+## Scheduled Task Cadence
+
+For scheduled/cron tasks, default to sub-hour intervals (30-minute); do not propose hourly cadences.
+
 ## Additional Non-overlapping Rules
 
 - **task_scope:** Match every action to what was explicitly requested. When intent is ambiguous, research official docs and present options via AskUserQuestion before making any changes. Proceed with edits only on explicit instruction.

package/hooks/blocking/precommit_code_rules_gate.py

@@ -0,0 +1,197 @@
+"""PreToolUse hook that runs the staged CODE_RULES gate before git commit.
+
+Intercepts Bash `git commit` invocations (including `git -C <path> commit`),
+resolves the repository root, and runs the shared code_rules_gate engine in
+``--staged`` mode over the staged files. A commit that would introduce
+CODE_RULES violations is denied with the gate's file:line report so the
+violations surface before the commit instead of stalling converge loops at
+commit time. Non-commit commands, repositories with no staged Python files,
+and clean staged changes pass through silently. A gate-engine failure denies
+the commit with the failure detail — the gate never fails open.
+"""
+
+import json
+import re
+import subprocess
+import sys
+from pathlib import Path
+
+_blocking_dir = str(Path(__file__).resolve().parent)
+if _blocking_dir not in sys.path:
+    sys.path.insert(0, _blocking_dir)
+_hooks_dir = str(Path(__file__).resolve().parent.parent)
+if _hooks_dir not in sys.path:
+    sys.path.insert(0, _hooks_dir)
+
+from block_main_commit import (  # noqa: E402
+    extract_git_working_directory,
+    is_commit_command,
+    parse_bash_command_from_stdin,
+    resolve_directory,
+)
+from hooks_constants.precommit_code_rules_gate_constants import (  # noqa: E402
+    ALL_GIT_REPOSITORY_ROOT_COMMAND,
+    ALL_STAGED_PYTHON_FILES_COMMAND,
+    GATE_RELATIVE_PATH,
+    GATE_TIMEOUT_SECONDS,
+    GIT_COMMAND_TIMEOUT_SECONDS,
+    GIT_DASH_C_COMMIT_PATTERN,
+)
+
+
+def is_git_commit_invocation(bash_command: str) -> bool:
+    """Report whether *bash_command* runs a git commit.
+
+    Matches both the plain ``git commit`` substring form and the
+    ``git -C <path> commit`` form, where the directory flag sits between
+    the two words.
+
+    Args:
+        bash_command: The Bash tool command string from the hook payload.
+
+    Returns:
+        True when the command invokes git commit; False otherwise.
+    """
+    if is_commit_command(bash_command):
+        return True
+    return re.search(GIT_DASH_C_COMMIT_PATTERN, bash_command) is not None
+
+
+def resolve_repository_root(working_directory: str | None) -> Path | None:
+    """Resolve the git repository root for the commit's working directory.
+
+    Args:
+        working_directory: Directory the commit runs in, or None for the
+            hook's current working directory.
+
+    Returns:
+        The repository root path, or None when the directory is not inside
+        a git repository or git is unavailable.
+    """
+    try:
+        completed_process = subprocess.run(
+            list(ALL_GIT_REPOSITORY_ROOT_COMMAND),
+            capture_output=True,
+            text=True,
+            timeout=GIT_COMMAND_TIMEOUT_SECONDS,
+            cwd=working_directory,
+        )
+    except (subprocess.TimeoutExpired, FileNotFoundError, OSError):
+        return None
+    if completed_process.returncode != 0:
+        return None
+    top_level_text = completed_process.stdout.strip()
+    if not top_level_text:
+        return None
+    return Path(top_level_text)
+
+
+def list_staged_python_files(repository_root: Path) -> list[str]:
+    """List repository-relative paths of staged Python files.
+
+    Args:
+        repository_root: Repository root used as the git working directory.
+
+    Returns:
+        Repository-relative paths of Python files staged for add, copy,
+        modify, or rename. Empty when the listing command fails — the
+        caller then allows the commit because git itself will surface the
+        repository problem.
+    """
+    try:
+        completed_process = subprocess.run(
+            list(ALL_STAGED_PYTHON_FILES_COMMAND),
+            capture_output=True,
+            text=True,
+            timeout=GIT_COMMAND_TIMEOUT_SECONDS,
+            cwd=str(repository_root),
+        )
+    except (subprocess.TimeoutExpired, FileNotFoundError, OSError):
+        return []
+    if completed_process.returncode != 0:
+        return []
+    return [
+        each_line.strip()
+        for each_line in completed_process.stdout.splitlines()
+        if each_line.strip()
+    ]
+
+
+def run_staged_gate(repository_root: Path) -> tuple[int, str]:
+    """Run the shared code_rules_gate engine in staged mode.
+
+    Args:
+        repository_root: Repository root passed to the gate's --repo-root.
+
+    Returns:
+        Tuple of the gate exit code and its stderr report. A missing gate
+        script or a gate timeout returns a non-zero code with an
+        explanatory message so the commit is denied rather than waved
+        through on infrastructure failure.
+    """
+    gate_path = Path(__file__).resolve().parents[2] / GATE_RELATIVE_PATH
+    if not gate_path.is_file():
+        return 1, f"precommit_code_rules_gate: gate engine missing at {gate_path}"
+    try:
+        completed_process = subprocess.run(
+            [
+                sys.executable,
+                str(gate_path),
+                "--repo-root",
+                str(repository_root),
+                "--staged",
+            ],
+            capture_output=True,
+            text=True,
+            encoding="utf-8",
+            errors="replace",
+            timeout=GATE_TIMEOUT_SECONDS,
+        )
+    except subprocess.TimeoutExpired:
+        return 1, (
+            f"precommit_code_rules_gate: gate engine timed out after {GATE_TIMEOUT_SECONDS}s"
+        )
+    return completed_process.returncode, completed_process.stderr
+
+
+def build_denial_response(gate_report: str) -> dict:
+    """Build the PreToolUse deny payload carrying the gate report.
+
+    Args:
+        gate_report: The gate's stderr report listing file:line violations.
+
+    Returns:
+        The hookSpecificOutput deny mapping for the PreToolUse protocol.
+    """
+    denial_reason = (
+        f"BLOCKED: staged files violate CODE_RULES; fix before committing.\n{gate_report.strip()}"
+    )
+    return {
+        "hookSpecificOutput": {
+            "hookEventName": "PreToolUse",
+            "permissionDecision": "deny",
+            "permissionDecisionReason": denial_reason,
+        }
+    }
+
+
+def main() -> None:
+    """Gate git commits on the staged CODE_RULES report."""
+    bash_command = parse_bash_command_from_stdin()
+    if not is_git_commit_invocation(bash_command):
+        sys.exit(0)
+    working_directory = resolve_directory(extract_git_working_directory(bash_command))
+    repository_root = resolve_repository_root(working_directory)
+    if repository_root is None:
+        sys.exit(0)
+    if not list_staged_python_files(repository_root):
+        sys.exit(0)
+    gate_exit_code, gate_report = run_staged_gate(repository_root)
+    if gate_exit_code == 0:
+        sys.exit(0)
+    print(json.dumps(build_denial_response(gate_report)))
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

package/hooks/blocking/test_precommit_code_rules_gate.py

@@ -0,0 +1,126 @@
+"""Behavior tests for the precommit_code_rules_gate PreToolUse hook.
+
+Each test builds a real git repository in a temporary directory, stages
+real files, and runs the hook script as a subprocess with a PreToolUse
+JSON payload on stdin — the exact production invocation path.
+"""
+
+import json
+import subprocess
+import sys
+from pathlib import Path
+
+HOOK_PATH = Path(__file__).resolve().parent / "precommit_code_rules_gate.py"
+
+CLEAN_MODULE_SOURCE = '''"""Increment helper used by the precommit gate tests."""
+
+
+def add_one(number: int) -> int:
+    """Return *number* plus one.
+
+    Args:
+        number: The integer to increment.
+
+    Returns:
+        The incremented integer.
+    """
+    return number + 1
+'''
+
+VIOLATING_MODULE_SOURCE = '''"""Module carrying a banned identifier for the precommit gate tests."""
+
+
+def compute_total() -> int:
+    """Return a fixed total.
+
+    Returns:
+        The fixed total.
+    """
+    result = 1
+    return result
+'''
+
+
+def run_git(repository_root: Path, *git_arguments: str) -> None:
+    subprocess.run(
+        ["git", "-C", str(repository_root), *git_arguments],
+        check=True,
+        capture_output=True,
+    )
+
+
+def initialize_repository(repository_root: Path) -> None:
+    run_git(repository_root, "init")
+    run_git(repository_root, "config", "user.email", "tests@example.com")
+    run_git(repository_root, "config", "user.name", "Gate Tests")
+    run_git(repository_root, "commit", "--allow-empty", "-m", "initial")
+
+
+def stage_file(repository_root: Path, relative_name: str, source_text: str) -> None:
+    (repository_root / relative_name).write_text(source_text, encoding="utf-8")
+    run_git(repository_root, "add", relative_name)
+
+
+def run_hook(bash_command: str, working_directory: Path) -> subprocess.CompletedProcess[str]:
+    payload = json.dumps({"tool_input": {"command": bash_command}})
+    return subprocess.run(
+        [sys.executable, str(HOOK_PATH)],
+        input=payload,
+        capture_output=True,
+        text=True,
+        cwd=str(working_directory),
+        timeout=120,
+    )
+
+
+def parse_denial(hook_stdout: str) -> dict:
+    return json.loads(hook_stdout)["hookSpecificOutput"]
+
+
+def test_non_commit_command_passes_through(tmp_path: Path) -> None:
+    initialize_repository(tmp_path)
+    completed_hook = run_hook("git status", tmp_path)
+    assert completed_hook.returncode == 0
+    assert completed_hook.stdout.strip() == ""
+
+
+def test_commit_with_clean_staged_python_file_is_allowed(tmp_path: Path) -> None:
+    initialize_repository(tmp_path)
+    stage_file(tmp_path, "incrementer.py", CLEAN_MODULE_SOURCE)
+    completed_hook = run_hook("git commit -m add", tmp_path)
+    assert completed_hook.returncode == 0
+    assert completed_hook.stdout.strip() == ""
+
+
+def test_commit_with_violating_staged_file_is_blocked(tmp_path: Path) -> None:
+    initialize_repository(tmp_path)
+    stage_file(tmp_path, "totals.py", VIOLATING_MODULE_SOURCE)
+    completed_hook = run_hook("git commit -m add", tmp_path)
+    assert completed_hook.returncode == 0
+    denial = parse_denial(completed_hook.stdout)
+    assert denial["permissionDecision"] == "deny"
+    assert "totals.py" in denial["permissionDecisionReason"]
+    assert "Line" in denial["permissionDecisionReason"]
+
+
+def test_git_dash_c_commit_form_is_blocked(tmp_path: Path) -> None:
+    repository_root = tmp_path / "repo"
+    repository_root.mkdir()
+    initialize_repository(repository_root)
+    stage_file(repository_root, "totals.py", VIOLATING_MODULE_SOURCE)
+    elsewhere = tmp_path / "elsewhere"
+    elsewhere.mkdir()
+    quoted_root = str(repository_root)
+    completed_hook = run_hook(f'git -C "{quoted_root}" commit -m add', elsewhere)
+    assert completed_hook.returncode == 0
+    denial = parse_denial(completed_hook.stdout)
+    assert denial["permissionDecision"] == "deny"
+    assert "totals.py" in denial["permissionDecisionReason"]
+
+
+def test_commit_with_no_staged_python_files_is_allowed(tmp_path: Path) -> None:
+    initialize_repository(tmp_path)
+    stage_file(tmp_path, "notes.md", "# Notes\n")
+    completed_hook = run_hook("git commit -m docs", tmp_path)
+    assert completed_hook.returncode == 0
+    assert completed_hook.stdout.strip() == ""

package/hooks/hooks.json

@@ -105,6 +105,11 @@
             "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/block_main_commit.py",
             "timeout": 15
           },
+          {
+            "type": "command",
+            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/precommit_code_rules_gate.py",
+            "timeout": 30
+          },
           {
             "type": "command",
             "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/pr_description_enforcer.py",

package/hooks/hooks_constants/precommit_code_rules_gate_constants.py

@@ -0,0 +1,26 @@
+"""Constants for the precommit_code_rules_gate PreToolUse hook.
+
+Command parsing, git timeouts, and the staged-gate invocation surface used
+to run the shared code_rules_gate engine before a git commit.
+"""
+
+from pathlib import Path
+
+GIT_DASH_C_COMMIT_PATTERN: str = r"git\s+-C\s+[\"']?[^\"';&|]+?[\"']?\s+commit\b"
+GIT_COMMAND_TIMEOUT_SECONDS: int = 5
+GATE_TIMEOUT_SECONDS: int = 25
+GATE_RELATIVE_PATH: Path = Path("_shared") / "pr-loop" / "scripts" / "code_rules_gate.py"
+ALL_STAGED_PYTHON_FILES_COMMAND: tuple[str, ...] = (
+    "git",
+    "diff",
+    "--cached",
+    "--name-only",
+    "--diff-filter=ACMR",
+    "--",
+    "*.py",
+)
+ALL_GIT_REPOSITORY_ROOT_COMMAND: tuple[str, ...] = (
+    "git",
+    "rev-parse",
+    "--show-toplevel",
+)

package/package.json

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

package/skills/_shared/pr-loop/prompts/pr-consistency-audit.xml

@@ -196,6 +196,7 @@
   <constraints>
     <constraint>Read every file completely. Do not skim. Do not skip any file or any line.</constraint>
     <constraint>Write findings to the temp file immediately. Do not accumulate them in memory and batch-write at the end. You will forget things.</constraint>
+    <constraint>Double-quote every path in shell commands and write paths with forward slashes (e.g. C:/Users/...), even on Windows.</constraint>
     <constraint>Every finding must cite the file and line of the problem AND the file and line of the evidence that proves it is a problem. No floating claims.</constraint>
     <constraint>When two files contradict each other, flag BOTH files. Do not guess which is correct unless a canonical source resolves it.</constraint>
     <constraint>If you cannot determine the correct value or form, flag the inconsistency and mark it "unresolvable — no canonical source found". Do not guess.</constraint>

package/skills/_shared/pr-loop/scripts/_path_resolver.py

@@ -124,7 +124,7 @@ def per_pr_workspace(
     slug = slugify_pr_identity(owner, repo, pr_number)
     return PerPrWorkspace(
         worktree=pr_workspace_dir / WORKTREE_DIRNAME,
-        diff_patch_template=str(pr_workspace_dir / slug / DIFF_PATCH_TEMPLATE),
+        diff_patch_template=(pr_workspace_dir / slug / DIFF_PATCH_TEMPLATE).as_posix(),
         outcome_xml_template=OUTCOME_XML_TEMPLATE,
         fix_outcome_xml_template=FIX_OUTCOME_XML_TEMPLATE,
     )

package/skills/_shared/pr-loop/scripts/build_audit_prompt.py

@@ -62,14 +62,14 @@ def build_audit_prompt_xml(
     SubElement(context, "pr_number").text = str(pr_number)
     SubElement(context, "head_ref").text = head_ref
     SubElement(context, "base_ref").text = base_ref
-    SubElement(context, "worktree_path").text = str(worktree_path)
-    SubElement(context, "run_temp_dir").text = str(run_temp_dir)
+    SubElement(context, "worktree_path").text = worktree_path.as_posix()
+    SubElement(context, "run_temp_dir").text = run_temp_dir.as_posix()
 
     scope = SubElement(root, "scope")
     scope.text = (
         f"Audit the full diff of {owner}/{repo}#{pr_number} "
         f"({head_ref} against {base_ref}) for CODE_RULES violations, "
-        f"bugs, and anti-patterns. Work in {worktree_path}."
+        f"bugs, and anti-patterns. Work in {worktree_path.as_posix()}."
     )
 
     bug_categories = SubElement(root, "bug_categories")

package/skills/_shared/pr-loop/scripts/build_fix_prompt.py

@@ -63,7 +63,7 @@ def build_fix_prompt_xml(
     SubElement(context, "pr_number").text = str(pr_number)
     SubElement(context, "head_ref").text = head_ref
     SubElement(context, "base_ref").text = base_ref
-    SubElement(context, "worktree_path").text = str(worktree_path)
+    SubElement(context, "worktree_path").text = worktree_path.as_posix()
 
     bugs_elem = SubElement(root, "bugs")
     if isinstance(findings_data, list):

package/skills/_shared/pr-loop/scripts/init_loop_state.py

@@ -124,7 +124,7 @@ def main(
             arguments.is_multi_pr if is_multi_pr is None else is_multi_pr
         ),
     )
-    print(state_path)
+    print(state_path.as_posix())
     return 0
 
 

package/skills/_shared/pr-loop/scripts/skills_pr_loop_constants/path_resolver_constants.py

@@ -26,6 +26,8 @@ ALL_AUDIT_CONSTRAINT_TEXTS = [
     "Every finding must cite file:line.",
     "Document each finding with severity, file, line, and suggested fix.",
     "Read each file in the diff before reporting on it.",
+    "Double-quote every path in shell commands and write paths with "
+    "forward slashes (e.g. C:/Users/...), even on Windows.",
 ]
 
 ALL_AUDIT_CATEGORY_ENTRIES = [
@@ -71,6 +73,8 @@ ALL_FIX_CONSTRAINT_TEXTS = [
     "Every fix must have a corresponding test.",
     "Remove deprecated code directly and update all call sites.",
     "Handle each error case with a named exception type.",
+    "Double-quote every path in shell commands and write paths with "
+    "forward slashes (e.g. C:/Users/...), even on Windows.",
 ]
 
 XML_PRETTY_INDENT = "  "

package/skills/_shared/pr-loop/scripts/teardown_worktrees.py

@@ -164,7 +164,7 @@ def main(all_arguments: list[str]) -> int:
         run_temp_dir=run_temp_dir,
         all_pr_entries=all_pr_entries,
     )
-    print(f"Removed {removed_count} worktree(s), cleaned {run_temp_dir}")
+    print(f"Removed {removed_count} worktree(s), cleaned {run_temp_dir.as_posix()}")
     return 0
 
 

package/skills/_shared/pr-loop/scripts/test__path_resolver.py

@@ -47,7 +47,17 @@ def test_per_pr_workspace_diff_patch_template_carries_loop_placeholder() -> None
     workspace = path_resolver.per_pr_workspace(run_temp_dir, "owner", "repo", 7)
     rendered = workspace.diff_patch_template.format(loop=3)
     assert rendered.endswith("loop-3.patch")
-    assert "owner-repo-pr-7" in rendered.replace("\\", "/")
+    assert "owner-repo-pr-7" in rendered
+
+
+def test_per_pr_workspace_diff_patch_template_uses_forward_slashes() -> None:
+    run_temp_dir = Path("C:/Users/jon/AppData/Local/Temp/bugteam-pr-376")
+    workspace = path_resolver.per_pr_workspace(run_temp_dir, "owner", "repo", 376)
+    assert "\\" not in workspace.diff_patch_template
+    assert workspace.diff_patch_template == (
+        "C:/Users/jon/AppData/Local/Temp/bugteam-pr-376/"
+        "pr-376/owner-repo-pr-376/loop-{loop}.patch"
+    )
 
 
 def test_per_pr_workspace_is_frozen() -> None:

package/skills/_shared/pr-loop/scripts/test_build_audit_prompt.py

@@ -60,6 +60,30 @@ def _build_audit_root() -> Element:
     )
 
 
+def test_context_and_scope_render_paths_with_forward_slashes() -> None:
+    root = build_audit_prompt.build_audit_prompt_xml(
+        owner="jl-cmd",
+        repo="claude-code-config",
+        pr_number=376,
+        loop=1,
+        head_ref="feat/branch",
+        base_ref="main",
+        worktree_path=Path("C:/Users/jon/AppData/Local/Temp/bugteam-pr-376/worktree"),
+        run_temp_dir=Path("C:/Users/jon/AppData/Local/Temp/bugteam-pr-376"),
+    )
+    context = root.find("context")
+    assert context is not None
+    worktree_text = context.findtext("worktree_path")
+    run_temp_text = context.findtext("run_temp_dir")
+    assert worktree_text == "C:/Users/jon/AppData/Local/Temp/bugteam-pr-376/worktree"
+    assert run_temp_text == "C:/Users/jon/AppData/Local/Temp/bugteam-pr-376"
+    scope = root.find("scope")
+    assert scope is not None
+    assert scope.text is not None
+    assert "\\" not in scope.text
+    assert "C:/Users/jon/AppData/Local/Temp/bugteam-pr-376/worktree" in scope.text
+
+
 def test_bug_categories_carry_ids_a_through_p_in_order() -> None:
     root = _build_audit_root()
     bug_categories = root.find("bug_categories")

package/skills/_shared/pr-loop/scripts/test_build_fix_prompt.py

@@ -0,0 +1,49 @@
+"""Tests for build_fix_prompt's agent-facing path rendering."""
+
+from __future__ import annotations
+
+import importlib.util
+import json
+import sys
+from pathlib import Path
+from types import ModuleType
+
+_SCRIPTS_DIR = Path(__file__).resolve().parent
+if str(_SCRIPTS_DIR) not in sys.path:
+    sys.path.insert(0, str(_SCRIPTS_DIR))
+
+
+def _load_build_fix_prompt() -> ModuleType:
+    module_path = _SCRIPTS_DIR / "build_fix_prompt.py"
+    spec = importlib.util.spec_from_file_location("build_fix_prompt", module_path)
+    assert spec is not None
+    assert spec.loader is not None
+    module = importlib.util.module_from_spec(spec)
+    sys.modules["build_fix_prompt"] = module
+    spec.loader.exec_module(module)
+    return module
+
+
+build_fix_prompt = _load_build_fix_prompt()
+
+
+def test_context_worktree_path_renders_with_forward_slashes(tmp_path: Path) -> None:
+    findings_json_path = tmp_path / "findings.json"
+    findings_json_path.write_text(
+        json.dumps([{"severity": "P1", "file": "a.py", "line": 1}]),
+        encoding="utf-8",
+    )
+    root = build_fix_prompt.build_fix_prompt_xml(
+        owner="jl-cmd",
+        repo="claude-code-config",
+        pr_number=376,
+        loop=1,
+        head_ref="feat/branch",
+        base_ref="main",
+        worktree_path=Path("C:/Users/jon/AppData/Local/Temp/bugteam-pr-376/worktree"),
+        findings_json_path=findings_json_path,
+    )
+    context = root.find("context")
+    assert context is not None
+    worktree_text = context.findtext("worktree_path")
+    assert worktree_text == "C:/Users/jon/AppData/Local/Temp/bugteam-pr-376/worktree"

package/skills/_shared/pr-loop/scripts/test_init_loop_state.py

@@ -46,3 +46,26 @@ def test_create_loop_state_writes_state_under_typed_worktree(
     written_state = json.loads(state_path.read_text(encoding="utf-8"))
     assert written_state["starting_sha"] == "abc1234"
     assert written_state["loop_count"] == 0
+
+
+def test_main_prints_state_path_with_forward_slashes(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    path_resolver_module = init_loop_state.resolve_run_temp_dir.__globals__["tempfile"]
+    monkeypatch.setattr(path_resolver_module, "gettempdir", lambda: str(tmp_path))
+    exit_code = init_loop_state.main(
+        [
+            "--pr-number",
+            "422",
+            "--head-ref",
+            "feat/branch",
+            "--starting-sha",
+            "abc1234",
+        ]
+    )
+    assert exit_code == 0
+    printed_path = capsys.readouterr().out.strip()
+    assert "\\" not in printed_path
+    assert printed_path.endswith("worktree/loop-state.json")

package/skills/autoconverge/SKILL.md

@@ -68,6 +68,17 @@ completion. Watch live progress with `/workflows`.
 The workflow returns
 `{ converged, rounds, finalSha, blocker }`.
 
+## Budget-aware round boundaries
+
+The workflow's `budget` API is the pacing signal: when a usage target is
+set, `converge.mjs` checks `budget.remaining()` before each round and
+stops at the round boundary when one full round (three parallel lenses +
+one fix commit + re-verify) does not fit. On a budget stop the workflow
+returns `blocker: "budget"` with the run id; resume with
+`Workflow({scriptPath, resumeFromRunId})` — completed rounds replay from
+the journal. Never start a round the budget cannot finish: a half-run
+round records nothing resumable and replays dirty.
+
 ## Teardown (on workflow completion)
 
 1. **When `converged` is true:** rewrite the PR description and clean the

package/skills/pr-converge/SKILL.md

@@ -43,6 +43,27 @@ working directory routes into the PR's repo for local work and returns to
 the session worktree before teardown. See
 [`reference/per-tick.md` § Step 1.5](reference/per-tick.md).
 
+## Budget-aware tick boundaries
+
+Before starting any tick, estimate whether the remaining session/usage
+budget covers one full clean tick (worst case: a BUGBOT fetch + a
+full-diff CODE_REVIEW + a fix commit + replies). If it does not, do not
+start the tick. Stop at the current tick boundary: write updated state to
+`$CLAUDE_JOB_DIR/pr-converge-state.json`, then report the exact resume
+command (`/pr-converge <PR URL>`) and the persisted `phase`/`tick_count`.
+A tick cut off mid-flight poisons the resume state — clean SHAs recorded
+against work that never landed — so an unstarted tick is always cheaper
+than a half-finished one.
+
+## Findings discipline
+
+Every finding, reply, and report states verified facts only — no hedging
+language (`likely`, `probably`, `should`, `appears to`). Verify each
+claim against the code on `current_head` before stating it; the
+anti-hallucination Stop hook rejects hedged output, forcing a rework
+pass. A claim that cannot be verified is reported as unverified, not
+softened.
+
 ## State persistence
 
 Single-PR mode persists loop state to `$CLAUDE_JOB_DIR/pr-converge-state.json`.
@@ -354,6 +375,7 @@ round as converged. This rule holds every tick, every loop, every PR.
       `python "$HOME/.claude/skills/bugteam/scripts/revoke_project_claude_permissions.py"`
 
 - [ ] **Step 11: Print final report**
+      Print this block verbatim — no paraphrase, no extra commentary:
       ```
       /pr-converge exit: converged
       Loops: <N>