claude-dev-env 1.38.0 → 1.39.0

package/_shared/pr-loop/scripts/tests/test_post_audit_thread_constants.py

@@ -0,0 +1,127 @@
+"""Tests for post_audit_thread_constants.py extracted constant set."""
+
+import importlib.util
+from pathlib import Path
+from types import ModuleType
+
+
+def _load_constants_module() -> ModuleType:
+    module_path = (
+        Path(__file__).parent.parent / "config" / "post_audit_thread_constants.py"
+    )
+    specification = importlib.util.spec_from_file_location(
+        "config.post_audit_thread_constants", module_path
+    )
+    assert specification is not None
+    assert specification.loader is not None
+    module = importlib.util.module_from_spec(specification)
+    specification.loader.exec_module(module)
+    return module
+
+
+constants_module = _load_constants_module()
+
+
+def test_http_request_content_type_is_application_json() -> None:
+    assert constants_module.HTTP_REQUEST_CONTENT_TYPE == "application/json"
+
+
+def test_http_method_post_constant_is_post() -> None:
+    assert constants_module.HTTP_METHOD_POST == "POST"
+
+
+def test_http_header_authorization_constant_is_authorization() -> None:
+    assert constants_module.HTTP_HEADER_AUTHORIZATION == "Authorization"
+
+
+def test_http_header_accept_constant_is_accept() -> None:
+    assert constants_module.HTTP_HEADER_ACCEPT == "Accept"
+
+
+def test_http_header_content_type_constant_is_content_type() -> None:
+    assert constants_module.HTTP_HEADER_CONTENT_TYPE == "Content-Type"
+
+
+def test_http_header_github_api_version_constant_is_x_github_api_version() -> None:
+    assert constants_module.HTTP_HEADER_GITHUB_API_VERSION == "X-GitHub-Api-Version"
+
+
+def test_http_header_user_agent_constant_is_user_agent() -> None:
+    assert constants_module.HTTP_HEADER_USER_AGENT == "User-Agent"
+
+
+def test_http_authorization_bearer_prefix_is_bearer_with_trailing_space() -> None:
+    prefix = constants_module.HTTP_AUTHORIZATION_BEARER_PREFIX
+    assert prefix == "Bearer "
+    assert prefix.endswith(" ")
+
+
+def test_http_request_timeout_seconds_is_positive_int() -> None:
+    timeout_seconds = constants_module.HTTP_REQUEST_TIMEOUT_SECONDS
+    assert isinstance(timeout_seconds, int)
+    assert timeout_seconds > 0
+
+
+def test_error_response_preview_chars_is_positive_int() -> None:
+    preview_chars = constants_module.ERROR_RESPONSE_PREVIEW_CHARS
+    assert isinstance(preview_chars, int)
+    assert preview_chars > 0
+
+
+def test_single_review_api_path_template_uses_pr_number_placeholder() -> None:
+    template_text = constants_module.SINGLE_REVIEW_API_PATH_TEMPLATE
+    assert "{owner}" in template_text
+    assert "{repo}" in template_text
+    assert "{pr_number}" in template_text
+    assert "{review_id}" in template_text
+
+
+def test_single_review_comments_api_path_template_uses_pr_number_placeholder() -> None:
+    template_text = constants_module.SINGLE_REVIEW_COMMENTS_API_PATH_TEMPLATE
+    assert "{owner}" in template_text
+    assert "{repo}" in template_text
+    assert "{pr_number}" in template_text
+    assert "{review_id}" in template_text
+    assert template_text.endswith("/comments")
+
+
+def test_audit_body_skeleton_marker_tokens_present() -> None:
+    open_marker = constants_module.AUDIT_BODY_SKELETON_OPEN_MARKER
+    close_marker = constants_module.AUDIT_BODY_SKELETON_CLOSE_MARKER
+    assert open_marker.startswith("<!--") and open_marker.endswith("-->")
+    assert close_marker.startswith("<!--") and close_marker.endswith("-->")
+    assert open_marker != close_marker
+
+
+def test_template_path_resolves_to_existing_markdown_file() -> None:
+    resolved_path = constants_module.template_path()
+    assert resolved_path.is_file(), f"missing: {resolved_path}"
+    assert resolved_path.suffix == ".md"
+
+
+def test_template_contains_skeleton_markers() -> None:
+    resolved_path = constants_module.template_path()
+    template_text = resolved_path.read_text(encoding="utf-8")
+    assert constants_module.AUDIT_BODY_SKELETON_OPEN_MARKER in template_text
+    assert constants_module.AUDIT_BODY_SKELETON_CLOSE_MARKER in template_text
+
+
+def test_live_test_fixture_names_are_not_exposed_from_production_config_module() -> None:
+    forbidden_attribute_names = [
+        "LIVE_TEST_OWNER",
+        "LIVE_TEST_REPO",
+        "LIVE_TEST_BRANCH_PREFIX",
+        "LIVE_TEST_PR_TITLE",
+        "LIVE_TEST_PR_BODY",
+        "LIVE_TEST_BASE_BRANCH",
+        "LIVE_TEST_FIXTURE_FILENAME",
+        "LIVE_TEST_FIXTURE_CONTENT",
+        "LIVE_TEST_FIXTURE_LINE_FOR_FINDING_ONE",
+        "LIVE_TEST_FIXTURE_LINE_FOR_FINDING_TWO",
+        "LIVE_TEST_FIXTURE_LINE_FOR_FINDING_THREE",
+    ]
+    for each_attribute_name in forbidden_attribute_names:
+        assert not hasattr(constants_module, each_attribute_name), (
+            f"production config module exposes test-only fixture "
+            f"{each_attribute_name!r}; move it to test_post_audit_thread.py"
+        )

package/_shared/pr-loop/state-schema.md

@@ -11,7 +11,7 @@ State each PR-loop workflow tracks across iterations. Workflows differ on persis
 | `last_findings` | object | `{p0, p1, p2, total}` count of findings from most recent AUDIT |
 | `audit_log` | list[str] | Per-iteration one-line summaries for the final report |
 | `starting_sha` | str | `git rev-parse HEAD` at workflow start |
-| `loop_comment_index` | dict | `{finding_id: {finding_comment_id, finding_comment_url, used_fallback, fix_status, ...}}` |
+| `loop_comment_index` | dict | `{finding_id: {finding_comment_id, finding_comment_url, thread_node_id, fix_status, ...}}` (`thread_node_id` is the PR review thread node id — `PRRT_kwDOxxx` — captured at audit time when calling `get_review_comments`, used by `resolve_thread` at FIX time) |
 
 ## Workflow-specific extensions
 

package/agents/clean-coder.md

@@ -8,7 +8,7 @@ color: green
 
 # Clean Coder — Zero-Defect Code Generation
 
-You are the definitive code-writing agent. You produce code so clean that reviewers find nothing. Every rule from CODE_RULES.md and every dimension from the readability rubric is internalized into your generation process. The goal: `/check` and `/readability-review` return CLEAN on every file you touch.
+You are the definitive code-writing agent. You produce code so clean that reviewers find nothing. Every rule from CODE_RULES.md and every dimension from the readability rubric is internalized into your generation process. The goal: `/check` returns CLEAN on every file you touch.
 
 **Announce at start:** "Using clean-coder agent — CODE_RULES.md internalized, targeting 160/160 readability."
 
@@ -445,7 +445,7 @@ Code clean-coder writes will be audited later against the A–K bug categories f
 Every line you write or modify will:
 - Score 160/160 on the 8-dimension readability rubric
 - Satisfy every hook-enforced gate so each write succeeds on the first attempt
-- Return CLEAN from `/check`, `/review-code`, and `/readability-review`
+- Return CLEAN from `/check` and `/review-code`
 - Use complete type hints on every parameter and return
 - Pass `mypy_validator.py` cleanly — every file is mypy-clean at write time
 - Land in the format the project's `auto_formatter.py` produces — the formatter runs at write time, but generation should already match the canonical Black/Prettier output

package/bin/install.mjs

@@ -16,7 +16,7 @@ const PACKAGE_NAME = 'claude-dev-env';
 const PACKAGE_VERSION = JSON.parse(readFileSync(join(PACKAGE_ROOT, 'package.json'), 'utf8')).version;
 const packageRequire = createRequire(import.meta.url);
 
-export const CONTENT_DIRECTORIES = ['rules', 'docs', 'commands', 'agents', 'system-prompts', 'scripts', '_shared'];
+export const CONTENT_DIRECTORIES = ['rules', 'docs', 'commands', 'agents', 'system-prompts', 'scripts', '_shared', 'audit-rubrics'];
 
 export function collectPackageSourceConflicts(packageDirectory) {
     const gitConflictStatusCodes = new Set(['DD', 'AU', 'UD', 'UA', 'DU', 'AA', 'UU']);
@@ -147,17 +147,16 @@ const INSTALL_GROUPS = {
     core: {
         description: 'Development standards, hooks, agents, commands',
         skills: [
-            'anthropic-plan', 'everything-search', 'ingest',
-            'npm-creator', 'pr-review-responder', 'readability-review',
-            'recall', 'remember', 'rule-audit', 'rule-creator',
-            'skill-writer', 'tdd-team'
+            'anthropic-plan', 'everything-search',
+            'pr-review-responder',
+            'recall', 'remember'
         ],
-        includeDirectories: ['rules', 'docs', 'commands', 'agents'],
+        includeDirectories: ['rules', 'docs', 'commands', 'agents', 'audit-rubrics'],
         includeAllHooks: true,
     },
     journal: {
         description: 'Session logging and memory',
-        skills: ['dream', 'session-log', 'session-tidy'],
+        skills: ['session-log', 'session-tidy'],
     },
     research: {
         description: 'Deep research and citation tools',

package/bin/install.test.mjs

@@ -135,6 +135,14 @@ test('CONTENT_DIRECTORIES includes _shared so installer copies _shared/pr-loop/
 });
 
 
+test('CONTENT_DIRECTORIES includes audit-rubrics so installer copies category rubrics and prompts to ~/.claude/audit-rubrics/', () => {
+    assert.ok(
+        CONTENT_DIRECTORIES.includes('audit-rubrics'),
+        'audit-rubrics must be in CONTENT_DIRECTORIES so bugteam can resolve $HOME/.claude/audit-rubrics/{category_rubrics,prompts}/',
+    );
+});
+
+
 test('collectPackageSourceConflicts surfaces both-added and deleted-by-them entries', () => {
     const repositoryRoot = createTemporaryGitRepository();
     try {

package/commands/doc-gist.md

@@ -0,0 +1,16 @@
+---
+description: Upload an HTML file as a secret gist and open the htmlpreview URL. Manual escape hatch when the auto-publish hook's marker route doesn't apply.
+allowed-tools: Bash
+---
+
+Argument: `$ARGUMENTS` is the path to an existing `.html` file.
+
+Run the doc-gist skill's transport script directly:
+
+```
+python3 "${CLAUDE_PLUGIN_ROOT}/skills/doc-gist/scripts/gist_upload.py" --input "$ARGUMENTS"
+```
+
+Quote both URLs (`Gist:` and `Preview:`) from stderr back to the user as clickable markdown links. Surface any `gh gist create failed` error with the suggested `gh auth login` next-step.
+
+When the user asks for a writeup or report rather than handing you a file path, design fresh HTML per [`skills/doc-gist/SKILL.md`](../skills/doc-gist/SKILL.md), include the `<!-- @publish-as-gist -->` marker, and write the file — the auto-publish hook will run on Write. Use this command only when the marker route doesn't fit (existing file you want to publish, HTML from a separate tool).

package/commands/plan.md

@@ -41,8 +41,6 @@ Plan a feature with full validation workflow.
 | Design | `plan` skill | Collaborative design with config discovery |
 | Write | `write-plan` skill | TDD plan with CODE_RULES.md compliance |
 | Review Plan | `review-plan` skill | Validate plan against standards |
-| Execute | `plan-executor` agent | Implement with standards enforcement |
-| Review Code | `readability-review` skill | Validate code before commit |
 
 ## Standards Reference
 

package/commands/review-plan.md

@@ -1,5 +1,5 @@
 Review the current plan against code standards.
 
 1. Identify plan files in `.planning/phases/` or `docs/plans/`
-2. Invoke the `readability-review` skill via the Skill tool with the plan file paths
+2. Review the plan against CODE_RULES.md standards
 3. Report the verdict back to the user

package/docs/CODE_RULES.md

@@ -52,6 +52,16 @@ These rules are automatically enforced by `code_rules_enforcer.py`. Violations b
 | Hardcoded user paths | No string literals naming a specific user's home directory in production code (`C:/Users/jon/...`, `/Users/alice/...`, `/home/bob/...`). Use `pathlib.Path.home()` or `os.path.expanduser('~')`. **Exempt:** test files, `config/` files, workflow registry paths (`/workflow/`, `_tab.py`, `/states.py`, `/modules.py`), Django migrations (`/migrations/`), and hook infrastructure (the enforcer embeds path patterns and must not self-block). |
 | sys.path.insert dedup | `sys.path.insert(0, X)` must be guarded by `if X not in sys.path:` (or equivalent membership test) so reloads do not push the same entry repeatedly. **Test files exempt.** |
 | Unused module-level imports | Module-level imports never referenced in the file body are flagged. Skipped for files declaring `__all__` (re-exports), files using `TYPE_CHECKING` (annotation-only imports), and lines marked `# noqa`. **Test files exempt.** |
+| Banned identifiers | Single-letter or 2–4 char abbreviations in production code: `ctx`, `cfg`, `msg`, `btn`, `idx`, `cnt`, `tmp`, `elem`, `val`. Test files exempt; loop counters `i`/`j`/`k` and exception `e` exempt. See §5 for the full list and rationale. |
+| Banned function prefixes | Function names starting with `handle_`, `process_`, `manage_`, or `do_` are flagged — these prefixes describe nothing about behavior. Name functions after the noun they produce or the verb they perform (`fetch_user`, `validate_payload`). **Test files exempt.** |
+| Type escape hatches | `from typing import Any`, `cast()`, and inline `Any` in production are flagged outside boundary files (`__init__.py`, `protocols.py`, `types.py`, `conftest.py`). Name the concrete shape instead. |
+| Bare except | `except:` and `except BaseException:` swallow KeyboardInterrupt/SystemExit; `except Exception:` hides bugs by catching nearly every error class. Name the specific exception(s) you intend to catch (tuple form `except (ValueError, KeyError):` is fine). **Test files and hook infrastructure exempt.** |
+| Boundary types — Any in signatures | `Any` appearing directly or nested inside a generic in a function signature (parameters, return type) or class attribute annotation is flagged. Local variable annotations are exempt. Files named `protocols.py` or `types.py` are interface-declaration surfaces and exempt. |
+| Stub implementations | Functions whose body is `pass`, `...`, or `raise NotImplementedError` in production code are flagged unless declared abstract (`@abstractmethod`) or part of a `Protocol`. Implement the function or remove it. |
+| TypedDict encode/decode pairs | Every `class FooPayload(TypedDict):` in production code must have companion `_encode_foo_payload(...)` and `_decode_foo_payload(...)` functions in the same module — boundary serialization should not leak to callers. |
+| Test-mode branching in production | Reading `TESTING`, `PYTEST_CURRENT_TEST`, `IS_TEST`, etc. from production code creates two parallel implementations. Use dependency injection so production stays single-path. **Test files and hook infrastructure exempt.** |
+| Thin wrapper files | A non-`__init__.py` module whose body is only imports (optionally with an `__all__` assignment) is a re-export indirection with no payload. Callers should import from the real module. `__init__.py` is the canonical re-export surface and is exempt. |
+| Docstring format (Google-style) | Public functions/methods (no leading underscore, not dunder, body > 3 lines, not `@property`/`@abstractmethod`) require Google-style `Args:` / `Returns:` (or `Yields:`) / `Raises:` sections matching the signature. **Test files exempt.** |
 
 ### Where UPPER_SNAKE is allowed
 
@@ -112,7 +122,7 @@ Full words only. No mental translation.
 
 **Exception:** `i`, `j`, `k` in loops; `e` for exception.
 
-**Extended naming rules** (from readability-review rubric):
+**Extended naming rules** :
 - Loop vars: `each_order`, `each_user` (prefix `each_`)
 - Booleans: `is_valid`, `has_permission`, `should_retry` (prefix `is_`/`has_`/`should_`/`can_`)
 - Collections: `all_orders`, `all_users` (prefix `all_`)
@@ -227,6 +237,57 @@ Parent knows: nothing about child's internals
 
 ---
 
+## 9.5 NO THIN WRAPPER MODULES
+
+A non-`__init__.py` module whose body is only imports (optionally with an `__all__` assignment) is a thin wrapper. Callers should import from the real module. The wrapper adds no payload — only an indirection layer that obscures where things live.
+
+`__init__.py` is the canonical re-export surface and is exempt; package surface aggregation is its job.
+
+---
+
+## 9.6 NO BACKWARDS-COMPATIBILITY SHIMS
+
+Removed code is removed. Do not leave behind:
+
+- Renamed functions that re-export the old name with a `# deprecated` comment
+- `_old_*` aliases pointing to the new implementation
+- Wrapper modules whose only purpose is to keep an old import path alive
+- `// removed in vX` comment markers next to deleted blocks
+
+When a symbol moves or its signature changes, update the call sites in the same commit. The git log records what changed; the codebase records what exists now.
+
+> **See also:** [`skills/code/SKILL.md`](../skills/code/SKILL.md) §5 ("No fallback paths, no back-compat shims, no legacy code") states the same principle as a session-start prompt directive. This section is the authoritative wording; the skill amplifies it for `/code` sessions.
+
+---
+
+## 9.7 NO FALLBACK / BEST-EFFORT WRAPPERS
+
+Do not wrap a call in `try/except` that swallows the failure and returns a default unless the caller has explicitly opted in to that behavior at the boundary.
+
+```python
+# BAD — silently hides every failure mode
+def fetch_user(user_id: int) -> User | None:
+    try:
+        return _registry[user_id]
+    except Exception:
+        return None
+```
+
+```python
+# GOOD — names the specific failure and propagates the rest
+def fetch_user(user_id: int) -> User | None:
+    try:
+        return _registry[user_id]
+    except KeyError:
+        return None
+```
+
+Fallback values mask programming errors (KeyError vs RuntimeError vs AttributeError all collapse to "None"), making debugging impossible. Production code names the specific failure mode it intends to handle.
+
+> **See also:** [`skills/code/SKILL.md`](../skills/code/SKILL.md) §2 ("No `try`/`except` in core logic that recovers, softens, or best-efforts a failure") states the same principle as a session-start prompt directive. The hook check `check_bare_except` enforces the narrowest case (bare/`Exception`/`BaseException` handlers); this section + the `code` skill cover the broader "any swallowing handler" intent.
+
+---
+
 ## 10. NO REDUNDANT DATA FETCHES
 
 If you already have data, don't fetch again.
@@ -243,6 +304,53 @@ const profile = await db.profile.first();
 
 ---
 
+## 11. ENFORCEMENT SURFACES
+
+Rules in this document are enforced through three distinct surfaces, each with different latency and reach. Knowing which surface owns a rule tells you what happens when you violate it.
+
+| Surface | What it catches | When it runs | Failure mode |
+|---------|-----------------|--------------|--------------|
+| **⚡ Hook** | Pattern-matchable violations: comments, magic values, banned identifiers, bare except, boundary `Any`, thin wrappers, docstring shape, etc. | PreToolUse on Write/Edit (and PostToolUse advisories) | Blocks the write — Claude must fix and retry |
+| **🤖 Prompt** | Judgment-driven principles: SRP, Right-Sized Engineering, KISS, conservative-action, BDD discovery; strict-mode standards via the `/code` skill (no `Any`/`cast`, immutable TypedDicts, DI hooks, 100% branch coverage, no fallback `try/except`) | Read into the model context at session start (CLAUDE.md, rules/*.md, skill prepends) | Influences Claude's decisions; no automatic block |
+| **👥 Audit rubric** | Cross-file architectural concerns: SOLID misapplication, abstraction leaks, multi-file coupling | Run on demand via `/check`, `/readability-review`, agent-driven audits | Surfaces in audit output; humans decide whether to act |
+
+### Prompt-enforced rules (no hook coverage)
+
+These principles cannot be reduced to a regex or AST visitor. They live in user-private `~/.claude/rules/` and `~/.claude/CLAUDE.md`, and are read into context every session:
+
+- **Right-Sized Engineering** — concrete classes for single concretions, functions when no state, no DI frameworks for solo-scale code
+- **SRP / SOLID misapplication signals** — see §7.5
+- **conservative-action** — when intent is ambiguous, ask before acting
+- **explore-thoroughly** — investigate before committing to an approach
+- **agent-spawn-protocol** — verify context before delegating to a subagent
+- **`code` skill ([`skills/code/SKILL.md`](../skills/code/SKILL.md))** — invoked via `/code`, prepends strict-mode standards for the entire session: no `Any`/`cast()`/`# type: ignore`, immutable TypedDicts with manual `_encode_*`/`_decode_*` and `require_*` validation, per-module `_test_hooks.py` for DI, 100% statement + branch coverage, zero mocks. Several criteria overlap with §9.6/§9.7 and the ⚡ B-series checks; the skill is the canonical entry point when the user explicitly opts into strict mode for an implementation task.
+
+### Audit-rubric reference
+
+For multi-file architectural reviews see [`packages/claude-dev-env/audit-rubrics/`](../audit-rubrics/). Categories A–F, I, K stay as agent rubrics rather than ⚡ blocking rules because they require multi-file reasoning that single-file hooks cannot perform.
+
+---
+
+## 12. DEFERRED RULES (P1 — TRACKED, NOT ENFORCED)
+
+The following rules are documented in `~/.claude/rules/` and applied by Claude through prompt context, but have no hook coverage in `code_rules_enforcer.py`. Promotion to ⚡ blocking enforcement is on the backlog and will land as separate hardening commits.
+
+| Rule | Source | Promotion path |
+|------|--------|----------------|
+| Context7 before web search for library/SDK questions | [`rules/context7.md`](../rules/context7.md) | New PreToolUse hook on WebSearch when query mentions a library name |
+| Verify-before-asking checklist | [`rules/verify-before-asking.md`](../rules/verify-before-asking.md) | Stop hook scanning AskUserQuestion calls for "where is", "what file", etc. |
+| BDD naming (`should_…` / `describe…it…`) | [`rules/bdd.md`](../rules/bdd.md) | `code_rules_enforcer.py::check_test_naming` (new) — flag test functions starting with `test_` lacking corresponding `should_…` form |
+| `gh` pagination requires `--paginate --slurp` plus external `jq` | [`rules/gh-paginate.md`](../rules/gh-paginate.md) | PreToolUse Bash hook matching `gh api .*/(reviews\|comments)` without `--paginate --slurp` |
+| Self-contained documentation (no "as discussed", "Option A", session refs) | [`rules/self-contained-docs.md`](../rules/self-contained-docs.md) | PostToolUse Write hook scanning new `.md` content for conversational refs |
+| Temp file cleanup at end of task | [`rules/cleanup-temp-files.md`](../rules/cleanup-temp-files.md) | Stop hook scanning for files Claude created and did not delete |
+| No credentials committed to git | [`rules/git-workflow.md`](../rules/git-workflow.md) | PreToolUse Bash hook on `git commit` scanning staged diff for high-entropy strings, `.env` patterns, and known credential file extensions |
+| Per-module DI hooks (`_test_hooks.py` sibling) instead of `if TESTING:` branching | [`skills/code/SKILL.md`](../skills/code/SKILL.md) §4 | New `check_test_hooks_sibling()` — when a module imports a side-effect dependency and a test exists, require a `<module>_test_hooks.py` sibling exposing the injection points |
+| 100% statement + branch coverage with zero mocks | [`skills/code/SKILL.md`](../skills/code/SKILL.md) §3 | CI check (not write-time) — `pytest --cov-branch --cov-fail-under=100` on touched packages; covers only what the diff added |
+| `TypedDict` `_decode_*` calls `require_*` on every field | [`skills/code/SKILL.md`](../skills/code/SKILL.md) §6 | Extend `check_typed_dict_encode_decode` (B2) — when the decoder is present, AST-verify every TypedDict field appears as a `require_*` call before the return |
+| `Protocol` signatures match the real implementation exactly | [`skills/code/SKILL.md`](../skills/code/SKILL.md) Gotchas | mypy `--strict` over the protocol module catches this; promotion = add `[tool.mypy] strict = true` per-module override in `pyproject.toml` for files declaring `Protocol` subclasses |
+
+---
+
 ## QUICK CHECKLIST
 
 ```
@@ -257,6 +365,16 @@ Hook will enforce:
 [⚡] Logging format args
 [ ] File length reasonable (advisory at 400, strong nudge at 1000 — see §6.5)
 [⚡] Constants in config/
+[⚡] No banned identifiers (ctx, cfg, msg, btn, idx, cnt, tmp, elem, val)
+[⚡] No banned function prefixes (handle_, process_, manage_, do_)
+[⚡] No type escape hatches (Any imports, cast(), inline Any)
+[⚡] No bare except / except Exception / except BaseException
+[⚡] No Any in function signatures or class attributes (boundary types)
+[⚡] No stub bodies (pass / ... / raise NotImplementedError) outside abstract methods
+[⚡] TypedDict has companion _encode_*/_decode_* in same module
+[⚡] No test-mode branching in production (TESTING / PYTEST_CURRENT_TEST)
+[⚡] No thin wrapper modules (imports only, optionally with __all__, outside __init__.py)
+[⚡] Public functions have Google-style Args:/Returns:/Raises: when warranted
 
 Manual check:
 [ ] No abbreviations?
@@ -264,5 +382,7 @@ Manual check:
 [ ] Self-contained components?
 [ ] SRP holds (one reason to change per function/class/module)?
 [ ] OCP/LSP/ISP/DIP only applied where abstractions already earn their keep (see §7.5)?
-[ ] Readability: /check or /readability-review
+[ ] No backwards-compatibility shims (§9.6)?
+[ ] No fallback/best-effort wrappers (§9.7)?
+[ ] Readability: /check
 ```

package/hooks/blocking/bot_mention_comment_blocker.py

@@ -0,0 +1,75 @@
+#!/usr/bin/env python3
+"""PreToolUse hook: block @cursor or @copilot mentions in add_issue_comment body.
+
+Bugbot trigger requires exactly ``bugbot run`` with no other text. Copilot review
+requires the GitHub REST API endpoint, not an issue comment mention. This hook
+catches both mistakes and returns the correct procedure for each.
+"""
+
+import json
+import sys
+from pathlib import Path
+
+
+def _insert_hooks_tree_for_imports() -> None:
+    hooks_tree = Path(__file__).resolve().parent.parent
+    hooks_tree_string = str(hooks_tree)
+    if hooks_tree_string not in sys.path:
+        sys.path.insert(0, hooks_tree_string)
+
+
+_insert_hooks_tree_for_imports()
+
+from config.bot_mention_comment_blocker_constants import (
+    COPILOT_MENTION_TOKEN,
+    CORRECTIVE_MESSAGE_COPILOT,
+    CORRECTIVE_MESSAGE_CURSOR,
+    CURSOR_MENTION_TOKEN,
+    TOOL_NAME,
+)
+
+
+def _body_contains_token(body: str, token: str) -> bool:
+    return token.lower() in body.lower()
+
+
+def _detect_bot_mention(body: str) -> str | None:
+    """Return corrective message if body contains a blocked mention, else None."""
+    if _body_contains_token(body, COPILOT_MENTION_TOKEN):
+        return CORRECTIVE_MESSAGE_COPILOT
+    if _body_contains_token(body, CURSOR_MENTION_TOKEN):
+        return CORRECTIVE_MESSAGE_CURSOR
+    return None
+
+
+def main() -> None:
+    try:
+        hook_input = json.load(sys.stdin)
+    except json.JSONDecodeError:
+        sys.exit(0)
+
+    if hook_input.get("tool_name", "") != TOOL_NAME:
+        sys.exit(0)
+
+    body = hook_input.get("tool_input", {}).get("body", "")
+    if not body:
+        sys.exit(0)
+
+    corrective_message = _detect_bot_mention(body)
+    if corrective_message is None:
+        sys.exit(0)
+
+    deny_payload = {
+        "hookSpecificOutput": {
+            "hookEventName": "PreToolUse",
+            "permissionDecision": "deny",
+            "permissionDecisionReason": corrective_message,
+        }
+    }
+    print(json.dumps(deny_payload))
+    sys.stdout.flush()
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()