@cluesmith/codev 3.2.3 → 3.3.0

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

@@ -1,42 +1,28 @@
 # Implementation Review Prompt
 
 ## Context
-You are reviewing implementation work during the Implement phase. A builder has completed a plan phase and needs feedback before proceeding. Your job is to verify the implementation matches the spec and plan.
 
-## CRITICAL: Verify Before Flagging
+You are reviewing implementation work during the Implement phase. A builder has completed a plan phase and needs feedback before proceeding. Verify the implementation matches the spec and plan.
 
-Before requesting changes for missing configuration, incorrect patterns, or framework issues:
-1. **Check `package.json`** for actual dependency versions — framework conventions change between major versions
-2. **Read the actual config files** (or confirm their deliberate absence) before flagging missing configs
-3. **Do not assume** your training data reflects the version in use — verify against project files
-4. If "Previous Iteration Context" is provided, read it carefully before re-raising concerns that were already disputed
+## Verify before flagging
 
-## Focus Areas
-
-1. **Spec Adherence**
-   - Does the implementation fulfill the spec requirements for this phase?
-   - Are acceptance criteria met?
-
-2. **Code Quality**
-   - Is the code readable and maintainable?
-   - Are there obvious bugs or issues?
-   - Are error cases handled appropriately?
+Before requesting changes for missing configuration, wrong patterns, or framework issues, confirm the claim against the project rather than your training data:
 
-3. **Test Coverage**
-   - Are the tests adequate for this phase?
-   - Do tests cover the main paths AND edge cases?
+- Check `package.json` for the actual dependency versions — framework conventions change between major versions.
+- Read the actual config files (or confirm their deliberate absence) before flagging a missing config.
+- If "Previous Iteration Context" is provided, read it before re-raising concerns already disputed.
 
-4. **Plan Alignment**
-   - Does the implementation follow the plan?
-   - Are there plan items skipped or partially completed?
+## Focus Areas
 
-5. **UX Verification** (if spec has UX requirements)
-   - Does the actual user experience match what the spec describes?
-   - If spec says "async" or "non-blocking", is it actually async?
+- **Spec Adherence** — the implementation fulfills the spec requirements for this phase; acceptance criteria are met.
+- **Code Quality** — readable and maintainable; no obvious bugs; error cases handled.
+- **Test Coverage** — tests are adequate for this phase and cover main paths and edge cases.
+- **Plan Alignment** — the implementation follows the plan; no plan items silently skipped.
+- **UX Verification** (if the spec has UX requirements) — the actual behavior matches what the spec describes (e.g. "async"/"non-blocking" really is).
 
 ## Verdict Format
 
-After your review, provide your verdict in exactly this format:
+Provide your verdict in exactly this format — `consult` parses it:
 
 ```
 ---
@@ -50,23 +36,10 @@ KEY_ISSUES:
 ...
 ```
 
-**Verdict meanings:**
-- `APPROVE`: Phase is complete, builder can proceed
-- `REQUEST_CHANGES`: Issues that must be fixed before proceeding
-- `COMMENT`: Minor suggestions, can proceed but note feedback
+- `APPROVE`: phase is complete, builder can proceed.
+- `REQUEST_CHANGES`: issues that must be fixed before proceeding.
+- `COMMENT`: minor suggestions; can proceed but note the feedback.
 
 ## Scoping (Multi-Phase Plans)
 
-When the implementation plan has multiple phases (e.g., scaffolding, landing, media_rtl):
-- **ONLY review work belonging to the current plan phase**
-- The query will specify which phase you are reviewing
-- Do NOT request changes for functionality scheduled in later phases
-- Do NOT flag missing features that are out of scope for this phase
-- If unsure whether something belongs to this phase, check the plan file
-
-## Notes
-
-- This is a phase-level review, not the final PR review
-- Focus on "does this phase work" not "is the whole feature done"
-- If referencing line numbers, use `file:line` format
-- The builder needs actionable feedback to continue
+Review **only the current plan phase** — the query names which one. Do not request changes for functionality scheduled in later phases, and do not flag missing features that are out of scope for this phase. If unsure whether something belongs to this phase, check the plan file. This is a phase-level review ("does this phase work"), not the final PR review.

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

@@ -1,44 +1,24 @@
 # PR Ready Review Prompt
 
 ## Context
-You are performing a final self-check during the Review phase. The builder has completed all implementation phases and is about to create a PR. This is the last check before the work goes to the architect for integration review.
 
-## Focus Areas
-
-1. **Completeness**
-   - Are all spec requirements implemented?
-   - Are all plan phases complete?
-   - Is the review document written (`codev/reviews/XXXX-name.md`)?
-   - Are all commits properly formatted (`[Spec XXXX][Phase]`)?
-
-2. **Test Status**
-   - Do all tests pass?
-   - Is test coverage adequate for the changes?
-   - Are there any skipped or flaky tests?
+You are performing the final self-check during the Review phase — the builder has completed all implementation phases and is about to open the PR. This is the last check before the work goes to the architect for integration review.
 
-3. **Code Cleanliness**
-   - Is there any debug code left in?
-   - Are there any TODO comments that should be resolved?
-   - Are there any `// REVIEW:` comments that weren't addressed?
-   - Is the code properly formatted?
-
-4. **Documentation**
-   - Are inline comments clear where needed?
-   - Is the review document comprehensive?
-   - Are any new APIs documented?
+## Focus Areas
 
-5. **PR Readiness**
-   - Is the branch up to date with its base (the integration branch the PR targets)?
-   - Are commits atomic and well-described?
-   - Is the change diff reasonable in size?
+- **Completeness** — all spec requirements implemented, all plan phases complete, the review document written (`codev/reviews/XXXX-name.md`), and commits in the `[Spec XXXX][Phase]` format.
+- **Test Status** — all tests pass, coverage is adequate for the changes, and any skipped/flaky tests are accounted for.
+- **Code Cleanliness** — no debug code, no stray `TODO` / `// REVIEW:` left unaddressed, code properly formatted.
+- **Documentation** — inline comments clear where needed, the review document comprehensive, new APIs documented.
+- **PR Readiness** — the branch is up to date with its base (the integration branch the PR targets), commits are atomic and well-described, and the diff size is reasonable.
 
 ## Scope
 
-- **DO NOT** flag the syntax of `git diff` examples that appear in review-file prose (e.g., `git diff ci..HEAD` inside a "Files Changed" caption or "How to Test Locally" section). Quoted diff syntax is documentation, not a command. Apply two-dot/three-dot scrutiny only to diffs you compute yourself.
+Do not flag the syntax of `git diff` examples that appear in review-file prose (e.g. `git diff ci..HEAD` inside a "Files Changed" caption or "How to Test Locally" section) — quoted diff syntax is documentation, not a command. Apply two-dot/three-dot scrutiny only to diffs you compute yourself.
 
 ## Verdict Format
 
-After your review, provide your verdict in exactly this format:
+Provide your verdict in exactly this format — `consult` parses it:
 
 ```
 ---
@@ -63,14 +43,8 @@ PR_SUMMARY: |
   - [How to test]
 ```
 
-**Verdict meanings:**
-- `APPROVE`: Ready to create PR
-- `REQUEST_CHANGES`: Issues to fix before PR creation
-- `COMMENT`: Minor items, can create PR but note feedback
-
-## Notes
+- `APPROVE`: ready to create the PR.
+- `REQUEST_CHANGES`: issues to fix before PR creation.
+- `COMMENT`: minor items; can create the PR but note the feedback.
 
-- This is the builder's final self-review before hand-off
-- The PR_SUMMARY in your output can be used as the PR description
-- Focus on "is this ready for someone else to review" not "is this perfect"
-- Any issues found here are cheaper to fix than during integration review
+The `PR_SUMMARY` block can be used directly as the PR description.

package/skeleton/protocols/maintain/prompts/maintain.md

@@ -47,7 +47,7 @@ For each audit finding:
 3. Build and test: `cd packages/codev && pnpm build && pnpm test`
 4. Commit: `git add <specific-files> && git commit -m "[Maintain] Remove unused X"`
 
-One removal at a time. Verify after each. Never use `git add -A`.
+One removal at a time, verified after each — staging only the specific files that removal touched.
 
 ## Step 4: Sync Documentation
 

package/skeleton/protocols/maintain/protocol.md

@@ -1,284 +1,50 @@
 # MAINTAIN Protocol
 
-## Overview
+Audit → Clean → Sync, in a single pass, then a PR. Two phases, one consultation during the
+maintain phase and one before the PR.
 
-MAINTAIN is a single-pass maintenance protocol for keeping codebases healthy. The builder does all maintenance work in one phase, then creates a PR with a 3-way review.
+Use it for dead code and unused dependencies, quarterly hygiene, pre-release cleanup, and
+keeping the governance docs honest — `arch.md`/`arch-critical.md`,
+`lessons-learned.md`/`lessons-critical.md`, and the `CLAUDE.md`↔`AGENTS.md` twins.
 
-**Core Principle**: Do the work in one pass. Don't over-ceremonialize housekeeping.
+## The state machine
 
-**Key Documents** MAINTAIN keeps current:
-- `codev/resources/arch.md` (COLD reference) + `codev/resources/arch-critical.md` (HOT, always-injected) — Architecture, two tiers (Spec 987)
-- `codev/resources/lessons-learned.md` (COLD reference) + `codev/resources/lessons-critical.md` (HOT, always-injected) — Engineering wisdom, two tiers
-
-The two governance docs are siblings with **different purposes**: `arch.md` owns system shape (services, transports, mental models, verified-wrong assumptions about *this* system); `lessons-learned.md` owns durable engineering wisdom that applies *across* specs. Use the routing matrix below to decide where each fact belongs.
-
-### Lives where: routing facts to the right home
-
-| Type of fact/insight | Lives in |
-|---|---|
-| Current system shape (services, transports, key mental models) | `codev/resources/arch.md` |
-| Mechanism for a unique subsystem | `codev/resources/arch.md` (subsystem section) OR a meta-spec under `codev/architecture/<domain>.md` if the mechanism is large enough to warrant its own doc |
-| A durable engineering pattern that applies across multiple specs | `codev/resources/lessons-learned.md` (COLD reference) |
-| A **behavior-changing, cross-cutting** rule (should change how the next project is built) | `codev/resources/lessons-critical.md` (HOT, capped) — demote to `lessons-learned.md` if full |
-| A **behavior-changing, cross-cutting** architecture invariant (a future builder must know up front) | `codev/resources/arch-critical.md` (HOT, capped) — demote to `arch.md` if full |
-| A spec-narrow fix recipe (reference detail) | `codev/resources/lessons-learned.md` (COLD) — kept as reference; **never** the hot file |
-| A system-shape surprise verified-wrong in production ("looks like X but isn't") | `codev/resources/arch.md` § "Verified-Wrong Assumptions" |
-| Aspirational architectural direction (where we want to go) | The relevant meta-spec or roadmap doc, NOT `arch.md` body |
-| A changelog entry ("we shipped X in spec Y on date Z") | `git log` + the spec/review document — NOT `arch.md`, NOT `lessons-learned.md` |
-| A retired or removed component | Delete the section entirely; do NOT keep a "retired components" graveyard. (`git log` retains history.) |
-
-The most commonly-misrouted entry is the system-shape surprise. If a future reader needs to know "the system *looks* like X but actually does Y," that is system shape and lives in `arch.md`. If they need to know "we learned that doing X is generally a bad idea," that is engineering wisdom and lives in `lessons-learned.md`.
-
-## When to Use
-
-- Before a release (clean slate for shipping)
-- After completing a major feature
-- Quarterly maintenance window
-- When the codebase feels "crusty"
-
-## Execution Model
-
-```
-afx spawn --protocol maintain
-    ↓
-1. MAINTAIN: Audit → Clean → Sync docs (single pass)
-    ↓ (build + test checks, 3-way review)
-2. REVIEW: Create PR
-    ↓ (3-way review)
-Architect reviews → Merge
-```
-
-Two phases total. One consultation during the maintain phase, one before PR.
-
-## Prerequisites
-
-Before starting:
-1. Check `codev/maintain/` for the last run number
-2. Note the base commit: `git log --oneline -1` on the last run file
-3. Focus on changes since then: `git log --oneline <base-commit>..HEAD`
-
----
-
-## The Maintain Phase (Single Pass)
-
-The builder works through these tasks in order, committing as they go.
-
-### Step 1: Audit
-
-Identify what needs fixing. Don't fix yet — just catalog.
-
-**Dead code**:
-```bash
-# Find unused exports (TypeScript)
-npx ts-prune 2>/dev/null || echo "ts-prune not available"
-
-# Find unused dependencies
-npx depcheck 2>/dev/null || echo "depcheck not available"
-```
-
-**Stale documentation**:
-```bash
-# What changed since last maintenance?
-git log --oneline <base-commit>..HEAD
-
-# Check arch.md references still exist
-grep -oE '[a-zA-Z]+/[a-zA-Z/]+\.[a-z]+' codev/resources/arch.md | sort -u | while read f; do
-  [ -e "$f" ] || echo "Missing: $f"
-done
-```
-
-**Stale project tracking**:
-- GitHub Issues that should be closed
-- Labels that need updating
-
-Record findings in the maintenance run file (`codev/maintain/NNNN.md`).
-
-### Step 2: Clean
-
-For each finding from the audit:
-1. Verify it's truly unused (grep the codebase)
-2. Remove it (use `git rm` for tracked files)
-3. Verify build + tests still pass
-4. Commit with `[Maintain] Remove unused X`
-
-**Rules**:
-- One removal at a time — don't batch unrelated changes
-- Verify after each removal — build must pass
-- Use soft deletion for untracked files: `mv file codev/maintain/.trash/$(date +%Y-%m-%d)/`
-- Never use `git add -A` or `git add .`
-
-### Step 3: Sync Documentation
-
-Step 3 is split into two sub-steps: **Audit first, then update.** This split exists because `arch.md` and `lessons-learned.md` accumulate without bound when MAINTAIN does only "what's new" — the audit pass surfaces what should be cut so the update pass is not purely additive.
-
-The `update-arch-docs` skill (at `.claude/skills/update-arch-docs/SKILL.md`) is invoked by both sub-steps. Read it before starting Step 3 so the discipline is fresh.
-
-#### Step 3a: Audit documentation
-
-Invoke the `update-arch-docs` skill in **audit-mode**. The skill reads all four governance files — `codev/resources/arch.md` / `arch-critical.md` and `codev/resources/lessons-learned.md` / `lessons-critical.md` — end-to-end against the discipline below, applies the cuts via the Edit tool, and records each cut's reason in the run file (`codev/maintain/NNNN.md`) under a `## Audit Findings` section. The diff plus the recorded reasons **is** the proposal; the architect's PR review is the human-confirmation step (consistent with the skill's audit-mode).
-
-**Per-arch.md-section pruning checklist** — for each section in `arch.md`, ask:
-- Does it describe **current state**? If aspirational, the section moves to a meta-spec; `arch.md` keeps a 1-paragraph summary + pointer (or nothing, if the meta-spec stands on its own).
-- Does it duplicate a meta-spec? If yes, replace with a 1-paragraph summary + pointer.
-- Is it a per-file enumeration that's gone stale? If yes, prune to the directory shape + a few key files.
-- Is it a changelog/narrative section ("Spec 0042 added X")? If yes, absorb the architecturally-relevant facts and remove the spec-numbered framing.
-- Is the component still alive? If retired, delete the section entirely.
-
-**Per-COLD-`lessons-learned.md`-entry pruning checklist** — for each entry, ask:
-- Is it terse (1–3 sentences)? If multi-paragraph, split or compress.
-- Is the topic section the right home? If filed under "Architecture (continued)" or a spec-numbered section, move it to the right topical home.
-- Is it a duplicate of an adjacent entry? If yes, fold them.
-- (Spec-narrow recipes are **kept** as reference — do not cut them just for being spec-narrow. Anti-accretion now lives in the hot cap, not the cold archive.)
-
-**Per-HOT-file checklist** (`arch-critical.md`, `lessons-critical.md`) — audit the cap and map:
-- Within the cap (≈10 entries + a ≈12-topic map, ≤35 lines)? If over, **demote** the weakest entries into the cold doc.
-- Does every map topic name a real top-level cold-doc section, and is any new/renamed section reflected? Fix drift; keep the map top-level only.
-- Is every entry still behavior-changing? Demote reference detail into the cold archive.
-
-**Sample audit prompt** (paste into the skill invocation if you want a baseline checklist run):
-
-```
-Audit all four governance files — codev/resources/arch.md + arch-critical.md and
-lessons-learned.md + lessons-critical.md — against the discipline in the
-update-arch-docs skill. For each cold section/entry run the cold pruning checklists,
-and for each hot file check the cap, displacement, and map accuracy (Step 3a).
-Apply the cuts with one-line reasons. Bias toward fewer, higher-confidence
-cuts ("when in doubt, KEEP"). Record each cut's reason in the current run
-file's ## Audit Findings section as you go — the diff plus those reasons is the proposal.
-```
-
-**When in doubt, KEEP.** This rule is preserved from the older Step 3. A confident cut is better than three speculative ones. The audit pass is a *proposal*; the architect's PR review confirms it.
-
-#### Step 3b: Update documentation
-
-Apply the audit decisions from Step 3a, plus any additive content needed.
-
-**arch.md / arch-critical.md**: Compare documented structure with actual codebase. Route behavior-changing invariants to `arch-critical.md` (HOT — respect the cap + keep its map accurate); reference detail to `arch.md` (COLD). Update:
-- Directory structure
-- Component descriptions (explain HOW things work, not just WHAT)
-- Key files and their purposes
-- Remove references to deleted code (per Step 3a audit findings)
-- Add new components/utilities
-
-**lessons-learned.md / lessons-critical.md**: Scan `codev/reviews/` for new reviews since last run. **Route** each new lesson by tier — behavior-changing + cross-cutting → `lessons-critical.md` (HOT; respect the cap, demote a weaker entry to cold if full); reference recipe / spec-narrow → `lessons-learned.md` (COLD). Apply Step 3a's per-entry cuts and keep each hot file's cold-doc map accurate.
-
-For specific additive changes, invoke `update-arch-docs` in **diff-mode** — it applies the smallest section update needed.
-
-**CLAUDE.md / AGENTS.md**: Diff the two files. They must be identical. Update the stale one.
-
-**Documentation pruning**:
-- Remove obsolete references
-- ~400 line guideline for CLAUDE.md/README.md (not a hard limit)
-- Document every deletion with justification (OBSOLETE, DUPLICATIVE, MOVED, VERBOSE)
-- When in doubt, KEEP the content
-
-### Step 4: Final Checks
-
-```bash
-# Build and test from the package directory
-cd packages/codev && pnpm build && pnpm test
-```
-
-Both must pass before moving to the review phase.
-
----
-
-## Maintenance Run File
-
-Each run creates `codev/maintain/NNNN.md`:
-
-```markdown
-# Maintenance Run NNNN
-
-**Date**: YYYY-MM-DD
-**Base Commit**: <hash>
-**PR**: #NNN
-
-## Changes Since Last Run
-
-<key commits summary>
-
-## Audit Findings
-
-Recorded by Step 3a (Audit documentation) as the cuts are applied — one line per cut, with its reason. The diff plus these reasons is the proposal; the architect's PR review is the gate.
-
-### arch.md (cold) / arch-critical.md (hot)
-- <section or hot entry>: <reason for cut / compression / demotion>
-
-### lessons-learned.md (cold) / lessons-critical.md (hot)
-- <entry>: <reason; note hot→cold demotions and any cold-doc-map fixes>
-
-## What Was Done
-
-### Dead Code Removed
-- `path/to/file.ts`: `unusedFunction()` — not imported anywhere
-- Removed `some-package` dependency — zero imports
-
-### Documentation Updated
-- arch.md / arch-critical.md: Added VS Code extension section + removed old dashboard-server refs (cold); routed 1 invariant to the hot tier, demoted 1 stale entry to cold
-- lessons-learned.md / lessons-critical.md: Extracted 3 lessons from reviews 653, 672 (cold); promoted 1 behavior-changer to the hot tier, refreshed its cold-doc map
-
-### Documentation Changes Log
-| Document | Section | Action | Reason |
-|----------|---------|--------|--------|
-| arch.md | "Dashboard Server" | DELETED | OBSOLETE — replaced by Tower |
-
-## Deferred
-
-- Items found but not worth fixing now
-
-## Summary
-
-<2-3 sentences>
+```json
+{{> protocols/maintain/protocol.json}}
 ```
 
-Keep it factual and short. The run file documents what happened, not what might happen.
+## Before starting
 
----
-
-## Commit Messages
-
-```
-[Maintain] Remove 5 unused exports
-[Maintain] Remove http-proxy dependency
-[Maintain] Update arch.md — add VS Code extension, remove dashboard-server refs
-[Maintain] Generate lessons-learned.md from reviews 653, 672
-[Maintain] Sync CLAUDE.md with AGENTS.md
-```
+Find the last run in `codev/maintain/`, note its base commit, and scope the audit to
+`git log --oneline <base>..HEAD`. Maintenance without a since-marker re-audits the whole
+repository every time and quietly stops being run.
 
----
+## The maintain phase
 
-## Governance
+**Audit** — find unused exports, unused dependencies, and orphaned files. Treat every hit as a
+*candidate*, not a verdict: a detector cannot tell "vestigial" from "used by a path you did not
+search". Confirm each with a targeted grep before removing it.
 
-MAINTAIN is an operational protocol, not a feature protocol:
+**Clean** — remove what you confirmed. Deletions go to `codev/maintain/.trash/` (gitignored,
+30-day retention) rather than straight out, so a wrong call is recoverable for a month rather
+than needing an archaeology session.
 
-| Document | Required? |
-|----------|-----------|
-| Spec | No |
-| Plan | No |
-| Review | No (maintenance run file serves this purpose) |
-| Consultation | Yes — 3-way review before PR |
+**Sync documentation** — route facts by tier rather than appending: behaviour-changing and
+cross-cutting go to the capped hot files (displace a weaker entry rather than growing them),
+reference detail to the cold archives. The `update-arch-docs` skill encodes the routing matrix,
+the caps, and what does *not* belong in each tier. Keep `CLAUDE.md` and `AGENTS.md`
+byte-identical.
 
-If maintenance reveals need for architectural changes, those should follow SPIR.
+## The maintenance run file
 
----
+Each run is recorded in `codev/maintain/` using this structure:
 
-## Rules
+{{> protocols/maintain/templates/maintenance-run.md}}
 
-1. **Don't be aggressive** — when in doubt, KEEP the content
-2. **Check git blame** — understand why code/docs exist before removing
-3. **Run full test suite** — not just affected tests
-4. **Group related changes** — one commit per logical change
-5. **Document every deletion** — what, why, and where (if moved)
-6. **Prefer moving over deleting** — extract to another file rather than removing
-7. **Size targets are guidelines** — never sacrifice clarity to hit a line count
+## Scope discipline
 
-## Anti-Patterns
+Maintenance is where scope creep is most tempting, because everything you touch looks
+improvable. Removing dead code is in scope; refactoring live code because you are already in the
+file is not. File an issue instead.
 
-1. Aggressive rewriting without explanation
-2. Deleting without documenting why
-3. Hitting line count targets at all costs
-4. Removing "patterns" or "best practices" sections without explicit approval
-5. Deleting everything the audit finds — review each item individually
-6. Skipping validation — "it looked dead" is not validation
-7. Using `rm` instead of `git rm`
+Never `git add -A` / `--all` / `.` — stage each file explicitly by path.

package/skeleton/protocols/maintain/templates/maintenance-run.md

@@ -8,6 +8,16 @@
 
 <key commits or summary>
 
+## Audit Findings
+
+Recorded by Step 3a (Audit documentation) as the cuts are applied — one line per cut, with its reason. The diff plus these reasons is the proposal; the architect's PR review is the gate.
+
+### arch.md (cold) / arch-critical.md (hot)
+- <section or hot entry>: <reason for cut / compression / demotion>
+
+### lessons-learned.md (cold) / lessons-critical.md (hot)
+- <entry>: <reason; note hot→cold demotions and any cold-doc-map fixes>
+
 ## What Was Done
 
 ### Dead Code Removed
@@ -23,6 +33,7 @@
 ### Documentation Changes Log
 | Document | Section | Action | Reason |
 |----------|---------|--------|--------|
+| | | | |
 
 ## Deferred
 

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

@@ -1,38 +1,24 @@
 # {{protocol_name}} Builder ({{mode}} mode)
 
-You are implementing a fix or feature driven by a GitHub issue, using the PIR protocol.
+You are implementing {{input_description}}.
 
 {{#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
+
+You follow the protocol yourself; the architect verifies compliance.
 {{/if}}
 
 {{#if mode_strict}}
 ## Mode: STRICT
-You are running in STRICT mode. This means:
-- Porch orchestrates your work
-- Run: `porch next` to get your next tasks
-- Follow porch signals and gate approvals
-- 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
+
+Porch orchestrates. `porch next` gives you tasks; `porch done` signals completion. Never
+hand-edit `status.yaml` — only porch commands modify project state.
 {{/if}}
 
 ## Protocol
-Follow the PIR protocol. Read and internalize the protocol before starting any work. The full protocol text is included below under **## Protocol Reference (full text)**.
 
-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 3-way consultation (Gemini, Codex, Claude) 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.**
+The full protocol text is inlined below under **## Protocol Reference (full text)** — you do not
+need to fetch it.
 
 {{#if issue}}
 ## Issue #{{issue.number}}
@@ -44,54 +30,34 @@ PIR has three phases:
 
 ## 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.
+PIR has two pre-PR human gates. When you reach one:
 
-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]"`
+1. Finish the phase work and run `porch done <id>`
+2. Run `porch next <id>` — you get a `gate_pending` response
+3. End your turn with a short summary: what you wrote, where it lives, how to approve
+4. **Stay in the interactive session. Do not exit.** Wait for the next message.
 
-**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.
+Feedback can arrive four ways, and all of them reach you: the reviewer editing the plan file or
+the code directly in the worktree (you see it via `git diff`), typing into your PTY pane (live),
+`afx send <your-builder-id>` (queued — check next turn), or a comment on the GitHub issue
+(re-fetch with `gh issue view <N> --comments`).
 
-## 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
+Revise, recommit, ask whether more remains. **The gate stays pending until the human runs
+`porch approve` — never call it yourself.**
 
 ## 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 `DEFAULT_BRANCH=$(git symbolic-ref --short refs/remotes/origin/HEAD 2>/dev/null | sed 's|^origin/||'); git diff "$(git merge-base "${DEFAULT_BRANCH:-main}" HEAD)"` (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
+If your session crashes, Tower's launch loop **resumes your conversation** (`--resume` against the
+session id pinned at spawn) and sends a short re-orientation nudge — your context is intact, so
+re-check state and continue. Only an unresumable session (repeated fast failures) falls back to a
+fresh relaunch with the same spawn prompt. On a fresh relaunch:
 
-1. Read the PIR protocol (provided inline in this prompt).
-2. Run `porch next {{project_id}}` to see what to do next
-3. Begin work
+1. `porch next {{project_id}}` to learn what phase you are in
+2. If `gate_pending`: read the latest plan file (plan-approval), or the diff (dev-approval) via
+   `DEFAULT_BRANCH=$(git symbolic-ref --short refs/remotes/origin/HEAD 2>/dev/null | sed 's|^origin/||'); git diff "$(git merge-base "${DEFAULT_BRANCH:-main}" HEAD)"`, plus any new issue comments and your `afx send` queue. Decide whether to revise or just announce you are back
+3. Otherwise pick up where you left off
 
----
-
-## Protocol Reference (full text)
+## Notifications
 
-{{protocol_reference}}
+The architect is not watching. `afx send architect "..."` at each of: gate reached, PR ready, PR
+merged, blocked.