@cluesmith/codev 3.2.4 → 3.3.1

package/skeleton/protocols/pir/consult-types/impl-review.md

@@ -2,47 +2,27 @@
 
 ## Context
 
-You are reviewing the implementation of a PIR protocol project before it reaches the `dev-approval` human gate. A builder has implemented the approved plan and written a dev-approval summary. Your job is to verify the implementation matches the plan and is ready for human review.
+You are reviewing a PIR implementation before it reaches the `dev-approval` human gate. A builder has implemented the approved plan and written a dev-approval summary. Verify the implementation matches the plan and is ready for human review.
 
-## CRITICAL: Verify Before Flagging
+## Verify before flagging
 
-Before requesting changes for missing configuration, incorrect patterns, or framework issues:
-1. **Check `package.json`** for actual dependency versions — framework conventions change between major versions
-2. **Read the actual config files** (or confirm their deliberate absence) before flagging missing configs
-3. **Do not assume** your training data reflects the version in use — verify against project files
-4. If "Previous Iteration Context" is provided, read it carefully before re-raising concerns that were already disputed
+Before requesting changes for missing configuration, wrong patterns, or framework issues, confirm the claim against the project rather than your training data:
 
-## Focus Areas
-
-1. **Plan Adherence**
-   - Does the implementation fulfill the approved plan?
-   - Are all "Files to Change" actually changed?
-   - Are the changes scoped to what the plan described, or has scope crept?
-
-2. **Code Quality**
-   - Is the code readable and maintainable?
-   - Are there obvious bugs?
-   - Are error cases handled appropriately?
-   - Is the change minimal — no unnecessary refactoring or unrelated tidy-ups?
-
-3. **Test Coverage**
-   - Are the tests adequate for the changes?
-   - Do tests cover both the main path and the edge cases the plan called out?
-   - For a bug fix: is there a regression test that would fail without the fix?
+- Check `package.json` for the actual dependency versions — framework conventions change between major versions.
+- Read the actual config files (or confirm their deliberate absence) before flagging a missing config.
+- If "Previous Iteration Context" is provided, read it before re-raising concerns already disputed.
 
-4. **Review File Quality**
-   - Does `codev/reviews/<id>-<slug>.md` exist and follow the template?
-   - Does it accurately describe what changed?
-   - Is "Things to Look At" honest about tricky spots?
-   - Is "How to Test Locally" specific enough that the human reviewer can act on it?
+## Focus Areas
 
-5. **PIR-Specific Concerns**
-   - For UI / mobile / cross-platform changes: does the review file explain platform-specific behavior the human should verify?
-   - For changes with external integrations: are the integration points documented?
+- **Plan Adherence** — the implementation fulfills the approved plan; every "Files to Change" is changed; the change is scoped to the plan, no creep.
+- **Code Quality** — readable and maintainable; no obvious bugs; error cases handled; the change is minimal, with no unrelated refactors.
+- **Test Coverage** — tests are adequate and cover the plan's main path and edge cases; a bug fix has a regression test that would fail without the fix.
+- **Review File Quality** — `codev/reviews/<id>-<slug>.md` exists, follows the template, describes what changed accurately, is honest in "Things to Look At", and specific enough in "How to Test Locally" for the human to act on.
+- **PIR-Specific Concerns** — for UI / mobile / cross-platform changes, the review file explains platform-specific behavior the human should verify; for external integrations, the integration points are documented.
 
 ## Verdict Format
 
-After your review, provide your verdict in exactly this format:
+Provide your verdict in exactly this format — `consult` parses it:
 
 ```
 ---
@@ -56,23 +36,10 @@ KEY_ISSUES:
 ...
 ```
 
-**Verdict meanings:**
-- `APPROVE`: Ready for human at the `dev-approval` gate
-- `REQUEST_CHANGES`: Issues that must be fixed before reaching the human
-- `COMMENT`: Minor suggestions, can proceed but note feedback
+- `APPROVE`: ready for the human at the `dev-approval` gate.
+- `REQUEST_CHANGES`: issues that must be fixed before reaching the human.
+- `COMMENT`: minor suggestions; can proceed but note the feedback.
 
 ## Scope
 
-- **DO** review the implementation against the approved plan
-- **DO** flag missing regression tests for bug fixes
-- **DO** flag obvious bugs, code smells, security issues
-- **DO NOT** redesign the approach — that was settled at `plan-approval`
-- **DO NOT** demand changes outside the plan's scope
-- **DO NOT** request architecture-level refactors unless the change introduces a clear new problem
-
-## Notes
-
-- This is a pre-gate review; the human is the final authority
-- Focus on "is this ready for someone else to test in a browser / simulator"
-- If referencing line numbers, use `file:line` format
-- The builder needs actionable feedback to iterate
+Review the implementation against the approved plan; flag missing regression tests for bug fixes, and obvious bugs, code smells, or security issues. Do **not** redesign the approach (that was settled at `plan-approval`), demand changes outside the plan's scope, or request architecture-level refactors unless the change introduces a clear new problem. This is a pre-gate review — the human is the final authority; focus on "is this ready for someone else to test in a browser / simulator".

package/skeleton/protocols/pir/consult-types/pr-review.md

@@ -2,37 +2,19 @@
 
 ## Context
 
-You are performing the 3-way review of a PIR protocol PR. The builder has implemented an approved plan, the human has approved the `dev-approval` gate (meaning a human has run the code locally and tested it), and the PR has been opened. This is a single advisory pass (`max_iterations: 1`) — your verdict is surfaced to the human at the `pr` gate, who is the sole remaining reviewer; it is not auto-re-reviewed.
+You are performing the 3-way review of a PIR PR. The builder implemented an approved plan, the human approved the `dev-approval` gate (having run and tested the code locally), and the PR is open. This is a single advisory pass (`max_iterations: 1`) — your verdict is surfaced to the human at the `pr` gate, who is the sole remaining reviewer; it is not auto-re-reviewed.
 
 ## Focus Areas
 
-1. **Completeness**
-   - Is the PR body the review file content + `Fixes #<N>`?
-   - Are all commits properly formatted (`[PIR #<N>] ...`)?
-   - Does the diff match what the review file describes?
-
-2. **Test Status**
-   - Do all tests pass on the branch?
-   - Is test coverage adequate for the change?
-   - Are there skipped or flaky tests documented?
-
-3. **Code Quality**
-   - Any debug code left in?
-   - Any TODO comments that should be resolved?
-   - Any `// REVIEW:` markers that weren't addressed?
-
-4. **Branch Hygiene**
-   - Is the branch up to date with the default branch? (If not, suggest a rebase. The default branch is whatever `git symbolic-ref --short refs/remotes/origin/HEAD` reports — typically `main`, but may be `dev`, `ci`, etc.)
-   - Are commits atomic and well-described?
-   - Is the change diff a reasonable size for the issue scope?
-
-5. **Issue Linkage**
-   - Does the PR body contain `Fixes #<N>` (or `Refs #<N>` for partial fixes)?
-   - Without this, GitHub won't auto-close the issue on merge
+- **Completeness** — the PR body is the review-file content plus `Fixes #<N>`; commits are formatted `[PIR #<N>] ...`; the diff matches what the review file describes.
+- **Test Status** — all tests pass on the branch, coverage is adequate, and skipped/flaky tests are documented.
+- **Code Quality** — no debug code, no stray `TODO` or unaddressed `// REVIEW:` markers.
+- **Branch Hygiene** — the branch is up to date with the default branch (whatever `git symbolic-ref --short refs/remotes/origin/HEAD` reports — typically `main`, sometimes `dev`/`ci`); commits are atomic; the diff size is reasonable for the issue.
+- **Issue Linkage** — the PR body carries `Fixes #<N>` (or `Refs #<N>` for a partial fix), without which GitHub won't auto-close the issue on merge.
 
 ## Verdict Format
 
-After your review, provide your verdict in exactly this format:
+Provide your verdict in exactly this format — `consult` parses it:
 
 ```
 ---
@@ -46,21 +28,10 @@ KEY_ISSUES:
 ...
 ```
 
-**Verdict meanings:**
-- `APPROVE`: Ready to merge
-- `REQUEST_CHANGES`: Issues to fix before merging
-- `COMMENT`: Minor items, can merge but note feedback
+- `APPROVE`: ready to merge.
+- `REQUEST_CHANGES`: issues to fix before merging.
+- `COMMENT`: minor items; can merge but note the feedback.
 
 ## Scope
 
-- **DO** flag missing `Fixes #<N>` lines
-- **DO** flag obvious problems the human reviewer at the gate might have missed
-- **DO NOT** redesign the approach — that was settled at `plan-approval` and validated at `dev-approval`
-- **DO NOT** demand changes the human reviewer already accepted at the `dev-approval` gate (the human ran the code and approved it; you didn't)
-- **DO NOT** flag the syntax of `git diff` examples that appear in review-file prose (e.g., `git diff ci..HEAD` inside a "Files Changed" caption or "How to Test Locally" section). Quoted diff syntax is documentation, not a command. Apply two-dot/three-dot scrutiny only to diffs you compute yourself.
-
-## Notes
-
-- The human at the `dev-approval` gate is the primary reviewer for behavior; you are the secondary reviewer for hygiene and edge cases
-- Focus on "what would an integration reviewer catch that the gate reviewer missed"
-- If referencing line numbers, use `file:line` format
+Flag a missing `Fixes #<N>` and obvious problems the gate reviewer might have missed. Do **not** redesign the approach (settled at `plan-approval`, validated at `dev-approval`), demand changes the human already accepted at `dev-approval` (they ran the code; you didn't), or flag the syntax of `git diff` examples in review-file prose — quoted diff syntax is documentation, not a command; apply two-dot/three-dot scrutiny only to diffs you compute yourself. You are the secondary reviewer for hygiene and edge cases: "what would an integration reviewer catch that the gate reviewer missed".

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

@@ -61,7 +61,7 @@ Follow the plan's "Files to Change" section. Apply the changes.
 [PIR #{{issue.number}}] <Concise description of this commit's change>
 ```
 
-**Never use `git add .` or `git add -A`.** Stage files explicitly:
+Stage files explicitly:
 
 ```bash
 git add path/to/changed-file.ts
@@ -140,10 +140,9 @@ Then **stay in the interactive session**. Do not exit. Wait for the user's next
 
 - **Don't write `codev/reviews/<id>-<slug>.md` in this phase** — it's the next phase's artifact, with a different shape (retrospective with arch + lessons updates)
 - Don't add features not in the plan — scope creep is a `BLOCKED` signal, not a free expansion
-- Don't run `porch approve` yourself
+- Don't run `porch approve` on your own initiative — only when the architect relays the human's approval
 - Don't push to the default branch — only to your builder branch
 - Don't squash commits — let the merge commit preserve history
-- Don't use `git add .` or `git add -A`
 - Don't open the PR yet — that's the `review` phase
 - Don't exit the interactive session at the gate
 

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

@@ -87,8 +87,6 @@ git commit -m "[PIR #{{issue.number}}] Plan draft"
 git push -u origin "$(git branch --show-current)"
 ```
 
-**Never use `git add .` or `git add -A`.**
-
 ### 5. Signal Phase Complete
 
 ```bash
@@ -116,9 +114,8 @@ Then **stay in the interactive session**. Do not exit. Wait for the user's next
 ## What NOT to Do
 
 - Don't write code — that's the implement phase
-- Don't run `porch approve` yourself — only the human can approve the gate
+- Don't run `porch approve` on your own initiative — only when the architect relays the human's approval
 - Don't post the plan content as a GitHub issue comment — the plan lives in the file, not the issue thread. A one-line pointer comment on the issue is fine if you think it helps the discussion.
-- Don't use `git add .` or `git add -A`
 - Don't exit the interactive session at the gate
 
 ## Handling Feedback

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

@@ -238,9 +238,9 @@ Together with the `--pr` record from step 4a and the `--merged` record from step
 
 ## What NOT to Do
 
-- **Don't merge before the `pr` gate is approved.** A consultation APPROVE verdict 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 merge before the `pr` gate is approved** (steps 8–9). Neither a consultation APPROVE verdict nor user-in-pane prose ("looks good", "lgtm", "merge it") authorizes `gh pr merge` — only porch reporting `gate_status: approved` for the `pr` gate does.
 - 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 run `porch approve` for any gate on your own initiative — only when the architect relays the human's approval
 - Don't push to the default branch — 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 the consultation to run twice.

package/skeleton/protocols/pir/protocol.md

@@ -1,202 +1,79 @@
 # 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).
+Plan → Implement → Review, driven by a GitHub issue, with **two human gates before any PR
+exists**. The issue is the implicit spec; there is no specify phase.
 
-## When to Use PIR
+Choose PIR when either is true:
 
-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:
+- **The approach needs review before coding.** Ambiguous root cause, unfamiliar or
+  high-blast-radius area, or a design-sensitive change — cheaper to redirect at plan time than
+  at PR time.
+- **The implementation must be exercised running, before a PR exists.** Mobile, UI/UX,
+  hardware-adjacent behaviour, OAuth or payment integrations, full user journeys, anything
+  performance-sensitive. A diff cannot show you these; a running worktree can.
 
-### 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
+Lighter than SPIR (no spec phase, one consult at the PR). Stronger than BUGFIX/AIR (two human
+gates *before* a PR, where the human reviews the running code rather than the diff).
 
-### 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** (spawns `afx dev <builder-id>` via Tower)
-- CLI: `afx dev <builder-id>`
-
-The dev process 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** 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. Routes new facts/wisdom by tier (Spec 987) — HOT `codev/resources/arch-critical.md` / `lessons-critical.md` (capped) or COLD `codev/resources/arch.md` / `lessons-learned.md` (reference) — 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 3-way consultation (Gemini, Codex, Claude; type=impl) as a **single advisory pass** (`max_iterations: 1`); consultation 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 review flow:
+## The state machine
 
 ```json
-{
-  "worktree": {
-    "symlinks": [".env.local", "packages/*/.env"],
-    "postSpawn": ["pnpm install --frozen-lockfile"],
-    "devCommand": "pnpm dev"
-  }
-}
+{{> protocols/pir/protocol.json}}
 ```
 
-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**: 3-way consultation (Gemini, Codex, Claude; type=impl) after the PR is opened, as a **single advisory pass** (`max_iterations: 1`). Same consult type (`impl`) as BUGFIX / AIR's PR-creation consult.
-
-The consultation at the PR is a single pass — there is **no iterate-until-APPROVE loop**. A `REQUEST_CHANGES` does not block or re-trigger it; 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 (the consultation does not re-check it).
-
-Net: PIR's distinguishing features are the two human gates (`plan-approval`, `dev-approval`), not AI-consult density.
+## Gates
 
-To disable consultation entirely, say "without multi-agent consultation" when starting work.
+Gate names are opaque strings keyed by `(project_id, gate_name)`, so sharing a name with another
+protocol is safe and needs no porch change.
 
-## Signals
+| Gate | When | What the human does |
+|---|---|---|
+| `plan-approval` | pre-PR | Reads the plan committed on the builder branch, before any code exists |
+| `dev-approval` | pre-PR | **PIR's distinctive gate** — reviews the *running* worktree via `afx dev` |
+| `pr` | post-PR | Reviews on GitHub, then approves; porch wakes the builder to merge |
 
-PIR uses the standard porch signal vocabulary:
+The `pr` gate holds the merge behind porch state: the human approves, the architect relays that
+approval, and the builder records it with `porch approve pr` before porch hands over the merge task.
 
-```
-<signal>PHASE_COMPLETE</signal>          # Current phase build complete
-<signal>BLOCKED:reason</signal>          # Cannot proceed
-```
+**Gates do not notify the architect automatically.** Porch broadcasts `overview-changed` over
+SSE; the VSCode Builders tree renders the blocked state with a bell and raises a toast. CLI
+users see it via the builder pane or `porch pending`. The builder's job at any gate is: write
+the artifact, commit, signal, wait — then run `porch approve` when the architect relays the human's
+approval, never on your own initiative.
 
-Signals are informational for log readability. The state machine is driven by `porch done` and `porch next` CLI calls inside the builder turn.
+## Rejection is iteration, not a command
 
-## Commit Messages
+There is no `porch reject`. Feedback arrives however is convenient — editing the plan file,
+typing in the builder pane, `afx send`, an issue comment — the builder revises and recommits,
+and **the gate stays pending until a human approves it**. The same pattern works at both
+pre-PR gates.
 
-Commits during PIR phases use the issue-driven format:
+## Artifacts
 
-```
-[PIR #<N>] Plan draft
-[PIR #<N>] Implement avatar masking
-[PIR #<N>] Add Android-side regression test
-```
+Plan and review live in `codev/plans/` and `codev/reviews/` on the builder branch and ship to
+the default branch with the merge. The review is shaped like SPIR's (Summary, Architecture
+Updates, Lessons Learned) so `codev/reviews/` stays semantically consistent across protocols.
 
-The PR title follows the project's existing PR convention.
+## Consultation
 
-## Branch Naming
+**One advisory CMAP pass at the PR** (`max_iterations: 1`) — no iterate-until-APPROVE loop. A
+`REQUEST_CHANGES` escalates to the human at the `pr` gate rather than triggering an automatic
+re-review.
 
-```
-builder/pir-<issue-number>
-```
+That footprint is a **design invariant, and it is fragile**: porch resolves models as
+*config > protocol*, so a project-wide `porch.consultation.models` (say a SPIR-tuned 3-model
+list) silently inflates PIR's cost. Leave it unset, or scope it per-protocol.
 
-Example: `builder/pir-842` for a PIR spawn against GitHub issue #842.
+## Builder session
 
-## File Locations
+A long-running interactive session in a Tower-managed PTY, launched as `claude "<prompt>"`
+inside a restart loop and pinned to a session id minted at spawn. Typed input reaches the live
+session immediately; the loop is crash recovery, not the gate-wait mechanism. There is no
+"session ended at gate" state. On a crash the loop **resumes the pinned conversation** (context
+intact, plus a re-orientation nudge) rather than replaying the spawn prompt; only an unresumable
+session degrades to a fresh prompt-replay relaunch. A deliberate quit relaunches fresh.
 
-```
-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
-```
+## Configuration
 
-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.
+The `worktree` block in `.codev/config.json` is what makes the `dev-approval` gate work — see
+the `runnable-worktrees` skill for `symlinks`, `postSpawn` and `devCommand`.

package/skeleton/protocols/research/builder-prompt.md

@@ -1,91 +1,60 @@
 # {{protocol_name}} Builder ({{mode}} mode)
 
-You are conducting multi-agent research.
+You are implementing {{input_description}}.
 
 {{#if mode_soft}}
 ## Mode: SOFT
-You are running in SOFT mode. This means:
-- You follow the RESEARCH protocol yourself (no porch orchestration)
-- The architect monitors your work and verifies you're adhering to the protocol
-- Use `consult` for the 3-way investigation and critique phases
+
+You follow the protocol yourself; the architect verifies compliance.
 {{/if}}
 
 {{#if mode_strict}}
 ## Mode: STRICT
-You are running in STRICT mode. This means:
-- Porch orchestrates your work
-- Run: `porch next` to get your next tasks
-- Follow porch signals and gate approvals
-
-### ABSOLUTE RESTRICTIONS (STRICT MODE)
-- **NEVER edit `status.yaml` directly** — only porch commands may modify project state
-- **NEVER call `porch approve` without explicit human approval** — only run it after the architect says to
-- **NEVER skip the 3-way consultation** — always follow porch next → porch done cycle
+
+Porch orchestrates. `porch next` gives you tasks; `porch done` signals completion. Never
+hand-edit `status.yaml` — only porch commands modify project state.
 {{/if}}
 
 ## Protocol
-Follow the RESEARCH protocol. Read and internalize the protocol before starting any work. The full protocol text is included below under **## Protocol Reference (full text)**.
 
-## RESEARCH Overview
+The full protocol text is inlined below under **## Protocol Reference (full text)** — you do not
+need to fetch it.
 
-The RESEARCH protocol produces a high-confidence research report through triangulation:
+## Research Topic
 
-1. **Scope** — Define the precise question, scope, and acceptance criteria. Write a research brief. Gate: architect approval before proceeding.
-2. **Investigate** — Dispatch the brief to 3 models (Gemini, Codex, Claude) in parallel. Each investigates independently. No anchoring — they don't see each other's work.
-3. **Synthesize** — Read all 3 reports. Identify consensus, disagreements, and unique contributions. Write a single synthesis report organized by topic (not by model).
-4. **Critique** — Send the synthesis back to all 3 models for critique. Incorporate valid feedback. Document rejected critique. Finalize the report.
+{{task_text}}
 
-## Output Location
+## Output
 
-All artifacts go to `codev/research/`:
-- `<topic>-brief.md` — the scoped question (Phase 1)
-- `<topic>-gemini.md`, `<topic>-codex.md`, `<topic>-claude.md` — individual investigations (Phase 2)
-- `<topic>.md` — the final synthesis report (Phase 3+4, this is the deliverable)
-- `<topic>-critique-rebuttals.md` — critique responses (Phase 4)
-
-{{#if task}}
-## Research Topic
-{{task_text}}
-{{/if}}
+`codev/research/<topic>.md`
 
 ## Key Principles
 
-- **Triangulate**: consensus across 3 models > any single model's claim
-- **Cite sources**: tell investigators to provide sources where possible
-- **Be candid about uncertainty**: "I don't know" > confabulation
-- **Organize by topic, not by model**: the synthesis is a standalone document
-- **Note surprises**: the most valuable findings are often unexpected
-- **Keep it concise**: the synthesis should be shorter than the sum of the investigations
-
-## Using consult for 3-way Investigation
+- **Triangulate**: consensus across three models beats any single model's claim
+- **Cite sources**; be candid about uncertainty — "I don't know" beats confabulation
+- **Organize by topic, not by model** — the synthesis is a standalone document
+- **Note surprises**: the most valuable findings are usually the unexpected ones
+- **Preserve disagreement**: smoothing over conflict destroys the signal that made a 3-way
+  investigation worth running
+- Keep the synthesis shorter than the sum of its investigations
 
-For the investigate phase, use the `consult` CLI to dispatch to each model:
+## Dispatching the investigation
 
 ```bash
-# Phase 2: parallel investigation
+# investigate — parallel, independent
 consult -m gemini --prompt-file codev/research/<topic>-brief.md --output codev/research/<topic>-gemini.md &
-consult -m codex --prompt-file codev/research/<topic>-brief.md --output codev/research/<topic>-codex.md &
+consult -m codex  --prompt-file codev/research/<topic>-brief.md --output codev/research/<topic>-codex.md &
 consult -m claude --prompt-file codev/research/<topic>-brief.md --output codev/research/<topic>-claude.md &
 wait
-```
 
-For the critique phase:
-```bash
-# Phase 4: parallel critique
+# critique — same shape, pointed at the synthesis
 consult -m gemini --prompt "Critique this research synthesis for gaps, errors, and bias:" --prompt-file codev/research/<topic>.md --output codev/research/<topic>-critique-gemini.md &
-consult -m codex --prompt "Critique this research synthesis for gaps, errors, and bias:" --prompt-file codev/research/<topic>.md --output codev/research/<topic>-critique-codex.md &
+consult -m codex  --prompt "Critique this research synthesis for gaps, errors, and bias:" --prompt-file codev/research/<topic>.md --output codev/research/<topic>-critique-codex.md &
 consult -m claude --prompt "Critique this research synthesis for gaps, errors, and bias:" --prompt-file codev/research/<topic>.md --output codev/research/<topic>-critique-claude.md &
 wait
 ```
 
-## Getting Started
-1. Read the RESEARCH protocol document
-2. Understand the research question from the architect
-3. Write the research brief (Phase 1)
-4. Wait for scope-approval before proceeding to investigation
-
----
-
-## Protocol Reference (full text)
+## Notifications
 
-{{protocol_reference}}
+The architect is not watching. `afx send architect "..."` at each of: gate reached, PR ready, PR
+merged, blocked.