@cluesmith/codev 3.2.3 → 3.3.0

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

@@ -4,28 +4,21 @@ You are implementing {{input_description}}.
 
 {{#if mode_soft}}
 ## Mode: SOFT
-You are running in SOFT mode. This means:
-- You follow the BUGFIX protocol 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
+
+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 review** — 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 BUGFIX protocol. Read and internalize the protocol before starting any work. The full protocol text is included below under **## Protocol Reference (full text)**.
+
+The full protocol text is inlined below under **## Protocol Reference (full text)** — you do not
+need to fetch it.
 
 {{#if issue}}
 ## Issue #{{issue.number}}
@@ -33,43 +26,28 @@ Follow the BUGFIX protocol. Read and internalize the protocol before starting an
 
 **Description**:
 {{issue.body}}
+{{/if}}
 
 ## Your Mission
+
 1. Reproduce the bug
-2. Identify root cause
-3. Implement fix (< 300 LOC)
-4. Add regression test
-5. Create PR with "Fixes #{{issue.number}}" in body
-6. Notify architect via `afx send architect "PR #N ready for review (fixes #{{issue.number}})"`
+2. Identify the root cause — **no code in the investigate phase**
+3. Implement the minimal fix (<300 LOC)
+4. Add a regression test that **fails without the fix and passes with it**
+5. Open a PR with `Fixes #{{issue.number}}` in the body
+6. Notify: `afx send architect "PR #N ready for review (fixes #{{issue.number}})"`
+
+When merging, use `gh pr merge --merge` **without** `--delete-branch` — you are checked out on
+that branch in a worktree.
+
+If the fix outgrows BUGFIX (>300 LOC, architectural impact, or an unclear root cause after
+investigation), stop and say so:
 
-If the fix is too complex (> 300 LOC or architectural changes), notify the Architect via:
 ```bash
 afx send architect "Issue #{{issue.number}} is more complex than expected. [Reason]. Recommend escalating to SPIR."
 ```
 
 ## Notifications
-Always use `afx send architect "..."` to notify the architect at key moments:
-- **PR ready**: `afx send architect "PR #N ready for review (fixes #{{issue.number}})"`
-- **PR merged**: `afx send architect "PR #N merged for issue #{{issue.number}}. Ready for cleanup."`
-- **Blocked**: `afx send architect "Blocked on issue #{{issue.number}}: [reason]"`
-{{/if}}
-
-## 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 your review under a `## Flaky Tests` section
-5. Commit the skip and continue with your work
-
-## Getting Started
-1. Read the BUGFIX protocol
-2. Review the issue details
-3. Reproduce the bug before fixing
-
----
-
-## Protocol Reference (full text)
 
-{{protocol_reference}}
+The architect is not watching. `afx send architect "..."` at each of: gate reached, PR ready, PR
+merged, blocked.

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

@@ -1,58 +1,40 @@
 # Implementation Review Prompt (BUGFIX)
 
 ## Context
-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.
+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. Verify the fix matches the issue's symptom and meets BUGFIX standards.
 
-## CRITICAL: Verify Before Flagging
+**BUGFIX is not SPIR.** There is **no spec, no plan, and no review document** — the GitHub Issue is the spec, and the PR body will be the review. Do **not** request changes for missing `codev/specs/`, `codev/plans/`, or `codev/reviews/` artifacts.
 
-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.
+## Verify before flagging
 
-## Focus Areas
-
-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)?
+Before requesting changes for missing configuration, wrong patterns, or framework issues, confirm the claim against the project rather than your training data:
 
-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?
+- 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. **Code Quality**
-   - Is the code readable and maintainable?
-   - 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.
+## Focus Areas
 
-5. **Test Status**
-   - Existing tests still pass.
-   - Build still passes.
-   - No new flaky tests introduced.
+- **Issue resolution** — the fix actually resolves the symptom in the issue, targeting the root cause rather than masking it with a workaround.
+- **Regression test** — a deterministic test exercises the exact scenario from the issue and **would fail without the fix**. If none was added, the builder has justified why (e.g. a docs-only change with no testable behavior).
+- **Scope discipline** — the change is focused on the root cause only (no unrelated refactors or drive-by fixes) and stays under ~300 LOC; if it grew larger, it should escalate to SPIR/TICK.
+- **Code quality** — readable and maintainable; no bugs introduced; error cases on the changed path handled; no debug or commented-out code.
+- **Test status** — existing tests and the build still pass; no new flaky tests.
 
 ## 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:
+These 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.
+- Commit format `[Spec NNNN][Phase]` — BUGFIX uses `Fix #N: ...` or `[Bugfix #N] ...`. That 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.
+- Phase-scoping concerns — BUGFIX is single-phase by design; there are no plan phases to scope against.
 
 ## Verdict Format
 
-After your review, provide your verdict in exactly this format:
+Provide your verdict in exactly this format — `consult` parses it:
 
 ```
 ---
@@ -66,14 +48,8 @@ KEY_ISSUES:
 ...
 ```
 
-**Verdict meanings:**
-- `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
+- `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).
+- `COMMENT`: minor suggestions; builder can proceed but should consider the feedback.
 
-- 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.
+This is an implementation-level review, not the final PR review — focus on "does this fix resolve the issue, protected by a regression test", not on artifacts from other protocols.

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

@@ -1,64 +1,35 @@
 # PR Ready Review Prompt (BUGFIX)
 
 ## Context
-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)
+You are performing the 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, and is about to create — or has just created — the PR for the architect's integration review.
 
-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]`.
+**BUGFIX is not SPIR.** Do **not** review against the SPIR three-document trinity. A BUGFIX project's artifacts are the originating **GitHub Issue** (the spec), the **code fix** (minimal, root-cause-focused), a **regression test** that fails without the fix and passes with it, and the **PR body** (Summary, Root Cause, Fix, Test Plan). There is **no `codev/specs/`, `codev/plans/`, or `codev/reviews/` file**, and there should not be. The commit format is `Fix #NNNN: <description>` (or `[Bugfix #NNNN] ...`), **not** `[Spec NNNN][Phase]`.
 
 ## Focus Areas
 
-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 its base (or close enough for clean merge).
-   - PR is linked to the issue.
+- **Issue resolution** — the fix resolves the symptom; the PR body includes `Fixes #<N>` (so the issue auto-closes on merge) and covers Summary, Root Cause, Fix, Test Plan.
+- **Regression test** — a deterministic test targets the exact scenario and would fail without the fix; a truly untestable (e.g. docs-only) fix has the absence explicitly justified.
+- **Scope discipline** — focused on the root cause, no unrelated refactors or drive-by fixes, net diff under ~300 LOC; if it grew beyond a bugfix, it should have escalated to SPIR/TICK.
+- **Code cleanliness** — no debug code, `console.log`, commented-out blocks, or stray TODOs; follows project conventions.
+- **Test status** — existing tests and the build pass; no new flaky tests.
+- **PR hygiene** — commits use `Fix #<N>: ...` / `[Bugfix #<N>] ...` (**not** `[Spec NNNN][Phase]`), the branch is current with its base, and the 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:
+These 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.
+- Missing `codev/reviews/<N>-*.md` — BUGFIX has no review document; the 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.
-- **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). Quoted diff syntax is documentation, not a command. Apply two-dot/three-dot scrutiny only to diffs you compute yourself.
+- The syntax of `git diff` examples in review-file prose (e.g. `git diff ci..HEAD` in a "Files Changed" caption) — quoted diff syntax is documentation, not a command. Apply two-dot/three-dot scrutiny only to diffs you compute yourself.
 
 ## Verdict Format
 
-After your review, provide your verdict in exactly this format:
+Provide your verdict in exactly this format — `consult` parses it:
 
 ```
 ---
@@ -76,23 +47,18 @@ PR_SUMMARY: |
   Fixes #<N>. [1-2 sentences on what was fixed.]
 
   ## Root Cause
-  [Brief explanation of what caused the bug]
+  [What caused the bug]
 
   ## Fix
-  [Brief explanation of the fix]
+  [What changed]
 
   ## Test Plan
   - [Regression test description]
   - [Manual verification, if applicable]
 ```
 
-**Verdict meanings:**
-- `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.
+- `APPROVE`: bug resolved, regression test in place, PR ready for architect review.
+- `REQUEST_CHANGES`: real BUGFIX-relevant issues (missing regression test, fix doesn't resolve the symptom, scope creep).
+- `COMMENT`: minor items; can proceed but note the feedback.
 
-## Notes
-
-- 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.
+The `PR_SUMMARY` block can be used directly as the PR description.

package/skeleton/protocols/bugfix/prompts/fix.md

@@ -2,76 +2,31 @@
 
 You are executing the **FIX** phase of the BUGFIX protocol.
 
-## Your Goal
+## Goal
 
-Implement the bug fix and add a regression test. Keep it minimal and focused.
+Fix the bug with the minimum change, and add a regression test that pins it.
 
 ## Context
 
 - **Issue**: #{{issue.number}} — {{issue.title}}
 - **Current State**: {{current_state}}
 
-## Process
+## What must be true when you finish
 
-### 1. Implement the Fix
+- **The change is minimal and targeted.** Fix the root cause from INVESTIGATE and nothing else — no refactoring of surrounding code, no unrelated features, no other bugs you happen to notice (file separate issues for those). Self-documenting code, no debug or commented-out code, existing project conventions.
+- **A regression test pins the fix.** Every bugfix carries a test that **fails without the fix and passes with it**, covers the issue's scenario, and is deterministic. The only exception is a genuinely untestable change (e.g. a CSS-only tweak with no observable behavior) — and then you state why, in the commit message and PR description.
+- **Build and tests pass.** Confirm the real project commands (check `package.json` if unsure) and run them; fix failures before signaling.
+- **The change stays within BUGFIX scope.** If the fix grows past ~300 LOC, signal `TOO_COMPLEX` rather than pressing on.
 
-Apply the minimum change needed to resolve the bug:
-- Fix the root cause identified in the INVESTIGATE phase
-- Do NOT refactor surrounding code
-- Do NOT add features beyond what's needed
-- Do NOT fix other bugs you happen to notice (file separate issues)
-
-**Code Quality**:
-- Self-documenting code (clear names, obvious structure)
-- No commented-out code or debug prints
-- Follow existing project conventions
-
-### 2. Add a Regression Test
-
-**A regression test is MANDATORY.** Every bugfix MUST include a test unless you provide explicit justification for why a test is impossible (e.g., pure CSS-only change with no testable behavior). If you skip the test, you MUST explain why in your commit message and PR description.
-
-Write a test that:
-- Fails without the fix (demonstrates the bug)
-- Passes with the fix (demonstrates the fix works)
-- Covers the specific scenario from the issue
-- Is deterministic (not flaky)
-
-Place tests following project conventions (`__tests__/`, `*.test.ts`, etc.).
-
-### 3. Verify the Fix
-
-Run build and tests:
-
-```bash
-npm run build      # Must pass
-npm test           # Must pass
-```
-
-Fix any failures before proceeding. If build/test commands don't exist, check `package.json`.
-
-### 4. Commit
-
-Stage and commit your changes:
-- Use explicit file paths (never `git add -A` or `git add .`)
-- Commit message: `Fix #{{issue.number}}: <brief description>`
+Commit with an explicit staged path and the message `Fix #{{issue.number}}: <brief description>`.
 
 ## Signals
 
-When fix and tests are complete and passing:
-
-```
-<signal>PHASE_COMPLETE</signal>
-```
-
-If you encounter a blocker:
-
-```
-<signal>BLOCKED:reason goes here</signal>
-```
-
-## Important Notes
-
-1. **Minimal changes only** — Fix the bug, nothing else
-2. **Regression test is MANDATORY** — No fix without a test. If truly untestable, justify in writing.
-3. **Build AND tests must pass** — Don't signal complete until both pass
-4. **Stay under 300 LOC** — If the fix grows beyond this, signal `TOO_COMPLEX`
+- Fix and tests complete and passing:
+  ```
+  <signal>PHASE_COMPLETE</signal>
+  ```
+- Blocked:
+  ```
+  <signal>BLOCKED:reason goes here</signal>
+  ```

package/skeleton/protocols/bugfix/prompts/investigate.md

@@ -2,76 +2,32 @@
 
 You are executing the **INVESTIGATE** phase of the BUGFIX protocol.
 
-## Your Goal
+## Goal
 
-Understand the bug, reproduce it, identify the root cause, and assess whether it's fixable within BUGFIX scope (< 300 LOC).
+Understand the bug, reproduce it, find the root cause, and decide whether it fits BUGFIX scope (a focused change under ~300 LOC).
 
 ## Context
 
 - **Issue**: #{{issue.number}} — {{issue.title}}
 - **Current State**: {{current_state}}
 
-## Process
+## What must be true when you finish
 
-### 1. Read the Issue
-
-Read the full issue description. Identify:
-- What is the expected behavior?
-- What is the actual behavior?
-- Are there reproduction steps?
-- Are there error messages or screenshots?
-
-### 2. Reproduce the Bug
-
-Before fixing anything, confirm the bug exists:
-- Follow the reproduction steps from the issue
-- If no steps are given, infer them from the description
-- Document the exact reproduction steps you used
-- If you **cannot** reproduce, signal `BLOCKED` with details
-
-### 3. Identify Root Cause
-
-Trace the bug to its source:
-- Read the relevant code paths
-- Use grep/search to find related code
-- Identify the exact file(s) and line(s) causing the issue
-- Understand **why** the bug occurs, not just **where**
-
-### 4. Assess Complexity
-
-Determine if this is BUGFIX-appropriate:
-- **< 300 LOC change**: Proceed with BUGFIX
-- **> 300 LOC or architectural**: Signal `TOO_COMPLEX` to escalate
-
-Consider:
-- How many files need to change?
-- Does it require new abstractions or refactoring?
-- Are there cascading effects?
-
-## Output
-
-By the end of this phase, you should know:
-1. The exact root cause
-2. Which files need to change
-3. The approximate size of the fix
-4. Whether it's BUGFIX-appropriate
+- **The bug is reproduced, not assumed.** You have confirmed the expected-vs-actual behavior from the issue and established concrete reproduction steps (inferring them if the issue gives none). If you cannot reproduce it, that is a `BLOCKED` signal with what you tried.
+- **The root cause is understood** — the exact file(s) and line(s), and *why* the bug happens, not just where. Trace the failure path rather than pattern-matching a symptom.
+- **The scope is assessed against BUGFIX's ceiling.** A focused fix under ~300 LOC proceeds; anything larger or architectural (new abstractions, refactors, cascading effects across many files) is a `TOO_COMPLEX` signal to escalate.
 
 ## Signals
 
-When investigation is complete:
-
-```
-<signal>PHASE_COMPLETE</signal>
-```
-
-If the bug is too complex for BUGFIX:
-
-```
-<signal>TOO_COMPLEX</signal>
-```
-
-If you're blocked (can't reproduce, missing context, etc.):
-
-```
-<signal>BLOCKED:reason goes here</signal>
-```
+- Investigation complete (root cause + fix scope known):
+  ```
+  <signal>PHASE_COMPLETE</signal>
+  ```
+- Too large or architectural for BUGFIX:
+  ```
+  <signal>TOO_COMPLEX</signal>
+  ```
+- Blocked (cannot reproduce, missing context):
+  ```
+  <signal>BLOCKED:reason goes here</signal>
+  ```

package/skeleton/protocols/bugfix/prompts/pr.md

@@ -2,32 +2,18 @@
 
 You are executing the **PR** phase of the BUGFIX protocol.
 
-## Your Goal
+## Goal
 
-Create a pull request, run CMAP review, and address feedback.
+Open the PR, run CMAP review on it, address feedback, and hand off to the architect at the `pr` gate.
 
 ## Context
 
 - **Issue**: #{{issue.number}} — {{issue.title}}
 - **Current State**: {{current_state}}
 
-## Process
+## Create the PR
 
-### 1. Create the Pull Request
-
-Create a PR that links to the issue.
-
-**PR body requirements**: The PR body MUST include `Fixes #<N>` (where `<N>` is
-the driving issue number) so GitHub auto-closes the issue on merge. If the PR
-fixes multiple issues (e.g. duplicates consolidated), include one `Fixes #<N>`
-per issue. Without this, GitHub will not auto-close the issue.
-
-**Exception**: if this PR only partially addresses the issue, use `Refs #<N>`
-or `Part of #<N>` instead of `Fixes` — the issue stays open until a
-follow-up PR closes it.
-
-**Note**: substitute the real issue number for `<N>` — do not leave the
-placeholder or any `{{...}}` template tag in the committed PR body.
+The PR body must carry `Fixes #<N>` for the driving issue — one per issue if several — so GitHub auto-closes it on merge. **Exception:** a PR that only partially addresses the issue uses `Refs #<N>` or `Part of #<N>` instead, leaving it open for the follow-up. Substitute the real number for `<N>`; leave no `{{...}}` tag or `<N>` placeholder in the committed body.
 
 ```bash
 gh pr create --title "Fix #<N>: <brief description>" --body "$(cat <<'EOF'
@@ -35,15 +21,15 @@ gh pr create --title "Fix #<N>: <brief description>" --body "$(cat <<'EOF'
 
 <1-2 sentence description of the bug and fix>
 
-Fixes #<N>  <!-- Substitute <N> with the real issue number -->
+Fixes #<N>  <!-- Substitute <N>; use "Refs #<N>" for a partial fix -->
 
 ## Root Cause
 
-<Brief explanation of why the bug occurred>
+<why the bug occurred>
 
 ## Fix
 
-<Brief explanation of what was changed>
+<what changed>
 
 ## Test Plan
 
@@ -54,9 +40,9 @@ EOF
 )"
 ```
 
-### 2. Run CMAP Review
+## Run CMAP review
 
-Run 3-way parallel consultation on the PR:
+BUGFIX runs its own 3-way consultation on the PR (porch does not do it for you). Dispatch all three in the background:
 
 ```bash
 consult -m gemini --protocol bugfix --type pr &
@@ -64,47 +50,26 @@ consult -m codex --protocol bugfix --type pr &
 consult -m claude --protocol bugfix --type pr &
 ```
 
-All three should run in the background (`run_in_background: true`).
-
-### 3. Wait for Results and Address Feedback
-
-**DO NOT proceed to step 4 until ALL THREE consultations have returned results.**
-
-Wait for each background consultation to complete, then read the results:
-- Use `TaskOutput` (with `block: true`) to retrieve each consultation result
-- Record each model's verdict (APPROVE or REQUEST_CHANGES)
-- Fix any issues identified by reviewers
-- Push updates to the PR branch
-- Re-run CMAP if substantial changes were made
-
-You must have three concrete verdicts (e.g., "gemini: APPROVE, codex: APPROVE, claude: APPROVE") before continuing.
+Do not proceed until **ALL THREE consultations have returned results** — retrieve each with `TaskOutput` (`block: true`), record its verdict (APPROVE / REQUEST_CHANGES), fix real issues, push, and re-run CMAP if the changes were substantial. You must hold three concrete verdicts before you notify.
 
-### 4. Notify Architect
+## Notify and hand off at the gate
 
-**DO NOT send this notification until you have all three CMAP verdicts from step 3.**
-
-Send a **single** notification that includes the PR link and each model's verdict:
+**DO NOT send this notification until you have all three CMAP verdicts.** Send a **single** notification with the PR link and all three verdicts, then request the gate:
 
 ```bash
 afx send architect "PR #<number> ready for review (fixes issue #{{issue.number}}). CMAP: gemini=<APPROVE|REQUEST_CHANGES>, codex=<APPROVE|REQUEST_CHANGES>, claude=<APPROVE|REQUEST_CHANGES>"
+porch done <project-id>
 ```
 
-Then run `porch done <project-id>` to auto-request the `pr` gate. The PR surfaces
-in Needs Attention from this point; **STOP and wait** for the architect to call
-`porch approve <project-id> pr`. After gate approval, porch will emit a merge task
-(via the next `porch next` call) — follow it to merge the PR and advance to
-`verified`.
+`porch done` fires the `pr` gate and surfaces the PR in Needs Attention. Wait for the architect to approve it (`porch approve <project-id> pr`) — a CMAP APPROVE is not merge authorization. After gate approval, follow the merge task from `porch next` to merge and advance to `verified`.
 
 ## Signals
 
-When PR is created and reviews are complete:
-
-```
-<signal>PHASE_COMPLETE</signal>
-```
-
-If you're blocked:
-
-```
-<signal>BLOCKED:reason goes here</signal>
-```
+- PR created and reviews complete:
+  ```
+  <signal>PHASE_COMPLETE</signal>
+  ```
+- Blocked:
+  ```
+  <signal>BLOCKED:reason goes here</signal>
+  ```