claude-dev-env 2.29.0 → 2.30.1

package/.agents/agents/pr-description-writer.md

@@ -1,19 +1,34 @@
 ---
 name: pr-description-writer
-description: "Optional agent that drafts factual pull request descriptions and comments from the current diff and validates each statement against the master review guides."
+description: "Optional agent that writes factual pull request titles, descriptions, and comments in plain illustrative language from the current diff."
 tools: Read,Grep,Glob,Bash
 ---
 
 # PR Description Writer
 
-Write the body from the current pull request diff and task. Resolve the active managed root and active agents home before reading guides: `~/.claude` is the default root, `CLAUDE_CONFIG_DIR` selects another root, and `--target DIR` takes precedence; the default `.claude` root uses sibling `~/.agents`, while another root uses sibling `<root-name>.agents`. Use `<agents-home>/skills/pr-title-description/SKILL.md` (source fallback: `packages/claude-dev-env/.agents/skills/pr-title-description/SKILL.md`) for required content and shape. Use the current review findings and task guidance for a review comment. Do not assume `~/.claude` or `~/.agents` for a named profile or explicit target.
+Write from the current pull request diff and task. Resolve the active managed root and active agents home before reading guides: `~/.claude` is the default root, `CLAUDE_CONFIG_DIR` selects another root, and `--target DIR` takes precedence; the default `.claude` root uses sibling `~/.agents`, while another root uses sibling `<root-name>.agents`. Use `<agents-home>/skills/pr-title-description/SKILL.md` (source fallback: `packages/claude-dev-env/.agents/skills/pr-title-description/SKILL.md`) for required content and shape. Use the current review findings and task guidance for a review comment. Do not assume `~/.claude` or `~/.agents` for a named profile or explicit target.
+
+## Voice
+
+Explain the change so a smart reader who knows nothing about the code can picture it on the first read.
+
+- Start with a concrete scene or action.
+- Prefer a tiny Before / After story when the change is about how something is found, asked for, checked, saved, retried, or stopped.
+- Use small words and picture words.
+- Replace jargon with the action it represents. When one technical term matters, explain it immediately in plain words.
+- Keep the main behavior in `What this adds`, the reason in `Why`, and proof in `Verification`.
+- Keep titles concrete. Say what someone gives it, what happens, or what comes back.
+
+For a concrete voice sample only when needed, read `reference/pr-description-illustrative-voice.md` beside this agent. For a concrete verification sample only when needed, read `reference/pr-description-verification.md`. These samples guide the shape and voice; they are not content to copy into unrelated pull requests.
 
 ## Draft the body
 
 1. Inspect the cumulative diff, the current pull request body, and the validation results.
-2. State the behavior change, its scope, and the validation that ran.
-3. Preserve accurate issue links and curated sections from the current body.
-4. Use headings when they help a reviewer scan the change.
+2. Find the main behavior a user, caller, operator, or reviewer can see.
+3. Write that behavior first in plain illustrative language.
+4. Preserve accurate issue links and curated sections from the current body when they remain useful.
+5. Use headings when they help a reviewer scan the change.
+6. In `Verification`, lead with what a person can open, see, click, compare, or try for themselves. Put test results in one short supporting line when useful.
 
 ## Publish through GitHub CLI
 
@@ -21,4 +36,4 @@ Place markdown in a BOM-free temporary file and pass its path with `--body-file`
 
 ## Check the draft
 
-Confirm every statement matches the diff and current pull request state. Return the final markdown and the file path ready for publication.
+Confirm every statement matches the diff and current pull request state. Confirm the title and body stay clear without requiring the reader to decode repository jargon. Confirm `Verification` gives the reviewer a visible check they can perform themselves whenever the change has one. Return the final markdown and the file path ready for publication.

package/.agents/agents/reference/README.md

@@ -0,0 +1,6 @@
+# PR writer references
+
+These files are optional examples for `pr-description-writer.md`.
+
+- `pr-description-illustrative-voice.md` — plain, picture-first title and description examples.
+- `pr-description-verification.md` — human-checkable verification examples.

package/.agents/agents/reference/pr-description-illustrative-voice.md

@@ -0,0 +1,45 @@
+# PR description illustrative voice
+
+Use this only when the PR writer needs a concrete voice sample.
+
+## Core pattern
+
+Start with something a person can picture.
+
+Before: show the old action in a tiny scene.
+
+After: show the new action in a tiny scene.
+
+Keep machine words out when a plain action works. If one technical term matters, explain it in the same breath with a simple picture.
+
+## Sample 1 — call the right helper directly
+
+The theme package has a phone icon somewhere. We need to find it.
+
+Before: yell, “anyone know how to find icons?” and wait for a hand.
+
+After: call the finder by its name tag: “icon finder, go.”
+
+That is all the operation name is here — the finder’s name tag.
+
+## Sample 2 — ask for a deeper review
+
+You start the review loop. It looks at the code, then looks again, until it has nothing new to say.
+
+Before: each look could be a quick glance.
+
+After: each look uses the deepest review setting the model has.
+
+The person running the loop asked for a full look, so every pass gets a full look.
+
+## Writing rules
+
+- Few words. Small words. Clear on first read.
+- Lead with the thing someone can see or do.
+- Prefer Before / After when the change is about how something is asked, found, checked, saved, retried, or stopped.
+- Use picture words: hand it, open it, find it, check it, save it, skip it, stop, call by name.
+- Prefer spoken results: “found it,” “missing,” “duplicated,” “couldn’t.”
+- Keep the main behavior in `What this adds`.
+- Keep `Why` short and concrete.
+- Put proof only in `Verification`.
+- Explain jargon immediately or replace it.

package/.agents/agents/reference/pr-description-verification.md

@@ -0,0 +1,19 @@
+# Human-checkable PR verification
+
+Use this only when the PR writer needs a concrete verification sample.
+
+Verification should lead with something a reviewer can open, see, click, compare, or try.
+
+Good:
+
+Open the generated PR description. The first paragraph should tell the story in plain words before it names any code detail. If the change has a visible result, point to the exact file, screen, output, or behavior the reviewer can inspect.
+
+Tests: focused checks pass.
+
+Weak:
+
+- Contract test passed.
+- Static analysis passed.
+- Internal schema assertion passed.
+
+Machine checks can support the claim. They should not be the whole proof when a person can inspect the result directly.

package/.agents/agents/test_pr_description_writer_style.py

@@ -0,0 +1,47 @@
+"""Contract tests for the PR description writer voice."""
+
+from pathlib import Path
+
+
+AGENT_DIRECTORY = Path(__file__).parent
+AGENT_PATH = AGENT_DIRECTORY / "pr-description-writer.md"
+VOICE_REFERENCE_PATH = AGENT_DIRECTORY / "reference" / "pr-description-illustrative-voice.md"
+VERIFICATION_REFERENCE_PATH = AGENT_DIRECTORY / "reference" / "pr-description-verification.md"
+
+
+def test_pr_description_writer_uses_repo_owned_progressive_samples() -> None:
+    agent_text = AGENT_PATH.read_text(encoding="utf-8")
+
+    assert "reference/pr-description-illustrative-voice.md" in agent_text
+    assert "reference/pr-description-verification.md" in agent_text
+    assert "only when needed" in agent_text
+    assert "PR #2562" not in agent_text
+    assert "PR #1150" not in agent_text
+
+
+def test_voice_reference_keeps_the_plain_illustrative_shape() -> None:
+    reference_text = VOICE_REFERENCE_PATH.read_text(encoding="utf-8")
+
+    for required_text in (
+        "Before:",
+        "After:",
+        "finder’s name tag",
+        "found it",
+        "missing",
+        "duplicated",
+        "What this adds",
+        "Why",
+        "Verification",
+    ):
+        assert required_text in reference_text
+
+
+def test_verification_leads_with_a_human_visible_check() -> None:
+    agent_text = AGENT_PATH.read_text(encoding="utf-8")
+    reference_text = VERIFICATION_REFERENCE_PATH.read_text(encoding="utf-8")
+
+    for visible_action in ("open", "see", "click", "compare", "try"):
+        assert visible_action in agent_text
+        assert visible_action in reference_text
+    assert "Tests: focused checks pass." in reference_text
+    assert "Machine checks can support the claim." in reference_text

package/.agents/skills/e-simplify/SKILL.md

@@ -25,7 +25,7 @@ Triggers: `/e-simplify` on the current diff (or a PR/branch/path passed as an ar
 
 ## The process
 
-`/simplify → 4 cleanup agents in parallel → apply the fixes`
+`/simplify → up to 4 cleanup agents in parallel → apply the fixes`
 
 You are improving the quality of the changed code, not hunting for bugs. Review
 it for reuse, simplification, efficiency, and altitude issues, then fix what you
@@ -40,13 +40,25 @@ include the working-tree changes in scope — the review often runs before the
 commit. If a PR number, branch name, or file path was passed as an argument,
 review that target instead. Treat this diff as the review scope.
 
-### Phase 1 — Review (4 cleanup agents in parallel)
+**Diff-size cap.** Run `git diff --shortstat` on the same range Phase 0 used
+to get the diff, and add its insertions and deletions for the changed-line
+count. Default ceiling: 400 changed lines for one run — a tunable default the
+user may adjust. Above the ceiling, narrow the target first — a subdirectory,
+a package, or one file path — and review that narrowed target. Do not launch
+Phase 1 over a diff above the ceiling.
 
-Launch **4 independent review agents** via the Agent tool, all in a
-single message so they run concurrently. Pass each agent the diff and one of
-the four angles below. Each returns its findings with `file`, `line`, a
-one-line `summary`, and the concrete cost (what is duplicated, wasted, or
-harder to maintain).
+### Phase 1 — Review (up to 4 cleanup agents in parallel)
+
+**Lens cap.** Four lenses is the ceiling, not the floor. Default split — also
+tunable — by the `git diff --shortstat` changed-line count from Phase 0:
+under 100 changed lines, run 2 lenses (reuse and simplification); at 100
+changed lines or above, and under the diff-size cap, run all 4 lenses.
+
+Launch the review agents for the lenses in scope for this run — 2 or 4 by the
+cap above — via the Agent tool, all in a single message so they run
+concurrently. Pass each agent the diff and one of the angles below. Each
+returns its findings with `file`, `line`, a one-line `summary`, and the
+concrete cost (what is duplicated, wasted, or harder to maintain).
 
 #### Reuse
 
@@ -79,7 +91,7 @@ special cases.
 
 ### Phase 2 — Apply the fixes
 
-Wait for all four agents to complete, dedup findings that point at the same
+Wait for every launched agent to complete, dedup findings that point at the same
 line or mechanism, and fix each remaining one directly. Skip any finding whose
 fix would change intended behavior, require changes well outside the reviewed
 diff, or that you judge to be a false positive — note the skip rather than

package/_shared/pr-loop/code-rules-gate.md

@@ -1,6 +1,6 @@
 # CODE_RULES gate
 
-Pre-audit validator run before each AUDIT (and pre-commit when applicable). Wraps `validate_content` from `~/.claude/hooks/blocking/code_rules_enforcer.py`.
+Pre-audit validator run before each AUDIT (and pre-commit when applicable). Wraps `validate_content_for_full_gate` from `~/.claude/hooks/blocking/code_rules_enforcer.py`.
 
 ## Script location
 

package/_shared/pr-loop/scripts/code_rules_gate.py

@@ -63,7 +63,7 @@ except ImportError as import_error:
 subprocess = git_file_sets.subprocess
 
 resolve_claude_dev_env_root = enforcer_loading.resolve_claude_dev_env_root
-load_validate_content = enforcer_loading.load_validate_content
+load_validate_content_for_full_gate = enforcer_loading.load_validate_content_for_full_gate
 ValidateContentCallable = enforcer_loading.ValidateContentCallable
 
 resolve_merge_base = git_file_sets.resolve_merge_base
@@ -357,7 +357,7 @@ def main(all_arguments: list[str]) -> int:
     repository_root = (
         arguments.repo_root.resolve() if arguments.repo_root is not None else Path.cwd().resolve()
     )
-    validate_content = load_validate_content()
+    validate_content = load_validate_content_for_full_gate()
     if arguments.paths:
         return _run_explicit_paths_mode(validate_content, arguments, repository_root)
     if arguments.immediate:

package/_shared/pr-loop/scripts/code_rules_gate_parts/enforcer_loading.py

@@ -1,8 +1,8 @@
-"""Load the code-rules enforcer's ``validate_content`` for in-process use.
+"""Load the code-rules enforcer's ``validate_content_for_full_gate`` for in-process use.
 
-The gate runs the same ``validate_content`` the PreToolUse enforcer runs, so it
-locates the ``hooks/blocking/code_rules_enforcer.py`` module from disk, executes
-it with the hooks directory on ``sys.path``, and hands back its callable.
+The gate runs the enforcer's full-gate validation phase, so it locates the
+``hooks/blocking/code_rules_enforcer.py`` module from disk, executes it with
+the hooks directory on ``sys.path``, and hands back its callable.
 """
 
 import importlib.machinery
@@ -138,11 +138,11 @@ def _exec_enforcer_with_hooks_on_path(
         _restore_hooks_constants_modules(all_saved_modules, hooks_root_path)
 
 
-def load_validate_content() -> ValidateContentCallable:
-    """Load ``code_rules_enforcer.validate_content`` for in-process use.
+def load_validate_content_for_full_gate() -> ValidateContentCallable:
+    """Load ``code_rules_enforcer.validate_content_for_full_gate`` for in-process use.
 
     Returns:
-        The ``validate_content`` callable from the enforcer module.
+        The ``validate_content_for_full_gate`` callable from the enforcer module.
 
     Raises:
         SystemExit: When the package root or the enforcer module cannot load.
@@ -153,7 +153,7 @@ def load_validate_content() -> ValidateContentCallable:
     )
     module = importlib.util.module_from_spec(specification)
     _exec_enforcer_with_hooks_on_path(specification, module)
-    return module.validate_content
+    return module.validate_content_for_full_gate
 
 
 def _restore_hooks_constants_modules(

package/_shared/pr-loop/scripts/code_rules_gate_parts/tests/test_enforcer_loading.py

@@ -10,8 +10,8 @@ def test_resolve_claude_dev_env_root_finds_enforcer_bearing_root() -> None:
     assert (resolved_root / "hooks" / "blocking" / "code_rules_enforcer.py").is_file()
 
 
-def test_load_validate_content_returns_callable_passing_a_clean_module() -> None:
-    validate_content = enforcer_loading.load_validate_content()
+def test_load_validate_content_for_full_gate_returns_callable_passing_a_clean_module() -> None:
+    validate_content = enforcer_loading.load_validate_content_for_full_gate()
     clean_module = '"""Clean module."""\n\n\ndef ping() -> str:\n    return "pong"\n'
     issues = validate_content(clean_module, "sample.py", "")
     assert issues == []

package/_shared/pr-loop/scripts/code_rules_gate_parts/tests/test_gate_running.py

@@ -130,7 +130,7 @@ def test_gate_caller_scans_staged_content_with_commit_stage_scope(
 
     resolved_file_path = file_path.resolve()
     exit_code = gate_running.run_gate(
-        validate_content=enforcer_loading.load_validate_content(),
+        validate_content=enforcer_loading.load_validate_content_for_full_gate(),
         all_file_paths=[resolved_file_path],
         repository_root=repository_root,
         all_added_lines_by_path={resolved_file_path: {2, 3}},

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

@@ -735,7 +735,7 @@ def test_run_gate_flags_copied_sibling_when_cwd_is_outside_repo_root(
     copied_file = package_directory / "copied_helper.py"
     existing_file.write_text(_DUPLICATE_HELPER_SOURCE, encoding="utf-8")
     copied_file.write_text(_DUPLICATE_HELPER_SOURCE, encoding="utf-8")
-    validate_content = gate_module.load_validate_content()
+    validate_content = gate_module.load_validate_content_for_full_gate()
 
     monkeypatch.chdir(temporary_git_repository.parent)
     blocking_by_file, _advisory_by_file, _skipped = (
@@ -813,7 +813,7 @@ def test_duplicate_body_span_range_covers_the_definition_through_last_body_line(
     assert span == range(definition_line, last_body_line + 1)
 
 
-def test_split_violations_blocks_duplicate_body_when_span_intersects_added_lines(
+def test_split_violations_by_scope_blocks_duplicate_body_when_span_intersects_added_lines(
     tmp_path: Path,
 ) -> None:
     """A duplicate-body issue whose copied-function span overlaps the diff's added
@@ -829,7 +829,7 @@ def test_split_violations_blocks_duplicate_body_when_span_intersects_added_lines
     assert advisory == []
 
 
-def test_split_violations_advises_duplicate_body_when_span_misses_added_lines(
+def test_split_violations_by_scope_advises_duplicate_body_when_span_misses_added_lines(
     tmp_path: Path,
 ) -> None:
     """A duplicate-body issue for an untouched pre-existing copy — whose span does
@@ -1002,7 +1002,7 @@ def test_collect_partitioned_violations_advises_pre_existing_sibling_duplicate(
         _DUPLICATE_HELPER_SOURCE + "unrelated_constant = 1\n", encoding="utf-8"
     )
     unrelated_added_line = _DUPLICATE_HELPER_SOURCE.count("\n") + 1
-    validate_content = gate_module.load_validate_content()
+    validate_content = gate_module.load_validate_content_for_full_gate()
 
     resolved_copied = copied_file.resolve()
     blocking_by_file, advisory_by_file, _skipped = (
@@ -1055,7 +1055,7 @@ def test_collect_partitioned_violations_blocks_sibling_duplicate_in_added_region
     definition_line = 3
     last_body_line = 15
     all_copied_function_lines = set(range(definition_line, last_body_line + 1))
-    validate_content = gate_module.load_validate_content()
+    validate_content = gate_module.load_validate_content_for_full_gate()
 
     resolved_copied = copied_file.resolve()
     blocking_by_file, _advisory_by_file, _skipped = (
@@ -1549,10 +1549,10 @@ def test_main_blocks_when_function_body_grows_past_threshold_with_def_line_untou
     assert exit_code == 1
 
 
-def test_split_violations_blocks_function_length_when_span_intersects_added_lines() -> None:
+def test_split_violations_by_scope_blocks_function_length_when_span_intersects_added_lines() -> None:
     """A function-length issue whose declared span overlaps the diff's added
     lines is blocking — the body grew, which is exactly Finding B's intent."""
-    validate_content = gate_module.load_validate_content()
+    validate_content = gate_module.load_validate_content_for_full_gate()
     long_function = _build_function_module(
         "oversized", body_line_count=70, leading_lines=3
     )
@@ -1571,12 +1571,12 @@ def test_split_violations_blocks_function_length_when_span_intersects_added_line
     assert advisory == []
 
 
-def test_split_violations_advises_function_length_when_span_misses_added_lines() -> None:
+def test_split_violations_by_scope_advises_function_length_when_span_misses_added_lines() -> None:
     """A function-length issue for an untouched pre-existing function — whose
     declared span does not overlap any added line — is advisory, not blocking.
     This prevents the over-block regression where every pre-existing >=60-line
     function in a touched file was forced into the blocking payload."""
-    validate_content = gate_module.load_validate_content()
+    validate_content = gate_module.load_validate_content_for_full_gate()
     long_function = _build_function_module(
         "oversized", body_line_count=70, leading_lines=3
     )
@@ -1595,7 +1595,7 @@ def test_split_violations_advises_function_length_when_span_misses_added_lines()
 
 
 def _isolation_issues_for_home_probe_test() -> list[str]:
-    validate_content = gate_module.load_validate_content()
+    validate_content = gate_module.load_validate_content_for_full_gate()
     header = "from pathlib import Path\n"
     test_body = (
         "def test_reads_home() -> None:\n"
@@ -1606,7 +1606,7 @@ def _isolation_issues_for_home_probe_test() -> list[str]:
     return [each_issue for each_issue in issues if "probes" in each_issue]
 
 
-def test_split_violations_blocks_isolation_when_function_span_intersects_added_lines() -> None:
+def test_split_violations_by_scope_blocks_isolation_when_function_span_intersects_added_lines() -> None:
     """An isolation issue whose enclosing test-function span overlaps the diff's
     added lines is blocking — a signature-line change that un-isolates an
     unchanged-body probe must block, matching the enforcer's terminal path."""
@@ -1621,7 +1621,7 @@ def test_split_violations_blocks_isolation_when_function_span_intersects_added_l
     assert advisory == []
 
 
-def test_split_violations_advises_isolation_when_function_span_misses_added_lines() -> None:
+def test_split_violations_by_scope_advises_isolation_when_function_span_misses_added_lines() -> None:
     """An isolation issue for an untouched pre-existing probe — whose enclosing
     test-function span does not overlap any added line — is advisory, not
     blocking, mirroring the function-length scope contract."""
@@ -1814,7 +1814,7 @@ def test_check_wrapper_plumb_through_stays_under_function_length_threshold() ->
 
 
 def _banned_noun_parameter_issues() -> list[str]:
-    validate_content = gate_module.load_validate_content()
+    validate_content = gate_module.load_validate_content_for_full_gate()
     source = (
         "def aggregate(canned_results: int) -> int:\n"
         "    doubled = canned_results * 2\n"
@@ -1824,7 +1824,7 @@ def _banned_noun_parameter_issues() -> list[str]:
     return [each_issue for each_issue in issues if "banned noun" in each_issue]
 
 
-def test_split_violations_blocks_banned_noun_when_binding_line_is_added() -> None:
+def test_split_violations_by_scope_blocks_banned_noun_when_binding_line_is_added() -> None:
     """A banned-noun binding is blocking when its own binding line is among the
     added lines. The gate reconstructs the one-line binding span through the
     same shared extractor registry it uses for function-length and isolation,
@@ -1840,7 +1840,7 @@ def test_split_violations_blocks_banned_noun_when_binding_line_is_added() -> Non
     assert advisory == []
 
 
-def test_split_violations_advises_banned_noun_when_binding_line_untouched() -> None:
+def test_split_violations_by_scope_advises_banned_noun_when_binding_line_untouched() -> None:
     """A banned-noun binding whose own line is not among the added lines is
     advisory — editing an unrelated body line does not pull a pre-existing
     binding into scope, mirroring the companion exact-match identifier check."""

package/docs/CODE_RULES.md

@@ -109,3 +109,13 @@ If you already have the data, don't fetch it again.
 ## 11. ENFORCEMENT SURFACES
 
 ⚡ **Hooks** block pattern-matchable violations at Write/Edit time. 🤖 **Prompt context** carries judgment principles (SRP, Right-Sized Engineering, research-first action on ambiguous intent, BDD discovery, docstring-prose-matches-implementation). 👥 **Audit rubrics** (`/check`, `packages/claude-dev-env/audit-rubrics/` categories A–Q) cover cross-file architectural concerns. Rules with documented-but-pending hook coverage live in `~/.claude/rules/*.md`; each names its own promotion path. The docstring-prose standard (free-form enumerations match the body) lives in `packages/claude-dev-env/rules/docstring-prose-matches-implementation.md`, enforced via Category O6 audit. The diagram-first docstring standard (a summary line, then a `::` example or doctest, then a couple of short prose lines) lives in `packages/claude-dev-env/rules/plain-illustrative-docstrings.md`, enforced by the `check_docstring_runon_sentence` and `check_docstring_prose_wall_without_illustration` backstop hooks and Category O9 audit.
+
+## 11.5 VALIDATION-PHASE PRECEDENCE
+
+`code_rules_enforcer.py` decides what a run checks and reports along three independent axes. Each axis filters a narrower scope than the one before it; none widens what the axis before it already decided.
+
+1. **Phase selects the roster.** `EDIT_LANE_PHASE` or `FULL_GATE_PHASE` decides which checks exist in the lane at all. `validate_content_for_phase` takes `phase` keyword-only with no default, so every caller names its lane explicitly.
+2. **Target classification filters within a lane.** The hook-infrastructure patterns and the ephemeral-path check decide whether a target is validated, and with which subset. Classification narrows a lane; it never adds a check the phase already excluded.
+3. **Changed-line scope filters only the report.** `defer_scope_to_caller` and the changed-line set decide which found violations block. Scope filters findings after every check in the roster already ran; it adds or removes no check.
+
+`hooks/hooks_constants/validation_phase_constants.py` is the single source for all three axes: the phase names (`EDIT_LANE_PHASE`, `FULL_GATE_PHASE`), the full-gate-only roster (`ALL_FULL_GATE_ONLY_CHECK_NAMES`), and the hook-infrastructure edit-lane roster (`ALL_HOOK_INFRASTRUCTURE_EDIT_LANE_CHECK_NAMES`).