claude-dev-env 1.26.0 → 1.26.2

package/skills/bugteam/SKILL_EVALS.md

@@ -6,7 +6,7 @@ Evaluation-driven iteration set for the `bugteam` skill, following [Anthropic
 
 Evals are split into two layers. Both layers run against the same trace but carry different failure semantics.
 
-**Layer A — Ironclad invariants.** Order-and-presence rules that MUST hold on every run regardless of fixture, regardless of model choice, regardless of the exact number of loops taken. Every Layer A assertion is cited to a specific line in `SKILL.md` — if the assertion fails, either the run diverged from the skill or the skill text is ambiguous and needs patching.
+**Layer A — Ironclad invariants.** Order-and-presence rules that MUST hold on every run regardless of fixture, regardless of model choice, regardless of the exact number of loops taken. Citations use **section headings and companion files** (`SKILL.md`, `CONSTRAINTS.md`, `reference/*.md`) — not fragile line numbers — so layout edits to `SKILL.md` do not invalidate the contract. If an assertion fails, either the run diverged from the skill or the cited text is ambiguous and needs patching.
 
 **Layer B — Fixture-dependent expectations.** The concrete tool trace predicted for a specific fixture (fixed PR state, canned audit XML, canned fix XML). Layer B is prediction — reality may diverge in small ways (extra `Bash("git rev-parse HEAD")` checkpoints the lead inserts for sanity; retry loops on transient failures; consolidated cleanup calls) without indicating a skill defect. Layer B failures trigger reconciliation, not auto-failure.
 
@@ -14,23 +14,23 @@ Evals are split into two layers. Both layers run against the same trace but carr
 
 ## Ironclad invariants (Layer A, apply to every eval)
 
-Each invariant cites the skill line it derives from.
+Each invariant cites the normative section or companion file it derives from.
 
 | # | Invariant | Citation |
 |---|---|---|
-| I-1 | `Bash(grant_project_claude_permissions.py)` precedes every `TeamCreate`. | SKILL.md Step 0 |
-| I-2 | `Bash(revoke_project_claude_permissions.py)` runs exactly once per invocation, after the last `TeamDelete`, on every exit path (converged, stuck, cap reached, error). | SKILL.md Step 5 |
-| I-3 | Exactly one `TeamCreate` and exactly one `TeamDelete` per invocation. | SKILL.md Step 2, Step 4 |
-| I-4 | Every `Agent(name=...)` spawn is followed (before `TeamDelete`) by a matching `SendMessage(to=..., message={type: "shutdown_request", ...})`. No orphaned teammates. | SKILL.md AUDIT shutdown, FIX shutdown, Step 4.1 |
-| I-5 | `Agent` calls are fresh per loop — the same `name` is never reused across loops without an intervening shutdown. | SKILL.md Constraints: "Fresh teammate per loop" |
-| I-6 | Both audit and fix `Agent` calls pass `model="sonnet"`. | SKILL.md Step 2 roles list, Constraints: "Sonnet for both teammates" |
+| I-1 | `Bash` invoking `scripts/grant_project_claude_permissions.py` precedes every `TeamCreate`. | `SKILL.md` § Step 0 |
+| I-2 | `Bash` invoking `scripts/revoke_project_claude_permissions.py` runs exactly once per invocation, after the last `TeamDelete`, on every exit path (converged, stuck, cap reached, error). | `SKILL.md` § Step 5 |
+| I-3 | Exactly one `TeamCreate` and exactly one `TeamDelete` per invocation. | `SKILL.md` § Step 2; § Step 4 |
+| I-4 | Before `TeamDelete`, no teammate remains active without cleanup: either the teammate self-terminated after `Agent` returned, or the lead sent a matching `SendMessage(..., shutdown_request)` (including parallel-auditor shutdowns). No orphaned teammates when `TeamDelete` runs. | `SKILL.md` § AUDIT action (**Shutdown**); § FIX action (**Shutdown**); § Step 4 |
+| I-5 | `Agent` calls are fresh per loop — the same `name` is never reused across loops without an intervening shutdown. | `CONSTRAINTS.md` — **Fresh teammate per loop** |
+| I-6 | Both audit and fix `Agent` calls pass `model="sonnet"`. | `SKILL.md` § Step 2 (**Roles**); `CONSTRAINTS.md` — **Sonnet for both teammates** |
 | I-7 | `TeamDelete()` is called with no arguments. | TeamDelete schema: no required params, no properties |
-| I-8 | Loop count ≤ 10 audits. 11th audit never fires. | SKILL.md: "10-loop hard cap" |
-| I-9 | From loop 4 onward without convergence, the audit phase emits three parallel `Agent` calls in a single assistant message with names `bugfind-loop-<N>-a/b/c`. | SKILL.md AUDIT action: "Parallel auditors from loop 4 onward" |
-| I-10 | Lead reads `.bugteam-loop-<N>.outcomes.xml` with the `Read` tool after each audit, before the next action. | SKILL.md: "the lead reads `.bugteam-loop-<N>.outcomes.xml` with the `Read` tool" |
-| I-11 | On exit of any kind, ordering is: `TeamDelete` → temp-dir cleanup → Step 4.5 PR rewrite → revoke. | SKILL.md Step 4, Step 4.5, Step 5 ordering |
-| I-12 | Lead never posts PR review comments, finding comments, or fix replies. The only lead-side PR mutation is the final `gh pr edit --body-file` in Step 4.5. | SKILL.md Constraints: "Teammates own audit/fix comment posting", "Lead owns the final PR description rewrite only" |
-| I-13 | Only the orchestrator (lead session) invokes `TeamCreate`. Every teammate `Agent(...)` call passes `team_name=<lead_team_name>`. No teammate ever calls `TeamCreate`. When supplementary work arises mid-cycle (parallel auditors, adjacent-file audits, infrastructure fixes), the lead spawns additional teammates into the existing team rather than creating a second team. | SKILL.md Constraints: "Orchestrator-only TeamCreate"; runtime error: `Already leading team "<name>". A leader can only manage one team at a time.` |
+| I-8 | Loop count ≤ 10 audits. 11th audit never fires. | `SKILL.md` YAML `description` (10-loop cap); § Step 3 (**Pre-audit** / **FIX** increment rules) |
+| I-9 | From loop 4 onward without convergence, the audit phase emits three parallel `Agent` calls in a single assistant message with names `bugfind-loop-<N>-a/b/c`. | `SKILL.md` § AUDIT action (**Parallel auditors**); `reference/audit-and-teammates.md` § **Parallel auditors** |
+| I-10 | Lead reads `.bugteam-loop-<N>.outcomes.xml` with the `Read` tool after each audit, before the next action. | `SKILL.md` § AUDIT action |
+| I-11 | On exit of any kind, ordering is: teammate shutdowns → `TeamDelete` → temp-dir cleanup → Step 4.5 PR rewrite → revoke. | `SKILL.md` § Step 4; § Step 4.5; § Step 5; `reference/teardown-publish-permissions.md` § **Step 4** / **Step 4.5** / **Step 5** |
+| I-12 | Lead never posts PR review comments, finding comments, or fix replies. The only lead-side PR mutation is the final `gh pr edit --body-file` in Step 4.5. | `CONSTRAINTS.md` — **Teammates own audit/fix comment posting**; **Lead owns the final PR description rewrite only** |
+| I-13 | Only the orchestrator (lead session) invokes `TeamCreate`. Every teammate `Agent(...)` call passes `team_name=<lead_team_name>`. No teammate ever calls `TeamCreate`. When supplementary work arises mid-cycle (parallel auditors, adjacent-file audits, infrastructure fixes), the lead spawns additional teammates into the existing team rather than creating a second team. | `CONSTRAINTS.md` — **Orchestrator-only `TeamCreate`** (runtime error quoted there) |
 
 Any eval failing one or more Layer A invariants fails the run.
 
@@ -105,33 +105,33 @@ The harness does not yet exist; this document defines its contract.
 
 | # | Tool call | Source |
 |---|---|---|
-| 1 | `Bash("python .../grant_project_claude_permissions.py")` | SKILL.md Step 0 |
-| 2 | `Bash("gh pr view --json number,baseRefName,headRefName,url")` | SKILL.md Step 1 |
-| 3 | `Bash("git rev-parse HEAD")` → captures `starting_sha` | SKILL.md:125 |
-| 4 | `TeamCreate(team_name="bugteam-pr-42-<ts>", description=..., agent_type="team-lead")` | SKILL.md Step 2 |
-| 5 | `Bash("mkdir -p <team_temp_dir>")` | SKILL.md AUDIT action |
-| 6 | `Bash("gh pr diff 42 -R ... > <team_temp_dir>/loop-1.patch")` | SKILL.md AUDIT action |
-| 7 | `Agent(subagent_type="code-quality-agent", name="bugfind", team_name=..., model="sonnet", description=..., prompt=<audit XML loop 1>)` | SKILL.md AUDIT action |
-| 8 | `Read(".bugteam-loop-1.outcomes.xml")` | SKILL.md AUDIT action |
-| 9 | `SendMessage(to="bugfind", message={type: "shutdown_request", reason: "audit loop 1 complete; outcome XML captured"})` | SKILL.md AUDIT shutdown |
-| 10 | `Agent(subagent_type="clean-coder", name="bugfix", team_name=..., model="sonnet", description=..., prompt=<fix XML loop 1>)` | SKILL.md FIX action |
-| 11 | `Read(".bugteam-loop-1.outcomes.xml")` — bugfix outcome XML overwrites same filename | SKILL.md FIX action |
-| 12 | `Bash("git rev-parse HEAD")` → verify HEAD advanced | SKILL.md:499, 502 |
-| 13 | `Bash("git fetch origin <branch> && git rev-parse origin/<branch>")` → verify push landed | SKILL.md:500 |
-| 14 | `SendMessage(to="bugfix", message={type: "shutdown_request", reason: "fix loop 1 complete; commit <sha7> pushed"})` | SKILL.md FIX shutdown |
-| 15 | `Bash("gh pr diff 42 -R ... > <team_temp_dir>/loop-2.patch")` | SKILL.md AUDIT action |
-| 16 | `Agent(subagent_type="code-quality-agent", name="bugfind", ...)` (loop 2) | SKILL.md AUDIT action |
-| 17 | `Read(".bugteam-loop-2.outcomes.xml")` — zero findings | SKILL.md AUDIT action |
-| 18 | `SendMessage(to="bugfind", message={type: "shutdown_request", reason: "audit loop 2 complete; zero findings"})` | SKILL.md AUDIT shutdown |
-| 19 | `TeamDelete()` | SKILL.md Step 4 |
-| 20 | `Bash("python -c \"import shutil; shutil.rmtree(r'<team_temp_dir>', ignore_errors=True)\"")` | SKILL.md Step 4 |
-| 21 | `Bash("gh pr diff 42 -R ... > .bugteam-final.diff")` | SKILL.md:564 |
-| 22 | `Bash("gh pr view 42 -R ... --json body --jq .body > .bugteam-original-body.md")` | SKILL.md:565 |
-| 23 | `Agent(subagent_type="pr-description-writer", description=..., prompt=<brief>)` | SKILL.md Step 4.5 |
-| 24 | `Write(".bugteam-final-body.md", <returned body>)` | SKILL.md:571 |
-| 25 | `Bash("gh pr edit 42 -R ... --body-file .bugteam-final-body.md")` | SKILL.md:572 |
-| 26 | `Bash("rm .bugteam-final.diff .bugteam-original-body.md .bugteam-final-body.md .bugteam-loop-*.outcomes.xml")` | SKILL.md:573, 621 |
-| 27 | `Bash("python .../revoke_project_claude_permissions.py")` | SKILL.md Step 5 |
+| 1 | `Bash("python .../scripts/grant_project_claude_permissions.py")` | `SKILL.md` § Step 0 |
+| 2 | `Bash("gh pr view --json number,baseRefName,headRefName,url")` | `SKILL.md` § Step 1 |
+| 3 | `Bash("git rev-parse HEAD")` → captures `starting_sha` | `SKILL.md` § Step 2 — **Loop state** block |
+| 4 | `TeamCreate(team_name="bugteam-pr-42-<ts>", description=..., agent_type="team-lead")` | `SKILL.md` § Step 2 |
+| 5 | `Bash("mkdir -p <team_temp_dir>")` | `SKILL.md` § AUDIT action |
+| 6 | `Bash("gh pr diff 42 -R ... > <team_temp_dir>/loop-1.patch")` | `SKILL.md` § AUDIT action |
+| 7 | `Agent(subagent_type="code-quality-agent", name="bugfind", team_name=..., model="sonnet", description=..., prompt=<audit XML loop 1>)` | `SKILL.md` § AUDIT action |
+| 8 | `Read(".bugteam-loop-1.outcomes.xml")` | `SKILL.md` § AUDIT action |
+| 9 | `SendMessage(to="bugfind", message={type: "shutdown_request", reason: "audit loop 1 complete; outcome XML captured"})` | `SKILL.md` § AUDIT action (**Shutdown** fallback) |
+| 10 | `Agent(subagent_type="clean-coder", name="bugfix", team_name=..., model="sonnet", description=..., prompt=<fix XML loop 1>)` | `SKILL.md` § FIX action |
+| 11 | `Read(".bugteam-loop-1.outcomes.xml")` — bugfix outcome XML overwrites same filename | `SKILL.md` § FIX action |
+| 12 | `Bash("git rev-parse HEAD")` → verify HEAD advanced | `SKILL.md` § FIX action (**Verify**) |
+| 13 | `Bash("git fetch origin <branch> && git rev-parse origin/<branch>")` → verify push landed | `SKILL.md` § FIX action (**Verify**) |
+| 14 | `SendMessage(to="bugfix", message={type: "shutdown_request", reason: "fix loop 1 complete; commit <sha7> pushed"})` | `SKILL.md` § FIX action (**Shutdown** fallback) |
+| 15 | `Bash("gh pr diff 42 -R ... > <team_temp_dir>/loop-2.patch")` | `SKILL.md` § AUDIT action |
+| 16 | `Agent(subagent_type="code-quality-agent", name="bugfind", ...)` (loop 2) | `SKILL.md` § AUDIT action |
+| 17 | `Read(".bugteam-loop-2.outcomes.xml")` — zero findings | `SKILL.md` § AUDIT action |
+| 18 | `SendMessage(to="bugfind", message={type: "shutdown_request", reason: "audit loop 2 complete; zero findings"})` | `SKILL.md` § AUDIT action (**Shutdown** fallback) |
+| 19 | `TeamDelete()` | `SKILL.md` § Step 4 |
+| 20 | `Bash("python -c \"import shutil; shutil.rmtree(r'<team_temp_dir>', ignore_errors=True)\"")` | `SKILL.md` § Step 4 |
+| 21 | `Bash("gh pr diff 42 -R ... > .bugteam-final.diff")` | `SKILL.md` § Step 4.5 step 1 |
+| 22 | `Bash("gh pr view 42 -R ... --json body --jq .body > .bugteam-original-body.md")` | `SKILL.md` § Step 4.5 step 2 |
+| 23 | `Agent(subagent_type="pr-description-writer", description=..., prompt=<brief>)` | `SKILL.md` § Step 4.5 |
+| 24 | `Write(".bugteam-final-body.md", <returned body>)` | `SKILL.md` § Step 4.5 step 4 |
+| 25 | `Bash("gh pr edit 42 -R ... --body-file .bugteam-final-body.md")` | `SKILL.md` § Step 4.5 step 4 |
+| 26 | `Bash("rm .bugteam-final.diff .bugteam-original-body.md .bugteam-final-body.md")` | `SKILL.md` § Step 4.5 step 5 (lead may add `.bugteam-loop-*.outcomes.xml` in the same or a separate `rm` — reconcile on first real run) |
+| 27 | `Bash("python .../scripts/revoke_project_claude_permissions.py")` | `SKILL.md` § Step 5 |
 
 **Pass criteria.**
 - All Layer A invariants hold.
@@ -228,7 +228,7 @@ Patch this table to match observation and annotate each correction.
 - Every finding's outcome XML carries `used_fallback="true"` and the issue-comment URL as `finding_comment_url`.
 - Cycle continues to the FIX action without aborting.
 
-**Open item for the real run.** The exact `gh api` payload shape for the issue-comments fallback is specified at `SKILL.md:164-171` as `jq -Rs | gh api .../issues/<number>/comments --input -`. Before running Eval 10 for real, confirm the teammate obeys this shape — the fixture must assert the endpoint path and the `--input -` pattern.
+**Open item for the real run.** The issue-comments fallback shape is `jq -Rs | gh api .../issues/<number>/comments --input -` (`SKILL.md` § Step 2.5 **Review POST fails**; full narrative in `reference/github-pr-reviews.md` § **Review POST failure fallback**). Before running Eval 10 for real, confirm the teammate obeys this shape — the fixture must assert the endpoint path and the `--input -` pattern.
 
 ---
 
@@ -327,8 +327,8 @@ The adjacent-audit teammate writes its own outcome XML, self-terminates. Lead re
 1. **Cycle 0 — Reconcile predictions with reality.** On the first real run, diff every Layer B predicted trace against the observed trace. Patch this file to match reality and annotate each correction with a reason.
 2. **Baseline.** Run every eval with the skill unloaded. Record which cases the base model handles from memory versus which it gets wrong.
 3. **Treatment.** Run every eval with the skill loaded. Layer A invariants must pass on every case. Layer B mismatches trigger Cycle 0 reconciliation.
-4. **Regress on change.** Every edit to `SKILL.md` re-runs the full suite. A passing→failing transition on any Layer A invariant blocks the change. A Layer B mismatch after a `SKILL.md` edit triggers a patch to the affected eval trace in the same commit.
-5. **Extend on gotcha.** When the skill misfires in real use, add a new eval that reproduces the miss before patching `SKILL.md`.
+4. **Regress on change.** Every edit to normative text in `SKILL.md`, `CONSTRAINTS.md`, `PROMPTS.md`, or `reference/*.md` sections that Layer A cites re-runs the full suite. A passing→failing transition on any Layer A invariant blocks the change. A Layer B mismatch after such an edit triggers a patch to the affected eval trace in the same commit.
+5. **Extend on gotcha.** When the skill misfires in real use, add a new eval that reproduces the miss before patching the orchestration or companion files.
 
 ## Harness sketch (future work)
 
@@ -341,6 +341,6 @@ A minimal Python harness under `packages/claude-dev-env/skills/bugteam/evals/`:
 
 ## Open research items flagged during this pass
 
-1. **GitHub REST review-POST payload shape.** Eval 9 and Eval 10 depend on the exact body shape of `POST /pulls/<number>/reviews`. `SKILL.md:138-158` specifies the `jq -n --rawfile ... --argjson ... | gh api ... --input -` shape. Before running Eval 9/10 for real, fetch the current GitHub REST reference to confirm the request schema (fields `commit_id`, `event`, `body`, `comments[]`) and the multi-line anchor `{path, start_line, start_side, line, side, body}` shape still apply. Record the confirmed version and URL here.
-2. **`SendMessage` shutdown origination — RESOLVED.** `SendMessage` tool docs include the line "Don't originate `shutdown_request` unless asked." `TeamCreate` tool docs explicitly direct the lead to originate `{type: "shutdown_request"}` for teammate cleanup. Real-run observation (loop 1 of eval run 2026-04-18) resolved the contradiction: teammates self-terminate when their task is complete — the `Agent` call returns and the teammate's session ends without any `SendMessage`. The cycle proceeded correctly without the lead ever needing to originate a `shutdown_request`. `SKILL.md` has been updated to document self-termination as the expected path and lead-originated `SendMessage(shutdown_request)` as a fallback for teammates that do not self-terminate after the `Agent` call returns. The literal `SendMessage` call shapes remain in `SKILL.md` for that fallback case.
+1. **GitHub REST review-POST payload shape.** Eval 9 and Eval 10 depend on the exact body shape of `POST /pulls/<number>/reviews`. The `jq -n --rawfile ... --argjson ... | gh api ... --input -` fence lives in `SKILL.md` § Step 2.5 (**Review POST**); expanded copy in `reference/github-pr-reviews.md` § **Per-loop review**. Before running Eval 9/10 for real, fetch the current GitHub REST reference to confirm the request schema (fields `commit_id`, `event`, `body`, `comments[]`) and the multi-line anchor `{path, start_line, start_side, line, side, body}` shape still apply. Record the confirmed version and URL here.
+2. **`SendMessage` shutdown origination — RESOLVED.** `SendMessage` tool docs include the line "Don't originate `shutdown_request` unless asked." `TeamCreate` tool docs explicitly direct the lead to originate `{type: "shutdown_request"}` for teammate cleanup. Real-run observation (loop 1 of eval run 2026-04-18) resolved the contradiction: teammates self-terminate when their task is complete — the `Agent` call returns and the teammate's session ends without any `SendMessage`. The cycle proceeded correctly without the lead ever needing to originate a `shutdown_request`. `SKILL.md` § AUDIT / FIX actions document self-termination as the expected path and lead-originated `SendMessage(shutdown_request)` as a fallback; `reference/audit-and-teammates.md` carries the longer shutdown narrative. Layer A **I-4** encodes “no orphaned teammates,” not “always send SendMessage.”
 3. **Model override redundancy.** `code-quality-agent` and `clean-coder` may already pin `model` in their agent definitions. The explicit `model="sonnet"` in every spawn is insurance, but on the first real run confirm no conflict between the lead-passed model and the agent-frontmatter model.

package/skills/bugteam/reference/README.md

@@ -0,0 +1,13 @@
+# Bugteam reference
+
+Expanded material that used to live inline in `SKILL.md`. Load a file when the orchestration stub in `SKILL.md` is not enough — debugging GitHub review shape, gate semantics, teardown edge cases, or explaining the design to a human.
+
+| File | Domain |
+|------|--------|
+| [`design-rationale.md`](design-rationale.md) | Why agent teams (clean-room), table-of-contents habit, when `/bugteam` applies, refusal reasons |
+| [`team-setup.md`](team-setup.md) | Permissions grant (`CLAUDE_SKILL_DIR`), PR scope, `TeamCreate`, team name / sanitization / temp dir / roles / loop state |
+| [`github-pr-reviews.md`](github-pr-reviews.md) | Per-loop reviews, `jq` + `gh api` payloads, anchors, fallbacks, REST endpoints |
+| [`audit-and-teammates.md`](audit-and-teammates.md) | Pre-audit gate, full cycle numbering, AUDIT and FIX actions, parallel auditors |
+| [`teardown-publish-permissions.md`](teardown-publish-permissions.md) | Utility scripts note, teardown, PR description rewrite, revoke, final report |
+
+Canonical documentation quotes: [`../sources.md`](../sources.md).

package/skills/bugteam/reference/audit-and-teammates.md

@@ -0,0 +1,127 @@
+# Gate, cycle, AUDIT, and FIX
+
+## Step 3 — The cycle (full detail)
+
+Repeat until an exit condition fires.
+
+**Ordering principle:** Mandatory **CODE_RULES** checks (`validate_content` from `hooks/blocking/code_rules_enforcer.py`) must pass on the PR-scoped file set **before** any **AUDIT** (bugfind) teammate runs. The **clean-coder** teammate clears gate failures; then the **code-quality-agent** teammate audits. This mirrors “CI green, then review,” without relying on GitHub Actions — the script is the gate.
+
+1. Decide the next action from `last_action` and `last_findings`:
+   - `last_action == "audited"` and `last_findings.total == 0` → exit reason = `converged`
+   - `last_action == "fixed"` and `git rev-parse HEAD` did not change since pre-FIX → exit reason = `stuck` (see FIX action)
+   - `last_action in {"fresh", "fixed"}` → go to **pre-audit path** (below), then **AUDIT**
+   - `last_action == "audited"` and `last_findings.total > 0` → go to **FIX** (below)
+
+2. **Pre-audit path** (only when the next step is **AUDIT**):
+   1. From the repository root, run the gate script (align `--base` with the PR base branch from Step 1, e.g. `origin/main` or `origin/develop`):
+
+      ```bash
+      python "${CLAUDE_SKILL_DIR}/scripts/bugteam_code_rules_gate.py" --base origin/<baseRefName>
+      ```
+
+      `git merge-base` + `git diff --name-only` live inside the script; see [`../scripts/README.md`](../scripts/README.md). The lead runs this (not a teammate).
+
+   2. If exit code **0** → continue to step 2.5 (AUDIT spawn) below.
+   3. If exit code **non-zero** → spawn a new **clean-coder** teammate — **standards-fix pass** — with instructions: read the script’s stderr, edit the repo until a **re-run** of the **same** gate command exits **0**, then one commit, `git push`, shutdown. Repeat standards-fix spawns until the gate exits **0** or **5** failed gate rounds (each round = one teammate session after a non-zero gate). If still non-zero after 5 rounds → exit reason = `error: code rules gate failed pre-audit`.
+   4. After gate exit **0**, increment `loop_count`. If `loop_count > 10`, exit reason = `cap reached` (counts **audits**, not standards-only rounds).
+   5. Execute **AUDIT action** (spawn bugfind). Print progress: `Loop <N> audit: ...`
+
+3. **FIX path** (when `last_action == "audited"` and `last_findings.total > 0`):
+   1. Increment `loop_count`. If `loop_count > 10`, exit reason = `cap reached`.
+   2. Execute **FIX action** (spawn bugfix clean-coder for audit findings). Print: `Loop <N> fix: commit ...`
+   3. Set `last_action = "fixed"`, update `audit_log`, loop to step 1 (next iteration hits **pre-audit path** before the next AUDIT).
+
+4. After **AUDIT**, update `last_action`, `last_findings`, `audit_log`; print the audit progress line if not already printed.
+
+5. Loop.
+
+**Note:** The first iteration uses **pre-audit path** then **AUDIT**. After a **FIX**, the next iteration runs **pre-audit path** again (gate → then AUDIT), so `validate_content` stays green before semantic audit.
+
+## AUDIT action (clean-room teammate, fresh per loop)
+
+Capture a fresh PR diff for this loop into the per-team scoped directory so concurrent `/bugteam` runs keep patches isolated. Use the literal `<team_temp_dir>` resolved once in Step 2 — Claude resolves the absolute path; every shell receives the same literal value.
+
+Commands and `Agent(...)` shape: `SKILL.md`.
+
+`<team_temp_dir>` includes the sanitized `team_name` and timestamp; `team_name` is already prefixed with `bugteam-`. Claude resolves `Path(tempfile.gettempdir()) / team_name` once and passes that absolute path to every shell. `tempfile.gettempdir()` honors `TMPDIR`, `TEMP`, `TMP` and falls back to the OS temp directory, so the same approach works on macOS, Linux, Windows cmd.exe, and PowerShell.
+
+Each loop calls `Agent` again with a fresh invocation so the teammate starts with its own context window. Doc line on lead history: [`../sources.md`](../sources.md).
+
+See [`../PROMPTS.md`](../PROMPTS.md) for AUDIT spawn-prompt XML and bugfind outcome schema. Substitute placeholders (`repo`, `branch`, `base_branch`, `pr_url`, `loop`, `diff_path`) into the `prompt` argument.
+
+After the teammate returns, the lead reads `.bugteam-loop-<N>.outcomes.xml` with the `Read` tool, parses it, and populates `loop_comment_index` from `<finding>` elements.
+
+### Shutdown (bugfind)
+
+**Expected path — self-termination:** Teammates often self-terminate when complete — the `Agent` call returns and the session ends. Then no `SendMessage` is needed.
+
+**Fallback — lead-initiated shutdown:** If the teammate still appears active after `Agent` returns, send:
+
+```
+SendMessage(
+  to="bugfind",
+  message={
+    "type": "shutdown_request",
+    "reason": "audit loop <N> complete; outcome XML captured"
+  }
+)
+```
+
+The teammate replies with `{type: "shutdown_response", approve: true}`. If `approve` is `false`, exit reason = `error: bugfind teammate refused shutdown` → Step 4 teardown then Step 5 revoke.
+
+`last_action = "audited"`. Append audit metadata to `audit_log`.
+
+### Parallel auditors (`loop_count >= 4`)
+
+The pre-audit gate must pass immediately before this step. After three full audit/fix rounds without convergence, issue three `Agent` calls in **one** assistant message so they run in parallel:
+
+```
+Agent(subagent_type="code-quality-agent", name="bugfind-loop-<N>-a", team_name="<team_name>", model="sonnet", description="Bugfind audit loop <N> variant a", prompt="<audit XML; write outcome to .bugteam-loop-<N>.outcomes.xml; post the per-loop review; read and merge b/c outcomes from <team_temp_dir>/loop-<N>-b.outcomes.xml and <team_temp_dir>/loop-<N>-c.outcomes.xml>")
+Agent(subagent_type="code-quality-agent", name="bugfind-loop-<N>-b", team_name="<team_name>", model="sonnet", description="Bugfind audit loop <N> variant b", prompt="<audit XML; write outcome to <team_temp_dir>/loop-<N>-b.outcomes.xml; skip PR posting>")
+Agent(subagent_type="code-quality-agent", name="bugfind-loop-<N>-c", team_name="<team_name>", model="sonnet", description="Bugfind audit loop <N> variant c", prompt="<audit XML; write outcome to <team_temp_dir>/loop-<N>-c.outcomes.xml; skip PR posting>")
+```
+
+Teammate `-a` is the post-owner: read all three outcome XML files at explicit absolute paths (`.bugteam-loop-<N>.outcomes.xml` in cwd, plus sibling paths under `<team_temp_dir>`), merge findings by `(file, line, category_letter)` (collapse duplicates, keep longest description and highest severity), re-assign merged IDs as `loopN-K`, post the single per-loop review. The `-a` prompt must embed sibling paths as literal absolutes so `Read` works without discovery.
+
+Shutdown order: parallel `SendMessage` to `b` and `c`, then `a`:
+
+```
+SendMessage(to="bugfind-loop-<N>-b", message={"type": "shutdown_request", "reason": "variant XML captured"})
+SendMessage(to="bugfind-loop-<N>-c", message={"type": "shutdown_request", "reason": "variant XML captured"})
+```
+
+then
+
+```
+SendMessage(to="bugfind-loop-<N>-a", message={"type": "shutdown_request", "reason": "merged review posted"})
+```
+
+## FIX action (fresh teammate)
+
+`Agent` shape in `SKILL.md`. The teammate sees only the latest audit’s findings — each `Agent` call starts with a fresh context window; prior-loop findings, fix history, and chat stay in the lead.
+
+Pass finding comment URL and id for each finding (from `loop_comment_index`) in the XML prompt so the teammate owns replies. After commit: one reply per finding (`Fixed in <commit_sha>` or `Could not address this loop: <one-line reason>`). Same identity model as bugfind: teammate posts; lead waits.
+
+After replies, the teammate writes outcome XML (schema in [`../PROMPTS.md`](../PROMPTS.md)).
+
+### Shutdown (bugfix)
+
+Same self-termination vs `SendMessage` split as bugfind. Fallback message:
+
+```
+SendMessage(
+  to="bugfix",
+  message={
+    "type": "shutdown_request",
+    "reason": "fix loop <N> complete; commit <sha7> pushed"
+  }
+)
+```
+
+`approve: false` → `error: bugfix teammate refused shutdown` → Step 4 then 5.
+
+Substitute placeholders from `last_findings` into the fix prompt per [`../PROMPTS.md`](../PROMPTS.md).
+
+**Verify push:** `git rev-parse HEAD` after fix must differ from before; new HEAD must exist on `origin/<branch>` (`git fetch origin <branch> && git rev-parse origin/<branch>` matches `HEAD`). If HEAD did not change → `stuck — bugfix teammate could not address findings`.
+
+`last_action = "fixed"`. Append fix line to `audit_log`.

package/skills/bugteam/reference/design-rationale.md

@@ -0,0 +1,28 @@
+# Design rationale
+
+## Core principle (expanded)
+
+A Claude Code **agent team** runs the audit-and-fix loop until convergence. The bugfind teammate audits clean-room (own context window, no chat history); the bugfix teammate addresses each audit's findings; both spawn fresh per loop. A 10-loop hard cap prevents runaway cost. Project permissions are granted at session start and revoked at session end.
+
+Teammate isolation versus subagents returning into the lead’s context is the clean-room property. Verbatim Anthropic quotes and URLs: [`../sources.md`](../sources.md).
+
+## Why not parallel subagents here
+
+Subagents return their results into the lead’s context, which accumulates across loops. Agent-team teammates are independent sessions with their own context windows and do not pollute the lead. The lead can shut down and respawn each loop so every audit starts fresh. For `/bugteam`, the independent-context property is required; parallel subagents fail the clean-room requirement. Supporting quotes: [`../sources.md`](../sources.md) (subagents vs agent teams).
+
+## Table of contents in `SKILL.md`
+
+The top-of-file list exists so partial reads (for example `head -100`) still show scope. Anthropic guidance: [Structure longer reference files with table of contents](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices#structure-longer-reference-files-with-table-of-contents).
+
+## When `/bugteam` applies (narrative)
+
+The user wants automated convergence on a clean PR without babysitting each step. Typed `/bugteam` once means full authorization for up to ten audit cycles and the corresponding fix commits.
+
+### Refusal reasons (detail)
+
+- **Agent teams off:** Without the feature flag, the workflow cannot run.
+- **No PR / diff:** There is nothing scoped to audit.
+- **Dirty tree:** The fix teammate will commit; uncommitted local work would be mixed into automated commits.
+- **Missing subagents:** Both `code-quality-agent` and `clean-coder` must exist in the environment before Step 0.
+
+Exact refusal strings remain in `SKILL.md`.

package/skills/bugteam/reference/github-pr-reviews.md

@@ -0,0 +1,86 @@
+# GitHub PR comments (Step 2.5)
+
+Per-loop pull-request reviews: findings render as a tree under one parent review (similar to Cursor Bugbot). **Teammates own all PR comment posting** — bugfind posts the review (parent body plus child finding comments in one batched POST); bugfix posts fix replies. Comment, review, and reply POSTs belong to teammates. The lead’s single PR write is the final description rewrite at Step 4.5 (`pr-description-writer`).
+
+- **Per-loop review** — One `POST /pulls/<number>/reviews` per loop, posted by the bugfind teammate **after** auditing. The review body is the loop header (audit counts); the review’s `comments[]` array holds one anchored finding per P0/P1/P2 finding. GitHub renders a single collapsible thread with each finding as a child comment.
+
+- **Fix replies** — Reply to each child finding comment after the commit lands. Body: `Fixed in <commit_sha>` if addressed, or `Could not address this loop: <one-line reason>` if not. The `/pulls/<number>/comments/<id>/replies` endpoint works on any review comment, including those created as part of a review.
+
+**Ordering:** Bugfind audits first, buffers findings, validates anchors against the captured diff, then posts the review **once** at the end. The review body states the finding count authoritatively. Keep all posting in that single end-of-loop review POST.
+
+## CLI shapes (teammate)
+
+All three POSTs use the same pattern: build JSON with `jq` (`--rawfile` or `-Rs` so markdown with backticks, newlines, and quotes survives intact), then pipe to `gh api ... --input -` on stdin. This avoids shell-quoting edge cases.
+
+### Per-loop review (one POST creates parent + children)
+
+Build `comments[]` programmatically from buffered, diff-anchored findings. Single-line shape: `{path, line, side: "RIGHT", body: <finding markdown>}`. Multi-line: `{path, start_line, start_side: "RIGHT", line, side: "RIGHT", body: ...}` (all four anchor fields required).
+
+```
+jq -n \
+  --rawfile review_body <tmp_review_body.md> \
+  --arg commit_id "$(git rev-parse HEAD)" \
+  --rawfile finding_body_1 <tmp_finding_1.md> \
+  --arg path_1 "<file_1>" \
+  --argjson line_1 <line_1> \
+  [... one finding_body_K / path_K / line_K triple per anchored finding ...] \
+  '{
+     commit_id: $commit_id,
+     event: "COMMENT",
+     body: $review_body,
+     comments: [
+       {path: $path_1, line: $line_1, side: "RIGHT", body: $finding_body_1}
+       [, ... one object per anchored finding ...]
+     ]
+   }' \
+| gh api repos/<owner>/<repo>/pulls/<number>/reviews -X POST --input -
+```
+
+Response JSON includes the parent review `id` / `html_url` and a `comments` array of child comments (`id`, `html_url`). Harvest children in index order and align with the finding list.
+
+### Fix reply
+
+```
+jq -Rs '{body: .}' < <tmp_reply.md> \
+| gh api repos/<owner>/<repo>/pulls/<number>/comments/<finding_comment_id>/replies -X POST --input -
+```
+
+### Review POST failure fallback
+
+Top-level PR comment via issue-comments (`{issue_number}` is the PR number):
+
+```
+jq -Rs '{body: .}' < <tmp_fallback.md> \
+| gh api repos/<owner>/<repo>/issues/<number>/comments -X POST --input -
+```
+
+`<head_sha_at_post_time>` is the SHA at post time (`git rev-parse HEAD` in the teammate’s working directory immediately before the POST). The review anchors finding comments to the head SHA at audit time (before this loop’s fix lands).
+
+Write each body (review body and every per-finding body) to its own temp file before the `jq` pipeline. Bodies stay inside files the pipeline reads — they reach GitHub inside the JSON payload — which keeps them compatible with the `gh-body-backtick-guard` hook that scans command-line `--body` arguments.
+
+## Review body template (`<tmp_review_body.md>`)
+
+```
+## /bugteam loop <N> audit: <P0>P0 / <P1>P1 / <P2>P2
+
+<if any findings could not be anchored to a diff line, include this section:>
+### Findings without a diff anchor
+
+- **[severity] title** — <file>:<line> — <one-line description>
+```
+
+If the audit returns zero findings, still post **one** review with `event=COMMENT`, empty `comments[]`, and body `## /bugteam loop <N> audit: 0P0 / 0P1 / 0P2 → clean` so each loop’s section is self-contained on the PR.
+
+## Anchor-validation fallback (teammate)
+
+GitHub rejects the entire review POST if any `comments[]` entry targets a line not in the diff. Before posting, validate every finding’s `(file, line)` against the captured diff. Findings not in the diff are **not** added to `comments[]`; list them in the review body under `### Findings without a diff anchor`. Outcome XML: `used_fallback="true"`, `finding_comment_id=""`, `finding_comment_url=<review_url>` (parent URL when there is no child). Log fallback count in outcome XML for the lead’s final report. The loop continues; anchor mismatch does not abort.
+
+## Review POST failure fallback
+
+If the review POST fails (rate limit, network, malformed payload), fall back to one top-level issue comment containing the review body plus every finding inline (severity, file:line, description). Every finding in that run: `used_fallback="true"`, `finding_comment_url` = issue-comment URL. Use the issue-comment CLI shape above.
+
+## GitHub REST endpoints
+
+- Per-loop batched review: `POST /repos/{owner}/{repo}/pulls/{pull_number}/reviews` (required: `body`, `event=COMMENT`, `commit_id`; optional `comments[]` — each entry needs `path`, `body`, `line`, `side`)
+- Fix reply: `POST /repos/{owner}/{repo}/pulls/{pull_number}/comments/{comment_id}/replies` (required: `body`)
+- Review-POST failure fallback: `POST /repos/{owner}/{repo}/issues/{issue_number}/comments` (required: `body`; `{issue_number}` is the PR number)

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

@@ -0,0 +1,51 @@
+# Team setup and loop state
+
+## Step 0 — Grant project permissions (detail)
+
+Before spawning any teammates, grant the team session write access to the project’s `.claude/**` tree. Command in `SKILL.md`.
+
+`${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.
+
+The script reads `Path.cwd()` and writes idempotent allow rules into `~/.claude/settings.json`. Run from the project root. If it fails (non-zero exit), surface the error and stop — do not proceed without the grant.
+
+This is the **first** action of every `/bugteam` invocation, before any team creation or agent spawn. The corresponding revoke runs at Step 5 regardless of how the cycle exits.
+
+## Step 1 — Resolve PR scope (detail)
+
+Same resolution path as `/findbugs`:
+
+1. `gh pr view --json number,baseRefName,headRefName,url` from the working directory.
+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 — Create the agent team (detail)
+
+This session is the **team lead**. Create the team with `TeamCreate` using the exact argument shape in `SKILL.md`.
+
+`<team_name>` is built under **Team name** below (sanitization + timestamp already applied). `TeamCreate` matches natural-language team creation in the product docs; quote in [`../sources.md`](../sources.md).
+
+### Team specification
+
+- **Team name:** `bugteam-pr-<number>-<YYYYMMDDHHMMSS>` (or `bugteam-<sanitized-head-branch>-<YYYYMMDDHHMMSS>` if no PR). The timestamp is captured at team-creation time from the lead session and prevents two concurrent invocations on the same PR from colliding.
+
+- **Branch-name sanitization (no-PR fallback only):** Before substituting `<head-branch>` into the `team_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`; `team_name` becomes `bugteam-feat-foo-bar-<YYYYMMDDHHMMSS>`. Apply sanitization when `team_name` is first assembled so every downstream use (team creation, scoped temp dir, cleanup) sees the safe form.
+
+- **Per-team temp directory (resolved once, reused everywhere):** After `team_name` is captured, resolve a portable absolute path with a Claude-side lookup using Python’s `tempfile.gettempdir()`, which honors `TMPDIR`, `TEMP`, and `TMP` in the platform-correct order and falls back to `C:\Users\<user>\AppData\Local\Temp` on Windows or `/tmp` on Unix: `Path(tempfile.gettempdir()) / team_name` (requires `import tempfile`). The `team_name` value already carries the `bugteam-` prefix; keep it as-is here. Let `tempfile.gettempdir()` perform the lookup; use its result directly. Capture the resolved absolute path as `<team_temp_dir>` and pass that literal path to every shell command that follows. Claude performs all temp-root resolution so every shell (bash, cmd.exe, PowerShell) receives the same literal absolute value.
+
+- **Roles defined up front (spawned per loop, not at team creation):**
+  - `bugfind` — teammate role `code-quality-agent`, model sonnet
+  - `bugfix` — teammate role `clean-coder`, model sonnet
+
+- **Display mode:** inherit the user’s default (`teammateMode` in `~/.claude.json`); do not override.
+
+Reference teammate role definitions by name when spawning. Doc quote on subagent scopes: [`../sources.md`](../sources.md).
+
+### 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_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.

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

@@ -0,0 +1,70 @@
+# Utility scripts, teardown, PR body, permissions, report
+
+## Utility scripts (progressive disclosure)
+
+Fragile or repeatable shell sequences belong in `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. Details: [`../scripts/README.md`](../scripts/README.md).
+
+### Pre-flight (recommended before Step 0)
+
+From the repository root, run the command in `SKILL.md`. If the exit code is non-zero, stop and fix failing checks before granting permissions. Optional: `BUGTEAM_PREFLIGHT_SKIP=1` skips pre-flight (emergency only). Optional: `--pre-commit` when `.pre-commit-config.yaml` exists.
+
+## Step 4 — Tear down the team and clean working tree
+
+When the cycle exits (any reason), run these steps in order from **this** session (the lead).
+
+1. **Confirm every teammate has shut down.** Any teammate still alive (for example, from an aborted shutdown mid-loop) must receive a shutdown message first. For each remaining teammate name:
+
+   ```
+   SendMessage(to="<teammate_name>", message={"type": "shutdown_request", "reason": "bugteam cycle ending"})
+   ```
+
+   Product docs: the lead’s cleanup checks for active teammates — shut them down first. Verbatim quote: [`../sources.md`](../sources.md) (lead cleanup).
+
+   If any teammate returns `approve: false` during cleanup, log the name (for example `cleanup warning: <teammate_name> refused shutdown_request`) and **still** proceed to `TeamDelete`. `TeamDelete` may fail if teammates remain; if so, surface the error in the final report. Do not abort the sequence — continue through temp-dir deletion, Step 4.5, and Step 5.
+
+2. **Clean up the team** with `TeamDelete()` (no arguments — reads `<team_name>` from session context). Maps to “clean up the team” in the docs; quote: [`../sources.md`](../sources.md).
+
+3. **Delete the per-team temp directory** using the Python one-liner in `SKILL.md` with the same literal `<team_temp_dir>` from Step 2. `shutil.rmtree(..., ignore_errors=True)` is portable across Windows and Unix.
+
+## Step 4.5 — Finalize the PR description (mandatory)
+
+After teardown and before permission revoke, the lead rewrites the PR body to the PR’s **final cumulative state** — what the change delivers, not the bugteam process. This is the **only** PR-write the lead performs (audit and fix comments stay with teammates).
+
+The lead delegates body text to the `pr-description-writer` agent so the global mandatory-pr-description-writer hook accepts the subsequent `gh pr edit`. The lead does **not** compose the body inline.
+
+`pr-description-writer` comes from the global git-workflow rule in `claude-code-config`. Invoke with `Agent`:
+
+```
+Agent(
+  subagent_type="pr-description-writer",
+  description="Rewrite PR <number> body from cumulative diff",
+  prompt="<brief from steps below>"
+)
+```
+
+If that subagent is missing, fall back to `general-purpose` with the same brief — the hook treats agent-authored bodies the same. If neither exists, log a warning and skip Step 4.5.
+
+**Steps:**
+
+1. Capture cumulative diff: `gh pr diff <number> -R <owner>/<repo> > .bugteam-final.diff`.
+2. Capture original body: `gh pr view <number> -R <owner>/<repo> --json body --jq .body > .bugteam-original-body.md`.
+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.
+   - **Output:** new body markdown.
+4. Write `.bugteam-final-body.md`.
+5. `gh pr edit <number> -R <owner>/<repo> --body-file .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`.
+
+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.

package/skills/bugteam/scripts/README.md

@@ -6,6 +6,10 @@ Scripts in this directory are **executed** by the lead or teammates. They are no
 |--------|---------|
 | `bugteam_preflight.py` | Run pytest (when configured) and optional `pre-commit` before `/bugteam`. |
 | `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). |
 
 ## `bugteam_preflight.py`