claude-dev-env 1.48.0 → 1.49.1

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.1",
     "description": "Claude Code development standards — rules, hooks, agents, commands, and skills",
     "type": "module",
     "bin": {
@@ -20,6 +20,7 @@
         "system-prompts/",
         "scripts/",
         "_shared/",
+        "audit-rubrics/",
         "CLAUDE.md"
     ],
     "keywords": [

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.

package/skills/bugteam/reference/teardown-publish-permissions.md

@@ -2,7 +2,12 @@
 
 ## Utility scripts (progressive disclosure)
 
-Fragile or repeatable shell sequences belong in `_shared/pr-loop/scripts/`. Bugteam-specific scripts (e.g. revoke, see Step 5) live in the skill-local [`scripts/`](../scripts/) directory. Anthropic: [Progressive disclosure patterns](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices#progressive-disclosure-patterns) — utility scripts are **executed**, not loaded into context as primary reading. Shared-script inventory: [`../../../_shared/pr-loop/scripts/README.md`](../../../_shared/pr-loop/scripts/README.md). Bugteam-script inventory: [`../scripts/README.md`](../scripts/README.md). Gate-only merge-base / diff semantics: [`../../../_shared/pr-loop/code-rules-gate.md`](../../../_shared/pr-loop/code-rules-gate.md).
+Fragile or repeatable shell sequences live in one of two shared script directories. Match the reference depth to the directory:
+
+- **Package-root** [`_shared/pr-loop/scripts/`](../../../_shared/pr-loop/scripts/) holds `code_rules_gate.py`, `preflight.py`, `post_audit_thread.py`, and the permission helpers. Reference it as `../../../_shared/…` in markdown and `${CLAUDE_SKILL_DIR}/../../_shared/…` at runtime (resolves to `~/.claude/_shared/`). Inventory: [`../../../_shared/pr-loop/scripts/README.md`](../../../_shared/pr-loop/scripts/README.md).
+- **Skill-tree** [`skills/_shared/pr-loop/scripts/`](../../_shared/pr-loop/scripts/) holds `teardown_worktrees.py`, `build_audit_prompt.py`, `build_fix_prompt.py`, `init_loop_state.py`, `write_audit_outcomes.py`, `write_fix_outcomes.py`, and `_path_resolver.py`. Reference it as `../../_shared/…` in markdown and `${CLAUDE_SKILL_DIR}/../_shared/…` at runtime (resolves to `~/.claude/skills/_shared/`).
+
+Bugteam-specific scripts (e.g. revoke, see Step 5) live in the skill-local [`scripts/`](../scripts/) directory. Anthropic: [Progressive disclosure patterns](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices#progressive-disclosure-patterns) — utility scripts are **executed**, not loaded into context as primary reading. Bugteam-script inventory: [`../scripts/README.md`](../scripts/README.md). Gate-only merge-base / diff semantics: [`../../../_shared/pr-loop/code-rules-gate.md`](../../../_shared/pr-loop/code-rules-gate.md).
 
 ### Pre-flight (recommended before Step 0)
 
@@ -19,7 +24,7 @@ When the cycle exits (any reason), run these steps in order from **this** sessio
    directory (Windows-safe `shutil.rmtree`):
 
    ```bash
-   python "${CLAUDE_SKILL_DIR}/../../_shared/pr-loop/scripts/teardown_worktrees.py" \
+   python "${CLAUDE_SKILL_DIR}/../_shared/pr-loop/scripts/teardown_worktrees.py" \
      --run-temp-dir "<run_temp_dir>" \
      --all-pr-jsons '<json array of {number, owner, repo}>'
    ```