claude-dev-env 1.50.3 → 1.51.0

package/audit-rubrics/prompts/category-p-name-vs-behavior-contract.md

@@ -0,0 +1,75 @@
+Audit [REPO/ARTIFACT] [TARGET_ID] for **Category P only** (name / regex / word-list vs behavior-contract precision). Skip A–O. Sub-bucket forced-exhaustion mode: Category P is decomposed into 7 sub-buckets below. Each sub-bucket REQUIRES at least one Shape A finding OR exactly one Shape B proof-of-absence with **at least 3 adversarial probes** specific to that sub-bucket. A sub-bucket returning neither is a protocol gap.
+
+[ARTIFACT METADATA — every newly-added or renamed identifier plus the body code that implements its contract]
+
+- Title / one-line summary: [TITLE]
+- Head ref / SHA at audit time: [HEAD_SHA]
+- New / renamed boolean flags (file:line + identifier + lifecycle sites): [NEW_FLAGS]
+- New / renamed predicate helpers (file:line + identifier + body + return contract): [NEW_PREDICATES]
+- New / renamed regex constants (file:line + identifier + regex source + anchors): [NEW_REGEXES]
+- New / renamed word-lists or replacement tables (file:line + identifier + entries): [NEW_LISTS]
+- New / renamed helper-function names (file:line + identifier + signature + return): [NEW_HELPERS]
+- Stated intent of each new identifier: [INTENT]
+
+ID prefix: `find`.
+
+[ONE-PARAGRAPH FRAME: list every fresh identifier introduced by the diff. State the audit goal: for each identifier, verify the body's behavior matches the contract the name asserts — not broader, not narrower.]
+
+## Source material ([N] files/sections, all lines in scope)
+
+[INLINE each fresh identifier in context — the constant declaration with the value, the function signature with the body, the flag with every assignment / reset site, the regex source with surrounding usage.]
+
+## Sub-buckets (each requires Shape A finding OR Shape B with ≥3 adversarial probes)
+
+**P1. Boolean / flag names assert state the body keeps**
+- For every new `is_*` / `has_*` / `was_*` / `should_*` flag, trace the body. Every set site must be paired with a reset site that fires when the named condition becomes false.
+- Adversarial probes: (a) grep every assignment to the flag — count set-true vs set-false; (b) for AST-driven flags, walk the visit method and confirm scope-exit semantics (def visited → flag set; dedent / function-exit → flag reset); (c) construct an input where the flag should be false after a prior true region — does the code agree.
+
+**P2. Predicate-name breadth matches body coverage**
+- For every new `_is_*` / `_has_*` / `_can_*` predicate function, list the body's `return True` branches. The named predicate must hold on the union of those branches and nothing else.
+- Adversarial probes: (a) construct an input that satisfies the name but returns False — that is a P2 narrowness finding; (b) construct an input that does not satisfy the name but returns True — that is a P2 breadth finding; (c) check neighbor predicates — is the body's actual contract the responsibility of a different helper.
+
+**P3. Regex name vs regex shape** ⭐ canonical P case
+- For every new `*_PATTERN` / `*_REGEX` constant, read the regex source. Confirm the anchors (`^`, `$`, `\b`, lookarounds) match the name's promised shape. `FILE_PATH_PATTERN` implies path shape; the regex must include path-shape anchors (slash count, segment shape, length bounds) enough to reject non-path inputs.
+- Adversarial probes: (a) construct 3 non-matching inputs that the regex's name says it should reject — does the regex reject them; (b) construct 3 inputs that satisfy the regex but violate the name — those are P3 findings; (c) check sibling regexes in the same module — is the new regex anchored consistently with them.
+
+**P4. Helper-function name vs return contract**
+- For every new helper function, compare the name to the return shape AND the matching semantics. `_split_module_stem_prefix` should split on a stem-prefix boundary; if the returned prefix substring-matches unrelated stems, the matching semantics diverge from the name.
+- Adversarial probes: (a) feed the helper an input class the name names — is the return what the name implies; (b) feed it an input the name excludes — does the helper still produce output; (c) check downstream callers — do they consume the return on the contract the name implies.
+
+**P5. Word-list / replacement-table precision**
+- For every new reference list, walk each entry. Every entry must satisfy the named class. A list named `HEAVY_WORDS_TO_REPLACE` may not contain words that are ordinary in legitimate user inputs.
+- Adversarial probes: (a) for each entry, construct 3 legitimate-looking inputs containing it — would the gate fire on legitimate writing; (b) check entry density against the named class — is the list curated or kitchen-sink; (c) propose 3 entries that fit the named class better and 3 entries that do not fit — does the list match the proposed-good or the proposed-bad set.
+
+**P6. Class / module name vs scope**
+- For every new class or module, list the responsibilities (exported symbols, dispatched calls). Confirm each fits the named scope.
+- Adversarial probes: (a) list exported symbols and ask whether each matches the named scope; (b) check imports — does the module pull in unrelated subsystems; (c) check call-graph centrality — does the class own one thing or many.
+
+**P7. Reverse: name understates what the body does**
+- For every new identifier, ask whether the body produces effects the name does not promise (side effects, more return values, broader input acceptance, hidden state mutation). A future caller relying on the narrow name will be surprised.
+- Adversarial probes: (a) walk side effects (writes, network calls, global mutation) — are they named in the contract; (b) walk return tuples / objects — is every component named; (c) walk input acceptance — does the helper silently accept inputs outside its named class.
+
+## Cross-bucket questions to answer at the end
+
+Q1: Across all 7 sub-buckets, which identifier's name-vs-body gap is most likely to cause false positives in a production gate? Cite the identifier and the input class that trips it.
+
+Q2: Which identifier is at highest risk of being relied on by a future caller based on the name alone, with the broader / narrower body causing a regression? Cite the identifier and the assumed contract.
+
+Q3: Which identifier most clearly shows the body should be renamed (the name is honest about intent and the body is wrong) vs the name should be tightened (the body is the contract and the name overpromises)? Cite the identifier and the recommended direction.
+
+## Output
+
+Lead: `Total: N (P0=N, P1=N, P2=N)`. For each sub-bucket P1-P7, produce Shape A or Shape B (with ≥3 probes). Each Shape A finding must cite (a) the identifier file:line, (b) one concrete input that shows the name-vs-body gap, and (c) the recommended fix direction (rename vs body-tighten). Cross-bucket Q1-Q3 answers after the per-sub-bucket walk. Adversarial second pass: "assume your first pass missed at least 3 identifiers whose names overstate what the body actually does — find them." Open Questions section for ambiguities. Read-only. No edits, no commits.
+
+---
+
+# Worked example: jl-cmd/claude-code-config PR #508
+
+Audit jl-cmd/claude-code-config PR #508 for **Category P only** (name / regex / word-list vs behavior-contract precision). Skip A-O.
+
+PR #508 ships the plain-language blocker hook. Two fresh identifiers in `plain_language_blocker_constants.py` show the canonical P shapes:
+
+- `FILE_PATH_PATTERN` (line 286) — a regex of shape `(\S+/\S+)` named for file paths but unanchored. Probes: `client/server`, `and/or`, `TCP/IP`, `lookup/replace` all match and are silently exempted from the plain-language scan even though none is a file path. **P3 finding.**
+- `HARD_DENY_REPLACEMENT_TERMS` (line 247) — a hard-deny replacement-by-term list named for ban-worthy heavy words but containing `command`, `address`, `function`, `subject`, `same`, `such`, `said`, `it is`, `there is`, `however`, `forward`. Each entry trips on ordinary technical English (`run the command`, `the address bar`, `validate the function`). **P5 finding.**
+
+Expected output: two P-class findings with cited file:line of the constant, cited example inputs (`client/server`, `run the command`), and recommended direction (anchor the regex to need repo-relative paths; curate the deny-list to drop dev-domain false positives).

package/docs/CODE_RULES.md

@@ -1,419 +1,97 @@
 # Code Rules Reference
 
-Compact reference for agents. Hook-enforced rules marked with ⚡.
+Compact reference for agents. ⚡ marks rules enforced by `code_rules_enforcer.py` — the hook blocks the Write/Edit and returns the corrective detail at violation time, so this document lists those rules by name only.
 
 ---
 
 ## COMMENT PRESERVATION (ABSOLUTE RULE)
 
-**NEVER remove existing comments.** If you are not adding or removing code on a line, do not touch its comments.
-
-- Existing comments are SACRED — never delete, rewrite, or "clean up" existing comments
-- New inline comments are not needed — write self-documenting code instead
-- Module-level docstrings are allowed in all files
-- Docstrings for new files/methods/classes are allowed
-- **Test files are exempt:** comments and docstrings inside test functions are allowed
-- The hook enforces BOTH directions: blocks new inline comments AND blocks deletion of existing comments
-
-**Scope:** Only evaluate comments on lines YOU are actively changing. If code is untouched, its comments are untouched.
+**NEVER remove existing comments.** Existing comments are SACRED. Only evaluate comments on lines you are actively changing. Do not add new inline comments in production code — write self-documenting code. Docstrings (module/class/function) are always allowed. Test files are exempt. The hook enforces both directions: it blocks new inline comments AND blocks deletion of existing ones.
 
 ---
 
 ## CORE PRINCIPLES
 
-### Self-Documenting Code
-New code explains itself through naming. Do not add new inline comments — use descriptive names instead. Docstrings on functions/methods/classes are allowed.
-
-> **Full readability standard:** `~/.claude/skills/readability-review/SKILL.md` — 8-dimension rubric (naming, SRP, abstraction, control flow, domain language, call sites, state clarity, visual rhythm). Run `/check` for parallel team review or `/readability-review` standalone.
-
-### Centralized Configuration
-One source of truth. Every constant lives in ONE place (`config/`).
-
-### Reuse Before Create
-Search first. Import second. Create last.
-
-### Encapsulation Enables Cleaner Naming
-Expose constants via helper functions: `isMaxLevel(level)` > `level >= MAXIMUM_LEVEL`
+- **Self-documenting code** — naming over comments. Full 8-dimension rubric: `~/.claude/skills/readability-review/SKILL.md` (`/check` for parallel team review, `/readability-review` standalone).
+- **Centralized configuration** — every constant lives in ONE place (`config/`).
+- **Reuse before create** — search first, import second, create last.
+- **Encapsulation enables cleaner naming** — `isMaxLevel(level)` > `level >= MAXIMUM_LEVEL`.
 
 ---
 
 ## ⚡ HOOK-ENFORCED RULES
 
-These rules are automatically enforced by `code_rules_enforcer.py`. Violations block Write/Edit.
-
-| Rule | What's Checked |
-|------|----------------|
-| No NEW comments | `#` / `//` in new production code only (existing comments NEVER removed; exempt markers: shebangs, `# type:`, `# noqa`, `# pylint:`, `# pragma:`, `// @ts-`, `// eslint-`, `// prettier-`, `/// `; docstrings and module docstrings are always allowed; all test files are exempt) |
-| Imports at top | No `import` inside function bodies |
-| Logging format args | No `log_*(f"...")` - use `log_*("...", arg)` |
-| File line count | Advisory only — see [File length guidance](#65-file-length-guidance) |
-| Magic values | No literals in production function bodies (0, 1, -1 exempt). **Test files exempt.** Includes string templates — if you strip the interpolations from an f-string and the remaining literal text is structural (paths, URLs, patterns), those fragments are magic values that belong in config |
-| Constants location | No `UPPER_SNAKE =` outside `config/` in **production code**. **Test files may define local constants.** |
-| Hardcoded user paths | No string literals naming a specific user's home directory in production code (`C:/Users/jon/...`, `/Users/alice/...`, `/home/bob/...`). Use `pathlib.Path.home()` or `os.path.expanduser('~')`. **Exempt:** test files, `config/` files, workflow registry paths (`/workflow/`, `_tab.py`, `/states.py`, `/modules.py`), Django migrations (`/migrations/`), and hook infrastructure (the enforcer embeds path patterns and must not self-block). |
-| sys.path.insert dedup | `sys.path.insert(0, X)` must be guarded by `if X not in sys.path:` (or equivalent membership test) so reloads do not push the same entry repeatedly. **Test files exempt.** |
-| Unused module-level imports | Module-level imports never referenced in the file body are flagged. Skipped for files declaring `__all__` (re-exports), files using `TYPE_CHECKING` (annotation-only imports), and lines marked `# noqa`. **Test files exempt.** |
-| Banned identifiers | Single-letter or 2–4 char abbreviations in production code: `ctx`, `cfg`, `msg`, `btn`, `idx`, `cnt`, `tmp`, `elem`, `val`. Test files exempt; loop counters `i`/`j`/`k` and exception `e` exempt. See §5 for the full list and rationale. |
-| Banned function prefixes | Function names starting with `handle_`, `process_`, `manage_`, or `do_` are flagged — these prefixes describe nothing about behavior. Name functions after the noun they produce or the verb they perform (`fetch_user`, `validate_payload`). **Test files exempt.** |
-| Type escape hatches | `from typing import Any`, `cast()`, and inline `Any` in production are flagged outside boundary files (`__init__.py`, `protocols.py`, `types.py`, `conftest.py`). Name the concrete shape instead. |
-| Bare except | `except:` and `except BaseException:` swallow KeyboardInterrupt/SystemExit; `except Exception:` hides bugs by catching nearly every error class. Name the specific exception(s) you intend to catch (tuple form `except (ValueError, KeyError):` is fine). **Test files and hook infrastructure exempt.** |
-| Boundary types — Any in signatures | `Any` appearing directly or nested inside a generic in a function signature (parameters, return type) or class attribute annotation is flagged. Local variable annotations are exempt. Files named `protocols.py` or `types.py` are interface-declaration surfaces and exempt. |
-| Stub implementations | Functions whose body is `pass`, `...`, or `raise NotImplementedError` in production code are flagged unless declared abstract (`@abstractmethod`) or part of a `Protocol`. Implement the function or remove it. |
-| TypedDict encode/decode pairs | Every `class FooPayload(TypedDict):` in production code must have companion `_encode_foo_payload(...)` and `_decode_foo_payload(...)` functions in the same module — boundary serialization should not leak to callers. |
-| Test-mode branching in production | Reading `TESTING`, `PYTEST_CURRENT_TEST`, `IS_TEST`, etc. from production code creates two parallel implementations. Use dependency injection so production stays single-path. **Test files and hook infrastructure exempt.** |
-| Thin wrapper files | A non-`__init__.py` module whose body is only imports (optionally with an `__all__` assignment) is a re-export indirection with no payload. Callers should import from the real module. `__init__.py` is the canonical re-export surface and is exempt. |
-| Docstring format (Google-style) | Public functions/methods (no leading underscore, not dunder, body > 3 lines, not `@property`/`@abstractmethod`) require Google-style `Args:` / `Returns:` (or `Yields:`) / `Raises:` sections matching the signature. **Test files exempt.** |
-| Docstring Args match signature | A public function whose docstring `Args:` section names a parameter the signature does not declare is flagged — a rename that left the adjacent `Args:` line stale. Only the `Args:` section is compared against the signature; `Raises:` is left alone because callee-propagated exceptions cause false positives. **Test files and hook infrastructure exempt.** |
-| Ignored must-check return | A bare-statement call to a function whose return value is its only failure signal (the curated `find_and_click`, `write_outcome` set) is flagged — the discarded boolean lets the caller move on silently after a failure. Assign the return and check it. Assigned (`clicked = …`) and branched-on (`if …:`) calls are exempt. Attribute calls are matched by their terminal method name alone (the receiver type is not resolved), so an unrelated `obj.write_outcome()` or `widget.find_and_click()` whose method name collides with a curated name is also flagged. **Test files exempt.** |
-
-### Where UPPER_SNAKE is allowed
-
-The "Constants location" rule is enforced at Write time. The hook exempts these path families where UPPER_SNAKE identifiers are either the canonical home or the native convention rather than misplaced scalar constants:
-
-| Path pattern | Why it is exempt |
-|---|---|
-| `config/*` | Canonical home for scalar constants. |
-| `/migrations/` (Django migrations) | Migration files are self-contained by framework convention; their UPPER_SNAKE identifiers are operation names, not misplaced configuration. |
-| `/workflow/`, `_tab.py`, `/states.py`, `/modules.py` (path normalized to forward slashes, matched as substrings) | Workflow state and module registries declare `StateDefinition` / `WorkflowModule` instances as module-level singletons using UPPER_SNAKE names. These are registry entries, not constants to hoist. |
-| Test files (`test_*.py`, `*_test.py`, `*.spec.*`, `conftest.py`, paths under `/tests/`) | Test files may define local constants without using `config/`. |
-
-Any production file outside these families that defines an UPPER_SNAKE at module scope is still flagged and must be moved to `config/`.
-
-> See also: [File-global constants use-count rule](../rules/file-global-constants.md) for the use-count requirement on file-global constants outside `config/`.
-
----
-
-## 3. REUSE CONSTANTS (DRY CONFIG)
-
-**Before writing ANY constant:**
+`code_rules_enforcer.py` blocks each of these at Write/Edit and explains the specific violation when it fires; exact patterns and exemption lists live in the hook:
 
-```bash
-# Find config files
-# Search your project for existing config files before creating new ones
+no new comments · imports at top · logging format args (`log_*("...", arg)`) · no magic values in production bodies (0, 1, -1 exempt) · UPPER_SNAKE constants only in `config/` (exempt: `config/*`, `/migrations/`, workflow registries `/workflow/` + `_tab.py` + `/states.py` + `/modules.py`, test files) · no hardcoded user home paths · guarded `sys.path.insert` · no unused module-level imports · banned identifiers (`ctx`, `cfg`, `msg`, `btn`, `idx`, `cnt`, `tmp`, `elem`, `val`) · banned function prefixes (`handle_`, `process_`, `manage_`, `do_`) · no type escape hatches (`Any` import, `cast()`, inline `Any`) outside boundary files · no bare/broad `except` · no `Any` in signatures or class attributes · no stub bodies (`pass`/`...`/`raise NotImplementedError`) outside abstract/Protocol · TypedDict `_encode_*`/`_decode_*` companions in the same module · no test-mode branching in production (use dependency injection) · no thin wrapper modules · Google-style docstrings on public functions with `Args:` matching the signature · boolean names prefixed `is_`/`has_`/`should_`/`can_`/`was_`/`did_` (assignments AND bool-typed parameters) · must-check returns (`find_and_click`, `write_outcome`) assigned and checked
 
-# Search for value
-grep -r "VALUE" config/
-```
-
-**Decision tree:**
-1. Search exact value → Found? → IMPORT IT
-2. Search semantic match → Found? → USE EXISTING NAME
-3. Config file exists? → ADD TO EXISTING
-4. Create new (rare)
+Test files are exempt from most checks. See also the file-global constants use-count rule: [`rules/file-global-constants.md`](../rules/file-global-constants.md).
 
 ---
 
-## 4. CONFIG LOCATIONS
+## 3. REUSE CONSTANTS / 4. CONFIG LOCATIONS
 
-| Constant Type | Location |
-|---------------|----------|
-| Timeouts, delays, retries | `config/timing.py` |
-| Ports, URLs, thresholds | `config/constants.py` |
-| CSS selectors | `config/selectors.py` |
+Before writing ANY constant: search `config/` for the exact value → semantic match → add to the existing config file → create new (rare). Locations: timeouts/delays/retries → `config/timing.py`; ports/URLs/thresholds → `config/constants.py`; CSS selectors → `config/selectors.py`.
 
 ---
 
 ## 5. NO ABBREVIATIONS
 
-Full words only. No mental translation.
-
-| Bad | Good |
-|-----|------|
-| `ctx`, `cfg`, `msg` | `context`, `configuration`, `message` |
-| `btn`, `idx`, `cnt` | `button`, `index`, `count` |
-| `tmp`, `elem`, `val` | `temporary_value`, `element`, `value` |
-
-**Exception:** `i`, `j`, `k` in loops; `e` for exception.
-
-**Extended naming rules** :
-- Loop vars: `each_order`, `each_user` (prefix `each_`)
-- Booleans: `is_valid`, `has_permission`, `should_retry`, `was_clicked`, `did_succeed` (prefix `is_`/`has_`/`should_`/`can_`/`was_`/`did_`). The hook covers both boolean assignments and boolean-typed function parameters (a parameter annotated `bool` or defaulting to a boolean literal); `self`/`cls` and single-character names are exempt.
-- Collections: `all_orders`, `all_users` (prefix `all_`)
-- Maps: `price_by_product`, `user_by_id` (pattern `X_by_Y`)
-- Preposition params: `from_path=`, `to=`, `into=`
-- **Banned names:** `result`, `data`, `output`, `response`, `value`, `item`, `temp`
-- **Banned prefixes:** `handle`, `process`, `manage`, `do`
+Full words only (`context`, not `ctx`). Exceptions: `i`/`j`/`k` in loops, `e` for exception. Naming patterns: loop vars `each_*`; booleans `is_/has_/should_/can_/was_/did_`; collections `all_*`; maps `X_by_Y`; preposition params (`from_path=`, `to=`, `into=`). Banned names: `result`, `data`, `output`, `response`, `value`, `item`, `temp`. Banned prefixes: `handle`, `process`, `manage`, `do`.
 
 ---
 
 ## 6. COMPLETE TYPE HINTS
 
-```python
-def function_name(
-    parameter: str,
-    optional: Optional[str] = None,
-) -> ReturnType:
-```
-
-- ALL parameters typed
-- ALL returns typed
-- No `Any` type
-- No `# type: ignore`
-
-*(Also enforced by mypy_validator.py hook)*
-
----
+ALL parameters typed, ALL returns typed. No `Any`, no `# type: ignore` (also enforced by the mypy_validator.py hook).
 
 ## 6.5 FILE LENGTH GUIDANCE
 
-File length is a **smell signal, not a hard threshold**. Long files often hide multiple responsibilities, but legitimately long files exist (migrations, generated code, registries, fixtures). The hook surfaces advisories instead of blocking.
-
-**Two advisory thresholds (non-blocking, stderr only):**
-
-| Threshold | Source basis | Hook behavior |
-|-----------|--------------|---------------|
-| `>= 400` lines | Robert C. Martin, *Clean Code* (2008), Ch. 5 "Formatting" — small files preferred; Martin Fowler, *Refactoring* — "Large Class" code smell | Soft advisory: "consider splitting" |
-| `>= 1000` lines | pylint default `max-module-lines=1000`; SonarQube rule S104 default `1000` | Strong nudge: "exceeds widely-used static-analysis defaults" |
-
-**What we deliberately reject:**
-
-- **Hard numeric blocks** — Google's Python Style Guide imposes no file-length cap (only a ~40-line function review hint at https://google.github.io/styleguide/pyguide.html). A blocking rule produces false positives on legitimate cases.
-- **A single magic number** — Different sources land at 200 (*Clean Code* preference), 750 (some SonarQube language profiles), or 1000 (pylint, Sonar Java). No source justifies a single universal cap.
-
-**When to actually split:**
-
-The size signal matters *because* of what it usually indicates: multiple responsibilities (Single Responsibility Principle — Robert C. Martin, *Agile Software Development*, 2002), poor cohesion (Steve McConnell, *Code Complete 2e*, 2004, Ch. 5–6), or the "Large Class" / "Long Function" smells (Fowler). Use the readability rubric (`~/.claude/skills/readability-review/SKILL.md`) when an advisory fires — split based on cohesion, not line count.
+Advisory only, never blocking: soft advisory at >= 400 lines, strong nudge at >= 1000 (pylint / SonarQube defaults). Split on cohesion (SRP, "Large Class" smell), not line count — run the readability rubric when an advisory fires.
 
 ---
 
 ## 7. RIGHT-SIZED ENGINEERING
 
 **Simple > Clever. Functions > Classes. Concrete > Abstract.**
-
-Never: ABC for single impl, DI frameworks, factory for single type
-Always: Functions when no state, concrete classes, simple imports
-
----
+Never: ABC for single impl, DI frameworks, factory for single type. Always: functions when no state, concrete classes, simple imports.
 
 ## 7.5 SOLID PRINCIPLES
 
-**Apply where two or more concrete implementations already share a contract. For code with a single concretion, §7 (Right-Sized Engineering) takes precedence: use concrete classes, functions when no state, and direct imports.**
-
-Reference: Robert C. Martin, *Agile Software Development: Principles, Patterns, and Practices* (2002), Ch. 8–12.
-
-| Letter | Principle | What it means here |
-|--------|-----------|--------------------|
-| **S** | Single Responsibility Principle | A class, function, or module has one reason to change. One unit = one axis of variation. Ties to §6.5 (file length as smell signal) and Fowler's "Large Class" / "Long Function" smells. |
-| **O** | Open/Closed Principle | Extend behavior by adding new code. Favor a new branch/handler/subclass over editing the same switch in five places. |
-| **L** | Liskov Substitution Principle | A subtype must be usable anywhere its parent type is expected without surprising the caller. If a subclass override breaks caller assumptions, flatten the hierarchy or prefer composition. |
-| **I** | Interface Segregation Principle | Each client depends on exactly the methods it calls. Split one fat interface into several role-specific ones so each caller imports only the role it needs. |
-| **D** | Dependency Inversion Principle | When two or more concretions exist or are imminent, depend on the shared abstraction. With exactly one concretion, import the concrete type directly (see §7). |
-
-### Reconciling SOLID with Right-Sized Engineering (§7)
-
-SOLID was written for OO codebases where most abstract types have two or more concrete subclasses. In this codebase:
-
-- **SRP always applies.** Functions, classes, and modules must have one reason to change regardless of paradigm. This is the only SOLID letter that applies immediately, without waiting for a second implementation.
-- **OCP, LSP, ISP, DIP apply where two or more concrete implementations already share a contract.** A single concrete class satisfies SOLID by default. Introduce interfaces, ABCs, or DI containers only when the second concretion lands.
-- **For code with fewer than two concretions, §7 wins:** concrete classes, functions when no state, direct imports. Refactor toward OCP/DIP at the commit that introduces the second concrete implementation (YAGNI).
-
-### Signals that SOLID is being misapplied
-
-- Creating an interface or ABC with exactly one implementation (violates §7 DIP guard)
-- Splitting a cohesive 80-line class with one reason to change into four 20-line classes because "SRP" — SRP counts distinct change reasons; size is a separate signal tracked in §6.5
-- Abstract factories for types that have exactly one concrete product
-- Dependency-injection containers where every injected type has exactly one concrete implementation across production and tests
-
-### When SOLID adds value
-
-- Two or more concrete implementations already exist → DIP and ISP earn their keep
-- A class shows multiple unrelated change reasons in git history → SRP split is justified
-- Subclass overrides break caller assumptions → LSP violation; fix or flatten the hierarchy
-- Editing the same `if`/`switch` block every time a new case is added → OCP refactor is justified
+**SRP always applies** — one reason to change per function/class/module. **OCP, LSP, ISP, DIP apply only where two or more concrete implementations already share a contract**; with a single concretion §7 wins (concrete classes, direct imports, YAGNI — introduce the abstraction at the commit that adds the second concretion). Misapplication signals: interface/ABC with exactly one implementation, SRP-splitting a cohesive class by size alone, abstract factories for one product, DI containers where every injected type has one concretion.
 
 ---
 
 ## 8. TDD PROCESS
 
-1. **RED** - Failing test first
-2. **GREEN** - Minimum code to pass
-3. **REFACTOR** - Only if valuable
-
----
+1. **RED** — failing test first. 2. **GREEN** — minimum code to pass. 3. **REFACTOR** — only if valuable.
 
 ## 9. SELF-CONTAINED COMPONENTS
 
-Components own their complete feature. Parents just render `<Child />`.
-
-Child handles: state, modals, overlays, toasts
-Parent knows: nothing about child's internals
-
----
+Components own their complete feature (state, modals, overlays, toasts). Parents just render `<Child />`.
 
 ## 9.5 NO THIN WRAPPER MODULES
 
-A non-`__init__.py` module whose body is only imports (optionally with an `__all__` assignment) is a thin wrapper. Callers should import from the real module. The wrapper adds no payload — only an indirection layer that obscures where things live.
-
-`__init__.py` is the canonical re-export surface and is exempt; package surface aggregation is its job.
-
----
+A non-`__init__.py` module whose body is only imports (optionally `__all__`) is indirection without payload — callers import the real module. `__init__.py` is the canonical re-export surface and is exempt.
 
 ## 9.6 NO BACKWARDS-COMPATIBILITY SHIMS
 
-Removed code is removed. Do not leave behind:
-
-- Renamed functions that re-export the old name with a `# deprecated` comment
-- `_old_*` aliases pointing to the new implementation
-- Wrapper modules whose only purpose is to keep an old import path alive
-- `// removed in vX` comment markers next to deleted blocks
-
-When a symbol moves or its signature changes, update the call sites in the same commit. The git log records what changed; the codebase records what exists now.
-
-> **See also:** [`skills/code/SKILL.md`](../skills/code/SKILL.md) §5 ("No fallback paths, no back-compat shims, no legacy code") states the same principle as a session-start prompt directive. This section is the authoritative wording; the skill amplifies it for `/code` sessions.
-
----
+Removed code is removed: no renamed re-export aliases, no `_old_*` aliases, no keep-alive wrapper modules, no tombstone comment markers. When a symbol's name or signature changes, update the call sites in the same commit. Git history records change; the codebase records what exists.
 
 ## 9.7 NO FALLBACK / BEST-EFFORT WRAPPERS
 
-Do not wrap a call in `try/except` that swallows the failure and returns a default unless the caller has explicitly opted in to that behavior at the boundary.
-
-```python
-# BAD — silently hides every failure mode
-def fetch_user(user_id: int) -> User | None:
-    try:
-        return _registry[user_id]
-    except Exception:
-        return None
-```
-
-```python
-# GOOD — names the specific failure and propagates the rest
-def fetch_user(user_id: int) -> User | None:
-    try:
-        return _registry[user_id]
-    except KeyError:
-        return None
-```
-
-Fallback values mask programming errors (KeyError vs RuntimeError vs AttributeError all collapse to "None"), making debugging impossible. Production code names the specific failure mode it intends to handle.
-
-> **See also:** [`skills/code/SKILL.md`](../skills/code/SKILL.md) §2 ("No `try`/`except` in core logic that recovers, softens, or best-efforts a failure") states the same principle as a session-start prompt directive. The hook check `check_bare_except` enforces the narrowest case (bare/`Exception`/`BaseException` handlers); this section + the `code` skill cover the broader "any swallowing handler" intent.
-
----
+Never swallow a failure into a default unless the caller explicitly opted in at the boundary. Name the specific exception (`except KeyError:`) and propagate the rest — collapsing every error class to `None` masks programming errors and makes debugging impossible.
 
 ## 9.8 REMOVE CODE YOU ORPHAN (Dead Code Elimination)
 
-When an edit deletes or rewrites code, it must also remove everything that edit makes dead. The change is not complete while orphans remain.
-
-After deleting or rewriting code, trace what it referenced and remove whatever is unreachable as a result:
-
-- **Variables** with no remaining readers after the change
-- **Functions / methods** with no remaining call sites
-- **Parameters** that no caller passes
-- **Branches** made unreachable (dead `if`/`else`, conditions that are always true or always false)
-- **Imports** left unused (also caught by the unused-import hook)
-- **Helper files** whose only consumer you just deleted
-
-**Confirm the orphan is truly unreferenced first.** "No remaining call sites" means none *anywhere in the codebase*, not just in the file you edited. Before removing a function, method, class, or module-level name, run Serena's `find_referencing_symbols` on it: the language server resolves call sites, `import` statements, and re-exports across files far more reliably and cheaply than a text sweep. Back it with a plain text search for string-based dynamic lookups (`getattr`, entry-point names) that the language server cannot see. A reference is not proof of life — the referrer can be dead too. The symbol is live only when some chain of references reaches a live entry point: a CLI command, route, public API, test, or any caller outside the code you are removing. Trace the referrers upward. If every chain dead-ends in code that is itself unreferenced, the whole cluster is dead — remove it together in the same commit (§9.6). If any chain reaches a live entry point, the symbol is in use; leave it. Deleting something still reachable breaks its importers; treating a self-referential dead cluster as alive leaves litter.
-
-**When liveness is uncertain, ask — never guess.** A tool cannot always tell what is live: a chain may leave the repository (a public API, plugin hook, or module other projects import), or run through dynamic or reflective dispatch that no search resolves. If you cannot conclusively prove a symbol is unreachable, do not delete it. Surface the specific ambiguity to the user through AskUserQuestion and let them decide. Removing live production code is never an acceptable risk — when in doubt, keep it and ask.
-
-This is the inverse of comment preservation: existing **comments** are sacred and never removed, but dead **code** is removed in the same edit that orphans it. A function left with no callers is not "preserved" — it is litter.
-
-> **See also:** §9.6 (a renamed alias is dead code by another name), the `file_global_constants_use_count` rule (zero references → delete), and the unused-import hook check — each enforces a specific slice of this principle automatically.
-
-> **Standard terms (shorthand for this section):** the mechanical part is *dead code elimination* (compilers; Aho et al., *Compilers: Principles, Techniques, and Tools*) and *tree-shaking* (bundlers like Rollup/Webpack) — retain only what is reachable from a live entry point. The ask-when-uncertain overlay guards against the *Lava Flow* anti-pattern — dead code kept because removing it feels risky (Brown et al., *AntiPatterns*, 1998). Compare Fowler's "Remove Dead Code" refactoring (*Refactoring*, 2nd ed., 2018). Direct source links: [`references/dead-code-elimination.md`](references/dead-code-elimination.md).
-
----
+An edit that deletes or rewrites code also removes everything it makes dead: unread variables, uncalled functions, unpassed parameters, dead branches, unused imports, helper files whose only consumer that edit deleted. Prove unreachability first: Serena `find_referencing_symbols` plus a text search for dynamic lookups (`getattr`, entry-point names). A symbol is live only when a reference chain reaches a live entry point (CLI command, route, public API, test); a self-referential dead cluster is removed together in the same commit. **When liveness is uncertain (public API, plugin hook, reflective dispatch), do NOT delete — surface the ambiguity via AskUserQuestion.** Source links: [`references/dead-code-elimination.md`](references/dead-code-elimination.md).
 
 ## 10. NO REDUNDANT DATA FETCHES
 
-If you already have data, don't fetch again.
-
-```typescript
-// BAD
-const profile = await getProfile();
-const localProfile = await db.profile.first(); // same data!
-
-// GOOD
-const profile = await db.profile.first();
-// ... use profile throughout ...
-```
+If you already have the data, don't fetch it again.
 
 ---
 
 ## 11. ENFORCEMENT SURFACES
 
-Rules in this document are enforced through three distinct surfaces, each with different latency and reach. Knowing which surface owns a rule tells you what happens when you violate it.
-
-| Surface | What it catches | When it runs | Failure mode |
-|---------|-----------------|--------------|--------------|
-| **⚡ Hook** | Pattern-matchable violations: comments, magic values, banned identifiers, bare except, boundary `Any`, thin wrappers, docstring shape, etc. | PreToolUse on Write/Edit (and PostToolUse advisories) | Blocks the write — Claude must fix and retry |
-| **🤖 Prompt** | Judgment-driven principles: SRP, Right-Sized Engineering, KISS, conservative-action, BDD discovery; strict-mode standards via the `/code` skill (no `Any`/`cast`, immutable TypedDicts, DI hooks, 100% branch coverage, no fallback `try/except`) | Read into the model context at session start (CLAUDE.md, rules/*.md, skill prepends) | Influences Claude's decisions; no automatic block |
-| **👥 Audit rubric** | Cross-file architectural concerns: SOLID misapplication, abstraction leaks, multi-file coupling | Run on demand via `/check`, `/readability-review`, agent-driven audits | Surfaces in audit output; humans decide whether to act |
-
-### Prompt-enforced rules (no hook coverage)
-
-These principles cannot be reduced to a regex or AST visitor. They live in user-private `~/.claude/rules/` and `~/.claude/CLAUDE.md`, and are read into context every session:
-
-- **Right-Sized Engineering** — concrete classes for single concretions, functions when no state, no DI frameworks for solo-scale code
-- **SRP / SOLID misapplication signals** — see §7.5
-- **conservative-action** — when intent is ambiguous, ask before acting
-- **explore-thoroughly** — investigate before committing to an approach
-- **agent-spawn-protocol** — verify context before delegating to a subagent
-- **`code` skill ([`skills/code/SKILL.md`](../skills/code/SKILL.md))** — invoked via `/code`, prepends strict-mode standards for the entire session: no `Any`/`cast()`/`# type: ignore`, immutable TypedDicts with manual `_encode_*`/`_decode_*` and `require_*` validation, per-module `_test_hooks.py` for DI, 100% statement + branch coverage, zero mocks. Several criteria overlap with §9.6/§9.7 and the ⚡ B-series checks; the skill is the canonical entry point when the user explicitly opts into strict mode for an implementation task.
-
-### Audit-rubric reference
-
-For multi-file architectural reviews see [`packages/claude-dev-env/audit-rubrics/`](../audit-rubrics/). Categories A–N are maintained as agent rubrics. Category J (CODE_RULES.md compliance) mirrors the ⚡ hook-enforced rules as an audit-side rubric; the other categories stay agent rubrics because they rest on multi-file reasoning beyond a single-file hook's reach.
-
----
-
-## 12. DEFERRED RULES (P1 — TRACKED, NOT ENFORCED)
-
-The following rules are documented in `~/.claude/rules/` and applied by Claude through prompt context, but have no hook coverage in `code_rules_enforcer.py`. Promotion to ⚡ blocking enforcement is on the backlog and will land as separate hardening commits.
-
-| Rule | Source | Promotion path |
-|------|--------|----------------|
-| Context7 before web search for library/SDK questions | [`rules/context7.md`](../rules/context7.md) | New PreToolUse hook on WebSearch when query mentions a library name |
-| Verify-before-asking checklist | [`rules/verify-before-asking.md`](../rules/verify-before-asking.md) | Stop hook scanning AskUserQuestion calls for "where is", "what file", etc. |
-| BDD naming (`should_…` / `describe…it…`) | [`rules/bdd.md`](../rules/bdd.md) | `code_rules_enforcer.py::check_test_naming` (new) — flag test functions starting with `test_` lacking corresponding `should_…` form |
-| `gh` pagination requires `--paginate --slurp` plus external `jq` | [`rules/gh-paginate.md`](../rules/gh-paginate.md) | PreToolUse Bash hook matching `gh api .*/(reviews\|comments)` without `--paginate --slurp` |
-| Self-contained documentation (no "as discussed", "Option A", session refs) | [`rules/self-contained-docs.md`](../rules/self-contained-docs.md) | PostToolUse Write hook scanning new `.md` content for conversational refs |
-| Temp file cleanup at end of task | [`rules/cleanup-temp-files.md`](../rules/cleanup-temp-files.md) | Stop hook scanning for files Claude created and did not delete |
-| No credentials committed to git | [`rules/git-workflow.md`](../rules/git-workflow.md) | PreToolUse Bash hook on `git commit` scanning staged diff for high-entropy strings, `.env` patterns, and known credential file extensions |
-| Per-module DI hooks (`_test_hooks.py` sibling) instead of `if TESTING:` branching | [`skills/code/SKILL.md`](../skills/code/SKILL.md) §4 | New `check_test_hooks_sibling()` — when a module imports a side-effect dependency and a test exists, require a `<module>_test_hooks.py` sibling exposing the injection points |
-| 100% statement + branch coverage with zero mocks | [`skills/code/SKILL.md`](../skills/code/SKILL.md) §3 | CI check (not write-time) — `pytest --cov-branch --cov-fail-under=100` on touched packages; covers only what the diff added |
-| `TypedDict` `_decode_*` calls `require_*` on every field | [`skills/code/SKILL.md`](../skills/code/SKILL.md) §6 | Extend `check_typed_dict_encode_decode` (B2) — when the decoder is present, AST-verify every TypedDict field appears as a `require_*` call before the return |
-| `Protocol` signatures match the real implementation exactly | [`skills/code/SKILL.md`](../skills/code/SKILL.md) Gotchas | mypy `--strict` over the protocol module catches this; promotion = add `[tool.mypy] strict = true` per-module override in `pyproject.toml` for files declaring `Protocol` subclasses |
-
----
-
-## QUICK CHECKLIST
-
-```
-Before ANY code:
-[ ] Searched existing configs?
-[ ] Importing from centralized config?
-
-Hook will enforce:
-[⚡] No NEW comments (existing comments NEVER removed)
-[⚡] No magic values
-[⚡] Imports at top
-[⚡] Logging format args
-[ ] File length reasonable (advisory at 400, strong nudge at 1000 — see §6.5)
-[⚡] Constants in config/
-[⚡] No banned identifiers (ctx, cfg, msg, btn, idx, cnt, tmp, elem, val)
-[⚡] No banned function prefixes (handle_, process_, manage_, do_)
-[⚡] No type escape hatches (Any imports, cast(), inline Any)
-[⚡] No bare except / except Exception / except BaseException
-[⚡] No Any in function signatures or class attributes (boundary types)
-[⚡] No stub bodies (pass / ... / raise NotImplementedError) outside abstract methods
-[⚡] TypedDict has companion _encode_*/_decode_* in same module
-[⚡] No test-mode branching in production (TESTING / PYTEST_CURRENT_TEST)
-[⚡] No thin wrapper modules (imports only, optionally with __all__, outside __init__.py)
-[⚡] Public functions have Google-style Args:/Returns:/Raises: when warranted
-[⚡] Docstring Args: names match the signature (a stale renamed param is flagged)
-[⚡] Boolean names prefixed is_/has_/should_/can_/was_/did_ (assignments AND bool-typed parameters)
-[⚡] No discarded must-check return (assign and check find_and_click/write_outcome outcomes)
-
-Manual check:
-[ ] No abbreviations?
-[ ] Complete type hints?
-[ ] Self-contained components?
-[ ] SRP holds (one reason to change per function/class/module)?
-[ ] OCP/LSP/ISP/DIP only applied where abstractions already earn their keep (see §7.5)?
-[ ] No backwards-compatibility shims (§9.6)?
-[ ] No fallback/best-effort wrappers (§9.7)?
-[ ] No code orphaned by an edit (§9.8 — dead vars, uncalled functions, unused imports, dead branches)?
-[ ] Readability: /check
-```
+⚡ **Hooks** block pattern-matchable violations at Write/Edit time. 🤖 **Prompt context** carries judgment principles (SRP, Right-Sized Engineering, conservative-action, BDD discovery; the `/code` skill prepends strict mode for a session: no `Any`/`cast()`, immutable TypedDicts with `_encode_*`/`_decode_*` + `require_*` validation, per-module `_test_hooks.py` DI, 100% statement + branch coverage, zero mocks). 👥 **Audit rubrics** (`/check`, `packages/claude-dev-env/audit-rubrics/` categories A–P) cover cross-file architectural concerns. Rules with documented-but-pending hook coverage live in `~/.claude/rules/*.md` and `skills/code/SKILL.md`; each names its own promotion path.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "claude-dev-env",
-    "version": "1.50.3",
+    "version": "1.51.0",
     "description": "Claude Code development standards — rules, hooks, agents, commands, and skills",
     "type": "module",
     "bin": {

package/rules/ask-user-question-required.md

@@ -1,44 +1,5 @@
 # AskUserQuestion Required
 
-**When this applies:** Any time you would ask the user a question during discovery, scoping, or implementation planning — after the `verify-before-asking` decision checklist confirms the question genuinely belongs to the user.
+Route every user-directed question through the `AskUserQuestion` tool — never a plain-text question in a response's final paragraph. Structure: concise `question`, `header` of 12 chars or fewer, 2-4 options (the UI adds the "Other" fallback), `multiSelect` only when choices genuinely combine.
 
-## Rule
-
-Route every user-directed question through the `AskUserQuestion` tool. Embedded plain-text questions in the final paragraph of an assistant message are blocked by a Stop hook, and the response must be re-output with the ask moved into an `AskUserQuestion` tool call.
-
-## Detection Criteria
-
-The `question_to_user_enforcer` Stop hook inspects the last non-empty paragraph of the response after stripping fenced code blocks, inline code (backticks), and blockquoted lines (`> …`). The response is blocked when either signal is present:
-
-- The final paragraph's last sentence ends with a question mark.
-- The final paragraph contains any of these preamble phrases (case-insensitive, word-boundary matched): `would you like`, `should I`, `do you want`, `which would you prefer`, `let me know if`, `let me know which`, `let me know whether`, `please confirm`, `please let me know`, `want me to`.
-
-## Acceptable Plain-Text Question Patterns
-
-These remain allowed and do not trigger the hook:
-
-- **Rhetorical questions answered in the same paragraph.** `"What happens if the queue is empty? The handler short-circuits cleanly."` The question frames its own answer; the reader never has to respond.
-- **Questions inside code, diffs, or documentation excerpts.** Code fences, inline backticks, and `>` blockquotes are stripped before detection. Quoting a GitHub issue title, a user's prior message, or a log line inside a blockquote is fine.
-- **Middle-paragraph questions when the closing paragraph is declarative.** Only the final paragraph is scanned.
-
-## AskUserQuestion Structure
-
-When a question is genuinely for the user, call the tool with:
-
-- A concise `question` string stating what is needed.
-- A `header` of twelve characters or fewer summarizing the decision.
-- Two to four `options`, each with a short `label` the user can pick. An "Other" free-text fallback is already provided by the UI; do not add one manually.
-- `multiSelect: false` unless the user can genuinely combine choices.
-
-## Why
-
-- **Structured options reduce re-reading friction.** The user sees labeled choices directly rather than scanning prose for the ask.
-- **Transcript clarity.** Tool-use entries are easy to locate in the JSONL transcript; prose questions disappear into the response text.
-- **Reduced drift.** Claude's next turn cannot move past an unanswered structured question; prose questions can be silently bypassed.
-
-## Enforcement
-
-- Hook: `packages/claude-dev-env/hooks/blocking/question_to_user_enforcer.py`, registered on the `Stop` matcher in `packages/claude-dev-env/hooks/hooks.json`.
-- Loop prevention: the hook honors Claude Code's `stop_hook_active` flag and does not re-block on retry.
-- User-facing notice: `USER_FACING_ASKUSERQUESTION_NOTICE` in `packages/claude-dev-env/hooks/hooks_constants/messages.py`.
-- Related rule: `packages/claude-dev-env/rules/verify-before-asking.md` gates whether the question belongs to the user in the first place.
+The `question_to_user_enforcer` Stop hook blocks a response whose final paragraph (after stripping code fences, inline code, and blockquotes) ends in a question mark or contains ask-phrases ("would you like", "should I", "let me know if", ...). Rhetorical questions answered in the same paragraph, and questions inside code or blockquotes, pass. `verify-before-asking` gates whether the question belongs to the user at all.