claude-dev-env 1.82.0 → 1.84.0

package/rules/verify-runtime-state.md

@@ -0,0 +1,40 @@
+# Verify Runtime State
+
+**When this applies:** Before stating that a component is fine, healthy, not at fault, or working — during debugging, triage, or any judgment about whether something runs.
+
+## Rule
+
+A verdict that a component is fine or not the cause rests on live evidence gathered this session: a process list, a port probe, a log tail, an HTTP status code, or a fresh repro. Reading the code, recalling how the component behaved earlier, or trusting a prior session's finding does not settle whether it runs right now. Code shows what should happen; only a live probe shows what does.
+
+Gather the probe before you write the verdict. When the probe contradicts the code (the code looks right but the port refuses the connection), report the live result and treat the component as suspect.
+
+## Grounding checklist
+
+Before stating a runtime claim, gather the matching live signal:
+
+| Claim | Grounding probe |
+|---|---|
+| The service is healthy | Hit its health endpoint and read the status code. |
+| The config is in effect | Print the loaded config at runtime and read the value. |
+| The server is up | Probe the port; a refused connection means it is down. |
+| The process is running | List processes and match the name or PID. |
+| The change took effect | Drive the flow and watch the new behavior. |
+| The dependency is reachable | Send one real request and read the response. |
+
+Only after a live signal backs the claim do you state it.
+
+## Examples
+
+**Wrong:** "The search server code looks correct, so it is not the problem."
+**Right:** Probe port 54321; report "connection refused — the server is down."
+
+**Wrong:** "This function handles the retry, so the request must be going through."
+**Right:** Tail the request log and confirm the retry fired, or report that no retry line appears.
+
+**Wrong:** "The config sets the timeout to 30 seconds, so the timeout is fine."
+**Right:** Print the loaded config at runtime and report the value the process actually holds.
+
+## Relationship to other rules
+
+- **`verify-before-asking`** answers questions with a tool before asking the user. This rule extends that to runtime verdicts: gather the live probe before you conclude, not just before you ask.
+- **`long-horizon-autonomy`** requires every progress claim to rest on a tool result from this session. A runtime verdict is a progress claim; this rule names the probes that back it.

package/rules/windows-filesystem-safe.md

@@ -1,3 +1,11 @@
+---
+paths:
+  - "**/*.py"
+  - "**/*.mjs"
+  - "**/*.js"
+  - "**/*.ts"
+---
+
 # Windows Filesystem Safety
 
 Never call `shutil.rmtree` with `ignore_errors=True` — Windows `ReadOnly` files (e.g. `.git/objects/pack/`) raise `PermissionError`, the flag swallows it, and the tree silently stays on disk. Use an `onexc` (Python >= 3.12) / `onerror` handler that runs `os.chmod(target_path, stat.S_IWRITE)` then retries the removal function the failure interrupted.

package/rules/workers-done-before-complete.md

@@ -0,0 +1,33 @@
+# Workers Done Before Complete
+
+**When this applies:** Before marking any task `completed` when the task spawned workers — subagents, workflow agents, or background shells.
+
+## Rule
+
+A task reaches `completed` only when two things hold: every worker it spawned has finished, and each worker's result is merged into run state — `state.json`, `pr-converge-state.json`, the task list, or whatever record the task keeps. A worker that still runs, or one that finished but whose output never landed in run state, leaves the task open.
+
+List the live workers before you mark the task complete. When a worker is dead or hung, that is a finding to record and report, not a result to drop in silence. A step that waits on workers ends its turn `in_progress` with a wakeup scheduled, so the run picks the workers back up rather than closing the task without them.
+
+## Checklist before marking complete
+
+| Check | Action |
+|---|---|
+| Are any spawned workers still running? | List them; if yes, stay `in_progress` and schedule a wakeup. |
+| Did every finished worker return a result? | Read each result; a dead or hung worker is a finding to report. |
+| Is each result merged into run state? | Write it to `state.json` / the task list before closing. |
+| Does the task's own goal now hold? | Confirm against the merged state, not a worker's self-report. |
+
+Mark `completed` only when every row passes.
+
+## Examples
+
+**Wrong:** Marking the audit task complete while two bugteam workers still run in the background.
+**Right:** List the workers, see two still running, keep the task `in_progress`, and schedule a wakeup to collect them.
+
+**Wrong:** A worker crashes; the task closes as complete because the other workers finished.
+**Right:** Record the crashed worker as a finding, report it, and hold the task open until its work is covered.
+
+## Relationship to other rules
+
+- **`long-horizon-autonomy`** covers acting on what you have and not ending a turn on a promise. This rule names the specific completion gate: workers finished and their results merged.
+- **`skills/pr-converge/reference/state-schema.md`** defines the run-state records this rule requires a worker's result to land in before the task closes.

package/rules/workflow-substitution-slots.md

@@ -1,3 +1,8 @@
+---
+paths:
+  - "**/*.workflow.js"
+---
+
 # Workflow Substitution Slot Rule
 
 In a `.workflow.js` agent-prompt template, every per-call or per-iteration value an agent must fill in is marked with the angle-bracket convention — `<plate.svg>`, `<object.svg>`, `<glow_hex>`, `cand_<i>`. A bare token such as `cand_i` reads as a fixed literal, so an agent can create one literal directory named `cand_i` and overwrite it across every iteration of a loop, collapsing an N-iteration gate into a single run.

package/skills/CLAUDE.md

@@ -35,6 +35,11 @@ Skills install to `~/.claude/skills/<skill-name>/` via `packages/claude-dev-env/
 - `pr-consistency-audit` — cross-file consistency check on a PR diff
 - `copilot-review` — requests and polls a GitHub Copilot review
 - `findbugs` / `fixbugs` — find bugs then fix them in separate passes
+- `reviewer-gates` — availability gates for external reviewers (opt-out parse, Copilot quota, Bugbot trigger/detect)
+- `pr-scope-resolve` — one resolution ladder for a PR-loop skill's audit/fix target
+- `pr-fix-protocol` — fix, reply, and resolve reviewer findings; the unresolved-thread sweep
+- `post-audit-findings` — publishes an audit pass as one GitHub PR review
+- `pr-loop-lifecycle` — opens and closes a PR-loop run (grant, teardown, PR description, revoke, report)
 - `code` — strict-mode code generation session
 
 **Research and discovery**
@@ -42,7 +47,7 @@ Skills install to `~/.claude/skills/<skill-name>/` via `packages/claude-dev-env/
 - `research-mode` — activates anti-hallucination discipline for a session
 - `recall` — retrieves facts from memory files
 - `remember` — saves a decision, gotcha, or architectural choice to the Obsidian vault
-- `everything-search` — file-system search via the Everything MCP tool
+- `everything-search` — file-system search via the Everything `es.exe` CLI
 - `caveman` — trims noise from a draft artifact
 
 **Session and workflow management**
@@ -62,5 +67,5 @@ Skills install to `~/.claude/skills/<skill-name>/` via `packages/claude-dev-env/
 - `pre-compact` — compact-safe session handoff
 - `qbug` — required baseline PR audit; one clean-coder subagent loops audit → fix → commit → push until clean or stuck
 - `skill-builder` — complete skill-building lifecycle
-- `doc-gist` — uploads an HTML file as a secret gist
 - `auditing-claude-config` — audits a Claude Code setup for context-budget waste and produces a migration table with savings
+- `log-audit` — background agent that audits this repo's own logs for recurring errors and timing regressions and files grouped fixes

package/skills/autoconverge/SKILL.md

@@ -83,31 +83,16 @@ PR's owner.
    example, `claude-code-config` while the PR lives in `llm-settings`) or in no
    git checkout at all cannot continue.
 
-4. **Grant project permissions.**
-   `python "$HOME/.claude/skills/bugteam/scripts/grant_project_claude_permissions.py"`
-
-   In auto-mode the classifier blocks this grant as an unrequested change to the
-   permission allowlist: the `/autoconverge` invocation alone does not meet its
-   bar for an explicitly requested permission change. When it is blocked, keep
-   the run alive — surface the grant to the user through `AskUserQuestion` with
-   the exact command and ask them to approve it or run it themselves with the `!`
-   prefix:
-   `! python "$HOME/.claude/skills/bugteam/scripts/grant_project_claude_permissions.py"`.
-   Continue once the grant lands. A user who wants future runs to skip this
-   prompt can add a standing Bash permission allow-rule for that script in their
-   settings.
-
-5. **Copilot quota pre-check.** Before the `Workflow` call, run once:
-   `python "$HOME/.claude/_shared/pr-loop/scripts/copilot_quota.py"`
-   It reads the account's remaining Copilot premium-request quota via
-   `gh api copilot_internal/user` and prints one line — log that line. Exit 0
-   means Copilot has quota to run, so pass `copilotDisabled: false`. Any non-zero
-   exit means skip Copilot for this run — the account is out of quota, the quota
-   API or account access is down, or no account is set — so pass
-   `copilotDisabled: true`; the workflow then skips the Copilot gate with no agent
-   spawned. The account comes from the `COPILOT_QUOTA_ACCOUNT` environment
-   variable or a git-ignored `.env` file, and the no-account line names the exact
-   `.env` path and key to set.
+4. **Grant project permissions.** Apply the `pr-loop-lifecycle` skill's Open
+   section (`../pr-loop-lifecycle/SKILL.md`) — the grant command
+   (`grant_project_claude_permissions.py`) and the auto-mode `AskUserQuestion`
+   escalation for a blocked grant both live there.
+
+5. **Copilot quota pre-check.** Before the `Workflow` call, apply the
+   `reviewer-gates` skill's Copilot quota gate (`../reviewer-gates/SKILL.md`)
+   once. Exit 0 maps to `copilotDisabled: false` in the Workflow call; any
+   non-zero exit maps to `copilotDisabled: true`, and the workflow then skips
+   the Copilot gate with no agent spawned.
 
 ## Run the workflow
 
@@ -133,7 +118,9 @@ on completion. Watch live progress with `/workflows`.
 The workflow returns
 `{ converged, rounds, finalSha, blocker, standardsNote, copilotNote, reuseNote, deferredPrs }`.
 `deferredPrs` is the list of draft environment-hardening PRs the standards-deferral
-path opened this run, each as `{ owner, repo, prNumber }` — the seed the
+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.
 
 ## Budget-aware round boundaries
@@ -150,10 +137,10 @@ round records nothing resumable and replays dirty.
 ## Teardown (on workflow completion)
 
 1. **When `converged` is true — build and publish the closing report.**
-   Skip this entire step (report, gist, comment, Chrome open) when the workflow
-   returned a non-null `blocker`. Per-round live-dashboard refresh is out of scope
-   here; this step builds the one-shot closing report and the seam (marker comment +
-   gist URL) a future live-dashboard reuses.
+   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
+   scope here; this step builds the one-shot closing report and the seam (marker
+   comment + artifact URL) a future live-dashboard reuses.
 
    a. **Resolve a seed journal path.** Glob
       `~/.claude/projects/**/workflows/wf_<runId>.json` (where `runId` is the run id
@@ -192,21 +179,16 @@ round records nothing resumable and replays dirty.
       Use the `combinedJournal`, `finalSha`, and `roundCount` from step b. Capture the
       output path from stdout.
 
-   e. **Publish as a secret gist** by reusing `doc-gist` (do not reimplement gist
-      creation):
-      ```
-      python "$HOME/.claude/skills/doc-gist/scripts/gist_upload.py" \
-        --input "<html path>" \
-        --no-open \
-        --description "autoconverge report PR #<n>"
-      ```
-      Capture the htmlpreview URL from stdout. The gist is secret by default; pass
-      no public flag.
+   e. **Publish via the Artifact tool.** Load the `artifact-design` skill first, then
+      call `Artifact` with `file_path` set to the report path from step d, `favicon`
+      set to the fixed autoconverge favicon `✅` (keep this favicon stable across
+      every autoconverge report — never swap it per run), and `description` set to
+      a one-sentence subtitle naming the PR. Capture the returned URL.
 
    f. **Post one idempotent PR comment.** List the PR's issue comments; if one
       carries the marker `<!-- autoconverge-report -->`, edit it in place, otherwise
       create a new one. The body begins with `<!-- autoconverge-report -->`, then
-      the htmlpreview link, then a plain-language summary that mirrors the report:
+      the artifact URL, then a plain-language summary that mirrors the report:
       lead with the one-sentence `verdictLine`; then the plain Problem and Fix
       sentences (`prProblem`, `prFix`); then the issue-class list — one bullet per
       class as `plainName (×count, status)`. Place the raw finding list as
@@ -217,21 +199,21 @@ round records nothing resumable and replays dirty.
       GitHub MCP `add_issue_comment` tool (body as a structured parameter, no
       `--body` flag).
 
-   g. **Open the report in Chrome.**
+   g. **Open the published report in Chrome.** Use the artifact URL captured in
+      step e.
       ```
-      Start-Process chrome -ArgumentList '--new-window', '<report path>'
+      Start-Process chrome -ArgumentList '--new-window', '<artifact URL>'
       ```
       Tolerate a missing Chrome without aborting the rest of teardown.
 
-2. **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.
-
-3. **Always revoke project permissions** (including on a blocker exit):
-   `python "$HOME/.claude/skills/bugteam/scripts/revoke_project_claude_permissions.py"`
+2. **Close the run.** Apply the `pr-loop-lifecycle` skill's Close section
+   (`../pr-loop-lifecycle/SKILL.md`): when `converged` is true, rewrite the PR
+   description and clean the working tree — see
+   [`pr-loop-lifecycle/reference/teardown-publish-permissions.md` § Clean working tree and § Publish the final PR description](../pr-loop-lifecycle/reference/teardown-publish-permissions.md);
+   the workflow already marked the PR ready. The permission revoke always runs,
+   including on a blocker exit.
 
-4. **Print the final report:**
+3. **Print the final report:**
 
    ```
    /autoconverge exit: <converged | blocked>
@@ -302,13 +284,14 @@ matches.
 
 - **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. 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.
+  `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.
   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
@@ -435,8 +418,8 @@ so there is nothing to converge. Report that and stop.
 
 ### Each generation
 
-Given a non-empty list of deferred PRs `{ owner, repo, prNumber }` (a generation
-may span more than one repository — a hardening PR lands in whichever repo owns
+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):
 
@@ -449,7 +432,11 @@ and `jl-cmd/claude-code-config` for rules and skills both appear):
    Grant project permissions once per repository the generation spans.
 2. **Converge the generation.** Launch `workflow/converge_multi.mjs` with one
    entry per checked-out deferred PR, exactly as the
-   [multi-PR launch](#launch-the-multi-pr-workflow) describes.
+   [multi-PR launch](#launch-the-multi-pr-workflow) describes. Each child run
+   re-checks Copilot and Bugbot availability every round through the workflow's own
+   pre-spawn probe, so a reviewer that is down or out of quota is never spawned in any
+   generation; the `copilotDisabled`/`bugbotDisabled` flags each deferred PR carries
+   seed that check for the first round.
 3. **Tear down.** Run the [multi-PR teardown](#multi-pr-teardown-on-workflow-completion)
    over the generation's `results`, and revoke project permissions once per
    repository.

package/skills/autoconverge/reference/closing-report.md

@@ -1,6 +1,6 @@
 # Closing Report
 
-When an autoconverge run converges (the workflow returns `converged: true`), the main session generates a convergence insights HTML report and publishes it as a secret gist with an idempotent PR comment linking to it.
+When an autoconverge run converges (the workflow returns `converged: true`), the main session generates a convergence insights HTML report and publishes it with the `Artifact` tool, with an idempotent PR comment linking to it.
 
 ## Data source
 
@@ -73,14 +73,14 @@ Counting is deterministic: `generated_date` comes from the journal `timestamp`,
 
 After rendering, the main session:
 
-1. **Uploads the HTML as a secret gist** using `doc-gist/scripts/gist_upload.py --no-open`. Captures the htmlpreview URL from stdout.
-2. **Posts one idempotent PR comment** marked with `<!-- autoconverge-report -->`. If a comment with that marker already exists on the PR, it is edited in place; otherwise a new comment is created. The body leads with the gist URL, then the one-sentence `verdictLine`, then the plain Problem and Fix sentences (`prProblem`, `prFix`), then the issue-class list — one bullet per class as `plainName (×count, status)` — and closes with the full finding list (`file:line — P# — title`) inside a collapsed `<details>` block. Write the body to a BOM-free temp file and pass `--body-file` to `gh issue comment` (never `--body`), or use the GitHub MCP `add_issue_comment` tool.
-3. **Opens the report** with `Start-Process chrome -ArgumentList '--new-window', '<report path>'`. A missing Chrome does not abort teardown.
+1. **Publishes the HTML with the Artifact tool.** Loads the `artifact-design` skill first, then calls `Artifact` with `file_path` set to the rendered report, `favicon` set to the fixed autoconverge favicon `✅` (kept stable across every autoconverge report), and `description` naming the PR. Captures the returned URL.
+2. **Posts one idempotent PR comment** marked with `<!-- autoconverge-report -->`. If a comment with that marker already exists on the PR, it is edited in place; otherwise a new comment is created. The body leads with the artifact URL, then the one-sentence `verdictLine`, then the plain Problem and Fix sentences (`prProblem`, `prFix`), then the issue-class list — one bullet per class as `plainName (×count, status)` — and closes with the full finding list (`file:line — P# — title`) inside a collapsed `<details>` block. Write the body to a BOM-free temp file and pass `--body-file` to `gh issue comment` (never `--body`), or use the GitHub MCP `add_issue_comment` tool.
+3. **Opens the published report** with `Start-Process chrome -ArgumentList '--new-window', '<artifact URL>'`, using the artifact URL captured in step 1. A missing Chrome does not abort teardown.
 
 ## Live-dashboard seam
 
-The marker comment and gist together form a seam for future per-round dashboard refreshes: a live-dashboard step re-renders with the same `render_report_html` function (pure, no side effects), runs `gh gist edit` on the same gist, and edits the same marker comment. That per-round refresh path is out of scope here; this document describes the one-shot closing report only.
+The marker comment and artifact together form a seam for future per-round dashboard refreshes: a live-dashboard step re-renders with the same `render_report_html` function (pure, no side effects), calls `Artifact` again on the same `file_path` to redeploy to the same URL, and edits the same marker comment. That per-round refresh path is out of scope here; this document describes the one-shot closing report only.
 
 ## Scope
 
-The closing report runs only when `converged === true`. On a blocker exit (`blocker: "budget"` or similar), the report, gist, comment, and Chrome open are all skipped.
+The closing report runs only when `converged === true`. On a blocker exit (`blocker: "budget"` or similar), the report, artifact publish, comment, and Chrome open are all skipped.

package/skills/autoconverge/reference/convergence.md

@@ -55,24 +55,25 @@ tracks CONVERGE passes only and is never the cap.
    - **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
+     shared A–P rubric from `_shared/pr-loop/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. Before its turn ends, the edit step dry-runs the
-   CODE_RULES commit gate (`code_rules_gate.py --staged`) over its staged
+4. **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
+   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
-   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.
+   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 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.
 
@@ -112,9 +113,10 @@ the current HEAD:
 4. The Copilot review on HEAD is clean or approved (bypassed when Copilot is down
    or out of quota this run).
 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).
+   Claude, and Copilot authored threads. The filter is purely
+   `isResolved == false`; `isOutdated` is informational, and the fix lens
+   verifies each outdated thread against current HEAD like any other (the
+   `pr-fix-protocol` skill's unresolved-thread sweep).
 6. The PR is mergeable (`mergeable` true and `mergeable_state` clean).
 7. No requested reviewers are still pending (bypassed when Copilot is down or out
    of quota this run).

package/skills/autoconverge/reference/gotchas.md

@@ -21,9 +21,12 @@ fails in a new way.
 - **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.
+  runs a single serial `git fetch origin main` inside the merged `preflight-git`
+  step — the one git-utility agent that also resolves the PR HEAD SHA and probes
+  mergeability — and the parallel lenses run no git fetch of their own; they
+  diff against the already-current ref. The workflow threads the resolved HEAD
+  through the rounds and re-runs `preflight-git` only after a push or rebase
+  invalidates it, so a round on an unchanged HEAD spawns no git agent at all.
 
 - **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

package/skills/autoconverge/workflow/autoconverge_report_constants/render_report_constants.py

@@ -154,16 +154,9 @@ Write so a non-programmer understands every line. The reader has never seen the
 
 Return strictly a JSON object with keys prProblem, prFix, problemScenes, fixScenes, verdictLine, and issueClasses."""
 
-HTML_DOCTYPE = "<!DOCTYPE html>"
-
-HTML_HEAD_TEMPLATE = """\
-<head>
-<meta charset="utf-8">
-<meta name="viewport" content="width=device-width, initial-scale=1">
+HTML_TITLE_AND_STYLE_TEMPLATE = """\
 <title>PR #{pr_number} Convergence Summary</title>
-<link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700;800&family=JetBrains+Mono:wght@400;500&display=swap" rel="stylesheet">
-{style_block}
-</head>"""
+{style_block}"""
 
 HTML_STYLE_BLOCK = """\
 <style>

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

@@ -44,15 +44,95 @@ 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.ok(convergeSource.includes("runGitTask('prefetch-main')"));
-  const prefetchCallIndex = convergeSource.indexOf("runGitTask('prefetch-main')");
+test('the merged preflight-git task fetches origin/main once before the parallel lenses', () => {
+  assert.ok(convergeSource.includes("runGitTask('preflight-git')"));
+  const preflightCallIndex = convergeSource.indexOf("runGitTask('preflight-git')");
   const parallelLensIndex = convergeSource.indexOf('const lenses = await parallel(');
-  assert.notEqual(prefetchCallIndex, -1, 'expected prefetch to be invoked');
+  assert.notEqual(preflightCallIndex, -1, 'expected the merged preflight 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',
+    preflightCallIndex < parallelLensIndex,
+    'expected the merged preflight to run before the parallel lenses spawn',
+  );
+  const gitTaskBody = functionSource('runGitTask');
+  assert.match(gitTaskBody, /git fetch origin main/, 'expected the merged task to carry the base-ref fetch');
+  assert.match(gitTaskBody, /--jq \.head\.sha/, 'expected the merged task to resolve the PR HEAD SHA');
+  assert.match(gitTaskBody, /PREFLIGHT_GIT_SCHEMA/, 'expected the merged task to return the {sha, conflicting, fetched} schema');
+});
+
+test('the merged preflight-git agent runs on haiku at low effort', () => {
+  const gitTaskBody = functionSource('runGitTask');
+  assert.match(gitTaskBody, /model: 'haiku'/, 'expected the git-utility agent to run on the cheapest model');
+  assert.match(gitTaskBody, /effort: 'low'/, 'expected the git-utility agent to run at low effort');
+});
+
+test('the CONVERGE round spawns a single shared reviewer-availability probe before the parallel lenses', () => {
+  const convergeBranchStart = convergeSource.indexOf("if (phase === 'CONVERGE')");
+  const refreshCallIndex = convergeSource.indexOf("runGitTask('preflight-git')", convergeBranchStart);
+  const probeCallIndex = convergeSource.indexOf('reviewerAvailability = await runReviewerAvailabilityCheck()');
+  const parallelLensIndex = convergeSource.indexOf('const lenses = await parallel(');
+  assert.notEqual(probeCallIndex, -1, 'expected the CONVERGE round to spawn the shared reviewer-availability probe');
+  assert.ok(
+    refreshCallIndex < probeCallIndex && probeCallIndex < parallelLensIndex,
+    'expected the probe to run after the round head refresh and before the parallel lenses spawn',
+  );
+  const probeBody = functionSource('runReviewerAvailabilityCheck');
+  assert.match(probeBody, /reviewer_availability\.py/);
+  assert.match(probeBody, /--reviewer copilot/);
+  assert.match(probeBody, /--reviewer bugbot/);
+  assert.match(probeBody, /schema:\s*REVIEWER_AVAILABILITY_SCHEMA/);
+});
+
+test('the Bugbot lens is not spawned pre-spawn when the shared gate reports Bugbot down', () => {
+  const parallelLensIndex = convergeSource.indexOf('const lenses = await parallel(');
+  assert.notEqual(parallelLensIndex, -1, 'expected the parallel lens block to exist');
+  const isBugbotDownPreSpawnIndex = convergeSource.indexOf('const isBugbotDownPreSpawn = resolveReviewerDown(');
+  assert.notEqual(isBugbotDownPreSpawnIndex, -1, 'expected a pre-spawn Bugbot-down decision computed before the lens array');
+  assert.ok(
+    isBugbotDownPreSpawnIndex < parallelLensIndex,
+    'expected the pre-spawn Bugbot-down decision to be computed before the parallel lens array',
+  );
+  const lensArrayEnd = convergeSource.indexOf('])', parallelLensIndex);
+  const lensArray = convergeSource.slice(parallelLensIndex, lensArrayEnd);
+  assert.match(
+    lensArray,
+    /isBugbotDownPreSpawn \? Promise\.resolve\(\{ sha: head, clean: true, down: true, findings: \[\] \}\) : runBugbotLens\(head\)/,
+    'expected the Bugbot lens slot to substitute a resolved down placeholder instead of spawning runBugbotLens when isBugbotDownPreSpawn is true',
+  );
+});
+
+test('the post-round bugbotDown verdict treats a dead Bugbot lens as down, not fail-open', () => {
+  const parallelLensIndex = convergeSource.indexOf('const lenses = await parallel(');
+  assert.notEqual(parallelLensIndex, -1, 'expected the parallel lens block to exist');
+  const lensArrayEnd = convergeSource.indexOf('])', parallelLensIndex);
+  const bugbotDownAssignIndex = convergeSource.indexOf('bugbotDown = ', lensArrayEnd);
+  assert.notEqual(bugbotDownAssignIndex, -1, 'expected the post-round bugbotDown assignment after the lens array');
+  const bugbotDownAssignLineEnd = convergeSource.indexOf('\n', bugbotDownAssignIndex);
+  const bugbotDownAssignLine = convergeSource.slice(bugbotDownAssignIndex, bugbotDownAssignLineEnd);
+  assert.match(
+    bugbotDownAssignLine,
+    /bugbotDown = lenses\[0\] == null \? true : resolveReviewerDown\(lenses\[0\], input\.bugbotDisabled \|\| false\)/,
+    'expected a dead (null) Bugbot lens result to report bugbotDown:true — resolveReviewerDown alone is fail-open on null, which would wrongly report bugbotDown:false for a lens agent that actually spawned and died, leaving check_convergence.py to look for a bugbot review that was never posted',
+  );
+});
+
+test('both reviewer trigger commands carry the CLAUDE_REVIEWER_GATE=autoconverge sentinel', () => {
+  assert.match(
+    convergeSource,
+    /const REVIEWER_GATE_SENTINEL = 'CLAUDE_REVIEWER_GATE=autoconverge '/,
+    'expected the shared sentinel constant to exist',
+  );
+  const copilotPrompt = lensPromptBody('runCopilotGate');
+  assert.match(
+    copilotPrompt,
+    /\$\{REVIEWER_GATE_SENTINEL\}gh api --method POST[^\n]*requested_reviewers/,
+    'expected the Copilot requested_reviewers trigger to carry the sentinel prefix',
+  );
+  const bugbotPrompt = lensPromptBody('runBugbotLens');
+  assert.match(
+    bugbotPrompt,
+    /\$\{REVIEWER_GATE_SENTINEL\}python "\$\{CONFIG\.sharedScripts\}\/post_fix_reply\.py"[^\n]*--body "bugbot run"/,
+    'expected the Bugbot rerun-comment trigger to carry the sentinel prefix',
   );
 });
 
@@ -178,11 +258,74 @@ test('the COPILOT fix branch does not re-assign head from the fix before re-conv
   );
 });
 
-test('the CONVERGE branch re-resolves HEAD from GitHub on every entry', () => {
+test('the CONVERGE branch refreshes HEAD via the merged preflight-git task only when the threaded head is invalidated', () => {
   const convergeBranchStart = convergeSource.indexOf("if (phase === 'CONVERGE')");
   assert.notEqual(convergeBranchStart, -1, 'expected the CONVERGE branch to exist');
-  const headResolveCallIndex = convergeSource.indexOf("runGitTask('resolve-head')", convergeBranchStart);
-  assert.notEqual(headResolveCallIndex, -1, 'expected CONVERGE to re-resolve HEAD via runGitTask');
+  const invalidGuardIndex = convergeSource.indexOf('if (!isResolvedHeadUsable(head))', convergeBranchStart);
+  const headRefreshCallIndex = convergeSource.indexOf("runGitTask('preflight-git')", convergeBranchStart);
+  assert.notEqual(invalidGuardIndex, -1, 'expected CONVERGE to gate the refresh on an invalidated head');
+  assert.notEqual(headRefreshCallIndex, -1, 'expected CONVERGE to refresh HEAD via the merged preflight-git task');
+  assert.ok(
+    invalidGuardIndex < headRefreshCallIndex,
+    'expected the invalidated-head guard to precede the merged refresh so a valid threaded head spawns no git agent',
+  );
+});
+
+test('each fix push, each lens-retry, and the convergence repair invalidate the threaded head so the next CONVERGE entry refreshes it', () => {
+  const invalidationMatches = convergeSource.match(/^ +head = null$/gm) || [];
+  assert.equal(
+    invalidationMatches.length,
+    5,
+    'expected head invalidation after the CONVERGE fix push, the COPILOT fix push, the convergence repair, the all-lenses-dead retry, and the not-clean-no-findings retry',
+  );
+});
+
+function convergeRetryBranch(guardMarker) {
+  const guardIndex = convergeSource.indexOf(guardMarker);
+  assert.notEqual(guardIndex, -1, `expected the ${guardMarker} retry branch to exist`);
+  const continueIndex = convergeSource.indexOf('continue', guardIndex);
+  assert.notEqual(continueIndex, -1, `expected a continue statement to close the ${guardMarker} branch`);
+  return convergeSource.slice(guardIndex, continueIndex + 'continue'.length);
+}
+
+test('the all-lenses-dead retry invalidates the threaded head so the next round re-fetches origin/main before spawning lenses', () => {
+  const branch = convergeRetryBranch('if (roundOutcome.allLensesDead) {');
+  const headNullIndex = branch.indexOf('head = null');
+  assert.notEqual(
+    headNullIndex,
+    -1,
+    'expected the all-lenses-dead retry to null head so the next round re-enters preflight-git — otherwise the lenses are told origin/main was fetched this round when no fetch ran',
+  );
+  assert.ok(
+    headNullIndex < branch.indexOf('continue'),
+    'expected head to be invalidated before the retry continues to the next round',
+  );
+});
+
+test('the not-clean-no-findings retry invalidates the threaded head so the next round re-fetches origin/main before spawning lenses', () => {
+  const branch = convergeRetryBranch('if (!roundOutcome.roundClean) {');
+  const headNullIndex = branch.indexOf('head = null');
+  assert.notEqual(
+    headNullIndex,
+    -1,
+    'expected the not-clean-no-findings retry to null head so the next round re-enters preflight-git — otherwise the lenses are told origin/main was fetched this round when no fetch ran',
+  );
+  assert.ok(
+    headNullIndex < branch.indexOf('continue'),
+    'expected head to be invalidated before the retry continues to the next round',
+  );
+});
+
+test('the preflight consumes the head returned by resolveMergeConflicts without an immediate re-resolve', () => {
+  const consumedHeadIndex = convergeSource.indexOf('head = await resolveMergeConflicts(');
+  assert.notEqual(consumedHeadIndex, -1, 'expected the post-rebase head from resolveMergeConflicts to be captured');
+  const whileLoopIndex = convergeSource.indexOf('while (iterations < CONFIG.maxIterations)');
+  const betweenPreflightAndLoop = convergeSource.slice(consumedHeadIndex, whileLoopIndex);
+  assert.doesNotMatch(
+    betweenPreflightAndLoop,
+    /runGitTask\(/,
+    'expected the reuse pass to reuse the threaded head with no git-utility agent spawn',
+  );
 });
 
 test('fix edit prompt resolves threads by PRRT thread node id looked up from the comment databaseId', () => {
@@ -484,7 +627,7 @@ test('the reuse pass applies its findings through applyFixes, not the standards-
   const reuseBlock = convergeSource.slice(reuseCallIndex, loopIndex);
   assert.match(
     reuseBlock,
-    /applyFixes\(reuseHead, reuseFindings, 'reuse-pass'\)/,
+    /applyFixes\(head, reuseFindings, 'reuse-pass'\)/,
     'expected the reuse pass to apply its findings via applyFixes',
   );
   assert.doesNotMatch(