claude-dev-env 1.67.2 → 1.69.0

package/hooks/blocking/test_code_rules_enforcer_docstring_fallback_branch.py

@@ -0,0 +1,398 @@
+"""Tests for check_docstring_fallback_branch_coverage — O6 fallback-branch drift.
+
+A function whose summary scopes a fallback to one condition while the body
+routes to that same fallback call from two or more distinct early-return guards
+hides the second condition from the reader. This is the deterministic slice of
+Category O6 (docstring prose vs implementation drift).
+"""
+
+from __future__ import annotations
+
+import importlib.util
+from pathlib import Path
+from types import ModuleType
+
+
+def _load_enforcer_module() -> ModuleType:
+    module_path = Path(__file__).parent / "code_rules_enforcer.py"
+    spec = importlib.util.spec_from_file_location("code_rules_enforcer", module_path)
+    assert spec is not None
+    assert spec.loader is not None
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module
+
+
+code_rules_enforcer = _load_enforcer_module()
+
+
+def check_docstring_fallback_branch_coverage(content: str, file_path: str) -> list[str]:
+    return code_rules_enforcer.check_docstring_fallback_branch_coverage(content, file_path)
+
+
+def validate_content(content: str, file_path: str, old_content: str) -> list[str]:
+    return code_rules_enforcer.validate_content(content, file_path, old_content)
+
+
+PRODUCTION_FILE_PATH = "/project/src/human_actions.py"
+TEST_FILE_PATH = "/project/src/test_human_actions.py"
+HOOK_INFRASTRUCTURE_PATH = "/home/user/.claude/hooks/blocking/example.py"
+
+
+def _drifted_scroll_method() -> str:
+    return (
+        "class HumanActions:\n"
+        "    async def _scroll_once_toward_target(\n"
+        "        self, all_container_screen_bounds: object\n"
+        "    ) -> None:\n"
+        '        """Drive one scrollbar pass, falling back to the keyboard when'
+        ' the bar has no geometry."""\n'
+        "        if all_container_screen_bounds is None:\n"
+        "            await self._activate_then_press_right_arrow(None)\n"
+        "            return\n"
+        "        if random.random() < wheel_scroll_config.keyboard_scroll_fallback_probability:\n"
+        "            await self._activate_then_press_right_arrow(all_container_screen_bounds)\n"
+        "            return\n"
+        "        await self._drive_scrollbar_gesture(all_container_screen_bounds)\n"
+    )
+
+
+def _enumerated_scroll_method() -> str:
+    return (
+        "class HumanActions:\n"
+        "    async def _scroll_once_toward_target(\n"
+        "        self, all_container_screen_bounds: object\n"
+        "    ) -> None:\n"
+        '        """Drive one scrollbar pass.\n'
+        "\n"
+        "        Route to the Right-Arrow keyboard burst either when the bar has\n"
+        "        no geometry or, on a random keyboard_scroll_fallback_probability\n"
+        "        fraction of passes, when geometry is available.\n"
+        '        """\n'
+        "        if all_container_screen_bounds is None:\n"
+        "            await self._activate_then_press_right_arrow(None)\n"
+        "            return\n"
+        "        if random.random() < wheel_scroll_config.keyboard_scroll_fallback_probability:\n"
+        "            await self._activate_then_press_right_arrow(all_container_screen_bounds)\n"
+        "            return\n"
+        "        await self._drive_scrollbar_gesture(all_container_screen_bounds)\n"
+    )
+
+
+def test_should_flag_two_branches_routing_to_one_scoped_fallback() -> None:
+    issues = check_docstring_fallback_branch_coverage(
+        _drifted_scroll_method(), PRODUCTION_FILE_PATH
+    )
+    assert any("_activate_then_press_right_arrow" in each for each in issues), (
+        f"Expected the second fallback route to be flagged, got: {issues!r}"
+    )
+    assert len(issues) == 1
+
+
+def test_should_report_the_route_count_in_the_message() -> None:
+    issues = check_docstring_fallback_branch_coverage(
+        _drifted_scroll_method(), PRODUCTION_FILE_PATH
+    )
+    assert any("2 distinct branches" in each for each in issues), (
+        f"Expected the branch count in the message, got: {issues!r}"
+    )
+
+
+def test_should_not_flag_when_both_conditions_are_enumerated() -> None:
+    issues = check_docstring_fallback_branch_coverage(
+        _enumerated_scroll_method(), PRODUCTION_FILE_PATH
+    )
+    assert issues == [], (
+        f"A docstring that enumerates both routes must not be flagged, got: {issues!r}"
+    )
+
+
+def test_should_not_flag_single_branch_fallback() -> None:
+    source = (
+        "def render(view: object) -> str:\n"
+        '    """Render the view, falling back to the empty string when absent."""\n'
+        "    if view is None:\n"
+        "        return ''\n"
+        "    return view.body\n"
+    )
+    issues = check_docstring_fallback_branch_coverage(source, PRODUCTION_FILE_PATH)
+    assert issues == [], f"One fallback route under one named condition is correct, got: {issues!r}"
+
+
+def test_should_not_flag_two_branches_to_different_callees() -> None:
+    source = (
+        "def dispatch(event: object) -> None:\n"
+        '    """Dispatch the event, falling back to the logger when unroutable."""\n'
+        "    if event is None:\n"
+        "        log_warning('empty')\n"
+        "        return\n"
+        "    if event.is_stale:\n"
+        "        drop_event(event)\n"
+        "        return\n"
+        "    route_event(event)\n"
+    )
+    issues = check_docstring_fallback_branch_coverage(source, PRODUCTION_FILE_PATH)
+    assert issues == [], (
+        f"Distinct callees per branch are not a shared-fallback drift, got: {issues!r}"
+    )
+
+
+def test_should_not_flag_when_docstring_has_no_scope_phrase() -> None:
+    source = (
+        "def select(target: object) -> None:\n"
+        '    """Pick the first matching candidate from the registry."""\n'
+        "    if target is None:\n"
+        "        await _press(None)\n"
+        "        return\n"
+        "    if target.is_idle:\n"
+        "        await _press(target)\n"
+        "        return\n"
+        "    await _drive(target)\n"
+    )
+    issues = check_docstring_fallback_branch_coverage(source, PRODUCTION_FILE_PATH)
+    assert issues == [], (
+        f"No exclusive-scope phrase means no fallback claim to check, got: {issues!r}"
+    )
+
+
+def test_should_not_flag_when_scope_phrase_is_a_substring_of_another_word() -> None:
+    source = (
+        "def refresh(cache: object) -> None:\n"
+        '    """Rebuild the cache; commonly when idle it reuses the warm copy."""\n'
+        "    if cache is None:\n"
+        "        rebuild_cache(None)\n"
+        "        return\n"
+        "    if cache.is_cold:\n"
+        "        rebuild_cache(cache)\n"
+        "        return\n"
+        "    serve_cache(cache)\n"
+    )
+    issues = check_docstring_fallback_branch_coverage(source, PRODUCTION_FILE_PATH)
+    assert issues == [], (
+        "'commonly when' must not match the 'only when' scope phrase as a bare "
+        f"substring, got: {issues!r}"
+    )
+
+
+def test_should_still_flag_word_boundary_scope_phrase() -> None:
+    source = (
+        "def refresh(cache: object) -> None:\n"
+        '    """Rebuild the cache only when it is invalid."""\n'
+        "    if cache is None:\n"
+        "        rebuild_cache(None)\n"
+        "        return\n"
+        "    if cache.is_cold:\n"
+        "        rebuild_cache(cache)\n"
+        "        return\n"
+        "    serve_cache(cache)\n"
+    )
+    issues = check_docstring_fallback_branch_coverage(source, PRODUCTION_FILE_PATH)
+    assert any("rebuild_cache" in each for each in issues), (
+        f"A genuine 'only when' scope phrase must still be flagged, got: {issues!r}"
+    )
+
+
+def test_should_not_flag_when_summary_enumerates_both_conditions_inline() -> None:
+    source = (
+        "def scroll(bar: object) -> None:\n"
+        '    """Drive a scrollbar pass, falling back to the keyboard when the bar'
+        ' lacks geometry or on a random fraction of passes."""\n'
+        "    if bar is None:\n"
+        "        _keyboard(None)\n"
+        "        return\n"
+        "    if bar.is_random:\n"
+        "        _keyboard(bar)\n"
+        "        return\n"
+        "    _drive(bar)\n"
+    )
+    issues = check_docstring_fallback_branch_coverage(source, PRODUCTION_FILE_PATH)
+    assert issues == [], (
+        "A summary that enumerates both fallback conditions inline with 'or' is not "
+        f"a single-condition scope and must not be flagged, got: {issues!r}"
+    )
+
+
+def test_should_still_flag_single_condition_fallback_with_two_routes() -> None:
+    source = (
+        "def scroll(bar: object) -> None:\n"
+        '    """Drive a scrollbar pass, falling back to the keyboard when the bar'
+        ' lacks geometry."""\n'
+        "    if bar is None:\n"
+        "        _keyboard(None)\n"
+        "        return\n"
+        "    if bar.is_random:\n"
+        "        _keyboard(bar)\n"
+        "        return\n"
+        "    _drive(bar)\n"
+    )
+    issues = check_docstring_fallback_branch_coverage(source, PRODUCTION_FILE_PATH)
+    assert any("_keyboard" in each for each in issues), (
+        "A summary scoping the fallback to one named condition while two routes reach "
+        f"it must still be flagged, got: {issues!r}"
+    )
+
+
+def test_should_not_flag_when_scope_phrase_is_a_left_anchored_prefix() -> None:
+    source = (
+        "def forward(packet: object) -> None:\n"
+        '    """Forward the packet; falls back toward the default sink when both'
+        ' checks miss."""\n'
+        "    if packet is None:\n"
+        "        send_to_sink(None)\n"
+        "        return\n"
+        "    if packet.is_stale:\n"
+        "        send_to_sink(packet)\n"
+        "        return\n"
+        "    deliver(packet)\n"
+    )
+    issues = check_docstring_fallback_branch_coverage(source, PRODUCTION_FILE_PATH)
+    assert issues == [], (
+        "'falls back toward' must not match the 'falls back to' scope phrase as a "
+        f"left-anchored prefix, got: {issues!r}"
+    )
+
+
+def test_should_not_flag_only_whenever_left_anchored_prefix() -> None:
+    source = (
+        "def refresh(cache: object) -> None:\n"
+        '    """Rebuild the cache only whenever it is invalid or stale."""\n'
+        "    if cache is None:\n"
+        "        rebuild_cache(None)\n"
+        "        return\n"
+        "    if cache.is_cold:\n"
+        "        rebuild_cache(cache)\n"
+        "        return\n"
+        "    serve_cache(cache)\n"
+    )
+    issues = check_docstring_fallback_branch_coverage(source, PRODUCTION_FILE_PATH)
+    assert issues == [], (
+        "'only whenever' must not match the 'only when' scope phrase as a "
+        f"left-anchored prefix, got: {issues!r}"
+    )
+
+
+def test_should_not_flag_two_branches_to_same_method_on_distinct_indexed_receivers() -> None:
+    source = (
+        "class Pool:\n"
+        "    def shutdown(self, signal: object) -> None:\n"
+        '        """Close resources only when a shutdown signal arrives."""\n'
+        "        if signal is None:\n"
+        "            self.pool[0].close(signal)\n"
+        "            return\n"
+        "        if signal.is_secondary:\n"
+        "            self.pool[1].close(signal)\n"
+        "            return\n"
+        "        self.pool[2].drain(signal)\n"
+    )
+    issues = check_docstring_fallback_branch_coverage(source, PRODUCTION_FILE_PATH)
+    assert issues == [], (
+        "Distinct indexed receivers calling the same method name are different "
+        f"fallbacks, got: {issues!r}"
+    )
+
+
+def test_should_not_flag_two_branches_to_same_named_method_on_distinct_receivers() -> None:
+    source = (
+        "class Closer:\n"
+        "    def shutdown(self, signal: object) -> None:\n"
+        '        """Close resources only when a shutdown signal arrives."""\n'
+        "        if signal is None:\n"
+        "            self.primary.close(signal)\n"
+        "            return\n"
+        "        if signal.is_secondary:\n"
+        "            self.secondary.close(signal)\n"
+        "            return\n"
+        "        self.tertiary.close(signal)\n"
+    )
+    issues = check_docstring_fallback_branch_coverage(source, PRODUCTION_FILE_PATH)
+    assert issues == [], (
+        "Distinct receivers calling the same method name are different fallbacks, "
+        f"got: {issues!r}"
+    )
+
+
+def test_should_flag_two_branches_to_same_method_on_one_receiver() -> None:
+    source = (
+        "class Closer:\n"
+        "    def shutdown(self, signal: object) -> None:\n"
+        '        """Close resources only when a shutdown signal arrives."""\n'
+        "        if signal is None:\n"
+        "            self.primary.close(signal)\n"
+        "            return\n"
+        "        if signal.is_secondary:\n"
+        "            self.primary.close(signal)\n"
+        "            return\n"
+        "        self.primary.drain(signal)\n"
+    )
+    issues = check_docstring_fallback_branch_coverage(source, PRODUCTION_FILE_PATH)
+    assert any("self.primary.close" in each for each in issues), (
+        f"Two routes to the same receiver.method must be flagged, got: {issues!r}"
+    )
+
+
+def test_should_flag_multi_statement_guard_with_one_call_before_return() -> None:
+    source = (
+        "def select(target: object) -> None:\n"
+        '    """Pick a candidate, falling back to the press action when idle."""\n'
+        "    if target is None:\n"
+        "        attempt = 1\n"
+        "        _press(None)\n"
+        "        return\n"
+        "    if target.is_idle:\n"
+        "        attempt = 1\n"
+        "        _press(target)\n"
+        "        return\n"
+        "    _drive(target)\n"
+    )
+    issues = check_docstring_fallback_branch_coverage(source, PRODUCTION_FILE_PATH)
+    assert any("_press" in each for each in issues), (
+        "A guard with a non-call statement before its single call still routes "
+        f"to that call, got: {issues!r}"
+    )
+
+
+def test_should_not_flag_guard_with_a_second_call_expression() -> None:
+    source = (
+        "def select(target: object) -> None:\n"
+        '    """Pick a candidate, falling back to the press action when idle."""\n'
+        "    if target is None:\n"
+        "        _press(None)\n"
+        "        _press(None)\n"
+        "        return\n"
+        "    if target.is_idle:\n"
+        "        _press(target)\n"
+        "        _press(target)\n"
+        "        return\n"
+        "    _drive(target)\n"
+    )
+    issues = check_docstring_fallback_branch_coverage(source, PRODUCTION_FILE_PATH)
+    assert issues == [], (
+        f"A second call expression disqualifies the block as a route, got: {issues!r}"
+    )
+
+
+def test_should_skip_test_file() -> None:
+    issues = check_docstring_fallback_branch_coverage(_drifted_scroll_method(), TEST_FILE_PATH)
+    assert issues == [], f"Test files exempt, got: {issues!r}"
+
+
+def test_should_skip_hook_infrastructure() -> None:
+    issues = check_docstring_fallback_branch_coverage(
+        _drifted_scroll_method(), HOOK_INFRASTRUCTURE_PATH
+    )
+    assert issues == [], f"Hook infrastructure exempt, got: {issues!r}"
+
+
+def test_should_handle_syntax_error_gracefully() -> None:
+    issues = check_docstring_fallback_branch_coverage("def fetch(\n", PRODUCTION_FILE_PATH)
+    assert issues == [], f"Syntax error must yield no issues, got: {issues!r}"
+
+
+def test_validate_content_surfaces_fallback_branch_drift() -> None:
+    issues = validate_content(_drifted_scroll_method(), PRODUCTION_FILE_PATH, old_content="")
+    matching_issues = [
+        each for each in issues if "_activate_then_press_right_arrow" in each and "O6" in each
+    ]
+    assert matching_issues, (
+        f"Expected validate_content to surface the O6 fallback-branch drift, got: {issues!r}"
+    )

package/hooks/blocking/test_code_rules_enforcer_file_global_constants.py

@@ -32,6 +32,7 @@ TYPESCRIPT_FILE_PATH = "packages/claude-dev-env/hooks/blocking/example.ts"
 TOP_LEVEL_CONFIG_FILE_PATH = "config/timing.py"
 NESTED_CONFIG_FILE_PATH = "packages/claude-dev-env/hooks/config/example_constants.py"
 BACKSLASH_CONFIG_FILE_PATH = "packages\\claude-dev-env\\hooks\\config\\example_constants.py"
+WORKFLOW_REGISTRY_FILE_PATH = "packages/claude-dev-env/hooks/blocking/workflow/app_info/states.py"
 
 
 def test_should_flag_constant_used_by_only_one_function() -> None:
@@ -114,6 +115,14 @@ def test_should_exempt_test_files() -> None:
     assert issues == [], f"Expected test file exemption, got: {issues}"
 
 
+def test_should_exempt_workflow_registry_files() -> None:
+    source = "UPPER = 1\n\ndef lonely_caller():\n    return UPPER\n"
+    issues = code_rules_enforcer.check_file_global_constants_use_count(
+        source, WORKFLOW_REGISTRY_FILE_PATH
+    )
+    assert issues == [], f"Expected workflow-registry file exemption, got: {issues}"
+
+
 def test_should_flag_constant_used_only_in_decorator_of_one_function() -> None:
     source = (
         "TIMEOUT = 5.0\n"

package/hooks/diagnostic/CLAUDE.md

@@ -0,0 +1,43 @@
+# hooks/diagnostic
+
+Hooks and scripts that collect, store, and query hook-firing records. The pipeline reads session JSONL transcripts, extracts hook attachment records, and writes them as rows into a Neon (Postgres) `hook_events` table.
+
+## Subdirectories
+
+| Directory | Role |
+|---|---|
+| `migrations/` | SQL migration files for the `hook_events` schema |
+| `queries/` | Parameterized SQL queries for inspecting blocked commands |
+
+## Key files
+
+| File | What it does |
+|---|---|
+| `hook_log_init.py` | One-time setup: creates the Neon schema (runs `schema.sql`), then verifies read-write parity with a sentinel round-trip |
+| `hook_log_extractor.py` | Stop hook — reads per-session JSONL transcripts and ingests new `hook_*` attachment records into the `hook_events` table; idempotent via a UNIQUE constraint on `(source_jsonl_path, source_line_number)` |
+| `hook_log_stop_wrapper.py` | Thin wrapper that invokes `hook_log_extractor.py` from the Stop lifecycle event |
+| `schema.sql` | DDL for the `hook_events` table, `blocked_commands` view, and supporting indexes |
+| `requirements-hook-logs.txt` | Runtime dependencies (`psycopg`) for the extractor |
+| `requirements-hook-logs-dev.txt` | Dev/test dependencies |
+| `test_hook_log_extractor.py` | Tests for the extractor |
+| `test_hook_log_init.py` | Tests for the schema-init script |
+| `test_hook_log_stop_wrapper.py` | Tests for the Stop wrapper |
+
+## Schema overview (`schema.sql`)
+
+The `hook_events` table captures one row per hook firing:
+
+- `hook_event`, `hook_name`, `hook_category` — what fired
+- `outcome` — `allowed`, `blocked`, or `ask`
+- `tool_name`, `command_excerpt` — what tool was called
+- `session_id`, `git_branch`, `cwd` — context
+- `duration_ms`, `exit_code` — timing and result
+- `source_jsonl_path`, `source_line_number` — idempotency key
+
+The `blocked_commands` view filters to `outcome = 'blocked'`.
+
+## Conventions
+
+- The extractor exits 0 even when Neon is unreachable (offline-graceful); it logs to `OFFLINE_WARNING_LOG` and does not block session end.
+- Constants for the extractor (table name, offset state file, timeout) live in `hooks_constants/hook_log_extractor_constants.py`.
+- Tests run with `python -m pytest diagnostic/test_hook_log_*.py`.

package/hooks/diagnostic/migrations/CLAUDE.md

@@ -0,0 +1,16 @@
+# hooks/diagnostic/migrations
+
+SQL migration files for the `hook_events` Neon schema. Each file applies a schema change to the `hook_events` table or its indexes.
+
+## Files
+
+| File | What it does |
+|---|---|
+| `2026-04-25-drop-themes-hook-events.sql` | Drops the `themes` hook-events table variant |
+| `README.md` | Notes on the migration approach |
+
+## Conventions
+
+- Run migrations manually against the Neon database using `psql` or the Neon console.
+- The baseline schema lives in `diagnostic/schema.sql`.
+- File names follow `YYYY-MM-DD-<description>.sql` for chronological ordering.

package/hooks/diagnostic/queries/CLAUDE.md

@@ -0,0 +1,19 @@
+# hooks/diagnostic/queries
+
+Parameterized SQL queries for inspecting the `hook_events` Neon table. Run these directly against the Neon database to analyze hook-firing patterns.
+
+## Files
+
+| File | What it returns |
+|---|---|
+| `block_details_for_hook.sql` | Full details for all blocked events matching a given hook name |
+| `blocks_by_category.sql` | Count of blocks grouped by hook category |
+| `blocks_by_tool.sql` | Count of blocks grouped by tool name |
+| `blocks_last_7_days.sql` | All blocked events from the last 7 days |
+| `top_blockers_last_24_hours.sql` | Hook names with the most blocks in the last 24 hours |
+| `top_blockers_overall.sql` | Hook names with the most blocks across all time |
+
+## Conventions
+
+- Queries target the `hook_events` table and `blocked_commands` view defined in `diagnostic/schema.sql`.
+- Run with `psql $DATABASE_URL -f <query>.sql` or paste into the Neon console.

package/hooks/git-hooks/CLAUDE.md

@@ -0,0 +1,28 @@
+# hooks/git-hooks
+
+Native git hooks that run outside the Claude Code lifecycle — invoked directly by git at commit and push time. The installer copies these scripts into the user's shared git-hooks directory (`core.hooksPath`).
+
+## Key files
+
+| File | Git hook | What it does |
+|---|---|---|
+| `pre_commit.py` | `pre-commit` | Runs the CODE_RULES gate (`precommit_code_rules_gate.py`) over staged changes; exits 1 when any staged file has a blocking violation |
+| `pre_push.py` | `pre-push` | Runs the verified-commit gate check before a push reaches the remote |
+| `post_commit.py` | `post-commit` | Runs after a commit lands; performs any post-commit bookkeeping |
+| `gate_utils.py` | — | Shared helpers: resolves the gate script path, checks that the path is a safe regular file |
+| `test_config.py` | — | Test configuration helpers |
+| `test_gate_utils.py` | — | Tests for `gate_utils.py` |
+| `test_pre_commit.py` | — | Tests for `pre_commit.py` |
+| `test_pre_push.py` | — | Tests for `pre_push.py` |
+
+## Subdirectory
+
+| Directory | Role |
+|---|---|
+| `git_hooks_constants/` | Shared constants imported by the git-hook scripts |
+
+## Conventions
+
+- The installer strips the `_` and `.py` suffix when copying into the live git-hooks path (e.g. `pre_commit.py` becomes `pre-commit`).
+- Constants (exit codes, argument names, error messages) live in `git_hooks_constants/` and are imported at the top of each script.
+- Run tests with `python -m pytest git-hooks/test_<name>.py`.

package/hooks/git-hooks/git_hooks_constants/CLAUDE.md

@@ -0,0 +1,21 @@
+# hooks/git-hooks/git_hooks_constants
+
+Shared constants imported by the git-hook scripts in `git-hooks/`. Centralizes exit codes, argument names, and error messages so every tunable lives in one place.
+
+## Files
+
+| File | Contents |
+|---|---|
+| `__init__.py` | Exports all constants; marks this as a package so `from git_hooks_constants import ...` resolves |
+
+## Key constants (defined in `__init__.py`)
+
+- `GATE_INFRASTRUCTURE_FAILURE_EXIT_CODE` — exit code when the gate script cannot be found or launched
+- `GATE_SCRIPT_NOT_FOUND_MESSAGE` — error message when the gate script path does not exist
+- `INVOKE_GATE_FAILURE_MESSAGE` — error message when the gate subprocess fails to start
+- `STAGED_SCOPE_ARGUMENT` — CLI argument passed to the gate script to scope it to staged changes
+
+## Conventions
+
+- Import with `from git_hooks_constants import <CONSTANT>` from within the `git-hooks/` directory.
+- Add new constants here rather than inline in the hook scripts.

package/hooks/hooks_constants/CLAUDE.md

@@ -0,0 +1,60 @@
+# hooks/hooks_constants
+
+Shared constant modules imported by hooks throughout the `hooks/` tree. Each file holds the tunables for one hook or one cross-cutting concern, keeping magic values out of the hook scripts themselves.
+
+## Files
+
+| File | What it holds |
+|---|---|
+| `__init__.py` | Package marker (`# pragma: no-tdd-gate`) |
+| `any_type_config.py` | Config for the `Any`-type escape-hatch check |
+| `banned_identifiers_constants.py` | The set of banned short identifiers and banned function-name prefixes |
+| `blocking_check_limits.py` | Max issue counts and preview lengths for blocking hooks |
+| `bot_mention_comment_blocker_constants.py` | Patterns for detecting bot @-mentions in PR comments |
+| `code_rules_enforcer_constants.py` | File-extension sets, test-path patterns, advisory line thresholds, boolean-name prefixes |
+| `code_rules_path_utils_constants.py` | Path-matching helpers used by the code-rules check modules |
+| `convergence_branch_constants.py` | Branch and worktree naming patterns for the convergence gate |
+| `dead_argparse_argument_constants.py` | Patterns for detecting unused argparse arguments |
+| `dead_config_field_constants.py` | Patterns for detecting unused dataclass config fields |
+| `dead_dataclass_field_constants.py` | Patterns for detecting unused dataclass fields |
+| `dead_module_constant_constants.py` | Patterns for detecting unexported `UPPER_SNAKE` constants in `*_constants.py` modules |
+| `destructive_command_segment_constants.py` | The list of destructive shell command patterns the blocker matches |
+| `doc_gist_auto_publish_constants.py` | Sentinel marker and URL patterns for the doc-gist auto-publish hook |
+| `duplicate_function_body_constants.py` | Hashing and comparison config for the duplicate-body check |
+| `dynamic_stderr_handler.py` | `DynamicStderrHandler` — a logging handler that resolves `sys.stderr` at emit time (for testability) |
+| `gh_pr_author_swap_constants.py` | Constants for the PR-author swap enforcement hooks |
+| `hardcoded_user_path_constants.py` | Patterns for detecting hardcoded home-directory paths |
+| `hook_log_extractor_constants.py` | Neon table name, offset state file path, timeouts, and outcome-type mapping for the hook-log extractor |
+| `hook_prose_detector_consistency_constants.py` | Trigger patterns and corrective messages for the hook-prose consistency checker |
+| `html_companion_constants.py` | Blocked URL schemes and other config for the `.md`-to-`.html` companion hook |
+| `inline_tuple_string_magic_constants.py` | Patterns for detecting magic strings in inline tuple literals |
+| `md_to_html_blocker_constants.py` | Path exemptions and trigger patterns for the markdown-to-html blocker |
+| `messages.py` | Short user-facing notice strings shown when a Stop hook redirects agent behavior |
+| `open_questions_in_plans_blocker_constants.py` | Patterns for detecting unresolved open questions in plan documents |
+| `orphan_css_class_constants.py` | Scan radius and selector patterns for the orphan-CSS-class check |
+| `path_rewriter_constants.py` | Path rewriting patterns for the Everything-search path rewriter |
+| `plain_language_blocker_constants.py` | The list of heavy words and their everyday replacements |
+| `pr_converge_bugteam_enforcer_constants.py` | State keys and timing config for the bugteam-parallel enforcer |
+| `pr_converge_bugteam_enforcer_state.py` | State-file helpers for the bugteam enforcer |
+| `pr_description_enforcer_constants.py` | PR-description shape rules and command patterns |
+| `pre_tool_use_stdin.py` | `read_hook_input_dictionary_from_stdin()` — shared stdin parser for PreToolUse hooks |
+| `precommit_code_rules_gate_constants.py` | Scope argument and exit-code constants for the precommit gate |
+| `project_paths_reader.py` | Loads `~/.claude/project-paths.json` — the per-user project-path registry |
+| `session_env_cleanup_constants.py` | Stale-age threshold and directory names for the session-env cleanup hook |
+| `session_handoff_blocker_constants.py` | Trigger phrases for the session-handoff blocker |
+| `setup_project_paths_constants.py` | Encoding policy, BOM marker, and registry meta-key used across multiple hooks |
+| `state_description_blocker_constants.py` | The set of historical/comparative phrases the state-description blocker rejects |
+| `stuttering_check_config.py` | Config for the stuttering (repeated-phrase) check |
+| `stuttering_import_binding_constants.py` | Import-binding patterns for the stuttering check |
+| `subprocess_budget_completeness_constants.py` | Required argument names for the subprocess-budget completeness check |
+| `sys_path_insert_constants.py` | Patterns for detecting unguarded `sys.path.insert` calls |
+| `unused_module_import_constants.py` | Patterns for detecting unused module-level imports |
+| `windows_rmtree_blocker_constants.py` | The unsafe `shutil.rmtree` pattern and the safe replacement pattern |
+| `workflow_substitution_slot_blocker_constants.py` | Per-iteration token patterns for the workflow-slot blocker |
+
+## Conventions
+
+- Every file in this package is a pure constants module — no side effects, no I/O.
+- Hooks import from this package with `from hooks_constants.<module> import <CONSTANT>`.
+- Tests for these modules live beside them as `test_<module>.py`. Run with `python -m pytest hooks_constants/test_<name>.py`.
+- `dynamic_stderr_handler.py` and `pre_tool_use_stdin.py` are utility modules (not pure constants) but live here because they are shared across many hooks.

package/hooks/hooks_constants/blocking_check_limits.py

@@ -17,6 +17,8 @@ MAX_BOUNDARY_TYPE_ISSUES: int = 5
 ALL_BANNED_PREFIX_NAMES: tuple[str, ...] = ("handle_", "process_", "manage_", "do_")
 MAX_DOCSTRING_FORMAT_ISSUES: int = 5
 MAX_DOCSTRING_ARGS_SIGNATURE_ISSUES: int = 5
+MAX_CLASS_DOCSTRING_PUBLIC_METHOD_ISSUES: int = 5
+MINIMUM_PUBLIC_METHODS_FOR_CLASS_DOCSTRING_BREADTH: int = 2
 MAX_IGNORED_MUST_CHECK_RETURN_ISSUES: int = 5
 MAX_TYPE_ESCAPE_HATCH_ISSUES: int = 5
 MAX_THIN_WRAPPER_ISSUES: int = 1
@@ -25,6 +27,22 @@ MAX_LOGGING_FSTRING_ISSUES: int = 3
 MAX_WINDOWS_API_NONE_ISSUES: int = 3
 MAX_E2E_TEST_NAMING_ISSUES: int = 3
 DOCSTRING_TRIVIAL_FUNCTION_BODY_LINE_LIMIT: int = 3
+MAX_DOCSTRING_FALLBACK_BRANCH_ISSUES: int = 3
+DOCSTRING_FALLBACK_BRANCH_MINIMUM_ROUTE_COUNT: int = 2
+
+ALL_DOCSTRING_EXCLUSIVE_SCOPE_PHRASES: tuple[str, ...] = (
+    "only when",
+    "only if",
+    "falls back to",
+    "falling back to",
+    "fall back to",
+)
+
+ALL_DOCSTRING_MULTIPLE_CONDITION_JOINING_PHRASES: tuple[str, ...] = (
+    " or ",
+    "either",
+    "both",
+)
 
 ALL_BARE_EXCEPT_BANNED_HANDLER_NAMES: frozenset[str] = frozenset({"Exception", "BaseException"})
 ALL_BOUNDARY_TYPE_EXEMPT_FILENAMES: frozenset[str] = frozenset({"protocols.py", "types.py"})

package/hooks/lifecycle/CLAUDE.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 |
+| `pr_converge_bugteam_skill_tracker.py` | PostToolUse | Tracks which bugteam skill runs have completed within a pr-converge loop, so the enforcer can verify parallel execution |
+| `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_pr_converge_bugteam_skill_tracker.py` | — | Tests for `pr_converge_bugteam_skill_tracker.py` |
+
+## Conventions
+
+- Constants for these hooks (stale-age threshold, cache directory, known-hook-count file) live in `hooks_constants/session_env_cleanup_constants.py` and `hooks_constants/pr_converge_bugteam_enforcer_constants.py`.
+- Tests run with `python -m pytest lifecycle/test_<name>.py`.