claude-dev-env 1.50.4 → 1.52.0

package/hooks/blocking/test_tdd_enforcer.py

@@ -690,3 +690,402 @@ def test_should_deny_code_rules_edit_when_split_family_sibling_is_stale(
     completed = _run_hook_with_payload(payload)
 
     assert _decision_from(completed) == "deny"
+
+
+def test_should_offer_nested_package_mirroring_candidate_for_subpackage_module(
+    tmp_path: Path,
+) -> None:
+    sandbox = _sandbox(tmp_path)
+    package_root = sandbox / "pkg"
+    subpackage_directory = package_root / "services" / "mouse_movement"
+    subpackage_directory.mkdir(parents=True)
+    (package_root / "tests").mkdir()
+    production_module = subpackage_directory / "tremor.py"
+
+    all_candidates = _PRODUCTION_MODULE.candidate_test_paths_for(production_module)
+
+    assert package_root / "tests" / "services" / "test_tremor.py" in all_candidates
+    assert (
+        package_root / "tests" / "services" / "mouse_movement" / "test_tremor.py"
+        in all_candidates
+    )
+
+
+def test_should_offer_flat_candidate_alongside_nested_candidates(
+    tmp_path: Path,
+) -> None:
+    sandbox = _sandbox(tmp_path)
+    package_root = sandbox / "pkg"
+    subpackage_directory = package_root / "services" / "mouse_movement"
+    subpackage_directory.mkdir(parents=True)
+    (package_root / "tests").mkdir()
+    production_module = subpackage_directory / "tremor.py"
+
+    all_candidates = _PRODUCTION_MODULE.candidate_test_paths_for(production_module)
+
+    assert package_root / "tests" / "test_tremor.py" in all_candidates
+    assert (
+        package_root / "tests" / "services" / "mouse_movement" / "test_tremor.py"
+        in all_candidates
+    )
+
+
+def test_should_allow_write_when_nested_package_mirroring_test_is_fresh(
+    tmp_path: Path,
+) -> None:
+    sandbox = _sandbox(tmp_path)
+    package_root = sandbox / "pkg"
+    subpackage_directory = package_root / "services" / "mouse_movement"
+    subpackage_directory.mkdir(parents=True)
+    nested_tests_directory = package_root / "tests" / "services" / "mouse_movement"
+    nested_tests_directory.mkdir(parents=True)
+    production_module = subpackage_directory / "tremor.py"
+    production_module.write_text("def jitter(): pass\n")
+    nested_test = nested_tests_directory / "test_tremor.py"
+    nested_test.write_text("def test_jitter(): pass\n")
+
+    completed = _run_hook_with_payload(_make_write_payload(production_module))
+
+    assert _decision_from(completed) == "allow"
+
+
+def test_should_collect_tests_directories_from_every_ancestor_up_to_repo_boundary(
+    tmp_path: Path,
+) -> None:
+    sandbox = _sandbox(tmp_path)
+    package_root = sandbox / "pkg"
+    subpackage_directory = package_root / "services"
+    subpackage_directory.mkdir(parents=True)
+    (package_root / "tests").mkdir()
+    (subpackage_directory / "tests").mkdir()
+
+    all_pairs = _PRODUCTION_MODULE._ancestor_tests_directories(subpackage_directory)
+
+    collected_tests_directories = [each_tests_directory for _, each_tests_directory in all_pairs]
+    assert subpackage_directory / "tests" in collected_tests_directories
+    assert package_root / "tests" in collected_tests_directories
+
+
+def test_ancestor_tests_walk_stops_at_repo_boundary(tmp_path: Path) -> None:
+    outer_tests_directory = tmp_path / "tests"
+    outer_tests_directory.mkdir()
+    sandbox = _sandbox(tmp_path)
+    package_directory = sandbox / "pkg"
+    package_directory.mkdir()
+
+    all_pairs = _PRODUCTION_MODULE._ancestor_tests_directories(package_directory)
+
+    collected_tests_directories = [each_tests_directory for _, each_tests_directory in all_pairs]
+    assert outer_tests_directory not in collected_tests_directories
+
+
+def test_ancestor_tests_walk_honors_parent_walk_limit(tmp_path: Path) -> None:
+    walk_limit = _PRODUCTION_MODULE._parent_walk_limit()
+    deep_directory = tmp_path
+    for each_level_index in range(walk_limit + 2):
+        deep_directory = deep_directory / f"level_{each_level_index}"
+    deep_directory.mkdir(parents=True)
+    top_tests_directory = tmp_path / "tests"
+    top_tests_directory.mkdir()
+
+    all_pairs = _PRODUCTION_MODULE._ancestor_tests_directories(deep_directory)
+
+    collected_tests_directories = [each_tests_directory for _, each_tests_directory in all_pairs]
+    assert top_tests_directory not in collected_tests_directories
+
+
+def test_should_deny_edit_that_swaps_an_import_target(tmp_path: Path) -> None:
+    sandbox = _sandbox(tmp_path)
+    production_module = sandbox / "orders.py"
+    production_module.write_text("import os\n\ndef fulfill(): pass\n")
+
+    completed = _run_hook_with_payload(
+        _make_edit_payload(
+            production_module,
+            old_string="import os",
+            new_string="import sys",
+        )
+    )
+
+    assert _decision_from(completed) == "deny"
+
+
+def test_should_allow_edit_that_removes_an_import_statement(tmp_path: Path) -> None:
+    sandbox = _sandbox(tmp_path)
+    production_module = sandbox / "orders.py"
+    production_module.write_text("import os\n\ndef fulfill(): pass\n")
+
+    completed = _run_hook_with_payload(
+        _make_edit_payload(
+            production_module,
+            old_string="import os\n",
+            new_string="",
+        )
+    )
+
+    assert _decision_from(completed) == "allow"
+
+
+def test_should_allow_multiedit_when_every_pair_removes_an_import(tmp_path: Path) -> None:
+    sandbox = _sandbox(tmp_path)
+    production_module = sandbox / "orders.py"
+    production_module.write_text("import os\nimport json\nimport time\n\ndef fulfill(): pass\n")
+
+    completed = _run_hook_with_payload(
+        _make_multiedit_payload(
+            production_module,
+            edits=[
+                {"old_string": "import os\n", "new_string": ""},
+                {"old_string": "import json\n", "new_string": ""},
+            ],
+        )
+    )
+
+    assert _decision_from(completed) == "allow"
+
+
+def test_should_deny_multiedit_when_one_pair_is_not_import_only(tmp_path: Path) -> None:
+    sandbox = _sandbox(tmp_path)
+    production_module = sandbox / "orders.py"
+    production_module.write_text("import os\n\ndef fulfill(): pass\n")
+
+    completed = _run_hook_with_payload(
+        _make_multiedit_payload(
+            production_module,
+            edits=[
+                {"old_string": "import os", "new_string": "import sys"},
+                {
+                    "old_string": "def fulfill(): pass",
+                    "new_string": "def fulfill(): return 1",
+                },
+            ],
+        )
+    )
+
+    assert _decision_from(completed) == "deny"
+
+
+def test_should_not_exempt_write_with_behavior_under_import_only_rule(
+    tmp_path: Path,
+) -> None:
+    sandbox = _sandbox(tmp_path)
+    production_module = sandbox / "orders.py"
+    write_content_with_behavior = "import os\n\ndef fulfill(): return os.getpid()\n"
+
+    completed = _run_hook_with_payload(
+        _make_write_payload(production_module, write_content_with_behavior)
+    )
+
+    assert _decision_from(completed) == "deny"
+
+
+def test_should_deny_behavior_edit_without_a_fresh_candidate_test(tmp_path: Path) -> None:
+    sandbox = _sandbox(tmp_path)
+    production_module = sandbox / "orders.py"
+    production_module.write_text("def fulfill(): pass\n")
+
+    completed = _run_hook_with_payload(
+        _make_edit_payload(
+            production_module,
+            old_string="def fulfill(): pass",
+            new_string="def fulfill(): return 1",
+        )
+    )
+
+    assert _decision_from(completed) == "deny"
+
+
+def test_should_deny_edit_of_import_text_inside_a_string_literal(tmp_path: Path) -> None:
+    sandbox = _sandbox(tmp_path)
+    production_module = sandbox / "orders.py"
+    production_module.write_text('banner = "import os is great"\n\ndef fulfill(): return banner\n')
+
+    completed = _run_hook_with_payload(
+        _make_edit_payload(
+            production_module,
+            old_string="import os",
+            new_string="import sys",
+        )
+    )
+
+    assert _decision_from(completed) == "deny"
+
+
+def test_should_allow_import_reorder_when_old_string_carries_context_lines(
+    tmp_path: Path,
+) -> None:
+    sandbox = _sandbox(tmp_path)
+    production_module = sandbox / "orders.py"
+    production_module.write_text("import os\nimport sys\n\ndef fulfill(): pass\n")
+
+    completed = _run_hook_with_payload(
+        _make_edit_payload(
+            production_module,
+            old_string="import os\nimport sys\n\ndef fulfill(): pass",
+            new_string="import sys\nimport os\n\ndef fulfill(): pass",
+        )
+    )
+
+    assert _decision_from(completed) == "allow"
+
+
+def test_should_allow_import_only_edit_after_a_constants_assignment(tmp_path: Path) -> None:
+    sandbox = _sandbox(tmp_path)
+    production_module = sandbox / "orders.py"
+    production_module.write_text("import os\nimport sys\n\nMAX_ORDERS = 5\n\ndef fulfill(): pass\n")
+
+    completed = _run_hook_with_payload(
+        _make_edit_payload(
+            production_module,
+            old_string="import os\n",
+            new_string="",
+        )
+    )
+
+    assert _decision_from(completed) == "allow"
+
+
+def test_should_deny_replace_all_edit_that_rewrites_call_sites(tmp_path: Path) -> None:
+    sandbox = _sandbox(tmp_path)
+    production_module = sandbox / "orders.py"
+    production_module.write_text("import json\n\ndef parse(line): return json.loads(line)\n")
+
+    completed = _run_hook_with_payload(
+        {
+            "tool_name": "Edit",
+            "tool_input": {
+                "file_path": str(production_module),
+                "old_string": "json",
+                "new_string": "pickle",
+                "replace_all": True,
+            },
+        }
+    )
+
+    assert _decision_from(completed) == "deny"
+
+
+def test_should_allow_edit_that_reorders_import_statements(tmp_path: Path) -> None:
+    sandbox = _sandbox(tmp_path)
+    production_module = sandbox / "orders.py"
+    production_module.write_text("import os\nimport sys\n\ndef fulfill(): pass\n")
+
+    completed = _run_hook_with_payload(
+        _make_edit_payload(
+            production_module,
+            old_string="import os\nimport sys",
+            new_string="import sys\nimport os",
+        )
+    )
+
+    assert _decision_from(completed) == "allow"
+
+
+def test_should_deny_edit_that_retargets_an_import_source(tmp_path: Path) -> None:
+    sandbox = _sandbox(tmp_path)
+    production_module = sandbox / "orders.py"
+    production_module.write_text("from fast import compute\n\ndef run(): return compute()\n")
+
+    completed = _run_hook_with_payload(
+        _make_edit_payload(
+            production_module,
+            old_string="from fast import compute",
+            new_string="from slow import compute",
+        )
+    )
+
+    assert _decision_from(completed) == "deny"
+
+
+def test_should_deny_edit_that_adds_a_future_import(tmp_path: Path) -> None:
+    sandbox = _sandbox(tmp_path)
+    production_module = sandbox / "orders.py"
+    production_module.write_text("import os\n\ndef fulfill(): return os.getpid()\n")
+
+    completed = _run_hook_with_payload(
+        _make_edit_payload(
+            production_module,
+            old_string="import os",
+            new_string="from __future__ import annotations\nimport os",
+        )
+    )
+
+    assert _decision_from(completed) == "deny"
+
+
+def test_should_deny_multiedit_with_an_empty_edits_list(tmp_path: Path) -> None:
+    sandbox = _sandbox(tmp_path)
+    production_module = sandbox / "orders.py"
+    production_module.write_text("import os\n\ndef fulfill(): return os.getpid()\n")
+
+    completed = _run_hook_with_payload(
+        _make_multiedit_payload(production_module, edits=[])
+    )
+
+    assert _decision_from(completed) == "deny"
+
+
+def test_should_deny_edit_that_removes_a_future_import(tmp_path: Path) -> None:
+    sandbox = _sandbox(tmp_path)
+    production_module = sandbox / "orders.py"
+    production_module.write_text(
+        "from __future__ import annotations\nimport os\n\ndef fulfill(): return os.getpid()\n"
+    )
+
+    completed = _run_hook_with_payload(
+        _make_edit_payload(
+            production_module,
+            old_string="from __future__ import annotations\n",
+            new_string="",
+        )
+    )
+
+    assert _decision_from(completed) == "deny"
+
+
+def test_should_deny_edit_that_adds_an_import(tmp_path: Path) -> None:
+    sandbox = _sandbox(tmp_path)
+    production_module = sandbox / "orders.py"
+    production_module.write_text("import os\n\ndef fulfill(): pass\n")
+
+    completed = _run_hook_with_payload(
+        _make_edit_payload(
+            production_module,
+            old_string="import os",
+            new_string="import os\nimport sys",
+        )
+    )
+
+    assert _decision_from(completed) == "deny"
+
+
+def test_should_deny_edit_that_duplicates_an_import(tmp_path: Path) -> None:
+    sandbox = _sandbox(tmp_path)
+    production_module = sandbox / "orders.py"
+    production_module.write_text("import os\n\ndef fulfill(): pass\n")
+
+    completed = _run_hook_with_payload(
+        _make_edit_payload(
+            production_module,
+            old_string="import os",
+            new_string="import os\nimport os",
+        )
+    )
+
+    assert _decision_from(completed) == "deny"
+
+
+def test_should_deny_changing_a_future_import_on_a_constants_only_file(tmp_path: Path) -> None:
+    sandbox = _sandbox(tmp_path)
+    production_module = sandbox / "orders.py"
+    production_module.write_text("from __future__ import annotations\nMAX_ORDERS = 5\n")
+
+    completed = _run_hook_with_payload(
+        _make_edit_payload(
+            production_module,
+            old_string="from __future__ import annotations",
+            new_string="from __future__ import division",
+        )
+    )
+
+    assert _decision_from(completed) == "deny"

package/hooks/hooks.json

@@ -2,16 +2,6 @@
   "description": "Code standards enforcement, safety guards, and development workflow hooks",
   "hooks": {
     "PreToolUse": [
-      {
-        "matcher": "Grep|Search",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/content_search_to_zoekt_redirector.py",
-            "timeout": 10
-          }
-        ]
-      },
       {
         "matcher": "Write|Edit",
         "hooks": [
@@ -130,11 +120,6 @@
             "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/convergence_gate_blocker.py",
             "timeout": 15
           },
-          {
-            "type": "command",
-            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/content_search_to_zoekt_redirector.py",
-            "timeout": 10
-          },
           {
             "type": "command",
             "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/windows_rmtree_blocker.py",

package/hooks/hooks_constants/code_rules_enforcer_constants.py

@@ -124,6 +124,11 @@ FUNCTION_LENGTH_BLOCKING_MESSAGE_SUFFIX: str = (
     "function review hint)"
 )
 
+PRECHECK_USAGE_EXIT_CODE: int = 2
+PRECHECK_USAGE_MESSAGE: str = (
+    "usage: code_rules_enforcer.py --check <candidate> [--as <target>]\n"
+)
+
 BANNED_NOUN_SPAN_FRAGMENT_TEMPLATE: str = (
     "(binding span at line {definition_line}, spanning {line_span} lines)"
 )

package/package.json

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

package/rules/ask-user-question-required.md

@@ -1,44 +1,5 @@
 # AskUserQuestion Required
 
-**When this applies:** Any time you would ask the user a question during discovery, scoping, or implementation planning — after the `verify-before-asking` decision checklist confirms the question genuinely belongs to the user.
+Route every user-directed question through the `AskUserQuestion` tool — never a plain-text question in a response's final paragraph. Structure: concise `question`, `header` of 12 chars or fewer, 2-4 options (the UI adds the "Other" fallback), `multiSelect` only when choices genuinely combine.
 
-## Rule
-
-Route every user-directed question through the `AskUserQuestion` tool. Embedded plain-text questions in the final paragraph of an assistant message are blocked by a Stop hook, and the response must be re-output with the ask moved into an `AskUserQuestion` tool call.
-
-## Detection Criteria
-
-The `question_to_user_enforcer` Stop hook inspects the last non-empty paragraph of the response after stripping fenced code blocks, inline code (backticks), and blockquoted lines (`> …`). The response is blocked when either signal is present:
-
-- The final paragraph's last sentence ends with a question mark.
-- The final paragraph contains any of these preamble phrases (case-insensitive, word-boundary matched): `would you like`, `should I`, `do you want`, `which would you prefer`, `let me know if`, `let me know which`, `let me know whether`, `please confirm`, `please let me know`, `want me to`.
-
-## Acceptable Plain-Text Question Patterns
-
-These remain allowed and do not trigger the hook:
-
-- **Rhetorical questions answered in the same paragraph.** `"What happens if the queue is empty? The handler short-circuits cleanly."` The question frames its own answer; the reader never has to respond.
-- **Questions inside code, diffs, or documentation excerpts.** Code fences, inline backticks, and `>` blockquotes are stripped before detection. Quoting a GitHub issue title, a user's prior message, or a log line inside a blockquote is fine.
-- **Middle-paragraph questions when the closing paragraph is declarative.** Only the final paragraph is scanned.
-
-## AskUserQuestion Structure
-
-When a question is genuinely for the user, call the tool with:
-
-- A concise `question` string stating what is needed.
-- A `header` of twelve characters or fewer summarizing the decision.
-- Two to four `options`, each with a short `label` the user can pick. An "Other" free-text fallback is already provided by the UI; do not add one manually.
-- `multiSelect: false` unless the user can genuinely combine choices.
-
-## Why
-
-- **Structured options reduce re-reading friction.** The user sees labeled choices directly rather than scanning prose for the ask.
-- **Transcript clarity.** Tool-use entries are easy to locate in the JSONL transcript; prose questions disappear into the response text.
-- **Reduced drift.** Claude's next turn cannot move past an unanswered structured question; prose questions can be silently bypassed.
-
-## Enforcement
-
-- Hook: `packages/claude-dev-env/hooks/blocking/question_to_user_enforcer.py`, registered on the `Stop` matcher in `packages/claude-dev-env/hooks/hooks.json`.
-- Loop prevention: the hook honors Claude Code's `stop_hook_active` flag and does not re-block on retry.
-- User-facing notice: `USER_FACING_ASKUSERQUESTION_NOTICE` in `packages/claude-dev-env/hooks/hooks_constants/messages.py`.
-- Related rule: `packages/claude-dev-env/rules/verify-before-asking.md` gates whether the question belongs to the user in the first place.
+The `question_to_user_enforcer` Stop hook blocks a response whose final paragraph (after stripping code fences, inline code, and blockquotes) ends in a question mark or contains ask-phrases ("would you like", "should I", "let me know if", ...). Rhetorical questions answered in the same paragraph, and questions inside code or blockquotes, pass. `verify-before-asking` gates whether the question belongs to the user at all.

package/rules/confirm-implementation-forks.md

@@ -1,48 +1,7 @@
 # Confirm Implementation Forks
 
-**When this applies:** During planning or implementation, whenever two or more viable paths would satisfy the goal and the choice changes the deliverable — its scope, completeness, the work it defers, the dependencies it adds, or a contract that is hard to reverse.
+At a material fork — two or more viable paths that change the deliverable's 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 is itself a fork to surface, never a silent default.
 
-## Rule
+How to ask: plain language, one option per path with its tradeoff in the description, recommended path listed first and flagged "(Recommended)", hold edits to the forked area until the answer arrives.
 
-At a material fork, stop and ask the user which path to take through `AskUserQuestion`. Do not silently pick one path and proceed. Present each path as an option whose description states its tradeoff: what it delivers, what it defers, the follow-up cost it creates, and how reversible it is. Begin implementing only after the user chooses.
-
-A fork is **material** when any of these hold:
-
-- The paths produce different deliverables, scope, or completeness against the stated target.
-- One path defers work — a stub, placeholder, or partial wiring — that creates a follow-up task or hidden debt, while another path completes the work in the same change.
-- The paths diverge on something hard to reverse: architecture, a public API or contract, a data schema, or a newly added dependency.
-- The choice trades off something the user has a stake in: speed against completeness, a scope cut against full coverage, or a shortcut against the original plan's target.
-
-When one path quietly drops part of the requested outcome or leaves work for later, that gap is itself the fork — surface it rather than choosing the smaller deliverable on the user's behalf.
-
-## Not a fork — just proceed
-
-- Trivially reversible, internal-only choices with no deliverable impact (a local variable name, the layout of a private helper, one of two equivalent standard-library calls).
-- The codebase, the user's stated goal, or an existing rule already determines the answer — follow it (see `verify-before-asking`), and do not manufacture a choice.
-- Only one path is actually viable — implement it; a false choice wastes a round-trip.
-
-## How to ask
-
-- Write the question and every option in plain language — short, common words and concrete phrasing a non-expert grasps on first read. Spell out or drop jargon, internal names, and acronyms the user has not already used.
-- Give just enough to decide (progressive disclosure): state each path's outcome and its main tradeoff in a sentence or two, and hold deeper detail in reserve for when the user asks. Do not paste code, long file lists, or background the choice does not need — extra information raises the reader's effort without improving the decision.
-- One option per path. Keep each `label` short; put the tradeoff in the `description`.
-- Recommend the path that best meets the user's stated target and list it first, flagged as recommended (per the AskUserQuestion directive in `CLAUDE.md`).
-- Hold all edits to the forked area until the answer arrives. Continue unrelated, unambiguous work if it helps.
-
-## Examples
-
-**Wrong:** Reach a point where the feature can be completed or partially wired with a placeholder, pick the placeholder, and move on — leaving the real implementation as an unrequested follow-up.
-**Right:** Ask: "Complete the feature in this change, or land a placeholder and track the rest as a follow-up?" with each option's cost stated, and wait for the choice.
-
-**Wrong:** Add a third-party dependency to solve a problem a few lines of existing code could handle, without flagging it.
-**Right:** Ask whether to add the dependency or hand-roll the small helper, naming the maintenance and footprint tradeoff.
-
-## Why
-
-A fork is a scope-or-direction decision the user holds a stake in. Choosing silently commits their effort and tokens to a path they may not want, and a deferred-work path can hide a follow-up the user never agreed to. Surfacing the fork once, with the tradeoffs visible, costs one round-trip and avoids rework.
-
-## Relationship to other rules
-
-- **verify-before-asking** gates *whether* a question belongs to the user; a material fork is a judgment or scope call that always does. Resolve anything the codebase can answer first, then ask only about the genuine choice.
-- **conservative-action** governs *whether* to act when intent is ambiguous; this rule names a specific trigger — divergent viable paths — that demands a choice before acting.
-- **ask-user-question-required** governs *how* to ask: route the fork through `AskUserQuestion`, never a plain-text question.
+Not a fork (just proceed): trivially reversible internal-only choices, anything the codebase / stated goal / an existing rule already determines (see `verify-before-asking`), or a single viable path.

package/rules/gh-body-file.md

@@ -1,81 +1,5 @@
 # gh --body-file Rule
 
-**MCP note:** MCP tools accept `body` as a structured string parameter and are unaffected by shell quoting. This rule applies to `gh` CLI invocations issued through the `Bash` tool.
+Every `gh` command carrying markdown body content (`gh pr create/edit/comment/review`, `gh issue create/edit/comment`) uses `--body-file <path>` with a temp file — never a `--body`/`-b` string, where backticks land on GitHub as literal `\``. Write the temp file BOM-free: `[IO.File]::WriteAllText($bodyPath, $body, [Text.UTF8Encoding]::new($false))`. MCP GitHub tools take `body` as a structured parameter and are unaffected.
 
-**Root cause:** In shell-invoked `gh` command contexts used in this repo, passing markdown body text via `--body "..."` can cause backticks to be stored as `\`` literals on GitHub instead of rendering as markdown code formatting. Quoting and escaping rules vary by execution environment (Bash, PowerShell, CMD), but the failure mode is the same: inline code and code fences can be broken in issues, PR descriptions, comments, and reviews written this way.
-
-**Rule:** All `gh` commands that include markdown body content **must** use `--body-file <path>` with a temp file. Never pass body text as a string argument to `--body` or its shorthand `-b`.
-
-## Affected subcommands
-
-- `gh issue create`
-- `gh issue edit`
-- `gh issue comment`
-- `gh pr create`
-- `gh pr edit`
-- `gh pr comment`
-- `gh pr review`
-
-## Safe patterns
-
-### Python (preferred)
-
-```python
-import subprocess
-import tempfile
-
-body = "## Summary\n\nFixes `foo` by updating `bar`.\n"
-
-with tempfile.NamedTemporaryFile(mode="w", suffix=".md", delete=False) as f:
-    f.write(body)
-    body_path = f.name
-
-subprocess.run(["gh", "pr", "create", "--title", "My PR", "--body-file", body_path], check=True)
-```
-
-### PowerShell (Windows — preferred for this repo)
-
-`Set-Content -Encoding utf8` writes UTF-8-**with-BOM** on Windows PowerShell 5.1,
-which causes `gh` to treat the leading BOM as part of the first heading character
-and can corrupt rendering. Use the BOM-free pattern below — it works on both
-Windows PowerShell 5.1 and PowerShell 7+.
-
-```powershell
-$bodyPath = [System.IO.Path]::ChangeExtension((New-TemporaryFile).FullName, '.md')
-$body = @'
-## Summary
-
-Fixes `foo` by updating `bar`.
-'@
-[IO.File]::WriteAllText($bodyPath, $body, [Text.UTF8Encoding]::new($false))
-
-gh pr create --title "My PR" --body-file $bodyPath
-```
-
-On PowerShell 7+ you can alternatively use `Set-Content -Encoding utf8NoBOM`,
-but the `[IO.File]::WriteAllText` pattern above is version-agnostic.
-
-### Bash
-
-Safe Bash patterns are intentionally omitted from this rule file. This repo
-is Windows/PowerShell-first, and Bash-only safe patterns such as `mktemp` and
-heredocs are not applicable here. Use the PowerShell example above in shell
-contexts in this repo, or the Python example when invoking `gh` from Python.
-The "What NOT to do" examples below use Bash syntax for illustration only and
-do not imply Bash is a supported safe-pattern environment.
-
-## What NOT to do
-
-```bash
-# BAD — backticks become \` on GitHub
-gh pr create --title "My PR" --body "Fixes \`foo\` by updating \`bar\`."
-
-# BAD — disallowed by repo policy; markdown body content must use --body-file
-gh issue create --title "T" --body 'Use `x` to do `y`'
-```
-
-## Enforcement
-
-A PreToolUse hook (`gh_body_arg_blocker.py`) blocks any Bash call that uses
-`gh <subcommand> ... --body <arg>` (without `-file`) and returns a corrective
-message directing you to use `--body-file` instead.
+`gh_body_arg_blocker.py` (PreToolUse on Bash) blocks `--body <arg>` and returns the corrective message.