claude-dev-env 1.39.0 → 1.41.0

package/hooks/blocking/test_pr_converge_bugteam_enforcer.py

@@ -0,0 +1,311 @@
+"""Unit tests for the pr_converge_bugteam_enforcer PreToolUse hook.
+
+Covers the Step 5 BUGTEAM contract: Agent({subagent_type: "clean-coder"})
+calls that look like audit substitutes are blocked when
+$CLAUDE_JOB_DIR/pr-converge-state.json (named by PR_CONVERGE_STATE_FILENAME)
+shows phase=BUGTEAM and the formal Skill({skill: "bugteam"}) has not
+registered at the current HEAD and tick. qbug is explicitly NOT a substitute.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import io
+import json
+import pathlib
+import sys
+from typing import Any
+from unittest import mock
+
+import pytest
+
+_HOOK_DIR = pathlib.Path(__file__).parent
+_HOOKS_TREE = _HOOK_DIR.parent
+for each_path in (str(_HOOK_DIR), str(_HOOKS_TREE)):
+    if each_path not in sys.path:
+        sys.path.insert(0, each_path)
+
+hook_spec = importlib.util.spec_from_file_location(
+    "pr_converge_bugteam_enforcer",
+    _HOOK_DIR / "pr_converge_bugteam_enforcer.py",
+)
+assert hook_spec is not None
+assert hook_spec.loader is not None
+hook_module = importlib.util.module_from_spec(hook_spec)
+hook_spec.loader.exec_module(hook_module)
+
+from config.pr_converge_bugteam_enforcer_constants import (
+    BUGTEAM_PHASE,
+    CLAUDE_JOB_DIR_ENV_VAR,
+    PR_CONVERGE_STATE_FILENAME,
+)
+
+_HEAD_SHA_CURRENT = "abc123def456abc123def456abc123def456abcd"
+_HEAD_SHA_STALE = "deadbeef0000deadbeef0000deadbeef0000dead"
+_TICK_CURRENT = 7
+_AUDIT_PROMPT = "Run the bugteam audit and report findings against the A-J categories."
+_FIX_ONLY_PROMPT = "Fix the failing test in tests/test_widget.py by adding a guard clause."
+
+
+def _write_state(state_directory: pathlib.Path, state: dict[str, Any]) -> pathlib.Path:
+    state_path = state_directory / PR_CONVERGE_STATE_FILENAME
+    state_path.write_text(json.dumps(state), encoding="utf-8")
+    return state_path
+
+
+def _bugteam_phase_state(**overrides: Any) -> dict[str, Any]:
+    baseline_state: dict[str, Any] = {
+        "phase": BUGTEAM_PHASE,
+        "current_head": _HEAD_SHA_CURRENT,
+        "tick_count": _TICK_CURRENT,
+        "bugteam_skill_invoked_at_head": None,
+        "bugteam_skill_invoked_at_tick": None,
+    }
+    baseline_state.update(overrides)
+    return baseline_state
+
+
+def _clean_coder_audit_payload(prompt: str = _AUDIT_PROMPT) -> dict[str, Any]:
+    return {
+        "tool_name": "Agent",
+        "tool_input": {
+            "subagent_type": "clean-coder",
+            "prompt": prompt,
+            "description": "Audit the PR",
+        },
+    }
+
+
+def _run_main_with_io(input_text: str) -> str:
+    with mock.patch("sys.stdin", io.StringIO(input_text)):
+        with mock.patch("sys.stdout", new_callable=io.StringIO) as captured_stdout:
+            try:
+                hook_module.main()
+            except SystemExit:
+                pass
+            return captured_stdout.getvalue()
+
+
+@pytest.fixture()
+def claude_job_directory(tmp_path: pathlib.Path, monkeypatch: pytest.MonkeyPatch) -> pathlib.Path:
+    monkeypatch.setenv(CLAUDE_JOB_DIR_ENV_VAR, str(tmp_path))
+    return tmp_path
+
+
+def test_should_allow_when_state_file_absent(claude_job_directory: pathlib.Path) -> None:
+    payload_text = json.dumps(_clean_coder_audit_payload())
+    captured_output = _run_main_with_io(payload_text)
+    assert captured_output == ""
+
+
+def test_should_allow_when_phase_not_bugteam(claude_job_directory: pathlib.Path) -> None:
+    _write_state(claude_job_directory, _bugteam_phase_state(phase="BUGBOT"))
+    payload_text = json.dumps(_clean_coder_audit_payload())
+    captured_output = _run_main_with_io(payload_text)
+    assert captured_output == ""
+
+
+def test_should_allow_when_subagent_type_not_clean_coder(
+    claude_job_directory: pathlib.Path,
+) -> None:
+    _write_state(claude_job_directory, _bugteam_phase_state())
+    explore_payload: dict[str, Any] = {
+        "tool_name": "Agent",
+        "tool_input": {"subagent_type": "Explore", "prompt": _AUDIT_PROMPT},
+    }
+    captured_output = _run_main_with_io(json.dumps(explore_payload))
+    assert captured_output == ""
+
+
+def test_should_allow_when_prompt_lacks_audit_keywords(
+    claude_job_directory: pathlib.Path,
+) -> None:
+    _write_state(claude_job_directory, _bugteam_phase_state())
+    payload_text = json.dumps(_clean_coder_audit_payload(prompt=_FIX_ONLY_PROMPT))
+    captured_output = _run_main_with_io(payload_text)
+    assert captured_output == ""
+
+
+def test_should_block_when_clean_coder_audit_without_bugteam_skill_invocation(
+    claude_job_directory: pathlib.Path,
+) -> None:
+    _write_state(claude_job_directory, _bugteam_phase_state())
+    captured_output = _run_main_with_io(json.dumps(_clean_coder_audit_payload()))
+    deny_payload = json.loads(captured_output)
+    assert deny_payload["hookSpecificOutput"]["permissionDecision"] == "deny"
+    assert "bugteam-enforcer" in deny_payload["hookSpecificOutput"]["permissionDecisionReason"]
+
+
+def test_should_allow_after_bugteam_skill_invoked_at_current_head_and_tick(
+    claude_job_directory: pathlib.Path,
+) -> None:
+    _write_state(
+        claude_job_directory,
+        _bugteam_phase_state(
+            bugteam_skill_invoked_at_head=_HEAD_SHA_CURRENT,
+            bugteam_skill_invoked_at_tick=_TICK_CURRENT,
+        ),
+    )
+    captured_output = _run_main_with_io(json.dumps(_clean_coder_audit_payload()))
+    assert captured_output == ""
+
+
+def test_should_block_when_bugteam_skill_invocation_is_stale_head(
+    claude_job_directory: pathlib.Path,
+) -> None:
+    _write_state(
+        claude_job_directory,
+        _bugteam_phase_state(
+            bugteam_skill_invoked_at_head=_HEAD_SHA_STALE,
+            bugteam_skill_invoked_at_tick=_TICK_CURRENT,
+        ),
+    )
+    captured_output = _run_main_with_io(json.dumps(_clean_coder_audit_payload()))
+    deny_payload = json.loads(captured_output)
+    assert deny_payload["hookSpecificOutput"]["permissionDecision"] == "deny"
+
+
+def test_should_block_when_qbug_was_invoked_but_not_bugteam(
+    claude_job_directory: pathlib.Path,
+) -> None:
+    _write_state(
+        claude_job_directory,
+        _bugteam_phase_state(
+            bugteam_skill_invoked_at_head=None,
+            bugteam_skill_invoked_at_tick=None,
+        ),
+    )
+    captured_output = _run_main_with_io(json.dumps(_clean_coder_audit_payload()))
+    deny_payload = json.loads(captured_output)
+    assert deny_payload["hookSpecificOutput"]["permissionDecision"] == "deny"
+
+
+def test_should_block_when_bugteam_invoked_at_current_head_but_previous_tick(
+    claude_job_directory: pathlib.Path,
+) -> None:
+    _write_state(
+        claude_job_directory,
+        _bugteam_phase_state(
+            bugteam_skill_invoked_at_head=_HEAD_SHA_CURRENT,
+            bugteam_skill_invoked_at_tick=_TICK_CURRENT - 1,
+        ),
+    )
+    captured_output = _run_main_with_io(json.dumps(_clean_coder_audit_payload()))
+    deny_payload = json.loads(captured_output)
+    assert deny_payload["hookSpecificOutput"]["permissionDecision"] == "deny"
+
+
+def test_should_block_when_invoked_head_is_non_string_type(
+    claude_job_directory: pathlib.Path,
+) -> None:
+    _write_state(
+        claude_job_directory,
+        _bugteam_phase_state(
+            bugteam_skill_invoked_at_head=42,
+            bugteam_skill_invoked_at_tick=_TICK_CURRENT,
+        ),
+    )
+    captured_output = _run_main_with_io(json.dumps(_clean_coder_audit_payload()))
+    deny_payload = json.loads(captured_output)
+    assert deny_payload["hookSpecificOutput"]["permissionDecision"] == "deny"
+
+
+def test_should_block_when_current_head_is_non_string_type(
+    claude_job_directory: pathlib.Path,
+) -> None:
+    _write_state(
+        claude_job_directory,
+        _bugteam_phase_state(
+            current_head=42,
+            bugteam_skill_invoked_at_head=_HEAD_SHA_CURRENT,
+            bugteam_skill_invoked_at_tick=_TICK_CURRENT,
+        ),
+    )
+    captured_output = _run_main_with_io(json.dumps(_clean_coder_audit_payload()))
+    deny_payload = json.loads(captured_output)
+    assert deny_payload["hookSpecificOutput"]["permissionDecision"] == "deny"
+
+
+def test_should_block_when_invoked_tick_is_string_type(
+    claude_job_directory: pathlib.Path,
+) -> None:
+    _write_state(
+        claude_job_directory,
+        _bugteam_phase_state(
+            bugteam_skill_invoked_at_head=_HEAD_SHA_CURRENT,
+            bugteam_skill_invoked_at_tick="7",
+        ),
+    )
+    captured_output = _run_main_with_io(json.dumps(_clean_coder_audit_payload()))
+    deny_payload = json.loads(captured_output)
+    assert deny_payload["hookSpecificOutput"]["permissionDecision"] == "deny"
+
+
+def test_should_block_when_current_tick_is_string_type(
+    claude_job_directory: pathlib.Path,
+) -> None:
+    _write_state(
+        claude_job_directory,
+        _bugteam_phase_state(
+            tick_count="7",
+            bugteam_skill_invoked_at_head=_HEAD_SHA_CURRENT,
+            bugteam_skill_invoked_at_tick=_TICK_CURRENT,
+        ),
+    )
+    captured_output = _run_main_with_io(json.dumps(_clean_coder_audit_payload()))
+    deny_payload = json.loads(captured_output)
+    assert deny_payload["hookSpecificOutput"]["permissionDecision"] == "deny"
+
+
+def test_should_block_when_invoked_tick_is_bool_type(
+    claude_job_directory: pathlib.Path,
+) -> None:
+    _write_state(
+        claude_job_directory,
+        _bugteam_phase_state(
+            tick_count=1,
+            bugteam_skill_invoked_at_head=_HEAD_SHA_CURRENT,
+            bugteam_skill_invoked_at_tick=True,
+        ),
+    )
+    captured_output = _run_main_with_io(json.dumps(_clean_coder_audit_payload()))
+    deny_payload = json.loads(captured_output)
+    assert deny_payload["hookSpecificOutput"]["permissionDecision"] == "deny"
+
+
+def test_should_block_when_current_tick_is_bool_type(
+    claude_job_directory: pathlib.Path,
+) -> None:
+    _write_state(
+        claude_job_directory,
+        _bugteam_phase_state(
+            tick_count=True,
+            bugteam_skill_invoked_at_head=_HEAD_SHA_CURRENT,
+            bugteam_skill_invoked_at_tick=1,
+        ),
+    )
+    captured_output = _run_main_with_io(json.dumps(_clean_coder_audit_payload()))
+    deny_payload = json.loads(captured_output)
+    assert deny_payload["hookSpecificOutput"]["permissionDecision"] == "deny"
+
+
+def test_should_allow_when_claude_job_dir_env_var_absent(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.delenv(CLAUDE_JOB_DIR_ENV_VAR, raising=False)
+    captured_output = _run_main_with_io(json.dumps(_clean_coder_audit_payload()))
+    assert captured_output == ""
+
+
+def test_should_allow_when_state_json_is_malformed(
+    claude_job_directory: pathlib.Path,
+) -> None:
+    state_path = claude_job_directory / PR_CONVERGE_STATE_FILENAME
+    state_path.write_text("{not valid json", encoding="utf-8")
+    captured_output = _run_main_with_io(json.dumps(_clean_coder_audit_payload()))
+    assert captured_output == ""
+
+
+def test_should_allow_when_payload_is_malformed_json() -> None:
+    captured_output = _run_main_with_io("not valid json {{{")
+    assert captured_output == ""

package/hooks/blocking/test_pr_description_enforcer.py

@@ -25,8 +25,21 @@ extract_body_from_command = hook_module.extract_body_from_command
 validate_pr_body = hook_module.validate_pr_body
 
 VALID_BODY = (
-    "## Description\n\nThis PR fixes a real bug.\n\n"
-    "## Why\n\nBecause it was broken in production.\n\n"
+    "Allow commas in branch names so PRs whose head branch was generated from "
+    "a title or external identifier no longer fail validation before any git "
+    "operation.\n\n"
+    "Fixes #1300.\n\n"
+    "## Changes\n\n"
+    "- `src/github/operations/branch.ts`: add `,` to the whitelist regex\n"
+    "- `test/branch.test.ts`: 3 new cases covering comma-bearing branch names\n\n"
+    "## Test plan\n\n"
+    "- `bun test test/branch.test.ts`\n"
+    "- `bun run typecheck`\n"
+)
+
+LEGACY_DESCRIPTION_WHY_HOW_BODY = (
+    "## Description\n\nThis PR fixes a real bug in the authentication module.\n\n"
+    "## Why\n\nBecause it was broken in production and customers reported failures.\n\n"
     "## How\n\nRefactored the auth module to handle edge cases correctly.\n"
 )
 
@@ -109,15 +122,63 @@ def test_extract_short_flag_shell_var_returns_empty() -> None:
     assert extract_body_from_command(command) == ""
 
 
-def test_validate_passes_complete_body() -> None:
+def test_validate_passes_anthropic_standard_body() -> None:
     assert validate_pr_body(VALID_BODY) == []
 
 
-def test_validate_blocks_missing_sections() -> None:
-    violations = validate_pr_body("Some body text without required sections.\n" * 5)
-    assert any(
-        "Missing required section" in each_violation for each_violation in violations
+def test_validate_passes_legacy_description_why_how_body() -> None:
+    """Existing Description/Why/How bodies must still pass -- the relaxed rule only widens what's accepted."""
+    assert validate_pr_body(LEGACY_DESCRIPTION_WHY_HOW_BODY) == []
+
+
+def test_validate_passes_sectionless_prose_body() -> None:
+    """Anthropic's trivial-PR shape is one sentence with no headers."""
+    body = (
+        "Pin third-party GitHub Actions references to immutable commit SHAs "
+        "so a tag move cannot redirect CI to attacker-controlled code."
+    )
+    assert validate_pr_body(body) == []
+
+
+def test_validate_blocks_skeleton_body_with_only_headers_and_bullets() -> None:
+    """Sections + bullets without any prose Why is rejected -- the substantive-prose check catches this."""
+    body = (
+        "## Summary\n\n"
+        "## Changes\n\n"
+        "- `a`\n"
+        "- `b`\n"
+        "- `c`\n"
+    )
+    violations = validate_pr_body(body)
+    assert any("substantive prose" in each_violation.lower() for each_violation in violations)
+
+
+def test_validate_blocks_blockquoted_headings_with_no_real_prose() -> None:
+    """Regression: blockquote markers must strip BEFORE heading stripping.
+
+    A line like `> ## Summary` starts with `>`, so `^#+[ \\t].*$` cannot match it
+    in heading position. If blockquote markers are stripped after, the bare
+    `## Summary` text survives into the prose stream and inflates the count.
+    Correct order strips `> ` first, then the line becomes a real heading and
+    drops out, leaving an effectively empty body below the 40-character minimum.
+    """
+    body = "> ## Summary\n> ## Why\n> ## How"
+    violations = validate_pr_body(body)
+    assert any("substantive prose" in each_violation.lower() for each_violation in violations)
+
+
+def test_validate_passes_prose_after_bare_hashes_with_no_space() -> None:
+    """Bug regression: `##\\n` followed by prose must not have its prose eaten by the heading regex.
+
+    The previous pattern `^#+\\s.*$` matched `\\s` against the newline, then `.*$` greedily
+    consumed the next line. The fix restricts the whitespace class to `[ \\t]` so only true
+    headings (`## text`) match, leaving prose-after-bare-hashes intact for substantive-prose counting.
+    """
+    body = (
+        "##\nThis is real prose that should not be eaten by the heading regex, "
+        "it should pass the 40-character minimum."
     )
+    assert validate_pr_body(body) == []
 
 
 def test_validate_blocks_vague_language() -> None:
@@ -128,7 +189,7 @@ def test_validate_blocks_vague_language() -> None:
 
 def test_validate_blocks_short_body() -> None:
     violations = validate_pr_body("Too short.")
-    assert any("too short" in each_violation.lower() for each_violation in violations)
+    assert any("substantive prose" in each_violation.lower() for each_violation in violations)
 
 
 def test_body_file_content_validated(tmp_path: pathlib.Path) -> None:

package/hooks/config/gh_pr_author_swap_constants.py

@@ -0,0 +1,76 @@
+"""Configuration constants for the gh-pr-author swap hook trio.
+
+The PreToolUse enforcer (``gh_pr_author_enforcer.py``) auto-switches the
+active ``gh`` CLI account to ``GITHUB_DEFAULT_ACCOUNT`` before a
+``gh pr create`` invocation, the PostToolUse companion
+(``gh_pr_author_restore.py``) restores the prior account afterwards, and
+the SessionStart cleanup hook (``gh_pr_author_session_cleanup.py``)
+sweeps any stale state files left behind when a prior session was
+interrupted between the swap and the restore. The state file written
+between the hooks is keyed per session so parallel Claude Code sessions
+cannot stomp on each other's swap state.
+"""
+
+from __future__ import annotations
+
+import re
+
+REQUIRED_ACCOUNT_ENV_VAR: str = "GITHUB_DEFAULT_ACCOUNT"
+
+BASH_TOOL_NAME: str = "Bash"
+
+GH_PR_CREATE_PATTERN: re.Pattern[str] = re.compile(
+    r"(?:^|[;&|\n`({]|\$\()[ \t]*"
+    r"(?:(?:if|then|else|elif|while|until|do|!)[ \t]+)*"
+    r"(?:[A-Za-z_][A-Za-z0-9_]*=\S+[ \t]+)*"
+    r"gh(?:[ \t]+(?:--[A-Za-z][\w-]*(?:=\S+)?|-[A-Za-z])(?:[ \t]+(?!-)\S+)?)*"
+    r"[ \t]+pr[ \t]+create\b",
+    re.IGNORECASE,
+)
+WEB_FLAG_PATTERN: re.Pattern[str] = re.compile(r"(?<!\S)(?:--web|-w)(?!\S)")
+COMMAND_SEPARATOR_PATTERN: re.Pattern[str] = re.compile(
+    r"(?:&&|\|\||;|(?<!\|)\|(?!\|)|(?<!&)&(?!&)|[\r\n])"
+)
+BASH_COMMENT_INTRODUCER_CHARACTER: str = "#"
+COMMAND_SUBSTITUTION_OPENER_LENGTH: int = 2
+
+ALL_GH_API_USER_COMMAND: tuple[str, ...] = ("gh", "api", "user", "--jq", ".login")
+GH_API_USER_TIMEOUT_SECONDS: int = 5
+
+ALL_GH_AUTH_SWITCH_COMMAND_HEAD: tuple[str, ...] = ("gh", "auth", "switch", "--user")
+GH_AUTH_SWITCH_TIMEOUT_SECONDS: int = 10
+
+STATE_FILE_PREFIX: str = "gh_pr_author_swap_"
+STATE_FILE_SUFFIX: str = ".json"
+STATE_FILE_DEFAULT_SESSION_ID: str = "default"
+
+SESSION_ID_UNSAFE_CHARACTERS_PATTERN: re.Pattern[str] = re.compile(r"[^A-Za-z0-9_-]")
+
+STATE_FILE_ORIGINAL_ACCOUNT_KEY: str = "original_account"
+STATE_FILE_PRIMARY_ACCOUNT_KEY: str = "primary_account"
+
+STATE_FILE_PERMISSION_MODE: int = 0o600
+
+STATE_FILE_PAYLOAD_TEXT_ENCODING_NAME: str = "utf-8"
+
+OS_O_NOFOLLOW_ATTRIBUTE_NAME: str = "O_NOFOLLOW"
+
+STATE_FILE_STALE_AGE_SECONDS: int = 1800
+
+ALL_SHELL_QUOTE_CHARACTERS: tuple[str, ...] = ("\"", "'")
+SHELL_QUOTE_REPLACEMENT_CHARACTER: str = " "
+SHELL_BACKSLASH_ESCAPE_PAIR_LENGTH: int = 2
+SHELL_BACKTICK_CHARACTER: str = "`"
+SHELL_DOLLAR_CHARACTER: str = "$"
+SHELL_PAREN_OPEN_CHARACTER: str = "("
+SHELL_PAREN_CLOSE_CHARACTER: str = ")"
+SHELL_LESS_THAN_CHARACTER: str = "<"
+SHELL_BACKSLASH_CHARACTER: str = "\\"
+SHELL_NEWLINE_CHARACTER: str = "\n"
+
+HEREDOC_OPENER_TAG_PATTERN: re.Pattern[str] = re.compile(
+    r"[ \t]*(?P<dash>-?)[ \t]*(?:'(?P<sq_tag>[A-Za-z_][A-Za-z0-9_]*)'"
+    r"|\"(?P<dq_tag>[A-Za-z_][A-Za-z0-9_]*)\""
+    r"|(?P<bare_tag>[A-Za-z_][A-Za-z0-9_]*))"
+)
+HEREDOC_OPENER_TOKEN_LENGTH: int = 2

package/hooks/config/pr_converge_bugteam_enforcer_constants.py

@@ -0,0 +1,55 @@
+"""Configuration constants for the pr_converge_bugteam_enforcer hook pair.
+
+The enforcer denies ``Agent({subagent_type: "clean-coder"})`` invocations that
+substitute audit-shaped work for the formal ``Skill({skill: "bugteam"})`` call
+during Step 5 BUGTEAM of the pr-converge loop. The tracker records every
+formal ``Skill({skill: "bugteam"})`` invocation so the enforcer can confirm
+the Skill fired this tick at the current HEAD before allowing follow-on
+clean-coder spawns.
+"""
+
+from __future__ import annotations
+
+AGENT_TOOL_NAME: str = "Agent"
+SKILL_TOOL_NAME: str = "Skill"
+
+CLEAN_CODER_SUBAGENT_TYPE: str = "clean-coder"
+BUGTEAM_SKILL_NAME: str = "bugteam"
+
+PR_CONVERGE_STATE_FILENAME: str = "pr-converge-state.json"
+CLAUDE_JOB_DIR_ENV_VAR: str = "CLAUDE_JOB_DIR"
+
+BUGTEAM_PHASE: str = "BUGTEAM"
+
+STATE_FIELD_PHASE: str = "phase"
+STATE_FIELD_CURRENT_HEAD: str = "current_head"
+STATE_FIELD_TICK_COUNT: str = "tick_count"
+STATE_FIELD_BUGTEAM_SKILL_INVOKED_AT_HEAD: str = "bugteam_skill_invoked_at_head"
+STATE_FIELD_BUGTEAM_SKILL_INVOKED_AT_TICK: str = "bugteam_skill_invoked_at_tick"
+
+ALL_AUDIT_PROMPT_SUBSTRINGS: tuple[str, ...] = (
+    "audit",
+    "findings",
+    "bugteam",
+    "a-j categor",
+    "code-quality",
+    "verify_clean",
+    "converge",
+)
+
+ENFORCER_CORRECTIVE_MESSAGE: str = (
+    "BLOCKED [pr-converge-bugteam-enforcer]: Step 5 BUGTEAM advances ONLY after "
+    '`Skill({skill: "bugteam", args: "<PR URL>"})` fires this tick at the '
+    'current HEAD. Substituting an `Agent({subagent_type: "clean-coder"})` '
+    "audit call for the formal Skill invocation is a protocol violation — the "
+    "formal Skill writes the artifact `check_convergence.py`'s `bugteam_clean_at` "
+    "gate looks for, and a substituted audit silently bypasses that gate.\n\n"
+    "`qbug` is NOT an accepted substitute — `bugteam` is the only allowed skill "
+    "at this step.\n\n"
+    'Run `Skill({skill: "bugteam", args: "<PR URL>"})` first. Follow-on '
+    "clean-coder fix spawns are allowed once the formal Skill has registered at "
+    "the current HEAD and tick."
+)
+
+STATE_FILE_ATOMIC_WRITE_SUFFIX: str = ".tmp"
+STATE_FILE_JSON_INDENT_SPACES: int = 2

package/hooks/config/pr_converge_bugteam_enforcer_state.py

@@ -0,0 +1,67 @@
+"""Shared state-loading helpers for the pr_converge_bugteam_enforcer hook pair.
+
+Both the enforcer (``pr_converge_bugteam_enforcer.py``) and the tracker
+(``pr_converge_bugteam_skill_tracker.py``) read the per-job
+``$CLAUDE_JOB_DIR/pr-converge-state.json`` file from the same per-job
+directory. This module hosts the byte-identical ``load_state_dictionary``
+and ``resolve_state_path`` helpers so each hook imports a single canonical
+definition.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+
+from config.pr_converge_bugteam_enforcer_constants import (
+    CLAUDE_JOB_DIR_ENV_VAR,
+    PR_CONVERGE_STATE_FILENAME,
+)
+
+
+def load_state_dictionary(state_path: Path) -> dict[str, object] | None:
+    """Return the parsed pr-converge state, or None when absent or unparseable.
+
+    Args:
+        state_path: Absolute path to ``pr-converge-state.json``.
+
+    Returns:
+        The decoded state dictionary, or None when the file is missing,
+        malformed, empty, or not a JSON object at the root.
+    """
+    if not state_path.is_file():
+        return None
+    try:
+        raw_text = state_path.read_text(encoding="utf-8")
+    except OSError:
+        return None
+    if not raw_text.strip():
+        return None
+    try:
+        parsed_state = json.loads(raw_text)
+    except json.JSONDecodeError:
+        return None
+    if not isinstance(parsed_state, dict):
+        return None
+    return parsed_state
+
+
+def resolve_state_path() -> Path | None:
+    """Return the absolute path to the per-job ``pr-converge-state.json``.
+
+    Reads ``$CLAUDE_JOB_DIR`` from the environment and joins
+    ``PR_CONVERGE_STATE_FILENAME`` onto it. The path is returned even when
+    the file does not yet exist on disk; callers are expected to call
+    ``load_state_dictionary`` (or ``state_path.is_file()``) to check for
+    presence.
+
+    Returns:
+        Absolute path to ``$CLAUDE_JOB_DIR/pr-converge-state.json``, or
+        ``None`` when the ``CLAUDE_JOB_DIR`` environment variable is unset
+        or empty (no single-PR pr-converge job is currently active).
+    """
+    job_directory = os.environ.get(CLAUDE_JOB_DIR_ENV_VAR, "")
+    if not job_directory:
+        return None
+    return Path(job_directory) / PR_CONVERGE_STATE_FILENAME

package/hooks/config/pr_description_enforcer_constants.py

@@ -0,0 +1,19 @@
+"""Configuration constants for the pr_description_enforcer PreToolUse hook."""
+
+import os
+import re
+
+
+_PLUGIN_ROOT: str = os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+PR_GUIDE_PATH: str = os.path.join(_PLUGIN_ROOT, "docs", "PR_DESCRIPTION_GUIDE.md")
+
+MINIMUM_SUBSTANTIVE_PROSE_CHARS: int = 40
+
+FENCED_CODE_BLOCK_PATTERN: re.Pattern[str] = re.compile(r"```.*?```", re.DOTALL)
+INLINE_CODE_PATTERN: re.Pattern[str] = re.compile(r"`[^`]*`")
+HEADING_LINE_PATTERN: re.Pattern[str] = re.compile(r"^#+[ \t].*$", re.MULTILINE)
+BOLD_PAIR_PATTERN: re.Pattern[str] = re.compile(r"\*\*([^*]+?)\*\*")
+BULLET_MARKER_PATTERN: re.Pattern[str] = re.compile(r"^\s*[-*+]\s+", re.MULTILINE)
+BLOCKQUOTE_MARKER_PATTERN: re.Pattern[str] = re.compile(r"^\s*>\s+", re.MULTILINE)
+LINK_TEXT_PATTERN: re.Pattern[str] = re.compile(r"\[([^\]]+)\]\([^)]+\)")
+WHITESPACE_RUN_PATTERN: re.Pattern[str] = re.compile(r"\s+")