claude-dev-env 1.83.0 → 1.85.0

package/skills/autoconverge/workflow/converge.mjs

@@ -26,7 +26,7 @@ const CONFIG = {
   copilotMaxPolls: 8,
   sharedScripts: '$HOME/.claude/skills/pr-converge/scripts',
   prLoopScripts: '$HOME/.claude/_shared/pr-loop/scripts',
-  bugteamRubric: '$HOME/.claude/skills/bugteam/reference/audit-contract.md',
+  bugteamRubric: '$HOME/.claude/_shared/pr-loop/audit-contract.md',
 }
 
 const REVIEWER_GATE_SENTINEL = 'CLAUDE_REVIEWER_GATE=autoconverge '
@@ -79,38 +79,32 @@ const convergeAgent = (prompt, options) =>
   agent(`${HEADLESS_SAFETY_PREAMBLE}${worktreeDirective(activeRepoPath)}${prompt}`, options)
 
 /**
- * Spawn a fresh git-utility Explore agent for a specific task. 'resolve-head'
- * prints the PR HEAD SHA, 'prefetch-main' fetches origin main so the review
- * lenses diff against an up-to-date base, and any other task reports whether the
- * branch has merge conflicts. The agent never edits code.
- * @param {string} task the short task name
- * @param {string} head optional HEAD SHA for conflict checks
- * @returns {Promise<object|string>} the structured output, or the transcript string when the 'prefetch-main' resume runs schema-less
+ * Spawn a fresh git-utility Explore agent for a specific task. The one task,
+ * 'preflight-git', bundles the three mechanical git reads into a single agent
+ * startup: it prints the PR HEAD SHA, fetches origin main so the review lenses
+ * diff against an up-to-date base, and polls GitHub mergeability, returning
+ * {sha, conflicting, fetched} in one structured result. The agent never edits
+ * code, so it runs on the cheapest model at low effort.
+ * @param {string} task the short task name ('preflight-git')
+ * @returns {Promise<object>} the structured PREFLIGHT_GIT_SCHEMA output
  */
-function runGitTask(task, head) {
-  if (task === 'resolve-head') {
-    return convergeAgent(
-      `Print the current HEAD SHA of ${prCoordinates}. Run exactly:\n` +
-        `gh api repos/${input.owner}/${input.repo}/pulls/${input.prNumber} --jq .head.sha\n` +
-        `Return the full 40-character SHA in the sha field. Do not modify any files.`,
-      { label: 'git-utility', phase: 'Converge', schema: HEAD_SCHEMA, agentType: 'Explore' },
-    )
-  }
-  if (task === 'prefetch-main') {
-    return convergeAgent(
-      `Refresh the base ref for ${prCoordinates} so the parallel review lenses can diff against an up-to-date origin/main without each running its own fetch. Run exactly:\n` +
-        `git fetch origin main\n` +
-        `Do not edit, commit, push, rebase, or modify any files — fetch only.`,
-      { label: 'git-utility', phase: 'Converge', agentType: 'Explore' },
-    )
+function runGitTask(task) {
+  if (task !== 'preflight-git') {
+    throw new Error(`runGitTask has no handler for task ${task}`)
   }
   return convergeAgent(
-    `Report whether ${prCoordinates} (HEAD ${head}) has merge conflicts with its base branch. Do not edit, commit, push, or rebase — read only.\n\n` +
-      `GitHub computes mergeability asynchronously, so .mergeable is null right after a push until it finishes. Poll until it resolves: run\n` +
+    `Run three read-only git preflight steps for ${prCoordinates}. Do not edit, commit, push, rebase, or modify any files — read only.\n\n` +
+      `STEP 1 — resolve HEAD. Print the current PR HEAD SHA. Run exactly:\n` +
+      `   gh api repos/${input.owner}/${input.repo}/pulls/${input.prNumber} --jq .head.sha\n` +
+      `Return the full 40-character SHA in the sha field.\n\n` +
+      `STEP 2 — refresh the base ref so the parallel review lenses can diff against an up-to-date origin/main without each running its own fetch. Run exactly:\n` +
+      `   git fetch origin main\n` +
+      `Return fetched:true when the fetch completed, fetched:false when it failed.\n\n` +
+      `STEP 3 — report whether the PR has merge conflicts with its base branch. GitHub computes mergeability asynchronously, so .mergeable is null right after a push until it finishes. Poll until it resolves: run\n` +
       `   gh api repos/${input.owner}/${input.repo}/pulls/${input.prNumber} --jq '{mergeable: .mergeable, state: .mergeable_state}'\n` +
-      `up to 5 times, 5 seconds apart (wait each 5-second interval inside this turn with the Monitor tool, per the WAITS AND POLLS rule above), stopping as soon as mergeable is true or false.\n\n` +
+      `up to 5 times, 5 seconds apart (wait each 5-second interval inside this turn with the Monitor tool, per the WAITS AND POLLS rule above), stopping as soon as mergeable is true or false.\n` +
       `Return conflicting:true when mergeable is false or state is "dirty" (the branch conflicts with the base). Return conflicting:false when mergeable is true, or when mergeable stays null after the full poll budget — mergeability is unknown, so let the bug checks proceed rather than rebase on a guess.`,
-    { label: 'git-utility', phase: 'Converge', schema: MERGE_CONFLICT_SCHEMA, agentType: 'Explore' },
+    { label: 'git-utility', phase: 'Converge', schema: PREFLIGHT_GIT_SCHEMA, agentType: 'Explore', model: 'haiku', effort: 'low' },
   )
 }
 
@@ -558,11 +552,18 @@ const REVIEWER_AVAILABILITY_SCHEMA = {
   required: ['copilot', 'bugbot'],
 }
 
-const HEAD_SCHEMA = {
+const PREFLIGHT_GIT_SCHEMA = {
   type: 'object',
   additionalProperties: false,
-  properties: { sha: { type: 'string' } },
-  required: ['sha'],
+  properties: {
+    sha: { type: 'string', description: 'the full 40-character PR HEAD SHA' },
+    conflicting: {
+      type: 'boolean',
+      description: 'true only when GitHub reports the PR branch conflicts with its base (mergeable:false or mergeable_state:dirty); false when it merges cleanly or mergeability could not be computed',
+    },
+    fetched: { type: 'boolean', description: 'true when git fetch origin main completed successfully' },
+  },
+  required: ['sha', 'conflicting', 'fetched'],
 }
 
 const FIX_SCHEMA = {
@@ -602,18 +603,6 @@ const REPAIR_EDIT_SCHEMA = {
   required: ['edited', 'rebased', 'resolvedWithoutCommit', 'summary'],
 }
 
-const MERGE_CONFLICT_SCHEMA = {
-  type: 'object',
-  additionalProperties: false,
-  properties: {
-    conflicting: {
-      type: 'boolean',
-      description: 'true only when GitHub reports the PR branch conflicts with its base (mergeable:false or mergeable_state:dirty); false when it merges cleanly or mergeability could not be computed',
-    },
-  },
-  required: ['conflicting'],
-}
-
 const CONFLICT_EDIT_SCHEMA = {
   type: 'object',
   additionalProperties: false,
@@ -1003,10 +992,10 @@ function commitNeedsCodeRecovery(commitResult) {
 
 /**
  * Decide whether a resolved HEAD SHA is safe to spawn lenses against. A dead
- * resolve-head agent or a malformed result yields a falsy SHA; spawning lenses
+ * preflight-git agent or a malformed result yields a falsy SHA; spawning lenses
  * against it interpolates the literal string 'HEAD undefined' into their prompts
  * and produces a spurious clean verdict on a non-existent commit.
- * @param {string|null|undefined} resolvedHead the SHA from the git-utility 'resolve-head' task
+ * @param {string|null|undefined} resolvedHead the SHA from the git-utility 'preflight-git' task
  * @returns {boolean} true only when the SHA is a non-empty string
  */
 function isResolvedHeadUsable(resolvedHead) {
@@ -1014,12 +1003,12 @@ function isResolvedHeadUsable(resolvedHead) {
 }
 
 /**
- * Decide whether the pre-flight merge-conflict check found the PR branch in
- * conflict with its base. A dead check agent (null/undefined result) reports
+ * Decide whether the pre-flight mergeability probe found the PR branch in
+ * conflict with its base. A dead preflight agent (null/undefined result) reports
  * not-conflicting so the run proceeds straight to the bug checks rather than
- * force-pushing a rebase on a verdict that does not exist — a transient check
+ * force-pushing a rebase on a verdict that does not exist — a transient probe
  * failure must never trigger a destructive rebase.
- * @param {object|null|undefined} mergeState the git-utility 'check-merge-conflicts' task result
+ * @param {object|null|undefined} mergeState the git-utility 'preflight-git' task result carrying the conflicting field
  * @returns {boolean} true only when the check reported conflicting:true
  */
 function isMergeConflicting(mergeState) {
@@ -1370,7 +1359,7 @@ function runCopilotGate(head) {
       `Copilot can run out of usage. When the newest Copilot review on HEAD carries an out-of-usage notice — a body stating Copilot was unable to review because the user who requested the review has reached their quota limit, or any equivalent quota / premium-request / usage-limit exhaustion message rather than an actual code review — Copilot is down for this run: return {sha:${'`'}${head}${'`'}, clean:true, down:true, findings:[]} and stop. Do NOT re-request a review, do NOT keep polling, and do NOT treat the notice as a finding.\n\n` +
       `1. Read any existing Copilot review on HEAD first: python "${CONFIG.sharedScripts}/fetch_copilot_reviews.py" --owner ${input.owner} --repo ${input.repo} --pr-number ${input.prNumber}. This lists every Copilot review across all commits newest-first; only count entries whose commit_id starts with ${head}. If the newest such HEAD-scoped Copilot review is the out-of-usage notice above -> return the down result and stop. A notice on any earlier commit is NOT down: ignore it and continue. With no Copilot review on HEAD, skip a duplicate request: python "${CONFIG.sharedScripts}/check_pending_reviews.py" --owner ${input.owner} --repo ${input.repo} --pr-number ${input.prNumber} --user copilot. Exit 0 means a request is already pending; otherwise request one:\n` +
       `   ${REVIEWER_GATE_SENTINEL}gh api --method POST repos/${input.owner}/${input.repo}/pulls/${input.prNumber}/requested_reviewers -f 'reviewers[]=copilot-pull-request-reviewer[bot]'\n` +
-      `2. Poll for Copilot's review on HEAD ${head}: up to ${CONFIG.copilotMaxPolls} attempts, 360 seconds apart (wait each 360-second interval inside this turn with the Monitor tool, per the WAITS AND POLLS rule above; if the attempt budget is spent with no review on HEAD, return down: true). Each attempt: python "${CONFIG.sharedScripts}/fetch_copilot_reviews.py" --owner ${input.owner} --repo ${input.repo} --pr-number ${input.prNumber} for the top-level review state, plus gh api "repos/${input.owner}/${input.repo}/pulls/${input.prNumber}/comments" --paginate --slurp for inline comment ids (Copilot's login contains "copilot", case-insensitive). Only count entries whose commit_id starts with ${head}.\n` +
+      `2. Poll for Copilot's review on HEAD ${head}: up to ${CONFIG.copilotMaxPolls} attempts, 360 seconds apart (wait each 360-second interval inside this turn with the Monitor tool, per the WAITS AND POLLS rule above; if the attempt budget is spent with no review on HEAD, return the full down result {sha:${'`'}${head}${'`'}, clean:false, down:true, findings:[]}). Each attempt: python "${CONFIG.sharedScripts}/fetch_copilot_reviews.py" --owner ${input.owner} --repo ${input.repo} --pr-number ${input.prNumber} for the top-level review state, plus gh api "repos/${input.owner}/${input.repo}/pulls/${input.prNumber}/comments" --paginate --slurp for inline comment ids (Copilot's login contains "copilot", case-insensitive). Only count entries whose commit_id starts with ${head}.\n` +
       `   - Out-of-usage notice on HEAD -> return the down result above (clean:true, down:true) and stop.\n` +
       `   - Copilot review present on HEAD whose state is APPROVED, or COMMENTED with no inline findings -> a clean pass: return {sha:${'`'}${head}${'`'}, clean:true, down:false, findings:[]}.\n` +
       `   - Copilot findings on HEAD -> return them (each with its inline comment id in replyToCommentId; category 'code-standard' for pure CODE_RULES/style violations with no behavioral impact, 'bug' otherwise), clean:false, down:false.\n` +
@@ -1432,20 +1421,22 @@ async function repairConvergence(head, failures) {
 
 /**
  * Pre-flight conflict resolution: when the PR branch conflicts with its base,
- * rebase it clean before the bug checks run — check (Explore probes mergeability)
- * -> edit (clean-coder rebases and resolves, no push) -> verify (code-verifier
- * binds a verdict to the rebased tree) -> commit (clean-coder force-with-lease
- * pushes). Returns the post-rebase HEAD so the first converge round runs its
- * lenses on the conflict-free diff. A non-conflicting PR, a rebase the edit step
- * declined, or a failed verdict returns the unchanged HEAD so the run proceeds to
- * the bug checks unchanged. A mid-run conflict (origin/main advancing later) is
- * still caught by the FINALIZE convergence repair, which also rebases.
+ * rebase it clean before the bug checks run — edit (clean-coder rebases and
+ * resolves, no push) -> verify (code-verifier binds a verdict to the rebased
+ * tree) -> commit (clean-coder force-with-lease pushes). The conflict decision
+ * comes from the merged 'preflight-git' probe the caller already ran, so this
+ * function spawns no mergeability agent of its own. Returns the post-rebase
+ * HEAD so the first converge round runs its lenses on the conflict-free diff.
+ * A non-conflicting PR, a rebase the edit step declined, or a failed verdict
+ * returns the unchanged HEAD so the run proceeds to the bug checks unchanged.
+ * A mid-run conflict (origin/main advancing later) is still caught by the
+ * FINALIZE convergence repair, which also rebases.
  * @param {string} head PR HEAD SHA before any rebase
+ * @param {boolean} isConflicting the isMergeConflicting decision over the preflight-git result
  * @returns {Promise<string>} the HEAD SHA after a successful rebase push, or the unchanged head
  */
-async function resolveMergeConflicts(head) {
-  const mergeState = await runGitTask('check-merge-conflicts', head)
-  if (!isMergeConflicting(mergeState)) return head
+async function resolveMergeConflicts(head, isConflicting) {
+  if (!isConflicting) return head
   log(`Pre-flight: ${prCoordinates} conflicts with origin/main — rebasing clean before the bug checks`)
   const editResult = await runCodeEditorTask('conflict-edit', { head })
   if (editResult?.rebased !== true) return head
@@ -1655,24 +1646,24 @@ let reuseNote = null
 let reviewerAvailability = null
 const deferredPrs = []
 
-const preflightHead = await runGitTask('resolve-head')
-if (isResolvedHeadUsable(preflightHead?.sha)) {
-  await resolveMergeConflicts(preflightHead.sha)
+const preflight = await runGitTask('preflight-git')
+if (isResolvedHeadUsable(preflight?.sha)) {
+  head = await resolveMergeConflicts(preflight.sha, isMergeConflicting(preflight))
 }
 
 log('Reuse pass: scanning the full diff for certain, behaviorally identical, autonomously implementable reuse improvements before convergence')
-const reuseHeadResult = await runGitTask('resolve-head')
-const reuseHead = reuseHeadResult?.sha
-if (isResolvedHeadUsable(reuseHead)) {
-  await runGitTask('prefetch-main')
-  const reuse = await runReuseAuditPass(reuseHead)
+if (isResolvedHeadUsable(head)) {
+  const reuse = await runReuseAuditPass(head)
   const reuseFindings = reuse?.findings || []
   if (reuseFindings.length > 0) {
     log(`Reuse pass: ${reuseFindings.length} qualifying reuse improvement(s) — applying before convergence`)
-    const reuseFix = await applyFixes(reuseHead, reuseFindings, 'reuse-pass')
+    const reuseFix = await applyFixes(head, reuseFindings, 'reuse-pass')
     reuseNote = reuseFix?.pushed === true
       ? `${reuseFindings.length} reuse improvement(s) applied before convergence (${reuseFix.newSha?.slice(0, SHA_COMPARISON_PREFIX_LENGTH)})`
       : `${reuseFindings.length} reuse improvement(s) identified before convergence but not landed — the code-review lens re-surfaces any that remain`
+    if (reuseFix?.pushed === true) {
+      head = isResolvedHeadUsable(reuseFix.newSha) ? reuseFix.newSha : null
+    }
   } else {
     log('Reuse pass: no reuse case cleared all three criteria — proceeding to convergence')
   }
@@ -1684,13 +1675,14 @@ while (iterations < CONFIG.maxIterations) {
   iterations += 1
   if (phase === 'CONVERGE') {
     rounds += 1
-    const headResult = await runGitTask('resolve-head')
-    head = headResult?.sha
     if (!isResolvedHeadUsable(head)) {
-      log(`Round ${rounds}: resolve-head agent returned no SHA — retrying without spawning lenses`)
+      const refreshedPreflight = await runGitTask('preflight-git')
+      head = isResolvedHeadUsable(refreshedPreflight?.sha) ? refreshedPreflight.sha : null
+    }
+    if (!isResolvedHeadUsable(head)) {
+      log(`Round ${rounds}: preflight-git agent returned no SHA — retrying without spawning lenses`)
       continue
     }
-    await runGitTask('prefetch-main')
     reviewerAvailability = await runReviewerAvailabilityCheck()
     const isBugbotDownPreSpawn = resolveReviewerDown(reviewerAvailability?.bugbot, input.bugbotDisabled || false)
     log(`Round ${rounds}: parallel Bugbot + code-review + bug-audit on ${head?.slice(0, 7)}`)
@@ -1703,6 +1695,7 @@ while (iterations < CONFIG.maxIterations) {
     const roundOutcome = resolveRoundOutcome(lenses)
     if (roundOutcome.allLensesDead) {
       log(`Round ${rounds}: every lens agent died — retrying without posting a clean artifact`)
+      head = null
       continue
     }
     const findings = roundOutcome.findings
@@ -1730,10 +1723,12 @@ while (iterations < CONFIG.maxIterations) {
           : `fix lens landed no push for ${findings.length} finding(s) on HEAD ${head}`
         break
       }
+      head = null
       continue
     }
     if (!roundOutcome.roundClean) {
       log(`Round ${rounds}: a lens reported not-clean with no findings on ${head?.slice(0, 7)} — re-converging without a clean artifact`)
+      head = null
       continue
     }
     log(`Round ${rounds}: all lenses clean on ${head?.slice(0, 7)} — posting clean audit artifact`)
@@ -1790,6 +1785,7 @@ while (iterations < CONFIG.maxIterations) {
           : `copilot fix lens landed no push for ${copilotOutcome.findings.length} finding(s) on HEAD ${head}`
         break
       }
+      head = null
       phase = 'CONVERGE'
       continue
     }
@@ -1817,6 +1813,7 @@ while (iterations < CONFIG.maxIterations) {
     }
     log(`Convergence check failed: ${convergenceOutcome.failures.join('; ')} — repairing then re-converging`)
     await repairConvergence(head, convergenceOutcome.failures)
+    head = null
     phase = 'CONVERGE'
     continue
   }

package/skills/autoconverge/workflow/render_report.py

@@ -17,8 +17,7 @@ from autoconverge_report_constants.render_report_constants import (
     DEFAULT_FINDING_CATEGORY,
     DEFAULT_FINDING_SEVERITY,
     DEFAULT_ISSUE_ICON,
-    HTML_DOCTYPE,
-    HTML_HEAD_TEMPLATE,
+    HTML_TITLE_AND_STYLE_TEMPLATE,
     HTML_STYLE_BLOCK,
     ISO_DATE_LENGTH,
     ISSUE_CLASS_FIELD_AFTER_LINES,
@@ -890,7 +889,9 @@ def render_report_html(
         generated_date: ISO date string derived from the journal timestamp.
 
     Returns:
-        A complete HTML document string.
+        A page-content HTML string (a title, a style block, and the body
+        markup) with no surrounding <!DOCTYPE>, <html>, <head>, or <body>
+        tags, ready for the Artifact tool to wrap and publish.
     """
     short_sha_length = SHORT_SHA_LENGTH
     pr_number = pr_metadata.number
@@ -899,7 +900,7 @@ def render_report_html(
     final_sha_short = pr_metadata.final_sha[:short_sha_length]
     round_count = pr_metadata.round_count
 
-    head_html = HTML_HEAD_TEMPLATE.format(
+    title_and_style_html = HTML_TITLE_AND_STYLE_TEMPLATE.format(
         pr_number=pr_number,
         style_block=HTML_STYLE_BLOCK,
     )
@@ -933,15 +934,10 @@ def render_report_html(
     )
 
     return (
-        f"{HTML_DOCTYPE}\n"
-        f"<html lang='en'>\n"
-        f"{head_html}\n"
-        f"<body>\n"
+        f"{title_and_style_html}\n"
         f'<div class="container">\n'
         f"{body_content}\n"
-        f"</div>\n"
-        f"</body>\n"
-        f"</html>"
+        f"</div>"
     )
 
 

package/skills/bugteam/CLAUDE.md

@@ -10,7 +10,7 @@ Each loop: a `code-quality-agent` (fresh context, all A–P audit categories) pr
 
 | File | Purpose |
 |---|---|
-| `SKILL.md` | Hub — pre-flight call, refusals, audit-posting protocol, progress checklist, and situation-to-reference table. Read this first. |
+| `SKILL.md` | Hub — pre-flight call, refusals, the audit-posting step (applies the `post-audit-findings` skill), progress checklist, and situation-to-reference table. Read this first. |
 | `PROMPTS.md` | Spawn XML, A–P category bindings, outcome XML schemas. |
 | `CONSTRAINTS.md` | Invariants — what the loop must never violate. |
 | `EXAMPLES.md` | Exit scenarios: converged, cap-reached, stuck, refusal, mixed-outcome. |

package/skills/bugteam/PROMPTS.md

@@ -278,7 +278,7 @@ cd into `<worktree_path>` before any git or file operation.
     [ ] 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
+    [ ] Publish fix summary via the Artifact tool, capture URL
     [ ] Append fix summary URL to parent review via add_reply_to_pull_request_comment
     [ ] Write fix outcomes XML
   </self_audit_checklist>
@@ -343,14 +343,15 @@ cd into `<worktree_path>` before any git or file operation.
      `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.
+  9. Write the fix summary (what was fixed, what was skipped, what was left
+     unaddressed) to a self-contained HTML file, load the `artifact-design`
+     skill, then publish it with the `Artifact` tool. Capture the returned
+     URL.
 
-  10. Append the fix summary gist URL (from step 9) to the parent review
+  10. Append the fix summary 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.
+      artifact 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.

package/skills/bugteam/SKILL.md

@@ -36,7 +36,8 @@ First match wins; respond with the quoted line exactly and stop:
   token `bugteam` (comma-separated, case-insensitive, whitespace-tolerant):
   `/bugteam is disabled via CLAUDE_REVIEWS_DISABLED.` The pre-flight script
   also exits 7 in this case so any caller invoking it directly halts on the
-  same signal.
+  same signal. Gate semantics live in the `reviewer-gates` skill
+  ([../reviewer-gates/SKILL.md](../reviewer-gates/SKILL.md)).
 - **No PR or upstream diff.** `No PR or upstream diff. /bugteam needs a target.`
 - **Dirty tree.** `Uncommitted changes detected. Stash, commit, or revert before
   /bugteam.`
@@ -46,74 +47,26 @@ First match wins; respond with the quoted line exactly and stop:
 
 ## Audit posting
 
-Every internal audit pass (CLEAN or DIRTY) ends with one call to
-`post_audit_thread.py`. The script POSTs a single review to
-`/repos/{owner}/{repo}/pulls/{N}/reviews` 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). The mandate applies
-whether bugteam runs inside `/pr-converge` or standalone.
-
-**Self-PR auto-toggle.** GitHub rejects both `APPROVE` and
-`REQUEST_CHANGES` reviews with HTTP 422 when the authenticated identity
-matches the PR author ("Cannot approve/request changes on your own pull
-request"). `post_audit_thread.py` detects this case via `gh api user` +
-`gh api repos/<o>/<r>/pulls/<n>` and auto-resolves an alternate gh
-account's token for the reviews POST — the active `gh auth` account is
-not mutated; only the bearer token sent on the request changes. After
-the POST the active account is still whoever it was before, so no
-"swap back" step is needed.
-
-Configuration:
-
-- `GH_TOKEN` / `GITHUB_TOKEN` env vars take precedence over the toggle.
-  Set them when you need to pin a specific reviewer identity by token
-  rather than by account login.
-- `BUGTEAM_REVIEWER_ACCOUNT` env var names which authenticated alternate
-  to prefer when a toggle is needed (for example,
-  `BUGTEAM_REVIEWER_ACCOUNT=jl-cmd`). When unset, the script falls back
-  to the first alternate account `gh auth status` reports.
-- The named alternate must be logged in (`gh auth login -h github.com -u
-  <login>`) before the audit skill runs. The script exits 1 with a
-  pointing-at-`gh auth login` message when self-PR is detected and no
-  usable alternate is authenticated.
-
-```
-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>
-```
-
-`--findings-json` points to a JSON file whose root is a list of objects
-shaped `{path, line, side, severity, description, fix_summary}`. The
-audit agent's persisted finding output maps as follows: finding `file`
-→ `path`, and the agent's `failure_mode` field carries both the failure
-narrative AND the `Fix:` / `Validation:` text per
-[`agents/code-quality-agent.md`](../../agents/code-quality-agent.md)
-("The `failure_mode` field is the audit-to-fix handoff"). Split
-`failure_mode` at the literal `Fix:` heading: the prefix (the failure
-narrative) becomes `description`, and the suffix starting 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` so the
-script's body template (`INLINE_COMMENT_BODY_TEMPLATE` in
-[`_shared/pr-loop/scripts/pr_loop_shared_constants/post_audit_thread_constants.py`](../../_shared/pr-loop/scripts/pr_loop_shared_constants/post_audit_thread_constants.py))
-still renders coherently. Set `side="RIGHT"` for every entry. On CLEAN,
-pass an empty array (`[]`) so the script posts an APPROVE review
-(GitHub stores it as `state=APPROVED`) with a "no findings" summary and
-zero inline comments.
-
-Exit codes: `0` on success (emits the new review's `html_url` to
-stdout); `1` on user input error; `2` on retry exhaustion (1s / 4s /
-16s backoff across four attempts total). Exit 2 is a hard blocker; the
-lead halts the loop and exits `error: post_audit_thread retry
-exhausted` without retrying.
+Every internal audit pass (CLEAN or DIRTY) ends with one posted GitHub PR
+review; the mandate applies whether bugteam runs inside `/pr-converge` or
+standalone. Apply the `post-audit-findings` skill
+([../post-audit-findings/SKILL.md](../post-audit-findings/SKILL.md)) with
+`--skill bugteam`: it covers the findings-JSON mapping (the `failure_mode`
+split at the literal `Fix:` heading), the anchored-vs-unanchored partition,
+the `post_audit_thread.py` invocation, the self-PR reviewer toggle
+(`BUGTEAM_REVIEWER_ACCOUNT`), the exit codes, and the id harvest.
+
+Bugteam-only obligations:
+
+- The lead runs the posting step; the FIX teammate waits for the harvested
+  ids before replying or resolving.
+- Record each harvested `{finding_comment_id, finding_comment_url,
+  thread_node_id}` triple into `loop_comment_index` (per-loop scope; see
+  [reference/team-setup.md](reference/team-setup.md) § Loop state block) so
+  the matching FIX action owns the reply-and-resolve unit.
+- Exit 2 from `post_audit_thread.py` is a hard blocker: the lead halts the
+  loop and exits `error: post_audit_thread retry exhausted` without
+  retrying.
 
 ## Progress checklist
 
@@ -143,13 +96,13 @@ end-to-end mental model before starting Step 0.
 | `--bugbot-retrigger` flag behavior | [reference/team-setup.md](reference/team-setup.md) |
 | AUDIT action and code-rules pre-audit gate, pre-cycle walk, cycle decision tree | [reference/audit-and-teammates.md](reference/audit-and-teammates.md) |
 | FIX action and verify-push semantics | [reference/audit-and-teammates.md](reference/audit-and-teammates.md) |
-| Posting the end-of-pass audit review via `post_audit_thread.py` (APPROVE on CLEAN — the request event; GitHub stores it as `state=APPROVED` — REQUEST_CHANGES with inline anchored comments on DIRTY) | [§ Audit posting](#audit-posting) |
+| Posting the end-of-pass audit review (APPROVE on CLEAN, REQUEST_CHANGES with inline anchored comments on DIRTY) | [§ Audit posting](#audit-posting), which applies [../post-audit-findings/SKILL.md](../post-audit-findings/SKILL.md) |
 | Posting per-finding fix replies via GitHub MCP `add_reply_to_pull_request_comment` (rendered with the unified template at [`_shared/pr-loop/audit-reply-template.md`](../../_shared/pr-loop/audit-reply-template.md)) | [reference/github-pr-reviews.md](reference/github-pr-reviews.md) |
-| Teardown, PR description rewrite via `pr-description-writer`, permission revoke, final report | [reference/teardown-publish-permissions.md](reference/teardown-publish-permissions.md) |
+| Teardown, PR description rewrite via `pr-description-writer`, permission revoke, final report | [../pr-loop-lifecycle/reference/teardown-publish-permissions.md](../pr-loop-lifecycle/reference/teardown-publish-permissions.md) |
 | Spawn-prompt XML, A–P category bindings, outcome XML schemas | [PROMPTS.md](PROMPTS.md) |
 | Per-category audit content (sub-buckets, decision criteria, ready-to-send Variant C templates) | `$HOME/.claude/audit-rubrics/{category_rubrics,prompts}/` |
 | Invariants and design rationale | [CONSTRAINTS.md](CONSTRAINTS.md), [reference/design-rationale.md](reference/design-rationale.md) |
-| Audit-contract finding shape (Shape A / B), Haiku secondary, post-fix self-audit | [reference/audit-contract.md](reference/audit-contract.md) |
+| Audit-contract finding shape (Shape A / B), Haiku secondary, post-fix self-audit | [../../_shared/pr-loop/audit-contract.md](../../_shared/pr-loop/audit-contract.md) |
 | Exit-scenario examples (converged, cap-reached, stuck, refusal, mixed-outcome) | [EXAMPLES.md](EXAMPLES.md) |
 | Doc URLs and verbatim quotes | [sources.md](sources.md) |
 | Historical Copilot gap analysis (superseded) | [reference/copilot-gap-analysis.md](reference/copilot-gap-analysis.md) |

package/skills/bugteam/reference/CLAUDE.md

@@ -7,11 +7,9 @@ Expanded workflow detail for the `bugteam` skill. Load a file from this director
 | File | Purpose |
 |---|---|
 | `README.md` | Index of all files in this directory with one-line domain summaries. |
-| `team-setup.md` | Permissions grant, PR scope resolution, run name, temp dir, and loop state. |
+| `team-setup.md` | Permissions grant, PR scope resolution (applies the `pr-scope-resolve` skill), run name, temp dir, and loop state. |
 | `audit-and-teammates.md` | Pre-audit CODE_RULES gate, full cycle numbering, AUDIT and FIX action detail. |
-| `audit-contract.md` | Finding shape (Shape A / B), Haiku secondary merge rules, post-fix self-audit. |
 | `github-pr-reviews.md` | Per-loop review posting, `jq`+`gh api` payloads, inline anchors, fallbacks, REST endpoints. |
-| `teardown-publish-permissions.md` | Teardown steps, PR description rewrite via `pr-description-writer`, permission revoke, final report. |
 | `design-rationale.md` | Why clean-room subagents, when `/bugteam` applies, refusal reasons. |
 | `copilot-gap-analysis.md` | Historical gap analysis (reference only). |
 

package/skills/bugteam/reference/README.md

@@ -8,7 +8,7 @@ Expanded material that used to live inline in `SKILL.md`. Load a file when the o
 | [`team-setup.md`](team-setup.md) | Permissions grant (`CLAUDE_SKILL_DIR`), PR scope, run name / temp dir / 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 |
-| [`teardown-publish-permissions.md`](teardown-publish-permissions.md) | Utility scripts note, teardown, PR description rewrite, revoke, final report |
+| [`../../pr-loop-lifecycle/reference/teardown-publish-permissions.md`](../../pr-loop-lifecycle/reference/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

@@ -153,7 +153,7 @@ Agent(
 
 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, 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.
+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; the mechanics follow the `pr-fix-protocol` skill ([`../../pr-fix-protocol/SKILL.md`](../../pr-fix-protocol/SKILL.md)), which frames the shared 13-step sequence in [`../../../_shared/pr-loop/fix-protocol.md`](../../../_shared/pr-loop/fix-protocol.md) (step 12 carries the exact reply-and-resolve sequence). Same identity model as bugfind: teammate posts; lead waits.
 
 After replies, the teammate writes outcome XML (schema in [`../PROMPTS.md`](../PROMPTS.md)).
 

package/skills/bugteam/reference/obstacles/fix-publish-summary.md

@@ -1,6 +1,6 @@
 # Publish fix summary
 
-Publish fix summary HTML via /doc-gist with commit SHA, files, per-fix descriptions
+Publish fix summary HTML via the Artifact tool with commit SHA, files, per-fix descriptions
 
 ## Self-population
 

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

@@ -8,7 +8,7 @@ Bugteam-specific utilities (preflight, fix_hookspath, grant, revoke) live in
 the skill-local [`scripts/`](../scripts/) directory. Shared utilities remain in
 [`_shared/pr-loop/scripts/`](../../_shared/pr-loop/scripts/) (run, do not paste
 into context). Utility scripts are **executed**, not loaded as primary context
-([`sources.md`](sources.md) § Progressive disclosure and utility scripts).
+([`sources.md`](../sources.md) § Progressive disclosure and utility scripts).
 
 ```bash
 python "${CLAUDE_SKILL_DIR}/scripts/bugteam_preflight.py"
@@ -53,7 +53,7 @@ the auto-remediation only applies to the `core.hooksPath` failure mode.
 Before spawning any subagents, grant the session write access to the project's `.claude/**` tree:
 
 ```bash
-python "${CLAUDE_SKILL_DIR}/scripts/grant_project_claude_permissions.py"
+python "${CLAUDE_SKILL_DIR}/../../_shared/pr-loop/scripts/grant_project_claude_permissions.py"
 ```
 
 `${CLAUDE_SKILL_DIR}` is a Claude Code host-managed token, pre-substituted by the runtime before any shell sees it. Unlike `${TMPDIR}` and similar shell parameter expansions, it does not depend on the shell’s expansion semantics, so it behaves the same on Unix and Windows shells.
@@ -64,11 +64,12 @@ This is the **first** action of every `/bugteam` invocation, before any subagent
 
 ## Step 1 — Resolve PR scope (detail)
 
-Same resolution path as `/findbugs`:
-
-1. Call `pull_request_read(method="get", pullNumber=N, owner=O, repo=R)` to fetch PR metadata; capture `number`, `headRefName`, `baseRefName`, and `url` from the response. Falls back to the merge-base diff path when no PR exists.
-2. Fall back to `git merge-base HEAD origin/<default>` then `git diff <merge-base>...HEAD`.
-3. Neither → refuse per refusal cases in `SKILL.md`.
+Apply the `pr-scope-resolve` skill
+([../../pr-scope-resolve/SKILL.md](../../pr-scope-resolve/SKILL.md)) with
+caller `bugteam`. Its resolution ladder hands back `owner`, `repo`, `number`,
+`head_ref`, `base_ref`, `url`, and `head_sha`; when no PR and no upstream
+diff exist, respond exactly `No PR or upstream diff. /bugteam needs a
+target.` and stop.
 
 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.
 

package/skills/bugteam/scripts/CLAUDE.md

@@ -9,9 +9,6 @@ Python scripts executed by the bugteam lead or teammates at runtime. These are n
 | `bugteam_preflight.py` | Run pytest and optional `pre-commit` before the first loop. Skips pytest when `BUGTEAM_PREFLIGHT_SKIP=1` or no test files exist. |
 | `bugteam_fix_hookspath.py` | Auto-remediate a stale `core.hooksPath` override, set the canonical global value, re-run preflight. |
 | `bugteam_code_rules_gate.py` | Run `validate_content` from `code_rules_enforcer.py` on PR-scoped files. Exit 1 on mandatory rule failures. |
-| `grant_project_claude_permissions.py` | Grant Edit/Write/Read on `cwd/.claude/**` in `~/.claude/settings.json`. |
-| `revoke_project_claude_permissions.py` | Remove the matching grant entries from `~/.claude/settings.json`. |
-| `_bugteam_permissions_common.py` | Shared helpers for grant/revoke (atomic JSON writes, settings sections). |
 | `windows_safe_rmtree.py` | Remove a directory tree on Windows by stripping ReadOnly attributes and retrying on failure. |
 | `probe_code_rules_enforcer_check.py` | Load `code_rules_enforcer.py` and invoke a named check function against a fixture file. |
 | `reflow_skill_md.py` | Reflow the bugteam SKILL.md body to fit line-length limits. |
@@ -23,9 +20,6 @@ Python scripts executed by the bugteam lead or teammates at runtime. These are n
 | `test_bugteam_preflight.py` | `bugteam_preflight.py` |
 | `test_bugteam_code_rules_gate.py` | `bugteam_code_rules_gate.py` |
 | `test_bugteam_fix_hookspath.py` | `bugteam_fix_hookspath.py` |
-| `test_bugteam_permissions_common.py` | `_bugteam_permissions_common.py` |
-| `test__bugteam_permissions_common.py` | Internal helpers in `_bugteam_permissions_common.py` |
-| `test_agent_config_carveout.py` | `.claude/**` grant/revoke carveout logic |
 | `test_probe_code_rules_enforcer_check.py` | `probe_code_rules_enforcer_check.py` |
 | `test_windows_safe_rmtree.py` | `windows_safe_rmtree.py` |
 

package/skills/bugteam/scripts/README.md

@@ -7,10 +7,6 @@ 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_fix_hookspath.py` | Auto-remediate a stale local `core.hooksPath` override, set canonical global value, re-run `bugteam_preflight.py`. Invoked by Claude when preflight reports a `core.hooksPath` failure. |
 | `bugteam_code_rules_gate.py` | Run `validate_content` from `code-rules-enforcer.py` on PR-scoped files (`git diff` vs merge-base). Exit `1` if any mandatory rule fails. Invoked **before each audit**; the fixer clears it before the auditor runs. |
-| `grant_project_claude_permissions.py` | Idempotent grant of Edit/Write/Read on `cwd/.claude/**` into `~/.claude/settings.json`. |
-| `revoke_project_claude_permissions.py` | Removes the matching grant entries from `~/.claude/settings.json`. |
-| `test_claude_permissions_common.py` | Pytest module for path normalization and glob-metacharacter guards in `_claude_permissions_common.py`. |
-| `_claude_permissions_common.py` | Shared helpers for the grant/revoke scripts (atomic JSON writes, settings sections). |
 | `windows_safe_rmtree.py` | Recursively remove a directory tree on Windows by stripping ReadOnly attributes and retrying the failing syscall. Invoked from SKILL.md Step 4 to delete `<run_temp_dir>` after teardown. |
 | `probe_code_rules_enforcer_check.py` | Dynamically load `~/.claude/hooks/blocking/code_rules_enforcer.py` and invoke a named check function against a fixture file. Used by the historical Copilot gap-analysis investigation as a verification shape (see `reference/copilot-gap-analysis.md`). |
 

package/skills/bugteam/scripts/bugteam_scripts_constants/CLAUDE.md

@@ -9,7 +9,6 @@ Python package of named constants imported by the bugteam scripts. Each module h
 | `bugteam_preflight_constants.py` | `bugteam_preflight.py` — env var name, hooks path suffix, exit codes, ignore dirs, argument tuples, config filenames. |
 | `bugteam_code_rules_gate_constants.py` | `bugteam_code_rules_gate.py` — gate-related path and exit-code constants. |
 | `bugteam_fix_hookspath_constants.py` | `bugteam_fix_hookspath.py` — canonical hooks path, remediation message strings. |
-| `claude_permissions_common_constants.py` | `_bugteam_permissions_common.py` — settings JSON keys, glob patterns for the grant/revoke scripts. |
 | `probe_code_rules_enforcer_check_constants.py` | `probe_code_rules_enforcer_check.py` — enforcer module path and function name constants. |
 | `reflow_skill_md_constants.py` | `reflow_skill_md.py` — line-length and formatting constants. |
 | `windows_safe_rmtree_constants.py` | `windows_safe_rmtree.py` — retry count and wait constants. |