ctx-cc 4.1.0 → 4.1.1

package/commands/cross-review.md

@@ -0,0 +1,142 @@
+---
+name: ctx:cross-review
+description: On-demand cross-model code review via OpenAI Codex. Works in any project.
+argument-hint: [commit-range] [--focus=area]
+---
+
+<objective>
+Dispatch the current diff to OpenAI Codex (GPT-5.x) via MCP for adversarial cross-model review. Catches bugs Claude's same-model review tends to miss — different training data, different blind spots.
+
+Wraps the `ctx-codex-reviewer` agent with the same skip logic and threadId carryforward used by Stage 3 of the CTX review gate, but invocable on demand from any Claude Code project (not just CTX-managed ones).
+</objective>
+
+<usage>
+```
+/ctx:cross-review                          # review staged + unstaged diff
+/ctx:cross-review HEAD~3..HEAD             # review last 3 commits
+/ctx:cross-review --focus=security         # review with focus area hint
+/ctx:cross-review HEAD~1 --focus=concurrency
+```
+
+Argument parsing (lenient — any order):
+- A git revision range (e.g. `HEAD~3..HEAD`, `main..HEAD`, `<sha1>..<sha2>`) selects what to review. If absent, defaults to `git diff` (working tree).
+- `--focus=<area>` hints Codex to weight specific concerns (security, perf, concurrency, error-handling, contract).
+- Bare positional after a range is treated as commentary appended to the prompt.
+</usage>
+
+<prerequisites>
+This command is a no-op without the Codex MCP. If `mcp__codex__codex` is not registered, the agent will return `VERDICT: SKIP` and tell the user how to set it up:
+
+```bash
+# One-time setup:
+codex login                                       # ChatGPT Plus auth
+claude mcp add codex -- codex mcp-server          # register MCP
+```
+
+Do NOT block the command on missing MCP — surface the SKIP reason and suggest the install commands.
+</prerequisites>
+
+<workflow>
+
+## Step 1: Resolve scope
+
+Parse `$ARGUMENTS`:
+- Extract any token matching `<rev>..<rev>` or `<sha>~N` as the range.
+- Extract `--focus=<area>` as a hint string.
+- Treat remaining text as freeform commentary.
+
+If no range, default: `git diff` (staged + unstaged).
+If range given, the agent will use `git diff <range>`.
+
+## Step 2: Detect CTX context (optional)
+
+```bash
+[ -f .ctx/STATE.json ] && jq -r '.activeStory // "none"' .ctx/STATE.json
+```
+
+If a CTX story is active, include it in the prompt so the agent can pull acceptance criteria from `.ctx/PRD.json`. If not, skip — review still works against raw diff.
+
+## Step 3: Spawn the cross-reviewer agent
+
+```
+Task:
+  subagent_type: "ctx-codex-reviewer"
+  prompt: |
+    On-demand cross-model review (not part of an automated review gate).
+
+    Scope:    {{range or "working tree (staged + unstaged)"}}
+    Focus:    {{--focus value or "general — bugs, security, contracts"}}
+    Story:    {{.activeStory or "n/a — not a CTX project"}}
+    Notes:    {{freeform commentary or empty}}
+
+    Run your standard playbook:
+      1. Gather the diff for the scope above.
+      2. Apply skip short-circuits (docs-only, test-only, <20 LOC).
+      3. Dispatch via mcp__codex__codex.
+      4. Parse verdict.
+
+    Output format (final line MUST be one of):
+      VERDICT: PASS
+      VERDICT: FAIL
+      VERDICT: SKIP
+
+    Append `THREAD: <id>` if a Codex thread was opened.
+  description: "Cross-model review"
+```
+
+## Step 4: Render the verdict to the user
+
+After the agent returns:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ CTX ► CROSS-REVIEW
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+For each verdict:
+
+- `PASS`: green checkmark, "Codex found no issues in {{scope}}."
+- `FAIL`: red X, list the issues by `file:line — description`. Group by severity if Codex provided it.
+- `SKIP`: muted ○, surface the skip reason verbatim. If reason is "MCP unavailable" or "auth expired", include the install commands from `<prerequisites>`.
+
+If the agent emitted `THREAD: <id>`, mention it for follow-ups:
+```
+Follow up with: ask Codex to expand on issue 2 in thread <id>
+```
+
+## Step 5: Optionally persist (CTX projects only)
+
+If `.ctx/` exists, write the result alongside Stage 3 reviews:
+
+```
+.ctx/reviews/cross-review-{{ISO-timestamp}}.json
+{
+  "command": "/ctx:cross-review",
+  "scope": "{{range or working-tree}}",
+  "focus": "{{focus or null}}",
+  "verdict": "PASS|FAIL|SKIP",
+  "issues": [...],
+  "threadId": "..."
+}
+```
+
+If not in a CTX project, just print and exit — no file output.
+
+</workflow>
+
+<guardrails>
+- Never fail on infra problems. Codex MCP missing, auth expired, or rate-limited → SKIP with actionable message, not error.
+- Never call Codex on docs-only, test-only, or sub-20-LOC diffs (the agent enforces this; do not override).
+- Rate-limit aware: the user's ChatGPT Plus quota is shared with everything else they use Codex for. One invocation = one message against the 5h window. Do not retry on transient failures.
+- Read-only sandbox: the agent uses `sandbox: read-only` when calling Codex. Do not pass arguments that would change this.
+</guardrails>
+
+<comparison>
+| When to use what | Tool |
+|---|---|
+| On-demand cross-review of current changes (any project) | `/ctx:cross-review` (this command) |
+| Story-scoped review inside CTX gate (auto, every story) | Stage 3 of `runReviewGate` (no command — fires on its own) |
+| Direct same-model review without Codex | `/ctx:verify` or `/ctx:quick` |
+| Just want to send a single prompt to Codex (not review) | `/codex` (if installed) |
+</comparison>

package/commands/help.md

@@ -115,6 +115,7 @@ Or use commands directly:
 | `/ctx plan [goal]` | Force research + planning |
 | `/ctx verify` | Force three-level verification |
 | `/ctx quick "task"` | Quick task bypass |
+| `/ctx cross-review [range] [--focus=area]` | On-demand Codex cross-model review (any project) |
 
 ### Debug
 | Command | Purpose |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ctx-cc",
-  "version": "4.1.0",
+  "version": "4.1.1",
   "description": "CTX 4.0 — Intelligent workflow orchestration for Claude Code. 26 subagents, 7 skills, deterministic hooks. Phase-based lifecycle with autonomous execution.",
   "keywords": [
     "claude",