claude-dev-env 1.82.0 → 1.84.0

package/skills/autoconverge/workflow/converge.mjs

@@ -26,9 +26,11 @@ 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 '
+
 const HEADLESS_SAFETY_PREAMBLE =
   'HEADLESS RUN — you run unattended: no human can answer a permission or confirmation prompt, and any such prompt stalls the entire convergence run. The destructive_command_blocker hook matches dangerous patterns (rm -rf, git reset --hard, dd, mkfs, chmod -R, fork bombs) as raw text anywhere in a Bash command, with no quote-awareness — so a destructive string stalls you even when it is only data you never execute. Therefore:\n' +
   '- Never place a destructive-command literal inside a Bash command — not in echo, not in a heredoc, and not as an argument to python -c, node -e, or awk. To exercise or verify destructive_command_blocker (or any hook) behavior, run the committed test suite, e.g. python -m pytest <test_file>, which passes the command strings as in-language data rather than as a shell command.\n' +
@@ -77,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' },
   )
 }
 
@@ -464,6 +460,27 @@ function runConvergenceCheck(context) {
   )
 }
 
+/**
+ * Spawn a single reviewer-availability Explore agent once per CONVERGE round,
+ * before either reviewer's own agent is spawned. It runs the shared
+ * reviewer_availability.py CLI for both Copilot and Bugbot and reports each
+ * one's down state and reason, so resolveReviewerDown can decide whether to
+ * spawn the Bugbot lens and the Copilot gate without depending on an
+ * externally pre-set input flag.
+ * @returns {Promise<object>} REVIEWER_AVAILABILITY_SCHEMA result
+ */
+function runReviewerAvailabilityCheck() {
+  return convergeAgent(
+    `Check whether GitHub Copilot and Cursor Bugbot are available to review ${prCoordinates} this round, before either reviewer's agent is spawned. Do not edit code, commit, or push.\n\n` +
+      `Run exactly:\n` +
+      `python "${CONFIG.prLoopScripts}/reviewer_availability.py" --reviewer copilot\n` +
+      `python "${CONFIG.prLoopScripts}/reviewer_availability.py" --reviewer bugbot\n` +
+      `Each run exits 0 when that reviewer is available and non-zero when it is down, and prints one line naming the reason (stdout when available, stderr when down) — capture that line.\n\n` +
+      `Return strictly the schema: copilot.down and bugbot.down report whether that reviewer's run exited non-zero, and copilot.reason / bugbot.reason carry its printed line.`,
+    { label: 'reviewer-availability', phase: 'Converge', schema: REVIEWER_AVAILABILITY_SCHEMA, agentType: 'Explore' },
+  )
+}
+
 const PRE_COMMIT_GATE_STEP =
   `\n\nFINAL STEP — pre-commit gate check (do NOT commit): before your turn ends, prove your working-tree changes CAN be committed by dry-running the CODE_RULES commit gate that gates git commit (precommit_code_rules_gate). From inside the checkout that holds your changes, resolve its root with git rev-parse --show-toplevel, stage your changes with git add -A, then run exactly:\n` +
   `   python "${CONFIG.prLoopScripts}/code_rules_gate.py" --repo-root "<that root>" --staged\n` +
@@ -509,11 +526,44 @@ const COPILOT_SCHEMA = {
   required: ['sha', 'clean', 'down', 'findings'],
 }
 
-const HEAD_SCHEMA = {
+const REVIEWER_AVAILABILITY_SCHEMA = {
   type: 'object',
   additionalProperties: false,
-  properties: { sha: { type: 'string' } },
-  required: ['sha'],
+  properties: {
+    copilot: {
+      type: 'object',
+      additionalProperties: false,
+      properties: {
+        down: { type: 'boolean', description: 'true when reviewer_availability.py --reviewer copilot exited non-zero (opted out or out of premium-request quota)' },
+        reason: { type: 'string', description: 'the one-line reason reviewer_availability.py printed for Copilot' },
+      },
+      required: ['down', 'reason'],
+    },
+    bugbot: {
+      type: 'object',
+      additionalProperties: false,
+      properties: {
+        down: { type: 'boolean', description: 'true when reviewer_availability.py --reviewer bugbot exited non-zero (opted out via CLAUDE_REVIEWS_DISABLED)' },
+        reason: { type: 'string', description: 'the one-line reason reviewer_availability.py printed for Bugbot' },
+      },
+      required: ['down', 'reason'],
+    },
+  },
+  required: ['copilot', 'bugbot'],
+}
+
+const PREFLIGHT_GIT_SCHEMA = {
+  type: 'object',
+  additionalProperties: false,
+  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 = {
@@ -553,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,
@@ -749,19 +787,27 @@ function isMoreSevere(candidateSeverity, currentSeverity) {
 }
 
 /**
- * Decide whether the convergence check should bypass the Bugbot gate this round,
- * recomputed from the current Bugbot lens result rather than latched across the
- * run, so a recovered Bugbot re-arms the gate. A dead lens agent (null/undefined
- * result) produces no Bugbot verdict on this HEAD, so it is treated as down to
- * keep the convergence gate from demanding a verdict that cannot exist.
- * @param {object|null|undefined} bugbotLens the current round's Bugbot lens result
- * @param {boolean} bugbotDisabled true when Bugbot is opted out for the whole run
- * @returns {boolean} true when the Bugbot gate is bypassed for the current HEAD
+ * Decide whether a reviewer is skipped this round — the one shared gate both
+ * Bugbot and Copilot consult before either reviewer's agent is spawned. The
+ * run's own disable flag always wins, so a deferred PR seeded with
+ * copilotDisabled or bugbotDisabled skips the reviewer without a probe.
+ * Otherwise the decision comes from the carried entry's down field, read from
+ * the round-start availability probe for a pre-spawn decision. A missing entry
+ * (a dead probe agent, or no result yet) reads as available rather than down,
+ * so an outage in the probe itself never wedges convergence — the reviewer's
+ * own runtime detection still runs and can report down on its own. This
+ * fail-open null handling suits a pre-spawn decision; a caller computing a
+ * post-round verdict from a reviewer's own lens/gate result — where a dead
+ * agent has no verdict to report, not an available one — guards that null
+ * case itself before calling this function.
+ * @param {{down: boolean}|null|undefined} reviewerAvailabilityEntry the probe's per-reviewer entry, or a reviewer's own result, carrying a down field
+ * @param {boolean} isReviewerDisabledByInput true when the run input opts this reviewer out for the whole run
+ * @returns {boolean} true when the reviewer is treated as down this round
  */
-function resolveBugbotDown(bugbotLens, bugbotDisabled) {
-  if (bugbotDisabled) return true
-  if (bugbotLens == null) return true
-  return bugbotLens.down === true
+function resolveReviewerDown(reviewerAvailabilityEntry, isReviewerDisabledByInput) {
+  if (isReviewerDisabledByInput) return true
+  if (reviewerAvailabilityEntry == null) return false
+  return reviewerAvailabilityEntry.down === true
 }
 
 /**
@@ -946,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) {
@@ -957,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) {
@@ -1015,9 +1061,10 @@ function classifyCopilotOutcome(copilot) {
 
 /**
  * Decide whether the Copilot review gate is bypassed for this COPILOT pass from
- * the gate outcome, mirroring resolveBugbotDown so the flag is recomputed every
- * pass rather than left sticky. Only a 'down' outcome (Copilot out of quota or
- * unreachable after the poll cap) bypasses the convergence Copilot gate; an
+ * the gate outcome, mirroring resolveReviewerDown's post-round bugbotDown
+ * recompute so the flag is recomputed every pass rather than left sticky. Only
+ * a 'down' outcome (Copilot out of quota or unreachable after the poll cap)
+ * bypasses the convergence Copilot gate; an
  * 'approved', 'fix', or 'retry' outcome means Copilot answered this pass, so the
  * gate must be evaluated against its review and is never bypassed. Recomputing
  * from the current outcome is what lets a recovered Copilot — one that returns
@@ -1105,9 +1152,6 @@ const prCoordinates = `owner=${input.owner} repo=${input.repo} PR #${input.prNum
  * @returns {Promise<object>} LENS_SCHEMA result
  */
 function runBugbotLens(head) {
-  if (input.bugbotDisabled) {
-    return Promise.resolve({ sha: head, clean: true, down: true, findings: [] })
-  }
   return convergeAgent(
     `You are the Cursor Bugbot lens for ${prCoordinates}, HEAD ${head}. Cursor Bugbot participates this run.\n\n` +
       `Goal: return Bugbot's verdict on HEAD ${head}. Do not edit code, commit, or push. You may post the literal trigger comment described below.\n\n` +
@@ -1120,7 +1164,7 @@ function runBugbotLens(head) {
       `   Only count entries whose commit_id starts with ${head}.\n` +
       `   - If findings exist on HEAD -> return them (each with its inline comment id in replyToCommentId when present, else null).\n` +
       `   - If a clean review exists on HEAD -> return clean.\n` +
-      `4. No review yet on HEAD: check_bugbot_ci.py --check-active. If active (exit 0), poll: repeat check_bugbot_ci.py --check-clean / --check-active every 60 seconds (wait each 60-second interval inside this turn with the Monitor tool, per the WAITS AND POLLS rule above) for up to 25 iterations, then re-fetch the review. If not active (exit 1), post the literal comment "bugbot run" (no @mention, no other text) via python "${CONFIG.sharedScripts}/post_fix_reply.py" --owner ${input.owner} --repo ${input.repo} --pr-number ${input.prNumber} --body "bugbot run", wait 8 seconds inside this turn with the Monitor tool (per the WAITS AND POLLS rule above), then poll as above.\n` +
+      `4. No review yet on HEAD: check_bugbot_ci.py --check-active. If active (exit 0), poll: repeat check_bugbot_ci.py --check-clean / --check-active every 60 seconds (wait each 60-second interval inside this turn with the Monitor tool, per the WAITS AND POLLS rule above) for up to 25 iterations, then re-fetch the review. If not active (exit 1), post the literal comment "bugbot run" (no @mention, no other text) via ${REVIEWER_GATE_SENTINEL}python "${CONFIG.sharedScripts}/post_fix_reply.py" --owner ${input.owner} --repo ${input.repo} --pr-number ${input.prNumber} --body "bugbot run", wait 8 seconds inside this turn with the Monitor tool (per the WAITS AND POLLS rule above), then poll as above.\n` +
       `5. If after the full poll budget Bugbot has neither a check run nor a review on HEAD -> return {sha:${'`'}${head}${'`'}, clean:true, down:true, findings:[]} (treat as down).\n\n` +
       `Scope is the whole PR; you are only reading Bugbot's own output here. For each finding set category: 'code-standard' when it is a pure CODE_RULES/style violation (naming, comments, type hints, magic values, structure) with no behavioral impact; 'bug' otherwise. Return strictly the schema.`,
     { label: 'lens:bugbot', phase: 'Converge', schema: LENS_SCHEMA },
@@ -1314,7 +1358,7 @@ function runCopilotGate(head) {
     `You are the Copilot gate for ${prCoordinates}, HEAD ${head}. Do not edit code, commit, or push.\n\n` +
       `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` +
-      `   gh api --method POST repos/${input.owner}/${input.repo}/pulls/${input.prNumber}/requested_reviewers -f 'reviewers[]=copilot-pull-request-reviewer[bot]'\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` +
       `   - 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` +
@@ -1377,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
@@ -1485,9 +1531,10 @@ function parseDeferredPr(prUrl) {
  * @param {Array<object>} findings deduped code-standard-only findings
  * @param {string} sourceLabel short description of where the findings came from
  * @param {boolean} hasHardeningPrAlreadyOpened true when an earlier round already opened the environment-hardening PR for this run, so the verify and commit steps are skipped and no second PR opens while the edit retries the issue filing
- * @returns {Promise<object>} `{ followUpIssueFiled, issueUrl, hardeningPrOpened, deferredPr }` — followUpIssueFiled true when the standards-edit step returned a non-empty issue URL, issueUrl that filed URL (empty string when the filing failed) so a later reuse-path round can reference it when resolving its own threads, hardeningPrOpened true when the hardening-commit step returned a non-empty hardeningPrUrl (a PR opened) so the run-once latch holds even when that URL does not parse into coordinates, and false when the commit step returned an empty URL (no PR opened) so a later round retries the open, and deferredPr the opened PR's `{owner, repo, prNumber}` (null when no PR was opened or the committed URL does not parse) so the self-closing orchestrator can converge it in turn
+ * @param {{copilotDisabled: boolean, bugbotDisabled: boolean}} deferredReviewerFlags this run's latest resolved reviewer-down state, carried onto the deferred PR so a later generation converging it seeds the known-unavailable state instead of re-learning it
+ * @returns {Promise<object>} `{ followUpIssueFiled, issueUrl, hardeningPrOpened, deferredPr }` — followUpIssueFiled true when the standards-edit step returned a non-empty issue URL, issueUrl that filed URL (empty string when the filing failed) so a later reuse-path round can reference it when resolving its own threads, hardeningPrOpened true when the hardening-commit step returned a non-empty hardeningPrUrl (a PR opened) so the run-once latch holds even when that URL does not parse into coordinates, and false when the commit step returned an empty URL (no PR opened) so a later round retries the open, and deferredPr the opened PR's `{owner, repo, prNumber, copilotDisabled, bugbotDisabled}` (null when no PR was opened or the committed URL does not parse) so the self-closing orchestrator can converge it in turn
  */
-async function spawnStandardsFollowUp(head, findings, sourceLabel, hasHardeningPrAlreadyOpened) {
+async function spawnStandardsFollowUp(head, findings, sourceLabel, hasHardeningPrAlreadyOpened, deferredReviewerFlags) {
   const editResult = await runCodeEditorTask('standards-edit', { head, findings, sourceLabel })
   const followUpIssueFiled = typeof editResult?.issueUrl === 'string' && editResult.issueUrl.length > 0
   const followUpIssueUrl = followUpIssueFiled ? editResult.issueUrl : ''
@@ -1506,7 +1553,11 @@ async function spawnStandardsFollowUp(head, findings, sourceLabel, hasHardeningP
   const commitResult = await runCodeEditorTask('hardening-commit', {
     head, sourceLabel, hardeningRepoPath: editResult.hardeningRepoPath, hardeningBranch: editResult.hardeningBranch, issueUrl: editResult.issueUrl,
   })
-  const deferredPr = parseDeferredPr(commitResult?.hardeningPrUrl)
+  const parsedDeferredPr = parseDeferredPr(commitResult?.hardeningPrUrl)
+  const deferredPr =
+    parsedDeferredPr === null
+      ? null
+      : { ...parsedDeferredPr, copilotDisabled: deferredReviewerFlags.copilotDisabled, bugbotDisabled: deferredReviewerFlags.bugbotDisabled }
   const hardeningPrOpened = typeof commitResult?.hardeningPrUrl === 'string' && commitResult.hardeningPrUrl.length > 0
   return { followUpIssueFiled, issueUrl: followUpIssueUrl, hardeningPrOpened, deferredPr }
 }
@@ -1561,15 +1612,16 @@ async function resolveStandardsThreadsForBatch(head, findings, sourceLabel) {
  * @param {string} head PR HEAD SHA the findings were raised against
  * @param {Array<object>} findings deduped code-standard-only findings
  * @param {string} sourceLabel short description of where the findings came from
- * @returns {Promise<object>} `{ hardeningPrOpened, deferredPr }` — hardeningPrOpened true when a hardening PR was opened for this run, and deferredPr the opened PR's `{owner, repo, prNumber}` when this call opened it (null otherwise) so the self-closing orchestrator can converge it in turn
+ * @param {{copilotDisabled: boolean, bugbotDisabled: boolean}} deferredReviewerFlags this run's latest resolved reviewer-down state, carried onto the deferred PR so a later generation converging it seeds the known-unavailable state instead of re-learning it
+ * @returns {Promise<object>} `{ hardeningPrOpened, deferredPr }` — hardeningPrOpened true when a hardening PR was opened for this run, and deferredPr the opened PR's `{owner, repo, prNumber, copilotDisabled, bugbotDisabled}` when this call opened it (null otherwise) so the self-closing orchestrator can converge it in turn
  */
-async function openStandardsFollowUpOnce(head, findings, sourceLabel) {
+async function openStandardsFollowUpOnce(head, findings, sourceLabel, deferredReviewerFlags) {
   if (!shouldOpenStandardsFollowUp(hasStandardsFollowUpFiled)) {
     log(`Standards deferral (${sourceLabel}): reusing the follow-up fix issue already filed for this run rather than filing a duplicate; environment-hardening PR ${wasStandardsHardeningPrOpened ? 'was opened for this run' : 'was not opened for this run'}`)
     await resolveStandardsThreadsForBatch(head, findings, sourceLabel)
     return { hardeningPrOpened: wasStandardsHardeningPrOpened, deferredPr: null }
   }
-  const standardsOutcome = await spawnStandardsFollowUp(head, findings, sourceLabel, wasStandardsHardeningPrOpened)
+  const standardsOutcome = await spawnStandardsFollowUp(head, findings, sourceLabel, wasStandardsHardeningPrOpened, deferredReviewerFlags)
   hasStandardsFollowUpFiled = standardsOutcome?.followUpIssueFiled === true
   if (hasStandardsFollowUpFiled) {
     standardsFollowUpIssueUrl = standardsOutcome.issueUrl
@@ -1591,26 +1643,27 @@ let hasStandardsFollowUpFiled = false
 let wasStandardsHardeningPrOpened = false
 let standardsFollowUpIssueUrl = ''
 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')
   }
@@ -1622,29 +1675,33 @@ 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)}`)
     const lenses = await parallel([
-      () => runBugbotLens(head),
+      () => (isBugbotDownPreSpawn ? Promise.resolve({ sha: head, clean: true, down: true, findings: [] }) : runBugbotLens(head)),
       () => runCodeReviewLens(head),
       () => runAuditLens(head),
     ])
-    bugbotDown = resolveBugbotDown(lenses[0], input.bugbotDisabled || false)
+    bugbotDown = lenses[0] == null ? true : resolveReviewerDown(lenses[0], input.bugbotDisabled || false)
     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
     if (isStandardsOnlyRound(findings)) {
       log(`Round ${rounds}: ${findings.length} code-standard-only finding(s) — deferring to follow-up PRs and treating the round as passed`)
-      const standardsOutcome = await openStandardsFollowUpOnce(head, findings, 'converge-round')
+      const standardsOutcome = await openStandardsFollowUpOnce(head, findings, 'converge-round', { copilotDisabled: copilotDown, bugbotDisabled: bugbotDown })
       standardsNote = standardsDeferralNote(findings.length, standardsOutcome.hardeningPrOpened)
       if (standardsOutcome?.deferredPr) deferredPrs.push(standardsOutcome.deferredPr)
       const auditResult = await runGeneralUtilityTask('post-clean-audit', { head })
@@ -1666,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`)
@@ -1683,10 +1742,10 @@ while (iterations < CONFIG.maxIterations) {
   }
 
   if (phase === 'COPILOT') {
-    if (input.copilotDisabled) {
+    if (resolveReviewerDown(reviewerAvailability?.copilot, input.copilotDisabled || false)) {
       copilotDown = true
-      copilotNote = 'Copilot was skipped by the quota pre-check (out of premium-request quota, unreachable, or unconfigured) — the Copilot gate was bypassed and the PR was marked ready without a Copilot review'
-      log('Copilot gate: the quota pre-check reported Copilot unavailable — skipping the Copilot gate with no agent spawned and proceeding to mark-ready with the gate bypassed.')
+      copilotNote = 'Copilot was unavailable or out of premium-request quota this round — the Copilot gate was bypassed with no agent spawned and the PR was marked ready without a Copilot review'
+      log('Copilot gate: the shared reviewer-availability probe (or the run input) reported Copilot unavailable — skipping the Copilot gate with no agent spawned and proceeding to mark-ready with the gate bypassed.')
       phase = 'FINALIZE'
       continue
     }
@@ -1708,7 +1767,7 @@ while (iterations < CONFIG.maxIterations) {
     if (copilotOutcome.kind === 'fix') {
       if (isStandardsOnlyRound(copilotOutcome.findings)) {
         log(`Copilot raised ${copilotOutcome.findings.length} code-standard-only finding(s) — deferring to follow-up PRs and treating the gate as passed`)
-        const standardsOutcome = await openStandardsFollowUpOnce(head, copilotOutcome.findings, 'copilot')
+        const standardsOutcome = await openStandardsFollowUpOnce(head, copilotOutcome.findings, 'copilot', { copilotDisabled: copilotDown, bugbotDisabled: bugbotDown })
         standardsNote = standardsDeferralNote(copilotOutcome.findings.length, standardsOutcome.hardeningPrOpened)
         if (standardsOutcome?.deferredPr) deferredPrs.push(standardsOutcome.deferredPr)
         copilotDown = false
@@ -1726,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
     }
@@ -1753,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.