npm - claude-dev-env - Versions diffs - 1.95.0 → 2.0.0 - Mend

claude-dev-env 1.95.0 → 2.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (240) hide show

package/skills/bugteam/reference/audit-and-teammates.md CHANGED Viewed

@@ -99,7 +99,17 @@ Repeat until an exit condition fires.
       `git merge-base` + `git diff --name-only` live inside the script; see [`../../../_shared/pr-loop/scripts/README.md`](../../../_shared/pr-loop/scripts/README.md) for what lives under this directory, and [`../../../_shared/pr-loop/code-rules-gate.md`](../../../_shared/pr-loop/code-rules-gate.md) for gate-only merge-base / invocation semantics. The lead runs this (not a teammate).
    2. If exit code **0** → continue to step 2.5 (AUDIT spawn) below.
-   3. If exit code **non-zero** → spawn a new **clean-coder** teammate (`mode="bypassPermissions"`) — **standards-fix pass** — with instructions: read the script’s stderr, edit the repo until a **re-run** of the **same** gate command exits **0**, then one commit, `git push`, shutdown. Repeat standards-fix spawns until the gate exits **0** or **5** failed gate rounds (each round = one teammate session after a non-zero gate). If still non-zero after 5 rounds → exit reason = `error: code rules gate failed pre-audit`.
+   3. If exit code **non-zero** → run a **standards-fix pass** through the
+      worker-spawn dispatcher (role `clean-coder`; see **Standards-fix
+      action** below). Instructions: read the gate script’s stderr, edit the
+      repo until a **re-run** of the **same** gate command exits **0**. On
+      tiers 1 and 3 the headless worker edits and runs tests but never
+      commits or pushes — the lead stages with explicit `git add`, mints the
+      code-verifier verdict, then commits and pushes. Tier 2 keeps in-agent
+      commit and push with `mode="bypassPermissions"`. Repeat standards-fix
+      spawns until the gate exits **0** or **5** failed gate rounds (each
+      round = one worker session after a non-zero gate). If still non-zero
+      after 5 rounds → exit reason = `error: code rules gate failed pre-audit`.
    4. After gate exit **0**, increment `loop_count`. If `loop_count > 20`, exit reason = `cap reached` (counts **audits**, not standards-only rounds).
    5. Execute **AUDIT action** (spawn bugfind). Print progress: `Loop <L> audit: ...`
@@ -116,46 +126,216 @@ Repeat until an exit condition fires.
 ## AUDIT action
-Spawn one audit agent that walks all A–P categories:
-```
-Agent(
-  subagent_type="code-quality-agent",
-  name="bugfind-pr<N>-loop<L>",
-  model="opus",
-  run_in_background=true,
-  description="Audit {owner}/{repo}#{N} loop {L}",
-  prompt="<output of build_audit_prompt.py; see ../../_shared/pr-loop/scripts/build_audit_prompt.py>"
-)
-```
+Walk all A–Q categories through the worker-spawn dispatcher
+([`worker-spawn.md`](../../../_shared/pr-loop/worker-spawn.md)). Every loop
+is a fresh process or a fresh agent context.
+1. **Build the headless audit prompt** and write it to a prompt file under the
+   per-PR workspace:
+   ```bash
+   python "${CLAUDE_SKILL_DIR}/../_shared/pr-loop/scripts/build_audit_prompt.py" \
+     --owner <O> --repo <R> --pr-number <N> --loop <L> \
+     --head-ref <head> --base-ref <base> \
+     --worktree-path <worktree_path> --run-temp-dir <run_temp_dir> \
+     --flavor headless \
+     > "${run_temp_dir}/pr-<N>/loop-<L>.audit-prompt.xml"
+   ```
+   Optional: `--pr-body-file <path>` when the PR body is available on disk.
+2. **Dispatch** via
+   [`resolve_worker_spawn.py`](../../../scripts/resolve_worker_spawn.py). Role
+   `bugteam` maps to primary agent `code-quality-agent`:
+   ```bash
+   python "${CLAUDE_SKILL_DIR}/../../scripts/resolve_worker_spawn.py" \
+     --role bugteam \
+     --prompt-file "${run_temp_dir}/pr-<N>/loop-<L>.audit-prompt.xml" \
+     --cwd <worktree_path> \
+     --run-temp-dir <run_temp_dir>
+   ```
+   The lead **blocks on the process** and reads the stdout JSON result.
+3. **Follow the result:**
+   - **Tier 1 or 3 served** (`tier_used` is `1` or `3`, exit `0`): the
+     dispatcher ran the worker to completion. Read the outcome XML at
+     `<worktree_path>/.bugteam-pr<N>-loop<L>.outcomes.xml`. The **lead**
+     posts the audit review with
+     [`post_audit_thread.py`](../../../_shared/pr-loop/scripts/post_audit_thread.py)
+     (see [SKILL.md § Audit posting](../SKILL.md#audit-posting)).
+   - **`claude_agent_required`** (exit `2`, attempts include tier `2` with
+     that reason): rebuild the prompt with default `--flavor agent` (omit
+     `--flavor` or pass `agent`) and spawn the Agent-tool worker, including
+     in-worker posting:
+     ```
+     Agent(
+       subagent_type="code-quality-agent",
+       name="bugfind-pr<N>-loop<L>",
+       model="opus",
+       run_in_background=true,
+       description="Audit {owner}/{repo}#{N} loop {L}",
+       prompt="<output of build_audit_prompt.py --flavor agent>"
+     )
+     ```
 The audit prompt XML is emitted by
 [`build_audit_prompt.py`](../../_shared/pr-loop/scripts/build_audit_prompt.py).
-Run it with `--owner --repo --pr-number --loop --head-ref --base-ref --worktree-path --run-temp-dir`
-to generate the complete `<spawn_prompt>` XML on stdout.
+`--flavor headless` targets the dispatcher path (gh reads, outcome file, no
+MCP/TaskCreate/Artifact). Default `--flavor agent` targets the Agent-tool
+path (MCP posting).
 `last_action = "audited"`. Append audit metadata to `audit_log`.
-## FIX action (fresh teammate)
-Spawn:
+## Standards-fix action
+Route through the worker-spawn dispatcher
+([`worker-spawn.md`](../../../_shared/pr-loop/worker-spawn.md)). Role
+`clean-coder` maps to primary agent `clean-coder`. Every round is a fresh
+process or a fresh agent context. The **5-round cap** stays (each round = one
+worker session after a non-zero gate).
+1. **Write a standards-fix prompt** under the per-PR workspace that includes
+   the gate stderr, the exact gate re-run command, and the worktree path. On
+   headless tiers the permission flag maps to each CLI's own flag
+   (`--permission-mode bypassPermissions`).
+2. **Dispatch:**
+   ```bash
+   python "${CLAUDE_SKILL_DIR}/../../scripts/resolve_worker_spawn.py" \
+     --role clean-coder \
+     --prompt-file "${run_temp_dir}/pr-<N>/loop-<L>.standards-fix-prompt.txt" \
+     --cwd <worktree_path> \
+     --run-temp-dir <run_temp_dir>
+   ```
+3. **Follow the result:**
+   - **Tier 1 or 3 served** (`tier_used` is `1` or `3`, exit `0`): the
+     headless worker edits and runs tests but never commits or pushes. The
+     lead session stages the worker's files itself with an explicit `git add`
+     (the session edit tracker does not see files the lead did not edit),
+     mints the code-verifier verdict in its own context, then commits and
+     pushes — so the commit gate and the staged-commit scans fire on the real
+     diff. Re-run the gate command; if still non-zero, start the next round.
+   - **`claude_agent_required`** (exit `2`, attempts include tier `2` with
+     that reason): spawn the Agent-tool worker with in-agent commit and push:
+     ```
+     Agent(
+       subagent_type="clean-coder",
+       name="standards-fix-pr<N>-loop<L>-round<R>",
+       model="opus",
+       mode="bypassPermissions",
+       run_in_background=true,
+       description="Standards-fix {owner}/{repo}#{N} loop {L} round {R}",
+       prompt="<gate stderr + re-run command + commit/push/shutdown>"
+     )
+     ```
+The missing-subagent refusal in [`../SKILL.md`](../SKILL.md) applies to tier 2
+only; headless tiers rely on the preflight's agent-definition-file check.
-```
-Agent(
-  subagent_type="clean-coder",
-  name="bugfix-pr<N>-loop<L>",
-  mode="bypassPermissions",
-  run_in_background=true,
-  description="Bugfix PR <N> loop <L>",
-  prompt="<output of build_fix_prompt.py; see ../../_shared/pr-loop/scripts/build_fix_prompt.py>"
-)
-```
-The teammate sees only the latest audit’s findings — each `Agent` call starts with a fresh context window; prior-loop findings, fix history, and chat stay in the lead.
-Pass finding comment URL, comment id, and thread node id for each finding (from `loop_comment_index`) in the XML prompt so the teammate owns both the reply and the thread resolution. After commit, the teammate posts one reply per finding using the unified template at [`../../../_shared/pr-loop/audit-reply-template.md`](../../../_shared/pr-loop/audit-reply-template.md) — the full header / horizontal rule / `<action_heading> ✅` / explanation / anchored-bullet / closing-paragraph skeleton, with `<status_line>` set per the path (`Fixed in <short_sha>` for `status=fixed`, `Could not address this loop` for `status=could_not_address`, `Hook blocked the fix commit` for `status=hook_blocked`). Per-thread reply and `resolve_thread` are atomic; the mechanics follow the shared 13-step sequence in [`../../../_shared/pr-loop/fix-protocol.md`](../../../_shared/pr-loop/fix-protocol.md) (step 12 carries the exact reply-and-resolve sequence). Same identity model as bugfind: teammate posts; lead waits.
+## FIX action (fresh teammate)
-After replies, the teammate writes outcome XML (schema in [`../PROMPTS.md`](../PROMPTS.md)).
+Route through the worker-spawn dispatcher
+([`worker-spawn.md`](../../../_shared/pr-loop/worker-spawn.md)). Role
+`clean-coder` maps to primary agent `clean-coder`. Every loop is a fresh
+process or a fresh agent context. The teammate sees only the latest audit’s
+findings — prior-loop findings, fix history, and chat stay in the lead.
+Pass finding comment URL, comment id, and thread node id for each finding
+(from `loop_comment_index`) in the XML prompt.
+1. **Build the headless fix prompt** and write it to a prompt file under the
+   per-PR workspace:
+   ```bash
+   python "${CLAUDE_SKILL_DIR}/../_shared/pr-loop/scripts/build_fix_prompt.py" \
+     --owner <O> --repo <R> --pr-number <N> --loop <L> \
+     --head-ref <head> --base-ref <base> \
+     --worktree-path <worktree_path> \
+     --findings-json <findings_json_path> \
+     --flavor headless \
+     > "${run_temp_dir}/pr-<N>/loop-<L>.fix-prompt.xml"
+   ```
+2. **Dispatch** via
+   [`resolve_worker_spawn.py`](../../../scripts/resolve_worker_spawn.py):
+   ```bash
+   python "${CLAUDE_SKILL_DIR}/../../scripts/resolve_worker_spawn.py" \
+     --role clean-coder \
+     --prompt-file "${run_temp_dir}/pr-<N>/loop-<L>.fix-prompt.xml" \
+     --cwd <worktree_path> \
+     --run-temp-dir <run_temp_dir>
+   ```
+   The lead **blocks on the process** and reads the stdout JSON result.
+3. **Follow the result:**
+   - **Tier 1 or 3 served** (`tier_used` is `1` or `3`, exit `0`): On tiers 1
+     and 3 the headless worker edits and runs tests but never commits or
+     pushes. The lead session stages the worker's files itself with an
+     explicit `git add` (the session edit tracker does not see files the lead
+     did not edit), mints the code-verifier verdict in its own context, then
+     commits and pushes — so the commit gate and the staged-commit scans fire
+     on the real diff. Read the outcome XML at
+     `<worktree_path>/.bugteam-pr<N>-loop<L>.fix-outcomes.xml`. The **lead**
+     posts one reply per finding using the unified template at
+     [`../../../_shared/pr-loop/audit-reply-template.md`](../../../_shared/pr-loop/audit-reply-template.md)
+     — the full header / horizontal rule / `<action_heading> ✅` /
+     explanation / anchored-bullet / closing-paragraph skeleton, with
+     `<status_line>` set per the path (`Fixed in <short_sha>` for
+     `status=fixed`, `Could not address this loop` for
+     `status=could_not_address`, `Hook blocked the fix commit` for
+     `status=hook_blocked`). Per-thread reply and `resolve_thread` are
+     atomic; the mechanics follow the shared 13-step sequence in
+     [`../../../_shared/pr-loop/fix-protocol.md`](../../../_shared/pr-loop/fix-protocol.md)
+     (step 12 carries the exact reply-and-resolve sequence).
+   - **`claude_agent_required`** (exit `2`, attempts include tier `2` with
+     that reason): Tier 2 keeps the current behavior end to end, including
+     in-agent commit and push and `mode="bypassPermissions"`. Rebuild the
+     prompt with default `--flavor agent` (omit `--flavor` or pass `agent`)
+     and spawn the Agent-tool worker, pinning model opus:
+     ```
+     Agent(
+       subagent_type="clean-coder",
+       name="bugfix-pr<N>-loop<L>",
+       model="opus",
+       mode="bypassPermissions",
+       run_in_background=true,
+       description="Bugfix PR <N> loop <L>",
+       prompt="<output of build_fix_prompt.py --flavor agent>"
+     )
+     ```
+     After commit, the teammate posts one reply per finding using the same
+     unified template and writes outcome XML (schema in
+     [`../PROMPTS.md`](../PROMPTS.md)).
+The fix prompt XML is emitted by
+[`build_fix_prompt.py`](../../_shared/pr-loop/scripts/build_fix_prompt.py).
+`--flavor headless` targets the dispatcher path (gh reads, outcome file, no
+commit/push/MCP/TaskCreate/Artifact). Default `--flavor agent` targets the
+Agent-tool path (in-agent commit, push, and MCP replies). On headless tiers
+the permission flag maps to each CLI's own flag
+(`--permission-mode bypassPermissions`).
+### Tier-1 flag profiles
+When tier-1 (headless grok) runs for audit or fix work and the **grok-spawn**
+skill is installed on the host, take CLI flag profiles from that skill's
+flag-profiles reference. Do not restate those flags here. When the skill is
+absent, use the host's grok headless defaults from the worker-spawn protocol
+and the headless runner. This page keeps the Agent-tool spawn shape for
+Claude-host teammates.
 ### Shutdown (bugfix)
@@ -163,9 +343,9 @@ Same self-termination model as bugfind. Missing notification → hard blocker.
 `approve: false` → `error: bugfix teammate refused shutdown` → Step 4 (`pr-loop-lifecycle` Close).
-Substitute placeholders from `last_findings` into the fix prompt per [`../PROMPTS.md`](../PROMPTS.md). The spawn XML includes TaskCreate/self_audit_checklist for task tracking — the FIX subagent MUST create tasks before starting.
+Substitute placeholders from `last_findings` into the fix prompt per [`../PROMPTS.md`](../PROMPTS.md). The agent-flavor spawn XML includes TaskCreate/self_audit_checklist for task tracking — the tier-2 FIX subagent MUST create tasks before starting. Headless flavors omit TaskCreate.
-**Verify push:** `git rev-parse HEAD` after fix must differ from before; new HEAD must exist on `origin/<branch>` (`git fetch origin <branch> && git rev-parse origin/<branch>` matches `HEAD`). If HEAD did not change → `stuck — bugfix teammate could not address findings`.
+**Verify push:** `git rev-parse HEAD` after fix must differ from before; new HEAD must exist on `origin/<branch>` (`git fetch origin <branch> && git rev-parse origin/<branch>` matches `HEAD`). If HEAD did not change → `stuck — bugfix teammate could not address findings`. On tiers 1 and 3 this check runs after the **lead** commit and push.
 **Scope verification.** Run `git diff HEAD~1 --name-only` and compare against the set of files referenced in `bugs_to_fix`. When the commit touches files NOT in the `bugs_to_fix` list, judge whether the extras are a coherent part of the fix: a shared helper the auditor did not think to name, a test file that exercises the fix, a config update the fix requires. If the extras are coherent with the fix, note them in the outcome XML's `<scope_notes>` and keep the outcome as `fixed`. If the extras look unrelated, suspicious, or out of scope, downgrade to `unverified_fixed` with reason `commit touched unexpected files: <list>`. The auditor's file list is a default, not a contract — the fix's coherence is the contract.

package/skills/bugteam/reference/design-rationale.md CHANGED Viewed

@@ -2,7 +2,7 @@
 ## Core principle (expanded)
-One audit agent (`code-quality-agent`, opus) walks all A–P categories per loop. One fix agent (`clean-coder`, opus) addresses the audit's findings.
+One audit agent (`code-quality-agent`, opus) walks all A–Q categories per loop. One fix agent (`clean-coder`, opus) addresses the audit's findings.
 Fresh-spawn clean-room isolation: each `Agent` call creates a new subagent with its own context window and no access to prior conversation. After the subagent writes its outcome XML and self-terminates, the lead reads the file. Results never accumulate in the lead’s context beyond the XML artifact. Verbatim Anthropic quotes and URLs: [`../sources.md`](../sources.md).

package/skills/bugteam/reference/obstacles/CLAUDE.md CHANGED Viewed

@@ -8,7 +8,7 @@ Per-step obstacle guides for the `bugteam` skill. Each file addresses a specific
 |---|---|
 | `audit-assign-ids.md` | Assigning stable finding IDs in the audit output. |
 | `audit-capture-excerpts.md` | Capturing code excerpts for each finding. |
-| `audit-walk-categories.md` | Walking all A–P categories without skipping. |
+| `audit-walk-categories.md` | Walking all A–Q categories without skipping. |
 | `audit-write-xml.md` | Writing the outcome XML from an audit pass. |
 | `fix-append-summary.md` | Appending the fix summary to the outcome XML. |
 | `fix-apply-fixes.md` | Applying code fixes from the finding list. |

package/skills/bugteam/reference/team-setup.md CHANGED Viewed

@@ -110,8 +110,14 @@ truth.
   `<run_temp_dir>` and pass that literal path to every shell command that follows.
 - **Subagent roles (spawned per loop, not at invocation start):**
-  - `bugfind` — `code-quality-agent`, model opus (Opus 4.7 at default xhigh effort)
-  - `bugfix` — `clean-coder`, no model pin (the lead picks the model per task)
+  - `bugfind` — `code-quality-agent`, model opus; routes through
+    `resolve_worker_spawn.py` with role `bugteam` (primary agent
+    `code-quality-agent`)
+  - `bugfix` — `clean-coder`, model opus; routes through
+    `resolve_worker_spawn.py` with role `clean-coder` (primary agent
+    `clean-coder`). Tier 2 Agent spawn pins `model="opus"`.
+  - `standards-fix` — `clean-coder` via the same dispatcher role; 5-round
+    cap; tier 2 pins `model="opus"` and `mode="bypassPermissions"`
 ### Loop state block

package/skills/codex-review/CLAUDE.md ADDED Viewed

@@ -0,0 +1,46 @@
+# codex-review
+Runs OpenAI Codex as a local PR or uncommitted-diff reviewer: opt-out gate, version/shape probe, target pick, classifying review (`codex exec … review --json`), outcome classification, and handoff of findings into `pr-fix-protocol`. Triggered by `/codex-review`, `codex review`, `run codex review`, `babysit codex review`, or `codex as a PR reviewer`.
+## Purpose
+One Codex review pass per invocation. The skill owns sequence and skill-level classification (`down` / `clean` / `findings`). The headless wrapper is capture-only (`completed` / `codex_down` plus raw fields). Shared peers own opt-out parsing (`reviews_disabled.py` / `reviewer-gates`) and the fix sequence (`pr-fix-protocol`). Observed raw CLI surface, wrapper capture contract, probe signals, failure fixtures, auth modes, cloud runbook, and classification map live under `reference/cli-contract.md`; PR-loop wiring lives under `reference/loop-integration.md`.
+## Key files
+| File | Purpose |
+|---|---|
+| `SKILL.md` | Flow skeleton: opt-out → probe → target → wrapper → classify → fix handoff; refusals; sub-skills table; ground rules. |
+| `reference/cli-contract.md` | Wrapper entrypoint and argv; version/shape probe; success JSONL and findings parse; failure classes tied to fixtures; auth modes; cloud runbook. |
+| `reference/loop-integration.md` | Gate placement in pr-converge and autoconverge; threshold rule; opt-out token; state fields; re-entry after fixes. |
+| `scripts/run_codex_review.py` | Headless capture wrapper: probes, single-target argv, JSONL capture, `completed` / `codex_down`. |
+| `scripts/test_run_codex_review.py` | Behavioral tests for `run_codex_review`. |
+| `scripts/codex_down_classifier.py` | Maps a Codex run's exit code and stream text to a failure detail class and the gate outcome class (`completed` / `codex_down`). |
+| `scripts/parse_codex_findings.py` | Parses reviewer text into findings: fenced JSON first, then the freeform bullet shape, then a single floor finding. |
+| `scripts/codex_usage_probe.py` | Weekly usage probe CLI: app-server rate-limits read, null-on-unknown JSON report. |
+| `scripts/test_codex_usage_probe.py` | Unit tests for the weekly usage probe and gate helper. |
+| `scripts/codex_review_scripts_constants/run_constants.py` | Named constants package for skill scripts: binary name, flags, prompt, probe pattern, timeout, exit sentinels, JSONL keys, capture outcome labels. |
+| `scripts/codex_review_scripts_constants/codex_usage_probe_constants.py` | Named constants for the weekly usage probe. |
+## Subdirectories
+| Directory | Role |
+|---|---|
+| `reference/` | Progressive-disclosure pages for cli-contract and loop-integration. |
+| `scripts/` | Capture wrapper, classifier, findings parser, weekly usage probe, tests, fixtures, and constants package. |
+## Environment opt-out
+Step 0 runs `reviews_disabled.py --reviewer codex` before any probe or review invoke.
+| Gate exit | Meaning for this skill |
+|---|---|
+| 0 | Opt-out active — refuse with the opt-out line in `SKILL.md` and stop |
+| 1 | Continue the flow |
+| Any other | Blocker — stop; do not invent an opt-out refusal |
+Set `CLAUDE_REVIEWS_DISABLED=codex` to disable. This package does not re-parse `CLAUDE_REVIEWS_DISABLED`; the shared gate owns the token parse.
+## Scripts surface
+`scripts/` holds the capture wrapper (`run_codex_review.py`), the down classifier (`codex_down_classifier.py`), the findings parser (`parse_codex_findings.py`), the weekly usage probe (`codex_usage_probe.py`), their tests, fixtures, and named constants. The wrapper returns capture fields only (`completed` / `codex_down`); agents map those fields to skill classes via the skill-class map and parse findings through `parse_codex_findings`. Classify only from a `codex exec … review --json` JSONL stream; do not invent a non-JSONL parse.

package/skills/codex-review/SKILL.md ADDED Viewed

@@ -0,0 +1,181 @@
+---
+name: codex-review
+description: >-
+  Runs OpenAI Codex as a local PR or uncommitted-diff reviewer and routes
+  findings into the shared fix protocol. Triggers: '/codex-review', 'codex
+  review', 'run codex review', 'babysit codex review', 'codex as a PR reviewer'.
+---
+# Codex Review
+Runs one Codex review pass against a chosen target, classifies the outcome, and hands findings to the shared fix protocol. Does not reimplement opt-out parsing or the fix sequence.
+## When this skill applies
+- The user wants Codex (the OpenAI Codex CLI) as a reviewer on the current PR branch, or on uncommitted work when no PR loop is active.
+- The user asks to babysit or re-run Codex review after fixes.
+## Refusals
+Respond with the quoted line exactly and stop:
+- Opt-out gate exit 0: `/codex-review is disabled via CLAUDE_REVIEWS_DISABLED.`
+- Version or shape probe reports Codex unavailable: `/codex-review cannot run: Codex CLI is missing or the shape probe failed.`
+- Skill class is `down` (wrapper `outcome_class` is `codex_down`): `/codex-review cannot complete: Codex reviewer is down.`
+Gate exits other than 0 or 1 are blockers: stop without a probe or review invoke. Do not invent an opt-out refusal for a non-opt-out failure.
+## Sub-skills
+| Skill | When | Produces |
+|---|---|---|
+| `reviewer-gates` | Step 0 — opt-out semantics for external reviewers | Gate contract for `reviews_disabled.py`; refusal line shape |
+| `pr-fix-protocol` | Step 5 — classification is `findings` | Fix sequence, reply-and-resolve unit, unresolved-thread sweep |
+If `pr-fix-protocol` is not installed when findings exist, stop with: `/codex-review needs the pr-fix-protocol skill to apply findings.`
+## Process checklist
+```
+- [ ] Step 0 — Opt-out gate
+- [ ] Step 1 — Version and shape probe
+- [ ] Step 2 — Target pick
+- [ ] Step 3 — Run classifying review
+- [ ] Step 4 — Classify outcome
+- [ ] Step 5 — Route findings (or stop on clean / down)
+```
+### Step 0: Opt-out gate
+Before any other work, run:
+```bash
+python "$HOME/.claude/_shared/pr-loop/scripts/reviews_disabled.py" --reviewer codex
+```
+- **Exit 0** — Codex reviews are disabled: refuse with the opt-out line above. Do not probe, review, or fix.
+- **Exit 1** — continue.
+- **Any other exit** — treat as a blocker and stop; do not skip the gate or continue as if it exited 1. Do not report the opt-out refusal line for a non-opt-out failure.
+Gate semantics live in `reviewer-gates` ([../reviewer-gates/SKILL.md](../reviewer-gates/SKILL.md)). The shared script owns the token parse; this skill does not re-parse `CLAUDE_REVIEWS_DISABLED`.
+### Step 1: Version and shape probe
+Probe the local Codex CLI so the run fails closed when the binary is missing or the installed shape does not match the contract.
+- **Contract owner:** [reference/cli-contract.md](reference/cli-contract.md) — probe command (`codex exec review --help`), minimum shape signals, and fail-as-`codex_down` rule.
+- **Probe outcome:** continue only when the probe reports a supported shape. On failure, refuse with the probe refusal line above (skill class `down`).
+### Step 2: Target pick
+Choose what Codex reviews:
+| Context | Target |
+|---|---|
+| PR-loop caller (or an open PR on the current branch) | Diff against the PR base branch (`--base`) |
+| Standalone run with no PR | Uncommitted work via `--uncommitted` (staged + unstaged + untracked) |
+Do not invent a synthetic commit range when a base branch is available. Loop-caller wiring for base-branch resolution lives in [reference/loop-integration.md](reference/loop-integration.md).
+### Step 3: Run classifying review
+Call `scripts/run_codex_review.py` (`run_codex_review`) against the chosen target on the classifying path.
+- **Classifying command:** `codex exec [options] review --json …` — this is the only path that emits the success JSONL stream Step 4 reads. Full surface: [reference/cli-contract.md](reference/cli-contract.md).
+- **Non-classifying form:** plain `codex review` (no `exec`, no `--json`) is not a classification input on the observed CLI; do not feed its stdout into Step 4.
+- **Contract owner:** [reference/cli-contract.md](reference/cli-contract.md) — wrapper entrypoint, required arguments (target, repo root, run-state directory), capture fields, and exit codes.
+- **Wrapper boundary (capture only):** returns `completed` or `codex_down`, plus `exit_code`, `binary_version`, `jsonl_path`, and `agent_message`. It does not emit skill classes `down` / `clean` / `findings` and does not parse findings.
+- **This skill's job:** pass the Step 2 target, ensure `run_state_directory` exists, and hand the capture outcome to Step 4. Do not parse raw Codex stdout inline outside the documented parser path. Fail closed on probe miss, non-usable stream, or `codex_down`.
+### Step 4: Classify outcome
+Map the wrapper capture (and its JSONL observation) to exactly one skill-level class:
+| Skill class | From wrapper | Meaning | Next action |
+|---|---|---|---|
+| `down` | `outcome_class == codex_down` | Codex did not produce a usable review (tool failure, auth, crash, shape miss) | Refuse with the down line; stop |
+| `clean` | `outcome_class == completed` and findings parse empty | Review completed with no findings against the target | Report one-line clean summary; stop |
+| `findings` | `outcome_class == completed` and findings parse non-empty | Review completed with one or more addressable findings | Continue to Step 5 |
+`outcome_class` is the capture success signal. A process `exit_code` of 0 does not mean success when the wrapper already set `codex_down` (for example a shape probe that exits 0 but lacks required flags).
+#### Skill class ↔ CLI observation map
+| Skill class | Maps from (cli-contract) | Signal |
+|---|---|---|
+| `down` | `codex_down` rows; unrecognized probe shape | Non-usable review (exit 1/2 failures, config/auth/model errors, probe miss) |
+| `clean` | Wrapper `completed` and `parse_codex_findings(agent_message)` empty (blank text or structured `[]`) | Usable review, zero addressable findings |
+| `findings` | Wrapper `completed` and `parse_codex_findings(agent_message)` non-empty (fenced JSON objects, freeform `- [P#]` bullets, or floor text) | Usable review with addressable findings |
+Raw CLI failure vocabulary is `codex_down` only ([reference/cli-contract.md](reference/cli-contract.md)). Skill steps and loop re-entry use `down` / `clean` / `findings`. Classification rules, findings parse, and payload fields live in [reference/cli-contract.md](reference/cli-contract.md).
+### Step 5: Route findings into the shared fix protocol
+When the class is `findings`:
+1. Read `$HOME/.claude/skills/pr-fix-protocol/SKILL.md` (or invoke `pr-fix-protocol` by name when the `Skill` tool is available).
+2. Pass the findings payload, PR scope when present, and worktree path.
+3. Apply the protocol end to end — failing test first when behavior is at stake, one fix commit, push when the caller requires it, reply and resolve per thread when the review is on a PR.
+This skill does not restate the fix sequence. Orchestrator callers that re-enter after a push follow [reference/loop-integration.md](reference/loop-integration.md).
+## Ground rules
+- **One capability:** run Codex review and classify; fixes go through `pr-fix-protocol`.
+- **Compose, do not rebuild:** opt-out via `reviews_disabled.py`; fixes via `pr-fix-protocol`.
+- **Fail closed** on opt-out, non-0/1 gate exit, probe failure, and `down`.
+- **Preserve draft state** of any open PR; this skill does not flip ready.
+- **Honor hooks** on any commit the fix protocol creates.
+## Examples
+<example>
+User: `/codex-review`
+Claude: [runs opt-out gate; on exit 1 probes Codex shape, picks base-branch or `--uncommitted` target, runs `codex exec … review --json`, classifies from JSONL, reports clean or routes findings; on non-0/1 gate exit stops as a blocker]
+</example>
+<example>
+`CLAUDE_REVIEWS_DISABLED=codex`
+Claude: `/codex-review is disabled via CLAUDE_REVIEWS_DISABLED.`
+</example>
+<example>
+User: "babysit codex review on this PR"
+Claude: [same flow; after findings, applies pr-fix-protocol, then re-runs the classifying review once for confirmation when the caller stays on this skill]
+</example>
+## Gotchas
+- **Opt-out uses `CLAUDE_REVIEWS_DISABLED=codex`.** `reviews_disabled.py --reviewer codex` exit 0 disables the review; exit 1 continues the probe and wrapper. Standalone `/codex-review` stops with the opt-out refusal line and never runs the wrapper (no `codex_down` capture). Orchestrator gates map the same exit 0 to `codex_down` / `codexDown` bypass on the machine checklist. Export `CLAUDE_REVIEWS_DISABLED=codex` (alone or comma-joined with other reviewers). A gate parse failure for an unknown token is a blocker — stop rather than skipping the gate. The shared gate must list `codex` among known reviewers for Step 0 to accept the flag.
+- **Only `codex exec … review --json` JSONL is classifiable.** Plain `codex review` stdout is non-classifying. Only a Step 4 `findings` class enters Step 5.
+- **Wrapper capture is not skill classification.** Step 5 consumes the skill-class payload from Step 4 (`down` / `clean` / `findings`), built from the wrapper's capture fields and the findings parse.
+- **Uncommitted targets have no review threads.** Fix protocol reply-and-resolve applies only when a PR carries threads; local-only runs stop after the fix commit path the protocol allows without a PR.
+## File index
+| File | Purpose |
+|---|---|
+| `SKILL.md` | Hub: opt-out, probe, target, classifying review, classify, fix handoff |
+| `CLAUDE.md` | Package map for agents opening this skill |
+| `reference/cli-contract.md` | CLI probe, wrapper capture, auth, cloud runbook, fixture-backed failure classes |
+| `reference/loop-integration.md` | Gate placement, threshold, opt-out, state fields, re-entry |
+| `scripts/run_codex_review.py` | Headless capture wrapper (`run_codex_review`) |
+| `scripts/test_run_codex_review.py` | Behavioral tests for the capture wrapper |
+| `scripts/codex_down_classifier.py` | Maps exit code and stream text to detail class and `completed` / `codex_down` |
+| `scripts/parse_codex_findings.py` | Parses agent text: fenced JSON, freeform bullets, then floor |
+| `scripts/codex_review_scripts_constants/run_constants.py` | Importable named constants for the capture wrapper |
+| `scripts/codex_usage_probe.py` | Weekly usage probe CLI (`percent_left`, `window_reset`, `source`) |
+| `scripts/test_codex_usage_probe.py` | Probe unit tests (app-server fixtures and gate helper) |
+| `scripts/codex_review_scripts_constants/codex_usage_probe_constants.py` | Named constants for the weekly usage probe |
+## Folder map
+- `SKILL.md` — orchestration steps and refusals.
+- `CLAUDE.md` — purpose, trigger, key files.
+- `reference/` — stable homes for cli-contract and loop-integration detail.
+- `scripts/` — capture wrapper, classifier, findings parser, weekly usage probe, tests, fixtures, and constants package.
+- `scripts/run_codex_review.py` — headless capture wrapper entrypoint.
+- `scripts/codex_down_classifier.py` — detail-class and gate-outcome classifier.
+- `scripts/parse_codex_findings.py` — findings parser entrypoint.
+- `scripts/codex_usage_probe.py` — weekly usage probe entrypoint.
+- `scripts/codex_review_scripts_constants/` — importable constants package for skill scripts.

package/skills/codex-review/reference/CLAUDE.md ADDED Viewed

@@ -0,0 +1,15 @@
+# codex-review/reference
+Reference pages for the `codex-review` skill. `SKILL.md` cites these files for CLI contract and PR-loop integration detail.
+## Key files
+| File | Purpose |
+|---|---|
+| `cli-contract.md` | Observed Codex CLI review surface: classifying `codex exec … review --json` path, wrapper capture (`completed` / `codex_down`), probe signals, success JSONL and findings parse, fixture-backed failure classes, skill-class map (`down` / `clean` / `findings`), auth modes, and cloud runbook. |
+| `loop-integration.md` | Gate placement in pr-converge and autoconverge; threshold rule; opt-out token; state fields; target selection; skill-class vocabulary; findings handoff; re-entry after a fix push. |
+## Conventions
+- Each page is the stable home for one child workstream. Cross-references from `SKILL.md` use these paths.
+- Keep one level deep: `SKILL.md` links here; orchestrator-owned detail links out to pr-converge / autoconverge pages rather than restating them.