claude-dev-env 2.13.0 → 2.14.1

package/hooks/hooks_constants/working_style_prompt_constants.py

@@ -7,24 +7,33 @@ __all__ = [
 ]
 
 WORKING_STYLE_PROMPT = (
-    "document everything in a location you can find later, rather than relying on "
-    "memory. scratch txt file you'll keep running as you go; ledger, if you will."
-    "Always, without exception, write in plain english. Keep responses focused, "
-    "brief, and concise. Keep disclaimers and caveats short, and spend most of the "
-    "response on the main answer. When asked to explain something, give a high-level "
-    "summary unless an in-depth explanation is specifically requested."
-    "Before your first tool call, say in one sentence what you're about to do. While "
-    "working, give a brief update only when you find something important or change "
-    "direction. When you finish, lead with the outcome: your first sentence should "
-    "answer \"what happened\" or \"what did you find,\" with supporting detail after "
-    "it for readers who want it."
-    "Match the length of written documents to what the task needs: cover the "
-    "substance, but do not pad with filler sections, redundant summaries, or "
-    "boilerplate."
-    "Deliver what was asked, at the scope intended. Make routine judgment calls "
-    "yourself, and check in only when different readings of the request would lead "
-    "to materially different work. If the request seems mistaken or a better "
-    "approach exists, say so in a sentence and continue with the task as asked "
-    "rather than quietly narrowing, widening, or transforming it. Finish the whole "
-    "task, and stop short of actions that are clearly beyond what was asked."
+    "Document each task in a location that remains easy to find later. Keep a "
+    "running scratch text ledger as you work. Write in plain English. Keep responses "
+    "focused, brief, and concise. Keep disclaimers and caveats short while giving "
+    "the main answer most of the response. Give a high-level explanation by default "
+    "and provide depth when the request calls for it. "
+    "Before your first tool call, state your next action in one sentence. While "
+    "working, give brief updates when you find important information or change "
+    "direction. Finish with the outcome in the first sentence, then provide "
+    "supporting detail for readers who want it. "
+    "Match written-document length to the task. Cover the substance and keep every "
+    "section, summary, and phrase useful. "
+    "Deliver the requested work at its intended scope. Make routine judgment calls "
+    "yourself. Ask for direction when different interpretations would produce "
+    "materially different work. When a request seems mistaken or a better approach "
+    "exists, state the concern briefly and continue with the requested task. Finish "
+    "the complete task and keep actions within the requested scope. "
+    "When a request has multiple reasonable interpretations, state your understanding "
+    "and the assumptions that shape the work. Ask one focused clarification question "
+    "when the ambiguity changes the outcome, scope, audience, format, or risk. Use a "
+    "clearly stated low-risk assumption when the intended result remains stable. "
+    "Pause for the user's choice before making a high-impact decision. "
+    "Use positive prose throughout every generated text surface, including "
+    "documentation, comments, user-facing messages, sub-agent prompts, labels, "
+    "plans, and instructions. Write each point as one direct affirmative statement "
+    "that presents only the intended action, fact, reason, or outcome. Use current, "
+    "immediately relevant context and omit historical clutter. Use plain language, "
+    "full terms, and simple descriptive names that communicate their meaning "
+    "immediately. Keep all text concise, clear, direct, and focused entirely on "
+    "useful information."
 )

package/hooks/lifecycle/AGENTS.md

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

package/hooks/lifecycle/CLAUDE.md

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

package/hooks/observability/AGENTS.md

@@ -0,0 +1,20 @@
+# hooks/observability
+
+PostToolUse hooks that record agent behavior for later review. These hooks do not block tool calls; they log or annotate them.
+
+## Key files
+
+| File | Event | What it does |
+|---|---|---|
+| `instructions_loaded_logger.py` | PostToolUse (file load events) | Appends a JSONL record to `~/.claude/logs/instructions_loaded.jsonl` each time Claude Code loads a context file (CLAUDE.md, rules, skills), capturing the file path, load reason, memory type, and session ID |
+| `session_file_edit_tracker.py` | PostToolUse (Write/Edit/MultiEdit) | Records the resolved absolute path of each file edited this session into a per-session JSON file under the system temp directory, for the session edit stage gate to read at commit time |
+| `prose_matcher_advisory.py` | Advisory emit from prose matchers | Privacy-safe JSONL candidates (`matcher_id`, surface, context fingerprint, label) plus keep/narrow/drop/advisory classification against the sample floor |
+| `test_instructions_loaded_logger.py` | — | Tests for `instructions_loaded_logger.py` |
+| `test_session_file_edit_tracker.py` | — | Tests for `session_file_edit_tracker.py` |
+| `test_prose_matcher_advisory.py` | — | Tests for advisory emit and precision classification |
+
+## Conventions
+
+- The log file is append-only; the hook creates the parent directory if needed.
+- Errors during logging are caught and written as error records rather than propagated — the hook never blocks the tool call.
+- Tests run with `python -m pytest observability/test_instructions_loaded_logger.py`.

package/hooks/observability/CLAUDE.md

@@ -1,20 +1 @@
-# hooks/observability
-
-PostToolUse hooks that record agent behavior for later review. These hooks do not block tool calls; they log or annotate them.
-
-## Key files
-
-| File | Event | What it does |
-|---|---|---|
-| `instructions_loaded_logger.py` | PostToolUse (file load events) | Appends a JSONL record to `~/.claude/logs/instructions_loaded.jsonl` each time Claude Code loads a context file (CLAUDE.md, rules, skills), capturing the file path, load reason, memory type, and session ID |
-| `session_file_edit_tracker.py` | PostToolUse (Write/Edit/MultiEdit) | Records the resolved absolute path of each file edited this session into a per-session JSON file under the system temp directory, for the session edit stage gate to read at commit time |
-| `prose_matcher_advisory.py` | Advisory emit from prose matchers | Privacy-safe JSONL candidates (`matcher_id`, surface, context fingerprint, label) plus keep/narrow/drop/advisory classification against the sample floor |
-| `test_instructions_loaded_logger.py` | — | Tests for `instructions_loaded_logger.py` |
-| `test_session_file_edit_tracker.py` | — | Tests for `session_file_edit_tracker.py` |
-| `test_prose_matcher_advisory.py` | — | Tests for advisory emit and precision classification |
-
-## Conventions
-
-- The log file is append-only; the hook creates the parent directory if needed.
-- Errors during logging are caught and written as error records rather than propagated — the hook never blocks the tool call.
-- Tests run with `python -m pytest observability/test_instructions_loaded_logger.py`.
+@AGENTS.md

package/hooks/session/AGENTS.md

@@ -0,0 +1,33 @@
+# hooks/session
+
+SessionStart and SessionEnd hooks for per-session setup and cleanup: removing stale session and plugin-data directories at startup, detecting unregistered repositories, starting the session's task-list maintenance loop, injecting working-style guidance, and clearing PR-author swap state at shutdown.
+
+## Key files
+
+| File | Event | What it does |
+|---|---|---|
+| `session_env_cleanup.py` | SessionStart | Removes the current session's pre-existing `~/.claude/session-env/<session_id>/` directory and prunes sibling entries older than the stale-age threshold. Prevents `EEXIST` errors from non-recursive `mkdir` calls in the Bash tool on Windows. |
+| `gh_pr_author_session_cleanup.py` | SessionEnd | Clears any PR-author swap state left over from the current session |
+| `session_edit_tracker_cleanup.py` | SessionStart, SessionEnd | Deletes the tracker file for the running Claude Code conversation from the system temp directory — at start for a clean slate and at end for a clean exit. A tracker is read only by the conversation that wrote it, so a live idle tracker is kept while a peer cleans up |
+| `plugin_data_dir_cleanup.py` | SessionStart | Removes empty plugin data directories at startup to prevent `EEXIST` when Claude Code recreates them |
+| `untracked_repo_detector.py` | SessionStart | Detects when the session cwd is inside a git repository that is not registered in `~/.claude/project-paths.json` and logs a warning |
+| `task_list_loop_starter.py` | SessionStart | Emits an `additionalContext` directive telling Claude to keep the task list current on a 10-minute cadence, starting the `/loop` skill when one is not already running. Writes nothing and runs no tools itself. |
+| `orchestrator_auto_starter.py` | SessionStart | Opt-in (`CLAUDE_ORCHESTRATOR_AUTO_STARTER_ENABLED`) consumer of the shared SessionStart injector; emits orchestrator skill context when enabled. Manual `/orchestrator` unchanged. |
+| `issue_tracker_session_starter.py` | SessionStart | Opt-in (`CLAUDE_ISSUE_TRACKER_SESSION_STARTER_ENABLED`) and repository-gated (git root in `~/.claude/project-paths.json`) issue-tracker skill context. |
+| `_path_setup.py` | — | Inserts the hooks directory on `sys.path` so SessionStart scripts import `hooks_constants` with top-level imports. |
+| `test_orchestrator_auto_starter.py` | — | Tests for `orchestrator_auto_starter.py` |
+| `test_issue_tracker_session_starter.py` | — | Tests for `issue_tracker_session_starter.py` |
+| `working_style_prompt.py` | SessionStart | Emits an `additionalContext` block with the fixed working-style prompt (running ledger, plain English, outcome-first finish, scope discipline). Writes nothing and runs no tools itself. |
+| `test_gh_pr_author_session_cleanup.py` | — | Tests for `gh_pr_author_session_cleanup.py` |
+| `test_session_edit_tracker_cleanup.py` | — | Tests for `session_edit_tracker_cleanup.py` |
+| `test_session_env_cleanup.py` | — | Tests for `session_env_cleanup.py` |
+| `test_untracked_repo_detector.py` | — | Tests for `untracked_repo_detector.py` |
+| `test_task_list_loop_starter.py` | — | Tests for `task_list_loop_starter.py` |
+| `test__path_setup.py` | — | Tests for `_path_setup.py` |
+| `test_working_style_prompt.py` | — | Tests for `working_style_prompt.py` |
+
+## Conventions
+
+- `session_env_cleanup.py` is Windows-specific in effect but safe to run on all platforms; it exits 0 when the target directory does not exist.
+- Constants (stale-age threshold, directory names) live in `hooks_constants/session_env_cleanup_constants.py`.
+- Tests run with `python -m pytest session/test_<name>.py`.

package/hooks/session/CLAUDE.md

@@ -1,33 +1 @@
-# hooks/session
-
-SessionStart and SessionEnd hooks for per-session setup and cleanup: removing stale session and plugin-data directories at startup, detecting unregistered repositories, starting the session's task-list maintenance loop, injecting working-style guidance, and clearing PR-author swap state at shutdown.
-
-## Key files
-
-| File | Event | What it does |
-|---|---|---|
-| `session_env_cleanup.py` | SessionStart | Removes the current session's pre-existing `~/.claude/session-env/<session_id>/` directory and prunes sibling entries older than the stale-age threshold. Prevents `EEXIST` errors from non-recursive `mkdir` calls in the Bash tool on Windows. |
-| `gh_pr_author_session_cleanup.py` | SessionEnd | Clears any PR-author swap state left over from the current session |
-| `session_edit_tracker_cleanup.py` | SessionStart, SessionEnd | Deletes the tracker file for the running Claude Code conversation from the system temp directory — at start for a clean slate and at end for a clean exit. A tracker is read only by the conversation that wrote it, so a live idle tracker is kept while a peer cleans up |
-| `plugin_data_dir_cleanup.py` | SessionStart | Removes empty plugin data directories at startup to prevent `EEXIST` when Claude Code recreates them |
-| `untracked_repo_detector.py` | SessionStart | Detects when the session cwd is inside a git repository that is not registered in `~/.claude/project-paths.json` and logs a warning |
-| `task_list_loop_starter.py` | SessionStart | Emits an `additionalContext` directive telling Claude to keep the task list current on a 10-minute cadence, starting the `/loop` skill when one is not already running. Writes nothing and runs no tools itself. |
-| `orchestrator_auto_starter.py` | SessionStart | Opt-in (`CLAUDE_ORCHESTRATOR_AUTO_STARTER_ENABLED`) consumer of the shared SessionStart injector; emits orchestrator skill context when enabled. Manual `/orchestrator` unchanged. |
-| `issue_tracker_session_starter.py` | SessionStart | Opt-in (`CLAUDE_ISSUE_TRACKER_SESSION_STARTER_ENABLED`) and repository-gated (git root in `~/.claude/project-paths.json`) issue-tracker skill context. |
-| `_path_setup.py` | — | Inserts the hooks directory on `sys.path` so SessionStart scripts import `hooks_constants` with top-level imports. |
-| `test_orchestrator_auto_starter.py` | — | Tests for `orchestrator_auto_starter.py` |
-| `test_issue_tracker_session_starter.py` | — | Tests for `issue_tracker_session_starter.py` |
-| `working_style_prompt.py` | SessionStart | Emits an `additionalContext` block with the fixed working-style prompt (running ledger, plain English, outcome-first finish, scope discipline). Writes nothing and runs no tools itself. |
-| `test_gh_pr_author_session_cleanup.py` | — | Tests for `gh_pr_author_session_cleanup.py` |
-| `test_session_edit_tracker_cleanup.py` | — | Tests for `session_edit_tracker_cleanup.py` |
-| `test_session_env_cleanup.py` | — | Tests for `session_env_cleanup.py` |
-| `test_untracked_repo_detector.py` | — | Tests for `untracked_repo_detector.py` |
-| `test_task_list_loop_starter.py` | — | Tests for `task_list_loop_starter.py` |
-| `test__path_setup.py` | — | Tests for `_path_setup.py` |
-| `test_working_style_prompt.py` | — | Tests for `working_style_prompt.py` |
-
-## Conventions
-
-- `session_env_cleanup.py` is Windows-specific in effect but safe to run on all platforms; it exits 0 when the target directory does not exist.
-- Constants (stale-age threshold, directory names) live in `hooks_constants/session_env_cleanup_constants.py`.
-- Tests run with `python -m pytest session/test_<name>.py`.
+@AGENTS.md

package/hooks/session/gh_pr_author_session_cleanup.py

@@ -34,6 +34,7 @@ if hooks_parent_directory not in sys.path:
     sys.path.insert(0, hooks_parent_directory)
 
 from _gh_pr_author_swap_utils import (  # noqa: E402
+    _build_restore_failure_message,
     _delete_state_file,
     _lstat_indicates_attacker_planted,
     _read_original_account,
@@ -142,8 +143,12 @@ def _restore_stale_state_file(state_file: Path) -> None:
         _delete_state_file(state_file)
     else:
         _write_line(
-            f"[gh-pr-author-cleanup] failed to restore active gh account to {original_account!r} from "
-            f"stale state file {state_file}; left in place for next session",
+            _build_restore_failure_message(
+                "gh-pr-author-cleanup",
+                original_account,
+                state_file,
+                "stale state file",
+            ),
             sys.stderr,
         )
 

package/hooks/session/task_list_loop_starter.py

@@ -2,9 +2,9 @@
 """SessionStart hook — start a task-list maintenance loop for the session.
 
 At session start this hook emits an ``additionalContext`` directive asking Claude
-to keep the session's task list current on a 10-minute cadence, starting the
-``/loop`` skill when one is not already running. The hook writes nothing and runs
-no tools itself. Claude reads the directive and invokes the ``/loop`` skill.
+to keep the session's task list current on a 10-minute cadence. Claude reuses the
+active ``/loop`` skill when available and starts the skill for the session's first
+task-list maintenance loop.
 """
 
 from __future__ import annotations

package/hooks/session/test_gh_pr_author_session_cleanup.py

@@ -343,7 +343,8 @@ def test_restore_stale_state_file_logs_when_switch_fails(
 
     captured_streams = capsys.readouterr()
     assert state_file.exists()
-    assert "[gh-pr-author-cleanup] failed to restore" in captured_streams.err
+    assert "[gh-pr-author-cleanup] Restore the gh account" in captured_streams.err
+    assert "gh account switch requires attention" in captured_streams.err
     assert "'jl-cmd'" in captured_streams.err
     assert str(state_file) in captured_streams.err
 

package/hooks/session/test_task_list_loop_starter.py

@@ -45,9 +45,17 @@ class TestSessionDirective:
         emitted = json.loads(_run_main())
         assert "/loop 10m" in emitted["additionalContext"]
 
-    def test_directive_is_idempotent_about_an_existing_loop(self) -> None:
+    def test_directive_runs_the_instruction_immediately(self) -> None:
         emitted = json.loads(_run_main())
-        assert "not already running" in emitted["additionalContext"]
+        assert "Run that instruction once immediately when starting the loop, then" in emitted[
+            "additionalContext"
+        ]
+
+    def test_directive_reuses_an_existing_loop(self) -> None:
+        emitted = json.loads(_run_main())
+        assert "Reuse the active task-list maintenance loop when available." in emitted[
+            "additionalContext"
+        ]
 
     def test_build_session_directive_returns_the_shared_constant(self) -> None:
         assert starter.build_session_directive() == TASK_LIST_LOOP_DIRECTIVE

package/hooks/session/test_working_style_prompt.py

@@ -36,12 +36,17 @@ class TestWorkingStylePrompt:
         emitted = json.loads(_run_main())
         assert emitted["additionalContext"] == WORKING_STYLE_PROMPT
 
-    def test_emitted_prompt_carries_ledger_and_scope_lines(self) -> None:
+    def test_emitted_prompt_preserves_existing_guidance_and_adds_policy(self) -> None:
         emitted = json.loads(_run_main())
         prompt_text = emitted["additionalContext"]
-        assert "scratch txt file you'll keep running as you go; ledger, if you will." in prompt_text
-        assert "Deliver what was asked, at the scope intended." in prompt_text
-        assert 'answer "what happened" or "what did you find,"' in prompt_text
+        assert "Document each task in a location that remains easy to find later." in prompt_text
+        assert "Deliver the requested work at its intended scope." in prompt_text
+        assert "Use positive prose throughout every generated text surface" in prompt_text
+        assert "Write each point as one direct affirmative statement" in prompt_text
+        assert "Use plain language, full terms, and simple descriptive names" in prompt_text
+        assert "When a request has multiple reasonable interpretations" in prompt_text
+        assert "Ask one focused clarification question" in prompt_text
+        assert "Pause for the user's choice before making a high-impact decision." in prompt_text
 
     def test_build_session_directive_returns_the_shared_constant(self) -> None:
         assert starter.build_session_directive() == WORKING_STYLE_PROMPT

package/hooks/validation/AGENTS.md

@@ -0,0 +1,20 @@
+# 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`.

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",
     )