claude-dev-env 1.59.0 → 1.60.0

package/skills/autoconverge/workflow/converge.contract.test.mjs

@@ -1,206 +1,206 @@
-import { test } from 'node:test';
-import { strict as assert } from 'node:assert';
-import { readFileSync } from 'node:fs';
-import { fileURLToPath } from 'node:url';
-import { dirname, join } from 'node:path';
-
-const workflowDirectory = dirname(fileURLToPath(import.meta.url));
-const convergeSource = readFileSync(join(workflowDirectory, 'converge.mjs'), 'utf8');
-const gotchasSource = readFileSync(
-  join(workflowDirectory, '..', 'reference', 'gotchas.md'),
-  'utf8',
-);
-
-function lensPromptBody(builderName) {
-  const builderStart = convergeSource.indexOf(`function ${builderName}(`);
-  assert.notEqual(builderStart, -1, `expected ${builderName} to exist`);
-  const nextBuilderStart = convergeSource.indexOf('\nfunction ', builderStart + 1);
-  const builderEnd = nextBuilderStart === -1 ? convergeSource.length : nextBuilderStart;
-  return convergeSource.slice(builderStart, builderEnd);
-}
-
-test('code-review lens prompt no longer instructs a per-lens git fetch', () => {
-  assert.doesNotMatch(lensPromptBody('runCodeReviewLens'), /git fetch origin main/);
-});
-
-test('bug-audit lens prompt no longer instructs a per-lens git fetch', () => {
-  assert.doesNotMatch(lensPromptBody('runAuditLens'), /git fetch origin main/);
-});
-
-test('a single round-level prefetch step fetches origin/main before the parallel lenses', () => {
-  assert.match(convergeSource, /function prefetchMainForRound\(/);
-  const prefetchCallIndex = convergeSource.indexOf('await prefetchMainForRound(');
-  const parallelLensIndex = convergeSource.indexOf('const lenses = await parallel(');
-  assert.notEqual(prefetchCallIndex, -1, 'expected prefetchMainForRound to be invoked');
-  assert.notEqual(parallelLensIndex, -1, 'expected the parallel lens block to exist');
-  assert.ok(
-    prefetchCallIndex < parallelLensIndex,
-    'expected the round prefetch to run before the parallel lenses spawn',
-  );
-});
-
-test('bugbot lens preamble does not blanket-instruct passing --owner/--repo to every script', () => {
-  const bugbotPrompt = lensPromptBody('runBugbotLens');
-  assert.doesNotMatch(
-    bugbotPrompt,
-    /use the existing scripts; pass --owner/,
-    'the blanket clause breaks reviews_disabled.py, which accepts only --reviewer',
-  );
-});
-
-test('bugbot lens invokes reviews_disabled.py with only --reviewer', () => {
-  const bugbotPrompt = lensPromptBody('runBugbotLens');
-  const reviewsDisabledIndex = bugbotPrompt.indexOf('reviews_disabled.py');
-  assert.notEqual(reviewsDisabledIndex, -1, 'expected reviews_disabled.py invocation');
-  const invocationLineEnd = bugbotPrompt.indexOf('\\n', reviewsDisabledIndex);
-  const invocationLine = bugbotPrompt.slice(reviewsDisabledIndex, invocationLineEnd);
-  assert.match(invocationLine, /--reviewer bugbot/);
-  assert.doesNotMatch(
-    invocationLine,
-    /--owner|--repo/,
-    'reviews_disabled.py argparse rejects --owner/--repo with SystemExit(2)',
-  );
-});
-
-test('gotchas doc states parallel lenses must avoid concurrent git operations', () => {
-  assert.doesNotMatch(gotchasSource, /cannot race on git state/);
-  assert.match(gotchasSource, /fetch.*once.*before/i);
-});
-
-test('repair-convergence filters unresolved threads to bot authors and skips human threads', () => {
-  const repairPrompt = lensPromptBody('repairConvergence');
-  assert.match(
-    repairPrompt,
-    /cursor.*claude.*copilot|copilot.*cursor.*claude|claude.*cursor.*copilot/is,
-    'expected the bot-author allowlist (Cursor/Claude/Copilot) to be named',
-  );
-  assert.match(
-    repairPrompt,
-    /skip.*human|human.*skip/is,
-    'expected an explicit instruction to skip human reviewer threads',
-  );
-});
-
-test('repair-convergence no longer instructs resolving every unresolved thread without an author filter', () => {
-  const repairPrompt = lensPromptBody('repairConvergence');
-  assert.doesNotMatch(
-    repairPrompt,
-    /fetch every thread where isResolved is false/,
-    'the unfiltered instruction could resolve human reviewer threads',
-  );
-});
-
-test('bugbot lens delay instructions are shell-agnostic with PowerShell as an alternative', () => {
-  const bugbotPrompt = lensPromptBody('runBugbotLens');
-  assert.match(bugbotPrompt, /sleep 60/, 'expected a shell-agnostic 60-second poll delay');
-  assert.match(bugbotPrompt, /sleep 8/, 'expected a concrete 8-second delay command');
-  assert.match(
-    bugbotPrompt,
-    /Start-Sleep[\s\S]*alternative|alternative[\s\S]*Start-Sleep/i,
-    'expected PowerShell to be named only as an allowed alternative',
-  );
-  assert.doesNotMatch(
-    bugbotPrompt,
-    /wait 8 seconds(?!,)/,
-    'the vague "wait 8 seconds" phrasing must carry a concrete command',
-  );
-});
-
-test('copilot gate delay instruction is shell-agnostic with PowerShell as an alternative', () => {
-  const copilotPrompt = lensPromptBody('runCopilotGate');
-  assert.match(copilotPrompt, /sleep 360/, 'expected a shell-agnostic 360-second poll delay');
-  assert.match(
-    copilotPrompt,
-    /Start-Sleep[\s\S]*alternative|alternative[\s\S]*Start-Sleep/i,
-    'expected PowerShell to be named only as an allowed alternative',
-  );
-});
-
-test('gotchas doc describes the reviewer wait as shell-agnostic', () => {
-  assert.match(
-    gotchasSource,
-    /\bsleep\b/i,
-    'expected the wait guidance to name a shell-agnostic sleep',
-  );
-  assert.doesNotMatch(
-    gotchasSource,
-    /a single PowerShell\s*`?Start-Sleep`?\s*loop/i,
-    'PowerShell Start-Sleep must be an alternative, not the sole mechanism',
-  );
-});
-
-function finalizeRepairBranch() {
-  const repairCallIndex = convergeSource.indexOf('await repairConvergence(');
-  assert.notEqual(repairCallIndex, -1, 'expected the FINALIZE repair call to exist');
-  const transitionIndex = convergeSource.indexOf("phase = 'CONVERGE'", repairCallIndex);
-  assert.notEqual(transitionIndex, -1, 'expected a CONVERGE transition after the repair call');
-  const continueIndex = convergeSource.indexOf('continue', transitionIndex);
-  assert.notEqual(continueIndex, -1, 'expected a continue statement to close the FINALIZE repair branch');
-  const branchEnd = continueIndex + 'continue'.length;
-  return convergeSource.slice(repairCallIndex, branchEnd);
-}
-
-test('the FINALIZE repair branch does not re-assign head from the repair before re-converging', () => {
-  assert.doesNotMatch(
-    finalizeRepairBranch(),
-    /head\s*=\s*repair/,
-    'the next CONVERGE pass re-resolves HEAD from GitHub, so assigning the repair SHA here is dead',
-  );
-});
-
-function fixBranchAfter(branchLabel) {
-  const labelIndex = convergeSource.indexOf(branchLabel);
-  assert.notEqual(labelIndex, -1, `expected the ${branchLabel} marker to exist`);
-  const applyFixesIndex = convergeSource.indexOf('await applyFixes(', labelIndex);
-  assert.notEqual(applyFixesIndex, -1, `expected an applyFixes call after ${branchLabel}`);
-  const continueIndex = convergeSource.indexOf('continue', applyFixesIndex);
-  assert.notEqual(continueIndex, -1, `expected a continue statement to close the ${branchLabel} branch`);
-  const branchEnd = continueIndex + 'continue'.length;
-  return convergeSource.slice(applyFixesIndex, branchEnd);
-}
-
-test('the CONVERGE fix branch does not re-assign head from the fix before re-converging', () => {
-  assert.doesNotMatch(
-    fixBranchAfter('${findings.length} finding(s) — applying fixes'),
-    /head\s*=\s*fixProgress/,
-    'the next CONVERGE pass re-resolves HEAD from GitHub, so assigning the fix SHA here is dead',
-  );
-});
-
-test('the COPILOT fix branch does not re-assign head from the fix before re-converging', () => {
-  assert.doesNotMatch(
-    fixBranchAfter('${copilotOutcome.findings.length} finding(s) — fixing and re-converging'),
-    /head\s*=\s*fixProgress/,
-    'the CONVERGE pass it transitions to re-resolves HEAD from GitHub, so assigning the fix SHA here is dead',
-  );
-});
-
-test('the CONVERGE branch re-resolves HEAD from GitHub on every entry', () => {
-  const convergeBranchStart = convergeSource.indexOf("if (phase === 'CONVERGE')");
-  assert.notEqual(convergeBranchStart, -1, 'expected the CONVERGE branch to exist');
-  const resolveHeadIndex = convergeSource.indexOf('head = await resolveHead()', convergeBranchStart);
-  assert.notEqual(resolveHeadIndex, -1, 'expected CONVERGE to re-resolve HEAD via resolveHead()');
-});
-
-test('fix prompt resolves threads by PRRT thread node id looked up from the comment databaseId', () => {
-  const fixPrompt = lensPromptBody('applyFixes');
-  assert.match(fixPrompt, /PRRT/, 'expected the thread node id form (PRRT_...) to be named');
-  assert.match(
-    fixPrompt,
-    /databaseId/,
-    'expected the GraphQL lookup matching comment databaseId to be named',
-  );
-  assert.match(
-    fixPrompt,
-    /not the numeric comment id/,
-    'expected an explicit guard against passing the numeric comment id to resolve_thread',
-  );
-});
-
-test('fix prompt does not pass the numeric comment id straight to resolve_thread', () => {
-  assert.doesNotMatch(
-    lensPromptBody('applyFixes'),
-    /then resolve that thread \(use the github MCP pull_request_review_write/,
-    'resolve_thread and resolveReviewThread require a PRRT_... thread node id, not the comment id',
-  );
-});
+import { test } from 'node:test';
+import { strict as assert } from 'node:assert';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+
+const workflowDirectory = dirname(fileURLToPath(import.meta.url));
+const convergeSource = readFileSync(join(workflowDirectory, 'converge.mjs'), 'utf8');
+const gotchasSource = readFileSync(
+  join(workflowDirectory, '..', 'reference', 'gotchas.md'),
+  'utf8',
+);
+
+function lensPromptBody(builderName) {
+  const builderStart = convergeSource.indexOf(`function ${builderName}(`);
+  assert.notEqual(builderStart, -1, `expected ${builderName} to exist`);
+  const nextBuilderStart = convergeSource.indexOf('\nfunction ', builderStart + 1);
+  const builderEnd = nextBuilderStart === -1 ? convergeSource.length : nextBuilderStart;
+  return convergeSource.slice(builderStart, builderEnd);
+}
+
+test('code-review lens prompt no longer instructs a per-lens git fetch', () => {
+  assert.doesNotMatch(lensPromptBody('runCodeReviewLens'), /git fetch origin main/);
+});
+
+test('bug-audit lens prompt no longer instructs a per-lens git fetch', () => {
+  assert.doesNotMatch(lensPromptBody('runAuditLens'), /git fetch origin main/);
+});
+
+test('a single round-level prefetch step fetches origin/main before the parallel lenses', () => {
+  assert.match(convergeSource, /function prefetchMainForRound\(/);
+  const prefetchCallIndex = convergeSource.indexOf('await prefetchMainForRound(');
+  const parallelLensIndex = convergeSource.indexOf('const lenses = await parallel(');
+  assert.notEqual(prefetchCallIndex, -1, 'expected prefetchMainForRound to be invoked');
+  assert.notEqual(parallelLensIndex, -1, 'expected the parallel lens block to exist');
+  assert.ok(
+    prefetchCallIndex < parallelLensIndex,
+    'expected the round prefetch to run before the parallel lenses spawn',
+  );
+});
+
+test('bugbot lens preamble does not blanket-instruct passing --owner/--repo to every script', () => {
+  const bugbotPrompt = lensPromptBody('runBugbotLens');
+  assert.doesNotMatch(
+    bugbotPrompt,
+    /use the existing scripts; pass --owner/,
+    'the blanket clause breaks reviews_disabled.py, which accepts only --reviewer',
+  );
+});
+
+test('bugbot lens invokes reviews_disabled.py with only --reviewer', () => {
+  const bugbotPrompt = lensPromptBody('runBugbotLens');
+  const reviewsDisabledIndex = bugbotPrompt.indexOf('reviews_disabled.py');
+  assert.notEqual(reviewsDisabledIndex, -1, 'expected reviews_disabled.py invocation');
+  const invocationLineEnd = bugbotPrompt.indexOf('\\n', reviewsDisabledIndex);
+  const invocationLine = bugbotPrompt.slice(reviewsDisabledIndex, invocationLineEnd);
+  assert.match(invocationLine, /--reviewer bugbot/);
+  assert.doesNotMatch(
+    invocationLine,
+    /--owner|--repo/,
+    'reviews_disabled.py argparse rejects --owner/--repo with SystemExit(2)',
+  );
+});
+
+test('gotchas doc states parallel lenses must avoid concurrent git operations', () => {
+  assert.doesNotMatch(gotchasSource, /cannot race on git state/);
+  assert.match(gotchasSource, /fetch.*once.*before/i);
+});
+
+test('repair-convergence filters unresolved threads to bot authors and skips human threads', () => {
+  const repairPrompt = lensPromptBody('repairConvergence');
+  assert.match(
+    repairPrompt,
+    /cursor.*claude.*copilot|copilot.*cursor.*claude|claude.*cursor.*copilot/is,
+    'expected the bot-author allowlist (Cursor/Claude/Copilot) to be named',
+  );
+  assert.match(
+    repairPrompt,
+    /skip.*human|human.*skip/is,
+    'expected an explicit instruction to skip human reviewer threads',
+  );
+});
+
+test('repair-convergence no longer instructs resolving every unresolved thread without an author filter', () => {
+  const repairPrompt = lensPromptBody('repairConvergence');
+  assert.doesNotMatch(
+    repairPrompt,
+    /fetch every thread where isResolved is false/,
+    'the unfiltered instruction could resolve human reviewer threads',
+  );
+});
+
+test('bugbot lens delay instructions are shell-agnostic with PowerShell as an alternative', () => {
+  const bugbotPrompt = lensPromptBody('runBugbotLens');
+  assert.match(bugbotPrompt, /sleep 60/, 'expected a shell-agnostic 60-second poll delay');
+  assert.match(bugbotPrompt, /sleep 8/, 'expected a concrete 8-second delay command');
+  assert.match(
+    bugbotPrompt,
+    /Start-Sleep[\s\S]*alternative|alternative[\s\S]*Start-Sleep/i,
+    'expected PowerShell to be named only as an allowed alternative',
+  );
+  assert.doesNotMatch(
+    bugbotPrompt,
+    /wait 8 seconds(?!,)/,
+    'the vague "wait 8 seconds" phrasing must carry a concrete command',
+  );
+});
+
+test('copilot gate delay instruction is shell-agnostic with PowerShell as an alternative', () => {
+  const copilotPrompt = lensPromptBody('runCopilotGate');
+  assert.match(copilotPrompt, /sleep 360/, 'expected a shell-agnostic 360-second poll delay');
+  assert.match(
+    copilotPrompt,
+    /Start-Sleep[\s\S]*alternative|alternative[\s\S]*Start-Sleep/i,
+    'expected PowerShell to be named only as an allowed alternative',
+  );
+});
+
+test('gotchas doc describes the reviewer wait as shell-agnostic', () => {
+  assert.match(
+    gotchasSource,
+    /\bsleep\b/i,
+    'expected the wait guidance to name a shell-agnostic sleep',
+  );
+  assert.doesNotMatch(
+    gotchasSource,
+    /a single PowerShell\s*`?Start-Sleep`?\s*loop/i,
+    'PowerShell Start-Sleep must be an alternative, not the sole mechanism',
+  );
+});
+
+function finalizeRepairBranch() {
+  const repairCallIndex = convergeSource.indexOf('await repairConvergence(');
+  assert.notEqual(repairCallIndex, -1, 'expected the FINALIZE repair call to exist');
+  const transitionIndex = convergeSource.indexOf("phase = 'CONVERGE'", repairCallIndex);
+  assert.notEqual(transitionIndex, -1, 'expected a CONVERGE transition after the repair call');
+  const continueIndex = convergeSource.indexOf('continue', transitionIndex);
+  assert.notEqual(continueIndex, -1, 'expected a continue statement to close the FINALIZE repair branch');
+  const branchEnd = continueIndex + 'continue'.length;
+  return convergeSource.slice(repairCallIndex, branchEnd);
+}
+
+test('the FINALIZE repair branch does not re-assign head from the repair before re-converging', () => {
+  assert.doesNotMatch(
+    finalizeRepairBranch(),
+    /head\s*=\s*repair/,
+    'the next CONVERGE pass re-resolves HEAD from GitHub, so assigning the repair SHA here is dead',
+  );
+});
+
+function fixBranchAfter(branchLabel) {
+  const labelIndex = convergeSource.indexOf(branchLabel);
+  assert.notEqual(labelIndex, -1, `expected the ${branchLabel} marker to exist`);
+  const applyFixesIndex = convergeSource.indexOf('await applyFixes(', labelIndex);
+  assert.notEqual(applyFixesIndex, -1, `expected an applyFixes call after ${branchLabel}`);
+  const continueIndex = convergeSource.indexOf('continue', applyFixesIndex);
+  assert.notEqual(continueIndex, -1, `expected a continue statement to close the ${branchLabel} branch`);
+  const branchEnd = continueIndex + 'continue'.length;
+  return convergeSource.slice(applyFixesIndex, branchEnd);
+}
+
+test('the CONVERGE fix branch does not re-assign head from the fix before re-converging', () => {
+  assert.doesNotMatch(
+    fixBranchAfter('${findings.length} finding(s) — applying fixes'),
+    /head\s*=\s*fixProgress/,
+    'the next CONVERGE pass re-resolves HEAD from GitHub, so assigning the fix SHA here is dead',
+  );
+});
+
+test('the COPILOT fix branch does not re-assign head from the fix before re-converging', () => {
+  assert.doesNotMatch(
+    fixBranchAfter('${copilotOutcome.findings.length} finding(s) — fixing and re-converging'),
+    /head\s*=\s*fixProgress/,
+    'the CONVERGE pass it transitions to re-resolves HEAD from GitHub, so assigning the fix SHA here is dead',
+  );
+});
+
+test('the CONVERGE branch re-resolves HEAD from GitHub on every entry', () => {
+  const convergeBranchStart = convergeSource.indexOf("if (phase === 'CONVERGE')");
+  assert.notEqual(convergeBranchStart, -1, 'expected the CONVERGE branch to exist');
+  const resolveHeadIndex = convergeSource.indexOf('head = await resolveHead()', convergeBranchStart);
+  assert.notEqual(resolveHeadIndex, -1, 'expected CONVERGE to re-resolve HEAD via resolveHead()');
+});
+
+test('fix prompt resolves threads by PRRT thread node id looked up from the comment databaseId', () => {
+  const fixPrompt = lensPromptBody('applyFixes');
+  assert.match(fixPrompt, /PRRT/, 'expected the thread node id form (PRRT_...) to be named');
+  assert.match(
+    fixPrompt,
+    /databaseId/,
+    'expected the GraphQL lookup matching comment databaseId to be named',
+  );
+  assert.match(
+    fixPrompt,
+    /not the numeric comment id/,
+    'expected an explicit guard against passing the numeric comment id to resolve_thread',
+  );
+});
+
+test('fix prompt does not pass the numeric comment id straight to resolve_thread', () => {
+  assert.doesNotMatch(
+    lensPromptBody('applyFixes'),
+    /then resolve that thread \(use the github MCP pull_request_review_write/,
+    'resolve_thread and resolveReviewThread require a PRRT_... thread node id, not the comment id',
+  );
+});

package/skills/autoconverge/workflow/converge.mjs

@@ -105,6 +105,31 @@ const FIX_SCHEMA = {
   required: ['newSha', 'pushed', 'resolvedWithoutCommit', 'summary'],
 }
 
+const CONVERGENCE_SUMMARY_SCHEMA = {
+  type: 'object',
+  additionalProperties: false,
+  properties: {
+    verdictLine: { type: 'string', description: 'one factual BLUF sentence: converged?, distinct issue-class count, all fixed or deferred. No hedging words.' },
+    issueClasses: {
+      type: 'array',
+      items: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          plainName: { type: 'string', description: 'everyday-language name of the issue class — no tool tokens, rule ids, file paths, line numbers, severity codes (P0/P1/P2), or bot names' },
+          count: { type: 'integer', description: 'number of raw findings grouped into this class' },
+          severity: { type: 'string', enum: ['P0', 'P1', 'P2'], description: 'most severe among the class' },
+          category: { type: 'string', enum: ['bug', 'code-standard'] },
+          status: { type: 'string', enum: ['fixed', 'deferred'] },
+          whatItWas: { type: 'string', description: 'at most 2 sentences, plain language, what the problem was' },
+        },
+        required: ['plainName', 'count', 'severity', 'category', 'status', 'whatItWas'],
+      },
+    },
+  },
+  required: ['verdictLine', 'issueClasses'],
+}
+
 const CONVERGENCE_SCHEMA = {
   type: 'object',
   additionalProperties: false,
@@ -124,6 +149,17 @@ const READY_SCHEMA = {
   required: ['ready'],
 }
 
+const CLEAN_AUDIT_SCHEMA = {
+  type: 'object',
+  additionalProperties: false,
+  properties: {
+    posted: { type: 'boolean', description: 'true only when post_audit_thread.py printed the review URL confirming the CLEAN bugteam review landed on HEAD' },
+    reviewUrl: { type: 'string', description: 'the posted review URL when posted is true, otherwise an empty string' },
+    reason: { type: 'string', description: 'when posted is false, the one-line reason the post did not land (a permission denial, a classifier block, or a script error)' },
+  },
+  required: ['posted', 'reviewUrl', 'reason'],
+}
+
 const SEVERITY_RANK = { P0: 0, P1: 1, P2: 2 }
 const SHA_COMPARISON_PREFIX_LENGTH = 7
 
@@ -579,17 +615,41 @@ function applyFixes(head, findings, sourceLabel) {
 
 /**
  * Post the terminal CLEAN bugteam audit artifact so check_convergence.py sees
- * a clean bugteam review on the converged HEAD.
+ * a clean bugteam review on the converged HEAD. The post is load-bearing: the
+ * convergence gate's bugteam-review check can never pass until this review
+ * lands, so the result reports whether the post succeeded rather than
+ * discarding it. A blocked post (a permission or auto-mode-classifier denial)
+ * or a script error returns posted:false with the reason so the caller can
+ * surface a blocker instead of re-converging into the iteration cap.
  * @param {string} head converged PR HEAD SHA
- * @returns {Promise<string>} agent transcript (unused)
+ * @returns {Promise<object>} CLEAN_AUDIT_SCHEMA result
  */
 function postCleanAudit(head) {
   return convergeAgent(
     `Post a CLEAN bugteam audit review on ${prCoordinates} at commit ${head}. All review lenses are clean on this HEAD.\n\n` +
       `Write an empty findings file: create a temp file containing exactly [] (an empty JSON array). Then run:\n` +
       `python "${CONFIG.prLoopScripts}/post_audit_thread.py" --skill bugteam --owner ${input.owner} --repo ${input.repo} --pr-number ${input.prNumber} --commit ${head} --state CLEAN --findings-json <temp-file>\n` +
-      `Run the script with --help first if any flag name differs. This posts the APPROVE review body that check_convergence.py reads for the bugteam gate. Do not edit code, commit, or push.`,
-    { label: 'post-clean-audit', phase: 'Converge', agentType: 'general-purpose' },
+      `Run the script with --help first if any flag name differs. This posts the APPROVE review body that check_convergence.py reads for the bugteam gate. Do not edit code, commit, or push.\n\n` +
+      `Report whether the review landed. When the script prints a review URL, return {posted:true, reviewUrl:<that URL>, reason:""}. When the script is denied (a permission prompt or auto-mode-classifier block), errors, or prints anything other than a review URL, return {posted:false, reviewUrl:"", reason:<the denial message or error as one line>}. Do not retry a denied post.`,
+    { label: 'post-clean-audit', phase: 'Converge', schema: CLEAN_AUDIT_SCHEMA, agentType: 'general-purpose' },
+  )
+}
+
+/**
+ * Blocker message for a CLEAN bugteam audit that did not land. The convergence
+ * gate's bugteam-review check can never pass without this review, so a blocked
+ * post stops the run with an actionable message rather than re-converging until
+ * the iteration cap. Handles a dead post agent (a null result) as not posted.
+ * @param {string} head converged PR HEAD SHA
+ * @param {object} auditResult CLEAN_AUDIT_SCHEMA result from postCleanAudit, or null when the agent died
+ * @returns {string} the blocker message naming the post failure and the unblock path
+ */
+function cleanAuditBlocker(head, auditResult) {
+  const reason = auditResult?.reason || 'the post agent returned no result'
+  return (
+    `clean-audit post blocked: the CLEAN bugteam review could not be posted on HEAD ${head} (${reason}) — ` +
+    `the convergence gate's bugteam-review check can never pass without it, so the run stops rather than re-converge to the iteration cap. ` +
+    `Allow post_audit_thread.py for this run with a Bash permission rule, or post the CLEAN review by hand, then re-run.`
   )
 }
 
@@ -730,6 +790,51 @@ function spawnStandardsFollowUp(head, findings, sourceLabel) {
   )
 }
 
+/**
+ * Spawn the convergence-summary agent at finalize so its StructuredOutput is
+ * recorded into the run journal for the closing report to read. The agent groups
+ * the deduped findings into plain-language issue classes, translates reviewer
+ * jargon to everyday English, and writes one BLUF verdict line. The side effect
+ * is the journal record; the return value is discarded by the caller.
+ * @param {Array<object>} distinctFindings deduped findings across every round
+ * @param {Array<string>} fixSummaries per-round fix-lens one-line summaries
+ * @param {number} roundCount the number of converge rounds the run took
+ * @param {string|null} standardsNote deferral note when a round was code-standard-only
+ * @param {string|null} copilotNote outage note when the Copilot gate was bypassed
+ * @returns {Promise<object>} CONVERGENCE_SUMMARY_SCHEMA result (journal side effect)
+ */
+function spawnConvergenceSummary(distinctFindings, fixSummaries, roundCount, standardsNote, copilotNote) {
+  const findingsBlock = distinctFindings.length
+    ? distinctFindings
+        .map((each, position) => {
+          const truncatedDetail = (each.detail || '').slice(0, 400)
+          return `${position + 1}. [${each.severity}/${each.category}] ${each.file}:${each.line} — ${each.title} :: ${truncatedDetail}`
+        })
+        .join('\n')
+    : 'none — every lens was clean on a stable HEAD'
+  const fixSummariesBlock = fixSummaries.length
+    ? fixSummaries.map((each, position) => `${position + 1}. ${each}`).join('\n')
+    : 'none'
+  const standardsBlock = standardsNote ? `\nDeferred code-standard note: ${standardsNote}\n` : ''
+  const copilotBlock = copilotNote ? `\nCopilot gate note: ${copilotNote}\n` : ''
+  return convergeAgent(
+    `You write the plain-language convergence summary for ${prCoordinates}. The autoconverge run reached convergence in ${roundCount} round(s). Use ONLY the findings and fix summaries below; invent nothing not present.\n\n` +
+      `Distinct findings caught across the run (already deduped):\n${findingsBlock}\n\n` +
+      `Per-round fix summaries:\n${fixSummariesBlock}\n${standardsBlock}${copilotBlock}\n` +
+      `Produce a summary an everyday reader understands:\n` +
+      `- GROUP near-duplicate findings into issue CLASSES: the same KIND of problem across different files or lines becomes ONE class with a count. Example: seven "Missing return type annotation on test function" findings become one class with count 7.\n` +
+      `- TRANSLATE reviewer jargon into plain everyday English. Examples: "CodingGuidelineID 1000000 / Repository guideline (Types)" -> "a typing rule the project enforces"; "missing return type annotation / Add -> None" -> "a test did not declare what it returns"; "Banned identifier result" -> "a vague variable name the project bans"; a magic-value finding -> "a raw number or string that should be a named value".\n` +
+      `- plainName must carry NO tool token, rule id, file path, line number, severity code (P0/P1/P2), or bot name.\n` +
+      `- Lead with category 'bug' classes, then 'code-standard'. Cap to about 5 classes. whatItWas is at most 2 sentences. No paragraphs.\n` +
+      `- status is 'fixed' unless the fix summaries or the deferred code-standard note mark the class deferred, in which case status is 'deferred'.\n` +
+      `- Use NO hedging words anywhere (likely, probably, should, appears, seems, may, might, could, possibly). State facts ("caught and fixed").\n` +
+      `- When there are zero findings, return issueClasses: [] and a verdictLine stating the run converged with no issues caught.\n` +
+      `- verdictLine is one factual sentence naming the round count and that all classes are fixed or deferred.\n\n` +
+      `Return strictly the schema.`,
+    { label: 'convergence-summary', phase: 'Finalize', schema: CONVERGENCE_SUMMARY_SCHEMA, agentType: 'general-purpose' },
+  )
+}
+
 let phase = 'CONVERGE'
 let head = null
 let rounds = 0
@@ -739,6 +844,8 @@ let bugbotDown = input.bugbotDisabled || false
 let copilotDown = false
 let copilotNote = null
 let standardsNote = null
+const allRoundFindings = []
+const fixSummaries = []
 
 while (iterations < CONFIG.maxIterations) {
   iterations += 1
@@ -765,15 +872,22 @@ while (iterations < CONFIG.maxIterations) {
     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`)
+      allRoundFindings.push(...findings)
       await spawnStandardsFollowUp(head, findings, 'converge-round')
       standardsNote = `${findings.length} code-standard finding(s) deferred to a follow-up fix issue plus an environment-hardening PR — verify both land`
-      await postCleanAudit(head)
+      const auditResult = await postCleanAudit(head)
+      if (!auditResult?.posted) {
+        blocker = cleanAuditBlocker(head, auditResult)
+        break
+      }
       phase = 'COPILOT'
       continue
     }
     if (findings.length > 0) {
       log(`Round ${rounds}: ${findings.length} finding(s) — applying fixes`)
+      allRoundFindings.push(...findings)
       const fixResult = await applyFixes(head, findings, 'converge-round')
+      if (fixResult?.summary) fixSummaries.push(fixResult.summary)
       const hadThreadBearingFinding = findings.some((each) => collectFindingThreadIds(each).length > 0)
       const fixProgress = detectFixProgress(fixResult, head, hadThreadBearingFinding)
       if (!fixProgress.progressed) {
@@ -789,7 +903,11 @@ while (iterations < CONFIG.maxIterations) {
       continue
     }
     log(`Round ${rounds}: all lenses clean on ${head?.slice(0, 7)} — posting clean audit artifact`)
-    await postCleanAudit(head)
+    const auditResult = await postCleanAudit(head)
+    if (!auditResult?.posted) {
+      blocker = cleanAuditBlocker(head, auditResult)
+      break
+    }
     phase = 'COPILOT'
     continue
   }
@@ -813,6 +931,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`)
+        allRoundFindings.push(...copilotOutcome.findings)
         await spawnStandardsFollowUp(head, copilotOutcome.findings, 'copilot')
         standardsNote = `${copilotOutcome.findings.length} code-standard finding(s) deferred to a follow-up fix issue plus an environment-hardening PR — verify both land`
         copilotDown = false
@@ -821,7 +940,9 @@ while (iterations < CONFIG.maxIterations) {
         continue
       }
       log(`Copilot raised ${copilotOutcome.findings.length} finding(s) — fixing and re-converging`)
+      allRoundFindings.push(...copilotOutcome.findings)
       const fixResult = await applyFixes(head, copilotOutcome.findings, 'copilot')
+      if (fixResult?.summary) fixSummaries.push(fixResult.summary)
       const hadThreadBearingFinding = copilotOutcome.findings.some((each) => collectFindingThreadIds(each).length > 0)
       const fixProgress = detectFixProgress(fixResult, head, hadThreadBearingFinding)
       if (!fixProgress.progressed) {
@@ -850,6 +971,7 @@ while (iterations < CONFIG.maxIterations) {
       const readyResult = await markReady(head, copilotDown)
       const readyOutcome = classifyReadyOutcome(readyResult)
       if (readyOutcome.converged) {
+        await spawnConvergenceSummary(dedupeFindings(allRoundFindings), fixSummaries, rounds, standardsNote, copilotNote)
         return { converged: true, rounds, finalSha: head, blocker: null, standardsNote, copilotNote }
       }
       blocker = readyOutcome.blocker