claude-dev-env 1.38.1 → 1.40.0

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

@@ -0,0 +1,135 @@
+"""Create a loop-state.json file for a bugteam run.
+
+Usage:
+  python scripts/init_loop_state.py --pr-number 422 --head-ref feat/branch --starting-sha abc1234 [--is-multi-pr]
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+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 _path_resolver import (
+    build_run_name,
+    per_pr_workspace,
+    resolve_run_temp_dir,
+)
+from config.path_resolver_constants import LOOP_STATE_JSON_INDENT
+
+
+def create_loop_state(
+    *,
+    pr_number: int,
+    head_ref: str,
+    starting_sha: str,
+    is_multi_pr: bool = False,
+) -> Path:
+    """Create the loop-state.json file and return its path.
+
+    The written state dict carries the subset of the keys documented
+    in `_shared/pr-loop/state-schema.md` common-fields table that are
+    initialized at loop creation. Fields populated only during the loop
+    (e.g. `audit_log`) are added by later steps and are not written
+    here:
+
+      - `loop_count: 0` (int counter, bumps on each AUDIT or tick)
+      - `last_action: "fresh"` (enum: fresh | audited | fixed)
+      - `last_findings: {p0: 0, p1: 0, p2: 0, total: 0}` (count dict
+        populated by AUDIT)
+      - `starting_sha: <str>` (the SHA passed in)
+      - `loop_comment_index: {}` (dict keyed by finding_id; AUDIT
+        populates `finding_comment_id`, `finding_comment_url`, and
+        `thread_node_id` per entry when it posts the per-loop review,
+        and FIX sets `fix_status` when its commit lands)
+
+    Args:
+        pr_number: Pull request number.
+        head_ref: Head branch ref.
+        starting_sha: Starting commit SHA.
+        is_multi_pr: Whether multi-PR mode is active.
+
+    Returns:
+        Path to the created loop-state.json file.
+    """
+    run_name = build_run_name(pr_number, head_ref, is_multi_pr=is_multi_pr)
+    run_temp_dir = resolve_run_temp_dir(run_name)
+    workspace = per_pr_workspace(run_temp_dir, "", "", pr_number)
+    worktree_path = workspace["worktree"]
+    assert isinstance(worktree_path, Path)
+
+    worktree_path.mkdir(parents=True, exist_ok=True)
+    state_path = worktree_path / "loop-state.json"
+
+    state = {
+        "loop_count": 0,
+        "last_action": "fresh",
+        "last_findings": {"p0": 0, "p1": 0, "p2": 0, "total": 0},
+        "starting_sha": starting_sha,
+        "loop_comment_index": {},
+    }
+
+    state_path.write_text(
+        json.dumps(state, indent=LOOP_STATE_JSON_INDENT) + "\n",
+        encoding="utf-8",
+    )
+    return state_path
+
+
+def parse_arguments(all_argv: list[str]) -> argparse.Namespace:
+    """Parse command-line arguments.
+
+    Args:
+        all_argv: Command-line argument list.
+
+    Returns:
+        Parsed namespace with pr_number, head_ref, starting_sha, and is_multi_pr.
+    """
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--pr-number", type=int, required=True)
+    parser.add_argument("--head-ref", required=True)
+    parser.add_argument("--starting-sha", required=True)
+    parser.add_argument(
+        "--is-multi-pr",
+        action="store_true",
+        default=False,
+    )
+    return parser.parse_args(all_argv)
+
+
+def main(
+    all_arguments: list[str], *, is_multi_pr: bool | None = None
+) -> int:
+    """Entry point: create loop-state.json and print its path.
+
+    Args:
+        all_arguments: Command-line arguments.
+        is_multi_pr: Override for multi-PR mode (default: from CLI).
+
+    Returns:
+        0 on success.
+    """
+    arguments = parse_arguments(all_arguments)
+    if arguments.starting_sha is None:
+        return 1
+    state_path = create_loop_state(
+        pr_number=getattr(arguments, "pr_number"),
+        head_ref=getattr(arguments, "head_ref"),
+        starting_sha=arguments.starting_sha,
+        is_multi_pr=(
+            arguments.is_multi_pr if is_multi_pr is None else is_multi_pr
+        ),
+    )
+    print(state_path)
+    return 0
+
+
+if __name__ == "__main__":
+    all_argv = sys.argv[1:]
+    arguments = parse_arguments(all_argv)
+    raise SystemExit(main(all_argv, is_multi_pr=arguments.is_multi_pr))

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

@@ -0,0 +1,175 @@
+"""Remove git worktrees and run temp directories for a bugteam run.
+
+Usage:
+  python scripts/teardown_worktrees.py --run-temp-dir <PATH> --all-pr-jsons <JSON>
+
+The JSON array must contain objects with keys: number, owner, repo.
+Tolerates already-removed worktrees and missing directories.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import shutil
+import stat
+import subprocess
+import sys
+from collections.abc import Callable
+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 _path_resolver import per_pr_workspace
+from config.path_resolver_constants import ALL_PYTHON_ONEXC_VERSION
+
+
+def _remove_readonly_attribute(
+    removal_function: Callable[[str], None],
+    target_path: str,
+    *_exc_info: object,
+) -> None:
+    """Windows-safe handler: strip ReadOnly attribute and retry the syscall.
+
+    Args:
+        removal_function: The syscall that failed (os.unlink or os.rmdir).
+        target_path: Path to the file or directory that triggered the error.
+        *_exc_info: Exception information (collapses onerror/onexc signature difference).
+    """
+    try:
+        os.chmod(target_path, stat.S_IWRITE)
+        removal_function(target_path)
+    except OSError:
+        pass
+
+
+def force_rmtree(target_path: str) -> None:
+    """Remove a directory tree, handling Windows ReadOnly attribute.
+
+    Args:
+        target_path: Path to the directory tree to remove.
+    """
+    handler_kw: dict[str, object] = (
+        {"onexc": _remove_readonly_attribute}
+        if sys.version_info >= ALL_PYTHON_ONEXC_VERSION
+        else {"onerror": _remove_readonly_attribute}
+    )
+    try:
+        shutil.rmtree(target_path, **handler_kw)
+    except OSError:
+        pass
+
+
+def remove_worktree(worktree_path: Path) -> bool:
+    """Remove a single git worktree via `git worktree remove`.
+
+    Args:
+        worktree_path: Path to the worktree directory.
+
+    Returns:
+        True when the worktree was registered and removed, False when
+        it was already absent or unregistered.
+    """
+    if not worktree_path.exists():
+        return False
+    completed_process = subprocess.run(
+        ["git", "worktree", "remove", str(worktree_path)],
+        capture_output=True,
+        text=True,
+        encoding="utf-8",
+        errors="replace",
+        check=False,
+    )
+    if completed_process.returncode != 0:
+        stderr_text = completed_process.stderr or ""
+        if "not a working tree" in stderr_text.lower():
+            force_rmtree(str(worktree_path))
+            return False
+        print(
+            f"git worktree remove failed for {worktree_path}: {stderr_text}",
+            file=sys.stderr,
+        )
+        return False
+    return True
+
+
+def teardown_run(
+    *,
+    run_temp_dir: Path,
+    all_pr_entries: list[dict[str, object]],
+) -> int:
+    """Remove all worktrees and the run temp directory.
+
+    Args:
+        run_temp_dir: Path to the run's temp directory.
+        all_pr_entries: List of dicts with number, owner, and repo keys.
+
+    Returns:
+        Count of worktrees successfully removed via git.
+    """
+    removed_count = 0
+    for each_entry in all_pr_entries:
+        pr_number = each_entry.get("number")
+        owner = each_entry.get("owner", "")
+        repo = each_entry.get("repo", "")
+        if not isinstance(pr_number, int):
+            continue
+        workspace = per_pr_workspace(run_temp_dir, str(owner), str(repo), pr_number)
+        worktree_path = workspace["worktree"]
+        if not isinstance(worktree_path, Path):
+            continue
+        if remove_worktree(worktree_path):
+            removed_count += 1
+
+    force_rmtree(str(run_temp_dir))
+    return removed_count
+
+
+def parse_arguments(all_argv: list[str]) -> argparse.Namespace:
+    """Parse command-line arguments.
+
+    Args:
+        all_argv: Command-line argument list.
+
+    Returns:
+        Parsed namespace with run_temp_dir and all_pr_jsons.
+    """
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--run-temp-dir", type=Path, required=True)
+    parser.add_argument("--all-pr-jsons", required=True)
+    return parser.parse_args(all_argv)
+
+
+def main(all_arguments: list[str]) -> int:
+    """Entry point: remove worktrees and temp directory.
+
+    Args:
+        all_arguments: Command-line arguments.
+
+    Returns:
+        0 on success, 1 on JSON parse failure.
+    """
+    arguments = parse_arguments(all_arguments)
+    run_temp_dir = getattr(arguments, "run_temp_dir")
+    try:
+        all_pr_entries = json.loads(getattr(arguments, "all_pr_jsons"))
+    except json.JSONDecodeError as exc:
+        print(f"Invalid JSON for --all-pr-jsons: {exc}", file=sys.stderr)
+        return 1
+    if not isinstance(all_pr_entries, list):
+        print("--all-pr-jsons must be a JSON array", file=sys.stderr)
+        return 1
+
+    removed_count = teardown_run(
+        run_temp_dir=run_temp_dir,
+        all_pr_entries=all_pr_entries,
+    )
+    print(f"Removed {removed_count} worktree(s), cleaned {run_temp_dir}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))

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

@@ -0,0 +1,182 @@
+"""Validate Shape A/B contract and write <bugteam_audit> XML at the canonical path.
+
+Usage:
+  python scripts/write_audit_outcomes.py --pr-number 422 --loop 3 --review-url <URL> --findings-json <PATH> --worktree-path <PATH>
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from xml.etree.ElementTree import Element, SubElement
+
+_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 _path_resolver import outcome_xml_path
+from _xml_utils import emit_pretty_xml
+from config.path_resolver_constants import ALL_FINDING_BODY_ELEMENT_KEYS
+
+
+def build_audit_xml(
+    *,
+    pr_number: int,
+    loop: int,
+    review_url: str,
+    findings_json_path: Path,
+) -> Element:
+    """Build the <bugteam_audit> XML element from findings data.
+
+    Args:
+        pr_number: Pull request number.
+        loop: Loop iteration number.
+        review_url: URL of the GitHub review.
+        findings_json_path: Path to the findings JSON file.
+
+    Returns:
+        Root <bugteam_audit> element.
+
+    Raises:
+        SystemExit: When findings-json is not a JSON array of objects.
+    """
+    findings_data = json.loads(findings_json_path.read_text(encoding="utf-8"))
+    if not isinstance(findings_data, list):
+        print("findings-json must contain a JSON array", file=sys.stderr)
+        raise SystemExit(1)
+    for each_index, each_finding in enumerate(findings_data):
+        if not isinstance(each_finding, dict):
+            print(
+                f"findings-json[{each_index}]: each entry must be a JSON object",
+                file=sys.stderr,
+            )
+            raise SystemExit(1)
+    root = Element("bugteam_audit", {
+        "pr": str(pr_number),
+        "loop": str(loop),
+        "review_url": review_url,
+    })
+
+    findings_elem = SubElement(root, "findings")
+    _populate_findings(findings_elem, findings_data)
+    return root
+
+
+def _populate_findings(parent: Element, findings_data: list[dict[str, object]]) -> None:
+    """Populate <finding> elements from a validated list of finding dicts.
+
+    Scalar finding fields become XML attributes on `<finding>`; the
+    body fields named in `ALL_FINDING_BODY_ELEMENT_KEYS` (defined in
+    `config/path_resolver_constants.py` and currently
+    `("title", "excerpt", "description")`) become child elements.
+    Nested dicts or lists in scalar slots are flattened to string form
+    so attribute serialization stays well-defined.
+
+    Args:
+        parent: Parent XML element (typically `<findings>`).
+        findings_data: Validated list of finding dicts (caller must have
+            confirmed each entry is a dict via the build_audit_xml gate).
+    """
+    all_finding_body_element_keys = ALL_FINDING_BODY_ELEMENT_KEYS
+    for each_finding in findings_data:
+        finding_elem = SubElement(parent, "finding")
+        for each_key, each_field_detail in each_finding.items():
+            field_text = (
+                str(each_field_detail) if each_field_detail is not None else ""
+            )
+            if each_key in all_finding_body_element_keys:
+                child = SubElement(finding_elem, each_key)
+                child.text = field_text
+            else:
+                finding_elem.set(each_key, field_text)
+
+
+def write_audit_xml(
+    *,
+    pr_number: int,
+    loop: int,
+    review_url: str,
+    findings_json_path: Path,
+    worktree_path: Path,
+) -> Path:
+    """Write the <bugteam_audit> XML to the canonical outcome path.
+
+    Args:
+        pr_number: Pull request number.
+        loop: Loop iteration number.
+        review_url: URL of the GitHub review.
+        findings_json_path: Path to the findings JSON file.
+        worktree_path: Path to the git worktree.
+
+    Returns:
+        Path to the written XML file.
+    """
+    root = build_audit_xml(
+        pr_number=pr_number,
+        loop=loop,
+        review_url=review_url,
+        findings_json_path=findings_json_path,
+    )
+    xml_string = emit_pretty_xml(root)
+
+    output_path = outcome_xml_path(worktree_path, pr_number, loop)
+    output_path.write_text(xml_string, encoding="utf-8")
+    return output_path
+
+
+def parse_arguments(all_argv: list[str]) -> argparse.Namespace:
+    """Parse command-line arguments.
+
+    Args:
+        all_argv: Command-line argument list.
+
+    Returns:
+        Parsed namespace with pr_number, loop, review_url, findings_json, and worktree_path.
+    """
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--pr-number", type=int, required=True)
+    parser.add_argument("--loop", type=int, required=True)
+    parser.add_argument("--review-url", required=True)
+    parser.add_argument("--findings-json", type=Path, required=True)
+    parser.add_argument("--worktree-path", type=Path, required=True)
+    return parser.parse_args(all_argv)
+
+
+def main(all_arguments: list[str]) -> int:
+    """Entry point: write <bugteam_audit> XML at the canonical path.
+
+    Args:
+        all_arguments: Command-line arguments.
+
+    Returns:
+        0 on success, 1 on validation or write 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:
+        output_path = write_audit_xml(
+            pr_number=getattr(arguments, "pr_number"),
+            loop=arguments.loop,
+            review_url=getattr(arguments, "review_url"),
+            findings_json_path=findings_path,
+            worktree_path=getattr(arguments, "worktree_path"),
+        )
+    except SystemExit:
+        return 1
+    except (json.JSONDecodeError, OSError) as exc:
+        print(f"write_audit_xml failed: {exc}", file=sys.stderr)
+        return 1
+    print(output_path)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))

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

@@ -0,0 +1,206 @@
+"""Validate status enum values and write <bugteam_fix> XML at the canonical path.
+
+Status enum (canonical source: `ALL_VALID_FIX_STATUSES` in
+`config/path_resolver_constants.py`): fixed | could_not_address |
+hook_blocked | unverified_fixed.
+
+Each outcome's scalar fields become XML attributes on `<outcome>`; the
+body fields named in `ALL_FIX_OUTCOME_BODY_ELEMENT_KEYS` (currently
+`("reason", "hook_output")`) become child elements.
+
+Usage:
+  python scripts/write_fix_outcomes.py --pr-number 422 --loop 3 --commit-sha abc1234 --outcomes-json <PATH> --worktree-path <PATH>
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from xml.etree.ElementTree import Element, SubElement
+
+_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 _path_resolver import fix_outcome_xml_path
+from _xml_utils import emit_pretty_xml
+from config.path_resolver_constants import (
+    ALL_FIX_OUTCOME_BODY_ELEMENT_KEYS,
+    ALL_VALID_FIX_STATUSES,
+)
+
+
+def validate_fix_statuses(all_outcomes: list[dict[str, object]]) -> list[str]:
+    """Validate that every outcome entry has a recognized status.
+
+    Args:
+        all_outcomes: List of outcome dicts, each expected to have a 'status' key.
+
+    Returns:
+        List of validation error messages (empty when valid).
+    """
+    valid_statuses = ALL_VALID_FIX_STATUSES
+    errors: list[str] = []
+    for each_index, each_outcome in enumerate(all_outcomes):
+        status = each_outcome.get("status")
+        if not isinstance(status, str):
+            errors.append(f"outcome[{each_index}]: status missing or not a string")
+            continue
+        if status not in valid_statuses:
+            errors.append(
+                f"outcome[{each_index}]: invalid status '{status}' "
+                f"(expected one of {sorted(valid_statuses)})"
+            )
+    return errors
+
+
+def build_fix_xml(
+    *,
+    pr_number: int,
+    loop: int,
+    commit_sha: str,
+    outcomes_json_path: Path,
+) -> Element:
+    """Build the <bugteam_fix> XML element from outcomes data.
+
+    Args:
+        pr_number: Pull request number.
+        loop: Loop iteration number.
+        commit_sha: Commit SHA of the fix commit.
+        outcomes_json_path: Path to the outcomes JSON file.
+
+    Returns:
+        Root <bugteam_fix> element.
+
+    Raises:
+        SystemExit: When outcomes-json is not a JSON array of objects, or
+            when status validation fails.
+    """
+    outcomes_data = json.loads(outcomes_json_path.read_text(encoding="utf-8"))
+    if not isinstance(outcomes_data, list):
+        print("outcomes-json must contain a JSON array", file=sys.stderr)
+        raise SystemExit(1)
+    for each_index, each_entry in enumerate(outcomes_data):
+        if not isinstance(each_entry, dict):
+            print(
+                f"outcomes-json[{each_index}]: each entry must be a JSON object",
+                file=sys.stderr,
+            )
+            raise SystemExit(1)
+    errors = validate_fix_statuses(outcomes_data)
+    if errors:
+        for each_error in errors:
+            print(each_error, file=sys.stderr)
+        raise SystemExit(1)
+
+    root = Element("bugteam_fix", {
+        "pr": str(pr_number),
+        "loop": str(loop),
+        "commit_sha": commit_sha,
+    })
+
+    all_fix_outcome_body_element_keys = ALL_FIX_OUTCOME_BODY_ELEMENT_KEYS
+    outcomes_elem = SubElement(root, "outcomes")
+    for each_outcome in outcomes_data:
+        outcome_elem = SubElement(outcomes_elem, "outcome")
+        for each_key, each_field_detail in each_outcome.items():
+            field_text = (
+                str(each_field_detail) if each_field_detail is not None else ""
+            )
+            if each_key in all_fix_outcome_body_element_keys:
+                child = SubElement(outcome_elem, each_key)
+                child.text = field_text
+            else:
+                outcome_elem.set(each_key, field_text)
+    return root
+
+
+def write_fix_xml(
+    *,
+    pr_number: int,
+    loop: int,
+    commit_sha: str,
+    outcomes_json_path: Path,
+    worktree_path: Path,
+) -> Path:
+    """Write the <bugteam_fix> XML to the canonical outcome path.
+
+    Args:
+        pr_number: Pull request number.
+        loop: Loop iteration number.
+        commit_sha: Commit SHA of the fix commit.
+        outcomes_json_path: Path to the outcomes JSON file.
+        worktree_path: Path to the git worktree.
+
+    Returns:
+        Path to the written XML file.
+    """
+    root = build_fix_xml(
+        pr_number=pr_number,
+        loop=loop,
+        commit_sha=commit_sha,
+        outcomes_json_path=outcomes_json_path,
+    )
+    xml_string = emit_pretty_xml(root)
+
+    output_path = fix_outcome_xml_path(worktree_path, pr_number, loop)
+    output_path.write_text(xml_string, encoding="utf-8")
+    return output_path
+
+
+def parse_arguments(all_argv: list[str]) -> argparse.Namespace:
+    """Parse command-line arguments.
+
+    Args:
+        all_argv: Command-line argument list.
+
+    Returns:
+        Parsed namespace with pr_number, loop, commit_sha, outcomes_json, and worktree_path.
+    """
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--pr-number", type=int, required=True)
+    parser.add_argument("--loop", type=int, required=True)
+    parser.add_argument("--commit-sha", required=True)
+    parser.add_argument("--outcomes-json", type=Path, required=True)
+    parser.add_argument("--worktree-path", type=Path, required=True)
+    return parser.parse_args(all_argv)
+
+
+def main(all_arguments: list[str]) -> int:
+    """Entry point: write <bugteam_fix> XML at the canonical path.
+
+    Args:
+        all_arguments: Command-line arguments.
+
+    Returns:
+        0 on success, 1 on validation or write failure.
+    """
+    arguments = parse_arguments(all_arguments)
+    outcomes_path = getattr(arguments, "outcomes_json")
+
+    early_exit = require_file(outcomes_path, "outcomes-json")
+    if early_exit is not None:
+        return early_exit
+
+    try:
+        output_path = write_fix_xml(
+            pr_number=getattr(arguments, "pr_number"),
+            loop=arguments.loop,
+            commit_sha=getattr(arguments, "commit_sha"),
+            outcomes_json_path=outcomes_path,
+            worktree_path=getattr(arguments, "worktree_path"),
+        )
+    except SystemExit:
+        return 1
+    except (json.JSONDecodeError, OSError) as exc:
+        print(f"write_fix_xml failed: {exc}", file=sys.stderr)
+        return 1
+    print(output_path)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))