claude-dev-env 1.94.0 → 2.0.0

package/skills/closeout/reference/pii-redaction-checklist.md

@@ -0,0 +1,36 @@
+# PII redaction checklist
+
+The PII pass runs on every closeout run, over every issue body and over the handoff prompt, before the confirmation gate. Repository visibility changes how aggressive the redaction is — public repos get the strictest pass — never whether the pass runs.
+
+## The pass
+
+Read each drafted body and the handoff prompt line by line. For every match below, swap the real value for the placeholder. When a value is load-bearing for the fix (a hook needs the exact path shape), keep the shape and drop the private part — `~/.claude/hooks/<hook>.py`, not the full home path.
+
+| Category | What to catch | Swap |
+|---|---|---|
+| Email | Any address | `<email>` |
+| Real name | A person's name in a path, log line, or account | `<name>` |
+| Home path | A user home directory | `~/` or `<home>/` |
+| Private host / IP | A LAN host, NAS name, private IP | `<host>` |
+| SSH user / port | A login user or non-standard port | `<user>`, `<port>` |
+| Account id | A store, cloud, app, or master-user id | `<account-id>` |
+| Token / secret | An API key, token, or credential | `<redacted>` |
+| Private repo name | An unpublished owner/repo | `<owner>/<repo>` |
+| Sheet / DB / script id | A Neon, Sheet, or Apps Script id | `<id>` |
+
+## Public versus private aggression
+
+| Target repo | Aggression |
+|---|---|
+| Public (ships to a public host, open source) | Strictest: redact every category above, and any value a stranger could tie to a person or a private system. When in doubt, redact. |
+| Private (internal, team-only) | Redact tokens, secrets, credentials, and emails without exception. Keep internal host and path shapes only when the fix needs them. |
+
+## After the pass
+
+- List every redaction made, so the confirmation gate shows the user what changed.
+- When a redaction removes a value the fix needs, note it as an open question for the user in the gate — do not guess a replacement.
+- A body that still holds a match after the pass does not reach the gate. Re-run the pass until every match is swapped.
+
+## Why the pass is unconditional
+
+An issue is a durable post on a shared server. A private value in an issue body outlives the session and the person who typed it. Running the pass on every body, public or private, keeps a leak from landing where it cannot be pulled back.

package/skills/codex-review/CLAUDE.md

@@ -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

@@ -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

@@ -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.

package/skills/codex-review/reference/cli-contract.md

@@ -0,0 +1,253 @@
+# CLI contract
+
+Observed shape of the Codex CLI review surface the skill classifies from. Fixture capture baseline: `codex` 0.144.3. Scripts under `../scripts/` implement this contract.
+
+## Wrapper entrypoint
+
+```text
+run_codex_review(
+    repository_directory=<repo root Path>,
+    run_state_directory=<run-state Path>,
+    base_branch=<branch> | is_uncommitted=True | commit_sha=<sha> | is_prompt_target=True,
+)
+```
+
+Exactly one target among `base_branch`, `is_uncommitted`, `commit_sha`, and `is_prompt_target`. Zero or more than one raises `ValueError`.
+
+### Return shape (`CodexReviewOutcome`)
+
+Capture only — skill-level classes `down` / `clean` / `findings` are **not** produced here.
+
+| Field | Meaning |
+|---|---|
+| `outcome_class` | `completed` or `codex_down` |
+| `exit_code` | Last process exit code, or a sentinel when none ran (`127` missing binary, `124` timeout, `70` decode error) |
+| `binary_version` | Parsed `codex --version` string, or empty |
+| `jsonl_path` | Path to captured JSONL (`codex-review.jsonl` under the run-state directory), or `None` when review did not run |
+| `agent_message` | Last `agent_message` text from the JSONL stream (stderr text when the run fails with empty agent text) |
+
+Detail classes from `classify_codex_run` are a separate step (see Failure classes). They are not fields on `CodexReviewOutcome`.
+
+## Command shape
+
+### Classifying path: `codex exec … review --json`
+
+Skill classification (Step 4) reads only the JSONL stream from the classifying path. The wrapper builds:
+
+```text
+codex exec [exec-options] review --json <one-target>
+```
+
+| Target | Flag / payload |
+|---|---|
+| Uncommitted | `--uncommitted` |
+| Base branch | `--base <BRANCH>` |
+| Commit | `--commit <SHA>` |
+| Custom instructions | positional PROMPT (`CUSTOM_INSTRUCTIONS_PROMPT`: freeform one-line summary, `Review comment:` heading, then `- [P#]` bullets — not fenced JSON) |
+
+`CODEX_MODEL_PIN` is empty in the shipped constants, so `-m` is omitted unless a pin is set.
+
+`--json` is required for a classifiable success stream. Without `--json`, stdout is not a Step 4 input.
+
+### Ordering rule
+
+`codex exec` options belong **before** the `review` subcommand. Review options such as `--json` and `--uncommitted` follow `review`.
+
+- Parses: `codex exec review --json --uncommitted`
+- Fails (exit 2, usage on stderr): trailing `-C <DIR>` after `review` (`unexpected argument '-C' found`)
+
+Run from the target repo directory (the wrapper sets `cwd` to `repository_directory`), or place `-C <DIR>` before `review`.
+
+### `codex review` (non-classifying)
+
+Plain `codex review` is a non-interactive review form. It is **not** the skill classifying path: bare `codex review --json` is not a supported classifiable form on the observed CLI (0.144.3). Do not feed plain `codex review` stdout into skill classification.
+
+| Form | Role |
+|---|---|
+| `[PROMPT]` | Optional custom review instructions; `-` reads stdin |
+| `-c` / `--config key=value` | Dotted-path overrides, values parsed as TOML |
+| `--uncommitted` | Staged + unstaged + untracked |
+| `--base <BRANCH>` | Diff against a base branch |
+| `--commit <SHA>` | Diff for a commit |
+| `--title <TITLE>` | Review title |
+| `--enable` / `--disable <FEATURE>` | Feature toggles |
+
+Exactly one target among `PROMPT`, `--uncommitted`, `--base`, and `--commit`. The four targets are mutually exclusive: a flag target never carries a positional `[PROMPT]`, and the custom-instructions text is itself the fourth target (PROMPT mode only). The same target flags apply under `codex exec … review`.
+
+Observed rejection when a flag target is combined with `[PROMPT]` (fixture capture: `codex` 0.144.3):
+
+```text
+error: the argument '--uncommitted' cannot be used with '[PROMPT]'
+Usage: codex exec review --json --uncommitted [PROMPT]
+```
+
+Exit code 2.
+
+### `codex exec` options (before `review`)
+
+| Option | Role |
+|---|---|
+| `-c` / `--config` | Config override |
+| `-i` / `--image` | Image input |
+| `-m` / `--model` | Model id |
+| `--oss` | OSS path |
+| `-p` / `--profile` | Profile |
+| `-s` / `--sandbox <read-only\|workspace-write\|danger-full-access>` | Sandbox mode |
+| `--full-auto` | Full auto |
+| `--dangerously-bypass-approvals-and-sandbox` | Bypass approvals and sandbox |
+| `-C` / `--cd <DIR>` | Working directory |
+| `--json` | JSONL event stream on stdout (required for classification) |
+| `-o` / `--output-last-message` | Write last message to a path |
+
+## Probe
+
+The wrapper probes before every review. Any failure returns `outcome_class=codex_down` and does not run the review.
+
+| Step | Command | Pass rule |
+|---|---|---|
+| Version | `codex --version` | Exit 0; version string parsed from stdout |
+| Shape | `codex exec review --help` | Exit 0; help text contains each required flag as a **whole token** |
+
+### Minimum shape signals
+
+The `review` subcommand is proven by the probe itself: a CLI without it exits non-zero on `codex exec review --help`, which is already a `codex_down` signal.
+
+Required whole-token flags:
+
+| Signal | Role |
+|---|---|
+| `--uncommitted` | Staged + unstaged + untracked target |
+| `--base` | Base-branch target |
+| `--commit` | Commit-SHA target |
+| `--json` | JSONL event stream on stdout |
+
+Longer lookalikes (`--baseline`, `--uncommitted-only`, `--commit-message`) do not satisfy the required target flags.
+
+### Fail-closed rule
+
+Any missing signal, non-zero probe exit, missing binary, timeout, or decode failure is `codex_down` (skill class `down`). Do not continue to a review invoke when the probe fails.
+
+## Success stream
+
+With `--json`, a successful run writes JSONL on stdout and exits 0. The wrapper writes stdout to `run_state_directory/codex-review.jsonl`.
+
+Fixture: `../scripts/fixtures/success_stream_v0.144.3.jsonl`.
+
+Typical event order:
+
+1. `thread.started` — includes `thread_id`
+2. `turn.started`
+3. `item.started` / `item.completed` pairs for `command_execution` items
+4. `item.completed` with `"type":"agent_message"` — review text body
+5. `turn.completed` — `usage` object (`input_tokens`, `cached_input_tokens`, `output_tokens`, `reasoning_output_tokens`)
+
+The wrapper extracts the last `item.completed` / `agent_message` / `text` as `agent_message`.
+
+### Finding text shapes
+
+`parse_codex_findings` reads `agent_message` and never drops non-empty text.
+
+| Priority | Shape | Fixture |
+|---|---|---|
+| 1 | Fenced JSON array of objects with keys `title`, `priority`, `file`, `line_range`, `body` | `../scripts/fixtures/structured_findings.txt` |
+| 2 | Freeform bullets `- [P1] <title> — <path>:<start>-<end>` plus body paragraphs | `../scripts/fixtures/freeform_findings_v0.144.3.txt` |
+| 3 | Floor: one unstructured finding whose `body` is the raw text | any non-empty unmatched text |
+
+Empty agent text or a structured empty array (`[]`) yields zero findings (`clean` for gate callers).
+
+## Failure classes
+
+All observed CLI failures map to wrapper `outcome_class=codex_down`. Every nonzero review exit maps to `codex_down`. Wrapper `outcome_class` is the capture success signal: a shape-probe miss can still return `codex_down` when the help process exits 0 but required flags are missing. Callers that need a detail class run `classify_codex_run(exit_code=..., stream_text=...)` separately — that helper treats exit 0 as `completed` and every nonzero exit as `codex_down` plus a detail class. Fixtures under `../scripts/fixtures/` are the source of truth for observed shapes.
+
+| Detail class | Outcome | Fixture | Observed shape |
+|---|---|---|---|
+| `completed` | `completed` | `success_stream_v0.144.3.jsonl` | Exit 0; JSONL success stream |
+| `config_error` | `codex_down` | `config_load_failure_v0.125.0.txt` | Exit 1; plain stderr, e.g. `Error loading config.toml: unknown variant 'default', expected 'fast' or 'flex' in 'service_tier'` |
+| `model_error` | `codex_down` | `model_rejection_v0.125.0.jsonl` | Exit 1; JSONL `error` with embedded 400 `invalid_request_error` (`model is not supported` / `requires a newer version of Codex`), then interrupted agent message, then `turn.failed` |
+| `usage_limit` | `codex_down` | `usage_limit_synthetic.txt` | Exit 1; phrase markers such as rate limit, too many requests, `http 429`, ` (429)`, credits exhausted, out of credits, api quota, usage quota (bare status numbers alone are not markers) |
+| `auth_failure` | `codex_down` | `auth_failure_synthetic.txt` | Exit 1; phrase markers such as unauthorized, authentication failed, login required, not authenticated (bare status numbers alone are not markers) |
+| `unknown` | `codex_down` | `unknown_failure_synthetic.txt` | Exit nonzero with no known marker (also empty stream on nonzero exit) |
+
+Probe and process failures (missing binary exit `127`, timeout exit `124`, decode error exit `70`, shape probe miss) also return `outcome_class=codex_down` from the wrapper. Skill step 4 maps these to skill class `down`. Detail classification is optional for those paths.
+
+CLI parse errors (exit 2, usage on stderr, no JSONL) are `codex_down` with detail `unknown` unless a marker matches.
+
+## Wrapper capture boundary
+
+Entrypoint: `scripts/run_codex_review.py` → `run_codex_review(...)`.
+
+The wrapper is **capture only**. It returns one of two classes:
+
+| Wrapper class | Meaning |
+|---|---|
+| `completed` | Review process exited 0; JSONL stream written under `run_state_directory` |
+| `codex_down` | Binary missing, timeout, decode failure, shape miss, or non-zero review exit |
+
+Skill-level classes `down` / `clean` / `findings` are **not** produced here. The skill (Step 4) maps:
+
+| Skill class | Source |
+|---|---|
+| `down` | Wrapper `codex_down` |
+| `clean` | Wrapper `completed` and findings parse empty |
+| `findings` | Wrapper `completed` and findings parse non-empty |
+
+### Caller contracts
+
+- Create `run_state_directory` before calling the wrapper; the wrapper writes `codex-review.jsonl` into that directory and does not create parents.
+- A missing `repository_directory` or `run_state_directory` raises `ValueError`. Both are checked before any Codex process starts, so a bad path costs no review run.
+- Treat `outcome_class` as the capture success signal; do not treat `exit_code == 0` alone as success.
+- `codex-review.jsonl` holds the stream's own line endings, so the captured file matches the bytes Codex wrote to stdout.
+
+## Skill classification map
+
+Skill steps and loop re-entry use three skill-level classes. This page's raw CLI failure name is `codex_down` only.
+
+| Skill class (`SKILL.md` Step 4) | Maps from this page | Signal |
+|---|---|---|
+| `down` | Any `codex_down` row; unrecognized probe shape | Non-usable review |
+| `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 |
+
+## Auth surface
+
+Placeholders only — never commit real tokens, hosts, or account ids.
+
+| Mode | How |
+|---|---|
+| ChatGPT / file store | Credentials under the Codex home directory as `auth.json`. `CODEX_HOME` relocates that directory. `cli_auth_credentials_store = "file"` in `config.toml` pins the file store. |
+| API key (exec only) | `CODEX_API_KEY=<YOUR_API_KEY>` authenticates a single `codex exec` invocation. |
+| Access-token login | Pipe an enterprise access token into `codex login --with-access-token` (token from a secret store; never inline). |
+
+The same `config.toml` serves the desktop app and the CLI. A value one accepts can fail the other's parser; that path surfaces as the `config_error` row above.
+
+The wrapper inherits the process environment, so `CODEX_HOME` and `CODEX_API_KEY` pass through when set.
+
+## Cloud runbook
+
+End-to-end path for a headless host (CI runner, remote agent, or cloud VM). Every account-specific value is a placeholder.
+
+1. **Install the CLI.** `npm install -g @openai/codex` (or pin a version that still exposes `codex exec review --json` with `--base` / `--uncommitted` / `--commit`).
+2. **Supply one auth mode from a secret store.**
+   - File store: write `auth.json` under `CODEX_HOME=<CODEX_HOME_DIR>` with credentials from the secret store, and set `cli_auth_credentials_store = "file"`.
+   - API key: export `CODEX_API_KEY` from the secret store for the process that runs the wrapper.
+   - Access token: `printf '%s' "$CODEX_ACCESS_TOKEN" | codex login --with-access-token`.
+3. **Fetch a resolvable base ref** when the target is a PR base branch. A bare `git fetch origin <BASE_BRANCH>` only updates `FETCH_HEAD` on a shallow or unconfigured remote and does **not** create `refs/heads/<BASE_BRANCH>`. Create or update a named ref the wrapper can pass to `--base`:
+
+   ```text
+   git fetch origin <BASE_BRANCH>:refs/remotes/origin/<BASE_BRANCH>
+   ```
+
+   Then pass that remote-tracking name as `base_branch` (for example `origin/<BASE_BRANCH>`), or create a local branch that points at the same commit (`git branch -f <BASE_BRANCH> origin/<BASE_BRANCH>`) and pass the local name.
+4. **Run the wrapper** from the repo root with a writable run-state directory:
+
+   ```text
+   run_codex_review(
+       repository_directory=<REPO_ROOT>,
+       run_state_directory=<RUN_STATE_DIR>,
+       base_branch=origin/<BASE_BRANCH>,   # PR loops — same ref the fetch step created
+       # or is_uncommitted=True            # standalone
+   )
+   ```
+
+5. **Parse JSONL / agent text.** On `outcome_class=completed`, call `parse_codex_findings(agent_message)`.
+6. **Classify failures.** On nonzero exit or `outcome_class=codex_down`, call `classify_codex_run(exit_code=..., stream_text=<stdout+stderr>)` when a detail class is needed. Every non-completed detail class is gate-level `codex_down` (fail closed; orchestrators bypass the clean-SHA requirement rather than block forever — see [loop-integration.md](loop-integration.md)).

package/skills/codex-review/reference/loop-integration.md

@@ -0,0 +1,118 @@
+# Loop integration
+
+How `codex-review` plugs into PR-loop orchestrators and standalone runs. Orchestrator-owned detail lives in the linked pages; this page states each rule once and points outward.
+
+## Target selection
+
+| Caller context | Target |
+|---|---|
+| PR loop (`pr-converge`, `autoconverge`, `bugteam`, or an open PR on the branch) | Diff against the PR base branch (`base_branch=<pr.base.ref>` / `--base`) |
+| Standalone (no PR) | Uncommitted work (`is_uncommitted=True` / `--uncommitted`: staged + unstaged + untracked) |
+
+Do not invent a synthetic commit range when a base branch is available. Wrapper argv and probe rules live in [cli-contract.md](cli-contract.md).
+
+## Classification vocabulary
+
+Orchestrators re-enter on the skill-level classes from `SKILL.md` Step 4. CLI failures map through `codex_down` in [cli-contract.md](cli-contract.md).
+
+| Skill class | CLI observation | Orchestrator next step |
+|---|---|---|
+| `down` | `codex_down` / probe miss | Mark the Codex gate skipped or stop per the caller's policy |
+| `clean` | Success stream, no finding bullets | End the Codex gate |
+| `findings` | Success stream with finding bullets | Shared fix path or `pr-fix-protocol` (see Findings handoff) |
+
+## Where the gate sits
+
+### `pr-converge` (tick-driven)
+
+After the terminal Bugbot gate confirms HEAD (or sets `bugbot_down`) and **before** the machine convergence checklist:
+
+1. Opt-out probe (`reviews_disabled.py --reviewer codex`)
+2. Usage probe (`codex_usage_probe.py` → `is_codex_review_required`)
+3. Skill / wrapper against the PR base branch
+4. Classify → stamp, fix, or bypass
+5. Convergence checklist (`check_convergence.py`)
+
+Owner docs: [pr-converge per-tick Codex step](../../pr-converge/reference/per-tick.md#codex-review-step-conditional) and [convergence gate (g)](../../pr-converge/reference/convergence-gates.md#g-codex-review-gate-conditional-required).
+
+### `autoconverge` (single autonomous run)
+
+Phase order ends with terminal confirmation gates: Bugbot → Copilot → **CODEX** → FINALIZE (`check_convergence.py`).
+
+The CODEX phase calls `runCodexGate(head)`, classifies via `classifyCodexGateOutcome`, then:
+
+| Outcome kind | Loop action |
+|---|---|
+| `skip-token` | Set `codexDown`, clear stamp, advance to FINALIZE |
+| `skip-usage` | Clear stamp (no down flag), advance to FINALIZE |
+| `down` | Set `codexDown`, clear stamp, advance to FINALIZE |
+| `fix` (non–code-standard) | Apply fixes via the shared fix path; re-enter CONVERGE |
+| `fix` (standards-only) | Defer via `openStandardsFollowUpOnce`; stamp `codexCleanAt = head`; advance to FINALIZE |
+| `clean` | Stamp `codexCleanAt = head`; advance to FINALIZE |
+| `retry` | Re-run the gate on the same HEAD |
+
+Owner doc: [autoconverge convergence CODEX phase](../../autoconverge/reference/convergence.md).
+
+## Threshold rule
+
+Shared helper only — never restate the numeric percent in callers.
+
+- Probe: `python "$HOME/.claude/skills/codex-review/scripts/codex_usage_probe.py"` → JSON `{percent_left, window_reset, source}`.
+- Decision: `is_codex_review_required(percent_left)` from the same module.
+- **Required** only when `percent_left` is known and strictly greater than `WEEKLY_USAGE_GATE_THRESHOLD_PERCENT` (constant in `codex_review_scripts_constants/codex_usage_probe_constants.py`).
+- **Skipped** when `percent_left` is null or at/below the threshold. Skip never blocks ready; do not stamp a clean SHA.
+
+`check_convergence.py` applies the same helper on the machine checklist so agent path and checklist stay aligned.
+
+## Opt-out token
+
+```bash
+python "$HOME/.claude/_shared/pr-loop/scripts/reviews_disabled.py" --reviewer codex
+```
+
+| Exit | Meaning |
+|---|---|
+| 0 | `CLAUDE_REVIEWS_DISABLED` lists `codex` — treat as bypass (`codex_down` / `codexDown`); do not probe usage or run the wrapper |
+| 1 | Continue |
+
+Gate semantics for the token live in `reviewer-gates`. This skill does not re-parse the env var.
+
+`check_convergence.py` also honors an exported `codex` token (and `--codex-down`) so a re-check without flags still bypasses.
+
+## State fields
+
+| Field | pr-converge (job state / checklist) | autoconverge (run locals → checklist flags) |
+|---|---|---|
+| Clean stamp | `codex_clean_at` — HEAD SHA of last clean skill run, or `null` | `codexCleanAt` → `--codex-clean-at <SHA>` |
+| Down / bypass | `codex_down` — `true` on wrapper `codex_down`, opt-out token, or explicit `--codex-down` | `codexDown` → `--codex-down` |
+
+Rules (stated once):
+
+- Stamp equals `current_head` only when the threshold rule requires a review.
+- Push invalidates both fields (reset stamp to `null`, down to `false`); the next Codex entry re-probes opt-out and usage.
+- While down/bypass is true, the machine gate never blocks ready.
+
+Schema detail: [pr-converge state schema](../../pr-converge/reference/state-schema.md). Checklist labels and detail strings: [convergence gate (g)](../../pr-converge/reference/convergence-gates.md#g-codex-review-gate-conditional-required).
+
+## Findings handoff
+
+Split by caller — do not mix orchestrator vocabularies.
+
+| Caller | On `findings` |
+|---|---|
+| Standalone `/codex-review` | Invoke `pr-fix-protocol` by name with the findings payload, PR scope, and worktree path. That protocol owns test-first fixes, commit, push, and reply-and-resolve when threads exist. |
+| `pr-converge` terminal Codex step | Apply the **shared fix protocol** (same family as other pr-converge findings). Reset push-invalidated markers (all `*_clean_at`, `merge_state_status`, `bugbot_down`, `bugbot_acknowledged_at`, `codex_down`); set `phase = CODE_REVIEW`; schedule the next wakeup. Owner: [pr-converge per-tick Codex step](../../pr-converge/reference/per-tick.md#codex-review-step-conditional). |
+| `autoconverge` CODEX phase | Do **not** call `pr-fix-protocol` by name. Route from the CODEX outcome table above — non-code-standard findings use the orchestrator shared fix path (`applyFixes`) and re-enter CONVERGE; standards-only findings defer a follow-up, stamp `codexCleanAt`, and advance to FINALIZE with no fix push. Owner: [autoconverge convergence CODEX phase](../../autoconverge/reference/convergence.md). |
+
+Codex gate findings are local (no GitHub review thread). Reply-and-resolve applies only when a PR already carries threads from another reviewer.
+
+## Re-entry after a fix
+
+Orchestrators that keep looping after a push:
+
+1. Re-resolve current HEAD (push cleared clean stamps and down flags).
+2. Re-run internal converge / code-review phases as the orchestrator requires (`pr-converge` re-enters at `CODE_REVIEW` after a findings fix; `autoconverge` re-enters CONVERGE after non-standard fixes).
+3. Re-enter the Codex gate against the same target class (PR base branch).
+4. Re-classify: `clean` stamps and ends the Codex gate; `findings` follows the caller-specific handoff table above; `down` / opt-out / usage-skip advances without blocking.
+
+Standalone skill re-entry (babysit mode): re-resolve HEAD, re-run the classifying path (`codex exec … review --json`) on the same target class, re-classify.