claude-dev-env 1.94.0 → 2.0.0

package/skills/pr-converge/CLAUDE.md

@@ -28,4 +28,4 @@ Drives a draft PR to convergence by driving the internal passes to clean first
 - All findings and PR reports state verified facts only — no hedging language.
 - The GitHub MCP (`pull_request_read`, `pull_request_review_write`) is the primary path for PR inspection; `gh api` is the fallback.
 - Three step-scoped agents (`fix_executor`, `thread_sweep`, `copilot_watch`) persist across ticks via the `persistent_agents` map in loop state; each tick resumes them with `SendMessage` and spawns a fresh named agent when a stored id is dead.
-- The tick delegates shared mechanics to five sibling sub-skills: `reviewer-gates` (opt-out, Copilot quota, Bugbot trigger), `pr-scope-resolve` (target resolution), `pr-fix-protocol` (fix sequence + unresolved-thread sweep), `post-audit-findings` (audit posting), and `pr-loop-lifecycle` (run open/close).
+- The tick delegates shared mechanics to three sibling sub-skills: `reviewer-gates` (opt-out, Copilot quota, Bugbot trigger), `pr-fix-protocol` (fix sequence + unresolved-thread sweep), and `pr-loop-lifecycle` (run open/close). Target resolution happens inline in `reference/per-tick.md` Steps 1 and 1.5. Audit posting follows the `_shared/pr-loop/post-audit-thread-contract.md` contract, run through `_shared/pr-loop/scripts/post_audit_thread.py`.

package/skills/pr-converge/SKILL.md

@@ -153,11 +153,12 @@ the `persistent_agents` map
   within one bounded wait, drop the map entry, spawn a fresh named agent,
   record it, and continue the tick. Never abort a tick on a stale id;
   never retry the same dead id.
-- **Fresh every round (never persisted):** the Step 5 `/code-review high --fix`
-  pass and the Step 6 bugteam audit (unbiased eyes each round; the
-  enforcer needs the formal Skill call), and every `code-verifier` — a
-  named code-verifier never fires `SubagentStop`, so no verdict mints (see
-  the named-`code-verifier` entry in the Gotchas list below).
+- **Fresh every round (never persisted):** the Step 5 host-aware
+  `invoke_code_review.py` / `/code-review high --fix` pass and the Step 6
+  bugteam audit (unbiased eyes each round; the enforcer needs the formal
+  Skill call), and every `code-verifier` — a named code-verifier never fires
+  `SubagentStop`, so no verdict mints (see the named-`code-verifier` entry
+  in the Gotchas list below).
 - **Shutdown:** at loop end (convergence or a stop condition), send each
   persistent agent a shutdown request and clear `persistent_agents` before
   the `pr-loop-lifecycle` Close.
@@ -206,11 +207,11 @@ post a fresh PR in a fresh branch based on origin main to the user.
   `pwsh` calls run through the PowerShell tool, not Bash. Bash on
   Windows is Git Bash which cannot execute PowerShell cmdlets. Route all
   PowerShell work through the PowerShell tool or `pwsh -NoProfile -File`.
-- **Cross-repo PR: route cwd into the PR worktree before `/code-review`** —
-  `/code-review high --fix` (Step 5) audits the repo of the current working
-  directory. When the session is rooted in a different repo than the PR,
-  `EnterWorktree` cannot re-root (it is scoped to the session's repo);
-  resolve the PR worktree and `cd` into it per
+- **Cross-repo PR: route cwd into the PR worktree before Step 5 review** —
+  `invoke_code_review.py` and `/code-review high --fix` audit the repo of the
+  cwd (the helper's `--cwd`). When the session is rooted in a different repo
+  than the PR, `EnterWorktree` cannot re-root (it is scoped to the session's
+  repo); resolve the PR worktree and `cd` into it per
   [Step 1.5](reference/per-tick.md). Skipping this reviews and edits the
   wrong repo. The route is routine and automatic — never a material fork
   to pause on.
@@ -292,12 +293,32 @@ round as converged. This rule holds every tick, every loop, every PR.
       See: [`reference/per-tick.md` § CODE_REVIEW entry](reference/per-tick.md).
       Pre-condition: cwd is the Step 1.5 PR worktree on `current_head`.
       Scope: FULL `origin/main...HEAD` diff every tick (no path args, no delta cut).
+      Review always runs at effort high on model opus through
+      `invoke_code_review.py`. Mode decision inputs: host profile + session
+      model. Call:
+      `python "$HOME/.claude/scripts/invoke_code_review.py" --cwd <PR-worktree>
+      --session-model <alias>`. Chain mode uses that cwd and empty stdin; the
+      chain process never commits and never pushes. JSON stdout carries
+      `mode` (`in_session` | `chain`), `served_command`, `returncode`, and
+      `dirty_tree`. Config/host errors still emit that JSON with non-zero
+      `returncode` (no traceback-only failure).
 
       - [ ] **Static sweep fails** → apply shared fix protocol → push → reset markers
             → stay CODE_REVIEW → Step 5
-      - [ ] **`/code-review high --fix` applies fixes** → commit + push → reset markers
-            → stay CODE_REVIEW → Step 5
-      - [ ] **clean** → zero unresolved threads (else fix + resolve) →
+      - [ ] **`mode == in_session`** (Claude host, session model opus) → run
+            `/code-review high --fix` in-session (no path args)
+      - [ ] **`mode == chain`** (any other host or non-opus session) → helper
+            already ran the headless review; read `returncode`,
+            `served_command`, and `dirty_tree` from JSON
+      - [ ] **failed review** (`returncode != 0`, or chain with null
+            `served_command`) → do not set `code_review_clean_at` → stay
+            CODE_REVIEW → Step 5
+      - [ ] **fixes applied** (`dirty_tree` true / working tree dirty) →
+            commit + push via shared fix protocol → reset markers → stay
+            CODE_REVIEW → Step 5
+      - [ ] **clean** (successful serve: `returncode == 0`, chain
+            `served_command` non-null when chain, and `dirty_tree` false) →
+            zero unresolved threads (else fix + resolve) →
             `code_review_clean_at = current_head` → `phase = BUGTEAM` → Step 6
 
 - [ ] **Step 6: BUGTEAM — run, decide, fix, reply, resolve**

package/skills/pr-converge/reference/convergence-gates.md

@@ -8,11 +8,12 @@
 - [(d) Post-convergence Copilot review request](#d-post-convergence-copilot-review-request)
 - [(e) Thread-resolution gate](#e-thread-resolution-gate)
 - [(f) Mark ready and report](#f-mark-ready-and-report)
+- [(g) Codex review gate (conditional-required)](#g-codex-review-gate-conditional-required)
 Run **only** after the terminal Bugbot gate confirms the HEAD
 (`bugbot_clean_at == current_head` OR `bugbot_down`), which runs just before
 these gates once Step 2 BUGTEAM reports `convergence (zero findings)` with no
 push during the bugteam tick. Gates run in order; first failure determines
-next-tick behavior. Mark PR ready only when all six pass.
+next-tick behavior. Mark PR ready only when every gate that applies passes.
 
 **Mandatory evidence rule:** Every gate that fetches data MUST produce a
 summary of its findings before proceeding to the next gate. Gate (f) MUST
@@ -47,7 +48,7 @@ Decide (four branches; match first whose predicate holds):
   dirty). Apply the shared fix protocol ([`../../../_shared/pr-loop/fix-protocol.md`](../../../_shared/pr-loop/fix-protocol.md); skill deltas in [`fix-protocol.md`](fix-protocol.md)) in the same tick.
   Reset push-invalidated markers per [ground-rules.md](ground-rules.md) /
   [state-schema.md](state-schema.md) (all `*_clean_at`, `merge_state_status`,
-  `bugbot_down`, `bugbot_acknowledged_at`), `phase = CODE_REVIEW`, schedule
+  `bugbot_down`, `bugbot_acknowledged_at`, `codex_down`), `phase = CODE_REVIEW`, schedule
   next wakeup, return. Full back-to-back-clean cycle plus all six gates must
   hold again on new HEAD.
 - **`classification == "dirty"` with empty inline comments matching
@@ -59,7 +60,7 @@ Decide (four branches; match first whose predicate holds):
   new HEAD SHA. Reset push-invalidated markers per
   [ground-rules.md](ground-rules.md) / [state-schema.md](state-schema.md)
   (all `*_clean_at`, `merge_state_status`, `bugbot_down`,
-  `bugbot_acknowledged_at`), `phase = CODE_REVIEW`, schedule next wakeup,
+  `bugbot_acknowledged_at`, `codex_down`), `phase = CODE_REVIEW`, schedule next wakeup,
   return. Convergence needs full back-to-back-clean on new HEAD.
 - **`classification == "clean"` (state `APPROVED`):** Set
   `copilot_clean_at = current_head`. Record evidence: "Copilot APPROVED at <SHA>".
@@ -90,7 +91,7 @@ Decide (four branches; match first whose predicate holds):
   path — apply the shared fix protocol ([`../../../_shared/pr-loop/fix-protocol.md`](../../../_shared/pr-loop/fix-protocol.md); skill deltas in [`fix-protocol.md`](fix-protocol.md)). Reset push-invalidated markers per
   [ground-rules.md](ground-rules.md) / [state-schema.md](state-schema.md)
   (all `*_clean_at`, `merge_state_status`, `bugbot_down`,
-  `bugbot_acknowledged_at`), `phase = CODE_REVIEW`, schedule next wakeup,
+  `bugbot_acknowledged_at`, `codex_down`), `phase = CODE_REVIEW`, schedule next wakeup,
   return.
 - **`classification == "dirty"` with empty inline comments matching
   `pull_request_review_id`:** Claude posted findings only in review body
@@ -99,7 +100,7 @@ Decide (four branches; match first whose predicate holds):
   shared fix protocol ([`../../../_shared/pr-loop/fix-protocol.md`](../../../_shared/pr-loop/fix-protocol.md); skill deltas in [`fix-protocol.md`](fix-protocol.md)). Reset
   push-invalidated markers per [ground-rules.md](ground-rules.md) /
   [state-schema.md](state-schema.md) (all `*_clean_at`, `merge_state_status`,
-  `bugbot_down`, `bugbot_acknowledged_at`), `phase = CODE_REVIEW`, schedule
+  `bugbot_down`, `bugbot_acknowledged_at`, `codex_down`), `phase = CODE_REVIEW`, schedule
   next wakeup, return.
 - **`classification == "clean"` (state `APPROVED`):** Record evidence:
   "Claude APPROVED at <SHA>". Continue to gate (c).
@@ -127,7 +128,7 @@ Persist `mergeable_state` into `merge_state_status`. Decide:
   every prior clean state — reset push-invalidated markers per
   [ground-rules.md](ground-rules.md) / [state-schema.md](state-schema.md)
   (all `*_clean_at`, `merge_state_status`, `bugbot_down`,
-  `bugbot_acknowledged_at`), `phase = CODE_REVIEW`, schedule next wakeup,
+  `bugbot_acknowledged_at`, `codex_down`), `phase = CODE_REVIEW`, schedule next wakeup,
   return. Loop re-runs from scratch on new HEAD.
 - **`mergeable_state` is `"blocked"`, `"behind"`, `"unknown"`, or `"unstable"` for
   non-conflict reasons** (required checks pending/failing for "unstable",
@@ -173,7 +174,7 @@ against `current_head`. Decide:
     Treat identically to gate (a) dirty path — apply the shared fix protocol ([`../../../_shared/pr-loop/fix-protocol.md`](../../../_shared/pr-loop/fix-protocol.md); skill deltas in [`fix-protocol.md`](fix-protocol.md)).
     Reset push-invalidated markers per [ground-rules.md](ground-rules.md) /
     [state-schema.md](state-schema.md) (all `*_clean_at`, `merge_state_status`,
-    `bugbot_down`, `bugbot_acknowledged_at`), `phase = CODE_REVIEW`, schedule
+    `bugbot_down`, `bugbot_acknowledged_at`, `codex_down`), `phase = CODE_REVIEW`, schedule
     next wakeup, return.
 - **No Copilot review at `current_head` yet:** Record evidence: "No Copilot
   review at <SHA> (wait count: <N>)". Increment `copilot_wait_count`
@@ -207,7 +208,7 @@ Decide:
   shared fix protocol unresolved-thread sweep ([`../../../_shared/pr-loop/fix-protocol.md`](../../../_shared/pr-loop/fix-protocol.md) step 12; skill deltas in [`fix-protocol.md`](fix-protocol.md)). Push if any code changed → reset
   push-invalidated markers per [ground-rules.md](ground-rules.md) /
   [state-schema.md](state-schema.md) (all `*_clean_at`, `merge_state_status`,
-  `bugbot_down`, `bugbot_acknowledged_at`), `phase = CODE_REVIEW`, schedule
+  `bugbot_down`, `bugbot_acknowledged_at`, `codex_down`), `phase = CODE_REVIEW`, schedule
   next wakeup, return. If only resolutions (no code changes), re-check this
   gate without resetting.
 
@@ -218,7 +219,8 @@ Decide:
 ```
 python $HOME/.claude/skills/pr-converge/scripts/check_convergence.py \
   --owner <O> --repo <R> --pr-number <N> \
-  [--bugbot-down] [--copilot-down]
+  [--bugbot-down] [--copilot-down] [--codex-down] \
+  [--codex-clean-at <SHA>]
 ```
 
 Ready means exit `0` and the line:
@@ -233,11 +235,13 @@ Exact printed labels (script order):
 2. `bugbot review body clean` (omitted when `bugbot_down`)
 3. `bugteam_clean_at == current_head`
 4. `copilot_clean_at == current_head`
-5. `zero unresolved bot threads`
-6. `PR is mergeable`
-7. `no pending requested reviews`
+5. `codex_clean_at == current_head` (skipped when usage is at/below threshold,
+   null, `codex_down`, or the `codex` opt-out token)
+6. `zero unresolved bot threads`
+7. `PR is mergeable`
+8. `no pending requested reviews`
 
-On label 5: `isOutdated == true` excludes the thread; bot filter is login
+On label 6: `isOutdated == true` excludes the thread; bot filter is login
 substrings `cursor` | `claude` | `copilot` only. The script has no Claude
 APPROVED review gate.
 
@@ -248,7 +252,7 @@ before invoking the script; they never appear as `check_convergence.py` labels.
 
 When the script fails (exit 1), do NOT mark ready. Report the FAIL label and
 route through the matching fix path (BUGBOT for dirty reviews, rebase for
-merge conflicts, and so on).
+merge conflicts, Codex findings via the shared fix protocol, and so on).
 
 When the script passes (exit 0):
 
@@ -258,5 +262,28 @@ Use the `update_pull_request` MCP tool:
 
 With `state.json`, append convergence row to
 `<TMPDIR>/pr-converge-<session_id>/converged.log` per `multi-pr-orchestration.md` §Memory; else skip.
-Report from the script's PASS lines (the seven labels above). **Omit loop
+Report from the script's PASS lines (the eight labels above). **Omit loop
 pacing** per **Convergence** of active pacing workflow.
+
+## (g) Codex review gate (conditional-required)
+
+Machine condition label: `codex_clean_at == current_head`.
+
+**Threshold rule** (shared with `codex_usage_probe.py` —
+`WEEKLY_USAGE_GATE_THRESHOLD_PERCENT`; never restate the numeric literal):
+
+- When the weekly probe reports **more than** the threshold percent left: a
+  clean Codex review on `current_head` is required. Stamp
+  `codex_clean_at = current_head` after a clean skill run, and pass
+  `--codex-clean-at <SHA>` (or keep it in `$CLAUDE_JOB_DIR/pr-converge-state.json`)
+  so `check_convergence.py` can verify the stamp.
+- When usage is **at or below** the threshold, or `percent_left` is null: the
+  gate is skipped and never blocks ready.
+- When `codex_down == true`, when `CLAUDE_REVIEWS_DISABLED` lists `codex`, or
+  when the caller passes `--codex-down`: the gate is bypassed and never blocks.
+
+**Agent path before the machine checklist:** run the usage probe, then when
+required and not opted out, invoke the `codex-review` skill against the PR base
+branch (HEAD vs base) per [per-tick.md](per-tick.md). Findings enter the shared
+fix protocol; a `codex_down` classification sets `codex_down = true` and
+continues without blocking.

package/skills/pr-converge/reference/fix-protocol.md

@@ -17,7 +17,7 @@ obligations and the same-tick re-entry rule.
 - Writes `last_action: "fix_pushed"`, `current_head: <new SHA>`,
   `bugbot_clean_at: null`, `code_review_clean_at: null`,
   `bugteam_clean_at: null`, `copilot_clean_at: null`,
-  `merge_state_status: null`, `bugbot_down: false`,
+  `merge_state_status: null`, `bugbot_down: false`, `codex_down: false`,
   `phase: "CODE_REVIEW"`, `status: "awaiting_code_review"`, `last_updated`
   (ISO-8601 UTC) to `state.json` (per §Concurrency).
 - Goes idle. Orchestrator spawns a follow-up `general-purpose` agent for the

package/skills/pr-converge/reference/ground-rules.md

@@ -7,7 +7,7 @@
 - **Bugbot findings on the current SHA mean fix-then-push-then-re-enter
   CODE_REVIEW,** so the internal passes re-clear the new HEAD before the terminal
   Bugbot gate runs again.
-- **All `*_clean_at`, `merge_state_status`, and `bugbot_down` reset on every push.**
+- **All `*_clean_at`, `merge_state_status`, and `bugbot_down` / `codex_down` reset on every push.**
 - **`bugbot run` comment is load-bearing.** Literal phrase exactly —
   empirically the only re-trigger Cursor Bugbot recognizes.
 - **Production edits go through `clean-coder`, except `/code-review high --fix`.**

package/skills/pr-converge/reference/per-tick.md

@@ -53,8 +53,8 @@ pull_request_read(owner=OWNER, repo=REPO, pullNumber=NUMBER, method="get") → `
 If owner/repo/number are not yet known, extract them from the PR URL.
 If `current_head` changed since last tick, reset push-invalidated markers
 per [ground-rules.md](ground-rules.md) / [state-schema.md](state-schema.md)
-(all `*_clean_at`, `merge_state_status`, `bugbot_down`, `bugbot_acknowledged_at`) —
-new HEAD invalidates prior clean and down-detection state.
+(all `*_clean_at`, `merge_state_status`, `bugbot_down`, `bugbot_acknowledged_at`,
+`codex_down`) — new HEAD invalidates prior clean and down-detection state.
 
 Capture `number`, `head.sha` (= `current_head`), owner/repo, branch.
 
@@ -171,9 +171,10 @@ CODE_REVIEW.
 ### `phase == CODE_REVIEW`
 
 The entry phase of every convergence tick, re-entered after any fix push. It runs
-a deterministic static sweep, then Claude Code's built-in `/code-review high
---fix` on the full `origin/main...HEAD` diff; `/code-review` produces no GitHub
-review artifact, so there are no code-review threads to resolve.
+a deterministic static sweep, then the built-in `/code-review high --fix` on the
+full `origin/main...HEAD` diff at effort high on model opus. `/code-review`
+produces no GitHub review artifact, so there are no code-review threads to
+resolve.
 
 a. **Static sweep — runs first, before `/code-review`.** Run the deterministic
    gates over the full `origin/main...HEAD` changed files:
@@ -182,41 +183,85 @@ a. **Static sweep — runs first, before `/code-review`.** Run the deterministic
    shared fix protocol ([`../../../_shared/pr-loop/fix-protocol.md`](../../../_shared/pr-loop/fix-protocol.md); skill deltas in [`fix-protocol.md`](fix-protocol.md)), commit and push,
    reset push-invalidated markers per [ground-rules.md](ground-rules.md) /
    [state-schema.md](state-schema.md) (all `*_clean_at`, `merge_state_status`,
-   `bugbot_down`, `bugbot_acknowledged_at`), stay `phase = CODE_REVIEW`, and
-   re-run the sweep. When the sweep is clean, run `/code-review` below.
+   `bugbot_down`, `bugbot_acknowledged_at`, `codex_down`), stay
+   `phase = CODE_REVIEW`, and re-run the sweep. When the sweep is clean, run
+   the host-aware review below.
 
-b. Run Claude Code's built-in `/code-review high --fix` on the FULL
-   `origin/main...HEAD` diff — every file the PR touches — via the
+b. Run the built-in `/code-review high --fix` on the FULL `origin/main...HEAD`
+   diff — every file the PR touches — via the
    [local diff review](https://code.claude.com/docs/en/code-review#review-a-diff-locally).
-   It reviews the diff and applies its findings to the working tree.
+   The review always runs at effort high on model opus. It reviews the diff and
+   applies its findings to the working tree.
 
    Before running, confirm the working directory is the PR worktree resolved
    in [Step 1.5](#step-15-resolve-the-pr-worktree-cwd-routing) — `git rev-parse
    --show-toplevel` is that checkout and `git rev-parse HEAD` equals
    `current_head` — with no uncommitted edits. When the session is rooted in a
    different repo than the PR, the `cd` from Step 1.5 supplies this; the
-   persisted working directory is what `/code-review` audits. Then invoke
-   `/code-review high --fix` with no path arguments so it audits the whole branch
-   diff against `origin/main`. Do not delta-scope to commits added since the
-   prior clean SHA, do not scope to a single file, do not scope to bugbot's
-   flagged paths. A partial-scope round does not count and cannot set
-   `code_review_clean_at`. Invoke `/code-review high --fix` so the pre-catch pass
-   gets broad coverage regardless of the session's current effort.
+   persisted working directory is the cwd the review audits.
 
-c. Decide (two branches; match first whose predicate holds):
+   Route every CODE_REVIEW pass through the host-aware helper
+   `invoke_code_review.py`. Mode decision inputs are the host profile (detected
+   by the helper) and the caller's session model short alias:
 
-   - **`/code-review` applied fixes (working tree changed):** Commit the
+   ```bash
+   python "$HOME/.claude/scripts/invoke_code_review.py" \
+     --cwd "$(git rev-parse --show-toplevel)" \
+     --session-model <session-model-alias>
+   ```
+
+   The helper prints one JSON object on stdout only:
+   `{mode, served_command, returncode, dirty_tree}`. Chain mode sets cwd to the
+   PR worktree and redirects stdin from the empty stream so the spawn does not
+   wait for interactive input. The chain process never commits and never pushes
+   — commit and push belong to this step via the shared fix protocol. On
+   `ChainConfigurationError` or host `ValueError`, the helper still prints that
+   JSON shape (non-zero `returncode`, null `served_command`) and exits non-zero
+   — never a traceback-only failure.
+
+   Match the first mode whose predicate holds:
+
+   - **`mode == "in_session"`** (Claude host and session model is opus): run
+     `/code-review high --fix` in this session with no path arguments so it
+     audits the whole branch diff against `origin/main`. After it returns, a
+     non-empty `git status --porcelain` means fixes applied (`dirty_tree`
+     equivalent). Treat a failed in-session slash command the same as a failed
+     review: do not set `code_review_clean_at`.
+   - **`mode == "chain"`** (any other host, or a Claude session on any model
+     other than opus): the helper already ran the headless review
+     (`claude -p "/code-review high --fix" --model opus` through the chain
+     runner) with cwd set to the PR worktree. Read `returncode`,
+     `served_command`, and `dirty_tree` from the JSON. A successful serve is
+     `returncode == 0` with a non-null `served_command`. `dirty_tree` true
+     means fixes applied; `dirty_tree` false is clean only after a successful
+     serve.
+
+   Do not delta-scope to commits added since the prior clean SHA, do not scope
+   to a single file, do not scope to bugbot's flagged paths. A partial-scope
+   round does not count and cannot set `code_review_clean_at`.
+
+c. Decide (three branches; match first whose predicate holds):
+
+   - **Failed review (`returncode != 0`, or chain mode with null
+     `served_command`):** The review did not complete a successful serve. Do
+     not set `code_review_clean_at`. Stay `phase = CODE_REVIEW`, schedule next
+     wakeup, return. A failed chain often leaves `dirty_tree` false — that is
+     not a clean stamp.
+   - **Fixes applied (working tree dirty / `dirty_tree` true):** Commit the
      applied fixes in one commit → push, following the shared fix protocol
      commit and push steps ([`../../../_shared/pr-loop/fix-protocol.md`](../../../_shared/pr-loop/fix-protocol.md)). Reset
      push-invalidated markers per [ground-rules.md](ground-rules.md) /
      [state-schema.md](state-schema.md) (all `*_clean_at`, `merge_state_status`,
-     `bugbot_down`, `bugbot_acknowledged_at`). Stay `phase = CODE_REVIEW`,
-     schedule next wakeup, return. Every fix push re-enters the internal
-     passes on the new HEAD.
-   - **Clean (no changes applied):** Set
+     `bugbot_down`, `bugbot_acknowledged_at`, `codex_down`). Stay
+     `phase = CODE_REVIEW`, schedule next wakeup, return. Every fix push
+     re-enters the internal passes on the new HEAD.
+   - **Clean (successful serve: `returncode == 0`, chain `served_command`
+     non-null when `mode == chain`, and `dirty_tree` false):** Set
      `code_review_clean_at = current_head`, `phase = BUGTEAM`. Continue
      BUGTEAM in same tick — back-to-back convergence requires code-review and
-     bugteam clean on the same HEAD before the terminal gates run.
+     bugteam clean on the same HEAD before the terminal gates run. Helper
+     contract: `is_code_review_clean_stamp_allowed` is true only for this
+     branch.
 
 ### `phase == BUGTEAM`
 
@@ -263,8 +308,8 @@ pushed commits during its run. `current_head` from Step 1 is stale:
    If `new_head != current_head`, set `current_head = new_head` and reset
    push-invalidated markers per [ground-rules.md](ground-rules.md) /
    [state-schema.md](state-schema.md) (all `*_clean_at`, `merge_state_status`,
-   `bugbot_down`, `bugbot_acknowledged_at`). New commits invalidate prior
-   clean and down-detection state.
+   `bugbot_down`, `bugbot_acknowledged_at`, `codex_down`). New commits
+   invalidate prior clean and down-detection state.
 
 c. Inspect bugteam outcome. Reports `convergence (zero findings)` or list
 of unfixed findings with file:line.
@@ -283,8 +328,8 @@ never falsely terminates:
      ([`../../../_shared/pr-loop/fix-protocol.md`](../../../_shared/pr-loop/fix-protocol.md); skill deltas in [fix-protocol.md](fix-protocol.md)). Reset push-invalidated markers
      per [ground-rules.md](ground-rules.md) / [state-schema.md](state-schema.md)
      (all `*_clean_at`, `merge_state_status`, `bugbot_down`,
-     `bugbot_acknowledged_at`), `phase = CODE_REVIEW`, schedule next wakeup,
-     return.
+     `bugbot_acknowledged_at`, `codex_down`), `phase = CODE_REVIEW`, schedule
+     next wakeup, return.
 
 ### `phase == BUGBOT` (terminal gate)
 
@@ -295,8 +340,9 @@ passes are clean; Bugbot confirms the HEAD, then the convergence gates run.
 `python "$HOME/.claude/_shared/pr-loop/scripts/reviews_disabled.py" --reviewer bugbot`
 
 - Exit 0 (Bugbot disabled for this run — the default, unless
-  `CLAUDE_REVIEWS_ENABLED` lists `bugbot`) → set `bugbot_down = true`, advance to
-  the [convergence gates](convergence-gates.md) in the same tick with the Bugbot
+  `CLAUDE_REVIEWS_ENABLED` lists `bugbot`) → set `bugbot_down = true`, run the
+  [Codex review step](#codex-review-step-conditional), advance to the
+  [convergence gates](convergence-gates.md) in the same tick with the Bugbot
   gate bypassed; skip steps a–c below.
 - Exit 1 (`CLAUDE_REVIEWS_ENABLED` lists `bugbot` and `CLAUDE_REVIEWS_DISABLED`
   does not) → go to step a.
@@ -344,18 +390,19 @@ c. Decide (four branches; match first whose predicate holds):
      Bugbot gate next tick.
    - **`commit_id == current_head` AND zero unaddressed inline AND review
      body clean:** Set `bugbot_clean_at = current_head`, reset
-     `inline_lag_streak = 0`, advance to the [convergence
-     gates](convergence-gates.md) in the same tick.
+     `inline_lag_streak = 0`, run the [Codex review step](#codex-review-step-conditional)
+     then advance to the [convergence gates](convergence-gates.md) in the same
+     tick.
    - **`commit_id == current_head` with unaddressed inline findings:**
      Apply the shared fix protocol ([`../../../_shared/pr-loop/fix-protocol.md`](../../../_shared/pr-loop/fix-protocol.md); skill deltas in [`fix-protocol.md`](fix-protocol.md)).
      Reset `inline_lag_streak = 0` and push-invalidated markers per
      [ground-rules.md](ground-rules.md) / [state-schema.md](state-schema.md)
      (all `*_clean_at`, `merge_state_status`, `bugbot_down`,
-     `bugbot_acknowledged_at`), `phase = CODE_REVIEW`. With `state.json`: the
-     clean-coder teammate executes the fix, writes `state.json`, goes idle; the
-     next tick re-enters CODE_REVIEW on the new HEAD. No `state.json`
-     (single-PR): the lead executes it, stays `phase = CODE_REVIEW`. Schedule
-     next wakeup, return.
+     `bugbot_acknowledged_at`, `codex_down`), `phase = CODE_REVIEW`. With
+     `state.json`: the clean-coder teammate executes the fix, writes
+     `state.json`, goes idle; the next tick re-enters CODE_REVIEW on the new
+     HEAD. No `state.json` (single-PR): the lead executes it, stays
+     `phase = CODE_REVIEW`. Schedule next wakeup, return.
 
 ### `phase == COPILOT_WAIT`
 
@@ -386,9 +433,9 @@ b. Decide (three branches; match first whose predicate holds):
      no inline threads. Reset push-invalidated markers per
      [ground-rules.md](ground-rules.md) / [state-schema.md](state-schema.md)
      (all `*_clean_at`, `merge_state_status`, `bugbot_down`,
-     `bugbot_acknowledged_at`). **Set `phase = CODE_REVIEW`** (NOT COPILOT_WAIT)
-     — every fix push re-enters the internal passes on the new HEAD. Schedule
-     next wakeup, return.
+     `bugbot_acknowledged_at`, `codex_down`). **Set `phase = CODE_REVIEW`**
+     (NOT COPILOT_WAIT) — every fix push re-enters the internal passes on the
+     new HEAD. Schedule next wakeup, return.
    - **No Copilot review at `current_head` yet:** Increment
      `copilot_wait_count` (init 0 on COPILOT_WAIT entry; reset to 0 on
      every push and on every successful Copilot review). `>= 3` → hard
@@ -401,6 +448,43 @@ back-to-back-clean guarantee (the internal code-review and bugteam passes both
 clean on the same HEAD before the terminal gates re-open) only holds when every
 fix commit re-enters through CODE_REVIEW.
 
+## Codex review step (conditional)
+
+Run once the terminal Bugbot gate has confirmed HEAD (or set `bugbot_down`) and
+**before** the [convergence gates](convergence-gates.md) machine checklist.
+Uses the `codex-review` skill wrapper against the PR **base** branch (HEAD vs
+base), never an invented commit range.
+
+1. **Opt-out / down gate.**
+   `python "$HOME/.claude/_shared/pr-loop/scripts/reviews_disabled.py" --reviewer codex`
+   - Exit 0 → set `codex_down = true`, skip the skill, continue to convergence
+     gates (export `CLAUDE_REVIEWS_DISABLED` including `codex` before the
+     checklist so `check_convergence.py` bypasses without flags).
+   - Exit 1 → continue.
+
+2. **Usage probe.**
+   `python "$HOME/.claude/skills/codex-review/scripts/codex_usage_probe.py"`
+   - When `percent_left` is null or not strictly above the probe threshold
+     constant (`WEEKLY_USAGE_GATE_THRESHOLD_PERCENT`): skip Codex; do not set
+     `codex_clean_at`; continue to convergence gates (the machine checklist
+     skips the condition on the same rule).
+   - When above threshold: continue to the skill.
+
+3. **Skill wrapper (HEAD vs base).** Invoke `codex-review` (or read
+   `../../codex-review/SKILL.md` when `Skill` is not invokable) so the wrapper
+   reviews the diff against the PR base branch at `current_head`.
+
+4. **Classify.**
+   - `clean` → set `codex_clean_at = current_head`; write the stamp into
+     `$CLAUDE_JOB_DIR/pr-converge-state.json` (and pass `--codex-clean-at` into
+     `check_convergence.py` when invoking the checklist).
+   - `findings` → apply the shared fix protocol; reset push-invalidated markers
+     (all `*_clean_at`, `merge_state_status`, `bugbot_down`,
+     `bugbot_acknowledged_at`, `codex_down`); `phase = CODE_REVIEW`; schedule
+     next wakeup; return.
+   - `down` / `codex_down` → set `codex_down = true`; continue to convergence
+     gates without blocking ready.
+
 ## Step 3: Re-trigger bugbot
 
 - [ ] **Availability gate.** Enforced at BUGBOT entry (see `### phase == BUGBOT`).
@@ -413,10 +497,14 @@ fix commit re-enters through CODE_REVIEW.
   (`../../reviewer-gates/SKILL.md` § Gate 3) against `current_head` — the
   silent-pass pre-check, the already-queued check, the trigger comment, and
   the acknowledge check, with their rationale. Map its outcomes:
-- [ ] Silent pass → set `bugbot_clean_at = current_head`, advance to the [convergence gates](convergence-gates.md) same tick
+- [ ] Silent pass → set `bugbot_clean_at = current_head`, run the
+  [Codex review step](#codex-review-step-conditional), advance to the
+  [convergence gates](convergence-gates.md) same tick
 - [ ] Already queued → skip posting, wait for completion, advance to Step 4
 - [ ] Trigger acknowledged (`bugbot_acknowledged_at` recorded) → advance to Step 4
-- [ ] Bugbot down → set `bugbot_down = true`, advance to the [convergence gates](convergence-gates.md) same tick
+- [ ] Bugbot down → set `bugbot_down = true`, run the
+  [Codex review step](#codex-review-step-conditional), advance to the
+  [convergence gates](convergence-gates.md) same tick
 
 ## Step 4: Loop pacing
 

package/skills/pr-converge/reference/state-schema.md

@@ -33,6 +33,16 @@ live ONLY in the single-PR `$CLAUDE_JOB_DIR/pr-converge-state.json` file
   Reset to `null` on every push.
 - `copilot_clean_at`: HEAD SHA where Copilot last reported clean, or `null`.
   Reset to `null` on every push.
+- `codex_clean_at`: HEAD SHA where the Codex review skill last reported clean,
+  or `null`. Reset to `null` on every push. The machine checklist requires this
+  stamp to equal `current_head` only when weekly usage is above the probe
+  threshold (see [convergence-gates.md](convergence-gates.md)).
+- `codex_down`: boolean, init `false`. Set `true` when the Codex skill
+  classifies `codex_down`, when `CLAUDE_REVIEWS_DISABLED` lists `codex`, or when
+  the agent passes `--codex-down` into `check_convergence.py`. While `true`,
+  the Codex gate never blocks ready. Reset to `false` on every push (same
+  push-invalidation rule as `bugbot_down`); the availability / opt-out check
+  re-applies on the next Codex entry.
 - `merge_state_status`: last-observed `mergeable_state` from
   `pull_request_read(method="get")` (e.g. `clean`, `dirty`, `blocked`,
   `behind`, `unknown`, `unstable`), or `null` before the first check. Reset

package/skills/pr-converge/scripts/CLAUDE.md

@@ -8,6 +8,7 @@ Python helper scripts for the `pr-converge` skill, plus their tests and a PowerS
 |---|---|
 | `check_bugbot_ci.py` | Checks bugbot CI check-run status on a given SHA |
 | `check_convergence.py` | Evaluates whether all convergence gates pass on the current HEAD |
+| `check_convergence_availability.py` | Resolves reviewer waivers from flag, disk-authoritative settings (env fallback), and the availability/quota probe, with waived / enforced / probe_error_reason states |
 | `check_convergence_gates.py` | GitHub REST leaf checks (review and Bugbot) the convergence gates call |
 | `check_convergence_thread_gates.py` | GitHub GraphQL and REST leaf checks (review threads and pending reviewers) the convergence gates call |
 | `check_pending_reviews.py` | Fetches pending review requests and reviewer states |
@@ -19,6 +20,7 @@ Python helper scripts for the `pr-converge` skill, plus their tests and a PowerS
 | `conftest.py` | Puts the scripts directory on `sys.path` so pytest collects the suite |
 | `test_check_bugbot_ci.py` | Tests for `check_bugbot_ci.py` |
 | `test_check_convergence.py` | Tests for `check_convergence.py` |
+| `test_check_convergence_availability.py` | Tests for `check_convergence_availability.py` |
 | `test_check_convergence_contract.py` | Contract pins for `check_convergence.py` gate wiring |
 | `test_check_convergence_gates.py` | Tests for `check_convergence_gates.py` |
 | `test_check_convergence_thread_gates.py` | Tests for `check_convergence_thread_gates.py` |

package/skills/pr-converge/scripts/_pr_converge_path_setup.py

@@ -10,10 +10,12 @@ from pathlib import Path
 
 _scripts_directory = Path(__file__).resolve().parent
 _skill_directory = _scripts_directory.parent
-_claude_dev_env_directory = _scripts_directory.parent.parent.parent
+_skills_directory = _skill_directory.parent
+_claude_dev_env_directory = _skills_directory.parent
 _shared_pr_loop_scripts_directory = (
     _claude_dev_env_directory / "_shared" / "pr-loop" / "scripts"
 )
+_codex_review_scripts_directory = _skills_directory / "codex-review" / "scripts"
 
 if str(_scripts_directory) not in sys.path:
     sys.path.insert(0, str(_scripts_directory))
@@ -21,3 +23,5 @@ if str(_skill_directory) not in sys.path:
     sys.path.insert(0, str(_skill_directory))
 if str(_shared_pr_loop_scripts_directory) not in sys.path:
     sys.path.insert(0, str(_shared_pr_loop_scripts_directory))
+if str(_codex_review_scripts_directory) not in sys.path:
+    sys.path.insert(0, str(_codex_review_scripts_directory))