claude-dev-env 1.67.2 → 1.69.0

package/_shared/CLAUDE.md

@@ -0,0 +1,13 @@
+# _shared
+
+Cross-cutting runtime assets shared by multiple PR-loop skills (`bugteam`, `pr-converge`, `findbugs`, `fixbugs`). Files here are installed into `~/.claude/_shared/` by `bin/install.mjs` alongside the skill directories that import them.
+
+## Contents
+
+| Entry | Description |
+|---|---|
+| `pr-loop/` | Docs, scripts, and constants for the PR-loop workflow suite |
+
+## Install path
+
+`bin/install.mjs` copies this entire directory tree verbatim to `~/.claude/_shared/`. Skills reference files here by relative path from their own skill root (e.g. `../../_shared/pr-loop/audit-contract.md`).

package/_shared/pr-loop/CLAUDE.md

@@ -0,0 +1,24 @@
+# _shared/pr-loop
+
+Runtime documents and scripts shared by every PR-loop skill. Changes here affect `bugteam`, `pr-converge`, `findbugs`, `fixbugs`, and `qbug` simultaneously — treat this as a breaking-change surface.
+
+## Key documents
+
+| File | Purpose |
+|---|---|
+| `audit-contract.md` | Canonical finding schema (Shape A / Shape B) and loop contract; defines the JSON shapes every audit skill must emit |
+| `audit-reply-template.md` | Canonical reply skeleton Claude posts to each unresolved review thread; single source of truth for reply structure |
+| `fix-protocol.md` | Ordered sequence a fix lens follows: read, capture SHA, TDD, apply, validate, self-audit, commit, push, reply + resolve |
+| `gh-payloads.md` | How to build GitHub review and reply payloads via MCP tools; describes the one-review-per-loop pattern |
+| `state-schema.md` | Fields each PR-loop workflow tracks across iterations; documents common fields and per-skill extensions |
+| `code-rules-gate.md` | Reference for the CODE_RULES pre-commit gate check; describes what the gate blocks and when it runs |
+
+## Subdirectory
+
+| Entry | Description |
+|---|---|
+| `scripts/` | Python scripts and constants consumed at runtime by the PR-loop skills |
+
+## Breaking-change rule
+
+Any shape change in `audit-contract.md` or `audit-reply-template.md` requires updating every consuming skill in the same commit.

package/_shared/pr-loop/scripts/CLAUDE.md

@@ -0,0 +1,30 @@
+# _shared/pr-loop/scripts
+
+Python scripts invoked at runtime by the PR-loop skills. Each script is a standalone CLI entry point; `pr_loop_shared_constants/` holds the named constants they import.
+
+## Key scripts
+
+| File | Purpose |
+|---|---|
+| `preflight.py` | Pre-flight check run before each audit loop tick: verifies hooks path, finds test files, runs pytest, checks for `BUGTEAM_PREFLIGHT_SKIP` opt-out |
+| `preflight_self_heal.py` | Clears stale `core.hooksPath` overrides that Git seeds into fresh worktree local config; called from `preflight.py` |
+| `post_audit_thread.py` | Posts an audit review (APPROVE / REQUEST_CHANGES) to a draft PR via the GitHub reviews API; reads the body skeleton from `audit-reply-template.md` at runtime |
+| `grant_project_claude_permissions.py` | Writes idempotent allow-rules and `additionalDirectories` entries into `~/.claude/settings.json` so subagents can edit the project's `.claude/` tree without prompting |
+| `revoke_project_claude_permissions.py` | Removes the allow-rules and entries that `grant_project_claude_permissions.py` wrote; safe to run when no prior grant exists |
+| `code_rules_gate.py` | Pre-commit gate that runs `code_rules_enforcer` checks on staged Python files before a fix commit lands |
+| `reviews_disabled.py` | Shared helper for the `CLAUDE_REVIEWS_DISABLED` opt-out gate; parses the env-var token to find which reviewer types are suppressed |
+| `fix_hookspath.py` | Repairs a malformed `core.hooksPath` global git config entry |
+| `_claude_permissions_common.py` | Internal helpers shared by the grant/revoke scripts: atomic settings.json writes, list mutation, path helpers |
+
+## Subdirectories
+
+| Entry | Description |
+|---|---|
+| `pr_loop_shared_constants/` | Named constants used by the scripts above |
+| `tests/` | pytest suite for all scripts in this directory |
+
+## Running tests
+
+```bash
+python -m pytest packages/claude-dev-env/_shared/pr-loop/scripts/tests/
+```

package/_shared/pr-loop/scripts/pr_loop_shared_constants/CLAUDE.md

@@ -0,0 +1,21 @@
+# pr_loop_shared_constants
+
+Named constants for every script in `_shared/pr-loop/scripts/`. Each module owns the constants for one script; the module name mirrors the script name with a `_constants` suffix.
+
+## Modules
+
+| File | Constants for |
+|---|---|
+| `claude_permissions_constants.py` | `grant_project_claude_permissions.py` and `revoke_project_claude_permissions.py` — permission rule strings and settings.json keys |
+| `claude_settings_keys_constants.py` | Top-level `~/.claude/settings.json` key names used across the permission helpers |
+| `code_rules_gate_constants.py` | `code_rules_gate.py` — file extensions, git diff subcommands, test filename patterns |
+| `fix_hookspath_constants.py` | `fix_hookspath.py` — verification suffix and related strings |
+| `post_audit_thread_constants.py` | `post_audit_thread.py` — HTTP status codes, retry counts, GitHub API paths |
+| `preflight_constants.py` | `preflight.py` — env-var names, git subcommands, pytest exit codes, test discovery patterns |
+| `preflight_self_heal_constants.py` | `preflight_self_heal.py` — git config keys and local-scope detection strings |
+| `reviews_disabled_constants.py` | `reviews_disabled.py` — `CLAUDE_REVIEWS_DISABLED` token taxonomy |
+| `__init__.py` | Empty package marker |
+
+## Convention
+
+Every constant is `UPPER_SNAKE_CASE` with an explicit type annotation. No magic literals appear in the consuming scripts — all values live here. Test coverage for each module lives in `tests/test_<module_name>.py`.

package/_shared/pr-loop/scripts/tests/CLAUDE.md

@@ -0,0 +1,32 @@
+# _shared/pr-loop/scripts/tests
+
+pytest suite for the scripts and constants in `_shared/pr-loop/scripts/`. Each test file covers one script or one constants module.
+
+## Test files
+
+| File | Covers |
+|---|---|
+| `test__claude_permissions_common.py` | Internal helpers in `_claude_permissions_common.py` (legacy underscore prefix) |
+| `test_claude_permissions_common.py` | Public API of `_claude_permissions_common.py` |
+| `test_claude_permissions_constants.py` | `pr_loop_shared_constants/claude_permissions_constants.py` |
+| `test_claude_settings_keys_constants.py` | `pr_loop_shared_constants/claude_settings_keys_constants.py` |
+| `test_code_rules_gate.py` | `code_rules_gate.py` gate logic |
+| `test_code_rules_gate_constants.py` | `pr_loop_shared_constants/code_rules_gate_constants.py` |
+| `test_fix_hookspath.py` | `fix_hookspath.py` repair logic |
+| `test_fix_hookspath_constants.py` | `pr_loop_shared_constants/fix_hookspath_constants.py` |
+| `test_grant_project_claude_permissions.py` | `grant_project_claude_permissions.py` end-to-end |
+| `test_post_audit_thread.py` | `post_audit_thread.py` review-posting flow |
+| `test_post_audit_thread_constants.py` | `pr_loop_shared_constants/post_audit_thread_constants.py` |
+| `test_preflight.py` | `preflight.py` pre-flight checks |
+| `test_preflight_constants.py` | `pr_loop_shared_constants/preflight_constants.py` |
+| `test_preflight_self_heal.py` | `preflight_self_heal.py` hooks-path repair |
+| `test_reviews_disabled.py` | `reviews_disabled.py` opt-out gate parsing |
+| `test_revoke_project_claude_permissions.py` | `revoke_project_claude_permissions.py` end-to-end |
+| `test_agent_config_carveout.py` | Agent-config deny-rule carve-out logic |
+| `conftest.py` | Shared pytest fixtures |
+
+## Running
+
+```bash
+python -m pytest packages/claude-dev-env/_shared/pr-loop/scripts/tests/
+```

package/agents/CLAUDE.md

@@ -0,0 +1,29 @@
+# agents
+
+Agent definition files installed into `~/.claude/agents/` by `bin/install.mjs`. Each `.md` file defines a named subagent: its description (shown in the Claude Code UI), allowed tools, and behavioral instructions.
+
+## Agent files
+
+| File | Agent name | Role |
+|---|---|---|
+| `caveman.md` | Caveman Agent | Terse voice and smallest-possible artifacts; questions premise before building |
+| `clasp-deployment-orchestrator.md` | Clasp Deployment Orchestrator | Creates and deploys Google Apps Script projects with multiple files |
+| `clean-coder.md` | Clean Coder | Primary code-writing agent; internalizes CODE_RULES.md and targets zero `/check` findings |
+| `code-advisor.md` | Code Advisor | Mid-run advisor for executor agents; returns plans or stop signals — no tools, no edits |
+| `code-quality-agent.md` | Code Quality Agent | Multi-file code quality review across an entire diff or set of files |
+| `code-verifier.md` | Code Verifier | Post-hoc verification after coder agents finish; read-only, fresh context, ends with a fenced verdict |
+| `deep-research.md` | Deep Research | Citation-grounded research with web search |
+| `docs-agent.md` | Docs Agent | Documentation authoring and maintenance |
+| `git-commit-crafter.md` | Git Commit Crafter | Stages changes, writes conventional commit messages, creates commits |
+| `plan-packet-validator.md` | Plan Packet Validator | Fresh-context validator for workflow-generated plan packets under `docs/plans/` |
+| `pr-description-writer.md` | PR Description Writer | Authors PR descriptions in Anthropic-style shapes; required by the `pr_description_enforcer` hook |
+
+## Format
+
+Each file uses YAML frontmatter (`name`, `description`, `tools`, optional `color`) followed by a Markdown body with the agent's behavioral instructions. The `description` field appears in the Claude Code agent picker.
+
+## Adding an agent
+
+1. Create a new `.md` file in this directory with valid frontmatter.
+2. Run `bin/install.mjs` to copy it to `~/.claude/agents/`.
+3. Restart Claude Code to pick up the new agent.

package/audit-rubrics/CLAUDE.md

@@ -0,0 +1,41 @@
+# audit-rubrics
+
+Audit rubrics for the PR-loop code-review suite. The rubrics define the 16 bug categories (A–P), their sub-bucket decompositions, and the prompt templates agents use during an audit pass. Installed into `~/.claude/audit-rubrics/` by `bin/install.mjs`.
+
+## Key file
+
+| File | Purpose |
+|---|---|
+| `source-material-section-types.md` | Lookup table for how to chunk an artifact into sections for an audit prompt; covers code PRs, docs, SQL schemas, config files, and more |
+
+## Subdirectories
+
+| Entry | Description |
+|---|---|
+| `category_rubrics/` | One `.md` per category (A–P): defines what the category audits, example findings, and a sub-bucket decomposition table |
+| `prompts/` | One `.md` per category: the ready-to-use audit prompt template an agent inlines the artifact into |
+
+## Categories
+
+| ID | Name |
+|---|---|
+| A | API contract verification |
+| B | Selector engine compatibility |
+| C | Resource cleanup |
+| D | Scoping and ordering |
+| E | Dead code |
+| F | Silent failures |
+| G | Bounds and overflow |
+| H | Security boundaries |
+| I | Concurrency |
+| J | Code-rules compliance |
+| K | Codebase conflicts |
+| L | Behavior equivalence |
+| M | Producer-consumer cardinality |
+| N | Test name / scenario verifier |
+| O | Docstring vs implementation drift |
+| P | Name vs behavior contract |
+
+## Breaking-change rule
+
+Adding a sub-bucket to a category rubric requires updating the matching prompt template in `prompts/` in the same commit. Skills that reference category IDs (`bugteam`, `findbugs`) rely on stable sub-bucket IDs (A1, A2, … P-n).

package/audit-rubrics/category_rubrics/CLAUDE.md

@@ -0,0 +1,36 @@
+# audit-rubrics/category_rubrics
+
+One rubric file per audit category (A–P). Each file defines what the category covers, gives concrete examples of findings, and provides the sub-bucket decomposition an audit agent uses to structure its pass.
+
+## Files
+
+| File | Category |
+|---|---|
+| `category-a-api-contracts.md` | A — API contract verification |
+| `category-b-selector-engine-compat.md` | B — Selector engine compatibility |
+| `category-c-resource-cleanup.md` | C — Resource cleanup |
+| `category-d-scoping-and-ordering.md` | D — Scoping and ordering |
+| `category-e-dead-code.md` | E — Dead code |
+| `category-f-silent-failures.md` | F — Silent failures |
+| `category-g-bounds-and-overflow.md` | G — Bounds and overflow |
+| `category-h-security-boundaries.md` | H — Security boundaries |
+| `category-i-concurrency.md` | I — Concurrency |
+| `category-j-code-rules-compliance.md` | J — Code-rules compliance |
+| `category-k-codebase-conflicts.md` | K — Codebase conflicts |
+| `category-l-behavior-equivalence.md` | L — Behavior equivalence |
+| `category-m-producer-consumer-cardinality.md` | M — Producer-consumer cardinality |
+| `category-n-test-name-scenario-verifier.md` | N — Test name / scenario verifier |
+| `category-o-docstring-vs-impl-drift.md` | O — Docstring vs implementation drift |
+| `category-p-name-vs-behavior-contract.md` | P — Name vs behavior contract |
+
+## Rubric structure
+
+Each file has:
+- A plain-language description of what the category audits
+- Concrete finding examples
+- A companion-reference pointer to `../source-material-section-types.md`
+- A sub-bucket decomposition table with stable IDs (A1, A2, …) and the concrete checks each bucket requires
+
+## Relationship to prompts/
+
+`category_rubrics/` is the human-readable reference. `prompts/` holds the agent-ready prompt templates that inline the same sub-bucket list in a structured prompt format. Keep both in sync when sub-buckets change.

package/audit-rubrics/category_rubrics/category-o-docstring-vs-impl-drift.md

@@ -25,7 +25,7 @@ Decomposition is by the **kind of docstring claim** that needs to be cross-check
 | O3 | Predicate-name and -docstring vs body breadth | A boolean helper's name and docstring promise a narrow predicate. Walk the body's branches: every branch's `return True` path is consistent with the promised name. Bodies that accept inputs broader than the name (`_dir_value_resolves_to_shared_temp` also accepting HOME/TMP env-derived paths) are O3 findings. |
 | O4 | Step-ordering narrative | A docstring describes processing as `A then B then C`. Walk the body and confirm the call order matches. Mismatched order is an O4 finding regardless of whether the final output is the same. |
 | O5 | Named-sentinel / filename references | A docstring names a sentinel marker, environment variable, filename, or magic string. Confirm the named token actually exists in the module body or in the repo's naming convention. |
-| O6 | Free-form `Args:`-adjacent claims | A docstring's `Returns:` / `Raises:` / `Note:` / `Example:` sections make claims (`returns shared-temp only`, `raises ValueError on missing key`). Verify each claim against the body. When a docstring enumerates the inputs a body counts (a "field counts as read when ..." list, a list of conditions treated as a match, a list of cases the body skips), list every union member and every suppressor the body applies (`read_names = a | b | c`, each early-return guard) and confirm each appears in the prose enumeration. A union member or suppressor the body applies but the prose omits is an O6 finding. A `Returns:` that names the mechanism, tool, or output format the function produces (`instructing a StructuredOutput summary`, `returns a YAML document`, `emits a JSON object`) matches the artifact the body actually builds: a prompt body that asks the agent to "Return strictly a JSON object" while the docstring claims it "instruct[s] a StructuredOutput" summary is an O6 finding, because the named tool appears nowhere in the emitted text. See `../../rules/docstring-prose-matches-implementation.md`. |
+| O6 | Free-form `Args:`-adjacent claims | A docstring's `Returns:` / `Raises:` / `Note:` / `Example:` sections make claims (`returns shared-temp only`, `raises ValueError on missing key`). Verify each claim against the body. When a docstring enumerates the inputs a body counts (a "field counts as read when ..." list, a list of conditions treated as a match, a list of cases the body skips), list every union member and every suppressor the body applies (`read_names = a | b | c`, each early-return guard) and confirm each appears in the prose enumeration. A union member or suppressor the body applies but the prose omits is an O6 finding. The single-condition shared-fallback shape of this drift — a summary that scopes a fallback call to one condition while the body routes to that same call from two or more early-return guards — is gated deterministically at Write/Edit time by `check_docstring_fallback_branch_coverage`, so the audit lane focuses on the O6 shapes the gate cannot match. A `Returns:` that names the mechanism, tool, or output format the function produces (`instructing a StructuredOutput summary`, `returns a YAML document`, `emits a JSON object`) matches the artifact the body actually builds: a prompt body that asks the agent to "Return strictly a JSON object" while the docstring claims it "instruct[s] a StructuredOutput" summary is an O6 finding, because the named tool appears nowhere in the emitted text. See `../../rules/docstring-prose-matches-implementation.md`. |
 | O7 | Module-doc-vs-split-module after refactor | When a refactor moves a responsibility to a sibling module, the originating module's docstring and the receiving module's docstring both describe the home of that responsibility. A module docstring should describe only the responsibilities it owns. |
 
 ---

package/audit-rubrics/prompts/CLAUDE.md

@@ -0,0 +1,36 @@
+# audit-rubrics/prompts
+
+Agent-ready audit prompt templates, one per category (A–P). An agent inlines the artifact under review into the `[INLINE THE FULL ARTIFACT HERE]` placeholder and runs the prompt as-is.
+
+## Files
+
+| File | Category |
+|---|---|
+| `category-a-api-contracts.md` | A — API contract verification |
+| `category-b-selector-engine-compat.md` | B — Selector engine compatibility |
+| `category-c-resource-cleanup.md` | C — Resource cleanup |
+| `category-d-scoping-and-ordering.md` | D — Scoping and ordering |
+| `category-e-dead-code.md` | E — Dead code |
+| `category-f-silent-failures.md` | F — Silent failures |
+| `category-g-bounds-and-overflow.md` | G — Bounds and overflow |
+| `category-h-security-boundaries.md` | H — Security boundaries |
+| `category-i-concurrency.md` | I — Concurrency |
+| `category-j-code-rules-compliance.md` | J — Code-rules compliance |
+| `category-k-codebase-conflicts.md` | K — Codebase conflicts |
+| `category-l-behavior-equivalence.md` | L — Behavior equivalence |
+| `category-m-producer-consumer-cardinality.md` | M — Producer-consumer cardinality |
+| `category-n-test-name-scenario-verifier.md` | N — Test name / scenario verifier |
+| `category-o-docstring-vs-impl-drift.md` | O — Docstring vs implementation drift |
+| `category-p-name-vs-behavior-contract.md` | P — Name vs behavior contract |
+
+## Prompt structure
+
+Each template:
+- Scopes the audit to one category only (skip the others)
+- Lists all sub-buckets from the matching `category_rubrics/` file
+- Requires each sub-bucket to produce at least one Shape A finding OR one Shape B proof-of-absence with three or more adversarial probes
+- Uses `find` as the finding ID prefix (single-pass audits) rather than `loop<N>-<K>`
+
+## Relationship to category_rubrics/
+
+`prompts/` is the executable form; `category_rubrics/` is the reference form. When a sub-bucket decomposition changes in a rubric, update the matching prompt in the same commit.

package/bin/CLAUDE.md

@@ -0,0 +1,28 @@
+# bin
+
+The installer and its companion modules. Running `npx claude-dev-env` (or `node bin/install.mjs`) copies package files into `~/.claude/`, merges hook entries into `~/.claude/settings.json`, installs Git hooks, and writes `~/.mypy.ini`.
+
+## Files
+
+| File | Purpose |
+|---|---|
+| `install.mjs` | Main installer: discovers install groups, copies content directories (`rules`, `docs`, `commands`, `agents`, `system-prompts`, `scripts`, `_shared`, `audit-rubrics`), merges hooks into `settings.json`, installs skills, runs `git_hooks_installer.mjs` and `install_mypy_ini.mjs` |
+| `git_hooks_installer.mjs` | Installs or updates the `pre-commit`, `pre-push`, and `post-commit` Git hooks in the user's git config; writes hook scripts that delegate to the installed Python hooks |
+| `install_mypy_ini.mjs` | Writes `~/.mypy.ini` with settings that make mypy find the hooks package and enforce strict type checking |
+| `install.test.mjs` | Tests for `install.mjs` — covers conflict detection, interpreter detection, settings merging |
+| `git_hooks_installer.test.mjs` | Tests for `git_hooks_installer.mjs` |
+| `install_mypy_ini.test.mjs` | Tests for `install_mypy_ini.mjs` |
+
+## Key exports from install.mjs
+
+| Export | Description |
+|---|---|
+| `CONTENT_DIRECTORIES` | Array of package subdirectory names copied verbatim to `~/.claude/` |
+| `pythonCandidatesForPlatform(platform)` | Returns ordered Python interpreter candidates to probe; `py -3` first on Windows to avoid Microsoft Store alias issues |
+| `isWindowsStorePythonStub(path)` | Returns true when the path resolves to the non-spawnable WindowsApps stub |
+| `interpreterCommandFromPath(path)` | Formats an absolute interpreter path as a settings.json hook command prefix |
+| `collectPackageSourceConflicts(dir)` | Returns any unmerged git conflicts in the package source; installer aborts when any exist |
+
+## Install groups
+
+`install.mjs` defines install groups (`core`, `journal`, `research`) plus any dependency groups discovered from `package.json` `dependencies`. The `core` group installs skills, all hooks, and the content directories. `journal` and `research` install only their skill sets.

package/commands/CLAUDE.md

@@ -0,0 +1,25 @@
+# commands
+
+Slash-command definitions installed into `~/.claude/commands/` by `bin/install.mjs`. Each `.md` file registers a `/command-name` the user can type in Claude Code. The file name (without `.md`) becomes the command name.
+
+## Command files
+
+| File | Command | What it does |
+|---|---|---|
+| `commit.md` | `/commit` | Commits and pushes changes to GitHub |
+| `doc-gist.md` | `/doc-gist` | Uploads an HTML file as a secret gist and opens the htmlpreview URL |
+| `docupdate.md` | `/docupdate` | Updates documentation to match current code state |
+| `hook-log-extract.md` | `/hook-log-extract` | Extracts and formats hook log entries for a session |
+| `hook-log-init.md` | `/hook-log-init` | Initializes the Neon Postgres schema that backs the hook-log extractor (one-time per machine) |
+| `implement.md` | `/implement` | Provides full implementation context to a right-sized engineer in XML format |
+| `initialize.md` | `/initialize` | Bootstraps a new project with standard Claude Code config |
+| `plan.md` | `/plan` | Plans a feature through the `anthropic-plan` skill and workflow |
+| `pr-comments.md` | `/pr-comments` | Fetches and formats PR review comments for response |
+| `review-plan.md` | `/review-plan` | Reviews the current plan packet against code standards |
+| `right-size.md` | `/right-size` | Checks an implementation against the Right-Sized Engineering rules |
+| `stubcheck.md` | `/stubcheck` | Finds stub bodies (`pass`/`...`/`raise NotImplementedError`) in the diff |
+| `sum.md` | `/sum` | Generates a formatted session summary for quick pickup in a new session |
+
+## Format
+
+Each file is plain Markdown. The first paragraph is the command's help text shown in the Claude Code UI. The body is the full instruction set Claude follows when the command runs.

package/docs/CLAUDE.md

@@ -0,0 +1,28 @@
+# docs
+
+Reference documentation installed into `~/.claude/docs/` by `bin/install.mjs`. These files are loaded on demand by rules, skills, and agents — they are not always-on context.
+
+## Files
+
+| File | Purpose |
+|---|---|
+| `CODE_RULES.md` | Compact agent reference for all code rules; ⚡ marks hook-enforced rules; canonical source agents load before writing code |
+| `TEST_QUALITY.md` | Test writing standards: what to test, what to remove, React testing patterns, anti-patterns |
+| `BDD_DISCOVERY_PROTOCOL.md` | Example Mapping algorithm for discovery before implementation; based on Smart & Molak *BDD in Action* §6.4 |
+| `BDD_SCENARIO_QUALITY.md` | Seven scenario quality patterns (§7.6-style catalog) |
+| `BDD_TEST_LAYOUT.md` | `describe/when/should` test layout and soap-opera personas |
+| `PR_DESCRIPTION_GUIDE.md` | Authoritative reference for the `pr-description-writer` agent; PR body shapes derived from a 120-PR Anthropic corpus |
+| `DJANGO_PATTERNS.md` | Django-specific coding patterns |
+| `REACT_PATTERNS.md` | React-specific coding patterns |
+| `emotion-informed-prompt-design.md` | Guidance for emotionally-aware prompt authoring |
+| `agents-md-alignment-plan.md` | Alignment between `AGENTS.md` review-tool rules and the local hook enforcement layer |
+
+## Subdirectory
+
+| Entry | Description |
+|---|---|
+| `references/` | Pointer documents to external sources and standard terminology; loaded on demand |
+
+## Load pattern
+
+Rules reference these docs with `@~/.claude/docs/<file>.md` to pull them into context only when needed, rather than loading every doc on every session start.

package/docs/references/CLAUDE.md

@@ -0,0 +1,13 @@
+# docs/references
+
+Pointer documents to external sources and standard terminology. Files here are loaded on demand by rules that cite external resources.
+
+## Files
+
+| File | Purpose |
+|---|---|
+| `dead-code-elimination.md` | External sources and standard terms behind CODE_RULES §9.8 (remove code you orphan): DCE, tree shaking, reachability analysis, and the Lava Flow anti-pattern |
+
+## Role
+
+Each file names an external concept, gives a one-line definition, and links a direct source. They back the rule text in `rules/` and `packages/claude-dev-env/docs/CODE_RULES.md` without embedding full third-party content inline.

package/hooks/CLAUDE.md

@@ -0,0 +1,31 @@
+# hooks
+
+Python hook scripts wired into Claude Code's lifecycle via `settings.json`. Each hook answers one or more lifecycle events (`PreToolUse`, `PostToolUse`, `Stop`, `SubagentStop`, `SessionStart`, `SessionEnd`) and either blocks a tool call, annotates it, or performs a side-effect.
+
+## Subdirectories
+
+| Directory | Role |
+|---|---|
+| `advisory/` | Hooks that warn but do not block (`permissionDecision: "ask"`) |
+| `blocking/` | Hooks that deny tool calls when a rule is violated |
+| `blocking/config/` | Shared constants for the verified-commit gate family |
+| `diagnostic/` | Hooks that record and extract hook-firing records into Neon |
+| `diagnostic/migrations/` | SQL migrations for the `hook_events` Neon schema |
+| `diagnostic/queries/` | Parameterized SQL queries for inspecting blocked commands |
+| `git-hooks/` | Native git hooks (`pre-commit`, `pre-push`, `post-commit`) installed via the git-hooks path |
+| `git-hooks/git_hooks_constants/` | Shared constants for the git-hook scripts |
+| `hooks_constants/` | Shared constant modules imported by multiple hooks across this tree |
+| `lifecycle/` | Hooks that run at session or config-change boundaries |
+| `observability/` | PostToolUse hooks that record agent behavior for diagnostics |
+| `session/` | SessionStart and SessionEnd hooks for per-session cleanup |
+| `validation/` | PostToolUse hooks that validate code quality after a write (mypy, auto-format) |
+| `validators/` | Library modules used by the validation hooks — checks split by concern |
+| `workflow/` | PostToolUse hooks that trigger doc publishing and companion-file generation |
+
+## Conventions
+
+- **Event mapping:** Every hook reads JSON from stdin and exits 0 (allow) or prints a `hookSpecificOutput` block (block/ask). Blocking hooks set `permissionDecision: "block"`.
+- **Constants companion:** Each hook with more than a handful of tunable strings keeps them in a `hooks_constants/<hook_name>_constants.py` sibling. Import from there; do not repeat literals.
+- **Tests:** Each hook has one or more `test_<hookname>*.py` files beside it. Run with `python -m pytest <test_file>`.
+- **Registration:** Hooks are declared in `settings.json` under the right lifecycle event. The installer (`packages/claude-dev-env/bin/install.mjs`) merges the hook entries during `npx claude-dev-env`.
+- **Top-level utilities:** `_gh_pr_author_swap_utils.py` and `rewrite_plugin_paths.py` are shared helpers imported by multiple blocking hooks. `hooks.json` records the canonical hook-to-event mapping for auditing.

package/hooks/advisory/CLAUDE.md

@@ -0,0 +1,16 @@
+# hooks/advisory
+
+Hooks that produce a warning prompt (`permissionDecision: "ask"`) rather than an outright block. The user sees the warning and can continue or cancel.
+
+## Key files
+
+| File | Event | What it guards |
+|---|---|---|
+| `migration_safety_advisor.py` | PreToolUse (Write/Edit) | Django migration files containing `RemoveField`, `RenameField`, `DeleteModel`, or `RenameModel` — warns that these operations must be backwards-compatible during deployment |
+| `refactor_guard.py` | PreToolUse (Edit) | Edits that rename or restructure existing code not present in the current git diff — warns that the change may be out of scope |
+
+## Conventions
+
+- Both hooks exit 0 (silent) when their trigger condition is not met.
+- `refactor_guard.py` respects a bypass token at `~/.claude/.refactor-bypass-token`; when that file exists the hook stays silent.
+- Tests live beside each hook following the `test_<name>.py` pattern used in `blocking/`. Run with `python -m pytest <test_file>`.

package/hooks/blocking/CLAUDE.md

@@ -0,0 +1,107 @@
+# hooks/blocking
+
+PreToolUse hooks that deny (block) tool calls when a rule is violated. The main enforcer is `code_rules_enforcer.py`, which routes each Write/Edit through a suite of focused check modules. Every other file in this directory is either a standalone blocker, a check module, or a test.
+
+## Subdirectory
+
+| Directory | Role |
+|---|---|
+| `config/` | Shared constants for the verified-commit gate family (`verified_commit_constants.py`) |
+
+## Core enforcer
+
+| File | What it does |
+|---|---|
+| `code_rules_enforcer.py` | Entry point — reads PreToolUse stdin, reconstructs post-edit content, dispatches all check modules, and returns a block with a per-issue list when any check fails |
+
+The check modules it calls are the `code_rules_<concern>.py` files below.
+
+## Check modules (imported by `code_rules_enforcer.py`)
+
+| Module | Concern |
+|---|---|
+| `code_rules_annotations_length.py` | Parameter/return annotations, function length, pytest fixture annotation requirements |
+| `code_rules_banned_identifiers.py` | Banned short names (`ctx`, `cfg`, `msg`, etc.), banned prefixes (`handle_`, `process_`, etc.) |
+| `code_rules_boolean_mustcheck.py` | Boolean naming (`is_`/`has_`/… prefixes) and must-check return values |
+| `code_rules_comments.py` | No new inline comments; no deletion of existing ones |
+| `code_rules_constants_config.py` | Constants must live in `config/`; file-global constant use-count |
+| `code_rules_dead_argparse_argument.py` | Argparse arguments with no references in the same file |
+| `code_rules_dead_config_field.py` | Dataclass config fields with no live references |
+| `code_rules_dead_dataclass_field.py` | Dataclass fields with no consuming references |
+| `code_rules_dead_module_constant.py` | `UPPER_SNAKE` constants in `*_constants.py` modules with no importers |
+| `code_rules_docstrings.py` | Google-style docstrings; `Args:` section matches signature; fallback-branch coverage |
+| `code_rules_duplicate_body.py` | Functions whose bodies match another function's body in the same file |
+| `code_rules_imports_logging.py` | Imports at top of file; logging format-arg style |
+| `code_rules_magic_values.py` | No magic numbers or strings in production code bodies |
+| `code_rules_mock_completeness.py` | Mock calls that skip required arguments |
+| `code_rules_naming_collection.py` | Collection names must use `all_*` prefix |
+| `code_rules_optional_params.py` | No optional parameters where a required one would do |
+| `code_rules_orphan_css_class.py` | CSS class attributes in Python markup with no matching `.<class>` selector |
+| `code_rules_path_utils.py` | Path utility helpers shared across check modules |
+| `code_rules_paths_syspath.py` | `sys.path.insert` must be guarded |
+| `code_rules_probe_chains.py` | Probe-chain detection logic |
+| `code_rules_probe_detection.py` | Probe pattern detection helpers |
+| `code_rules_probe_recording.py` | Probe recording utilities |
+| `code_rules_scope_binding.py` | Scope/binding analysis utilities |
+| `code_rules_shared.py` | Shared dataclasses and helpers used by multiple check modules |
+| `code_rules_string_magic.py` | Magic string detection with masking and f-string support |
+| `code_rules_test_assertions.py` | Test assertion style rules |
+| `code_rules_test_branching_except.py` | No bare or broad `except` in test branches |
+| `code_rules_test_isolation.py` | Tests must not rely on home-dir or temp-dir side effects |
+| `code_rules_type_escape.py` | No `Any` imports, `cast()`, or `# type: ignore` outside boundary files |
+| `code_rules_typeddict_stub.py` | TypedDict pairs (`_encode_*`/`_decode_*`) must both exist in the same module |
+| `code_rules_unused_imports.py` | Unused module-level imports |
+
+## Other standalone blockers
+
+| File | Event | What it blocks |
+|---|---|---|
+| `block_main_commit.py` | PreToolUse (Bash) | `git commit`/`git push` directly to `main` |
+| `bot_mention_comment_blocker.py` | PreToolUse (Write/Edit) | PR review comments that @-mention a bot |
+| `convergence_gate_blocker.py` | PreToolUse (Bash) | Convergence workflow actions on a conflicting PR |
+| `destructive_command_blocker.py` | PreToolUse (Bash/PowerShell) | Shell commands with destructive literals (`rm -rf`, `git reset --hard`, etc.) |
+| `es_exe_path_rewriter.py` | PreToolUse | Rewrites paths referencing `.exe` under the Everything search path |
+| `gh_body_arg_blocker.py` | PreToolUse (Bash) | `gh` commands passing `--body`/`-b` directly (requires `--body-file` instead) |
+| `gh_pr_author_enforcer.py` | PreToolUse | Enforces PR author identity rules |
+| `gh_pr_author_restore.py` | PostToolUse | Restores PR author after a tool call |
+| `hedging_language_blocker.py` | Stop | Responses with hedging words (`likely`, `probably`, `appears to`) |
+| `hook_prose_detector_consistency.py` | PreToolUse (Write/Edit) | Hook docstrings/messages that claim a trigger the detector cannot fire on |
+| `intent_only_ending_blocker.py` | Stop | Responses that end on a plan or intent without doing the work |
+| `md_to_html_blocker.py` | PreToolUse (Write/Edit) | Writing `.md` files when an `.html` companion is required |
+| `open_questions_in_plans_blocker.py` | PreToolUse (Write/Edit) | Plan documents with unresolved open questions |
+| `plain_language_blocker.py` | PreToolUse (Write/Edit/AskUserQuestion) | Heavy or jargon words in user-facing prose |
+| `pr_converge_bugteam_enforcer.py` | PreToolUse | Enforces that bugteam runs in parallel with bugbot in pr-converge loops |
+| `pr_description_enforcer.py` | PreToolUse (Bash) | `gh pr create`/`edit` without a PR-description-writer-authored body |
+| `precommit_code_rules_gate.py` | PreToolUse (Bash) | Staged changes that fail the CODE_RULES gate at commit time |
+| `question_to_user_enforcer.py` | Stop | User-directed questions not routed through `AskUserQuestion` |
+| `sensitive_file_protector.py` | PreToolUse (Write/Edit) | Writes to sensitive credential or config files |
+| `session_handoff_blocker.py` | Stop | Responses suggesting a new session mid-task |
+| `state_description_blocker.py` | PreToolUse (Write/Edit) | Historical/comparative language in documentation |
+| `subprocess_budget_completeness.py` | PreToolUse | Subprocess calls missing required budget arguments |
+| `tdd_enforcer.py` | PreToolUse (Write/Edit) | Production code written without a matching failing test |
+| `verdict_directory_write_blocker.py` | PreToolUse (Bash/PowerShell) | Shell writes into `~/.claude/verification/` |
+| `verified_commit_gate.py` | PreToolUse (Bash/PowerShell) | `git commit`/`git push` without a passing verifier verdict |
+| `verified_commit_message_accuracy_blocker.py` | PreToolUse | Commit messages that misstate what the diff has |
+| `verifier_verdict_minter.py` | SubagentStop | Mints a passing verdict file when a `code-verifier` agent finishes cleanly |
+| `windows_rmtree_blocker.py` | PreToolUse (Write/Edit) | `shutil.rmtree` with `ignore_errors=True` on Windows |
+| `workflow_substitution_slot_blocker.py` | PreToolUse (Write/Edit) | Workflow templates with bare per-iteration tokens missing angle-bracket slots |
+| `write_existing_file_blocker.py` | PreToolUse (Write) | Write to a path where a file already exists |
+
+## Supporting modules
+
+| File | Role |
+|---|---|
+| `_gh_body_arg_utils.py` | Parsing helpers for `gh_body_arg_blocker.py` |
+| `_md_to_html_blocker_test_support.py` | Test fixtures shared across `md_to_html_blocker` tests |
+| `md_path_exemptions.py` | Path exemption logic for `md_to_html_blocker.py` |
+| `pr_description_body_audit.py` | Body audit logic for `pr_description_enforcer.py` |
+| `pr_description_command_parser.py` | `gh` command parsing for `pr_description_enforcer.py` |
+| `pr_description_pr_number.py` | PR number extraction logic |
+| `pr_description_readability.py` | Readability checks on PR description bodies |
+| `verification_verdict_store.py` | Reads and writes verdict files under `~/.claude/verification/` |
+
+## Conventions
+
+- Tests live beside each hook as `test_<hookname>.py` or `test_<hookname>_<suffix>.py`. Run with `python -m pytest <test_file>`.
+- Tunable constants live in `hooks_constants/<hook_name>_constants.py`; the verified-commit family uses `blocking/config/verified_commit_constants.py`.
+- `conftest.py` gives shared pytest fixtures for the blocking test suite.

package/hooks/blocking/code_rules_constants_config.py

@@ -203,15 +203,18 @@ def check_file_global_constants_use_count(content: str, file_path: str) -> list[
     """Flag module-level UPPER_SNAKE constants referenced by only one function/method.
 
     Enforces the file-global-constants use-count rule: a constant used by just
-    one caller belongs in that caller's scope. Test files, config files, and
-    non-Python files are exempt. Constants with zero references are out of
-    scope. The enforcer entry module (``hooks/blocking/code_rules_enforcer.py``)
-    is exempt to avoid self-blocking.
+    one caller belongs in that caller's scope. Test files, config files,
+    workflow-registry files, and non-Python files are exempt. Constants with
+    zero references are out of scope. The enforcer entry module
+    (``hooks/blocking/code_rules_enforcer.py``) is exempt to avoid
+    self-blocking.
     """
     if is_test_file(file_path):
         return []
     if is_config_file(file_path):
         return []
+    if is_workflow_registry_file(file_path):
+        return []
     if get_file_extension(file_path) not in ALL_PYTHON_EXTENSIONS:
         return []
     if file_path.replace("\\", "/").endswith("hooks/blocking/code_rules_enforcer.py"):