fp-review (Phase 3 — Sandbox Review)

Spawn HEAVIER in an isolated worktree to run RED/GREEN tests, then post a
structured review comment to the PR. This phase is read-and-comment only —
no commits leave this phase.

The sandbox isolation matters: it prevents a flawed review from dirtying the
working branch, and it forces HEAVIER to reproduce failures from a clean state
rather than relying on local cache.

Setup

STATE=".agents/skills/feature-pipeline/scripts/state.sh"
branch=$($STATE get branch)
pr=$($STATE get prNumber)
phase=$($STATE get phase)

Confirm phase == 4 (set by /fp-implement on completion). If it is not 4,
print a clear message explaining the pipeline order and end your turn — running
out of order will produce a review against incomplete or wrong commits.

HEAVIER brief

Spawn HEAVIER with isolation: worktree on $branch. Give it exactly this
brief (substitute variables):

You are reviewing PR #$pr on branch $branch. Your job is to verify each
changed public surface with RED/GREEN tests, then post a review comment.
Do not push any commits.

1. Read the full diff:

   git diff origin/main...HEAD

2. For each changed public surface (function, CLI flag, schema field):
   a. Write a RED test that FAILS before the fix. Verify this by temporarily
   reverting that change, running the test, then re-applying it.
   b. Write a GREEN test that PASSES with the fix in place.

3. For schema-touching commits, run:

   gaia dev validate

4. For doc-touching commits, run:

   gaia dev docs --check

5. Post this exact comment structure to the PR via gh pr comment:

## Sandbox Review

### RED tests
| Description | Result | Notes |
|-------------|--------|-------|

### GREEN tests
| Description | Result | Notes |
|-------------|--------|-------|

### Issues found
- [ ] <description> — `<file>:<line>`

### Verdict: APPROVE / REQUEST CHANGES

After HEAVIER finishes, capture the comment URL from its output.

Phase completion

$STATE set reviewCommentUrl "<url>"
$STATE set phase 5

Print the M3 stop hook and end your turn:

╔══ STOP HOOK M3 ══════════════════════════════════════════════════════════════╗
║  Sandbox review posted — PR #<N>                                             ║
║  Review the comment, then run /fp-iterate to address findings + watch CI.   ║
╚══════════════════════════════════════════════════════════════════════════════╝

Constraints

• If HEAVIER fails to spawn, write .fp-handover.md with the diff URL and
  branch name so a human can complete the review manually. End your turn — do
  not attempt the review yourself; the sandbox isolation is the point.
• Do not push any commits. This phase is read + comment only.