claude-dev-env 2.4.0 → 2.5.0

package/commands/implement.md

@@ -5,7 +5,7 @@ allowed-tools: Task, Read, Grep, Glob
 
 **Implementation with Full Context - XML-Structured Guidance**
 
-Launch a clean-coder agent with COMPREHENSIVE implementation context provided in structured XML format.
+Launch a clean-coder agent — `model: sonnet`, worker-model routing per [`skills/orchestrator/SKILL.md`](../skills/orchestrator/SKILL.md#workflow-agent-routing); resolver-supplied sonnet-equivalent on third-party hosts — with COMPREHENSIVE implementation context provided in structured XML format.
 
 ## Process:
 

package/commands/right-size.md

@@ -3,7 +3,7 @@ description: Prevent over/under-engineering
 allowed-tools: Task
 ---
 
-Launch the clean-coder agent to review code for appropriate engineering practices.
+Launch the clean-coder agent — `model: sonnet`, worker-model routing per [`skills/orchestrator/SKILL.md`](../skills/orchestrator/SKILL.md#workflow-agent-routing); resolver-supplied sonnet-equivalent on third-party hosts — to review code for appropriate engineering practices.
 
 The agent will evaluate whether abstractions, patterns, and practices match the actual needs of the project, ensuring code is neither over-engineered nor under-engineered for its current scale and purpose.
 

package/docs/CLAUDE.md

@@ -18,6 +18,7 @@ Reference documentation installed into `~/.claude/docs/` by `bin/install.mjs`. T
 | `nas-ssh-invocation.md` | Full NAS ssh policy behind the `rules/nas-ssh-invocation.md` kernel: the OpenSSH binary form, config sources, and hook enforcement |
 | `worker-completion-gate.md` | Full worker-completion gate behind the `rules/workers-done-before-complete.md` kernel: the checklist, examples, and run-state records |
 | `wsl-docker-cowork-starter-matrix.md` | Host matrix: WSL/Docker/cowork component → starter → required? → shutdown; policy options with costs; no unmeasured `.wslconfig` memory cap |
+| `host-pool-health-monitor.md` | Operator recipe for Windows pool/handle health: thresholds, clean-shell re-run of `Capture-PoolHealth.ps1`, RC2/RC3/RC4 remediation map |
 
 ## Subdirectory
 

package/docs/host-pool-health-monitor.md

@@ -0,0 +1,102 @@
+# Host pool health monitor
+
+Operator recipe for kernel pool counters, handle pressure, and pool tags on a Windows host that runs Claude Code / agent tooling. Ships as `scripts/Capture-PoolHealth.ps1` (installed to `~/.claude/scripts/`).
+
+## Verdict this monitor tracks
+
+Evidence capture (`results/04-pool-tags.md` in the ram-process-sprawl plan pack) shows:
+
+| Tag | Pool | Role |
+|-----|------|------|
+| **File** | nonpaged (~multi-GB when bad) | File objects |
+| **IoFE** | nonpaged | I/O / file-object adjacent |
+| **Toke** | paged (~multi-GB when bad) | Security token objects |
+| **Key** | paged | Registry key objects (often Git `find` storms) |
+
+**Primary story:** process-object / object-manager pressure from agent sprawl — not a single third-party driver leak. Fix sprawl with RC2 / RC3 / RC4; re-run this recipe after those land to confirm File/Toke fall.
+
+## Alert thresholds
+
+| Signal | Alert when |
+|--------|------------|
+| `\Memory\Pool Nonpaged Bytes` | **> 2 GB** |
+| Any process `HandleCount` | **> 2000** |
+| `\Process(_Total)\Handle Count` | **> 500000** |
+
+Also watch pool tags **File**, **Toke**, **IoFE**, **Key**, **FMfn** whenever any threshold fires.
+
+## Clean-shell re-run
+
+From a new PowerShell window (no profile, no prior session state):
+
+```powershell
+# After package install (npx claude-dev-env / node bin/install.mjs)
+pwsh -NoProfile -File "$HOME\.claude\scripts\Capture-PoolHealth.ps1"
+
+# Or from a checkout
+pwsh -NoProfile -File "packages\claude-dev-env\scripts\Capture-PoolHealth.ps1"
+
+# Save a snapshot
+pwsh -NoProfile -File "$HOME\.claude\scripts\Capture-PoolHealth.ps1" `
+  -OutPath "$env:TEMP\pool-health-$(Get-Date -Format yyyyMMdd-HHmmss).txt"
+```
+
+Exit code: `0` = all thresholds clear; `1` = one or more alerts. Hard capture failures (for example Get-Counter) stop with a non-zero exit. Soft failures (for example pool-tag walk unavailable) print a warning and can still exit `0` when thresholds are clear.
+
+### What the script prints
+
+1. **Counters** — nonpaged/paged pool, commit, available MB, total handles/threads  
+2. **High-handle processes** — every process over the handle threshold (top N by default)  
+3. **Pool tags** — top nonpaged, top paged, plus File/IoFE/Toke/Key/FMfn watchlist via `NtQuerySystemInformation` class 22 (same source PoolMon uses; no admin and no WDK required)  
+4. **Remediation map** — RC issue pointers below  
+5. **Threshold verdict** — `OK` or `ALERT ...` lines (last; drives exit code)  
+
+### Counters-only one-liner (no tags)
+
+```powershell
+pwsh -NoProfile -Command "
+  Get-Date -Format 'yyyy-MM-dd HH:mm:ss zzz'
+  Get-Counter '\Memory\Pool Nonpaged Bytes','\Memory\Pool Paged Bytes',
+    '\Memory\Committed Bytes','\Memory\Available MBytes',
+    '\Process(_Total)\Handle Count','\Process(_Total)\Thread Count' |
+    Select-Object -ExpandProperty CounterSamples |
+    Format-Table Path, CookedValue -AutoSize
+"
+```
+
+## Remediation map
+
+When nonpaged, handles, or File/Toke tags are high, apply the sprawl fixes — not a random driver unload.
+
+| RC | Issue | What it cuts | Expected pool/handle effect |
+|----|-------|--------------|-----------------------------|
+| **RC2** | [#255](https://github.com/jl-cmd/claude-dev-env/issues/255) Cap MCP servers — stop per-session mcpvault/playwright/serena spawn-without-reap | Extra `node`/MCP process trees | Lower **File** / **Toke** / **Thre** object pressure |
+| **RC3** | [#254](https://github.com/jl-cmd/claude-dev-env/issues/254) `Show-Asset.ps1` exit on parent death + timeout | Orphan UI/`Application.Run` processes | Lower process count and handle tables |
+| **RC4** | [#253](https://github.com/jl-cmd/claude-dev-env/issues/253) Block Git `find` filesystem walks; `es.exe` primary; kill runaway `find` (>2k handles) | Orphan `Git\usr\bin\find.exe` with 10^5–10^6 **Key** handles | Sharp drop in total handles and **Key** paged; secondary relief on object manager |
+| **RC5** | [#256](https://github.com/jl-cmd/claude-dev-env/issues/256) Attribute WSL/Docker/cowork VM starters | `vmmem*` / **VdMm** | Secondary only — measure first; no blind `.wslconfig` memory cap |
+
+**Do not** treat multi-GB **File**/**Toke** as “install poolmon and hunt NVRM.” NVRM/VdMm appear as tens of MB in the evidence pack; the multi-GB leaders are object-class tags.
+
+### Emergency: runaway `find.exe`
+
+```powershell
+Get-CimInstance Win32_Process -Filter "Name='find.exe'" |
+  Select-Object ProcessId, ParentProcessId, HandleCount, CommandLine
+# If HandleCount > 2000 and parent is dead → stop the process (RC4 policy)
+```
+
+## After RC2 / RC3 / RC4 land
+
+1. Idle the agent host (no active find storms, no orphan Show-Asset, MCP set capped).  
+2. Re-run `Capture-PoolHealth.ps1` from a clean shell.  
+3. Confirm: nonpaged trend down, total handles under 500k when idle, **File**/**Toke** tag bytes down vs the 04-pool-tags baseline.  
+
+## Optional: stock `poolmon.exe`
+
+This recipe does **not** need the WDK. Operators who prefer the Microsoft binary can install Windows Driver Kit tools and run elevated `poolmon -b` snapshots. Tag names still map through `pooltag.txt` under Windows Kits Debuggers when present.
+
+## Related
+
+- Parent epic: [#252](https://github.com/jl-cmd/claude-dev-env/issues/252)  
+- This child: [#257](https://github.com/jl-cmd/claude-dev-env/issues/257)  
+- Script: `packages/claude-dev-env/scripts/Capture-PoolHealth.ps1`  

package/docs/references/CLAUDE.md

@@ -1,6 +1,6 @@
 # docs/references
 
-Pointer documents to external sources and standard terminology. Files here are loaded on demand by rules that cite external resources.
+Pointer documents to external sources, standard terminology, and internal tool or skill usage. Files here are loaded on demand by rules that cite them.
 
 ## Files
 
@@ -8,7 +8,9 @@ Pointer documents to external sources and standard terminology. Files here are l
 |---|---|
 | `dead-code-elimination.md` | External sources and standard terms behind CODE_RULES §9.8 (remove code you orphan): DCE, tree shaking, reachability analysis, and the Lava Flow anti-pattern |
 | `code-review-enforcement.md` | How the code-review gates work: the two required efforts (push at low, PR creation at xhigh), the stamp bound to the branch-surface hash, the single sanctioned minter, the two-layer stamp-directory guard, and the bypass surfaces the gates leave open |
+| `advisor-tool.md` | The `advisor()` tool: a no-parameter review call that forwards the full conversation history to a stronger reviewer model, and when to call it |
+| `team-advisor-skill.md` | The `/team-advisor` skill: spawning a standing review agent at the strongest reachable tier, and how it relates to the `advisor()` tool |
 
 ## Role
 
-Each file names an external concept, gives a one-line definition, and links a direct source. They back the rule text in `rules/` and `packages/claude-dev-env/docs/CODE_RULES.md` without embedding full third-party content inline.
+A file naming an external concept gives a one-line definition and links a direct source. A file naming an internal tool or skill describes what it does and when to use it. They back the rule text in `rules/` and `packages/claude-dev-env/docs/CODE_RULES.md` without embedding full third-party content inline.

package/docs/references/advisor-tool.md

@@ -0,0 +1,13 @@
+# Advisor Tool
+
+`advisor()` is a review tool backed by a stronger reviewer model. It takes no parameters — calling it forwards the entire conversation history automatically, so the reviewer sees the task, every tool call made, and every result seen so far.
+
+## When to call it
+
+Call `advisor()` before substantive work: before writing, before committing to an interpretation, before building on an assumption. Orientation work — finding files, fetching a source, seeing what exists — comes first; call `advisor()` once that orientation is done and before the substantive step begins.
+
+Treat the advisor as more experienced than the calling agent. Consult it whenever a path forward is uncertain.
+
+## Availability
+
+`advisor()` is present only in environments where it has been configured as a tool. Check the available tools before relying on it; when it is absent, fall back to `/team-advisor` (see `team-advisor-skill.md` in this directory).

package/docs/references/code-review-enforcement.md

@@ -9,6 +9,16 @@ This feature ties two git actions to a clean run of the built-in
 
 The gates follow the same shape as the `verified_commit` gate family.
 
+## Opt-in (default off)
+
+Enforcement is **off by default**. The master flag is
+`CODE_REVIEW_ENFORCEMENT_ENABLED` in
+`hooks/blocking/config/code_review_enforcement_constants.py`. Set it to
+`True` to enable the push gate, the PR-create gate, the native pre-push
+backstop (via the shared deny decision), and the stamp-directory write
+blocker. When the flag is `False`, every gate allows the action and the
+write-blocker allows stamp-directory access.
+
 ## How a stamp works
 
 A stamp is a small JSON file that records one fact: a clean `/code-review` pass

package/docs/references/team-advisor-skill.md

@@ -0,0 +1,14 @@
+# Team-Advisor Skill Invocation
+
+`/team-advisor` spawns a standing review agent for the session at the strongest reachable model tier, run at the highest reasoning effort. Use it to get a second opinion from a distinct model line than the one driving the session. For example:
+
+- Claude session -> consult Fable xhigh
+- Codex session -> consult Sol xhigh
+
+## When to use it
+
+Consult the spawned advisor before big decisions, before declaring work complete, before any commit, when a failure repeats, or when reconsidering a chosen approach.
+
+## Relationship to the advisor tool
+
+`/team-advisor` works standalone; it needs no `advisor()` tool present. When both are available (see `advisor-tool.md` in this directory), use `advisor()` for a fast, history-forwarding check before substantive work, and `/team-advisor` for a standing reviewer consulted at decision points.

package/hooks/blocking/CLAUDE.md

@@ -69,6 +69,7 @@ The check modules it calls are the `code_rules_<concern>.py` files below.
 
 | File | Event | What it blocks |
 |---|---|---|
+| `orchestrator_refresh_reschedule_gate.py` | PreToolUse (ScheduleWakeup/CronCreate) | `/orchestrator-refresh` re-arm when run status is not `active` |
 | `block_main_commit.py` | PreToolUse (Bash) | `git commit`/`git push` directly to `main` |
 | `bot_mention_comment_blocker.py` | PreToolUse (Write/Edit) | PR review comments that @-mention a bot |
 | `claude_md_orphan_file_blocker.py` | PreToolUse (Write/Edit/MultiEdit) | Per-directory `CLAUDE.md` table cells naming a bare filename absent from the directory subtree |

package/hooks/blocking/code_review_pr_create_gate.py

@@ -1,7 +1,8 @@
 """PreToolUse gate: PR create lands only behind a clean xhigh code-review stamp.
 
-Fires on Bash/PowerShell ``gh pr create`` and on the MCP
-``create_pull_request`` tool. Resolves the repository from the session
+Fires when ``CODE_REVIEW_ENFORCEMENT_ENABLED`` is on (default off). Runs on
+Bash/PowerShell ``gh pr create`` and on the MCP ``create_pull_request``
+tool. Resolves the repository from the session
 working directory (or the payload cwd), computes the live change-surface
 hash, and allows the create only when a clean stamp at effort ``xhigh`` or
 higher covers that exact hash under ``~/.claude/code-review-stamps/``.
@@ -40,6 +41,7 @@ try:
     from code_review_stamp_store import live_surface_hash, stamp_covers_surface
     from config.code_review_enforcement_constants import (
         ALL_GATED_SHELL_TOOL_NAMES,
+        CODE_REVIEW_ENFORCEMENT_ENABLED,
         GH_PR_CREATE_INVOCATION_PATTERN,
         HASH_PREVIEW_LENGTH,
         MCP_CREATE_PULL_REQUEST_TOOL_NAME,
@@ -98,7 +100,7 @@ def deny_reason_for_directory(target_directory: str) -> str | None:
 
     ::
 
-        no repo / empty surface / covering xhigh stamp   -> None (allow)
+        enforcement off / no repo / empty surface / covering xhigh stamp -> None
         production surface without xhigh-or-higher stamp -> corrective (deny)
 
     Args:
@@ -108,6 +110,8 @@ def deny_reason_for_directory(target_directory: str) -> str | None:
         The deny reason when the surface needs a clean xhigh stamp and none
         covers it; None when the create may proceed.
     """
+    if not CODE_REVIEW_ENFORCEMENT_ENABLED:
+        return None
     repo_root = resolve_repo_root(target_directory)
     if repo_root is None:
         return None

package/hooks/blocking/code_review_push_gate.py

@@ -1,7 +1,8 @@
 """PreToolUse gate: git push lands only behind a clean low code-review stamp.
 
-Fires on Bash/PowerShell tool calls. When the command carries a ``git push``,
-the gate resolves each repository the push targets, computes the live
+Fires on Bash/PowerShell tool calls when ``CODE_REVIEW_ENFORCEMENT_ENABLED``
+is on (default off). When the command carries a ``git push``, the gate
+resolves each repository the push targets, computes the live
 change-surface hash against the merge base, and allows the push only when a
 clean stamp at effort ``low`` or higher covers that exact hash under
 ``~/.claude/code-review-stamps/``.
@@ -44,6 +45,7 @@ try:
     from config.code_review_enforcement_constants import (
         ALL_GATED_SHELL_TOOL_NAMES,
         CODE_REVIEW_BYPASS_MARKER,
+        CODE_REVIEW_ENFORCEMENT_ENABLED,
         GATED_PUSH_SUBCOMMANDS,
         HASH_PREVIEW_LENGTH,
         PUSH_GATE_CORRECTIVE_MESSAGE,
@@ -69,8 +71,9 @@ except ImportError as import_error:
 def deny_reason_for_directory(target_directory: str) -> str | None:
     """Decide whether a push from a directory must be blocked.
 
-    Allowed when the directory is no repo, has no upstream base, is a
-    mechanically exempt surface, or a clean low-or-higher stamp covers it.
+    Allowed when enforcement is off, the directory is no repo, has no upstream
+    base, is a mechanically exempt surface, or a clean low-or-higher stamp
+    covers it.
 
     Args:
         target_directory: The directory the push targets.
@@ -78,6 +81,8 @@ def deny_reason_for_directory(target_directory: str) -> str | None:
     Returns:
         The deny reason when the surface lacks a covering low stamp, else None.
     """
+    if not CODE_REVIEW_ENFORCEMENT_ENABLED:
+        return None
     repo_root = resolve_repo_root(target_directory)
     if repo_root is None:
         return None

package/hooks/blocking/code_review_stamp_directory_write_blocker.py

@@ -1,6 +1,9 @@
 #!/usr/bin/env python3
 """PreToolUse guard: deny shell and file-tool access to the stamp directory.
 
+Runs only when ``CODE_REVIEW_ENFORCEMENT_ENABLED`` is on (default off); with
+the flag off the guard allows every stamp-directory access.
+
 The push and PR-create gates trust a single invariant: only
 ``invoke_code_review.py --record-stamp`` mints stamp files under
 ``~/.claude/code-review-stamps/``. settings.json cannot be the only shipped
@@ -53,6 +56,7 @@ try:
         ALL_GATED_SHELL_TOOL_NAMES,
         ALL_STAMP_STORE_FORGE_PATTERNS,
         ALL_WRITE_EDIT_TOOL_NAMES,
+        CODE_REVIEW_ENFORCEMENT_ENABLED,
         DENY_PERMISSION_DECISION,
         PRE_TOOL_USE_HOOK_EVENT_NAME,
         RELATIVE_STAMP_DIRECTORY_PATTERN,
@@ -296,6 +300,8 @@ def decision_for_payload(
 ) -> dict[str, dict[str, str]] | None:
     """Build the deny decision for stamp-directory shell or file-tool access.
 
+    Returns None immediately when `CODE_REVIEW_ENFORCEMENT_ENABLED` is off.
+
     Args:
         all_pretooluse_payload: The PreToolUse hook payload.
 
@@ -303,6 +309,8 @@ def decision_for_payload(
         The deny decision mapping when a gated tool targets the stamp
         directory; None when the tool call may proceed.
     """
+    if not CODE_REVIEW_ENFORCEMENT_ENABLED:
+        return None
     tool_name = all_pretooluse_payload.get("tool_name", "")
     if not isinstance(tool_name, str):
         return None

package/hooks/blocking/config/__init__.py

@@ -1,5 +1,5 @@
-"""Configuration package for the blocking hooks.
-
-A regular package (not a namespace package) so it resolves ahead of any
-same-named package later on ``sys.path``.
-"""
+"""Configuration package for the blocking hooks.
+
+A regular package (not a namespace package) so it resolves ahead of any
+same-named package later on ``sys.path``.
+"""

package/hooks/blocking/config/code_review_enforcement_constants.py

@@ -6,11 +6,14 @@ out because it needs an interactive terminal), the effort a push and a
 pull-request creation each require, the stamp record keys, the gate and
 write-blocker messages, the store-forge shell patterns, the MCP create-PR
 tool name, and the effort comparison every gate and the stamp store share so
-the thresholds never drift between them.
+the thresholds never drift between them, and the master enable flag
+(``CODE_REVIEW_ENFORCEMENT_ENABLED``, default off) that every gate and
+the stamp-directory write-blocker read before they enforce anything.
 """
 
 from __future__ import annotations
 
+CODE_REVIEW_ENFORCEMENT_ENABLED = False
 STAMP_DIRECTORY_NAME = "code-review-stamps"
 ALL_EFFORT_TOKENS_IN_ASCENDING_ORDER = ("low", "medium", "high", "xhigh", "max")
 PUSH_REQUIRED_EFFORT = "low"

package/hooks/blocking/config/test_code_review_enforcement_constants.py

@@ -23,6 +23,7 @@ _constants_module = importlib.util.module_from_spec(_constants_spec)
 _constants_spec.loader.exec_module(_constants_module)
 
 effort_meets_threshold = _constants_module.effort_meets_threshold
+CODE_REVIEW_ENFORCEMENT_ENABLED = _constants_module.CODE_REVIEW_ENFORCEMENT_ENABLED
 PUSH_REQUIRED_EFFORT = _constants_module.PUSH_REQUIRED_EFFORT
 PR_CREATE_REQUIRED_EFFORT = _constants_module.PR_CREATE_REQUIRED_EFFORT
 GATED_PUSH_SUBCOMMANDS = _constants_module.GATED_PUSH_SUBCOMMANDS
@@ -106,3 +107,7 @@ def test_push_gate_message_names_the_push_action_and_low_effort() -> None:
 
 def test_guard_message_directs_users_to_the_sanctioned_minter_flag() -> None:
     assert SANCTIONED_STAMP_MINTER_FLAG in STAMP_DIRECTORY_GUARD_MESSAGE
+
+
+def test_enforcement_defaults_to_off() -> None:
+    assert CODE_REVIEW_ENFORCEMENT_ENABLED is False