@cluesmith/codev 3.0.5 → 3.0.7

package/scripts/forge/gitea/recently-merged.sh

@@ -1,3 +1,27 @@
 #!/bin/sh
 # Forge concept: recently-merged (Gitea via tea CLI)
-exec tea pulls list --state closed --limit 1000 --output json
+#
+# `tea pulls list --state closed` returns both merged PRs and closed-without-
+# merge PRs. Filter to merged only via `.merged == true` (the same predicate
+# scripts/forge/gitea/pr-exists.sh already relies on), then map to the
+# GitHub-compatible shape:
+#   index           -> number (int)
+#   created         -> createdAt
+#   updated         -> mergedAt  (tea exposes no merged_at field via --fields;
+#                                 close-then-edit overestimates merged time
+#                                 but is acceptable for the 24h overview window)
+#   head.ref        -> headRefName
+#   description     -> body
+exec tea pulls list --state closed --limit 1000 \
+  --fields index,title,state,author,url,created,updated,head,description,merged \
+  --output json \
+  | jq '[.[] | select(.merged == true) | {
+      number: (.index | tonumber),
+      title,
+      state,
+      url,
+      body: (.description // ""),
+      createdAt: .created,
+      mergedAt: .updated,
+      headRefName: (.head.ref // "")
+    }]'

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

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