claude-dev-env 2.5.0 → 2.7.1

package/skills/fresh-branch/scripts/test_create_fresh_branch.py

@@ -245,28 +245,23 @@ class TestResolveAgentSlug:
 
 
 class TestResolveAgentWorktreeRoot:
-    def should_use_userprofile_scratch_on_windows(
+    def should_nest_under_the_repository_claude_worktrees_directory(
         self,
-        monkeypatch: pytest.MonkeyPatch,
+        tmp_path: Path,
     ) -> None:
         module = load_create_fresh_branch_module()
-        monkeypatch.setattr(module.sys, "platform", "win32")
-        monkeypatch.setenv("USERPROFILE", r"C:\Users\example")
-        worktree_root = module.resolve_agent_worktree_root("grok")
-        assert worktree_root == (
-            Path(r"C:\Users\example") / "AppData" / "Local" / "Temp" / "grok"
-        )
+        worktree_root = module.resolve_agent_worktree_root(tmp_path, "grok")
+        assert worktree_root == tmp_path / ".claude" / "worktrees" / "grok"
 
-    def should_fall_back_to_gettempdir_off_windows(
+    def should_keep_each_agent_in_its_own_subdirectory(
         self,
-        monkeypatch: pytest.MonkeyPatch,
         tmp_path: Path,
     ) -> None:
         module = load_create_fresh_branch_module()
-        monkeypatch.setattr(module.sys, "platform", "linux")
-        monkeypatch.setattr(module.tempfile, "gettempdir", lambda: str(tmp_path))
-        worktree_root = module.resolve_agent_worktree_root("claude")
-        assert worktree_root == tmp_path / "claude"
+        grok_root = module.resolve_agent_worktree_root(tmp_path, "grok")
+        claude_root = module.resolve_agent_worktree_root(tmp_path, "claude")
+        assert grok_root != claude_root
+        assert grok_root.parent == claude_root.parent
 
 
 class TestResolveUniqueWorktreePath:
@@ -301,18 +296,9 @@ class TestAgentSlugPathSafety:
     def should_reject_parent_segment_agent_slug_without_mkdir_outside(
         self,
         tmp_path: Path,
-        monkeypatch: pytest.MonkeyPatch,
     ) -> None:
         module = load_create_fresh_branch_module()
-        agent_scratch_parent = tmp_path / "agent-scratch"
-        agent_scratch_parent.mkdir()
-        escaped_agent_root = (agent_scratch_parent / ".." / "escape-agent").resolve()
-        monkeypatch.setattr(module.sys, "platform", "linux")
-        monkeypatch.setattr(
-            module.tempfile,
-            "gettempdir",
-            lambda: str(agent_scratch_parent),
-        )
+        escaped_agent_root = (tmp_path / "escape-agent").resolve()
         with pytest.raises(ValueError, match="agent slug"):
             module.create_fresh_branch(
                 branch_name="fix/safe-branch",
@@ -321,22 +307,13 @@ class TestAgentSlugPathSafety:
                 base_ref=DEFAULT_BASE_REF,
             )
         assert not escaped_agent_root.exists()
-        assert not (agent_scratch_parent / "claude").exists()
+        assert not (tmp_path / "unused-repo").exists()
 
     def should_reject_empty_agent_slug(
         self,
         tmp_path: Path,
-        monkeypatch: pytest.MonkeyPatch,
     ) -> None:
         module = load_create_fresh_branch_module()
-        agent_scratch_parent = tmp_path / "agent-scratch"
-        agent_scratch_parent.mkdir()
-        monkeypatch.setattr(module.sys, "platform", "linux")
-        monkeypatch.setattr(
-            module.tempfile,
-            "gettempdir",
-            lambda: str(agent_scratch_parent),
-        )
         with pytest.raises(ValueError, match="agent slug"):
             module.create_fresh_branch(
                 branch_name="fix/safe-branch",
@@ -344,25 +321,16 @@ class TestAgentSlugPathSafety:
                 agent_slug="",
                 base_ref=DEFAULT_BASE_REF,
             )
-        assert not any(agent_scratch_parent.iterdir())
+        assert not (tmp_path / "unused-repo").exists()
 
 
 class TestBranchNamePathSafety:
     def should_reject_parent_segments_without_mkdir_outside(
         self,
         tmp_path: Path,
-        monkeypatch: pytest.MonkeyPatch,
     ) -> None:
         module = load_create_fresh_branch_module()
-        agent_scratch_parent = tmp_path / "agent-scratch"
-        agent_scratch_parent.mkdir()
-        monkeypatch.setattr(module.sys, "platform", "linux")
-        monkeypatch.setattr(
-            module.tempfile,
-            "gettempdir",
-            lambda: str(agent_scratch_parent),
-        )
-        escaped_path = agent_scratch_parent / "escape"
+        escaped_path = tmp_path / "escape"
         with pytest.raises(ValueError, match="relative path"):
             module.create_fresh_branch(
                 branch_name="fix/../../escape",
@@ -371,23 +339,14 @@ class TestBranchNamePathSafety:
                 base_ref=DEFAULT_BASE_REF,
             )
         assert not escaped_path.exists()
-        assert not (agent_scratch_parent / "claude").exists()
+        assert not (tmp_path / "unused-repo").exists()
 
     def should_reject_absolute_branch_without_mkdir_outside(
         self,
         tmp_path: Path,
-        monkeypatch: pytest.MonkeyPatch,
     ) -> None:
         module = load_create_fresh_branch_module()
-        agent_scratch_parent = tmp_path / "agent-scratch"
-        agent_scratch_parent.mkdir()
         outside_target = tmp_path / "outside-evil"
-        monkeypatch.setattr(module.sys, "platform", "linux")
-        monkeypatch.setattr(
-            module.tempfile,
-            "gettempdir",
-            lambda: str(agent_scratch_parent),
-        )
         with pytest.raises(ValueError, match="relative path"):
             module.create_fresh_branch(
                 branch_name=str(outside_target),
@@ -396,7 +355,7 @@ class TestBranchNamePathSafety:
                 base_ref=DEFAULT_BASE_REF,
             )
         assert not outside_target.exists()
-        assert not (agent_scratch_parent / "claude").exists()
+        assert not (tmp_path / "unused-repo").exists()
 
 
 class TestCreateFreshBranchIntegration:
@@ -409,13 +368,6 @@ class TestCreateFreshBranchIntegration:
         repository_path = build_repo_with_origin(tmp_path / "repo")
         caller_head_before = read_head_branch(repository_path)
         caller_commit_before = read_head_commit(repository_path)
-        agent_scratch_parent = tmp_path / "agent-scratch"
-        monkeypatch.setattr(module.sys, "platform", "linux")
-        monkeypatch.setattr(
-            module.tempfile,
-            "gettempdir",
-            lambda: str(agent_scratch_parent),
-        )
         success_payload = module.create_fresh_branch(
             branch_name="fix/example-one",
             repo_path=repository_path,
@@ -424,7 +376,14 @@ class TestCreateFreshBranchIntegration:
         )
         worktree_path = Path(success_payload[PAYLOAD_KEY_WORKTREE_PATH])
         assert worktree_path.is_dir()
-        assert worktree_path == agent_scratch_parent / "grok" / "fix" / "example-one"
+        assert worktree_path == (
+            repository_path.resolve()
+            / ".claude"
+            / "worktrees"
+            / "grok"
+            / "fix"
+            / "example-one"
+        )
         assert read_head_branch(worktree_path) == "fix/example-one"
         assert read_head_commit(worktree_path) == caller_commit_before
         assert success_payload[PAYLOAD_KEY_BRANCH] == "fix/example-one"
@@ -445,14 +404,10 @@ class TestCreateFreshBranchIntegration:
     ) -> None:
         module = load_create_fresh_branch_module()
         repository_path = build_repo_with_origin(tmp_path / "repo")
-        agent_scratch_parent = tmp_path / "agent-scratch"
-        monkeypatch.setattr(module.sys, "platform", "linux")
-        monkeypatch.setattr(
-            module.tempfile,
-            "gettempdir",
-            lambda: str(agent_scratch_parent),
+        repository_worktree_root = (
+            repository_path.resolve() / ".claude" / "worktrees" / "claude"
         )
-        occupied_path = agent_scratch_parent / "claude" / "fix" / "collision"
+        occupied_path = repository_worktree_root / "fix" / "collision"
         occupied_path.mkdir(parents=True)
         success_payload = module.create_fresh_branch(
             branch_name="fix/collision",
@@ -461,7 +416,7 @@ class TestCreateFreshBranchIntegration:
             base_ref=DEFAULT_BASE_REF,
         )
         worktree_path = Path(success_payload[PAYLOAD_KEY_WORKTREE_PATH])
-        assert worktree_path == agent_scratch_parent / "claude" / "fix" / "collision-2"
+        assert worktree_path == repository_worktree_root / "fix" / "collision-2"
         assert worktree_path.is_dir()
         assert read_head_branch(worktree_path) == "fix/collision"
 
@@ -472,13 +427,6 @@ class TestCreateFreshBranchIntegration:
     ) -> None:
         module = load_create_fresh_branch_module()
         repository_path = build_repo_with_origin(tmp_path / "repo")
-        agent_scratch_parent = tmp_path / "agent-scratch"
-        monkeypatch.setattr(module.sys, "platform", "linux")
-        monkeypatch.setattr(
-            module.tempfile,
-            "gettempdir",
-            lambda: str(agent_scratch_parent),
-        )
         module.create_fresh_branch(
             branch_name="fix/dup",
             repo_path=repository_path,
@@ -515,13 +463,6 @@ class TestCreateFreshBranchIntegration:
         )
         local_main_commit = read_head_commit(repository_path)
         assert local_main_commit != origin_tip_before
-        agent_scratch_parent = tmp_path / "agent-scratch"
-        monkeypatch.setattr(module.sys, "platform", "linux")
-        monkeypatch.setattr(
-            module.tempfile,
-            "gettempdir",
-            lambda: str(agent_scratch_parent),
-        )
         success_payload = module.create_fresh_branch(
             branch_name="fix/bare-base",
             repo_path=repository_path,
@@ -543,13 +484,6 @@ class TestWorktreeBranchTracking:
     ) -> None:
         module = load_create_fresh_branch_module()
         repository_path = build_repo_with_origin(tmp_path / "repo")
-        agent_scratch_parent = tmp_path / "agent-scratch"
-        monkeypatch.setattr(module.sys, "platform", "linux")
-        monkeypatch.setattr(
-            module.tempfile,
-            "gettempdir",
-            lambda: str(agent_scratch_parent),
-        )
         success_payload = module.create_fresh_branch(
             branch_name="fix/no-upstream",
             repo_path=repository_path,
@@ -574,13 +508,6 @@ class TestWorktreeBranchTracking:
             repository_path,
             empty_hooks_path=empty_hooks_path,
         )
-        agent_scratch_parent = tmp_path / "agent-scratch"
-        monkeypatch.setattr(module.sys, "platform", "linux")
-        monkeypatch.setattr(
-            module.tempfile,
-            "gettempdir",
-            lambda: str(agent_scratch_parent),
-        )
         success_payload = module.create_fresh_branch(
             branch_name="feature/silent-push",
             repo_path=repository_path,
@@ -619,13 +546,6 @@ class TestMainCli:
     ) -> None:
         module = load_create_fresh_branch_module()
         repository_path = build_repo_with_origin(tmp_path / "repo")
-        agent_scratch_parent = tmp_path / "agent-scratch"
-        monkeypatch.setattr(module.sys, "platform", "linux")
-        monkeypatch.setattr(
-            module.tempfile,
-            "gettempdir",
-            lambda: str(agent_scratch_parent),
-        )
         monkeypatch.setattr(
             sys,
             "argv",
@@ -697,15 +617,7 @@ class TestMainCli:
     ) -> None:
         module = load_create_fresh_branch_module()
         repository_path = build_repo_with_origin(tmp_path / "repo")
-        agent_scratch_parent = tmp_path / "agent-scratch"
-        agent_scratch_parent.mkdir()
-        escaped_path = agent_scratch_parent / "escape"
-        monkeypatch.setattr(module.sys, "platform", "linux")
-        monkeypatch.setattr(
-            module.tempfile,
-            "gettempdir",
-            lambda: str(agent_scratch_parent),
-        )
+        escaped_path = tmp_path / "escape"
         monkeypatch.setattr(
             sys,
             "argv",
@@ -726,7 +638,7 @@ class TestMainCli:
         assert PAYLOAD_KEY_ERROR in error_payload
         assert "relative path" in error_payload[PAYLOAD_KEY_ERROR]
         assert not escaped_path.exists()
-        assert not (agent_scratch_parent / "claude").exists()
+        assert not (tmp_path / "unused-repo").exists()
 
     def should_print_error_json_for_absolute_branch_name(
         self,
@@ -736,15 +648,7 @@ class TestMainCli:
     ) -> None:
         module = load_create_fresh_branch_module()
         repository_path = build_repo_with_origin(tmp_path / "repo")
-        agent_scratch_parent = tmp_path / "agent-scratch"
-        agent_scratch_parent.mkdir()
         outside_target = tmp_path / "outside-evil"
-        monkeypatch.setattr(module.sys, "platform", "linux")
-        monkeypatch.setattr(
-            module.tempfile,
-            "gettempdir",
-            lambda: str(agent_scratch_parent),
-        )
         monkeypatch.setattr(
             sys,
             "argv",
@@ -765,4 +669,4 @@ class TestMainCli:
         assert PAYLOAD_KEY_ERROR in error_payload
         assert "relative path" in error_payload[PAYLOAD_KEY_ERROR]
         assert not outside_target.exists()
-        assert not (agent_scratch_parent / "claude").exists()
+        assert not (tmp_path / "unused-repo").exists()

package/skills/grok-spawn/SKILL.md

@@ -125,7 +125,6 @@ Shape:
       "tool_profile": "readonly",
       "timeout_seconds": 600,
       "is_repo_only": true,
-      "max_turns": 8,
       "agent_name": null
     }
   ]
@@ -141,11 +140,14 @@ Shape:
 | `prompt_parts` | Ordered absolute paths to part files |
 | `cwd` | Working directory for that worker |
 | `tool_profile` | `readonly` or `build` |
-| `timeout_seconds` | Per-worker timeout (default 600) |
+| `timeout_seconds` | Per-worker timeout (default 600, ceiling 5400). A spec asking for more is refused |
 | `is_repo_only` | Readonly only: when true, also pass `--disable-web-search` |
-| `max_turns` | Turn cap (default 8) |
 | `agent_name` | Optional `--agent` name, or `null` |
 
+Workers run with no turn cap. The timeout is the only bound on a worker's
+length, and a worker that hits it is killed with its whole process tree and
+reported as `timeout`.
+
 Put the spec file under the run state directory (or any path you pass to
 `--spec`).
 

package/skills/grok-spawn/reference/flag-profiles.md

@@ -20,10 +20,12 @@ The headless runner always passes:
 | `--cwd` | Worker `cwd` from the batch spec |
 | `--output-format` | `json` |
 | `--always-approve` | present (auto-approve tool runs) |
-| `--max-turns` | Worker `max_turns` (default `8`) |
 | `--leader-socket` | Unique per-worker socket path under the run state dir |
 | `--debug-file` | Unique per-worker debug log (batch launcher adds this) |
 
+The runner passes no `--max-turns`. Worker length is bounded by the per-worker
+timeout alone. The preflight ping keeps its own single-turn cap.
+
 Optional:
 
 | Flag | When |

package/skills/orchestrator/SKILL.md

@@ -64,6 +64,16 @@ schedule prompt must carry it: `/orchestrator-refresh --run-slug SLUG`.
 
 ### Single-pending re-arm protocol (all hosts)
 
+**The re-arm never interrupts the run.** Every "stop" in the five steps
+below ends the *re-arm* and nothing else: the session returns to
+orchestrating in the same turn. Arming a delayed wake schedules a later
+reminder; it neither ends the turn nor pauses in-flight executors, and
+the session never waits for the refresh to fire before it carries on.
+When a create fails, keep orchestrating and re-arm at the next natural
+break. When the denial is `rearm_already_pending`, a refresh is already
+queued — keep orchestrating and arm nothing further this turn; the next
+refresh firing clears the latch and arms again.
+
 Exactly one delayed refresh may be outstanding. **Create then claim**
 (order matters on Claude: PreToolUse denies `ScheduleWakeup` when the
 slot is already pending).
@@ -105,11 +115,11 @@ pending, or when the tool is `CronCreate`.
 1. **Invocation guard.** One `/orchestrator` per session. When a refresh
    one-shot is already queued (`should-reschedule` exits 1 with
    `rearm_already_pending`), do not stack a second: reuse the live
-   advisor bind and go to step 6 (Orchestrate). Skip steps 4–5 — status
-   is already active and a re-arm is already latched; re-registering
-   would attempt a redundant host schedule. (Re-asserting
-   `set --status active` preserves `rearm_pending` when already active,
-   but still do not run step 5.)
+   advisor bind, skip step 4 and the re-arm half of step 5, and carry on
+   from step 5's dispatch — status is already active and a re-arm is
+   already latched, so a second registration would stack a duplicate
+   host schedule. (Re-asserting `set --status active` preserves
+   `rearm_pending` when already active, but still do not re-arm.)
 2. **Bind the shared advisor before any executor.** Follow
    [`_shared/advisor/advisor-protocol.md`](../../_shared/advisor/advisor-protocol.md)
    end to end: detect the host profile, compute the floor from the
@@ -123,11 +133,15 @@ pending, or when the tool is `CronCreate`.
 3. **Write the run artifacts** (next section) before the first spawn.
 4. **Activate status_gate** when the first open ledger task exists:
    `python scripts/status_gate.py set --status active`.
-5. **Register the discipline reminder** via the single-pending re-arm
-   protocol (cancel matching → `should-reschedule` → one non-recurring
-   delayed wake → `claim-rearm`; default delay about 2700s).
+5. **Dispatch the first task with its ticket** (Spawn ticket section),
+   **then register the discipline reminder** via the single-pending
+   re-arm protocol (cancel matching → `should-reschedule` → one
+   non-recurring delayed wake → `claim-rearm`; default delay about
+   2700s). Spawn before you arm, so the run is already moving, and go
+   straight on to step 6 in the same turn — the armed wake is a later
+   reminder, not the next thing to wait for.
 6. **Orchestrate.** Hold the plan and the user conversation. Spawn each
-   task with a ticket (Spawn ticket section), keep driving while
+   remaining task with a ticket (Spawn ticket section), keep driving while
    executors work, and keep the ledger reconciled (Task ledger
    discipline).
 7. **Consult the advisor at hard decisions.** The trigger list, consult

package/skills/orchestrator-refresh/SKILL.md

@@ -33,7 +33,7 @@ python <status_gate.py> begin-firing [--run-slug SLUG]
 
 | Exit | Action |
 |---|---|
-| **1** | Stop. Cancel matching host schedules for `/orchestrator-refresh` if the host allows. Report inactive/done. **Do not** re-arm. Do not spawn. |
+| **1** | End the refresh. Cancel matching host schedules for `/orchestrator-refresh` if the host allows. Report inactive/done. **Do not** re-arm. Do not spawn. Any work already in flight keeps running. |
 | **0** | Latch cleared. Continue with steps 1–6. |
 
 ### 0b. Done after ledger (step 1)
@@ -47,6 +47,25 @@ python <status_gate.py> set --status done [--run-slug SLUG]
 
 Cancel matching host schedules; stop without re-arming.
 
+## The refresh never interrupts the run
+
+A refresh firing reinforces discipline alongside work already in flight.
+It never pauses, cancels, or waits on a running executor. Reconcile the
+ledger, re-assert the routing, re-arm once, and hand control straight back
+to the work in progress.
+
+Inside the re-arm protocol (step 6), every "stop" ends the *re-arm* and
+nothing else. A `should-reschedule` exit 1 means no schedule is created this
+firing, and a `claim-rearm` exit 1 means the schedule just created is
+cancelled; either way the session keeps orchestrating in the same turn.
+
+Two stops end the whole firing, and both leave running executors alone:
+`begin-firing` exit 1 (step 0a) and the done branch (step 0b). Each means the
+run is finished, not active, or has no readable status file, so the refresh
+reports and adds nothing further. A fail-closed advisor bind (step 3) stops
+advisor consultation alone; the firing still reconciles the ledger, re-arms
+once, and reports the unreachable advisor.
+
 ## Discipline steps
 
 1. **Reconcile the task ledger first.** Call `TaskList` after the gate.

package/skills/privacy-hygiene/reference/sweep-procedure.md

@@ -49,7 +49,7 @@ Review each hit. Ignore:
 ## 4. Re-check before commit / post
 
 - Stage only clean files
-- Prefer `--body-file` for `gh` posts (also required by the gh-body-file rule)
+- Prefer `--body-file` for `gh` posts (also required by the gh-cli-conventions rule)
 - Let `pii_prevention_blocker` re-run on the next Write / commit / post
 
 ## Accepted residual (do not over-scrub)

package/skills/session-log/SKILL.md

@@ -25,7 +25,7 @@ Sessions come in many shapes — convergence loops, feature builds, research div
 - **The `Artifact` tool wraps the file in a document skeleton at publish time.** It adds `<!doctype html>…<head>…</head><body>` around whatever the file holds — write page content only (a `<title>`, a `<style>` block, and the body markup). Do not include `<!DOCTYPE>`, `<html>`, `<head>`, or `<body>` tags in the file itself.
 - **The `Artifact` tool redeploys to the same URL only within the current run.** Editing the session's HTML file in a later step of this same skill run and calling `Artifact` again does not mint a new URL — it updates the same published page in place. A fresh session has no memory of an artifact's URL from an earlier run, so republishing a session report written in a prior session always mints a new URL (there is no other way to target the old one without the user supplying it).
 - **Vault paths sit outside `.claude/`.** Headless vault paths (e.g., `$OBSIDIAN_VAULT_PATH`) resolve outside the project tree. Session reports use HTML regardless of vault location — the Artifact tool needs a written file to publish.
-- **Sessions describe current state by convention.** The state_description_blocker hook does not scan .html, but the rule at `~/.claude/rules/no-historical-clutter.md` applies as a writing standard — skip historical and comparative language when composing the report; the rule file lists the full trigger set.
+- **Sessions describe current state by convention.** The state_description_blocker hook does not scan .html, but the rule at `~/.claude/rules/doc-prose-cuts.md` applies as a writing standard — skip historical and comparative language when composing the report; the rule file lists the full trigger set.
 - **`write_existing_file_blocker` rejects Write on existing paths.** Use Write only when creating a fresh session report; use Edit for the vault-context append in step 3.
 - **Obsidian frontmatter index is HTML-blind.** Obsidian's native YAML-frontmatter parser reads only `.md` files. HTML files do not appear in Obsidian's frontmatter index. Search by content still works; search by `type: session-report` does not.
 

package/rules/claude-md-orphan-file.md

@@ -1,28 +0,0 @@
----
-paths:
-  - "**/CLAUDE.md"
----
-
-# Orphan File Reference in a Per-Directory CLAUDE.md
-
-**When this applies:** Any Write, Edit, or MultiEdit to a file named `CLAUDE.md` that lists files in a markdown table whose first column names each file in backticks, or that shows run commands invoking those files inside fenced code blocks.
-
-## Rule
-
-Every bare filename a per-directory `CLAUDE.md` names points at a file that exists in the directory subtree the `CLAUDE.md` describes — both the filenames its table cells list and the scripts its fenced run commands invoke (`python script.py`). A table cell or a run command naming a file that exists nowhere in that subtree points a reader at something that is not there: the doc claims a file the directory does not hold.
-
-When you add a table row or a run command, the file it names already exists in this directory or a subdirectory of it. When you remove a file, drop the row and the run command that named it.
-
-## What the gate checks
-
-The `claude_md_orphan_file_blocker.py` hook runs on every Write, Edit, and MultiEdit whose target basename is `CLAUDE.md`. It:
-
-1. Reads the content the tool would leave on disk. For a Write that is the full `content`. For an Edit or MultiEdit it reconstructs the post-edit file — the existing on-disk file with the replacements applied — and also notes which orphans the file already held before the edit, so a pre-existing orphan on an untouched line is excluded and only an orphan the edit introduces is reported; when the existing file cannot be read, it scans the raw `new_string` fragment(s) instead.
-2. Collects two kinds of referenced filename. Table cells: the first column of each markdown table row **outside** a fenced code block, keeping cells that name a bare filename wrapped in backticks, no path separator, not a slash-command, ending in a known file extension (`.py`, `.md`, `.json`, `.mjs`, `.js`, `.ts`, `.ps1`, `.cmd`, `.ahk`, `.yml`, `.yaml`, `.sh`, `.txt`, `.cfg`, `.toml`, `.ini`). Run commands: each line **inside** a fenced code block (between a ``` or `~~~` fence pair) that invokes an interpreter (`python`, `python.exe`, `python3`, `node`, `pwsh`, `powershell`, `bash`, `sh`, `ruby`, `perl`) on a script, taking that script's basename when it ends in `.py`, `.mjs`, `.js`, `.ts`, `.ps1`, `.sh`, `.rb`, or `.pl`. A fenced *table row* is an example, not a live listing, so it contributes no table-cell filename; a fenced *run command* is the contract a reader runs, so its script filename is checked.
-3. Blocks the write when a referenced filename — from a table cell or a fenced run command — exists nowhere under the scan root — the `CLAUDE.md` directory's parent, which covers the directory, its subdirectories, and its siblings. A filesystem error that halts the whole subtree walk fails open (the write proceeds), so an unreadable tree never blocks a write.
-
-The check stays quiet for a target that is not a `CLAUDE.md`, for a table cell that holds a path, a subdirectory ending in `/`, or a slash-command, for a table row inside a fenced code block, for an inline `python x.py` mention outside a fence (prose, not a runnable contract), and for a table whose content names an explicit relative-path source (a `../` token), since that table documents files that sit outside the subtree by design.
-
-## Why this is a hook, not a lint pass
-
-A table row or a run command that names an absent file reads as a contract: a reader trusts the listing to map the directory and trusts the shown command to run. A wrong row sends the reader looking for a file that is not there; a stale run command fails the moment the reader runs it. Both erode trust in every other entry. Catching them as each line is written keeps the doc and the directory in step.

package/rules/cleanup-command-forms.md

@@ -1,23 +0,0 @@
-# Cleanup Command Forms
-
-Never use bash `rm` in any form to clean up. The `destructive_command_blocker` hook watches every Bash-tool command and matches `rm -rf` (and the rest of the destructive patterns) as raw text. It allows an `rm` without a prompt only for a narrow set of shapes it can prove safe: an `rm` whose every target is an absolute path under the OS temp root, `/tmp`, `/temp`, or a worktrees directory — standalone, or in a chain whose other segments are plain reporting commands such as `echo` or `cat`; an `rm` run from an ephemeral working directory; and an `rm` whose every target sits inside `~/.claude`. It falls through to a permission prompt on anything outside that set: a `$`, `$(...)`, or backtick expansion whose value it cannot resolve, a target it cannot place in a safe directory, a glob basename, or a string-executing wrapper (`bash -c 'rm -rf …'`). In a background or auto-mode run no human can answer that prompt, so the call stalls.
-
-Remove files with these forms, which the hook never prompts on:
-
-- **Scratch and probe files:** the PowerShell tool — `Remove-Item -Recurse -Force -Confirm:$false <absolute path>`. The hook watches only the Bash tool, so a PowerShell removal never reaches it. A file left in the OS temp dir or `$CLAUDE_JOB_DIR/tmp` is ephemeral and needs no explicit removal.
-- **Worktrees:** `git worktree remove --force <path>`. This matches no destructive pattern.
-- **When bash `rm` is unavoidable:** one standalone `rm` command, an absolute literal path under the OS temp root or a worktrees directory, no chaining, no variables, no globs. The hook auto-allows this shape without a prompt.
-
-## Every subagent prompt carries the rule
-
-A prompt-delivered directive reaches only the agent that gets it. An agent that spawns its own workers — review lenses, fix agents, verifiers — copies this line into every subagent prompt it issues, so a grandchild cleaning up its own probe file uses an allowed form:
-
-> Never use bash rm in any form. Delete scratch/probe files with the PowerShell tool (Remove-Item -Recurse -Force -Confirm:$false <absolute path>), or leave them in the OS temp dir; remove worktrees only via git worktree remove --force.
-
-Prefer that a child leaves its scratch files in place for the parent to remove at teardown with `Remove-Item`.
-
-## Sibling rules
-
-- [`no-inline-destructive-literals`](no-inline-destructive-literals.md) — keep a destructive literal out of the Bash command string even when it rides only as data.
-- [`cleanup-temp-files`](cleanup-temp-files.md) — remove the scratch files a task created once the task is done.
-- [`windows-filesystem-safe`](windows-filesystem-safe.md) — the safe `rmtree` / `force_rmtree` patterns for read-only Windows files.

package/rules/code-reviews.md

@@ -1,11 +0,0 @@
-# Responding to Code Reviews
-
-**When this applies:** GitHub PR review feedback on a branch you are fixing.
-
-**MANDATORY PROTOCOL:**
-
-1. Fetch ALL reviewer comments BEFORE any fixes
-2. Create TodoWrite checklist - One item per comment
-3. Fix systematically - Mark each todo complete
-4. Reply to EACH comment inline
-5. Create ONE review fix commit - DO NOT squash with original

package/rules/env-var-table-code-drift.md

@@ -1,10 +0,0 @@
----
-paths:
-  - "**/*.md"
----
-
-# Env-Var Summary Table Names a Code File That Reads the Variable
-
-Every row in an env-var summary table pairs an UPPER_SNAKE variable with a code-file path that reads it — written as `` | `GOOGLE_APPLICATION_CREDENTIALS` | `auth/google_auth.py` | ... | ``. When a code change removes the last read of a variable from a file, the same change drops or corrects the table row that names that file.
-
-`env_var_table_code_drift_blocker.py` (PreToolUse on Write|Edit|MultiEdit of `.md`) blocks a row whose named code file exists yet never references the variable, and names the fix. For an Edit, drift a file already held on an untouched row is excluded; a row whose code file resolves nowhere stays quiet (the hook cannot prove the drift).

package/rules/gh-body-file.md

@@ -1,5 +0,0 @@
-# gh --body-file Rule
-
-Every `gh` command carrying markdown body content (`gh pr create/edit/comment/review`, `gh issue create/edit/comment`) uses `--body-file <path>` with a temp file — never a `--body`/`-b` string, where backticks land on GitHub as literal `\``. Write the temp file BOM-free: `[IO.File]::WriteAllText($bodyPath, $body, [Text.UTF8Encoding]::new($false))`. MCP GitHub tools take `body` as a structured parameter and are unaffected.
-
-`gh_body_arg_blocker.py` (PreToolUse on Bash) blocks `--body <arg>` and returns the corrective message.

package/rules/gh-paginate.md

@@ -1,3 +0,0 @@
-# gh API Pagination
-
-Every `gh api` read of a paginated GitHub list endpoint (PR `reviews`/`comments`/`files`, issue `comments`, `pulls`, `issues`) uses `--paginate --slurp` piped to **external** `jq` — `gh`'s built-in `--jq` runs per page, so cross-page operations like `sort_by | last` give wrong-but-confident results. Single-object endpoints (`pulls/<n>`, `issues/<n>`) skip pagination and may use `--jq` directly. For a newest-first walk, sort the slurped array and take the last element; for single-page bounds, cap with a `per_page` query parameter.

package/rules/hook-prose-matches-detector.md

@@ -1,15 +0,0 @@
----
-paths: **/hooks/**/*.py
----
-
-# Hook Prose Matches Its Detector
-
-A hook's docstring lead narrative and its `CORRECTIVE_MESSAGE` describe exactly the shapes the detector flags — no broader trigger surface than the regex enforces.
-
-`hook_prose_detector_consistency` (PreToolUse on Write|Edit of hook modules and `*_constants.py` companions) blocks prose that claims a trigger the detector never fires on, and names the fix.
-
-## Judgment
-
-After writing a hook, ask: would a token that matches every word of this message actually trip the detector? When the message names a shape the regex skips, rewrite the message to name only what the regex catches.
-
-The path-shape case is the common overstatement: a detector that keys off a path separator must not claim it blocks an "output-key segment". The corrective message spells the rewrite.

package/rules/no-historical-clutter.md

@@ -1,26 +0,0 @@
----
-paths:
-  - "**/*.md"
-  - "**/*.py"
-  - "**/*.mjs"
-  - "**/*.js"
-  - "**/*.ts"
-  - "**/*.ps1"
-  - "**/*.sh"
----
-
-# No Historical Clutter in Documentation or Comments
-
-Never reference removed implementations, old defaults, prior behaviors, or earlier contracts when updating documentation or comments. The current state is all that matters. A module or function docstring carries the same describe-current-state-only contract as a `.md` file.
-
-`state_description_blocker` (PreToolUse on Write|Edit) blocks historical and comparative phrases in `.md` prose, code comments, and Python docstrings; a phrase wrapped in double quotes or backticks inside a docstring counts as a mention and is skipped. The denial names the matched phrases and shows a rewrite example.
-
-## What stays allowed
-
-- Comparisons to alternatives that still exist (for example, "use `--paginate --slurp | jq`, not `--jq` alone")
-- Rationale that explains why a pattern is wrong in terms of present behavior (for example, "`--jq` runs per-page, so cross-page operations produce wrong results")
-- References to external sources for defects that still exist (for example, gh CLI #10459)
-
-## The test
-
-After writing, ask: if someone reads this a year from now with no knowledge of earlier states, does every sentence still make sense and add value? If a sentence only helps someone who knew an earlier state, delete it.

package/rules/no-inline-destructive-literals.md

@@ -1,9 +0,0 @@
-# No Inline Destructive-Command Literals in Bash
-
-The `destructive_command_blocker` PreToolUse hook matches destructive patterns (`rm -rf`, `git reset --hard`, `dd`, `mkfs`, `chmod -R`, fork bombs) as raw text anywhere in a Bash-tool command, with no quote-awareness — so a destructive literal carried only as data (a commit message, a PR/issue body, an echoed string, a `python -c` / `node -e` / `awk` argument, a heredoc) trips the confirmation prompt even though the shell never executes it. In a background or auto-mode run no human can answer that prompt, so the call stalls.
-
-Keep destructive literals out of the Bash command string:
-
-- Bodies that describe destructive-command behavior go in a file passed by path — `git commit -F <file>`, `gh ... --body-file <file>` (see [`gh-body-file`](gh-body-file.md)) — never `git commit -m` / `gh ... -b`.
-- To exercise or verify the blocker (or any hook), run the committed test suite (`python -m pytest <test_file>`), which passes the command strings as in-language data — never an inline `python -c` harness.
-- Genuine cleanup targets the OS temp dir or `$CLAUDE_JOB_DIR/tmp` (auto-allowed as ephemeral), never a repository or worktree path.