@cluesmith/codev 3.0.3 → 3.0.6

package/skeleton/protocols/pir/protocol.md

@@ -0,0 +1,204 @@
+# PIR Protocol
+
+> **Plan → Implement → Review** for GitHub-issue-driven work that needs human review of *either* the approach (before code is written) *or* the implementation (before a PR exists), or both. Lighter than SPIR/ASPIR (no `specify` phase — the GitHub issue is the implicit spec) with the human dev-approval moved earlier (pre-PR instead of post-PR). Stronger than BUGFIX/AIR (two human gates before the PR).
+
+## When to Use PIR
+
+Pick PIR when working from a GitHub Issue and ONE or BOTH of the following apply — based on the *nature* of the change, not its size:
+
+### 1. The approach needs review before coding starts
+- Root cause is ambiguous; multiple valid fixes exist
+- Area is unfamiliar or high-blast-radius (shared utilities, auth, migrations, public APIs)
+- Design-sensitive (affects conventions, patterns, architecture)
+- Cheaper to redirect at plan time than at PR time
+
+### 2. The implementation needs to be tested before a PR is created
+The PR diff alone is insufficient; the reviewer must *run* the code:
+- Mobile app changes (needs device testing on Android, iOS, possibly web)
+- UI / UX changes (visual inspection, interaction flow, accessibility)
+- Hardware-adjacent behavior (sensors, camera, permissions, notifications)
+- Integration with external services that don't mock cleanly (OAuth, payments, analytics)
+- User-journey changes that need a full-flow exercise
+- Performance-sensitive changes that need profiling on the running app
+
+### Use SPIR / ASPIR / BUGFIX / AIR instead when
+- **SPIR / ASPIR**: the change is complex enough to warrant careful specification, multi-agent consultation at every phase, and the full spec → plan → implement → review ceremony with file artifacts. The driving issue is incidental — what matters is that the design work deserves a formal spec and the implementation deserves consult-driven review at each phase
+- **BUGFIX**: small bug fix, no design review needed, diff-on-PR review is enough
+- **AIR**: small feature from an issue, autonomous, diff-on-PR review is enough
+
+## How PIR Differs from SPIR
+
+PIR is structurally *SPIR minus the `specify` phase*, with the human dev-approval moved earlier (pre-PR instead of post-PR).
+
+| Aspect | SPIR | PIR |
+|---|---|---|
+| Phases | specify → plan → implement → review → verify | plan → implement → review |
+| Spec artifact | `codev/specs/<id>-<slug>.md` | GitHub Issue body (implicit spec) |
+| Plan artifact | `codev/plans/<id>-<slug>.md` | Same — committed on builder branch |
+| Review artifact | `codev/reviews/<id>-<slug>.md` (Summary + Architecture Updates + Lessons Learned, becomes PR body) | **Same shape** — `codev/reviews/<id>-<slug>.md` with the same sections, also becomes PR body |
+| Human gates | spec-approval, plan-approval, pr, verify-approval | plan-approval, dev-approval, pr |
+| Where code is reviewed by the human | On the PR (post-creation) — read the diff | Pre-PR (at the `dev-approval` gate) — read the diff **and run the worktree locally** |
+
+The review file always includes Summary, Architecture Updates, and Lessons Learned sections so `codev/reviews/` stays semantically consistent across all protocols. PIR's lightness comes from skipping the `specify` phase (the issue body is the spec), not from cutting corners on the retrospective.
+
+The `dev-approval` gate is what makes PIR genuinely different: the human gates the *running implementation* via the worktree before the PR exists, instead of gating the PR after creation.
+
+## Phases
+
+```
+plan → implement → review
+```
+
+### Plan (gated by `plan-approval`)
+
+The builder:
+1. Reads the GitHub issue and investigates the codebase
+2. Writes `codev/plans/<id>-<slug>.md` with: Understanding / Proposed change / Files to change / Risks & alternatives / Test plan
+3. Commits the plan on the builder branch and pushes
+4. Runs `porch done` and `porch next` — the `plan-approval` gate becomes pending
+5. Sits at the interactive prompt waiting for review
+
+**Reviewer paths** (all equivalent):
+- Open `codev/plans/<id>-<slug>.md` in the worktree, read and / or edit directly, save
+- Type feedback into the builder's PTY pane — the builder is alive in interactive mode
+- `afx send <builder-id> "<feedback>"`
+- Comment on the GitHub issue (sidecar discussion)
+
+When satisfied, approve via VSCode's "Approve Gate" command (Cmd+K G) or:
+
+```bash
+porch approve <id> plan-approval --a-human-explicitly-approved-this
+```
+
+### Implement (gated by `dev-approval`)
+
+The builder:
+1. Reads the approved plan file
+2. Writes code and tests; runs build + tests via the `checks` block
+3. *No AI consult on this phase* — the human at the `dev-approval` gate is the sole reviewer of the running code. Matches BUGFIX / AIR's pattern of "no consult on implementation, one consult at PR creation".
+4. Pushes the branch
+5. Runs `porch done` and `porch next` — the `dev-approval` gate becomes pending
+6. Outputs a **prose** dev-approval summary in the PTY pane (Summary / Files / Test results / Things to look at / How to test locally). This is a transient message to orient the human reviewer — **not a committed file**. The retrospective file is written in the next phase, after the human approves the running code.
+7. Sits at the interactive prompt
+
+**The reviewer's killer move**: run the worktree locally.
+
+- VSCode: right-click the builder in the Codev sidebar → **Run Dev Server** (spawns `afx dev <builder-id>` via Tower)
+- CLI: `afx dev <builder-id>`
+
+The dev server uses **the same ports and URLs as main** intentionally (OAuth callbacks, CORS, cookie scoping all depend on consistent origins). Only one dev env runs at a time; stop main's `pnpm dev` before starting the worktree's, or use VSCode's **Stop Dev Server** to swap.
+
+Reviewer tests the change on real devices / browsers / simulators. When satisfied, approves via Cmd+K G or:
+
+```bash
+porch approve <id> dev-approval --a-human-explicitly-approved-this
+```
+
+### Review (gated by `pr`)
+
+The builder:
+1. Writes `codev/reviews/<id>-<slug>.md` with **Summary**, **Architecture Updates**, **Lessons Learned Updates**, plus the supporting sections (Files Changed, Commits, Test Results, Things to Look At, How to Test Locally).
+2. Updates `codev/resources/arch.md` and/or `codev/resources/lessons-learned.md` if real changes need recording. If not, the review file's sections state "no changes needed" with a one-line explanation (the porch `checks` block enforces section presence, not content).
+3. Commits the review file (and arch / lessons updates if any) and pushes
+4. Opens a PR with `gh pr create`; PR body is the review file content + `Fixes #<N>`. Records the PR with `porch done <id> --pr <M> --branch <name>`.
+5. Runs `porch done <id>` — porch's `verify` block runs CMAP-2 (Gemini + Codex, type=impl) as a **single advisory pass** (`max_iterations: 1`); CMAP outputs land in `codev/projects/<id>-*/`. There is no iterate-until-APPROVE loop: whatever the verdicts, porch records them and advances to the `pr` gate. A `REQUEST_CHANGES` is not auto-re-reviewed — the builder addresses or rebuts it, adds a regression test if it's a real defect, and escalates it in the architect notification so the human verifies it at the `pr` gate. Outcomes are not auto-appended to the PR body; reviewers with the worktree read them from the projects dir.
+6. The `pr` gate fires (pending) regardless of verdict. Builder notifies the architect once — leading with any `REQUEST_CHANGES` and its disposition (since PIR will not re-review it) rather than burying it in a flat status line.
+7. Builder waits at the `pr` gate. The human reviews the PR on GitHub, then approves the `pr` gate (Cmd+K G or `porch approve <id> pr --a-human-explicitly-approved-this`). Porch wakes the builder.
+8. Builder verifies the gate is genuinely approved via `porch next` (defensive — typed prose can't trigger this branch, only real porch state does), then runs `gh pr merge --merge`, records via `porch done --merged <M>`, and sends the cleanup-ready notification. Protocol complete (`next: null`).
+
+## Gates
+
+PIR uses porch's existing gate machinery. Gate names are opaque strings; no porch engine changes are needed.
+
+- **`plan-approval`** — pre-PR. Human reads the plan file (committed on the builder branch) and approves before any code is written. Gates are keyed by `(project_id, gate_name)` so the name is safe to share with other protocols.
+- **`dev-approval`** — pre-PR. The human reviews the *running* worktree (via `afx dev`) before any PR exists. This is PIR's distinctive gate.
+- **`pr`** — post-PR. Gates the merge step. The human reviews the PR on GitHub and approves this gate; porch wakes the builder, which then runs `gh pr merge`. The gate exists so the merge trigger is structured porch state (binary approved/not), not free-text prose typed into the builder's pane. Eliminates the self-merge bug class: builders can't infer authorization from ambiguous user input.
+
+When a gate becomes pending, porch broadcasts `overview-changed` via SSE. The VSCode Builders tree picks up the blocked state and renders it with a bell icon; a toast surfaces the new gate-pending event. Architect notification is *not* automatic — gates surface via the toast/sidebar (for IDE users) or by checking the builder pane / `porch pending` (for CLI users). The builder's job at any gate is to write the artifact, commit, signal completion, and wait — never to invoke `porch approve` itself (Claude refuses the `--a-human-explicitly-approved-this` flag by design).
+
+## Rejection / Feedback Model
+
+There is no formal `porch reject` command. Rejection works via the feedback-iterate pattern:
+
+1. Reviewer provides feedback (edit the plan file in VSCode, type in the builder pane, `afx send`, or issue comment)
+2. Builder reads the feedback on its next turn, revises the artifact, recommits
+3. The gate remains pending — porch doesn't advance until the human runs `porch approve`
+
+The same pattern works at both gates.
+
+## Builder Session Lifetime
+
+The builder is a long-running interactive Claude Code session in a PTY pane managed by Tower. The session is launched as `claude "<prompt>"` (no `--print`) inside a `while true` restart loop. That form starts an interactive Claude REPL with the prompt as the first user message; after Claude finishes the prompted work it sits at the input prompt awaiting next user input. The outer `while true` loop only fires if Claude crashes — it is a crash-recovery safety net, not the gate-wait mechanism.
+
+This means typed input in the builder pane reaches the live Claude session immediately, exactly like any other interactive Claude Code conversation. There is no "session ended at gate" state to worry about under normal operation.
+
+## Configuration
+
+PIR uses the same `.codev/config.json` configuration as other protocols. The `worktree` block (from Issue 689) enables the at-gate dev-server review flow:
+
+```json
+{
+  "worktree": {
+    "symlinks": [".env.local", "packages/*/.env"],
+    "postSpawn": ["pnpm install --frozen-lockfile"],
+    "devCommand": "pnpm dev"
+  }
+}
+```
+
+Without `worktree.devCommand`, `afx dev` won't work and the `dev-approval` gate degenerates to a diff-read — at which point you should probably use AIR or BUGFIX instead.
+
+## Multi-Agent Consultation
+
+- **plan**: human-only review. No AI consultation.
+- **implement**: no AI consult — the human at the `dev-approval` gate is the sole reviewer of the running code.
+- **review**: CMAP-2 (Gemini + Codex, type=impl) after the PR is opened, as a **single advisory pass** (`max_iterations: 1`). Same pattern as BUGFIX / AIR's PR-creation consult.
+
+CMAP at the PR is a single pass — there is **no iterate-until-APPROVE loop**. A `REQUEST_CHANGES` does not block or re-trigger CMAP; the builder addresses or rebuts it and escalates it to the human at the `pr` gate, who is the sole remaining reviewer of any resulting fix (CMAP does not re-check it).
+
+Net: PIR runs **two model calls per protocol run**, matching its BUGFIX/AIR peers — its distinguishing features are the two human gates (`plan-approval`, `dev-approval`), not AI-consult density.
+
+**The 2-model footprint is a design invariant.** porch's model precedence is *config > protocol* (`porch.consultation.models` in `.codev/config.json` overrides a protocol's declared `verify.models`). A project-wide setting tuned for SPIR (gemini + codex + claude) will silently inflate PIR to a 3-model pass, breaking the BUGFIX/AIR-parity cost story. To keep PIR at CMAP-2, leave `porch.consultation.models` unset or scope it per-protocol.
+
+To disable consultation entirely, say "without multi-agent consultation" when starting work.
+
+## Signals
+
+PIR uses the standard porch signal vocabulary:
+
+```
+<signal>PHASE_COMPLETE</signal>          # Current phase build complete
+<signal>BLOCKED:reason</signal>          # Cannot proceed
+```
+
+Signals are informational for log readability. The state machine is driven by `porch done` and `porch next` CLI calls inside the builder turn.
+
+## Commit Messages
+
+Commits during PIR phases use the issue-driven format:
+
+```
+[PIR #<N>] Plan draft
+[PIR #<N>] Implement avatar masking
+[PIR #<N>] Add Android-side regression test
+```
+
+The PR title follows the project's existing PR convention.
+
+## Branch Naming
+
+```
+builder/pir-<issue-number>
+```
+
+Example: `builder/pir-842` for a PIR spawn against GitHub issue #842.
+
+## File Locations
+
+```
+codev/plans/<id>-<slug>.md             # written in plan phase, on builder branch
+codev/reviews/<id>-<slug>.md           # written in review phase (post-dev-approval-approval), on builder branch; becomes PR body
+codev/projects/<id>-<slug>/status.yaml # porch state, managed automatically
+```
+
+The plan and review files ship to `main` with the merged PR — durable, searchable, git-versioned. The review file includes Summary + Architecture Updates + Lessons Learned + supporting sections, so `codev/reviews/` stays semantically consistent across protocols.

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

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

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

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

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

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

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

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

package/skeleton/protocols/spir/protocol.md

@@ -79,6 +79,10 @@ Each phase follows a build-verify loop: build the artifact, then verify with 3-w
 - Dependency updates
 - Emergency hotfixes (but do a lightweight retrospective after)
 
+## Baked Decisions (Optional)
+
+When filing an issue for SPIR, you can pin architectural decisions you don't want the builder or CMAP reviewers to re-litigate. Include a `## Baked Decisions` section (any heading level is fine) anywhere in the issue body. Useful categories: language, framework, deployment shape, key dependencies, decisions deferred to a later spec. The builder will copy the section verbatim into the spec's Constraints and treat each item as fixed; CMAP reviewers will not propose alternatives unless the spec itself fails to honor a stated decision. Leave the section out for issues where you want the builder to explore freely — absence is the no-op default. You can amend or rescind a baked decision at any time by updating the issue and respawning, or by sending the builder a direct instruction via `afx send`.
+
 ## Protocol Phases
 
 ### S - Specify (Collaborative Design Exploration)

package/skeleton/templates/AGENTS.md

@@ -12,10 +12,34 @@ This project uses **Codev** for AI-assisted development.
 - **ASPIR**: Autonomous SPIR — no human gates on spec/plan (`codev/protocols/aspir/protocol.md`)
 - **AIR**: Autonomous Implement & Review for small features (`codev/protocols/air/protocol.md`)
 - **BUGFIX**: Bug fixes from GitHub issues (`codev/protocols/bugfix/protocol.md`)
+- **PIR**: Plan / Implement / Review — issue-driven with three human gates (plan-approval, dev-approval, pr) (`codev/protocols/pir/protocol.md`)
 - **EXPERIMENT**: Disciplined experimentation (`codev/protocols/experiment/protocol.md`)
 - **MAINTAIN**: Codebase maintenance (`codev/protocols/maintain/protocol.md`)
 - **RESEARCH**: Multi-agent research with 3-way investigation, synthesis, and critique (`codev/protocols/research/protocol.md`)
 
+## File Resolution (How Codev Finds Protocols and Templates)
+
+Codev resolves protocol files, prompts, agent definitions, and roles through a four-tier lookup (highest priority first):
+
+1. `.codev/<path>` — user override (project-local customization)
+2. `codev/<path>` — project-local copy (customized and checked in)
+3. Runtime cache
+4. **Installed package skeleton** — ships with `@cluesmith/codev` (the default for every standard protocol)
+
+**The absence of `codev/protocols/<name>/` on disk is not a missing reference** — it's the normal case for any protocol you haven't customized. The protocol resolves from the installed package's skeleton at runtime. Only protocols you want to customize need to live in your repo's `codev/protocols/`.
+
+**Implication for `codev update` and CLAUDE.md / AGENTS.md merges:** when an updated template references a protocol, do NOT drop the reference because `codev/protocols/<name>/` is absent locally. The protocol resolves via the package skeleton, and dropping the reference removes it from your available-protocol list while it's still callable from the CLI.
+
+## Protocol Verification (When You Don't Recognize a Protocol Name)
+
+If the user mentions a protocol name you don't immediately recognize, verify against the CLI before responding:
+
+```bash
+afx spawn --protocol <name> --help
+```
+
+This succeeds if the protocol is registered (including via the skeleton fallback in tier 4 of the resolution chain) and errors helpfully otherwise. The CLI is the source of truth — defer to it when in doubt.
+
 ## Key Locations
 
 - **Specs**: `codev/specs/` - Feature specifications (WHAT to build)

package/skeleton/templates/CLAUDE.md

@@ -10,10 +10,34 @@ This project uses **Codev** for AI-assisted development.
 - **ASPIR**: Autonomous SPIR — no human gates on spec/plan (`codev/protocols/aspir/protocol.md`)
 - **AIR**: Autonomous Implement & Review for small features (`codev/protocols/air/protocol.md`)
 - **BUGFIX**: Bug fixes from GitHub issues (`codev/protocols/bugfix/protocol.md`)
+- **PIR**: Plan / Implement / Review — issue-driven with three human gates (plan-approval, dev-approval, pr) (`codev/protocols/pir/protocol.md`)
 - **EXPERIMENT**: Disciplined experimentation (`codev/protocols/experiment/protocol.md`)
 - **MAINTAIN**: Codebase maintenance (`codev/protocols/maintain/protocol.md`)
 - **RESEARCH**: Multi-agent research with 3-way investigation, synthesis, and critique (`codev/protocols/research/protocol.md`)
 
+## File Resolution (How Codev Finds Protocols and Templates)
+
+Codev resolves protocol files, prompts, agent definitions, and roles through a four-tier lookup (highest priority first):
+
+1. `.codev/<path>` — user override (project-local customization)
+2. `codev/<path>` — project-local copy (customized and checked in)
+3. Runtime cache
+4. **Installed package skeleton** — ships with `@cluesmith/codev` (the default for every standard protocol)
+
+**The absence of `codev/protocols/<name>/` on disk is not a missing reference** — it's the normal case for any protocol you haven't customized. The protocol resolves from the installed package's skeleton at runtime. Only protocols you want to customize need to live in your repo's `codev/protocols/`.
+
+**Implication for `codev update` and CLAUDE.md / AGENTS.md merges:** when an updated template references a protocol, do NOT drop the reference because `codev/protocols/<name>/` is absent locally. The protocol resolves via the package skeleton, and dropping the reference removes it from your available-protocol list while it's still callable from the CLI.
+
+## Protocol Verification (When You Don't Recognize a Protocol Name)
+
+If the user mentions a protocol name you don't immediately recognize, verify against the CLI before responding:
+
+```bash
+afx spawn --protocol <name> --help
+```
+
+This succeeds if the protocol is registered (including via the skeleton fallback in tier 4 of the resolution chain) and errors helpfully otherwise. The CLI is the source of truth — defer to it when in doubt.
+
 ## Key Locations
 
 - **Specs**: `codev/specs/` - Feature specifications (WHAT to build)