claude-dev-env 1.38.0 → 1.39.0

package/skills/bugteam/reference/obstacles/fix-py-compile.md

@@ -0,0 +1,13 @@
+# py_compile
+
+Run py_compile or language-equivalent on every modified file
+
+## Self-population
+
+Hit a wall on this step? Spawn a background agent to record it. Keep working.
+
+1. Spawn  — brief it: check  for an open PR touching this file, add a commit to it, or create a fresh branch + worktree + draft PR.
+2. Tell the agent your obstacle and what fixed it. It writes the entry below.
+
+## Obstacles
+

package/skills/bugteam/reference/obstacles/fix-read-files.md

@@ -0,0 +1,13 @@
+# Read files
+
+Read each referenced file before editing
+
+## Self-population
+
+Hit a wall on this step? Spawn a background agent to record it. Keep working.
+
+1. Spawn  — brief it: check  for an open PR touching this file, add a commit to it, or create a fresh branch + worktree + draft PR.
+2. Tell the agent your obstacle and what fixed it. It writes the entry below.
+
+## Obstacles
+

package/skills/bugteam/reference/obstacles/fix-resolve-thread.md

@@ -0,0 +1,13 @@
+# Resolve threads
+
+Resolve each thread via pull_request_review_write resolve_thread using thread_node_id
+
+## Self-population
+
+Hit a wall on this step? Spawn a background agent to record it. Keep working.
+
+1. Spawn  — brief it: check  for an open PR touching this file, add a commit to it, or create a fresh branch + worktree + draft PR.
+2. Tell the agent your obstacle and what fixed it. It writes the entry below.
+
+## Obstacles
+

package/skills/bugteam/reference/obstacles/fix-test-suite.md

@@ -0,0 +1,13 @@
+# Test suite
+
+Run test suite, diagnose and fix regressions before committing
+
+## Self-population
+
+Hit a wall on this step? Spawn a background agent to record it. Keep working.
+
+1. Spawn  — brief it: check  for an open PR touching this file, add a commit to it, or create a fresh branch + worktree + draft PR.
+2. Tell the agent your obstacle and what fixed it. It writes the entry below.
+
+## Obstacles
+

package/skills/bugteam/reference/obstacles/fix-violation-count.md

@@ -0,0 +1,13 @@
+# Violation count
+
+Post-fix violation count must not exceed previous loop total
+
+## Self-population
+
+Hit a wall on this step? Spawn a background agent to record it. Keep working.
+
+1. Spawn  — brief it: check  for an open PR touching this file, add a commit to it, or create a fresh branch + worktree + draft PR.
+2. Tell the agent your obstacle and what fixed it. It writes the entry below.
+
+## Obstacles
+

package/skills/bugteam/reference/obstacles/fix-write-xml.md

@@ -0,0 +1,13 @@
+# Write fix outcomes
+
+Write fix outcomes XML to worktree path with reply IDs, resolution status
+
+## Self-population
+
+Hit a wall on this step? Spawn a background agent to record it. Keep working.
+
+1. Spawn  — brief it: check  for an open PR touching this file, add a commit to it, or create a fresh branch + worktree + draft PR.
+2. Tell the agent your obstacle and what fixed it. It writes the entry below.
+
+## Obstacles
+

package/skills/bugteam/reference/team-setup.md

@@ -1,8 +1,48 @@
 # Run setup and loop state
 
+## Pre-flight (before Step 0)
+
+### Utility scripts
+
+Bugteam-specific utilities (preflight, fix_hookspath, grant, revoke) live in
+the skill-local [`scripts/`](../scripts/) directory. Shared utilities remain in
+[`_shared/pr-loop/scripts/`](../../_shared/pr-loop/scripts/) (run, do not paste
+into context). Utility scripts are **executed**, not loaded as primary context
+([`sources.md`](sources.md) § Progressive disclosure and utility scripts).
+
+```bash
+python "${CLAUDE_SKILL_DIR}/scripts/bugteam_preflight.py"
+```
+
+Non-zero → fix before grant. `BUGTEAM_PREFLIGHT_SKIP=1` emergency only.
+`--pre-commit` if `.pre-commit-config.yaml` exists.
+
+**Auto-remediation for `core.hooksPath`:** when preflight fails with stderr
+containing `core.hooksPath` (the message starts with `bugteam_preflight:
+core.hooksPath is`, or `Git-side CODE_RULES enforcement is not active`), Claude
+must auto-invoke the fix script — do not fall through to `AskUserQuestion`, do
+not punt to the user, do not ask for confirmation:
+
+```bash
+python "${CLAUDE_SKILL_DIR}/scripts/bugteam_fix_hookspath.py"
+```
+
+The fix script removes any non-canonical local-scope override on the active
+repository, sets the global `core.hooksPath` to `~/.claude/hooks/git-hooks` if
+missing or wrong, and re-runs `bugteam_preflight.py`. Its exit code becomes the
+preflight outcome. Exit 0 → continue to Step 0. Non-zero only when the
+canonical hooks directory is missing (run `npx claude-dev-env .` first) or
+`git config --global` writes are blocked. Other preflight failures (pytest,
+pre-commit) still require manual fixes —
+the auto-remediation only applies to the `core.hooksPath` failure mode.
+
 ## Step 0 — Grant project permissions (detail)
 
-Before spawning any subagents, grant the session write access to the project’s `.claude/**` tree. Command in `SKILL.md`.
+Before spawning any subagents, grant the session write access to the project's `.claude/**` tree:
+
+```bash
+python "${CLAUDE_SKILL_DIR}/scripts/grant_project_claude_permissions.py"
+```
 
 `${CLAUDE_SKILL_DIR}` is a Claude Code host-managed token, pre-substituted by the runtime before any shell sees it. Unlike `${TMPDIR}` and similar shell parameter expansions, it does not depend on the shell’s expansion semantics, so it behaves the same on Unix and Windows shells.
 
@@ -14,21 +54,45 @@ This is the **first** action of every `/bugteam` invocation, before any subagent
 
 Same resolution path as `/findbugs`:
 
-1. `pull_request_read(method="get", pullNumber=N, owner=O, repo=R)` — extracts `number`, `baseRefName`, `headRefName`, `url` from response (`N` comes from the parent skill's PR context, or fall back to `pull_request_read` with the default branch lookup to recover the PR number).
+1. Call `pull_request_read(method="get", pullNumber=N, owner=O, repo=R)` to fetch PR metadata; capture `number`, `headRefName`, `baseRefName`, and `url` from the response. Falls back to the merge-base diff path when no PR exists.
 2. Fall back to `git merge-base HEAD origin/<default>` then `git diff <merge-base>...HEAD`.
 3. Neither → refuse per refusal cases in `SKILL.md`.
 
 Capture `<owner>/<repo>`, head branch, base branch, PR number, PR URL. This scope persists across every loop — `/bugteam` runs to completion from the single up-front confirmation.
 
-## Step 2 — Run name and temp directory (detail)
+For multi-PR invocations, capture `all_prs = [{number, owner, repo, baseRef, headRef, url}, ...]`. A single-PR invocation produces a one-element list and follows the same downstream rules.
 
-### Run specification
+### Per-PR workspace
 
-- **Run name:** `bugteam-pr-<number>-<YYYYMMDDHHMMSS>` for single-PR invocations, `bugteam-<YYYYMMDDHHMMSS>` for multi-PR invocations (or `bugteam-<sanitized-head-branch>-<YYYYMMDDHHMMSS>` if no PR). The timestamp is captured once at invocation start and prevents two concurrent invocations on the same PR from colliding.
+For each PR in `all_prs`:
 
-- **Branch-name sanitization (no-PR fallback only):** Before substituting `<head-branch>` into the `run_name` template, replace every character outside `[A-Za-z0-9._-]` with `-`. The whitelist keeps safe portable filename characters only; OS-reserved and shell-special characters (`/ \ : * ? < > | "` plus ASCII control characters `0x00`–`0x1F`) fall outside the whitelist and become `-`. Example: `feat/foo*bar` → `feat-foo-bar`; `run_name` becomes `bugteam-feat-foo-bar-<YYYYMMDDHHMMSS>`. Apply sanitization when `run_name` is first assembled so every downstream use (temp dir, cleanup) sees the safe form.
+Canonical path functions live in
+[`_shared/pr-loop/scripts/_path_resolver.py`](../../_shared/pr-loop/scripts/_path_resolver.py):
+`per_pr_workspace(run_temp_dir, owner, repo, pr_number)` returns dict with keys
+`worktree`, `diff_patch_template`, `outcome_xml_template`, `fix_outcome_xml_template`.
 
-- **Per-run temp directory (resolved once, reused everywhere):** After `run_name` is captured, resolve a portable absolute path: `Path(tempfile.gettempdir()) / run_name` (requires `import tempfile`). `tempfile.gettempdir()` honors `TMPDIR`, `TEMP`, and `TMP` in platform-correct order and falls back to `C:\Users\<user>\AppData\Local\Temp` on Windows or `/tmp` on Unix. Capture the resolved absolute path as `<run_temp_dir>` and pass that literal path to every shell command that follows.
+1. Create `<run_temp_dir>/pr-<N>/`.
+2. Run `git worktree add "<run_temp_dir>/pr-<N>/worktree" origin/<headRef>`.
+3. Record the absolute worktree path alongside the PR's other fields.
+
+Background subagents for a PR operate inside that PR's worktree. Step 4 teardown
+runs [`teardown_worktrees.py`](../../_shared/pr-loop/scripts/teardown_worktrees.py)
+for each PR before the shared `rmtree`.
+
+## Step 2 — Run name and temp directory (detail)
+
+Canonical path resolution lives in
+[`_shared/pr-loop/scripts/_path_resolver.py`](../../_shared/pr-loop/scripts/_path_resolver.py).
+The functions below are its public API; the implementation is the single source of
+truth.
+
+- **Run name:** `build_run_name(pr_number, head_branch, *, is_multi_pr)` — returns
+  `bugteam-pr-<number>` for single-PR, `bugteam-<sanitized-head-branch>` for multi-PR.
+- **Branch-name sanitization:** `sanitize_branch_name(head_branch)` — maps every
+  character outside `[A-Za-z0-9._-]` to `-`.
+- **Per-run temp directory:** `resolve_run_temp_dir(run_name)` — returns
+  `Path(tempfile.gettempdir()) / run_name`. Capture the resolved absolute path as
+  `<run_temp_dir>` and pass that literal path to every shell command that follows.
 
 - **Subagent roles (spawned per loop, not at invocation start):**
   - `bugfind` — `code-quality-agent`, model opus (Opus 4.7 at default xhigh effort)
@@ -36,8 +100,41 @@ Capture `<owner>/<repo>`, head branch, base branch, PR number, PR URL. This scop
 
 ### Loop state block
 
-The block in `SKILL.md` mixes lead-internal variables and one shell command (`starting_sha`). Read it as instructions, not a single runnable script.
+Loop state (lead; not a single script; per-PR): the variables below are tracked
+independently for each PR in `all_prs`. Each PR has its own cycle, state, and
+exit reason.
+
+Create the initial state file with
+[`init_loop_state.py`](../../_shared/pr-loop/scripts/init_loop_state.py):
+
+```
+python scripts/init_loop_state.py --pr-number <N> --head-ref <ref> --starting-sha <SHA> [--is-multi-pr]
+```
+
+Outputs the path to `<run_temp_dir>/pr-<N>/loop-state.json` with keys
+`loop_count`, `last_action`, `last_findings`, `starting_sha`, `loop_comment_index`.
 
 **`loop_comment_index` scope (per-loop, not cross-loop):** Reset at the start of every AUDIT action, populated as finding comments are posted during AUDIT, consumed by the matching FIX action when it posts fix replies, and discarded after FIX completes. It does not persist across loops; each loop starts with an empty index and its own fresh set of comment URLs.
 
-Each entry: `{loop, finding_id, finding_comment_id, finding_comment_url, used_fallback, fix_status}`. Populated by AUDIT, consumed by FIX.
+Shape: dict keyed by `finding_id`. Each value: `{finding_comment_id, finding_comment_url, thread_node_id, fix_status}` where `thread_node_id` is the PR review thread node id (`PRRT_kwDOxxx`) captured at audit time when calling `get_review_comments`, used by the FIX step's `resolve_thread` call. The loop number is implicit (the index resets at every AUDIT) so it does not repeat in each value. AUDIT populates `finding_comment_id`, `finding_comment_url`, and `thread_node_id` when it posts the per-loop review; FIX sets `fix_status` when its commit lands.
+
+#### Multi-PR sub-team tracking
+
+When `/bugteam` runs against multiple PRs across repos, each PR operates as a
+logical sub-team within the master `bugteam` team. The PR identity token is
+`{owner}/{repo}#{N}` (e.g. `jl-cmd/claude-code-config#422`). The slugified form
+comes from `slugify_pr_identity(owner, repo, pr_number)` in
+[`_path_resolver.py`](../../_shared/pr-loop/scripts/_path_resolver.py).
+
+- **Teammate name:** `bugfind-{owner}-{repo}-pr{N}-loop{L}-{letter}`
+- **Task subject:** `{owner}/{repo}#{N} audit {letter}`
+- **Outcome XML:** `diff_patch_path(run_temp_dir, owner, repo, pr_number, loop_number)` from `_path_resolver.py`
+
+The lead filters by the slugified prefix to group tasks and teammates by PR.
+Self-claiming by task subject prefix keeps each teammate on its assigned PR.
+
+### --bugbot-retrigger flag
+
+**`--bugbot-retrigger` flag:** when present, the FIX subagent posts a `bugbot
+run` issue comment via the Step 2.5 issue-comments fallback endpoint after
+every successful FIX push, to re-trigger Cursor's bugbot on the new commit.

package/skills/bugteam/reference/teardown-publish-permissions.md

@@ -2,7 +2,7 @@
 
 ## Utility scripts (progressive disclosure)
 
-Fragile or repeatable shell sequences belong in `_shared/pr-loop/scripts/`. Anthropic: [Progressive disclosure patterns](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices#progressive-disclosure-patterns) — utility scripts are **executed**, not loaded into context as primary reading. Script inventory and entry points: [`../../../_shared/pr-loop/scripts/README.md`](../../../_shared/pr-loop/scripts/README.md). Gate-only merge-base / diff semantics: [`../../../_shared/pr-loop/code-rules-gate.md`](../../../_shared/pr-loop/code-rules-gate.md).
+Fragile or repeatable shell sequences belong in `_shared/pr-loop/scripts/`. Bugteam-specific scripts (e.g. revoke, see Step 5) live in the skill-local [`scripts/`](../scripts/) directory. Anthropic: [Progressive disclosure patterns](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices#progressive-disclosure-patterns) — utility scripts are **executed**, not loaded into context as primary reading. Shared-script inventory: [`../../../_shared/pr-loop/scripts/README.md`](../../../_shared/pr-loop/scripts/README.md). Bugteam-script inventory: [`../scripts/README.md`](../scripts/README.md). Gate-only merge-base / diff semantics: [`../../../_shared/pr-loop/code-rules-gate.md`](../../../_shared/pr-loop/code-rules-gate.md).
 
 ### Pre-flight (recommended before Step 0)
 
@@ -12,7 +12,21 @@ From the repository root, run the command in `SKILL.md`. If the exit code is non
 
 When the cycle exits (any reason), run these steps in order from **this** session (the lead).
 
-1. **Delete the per-run temp directory** using the Python one-liner in `SKILL.md` with the same literal `<run_temp_dir>` from Step 2. The one-liner uses an `onexc`/`onerror` handler that strips the Windows ReadOnly attribute and retries the failing syscall — `ignore_errors=True` is unsafe on Windows because it silently swallows ReadOnly-attribute failures (see `~/.claude/rules/windows-filesystem-safe.md`).
+1. **Delete the team:** `TeamDelete` removes `~/.claude/teams/bugteam/` and `~/.claude/tasks/bugteam/`. Only at convergence/cap/stuck — not between loops.
+
+2. Run [`teardown_worktrees.py`](../../_shared/pr-loop/scripts/teardown_worktrees.py)
+   to remove each PR's worktree (`git worktree remove`) and the run temp
+   directory (Windows-safe `shutil.rmtree`):
+
+   ```bash
+   python "${CLAUDE_SKILL_DIR}/../../_shared/pr-loop/scripts/teardown_worktrees.py" \
+     --run-temp-dir "<run_temp_dir>" \
+     --all-pr-jsons '<json array of {number, owner, repo}>'
+   ```
+
+   Tolerates already-removed worktrees and missing directories. Uses an
+   `onexc`/`onerror` handler for Windows ReadOnly attribute safety
+   (see `~/.claude/rules/windows-filesystem-safe.md`).
 
 ## Step 4.5 — Finalize the PR description (mandatory)
 
@@ -25,6 +39,7 @@ The lead delegates body text to the `pr-description-writer` agent so the global
 ```
 Agent(
   subagent_type="pr-description-writer",
+  mode="bypassPermissions",
   description="Rewrite PR <number> body from cumulative diff",
   prompt="<brief from steps below>"
 )
@@ -34,25 +49,41 @@ If that subagent is missing, fall back to `general-purpose` with the same brief
 
 **Steps:**
 
-1. Capture cumulative diff: `pull_request_read(method="get_diff", pullNumber=N, owner=O, repo=R)` → write output to `.bugteam-final.diff` with `Write` tool.
-2. Capture original body: `pull_request_read(method="get", pullNumber=N, owner=O, repo=R)` → extract `.body` from response, write to `.bugteam-original-body.md` with `Write` tool.
+1. Capture cumulative diff: `pull_request_read(method="get_diff", pullNumber=N, owner=O, repo=R)` → write the response text to `.bugteam-final.diff` using the `Write` tool.
+2. Capture original body: `pull_request_read(method="get", pullNumber=N, owner=O, repo=R)` → extract `.body` from the response, write it to `.bugteam-original-body.md` using the `Write` tool.
 3. Agent brief:
    - **Inputs:** diff path, original body path, head branch, base branch.
    - **Constraint:** describe what the PR delivers from the cumulative diff — behavior, user-visible effect, merge rationale. Process metadata (loops, fix counts, findings) stays in review comments.
-   - **Preservation rule:** if the original body has manually curated sections (linked issues, screenshots, test plan, "Risk Assessment", etc.), preserve them verbatim and only rewrite narrative around them.
+   - **Preservation rule:** if the original body has manually curated sections (linked issues, screenshots, test plan, “Risk Assessment”, etc.), preserve them verbatim and only rewrite narrative around them.
    - **Output:** new body markdown.
 4. Write `.bugteam-final-body.md`.
-5. `update_pull_request(pullNumber=N, owner=O, repo=R, body=<body_text>)`.
+5. Publish the new body: `update_pull_request(pullNumber=N, owner=O, repo=R, body=<contents of .bugteam-final-body.md>)`.
 6. Delete `.bugteam-final.diff`, `.bugteam-original-body.md`, `.bugteam-final-body.md`.
 
 If Step 4.5 fails (agent error, hook block, network), report in the final report and continue to Step 5. The original PR body remains; commits and comments are unaffected.
 
 ## Step 5 — Revoke project permissions (mandatory, always)
 
-After team cleanup — including on error, cap-reached, or stuck exits — run the revoke command from `SKILL.md`.
+After team cleanup — including on error, cap-reached, or stuck exits — run:
+
+```bash
+python "${CLAUDE_SKILL_DIR}/scripts/revoke_project_claude_permissions.py"
+```
 
 This removes allow rules and `additionalDirectories` added in Step 0. Revoke is non-negotiable: leaving the grant in place would let future sessions inherit elevated `.claude/**` access without an explicit opt-in. Run revoke even if Step 4 partially failed; log cleanup errors separately.
 
 ## Step 6 — Final report
 
-Template and exit hints are in `SKILL.md`. If exit = `cap reached`, name remaining bug count and suggest `/findbugs` for human triage. If `stuck`, name which findings the fix agent could not resolve. If `error`, surface the error and loop number.
+```
+/bugteam exit: <converged | cap reached | stuck | error>
+Loops: <loop_count>
+Starting commit: <starting_sha7>
+Final commit: <current_HEAD_sha7>
+Net change: <total_files> files, +<total_add>/-<total_del>
+
+Loop log:
+1 audit: 3P0 2P1 0P2
+...
+```
+
+If exit = `cap reached`, name remaining bug count and suggest `/findbugs` for human triage. If `stuck`, name which findings the fix agent could not resolve. If `error`, surface the error and loop number.

package/skills/bugteam/scripts/README.md

@@ -0,0 +1,60 @@
+# Bugteam utility scripts
+
+Scripts in this directory are **executed** by the lead or teammates. They are not loaded into context as instructions (see Anthropic [Skill authoring best practices — Progressive disclosure](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices#progressive-disclosure-patterns)).
+
+| Script | Purpose |
+|--------|---------|
+| `bugteam_preflight.py` | Run pytest (when configured) and optional `pre-commit` before `/bugteam`. |
+| `bugteam_fix_hookspath.py` | Auto-remediate a stale local `core.hooksPath` override, set canonical global value, re-run `bugteam_preflight.py`. Invoked by Claude when preflight reports a `core.hooksPath` failure. |
+| `bugteam_code_rules_gate.py` | Run `validate_content` from `code-rules-enforcer.py` on PR-scoped files (`git diff` vs merge-base). Exit `1` if any mandatory rule fails. Invoked **before each audit**; the fixer clears it before the auditor runs. |
+| `grant_project_claude_permissions.py` | Idempotent grant of Edit/Write/Read on `cwd/.claude/**` into `~/.claude/settings.json`. |
+| `revoke_project_claude_permissions.py` | Removes the matching grant entries from `~/.claude/settings.json`. |
+| `test_claude_permissions_common.py` | Pytest module for path normalization and glob-metacharacter guards in `_claude_permissions_common.py`. |
+| `_claude_permissions_common.py` | Shared helpers for the grant/revoke scripts (atomic JSON writes, settings sections). |
+| `windows_safe_rmtree.py` | Recursively remove a directory tree on Windows by stripping ReadOnly attributes and retrying the failing syscall. Invoked from SKILL.md Step 4 to delete `<run_temp_dir>` after teardown. |
+| `probe_code_rules_enforcer_check.py` | Dynamically load `~/.claude/hooks/blocking/code_rules_enforcer.py` and invoke a named check function against a fixture file. Used by the historical Copilot gap-analysis investigation as a verification shape (see `reference/copilot-gap-analysis.md`). |
+
+## `bugteam_preflight.py`
+
+From the repository root:
+
+```bash
+python "${CLAUDE_SKILL_DIR}/scripts/bugteam_preflight.py"
+```
+
+- Skips pytest when `BUGTEAM_PREFLIGHT_SKIP=1`.
+- Skips pytest when `pytest.ini` / `pyproject.toml` exists but no `test_*.py` / `*_test.py` files are found under the repo root.
+- Pytest exit code `5` (no tests collected) is treated as success.
+- Add `--pre-commit` to run `pre-commit run --all-files` when `.pre-commit-config.yaml` exists.
+
+## `bugteam_fix_hookspath.py`
+
+From the repository root:
+
+```bash
+python "${CLAUDE_SKILL_DIR}/scripts/bugteam_fix_hookspath.py"
+```
+
+- Removes any local-scope `core.hooksPath` value that does not end in `hooks/git-hooks`.
+- Sets `git config --global core.hooksPath ~/.claude/hooks/git-hooks` when the global value is unset or non-canonical.
+- Refuses to run (exit non-zero) when `~/.claude/hooks/git-hooks` does not exist on disk — install via `npx claude-dev-env .` first.
+- Idempotent: a second invocation is a clean no-op.
+- Re-runs `bugteam_preflight.py --no-pytest` and propagates its exit code.
+
+The bugteam SKILL invokes this automatically when preflight stderr indicates a `core.hooksPath` failure, so Claude does not surface the error to the user.
+
+## `bugteam_code_rules_gate.py`
+
+From the repository root (same merge-base rules as the PR head vs base — default `--base origin/main`):
+
+```bash
+python "${CLAUDE_SKILL_DIR}/scripts/bugteam_code_rules_gate.py"
+```
+
+Optional explicit files instead of `git diff`:
+
+```bash
+python "${CLAUDE_SKILL_DIR}/scripts/bugteam_code_rules_gate.py" path/to/a.py path/to/b.ts
+```
+
+This loads `validate_content` from `hooks/blocking/code-rules-enforcer.py` inside `claude-dev-env` (same logic as the PreToolUse hook). Exit `0` = mandatory checks pass on scanned files; exit `1` = violations printed to stderr.