claude-dev-env 1.40.0 → 1.42.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/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

@@ -1,7 +1,12 @@
 """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)

package/hooks/config/test_pr_description_enforcer_constants.py

@@ -0,0 +1,82 @@
+"""Behavior tests for pr_description_enforcer_constants module."""
+
+from __future__ import annotations
+
+import os
+import sys
+from pathlib import Path
+
+_HOOKS_ROOT = Path(__file__).resolve().parent.parent
+if str(_HOOKS_ROOT) not in sys.path:
+    sys.path.insert(0, str(_HOOKS_ROOT))
+
+from config import pr_description_enforcer_constants as constants_module
+
+
+def test_plugin_root_is_private_module_attribute() -> None:
+    assert hasattr(constants_module, "_PLUGIN_ROOT")
+    assert isinstance(constants_module._PLUGIN_ROOT, str)
+    assert os.path.isabs(constants_module._PLUGIN_ROOT)
+
+
+def test_plugin_root_public_name_is_not_exported() -> None:
+    assert not hasattr(constants_module, "PLUGIN_ROOT")
+
+
+def test_pr_guide_path_resolves_under_plugin_root_docs() -> None:
+    expected_pr_guide_path = os.path.join(
+        constants_module._PLUGIN_ROOT, "docs", "PR_DESCRIPTION_GUIDE.md"
+    )
+    assert constants_module.PR_GUIDE_PATH == expected_pr_guide_path
+
+
+def test_minimum_substantive_prose_chars_is_positive_integer() -> None:
+    assert isinstance(constants_module.MINIMUM_SUBSTANTIVE_PROSE_CHARS, int)
+    assert constants_module.MINIMUM_SUBSTANTIVE_PROSE_CHARS > 0
+
+
+def test_fenced_code_block_pattern_matches_triple_backtick_block() -> None:
+    sample_markdown = "before ```python\ncode\n``` after"
+    match = constants_module.FENCED_CODE_BLOCK_PATTERN.search(sample_markdown)
+    assert match is not None
+    assert match.group(0).startswith("```")
+    assert match.group(0).endswith("```")
+
+
+def test_inline_code_pattern_matches_single_backtick_span() -> None:
+    match = constants_module.INLINE_CODE_PATTERN.search("see `value` here")
+    assert match is not None
+    assert match.group(0) == "`value`"
+
+
+def test_heading_line_pattern_matches_atx_heading() -> None:
+    match = constants_module.HEADING_LINE_PATTERN.search("## Description\n")
+    assert match is not None
+    assert match.group(0).strip() == "## Description"
+
+
+def test_bold_pair_pattern_captures_inner_text() -> None:
+    match = constants_module.BOLD_PAIR_PATTERN.search("this is **bold** text")
+    assert match is not None
+    assert match.group(1) == "bold"
+
+
+def test_bullet_marker_pattern_strips_dash_bullet_from_line() -> None:
+    stripped_line = constants_module.BULLET_MARKER_PATTERN.sub("", "- first item")
+    assert stripped_line == "first item"
+
+
+def test_blockquote_marker_pattern_strips_quote_marker_from_line() -> None:
+    stripped_line = constants_module.BLOCKQUOTE_MARKER_PATTERN.sub("", "> quoted line")
+    assert stripped_line == "quoted line"
+
+
+def test_link_text_pattern_captures_anchor_text() -> None:
+    match = constants_module.LINK_TEXT_PATTERN.search("See [the docs](https://example.com) now")
+    assert match is not None
+    assert match.group(1) == "the docs"
+
+
+def test_whitespace_run_pattern_collapses_multiple_spaces() -> None:
+    collapsed_text = constants_module.WHITESPACE_RUN_PATTERN.sub(" ", "a   b\t\tc\n\nd")
+    assert collapsed_text == "a b c d"

package/hooks/hooks.json

@@ -124,6 +124,11 @@
             "type": "command",
             "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/windows_rmtree_blocker.py",
             "timeout": 10
+          },
+          {
+            "type": "command",
+            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/gh_pr_author_enforcer.py",
+            "timeout": 30
           }
         ]
       },
@@ -136,6 +141,26 @@
             "timeout": 10
           }
         ]
+      },
+      {
+        "matcher": "Agent",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/pr_converge_bugteam_enforcer.py",
+            "timeout": 10
+          }
+        ]
+      },
+      {
+        "matcher": "Skill",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/lifecycle/pr_converge_bugteam_skill_tracker.py",
+            "timeout": 10
+          }
+        ]
       }
     ],
     "SessionStart": [
@@ -156,6 +181,11 @@
             "type": "command",
             "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/session/untracked_repo_detector.py",
             "timeout": 10
+          },
+          {
+            "type": "command",
+            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/session/gh_pr_author_session_cleanup.py",
+            "timeout": 30
           }
         ]
       }
@@ -241,6 +271,16 @@
             "timeout": 10
           }
         ]
+      },
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/gh_pr_author_restore.py",
+            "timeout": 20
+          }
+        ]
       }
     ],
     "InstructionsLoaded": [