claude-dev-env 1.59.0 → 1.61.0

package/skills/autoconverge/workflow/converge.mjs

@@ -105,6 +105,77 @@ const FIX_SCHEMA = {
   required: ['newSha', 'pushed', 'resolvedWithoutCommit', 'summary'],
 }
 
+const EDIT_SCHEMA = {
+  type: 'object',
+  additionalProperties: false,
+  properties: {
+    edited: { type: 'boolean', description: 'true when the step edited code to fix at least one finding' },
+    resolvedWithoutCommit: { type: 'boolean', description: 'true when every finding was already addressed so no code change was made, yet each finding thread was still resolved' },
+    summary: { type: 'string' },
+  },
+  required: ['edited', 'resolvedWithoutCommit', 'summary'],
+}
+
+const REPAIR_EDIT_SCHEMA = {
+  type: 'object',
+  additionalProperties: false,
+  properties: {
+    edited: { type: 'boolean', description: 'true when a still-applicable bot-thread concern was fixed test-first in the working tree' },
+    rebased: { type: 'boolean', description: 'true when the branch was rebased onto origin/main to restore mergeability' },
+    resolvedWithoutCommit: { type: 'boolean', description: 'true when the failing gates were addressed with neither a code change nor a rebase — bot threads resolved only, so there is nothing for the commit step to push' },
+    summary: { type: 'string' },
+  },
+  required: ['edited', 'rebased', 'resolvedWithoutCommit', 'summary'],
+}
+
+const STANDARDS_EDIT_SCHEMA = {
+  type: 'object',
+  additionalProperties: false,
+  properties: {
+    issueUrl: { type: 'string', description: 'the follow-up fix issue URL, or an empty string when the issue could not be filed' },
+    hardeningRepoPath: { type: 'string', description: 'absolute path of the environment-config repo checkout the hardening branch was edited in, or an empty string when no hardening edit was made' },
+    hardeningBranch: { type: 'string', description: 'the hardening branch name created in that repo, or an empty string when no hardening edit was made' },
+    hardeningEdited: { type: 'boolean', description: 'true when hooks or rules were edited in the working tree of the hardening repo, uncommitted, so the verify and commit steps have a surface to bind and push' },
+    summary: { type: 'string' },
+  },
+  required: ['issueUrl', 'hardeningRepoPath', 'hardeningBranch', 'hardeningEdited', 'summary'],
+}
+
+const VERDICT_FENCE_STEPS =
+  `Compute the binding hash for the live surface by running exactly:\n` +
+  `   "C:\\Python313\\python.exe" "<REPO>/packages/claude-dev-env/hooks/blocking/verification_verdict_store.py" --manifest-hash "<REPO>"\n` +
+  `   (substitute the REPO path you resolved). That prints a single 64-char hex hash on stdout — capture it.\n` +
+  `Then END your message with a fenced verdict block exactly in this shape, on its own, carrying that hash:\n` +
+  "   ```verdict\n" +
+  `   {"all_pass": true, "findings": [], "manifest_sha256": "<that hash>"}\n` +
+  "   ```\n" +
+  `   When verification fails, set all_pass to false and list the unresolved concerns in findings; still include the manifest_sha256. The verdict fence must be the last thing in your message.`
+
+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 +195,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
 
@@ -277,6 +359,33 @@ function normalizeShaForComparison(sha) {
   return sha.slice(0, SHA_COMPARISON_PREFIX_LENGTH).toLowerCase()
 }
 
+/**
+ * Decide whether a workflow code-verifier transcript ended in a passing
+ * verdict. The verify step runs with no schema so its verdict lands as plain
+ * assistant text; this reads the LAST ```verdict ...``` fenced JSON block and
+ * returns true only when it parses to an object with all_pass true. A missing
+ * fence, a parse failure, or all_pass false reads as not-passed so the commit
+ * step is skipped and the round reads as not-progressed.
+ * @param {string|null|undefined} verifyTranscript the verifier's transcript text
+ * @returns {boolean} true only when the last verdict fence reports all_pass true
+ */
+function verdictPassed(verifyTranscript) {
+  if (typeof verifyTranscript !== 'string') return false
+  const fencePattern = /```verdict\s*\n([\s\S]*?)```/g
+  let lastFenceBody = null
+  let eachMatch
+  while ((eachMatch = fencePattern.exec(verifyTranscript)) !== null) {
+    lastFenceBody = eachMatch[1]
+  }
+  if (lastFenceBody === null) return false
+  try {
+    const verdictRecord = JSON.parse(lastFenceBody)
+    return verdictRecord != null && verdictRecord.all_pass === true
+  } catch {
+    return false
+  }
+}
+
 /**
  * Decide whether a fix lens actually advanced the round: a pushed fix that moved
  * HEAD progressed, and so did an all-stale round whose findings were every one
@@ -540,15 +649,12 @@ function runAuditLens(head) {
 }
 
 /**
- * Fix lens: one clean-coder applies every finding in a single TDD commit,
- * pushes, then replies to and resolves any real GitHub review threads.
- * @param {string} head PR HEAD SHA the findings were raised against
- * @param {Array<object>} findings deduped findings across all lenses
- * @param {string} sourceLabel short description of where the findings came from
- * @returns {Promise<object>} FIX_SCHEMA result
+ * Render the numbered findings block shared by the fix steps.
+ * @param {Array<object>} findings deduped findings to render
+ * @returns {string} one numbered line per finding, with any thread-id note
  */
-function applyFixes(head, findings, sourceLabel) {
-  const findingsBlock = findings
+function renderFindingsBlock(findings) {
+  return findings
     .map((each, position) => {
       const eachThreadIds = collectFindingThreadIds(each)
       const threadNote = eachThreadIds.length
@@ -557,39 +663,156 @@ function applyFixes(head, findings, sourceLabel) {
       return `${position + 1}. [${each.severity}] ${each.file}:${each.line} — ${each.title}\n   ${each.detail}${threadNote}`
     })
     .join('\n')
+}
+
+/**
+ * Edit step: one clean-coder fixes every finding test-first in the working
+ * tree and resolves the GitHub review threads, making NO commit or push so the
+ * verify step can bind a verdict to the unstaged fixes.
+ * @param {string} head PR HEAD SHA the findings were raised against
+ * @param {Array<object>} findings deduped findings across all lenses
+ * @param {string} sourceLabel short description of where the findings came from
+ * @returns {Promise<object>} EDIT_SCHEMA result
+ */
+function applyFixesEdit(head, findings, sourceLabel) {
+  const findingsBlock = renderFindingsBlock(findings)
   const threadIds = findings
     .flatMap((each) => collectFindingThreadIds(each))
     .filter((each) => typeof each === 'number')
   return convergeAgent(
-    `You are fixing ${findings.length} finding(s) (${sourceLabel}) on ${prCoordinates}, HEAD ${head}.\n\n` +
+    `You are the EDIT step fixing ${findings.length} finding(s) (${sourceLabel}) on ${prCoordinates}, HEAD ${head}. A separate verify step then a separate commit step run after you.\n\n` +
       `Findings:\n${findingsBlock}\n\n` +
       `Rules:\n` +
       `- Confirm the working tree is on the PR branch at HEAD ${head} with no unrelated edits before you start.\n` +
       `- Fix every finding test-first (failing test, then minimum code to pass) per CODE_RULES. Verify each concern against current code; a finding whose concern no longer applies needs no code change but still needs its thread resolved.\n` +
-      `- Make ONE commit for all fixes, then push to the PR branch.\n` +
+      `- Leave all fixes in the working tree. Do NOT commit and do NOT push — the commit step does that after verification. Committing or pushing here would change the surface the verifier binds to.\n` +
       `- For each finding that carries a GitHub review comment id (${threadIds.length ? threadIds.join(', ') : 'none this batch'}): post an inline reply with python "${CONFIG.sharedScripts}/post_fix_reply.py" --owner ${input.owner} --repo ${input.repo} --pr-number ${input.prNumber} --in-reply-to <id> --body "<what changed>". Then resolve the PR review thread by thread node id (PRRT_...): look up the thread id for that comment via GraphQL (match on comment databaseId == <id> in the pull request's reviewThreads), then call the github MCP pull_request_review_write method=resolve_thread with threadId=<PRRT_...> (not the numeric comment id), or run the resolveReviewThread GraphQL mutation with the same threadId.\n` +
       `- Findings with replyToCommentId null are in-memory audit findings: fix them, no reply needed.\n\n` +
       `Return values:\n` +
-      `- When you commit and push a fix: newSha=the new HEAD SHA after your push, pushed=true, resolvedWithoutCommit=false.\n` +
-      `- When every finding was already addressed so no code change is needed — yet you still resolved each GitHub review thread above: newSha=${head} (the unchanged HEAD), pushed=false, resolvedWithoutCommit=true. Only set this when every thread that carries a comment id is resolved; otherwise the round is treated as stalled.\n` +
+      `- When you edited code to fix at least one finding: edited=true, resolvedWithoutCommit=false.\n` +
+      `- When every finding was already addressed so no code change was needed — yet you still resolved each GitHub review thread above: edited=false, resolvedWithoutCommit=true. Only set this when every thread that carries a comment id is resolved; otherwise the round is treated as stalled.\n` +
       `Always include a one-line summary.`,
-    { label: `fix:${sourceLabel}`, phase: 'Converge', schema: FIX_SCHEMA, agentType: 'clean-coder' },
+    { label: `fix-edit:${sourceLabel}`, phase: 'Converge', schema: EDIT_SCHEMA, agentType: 'clean-coder' },
+  )
+}
+
+/**
+ * Verify step: a code-verifier checks the working-tree fixes against the
+ * findings, computes the binding surface hash, and ends with a verdict fence
+ * as plain assistant text (NO schema, so the fence is not consumed as
+ * structured output). The fence's manifest_sha256 is what unlocks the
+ * verified-commit gate for the commit step. The verifier makes no edits.
+ * @param {string} head PR HEAD SHA the findings were raised against
+ * @param {Array<object>} findings deduped findings the fixes must address
+ * @param {string} sourceLabel short description of where the findings came from
+ * @returns {Promise<string>} the verifier transcript carrying the verdict fence
+ */
+function verifyFixesInWorkingTree(head, findings, sourceLabel) {
+  const findingsBlock = renderFindingsBlock(findings)
+  return convergeAgent(
+    `You are the VERIFY step for ${findings.length} finding(s) (${sourceLabel}) on ${prCoordinates}, HEAD ${head}. The edit step left fixes in the working tree, uncommitted. Do NO edits of any kind — verification only; any edit invalidates the verdict you are about to emit.\n\n` +
+      `Findings the working-tree fixes must address:\n${findingsBlock}\n\n` +
+      `Steps:\n` +
+      `1. Resolve the worktree repo root: REPO=$(git rev-parse --show-toplevel).\n` +
+      `2. Verify the uncommitted working-tree changes resolve every finding above: run the relevant tests and the named gates against the working tree. Read the diff (git diff) and confirm each finding is fixed test-first per CODE_RULES.\n` +
+      `3. ${VERDICT_FENCE_STEPS}`,
+    { label: `fix-verify:${sourceLabel}`, phase: 'Converge', agentType: 'code-verifier' },
   )
 }
 
+/**
+ * Commit step: one clean-coder commits the already-verified working-tree fixes
+ * in a single commit and pushes to the PR branch, making NO further file edits
+ * — any edit changes the surface and invalidates the verifier verdict that
+ * unlocks the commit gate.
+ * @param {string} head PR HEAD SHA before the fix commit
+ * @param {string} sourceLabel short description of where the findings came from
+ * @returns {Promise<object>} FIX_SCHEMA result
+ */
+function commitVerifiedFixes(head, sourceLabel) {
+  return convergeAgent(
+    `You are the COMMIT step for fixes (${sourceLabel}) on ${prCoordinates}, HEAD ${head}. The edit step left fixes in the working tree and the verify step passed, so a verifier verdict already binds to this exact working tree.\n\n` +
+      `Rules:\n` +
+      `- Make NO further file edits of any kind. Any edit changes the surface and invalidates the verdict that unlocks the commit gate, so the commit would be blocked. Do not run a formatter, do not touch a test, do not re-fix anything — only commit and push what is already there.\n` +
+      `- Make ONE commit for all the working-tree fixes, then push to the PR branch.\n\n` +
+      `Return values: newSha=the new HEAD SHA after your push, pushed=true, resolvedWithoutCommit=false, and a one-line summary. If the commit or push is blocked or fails, return newSha=${head}, pushed=false, resolvedWithoutCommit=false, and a summary naming the failure.`,
+    { label: `fix-commit:${sourceLabel}`, phase: 'Converge', schema: FIX_SCHEMA, agentType: 'clean-coder' },
+  )
+}
+
+/**
+ * Fix lens: edit (clean-coder, no commit) -> verify (code-verifier emits a
+ * verdict fence binding the working tree) -> commit (clean-coder, one commit +
+ * push, no edits). Splitting the single editing-and-committing agent lets a
+ * workflow code-verifier produce the verdict the verified-commit gate requires,
+ * which the SubagentStop minter cannot mint for workflow-spawned agents. When
+ * verification fails (or the edit step stalled with no thread to resolve), the
+ * commit step is skipped and the unchanged HEAD is returned so the round reads
+ * as not-progressed.
+ * @param {string} head PR HEAD SHA the findings were raised against
+ * @param {Array<object>} findings deduped findings across all lenses
+ * @param {string} sourceLabel short description of where the findings came from
+ * @returns {Promise<object>} FIX_SCHEMA result
+ */
+async function applyFixes(head, findings, sourceLabel) {
+  const editResult = await applyFixesEdit(head, findings, sourceLabel)
+  if (editResult?.resolvedWithoutCommit === true && editResult?.edited !== true) {
+    return {
+      newSha: head,
+      pushed: false,
+      resolvedWithoutCommit: true,
+      summary: editResult?.summary || 'fixes resolved without a code change',
+    }
+  }
+  const verifyTranscript = await verifyFixesInWorkingTree(head, findings, sourceLabel)
+  if (!verdictPassed(verifyTranscript)) {
+    return {
+      newSha: head,
+      pushed: false,
+      resolvedWithoutCommit: false,
+      summary: `verify step did not pass the working-tree fixes for ${findings.length} finding(s) — not committing`,
+    }
+  }
+  return commitVerifiedFixes(head, 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.`
   )
 }
 
@@ -664,28 +887,121 @@ function markReady(head, copilotDown) {
 }
 
 /**
- * Address the gates a convergence check reported as failing, then hand control
- * back to the converge phase. Resolves lingering bot threads and rebases when
- * the PR is not mergeable.
+ * Repair edit step: one clean-coder resolves the lingering bot review threads
+ * the convergence check flagged, fixes any still-applicable bot-thread concern
+ * test-first in the working tree, and rebases onto origin/main when the PR is
+ * not mergeable — making NO commit and NO push, so the verify step can bind a
+ * verdict to the resulting surface before the commit step pushes it. Human
+ * reviewer threads are never touched.
  * @param {string} head current PR HEAD SHA
  * @param {Array<string>} failures FAIL lines from the convergence check
- * @returns {Promise<object>} FIX_SCHEMA result
+ * @returns {Promise<object>} REPAIR_EDIT_SCHEMA result
  */
-function repairConvergence(head, failures) {
+function repairConvergenceEdit(head, failures) {
   const failureBlock = failures.length
     ? failures.map((each, position) => `${position + 1}. ${each}`).join('\n')
     : 'none reported'
   return convergeAgent(
-    `The convergence check for ${prCoordinates} failed these gates on HEAD ${head}:\n${failureBlock}\n\n` +
-      `Address only the failing gates:\n` +
-      `- Unresolved bot review threads: fetch the threads where isResolved is false (gh api graphql, or the github MCP pull_request_read get_review_comments), then keep only the bot-authored ones — a thread whose root comment author login contains "cursor", "claude", or "copilot" (case-insensitive substring). Explicitly skip every human reviewer thread; the convergence gate counts only unresolved bot threads, so touching a human thread is out of scope. For each bot thread, verify the concern against current code; if it still applies, fix it test-first; either way post an inline reply and resolve the thread.\n` +
-      `- PR not mergeable: rebase onto origin/main and force-push (git fetch origin main; git rebase origin/main; resolve conflicts; git push --force-with-lease).\n` +
-      `- A dirty bot review or a still-pending requested reviewer: leave it; the next round re-runs that reviewer.\n` +
-      `Make at most one commit for any code fix. Return the HEAD SHA after any push in newSha (the unchanged ${head} when nothing was pushed), pushed true/false, resolvedWithoutCommit=false (this gate already accepts an unchanged HEAD), and a one-line summary.`,
-    { label: 'repair-convergence', phase: 'Finalize', schema: FIX_SCHEMA, agentType: 'clean-coder' },
+    `You are the EDIT step repairing the convergence gates that failed for ${prCoordinates} on HEAD ${head}. A separate verify step then a separate commit step run after you.\n\n` +
+      `Failing gates:\n${failureBlock}\n\n` +
+      `Address only the failing gates, and make NO commit and NO push — leave every code change in the working tree (a rebase necessarily creates local commits, which is fine; just do not push them):\n` +
+      `- Unresolved bot review threads: fetch the threads where isResolved is false (gh api graphql, or the github MCP pull_request_read get_review_comments), then keep only the bot-authored ones — a thread whose root comment author login contains "cursor", "claude", or "copilot" (case-insensitive substring). Explicitly skip every human reviewer thread; the convergence gate counts only unresolved bot threads, so touching a human thread is out of scope. For each bot thread, verify the concern against current code; if it still applies, fix it test-first in the working tree and leave the fix uncommitted; either way post an inline reply and resolve the thread by its PRRT_ node id (GraphQL lookup matching the comment databaseId, then resolveReviewThread or the github MCP pull_request_review_write method=resolve_thread — not the numeric comment id).\n` +
+      `- PR not mergeable: rebase onto origin/main FIRST, before applying any uncommitted bot-thread fix, so the rebase runs on a clean tree (git fetch origin main; git rebase origin/main; resolve conflicts). Do NOT force-push — the commit step does that after verification.\n` +
+      `- A dirty bot review or a still-pending requested reviewer: leave it; the next round re-runs that reviewer.\n\n` +
+      `Return values:\n` +
+      `- edited=true when you changed code in the working tree to fix a bot-thread concern.\n` +
+      `- rebased=true when you rebased the branch onto origin/main.\n` +
+      `- resolvedWithoutCommit=true only when you addressed the gates with neither a code change nor a rebase (bot threads resolved only), so there is nothing for the commit step to push.\n` +
+      `Always include a one-line summary.`,
+    { label: 'repair-edit', phase: 'Finalize', schema: REPAIR_EDIT_SCHEMA, agentType: 'clean-coder' },
+  )
+}
+
+/**
+ * Repair verify step: a code-verifier confirms the working-tree repair (any
+ * bot-thread fix plus any rebase result) is sound, computes the binding surface
+ * hash, and ends with a verdict fence as plain assistant text (NO schema). The
+ * fence's manifest_sha256 unlocks the verified-commit gate for the commit step's
+ * push. The verifier makes no edits.
+ * @param {string} head PR HEAD SHA the repair started from
+ * @param {Array<string>} failures FAIL lines the repair addressed
+ * @returns {Promise<string>} the verifier transcript carrying the verdict fence
+ */
+function verifyRepairChanges(head, failures) {
+  const failureBlock = failures.length
+    ? failures.map((each, position) => `${position + 1}. ${each}`).join('\n')
+    : 'none reported'
+  return convergeAgent(
+    `You are the VERIFY step for the convergence repair on ${prCoordinates}, HEAD ${head}. The edit step left its repair in the working tree (a bot-thread fix uncommitted, and/or a rebase onto origin/main), unpushed. Do NO edits of any kind — verification only; any edit invalidates the verdict you are about to emit.\n\n` +
+      `Concerns the working-tree repair must resolve (the gates the convergence check flagged):\n${failureBlock}\n\n` +
+      `Steps:\n` +
+      `1. Resolve the worktree repo root: REPO=$(git rev-parse --show-toplevel).\n` +
+      `2. Verify the working tree against origin/main: any bot-thread code fix is correct test-first per CODE_RULES, and a rebase (if any) left a clean, conflict-free tree. Read the diff (git diff origin/main) and run the relevant tests and named gates.\n` +
+      `3. ${VERDICT_FENCE_STEPS}`,
+    { label: 'repair-verify', phase: 'Finalize', agentType: 'code-verifier' },
+  )
+}
+
+/**
+ * Repair commit step: one clean-coder commits any uncommitted bot-thread fix in
+ * a single commit and pushes to the PR branch (force-with-lease when the edit
+ * step rebased), making NO further file edits — any edit changes the surface and
+ * invalidates the verifier verdict that unlocks the commit gate.
+ * @param {string} head PR HEAD SHA before the repair push
+ * @param {boolean} wasRebased true when the edit step rebased the branch, so the push must be force-with-lease
+ * @returns {Promise<object>} FIX_SCHEMA result
+ */
+function commitRepairFixes(head, wasRebased) {
+  const pushInstruction = wasRebased
+    ? 'The edit step rebased the branch, so push with git push --force-with-lease.'
+    : 'Push to the PR branch with a plain git push.'
+  return convergeAgent(
+    `You are the COMMIT step for the convergence repair on ${prCoordinates}, HEAD ${head}. The edit step left its repair in the working tree and the verify step passed, so a verifier verdict already binds to this exact working tree.\n\n` +
+      `Rules:\n` +
+      `- Make NO further file edits of any kind. Any edit changes the surface and invalidates the verdict that unlocks the commit gate, so the push would be blocked. Do not run a formatter, do not re-fix anything — only commit and push what is already there.\n` +
+      `- Commit any uncommitted bot-thread fix in ONE commit (skip the commit when the working tree carries only already-committed rebase results). ${pushInstruction}\n\n` +
+      `Return values: newSha=the new HEAD SHA after your push, pushed=true, resolvedWithoutCommit=false, and a one-line summary. If the commit or push is blocked or fails, return newSha=${head}, pushed=false, resolvedWithoutCommit=false, and a summary naming the failure.`,
+    { label: 'repair-commit', phase: 'Finalize', schema: FIX_SCHEMA, agentType: 'clean-coder' },
   )
 }
 
+/**
+ * Address the gates a convergence check reported as failing, then hand control
+ * back to the converge phase: edit (clean-coder resolves bot threads, applies
+ * any fix and rebase in the working tree, no push) -> verify (code-verifier
+ * emits a verdict fence binding the working tree) -> commit (clean-coder, one
+ * commit + push, no edits). Splitting the edit from the push lets a workflow
+ * code-verifier produce the verdict the verified-commit gate requires for the
+ * bot-thread fix commit and the post-rebase force-push. When the edit resolved
+ * the gates with neither a code change nor a rebase, or the verify step fails,
+ * the commit step is skipped and the unchanged HEAD is returned.
+ * @param {string} head current PR HEAD SHA
+ * @param {Array<string>} failures FAIL lines from the convergence check
+ * @returns {Promise<object>} FIX_SCHEMA result
+ */
+async function repairConvergence(head, failures) {
+  const editResult = await repairConvergenceEdit(head, failures)
+  const hasPushWork = editResult?.edited === true || editResult?.rebased === true
+  if (!hasPushWork) {
+    return {
+      newSha: head,
+      pushed: false,
+      resolvedWithoutCommit: true,
+      summary: editResult?.summary || 'convergence gates resolved without a code change or rebase',
+    }
+  }
+  const verifyTranscript = await verifyRepairChanges(head, failures)
+  if (!verdictPassed(verifyTranscript)) {
+    return {
+      newSha: head,
+      pushed: false,
+      resolvedWithoutCommit: false,
+      summary: `repair verify step did not pass the working-tree repair on HEAD ${head} — not pushing`,
+    }
+  }
+  return commitRepairFixes(head, editResult?.rebased === true)
+}
+
 /**
  * Decide whether a review round surfaced ONLY code-standard violations — pure
  * CODE_RULES/style findings with no behavioral impact. Such a round passes for
@@ -699,34 +1015,164 @@ function isStandardsOnlyRound(findings) {
 }
 
 /**
- * Defer a standards-only round: one agent files a GitHub issue listing every
- * code-standard finding, opens a draft PR hardening the Claude environment
- * (hooks/rules) so those violation classes are blocked before code is written,
- * and replies to / resolves any GitHub threads the findings carry, noting the
- * deferral. This PR's branch is never touched.
+ * Standards-deferral edit step: one clean-coder files the follow-up fix issue,
+ * stages an environment-hardening hooks/rules change in the config repo's
+ * working tree WITHOUT committing, and resolves the PR's code-standard threads.
+ * Leaving the hardening edit uncommitted lets the verify step bind a verdict to
+ * it before the commit step opens the PR. The PR's own branch is never touched.
  * @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<string>} agent transcript (unused)
+ * @returns {Promise<object>} STANDARDS_EDIT_SCHEMA result
  */
-function spawnStandardsFollowUp(head, findings, sourceLabel) {
-  const findingsBlock = findings
-    .map((each, position) => {
-      const eachThreadIds = collectFindingThreadIds(each)
-      const threadNote = eachThreadIds.length
-        ? `\n   (GitHub review comment ids: ${eachThreadIds.join(', ')})`
-        : ''
-      return `${position + 1}. [${each.severity}] ${each.file}:${each.line} — ${each.title}\n   ${each.detail}${threadNote}`
-    })
-    .join('\n')
+function standardsFollowUpEdit(head, findings, sourceLabel) {
+  const findingsBlock = renderFindingsBlock(findings)
+  const threadIds = findings
+    .flatMap((each) => collectFindingThreadIds(each))
+    .filter((each) => typeof each === 'number')
   return convergeAgent(
-    `A review round on ${prCoordinates}, HEAD ${head}, surfaced ONLY code-standard violations (CODE_RULES/style, no behavioral impact). The convergence run treats the round as passed and defers these to follow-up work, which you now create. Do NOT commit or push to the PR's own branch.\n\n` +
+    `You are the EDIT step deferring a code-standard-only round on ${prCoordinates}, HEAD ${head} (${sourceLabel}). The round surfaced ONLY code-standard violations (CODE_RULES/style, no behavioral impact); the run treats it as passed and defers the fixes to follow-up work, which you now stage. A separate verify step then a separate commit step open the hardening PR after you. Do NOT commit or push to the PR's own branch.\n\n` +
       `Findings:\n${findingsBlock}\n\n` +
-      `1. Follow-up fix issue: file a GitHub issue on ${input.owner}/${input.repo} (gh issue create --body-file with a temp file) titled "Deferred code-standard fixes from PR #${input.prNumber}". The body references the PR and lists each finding with its file:line, severity, and detail. The issue carries the fix work; do not open a fix PR.\n` +
-      `2. Environment-hardening PR: in the Claude environment config repo (the repo owning ~/.claude hooks and rules — JonEcho/llm-settings for hooks, jl-cmd/claude-code-config for rules/skills; pick whichever owns the needed surface), create a branch and open a DRAFT PR that hardens hooks/rules so each violation class found here is blocked at Write/Edit time, before code is written or reviewed. Reference the issue from step 1 in the PR body.\n` +
-      `3. For each finding that carries a GitHub review comment id: post an inline reply via python "${CONFIG.sharedScripts}/post_fix_reply.py" --owner ${input.owner} --repo ${input.repo} --pr-number ${input.prNumber} --in-reply-to <id> --body "Code-standard-only finding — deferred to follow-up issue <url>." Then resolve the thread by its PRRT_ node id (GraphQL lookup on comment databaseId, then resolveReviewThread or the github MCP pull_request_review_write method=resolve_thread).\n\n` +
-      `Return a one-line summary naming the follow-up issue URL and the hardening PR URL.`,
-    { label: `standards-followup:${sourceLabel}`, phase: 'Converge', agentType: 'clean-coder' },
+      `1. Follow-up fix issue: file a GitHub issue on ${input.owner}/${input.repo} (gh issue create --body-file with a temp file) titled "Deferred code-standard fixes from PR #${input.prNumber}". The body references the PR and lists each finding with its file:line, severity, and detail. The issue carries the fix work; do not open a fix PR. Capture the issue URL.\n` +
+      `2. Stage the environment-hardening change: in the Claude environment config repo (the repo owning ~/.claude hooks and rules — JonEcho/llm-settings for hooks, jl-cmd/claude-code-config for rules/skills; pick whichever owns the surface that would block these violation classes), find or clone a local checkout, fetch origin, and create a branch off origin/main. Edit the hooks/rules in that checkout's WORKING TREE so each violation class found here is blocked at Write/Edit time, before code is written. Do NOT commit and do NOT push — the commit step does that after the verify step binds a verdict to the working tree. Return the checkout's absolute path in hardeningRepoPath, the branch name in hardeningBranch, and set hardeningEdited=true. When no hardening is feasible for these classes, leave hardeningRepoPath and hardeningBranch empty and hardeningEdited=false; the follow-up issue still stands.\n` +
+      `3. For each finding that carries a GitHub review comment id (${threadIds.length ? threadIds.join(', ') : 'none this batch'}): post an inline reply via python "${CONFIG.sharedScripts}/post_fix_reply.py" --owner ${input.owner} --repo ${input.repo} --pr-number ${input.prNumber} --in-reply-to <id> --body "Code-standard-only finding — deferred to follow-up issue <url>." Then resolve the thread by its PRRT_ node id (GraphQL lookup on comment databaseId, then resolveReviewThread or the github MCP pull_request_review_write method=resolve_thread — not the numeric comment id).\n\n` +
+      `Return the issue URL in issueUrl (empty string when it could not be filed), the hardening checkout path and branch, hardeningEdited, and a one-line summary.`,
+    { label: `standards-edit:${sourceLabel}`, phase: 'Converge', schema: STANDARDS_EDIT_SCHEMA, agentType: 'clean-coder' },
+  )
+}
+
+/**
+ * Standards-hardening verify step: a code-verifier confirms the uncommitted
+ * hooks/rules change staged in the hardening repo blocks the deferred violation
+ * classes, computes the binding surface hash for that repo, and ends with a
+ * verdict fence as plain assistant text (NO schema) — unlocking the
+ * verified-commit gate for the cross-repo hardening commit. The verifier makes
+ * no edits.
+ * @param {string} hardeningRepoPath absolute path of the hardening repo checkout the edit staged
+ * @param {string} sourceLabel short description of where the findings came from
+ * @returns {Promise<string>} the verifier transcript carrying the verdict fence
+ */
+function verifyHardeningChanges(hardeningRepoPath, sourceLabel) {
+  return convergeAgent(
+    `You are the VERIFY step for an environment-hardening change (${sourceLabel}) staged in the working tree of ${hardeningRepoPath}. The edit step left the hooks/rules edits uncommitted there. Do NO edits of any kind — verification only; any edit invalidates the verdict you are about to emit.\n\n` +
+      `Concern the working-tree change must resolve: the edited hooks/rules block the code-standard violation classes from the deferred round at Write/Edit time, and a hook change carries a passing test per CODE_RULES.\n\n` +
+      `Steps:\n` +
+      `1. cd into ${hardeningRepoPath}, then resolve its repo root: REPO=$(git rev-parse --show-toplevel).\n` +
+      `2. Verify the uncommitted working-tree change in REPO: read the diff (git diff) and run the hook/rule tests in that repo, confirming each violation class is now blocked.\n` +
+      `3. ${VERDICT_FENCE_STEPS}`,
+    { label: `standards-verify:${sourceLabel}`, phase: 'Converge', agentType: 'code-verifier' },
+  )
+}
+
+/**
+ * Standards-hardening commit step: one clean-coder commits the verified
+ * working-tree hooks/rules change in a single commit, pushes the hardening
+ * branch, and opens the DRAFT hardening PR — making NO further file edits, since
+ * any edit changes the surface and invalidates the verdict that unlocks the
+ * commit gate. The PR's own branch is never touched.
+ * @param {string} hardeningRepoPath absolute path of the hardening repo checkout
+ * @param {string} hardeningBranch the hardening branch the edit step created
+ * @param {string} issueUrl the follow-up fix issue URL the PR body references
+ * @param {string} sourceLabel short description of where the findings came from
+ * @returns {Promise<string>} agent transcript (unused)
+ */
+function commitHardeningPr(hardeningRepoPath, hardeningBranch, issueUrl, sourceLabel) {
+  return convergeAgent(
+    `You are the COMMIT step opening the environment-hardening PR (${sourceLabel}) for the change staged in ${hardeningRepoPath} on branch ${hardeningBranch}. The edit step left the hooks/rules edits in the working tree and the verify step passed, so a verifier verdict already binds to this exact working tree. Do NOT touch the PR's own branch.\n\n` +
+      `Rules:\n` +
+      `- Make NO further file edits of any kind. Any edit changes the surface and invalidates the verdict that unlocks the commit gate, so the push would be blocked. Only commit and push what is already there.\n` +
+      `- In ${hardeningRepoPath}: make ONE commit of the staged hooks/rules change on branch ${hardeningBranch}, push it, then open a DRAFT PR. The PR body references the follow-up issue ${issueUrl || '(none)'} and states the PR hardens the environment so the deferred violation classes are blocked at Write/Edit time. Honor the gh-body-file rule: write a BOM-free temp file and pass --body-file.\n\n` +
+      `Return a one-line summary naming the hardening PR URL.`,
+    { label: `standards-commit:${sourceLabel}`, phase: 'Converge', agentType: 'clean-coder' },
+  )
+}
+
+/**
+ * Build the standards-deferral note for the closing report, naming the
+ * environment-hardening PR only when one was opened this round so the note
+ * never claims a PR the skip paths did not produce.
+ * @param {number} findingsCount count of deferred code-standard findings
+ * @param {boolean} hardeningPrOpened true when the hardening PR was opened this round
+ * @returns {string} the human-facing deferral note
+ */
+function standardsDeferralNote(findingsCount, hardeningPrOpened) {
+  const base = `${findingsCount} code-standard finding(s) deferred to a follow-up fix issue`
+  return hardeningPrOpened
+    ? `${base} plus an environment-hardening PR — verify both land`
+    : `${base} — verify it lands (no environment-hardening PR was opened this round)`
+}
+
+/**
+ * Defer a standards-only round: edit (clean-coder files the follow-up fix issue,
+ * stages an environment-hardening hooks/rules change in the config repo's
+ * working tree without committing, and resolves the PR's code-standard threads)
+ * -> verify (code-verifier binds a verdict to the hardening working tree) ->
+ * commit (clean-coder makes one commit, pushes, and opens the DRAFT hardening
+ * PR). Splitting the edit from the push lets a workflow code-verifier produce the
+ * verdict the verified-commit gate requires for the cross-repo hardening commit.
+ * This PR's own branch is never touched. When the edit staged no hardening, or
+ * the verify step fails, the follow-up issue still stands and the commit step is
+ * skipped.
+ * @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 }` — true only when the hardening PR was opened this round
+ */
+async function spawnStandardsFollowUp(head, findings, sourceLabel) {
+  const editResult = await standardsFollowUpEdit(head, findings, sourceLabel)
+  if (editResult?.hardeningEdited !== true || !editResult?.hardeningRepoPath) {
+    return { hardeningPrOpened: false }
+  }
+  const verifyTranscript = await verifyHardeningChanges(editResult.hardeningRepoPath, sourceLabel)
+  if (!verdictPassed(verifyTranscript)) {
+    return { hardeningPrOpened: false }
+  }
+  await commitHardeningPr(editResult.hardeningRepoPath, editResult.hardeningBranch, editResult.issueUrl, sourceLabel)
+  return { hardeningPrOpened: true }
+}
+
+/**
+ * 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' },
   )
 }
 
@@ -739,6 +1185,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 +1213,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`)
-      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)
+      allRoundFindings.push(...findings)
+      const standardsOutcome = await spawnStandardsFollowUp(head, findings, 'converge-round')
+      standardsNote = standardsDeferralNote(findings.length, standardsOutcome?.hardeningPrOpened === true)
+      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 +1244,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,15 +1272,18 @@ 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`)
-        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`
+        allRoundFindings.push(...copilotOutcome.findings)
+        const standardsOutcome = await spawnStandardsFollowUp(head, copilotOutcome.findings, 'copilot')
+        standardsNote = standardsDeferralNote(copilotOutcome.findings.length, standardsOutcome?.hardeningPrOpened === true)
         copilotDown = false
         copilotNote = null
         phase = 'FINALIZE'
         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 +1312,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