claude-dev-env 1.92.1 → 1.93.0

package/skills/autoconverge/SKILL.md

@@ -1,13 +1,12 @@
 ---
 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'.
+  Drives one draft PR to convergence in one autonomous run: a deterministic static
+  sweep, then code review, bug audit, and self-review on one HEAD, all fixes in one
+  commit, then Bugbot and Copilot as terminal confirmation gates before 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
@@ -46,6 +45,19 @@ Scan the tool list at the top of this conversation for the literal string
 aborting` and stop. The workflow also needs the `gh` CLI authenticated for the
 PR's owner.
 
+## Transport check (before any GitHub step)
+
+Run `command -v gh`; when it succeeds, run `gh auth status`; once the PR
+scope is resolved, run `gh api repos/<owner>/<repo> --jq .permissions.push`
+and take `true` as the pass. When any check fails, run the
+`pr-loop-cloud-transport` skill first and route every `gh` operation in this
+skill through its substitution matrix. The workflow script
+(`workflow/converge.mjs`) embeds `gh` commands and gh-backed helper scripts in
+its agent prompts, so a cloud run also applies the same substitution to those
+agent prompts when it authors the launch — the transport skill covers the
+orchestrating session's own steps, and the script's agent-prompt text carries
+`gh` calls the spawned agents cannot run in a cloud session.
+
 ## Pre-flight (main session)
 
 1. **Enter a worktree.** Call `EnterWorktree` with no arguments before any
@@ -80,7 +92,7 @@ PR's owner.
    enter the branch worktree. A non-zero exit prints a `PREFLIGHT_OUTCOME` line
    and an `ABORT` line: report that line and stop. Autoconverge runs inside the
    PR's own repo, so a working directory rooted in a different repo (for
-   example, `claude-code-config` while the PR lives in `llm-settings`) or in no
+   example, `claude-dev-env` while the PR lives in `llm-settings`) or in no
    git checkout at all cannot continue.
 
 4. **Grant project permissions.** Apply the `pr-loop-lifecycle` skill's Open
@@ -129,13 +141,40 @@ Write it again when the result lands, so the handoff carries the final run id an
 names the teardown phase the fresh session picks up from.
 
 The workflow returns
-`{ converged, rounds, finalSha, blocker, standardsNote, copilotNote, reuseNote, deferredPrs }`.
+`{ converged, rounds, finalSha, blocker, standardsNote, copilotNote, reuseNote, deferredPrs }`,
+plus a `userReview` field on a `blocker: "user-review"` return.
 `deferredPrs` is the list of draft environment-hardening PRs the standards-deferral
 path opened this run, each as `{ owner, repo, prNumber, copilotDisabled, bugbotDisabled }`.
 The two flags carry this run's Copilot and Bugbot availability, so the next generation
 skips a reviewer that is down or out of quota without re-probing. This list is the seed the
 [self-closing loop](#self-closing-loop-converge-the-deferred-prs) converges next.
 
+## Copilot findings — two-tier triage
+
+The Copilot gate tiers each finding it surfaces. A **self-healing** finding is
+pure style, type hints, misplaced or unused imports, formatting, magic-value
+extraction, a test-only change, a doc-or-description vs code mismatch, or code
+de-duplication — a fix that cannot change observable runtime behavior for
+production callers. Self-healing findings flow into the fix round and count
+toward convergence, with no user notification.
+
+A **code-concern** finding is behavior-changing or needs a product decision:
+logic or correctness, security, data handling, error-handling semantics, or
+concurrency. Copilot tiers a finding as code-concern whenever the tier is in
+doubt. When one or more code-concern findings land, the workflow neither
+auto-fixes them nor marks the PR ready. It returns `converged: false`,
+`blocker: "user-review"`, and a `userReview` field carrying
+`{ reviewUrl, findings: [{ file, line, severity, tier, title }] }`.
+
+A background workflow cannot hold for a human, so the wait belongs to the
+orchestrating session. On a `blocker: "user-review"` return, run the
+[`copilot-finding-triage`](../copilot-finding-triage/SKILL.md) skill: send the
+ntfy notification (the finding summary plus the `reviewUrl` Copilot review link),
+then hold with a 45-minute `ScheduleWakeup` for the user's response. When the
+user answers within the window, follow their direction. When the window closes
+with no response, run normal teardown and report the code-concern findings
+un-reviewed.
+
 ## Budget-aware round boundaries
 
 The workflow's `budget` API is the pacing signal: when a usage target is
@@ -173,6 +212,25 @@ On teardown entry, when `~/.claude/runtime/pr-loop/bugteam-pr-<N>/handoff.json`
 exists, read its `completed_steps` and skip any checkpoint the list already
 names, so a resumed run performs only the checkpoints left.
 
+On a `blocker: "user-review"` return, run the
+[`copilot-finding-triage`](../copilot-finding-triage/SKILL.md) gate before
+teardown: send the ntfy alert with the finding summary and the
+`userReview.reviewUrl` link, then hold with a 45-minute `ScheduleWakeup`. Act on
+the user's direction when it arrives inside the window; when the window closes
+with no response, fall through to normal teardown and report the
+`userReview.findings` un-reviewed. The PR stays a draft in this path — the
+workflow marked nothing ready.
+
+Before the checkpoints, when the workflow returned a non-null `copilotNote`
+(the Copilot gate was bypassed), query the PR's reviews once more for a
+`copilot-pull-request-reviewer[bot]` review on the final HEAD
+(`fetch_copilot_reviews.py`, or the GitHub MCP `pull_request_read` method
+`get_reviews`). Copilot typically posts within 10–15 minutes of a request, so
+a review can land between the bypass and teardown. When one exists and
+carries findings, mark the PR draft, route the findings through one fix
+round per the `pr-fix-protocol` skill, re-verify, push, and mark the PR
+ready again — then run the checkpoints.
+
 1. **When `converged` is true — build and publish the closing report.**
    Skip this entire step (report, artifact publish, comment, Chrome open) when the
    workflow returned a non-null `blocker`. Per-round live-dashboard refresh is out of
@@ -300,9 +358,13 @@ Every agent prompt carries a headless-safety preamble: the run is unattended, so
 agents never inline a destructive-command literal (`rm -rf`, `git reset --hard`,
 `dd`) into a Bash command — the `destructive_command_blocker` hook matches those
 patterns as raw text, and a confirmation prompt no human can answer would stall
-the run. Agents verify destructive-blocker behavior through the committed test
-suite (`python -m pytest`) and keep scratch work in the OS temp dir. The preamble
-describes the narrowest rm auto-allow path — a standalone Bash call whose target
+the run. The preamble has two forms. Read-only agents — the review, verify, and
+utility spawns that edit nothing — receive a trimmed form that drops the rm-shape
+rules, since a read-only agent never runs `rm`. Edit agents — the fix and commit
+spawns — receive the full form that carries the rm-shape rules described below.
+Agents verify destructive-blocker behavior through the committed test
+suite (`python -m pytest`) and keep scratch work in the OS temp dir. The full
+preamble describes the narrowest rm auto-allow path — a standalone Bash call whose target
 resolves inside the ephemeral namespace (`/tmp`, `/temp`, the OS temp root, or the
 run worktree) — and a compound path that accepts an rm joined with benign
 reporting segments when every rm target is an absolute ephemeral path. Both of
@@ -323,36 +385,52 @@ helper file and run it as `python <file>.py` — keeping every destructive liter
 out of a Bash command string entirely and independent of which auto-allow path
 matches.
 
-- **Converge:** `parallel([Bugbot lens, code-review lens, bug-audit lens])` on
-  the current HEAD, full `origin/main...HEAD` diff. The preflight step fetches
-  `origin/main` once for the round and enumerates the diff (changed-file list plus
-  diffstat); each lens receives that list and reads only the files it needs rather
-  than re-deriving the diff, forming its own review judgment. Dedup findings; one
-  `clean-coder` applies the round's fixes per the `pr-fix-protocol` skill
-  (`../pr-fix-protocol/SKILL.md`) — fix, reply, resolve — landing every fix in
-  one commit per round, which the workflow journal records; 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.
+- **Static sweep:** each round opens with a deterministic static-sweep lens that
+  runs the CODE_RULES gate (`code_rules_gate.py --base origin/main`), `ruff`,
+  `mypy`, and stem-matched `pytest` over the changed files. Any failure routes
+  through the same fix flow and the round re-runs, so the reading lenses only ever
+  review sweep-clean code. The sweep uses local commands only, so it runs in any
+  session.
+- **Converge:** `parallel([code-review lens, bug-audit lens, self-review lens])`
+  on the current HEAD, full `origin/main...HEAD` diff. The bug-audit lens applies
+  the A-P rubric and then its adversarial second pass; the self-review lens covers
+  the doc-vs-code parity, test-assertion completeness, and PR-description-vs-diff
+  parity lanes. The preflight step fetches `origin/main` once for the round and
+  enumerates the diff (changed-file list plus diffstat); each lens receives that
+  list and reads only the files it needs rather than re-deriving the diff, forming
+  its own review judgment. Dedup findings; one `clean-coder` applies the round's
+  fixes per the `pr-fix-protocol` skill (`../pr-fix-protocol/SKILL.md`) — fix,
+  reply, resolve — landing every fix in one commit per round, which the workflow
+  journal records; 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 internal
+  lenses 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
   (hooks/rules that block those violation classes at Write/Edit time), resolves
   any bot threads with a deferral note, and reports the deferral in
   `standardsNote`.
-- **Copilot gate:** request a Copilot review, poll up to the configured cap; findings
-  route back into Converge. When Copilot is down or out of quota — it posts an
-  out-of-usage notice (the requester hit their quota) on the HEAD, or surfaces no
-  review at all after the configured cap — the gate logs a notice and the run marks the PR
-  ready with the Copilot gate bypassed. `copilotNote` records the bypass.
+- **Bugbot gate:** the terminal Cursor Bugbot confirmation gate runs once the
+  internal lenses are clean. When Bugbot is disabled or opted out for the run (the
+  default) or unreachable, the gate spawns no agent and passes straight to the
+  Copilot gate. Otherwise it fetches Bugbot's verdict on the HEAD; findings route
+  back into Converge, and a clean verdict advances to the Copilot gate.
+- **Copilot gate:** the terminal GitHub Copilot confirmation gate. Request a
+  Copilot review, poll up to the configured cap; findings route back into
+  Converge. When Copilot is down or out of quota — it posts an out-of-usage notice
+  (the requester hit their quota) on the HEAD, or surfaces no review at all after
+  the configured cap — the gate logs a notice and the run marks the PR ready with
+  the Copilot gate bypassed. `copilotNote` records the bypass.
 - **Convergence check:** `check_convergence.py` is the authoritative gate; one
   agent runs it and, on a full pass, marks `draft=false` in the same turn. Each
-  spawned agent runs on the model tier its role needs — opus/medium for the review
-  lenses and the code-editing fix steps, sonnet/medium for the verify, commit, and
-  recovery steps, haiku/low for the mechanical probes (preflight, Copilot gate,
-  CLEAN-audit post, convergence check).
+  spawned agent runs on the model tier its role needs — sonnet/medium for the
+  deterministic static sweep, opus/medium for the code-review, bug-audit,
+  self-review, reuse, and terminal Bugbot lenses and the code-editing fix steps,
+  sonnet/medium for the verify, commit, and recovery steps, and haiku/low for the
+  mechanical probes (preflight, Copilot gate, CLEAN-audit post, convergence
+  check).
 
 ## Multiple PRs
 
@@ -471,7 +549,7 @@ so there is nothing to converge. Report that and stop.
 Given a non-empty list of deferred PRs `{ owner, repo, prNumber, copilotDisabled, bugbotDisabled }`
 (a generation may span more than one repository — a hardening PR lands in whichever repo owns
 the surface that blocks the deferred class, so `JonEcho/llm-settings` for hooks
-and `jl-cmd/claude-code-config` for rules and skills both appear):
+and `jl-cmd/claude-dev-env` for rules and skills both appear):
 
 1. **Check out each deferred PR.** Run the
    [Multi-PR pre-flight](#multi-pr-pre-flight-main-session) once per deferred PR.

package/skills/autoconverge/reference/CLAUDE.md

@@ -6,7 +6,7 @@ Reference documentation for the `autoconverge` skill. The `converge.mjs` workflo
 
 | File | Role |
 |---|---|
-| `convergence.md` | Round shape: the three parallel lenses (Bugbot, code-review, bug-audit), deduplication, the fix commit step, and the definition of a clean convergence. |
-| `stop-conditions.md` | Every condition that ends the run short of ready: budget cap, iteration cap, blocker exit, Copilot bypass. |
+| `convergence.md` | Round shape: the static sweep, the three parallel internal lenses (code-review, bug-audit, self-review), deduplication, the fix commit step, the terminal Bugbot and Copilot gates, and the definition of a clean convergence. |
+| `stop-conditions.md` | Every condition that ends the run short of ready: budget cap, iteration cap, blocker exit, static-sweep stall, Bugbot and Copilot bypass. |
 | `gotchas.md` | Hard-won lessons from failed runs: PR title validation, conflicting PRs, worktree branch lock, resumed sessions rerooting, and minter issues. |
 | `closing-report.md` | Specification for the closing HTML convergence report the teardown step builds and publishes. |

package/skills/autoconverge/reference/convergence.md

@@ -39,34 +39,45 @@ any improvement that did not land.
 
 ## The round loop
 
-The workflow holds three states and moves between them until the PR is ready or
+The workflow holds four 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.
+tracks CONVERGE passes only and is never the cap. The internal lenses drive the
+code to clean first; the external reviewers run only after that, as terminal
+confirmation gates that are expected to return zero.
 
-**CONVERGE** (one round = one parallel sweep):
+**CONVERGE** (one round = a static sweep then one parallel lens sweep):
 
 1. Resolve the current PR HEAD SHA. The same preflight step also fetches
    `origin/main` once for the round and enumerates the diff — the
    `git diff --name-status origin/main...HEAD` changed-file list and the
    `git diff --stat` diffstat — and carries both into the round.
-2. Run three lenses in parallel on that HEAD, each over the full
+2. Run the **static-sweep lens** on that HEAD: a deterministic pass that runs the
+   CODE_RULES gate (`code_rules_gate.py --base origin/main`), `ruff`, `mypy`, and
+   stem-matched `pytest` over the changed files, mapping each failure to a
+   finding. It uses local commands only, so it runs in any session. When the sweep
+   raises a finding, one `clean-coder` fixes it through the same fix flow below and
+   the round re-runs, so the reading lenses only ever review sweep-clean code.
+3. Run three reading lenses in parallel on that HEAD, each over the full
    `origin/main...HEAD` diff. Each lens receives the preflight's changed-file
    list and diffstat and reads only the files it needs from that list rather than
    re-deriving the diff; each lens forms its own review judgment.
-   - **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 `_shared/pr-loop/audit-contract.md`, reporting
+     shared A–P rubric from `_shared/pr-loop/audit-contract.md`, then its
+     adversarial second pass, and the doc-parity, test-assertion, and
+     PR-description lanes from `_shared/pr-loop/precatch-rubric.md`, reporting
      findings without editing.
-3. Dedup findings across the three lenses by file, line, and title. A collision
+   - **Self-review lens** — the semantic parity pass (`code-quality-agent`) that
+     reads `_shared/pr-loop/precatch-rubric.md` and covers doc-vs-code parity,
+     test-assertion completeness, and PR-description-vs-diff parity, reporting
+     findings without editing.
+4. 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 per the
+5. **Any findings** → one `clean-coder` applies every fix per the
    `pr-fix-protocol` skill (`../../pr-fix-protocol/SKILL.md`): a single
    test-first commit, a push, then a reply and resolve on each finding that
    carries a GitHub review thread. Before its turn ends, the edit step dry-runs
@@ -79,10 +90,22 @@ tracks CONVERGE passes only and is never the cap.
    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.
+6. **Zero findings on a stable HEAD** → post the CLEAN bugteam audit artifact
+   for that HEAD, then move to the terminal Bugbot gate.
+
+**BUGBOT** gate (terminal external confirmation):
+
+- Runs once the internal lenses are clean. When Bugbot is off for the run — the
+  default unless `CLAUDE_REVIEWS_ENABLED` lists `bugbot` — opted out via
+  `CLAUDE_REVIEWS_DISABLED`, or unreachable, the gate spawns no agent and moves
+  to the Copilot gate with `bugbotDown` set.
+- Otherwise drive Cursor Bugbot to a verdict on HEAD (trigger and poll its CI
+  check run when needed).
+- Bugbot findings → fix them and return to CONVERGE on the new HEAD.
+- Bugbot clean or approved → move to the Copilot gate.
+- Bugbot down after the poll cap → move to the Copilot gate with `bugbotDown` set.
 
-**COPILOT** gate:
+**COPILOT** gate (terminal external confirmation):
 
 - Request a Copilot review on HEAD (skipping a duplicate request), then poll up
   to the configured cap, 360 seconds apart.
@@ -104,14 +127,11 @@ tracks CONVERGE passes only and is never the cap.
 Each spawned agent runs on the model and effort its role needs, so the run spends
 the strongest model only where judgment is dense:
 
-- **opus / medium** — the review lenses (Bugbot, code-review, bug-audit, reuse)
-  and the code-editing steps that fix findings (fix-edit, conflict-edit,
-  repair-edit, standards-edit).
-- **sonnet / medium** — the verify steps, the commit steps, and the recovery
-  edits that clear a commit-gate or verdict rejection.
-- **haiku / low** — the mechanical steps: the preflight git-and-availability
-  probe, the Copilot gate, the CLEAN-audit post, and the convergence check that
-  marks the PR ready.
+- **sonnet** — the deterministic static-sweep lens, and the verify,
+  commit, and recovery steps that clear a commit-gate or verdict rejection.
+- **opus** — the reading lenses (code-review, bug-audit, self-review,
+  reuse), the terminal Bugbot gate, and the code-editing steps that fix findings
+  (fix-edit, conflict-edit, repair-edit, standards-edit).
 
 ## Full-diff rule
 
@@ -126,7 +146,9 @@ every condition from GitHub and marks the PR ready only when all of these hold o
 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).
+   (bypassed when Bugbot is off for the run — the default unless
+   `CLAUDE_REVIEWS_ENABLED` lists `bugbot` — opted out via
+   `CLAUDE_REVIEWS_DISABLED`, 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.

package/skills/autoconverge/reference/gotchas.md

@@ -60,3 +60,14 @@ fails in a new way.
   own. When landing a fix needs it, stop and tell the user the verified-commit
   gate is blocking the push and that going forward needs either a `# verify-skip`
   bypass or a switch to `/pr-converge`, then let the user decide.
+
+- **A Copilot "down" verdict is valid only after the full poll budget.** A
+  successful review request means the review is in flight — Copilot typically
+  posts within 10–15 minutes of the request. A gate agent that returns
+  `down:true` on a partial poll misreports an in-flight review as reviewer
+  unavailability, and the run marks the PR ready moments before the review
+  lands. After a successful request the only valid gate outcomes are a
+  received review on HEAD, an out-of-usage notice, or the full poll budget
+  spent. The teardown re-checks the PR for a late-arriving Copilot review
+  whenever the gate was bypassed, and routes its findings through one more
+  fix round.

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

@@ -26,7 +26,13 @@ skill still runs teardown (revoke permissions, final report).
   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.
+  reaches the terminal Bugbot, Copilot, and convergence gates.
+- **Static-sweep stalled** — the deterministic static sweep (`code_rules_gate.py
+  --base origin/main`, `ruff`, `mypy`, stem-matched `pytest`) raises gate or test
+  failures the fixer cannot clear on the current HEAD, so HEAD does not move. The
+  reading lenses never run on a sweep-dirty HEAD, so the run ends with a
+  static-sweep stall `blocker` naming the failure count and the stalled HEAD
+  rather than looping to the iteration cap.
 - **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`;
@@ -55,8 +61,12 @@ skill still runs teardown (revoke permissions, final report).
 
 ## 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`.
+- **Terminal Bugbot gate down or disabled** — the terminal Bugbot gate runs once
+  the internal lenses are clean. When Cursor Bugbot is off for the run (the
+  default unless `CLAUDE_REVIEWS_ENABLED` lists `bugbot`) or opted out via
+  `CLAUDE_REVIEWS_DISABLED`, the gate spawns no agent and passes to the Copilot
+  gate with `bugbotDown` set. When Bugbot is enabled but never produces a check
+  run or review after the gate poll budget, the gate returns down the same way.
   The run continues, and the convergence check runs with `--bugbot-down` so its
   Bugbot gate is bypassed.
 - **Copilot down or out of quota** — when Copilot posts an out-of-usage notice on
@@ -66,16 +76,16 @@ skill still runs teardown (revoke permissions, final report).
   check with `--copilot-down` (the Copilot review gate and the
   pending-requested-reviews gate bypassed), and marks the PR ready. `copilotNote`
   records the bypass for the final report.
-- **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 (a single round)** — 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. This is a
+- **A lens agent dies** — when one parallel reading 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
+  terminal Bugbot gate agent (null result) is a retry rather than an approval, so
+  the gate re-runs on the same HEAD rather than treating a dead agent as a clean
+  Bugbot verdict.
+- **Every lens agent dies (a single round)** — when all three parallel reading
+  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 terminal
+  gates. It re-resolves HEAD and retries on the next round. This is a
   no-lens-reviewed round, so consecutive occurrences are bounded by the
   no-review-lens cap in the blockers above, not just the iteration cap.
 

package/skills/autoconverge/workflow/CLAUDE.md

@@ -6,7 +6,7 @@ Workflow scripts and report utilities for the `autoconverge` skill.
 
 | File | Role |
 |---|---|
-| `converge.mjs` | Main convergence workflow script. Each round runs Bugbot, code-review, and bug-audit lenses in parallel, deduplicates findings, applies fixes, pushes, gates on Copilot, checks convergence, and marks the PR ready. Runs via the `Workflow` tool — not directly with Node. |
+| `converge.mjs` | Main convergence workflow script. Each round runs a deterministic static sweep first, then code-review, bug-audit, and self-review lenses in parallel, deduplicates findings, applies fixes, and pushes; Bugbot and Copilot then run as terminal confirmation gates before it checks convergence and marks the PR ready. Runs via the `Workflow` tool — not directly with Node. |
 | `aggregate_runs.py` | Merges every autoconverge journal for a given PR (matched by run id) into one merged journal. Prints a JSON line with `mergedJournal`, `roundCount`, `finalSha`, and `findingCount`. |
 | `convergence_summary.py` | Builds the convergence-summary agent prompt over the merged journal's findings. The teardown step spawns a `general-purpose` subagent on this prompt. |
 | `render_report.py` | Builds the closing HTML insights report. Takes `--journal`, `--summary-file`, `--out`, `--pr`, `--final-sha`, and `--rounds`. Writes the HTML to `--out` and prints the output path on stdout. |
@@ -14,6 +14,7 @@ Workflow scripts and report utilities for the `autoconverge` skill.
 | `converge.contract.test.mjs` | Contract tests for `converge.mjs` — verify the workflow interface and step ordering. |
 | `converge.clean-audit.test.mjs` | Tests the clean-audit path (all lenses clean on first round). |
 | `converge.copilot-gate.test.mjs` | Tests Copilot gate behavior (bypass on quota exhaustion). |
+| `converge.precatch.test.mjs` | Tests the pre-catch stage: static-sweep ordering and gate coverage, the adversarial second pass, the self-review lens, the terminal Bugbot gate, the read-only/edit preamble split, and the commit-recovery cap. |
 | `converge.fix-progress.test.mjs` | Tests fix-progress tracking across rounds. |
 | `converge.fix-recovery.test.mjs` | Tests recovery when a fix commit fails. |
 | `converge.run-input.test.mjs` | Tests workflow input validation. |

package/skills/autoconverge/workflow/converge.clean-audit.test.mjs

@@ -53,7 +53,7 @@ const {
 
 function buildRunGeneralUtilityTask(convergeAgentStub) {
   const factory = new Function(
-    'convergeAgent',
+    'convergeReadOnlyAgent',
     'input',
     'CONFIG',
     'prCoordinates',
@@ -122,7 +122,7 @@ test('nameLensResults classifies a not-spawned stub, a dead agent, and a ran len
   assert.equal(namedLenses[2].status, 'ran');
   assert.equal(namedLenses[2].report, auditReport);
   const allLensNames = namedLenses.map((eachEntry) => eachEntry.lens);
-  assert.deepEqual(allLensNames, ['Cursor Bugbot', 'code-review', 'bug-audit']);
+  assert.deepEqual(allLensNames, ['code-review', 'bug-audit', 'self-review']);
 });
 
 test('nameLensResults tags a down lens reported-down only with zero findings, and ran when it produced findings', () => {
@@ -145,10 +145,10 @@ test('nameLensResults tags a down lens reported-down only with zero findings, an
 
 test('describeNotRunLens words each not-run status without claiming a review or asserting a poll or timeout', () => {
   assert.match(
-    describeNotRunLens({ lens: 'Cursor Bugbot', status: 'down' }),
+    describeNotRunLens({ lens: 'self-review', status: 'down' }),
     /down\/disabled — did not run/,
   );
-  const reportedDownClause = describeNotRunLens({ lens: 'Cursor Bugbot', status: 'reported-down' });
+  const reportedDownClause = describeNotRunLens({ lens: 'self-review', status: 'reported-down' });
   assert.match(reportedDownClause, /reported itself down/);
   assert.match(reportedDownClause, /produced no review for this HEAD/);
   assert.doesNotMatch(reportedDownClause, /poll|timeout/i);
@@ -194,7 +194,7 @@ test('the standards-only branch reaches the deferral filing without a zero-ran g
 test('the all-clean zero-ran retry is inlined, registers a no-lens round, and the shared helper is gone', () => {
   const allCleanBranch = convergeSource.slice(
     convergeSource.indexOf('all lenses clean on'),
-    convergeSource.indexOf("if (phase === 'COPILOT') {"),
+    convergeSource.indexOf("if (phase === 'BUGBOT') {"),
   );
   assert.match(allCleanBranch, /if \(auditResult\?\.noLensRan\)/);
   assert.match(allCleanBranch, /registerNoLensRound\(noLensRoundCausesFor\(allCleanNamedLenses\)\)/);
@@ -209,7 +209,7 @@ test('every no-lens-reviewed round registers one shared counter and every lens-r
   const registerSites = loopBody.match(/registerNoLensRound\(/g) || [];
   assert.equal(registerSites.length, 3, 'expected the preflight-no-SHA, all-lenses-dead, and no-lens-ran rounds to register');
   const resetSites = loopBody.match(/resetNoLensRounds\(\)/g) || [];
-  assert.equal(resetSites.length, 4, 'expected a reset on the standards, findings, not-clean, and posted lens-ran rounds');
+  assert.equal(resetSites.length, 5, 'expected a reset on the static-sweep, standards, findings, not-clean, and posted lens-ran rounds');
   const deadBranch = convergeSource.slice(
     convergeSource.indexOf('if (roundOutcome.allLensesDead) {'),
     convergeSource.indexOf('const findings = roundOutcome.findings'),
@@ -554,14 +554,19 @@ test('the standards-only call site relays lens provenance, the deferred standard
   assert.match(buildBody, /hardeningPrOpened: wasStandardsHardeningPrOpened/);
 });
 
-test('both standardsDeferralNote call sites pass the shared deferral state with no legacy argument', () => {
+test('every standardsDeferralNote call site passes the shared deferral state with no legacy argument', () => {
   const noteCalls = convergeSource.match(/standardsNote = standardsDeferralNote\([^\n]*/g) || [];
-  assert.equal(noteCalls.length, 2);
+  assert.equal(noteCalls.length, 3);
   assert.equal(
     noteCalls.filter((eachCall) => /standardsDeferralNote\(findings\.length, standardsDeferral\)/.test(eachCall)).length,
     1,
     'expected the converge call site to pass the standardsDeferral local built from buildStandardsDeferral()',
   );
+  assert.equal(
+    noteCalls.filter((eachCall) => /standardsDeferralNote\(bugbotOutcome\.findings\.length, buildStandardsDeferral\(\)\)/.test(eachCall)).length,
+    1,
+    'expected the terminal-Bugbot call site to pass buildStandardsDeferral() inline',
+  );
   assert.equal(
     noteCalls.filter((eachCall) => /standardsDeferralNote\(copilotOutcome\.findings\.length, buildStandardsDeferral\(\)\)/.test(eachCall)).length,
     1,
@@ -573,19 +578,10 @@ test('both standardsDeferralNote call sites pass the shared deferral state with
   assert.doesNotMatch(convergeSource, /buildStandardsDeferral\(standardsOutcome\)/);
 });
 
-test('the parallel lens spawn marks the workflow-synthesized Bugbot down-stub as not-spawned', () => {
-  const spawnRegion = convergeSource.slice(
-    convergeSource.indexOf('const lenses = await parallel(['),
-    convergeSource.indexOf('bugbotDown = lenses[0]'),
-  );
-  assert.match(spawnRegion, /isBugbotDownPreSpawn \?/);
-  assert.match(spawnRegion, /notSpawned: true/);
-});
-
 test('the all-clean call site breaks with a clean-audit blocker when the post does not land', () => {
   const branch = convergeSource.slice(
     convergeSource.indexOf('all lenses clean on'),
-    convergeSource.indexOf("if (phase === 'COPILOT') {"),
+    convergeSource.indexOf("if (phase === 'BUGBOT') {"),
   );
   assert.match(branch, /runGeneralUtilityTask\(.*'post-clean-audit'/);
   assert.match(branch, /if \(!auditResult\?\.posted\)/);
@@ -596,7 +592,7 @@ test('the all-clean call site breaks with a clean-audit blocker when the post do
 test('the all-clean call site relays lens provenance into the post-clean-audit context without a postFindings field', () => {
   const branch = convergeSource.slice(
     convergeSource.indexOf('all lenses clean on'),
-    convergeSource.indexOf("if (phase === 'COPILOT') {"),
+    convergeSource.indexOf("if (phase === 'BUGBOT') {"),
   );
   assert.match(branch, /const allCleanNamedLenses = nameLensResults\(lenses\)/);
   assert.match(branch, /lensResults: allCleanNamedLenses/);