claude-dev-env 1.47.0 → 1.49.0

package/CLAUDE.md

@@ -9,6 +9,8 @@ The user delegates execution to you and expects zero manual steps unless strictl
 ## Code Rules
 @~/.claude/docs/CODE_RULES.md
 
+When an edit deletes or rewrites code, delete everything it orphans in the same edit — unused variables, uncalled functions, unpassed parameters, dead branches, unused imports — once Serena's `find_referencing_symbols` (plus a text search for dynamic lookups) confirms they're unreachable from any live entry point, not merely unreferenced; when liveness is uncertain, ask via AskUserQuestion rather than risk deleting live code (CODE_RULES.md §9.8).
+
 ALWAYS call the AskUserQuestion tool if you have a question for the user. Provide content-appropriate default options, with a flag for the recommended one.
 
 ## Timeless Documentation (all `.md` files)
@@ -50,3 +52,4 @@ Reserve `Read`/`Grep`/`Glob` for files you will actually touch this turn. Compos
 ## Additional Non-overlapping Rules
 
 - **task_scope:** Match every action to what was explicitly requested. When intent is ambiguous, research official docs and present options via AskUserQuestion before making any changes. Proceed with edits only on explicit instruction.
+- **confirm_implementation_forks:** When two or more viable paths would satisfy the goal and the choice changes the deliverable — its scope, completeness, deferred work, dependencies, or a hard-to-reverse contract — stop and ask which path via AskUserQuestion before implementing. A path that defers work or leaves a placeholder creating a follow-up task is itself a fork to surface, not a default to take silently. Phrase the question in plain language with only the detail needed to decide. See [`confirm-implementation-forks`](rules/confirm-implementation-forks.md).

package/docs/CODE_RULES.md

@@ -288,6 +288,31 @@ Fallback values mask programming errors (KeyError vs RuntimeError vs AttributeEr
 
 ---
 
+## 9.8 REMOVE CODE YOU ORPHAN (Dead Code Elimination)
+
+When an edit deletes or rewrites code, it must also remove everything that edit makes dead. The change is not complete while orphans remain.
+
+After deleting or rewriting code, trace what it referenced and remove whatever is unreachable as a result:
+
+- **Variables** with no remaining readers after the change
+- **Functions / methods** with no remaining call sites
+- **Parameters** that no caller passes
+- **Branches** made unreachable (dead `if`/`else`, conditions that are always true or always false)
+- **Imports** left unused (also caught by the unused-import hook)
+- **Helper files** whose only consumer you just deleted
+
+**Confirm the orphan is truly unreferenced first.** "No remaining call sites" means none *anywhere in the codebase*, not just in the file you edited. Before removing a function, method, class, or module-level name, run Serena's `find_referencing_symbols` on it: the language server resolves call sites, `import` statements, and re-exports across files far more reliably and cheaply than a text sweep. Back it with a plain text search for string-based dynamic lookups (`getattr`, entry-point names) that the language server cannot see. A reference is not proof of life — the referrer can be dead too. The symbol is live only when some chain of references reaches a live entry point: a CLI command, route, public API, test, or any caller outside the code you are removing. Trace the referrers upward. If every chain dead-ends in code that is itself unreferenced, the whole cluster is dead — remove it together in the same commit (§9.6). If any chain reaches a live entry point, the symbol is in use; leave it. Deleting something still reachable breaks its importers; treating a self-referential dead cluster as alive leaves litter.
+
+**When liveness is uncertain, ask — never guess.** A tool cannot always tell what is live: a chain may leave the repository (a public API, plugin hook, or module other projects import), or run through dynamic or reflective dispatch that no search resolves. If you cannot conclusively prove a symbol is unreachable, do not delete it. Surface the specific ambiguity to the user through AskUserQuestion and let them decide. Removing live production code is never an acceptable risk — when in doubt, keep it and ask.
+
+This is the inverse of comment preservation: existing **comments** are sacred and never removed, but dead **code** is removed in the same edit that orphans it. A function left with no callers is not "preserved" — it is litter.
+
+> **See also:** §9.6 (a renamed alias is dead code by another name), the `file_global_constants_use_count` rule (zero references → delete), and the unused-import hook check — each enforces a specific slice of this principle automatically.
+
+> **Standard terms (shorthand for this section):** the mechanical part is *dead code elimination* (compilers; Aho et al., *Compilers: Principles, Techniques, and Tools*) and *tree-shaking* (bundlers like Rollup/Webpack) — retain only what is reachable from a live entry point. The ask-when-uncertain overlay guards against the *Lava Flow* anti-pattern — dead code kept because removing it feels risky (Brown et al., *AntiPatterns*, 1998). Compare Fowler's "Remove Dead Code" refactoring (*Refactoring*, 2nd ed., 2018). Direct source links: [`references/dead-code-elimination.md`](references/dead-code-elimination.md).
+
+---
+
 ## 10. NO REDUNDANT DATA FETCHES
 
 If you already have data, don't fetch again.
@@ -384,5 +409,6 @@ Manual check:
 [ ] OCP/LSP/ISP/DIP only applied where abstractions already earn their keep (see §7.5)?
 [ ] No backwards-compatibility shims (§9.6)?
 [ ] No fallback/best-effort wrappers (§9.7)?
+[ ] No code orphaned by an edit (§9.8 — dead vars, uncalled functions, unused imports, dead branches)?
 [ ] Readability: /check
 ```

package/docs/references/dead-code-elimination.md

@@ -0,0 +1,17 @@
+# Dead Code Elimination — Reference
+
+External sources and standard terminology behind [CODE_RULES §9.8](../CODE_RULES.md#98-remove-code-you-orphan-dead-code-elimination). Each entry names the concept, gives a one-line definition, and links a direct source.
+
+## The mechanic — removing code that cannot affect results
+
+- **Dead-code elimination (DCE)** — a compiler optimization that removes code which does not affect program results, reducing program size, resource use, and execution time. Foundational treatment: Aho, Lam, Sethi & Ullman, *Compilers: Principles, Techniques, and Tools* (the "Dragon Book"). <https://en.wikipedia.org/wiki/Dead-code_elimination>
+- **Tree shaking** — dead-code elimination driven by `import`/`export` structure: keep only the exports reachable from an entry point and drop the rest. MDN glossary: <https://developer.mozilla.org/en-US/docs/Glossary/Tree_shaking>. Webpack guide: <https://webpack.js.org/guides/tree-shaking/>
+- **Remove Dead Code** — the named refactoring for eliminating unreachable or unused segments to improve clarity and maintainability. Martin Fowler, *Refactoring* (2nd ed., 2018): <https://refactoring.com/catalog/removeDeadCode.html>
+
+## The liveness test — reachability, not mere reference
+
+- **Unreachable code / reachability analysis** — code with no control-flow path from the rest of the program; detecting it is a form of control-flow analysis. This is the basis for §9.8 testing reachability from a live entry point rather than the bare presence of a reference. <https://en.wikipedia.org/wiki/Unreachable_code>
+
+## The safety overlay — why uncertain deletions escalate
+
+- **Lava Flow anti-pattern** — suboptimal code that survives in production because accumulated dependencies and backward-compatibility fears make removal feel risky. Brown, Malveau, McCormick & Mowbray, *AntiPatterns* (1998). The §9.8 "ask when uncertain, never guess-delete" clause guards against blind risky removals. <https://en.wikipedia.org/wiki/Lava_flow_(programming)>

package/hooks/blocking/plain_language_blocker.py

@@ -0,0 +1,184 @@
+#!/usr/bin/env python3
+"""PreToolUse hook that blocks heavy words in AskUserQuestion prose and .md writes.
+
+Reaches for the everyday word over the formal one: `use` over `utilize`,
+`start` over `initiate`, `enough` over `sufficient`. Two surfaces are guarded --
+AskUserQuestion (its question and option prose) and Write/Edit/MultiEdit targeting a .md
+file. Code fences, inline code, blockquotes, URLs, and file paths are stripped
+before matching so exact identifiers and paths are never flagged.
+
+See the plain-language rule for the full guidance this hook enforces.
+"""
+
+import json
+import sys
+from pathlib import Path
+from typing import TextIO
+
+_hooks_dir = str(Path(__file__).resolve().parent.parent)
+if _hooks_dir not in sys.path:
+    sys.path.insert(0, _hooks_dir)
+
+from hooks_constants.plain_language_blocker_constants import (  # noqa: E402
+    ALL_SOFTWARE_TERMS,
+    ALL_TERM_PATTERNS,
+    ALL_WRITE_EDIT_TOOL_NAMES,
+    ASK_USER_QUESTION_TOOL_NAME,
+    BLOCKQUOTE_LINE_PATTERN,
+    FENCED_CODE_BLOCK_PATTERN,
+    FILE_PATH_PATTERN,
+    INLINE_CODE_PATTERN,
+    MARKDOWN_EXTENSION,
+    URL_PATTERN,
+    USER_FACING_PLAIN_LANGUAGE_NOTICE,
+)
+
+
+def strip_non_prose_regions(text: str) -> str:
+    """Return text with code, quotes, URLs, and file paths removed.
+
+    These regions carry exact identifiers and references that plain language
+    leaves untouched, so they must not contribute matches.
+    """
+    without_fences = FENCED_CODE_BLOCK_PATTERN.sub("", text)
+    without_inline_code = INLINE_CODE_PATTERN.sub("", without_fences)
+    without_blockquotes = BLOCKQUOTE_LINE_PATTERN.sub("", without_inline_code)
+    without_urls = URL_PATTERN.sub("", without_blockquotes)
+    without_paths = FILE_PATH_PATTERN.sub("", without_urls)
+    return without_paths
+
+
+def find_banned_terms(text: str) -> list[tuple[str, str]]:
+    """Return each (matched term, suggested replacement) found in the prose.
+
+    Each term appears at most once, in first-seen order. Matching is
+    case-insensitive and respects word boundaries; multi-word phrases match as
+    whole units. Terms in the software-term allowlist are exempt and never
+    flagged.
+    """
+    prose_text = strip_non_prose_regions(text)
+    all_matches: list[tuple[str, str]] = []
+    seen_terms: set[str] = set()
+    for each_pattern, each_replacement in ALL_TERM_PATTERNS:
+        first_match = each_pattern.search(prose_text)
+        if first_match is None:
+            continue
+        normalized_term = first_match.group(0).lower()
+        if normalized_term in seen_terms:
+            continue
+        if normalized_term in ALL_SOFTWARE_TERMS:
+            continue
+        seen_terms.add(normalized_term)
+        all_matches.append((normalized_term, each_replacement))
+    return all_matches
+
+
+def build_block_reason(all_matches: list[tuple[str, str]]) -> str:
+    """Return a deny reason naming each flagged term and its plain replacement."""
+    swap_phrases = ", ".join(
+        f'use "{each_replacement}" instead of "{each_term}"'
+        for each_term, each_replacement in all_matches
+    )
+    return (
+        "BLOCKED: [PLAIN_LANGUAGE] Heavy words detected -- "
+        f"{swap_phrases}. Reach for the everyday word the reader understands "
+        "on the first pass."
+    )
+
+
+def _collect_ask_user_question_prose(tool_input: dict) -> str:
+    all_questions = tool_input.get("questions", [])
+    if not isinstance(all_questions, list):
+        return ""
+    prose_segments: list[str] = []
+    for each_question in all_questions:
+        if not isinstance(each_question, dict):
+            continue
+        question_text = each_question.get("question", "")
+        if isinstance(question_text, str):
+            prose_segments.append(question_text)
+        all_options = each_question.get("options", [])
+        if isinstance(all_options, list):
+            for each_option in all_options:
+                if isinstance(each_option, dict):
+                    option_label = each_option.get("label", "")
+                    if isinstance(option_label, str):
+                        prose_segments.append(option_label)
+                    option_description = each_option.get("description", "")
+                    if isinstance(option_description, str):
+                        prose_segments.append(option_description)
+    return "\n".join(prose_segments)
+
+
+def _collect_write_edit_markdown_prose(tool_name: str, tool_input: dict) -> str:
+    file_path = tool_input.get("file_path", "")
+    if not isinstance(file_path, str) or not file_path.lower().endswith(MARKDOWN_EXTENSION):
+        return ""
+    if tool_name == "Write":
+        content = tool_input.get("content", "")
+        return content if isinstance(content, str) else ""
+    if tool_name == "Edit":
+        new_string = tool_input.get("new_string", "")
+        return new_string if isinstance(new_string, str) else ""
+    all_edits = tool_input.get("edits", [])
+    if not isinstance(all_edits, list):
+        return ""
+    prose_segments: list[str] = []
+    for each_edit in all_edits:
+        if isinstance(each_edit, dict):
+            new_string = each_edit.get("new_string", "")
+            if isinstance(new_string, str):
+                prose_segments.append(new_string)
+    return "\n".join(prose_segments)
+
+
+def _collect_prose_for_tool(tool_name: str, tool_input: dict) -> str:
+    if tool_name == ASK_USER_QUESTION_TOOL_NAME:
+        return _collect_ask_user_question_prose(tool_input)
+    if tool_name in ALL_WRITE_EDIT_TOOL_NAMES:
+        return _collect_write_edit_markdown_prose(tool_name, tool_input)
+    return ""
+
+
+def _emit_deny(all_matches: list[tuple[str, str]], output_stream: TextIO) -> None:
+    deny_payload = {
+        "hookSpecificOutput": {
+            "hookEventName": "PreToolUse",
+            "permissionDecision": "deny",
+            "permissionDecisionReason": build_block_reason(all_matches),
+        },
+        "systemMessage": USER_FACING_PLAIN_LANGUAGE_NOTICE,
+        "suppressOutput": True,
+    }
+    output_stream.write(json.dumps(deny_payload))
+    output_stream.flush()
+
+
+def main() -> None:
+    try:
+        input_data = json.load(sys.stdin)
+    except json.JSONDecodeError:
+        sys.exit(0)
+
+    if not isinstance(input_data, dict):
+        sys.exit(0)
+
+    tool_name = input_data.get("tool_name", "")
+    tool_input = input_data.get("tool_input", {})
+    if not isinstance(tool_name, str) or not isinstance(tool_input, dict):
+        sys.exit(0)
+
+    prose_text = _collect_prose_for_tool(tool_name, tool_input)
+    if not prose_text:
+        sys.exit(0)
+
+    all_matches = find_banned_terms(prose_text)
+    if not all_matches:
+        sys.exit(0)
+
+    _emit_deny(all_matches, sys.stdout)
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

package/hooks/blocking/pr_description_enforcer.py

@@ -31,6 +31,7 @@ from hooks_constants.pr_description_enforcer_constants import (  # noqa: E402
     ALL_HEAVY_TESTING_HEADERS,
     ALL_READABILITY_CLI_FLAG_TOKENS,
     ATOMIC_WRITE_TEMP_SUFFIX,
+    BLOCKQUOTE_LINE_PATTERN,
     BLOCKQUOTE_MARKER_PATTERN,
     BOLD_PAIR_PATTERN,
     BULLET_MARKER_PATTERN,
@@ -63,6 +64,7 @@ from hooks_constants.pr_description_enforcer_constants import (  # noqa: E402
     SELF_CLOSING_REFERENCE_MESSAGE_SUFFIX,
     SELF_REFERENCE_PATTERN_TEMPLATE,
     STANDARD_SHAPE,
+    TABLE_ROW_LINE_PATTERN,
     THIS_PR_OPENING_PATTERN,
     TRIVIAL_BODY_CHAR_THRESHOLD,
     TRIVIAL_SHAPE,
@@ -350,6 +352,23 @@ def _count_substantive_prose_chars(body: str) -> int:
     return len(body_collapsed)
 
 
+def _extract_vague_scan_text(body: str) -> str:
+    """Return the prose to scan for vague language, with non-prose regions removed.
+
+    Drops whole blockquote lines and whole pipe-delimited table rows, then strips
+    the same Markdown ceremony as the prose-count path -- which removes fenced
+    code, inline code, and whole heading lines. This exempts vague phrases that
+    appear only inside code fences, inline code, Markdown headings, quoted
+    reviewer text, or pipe-delimited example tables -- those are not the author's
+    own prose. A pipe-delimited row carries at least two pipes; a line with a
+    single leading pipe, or a borderless table row with no leading pipe, stays in
+    scope.
+    """
+    without_blockquote_lines = BLOCKQUOTE_LINE_PATTERN.sub("", body)
+    without_table_rows = TABLE_ROW_LINE_PATTERN.sub("", without_blockquote_lines)
+    return _strip_markdown_ceremony(without_table_rows)
+
+
 def _iter_section_headers(body: str) -> list[str]:
     """Return every ATX heading line in the body, preserving canonical form.
 
@@ -813,7 +832,8 @@ def validate_pr_body(body: str, pr_number: int | None = None) -> list[str]:
             "(Adds, Fixes, Updates, Removes, Tightens, Ports)"
         )
 
-    vague_matches = VAGUE_LANGUAGE_PATTERN.findall(body)
+    vague_scan_text = _extract_vague_scan_text(body)
+    vague_matches = VAGUE_LANGUAGE_PATTERN.findall(vague_scan_text)
     if vague_matches:
         violations.append(
             f"Vague language detected: {', '.join(vague_matches)} -- "

package/hooks/blocking/test_plain_language_blocker.py

@@ -0,0 +1,247 @@
+"""Tests for the plain_language_blocker PreToolUse hook.
+
+Covers the shared prose scanner (fenced code, inline code, blockquotes, URLs,
+file paths), the word-boundary guard, multi-word phrase matching, case
+insensitivity, the term -> replacement block message, and both registered
+PreToolUse surfaces (AskUserQuestion and Write|Edit on .md targets).
+"""
+
+import importlib.util
+import json
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+HOOK_SCRIPT_PATH = Path(__file__).parent / "plain_language_blocker.py"
+_HOOKS_DIR = str(Path(__file__).resolve().parent)
+_HOOKS_ROOT = str(Path(__file__).resolve().parent.parent)
+if _HOOKS_DIR not in sys.path:
+    sys.path.insert(0, _HOOKS_DIR)
+if _HOOKS_ROOT not in sys.path:
+    sys.path.insert(0, _HOOKS_ROOT)
+
+
+def _load_hook_module() -> object:
+    module_spec = importlib.util.spec_from_file_location(
+        "plain_language_blocker_under_test", HOOK_SCRIPT_PATH
+    )
+    assert module_spec is not None and module_spec.loader is not None
+    loaded_module = importlib.util.module_from_spec(module_spec)
+    module_spec.loader.exec_module(loaded_module)
+    return loaded_module
+
+
+hook_module = _load_hook_module()
+find_banned_terms = hook_module.find_banned_terms
+strip_non_prose_regions = hook_module.strip_non_prose_regions
+build_block_reason = hook_module.build_block_reason
+
+
+def _run_hook_with_payload(payload: dict) -> subprocess.CompletedProcess[str]:
+    return subprocess.run(
+        [sys.executable, str(HOOK_SCRIPT_PATH)],
+        input=json.dumps(payload),
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+
+
+def _decision_from(completed: subprocess.CompletedProcess[str]) -> str | None:
+    if not completed.stdout:
+        return None
+    parsed = json.loads(completed.stdout)
+    return parsed.get("hookSpecificOutput", {}).get("permissionDecision")
+
+
+def test_canonical_hook_script_exists_at_expected_path() -> None:
+    assert HOOK_SCRIPT_PATH.is_file()
+
+
+def test_bare_prose_banned_term_is_detected() -> None:
+    matched = find_banned_terms("We initiate the worker pool at boot.")
+    assert any(each_term == "initiate" for each_term, _replacement in matched)
+
+
+def test_banned_term_inside_fenced_code_is_exempt() -> None:
+    prose = "Start the pool at boot.\n\n```python\nutilize(pool)\n```\n"
+    assert find_banned_terms(prose) == []
+
+
+def test_banned_term_inside_inline_code_is_exempt() -> None:
+    prose = "Call the `utilize` helper from the legacy module to migrate."
+    assert find_banned_terms(prose) == []
+
+
+def test_banned_term_inside_blockquote_is_exempt() -> None:
+    prose = "> The old guide said to utilize the pool.\n\nUse the pool directly now."
+    assert find_banned_terms(prose) == []
+
+
+def test_banned_term_inside_url_is_exempt() -> None:
+    prose = "See https://example.com/initiate-flow for the original write-up."
+    assert find_banned_terms(prose) == []
+
+
+def test_banned_term_inside_file_path_is_exempt() -> None:
+    prose = "Edit src/utilize_helpers/initiate.py to wire the new path."
+    assert find_banned_terms(prose) == []
+
+
+def test_word_boundary_guard_does_not_match_substring() -> None:
+    assert find_banned_terms("The reinitialize routine reruns the seed.") == []
+
+
+def test_case_insensitive_match() -> None:
+    matched_lower = find_banned_terms("utilize the cache.")
+    matched_upper = find_banned_terms("Utilize the cache.")
+    assert any(term == "utilize" for term, _ in matched_lower)
+    assert any(term == "utilize" for term, _ in matched_upper)
+
+
+def test_multi_word_phrase_matches_as_unit() -> None:
+    matched = find_banned_terms("Run the migration prior to the deploy step.")
+    assert any(term == "prior to" for term, _ in matched)
+
+
+def test_strip_non_prose_regions_removes_code_and_paths() -> None:
+    prose = "Use `utilize` and src/initiate.py and https://x.test/utilize here."
+    stripped = strip_non_prose_regions(prose)
+    assert "utilize" not in stripped
+    assert "initiate" not in stripped
+
+
+def test_block_reason_names_term_and_replacement() -> None:
+    reason = build_block_reason([("initiate", "start")])
+    assert "initiate" in reason
+    assert "start" in reason
+
+
+def test_ask_user_question_with_banned_term_is_denied() -> None:
+    payload = {
+        "tool_name": "AskUserQuestion",
+        "tool_input": {
+            "questions": [
+                {
+                    "question": "Should we utilize the new allocator now?",
+                    "header": "Allocator",
+                    "options": [{"label": "Yes", "description": "Switch now."}],
+                }
+            ]
+        },
+    }
+    completed = _run_hook_with_payload(payload)
+    assert _decision_from(completed) == "deny"
+
+
+def test_ask_user_question_banned_term_in_option_label_is_denied() -> None:
+    payload = {
+        "tool_name": "AskUserQuestion",
+        "tool_input": {
+            "questions": [
+                {
+                    "question": "Which path should we take?",
+                    "header": "Path",
+                    "options": [{"label": "Utilize the cache", "description": "Go fast."}],
+                }
+            ]
+        },
+    }
+    completed = _run_hook_with_payload(payload)
+    assert _decision_from(completed) == "deny"
+
+
+def test_clean_ask_user_question_passes_through() -> None:
+    payload = {
+        "tool_name": "AskUserQuestion",
+        "tool_input": {
+            "questions": [
+                {
+                    "question": "Should we switch the allocator now?",
+                    "header": "Allocator",
+                    "options": [{"label": "Yes", "description": "Switch now."}],
+                }
+            ]
+        },
+    }
+    completed = _run_hook_with_payload(payload)
+    assert _decision_from(completed) is None
+
+
+def test_write_markdown_with_banned_term_is_denied(tmp_path: Path) -> None:
+    target = tmp_path / "notes.md"
+    payload = {
+        "tool_name": "Write",
+        "tool_input": {
+            "file_path": str(target),
+            "content": "This guide explains how to utilize the new cache layer.",
+        },
+    }
+    completed = _run_hook_with_payload(payload)
+    assert _decision_from(completed) == "deny"
+
+
+def test_write_non_markdown_is_ignored(tmp_path: Path) -> None:
+    target = tmp_path / "notes.txt"
+    payload = {
+        "tool_name": "Write",
+        "tool_input": {
+            "file_path": str(target),
+            "content": "This guide explains how to utilize the new cache layer.",
+        },
+    }
+    completed = _run_hook_with_payload(payload)
+    assert _decision_from(completed) is None
+
+
+def test_edit_markdown_clean_content_passes_through(tmp_path: Path) -> None:
+    target = tmp_path / "notes.md"
+    payload = {
+        "tool_name": "Edit",
+        "tool_input": {
+            "file_path": str(target),
+            "new_string": "This guide explains how to use the new cache layer.",
+        },
+    }
+    completed = _run_hook_with_payload(payload)
+    assert _decision_from(completed) is None
+
+
+def test_multiedit_markdown_with_banned_term_is_denied(tmp_path: Path) -> None:
+    target = tmp_path / "notes.md"
+    payload = {
+        "tool_name": "MultiEdit",
+        "tool_input": {
+            "file_path": str(target),
+            "edits": [
+                {"old_string": "intro", "new_string": "This section reads cleanly."},
+                {"old_string": "body", "new_string": "Then we utilize the new cache."},
+            ],
+        },
+    }
+    completed = _run_hook_with_payload(payload)
+    assert _decision_from(completed) == "deny"
+
+
+def test_other_tool_is_ignored() -> None:
+    payload = {"tool_name": "Bash", "tool_input": {"command": "echo utilize"}}
+    completed = _run_hook_with_payload(payload)
+    assert _decision_from(completed) is None
+
+
+def test_software_allowlisted_term_is_not_flagged() -> None:
+    assert find_banned_terms("Run this command to start the worker.") == []
+
+
+def test_non_allowlisted_formal_term_still_flagged() -> None:
+    matched = find_banned_terms("Please utilize the cache now.")
+    assert any(term == "utilize" for term, _ in matched)
+
+
+def test_prose_slash_token_is_not_stripped_as_path() -> None:
+    assert "client/server" in strip_non_prose_regions("Use a client/server split here.")
+
+
+def test_real_file_path_is_still_stripped() -> None:
+    assert "initiate" not in strip_non_prose_regions("Edit src/initiate.py to wire it.")

package/hooks/blocking/test_pr_description_enforcer.py

@@ -225,6 +225,74 @@ def test_validate_blocks_vague_language() -> None:
     assert any("Vague language" in each_violation for each_violation in violations)
 
 
+def _has_vague_language_violation(all_violations: list[str]) -> bool:
+    return any("Vague language" in each_violation for each_violation in all_violations)
+
+
+def test_vague_language_inside_fenced_code_block_is_exempt() -> None:
+    body = (
+        "The allocator now bounds retries so a runaway request cannot exhaust the "
+        "connection pool under sustained load.\n\n"
+        "```bash\ngit commit -m \"fixed bug in parser\"\n```\n"
+    )
+    assert not _has_vague_language_violation(validate_pr_body(body))
+
+
+def test_vague_language_inside_inline_code_span_is_exempt() -> None:
+    body = (
+        "This change documents the historical commit message `fixed bug` referenced "
+        "in the changelog and rewrites the surrounding allocator narrative for clarity.\n"
+    )
+    assert not _has_vague_language_violation(validate_pr_body(body))
+
+
+def test_vague_language_inside_blockquote_line_is_exempt() -> None:
+    body = (
+        "> The reviewer wrote: minor changes were requested here.\n\n"
+        "The allocator rewrite removes the unbounded retry loop and adds a hard ceiling "
+        "so a single client cannot starve the pool.\n"
+    )
+    assert not _has_vague_language_violation(validate_pr_body(body))
+
+
+def test_vague_language_inside_markdown_table_is_exempt() -> None:
+    body = (
+        "The commit-message guide contrasts weak and strong messages so contributors "
+        "learn the difference before opening a pull request.\n\n"
+        "| Bad message | Good message |\n"
+        "| --- | --- |\n"
+        "| fixed bug | bound retry loop in allocator |\n"
+        "| update code | rename pool field to active_count |\n"
+    )
+    assert not _has_vague_language_violation(validate_pr_body(body))
+
+
+def test_vague_language_in_bare_prose_still_blocks() -> None:
+    body = (
+        "The allocator rewrite removes the unbounded retry loop and adds a hard "
+        "ceiling so a single client cannot starve the pool. Fixed bug in the parser.\n"
+    )
+    assert _has_vague_language_violation(validate_pr_body(body))
+
+
+def test_vague_language_inside_heading_is_exempt() -> None:
+    body = (
+        "## Fixed bug in the allocator\n\n"
+        "The allocator rewrite removes the unbounded retry loop and adds a hard "
+        "ceiling so a single client cannot starve the connection pool.\n"
+    )
+    assert not _has_vague_language_violation(validate_pr_body(body))
+
+
+def test_vague_language_in_single_pipe_prose_line_still_blocks() -> None:
+    body = (
+        "The allocator rewrite removes the unbounded retry loop and adds a hard "
+        "ceiling so a single client cannot starve the connection pool.\n\n"
+        "| fixed bug\n"
+    )
+    assert _has_vague_language_violation(validate_pr_body(body))
+
+
 def test_validate_blocks_short_body() -> None:
     violations = validate_pr_body("Too short.")
     assert any("substantive prose" in each_violation.lower() for each_violation in violations)

package/hooks/hooks.json

@@ -69,6 +69,11 @@
             "type": "command",
             "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/open_questions_in_plans_blocker.py",
             "timeout": 10
+          },
+          {
+            "type": "command",
+            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/plain_language_blocker.py",
+            "timeout": 10
           }
         ]
       },
@@ -171,6 +176,16 @@
             "timeout": 10
           }
         ]
+      },
+      {
+        "matcher": "AskUserQuestion",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/plain_language_blocker.py",
+            "timeout": 10
+          }
+        ]
       }
     ],
     "SessionStart": [