claude-dev-env 1.80.0 → 1.82.0

package/hooks/hooks_constants/command_dispatch_constants.py

@@ -0,0 +1,28 @@
+"""Constants for the unanchored command-dispatch meta-gate."""
+
+import re
+
+COMMAND_DISPATCH_PATH_MARKER: str = "hooks/blocking"
+
+COMMAND_DISPATCH_LITERAL_PATTERN: re.Pattern[str] = re.compile(
+    r"\b(?:gh|git|npm|npx|node|python3?|pwsh|powershell|docker|kubectl|pip|cargo"
+    r"|yarn|pnpm)\\s[+*]"
+)
+
+COMMAND_KEY_ACCESS_PATTERN: re.Pattern[str] = re.compile(
+    r"""(?:\[\s*|\.get\(\s*)["']command["']"""
+)
+
+FIRST_TOKEN_TOKENIZATION_PATTERN: re.Pattern[str] = re.compile(
+    r"shlex\.split|\.split\("
+)
+
+ALL_REGEX_START_ANCHOR_TOKENS: tuple[str, ...] = ("^", "\\A")
+
+COMMAND_DISPATCH_MESSAGE_SUFFIX: str = (
+    "matches a multi-word command as a substring - anchor the pattern to the "
+    "start of the command (^) or tokenize the first word (shlex.split) so a "
+    "command like 'echo gh pr create' is not matched"
+)
+
+MAX_COMMAND_DISPATCH_ISSUES: int = 20

package/hooks/hooks_constants/conventional_pr_title_gate_constants.py

@@ -0,0 +1,58 @@
+"""Configuration constants for the conventional_pr_title_gate PreToolUse hook."""
+
+import re
+
+ALL_GH_EXECUTABLE_BASENAMES: frozenset[str] = frozenset({"gh", "gh.exe"})
+PR_SUBCOMMAND_TOKEN: str = "pr"
+ALL_PR_TITLE_SUBCOMMAND_VERBS: frozenset[str] = frozenset({"create", "edit"})
+GH_PR_SUBCOMMAND_MINIMUM_TOKEN_COUNT: int = 3
+
+BASH_TOOL_NAME: str = "Bash"
+
+TITLE_LONG_FLAG: str = "--title"
+TITLE_SHORT_FLAG: str = "-t"
+REPO_LONG_FLAG: str = "--repo"
+REPO_SHORT_FLAG: str = "-R"
+
+WORKFLOWS_DIRECTORY_RELATIVE_PATH: str = ".github/workflows"
+ALL_WORKFLOW_FILE_GLOB_PATTERNS: tuple[str, ...] = ("*.yml", "*.yaml")
+
+ALL_SEMANTIC_TITLE_CI_MARKERS: tuple[str, ...] = (
+    "semantic-pull-request",
+    "action-semantic-pull-request",
+    "semantic_pull_request",
+)
+
+ALL_CONVENTIONAL_COMMIT_TYPES: tuple[str, ...] = (
+    "feat",
+    "fix",
+    "chore",
+    "docs",
+    "refactor",
+    "perf",
+    "ci",
+    "style",
+    "test",
+    "build",
+    "revert",
+)
+
+CONVENTIONAL_COMMIT_TITLE_PATTERN: re.Pattern[str] = re.compile(
+    r"^(?:" + "|".join(ALL_CONVENTIONAL_COMMIT_TYPES) + r")(?:\([^)]+\))?!?: .+"
+)
+
+SEMANTIC_ACTION_TYPES_INPUT_PATTERN: re.Pattern[str] = re.compile(r"^\s*types\s*:")
+
+SEMANTIC_ACTION_FLOW_TYPES_INPUT_PATTERN: re.Pattern[str] = re.compile(r"[{,]\s*types\s*:")
+
+YAML_LIST_ITEM_PREFIX: str = "- "
+
+CORRECTIVE_MESSAGE: str = (
+    "BLOCKED [conventional-pr-title]: this repository's CI validates PR titles "
+    "against Conventional Commits, and the --title value here does not match. "
+    "Required shape: type(scope)!: description, where the scope and the "
+    "breaking-change marker (!) are optional. Allowed types: "
+    f"{', '.join(ALL_CONVENTIONAL_COMMIT_TYPES)}.\n\n"
+    "Example: feat(hooks): add the conventional PR title gate\n\n"
+    "Fix the --title value and retry."
+)

package/hooks/hooks_constants/js_conventions_constants.py

@@ -0,0 +1,54 @@
+"""Configuration constants for the JavaScript convention checks in code_rules_enforcer."""
+
+import re
+
+ALL_JAVASCRIPT_BANNED_IDENTIFIERS: frozenset[str] = frozenset(
+    {
+        "result",
+        "data",
+        "output",
+        "response",
+        "value",
+        "item",
+        "temp",
+        "ctx",
+        "cfg",
+        "msg",
+        "btn",
+        "idx",
+        "cnt",
+        "tmp",
+        "elem",
+        "val",
+    }
+)
+
+_JAVASCRIPT_NEGATION_OPERAND: str = (
+    r"[A-Za-z_$][\w$]*"
+    r"(?:\s*\.\s*[A-Za-z_$][\w$]*|\s*\((?:[^()]|\([^()]*\))*\))*"
+)
+
+JAVASCRIPT_BOOLEAN_DECLARATION_PATTERN: re.Pattern[str] = re.compile(
+    r"\b(?:const|let|var)\s+(?P<name>[A-Za-z_$][\w$]*)\s*=\s*"
+    r"(?:(?:true|false)\b|!\s*" + _JAVASCRIPT_NEGATION_OPERAND + r"\s*(?:;|$))"
+)
+
+JAVASCRIPT_BOOLEAN_JSDOC_PARAMETER_PATTERN: re.Pattern[str] = re.compile(
+    r"@param\s*\{\s*boolean\s*\}\s+(?P<name>[A-Za-z_$][\w$]*)"
+)
+
+JAVASCRIPT_DECLARATION_NAME_PATTERN: re.Pattern[str] = re.compile(
+    r"\b(?:const|let|var)\s+(?P<name>[A-Za-z_$][\w$]*)\s*="
+)
+
+JAVASCRIPT_BOOLEAN_PREFIX_PATTERN: re.Pattern[str] = re.compile(
+    r"^(?:is|has|should|can|was|did)(?:[A-Z0-9_]|$)"
+)
+
+BOOLEAN_PREFIX_GUIDANCE: str = "prefix with is/has/should/can/was/did"
+
+SINGLE_CHARACTER_NAME_LENGTH: int = 1
+
+MAX_JAVASCRIPT_BOOLEAN_NAMING_ISSUES: int = 20
+
+MAX_JAVASCRIPT_BANNED_IDENTIFIER_ISSUES: int = 20

package/package.json

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

package/rules/docstring-prose-matches-implementation.md

@@ -6,7 +6,7 @@
 
 When a docstring enumerates the behaviors a body applies, the enumeration covers every behavior the body applies. A reader trusts the list to be complete: an item the code applies but the prose omits is a silent gap that misleads every future reader and reviewer.
 
-The gate validator `check_docstring_args_match_signature` covers the `Args:` section parameter names. Nine more gate validators each cover one deterministic slice of the free-form prose. `check_docstring_length_constant_superlative_vs_exact_gate` covers a length-constant module whose docstring describes an integer `*_LENGTH` constant with a superlative or range word (`the longest color string the swatch accepts`) while the only code consuming the constant compares `len(...)` against it with `==`/`!=` — an exact-length gate that rejects every other length — and never with an ordered operator; the check scans the constant module's package tree (its own directory, or the parent package when the module sits in a `config/` subdirectory), so the mismatching consumer may sit in a sibling module. `check_docstring_fallback_branch_coverage` covers a summary that scopes a fallback to a single condition (`only when`, `falls back to ... when`) while the body routes to that same fallback call from two or more distinct early-return guards. `check_class_docstring_names_public_methods` covers a class whose docstring is a single summary line while the class exposes two or more public methods whose names the summary never spells out — the drift where a one-line class summary keeps naming its first feature after the class grows a second public entry point. `check_docstring_no_consumer_claim` covers a producer docstring asserting that no consumer reads its output yet (`producer-only artifact`, `no submission-run consumer reads it yet`) — a transitional claim that drifts the moment a reader lands and contradicts any companion `SKILL.md` that documents the consumer; this is the deterministic slice of the O8 companion-doc producer/consumer drift below. `check_docstring_returns_plural_cardinality` covers a `Returns:` clause that names a dict-key prefix family with a plural noun (`the sheen stops`) while the returned dict literal holds exactly one key in that family (`sheen_mid`) — the drift where a single-key family carries a plural noun, so the prose claims a cardinality of two or more that the dict does not hold. `check_docstring_args_single_line_scope_vs_span` covers an `Args:` entry whose prose scopes a finding to a single named line (`only when its block-anchor line is among the changed lines`) while the body builds a `range(...)` span over the finding's source lines and scopes it through a span-intersection scoper — the drift where the Args entry claims a narrower single-line scope than the span-intersection body applies, so an edit touching any non-anchor line of the span still blocks. `check_docstring_cardinal_count_matches_constant_family` covers a docstring that states a cardinal count of an outcome family (`Covers the four outcome branches: ...`) and lists those members, while the module references more members of the same `UPPER_SNAKE` constant family than the count names (`OUTCOME_OFFENDER_UNREADABLE` is imported and exercised, yet the summary stops at four) — the drift where a summary keeps the old count after the code grows another branch; this gate runs on test modules as well as production modules. `check_docstring_raises_unraisable_largezipfile` covers a `Raises:` clause that names `zipfile.LargeZipFile` while the function opens its `zipfile.ZipFile` writer in a write mode (`w`/`a`/`x`) with `allowZip64` left at its default of True — `zipfile` raises `LargeZipFile` only when an entry needs ZIP64 and `allowZip64` is False, so a writer that allows ZIP64 documents an exception the body cannot produce. `check_docstring_no_network_claim_with_metadata_access` covers a function docstring promising a code path returns `without touching the network` (or a sibling no-network phrase) while the body calls a path-metadata method (`is_file`, `is_dir`, `exists`, `stat`, `lstat`) — on a network share each metadata call is a round-trip over the wire, so a cache-hit path the docstring swore avoids the network still pays a stat on every call; reword the claim to state the path is stat-checked on every call, or short-circuit to the cached path before the share is touched. The remaining free-form prose — `"a field counts as read when ..."`, `"resolves to shared temp only"`, `"strip ceremony, then drop blockquotes"`, and the broader module-responsibility paragraph outside the user-facing-text-scope slice the checklist below names — has no signature, method roster, or single structural shape to compare against, so the gate cannot catch its drift. This rule is the judgment standard for that prose; the audit lane below is the enforcement for everything outside the ten gated slices.
+The gate validator `check_docstring_args_match_signature` covers the `Args:` section parameter names. Ten more gate validators each cover one deterministic slice of the free-form prose. `check_docstring_names_absent_type_checking_gate` covers a module or function docstring that names a `TYPE_CHECKING` gate-detection step, or a `type-checking-gate` helper family, while no identifier in the module's code carries the `type_checking` marker — the drift where the prose points a reader at a gate the body never performs; drop the `TYPE_CHECKING` gate wording, or add the detection the prose describes. `check_docstring_length_constant_superlative_vs_exact_gate` covers a length-constant module whose docstring describes an integer `*_LENGTH` constant with a superlative or range word (`the longest color string the swatch accepts`) while the only code consuming the constant compares `len(...)` against it with `==`/`!=` — an exact-length gate that rejects every other length — and never with an ordered operator; the check scans the constant module's package tree (its own directory, or the parent package when the module sits in a `config/` subdirectory), so the mismatching consumer may sit in a sibling module. `check_docstring_fallback_branch_coverage` covers a summary that scopes a fallback to a single condition (`only when`, `falls back to ... when`) while the body routes to that same fallback call from two or more distinct early-return guards. `check_class_docstring_names_public_methods` covers a class whose docstring is a single summary line while the class exposes two or more public methods whose names the summary never spells out — the drift where a one-line class summary keeps naming its first feature after the class grows a second public entry point. `check_docstring_no_consumer_claim` covers a producer docstring asserting that no consumer reads its output yet (`producer-only artifact`, `no submission-run consumer reads it yet`) — a transitional claim that drifts the moment a reader lands and contradicts any companion `SKILL.md` that documents the consumer; this is the deterministic slice of the O8 companion-doc producer/consumer drift below. `check_docstring_returns_plural_cardinality` covers a `Returns:` clause that names a dict-key prefix family with a plural noun (`the sheen stops`) while the returned dict literal holds exactly one key in that family (`sheen_mid`) — the drift where a single-key family carries a plural noun, so the prose claims a cardinality of two or more that the dict does not hold. `check_docstring_args_single_line_scope_vs_span` covers an `Args:` entry whose prose scopes a finding to a single named line (`only when its block-anchor line is among the changed lines`) while the body builds a `range(...)` span over the finding's source lines and scopes it through a span-intersection scoper — the drift where the Args entry claims a narrower single-line scope than the span-intersection body applies, so an edit touching any non-anchor line of the span still blocks. `check_docstring_cardinal_count_matches_constant_family` covers a docstring that states a cardinal count of an outcome family (`Covers the four outcome branches: ...`) and lists those members, while the module references more members of the same `UPPER_SNAKE` constant family than the count names (`OUTCOME_OFFENDER_UNREADABLE` is imported and exercised, yet the summary stops at four) — the drift where a summary keeps the old count after the code grows another branch; this gate runs on test modules as well as production modules. `check_docstring_raises_unraisable_largezipfile` covers a `Raises:` clause that names `zipfile.LargeZipFile` while the function opens its `zipfile.ZipFile` writer in a write mode (`w`/`a`/`x`) with `allowZip64` left at its default of True — `zipfile` raises `LargeZipFile` only when an entry needs ZIP64 and `allowZip64` is False, so a writer that allows ZIP64 documents an exception the body cannot produce. `check_docstring_no_network_claim_with_metadata_access` covers a function docstring promising a code path returns `without touching the network` (or a sibling no-network phrase) while the body calls a path-metadata method (`is_file`, `is_dir`, `exists`, `stat`, `lstat`) — on a network share each metadata call is a round-trip over the wire, so a cache-hit path the docstring swore avoids the network still pays a stat on every call; reword the claim to state the path is stat-checked on every call, or short-circuit to the cached path before the share is touched. The remaining free-form prose — `"a field counts as read when ..."`, `"resolves to shared temp only"`, `"strip ceremony, then drop blockquotes"`, and the broader module-responsibility paragraph outside the user-facing-text-scope slice the checklist below names — has no signature, method roster, or single structural shape to compare against, so the gate cannot catch its drift. This rule is the judgment standard for that prose; the audit lane below is the enforcement for everything outside the eleven gated slices.
 
 ## What to check before you write the docstring
 
@@ -28,6 +28,7 @@ Read the body and the docstring side by side:
 - **Predicate breadth.** A boolean helper whose prose promises a narrow check accepts only the inputs the prose names — no broader input class the name and prose do not mention.
 - **Exclusion-clause distinguisher.** A docstring sentence that says a named category of input "are not" / "is not" the thing the function flags (`plain logging, screenshot, or method-on-local calls inside a branch are not dispatch steps`) keys the exclusion to the same axis the body's classification keys on. When the body decides on one axis (a call sits in an `If.test` guard versus a plain statement) but the prose excludes on a different axis (the call's receiver shape — a method on a local), the exclusion clause names a category the body still flags: a guarded method-on-local call is flagged even though the prose lists method-on-local calls as excluded. Read the body's actual branch condition, then state the exclusion on that same axis (`plain (unguarded) calls inside a branch body are not dispatch steps`), so every member the prose excludes is a member the body also excludes.
 - **Companion-doc ordering and content claims.** A `SKILL.md` (or sibling `.md`) sentence that names a produced artifact and claims its order (`sorted`, `alphabetical`, `in sorted order`) or its content (`the at-risk names`, `just the current set`) matches the producer function's docstring and body for that same artifact. A producer that builds the artifact by merging stored names with new names and appending — preserving file order, not re-sorting the union — leaves a doc that still says `sorted` drifted on both counts: the order claim is wrong, and the content claim hides the merged-in prior entries. When the producer's ordering or union changes, the same change updates the companion doc. The two move together in one commit, even when the producer edit does not touch the `.md` file.
+- **TYPE_CHECKING gate claim vs code.** A docstring that names a `TYPE_CHECKING` gate-detection step, or a `type-checking-gate` helper family, matches a module whose code handles TYPE_CHECKING. When no identifier in the body carries the `type_checking` marker — no `TYPE_CHECKING` load, import alias, attribute, or helper name — the prose points a reader at a gate the module never performs. State what the module does, or add the detection the prose describes. The `check_docstring_names_absent_type_checking_gate` gate blocks this drift at Write/Edit time, and covers hook infrastructure, where the import-scan gates that carry this drift class live.
 
 When the body changes the set of behaviors it applies, the same edit updates the prose enumeration. The two move together in one commit.
 

package/skills/_shared/pr-loop/scripts/build_audit_prompt.py

@@ -3,7 +3,8 @@
 Builds <context> and <scope> from CLI args; <bug_categories>,
 <rubric_reference>, and <constraints> come from the shared constants in
 skills_pr_loop_constants; <comment_posting> and <output_format> are built
-inline.
+inline. <pr_description> carries the PR body text read from --pr-body-file,
+and stays empty when that argument is absent or the file cannot be read.
 
 Usage:
   python scripts/build_audit_prompt.py --owner jl-cmd --repo claude-code-config --pr-number 422 --loop 1 --head-ref feat/branch --base-ref main --worktree-path <PATH> --run-temp-dir <PATH>
@@ -28,6 +29,38 @@ from skills_pr_loop_constants.path_resolver_constants import (
 )
 
 
+def read_pr_body_text(pr_body_file: Path | None) -> str | None:
+    """Read the PR description body from a file when given and readable.
+
+    Args:
+        pr_body_file: Path to a file holding the PR description body, or None.
+
+    Returns:
+        The file's text when the path is given and readable, otherwise None.
+    """
+    if pr_body_file is None:
+        return None
+    try:
+        return pr_body_file.read_text(encoding="utf-8")
+    except OSError:
+        return None
+
+
+def _append_pr_description(root: Element, pr_body_text: str | None) -> None:
+    """Append a <pr_description> element carrying the PR body text.
+
+    Args:
+        root: Root element the <pr_description> child is appended to.
+        pr_body_text: PR description body text, or None when unavailable.
+
+    Returns:
+        None.
+    """
+    pr_description = SubElement(root, "pr_description")
+    if pr_body_text:
+        pr_description.text = pr_body_text
+
+
 def build_audit_prompt_xml(
     *,
     owner: str,
@@ -38,6 +71,7 @@ def build_audit_prompt_xml(
     base_ref: str,
     worktree_path: Path,
     run_temp_dir: Path,
+    pr_body_text: str | None = None,
 ) -> Element:
     """Build the complete AUDIT spawn prompt XML.
 
@@ -50,6 +84,7 @@ def build_audit_prompt_xml(
         base_ref: Base branch ref.
         worktree_path: Path to the git worktree.
         run_temp_dir: Path to the run temp directory.
+        pr_body_text: PR description body text, or None when unavailable.
 
     Returns:
         Root <spawn_prompt> element.
@@ -72,6 +107,8 @@ def build_audit_prompt_xml(
         f"bugs, and anti-patterns. Work in {worktree_path.as_posix()}."
     )
 
+    _append_pr_description(root, pr_body_text)
+
     bug_categories = SubElement(root, "bug_categories")
     for each_category_id, each_category_label in ALL_AUDIT_CATEGORY_ENTRIES:
         cat_elem = SubElement(bug_categories, "category", {"id": each_category_id})
@@ -110,6 +147,7 @@ def emit_audit_prompt(
     base_ref: str,
     worktree_path: Path,
     run_temp_dir: Path,
+    pr_body_text: str | None = None,
 ) -> str:
     """Build and serialize the AUDIT spawn prompt to a pretty-printed XML string.
 
@@ -122,6 +160,7 @@ def emit_audit_prompt(
         base_ref: Base branch ref.
         worktree_path: Path to the git worktree.
         run_temp_dir: Path to the run temp directory.
+        pr_body_text: PR description body text, or None when unavailable.
 
     Returns:
         Pretty-printed XML string.
@@ -135,6 +174,7 @@ def emit_audit_prompt(
         base_ref=base_ref,
         worktree_path=worktree_path,
         run_temp_dir=run_temp_dir,
+        pr_body_text=pr_body_text,
     )
     return emit_pretty_xml(root)
 
@@ -157,6 +197,7 @@ def parse_arguments(all_argv: list[str]) -> argparse.Namespace:
     parser.add_argument("--base-ref", required=True)
     parser.add_argument("--worktree-path", type=Path, required=True)
     parser.add_argument("--run-temp-dir", type=Path, required=True)
+    parser.add_argument("--pr-body-file", type=Path, default=None)
     return parser.parse_args(all_argv)
 
 
@@ -179,6 +220,7 @@ def main(all_arguments: list[str]) -> int:
         base_ref=arguments.base_ref,
         worktree_path=arguments.worktree_path,
         run_temp_dir=arguments.run_temp_dir,
+        pr_body_text=read_pr_body_text(arguments.pr_body_file),
     )
     sys.stdout.write(xml_output)
     return 0

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

@@ -7,7 +7,7 @@ Python package of named constants for the `pr-loop` shared scripts. All constant
 | File | Role |
 |---|---|
 | `__init__.py` | Package marker. |
-| `path_resolver_constants.py` | Path template strings and format constants: workspace directory naming, worktree directory name, diff patch filename pattern, outcome XML filename patterns, loop state filename, fix status values, audit constraint texts, audit category entries, fix execution steps, fix constraint texts, and XML serialization settings. |
+| `path_resolver_constants.py` | Path template strings and format constants: workspace directory naming, worktree directory name, diff patch filename pattern, outcome XML filename patterns, fix status values, audit constraint texts, audit category entries, fix execution steps, and fix constraint texts. |
 | `preflight_constants.py` | Constants used by `preflight_worktree.py` for exit codes and output marker strings. |
 
 ## Usage
@@ -15,5 +15,5 @@ Python package of named constants for the `pr-loop` shared scripts. All constant
 Scripts import directly from the package:
 
 ```python
-from skills_pr_loop_constants.path_resolver_constants import LOOP_STATE_FILENAME
+from skills_pr_loop_constants.path_resolver_constants import PER_PR_WORKSPACE_TEMPLATE
 ```

package/skills/_shared/pr-loop/scripts/skills_pr_loop_constants/path_resolver_constants.py

@@ -9,7 +9,6 @@ WORKTREE_DIRNAME = "worktree"
 DIFF_PATCH_TEMPLATE = "loop-{loop}.patch"
 OUTCOME_XML_TEMPLATE = ".bugteam-pr{number}-loop{loop}.outcomes.xml"
 FIX_OUTCOME_XML_TEMPLATE = ".bugteam-pr{number}-loop{loop}.fix-outcomes.xml"
-LOOP_STATE_FILENAME = "loop-state.json"
 SLUGIFY_SAFE_CHARS = re.compile(r"[^A-Za-z0-9._-]")
 SLUGIFY_REPLACEMENT = "-"
 MULTI_PR_SLUG_TEMPLATE = "{owner}-{repo}-pr-{number}"
@@ -47,6 +46,7 @@ ALL_AUDIT_CATEGORY_ENTRIES = [
     ("N", "Test-name scenario verifier"),
     ("O", "Docstring / fixture-prose vs implementation drift"),
     ("P", "Name / regex / word-list vs behavior-contract precision"),
+    ("Q", "Cross-surface claim consistency (terminology, PR-description claims, message-vs-guard)"),
 ]
 
 AUDIT_RUBRIC_REFERENCE_TEXT = (
@@ -77,9 +77,6 @@ ALL_FIX_CONSTRAINT_TEXTS = [
     "forward slashes (e.g. C:/Users/...), even on Windows.",
 ]
 
-XML_PRETTY_INDENT = "  "
-XML_SERIALIZE_ENCODING = "unicode"
-XML_OUTPUT_ENCODING = "utf-8"
 ALL_PYTHON_ONEXC_VERSION = (3, 12)
 
 ALL_FINDING_BODY_ELEMENT_KEYS: tuple[str, ...] = (

package/skills/_shared/pr-loop/scripts/test_build_audit_prompt.py

@@ -1,4 +1,4 @@
-"""Tests pinning build_audit_prompt's emitted A-P category taxonomy."""
+"""Tests pinning build_audit_prompt's emitted A-Q category taxonomy."""
 
 from __future__ import annotations
 
@@ -18,7 +18,7 @@ from skills_pr_loop_constants.path_resolver_constants import (
 )
 
 _CATEGORY_RUBRICS_DIR = _SCRIPTS_DIR.parents[3] / "audit-rubrics" / "category_rubrics"
-_HEADING_PATTERN = re.compile(r"^# Category ([A-P]) — (.+)$")
+_HEADING_PATTERN = re.compile(r"^# Category ([A-Q]) — (.+)$")
 
 
 def _load_build_audit_prompt() -> ModuleType:
@@ -84,12 +84,12 @@ def test_context_and_scope_render_paths_with_forward_slashes() -> None:
     assert "C:/Users/jon/AppData/Local/Temp/bugteam-pr-376/worktree" in scope.text
 
 
-def test_bug_categories_carry_ids_a_through_p_in_order() -> None:
+def test_bug_categories_carry_ids_a_through_q_in_order() -> None:
     root = _build_audit_root()
     bug_categories = root.find("bug_categories")
     assert bug_categories is not None
     all_emitted_ids = [each_category.get("id") for each_category in bug_categories]
-    all_expected_ids = list("ABCDEFGHIJKLMNOP")
+    all_expected_ids = list("ABCDEFGHIJKLMNOPQ")
     assert all_emitted_ids == all_expected_ids
 
 
@@ -161,3 +161,99 @@ def test_prompt_skeleton_sub_bucket_counts_match_rubric_rows() -> None:
                 f"{each_letter}{each_walk_match.group(1)} but rubric has "
                 f"{sub_bucket_row_count} rows"
             )
+
+
+def test_bug_categories_include_category_q() -> None:
+    root = _build_audit_root()
+    bug_categories = root.find("bug_categories")
+    assert bug_categories is not None
+    label_by_id = {
+        each_category.get("id"): each_category.text for each_category in bug_categories
+    }
+    assert label_by_id["Q"] == (
+        "Cross-surface claim consistency "
+        "(terminology, PR-description claims, message-vs-guard)"
+    )
+
+
+def test_pr_description_carries_body_text_when_supplied() -> None:
+    root = build_audit_prompt.build_audit_prompt_xml(
+        owner="jl-cmd",
+        repo="claude-code-config",
+        pr_number=422,
+        loop=1,
+        head_ref="feat/branch",
+        base_ref="main",
+        worktree_path=Path("/tmp/bugteam-pr-422/worktree"),
+        run_temp_dir=Path("/tmp/bugteam-pr-422"),
+        pr_body_text="## Summary\nCloses the gate.",
+    )
+    pr_description = root.find("pr_description")
+    assert pr_description is not None
+    assert pr_description.text == "## Summary\nCloses the gate."
+
+
+def test_pr_description_empty_when_body_absent() -> None:
+    root = _build_audit_root()
+    pr_description = root.find("pr_description")
+    assert pr_description is not None
+    assert pr_description.text is None
+
+
+def test_read_pr_body_text_returns_file_contents(tmp_path: Path) -> None:
+    body_file = tmp_path / "pr-body.md"
+    body_file.write_text("body from disk", encoding="utf-8")
+    assert build_audit_prompt.read_pr_body_text(body_file) == "body from disk"
+
+
+def test_read_pr_body_text_returns_none_when_path_absent() -> None:
+    assert build_audit_prompt.read_pr_body_text(None) is None
+
+
+def test_read_pr_body_text_returns_none_when_file_missing(tmp_path: Path) -> None:
+    missing_file = tmp_path / "does-not-exist.md"
+    assert build_audit_prompt.read_pr_body_text(missing_file) is None
+
+
+def test_emit_audit_prompt_embeds_pr_body_text_in_pr_description() -> None:
+    xml_text = build_audit_prompt.emit_audit_prompt(
+        owner="jl-cmd",
+        repo="claude-code-config",
+        pr_number=422,
+        loop=1,
+        head_ref="feat/branch",
+        base_ref="main",
+        worktree_path=Path("/tmp/bugteam-pr-422/worktree"),
+        run_temp_dir=Path("/tmp/bugteam-pr-422"),
+        pr_body_text="body via emit",
+    )
+    assert "body via emit" in xml_text
+
+
+def test_parse_arguments_defaults_pr_body_file_to_none() -> None:
+    arguments = build_audit_prompt.parse_arguments([
+        "--owner", "jl-cmd",
+        "--repo", "claude-code-config",
+        "--pr-number", "422",
+        "--loop", "1",
+        "--head-ref", "feat/branch",
+        "--base-ref", "main",
+        "--worktree-path", "/tmp/wt",
+        "--run-temp-dir", "/tmp/rt",
+    ])
+    assert arguments.pr_body_file is None
+
+
+def test_parse_arguments_reads_pr_body_file_path() -> None:
+    arguments = build_audit_prompt.parse_arguments([
+        "--owner", "jl-cmd",
+        "--repo", "claude-code-config",
+        "--pr-number", "422",
+        "--loop", "1",
+        "--head-ref", "feat/branch",
+        "--base-ref", "main",
+        "--worktree-path", "/tmp/wt",
+        "--run-temp-dir", "/tmp/rt",
+        "--pr-body-file", "/tmp/body.md",
+    ])
+    assert arguments.pr_body_file == Path("/tmp/body.md")

package/skills/autoconverge/SKILL.md

@@ -131,7 +131,10 @@ no agent spawned. The workflow runs in the background and notifies this session
 on completion. Watch live progress with `/workflows`.
 
 The workflow returns
-`{ converged, rounds, finalSha, blocker, standardsNote, copilotNote, reuseNote }`.
+`{ converged, rounds, finalSha, blocker, standardsNote, copilotNote, reuseNote, deferredPrs }`.
+`deferredPrs` is the list of draft environment-hardening PRs the standards-deferral
+path opened this run, each as `{ owner, repo, prNumber }` — the seed the
+[self-closing loop](#self-closing-loop-converge-the-deferred-prs) converges next.
 
 ## Budget-aware round boundaries
 
@@ -312,10 +315,10 @@ matches.
   (hooks/rules that block those violation classes at Write/Edit time), resolves
   any bot threads with a deferral note, and reports the deferral in
   `standardsNote`.
-- **Copilot gate:** request a Copilot review, poll up to three times; findings
+- **Copilot gate:** request a Copilot review, poll up to the configured cap; findings
   route back into Converge. When Copilot is down or out of quota — it posts an
   out-of-usage notice (the requester hit their quota) on the HEAD, or surfaces no
-  review at all after the cap — the gate logs a notice and the run marks the PR
+  review at all after the configured cap — the gate logs a notice and the run marks the PR
   ready with the Copilot gate bypassed. `copilotNote` records the bypass.
 - **Convergence check:** `check_convergence.py` is the authoritative gate; on a
   full pass the workflow marks `draft=false`.
@@ -387,10 +390,13 @@ checked out in. The workflow runs in the background and notifies this session on
 completion; watch live progress with `/workflows`, where each PR's child run
 appears under its own group.
 
-The workflow returns `{ converged, prCount, convergedCount, results, blocker }`,
-where `results` is one record per PR carrying
-`{ owner, repo, prNumber, converged, rounds, finalSha, blocker }`. The top-level
-`converged` is true only when every PR converged.
+The workflow returns
+`{ converged, prCount, convergedCount, results, allDeferredPrs, blocker }`, where
+`results` is one record per PR carrying
+`{ owner, repo, prNumber, converged, rounds, finalSha, blocker, deferredPrs }`.
+Each record's `deferredPrs` is that PR's own list of draft hardening PRs, and
+`allDeferredPrs` is every record's `deferredPrs` flattened into one list. The
+top-level `converged` is true only when every PR converged.
 
 ### Multi-PR teardown (on workflow completion)
 
@@ -403,6 +409,85 @@ permissions once per repository after every PR's teardown. Then print one summar
 report — a line per PR as
 `#<prNumber>: <converged | blocked> — rounds <N>, final <finalSha>[, blocker <blocker>]`.
 
+## Self-closing loop: converge the deferred PRs
+
+Every run leaves work behind. When a round holds only code-standard findings, the
+standards-deferral path opens a draft environment-hardening PR and reports it in
+`deferredPrs`. That PR is itself a draft that needs to reach ready, and its own
+convergence can defer more standard findings, opening more hardening PRs. The
+self-closing loop drives that chain to the ground: after teardown, the
+orchestrator (this session, which launched the workflow) converges the deferred
+PRs, then the PRs their runs defer, and so on until a generation opens none.
+
+This loop runs by default at the end of every autoconverge run — single-PR and
+multi-PR alike. It stops only when a generation's deferred-PR list comes back
+empty.
+
+### Seed the loop
+
+Collect the first generation of deferred PRs from the run that just finished:
+
+- A single-PR run seeds from its `deferredPrs`.
+- A multi-PR run seeds from its `allDeferredPrs`.
+
+When the seed list is empty, the loop is already done — the run deferred nothing,
+so there is nothing to converge. Report that and stop.
+
+### Each generation
+
+Given a non-empty list of deferred PRs `{ owner, repo, prNumber }` (a generation
+may span more than one repository — a hardening PR lands in whichever repo owns
+the surface that blocks the deferred class, so `JonEcho/llm-settings` for hooks
+and `jl-cmd/claude-code-config` for rules and skills both appear):
+
+1. **Check out each deferred PR.** Run the
+   [Multi-PR pre-flight](#multi-pr-pre-flight-main-session) once per deferred PR.
+   Because a deferred PR can live in a repo the first run never touched, first
+   find a local checkout of that PR's repo; when none exists, clone it under the
+   session temp dir, then add the per-PR worktree on the PR's head ref. Drop any
+   PR whose strict pre-flight fails rather than stopping the whole generation.
+   Grant project permissions once per repository the generation spans.
+2. **Converge the generation.** Launch `workflow/converge_multi.mjs` with one
+   entry per checked-out deferred PR, exactly as the
+   [multi-PR launch](#launch-the-multi-pr-workflow) describes.
+3. **Tear down.** Run the [multi-PR teardown](#multi-pr-teardown-on-workflow-completion)
+   over the generation's `results`, and revoke project permissions once per
+   repository.
+4. **Take the next seed.** The generation's `allDeferredPrs` is the next
+   generation's seed list. When it is empty, the loop is done.
+
+Repeat from step 1 with each new seed. The depth is unbounded: the loop keeps
+opening generations until one converges every deferred PR without deferring
+anything new.
+
+### Report each generation
+
+Log one line as each generation finishes, so a watcher sees the chain close:
+
+```
+Self-closing generation <k>: <converged>/<total> deferred PR(s) converged, <new> new deferred PR(s) opened
+```
+
+When the loop ends, print a final line naming the generation count and the total
+deferred PRs converged across every generation.
+
+### Conventional titles on deferred PRs
+
+Each hardening PR the loop opens targets a repo whose CI validates the PR title
+as a Conventional Commit. The commit step's prompt directs the agent to title
+the hardening PR as a Conventional Commit — a type prefix, an optional scope,
+then a colon and a short summary — so a deferred PR carries a conforming title
+(`feat(hooks): …`, `chore(rules): …`) before it exists. That prompt is where the
+conforming title is enforced.
+
+The `conventional_pr_title_gate` hook is a best-effort backstop on that title,
+not the guarantee. It blocks a `gh pr create` with a non-conforming `--title`
+only for a repo whose semantic-pull-request workflow leaves the action's
+`types:` input at the default Conventional Commits list. For a repo that pins
+its own explicit `types:` list — which the main target repo does in
+`.github/workflows/pr-check.yml` — the hook fails open and lets the title
+through, and the CI title check on GitHub has the final say.
+
 ## Folder map
 
 - `SKILL.md` — this hub.

package/skills/autoconverge/reference/convergence.md

@@ -79,11 +79,11 @@ tracks CONVERGE passes only and is never the cap.
 **COPILOT** gate:
 
 - Request a Copilot review on HEAD (skipping a duplicate request), then poll up
-  to three times, 360 seconds apart.
+  to the configured cap, 360 seconds apart.
 - Copilot findings → fix them and return to CONVERGE on the new HEAD.
 - Copilot clean or approved → move to the convergence check.
-- Copilot down or out of quota (an out-of-usage notice, or no review after three
-  polls) → log a notice and move to the convergence check with the Copilot gate
+- Copilot down or out of quota (an out-of-usage notice, or no review after the
+  configured cap) → log a notice and move to the convergence check with the Copilot gate
   bypassed.
 
 **Convergence check**:

package/skills/autoconverge/reference/gotchas.md

@@ -3,11 +3,11 @@
 Hard-won lessons for the autoconverge workflow. Append a bullet each time a run
 fails in a new way.
 
-- **The workflow script cannot sleep.** `Date.now`, `Math.random`, and timers
-  are unavailable in the script body, and a foreground sleep is blocked. Every
-  reviewer wait lives inside an `agent`'s own poll loop — a shell-agnostic `sleep`
-  loop (PowerShell `Start-Sleep` is an allowed alternative), or `gh` check
-  polling. Never try to wait in the script itself.
+- **The workflow script cannot sleep, and neither can an agent's foreground shell.** `Date.now`, `Math.random`, and timers
+  are unavailable in the script body, and a foreground `sleep` / `Start-Sleep` is blocked in the headless harness. Every
+  reviewer wait lives inside an `agent`'s own poll loop, and that loop waits with the Monitor tool inside the same turn —
+  never a foreground sleep, and never backgrounding a wait and ending the turn to await it, which
+  leaves a schema-bearing agent with no `StructuredOutput` call. Never try to wait in the script itself.
 
 - **Workflow agents start blank.** Spawned agents do not inherit CLAUDE.md,
   rules, or this skill's context. Each agent prompt is self-contained: it names

package/skills/autoconverge/reference/stop-conditions.md

@@ -47,7 +47,7 @@ skill still runs teardown (revoke permissions, final report).
   Bugbot gate is bypassed.
 - **Copilot down or out of quota** — when Copilot posts an out-of-usage notice on
   the current HEAD (the user who requested the review reached their quota limit)
-  rather than a code review, or surfaces no review at all after three polls, the
+  rather than a code review, or surfaces no review at all after the configured cap, the
   Copilot gate returns `down: true`. The run logs a notice, runs the convergence
   check with `--copilot-down` (the Copilot review gate and the
   pending-requested-reviews gate bypassed), and marks the PR ready. `copilotNote`