claude-dev-env 1.58.0 → 1.60.0

package/hooks/hooks_constants/destructive_command_segment_constants.py

@@ -0,0 +1,178 @@
+"""Segment-splitting and command-name constants for the destructive command blocker compound rm guard."""
+
+ALL_SHELL_CONTROL_OPERATOR_TOKENS: frozenset[str] = frozenset({"&&", "||", ";", "|&", "|", "&", "\n", "\r"})
+ALL_COMMAND_LAUNCHER_WRAPPER_COMMANDS: frozenset[str] = frozenset(
+    {
+        "timeout",
+        "nohup",
+        "nice",
+        "ionice",
+        "stdbuf",
+        "time",
+        "setsid",
+        "chrt",
+        "taskset",
+    }
+)
+ALL_LAUNCHERS_REQUIRING_A_POSITIONAL_VALUE: frozenset[str] = frozenset(
+    {
+        "timeout",
+        "chrt",
+        "taskset",
+    }
+)
+ALL_INTERPRETER_AND_WRAPPER_COMMANDS: frozenset[str] = frozenset(
+    {
+        "sh",
+        "bash",
+        "zsh",
+        "dash",
+        "ksh",
+        "tcsh",
+        "csh",
+        "fish",
+        "pwsh",
+        "powershell",
+        "cmd",
+        "eval",
+        "exec",
+        "source",
+        "sudo",
+        "su",
+        "env",
+        "xargs",
+        "awk",
+        "gawk",
+        "mawk",
+        "nawk",
+        "make",
+        "tclsh",
+        "expect",
+        "lua",
+    }
+)
+ALL_REMOTE_AND_PROGRAM_STRING_EXECUTORS: frozenset[str] = frozenset(
+    {
+        "ssh",
+        "python",
+        "python2",
+        "python3",
+        "perl",
+        "ruby",
+        "node",
+        "deno",
+        "bun",
+        "php",
+    }
+)
+ALL_STRING_ARGUMENT_EXECUTION_FLAGS: frozenset[str] = frozenset({"-c", "-e"})
+ALL_BENIGN_COMPOUND_SEGMENT_COMMANDS: frozenset[str] = frozenset(
+    {
+        "echo",
+        "printf",
+        "gh",
+        "head",
+        "tail",
+        "cat",
+        "ls",
+        "grep",
+        "wc",
+        "sort",
+        "uniq",
+        "true",
+        "git",
+    }
+)
+OUTPUT_REDIRECTION_OPERATOR_PATTERN: str = r"(?:\d+|&)?>>?\|?(?!&[\d-])"
+ALL_FILE_WRITING_OUTPUT_FLAGS_BY_BENIGN_PROGRAM: dict[str, frozenset[str]] = {
+    "sort": frozenset({"-o", "--output"}),
+}
+ALL_GIT_CONFIG_READ_ONLY_FLAGS: frozenset[str] = frozenset(
+    {"--get", "--get-all", "--get-regexp", "--list", "-l", "--get-urlmatch"}
+)
+ALL_GIT_REMOTE_READ_ONLY_VERBS: frozenset[str] = frozenset({"show", "get-url"})
+ALL_GIT_FETCH_FORCE_FLAGS: frozenset[str] = frozenset({"-f", "--force"})
+ALL_GH_HTTP_WRITE_METHOD_FLAGS: frozenset[str] = frozenset({"-X", "--method"})
+ALL_GH_HTTP_WRITE_METHODS: frozenset[str] = frozenset({"POST", "PUT", "PATCH", "DELETE"})
+GH_HTTP_READ_ONLY_METHOD: str = "GET"
+GH_SHORT_METHOD_FLAG_PREFIX: str = "-X"
+GH_LONG_METHOD_FLAG_EQUALS_PREFIX: str = "--method="
+ALL_GH_API_REQUEST_BODY_FIELD_FLAGS: frozenset[str] = frozenset(
+    {"-f", "--raw-field", "-F", "--field", "--input"}
+)
+ALL_GH_API_GLUED_REQUEST_BODY_FIELD_FLAG_PREFIXES: tuple[str, ...] = (
+    "-f",
+    "-F",
+    "--raw-field=",
+    "--field=",
+    "--input=",
+)
+ALL_READ_ONLY_GIT_SUBCOMMANDS: frozenset[str] = frozenset(
+    {
+        "status",
+        "log",
+        "show",
+        "diff",
+        "rev-parse",
+        "rev-list",
+        "describe",
+        "config",
+        "remote",
+        "fetch",
+        "ls-files",
+        "ls-remote",
+        "ls-tree",
+        "cat-file",
+        "blame",
+        "shortlog",
+        "name-rev",
+        "for-each-ref",
+        "symbolic-ref",
+        "merge-base",
+        "count-objects",
+        "version",
+        "help",
+    }
+)
+ALL_READ_ONLY_GH_SUBCOMMANDS: frozenset[str] = frozenset(
+    {
+        "view",
+        "list",
+        "status",
+        "checks",
+        "diff",
+        "search",
+        "browse",
+        "api",
+    }
+)
+ALL_READ_ONLY_SUBCOMMANDS_BY_DISPATCHING_PROGRAM: dict[str, frozenset[str]] = {
+    "git": ALL_READ_ONLY_GIT_SUBCOMMANDS,
+    "gh": ALL_READ_ONLY_GH_SUBCOMMANDS,
+}
+ALL_READ_ONLY_SUBCOMMAND_POSITION_DEPTHS_BY_DISPATCHING_PROGRAM: dict[str, int] = {
+    "git": 1,
+    "gh": 2,
+}
+LAUNCHER_POSITIONAL_VALUE_SHAPE_PATTERN: str = (
+    r"^(?:0x[0-9A-Fa-f]+"
+    r"|[0-9]+(?:[.,][0-9]+)?[smhd]?"
+    r"|[0-9]+(?:-[0-9]+)?(?:,[0-9]+(?:-[0-9]+)?)*)$"
+)
+ALL_LAUNCHER_OPTIONS_TAKING_SEPARATE_VALUE: frozenset[str] = frozenset(
+    {
+        "-s",
+        "--signal",
+        "-k",
+        "--kill-after",
+        "-n",
+        "-o",
+        "--output",
+        "-e",
+        "--error",
+        "-i",
+        "--input",
+        "--classdata",
+    }
+)
+ALL_SUBSHELL_GROUPING_CHARACTERS: str = "({"

package/hooks/hooks_constants/duplicate_function_body_constants.py

@@ -0,0 +1,34 @@
+"""Constants for the duplicate-function-body scan in ``code_rules_enforcer``.
+
+The blocking scan flags a top-level function whose body is structurally identical
+to a top-level function already defined in a sibling ``.py`` module in the same
+directory. This catches the Reuse-before-create / DRY violation where a helper is
+copy-pasted across several modules instead of imported from one shared home.
+
+The ``CROSS_SKILL_*`` and ``SKILL*`` constants feed the non-blocking companion
+advisory: a helper copied between two skills' ``scripts`` directories, where a
+shared module would break independent install. That advisory names the source
+skill on stderr rather than denying the write.
+"""
+
+MINIMUM_DUPLICATE_BODY_STATEMENTS: int = 3
+MAX_DUPLICATE_BODY_ISSUES: int = 25
+DUNDER_INIT_FILENAME: str = "__init__.py"
+PYTHON_SOURCE_SUFFIX: str = ".py"
+DUPLICATE_BODY_GUIDANCE: str = (
+    "this function body is identical to one in a sibling module; "
+    "extract a single shared helper (for example in hooks_constants/) and "
+    "import it from both modules instead of copying it (Reuse before create / DRY)"
+)
+
+SKILLS_DIRECTORY_NAME: str = "skills"
+SKILL_SCRIPTS_DIRECTORY_NAME: str = "scripts"
+MAX_CROSS_SKILL_ADVISORY_ISSUES: int = 25
+CROSS_SKILL_ADVISORY_PREFIX: str = "[CODE_RULES advisory]"
+CROSS_SKILL_DUPLICATE_GUIDANCE: str = (
+    "two skill folders install on their own, so this copy is a defensible "
+    "skill-isolation tradeoff; a shared module would couple the skills and "
+    "break independent install. Confirm the copy is intentional, or for a "
+    "large or behavior-bearing body raise the choice through AskUserQuestion "
+    "(see the no-cross-skill-duplicate-helpers rule)"
+)

package/hooks/hooks_constants/hook_prose_detector_consistency_constants.py

@@ -0,0 +1,30 @@
+"""Configuration constants for the hook_prose_detector_consistency PreToolUse hook."""
+
+WRITE_TOOL_NAME: str = "Write"
+EDIT_TOOL_NAME: str = "Edit"
+
+HOOK_MODULE_PATH_SEGMENT: str = "/hooks/"
+PYTHON_FILE_SUFFIX: str = ".py"
+CONSTANTS_MODULE_SUFFIX: str = "_constants.py"
+TEST_MODULE_PREFIX: str = "test_"
+
+PATH_SEPARATOR_CLASS_PATTERN: str = (
+    r"\[[^\]/]*\\\\[^\]/]*\]|\[[^\]]*\\\\?/[^\]]*\]|\[[^\]]*/\\\\?[^\]]*\]"
+)
+OVERSTATED_OUTPUT_KEY_PHRASE_PATTERN: str = r"output[- ]key\s+segment"
+
+CORRECTIVE_MESSAGE: str = (
+    "BLOCKED [hook-prose-detector-consistency]: A hook module's user-facing prose "
+    "(its docstring lead narrative or CORRECTIVE_MESSAGE) claims the hook blocks an "
+    "'output-key segment', but the module's detector keys off a path separator only "
+    "(it matches a token next to `\\` or `/`). A quoted structured-output key alone "
+    "never triggers a block, so the prose overstates the contract: an author whose "
+    "only per-iteration token is an output key would never see this message, and an "
+    "author who does see it is told an output key caused a block it cannot cause.\n\n"
+    "Describe only the trigger the detector implements: a per-iteration path segment "
+    "next to a path separator. Drop 'or output-key segment' (or restate it as 'a "
+    "per-iteration path segment') so the message and docstring match what the regex "
+    "catches.\n\n"
+    "Invariant: a hook's docstring and corrective message describe exactly the shapes "
+    "its detector flags -- no broader trigger surface than the regex enforces."
+)

package/hooks/hooks_constants/precommit_code_rules_gate_constants.py

@@ -8,7 +8,7 @@ from pathlib import Path
 
 GIT_DASH_C_COMMIT_PATTERN: str = r"git\s+-C\s+[\"']?[^\"';&|]+?[\"']?\s+commit\b"
 GIT_COMMAND_TIMEOUT_SECONDS: int = 5
-GATE_TIMEOUT_SECONDS: int = 25
+GATE_TIMEOUT_SECONDS: int = 120
 GATE_RELATIVE_PATH: Path = Path("_shared") / "pr-loop" / "scripts" / "code_rules_gate.py"
 ALL_STAGED_PYTHON_FILES_COMMAND: tuple[str, ...] = (
     "git",

package/hooks/hooks_constants/subprocess_budget_completeness_constants.py

@@ -0,0 +1,5 @@
+"""Configuration constants for the subprocess_budget_completeness PreToolUse hook."""
+
+ALL_BUDGET_NAME_MARKERS: tuple[str, ...] = ("worst_case", "_budget", "budget_seconds")
+SUBPROCESS_TIMEOUT_KEYWORD: str = "timeout"
+BUDGET_ENTRY_POINT_FUNCTION_NAME: str = "main"

package/hooks/hooks_constants/workflow_substitution_slot_blocker_constants.py

@@ -0,0 +1,22 @@
+"""Configuration constants for the workflow_substitution_slot_blocker PreToolUse hook."""
+
+WRITE_TOOL_NAME: str = "Write"
+EDIT_TOOL_NAME: str = "Edit"
+MULTI_EDIT_TOOL_NAME: str = "MultiEdit"
+
+WORKFLOW_FILE_SUFFIX: str = ".workflow.js"
+
+CORRECTIVE_MESSAGE: str = (
+    "BLOCKED [workflow-substitution-slot]: A bare per-iteration index token "
+    "(for example `cand_i`) appears as a per-iteration path segment inside a "
+    ".workflow.js agent-prompt block that loops over an index. A bare `_i` "
+    "token reads as a fixed literal, so an agent can create one literal "
+    "directory and overwrite it across every iteration -- collapsing an "
+    "N-iteration gate into one.\n\n"
+    "Mark the index as a substitution slot with the angle-bracket convention "
+    "this template already uses for per-call values (`<plate.svg>`, `<glow_hex>`): "
+    "write `cand_<i>` instead of `cand_i`, or spell out 'replace <i> with the "
+    "iteration index 0, 1, 2' in the step text.\n\n"
+    "Convention: every per-call substitution slot in a .workflow.js template is "
+    "marked with angle brackets, so an agent fills in a fresh value per call."
+)

package/package.json

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

package/rules/docstring-prose-matches-implementation.md

@@ -0,0 +1,43 @@
+# Docstring Prose Matches Implementation
+
+**When this applies:** Any Write or Edit to a public function, method, class, or module whose docstring prose makes an enumerable claim about behavior — a list of inputs the code handles, the conditions it treats as a match, the cases it skips, or the order of its steps.
+
+## Rule
+
+When a docstring enumerates the behaviors a body applies, the enumeration covers every behavior the body applies. A reader trusts the list to be complete: an item the code applies but the prose omits is a silent gap that misleads every future reader and reviewer.
+
+The gate validator `check_docstring_args_match_signature` covers the `Args:` section parameter names. Free-form prose — `"a field counts as read when ..."`, `"resolves to shared temp only"`, `"strip ceremony, then drop blockquotes"` — has no signature to compare against, so the gate cannot catch its drift. This rule is the judgment standard for that prose. It carries documented-but-pending hook coverage; the audit lane below is the enforcement until a deterministic gate check exists.
+
+## What to check before you write the docstring
+
+Read the body and the docstring side by side:
+
+- **Read-source / match-source unions.** A body that computes `read_names = a | b | c` (or any union of "what counts") names each union member in the prose enumeration. A union member the code applies but the prose omits is a gap.
+- **Suppressor / skip lists.** A body with several early returns that suppress the check names each suppressor in the prose.
+- **Step order.** A docstring that says `A then B then C` matches the call order in the body.
+- **Predicate breadth.** A boolean helper whose prose promises a narrow check accepts only the inputs the prose names — no broader input class the name and prose do not mention.
+
+When the body changes the set of behaviors it applies, the same edit updates the prose enumeration. The two move together in one commit.
+
+## Worked example
+
+A `@dataclass` dead-field check builds its set of "field counts as read" sources by union:
+
+```python
+read_names = (
+    attribute_read_names
+    | dynamic_literal_names
+    | _match_pattern_attribute_names(tree)
+    | _exported_names(tree)
+)
+```
+
+A docstring that enumerates "attribute read, augmented-assignment target, class-pattern keyword, literal `getattr`/`attrgetter`" but omits the `__all__` source (`_exported_names`) is drifted: a field whose name appears in `__all__` is treated as read, and the prose hides that. The fix adds the missing source to the enumeration so the list matches the union.
+
+## Enforcement (audit lane)
+
+This drift class is sub-bucket **O6** in `packages/claude-dev-env/audit-rubrics/category_rubrics/category-o-docstring-vs-impl-drift.md` (free-form `Note:` / `Returns:` / responsibility-list claims). The audit teammate lists every prose enumeration in a changed docstring and verifies each item against the body, and lists every union member / suppressor / step in the body and verifies each appears in the prose. A union member or suppressor in the body that the prose omits is an O6 finding.
+
+## Why
+
+A docstring enumeration earns its place by being trustworthy. A complete list lets a reader reason about the function without scanning the body; a list missing one item is worse than no list, because it asserts completeness it does not have. Naming this standard makes the gap a first-class finding at write time and at audit, rather than a surprise a reader hits months later.

package/rules/file-global-constants.md

@@ -20,7 +20,13 @@ Test-file detection uses the following anchored patterns against the full relati
 
 ## `config/` files are exempt
 
-Constants placed in `config/` satisfy the constants-location rule; the use-count requirement applies only to production code outside `config/`.
+Constants placed in `config/` satisfy the constants-location rule; the use-count rule applies only to production code outside `config/`.
+
+## Dead constant in a dedicated constants module (cross-module)
+
+The use-count rule above governs a file-global constant in production code outside `config/` by counting same-file references. A dedicated constants module — a file whose name ends in `_constants.py`, or any module under a `config/` directory — exports its constants to importer modules elsewhere, so a same-file count proves nothing. A separate hook, `check_dead_module_constants` (dispatched from `code_rules_enforcer`), governs these modules: it flags an `UPPER_SNAKE` constant defined in the written module whose name appears in no `.py` module anywhere under the enclosing package tree — not imported, not read, not listed in an `__all__` literal, not named in a string annotation. That is the dead exported constant CODE_RULES §9.8 targets, caught at Write/Edit time.
+
+The scan resolves the enclosing package tree from the written file: for a constants module inside a package subdirectory, the tree is the package's parent (so an importer one directory up is in scope); for a `config/` module, the tree is the parent of the `config` directory. A module that declares its own `__all__` is skipped — the author's explicit export surface is taken as the liveness contract. A reference from a test module under the tree keeps a constant live. Test modules and migration modules are themselves exempt from the check.
 
 ## Examples
 

package/rules/hook-prose-matches-detector.md

@@ -0,0 +1,26 @@
+---
+paths: **/hooks/**/*.py
+---
+
+# Hook Prose Matches Its Detector
+
+**When this applies:** Any Write or Edit to a hook module (`.py` under `hooks/`) or its `*_constants.py` companion.
+
+**Hook enforcement:** `hook-prose-detector-consistency` (PreToolUse on Write|Edit) blocks a hook whose user-facing prose claims a trigger its detector never fires on. See `hooks.json` for registration.
+
+## Rule
+
+A hook's docstring lead narrative and its `CORRECTIVE_MESSAGE` describe exactly the shapes the detector flags — no broader trigger surface than the regex enforces. An author reads the corrective message to learn what they did wrong; an author reads the docstring to learn what the hook guards. When either claims a trigger the detector cannot fire on, both audiences are misled: an author whose only token is that shape never sees the block, and an author who does see the block is told the wrong cause.
+
+## The path-shape blocker case
+
+A path-shape blocker detects a per-iteration token only when the token sits next to a path separator (its detection regex keys off a `[\\/]`-style character class). Such a hook must not claim it blocks an "output-key segment": a quoted structured-output key alone, with no looped path, is never flagged. The `*_constants.py` companion holds the corrective message and not the detector, so the phrase "output-key segment" describing a blocked trigger is itself the violation there, regardless of which file holds the regex.
+
+| Prohibited claim | Why it overstates | Correct phrasing |
+|---|---|---|
+| "appears as a path or output-key segment" | the detector keys off a path separator only | "appears as a per-iteration path segment" |
+| docstring: "blocks a bare token like `cand_i`" | a bare prose token next to no separator is not flagged | "blocks a per-iteration path like `${work}\cand_i\plate.svg`" |
+
+## The test
+
+After writing a hook, ask: **would a token that matches every word of this message actually trip the detector?** When the message names a shape the regex skips, rewrite the message to name only what the regex catches.

package/rules/no-cross-skill-duplicate-helpers.md

@@ -0,0 +1,29 @@
+---
+paths: "**/skills/*/scripts/**/*.py"
+---
+
+# Cross-Skill Duplicate Helpers
+
+**When this applies:** Any Write or Edit to a `.py` file under a skill's `scripts/` directory (`**/skills/<skill-name>/scripts/**/*.py`) that copies a top-level helper from another skill's `scripts/` directory.
+
+## The two duplication cases differ
+
+CODE_RULES "Reuse before create" / DRY says one helper lives in one home and both call sites import it. That rule is blocking **within one skill** — two `.py` modules in the same skill's `scripts/` directory that carry the same top-level function body fail the `code_rules_duplicate_body` gate, and the fix is a shared module both import.
+
+Across **two skill folders** the same copy is a different call. Each skill folder installs on its own, so a shared module would couple two skills the install model keeps separate: deleting or reinstalling one skill would break a helper the other depends on. A small launch helper copied into each skill (for example a Chrome-open helper that reads the registry and runs `chrome.exe`) is a defensible skill-isolation tradeoff, not a regression.
+
+## Decision
+
+Before you copy a top-level helper from one skill's `scripts/` directory into another:
+
+- **Same skill, two modules** — extract one shared module in that skill and import it from both. The `code_rules_duplicate_body` gate blocks the copy.
+- **Two skill folders, a small self-contained helper** — copy it; the skill-isolation tradeoff stands. A non-blocking `[CODE_RULES advisory]` names the source skill at Write time so the copy is a deliberate choice on record, not an oversight.
+- **Two skill folders, a large or behavior-bearing body** — when the copied body is large, holds business logic, or would drift in a way that changes behavior, raise the choice through `AskUserQuestion`: copy and accept drift, or stand up a shared dependency both skills declare (for example a published package both `requirements` files name, or a `_shared` module the install step writes into each skill). A shared dependency that survives independent install is the only shared-home path that does not break the install model.
+
+## What the advisory tells you
+
+The `advise_cross_skill_duplicate_helper` check in `code_rules_duplicate_body` prints to stderr (never blocks) when a top-level function in the file being written has the same normalized body as a top-level function in another skill's `scripts/` directory. The message names the source skill and function so a reviewer can confirm the copy was intentional. It fires only across skill folders; within one skill the blocking gate already covers the copy.
+
+## Why this is a rule, not a wider gate
+
+Extending the blocking duplicate-body gate to span skill folders would deny the exact skill-isolation copy that keeps skills independently installable — a false positive on a sanctioned pattern. The boundary between "same skill, block" and "two skills, signal" is a judgment the writer makes with the source skill named in front of them. The rule states the judgment; the `[CODE_RULES advisory]` surfaces the signal; neither blocks the defensible copy.

package/rules/no-inline-destructive-literals.md

@@ -0,0 +1,11 @@
+# No Inline Destructive-Command Literals in Bash
+
+The `destructive_command_blocker` PreToolUse hook matches destructive patterns (`rm -rf`, `git reset --hard`, `dd`, `mkfs`, `chmod -R`, fork bombs) as raw text anywhere in a Bash-tool command, with no quote-awareness — so a destructive literal carried only as DATA (a commit message, a PR/issue/review-comment body, an echoed string, a `python -c`/`node -e`/`awk` argument, a heredoc) trips the confirmation prompt even though the shell never executes it. In a background or auto-mode run no human can answer that prompt, so the call stalls.
+
+Keep destructive literals out of the Bash command string:
+
+- Commit messages and PR/issue/review-comment bodies that describe destructive-command behavior go in a file passed by path — `git commit -F <file>`, `gh ... --body-file <file>` (see [`gh-body-file`](gh-body-file.md)) — never `git commit -m` / `gh ... -b`.
+- To exercise or verify `destructive_command_blocker` (or any hook) behavior, run the committed test suite (`python -m pytest <test_file>`), which passes the command strings as in-language data, not as a shell command — never an inline `python -c` harness.
+- Genuine cleanup targets the OS temp dir or `$CLAUDE_JOB_DIR/tmp` (auto-allowed as ephemeral), never a repository or worktree path.
+
+The `destructive_command_blocker` hook is the enforcement surface; this rule is how to keep a non-executing mention from tripping it.

package/rules/workflow-substitution-slots.md

@@ -0,0 +1,7 @@
+# Workflow Substitution Slot Rule
+
+In a `.workflow.js` agent-prompt template, every per-call or per-iteration value an agent must fill in is marked with the angle-bracket convention — `<plate.svg>`, `<object.svg>`, `<glow_hex>`, `cand_<i>`. A bare token such as `cand_i` reads as a fixed literal, so an agent can create one literal directory named `cand_i` and overwrite it across every iteration of a loop, collapsing an N-iteration gate into a single run.
+
+When a loop builds a per-iteration path or output key, write the index as a slot — `cand_<i>` — or spell out `replace <i> with the iteration index 0, 1, 2` in the step text. Every per-call value in a `.workflow.js` template carries angle brackets so an agent fills in a fresh value per call.
+
+`workflow_substitution_slot_blocker.py` (PreToolUse on Write/Edit) blocks a `.workflow.js` write whose looped content carries a bare `<word>_<i|j|k>` token as a per-iteration path segment, and returns the corrective message.