claude-dev-env 1.83.0 → 1.84.0

package/hooks/workflow/CLAUDE.md

@@ -1,22 +1,16 @@
 # hooks/workflow
 
-PostToolUse hooks that trigger side-effects after Claude writes a file. They do not block writes; they produce companion artifacts or publish content automatically.
+PostToolUse hooks that run after Claude writes a file. They do not block the write; they run follow-up side effects — reformatting the written file and resetting the investigation tracker.
 
 ## Key files
 
 | File | Event | What it does |
 |---|---|---|
 | `auto_formatter.py` | PostToolUse (Write/Edit) | Runs the project's auto-formatter (ruff, prettier, etc.) on the written file and sends a desktop notification when formatting changes are applied |
-| `doc_gist_auto_publish.py` | PostToolUse (Write on `.html` files) | When an `.html` file has the `<!-- @publish-as-gist -->` marker, uploads it as a secret GitHub Gist and prints the htmlpreview URL into the harness output |
-| `md_to_html_companion.py` | PostToolUse (Write/Edit on `.md` files) | Generates a styled `.html` companion file from the `.md` source with dark-mode styling |
 | `investigation_tracker_reset.py` | PostToolUse | Resets the investigation tracker state after a tool call |
 | `test_auto_formatter.py` | — | Tests for `auto_formatter.py` |
-| `test_doc_gist_auto_publish.py` | — | Tests for `doc_gist_auto_publish.py` |
-| `test_md_to_html_companion.py` | — | Tests for `md_to_html_companion.py` |
 
 ## Conventions
 
-- All three main hooks exit 0 even on failure — they log warnings to stderr but do not break Claude's flow.
-- `doc_gist_auto_publish.py` checks for the `<!-- @publish-as-gist -->` marker before doing any work; HTML files without it are ignored.
-- Constants (marker text, blocked URL schemes, gist upload script path) live in `hooks_constants/doc_gist_auto_publish_constants.py` and `hooks_constants/html_companion_constants.py`.
+- `auto_formatter.py` exits 0 even on failure — it logs warnings to stderr but does not break Claude's flow.
 - Tests run with `python -m pytest workflow/test_<name>.py`.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "claude-dev-env",
-    "version": "1.83.0",
+    "version": "1.84.0",
     "description": "Claude Code development standards — rules, hooks, agents, commands, and skills",
     "type": "module",
     "bin": {

package/rules/CLAUDE.md

@@ -33,7 +33,7 @@ Rule files installed into `~/.claude/rules/` by `bin/install.mjs`. Claude Code l
 | `package-inventory-stale-entry.md` | A new production code file added to a directory carries an entry in that directory's `README.md`/`CLAUDE.md` file inventory |
 | `paired-test-coverage.md` | A public function omitted by a module's established paired test suite must get a behavioral test |
 | `parallel-tools.md` | Make all independent tool calls in a single response |
-| `plain-illustrative-docstrings.md` | Public docstring narrative reads plainly and paints a concrete scene a general developer follows on first read; a run-on backstop hook plus Category O9 audit enforce it |
+| `plain-illustrative-docstrings.md` | Public docstring narrative reads plainly and shows behavior with a diagram block (a `::` example or a doctest), painting a concrete scene a general developer follows on first read; a run-on backstop hook, a prose-wall backstop hook, and Category O9 audit enforce it |
 | `plain-language.md` | Everyday words, short active sentences, lead with the answer |
 | `prompt-workflow-context-controls.md` | Keep prompt-workflow instruction layers small and stable; load heavy skills on demand |
 | `research-mode.md` | Three anti-hallucination constraints: say "I don't know", verify with citations, quote for factual grounding |

package/rules/plain-illustrative-docstrings.md

@@ -19,6 +19,39 @@ Two shapes break the standard. Hold the prose clear of both:
 - **No machinery nouns stacked into a wall.** A sentence that chains abstract machinery terms (`the SIGINT install/restore/installability check, the atexit terminal-record registration, and the interrupted-run finalizer`) names parts without painting a scene. Name what the reader sees and why it matters.
 - **No defining by negation.** Prose that explains a thing by what it is not (`the non-promoter-specific machinery`) leaves the reader without a picture. Say what the thing is.
 
+## Shape: a summary line, then a diagram
+
+The clearest way to be illustrative is to show a worked example, not describe one. A docstring that lands well reads in four parts:
+
+1. **One summary line** that says what the code does.
+2. **A diagram block** that carries the explanation by sight — a reStructuredText literal block (a line ending in `::`, then an indented example) or a doctest (`>>>`). Give the concrete input, mark the outcome, and add `ok:` / `flag:` contrast lines where a pass-and-fail pair makes the point. Keep the diagram clear of a bare number or an ALL-CAPS `NAME = value` line, which read as a magic value or a stray constant to a line-based lint pass.
+3. **A couple of short narrative lines** after the block — two or three at most.
+4. **The Google `Args:` / `Returns:` sections.**
+
+Keep the wording neutral in the diagram and the prose: two names "contradict" or "clash", two names "agree". Skip words that pass judgment.
+
+Canonical example:
+
+```
+Flag a boolean assignment whose target and callee assert opposite polarity.
+
+::
+
+    is_inside_allowed = _point_hits_any_forbidden(...)
+             ^^^^^^^                    ^^^^^^^^^
+             allowed         vs.        forbidden      ⚠ the two names clash
+    ok:   is_inside_allowed = _point_inside_allowed_region(...)
+    flag: is_inside_allowed = _point_hits_any_forbidden(...)
+
+The target token and the callee token contradict each other, so the reader
+cannot tell which name states the truth. Rename the callee to a neutral form
+the two names agree on at every call site.
+```
+
+The live version of this docstring sits on `check_polarity_name_contradiction` in `packages/claude-dev-env/hooks/blocking/code_rules_naming_collection.py`.
+
+A short narrative with no diagram is fine when a couple of plain sentences carry the whole picture. The diagram earns its place once the explanation grows past what two or three lines hold — the moment a wall of prose starts to form.
+
 ## What to check before you write the docstring
 
 Read the narrative back as a stranger would:
@@ -53,7 +86,8 @@ one — and you're debugging blind.
 
 Two surfaces carry this standard:
 
-- **Hook (the run-on backstop).** `check_docstring_runon_sentence` in `packages/claude-dev-env/hooks/blocking/code_rules_docstrings.py` flags the one mechanical mark of a wall: a single narrative sentence that is both over the word limit and joined by an em-dash or a semicolon. A hook cannot judge whether prose paints a picture, so it catches only this structural mark.
+- **Hook (the run-on backstop).** `check_docstring_runon_sentence` in `packages/claude-dev-env/hooks/blocking/code_rules_docstrings.py` flags the one mechanical mark of a wall: a single narrative sentence that is both over the word limit and joined by an em-dash or a semicolon. A hook cannot judge whether prose paints a picture, so it catches only this structural mark. It reads the narrative through a shared partition that sets aside any `::` literal block and any doctest, so a diagram's own arrows and dashes never count against the sentence.
+- **Hook (the prose-wall backstop).** `check_docstring_prose_wall_without_illustration` in the same module flags a narrative that runs more than six prose lines with no diagram block. It marks the wall so the writer shows the behavior with a `::` example or a doctest and trims the prose to a few short lines. It cannot judge whether the diagram illustrates well; that stays with the audit lane.
 - **Audit (the judgment lane).** Category O sub-bucket O9 in `packages/claude-dev-env/audit-rubrics/category_rubrics/category-o-docstring-vs-impl-drift.md` carries the illustrative-and-brief judgment the hook cannot. The audit teammate reads each changed docstring's narrative and asks whether a general developer follows it on the first read.
 
 ## Why

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**
@@ -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
 
@@ -152,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
@@ -194,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
@@ -219,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>
@@ -304,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

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,26 +44,37 @@ 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 prefetchCallIndex = convergeSource.indexOf("runGitTask('prefetch-main')");
+  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(
-    prefetchCallIndex < probeCallIndex && probeCallIndex < parallelLensIndex,
-    'expected the probe to run after the round prefetch and before the parallel lenses spawn',
+    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/);
@@ -247,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', () => {
@@ -553,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(

package/skills/autoconverge/workflow/converge.copilot-gate.test.mjs

@@ -73,7 +73,7 @@ test('Copilot findings route to a fix when Copilot is reachable and not down', (
 
 test('COPILOT_SCHEMA carries a required down field', () => {
   const schemaStart = convergeSource.indexOf('const COPILOT_SCHEMA =');
-  const schemaEnd = convergeSource.indexOf('const HEAD_SCHEMA =');
+  const schemaEnd = convergeSource.indexOf('const REVIEWER_AVAILABILITY_SCHEMA =');
   assert.notEqual(schemaStart, -1, 'expected COPILOT_SCHEMA to exist');
   const schemaSource = convergeSource.slice(schemaStart, schemaEnd);
   assert.match(schemaSource, /down:\s*\{\s*type:\s*'boolean'/);

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

@@ -39,7 +39,7 @@ test('the git agent handles merge-conflict checks with a Monitor-based poll', ()
     /do not edit, commit, push, or rebase|read only/i,
     'expected the git agent merge check to be read-only',
   );
-  assert.match(gitBody, /MERGE_CONFLICT_SCHEMA/, 'expected the git agent to return MERGE_CONFLICT_SCHEMA');
+  assert.match(gitBody, /PREFLIGHT_GIT_SCHEMA/, 'expected the git agent to return PREFLIGHT_GIT_SCHEMA');
   assert.match(gitBody, /Monitor tool/, 'expected a Monitor-based poll delay, not a foreground sleep');
 });
 
@@ -53,31 +53,38 @@ test('runCodeEditorTask conflict-edit path rebases onto origin/main and makes no
   );
 });
 
-test('resolveMergeConflicts runs check -> edit -> verify -> commit and gates the push on the verdict', () => {
+test('resolveMergeConflicts runs edit -> verify -> commit and gates the push on the verdict', () => {
   const body = functionBody('resolveMergeConflicts');
-  const checkIndex = body.indexOf("runGitTask('check-merge-conflicts'");
   const editIndex = body.indexOf("runCodeEditorTask('conflict-edit'");
   const verifyIndex = body.indexOf('runVerifierTask(');
   const commitIndex = body.indexOf('commitWithRecovery(');
-  assert.notEqual(checkIndex, -1, 'expected the conflict check to run');
   assert.notEqual(editIndex, -1, 'expected the 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',
+    editIndex < verifyIndex && verifyIndex < commitIndex,
+    'expected the order edit -> verify -> commit',
   );
   assert.match(body, /verdictPassed\(/, 'expected the verifier verdict to gate the force-push');
+  assert.doesNotMatch(
+    body,
+    /runGitTask\(/,
+    'expected the conflict decision to come from the merged preflight-git probe, with no mergeability agent spawned here',
+  );
 });
 
-test('resolveMergeConflicts rebases only when the check reports a conflict', () => {
+test('resolveMergeConflicts rebases only when the caller-supplied preflight decision 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/,
+    /if \(!isConflicting\) return head/,
     'expected a clean PR to return the unchanged HEAD without rebasing',
   );
+  assert.match(
+    convergeSource,
+    /resolveMergeConflicts\(preflight\.sha, isMergeConflicting\(preflight\)\)/,
+    'expected the call site to derive the conflict decision from the merged preflight-git result',
+  );
 });
 
 test('the merge-conflict pre-flight runs once before the round loop, ahead of the parallel bug-check lenses', () => {