claude-dev-env 1.86.1 → 1.88.0

package/CLAUDE.md

@@ -21,6 +21,10 @@ Every Markdown file I write or edit describes the system's **current** state onl
 Full banned-pattern set + enforcement: `~/.claude/rules/no-historical-clutter.md` (hook `state-description-blocker`) and `~/.claude/rules/self-contained-docs.md`.
 
 ## GOTCHAS
+ALWAYS base new worktrees off of UPSTREAM origin main. Assume local is out of date.
+
+ALWAYS start each session with a /loop 15m populate or update the task list based on remaining todos.
+
 When making code changes, make sure you are working in the proper worktree path for the task at hand.
 
 ## Choosing Edit vs Write

package/agents/CLAUDE.md

@@ -16,7 +16,7 @@ Agent definition files installed into `~/.claude/agents/` by `bin/install.mjs`.
 | `docs-agent.md` | Docs Agent | Documentation authoring and maintenance |
 | `git-commit-crafter.md` | Git Commit Crafter | Stages changes, writes conventional commit messages, creates commits |
 | `plan-packet-validator.md` | Plan Packet Validator | Fresh-context validator for workflow-generated plan packets under `docs/plans/` |
-| `pr-description-writer.md` | PR Description Writer | Authors PR descriptions in Anthropic-style shapes; required by the `pr_description_enforcer` hook |
+| `pr-description-writer.md` | PR Description Writer | Authors PR descriptions in Anthropic-style shapes that pass the `pr_description_enforcer` hook's body audit |
 
 ## Format
 

package/agents/pr-description-writer.md

@@ -1,6 +1,6 @@
 ---
 name: pr-description-writer
-description: "MANDATORY agent for PR descriptions and PR comments. Enforced by the `pr_description_enforcer` PreToolUse hook on `gh pr create`, `gh pr edit`, and `gh pr comment`. Authors bodies in one of three Anthropic-derived shapes (Trivial / Standard / Heavy) so PRs match merged-PR style in `anthropics/claude-code`, `anthropics/claude-code-action`, and `anthropics/claude-code-sdk-python`."
+description: "Optional agent for PR descriptions and PR comments. Authors bodies in one of three Anthropic-derived shapes (Trivial / Standard / Heavy) so PRs match merged-PR style in `anthropics/claude-code`, `anthropics/claude-code-action`, and `anthropics/claude-code-sdk-python`, and pass the `pr_description_enforcer` PreToolUse hook's body audit on `gh pr create`, `gh pr edit`, and `gh pr comment`."
 tools: Read,Grep,Glob,Bash
 model: haiku
 ---

package/bin/install.mjs

@@ -147,6 +147,7 @@ const INSTALL_GROUPS = {
     core: {
         description: 'Development standards, hooks, agents, commands',
         skills: [
+            'advisor', 'advisor-refresh',
             'anthropic-plan', 'everything-search',
             'pr-review-responder',
             'recall', 'remember', 'task-build', 'verified-build'

package/hooks/blocking/CLAUDE.md

@@ -81,7 +81,7 @@ The check modules it calls are the `code_rules_<concern>.py` files below.
 | `package_inventory_stale_blocker.py` | PreToolUse (Write) | A new production code file created in a directory whose `README.md`/`CLAUDE.md` inventory (or a parent skill's `SKILL.md` Layout table mapping the `scripts/` subdirectory) names two or more sibling files but no entry for the new file |
 | `plain_language_blocker.py` | PreToolUse (Write/Edit/AskUserQuestion) | Heavy or jargon words in user-facing prose |
 | `pr_converge_bugteam_enforcer.py` | PreToolUse | Enforces that bugteam runs in parallel with bugbot in pr-converge loops |
-| `pr_description_enforcer.py` | PreToolUse (Bash) | `gh pr create`/`edit` without a PR-description-writer-authored body |
+| `pr_description_enforcer.py` | PreToolUse (Bash) | `gh pr create`/`edit`/`comment` bodies that fail the Anthropic claude-code style audit |
 | `precommit_code_rules_gate.py` | PreToolUse (Bash) | Staged changes that fail the CODE_RULES gate at commit time |
 | `pytest_testpaths_orphan_blocker.py` | PreToolUse (Write/Edit/MultiEdit) | New `test_*.py` files created under a directory absent from a package's explicit pytest `testpaths` allowlist |
 | `question_to_user_enforcer.py` | Stop | User-directed questions not routed through `AskUserQuestion` |

package/hooks/blocking/pr_description_enforcer.py

@@ -178,7 +178,7 @@ def main() -> None:
         pr_guide_reference = f" @{PR_GUIDE_PATH}" if os.path.exists(PR_GUIDE_PATH) else ""
         denial_reason = (
             f"BLOCKED: [PR_DESCRIPTION] {violation_list}. "
-            f"Use the pr-description-writer agent to author the body in Anthropic claude-code style. "
+            f"Rewrite the body yourself in Anthropic claude-code style. "
             f"Guide:{pr_guide_reference}"
         )
         denial_payload = {

package/hooks/blocking/pr_description_readability.py

@@ -76,8 +76,10 @@ def _read_strike_count() -> int:
 def _increment_strike_count() -> int:
     payload = _read_json_or_default(READABILITY_STATE_FILE, {"strikes": 0})
     raw_count = payload.get("strikes", 0)
-    is_valid_integer = isinstance(raw_count, int) and not isinstance(raw_count, bool)
-    starting_count = max(raw_count, 0) if is_valid_integer else 0
+    if isinstance(raw_count, int) and not isinstance(raw_count, bool):
+        starting_count = max(raw_count, 0)
+    else:
+        starting_count = 0
     new_count = starting_count + 1
     _atomic_write_json(READABILITY_STATE_FILE, {"strikes": new_count})
     return new_count
@@ -87,31 +89,27 @@ def _reset_strike_count() -> None:
     _atomic_write_json(READABILITY_STATE_FILE, {"strikes": 0})
 
 
+def _resolve_integer_field(
+    all_payload_fields: dict[str, object], field_name: str, default_value: int
+) -> int:
+    raw_value = all_payload_fields.get(field_name, default_value)
+    if isinstance(raw_value, int) and not isinstance(raw_value, bool):
+        return raw_value
+    return default_value
+
+
 def _load_readability_thresholds() -> ReadabilityThresholds:
     payload = _read_json_or_default(READABILITY_THRESHOLD_OVERRIDE_FILE, {})
-    flesch_min_value = payload.get("flesch_min", DEFAULT_READABILITY_THRESHOLDS.flesch_min)
-    max_sentence_value = payload.get(
-        "max_sentence_words", DEFAULT_READABILITY_THRESHOLDS.max_sentence_words
-    )
-    avg_sentence_value = payload.get(
-        "avg_sentence_words", DEFAULT_READABILITY_THRESHOLDS.avg_sentence_words
-    )
-    flesch_is_int = isinstance(flesch_min_value, int) and not isinstance(flesch_min_value, bool)
-    max_is_int = isinstance(max_sentence_value, int) and not isinstance(max_sentence_value, bool)
-    avg_is_int = isinstance(avg_sentence_value, int) and not isinstance(avg_sentence_value, bool)
-    resolved_flesch = (
-        flesch_min_value if flesch_is_int else DEFAULT_READABILITY_THRESHOLDS.flesch_min
-    )
-    resolved_max = (
-        max_sentence_value if max_is_int else DEFAULT_READABILITY_THRESHOLDS.max_sentence_words
-    )
-    resolved_avg = (
-        avg_sentence_value if avg_is_int else DEFAULT_READABILITY_THRESHOLDS.avg_sentence_words
-    )
     return ReadabilityThresholds(
-        flesch_min=resolved_flesch,
-        max_sentence_words=resolved_max,
-        avg_sentence_words=resolved_avg,
+        flesch_min=_resolve_integer_field(
+            payload, "flesch_min", DEFAULT_READABILITY_THRESHOLDS.flesch_min
+        ),
+        max_sentence_words=_resolve_integer_field(
+            payload, "max_sentence_words", DEFAULT_READABILITY_THRESHOLDS.max_sentence_words
+        ),
+        avg_sentence_words=_resolve_integer_field(
+            payload, "avg_sentence_words", DEFAULT_READABILITY_THRESHOLDS.avg_sentence_words
+        ),
     )
 
 

package/package.json

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

package/skills/CLAUDE.md

@@ -26,6 +26,8 @@ Skills install to `~/.claude/skills/<skill-name>/` via `packages/claude-dev-env/
 - `implement` — structured implementation from an existing plan packet
 - `bdd-protocol` — BDD depth: Example Mapping, scenario quality, outside-in layout
 - `verified-build` — build + test loop that gates on a verifier verdict
+- `advisor` — turns the session into the advisor-orchestrator: it spawns executor subagents to do the code edits and test runs, and answers a blocked executor with a plan, correction, or stop
+- `advisor-refresh` — sub-skill fired by the `/advisor` loop to re-assert the executor-advisor discipline mid-run
 
 **PR review and convergence**
 - `autoconverge` — autonomous single-run workflow that drives a PR to ready

package/skills/advisor/SKILL.md

@@ -0,0 +1,137 @@
+---
+name: advisor
+description: >-
+  Turns the session into the advisor-orchestrator — the user's sole interface,
+  which spawns and resumes executor subagents (clean-coder and the like) to do
+  all the code editing and every build or test run. When an executor hits a
+  blocker it consults the advisor, which replies with one of three brief
+  signals — a plan, a correction, or a stop. The advisor orchestrates and
+  advises but never edits code or runs tests itself. Caps consultations per
+  task (default 5), reuses warm agents before spawning new ones, and
+  re-asserts the discipline every 20 minutes through the /advisor-refresh
+  loop. Adapts Anthropic's advisor strategy to Claude Code. Triggers:
+  '/advisor', 'advisor strategy', 'run with an advisor', 'executor-advisor
+  mode'.
+---
+
+# Advisor Strategy
+
+## Principle
+
+A cost-effective executor runs the primary work — it calls tools, reads
+results, and iterates — while a stronger model advises only at the hard
+decisions. Source: Anthropic's advisor strategy,
+https://claude.com/blog/the-advisor-strategy.
+
+Under this skill the session is the advisor-orchestrator. In Claude Code the
+user always talks to the session and never to a subagent, so the session is
+the user's sole interface: all user-facing communication flows through it. It
+spawns and resumes executor subagents — `clean-coder` and the like — and those
+executors do every bit of the execution: the code edits, the build runs, the
+test runs. The advisor drives the plan and answers the executors when they get
+stuck.
+
+This is the advisor-lite shape: the blog's pure pairing keeps the advisor
+tool-less and hidden from the user, but Claude Code routes every user message
+through the session, so the advisor here stays the user's interface while
+keeping execution out of its own hands. Consultations are capped (default 5
+per task) — the same guard the API's `max_uses` gives a tool.
+
+## Gotchas
+
+- **Double invocation duplicates the reminder loop.** A second `/advisor` in
+  the same session schedules a second refresh loop. Check whether the loop is
+  already running before you schedule one (see the invocation guard in
+  Process step 1).
+- **The advisor never executes.** The moment it edits a file or runs the tests
+  itself, the pairing breaks and the executor's warm context is wasted. Hand
+  every code edit and every build or test run to an executor; keep the
+  advisor's own tool use to orchestration and light verification reads.
+- **Resuming an unnamed background agent needs its agentId.** A background
+  spawn returns an `agentId` (format `a...-...`); keep it so `SendMessage` can
+  reach that agent later. A named agent is reachable by name.
+- **Consultations past the cap signal a scoping problem.** When five
+  consultations do not clear the blocker, the task needs re-scoping or a
+  hand-off to the user — not a sixth round of advice.
+
+
+## Process
+
+1. **Invocation guard (once per session).** Before scheduling anything, check
+   whether the refresh loop is already running this session. If it is, skip
+   straight to orchestration — do not schedule a second loop.
+
+2. **Register the discipline reminder.** By default, schedule it with
+   `ScheduleWakeup` at `delaySeconds: 1200`, prompt `/advisor-refresh`, where
+   each refresh re-schedules the next one — a 1200-second wakeup costs one
+   prompt-cache miss per firing and nothing more (see Gotchas). The loop
+   mechanism (`/loop 20m /advisor-refresh`) is the escape hatch when
+   `ScheduleWakeup` is not available. Either way the reminder is the
+   enforcement surface: each firing re-asserts the discipline while the run is
+   in flight.
+
+3. **Orchestrate the task.** Hold the plan and the user conversation. Spawn or
+   resume executor subagents (for example `clean-coder`) to do every code edit
+   and every build or test run, and keep driving while they work. Your own
+   tool use stays orchestration and light verification reads. Keep your task list updated religiously.
+
+4. **Executors consult at a hard decision.** Each executor's spawn prompt tells
+   it to stop and message you — with the task, what it tried, and the exact
+   blocker (plus any short code excerpt that helps) — when one of these holds:
+   - It has tried the same problem twice or more and it still fails.
+   - A decision changes the deliverable's scope or a contract that is hard to
+     reverse.
+   - Two constraints conflict and it cannot satisfy both.
+   - It is unsure whether to stop or keep going.
+
+5. **Answer with one signal.** On a consultation, reply with exactly one
+   signal, brief (about 400 to 700 tokens):
+   - **PLAN** — a different approach, as concrete ordered steps the executor
+     can run. When a warm agent fits the plan, name which one to resume.
+   - **CORRECTION** — the executor's approach is right, one thing is wrong;
+     name the wrong step and the fix.
+   - **STOP** — no path satisfies the task as assigned; say why so it can be
+     reported upward.
+   The executor resumes the moment your reply lands.
+
+   A worked consultation:
+
+   ```
+   Executor → advisor
+   Task: add a retry to the upload client.
+   Tried: wrapped upload() in a three-attempt loop; the second attempt
+   double-posts.
+   Blocker: the server takes no idempotency key, so a retry after a timeout
+   creates a duplicate record.
+
+   Advisor → executor
+   CORRECTION — the retry loop is right; the missing piece is a stable request
+   id. Generate one client-side on the first attempt and send the same id on
+   every retry, so the server treats the retries as one request.
+   ```
+
+   For a decision the advisor itself cannot settle, it may spawn the tool-less
+   `code-advisor` agent for a second opinion — an optional escalation, not a
+   required step.
+
+## Agent reuse (non-negotiable)
+
+- **Resume before you spawn, always.** A warm agent carries its context and
+  cached tokens; a fresh spawn starts cold and pays to rebuild both.
+  `SendMessage` with an agent's name or `agentId` resumes a running or a
+  completed agent with its context intact — verified live in this environment.
+  Prefer that path every time an existing agent holds relevant context.
+- **Spawn a fresh agent only when** no existing agent holds relevant context,
+  or a genuine task switch needs a clean context.
+- **Name the agent to resume.** When you answer with a PLAN and a warm agent
+  fits, say which agent to resume and where.
+
+## Constraints
+
+- One `/advisor` per session; the invocation guard blocks a second reminder
+  loop.
+- The advisor orchestrates and advises but never edits code or runs a build or
+  test itself — executors do that.
+- Consultations are capped at five per task by default. At the cap, re-scope
+  or hand off; do not keep answering.
+- Reuse a warm agent over a cold spawn whenever one holds relevant context.

package/skills/advisor-refresh/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: advisor-refresh
+description: >-
+  Fired by the /advisor loop reminder about every 20 minutes to re-assert the
+  advisor discipline mid-run. A compressed restatement of /advisor: orchestrate
+  rather than execute, answer a blocked executor with a plan, correction, or
+  stop, and reuse warm agents before spawning new ones. Triggers:
+  '/advisor-refresh'.
+---
+
+# Advisor Refresh
+
+1. **You are the advisor.** Orchestrate and hold the user conversation; spawn
+   executor subagents to do all the work — every code edit and build or test
+   run.
+2. **An executor blocked twice on the same thing?** Answer it with one signal
+   — a plan, a correction, or a stop — brief. Never take over the edit or the
+   tests yourself.
+3. **Resume before you spawn.** `SendMessage` an existing agent by name or
+   `agentId` to reuse its warm context; prefer that over a cold spawn.
+4. **Fresh spawn only for a genuine task switch.** No tool compacts or clears a
+   subagent's context, so a clean context comes from a fresh spawn — never tell
+   an agent to compact.
+5. **Re-schedule the next refresh** (about 1200 seconds out) when the loop
+   mechanism needs each firing to queue the following one.

package/skills/autoconverge/SKILL.md

@@ -324,7 +324,10 @@ 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. Dedup findings; one
+  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
@@ -344,8 +347,12 @@ matches.
   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; on a
-  full pass the workflow marks `draft=false`.
+- **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).
 
 ## Multiple PRs
 

package/skills/autoconverge/reference/convergence.md

@@ -46,9 +46,14 @@ tracks CONVERGE passes only and is never the cap.
 
 **CONVERGE** (one round = one parallel sweep):
 
-1. Resolve the current PR HEAD SHA.
+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
-   `origin/main...HEAD` diff:
+   `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.
@@ -89,9 +94,24 @@ tracks CONVERGE passes only and is never the cap.
 
 **Convergence check**:
 
-- Run `check_convergence.py`. A full pass marks the PR ready (`draft=false`) and
-  ends the run. A failure returns to CONVERGE so the next round addresses the
-  failing gate.
+- One agent runs `check_convergence.py` and, on a full pass, marks the PR ready
+  (`draft=false`) in the same turn, ending the run. A failure returns to CONVERGE
+  so the next round addresses the failing gate; the repair path re-runs this same
+  check, and only a passing check marks the PR ready.
+
+## Model tiers
+
+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.
 
 ## Full-diff rule
 

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

@@ -58,7 +58,7 @@ function buildRunGeneralUtilityTask(convergeAgentStub) {
     'CONFIG',
     'prCoordinates',
     'CLEAN_AUDIT_SCHEMA',
-    'READY_SCHEMA',
+    'TIERS',
     'describeStandardsDeferral',
     'describeNotRunLens',
     'serializeOneLineJson',
@@ -70,7 +70,7 @@ function buildRunGeneralUtilityTask(convergeAgentStub) {
     { prLoopScripts: 'x' },
     'coords',
     {},
-    {},
+    { haikuLow: { model: 'haiku', effort: 'low' } },
     describeStandardsDeferral,
     describeNotRunLens,
     serializeOneLineJson,

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

@@ -36,6 +36,14 @@ function functionSource(functionName) {
   return convergeSource.slice(functionStart, functionEnd);
 }
 
+function docstringBefore(functionName) {
+  const functionStart = convergeSource.indexOf(`function ${functionName}(`);
+  assert.notEqual(functionStart, -1, `expected ${functionName} to exist`);
+  const docStart = convergeSource.lastIndexOf('/**', functionStart);
+  assert.notEqual(docStart, -1, `expected a JSDoc block before ${functionName}`);
+  return convergeSource.slice(docStart, functionStart);
+}
+
 test('code-review lens prompt no longer instructs a per-lens git fetch', () => {
   assert.doesNotMatch(lensPromptBody('runCodeReviewLens'), /git fetch origin main/);
 });
@@ -60,10 +68,36 @@ test('the merged preflight-git task fetches origin/main once before the parallel
   assert.match(gitTaskBody, /PREFLIGHT_GIT_SCHEMA/, 'expected the merged task to return the {sha, conflicting, fetched, copilot, bugbot} schema');
 });
 
-test('the merged preflight-git agent runs on haiku at low effort', () => {
+test('the merged preflight-git agent spreads the haikuLow tier', () => {
   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');
+  assert.match(
+    gitTaskBody,
+    /\.\.\.TIERS\.haikuLow/,
+    'expected the git-utility agent to spread the single-sourced haikuLow tier rather than inline model/effort literals',
+  );
+  assert.doesNotMatch(
+    gitTaskBody,
+    /model: 'haiku', effort: 'low'/,
+    'expected no inline haikuLow literals duplicating the TIERS definition',
+  );
+});
+
+test('the preflight-git prompt states the correct number of read-only steps it enumerates', () => {
+  const body = functionSource('runGitTask');
+  assert.match(
+    body,
+    /Run five read-only preflight steps/,
+    'expected the stated step count to match the five enumerated STEP blocks',
+  );
+  assert.match(body, /STEP 5 —/, 'expected the fifth step to be enumerated');
+  assert.doesNotMatch(body, /Run four read-only preflight steps/);
+});
+
+test('the runGitTask docstring names the diff enumeration and its changedFiles/diffstat return fields', () => {
+  const doc = docstringBefore('runGitTask');
+  assert.match(doc, /diff|changed-file|enumerat/i, 'expected the docstring to name the diff enumeration operation');
+  assert.match(doc, /changedFiles/, 'expected the docstring return shape to name changedFiles');
+  assert.match(doc, /diffstat/, 'expected the docstring return shape to name diffstat');
 });
 
 test('the reviewer-availability probe rides the merged preflight-git spawn, not a separate agent', () => {
@@ -98,7 +132,7 @@ test('the Bugbot lens is not spawned pre-spawn when the shared gate reports Bugb
   const lensArray = convergeSource.slice(parallelLensIndex, lensArrayEnd);
   assert.match(
     lensArray,
-    /isBugbotDownPreSpawn \? Promise\.resolve\(\{ sha: head, clean: true, down: true, notSpawned: true, findings: \[\] \}\) : runBugbotLens\(head\)/,
+    /isBugbotDownPreSpawn \? Promise\.resolve\(\{ sha: head, clean: true, down: true, notSpawned: true, findings: \[\] \}\) : runBugbotLens\(head, reviewerAvailability\)/,
     'expected the Bugbot lens slot to substitute a resolved down placeholder instead of spawning runBugbotLens when isBugbotDownPreSpawn is true',
   );
 });
@@ -263,7 +297,7 @@ test('the COPILOT fix branch does not re-assign head from the fix before re-conv
 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 invalidGuardIndex = convergeSource.indexOf('if (!isResolvedHeadUsable(head))', convergeBranchStart);
+  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');
@@ -273,6 +307,19 @@ test('the CONVERGE branch refreshes HEAD via the merged preflight-git task only
   );
 });
 
+test('the CONVERGE branch refreshes preflight when the availability enumeration was computed against a different SHA than the head under review', () => {
+  const convergeBranchStart = convergeSource.indexOf("if (phase === 'CONVERGE')");
+  assert.notEqual(convergeBranchStart, -1, 'expected the CONVERGE branch to exist');
+  const guardIndex = convergeSource.indexOf('if (!isResolvedHeadUsable(head)', convergeBranchStart);
+  assert.notEqual(guardIndex, -1, 'expected the refresh guard to exist');
+  const guardLine = convergeSource.slice(guardIndex, convergeSource.indexOf('\n', guardIndex));
+  assert.match(
+    guardLine,
+    /reviewerAvailability\?\.sha !== head/,
+    'expected the refresh guard to fire when the reviewerAvailability changed-file enumeration was computed against a SHA other than the current head, so a rebase or reuse push that advances HEAD before round 1 hands the lenses the diff for the head they actually review',
+  );
+});
+
 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(
@@ -830,8 +877,18 @@ for (const { name, isAsync } of taskDispatchers) {
   });
 }
 
-test('runGeneralUtilityTask only handles the two tasks it is called with', () => {
+test('runGeneralUtilityTask only handles the post-clean-audit task it is called with', () => {
   const generalBody = functionSource('runGeneralUtilityTask');
+  assert.match(
+    generalBody,
+    /task === 'post-clean-audit'/,
+    'expected runGeneralUtilityTask to handle the post-clean-audit task',
+  );
+  assert.doesNotMatch(
+    generalBody,
+    /task === 'mark-ready'/,
+    'the mark-ready step is merged into the FINALIZE convergence check (runConvergenceCheck), so its branch must be removed here',
+  );
   assert.doesNotMatch(
     generalBody,
     /task === 'bugbot-lens'/,
@@ -1041,3 +1098,116 @@ test('the Monitor ceiling the guidance names covers the longest interval-times-a
     );
   }
 });
+
+function optionsLineForLabel(label) {
+  const labelIndex = convergeSource.indexOf(`label: '${label}'`);
+  assert.notEqual(labelIndex, -1, `expected an agent options object labeled ${label}`);
+  const lineStart = convergeSource.lastIndexOf('\n', labelIndex);
+  const lineEnd = convergeSource.indexOf('\n', labelIndex);
+  return convergeSource.slice(lineStart, lineEnd);
+}
+
+test('the TIERS map defines the opus/sonnet/haiku model-effort tiers', () => {
+  assert.match(convergeSource, /opusMedium:\s*\{ model: 'opus', effort: 'medium' \}/);
+  assert.match(convergeSource, /sonnetMedium:\s*\{ model: 'sonnet', effort: 'medium' \}/);
+  assert.match(convergeSource, /haikuLow:\s*\{ model: 'haiku', effort: 'low' \}/);
+});
+
+test('every convergeAgent spawn options object carries a model and effort tier', () => {
+  const optionObjects = convergeSource.match(/\{ label[^\n]*\}/g) || [];
+  assert.ok(
+    optionObjects.length >= 20,
+    `expected to find the per-spawn options objects, found ${optionObjects.length}`,
+  );
+  for (const optionObject of optionObjects) {
+    const hasTier = optionObject.includes('...TIERS.');
+    const hasInlineModelEffort = /model:\s*'/.test(optionObject) && /effort:\s*'/.test(optionObject);
+    assert.ok(
+      hasTier || hasInlineModelEffort,
+      `expected the spawn options to carry a model and effort tier: ${optionObject}`,
+    );
+  }
+});
+
+test('the four review lenses run on the opusMedium tier', () => {
+  for (const label of ['lens:bugbot', 'lens:code-review', 'lens:bug-audit', 'lens:reuse']) {
+    assert.match(
+      optionsLineForLabel(label),
+      /\.\.\.TIERS\.opusMedium/,
+      `expected ${label} to run on the opusMedium tier`,
+    );
+  }
+});
+
+test('the copilot gate runs on the haikuLow tier', () => {
+  assert.match(optionsLineForLabel('copilot-gate'), /\.\.\.TIERS\.haikuLow/);
+});
+
+test('the merged finalize convergence check runs on the haikuLow tier', () => {
+  assert.match(functionSource('runConvergenceCheck'), /\.\.\.TIERS\.haikuLow/);
+});
+
+test('the preflight-git task returns the changed-file list and diffstat for the lenses', () => {
+  const body = functionSource('runGitTask');
+  assert.match(body, /git diff --name-status origin\/main\.\.\.HEAD/);
+  assert.match(body, /git diff --stat origin\/main\.\.\.HEAD/);
+  assert.match(body, /changedFiles/);
+  assert.match(body, /diffstat/);
+  const schemaStart = convergeSource.indexOf('const PREFLIGHT_GIT_SCHEMA =');
+  const schemaEnd = convergeSource.indexOf('\n}', schemaStart);
+  const schema = convergeSource.slice(schemaStart, schemaEnd);
+  assert.match(schema, /changedFiles:/);
+  assert.match(schema, /diffstat:/);
+  assert.match(schema, /required:[^\n]*'changedFiles'[^\n]*'diffstat'/);
+});
+
+test('each per-round lens and the reuse lens inject the preflight changed-file context', () => {
+  for (const builder of ['runBugbotLens', 'runCodeReviewLens', 'runAuditLens', 'runReuseAuditPass']) {
+    assert.match(
+      lensPromptBody(builder),
+      /renderLensDiffContext\(preflightResult\)/,
+      `expected ${builder} to inject the changed-file context from the preflight result`,
+    );
+  }
+});
+
+test('renderLensDiffContext reuses the changed-file list when present and falls back to self-enumeration otherwise', () => {
+  const renderLensDiffContext = new Function(
+    `${functionSource('renderLensDiffContext')}\nreturn renderLensDiffContext;`,
+  )();
+  const withList = renderLensDiffContext({ changedFiles: 'M\ta.py', diffstat: ' a.py | 2 +-' });
+  assert.match(withList, /Changed files/);
+  assert.match(withList, /a\.py/);
+  const fallback = renderLensDiffContext(null);
+  assert.match(fallback, /git diff --name-only/, 'expected a missing file list to fall back to self-enumeration');
+});
+
+test('the merged FINALIZE check runs check_convergence then marks the PR ready on pass in one agent', () => {
+  const body = functionSource('runConvergenceCheck');
+  assert.match(body, /check_convergence\.py/, 'expected the merged check to run check_convergence.py');
+  assert.match(body, /gh pr ready/, 'expected the merged check to mark the PR ready on the passing path');
+  assert.match(body, /schema: FINALIZE_SCHEMA/, 'expected the merged check to return the {pass, failures, ready} schema');
+  assert.match(body, /context\.copilotDown/, 'expected the merged check to carry the copilotDown opt-out context');
+});
+
+test('FINALIZE_SCHEMA carries pass, failures, and ready', () => {
+  const schemaStart = convergeSource.indexOf('const FINALIZE_SCHEMA =');
+  assert.notEqual(schemaStart, -1, 'expected FINALIZE_SCHEMA to exist');
+  const schema = convergeSource.slice(schemaStart, convergeSource.indexOf('\n}', schemaStart));
+  for (const field of ['pass', 'failures', 'ready']) {
+    assert.match(schema, new RegExp(`${field}:`), `expected FINALIZE_SCHEMA to carry ${field}`);
+  }
+});
+
+test('the FINALIZE phase drives the merged check and reads ready from its result without a separate mark-ready spawn', () => {
+  const finalizeStart = convergeSource.indexOf("if (phase === 'FINALIZE') {");
+  assert.notEqual(finalizeStart, -1, 'expected a FINALIZE phase block');
+  const finalizeBody = convergeSource.slice(finalizeStart, finalizeStart + 1000);
+  assert.match(finalizeBody, /runConvergenceCheck\(\{ head, bugbotDown, copilotDown \}\)/);
+  assert.match(finalizeBody, /classifyReadyOutcome\(finalizeResult\)/);
+  assert.doesNotMatch(
+    finalizeBody,
+    /runGeneralUtilityTask\('mark-ready'/,
+    'the separate mark-ready spawn is merged into the FINALIZE convergence check',
+  );
+});