claude-dev-env 2.13.0 → 2.14.0

package/hooks/validation/CLAUDE.md

@@ -1,20 +1 @@
-# hooks/validation
-
-PostToolUse hooks that validate code quality after Claude writes or edits a file. Unlike the blocking hooks (which fire PreToolUse and can deny the write), these hooks run after the write and report errors that need a follow-up fix.
-
-## Key files
-
-| File | Event | What it does |
-|---|---|---|
-| `mypy_validator.py` | PostToolUse (Write/Edit on `.py` files) | Runs mypy on the written file and blocks (via PostToolUse block decision) when type errors are found — catches missing attributes, wrong signatures, type mismatches, and import errors |
-| `hook_format_validator.py` | PostToolUse | Validates that a hook script's output JSON matches the expected Claude Code hook-output schema |
-| `test_mypy_validator.py` | — | Tests for `mypy_validator.py` |
-| `test_hook_format_validator.py` | — | Tests for `hook_format_validator.py` |
-
-## Conventions
-
-- `mypy_validator.py` resolves the project root via `CLAUDE_PROJECT_ROOT` or `git rev-parse --show-toplevel`.
-- It works on both WSL and Windows.
-- Constants (timeouts, max displayed errors) are inline in `mypy_validator.py`; longer tunables go in `hooks_constants/`.
-- The `eval_*.txt` files in this directory are evaluation exports used during development — not runtime artifacts.
-- Tests run with `python -m pytest validation/test_<name>.py`.
+@AGENTS.md

package/hooks/validators/AGENTS.md

@@ -0,0 +1,51 @@
+# hooks/validators
+
+A library of check modules used by the validation hooks. Each module focuses on one concern; `run_all_validators.py` runs them all and collects results. These modules do not hook into Claude Code directly — they are imported by the validation hooks.
+
+## Core infrastructure
+
+| File | Role |
+|---|---|
+| `validator_base.py` | Defines the `Violation` dataclass (`file`, `line`, `message`) used by every check module |
+| `validator_defaults.py` | Default configuration values shared across check modules |
+| `exempt_paths.py` | Path exemption logic — paths that checks skip (e.g. vendored code) |
+| `output_formatter.py` | Formats `Violation` lists into human-readable output |
+| `run_all_validators.py` | Entry point — runs every check module and aggregates results |
+| `health_check.py` | Verifies that all validator dependencies (ruff, mypy) are reachable |
+| `pyproject_config_discovery.py` | Shared walk-up primitive that resolves a tool's pyproject.toml config from an original target path, matching the `[tool.<name>]` table the tool owns |
+| `python_style_helpers.py` | Shared source-line splitting and function-discovery helpers imported by `python_style_checks.py` |
+
+## Check modules
+
+| Module | What it checks |
+|---|---|
+| `abbreviation_checks.py` | Abbreviated names in Python code |
+| `code_quality_checks.py` | General code quality concerns (dead code, stub bodies, etc.) |
+| `comment_checks.py` | Inline comment presence and content |
+| `file_structure_checks.py` | File-level structural rules (line count, module layout) |
+| `git_checks.py` | Git-state checks (untracked files, merge conflicts) |
+| `magic_value_checks.py` | Magic numbers and strings |
+| `mypy_integration.py` | Runs mypy and converts its output to `Violation` objects |
+| `pr_reference_checks.py` | PR references in commit messages and changelogs |
+| `python_antipattern_checks.py` | Python-specific anti-patterns (bare `except`, `Any`, etc.) |
+| `python_style_checks.py` | Python style rules (naming, imports, type hints) |
+| `react_checks.py` | React/TSX-specific checks (class component patterns, PureComponent usage) |
+| `ruff_integration.py` | Runs ruff and converts its output to `Violation` objects |
+| `security_checks.py` | Security anti-patterns (hardcoded secrets, unsafe calls) |
+| `todo_checks.py` | TODO/FIXME markers without an associated issue reference |
+| `type_safety_checks.py` | Type-safety rules (no `Any`, no `cast`, no `# type: ignore`) |
+| `useless_test_checks.py` | Tests that check only existence or constant values |
+
+## Subdirectory
+
+| Directory | Role |
+|---|---|
+| `config/` | Constants module (`directory_exemption_constants.py`) holding the exemption directory-segment names that `validate_proposed_file` staging keeps |
+| `test_files/` | Fixture files used by the validator tests — not checked-in test code |
+
+## Conventions
+
+- Every check module exposes one or more functions that take file content or an AST and return a list of `Violation` objects.
+- Test files live beside the modules they test: `test_<module>.py`. Run with `python -m pytest validators/test_<name>.py`.
+- `conftest.py` provides shared test fixtures (sample files, fixture paths).
+- `README.md` in this directory documents the validator design and how to add a new check.

package/hooks/validators/CLAUDE.md

@@ -1,51 +1 @@
-# hooks/validators
-
-A library of check modules used by the validation hooks. Each module focuses on one concern; `run_all_validators.py` runs them all and collects results. These modules do not hook into Claude Code directly — they are imported by the validation hooks.
-
-## Core infrastructure
-
-| File | Role |
-|---|---|
-| `validator_base.py` | Defines the `Violation` dataclass (`file`, `line`, `message`) used by every check module |
-| `validator_defaults.py` | Default configuration values shared across check modules |
-| `exempt_paths.py` | Path exemption logic — paths that checks skip (e.g. vendored code) |
-| `output_formatter.py` | Formats `Violation` lists into human-readable output |
-| `run_all_validators.py` | Entry point — runs every check module and aggregates results |
-| `health_check.py` | Verifies that all validator dependencies (ruff, mypy) are reachable |
-| `pyproject_config_discovery.py` | Shared walk-up primitive that resolves a tool's pyproject.toml config from an original target path, matching the `[tool.<name>]` table the tool owns |
-| `python_style_helpers.py` | Shared source-line splitting and function-discovery helpers imported by `python_style_checks.py` |
-
-## Check modules
-
-| Module | What it checks |
-|---|---|
-| `abbreviation_checks.py` | Abbreviated names in Python code |
-| `code_quality_checks.py` | General code quality concerns (dead code, stub bodies, etc.) |
-| `comment_checks.py` | Inline comment presence and content |
-| `file_structure_checks.py` | File-level structural rules (line count, module layout) |
-| `git_checks.py` | Git-state checks (untracked files, merge conflicts) |
-| `magic_value_checks.py` | Magic numbers and strings |
-| `mypy_integration.py` | Runs mypy and converts its output to `Violation` objects |
-| `pr_reference_checks.py` | PR references in commit messages and changelogs |
-| `python_antipattern_checks.py` | Python-specific anti-patterns (bare `except`, `Any`, etc.) |
-| `python_style_checks.py` | Python style rules (naming, imports, type hints) |
-| `react_checks.py` | React/TSX-specific checks (class component patterns, PureComponent usage) |
-| `ruff_integration.py` | Runs ruff and converts its output to `Violation` objects |
-| `security_checks.py` | Security anti-patterns (hardcoded secrets, unsafe calls) |
-| `todo_checks.py` | TODO/FIXME markers without an associated issue reference |
-| `type_safety_checks.py` | Type-safety rules (no `Any`, no `cast`, no `# type: ignore`) |
-| `useless_test_checks.py` | Tests that check only existence or constant values |
-
-## Subdirectory
-
-| Directory | Role |
-|---|---|
-| `config/` | Constants module (`directory_exemption_constants.py`) holding the exemption directory-segment names that `validate_proposed_file` staging keeps |
-| `test_files/` | Fixture files used by the validator tests — not checked-in test code |
-
-## Conventions
-
-- Every check module exposes one or more functions that take file content or an AST and return a list of `Violation` objects.
-- Test files live beside the modules they test: `test_<module>.py`. Run with `python -m pytest validators/test_<name>.py`.
-- `conftest.py` provides shared test fixtures (sample files, fixture paths).
-- `README.md` in this directory documents the validator design and how to add a new check.
+@AGENTS.md

package/hooks/validators/health_check.py

@@ -7,14 +7,15 @@ Provides:
 """
 
 import hashlib
+import stat
 import subprocess
 import sys
 from dataclasses import dataclass
-from datetime import datetime
+from datetime import datetime, timezone
+from enum import StrEnum
 from pathlib import Path
 from typing import Dict, Optional
 
-
 VALIDATOR_FILES = [
     "python_style_checks.py",
     "test_safety_checks.py",
@@ -25,15 +26,38 @@ VALIDATOR_FILES = [
 ]
 
 
+class ValidatorStatus(StrEnum):
+    """Displayed state for one required validator."""
+
+    READY = "[READY]"
+    FILE_REQUIRED = "[FILE REQUIRED]"
+    ACCESS_REQUIRED = "[ACCESS REQUIRED]"
+
+
 @dataclass(frozen=True)
 class ValidatorHealth:
     """Health status of a single validator."""
 
     name: str
-    healthy: bool
+    status: ValidatorStatus
     error: Optional[str] = None
     last_modified: Optional[datetime] = None
 
+    @property
+    def is_healthy(self) -> bool:
+        """Return whether the validator is ready for use."""
+        return self.status is ValidatorStatus.READY
+
+    @property
+    def healthy(self) -> bool:
+        """Return the readiness state for compatibility readers."""
+        return self.is_healthy
+
+    @property
+    def is_present(self) -> bool:
+        """Return whether the validator file is present on disk."""
+        return self.status is not ValidatorStatus.FILE_REQUIRED
+
 
 @dataclass(frozen=True)
 class SystemHealth:
@@ -56,26 +80,33 @@ def check_validator_exists(validator_path: Path) -> ValidatorHealth:
     """
     name = validator_path.stem
 
-    if not validator_path.exists():
+    try:
+        validator_stat = validator_path.stat()
+        if not stat.S_ISREG(validator_stat.st_mode):
+            return ValidatorHealth(
+                name=name,
+                status=ValidatorStatus.FILE_REQUIRED,
+                error=f"Validator file required: {validator_path}",
+            )
+        validator_path.read_text(encoding="utf-8")
         return ValidatorHealth(
             name=name,
-            healthy=False,
-            error=f"Validator not found: {validator_path}",
+            status=ValidatorStatus.READY,
+            last_modified=datetime.fromtimestamp(
+                validator_stat.st_mtime, tz=timezone.utc
+            ),
         )
-
-    try:
-        validator_path.read_text(encoding="utf-8")
-        mtime = datetime.fromtimestamp(validator_path.stat().st_mtime)
+    except FileNotFoundError:
         return ValidatorHealth(
             name=name,
-            healthy=True,
-            last_modified=mtime,
+            status=ValidatorStatus.FILE_REQUIRED,
+            error=f"Validator file required: {validator_path}",
         )
     except (IOError, OSError, PermissionError) as error:
         return ValidatorHealth(
             name=name,
-            healthy=False,
-            error=f"Cannot read validator: {error}",
+            status=ValidatorStatus.ACCESS_REQUIRED,
+            error=f"Validator read access requires attention: {error}",
         )
 
 
@@ -135,7 +166,10 @@ def get_validator_version(validators_dir: Optional[Path] = None) -> str:
     for validator_file in sorted(VALIDATOR_FILES):
         validator_path = validators_dir / validator_file
         if validator_path.exists():
-            content = validator_path.read_bytes()
+            try:
+                content = validator_path.read_bytes()
+            except (FileNotFoundError, OSError):
+                continue
             hasher.update(content)
 
     return hasher.hexdigest()[:8]
@@ -154,7 +188,7 @@ def get_system_health(validators_dir: Optional[Path] = None) -> SystemHealth:
         validators_dir = Path(__file__).parent
 
     validators = check_all_validators(validators_dir)
-    all_healthy = all(v.healthy for v in validators.values())
+    all_healthy = all(v.is_healthy for v in validators.values())
 
     optional_tools = {
         "ruff": check_optional_tool("ruff"),
@@ -187,15 +221,14 @@ def print_health_report(health: SystemHealth) -> None:
 
     print("Required Validators:")
     for name, validator in sorted(health.validators.items()):
-        status = "[OK]" if validator.healthy else "[MISSING]"
-        print(f"  {status} {name}")
+        print(f"  {validator.status.value} {name}")
         if validator.error:
             print(f"         Error: {validator.error}")
     print()
 
     print("Optional Tools:")
     for tool, available in sorted(health.optional_tools.items()):
-        status = "[OK]" if available else "[NOT INSTALLED]"
+        status = ValidatorStatus.READY.value if available else "[OPTIONAL]"
         print(f"  {status} {tool}")
     print()
 

package/hooks/validators/python_style_checks.py

@@ -169,7 +169,7 @@ def _decorator_gap_violation(
     return Violation(
         filename,
         last_decorator_line,
-        "No empty line allowed between decorator and function",
+        "Place the decorator directly above the function",
     )
 
 

package/hooks/validators/test_health_check.py

@@ -1,35 +1,92 @@
 """Tests for validator health checks."""
 
-import tempfile
 from pathlib import Path
 
 import pytest
 
 from .health_check import (
+    SystemHealth,
     ValidatorHealth,
+    ValidatorStatus,
     check_validator_exists,
     check_all_validators,
     get_validator_version,
+    print_health_report,
 )
 
 
 class TestValidatorExists:
-    def test_existing_validator_healthy(self) -> None:
-        with tempfile.NamedTemporaryFile(suffix=".py", delete=False) as temp_file:
-            temp_file.write(b"print('hello')")
-            temp_path = Path(temp_file.name)
-
-        try:
-            result = check_validator_exists(temp_path)
-            assert result.healthy is True
-            assert result.error is None
-        finally:
-            temp_path.unlink()
-
-    def test_missing_validator_unhealthy(self) -> None:
+    def test_existing_validator_is_ready(self, tmp_path: Path) -> None:
+        validator_path = tmp_path / "validator.py"
+        validator_path.write_text("print('hello')", encoding="utf-8")
+
+        result = check_validator_exists(validator_path)
+
+        assert result.is_healthy is True
+        assert result.healthy is result.is_healthy
+        assert result.status is ValidatorStatus.READY
+        assert result.error is None
+        assert result.is_present is True
+
+    def test_missing_validator_requires_a_file(self) -> None:
         result = check_validator_exists(Path("/nonexistent/validator.py"))
-        assert result.healthy is False
-        assert "not found" in result.error.lower()
+        assert result.is_healthy is False
+        assert result.status is ValidatorStatus.FILE_REQUIRED
+        assert result.is_present is False
+        assert "file required" in result.error.lower()
+
+    def test_unreadable_validator_reports_read_access_state(
+        self,
+        tmp_path: Path,
+        monkeypatch: pytest.MonkeyPatch,
+    ) -> None:
+        validator_path = tmp_path / "validator.py"
+        validator_path.write_text("print('ready')", encoding="utf-8")
+
+        def raise_read_error(*_args: object, **_kwargs: object) -> str:
+            raise OSError("permission detail")
+
+        monkeypatch.setattr(Path, "read_text", raise_read_error)
+
+        result = check_validator_exists(validator_path)
+
+        assert result.is_healthy is False
+        assert result.status is ValidatorStatus.ACCESS_REQUIRED
+        assert result.is_present is True
+        assert "read access requires attention" in result.error.lower()
+
+    def test_directory_at_validator_path_requires_a_file(self, tmp_path: Path) -> None:
+        validator_path = tmp_path / "validator.py"
+        validator_path.mkdir()
+
+        result = check_validator_exists(validator_path)
+
+        assert result.is_healthy is False
+        assert result.status is ValidatorStatus.FILE_REQUIRED
+        assert result.is_present is False
+
+    def test_validator_disappearance_reports_file_required(
+        self,
+        tmp_path: Path,
+        monkeypatch: pytest.MonkeyPatch,
+    ) -> None:
+        validator_path = tmp_path / "validator.py"
+        validator_path.write_text("print('ready')", encoding="utf-8")
+
+        original_read_text = Path.read_text
+
+        def remove_before_read(
+            each_path: Path, **all_keyword_arguments: object
+        ) -> str:
+            each_path.unlink()
+            return original_read_text(each_path, **all_keyword_arguments)
+
+        monkeypatch.setattr(Path, "read_text", remove_before_read)
+
+        result = check_validator_exists(validator_path)
+
+        assert result.status is ValidatorStatus.FILE_REQUIRED
+        assert result.is_present is False
 
 
 class TestCheckAllValidators:
@@ -41,17 +98,45 @@ class TestCheckAllValidators:
 
 
 class TestGetValidatorVersion:
-    def test_version_changes_when_content_changes(self) -> None:
-        with tempfile.TemporaryDirectory() as temp_dir:
-            temp_path = Path(temp_dir)
-            validator_file = temp_path / "python_style_checks.py"
+    def test_version_changes_when_content_changes(self, tmp_path: Path) -> None:
+        validator_file = tmp_path / "python_style_checks.py"
+
+        validator_file.write_text("# version 1")
+        version1 = get_validator_version(tmp_path)
+
+        validator_file.write_text("# version 2 - different content")
+        version2 = get_validator_version(tmp_path)
+
+        assert version1 != version2
+        assert isinstance(version1, str)
+        assert len(version1) > 0
+
 
-            validator_file.write_text("# version 1")
-            version1 = get_validator_version(temp_path)
+def test_print_health_report_distinguishes_validator_states(
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    health = SystemHealth(
+        all_healthy=False,
+        validators={
+            "missing_validator": ValidatorHealth(
+                name="missing_validator",
+                status=ValidatorStatus.FILE_REQUIRED,
+                error="Validator file required: missing_validator.py",
+            ),
+            "unreadable_validator": ValidatorHealth(
+                name="unreadable_validator",
+                status=ValidatorStatus.ACCESS_REQUIRED,
+                error="Validator read access requires attention: permission detail",
+            ),
+        },
+        python_version="3.12.0",
+        optional_tools={"mypy": True, "ruff": False},
+    )
 
-            validator_file.write_text("# version 2 - different content")
-            version2 = get_validator_version(temp_path)
+    print_health_report(health)
 
-            assert version1 != version2
-            assert isinstance(version1, str)
-            assert len(version1) > 0
+    report = capsys.readouterr().out
+    assert "[FILE REQUIRED] missing_validator" in report
+    assert "[ACCESS REQUIRED] unreadable_validator" in report
+    assert "[READY] mypy" in report
+    assert "[OPTIONAL] ruff" in report

package/hooks/workflow/AGENTS.md

@@ -0,0 +1,16 @@
+# hooks/workflow
+
+PostToolUse hooks that run after Claude writes a file. They do not block the write; they run follow-up side effects — reformatting the written file and resetting the investigation tracker.
+
+## Key files
+
+| File | Event | What it does |
+|---|---|---|
+| `auto_formatter.py` | PostToolUse (Write/Edit) | Runs the project's auto-formatter (ruff, prettier, etc.) on the written file and sends a desktop notification when formatting changes are applied |
+| `investigation_tracker_reset.py` | PostToolUse | Resets the investigation tracker state after a tool call |
+| `test_auto_formatter.py` | — | Tests for `auto_formatter.py` |
+
+## Conventions
+
+- `auto_formatter.py` exits 0 even on failure — it logs warnings to stderr but does not break Claude's flow.
+- Tests run with `python -m pytest workflow/test_<name>.py`.

package/hooks/workflow/CLAUDE.md

@@ -1,16 +1 @@
-# hooks/workflow
-
-PostToolUse hooks that run after Claude writes a file. They do not block the write; they run follow-up side effects — reformatting the written file and resetting the investigation tracker.
-
-## Key files
-
-| File | Event | What it does |
-|---|---|---|
-| `auto_formatter.py` | PostToolUse (Write/Edit) | Runs the project's auto-formatter (ruff, prettier, etc.) on the written file and sends a desktop notification when formatting changes are applied |
-| `investigation_tracker_reset.py` | PostToolUse | Resets the investigation tracker state after a tool call |
-| `test_auto_formatter.py` | — | Tests for `auto_formatter.py` |
-
-## Conventions
-
-- `auto_formatter.py` exits 0 even on failure — it logs warnings to stderr but does not break Claude's flow.
-- Tests run with `python -m pytest workflow/test_<name>.py`.
+@AGENTS.md

package/installable-surfaces.manifest.json

@@ -14,6 +14,7 @@
     "audit-rubrics"
   ],
   "root_files": [
+    "AGENTS.md",
     "CLAUDE.md",
     "codex-capability-map.json",
     "installable-surfaces.manifest.json"

package/output-styles/AGENTS.md

@@ -0,0 +1,15 @@
+# output-styles
+
+Output-style instruction files installed into `~/.claude/output-styles/` by `bin/install.mjs`. Each file instructs an agent or session to respond in a specific voice or format.
+
+## Files
+
+No output-style instruction files ship in this directory. The active caveman behavior lives in `agents/caveman.md`.
+
+## Format
+
+Each file uses YAML frontmatter (`name`, `description`, optional `keep-coding-instructions`) followed by Markdown instructions. The `keep-coding-instructions: true` flag tells Claude Code to keep the session's coding rules even when this style is active.
+
+## Adding a style
+
+Create a `.md` file with frontmatter and behavioral instructions, then run `bin/install.mjs` to copy it to `~/.claude/output-styles/`.

package/output-styles/CLAUDE.md

@@ -1,15 +1 @@
-# output-styles
-
-Output-style instruction files installed into `~/.claude/output-styles/` by `bin/install.mjs`. Each file instructs an agent or session to respond in a specific voice or format.
-
-## Files
-
-No output-style instruction files ship in this directory. The active caveman behavior lives in `agents/caveman.md`.
-
-## Format
-
-Each file uses YAML frontmatter (`name`, `description`, optional `keep-coding-instructions`) followed by Markdown instructions. The `keep-coding-instructions: true` flag tells Claude Code to keep the session's coding rules even when this style is active.
-
-## Adding a style
-
-Create a `.md` file with frontmatter and behavioral instructions, then run `bin/install.mjs` to copy it to `~/.claude/output-styles/`.
+@AGENTS.md

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "claude-dev-env",
-    "version": "2.13.0",
+    "version": "2.14.0",
     "description": "Claude Code development standards — rules, hooks, agents, commands, and skills",
     "type": "module",
     "bin": {
@@ -26,6 +26,7 @@
         "installable-surfaces.manifest.json",
         "_shared/",
         "audit-rubrics/",
+        "AGENTS.md",
         "CLAUDE.md",
         "!**/__pycache__/**",
         "!**/*.py[cod]",

package/rules/AGENTS.md

@@ -0,0 +1,61 @@
+---
+paths:
+  - "**/rules/**"
+---
+
+# rules
+
+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
+
+| File | Rule |
+|---|---|
+| `agent-spawn-protocol.md` | Check context sufficiency before a spawn and ask subagents for file-and-line answers; `/prompt-generator` is recommended for a complex or user-facing spawn |
+| `anti-corollary-tests.md` | Tests must carry information: no corollary matrices over canonical reductions, no suite that only matches a dead-implementation default, stated mutation in the audit lane |
+| `ask-user-question-required.md` | Every user-directed question goes through the `AskUserQuestion` tool — no plain-text questions |
+| `bdd.md` | BDD discovery-driven development workflow and Example Mapping reference |
+| `claims-as-quotes.md` | On agent reports, hand-offs, review verdicts, and PR or commit prose, a design-gating claim travels with its quoted lines and `path:line` reference; chat keeps research-mode compact citations; a claim without its quote is a lead to check |
+| `cleanup-temp-files.md` | Remove temporary files created during a task when the task is complete |
+| `code-standards.md` | Pointer to `CODE_RULES.md` as the single source of truth, including §8 (TDD) and §7 (right-sizing); BDD is the outer process and TDD the inner loop |
+| `confirm-implementation-forks.md` | Stop and ask when two or more workable implementation paths change the deliverable |
+| `conservative-action.md` | Research and recommend when intent is ambiguous; act only on explicit request |
+| `context7.md` | Use Context7 MCP to fetch current library docs; always prefer live docs over built-in knowledge |
+| `destructive-commands.md` | Allowed removal forms and the ephemeral namespace the `destructive_command_blocker` auto-allows; keep destructive literals out of a Bash command string even as data |
+| `doc-inventory-integrity.md` | Three inventory shapes stay in step with the code: a per-directory `CLAUDE.md` file list, a package `README`/`SKILL.md` inventory, and an env-var summary table |
+| `doc-prose-cuts.md` | Four sentence shapes to cut from prose: exclusion claims, justification sentences, conversation references, and time references |
+| `docstring-prose-matches-implementation.md` | Prose enumerations in docstrings cover every behavior the body applies |
+| `durable-post-artifacts.md` | GitHub post bodies never reference volatile scratch paths; text embeds inline and binary artifacts upload to the `artifacts` release with the permanent URL linked |
+| `eli11-replies.md` | Every chat reply the user reads follows one shape: action first, detail last, few words; `plain-language.md` governs word choice, this rule governs reply length and shape |
+| `explore-thoroughly.md` | Read relevant files and map existing patterns before proposing a change |
+| `falsify-before-green.md` | A check's green counts as evidence only after that same check ran red on a named break, with a passing control beside it |
+| `file-global-constants.md` | File-global constants need at least two same-file references; otherwise move value to `config/` |
+| `filesystem-search.md` | Every filesystem search names a scope; `es.exe`, `Glob`, `Grep`, and `Read` are equally sanctioned, and the `unscoped_search_blocker` denies a walk from a root |
+| `gh-cli-conventions.md` | `--body-file` for every `gh` body; `--paginate --slurp` piped to external `jq` for every paginated list read |
+| `git-workflow.md` | PR workflow: always create as draft, one commit per review stage, never commit working docs or images; carries the review-response protocol and a See-also block for its seven siblings |
+| `hedging-claims.md` | State the evidence or name the claim unverified; the `hedging_language_blocker` Stop hook sends a hedged response back for a re-check |
+| `long-horizon-autonomy.md` | Autonomous-run behaviors: act on what you have, do not end on a promise, delegate and keep working |
+| `measurement-denominators.md` | Every reported count names what it scanned and carries its denominator; a rate needs two runs; the consumer cross-checks the count against the scope its denominator names |
+| `nas-ssh-invocation.md` | Reach the NAS through the paramiko-backed `nas_ssh_key.py` runner, which signs in-process; every ssh-family client reads the key through file permissions, refuses it, and stalls an unattended run on a password prompt |
+| `no-cross-skill-duplicate-helpers.md` | Within one skill a duplicated helper is blocked; across two skill folders a small self-contained copy is a sanctioned isolation tradeoff that draws a non-blocking advisory naming the source skill |
+| `orphan-css-class.md` | Every `class="..."` attribute in Python-generated markup has a matching selector in the `<style>` block |
+| `opus5-communication-contract.md` | Visible concision, one-sentence first progress, important-change-only updates, outcome-first finals, thinking-disabled tool narration (`opus5-communication-contract-v1`) |
+| `paired-test-coverage.md` | A public function omitted by a module's established paired test suite must get a behavioral test |
+| `parallel-tools.md` | Make all independent tool calls in a single response |
+| `plain-illustrative-docstrings.md` | Public docstring narrative reads plainly and shows behavior with a diagram block (a `::` example or a doctest), painting a concrete scene a general developer follows on first read; a run-on backstop hook, a prose-wall backstop hook, and Category O9 audit enforce it |
+| `plain-language.md` | Everyday words, short active sentences, lead with the answer |
+| `prompt-workflow-context-controls.md` | Keep prompt-workflow instruction layers small and stable; load heavy skills on demand |
+| `re-stage-before-commit.md` | Stage the files edited this session before `git commit`; the session edit stage gate denies a commit that leaves a tracked session edit unstaged, with `-a`, a pathspec, a preceding `git add`, and `# partial-commit` as escapes |
+| `research-mode.md` | Three anti-hallucination constraints: say "I don't know", verify with citations, quote for factual grounding |
+| `shell-invocation.md` | Windows shell commands run through `pwsh`; no `$(...)`, backtick, or process substitution in a Bash tool command |
+| `testing.md` | Test quality and infrastructure standards |
+| `vault-context.md` | Search Obsidian vault for prior sessions and decisions before substantive project work |
+| `verify-before-asking.md` | Answer questions by inspecting files or running tools before asking; recalled facts expire until re-checked this session |
+| `verify-runtime-state.md` | A "component is fine / not at fault" verdict rests on a live probe this session, never code reading or prior-session memory |
+| `windows-filesystem-safe.md` | Use safe `rmtree` patterns on Windows; `mkdirSync` with `recursive: true` on possibly-existing paths |
+| `workers-done-before-complete.md` | A task reaches `completed` only when every spawned worker has finished and its results are merged into run state |
+| `workflow-substitution-slots.md` | Per-iteration values in `.workflow.js` templates use angle-bracket slots |
+
+## Hook enforcement
+
+Rules marked with ⚡ in `~/.claude/docs/CODE_RULES.md` are backed by a blocking hook in `hooks/blocking/`. Rules without a hook are judgment-based and enforced via audit rubrics (`audit-rubrics/`).