claude-dev-env 1.41.0 → 1.43.0

package/_shared/pr-loop/scripts/tests/test_preflight_constants.py

@@ -6,9 +6,13 @@ from types import ModuleType
 
 
 def _load_constants_module() -> ModuleType:
-    module_path = Path(__file__).parent.parent / "config" / "preflight_constants.py"
+    module_path = (
+        Path(__file__).parent.parent
+        / "pr_loop_shared_constants"
+        / "preflight_constants.py"
+    )
     specification = importlib.util.spec_from_file_location(
-        "config.preflight_constants", module_path
+        "pr_loop_shared_constants.preflight_constants", module_path
     )
     assert specification is not None
     assert specification.loader is not None

package/_shared/pr-loop/scripts/tests/test_revoke_project_claude_permissions.py

@@ -1,7 +1,8 @@
 """Smoke tests for revoke_project_claude_permissions wiring.
 
 Confirms the module imports cleanly with the constants now sourced from
-config/claude_permissions_constants.py and config/claude_settings_keys_constants.py.
+pr_loop_shared_constants/claude_permissions_constants.py and
+pr_loop_shared_constants/claude_settings_keys_constants.py.
 """
 
 from __future__ import annotations
@@ -17,7 +18,6 @@ def _load_revoke_module() -> ModuleType:
     parent_directory = str(scripts_directory.resolve())
     if parent_directory not in sys.path:
         sys.path.insert(0, parent_directory)
-    sys.modules.pop("config", None)
     module_path = scripts_directory / "revoke_project_claude_permissions.py"
     specification = importlib.util.spec_from_file_location(
         "revoke_project_claude_permissions", module_path
@@ -32,7 +32,9 @@ def _load_revoke_module() -> ModuleType:
 def test_module_imports_constants_from_config_modules() -> None:
     revoke_module = _load_revoke_module()
     assert revoke_module.ALL_PERMISSION_ALLOW_TOOLS == ("Edit", "Write", "Read")
-    assert "{project_path}" in revoke_module.AUTO_MODE_ENVIRONMENT_ENTRY_TEMPLATE
+    assert revoke_module.AUTO_MODE_ENVIRONMENT_ENTRY_PREFIX == (
+        "Trusted local workspace:"
+    )
     assert revoke_module.CLAUDE_SETTINGS_PERMISSIONS_KEY == "permissions"
 
 

package/agents/pr-description-writer.md

@@ -1,185 +1,95 @@
 ---
 name: pr-description-writer
-description: "MANDATORY agent for writing PR descriptions, commit messages, PR comments, and issue comments. Enforced by the pr_description_enforcer PreToolUse hook -- every gh pr create/edit invocation that carries a body is blocked until this agent has authored it. Produces output in the style of merged pull requests in anthropics/claude-code, anthropics/claude-code-action, and anthropics/claude-cli-internal: trivial one-liners for mechanical changes, intro-paragraph + Changes + Test plan for standard fixes, full Problem/Fix/Verification with optional Caveat/Runtime-behavior for heavy changes. Triggers: write a PR body, draft a PR description, author the commit message, comment on the PR, comment on the issue, prepare the body for gh pr create / gh pr edit / gh pr comment / gh issue comment, generate the body-file, fix the blocked PR description."
+description: "MANDATORY agent for PR descriptions and PR comments. Enforced by the `pr_description_enforcer` PreToolUse hook on `gh pr create`, `gh pr edit`, and `gh pr comment`. Authors bodies in one of three Anthropic-derived shapes (Trivial / Standard / Heavy) so PRs match merged-PR style in `anthropics/claude-code`, `anthropics/claude-code-action`, and `anthropics/claude-code-sdk-python`."
 tools: Read,Grep,Glob,Bash
 model: haiku
 ---
 
 # PR Description Writer
 
-You author PR descriptions, commit messages, and PR/issue comments in the shape that merged pull requests in `anthropics/claude-code`, `anthropics/claude-code-action`, and `anthropics/claude-cli-internal` take. You pick the shape from the diff. You write the body text and nothing else -- the caller passes it to `gh pr create --body-file`.
+You write PR bodies and PR comments. Your output follows Anthropic Claude Code house style. The style derives from a 120-PR sample across `anthropics/claude-code`, `anthropics/claude-code-action`, and `anthropics/claude-code-sdk-python`. Pick a shape that matches the diff size. Open with an imperative verb. Explain WHY the change exists in prose a reviewer can scan. The companion reference `packages/claude-dev-env/docs/PR_DESCRIPTION_GUIDE.md` carries the full header catalog and the readability escape-hatch flow.
 
-## TOC
+## The three shapes
 
-- Process (the 4-step checklist)
-- Sizing (Trivial / Standard / Heavy)
-- Shape 1: Trivial (sectionless one-liner)
-- Shape 2: Standard (intro + Changes + Test plan)
-- Shape 3: Heavy (intro + Problem + Fix + Verification + optional)
-- File reference style
-- Cross-references
-- Markers and footers
-- Commit messages
-- Gotchas
-- Refusals
+Choose one shape per body. Mixing shapes signals confusion to the reviewer.
 
-The companion guide (`packages/claude-dev-env/docs/PR_DESCRIPTION_GUIDE.md`) carries the section-vocabulary table and the hook's pass/block contract -- do not duplicate that content here.
+### Trivial — diff ≤ 10 lines
 
-## Process
+One to three sentences of prose. Zero headers. No `## Summary`, no `## Test plan`. The opening verb describes the change directly.
 
-Copy this checklist into your response and check items off as you go:
-
-- [ ] Inspect the diff: `git diff <base>...HEAD --stat`, then `git diff <base>...HEAD` for any file whose purpose isn't obvious from the path.
-- [ ] If the branch name or any commit mentions an issue (`fix-1311`, `Fixes #1311`), read it: `gh issue view 1311`.
-- [ ] Pick the shape from the Sizing table.
-- [ ] Write the body in that shape. Output ONLY the body text -- no preamble, no `<body>` tags, no trailing commentary.
-
-## Sizing
-
-| Signal | Shape |
-|---|---|
-| 1-3 files, mechanical change (pin bump, link fix, typo, single-line config), no behavior change | **Trivial** |
-| Behavior change, bug fix, small feature; under ~15 files | **Standard** |
-| New subsystem, refactor across many files, schema or contract change, anything with a caveat | **Heavy** |
-
-Prefer the smaller shape when borderline. Anthropic authors prefer the smaller shape.
-
-## Shape 1: Trivial
-
-One declarative sentence. No Markdown headers. Optional `Fixes #N` line.
-
-```
-Pin third-party GitHub Actions references to immutable commit SHAs.
+```markdown
+Bump bun to 1.3.14. Picks up the bugfix for the runtime panic on empty stdin.
 ```
 
-```
-Bump pinned Bun from 1.3.6 to 1.3.14.
-
-Fixes #1311.
-```
+### Standard — diff 11–500 lines
 
-## Shape 2: Standard
-
-```
-<One short intro paragraph stating the change and why it matters.
- Reference the failure mode or user-visible symptom when there is one.>
+Opens with an imperative-verb paragraph. Optional headers drawn from the Anthropic set: `## Summary`, `## Problem`, `## Fix`, `## Changes`, `## Test plan`, `## Tests`, `## Testing`, `## Approach`, `## Root cause`. Most Standard PRs use one or two — pick the ones the change earns.
 
-Fixes #<n>.
-
-## Changes
-
-- `path/to/file.ext`: short clause describing the change
-- `path/to/other.ext`: short clause
-- `tests/foo.test.ts`: 2 new cases for X
+```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
 
-- `bun test test/foo.test.ts`
-- `bun run typecheck`
-- Manual: reproduce on a branch named `feature/a,b`; confirm no rejection
+- [ ] `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
 ```
 
-## Shape 3: Heavy
-
-```
-<Two- to four-sentence intro: scope, motivation, user-visible effect.
- Link to the prior PR or issue that motivates this one if applicable.>
+### Heavy — diff > 500 lines, or a cross-cutting bug fix
 
-Fixes #<n>.
+Two required header categories. Body MUST contain at least one of `## Problem` or `## Summary`. Body MUST contain at least one of `## Test plan`, `## Testing`, `## Tests`, `## Verification`, or `## Validation`. Add `## Fix`, `## Changes`, `## Root cause`, or `## Approach` when the change earns them.
 
+```markdown
 ## Problem
 
-<Concrete description of the failure mode or gap. Quote the actual
- error text or a reproduction in a fenced code block when it helps.>
-
-```
-<error or reproduction>
-```
+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
 
-<What the change does at the level a reviewer needs to evaluate it.
- Reference the file or function by path. Don't restate the diff
- line-by-line.>
-
-- `src/path/file.ts`: brief description
-- `src/path/other.ts`: brief description
-
-## Verification
+Routes every `gh api .../reviews` and `.../comments` call through `--paginate --slurp | jq` so the cross-page filter sees the full set.
 
-- Command 1
-- Command 2 (with output count when useful: "666 pass, 0 fail")
-- Manual scenarios walked through
-
-## Caveat
+## Test plan
 
-<Anything a reviewer or downstream user needs to know that isn't in
- the diff. Omit the section when there is no caveat.>
+- [ ] Mock paginated API and assert `jq` filter operates on the merged stream
+- [ ] Replay PR #467 review history and confirm the late bugbot comment surfaces
 ```
 
-Optional Heavy-shape sections, used only when they earn their place: `## Runtime behavior`, `## Components` (as a path/type/invocation table), `## Backward compatibility`, `## Context`.
-
-## File reference style
-
-- Backtick file paths: `` `src/github/operations/branch.ts` ``.
-- Use the full path from repo root unless the basename is unambiguous within the PR.
-- Per-file change bullets lead with the backticked path and a colon:
-  - `` `src/foo.ts`: whitelists `,` in branch names ``
-- When one file is the centerpiece, bold the backticked filename: `` **`branch.ts`**: ... ``.
+## Style rules
 
-## Cross-references
+- Open with an imperative verb: `Adds`, `Fixes`, `Updates`, `Removes`, `Ports`, `Tightens`. 51% of prose-opening Anthropic PRs follow this pattern.
+- Do not open with `This PR`. The phrase appears in 1 of 120 corpus PRs. The enforcer hook treats `This PR adds/fixes/updates…` as a hard block.
+- Backticked identifiers (`function_name`, `--flag`, `CONST`) belong in intro prose. Anthropic PRs use them routinely.
+- Em-dashes — like these — work as parenthetical separators. 48% of corpus PRs use them.
+- Focus on WHY. The diff shows WHAT.
+- No code snippets in the description body. Reviewers read the diff for code.
+- No implementation-detail dumping. `Add a 5-second timeout` beats ``Add `pullStartedAt: Date.now()` parameter to the `runPull()` callback``.
+- No filler. Strike `In this PR I have made the following changes:` and start with the action.
 
-- Same-repo: `#1311`. Cross-repo: `anthropics/claude-code#40576`.
-- `Fixes #N` and `Closes #N` close the issue on merge -- pick one and use it deliberately.
-- `Linear: CC-1723` on its own line.
-- "Follow-up to #<n>" / "Same change as <repo>#<n>" -- short orientation one-liners are welcome.
-
-## Markers and footers
-
-- `<!-- NO CHANGELOG -->` at the end, on its own line, for docs-only or CI-only PRs in repos that auto-generate changelogs from titles.
-- No "Generated with Claude Code" footer. Merged Anthropic PRs do not use one consistently and the commit trailer covers attribution.
-
-## Commit messages
+## Gotchas
 
-Same shape, compressed:
+- **Self-closing reference.** Do not write `Fixes #<the PR's own number>` in a `gh pr edit` or `gh pr comment` body. The enforcer hook reads the positional after `pr edit` or `pr comment` and blocks the body when the self-reference matches.
+- **Trivial shape with `## Summary` header.** A four-line body wrapped in `## Summary` trips the ceremony-on-Trivial check. Keep tiny bodies as plain prose.
+- **Heavy shape missing a testing header.** A 600-line PR body with `## Problem` and `## Fix` but no `## Test plan` / `## Testing` / `## Tests` block trips the Heavy required-headers check.
+- **`This PR` opening on any shape.** Hard block regardless of size.
+- **Dual-mode dispatch (unique pattern in `hooks/blocking/`).** The `pr_description_enforcer.py` hook reads `sys.argv` for `--readability-*` CLI flags as well as its stdin-JSON hook input. This dual-mode pattern is the only one of its kind across the blocking hooks directory. When extending the hook, preserve the precedence: CLI flags handled first and exited; stdin-JSON path falls through.
 
-- First line: imperative summary, max 72 chars. Conventional-commit prefix when the repo uses them (`fix:`, `feat:`, `chore:`, `docs:`, `ci:`, `style:`, `refactor:`).
-- Blank line.
-- Body: one short paragraph stating the Why and the Fix together. Reference the issue when relevant.
-- Skip the body entirely for trivial commits whose first line says everything.
+## Readability targets
 
-```
-fix: allow , in branch names
+The enforcer hook computes a Flesch Reading Ease score plus sentence-length metrics on the intro paragraph and the first body section combined.
 
-git check-ref-format permits commas; the whitelist in
-src/github/operations/branch.ts did not, so PRs whose head
-branch contained a comma failed validation before any git
-operation. Add `,` to the whitelist; same reasoning as
-adding `#` (#1167) and `+` (#1248).
-
-Fixes #1300.
-```
+| Metric | Target |
+|---|---|
+| Longest sentence | ≤ 28 words |
+| Average sentence | ≤ 18 words |
+| Flesch Reading Ease | ≥ 50 |
 
-## Gotchas
+The hook tracks a per-user strike counter at `~/.claude/state/pr_description_readability_strikes.json`. The first two readability failures emit a metric-specific block (e.g., `Readability: longest sentence is 32 words (maximum 28); split or rewrite the longest sentence`). The third triggering failure fires an escape-hatch message listing four recovery actions. The full action list lives in `PR_DESCRIPTION_GUIDE.md` under "Escape hatch".
 
-Highest-signal content. Each item is a real failure mode that has shown up in PR drafts that needed to be rewritten before merge.
-
-- **Don't restate the PR title as the body's first line.** The title is already displayed. Start with the *consequence* the reader cares about.
-- **Don't add `## Why` over a single-paragraph intro.** A header on one paragraph reads as ceremony. The unmarked intro paragraph IS the Why.
-- **Don't add a "Generated with Claude Code" footer.** Anthropic's own merged PRs use this footer inconsistently; defaulting to omit matches the median.
-- **Don't write second-person commentary to the reviewer.** "Please review carefully" / "Let me know if" / "WDYT" don't appear in merged Anthropic PR bodies.
-- **Don't restate the diff in `## Changes`.** Per-file bullets describe the *purpose* of the change in the file, not the line edits. The reviewer reads the diff.
-- **Don't put verification commands in `## Changes`.** They go in `## Test plan` / `## Verification`. Mixing them obscures both.
-- **Don't bold a filename without backticks.** Filenames are code; the canonical form is `` **`branch.ts`**: ... ``, never `**branch.ts**:`.
-- **Don't mix `Fixes #N` and `Closes #N` within one body.** Both close the linked issue on merge -- pick one verb per PR.
-- **Don't add empty section headers.** If `## Caveat` would be empty, drop it. Headers exist to organize content, not to satisfy a template.
-- **Don't hedge.** "should", "might", "I think" -- delete or replace with a verified claim or an explicit "not yet verified" call-out.
-- **Trivial PRs need no sections.** Resist the urge to add `## Summary` over a one-sentence body. The hook does not require headers; the style does not invite them.
-- **The hook permits sectionless bodies.** A single substantive sentence (>= 40 chars of prose after stripping ceremony) passes the `pr_description_enforcer` substantive-prose check. Don't add headers to placate the hook -- the hook isn't asking for them.
+Hit the targets on first attempt by writing short sentences in common Anglo-Saxon words. The average tracks the corpus median of 14.5.
 
 ## Refusals
 
-First match wins. Respond with the quoted line exactly and stop:
+Decline to write a body when:
 
-- **No diff visible** (e.g., called against an empty branch or before any commits land). Respond: `No diff to describe. Run "git diff <base>...HEAD --stat" first; if the diff is genuinely empty, the PR shouldn't exist.`
-- **Caller asks for prose to be edited into the PR description rather than authored from the diff** (e.g., "add a paragraph saying X to the existing body"). Respond: `Author the body from the diff, not from external prose. Fetch the current diff and re-derive; if the caller has standing instruction text that must appear verbatim, paste it as a Caveat block.`
+- The PR has zero diff lines (genuinely empty).
+- The user describes intent that contradicts the diff (e.g., "describe this as a bug fix" when the diff adds a feature).
+- The user requests a shape that violates the hook (e.g., `## Summary` on a one-line bump). Offer the correct shape.

package/docs/PR_DESCRIPTION_GUIDE.md

@@ -1,158 +1,157 @@
 # PR Description Guide
 
-This guide describes the PR-body shape that the `pr-description-writer` agent produces and that the `pr_description_enforcer` PreToolUse hook validates against. The style mirrors merged pull requests in `anthropics/claude-code`, `anthropics/claude-code-action`, and `anthropics/claude-cli-internal`.
+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.
 
-## Three shapes, picked from the diff
+## Anthropic style basis
 
-Pick the shape from the size and risk of the change, not from a template.
+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.
 
-| Signal | Shape |
-|---|---|
-| 1-3 files, mechanical change (pin bump, link fix, typo, single-line config), no behavior change | **Trivial** -- one declarative sentence, no headers |
-| Behavior change, bug fix, small feature; under ~15 files | **Standard** -- intro paragraph + `## Changes` + `## Test plan` (or `## Validation`) |
-| New subsystem, refactor across many files, schema or contract change, anything with a caveat | **Heavy** -- intro + `## Problem` + `## Fix` (or `## Changes`) + `## Verification` + extra sections as needed |
+Key signals from the corpus:
 
-Prefer the smaller shape when in doubt.
+- **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.
 
-## Shape 1: Trivial
+## The three shapes
 
-One sentence. No Markdown headers. Optional `Fixes #N` line.
+### Trivial
 
-```
-Pin third-party GitHub Actions references to immutable commit SHAs.
-```
+- **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.
 
-```
-Bump pinned Bun from 1.3.6 to 1.3.14.
+Example:
 
-Fixes #1311.
+```markdown
+Bump bun to 1.3.14. Picks up the bugfix for the runtime panic on empty stdin.
 ```
 
-## Shape 2: Standard
-
-```
-<One short intro paragraph stating the change and why it matters.
- Reference the failure mode or user-visible symptom when there is one.>
+### Standard
 
-Fixes #<n>.
+- **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`.
 
-## Changes
+Example:
 
-- `path/to/file.ext`: short clause describing the change
-- `path/to/other.ext`: short clause
-- `tests/foo.test.ts`: 2 new cases for X
+```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
 
-- `bun test test/foo.test.ts`
-- `bun run typecheck`
-- Manual: reproduce on a branch named `feature/a,b`; confirm no rejection
+- [ ] `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
 ```
 
-The intro paragraph carries the Why -- no `## Why` header needed when one paragraph is enough.
+### Heavy
 
-## Shape 3: 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.
 
-```
-<Two- to four-sentence intro: scope, motivation, user-visible effect.
- Link to the prior PR or issue that motivates this one if applicable.>
-
-Fixes #<n>.
+Example:
 
+```markdown
 ## Problem
 
-<Concrete description of the failure mode or gap. Include the actual
- error text, a reproduction, or the symptomatic log line in a fenced
- code block when it helps.>
+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.
 
-```
-<example error or reproduction>
+## 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
 ```
 
-## Fix
+## Header vocabulary
 
-<What the change does at the level a reviewer needs to evaluate it.
- Reference the file or function by path/name. Don't restate the diff
- line-by-line -- the reviewer can read the code.>
+| 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 |
 
-- `src/path/file.ts`: brief description
-- `src/path/other.ts`: brief description
+`## Test plan` and `## Root cause` use sentence-case in the corpus. The enforcer regex matches case-insensitively.
 
-## Verification
+## Readability targets
 
-- Command 1
-- Command 2 (with output count when useful: "666 pass, 0 fail")
-- Manual scenarios walked through
+The enforcer measures three metrics on the intro paragraph and first body section combined.
 
-## Caveat
+| Metric | Target |
+|---|---|
+| Longest sentence | ≤ 28 words |
+| Average sentence | ≤ 18 words |
+| Flesch Reading Ease | ≥ 50 |
 
-<Anything a reviewer or downstream user needs to know that isn't in
- the diff. Omit this section when there is no caveat.>
-```
+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.
 
-Optional heavy-shape sections, used when they earn their place:
+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.
 
-- `## Runtime behavior` -- when the change preserves behavior but moves it.
-- `## Components` -- a small table when the PR introduces multiple named artifacts.
-- `## Backward compatibility` -- when an older consumer might still hit this code path.
-- `## Context` -- background a reviewer outside the area would need.
+## Escape hatch
 
-## Section vocabulary
+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.
 
-Pick from these. Don't invent new ones, and don't use synonyms within one PR:
+### Action 1 — loosen thresholds 10%
 
-| Intent | Header (pick one) |
-|---|---|
-| What this PR is and why | `## Summary` -- or no header (preferred when 1-3 sentences) |
-| The failure being fixed | `## Problem` -- or no header when the intro paragraph carries it |
-| The change itself | `## Changes` or `## Fix` |
-| How it was verified | `## Test plan`, `## Validation`, `## Verification`, or `## Testing` |
-| Things to know | `## Caveat`, `## Runtime behavior`, `## Backward compatibility`, `## Context` |
+```bash
+python <enforcer-path> --readability-loosen
+```
 
-## File reference style
+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.
 
-- Always backtick file paths: `` `src/github/operations/branch.ts` ``.
-- Use the full path from repo root, not just the basename, unless the basename is unambiguous within the PR.
-- Bullet lists describing per-file changes lead with the backticked path and a colon:
-  - `` `src/foo.ts`: whitelists `,` in branch names ``
-  - `` `test/foo.test.ts`: 3 new cases for comma-bearing branches ``
-- Prose calling out a single primary file bolds the backticked filename plus a colon: `` **`branch.ts`**: ... ``.
+Caps:
 
-## Cross-references
+- 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.
 
-- Issue/PR shorthand: `#1311` (same repo), `anthropics/claude-code#40576` (cross-repo).
-- `Fixes #N` and `Closes #N` close the linked issue on merge -- use them deliberately.
-- `Linear: CC-1723` -- one line, no Markdown, after the intro paragraph or at the bottom.
-- "Same change as <repo>#<n>" / "Follow-up to #<n>" -- one-liners that orient a reviewer.
+### Action 2 — disable readability entirely
 
-## Markers and footers
+```bash
+python <enforcer-path> --readability-disable
+```
 
-- `<!-- NO CHANGELOG -->` on its own line, at the very end, for docs-only or CI-only PRs in repos that auto-generate changelogs from PR titles.
-- Don't add a "Generated with Claude Code" footer -- merged Anthropic PRs don't use one consistently, and the repo's commit trailer covers attribution.
+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.
 
-## What the hook checks
+Re-enable with:
 
-`pr_description_enforcer.py` runs on `gh pr create` and `gh pr edit` invocations that include a body. It blocks when any of the following are true:
+```bash
+python <enforcer-path> --readability-enable
+```
 
-- The body, after stripping Markdown ceremony (headers, code fences, bullet markers, bold/emphasis, link text), contains fewer than 40 characters of prose. A skeleton of `## Summary` + `## Changes` + bullets with no Why paragraph fails here.
-- The body contains vague phrases like `fix bug`, `update code`, `minor changes`, or `various fixes`.
+### Action 3 — reset the strike counter
 
-The hook does not require any specific section headers -- `## Summary`, `## Problem`, `## Fix`, `## Changes`, `## Test plan` are all optional, including any combination of them. A single substantive sentence ("Pin third-party GitHub Actions references to immutable commit SHAs.") satisfies the check.
+```bash
+python <enforcer-path> --readability-reset
+```
 
-When the hook blocks, it points the caller at the `pr-description-writer` agent and at this guide.
+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.
 
-## Tone
+### Action 4 — report a false positive
 
-- Plain language. "The pull engine would blindly overwrite any record marked as 'synced'" -- not "PullEngine.run() exhibited non-idempotent behavior".
-- Active voice. "Add `,` to the whitelist" -- not "`,` was added to the whitelist".
-- No filler. Start with the content, not "This PR..." or "In this change...".
-- No restating the diff. Trust the reviewer to read the code; explain the parts they can't infer.
-- No hedging ("should", "might", "I think") unless the uncertainty is real -- in which case say "not yet verified" and call it out.
+Reply with the PR body and your intended commit message. The maintainer tunes the thresholds or refines the regex.
 
 ## What to avoid
 
-- Code snippets that simply repeat the diff. Code blocks are for error reproductions, failing commands, or before/after when the contrast is the point.
-- Technical jargon for non-obvious internals ("Dexie transaction" -> "database transaction").
-- Multi-line preamble. The PR title already says what the change is.
-- Section headers over empty content. If `## Caveat` would be empty, drop the header.
-- Second-person commentary directed at the reviewer ("please review carefully"). The reviewer knows their job.
+- **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/hooks/_gh_pr_author_swap_utils.py

@@ -32,7 +32,7 @@ import tempfile
 from pathlib import Path
 from typing import TextIO
 
-from config.gh_pr_author_swap_constants import (
+from hooks_constants.gh_pr_author_swap_constants import (
     ALL_GH_AUTH_SWITCH_COMMAND_HEAD,
     ALL_SHELL_QUOTE_CHARACTERS,
     BASH_COMMENT_INTRODUCER_CHARACTER,

package/hooks/blocking/bot_mention_comment_blocker.py

@@ -10,17 +10,11 @@ import json
 import sys
 from pathlib import Path
 
+_hooks_dir = str(Path(__file__).resolve().parent.parent)
+if _hooks_dir not in sys.path:
+    sys.path.insert(0, _hooks_dir)
 
-def _insert_hooks_tree_for_imports() -> None:
-    hooks_tree = Path(__file__).resolve().parent.parent
-    hooks_tree_string = str(hooks_tree)
-    if hooks_tree_string not in sys.path:
-        sys.path.insert(0, hooks_tree_string)
-
-
-_insert_hooks_tree_for_imports()
-
-from config.bot_mention_comment_blocker_constants import (
+from hooks_constants.bot_mention_comment_blocker_constants import (  # noqa: E402
     COPILOT_MENTION_TOKEN,
     CORRECTIVE_MESSAGE_COPILOT,
     CORRECTIVE_MESSAGE_CURSOR,