claude-dev-env 1.95.0 → 2.0.1

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.

package/skills/codex-review/scripts/codex_down_classifier.py

@@ -0,0 +1,98 @@
+"""Classify Codex run streams into down-detail and gate outcome classes.
+
+::
+
+    classification = classify_codex_run(exit_code=1, stream_text=stderr_text)
+    classification.detail_class   # usage_limit | auth_failure | ...
+    classification.outcome_class  # codex_down | completed
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from codex_review_scripts_constants.classifier_constants import (
+    ALL_AUTH_FAILURE_MARKERS,
+    ALL_CONFIG_ERROR_MARKERS,
+    ALL_MODEL_ERROR_MARKERS,
+    ALL_USAGE_LIMIT_MARKERS,
+    FAILURE_CLASS_AUTH_FAILURE,
+    FAILURE_CLASS_CONFIG_ERROR,
+    FAILURE_CLASS_MODEL_ERROR,
+    FAILURE_CLASS_UNKNOWN,
+    FAILURE_CLASS_USAGE_LIMIT,
+    SUCCESS_EXIT_CODE,
+)
+from codex_review_scripts_constants.run_constants import (
+    OUTCOME_CLASS_CODEX_DOWN,
+    OUTCOME_CLASS_COMPLETED,
+)
+
+
+@dataclass(frozen=True)
+class CodexRunClassification:
+    """Fine-grained failure class plus the gate-level outcome class.
+
+    ::
+
+        CodexRunClassification(
+            detail_class="config_error",
+            outcome_class="codex_down",
+        )
+
+    Attributes:
+        detail_class: ``completed`` or a failure class name.
+        outcome_class: ``completed`` or ``codex_down`` for the conditional gate.
+    """
+
+    detail_class: str
+    outcome_class: str
+
+
+def _stream_contains_marker(stream_text: str, all_markers: tuple[str, ...]) -> bool:
+    lowered_stream = stream_text.lower()
+    return any(each_marker in lowered_stream for each_marker in all_markers)
+
+
+def _classify_failure_detail(stream_text: str) -> str:
+    if _stream_contains_marker(stream_text, ALL_CONFIG_ERROR_MARKERS):
+        return FAILURE_CLASS_CONFIG_ERROR
+    if _stream_contains_marker(stream_text, ALL_MODEL_ERROR_MARKERS):
+        return FAILURE_CLASS_MODEL_ERROR
+    if _stream_contains_marker(stream_text, ALL_USAGE_LIMIT_MARKERS):
+        return FAILURE_CLASS_USAGE_LIMIT
+    if _stream_contains_marker(stream_text, ALL_AUTH_FAILURE_MARKERS):
+        return FAILURE_CLASS_AUTH_FAILURE
+    return FAILURE_CLASS_UNKNOWN
+
+
+def classify_codex_run(*, exit_code: int, stream_text: str) -> CodexRunClassification:
+    """Map exit code and stream text to detail and gate outcome classes.
+
+    ::
+
+        classify_codex_run(exit_code=0, stream_text=success_jsonl)
+        # ok: detail_class=completed, outcome_class=completed
+        classify_codex_run(exit_code=1, stream_text="rate limit")
+        # ok: detail_class=usage_limit, outcome_class=codex_down
+
+    Exit zero is a completed review. Every other class — including
+    ``unknown`` for nonzero exits and unparseable text — maps to
+    ``codex_down`` so the conditional gate fails closed.
+
+    Args:
+        exit_code: Process exit code from the Codex review invocation.
+        stream_text: Captured stdout JSONL and/or stderr text.
+
+    Returns:
+        Detail class and gate outcome class for the run.
+    """
+    if exit_code == SUCCESS_EXIT_CODE:
+        return CodexRunClassification(
+            detail_class=OUTCOME_CLASS_COMPLETED,
+            outcome_class=OUTCOME_CLASS_COMPLETED,
+        )
+    return CodexRunClassification(
+        detail_class=_classify_failure_detail(stream_text),
+        outcome_class=OUTCOME_CLASS_CODEX_DOWN,
+    )

package/skills/codex-review/scripts/codex_review_scripts_constants/CLAUDE.md

@@ -0,0 +1,18 @@
+# codex-review/scripts/codex_review_scripts_constants
+
+Python package of named constants imported by codex-review scripts. Importing from this package keeps magic values out of script bodies.
+
+## Modules
+
+| File | Constants for |
+|---|---|
+| `__init__.py` | Package marker and package docstring. |
+| `run_constants.py` | Binary name, flag strings, custom-instructions prompt, version-probe pattern, timeout default, decode/timeout exit sentinels, flag_token_pattern suffix (whole-token shape match), JSONL keys, and capture outcome class labels for `run_codex_review.py`. |
+| `findings_constants.py` | Finding field keys, fenced-JSON and freeform patterns for `parse_codex_findings.py`. |
+| `classifier_constants.py` | Failure class names and stream markers for `codex_down_classifier.py`. |
+| `run_constants.py` | Binary name, flag strings, custom-instructions prompt, version-probe pattern, timeout default, decode/timeout exit sentinels, flag_token_pattern suffix (whole-token shape match), JSONL keys, JSONL capture filename and newline mode, and capture outcome class labels for `run_codex_review.py`. |
+| `codex_usage_probe_constants.py` | The weekly-usage probe CLI: gate threshold, report JSON keys, app-server JSON-RPC surface, rate-limit field keys, weekly-window sizing, text-status parse patterns, source labels, and exit codes. |
+
+## Convention
+
+Scripts import from this package at module scope. No constant is defined inline in a script body — the hook enforces this at write time.

package/skills/codex-review/scripts/codex_review_scripts_constants/__init__.py

@@ -0,0 +1 @@
+"""Named constants for the codex-review skill scripts."""

package/skills/codex-review/scripts/codex_review_scripts_constants/classifier_constants.py

@@ -0,0 +1,35 @@
+"""Named constants for the Codex down-classifier."""
+
+from __future__ import annotations
+
+FAILURE_CLASS_USAGE_LIMIT = "usage_limit"
+FAILURE_CLASS_AUTH_FAILURE = "auth_failure"
+FAILURE_CLASS_CONFIG_ERROR = "config_error"
+FAILURE_CLASS_MODEL_ERROR = "model_error"
+FAILURE_CLASS_UNKNOWN = "unknown"
+ALL_CONFIG_ERROR_MARKERS = (
+    "error loading config.toml",
+    "unknown variant",
+)
+ALL_MODEL_ERROR_MARKERS = (
+    "invalid_request_error",
+    "model is not supported",
+    "requires a newer version of codex",
+)
+ALL_USAGE_LIMIT_MARKERS = (
+    "rate limit",
+    "too many requests",
+    "http 429",
+    " (429)",
+    "credits exhausted",
+    "out of credits",
+    "api quota",
+    "usage quota",
+)
+ALL_AUTH_FAILURE_MARKERS = (
+    "unauthorized",
+    "authentication failed",
+    "login required",
+    "not authenticated",
+)
+SUCCESS_EXIT_CODE = 0

package/skills/codex-review/scripts/codex_review_scripts_constants/codex_usage_probe_constants.py

@@ -0,0 +1,86 @@
+"""Constants for the Codex weekly-usage probe CLI.
+
+Groups: gate threshold, probe report JSON keys, app-server JSON-RPC surface,
+rate-limit snapshot field keys, weekly-window sizing, parse patterns for
+text status output, source labels, and exit codes.
+"""
+
+from __future__ import annotations
+
+WEEKLY_USAGE_GATE_THRESHOLD_PERCENT = 10
+
+USAGE_REPORT_KEY_PERCENT_LEFT = "percent_left"
+USAGE_REPORT_KEY_WINDOW_RESET = "window_reset"
+USAGE_REPORT_KEY_SOURCE = "source"
+
+CODEX_BINARY_NAME = "codex"
+ALL_APP_SERVER_COMMAND_PARTS = ("app-server", "--listen", "stdio://")
+APP_SERVER_TIMEOUT_SECONDS = 30
+READER_THREAD_JOIN_TIMEOUT_SECONDS = 2
+PROCESS_TREE_WAIT_TIMEOUT_SECONDS = 5
+WINDOWS_OS_NAME = "nt"
+WINDOWS_COMMAND_SHELL = "cmd"
+WINDOWS_COMMAND_SHELL_RUN_FLAG = "/c"
+ALL_WINDOWS_SCRIPT_SUFFIXES = (".cmd", ".bat")
+WINDOWS_TASKKILL_COMMAND = "taskkill"
+WINDOWS_TASKKILL_FORCE_FLAG = "/F"
+WINDOWS_TASKKILL_TREE_FLAG = "/T"
+WINDOWS_TASKKILL_PID_FLAG = "/PID"
+
+JSONRPC_VERSION = "2.0"
+JSONRPC_KEY_ID = "id"
+JSONRPC_KEY_METHOD = "method"
+JSONRPC_KEY_PARAMS = "params"
+JSONRPC_KEY_REPLY_BODY = "result"
+JSONRPC_KEY_ERROR = "error"
+JSONRPC_KEY_VERSION = "jsonrpc"
+
+INITIALIZE_REQUEST_ID = 1
+RATE_LIMITS_REQUEST_ID = 2
+METHOD_INITIALIZE = "initialize"
+METHOD_INITIALIZED = "initialized"
+METHOD_RATE_LIMITS_READ = "account/rateLimits/read"
+
+CLIENT_INFO_KEY = "clientInfo"
+CLIENT_INFO_NAME_KEY = "name"
+CLIENT_INFO_VERSION_KEY = "version"
+CLIENT_INFO_NAME = "codex-usage-probe"
+CLIENT_INFO_VERSION = "1.0.0"
+CAPABILITIES_KEY = "capabilities"
+EXPERIMENTAL_API_KEY = "experimentalApi"
+
+RATE_LIMITS_KEY = "rateLimits"
+PRIMARY_WINDOW_KEY = "primary"
+SECONDARY_WINDOW_KEY = "secondary"
+USED_PERCENT_KEY = "usedPercent"
+RESETS_AT_KEY = "resetsAt"
+WINDOW_DURATION_MINS_KEY = "windowDurationMins"
+
+WEEKLY_WINDOW_DURATION_MINUTES = 10080
+PERCENT_FULL = 100
+PERCENT_EMPTY = 0
+
+SOURCE_APP_SERVER_RATE_LIMITS = "codex app-server account/rateLimits/read"
+SOURCE_TEXT_STATUS = "text-status"
+SOURCE_NO_USAGE_SURFACE = "no-usage-surface"
+
+TEXT_WEEKLY_PERCENT_LEFT_PATTERN = (
+    r"(?i)weekly(?:\s+(?:limit|usage|cap))?"
+    r"[^\n%]{0,40}?"
+    r"(?P<percent>\d{1,3}(?:\.\d+)?)\s*%\s*(?:left|remaining)"
+)
+TEXT_WEEKLY_USED_PERCENT_PATTERN = (
+    r"(?i)weekly(?:\s+(?:limit|usage|cap))?"
+    r"[^\n%]{0,40}?"
+    r"(?P<percent>\d{1,3}(?:\.\d+)?)\s*%\s*(?:used|consumed)"
+)
+TEXT_WINDOW_RESET_PATTERN = (
+    r"(?i)(?:weekly\s+)?(?:window\s+)?resets?(?:\s+at)?"
+    r"[:\s]+(?P<reset>[^\s)\].,;]+)"
+)
+
+EXIT_CODE_SUCCESS = 0
+EXIT_CODE_CRASH = 1
+
+UTF8_ENCODING = "utf-8"
+NEWLINE = "\n"

package/skills/codex-review/scripts/codex_review_scripts_constants/findings_constants.py

@@ -0,0 +1,18 @@
+"""Named constants for the Codex findings parser."""
+
+from __future__ import annotations
+
+FINDING_KEY_TITLE = "title"
+FINDING_KEY_PRIORITY = "priority"
+FINDING_KEY_FILE = "file"
+FINDING_KEY_LINE_RANGE = "line_range"
+FINDING_KEY_BODY = "body"
+FENCED_JSON_BLOCK_PATTERN = r"```(?:json)?\s*\n(.*?)\n```"
+FREEFORM_FINDING_LINE_PATTERN = (
+    r"^-\s*\[(?P<priority>P\d+)\]\s+"
+    r"(?P<title>.+?)\s+[—–-]\s+"
+    r"(?P<file_path>.+?):(?P<line_range>\d+-\d+)\s*$"
+)
+FREEFORM_BULLET_PREFIX = "- ["
+EMPTY_STRING = ""
+NEWLINE = "\n"