@cluesmith/codev 3.2.4 → 3.3.0

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

@@ -2,9 +2,9 @@
 
 You are executing the **IMPLEMENT** phase of the SPIR protocol.
 
-## Your Goal
+## Goal
 
-Write clean, well-structured code AND tests that implement the current plan phase.
+Implement the current plan phase — code and tests — so it matches the spec and passes build and tests.
 
 ## Context
 
@@ -13,203 +13,34 @@ Write clean, well-structured code AND tests that implement the current plan phas
 - **Current State**: {{current_state}}
 - **Plan Phase**: {{plan_phase_id}} - {{plan_phase_title}}
 
-## ⚠️ SCOPE RESTRICTION — READ THIS FIRST
+## Scope: this phase only
 
-**You are implementing ONLY the current plan phase: {{plan_phase_id}} ({{plan_phase_title}}).**
+Your scope is exactly `{{plan_phase_id}}` ({{plan_phase_title}}), whose details are included below under "Current Plan Phase Details". Other phases are handled in later porch iterations — do not implement them, and do not read the full plan and build everything you see. Read `codev/specs/{{project_id}}-*.md` for requirements, but implement only what this phase requires.
 
-- **DO NOT** implement other phases. Other phases will be handled in subsequent porch iterations.
-- **DO NOT** read the full plan file and implement everything you see.
-- The plan phase details are included below under "Current Plan Phase Details". That is your ONLY scope.
-- If you need to reference the spec for requirements, read `codev/specs/{{project_id}}-*.md` but ONLY implement what the current phase requires.
+When you signal `PHASE_COMPLETE`, porch runs the 3-way consultation, checks that tests exist and pass, and either respawns you with feedback or commits and moves to the next phase.
 
-## What Happens After You Finish
+## What must be true when you finish
 
-When you signal `PHASE_COMPLETE`, porch will:
-1. Run 3-way consultation (Gemini, Codex, Claude) on your implementation
-2. Check that tests exist and pass
-3. If reviewers request changes, you'll be respawned with their feedback
-4. Once approved, porch commits and moves to the next plan phase
-
-## Spec Compliance (CRITICAL)
-
-**The spec is the source of truth. Code that doesn't match the spec is wrong, even if it "works".**
-
-### Trust Hierarchy
-
-```
-SPEC (source of truth)
-  ↓
-PLAN (implementation guide derived from spec)
-  ↓
-EXISTING CODE (NOT TRUSTED - must be validated against spec)
-```
-
-**Never trust existing code over the spec.** Previous implementations may have drifted.
-
-### Pre-Implementation Sanity Check (PISC)
-
-**Before writing ANY code:**
-
-1. ✅ "Have I read the spec in the last 30 minutes?"
-2. ✅ "If the spec has a 'Traps to Avoid' section, have I read it?"
-3. ✅ "Does my approach match the spec's Technical Implementation section?"
-4. ✅ "If the spec has code examples, am I following them?"
-5. ✅ "Does the existing code I'm building on actually match the spec?"
-
-**If ANY answer is "no" or "unsure" → STOP and re-read the spec.**
-
-### Avoiding "Fixing Mode"
-
-A dangerous pattern: You start looking at symptoms in code, making incremental fixes, copying existing patterns - without going back to the spec. This leads to:
-- Cargo-culting patterns that may be wrong
-- Building on broken foundations
-- Implementing something different from the spec
-
-**When you catch yourself "fixing" code:**
-1. STOP
-2. Ask: "What does the spec say about this?"
-3. Re-read the spec's Traps to Avoid section
-4. Verify existing code matches the spec before building on it
-
-## Prerequisites
-
-Before implementing, verify:
-1. Previous phase (if any) is committed to git
-2. You've read the plan phase you're implementing
-3. You understand the success criteria for this phase
-4. Dependencies from earlier phases are available
-
-## Process
-
-### 1. Review the Plan Phase
-
-Read the current phase in the plan:
-- What is the objective?
-- What files need to be created/modified?
-- What are the success criteria?
-- What dependencies exist?
-
-### 2. Set Up
-
-- Verify you're on the correct branch
-- Check that previous phase is committed: `git log --oneline -5`
-- Ensure build passes before starting: `npm run build` (or equivalent)
-
-### 3. Implement the Code
-
-Write the code following these principles:
-
-**Code Quality Standards**:
-- Self-documenting code (clear names, obvious structure)
-- No commented-out code
-- No debug prints in final code
-- Explicit error handling
-- Follow project style guide
-
-**Implementation Approach**:
-- Work on one file at a time
-- Make small, incremental changes
-- Document complex logic with comments
-
-### 4. Write Tests
-
-**Tests are required.** For each piece of functionality you implement:
-
-- Write unit tests for core logic
-- Write integration tests if the phase involves multiple components
-- Test error cases and edge conditions
-- Ensure tests are deterministic (no flaky tests)
-
-**Test file locations** (follow project conventions):
-- `tests/` or `__tests__/` directories
-- `*.test.ts` or `*.spec.ts` naming
-
-### 5. Verify Everything Works
-
-Run both build and tests:
-
-```bash
-npm run build      # Must pass
-npm test           # Must pass
-```
-
-**Important**: Don't assume these commands exist. Check `package.json` first.
-
-Fix any errors before signaling completion.
-
-### 6. Self-Review
-
-Before signaling completion:
-- Read through all code changes
-- Read through all test changes
-- Verify code matches the spec requirements
-- Ensure no accidental debug code
-- Check test coverage is adequate
-
-## Output
-
-When complete, you should have:
-- Modified/created source files as specified in the plan phase
-- Tests covering the new functionality
-- All build checks passing
-- All tests passing
+- **The implementation matches the spec.** The spec is the source of truth; the plan derives from it; existing code is not trusted until validated against the spec, because earlier work may have drifted. Code that "works" but diverges from the spec is wrong. When you notice yourself patching symptoms in existing code, stop and re-check what the spec actually requires before building further.
+- **Tests exist and are meaningful.** Unit tests for the core logic, integration tests where the phase spans components, and coverage of error and edge cases. Tests are deterministic. Follow the project's existing test locations and naming.
+- **Build and tests pass.** Confirm the actual project commands (check `package.json` rather than assuming `npm run build` / `npm test` exist) and run them; fix failures before signaling.
+- **The change is clean.** Self-documenting names, explicit error handling, no commented-out or debug code, only the files this phase touches — the simplest solution that satisfies the phase, not more.
 
 ## Signals
 
-When implementation AND tests are complete and passing:
-
-```
-<signal>PHASE_COMPLETE</signal>
-```
-
-If you encounter a blocker:
-
-```
-<signal>BLOCKED:reason goes here</signal>
-```
-
-If you need spec/plan clarification:
-
-```
-<signal type=AWAITING_INPUT>
-Your specific questions here
-</signal>
-```
-
-## Important Notes
-
-1. **Follow the plan** - Implement what's specified, not more
-2. **Don't over-engineer** - Simplest solution that works
-3. **Don't skip error handling** - But don't go overboard either
-4. **Keep changes focused** - Only touch files in this phase
-5. **Build AND tests must pass** - Don't signal complete until both pass
-6. **Write tests** - Every implementation phase needs tests
-
-## What NOT to Do
-
-- Don't modify files outside this phase's scope
-- Don't add features not in the spec
-- Don't leave TODO comments for later (fix now or note as blocker)
-- Don't skip writing tests
-- Don't use `git add .` or `git add -A` when you commit (security risk)
-
-## Handling Problems
-
-**If the plan is unclear**:
-Signal `AWAITING_INPUT` with your specific question.
-
-**If you discover the spec is wrong**:
-Signal `BLOCKED` and explain the issue. The Architect may need to update the spec.
-
-**If a dependency is missing**:
-Signal `BLOCKED` with details about what's missing.
-
-**If build or tests fail and you can't fix it**:
-Signal `BLOCKED` with the error message.
-
-**If you encounter pre-existing flaky tests** (tests that fail intermittently but are unrelated to your changes):
-1. **DO NOT** edit `status.yaml` to bypass checks
-2. **DO NOT** skip porch checks or use workarounds to avoid the failure
-3. **DO** mark the flaky test as skipped with a clear annotation (e.g., `it.skip('...') // FLAKY: intermittent timeout, skipped pending investigation`)
-4. **DO** document each skipped flaky test in your review under a `## Flaky Tests` section so the team can follow up
-5. Commit the skip and continue with your work
+- Implementation and tests complete and passing:
+  ```
+  <signal>PHASE_COMPLETE</signal>
+  ```
+- Blocked — the plan is wrong, the spec is wrong, a dependency is missing, or build/tests fail in a way you cannot resolve:
+  ```
+  <signal>BLOCKED:reason goes here</signal>
+  ```
+- Need spec/plan clarification:
+  ```
+  <signal type=AWAITING_INPUT>
+  Your specific questions here
+  </signal>
+  ```
+
+A blocker is a signal, not a silent workaround: never edit `status.yaml` or bypass a porch check to force a green.

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

@@ -2,9 +2,9 @@
 
 You are executing the **PLAN** phase of the SPIR protocol.
 
-## Your Goal
+## Goal
 
-Transform the approved specification into an executable implementation plan with clear phases.
+Turn the approved spec into an executable plan at `codev/plans/{{artifact_name}}.md`: a phase breakdown a builder can implement one phase at a time.
 
 ## Context
 
@@ -14,105 +14,41 @@ Transform the approved specification into an executable implementation plan with
 - **Spec File**: `codev/specs/{{artifact_name}}.md`
 - **Plan File**: `codev/plans/{{artifact_name}}.md`
 
-## Prerequisites
+## What must be true when you finish
 
-Before planning, verify:
-1. The specification exists and has been approved
-2. You've read and understood the entire spec
-3. Success criteria are clear and measurable
+- **The plan derives from the spec.** You have read the whole spec — its functional and non-functional requirements, constraints, and success criteria — and the plan validates against them.
+- **The work is decomposed into phases, each of which is:**
+  - **self-contained** — a complete unit of functionality;
+  - **independently testable** — verifiable on its own;
+  - **valuable** — delivers observable progress;
+  - **committable** — a single atomic commit.
 
-## Process
-
-### 1. Analyze the Specification
-
-Read the spec thoroughly. Identify:
-- All functional requirements
-- Non-functional requirements
-- Dependencies and constraints
-- Success criteria to validate against
-
-### 2. Identify Implementation Phases
-
-Break the work into logical phases. Each phase should be:
-- **Self-contained** - A complete unit of functionality
-- **Independently testable** - Can be verified on its own
-- **Valuable** - Delivers observable progress
-- **Committable** - Can be a single atomic commit
-
-Good phase examples:
-- "Database Schema" - Creates all tables/migrations
-- "Core API Endpoints" - Implements main REST routes
-- "Authentication Flow" - Handles login/logout/session
-
-Bad phase examples:
-- "Setup" - Too vague
-- "Part 1" - Not descriptive
-- "Everything" - Not broken down
-
-### 3. Define Each Phase
-
-For each phase, document:
-- **Objective** - Single clear goal
-- **Files to modify/create** - Specific paths
-- **Dependencies** - Which phases must complete first
-- **Success criteria** - How to know it's done
-- **Test approach** - What tests will verify it
-
-### 4. Order Phases by Dependencies
-
-Arrange phases so dependencies are satisfied:
-```
-Phase 1: Database Schema (no dependencies)
-Phase 2: Data Models (depends on Phase 1)
-Phase 3: API Endpoints (depends on Phase 2)
-Phase 4: Frontend Integration (depends on Phase 3)
-```
-
-### 5. Finalize
-
-After completing the plan draft, signal completion. Porch will run 3-way consultation (Gemini, Codex, Claude) automatically via the verify step. If reviewers request changes, you'll be respawned with their feedback.
+  A phase name states what it delivers ("Database schema", "Authentication flow"), not a position ("Setup", "Part 1").
+- **Each phase carries its own contract:** objective, the specific files it creates or modifies, which earlier phases it depends on, its success criteria, and how it will be tested.
+- **Phases are ordered so dependencies are satisfied before the phase that needs them.**
 
 ## Output
 
-Create the plan file at `codev/plans/{{artifact_name}}.md`, following the template below:
+Write the plan to `codev/plans/{{artifact_name}}.md` using the template below as its interface:
 
 {{> protocols/spir/templates/plan.md}}
 
 ## Signals
 
-Emit appropriate signals based on your progress:
-
-- After completing the plan draft:
+- Draft done:
   ```
   <signal>PLAN_DRAFTED</signal>
   ```
 
-## Commit Cadence
+## Commit cadence
 
-Make commits at these milestones:
+Commit at each milestone, staging the plan file explicitly:
+```bash
+git add codev/plans/{{artifact_name}}.md
+```
 1. `[Spec {{project_id}}] Initial implementation plan`
 2. `[Spec {{project_id}}] Plan with multi-agent review`
 3. `[Spec {{project_id}}] Plan with user feedback`
 4. `[Spec {{project_id}}] Final approved plan`
 
-**CRITICAL**: Never use `git add .` or `git add -A`. Always stage specific files:
-```bash
-git add codev/plans/{{artifact_name}}.md
-```
-
-## Important Notes
-
-1. **No time estimates** - Don't include hours/days/weeks
-3. **Be specific about files** - Exact paths, not "the config file"
-4. **Keep phases small** - 1-3 files per phase is ideal
-5. **Document dependencies clearly** - Prevents blocked work
-
-## What NOT to Do
-
-- Don't run `consult` commands yourself (porch handles consultations)
-- Don't write code (that's for Implement phase)
-- Don't estimate time (meaningless in AI development)
-- Don't create phases that can't be independently tested
-- Don't skip dependency analysis
-- Don't make phases too large (if >5 files, split it)
-- Don't use `git add .` or `git add -A` (security risk)
+Porch runs the 3-way consultation itself after you signal — do not run `consult`. This is the Plan phase: decompose and sequence the work, do not write code, and do not estimate time.

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

@@ -2,9 +2,9 @@
 
 You are executing the **REVIEW** phase of the SPIR protocol.
 
-## Your Goal
+## Goal
 
-Perform a comprehensive review, document lessons learned, and prepare for PR submission.
+Review the whole implementation, write the retrospective at `codev/reviews/{{artifact_name}}.md`, and open the PR — so porch's consultation and the architect both review a real PR.
 
 ## Context
 
@@ -15,264 +15,65 @@ Perform a comprehensive review, document lessons learned, and prepare for PR sub
 - **Plan File**: `codev/plans/{{artifact_name}}.md`
 - **Review File**: `codev/reviews/{{artifact_name}}.md`
 
-## Prerequisites
+## What must be true when you finish
 
-Before review, verify:
-1. All implementation phases are committed
-2. All tests are passing
-3. Build is passing
-4. Spec compliance verified for all phases
+- **The work is done and green.** All phases committed (`git log --oneline | grep "[Spec {{project_id}}]"`), build and tests passing, no uncommitted changes.
+- **The implementation has been reviewed against the spec** — code quality, architecture fit, and security considered; deviations from the spec noted with their reasons; every success criterion accounted for.
+- **The review document exists** at `codev/reviews/{{artifact_name}}.md`, following the template below (its headings, its order — do not pattern-match an older review that predates it).
+- **Consultation feedback is captured.** The review carries a `## Consultation Feedback` section that, per phase / round / model, records each concern and its disposition — **Addressed** (changed), **Rebutted** (why it does not apply), or **N/A** (out of scope / handled elsewhere). "No concerns raised — all consultations approved" is the right line when that is true; note COMMENT verdicts and any `CONSULT_ERROR`. Read the consult outputs from `codev/projects/{{project_id}}-*/`.
+- **Governance facts are routed by tier** (see below).
+- **The PR exists before you signal**, with a close-keyword so merging auto-closes the issue (see below).
 
-Verify commits: `git log --oneline | grep "[Spec {{project_id}}]"`
-
-## Process
-
-### 1. Comprehensive Review
-
-Review the entire implementation:
-
-**Code Quality**:
-- Is the code readable and maintainable?
-- Are there any code smells?
-- Is error handling consistent?
-- Are there any security concerns?
-
-**Architecture**:
-- Does the implementation fit well with existing code?
-- Are there any architectural concerns?
-- Is the design scalable if needed?
-
-**Documentation**:
-- Is code adequately commented where needed?
-- Are public APIs documented?
-- Is README updated if needed?
-
-### 2. Spec Comparison
-
-Compare final implementation to original specification:
-
-- What was delivered vs what was specified?
-- Any deviations? Document why.
-- All success criteria met?
-
-### 3. Create Review Document
-
-Create `codev/reviews/{{artifact_name}}.md`:
-
-```markdown
-# Review: {{title}}
-
-## Summary
-Brief description of what was implemented.
-
-## Spec Compliance
-- [x] Requirement 1: Implemented as specified
-- [x] Requirement 2: Implemented with deviation (see below)
-- [x] Requirement 3: Implemented as specified
-
-## Deviations from Plan
-- **Phase X**: [What changed and why]
-
-## Lessons Learned
-
-### What Went Well
-- [Positive observation 1]
-- [Positive observation 2]
-
-### Challenges Encountered
-- [Challenge 1]: [How it was resolved]
-- [Challenge 2]: [How it was resolved]
-
-### What Would Be Done Differently
-- [Insight 1]
-- [Insight 2]
-
-### Methodology Improvements
-- [Suggested improvement to SPIR protocol]
-- [Suggested improvement to tooling]
-
-## Technical Debt
-- [Any shortcuts taken that should be addressed later]
-
-## Consultation Feedback
-
-[See instructions below]
-
-## Flaky Tests
-- [Any pre-existing tests that were skipped as flaky during this project]
-- [Include test name, file path, and observed failure mode]
-- [If none: "No flaky tests encountered"]
-
-## Follow-up Items
-- [Any items identified for future work]
-```
-
-### 3b. Include Consultation Feedback
-
-**IMPORTANT**: The review document MUST include a `## Consultation Feedback` section that summarizes all consultation concerns raised during every phase of the project and how the builder responded.
-
-Read the consultation output files from the project directory (`codev/projects/{project-id}-*/`). For each phase that had consultation, create a subsection organized by phase, round, and model:
-
-```markdown
-## Consultation Feedback
-
-### Specify Phase (Round 1)
-
-#### Gemini
-- **Concern**: [Summary of the concern]
-  - **Addressed**: [What was changed to resolve it]
-
-#### Codex
-- **Concern**: [Summary]
-  - **Rebutted**: [Why the current approach is correct]
-
-#### Claude
-- No concerns raised (APPROVE)
-
-### Plan Phase (Round 1)
-...
-```
-
-**Response types** — each concern gets exactly one:
-- **Addressed**: Builder made a change to resolve the concern
-- **Rebutted**: Builder explains why the concern doesn't apply
-- **N/A**: Concern is out of scope, already handled elsewhere, or moot
-
-**Edge cases**:
-- If all reviewers approved with no concerns: "No concerns raised — all consultations approved"
-- For COMMENT verdicts: include their feedback (non-blocking but useful context)
-- For CONSULT_ERROR (model failure): note "Consultation failed for [model]"
-- If a phase had multiple rounds, give each round its own subsection
-
-### 4. Update Architecture and Lessons Learned Documentation
-
-**MANDATORY**: The review document MUST include `## Architecture Updates` and `## Lessons Learned Updates` sections. Porch will block advancement if these are missing.
-
-Each governance doc has **two tiers** (Spec 987) — **route** each new fact/lesson to the right tier; do **not** just append to the cold archive:
-- **HOT** — `codev/resources/arch-critical.md` / `lessons-critical.md`: tiny, **hard-capped**, **always injected** into every prompt and into CLAUDE.md/AGENTS.md. The behavior-changer.
-- **COLD** — `codev/resources/arch.md` / `lessons-learned.md`: full, on-demand reference.
-
-**Architecture Updates**:
-1. Read `arch-critical.md` (hot) and skim `arch.md` (cold).
-2. If this project produced a system-shape fact, route it:
-   - **Behavior-changing + cross-cutting** (an invariant/decision a future builder must know up front) → add to **`arch-critical.md`**. Respect the cap: if the hot file is full, **demote** a weaker entry into `arch.md` to make room. If you add/rename a top-level `arch.md` section, keep the hot file's cold-doc map accurate.
-   - **Reference detail** (subsystem mechanism, file location, one-off) → add to **`arch.md`** (cold).
-3. Describe what you routed where in the `## Architecture Updates` section. If nothing qualifies: write "No architecture updates needed" with a brief reason.
-
-**Lessons Learned Updates**:
-1. Read `lessons-critical.md` (hot) and skim `lessons-learned.md` (cold).
-2. If this project produced a durable lesson, route it:
-   - **Behavior-changing + cross-cutting** (a rule that should change how the next project is built) → add to **`lessons-critical.md`**, respecting the cap (demote a weaker entry into `lessons-learned.md` if full).
-   - **Spec-narrow recipe / reference tip** → add to **`lessons-learned.md`** (cold). Spec-narrow recipes belong in the cold archive, never the always-on hot file.
-3. Describe what you routed where in the `## Lessons Learned Updates` section. If nothing qualifies: write "No lessons learned updates needed" with a brief reason.
-
-**Never** grow a hot file past its cap by appending — route to cold or displace. The cap is what keeps the hot tier cheap enough to always inject.
+## Output
 
-### 4b. Update Other Documentation
+Write the review to `codev/reviews/{{artifact_name}}.md` using the template below as its interface. Steps below expand its `## Consultation Feedback`, `## Architecture Updates`, and `## Lessons Learned Updates` sections; porch greps the produced file for the last two by exact heading.
 
-If needed, also update:
-- README.md (new features, changed behavior)
-- API documentation
+{{> protocols/spir/templates/review.md}}
 
-### 5. Final Verification
+## Route governance facts by tier (Spec 987)
 
-Before PR:
-- [ ] All tests pass (use project-specific test command)
-- [ ] Build passes (use project-specific build command)
-- [ ] Lint passes (if configured)
-- [ ] No uncommitted changes: `git status`
-- [ ] Review document complete
+Each governance doc has two tiers. **Route** each new fact; do not simply append to the cold archive.
 
-### 6. Create Pull Request
+- **HOT** — `codev/resources/arch-critical.md` and `lessons-critical.md`: tiny, hard-capped, always injected into every prompt and into CLAUDE.md/AGENTS.md. Add here only a **behavior-changing, cross-cutting** fact a future builder must know up front. The hot files are capped: if one is full, **demote** a weaker entry into its cold counterpart to make room, and keep the hot file's cold-doc map accurate.
+- **COLD** — `codev/resources/arch.md` and `lessons-learned.md`: full, on-demand reference for subsystem detail, file locations, one-offs, and spec-narrow recipes.
 
-**IMPORTANT: Create the PR BEFORE signaling completion.** The PR must exist so that
-porch consultation reviews the actual PR, and the architect can review a real PR
-when the pr gate fires.
+The review's `## Architecture Updates` and `## Lessons Learned Updates` sections state what you routed where; if nothing qualifies, keep the heading with a one-line reason. Never grow a hot file past its cap by appending — route to cold or displace. The `update-arch-docs` skill encodes this discipline.
 
-**PR body requirements**: The PR body MUST include `Closes #<N>` (for feature issues)
-or `Fixes #<N>` (for bug issues) for the driving GitHub issue. If the PR closes
-multiple issues (e.g. duplicates consolidated), include one keyword per issue.
-Without this, GitHub will not auto-close the issue on merge.
+## Create the PR (before signaling)
 
-**Exception**: if this PR only partially addresses the issue (e.g. one phase of a
-multi-PR effort), DO NOT use `Closes`/`Fixes` — reference the issue with `Refs #<N>`
-or `Part of #<N>` instead. The issue stays open until the follow-up PR closes it.
+The PR body must carry `Closes #<N>` (feature) or `Fixes #<N>` (bug) for the driving issue — one keyword per issue if several — so GitHub auto-closes on merge. **Exception:** a PR that only partially addresses its issue uses `Refs #<N>` or `Part of #<N>` instead, leaving the issue open for the follow-up.
 
 ```bash
 gh pr create --title "[Spec {{project_id}}] {{title}}" --body "$(cat <<'EOF'
 ## Summary
-[Brief description of the implementation]
+[what was implemented]
 
-Closes #<N>  <!-- Replace <N> with the driving issue number, or use "Refs #<N>" for partial fixes -->
+Closes #<N>  <!-- driving issue; use "Refs #<N>" for a partial fix -->
 
 ## Changes
-- [Change 1]
-- [Change 2]
+- ...
 
 ## Testing
-- All unit tests passing
-- Integration tests added for [X]
-- Manual testing completed for [Y]
+- ...
 
 ## Spec
-Link: codev/specs/{{artifact_name}}.md
+codev/specs/{{artifact_name}}.md
 
 ## Review
-Link: codev/reviews/{{artifact_name}}.md
+codev/reviews/{{artifact_name}}.md
 EOF
 )"
 ```
 
-### 7. Signal Completion
-
-After the PR is created, signal completion. Porch will run 3-way consultation
-(Gemini, Codex, Claude) automatically via the verify step. If reviewers request
-changes, you'll be respawned with their feedback.
-
-## Output
-
-- Review document at `codev/reviews/{{artifact_name}}.md`
-- Updated documentation (if needed)
-- Pull request created and ready for review
-
 ## Signals
 
-- After review document is complete:
+- Review document complete:
   ```
   <signal>REVIEW_COMPLETE</signal>
   ```
-
-- After PR is created — signal completion so porch runs consultation:
+- PR created — signal so porch runs the 3-way consultation:
   ```
   <signal>PR_READY</signal>
   ```
 
-## Important Notes
-
-1. **Be honest in lessons learned** - Future you will thank present you
-3. **Document deviations** - They're not failures, they're learnings
-4. **Update methodology** - If you found a better way, document it
-5. **Don't skip the checklist** - It catches last-minute issues
-6. **Clean PR description** - Makes review easier
-
-## What NOT to Do
-
-- Don't run `consult` commands yourself (porch handles consultations)
-- Don't skip lessons learned ("nothing to report")
-- Don't merge your own PR (Architect handles integration)
-- Don't leave uncommitted changes
-- Don't forget to update documentation
-- Don't rush this phase - it's valuable for learning
-- Don't use `git add .` or `git add -A` (security risk)
-
-## Review Prompts for Reflection
-
-Ask yourself:
-- What surprised me during implementation?
-- Where did I spend the most time? Was it avoidable?
-- What would have helped me go faster?
-- Did the spec adequately describe what was needed?
-- Did the plan phases make sense in hindsight?
-- What tests caught issues? What tests were unnecessary?
-
-Capture these reflections in the lessons learned section.
+Do not run `consult` (porch handles it) and merge your own PR only after the human approves the `pr` gate — never before.