claude-dev-env 2.0.0 → 2.0.2

package/hooks/blocking/test_verified_commit_docs_delta.py

@@ -0,0 +1,176 @@
+"""Gate behavior for docs-only deltas and the cross-work-tree deny message.
+
+Each test builds a real git repository with a real origin remote and drives
+``deny_reason_for_directory`` — the same decision the verified_commit_gate hook
+runs — so the docs-only exemption, the docs-after-verified-code block, and the
+denial message's work-tree keying are asserted against live git state.
+"""
+
+import importlib.util
+import pathlib
+import subprocess
+import sys
+
+import pytest
+
+_HOOK_DIR = pathlib.Path(__file__).parent
+if str(_HOOK_DIR) not in sys.path:
+    sys.path.insert(0, str(_HOOK_DIR))
+
+gate_spec = importlib.util.spec_from_file_location(
+    "verified_commit_gate",
+    _HOOK_DIR / "verified_commit_gate.py",
+)
+assert gate_spec is not None
+assert gate_spec.loader is not None
+gate_module = importlib.util.module_from_spec(gate_spec)
+gate_spec.loader.exec_module(gate_module)
+deny_reason_for_directory = gate_module.deny_reason_for_directory
+
+store_spec = importlib.util.spec_from_file_location(
+    "verification_verdict_store",
+    _HOOK_DIR / "verification_verdict_store.py",
+)
+assert store_spec is not None
+assert store_spec.loader is not None
+store_module = importlib.util.module_from_spec(store_spec)
+store_spec.loader.exec_module(store_module)
+resolve_merge_base = store_module.resolve_merge_base
+branch_surface_manifest = store_module.branch_surface_manifest
+manifest_sha256 = store_module.manifest_sha256
+write_verdict = store_module.write_verdict
+
+PRODUCTION_SOURCE = "def add(left: int, right: int) -> int:\n    return left + right\n"
+BEHAVIORAL_EDIT_SOURCE = "def add(left: int, right: int) -> int:\n    return left - right\n"
+
+
+def _run_git(repo_dir: pathlib.Path, *git_arguments: str) -> None:
+    subprocess.run(
+        ["git", "-C", str(repo_dir), *git_arguments],
+        check=True,
+        capture_output=True,
+        text=True,
+    )
+
+
+def _isolate_home(monkeypatch: pytest.MonkeyPatch, fake_home: pathlib.Path) -> None:
+    home_text = str(fake_home)
+    monkeypatch.setenv("HOME", home_text)
+    monkeypatch.setenv("USERPROFILE", home_text)
+    monkeypatch.delenv("HOMEDRIVE", raising=False)
+    monkeypatch.delenv("HOMEPATH", raising=False)
+
+
+def _empty_hooks_dir(tmp_path: pathlib.Path) -> pathlib.Path:
+    hooks_dir = tmp_path / "nohooks"
+    hooks_dir.mkdir(exist_ok=True)
+    return hooks_dir
+
+
+def _empty_transcript(tmp_path: pathlib.Path) -> pathlib.Path:
+    transcript_path = tmp_path / "projects" / "demo" / "sess1.jsonl"
+    transcript_path.parent.mkdir(parents=True, exist_ok=True)
+    transcript_path.write_text("", encoding="utf-8")
+    return transcript_path
+
+
+def _init_pushed_repo(tmp_path: pathlib.Path) -> pathlib.Path:
+    origin_dir = tmp_path / "origin.git"
+    work_dir = tmp_path / "work"
+    work_dir.mkdir()
+    subprocess.run(
+        ["git", "init", "--bare", "--initial-branch=main", str(origin_dir)],
+        check=True,
+        capture_output=True,
+        text=True,
+    )
+    _run_git(work_dir, "init", "--initial-branch=main")
+    _run_git(work_dir, "config", "user.email", "tests@example.com")
+    _run_git(work_dir, "config", "user.name", "Docs Delta Tests")
+    _run_git(work_dir, "config", "core.hooksPath", str(_empty_hooks_dir(tmp_path)))
+    (work_dir / "app.py").write_text(PRODUCTION_SOURCE, encoding="utf-8")
+    (work_dir / "README.md").write_text("# base\n", encoding="utf-8")
+    _run_git(work_dir, "add", "-A")
+    _run_git(work_dir, "commit", "-m", "base")
+    _run_git(work_dir, "remote", "add", "origin", str(origin_dir))
+    _run_git(work_dir, "push", "-u", "origin", "main")
+    return work_dir
+
+
+def _make_docs_only_repo(tmp_path: pathlib.Path) -> pathlib.Path:
+    work_dir = _init_pushed_repo(tmp_path)
+    (work_dir / "README.md").write_text("# base\n\nUpdated docs.\n", encoding="utf-8")
+    return work_dir
+
+
+def _make_behavioral_code_repo(tmp_path: pathlib.Path) -> pathlib.Path:
+    work_dir = _init_pushed_repo(tmp_path)
+    (work_dir / "app.py").write_text(BEHAVIORAL_EDIT_SOURCE, encoding="utf-8")
+    return work_dir
+
+
+def _live_surface_hash(work_dir: pathlib.Path) -> str:
+    merge_base_sha = resolve_merge_base(str(work_dir))
+    assert merge_base_sha is not None
+    surface_manifest_text = branch_surface_manifest(str(work_dir), merge_base_sha)
+    assert surface_manifest_text is not None
+    return manifest_sha256(surface_manifest_text)
+
+
+def test_pure_docs_only_branch_is_allowed_without_verdict(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: pathlib.Path
+) -> None:
+    fake_home = tmp_path / "home"
+    fake_home.mkdir()
+    _isolate_home(monkeypatch, fake_home)
+    work_dir = _make_docs_only_repo(tmp_path)
+    transcript_path = _empty_transcript(tmp_path)
+    assert deny_reason_for_directory(str(work_dir), str(transcript_path)) is None
+
+
+def test_readme_change_after_verified_code_commit_is_denied(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: pathlib.Path
+) -> None:
+    fake_home = tmp_path / "home"
+    fake_home.mkdir()
+    _isolate_home(monkeypatch, fake_home)
+    work_dir = _make_behavioral_code_repo(tmp_path)
+    code_surface_hash = _live_surface_hash(work_dir)
+    write_verdict(str(work_dir), code_surface_hash, True, [], "agent-x")
+    transcript_path = _empty_transcript(tmp_path)
+    assert deny_reason_for_directory(str(work_dir), str(transcript_path)) is None
+    _run_git(work_dir, "add", "-A")
+    _run_git(work_dir, "commit", "-m", "verified code change")
+    (work_dir / "README.md").write_text("# added after verification\n", encoding="utf-8")
+    deny_reason = deny_reason_for_directory(str(work_dir), str(transcript_path))
+    assert deny_reason is not None
+    assert "VERIFIED_COMMIT_GATE" in deny_reason
+
+
+def test_readme_added_beside_unverified_code_is_denied(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: pathlib.Path
+) -> None:
+    fake_home = tmp_path / "home"
+    fake_home.mkdir()
+    _isolate_home(monkeypatch, fake_home)
+    work_dir = _make_behavioral_code_repo(tmp_path)
+    (work_dir / "README.md").write_text("# docs beside code\n", encoding="utf-8")
+    transcript_path = _empty_transcript(tmp_path)
+    deny_reason = deny_reason_for_directory(str(work_dir), str(transcript_path))
+    assert deny_reason is not None
+    assert "VERIFIED_COMMIT_GATE" in deny_reason
+
+
+def test_deny_reason_for_directory_names_worktree_keying_and_remedy(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: pathlib.Path
+) -> None:
+    fake_home = tmp_path / "home"
+    fake_home.mkdir()
+    _isolate_home(monkeypatch, fake_home)
+    work_dir = _make_behavioral_code_repo(tmp_path)
+    transcript_path = _empty_transcript(tmp_path)
+    deny_reason = deny_reason_for_directory(str(work_dir), str(transcript_path))
+    assert deny_reason is not None
+    lowered_reason = deny_reason.lower()
+    assert "work tree" in lowered_reason
+    assert "run this command from the work tree" in lowered_reason

package/hooks/blocking/test_verifier_verdict_minter.py

@@ -69,6 +69,36 @@ def _write_sidecar(agent_transcript_file: pathlib.Path, agent_type: str) -> None
     )
 
 
+def _write_verdict_transcript(agent_transcript_file: pathlib.Path, verdict_body: str) -> None:
+    verdict_text = f"ok\n```verdict\n{verdict_body}\n```\n"
+    agent_transcript_file.write_text(
+        json.dumps(
+            {
+                "type": "assistant",
+                "message": {"content": [{"type": "text", "text": verdict_text}]},
+            }
+        )
+        + "\n",
+        encoding="utf-8",
+    )
+
+
+def _make_repo(tmp_path: pathlib.Path) -> pathlib.Path:
+    repo_root = tmp_path / "repo"
+    repo_root.mkdir()
+    return repo_root
+
+
+def _mint_payload(
+    agent_transcript_file: pathlib.Path, repo_root: pathlib.Path, agent_id: str
+) -> dict[str, str]:
+    return {
+        "agent_transcript_path": str(agent_transcript_file),
+        "cwd": str(repo_root),
+        "agent_id": agent_id,
+    }
+
+
 def test_resolves_subagent_type_from_sidecar(tmp_path: pathlib.Path) -> None:
     agent_transcript = tmp_path / "agent-7.jsonl"
     agent_transcript.write_text("", encoding="utf-8")
@@ -141,7 +171,7 @@ def test_verifier_type_without_a_verdict_mints_nothing(tmp_path: pathlib.Path) -
     assert mint_for_payload(payload) is None
 
 
-def _init_repo_with_upstream_and_edit(repo_root: pathlib.Path) -> None:
+def _init_repo_with_upstream(repo_root: pathlib.Path) -> None:
     subprocess.run(["git", "-C", str(repo_root), "init", "-q"], check=True)
     subprocess.run(
         ["git", "-C", str(repo_root), "config", "user.email", "verifier@test"], check=True
@@ -151,37 +181,20 @@ def _init_repo_with_upstream_and_edit(repo_root: pathlib.Path) -> None:
     subprocess.run(["git", "-C", str(repo_root), "add", "-A"], check=True)
     subprocess.run(["git", "-C", str(repo_root), "commit", "-qm", "init"], check=True)
     subprocess.run(["git", "-C", str(repo_root), "branch", "-f", "origin/main", "HEAD"], check=True)
+
+
+def _init_repo_with_upstream_and_edit(repo_root: pathlib.Path) -> None:
+    _init_repo_with_upstream(repo_root)
     (repo_root / "module.py").write_text("answer = 2\n", encoding="utf-8")
 
 
 def test_clean_verifier_verdict_mints_a_verdict_file(tmp_path: pathlib.Path) -> None:
-    repo_root = tmp_path / "repo"
-    repo_root.mkdir()
+    repo_root = _make_repo(tmp_path)
     _init_repo_with_upstream_and_edit(repo_root)
     agent_transcript = tmp_path / "agent-7.jsonl"
-    agent_transcript.write_text(
-        json.dumps(
-            {
-                "type": "assistant",
-                "message": {
-                    "content": [
-                        {
-                            "type": "text",
-                            "text": 'ok\n```verdict\n{"all_pass": true, "findings": []}\n```\n',
-                        }
-                    ]
-                },
-            }
-        )
-        + "\n",
-        encoding="utf-8",
-    )
+    _write_verdict_transcript(agent_transcript, '{"all_pass": true, "findings": []}')
     _write_sidecar(agent_transcript, MINTING_AGENT_TYPE)
-    payload = {
-        "agent_transcript_path": str(agent_transcript),
-        "cwd": str(repo_root),
-        "agent_id": "a02b9583eedc74093",
-    }
+    payload = _mint_payload(agent_transcript, repo_root, "a02b9583eedc74093")
     verdict_path = mint_for_payload(payload)
     try:
         assert verdict_path is not None
@@ -199,7 +212,8 @@ def _deny_rules() -> list[str]:
 
 
 def test_settings_deny_verdict_directory_write() -> None:
-    assert "Write($HOME/.claude/verification/**)" in _deny_rules()
+    assert "Edit($HOME/.claude/verification/**)" in _deny_rules()
+    assert "Write($HOME/.claude/verification/**)" not in _deny_rules()
 
 
 def test_settings_deny_verdict_directory_edit() -> None:
@@ -209,87 +223,28 @@ def test_settings_deny_verdict_directory_edit() -> None:
 def test_minter_refuses_when_attested_hash_equals_empty_surface_hash(
     tmp_path: pathlib.Path,
 ) -> None:
-    repo_root = tmp_path / "repo"
-    repo_root.mkdir()
+    repo_root = _make_repo(tmp_path)
     _init_repo_with_upstream_and_edit(repo_root)
     attested_empty = empty_surface_hash()
     verdict_fence = json.dumps(
         {"all_pass": True, "findings": [], "manifest_sha256": attested_empty}
     )
     agent_transcript = tmp_path / "agent-7.jsonl"
-    agent_transcript.write_text(
-        json.dumps(
-            {
-                "type": "assistant",
-                "message": {
-                    "content": [
-                        {
-                            "type": "text",
-                            "text": f"ok\n```verdict\n{verdict_fence}\n```\n",
-                        }
-                    ]
-                },
-            }
-        )
-        + "\n",
-        encoding="utf-8",
-    )
+    _write_verdict_transcript(agent_transcript, verdict_fence)
     _write_sidecar(agent_transcript, MINTING_AGENT_TYPE)
-    payload = {
-        "agent_transcript_path": str(agent_transcript),
-        "cwd": str(repo_root),
-        "agent_id": "empty-surface-1",
-    }
+    payload = _mint_payload(agent_transcript, repo_root, "empty-surface-1")
     assert mint_for_payload(payload) is None
 
 
 def test_minter_refuses_when_recomputed_surface_is_empty(
     tmp_path: pathlib.Path,
 ) -> None:
-    repo_root = tmp_path / "repo"
-    repo_root.mkdir()
-    subprocess.run(["git", "-C", str(repo_root), "init", "-q"], check=True)
-    subprocess.run(
-        ["git", "-C", str(repo_root), "config", "user.email", "verifier@test"],
-        check=True,
-    )
-    subprocess.run(
-        ["git", "-C", str(repo_root), "config", "user.name", "verifier"],
-        check=True,
-    )
-    (repo_root / "module.py").write_text("answer = 1\n", encoding="utf-8")
-    subprocess.run(["git", "-C", str(repo_root), "add", "-A"], check=True)
-    subprocess.run(
-        ["git", "-C", str(repo_root), "commit", "-qm", "init"], check=True
-    )
-    subprocess.run(
-        ["git", "-C", str(repo_root), "branch", "-f", "origin/main", "HEAD"],
-        check=True,
-    )
+    repo_root = _make_repo(tmp_path)
+    _init_repo_with_upstream(repo_root)
     agent_transcript = tmp_path / "agent-7.jsonl"
-    agent_transcript.write_text(
-        json.dumps(
-            {
-                "type": "assistant",
-                "message": {
-                    "content": [
-                        {
-                            "type": "text",
-                            "text": 'ok\n```verdict\n{"all_pass": true, "findings": []}\n```\n',
-                        }
-                    ]
-                },
-            }
-        )
-        + "\n",
-        encoding="utf-8",
-    )
+    _write_verdict_transcript(agent_transcript, '{"all_pass": true, "findings": []}')
     _write_sidecar(agent_transcript, MINTING_AGENT_TYPE)
-    payload = {
-        "agent_transcript_path": str(agent_transcript),
-        "cwd": str(repo_root),
-        "agent_id": "empty-recompute-1",
-    }
+    payload = _mint_payload(agent_transcript, repo_root, "empty-recompute-1")
     assert mint_for_payload(payload) is None
 
 
@@ -297,23 +252,7 @@ def test_resolves_none_when_sidecar_absent_even_with_verdict_fence(
     tmp_path: pathlib.Path,
 ) -> None:
     agent_transcript = tmp_path / "agent-7.jsonl"
-    agent_transcript.write_text(
-        json.dumps(
-            {
-                "type": "assistant",
-                "message": {
-                    "content": [
-                        {
-                            "type": "text",
-                            "text": 'ok\n```verdict\n{"all_pass": true, "findings": []}\n```\n',
-                        }
-                    ]
-                },
-            }
-        )
-        + "\n",
-        encoding="utf-8",
-    )
+    _write_verdict_transcript(agent_transcript, '{"all_pass": true, "findings": []}')
     payload = {"agent_transcript_path": str(agent_transcript)}
     assert resolved_subagent_type(payload) is None
 
@@ -321,67 +260,25 @@ def test_resolves_none_when_sidecar_absent_even_with_verdict_fence(
 def test_does_not_mint_when_sidecar_absent_but_transcript_has_verdict(
     tmp_path: pathlib.Path,
 ) -> None:
-    repo_root = tmp_path / "repo"
-    repo_root.mkdir()
+    repo_root = _make_repo(tmp_path)
     _init_repo_with_upstream_and_edit(repo_root)
     agent_transcript = tmp_path / "agent-7.jsonl"
-    agent_transcript.write_text(
-        json.dumps(
-            {
-                "type": "assistant",
-                "message": {
-                    "content": [
-                        {
-                            "type": "text",
-                            "text": 'ok\n```verdict\n{"all_pass": true, "findings": []}\n```\n',
-                        }
-                    ]
-                },
-            }
-        )
-        + "\n",
-        encoding="utf-8",
-    )
-    payload = {
-        "agent_transcript_path": str(agent_transcript),
-        "cwd": str(repo_root),
-        "agent_id": "no-sidecar-1",
-    }
+    _write_verdict_transcript(agent_transcript, '{"all_pass": true, "findings": []}')
+    payload = _mint_payload(agent_transcript, repo_root, "no-sidecar-1")
     assert mint_for_payload(payload) is None
 
 
 def test_attested_manifest_hash_binds_over_cwd_surface(tmp_path: pathlib.Path) -> None:
-    repo_root = tmp_path / "repo"
-    repo_root.mkdir()
+    repo_root = _make_repo(tmp_path)
     _init_repo_with_upstream_and_edit(repo_root)
     attested_hash = "c" * 64
-    agent_transcript = tmp_path / "agent-7.jsonl"
     verdict_fence = json.dumps(
         {"all_pass": True, "findings": [], "manifest_sha256": attested_hash}
     )
-    agent_transcript.write_text(
-        json.dumps(
-            {
-                "type": "assistant",
-                "message": {
-                    "content": [
-                        {
-                            "type": "text",
-                            "text": f"ok\n```verdict\n{verdict_fence}\n```\n",
-                        }
-                    ]
-                },
-            }
-        )
-        + "\n",
-        encoding="utf-8",
-    )
+    agent_transcript = tmp_path / "agent-7.jsonl"
+    _write_verdict_transcript(agent_transcript, verdict_fence)
     _write_sidecar(agent_transcript, MINTING_AGENT_TYPE)
-    payload = {
-        "agent_transcript_path": str(agent_transcript),
-        "cwd": str(repo_root),
-        "agent_id": "attest-1",
-    }
+    payload = _mint_payload(agent_transcript, repo_root, "attest-1")
     verdict_path = mint_for_payload(payload)
     try:
         assert verdict_path is not None

package/hooks/blocking/tests/test_pii_prevention_blocker.py

@@ -142,7 +142,6 @@ def test_commit_with_missing_local_identity_still_blocks_the_value(
     assert deny_reason is not None
     assert "email" in deny_reason
 
-
 def _init_repo_with_staged_pii(repository_root: Path) -> None:
     repository_root.mkdir(parents=True, exist_ok=True)
     subprocess.run(["git", "init", "-q"], cwd=repository_root, check=True)

package/hooks/hooks_constants/dead_module_constant_constants.py

@@ -20,3 +20,11 @@ DEAD_MODULE_CONSTANT_GUIDANCE: str = (
     " module in the enclosing package tree - remove the constant, or reference it"
     " where its value is needed (CODE_RULES §9.8)"
 )
+DEAD_MODULE_CONSTANT_RETRY_GUIDANCE: str = (
+    "To land a constant a consumer will read, break the write-order deadlock by"
+    " writing the consumer that reads it first: that write completes even though a"
+    " transient mypy attr-defined advisory flags the not-yet-defined name (a"
+    " non-blocking post-write check), then re-issue this write, which passes once"
+    " the consumer is on disk. A constant no module ever reads stays flagged on"
+    " every attempt."
+)

package/hooks/hooks_constants/pii_prevention_constants.py

@@ -132,6 +132,7 @@ ALL_SOURCE_TEST_FILE_SUFFIXES: tuple[str, ...] = (
 )
 ALL_SAFE_EMAIL_DOMAINS: frozenset[str] = frozenset(
     {
+        "anthropic.com",
         "example.com",
         "example.org",
         "example.net",

package/package.json

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

package/rules/CLAUDE.md

@@ -5,7 +5,7 @@ paths:
 
 # rules
 
-Rule files installed into `~/.claude/rules/` by `bin/install.mjs`. Claude Code loads these as always-on behavioral constraints for every session. Each `.md` file covers one named rule; hook-enforced rules are also backed by a Python hook in `hooks/`.
+Rule files installed into `~/.claude/rules/` by `bin/install.mjs`. A rule without `paths:` frontmatter loads at the start of every session; a rule with `paths:` frontmatter loads only when the session works with a file its globs match. The `InstructionsLoaded` log records that match as a `path_glob_match` event. Each `.md` file covers one named rule; hook-enforced rules are also backed by a Python hook in `hooks/`.
 
 ## Files
 
@@ -37,7 +37,6 @@ Rule files installed into `~/.claude/rules/` by `bin/install.mjs`. Claude Code l
 | `no-inline-destructive-literals.md` | No destructive-command literals in Bash tool command strings, even as data |
 | `no-justification-noise.md` | Markdown states facts a reader can act on; cut a present-tense sentence that only justifies a stated choice or restates a gain the reader already works out from the behavior or from a rule enforced elsewhere |
 | `env-var-table-code-drift.md` | Every env-var summary table row in a `.md` file names a code file whose source references the variable |
-| `es-exe-file-search.md` | File search on Windows routes through the `es.exe` CLI with a scoped query; the Everything HTTP server stays off |
 | `orphan-css-class.md` | Every `class="..."` attribute in Python-generated markup has a matching selector in the `<style>` block |
 | `package-inventory-stale-entry.md` | A new production code file added to a directory carries an entry in that directory's `README.md`/`CLAUDE.md` file inventory |
 | `paired-test-coverage.md` | A public function omitted by a module's established paired test suite must get a behavioral test |
@@ -50,7 +49,7 @@ Rule files installed into `~/.claude/rules/` by `bin/install.mjs`. Claude Code l
 | `research-mode.md` | Three anti-hallucination constraints: say "I don't know", verify with citations, quote for factual grounding |
 | `right-sized-engineering.md` | Simple over clever; functions over classes; concrete over abstract |
 | `self-contained-docs.md` | Every document is fully self-contained; no references to the conversation that produced it |
-| `shell-invocation-policy.md` | All Windows shell commands use `pwsh`; `powershell.exe`, `cmd /c`, and `bash -c` are blocked |
+| `shell-invocation-policy.md` | All Windows shell commands use `pwsh`; `Audit-ShellPolicy.ps1` reports the non-`pwsh` forms in the `settings.json` permission rules and `Migrate-ShellPolicy.ps1` rewrites them to `pwsh`, both run on demand, not as a live gate |
 | `tdd.md` | Test-driven development: red → green → refactor, no production code before a failing test |
 | `testing.md` | Test quality and infrastructure standards |
 | `vault-context.md` | Search Obsidian vault for prior sessions and decisions before substantive project work |

package/rules/agent-spawn-protocol.md

@@ -1,47 +1,9 @@
 # Agent Spawn Protocol (Mandatory)
 
-**When this applies:** Before any Agent or Task tool invocation (Explore, implementation, research, or team subagents).
+Before any Agent or Task tool spawn (Explore, implementation, research, or team subagents):
 
-<agent_spawn_protocol>
+1. **Check context sufficiency** — you can name the files involved, the constraints, and what success looks like, and the task is unambiguous. When you cannot, investigate or ask the user first; do not spawn with incomplete context.
+2. **Craft the prompt with `/prompt-generator`** — feed it the goal, the target files from step 1, the constraints, the output format, and the acceptance criteria; use its output as the agent's `prompt`.
+3. **Spawn** with that structured prompt.
 
-## Before spawning ANY agent — no exceptions
-
-Every Agent and Task tool call must follow this protocol. This includes Explore agents, research agents, execution agents, and team members.
-
-### Step 1: Context sufficiency check
-
-Before writing any agent prompt, verify you can answer all of these:
-- [ ] What specific files, directories, or areas of the codebase are involved?
-- [ ] What constraints apply? (patterns to follow, things NOT to change, boundaries)
-- [ ] What does success look like? (expected output, acceptance criteria)
-- [ ] Is the task unambiguous enough to delegate?
-
-If ANY answer is "I don't know" -- investigate first (read files, search code) or ask the user. Do NOT spawn with incomplete context.
-
-### Step 2: Craft the prompt with /prompt-generator
-
-Run the `/prompt-generator` skill to produce a structured prompt. Feed it:
-- The task description and goal
-- Target files/directories discovered in Step 1
-- Constraints and boundaries
-- Expected output format
-- Acceptance criteria
-
-The skill will ask 1-3 clarifying questions if information is missing -- this is the built-in context verification.
-
-Use the skill's output as the agent's `prompt` parameter.
-
-### Step 3: Spawn the agent
-
-Pass the structured prompt from Step 2 to the Agent/Task tool.
-
-</agent_spawn_protocol>
-
-## Why
-
-Agents receiving vague prompts waste tokens exploring in circles, produce code that misses constraints, and require expensive rework. A 30-second investment in prompt quality via /prompt-generator saves 5-minute agent failures. This applies equally to Explore agents (which waste context on unfocused searches) and execution agents (which write wrong code).
-
-## Relationship to other rules
-
-- **conservative-action.md** gates acting when ambiguous. This extends that: do not delegate when the task is ambiguous—investigate or ask the user first.
-- Project-specific rules or `~/.claude/CLAUDE.md` may define *whether* to use subagents or teams; this rule governs *how* to craft prompts when you do delegate.
+Full step detail, rationale, and relationship to other rules: `@~/.claude/docs/agent-spawn-protocol.md`.

package/rules/code-standards.md

@@ -3,39 +3,4 @@
 > **MANDATORY REFERENCE:** CODE_RULES.md - Load for ALL code generation.
 > This is the single source of truth for code standards. Non-negotiable.
 
-**Key principles (see CODE_RULES.md for complete reference):**
-- Self-documenting code (no comments)
-- Centralized configuration (one source of truth)
-- Reuse constants (search before creating)
-- No magic values (everything named)
-- No abbreviations (full words)
-- Complete type hints
-- TDD (test first)
-
-## Function Parameters - Required vs Optional
-
-**Use required parameters when no valid use case exists for optional.**
-**Remove unused parameters.**
-
-## Encapsulation - Logic Belongs in Models
-
-**NEVER scatter construction logic in calling code.**
-
-Path/URL building, formatting, transformations -> Put in model methods.
-If you find yourself building the same string pattern in multiple places, it belongs in the model.
-
-## Document Temporary Code
-
-**Scaffolding/placeholder code MUST have TODO comments.**
-
-When code exists only to enable testing before full implementation:
-- Add `// TODO: Replace with...` explaining what will replace it
-- Explain WHY it's temporary, not just WHAT it does
-
-## Naming Reflects Behavior
-
-**Name components after what they ARE, not abstract concepts.**
-
-If it overlays the viewport -> "Overlay" not "Screen"
-If it validates input -> "Validator" not "Handler"
-Names should describe observable behavior or visual appearance.
+`CODE_RULES.md` (`~/.claude/docs/CODE_RULES.md`) is the compact reference for every standard: self-documenting names, centralized configuration, constant reuse, no magic literals, full words, complete type hints, required-vs-optional parameters, construction logic in the model, temporary-code `TODO:` markers, behavior-first component names, and TDD.

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

@@ -5,25 +5,6 @@ paths:
 
 # Env-Var Summary Table Names a Code File That Reads the Variable
 
-**When this applies:** Any Write, Edit, or MultiEdit to a markdown (`.md`) file that carries an environment-variable summary table — a markdown table whose rows pair a `` `VARIABLE` `` name with the `` `code/file.py` `` that reads it.
+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.
 
-## Rule
-
-Every row in an env-var summary table names a code file whose source references the variable. A row pairs an UPPER_SNAKE variable with a code-file path, written as `` | `GOOGLE_APPLICATION_CREDENTIALS` | `auth/google_auth.py` | ... | ``, and the named file reads that variable. When the file exists yet its source never mentions the variable name, the row is stale: the table points a reader at a consumer relationship the code does not have, so a reader trusts the doc to behavior the code dropped.
-
-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. The doc and the code move together in one commit.
-
-## What the gate checks
-
-The `env_var_table_code_drift_blocker.py` hook runs on every Write, Edit, and MultiEdit whose target is a `.md` file. It:
-
-1. Reads the content the tool would leave on disk, skipping lines inside a fenced code block.
-2. Collects each table row whose first cell names an UPPER_SNAKE variable and whose later cell names a code file with a recognized extension (`.py`, `.mjs`, `.js`, `.ts`, `.ps1`, `.sh`).
-3. Resolves the named code file under the repository root (the nearest `.git`-bearing ancestor of the markdown file) and reads its source.
-4. Blocks the write when the file resolves yet its source never references the variable name. For an Edit, drift the file already held on an untouched row is excluded, so only drift the edit introduces is reported.
-
-The check stays quiet for a row whose code file resolves nowhere under the repository root (it cannot prove the drift), a row whose second cell holds no code-file path, and a table row inside a fenced code block.
-
-## Why this is a hook, not a lint pass
-
-An env-var table that names a file whose source skips the variable reads as a correct map of which code consumes which setting, while pointing one row at behavior the code dropped. A reader trusting the row chases a setting the file ignores, and the gap survives review because the table still looks complete. Catching it as the doc is written keeps the table and the code in step.
+`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).