claude-dev-env 1.55.1 → 1.56.0

package/CLAUDE.md

@@ -41,6 +41,34 @@ Ask the subagent for a specific answer: "return the file:line where X is defined
 
 Reserve `Read`/`Grep`/`Glob` for files you will actually touch this turn. Compose subagent prompts via the protocol in `agent-spawn-protocol`.
 
+## Target Execution Workflow for Code Tasks
+
+Run every multi-step code task in two phases:
+
+1. **Coders** — one Sonnet agent per scoped assignment writes the code. A coder that hits a decision it can't reasonably solve consults the tool-less `fable-advisor` agent — which returns a plan, a correction, or a stop signal — and resumes. Source: Anthropic's advisor strategy (https://claude.com/blog/the-advisor-strategy).
+2. **Verification** — when the coders finish, the main session spawns the `fable-verifier` agent in a fresh context. It derives and runs the checks itself rather than trusting coder reports: the task's named gates, tests against baselines recorded before the coders ran, and a two-way diff-vs-assignment reading (every task item maps to a hunk, every hunk maps to a task item, nothing missing). A finding must cite a failing command or a named task item. Source: the fresh-context review step in Claude Code best practices (https://code.claude.com/docs/en/best-practices) — the agent doing the work isn't the one grading it.
+
+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/md_path_exemptions.py

@@ -21,12 +21,10 @@ from hooks_constants.md_to_html_blocker_constants import (  # noqa: E402
     ALL_EXEMPT_PLUGIN_DIRECTORY_SEGMENTS,
     ALL_EXEMPT_ROOT_FILENAMES_LOWER,
     CLAUDE_DEV_ENV_REPO_NAME_SEGMENT,
-    CLAUDE_DIRECTORY_PATH_PREFIX,
-    CLAUDE_DIRECTORY_SEGMENT_MARKER,
+    CLAUDE_DIRECTORY_NAME,
+    CLAUDE_PROFILE_DIRECTORY_NAME_PREFIX,
     MINIMUM_SEGMENT_COUNT_TO_MATCH_INDICATOR,
     PACKAGES_TOP_LEVEL_SEGMENT,
-    PLUGIN_DIRECTORY_PATH_PREFIX,
-    PLUGIN_DIRECTORY_SEGMENT_MARKER,
     PLUGIN_ROOT_MARKER_DIRECTORY_NAME,
     REPO_ROOT_MARKER_NAME,
     RESOLVED_HOME_DIRECTORY_LOWER,
@@ -38,7 +36,9 @@ def is_exempt_path(file_path: str) -> bool:
     """Return True when the .md file path is exempt from the blocker policy.
 
     Exemption sources, in order of evaluation:
-    - Any segment under `.claude/` or `.claude-plugin/` (case-insensitive)
+    - Any directory segment named `.claude` or prefixed `.claude-`
+      (case-insensitive): project infrastructure, profile directories like
+      `.claude-mel/`, and `.claude-plugin/`
     - Basename in `ALL_EXEMPT_ANYWHERE_FILENAMES` (e.g. SKILL.md)
     - Anchored under `packages/claude-dev-env/<one of
       ALL_CLAUDE_CODE_SOURCE_TOP_DIRECTORIES>/...` (docs, rules,
@@ -60,15 +60,7 @@ def is_exempt_path(file_path: str) -> bool:
     expanded_path = os.path.expanduser(file_path)
     normalized = os.path.normpath(expanded_path).replace("\\", "/")
     lower_normalized = normalized.lower()
-    if (
-        CLAUDE_DIRECTORY_SEGMENT_MARKER in lower_normalized
-        or lower_normalized.startswith(CLAUDE_DIRECTORY_PATH_PREFIX)
-    ):
-        return True
-    if (
-        PLUGIN_DIRECTORY_SEGMENT_MARKER in lower_normalized
-        or lower_normalized.startswith(PLUGIN_DIRECTORY_PATH_PREFIX)
-    ):
+    if _has_claude_infrastructure_segment(lower_normalized):
         return True
     basename_lower = os.path.basename(normalized).lower()
     if basename_lower in ALL_EXEMPT_ANYWHERE_FILENAMES_LOWER:
@@ -101,6 +93,33 @@ def _resolve_absolute_directory(normalized_path: str) -> str:
     return os.path.abspath(directory)
 
 
+def _has_claude_infrastructure_segment(lower_normalized_path: str) -> bool:
+    """A directory named `.claude` or prefixed `.claude-` (profile and
+    plugin directories) holds Claude infrastructure; any path inside one
+    is exempt.
+
+    Only directory segments are matched. The final segment is always the
+    file's basename (``normpath`` strips any trailing slash), so a file
+    merely named with the ``.claude-`` prefix in an ordinary directory
+    stays subject to the policy.
+
+    Args:
+        lower_normalized_path: Lowercased path with separators normalized
+            to forward slashes.
+
+    Returns:
+        True when any directory segment names a Claude infrastructure
+        directory.
+    """
+    all_directory_segments = lower_normalized_path.split("/")[:-1]
+    for each_segment in all_directory_segments:
+        if each_segment == CLAUDE_DIRECTORY_NAME:
+            return True
+        if each_segment.startswith(CLAUDE_PROFILE_DIRECTORY_NAME_PREFIX):
+            return True
+    return False
+
+
 def _has_plugin_directory_segment(lower_normalized_path: str) -> bool:
     for each_directory_segment in ALL_EXEMPT_PLUGIN_DIRECTORY_SEGMENTS:
         segment_marker = f"/{each_directory_segment}/"

package/hooks/blocking/md_to_html_blocker.py

@@ -25,6 +25,7 @@ from hooks_constants.md_to_html_blocker_constants import (  # noqa: E402
     ALL_EXEMPT_PLUGIN_DIRECTORY_SEGMENTS,
     CLAUDE_DEV_ENV_REPO_NAME_SEGMENT,
     CLAUDE_DIRECTORY_NAME,
+    CLAUDE_PROFILE_DIRECTORY_NAME_PREFIX,
     PACKAGES_TOP_LEVEL_SEGMENT,
     PLUGIN_ROOT_MARKER_DIRECTORY_NAME,
 )
@@ -63,7 +64,7 @@ def _block_context() -> str:
         "Reference for HTML effectiveness patterns:\n"
         f"{_html_effectiveness_url}\n"
         "Exceptions (.md still allowed):\n"
-        f"- Files inside {CLAUDE_DIRECTORY_NAME}/ or {PLUGIN_ROOT_MARKER_DIRECTORY_NAME}/ directories\n"
+        f"- Files inside {CLAUDE_DIRECTORY_NAME}/ or {CLAUDE_PROFILE_DIRECTORY_NAME_PREFIX}*/ directories\n"
         f"- {_exempt_anywhere_filenames_summary} anywhere\n"
         f"- Files under {_exempt_plugin_segments_summary} directories\n"
         f"- Files under {_claude_dev_env_source_directories_summary} source directories\n"
@@ -79,7 +80,7 @@ def _block_system_message() -> str:
         ".md files are blocked in this project — generate a self-contained .html "
         f"file instead. See {_html_effectiveness_url} for "
         f"design patterns and examples. Exemptions: {CLAUDE_DIRECTORY_NAME}/ and "
-        f"{PLUGIN_ROOT_MARKER_DIRECTORY_NAME}/ infrastructure, "
+        f"{CLAUDE_PROFILE_DIRECTORY_NAME_PREFIX}*/ infrastructure, "
         f"{_exempt_anywhere_filenames_summary} anywhere, {_exempt_plugin_segments_summary} trees, "
         f"{_claude_dev_env_source_directories_summary} source trees, "
         f"files under a {PLUGIN_ROOT_MARKER_DIRECTORY_NAME}/ root, "

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_md_to_html_blocker_exemptions.py

@@ -1,7 +1,8 @@
 """Tests for md_to_html_blocker directory and filename exemptions.
 
-Covers which directory trees (`.claude/`, `.claude-plugin/`, source subtrees
-under `packages/claude-dev-env/`, `agents/`, `skills/`, `commands/`) and which
+Covers which directory trees (`.claude/`, `.claude-*/` profile and plugin
+directories, source subtrees under `packages/claude-dev-env/`, `agents/`,
+`skills/`, `commands/`) and which
 root-level filenames (`README.md`, `CHANGELOG.md`, `CLAUDE.md`, `AGENTS.md`,
 `SKILL.md`) are exempt from the `.md` block, and the segment-anchored matching
 that prevents nested look-alike paths from bypassing the block.
@@ -366,3 +367,68 @@ def test_blocks_ordinary_docs_md_file():
     assert result.returncode == 0
     output = json.loads(result.stdout)
     assert output["hookSpecificOutput"]["permissionDecision"] == "deny"
+
+
+def test_passes_claude_profile_memory_directory():
+    """A Claude profile directory (`.claude-<name>/`, e.g. `.claude-mel/`)
+    carries the same infrastructure as `.claude/`; per-project memory files
+    under it accept .md writes."""
+    result = _run_hook(
+        "Write",
+        {
+            "file_path": (
+                "C:/Users/sample/.claude-mel/projects"
+                "/sample-project/memory/fact.md"
+            ),
+            "content": "# Fact",
+        },
+    )
+    assert result.returncode == 0
+    assert result.stdout == ""
+
+
+def test_passes_relative_claude_profile_directory():
+    result = _run_hook(
+        "Write",
+        {
+            "file_path": ".claude-mel/projects/sample/memory/fact.md",
+            "content": "# Fact",
+        },
+    )
+    assert result.returncode == 0
+    assert result.stdout == ""
+
+
+def test_passes_claude_profile_directory_case_insensitive():
+    result = _run_hook(
+        "Write",
+        {"file_path": "C:/Users/sample/.Claude-Mel/MEMORY.md", "content": "# Index"},
+    )
+    assert result.returncode == 0
+    assert result.stdout == ""
+
+
+def test_blocks_dot_directory_that_starts_with_claude_but_lacks_hyphen():
+    """`.claudette/` is not Claude infrastructure: only a directory named
+    exactly `.claude` or carrying the `.claude-` prefix is exempt."""
+    result = _run_hook(
+        "Write",
+        {"file_path": "notes/.claudette/intro.md", "content": "# Intro"},
+    )
+    assert result.returncode == 0
+    output = json.loads(result.stdout)
+    assert output["hookSpecificOutput"]["permissionDecision"] == "deny"
+
+
+def test_blocks_claude_prefixed_filename_in_plain_directory():
+    """A file merely named with the `.claude-` prefix (e.g.
+    `docs/.claude-notes.md`) is not Claude infrastructure: the exemption
+    matches directory segments only, so a `.claude-*.md` basename inside
+    an ordinary directory is blocked."""
+    result = _run_hook(
+        "Write",
+        {"file_path": "docs/.claude-notes.md", "content": "# Notes"},
+    )
+    assert result.returncode == 0
+    output = json.loads(result.stdout)
+    assert output["hookSpecificOutput"]["permissionDecision"] == "deny"

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/md_to_html_blocker_constants.py

@@ -24,10 +24,7 @@ REPO_ROOT_MARKER_NAME: str = ".git"
 CLAUDE_DIRECTORY_NAME: str = ".claude"
 PLUGIN_ROOT_MARKER_DIRECTORY_NAME: str = ".claude-plugin"
 
-CLAUDE_DIRECTORY_SEGMENT_MARKER: str = f"/{CLAUDE_DIRECTORY_NAME}/"
-CLAUDE_DIRECTORY_PATH_PREFIX: str = f"{CLAUDE_DIRECTORY_NAME}/"
-PLUGIN_DIRECTORY_SEGMENT_MARKER: str = f"/{PLUGIN_ROOT_MARKER_DIRECTORY_NAME}/"
-PLUGIN_DIRECTORY_PATH_PREFIX: str = f"{PLUGIN_ROOT_MARKER_DIRECTORY_NAME}/"
+CLAUDE_PROFILE_DIRECTORY_NAME_PREFIX: str = f"{CLAUDE_DIRECTORY_NAME}-"
 
 ALL_EXEMPT_ANYWHERE_FILENAMES_LOWER: frozenset[str] = frozenset(
     each_filename.lower() for each_filename in ALL_EXEMPT_ANYWHERE_FILENAMES
@@ -68,12 +65,9 @@ __all__ = [
     "ALL_EXEMPT_ROOT_FILENAMES_LOWER",
     "CLAUDE_DEV_ENV_REPO_NAME_SEGMENT",
     "CLAUDE_DIRECTORY_NAME",
-    "CLAUDE_DIRECTORY_PATH_PREFIX",
-    "CLAUDE_DIRECTORY_SEGMENT_MARKER",
+    "CLAUDE_PROFILE_DIRECTORY_NAME_PREFIX",
     "MINIMUM_SEGMENT_COUNT_TO_MATCH_INDICATOR",
     "PACKAGES_TOP_LEVEL_SEGMENT",
-    "PLUGIN_DIRECTORY_PATH_PREFIX",
-    "PLUGIN_DIRECTORY_SEGMENT_MARKER",
     "PLUGIN_ROOT_MARKER_DIRECTORY_NAME",
     "REPO_ROOT_MARKER_NAME",
     "RESOLVED_HOME_DIRECTORY_LOWER",

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/hooks/hooks_constants/test_md_to_html_blocker_constants.py

@@ -115,3 +115,11 @@ def test_plugin_root_marker_directory_name_is_dot_claude_plugin() -> None:
     a plugin repo root and exempted."""
     assert constants_module.PLUGIN_ROOT_MARKER_DIRECTORY_NAME == ".claude-plugin"
     assert "PLUGIN_ROOT_MARKER_DIRECTORY_NAME" in constants_module.__all__
+
+
+def test_claude_profile_directory_name_prefix_is_dot_claude_hyphen() -> None:
+    """A directory whose name carries the `.claude-` prefix (profile
+    directories like `.claude-mel/`, plus `.claude-plugin/`) is Claude
+    infrastructure; any path inside one bypasses the .md block."""
+    assert constants_module.CLAUDE_PROFILE_DIRECTORY_NAME_PREFIX == ".claude-"
+    assert "CLAUDE_PROFILE_DIRECTORY_NAME_PREFIX" in constants_module.__all__

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "claude-dev-env",
-    "version": "1.55.1",
+    "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>