codex-review-wrap

Files (13)

• LAUNCHD.md
• SKILL.md
• codex-broker-reaper.plist
• codex-broker-reaper.sh
• appendices.md · references/
• example-flow.md · references/
• step4-run-review.md · references/
• step5-approval-and-rounds.md · references/
• step5-premise-verification.md · references/
• step5-siblings-and-regions.md · references/
• verification-log.md · references/
• fixture-sibling-defect-cross-check.md · tests/
• fixture-step4-no-skill-probe.md · tests/

SKILL.md (first lines)

# codex-review-wrap

## Overview

`/codex:review` selects the working tree based on cwd. When multiple worktrees
are active — the common case mid-session after a merge or context switch — cwd
drifts away from the intended target without warning.

This wrapper intercepts before Codex runs:

1. Lists all active worktrees via `git worktree list`
2. If **≥ 2 worktrees** are active → `AskUserQuestion` forces explicit selection
3. If **exactly 1** → proceeds automatically (same as current `/codex:review` behaviour)
4. Delegates to `/codex:review` with the confirmed worktree as cwd

After Codex returns, a second responsibility activates: every fact-modifying
finding must pass an independent premise check before it becomes an edit, and
the wrapper maintains a session ledger that halts same-session A→B→A flips.
When the PR is a port / parallel hotfix / A/B implementation of logic in a
sibling PR or repo, Step 5d additionally cross-checks each verified finding
against the sibling and records the result. Step 5f tracks how many rounds
have touched each `{file}:{region}` pair and emits a one-time non-blocking
advisory when the count exceeds the configured threshold (default: 4 rounds,
env var `PRAXIS_DIMINISHING_RETURNS_N`). Step 5i then puts every finding
that survived 5b and 5c — fact-modifying, structural, or stylistic — in
front of the user via `AskUserQuestion` before any edit lands: the agent's
verdict is a recommendation, the user's answer is the decision.
See **Step 5** for the full gate.

A third responsibility runs at phase end: **Step 6** reaps openai-codex
app-server brokers that outlived their owning session (a process leak that
spikes `kernel_task` once accumulated RSS crosses the macOS compressor
threshold). See **Step 6** for the reaper and its safety gate.

**Reference map:**

- Step 4 runbook (4a resolve, 4b run + liveness): [`references/step4-run-review.md`](references/step4-run-review.md)
- Step 5 verification gates (5a/5b/5c/5g): [`references/step5-premise-verification.md`](references/step5-premise-verification.md)
- Step 5 cross-checks and counters (5d/5f/5h): [`references/step5-siblings-and-regions.md`](references/step5-siblings-and-regions.md)
- Step 5 decisions and round boundary (5e/5i/5j): [`references/step5-approval-and-rounds.md`](references/step5-approval-and-rounds.md)
- Error-handling table + limitations: [`references/appendices.md`](references/appendices.md)
- Worked end-to-end example: [`references/example-flow.md`](references/example-flow.md)
- Runtime verification log: [`references/verification-log.md`](references/verification-log.md)
- Running under Hermes Agent: [Running under Hermes](#running-under-hermes) below

## Invocation Model

**Cardinality**: This skill handles exactly **one PR per invocation**. For N PRs, invoke the skill N times sequentially. Batch for-loops are **not supported** — they collapse Step 5c per-round ledger emission across multiple PRs and break flip-detection guarantees.

One invocation may still run **N rounds** against that single PR: the axis the batch prohibition guards is PR cardinality, while Step 5j loops on round cardinality, and every one of its iterations passes through an explicit user decision.

## When to Use

- Before calling `/codex:review` from any multi-worktree project
- When the session cwd differs from the worktree you just finished working in

## Inputs

```
/codex-review-wrap
/codex-review-wrap --model opus
```

Optional `--model` is forwarded to `/codex:review` unchanged.

## Process

### Step 1: Enumerate Active Worktrees

```bash
git worktree list --porcelain
```

Parse output into a list of `{path, branch, HEAD, detached}` entries.
Filter out entries with the explicit `bare` marker — they have no working tree.
Keep detached worktrees (no `branch` line but no `bare` marker) as valid review targets.

Expected output shape per entry:
```
worktree /path/to/repo
HEAD <sha>
branch refs/heads/<branch-name>

worktree /path/to/repo-wt/feature-xyz
HEAD <sha>
branch refs/heads/feature-xyz

worktree /path/to/repo-wt/detached-xyz
HEAD <sha>
detached
```

### Step 2: Disambiguation Gate

Evaluate Case A2 first; Cases A and B apply only when no PR is named.

**Case A2 — the review is for a named PR:**

Read the PR's `headRefOid` (`gh pr view <N> --json headRefOid`). If exactly
one worktree's `HEAD` equals it, that worktree is the target: skip the
question and proceed to Step 3. The commit match removes the ambiguity the
question exists for. Ask as in Case B when no worktree or more than one
matches — even when only one worktree exists, since its `HEAD` is then not
the PR's head and reviewing cwd would review unrelated code.

**Case A — exactly 1 non-bare worktree (no named PR):**

Skip selection. Proceed directly to Step 3 using cwd.

**Case B — 2 or more non-bare worktrees:**

Call `AskUserQuestion` with at most **3** worktree options + `"취소"` to
respect the `AskUserQuestion.options` `maxItems: 4` runtime cap (see
`RUNTIME_CONSTRAINTS.md`). When more than 3 worktrees are active, rank
by recency (most recent HEAD commit time first) and surface the top 3;
the runtime's automatic "Other" slot lets the user type any worktree
path not in the list.

```

From devseunggwan/praxis, MIT.

More from devseunggwan/praxis