claude-dev-env 2.3.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

@@ -17,6 +17,8 @@ Reference documentation installed into `~/.claude/docs/` by `bin/install.mjs`. T
 | `agent-spawn-protocol.md` | Full agent-spawn protocol behind the `rules/agent-spawn-protocol.md` kernel: context-sufficiency check, `/prompt-generator` prompt crafting, and the spawn step |
 | `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,13 +1,16 @@
 # 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
 
 | File | Purpose |
 |---|---|
 | `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

@@ -0,0 +1,107 @@
+# Code-review enforcement
+
+This feature ties two git actions to a clean run of the built-in
+`/code-review --fix`:
+
+- **`git push`** needs a clean review at effort **low** or higher.
+- **Pull-request creation** (`gh pr create` and the MCP `create_pull_request`
+  tool) needs a clean review at effort **xhigh** or higher.
+
+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
+ran against an exact branch surface at a given effort. Each work tree keeps one
+file under `~/.claude/code-review-stamps/`, named by a hash of the resolved
+work-tree path.
+
+The stamp binds to a **branch-surface hash** — the hash of every changed path
+and untracked file, each bound by its content digest, measured against the
+merge base. When any byte of the change surface moves, the live hash stops
+matching the stored hash, so the stamp stops covering the surface and the gate
+asks for a fresh review.
+
+A gate allows the action only when a stored stamp matches the live hash exactly
+and its effort ranks at or above the effort the action needs. A missing,
+unreadable, or malformed stamp reads as no coverage, so the gate fails closed.
+
+## The single sanctioned minter
+
+Only `invoke_code_review.py --record-stamp` writes a stamp. It forces a headless
+`/code-review <effort> --fix` run, then mints a stamp only when the review
+returns a clean exit code and leaves the branch surface unchanged in the same
+pass. A pass that applies fixes mints nothing; the run loops on the new surface
+up to a capped number of passes and mints only on a stable clean pass.
+
+## Two layers guard the stamp directory
+
+The gates trust one rule: only the sanctioned minter writes stamp files. Two
+layers hold that rule.
+
+1. **File-tool deny in `settings.json`.** `Write`, `Edit`, and `MultiEdit`
+   under `~/.claude/code-review-stamps/` are denied. This layer covers work
+   inside the repository. The installer merges hook groups into a user's
+   `settings.json` and does not ship this package's `permissions.deny`, so on a
+   user's machine this layer protects contributor work, at parity with the
+   `verified_commit` gate's own file-tool deny.
+2. **`code_review_stamp_directory_write_blocker` hook.** This hook ships through
+   `hooks.json`, so it reaches every install. It has two arms:
+   - a shell arm that denies any Bash or PowerShell command naming the stamp
+     directory, or importing the stamp store module, or calling its mint
+     function — while it lets the sanctioned minter command through;
+   - a file-tool arm that denies any `Write`, `Edit`, or `MultiEdit` whose path
+     resolves under the stamp directory. This arm closes the plain file-tool
+     forge on every shipped install, which the package `settings.json` deny
+     cannot reach on its own.
+
+## What the gates block
+
+- **Casual and accidental forges.** A plain file-tool write to the stamp
+  directory, and a casual shell write to it, are both denied.
+- **Hidden-path and split-step shell forges.** A shell command that assembles
+  the stamp path from hex, base64, or character math is decoded and denied. A
+  command that splits the directory change across steps to walk into the stamp
+  directory is traced and denied.
+- **Lazy skips.** A push or a pull-request creation cannot go ahead without a
+  stamp that matches the live surface at the needed effort.
+
+## What the gates do not block
+
+The chain-mode `/code-review` runs as a subprocess spawn of the `claude`
+binary, not a harness-recorded subagent, so there is no signed sidecar to
+anchor a forgery-proof mint. The stamp reaches the same posture the
+`verified_commit` gate holds, and no further. These bypass surfaces stay open:
+
+- **Pull requests that skip the tool paths.** A PR opened through
+  `gh api -X POST .../pulls` or the GitHub web page never triggers the
+  create-PR gate.
+- **`git push --no-verify`.** This flag tells git to skip the native pre-push
+  hook, so the native backstop does not run.
+- **A rebuilt store.** A script that re-implements the stamp store in memory
+  and writes a matching file can mint a stamp the gates accept.
+
+In short: these gates stop casual forges and lazy skips. They do not stop a
+determined attacker who sets out to defeat them.
+
+## Where the pieces live
+
+- Gates: `hooks/blocking/code_review_push_gate.py`,
+  `hooks/blocking/code_review_pr_create_gate.py`.
+- Stamp store: `hooks/blocking/code_review_stamp_store.py`.
+- Directory guard: `hooks/blocking/code_review_stamp_directory_write_blocker.py`.
+- Shared constants: `hooks/blocking/config/code_review_enforcement_constants.py`.
+- Native backstop: `hooks/git-hooks/pre_push.py` reuses the push gate's
+  `deny_reason_for_directory` so the native hook and the Claude gate share one
+  decision source.
+- Minter: `scripts/invoke_code_review.py --record-stamp`.

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/docs/wsl-docker-cowork-starter-matrix.md

@@ -0,0 +1,89 @@
+# WSL / Docker / Cowork starter matrix
+
+Attribution and policy surface for host memory consumers that sit under WSL2, Docker Desktop, and the Claude Cowork HCS VM. Source evidence: forensic capture summarized on [issue #256](https://github.com/jl-cmd/claude-dev-env/issues/256) (`results/05-wsl-who-started.md` in the local ram-process-sprawl evidence pack). This file records supported starters, whether each component is required for day-to-day agent work, and how to shut it down. It does **not** apply a `.wslconfig` memory cap.
+
+## Hard rules
+
+1. **No unmeasured `.wslconfig` memory cap.** Do not set `memory=` (or other hard caps) in `%UserProfile%\.wslconfig` until (a) the owner of the WSL VM commit is known for the workload under test and (b) a before/after private-working-set measurement is recorded on the same host boot window. A blind cap is out of scope for this matrix.
+2. **Proven starters only.** Rows below use only process-parent, service, HCS owner, registry, and product-log evidence from the capture. Proximity without a parent edge is labeled **unknown**, not a starter claim.
+3. **Two HCS VMs are not one.** Owner=`WSL` maps to `vmmemWSL`. Owner=`cowork-vm-*` maps to plain `vmmem`. Treat them as separate shutdown and policy targets.
+
+## Starter matrix
+
+| Component | Starter / owner (supported) | Required for daily agent work? | Shutdown / stop |
+|-----------|----------------------------|--------------------------------|-----------------|
+| **WSLService** (`wslservice.exe`) | Windows service **WSLService**, StartMode=Auto, parent `services.exe` since boot | **Platform yes** if any WSL2 distro is used; leave Auto unless WSL is retired on the host | `Stop-Service WSLService` only when deliberately disabling WSL; normal idle path is distro shutdown, not service kill |
+| **`vmmemWSL`** (WSL2 utility VM) | HCS VM Owner=`WSL`; worker chain `vmcompute` → `vmwp` → `vmmemWSL` | **Yes while any distro is Running** (`wsl -l -v`) | `wsl --shutdown` (stops all WSL2 distros and the WSL utility VM; disrupts Docker's WSL backend too) |
+| **First user wake of WSL VM** | **Unknown** in the capture (no Security 4688; no surviving user `wsl.exe` from the create second). Docker was **not** up yet at that create time | N/A — attribution gap | Same as `vmmemWSL` once running |
+| **Docker Desktop / `com.docker.backend`** | Docker Desktop launches backend (product log). **HKCU Run** key registers Docker Desktop for logon. Windows service `com.docker.service` was **Stopped** / Manual — engine path is Desktop/backend user-mode | **Only when containers or Docker tooling are in active use** | Quit Docker Desktop (tray → Quit); confirm `com.docker.backend` gone. Optional: remove or disable the HKCU Run value named `Docker Desktop` so logon does not relaunch it |
+| **Live `wsl.exe` for `docker-desktop` + Ubuntu integration** | Parent **`com.docker.backend.exe` (services)** | Same as Docker Desktop | Stop Docker Desktop; or `wsl --shutdown` (broader blast radius) |
+| **Live `wsl.exe` for `code-index-mcp`** | Parent **`codex.exe`** ← **ChatGPT.exe** ← explorer. Command shape: `wsl.exe …/code-index-mcp` | **Only while Codex/ChatGPT needs the Ubuntu MCP indexer** | Exit Codex / ChatGPT app-server session; confirm no `wsl.exe` whose command line is `code-index-mcp` |
+| **Plain `vmmem` (cowork HCS VM)** | HCS VM Owner=`cowork-vm-*` (name match). Chain `vmcompute` → `vmwp` → `vmmem`. **Exact user process that created the VM is unknown** (no live parent edge). Claude Desktop cmdlines carry `cowork-*` schemes; that is label association, not a proven create edge | **Only while Claude Cowork VM features are in use** | Quit Claude Desktop / Cowork UI that owns the session; if the HCS VM remains Running, treat full stop as an open procedure (see open questions). Do **not** assume `wsl --shutdown` stops this VM — it is not Owner=`WSL` |
+| **grok as WSL parent** | **None** in the capture (high-confidence negative) | N/A | N/A |
+| **claude as parent of live `wsl.exe`** | **None** in the capture (high-confidence negative) | N/A for WSL shells; see cowork row for the separate HCS VM | N/A for `wsl.exe` |
+
+### Capture facts that stay fixed for this matrix
+
+These are host-capture facts the matrix must not rewrite:
+
+- Docker autostart comes from the **HKCU `Run` key** entry for Docker Desktop (not the stopped `com.docker.service`).
+- **Codex `code-index-mcp`** is a live holder of `wsl.exe`; it is not the create-time owner of `vmmemWSL` when Codex starts hours later.
+- **cowork-vm** is a **separate** HCS VM and plain `vmmem` consumer; it is not `vmmemWSL`.
+- **grok** and **claude** were **not** parents of any live `wsl.exe` in the capture.
+
+## Open questions
+
+Named gaps only — do not fill these with guesses in policy or code:
+
+1. **Exact user-mode process that first woke the WSL VM** at the `vmmemWSL` create second (Security 4688 / Sysmon not available in the capture).
+2. **Exact process that created HCS `cowork-vm-*` / plain `vmmem`** (parent chain ends at `vmwp` / `vmcompute`).
+3. **Whether a given Docker start was pure logon Run vs interactive tray open** (Run key proves Docker can autostart; a dead parent PID on the backend does not by itself prove which path fired).
+4. **Identity of dead parents** of mid-session Ubuntu `wslhost` processes whose PPID is already recycled.
+5. **Documented, safe idle-stop for the cowork HCS VM** when Claude UI is gone but `hcsdiag` still lists Owner=`cowork-vm-*` Running.
+6. **Whether historical sessions of grok/claude started WSL earlier in a boot** — unprovable without process-creation audit history; live snapshot negatives do not extend backward.
+
+To close (1), (2), (4), or (6): enable process-creation audit (Security 4688) or Sysmon with filters on `wsl.exe`, `vmwp.exe`, and Docker/Claude/Codex image paths, then re-capture on a clean boot.
+
+## Policy options (with costs)
+
+Choose explicitly. None of these options includes an unmeasured `.wslconfig` `memory=` write.
+
+| Option | Action | RAM / sprawl effect (directional) | Cost / risk |
+|--------|--------|-----------------------------------|-------------|
+| **P0 — Observe only** | Keep matrix; no host change | None until a component is stopped | Continues dual-VM + Docker + Codex WSL hold when those apps run |
+| **P1 — Docker on demand** | Remove or disable HKCU Run `Docker Desktop`; start Desktop only when containers are needed | Avoids Docker backend + docker-desktop/Ubuntu integration `wsl.exe` on boots/sessions that never use Docker | Manual start latency; first container work pays cold start; any script that assumes Docker is already up fails until launch |
+| **P2 — Docker fully off when idle** | Quit Docker Desktop after use; optional P1 | Frees backend private set and Docker-held WSL distro activity | Must re-open Desktop before compose/build; `wsl -l -v` may still show Running until `wsl --shutdown` or Docker stops holding distros |
+| **P3 — Codex indexer off when idle** | Exit ChatGPT/Codex app-server when not reviewing; disable code-index MCP if product settings allow | Drops Codex-held `wsl.exe … code-index-mcp` edges | Codex features that need the Ubuntu indexer fail until restart; does **not** by itself tear down `vmmemWSL` if Docker or another client still holds a distro |
+| **P4 — WSL idle shutdown** | When no Docker/Codex/other WSL client is needed: `wsl --shutdown` | Tears down Ubuntu + docker-desktop distros and `vmmemWSL` | **Breaks** any live Docker WSL backend and any in-distro MCP until restart; never use mid-task if containers or WSL MCP are active |
+| **P5 — Cowork VM idle policy** | Quit Claude Cowork/Desktop when the VM is not needed; re-check `hcsdiag list` for Owner=`cowork-vm-*` | Targets plain `vmmem` (~multi-GB private in the capture) without touching Owner=`WSL` | Create/stop procedure for a leftover Running cowork VM is still an open question; wrong kill path can disrupt Cowork artifacts |
+| **P6 — Process-creation audit** | Turn on 4688 or Sysmon for wsl/vmwp/Docker/Claude/Codex | No direct RAM win; closes open questions (1)(2)(4)(6) | Audit volume, privacy review, and storage for event logs |
+| **P7 — `.wslconfig` memory cap** | Set `memory=` under `[wsl2]` | Caps WSL utility VM commit **only after** measured before/after on this host | **Blocked here until measured.** Risk: OOM inside distros, Docker backend instability, false “fix” that leaves cowork `vmmem` untouched |
+
+### Measurement gate for P7 (and any memory cap)
+
+Before any `.wslconfig` memory write:
+
+1. Record `wsl -l -v`, `hcsdiag list`, and private working set for `vmmemWSL` / plain `vmmem` / `com.docker.backend`.
+2. Name which component the cap is meant to bound (Owner=`WSL` only — cowork is outside `.wslconfig`).
+3. Apply cap; reboot or `wsl --shutdown` + re-start workload as required for the setting to apply.
+4. Re-record the same counters under the same workload.
+5. Commit the before/after note next to the policy decision (issue comment or evidence pack). Without that note, leave `.wslconfig` without a memory cap.
+
+## Quick identification commands
+
+Read-only checks agents and operators use on Windows:
+
+```text
+wsl -l -v
+hcsdiag list
+Get-CimInstance Win32_Service -Filter "Name='WSLService'"
+Get-ItemProperty HKCU:\Software\Microsoft\Windows\CurrentVersion\Run
+Get-CimInstance Win32_Process -Filter "Name='wsl.exe'" | Select ProcessId, ParentProcessId, CommandLine
+```
+
+Resolve each `wsl.exe` ParentProcessId to an image name before blaming an agent binary. A missing parent is **unknown**, not proof of a named starter.
+
+## Related
+
+- Issue: [jl-cmd/claude-dev-env#256](https://github.com/jl-cmd/claude-dev-env/issues/256) (child of epic #252)
+- Local forensic write-up: `results/05-wsl-who-started.md` under the host evidence pack path named in the issue body

package/hooks/blocking/CLAUDE.md

@@ -9,6 +9,7 @@ PreToolUse hooks that deny (block) tool calls when a rule is violated. The main
 | `config/` | Shared constants for the verified-commit gate family (`verified_commit_constants.py`) |
 | `tdd_enforcer_parts/` | Concern modules the `tdd_enforcer.py` entry hook wires together: path classification, content analysis, candidate-path resolution, freshness, git-tracking restore detection, decisions, and constants |
 | `verified_commit_gate_parts/` | Concern modules the `verified_commit_gate.py` entry hook wires together: command tokenization, directory-change resolution, gated git-invocation resolution, deny-reason resolution, and deny-payload assembly |
+| `code_review_stamp_write_blocker_parts/` | Concern modules the `code_review_stamp_directory_write_blocker.py` entry hook wires together: the split directory-change-into-stamp matcher and the obfuscated-stamp-path-write matcher |
 | `claude_md_orphan_file_blocker_parts/` | Concern modules the `claude_md_orphan_file_blocker.py` entry hook wires together: reference extraction, subtree scan, scan plan, decision, and constants |
 | `package_inventory_stale_blocker_parts/` | Concern modules the `package_inventory_stale_blocker.py` entry hook wires together: inventory detection, decision, and constants |
 | `inventory_intent_records/` | The shared per-session pending-intent store both inventory blockers read to break the file/row add-order deadlock |
@@ -68,10 +69,14 @@ 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 |
-| `code_verifier_spawn_preflight_gate.py` | PreToolUse (Agent) | Spawning the `code-verifier` subagent when the branch has a merge conflict vs its base or a CODE_RULES violation on a working-tree-added line |
+| `code_review_pr_create_gate.py` | PreToolUse (Bash/MCP GitHub) | `gh pr create` or the MCP `create_pull_request` tool without a clean `xhigh` code-review stamp covering the branch surface |
+| `code_review_push_gate.py` | PreToolUse (Bash/PowerShell) | `git push` without a clean `low` code-review stamp covering the branch surface |
+| `code_review_stamp_directory_write_blocker.py` | PreToolUse (Bash/PowerShell/Write/Edit/MultiEdit) | Shell or file-tool writes into `~/.claude/code-review-stamps/`, and shell references to the stamp store module or its mint call, outside the sanctioned invoker |
+| `code_verifier_spawn_preflight_gate.py` | PreToolUse (Agent) | Spawning the `code-verifier` subagent when the branch has a merge conflict vs its base or a CODE_RULES violation on a working-tree-added line, or the CODE_RULES engine fails to load |
 | `convergence_gate_blocker.py` | PreToolUse (Bash) | Convergence workflow actions on a conflicting PR |
 | `conventional_pr_title_gate.py` | PreToolUse (Bash) | `gh pr create`/`gh pr edit` with a `--title` that is not a Conventional Commit, in a repo whose CI runs a semantic-pull-request title check |
 | `destructive_command_blocker.py` | PreToolUse (Bash/PowerShell) | Shell commands with destructive literals (`rm -rf`, `git reset --hard`, etc.) |
@@ -121,6 +126,9 @@ The check modules it calls are the `code_rules_<concern>.py` files below.
 | File | Role |
 |---|---|
 | `_gh_body_arg_utils.py` | Parsing helpers for `gh_body_arg_blocker.py` |
+| `code_review_enforcement_config_bootstrap.py` | Binds `config.code_review_enforcement_constants` to the sibling `config/` file by explicit location, so the code-review gate family resolves its constants regardless of a foreign `config` package's `sys.path` order |
+| `code_review_gate_deny.py` | Shared deny scaffold for the push and PR-create code-review gates: the `hookSpecificOutput` deny-payload builder and the log-and-emit helper, so both gates share one deny shape |
+| `code_review_stamp_store.py` | Reads and writes the per-work-tree code-review stamp files under `~/.claude/code-review-stamps/`, and decides whether a clean stamp at the needed effort covers the live branch surface |
 | `pr_description_body_audit.py` | Body audit logic for `pr_description_enforcer.py` |
 | `pr_description_command_parser.py` | `gh` command parsing for `pr_description_enforcer.py` |
 | `pr_description_pr_number.py` | PR number extraction logic |

package/hooks/blocking/code_review_enforcement_config_bootstrap.py

@@ -0,0 +1,53 @@
+"""Deterministic loader for the code-review enforcement constants module.
+
+The stamp store and every code-review gate import their shared constants as
+``from config.code_review_enforcement_constants import ...``. In the installed
+hook tree a second, unrelated ``config`` package can sit ahead of this package
+on ``sys.path`` and win that dotted name by path order, so the import binds to
+the wrong file and raises ImportError on any constant the stale copy lacks.
+This module binds the dotted name to its sibling ``config/`` file by explicit
+location, so resolution never depends on ``sys.path`` order.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import sys
+from pathlib import Path
+
+
+def register_code_review_enforcement_constants() -> None:
+    """Bind the code-review enforcement constants dotted name to its config file.
+
+    ::
+
+        sys.path = ["<installed hooks>", "<blocking>"]  # foreign config first
+        register_code_review_enforcement_constants()
+        from config.code_review_enforcement_constants import STAMP_DIRECTORY_NAME
+        ok: bound to <blocking>/config/code_review_enforcement_constants.py
+
+    A ``from config.code_review_enforcement_constants import`` that follows this
+    call reads the entry straight from ``sys.modules``, so it resolves to this
+    file whatever else owns the ``config`` name. An entry already cached is left
+    in place, so the call is idempotent and never displaces a module a caller
+    loaded on purpose.
+
+    Returns:
+        None. The effect is the ``sys.modules`` registration.
+    """
+    _bind_config_module_by_location(
+        "config.code_review_enforcement_constants",
+        Path(__file__).resolve().parent / "config" / "code_review_enforcement_constants.py",
+    )
+
+
+def _bind_config_module_by_location(dotted_name: str, constants_file_path: Path) -> None:
+    """Register a dotted config name against an explicit file path in sys.modules."""
+    if dotted_name in sys.modules:
+        return
+    module_spec = importlib.util.spec_from_file_location(dotted_name, constants_file_path)
+    if module_spec is None or module_spec.loader is None:
+        return
+    constants_module = importlib.util.module_from_spec(module_spec)
+    sys.modules[dotted_name] = constants_module
+    module_spec.loader.exec_module(constants_module)

package/hooks/blocking/code_review_gate_deny.py

@@ -0,0 +1,74 @@
+"""Shared deny scaffold for the code-review PreToolUse gates.
+
+The push gate and the PR-create gate deny a blocked tool call the same way: a
+``hookSpecificOutput`` payload carrying the deny decision and a corrective
+reason, logged through ``log_hook_block`` before it reaches stdout. This module
+holds that one payload builder and the log-and-emit helper, so the two gates
+share a single deny shape and stay in step.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+
+try:
+    _blocking_directory = str(Path(__file__).resolve().parent)
+    _hooks_directory = str(Path(__file__).resolve().parent.parent)
+    for each_bootstrap_directory in (_blocking_directory, _hooks_directory):
+        if each_bootstrap_directory not in sys.path:
+            sys.path.insert(0, each_bootstrap_directory)
+
+    from code_review_enforcement_config_bootstrap import (
+        register_code_review_enforcement_constants,
+    )
+
+    register_code_review_enforcement_constants()
+
+    from config.code_review_enforcement_constants import (
+        DENY_PERMISSION_DECISION,
+        PRE_TOOL_USE_HOOK_EVENT_NAME,
+    )
+
+    from hooks_constants.hook_block_logger import log_hook_block
+except ImportError as import_error:
+    raise ImportError(
+        "the code_review_gate_deny dependencies did not import; "
+        "ensure the hooks directory is importable."
+    ) from import_error
+
+
+def build_code_review_deny_payload(deny_reason: str) -> dict[str, dict[str, str]]:
+    """Build the PreToolUse deny payload for a blocked code-review gate action.
+
+    Args:
+        deny_reason: The corrective message naming why the action is denied.
+
+    Returns:
+        The ``hookSpecificOutput`` deny payload.
+    """
+    return {
+        "hookSpecificOutput": {
+            "hookEventName": PRE_TOOL_USE_HOOK_EVENT_NAME,
+            "permissionDecision": DENY_PERMISSION_DECISION,
+            "permissionDecisionReason": deny_reason,
+        }
+    }
+
+
+def log_and_emit_code_review_deny(deny_reason: str, tool_name: str, hook_module_name: str) -> None:
+    """Log a code-review gate block and write its deny payload to stdout.
+
+    Args:
+        deny_reason: The corrective message naming why the action is denied.
+        tool_name: The name of the gated tool, recorded in the block log.
+        hook_module_name: The calling gate's module name, recorded in the log.
+    """
+    log_hook_block(
+        calling_hook_name=hook_module_name,
+        hook_event=PRE_TOOL_USE_HOOK_EVENT_NAME,
+        block_reason=deny_reason,
+        tool_name=tool_name if isinstance(tool_name, str) else None,
+    )
+    sys.stdout.write(json.dumps(build_code_review_deny_payload(deny_reason)) + "\n")