claude-dev-env 2.13.0 → 2.14.1

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,75 @@
+# 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`.
+
+## Schema init
+
+Run `hook_log_init.py` once per machine, or after rotating the Neon project.
+
+Prerequisites: Bitwarden Secrets Manager CLI (`bws`) on PATH; a machine-account
+token in `BWS_ACCESS_TOKEN` for the user environment (`setx` on Windows, shell
+profile on macOS/Linux); Neon connection string stored as
+`NEON_HOOK_LOGS_DATABASE_URL`; Python deps from `requirements-hook-logs.txt`.
+
+```
+bws run -- python packages/claude-dev-env/hooks/diagnostic/hook_log_init.py
+```
+
+`bws run` strips `BWS_ACCESS_TOKEN` from the child environment so the Python
+process never sees it. The script verifies `NEON_HOOK_LOGS_DATABASE_URL`,
+connects with a 5-second timeout, applies `schema.sql` with idempotent DDL,
+runs a sentinel insert/select/delete round-trip, and prints the Neon host,
+table name, and row count.
+
+## Operator CLI flags
+
+`hook_log_extractor.py` and `hook_log_stop_wrapper.py` mains exit 0 with no work.
+The extractor body still documents these flags for a re-enable path:
+
+- default / `--incremental`: resume from `~/.claude/logs/hooks/.state/offsets.json`
+- `--full-rebuild`: clear offsets, truncate `hook_events`, re-read every JSONL
+- `--summary`: print the top-10 blockers of the last 24 hours
+- `--query <name>`: run `queries/<name>.sql` (`top_blockers_overall`,
+  `top_blockers_last_24_hours`, `blocks_last_7_days`, `blocks_by_category`,
+  `blocks_by_tool`, `block_details_for_hook`)
+

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/hook_log_init.py

@@ -66,7 +66,7 @@ def verify_environment_variables() -> list[str]:
     child process invoked via ``bws run -- python hook_log_init.py``
     would therefore always fail even when the machine is configured
     correctly. The one-time ``setx BWS_ACCESS_TOKEN`` prerequisite is
-    documented in ``packages/claude-dev-env/commands/hook-log-init.md``.
+    documented in ``packages/claude-dev-env/hooks/diagnostic/AGENTS.md``.
     """
     all_missing_variable_names: list[str] = []
     raw_database_url_value = os.environ.get(NEON_DATABASE_URL_ENVIRONMENT_VARIABLE)
@@ -172,7 +172,7 @@ def _print_missing_environment_variables(all_missing_variable_names: list[str])
 
 
 def main() -> int:
-    """Entry point for the ``/hook-log-init`` slash command."""
+    """CLI entry for one-time Neon schema init."""
     all_missing_variable_names = verify_environment_variables()
     if all_missing_variable_names:
         _print_missing_environment_variables(all_missing_variable_names)

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

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

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

package/hooks/diagnostic/test_hook_log_extractor.py

@@ -617,7 +617,7 @@ def test_tool_name_extracted_from_hook_name_prefix() -> None:
     assert hook_log_extractor.extract_tool_name("UserPromptSubmit") is None
 
 
-def test_run_summary_prints_no_new_blocks_when_cursor_empty(
+def test_run_summary_prints_zero_blocked_events_when_cursor_empty(
     capsys: pytest.CaptureFixture[str],
 ) -> None:
     fake_cursor = MagicMock()
@@ -632,7 +632,7 @@ def test_run_summary_prints_no_new_blocks_when_cursor_empty(
 
     captured = capsys.readouterr()
     assert exit_code == 0
-    assert "No new blocks since last run." in captured.out
+    assert "Blocked events recorded in the last 24 hours: 0." in captured.out
 
 
 def test_run_summary_prints_table_when_rows_returned(

package/hooks/git-hooks/AGENTS.md

@@ -0,0 +1,31 @@
+# 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` | Blocks a push that would land a non-`main` local branch onto remote `main` (or `master`), then runs the CODE_RULES gate. An existing branch's gate base is the merge base with the remote default branch; the gate process still diffs that base against checkout HEAD, so the surface matches the pushed tip only when HEAD is that tip. |
+| `pre_push_base_reference.py` | — | Resolves a usable gate base for `pre_push.py`: reads the pushed remote name from git's arguments, then turns a symbolic default-branch head into a reference that git can resolve |
+| `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` |
+| `test_pre_push_base_reference.py` | — | Tests for the gate base resolution in `pre_push.py` |
+| `conftest.py` | — | Puts this directory on `sys.path` and clears cached `config` modules, so each test module imports the hooks at the top of the file |
+
+## 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/CLAUDE.md

@@ -1,31 +1 @@
-# 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` | Blocks a push that would land a non-`main` local branch onto remote `main` (or `master`), then runs the CODE_RULES gate. An existing branch's gate base is the merge base with the remote default branch; the gate process still diffs that base against checkout HEAD, so the surface matches the pushed tip only when HEAD is that tip. |
-| `pre_push_base_reference.py` | — | Resolves a usable gate base for `pre_push.py`: reads the pushed remote name from git's arguments, then turns a symbolic default-branch head into a reference that git can resolve |
-| `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` |
-| `test_pre_push_base_reference.py` | — | Tests for the gate base resolution in `pre_push.py` |
-| `conftest.py` | — | Puts this directory on `sys.path` and clears cached `config` modules, so each test module imports the hooks at the top of the file |
-
-## 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`.
+@AGENTS.md

package/hooks/git-hooks/git_hooks_constants/AGENTS.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/git-hooks/git_hooks_constants/CLAUDE.md

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

package/hooks/git-hooks/git_hooks_constants/__init__.py

@@ -49,12 +49,9 @@ NO_PARSEABLE_STDIN_LINES_MESSAGE: str = (
 NO_PARSEABLE_STDIN_LINES_SENTINEL: str = "__no_parseable_stdin_lines__"
 UNRESOLVABLE_MERGE_BASE_SENTINEL: str = "__unresolvable_merge_base__"
 UNRESOLVABLE_MERGE_BASE_MESSAGE: str = (
-    "claude-dev-env pre-push: git found no merge base between the pushed object "
-    "and the default branch, so the gate scope is unknown and "
-    "enforcement is skipped. That happens when the pushed branch and the "
-    "default branch hold unrelated histories, or when a default-branch ref "
-    "resolved and merge-base still could not name a shared commit "
-    "(for example a shallow clone missing the connecting history)."
+    "claude-dev-env pre-push: CODE_RULES validation is pending because the pushed "
+    "object and default branch have no shared merge base. Restore shared history "
+    "or provide a reachable default branch, then run the push again."
 )
 LOCAL_BRANCH_REFERENCE_PREFIX: str = "refs/heads/"
 ORIGIN_HEAD_SYMBOLIC_REFERENCE: str = "refs/remotes/origin/HEAD"
@@ -63,6 +60,7 @@ ALL_DEFAULT_BRANCH_FALLBACK_REFERENCES: tuple[str, ...] = (
     "refs/remotes/origin/main",
     "refs/remotes/origin/master",
 )
+REMOTE_BRANCH_REFERENCE_TEMPLATE: str = "refs/remotes/{remote}/{branch}"
 ALL_GIT_SYMBOLIC_REFERENCE_COMMAND_PREFIX: tuple[str, ...] = (
     "git",
     "symbolic-ref",