claude-dev-env 1.71.0 → 1.73.0

package/rules/docstring-prose-matches-implementation.md

@@ -6,7 +6,7 @@
 
 When a docstring enumerates the behaviors a body applies, the enumeration covers every behavior the body applies. A reader trusts the list to be complete: an item the code applies but the prose omits is a silent gap that misleads every future reader and reviewer.
 
-The gate validator `check_docstring_args_match_signature` covers the `Args:` section parameter names. Two more gate validators each cover one deterministic slice of the free-form prose. `check_docstring_fallback_branch_coverage` covers a summary that scopes a fallback to a single condition (`only when`, `falls back to ... when`) while the body routes to that same fallback call from two or more distinct early-return guards. `check_class_docstring_names_public_methods` covers a class whose docstring is a single summary line while the class exposes two or more public methods whose names the summary never spells out — the drift where a one-line class summary keeps naming its first feature after the class grows a second public entry point. The remaining free-form prose — `"a field counts as read when ..."`, `"resolves to shared temp only"`, `"strip ceremony, then drop blockquotes"`, and module-level responsibility paragraphs — has no signature, method roster, or single structural shape to compare against, so the gate cannot catch its drift. This rule is the judgment standard for that prose; the audit lane below is the enforcement for everything outside the three gated slices.
+The gate validator `check_docstring_args_match_signature` covers the `Args:` section parameter names. Three more gate validators each cover one deterministic slice of the free-form prose. `check_docstring_fallback_branch_coverage` covers a summary that scopes a fallback to a single condition (`only when`, `falls back to ... when`) while the body routes to that same fallback call from two or more distinct early-return guards. `check_class_docstring_names_public_methods` covers a class whose docstring is a single summary line while the class exposes two or more public methods whose names the summary never spells out — the drift where a one-line class summary keeps naming its first feature after the class grows a second public entry point. `check_docstring_no_consumer_claim` covers a producer docstring asserting that no consumer reads its output yet (`producer-only artifact`, `no submission-run consumer reads it yet`) — a transitional claim that drifts the moment a reader lands and contradicts any companion `SKILL.md` that documents the consumer; this is the deterministic slice of the O8 companion-doc producer/consumer drift below. The remaining free-form prose — `"a field counts as read when ..."`, `"resolves to shared temp only"`, `"strip ceremony, then drop blockquotes"`, and module-level responsibility paragraphs — has no signature, method roster, or single structural shape to compare against, so the gate cannot catch its drift. This rule is the judgment standard for that prose; the audit lane below is the enforcement for everything outside the four gated slices.
 
 ## What to check before you write the docstring
 
@@ -15,8 +15,9 @@ Read the body and the docstring side by side:
 - **Read-source / match-source unions.** A body that computes `read_names = a | b | c` (or any union of "what counts") names each union member in the prose enumeration. A union member the code applies but the prose omits is a gap.
 - **Suppressor / skip lists.** A body with several early returns that suppress the check names each suppressor in the prose.
 - **Shared fallback routes.** A summary that scopes a fallback call to one condition names every condition that reaches that call. When the body routes to the same fallback from two or more early-return guards (`if a is None: fallback(); return` and `if random() < p: fallback(); return`), the prose enumerates both guards. The `check_docstring_fallback_branch_coverage` gate blocks the single-condition form of this drift at Write/Edit time.
-- **Step order.** A docstring that says `A then B then C` matches the call order in the body.
+- **Step order.** A docstring that says `A then B then C` matches the call order in the body. A step enumeration that names the body's linear steps also names every corrective step the body guards inside an `if`/`elif` branch (`if not await cancel_and_reinitiate_update(...): return`). The `check_docstring_step_enumeration_dispatch_coverage` gate blocks the branch-guarded-dispatch form of this drift — a step-enumeration docstring that omits a two-or-more-token dispatch step the body guards inside a branch — at Write/Edit time.
 - **Predicate breadth.** A boolean helper whose prose promises a narrow check accepts only the inputs the prose names — no broader input class the name and prose do not mention.
+- **Exclusion-clause distinguisher.** A docstring sentence that says a named category of input "are not" / "is not" the thing the function flags (`plain logging, screenshot, or method-on-local calls inside a branch are not dispatch steps`) keys the exclusion to the same axis the body's classification keys on. When the body decides on one axis (a call sits in an `If.test` guard versus a plain statement) but the prose excludes on a different axis (the call's receiver shape — a method on a local), the exclusion clause names a category the body still flags: a guarded method-on-local call is flagged even though the prose lists method-on-local calls as excluded. Read the body's actual branch condition, then state the exclusion on that same axis (`plain (unguarded) calls inside a branch body are not dispatch steps`), so every member the prose excludes is a member the body also excludes.
 - **Companion-doc ordering and content claims.** A `SKILL.md` (or sibling `.md`) sentence that names a produced artifact and claims its order (`sorted`, `alphabetical`, `in sorted order`) or its content (`the at-risk names`, `just the current set`) matches the producer function's docstring and body for that same artifact. A producer that builds the artifact by merging stored names with new names and appending — preserving file order, not re-sorting the union — leaves a doc that still says `sorted` drifted on both counts: the order claim is wrong, and the content claim hides the merged-in prior entries. When the producer's ordering or union changes, the same change updates the companion doc. The two move together in one commit, even when the producer edit does not touch the `.md` file.
 
 When the body changes the set of behaviors it applies, the same edit updates the prose enumeration. The two move together in one commit.

package/scripts/CLAUDE.md

@@ -18,6 +18,7 @@ Utility scripts installed into `~/.claude/scripts/` by `bin/install.mjs`. Each s
 | `Migrate-ShellPolicy.ps1` | Applies automated fixes for common shell-policy violations found by the audit script |
 | `Install-SweepEmptyDirs.ps1` | Registers `sweep_empty_dirs.py` as a scheduled task on Windows |
 | `check.ps1` | Runs the full code-quality check suite |
+| `Show-Asset.ps1` | Opens files on screen, sizing each image window to the image's pixel dimensions (scaled to fit the screen); non-image files open in their default application |
 
 ## Subdirectories
 

package/scripts/Show-Asset.ps1

@@ -0,0 +1,106 @@
+<#
+.SYNOPSIS
+Opens files on screen, sizing each image window to the image's own dimensions.
+
+.DESCRIPTION
+For every path given, an image opens in a window whose client area matches the
+image's pixel size, scaled down to fit the primary screen's working area when the
+image is larger than the screen. A small image gets a usable minimum window with
+the picture centered at native size. Non-image files open in their registered
+default application, and any file that cannot be loaded as an image falls back to
+that default application too. Escape or the close button dismisses a window; the
+process exits once every window is closed.
+
+.PARAMETER Paths
+One or more file paths to open.
+#>
+param(
+    [Parameter(ValueFromRemainingArguments = $true)]
+    [string[]]$Paths
+)
+
+Add-Type -AssemblyName System.Windows.Forms
+Add-Type -AssemblyName System.Drawing
+
+try {
+    [System.Windows.Forms.Application]::SetHighDpiMode([System.Windows.Forms.HighDpiMode]::PerMonitorV2) | Out-Null
+}
+catch {
+    $null = $_
+}
+[System.Windows.Forms.Application]::EnableVisualStyles()
+
+$imageExtensions = @('.png', '.jpg', '.jpeg', '.gif', '.bmp', '.webp', '.tif', '.tiff', '.ico')
+$screenMargin = 80
+$minimumClientWidth = 220
+$minimumClientHeight = 160
+$openWindowCount = 0
+
+foreach ($path in $Paths) {
+    if (-not (Test-Path -LiteralPath $path)) { continue }
+    $fullPath = (Resolve-Path -LiteralPath $path).Path
+    $extension = [System.IO.Path]::GetExtension($fullPath).ToLowerInvariant()
+
+    if ($imageExtensions -notcontains $extension) {
+        Invoke-Item -LiteralPath $fullPath
+        continue
+    }
+
+    try {
+        $imageBytes = [System.IO.File]::ReadAllBytes($fullPath)
+        $imageStream = New-Object System.IO.MemoryStream(, $imageBytes)
+        $loadedImage = [System.Drawing.Image]::FromStream($imageStream)
+        $image = New-Object System.Drawing.Bitmap($loadedImage)
+        $loadedImage.Dispose()
+        $imageStream.Dispose()
+    }
+    catch {
+        Invoke-Item -LiteralPath $fullPath
+        continue
+    }
+
+    $workingArea = [System.Windows.Forms.Screen]::PrimaryScreen.WorkingArea
+    $maximumWidth = $workingArea.Width - $screenMargin
+    $maximumHeight = $workingArea.Height - $screenMargin
+    $scale = [Math]::Min(1.0, [Math]::Min($maximumWidth / $image.Width, $maximumHeight / $image.Height))
+
+    $pictureBox = New-Object System.Windows.Forms.PictureBox
+    $pictureBox.Dock = [System.Windows.Forms.DockStyle]::Fill
+    $pictureBox.Image = $image
+
+    if ($scale -lt 1.0) {
+        $pictureBox.SizeMode = [System.Windows.Forms.PictureBoxSizeMode]::Zoom
+        $clientWidth = [int][Math]::Round($image.Width * $scale)
+        $clientHeight = [int][Math]::Round($image.Height * $scale)
+    }
+    else {
+        $pictureBox.SizeMode = [System.Windows.Forms.PictureBoxSizeMode]::CenterImage
+        $clientWidth = [Math]::Max($minimumClientWidth, $image.Width)
+        $clientHeight = [Math]::Max($minimumClientHeight, $image.Height)
+    }
+
+    $form = New-Object System.Windows.Forms.Form
+    $form.Text = [System.IO.Path]::GetFileName($fullPath)
+    $form.AutoScaleMode = [System.Windows.Forms.AutoScaleMode]::None
+    $form.StartPosition = [System.Windows.Forms.FormStartPosition]::CenterScreen
+    $form.ClientSize = New-Object System.Drawing.Size($clientWidth, $clientHeight)
+    $form.KeyPreview = $true
+    $form.BackColor = [System.Drawing.Color]::FromArgb(24, 24, 24)
+    $form.Controls.Add($pictureBox)
+
+    $form.Add_KeyDown({
+            param($sender, $eventArguments)
+            if ($eventArguments.KeyCode -eq [System.Windows.Forms.Keys]::Escape) { $sender.Close() }
+        })
+    $form.Add_FormClosed({
+            $script:openWindowCount--
+            if ($script:openWindowCount -le 0) { [System.Windows.Forms.Application]::Exit() }
+        })
+
+    $openWindowCount++
+    $form.Show()
+}
+
+if ($openWindowCount -gt 0) {
+    [System.Windows.Forms.Application]::Run()
+}

package/skills/autoconverge/SKILL.md

@@ -23,6 +23,22 @@ the workflow journal.
 autoconverge runs it as a deterministic workflow. The two skills share the same
 helper scripts and the same convergence gate.
 
+## Run scope: one PR or several
+
+Decide the scope from how many PRs the user named, then follow that path:
+
+1. **One PR** → the single-PR run described below (`workflow/converge.mjs`): one
+   worktree, one workflow launch, one teardown.
+2. **Several PRs** → the [Multiple PRs](#multiple-prs) run
+   (`workflow/converge_multi.mjs`): one worktree per PR and a single workflow
+   launch that drives every PR's converge run in parallel, then one teardown per
+   PR.
+
+The single-PR sections (Requirements, Pre-flight, Run the workflow, Teardown)
+each describe one converge run. The Multiple PRs section reuses them once per PR
+and adds only what fanning out needs: a per-PR worktree and a per-PR teardown
+loop.
+
 ## Requirements
 
 Scan the tool list at the top of this conversation for the literal string
@@ -101,7 +117,7 @@ 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, standardsNote, copilotNote }`.
+`{ converged, rounds, finalSha, blocker, standardsNote, copilotNote, reuseNote }`.
 
 ## Budget-aware round boundaries
 
@@ -207,8 +223,31 @@ round records nothing resumable and replays dirty.
    Blocker: <blocker>        # only when blocked
    Standards: <standardsNote> # only when a round deferred code-standard findings
    Copilot: <copilotNote>     # only when Copilot was down or out of quota
+   Reuse: <reuseNote>         # only when the reuse pass identified an improvement
    ```
 
+## Reuse pass (before convergence)
+
+Before the first round, one reuse lens (`code-quality-agent`) scans the full
+`origin/main...HEAD` diff for places the PR re-implements behavior the codebase
+already provides. It reports a reuse improvement only when all three criteria
+hold, and drops any case where even one is in doubt:
+
+- **Certain** — an existing symbol or module unquestionably covers the new
+  code's behavior, cited at `file:line`.
+- **Behaviorally identical** — swapping the new code for the existing one
+  changes no observable behavior: same inputs, outputs, side effects, and error
+  handling.
+- **Autonomously implementable** — the replacement is a mechanical edit (import
+  and call the existing symbol, delete the duplicate) needing no product
+  decision and no human judgment.
+
+The reuse lens reports without editing. Qualifying improvements then run through
+the same edit → verify → commit fix flow the rounds use, so they land in one
+verified commit before convergence starts. The pass is best-effort: when no case
+clears all three criteria, the run proceeds straight to convergence, and
+`reuseNote` records what landed.
+
 ## What the workflow does each round
 
 See [`reference/convergence.md`](reference/convergence.md) for the full round
@@ -227,8 +266,12 @@ suite (`python -m pytest`) and keep scratch work in ephemeral temp dirs.
 - **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.
+  resolves any bot threads; re-verify next round on the new HEAD. Every edit
+  step ends with a pre-commit gate check: before its turn ends, the fixer
+  dry-runs the CODE_RULES commit gate (`code_rules_gate.py --staged`) and keeps
+  fixing until that gate would accept the commit — it makes no commit itself.
+  When all three are clean on a stable HEAD, post the CLEAN bugteam audit
+  artifact.
   A round whose findings are ALL code-standard violations (pure CODE_RULES/style,
   no behavioral impact) passes for convergence purposes: the workflow files a
   follow-up issue listing the findings, opens a draft environment-hardening PR
@@ -243,10 +286,87 @@ suite (`python -m pytest`) and keep scratch work in ephemeral temp dirs.
 - **Convergence check:** `check_convergence.py` is the authoritative gate; on a
   full pass the workflow marks `draft=false`.
 
+## Multiple PRs
+
+The multi-PR run drives several draft PRs to ready in one launch:
+`workflow/converge_multi.mjs` fans out one `converge.mjs` child run per PR with
+`parallel()`, and every child is pinned to its own PR's worktree through the
+`repoPath` it receives, so the children never share a checkout. Each child run is
+the exact single-PR convergence loop — same rounds, same reuse pass, same Copilot
+gate, same convergence check — one per PR at once. The children share the run's
+concurrency cap, so the fan-out self-throttles rather than spawning every PR's
+lenses at the same instant.
+
+### Multi-PR pre-flight (main session)
+
+`EnterWorktree` puts the session on one branch only, so the multi-PR path gives
+each PR its own checkout with `git worktree add`. For each PR the user named:
+
+1. **Resolve PR scope** as the single-PR pre-flight step 2 does: capture `owner`,
+   `repo`, `prNumber`, and `headRefName`; confirm the PR is a draft, and mark it
+   draft (`gh pr ready <n> --repo <o>/<r> --undo`) when it is already ready so the
+   loop owns the ready transition.
+2. **Create a worktree on the PR's head ref** and capture its absolute path. From
+   inside the PR's repository checkout:
+   `git worktree add <abs worktree path> <headRefName>` (run `git fetch origin
+   <headRefName>` first when the ref is not local). Put each PR's worktree under a
+   path carrying its PR number so the fan-out keeps them distinct. Confirm
+   `git -C <abs worktree path> rev-parse --abbrev-ref HEAD` equals the head ref
+   and its `HEAD` equals the PR head SHA.
+3. **Verify each worktree is the PR's repo (strict pre-flight):**
+   `python "$HOME/.claude/skills/_shared/pr-loop/scripts/preflight_worktree.py" --owner <owner> --repo <repo> --mode strict`,
+   run with that worktree as the working directory. A non-zero exit prints a
+   `PREFLIGHT_OUTCOME` line and an `ABORT` line: report it and drop that PR from
+   the run rather than aborting every PR.
+4. **Grant project permissions once per repository** — the single-PR pre-flight
+   step 4 grant covers every worktree of the same repo, so run it one time for
+   the repo the PRs live in.
+
+### Launch the multi-PR workflow
+
+Call the `Workflow` tool against the fan-out script, passing the absolute path of
+`converge.mjs` and one entry per PR:
+
+```
+Workflow({
+  scriptPath: "<this skill dir>/workflow/converge_multi.mjs",
+  args: {
+    convergeScriptPath: "<this skill dir>/workflow/converge.mjs",
+    prs: [
+      { owner: "<O>", repo: "<R>", prNumber: <N1>, repoPath: "<abs worktree 1>", bugbotDisabled: false },
+      { owner: "<O>", repo: "<R>", prNumber: <N2>, repoPath: "<abs worktree 2>", bugbotDisabled: false }
+    ]
+  }
+})
+```
+
+`convergeScriptPath` is the absolute path to `workflow/converge.mjs` in this same
+skill directory; each `repoPath` is the absolute path of the worktree that PR is
+checked out in. The workflow runs in the background and notifies this session on
+completion; watch live progress with `/workflows`, where each PR's child run
+appears under its own group.
+
+The workflow returns `{ converged, prCount, convergedCount, results, blocker }`,
+where `results` is one record per PR carrying
+`{ owner, repo, prNumber, converged, rounds, finalSha, blocker }`. The top-level
+`converged` is true only when every PR converged.
+
+### Multi-PR teardown (on workflow completion)
+
+Run the single-PR [Teardown](#teardown-on-workflow-completion) once per entry in
+`results`, using that PR's `owner`, `repo`, `prNumber`, and `finalSha`, and its
+own worktree as the working directory. Build and publish a PR's closing report
+only for a PR whose `converged` is true; for a PR that returned a blocker, skip
+its report and carry the blocker into the final summary. Revoke project
+permissions once per repository after every PR's teardown. Then print one summary
+report — a line per PR as
+`#<prNumber>: <converged | blocked> — rounds <N>, final <finalSha>[, blocker <blocker>]`.
+
 ## Folder map
 
 - `SKILL.md` — this hub.
 - `workflow/converge.mjs` — the convergence workflow script.
+- `workflow/converge_multi.mjs` — the multi-PR fan-out driver: one `converge.mjs` child run per PR in parallel, each pinned to its PR worktree via `repoPath`.
 - `workflow/aggregate_runs.py` — merges every autoconverge journal for a PR into one journal and returns its deduped findings, fix summaries, round count, and final SHA.
 - `workflow/convergence_summary.py` — builds the convergence-summary agent prompt over a PR's merged findings.
 - `workflow/render_report.py` — builds the closing convergence insights HTML report, taking the summary from `--summary-file`.

package/skills/autoconverge/reference/convergence.md

@@ -1,5 +1,42 @@
 # Convergence — round shape and the ready definition
 
+## Pre-flight: clear merge conflicts
+
+Before the first round, the workflow checks once whether the PR branch conflicts
+with `origin/main`. When GitHub reports a conflict (`mergeable` false or
+`mergeable_state` dirty), one `clean-coder` rebases the branch onto `origin/main`
+and resolves every conflict — gated the same way as every other code change: the
+edit leaves the rebase in the working tree, a `code-verifier` binds a verdict to
+it, and the commit step force-pushes with lease. The bug checks then run on a
+conflict-free diff.
+
+A PR that merges cleanly skips the rebase. A conflict that surfaces mid-run, when
+`origin/main` advances during a later round, is caught by the convergence repair
+at the end of the loop, which also rebases.
+
+## Reuse pass (runs after the conflict pre-flight, before convergence)
+
+One reuse lens (`code-quality-agent`) reviews the full `origin/main...HEAD` diff
+for code that re-implements behavior the repository already provides. It reports a
+reuse improvement only when all three criteria hold together, and omits any case
+where even one is in doubt:
+
+1. **Certain** — an existing symbol or module unquestionably covers the new
+   code's behavior, cited at `file:line`.
+2. **Behaviorally the same** — swapping the new code for the existing one
+   changes no observable behavior: same inputs, outputs, side effects, and
+   error handling.
+3. **Autonomously implementable** — the replacement is a mechanical edit (import
+   and call the existing symbol, drop the duplicate) needing no product
+   decision and no human judgment.
+
+The lens reports without editing. Each qualifying improvement runs through the
+same edit → verify → commit fix flow the rounds use, landing in one verified
+commit before convergence begins. The pass is best-effort: when no case clears
+all three criteria the run proceeds straight to convergence. Whatever the reuse
+pass surfaces also joins the round findings, so the code-review lens re-checks
+any improvement that did not land.
+
 ## The round loop
 
 The workflow holds three states and moves between them until the PR is ready or
@@ -26,7 +63,10 @@ tracks CONVERGE passes only and is never the cap.
    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
+   GitHub review thread. Before its turn ends, the edit step dry-runs the
+   CODE_RULES commit gate (`code_rules_gate.py --staged`) over its staged
+   changes and keeps fixing until that gate would accept the commit, so the
+   later commit step never hits a gate rejection. 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

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

@@ -457,3 +457,93 @@ test('both standards-deferral call sites build standardsNote from the spawnStand
     'expected no unconditional hardening-PR claim in standardsNote',
   );
 });
+
+test('a reuse-audit lens builder exists', () => {
+  assert.match(convergeSource, /function runReuseAuditPass\(/);
+});
+
+test('the reuse pass runs once before the convergence loop', () => {
+  const reuseCallIndex = convergeSource.indexOf('await runReuseAuditPass(');
+  const loopIndex = convergeSource.indexOf('while (iterations < CONFIG.maxIterations)');
+  assert.notEqual(reuseCallIndex, -1, 'expected the reuse pass to be invoked');
+  assert.notEqual(loopIndex, -1, 'expected the convergence loop to exist');
+  assert.ok(
+    reuseCallIndex < loopIndex,
+    'expected the reuse pass to run before the convergence loop starts',
+  );
+});
+
+test('the reuse lens prompt enumerates all three qualifying criteria and an omit rule', () => {
+  const reusePrompt = lensPromptBody('runReuseAuditPass');
+  assert.match(reusePrompt, /CERTAIN/);
+  assert.match(reusePrompt, /BEHAVIORALLY IDENTICAL/);
+  assert.match(reusePrompt, /AUTONOMOUSLY IMPLEMENTABLE/);
+  assert.match(
+    reusePrompt,
+    /when any one is in doubt, omit the finding/i,
+    'expected the reuse lens to drop any finding that fails a criterion',
+  );
+});
+
+test('the reuse lens reviews the full diff and does not edit', () => {
+  const reusePrompt = lensPromptBody('runReuseAuditPass');
+  assert.match(reusePrompt, /origin\/main\.\.\.HEAD/);
+  assert.match(
+    reusePrompt,
+    /Do NOT edit, commit, or push/,
+    'expected the reuse lens to report findings without editing',
+  );
+});
+
+test('the reuse pass applies its findings through applyFixes, not the standards-deferral path', () => {
+  const reuseCallIndex = convergeSource.indexOf('await runReuseAuditPass(');
+  const loopIndex = convergeSource.indexOf('while (iterations < CONFIG.maxIterations)');
+  const reuseBlock = convergeSource.slice(reuseCallIndex, loopIndex);
+  assert.match(
+    reuseBlock,
+    /applyFixes\(reuseHead, reuseFindings, 'reuse-pass'\)/,
+    'expected the reuse pass to apply its findings via applyFixes',
+  );
+  assert.doesNotMatch(
+    reuseBlock,
+    /spawnStandardsFollowUp/,
+    'expected the reuse pass to apply improvements, not defer them',
+  );
+});
+
+test('the reuse lens runs under the Reuse phase', () => {
+  const reusePrompt = lensPromptBody('runReuseAuditPass');
+  assert.match(reusePrompt, /phase: 'Reuse'/);
+});
+
+test('the pre-commit gate step is a shared constant that dry-runs the CODE_RULES commit gate', () => {
+  assert.match(convergeSource, /const PRE_COMMIT_GATE_STEP =/);
+  const stepStart = convergeSource.indexOf('const PRE_COMMIT_GATE_STEP =');
+  const stepEnd = convergeSource.indexOf('\n\n', stepStart);
+  const stepBody = convergeSource.slice(stepStart, stepEnd);
+  assert.match(stepBody, /code_rules_gate\.py/);
+  assert.match(stepBody, /--staged/);
+  assert.match(
+    stepBody,
+    /do NOT commit/i,
+    'expected the gate step to forbid committing — it is a dry committability check',
+  );
+});
+
+const editStepBuilders = [
+  'applyFixesEdit',
+  'recoverCommitBlockEdit',
+  'recoverVerifyFailEdit',
+  'repairConvergenceEdit',
+  'standardsFollowUpEdit',
+];
+
+for (const builderName of editStepBuilders) {
+  test(`${builderName} appends the pre-commit gate step to its edit prompt`, () => {
+    assert.match(
+      lensPromptBody(builderName),
+      /\+\s*PRE_COMMIT_GATE_STEP/,
+      `expected ${builderName} to append PRE_COMMIT_GATE_STEP`,
+    );
+  });
+}

package/skills/autoconverge/workflow/converge.merge-conflict.test.mjs

@@ -0,0 +1,98 @@
+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 nextFunctionMatch = /\n(?:async )?function /.exec(convergeSource.slice(functionStart + 1));
+  const functionEnd =
+    nextFunctionMatch === null ? convergeSource.length : functionStart + 1 + nextFunctionMatch.index;
+  return convergeSource.slice(functionStart, functionEnd);
+}
+
+const helperModule = new Function(
+  `${functionBody('isMergeConflicting')}\nreturn { isMergeConflicting };`,
+)();
+const { isMergeConflicting } = helperModule;
+
+test('isMergeConflicting treats a dead check agent (null/undefined) as not conflicting', () => {
+  assert.equal(isMergeConflicting(null), false);
+  assert.equal(isMergeConflicting(undefined), false);
+});
+
+test('isMergeConflicting reports a conflict only when the check returned conflicting:true', () => {
+  assert.equal(isMergeConflicting({ conflicting: true }), true);
+  assert.equal(isMergeConflicting({ conflicting: false }), false);
+});
+
+test('checkMergeConflicts is a read-only mergeability probe that polls until GitHub computes it', () => {
+  const body = functionBody('checkMergeConflicts');
+  assert.match(body, /mergeable/, 'expected the probe to read the PR mergeable field');
+  assert.match(
+    body,
+    /do not edit, commit, push, or rebase|read only/i,
+    'expected the probe to be read-only',
+  );
+  assert.match(body, /agentType:\s*'Explore'/, 'expected the probe to use the read-only Explore agent');
+  assert.match(body, /schema:\s*MERGE_CONFLICT_SCHEMA/, 'expected the probe to return MERGE_CONFLICT_SCHEMA');
+  assert.match(body, /null/, 'expected the probe to handle GitHub returning mergeable:null while it computes');
+  assert.match(body, /sleep 5|Start-Sleep/, 'expected a shell-agnostic poll delay');
+});
+
+test('resolveConflictsEdit rebases onto origin/main and makes no push', () => {
+  const body = functionBody('resolveConflictsEdit');
+  assert.match(body, /git rebase origin\/main/, 'expected the edit step to rebase onto origin/main');
+  assert.match(
+    body,
+    /do not push|no push|not push/i,
+    'expected the edit step to leave the push to the commit step',
+  );
+  assert.match(body, /agentType:\s*'clean-coder'/, 'expected the edit step to use clean-coder');
+});
+
+test('resolveMergeConflicts runs check -> edit -> verify -> commit and gates the push on the verdict', () => {
+  const body = functionBody('resolveMergeConflicts');
+  const checkIndex = body.indexOf('checkMergeConflicts(');
+  const editIndex = body.indexOf('resolveConflictsEdit(');
+  const verifyIndex = body.indexOf('verifyRepairChanges(');
+  const commitIndex = body.indexOf('commitRepairFixes(');
+  assert.notEqual(checkIndex, -1, 'expected the conflict check to run');
+  assert.notEqual(editIndex, -1, 'expected the rebase edit step to run');
+  assert.notEqual(verifyIndex, -1, 'expected the verify step to run');
+  assert.notEqual(commitIndex, -1, 'expected the commit step to run');
+  assert.ok(
+    checkIndex < editIndex && editIndex < verifyIndex && verifyIndex < commitIndex,
+    'expected the order check -> edit -> verify -> commit',
+  );
+  assert.match(body, /verdictPassed\(/, 'expected the verifier verdict to gate the force-push');
+  assert.match(
+    body,
+    /commitRepairFixes\(head,\s*true\)/,
+    'expected the commit to force-with-lease (wasRebased=true) after a rebase',
+  );
+});
+
+test('resolveMergeConflicts rebases only when the check reports a conflict', () => {
+  const body = functionBody('resolveMergeConflicts');
+  assert.match(body, /isMergeConflicting\(/, 'expected the orchestrator to branch on the conflict decision');
+  assert.match(
+    body,
+    /if \(!isMergeConflicting\([^)]*\)\) return head/,
+    'expected a clean PR to return the unchanged HEAD without rebasing',
+  );
+});
+
+test('the merge-conflict pre-flight runs once before the round loop, ahead of the parallel bug-check lenses', () => {
+  const preflightCall = convergeSource.indexOf('await resolveMergeConflicts(');
+  const whileLoop = convergeSource.indexOf('while (iterations < CONFIG.maxIterations)');
+  const firstLens = convergeSource.indexOf('const lenses = await parallel(');
+  assert.notEqual(preflightCall, -1, 'expected the pre-flight resolveMergeConflicts call site');
+  assert.ok(preflightCall < whileLoop, 'expected the pre-flight to run before the round loop');
+  assert.ok(preflightCall < firstLens, 'expected the pre-flight to run before the first bug-check lenses');
+});