claude-dev-env 1.88.1 → 1.90.0

package/hooks/lifecycle/CLAUDE.md

@@ -7,12 +7,14 @@ Hooks that run at session or config-change boundaries rather than on individual
 | File | Event | What it does |
 |---|---|---|
 | `config_change_guard.py` | PostToolUse (Write/Edit on `settings.json`) | Counts hooks in the edited `settings.json` and logs any change to `~/.claude/cache/config-change-audit.log`; alerts when the hook count drops below the last known value |
+| `enter_worktree_origin_prefetch.py` | PreToolUse (EnterWorktree) | Fetches origin's default branch before a worktree creation call, keeping the `refs/remotes/origin/<default-branch>` ref that `fresh` mode reads current; never blocks on fetch failure |
 | `pr_converge_bugteam_skill_tracker.py` | PreToolUse (Skill) | Tracks which bugteam skill runs have completed within a pr-converge loop, so the enforcer can verify parallel execution |
 | `session_end_cleanup.py` | SessionEnd | Purges stale cache entries from `~/.claude/cache/` (entries older than the configured threshold) and old backup files |
 | `test_config_change_guard.py` | — | Tests for `config_change_guard.py` |
+| `test_enter_worktree_origin_prefetch.py` | — | Tests for `enter_worktree_origin_prefetch.py` |
 | `test_pr_converge_bugteam_skill_tracker.py` | — | Tests for `pr_converge_bugteam_skill_tracker.py` |
 
 ## Conventions
 
-- Constants for these hooks (stale-age threshold, cache directory, known-hook-count file) live in `hooks_constants/session_env_cleanup_constants.py` and `hooks_constants/pr_converge_bugteam_enforcer_constants.py`.
+- Constants for these hooks (stale-age threshold, cache directory, known-hook-count file, EnterWorktree prefetch tuning) live in `hooks_constants/session_env_cleanup_constants.py`, `hooks_constants/pr_converge_bugteam_enforcer_constants.py`, and `hooks_constants/enter_worktree_prefetch_constants.py`.
 - Tests run with `python -m pytest lifecycle/test_<name>.py`.

package/hooks/lifecycle/enter_worktree_origin_prefetch.py

@@ -0,0 +1,146 @@
+#!/usr/bin/env python3
+"""PreToolUse hook: fetch origin's default branch before EnterWorktree creates one.
+
+``EnterWorktree`` in its default ``fresh`` mode bases a new worktree on the
+locally cached ``refs/remotes/origin/<default-branch>`` ref and only runs
+``git fetch`` when that ref is missing entirely -- so a worktree created
+without a recent fetch silently starts behind the remote. This hook fetches
+that ref immediately before the tool resolves its base, so the ref it reads
+is current.
+
+::
+
+    EnterWorktree({})                              # tool_input has no "path"
+             |
+             v
+    this hook: git fetch origin <default-branch>   # best-effort, never blocks
+             |
+             v
+    EnterWorktree resolves refs/remotes/origin/<default-branch>  # now fresh
+
+The hook is a no-op when ``tool_input`` carries a ``path`` (switching into an
+already-existing worktree needs no fresh base) and always exits 0 -- a failed
+or slow fetch never blocks worktree creation.
+"""
+
+from __future__ import annotations
+
+import json
+import subprocess
+import sys
+from pathlib import Path
+
+_hooks_dir = str(Path(__file__).resolve().parent.parent)
+if _hooks_dir not in sys.path:
+    sys.path.insert(0, _hooks_dir)
+
+from hooks_constants.enter_worktree_prefetch_constants import (  # noqa: E402
+    ENTER_WORKTREE_PATH_INPUT_KEY,
+    ENTER_WORKTREE_TOOL_NAME,
+    GIT_FETCH_TIMEOUT_SECONDS,
+    GIT_SYMBOLIC_REF_TIMEOUT_SECONDS,
+    ORIGIN_HEAD_SYMBOLIC_REF,
+    ORIGIN_REMOTE_NAME,
+    ORIGIN_REMOTE_REF_PREFIX,
+)
+
+
+def is_enter_worktree_creation(payload_by_field: dict[str, object]) -> bool:
+    """Return True when this hook invocation is an EnterWorktree creation call.
+
+    Args:
+        payload_by_field: The full PreToolUse hook payload (already JSON-parsed),
+            keyed by top-level field name.
+
+    Returns:
+        True when ``tool_name == "EnterWorktree"`` and ``tool_input`` carries
+        no ``path`` key. A ``path`` value means the call switches into an
+        already-existing worktree rather than creating one, so it is False
+        for that case and for every other tool.
+    """
+    if payload_by_field.get("tool_name", "") != ENTER_WORKTREE_TOOL_NAME:
+        return False
+    tool_input = payload_by_field.get("tool_input", {})
+    if not isinstance(tool_input, dict):
+        return True
+    return not tool_input.get(ENTER_WORKTREE_PATH_INPUT_KEY)
+
+
+def resolve_origin_default_branch(repo_directory: str) -> str | None:
+    """Return the branch name origin's HEAD points at, or None if unresolved.
+
+    Args:
+        repo_directory: Working directory to run ``git`` in.
+
+    Returns:
+        The branch name (for example ``"main"``) parsed from
+        ``refs/remotes/origin/HEAD``, or None when the symbolic ref is
+        unset, git is unavailable, or the command times out.
+    """
+    try:
+        completed_process = subprocess.run(
+            ["git", "symbolic-ref", ORIGIN_HEAD_SYMBOLIC_REF],
+            capture_output=True,
+            text=True,
+            timeout=GIT_SYMBOLIC_REF_TIMEOUT_SECONDS,
+            cwd=repo_directory,
+            check=False,
+        )
+    except (subprocess.TimeoutExpired, FileNotFoundError, OSError):
+        return None
+    if completed_process.returncode != 0:
+        return None
+    resolved_ref = completed_process.stdout.strip()
+    if not resolved_ref.startswith(ORIGIN_REMOTE_REF_PREFIX):
+        return None
+    return resolved_ref[len(ORIGIN_REMOTE_REF_PREFIX):]
+
+
+def fetch_origin_branch(repo_directory: str, branch_name: str) -> None:
+    """Best-effort ``git fetch origin <branch_name>``; never raises.
+
+    Args:
+        repo_directory: Working directory to run ``git`` in.
+        branch_name: Branch to fetch from the ``origin`` remote.
+    """
+    try:
+        subprocess.run(
+            ["git", "fetch", ORIGIN_REMOTE_NAME, branch_name],
+            capture_output=True,
+            text=True,
+            timeout=GIT_FETCH_TIMEOUT_SECONDS,
+            cwd=repo_directory,
+            check=False,
+        )
+    except (subprocess.TimeoutExpired, FileNotFoundError, OSError):
+        return
+
+
+def main() -> None:
+    """Entry point for the PreToolUse:EnterWorktree hook.
+
+    Reads the PreToolUse payload from stdin, and when it is an EnterWorktree
+    creation call, fetches origin's default branch in the session's ``cwd``
+    before returning. Always exits 0: a fetch failure self-heals on the next
+    fetch rather than blocking worktree creation.
+    """
+    try:
+        hook_payload = json.load(sys.stdin)
+    except json.JSONDecodeError:
+        sys.exit(0)
+    if not isinstance(hook_payload, dict):
+        sys.exit(0)
+    if not is_enter_worktree_creation(hook_payload):
+        sys.exit(0)
+    repo_directory = hook_payload.get("cwd")
+    if not isinstance(repo_directory, str) or not repo_directory:
+        sys.exit(0)
+    default_branch = resolve_origin_default_branch(repo_directory)
+    if default_branch is None:
+        sys.exit(0)
+    fetch_origin_branch(repo_directory, default_branch)
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

package/hooks/lifecycle/test_enter_worktree_origin_prefetch.py

@@ -0,0 +1,178 @@
+"""Unit tests for the enter_worktree_origin_prefetch PreToolUse hook.
+
+Uses real git repositories (a "remote" repo cloned into a "local" one) so the
+fetch behavior is exercised against actual git plumbing, not mocked calls.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import io
+import json
+import pathlib
+import subprocess
+import sys
+
+import pytest
+
+_HOOK_DIR = pathlib.Path(__file__).parent
+_HOOKS_TREE = _HOOK_DIR.parent
+for each_path in (str(_HOOK_DIR), str(_HOOKS_TREE)):
+    if each_path not in sys.path:
+        sys.path.insert(0, each_path)
+
+hook_spec = importlib.util.spec_from_file_location(
+    "enter_worktree_origin_prefetch",
+    _HOOK_DIR / "enter_worktree_origin_prefetch.py",
+)
+assert hook_spec is not None
+assert hook_spec.loader is not None
+hook_module = importlib.util.module_from_spec(hook_spec)
+hook_spec.loader.exec_module(hook_module)
+
+
+def _run_git(repo_directory: pathlib.Path, *args: str) -> subprocess.CompletedProcess[str]:
+    return subprocess.run(
+        ["git", *args],
+        cwd=repo_directory,
+        capture_output=True,
+        text=True,
+        check=True,
+    )
+
+
+def _init_repo_with_commit(repo_directory: pathlib.Path) -> None:
+    repo_directory.mkdir(parents=True, exist_ok=True)
+    _run_git(repo_directory, "init", "--quiet", "--initial-branch=main")
+    _run_git(repo_directory, "config", "user.email", "test@example.com")
+    _run_git(repo_directory, "config", "user.name", "Test")
+    _run_git(repo_directory, "commit", "--allow-empty", "--quiet", "-m", "init")
+
+
+def _clone_as_local(remote_directory: pathlib.Path, local_directory: pathlib.Path) -> None:
+    subprocess.run(
+        ["git", "clone", "--quiet", str(remote_directory), str(local_directory)],
+        capture_output=True,
+        text=True,
+        check=True,
+    )
+    _run_git(local_directory, "config", "user.email", "test@example.com")
+    _run_git(local_directory, "config", "user.name", "Test")
+
+
+def test_is_enter_worktree_creation_true_when_no_path_given() -> None:
+    payload = {"tool_name": "EnterWorktree", "tool_input": {}}
+    assert hook_module.is_enter_worktree_creation(payload) is True
+
+
+def test_is_enter_worktree_creation_true_with_name_only() -> None:
+    payload = {"tool_name": "EnterWorktree", "tool_input": {"name": "my-branch"}}
+    assert hook_module.is_enter_worktree_creation(payload) is True
+
+
+def test_is_enter_worktree_creation_false_when_path_given() -> None:
+    payload = {"tool_name": "EnterWorktree", "tool_input": {"path": "/some/worktree"}}
+    assert hook_module.is_enter_worktree_creation(payload) is False
+
+
+def test_is_enter_worktree_creation_false_for_other_tool() -> None:
+    payload = {"tool_name": "Bash", "tool_input": {}}
+    assert hook_module.is_enter_worktree_creation(payload) is False
+
+
+def test_resolve_origin_default_branch_reads_cloned_head(tmp_path: pathlib.Path) -> None:
+    remote_directory = tmp_path / "remote"
+    local_directory = tmp_path / "local"
+    _init_repo_with_commit(remote_directory)
+    _clone_as_local(remote_directory, local_directory)
+
+    resolved_branch = hook_module.resolve_origin_default_branch(str(local_directory))
+
+    assert resolved_branch == "main"
+
+
+def test_resolve_origin_default_branch_returns_none_without_origin(
+    tmp_path: pathlib.Path,
+) -> None:
+    solo_directory = tmp_path / "solo"
+    _init_repo_with_commit(solo_directory)
+
+    resolved_branch = hook_module.resolve_origin_default_branch(str(solo_directory))
+
+    assert resolved_branch is None
+
+
+def test_fetch_origin_branch_updates_stale_local_ref(tmp_path: pathlib.Path) -> None:
+    remote_directory = tmp_path / "remote"
+    local_directory = tmp_path / "local"
+    _init_repo_with_commit(remote_directory)
+    _clone_as_local(remote_directory, local_directory)
+
+    _run_git(remote_directory, "commit", "--allow-empty", "--quiet", "-m", "second")
+    remote_head_sha = _run_git(remote_directory, "rev-parse", "HEAD").stdout.strip()
+    local_cached_sha_before = _run_git(
+        local_directory, "rev-parse", "refs/remotes/origin/main"
+    ).stdout.strip()
+    assert local_cached_sha_before != remote_head_sha
+
+    hook_module.fetch_origin_branch(str(local_directory), "main")
+
+    local_cached_sha_after = _run_git(
+        local_directory, "rev-parse", "refs/remotes/origin/main"
+    ).stdout.strip()
+    assert local_cached_sha_after == remote_head_sha
+
+
+def test_fetch_origin_branch_never_raises_when_remote_missing(tmp_path: pathlib.Path) -> None:
+    solo_directory = tmp_path / "solo"
+    _init_repo_with_commit(solo_directory)
+
+    hook_module.fetch_origin_branch(str(solo_directory), "main")
+
+
+def test_main_fetches_stale_ref_and_exits_zero(
+    tmp_path: pathlib.Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    remote_directory = tmp_path / "remote"
+    local_directory = tmp_path / "local"
+    _init_repo_with_commit(remote_directory)
+    _clone_as_local(remote_directory, local_directory)
+    _run_git(remote_directory, "commit", "--allow-empty", "--quiet", "-m", "second")
+    remote_head_sha = _run_git(remote_directory, "rev-parse", "HEAD").stdout.strip()
+
+    payload = {
+        "tool_name": "EnterWorktree",
+        "tool_input": {},
+        "cwd": str(local_directory),
+    }
+    monkeypatch.setattr(sys, "stdin", io.StringIO(json.dumps(payload)))
+
+    with pytest.raises(SystemExit) as exit_info:
+        hook_module.main()
+
+    assert exit_info.value.code == 0
+    local_cached_sha_after = _run_git(
+        local_directory, "rev-parse", "refs/remotes/origin/main"
+    ).stdout.strip()
+    assert local_cached_sha_after == remote_head_sha
+
+
+def test_main_exits_zero_for_non_enter_worktree_tool(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    payload = {"tool_name": "Bash", "tool_input": {"command": "ls"}, "cwd": "/tmp"}
+    monkeypatch.setattr(sys, "stdin", io.StringIO(json.dumps(payload)))
+
+    with pytest.raises(SystemExit) as exit_info:
+        hook_module.main()
+
+    assert exit_info.value.code == 0
+
+
+def test_main_exits_zero_on_malformed_json(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setattr(sys, "stdin", io.StringIO("not json"))
+
+    with pytest.raises(SystemExit) as exit_info:
+        hook_module.main()
+
+    assert exit_info.value.code == 0

package/package.json

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

package/rules/CLAUDE.md

@@ -17,6 +17,7 @@ Rule files installed into `~/.claude/rules/` by `bin/install.mjs`. Claude Code l
 | `conservative-action.md` | Research and recommend when intent is ambiguous; act only on explicit request |
 | `context7.md` | Use Context7 MCP to fetch current library docs; always prefer live docs over built-in knowledge |
 | `docstring-prose-matches-implementation.md` | Prose enumerations in docstrings cover every behavior the body applies |
+| `durable-post-artifacts.md` | GitHub post bodies never reference volatile scratch paths; text embeds inline and binary artifacts upload to the `artifacts` release with the permanent URL linked |
 | `explore-thoroughly.md` | Read relevant files and map existing patterns before proposing a change |
 | `file-global-constants.md` | File-global constants need at least two same-file references; otherwise move value to `config/` |
 | `gh-body-file.md` | Use `--body-file` with a temp file for all `gh` commands carrying markdown body content |

package/rules/durable-post-artifacts.md

@@ -0,0 +1,35 @@
+# Durable Post Artifacts
+
+**When this applies:** Any GitHub post that lives on the server — an issue, a pull request, a comment, or a review — created through `gh` (`gh pr create/comment/edit/review`, `gh issue create/comment/edit`) or a GitHub MCP post tool.
+
+## Rule
+
+A post lives forever. Job scratch directories, worktrees, and system temp folders do not — they are cleaned soon after the run that made them. So a post must never point at a path in that scratch. The moment the directory is cleaned, the reference breaks and the reader is left with a dead path.
+
+Handle the two kinds of content differently:
+
+- **Text data** (logs, tables, diffs, stack traces): paste the actual text inline in the post body. Do not link a scratch file that holds it.
+- **Binary artifacts** (images, screenshots, archives): upload the file to the repository's durable `artifacts` release and link the permanent URL. Use the helper:
+
+  ```
+  python3 ~/.claude/scripts/gh_artifact_upload.py <file-path> <owner/repo>
+  ```
+
+  It ensures the repository has a prerelease tagged `artifacts`, uploads the file under a `YYYYMMDD_HHMMSS_<name>` asset name, and prints the permanent download URL. Put that URL in the post.
+
+## Volatile paths that must not appear in a post body
+
+- A job scratch directory (`.claude-editor/jobs/`)
+- A worktree (`.claude/worktrees/`)
+- A system temp location (`AppData\Local\Temp`, `%TEMP%`, `$env:TEMP`, `/tmp/`)
+- The job scratch environment variable (`$CLAUDE_JOB_DIR`)
+
+Both slash directions count.
+
+## Enforcement
+
+The `volatile_path_in_post_blocker` PreToolUse hook reads the body of each `gh` post command and each GitHub MCP post call, scans it for these markers, and blocks the post when it finds one. For a `--body-file`, the hook reads the file and scans its contents, so writing the body to a temp file and passing it with `--body-file` stays allowed — what the hook rejects is a volatile path inside the text that gets posted.
+
+## Why
+
+A comment that cites an artifact under a job's tmp directory reads fine the moment it is posted and breaks a few minutes later, once the job is cleaned. Embedding text inline and linking binary artifacts to a durable release keeps every post readable for as long as it exists.

package/scripts/CLAUDE.md

@@ -6,6 +6,7 @@ Utility scripts installed into `~/.claude/scripts/` by `bin/install.mjs`. Each s
 
 | File | Purpose |
 |---|---|
+| `gh_artifact_upload.py` | Uploads a file to a repo's durable `artifacts` prerelease under a timestamped asset name and prints the permanent download URL a GitHub post can link |
 | `setup_project_paths.py` | One-time bootstrap: discovers git repos via `es.exe` (Everything) and writes `~/.claude/project-paths.json`; never hardcodes scan roots |
 | `sweep_empty_dirs.py` | Deletes empty directories older than a configurable age under a given root; runs once (`--once`) or in continuous-watch mode |
 | `sync_to_cursor.py` | Entry point for syncing Claude rules to Cursor `.mdc` files; delegates to the `sync_to_cursor/` package |

package/scripts/dev_env_scripts_constants/CLAUDE.md

@@ -7,6 +7,7 @@ Named constants for scripts in `scripts/`. Follows the project convention that t
 | File | Constants for |
 |---|---|
 | `timing.py` | `sweep_empty_dirs.py` — `DEFAULT_AGE_SECONDS` (smallest age before an empty directory is eligible for removal) and `DEFAULT_POLL_INTERVAL` (seconds between sweep passes in continuous-watch mode) |
+| `gh_artifact_upload_constants.py` | `gh_artifact_upload.py` — the `artifacts` release tag, title, and notes body, the GitHub CLI binary name, the asset-name timestamp format and template, the asset download URL template, the notes-file suffix, and the text encoding |
 | `__init__.py` | Empty package marker |
 
 ## Convention

package/scripts/dev_env_scripts_constants/gh_artifact_upload_constants.py

@@ -0,0 +1,43 @@
+"""Constants for the gh_artifact_upload script.
+
+Per the project's configuration conventions, script-level scalar constants
+live in dev_env_scripts_constants alongside timing.py.
+"""
+
+ARTIFACTS_RELEASE_TAG: str = "artifacts"
+"""Release tag that holds durable post artifacts."""
+
+ARTIFACTS_RELEASE_TITLE: str = "Durable post artifacts"
+"""Human-readable title for the artifacts release."""
+
+ARTIFACTS_RELEASE_NOTES: str = (
+    "Permanent storage for binary artifacts linked from GitHub issue and pull "
+    "request posts. Job scratch directories are ephemeral and get cleaned soon "
+    "after a run; assets uploaded to this prerelease persist so a durable post "
+    "can link a stable URL."
+)
+"""Release body written when the artifacts release is first created."""
+
+GH_BINARY_NAME: str = "gh"
+"""The GitHub CLI executable name."""
+
+ASSET_NAME_TIMESTAMP_FORMAT: str = "%Y%m%d_%H%M%S"
+"""strftime format for the timestamp prefix on an uploaded asset name."""
+
+ASSET_NAME_TEMPLATE: str = "{timestamp}_{basename}"
+"""Template joining the timestamp prefix and the source file basename."""
+
+RELEASE_ASSETS_JSON_KEY: str = "assets"
+"""``gh release view --json`` field holding the release's asset list."""
+
+ASSET_URL_JSON_KEY: str = "url"
+"""Asset field carrying the browser download URL GitHub serves."""
+
+ASSET_CREATED_AT_JSON_KEY: str = "createdAt"
+"""Asset field carrying the ISO 8601 creation timestamp."""
+
+NOTES_FILE_SUFFIX: str = ".md"
+"""Suffix for the temporary release-notes file."""
+
+UTF8_ENCODING: str = "utf-8"
+"""Text encoding for subprocess output and temp files."""