claude-dev-env 1.38.1 → 1.40.0

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

@@ -0,0 +1,22 @@
+"""Shared CLI utilities for pr-loop scripts."""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+
+def require_file(file_path: Path, label: str) -> int | None:
+    """Verify a required file exists, returning an exit code when absent.
+
+    Args:
+        file_path: Path to the required file.
+        label: Human-readable label for the error message.
+
+    Returns:
+        None when the file exists (caller continues), or 1 when absent.
+    """
+    if not file_path.is_file():
+        print(f"{label} not found: {file_path}", file=sys.stderr)
+        return 1
+    return None

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

@@ -0,0 +1,165 @@
+"""Canonical path resolution for pr-loop skills (bugteam, qbug, findbugs, fixbugs).
+
+Single source of truth for all path patterns — when a path changes, only this
+file is edited. Pure functions with no side effects.
+"""
+
+from __future__ import annotations
+
+import tempfile
+from pathlib import Path
+
+from config.path_resolver_constants import (
+    DIFF_PATCH_TEMPLATE,
+    FIX_OUTCOME_XML_TEMPLATE,
+    MULTI_PR_SLUG_TEMPLATE,
+    OUTCOME_XML_TEMPLATE,
+    PER_PR_WORKSPACE_TEMPLATE,
+    RUN_NAME_TEMPLATE_MULTI,
+    RUN_NAME_TEMPLATE_SINGLE,
+    SLUGIFY_REPLACEMENT,
+    SLUGIFY_SAFE_CHARS,
+    WORKTREE_DIRNAME,
+)
+
+
+def sanitize_branch_name(head_branch: str) -> str:
+    """Replace filesystem-unsafe characters in a git branch name.
+
+    Args:
+        head_branch: Raw git branch name (e.g. 'feat/my-branch').
+
+    Returns:
+        Sanitized string safe for use in directory names.
+    """
+    return SLUGIFY_SAFE_CHARS.sub(SLUGIFY_REPLACEMENT, head_branch)
+
+
+def build_run_name(pr_number: int, head_branch: str, *, is_multi_pr: bool) -> str:
+    """Build the run_name directory token for a single or multi-PR run.
+
+    Args:
+        pr_number: Pull request number.
+        head_branch: Head branch ref (used for multi-PR naming).
+        is_multi_pr: True when the run spans multiple PRs.
+
+    Returns:
+        Run name string (e.g. 'bugteam-pr-422' or 'bugteam-feat-my-branch').
+    """
+    if is_multi_pr:
+        return RUN_NAME_TEMPLATE_MULTI.format(
+            sanitized_branch=sanitize_branch_name(head_branch),
+        )
+    return RUN_NAME_TEMPLATE_SINGLE.format(number=pr_number)
+
+
+def resolve_run_temp_dir(run_name: str) -> Path:
+    """Resolve the temporary directory for a given run name.
+
+    Args:
+        run_name: Run name token (from build_run_name).
+
+    Returns:
+        Absolute path to the run's temp directory.
+    """
+    return Path(tempfile.gettempdir()) / run_name
+
+
+def slugify_pr_identity(owner: str, repo: str, pr_number: int) -> str:
+    """Generate a slugified identity token for a PR.
+
+    Used as a subdirectory name under the run temp dir in multi-PR scenarios.
+
+    Args:
+        owner: GitHub repository owner.
+        repo: GitHub repository name.
+        pr_number: Pull request number.
+
+    Returns:
+        Slugified token (e.g. 'jl-cmd-claude-code-config-pr-422').
+    """
+    return MULTI_PR_SLUG_TEMPLATE.format(owner=owner, repo=repo, number=pr_number)
+
+
+def per_pr_workspace(
+    run_temp_dir: Path, owner: str, repo: str, pr_number: int
+) -> dict[str, object]:
+    """Build the per-PR workspace paths dict.
+
+    Args:
+        run_temp_dir: Run temp directory (from resolve_run_temp_dir).
+        owner: GitHub repository owner.
+        repo: GitHub repository name.
+        pr_number: Pull request number.
+
+    Returns:
+        Dict with keys:
+          - worktree: Path to the git worktree checkout
+          - diff_patch_template: str template with {loop} placeholder
+          - outcome_xml_template: str template with {number} and {loop} placeholders
+          - fix_outcome_xml_template: str template with {number} and {loop} placeholders
+    """
+    pr_workspace_dir = run_temp_dir / PER_PR_WORKSPACE_TEMPLATE.format(number=pr_number)
+    slug = slugify_pr_identity(owner, repo, pr_number)
+    return {
+        "worktree": pr_workspace_dir / WORKTREE_DIRNAME,
+        "diff_patch_template": str(pr_workspace_dir / slug / DIFF_PATCH_TEMPLATE),
+        "outcome_xml_template": OUTCOME_XML_TEMPLATE,
+        "fix_outcome_xml_template": FIX_OUTCOME_XML_TEMPLATE,
+    }
+
+
+def outcome_xml_path(worktree_path: Path, pr_number: int, loop_number: int) -> Path:
+    """Construct the canonical path for an AUDIT outcome XML file.
+
+    Args:
+        worktree_path: Path to the git worktree (from per_pr_workspace).
+        pr_number: Pull request number.
+        loop_number: Current loop iteration.
+
+    Returns:
+        Absolute path (e.g. '<worktree>/.bugteam-pr422-loop3.outcomes.xml').
+    """
+    return worktree_path / OUTCOME_XML_TEMPLATE.format(
+        number=pr_number, loop=loop_number
+    )
+
+
+def fix_outcome_xml_path(worktree_path: Path, pr_number: int, loop_number: int) -> Path:
+    """Construct the canonical path for a FIX outcome XML file.
+
+    Args:
+        worktree_path: Path to the git worktree (from per_pr_workspace).
+        pr_number: Pull request number.
+        loop_number: Current loop iteration.
+
+    Returns:
+        Absolute path (e.g. '<worktree>/.bugteam-pr422-loop3.fix-outcomes.xml').
+    """
+    return worktree_path / FIX_OUTCOME_XML_TEMPLATE.format(
+        number=pr_number, loop=loop_number
+    )
+
+
+def diff_patch_path(
+    run_temp_dir: Path,
+    owner: str,
+    repo: str,
+    pr_number: int,
+    loop_number: int,
+) -> Path:
+    """Construct the path for a diff/patch file.
+
+    Args:
+        run_temp_dir: Run temp directory (from resolve_run_temp_dir).
+        owner: GitHub repository owner.
+        repo: GitHub repository name.
+        pr_number: Pull request number.
+        loop_number: Current loop iteration.
+
+    Returns:
+        Absolute path (e.g. '<run_temp>/jl-cmd-claude-code-config-pr-422/loop-3.patch').
+    """
+    slug = slugify_pr_identity(owner, repo, pr_number)
+    filename = DIFF_PATCH_TEMPLATE.format(loop=loop_number)
+    return run_temp_dir / slug / filename

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

@@ -0,0 +1,20 @@
+"""Shared XML utilities for pr-loop scripts."""
+
+from __future__ import annotations
+
+from xml.dom import minidom
+from xml.etree.ElementTree import Element, tostring
+
+
+def emit_pretty_xml(root: Element) -> str:
+    """Serialize an ElementTree to a pretty-printed XML string.
+
+    Args:
+        root: Root XML element.
+
+    Returns:
+        Pretty-printed XML string.
+    """
+    raw_text = tostring(root, encoding="unicode")
+    reparsed_dom = minidom.parseString(raw_text)
+    return reparsed_dom.toprettyxml(indent="  ")

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

@@ -0,0 +1,182 @@
+"""Emit the complete AUDIT spawn prompt XML to stdout.
+
+Substitutes <context>, <scope>, <bug_categories>, <constraints>,
+<comment_posting>, and <output_format> blocks from CLI args.
+
+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>
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from xml.etree.ElementTree import Element, SubElement
+from pathlib import Path
+
+_self_dir = Path(__file__).resolve().parent
+if str(_self_dir) not in sys.path:
+    sys.path.insert(0, str(_self_dir))
+
+from _xml_utils import emit_pretty_xml
+from config.path_resolver_constants import (
+    ALL_AUDIT_CATEGORY_ENTRIES,
+    ALL_AUDIT_CONSTRAINT_TEXTS,
+)
+
+
+def build_audit_prompt_xml(
+    *,
+    owner: str,
+    repo: str,
+    pr_number: int,
+    loop: int,
+    head_ref: str,
+    base_ref: str,
+    worktree_path: Path,
+    run_temp_dir: Path,
+) -> Element:
+    """Build the complete AUDIT spawn prompt XML.
+
+    Args:
+        owner: GitHub repository owner.
+        repo: GitHub repository name.
+        pr_number: Pull request number.
+        loop: Loop iteration number.
+        head_ref: Head branch ref.
+        base_ref: Base branch ref.
+        worktree_path: Path to the git worktree.
+        run_temp_dir: Path to the run temp directory.
+
+    Returns:
+        Root <spawn_prompt> element.
+    """
+    root = Element("spawn_prompt", {"role": "audit", "loop": str(loop)})
+
+    context = SubElement(root, "context")
+    SubElement(context, "owner").text = owner
+    SubElement(context, "repo").text = repo
+    SubElement(context, "pr_number").text = str(pr_number)
+    SubElement(context, "head_ref").text = head_ref
+    SubElement(context, "base_ref").text = base_ref
+    SubElement(context, "worktree_path").text = str(worktree_path)
+    SubElement(context, "run_temp_dir").text = str(run_temp_dir)
+
+    scope = SubElement(root, "scope")
+    scope.text = (
+        f"Audit the full diff of {owner}/{repo}#{pr_number} "
+        f"({head_ref} against {base_ref}) for CODE_RULES violations, "
+        f"bugs, and anti-patterns. Work in {worktree_path}."
+    )
+
+    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})
+        cat_elem.text = each_category_label
+
+    constraints = SubElement(root, "constraints")
+    for each_constraint in ALL_AUDIT_CONSTRAINT_TEXTS:
+        SubElement(constraints, "constraint").text = each_constraint
+
+    comment_posting = SubElement(root, "comment_posting")
+    comment_posting.text = (
+        "Post findings as inline review comments on the PR via "
+        "the GitHub MCP add_comment_to_pending_review tool. "
+        "Group related findings into a single pending review."
+    )
+
+    output_format = SubElement(root, "output_format")
+    output_format.text = (
+        "Emit findings as JSON array of objects with keys: "
+        "severity (P0/P1/P2), file, line, category, message, suggestion."
+    )
+
+    return root
+
+
+def emit_audit_prompt(
+    *,
+    owner: str,
+    repo: str,
+    pr_number: int,
+    loop: int,
+    head_ref: str,
+    base_ref: str,
+    worktree_path: Path,
+    run_temp_dir: Path,
+) -> str:
+    """Build and serialize the AUDIT spawn prompt to a pretty-printed XML string.
+
+    Args:
+        owner: GitHub repository owner.
+        repo: GitHub repository name.
+        pr_number: Pull request number.
+        loop: Loop iteration number.
+        head_ref: Head branch ref.
+        base_ref: Base branch ref.
+        worktree_path: Path to the git worktree.
+        run_temp_dir: Path to the run temp directory.
+
+    Returns:
+        Pretty-printed XML string.
+    """
+    root = build_audit_prompt_xml(
+        owner=owner,
+        repo=repo,
+        pr_number=pr_number,
+        loop=loop,
+        head_ref=head_ref,
+        base_ref=base_ref,
+        worktree_path=worktree_path,
+        run_temp_dir=run_temp_dir,
+    )
+    return emit_pretty_xml(root)
+
+
+def parse_arguments(all_argv: list[str]) -> argparse.Namespace:
+    """Parse command-line arguments.
+
+    Args:
+        all_argv: Command-line argument list.
+
+    Returns:
+        Parsed namespace with all required audit prompt parameters.
+    """
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--owner", required=True)
+    parser.add_argument("--repo", required=True)
+    parser.add_argument("--pr-number", type=int, required=True)
+    parser.add_argument("--loop", type=int, required=True)
+    parser.add_argument("--head-ref", required=True)
+    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)
+    return parser.parse_args(all_argv)
+
+
+def main(all_arguments: list[str]) -> int:
+    """Entry point: emit AUDIT spawn prompt XML to stdout.
+
+    Args:
+        all_arguments: Command-line arguments.
+
+    Returns:
+        0 on success.
+    """
+    arguments = parse_arguments(all_arguments)
+    xml_output = emit_audit_prompt(
+        owner=arguments.owner,
+        repo=arguments.repo,
+        pr_number=getattr(arguments, "pr_number"),
+        loop=arguments.loop,
+        head_ref=getattr(arguments, "head_ref"),
+        base_ref=getattr(arguments, "base_ref"),
+        worktree_path=getattr(arguments, "worktree_path"),
+        run_temp_dir=getattr(arguments, "run_temp_dir"),
+    )
+    sys.stdout.write(xml_output)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))

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

@@ -0,0 +1,185 @@
+"""Emit the complete FIX spawn prompt XML to stdout.
+
+Populates <bug> entries from findings JSON, plus <execution> checklist
+and <constraints>.
+
+Usage:
+  python scripts/build_fix_prompt.py --owner jl-cmd --repo claude-code-config --pr-number 422 --loop 1 --head-ref feat/branch --base-ref main --worktree-path <PATH> --findings-json <PATH>
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from xml.etree.ElementTree import Element, SubElement
+from pathlib import Path
+
+_self_dir = Path(__file__).resolve().parent
+if str(_self_dir) not in sys.path:
+    sys.path.insert(0, str(_self_dir))
+
+from _cli_utils import require_file
+from _xml_utils import emit_pretty_xml
+from config.path_resolver_constants import (
+    ALL_FIX_CONSTRAINT_TEXTS,
+    ALL_FIX_EXECUTION_STEPS,
+)
+
+
+def build_fix_prompt_xml(
+    *,
+    owner: str,
+    repo: str,
+    pr_number: int,
+    loop: int,
+    head_ref: str,
+    base_ref: str,
+    worktree_path: Path,
+    findings_json_path: Path,
+) -> Element:
+    """Build the complete FIX spawn prompt XML.
+
+    Args:
+        owner: GitHub repository owner.
+        repo: GitHub repository name.
+        pr_number: Pull request number.
+        loop: Loop iteration number.
+        head_ref: Head branch ref.
+        base_ref: Base branch ref.
+        worktree_path: Path to the git worktree.
+        findings_json_path: Path to the findings JSON file.
+
+    Returns:
+        Root <spawn_prompt> element.
+    """
+    findings_data = json.loads(findings_json_path.read_text(encoding="utf-8"))
+
+    root = Element("spawn_prompt", {"role": "fix", "loop": str(loop)})
+
+    context = SubElement(root, "context")
+    SubElement(context, "owner").text = owner
+    SubElement(context, "repo").text = repo
+    SubElement(context, "pr_number").text = str(pr_number)
+    SubElement(context, "head_ref").text = head_ref
+    SubElement(context, "base_ref").text = base_ref
+    SubElement(context, "worktree_path").text = str(worktree_path)
+
+    bugs_elem = SubElement(root, "bugs")
+    if isinstance(findings_data, list):
+        for each_finding in findings_data:
+            if isinstance(each_finding, dict):
+                bug = SubElement(bugs_elem, "bug")
+                for each_key, each_field_detail in each_finding.items():
+                    child = SubElement(bug, each_key)
+                    child.text = (
+                        str(each_field_detail) if each_field_detail is not None else ""
+                    )
+
+    execution = SubElement(root, "execution")
+    for each_step in ALL_FIX_EXECUTION_STEPS:
+        SubElement(execution, "step").text = each_step
+
+    constraints = SubElement(root, "constraints")
+    for each_constraint in ALL_FIX_CONSTRAINT_TEXTS:
+        SubElement(constraints, "constraint").text = each_constraint
+
+    return root
+
+
+def emit_fix_prompt(
+    *,
+    owner: str,
+    repo: str,
+    pr_number: int,
+    loop: int,
+    head_ref: str,
+    base_ref: str,
+    worktree_path: Path,
+    findings_json_path: Path,
+) -> str:
+    """Build and serialize the FIX spawn prompt to a pretty-printed XML string.
+
+    Args:
+        owner: GitHub repository owner.
+        repo: GitHub repository name.
+        pr_number: Pull request number.
+        loop: Loop iteration number.
+        head_ref: Head branch ref.
+        base_ref: Base branch ref.
+        worktree_path: Path to the git worktree.
+        findings_json_path: Path to the findings JSON file.
+
+    Returns:
+        Pretty-printed XML string.
+    """
+    root = build_fix_prompt_xml(
+        owner=owner,
+        repo=repo,
+        pr_number=pr_number,
+        loop=loop,
+        head_ref=head_ref,
+        base_ref=base_ref,
+        worktree_path=worktree_path,
+        findings_json_path=findings_json_path,
+    )
+    return emit_pretty_xml(root)
+
+
+def parse_arguments(all_argv: list[str]) -> argparse.Namespace:
+    """Parse command-line arguments.
+
+    Args:
+        all_argv: Command-line argument list.
+
+    Returns:
+        Parsed namespace with all required fix prompt parameters.
+    """
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--owner", required=True)
+    parser.add_argument("--repo", required=True)
+    parser.add_argument("--pr-number", type=int, required=True)
+    parser.add_argument("--loop", type=int, required=True)
+    parser.add_argument("--head-ref", required=True)
+    parser.add_argument("--base-ref", required=True)
+    parser.add_argument("--worktree-path", type=Path, required=True)
+    parser.add_argument("--findings-json", type=Path, required=True)
+    return parser.parse_args(all_argv)
+
+
+def main(all_arguments: list[str]) -> int:
+    """Entry point: emit FIX spawn prompt XML to stdout.
+
+    Args:
+        all_arguments: Command-line arguments.
+
+    Returns:
+        0 on success, 1 on failure.
+    """
+    arguments = parse_arguments(all_arguments)
+    findings_path = getattr(arguments, "findings_json")
+
+    early_exit = require_file(findings_path, "findings-json")
+    if early_exit is not None:
+        return early_exit
+
+    try:
+        xml_output = emit_fix_prompt(
+            owner=arguments.owner,
+            repo=arguments.repo,
+            pr_number=getattr(arguments, "pr_number"),
+            loop=arguments.loop,
+            head_ref=getattr(arguments, "head_ref"),
+            base_ref=getattr(arguments, "base_ref"),
+            worktree_path=getattr(arguments, "worktree_path"),
+            findings_json_path=findings_path,
+        )
+    except (json.JSONDecodeError, OSError) as exc:
+        print(f"emit_fix_prompt failed: {exc}", file=sys.stderr)
+        return 1
+    sys.stdout.write(xml_output)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))

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

@@ -0,0 +1,78 @@
+"""Path template constants for the bugteam / pr-loop shared scripts."""
+
+import re
+
+RUN_NAME_TEMPLATE_SINGLE = "bugteam-pr-{number}"
+RUN_NAME_TEMPLATE_MULTI = "bugteam-{sanitized_branch}"
+PER_PR_WORKSPACE_TEMPLATE = "pr-{number}"
+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}"
+LOOP_STATE_JSON_INDENT = 2
+ALL_VALID_FIX_STATUSES = frozenset({
+    "fixed",
+    "could_not_address",
+    "hook_blocked",
+    "unverified_fixed",
+})
+
+ALL_AUDIT_CONSTRAINT_TEXTS = [
+    "Work exclusively within the worktree directory.",
+    "Every finding must cite file:line.",
+    "Document each finding with severity, file, line, and suggested fix.",
+    "Read each file in the diff before reporting on it.",
+]
+
+ALL_AUDIT_CATEGORY_ENTRIES = [
+    ("A", "Documentation / API call accuracy"),
+    ("B", "Type safety / boundary types"),
+    ("C", "Magic values / hardcoded constants"),
+    ("D", "Naming / banned identifiers"),
+    ("E", "Orphans / dead code"),
+    ("F", "Error handling / bare except"),
+    ("G", "Bounds / silent cap exits"),
+    ("H", "Testing / test quality"),
+    ("I", "Control flow / logic errors"),
+    ("J", "Architecture / SOLID violations"),
+    ("K", "Codebase conflicts / DRY"),
+]
+
+ALL_FIX_EXECUTION_STEPS = [
+    "Read the finding and verify it against the current file at file:line.",
+    "Write a failing test that reproduces the bug.",
+    "Implement the smallest change that resolves the finding.",
+    "Run the full test suite — confirm the new test and all existing tests pass.",
+    "Stage and commit the fix with a descriptive message.",
+    "Push the commit to the head branch.",
+    "Post an inline reply on the finding thread confirming the fix.",
+]
+
+ALL_FIX_CONSTRAINT_TEXTS = [
+    "Work exclusively within the worktree directory.",
+    "Change only the lines directly related to each finding.",
+    "Create one commit per fix loop, each focused on a single category of findings.",
+    "Every fix must have a corresponding test.",
+    "Remove deprecated code directly and update all call sites.",
+    "Handle each error case with a named exception type.",
+]
+
+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, ...] = (
+    "title",
+    "excerpt",
+    "description",
+)
+
+ALL_FIX_OUTCOME_BODY_ELEMENT_KEYS: tuple[str, ...] = (
+    "reason",
+    "hook_output",
+)