claude-dev-env 2.29.0 → 2.30.0

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