Forward --backend through skill Step-5 template + document codex surface area

R0 review on PR #421 caught the exact "incomplete parameter propagation"
anti-pattern: the script accepted --backend via argparse, but the skill's
Step-5 command template never forwarded it. Effect: `/ai-review-local
--backend codex` (or `--backend api`) was silently ignored, and the script's
default `auto` always won.

Fix:
  - Step 5 command template now includes `--backend "$backend"`
  - Step 5 bullet list documents that --backend always passes through
  - New test `test_skill_step5_command_template_forwards_backend` pins
    the template (asserts both the literal `--backend ` token and the
    `$backend` shell variable are present)

Also documents codex backend's surface area in the skill doc:

  Under codex backend, Codex can read any file under the repo root (via
  `--cd`), not just the staged diff. Same surface as direct `codex` use,
  but the Step-3b pre-upload secret scan only covers diff content, NOT
  files Codex may load on its own. Recommend `--backend api` (or a
  sanitized worktree) when the repo contains sensitive files outside the
  diff.

This is documentation, not enforcement — sandboxing reads to a temp
checkout would defeat the agentic value (Codex needs the full repo to
do cross-surface audits). Users opting into codex are already running
`codex` directly as part of `codex login` setup.

197 tests pass.

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

Author: igerber

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

@@ -36,6 +36,13 @@ Notes:
   cleaned up automatically.
 - `--context` and `--token-budget` are ignored under the codex backend (Codex
   chooses what to load on its own); the script warns if you pass them.
+- **Surface area**: under the codex backend, Codex can read any file under the
+  repo root via `--cd`, not just the staged diff. This is the same surface that
+  any direct invocation of `codex` itself would have, but worth knowing: the
+  Step 3b pre-upload secret scan only covers diff content, NOT files Codex may
+  load on its own. If your repo contains sensitive files outside the diff
+  (e.g. `.env`, local credentials), prefer `--backend api` or run the codex
+  backend from a sanitized worktree.
 
 ## Arguments
 
@@ -356,10 +363,11 @@ review via `--previous-review`.
 ### Step 5: Run the Review Script
 
 Build and run the command. Include optional arguments only when their conditions are met:
+- `--backend`: pass through from parsed arguments (default `auto`); the script auto-detects
 - `--previous-review`: only if `.claude/reviews/local-review-previous.md` exists AND `--force-fresh` was NOT set
 - `--delta-diff` and `--delta-changed-files`: only if delta files were generated in Step 4
 - `--review-state`, `--commit-sha`, `--base-ref`: always include (even with `--force-fresh`, to seed a new baseline)
-- `--context`, `--include-files`, `--token-budget`: pass through from parsed arguments
+- `--context`, `--include-files`, `--token-budget`: pass through from parsed arguments (only meaningful for `--backend api`; ignored under codex)
 
 ```bash
 python3 .claude/scripts/openai_review.py \
@@ -370,6 +378,7 @@ python3 .claude/scripts/openai_review.py \
     --output .claude/reviews/local-review-latest.md \
     --branch-info "$branch_name" \
     --repo-root "$(pwd)" \
+    --backend "$backend" \
     --context "$context_level" \
     --review-state .claude/reviews/review-state.json \
     --commit-sha "$(git rev-parse HEAD)" \
@@ -385,6 +394,12 @@ python3 .claude/scripts/openai_review.py \
     [--dry-run]
 ```
 
+Always pass `--backend "$backend"` (where `$backend` is the parsed value, defaulting
+to `auto`). The script handles auto-detection internally; forwarding the flag means
+explicit `/ai-review-local --backend codex` and `/ai-review-local --backend api`
+choices are honored end-to-end. Without forwarding, the user's `--backend` selection
+would be silently ignored.
+
 Note: `--force-fresh` is a skill-only flag — it controls whether delta diffs are
 generated in Step 4 and is NOT passed to the script.
 

tests/test_openai_review.py

@@ -2045,6 +2045,26 @@ def test_skill_doc_mentions_codex_install(self):
         assert "brew install --cask codex" in text or "@openai/codex" in text
         assert "codex login" in text
 
+    def test_skill_step5_command_template_forwards_backend(self):
+        """Regression: the Step-5 invocation MUST pass --backend through to
+        the script. Without this, /ai-review-local --backend codex (or api)
+        is silently ignored — the script's parsed --backend always defaults
+        to 'auto'. This is the exact 'incomplete parameter propagation'
+        anti-pattern; pin the template."""
+        assert _SCRIPT_PATH is not None
+        repo_root = _SCRIPT_PATH.parent.parent.parent
+        doc = repo_root / ".claude" / "commands" / "ai-review-local.md"
+        if not doc.exists():
+            pytest.skip("ai-review-local.md not found")
+        text = doc.read_text()
+        # The Step 5 command template must contain the --backend flag,
+        # forwarded as a shell variable substitution.
+        assert "--backend " in text and "$backend" in text, (
+            "Step 5 command template must forward --backend to the script "
+            "(use `--backend \"$backend\"`); otherwise users' explicit "
+            "--backend selection is dropped."
+        )
+
 
 class TestExtractResponseText:
     def test_prefers_output_text_field(self, review_mod):