claude-dev-env 1.71.0 → 1.73.0

package/skills/autoconverge/workflow/converge.mjs

@@ -14,6 +14,7 @@ export const meta = {
   description: 'Drive one draft PR to convergence in a single autonomous run: parallel Bugbot + code-review + bug-audit lenses on the same HEAD each round, dedup findings, fix once, re-verify, then a Copilot wait-gate and a final convergence check that marks the PR ready.',
   whenToUse: 'Launched by the /autoconverge skill after it resolves PR scope, enters a worktree, and grants project .claude permissions.',
   phases: [
+    { title: 'Reuse', detail: 'Before convergence, one reuse lens scans the full diff for reuse improvements that are certain, behaviorally identical, and autonomously implementable, and applies the qualifying ones in one commit' },
     { title: 'Converge', detail: 'Bugbot + code-review + bug-audit in parallel each round; one clean-coder applies all fixes; loop until all three are clean on a stable HEAD' },
     { title: 'Copilot gate', detail: 'Request Copilot review and poll up to three times; route findings back into Converge; when Copilot is down or out of quota, log a notice and mark the PR ready with the gate bypassed' },
     { title: 'Finalize', detail: 'Run check_convergence.py; mark draft=false on a full pass' },
@@ -35,16 +36,45 @@ const HEADLESS_SAFETY_PREAMBLE =
   '- Keep scratch files and cleanup inside the OS temp dir or $CLAUDE_JOB_DIR/tmp (auto-allowed as ephemeral); never target a repository or worktree path with rm -rf.\n' +
   '- If a step appears to require a real destructive command, use a non-destructive equivalent or report it as a blocker instead of running it.\n\n'
 
+let activeRepoPath = null
+
+/**
+ * Build the per-agent worktree directive for a path-scoped run.
+ *
+ * A multi-PR parent run drives several converge children from one shared
+ * working directory, so each child pins its own agents to the worktree its PR
+ * is checked out in; without that pin every child's git, gh, diff, edit,
+ * commit, and test commands would run in the shared launch directory rather
+ * than the PR's own checkout. The parent hands the worktree path in as
+ * input.repoPath, which sets activeRepoPath. A single-PR run carries no
+ * repoPath, so this returns an empty string and every agent keeps its own
+ * working directory — behavior identical to a run with no path scoping.
+ * @param {string|null} repoPath the PR worktree absolute path, or null for the single-PR default
+ * @returns {string} the worktree directive to prepend, or an empty string when repoPath is null
+ */
+const worktreeDirective = (repoPath) =>
+  repoPath
+    ? `WORKTREE — this PR is checked out at ${repoPath}. Unless a step explicitly names a different repository directory (for example an environment-hardening repo checkout, which you cd into exactly as that step directs), run every git, gh, diff, edit, commit, push, and test command for this PR in that worktree: cd "${repoPath}" before any such command, and resolve repository roots from there.\n\n`
+    : ''
+
 /**
  * Spawn a workflow agent with the headless-safety preamble prepended to its
  * prompt. Every agent in this convergence loop runs unattended, so each one is
- * routed through here to inherit the same no-confirmation-prompt guidance.
+ * routed through here to inherit the same no-confirmation-prompt guidance. On a
+ * path-scoped run the worktree directive is prepended too, so every agent runs
+ * in the PR's own worktree (activeRepoPath); on a single-PR run that directive
+ * is empty and the agent keeps its own working directory.
  * @param {string} prompt the agent's role-specific instruction body
  * @param {object} options the agent() options (label, phase, schema, agentType, model)
  * @returns {Promise<*>} the agent() result
  */
 const convergeAgent = (prompt, options) =>
-  agent(`${HEADLESS_SAFETY_PREAMBLE}${prompt}`, options)
+  agent(`${HEADLESS_SAFETY_PREAMBLE}${worktreeDirective(activeRepoPath)}${prompt}`, options)
+
+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` +
+  `Exit 0 means the commit gate would accept the commit. On any non-zero exit, read every violation it prints, fix each one test-first per CODE_RULES, and re-run the gate until it exits 0. Then unstage with git restore --staged . so the verify step reads the working-tree diff. Make NO git commit and NO git push here — this is a dry committability check; the separate verify and commit steps run after you, and the verified-commit gate is their job, not yours. Your turn does not end while the commit gate would reject the commit.`
 
 const LENS_SCHEMA = {
   type: 'object',
@@ -130,6 +160,28 @@ 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,
+  properties: {
+    rebased: { type: 'boolean', description: 'true when the branch was rebased onto origin/main and every conflict resolved in the working tree' },
+    summary: { type: 'string' },
+  },
+  required: ['rebased', 'summary'],
+}
+
 const STANDARDS_EDIT_SCHEMA = {
   type: 'object',
   additionalProperties: false,
@@ -529,6 +581,19 @@ function isResolvedHeadUsable(resolvedHead) {
   return typeof resolvedHead === 'string' && resolvedHead.length > 0
 }
 
+/**
+ * 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
+ * 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
+ * failure must never trigger a destructive rebase.
+ * @param {object|null|undefined} mergeState the checkMergeConflicts result
+ * @returns {boolean} true only when the check reported conflicting:true
+ */
+function isMergeConflicting(mergeState) {
+  return mergeState != null && mergeState.conflicting === true
+}
+
 /**
  * Decide whether the mark-ready step actually cleared the draft state. The run
  * reports converged only when the mark-ready agent confirms ready:true; a dead
@@ -655,6 +720,7 @@ if (runInput.blocker) {
   return { converged: false, rounds: 0, finalSha: null, blocker: runInput.blocker }
 }
 const input = runInput.input
+activeRepoPath = typeof input.repoPath === 'string' && input.repoPath ? input.repoPath : null
 const prCoordinates = `owner=${input.owner} repo=${input.repo} PR #${input.prNumber} (https://github.com/${input.owner}/${input.repo}/pull/${input.prNumber})`
 
 /**
@@ -749,6 +815,29 @@ function runAuditLens(head) {
   )
 }
 
+/**
+ * Reuse lens: a one-time pre-convergence pass that scans the full diff for
+ * places the PR re-implements behavior the codebase already provides, and
+ * returns only the reuse improvements that are certain, behaviorally identical,
+ * and autonomously implementable. It reports findings without editing; the
+ * reuse pass routes the qualifying findings through applyFixes so they are
+ * implemented in one commit before the convergence rounds begin.
+ * @param {string} head PR HEAD SHA to evaluate
+ * @returns {Promise<object>} LENS_SCHEMA result carrying the qualifying reuse findings
+ */
+function runReuseAuditPass(head) {
+  return convergeAgent(
+    `You are the REUSE lens for ${prCoordinates}, HEAD ${head}. This pass runs once before convergence to find where the PR re-implements behavior the codebase already provides.\n\n` +
+      `Review the FULL origin/main...HEAD diff — every file the PR touches. Do NOT delta-scope to recent commits or a single file. The workflow already fetched origin/main, so do NOT run git fetch; run git diff --name-only origin/main...HEAD to enumerate the changed files, then read the complete diff of each. For every new function, helper, constant, type, or block of logic the PR introduces, search the repository (Serena symbol search, grep, and the project's config/ and shared/ modules) for an existing equivalent that already provides the same behavior.\n\n` +
+      `Report a reuse finding ONLY when ALL THREE criteria hold — when any one is in doubt, omit the finding:\n` +
+      `  A. CERTAIN: an existing symbol or module unquestionably covers the new code's behavior, and you can cite it at file:line.\n` +
+      `  B. BEHAVIORALLY IDENTICAL: replacing the new code with the existing one changes no observable behavior — same inputs, outputs, side effects, and error handling.\n` +
+      `  C. AUTONOMOUSLY IMPLEMENTABLE: the replacement is a mechanical edit (import and call the existing symbol, delete the duplicate) that needs no product decision, no API the existing code lacks, and no human judgment.\n\n` +
+      `Do NOT edit, commit, or push — report only; a separate fix step applies what you return. Return strictly the schema: clean=true with empty findings when no reuse case clears all three criteria, otherwise one entry per qualifying reuse improvement. For each: file and line of the duplicate in the PR; severity P2; category 'code-standard'; title naming the existing symbol to reuse; detail giving the existing symbol's file:line and the exact mechanical replacement; replyToCommentId=null. Set sha=${'`'}${head}${'`'}, down=false.`,
+    { label: 'lens:reuse', phase: 'Reuse', schema: LENS_SCHEMA, agentType: 'code-quality-agent' },
+  )
+}
+
 /**
  * Render the numbered findings block shared by the fix steps.
  * @param {Array<object>} findings deduped findings to render
@@ -792,7 +881,8 @@ function applyFixesEdit(head, findings, sourceLabel) {
       `Return values:\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.`,
+      `Always include a one-line summary.` +
+      PRE_COMMIT_GATE_STEP,
     { label: `fix-edit:${sourceLabel}`, phase: 'Converge', schema: EDIT_SCHEMA, agentType: 'clean-coder' },
   )
 }
@@ -865,7 +955,8 @@ function recoverCommitBlockEdit(head, blockerDetail, sourceLabel, attempt) {
       `- Confirm the working tree is on the PR branch at HEAD ${head} with the prior fixes still present.\n` +
       `- Fix ONLY the violation named above, test-first (failing test, then minimum code to pass) per CODE_RULES. Do not re-open the original findings, and do not touch GitHub review threads — the edit step already handled those.\n` +
       `- Leave the corrected fixes in the working tree. Do NOT commit and do NOT push — the verify step re-binds a verdict and the commit step pushes after you.\n\n` +
-      `Return values: edited=true with a one-line summary when you changed code to clear the block; edited=false, resolvedWithoutCommit=false when the block cannot be cleared with a code change.`,
+      `Return values: edited=true with a one-line summary when you changed code to clear the block; edited=false, resolvedWithoutCommit=false when the block cannot be cleared with a code change.` +
+      PRE_COMMIT_GATE_STEP,
     { label: `fix-recover:${sourceLabel}`, phase: 'Converge', schema: EDIT_SCHEMA, agentType: 'clean-coder' },
   )
 }
@@ -891,7 +982,8 @@ function recoverVerifyFailEdit(head, objection, sourceLabel, attempt) {
       `- Confirm the working tree is on the PR branch at HEAD ${head} with the prior fixes still present.\n` +
       `- Address every objection above test-first (failing test, then minimum code to pass) per CODE_RULES, so each named concern is genuinely resolved the way the verdict requires. Do not touch GitHub review threads — the edit step already handled those.\n` +
       `- Leave the corrected fixes in the working tree. Do NOT commit and do NOT push — the verify step re-binds a verdict and the commit step pushes after you.\n\n` +
-      `Return values: edited=true with a one-line summary when you changed code to address the objections; edited=false, resolvedWithoutCommit=false when the objections cannot be cleared with a code change.`,
+      `Return values: edited=true with a one-line summary when you changed code to address the objections; edited=false, resolvedWithoutCommit=false when the objections cannot be cleared with a code change.` +
+      PRE_COMMIT_GATE_STEP,
     { label: `fix-verify-recover:${sourceLabel}`, phase: 'Converge', schema: EDIT_SCHEMA, agentType: 'clean-coder' },
   )
 }
@@ -1130,7 +1222,8 @@ function repairConvergenceEdit(head, failures) {
       `- 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.`,
+      `Always include a one-line summary.` +
+      PRE_COMMIT_GATE_STEP,
     { label: 'repair-edit', phase: 'Finalize', schema: REPAIR_EDIT_SCHEMA, agentType: 'clean-coder' },
   )
 }
@@ -1235,6 +1328,79 @@ async function repairConvergence(head, failures) {
   })
 }
 
+/**
+ * Pre-flight merge-conflict check: ask GitHub whether the PR branch still merges
+ * cleanly into its base. GitHub computes mergeability asynchronously, so the
+ * agent polls until .mergeable resolves to a boolean before judging. Read-only —
+ * it makes no edit, commit, push, or rebase.
+ * @param {string} head PR HEAD SHA the check runs against
+ * @returns {Promise<object>} MERGE_CONFLICT_SCHEMA result
+ */
+function checkMergeConflicts(head) {
+  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` +
+      `   gh api repos/${input.owner}/${input.repo}/pulls/${input.prNumber} --jq '{mergeable: .mergeable, state: .mergeable_state}'\n` +
+      `up to 5 times, 5 seconds apart (delay each retry with "sleep 5", or the PowerShell alternative "Start-Sleep -Seconds 5"), stopping as soon as mergeable is true or false.\n\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: 'check-merge-conflicts', phase: 'Converge', schema: MERGE_CONFLICT_SCHEMA, agentType: 'Explore' },
+  )
+}
+
+/**
+ * Conflict-resolution edit step: one clean-coder rebases the PR branch onto
+ * origin/main and resolves every conflict in the working tree, making NO push —
+ * the verify step binds a verdict to the rebased tree before the commit step
+ * force-pushes it. A rebase necessarily creates local commits, which is expected;
+ * only the force-push is withheld so the verifier binds the surface first.
+ * @param {string} head PR HEAD SHA before the rebase
+ * @returns {Promise<object>} CONFLICT_EDIT_SCHEMA result
+ */
+function resolveConflictsEdit(head) {
+  return convergeAgent(
+    `You are the EDIT step resolving merge conflicts for ${prCoordinates}, HEAD ${head}, before the bug checks run. The PR branch conflicts with origin/main. A separate verify step then a separate commit step run after you.\n\n` +
+      `Rules:\n` +
+      `- Confirm the working tree is on the PR branch at HEAD ${head} with no unrelated edits before you start.\n` +
+      `- Rebase the branch onto origin/main and resolve every conflict so the tree is clean and conflict-free: git fetch origin main; git rebase origin/main; resolve each conflict, preserving the intent of both the PR's change and the incoming base change. A rebase creates local commits, which is fine.\n` +
+      `- Do NOT push and do NOT force-push — the commit step force-pushes after the verify step binds a verdict. Pushing here would change the surface the verifier binds to.\n\n` +
+      `Return rebased=true with a one-line summary when you rebased onto origin/main and resolved the conflicts; rebased=false with a summary when the branch did not actually need a rebase or you could not complete it.`,
+    { label: 'resolve-conflicts-edit', phase: 'Converge', schema: CONFLICT_EDIT_SCHEMA, agentType: 'clean-coder' },
+  )
+}
+
+/**
+ * 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.
+ * @param {string} head PR HEAD SHA before any rebase
+ * @returns {Promise<string>} the HEAD SHA after a successful rebase push, or the unchanged head
+ */
+async function resolveMergeConflicts(head) {
+  const mergeState = await checkMergeConflicts(head)
+  if (!isMergeConflicting(mergeState)) return head
+  log(`Pre-flight: ${prCoordinates} conflicts with origin/main — rebasing clean before the bug checks`)
+  const editResult = await resolveConflictsEdit(head)
+  if (editResult?.rebased !== true) return head
+  const failures = ['PR branch had merge conflicts with origin/main; the rebase must leave a clean, conflict-free tree']
+  const verifyTranscript = await verifyWithRecovery({
+    runVerify: () => verifyRepairChanges(head, failures),
+    runRecoverEdit: (objection, attempt) => recoverVerifyFailEdit(head, objection, 'conflict-rebase', attempt),
+  })
+  if (!verdictPassed(verifyTranscript)) return head
+  const commitResult = await commitWithRecovery({
+    runCommit: () => commitRepairFixes(head, true),
+    runVerify: () => verifyRepairChanges(head, failures),
+    runRecoverEdit: (detail, attempt) => recoverCommitBlockEdit(head, detail, 'conflict-rebase', attempt),
+  })
+  return commitResult?.newSha || head
+}
+
 /**
  * Decide whether a review round surfaced ONLY code-standard violations — pure
  * CODE_RULES/style findings with no behavioral impact. Such a round passes for
@@ -1269,7 +1435,8 @@ function standardsFollowUpEdit(head, findings, sourceLabel) {
       `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.`,
+      `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.` +
+      PRE_COMMIT_GATE_STEP,
     { label: `standards-edit:${sourceLabel}`, phase: 'Converge', schema: STANDARDS_EDIT_SCHEMA, agentType: 'clean-coder' },
   )
 }
@@ -1428,9 +1595,36 @@ let bugbotDown = input.bugbotDisabled || false
 let copilotDown = false
 let copilotNote = null
 let standardsNote = null
+let reuseNote = null
 const allRoundFindings = []
 const fixSummaries = []
 
+const preflightHead = await resolveHead()
+if (isResolvedHeadUsable(preflightHead)) {
+  await resolveMergeConflicts(preflightHead)
+}
+
+log('Reuse pass: scanning the full diff for certain, behaviorally identical, autonomously implementable reuse improvements before convergence')
+const reuseHead = await resolveHead()
+if (isResolvedHeadUsable(reuseHead)) {
+  await prefetchMainForRound()
+  const reuse = await runReuseAuditPass(reuseHead)
+  const reuseFindings = reuse?.findings || []
+  if (reuseFindings.length > 0) {
+    log(`Reuse pass: ${reuseFindings.length} qualifying reuse improvement(s) — applying before convergence`)
+    allRoundFindings.push(...reuseFindings)
+    const reuseFix = await applyFixes(reuseHead, reuseFindings, 'reuse-pass')
+    if (reuseFix?.summary) fixSummaries.push(reuseFix.summary)
+    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`
+  } else {
+    log('Reuse pass: no reuse case cleared all three criteria — proceeding to convergence')
+  }
+} else {
+  log('Reuse pass: could not resolve HEAD — proceeding to convergence')
+}
+
 while (iterations < CONFIG.maxIterations) {
   iterations += 1
   if (phase === 'CONVERGE') {
@@ -1556,7 +1750,7 @@ while (iterations < CONFIG.maxIterations) {
       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 }
+        return { converged: true, rounds, finalSha: head, blocker: null, standardsNote, copilotNote, reuseNote }
       }
       blocker = readyOutcome.blocker
       break
@@ -1575,4 +1769,5 @@ return {
   blocker: blocker || `iteration cap reached (${CONFIG.maxIterations})`,
   standardsNote,
   copilotNote,
+  reuseNote,
 }

package/skills/autoconverge/workflow/converge.path-aware.test.mjs

@@ -0,0 +1,47 @@
+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');
+
+function sliceBetween(startNeedle, endNeedle) {
+  const sliceStart = convergeSource.indexOf(startNeedle);
+  assert.notEqual(sliceStart, -1, `expected ${startNeedle} to exist`);
+  const sliceEnd = convergeSource.indexOf(endNeedle, sliceStart + startNeedle.length);
+  assert.notEqual(sliceEnd, -1, `expected ${endNeedle} to exist after ${startNeedle}`);
+  return convergeSource.slice(sliceStart, sliceEnd);
+}
+
+const productionModule = new Function(
+  `${sliceBetween('const worktreeDirective =', '\nconst convergeAgent =')}\n` +
+    'return { worktreeDirective };',
+)();
+const { worktreeDirective } = productionModule;
+
+test('a single-PR run (no repoPath) produces an empty worktree directive', () => {
+  assert.equal(worktreeDirective(null), '');
+});
+
+test('a path-scoped run pins every agent to the PR worktree by absolute path', () => {
+  const directive = worktreeDirective('/worktrees/pr-398');
+  assert.match(directive, /\/worktrees\/pr-398/);
+  assert.match(directive, /cd /);
+  assert.match(directive, /git, gh, diff, edit, commit, push, and test/);
+});
+
+test('a path-scoped run defers to a step that names a different repository directory', () => {
+  assert.match(worktreeDirective('/worktrees/pr-398'), /different repository directory/i);
+});
+
+test('convergeAgent prepends the worktree directive for the active repo path', () => {
+  const agentDefinition = sliceBetween('const convergeAgent =', '\nconst PRE_COMMIT_GATE_STEP');
+  assert.match(agentDefinition, /worktreeDirective\(activeRepoPath\)/);
+  assert.match(agentDefinition, /HEADLESS_SAFETY_PREAMBLE/);
+});
+
+test('the run binds activeRepoPath from input.repoPath after the input is parsed', () => {
+  assert.match(convergeSource, /activeRepoPath = typeof input\.repoPath === 'string'/);
+});

package/skills/autoconverge/workflow/converge_multi.mjs

@@ -0,0 +1,161 @@
+/**
+ * Autoconverge multi-PR fan-out workflow driver.
+ *
+ * SINGLE-FILE CONTRACT — keep this file self-contained. The Workflow runtime
+ * wraps this body in a function (so top-level await and return work) and rejects
+ * static import statements, and `export const meta` must be the first statement.
+ * This driver fans out one converge.mjs child run per PR with parallel(); the
+ * converge.mjs child uses only agent()/parallel() (never workflow()), so the
+ * one-level workflow() nesting limit holds.
+ */
+
+export const meta = {
+  name: 'autoconverge-multi',
+  description: 'Drive several draft PRs to convergence in one run: fan out one autoconverge converge.mjs child per PR in parallel, each pinned to its own checked-out worktree via repoPath, then report every PR\'s outcome together.',
+  whenToUse: 'Launched by the /autoconverge skill when the user names more than one PR to converge at once; the single-PR path launches workflow/converge.mjs directly.',
+  phases: [
+    { title: 'Converge all', detail: 'One converge.mjs child run per PR, all in parallel; each child is pinned to its own PR worktree through repoPath' },
+  ],
+}
+
+/**
+ * Normalize the workflow args global into a parsed object.
+ *
+ * The Workflow runtime may deliver args as a JSON-encoded string or as an
+ * object; a string is parsed and an object passes through unchanged. A non-JSON
+ * or empty string yields null so a malformed payload becomes a structured
+ * blocker rather than aborting the run.
+ * @param {string|object} rawArgs the workflow args global (JSON string or object)
+ * @returns {object|null} the parsed args, or null when a string payload fails to parse
+ */
+function normalizeMultiInput(rawArgs) {
+  if (typeof rawArgs !== 'string') return rawArgs
+  try {
+    return JSON.parse(rawArgs)
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Decide whether one PR entry carries every coordinate a child run needs.
+ *
+ * A child converge run needs the PR's owner, repo, and number to address its
+ * GitHub calls, and the absolute worktree path the PR is checked out in to pin
+ * its agents there.
+ * @param {object} prEntry one element of the args.prs array
+ * @returns {boolean} true when owner, repo, prNumber, and a non-empty string repoPath are all present
+ */
+function isUsablePrEntry(prEntry) {
+  return (
+    prEntry != null &&
+    Boolean(prEntry.owner) &&
+    Boolean(prEntry.repo) &&
+    Boolean(prEntry.prNumber) &&
+    typeof prEntry.repoPath === 'string' &&
+    Boolean(prEntry.repoPath)
+  )
+}
+
+/**
+ * Validate the normalized multi-PR input into usable coordinates or a blocker.
+ *
+ * A fan-out run needs the absolute converge.mjs script path and a non-empty list
+ * of PR entries that each carry owner, repo, prNumber, and the absolute worktree
+ * path the PR is checked out in. A payload that fails to parse, a non-string
+ * convergeScriptPath, a missing or empty prs list, or any entry missing a
+ * coordinate yields a blocker the top-level run reports as
+ * {converged:false, blocker} rather than throwing on a missing field.
+ * @param {string|object} rawArgs the workflow args global (JSON string or object)
+ * @returns {{input: object|null, blocker: string|null}} usable coordinates or a blocker
+ */
+function classifyMultiInput(rawArgs) {
+  const candidate = normalizeMultiInput(rawArgs)
+  if (candidate == null) {
+    return {
+      input: null,
+      blocker: 'invalid run coordinates: the workflow args did not parse into an object',
+    }
+  }
+  if (typeof candidate.convergeScriptPath !== 'string' || !candidate.convergeScriptPath) {
+    return {
+      input: null,
+      blocker:
+        'invalid run coordinates: convergeScriptPath (absolute path to converge.mjs) is required',
+    }
+  }
+  if (!Array.isArray(candidate.prs) || candidate.prs.length === 0) {
+    return {
+      input: null,
+      blocker: 'invalid run coordinates: prs must be a non-empty array of PR entries',
+    }
+  }
+  const unusableEntryCount = candidate.prs.filter(
+    (eachEntry) => !isUsablePrEntry(eachEntry),
+  ).length
+  if (unusableEntryCount > 0) {
+    return {
+      input: null,
+      blocker: `invalid run coordinates: ${unusableEntryCount} PR entry/entries missing owner, repo, prNumber, or repoPath`,
+    }
+  }
+  return { input: candidate, blocker: null }
+}
+
+const multiInput = classifyMultiInput(args)
+if (multiInput.blocker) {
+  return { converged: false, prCount: 0, convergedCount: 0, results: [], blocker: multiInput.blocker }
+}
+const input = multiInput.input
+
+phase('Converge all')
+log(`autoconverge multi-PR: driving ${input.prs.length} PR(s) to ready in parallel`)
+
+const childResults = await parallel(
+  input.prs.map((eachPr) => async () => {
+    const childOutcome = await workflow(
+      { scriptPath: input.convergeScriptPath },
+      {
+        owner: eachPr.owner,
+        repo: eachPr.repo,
+        prNumber: eachPr.prNumber,
+        repoPath: eachPr.repoPath,
+        bugbotDisabled: Boolean(eachPr.bugbotDisabled),
+      },
+    )
+    return {
+      owner: eachPr.owner,
+      repo: eachPr.repo,
+      prNumber: eachPr.prNumber,
+      converged: Boolean(childOutcome && childOutcome.converged),
+      rounds: childOutcome && childOutcome.rounds !== undefined ? childOutcome.rounds : null,
+      finalSha: childOutcome && childOutcome.finalSha !== undefined ? childOutcome.finalSha : null,
+      blocker: childOutcome && childOutcome.blocker !== undefined ? childOutcome.blocker : null,
+    }
+  }),
+)
+
+const results = childResults.map((eachResult, eachIndex) =>
+  eachResult === null
+    ? {
+        owner: input.prs[eachIndex].owner,
+        repo: input.prs[eachIndex].repo,
+        prNumber: input.prs[eachIndex].prNumber,
+        converged: false,
+        rounds: null,
+        finalSha: null,
+        blocker: 'child run threw or was skipped before returning an outcome',
+      }
+    : eachResult,
+)
+
+const convergedCount = results.filter((eachResult) => eachResult.converged).length
+log(`autoconverge multi-PR done: ${convergedCount}/${results.length} PR(s) converged`)
+
+return {
+  converged: convergedCount === results.length,
+  prCount: results.length,
+  convergedCount,
+  results,
+  blocker: null,
+}

package/skills/autoconverge/workflow/converge_multi.run-input.test.mjs

@@ -0,0 +1,100 @@
+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 multiSource = readFileSync(join(workflowDirectory, 'converge_multi.mjs'), 'utf8');
+
+function sourceSliceBetween(startNeedle, endNeedle) {
+  const sliceStart = multiSource.indexOf(startNeedle);
+  assert.notEqual(sliceStart, -1, `expected ${startNeedle} to exist`);
+  const sliceEnd = multiSource.indexOf(endNeedle, sliceStart + startNeedle.length);
+  assert.notEqual(sliceEnd, -1, `expected ${endNeedle} to exist after ${startNeedle}`);
+  return multiSource.slice(sliceStart, sliceEnd);
+}
+
+const productionModule = new Function(
+  `${sourceSliceBetween('function normalizeMultiInput(', '\nconst multiInput =')}\n` +
+    'return { normalizeMultiInput, isUsablePrEntry, classifyMultiInput };',
+)();
+const { normalizeMultiInput, classifyMultiInput } = productionModule;
+
+const SCRIPT_PATH = '/abs/skills/autoconverge/workflow/converge.mjs';
+
+function validEntry(prNumber) {
+  return {
+    owner: 'JonEcho',
+    repo: 'python-automation',
+    prNumber,
+    repoPath: `/worktrees/pr-${prNumber}`,
+  };
+}
+
+function validArgs() {
+  return { convergeScriptPath: SCRIPT_PATH, prs: [validEntry(398), validEntry(402)] };
+}
+
+test('an object payload passes through unchanged', () => {
+  const parsed = validArgs();
+  assert.deepEqual(normalizeMultiInput(parsed), parsed);
+});
+
+test('a JSON-encoded string payload is parsed into coordinates', () => {
+  assert.deepEqual(normalizeMultiInput(JSON.stringify(validArgs())), validArgs());
+});
+
+test('a non-JSON string returns null rather than throwing', () => {
+  assert.equal(normalizeMultiInput('not json at all'), null);
+});
+
+test('valid coordinates classify with no blocker and keep every PR entry', () => {
+  const classified = classifyMultiInput(validArgs());
+  assert.equal(classified.blocker, null);
+  assert.equal(classified.input.prs.length, 2);
+});
+
+test('a missing convergeScriptPath is blocked', () => {
+  const classified = classifyMultiInput({ prs: [validEntry(398)] });
+  assert.equal(classified.input, null);
+  assert.match(classified.blocker, /convergeScriptPath/);
+});
+
+test('an empty prs array is blocked', () => {
+  const classified = classifyMultiInput({ convergeScriptPath: SCRIPT_PATH, prs: [] });
+  assert.equal(classified.input, null);
+  assert.match(classified.blocker, /non-empty array/);
+});
+
+test('a missing prs list is blocked', () => {
+  const classified = classifyMultiInput({ convergeScriptPath: SCRIPT_PATH });
+  assert.equal(classified.input, null);
+  assert.match(classified.blocker, /non-empty array/);
+});
+
+test('a non-array prs value is blocked', () => {
+  const classified = classifyMultiInput({ convergeScriptPath: SCRIPT_PATH, prs: 'nope' });
+  assert.equal(classified.input, null);
+  assert.match(classified.blocker, /non-empty array/);
+});
+
+test('an entry missing prNumber is blocked', () => {
+  const badEntry = { owner: 'JonEcho', repo: 'python-automation', repoPath: '/w/x' };
+  const classified = classifyMultiInput({ convergeScriptPath: SCRIPT_PATH, prs: [badEntry] });
+  assert.equal(classified.input, null);
+  assert.match(classified.blocker, /missing/);
+});
+
+test('an entry missing repoPath is blocked', () => {
+  const badEntry = { owner: 'JonEcho', repo: 'python-automation', prNumber: 398 };
+  const classified = classifyMultiInput({ convergeScriptPath: SCRIPT_PATH, prs: [badEntry] });
+  assert.equal(classified.input, null);
+  assert.match(classified.blocker, /missing/);
+});
+
+test('a null payload is blocked', () => {
+  const classified = classifyMultiInput('not json at all');
+  assert.equal(classified.input, null);
+  assert.match(classified.blocker, /did not parse/);
+});