@cluesmith/codev 3.0.5 → 3.0.6

package/skeleton/protocols/pir/prompts/review.md

@@ -0,0 +1,261 @@
+# REVIEW Phase Prompt
+
+You are executing the **REVIEW** phase of the PIR protocol.
+
+## Your Goal
+
+Write a retrospective at `codev/reviews/{{artifact_name}}.md` including **Summary**, **Architecture Updates**, and **Lessons Learned Updates** sections. Push, open a PR using the review file as the PR body, record the PR with porch, then signal completion — **porch runs CMAP-2 (Gemini + Codex) once** via the verify block. CMAP is a *single advisory pass* (`max_iterations: 1`): its verdicts are surfaced to the human at the `pr` gate, **not** an iterate-until-APPROVE loop. After the single pass the `pr` gate fires regardless of verdict; you notify the architect (leading with any REQUEST_CHANGES) and wait at the gate while the human merges on GitHub.
+
+The retrospective ships with the merged PR — it's durable team knowledge, searchable in `codev/reviews/` on `main`.
+
+## Context
+
+- **Project ID**: {{project_id}}
+- **Issue Number**: #{{issue.number}}
+- **Plan File**: `codev/plans/{{artifact_name}}.md`
+- **Review File**: `codev/reviews/{{artifact_name}}.md` (you will write this)
+
+## Prerequisites
+
+- The `dev-approval` gate has been approved (you're here because `porch next` advanced you)
+- Your branch contains the implementation commits
+- Build and tests pass
+
+## Process
+
+### 1. Write the Review File
+
+Create `codev/reviews/{{artifact_name}}.md` with these sections:
+
+```markdown
+# PIR Review: <Short Title>
+
+Fixes #{{issue.number}}
+
+## Summary
+
+2–3 sentence overview of what was implemented and why. The reader is someone scanning `codev/reviews/` six months from now trying to understand what this PR did.
+
+## Files Changed
+
+Output of `git diff --stat main`, formatted as a list:
+
+- `path/to/file.ts` (+12 / -3)
+- `path/to/new-file.ts` (+45 / -0)
+
+## Commits
+
+Output of `git log main..HEAD --oneline`:
+
+- `<sha>` [PIR #{{issue.number}}] First change
+- `<sha>` [PIR #{{issue.number}}] Second change
+
+## Test Results
+
+- `npm run build`: ✓ pass
+- `npm test`: ✓ pass (X tests, Y new)
+- Manual verification: <what was verified, on what platforms — pulled from the human's review at the dev-approval gate if known>
+
+## Architecture Updates
+
+What changed in `codev/resources/arch.md` (or why no changes were needed). If this PR introduced or modified an architectural pattern, document it here AND update `arch.md` in this same commit. If no architectural updates are needed (typical for small fixes), write a single line explaining why: "No arch changes — this PR fixes a typo without affecting module boundaries."
+
+Use the `update-arch-docs` skill if available (`.claude/skills/update-arch-docs/SKILL.md`) — it encodes the discipline for what NOT to include in arch docs.
+
+## Lessons Learned Updates
+
+What durable engineering wisdom emerged from this PR (or why no lessons were captured). Same pattern as Architecture Updates: if something is worth recording in `codev/resources/lessons-learned.md`, update both files in this commit. If not, explain why: "No lessons captured — change was mechanical."
+
+## Things to Look At During PR Review
+
+Tricky spots the PR reviewer should focus on. Honest — if a section was hard to get right, flag it.
+
+## How to Test Locally
+
+For reviewers pulling the branch:
+
+- **View diff**: VSCode sidebar → right-click builder pir-{{project_id}} → **Review Diff** (auto-detects the repo's default branch)
+- **Run dev server**: VSCode sidebar → **Run Dev Server**, or `afx dev pir-{{project_id}}`
+- **What to verify**: <bullet list mapped to the plan's Test Plan>
+
+## Flaky Tests (if any)
+
+List any tests you skipped due to pre-existing flakiness, with file:line refs and a one-line rationale each. Omit this section if none.
+```
+
+### 2. Update Architecture / Lessons Docs (if applicable)
+
+If your "Architecture Updates" or "Lessons Learned Updates" section calls out real changes, update `codev/resources/arch.md` and/or `codev/resources/lessons-learned.md` accordingly. Use the `update-arch-docs` skill if it's available.
+
+If neither doc needs updating, your review file's sections still need to explain why — the porch `checks` block enforces section presence.
+
+### 3. Commit the Review File (and arch / lessons updates)
+
+```bash
+git add codev/reviews/{{artifact_name}}.md
+# Add arch.md / lessons-learned.md only if you changed them
+git add codev/resources/arch.md           # only if changed
+git add codev/resources/lessons-learned.md  # only if changed
+git commit -m "[PIR #{{issue.number}}] Review + retrospective"
+git push
+```
+
+### 4. Open the PR
+
+```bash
+PR_TITLE="<concise description of the change>"
+BRANCH="$(git branch --show-current)"
+
+gh pr create \
+  --base main \
+  --head "$BRANCH" \
+  --title "$PR_TITLE" \
+  --body-file codev/reviews/{{artifact_name}}.md
+```
+
+**Verify the PR body contains `Fixes #{{issue.number}}`** (it should — the review file has it at the top). If somehow missing, edit and re-apply:
+
+```bash
+gh pr edit <PR-number> --body-file codev/reviews/{{artifact_name}}.md
+```
+
+**Exception**: if this PR only partially addresses the issue, use `Refs #{{issue.number}}` instead — the issue stays open until a follow-up PR closes it.
+
+### 4a. Record the PR with Porch
+
+Immediately after creating the PR, tell porch about it so `status.yaml` carries the PR number and branch. This is a metadata-only call — it does NOT advance the phase or trigger CMAP:
+
+```bash
+porch done {{project_id}} --pr <PR-number> --branch "$(git branch --show-current)"
+```
+
+Without this, porch's `history:` for the project stays empty and downstream tooling (status views, analytics, audit trails) can't link the porch project to its GitHub PR.
+
+### 5. Signal Completion to Porch (porch runs CMAP-2)
+
+```bash
+porch done {{project_id}}
+```
+
+Porch will:
+1. Run the `pr_exists` / `review_has_arch_updates` / `review_has_lessons_updates` checks.
+2. **Execute CMAP-2 (Gemini + Codex) automatically** via the protocol's `verify` block. Outputs land in `codev/projects/{{project_id}}-<slug>/{{project_id}}-gemini.txt` and `<id>-codex.txt`.
+3. CMAP runs **exactly once** (`max_iterations: 1`). Whatever the verdicts, porch records them in `status.yaml` and advances to the `pr` gate — there is **no automated re-review pass and no "stays in the review phase" loop**. `APPROVE` and `REQUEST_CHANGES` differ only in what you must surface to the human (steps 6–7), not in whether the gate fires. The output of `porch done` surfaces the verdicts.
+
+> **Why CMAP-2, not CMAP-3?** PIR's design parallels BUGFIX/AIR's consult footprint. The human already approved the *running* implementation at the `dev-approval` gate; CMAP at PR is a pre-merge hygiene + code-quality pass, not a functional review.
+
+### 6. Handle a REQUEST_CHANGES Verdict (single-pass — no automated re-review)
+
+PIR's CMAP is one advisory pass (`max_iterations: 1`). If a reviewer returns `REQUEST_CHANGES`, porch does **not** loop or re-run CMAP — it records the verdict and proceeds to the `pr` gate. There is no iter-2. The correctness backstop for a CMAP-flagged issue is therefore **(a)** your fix + a regression test and **(b)** the human's `pr`-gate review — *not* an independent model re-review. Treat that as load-bearing: a substantive finding you "address and rebut" gets no second AI opinion.
+
+For any `REQUEST_CHANGES`:
+
+1. Read the finding in full (`codev/projects/{{project_id}}-*/{{project_id}}-<model>.txt`).
+2. **Assess it honestly:**
+   - **Real defect** (correctness / cancellation / security / data-loss): fix it in code, add a regression test that fails without the fix, commit + push (the PR updates automatically — no new `gh pr create`). Then document the finding, your fix, and the pinning test in the review file's **"Things to Look At During PR Review"** section.
+   - **False positive / out of scope**: write a brief rebuttal in that same section explaining why no change is warranted.
+3. Do **not** re-run `porch done` expecting another CMAP — `max_iterations: 1` means it will not re-review. Proceed to step 7.
+
+Whether you fixed it or rebutted it, a `REQUEST_CHANGES` that PIR will never re-check **must be escalated to the human at the `pr` gate** (step 7) — they are the only remaining reviewer of that decision.
+
+### 7. Notify the Architect (after the single CMAP pass — gate is now pending)
+
+After the one CMAP pass + structural checks, porch fires the **`pr` gate** (pending) **regardless of the verdicts**. Read the verdicts from porch state and notify — and if any verdict is `REQUEST_CHANGES`, **lead with it and state the disposition**, because PIR will not re-review it and the human at the `pr` gate is the only remaining check:
+
+```bash
+GEMINI_VERDICT=$(grep -m1 -i '^\(approve\|request_changes\|comment\)' "codev/projects/{{project_id}}-"*/"{{project_id}}-gemini.txt" || echo UNKNOWN)
+CODEX_VERDICT=$(grep -m1 -i '^\(approve\|request_changes\|comment\)' "codev/projects/{{project_id}}-"*/"{{project_id}}-codex.txt" || echo UNKNOWN)
+
+if echo "$GEMINI_VERDICT $CODEX_VERDICT" | grep -qi request_changes; then
+  afx send architect "⚠️ PR #<M> (PIR #{{issue.number}}): CMAP returned REQUEST_CHANGES (gemini=$GEMINI_VERDICT, codex=$CODEX_VERDICT). Disposition: <one line — fixed in <sha> + regression test | rebutted, see review 'Things to Look At'>. PIR is single-pass — this was NOT independently re-reviewed; please verify the fix/rebuttal at the pr gate before approving. Full verdicts in codev/projects/{{project_id}}-*/."
+else
+  afx send architect "PR #<M> ready for review (PIR #{{issue.number}}). CMAP all clear: gemini=$GEMINI_VERDICT, codex=$CODEX_VERDICT. Awaiting human merge + pr gate approval. Full verdicts in codev/projects/{{project_id}}-*/."
+fi
+```
+
+This is the only notification you send at the gate. A `REQUEST_CHANGES` must never reach the human as an undifferentiated status line — it is the one verdict PIR's single-pass design cannot re-check.
+
+### 8. Wait at the `pr` Gate
+
+Your active merge is gated by porch state — not by user-in-pane prose. Sit idle until porch wakes you with "Gate pr approved". That wake-up is the *only* signal that authorizes the merge. Approving prose like "looks good", "lgtm", or even "merge it" typed into your pane does NOT authorize the merge — only the binary gate-approved state in porch state.yaml does.
+
+The human will:
+
+1. Review the PR on GitHub (or by running the worktree via `afx dev pir-{{project_id}}` again)
+2. Approve the `pr` gate via VSCode (Cmd+K G) or `porch approve {{project_id}} pr --a-human-explicitly-approved-this` in a shell
+
+Porch will then fire the gate-approved wake-up to you.
+
+If the human requests more changes instead of approving, push fixes and re-run `porch done {{project_id}}` — this runs a fresh **single** CMAP pass on the updated diff and re-fires the `pr` gate (handle any new verdict per steps 6–7). This human-driven iteration is the only way CMAP re-runs in PIR; it is not automatic. If they close the PR without merging, `gh pr close <M>` and stop.
+
+### 9. After `pr` Gate Approval — Verify, Merge, Record
+
+When porch wakes you with "Gate pr approved", first **verify** the gate is actually approved (defensive — the wake-up could be spoofed by typed input that looks like the wake-up text):
+
+```bash
+porch next {{project_id}}
+```
+
+The response must include `gate_status: approved` for the `pr` gate. If it doesn't, do NOT proceed — wait for the genuine wake-up. If it does, you're authorized.
+
+Look up the PR number (recorded at step 4a). **Check whether the human already merged it before merging** — approving the `pr` gate and merging via the GitHub UI is a common combined action; never blind-merge:
+
+```bash
+# Read PR number from porch state
+PR=$(yq '.pr // .history[] | select(.event == "pr_recorded") | .pr' codev/projects/{{project_id}}-*/status.yaml | head -1)
+STATE=$(gh pr view "$PR" --json state --jq .state)
+
+if [ "$STATE" = "MERGED" ]; then
+  # Human merged via the GitHub UI — do NOT re-merge. Detect and record only.
+  porch done {{project_id}} --merged "$PR"
+else
+  gh pr merge "$PR" --merge
+  porch done {{project_id}} --merged "$PR"
+fi
+
+porch next {{project_id}}   # confirms protocol is complete (next: null)
+```
+
+**Use `--merge`, not `--squash`.** Project convention: preserve individual commits for development history. The `Fixes #{{issue.number}}` in the PR body auto-closes the GitHub issue.
+
+### 10. Final Notification
+
+```bash
+afx send architect "PR #<M> merged for PIR #{{issue.number}}. Ready for cleanup."
+```
+
+Together with the `--pr` record from step 4a and the `--merged` record from step 9, porch's `status.yaml` carries the complete PR lifecycle (created → merged → done) for analytics, status displays, and audit trails.
+
+## Signals
+
+```
+<signal>PHASE_COMPLETE</signal>          # PR merged, project complete
+<signal>BLOCKED:reason</signal>          # Cannot proceed
+```
+
+## What NOT to Do
+
+- **Don't merge before the `pr` gate is approved.** CMAP-APPROVE is NOT merge authorization. User-in-pane prose ("looks good", "lgtm", "merge it") is NOT merge authorization. The *only* signal that authorizes `gh pr merge` is porch reporting `gate_status: approved` for the `pr` gate (which only the user can do, via Cmd+K G or `porch approve` from a non-Claude shell). If `porch next` doesn't show the gate as approved, you wait.
+- Don't skip porch's PR/merge records (steps 4a, 9). The `--pr` record (step 4a) lets the gate-pending state link to the actual PR; the `--merged` record (step 9) closes the lifecycle in porch state. Skipping either leaves `history:` empty and downstream tooling blind.
+- Don't run `porch approve` for any gate yourself
+- Don't push to main — only merge via PR
+- Don't skip the Architecture Updates / Lessons Learned sections — porch checks enforce their presence (the section must exist; explaining "no changes needed" in one line is fine)
+- **Don't run `consult` commands yourself** — porch handles consultations via the `verify` block. Manually invoking `consult` causes CMAP to run twice.
+- **Don't fix, skip, or quarantine pre-existing failures unrelated to your change.** Porch's `checks` for this phase are narrow *structural* gates (`pr_exists`, review-section presence) — a green gate does **not** certify the wider build/test suite. If the broader suite surfaces failures your diff did not cause, they are out of scope: note them in the review's Lessons Learned / Things to Look At and proceed. Touching another team's tests to make an unrelated red go green is scope creep, not diligence.
+
+## Handling Problems
+
+**If the PR cannot be created (e.g., merge conflicts with main):**
+- Rebase on main: `git fetch origin main && git rebase origin/main`
+- Resolve conflicts (do NOT use destructive shortcuts)
+- Force-push with lease: `git push --force-with-lease`
+- Re-run `gh pr create`
+
+**If porch's CMAP consults fail (e.g., model unavailable):**
+- `porch done` will report the failure. Inspect `codev/projects/{{project_id}}-*/{{project_id}}-<model>.txt` for the failure details.
+- Re-run `porch done {{project_id}}` once — porch will retry the consult.
+- If the model is persistently unavailable, notify the architect and ask whether to proceed without that model's verdict. They may direct you to skip via a manual override.
+
+**If the architect doesn't respond within a reasonable window:**
+- Send one follow-up via `afx send architect "..."` after a few hours
+- Do not auto-merge

package/skeleton/protocols/pir/protocol.json

@@ -0,0 +1,125 @@
+{
+  "$schema": "../../protocol-schema.json",
+  "name": "pir",
+  "alias": "plan-implement-review",
+  "version": "1.0.0",
+  "description": "PIR: Plan → Implement → Review with build-verify cycles and two pre-PR human gates (plan-approval, dev-approval), for GitHub-issue-driven work.",
+  "input": {
+    "type": "github-issue",
+    "required": true,
+    "default_for": ["--issue", "-i"]
+  },
+  "hooks": {
+    "pre-spawn": {
+      "collision-check": true,
+      "comment-on-issue": "On it! Working on this with the PIR protocol (plan + dev-approval gates before PR)."
+    }
+  },
+  "phases": [
+    {
+      "id": "plan",
+      "name": "Plan",
+      "description": "Read the issue, investigate the codebase, write codev/plans/<id>-<slug>.md, await plan-approval",
+      "type": "build_verify",
+      "build": {
+        "prompt": "plan.md",
+        "artifact": "codev/plans/${PROJECT_TITLE}.md"
+      },
+      "verify": null,
+      "max_iterations": 1,
+      "on_complete": {
+        "commit": true,
+        "push": true
+      },
+      "checks": {
+        "plan_exists": "test -f codev/plans/${PROJECT_TITLE}.md"
+      },
+      "gate": "plan-approval",
+      "next": "implement"
+    },
+    {
+      "id": "implement",
+      "name": "Implement",
+      "description": "Write code + tests, run build/test checks, await dev-approval on the running worktree",
+      "type": "build_verify",
+      "build": {
+        "prompt": "implement.md",
+        "artifact": "src/**/*.{ts,tsx,js,jsx,py,go,rs}"
+      },
+      "verify": null,
+      "max_iterations": 1,
+      "on_complete": {
+        "commit": true,
+        "push": true
+      },
+      "checks": {
+        "build": {
+          "command": "npm run build",
+          "on_fail": "retry",
+          "max_retries": 2
+        },
+        "tests": {
+          "command": "npm test",
+          "on_fail": "retry",
+          "max_retries": 2
+        }
+      },
+      "gate": "dev-approval",
+      "next": "review"
+    },
+    {
+      "id": "review",
+      "name": "Review",
+      "description": "Write retrospective (arch + lessons), push, open PR with review as body, run CMAP, then wait at pr gate while the human merges on GitHub",
+      "type": "build_verify",
+      "build": {
+        "prompt": "review.md",
+        "artifact": "codev/reviews/${PROJECT_TITLE}.md"
+      },
+      "verify": {
+        "type": "impl",
+        "models": ["gemini", "codex"],
+        "parallel": true
+      },
+      "max_iterations": 1,
+      "on_complete": {
+        "commit": true,
+        "push": true
+      },
+      "checks": {
+        "pr_exists": {
+          "command": "gh pr list --state all --head \"$(git branch --show-current)\" --json number --jq 'length' | grep -q '^[1-9]'",
+          "description": "PR must be created before signaling completion"
+        },
+        "review_has_arch_updates": {
+          "command": "grep -q '## Architecture Updates' codev/reviews/${PROJECT_TITLE}.md",
+          "description": "Review must include '## Architecture Updates' section (what changed in arch.md, or why no changes needed)"
+        },
+        "review_has_lessons_updates": {
+          "command": "grep -q '## Lessons Learned Updates' codev/reviews/${PROJECT_TITLE}.md",
+          "description": "Review must include '## Lessons Learned Updates' section (what changed in lessons-learned.md, or why no changes needed)"
+        }
+      },
+      "gate": "pr",
+      "next": null
+    }
+  ],
+  "signals": {
+    "PHASE_COMPLETE": {
+      "description": "Signal current build phase is complete",
+      "transitions_to": "next_phase"
+    },
+    "BLOCKED": {
+      "description": "Signal implementation is blocked",
+      "requires": "reason"
+    }
+  },
+  "defaults": {
+    "mode": "strict",
+    "max_iterations": 1,
+    "consultation": {
+      "enabled": true,
+      "parallel": true
+    }
+  }
+}

package/skeleton/protocols/pir/protocol.md

@@ -0,0 +1,204 @@
+# PIR Protocol
+
+> **Plan → Implement → Review** for GitHub-issue-driven work that needs human review of *either* the approach (before code is written) *or* the implementation (before a PR exists), or both. Lighter than SPIR/ASPIR (no `specify` phase — the GitHub issue is the implicit spec) with the human dev-approval moved earlier (pre-PR instead of post-PR). Stronger than BUGFIX/AIR (two human gates before the PR).
+
+## When to Use PIR
+
+Pick PIR when working from a GitHub Issue and ONE or BOTH of the following apply — based on the *nature* of the change, not its size:
+
+### 1. The approach needs review before coding starts
+- Root cause is ambiguous; multiple valid fixes exist
+- Area is unfamiliar or high-blast-radius (shared utilities, auth, migrations, public APIs)
+- Design-sensitive (affects conventions, patterns, architecture)
+- Cheaper to redirect at plan time than at PR time
+
+### 2. The implementation needs to be tested before a PR is created
+The PR diff alone is insufficient; the reviewer must *run* the code:
+- Mobile app changes (needs device testing on Android, iOS, possibly web)
+- UI / UX changes (visual inspection, interaction flow, accessibility)
+- Hardware-adjacent behavior (sensors, camera, permissions, notifications)
+- Integration with external services that don't mock cleanly (OAuth, payments, analytics)
+- User-journey changes that need a full-flow exercise
+- Performance-sensitive changes that need profiling on the running app
+
+### Use SPIR / ASPIR / BUGFIX / AIR instead when
+- **SPIR / ASPIR**: the change is complex enough to warrant careful specification, multi-agent consultation at every phase, and the full spec → plan → implement → review ceremony with file artifacts. The driving issue is incidental — what matters is that the design work deserves a formal spec and the implementation deserves consult-driven review at each phase
+- **BUGFIX**: small bug fix, no design review needed, diff-on-PR review is enough
+- **AIR**: small feature from an issue, autonomous, diff-on-PR review is enough
+
+## How PIR Differs from SPIR
+
+PIR is structurally *SPIR minus the `specify` phase*, with the human dev-approval moved earlier (pre-PR instead of post-PR).
+
+| Aspect | SPIR | PIR |
+|---|---|---|
+| Phases | specify → plan → implement → review → verify | plan → implement → review |
+| Spec artifact | `codev/specs/<id>-<slug>.md` | GitHub Issue body (implicit spec) |
+| Plan artifact | `codev/plans/<id>-<slug>.md` | Same — committed on builder branch |
+| Review artifact | `codev/reviews/<id>-<slug>.md` (Summary + Architecture Updates + Lessons Learned, becomes PR body) | **Same shape** — `codev/reviews/<id>-<slug>.md` with the same sections, also becomes PR body |
+| Human gates | spec-approval, plan-approval, pr, verify-approval | plan-approval, dev-approval, pr |
+| Where code is reviewed by the human | On the PR (post-creation) — read the diff | Pre-PR (at the `dev-approval` gate) — read the diff **and run the worktree locally** |
+
+The review file always includes Summary, Architecture Updates, and Lessons Learned sections so `codev/reviews/` stays semantically consistent across all protocols. PIR's lightness comes from skipping the `specify` phase (the issue body is the spec), not from cutting corners on the retrospective.
+
+The `dev-approval` gate is what makes PIR genuinely different: the human gates the *running implementation* via the worktree before the PR exists, instead of gating the PR after creation.
+
+## Phases
+
+```
+plan → implement → review
+```
+
+### Plan (gated by `plan-approval`)
+
+The builder:
+1. Reads the GitHub issue and investigates the codebase
+2. Writes `codev/plans/<id>-<slug>.md` with: Understanding / Proposed change / Files to change / Risks & alternatives / Test plan
+3. Commits the plan on the builder branch and pushes
+4. Runs `porch done` and `porch next` — the `plan-approval` gate becomes pending
+5. Sits at the interactive prompt waiting for review
+
+**Reviewer paths** (all equivalent):
+- Open `codev/plans/<id>-<slug>.md` in the worktree, read and / or edit directly, save
+- Type feedback into the builder's PTY pane — the builder is alive in interactive mode
+- `afx send <builder-id> "<feedback>"`
+- Comment on the GitHub issue (sidecar discussion)
+
+When satisfied, approve via VSCode's "Approve Gate" command (Cmd+K G) or:
+
+```bash
+porch approve <id> plan-approval --a-human-explicitly-approved-this
+```
+
+### Implement (gated by `dev-approval`)
+
+The builder:
+1. Reads the approved plan file
+2. Writes code and tests; runs build + tests via the `checks` block
+3. *No AI consult on this phase* — the human at the `dev-approval` gate is the sole reviewer of the running code. Matches BUGFIX / AIR's pattern of "no consult on implementation, one consult at PR creation".
+4. Pushes the branch
+5. Runs `porch done` and `porch next` — the `dev-approval` gate becomes pending
+6. Outputs a **prose** dev-approval summary in the PTY pane (Summary / Files / Test results / Things to look at / How to test locally). This is a transient message to orient the human reviewer — **not a committed file**. The retrospective file is written in the next phase, after the human approves the running code.
+7. Sits at the interactive prompt
+
+**The reviewer's killer move**: run the worktree locally.
+
+- VSCode: right-click the builder in the Codev sidebar → **Run Dev Server** (spawns `afx dev <builder-id>` via Tower)
+- CLI: `afx dev <builder-id>`
+
+The dev server uses **the same ports and URLs as main** intentionally (OAuth callbacks, CORS, cookie scoping all depend on consistent origins). Only one dev env runs at a time; stop main's `pnpm dev` before starting the worktree's, or use VSCode's **Stop Dev Server** to swap.
+
+Reviewer tests the change on real devices / browsers / simulators. When satisfied, approves via Cmd+K G or:
+
+```bash
+porch approve <id> dev-approval --a-human-explicitly-approved-this
+```
+
+### Review (gated by `pr`)
+
+The builder:
+1. Writes `codev/reviews/<id>-<slug>.md` with **Summary**, **Architecture Updates**, **Lessons Learned Updates**, plus the supporting sections (Files Changed, Commits, Test Results, Things to Look At, How to Test Locally).
+2. Updates `codev/resources/arch.md` and/or `codev/resources/lessons-learned.md` if real changes need recording. If not, the review file's sections state "no changes needed" with a one-line explanation (the porch `checks` block enforces section presence, not content).
+3. Commits the review file (and arch / lessons updates if any) and pushes
+4. Opens a PR with `gh pr create`; PR body is the review file content + `Fixes #<N>`. Records the PR with `porch done <id> --pr <M> --branch <name>`.
+5. Runs `porch done <id>` — porch's `verify` block runs CMAP-2 (Gemini + Codex, type=impl) as a **single advisory pass** (`max_iterations: 1`); CMAP outputs land in `codev/projects/<id>-*/`. There is no iterate-until-APPROVE loop: whatever the verdicts, porch records them and advances to the `pr` gate. A `REQUEST_CHANGES` is not auto-re-reviewed — the builder addresses or rebuts it, adds a regression test if it's a real defect, and escalates it in the architect notification so the human verifies it at the `pr` gate. Outcomes are not auto-appended to the PR body; reviewers with the worktree read them from the projects dir.
+6. The `pr` gate fires (pending) regardless of verdict. Builder notifies the architect once — leading with any `REQUEST_CHANGES` and its disposition (since PIR will not re-review it) rather than burying it in a flat status line.
+7. Builder waits at the `pr` gate. The human reviews the PR on GitHub, then approves the `pr` gate (Cmd+K G or `porch approve <id> pr --a-human-explicitly-approved-this`). Porch wakes the builder.
+8. Builder verifies the gate is genuinely approved via `porch next` (defensive — typed prose can't trigger this branch, only real porch state does), then runs `gh pr merge --merge`, records via `porch done --merged <M>`, and sends the cleanup-ready notification. Protocol complete (`next: null`).
+
+## Gates
+
+PIR uses porch's existing gate machinery. Gate names are opaque strings; no porch engine changes are needed.
+
+- **`plan-approval`** — pre-PR. Human reads the plan file (committed on the builder branch) and approves before any code is written. Gates are keyed by `(project_id, gate_name)` so the name is safe to share with other protocols.
+- **`dev-approval`** — pre-PR. The human reviews the *running* worktree (via `afx dev`) before any PR exists. This is PIR's distinctive gate.
+- **`pr`** — post-PR. Gates the merge step. The human reviews the PR on GitHub and approves this gate; porch wakes the builder, which then runs `gh pr merge`. The gate exists so the merge trigger is structured porch state (binary approved/not), not free-text prose typed into the builder's pane. Eliminates the self-merge bug class: builders can't infer authorization from ambiguous user input.
+
+When a gate becomes pending, porch broadcasts `overview-changed` via SSE. The VSCode Builders tree picks up the blocked state and renders it with a bell icon; a toast surfaces the new gate-pending event. Architect notification is *not* automatic — gates surface via the toast/sidebar (for IDE users) or by checking the builder pane / `porch pending` (for CLI users). The builder's job at any gate is to write the artifact, commit, signal completion, and wait — never to invoke `porch approve` itself (Claude refuses the `--a-human-explicitly-approved-this` flag by design).
+
+## Rejection / Feedback Model
+
+There is no formal `porch reject` command. Rejection works via the feedback-iterate pattern:
+
+1. Reviewer provides feedback (edit the plan file in VSCode, type in the builder pane, `afx send`, or issue comment)
+2. Builder reads the feedback on its next turn, revises the artifact, recommits
+3. The gate remains pending — porch doesn't advance until the human runs `porch approve`
+
+The same pattern works at both gates.
+
+## Builder Session Lifetime
+
+The builder is a long-running interactive Claude Code session in a PTY pane managed by Tower. The session is launched as `claude "<prompt>"` (no `--print`) inside a `while true` restart loop. That form starts an interactive Claude REPL with the prompt as the first user message; after Claude finishes the prompted work it sits at the input prompt awaiting next user input. The outer `while true` loop only fires if Claude crashes — it is a crash-recovery safety net, not the gate-wait mechanism.
+
+This means typed input in the builder pane reaches the live Claude session immediately, exactly like any other interactive Claude Code conversation. There is no "session ended at gate" state to worry about under normal operation.
+
+## Configuration
+
+PIR uses the same `.codev/config.json` configuration as other protocols. The `worktree` block (from Issue 689) enables the at-gate dev-server review flow:
+
+```json
+{
+  "worktree": {
+    "symlinks": [".env.local", "packages/*/.env"],
+    "postSpawn": ["pnpm install --frozen-lockfile"],
+    "devCommand": "pnpm dev"
+  }
+}
+```
+
+Without `worktree.devCommand`, `afx dev` won't work and the `dev-approval` gate degenerates to a diff-read — at which point you should probably use AIR or BUGFIX instead.
+
+## Multi-Agent Consultation
+
+- **plan**: human-only review. No AI consultation.
+- **implement**: no AI consult — the human at the `dev-approval` gate is the sole reviewer of the running code.
+- **review**: CMAP-2 (Gemini + Codex, type=impl) after the PR is opened, as a **single advisory pass** (`max_iterations: 1`). Same pattern as BUGFIX / AIR's PR-creation consult.
+
+CMAP at the PR is a single pass — there is **no iterate-until-APPROVE loop**. A `REQUEST_CHANGES` does not block or re-trigger CMAP; the builder addresses or rebuts it and escalates it to the human at the `pr` gate, who is the sole remaining reviewer of any resulting fix (CMAP does not re-check it).
+
+Net: PIR runs **two model calls per protocol run**, matching its BUGFIX/AIR peers — its distinguishing features are the two human gates (`plan-approval`, `dev-approval`), not AI-consult density.
+
+**The 2-model footprint is a design invariant.** porch's model precedence is *config > protocol* (`porch.consultation.models` in `.codev/config.json` overrides a protocol's declared `verify.models`). A project-wide setting tuned for SPIR (gemini + codex + claude) will silently inflate PIR to a 3-model pass, breaking the BUGFIX/AIR-parity cost story. To keep PIR at CMAP-2, leave `porch.consultation.models` unset or scope it per-protocol.
+
+To disable consultation entirely, say "without multi-agent consultation" when starting work.
+
+## Signals
+
+PIR uses the standard porch signal vocabulary:
+
+```
+<signal>PHASE_COMPLETE</signal>          # Current phase build complete
+<signal>BLOCKED:reason</signal>          # Cannot proceed
+```
+
+Signals are informational for log readability. The state machine is driven by `porch done` and `porch next` CLI calls inside the builder turn.
+
+## Commit Messages
+
+Commits during PIR phases use the issue-driven format:
+
+```
+[PIR #<N>] Plan draft
+[PIR #<N>] Implement avatar masking
+[PIR #<N>] Add Android-side regression test
+```
+
+The PR title follows the project's existing PR convention.
+
+## Branch Naming
+
+```
+builder/pir-<issue-number>
+```
+
+Example: `builder/pir-842` for a PIR spawn against GitHub issue #842.
+
+## File Locations
+
+```
+codev/plans/<id>-<slug>.md             # written in plan phase, on builder branch
+codev/reviews/<id>-<slug>.md           # written in review phase (post-dev-approval-approval), on builder branch; becomes PR body
+codev/projects/<id>-<slug>/status.yaml # porch state, managed automatically
+```
+
+The plan and review files ship to `main` with the merged PR — durable, searchable, git-versioned. The review file includes Summary + Architecture Updates + Lessons Learned + supporting sections, so `codev/reviews/` stays semantically consistent across protocols.

package/skeleton/templates/AGENTS.md

@@ -12,10 +12,34 @@ This project uses **Codev** for AI-assisted development.
 - **ASPIR**: Autonomous SPIR — no human gates on spec/plan (`codev/protocols/aspir/protocol.md`)
 - **AIR**: Autonomous Implement & Review for small features (`codev/protocols/air/protocol.md`)
 - **BUGFIX**: Bug fixes from GitHub issues (`codev/protocols/bugfix/protocol.md`)
+- **PIR**: Plan / Implement / Review — issue-driven with three human gates (plan-approval, dev-approval, pr) (`codev/protocols/pir/protocol.md`)
 - **EXPERIMENT**: Disciplined experimentation (`codev/protocols/experiment/protocol.md`)
 - **MAINTAIN**: Codebase maintenance (`codev/protocols/maintain/protocol.md`)
 - **RESEARCH**: Multi-agent research with 3-way investigation, synthesis, and critique (`codev/protocols/research/protocol.md`)
 
+## File Resolution (How Codev Finds Protocols and Templates)
+
+Codev resolves protocol files, prompts, agent definitions, and roles through a four-tier lookup (highest priority first):
+
+1. `.codev/<path>` — user override (project-local customization)
+2. `codev/<path>` — project-local copy (customized and checked in)
+3. Runtime cache
+4. **Installed package skeleton** — ships with `@cluesmith/codev` (the default for every standard protocol)
+
+**The absence of `codev/protocols/<name>/` on disk is not a missing reference** — it's the normal case for any protocol you haven't customized. The protocol resolves from the installed package's skeleton at runtime. Only protocols you want to customize need to live in your repo's `codev/protocols/`.
+
+**Implication for `codev update` and CLAUDE.md / AGENTS.md merges:** when an updated template references a protocol, do NOT drop the reference because `codev/protocols/<name>/` is absent locally. The protocol resolves via the package skeleton, and dropping the reference removes it from your available-protocol list while it's still callable from the CLI.
+
+## Protocol Verification (When You Don't Recognize a Protocol Name)
+
+If the user mentions a protocol name you don't immediately recognize, verify against the CLI before responding:
+
+```bash
+afx spawn --protocol <name> --help
+```
+
+This succeeds if the protocol is registered (including via the skeleton fallback in tier 4 of the resolution chain) and errors helpfully otherwise. The CLI is the source of truth — defer to it when in doubt.
+
 ## Key Locations
 
 - **Specs**: `codev/specs/` - Feature specifications (WHAT to build)