claude-dev-env 1.39.0 → 1.41.0

package/hooks/blocking/pr_converge_bugteam_enforcer.py

@@ -0,0 +1,170 @@
+#!/usr/bin/env python3
+"""PreToolUse hook: enforce formal bugteam Skill at Step 5 BUGTEAM ticks.
+
+The pr-converge loop's Step 5 BUGTEAM contract requires the formal
+``Skill({skill: "bugteam", args: "<PR URL>"})`` invocation per tick.
+Substituting an ad-hoc ``Agent({subagent_type: "clean-coder", ...})`` audit
+call returns a "converged" verdict without writing the artifact that
+``check_convergence.py``'s ``bugteam_clean_at`` gate reads, so the loop later
+hits ``gh pr ready`` and fails structurally with no formal review on the PR.
+
+The companion tracker hook
+(``pr_converge_bugteam_skill_tracker.py``) records every formal Skill
+invocation. This enforcer reads the recorded HEAD and tick and denies any
+clean-coder audit-shaped Agent call that has not first been preceded by the
+formal Skill at the same HEAD and tick.
+
+``qbug`` is NOT an accepted substitute; only the ``bugteam`` skill records
+the gate artifact, and the tracker deliberately ignores ``qbug`` invocations.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+from typing import TextIO
+
+
+def _insert_hooks_tree_for_imports() -> None:
+    hooks_tree = Path(__file__).resolve().parent.parent
+    hooks_tree_string = str(hooks_tree)
+    if hooks_tree_string not in sys.path:
+        sys.path.insert(0, hooks_tree_string)
+
+
+_insert_hooks_tree_for_imports()
+
+from config.pr_converge_bugteam_enforcer_constants import (
+    AGENT_TOOL_NAME,
+    ALL_AUDIT_PROMPT_SUBSTRINGS,
+    BUGTEAM_PHASE,
+    CLEAN_CODER_SUBAGENT_TYPE,
+    ENFORCER_CORRECTIVE_MESSAGE,
+    STATE_FIELD_BUGTEAM_SKILL_INVOKED_AT_HEAD,
+    STATE_FIELD_BUGTEAM_SKILL_INVOKED_AT_TICK,
+    STATE_FIELD_CURRENT_HEAD,
+    STATE_FIELD_PHASE,
+    STATE_FIELD_TICK_COUNT,
+)
+from config.pr_converge_bugteam_enforcer_state import (
+    load_state_dictionary,
+    resolve_state_path,
+)
+
+
+def _prompt_is_audit_shaped(agent_prompt: str) -> bool:
+    """Return True when the Agent prompt looks like an audit substitute.
+
+    Args:
+        agent_prompt: The ``prompt`` field of the Agent tool_input.
+
+    Returns:
+        True when any audit-shaped substring appears in the prompt
+        (case-insensitive); False for fix-only or unrelated prompts.
+    """
+    lowercased_prompt = agent_prompt.lower()
+    return any(
+        each_substring in lowercased_prompt for each_substring in ALL_AUDIT_PROMPT_SUBSTRINGS
+    )
+
+
+def _has_formal_skill_fired_this_tick(state_by_field: dict[str, object]) -> bool:
+    """Return True when the bugteam Skill registered at current HEAD and tick.
+
+    Args:
+        state_by_field: Parsed pr-converge state.json mapping each field name
+            to its recorded value.
+
+    Returns:
+        True when both ``bugteam_skill_invoked_at_head`` matches
+        ``current_head`` and ``bugteam_skill_invoked_at_tick`` matches
+        ``tick_count``; False when either is missing, stale, or carries a
+        type that violates state-schema.md (head must be ``str``, tick must
+        be a non-bool ``int``) — type-invalid values fail closed so the
+        enforcer rejects corrupted state.
+    """
+    invoked_head = state_by_field.get(STATE_FIELD_BUGTEAM_SKILL_INVOKED_AT_HEAD)
+    current_head = state_by_field.get(STATE_FIELD_CURRENT_HEAD)
+    invoked_tick = state_by_field.get(STATE_FIELD_BUGTEAM_SKILL_INVOKED_AT_TICK)
+    current_tick = state_by_field.get(STATE_FIELD_TICK_COUNT)
+    if not isinstance(invoked_head, str) or not isinstance(current_head, str):
+        return False
+    if invoked_head != current_head:
+        return False
+    if isinstance(invoked_tick, bool) or isinstance(current_tick, bool):
+        return False
+    if not isinstance(invoked_tick, int) or not isinstance(current_tick, int):
+        return False
+    return invoked_tick == current_tick
+
+
+def _should_block(payload_by_field: dict[str, object]) -> bool:
+    """Return True when the Agent call is a BUGTEAM-phase Skill substitution.
+
+    Args:
+        payload_by_field: The full PreToolUse hook payload (already JSON-parsed),
+            keyed by top-level field name.
+
+    Returns:
+        True when every gating condition holds: tool is Agent, subagent_type
+        is clean-coder, prompt is audit-shaped, pr-converge state.json exists
+        with phase BUGTEAM, and the formal bugteam Skill has NOT been
+        recorded at the current HEAD and tick. False otherwise.
+    """
+    if payload_by_field.get("tool_name", "") != AGENT_TOOL_NAME:
+        return False
+    tool_input = payload_by_field.get("tool_input", {})
+    if not isinstance(tool_input, dict):
+        return False
+    if tool_input.get("subagent_type", "") != CLEAN_CODER_SUBAGENT_TYPE:
+        return False
+    agent_prompt = tool_input.get("prompt", "")
+    if not isinstance(agent_prompt, str):
+        return False
+    if not _prompt_is_audit_shaped(agent_prompt):
+        return False
+    state_path = resolve_state_path()
+    if state_path is None:
+        return False
+    parsed_state = load_state_dictionary(state_path)
+    if parsed_state is None:
+        return False
+    if parsed_state.get(STATE_FIELD_PHASE) != BUGTEAM_PHASE:
+        return False
+    return not _has_formal_skill_fired_this_tick(parsed_state)
+
+
+def _emit_deny_payload(output_stream: TextIO) -> None:
+    """Write the PreToolUse deny payload to the provided stream.
+
+    Args:
+        output_stream: Writable text stream — production code passes
+            ``sys.stdout``; tests pass a ``StringIO`` to capture the JSON.
+    """
+    deny_payload = {
+        "hookSpecificOutput": {
+            "hookEventName": "PreToolUse",
+            "permissionDecision": "deny",
+            "permissionDecisionReason": ENFORCER_CORRECTIVE_MESSAGE,
+        }
+    }
+    output_stream.write(json.dumps(deny_payload) + "\n")
+    output_stream.flush()
+
+
+def main() -> None:
+    try:
+        hook_payload = json.load(sys.stdin)
+    except json.JSONDecodeError:
+        sys.exit(0)
+    if not isinstance(hook_payload, dict):
+        sys.exit(0)
+    if not _should_block(hook_payload):
+        sys.exit(0)
+    _emit_deny_payload(sys.stdout)
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

package/hooks/blocking/pr_description_enforcer.py

@@ -20,16 +20,28 @@ from _gh_body_arg_utils import (
     iter_significant_tokens,
 )
 
-PLUGIN_ROOT = os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
-PR_GUIDE_PATH = os.path.join(PLUGIN_ROOT, "docs", "PR_DESCRIPTION_GUIDE.md")
 
-REQUIRED_PR_SECTION_HEADERS = [
-    "description",
-    "why",
-    "how",
-]
-
-MINIMUM_PR_BODY_LENGTH = 50
+def _insert_hooks_tree_for_imports() -> None:
+    hooks_tree = Path(__file__).resolve().parent.parent
+    hooks_tree_string = str(hooks_tree)
+    if hooks_tree_string not in sys.path:
+        sys.path.insert(0, hooks_tree_string)
+
+
+_insert_hooks_tree_for_imports()
+
+from config.pr_description_enforcer_constants import (
+    BLOCKQUOTE_MARKER_PATTERN,
+    BOLD_PAIR_PATTERN,
+    BULLET_MARKER_PATTERN,
+    FENCED_CODE_BLOCK_PATTERN,
+    HEADING_LINE_PATTERN,
+    INLINE_CODE_PATTERN,
+    LINK_TEXT_PATTERN,
+    MINIMUM_SUBSTANTIVE_PROSE_CHARS,
+    PR_GUIDE_PATH,
+    WHITESPACE_RUN_PATTERN,
+)
 
 VAGUE_LANGUAGE_PATTERN = re.compile(
     r'\b(fix(?:ed)? (?:bug|issue|it)|update(?:d)? code|minor changes|various (?:fixes|updates|improvements))\b',
@@ -269,23 +281,43 @@ def extract_body_from_command(
     return result
 
 
+def _count_substantive_prose_chars(body: str) -> int:
+    """Return the count of prose characters after stripping Markdown ceremony.
+
+    Removes fenced code, inline code, heading lines, blockquote markers,
+    bullet list markers, bold/emphasis markers, and Markdown link targets.
+    Collapses internal whitespace so a body of only headers and bullets --
+    no real WHY paragraph -- registers as effectively empty.
+    """
+    body_without_fences = FENCED_CODE_BLOCK_PATTERN.sub('', body)
+    body_without_inline_code = INLINE_CODE_PATTERN.sub('', body_without_fences)
+    body_without_blockquotes = BLOCKQUOTE_MARKER_PATTERN.sub('', body_without_inline_code)
+    body_without_headings = HEADING_LINE_PATTERN.sub('', body_without_blockquotes)
+    body_without_bullets = BULLET_MARKER_PATTERN.sub('', body_without_headings)
+    body_without_bold = BOLD_PAIR_PATTERN.sub(r'\1', body_without_bullets)
+    body_without_emphasis = body_without_bold.replace('*', '')
+    body_without_links = LINK_TEXT_PATTERN.sub(r'\1', body_without_emphasis)
+    body_collapsed = WHITESPACE_RUN_PATTERN.sub(' ', body_without_links).strip()
+    return len(body_collapsed)
+
+
 def validate_pr_body(body: str) -> list[str]:
-    violations = []
-    body_lower = body.lower()
+    """Audit a PR body for substantive-prose and vague-language violations.
 
-    missing_required_sections = [
-        header for header in REQUIRED_PR_SECTION_HEADERS
-        if f"## {header}" not in body_lower and f"**{header}" not in body_lower
-    ]
+    Args:
+        body: The PR body markdown text to audit.
 
-    if missing_required_sections:
-        formatted_sections = ", ".join(f"'{each_section.title()}'" for each_section in missing_required_sections)
-        violations.append(f"Missing required section(s): {formatted_sections}")
+    Returns:
+        A list of human-readable violation messages. Empty when the body passes.
+    """
+    violations = []
 
-    stripped_body = re.sub(r'#.*', '', body).strip()
-    stripped_body = re.sub(r'\*\*.*?\*\*', '', stripped_body).strip()
-    if len(stripped_body) < MINIMUM_PR_BODY_LENGTH:
-        violations.append("PR body too short -- provide meaningful context for reviewers")
+    substantive_chars = _count_substantive_prose_chars(body)
+    if substantive_chars < MINIMUM_SUBSTANTIVE_PROSE_CHARS:
+        violations.append(
+            "PR body lacks substantive prose -- include a Why paragraph or "
+            "substantive explanation, not only headers and bullets"
+        )
 
     vague_matches = VAGUE_LANGUAGE_PATTERN.findall(body)
     if vague_matches:
@@ -329,7 +361,8 @@ def main() -> None:
         pr_guide_reference = f" @{PR_GUIDE_PATH}" if os.path.exists(PR_GUIDE_PATH) else ""
         denial_reason = (
             f"BLOCKED: [PR_DESCRIPTION] {violation_list}. "
-            f"Follow the PR description guide:{pr_guide_reference}"
+            f"Use the pr-description-writer agent to author the body in Anthropic claude-code style. "
+            f"Guide:{pr_guide_reference}"
         )
         result = {
             "hookSpecificOutput": {

package/hooks/blocking/test_gh_body_arg_blocker.py

@@ -401,10 +401,15 @@ def test_has_backtick_bash_continuation_stripped() -> None:
     assert not _has_backtick(command)
 
 
-def test_has_backtick_powershell_continuation_stripped() -> None:
-    """PowerShell backtick line continuations are stripped before checking."""
+def test_has_backtick_powershell_continuation_not_stripped_in_bash_context() -> None:
+    """PowerShell backtick continuations are real backticks under the Bash tool.
+
+    The hook runs on Bash tool invocations where PowerShell-style backtick
+    continuations are not continuation markers. Any backtick character in
+    the command is a literal backtick that must be detected.
+    """
     command = 'gh pr create `\n  --title "T" `\n  --body "bugbot run"\n'
-    assert not _has_backtick(command)
+    assert _has_backtick(command)
 
 
 def test_has_backtick_content_backtick_at_line_end() -> None:
@@ -418,3 +423,20 @@ def test_has_backtick_multi_line_body() -> None:
     command = 'gh pr create --title "T" --body "First line.\nSecond with `code`."'
     assert _has_backtick(command)
 
+
+def test_has_backtick_inside_unclosed_double_quoted_body_value() -> None:
+    """Trailing backtick inside an unclosed --body "..." opening line counts as body content.
+
+    The first line carries an opening double-quote for --body that is not
+    closed on that line (odd quote count = 3). The trailing backtick is body
+    content (an inline-code opening), not a PowerShell continuation marker.
+    The unclosed-quote check preserves the original line including its
+    trailing backtick, so _has_backtick sees the backtick and returns True.
+    """
+    command = (
+        'gh pr create --title "T" --body "Thanks `\n'
+        '  this continues the body\n'
+        '  with more text"\n'
+    )
+    assert _has_backtick(command)
+