claude-dev-env 2.0.1 → 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/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.1",
+    "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).

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

@@ -4,23 +4,12 @@ paths: **/hooks/**/*.py
 
 # Hook Prose Matches Its Detector
 
-**When this applies:** Any Write or Edit to a hook module (`.py` under `hooks/`) or its `*_constants.py` companion.
+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 enforcement:** `hook-prose-detector-consistency` (PreToolUse on Write|Edit) blocks a hook whose user-facing prose claims a trigger its detector never fires on. See `hooks.json` for registration.
+`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.
 
-## Rule
+## Judgment
 
-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. An author reads the corrective message to learn what they did wrong; an author reads the docstring to learn what the hook guards. When either claims a trigger the detector cannot fire on, both audiences are misled: an author whose only token is that shape never sees the block, and an author who does see the block is told the wrong cause.
+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 blocker case
-
-A path-shape blocker detects a per-iteration token only when the token sits next to a path separator (its detection regex keys off a `[\\/]`-style character class). Such a hook must not claim it blocks an "output-key segment": a quoted structured-output key alone, with no looped path, is never flagged. The `*_constants.py` companion holds the corrective message and not the detector, so the phrase "output-key segment" describing a blocked trigger is itself the violation there, regardless of which file holds the regex.
-
-| Prohibited claim | Why it overstates | Correct phrasing |
-|---|---|---|
-| "appears as a path or output-key segment" | the detector keys off a path separator only | "appears as a per-iteration path segment" |
-| docstring: "blocks a bare token like `cand_i`" | a bare prose token next to no separator is not flagged | "blocks a per-iteration path like `${work}\cand_i\plate.svg`" |
-
-## The test
-
-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/nas-ssh-invocation.md

@@ -1,23 +1,11 @@
 # NAS SSH Invocation Policy
 
-**When this applies:** Any `ssh`, `scp`, or `sftp` command against the NAS.
-
-## Rule
-
-Reach the NAS through the Windows OpenSSH binary with batch mode on. Git Bash's MSYS `ssh` reads `~/.ssh/id_ed25519` as world-readable through its ACL mapping, rejects the key as bad permissions, offers no key, and falls back to an interactive password prompt. In an unattended session no one answers that prompt, so the session hangs. The `System32/OpenSSH` binary authenticates the same key without a prompt.
-
-Use this form for every NAS ssh command:
+Reach the NAS through the Windows `System32/OpenSSH` binary with `-o BatchMode=yes` on every `ssh`, `scp`, or `sftp` command:
 
 ```
 "/c/Windows/System32/OpenSSH/ssh.exe" -o BatchMode=yes -o ConnectTimeout=10 -p 22 operator@nas.example.local "<cmd>"
 ```
 
-`scp` and `sftp` take the matching `System32/OpenSSH` binary, `-o BatchMode=yes`, and the same port (`-P` for `scp`).
-
-The host, ssh user, and port come from the `CLAUDE_NAS_*` environment variables or `~/.claude/local-identity.json`; the committed examples show placeholders (`nas.example.local`, `operator`, `22`).
-
-`-o BatchMode=yes` is required, not optional: it turns a key-authentication failure into a loud non-zero exit rather than a silent password prompt, so an auth regression surfaces as an error you can read.
-
-## Enforcement
+Git Bash's MSYS `ssh` falls back to an interactive password prompt that hangs an unattended session; the `System32/OpenSSH` binary authenticates the key without a prompt, and `-o BatchMode=yes` turns an auth failure into a loud non-zero exit. `nas_ssh_binary_enforcer.py` (PreToolUse on Bash) enforces this: it denies a bare ssh-family word aimed at the NAS, and denies the full binary when `-o BatchMode=yes` is absent.
 
-`nas_ssh_binary_enforcer.py` (PreToolUse on Bash) denies a bare `ssh`/`scp`/`sftp` command word aimed at the NAS host and points at the full-binary form. It also denies the full `System32/OpenSSH` binary to that host when the command omits `-o BatchMode=yes`. Commands to any other host, and commands that mention the address without an ssh-family command word, pass.
+Host, user, and port config, the `scp`/`sftp` forms, and the full rationale: `@~/.claude/docs/nas-ssh-invocation.md`.

package/rules/no-historical-clutter.md

@@ -11,58 +11,16 @@ paths:
 
 # No Historical Clutter in Documentation or Comments
 
-**When this applies:** Any Write or Edit to files containing comments or documentation.
+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.
 
-**Hook enforcement:** `state-description-blocker` (PreToolUse on Write|Edit) blocks historical/comparative language automatically. See `hooks.json` for registration.
+`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.
 
-Coverage spans `.md` prose, code comments, and Python module/class/function docstrings; a phrase wrapped in double quotes or backticks inside a docstring counts as a mention and is skipped.
+## What stays allowed
 
-## Rule
-
-Never reference removed implementations, old defaults, prior behaviors, or how something `"used to be"` when updating documentation. The current state is all that matters.
-
-A module or function docstring carries the same describe-current-state-only contract as a `.md` file.
-
-## Examples of prohibited patterns
-
-### In documentation (.md files)
-
-| Pattern | Why it's clutter |
-|---------|-----------------|
-| `` `"instead of 30"` `` in a pagination rule | The old default `no longer` exists in code; the rule reader doesn't need to know what it was |
-| `` `"previously this used X"` `` | If X is gone, it's noise |
-| `` `"before this rule, we did Y"` `` | The rule exists now; the before-state is irrelevant |
-| `` `"migrated from Z to W"` `` | If Z is fully removed, the migration story is git history, not documentation |
-| `` `"the old implementation did A"` `` | If A is gone, the reader gains nothing from knowing it existed |
-| `` `"originally"` `` / `` `"used to be"` `` | Same — dead context |
-
-### In code comments
-
-| Pattern | Good replacement |
-|---------|-----------------|
-| `# Uses X instead of Y` | `# Uses X` |
-| `# Previously configured via Z` | `# Configured via Z` |
-| `# Now uses the new API client` | `# Uses the new API client` |
-| `# No longer supports legacy mode` | `# Supports modern mode only` |
-| `// Switched to async processing` | `// Processes asynchronously` |
-| `# Replaced by the cache layer` | `# Cache layer handles reads` |
-
-### Hook-detected patterns
-
-The `state-description-blocker` hook (PreToolUse on Write\|Edit) enforces these patterns automatically:
-
-`instead of`, `previously`, `now uses/does/handles/supports/names/includes`, `was previously`, `were previously`, `was formerly`, `was added`, `used to`, `no longer`, `has/have been updated/changed`, `replaced by`, `replaces`, `superseded by`, `supersedes`, `changed from`, `changes from`, `switched from/to`, `migrated from/to`, `moved to/into`, `extracted as`, `updated to`, `originally`, `as of`
-
-## What IS allowed
-
-- Comparisons to *currently existing* alternatives (e.g., "use `--paginate --slurp | jq`, not `--jq` alone")
-- Rationale that explains *why* a pattern is wrong in terms of present behavior (e.g., "`--jq` runs per-page, so cross-page operations produce wrong results")
-- References to external sources for defects that still exist (e.g., gh CLI #10459)
+- 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 documentation, ask: **"If someone reads this a year from now, with no knowledge of what came before, does every sentence still make sense and add value?"** If a sentence only adds value to someone who knew the old state, delete it.
-
-## Why
-
-Historical references clog context windows and force readers to mentally filter "what was" from "what is." The git log is the authoritative record of what changed and why. Documentation describes the current contract.
+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,11 +1,9 @@
 # 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/review-comment 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.
+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:
 
-- Commit messages and PR/issue/review-comment 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 `destructive_command_blocker` (or any hook) behavior, run the committed test suite (`python -m pytest <test_file>`), which passes the command strings as in-language data, not as a shell command — never an inline `python -c` harness.
+- 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.
-
-The `destructive_command_blocker` hook is the enforcement surface; this rule is how to keep a non-executing mention from tripping it.

package/rules/package-inventory-stale-entry.md

@@ -10,41 +10,16 @@ paths:
 
 # New Production File Absent From Its Package Inventory
 
-**When this applies:** Any Write that creates a new production code file (`.py`, `.mjs`, `.js`, `.ts`, `.ps1`, `.sh`) in a directory whose sibling `README.md` or `CLAUDE.md` already names two or more of the directory's files in backticks, in a directory whose own `SKILL.md` names two or more of the directory's files, or in a skill's `scripts/` subdirectory whose parent `SKILL.md` Layout table already names two or more of those scripts.
+A package directory that documents its own files in a `README.md` Layout table, a `CLAUDE.md` "Key files" list, or a skill `SKILL.md` Layout table keeps that inventory in step with the directory. When you create a new production file in such a directory, add an entry naming it — a row in the table or a bullet in the list — in the same change. The entry names the file in backticks and says what it does.
 
-## Rule
+`package_inventory_stale_blocker.py` (PreToolUse on Write) blocks a new production file whose basename appears in no present inventory and names the fix. A skill `SKILL.md` Layout table that maps `scripts/` counts as the inventory for files in that subdirectory.
 
-A package directory that documents its own files in a `README.md` Layout table or a `CLAUDE.md` "Key files" list keeps that inventory in step with the directory. A skill package does the same in its `SKILL.md` Layout table, which sits at the skill root and maps the `scripts/` subdirectory by naming each script with its `scripts/<name>` path. A new production file the inventory does not name leaves the inventory and the directory disagreeing on the package's file set: a reader who trusts the inventory to map the directory misses the new file.
+## Judgment the gate cannot derive
 
-When you create a new production file in such a directory, add an entry naming it — a row in the `README.md` or `SKILL.md` table, a bullet in the `CLAUDE.md` list — in the same change. The entry names the file in backticks and says what it does.
+The file-list entry is the slice the gate checks by name. Two free-prose slices stay with judgment and belong in the same change:
 
-## Companion: keep the Purpose/scope sentence in step with the new responsibility
+1. **Purpose / scope sentence.** When the new module adds a responsibility the package `## Purpose` (or the parent inventory's one-line summary of this subdirectory) omits, broaden that sentence to name it. A hook cannot derive a module's responsibility from its filename.
 
-The file-list entry is the deterministic slice the gate enforces. A package inventory also carries a free-prose scope sentence — a `## Purpose` paragraph in a `CLAUDE.md`, a one-line summary the parent directory's inventory gives each subdirectory — that names the responsibilities the package's modules cover. When the new module adds a responsibility the scope sentence omits, the same change broadens that sentence to name it, and updates the parent inventory's one-line summary of this subdirectory to match.
+2. **Per-file description clause.** When a file gains a responsibility the inventory's em-dash description omits — a new public function, a new module-level constant — broaden the description clause to name it. The gate only checks that the basename appears once; it never reads the description. Constants modules (`*_constants.py`, or any `.py` directly inside `config/`) are the common shape: the constant's other home is the module docstring, so the clause that lands in the docstring lands in the inventory description in the same change. The gate fires on Write of a new file and skips files directly inside `config/`, so an Edit that adds a constant to an existing config module matches neither path.
 
-Take a `files/` package whose `Purpose` reads "Holds helpers for downloading files over HTTP and extracting zip archives" and whose parent summary reads "file download, extraction, and path config helpers". Once a `force_remove.py` module that removes a directory tree sits beside the download helpers, both sentences name a narrower responsibility set than the directory holds. The required file-list bullet alone leaves that gap open. Broaden the `Purpose` sentence to name directory removal, and broaden the parent summary to match, in the same change that adds the module and its bullet.
-
-This scope-sentence slice is free prose: a hook cannot derive a module's responsibility from its filename, so the gate leaves it to judgment. It is the judgment companion to the file-list entry the gate enforces, and it belongs in the same change. This is the `category-o-docstring-vs-impl-drift` (O8) orphaned-doc-claim shape applied to a package inventory: a behavior change orphans a scope claim the prose still makes.
-
-## Companion: keep a per-file description in step with the file it describes
-
-The per-file entry a `CLAUDE.md` "Key files" list or a `README.md` Layout table gives each file carries more than the backticked filename the gate checks for. The clause after the file name — the em-dash description — is itself a free-prose scope claim about what the file holds. When the file gains a responsibility the description omits — a new public function, a new constant — the same change broadens the description clause to name it. The gate's file-list check passes the moment the file name appears once; it never reads the description clause, so a stale description beside a present file name stays invisible to the gate.
-
-A constants module is the common shape of this drift. A file whose name ends `_constants.py`, or any `.py` directly inside a `config/` directory, holds a set of module-level constants, and a sibling inventory describes that file by listing the set — `` `stp_constants.py` — the STP archive member constants: the Properties.xml member name, the workspace prefix every asset reference carries, and the source-form nine-patch filename suffix ``. When the file gains a module-level constant the list omits, three claims drift together: the list itself, the scope label that heads it (`the STP archive member constants`), and the package `## Purpose` sentence when that sentence describes the file's contents. The constant's other home — the module docstring of the constants file — and the sibling inventory's description of that file cover the same set, so the clause that lands in the docstring lands in the inventory description in the same change.
-
-This slice sits outside the gate. The gate fires on a Write that creates a new file, and it skips a file directly inside a `config/` directory, so an Edit that adds a constant to an existing `config/` constants module matches neither path. Like the Purpose/scope companion above, it is free prose a hook cannot derive from a file name, so it stays judgment here and a Category O8 finding at audit: a behavior change orphans a description claim the inventory still makes.
-
-## What the gate checks
-
-The `package_inventory_stale_blocker.py` hook runs on every Write whose target is a new file (a path not yet on disk). It:
-
-1. Skips a target that is not a production code file (`.py`, `.mjs`, `.js`, `.ts`, `.ps1`, `.sh`), an exempt basename (`__init__.py`, `conftest.py`, `setup.py`, `_path_setup.py`), a test file (`test_*.py`, `*_test.py`, `*.spec.*`, `*.test.*`), or a file directly inside a `config/` or `tests/` directory.
-2. Reads each `README.md`, `CLAUDE.md`, and `SKILL.md` present in the target's own directory and, when the target sits in a `scripts/` subdirectory, the parent directory's `SKILL.md`, and collects every bare filename they name in backticks. A backticked token holding a path contributes its final segment, so `pipeline/seam_continuity.py` in an inventory counts as naming `seam_continuity.py` and `scripts/stp_selection.py` in a parent `SKILL.md` Layout table counts as naming `stp_selection.py`. A multi-word command-example span — one carrying whitespace or shell punctuation (`:`, `$`, `<`, `>`), such as `parent:node_modules package.json` or `python <file>.py` — names no literal file and is dropped.
-3. Filters the named basenames to those that exist as a file in the target's own directory — the inventory's own sibling files — and treats the directory as carrying a maintained inventory only when two or more such sibling files are named. A directory with no inventory, one whose `README.md` mentions a single file in passing, or one whose inventory prose names only files living in other directories (so no named basename is an on-disk sibling) is out of scope.
-4. Blocks the write when the new file's basename appears in no present inventory. An unreadable or oversized inventory document is skipped, so a missing inventory never blocks a write.
-
-The check fires on Write only — editing an existing file adds no new inventory entry — and stays quiet for a directory with no inventory document, an inventory naming too few siblings to be a maintained list, an exempt or test file, and a file the inventory already names.
-
-## Why this is a hook, not a lint pass
-
-A package inventory that omits a file reads as a complete map of the directory while leaving one file off it. A reader trusting the inventory to list the package misses the new file, and the gap survives review because the inventory still looks complete. Catching it as the new file is written keeps the inventory and the directory in step. This is the counterpart to `claude-md-orphan-file.md`, which catches the reverse drift: an inventory entry naming a file the directory does not hold.
+This is the `category-o-docstring-vs-impl-drift` (O8) orphaned-doc-claim shape applied to a package inventory.