@cluesmith/codev 3.0.3 → 3.0.6

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

@@ -30,6 +30,12 @@ You are running in STRICT mode. This means:
 Follow the ASPIR protocol: `codev/protocols/aspir/protocol.md`
 Read and internalize the protocol before starting any work.
 
+## Baked Decisions
+
+If the issue body contains a section named "Baked Decisions" (any heading level, case-insensitive), treat its contents as fixed architectural decisions baked in by the architect. Do not autonomously override them in your spec, plan, or implementation. If you discover a serious reason to question a baked decision, surface that concern to the architect via `afx send` rather than relitigating it inside the spec/plan/review.
+
+If the architect's baked-decisions section contains internal contradictions (e.g., two different language choices), do not pick one — pause, flag the contradiction to the architect via `afx send`, and wait for resolution before proceeding.
+
 {{#if spec}}
 ## Spec
 Read the specification at: `{{spec.path}}`
@@ -53,13 +59,23 @@ Follow the implementation plan at: `{{plan.path}}`
 {{task_text}}
 {{/if}}
 
-## Multi-PR Workflow
+## PR Strategy
+
+**Do not autonomously open a PR per implementation phase.** Plan phases ship as git commits within a single PR, not as separate PRs. The plan's instruction that "each phase commits independently" refers to git commits, not PRs.
+
+By default, the PR is opened during/after the final implement phase, with all phase-commits already on the branch.
+
+### Architect-requested PRs
+
+The architect MAY request a PR at any point — for spec review, mid-implementation feedback, slicing a large spec into shippable PRs, etc. When the architect explicitly asks for a PR earlier (or for additional PRs), follow that direction. The prohibition is specifically on the *builder* autonomously deciding to open per-phase PRs without architect request.
+
+### Multi-PR Mechanics (when the architect requests sequential PRs)
 
-Your worktree is persistent — it survives across PR merges. You can produce multiple PRs sequentially:
+Your worktree is persistent — it survives across PR merges. When the architect asks for sequential PRs (e.g., to slice a large spec into shippable pieces), use this loop:
 
 1. Cut a branch, open a PR, wait for merge
 2. After merge: `git fetch origin main && git checkout -b <next-branch> origin/main`
-3. Continue to the next phase, open another PR
+3. Continue to the next slice, open another PR
 
 **Important**: Do NOT run `git checkout main` — git worktrees cannot check out a branch that's checked out elsewhere. Always branch off `origin/main` via fetch.
 

package/skeleton/protocols/aspir/consult-types/plan-review.md

@@ -3,6 +3,12 @@
 ## Context
 You are reviewing an implementation plan during the Plan phase. The spec has been approved - now you must evaluate whether the plan adequately describes HOW to implement it.
 
+## Baked Decisions
+
+If the issue body or the approved spec's Constraints section includes content under a "Baked Decisions" heading, the architect has marked those choices as fixed (this extends the existing "don't re-litigate spec decisions" rule with explicit baked-decision language). Do not autonomously challenge them: do not propose alternative languages, frameworks, deployment shapes, or dependencies that contradict a baked decision. You may `COMMENT` with concerns; reserve `REQUEST_CHANGES` for the case where the plan **fails to honor** a stated baked decision — that is a real defect.
+
+If the baked decisions themselves contain contradictions, do not pick one — `REQUEST_CHANGES` and ask the architect to clarify before proceeding.
+
 ## Focus Areas
 
 1. **Spec Coverage**

package/skeleton/protocols/aspir/consult-types/spec-review.md

@@ -3,6 +3,12 @@
 ## Context
 You are reviewing a feature specification during the Specify phase. Your role is to ensure the spec is complete, correct, and feasible before it moves to human approval.
 
+## Baked Decisions
+
+If the issue body or the spec's Constraints section includes content under a "Baked Decisions" heading, the architect has marked those choices as fixed. Do not autonomously challenge them: do not propose alternative languages, frameworks, deployment shapes, or dependencies that contradict a baked decision. You may `COMMENT` with concerns about a baked decision (the architect decides whether to rescind it); reserve `REQUEST_CHANGES` for the case where the spec **fails to honor** a stated baked decision — that is a real defect.
+
+If the baked decisions themselves contain contradictions (e.g., two different language choices), do not pick one — `REQUEST_CHANGES` and ask the architect to clarify before proceeding.
+
 ## Focus Areas
 
 1. **Completeness**

package/skeleton/protocols/aspir/prompts/specify.md

@@ -31,6 +31,12 @@ ls codev/specs/{{project_id}}-*.md
 
 **If no spec exists:** Proceed to Step 1 below.
 
+### 0.5 Baked Decisions
+
+Before exploring solution approaches, check the issue body for a section named "Baked Decisions" (any heading level, case-insensitive). If present, copy its content verbatim into the spec's Constraints section and treat each item as fixed. Do not autonomously relitigate the architect's choices in your Solution Exploration. If you discover a serious problem with a baked decision, raise it via `afx send architect` rather than overriding it in the spec.
+
+If two baked decisions contradict each other (e.g., two different language choices), do not pick one — pause, flag the contradiction via `afx send`, and wait for resolution before drafting.
+
 ### 1. Clarifying Questions (ONLY IF NO SPEC EXISTS)
 
 Before writing anything, ask clarifying questions to understand:

package/skeleton/protocols/aspir/protocol.md

@@ -41,6 +41,10 @@ Use SPIR instead when:
 - The work is **high-risk** — security-sensitive, user-facing, or broadly impactful
 - You want to **review and adjust** the plan before implementation starts
 
+## Baked Decisions (Optional)
+
+When filing an issue for ASPIR, you can pin architectural decisions you don't want the builder or CMAP reviewers to re-litigate. Include a `## Baked Decisions` section (any heading level is fine) anywhere in the issue body. Useful categories: language, framework, deployment shape, key dependencies, decisions deferred to a later spec. The builder will copy the section verbatim into the spec's Constraints and treat each item as fixed; CMAP reviewers will not propose alternatives unless the spec itself fails to honor a stated decision. Leave the section out for issues where you want the builder to explore freely — absence is the no-op default. You can amend or rescind a baked decision at any time by updating the issue and respawning, or by sending the builder a direct instruction via `afx send`.
+
 ## Protocol Phases
 
 ASPIR follows the same four phases as SPIR. For full phase documentation, see the [SPIR protocol](../spir/protocol.md).

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

@@ -1,38 +1,54 @@
-# Implementation Review Prompt
+# Implementation Review Prompt (BUGFIX)
 
 ## Context
-You are reviewing implementation work during the Implement phase. A builder has completed a plan phase and needs feedback before proceeding. Your job is to verify the implementation matches the spec and plan.
+You are reviewing in-progress fix work for a **BUGFIX protocol** project. A builder has investigated a GitHub Issue, identified a root cause, and is implementing the fix + regression test. Your job is to verify the fix matches the issue's symptom and meets BUGFIX standards.
+
+**BUGFIX is not SPIR.** There is **no spec, no plan, and no review document**. The GitHub Issue is the spec. The PR body will be the review. Do **not** request changes for missing `codev/specs/`, `codev/plans/`, or `codev/reviews/` artifacts.
 
 ## CRITICAL: 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
+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.
 
 ## Focus Areas
 
-1. **Spec Adherence**
-   - Does the implementation fulfill the spec requirements for this phase?
-   - Are acceptance criteria met?
+1. **Issue Adherence**
+   - Does the implementation actually resolve the symptom described in the GitHub Issue?
+   - Is the root cause fix targeted, or is it a workaround that masks the symptom?
+
+2. **Regression Test**
+   - Is there a regression test that exercises the exact scenario from the issue?
+   - Without the fix applied, would this test fail? (The whole point.)
+   - Is the test deterministic?
+   - If no test was added, has the builder justified why (e.g., docs-only change with no testable behavior)?
+
+3. **Scope Discipline**
+   - Is the change focused on the root cause only — no unrelated refactors, no drive-by fixes?
+   - Is the net diff staying under ~300 LOC? If it has grown larger, should this escalate to SPIR/TICK?
 
-2. **Code Quality**
+4. **Code Quality**
    - Is the code readable and maintainable?
-   - Are there obvious bugs or issues?
-   - Are error cases handled appropriately?
+   - Are there obvious bugs or issues introduced by the fix?
+   - Are error cases handled appropriately for the path that was changed?
+   - No debug code, stray `console.log`, or commented-out code.
 
-3. **Test Coverage**
-   - Are the tests adequate for this phase?
-   - Do tests cover the main paths AND edge cases?
+5. **Test Status**
+   - Existing tests still pass.
+   - Build still passes.
+   - No new flaky tests introduced.
 
-4. **Plan Alignment**
-   - Does the implementation follow the plan?
-   - Are there plan items skipped or partially completed?
+## Out of Scope (Do NOT request changes for)
 
-5. **UX Verification** (if spec has UX requirements)
-   - Does the actual user experience match what the spec describes?
-   - If spec says "async" or "non-blocking", is it actually async?
+The following are **not** part of the BUGFIX protocol and must **not** be cited as REQUEST_CHANGES reasons:
+
+- Missing `codev/specs/<N>-*.md`, `codev/plans/<N>-*.md`, or `codev/reviews/<N>-*.md` — BUGFIX produces none of these. The GitHub Issue is the spec; the PR body is the review.
+- Commit format `[Spec NNNN][Phase]` — BUGFIX uses `Fix #N: ...` or `[Bugfix #N] ...`. This is the protocol-mandated format, **not** a bug.
+- `status.yaml` fields such as `build_complete: false` — porch manages `status.yaml`; the builder is **forbidden** from editing it manually. Treat porch state as informational, not a fixable issue.
+- "Plan Alignment" or "Spec Adherence" — there is no plan and no spec to align with.
+- Phase-scoping concerns — BUGFIX is single-phase by design. There are no plan phases to scope against.
 
 ## Verdict Format
 
@@ -51,22 +67,13 @@ KEY_ISSUES:
 ```
 
 **Verdict meanings:**
-- `APPROVE`: Phase is complete, builder can proceed
-- `REQUEST_CHANGES`: Issues that must be fixed before proceeding
-- `COMMENT`: Minor suggestions, can proceed but note feedback
-
-## Scoping (Multi-Phase Plans)
-
-When the implementation plan has multiple phases (e.g., scaffolding, landing, media_rtl):
-- **ONLY review work belonging to the current plan phase**
-- The query will specify which phase you are reviewing
-- Do NOT request changes for functionality scheduled in later phases
-- Do NOT flag missing features that are out of scope for this phase
-- If unsure whether something belongs to this phase, check the plan file
+- `APPROVE`: Fix and regression test are in good shape; builder can proceed to PR creation.
+- `REQUEST_CHANGES`: Real BUGFIX-relevant issues (fix doesn't resolve the symptom, missing regression test without justification, scope creep, broken existing tests, etc.).
+- `COMMENT`: Minor suggestions; builder can proceed but should consider the feedback.
 
 ## Notes
 
-- This is a phase-level review, not the final PR review
-- Focus on "does this phase work" not "is the whole feature done"
-- If referencing line numbers, use `file:line` format
-- The builder needs actionable feedback to continue
+- This is an implementation-level review, not the final PR review.
+- Focus on "does this fix actually resolve the issue, and is it protected by a regression test" — not on artifacts from other protocols.
+- If referencing line numbers, use `file:line` format.
+- The builder needs actionable, protocol-correct feedback to continue.

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

@@ -1,36 +1,59 @@
-# PR Ready Review Prompt
+# PR Ready Review Prompt (BUGFIX)
 
 ## Context
-You are performing a final self-check during the Review phase. The builder has completed all implementation phases and is about to create a PR. This is the last check before the work goes to the architect for integration review.
+You are performing a final self-check during the PR phase of the **BUGFIX protocol**. The builder has investigated a GitHub Issue, implemented a focused fix, and added a regression test. They are about to create — or have just created — a PR for the architect's integration review.
+
+**BUGFIX is not SPIR.** Do **not** review against the SPIR three-document trinity. The artifacts of a BUGFIX project are:
+- The originating **GitHub Issue** (serves as the spec)
+- The **code fix** (minimal, focused on root cause)
+- A **regression test** that fails without the fix and passes with it
+- The **PR body** (Summary, Root Cause, Fix, Test Plan)
+
+There is **no `codev/specs/`, `codev/plans/`, or `codev/reviews/` file** for a BUGFIX, and there should not be one. The commit format is `Fix #NNNN: <description>` (or `[Bugfix #NNNN] ...`), **not** `[Spec NNNN][Phase]`.
 
 ## Focus Areas
 
-1. **Completeness**
-   - Are all spec requirements implemented?
-   - Are all plan phases complete?
-   - Is the review document written (`codev/reviews/XXXX-name.md`)?
-   - Are all commits properly formatted (`[Spec XXXX][Phase]`)?
-
-2. **Test Status**
-   - Do all tests pass?
-   - Is test coverage adequate for the changes?
-   - Are there any skipped or flaky tests?
-
-3. **Code Cleanliness**
-   - Is there any debug code left in?
-   - Are there any TODO comments that should be resolved?
-   - Are there any `// REVIEW:` comments that weren't addressed?
-   - Is the code properly formatted?
-
-4. **Documentation**
-   - Are inline comments clear where needed?
-   - Is the review document comprehensive?
-   - Are any new APIs documented?
-
-5. **PR Readiness**
-   - Is the branch up to date with main?
-   - Are commits atomic and well-described?
-   - Is the change diff reasonable in size?
+1. **Issue Resolution**
+   - Does the fix actually resolve the symptom described in the issue?
+   - Does the PR body include `Fixes #<N>` so the issue auto-closes on merge?
+   - Does the PR description cover: Summary, Root Cause, Fix, Test Plan?
+
+2. **Regression Test**
+   - Is there a regression test that targets the exact scenario from the issue?
+   - Would the test fail without the fix? (If reviewers can't tell, ask the builder to demonstrate.)
+   - Is the test deterministic (not flaky)?
+   - If the fix is documentation-only or otherwise truly untestable, has the builder explicitly justified the absence of a test?
+
+3. **Scope Discipline**
+   - Is the change focused on the root cause? No unrelated refactors, no drive-by fixes for other bugs.
+   - Is the net diff under ~300 LOC (additions + deletions, excluding generated/lockfiles)?
+   - If the scope grew beyond a bugfix, should the builder have escalated to SPIR/TICK instead?
+
+4. **Code Cleanliness**
+   - No debug code, `console.log`, or commented-out blocks left behind.
+   - No stray TODOs introduced by this fix.
+   - Code follows existing project conventions.
+
+5. **Test Status**
+   - All existing tests pass.
+   - Build passes.
+   - No new flaky tests introduced.
+
+6. **PR Hygiene**
+   - Commits use the BUGFIX format: `Fix #<N>: ...` or `[Bugfix #<N>] ...` (**not** `[Spec NNNN][Phase]`).
+   - Branch is up to date with main (or close enough for clean merge).
+   - PR is linked to the issue.
+
+## Out of Scope (Do NOT request changes for)
+
+The following are **not** part of the BUGFIX protocol and must **not** be cited as REQUEST_CHANGES reasons:
+
+- Missing `codev/specs/<N>-*.md` — BUGFIX has no spec; the GitHub Issue is the spec.
+- Missing `codev/plans/<N>-*.md` — BUGFIX has no plan.
+- Missing `codev/reviews/<N>-*.md` — BUGFIX has no review document; review lives in the PR body.
+- Commit format `[Spec NNNN][Phase]` — BUGFIX intentionally uses `Fix #N:` / `[Bugfix #N]`.
+- `status.yaml` fields like `build_complete: false` — porch manages `status.yaml`; the builder is **forbidden** from editing it directly. Treat porch state as informational, not a fixable issue.
+- Phase-scoping concerns — BUGFIX is a single-phase protocol; there are no plan phases to scope against.
 
 ## Verdict Format
 
@@ -49,24 +72,26 @@ KEY_ISSUES:
 
 PR_SUMMARY: |
   ## Summary
-  [2-3 sentences describing what this PR does]
+  Fixes #<N>. [1-2 sentences on what was fixed.]
+
+  ## Root Cause
+  [Brief explanation of what caused the bug]
 
-  ## Key Changes
-  - [Change 1]
-  - [Change 2]
+  ## Fix
+  [Brief explanation of the fix]
 
   ## Test Plan
-  - [How to test]
+  - [Regression test description]
+  - [Manual verification, if applicable]
 ```
 
 **Verdict meanings:**
-- `APPROVE`: Ready to create PR
-- `REQUEST_CHANGES`: Issues to fix before PR creation
-- `COMMENT`: Minor items, can create PR but note feedback
+- `APPROVE`: Bug is resolved, regression test is in place, PR is ready for architect review.
+- `REQUEST_CHANGES`: Real BUGFIX-relevant issues to fix (missing regression test, fix doesn't resolve the symptom, scope creep, etc.).
+- `COMMENT`: Minor items, can proceed but note feedback.
 
 ## Notes
 
-- This is the builder's final self-review before hand-off
-- The PR_SUMMARY in your output can be used as the PR description
-- Focus on "is this ready for someone else to review" not "is this perfect"
-- Any issues found here are cheaper to fix than during integration review
+- This is the builder's final self-review before hand-off to the architect.
+- The `PR_SUMMARY` block can be used directly as the PR description.
+- Focus on "is this bug actually fixed and protected by a test" — not on artifacts from other protocols.

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

@@ -0,0 +1,92 @@
+# {{protocol_name}} Builder ({{mode}} mode)
+
+You are implementing a fix or feature driven by a GitHub issue, using the PIR protocol.
+
+{{#if mode_soft}}
+## Mode: SOFT
+You are running in SOFT mode. This means:
+- You follow the PIR protocol document yourself (no porch orchestration)
+- The architect monitors your work and verifies you're adhering to the protocol
+- Run consultations manually when the protocol calls for them
+- You have flexibility in execution, but must stay compliant with the protocol
+{{/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
+- Do not deviate from the porch-driven workflow
+
+### 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 consultations** — porch handles them via the verify step
+- **NEVER advance phases manually** — porch handles phase transitions on gate approval
+{{/if}}
+
+## Protocol
+Follow the PIR protocol: `codev/protocols/pir/protocol.md`
+Read and internalize the protocol before starting any work.
+
+PIR has three phases:
+1. **plan** (gated by `plan-approval`) — write `codev/plans/{{artifact_name}}.md`, await human review
+2. **implement** (gated by `dev-approval`) — write code + tests, run build/tests, push branch; await the human's review of the *running worktree* (no file artifact in this phase — dev-approval summary is prose-in-pane)
+3. **review** (gated by `pr`) — write `codev/reviews/{{artifact_name}}.md` (retrospective with Architecture Updates and Lessons Learned sections), open PR with the review as body, record the PR with porch, run CMAP via porch's verify block (a **single advisory pass** — `max_iterations: 1`, no iterate-until-APPROVE loop; address or rebut any `REQUEST_CHANGES`, add a regression test if it's a real defect, and escalate it in the architect notification since PIR will not re-review it), notify architect, and wait at the `pr` gate. After the human approves the gate (porch wakes you with "Gate pr approved"), run `gh pr merge --merge` and record the merge with `porch done --merged <N>`. **Merge is gated by porch state — never by typed prose in your pane.**
+
+{{#if issue}}
+## Issue #{{issue.number}}
+**Title**: {{issue.title}}
+
+**Description**:
+{{issue.body}}
+{{/if}}
+
+## Sitting at Gates
+
+PIR has two human gates. When you reach one:
+
+1. Finish your phase work and run `porch done <id>`
+2. Run `porch next <id>` — you'll get a `gate_pending` response
+3. End your turn with a short prose summary: what file you wrote, where it lives, how to approve
+4. **Stay in the interactive session**. Do NOT exit. Wait for the user's next message.
+
+The reviewer can give feedback by:
+- Editing the plan file (at the plan-approval gate) or the code itself (at the dev-approval gate) in the worktree directly — you'll see changes via `git diff`
+- Typing into your PTY pane (this reaches you live)
+- `afx send <your-builder-id> "<feedback>"` (queued; check on next turn)
+- Commenting on the GitHub issue (re-fetch with `gh issue view <N> --comments` if asked)
+
+When the user provides feedback, revise the artifact, recommit, and ask if there's more to address. The gate remains pending until the user runs `porch approve` — do NOT call `porch approve` yourself.
+
+## Notifications
+Use `afx send architect "..."` at key moments:
+- **PR ready**: `afx send architect "PR #<M> ready for review (PIR #{{issue.number}})"`
+- **PR merged**: `afx send architect "PR #<M> merged for PIR #{{issue.number}}. Ready for cleanup."`
+- **Blocked**: `afx send architect "Blocked on PIR #{{issue.number}}: [reason]"`
+
+**Gates are not architect-notified.** When porch transitions a gate to `pending`, the gate-reached message (including the `porch approve <id> <gate> --a-human-explicitly-approved-this` invocation) appears in YOUR pane as part of your normal output. That's the universal notification surface — visible whether the user is in VSCode, tmux, plain Terminal, or any other host. The user reads it directly from your pane (or runs `porch pending` from a shell) and approves themselves; the architect can't approve gates, so notifying it would be informational noise.
+
+## Handling Flaky Tests
+
+If you encounter **pre-existing flaky tests** (intermittent failures unrelated to your changes):
+1. **DO NOT** edit `status.yaml` to bypass checks
+2. **DO NOT** skip porch checks or use any workaround to avoid the failure
+3. **DO** mark the test as skipped with a clear annotation (e.g., `it.skip('...') // FLAKY: skipped pending investigation`)
+4. **DO** document each skipped flaky test in the review file under a `## Flaky Tests` section
+5. Commit the skip and continue with your work
+
+## Resumption After Crash
+
+If your Claude session crashes mid-flow, Tower's `while true` loop will relaunch you with the same prompt. On startup:
+
+1. Run `porch next {{project_id}}` to learn what phase you're in
+2. If `gate_pending`: read the latest plan file (plan-approval) or `git diff main` (dev-approval) plus any new GitHub issue comments; check `afx send` queue. Decide whether to revise or just announce you're back.
+3. Otherwise: pick up where you left off
+
+## Getting Started
+
+1. Read the PIR protocol document (`codev/protocols/pir/protocol.md`)
+2. Run `porch next {{project_id}}` to see what to do next
+3. Begin work

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

@@ -0,0 +1,78 @@
+# Implementation Review Prompt (PIR)
+
+## 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.
+
+## CRITICAL: 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
+
+## 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?
+
+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?
+
+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?
+
+## Verdict Format
+
+After your review, provide your verdict in exactly this format:
+
+```
+---
+VERDICT: [APPROVE | REQUEST_CHANGES | COMMENT]
+SUMMARY: [One-line summary of your assessment]
+CONFIDENCE: [HIGH | MEDIUM | LOW]
+---
+KEY_ISSUES:
+- [Issue 1 or "None"]
+- [Issue 2]
+...
+```
+
+**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
+
+## 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

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

@@ -0,0 +1,65 @@
+# PR Review Prompt (PIR)
+
+## Context
+
+You are performing the CMAP-2 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.
+
+## 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 main? (If not, suggest a rebase.)
+   - 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
+
+## Verdict Format
+
+After your review, provide your verdict in exactly this format:
+
+```
+---
+VERDICT: [APPROVE | REQUEST_CHANGES | COMMENT]
+SUMMARY: [One-line summary of your assessment]
+CONFIDENCE: [HIGH | MEDIUM | LOW]
+---
+KEY_ISSUES:
+- [Issue 1 or "None"]
+- [Issue 2]
+...
+```
+
+**Verdict meanings:**
+- `APPROVE`: Ready to merge
+- `REQUEST_CHANGES`: Issues to fix before merging
+- `COMMENT`: Minor items, can merge but note 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)
+
+## 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