claude-dev-env 1.94.0 → 2.0.0

package/hooks/workflow/auto_formatter.py

@@ -48,6 +48,7 @@ PLUGIN_ROOT = os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__
 HOOKS_DIR = os.path.join(PLUGIN_ROOT, "hooks") + os.sep
 PYTHON_FORMAT_TIMEOUT_SECONDS = 12
 JS_FORMAT_TIMEOUT_SECONDS = 30
+GIT_LS_FILES_TIMEOUT_SECONDS = 5
 PRETTIER_CONFIG_NAMES = {
     ".prettierrc",
     ".prettierrc.json",
@@ -99,10 +100,10 @@ def is_untracked_in_git(file_path: str) -> bool:
     try:
         git_check = subprocess.run(
             ["git", "ls-files", "--error-unmatch", file_path],
-            capture_output=True,
+            check=False, capture_output=True,
             text=True,
             cwd=containing_directory,
-            timeout=5,
+            timeout=GIT_LS_FILES_TIMEOUT_SECONDS,
         )
         return git_check.returncode != 0
     except (FileNotFoundError, subprocess.TimeoutExpired):
@@ -150,7 +151,7 @@ def main() -> None:
             [sys.executable, "-m", "black", file_path],
         ]:
             try:
-                format_run = subprocess.run(each_formatter_command, capture_output=True, text=True, timeout=PYTHON_FORMAT_TIMEOUT_SECONDS)
+                format_run = subprocess.run(each_formatter_command, check=False, capture_output=True, text=True, timeout=PYTHON_FORMAT_TIMEOUT_SECONDS)
                 if format_run.returncode == 0:
                     formatter_name = each_formatter_command[0] if each_formatter_command[0] != sys.executable else each_formatter_command[2]
                     send_format_notification(file_path, formatter_name)
@@ -165,7 +166,7 @@ def main() -> None:
         try:
             prettier_run = subprocess.run(
                 ["npx", "--yes", "prettier", "--write", file_path],
-                capture_output=True,
+                check=False, capture_output=True,
                 text=True,
                 timeout=JS_FORMAT_TIMEOUT_SECONDS,
             )

package/package.json

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

package/rules/CLAUDE.md

@@ -12,6 +12,7 @@ Rule files installed into `~/.claude/rules/` by `bin/install.mjs`. Claude Code l
 | File | Rule |
 |---|---|
 | `agent-spawn-protocol.md` | Protocol for spawning subagents: context sufficiency check, prompt generation via `/prompt-generator`, then spawn |
+| `anti-corollary-tests.md` | Tests must carry information: no corollary matrices over canonical reductions, no suite that only matches a dead-implementation default, stated mutation in the audit lane |
 | `ask-user-question-required.md` | Every user-directed question goes through the `AskUserQuestion` tool — no plain-text questions |
 | `bdd.md` | BDD discovery-driven development workflow and Example Mapping reference |
 | `claude-md-orphan-file.md` | Every backticked bare filename in a per-directory `CLAUDE.md` table's first column names a file in that directory's subtree |

package/rules/anti-corollary-tests.md

@@ -0,0 +1,69 @@
+---
+paths:
+  - "**/test_*.py"
+  - "**/*_test.py"
+  - "**/*.test.*"
+  - "**/*.spec.*"
+  - "**/conftest.py"
+  - "**/tests/**"
+---
+
+# Anti-Corollary Tests
+
+**When this applies:** Any Write or Edit that adds or changes tests.
+
+## Rule
+
+A large green suite can prove almost nothing. Before you keep a case, answer three questions. If any answer fails, cut the case or replace it with one that carries information.
+
+## The three questions
+
+### 1. Is this a corollary?
+
+When the code reduces each input to a canonical form and then compares the forms, every pairwise combination of input spellings follows once the reduction is proven canonical. Walking the full N×N matrix restates that fact. It adds cases and runtime, and it buries the few cases that carry information.
+
+**Do this:** test the reduction once. Test the comparison with a few discriminating cases. Do not walk the cross product of spellings.
+
+### 2. Could this test pass if the mechanism were dead?
+
+Name the degenerate value a dead implementation would return — empty string, `None`, `False`, a blanket refusal, an empty collection. When the test's expected value equals that default, the test passes whether the mechanism works or not. On its own it proves nothing.
+
+**Do this:** keep at least one case that expects the **non-default** answer, and drive the real code path — not a mock that only records that a call happened.
+
+### 3. What single change to the code would make this test fail?
+
+When the honest answer is "none," or "only a change that also breaks everything else," the test is decoration. Drop it or rewrite it so one named mutation kills it.
+
+## What a mechanism with a degenerate failure mode needs
+
+1. **At least one non-default case** that exercises the live path and expects the non-default answer.
+2. **A stated mutation (audit lane):** name one specific change to the code and record how many tests it kills. A mutation that kills zero tests means the suite proves nothing. A reviewer or an audit skill checks this; a hook does not compute it.
+3. **A few discriminating cases** in place of a large matrix.
+
+## Worked shape (sanitized)
+
+A write guard decides whether a write is about to hit a production database. It reduces each database URL to a canonical endpoint identity, then compares identities.
+
+Two independent mutations show the two halves of a useful suite:
+
+- Gut the reduction so it always returns the empty string: the guard fails **closed** and refuses everything. Only the *allow*-expecting cases die.
+- Abandon the reduction and compare raw hostnames: the guard fails **open** and allows a production write. Only the *refuse*-expecting cases die.
+
+Opposite breaks kill opposite halves. A suite with only one half cannot see one of those breaks. Build both halves; skip the spelling matrix once the reduction is covered.
+
+## What this is not
+
+A structural hook is the wrong tool here. "Is this a corollary?" and "would this pass against a dead implementation?" need the intent of the code under test. A hook that pattern-matches `parametrize` breadth or counts assertions fires on correct suites and trains people to ignore it. A false-positive gate on a judgment call is worse than no gate. This rule stays judgment-only, with the stated-mutation check in the audit lane — the same pattern as other judgment rules in this package that have no Write/Edit blocker.
+
+## Sibling rules
+
+| Rule | Role |
+|---|---|
+| `tdd.md` | Write a failing test before production code |
+| `testing.md` | Mocks and test infrastructure standards |
+| `paired-test-coverage.md` | Every public function in an established suite gets a behavioral test |
+| `anti-corollary-tests.md` | Each test carries information; no corollary matrices; no suite that only matches the dead default |
+
+## Enforcement
+
+The AI review lane and audit skills carry this rule: an agent applies it to the test lines a PR changes. No blocking hook backs it, because corollary and dead-default judgments need meaning a regex cannot read.

package/rules/bdd.md

@@ -2,8 +2,6 @@
 
 **Canonical detail:** `~/.claude/system-prompts/software-engineer.xml` → `<behavior_protocol>`.
 
-**On-demand depth:** `@~/.claude/skills/bdd-protocol/SKILL.md` (Example Mapping §6.4, §7.6 catalog, solo patterns). Tracking design: [jl-cmd/claude-dev-env#82](https://github.com/jl-cmd/claude-dev-env/issues/82).
-
 **Optional long-form references (load when needed):**
 
 - `@~/.claude/docs/BDD_SCENARIO_QUALITY.md` — seven scenario quality patterns (§7.6-style)
@@ -21,7 +19,7 @@ Conversation is the essential practice: if discovery is skipped, structured form
 
 ## Solo developer
 
-You are often the stakeholder. Use **Example Mapping** in chat ("the one where …", probes, parking lot). Load **`bdd-protocol`** when you need the full algorithm and anti-pattern list.
+You are often the stakeholder. Use **Example Mapping** in chat ("the one where …", probes, parking lot). See the optional long-form references above for the full algorithm and anti-pattern list.
 
 ## Naming
 

package/rules/code-reviews.md

@@ -2,7 +2,7 @@
 
 **When this applies:** GitHub PR review feedback on a branch you are fixing.
 
-**MANDATORY PROTOCOL (use pr-review-responder skill):**
+**MANDATORY PROTOCOL:**
 
 1. Fetch ALL reviewer comments BEFORE any fixes
 2. Create TodoWrite checklist - One item per comment

package/rules/gh-paginate.md

@@ -1,3 +1,3 @@
 # gh API Pagination
 
-Every `gh api` read of a paginated GitHub list endpoint (PR `reviews`/`comments`/`files`, issue `comments`, `pulls`, `issues`) uses `--paginate --slurp` piped to **external** `jq` — `gh`'s built-in `--jq` runs per page, so cross-page operations like `sort_by | last` give wrong-but-confident results. Single-object endpoints (`pulls/<n>`, `issues/<n>`) skip pagination and may use `--jq` directly. Full safe patterns (single-page bounds, newest-first walks): gh-paginate skill.
+Every `gh api` read of a paginated GitHub list endpoint (PR `reviews`/`comments`/`files`, issue `comments`, `pulls`, `issues`) uses `--paginate --slurp` piped to **external** `jq` — `gh`'s built-in `--jq` runs per page, so cross-page operations like `sort_by | last` give wrong-but-confident results. Single-object endpoints (`pulls/<n>`, `issues/<n>`) skip pagination and may use `--jq` directly. For a newest-first walk, sort the slurped array and take the last element; for single-page bounds, cap with a `per_page` query parameter.

package/rules/plain-language.md

@@ -3,3 +3,5 @@
 All prose a person reads (chat, `AskUserQuestion`, docs, PR/issue bodies, commits): everyday words, short active sentences, lead with the answer, define jargon on first use, and give only the detail the reader needs to act (progressive disclosure). Aim for first-pass readability by a non-specialist. Exact identifiers, file paths, and API names stay exact; code is out of scope.
 
 The `plain_language_blocker` PreToolUse hook (AskUserQuestion + `.md` Write/Edit/MultiEdit) blocks a heavy word and names the everyday swap; code fences, inline code, blockquotes, URLs, and file paths are skipped.
+
+A project can keep its own domain words out of the check with a `.claude/plain-language-allow.json` file: a JSON array of terms. An exact, case-insensitive, whole-word match on any term passes. The hook reads this file only from inside the project tree, up to the repository root, so each project's allowlist stays with its own code.

package/scripts/CLAUDE.md

@@ -8,9 +8,13 @@ Utility scripts installed into `~/.claude/scripts/` by `bin/install.mjs`. Each s
 |---|---|
 | `claude_chain_runner.py` | Runs a `claude` invocation through a config-driven fallback chain (`~/.claude/claude-chain.json`): the leading binary serves the call, and only a usage-limit failure falls over to the next logged-in binary; usable as an imported module (`run_claude`) or a CLI. Copy `claude-chain.example.json` to `~/.claude/claude-chain.json` and list your binaries in fallback order |
 | `gh_artifact_upload.py` | Uploads a file to a repo's durable `artifacts` prerelease under a timestamped asset name and prints the permanent download URL a GitHub post can link |
+| `grok_headless_runner.py` | Runs one worker as headless `grok`: builds argv, mints a unique leader socket, captures streams, kills on timeout with grace, classifies ok/usage_limit/auth_failure/timeout/error; imported by `spawn_grok_batch.py` |
+| `grok_worker_preflight.py` | Soft gate for the headless grok tier: binary on PATH, `grok models` auth, install manifest + role agents, opt-in cached live ping; non-zero exit is fallthrough, not failure |
 | `setup_project_paths.py` | One-time bootstrap: discovers git repos via `es.exe` (Everything) and writes `~/.claude/project-paths.json`; never hardcodes scan roots |
+| `spawn_grok_batch.py` | Launches a fleet of headless grok workers from a JSON batch spec: gates once through the preflight, assembles each prompt from part files, staggers starts, runs each through `grok_headless_runner.py`, and emits one batch summary JSON |
 | `sweep_empty_dirs.py` | Deletes empty directories older than a configurable age under a given root; runs once (`--once`) or in continuous-watch mode |
 | `sync_to_cursor.py` | Entry point for syncing Claude rules to Cursor `.mdc` files; delegates to the `sync_to_cursor/` package |
+| `resolve_worker_spawn.py` | Dispatches a worker role through grok then claude fallback tiers (preflight, headless grok, `claude_agent_required` handoff, optional claude headless); protocol: [`../_shared/pr-loop/worker-spawn.md`](../_shared/pr-loop/worker-spawn.md) |
 
 ## PowerShell scripts
 

package/scripts/dev_env_scripts_constants/CLAUDE.md

@@ -6,11 +6,13 @@ Named constants for scripts in `scripts/`. Follows the project convention that t
 
 | File | Constants for |
 |---|---|
-| `timing.py` | `sweep_empty_dirs.py` — `DEFAULT_AGE_SECONDS` (smallest age before an empty directory is eligible for removal) and `DEFAULT_POLL_INTERVAL` (seconds between sweep passes in continuous-watch mode) |
-| `gh_artifact_upload_constants.py` | `gh_artifact_upload.py` — the `artifacts` release tag, title, and notes body, the GitHub CLI binary name, the asset-name timestamp format and template, the asset download URL template, the notes-file suffix, and the text encoding |
-| `claude_chain_constants.py` | `claude_chain_runner.py` — the chain config filename and home subdirectory, the usage-limit signature text, the per-binary status labels, the default timeout, CLI flag and separator tokens, config JSON keys, invalid-shape reason text, config-error and exhausted-chain message templates, and CLI exit codes |
+| `timing.py` | `sweep_empty_dirs.py` - `DEFAULT_AGE_SECONDS` (smallest age before an empty directory is eligible for removal) and `DEFAULT_POLL_INTERVAL` (seconds between sweep passes in continuous-watch mode); `spawn_grok_batch.py` - `WORKER_STAGGER_SECONDS` (seconds between staggered headless grok worker starts); `invoke_code_review.py` - `DEFAULT_CODE_REVIEW_TIMEOUT_SECONDS` (timeout for one headless `/code-review` chain run) |
+| `gh_artifact_upload_constants.py` | `gh_artifact_upload.py` - the `artifacts` release tag, title, and notes body, the GitHub CLI binary name, the asset-name timestamp format and template, the asset download URL template, the notes-file suffix, and the text encoding |
+| `claude_chain_constants.py` | `claude_chain_runner.py` - the chain config filename and home subdirectory, the usage-limit signature text, the per-binary status labels, the default timeout, CLI flag and separator tokens, config JSON keys, invalid-shape reason text, config-error and exhausted-chain message templates, and CLI exit codes |
+| `grok_worker_constants.py` | `grok_worker_preflight.py`, `grok_headless_runner.py`, and `spawn_grok_batch.py` - the `grok` binary name and CLI flags, model and subcommand tokens, leader-socket and scratch-file name parts, auth and usage-limit signature lists, outcome classifications, fallthrough reasons, tool-profile names and prompt headers, timeouts and turn caps (including launch-failure return code and post-kill grace), ping-cache keys and TTL, batch-spec and summary JSON keys, the prompt-part and report-stream join separators, and the CLI launch-error stderr prefix |
+| `code_review_constants.py` | `invoke_code_review.py` - the `/code-review high --fix` prompt, opus model alias, permission-mode flag and value, result mode and JSON keys, session-model CLI flag, git dirty-check tokens, and in-session return markers |
 | `__init__.py` | Empty package marker |
 
 ## Convention
 
-Every constant is `UPPER_SNAKE_CASE` with an explicit type annotation and a docstring. Scripts import from here rather than embedding literal values in their bodies.
+Every constant is `UPPER_SNAKE_CASE` with an explicit type annotation and a docstring. Scripts import from here rather than embedding literal values in their bodies.

package/scripts/dev_env_scripts_constants/code_review_constants.py

@@ -0,0 +1,71 @@
+"""Named constants for the host-aware `/code-review` invoker.
+
+`invoke_code_review.py` imports every scalar and structural constant it
+needs from this module (and shared flag tokens from
+`grok_worker_constants`) so the prompt, model alias, and JSON keys are
+never hardcoded twice.
+"""
+
+from __future__ import annotations
+
+CODE_REVIEW_SLASH_COMMAND: str = "/code-review"
+"""Built-in Claude Code slash command that runs the repository review."""
+
+CODE_REVIEW_EFFORT: str = "high"
+"""Effort level passed to the built-in review slash command."""
+
+CODE_REVIEW_FIX_FLAG: str = "--fix"
+"""Slash-command flag that applies automatic fixes for review findings."""
+
+CODE_REVIEW_PROMPT: str = (
+    f"{CODE_REVIEW_SLASH_COMMAND} {CODE_REVIEW_EFFORT} {CODE_REVIEW_FIX_FLAG}"
+)
+"""Single-turn prompt that runs the built-in review slash command with fixes."""
+
+CODE_REVIEW_MODEL_ALIAS: str = "opus"
+"""CLI `--model` short alias the review always pins to."""
+
+PERMISSION_MODE_FLAG: str = "--permission-mode"
+"""CLI flag that selects how the headless claude process handles tool permission prompts."""
+
+PERMISSION_MODE_BYPASS: str = "bypassPermissions"
+"""Permission-mode value that auto-approves tools for unattended chain runs."""
+
+MODE_IN_SESSION: str = "in_session"
+"""Result mode when the host is Claude and the session already runs opus."""
+
+MODE_CHAIN: str = "chain"
+"""Result mode when the helper spawns a headless claude chain for the review."""
+
+RESULT_KEY_MODE: str = "mode"
+"""JSON result key naming the review mode (`in_session` or `chain`)."""
+
+RESULT_KEY_SERVED_COMMAND: str = "served_command"
+"""JSON result key naming the chain binary that served the call, or null."""
+
+RESULT_KEY_RETURNCODE: str = "returncode"
+"""JSON result key holding the process return code from the chain run."""
+
+RESULT_KEY_DIRTY_TREE: str = "dirty_tree"
+"""JSON result key holding whether the working tree is dirty after the review."""
+
+CLI_SESSION_MODEL_FLAG: str = "--session-model"
+"""CLI flag naming the caller's current session model short alias."""
+
+GIT_BINARY: str = "git"
+"""Executable name resolved on PATH for working-tree dirty checks."""
+
+GIT_STATUS_SUBCOMMAND: str = "status"
+"""Git subcommand used to detect an uncommitted dirty working tree."""
+
+GIT_PORCELAIN_FLAG: str = "--porcelain"
+"""Git status flag that prints machine-readable dirty-path lines."""
+
+IN_SESSION_RETURNCODE: int = 0
+"""Return code reported when the helper hands the review back to the in-session skill."""
+
+HOST_PROFILE_ERROR_RETURNCODE: int = 1
+"""Return code when host-profile detection raises ValueError at the CLI boundary."""
+
+SUCCESSFUL_REVIEW_RETURNCODE: int = 0
+"""Return code required before a clean stamp may advance past CODE_REVIEW."""