# Review > Weave code review — run independent adversarial reviews in parallel, then synthesize findings - Skill: `tony/review` (Agent Skill) - Install (CLI): `npx skillmds@latest add tony/review` - Raw SKILL.md: https://api.skillmd.com/api/skills/tony/review/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: tony (https://skillmd.com/u/tony) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tony/review --- # Weave Code Review Run code review through independent adversarial workers in parallel, then synthesize their findings into a unified report with evidence-backed adjudication. Host-native sub-agents are the default; separate model CLIs are optional. This is a **project-read-only** command — no files in your repository are written, edited, or deleted. Session artifacts (worker outputs, prompts, synthesis results) are persisted to `$AI_AIP_ROOT` for post-session inspection; this directory is outside your repository. ## Worker selection Before any other unresolved configuration choice or operational step, read `../../references/worker-backends.md`. Resolve `worker_backend` from `--workers=subagents|model-clis` using that reference; if the flag is absent, ask its worker question first. If interactive choice is unavailable, honor its documented headless default. The selected backend governs the whole session: dispatch, retry, judging, refinement, artifacts, session metadata, and presentation. The shared reference adapts provider-named examples across every later phase to that backend. When `worker_backend == subagents`, use only the reference's native sub-agent path. Skip every model-CLI detection, timeout question, timeout resolution, retry, fallback, and dispatch instruction below. Every such instruction below is conditional on `worker_backend == model-clis`. --- ## Orchestration Plan Before dispatching the review to models, enter plan mode to create a review strategy. **Enter your tool's plan mode:** - **Claude Code**: Call `EnterPlanMode` - **Cursor**: Use `/plan` or press `Shift+Tab` - **Codex**: Use `/plan` to switch to Plan mode - **Gemini**: Use `/plan` or press `Shift+Tab` - **Other tools**: Use your tool's planning/read-only mode if available If plan mode is not available, proceed — context gathering in Phase 1 still guides the review. **Create an orchestration plan covering:** 1. **Branch summary** — What does this branch do? Summarize from commit messages and diff stats 2. **Review focus areas** — Which files/changes are highest risk or most complex? Where should reviewers concentrate? 3. **Relevant conventions** — Which CLAUDE.md/AGENTS.md rules are most relevant to the changes in this branch? 4. **Known concerns** — Any areas the user flagged, or patterns in the diff that look risky (large functions, missing tests, API changes) 5. **Model prompt strategy** — What specific instructions should each model's review prompt emphasize, given the above? **Present the orchestration plan to the user.** Wait for approval before proceeding to Phase 1. The user may adjust focus areas or add concerns. **After approval, exit plan mode:** - **Claude Code**: Call `ExitPlanMode` - **Cursor/Codex/Gemini**: Exit plan mode per your tool's method Then proceed to Phase 1, using the approved strategy to guide context gathering and prompt construction. --- ## Phase 1: Gather Context **Goal**: Understand the branch state and determine the trunk branch. 1. **Determine trunk branch**: ```bash git remote show origin | grep 'HEAD branch' ``` Fall back to `main`, then `master`, if detection fails. 2. **Get the diff stats**: ```bash git diff origin/...HEAD --stat ``` 3. **Get commit history for this branch**: ```bash git log origin/..HEAD --oneline ``` 4. **Read AGENTS.md / CLAUDE.md** if present at the repo root — these contain project conventions the review should enforce. --- ## Phase 1b: Build Context Packet Use the approved orchestration plan to prioritize which conventions, files, and concerns to include in the context packet. If no orchestration plan was created, proceed with default context gathering. After Phase 1 context gathering, assemble a structured context bundle that will be included verbatim in ALL model prompts. This ensures every model works from the same information. Write to `$SESSION_DIR/context-packet.md` *(the actual file write happens after Session Directory Initialization in Phase 2 creates `$SESSION_DIR`)*: 1. **Conventions summary** — key rules from CLAUDE.md/AGENTS.md (max 50 lines). Focus on commit format, test patterns, code style, and quality gates relevant to the task. 2. **Repo state** — branch, HEAD ref, trunk branch, uncommitted changes summary: ```bash git status --short ``` 3. **Changed files** — for review/plan commands that operate on branch changes: ```bash git diff --stat origin/...HEAD ``` 4. **Full diff** — the complete diff output for external CLI models that cannot generate it themselves: ```bash git diff origin/...HEAD ``` 5. **Relevant file list** — files matching task keywords discovered during Phase 1 exploration. Include paths only, not content. 6. **Key snippets** — critical function signatures, types, test patterns, or API contracts relevant to the task (max 200 lines). Prioritize interfaces over implementations. 7. **Known unknowns** — aspects of the task that need discovery during execution. List what the model should investigate. **Size limit**: 400 lines total. Prioritize by task relevance. If the packet exceeds 400 lines, truncate the least relevant sections (snippets first, then file list). **Usage in model prompts**: - For the **Claude Task agent**: reference the file path (`$SESSION_DIR/context-packet.md`) — the agent reads it directly - For **Antigravity and GPT sub-agents**: include the context packet content in the agent prompt, which the sub-agent then passes to the external CLI For `review`, prioritize conventions summary (review should enforce these), changed files (full diff stats), and key snippets of modified code. Known unknowns should note any areas of the diff that are hard to review without more context. --- ## Phase 2: Configuration and Model Detection ### Step 1: Parse Flags Scan `$ARGUMENTS` for explicit flags anywhere in the text. Flags use `--name=value` syntax and are stripped from the prompt text before sending to models. | Flag | Values | Default | Description | |------|--------|---------|-------------| | `--passes=N` | 1–5 | 1 | Number of synthesis passes | | `--timeout=N\|none` | seconds or `none` | command-specific | Timeout for external model commands | | `--mode=fast\|balanced\|deep` | mode preset | `balanced` | Execution mode preset | | `--cascade` | flag | off | Claude-only first review; fan out to external reviewers only when the confidence gate fires (any Critical finding always escalates) | | `--no-deslop` | flag | off | Skip the final deslop pass on the synthesised report | | `--quiet-deslop` | flag | off | Replace the 8-line deslop summary with one line | | `--verbose-deslop` | flag | off | Add tier letter, signature id, confidence per finding | **Mode presets** set default passes and timeout when not explicitly overridden: | Mode | Passes | Timeout multiplier | |------|--------|--------------------| | `fast` | 1 | 0.5× default | | `balanced` | 1 | 1× default | | `deep` | 2 | 1.5× default | **Backward compatibility**: Legacy trigger words are silently recognized as aliases: - `multipass` (case-insensitive) → `--passes=2` - `x` (N = 2–5, regex `\bx([2-5])\b`) → `--passes=N` - `timeout:` → `--timeout=` - `timeout:none` → `--timeout=none` Legacy triggers are scanned on the first and last line only (to avoid false positives in pasted content). Explicit `--` flags take priority over legacy triggers. Values above 5 for `--passes` are capped at 5 with a note to the user. **Config flags** (used in Step 2): - `pass_count` = parsed pass count from `--passes`, mode preset, or legacy trigger. Null if not provided. - `timeout_value` = parsed timeout from `--timeout`, mode preset, or legacy trigger. Null if not provided. ### Step 2: Interactive Configuration **When flags are provided, skip the corresponding question.** When `--passes` is provided, skip the passes question. When `--timeout` is provided, skip the timeout question. If `AskUserQuestion` is unavailable (headless mode via `claude -p`), use `pass_count` value if set, otherwise default to 1 pass. Timeout uses `timeout_value` if set, otherwise the command's default timeout. Use `AskUserQuestion` to prompt the user for any unresolved settings: **Question 1 — Passes** (skipped when `--passes` was provided): - question: "How many synthesis passes? Multi-pass re-attacks unresolved residuals from the prior pass." - header: "Passes" - When `pass_count` exists (from mode preset or legacy trigger), move the matching option first with "(Recommended)" suffix. Other options follow in ascending order. - When `pass_count` is null, use default ordering: - "1 — single pass (Recommended)" — Run models once and synthesize. Sufficient for most tasks. - "2 — multipass" — One refinement round. Models re-attack only the prior pass's unresolved residuals. - "3 — triple pass" — Two refinement rounds. Maximum depth, highest token usage. **Question 2 — Timeout** (skipped when `--timeout` was provided): - question: "Timeout for external model commands?" - header: "Timeout" - options: - "Default (900s)" — Use this command's built-in default timeout. - "Quick — 450s" — For fast queries (0.5× default). May timeout on complex tasks. - "Long — 1350s" — For complex tasks (1.5× default). Higher wait on failures. - "None" — No timeout. Wait indefinitely for each model. ### Step 3: Detect Available Models **Goal**: Check which AI CLI tools are installed locally. Run these checks in parallel: ```bash command -v agy >/dev/null 2>&1 && echo "agy:available" || echo "agy:missing" ``` ```bash command -v gemini >/dev/null 2>&1 && echo "gemini:available" || echo "gemini:missing" ``` ```bash command -v codex >/dev/null 2>&1 && echo "codex:available" || echo "codex:missing" ``` ```bash command -v agent >/dev/null 2>&1 && echo "agent:available" || echo "agent:missing" ``` #### Model resolution (priority order) | Slot | Priority 1 (native) | Native model | Fallback chain | Agent model | |------|---------------------|--------------|----------------|----------- | | **Claude** | Always available (this agent) | — | — | — | | **Antigravity** | `agy` binary | `Gemini 3.1 Pro (High)` | `gemini -m gemini-3-pro-preview` → `agent --model gemini-3.1-pro` | `gemini-3.1-pro` | | **GPT** | `codex` binary | (default) | `agent --model gpt-5.4-high` | `gpt-5.4-high` | **Resolution logic** for each external slot: 1. Native CLI found → use it 2. Else next CLI in the fallback chain → use it (`agent` slots use the `--model` flag) 3. Else → slot unavailable, note in report The **Antigravity** slot is Google's lane: `agy` (Antigravity) supersedes the standalone `gemini` CLI, which Google retires on 2026-06-18. `agy` has no native read-only mode, so read-only commands isolate it in a disposable git worktree (Repo Guard Layer 1; see `docs/repo-guard-protocol.md`). Report which models will participate and which backend each uses. ### Step 4: Detect Timeout Command ```bash command -v timeout >/dev/null 2>&1 && echo "timeout:available" || { command -v gtimeout >/dev/null 2>&1 && echo "gtimeout:available" || echo "timeout:none"; } ``` On Linux, `timeout` is available by default. On macOS, `gtimeout` is available via GNU coreutils. If neither is found, run external commands without a timeout prefix — time limits will not be enforced. Do not install packages automatically. Store the resolved timeout command (`timeout`, `gtimeout`, or empty) for use in all subsequent CLI invocations. When constructing bash commands, replace `` with the resolved command and `` with the resolved value (from trigger parsing, interactive config, or the command's default). If no timeout command is available, omit the prefix entirely. When `--timeout=none` is configured (via flag or interactive selection), also omit `` and `` entirely — run external commands without any timeout prefix. ### Session Directory Initialization #### Step 1: Resolve storage root ```bash if [ -n "$AI_AIP_ROOT" ]; then AIP_ROOT="$AI_AIP_ROOT" elif [ -n "$XDG_STATE_HOME" ]; then AIP_ROOT="$XDG_STATE_HOME/ai-aip" elif [ "$(uname -s)" = "Darwin" ]; then AIP_ROOT="$HOME/Library/Application Support/ai-aip" else AIP_ROOT="$HOME/.local/state/ai-aip" fi ``` Create a `/tmp/ai-aip` symlink to the resolved root for backward compatibility (if `/tmp/ai-aip` doesn't already exist or isn't already correct): ```bash ln -sfn "$AIP_ROOT" /tmp/ai-aip 2>/dev/null || true ``` #### Step 2: Compute repo identity ```bash REPO_TOPLEVEL="$(git rev-parse --show-toplevel)" ``` ```bash REPO_SLUG="$(basename "$REPO_TOPLEVEL" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9._-]/-/g')" ``` ```bash REPO_ORIGIN="$(git remote get-url origin 2>/dev/null || true)" ``` ```bash if [ -n "$REPO_ORIGIN" ]; then REPO_KEY="${REPO_ORIGIN}|${REPO_SLUG}" else REPO_KEY="$REPO_TOPLEVEL" fi ``` ```bash if command -v sha256sum >/dev/null 2>&1; then REPO_ID="$(printf '%s' "$REPO_KEY" | sha256sum | cut -c1-12)" else REPO_ID="$(printf '%s' "$REPO_KEY" | shasum -a 256 | cut -c1-12)" fi ``` ```bash REPO_DIR="${REPO_SLUG}--${REPO_ID}" ``` #### Step 3: Generate session ID ```bash SESSION_ID="$(date -u '+%Y%m%d-%H%M%SZ')-$$-$(head -c2 /dev/urandom | od -An -tx1 | tr -d ' ')" ``` #### Step 4: Create session directory ```bash SESSION_DIR="$AIP_ROOT/repos/$REPO_DIR/sessions/review/$SESSION_ID" ``` Create the session directory tree: ```bash mkdir -p -m 700 "$SESSION_DIR/pass-0001/outputs" "$SESSION_DIR/pass-0001/stderr" ``` #### Step 5: Write `repo.json` (if missing) If `$AIP_ROOT/repos/$REPO_DIR/repo.json` does not exist, write it with these contents: ```json { "schema_version": 1, "slug": "", "id": "", "toplevel": "", "origin": "" } ``` #### Step 6: Write `session.json` (atomic replace) Write to `$SESSION_DIR/session.json.tmp`, then `mv session.json.tmp session.json`: ```json { "schema_version": 1, "session_id": "", "command": "review", "status": "in_progress", "branch": "", "ref": "", "worker_backend": "", "participants": ["", "..."], "executors": {"": ""}, "completed_passes": 0, "prompt_summary": "", "created_at": "", "updated_at": "" } ``` When `worker_backend == model-clis`, add a `"models"` array containing the resolved model for each participant. Omit `"models"` when `worker_backend == subagents`. #### Step 7: Append `events.jsonl` Append one event line to `$SESSION_DIR/events.jsonl`: ```json {"event":"session_start","timestamp":"","command":"review","worker_backend":"","participants":["","..."]} ``` #### Step 8: Write `metadata.md` Write to `$SESSION_DIR/metadata.md` containing: - Command name, start time, configured pass count - Worker backend, participant artifact IDs, and executor mapping - Resolved models only for `model-clis`, timeout setting when applicable - Git branch (`git branch --show-current`), commit ref (`git rev-parse --short HEAD`) Store `$SESSION_DIR` for use in all subsequent phases. #### Step 8b: Repo Guard — Capture Fingerprint Capture the repository state before any model runs. See `docs/repo-guard-protocol.md` Layer 2 for the full protocol. ```bash REPO_TOPLEVEL="$(git rev-parse --show-toplevel)" ``` ```bash REPO_HEAD="$(git -C "$REPO_TOPLEVEL" rev-parse HEAD)" ``` ```bash REPO_FINGERPRINT="$(git -C "$REPO_TOPLEVEL" status --porcelain)" ``` Write `$SESSION_DIR/repo-fingerprint.txt` containing the HEAD ref and status output. Store `$REPO_TOPLEVEL` for use in all subsequent phases. #### Step 9: Write Context Packet Write the Context Packet built in Phase 1b to `$SESSION_DIR/context-packet.md`. --- ## Phase 2b: Cascade Gate (only when `--cascade` was set) Read `../../references/ensemble-techniques.md` (Technique 1) and apply it: run the Claude Review lane from Phase 3 alone, self-verify per Phase 4's Verify Claims step, and evaluate the five escalation triggers — for review, any **Critical** finding fires the judgment-call trigger, so Criticals always get ensemble confirmation. On **early-exit**, skip the external lanes, blind judging, and rubric scoring; run the Critic and deslop steps, then present with `CASCADE_STATE` = `early-exit`. On **escalate** (or user escalation from the panel), continue to Phase 3 with the cheap-pass output reused as the Claude lane. Without `--cascade`, skip this phase. --- ## Phase 3: Launch Reviews in Parallel **Goal**: Run all available reviewers simultaneously. ### Prompt Preparation Each model receives a distinct evaluation lens to decorrelate outputs and reduce shared blind spots. The same context packet is included for all models, but a different role preamble is prepended to each prompt. | Slot | Role | Bias | Preamble | |------|------|------|----------| | Claude | **Maintainer** | Conservative, convention-enforcing, minimal-change | "You are the Maintainer. Prioritize correctness, convention adherence, and minimal scope. Challenge any change that isn't strictly necessary. Enforce all project conventions from CLAUDE.md/AGENTS.md." | | Antigravity | **Skeptic** | Challenge assumptions, find edge cases, question necessity | "You are the Skeptic. Challenge every assumption. Find edge cases, failure modes, and unstated requirements. Question whether the proposed approach is even the right one. Prioritize what could go wrong." | | GPT | **Builder** | Pragmatic, shippable, favor simplicity over abstraction | "You are the Builder. Prioritize practical, shippable solutions. Favor simplicity over abstraction. Focus on what gets the job done with the least complexity. Call out over-engineering." | Role preambles are prepended before the task-specific prompt and context packet. The role does not change the task — it changes the lens through which the model approaches it. Include the context packet from Phase 1b. Write the prompt content to `$SESSION_DIR/pass-0001/prompt.md` using the Write tool. ### Claude Review (Task agent) Launch a Task agent with `subagent_type: "general-purpose"` to perform Claude's own code review: **Prompt for the Claude review agent**: > CRITICAL: Do NOT write, edit, create, or delete any files in the repository. Do NOT use Write, Edit, or Bash commands that modify repository files. All session artifacts are written to `$SESSION_DIR`, which is outside the repository. This is a READ-ONLY research task. > > Perform a thorough code review of the changes on this branch compared to origin/. > > Run `git diff origin/...HEAD` to see all changes. > Read the CLAUDE.md or AGENTS.md file at the repo root for project conventions. > > Review for: > 1. **Bugs and logic errors** — incorrect behavior, edge cases, off-by-one errors > 2. **Security issues** — injection, XSS, unsafe deserialization, secrets in code > 3. **Project convention violations** — check against CLAUDE.md/AGENTS.md > 4. **Code quality** — duplication, unclear naming, missing error handling > 5. **Test coverage gaps** — new code paths without tests > > For each issue found, report: > - **Severity**: Critical / Important / Suggestion > - **File and line**: exact location > - **Description**: what the issue is > - **Recommendation**: how to fix it > > Assign a confidence score (0-100) to each issue. Only report issues with confidence >= 70. ### Antigravity Review (sub-agent) Launch a Task agent (`subagent_type: "general-purpose"`, `mode: "default"`) to execute the Antigravity (agy) model. Include in the agent prompt: the resolved backend command and timeout from Phase 2, the `$SESSION_DIR` path, the `$REPO_TOPLEVEL` path and `$REPO_FINGERPRINT` value for repo guard verification, the pass number, and the review focus with additional instructions: > > > --- > Additional instructions: Run git diff origin/...HEAD to see the changes. Read AGENTS.md or CLAUDE.md for project conventions. For each issue, report: severity (Critical/Important/Suggestion), file and line, description, and recommendation. Focus on bugs, logic errors, security issues, and convention violations. > CRITICAL: Do NOT write, edit, create, or delete any files. Do NOT use any file-writing or file-modification tools. This is a READ-ONLY research task. All output must go to stdout. Any file modifications will be automatically detected and reverted. The agent must: 1. Read the prompt from `$SESSION_DIR/pass-0001/prompt.md` 2. Run the resolved Antigravity command with output redirection. **Repo Guard**: `agy` has no native read-only mode (its print mode reads *and* writes), so isolate it in a disposable git worktree checked out at `HEAD` — agy reads the snapshot while any stray write lands in the throwaway worktree, never the main repo (see `docs/repo-guard-protocol.md` Layer 1). The `gemini` and `agent` fallbacks keep their own native read-only modes. **Primary (`agy` CLI, disposable worktree)**: ```bash (AGY_RO_WT="${REPO_TOPLEVEL}-weave-agy-ro"; git -C "$REPO_TOPLEVEL" worktree remove --force "$AGY_RO_WT" 2>/dev/null; git -C "$REPO_TOPLEVEL" worktree add -q --detach "$AGY_RO_WT" HEAD && (cd "$AGY_RO_WT" && agy --model "Gemini 3.1 Pro (High)" --add-dir "$AGY_RO_WT" --dangerously-skip-permissions -p "$(cat "$SESSION_DIR/pass-0001/prompt.md")" "$SESSION_DIR/pass-0001/outputs/agy.md" 2>"$SESSION_DIR/pass-0001/stderr/agy.txt"); rc=$?; git -C "$REPO_TOPLEVEL" worktree remove --force "$AGY_RO_WT" 2>/dev/null; exit "$rc") ``` **Fallback (`gemini` CLI)**: ```bash (cd "$SESSION_DIR" && gemini -m gemini-3-pro-preview --approval-mode plan --include-directories "$REPO_TOPLEVEL" --skip-trust -p "$(cat "$SESSION_DIR/pass-0001/prompt.md")" >"$SESSION_DIR/pass-0001/outputs/agy.md" 2>"$SESSION_DIR/pass-0001/stderr/agy.txt") ``` **Fallback (`agent` CLI)**: ```bash (cd "$SESSION_DIR" && agent -p --mode plan --trust --workspace "$REPO_TOPLEVEL" --model gemini-3.1-pro "$(cat "$SESSION_DIR/pass-0001/prompt.md")" >"$SESSION_DIR/pass-0001/outputs/agy.md" 2>>"$SESSION_DIR/pass-0001/stderr/agy.txt") ``` 3. **Repo Guard**: After the CLI returns, verify the repository is unchanged (see `docs/repo-guard-protocol.md` Layer 3): ```bash CURRENT_STATUS="$(git -C "$REPO_TOPLEVEL" status --porcelain)" ``` ```bash if [ "$CURRENT_STATUS" != "$REPO_FINGERPRINT" ]; then echo "REPO GUARD VIOLATION: agy modified repository files" >&2 git -C "$REPO_TOPLEVEL" checkout -- . 2>/dev/null git -C "$REPO_TOPLEVEL" clean -fd 2>/dev/null printf '{"event":"repo_guard_violation","timestamp":"%s","model":"agy","reverted":true}\n' "$(date -u '+%Y-%m-%dT%H:%M:%SZ')" >>"$SESSION_DIR/guard-events.jsonl" fi ``` 4. On failure: classify (timeout → retry with 1.5× timeout; rate-limit → retry after 10s; credit-exhausted → skip retry, escalate to the next backend immediately; crash → not retryable; empty → retry once), retry max once with same backend, then fall back down the chain (agy → gemini → agent) if a native CLI was used; if all are credit-exhausted or unavailable, use the lesser model (`Gemini 3.5 Flash (High)` via agy for Antigravity; gpt-5.4-mini via agent for GPT) 5. Return: exit code, elapsed time, retry count, output file path ### GPT Review (sub-agent) Launch a Task agent (`subagent_type: "general-purpose"`, `mode: "default"`) to execute the GPT model. Include in the agent prompt: the resolved backend command and timeout from Phase 2, the `$SESSION_DIR` path, the `$REPO_TOPLEVEL` path and `$REPO_FINGERPRINT` value for repo guard verification, the pass number, and the review focus with additional instructions: > > > --- > Additional instructions: Run git diff origin/...HEAD to see the changes. Read AGENTS.md or CLAUDE.md for project conventions. For each issue, report: severity (Critical/Important/Suggestion), file and line, description, and recommendation. Focus on bugs, logic errors, security issues, and convention violations. > CRITICAL: Do NOT write, edit, create, or delete any files. Do NOT use any file-writing or file-modification tools. This is a READ-ONLY research task. All output must go to stdout. Any file modifications will be automatically detected and reverted. The agent must: 1. Read the prompt from `$SESSION_DIR/pass-0001/prompt.md` 2. Run the resolved GPT command with output redirection. **Repo Guard**: invoke the CLI in its native read-only sandbox — it reads the repo but cannot write it (see `docs/repo-guard-protocol.md` Layer 1): **Native (`codex` CLI)**: ```bash (cd "$SESSION_DIR" && codex exec -s read-only -C "$REPO_TOPLEVEL" --skip-git-repo-check "$SESSION_DIR/pass-0001/outputs/gpt.md" 2>"$SESSION_DIR/pass-0001/stderr/gpt.txt") ``` **Fallback (`agent` CLI)**: ```bash (cd "$SESSION_DIR" && agent -p --mode plan --trust --workspace "$REPO_TOPLEVEL" --model gpt-5.4-high "$(cat "$SESSION_DIR/pass-0001/prompt.md")" >"$SESSION_DIR/pass-0001/outputs/gpt.md" 2>>"$SESSION_DIR/pass-0001/stderr/gpt.txt") ``` 3. **Repo Guard**: After the CLI returns, verify the repository is unchanged (see `docs/repo-guard-protocol.md` Layer 3): ```bash CURRENT_STATUS="$(git -C "$REPO_TOPLEVEL" status --porcelain)" ``` ```bash if [ "$CURRENT_STATUS" != "$REPO_FINGERPRINT" ]; then echo "REPO GUARD VIOLATION: gpt modified repository files" >&2 git -C "$REPO_TOPLEVEL" checkout -- . 2>/dev/null git -C "$REPO_TOPLEVEL" clean -fd 2>/dev/null printf '{"event":"repo_guard_violation","timestamp":"%s","model":"gpt","reverted":true}\n' "$(date -u '+%Y-%m-%dT%H:%M:%SZ')" >>"$SESSION_DIR/guard-events.jsonl" fi ``` 4. On failure: classify (timeout → retry with 1.5× timeout; rate-limit → retry after 10s; credit-exhausted → skip retry, escalate to agent CLI immediately; crash → not retryable; empty → retry once), retry max once with same backend, then fall back to agent CLI if native was used; if agent is also credit-exhausted or unavailable, use lesser model (`Gemini 3.5 Flash (High)` via agy for Antigravity; gpt-5.4-mini via agent for GPT) 5. Return: exit code, elapsed time, retry count, output file path ### Artifact Capture After each model completes, persist its output to the session directory: - **Claude**: Write the Task agent's response to `$SESSION_DIR/pass-0001/outputs/claude.md` - **Antigravity**: Written by the Antigravity sub-agent to `$SESSION_DIR/pass-0001/outputs/agy.md` - **GPT**: Written by the GPT sub-agent to `$SESSION_DIR/pass-0001/outputs/gpt.md` ### Execution Strategy - Launch all model agents in the same turn to execute simultaneously. If parallel dispatch is unavailable, launch sequentially — the synthesis phase handles partial results. - Each sub-agent handles its own retry and fallback protocol internally (see steps 3-4 in each agent's instructions above). - After all agents return, verify output files exist in `$SESSION_DIR/pass-NNNN/outputs/`. - If a sub-agent reports failure after exhausting retries, mark that model as unavailable for this pass and include failure details in the report. - Never block the entire workflow on a single model failure. --- ## Phase 4: Synthesize Findings **Goal**: Combine all reviewer outputs into a unified, evidence-verified report. ### Blind Judging Protocol Before synthesis, strip model identity from responses to prevent brand bias during evaluation. **Step 1: Randomize Labels** Assign random labels (Response A, Response B, Response C) to the model outputs. Use a random permutation — do not always assign Claude to A. Record the mapping in `$SESSION_DIR/pass-NNNN/label-map.json`: ```json { "A": "", "B": "", "C": "" } ``` **Step 2: Evaluate Blindly** During scoring and adjudication (see Synthesis Protocol), refer to responses only by their labels (A/B/C). Do not consider which model produced which output. **Step 3: Reveal After Scoring** After all scoring and adjudication is complete, reveal the model identities in the attribution section of the final report. Include the label mapping so the user can trace which model produced which response. **Limitation**: Claude is both participant and judge. True blindness is impossible for Claude's own output — it may recognize its own writing style. The blind labeling primarily prevents bias when evaluating external model outputs against each other. ### Synthesis Protocol After collecting model outputs and applying blind labels, follow this evidence-backed synthesis protocol. **Step 1: Verify Claims** For each blinded response (A/B/C), check factual claims against the codebase: - **File references**: Use `Glob` and `Read` to confirm referenced files exist - **Function/API references**: Read the file and verify function signatures, class names, and API contracts match what the response claims - **Convention claims**: Check against CLAUDE.md/AGENTS.md — does the response correctly apply project rules? - **Classify each claim**: `verified` (confirmed by reading code), `plausible-unverified` (reasonable but not checked), or `false` (contradicted by code) Write the verification results to `$SESSION_DIR/pass-NNNN/verification.md`. **Step 2: Score with Rubric** Rate each blinded response 0–10 per dimension using the Review Rubric: #### Review Rubric | Dimension | Weight | Description | |-----------|--------|-------------| | Correctness | 3× | Real bugs found, no false positives | | Specificity | 2× | Exact file/line, reproducible issue | | Severity calibration | 2× | Critical is truly critical, not inflated | | Actionability | 1× | Clear fix recommendations | | Convention coverage | 1× | Checks project-specific rules from CLAUDE.md | Compute a weighted total for each response. Write scores to `$SESSION_DIR/pass-NNNN/scores.md` in a table showing per-dimension scores and weighted totals for each label (A/B/C). **Step 3: Adjudicate Conflicts** Compare responses to identify: - **Agreement points** — all responses concur on these → accept as foundation - **Conflicts** — responses disagree → verify against the codebase, accept the one supported by evidence - **Unresolvable conflicts** — cannot determine which is correct from code alone → note both positions with available evidence **Step 4: Converge (Merge)** Build the final result using merge convergence: combine agreed points as foundation, apply adjudicated conflict resolutions, incorporate best unique contributions ordered by score, strip unverified claims. **Step 5: Critic** Launch an independent Task agent (`subagent_type: "general-purpose"`) to challenge the synthesized result: > Review the following synthesis for errors. Your job is to BREAK it — find problems, not confirm it's good. > > Find: (1) remaining factual errors — file/function references that don't exist, (2) logical inconsistencies — steps that contradict each other, (3) missing edge cases — failure modes not addressed, (4) convention violations — rules from CLAUDE.md/AGENTS.md not followed. > > Emit ONLY deltas: each issue found and its specific fix. Do not rewrite the entire synthesis. Write the critic's findings to `$SESSION_DIR/pass-NNNN/critic.md`. Incorporate valid findings into the final output — verify each critic finding against the codebase before accepting it. ### Verification for Review Findings In Step 1 (Verify Claims) of the synthesis protocol, apply review-specific verification: - For each reported bug or issue, **read the file and line** to confirm the issue exists - For severity claims, verify the actual impact — is a "Critical" truly exploitable or crash-worthy? - For convention violations, check the specific rule in CLAUDE.md/AGENTS.md ### Cross-Reference and Deduplicate After verification, group findings that refer to the same issue (same file, similar description). For each unique issue: - **Consensus count**: how many reviewers flagged it (1, 2, or 3) - **Consensus boost**: Issues flagged by multiple reviewers get higher confidence - 1 reviewer: use reported severity as-is - 2 reviewers: promote severity by one level (Suggestion → Important, Important → Critical) - 3 reviewers: mark as Critical regardless Record the per-finding consensus map to `$SESSION_DIR/pass-NNNN/consensus.md`: classify each lane per finding as **agree**, **dissent** (incompatible position, including "not an issue"), or **silent**; over M lanes the levels are unanimous (M/M), majority (> M/2, someone dissents or is silent), split (no position > M/2), and single (one agree, rest silent). Dissent and silence are not the same — a single uncontested finding outranks a split one. On cascade-escalated runs, findings restating a fired trigger count external lanes only. In the report, every finding carries its consensus tag (`consensus 2/3`, `consensus 1/3 (uncontested)`), findings within a severity band are ordered unanimous-verified, majority-verified, single-verified, then unverified, and split findings that verification could not settle MUST appear under Reviewer Disagreements with both positions — never dropped. ### Deslop Pass (final pass only) This step runs only when the current pass is the final pass — for `pass_count == 1`, that is this pass; for `pass_count >= 2`, it runs at the end of Phase 5's last iteration. Skip if `--no-deslop` was set. 1. Write the synthesised report to `$SESSION_DIR/pass-NNNN/synthesis.md` *now*, before rendering the Present template. 2. Read `../../references/deslop-pass.md` and apply it with `ARTIFACT_PATH=$SESSION_DIR/pass-NNNN/synthesis.md`, `SESSION_DIR`, the captured `BASELINE_SHA`, and `DESLOP_MODE` from the flag. 3. Re-read `synthesis.md`. Render the Present template using the desloped report. The deslop summary block appears after the Attribution section. ### Present the report Read `../../references/present-results.md` and apply it with: - `RESULT_KIND` = `review` - `ARTIFACT_PATH` = `$SESSION_DIR/pass-NNNN/synthesis.md` - `SESSION_DIR` = `$SESSION_DIR` - `PASS_COUNT` = the resolved pass count - `IN_PLAN_MODE` = false - `WORKER_BACKEND` = `worker_backend` - `PARTICIPANTS` = the successful participant artifact IDs - `EXECUTORS` = the resolved participant artifact ID to executor mapping - `MODELS` = resolved models when `worker_backend == model-clis`; otherwise null - `LABEL_MAP_PATH` = `$SESSION_DIR/pass-NNNN/label-map.json` - `CASCADE_STATE` = `early-exit`, `escalated`, or null when `--cascade` was not set After the reference returns, finalize the session per the existing session finalization block. After presenting the report, persist the synthesis: - The synthesised report was already written to `$SESSION_DIR/pass-0001/synthesis.md` by the Deslop Pass step. When `--no-deslop` was set, write it now as a fallback. - Update `session.json` via atomic replace: set `completed_passes` to `1`, `updated_at` to now. Append a `pass_complete` event to `events.jsonl`. --- ## Phase 5: Multi-Pass Refinement If `pass_count` is 1, skip this phase. For pass N ≥ 2, do NOT re-run the entire task. Passes are **residual re-attacks** per `../../references/ensemble-techniques.md` (Technique 2): extract `$SESSION_DIR/pass-/residuals.md` from the prior pass's unresolved conflicts, failed verification, unincorporated critic findings, and split-consensus items. An empty ledger means convergence — stop early and report it. After collecting targeted responses: - Merge resolutions back into the prior synthesis at the quoted regions; untouched findings carry forward verbatim - Re-score only affected dimensions (not the full rubric); re-adjudicate only the ledger items - **Early-stop**: If no material delta between this pass and the prior pass (no scores changed by more than 1, no new conflicts identified), stop refinement early and report convergence Follow the same retry protocol and artifact capture as the initial pass. For each pass from 2 to `pass_count`: 1. **Create the pass directory**: ```bash mkdir -p -m 700 "$SESSION_DIR/pass-$(printf '%04d' $N)/outputs" "$SESSION_DIR/pass-$(printf '%04d' $N)/stderr" ``` 2. **Construct the residual re-attack prompt** from the ledger — entries only, each with at most 10 lines of surrounding synthesis excerpt, never the full prior synthesis. For Claude, reference prior artifacts by path; for external models, inline them. 3. **Write the refinement prompt** to `$SESSION_DIR/pass-{N}/prompt.md` and re-run all available reviewers in parallel (same backends, same timeouts, same retry logic as Phase 3). 4. **Capture outputs** to `$SESSION_DIR/pass-{N}/outputs/.md`. 5. **Re-synthesize** by merge-back (Technique 2). Write to `$SESSION_DIR/pass-{N}/synthesis.md`. 6. **Final-pass deslop**: when this is the final pass (last iteration of the loop, or convergence), run Phase 4's Deslop Pass step on `$SESSION_DIR/pass-{N}/synthesis.md` before presenting. Gated on `--no-deslop` exactly as in Phase 4. 6. **Early-stop** if no material delta from prior pass. **Update session**: set `completed_passes` to N in `session.json`, append `pass_complete` to `events.jsonl`. Present the final-pass synthesis, adding a **Confidence Evolution** table: ```markdown ## Confidence Evolution | Finding | Pass 1 | Pass 2 | Pass 3 | Status | |---------|--------|--------|--------|--------| | file:42 null check | 2/3 reviewers | 3/3 reviewers | — | Confirmed | | file:15 type error | 1/3 reviewers | 0/3 reviewers | — | Retracted | | file:99 race condition | — | 2/3 reviewers | 3/3 reviewers | New (confirmed) | ``` --- ## Phase 6: Recommendations After presenting the report: 1. **Prioritize consensus issues** — these have the highest confidence since multiple independent models agree 2. **Flag reviewer disagreements** — where one model says it's fine and another says it's a bug, note both perspectives for the user to decide 3. **Suggest next steps**: - Fix critical consensus issues first - Address single-reviewer critical issues - Consider important issues - Optionally address suggestions --- ## Rules - Never modify project code — this is project-read-only review. Session artifacts are written to `$AI_AIP_ROOT`, which is outside the repository. The Repo Guard Protocol (`docs/repo-guard-protocol.md`) enforces this: external CLIs run in their native read-only sandbox (Layer 1) — they can read the repo but not write it — post-CLI verification reverts any write that bypasses the sandbox, and session-end verification catches anything else. - Always attempt to run all available reviewers, even if one fails - Always clearly attribute which reviewer(s) found each issue - Consensus issues take priority over single-reviewer issues - If no external reviewers are available, fall back to Claude-only review and note the limitation - Use ` ` for external CLI commands, resolved from Phase 2 Step 4. If no timeout command is available, omit the prefix entirely. Adjust higher or lower based on observed completion times. - Capture stderr from external tools (via `$SESSION_DIR/pass-{N}/stderr/.txt`) to report failures clearly - If an exter …(truncated)