claude-dev-env 2.12.0 → 2.14.0

package/hooks/blocking/AGENTS.md

@@ -0,0 +1,123 @@
+# hooks/blocking
+
+PreToolUse hooks that deny (block) tool calls when a rule is violated. The main enforcer is `code_rules_enforcer.py`, which routes each Write/Edit through a suite of focused check modules. Every other file in this directory is either a standalone blocker, a check module, or a test.
+
+## Subdirectory
+
+| Directory | Role |
+|---|---|
+| `tdd_enforcer_parts/` | Concern modules the `tdd_enforcer.py` entry hook wires together: path classification, content analysis, candidate-path resolution, freshness, git-tracking restore detection, decisions, and constants |
+| `claude_md_orphan_file_blocker_parts/` | Concern modules the `claude_md_orphan_file_blocker.py` entry hook wires together: reference extraction, subtree scan, scan plan, decision, and constants |
+| `package_inventory_stale_blocker_parts/` | Concern modules the `package_inventory_stale_blocker.py` entry hook wires together: inventory detection, decision, and constants |
+| `inventory_intent_records/` | The shared per-session pending-intent store both inventory blockers read to break the file/row add-order deadlock |
+| `pii_prevention_blocker_parts/` | Concern modules the `pii_prevention_blocker.py` entry hook wires together: per-repository scan exemption, the per-repository allowlist of exact values a commit may carry, and resolving the repository a commit command targets (with `config/` for the resolution deny-message constants) |
+| `tests/` | pytest suite for `pii_prevention_blocker.py` repository resolution and the `pii_prevention_blocker_parts` modules |
+
+## Core enforcer
+
+| File | What it does |
+|---|---|
+| `code_rules_enforcer.py` | Entry point — reads PreToolUse stdin, reconstructs post-edit content, dispatches all check modules, and returns a block with a per-issue list when any check fails |
+
+The check modules it calls are the `code_rules_<concern>.py` files below.
+
+## Check modules (imported by `code_rules_enforcer.py`)
+
+| Module | Concern |
+|---|---|
+| `code_rules_annotations_length.py` | Parameter/return annotations, function length, pytest fixture annotation requirements |
+| `code_rules_banned_identifiers.py` | Banned short names (`ctx`, `cfg`, `msg`, etc.), banned prefixes (`handle_`, `process_`, etc.) |
+| `code_rules_boolean_mustcheck.py` | Boolean naming (`is_`/`has_`/… prefixes) and must-check return values |
+| `code_rules_command_dispatch.py` | A `hooks/blocking/` command classifier matching a multi-word command regex without a start anchor or first-word tokenization |
+| `code_rules_comments.py` | No new inline comments; advisory on deletion of existing ones |
+| `code_rules_constants_config.py` | Constants must live in `config/`; file-global constant use-count |
+| `code_rules_dead_argparse_argument.py` | Argparse arguments with no references in the same file |
+| `code_rules_dead_config_field.py` | `*Config` / `*Selectors` dataclass fields with no live references |
+| `code_rules_dead_dataclass_field.py` | Dataclass fields with no consuming references |
+| `code_rules_dead_module_constant.py` | `UPPER_SNAKE` constants in `*_constants.py` modules with no importers |
+| `code_rules_dead_split_branch.py` | A conditional whose falsy branch is unreachable because the tested value comes from a separator `str.split()`, which never returns an empty list |
+| `code_rules_docstrings.py` | Google-style docstrings; `Args:` section matches signature; fallback-branch coverage |
+| `code_rules_duplicate_body.py` | A function body copied from a sibling module, or a helper body inlined as a block inside a larger function in the same file |
+| `code_rules_imports_logging.py` | Imports at top of file; logging format-arg style; printf tokens in `str.format`-logger messages |
+| `code_rules_js_conventions.py` | Boolean-prefix naming and banned identifiers for JavaScript/TypeScript declarations and `@param {boolean}` JSDoc, scoped to changed lines |
+| `code_rules_magic_values.py` | No magic numbers or strings in production code bodies |
+| `code_rules_mock_completeness.py` | Mock calls that skip required arguments |
+| `code_rules_naming_collection.py` | Collection names must use `all_*` prefix |
+| `code_rules_optional_params.py` | No optional parameters where a required one would do |
+| `code_rules_orphan_css_class.py` | CSS class attributes in Python markup with no matching `.<class>` selector |
+| `code_rules_paired_test.py` | A public function omitted by a module's established paired test suite must get a behavioral test — checked on both the production-module write and the stem-matched test-file write |
+| `code_rules_path_utils.py` | Path utility helpers shared across check modules |
+| `code_rules_paths_syspath.py` | `sys.path.insert` must be guarded |
+| `code_rules_probe_chains.py` | Probe-chain detection logic |
+| `code_rules_probe_detection.py` | Probe pattern detection helpers |
+| `code_rules_probe_recording.py` | Probe recording utilities |
+| `code_rules_scope_binding.py` | Scope/binding analysis utilities |
+| `code_rules_shared.py` | Shared dataclasses and helpers used by multiple check modules |
+| `code_rules_string_magic.py` | Magic string detection with masking and f-string support; whitespace-only indentation literals in function bodies |
+| `code_rules_test_assertions.py` | Test assertion style rules |
+| `code_rules_test_layout.py` | Dead scaffolding in a test module: a private module constant read by no other line, and an unused parameter on a private test helper |
+| `code_rules_test_branching_except.py` | No bare or broad `except` in test branches |
+| `code_rules_test_isolation.py` | Tests must not rely on home-dir or temp-dir side effects |
+| `code_rules_type_escape.py` | No `Any` imports, `cast()`, or `# type: ignore` outside boundary files |
+| `code_rules_typeddict_stub.py` | TypedDict pairs (`_encode_*`/`_decode_*`) must both exist in the same module |
+| `code_rules_unused_imports.py` | Unused module-level imports |
+
+## Other standalone blockers
+
+| File | Event | What it blocks |
+|---|---|---|
+| `orchestrator_refresh_reschedule_gate.py` | PreToolUse (ScheduleWakeup/CronCreate) | `/orchestrator-refresh` re-arm when run status is not `active` |
+| `block_main_commit.py` | PreToolUse (Bash) | `git commit`/`git push` directly to `main` |
+| `bot_mention_comment_blocker.py` | PreToolUse (Write/Edit) | PR review comments that @-mention a bot |
+| `claude_md_orphan_file_blocker.py` | PreToolUse (Write/Edit/MultiEdit) | Per-directory `CLAUDE.md` table cells naming a bare filename absent from the directory subtree |
+| `conventional_pr_title_gate.py` | PreToolUse (Bash) | `gh pr create`/`gh pr edit` with a `--title` that is not a Conventional Commit, in a repo whose CI runs a semantic-pull-request title check |
+| `destructive_command_blocker.py` | PreToolUse (Bash/PowerShell) | Shell commands with destructive literals (`rm -rf`, `git reset --hard`, etc.) |
+| `docstring_rule_gate_count_blocker.py` | PreToolUse (Write/Edit/MultiEdit) | A stale spelled-out gate-validator count in `docstring-prose-matches-implementation.md` — the "N more gate validators" / "M gated slices" count drifting from the `check_docstring_*` validators the prose names |
+| `duplicate_rmtree_helper_blocker.py` | PreToolUse (Write/Edit) | A local re-definition of the Windows-safe rmtree helper trio (`_strip_read_only_and_retry`, `_force_remove_tree` / `force_rmtree`) in place of importing a shared helper |
+| `eli11_reply_enforcer.py` | Stop | Final replies breaking the `eli11-replies` shape — more than 6 bullet lines, more than 2 list lines over 20 words each, or multi-line instructions with no numbered step among the lead lines. Code fences, inline code, blockquotes, table rows, and link targets come off before the reply is judged. |
+| `env_var_table_code_drift_blocker.py` | PreToolUse (Write/Edit/MultiEdit) | A markdown env-var summary table row attributing an environment variable to a code file whose source never references that variable name |
+| `es_exe_path_rewriter.py` | PreToolUse | Rewrites paths referencing `.exe` under the Everything search path |
+| `fable_spawn_gate.py` | PreToolUse (Agent/Task) | An `Agent` or `Task` spawn whose prompt carries no `FABLE-SPAWN-AUTHORIZED` token and whose model field reads `fable` in any letter case — the bare alias, or a delimiter segment of a full model id, so `claude-fable-5` is denied too |
+| `gh_body_arg_blocker.py` | PreToolUse (Bash) | `gh` commands passing `--body`/`-b` directly (requires `--body-file` instead) |
+| `gh_pr_author_enforcer.py` | PreToolUse | Enforces PR author identity rules |
+| `gh_pr_author_restore.py` | PostToolUse | Restores PR author after a tool call |
+| `hedging_language_blocker.py` | Stop | Responses with hedging words (`likely`, `probably`, `appears to`); armed only when `CLAUDE_PROSE_STYLE_ENFORCEMENT` is on (default off) |
+| `hook_prose_detector_consistency.py` | PreToolUse (Write/Edit) | Hook docstrings/messages that claim a trigger the detector cannot fire on; armed only when `CLAUDE_PROSE_STYLE_ENFORCEMENT` is on (default off) |
+| `intent_only_ending_blocker.py` | Stop | Responses that end on a plan or intent without doing the work; armed only when `CLAUDE_PROSE_STYLE_ENFORCEMENT` is on (default off) |
+| `open_questions_in_plans_blocker.py` | PreToolUse (Write/Edit) | Plan documents with unresolved open questions |
+| `nas_ssh_binary_enforcer.py` | PreToolUse (Bash) | A bare `ssh`/`scp`/`sftp` command word targeting the NAS (Git Bash's MSYS ssh stalls on an interactive password prompt), or the full `System32/OpenSSH` binary to that host without `-o BatchMode=yes` |
+| `package_inventory_stale_blocker.py` | PreToolUse (Write) | A new production code file created in a directory whose `README.md`/`CLAUDE.md` inventory (or a parent skill's `SKILL.md` Layout table mapping the `scripts/` subdirectory) names two or more sibling files but no entry for the new file |
+| `pii_commit_command.py` | library | Token-aware git-commit detection reused by `pii_prevention_blocker.py` |
+| `pii_payload_scan.py` | library | Write/Edit and durable post-body PII evaluation reused by `pii_prevention_blocker.py` |
+| `pii_prevention_blocker.py` | PreToolUse (Write/Edit/MultiEdit/Bash/PowerShell/MCP GitHub) | Entry hook — content that carries high-confidence personal data or secrets (real emails, home-dir paths, private IPs, credential material) on write, durable GitHub posts, or staged commit paths; resolves the staged-commit repository from the command it gates (via `pii_prevention_blocker_parts`), not the session working directory |
+| `pii_scanner.py` | library | Pure text scanners shared by `pii_prevention_blocker.py` |
+| `piped_pytest_blocker.py` | PreToolUse (Bash) | A pytest run whose output feeds a pipe, where the pipeline reports the exit code of the command on the right |
+| `plain_language_blocker.py` | PreToolUse (Write/Edit/AskUserQuestion) | Heavy or jargon words in user-facing prose when `CLAUDE_PROSE_STYLE_ENFORCEMENT` is on (default off); AskUserQuestion lean-block structure stays always on |
+| `precommit_code_rules_gate.py` | PreToolUse (Bash) | Staged changes that fail the CODE_RULES gate at commit time |
+| `pytest_testpaths_orphan_blocker.py` | PreToolUse (Write/Edit/MultiEdit) | New `test_*.py` files created under a directory absent from a package's explicit pytest `testpaths` allowlist |
+| `question_to_user_enforcer.py` | Stop | User-directed questions not routed through `AskUserQuestion` |
+| `send_user_file_open_locally_blocker.py` | PreToolUse (SendUserFile) | A desk-side file attach (`SendUserFile` with `status` not `proactive`); points to opening the file with its native Windows app |
+| `sensitive_file_protector.py` | PreToolUse (Write/Edit) | Writes to sensitive credential or config files |
+| `session_edit_stage_gate.py` | PreToolUse (Bash) | A `git commit` that would drop files edited this session because they are tracked but left unstaged |
+| `session_handoff_blocker.py` | Stop | Responses suggesting a new session mid-task |
+| `shell_substitution_blocker.py` | PreToolUse (Bash) | A command carrying `$(...)`, a live backtick, or `<(...)`/`>(...)` process substitution, which the allowlist matcher cannot descend into |
+| `stale_comment_reference_blocker.py` | PreToolUse (Edit) | An Edit that rewrites a Python code line while keeping the standalone comment directly above it, when that comment names an identifier the rewrite removes from the line |
+| `state_description_blocker.py` | PreToolUse (Write/Edit) | Historical/comparative language in documentation; armed only when `CLAUDE_PROSE_STYLE_ENFORCEMENT` is on (default off) |
+| `subprocess_budget_completeness.py` | PreToolUse | Subprocess calls missing required budget arguments |
+| `tdd_enforcer.py` | PreToolUse (Write/Edit) | Production code written without a matching failing test |
+| `unscoped_search_blocker.py` | PreToolUse (Bash/PowerShell) | A `find` or recursive listing that walks from the filesystem root, a drive root, bare home, or a network share root |
+| `volatile_path_in_post_blocker.py` | PreToolUse (Bash/MCP GitHub) | `gh` post commands and GitHub MCP post tools whose body references a volatile path (job scratch dir, worktree, or system temp) that outlives the durable post |
+| `windows_rmtree_blocker.py` | PreToolUse (Write/Edit) | `shutil.rmtree` with `ignore_errors=True` on Windows |
+| `workflow_substitution_slot_blocker.py` | PreToolUse (Write/Edit) | Workflow templates with bare per-iteration tokens missing angle-bracket slots |
+| `write_existing_file_blocker.py` | PreToolUse (Write) | Write to a path where a file already exists |
+
+## Supporting modules
+
+| File | Role |
+|---|---|
+| `_gh_body_arg_utils.py` | Parsing helpers for `gh_body_arg_blocker.py` |
+
+## Conventions
+
+- Tests live beside each hook as `test_<hookname>.py` or `test_<hookname>_<suffix>.py`. Run with `python -m pytest <test_file>`.
+- Tunable constants live in `hooks_constants/<hook_name>_constants.py`.

package/hooks/blocking/CLAUDE.md

@@ -1,148 +1 @@
-# hooks/blocking
-
-PreToolUse hooks that deny (block) tool calls when a rule is violated. The main enforcer is `code_rules_enforcer.py`, which routes each Write/Edit through a suite of focused check modules. Every other file in this directory is either a standalone blocker, a check module, or a test.
-
-## Subdirectory
-
-| Directory | Role |
-|---|---|
-| `config/` | Shared constants for the verified-commit gate family (`verified_commit_constants.py`) |
-| `tdd_enforcer_parts/` | Concern modules the `tdd_enforcer.py` entry hook wires together: path classification, content analysis, candidate-path resolution, freshness, git-tracking restore detection, decisions, and constants |
-| `verified_commit_gate_parts/` | Concern modules the `verified_commit_gate.py` entry hook wires together: command tokenization, directory-change resolution, gated git-invocation resolution, deny-reason resolution, and deny-payload assembly |
-| `code_review_stamp_write_blocker_parts/` | Concern modules the `code_review_stamp_directory_write_blocker.py` entry hook wires together: the split directory-change-into-stamp matcher and the obfuscated-stamp-path-write matcher |
-| `claude_md_orphan_file_blocker_parts/` | Concern modules the `claude_md_orphan_file_blocker.py` entry hook wires together: reference extraction, subtree scan, scan plan, decision, and constants |
-| `package_inventory_stale_blocker_parts/` | Concern modules the `package_inventory_stale_blocker.py` entry hook wires together: inventory detection, decision, and constants |
-| `inventory_intent_records/` | The shared per-session pending-intent store both inventory blockers read to break the file/row add-order deadlock |
-| `pii_prevention_blocker_parts/` | Concern modules the `pii_prevention_blocker.py` entry hook wires together: per-repository scan exemption, the per-repository allowlist of exact values a commit may carry, and resolving the repository a commit command targets (with `config/` for the resolution deny-message constants) |
-| `tests/` | pytest suite for `pii_prevention_blocker.py` repository resolution and the `pii_prevention_blocker_parts` modules |
-
-## Core enforcer
-
-| File | What it does |
-|---|---|
-| `code_rules_enforcer.py` | Entry point — reads PreToolUse stdin, reconstructs post-edit content, dispatches all check modules, and returns a block with a per-issue list when any check fails |
-
-The check modules it calls are the `code_rules_<concern>.py` files below.
-
-## Check modules (imported by `code_rules_enforcer.py`)
-
-| Module | Concern |
-|---|---|
-| `code_rules_annotations_length.py` | Parameter/return annotations, function length, pytest fixture annotation requirements |
-| `code_rules_banned_identifiers.py` | Banned short names (`ctx`, `cfg`, `msg`, etc.), banned prefixes (`handle_`, `process_`, etc.) |
-| `code_rules_boolean_mustcheck.py` | Boolean naming (`is_`/`has_`/… prefixes) and must-check return values |
-| `code_rules_command_dispatch.py` | A `hooks/blocking/` command classifier matching a multi-word command regex without a start anchor or first-word tokenization |
-| `code_rules_comments.py` | No new inline comments; advisory on deletion of existing ones |
-| `code_rules_constants_config.py` | Constants must live in `config/`; file-global constant use-count |
-| `code_rules_dead_argparse_argument.py` | Argparse arguments with no references in the same file |
-| `code_rules_dead_config_field.py` | `*Config` / `*Selectors` dataclass fields with no live references |
-| `code_rules_dead_dataclass_field.py` | Dataclass fields with no consuming references |
-| `code_rules_dead_module_constant.py` | `UPPER_SNAKE` constants in `*_constants.py` modules with no importers |
-| `code_rules_dead_split_branch.py` | A conditional whose falsy branch is unreachable because the tested value comes from a separator `str.split()`, which never returns an empty list |
-| `code_rules_docstrings.py` | Google-style docstrings; `Args:` section matches signature; fallback-branch coverage |
-| `code_rules_duplicate_body.py` | A function body copied from a sibling module, or a helper body inlined as a block inside a larger function in the same file |
-| `code_rules_imports_logging.py` | Imports at top of file; logging format-arg style; printf tokens in `str.format`-logger messages |
-| `code_rules_js_conventions.py` | Boolean-prefix naming and banned identifiers for JavaScript/TypeScript declarations and `@param {boolean}` JSDoc, scoped to changed lines |
-| `code_rules_magic_values.py` | No magic numbers or strings in production code bodies |
-| `code_rules_mock_completeness.py` | Mock calls that skip required arguments |
-| `code_rules_naming_collection.py` | Collection names must use `all_*` prefix |
-| `code_rules_optional_params.py` | No optional parameters where a required one would do |
-| `code_rules_orphan_css_class.py` | CSS class attributes in Python markup with no matching `.<class>` selector |
-| `code_rules_paired_test.py` | A public function omitted by a module's established paired test suite must get a behavioral test — checked on both the production-module write and the stem-matched test-file write |
-| `code_rules_path_utils.py` | Path utility helpers shared across check modules |
-| `code_rules_paths_syspath.py` | `sys.path.insert` must be guarded |
-| `code_rules_probe_chains.py` | Probe-chain detection logic |
-| `code_rules_probe_detection.py` | Probe pattern detection helpers |
-| `code_rules_probe_recording.py` | Probe recording utilities |
-| `code_rules_scope_binding.py` | Scope/binding analysis utilities |
-| `code_rules_shared.py` | Shared dataclasses and helpers used by multiple check modules |
-| `code_rules_string_magic.py` | Magic string detection with masking and f-string support; whitespace-only indentation literals in function bodies |
-| `code_rules_test_assertions.py` | Test assertion style rules |
-| `code_rules_test_layout.py` | Dead scaffolding in a test module: a private module constant read by no other line, and an unused parameter on a private test helper |
-| `code_rules_test_branching_except.py` | No bare or broad `except` in test branches |
-| `code_rules_test_isolation.py` | Tests must not rely on home-dir or temp-dir side effects |
-| `code_rules_type_escape.py` | No `Any` imports, `cast()`, or `# type: ignore` outside boundary files |
-| `code_rules_typeddict_stub.py` | TypedDict pairs (`_encode_*`/`_decode_*`) must both exist in the same module |
-| `code_rules_unused_imports.py` | Unused module-level imports |
-
-## Other standalone blockers
-
-| File | Event | What it blocks |
-|---|---|---|
-| `orchestrator_refresh_reschedule_gate.py` | PreToolUse (ScheduleWakeup/CronCreate) | `/orchestrator-refresh` re-arm when run status is not `active` |
-| `block_main_commit.py` | PreToolUse (Bash) | `git commit`/`git push` directly to `main` |
-| `bot_mention_comment_blocker.py` | PreToolUse (Write/Edit) | PR review comments that @-mention a bot |
-| `claude_md_orphan_file_blocker.py` | PreToolUse (Write/Edit/MultiEdit) | Per-directory `CLAUDE.md` table cells naming a bare filename absent from the directory subtree |
-| `code_review_pr_create_gate.py` | PreToolUse (Bash/MCP GitHub) | `gh pr create` or the MCP `create_pull_request` tool without a clean `xhigh` code-review stamp covering the branch surface |
-| `code_review_push_gate.py` | PreToolUse (Bash/PowerShell) | `git push` without a clean `low` code-review stamp covering the branch surface |
-| `code_review_stamp_directory_write_blocker.py` | PreToolUse (Bash/PowerShell/Write/Edit/MultiEdit) | Shell or file-tool writes into `~/.claude/code-review-stamps/`, and shell references to the stamp store module or its mint call, outside the sanctioned invoker |
-| `code_verifier_spawn_preflight_gate.py` | PreToolUse (Agent) | Spawning the `code-verifier` subagent when the branch has a merge conflict vs its base or a CODE_RULES violation on a working-tree-added line, or the CODE_RULES engine fails to load |
-| `convergence_gate_blocker.py` | PreToolUse (Bash) | Convergence workflow actions on a conflicting PR |
-| `conventional_pr_title_gate.py` | PreToolUse (Bash) | `gh pr create`/`gh pr edit` with a `--title` that is not a Conventional Commit, in a repo whose CI runs a semantic-pull-request title check |
-| `destructive_command_blocker.py` | PreToolUse (Bash/PowerShell) | Shell commands with destructive literals (`rm -rf`, `git reset --hard`, etc.) |
-| `docstring_rule_gate_count_blocker.py` | PreToolUse (Write/Edit/MultiEdit) | A stale spelled-out gate-validator count in `docstring-prose-matches-implementation.md` — the "N more gate validators" / "M gated slices" count drifting from the `check_docstring_*` validators the prose names |
-| `duplicate_rmtree_helper_blocker.py` | PreToolUse (Write/Edit) | A local re-definition of the Windows-safe rmtree helper trio (`_strip_read_only_and_retry`, `_force_remove_tree` / `force_rmtree`) in place of importing a shared helper |
-| `eli11_reply_enforcer.py` | Stop | Final replies breaking the `eli11-replies` shape — more than 6 bullet lines, more than 2 list lines over 20 words each, or multi-line instructions with no numbered step among the lead lines. Code fences, inline code, blockquotes, table rows, and link targets come off before the reply is judged. |
-| `env_var_table_code_drift_blocker.py` | PreToolUse (Write/Edit/MultiEdit) | A markdown env-var summary table row attributing an environment variable to a code file whose source never references that variable name |
-| `es_exe_path_rewriter.py` | PreToolUse | Rewrites paths referencing `.exe` under the Everything search path |
-| `fable_spawn_gate.py` | PreToolUse (Agent/Task) | An `Agent` or `Task` spawn whose prompt carries no `FABLE-SPAWN-AUTHORIZED` token and whose model field reads `fable` in any letter case — the bare alias, or a delimiter segment of a full model id, so `claude-fable-5` is denied too |
-| `gh_body_arg_blocker.py` | PreToolUse (Bash) | `gh` commands passing `--body`/`-b` directly (requires `--body-file` instead) |
-| `gh_pr_author_enforcer.py` | PreToolUse | Enforces PR author identity rules |
-| `gh_pr_author_restore.py` | PostToolUse | Restores PR author after a tool call |
-| `hedging_language_blocker.py` | Stop | Responses with hedging words (`likely`, `probably`, `appears to`); armed only when `CLAUDE_PROSE_STYLE_ENFORCEMENT` is on (default off) |
-| `hook_prose_detector_consistency.py` | PreToolUse (Write/Edit) | Hook docstrings/messages that claim a trigger the detector cannot fire on; armed only when `CLAUDE_PROSE_STYLE_ENFORCEMENT` is on (default off) |
-| `intent_only_ending_blocker.py` | Stop | Responses that end on a plan or intent without doing the work; armed only when `CLAUDE_PROSE_STYLE_ENFORCEMENT` is on (default off) |
-| `open_questions_in_plans_blocker.py` | PreToolUse (Write/Edit) | Plan documents with unresolved open questions |
-| `nas_ssh_binary_enforcer.py` | PreToolUse (Bash) | A bare `ssh`/`scp`/`sftp` command word targeting the NAS (Git Bash's MSYS ssh stalls on an interactive password prompt), or the full `System32/OpenSSH` binary to that host without `-o BatchMode=yes` |
-| `package_inventory_stale_blocker.py` | PreToolUse (Write) | A new production code file created in a directory whose `README.md`/`CLAUDE.md` inventory (or a parent skill's `SKILL.md` Layout table mapping the `scripts/` subdirectory) names two or more sibling files but no entry for the new file |
-| `pii_commit_command.py` | library | Token-aware git-commit detection reused by `pii_prevention_blocker.py` |
-| `pii_payload_scan.py` | library | Write/Edit and durable post-body PII evaluation reused by `pii_prevention_blocker.py` |
-| `pii_prevention_blocker.py` | PreToolUse (Write/Edit/MultiEdit/Bash/PowerShell/MCP GitHub) | Entry hook — content that carries high-confidence personal data or secrets (real emails, home-dir paths, private IPs, credential material) on write, durable GitHub posts, or staged commit paths; resolves the staged-commit repository from the command it gates (via `pii_prevention_blocker_parts`), not the session working directory |
-| `pii_scanner.py` | library | Pure text scanners shared by `pii_prevention_blocker.py` |
-| `piped_pytest_blocker.py` | PreToolUse (Bash) | A pytest run whose output feeds a pipe, where the pipeline reports the exit code of the command on the right |
-| `plain_language_blocker.py` | PreToolUse (Write/Edit/AskUserQuestion) | Heavy or jargon words in user-facing prose when `CLAUDE_PROSE_STYLE_ENFORCEMENT` is on (default off); AskUserQuestion lean-block structure stays always on |
-| `pr_converge_bugteam_enforcer.py` | PreToolUse | Enforces that bugteam runs in parallel with bugbot in pr-converge loops |
-| `pr_description_enforcer.py` | PreToolUse (Bash) | `gh pr create`/`edit`/`comment` bodies that fail the Anthropic claude-code style audit, proof-shaped `gh pr comment` bodies missing proof-of-work parts, and `gh pr ready` while the PR carries no passing proof comment |
-| `precommit_code_rules_gate.py` | PreToolUse (Bash) | Staged changes that fail the CODE_RULES gate at commit time |
-| `pytest_testpaths_orphan_blocker.py` | PreToolUse (Write/Edit/MultiEdit) | New `test_*.py` files created under a directory absent from a package's explicit pytest `testpaths` allowlist |
-| `question_to_user_enforcer.py` | Stop | User-directed questions not routed through `AskUserQuestion` |
-| `reviewer_spawn_gate.py` | PreToolUse (Bash) | A sentinel-marked autoconverge reviewer-spawn command (Copilot review request, Bugbot rerun comment) run while `reviewer_availability.py` reports that reviewer down or out of quota |
-| `send_user_file_open_locally_blocker.py` | PreToolUse (SendUserFile) | A desk-side file attach (`SendUserFile` with `status` not `proactive`); points to opening the file locally via `Show-Asset.ps1` |
-| `sensitive_file_protector.py` | PreToolUse (Write/Edit) | Writes to sensitive credential or config files |
-| `session_edit_stage_gate.py` | PreToolUse (Bash) | A `git commit` that would drop files edited this session because they are tracked but left unstaged |
-| `session_handoff_blocker.py` | Stop | Responses suggesting a new session mid-task |
-| `shell_substitution_blocker.py` | PreToolUse (Bash) | A command carrying `$(...)`, a live backtick, or `<(...)`/`>(...)` process substitution, which the allowlist matcher cannot descend into |
-| `stale_comment_reference_blocker.py` | PreToolUse (Edit) | An Edit that rewrites a Python code line while keeping the standalone comment directly above it, when that comment names an identifier the rewrite removes from the line |
-| `state_description_blocker.py` | PreToolUse (Write/Edit) | Historical/comparative language in documentation; armed only when `CLAUDE_PROSE_STYLE_ENFORCEMENT` is on (default off) |
-| `subprocess_budget_completeness.py` | PreToolUse | Subprocess calls missing required budget arguments |
-| `tdd_enforcer.py` | PreToolUse (Write/Edit) | Production code written without a matching failing test |
-| `unscoped_search_blocker.py` | PreToolUse (Bash/PowerShell) | A `find` or recursive listing that walks from the filesystem root, a drive root, bare home, or a network share root |
-| `verdict_directory_write_blocker.py` | PreToolUse (Bash/PowerShell) | Shell writes into `~/.claude/verification/` |
-| `verified_commit_gate.py` | PreToolUse (Bash/PowerShell) | `git commit`/`git push` without a passing verifier verdict |
-| `verified_commit_message_accuracy_blocker.py` | PreToolUse | Commit messages that misstate what the diff has |
-| `verifier_verdict_minter.py` | SubagentStop | Mints a passing verdict file when a `code-verifier` agent finishes cleanly |
-| `volatile_path_in_post_blocker.py` | PreToolUse (Bash/MCP GitHub) | `gh` post commands and GitHub MCP post tools whose body references a volatile path (job scratch dir, worktree, or system temp) that outlives the durable post |
-| `windows_rmtree_blocker.py` | PreToolUse (Write/Edit) | `shutil.rmtree` with `ignore_errors=True` on Windows |
-| `workflow_substitution_slot_blocker.py` | PreToolUse (Write/Edit) | Workflow templates with bare per-iteration tokens missing angle-bracket slots |
-| `write_existing_file_blocker.py` | PreToolUse (Write) | Write to a path where a file already exists |
-
-## Supporting modules
-
-| File | Role |
-|---|---|
-| `_gh_body_arg_utils.py` | Parsing helpers for `gh_body_arg_blocker.py` |
-| `code_review_enforcement_config_bootstrap.py` | Binds `config.code_review_enforcement_constants` to the sibling `config/` file by explicit location, so the code-review gate family resolves its constants regardless of a foreign `config` package's `sys.path` order |
-| `code_review_gate_deny.py` | Shared deny scaffold for the push and PR-create code-review gates: the `hookSpecificOutput` deny-payload builder and the log-and-emit helper, so both gates share one deny shape |
-| `code_review_stamp_store.py` | Reads and writes the per-work-tree code-review stamp files under `~/.claude/code-review-stamps/`, and decides whether a clean stamp at the needed effort covers the live branch surface |
-| `pr_description_body_audit.py` | Body audit logic for `pr_description_enforcer.py` |
-| `pr_description_command_parser.py` | `gh` command parsing for `pr_description_enforcer.py` |
-| `pr_description_pr_number.py` | PR number extraction logic |
-| `pr_description_proof_of_work.py` | Proof-of-work comment audit and `gh pr ready` gate logic for `pr_description_enforcer.py` |
-| `pr_description_readability.py` | Readability checks on PR description bodies |
-| `verification_verdict_store.py` | Reads and writes verdict files under `~/.claude/verification/` |
-| `verified_commit_config_bootstrap.py` | Binds `config.verified_commit_constants` to the sibling `config/` file by explicit location, so the gate family resolves its constants regardless of a foreign `config` package's `sys.path` order |
-
-## Conventions
-
-- Tests live beside each hook as `test_<hookname>.py` or `test_<hookname>_<suffix>.py`. Run with `python -m pytest <test_file>`.
-- Tunable constants live in `hooks_constants/<hook_name>_constants.py`; the verified-commit family uses `blocking/config/verified_commit_constants.py`.
+@AGENTS.md

package/hooks/blocking/claude_md_orphan_file_blocker_parts/AGENTS.md

@@ -0,0 +1,28 @@
+# claude_md_orphan_file_blocker_parts
+
+The concern modules `claude_md_orphan_file_blocker.py` wires together to block a
+per-directory `CLAUDE.md` that names a file absent from its subtree. The entry
+hook imports them and re-exports their surface for the test suite.
+
+## Modules
+
+| File | Purpose |
+|---|---|
+| `references.py` | Extracts the bare filenames a table cell names and the scripts a fenced run command invokes, honoring the `../` relative-path exemptions |
+| `subtree_scan.py` | Resolves the scan root and reports which referenced filenames are absent from it, with a bounded walk plus a direct probe fallback |
+| `scan_plan.py` | Builds the Write/Edit/MultiEdit scan plan and collects the orphan filenames the change introduces, excluding pre-existing orphans |
+| `decision.py` | Builds the deny payload listing the missing files and closing with the retry hint, and emits the decision JSON |
+| `__init__.py` | Package marker |
+
+## Subdirectories
+
+| Entry | Description |
+|---|---|
+| `config/` | The region-join newline, the retry hint the deny reason closes with, and the missing-name join separator (`orphan_blocker_constants.py`) |
+| `tests/` | pytest suite with one test module per module above |
+
+## Running tests
+
+```bash
+python -m pytest packages/claude-dev-env/hooks/blocking/claude_md_orphan_file_blocker_parts/tests/
+```

package/hooks/blocking/claude_md_orphan_file_blocker_parts/CLAUDE.md

@@ -1,28 +1 @@
-# claude_md_orphan_file_blocker_parts
-
-The concern modules `claude_md_orphan_file_blocker.py` wires together to block a
-per-directory `CLAUDE.md` that names a file absent from its subtree. The entry
-hook imports them and re-exports their surface for the test suite.
-
-## Modules
-
-| File | Purpose |
-|---|---|
-| `references.py` | Extracts the bare filenames a table cell names and the scripts a fenced run command invokes, honoring the `../` relative-path exemptions |
-| `subtree_scan.py` | Resolves the scan root and reports which referenced filenames are absent from it, with a bounded walk plus a direct probe fallback |
-| `scan_plan.py` | Builds the Write/Edit/MultiEdit scan plan and collects the orphan filenames the change introduces, excluding pre-existing orphans |
-| `decision.py` | Builds the deny payload listing the missing files and closing with the retry hint, and emits the decision JSON |
-| `__init__.py` | Package marker |
-
-## Subdirectories
-
-| Entry | Description |
-|---|---|
-| `config/` | The region-join newline, the retry hint the deny reason closes with, and the missing-name join separator (`orphan_blocker_constants.py`) |
-| `tests/` | pytest suite with one test module per module above |
-
-## Running tests
-
-```bash
-python -m pytest packages/claude-dev-env/hooks/blocking/claude_md_orphan_file_blocker_parts/tests/
-```
+@AGENTS.md

package/hooks/blocking/code_rules_banned_identifiers.py

@@ -390,7 +390,7 @@ def check_banned_noun_word_boundary(
 def check_banned_prefixes(content: str, file_path: str) -> list[str]:
     """Flag function and method names using generic banned prefixes.
 
-    Per CODE_RULES.md / AGENTS.md Naming, function names use specific verbs.
+    Per CODE_RULES.md Naming, function names use specific verbs.
     Generic prefixes ``handle_``, ``process_``, ``manage_``, ``do_`` are
     placeholders that hide the actual responsibility and are flagged so the
     author renames the function to a specific verb.

package/hooks/blocking/code_rules_dead_module_constant.py

@@ -29,13 +29,20 @@ The scan is deliberately conservative to keep false positives near zero:
   exported constant live.
 - When the package-tree scan leaves a constant unreferenced, the scan widens to
   the repository root (the nearest ``.git`` ancestor). The widened pass counts a
-  sibling-tree reference only when a module imports the name through a
-  ``from <module> import`` whose final dotted segment equals the written
-  module's filename stem, so a genuine cross-tree consumer of this constants
-  module keeps the constant live while a same-named constant exported by an
-  unrelated module never masks a dead one. The widened pass reads a repository
-  file only to test whether its text names the written module's filename stem;
-  a file that never mentions the stem cannot carry such an import, so it is
+  sibling-tree reference in two shapes. The first is an import of the name
+  through a ``from <module> import`` whose final dotted segment equals the
+  written module's filename stem. The second is an attribute read on a binding
+  of the written module itself: a consumer that writes
+  ``import pkg.config.constants``, the same with an alias,
+  ``from pkg.config import constants``, or the same with an alias, and then
+  reads each constant as an attribute on that binding (``alias.NAME``,
+  ``pkg.config.constants.NAME``), keeps every name it reads that way live. Both
+  shapes are bound to the written module's stem, so a genuine cross-tree
+  consumer of this constants module keeps the constant live while a same-named
+  constant exported by an unrelated module never masks a dead one. The widened
+  pass reads a repository file only to test whether its text names the written
+  module's filename stem; neither shape can appear in a file that never spells
+  the stem, so such a file is
   skipped without spending scan-cap budget, keeping the widened pass bounded to
   the handful of candidate importer files even in a large repository. A module
   outside any repository is
@@ -65,6 +72,7 @@ if _blocking_directory not in sys.path:
 if _hooks_directory not in sys.path:
     sys.path.insert(0, _hooks_directory)
 
+from code_rules_probe_chains import _dotted_attribute_chain  # noqa: E402
 from code_rules_shared import (  # noqa: E402
     is_migration_file,
     is_test_file,
@@ -268,13 +276,116 @@ def _module_final_segment(module_path: str | None) -> str:
     return module_path.rsplit(".", 1)[-1]
 
 
-def _qualified_import_member_names(source: str, module_stem: str) -> set[str]:
-    """Return names imported from a module whose filename stem is ``module_stem``.
+def _stem_import_member_names(import_node: ast.ImportFrom, module_stem: str) -> set[str]:
+    """Return the member names a stem-matched ``from ... import`` brings in.
 
-    A cross-package consumer of an exported constant imports it through an
-    explicit ``from <module> import NAME`` whose module path ends in the defining
-    module's filename stem. Collecting only those member names binds a
-    widened-scan reference to the module that actually defines the constant, so a
+    ::
+
+        from pkg.config.constants import NAME  ->  "NAME"
+        from pkg.config.other import NAME      ->  nothing (stem mismatch)
+
+    Args:
+        import_node: A ``from ... import`` statement node.
+        module_stem: The filename stem of the constants module being judged.
+
+    Returns:
+        The imported member names when the module path's final dotted segment
+        equals ``module_stem``, empty otherwise.
+    """
+    if _module_final_segment(import_node.module) != module_stem:
+        return set()
+    return {each_alias.name for each_alias in import_node.names}
+
+
+def _import_module_bindings(all_import_aliases: list[ast.alias], module_stem: str) -> set[str]:
+    """Return the names an import's aliases bind to the constants module object.
+
+    ::
+
+        import pkg.config.constants        ->  "pkg.config.constants"
+        import pkg.config.constants as sg  ->  "sg"
+        from pkg.config import constants   ->  "constants"
+        from . import constants as sg      ->  "sg"
+        import pkg.config.other            ->  nothing (stem mismatch)
+
+    A plain ``import`` names the module by its dotted path, so the final
+    segment is matched against the stem. A ``from ... import`` alias name is a
+    single identifier, which the same final-segment match covers unchanged.
+
+    Args:
+        all_import_aliases: The ``names`` list of an ``Import`` or
+            ``ImportFrom`` node.
+        module_stem: The filename stem of the constants module being judged.
+
+    Returns:
+        The dotted paths and aliases through which the module object is
+        reachable.
+    """
+    binding_names: set[str] = set()
+    for each_alias in all_import_aliases:
+        if _module_final_segment(each_alias.name) != module_stem:
+            continue
+        binding_names.add(each_alias.asname or each_alias.name)
+    return binding_names
+
+
+def _collect_widened_scan_facts(
+    tree: ast.Module, module_stem: str
+) -> tuple[set[str], set[str], list[ast.Attribute]]:
+    """Collect a candidate module's import and attribute facts in one walk.
+
+    Args:
+        tree: The parsed candidate module.
+        module_stem: The filename stem of the constants module being judged.
+
+    Returns:
+        The member names imported through a stem-matched ``from ... import``,
+        the names bound to the constants module object itself, and every
+        attribute node in the module.
+    """
+    member_names: set[str] = set()
+    binding_names: set[str] = set()
+    all_attribute_nodes: list[ast.Attribute] = []
+    for each_node in ast.walk(tree):
+        if isinstance(each_node, ast.ImportFrom):
+            member_names |= _stem_import_member_names(each_node, module_stem)
+        if isinstance(each_node, (ast.Import, ast.ImportFrom)):
+            binding_names |= _import_module_bindings(each_node.names, module_stem)
+        if isinstance(each_node, ast.Attribute):
+            all_attribute_nodes.append(each_node)
+    return member_names, binding_names, all_attribute_nodes
+
+
+def _attribute_read_names(
+    all_attribute_nodes: list[ast.Attribute], all_binding_names: set[str]
+) -> set[str]:
+    """Return the constant names read as attributes on a module-object binding.
+
+    The expression an attribute is read on is spelled back to its dotted source
+    form and matched against the bindings, so an alias read (``sg.NAME``) and a
+    full dotted path (``pkg.config.constants.NAME``) both resolve, while a read
+    on a binding of some other module counts for nothing.
+
+    Args:
+        all_attribute_nodes: Every attribute node in the candidate module.
+        all_binding_names: The names bound to the constants module object.
+
+    Returns:
+        The attribute names read on a binding of the constants module.
+    """
+    if not all_binding_names:
+        return set()
+    return {
+        each_attribute.attr
+        for each_attribute in all_attribute_nodes
+        if _dotted_attribute_chain(each_attribute.value) in all_binding_names
+    }
+
+
+def _widened_scan_reference_names(source: str, module_stem: str) -> set[str]:
+    """Return the names a repository-wide candidate contributes, parsing it once.
+
+    Both counted shapes are bound to the written module's filename stem, so a
     same-named constant exported by an unrelated module never masks a dead one.
 
     Args:
@@ -282,22 +393,18 @@ def _qualified_import_member_names(source: str, module_stem: str) -> set[str]:
         module_stem: The filename stem of the constants module being judged.
 
     Returns:
-        The member names imported from a module whose final dotted segment equals
-        ``module_stem``. A module that fails to parse contributes no names.
+        The members imported through a stem-matched ``from <module> import``,
+        plus the constant names read as attributes on an imported binding of the
+        constants module. A module that fails to parse contributes no names.
     """
     try:
         tree = ast.parse(source)
     except SyntaxError:
         return set()
-    member_names: set[str] = set()
-    for each_node in ast.walk(tree):
-        if not isinstance(each_node, ast.ImportFrom):
-            continue
-        if _module_final_segment(each_node.module) != module_stem:
-            continue
-        for each_alias in each_node.names:
-            member_names.add(each_alias.name)
-    return member_names
+    member_names, binding_names, all_attribute_nodes = _collect_widened_scan_facts(
+        tree, module_stem
+    )
+    return member_names | _attribute_read_names(all_attribute_nodes, binding_names)
 
 
 def _scan_root_for_constants_module(file_path: str) -> Path:
@@ -350,11 +457,13 @@ def _read_candidate_source(file_path: Path, required_substring: str | None) -> s
         required_substring = None                 -> read and keep every file
         required_substring = the module stem      -> keep only files naming it
             from pkg.foo_constants import BAR  ->  names the stem  ->  candidate
+            from pkg import foo_constants as c ->  names the stem  ->  candidate
             def unrelated() -> int: ...        ->  no stem mention ->  skipped
 
-    The widened repository pass looks only for a ``from <module> import`` whose
-    final dotted segment equals the constants module's filename stem, and such an
-    import always spells that stem in the file's text. A file whose text never
+    The widened repository pass looks only for an import bound to the constants
+    module's filename stem — a ``from <module> import`` whose final dotted segment
+    equals the stem, or an import of the module object itself — and every such
+    import spells that stem in the file's text. A file whose text never
     mentions the stem cannot carry the import, so returning None for it lets the
     caller skip the file without spending scan-cap budget, which keeps the widened
     pass bounded to the candidate importer files even under a large repository.
@@ -422,7 +531,9 @@ def _collect_names_under_root(
             in before the walk begins.
         extract_names: Maps one module's source text to the set of names it
             contributes — the generous reference collector for the package-tree
-            pass, the stem-bound import collector for the widened pass.
+            pass, and for the widened pass the stem-bound collector that counts
+            both a stem-matched from-import and an attribute read on a binding
+            of the written module.
         already_scanned_count: The parsed-file count accumulated by a prior
             pass, so the parse cap bounds the combined work of the
             package-tree and widened passes.
@@ -552,12 +663,13 @@ def check_dead_module_constants(
     are governed by the use-count rule instead. A constant is dead when its name
     appears in no ``.py`` module under the enclosing package tree — not imported,
     not read, not listed in another module's ``__all__`` literal, not named in a
-    string annotation — and, in the repository-wide scan the check widens to when
-    the package-tree scan leaves the constant unreferenced, no module imports the
-    name from a ``from <module> import`` whose final dotted segment equals this
-    module's filename stem. Binding the widened scan to the stem keeps a genuine
-    cross-tree consumer counting while a same-named constant exported by an
-    unrelated module never masks a dead one. A module declaring ``__all__``
+    string annotation. When that leaves a constant unreferenced, the scan widens
+    to the repository, where two shapes count: a ``from <module> import`` whose
+    final dotted segment equals this module's filename stem, and an attribute
+    read on a binding of this module (``import pkg.config.constants as alias``
+    then the alias followed by the constant name). Binding both to the stem
+    keeps a same-named constant in an unrelated module from masking a dead one.
+    A module declaring ``__all__``
     narrows the check to the constants its ``__all__`` list names: each must be
     imported or read by another module, and the module's own ``__all__`` entry
     never counts as that consumer, so an exported constant no module consumes is
@@ -616,14 +728,14 @@ def check_dead_module_constants(
     if has_unreferenced_constant:
         repository_root = _repository_root_for(written_path)
         if repository_root is not None and repository_root != scan_root:
-            collect_qualified_imports = partial(
-                _qualified_import_member_names, module_stem=written_path.stem
+            collect_widened_scan_names = partial(
+                _widened_scan_reference_names, module_stem=written_path.stem
             )
             widened_names, _widened_count, widened_cap_was_hit = _collect_names_under_root(
                 repository_root,
                 written_path,
                 set(),
-                collect_qualified_imports,
+                collect_widened_scan_names,
                 already_scanned_count=scanned_file_count,
                 excluded_subtree=scan_root,
                 required_substring=written_path.stem,