claude-dev-env 1.38.0 → 1.39.0

package/skills/bugteam/CONSTRAINTS.md

@@ -1,28 +1,27 @@
-# Bugteam constraints
-
-## Non-Negotiable
-
-- **Pre-flight is mandatory.** `preflight.py` must exit 0 before Step 0. If it fails for `core.hooksPath`, auto-remediate with `fix_hookspath.py`. All other failures require manual fixes.
-- **Looping against a fixed known count.** 10 audit loops hard cap. No exceptions. The cap is a safety value, set high enough to converge on most non-trivial PRs while preventing infinite loops.
-- **`loop_count` is the iteration counter.** It increments before each AUDIT in Step 3. A FIX without a preceding AUDIT does not advance `loop_count`. The `loop_count > 10` check runs before each AUDIT. After 10 AUDITs, the cycle exits regardless of remaining FIX rounds. Standards-fix passes before an audit do not advance `loop_count`.
-- **One review per loop, findings as child comments of that review.** Each loop posts a single pull-request review whose body is the loop header and whose `comments[]` are the anchored findings. Each loop's review stands alone — one review created per loop, fully self-contained on the PR conversation.
-- **PR description rewrite on every exit.** Step 4.5 runs on `converged`, `cap reached`, and `stuck`. On `error`, the rewrite is best-effort; if it fails, surface the error in the final report and continue to revoke.
-- **Outcome XML, not JSON.** The AUDIT subagent writes findings to `.bugteam-pr<N>-loop<L>.outcomes.xml` and the FIX subagent writes fix outcomes to `.bugteam-pr<N>-loop<L>.fix-outcomes.xml`. The lead reads these files between actions. Separate paths prevent the FIX output from overwriting the AUDIT's findings file. XML chosen for parser robustness against multi-line, special-character, and quoted reason fields.
+# Bugteam — invariants and design rationale
+
+## Constraints
+
+- **Full A–K audit every loop, no exceptions.** PR size, "focused audit," "team overhead," "CODE_RULES already passed" — not valid reasons. Empty `<findings/>` for any category is a valid result. The audit agent walks all A–K rubrics each loop.
+- **One run per invocation, multi-PR supported.** All PRs in a single /bugteam invocation share one `run_temp_dir`. Per-PR identity lives in the subagent name prefix (`bugfind-pr<N>-loop<L>` / `bugfix-pr<N>-loop<L>`) and the `<run_temp_dir>/pr-<N>/` subfolder containing that PR's git worktree, diff patches, and outcome XML files.
+- **Grant before any spawn, revoke before any return.** Step 0 grants project `.claude/**` permissions; Step 5 revokes. Both are mandatory. Revoke runs on every exit path including error, cap-reached, and stuck.
+- **Fresh subagent per loop.** Both bugfind and bugfix are spawned new each loop. Reusing a subagent across loops accumulates context inside that subagent's window — defeats clean-room.
+- **One up-front confirmation = whole cycle.** The `/bugteam` invocation authorizes the entire cycle; every subsequent decision runs on that single authorization.
+- **20-loop hard cap.** Counted as **AUDIT** completions (increment in Step 3). Standards-fix passes before an audit do not advance `loop_count`. Worst case includes extra clean-coder spawns for the code-rules gate.
+- **Code rules gate before every AUDIT.** Run `${CLAUDE_SKILL_DIR}/scripts/bugteam_code_rules_gate.py` until exit **0** before spawning **bugfind**. Same `validate_content` logic as `hooks/blocking/code_rules_enforcer.py`.
+- **Clean-room audits, every loop.** Each bugfind subagent's spawn prompt contains only the PR scope, audit rubric, and the current loop number. Prior loop history stays in the lead.
+- **Targeted fixes.** Each fix subagent sees ONLY the most recent audit's findings. Prior loops are invisible to the fix subagent.
+- **Fix subagent receives the latest audit as its input contract.** Each loop's fix run operates on the current audit's output and only that.
+- **Lead owns the final PR description rewrite only** (Step 4.5), via the `pr-description-writer` agent.
 
 ## Why this design
 
-### Why retry with fix — why not just reject and move on
-
-Bugteam's purpose is to make real PRs better before they ship, not to just point out problems. A review that says "fix this bug" without giving the author&#60;subagent&#62; a chance to fix it in the same session would be a weaker intervention — the PR author still has to go back, figure out the fix, apply it, re-push, and re-trigger review. By bundling fix attempts into the same loop, bugteam reduces round-trips from N audits + N manual fix cycles to N audits + N automated fix attempts, with no human context-switching.
-
-### Why 10 loops — why not unlimited
-
-A PR that needs more than 10 audit-fix rounds has deeper problems than bugteam can address. The 10-loop cap is a forcing function: after 10 rounds, escalate to `/findbugs` or human review rather than grinding on diminishing returns.
-
-### Why outcome XML — why not JSON
+The three sibling skills compose, but `/bugteam` solves a problem they cannot solve in sequence:
 
-JSON escapes `\n` inside `"reason": "could not address: some\nmulti-line\ntext"`, making the file hard to read and grep. XML preserves the raw text as element content, so `&#60;reason&#62;could not address: some&#10;multi-line&#10;text&#60;/reason&#62;` renders legibly in every markdown-capable viewer. The choice is ergonomic, not technical — both formats carry the same information.
+- `/findbugs` audits once and stops.
+- `/fixbugs` fixes the findings of one audit and stops.
+- A human-driven `/findbugs` → `/fixbugs` → `/findbugs` → `/fixbugs` cycle works but requires the user to drive it.
 
-### Why sibling auditor paths diverge (worktree vs temp)
+`/bugteam` automates that cycle. The clean-room property is preserved by spawning a fresh audit agent each loop with no inherited context — every audit is independent of the prior loop's verdict. The 20-loop cap is the safety: pathological cases (audit agent oscillating, fix agent regressing) cannot run away.
 
-Only the -a validator writes to the worktree `.bugteam-pr&#60;N&#62;-loop&#60;L&#62;.outcomes.xml` path, which the lead reads. Sibling auditors (-b through -k) write to unique paths under `&#60;run_temp_dir&#62;` to avoid collisions. Without this split, parallel haiku auditors writing to the same path would clobber each other's output, and the lead consuming one path would see only whichever writer finished last.
+The single up-front confirmation is the explicit trade — `/bugteam` is more autonomous than `/findbugs`+`/fixbugs` chained manually. The user accepts that autonomy by typing the command. Stop conditions and the loop log give the user full visibility on exit.

package/skills/bugteam/EXAMPLES.md

@@ -19,12 +19,12 @@ Claude: [resolves PR #42, runs loop]
 
 <example>
 User: `/bugteam`
-Claude: [runs 10 loops without convergence]
+Claude: [runs 20 loops without convergence]
 
-`Loop 10 audit: 0P0 / 1P1 / 2P2`
+`Loop 20 audit: 0P0 / 1P1 / 2P2`
 
 `/bugteam exit: cap reached`
-`Loops: 10`
+`Loops: 20`
 `Remaining: 0P0 / 1P1 / 2P2 — run /findbugs for human triage`
 </example>
 

package/skills/bugteam/PROMPTS.md

@@ -38,11 +38,11 @@ cd into `<worktree_path>` before any git or file operation.
   verified-clean -- re-audit with a concrete trace.
 
   Categories A–K (one-line summary; full rubric and sub-bucket decomposition
-  for each is in `packages/claude-dev-env/audit-rubrics/category_rubrics/`;
+  for each is in `$HOME/.claude/audit-rubrics/category_rubrics/`;
   ready-to-send Variant C prompts — each with a PR/repo-independent
   generalized skeleton above a `---` separator and a worked example against
   an authentic PR below — are in
-  `packages/claude-dev-env/audit-rubrics/prompts/`):
+  `$HOME/.claude/audit-rubrics/prompts/`):
 
   A. API contract verification (signatures, return types, async/await correctness)
   B. Selector / query / engine compatibility
@@ -69,11 +69,24 @@ cd into `<worktree_path>` before any git or file operation.
 </constraints>
 
 <comment_posting>
-  Sibling auditors (-b through -k): run only steps 1–2 (audit, assign IDs,
-  capture excerpt, validate anchors), then write outcome XML per <output_format> and return.
-  Skip steps 3–5 — sibling auditors do not post PR reviews.
+  Load all A–K rubrics from
+  `$HOME/.claude/audit-rubrics/{category_rubrics,prompts}/`. The prompt file
+  is a template for output shape, not a straitjacket — reorganize when the
+  diff demands it. The diff supplies the findings; the rubric supplies the
+  sub-bucket decomposition and decision criteria. Both must be loaded.
 
-  Validator (-a) and single-opus auditors: run all steps below.
+  Before starting, create one task per checklist item via TaskCreate. Use
+  TaskUpdate to mark each in_progress as you begin it and completed when
+  done.
+
+  <self_audit_checklist>
+    [ ] Walk all 11 categories (A–K), each with Shape A or Shape B
+    [ ] Assign finding IDs (loop<L>-<K>)
+    [ ] Capture excerpts, validate anchors, format finding bodies
+    [ ] Build findings JSON, invoke post_audit_thread.py, capture html_url
+    [ ] Harvest child-comment ids/urls AND thread_node_ids; populate loop_comment_index
+    [ ] Write outcome XML
+  </self_audit_checklist>
 
   1. Audit the diff against the 11 categories above. Buffer the findings
      in memory; all posting happens at step 4 once anchors are validated.
@@ -83,58 +96,132 @@ cd into `<worktree_path>` before any git or file operation.
      line. Populate the `<excerpt>` element in the outcome XML with it. Validate
      every finding's (file, line) against the captured diff. Split findings into two
      buckets: anchored (line is in the diff) and unanchored (line is not in the diff
-     — goes into the review body's "Findings without a diff anchor" section per
-     Step 2.5). Format each finding body as:
-
-       **[severity] one-line title**
-       Category: <letter> (<category name>)
-       <2-3 sentence description with concrete trace>
-
-       _From /bugteam audit loop <L>._
-
-  4. Post ONE review via `pull_request_review_write(method="create",
-     event="COMMENT", body=<review_body>, owner=<O>, repo=<R>,
-     pullNumber=<N>, comments=[...])`. See Step 2.5 in SKILL.md for the full
-     parameter shape. Harvest the parent review `html_url` from the response
-     and the `comments[]` child entries (each with its own `id` and `html_url`).
-     Match child entries to anchored findings in index order.
-  5. If the review POST fails, use `add_issue_comment(owner=<O>, repo=<R>,
-     issueNumber=<N>, body=<full_text>)` as fallback.
-  Body text is passed directly as string parameters to the MCP tool calls —
-  no temp files, no jq, no shell pipes.
+     — surfaced in the calling skill's user-facing output rather than as inline
+     anchored comments).
+
+     Each anchored finding contributes one entry to the JSON payload built
+     in step 4. The payload schema is
+     `{path, line, side, severity, description, fix_summary}`; the audit
+     teammate populates `description` (the failure narrative) and
+     `fix_summary` (the `Fix:` / `Validation:` text) from the
+     finding's `failure_mode` per the mapping in step 4. The audit
+     teammate does NOT author the inline-comment body directly:
+     `post_audit_thread.py` renders every body from
+     `INLINE_COMMENT_BODY_TEMPLATE` (defined in
+     [`_shared/pr-loop/scripts/config/post_audit_thread_constants.py`](../../_shared/pr-loop/scripts/config/post_audit_thread_constants.py))
+     — the template prepends `**[<severity>] <Skill> audit finding**`
+     and renders the suggested-fix block, so a teammate who hand-formats
+     a title or footer wastes the work.
+
+  4. **Before posting, read the full review once as if you were the PR
+     author.** Ask: would I understand what to fix and why? Do any two
+     findings describe the same problem in different words — merge them. Does
+     any finding miss its mark — rewrite or drop it. Does the review feel
+     coherent as a whole? The review's job is to make the PR author want to
+     fix these bugs, not to demonstrate that the rubric ran. Rearrange,
+     merge, or rephrase anything that would confuse the author. Then
+     proceed with the mechanical script invocation below.
+
+     Post ONE review per loop via `post_audit_thread.py` per
+     [SKILL.md § Audit posting](SKILL.md#audit-posting). Serialize the
+     anchored findings to a JSON file shaped as a list of
+     `{path, line, side, severity, description, fix_summary}` entries.
+     Map each finding's `file` → `path`; split each finding's
+     `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 the agent omits the `Fix:` heading on a given
+     finding, write the full `failure_mode` text to BOTH `description`
+     and `fix_summary`. Set `side="RIGHT"` for every entry. Zero
+     anchored findings → `--state CLEAN` with the findings file holding
+     an empty array (`[]`); one or more → `--state DIRTY` with the full
+     list.
+
+     ```
+     python "${CLAUDE_SKILL_DIR}/../../_shared/pr-loop/scripts/post_audit_thread.py" \
+       --skill bugteam \
+       --owner <O> \
+       --repo <R> \
+       --pr-number <N> \
+       --commit <head_sha> \
+       --state <CLEAN|DIRTY> \
+       --findings-json <path>
+     ```
+
+     The script POSTs a single review with `event=APPROVE` on CLEAN
+     (the request event; GitHub stores it as `state=APPROVED`; empty
+     `comments[]`, body documents "no findings") or
+     `event=REQUEST_CHANGES` on DIRTY (one inline anchored comment per
+     finding; each becomes its own resolvable thread on the PR). It
+     handles retries internally (1s / 4s / 16s backoff across four
+     attempts). Exit codes:
+
+     - `0` — review posted; the new review's `html_url` is on stdout.
+       Capture this URL as the parent review URL.
+     - `1` — user input error (bad arguments, malformed findings JSON,
+       missing template).
+     - `2` — retry exhaustion. Hard blocker; halt and exit
+       `error: post_audit_thread retry exhausted` without retrying and
+       without falling back to a flat issue comment. There is no
+       fallback path — a hard blocker on the audit-posting path is a
+       halt condition.
+
+     Exit 0 emits the new review's `html_url` on stdout. Extract the
+     numeric review id from that URL's `#pullrequestreview-<id>` suffix
+     (the trailing URL fragment, the part after `#`). Then harvest child-comment URLs
+     **and PR review thread node ids** via
+     `pull_request_read(method="get_review_comments", owner=<O>,
+     repo=<R>, pullNumber=<N>)` filtered to that review id.
+     Match children to findings in the order they appear in the findings
+     JSON. Each `loop_comment_index[finding_id]` entry must carry both
+     `finding_comment_id` (numeric, used by `add_reply_to_pull_request_comment`)
+     and `thread_node_id` (e.g. `PRRT_kwDOxxx`, used by
+     `resolve_thread`) so the FIX teammate can reply and resolve.
+
+  The findings JSON is serialized to a temp file and passed by path; the
+  review-body content is read from `audit-reply-template.md` at runtime by
+  `post_audit_thread.py`, not passed in by the caller. No body-content
+  temp files, no jq, no shell pipes.
 </comment_posting>
 
 <output_format>
-  For the (-a) validator: write the outcome XML below to .bugteam-pr<N>-loop<L>.outcomes.xml inside
-  the PR's worktree directory (<worktree_path>). For sibling auditors (-b through -k): write to <run_temp_dir>/pr-<N>/loop-<L>-<letter>.outcomes.xml (absolute path passed in prompt). Sibling auditors do not post PR reviews; set review_url, finding_comment_id, and finding_comment_url to empty strings, and used_fallback to "false". Omit unanchored findings from sibling output — only the validator handles those. Return only that path on stdout. The schema:
+  Run `python scripts/write_audit_outcomes.py` to write the outcome XML.
+  The script owns the canonical path, filename, and format.
 </output_format>
 ```
 
-## AUDIT outcome XML schema (bugfind writes this)
+## AUDIT outcome XML schema
+
+`write_audit_outcomes.py` reads the findings JSON (list of finding dicts) and
+emits this shape. Scalar finding fields become XML attributes on
+`<finding>`; the body fields `title`, `excerpt`, and `description` become
+child elements. The root carries `pr`, `loop`, and `review_url` as
+attributes.
 
 ```xml
-<bugteam_audit loop="<L>" review_url="<url>">
-  <finding
-    finding_id="loop<L>-<K>"
-    severity="P0|P1|P2"
-    category="<letter>"
-    file="<path>"
-    line="<int>"
-    finding_comment_id="<gh child comment id, or empty if unanchored/review-fallback>"
-    finding_comment_url="<url of child comment, OR review_url if unanchored, OR fallback issue comment URL>"
-    used_fallback="true|false"
-  >
-    <title>one-line title</title>
-    <excerpt>verbatim source line or snippet from the file at the cited line</excerpt>
-    <description>2-3 sentence description with concrete trace</description>
-  </finding>
-  <verified_clean>
-    <category letter="<letter>" name="<name>" evidence="brief evidence + cleared conclusion"/>
-  </verified_clean>
+<bugteam_audit pr="<N>" loop="<L>" review_url="<url>">
+  <findings>
+    <finding
+      finding_id="loop<L>-<K>"
+      severity="P0|P1|P2"
+      category="<letter>"
+      file="<path>"
+      line="<int>"
+      finding_comment_id="<gh child comment id, or empty if unanchored>"
+      finding_comment_url="<url of child comment, OR review_url if unanchored>"
+      thread_node_id="<PR review thread node id (PRRT_kwDOxxx), or empty if unanchored>"
+    >
+      <title>one-line title</title>
+      <excerpt>verbatim source line or snippet from the file at the cited line</excerpt>
+      <description>2-3 sentence description with concrete trace</description>
+    </finding>
+  </findings>
 </bugteam_audit>
 ```
 
-After the teammate writes the XML and returns, the lead reads `.bugteam-pr<N>-loop<L>.outcomes.xml` from the PR's worktree directory with the `Read` tool, parses it, and populates `loop_comment_index` from `<finding>` elements.
+Verified-clean evidence per A–K category is surfaced in the agent's text-mode
+final report, not in this outcome XML (the writer accepts a flat findings list
+only).
 
 ## FIX spawn-prompt XML (bugfix teammate)
 
@@ -159,14 +246,33 @@ cd into `<worktree_path>` before any git or file operation.
     file="<path>"
     line="<int>"
     category="<letter>"
-    finding_comment_id="<id>"
+    finding_comment_id="<numeric comment id>"
     finding_comment_url="<url>"
+    thread_node_id="<PR review thread node id (PRRT_kwDOxxx)>"
   >
     <description>...</description>
   </bug>
 </bugs_to_fix>
 
 <execution>
+  Before starting, create one task per checklist item via TaskCreate. Use
+  TaskUpdate to mark each in_progress as you begin it and completed when
+  done.
+
+  <self_audit_checklist>
+    [ ] Read each referenced file
+    [ ] Apply all addressable fixes
+    [ ] py_compile on every modified file
+    [ ] Test suite passes
+    [ ] Post-fix violation count ≤ previous loop total (skip on L=1)
+    [ ] git add + commit
+    [ ] git push
+    [ ] Per finding: atomically post the unified-template reply, then call resolve_thread (no yield between them)
+    [ ] Publish fix summary via /doc-gist, capture URL
+    [ ] Append fix summary URL to parent review via add_reply_to_pull_request_comment
+    [ ] Write fix outcomes XML
+  </self_audit_checklist>
+
   1. Read each referenced file before editing.
   2. Apply each fix you can address.
   3. Run `python -m py_compile` (or language-equivalent) on every modified file.
@@ -178,28 +284,82 @@ cd into `<worktree_path>` before any git or file operation.
        (the commit was atomic; if it failed, no finding was applied), populate hook_output
        on each outcome, and return WITHOUT retrying. The lead will treat this loop as no-progress.
   7. git push with a plain fast-forward push (the default, no flag overrides).
-  8. For each bug, post a fix reply to its finding_comment_id via
-     `add_reply_to_pull_request_comment(commentId=<id>, body=<reply_text>,
-     owner=<O>, repo=<R>, pullNumber=<N>)`:
-     - "Fixed in <commit_sha>" if the bug was addressed by your commit
-     - "Could not address this loop: <one-line reason>" if you skipped or failed it
-     - "Hook blocked the fix commit: <one-line summary>" if the commit was hook-blocked
-     Body text is passed directly as string parameters -- no temp files, no jq, no shell pipes.
-  9. Write `.bugteam-pr<N>-loop<L>.fix-outcomes.xml` inside `<worktree_path>` (schema below) and return its path.
+  8. For each finding, atomically (a) post the fix reply and
+     (b) call `resolve_thread`. The two calls form one logical action
+     per thread — do not yield to the lead between them, and do not
+     batch all replies before any resolves.
+
+     (a) Reply via
+     `add_reply_to_pull_request_comment(commentId=<finding_comment_id>,
+     body=<reply_body>, owner=<O>, repo=<R>, pullNumber=<N>)`. The
+     reply body uses the unified template at
+     [`../../_shared/pr-loop/audit-reply-template.md`](../../_shared/pr-loop/audit-reply-template.md).
+     Skeleton (identical across all paths):
+
+     ```
+     **Claude finished @<reviewer>'s task** —— <status_line>
+
+     ---
+     ### <action_heading> ✅
+
+     <1–2 paragraph plain-language explanation>
+
+     **`<file>:<line>`:**
+     - <bullet describing change or rationale>
+     - <bullet describing change or rationale>
+
+     <closing paragraph>
+     ```
+
+     Per-path `<status_line>` / `<action_heading>`:
+     - `status=fixed`: `Fixed in <short_sha>` (first 7 chars) /
+       finding-specific action verb (e.g.,
+       `Replaced Any with concrete type`).
+     - `status=could_not_address`: `Could not address this loop` /
+       one-line reason text.
+     - `status=hook_blocked`: `Hook blocked the fix commit` /
+       one-line hook summary.
+
+     Body text is passed directly as string parameters — no temp files,
+     no jq, no shell pipes.
+
+     (b) Immediately call
+     `pull_request_review_write(method="resolve_thread",
+     threadId=<thread_node_id>, owner=<O>, repo=<R>, pullNumber=<N>)`
+     for the same thread (this is the PR review thread node ID —
+     `PRRT_kwDOxxx` — distinct from the numeric comment ID; the AUDIT
+     teammate captures it at audit time when calling
+     `get_review_comments` and stores it on each
+     `loop_comment_index` entry alongside `finding_comment_id`, see
+     [reference/obstacles/fix-resolve-thread.md](reference/obstacles/fix-resolve-thread.md)).
+
+  9. Publish the fix summary gist via `/doc-gist`. Pass the fix report
+     (what was fixed, what was skipped, what was left unaddressed) as the
+     gist body. Capture the returned gist URL.
+
+  10. Append the fix summary gist URL (from step 9) to the parent review
+      via `add_reply_to_pull_request_comment(commentId=<id>, body=...,
+      owner=<O>, repo=<R>, pullNumber=<N>)`. The body carries the
+      gist URL plus a one-line summary of fixes applied this loop.
+
+  11. Write `.bugteam-pr<N>-loop<L>.fix-outcomes.xml` inside
+      `<worktree_path>` (schema below) and return its path.
 </execution>
 
 <outcome_xml_schema>
-  <bugteam_fix loop="<L>" commit_sha="<sha or empty if no commit>">
-    <outcome
-      finding_id="loop<L>-<K>"
-      status="fixed|could_not_address|hook_blocked"
-      commit_sha="<sha if fixed, empty otherwise>"
-      reply_comment_id="<id of the reply posted>"
-      reply_comment_url="<url of the reply posted>"
-    >
-      <reason>only present when status=could_not_address; one-line reason text</reason>
-      <hook_output>only present when status=hook_blocked; verbatim stderr from the blocked hook</hook_output>
-    </outcome>
+  <bugteam_fix pr="<N>" loop="<L>" commit_sha="<sha or empty if no commit>">
+    <outcomes>
+      <outcome
+        finding_id="loop<L>-<K>"
+        status="fixed|could_not_address|hook_blocked|unverified_fixed"
+        commit_sha="<sha if fixed, empty otherwise>"
+        reply_comment_id="<id of the reply posted>"
+        reply_comment_url="<url of the reply posted>"
+      >
+        <reason>only present when status=could_not_address; one-line reason text</reason>
+        <hook_output>only present when status=hook_blocked; verbatim stderr from the blocked hook</hook_output>
+      </outcome>
+    </outcomes>
   </bugteam_fix>
 </outcome_xml_schema>