claude-dev-env 1.68.0 → 1.69.0

package/hooks/blocking/code_rules_docstrings.py

@@ -26,9 +26,11 @@ from hooks_constants.blocking_check_limits import (  # noqa: E402
     ALL_DOCSTRING_MULTIPLE_CONDITION_JOINING_PHRASES,
     DOCSTRING_FALLBACK_BRANCH_MINIMUM_ROUTE_COUNT,
     DOCSTRING_TRIVIAL_FUNCTION_BODY_LINE_LIMIT,
+    MAX_CLASS_DOCSTRING_PUBLIC_METHOD_ISSUES,
     MAX_DOCSTRING_ARGS_SIGNATURE_ISSUES,
     MAX_DOCSTRING_FALLBACK_BRANCH_ISSUES,
     MAX_DOCSTRING_FORMAT_ISSUES,
+    MINIMUM_PUBLIC_METHODS_FOR_CLASS_DOCSTRING_BREADTH,
 )
 from hooks_constants.code_rules_enforcer_constants import (  # noqa: E402
     ALL_DOCSTRING_ARGS_SECTION_HEADERS,
@@ -462,3 +464,98 @@ def check_docstring_fallback_branch_coverage(content: str, file_path: str) -> li
         if len(issues) >= MAX_DOCSTRING_FALLBACK_BRANCH_ISSUES:
             break
     return issues[:MAX_DOCSTRING_FALLBACK_BRANCH_ISSUES]
+
+
+def _class_docstring_summary_is_single_line(docstring_text: str) -> bool:
+    stripped_text = docstring_text.strip()
+    if not stripped_text:
+        return False
+    summary_line, separator, _remainder = stripped_text.partition("\n")
+    if separator and stripped_text[len(summary_line):].strip():
+        return False
+    return bool(summary_line.strip())
+
+
+def _public_method_names(class_node: ast.ClassDef) -> list[str]:
+    deduplicated_names: dict[str, None] = {}
+    for each_statement in class_node.body:
+        if not isinstance(each_statement, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            continue
+        if _function_is_private_or_dunder(each_statement.name):
+            continue
+        deduplicated_names[each_statement.name] = None
+    return list(deduplicated_names)
+
+
+def _name_tokens(method_name: str) -> list[str]:
+    return [each_token for each_token in method_name.split("_") if each_token]
+
+
+def _docstring_mentions_method(docstring_text: str, method_name: str) -> bool:
+    lowered_docstring = docstring_text.lower()
+    if method_name.lower() in lowered_docstring:
+        return True
+    return all(
+        each_token.lower() in lowered_docstring for each_token in _name_tokens(method_name)
+    )
+
+
+def _unmentioned_public_methods(class_node: ast.ClassDef, docstring_text: str) -> list[str]:
+    return [
+        each_name
+        for each_name in _public_method_names(class_node)
+        if not _docstring_mentions_method(docstring_text, each_name)
+    ]
+
+
+def check_class_docstring_names_public_methods(
+    content: str, file_path: str
+) -> list[str]:
+    """Flag a one-line class docstring that omits two or more public methods.
+
+    A class whose docstring is a single summary line names one responsibility,
+    so a reader trusts that line to describe the whole class. When the class
+    later gains a second public entry point — the drift pattern where a
+    coffee-break reporter grows a regular-pace method — the terse summary keeps
+    describing only the original feature. Each public method whose name (or all
+    of its underscore-separated tokens) appears nowhere in the summary counts as
+    omitted; a class with two or more omitted public methods is reported so the
+    summary is widened to name the broader surface. Classes with a multi-line
+    docstring body are left to the audit lane, since their prose can carry the
+    enumeration without naming each method by name.
+
+    Args:
+        content: The source text to inspect.
+        file_path: The path the source will be written to, used for exemptions.
+
+    Returns:
+        One issue per class whose single-line docstring omits two or more of its
+        public methods, capped at the module limit.
+    """
+    if is_test_file(file_path) or is_hook_infrastructure(file_path):
+        return []
+    try:
+        parsed_tree = ast.parse(content)
+    except SyntaxError:
+        return []
+    issues: list[str] = []
+    for each_node in _walk_skipping_type_checking_blocks(parsed_tree):
+        if not isinstance(each_node, ast.ClassDef):
+            continue
+        class_docstring = ast.get_docstring(each_node) or ""
+        if not _class_docstring_summary_is_single_line(class_docstring):
+            continue
+        public_names = _public_method_names(each_node)
+        if len(public_names) < MINIMUM_PUBLIC_METHODS_FOR_CLASS_DOCSTRING_BREADTH:
+            continue
+        unmentioned_names = _unmentioned_public_methods(each_node, class_docstring)
+        if len(unmentioned_names) < MINIMUM_PUBLIC_METHODS_FOR_CLASS_DOCSTRING_BREADTH:
+            continue
+        issues.append(
+            f"Line {each_node.lineno}: {each_node.name} one-line docstring omits "
+            f"public method(s) {', '.join(unmentioned_names)} — widen the summary "
+            "so it names the class's full public surface"
+        )
+        if len(issues) >= MAX_CLASS_DOCSTRING_PUBLIC_METHOD_ISSUES:
+            break
+    return issues[:MAX_CLASS_DOCSTRING_PUBLIC_METHOD_ISSUES]

package/hooks/blocking/code_rules_enforcer.py

@@ -65,6 +65,7 @@ from code_rules_dead_module_constant import (  # noqa: E402
     check_dead_module_constants,
 )
 from code_rules_docstrings import (  # noqa: E402
+    check_class_docstring_names_public_methods,
     check_docstring_args_match_signature,
     check_docstring_fallback_branch_coverage,
     check_docstring_format,
@@ -250,6 +251,9 @@ def validate_content(
         all_issues.extend(check_docstring_format(effective_content, file_path))
         all_issues.extend(check_docstring_args_match_signature(effective_content, file_path))
         all_issues.extend(check_docstring_fallback_branch_coverage(effective_content, file_path))
+        all_issues.extend(
+            check_class_docstring_names_public_methods(effective_content, file_path)
+        )
         all_issues.extend(
             check_boolean_naming(
                 effective_content,

package/hooks/blocking/config/CLAUDE.md

@@ -0,0 +1,22 @@
+# hooks/blocking/config
+
+A Python package that holds shared constants for the verified-commit gate family. Three modules in `blocking/` import from here:
+
+- `verification_verdict_store.py`
+- `verified_commit_gate.py`
+- `verifier_verdict_minter.py`
+
+## Key files
+
+| File | Contents |
+|---|---|
+| `__init__.py` | Declares this as a regular package (not a namespace package) so it resolves first on `sys.path` |
+| `verified_commit_constants.py` | All tunables for the gate: directory names, regex patterns for detecting verdict paths and obfuscation attempts, timeout values, git subcommand sets, bypass marker, and corrective messages |
+
+## Key constants in `verified_commit_constants.py`
+
+- `VERIFICATION_BYPASS_MARKER` — the `# verify-skip` comment that exempts a single commit/push from the gate
+- `MINTING_AGENT_TYPE` — `"code-verifier"`, the agent type whose SubagentStop hook mints verdicts
+- `VERDICT_DIRECTORY_NAME` — `"verification"`, the directory under `~/.claude/` that holds verdict JSON files
+- `DOCS_ONLY_EXTENSIONS` — extensions (`.md`, `.txt`, images) whose changes are mechanically exempt from the gate
+- `CORRECTIVE_MESSAGE` / `VERDICT_DIRECTORY_GUARD_MESSAGE` — user-facing block messages

package/hooks/blocking/test_code_rules_enforcer_class_docstring_methods.py

@@ -0,0 +1,262 @@
+"""Tests for check_class_docstring_names_public_methods — class prose breadth.
+
+A class whose docstring is a single summary line names one responsibility. When
+the class exposes a second public entry point the summary never names, the prose
+under-describes the class — the same drift the os_update_workflow break reporter
+hit when it grew a regular-pace method beside its coffee-break method.
+"""
+
+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_class_docstring_names_public_methods(content: str, file_path: str) -> list[str]:
+    return code_rules_enforcer.check_class_docstring_names_public_methods(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/break_reporter.py"
+TEST_FILE_PATH = "/project/src/test_break_reporter.py"
+HOOK_INFRASTRUCTURE_PATH = "/home/user/.claude/hooks/blocking/example.py"
+
+
+def _narrow_class_with_widened_surface() -> str:
+    return (
+        "class ConsoleBreakReporter:\n"
+        '    """Run a coffee break with operator visibility: announce, then count down."""\n'
+        "\n"
+        "    async def pause_then_resume(self, seconds: float) -> None:\n"
+        "        await self._sleep(seconds)\n"
+        "\n"
+        "    async def stretch_then_resume(self, seconds: float) -> None:\n"
+        "        await self._sleep(seconds)\n"
+    )
+
+
+def test_should_flag_single_line_docstring_omitting_two_public_methods() -> None:
+    issues = check_class_docstring_names_public_methods(
+        _narrow_class_with_widened_surface(), PRODUCTION_FILE_PATH
+    )
+    assert any("pause_then_resume" in each for each in issues), (
+        f"Expected omitted-method flag, got: {issues!r}"
+    )
+    assert any("stretch_then_resume" in each for each in issues)
+    assert len(issues) == 1
+
+
+def test_should_not_flag_when_summary_names_every_public_method() -> None:
+    source = (
+        "class ConsoleBreakReporter:\n"
+        '    """Announce a pause then resume, or stretch then resume, with a countdown."""\n'
+        "\n"
+        "    async def pause_then_resume(self, seconds: float) -> None:\n"
+        "        await self._sleep(seconds)\n"
+        "\n"
+        "    async def stretch_then_resume(self, seconds: float) -> None:\n"
+        "        await self._sleep(seconds)\n"
+    )
+    issues = check_class_docstring_names_public_methods(source, PRODUCTION_FILE_PATH)
+    assert issues == [], f"Summary naming every method must not flag, got: {issues!r}"
+
+
+def test_should_not_flag_when_only_one_public_method_is_omitted() -> None:
+    source = (
+        "class ConsoleBreakReporter:\n"
+        '    """Pause then resume the submission run with an operator countdown."""\n'
+        "\n"
+        "    async def pause_then_resume(self, seconds: float) -> None:\n"
+        "        await self._sleep(seconds)\n"
+        "\n"
+        "    async def stretch_then_resume(self, seconds: float) -> None:\n"
+        "        await self._sleep(seconds)\n"
+    )
+    issues = check_class_docstring_names_public_methods(source, PRODUCTION_FILE_PATH)
+    assert issues == [], f"A single omitted method must not flag, got: {issues!r}"
+
+
+def test_should_not_flag_multi_line_docstring_body() -> None:
+    source = (
+        "class ConsoleBreakReporter:\n"
+        '    """Run a coffee break with operator visibility.\n'
+        "\n"
+        "    Also paces the regular between-theme waits through the same seam.\n"
+        '    """\n'
+        "\n"
+        "    async def pause_then_resume(self, seconds: float) -> None:\n"
+        "        await self._sleep(seconds)\n"
+        "\n"
+        "    async def stretch_then_resume(self, seconds: float) -> None:\n"
+        "        await self._sleep(seconds)\n"
+    )
+    issues = check_class_docstring_names_public_methods(source, PRODUCTION_FILE_PATH)
+    assert issues == [], f"Multi-line docstrings go to the audit lane, got: {issues!r}"
+
+
+def test_should_not_flag_class_with_single_public_method() -> None:
+    source = (
+        "class ConsoleBreakReporter:\n"
+        '    """Run a coffee break with operator visibility."""\n'
+        "\n"
+        "    async def pause_then_resume(self, seconds: float) -> None:\n"
+        "        await self._sleep(seconds)\n"
+    )
+    issues = check_class_docstring_names_public_methods(source, PRODUCTION_FILE_PATH)
+    assert issues == [], f"A one-method class must not flag, got: {issues!r}"
+
+
+def test_should_skip_private_methods_when_counting_surface() -> None:
+    source = (
+        "class ConsoleBreakReporter:\n"
+        '    """Run a coffee break with operator visibility."""\n'
+        "\n"
+        "    async def pause_then_resume(self, seconds: float) -> None:\n"
+        "        await self._sleep(seconds)\n"
+        "\n"
+        "    async def _sleep(self, seconds: float) -> None:\n"
+        "        await self._clock.sleep(seconds)\n"
+        "\n"
+        "    def __init__(self) -> None:\n"
+        "        self._clock = None\n"
+    )
+    issues = check_class_docstring_names_public_methods(source, PRODUCTION_FILE_PATH)
+    assert issues == [], f"Private and dunder methods are not public surface, got: {issues!r}"
+
+
+def test_should_skip_class_without_docstring() -> None:
+    source = (
+        "class ConsoleBreakReporter:\n"
+        "    async def pause_then_resume(self, seconds: float) -> None:\n"
+        "        await self._sleep(seconds)\n"
+        "\n"
+        "    async def stretch_then_resume(self, seconds: float) -> None:\n"
+        "        await self._sleep(seconds)\n"
+    )
+    issues = check_class_docstring_names_public_methods(source, PRODUCTION_FILE_PATH)
+    assert issues == [], f"No-docstring classes are out of scope, got: {issues!r}"
+
+
+def test_should_skip_test_file() -> None:
+    issues = check_class_docstring_names_public_methods(
+        _narrow_class_with_widened_surface(), TEST_FILE_PATH
+    )
+    assert issues == [], f"Test files exempt, got: {issues!r}"
+
+
+def test_should_skip_hook_infrastructure() -> None:
+    issues = check_class_docstring_names_public_methods(
+        _narrow_class_with_widened_surface(), HOOK_INFRASTRUCTURE_PATH
+    )
+    assert issues == [], f"Hook infrastructure exempt, got: {issues!r}"
+
+
+def test_should_handle_syntax_error_gracefully() -> None:
+    issues = check_class_docstring_names_public_methods("class Broken(\n", PRODUCTION_FILE_PATH)
+    assert issues == [], f"Syntax error must yield no issues, got: {issues!r}"
+
+
+def _real_break_reporter_drift() -> str:
+    return (
+        "class ConsoleBreakReporter:\n"
+        '    """Run a coffee-break with operator visibility: announce, then count down."""\n'
+        "\n"
+        "    async def announce_and_pause(self, nominal_break_seconds: float) -> None:\n"
+        "        await self._announce(nominal_break_seconds)\n"
+        "\n"
+        "    async def announce_and_pause_exact(self, break_seconds: float) -> None:\n"
+        "        await self._announce(break_seconds)\n"
+    )
+
+
+def test_should_flag_real_break_reporter_widened_surface() -> None:
+    issues = check_class_docstring_names_public_methods(
+        _real_break_reporter_drift(), PRODUCTION_FILE_PATH
+    )
+    assert any("announce_and_pause_exact" in each for each in issues), (
+        f"Expected the regular-pace method to flag, got: {issues!r}"
+    )
+    assert any("announce_and_pause" in each for each in issues)
+    assert len(issues) == 1
+
+
+def _overload_class_omitting_the_only_method() -> str:
+    return (
+        "from typing import overload\n"
+        "\n"
+        "class PayloadTransformer:\n"
+        '    """Hold a fixed payload value for later use."""\n'
+        "\n"
+        "    @overload\n"
+        "    def transform(self, payload: str) -> dict[str, str]: ...\n"
+        "\n"
+        "    @overload\n"
+        "    def transform(self, payload: bytes) -> dict[str, str]: ...\n"
+        "\n"
+        "    def transform(self, payload: str | bytes) -> dict[str, str]:\n"
+        "        return self._normalize(payload)\n"
+    )
+
+
+def test_should_not_flag_single_overloaded_method_below_breadth_threshold() -> None:
+    issues = check_class_docstring_names_public_methods(
+        _overload_class_omitting_the_only_method(), PRODUCTION_FILE_PATH
+    )
+    assert issues == [], f"One overloaded public method must not flag, got: {issues!r}"
+
+
+def test_should_not_repeat_an_overloaded_name_in_the_issue_message() -> None:
+    source = (
+        "from typing import overload\n"
+        "\n"
+        "class PayloadTransformer:\n"
+        '    """Hold a fixed payload value for later use."""\n'
+        "\n"
+        "    @overload\n"
+        "    def transform(self, payload: str) -> dict[str, str]: ...\n"
+        "\n"
+        "    @overload\n"
+        "    def transform(self, payload: bytes) -> dict[str, str]: ...\n"
+        "\n"
+        "    def transform(self, payload: str | bytes) -> dict[str, str]:\n"
+        "        return self._normalize(payload)\n"
+        "\n"
+        "    def reset(self) -> None:\n"
+        "        self._payload = None\n"
+    )
+    issues = check_class_docstring_names_public_methods(source, PRODUCTION_FILE_PATH)
+    assert len(issues) == 1, f"Expected a single drift issue, got: {issues!r}"
+    only_issue = issues[0]
+    assert only_issue.count("transform") == 1, (
+        f"Overloaded name must appear once in the message, got: {only_issue!r}"
+    )
+    assert "reset" in only_issue
+
+
+def test_validate_content_surfaces_class_docstring_breadth_drift() -> None:
+    issues = validate_content(
+        _narrow_class_with_widened_surface(), PRODUCTION_FILE_PATH, old_content=""
+    )
+    matching_issues = [
+        each for each in issues if "pause_then_resume" in each and "public method" in each
+    ]
+    assert matching_issues, (
+        f"Expected validate_content to surface the class-breadth drift, got: {issues!r}"
+    )

package/hooks/blocking/test_code_rules_enforcer_dead_module_constant.py

@@ -56,6 +56,12 @@ def _check(source: str, file_path: str) -> list[str]:
     return code_rules_enforcer.check_dead_module_constants(source, file_path)
 
 
+def _check_edit(fragment: str, full_file_content: str, file_path: str) -> list[str]:
+    return code_rules_enforcer.check_dead_module_constants(
+        fragment, file_path, full_file_content
+    )
+
+
 def _build_constants_package(
     workflow_directory: Path,
     constants_body: str,
@@ -94,6 +100,36 @@ def test_flags_constant_imported_by_no_module_in_the_tree(neutral_root: Path) ->
     ), f"Imported constants must not be flagged, got: {issues}"
 
 
+def test_flags_a_dead_constant_added_by_an_edit_to_an_existing_module(
+    neutral_root: Path,
+) -> None:
+    consumer_body = (
+        "from report_constants.render_report_constants import (\n"
+        "    MEDIUM_CODE,\n"
+        "    MEDIUM_TERMINAL,\n"
+        ")\n"
+        "\n"
+        "def panel_class(medium: str) -> str:\n"
+        "    if medium == MEDIUM_TERMINAL:\n"
+        "        return 'terminal'\n"
+        "    return 'code-panel' if medium == MEDIUM_CODE else 'text-panel'\n"
+    )
+    prior_body = 'MEDIUM_TERMINAL = "terminal"\nMEDIUM_CODE = "code"\n'
+    constants_path = _build_constants_package(
+        neutral_root / "workflow", prior_body, consumer_body
+    )
+    edit_fragment = 'MEDIUM_CODE = "code"\nMEDIUM_TEXT = "text"\n'
+    post_edit_body = prior_body + 'MEDIUM_TEXT = "text"\n'
+    issues = _check_edit(edit_fragment, post_edit_body, str(constants_path))
+    assert any("MEDIUM_TEXT" in each_issue for each_issue in issues), (
+        f"An Edit that inserts a dead constant must be flagged, got: {issues}"
+    )
+    assert not any(
+        "MEDIUM_TERMINAL" in each_issue or "MEDIUM_CODE" in each_issue
+        for each_issue in issues
+    ), f"Imported constants must not be flagged on an edit, got: {issues}"
+
+
 def test_does_not_flag_constant_imported_one_directory_up(neutral_root: Path) -> None:
     consumer_uses_text = (
         "from report_constants.render_report_constants import (\n"

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.