@cluesmith/codev 3.0.3 → 3.0.6

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

@@ -0,0 +1,156 @@
+# IMPLEMENT Phase Prompt
+
+You are executing the **IMPLEMENT** phase of the PIR protocol.
+
+## Your Goal
+
+Implement the approved plan, write tests, and pause at the `dev-approval` gate so the human can verify behavior by running the worktree locally. No file artifact is produced in this phase — the retrospective (review file) is written in the next phase, after the human has approved the running code.
+
+## Context
+
+- **Project ID**: {{project_id}}
+- **Issue Number**: #{{issue.number}}
+- **Issue Title**: {{issue.title}}
+- **Plan File**: `codev/plans/{{artifact_name}}.md` (already approved)
+
+## Resumption Check (do this FIRST)
+
+Run `porch next {{project_id}}`. If the response is `gate_pending` on `dev-approval`, the code is already written and you're awaiting review. In that case:
+
+1. Check for feedback:
+   - `git diff main` — has the reviewer made any direct edits to your code?
+   - `gh issue view {{issue.number}} --comments`
+   - `afx send` queue messages
+2. If feedback requires code changes: make them, re-run build + tests, recommit.
+3. If feedback is a discussion question: respond and stay in the session.
+
+Otherwise (`tasks` response — first run), continue below.
+
+## Process
+
+### 1. Re-Read the Plan
+
+```bash
+cat codev/plans/{{artifact_name}}.md
+```
+
+The plan is your authoritative scope. Stick to it. If you discover the plan is wrong while implementing, stop and signal `BLOCKED` rather than silently deviating.
+
+### 2. Implement the Code
+
+Follow the plan's "Files to Change" section. Apply the changes.
+
+**Code quality standards:**
+- Self-documenting code (clear names, obvious structure)
+- No commented-out code
+- No debug prints
+- Explicit error handling
+- Follow project style guide
+
+**Commit cadence:** commit each logical unit separately. Use the format:
+
+```
+[PIR #{{issue.number}}] <Concise description of this commit's change>
+```
+
+**Never use `git add .` or `git add -A`.** Stage files explicitly:
+
+```bash
+git add path/to/changed-file.ts
+git commit -m "[PIR #{{issue.number}}] ..."
+```
+
+### 3. Write Tests
+
+The plan's "Test Plan" section lists what to verify. Write the corresponding tests:
+
+- Unit tests for new functions
+- Integration tests for cross-component flows
+- Regression tests for any bug fixes
+
+**Test quality:**
+- Test behavior, not implementation
+- Avoid overmocking — only mock external dependencies (APIs, databases, file systems)
+- Use real implementations for internal module boundaries
+
+### 4. Verify Everything Works
+
+```bash
+npm run build    # or project equivalent
+npm test         # or project equivalent
+```
+
+Both MUST pass before signaling phase complete. If a test is flaky (intermittent failure unrelated to your changes), skip it with annotation — you'll document each skipped test in the review file in the next phase.
+
+**Flaky ≠ pre-existing unrelated failure.** If the suite surfaces a *deterministic* failure your diff did not cause (e.g., a stale test broken by another team's earlier refactor, or a type error in an unrelated package), that is **out of scope** — do not fix it, skip it, or quarantine it to force a green. Note it for the review file's Lessons Learned and proceed. Porch's gate `checks` are narrow structural assertions, not a full-suite proof; making an unrelated red go green is scope creep, not diligence.
+
+### 5. Push Your Branch
+
+```bash
+git push -u origin "$(git branch --show-current)"
+```
+
+So the reviewer can pull / inspect from elsewhere if they want.
+
+### 6. Signal Phase Complete
+
+```bash
+porch done {{project_id}}
+porch next {{project_id}}
+```
+
+PIR's `implement` phase has no AI consult — the `dev-approval` gate becomes pending immediately, and the human is the sole reviewer of the running code. (CMAP-2 runs later, in the `review` phase, after the human approves the gate and the PR is opened.)
+
+### 7. End Your Turn With a Code-Review Summary (Prose, Not a File)
+
+When the gate goes pending, output a short prose summary in the pane to orient the human reviewer. This is **not** a committed file — it's a transient message to help them inspect the change. Structure:
+
+> **What changed**: 2–3 sentence summary.
+>
+> **Files**: `git diff --stat main` style list — paths and +/-.
+>
+> **Test results**: `npm run build` ✓, `npm test` ✓ (X tests, Y new).
+>
+> **Things to look at**: tricky spots, platform-specific behavior, anything you want the reviewer to focus on.
+>
+> **How to test locally**: VSCode → right-click builder → **Run Dev Server**, or `afx dev pir-{{project_id}}`. View diff via VSCode → **View Diff** (auto-detects the repo's default branch).
+>
+> Ready for review — type feedback here, or approve with `porch approve {{project_id}} dev-approval --a-human-explicitly-approved-this` (Cmd+K G in VSCode).
+
+Then **stay in the interactive session**. Do not exit. Wait for the user's next message.
+
+(Optional: if your team prefers an issue-thread record, you can also post a one-line comment on the GitHub issue pointing reviewers at the worktree branch. The summary itself stays in the pane — don't duplicate it as a committed file. That's the next phase's job, and that file will be a proper retrospective with arch + lessons updates, not a transient dev-approval note.)
+
+## Signals
+
+```
+<signal>PHASE_COMPLETE</signal>          # Implementation + tests done; dev-approval gate becomes pending
+<signal>BLOCKED:reason</signal>          # Cannot proceed
+```
+
+## What NOT to Do
+
+- **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 push to main — 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
+
+## Handling Feedback at the Gate
+
+The reviewer will run your code via `afx dev` and test it. They may:
+
+- Approve immediately → porch advances to the `review` phase
+- Type feedback in the pane / send via `afx send` / edit code in the worktree / comment on the issue
+- Ask clarifying questions about specific files or behaviors
+
+When they provide feedback:
+
+1. If it's code feedback: make the change, run build + tests, recommit
+2. If it's a discussion question: answer it in the pane
+3. Don't re-run `porch done` unless porch's `verify` block needs to re-validate — porch will tell you
+
+The gate stays pending until the human approves.

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

@@ -0,0 +1,133 @@
+# PLAN Phase Prompt
+
+You are executing the **PLAN** phase of the PIR protocol.
+
+## Your Goal
+
+Read the GitHub issue, investigate the codebase, and write a plan to `codev/plans/{{artifact_name}}.md`. The plan is reviewed by a human at the `plan-approval` gate before any code is written.
+
+## Context
+
+- **Project ID**: {{project_id}}
+- **Issue Number**: #{{issue.number}}
+- **Issue Title**: {{issue.title}}
+- **Artifact**: `codev/plans/{{artifact_name}}.md`
+
+## Resumption Check (do this FIRST)
+
+Run `porch next {{project_id}}`. If the response is `gate_pending`, you have already drafted the plan and are awaiting review. In that case:
+
+1. Read your current plan file: `cat codev/plans/{{artifact_name}}.md`
+2. Check for new feedback that may have arrived while you were idle:
+   - `git diff HEAD~1 codev/plans/{{artifact_name}}.md` — the reviewer may have edited the file directly
+   - `gh issue view {{issue.number}} --comments` — check for new comments
+   - Read any `afx send` queue messages
+3. If feedback exists, revise the plan and recommit. If not, end the turn with a short "still awaiting review" message and stay in the interactive session.
+
+Otherwise (`tasks` response — this is your first run), continue with the steps below.
+
+## Process
+
+### 1. Read the Issue
+
+```bash
+gh issue view {{issue.number}}
+```
+
+Understand what's being asked. For a bug, identify the symptom. For a feature, identify the desired outcome.
+
+### 2. Investigate the Codebase
+
+- Use Glob / Grep / Read to find the relevant code
+- For a bug: trace the failure path, identify the root cause
+- For a feature: find the existing patterns and integration points
+- Note any existing utilities, components, or conventions you should reuse
+
+### 3. Write the Plan
+
+Create `codev/plans/{{artifact_name}}.md` where `<slug>` is a short kebab-case description of the change. Use this structure:
+
+```markdown
+# PIR Plan: <Short Title>
+
+## Understanding
+
+What the issue is asking for, in your own words. For a bug, include the root cause you identified — back it up with file:line references.
+
+## Proposed Change
+
+The approach you intend to take. Be specific. If there are multiple valid approaches, pick one and explain why.
+
+## Files to Change
+
+Concrete file paths. Use `file:line` format for specific edits where possible.
+
+- `path/to/file.ts:42-55` — what changes
+- `path/to/new-file.ts` — new file, what it does
+
+## Risks & Alternatives Considered
+
+- Risk: what could go wrong; mitigation
+- Alternative: <other approach>; why rejected
+
+## Test Plan
+
+How to verify this works once implemented. The reviewer will use this at the `dev-approval` gate to test the running worktree.
+
+- Unit test: <what to test>
+- Manual: <what to click / observe>
+- Cross-platform: <if applicable — what to verify on iOS / Android / web>
+```
+
+### 4. Commit and Push
+
+```bash
+git add codev/plans/{{artifact_name}}.md
+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
+porch done {{project_id}}
+porch next {{project_id}}
+```
+
+`porch next` will respond with `gate_pending` on the `plan-approval` gate. Porch automatically notifies the architect.
+
+### 6. End Your Turn With a Prose Summary
+
+Output something like:
+
+> Plan written to `codev/plans/{{artifact_name}}.md` and committed. Ready for review — type any feedback here, edit the plan file directly in VSCode, or approve with `porch approve {{project_id}} plan-approval --a-human-explicitly-approved-this` (Cmd+K G in VSCode).
+
+Then **stay in the interactive session**. Do not exit. Wait for the user's next message.
+
+## Signals
+
+```
+<signal>PHASE_COMPLETE</signal>          # Plan drafted (informational; the real signal is porch done)
+<signal>BLOCKED:reason</signal>          # Cannot proceed
+```
+
+## 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 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
+
+When the reviewer provides feedback (typed in pane, file-edit, `afx send`, or issue comment):
+
+1. Re-read the plan file (the user may have edited it)
+2. Apply the requested changes to your plan
+3. Recommit: `git add codev/plans/{{artifact_name}}.md && git commit -m "[PIR #{{issue.number}}] Plan revised"`
+4. Push
+5. Output a short "Revised — see commit X" message
+6. Wait for next input — the gate remains pending until the human approves

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
+    }
+  }
+}