Enforce auth on explicit --backend codex; refresh stale doc strings

R5 review on PR #421 returned ✅ Looks good with two non-blocking items:

P2: --backend codex (explicit) only checked for the binary, not auth.json.
On a machine with codex installed but `codex login` not run, the script
would degrade into a confusing late subprocess error inside `codex exec`,
and the runtime banner would unconditionally claim "auth.json detected".

  - _detect_backend("codex") now also requires CODEX_AUTH_PATH to exist
    and raises a clear "no codex auth found at ~/.codex/auth.json — run
    `codex login`" if absent. Auto-mode unaffected (already gated on
    both checks).
  - Runtime banner only mentions auth.json when it actually exists
    (defensive — auto-mode gates already require it, but the explicit-
    mode change above makes the same invariant true everywhere).
  - Test test_explicit_codex_with_auth: writes auth.json before assert
    (was implicitly relying on the now-removed "auth not checked" path)
  - New test test_explicit_codex_errors_when_auth_missing: codex on PATH
    but no auth.json → RuntimeError "no codex auth found"

P3: Four stale doc/CLI strings refreshed for the dual-backend world:
  - Skill doc bullet describing .claude treatment now reflects the
    .claude/settings.local.json scanning + .claude/reviews/ exclusion
    (was: "skipped wholesale")
  - Skill doc Step 1 default-behavior text mentions auto-detect backend
    (was: "live API call")
  - --dry-run argparse + skill doc help: "without invoking the chosen
    backend (no api call, no codex subprocess)" (was: "without calling
    the API")
  - --repo-root argparse help: per-backend behavior (api: required for
    standard/deep; codex: optional, falls back to cwd) (was: blanket
    "required unless --context minimal")

Tests: 233 pass (1 new).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: igerber

.claude/commands/ai-review-local.md

@@ -58,9 +58,14 @@ Notes:
      definitions, or doc examples. Filename scan still applies to those
      dirs (so a real `.env` checked into `tests/` would still be caught).
 
-  Heavy dirs (`.venv`, `node_modules`, `__pycache__`, `.claude`, etc.) are
-  skipped to avoid vendored test fixtures. Both scans include gitignored
-  files — gitignored `.env` files are exactly what we want to catch.
+  Heavy dirs (`.venv`, `node_modules`, `__pycache__`, etc.) are skipped from
+  the walk to avoid vendored test fixtures. The `.claude/` subtree is NOT
+  skipped wholesale — `.claude/settings.local.json` (gitignored, common
+  place for OAuth tokens) is content-scanned. Only `.claude/reviews/` and
+  `.claude/paper-review/` (agent-generated review artifacts that may quote
+  literal pattern strings) are excluded from the content scan; their
+  filenames are still scanned. Both scans include gitignored files —
+  gitignored `.env` files are exactly what we want to catch.
 
   If either scan finds matches, codex is **NOT invoked** and the script
   exits 1 unless you pass `--allow-secrets` to acknowledge the surface.
@@ -89,7 +94,8 @@ Notes:
 - `--full-registry`: Include the entire REGISTRY.md instead of selective sections
 - `--model <name>`: Override the model (default: `gpt-5.4`). Applies to both backends.
 - `--timeout <seconds>`: HTTP request timeout. If omitted, defaults to 900 for reasoning models (gpt-5.4, *-pro, o1/o3/o4) and 300 otherwise. *Api backend only.*
-- `--dry-run`: Print the compiled prompt without calling the API
+- `--dry-run`: Print the compiled prompt without invoking the chosen backend
+  (no API call, no codex subprocess)
 
 **Reasoning models** (`gpt-5.4-pro`, `o3`, `o4-mini`, etc.) on the api backend:
 Reviews may take 10-15 minutes. For deep reviews with reasoning models, combine
@@ -126,7 +132,8 @@ Step 5 invokes the chosen backend:
 ### Step 1: Parse Arguments
 
 Parse `$ARGUMENTS` for the optional flags listed above. All flags are optional —
-the default behavior (standard context, selective registry, gpt-5.4, live API call)
+the default behavior (auto-detect backend, standard context for api or
+agentic loading for codex, selective registry, gpt-5.4)
 requires no arguments.
 
 ### Step 2: Validate Prerequisites
@@ -566,7 +573,7 @@ runs `--force-fresh` or when a rebase invalidates the tracked commit.
 # Api backend, extra context files
 /ai-review-local --backend api --include-files linalg.py,utils.py
 
-# Preview the compiled prompt without calling the API
+# Preview the compiled prompt without invoking the chosen backend
 /ai-review-local --dry-run
 
 # Force a fresh review (ignore previous review state)

.claude/scripts/openai_review.py

@@ -1454,6 +1454,12 @@ def _detect_backend(requested: str) -> str:
                 "Install via `brew install --cask codex` or "
                 "`npm install -g @openai/codex`, then run `codex login`."
             )
+        if not os.path.exists(CODEX_AUTH_PATH):
+            raise RuntimeError(
+                f"--backend codex requested but no codex auth found at "
+                f"{CODEX_AUTH_PATH}. Run `codex login` first (subscription "
+                f"or API key)."
+            )
         return "codex"
     if requested == "api":
         return "api"
@@ -1809,7 +1815,10 @@ def main() -> None:
     parser.add_argument(
         "--dry-run",
         action="store_true",
-        help="Print compiled prompt to stdout without calling the API",
+        help=(
+            "Print compiled prompt to stdout without invoking the chosen "
+            "backend (no api call, no codex subprocess)"
+        ),
     )
     # New arguments
     parser.add_argument(
@@ -1822,7 +1831,12 @@ def main() -> None:
     parser.add_argument(
         "--repo-root",
         default=None,
-        help="Repository root directory (required unless --context minimal)",
+        help=(
+            "Repository root directory. Api backend: required when --context "
+            "is 'standard' or 'deep' (used for source-file preloading). Codex "
+            "backend: optional — falls back to os.getcwd() and is passed to "
+            "`codex exec --cd`."
+        ),
     )
     parser.add_argument(
         "--include-files",
@@ -2183,8 +2197,17 @@ def main() -> None:
 
     # Dispatch on backend.
     if backend == "codex":
+        # Only mention auth.json if it actually exists. Auto-mode requires it
+        # to pick codex; explicit `--backend codex` now also requires it (see
+        # _detect_backend) — but defensive check here prevents misleading log
+        # if either invariant ever loosens.
+        auth_note = (
+            f" (auth.json detected at {CODEX_AUTH_PATH})"
+            if os.path.exists(CODEX_AUTH_PATH)
+            else ""
+        )
         print(
-            f"Using codex backend (auth.json detected at {CODEX_AUTH_PATH}); "
+            f"Using codex backend{auth_note}; "
             f"sending to {args.model} via `codex exec`...",
             file=sys.stderr,
         )

tests/test_openai_review.py

@@ -1870,9 +1870,12 @@ def test_auto_no_auth(self, patched, review_mod):
         # Don't create auth.json
         assert review_mod._detect_backend("auto") == "api"
 
-    def test_explicit_codex(self, patched, review_mod):
+    def test_explicit_codex_with_auth(self, patched, review_mod):
+        """Explicit `--backend codex` requires both the binary AND auth.json
+        — without auth, codex would fail late (subprocess) with a confusing
+        error; the explicit-request path now fails fast with actionable text."""
         self._set_codex_present(patched, True)
-        # auth.json existence is NOT checked when explicitly requested
+        patched["auth"].write_text("{}")  # auth present
         assert review_mod._detect_backend("codex") == "codex"
 
     def test_explicit_api(self, patched, review_mod):
@@ -1886,6 +1889,15 @@ def test_explicit_codex_errors_when_codex_missing(self, patched, review_mod):
         with pytest.raises(RuntimeError, match="codex.*not installed"):
             review_mod._detect_backend("codex")
 
+    def test_explicit_codex_errors_when_auth_missing(self, patched, review_mod):
+        """Codex installed but `codex login` not done — fast-fail with a
+        clear message instead of degrading into a confusing subprocess
+        error inside `codex exec`."""
+        self._set_codex_present(patched, True)
+        # Don't write auth.json
+        with pytest.raises(RuntimeError, match="no codex auth found"):
+            review_mod._detect_backend("codex")
+
 
 class TestBuildCodexCmd:
     """`_build_codex_cmd` constructs the argv for `codex exec`. The literal