claude-dev-env 1.39.0 → 1.41.0

package/skills/bugteam/scripts/test_claude_permissions_common.py

@@ -118,18 +118,26 @@ def test_default_settings_file_mode_used_when_settings_file_missing(
     assert returned_mode == DEFAULT_SETTINGS_FILE_MODE
 
 
-def test_is_valid_project_root_helper_is_not_orphaned_in_common_module() -> None:
-    """The orphan helper in the common module must be removed.
+def test_is_valid_project_root_exported_from_consumer_modules(
+    tmp_path: Path,
+) -> None:
+    """is_valid_project_root behaviour matches across both consumers.
 
-    Both grant and revoke keep their own local copies and consume them from
-    module scope; the common-module copy was dead code with zero call sites.
+    Grant and revoke each define their own local copy of the helper, so
+    both copies must agree on the .git / .claude marker contract.
     """
-    assert not hasattr(common_module, "is_valid_project_root"), (
-        "is_valid_project_root must not live in _claude_permissions_common — "
-        "neither grant nor revoke imports it from there"
-    )
-    assert callable(grant_module.is_valid_project_root)
-    assert callable(revoke_module.is_valid_project_root)
+    git_marker_project_root = tmp_path / "git_project"
+    (git_marker_project_root / ".git").mkdir(parents=True)
+    claude_marker_project_root = tmp_path / "claude_project"
+    (claude_marker_project_root / ".claude").mkdir(parents=True)
+    bare_directory = tmp_path / "no_marker"
+    bare_directory.mkdir()
+    assert grant_module.is_valid_project_root(git_marker_project_root) is True
+    assert grant_module.is_valid_project_root(claude_marker_project_root) is True
+    assert grant_module.is_valid_project_root(bare_directory) is False
+    assert revoke_module.is_valid_project_root(git_marker_project_root) is True
+    assert revoke_module.is_valid_project_root(claude_marker_project_root) is True
+    assert revoke_module.is_valid_project_root(bare_directory) is False
 
 
 def _reload_with_stale_config_cache(module_name: str) -> ModuleType:

package/skills/copilot-review/SKILL.md

@@ -21,6 +21,22 @@ The user is on a PR branch, wants Copilot (the GitHub Copilot reviewer bot) to k
 
 ## The Process
 
+### Step 0: Opt-out check
+
+Before any other work, inspect the `CLAUDE_REVIEWS_DISABLED` environment
+variable. Treat the value as a comma-separated list of skill tokens
+(case-insensitive, whitespace-tolerant). When the parsed list contains
+`copilot`, respond with the literal line `/copilot-review is disabled via
+CLAUDE_REVIEWS_DISABLED.` and stop — do not spawn the subagent, do not call
+the Copilot reviewer API, do not run any other step of this skill.
+
+PowerShell probe (Windows):
+
+```pwsh
+$disabled = ($env:CLAUDE_REVIEWS_DISABLED -split ',' | ForEach-Object { $_.Trim().ToLowerInvariant() })
+if ($disabled -contains 'copilot') { '/copilot-review is disabled via CLAUDE_REVIEWS_DISABLED.' }
+```
+
 ### Step 1: Gather PR context
 
 From the current repo:

package/skills/findbugs/SKILL.md

@@ -18,6 +18,16 @@ User types `/findbugs` or asks for a bug audit on the current branch's PR. Typic
 
 If the current branch has no associated PR and no diff against the default branch, say so and stop. Do not invent scope.
 
+## Refusals
+
+First match wins; respond with the quoted line exactly and stop:
+
+- **Disabled via environment.** When `CLAUDE_REVIEWS_DISABLED` contains the
+  token `bugteam` (comma-separated, case-insensitive, whitespace-tolerant):
+  `/findbugs is disabled via CLAUDE_REVIEWS_DISABLED.` `/findbugs` is a PR
+  bug-audit skill in the same family as `/bugteam` and `/qbug`, so the
+  shared `bugteam` token disables all three.
+
 ## The Process
 
 ### Step 1: Resolve PR scope
@@ -120,13 +130,31 @@ returns findings without posting them as inline comments is invisible
 to the gate. Findbugs remains read-only on code — the review post is
 the only side effect.
 
-**Self-PR precondition.** GitHub rejects both `APPROVE` and
-`REQUEST_CHANGES` reviews when the authenticated identity matches the
-PR author with HTTP 422; `post_audit_thread.py` retries and then exits 2.
-To run findbugs on a PR you authored, switch `gh auth` to an alternate
-reviewer identity (a separate GitHub account) BEFORE invoking the skill.
-Without this switch, exit 2 is a hard halt — there is no automated
-fallback path. The script does not auto-downgrade on the self-PR case.
+**Self-PR auto-toggle.** GitHub rejects both `APPROVE` and
+`REQUEST_CHANGES` reviews with HTTP 422 when the authenticated identity
+matches the PR author ("Cannot approve/request changes on your own pull
+request"). `post_audit_thread.py` detects this case via `gh api user` +
+`gh api repos/<o>/<r>/pulls/<n>` and auto-resolves an alternate gh
+account's token for the reviews POST — the active `gh auth` account is
+not mutated; only the bearer token sent on the request changes. After
+the POST the active account is still whoever it was before, so no
+"swap back" step is needed.
+
+Configuration:
+
+- `GH_TOKEN` / `GITHUB_TOKEN` env vars take precedence over the toggle.
+  Set them when you need to pin a specific reviewer identity by token
+  rather than by account login.
+- `BUGTEAM_REVIEWER_ACCOUNT` env var names which authenticated alternate
+  to prefer when a toggle is needed (for example,
+  `BUGTEAM_REVIEWER_ACCOUNT=jl-cmd`). The env var name is shared across
+  every skill that invokes `post_audit_thread.py`. When unset, the
+  script falls back to the first alternate account `gh auth status`
+  reports.
+- The named alternate must be logged in (`gh auth login -h github.com -u
+  <login>`) before the audit skill runs. The script exits 1 with a
+  pointing-at-`gh auth login` message when self-PR is detected and no
+  usable alternate is authenticated.
 
 After the agent (and Haiku secondary) return and the merge is complete,
 serialize the merged findings to a JSON file and call

package/skills/monitor-open-prs/SKILL.md

@@ -27,6 +27,7 @@ description: >-
 
 Refusals — first match wins; respond with the quoted line exactly and stop:
 
+- **Disabled via environment.** When `CLAUDE_REVIEWS_DISABLED` (comma-separated, case-insensitive, whitespace-tolerant) contains the token `bugteam`: `/monitor-open-prs is a /bugteam dispatcher and /bugteam is disabled via CLAUDE_REVIEWS_DISABLED.`
 - **GitHub API not accessible.** `get_me failed. /monitor-open-prs needs active GitHub MCP credentials.`
 - **Dirty tree on the caller's repo.** `Uncommitted changes detected. Stash, commit, or revert before /monitor-open-prs.`
 - **Required subagents missing.** Confirm `code-quality-agent` and `clean-coder` exist. Else: `Required subagent type <name> not installed.`
@@ -40,7 +41,7 @@ Call `scripts/discover_open_prs.discover_open_prs(all_owners=["jl-cmd", "JonEcho
 For each discovered PR:
 
 1. Resolve the PR's repo checkout (existing worktree or fresh `git clone`).
-2. From that checkout, invoke `/bugteam --bugbot-retrigger <pr_number>`.
+2. From that checkout, invoke `/bugteam --bugbot-retrigger <pr_number>`. When `CLAUDE_REVIEWS_DISABLED` (comma-separated, case-insensitive, whitespace-tolerant) contains the token `bugbot`, omit `--bugbot-retrigger` from the dispatched command so the bugbot leg sits out the run.
 3. The `--bugbot-retrigger` flag tells bugteam to post `bugbot run` as an issue comment after every successful FIX push so Cursor's bugbot re-evaluates the new commit.
 4. Bugteam runs its own 20-loop audit/fix cycle per PR; this skill waits for each bugteam invocation to return before dispatching the next (or fanning out — see below).
 

package/skills/pr-converge/SKILL.md

@@ -38,7 +38,8 @@ clean-at SHAs. On tick exit, write updated state before calling ScheduleWakeup
 so the next tick resumes with accurate state.
 
 Fields: `phase`, `tick_count`, `bugbot_clean_at`, `bugteam_clean_at`,
-`copilot_clean_at`, `current_head`, `bugbot_acknowledged_at`, `bugbot_down`.
+`copilot_clean_at`, `current_head`, `bugbot_acknowledged_at`, `bugbot_down`,
+`bugteam_skill_invoked_at_head`, `bugteam_skill_invoked_at_tick`.
 
 ## Gotchas
 
@@ -136,7 +137,9 @@ no longer applies.
             - [ ] `bugbot_clean_at = current_head`
             - [ ] Advance to Step 5
       - [ ] **no review yet / commit_id mismatch** →
-            - [ ] Run `python ~/.claude/skills/pr-converge/scripts/check_bugbot_ci.py --owner <O> --repo <R> --check-active --sha <current_head>`
+            - [ ] Run `python ~/.claude/skills/pr-converge/scripts/check_bugbot_ci.py --owner <O> --repo <R> --check-clean --sha <current_head>`
+            - [ ] Exit 0 (bugbot CI completed with success/neutral conclusion and no review = silent pass) → `bugbot_clean_at = current_head` → advance to Step 5
+            - [ ] Exit 1 (not a silent pass) or Exit 2 (gh CLI error — silent pass not confirmable) → Run `python ~/.claude/skills/pr-converge/scripts/check_bugbot_ci.py --owner <O> --repo <R> --check-active --sha <current_head>`
             - [ ] Exit 0 (already queued) → schedule 360s wakeup → return to Step 4 next tick
             - [ ] Exit 1 → post exactly `bugbot run` via `add_issue_comment` (no `@cursor[bot]` mention, no other text), wait 8s
             - [ ] Run `python ~/.claude/skills/pr-converge/scripts/check_bugbot_ci.py --owner <O> --repo <R> --sha <current_head>`
@@ -148,7 +151,12 @@ no longer applies.
 
       Pre-condition: `bugbot_clean_at == current_head` (or `bugbot_down == true`).
 
-      Run `Skill({skill: "bugteam", args: "<PR URL>"})`.
+      Step 5 advances ONLY after `Skill({skill: "bugteam", args: "<PR URL>"})`
+      fires this tick. Substituting an `Agent({subagent_type: "clean-coder"})`
+      audit call for the formal Skill invocation is a protocol violation — the
+      `pr_converge_bugteam_enforcer` hook blocks it. `qbug` is NOT an accepted
+      substitute; `bugteam` is the only allowed skill at this step.
+
       After bugteam completes, re-resolve HEAD.
 
       - [ ] **bugteam pushed new commits** →

package/skills/pr-converge/config/constants.py

@@ -2,7 +2,8 @@
 
 All runtime and API constants live here. Script-specific constants
 (CLI args, markdown patterns, reflow settings) stay in
-``scripts/config/pr_converge_constants.py``, which imports from here.
+``packages/claude-dev-env/skills/pr-converge/scripts/config/pr_converge_constants.py``,
+which imports from here.
 """
 
 CURSOR_BOT_LOGIN = "cursor[bot]"
@@ -27,6 +28,7 @@ BUGBOT_DIRTY_BODY_REGEX = (
 )
 BUGBOT_CHECK_RUN_NAME_SUBSTRING = "bugbot"
 ALL_BUGBOT_CHECK_RUN_ACTIVE_STATUSES = ("queued", "in_progress")
+BUGBOT_CHECK_RUN_COMPLETED_STATUS = "completed"
 ALL_BUGBOT_CHECK_RUN_COMPLETE_CONCLUSIONS = ("success", "neutral")
 BUGBOT_RUN_TRIGGER_PHRASE = "bugbot run\n"
 BUGBOT_RUN_TRIGGER_WAIT_SECONDS = 8

package/skills/pr-converge/reference/per-tick.md

@@ -207,6 +207,14 @@ BUGBOT.
 
 ## Step 3: Re-trigger bugbot
 
+- [ ] **Opt-out gate.** When `CLAUDE_REVIEWS_DISABLED` (comma-separated,
+  case-insensitive, whitespace-tolerant) contains `bugbot`, set
+  `bugbot_down = true`, skip every check below, set `phase = BUGTEAM`,
+  and continue BUGTEAM in the same tick. The downstream loop branches on
+  `bugbot_down` exactly the way it does when bugbot CI is unavailable.
+- [ ] **Silent-pass pre-check.** Run `python ~/.claude/skills/pr-converge/scripts/check_bugbot_ci.py --check-clean --owner <O> --repo <R> --sha <current_head>`
+- [ ] Exit 0 → bugbot CI completed clean with no review (silent pass); set `bugbot_clean_at = current_head`, `phase = BUGTEAM`, continue BUGTEAM same tick
+- [ ] Exit 1 (not a silent pass) or Exit 2 (gh CLI error — silent pass not confirmable) → continue with the trigger flow below
 - [ ] Run `python ~/.claude/skills/pr-converge/scripts/check_bugbot_ci.py --check-active --owner <O> --repo <R> --sha <current_head>`
 - [ ] Exit 0 → bugbot already queued on this commit; skip posting, wait for completion
 - [ ] Exit 1 → post trigger via `add_issue_comment(owner="OWNER", repo="REPO", issueNumber=NUMBER, body="bugbot run")`
@@ -215,6 +223,15 @@ BUGBOT.
 - [ ] Exit non-zero → bugbot is down; set `bugbot_down = true`, `phase = BUGTEAM`, continue BUGTEAM same tick
 - [ ] Exit 0 (check run present) → record `bugbot_acknowledged_at = <now ISO 8601>`, proceed to Step 4
 
+The silent-pass pre-check fires FIRST so we never re-trigger a bot that
+already finished cleanly. Cursor Bugbot communicates "no findings" by
+completing the CI check with `conclusion: success` (or `neutral`) and
+posting no review. The pre-check treats that outcome as
+`bugbot_clean_at = current_head`, equivalent to an explicit clean
+review. Without it, the trigger flow would re-prompt a bot that has
+already evaluated this commit and refuses to re-run, and the bypass
+branch would falsely mark `bugbot_down = true`.
+
 `bugbot run` is empirically the only re-trigger Cursor Bugbot recognizes;
 alternative phrasings silently no-op.
 

package/skills/pr-converge/reference/state-schema.md

@@ -1,10 +1,13 @@
 # State across ticks
 
-**Dual persistence:** `<TMPDIR>/pr-converge-<session_id>/state.json`
-exists (multi-PR) → that file is source of truth for `phase`, heads,
-counters, status, not conversation transcript. No `state.json` (typical
-single-PR `/pr-converge`) → track in each assistant turn as
-plain text so next tick re-reads from context:
+**Dual persistence:** Single-PR `/pr-converge` writes loop state to
+`$CLAUDE_JOB_DIR/pr-converge-state.json`; that file is the source of truth
+for `phase`, heads, counters, status. Multi-PR mode additionally maintains
+`<TMPDIR>/pr-converge-<session_id>/state.json` for orchestrator coordination
+across PRs. Both files share most of the fields below; the
+`bugteam_skill_invoked_at_head` and `bugteam_skill_invoked_at_tick` fields
+live ONLY in the single-PR `$CLAUDE_JOB_DIR/pr-converge-state.json` file
+(see those field entries below for details).
 
 - `phase`: `BUGBOT`, `BUGTEAM`, or `COPILOT_WAIT`. Start `BUGBOT` on first tick.
 - `bugbot_clean_at`: HEAD SHA where bugbot last reported clean, or `null`.
@@ -34,7 +37,32 @@ plain text so next tick re-reads from context:
   (c) reads this field to decide between "schedule next wakeup" and
   "escalate to bugbot-down".
 - `tick_count`: integer, init `0`. Increment every tick.
+- `bugteam_skill_invoked_at_head`: HEAD SHA (string) at which the formal
+  `Skill({skill: "bugteam"})` was last invoked, or `null`. Stamped by the
+  `pr_converge_bugteam_skill_tracker` hook on every formal bugteam Skill
+  invocation. **On-disk location:** the tracker writes this field to
+  `$CLAUDE_JOB_DIR/pr-converge-state.json` (single-PR mode); it is NOT
+  mirrored into the multi-PR `<TMPDIR>/pr-converge-<session_id>/state.json`
+  file. Operators inspecting these stamps must read the single-PR
+  `pr-converge-state.json` under `$CLAUDE_JOB_DIR`. Reset by overwrite on
+  the next bugteam Skill invocation; staleness is detected by the head/tick
+  equality check rather than by explicit reset. The
+  `pr_converge_bugteam_enforcer` hook reads this field together with
+  `current_head` to confirm the formal Skill registered at the current HEAD
+  before allowing follow-on clean-coder audit-shaped Agent spawns. `qbug`
+  invocations deliberately do NOT update this field.
+- `bugteam_skill_invoked_at_tick`: integer tick number at which the formal
+  bugteam Skill was last invoked, or `null`. Companion to
+  `bugteam_skill_invoked_at_head` and persisted to the same
+  `$CLAUDE_JOB_DIR/pr-converge-state.json` file (single-PR mode only).
+  Reset by overwrite on the next bugteam Skill invocation; staleness is
+  detected by the head/tick equality check rather than by explicit reset.
+  The enforcer requires this value to equal the current `tick_count` so a
+  Skill invocation from a prior tick cannot wave through clean-coder
+  audit-shaped Agent spawns on a later tick at the same HEAD.
 
-Tick begins reading prior state line from most recent assistant message
-(no `state.json`) and ends by emitting updated state line; with
-`state.json`, follow `multi-pr-orchestration.md` §What orchestrator does per tick.
+Single-PR tick begins by reading `$CLAUDE_JOB_DIR/pr-converge-state.json`
+if it exists and ends by writing the updated state back to that same file
+before scheduling the next wakeup. Multi-PR mode additionally coordinates
+across PRs via `<TMPDIR>/pr-converge-<session_id>/state.json` per
+`multi-pr-orchestration.md` §What orchestrator does per tick.

package/skills/pr-converge/scripts/check_bugbot_ci.py

@@ -2,11 +2,23 @@
 
 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
 
-Exit codes:
+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
@@ -23,6 +35,8 @@ if str(_pr_converge_dir) not in sys.path:
 
 from config.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,
@@ -121,6 +135,74 @@ def is_bugbot_run_active(*, owner: str, repo: str, sha: str) -> bool:
     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.
 
@@ -128,18 +210,28 @@ def parse_arguments(all_argv: list[str]) -> argparse.Namespace:
         all_argv: Command-line argument list.
 
     Returns:
-        Parsed namespace with owner, repo, and sha.
+        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")
-    parser.add_argument(
+    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)
 
 
@@ -150,19 +242,32 @@ def main(all_arguments: list[str]) -> int:
         all_arguments: Command-line arguments.
 
     Returns:
-        0 when a bugbot check run is found, 1 when absent,
-        EXIT_CODE_GH_ERROR on error.
+        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:
-        found = is_bugbot_run_active(
+        is_active = is_bugbot_run_active(
             owner=arguments.owner,
             repo=arguments.repo,
             sha=arguments.sha,
         )
-        if not found:
+        if not is_active:
             print("bugbot: not found")
-        return 0 if found else 1
+        return 0 if is_active else 1
     return check_bugbot_ci(
         owner=arguments.owner,
         repo=arguments.repo,