tlc-claude-code 2.4.9 → 2.5.0

package/.claude/commands/tlc/review.md

@@ -1,15 +1,15 @@
-# /tlc:review - Review Current Branch
-
-Review changes on current branch before pushing. **Runs in a loop until clean.**
-
-## Routing
-
-This command supports multi-model routing via `~/.tlc/config.json`.
-
-**Before executing this command:**
-
-1. Read routing config:
-   ```bash
+# /tlc:review - Review Current Branch
+
+Review changes on current branch before pushing. **Runs in a loop until clean.**
+
+## Routing
+
+This command supports multi-model routing via `~/.tlc/config.json`.
+
+**Before executing this command:**
+
+1. Read routing config:
+   ```bash
    node -e "const fs = require('fs');
 const path = require('path');
 const os = require('os');
@@ -80,227 +80,252 @@ function resolveRouting(options) {
 }
 const result = resolveRouting({ command: \"review\", flagModel: process.argv[1], projectDir: process.cwd(), homeDir: process.env.HOME || os.homedir(), fs });
 process.stdout.write(JSON.stringify(result));" 2>/dev/null
-   ```
-
-2. If `models[0]` is NOT `claude` (i.e., routed to external model):
-   - Read PROJECT.md, current phase PLAN.md, CODING-STANDARDS.md
-   - Package the agent prompt below with project context using `prompt-packager`
-   - Dispatch to the target CLI using `cli-dispatcher`
-   - Display the CLI output and stop — do NOT execute the agent prompt below
-
-3. If `models[0]` IS `claude` (or no routing config exists):
-   - Execute the agent prompt below as normal (current behavior)
-
-4. If `strategy` is `parallel`:
-   - Execute inline (Claude) AND dispatch to CLI models simultaneously
-   - Collect and merge results
-
-**Override:** Pass `--model <name>` to route this specific run to a different model.
-
-## What This Does
-
-1. Compares current branch to main/master
-2. **Invokes configured review providers** (Claude, Codex, Gemini)
-3. Checks test coverage for all changed files
-4. Analyzes commit order for TDD compliance
-5. Scans for security issues
-6. If issues found → **fix them automatically, then re-review**
-7. **Repeats until both Claude and Codex approve** — no arbitrary limit, runs until clean
-
-**This is an iterative review loop, not a single pass.** Think of it as RL-mode: keep fixing and re-checking until the code is foolproof.
-
-**This runs automatically at the end of `/tlc:build`.**
-
-## Multi-Provider Reviews
-
-TLC automatically uses ALL providers configured for the `review` capability in `.tlc.json`:
-
-```json
-{
-  "router": {
-    "capabilities": {
-      "review": { "providers": ["claude", "codex"], "fallback": "claude" }
-    }
-  }
-}
-```
-
-**With this config, `/tlc:review` will:**
-1. Run Claude's review (current session)
+   ```
+
+2. If `models[0]` is NOT `claude` (i.e., routed to external model):
+   - Read PROJECT.md, current phase PLAN.md, CODING-STANDARDS.md
+   - Package the agent prompt below with project context using `prompt-packager`
+   - Dispatch to the target CLI using `cli-dispatcher`
+   - Display the CLI output and stop — do NOT execute the agent prompt below
+
+3. If `models[0]` IS `claude` (or no routing config exists):
+   - Execute the agent prompt below as normal (current behavior)
+
+4. If `strategy` is `parallel`:
+   - Execute inline (Claude) AND dispatch to CLI models simultaneously
+   - Collect and merge results
+   - **CRITICAL: If a provider fails (wrong model, auth error, CLI missing), do NOT silently fall back to single-provider.** Instead:
+     1. Check `.tlc/.router-state.json` for the provider's actual available model and retry
+     2. If retry fails, ask the user: "[Provider] failed: [reason]. Run with [other provider] only, or fix and retry?"
+     3. Never say "proceeding with X-only" without user consent
+
+**Override:** Pass `--model <name>` to route this specific run to a different model.
+
+## What This Does
+
+1. Compares current branch to main/master
+2. **Invokes configured review providers** (Claude, Codex, Gemini)
+3. Checks test coverage for all changed files
+4. Analyzes commit order for TDD compliance
+5. Scans for security issues
+6. If issues found → **fix them automatically, then re-review**
+7. **Repeats until both Claude and Codex approve** — no arbitrary limit, runs until clean
+
+**This is an iterative review loop, not a single pass.** Think of it as RL-mode: keep fixing and re-checking until the code is foolproof.
+
+**This runs automatically at the end of `/tlc:build`.**
+
+## Multi-Provider Reviews
+
+TLC automatically uses ALL providers configured for the `review` capability in `.tlc.json`:
+
+```json
+{
+  "router": {
+    "capabilities": {
+      "review": { "providers": ["claude", "codex"], "fallback": "claude" }
+    }
+  }
+}
+```
+
+**With this config, `/tlc:review` will:**
+1. Run Claude's review (current session)
 2. Invoke Codex CLI for second opinion: `codex exec review --base main -m gpt-5.4 --json --ephemeral`
-3. Combine verdicts - both must approve for APPROVED
-
-## Usage
-
-```
-/tlc:review              # Review current branch vs main
-/tlc:review --base dev   # Review vs different base branch
-```
-
-## Process
-
-### Step 1: Load Router State (Persistent)
-
-**Always read from the router state file first**, then fall back to config:
-
-```javascript
-// 1. Read persistent router state (written by session-init hook)
-const routerState = JSON.parse(fs.readFileSync('.tlc/.router-state.json', 'utf-8'));
-
-// 2. Read config for capability mappings
-const config = JSON.parse(fs.readFileSync('.tlc.json', 'utf-8'));
-const reviewProviders = config.router?.capabilities?.review?.providers || ['claude'];
-const providers = config.router?.providers || {};
-
-// 3. Filter to only AVAILABLE providers (from state file)
-const availableReviewers = reviewProviders.filter(p =>
-  routerState.providers[p]?.available === true
-);
-```
-
-**The state file (`.tlc/.router-state.json`) is authoritative for availability.** It's written by the `SessionStart` hook, re-probed every hour, and persists across skill invocations. Never run `which codex` yourself — read the state file.
-
-If the state file is missing or stale (>1 hour), probe manually and write a fresh one.
-
-**Default providers for review:** `['claude', 'codex']` — but only invoked if the state file confirms they're available.
-
-If Codex is configured AND available in state, it WILL be invoked automatically.
-
-### Step 2: Identify Changes
-
-```bash
-git diff --name-status main...HEAD
-```
-
-Categorize files:
-- Implementation files (`.js`, `.ts`, `.py`, etc.)
-- Test files (`*.test.*`, `test_*`, `*_test.*`)
-- Other files (docs, config, etc.)
-
-### Step 3: Check Test Coverage
-
-For each implementation file, verify a corresponding test exists:
-
-| Implementation | Expected Test |
-|---------------|---------------|
-| `src/auth.js` | `src/auth.test.js` or `test/auth.test.js` |
-| `lib/utils.ts` | `lib/utils.test.ts` or `tests/utils.test.ts` |
-| `pkg/main.go` | `pkg/main_test.go` |
-| `src/login.py` | `tests/test_login.py` |
-
-**Fail if:** Implementation files have no corresponding test (in changeset or on disk).
-
-### Step 4: Analyze TDD Compliance
-
-Check commit order to verify tests were written first:
-
-```bash
-git log --oneline --name-status main..HEAD
-```
-
-**Score calculation:**
-- Test-only commits → +1 TDD point
-- Implementation-only commits → -1 TDD point (except fix/refactor/chore)
-- Mixed commits → neutral
-
-**TDD Score = (test-first commits / total commits) × 100**
-
-**Fail if:** TDD score < 50% with more than 2 commits.
-
-### Step 5: Security Scan
-
-Scan diff for common security issues:
-
-**Pattern-Based Checks:**
-
-| Pattern | Issue | Severity |
-|---------|-------|----------|
-| `password = "..."` | Hardcoded password | HIGH |
-| `api_key = "..."` | Hardcoded API key | HIGH |
-| `eval(...)` | Code injection risk | MEDIUM |
-| `innerHTML =` | XSS risk | MEDIUM |
-| `dangerouslySetInnerHTML` | React XSS risk | MEDIUM |
-| `exec("..." + var)` | Command injection | HIGH |
-| `SELECT...WHERE...+` | SQL injection | HIGH |
-
-**Semantic Security Checks (read the code, not just grep):**
-
-| Check | What to Look For | Severity |
-|-------|-----------------|----------|
-| **Ownership/IDOR** | Controller methods that take an ID param (`req.params.id`, `@Param('id')`) and query data without checking the requesting user owns the resource. Every data-access endpoint MUST verify ownership, not just authentication. | HIGH |
-| **Secrets in responses** | Response objects, DTOs, or `res.json()`/`res.send()` calls that include fields like `apiKey`, `secret`, `token`, `password`, `webhookSecret`. Secrets are write-only — never return them. | HIGH |
-| **Direct `process.env`** | `process.env.` usage in service, controller, or middleware files. All env access MUST go through a validated config module. Grep: `process\.env\.` in non-config files. | MEDIUM |
-| **Unescaped HTML** | Template literals that build HTML with `${...}` interpolation of variables (e.g., `` `<h1>${user.name}</h1>` ``). All dynamic values in HTML MUST be escaped. | HIGH |
-| **Plaintext sensitive data** | OTP codes, reset tokens, or session secrets stored without hashing. Look for database inserts/updates of these values without a hash step. | HIGH |
-| **Manual instantiation** | `new SomeProvider(...)` or `new SomeService(...)` in application code instead of using DI. | MEDIUM |
-
-**Fail if:** Any HIGH severity issues found.
-
-### Step 5b: Coding Standards Check
-
-Scan all changed/added files for coding standards violations:
-
-#### File Size Check
-```bash
-# For each changed implementation file
-wc -l <file>
-# >1000 lines = ERROR, 500-1000 = WARNING
-```
-
-#### Folder Size Check
-```bash
-# For each folder containing changed files
-ls <folder> | wc -l
-# >15 files = ERROR, 8-15 = WARNING
-```
-
-#### Strict Typing Check
-```bash
-# Scan changed .ts/.tsx files for `any` type
-grep -n ': any' <file>
-grep -n 'as any' <file>
-grep -n '<any>' <file>
-# Any match = ERROR
-```
-
-#### Return Type Check
-```bash
-# Scan changed .ts/.tsx files for exported functions missing return types
-# Pattern: export function name(params) {   (no : ReturnType before {)
-grep -n 'export function.*)[[:space:]]*{' <file>
-grep -n 'export const.*=.*=>.*{' <file>
-# Missing return type on exported function = WARNING
-```
-
-#### Module Structure Check
-```
-# Flag flat folder anti-patterns in changed files:
-# - src/services/ with >5 unrelated services → should be modules/{entity}/
-# - src/controllers/ with >5 controllers → should be modules/{entity}/
-# - src/interfaces/ at project root → should be per-module interfaces/
-```
-
-**Standards results in report:**
-```
-Coding Standards:
-  File Sizes: ✅ All under 1000 lines
-  Folder Sizes: ✅ All under 15 files
-  Strict Typing: ❌ 3 `any` types found
-  ├── src/api/users.controller.ts:45
-  ├── src/api/users.controller.ts:89
-  └── src/services/email.ts:12
-  Return Types: ⚠️ 2 missing on exports
-  Module Structure: ✅ Domain-grouped
-```
-
-**Fail if:** Any `any` types in new code, or files >1000 lines.
-
+3. Combine verdicts - both must approve for APPROVED
+
+## Usage
+
+```
+/tlc:review              # Review current branch vs main
+/tlc:review --base dev   # Review vs different base branch
+```
+
+## Process
+
+### Step 1: Load Router State (Persistent)
+
+**Always read from the router state file first**, then fall back to config:
+
+```javascript
+// 1. Read persistent router state (written by session-init hook)
+const routerState = JSON.parse(fs.readFileSync('.tlc/.router-state.json', 'utf-8'));
+
+// 2. Read config for capability mappings
+const config = JSON.parse(fs.readFileSync('.tlc.json', 'utf-8'));
+const reviewProviders = config.router?.capabilities?.review?.providers || ['claude'];
+const providers = config.router?.providers || {};
+
+// 3. Filter to only AVAILABLE providers (from state file)
+const availableReviewers = reviewProviders.filter(p =>
+  routerState.providers[p]?.available === true
+);
+```
+
+**The state file (`.tlc/.router-state.json`) is authoritative for availability.** It's written by the `SessionStart` hook, re-probed every hour, and persists across skill invocations. Never run `which codex` yourself — read the state file.
+
+If the state file is missing or stale (>1 hour), probe manually and write a fresh one.
+
+**Default providers for review:** `['claude', 'codex']` — but only invoked if the state file confirms they're available.
+
+If Codex is configured AND available in state, it WILL be invoked automatically.
+
+### Step 2: Identify Changes
+
+```bash
+git diff --name-status main...HEAD
+```
+
+Categorize files:
+- Implementation files (`.js`, `.ts`, `.py`, etc.)
+- Test files (`*.test.*`, `test_*`, `*_test.*`)
+- Other files (docs, config, etc.)
+
+### Step 3: Check Test Coverage
+
+For each implementation file, verify a corresponding test exists:
+
+| Implementation | Expected Test |
+|---------------|---------------|
+| `src/auth.js` | `src/auth.test.js` or `test/auth.test.js` |
+| `lib/utils.ts` | `lib/utils.test.ts` or `tests/utils.test.ts` |
+| `pkg/main.go` | `pkg/main_test.go` |
+| `src/login.py` | `tests/test_login.py` |
+
+**Fail if:** Implementation files have no corresponding test (in changeset or on disk).
+
+### Step 4: Analyze TDD Compliance
+
+Check commit order to verify tests were written first:
+
+```bash
+git log --oneline --name-status main..HEAD
+```
+
+**Score calculation:**
+- Test-only commits → +1 TDD point
+- Implementation-only commits → -1 TDD point (except fix/refactor/chore)
+- Mixed commits → neutral
+
+**TDD Score = (test-first commits / total commits) × 100**
+
+**Fail if:** TDD score < 50% with more than 2 commits.
+
+### Step 5: Security Scan
+
+Scan diff for common security issues:
+
+**Pattern-Based Checks:**
+
+| Pattern | Issue | Severity |
+|---------|-------|----------|
+| `password = "..."` | Hardcoded password | HIGH |
+| `api_key = "..."` | Hardcoded API key | HIGH |
+| `eval(...)` | Code injection risk | MEDIUM |
+| `innerHTML =` | XSS risk | MEDIUM |
+| `dangerouslySetInnerHTML` | React XSS risk | MEDIUM |
+| `exec("..." + var)` | Command injection | HIGH |
+| `SELECT...WHERE...+` | SQL injection | HIGH |
+
+**Semantic Security Checks (read the code, not just grep):**
+
+| Check | What to Look For | Severity |
+|-------|-----------------|----------|
+| **Ownership/IDOR** | Controller methods that take an ID param (`req.params.id`, `@Param('id')`) and query data without checking the requesting user owns the resource. Every data-access endpoint MUST verify ownership, not just authentication. | HIGH |
+| **Secrets in responses** | Response objects, DTOs, or `res.json()`/`res.send()` calls that include fields like `apiKey`, `secret`, `token`, `password`, `webhookSecret`. Secrets are write-only — never return them. | HIGH |
+| **Direct `process.env`** | `process.env.` usage in service, controller, or middleware files. All env access MUST go through a validated config module. Grep: `process\.env\.` in non-config files. | MEDIUM |
+| **Unescaped HTML** | Template literals that build HTML with `${...}` interpolation of variables (e.g., `` `<h1>${user.name}</h1>` ``). All dynamic values in HTML MUST be escaped. | HIGH |
+| **Plaintext sensitive data** | OTP codes, reset tokens, or session secrets stored without hashing. Look for database inserts/updates of these values without a hash step. | HIGH |
+| **Manual instantiation** | `new SomeProvider(...)` or `new SomeService(...)` in application code instead of using DI. | MEDIUM |
+
+**Fail if:** Any HIGH severity issues found.
+
+### Step 5b: Coding Standards Check
+
+Scan all changed/added files for coding standards violations:
+
+#### Silent Failure Check (CRITICAL — run first)
+```bash
+# Empty catch blocks
+grep -n 'catch.*{[[:space:]]*}' <file>
+# catch with only return null/undefined/false and no logging
+grep -n 'catch.*{' <file>  # then inspect: does the block log before returning?
+# External calls without try/catch (fetch, pool.query, exec, spawn, readFile, writeFile)
+grep -n 'fetch\|\.query\|execSync\|spawn\|readFile\|writeFile' <file>
+# Each must be wrapped in try/catch with error logging
+# Empty catch = ERROR, silent return = ERROR, unwrapped external call = ERROR
+```
+
+#### Connection State Logging Check
+```bash
+# DB, Redis, WebSocket, Docker, HTTP client connections
+# Must have: connect log, disconnect log, error log
+grep -n 'connect\|createPool\|createClient\|new WebSocket\|new Docker' <file>
+# Each connection point should have associated logging for state changes
+# Missing connection logging = WARNING
+```
+
+#### File Size Check
+```bash
+# For each changed implementation file
+wc -l <file>
+# >1000 lines = ERROR, 500-1000 = WARNING
+```
+
+#### Folder Size Check
+```bash
+# For each folder containing changed files
+ls <folder> | wc -l
+# >15 files = ERROR, 8-15 = WARNING
+```
+
+#### Strict Typing Check
+```bash
+# Scan changed .ts/.tsx files for `any` type
+grep -n ': any' <file>
+grep -n 'as any' <file>
+grep -n '<any>' <file>
+# Any match = ERROR
+```
+
+#### Return Type Check
+```bash
+# Scan changed .ts/.tsx files for exported functions missing return types
+# Pattern: export function name(params) {   (no : ReturnType before {)
+grep -n 'export function.*)[[:space:]]*{' <file>
+grep -n 'export const.*=.*=>.*{' <file>
+# Missing return type on exported function = WARNING
+```
+
+#### Module Structure Check
+```
+# Flag flat folder anti-patterns in changed files:
+# - src/services/ with >5 unrelated services → should be modules/{entity}/
+# - src/controllers/ with >5 controllers → should be modules/{entity}/
+# - src/interfaces/ at project root → should be per-module interfaces/
+```
+
+**Standards results in report:**
+```
+Coding Standards:
+  File Sizes: ✅ All under 1000 lines
+  Folder Sizes: ✅ All under 15 files
+  Strict Typing: ❌ 3 `any` types found
+  ├── src/api/users.controller.ts:45
+  ├── src/api/users.controller.ts:89
+  └── src/services/email.ts:12
+  Return Types: ⚠️ 2 missing on exports
+  Module Structure: ✅ Domain-grouped
+```
+
+**Fail if:** Any `any` types in new code, or files >1000 lines.
+
 ### Step 6: Invoke External Providers (Codex, Gemini)
-
-**CRITICAL: This step runs automatically when providers are configured.**
-
-For each provider in `reviewProviders` (except `claude` which is the current session):
-
+
+**CRITICAL: This step runs automatically when providers are configured.**
+
+For each provider in `reviewProviders` (except `claude` which is the current session):
+
 **How to invoke:**
 
 **Codex** — use `codex exec review` with explicit model selection, JSON output, and `--ephemeral` for CI-style stateless runs. It reads the git diff natively, no need to pipe files.
@@ -375,343 +400,343 @@ Review the full diff against main but do not re-check every local edit. Focus on
 ```
 
 Use `codex exec review`, not plain `codex review`, for better automation controls. Always include `-m gpt-5.4`, `--json`, and `--ephemeral` in automated runs.
-
-**Gemini** — no built-in review command, so save diff and invoke:
-
-```bash
-# Save diff for Gemini
-git diff main...HEAD > /tmp/review-diff.patch
-line_count=$(wc -l < /tmp/review-diff.patch)
-
-# Truncate if too large
-if [ "$line_count" -gt 500 ]; then
-  head -500 /tmp/review-diff.patch > /tmp/review-diff-truncated.patch
-  echo "... truncated (showing first 500 of $line_count lines)" >> /tmp/review-diff-truncated.patch
-  mv /tmp/review-diff-truncated.patch /tmp/review-diff.patch
-fi
-
-gemini --print "Review this code diff as a senior engineer. Provide:
-- Specific line-by-line feedback
-- Security vulnerabilities with file:line references
-- Performance concerns
-- Code quality issues
-- Missing test coverage
-
-Be thorough and specific. End with APPROVED or CHANGES_REQUESTED.
-
-$(cat /tmp/review-diff.patch)"
-```
-
-**Note:** Each CLI has its own syntax. Check `codex --help` and `gemini --help` for exact flags. The `--print` flag outputs the response without interactive mode.
-
-**Example output:**
-
-```
-Invoking Codex (GPT-5.2) for review...
-┌─────────────────────────────────────────┐
-│ Codex Review Result                     │
-├─────────────────────────────────────────┤
-│ Verdict: APPROVED                       │
-│                                         │
-│ Comments:                               │
-│ - Clean implementation                  │
-│ - Tests cover main paths                │
-│ - No security issues detected           │
-└─────────────────────────────────────────┘
-```
-
-**Consensus Mode:**
-- If multiple providers are configured, ALL must approve
-- Any CHANGES_REQUESTED = overall CHANGES_REQUESTED
-- Issues from all providers are combined in the report
-
-### Step 7: Fix-and-Recheck Loop (RL Mode)
-
-**This is the core innovation. Reviews are not one-shot — they loop until clean.**
-
-After Steps 2-6 complete, if ANY issues were found:
-
-```
-┌─────────────────────────────────────────────┐
-│  REVIEW LOOP (runs until clean)             │
-│                                             │
-│  1. Collect all issues from Claude + Codex  │
-│  2. Fix each issue:                         │
-│     - Missing tests → write them            │
-│     - Security issues → patch the code      │
-│     - Coding standards → refactor           │
-│     - Codex feedback → apply fixes          │
-│  3. Run tests to verify fixes don't break   │
-│  4. Commit fixes                            │
-│  5. Re-run Steps 2-6 (full review again)    │
-│  6. If new issues → loop back to 1          │
-│  7. If clean → exit loop, generate report   │
-└─────────────────────────────────────────────┘
-```
-
-**Iteration rules:**
-
-1. **No arbitrary limit** — keep looping until BOTH providers return APPROVED. The code isn't done until it's clean.
-2. **Each iteration runs the FULL check** — don't skip steps. Fresh eyes each time.
-3. **Re-invoke Codex each iteration** — `codex review --base main` sees the latest fixes
-4. **Commit after each fix round** — `git commit -m "fix: address review feedback (round N)"`
-5. **Track what was fixed** — maintain a running list for the final report
-6. **Stuck detection** — if the SAME issue appears 3 times after being "fixed", stop and escalate to the user with context on what was tried. This is the only exit condition besides clean.
-
-**Fix priority order:**
-1. Security issues (HIGH severity) — fix these first, they block everything
-2. Missing tests — write them before touching implementation
-3. Implementation bugs flagged by Codex — apply fixes
-4. Coding standards (file size, `any` types, return types) — refactor
-5. Style/naming/docs — lowest priority, fix if time permits
-
-**What gets auto-fixed vs flagged for human:**
-
-| Issue Type | Auto-Fix | Human Review |
-|-----------|----------|--------------|
-| Missing test file | Write it | - |
-| Hardcoded secret | Replace with env var | If unclear what var to use |
-| `any` type | Replace with proper interface | If domain type unclear |
-| File >1000 lines | Split into sub-modules | If split strategy unclear |
-| Security vulnerability | Patch it | If fix might break behavior |
-| Missing ownership check | Add guard/check | If ownership model unclear |
-| Secrets in response | Remove or mask fields | If field is needed by client |
-| Direct `process.env` | Move to config module | If config module doesn't exist yet |
-| Unescaped HTML | Add escapeHtml() | If templating engine preferred |
-| Plaintext sensitive data | Add hash step | - |
-| Manual `new Service()` | Convert to DI | If DI container not set up |
-| Codex-flagged bug | Apply suggestion | If suggestion conflicts with Claude |
-| Merge conflict | - | Always human |
-
-**Example iteration:**
-
-```
-───────────────────────────────────────
-Review Round 1/5
-───────────────────────────────────────
-Claude: CHANGES_REQUESTED
-  - Missing test for src/utils.js
-  - Hardcoded API key in src/config.js
-Codex:  CHANGES_REQUESTED
-  - Missing null check in src/parser.js:42
-  - No error handling in src/api.js:88
-
-Fixing 4 issues...
-  ✅ Created src/utils.test.js (3 tests)
-  ✅ Replaced hardcoded key with process.env.API_KEY
-  ✅ Added null check in parser.js:42
-  ✅ Added try/catch in api.js:88
-  ✅ All tests pass
-  ✅ Committed: fix: address review feedback (round 1)
-
-───────────────────────────────────────
-Review Round 2/5
-───────────────────────────────────────
-Claude: CHANGES_REQUESTED
-  - src/utils.test.js missing edge case for empty input
-Codex:  APPROVED
-
-Fixing 1 issue...
-  ✅ Added empty input edge case test
-  ✅ All tests pass
-  ✅ Committed: fix: address review feedback (round 2)
-
-───────────────────────────────────────
-Review Round 3/5
-───────────────────────────────────────
-Claude: APPROVED
-Codex:  APPROVED
-
-✅ All providers agree — exiting loop.
-───────────────────────────────────────
-```
-
-**Stuck detection (only exit besides clean):**
-
-```
-───────────────────────────────────────
-Review Round 7
-───────────────────────────────────────
-Claude: APPROVED
-Codex:  CHANGES_REQUESTED
-  - Complex refactor needed in src/legacy.js  ← appeared 3 times
-
-⚠️ STUCK: This issue has reappeared 3 times after being fixed.
-Escalating to human review.
-
-Attempts made:
-  Round 3: Extracted helper function → Codex still flagged
-  Round 5: Split into two modules → Codex still flagged
-  Round 7: Added interface layer → Codex still flagged
-
-This needs human judgment. Run /tlc:review again after manual fix.
-───────────────────────────────────────
-```
-
-### Step 8: Generate Report
-
-```markdown
-# Code Review Report
-
-**Date:** 2024-01-15T10:30:00Z
-**Base:** main → **Head:** feature/auth
-
-## ✅ Verdict: APPROVED
-
-## Summary
-
-- ✅ All changed files have tests
-- ✅ TDD score: 75%
-- ✅ No security issues detected
-- ✅ All files under 1000 lines
-- ✅ No `any` types
-- ✅ All exports have return types
-
-## Statistics
-
-- Files changed: 8
-- Implementation files: 5
-- Test files: 3
-- Commits: 4
-- TDD Score: 75%
-```
-
-### Step 9: Return Verdict
-
-**APPROVED** - All providers agree after N iterations. Ready to push/merge.
-
-**CHANGES_REQUESTED** - Max iterations reached with remaining issues. Needs human review.
-
-## Example Output
-
-### Passing Review (Multi-Provider)
-
-```
-/tlc:review
-
-Loading router config from .tlc.json...
-  Review providers: claude, codex
-
-Reviewing current branch vs main...
-
-Changed files: 6
-├── src/auth/login.js (impl)
-├── src/auth/login.test.js (test) ✓
-├── src/auth/session.js (impl)
-├── src/auth/session.test.js (test) ✓
-└── README.md (docs)
-
-Test coverage: ✅ All implementation files have tests
-
-Commit analysis:
-├── abc1234 test: add login tests
-├── def5678 feat: implement login
-├── ghi9012 test: add session tests
-└── jkl3456 feat: implement session
-
-TDD Score: 50% ✅
-
-Security scan: ✅ No issues found
-
-───────────────────────────────────────
-Invoking Codex (GPT-5.2) for review...
-───────────────────────────────────────
-Codex verdict: ✅ APPROVED
-  - Clean implementation
-  - Good separation of concerns
-  - Tests are comprehensive
-───────────────────────────────────────
-
-Provider Results:
-  ✅ Claude: APPROVED
-  ✅ Codex:  APPROVED
-
-─────────────────────────────────────────────
-✅ APPROVED - Ready to push (2/2 agree)
-─────────────────────────────────────────────
-```
-
-### Failing Review (Multi-Provider Disagreement)
-
-```
-/tlc:review
-
-Loading router config from .tlc.json...
-  Review providers: claude, codex
-
-Reviewing current branch vs main...
-
-Changed files: 4
-├── src/api/users.js (impl)
-├── src/api/auth.js (impl)
-└── src/utils.js (impl)
-
-Test coverage: ❌ 3 files missing tests
-├── src/api/users.js → needs src/api/users.test.js
-├── src/api/auth.js → needs src/api/auth.test.js
-└── src/utils.js → needs src/utils.test.js
-
-Commit analysis:
-└── abc1234 feat: add all features
-
-TDD Score: 0% ❌ (target: 50%+)
-
-Security scan: ❌ 1 high severity issue
-└── src/api/auth.js: password = "admin123"
-
-───────────────────────────────────────
-Invoking Codex (GPT-5.2) for review...
-───────────────────────────────────────
-Codex verdict: ❌ CHANGES_REQUESTED
-  - Missing input validation in users.js
-  - SQL injection risk in auth.js line 45
-  - No error handling for network failures
-───────────────────────────────────────
-
-Provider Results:
-  ❌ Claude: CHANGES_REQUESTED
-  ❌ Codex:  CHANGES_REQUESTED
-
-Combined Issues:
-  [Claude] Missing tests for 3 files
-  [Claude] Hardcoded password
-  [Codex]  Missing input validation
-  [Codex]  SQL injection risk
-  [Codex]  No error handling
-
-───────────────────────────────────────────
-❌ CHANGES_REQUESTED (0/2 approved)
-
-Action required:
-1. Add tests for 3 implementation files
-2. Fix hardcoded password in src/api/auth.js
-3. Add input validation (Codex)
-4. Fix SQL injection risk (Codex)
-5. Consider splitting into test-first commits
-───────────────────────────────────────────
-```
-
-## Flags
-
-| Flag | Description |
-|------|-------------|
-| `--base <branch>` | Compare against different base (default: main) |
-| `--strict` | Fail on any TDD violation |
-| `--no-security` | Skip security scan |
-| `--providers <list>` | Override providers (e.g., `--providers codex,gemini`) |
-| `--codex-only` | Use only Codex for review |
-| `--no-external` | Skip external providers, use Claude only |
-| `--stuck-threshold <N>` | How many times the same issue reappears before escalating to human (default: 3) |
-| `--no-fix` | Single-pass review only — report issues but don't auto-fix |
-| `--fix-all` | Fix even low-priority style issues (default: skip style) |
-
-## Integration
-
-This review runs automatically:
-- At the end of `/tlc:build` (blocks completion if fails)
-- Before `/tlc:verify` (informational)
-- Can be run manually anytime
-
-## ARGUMENTS
-
-$ARGUMENTS
+
+**Gemini** — no built-in review command, so save diff and invoke:
+
+```bash
+# Save diff for Gemini
+git diff main...HEAD > /tmp/review-diff.patch
+line_count=$(wc -l < /tmp/review-diff.patch)
+
+# Truncate if too large
+if [ "$line_count" -gt 500 ]; then
+  head -500 /tmp/review-diff.patch > /tmp/review-diff-truncated.patch
+  echo "... truncated (showing first 500 of $line_count lines)" >> /tmp/review-diff-truncated.patch
+  mv /tmp/review-diff-truncated.patch /tmp/review-diff.patch
+fi
+
+gemini --print "Review this code diff as a senior engineer. Provide:
+- Specific line-by-line feedback
+- Security vulnerabilities with file:line references
+- Performance concerns
+- Code quality issues
+- Missing test coverage
+
+Be thorough and specific. End with APPROVED or CHANGES_REQUESTED.
+
+$(cat /tmp/review-diff.patch)"
+```
+
+**Note:** Each CLI has its own syntax. Check `codex --help` and `gemini --help` for exact flags. The `--print` flag outputs the response without interactive mode.
+
+**Example output:**
+
+```
+Invoking Codex (GPT-5.2) for review...
+┌─────────────────────────────────────────┐
+│ Codex Review Result                     │
+├─────────────────────────────────────────┤
+│ Verdict: APPROVED                       │
+│                                         │
+│ Comments:                               │
+│ - Clean implementation                  │
+│ - Tests cover main paths                │
+│ - No security issues detected           │
+└─────────────────────────────────────────┘
+```
+
+**Consensus Mode:**
+- If multiple providers are configured, ALL must approve
+- Any CHANGES_REQUESTED = overall CHANGES_REQUESTED
+- Issues from all providers are combined in the report
+
+### Step 7: Fix-and-Recheck Loop (RL Mode)
+
+**This is the core innovation. Reviews are not one-shot — they loop until clean.**
+
+After Steps 2-6 complete, if ANY issues were found:
+
+```
+┌─────────────────────────────────────────────┐
+│  REVIEW LOOP (runs until clean)             │
+│                                             │
+│  1. Collect all issues from Claude + Codex  │
+│  2. Fix each issue:                         │
+│     - Missing tests → write them            │
+│     - Security issues → patch the code      │
+│     - Coding standards → refactor           │
+│     - Codex feedback → apply fixes          │
+│  3. Run tests to verify fixes don't break   │
+│  4. Commit fixes                            │
+│  5. Re-run Steps 2-6 (full review again)    │
+│  6. If new issues → loop back to 1          │
+│  7. If clean → exit loop, generate report   │
+└─────────────────────────────────────────────┘
+```
+
+**Iteration rules:**
+
+1. **No arbitrary limit** — keep looping until BOTH providers return APPROVED. The code isn't done until it's clean.
+2. **Each iteration runs the FULL check** — don't skip steps. Fresh eyes each time.
+3. **Re-invoke Codex each iteration** — `codex review --base main` sees the latest fixes
+4. **Commit after each fix round** — `git commit -m "fix: address review feedback (round N)"`
+5. **Track what was fixed** — maintain a running list for the final report
+6. **Stuck detection** — if the SAME issue appears 3 times after being "fixed", stop and escalate to the user with context on what was tried. This is the only exit condition besides clean.
+
+**Fix priority order:**
+1. Security issues (HIGH severity) — fix these first, they block everything
+2. Missing tests — write them before touching implementation
+3. Implementation bugs flagged by Codex — apply fixes
+4. Coding standards (file size, `any` types, return types) — refactor
+5. Style/naming/docs — lowest priority, fix if time permits
+
+**What gets auto-fixed vs flagged for human:**
+
+| Issue Type | Auto-Fix | Human Review |
+|-----------|----------|--------------|
+| Missing test file | Write it | - |
+| Hardcoded secret | Replace with env var | If unclear what var to use |
+| `any` type | Replace with proper interface | If domain type unclear |
+| File >1000 lines | Split into sub-modules | If split strategy unclear |
+| Security vulnerability | Patch it | If fix might break behavior |
+| Missing ownership check | Add guard/check | If ownership model unclear |
+| Secrets in response | Remove or mask fields | If field is needed by client |
+| Direct `process.env` | Move to config module | If config module doesn't exist yet |
+| Unescaped HTML | Add escapeHtml() | If templating engine preferred |
+| Plaintext sensitive data | Add hash step | - |
+| Manual `new Service()` | Convert to DI | If DI container not set up |
+| Codex-flagged bug | Apply suggestion | If suggestion conflicts with Claude |
+| Merge conflict | - | Always human |
+
+**Example iteration:**
+
+```
+───────────────────────────────────────
+Review Round 1/5
+───────────────────────────────────────
+Claude: CHANGES_REQUESTED
+  - Missing test for src/utils.js
+  - Hardcoded API key in src/config.js
+Codex:  CHANGES_REQUESTED
+  - Missing null check in src/parser.js:42
+  - No error handling in src/api.js:88
+
+Fixing 4 issues...
+  ✅ Created src/utils.test.js (3 tests)
+  ✅ Replaced hardcoded key with process.env.API_KEY
+  ✅ Added null check in parser.js:42
+  ✅ Added try/catch in api.js:88
+  ✅ All tests pass
+  ✅ Committed: fix: address review feedback (round 1)
+
+───────────────────────────────────────
+Review Round 2/5
+───────────────────────────────────────
+Claude: CHANGES_REQUESTED
+  - src/utils.test.js missing edge case for empty input
+Codex:  APPROVED
+
+Fixing 1 issue...
+  ✅ Added empty input edge case test
+  ✅ All tests pass
+  ✅ Committed: fix: address review feedback (round 2)
+
+───────────────────────────────────────
+Review Round 3/5
+───────────────────────────────────────
+Claude: APPROVED
+Codex:  APPROVED
+
+✅ All providers agree — exiting loop.
+───────────────────────────────────────
+```
+
+**Stuck detection (only exit besides clean):**
+
+```
+───────────────────────────────────────
+Review Round 7
+───────────────────────────────────────
+Claude: APPROVED
+Codex:  CHANGES_REQUESTED
+  - Complex refactor needed in src/legacy.js  ← appeared 3 times
+
+⚠️ STUCK: This issue has reappeared 3 times after being fixed.
+Escalating to human review.
+
+Attempts made:
+  Round 3: Extracted helper function → Codex still flagged
+  Round 5: Split into two modules → Codex still flagged
+  Round 7: Added interface layer → Codex still flagged
+
+This needs human judgment. Run /tlc:review again after manual fix.
+───────────────────────────────────────
+```
+
+### Step 8: Generate Report
+
+```markdown
+# Code Review Report
+
+**Date:** 2024-01-15T10:30:00Z
+**Base:** main → **Head:** feature/auth
+
+## ✅ Verdict: APPROVED
+
+## Summary
+
+- ✅ All changed files have tests
+- ✅ TDD score: 75%
+- ✅ No security issues detected
+- ✅ All files under 1000 lines
+- ✅ No `any` types
+- ✅ All exports have return types
+
+## Statistics
+
+- Files changed: 8
+- Implementation files: 5
+- Test files: 3
+- Commits: 4
+- TDD Score: 75%
+```
+
+### Step 9: Return Verdict
+
+**APPROVED** - All providers agree after N iterations. Ready to push/merge.
+
+**CHANGES_REQUESTED** - Max iterations reached with remaining issues. Needs human review.
+
+## Example Output
+
+### Passing Review (Multi-Provider)
+
+```
+/tlc:review
+
+Loading router config from .tlc.json...
+  Review providers: claude, codex
+
+Reviewing current branch vs main...
+
+Changed files: 6
+├── src/auth/login.js (impl)
+├── src/auth/login.test.js (test) ✓
+├── src/auth/session.js (impl)
+├── src/auth/session.test.js (test) ✓
+└── README.md (docs)
+
+Test coverage: ✅ All implementation files have tests
+
+Commit analysis:
+├── abc1234 test: add login tests
+├── def5678 feat: implement login
+├── ghi9012 test: add session tests
+└── jkl3456 feat: implement session
+
+TDD Score: 50% ✅
+
+Security scan: ✅ No issues found
+
+───────────────────────────────────────
+Invoking Codex (GPT-5.2) for review...
+───────────────────────────────────────
+Codex verdict: ✅ APPROVED
+  - Clean implementation
+  - Good separation of concerns
+  - Tests are comprehensive
+───────────────────────────────────────
+
+Provider Results:
+  ✅ Claude: APPROVED
+  ✅ Codex:  APPROVED
+
+─────────────────────────────────────────────
+✅ APPROVED - Ready to push (2/2 agree)
+─────────────────────────────────────────────
+```
+
+### Failing Review (Multi-Provider Disagreement)
+
+```
+/tlc:review
+
+Loading router config from .tlc.json...
+  Review providers: claude, codex
+
+Reviewing current branch vs main...
+
+Changed files: 4
+├── src/api/users.js (impl)
+├── src/api/auth.js (impl)
+└── src/utils.js (impl)
+
+Test coverage: ❌ 3 files missing tests
+├── src/api/users.js → needs src/api/users.test.js
+├── src/api/auth.js → needs src/api/auth.test.js
+└── src/utils.js → needs src/utils.test.js
+
+Commit analysis:
+└── abc1234 feat: add all features
+
+TDD Score: 0% ❌ (target: 50%+)
+
+Security scan: ❌ 1 high severity issue
+└── src/api/auth.js: password = "admin123"
+
+───────────────────────────────────────
+Invoking Codex (GPT-5.2) for review...
+───────────────────────────────────────
+Codex verdict: ❌ CHANGES_REQUESTED
+  - Missing input validation in users.js
+  - SQL injection risk in auth.js line 45
+  - No error handling for network failures
+───────────────────────────────────────
+
+Provider Results:
+  ❌ Claude: CHANGES_REQUESTED
+  ❌ Codex:  CHANGES_REQUESTED
+
+Combined Issues:
+  [Claude] Missing tests for 3 files
+  [Claude] Hardcoded password
+  [Codex]  Missing input validation
+  [Codex]  SQL injection risk
+  [Codex]  No error handling
+
+───────────────────────────────────────────
+❌ CHANGES_REQUESTED (0/2 approved)
+
+Action required:
+1. Add tests for 3 implementation files
+2. Fix hardcoded password in src/api/auth.js
+3. Add input validation (Codex)
+4. Fix SQL injection risk (Codex)
+5. Consider splitting into test-first commits
+───────────────────────────────────────────
+```
+
+## Flags
+
+| Flag | Description |
+|------|-------------|
+| `--base <branch>` | Compare against different base (default: main) |
+| `--strict` | Fail on any TDD violation |
+| `--no-security` | Skip security scan |
+| `--providers <list>` | Override providers (e.g., `--providers codex,gemini`) |
+| `--codex-only` | Use only Codex for review |
+| `--no-external` | Skip external providers, use Claude only |
+| `--stuck-threshold <N>` | How many times the same issue reappears before escalating to human (default: 3) |
+| `--no-fix` | Single-pass review only — report issues but don't auto-fix |
+| `--fix-all` | Fix even low-priority style issues (default: skip style) |
+
+## Integration
+
+This review runs automatically:
+- At the end of `/tlc:build` (blocks completion if fails)
+- Before `/tlc:verify` (informational)
+- Can be run manually anytime
+
+## ARGUMENTS
+
+$ARGUMENTS