claude-dev-env 1.48.0 → 1.49.0

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": [

package/hooks/hooks_constants/plain_language_blocker_constants.py

@@ -0,0 +1,295 @@
+"""Configuration constants for the plain_language_blocker PreToolUse hook."""
+
+from __future__ import annotations
+
+import re
+
+REPLACEMENT_BY_TERM: dict[str, str] = {
+    "addressees are requested": "(omit), please",
+    "under the provisions of": "under",
+    "interpose no objection": "don't object",
+    "afford an opportunity": "allow, let",
+    "has a requirement for": "needs",
+    "is in consonance with": "agrees with, follows",
+    "not later than 10 may": "by 10 May, before 11 May",
+    "provides guidance for": "guides",
+    "successfully complete": "complete, pass",
+    "with the exception of": "except for",
+    "due to the fact that": "due to, since",
+    "effect modifications": "make changes",
+    "in view of the above": "so",
+    "adversely impact on": "hurt, set back",
+    "at the present time": "at present, now",
+    "not later than 1600": "by 1600",
+    "combat environment": "combat",
+    "in a timely manner": "on time, promptly",
+    "in accordance with": "by, following, per, under",
+    "in the near future": "shortly, soon",
+    "is responsible for": "(omit) handles",
+    "on a regular basis": "(omit)",
+    "until such time as": "until",
+    "during the period": "during",
+    "in the process of": "(omit)",
+    "with reference to": "about",
+    "as prescribed by": "in, under",
+    "in the amount of": "for",
+    "is applicable to": "applies to",
+    "is authorized to": "may",
+    "state-of-the-art": "latest",
+    "close proximity": "near",
+    "for a period of": "for",
+    "in an effort to": "to",
+    "in the event of": "if",
+    "it is essential": "must, need to",
+    "it is requested": "please, we request, I request",
+    "notwithstanding": "inspite of, still",
+    "the undersigned": "I",
+    "arrive onboard": "arrive",
+    "in relation to": "about, with, to",
+    "incumbent upon": "must",
+    "limited number": "limits",
+    "take action to": "(omit)",
+    "as a means of": "to",
+    "in order that": "for, so",
+    "pertaining to": "about, of, on",
+    "provided that": "if",
+    "this activity": "us, we",
+    "advantageous": "helpful",
+    "consequently": "so",
+    "in regard to": "about, concerning, on",
+    "remuneration": "pay, payment",
+    "set forth in": "in",
+    "subsequently": "after, later, then",
+    "the month of": "(omit)",
+    "a number of": "some",
+    "accordingly": "so",
+    "adjacent to": "next to",
+    "appreciable": "many",
+    "appropriate": "(omit), proper, right",
+    "approximate": "about",
+    "by means of": "by, with",
+    "comply with": "follow",
+    "consolidate": "combine, join, merge",
+    "constitutes": "is, forms, makes up",
+    "demonstrate": "prove, show",
+    "discontinue": "drop, stop",
+    "disseminate": "give, issue, pass, send",
+    "expeditious": "fast, quick",
+    "immediately": "at once",
+    "in addition": "also, besides, too",
+    "in order to": "to",
+    "inasmuch as": "since",
+    "methodology": "method",
+    "necessitate": "cause, need",
+    "participate": "take part",
+    "practicable": "practical",
+    "proficiency": "skill",
+    "pursuant to": "by, following, per, under",
+    "relative to": "about, on",
+    "requirement": "need",
+    "substantial": "large, much",
+    "time period": "(either one)",
+    "utilization": "use",
+    "your office": "you",
+    "a and/or b": "a or b or both",
+    "accomplish": "carry out, do",
+    "additional": "added, more, other",
+    "addressees": "you",
+    "anticipate": "expect",
+    "assistance": "aid, help",
+    "be advised": "(omit)",
+    "capability": "ability",
+    "concerning": "about, on",
+    "equipments": "equipment",
+    "expiration": "end",
+    "facilitate": "ease, help",
+    "frequently": "often",
+    "heretofore": "until now",
+    "in lieu of": "instead",
+    "in view of": "since",
+    "indication": "sign",
+    "inter alia": "(omit)",
+    "it appears": "seems",
+    "parameters": "limits",
+    "previously": "before",
+    "prioritize": "rank",
+    "promulgate": "issue, publish",
+    "represents": "is",
+    "similar to": "like",
+    "subsequent": "later, next",
+    "sufficient": "enough",
+    "the use of": "(omit)",
+    "accompany": "go with",
+    "ascertain": "find out, learn",
+    "component": "part",
+    "currently": "(omit), now",
+    "designate": "appoint, choose, name",
+    "determine": "decide, figure, find",
+    "eliminate": "cut, drop, end",
+    "encounter": "meet",
+    "enumerate": "count",
+    "equitable": "fair",
+    "establish": "set up, prove, show",
+    "evidenced": "showed",
+    "expertise": "ability",
+    "failed to": "didn't",
+    "identical": "same",
+    "implement": "carry out, start",
+    "inception": "start",
+    "interface": "meet, work with",
+    "magnitude": "size",
+    "objective": "aim, goal",
+    "regarding": "about, of, on",
+    "remainder": "rest",
+    "selection": "choice",
+    "terminate": "end, stop",
+    "there are": "(omit)",
+    "therefore": "so",
+    "witnessed": "saw",
+    "accorded": "given",
+    "accurate": "correct, exact, right",
+    "aircraft": "plane",
+    "allocate": "divide",
+    "apparent": "clear, plain",
+    "combined": "joint",
+    "commence": "begin, start",
+    "comprise": "form, include, make up",
+    "contains": "has",
+    "disclose": "show",
+    "endeavor": "try",
+    "expedite": "hasten, speed up",
+    "feasible": "can be done, workable",
+    "finalize": "complete, finish",
+    "function": "act, role, work",
+    "herewith": "below, here",
+    "identify": "find, name, show",
+    "impacted": "affected, changed",
+    "indicate": "show, write down",
+    "initiate": "start",
+    "maintain": "keep, support",
+    "minimize": "decrease, method",
+    "numerous": "many",
+    "obligate": "bind, compel",
+    "preclude": "prevent",
+    "previous": "earlier",
+    "prior to": "before",
+    "purchase": "buy",
+    "relocate": "move",
+    "there is": "(omit)",
+    "transmit": "send",
+    "validate": "confirm",
+    "address": "discuss",
+    "attempt": "try",
+    "benefit": "help",
+    "command": "us, we",
+    "convene": "meet",
+    "evident": "clear",
+    "exhibit": "show",
+    "females": "women",
+    "forfeit": "give up, lose",
+    "forward": "send",
+    "furnish": "give, send",
+    "however": "but",
+    "initial": "first",
+    "liaison": "discussion",
+    "maximum": "greatest, largest, most",
+    "minimum": "least, smallest",
+    "monitor": "check, watch",
+    "observe": "see",
+    "operate": "run, use, work",
+    "optimum": "best, greatest, most",
+    "perform": "do",
+    "portion": "part",
+    "possess": "have, own",
+    "proceed": "do, go ahead, try",
+    "procure": "(omit)",
+    "provide": "give, offer, say",
+    "reflect": "say, show",
+    "request": "ask",
+    "require": "must, need",
+    "solicit": "ask for, request",
+    "subject": "the, this, your",
+    "therein": "there",
+    "thereof": "its, their",
+    "utilize": "use",
+    "warrant": "call for, permit",
+    "whereas": "because, since",
+    "accrue": "add, gain",
+    "advise": "recommend, tell",
+    "assist": "aid, help",
+    "attain": "meet",
+    "caveat": "warning",
+    "delete": "cut, drop",
+    "depart": "leave",
+    "desire": "want, wish",
+    "employ": "use",
+    "ensure": "make sure",
+    "expend": "spend",
+    "herein": "here",
+    "modify": "change",
+    "notify": "let know, tell",
+    "option": "choice, way",
+    "permit": "let",
+    "remain": "stay",
+    "render": "give, make",
+    "reside": "live",
+    "retain": "keep",
+    "submit": "give, send",
+    "timely": "prompt",
+    "viable": "practical, workable",
+    "elect": "choose, pick",
+    "it is": "(omit)",
+    "deem": "believe, consider, think",
+    "said": "the, this, that",
+    "same": "the, this, that",
+    "such": "the, this, that",
+    "type": "(omit)",
+    "vice": "instead of, versus",
+}
+
+ALL_TERM_PATTERNS: list[tuple[re.Pattern[str], str]] = [
+    (re.compile(r"\b" + re.escape(each_term) + r"\b", re.IGNORECASE), each_replacement)
+    for each_term, each_replacement in REPLACEMENT_BY_TERM.items()
+]
+
+ALL_SOFTWARE_TERMS: frozenset[str] = frozenset(
+    {
+        "command",
+        "function",
+        "address",
+        "parameters",
+        "interface",
+        "component",
+        "monitor",
+        "request",
+        "validate",
+        "however",
+        "forward",
+        "subject",
+        "same",
+        "such",
+        "said",
+        "type",
+        "it is",
+        "there is",
+        "there are",
+    }
+)
+
+FENCED_CODE_BLOCK_PATTERN: re.Pattern[str] = re.compile(r"```[\s\S]*?```", re.MULTILINE)
+INLINE_CODE_PATTERN: re.Pattern[str] = re.compile(r"`[^`]+`")
+BLOCKQUOTE_LINE_PATTERN: re.Pattern[str] = re.compile(r"^\s*>.*$", re.MULTILINE)
+URL_PATTERN: re.Pattern[str] = re.compile(r"https?://\S+", re.IGNORECASE)
+FILE_PATH_PATTERN: re.Pattern[str] = re.compile(
+    r"(?<![\w/\\])(?:[A-Za-z]:[\\/]|~?[\\/]|\.{1,2}[\\/])(?:[\w.\-]+[\\/])*[\w.\-]+"
+    r"|(?:[\w.\-]+[\\/])+[\w.\-]+\.[A-Za-z0-9]+"
+)
+
+MARKDOWN_EXTENSION: str = ".md"
+ASK_USER_QUESTION_TOOL_NAME: str = "AskUserQuestion"
+ALL_WRITE_EDIT_TOOL_NAMES: frozenset[str] = frozenset({"Write", "Edit", "MultiEdit"})
+
+USER_FACING_PLAIN_LANGUAGE_NOTICE: str = (
+    "Plain-language check: replace each flagged formal word with the simpler "
+    "word named in the reason."
+)

package/hooks/hooks_constants/pr_description_enforcer_constants.py

@@ -19,6 +19,8 @@ HEADING_LINE_PATTERN: re.Pattern[str] = re.compile(r"^#+[ \t].*$", re.MULTILINE)
 BOLD_PAIR_PATTERN: re.Pattern[str] = re.compile(r"\*\*([^*]+?)\*\*")
 BULLET_MARKER_PATTERN: re.Pattern[str] = re.compile(r"^\s*[-*+]\s+", re.MULTILINE)
 BLOCKQUOTE_MARKER_PATTERN: re.Pattern[str] = re.compile(r"^\s*>\s+", re.MULTILINE)
+BLOCKQUOTE_LINE_PATTERN: re.Pattern[str] = re.compile(r"^\s*>.*$", re.MULTILINE)
+TABLE_ROW_LINE_PATTERN: re.Pattern[str] = re.compile(r"^\s*\|.*\|.*$", re.MULTILINE)
 LINK_TEXT_PATTERN: re.Pattern[str] = re.compile(r"\[([^\]]+)\]\([^)]+\)")
 WHITESPACE_RUN_PATTERN: re.Pattern[str] = re.compile(r"\s+")
 
@@ -115,6 +117,7 @@ __all__ = [
     "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",
@@ -147,6 +150,7 @@ __all__ = [
     "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",

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "claude-dev-env",
-    "version": "1.48.0",
+    "version": "1.49.0",
     "description": "Claude Code development standards — rules, hooks, agents, commands, and skills",
     "type": "module",
     "bin": {

package/rules/plain-language.md

@@ -2,6 +2,8 @@
 
 **When this applies:** All prose you write — chat responses, `AskUserQuestion` questions and options, documentation and Markdown, PR and issue bodies, and commit messages. Anything a person reads.
 
+**Hook enforcement:** `plain_language_blocker` (PreToolUse on `AskUserQuestion` and on Write|Edit|MultiEdit of `.md` targets) blocks a heavy word and names the everyday word to swap in. Code fences, inline code, blockquotes, URLs, and file paths are skipped so exact identifiers stay untouched. See `hooks.json` for registration.
+
 ## Rule
 
 Write so the reader understands it on the first pass, without hunting for extra context and without wading through more than the point requires. Favor everyday words, short sentences, and concrete phrasing. This is **plain language** (ISO 24495-1:2023; U.S. Plain Writing Act of 2010) — clear writing, not dumbed-down writing.