claude-dev-env 2.12.0 → 2.13.0

package/skills/prototype/SKILL.md

@@ -10,8 +10,8 @@ description: >-
 
 Give a build the freedom to move fast, then make it earn the right to ship. Two phases, one hard wall between them:
 
-- **Sandbox** — an isolated worktree where an agent runs under `claude --bare`, so none of the standards gates (TDD, code rules, verified-commit, plain-language, stage) fire. The agent builds a proof-of-concept with zero friction.
-- **Promotion** — back in the normal, fully-hooked session, the successful POC goes through a clean-room re-verification before it becomes a commit and a pull request. Nothing from the sandbox rides along un-checked.
+- **Sandbox** — an isolated worktree where an agent runs under `claude --bare`, so the normal TDD, code-rules, plain-language, and stage hooks do not run. The agent builds a proof-of-concept with zero friction.
+- **Promotion** — back in the normal, fully-hooked session, the successful POC receives clean-room review and verification under the [review guide](../reviews/SKILL.md#review-workflow) before it becomes a commit and a pull request.
 
 Two safety gates stay live even in the sandbox: personal-data blocking and destructive-command blocking. A worktree shares the real repo's `.git` store and `rm` reaches the whole disk, so these are containment, not the "delays" the sandbox is meant to shed.
 
@@ -45,7 +45,7 @@ Follow `workflows/sandbox.md`. In short:
 
 ### Phase 2 — Promotion
 
-Run only in the normal, fully-hooked session — never inside the sandbox. Follow `workflows/promotion.md`, which drives the clean-room task seeds in `reference/promotion-tasks.md`: fresh branch off live `origin/main`, POC content as an uncommitted diff, cleanup and privacy sweep, `code-verifier` in a fresh context, then `/commit` and a draft PR handed to a PR-loop skill. State the two honest limitations from `reference/honest-limitations.md`.
+Run only in the normal, fully-hooked session — never inside the sandbox. Follow `workflows/promotion.md`, which drives the clean-room task seeds in `reference/promotion-tasks.md`: fresh branch off live `origin/main`, POC content as an uncommitted diff, cleanup and privacy sweep, review and verification under the [review guide](../reviews/SKILL.md#review-workflow), then `/commit` and a draft PR handed to a PR-loop skill. State the two honest limitations from `reference/honest-limitations.md`.
 
 ## Task seeding
 
@@ -57,7 +57,7 @@ At the start of Phase 2, register every item in `reference/promotion-tasks.md` a
 |---|---|---|---|
 | `fresh-branch` | Sandbox step 1; Promotion step 2 | isolated worktree JSON (`worktree_path`, `base_commit`, `repo_root`) | Refuse — see refusal cases |
 | `privacy-hygiene` | Promotion step 5 | personal-data and secret sweep of the diff | Warn; do a manual review before continuing |
-| `code-verifier` (agent) | Promotion step 6 | fresh-context verdict against the real diff; mints the commit-gate verdict | Stop; the commit gate will block anyway |
+| [Review guide](../reviews/SKILL.md#review-workflow) | Promotion step 6 | review and verification of the real diff | Stop and report the incomplete promotion |
 | `/commit` (command) | Promotion step 7 | conventional commit + push | Commit and push by hand per `git-workflow` |
 | `autoconverge` (default; `pr-converge` or `bugteam` as alternatives) | Promotion step 9 | the PR converged to ready | Stop after the draft PR; tell the user to converge manually |
 

package/skills/prototype/reference/honest-limitations.md

@@ -6,9 +6,9 @@ State both of these to the user, in these terms, whenever a proof-of-concept is
 
 `code_rules_enforcer` is a Write/Edit gate: it checks content as it is written. Prototype code is built under `--bare`, so that gate never fired, and content brought into promotion as a git diff (apply, checkout, cherry-pick) does not pass through it either.
 
-Standards re-engage on promotion through three surfaces that stand in for the write-time hook:
+Promotion records the controls applied to the real diff:
 
-- the `code-verifier` agent, in a fresh context, deriving and running the named gates against the real diff;
+- review and verification under the [review guide](../../reviews/SKILL.md#review-workflow);
 - the `privacy-hygiene` sweep for personal data and secrets;
 - the pull-request review (AGENTS.md criteria and any PR-loop reviewers).
 
@@ -18,6 +18,6 @@ Say plainly: the write-time rule engine did not see this code; the verifier and
 
 The sandbox agent wrote code first and tests, if any, after. Red-green-refactor ordering did not happen. So the honest claim on promoted prototype code is exactly this, and nothing more:
 
-> code-verifier passed, privacy swept, review passed — TDD ordering waived.
+> Review and verification completed, privacy swept — TDD ordering waived.
 
-Do not claim red-green compliance on these lines. A prototype is a reference build, not a test-first build. Fred Brooks: plan to throw one away. Promotion re-verifies the code and often rewrites it to standard; expect real work in the verifier repair loop, not a rubber stamp.
+Do not claim red-green compliance on these lines. A prototype is a reference build, not a test-first build. Promotion reviews and verifies the code against the current standards.

package/skills/prototype/reference/promotion-tasks.md

@@ -14,9 +14,9 @@ Promotion runs in the **normal, fully-hooked session** — never inside the `--b
 
 5. **Privacy sweep.** Run the `privacy-hygiene` skill over the full applied working tree, not only the diff — a POC that pulled live data can leave a secret in a file the diff view hides. Evidence: its clean report, or the leak it found and how it was removed. If the skill is missing, do a manual PII and secret review and say so.
 
-6. **Verify in a fresh context.** Spawn the `code-verifier` agent against the real diff. Expect findings and a repair loop — the code was un-TDD'd. Evidence: the verifier's clean verdict, and a note of what it made you fix. Do not skip this on the belief that the sandbox agent already tested it.
+6. **Review and verify the real diff.** Apply the [review guide](../../reviews/SKILL.md#review-workflow). Evidence: the checks run and each required finding repaired. Do not rely on sandbox testing as promotion evidence.
 
-7. **Commit and open a draft PR.** Only on a clean verdict, run `/commit` (which mints the commit-gate verdict and pushes), then open a draft PR per the `git-workflow` rule. Evidence: the commit hash and the PR URL.
+7. **Commit and open a draft PR.** After the review and verification record is complete, run `/commit`, then open a draft PR per the `git-workflow` rule. Evidence: the commit hash and the PR URL.
 
 8. **State the honest limitations.** Post the two statements from `reference/honest-limitations.md` — write-time rules never ran; TDD ordering waived — in the PR body or to the user. Evidence: the text was included.
 

package/skills/prototype/workflows/promotion.md

@@ -4,7 +4,7 @@ Turn a successful proof-of-concept into a real, verified change. Run every step
 
 ## Seed the task list first
 
-Register every item in `reference/promotion-tasks.md` as a session task (`TaskCreate`, or `TodoWrite` if that is the host tool). Work only from the task list. Mark each complete with evidence — a command result, a path, a verdict, or a skill's return.
+Register every item in `reference/promotion-tasks.md` as a session task (`TaskCreate`, or `TodoWrite` if that is the host tool). Work only from the task list. Mark each complete with evidence — a command result, a path, a review record, or a skill's return.
 
 ## The clean-room protocol
 
@@ -15,13 +15,11 @@ The task seeds carry the full ordered detail. The shape:
 3. **Bring content as an uncommitted diff.** Copy the POC's file changes into the new branch's working tree. Do not cherry-pick or merge the sandbox commits; the sandbox history stays behind.
 4. **Cleanup.** Remove scratch files, debug dumps, and temp helpers the POC created (`cleanup-temp-files` rule).
 5. **Privacy sweep** via `privacy-hygiene` over the diff.
-6. **Verify** with the `code-verifier` agent — `model: sonnet`, worker-model routing per [`skills/orchestrator/SKILL.md`](../../orchestrator/SKILL.md#workflow-agent-routing); resolver-supplied sonnet-equivalent on third-party hosts — in a fresh context. This is where standards re-engage. Expect findings and a repair loop — the POC was un-TDD'd.
-7. **Commit and PR.** Only on a clean verdict, run `/commit`, then open a draft PR per the `git-workflow` rule.
+6. **Review and verify** the real diff against the [review guide](../../reviews/SKILL.md#review-workflow). Record the checks run and repair every required finding.
+7. **Commit and PR.** After the review and verification record is complete, run `/commit`, then open a draft PR per the `git-workflow` rule.
 8. **State the honest limitations** from `reference/honest-limitations.md` in the PR body or to the user.
 9. **Converge** by handing the PR to `autoconverge` by default; use `pr-converge` for paced ticks or `bugteam` for an open-loop audit.
 
 ## Why the clean room, not a push
 
-`code_rules_enforcer` is a write-time Write/Edit gate. Content that lands through `git apply`, `git checkout`, or cherry-pick never passes through it, so pushing the sandbox branch would ship code the rule engine never saw, carrying sandbox scratch along with it. Standards re-engage through the `code-verifier` agent, the `privacy-hygiene` sweep, and the PR review — not through a write-time hook. Steps 4-6 are hard gates: the honest claim on promoted POC code is code-verifier-passed, privacy-swept, review-passed, with TDD ordering waived.
-
-The `verified_commit_gate` hook is the backstop under all of this — it refuses a commit or push with no minted verdict — but the clean-room steps are the mechanism, not the gate firing.
+`code_rules_enforcer` is a write-time Write/Edit gate. Content that lands through `git apply`, `git checkout`, or cherry-pick receives the clean-room controls in steps 4–6: cleanup, privacy review, and review and verification under the [review guide](../../reviews/SKILL.md#review-workflow). The promotion record states the checks run and the remaining TDD limitation.

package/skills/reviews/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: reviews
+description: >-
+  Review a pull request or code change for code health. Use when a user asks to
+  "code review", "review this PR", or "review this change".
+---
+
+# Code Review Guide
+
+Use this guide to evaluate a pull request or code change. Apply the repository's
+`AGENTS.md` and `CODE_RULES.md` as its project-specific quality rubric.
+
+## Review Judgment
+
+Review work supports code health. Frame each conclusion around observable
+behavior, maintainability, risk, and the change's intended outcome.
+
+- Use technical evidence and repository conventions to resolve trade-offs.
+- Mark a required change when it materially affects correctness, security,
+  reliability, data integrity, maintainability, or the stated behavior.
+- Mark optional improvement as `Consider` or `Nit` so the author can prioritize
+  the work accurately.
+- Accept an evidence-backed explanation when it satisfies the applicable
+  quality rubric.
+
+## Evaluation Criteria
+
+Evaluate the changed code and the surrounding context for:
+
+- Design fit, interfaces, complexity, and future maintenance cost.
+- Functional behavior, user impact, edge cases, concurrency, privacy,
+  security, and accessibility where applicable.
+- Tests that exercise the changed behavior and distinguish regressions.
+- Names, comments, documentation, and style against the repository rubric and
+  the applicable language guide.
+- Migration, configuration, compatibility, and operational effects.
+
+## Review Workflow
+
+1. Read the pull request description and identify the intended outcome.
+2. Inspect the changed code, relevant callers, and the surrounding design.
+3. Run or assess relevant verification and identify its coverage boundaries.
+4. Write each finding with the affected location, observed effect, expected
+   outcome, and supporting evidence.
+5. State the reviewed scope, verification performed, and any remaining
+   uncertainty in the review output.
+
+Use the [comment guide](../comments/SKILL.md#writing-useful-review-comments)
+for finding wording and the [description guide](../descriptions/SKILL.md#reviewing-a-description)
+for description content.
+
+## Execution Support
+
+Use available runners for inspection, verification, and repository navigation.
+This guide supplies the judgment criteria and the corresponding guide anchors.
+
+## Review Responsiveness
+
+Begin a requested review at the next clean work boundary. Provide a useful
+response promptly, including the completed scope and the remaining work when
+context gathering continues.
+
+Review the highest-impact design questions early. A focused response gives the
+author a clear next action while the full assessment continues.
+
+## Resolving Disagreements
+
+Consolidate a disagreement into one thread that records the relevant context,
+technical rationale, and desired decision. Reassess the finding against the
+repository rubric and accept a sound alternative that meets the same outcome.
+
+Seek a maintainer or lead decision when the discussion requires ownership or
+product direction beyond the available evidence. Keep the resulting decision in
+the pull request record.
+
+## Related Guides
+
+- Use [comments](../comments/SKILL.md#when-to-use-this-guide) to draft or answer
+  review feedback.
+- Use [descriptions](../descriptions/SKILL.md#when-to-use-this-guide) to prepare
+  or assess pull request context.
+- Use [emergencies](../emergencies/SKILL.md#emergency-classification) to classify
+  an urgent production change.
+- Use [small-cl](../small-cl/SKILL.md#when-to-use-this-guide) to focus or split
+  a change that exceeds a clear review boundary.

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/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`.