claude-dev-env 8.42.4 → 8.42.5

package/docs/rule-guides/shell-invocation.md

@@ -0,0 +1,25 @@
+Back to the [rule entry](../../rules/shell-invocation.md).
+
+# Shell Invocation
+
+Two constraints govern every shell command an agent issues: which shell runs it, and what the command string may contain.
+
+## Use pwsh
+
+Every Bash-tool shell command on Windows uses `pwsh`: `pwsh -NoProfile -File '<script>.ps1' <args>` for scripts, `pwsh -NoProfile -Command "..."` (or a literal `@'...'@` here-string) for inline work, or the built-in `PowerShell` tool for pure-PowerShell workflows (it supports `run_in_background`). Never wrap a script path in `-Command "& '...'"`. The `-File` form keeps `permissions.allow` matching. The `&` call operator is fine for invoking an executable at a path (`& '<venv>\Scripts\python.exe' script.py`).
+
+The mandate covers the shell a command runs through. A direct interpreter invocation, such as a `python` call on a repo script, conforms as written.
+
+Keep `powershell`, `powershell.exe`, `cmd /c`, and `bash -c` out of the `settings.json` permission rules. `Audit-ShellPolicy.ps1` reports those forms and `Migrate-ShellPolicy.ps1` rewrites them to `pwsh`. Both ship in the claude-dev-env repo at `packages/claude-dev-env/scripts/` and run on demand. No hook runs them.
+
+## No shell substitution
+
+No `$(...)`, unescaped backticks, or `<(...)` / `>(...)` process substitution in Bash tool commands. The allowlist matcher reads the raw command string, so a substitution wrapper forces a permission prompt even when every inner segment is auto-allowed. Split into separate tool calls, or use flag forms like `git -C "<path>" rev-parse HEAD`. Arithmetic `$((...))` passes: it spawns no subshell.
+
+When a script file's literal body needs `$(...)`, author it with the Write tool.
+
+## Enforcement
+
+No PreToolUse hook denies a Bash command for its shell form. The substitution constraint above is guidance a reader follows, and a permission prompt on a wrapped command is the signal that one slipped through.
+
+`blocking/msys_rev_path_rewriter.py` only rewrites a Bash command. It keeps Git Bash from converting a `<rev>:<path>` argument when the revision holds a slash. A test pins the dispatcher roster to this one hook.

package/package.json

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

package/rules/shell-invocation.md

@@ -1,23 +1,9 @@
-# Shell Invocation
+# Shell invocation
 
-Two constraints govern every shell command an agent issues: which shell runs it, and what the command string may contain.
+**When:** Issuing a Bash-tool shell command, or writing a `settings.json` permission rule.
 
-## Use pwsh
+On Windows, run shell work through `pwsh`: `pwsh -NoProfile -File '<script>.ps1' <args>` for a script, and `pwsh -NoProfile -Command "..."` or the `PowerShell` tool for inline work. A direct interpreter call such as `python script.py` conforms as written. Keep `powershell`, `cmd /c`, and `bash -c` out of permission rules. Keep `$(...)`, unescaped backticks, and `<(...)` or `>(...)` out of Bash commands; split the call or use a flag form such as `git -C "<path>"`. Arithmetic `$((...))` passes.
 
-Every Bash-tool shell command on Windows uses `pwsh`: `pwsh -NoProfile -File '<script>.ps1' <args>` for scripts, `pwsh -NoProfile -Command "..."` (or a literal `@'...'@` here-string) for inline work, or the built-in `PowerShell` tool for pure-PowerShell workflows (it supports `run_in_background`). Never wrap a script path in `-Command "& '...'"` — `-File` keeps `permissions.allow` matching. The `&` call operator is fine for invoking an executable at a path (`& '<venv>\Scripts\python.exe' script.py`).
+**Enforcement:** none, the agent applies it; a permission prompt on a wrapped command is the signal. `blocking/msys_rev_path_rewriter.py` only rewrites a `<rev>:<path>` argument.
 
-The mandate covers the shell a command runs through. A direct interpreter invocation, such as a `python` call on a repo script, conforms as written.
-
-Keep `powershell`, `powershell.exe`, `cmd /c`, and `bash -c` out of the `settings.json` permission rules. `Audit-ShellPolicy.ps1` reports those forms and `Migrate-ShellPolicy.ps1` rewrites them to `pwsh`. Both ship in the claude-dev-env repo at `packages/claude-dev-env/scripts/` and run on demand, not as a live gate.
-
-## No shell substitution
-
-No `$(...)`, unescaped backticks, or `<(...)` / `>(...)` process substitution in Bash tool commands. The allowlist matcher reads the raw command string, so a substitution wrapper forces a permission prompt even when every inner segment is auto-allowed. Split into separate tool calls, or use flag forms like `git -C "<path>" rev-parse HEAD`. Arithmetic `$((...))` passes: it spawns no subshell.
-
-When a script file's literal body needs `$(...)`, author it with the Write tool, not a Bash heredoc.
-
-## Enforcement
-
-No PreToolUse hook denies a Bash command for its shell form. The substitution constraint above is guidance a reader follows, and a permission prompt on a wrapped command is the signal that one slipped through.
-
-`blocking/msys_rev_path_rewriter.py` only rewrites a Bash command. It keeps Git Bash from converting a `<rev>:<path>` argument when the revision holds a slash. A test pins the dispatcher roster to this one hook.
+**Full text:** [`docs/rule-guides/shell-invocation.md`](../docs/rule-guides/shell-invocation.md). Read it before writing a permission rule or a multi-step shell command.

package/scripts/tests/test_rule_index_shape.py

@@ -0,0 +1,138 @@
+"""Each rule entry keeps the index shape, and the always-loaded entries stay inside a byte budget."""
+
+import re
+import sys
+from pathlib import Path
+
+PACKAGE_ROOT = Path(__file__).resolve().parents[2]
+RULES_DIRECTORY = PACKAGE_ROOT / "rules"
+RULE_GUIDES_DIRECTORY = PACKAGE_ROOT / "docs" / "rule-guides"
+
+module_directory = str(Path(__file__).parents[1])
+if module_directory not in sys.path:
+    sys.path.insert(0, module_directory)
+
+from codex_compat_materializer import (
+    codex_instruction_rule_relative_paths,
+    instruction_alias_filenames,
+)
+
+FRONTMATTER_DELIMITER = "---"
+FULL_TEXT_LINK_PATTERN = re.compile(
+    r"^\*\*Full text:\*\*.*?\]\((\.\./docs/rule-guides/[^)#\s]+\.md)\)", re.MULTILINE
+)
+TITLE_PATTERN = re.compile(r"^# \S", re.MULTILINE)
+
+MAXIMUM_ENTRY_BYTES = 1_500
+MAXIMUM_ALWAYS_ON_BYTES = 12_000
+POINTER_ENTRY_NAMES = frozenset({"skill-pointers.md"})
+CODEX_VERBATIM_ENTRY_NAMES = frozenset({"question-presentation.md"})
+CODEX_MATERIALIZED_GUIDE_NAMES = frozenset(
+    Path(each_path).name for each_path in codex_instruction_rule_relative_paths
+)
+
+
+def _entry_paths() -> list[Path]:
+    return sorted(
+        each_path
+        for each_path in RULES_DIRECTORY.glob("*.md")
+        if each_path.name not in instruction_alias_filenames
+    )
+
+
+def _split_frontmatter(entry_text: str) -> tuple[list[str], str]:
+    all_lines = entry_text.splitlines()
+    if not all_lines or all_lines[0] != FRONTMATTER_DELIMITER:
+        return [], entry_text
+    for each_index, each_line in enumerate(all_lines[1:], start=1):
+        if each_line == FRONTMATTER_DELIMITER:
+            return all_lines[1:each_index], "\n".join(all_lines[each_index + 1 :])
+    return [], entry_text
+
+
+def _loads_in_every_session(entry_text: str) -> bool:
+    all_frontmatter_lines, _ = _split_frontmatter(entry_text)
+    return not any(
+        each_line.startswith("paths:") for each_line in all_frontmatter_lines
+    )
+
+
+def _linked_guide_names(entry_text: str) -> set[str]:
+    return {
+        Path(each_target).name
+        for each_target in FULL_TEXT_LINK_PATTERN.findall(entry_text)
+    }
+
+
+def _entry_text(entry_path: Path) -> str:
+    return entry_path.read_text(encoding="utf-8")
+
+
+def test_each_entry_stays_inside_the_entry_byte_budget() -> None:
+    over_budget = {
+        each_path.name: len(each_path.read_bytes())
+        for each_path in _entry_paths()
+        if len(each_path.read_bytes()) > MAXIMUM_ENTRY_BYTES
+    }
+    assert over_budget == {}
+
+
+def test_each_entry_opens_with_a_title_after_its_frontmatter() -> None:
+    untitled = [
+        each_path.name
+        for each_path in _entry_paths()
+        if not TITLE_PATTERN.match(
+            _split_frontmatter(_entry_text(each_path))[1].lstrip()
+        )
+    ]
+    assert untitled == []
+
+
+def _full_text_link_problems(entry_path: Path) -> list[str]:
+    all_guide_names = _linked_guide_names(_entry_text(entry_path))
+    if not all_guide_names:
+        return [f"{entry_path.name}: no Full text link"]
+    return [
+        f"{entry_path.name}: {each_guide_name} does not exist"
+        for each_guide_name in sorted(all_guide_names)
+        if not (RULE_GUIDES_DIRECTORY / each_guide_name).is_file()
+    ]
+
+
+def test_each_entry_links_a_full_text_guide_that_exists() -> None:
+    all_problems = [
+        each_problem
+        for each_path in _entry_paths()
+        if each_path.name not in POINTER_ENTRY_NAMES | CODEX_VERBATIM_ENTRY_NAMES
+        for each_problem in _full_text_link_problems(each_path)
+    ]
+    assert all_problems == []
+
+
+def test_each_guide_has_exactly_one_owner() -> None:
+    owners_by_guide: dict[str, list[str]] = {}
+    for each_path in _entry_paths():
+        for each_guide_name in _linked_guide_names(_entry_text(each_path)):
+            owners_by_guide.setdefault(each_guide_name, []).append(each_path.name)
+    unowned = sorted(
+        each_guide.name
+        for each_guide in RULE_GUIDES_DIRECTORY.glob("*.md")
+        if each_guide.name not in owners_by_guide
+        and each_guide.name not in CODEX_MATERIALIZED_GUIDE_NAMES
+    )
+    shared = {
+        each_guide_name: all_owner_names
+        for each_guide_name, all_owner_names in owners_by_guide.items()
+        if len(all_owner_names) > 1
+    }
+    assert unowned == []
+    assert shared == {}
+
+
+def test_always_loaded_entries_stay_inside_the_total_byte_budget() -> None:
+    always_on_bytes = sum(
+        len(each_path.read_bytes())
+        for each_path in _entry_paths()
+        if _loads_in_every_session(_entry_text(each_path))
+    )
+    assert always_on_bytes <= MAXIMUM_ALWAYS_ON_BYTES