claude-dev-env 1.55.2 → 1.57.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.57.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

@@ -66,7 +66,19 @@ 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 }`.
+`{ converged, rounds, finalSha, blocker, standardsNote }`. Every agent the
+workflow spawns runs on Fable 5 (`model: 'fable'`).
+
+## 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)
 
@@ -85,6 +97,7 @@ The workflow returns
    Rounds: <N>
    Final commit: <finalSha>
    Blocker: <blocker>        # only when blocked
+   Standards: <standardsNote> # only when a round deferred code-standard findings
    ```
 
 ## What the workflow does each round
@@ -100,6 +113,12 @@ run ends short of ready. Hard-won failure lessons live in
   `clean-coder` applies all fixes in a single commit, pushes, replies to and
   resolves any bot threads; re-verify next round on the new HEAD. When all
   three are clean on a stable HEAD, post the CLEAN bugteam audit artifact.
+  A round whose findings are ALL code-standard violations (pure CODE_RULES/style,
+  no behavioral impact) passes for convergence purposes: the workflow files a
+  follow-up issue listing the findings, opens a draft environment-hardening PR
+  (hooks/rules that block those violation classes at Write/Edit time), resolves
+  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.
 - **Convergence check:** `check_convergence.py` is the authoritative gate; on a

package/skills/autoconverge/workflow/converge.mjs

@@ -44,11 +44,12 @@ const LENS_SCHEMA = {
           file: { type: 'string' },
           line: { type: 'integer' },
           severity: { type: 'string', enum: ['P0', 'P1', 'P2'] },
+          category: { type: 'string', enum: ['bug', 'code-standard'], description: 'code-standard for pure CODE_RULES/style violations with no behavioral impact; bug otherwise' },
           title: { type: 'string' },
           detail: { type: 'string' },
           replyToCommentId: { type: ['integer', 'null'], description: 'GitHub review comment id to reply to and resolve, or null when the finding has no thread' },
         },
-        required: ['file', 'line', 'severity', 'title', 'detail', 'replyToCommentId'],
+        required: ['file', 'line', 'severity', 'category', 'title', 'detail', 'replyToCommentId'],
       },
     },
   },
@@ -415,7 +416,7 @@ async function resolveHead() {
     `Print the current HEAD SHA of ${prCoordinates}. Run exactly:\n` +
       `gh api repos/${input.owner}/${input.repo}/pulls/${input.prNumber} --jq .head.sha\n` +
       `Return the full 40-character SHA in the sha field. Do not modify any files.`,
-    { label: 'resolve-head', phase: 'Converge', schema: HEAD_SCHEMA, agentType: 'Explore' },
+    { model: 'fable', label: 'resolve-head', phase: 'Converge', schema: HEAD_SCHEMA, agentType: 'Explore' },
   )
   return head?.sha
 }
@@ -433,7 +434,7 @@ function prefetchMainForRound() {
     `Refresh the base ref for ${prCoordinates} so the parallel review lenses can diff against an up-to-date origin/main without each running its own fetch. Run exactly:\n` +
       `git fetch origin main\n` +
       `Do not edit, commit, push, rebase, or modify any files — fetch only.`,
-    { label: 'prefetch-main', phase: 'Converge', agentType: 'Explore' },
+    { model: 'fable', label: 'prefetch-main', phase: 'Converge', agentType: 'Explore' },
   )
 }
 
@@ -461,8 +462,8 @@ function runBugbotLens(head) {
       `   - If a clean review exists on HEAD -> return clean.\n` +
       `4. No review yet on HEAD: check_bugbot_ci.py --check-active. If active (exit 0), poll: repeat check_bugbot_ci.py --check-clean / --check-active every 60 seconds (delay each iteration with "sleep 60", or the PowerShell alternative "Start-Sleep -Seconds 60") for up to 25 iterations, then re-fetch the review. If not active (exit 1), post the literal comment "bugbot run" (no @mention, no other text) via python "${CONFIG.sharedScripts}/post_fix_reply.py" --owner ${input.owner} --repo ${input.repo} --pr-number ${input.prNumber} --body "bugbot run", delay 8 seconds with "sleep 8" (PowerShell alternative "Start-Sleep -Seconds 8"), then poll as above.\n` +
       `5. If after the full poll budget Bugbot has neither a check run nor a review on HEAD -> return {sha:${'`'}${head}${'`'}, clean:true, down:true, findings:[]} (treat as down).\n\n` +
-      `Scope is the whole PR; you are only reading Bugbot's own output here. Return strictly the schema.`,
-    { label: 'lens:bugbot', phase: 'Converge', schema: LENS_SCHEMA },
+      `Scope is the whole PR; you are only reading Bugbot's own output here. For each finding set category: 'code-standard' when it is a pure CODE_RULES/style violation (naming, comments, type hints, magic values, structure) with no behavioral impact; 'bug' otherwise. Return strictly the schema.`,
+    { model: 'fable', label: 'lens:bugbot', phase: 'Converge', schema: LENS_SCHEMA },
   )
 }
 
@@ -477,8 +478,8 @@ function runCodeReviewLens(head) {
     `You are the code-review lens for ${prCoordinates}, HEAD ${head}.\n\n` +
       `Review the FULL origin/main...HEAD diff — every file the PR touches. Do NOT delta-scope to recent commits or to a single file. The workflow already fetched origin/main this round, so do NOT run git fetch; run git diff --name-only origin/main...HEAD to enumerate the changed files, then review the complete diff of each.\n\n` +
       `Apply correctness-focused review: real bugs, broken logic, incorrect error handling, data-loss or security risks, contract mismatches, and reuse/simplification problems. Report only defensible findings with concrete file:line evidence.\n\n` +
-      `Do NOT edit, commit, or push — reporting only. Return strictly the schema: clean=true with empty findings when the diff is sound, otherwise one entry per finding (severity P0/P1/P2, replyToCommentId=null since these are not yet GitHub threads). Set sha=${'`'}${head}${'`'}, down=false.`,
-    { label: 'lens:code-review', phase: 'Converge', schema: LENS_SCHEMA, agentType: 'code-quality-agent' },
+      `Do NOT edit, commit, or push — reporting only. Return strictly the schema: clean=true with empty findings when the diff is sound, otherwise one entry per finding (severity P0/P1/P2; category 'code-standard' for pure CODE_RULES/style violations with no behavioral impact, 'bug' otherwise; replyToCommentId=null since these are not yet GitHub threads). Set sha=${'`'}${head}${'`'}, down=false.`,
+    { model: 'fable', label: 'lens:code-review', phase: 'Converge', schema: LENS_SCHEMA, agentType: 'code-quality-agent' },
   )
 }
 
@@ -493,8 +494,8 @@ function runAuditLens(head) {
     `You are the second-opinion bug-audit lens for ${prCoordinates}, HEAD ${head}.\n\n` +
       `Read the audit rubric at ${CONFIG.bugteamRubric} and apply its categories (A through P) against the FULL origin/main...HEAD diff — every file the PR touches, never a delta cut. The workflow already fetched origin/main this round, so do NOT run git fetch; run git diff --name-only origin/main...HEAD first to enumerate scope.\n\n` +
       `This is a clean-room audit: assume nothing from other lenses. Report only findings backed by concrete file:line evidence. Do NOT edit, commit, or push.\n\n` +
-      `Return strictly the schema: clean=true with empty findings when the diff passes every category, otherwise one entry per finding (severity P0/P1/P2, replyToCommentId=null). Set sha=${'`'}${head}${'`'}, down=false.`,
-    { label: 'lens:bug-audit', phase: 'Converge', schema: LENS_SCHEMA, agentType: 'code-quality-agent' },
+      `Return strictly the schema: clean=true with empty findings when the diff passes every category, otherwise one entry per finding (severity P0/P1/P2; category 'code-standard' for pure CODE_RULES/style violations with no behavioral impact, 'bug' otherwise; replyToCommentId=null). Set sha=${'`'}${head}${'`'}, down=false.`,
+    { model: 'fable', label: 'lens:bug-audit', phase: 'Converge', schema: LENS_SCHEMA, agentType: 'code-quality-agent' },
   )
 }
 
@@ -532,7 +533,7 @@ function applyFixes(head, findings, sourceLabel) {
       `- When you commit and push a fix: newSha=the new HEAD SHA after your push, pushed=true, resolvedWithoutCommit=false.\n` +
       `- When every finding was already addressed so no code change is needed — yet you still resolved each GitHub review thread above: newSha=${head} (the unchanged HEAD), pushed=false, resolvedWithoutCommit=true. Only set this when every thread that carries a comment id is resolved; otherwise the round is treated as stalled.\n` +
       `Always include a one-line summary.`,
-    { label: `fix:${sourceLabel}`, phase: 'Converge', schema: FIX_SCHEMA, agentType: 'clean-coder' },
+    { model: 'fable', label: `fix:${sourceLabel}`, phase: 'Converge', schema: FIX_SCHEMA, agentType: 'clean-coder' },
   )
 }
 
@@ -548,7 +549,7 @@ function postCleanAudit(head) {
       `Write an empty findings file: create a temp file containing exactly [] (an empty JSON array). Then run:\n` +
       `python "${CONFIG.prLoopScripts}/post_audit_thread.py" --skill bugteam --owner ${input.owner} --repo ${input.repo} --pr-number ${input.prNumber} --commit ${head} --state CLEAN --findings-json <temp-file>\n` +
       `Run the script with --help first if any flag name differs. This posts the APPROVE review body that check_convergence.py reads for the bugteam gate. Do not edit code, commit, or push.`,
-    { label: 'post-clean-audit', phase: 'Converge', agentType: 'general-purpose' },
+    { model: 'fable', label: 'post-clean-audit', phase: 'Converge', agentType: 'general-purpose' },
   )
 }
 
@@ -565,10 +566,10 @@ function runCopilotGate(head) {
       `   gh api --method POST repos/${input.owner}/${input.repo}/pulls/${input.prNumber}/requested_reviewers -f 'reviewers[]=copilot-pull-request-reviewer[bot]'\n` +
       `2. Poll for Copilot's review on HEAD ${head}: up to ${CONFIG.copilotMaxPolls} attempts, 360 seconds apart (delay each attempt with "sleep 360", or the PowerShell alternative "Start-Sleep -Seconds 360"). Each attempt: python "${CONFIG.sharedScripts}/fetch_copilot_reviews.py" --owner ${input.owner} --repo ${input.repo} --pr-number ${input.prNumber} for the top-level review state, plus gh api "repos/${input.owner}/${input.repo}/pulls/${input.prNumber}/comments" --paginate --slurp for inline comment ids (Copilot's login contains "copilot", case-insensitive). Only count entries whose commit_id starts with ${head}.\n` +
       `   - Copilot review present and clean/approved on HEAD -> return {sha:${'`'}${head}${'`'}, clean:true, findings:[], blocker:null}.\n` +
-      `   - Copilot findings on HEAD -> return them (each with its inline comment id in replyToCommentId), clean:false, blocker:null.\n` +
+      `   - Copilot findings on HEAD -> return them (each with its inline comment id in replyToCommentId; category 'code-standard' for pure CODE_RULES/style violations with no behavioral impact, 'bug' otherwise), clean:false, blocker:null.\n` +
       `   - No review after ${CONFIG.copilotMaxPolls} attempts -> return {sha:${'`'}${head}${'`'}, clean:false, findings:[], blocker:"Copilot did not surface a review on HEAD after ${CONFIG.copilotMaxPolls} polls"}.\n\n` +
       `Return strictly the schema.`,
-    { label: 'copilot-gate', phase: 'Copilot gate', schema: COPILOT_SCHEMA },
+    { model: 'fable', label: 'copilot-gate', phase: 'Copilot gate', schema: COPILOT_SCHEMA },
   )
 }
 
@@ -585,7 +586,7 @@ function checkConvergence(bugbotDown) {
       `Exit 0 -> every gate passed: return {pass:true, failures:[]}.\n` +
       `Exit 1 -> return {pass:false, failures:[<each printed FAIL line verbatim>]}.\n` +
       `Exit 2 -> retry once; if it still errors, return {pass:false, failures:["check_convergence gh error"]}.`,
-    { label: 'check-convergence', phase: 'Finalize', schema: CONVERGENCE_SCHEMA, agentType: 'Explore' },
+    { model: 'fable', label: 'check-convergence', phase: 'Finalize', schema: CONVERGENCE_SCHEMA, agentType: 'Explore' },
   )
 }
 
@@ -600,7 +601,7 @@ function markReady(head) {
       `1. Run: gh pr ready ${input.prNumber} --repo ${input.owner}/${input.repo}\n` +
       `2. Re-query the draft state: gh api repos/${input.owner}/${input.repo}/pulls/${input.prNumber} --jq .draft\n` +
       `Return {ready:true} only when step 2 prints false (the PR is no longer a draft). If step 1 errors or step 2 still prints true, return {ready:false}.`,
-    { label: 'mark-ready', phase: 'Finalize', schema: READY_SCHEMA, agentType: 'general-purpose' },
+    { model: 'fable', label: 'mark-ready', phase: 'Finalize', schema: READY_SCHEMA, agentType: 'general-purpose' },
   )
 }
 
@@ -623,7 +624,51 @@ function repairConvergence(head, failures) {
       `- PR not mergeable: rebase onto origin/main and force-push (git fetch origin main; git rebase origin/main; resolve conflicts; git push --force-with-lease).\n` +
       `- A dirty bot review or a still-pending requested reviewer: leave it; the next round re-runs that reviewer.\n` +
       `Make at most one commit for any code fix. Return the HEAD SHA after any push in newSha (the unchanged ${head} when nothing was pushed), pushed true/false, resolvedWithoutCommit=false (this gate already accepts an unchanged HEAD), and a one-line summary.`,
-    { label: 'repair-convergence', phase: 'Finalize', schema: FIX_SCHEMA, agentType: 'clean-coder' },
+    { model: 'fable', label: 'repair-convergence', phase: 'Finalize', schema: FIX_SCHEMA, agentType: 'clean-coder' },
+  )
+}
+
+/**
+ * Decide whether a review round surfaced ONLY code-standard violations — pure
+ * CODE_RULES/style findings with no behavioral impact. Such a round passes for
+ * convergence purposes: the violations are deferred to a follow-up fix issue
+ * (plus an environment-hardening PR) rather than blocking this PR.
+ * @param {Array<object>} findings deduped findings for the round
+ * @returns {boolean} true when every finding is category code-standard
+ */
+function isStandardsOnlyRound(findings) {
+  return findings.length > 0 && findings.every((each) => each.category === 'code-standard')
+}
+
+/**
+ * Defer a standards-only round: one agent files a GitHub issue listing every
+ * code-standard finding, opens a draft PR hardening the Claude environment
+ * (hooks/rules) so those violation classes are blocked before code is written,
+ * and replies to / resolves any GitHub threads the findings carry, noting the
+ * deferral. This PR's branch is never touched.
+ * @param {string} head PR HEAD SHA the findings were raised against
+ * @param {Array<object>} findings deduped code-standard-only findings
+ * @param {string} sourceLabel short description of where the findings came from
+ * @returns {Promise<string>} agent transcript (unused)
+ */
+function spawnStandardsFollowUp(head, findings, sourceLabel) {
+  const findingsBlock = findings
+    .map((each, position) => {
+      const eachThreadIds = collectFindingThreadIds(each)
+      const threadNote = eachThreadIds.length
+        ? `\n   (GitHub review comment ids: ${eachThreadIds.join(', ')})`
+        : ''
+      return `${position + 1}. [${each.severity}] ${each.file}:${each.line} — ${each.title}\n   ${each.detail}${threadNote}`
+    })
+    .join('\n')
+  return agent(
+    `A review round on ${prCoordinates}, HEAD ${head}, surfaced ONLY code-standard violations (CODE_RULES/style, no behavioral impact). The convergence run treats the round as passed and defers these to follow-up work, which you now create. Do NOT commit or push to the PR's own branch.\n\n` +
+      `Findings:\n${findingsBlock}\n\n` +
+      `1. Follow-up fix issue: file a GitHub issue on ${input.owner}/${input.repo} (gh issue create --body-file with a temp file) titled "Deferred code-standard fixes from PR #${input.prNumber}". The body references the PR and lists each finding with its file:line, severity, and detail. The issue carries the fix work; do not open a fix PR.\n` +
+      `2. Environment-hardening PR: in the Claude environment config repo (the repo owning ~/.claude hooks and rules — JonEcho/llm-settings for hooks, jl-cmd/claude-code-config for rules/skills; pick whichever owns the needed surface), create a branch and open a DRAFT PR that hardens hooks/rules so each violation class found here is blocked at Write/Edit time, before code is written or reviewed. Reference the issue from step 1 in the PR body.\n` +
+      `3. For each finding that carries a GitHub review comment id: post an inline reply via python "${CONFIG.sharedScripts}/post_fix_reply.py" --owner ${input.owner} --repo ${input.repo} --pr-number ${input.prNumber} --in-reply-to <id> --body "Code-standard-only finding — deferred to follow-up issue <url>." Then resolve the thread by its PRRT_ node id (GraphQL lookup on comment databaseId, then resolveReviewThread or the github MCP pull_request_review_write method=resolve_thread).\n\n` +
+      `Return a one-line summary naming the follow-up issue URL and the hardening PR URL.`,
+    { model: 'fable', label: `standards-followup:${sourceLabel}`, phase: 'Converge', agentType: 'clean-coder' },
   )
 }
 
@@ -633,6 +678,7 @@ let rounds = 0
 let iterations = 0
 let blocker = null
 let bugbotDown = input.bugbotDisabled || false
+let standardsNote = null
 
 while (iterations < CONFIG.maxIterations) {
   iterations += 1
@@ -657,6 +703,14 @@ while (iterations < CONFIG.maxIterations) {
       continue
     }
     const findings = roundOutcome.findings
+    if (isStandardsOnlyRound(findings)) {
+      log(`Round ${rounds}: ${findings.length} code-standard-only finding(s) — deferring to follow-up PRs and treating the round as passed`)
+      await spawnStandardsFollowUp(head, findings, 'converge-round')
+      standardsNote = `${findings.length} code-standard finding(s) deferred to a follow-up fix issue plus an environment-hardening PR — verify both land`
+      await postCleanAudit(head)
+      phase = 'COPILOT'
+      continue
+    }
     if (findings.length > 0) {
       log(`Round ${rounds}: ${findings.length} finding(s) — applying fixes`)
       const fixResult = await applyFixes(head, findings, 'converge-round')
@@ -693,6 +747,13 @@ while (iterations < CONFIG.maxIterations) {
       break
     }
     if (copilotOutcome.kind === 'fix') {
+      if (isStandardsOnlyRound(copilotOutcome.findings)) {
+        log(`Copilot raised ${copilotOutcome.findings.length} code-standard-only finding(s) — deferring to follow-up PRs and treating the gate as passed`)
+        await spawnStandardsFollowUp(head, copilotOutcome.findings, 'copilot')
+        standardsNote = `${copilotOutcome.findings.length} code-standard finding(s) deferred to a follow-up fix issue plus an environment-hardening PR — verify both land`
+        phase = 'FINALIZE'
+        continue
+      }
       log(`Copilot raised ${copilotOutcome.findings.length} finding(s) — fixing and re-converging`)
       const fixResult = await applyFixes(head, copilotOutcome.findings, 'copilot')
       const hadThreadBearingFinding = copilotOutcome.findings.some((each) => collectFindingThreadIds(each).length > 0)
@@ -722,7 +783,7 @@ while (iterations < CONFIG.maxIterations) {
       const readyResult = await markReady(head)
       const readyOutcome = classifyReadyOutcome(readyResult)
       if (readyOutcome.converged) {
-        return { converged: true, rounds, finalSha: head, blocker: null }
+        return { converged: true, rounds, finalSha: head, blocker: null, standardsNote }
       }
       blocker = readyOutcome.blocker
       break
@@ -739,4 +800,5 @@ return {
   rounds,
   finalSha: head,
   blocker: blocker || `iteration cap reached (${CONFIG.maxIterations})`,
+  standardsNote,
 }

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>