claude-dev-env 1.38.1 → 1.40.0

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

@@ -1,5 +1,82 @@
 # Gate, cycle, AUDIT, and FIX
 
+## Pre-cycle: walk prior bugteam reviews end-first
+
+**Pre-cycle: walk prior bugteam reviews end-first** (once per PR, after Step 2
+and before iteration begins, when `last_action == "fresh"`). A re-invocation of
+`/bugteam` on a PR with prior loops detects whether the most recent loop already
+cleaned this HEAD (short-circuit) and otherwise records that prior loops were
+dirty so the AUDIT runs against the latest diff with that signal in mind:
+
+```python
+dirty_review_count = 0
+all_reviews = pull_request_read(
+    method="get_reviews", pullNumber=N, owner=O, repo=R
+)
+
+NEW_BUGTEAM_HEADER_PREFIX = "**Bugteam audit completed**"
+LEGACY_BUGTEAM_HEADER_PREFIX = "## /bugteam loop "
+NEW_CLEAN_STATE_LABEL = "Clean — no findings"
+LEGACY_CLEAN_TOKEN = "→ clean"
+
+
+def is_bugteam_review(review_body: str) -> bool:
+    return (
+        review_body.startswith(NEW_BUGTEAM_HEADER_PREFIX)
+        or review_body.startswith(LEGACY_BUGTEAM_HEADER_PREFIX)
+    )
+
+
+def is_clean_bugteam_review(review_body: str) -> bool:
+    if review_body.startswith(NEW_BUGTEAM_HEADER_PREFIX):
+        return NEW_CLEAN_STATE_LABEL in review_body.splitlines()[0]
+    return review_body.rstrip().endswith(LEGACY_CLEAN_TOKEN)
+
+
+prior_reviews = [
+    rev for rev in all_reviews
+    if is_bugteam_review(rev.get("body", ""))
+]
+prior_reviews.sort(key=lambda rev: rev["submitted_at"], reverse=True)
+```
+
+The classifier handles both shapes. The new shape — emitted by
+`_shared/pr-loop/scripts/post_audit_thread.py` reading
+`_shared/pr-loop/audit-reply-template.md` at runtime — opens with
+`**Bugteam audit completed** —— Clean — no findings` on CLEAN and
+`**Bugteam audit completed** —— Findings requested` on DIRTY. The legacy
+shape — emitted before `post_audit_thread.py` became canonical — opens
+with `## /bugteam loop <N> audit:` and ends with `→ clean` on CLEAN. Both
+shapes are recognized so re-invocations on long-lived branches with
+mixed-shape history classify correctly.
+
+Iterate from index 0 (most recent) toward older entries:
+
+- A bugteam review body whose first line carries the
+  `Clean — no findings` state label (new shape) or whose body ends with
+  `→ clean` (legacy shape) is **clean**; any other bugteam review body
+  is **dirty**.
+- For a dirty review, increment `dirty_review_count` by one. The review's
+  specific finding bodies are not carried forward —
+  bugteam's AUDIT regenerates
+  findings against the current HEAD's diff each loop, so prior bodies are stale
+  by definition. The count alone is the carried signal.
+- Stop at the first clean review. Older reviews are presumed addressed at that
+  clean checkpoint and are not re-read.
+- When index 0 is itself clean AND its `commit_id` matches `git rev-parse HEAD`,
+  the PR is already converged on this HEAD — set `last_action="audited"`,
+  `last_findings='{"total": 0}'`, fall through to step 1's `converged` exit,
+  skip Step 3 iteration entirely.
+- When `dirty_review_count > 0`, log the count and proceed into the normal
+  iteration; the next AUDIT regenerates anchored findings against the current
+  HEAD so `loop_comment_index` stays correct. Unlike `pr-converge` — where
+  Cursor Bugbot's prior dirty-review *bodies* are read back by the Fix protocol
+  because each dirty body lists specific findings the loop must still address
+  —
+  bugteam's per-loop bodies are anchored to the diff at *that loop's* HEAD, so
+  re-applying them against a newer diff would be incorrect. The count is
+  sufficient signal that "prior loops did not converge here."
+
 ## Step 3 — The cycle (full detail)
 
 Repeat until an exit condition fires.
@@ -22,12 +99,12 @@ Repeat until an exit condition fires.
       `git merge-base` + `git diff --name-only` live inside the script; see [`../../../_shared/pr-loop/scripts/README.md`](../../../_shared/pr-loop/scripts/README.md) for what lives under this directory, and [`../../../_shared/pr-loop/code-rules-gate.md`](../../../_shared/pr-loop/code-rules-gate.md) for gate-only merge-base / invocation semantics. 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).
+   3. If exit code **non-zero** → spawn a new **clean-coder** teammate (`mode="bypassPermissions"`) — **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 > 20`, exit reason = `cap reached` (counts **audits**, not standards-only rounds).
    5. Execute **AUDIT action** (spawn bugfind). Print progress: `Loop <L> 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`.
+   1. Increment `loop_count`. If `loop_count > 20`, exit reason = `cap reached`.
    2. Execute **FIX action** (spawn bugfix clean-coder for audit findings). Print: `Loop <L> fix: commit ...`
    3. Set `last_action = "fixed"`, update `audit_log`, loop to step 1 (next iteration hits **pre-audit path** before the next AUDIT).
 
@@ -37,53 +114,47 @@ Repeat until an exit condition fires.
 
 **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-PR scoped directory so concurrent `/bugteam` runs keep patches isolated. Use the literal `<run_temp_dir>` resolved once in Step 2 — Claude resolves the absolute path; every shell receives the same literal value.
+## AUDIT action
 
-Commands and `Agent(...)` shape: `SKILL.md`.
+Spawn one audit agent that walks all A–K categories:
 
-`<run_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-pr<N>-loop<L>.outcomes.xml` from the worktree directory with the `Read` tool, parses it, and populates `loop_comment_index` from `<finding>` elements.
-
-### Shutdown (bugfind)
+```
+Agent(
+  subagent_type="code-quality-agent",
+  name="bugfind-pr<N>-loop<L>",
+  model="opus",
+  run_in_background=true,
+  description="Audit {owner}/{repo}#{N} loop {L}",
+  prompt="<output of build_audit_prompt.py; see ../../_shared/pr-loop/scripts/build_audit_prompt.py>"
+)
+```
 
-Teammates self-terminate when complete — the background-completion notification arrives and the lead reads the outcomes XML. If the notification does not arrive within the lead timeout (120s), treat as a hard blocker and abort the loop.
+The audit prompt XML is emitted by
+[`build_audit_prompt.py`](../../_shared/pr-loop/scripts/build_audit_prompt.py).
+Run it with `--owner --repo --pr-number --loop --head-ref --base-ref --worktree-path --run-temp-dir`
+to generate the complete `<spawn_prompt>` XML on stdout.
 
 `last_action = "audited"`. Append audit metadata to `audit_log`.
 
-### Parallel auditors (`loop_count >= 4`)
+## FIX action (fresh teammate)
 
-The pre-audit gate must pass immediately before this step. After three full audit/fix rounds without convergence, issue eleven `Agent` calls in **one** assistant message so they run in parallel:
+Spawn:
 
 ```
-Agent(subagent_type="code-quality-agent", name="bugfind-pr<N>-loop<L>-a", team_name="<team_name>", model="opus", run_in_background=true, description="Bugfind audit PR <N> loop <L> validator", prompt="<audit XML; poll for all 10 sibling XMLs at <run_temp_dir>/pr-<N>/loop-<L>-b.outcomes.xml through <run_temp_dir>/pr-<N>/loop-<L>-k.outcomes.xml (60s timeout, 2s interval); on timeout: log diagnostics entry, proceed with validated findings from available XMLs; validate each finding: file exists, line in bounds, excerpt matches claimed line, category A-J, severity P0/P1/P2; quarantine hallucinated findings to <run_temp_dir>/pr-<N>/loop-<L>-diagnostics.json under validator_rejected; de-dup by (file, line, category), max severity wins, keep longest description on conflict; re-id as loop<L>-<K>; write <worktree_path>/.bugteam-pr<N>-loop<L>.outcomes.xml; post review>")
-Agent(subagent_type="code-quality-agent", name="bugfind-pr<N>-loop<L>-b", team_name="<team_name>", model="haiku", run_in_background=true, description="Bugfind audit PR <N> loop <L> variant b", prompt="<audit XML; write outcome to <run_temp_dir>/pr-<N>/loop-<L>-b.outcomes.xml; skip PR posting>")
-Agent(subagent_type="code-quality-agent", name="bugfind-pr<N>-loop<L>-c", team_name="<team_name>", model="haiku", run_in_background=true, description="Bugfind audit PR <N> loop <L> variant c", prompt="<audit XML; write outcome to <run_temp_dir>/pr-<N>/loop-<L>-c.outcomes.xml; skip PR posting>")
-Agent(subagent_type="code-quality-agent", name="bugfind-pr<N>-loop<L>-d", team_name="<team_name>", model="haiku", run_in_background=true, description="Bugfind audit PR <N> loop <L> variant d", prompt="<audit XML; write outcome to <run_temp_dir>/pr-<N>/loop-<L>-d.outcomes.xml; skip PR posting>")
-Agent(subagent_type="code-quality-agent", name="bugfind-pr<N>-loop<L>-e", team_name="<team_name>", model="haiku", run_in_background=true, description="Bugfind audit PR <N> loop <L> variant e", prompt="<audit XML; write outcome to <run_temp_dir>/pr-<N>/loop-<L>-e.outcomes.xml; skip PR posting>")
-Agent(subagent_type="code-quality-agent", name="bugfind-pr<N>-loop<L>-f", team_name="<team_name>", model="haiku", run_in_background=true, description="Bugfind audit PR <N> loop <L> variant f", prompt="<audit XML; write outcome to <run_temp_dir>/pr-<N>/loop-<L>-f.outcomes.xml; skip PR posting>")
-Agent(subagent_type="code-quality-agent", name="bugfind-pr<N>-loop<L>-g", team_name="<team_name>", model="haiku", run_in_background=true, description="Bugfind audit PR <N> loop <L> variant g", prompt="<audit XML; write outcome to <run_temp_dir>/pr-<N>/loop-<L>-g.outcomes.xml; skip PR posting>")
-Agent(subagent_type="code-quality-agent", name="bugfind-pr<N>-loop<L>-h", team_name="<team_name>", model="haiku", run_in_background=true, description="Bugfind audit PR <N> loop <L> variant h", prompt="<audit XML; write outcome to <run_temp_dir>/pr-<N>/loop-<L>-h.outcomes.xml; skip PR posting>")
-Agent(subagent_type="code-quality-agent", name="bugfind-pr<N>-loop<L>-i", team_name="<team_name>", model="haiku", run_in_background=true, description="Bugfind audit PR <N> loop <L> variant i", prompt="<audit XML; write outcome to <run_temp_dir>/pr-<N>/loop-<L>-i.outcomes.xml; skip PR posting>")
-Agent(subagent_type="code-quality-agent", name="bugfind-pr<N>-loop<L>-j", team_name="<team_name>", model="haiku", run_in_background=true, description="Bugfind audit PR <N> loop <L> variant j", prompt="<audit XML; write outcome to <run_temp_dir>/pr-<N>/loop-<L>-j.outcomes.xml; skip PR posting>")
-Agent(subagent_type="code-quality-agent", name="bugfind-pr<N>-loop<L>-k", team_name="<team_name>", model="haiku", run_in_background=true, description="Bugfind audit PR <N> loop <L> variant k", prompt="<audit XML; write outcome to <run_temp_dir>/pr-<N>/loop-<L>-k.outcomes.xml; skip PR posting>")
+Agent(
+  subagent_type="clean-coder",
+  name="bugfix-pr<N>-loop<L>",
+  model="opus",
+  mode="bypassPermissions",
+  run_in_background=true,
+  description="Bugfix PR <N> loop <L>",
+  prompt="<output of build_fix_prompt.py; see ../../_shared/pr-loop/scripts/build_fix_prompt.py>"
+)
 ```
 
-Teammate `-a` is the opus validator: polls for all 10 sibling XMLs at explicit absolute paths under `<run_temp_dir>/pr-<N>` (60s timeout, 2s interval; on timeout: log diagnostics entry, proceed with validated findings from available XMLs), then validates each finding — file exists, line in bounds, excerpt matches claimed line, category is A–J, severity is P0/P1/P2. Hallucinated findings are quarantined to `<run_temp_dir>/pr-<N>/loop-<L>-diagnostics.json` under `validator_rejected`. Valid findings are de-duplicated by `(file, line, category)` (max severity wins, keep longest description on conflict) and re-assigned merged IDs as `loop<L>-<K>`. The `-a` prompt must embed sibling paths as literal absolutes so `Read` works without discovery.
-
-All subagents self-terminate via background completion. The lead awaits only the validator (-a) notification (120s timeout). Missing notification → hard blocker.
-
-## 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.
+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.
+Pass finding comment URL, comment id, and thread node id for each finding (from `loop_comment_index`) in the XML prompt so the teammate owns both the reply and the thread resolution. After commit, the teammate posts one reply per finding using the unified template at [`../../../_shared/pr-loop/audit-reply-template.md`](../../../_shared/pr-loop/audit-reply-template.md) — the full header / horizontal rule / `<action_heading> ✅` / explanation / anchored-bullet / closing-paragraph skeleton, with `<status_line>` set per the path (`Fixed in <short_sha>` for `status=fixed`, `Could not address this loop` for `status=could_not_address`, `Hook blocked the fix commit` for `status=hook_blocked`). Per-thread reply and `resolve_thread` are atomic — see [`../../../_shared/pr-loop/fix-protocol.md`](../../../_shared/pr-loop/fix-protocol.md) step 12 for the exact sequence. Same identity model as bugfind: teammate posts; lead waits.
 
 After replies, the teammate writes outcome XML (schema in [`../PROMPTS.md`](../PROMPTS.md)).
 
@@ -93,8 +164,10 @@ Same self-termination model as bugfind. Missing notification → hard blocker.
 
 `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).
+Substitute placeholders from `last_findings` into the fix prompt per [`../PROMPTS.md`](../PROMPTS.md). The spawn XML includes TaskCreate/self_audit_checklist for task tracking — the FIX subagent MUST create tasks before starting.
 
 **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`.
 
+**Scope verification.** Run `git diff HEAD~1 --name-only` and compare against the set of files referenced in `bugs_to_fix`. When the commit touches files NOT in the `bugs_to_fix` list, judge whether the extras are a coherent part of the fix: a shared helper the auditor did not think to name, a test file that exercises the fix, a config update the fix requires. If the extras are coherent with the fix, note them in the outcome XML's `<scope_notes>` and keep the outcome as `fixed`. If the extras look unrelated, suspicious, or out of scope, downgrade to `unverified_fixed` with reason `commit touched unexpected files: <list>`. The auditor's file list is a default, not a contract — the fix's coherence is the contract.
+
 `last_action = "fixed"`. Append fix line to `audit_log`.

package/skills/bugteam/reference/audit-contract.md

@@ -21,7 +21,7 @@ Each finding an audit produces MUST be one of exactly two shapes.
   "id": "loop<L>-<K>",
   "file": "path/relative/to/repo/root.py",
   "line": 123,
-  "category": "A | B | C | D | E | F | G | H | I | J",
+  "category": "A | B | C | D | E | F | G | H | I | J | K",
   "severity": "P0 | P1 | P2",
   "excerpt": "verbatim code snippet from the offending line(s)",
   "failure_mode": "one sentence describing what goes wrong and when",
@@ -37,7 +37,7 @@ Used when an audit investigates a category and does NOT find a bug. Bare "verifi
 
 ```json
 {
-  "category": "A | B | C | D | E | F | G | H | I | J",
+  "category": "A | B | C | D | E | F | G | H | I | J | K",
   "files_opened": ["file1.py", "file2.py"],
   "lines_quoted": [
     {"file": "file1.py", "line": 88, "text": "verbatim line content"}
@@ -89,25 +89,7 @@ After the primary finding list is complete, every audit runs a second pass again
 
 The audit must either produce new Shape A findings citing new file:line references not present in the first pass, or cite explicit Shape B adversarial-probe entries for each category it re-examined. An adversarial pass that returns "nothing new, confident first pass was complete" is REJECTED — produce evidence or findings, not confidence.
 
-## Haiku secondary auditor
-
-For single-subagent skills (`/qbug`, `/findbugs`) the LEAD spawns two `Agent()` calls in one message:
-
-- **Primary** — `subagent_type=clean-coder`, `model=sonnet` (for qbug cycle) or `subagent_type=code-quality-agent`, `model=sonnet` (for findbugs clean-room).
-- **Secondary (Haiku)** — `subagent_type=code-quality-agent`, `model=haiku`, same self-contained clean-room prompt shape used by `/findbugs`.
-
-Both audit the same diff. The secondary returns findings to the LEAD only — never posted to the PR.
-
-Merge rules:
-
-- **De-dup key**: `(file, line, category)`.
-- **Severity conflict**: max wins (P0 > P1 > P2).
-- **Unique-to-Haiku findings**: added to the primary set with Haiku's severity and source annotation.
-- **Unique-to-primary findings**: kept as-is.
-- **Zero Haiku findings**: primary set trusted; proceed.
-- **Malformed or non-parseable Haiku output**: lead trusts the primary set, logs the event in `loop-<L>-diagnostics.json` under `haiku_findings` as `[{"parse_error": "<message>"}]`.
-
-For multi-subagent skills (`/bugteam`) the parallel-auditors pattern in [`audit-and-teammates.md`](audit-and-teammates.md) already provides cross-model coverage via 10 haiku auditors + opus validator.
+For `/bugteam`, the single audit agent provides per-category coverage by walking all A–K rubrics in one invocation.
 
 ## Post-fix self-audit
 
@@ -120,7 +102,7 @@ Sequence:
 3. Run `py_compile` (or language-equivalent) on each modified file.
 4. Compute `fix_diff` against pre-fix contents for the modified set.
 5. Run `bugteam_code_rules_gate.py` with explicit paths for every modified file.
-6. Spawn a scoped audit of `fix_diff` with full A–J rigor, Shape A/B contract, adversarial pass, AND Haiku secondary in parallel (paranoid mode on post-fix).
+6. Spawn a scoped audit of `fix_diff` with full A–K rigor, Shape A/B contract, adversarial pass, AND Haiku secondary in parallel (paranoid mode on post-fix).
 7. Any new findings become same-loop fix-targets. Internal iteration count increments by one.
 8. After 3 internal iterations with fresh findings each time, exit `stuck: post-fix audit not converging`.
 9. Only when `gate_findings` empty AND `post_fix_findings` empty: `git add`, commit, push.

package/skills/bugteam/reference/copilot-gap-analysis.md

@@ -155,7 +155,7 @@ Each section names exactly one target file, the literal text or regex to add, an
 **Verification step (one line, no `$(...)`):**
 
 ```
-python C:/Users/jon/.claude/skills/bugteam/scripts/bugteam_code_rules_gate.py /tmp/pr70_writer.py /tmp/pr70_summary.py /tmp/pr73_constants.py /tmp/pr73_writer.py
+python $HOME/.claude/skills/bugteam/scripts/bugteam_code_rules_gate.py /tmp/pr70_writer.py /tmp/pr70_summary.py /tmp/pr73_constants.py /tmp/pr73_writer.py
 ```
 
 Run after the K and L deterministic detectors land in §c/d below; the categories M and N stay rubric-only and are exercised by replaying PR #70 / PR #73 through `/bugteam` with the new PROMPTS.md and observing that the audit posts findings keyed to lines 158 (M), 125 (rubric N — naming clarity), 263 (rubric N — PR-description drift), 361 (initial/final standards review — file length), and 206 (N — wrapper plumb-through).
@@ -348,7 +348,7 @@ Wire into `run_gate` the same way as Detector 1, by appending its output to `iss
 **Verification step:**
 
 ```
-python C:/Users/jon/.claude/skills/bugteam/scripts/bugteam_code_rules_gate.py /tmp/pr70_writer.py /tmp/pr70_summary.py /tmp/pr73_constants.py /tmp/pr73_writer.py /tmp/pr73_tracker.py
+python $HOME/.claude/skills/bugteam/scripts/bugteam_code_rules_gate.py /tmp/pr70_writer.py /tmp/pr70_summary.py /tmp/pr73_constants.py /tmp/pr73_writer.py /tmp/pr73_tracker.py
 ```
 
 Expected output after the patch lands: at minimum one `Column-name string magic 'theme_name' - extract to config` line on `pr70_writer.py` (Copilot id 3153098661) and one `Wrapper 'flush' drops optional kwargs ['loud_banner_stream'] of delegate 'flush'` line on `pr73_tracker.py` (Copilot id 3153475331).
@@ -488,13 +488,16 @@ def check_library_print(content: str, file_path: str) -> list[str]:
         all_issues.extend(check_library_print(content, file_path))
 ```
 
-**Verification step:**
+**Verification step** — invoke the
+[`probe_code_rules_enforcer_check.py`](../scripts/probe_code_rules_enforcer_check.py)
+script (which dynamically loads `code_rules_enforcer` and runs the named
+detector against a fixture):
 
 ```
-python -c "import importlib.util, sys; spec=importlib.util.spec_from_file_location('e','C:/Users/jon/.claude/hooks/blocking/code_rules_enforcer.py'); m=importlib.util.module_from_spec(spec); spec.loader.exec_module(m); content=open('/tmp/pr73_constants.py').read(); print(m.check_collection_prefix(content,'shared_utils/theme_db/config/constants.py'))"
+python "${CLAUDE_SKILL_DIR}/scripts/probe_code_rules_enforcer_check.py" check_collection_prefix /tmp/pr73_constants.py shared_utils/theme_db/config/constants.py
 ```
 
-Expected output after the patch lands: a list containing `Line 91: Collection constant THEMES_INSERT_REQUIRED_COLUMN_NAMES - prefix with ALL_ (CODE_RULES §5)`. The same command against `/tmp/pr73_writer.py` (Copilot id 3153475297) emits `Line 296: Collection parameter column_value_pairs - prefix with all_ (CODE_RULES §5)`. Replacing the call with `m.check_library_print` against `/tmp/pr70_summary.py` (Copilot id 3153098727) emits at minimum one `Line 256: Library print() - …` line.
+Expected output after the patch lands: a list containing `Line 91: Collection constant THEMES_INSERT_REQUIRED_COLUMN_NAMES - prefix with ALL_ (CODE_RULES §5)`. The same command against `/tmp/pr73_writer.py` (Copilot id 3153475297) emits `Line 296: Collection parameter column_value_pairs - prefix with all_ (CODE_RULES §5)`. Re-running with `check_library_print /tmp/pr70_summary.py shared_utils/theme_db/summary.py` (Copilot id 3153098727) emits at minimum one `Line 256: Library print() - …` line.
 
 **Justification for touching `code_rules_enforcer.py`:** the root-cause statement names write-time enforcement as the right layer for collection-prefix and library-print, because both rules in `CODE_RULES.md §5` are mechanical (no judgment), produce concrete fixes, and were the dominant source of follow-up Copilot findings (3 of 8 inventory rows). The bugteam pre-flight gate alone is insufficient — it only fires before each AUDIT, so a clean-coder fix pass that introduces a new violation lives unblocked until the next gate run; write-time enforcement closes that window.
 

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

@@ -2,7 +2,7 @@
 
 ## Core principle (expanded)
 
-Background subagents (`Agent(..., run_in_background=true)`) run the audit-and-fix loop until convergence. The bugfind subagent audits clean-room (own context window, no chat history); the bugfix subagent addresses each audit’s findings; both spawn fresh per loop with no shared state. A 10-loop hard cap prevents runaway cost. Project permissions are granted at session start and revoked at session end.
+One audit agent (`code-quality-agent`, opus) walks all A–K categories per loop. One fix agent (`clean-coder`, opus) addresses the audit's findings.
 
 Fresh-spawn clean-room isolation: each `Agent` call creates a new subagent with its own context window and no access to prior conversation. After the subagent writes its outcome XML and self-terminates, the lead reads the file. Results never accumulate in the lead’s context beyond the XML artifact. Verbatim Anthropic quotes and URLs: [`../sources.md`](../sources.md).
 
@@ -12,7 +12,7 @@ The top-of-file list exists so partial reads (for example `head -100`) still sho
 
 ## 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.
+The user wants automated convergence on a clean PR without babysitting each step. Typed `/bugteam` once means full authorization for up to twenty audit cycles and the corresponding fix commits.
 
 ### Refusal reasons (detail)
 

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

@@ -1,86 +1,79 @@
-# GitHub PR comments (Step 2.5)
+# GitHub PR comments
 
-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 pull-request reviews and post-fix replies use two distinct transports:
 
-- **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.
+- **Per-loop audit review** — posted via [`post_audit_thread.py`](../../../_shared/pr-loop/scripts/post_audit_thread.py). One review per audit pass. `APPROVE` on CLEAN (the request event; GitHub stores it as `state=APPROVED`; body documents "no findings", zero inline comments). `REQUEST_CHANGES` on DIRTY (one inline anchored comment per finding; each becomes its own resolvable thread).
+- **Fix replies** — posted via the GitHub MCP `add_reply_to_pull_request_comment` after the fix commit lands. The reply body uses the unified template at [`../../../_shared/pr-loop/audit-reply-template.md`](../../../_shared/pr-loop/audit-reply-template.md); reply and `resolve_thread` are atomic per thread.
 
-- **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.
+## Per-loop audit review (post_audit_thread.py)
 
-**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.
+Run the script at the end of every audit pass:
 
-## MCP tool shapes (teammate)
+```
+python "${CLAUDE_SKILL_DIR}/../../_shared/pr-loop/scripts/post_audit_thread.py" \
+  --skill bugteam \
+  --owner <owner> \
+  --repo <repo> \
+  --pr-number <N> \
+  --commit <head_sha> \
+  --state <CLEAN|DIRTY> \
+  --findings-json <path>
+```
 
-All three POSTs use MCP tool calls. Body text with markdown (backticks, newlines, quotes) passes through safely as string parameters — no temp files, no jq, no shell pipes.
+Capture `<head_sha>` via `git rev-parse HEAD` in the subagent cwd immediately before this call so the review attaches to the commit the audit actually scoped.
 
-### Per-loop review (one POST creates parent + children)
+`--findings-json` points to a JSON file whose root is a list of objects shaped `{path, line, side, severity, description, fix_summary}`. Build it from the merged Shape A findings: finding `file` → `path`. Each finding's `failure_mode` carries the full audit-to-fix handoff text per [`agents/code-quality-agent.md`](../../../agents/code-quality-agent.md); split `failure_mode` at the literal `Fix:` heading so the failure narrative becomes `description` and the suffix beginning at `Fix:` (including the trailing `Validation:` clause) becomes `fix_summary`. When a finding's `failure_mode` omits the `Fix:` heading, write the full text to BOTH `description` and `fix_summary` so the script's body template (`INLINE_COMMENT_BODY_TEMPLATE` in [`scripts/config/post_audit_thread_constants.py`](../../../_shared/pr-loop/scripts/config/post_audit_thread_constants.py)) renders coherently. Set `side="RIGHT"` for every entry. On CLEAN the list is empty (`[]`); on DIRTY the list carries one entry per finding.
 
-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).
+The script handles retries internally — 1s / 4s / 16s backoff across four attempts (one initial plus three retries). Exit codes:
 
-```
-pull_request_review_write(
-  method="create",
-  event="COMMENT",
-  body=<review_body_markdown>,
-  commitID=<head_sha_at_post_time>,
-  owner=<owner>, repo=<repo>, pullNumber=<pull_number>,
-  comments=[
-    {path: <file_1>, line: <line_1>, side: "RIGHT", body: <finding_1_markdown>}
-    [, ... one object per anchored finding ...]
-  ]
-)
-```
+- `0` — review posted; the new review's `html_url` is on stdout.
+- `1` — user input error (bad arguments, malformed findings JSON, missing template).
+- `2` — retry exhaustion. Hard blocker; the lead exits `error: post_audit_thread retry exhausted` without retrying and without falling back to a flat issue comment.
 
-Response includes the parent review `html_url` and a `comments` array of child comments (`id`, `html_url`). Harvest children in index order and align with the finding list.
+Harvest the parent review URL from stdout, then extract the numeric review id from the URL's `#pullrequestreview-<id>` suffix (the trailing URL fragment of `html_url`, the part after `#`). Fetch child-comment URLs via `pull_request_read(method="get_review_comments", owner=<owner>, repo=<repo>, pullNumber=<N>)` filtered to that review id. That same response carries each comment's PR review thread node id (e.g. `PRRT_kwDOxxx`) — capture it alongside the numeric comment id. Match children to findings in the order they appear in the findings JSON, and store the mapping as `loop_comment_index[finding_id]` carrying both `finding_comment_id` (numeric) and `thread_node_id` (`PRRT_kwDOxxx`) for the FIX step to reply against and resolve.
 
-### Fix reply
+The script reads its body skeleton from [`../../../_shared/pr-loop/audit-reply-template.md`](../../../_shared/pr-loop/audit-reply-template.md) at runtime, so the template doc remains the single source of truth for the body shape — edits there propagate without restarting the caller.
 
-```
-add_reply_to_pull_request_comment(
-  commentId=<finding_comment_id>,
-  body=<reply_markdown>,
-  owner=<owner>, repo=<repo>, pullNumber=<pull_number>
-)
-```
-
-### Review POST failure fallback
+## Fix reply (MCP)
 
-Top-level PR comment via issue-comments (`issue_number` is the PR number):
+After the fix commit lands, post one reply per finding thread and resolve the thread atomically.
 
 ```
-add_issue_comment(
-  owner=<owner>, repo=<repo>,
-  issueNumber=<pull_number>,
-  body=<full_fallback_markdown>
+mcp__plugin_github_github__add_reply_to_pull_request_comment(
+  owner="<owner>",
+  repo="<repo>",
+  pullNumber=<number>,
+  commentId=<finding_comment_id>,
+  body="<reply body using unified template>"
 )
 ```
 
-`<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).
-
-Body text is passed directly as string parameters to the MCP tool calls — no temp files, no jq, no shell pipes.
+The reply body uses the unified template from [`../../../_shared/pr-loop/audit-reply-template.md`](../../../_shared/pr-loop/audit-reply-template.md). Per-status `<status_line>` / `<action_heading>` values live in [`../PROMPTS.md`](../PROMPTS.md) § FIX execution step 8.
 
-## Review body template (`<tmp_review_body.md>`)
+Immediately after the reply call returns, resolve the same thread:
 
 ```
-## /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>
+mcp__plugin_github_github__pull_request_review_write(
+  method="resolve_thread",
+  owner="<owner>",
+  repo="<repo>",
+  pullNumber=<number>,
+  threadId=<thread_node_id>
+)
 ```
 
-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.
+`<thread_node_id>` is the PR review thread node ID (`PRRT_kwDOxxx`) harvested above when calling `get_review_comments`, distinct from the numeric comment ID used in the reply call. See [obstacles/fix-resolve-thread.md](obstacles/fix-resolve-thread.md) for the full identifier-shape rationale.
 
-## Anchor-validation fallback (teammate)
+The two calls form one atomic per-thread action. Do not yield to the lead between them. Do not batch all replies before any resolves.
 
-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.
+## Anchor validation
 
-## Review POST failure fallback
+GitHub's reviews endpoint rejects the entire POST if any inline comment in `comments[]` targets a line not present in the diff at `--commit`. Validate `(path, line)` against the captured diff before adding a finding to the findings JSON. Findings without a diff anchor stay out of the JSON; surface them in the calling skill's user-facing output instead so the audit pass still completes.
 
-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 `add_issue_comment` (see MCP tool reference below).
+## GitHub MCP tools used
 
-## MCP tool reference
+- `add_reply_to_pull_request_comment` — fix replies on existing review comments.
+- `pull_request_review_write` (`method="resolve_thread"`) — thread resolution after the reply lands; called atomically with the reply.
+- `pull_request_read` (`method="get_review_comments"`) — harvest child-comment ids/urls after the script's parent review posts.
 
-- Per-loop batched review: `pull_request_review_write(method="create", event="COMMENT", body=..., commitID=..., owner=..., repo=..., pullNumber=..., comments=[...])` — wraps `POST /repos/{owner}/{repo}/pulls/{pull_number}/reviews`
-- Fix reply: `add_reply_to_pull_request_comment(commentId=..., body=..., owner=..., repo=..., pullNumber=...)` — wraps `POST /repos/{owner}/{repo}/pulls/{pull_number}/comments/{comment_id}/replies`
-- Review-POST failure fallback: `add_issue_comment(owner=..., repo=..., issueNumber=..., body=...)` — wraps `POST /repos/{owner}/{repo}/issues/{issue_number}/comments`
+Reference: https://github.com/github/github-mcp-server.

package/skills/bugteam/reference/obstacles/audit-assign-ids.md

@@ -0,0 +1,13 @@
+# Assign IDs
+
+Assign each finding a stable finding_id (loop<L>-<K>), 1-based within loop
+
+## 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/audit-capture-excerpts.md

@@ -0,0 +1,13 @@
+# Capture excerpts
+
+Capture verbatim excerpts, validate anchors against diff, split into anchored and unanchored buckets
+
+## 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/audit-walk-categories.md

@@ -0,0 +1,13 @@
+# Walk categories
+
+Audit every category A through K. Each returns Shape A finding or Shape B verified-clean. No skipped categories.
+
+## Self-population
+
+Hit a wall on this step? Spawn a background agent to record it. Keep working.
+
+1. Spawn `Agent(run_in_background=true)` — brief it: check `jl-cmd/claude-code-config` 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/audit-write-xml.md

@@ -0,0 +1,13 @@
+# Write outcome XML
+
+Write outcome XML to worktree path with finding IDs, thread node IDs, and review URL
+
+## 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-append-summary.md

@@ -0,0 +1,13 @@
+# Append summary URL
+
+Append fix summary URL to parent review via add_reply_to_pull_request_comment
+
+## 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-apply-fixes.md

@@ -0,0 +1,13 @@
+# Apply fixes
+
+Apply each addressable fix, skip only with explicit reason
+
+## 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-git-add-commit.md

@@ -0,0 +1,13 @@
+# Git add + commit
+
+git add by explicit path, commit with summary, capture hook failures
+
+## 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-git-push.md

@@ -0,0 +1,13 @@
+# Git push
+
+Fast-forward push, no flag overrides
+
+## 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-post-reply.md

@@ -0,0 +1,13 @@
+# Post fix replies
+
+Post fix reply on each finding comment thread via add_reply_to_pull_request_comment
+
+## 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-publish-summary.md

@@ -0,0 +1,13 @@
+# Publish fix summary
+
+Publish fix summary HTML via /doc-gist with commit SHA, files, per-fix descriptions
+
+## 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
+