claude-dev-env 1.52.0 → 1.53.0

package/package.json

@@ -1,13 +1,13 @@
 {
     "name": "claude-dev-env",
-    "version": "1.52.0",
+    "version": "1.53.0",
     "description": "Claude Code development standards — rules, hooks, agents, commands, and skills",
     "type": "module",
     "bin": {
         "claude-dev-env": "bin/install.mjs"
     },
     "scripts": {
-        "test": "node --test bin/*.test.mjs"
+        "test": "node --test \"bin/*.test.mjs\" \"skills/**/*.test.mjs\""
     },
     "files": [
         "bin/",

package/skills/autoconverge/SKILL.md

@@ -0,0 +1,112 @@
+---
+name: autoconverge
+description: >-
+  Drives one draft PR to convergence in a single autonomous workflow run.
+  Each round runs Cursor Bugbot, a code-review pass, and a bug-audit in
+  parallel on the same HEAD, dedups findings, applies every fix in one
+  commit, re-verifies, then clears a Copilot wait-gate and a closing
+  convergence check before marking the PR ready. Use when the user says
+  '/autoconverge', 'autoconverge this PR', 'converge this PR in one run',
+  'run the converge workflow', or 'drive the PR to ready autonomously'.
+---
+
+# Autoconverge
+
+One launch drives the whole loop to convergence. The `/autoconverge` skill
+resolves PR scope, enters a worktree, grants project permissions, then hands
+the loop to the **`converge.mjs` workflow**, which runs every round and every
+reviewer wait inside one background pass — no ticks, no `ScheduleWakeup`, no
+state file. State lives in the workflow's own variables; resume is handled by
+the workflow journal.
+
+`pr-converge` paces the same four-reviewer loop across `ScheduleWakeup` ticks;
+autoconverge runs it as a deterministic workflow. The two skills share the same
+helper scripts and the same convergence gate.
+
+## Requirements
+
+Scan the tool list at the top of this conversation for the literal string
+`Workflow`. If it is absent, report `autoconverge requires the Workflow tool;
+aborting` and stop. The workflow also needs the `gh` CLI authenticated for the
+PR's owner.
+
+## Pre-flight (main session)
+
+1. **Enter a worktree.** Call `EnterWorktree` with no arguments before any
+   `gh`, `git`, file read, or edit. `gh`/`git` Bash calls do not auto-isolate,
+   so this is mandatory. If it fails, report and stop.
+
+2. **Resolve PR scope.** When the user passed a PR URL or number, parse owner,
+   repo, and number from it. Otherwise read the current branch's PR:
+   `gh pr view --json number,headRefName,url,isDraft,baseRefName`. Capture
+   `owner`, `repo`, `prNumber`. Confirm the PR is a draft; if it is already
+   ready, mark it draft first (`gh pr ready <n> --repo <o>/<r> --undo`) so the
+   loop owns the ready transition.
+
+3. **Grant project permissions.**
+   `python "$HOME/.claude/skills/bugteam/scripts/grant_project_claude_permissions.py"`
+
+## Run the workflow
+
+Call the `Workflow` tool against the colocated script:
+
+```
+Workflow({
+  scriptPath: "<this skill dir>/workflow/converge.mjs",
+  args: { owner: "<O>", repo: "<R>", prNumber: <N>, bugbotDisabled: false }
+})
+```
+
+`scriptPath` is the absolute path to `workflow/converge.mjs` inside this skill's
+own directory (on this install,
+`<home>/.claude/skills/autoconverge/workflow/converge.mjs`). Set
+`bugbotDisabled: true` only when the user has opted Cursor Bugbot out for the
+run; otherwise the workflow detects an opt-out or an unreachable Bugbot on its
+own. The workflow runs in the background and notifies this session on
+completion. Watch live progress with `/workflows`.
+
+The workflow returns
+`{ converged, rounds, finalSha, blocker }`.
+
+## Teardown (on workflow completion)
+
+1. **When `converged` is true:** rewrite the PR description and clean the
+   working tree — see
+   [`bugteam/reference/teardown-publish-permissions.md` § Step 4 and § Step 4.5](../bugteam/reference/teardown-publish-permissions.md).
+   The workflow already marked the PR ready.
+
+2. **Always revoke project permissions** (including on a blocker exit):
+   `python "$HOME/.claude/skills/bugteam/scripts/revoke_project_claude_permissions.py"`
+
+3. **Print the final report:**
+
+   ```
+   /autoconverge exit: <converged | blocked>
+   Rounds: <N>
+   Final commit: <finalSha>
+   Blocker: <blocker>        # only when blocked
+   ```
+
+## What the workflow does each round
+
+See [`reference/convergence.md`](reference/convergence.md) for the full round
+shape and the exact convergence definition, and
+[`reference/stop-conditions.md`](reference/stop-conditions.md) for every way the
+run ends short of ready. Hard-won failure lessons live in
+[`reference/gotchas.md`](reference/gotchas.md).
+
+- **Converge:** `parallel([Bugbot lens, code-review lens, bug-audit lens])` on
+  the current HEAD, full `origin/main...HEAD` diff. Dedup findings; one
+  `clean-coder` applies all fixes in a single commit, pushes, replies to and
+  resolves any bot threads; re-verify next round on the new HEAD. When all
+  three are clean on a stable HEAD, post the CLEAN bugteam audit artifact.
+- **Copilot gate:** request a Copilot review, poll up to three times; findings
+  route back into Converge, a no-show after the cap is a blocker.
+- **Convergence check:** `check_convergence.py` is the authoritative gate; on a
+  full pass the workflow marks `draft=false`.
+
+## Folder map
+
+- `SKILL.md` — this hub.
+- `workflow/converge.mjs` — the convergence workflow script.
+- `reference/` — convergence definition, stop conditions, gotchas.

package/skills/autoconverge/reference/convergence.md

@@ -0,0 +1,84 @@
+# Convergence — round shape and the ready definition
+
+## The round loop
+
+The workflow holds three states and moves between them until the PR is ready or
+a blocker ends the run. A single iteration counter increments on every pass
+through any phase and caps the whole run at 20 loop iterations; the round counter
+tracks CONVERGE passes only and is never the cap.
+
+**CONVERGE** (one round = one parallel sweep):
+
+1. Resolve the current PR HEAD SHA.
+2. Run three lenses in parallel on that HEAD, each over the full
+   `origin/main...HEAD` diff:
+   - **Bugbot lens** — drive Cursor Bugbot to a verdict on HEAD (trigger and
+     poll its CI check run when needed) and return its findings, or mark itself
+     down when Bugbot is opted out or unreachable.
+   - **Code-review lens** — a correctness-focused review pass (`code-quality-agent`)
+     that reports findings without editing.
+   - **Bug-audit lens** — the bug-audit (`code-quality-agent`) applying the
+     shared A–P rubric from `bugteam/reference/audit-contract.md`, reporting
+     findings without editing.
+3. Dedup findings across the three lenses by file, line, and title. A collision
+   keeps the most severe duplicate's severity (P0 > P1 > P2), unions the detail
+   text, and collects every distinct bot thread id so the fix lens resolves all
+   colliding threads.
+4. **Any findings** → one `clean-coder` applies every fix in a single test-first
+   commit, pushes, then replies to and resolves each finding that carries a
+   GitHub review thread. A round progresses when the fix lens lands a push that
+   moves HEAD, or when every finding was already addressed so no code change is
+   needed yet each finding thread is still resolved (the fix lens reports
+   `resolvedWithoutCommit` and the run re-converges on the unchanged HEAD). A
+   round whose fix lens reports neither a moved-HEAD push nor a full
+   thread-resolution ends the run with a fix-stalled blocker. The next round
+   re-verifies on the current HEAD.
+5. **Zero findings on a stable HEAD** → post the CLEAN bugteam audit artifact
+   for that HEAD, then move to the Copilot gate.
+
+**COPILOT** gate:
+
+- Request a Copilot review on HEAD (skipping a duplicate request), then poll up
+  to three times, 360 seconds apart.
+- Copilot findings → fix them and return to CONVERGE on the new HEAD.
+- Copilot clean or approved → move to the convergence check.
+- No review after three polls → blocker.
+
+**Convergence check**:
+
+- Run `check_convergence.py`. A full pass marks the PR ready (`draft=false`) and
+  ends the run. A failure returns to CONVERGE so the next round addresses the
+  failing gate.
+
+## Full-diff rule
+
+Every lens, every round, reviews the full `origin/main...HEAD` diff — every file
+the PR touches. A lens that scopes to recent commits, a single file, or a
+bugbot-flagged path does not satisfy the round; its clean verdict is not a clean.
+
+## The ready definition
+
+`check_convergence.py` is the single source of truth for readiness. It re-derives
+every condition from GitHub and marks the PR ready only when all of these hold on
+the current HEAD:
+
+1. Bugbot CI check run is completed with a success or neutral conclusion
+   (bypassed when Bugbot is opted out or proved unreachable this run).
+2. The Bugbot review body on HEAD reports no findings (checked when a Bugbot
+   review is present).
+3. A CLEAN bugteam audit review sits on HEAD.
+4. The Copilot review on HEAD is clean or approved.
+5. Zero unresolved bot review threads anywhere on the PR — counting Cursor,
+   Claude, and Copilot authored threads where `isResolved` is false (`isOutdated`
+   threads are excluded by the gate, but the fix lens still verifies and resolves
+   them during the round).
+6. The PR is mergeable (`mergeable` true and `mergeable_state` clean).
+7. No requested reviewers are still pending.
+
+## Audit-trail design
+
+Bugbot and Copilot post their own review threads, which the fix lens replies to
+and resolves. The bug-audit lens keeps its findings in memory across the round
+and posts only the terminal CLEAN bugteam review once every lens is clean on a
+stable HEAD — that single artifact is what gate 3 reads. This keeps thread churn
+to the threads the bots raise themselves.

package/skills/autoconverge/reference/gotchas.md

@@ -0,0 +1,47 @@
+# Gotchas
+
+Hard-won lessons for the autoconverge workflow. Append a bullet each time a run
+fails in a new way.
+
+- **The workflow script cannot sleep.** `Date.now`, `Math.random`, and timers
+  are unavailable in the script body, and a foreground sleep is blocked. Every
+  reviewer wait lives inside an `agent`'s own poll loop — a shell-agnostic `sleep`
+  loop (PowerShell `Start-Sleep` is an allowed alternative), or `gh` check
+  polling. Never try to wait in the script itself.
+
+- **Workflow agents start blank.** Spawned agents do not inherit CLAUDE.md,
+  rules, or this skill's context. Each agent prompt is self-contained: it names
+  the exact scripts and flags, the full `origin/main...HEAD` diff scope, and the
+  return contract.
+
+- **Only the fix lens writes.** The three converge lenses read and report; they
+  never edit, commit, or push. Because only the serial fix step pushes, the
+  parallel sweep needs no worktree isolation.
+
+- **Fetch origin/main once before the parallel lenses.** The code-review and
+  bug-audit lenses both diff against `origin/main`. Concurrent `git fetch` calls
+  contend on the worktree `.git` lock and fail intermittently, so the workflow
+  runs a single serial `git fetch origin main` (the `prefetch-main` step) at the
+  start of each round and the parallel lenses run no git fetch of their own —
+  they diff against the already-current ref.
+
+- **The CLEAN bugteam artifact is HEAD-specific.** `check_convergence.py` reads
+  the bugteam review on the current HEAD. Any push moves HEAD and invalidates a
+  prior artifact, so post it only when a round is fully clean, and post a fresh
+  one after any later fix round.
+
+- **Bot login fields differ by endpoint.** `get_reviews` returns `.user.login`
+  (an object), while `get_review_comments` returns `.author` (a string). Match
+  bot logins with case-insensitive substring tests, not strict equality.
+
+- **`scriptPath` takes a real path, not a shell variable.** `$HOME` expands in a
+  Bash command but not in the `Workflow` tool's `scriptPath` argument. Pass the
+  expanded absolute path to `workflow/converge.mjs`.
+
+- **Tilde paths fail on Windows Git Bash.** Inside shell calls, use `$HOME/.claude/...`,
+  not `~/.claude/...`; a tilde resolves to the wrong home and gives a
+  file-not-found error that looks like a script failure.
+
+- **`gh` token drift across accounts.** When a run touches more than one GitHub
+  account, pin the token with `--user <login>`; `gh auth token` alone can return
+  another account's token after a switch.

package/skills/autoconverge/reference/stop-conditions.md

@@ -0,0 +1,59 @@
+# Stop conditions
+
+The workflow ends one of two ways: converged (PR marked ready) or blocked. A
+blocker exit returns `{ converged: false, rounds, finalSha, blocker }`, and the
+skill still runs teardown (revoke permissions, final report).
+
+## Blockers (end the run short of ready)
+
+- **Copilot no-show** — Copilot surfaces no review on the current HEAD after
+  three polls (360 seconds apart). `blocker` names the Copilot timeout.
+- **Iteration cap** — 20 loop iterations pass without a full convergence-check
+  pass. The iteration counter increments on every pass through any phase, so a
+  convergence-check gate that no round can clear (for example a `mergeable_state`
+  stuck at `blocked`, `behind`, or `unknown` that a rebase does not fix) and a
+  Copilot gate agent that keeps dying and retrying on the same HEAD both reach
+  the cap this way. `blocker` reports `iteration cap reached`.
+- **Fix stalled** — the fix lens reports no push (`pushed: false`) without
+  resolving every finding thread, returns a SHA equal to the prior HEAD on a
+  case-folded common prefix (a full or abbreviated SHA of the unchanged commit
+  both count), or returns null for a round's findings. HEAD did not move and the
+  threads were not all resolved, so the next round would re-raise the same
+  findings. The run ends with a `blocker` that names the finding count and the
+  stalled HEAD. A round whose every finding carries no GitHub thread
+  (`replyToCommentId: null` on each) and whose fix reports
+  `resolvedWithoutCommit: true` is also a stall: it moves no code and resolves no
+  thread, so re-converging on the unchanged HEAD would loop the same finding to
+  the iteration cap. The `blocker` names the in-memory finding count and the
+  stalled HEAD. An all-stale round that makes no commit but resolves every
+  finding thread (`resolvedWithoutCommit: true` with at least one thread-bearing
+  finding) is not a stall — the run re-converges on the unchanged HEAD and
+  reaches the Copilot and convergence gates.
+- **Mark-ready failed** — the convergence check passes but the mark-ready step
+  cannot confirm the PR left draft state (`gh pr ready` errored, or the draft
+  re-query still reports true). The workflow does not report `converged: true`;
+  the run ends with a `blocker` naming the failed ready transition.
+
+## Not a blocker (the run continues)
+
+- **Bugbot down** — when Cursor Bugbot is opted out, or never produces a check
+  run or review after the lens poll budget, the Bugbot lens returns `down: true`.
+  The run continues, and the convergence check runs with `--bugbot-down` so its
+  Bugbot gate is bypassed.
+- **A lens agent dies** — when one parallel lens returns null (a terminal agent
+  failure), the round proceeds on the surviving lenses. A real defect it would
+  have caught surfaces in a later round or at the convergence check. A dead
+  Bugbot lens (null result) counts as down for that HEAD, so the convergence
+  check runs with `--bugbot-down` rather than demanding a Bugbot verdict the
+  dead agent never produced.
+- **Every lens agent dies** — when all three parallel lenses return null in the
+  same round, the round is a failure, not a clean: the workflow posts no CLEAN
+  bugteam artifact and does not advance to the Copilot gate. It re-resolves HEAD
+  and retries on the next round, still bounded by the iteration cap.
+
+## User stop
+
+Stopping the background workflow (`TaskStop`, or the user halting the run) ends
+it where it stands. Re-launching `/autoconverge` starts a fresh run; the
+workflow journal allows resuming the prior run from its last completed step with
+`Workflow({ scriptPath, resumeFromRunId })`.

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

@@ -0,0 +1,177 @@
+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 branchEnd = convergeSource.indexOf('continue', transitionIndex) + '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',
+  );
+});
+
+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.fix-progress.test.mjs

@@ -0,0 +1,107 @@
+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 functionBody(functionName) {
+  const functionStart = convergeSource.indexOf(`function ${functionName}(`);
+  assert.notEqual(functionStart, -1, `expected ${functionName} to exist`);
+  const nextFunctionStart = convergeSource.indexOf('\nfunction ', functionStart + 1);
+  const functionEnd = nextFunctionStart === -1 ? convergeSource.length : nextFunctionStart;
+  return convergeSource.slice(functionStart, functionEnd);
+}
+
+function constantLine(constantName) {
+  const constantSource = readFileSync(join(workflowDirectory, 'converge.mjs'), 'utf8');
+  const matchedLine = constantSource
+    .split('\n')
+    .find((eachLine) => eachLine.trimStart().startsWith(`const ${constantName} =`));
+  assert.ok(matchedLine, `expected ${constantName} to be declared`);
+  return matchedLine;
+}
+
+const productionModule = new Function(
+  `${constantLine('SHA_COMPARISON_PREFIX_LENGTH')}\n` +
+    `${functionBody('normalizeShaForComparison')}\n` +
+    `${functionBody('collectFindingThreadIds')}\n` +
+    `${functionBody('detectFixProgress')}\n` +
+    'return { detectFixProgress, collectFindingThreadIds };',
+)();
+
+const { detectFixProgress, collectFindingThreadIds } = productionModule;
+
+const PRIOR_HEAD = 'abcdef0123456789abcdef0123456789abcdef01';
+const MOVED_HEAD = 'fedcba9876543210fedcba9876543210fedcba98';
+
+function nullThreadFinding() {
+  return { file: 'converge.mjs', line: 278, severity: 'P2', title: 'stale', detail: 'x', replyToCommentId: null };
+}
+
+function threadBearingFinding() {
+  return { file: 'converge.mjs', line: 278, severity: 'P2', title: 'stale', detail: 'x', replyToCommentId: 4242 };
+}
+
+test('a resolvedWithoutCommit round whose findings carry no thread id does not count as progress', () => {
+  const allNullThreadFindings = [nullThreadFinding(), nullThreadFinding()];
+  const hadThreadBearingFinding = allNullThreadFindings.some(
+    (eachFinding) => collectFindingThreadIds(eachFinding).length > 0,
+  );
+  const fixProgress = detectFixProgress(
+    { newSha: PRIOR_HEAD, pushed: false, resolvedWithoutCommit: true, summary: 'judged stale' },
+    PRIOR_HEAD,
+    hadThreadBearingFinding,
+  );
+  assert.equal(fixProgress.progressed, false);
+});
+
+test('a resolvedWithoutCommit round with at least one thread-bearing finding still counts as progress', () => {
+  const mixedFindings = [nullThreadFinding(), threadBearingFinding()];
+  const hadThreadBearingFinding = mixedFindings.some(
+    (eachFinding) => collectFindingThreadIds(eachFinding).length > 0,
+  );
+  const fixProgress = detectFixProgress(
+    { newSha: PRIOR_HEAD, pushed: false, resolvedWithoutCommit: true, summary: 'resolved threads' },
+    PRIOR_HEAD,
+    hadThreadBearingFinding,
+  );
+  assert.equal(fixProgress.progressed, true);
+  assert.equal(fixProgress.newSha, PRIOR_HEAD);
+});
+
+test('a pushed fix that moved HEAD still progresses regardless of thread-bearing findings', () => {
+  const fixProgress = detectFixProgress(
+    { newSha: MOVED_HEAD, pushed: true, resolvedWithoutCommit: false, summary: 'committed' },
+    PRIOR_HEAD,
+    false,
+  );
+  assert.equal(fixProgress.progressed, true);
+  assert.equal(fixProgress.newSha, MOVED_HEAD);
+});
+
+test('a dead fix agent never progresses', () => {
+  const fixProgress = detectFixProgress(null, PRIOR_HEAD, true);
+  assert.equal(fixProgress.progressed, false);
+  assert.equal(fixProgress.newSha, PRIOR_HEAD);
+});
+
+test('the converge call site sets a fix-stalled blocker when an all-null-thread resolvedWithoutCommit round cannot progress', () => {
+  const convergeBranch = convergeSource.slice(
+    convergeSource.indexOf("const fixResult = await applyFixes(head, findings, 'converge-round')"),
+    convergeSource.indexOf("if (!roundOutcome.roundClean)"),
+  );
+  assert.match(convergeBranch, /collectFindingThreadIds/);
+  assert.match(convergeBranch, /fix stalled/i);
+});
+
+test('the copilot call site sets a fix-stalled blocker when an all-null-thread resolvedWithoutCommit round cannot progress', () => {
+  const copilotBranch = convergeSource.slice(
+    convergeSource.indexOf("const fixResult = await applyFixes(head, copilotOutcome.findings, 'copilot')"),
+    convergeSource.indexOf("phase = 'CONVERGE'\n      continue\n    }\n    phase = 'FINALIZE'"),
+  );
+  assert.match(copilotBranch, /collectFindingThreadIds/);
+  assert.match(copilotBranch, /fix stalled/i);
+});