@cluesmith/codev 3.0.5 → 3.0.6

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

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