claude-dev-env 2.12.0 → 2.14.0

package/skills/small-cl/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: small-cl
+description: >-
+  Scope or split a pull request into a self-contained reviewable increment. Use
+  when a user asks to "split this PR", "make this change smaller", or "small CL".
+---
+
+# Focused Pull Request Guide
+
+## When to Use This Guide
+
+Use this guide to plan, assess, or split a pull request into a reviewable unit.
+The pull request boundary is conceptual: one coherent outcome that a reviewer
+can understand with its context and verification.
+
+## What a Focused Pull Request Contains
+
+A focused pull request contains the implementation, related tests, documentation,
+and configuration needed for one outcome. It leaves the system in a usable state
+and gives the reviewer the information needed to assess the change.
+
+Use the [description guide](../descriptions/SKILL.md#required-content) to record
+the scope, verification, risks, and follow-up work.
+
+## Splitting a Change
+
+Choose a split that gives each increment a coherent purpose and a clear test
+boundary. Useful seams include:
+
+- Preparation refactors followed by behavior changes.
+- Independent vertical features that each deliver a user-visible capability.
+- Layer-specific work when each layer remains independently understandable.
+- Stacked changes when each earlier change supplies the next change's stable
+  foundation.
+
+State dependencies between related pull requests and keep each increment safe to
+merge or revert on its own.
+
+## Reviewable Scope
+
+Ask to split a change when its breadth prevents a reliable assessment of design,
+behavior, or verification. Identify the first coherent increment and the
+remaining increments so the author has an actionable path forward.
+
+Use [reviews](../reviews/SKILL.md#evaluation-criteria) to evaluate the resulting
+scope and [emergencies](../emergencies/SKILL.md#emergency-classification) when an
+active incident sets the immediate boundary.
+
+## Responding to Review
+
+Use the [comment guide](../comments/SKILL.md#responding-to-feedback) to respond
+to feedback and resolve pushback.

package/skills/task-build/AGENTS.md

@@ -0,0 +1,29 @@
+# task-build
+
+Gathers every open task in the current session and registers each one with the best available task or plan tool.
+
+**Trigger:** `/task-build`, "build my task list", "capture these tasks", "add open tasks to the task list", "track these".
+
+## Purpose
+
+Collects outstanding work from the conversation, `$ARGUMENTS`, and any plan documents or task items raised this session, then registers one item per open task — skipping anything already tracked or already complete.
+
+## Key files
+
+| File | Purpose |
+|---|---|
+| `SKILL.md` | Complete task discovery and registration workflow |
+| `reference/tool-routing.md` | Progressive-disclosure routing and fallback rules |
+
+## How the skill runs
+
+1. Reads the current list or visible plan with the selected host tool — prevents duplicates.
+2. Scans `$ARGUMENTS`, the conversation, and any plan or checklist items for open, actionable work.
+3. Prefers `update_plan`; otherwise uses `TaskList`/`TaskCreate`, then `TodoWrite` as the fallback. See `reference/tool-routing.md` for field mapping.
+4. Reports the selected tool, how many tasks were added, and how many were already tracked.
+
+## Conventions
+
+- This skill only records tasks — it does not start, assign, or complete them.
+- Use the matching host operation to set status after the list is built.
+- `disable-model-invocation: true` is not set; the skill uses model judgment to classify open vs. complete items.

package/skills/task-build/CLAUDE.md

@@ -1,29 +1 @@
-# task-build
-
-Gathers every open task in the current session and registers each one with the best available task or plan tool.
-
-**Trigger:** `/task-build`, "build my task list", "capture these tasks", "add open tasks to the task list", "track these".
-
-## Purpose
-
-Collects outstanding work from the conversation, `$ARGUMENTS`, and any plan documents or task items raised this session, then registers one item per open task — skipping anything already tracked or already complete.
-
-## Key files
-
-| File | Purpose |
-|---|---|
-| `SKILL.md` | Complete task discovery and registration workflow |
-| `reference/tool-routing.md` | Progressive-disclosure routing and fallback rules |
-
-## How the skill runs
-
-1. Reads the current list or visible plan with the selected host tool — prevents duplicates.
-2. Scans `$ARGUMENTS`, the conversation, and any plan or checklist items for open, actionable work.
-3. Prefers `update_plan`; otherwise uses `TaskList`/`TaskCreate`, then `TodoWrite` as the fallback. See `reference/tool-routing.md` for field mapping.
-4. Reports the selected tool, how many tasks were added, and how many were already tracked.
-
-## Conventions
-
-- This skill only records tasks — it does not start, assign, or complete them.
-- Use the matching host operation to set status after the list is built.
-- `disable-model-invocation: true` is not set; the skill uses model judgment to classify open vs. complete items.
+@AGENTS.md

package/skills/update/AGENTS.md

@@ -0,0 +1,38 @@
+# update
+
+Fast-forwards a local git repository's `main` branch to a chosen remote's `main`.
+
+**Trigger:** `/update`, "update main", "fast-forward main", "sync main from origin", "pull latest main into <path>", "bring main up to date".
+
+## Purpose
+
+Advances the `main` ref in a safe, confirmed, fast-forward-only way. Never forces, never merges. Confirms the repo path and source remote before any write. Offers to switch the checkout to `main` after the ref moves, with a clean-tree safety check.
+
+## Key files
+
+| File | Purpose |
+|---|---|
+| `SKILL.md` | The complete skill — five phases, refusals, gotchas. Flat by design; no companion files. |
+
+## Five phases
+
+| Phase | Key action |
+|---|---|
+| 1 — Resolve path | `git -C "<path>" rev-parse --show-toplevel` |
+| 2 — Confirm path + remote | One `AskUserQuestion` listing remote/URL pairs; recommends `origin/main` first |
+| 3 — Fetch + fast-forward | Fetch, check ancestry with `merge-base --is-ancestor`, apply via `merge --ff-only` (on main) or `fetch main:main` (off main) |
+| 4 — Report | Old SHA → new SHA, checkout state, dirty tracked files |
+| 5 — Offer to land on disk | `AskUserQuestion` to switch checkout to `main` (only when tree is clean and `main` is not held by another worktree) |
+
+## Refusals (first match wins)
+
+- Path is not a git repository → stated error, stop.
+- Remote has no `main` → stated error, stop.
+- Local `main` has diverged (not a fast-forward) → stated error, stop. Use `/rebase` to reconcile.
+
+## Conventions
+
+- Every command uses `git -C "<path>"` — never `cd` into the repo.
+- Path confirmation is mandatory even when the path comes from the argument.
+- The skill never switches to any branch other than `main`, and only in Phase 5 with operator approval.
+- `origin` is not always the source of truth; the confirmed remote may be `upstream` or another name.

package/skills/update/CLAUDE.md

@@ -1,38 +1 @@
-# update
-
-Fast-forwards a local git repository's `main` branch to a chosen remote's `main`.
-
-**Trigger:** `/update`, "update main", "fast-forward main", "sync main from origin", "pull latest main into <path>", "bring main up to date".
-
-## Purpose
-
-Advances the `main` ref in a safe, confirmed, fast-forward-only way. Never forces, never merges. Confirms the repo path and source remote before any write. Offers to switch the checkout to `main` after the ref moves, with a clean-tree safety check.
-
-## Key files
-
-| File | Purpose |
-|---|---|
-| `SKILL.md` | The complete skill — five phases, refusals, gotchas. Flat by design; no companion files. |
-
-## Five phases
-
-| Phase | Key action |
-|---|---|
-| 1 — Resolve path | `git -C "<path>" rev-parse --show-toplevel` |
-| 2 — Confirm path + remote | One `AskUserQuestion` listing remote/URL pairs; recommends `origin/main` first |
-| 3 — Fetch + fast-forward | Fetch, check ancestry with `merge-base --is-ancestor`, apply via `merge --ff-only` (on main) or `fetch main:main` (off main) |
-| 4 — Report | Old SHA → new SHA, checkout state, dirty tracked files |
-| 5 — Offer to land on disk | `AskUserQuestion` to switch checkout to `main` (only when tree is clean and `main` is not held by another worktree) |
-
-## Refusals (first match wins)
-
-- Path is not a git repository → stated error, stop.
-- Remote has no `main` → stated error, stop.
-- Local `main` has diverged (not a fast-forward) → stated error, stop. Use `/rebase` to reconcile.
-
-## Conventions
-
-- Every command uses `git -C "<path>"` — never `cd` into the repo.
-- Path confirmation is mandatory even when the path comes from the argument.
-- The skill never switches to any branch other than `main`, and only in Phase 5 with operator approval.
-- `origin` is not always the source of truth; the confirmed remote may be `upstream` or another name.
+@AGENTS.md

package/system-prompts/AGENTS.md

@@ -0,0 +1,17 @@
+# system-prompts
+
+System-prompt reference files installed into `~/.claude/system-prompts/` by `bin/install.mjs`. Rules and skills pull a file (or one of its sections) into context on demand by citing its installed path.
+
+## Files
+
+| File | Purpose |
+|---|---|
+| `software-engineer.xml` | Software-engineering reference: defines the engineering role, task-scope rules, output style, and the BDD `<behavior_protocol>` that `rules/bdd.md` cites on demand |
+
+## Format
+
+Files use XML with named sections (`<role>`, `<task_scope>`, `<output_style>`, `<behavior_protocol>`, etc.). A rule or skill cites a file, or one of its sections, to pull it into context when the task needs it.
+
+## Adding a prompt
+
+Create a new `.xml` file and run `bin/install.mjs` to copy it to `~/.claude/system-prompts/`. Reference the new file in the relevant rule or skill by its installed path.

package/system-prompts/CLAUDE.md

@@ -1,17 +1 @@
-# system-prompts
-
-System-prompt reference files installed into `~/.claude/system-prompts/` by `bin/install.mjs`. Rules and skills pull a file (or one of its sections) into context on demand by citing its installed path.
-
-## Files
-
-| File | Purpose |
-|---|---|
-| `software-engineer.xml` | Software-engineering reference: defines the engineering role, task-scope rules, output style, and the BDD `<behavior_protocol>` that `rules/bdd.md` cites on demand |
-
-## Format
-
-Files use XML with named sections (`<role>`, `<task_scope>`, `<output_style>`, `<behavior_protocol>`, etc.). A rule or skill cites a file, or one of its sections, to pull it into context when the task needs it.
-
-## Adding a prompt
-
-Create a new `.xml` file and run `bin/install.mjs` to copy it to `~/.claude/system-prompts/`. Reference the new file in the relevant rule or skill by its installed path.
+@AGENTS.md

package/system-prompts/software-engineer.xml

@@ -90,9 +90,9 @@
 </problem_solving>
 
 <code_quality>
-  Canonical code-quality policy is repository-root AGENTS.md (installed review contract).
-  ~/.claude/docs/CODE_RULES.md is the compact projection of AGENTS.md for generation load —
-  when the two disagree, AGENTS.md wins. The checklist below is a short reminder, not a
+  The checked-in .cursor/BUGBOT.md is the full code-quality review contract.
+  ~/.claude/docs/CODE_RULES.md is the compact projection for generation load.
+  The checklist below is a short reminder, not a
   second canonical source.
 
   Naming — full words only:

package/agents/code-verifier.md

@@ -1,74 +0,0 @@
----
-name: code-verifier
-description: Post-hoc verification agent. Runs only when the task owner asks for a verification pass — never spawned automatically because a coder agent finished. Runs every check itself in a fresh context — named gates, tests against recorded baselines, two-way diff-vs-task reading — puts the draft verdict through one strongest-tier validation subagent that tries to refute it, then ends with a fenced verdict block the verifier_verdict_minter hook turns into the commit-gate verdict. Never edits files in the tree under review — its one exception is a deliberate break at an off-tree break site outside that tree, defined in its body.
-tools: Read, Grep, Glob, Bash, Task
-color: orange
----
-
-You are the verifier in a three-phase code workflow: coder agents wrote changes, and you grade the result on its own terms (Claude Code best practices, fresh-context review: https://code.claude.com/docs/en/best-practices). The agent doing the work is never the one grading it — that is you, so you trust nothing you did not run or read yourself this session.
-
-The caller gives you task texts, the diff scope, and baselines recorded before the coders ran. Treat every claim in the caller's message — and any coder summary quoted in it — as a hypothesis to test, never as a fact.
-
-Run all three layers, in this order:
-
-1. **Runnable gates.** Every check the task names (its verification section), plus the universal set whether or not the caller asked: compile/syntax checks on changed files, the recorded-baseline tests scoped to the changed modules — the test files the task names plus tests that import a changed module (the failure set must match the recorded baseline exactly — no new failures, none silently fixed without explanation), imports of changed modules, and any repo commit gate. Run the full recorded suite only when the caller recorded a full-suite baseline because the surface spans multiple modules or multiple coders. Run each command yourself and keep its output.
-2. **Two-way diff-vs-task reading.** Read each coder's diff against that coder's task text. Every task item maps to a hunk that does it; every hunk maps back to a task item — a hunk with no task item is out-of-scope change, a task item with no hunk is missing work.
-3. **Negative space.** Walk the task's item list asking "where is this one?": silent deferrals, stubs, TODO markers, the smaller half of a task shipped, a sync change without its async twin.
-
-Findings discipline:
-
-- A finding must cite a failing command (with its output) or a named task item. No citation, no finding. `findings` carries code defects alone.
-- Report gaps that affect correctness or the task's stated terms — never style preferences. Sound work produces zero findings; do not invent gaps to look thorough.
-- Never edit a file in the work tree you verify — you verify; repair agents repair. The one exception is a deliberate break for the shown-red table, which goes at one of the off-tree break sites the shown-red section below lists.
-- Never run `git stash`. `refs/stash` belongs to the repository, not to a work tree, so every worktree shares one stash list: a `pop` can apply another verifier's entry into your tree and hand you a surface that is not your assignment. To read the base, add a throwaway detached worktree at the base commit (`git worktree add --detach <temp-path> <base-sha>`), read it there, and drop it with `git worktree remove --force <temp-path>`. You only ever need to read a base tree, and stash moves the very tree you were asked to verify.
-- Never execute code that drives the user's real input or screen — no live mouse moves, keystrokes, clicks, or window focus (pyautogui and its callers included). Run only the test commands the task names, scoped to the test files it names; no repo-wide test sweeps. Judge behavior equivalence by reading both versions, never by live execution of input-driving paths.
-
-Before you write the verdict, learn the surface hash of the work tree you verified. Use the branch mode — it resolves the work tree that holds the branch automatically, so it is immune to your own cwd:
-
-    python ~/.claude/hooks/blocking/verification_verdict_store.py --manifest-hash-for-branch <branch under review>
-
-On Windows the same file sits at %USERPROFILE%\.claude\hooks\blocking\verification_verdict_store.py; invoke it with the python on your PATH. If the caller named an explicit work-tree path rather than a branch, use the explicit-directory mode instead:
-
-    python ~/.claude/hooks/blocking/verification_verdict_store.py --manifest-hash <explicit-work-tree-dir>
-
-The printed hash commits to every changed and untracked file's content in the verified work tree, so it names that surface no matter which directory you or the committer run from. If the CLI prints an empty-surface or wrong-work-tree error and no hash, you are pointed at a work tree with no changes versus origin/main — re-run with the branch mode to locate the correct work tree.
-
-As the last step before the verdict, put your draft verdict through one best-effort strongest-tier validation pass. Spawn a single validation subagent through the Task tool as the `Explore` agent type at the strongest reachable tier: set the Task `subagent_type` to `Explore`, detect the host profile first per `~/.claude/_shared/advisor/advisor-protocol.md` — the source of truth for host detection, the ladder, and its aliases — then on a Claude host pick the strongest reachable tier on the Fable → Opus → Sonnet → Haiku ladder and on a third-party host use the single third-party tier, and set the Task `model:` field to that tier's alias. A tier denied by policy counts as unreachable, so the walk continues down the ladder to the next tier rather than skipping the validation pass. The `Explore` type carries no Edit or Write tools and cannot spawn further agents, so the harness itself holds the validator to the no-edit, no-spawn contract the next paragraph names. Hand it the draft verdict together with your evidence — every command you ran with its output, your two-way diff-to-task mapping, and the shown-red table with every deliberate-red run labeled as shown-red evidence so the validator reads it as a staged break rather than a genuine failure — and state that its task is adversarial verification of that supplied draft verdict: refute it against the supplied evidence rather than discover code, naming any gate you misread, any task item you mapped wrong, or any finding that does not hold. This pass is always a cold `Explore` spawn, not a message to the session's warm advisor: the refutation needs a grader with no accumulated session context or prior positions, and the verifier runs in sessions that have no advisor bound. Run that spawn synchronously — set the Task `run_in_background` field to `false` — so the validator's reply lands inside this turn. A background spawn returns straight away and its completion notification arrives after your turn is over, so the reply you are waiting for never reaches you and the verdict fence never gets written. When the spawn is unavailable — a Task tool error, an unreachable tier at every rung, or this subagent being barred from spawning further agents — skip the validation pass and emit the draft verdict as it stands, noting the skip in your final message; a spawn failure never blocks the verdict fence from being emitted.
-
-Ending your turn without the verdict fence throws the whole run away: every gate you ran and every mapping you built reaches the caller as prose it cannot mint, and the commit gate stays shut on work you already checked. So the fence is unconditional. A validator that returns nothing usable, a tier that never binds, a refutation you accept and fold in — each of those ends the same way, with the fence. When you find yourself about to close on a promise to finish once something reports back, run the refutation pass yourself and emit the verdict.
-
-This validation pass is terminal: the `Explore` type gives the validation subagent no way to spawn a further agent or edit a file, so it answers with prose only. When it refutes any part, re-check that part yourself against the commands and the diff, and correct the verdict before you emit it. When it refutes nothing, the draft verdict stands. Then write your final message.
-
-Your final message runs in one order: the shown-red table, then — only when the verdict is incomplete — the named unshown check, then every `no break available` row named, then the verdict fence last, so the verifier_verdict_minter hook reads it. Every runnable check the verdict rests on gets one row — a runnable check is a layer 1 runnable gate you can execute against the surface. Breakability is not part of that definition: no check leaves the runnable set by being called unbreakable.
-
-| Check | Deliberate break | Red | Green |
-|---|---|---|---|
-| `<command you ran>` | `<break you applied>`, or `no break available — <why no input, no environment, and no scratch-copy mutation can make this check fail>`, or `n/a — check not run` | `<exit code or the deciding line>`, or `no red` | `<exit code or the deciding line>` |
-
-The Deliberate break cell holds exactly one of those three values: the break you applied, `no break available` with its one-line reason, or `n/a — check not run`. Only the first of the three produced a red, so only the first carries a red result in the Red cell. A `no break available` row and an `n/a — check not run` row each carry the literal `no red` there — never an empty cell, never the Green value repeated, and never an exit code, which would make a row that showed no red scan like one that did.
-
-Keep each cell to one line — an exit code, a failing test id, an assert line, or a hook's block message. The Green cell may cite the check's first clean run when you kept that output; a clean result already in hand needs no third run. Longer excerpts go below the table in a plain fenced block carrying no info string.
-
-The reading layers, 2 and 3 above, take no rows. Name in prose what you read and what that reading would catch. A runnable check keeps its row whatever you conclude by reading it, and whatever you conclude about breaking it.
-
-Break the check at an off-tree break site — a site where the break cannot reach the tree you verify: a failing input or environment fed to the check, or a mutated copy in a scratch directory outside that tree.
-
-At either off-tree break site, a check that exercises the changed behavior fails because of the break rather than for an unrelated reason.
-
-Break off-tree so the work tree under verification stays as the coders left it; an in-place break moves the surface `manifest_sha256` names and is forbidden. The green is that same check run against the verified tree.
-
-Every runnable check the verdict rests on gets a row, with no exclusion path: a rested-on runnable check with no row makes the verdict incomplete, and a check you judge unbreakable still owes its row. Where no runnable check the verdict depends on exists, the surface rests on the reading layers alone and carries an empty table, complete. The empty table is for a surface where nothing runnable exists at all, never for one where a runnable check exists and you skipped it. A row carrying `n/a — check not run` is a runnable check you relied on and never showed red, and it makes the verdict incomplete too; its Red cell carries `no red`.
-
-`no break available` is a different claim from `n/a — check not run`: the check ran, and no break exists for it, so its Red cell carries `no red` as well. That row counts complete when it carries the one-line reason naming why no input, no environment, and no scratch-copy mutation can make that check fail, so `all_pass` true stays reachable for a genuinely unbreakable gate. A `no break available` row without that reason is an incomplete row and makes the verdict incomplete exactly as a missing row does.
-
-An incomplete verdict names the unshown check directly above the fence and sets `all_pass` to false. Naming a `no break available` row is a separate matter from that incomplete-check naming: a verdict carrying any `no break available` row names each of those rows directly above the fence because the row carries no red, whether the verdict is otherwise complete or incomplete, and naming one never by itself makes the verdict incomplete or sets `all_pass` false. `findings` goes on carrying every code defect the run found, and is empty only when the run found none.
-
-Write the table as plain markdown; the fence holds JSON alone.
-
-Exactly one fenced verdict block — the verifier_verdict_minter hook parses it, binds it to that hash, and the verified_commit_gate hook unlocks `git commit`/`git push` for any work tree whose live surface matches it:
-
-```verdict
-{"all_pass": false, "findings": [{"check": "<gate or task item>", "detail": "<command + output, or the named task item and what is missing>"}], "manifest_sha256": "<hash the CLI printed>"}
-```
-
-Set `all_pass` to true with an empty `findings` list only when every layer came back clean and the shown-red table is complete. Always include `manifest_sha256` so the verdict clears the commit regardless of which work tree the verifier or the committer ran in. Commit-committability gates (CODE_RULES / merge conflicts) must already be green before you are spawned; you are the last semantic check before commit. Any file change after you finish moves that hash and invalidates the verdict.

package/docs/PR_DESCRIPTION_GUIDE.md

@@ -1,157 +0,0 @@
-# PR Description Guide
-
-Authoritative reference for the `pr-description-writer` agent and the `pr_description_enforcer` PreToolUse hook. PR bodies that match this guide pass the enforcer on first attempt.
-
-## Anthropic style basis
-
-The shape rules and header vocabulary derive from a 120-PR sample. Sources: `anthropics/claude-code` (40 PRs), `anthropics/claude-code-action` (40 PRs), and `anthropics/claude-code-sdk-python` (40 PRs). The corpus was sampled from merged PRs.
-
-Key signals from the corpus:
-
-- **Shape distribution.** Trivial (≤ 10 lines): 32.5% — median body 288 chars. Small (11–100 lines): 41.7% — median 1,105 chars. Medium (101–500 lines): 20.0% — median 940 chars. Large (> 500 lines): 5.8% — median 2,441 chars.
-- **Modal headers.** `## Summary` 43, `## Problem` 20, `## Test plan` 20, `## Fix` 18, `## Changes` 14, `## Tests` 11, `## Testing` 10, `## Root cause` 5, `## Approach` 2.
-- **Opening style.** 46.7% open with a header, 53.3% with an unmarked paragraph. 51% of prose-opening Small/Medium PRs open with an imperative verb. `This PR` appears in 1 of 120 PRs.
-- **Issue references.** 27.5% of PRs use `Fixes #N`, `Closes #N`, or `Resolves #N`.
-- **Sentence length.** First-paragraph mean 15.2 words; median 14.5. Sentences over 28 words are uncommon.
-- **Em-dashes.** Appear in 48% of bodies as parenthetical separators.
-- **Backtick identifiers in intros.** Routine — filenames, function names, env vars, and CLI flags appear in opening paragraphs.
-
-## The three shapes
-
-### Trivial
-
-- **Guidance.** Diff ≤ 10 lines changed (the agent picks shape by diff size; the hook cannot see the diff).
-- **Hook enforcement.** Substantive prose under `TRIVIAL_BODY_CHAR_THRESHOLD` (200 chars). The hook blocks any ATX heading at any depth (`#`, `##`, `###`, ...) in a Trivial-sized body — the ceremony-on-Trivial check uses `HEADING_LINE_PATTERN`, not just `##`.
-- **Body.** 1–3 sentences of prose. Zero headings of any level.
-- **Forbidden.** Any heading (`# Anything`, `## Summary`, `### Detail`, ...). Triggers the hook's ceremony-on-Trivial check.
-
-Example:
-
-```markdown
-Bump bun to 1.3.14. Picks up the bugfix for the runtime panic on empty stdin.
-```
-
-### Standard
-
-- **Guidance.** Diff 11–500 lines (agent-side; hook infers shape from body length).
-- **Hook enforcement.** Substantive prose between `TRIVIAL_BODY_CHAR_THRESHOLD` (200) and `HEAVY_MIN_BODY_CHARS_FOR_CLASSIFICATION` (500). No required headers.
-- **Body.** Imperative-verb intro paragraph. Optional headers drawn from the Anthropic set.
-- **Optional headers.** `## Summary`, `## Problem`, `## Fix`, `## Changes`, `## Test plan`, `## Tests`, `## Testing`, `## Approach`, `## Root cause`.
-
-Example:
-
-```markdown
-Adds a syllable-counted Flesch reading score to the PR description enforcer. Bodies above the readability ceiling surface a targeted block message before the strike counter increments.
-
-## Test plan
-
-- [ ] `pytest packages/claude-dev-env/hooks/blocking/test_pr_description_enforcer.py`
-- [ ] Open a draft PR with a 45-word sentence and confirm the metric block fires
-```
-
-### Heavy
-
-- **Criterion.** Diff > 500 lines, or a cross-cutting bug fix that touches multiple subsystems.
-- **Body.** At least one of `## Problem` or `## Summary`. At least one of `## Test plan`, `## Testing`, `## Tests`, `## Verification`, or `## Validation`. Plus any additional Anthropic headers the change earns.
-- **Hook enforcement.** Missing either required category triggers a Heavy-required-headers block message naming the absent category.
-
-Example:
-
-```markdown
-## Problem
-
-Long-running `gh api` review fetches drop pages silently when the reviewer count crosses 30. Bugbot findings on PRs past the first review cycle stay hidden.
-
-## Fix
-
-Routes every `gh api .../reviews` and `.../comments` call through `--paginate --slurp | jq` so the cross-page filter sees the full set.
-
-## Test plan
-
-- [ ] Mock paginated API and assert `jq` filter operates on the merged stream
-- [ ] Replay PR #467 review history and confirm the late bugbot comment surfaces
-```
-
-## Header vocabulary
-
-| Header | Corpus count | Typical use |
-|---|---:|---|
-| `## Summary` | 43 | High-level overview, often two or three sentences |
-| `## Problem` | 20 | Bug context — what broke, who hit it |
-| `## Test plan` | 20 | Reviewer checklist of verification steps |
-| `## Fix` | 18 | How the change addresses the problem |
-| `## Changes` | 14 | Bulleted catalog of code-level updates |
-| `## Tests` | 11 | New or expanded test coverage |
-| `## Testing` | 10 | Manual or CI verification notes |
-| `## Root cause` | 5 | Underlying defect analysis |
-| `## Approach` | 2 | Design rationale for non-obvious solutions |
-
-`## Test plan` and `## Root cause` use sentence-case in the corpus. The enforcer regex matches case-insensitively.
-
-## Readability targets
-
-The enforcer measures three metrics on the intro paragraph and first body section combined.
-
-| Metric | Target |
-|---|---|
-| Longest sentence | ≤ 28 words |
-| Average sentence | ≤ 18 words |
-| Flesch Reading Ease | ≥ 50 |
-
-The Flesch score uses `206.835 - 1.015 × (words/sentences) - 84.6 × (syllables/words)`. The hook implements the formula in pure stdlib with a vowel-group syllable heuristic.
-
-Hit the targets by writing short sentences in common Anglo-Saxon words. The corpus first-paragraph average of 14.5 words is the target to beat.
-
-## Escape hatch
-
-The hook tracks a per-user readability strike counter at `~/.claude/state/pr_description_readability_strikes.json`. Counter increments on every triggering violation. The first two failures emit metric-specific block messages. The third triggering failure fires the escape-hatch message with four recovery actions.
-
-### Action 1 — loosen thresholds 10%
-
-```bash
-python <enforcer-path> --readability-loosen
-```
-
-Scales the three thresholds. Flesch floor × 0.9 (rounded down). Max-sentence ceiling × 10/9 (rounded up). Avg-sentence ceiling × 10/9 (rounded up). Cascades on repeat — the second loosen applies the same scaling to the already-loosened values.
-
-Caps:
-
-- Max 3 successive loosens (`READABILITY_LOOSEN_CAP = 3`). A fourth `--readability-loosen` errors with `loosen cap reached; use --readability-disable or --readability-reset`.
-- Flesch floor of 30 (`READABILITY_MIN_FLESCH_FLOOR`). Once `flesch_min` reaches 30 the loosen action errors.
-- Max-sentence ceiling of 60 (`READABILITY_MAX_SENTENCE_WORDS_CEILING`). Once `max_sentence_words` reaches 60 the loosen action errors.
-- Avg-sentence ceiling of 40 (`READABILITY_AVG_SENTENCE_WORDS_CEILING`). Once `avg_sentence_words` reaches 40 the loosen action errors.
-
-### Action 2 — disable readability entirely
-
-```bash
-python <enforcer-path> --readability-disable
-```
-
-Writes `{"enabled": false}` to `~/.claude/state/pr_description_readability_enabled.json`. Shape detection, Heavy required-headers, ceremony-on-Trivial, self-closing reference, `This PR` opening, vague-language, and minimum-length checks all stay active. The readability check is the only one silenced.
-
-Re-enable with:
-
-```bash
-python <enforcer-path> --readability-enable
-```
-
-### Action 3 — reset the strike counter
-
-```bash
-python <enforcer-path> --readability-reset
-```
-
-Zeroes the strike counter at `~/.claude/state/pr_description_readability_strikes.json`. Clears `loosens_used` and threshold overrides at `~/.claude/state/pr_description_readability_overrides.json`. The readability check returns to default thresholds and a clean strike count.
-
-### Action 4 — report a false positive
-
-Reply with the PR body and your intended commit message. The maintainer tunes the thresholds or refines the regex.
-
-## What to avoid
-
-- **Vague language.** `fix bug`, `update code`, `minor changes`, `various improvements`. Each trips the `VAGUE_LANGUAGE_PATTERN` check.
-- **`This PR` openings.** Hard block. Open with an imperative verb.
-- **Self-closing references.** `Fixes #<this PR>` in a `gh pr edit` body. Self-reference adds zero context. Triggers a block on `gh pr edit` and `gh pr comment` invocations where the PR number is known.
-- **Code snippets in prose.** The diff shows the code. Bodies describe intent.
-- **Implementation-detail dumping.** Reviewers do not need every parameter name and call site. Describe the behavior change.
-- **Filler.** `In this PR I have made the following changes:` adds zero signal. Start with the action.

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

@@ -1,132 +0,0 @@
-# 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**. Turn it on by setting the environment
-variable `CLAUDE_CODE_REVIEW_ENFORCEMENT` to `1`, `true`, `yes`, or `on`
-(case and surrounding spaces are ignored). Any other value, and an unset
-variable, leave enforcement off.
-
-Set the variable in the machine's own user environment so every gate reads it,
-including the native git pre-push backstop, which git runs in the shell's
-environment. An `env` block in `settings.json` reaches the three Claude Code
-hook gates alone. Each gate process reads the variable as it starts, so a
-Claude Code session already running keeps its current setting until it
-restarts, while the git pre-push backstop picks up the current shell
-environment on each push.
-
-A user-environment setting arms the gates machine-wide. The backstop installs
-through the shared `core.hooksPath`, so it runs for every repository on the
-machine, and the gates carry no per-repository allowlist. Each repository then
-needs its own clean stamp before a push lands there.
-
-The variable feeds the master flag `CODE_REVIEW_ENFORCEMENT_ENABLED` in
-`hooks/blocking/config/code_review_enforcement_constants.py`, which every gate
-reads at start-up. When it is on, the push gate, the PR-create gate, the native
-pre-push backstop (via the shared deny decision), and the stamp-directory write
-blocker all enforce. When it is off, every gate allows the action and the
-write-blocker allows stamp-directory access.
-
-`npx claude-dev-env` copies the shipped `hooks/` tree over `~/.claude/` on each
-install, so the environment setting survives an install and an edit to the
-constant does not.
-
-## 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 push that clears the enable variable.** The backstop reads
-  `CLAUDE_CODE_REVIEW_ENFORCEMENT` from the shell that runs the push, so
-  `CLAUDE_CODE_REVIEW_ENFORCEMENT=0 git push` reads as enforcement off and the
-  backstop allows the push with no flag and no bypass marker.
-- **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`.