claude-dev-env 2.13.0 → 2.14.0

package/hooks/blocking/gh_pr_author_restore.py

@@ -36,6 +36,7 @@ if hooks_parent_directory not in sys.path:
     sys.path.insert(0, hooks_parent_directory)
 
 from _gh_pr_author_swap_utils import (  # noqa: E402
+    _build_restore_failure_message,
     _command_invokes_gh_pr_create_in_stripped,
     _delete_state_file,
     _preprocess_command_for_matching,
@@ -89,8 +90,12 @@ def main() -> None:
         _delete_state_file(state_file)
     else:
         _write_line(
-            f"[gh-pr-author-restore] failed to restore active gh account to {original_account!r}; "
-            f"state file {state_file} left in place so the SessionStart cleanup hook can retry",
+            _build_restore_failure_message(
+                "gh-pr-author-restore",
+                original_account,
+                state_file,
+                "state file",
+            ),
             sys.stderr,
         )
     sys.exit(0)

package/hooks/blocking/intent_only_ending_blocker.py

@@ -1,12 +1,10 @@
 #!/usr/bin/env python3
-"""
-Stop hook that blocks Claude responses ending on a promise about undone work.
+"""Stop hook that blocks a turn ending with a promise of future work.
 
-When a turn ends on a forward-looking statement of intent ("I'll now run the
-tests", "Let me implement the fix") instead of actually doing the work, the
-agent is forced to do the work now with tool calls, or - when genuinely blocked
-on input only the user can supply - route through AskUserQuestion and end
-cleanly. The rule name is long-horizon-autonomy.
+When a turn ends with a forward-looking statement of intent ("I'll now run the
+tests", "Let me implement the fix"), complete the work with tool calls during
+the turn. Route work requiring user-only input through AskUserQuestion. The
+rule name is long-horizon-autonomy.
 """
 
 import json
@@ -104,7 +102,7 @@ def find_intent_only_ending(text: str) -> bool:
 
 
 def main() -> None:
-    """Read the stop-hook payload and block turns that end on a promise of undone work."""
+    """Read the stop-hook payload and block turns that promise future work."""
     try:
         hook_input = json.load(sys.stdin)
     except json.JSONDecodeError:
@@ -125,14 +123,11 @@ def main() -> None:
         sys.exit(0)
 
     block_reason = (
-        "LONG-HORIZON-AUTONOMY GUARDRAIL: Your turn ends on a promise about work "
-        "that is not yet done, rather than doing it. Do the work NOW with tool calls "
-        "instead of describing what you are about to do.\n\n"
-        "If the work is genuinely blocked on input only the user can give, route the "
-        "ask through an AskUserQuestion tool call and end the turn cleanly. Otherwise, "
-        "carry out the stated action this turn.\n\n"
-        "You MUST re-output the complete response with the work actually performed, "
-        "per the long-horizon-autonomy rule."
+        "LONG-HORIZON-AUTONOMY GUARDRAIL: This turn ends with a promise of future "
+        "work. Complete that work with tool calls during this turn. Route questions "
+        "requiring user-only input through AskUserQuestion, then end the turn cleanly.\n\n"
+        "Re-output the complete response with the work performed, per the "
+        "long-horizon-autonomy rule."
     )
     block_response = {
         "decision": "block",

package/hooks/blocking/inventory_intent_records/AGENTS.md

@@ -0,0 +1,26 @@
+# inventory_intent_records
+
+The shared pending-intent store that lets `package_inventory_stale_blocker.py`
+and `claude_md_orphan_file_blocker.py` add a new file and its inventory row in
+one change, in either order. When one blocker denies, it records a note; the
+sibling blocker reads that note to allow the matching second write.
+
+## Modules
+
+| File | Purpose |
+|---|---|
+| `records.py` | Read, record, peek, and consume the per-session file and row intents; a missing or corrupt store reads as no notes |
+| `__init__.py` | Package marker |
+
+## Subdirectories
+
+| Entry | Description |
+|---|---|
+| `config/` | The records-file name shape, the freshness window, the list keys, and the note field names (`intent_records_constants.py`) |
+| `tests/` | pytest suite for the records store |
+
+## Running tests
+
+```bash
+python -m pytest packages/claude-dev-env/hooks/blocking/inventory_intent_records/tests/
+```

package/hooks/blocking/inventory_intent_records/CLAUDE.md

@@ -1,26 +1 @@
-# inventory_intent_records
-
-The shared pending-intent store that lets `package_inventory_stale_blocker.py`
-and `claude_md_orphan_file_blocker.py` add a new file and its inventory row in
-one change, in either order. When one blocker denies, it records a note; the
-sibling blocker reads that note to allow the matching second write.
-
-## Modules
-
-| File | Purpose |
-|---|---|
-| `records.py` | Read, record, peek, and consume the per-session file and row intents; a missing or corrupt store reads as no notes |
-| `__init__.py` | Package marker |
-
-## Subdirectories
-
-| Entry | Description |
-|---|---|
-| `config/` | The records-file name shape, the freshness window, the list keys, and the note field names (`intent_records_constants.py`) |
-| `tests/` | pytest suite for the records store |
-
-## Running tests
-
-```bash
-python -m pytest packages/claude-dev-env/hooks/blocking/inventory_intent_records/tests/
-```
+@AGENTS.md

package/hooks/blocking/package_inventory_stale_blocker_parts/AGENTS.md

@@ -0,0 +1,26 @@
+# package_inventory_stale_blocker_parts
+
+The concern modules `package_inventory_stale_blocker.py` wires together to block a
+new production file its package inventory omits. The entry hook imports them and
+re-exports their surface for the test suite.
+
+## Modules
+
+| File | Purpose |
+|---|---|
+| `inventory_detection.py` | Surveys a directory's `README.md`/`CLAUDE.md`/`SKILL.md`, collects the filenames they name, and reports whether a maintained inventory omits the file being written |
+| `decision.py` | Builds the deny payload naming the omitted file and closing with the retry hint, and emits the decision JSON |
+| `__init__.py` | Package marker |
+
+## Subdirectories
+
+| Entry | Description |
+|---|---|
+| `config/` | The retry hint the deny reason closes with and the inventory-name join separator (`inventory_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/package_inventory_stale_blocker_parts/tests/
+```

package/hooks/blocking/package_inventory_stale_blocker_parts/CLAUDE.md

@@ -1,26 +1 @@
-# package_inventory_stale_blocker_parts
-
-The concern modules `package_inventory_stale_blocker.py` wires together to block a
-new production file its package inventory omits. The entry hook imports them and
-re-exports their surface for the test suite.
-
-## Modules
-
-| File | Purpose |
-|---|---|
-| `inventory_detection.py` | Surveys a directory's `README.md`/`CLAUDE.md`/`SKILL.md`, collects the filenames they name, and reports whether a maintained inventory omits the file being written |
-| `decision.py` | Builds the deny payload naming the omitted file and closing with the retry hint, and emits the decision JSON |
-| `__init__.py` | Package marker |
-
-## Subdirectories
-
-| Entry | Description |
-|---|---|
-| `config/` | The retry hint the deny reason closes with and the inventory-name join separator (`inventory_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/package_inventory_stale_blocker_parts/tests/
-```
+@AGENTS.md

package/hooks/blocking/pii_prevention_blocker_parts/AGENTS.md

@@ -0,0 +1,24 @@
+# pii_prevention_blocker_parts
+
+The concern modules `pii_prevention_blocker.py` wires together. The entry hook
+imports them and re-exports their surface for the test suite.
+
+## Modules
+
+| File | Purpose |
+|---|---|
+| `repository_exemption.py` | Resolves a commit's origin owner/repo slug, decides whether the repository skips the staged PII scan, and resolves the exact values that repository allows past the scan |
+| `repository_resolution.py` | Reads the repository a commit command targets — composing multiple `-C` values and a leading `cd`/`pushd` — and builds the deny reason naming the path when the repository root does not resolve |
+| `__init__.py` | Package marker |
+
+## Subdirectories
+
+| Entry | Description |
+|---|---|
+| `config/` | The repository-resolution deny-message template and the session-cwd label (`repository_resolution_constants.py`) |
+
+## Running tests
+
+```bash
+python -m pytest packages/claude-dev-env/hooks/blocking/tests/
+```

package/hooks/blocking/pii_prevention_blocker_parts/CLAUDE.md

@@ -1,24 +1 @@
-# pii_prevention_blocker_parts
-
-The concern modules `pii_prevention_blocker.py` wires together. The entry hook
-imports them and re-exports their surface for the test suite.
-
-## Modules
-
-| File | Purpose |
-|---|---|
-| `repository_exemption.py` | Resolves a commit's origin owner/repo slug, decides whether the repository skips the staged PII scan, and resolves the exact values that repository allows past the scan |
-| `repository_resolution.py` | Reads the repository a commit command targets — composing multiple `-C` values and a leading `cd`/`pushd` — and builds the deny reason naming the path when the repository root does not resolve |
-| `__init__.py` | Package marker |
-
-## Subdirectories
-
-| Entry | Description |
-|---|---|
-| `config/` | The repository-resolution deny-message template and the session-cwd label (`repository_resolution_constants.py`) |
-
-## Running tests
-
-```bash
-python -m pytest packages/claude-dev-env/hooks/blocking/tests/
-```
+@AGENTS.md

package/hooks/blocking/tdd_enforcer_parts/AGENTS.md

@@ -0,0 +1,30 @@
+# tdd_enforcer_parts
+
+The concern modules `tdd_enforcer.py` wires together to run the TDD gate. Each
+module owns one concern; the entry hook imports them and re-exports their
+surface for the test suite.
+
+## Modules
+
+| File | Purpose |
+|---|---|
+| `path_classification.py` | Classifies a write target (docs, tests, `.claude` trees) the gate skips, and extracts the written text from a Write, Edit, or MultiEdit payload |
+| `content_analysis.py` | Decides whether a payload is constants-only, and whether an Edit or MultiEdit merely removes or reorders imports |
+| `candidate_paths.py` | Resolves the candidate test files whose freshness can satisfy the gate for a production file |
+| `freshness.py` | Checks whether a candidate test was modified within the window and holds a real test function |
+| `git_tracking.py` | Detects a write that restores a git-tracked file absent on disk, so a remove-then-Write rewrite is exempt from the gate |
+| `decisions.py` | Builds the deny reason and writes the allow or deny decision JSON to stdout |
+| `__init__.py` | Package marker |
+
+## Subdirectories
+
+| Entry | Description |
+|---|---|
+| `config/` | The freshness window, the ancestor-walk limit, the git-tracking command tokens, the source-file extension sets, and the join separator (`tdd_enforcer_constants.py`) |
+| `tests/` | pytest suite with one test module per module above |
+
+## Running tests
+
+```bash
+python -m pytest packages/claude-dev-env/hooks/blocking/tdd_enforcer_parts/tests/
+```

package/hooks/blocking/tdd_enforcer_parts/CLAUDE.md

@@ -1,30 +1 @@
-# tdd_enforcer_parts
-
-The concern modules `tdd_enforcer.py` wires together to run the TDD gate. Each
-module owns one concern; the entry hook imports them and re-exports their
-surface for the test suite.
-
-## Modules
-
-| File | Purpose |
-|---|---|
-| `path_classification.py` | Classifies a write target (docs, tests, `.claude` trees) the gate skips, and extracts the written text from a Write, Edit, or MultiEdit payload |
-| `content_analysis.py` | Decides whether a payload is constants-only, and whether an Edit or MultiEdit merely removes or reorders imports |
-| `candidate_paths.py` | Resolves the candidate test files whose freshness can satisfy the gate for a production file |
-| `freshness.py` | Checks whether a candidate test was modified within the window and holds a real test function |
-| `git_tracking.py` | Detects a write that restores a git-tracked file absent on disk, so a remove-then-Write rewrite is exempt from the gate |
-| `decisions.py` | Builds the deny reason and writes the allow or deny decision JSON to stdout |
-| `__init__.py` | Package marker |
-
-## Subdirectories
-
-| Entry | Description |
-|---|---|
-| `config/` | The freshness window, the ancestor-walk limit, the git-tracking command tokens, the source-file extension sets, and the join separator (`tdd_enforcer_constants.py`) |
-| `tests/` | pytest suite with one test module per module above |
-
-## Running tests
-
-```bash
-python -m pytest packages/claude-dev-env/hooks/blocking/tdd_enforcer_parts/tests/
-```
+@AGENTS.md

package/hooks/blocking/test_code_rules_enforcer_banned_prefixes.py

@@ -1,6 +1,6 @@
 """Tests for check_banned_prefixes — flags function names with generic prefixes.
 
-CODE_RULES.md §5 / AGENTS.md "Naming → Function names use specific verbs:
+CODE_RULES.md §5 "Naming → Function names use specific verbs:
 parse_invoice, dispatch_event, migrate_schema. Generic prefixes to replace:
 handle_, process_, manage_, do_."
 

package/hooks/blocking/test_code_rules_enforcer_dead_module_constant.py

@@ -506,3 +506,174 @@ def test_dead_constant_stays_denied_on_every_attempt(neutral_root: Path) -> None
             "re-issue this write" in each_issue for each_issue in each_attempt
         ), f"A dead constant stays denied with the retry escape, got: {each_attempt}"
 
+
+ALIAS_CONSTANTS_BODY = 'BASE_PROMPTS_DIRECTORY_NAME = "prompts"\nSTYLE_SHEET_FILENAME = "style.css"\n'
+
+ALIASED_IMPORT_CONSUMER_BODY = (
+    "from style_guide_gen_constants.config import constants as sg\n"
+    "\n"
+    "def prompts_directory() -> str:\n"
+    "    return sg.BASE_PROMPTS_DIRECTORY_NAME\n"
+    "\n"
+    "def style_sheet() -> str:\n"
+    "    return sg.STYLE_SHEET_FILENAME\n"
+)
+
+
+def _build_alias_repository(
+    package_parent: Path,
+    consumer_directory: Path,
+    consumer_body: str,
+) -> Path:
+    package_directory = package_parent / "style_guide_gen_constants"
+    config_directory = package_directory / "config"
+    config_directory.mkdir(parents=True)
+    (package_directory / "__init__.py").write_text("", encoding="utf-8")
+    (config_directory / "__init__.py").write_text("", encoding="utf-8")
+    constants_path = config_directory / "constants.py"
+    constants_path.write_text(ALIAS_CONSTANTS_BODY, encoding="utf-8")
+    consumer_directory.mkdir(parents=True, exist_ok=True)
+    (consumer_directory / "style_guide_gen.py").write_text(consumer_body, encoding="utf-8")
+    return constants_path
+
+
+def test_does_not_flag_constant_read_through_an_aliased_module_import(
+    neutral_root: Path,
+) -> None:
+    constants_path = _build_alias_repository(
+        neutral_root,
+        neutral_root / "style_guide_gen_constants",
+        ALIASED_IMPORT_CONSUMER_BODY,
+    )
+    issues = _check(ALIAS_CONSTANTS_BODY, str(constants_path))
+    assert issues == [], (
+        f"A constant read as an attribute on an aliased module import stays live, got: {issues}"
+    )
+
+
+def test_does_not_flag_constant_read_through_an_alias_outside_the_package_tree(
+    neutral_root: Path,
+) -> None:
+    constants_path = _build_alias_repository(
+        neutral_root / "scripts",
+        neutral_root / "scripts",
+        ALIASED_IMPORT_CONSUMER_BODY,
+    )
+    issues = _check(ALIAS_CONSTANTS_BODY, str(constants_path))
+    assert issues == [], (
+        "A constant an aliased module import reads from outside the package tree "
+        f"stays live through the widened scan, got: {issues}"
+    )
+
+
+def test_does_not_flag_constant_read_through_an_unaliased_module_import_outside_the_tree(
+    neutral_root: Path,
+) -> None:
+    consumer_body = (
+        "from style_guide_gen_constants.config import constants\n"
+        "\n"
+        "def prompts_directory() -> str:\n"
+        "    return constants.BASE_PROMPTS_DIRECTORY_NAME\n"
+        "\n"
+        "def style_sheet() -> str:\n"
+        "    return constants.STYLE_SHEET_FILENAME\n"
+    )
+    constants_path = _build_alias_repository(
+        neutral_root / "scripts",
+        neutral_root / "scripts",
+        consumer_body,
+    )
+    issues = _check(ALIAS_CONSTANTS_BODY, str(constants_path))
+    assert issues == [], (
+        f"A constant read on an unaliased imported module object stays live, got: {issues}"
+    )
+
+
+def test_does_not_flag_constant_read_through_a_dotted_module_path_outside_the_tree(
+    neutral_root: Path,
+) -> None:
+    consumer_body = (
+        "import style_guide_gen_constants.config.constants\n"
+        "\n"
+        "def prompts_directory() -> str:\n"
+        "    return style_guide_gen_constants.config.constants.BASE_PROMPTS_DIRECTORY_NAME\n"
+        "\n"
+        "def style_sheet() -> str:\n"
+        "    return style_guide_gen_constants.config.constants.STYLE_SHEET_FILENAME\n"
+    )
+    constants_path = _build_alias_repository(
+        neutral_root / "scripts",
+        neutral_root / "scripts",
+        consumer_body,
+    )
+    issues = _check(ALIAS_CONSTANTS_BODY, str(constants_path))
+    assert issues == [], (
+        f"A constant read through the full dotted module path stays live, got: {issues}"
+    )
+
+
+def test_does_not_flag_constant_read_through_an_alias_in_a_sibling_tree(
+    neutral_root: Path,
+) -> None:
+    constants_body = 'CROSS_TREE_CONSTANT = "cross"\nLOCALLY_DEAD_CONSTANT = "dead"\n'
+    sibling_consumer_body = (
+        "from shared.theme_db.config import constants as theme_constants\n"
+        "\n"
+        "def tally() -> str:\n"
+        "    return theme_constants.CROSS_TREE_CONSTANT\n"
+    )
+    constants_path = _build_cross_tree_repository(
+        neutral_root, constants_body, sibling_consumer_body
+    )
+    issues = _check(constants_body, str(constants_path))
+    assert not any("CROSS_TREE_CONSTANT" in each_issue for each_issue in issues), (
+        "A constant a sibling tree reads as an attribute on an aliased module import "
+        f"must not be flagged, got: {issues}"
+    )
+    assert any("LOCALLY_DEAD_CONSTANT" in each_issue for each_issue in issues), (
+        f"A constant referenced nowhere in the repository stays flagged, got: {issues}"
+    )
+
+
+def _build_alias_collision_repository(
+    repository_root: Path,
+    promoter_constants_body: str,
+    harness_constants_body: str,
+    harness_consumer_body: str,
+) -> Path:
+    promoter_config = repository_root / "promoter" / "config"
+    promoter_config.mkdir(parents=True)
+    promoter_constants_path = promoter_config / "constants.py"
+    promoter_constants_path.write_text(promoter_constants_body, encoding="utf-8")
+    harness_config = repository_root / "harness" / "config"
+    harness_config.mkdir(parents=True)
+    (harness_config / "other_constants.py").write_text(harness_constants_body, encoding="utf-8")
+    (repository_root / "harness" / "lockfile.py").write_text(
+        harness_consumer_body, encoding="utf-8"
+    )
+    return promoter_constants_path
+
+
+def test_alias_attribute_read_on_an_unrelated_module_does_not_mask_a_dead_constant(
+    neutral_root: Path,
+) -> None:
+    promoter_constants_body = 'NEVER_READ_CONSTANT = "dead"\n'
+    harness_constants_body = 'NEVER_READ_CONSTANT = "twin"\n'
+    harness_consumer_body = (
+        "from harness.config import other_constants as oc\n"
+        "\n"
+        "def acquire() -> str:\n"
+        "    return oc.NEVER_READ_CONSTANT\n"
+    )
+    promoter_constants_path = _build_alias_collision_repository(
+        neutral_root,
+        promoter_constants_body,
+        harness_constants_body,
+        harness_consumer_body,
+    )
+    issues = _check(promoter_constants_body, str(promoter_constants_path))
+    assert any("NEVER_READ_CONSTANT" in each_issue for each_issue in issues), (
+        "A constant whose only same-named twin is read as an attribute on an "
+        f"unrelated aliased module must still be flagged dead, got: {issues}"
+    )
+

package/hooks/blocking/test_code_rules_enforcer_magic_allowlist.py

@@ -1,6 +1,6 @@
 """Tests for magic-value allowlist alignment with CODE_RULES §HOOK-ENFORCED.
 
-CODE_RULES.md and AGENTS.md both state that only
+CODE_RULES.md states that only
 0, 1, and -1 (plus their float forms 0.0, 1.0) are exempt from the
 magic-value check. Prior to this change, the hook silently allowed 2
 and 100 as well, making the hook more permissive than the written rule.

package/hooks/blocking/test_gh_pr_author_restore.py

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

package/hooks/blocking/test_intent_only_ending_blocker.py

@@ -111,6 +111,10 @@ def test_intent_ending_message_emits_block_with_short_user_notice():
     assert parsed_response["systemMessage"] == USER_FACING_INTENT_ENDING_NOTICE
     assert parsed_response["suppressOutput"] is True
     assert "long-horizon-autonomy" in parsed_response["reason"]
+    assert "This turn ends with a promise of future work." in parsed_response["reason"]
+    assert "Complete that work with tool calls during this turn." in parsed_response[
+        "reason"
+    ]
 
 
 def test_next_steps_lead_in_emits_block():

package/hooks/diagnostic/AGENTS.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` | Disabled CLI: exits 0 without reading transcripts or rewriting offset state; body remains for a re-enable path that ingests `hook_*` attachments into Neon |
+| `hook_log_stop_wrapper.py` | Disabled Stop wrapper stub: exits 0; not on the Stop dispatcher roster |
+| `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
+
+- Extractor and Stop wrapper mains are disabled and exit 0 with no work.
+- 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/CLAUDE.md

@@ -1,43 +1 @@
-# 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` | Disabled CLI: exits 0 without reading transcripts or rewriting offset state; body remains for a re-enable path that ingests `hook_*` attachments into Neon |
-| `hook_log_stop_wrapper.py` | Disabled Stop wrapper stub: exits 0; not on the Stop dispatcher roster |
-| `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
-
-- Extractor and Stop wrapper mains are disabled and exit 0 with no work.
-- 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`.
+@AGENTS.md

package/hooks/diagnostic/hook_log_extractor.py

@@ -99,7 +99,7 @@ from hooks_constants.hook_log_extractor_constants import (
     STDERR_EXCERPT_MAX_CHARACTERS,
     STDOUT_EXCERPT_MAX_CHARACTERS,
     SUMMARY_COLUMN_HEADINGS,
-    SUMMARY_NO_NEW_BLOCKS_MESSAGE,
+    SUMMARY_ZERO_BLOCKED_EVENTS_MESSAGE,
     SUMMARY_TABLE_COLUMN_GAP,
     TOP_BLOCKED_COMMAND_PREVIEW_MAX_CHARACTERS,
     TOP_BLOCKERS_LAST_24_HOURS_SQL,
@@ -780,7 +780,7 @@ def run_summary() -> int:
         except Exception:
             pass
     if not all_result_rows:
-        print(SUMMARY_NO_NEW_BLOCKS_MESSAGE)
+        print(SUMMARY_ZERO_BLOCKED_EVENTS_MESSAGE)
         return EXIT_CODE_SUCCESS
     _print_summary_table(all_result_rows)
     return EXIT_CODE_SUCCESS

package/hooks/diagnostic/migrations/AGENTS.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/migrations/CLAUDE.md

@@ -1,16 +1 @@
-# 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.
+@AGENTS.md