claude-dev-env 2.16.0 → 2.18.0

package/_shared/pr-loop/audit-reply-template.md

@@ -4,6 +4,10 @@ Canonical reply shape for every orchestrator-to-thread reply posted by the PR-lo
 
 Read this doc before authoring any code that posts a reply. The template is the contract emitted by every `clean-coder` reply path; the audit-skill wiring (`bugteam`, `pr-converge`) reads it before authoring a reply.
 
+Use `~/.claude/rules/asd-ste100-language.md` for user-facing word choice,
+sentence style, tone, punctuation, and prose form. This template owns review
+thread fields, evidence slots, and action/status structure.
+
 This doc has two surfaces, called out separately so consumers do not conflate them: the **reply template** (this section and below) shapes the body Claude posts back to a single review thread; the **audit body skeleton** in [Relationship to the audit review body](#relationship-to-the-audit-review-body) shapes the parent review `post_audit_thread.py` posts at audit time. The reply-template consumers are the skills/agents listed above (read-only `clean-room audit` is excluded — it posts an audit review via `post_audit_thread.py` but never authors thread replies). The audit-body-skeleton consumers include `clean-room audit` alongside `bugteam` because both post audit reviews via the same script.
 
 ## Provenance

package/_shared/pr-loop/fix-protocol.md

@@ -7,9 +7,9 @@
 3. **Capture pre-fix file contents** for every file this fix will touch. Used in step 8 for the post-fix self-audit diff.
 4. **TDD where applicable:** when the finding has behavior to test, write a failing test first; for pure doc, comment, or naming nits with no behavior, fix directly.
 5. **Apply each fix:**
-   - Preserve existing comments on lines left unchanged
-   - Add complete type hints on every signature touched
-   - Use positive framing in any new prose (no banned negatives)
+    - Preserve existing comments on lines left unchanged
+    - Add complete type hints on every signature touched
+    - Apply `~/.claude/rules/asd-ste100-language.md` to new user-facing prose
 6. **Validate each modified Python file:** `python -m py_compile <path>`. Halt on syntax error; fix and re-run.
 7. **Compute fix diff:** the diff between pre-fix and post-fix file contents for every modified file.
 8. **Post-fix self-audit:** follow [`audit-contract.md`](audit-contract.md) post-fix self-audit sequence. Internal iteration cap: 3. Three rounds with fresh findings → exit `stuck: post-fix audit not converging`. Only when `gate_findings` empty AND `post_fix_findings` empty → proceed to git add.
@@ -40,10 +40,11 @@
     - `status=could_not_address`: `Could not address this loop` / one-line reason text.
     - `status=hook_blocked`: `Hook blocked the fix commit` / one-line hook summary.
 
-    Transport: post the reply via [`gh-payloads.md`](gh-payloads.md), then call `pull_request_review_write(method="resolve_thread", threadId=<thread_node_id>, ...)` for the same thread before moving to the next finding (this is the PR review thread node ID — `PRRT_kwDOxxx` — distinct from the numeric comment ID; harvest it at audit time when calling `get_review_comments`, see [`skills/bugteam/reference/obstacles/fix-resolve-thread.md`](../../skills/bugteam/reference/obstacles/fix-resolve-thread.md)).
+    Transport: post the reply via [`gh-payloads.md`](gh-payloads.md), then call `pull_request_review_write(method="resolve_thread", threadId=<thread_node_id>, ...)` for the same thread before moving to the next finding (this is the PR review thread node ID — `PRRT_kwDOxxx` — distinct from the numeric comment ID; harvest it at audit time when calling `get_review_comments`; see the archived [`fix-resolve-thread` runbook](../../.agents/skills-archived/bugteam/reference/obstacles/fix-resolve-thread.md)).
 13. **Re-trigger reviewer** when the calling workflow specifies. Workflow-specific:
-    - `pr-converge`: post `bugbot run` issue comment after every push (Cursor Bugbot); when the multi-PR path also needs Copilot, call `requested_reviewers` for Copilot as well
-    - `bugteam`: skip — Claude itself is the reviewer; the next loop iteration audits
+    - **autoconverge** — terminal Bugbot, Copilot, and Codex gates re-run after each fix push per [`../../.agents/skills/autoconverge/reference/convergence.md`](../../.agents/skills/autoconverge/reference/convergence.md)
+    - **Archived pr-converge** — post `bugbot run` after every push; see archived skill reference
+    - **Archived bugteam** — skip external re-trigger; the next loop iteration audits
 
 ## Stuck detection
 

package/_shared/pr-loop/gh-payloads.md

@@ -1,6 +1,7 @@
 # MCP-based payloads
 
-Shared payload shapes for posting PR reviews and replies. Used by `bugteam` and `pr-converge`.
+Shared payload shapes for posting PR reviews and replies. Used by autoconverge
+terminal gates and the archived `bugteam` / `pr-converge` skills.
 
 ## Build payloads with MCP tools
 
@@ -12,9 +13,11 @@ Posting the per-loop audit review is handled by
 [`_shared/pr-loop/scripts/post_audit_thread.py`](scripts/post_audit_thread.py).
 The script owns the review-create/POST/retry flow internally; callers no longer
 build the GitHub reviews-API payload themselves. See
-[`skills/bugteam/SKILL.md` § Audit posting](../../skills/bugteam/SKILL.md#audit-posting)
-for the contract and [`skills/bugteam/PROMPTS.md`](../../skills/bugteam/PROMPTS.md)
-for the AUDIT-step invocation shape.
+[`post-audit-thread-contract.md`](post-audit-thread-contract.md) for the contract
+and the archived
+[`bugteam` audit-posting section](../../.agents/skills-archived/bugteam/SKILL.md)
+for the historical invocation shape in
+[`PROMPTS.md`](../../.agents/skills-archived/bugteam/PROMPTS.md).
 
 ## Review body skeleton
 
@@ -57,7 +60,7 @@ user-facing output (chat reply to the user) rather than in the PR review body.
 
 There is no fallback payload to build. On retry exhaustion
 `post_audit_thread.py` exits `2` and the orchestrator halts — see
-[`./post-audit-thread-contract.md`](./post-audit-thread-contract.md) § Exit codes.
+[`post-audit-thread-contract.md`](post-audit-thread-contract.md) § Exit codes.
 A hard blocker on the audit-posting path is a halt condition, not a degraded
 flat-issue-comment fall-through.
 
@@ -70,4 +73,3 @@ flat-issue-comment fall-through.
 ## SHA capture timing
 
 `commit_id` and any `<head_sha_at_post_time>` reference: `git rev-parse HEAD` immediately before the POST, in the cwd of whichever subagent or process is posting.
-

package/_shared/pr-loop/precatch-rubric.md

@@ -17,11 +17,12 @@ sweep to have cleared them and reviews sweep-clean code.
 
 ## Lane 2 — Doc-vs-code parity
 
-Every doc claim in the diff matches the code it describes. Reuse the
-`pr-consistency-audit` skill's canonical-source cross-reference method
-(`~/.claude/skills/pr-consistency-audit/SKILL.md`, canonical source first) and the
-drift rubric at
-`~/.claude/audit-rubrics/category_rubrics/category-o-docstring-vs-impl-drift.md`.
+Every doc claim in the diff matches the code it describes. Reuse the cross-file
+consistency prompt at
+[`../../.agents/skills/_shared/pr-loop/prompts/pr-consistency-audit.xml`](../../.agents/skills/_shared/pr-loop/prompts/pr-consistency-audit.xml)
+(installed as `~/.claude/skills/_shared/pr-loop/prompts/pr-consistency-audit.xml`)
+and the drift rubric at
+[`../../audit-rubrics/category_rubrics/category-o-docstring-vs-impl-drift.md`](../../audit-rubrics/category_rubrics/category-o-docstring-vs-impl-drift.md).
 
 - Every line citation resolves to the line it names.
 - Every referenced file or script path exists.

package/_shared/pr-loop/scripts/AGENTS.md

@@ -19,6 +19,18 @@ Python scripts invoked at runtime by the PR-loop skills. Each script is a standa
 | `reviewer_availability.py` | Unified reviewer-availability entry point for Copilot and Bugbot: reuses `copilot_quota.py` and `reviews_disabled.py` and exits 0 when the named `--reviewer` may be spawned, non-zero when it is opted out or (for Copilot) out of quota |
 | `fix_hookspath.py` | Repairs a malformed `core.hooksPath` global git config entry |
 | `_claude_permissions_common.py` | Internal helpers shared by the grant/revoke scripts: atomic settings.json writes, list mutation, path helpers |
+| `check_convergence.py` | Single convergence gate check for autoconverge finalize and mark-ready hooks |
+| `check_bugbot_ci.py` | Bugbot CI check-run status on a given SHA |
+| `check_convergence_availability.py` | Reviewer waiver resolution for convergence gates |
+| `check_convergence_gates.py` | GitHub REST leaf checks for convergence gates |
+| `check_convergence_thread_gates.py` | GitHub GraphQL and REST thread gate checks |
+| `check_pending_reviews.py` | Pending review requests and reviewer states |
+| `fetch_copilot_reviews.py` | Copilot reviews filtered to the current HEAD |
+| `post_fix_reply.py` | Inline reply poster for review comment threads |
+| `run_codex_review.py` | Codex review capture wrapper for the autoconverge Codex gate |
+| `codex_usage_probe.py` | Weekly Codex usage probe for gate threshold decisions |
+| `codex_down_classifier.py` | Maps Codex run outcomes to completed or codex_down |
+| `parse_codex_findings.py` | Parses Codex reviewer output into findings |
 
 ## Subdirectories
 
@@ -26,6 +38,9 @@ Python scripts invoked at runtime by the PR-loop skills. Each script is a standa
 |---|---|
 | `code_rules_gate_parts/` | The decomposed modules `code_rules_gate.py` wires together: enforcer loading, git file sets, blob readers, added-line maps, violation scoping, wrapper plumb-through, gate running, staged-test running, and argument parsing |
 | `pr_loop_shared_constants/` | Named constants used by the scripts above |
+| `pr_converge_skill_constants/` | Bot logins, review states, and API templates for convergence scripts |
+| `pr_converge_scripts_constants/` | CLI and reflow constants for convergence scripts |
+| `codex_review_scripts_constants/` | Constants for Codex review capture and classification |
 | `tests/` | pytest suite for all scripts in this directory |
 
 ## Running tests

package/_shared/pr-loop/scripts/_pr_converge_path_setup.py

@@ -0,0 +1,38 @@
+"""Put shared PR-loop script directories on sys.path for standalone runs.
+
+Importing this module makes the convergence constants packages and the shared
+``reviews_disabled`` module resolvable when a script in this directory runs
+as ``__main__``. Each directory is added once, guarded against duplicates.
+
+Scripts ship under ``packages/claude-dev-env/_shared/pr-loop/scripts/`` and
+install to ``~/.claude/_shared/pr-loop/scripts/``.
+"""
+
+import sys
+from pathlib import Path
+
+_scripts_directory = Path(__file__).resolve().parent
+_skill_directory = _scripts_directory.parent
+_skills_directory = _skill_directory.parent
+_skills_home_directory = _skills_directory.parent
+_package_or_user_home = (
+    _skills_home_directory.parent
+    if _skills_home_directory.name == ".agents"
+    else _skills_home_directory
+)
+_shared_under_package = _package_or_user_home / "_shared" / "pr-loop" / "scripts"
+_shared_under_claude = (
+    _package_or_user_home / ".claude" / "_shared" / "pr-loop" / "scripts"
+)
+_shared_pr_loop_scripts_directory = (
+    _shared_under_package
+    if _shared_under_package.is_dir()
+    else _shared_under_claude
+)
+
+if str(_scripts_directory) not in sys.path:
+    sys.path.insert(0, str(_scripts_directory))
+if str(_skill_directory) not in sys.path:
+    sys.path.insert(0, str(_skill_directory))
+if str(_shared_pr_loop_scripts_directory) not in sys.path:
+    sys.path.insert(0, str(_shared_pr_loop_scripts_directory))

package/_shared/pr-loop/scripts/check_bugbot_ci.py

@@ -0,0 +1,279 @@
+"""Check for bugbot CI check runs on a commit.
+
+Usage:
+  python scripts/check_bugbot_ci.py --owner <O> --repo <R> --sha <SHA>
+  python scripts/check_bugbot_ci.py --owner <O> --repo <R> --sha <SHA> --check-active
+  python scripts/check_bugbot_ci.py --owner <O> --repo <R> --sha <SHA> --check-clean
+
+Default mode (no flag):
+  0 — bugbot check run found (printed to stdout as JSON)
+  1 — no bugbot check run found
+  EXIT_CODE_GH_ERROR — gh CLI error
+
+``--check-active`` mode:
+  0 — bugbot check run is queued or in_progress
+  1 — bugbot check run is absent or no longer active
+
+``--check-clean`` mode (silent-pass detection):
+  0 — bugbot check run is completed with success/neutral conclusion
+  1 — bugbot check run is absent, still active, or completed with a
+      non-clean conclusion (failure, action_required, etc.)
+  EXIT_CODE_GH_ERROR — gh CLI error
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import subprocess
+import sys
+from pathlib import Path
+
+_pr_converge_dir = Path(__file__).absolute().parent.parent
+if str(_pr_converge_dir) not in sys.path:
+    sys.path.insert(0, str(_pr_converge_dir))
+
+from pr_converge_skill_constants.constants import (
+    ALL_BUGBOT_CHECK_RUN_ACTIVE_STATUSES,
+    ALL_BUGBOT_CHECK_RUN_COMPLETE_CONCLUSIONS,
+    BUGBOT_CHECK_RUN_COMPLETED_STATUS,
+    BUGBOT_CHECK_RUN_NAME_SUBSTRING,
+    CHECK_RUNS_PER_PAGE,
+    EXIT_CODE_GH_ERROR,
+    GH_CHECK_RUNS_PATH_TEMPLATE,
+)
+
+
+def _run_check_runs_api(
+    *, owner: str, repo: str, sha: str
+) -> subprocess.CompletedProcess[str]:
+    endpoint_path = GH_CHECK_RUNS_PATH_TEMPLATE.format(owner=owner, repo=repo, sha=sha)
+    jq_filter = ".check_runs[] | {name, status, conclusion}"
+    return subprocess.run(
+        [
+            "gh",
+            "api",
+            f"{endpoint_path}?per_page={CHECK_RUNS_PER_PAGE}",
+            "--jq",
+            jq_filter,
+        ],
+        capture_output=True,
+        text=True,
+        encoding="utf-8",
+        errors="replace",
+        check=False,
+    )
+
+
+def check_bugbot_ci(*, owner: str, repo: str, sha: str) -> int:
+    """Check whether a bugbot CI check run exists on the given commit.
+
+    Args:
+        owner: GitHub repository owner.
+        repo: GitHub repository name.
+        sha: Commit SHA to check.
+
+    Returns:
+        0 when a bugbot check run is found, 1 when absent,
+        EXIT_CODE_GH_ERROR on gh CLI error.
+    """
+    completed_process = _run_check_runs_api(owner=owner, repo=repo, sha=sha)
+    if completed_process.returncode != 0:
+        print(f"gh api error: {completed_process.stderr}", file=sys.stderr)
+        return EXIT_CODE_GH_ERROR
+    for each_line in completed_process.stdout.splitlines():
+        stripped_line = each_line.strip()
+        if not stripped_line:
+            continue
+        try:
+            check_entry: dict[str, object] = json.loads(stripped_line)
+        except json.JSONDecodeError:
+            continue
+        each_name: object = check_entry.get("name")
+        if not isinstance(each_name, str):
+            continue
+        if BUGBOT_CHECK_RUN_NAME_SUBSTRING.lower() in each_name.lower():
+            json.dump(check_entry, sys.stdout)
+            sys.stdout.write("\n")
+            return 0
+    return 1
+
+
+def is_bugbot_run_active(*, owner: str, repo: str, sha: str) -> bool:
+    """Check whether bugbot has an active (queued/in-progress) check run.
+
+    Args:
+        owner: GitHub repository owner.
+        repo: GitHub repository name.
+        sha: Commit SHA to check.
+
+    Returns:
+        True when a bugbot check run with an active status exists.
+    """
+    completed_process = _run_check_runs_api(owner=owner, repo=repo, sha=sha)
+    if completed_process.returncode != 0:
+        return False
+    for each_line in completed_process.stdout.splitlines():
+        stripped_line = each_line.strip()
+        if not stripped_line:
+            continue
+        try:
+            check_entry: dict[str, object] = json.loads(stripped_line)
+        except json.JSONDecodeError:
+            continue
+        each_name: object = check_entry.get("name")
+        if not isinstance(each_name, str):
+            continue
+        if BUGBOT_CHECK_RUN_NAME_SUBSTRING.lower() not in each_name.lower():
+            continue
+        each_status: object = check_entry.get("status")
+        if (
+            isinstance(each_status, str)
+            and each_status in ALL_BUGBOT_CHECK_RUN_ACTIVE_STATUSES
+        ):
+            return True
+    return False
+
+
+def _classify_bugbot_check_run(
+    completed_process: subprocess.CompletedProcess[str],
+) -> bool | None:
+    """Classify the bugbot check run state from a gh API process result.
+
+    Args:
+        completed_process: Result of calling ``_run_check_runs_api``.
+
+    Returns:
+        True when the captured stdout contains a bugbot check run with a
+        ``completed`` status and a conclusion in
+        ``ALL_BUGBOT_CHECK_RUN_COMPLETE_CONCLUSIONS``. False when no such
+        check run is present (absent, still active, or completed with a
+        non-clean conclusion). None when ``completed_process.returncode``
+        is non-zero, signalling a gh CLI failure that the caller must
+        surface separately from "not clean".
+    """
+    if completed_process.returncode != 0:
+        return None
+    for each_line in completed_process.stdout.splitlines():
+        stripped_line = each_line.strip()
+        if not stripped_line:
+            continue
+        try:
+            check_entry: dict[str, object] = json.loads(stripped_line)
+        except json.JSONDecodeError:
+            continue
+        each_name: object = check_entry.get("name")
+        if not isinstance(each_name, str):
+            continue
+        if BUGBOT_CHECK_RUN_NAME_SUBSTRING.lower() not in each_name.lower():
+            continue
+        each_status: object = check_entry.get("status")
+        if each_status != BUGBOT_CHECK_RUN_COMPLETED_STATUS:
+            return False
+        each_conclusion: object = check_entry.get("conclusion")
+        return (
+            isinstance(each_conclusion, str)
+            and each_conclusion in ALL_BUGBOT_CHECK_RUN_COMPLETE_CONCLUSIONS
+        )
+    return False
+
+
+def is_bugbot_run_clean(*, owner: str, repo: str, sha: str) -> bool | None:
+    """Check whether bugbot has a completed check run with a clean conclusion.
+
+    A "silent pass" is bugbot's signal that it found no issues: the CI
+    check run completes with a ``success`` or ``neutral`` conclusion and
+    no review comment is posted. This function detects that signal so
+    callers can treat it as equivalent to an explicit clean review.
+
+    Args:
+        owner: GitHub repository owner.
+        repo: GitHub repository name.
+        sha: Commit SHA to check.
+
+    Returns:
+        True when a bugbot check run is completed with a conclusion in
+        ``ALL_BUGBOT_CHECK_RUN_COMPLETE_CONCLUSIONS``. False when the
+        check run is absent, still active, or completed with a non-clean
+        conclusion. None when the gh CLI returns an error so the caller
+        can distinguish a transient API failure from a "not clean"
+        result.
+    """
+    completed_process = _run_check_runs_api(owner=owner, repo=repo, sha=sha)
+    return _classify_bugbot_check_run(completed_process)
+
+
+def parse_arguments(all_argv: list[str]) -> argparse.Namespace:
+    """Parse command-line arguments.
+
+    Args:
+        all_argv: Command-line argument list.
+
+    Returns:
+        Parsed namespace with owner, repo, sha, and mode flags.
+    """
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--owner", required=True, help="GitHub repository owner")
+    parser.add_argument("--repo", required=True, help="GitHub repository name")
+    parser.add_argument("--sha", required=True, help="Commit SHA to check")
+    mode_group = parser.add_mutually_exclusive_group()
+    mode_group.add_argument(
+        "--check-active",
+        action="store_true",
+        default=False,
+        help="Check for active (queued/in-progress) check runs only",
+    )
+    mode_group.add_argument(
+        "--check-clean",
+        action="store_true",
+        default=False,
+        help=(
+            "Check for a completed bugbot check run with a "
+            "success/neutral conclusion (silent-pass detection)"
+        ),
+    )
+    return parser.parse_args(all_argv)
+
+
+def main(all_arguments: list[str]) -> int:
+    """Entry point for check_bugbot_ci.
+
+    Args:
+        all_arguments: Command-line arguments.
+
+    Returns:
+        Exit code per the mode-specific contract documented in the
+        module docstring.
+    """
+    arguments = parse_arguments(all_arguments)
+    if arguments.check_clean:
+        completed_process = _run_check_runs_api(
+            owner=arguments.owner,
+            repo=arguments.repo,
+            sha=arguments.sha,
+        )
+        if completed_process.returncode != 0:
+            print(f"gh api error: {completed_process.stderr}", file=sys.stderr)
+            return EXIT_CODE_GH_ERROR
+        is_clean = _classify_bugbot_check_run(completed_process)
+        if is_clean is not True:
+            print("bugbot: not clean")
+        return 0 if is_clean is True else 1
+    if arguments.check_active:
+        is_active = is_bugbot_run_active(
+            owner=arguments.owner,
+            repo=arguments.repo,
+            sha=arguments.sha,
+        )
+        if not is_active:
+            print("bugbot: not found")
+        return 0 if is_active else 1
+    return check_bugbot_ci(
+        owner=arguments.owner,
+        repo=arguments.repo,
+        sha=arguments.sha,
+    )
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))