@cluesmith/codev 3.2.4 → 3.3.0

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

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

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

@@ -1,10 +1,10 @@
 # SPECIFY Phase Prompt
 
-You are executing the **SPECIFY** phase of the SPIR protocol.
+You are executing the **SPECIFY** phase of the ASPIR protocol.
 
-## Your Goal
+## Goal
 
-Create a comprehensive specification document that thoroughly explores the problem space and proposed solution.
+Produce a specification at `codev/specs/{{artifact_name}}.md` that explores the problem space and the proposed solution well enough that the plan and implementation can follow without re-deciding anything.
 
 ## Context
 
@@ -13,133 +13,47 @@ Create a comprehensive specification document that thoroughly explores the probl
 - **Current State**: {{current_state}}
 - **Spec File**: `codev/specs/{{artifact_name}}.md`
 
-## Process
+## What must be true when you finish
 
-### 0. Check for Existing Spec (ALWAYS DO THIS FIRST)
-
-**Before asking ANY questions**, check if a spec already exists:
-
-```bash
-ls codev/specs/{{project_id}}-*.md
-```
-
-**If a spec file exists:**
-1. READ IT COMPLETELY - the answers to your questions are already there
-2. The spec author has already made the key decisions
-3. DO NOT ask clarifying questions - proceed directly to consultation
-4. Your job is to REVIEW and IMPROVE the existing spec, not rewrite it from scratch
-
-**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:
-- What problem is being solved?
-- Who are the stakeholders?
-- What are the constraints?
-- What's in scope vs out of scope?
-- What does success look like?
-
-If this is your first iteration AND no spec exists, ask these questions now and wait for answers.
-
-**CRITICAL**: Do NOT ask questions if a spec already exists. The spec IS the answer.
-
-**On subsequent iterations**: If questions were already answered, acknowledge the answers and proceed to the next step.
-
-### 2. Problem Analysis
-
-Once you have answers, document:
-- The problem being solved (clearly articulated)
-- Current state vs desired state
-- Stakeholders and their needs
-- Assumptions and constraints
-
-### 3. Solution Exploration
-
-Generate multiple solution approaches. For each:
-- Technical design overview
-- Trade-offs (pros/cons)
-- Complexity assessment
-- Risk assessment
-
-### 4. Open Questions
-
-List uncertainties categorized as:
-- **Critical** - blocks progress
-- **Important** - affects design
-- **Nice-to-know** - optimization
-
-### 5. Success Criteria
-
-Define measurable acceptance criteria:
-- Functional requirements (MUST, SHOULD, COULD)
-- Non-functional requirements (performance, security)
-- Test scenarios
-
-### 6. Finalize
-
-After completing the spec draft, signal completion. Porch will run 3-way consultation (Gemini, Codex, Claude) automatically via the verify step. If reviewers request changes, you'll be respawned with their feedback.
+- **An existing spec is honored, not rewritten.** If `codev/specs/{{project_id}}-*.md` already exists, it carries the architect's decisions — read it fully and refine it in place. Clarifying questions are for the case where no spec exists yet; when one does, the spec is the answer.
+- **Baked Decisions are fixed.** If the issue body has a "Baked Decisions" section (any heading level, case-insensitive), copy it verbatim into the spec's Constraints and treat each item as settled — **do not autonomously override** the architect's choices in Solution Exploration. Raise a genuine problem with a baked decision via `afx send architect` rather than overriding it. If two baked decisions contradict each other, do not choose — **pause**, **flag** the contradiction via `afx send`, and wait for resolution.
+- **The problem is characterized before solutions are.** Current state vs desired state, stakeholders, assumptions, and constraints are explicit.
+- **Solutions are explored, not assumed.** More than one approach is considered, each with its trade-offs and risks, before one is recommended.
+- **Open questions are surfaced and ranked** by whether they block progress, shape the design, or are merely nice to know.
+- **Success is measurable.** Acceptance criteria are concrete enough to test against.
 
 ## Output
 
-Create or update the specification file at `codev/specs/{{artifact_name}}.md`.
+Write the spec to `codev/specs/{{artifact_name}}.md` using the template below as its interface — these headings, in this order. A section that genuinely does not apply keeps its heading with a one-line `N/A — [reason]` rather than being deleted. Do not pattern-match an older spec in `codev/specs/` that predates this template.
 
-**IMPORTANT**: Keep spec/plan/review filenames in sync:
-- Spec: `codev/specs/{{artifact_name}}.md`
-- Plan: `codev/plans/{{artifact_name}}.md`
-- Review: `codev/reviews/{{artifact_name}}.md`
+{{> protocols/spir/templates/spec.md}}
 
-## Signals
+Keep the three artifact filenames in sync: spec `codev/specs/{{artifact_name}}.md`, plan `codev/plans/{{artifact_name}}.md`, review `codev/reviews/{{artifact_name}}.md`.
 
-Emit appropriate signals based on your progress:
+## Signals
 
-- When waiting for clarifying question answers, **include your questions in the signal**:
+- Waiting on clarifying-question answers — **put the questions inside the signal**, which is displayed prominently to the user:
   ```
   <signal type=AWAITING_INPUT>
-  Please answer these questions:
-  1. What should the primary use case be - internal tooling or customer-facing?
-  2. What are the key constraints we should consider?
-  3. Who are the main stakeholders?
+  Please answer:
+  1. ...
+  2. ...
   </signal>
   ```
-
-  The content inside the signal tag is displayed prominently to the user.
-
-- After completing the initial spec draft:
+- Initial draft done:
   ```
   <signal>SPEC_DRAFTED</signal>
   ```
 
+## Commit cadence
 
-## Commit Cadence
-
-Make commits at these milestones:
+Commit at each milestone, staging the spec file explicitly:
+```bash
+git add codev/specs/{{artifact_name}}.md
+```
 1. `[Spec {{project_id}}] Initial specification draft`
 2. `[Spec {{project_id}}] Specification with multi-agent review`
 3. `[Spec {{project_id}}] Specification with user feedback`
 4. `[Spec {{project_id}}] Final approved specification`
 
-**CRITICAL**: Never use `git add .` or `git add -A`. Always stage specific files:
-```bash
-git add codev/specs/{{artifact_name}}.md
-```
-
-## Important Notes
-
-1. **Be thorough** - A good spec prevents implementation problems
-3. **Be specific** - Vague specs lead to wrong implementations
-4. **Include examples** - Concrete examples clarify intent
-
-## What NOT to Do
-
-- Don't run `consult` commands yourself (porch handles consultations)
-- Don't include implementation details (that's for the Plan phase)
-- Don't estimate time (AI makes time estimates meaningless)
-- Don't start coding (you're in Specify, not Implement)
-- Don't use `git add .` or `git add -A` (security risk)
+Porch runs the 3-way consultation itself after you signal — do not run `consult`. This is the Specify phase: no implementation detail (that is the plan), no code, no time estimates.

package/skeleton/protocols/aspir/protocol.json

@@ -23,6 +23,16 @@
         "models": ["gemini", "codex", "claude"],
         "parallel": true
       },
+      "checks": {
+        "spec_exists": {
+          "command": "test -f codev/specs/${PROJECT_TITLE}.md",
+          "description": "Spec file must exist before the spec-approval gate"
+        },
+        "spec_has_required_sections": {
+          "command": "grep -qF '## Problem Statement' codev/specs/${PROJECT_TITLE}.md && grep -qF '## Current State' codev/specs/${PROJECT_TITLE}.md && grep -qF '## Desired State' codev/specs/${PROJECT_TITLE}.md && grep -qF '## Success Criteria' codev/specs/${PROJECT_TITLE}.md",
+          "description": "Spec must follow the canonical template delivered by the specify prompt (protocols/spir/templates/spec.md). Required headings: ## Problem Statement, ## Current State, ## Desired State, ## Success Criteria"
+        }
+      },
       "max_iterations": 3,
       "on_complete": {
         "commit": true,

package/skeleton/protocols/aspir/protocol.md

@@ -1,98 +1,52 @@
 # ASPIR Protocol
 
-> **ASPIR** = **A**utonomous **S**pecify → **P**lan → **I**mplement → **R**eview
->
-> Identical to SPIR but without human approval gates on spec and plan phases.
-> Each phase has one build-verify cycle with 3-way consultation.
+Autonomous SPIR: the same phases, artifacts, consultations and checks, with the **spec and plan
+human gates absent**. The builder runs Specify → Plan → Implement without stopping, and a human
+still reviews everything at the `pr` gate before merge.
 
-## What is ASPIR?
+Use ASPIR for trusted, low-risk work where reviewing the approach up front would cost more than
+it saves, and deferring that review to the PR is acceptable. When getting the shape wrong would
+be expensive to unwind, use SPIR and take the gates.
 
-ASPIR is an autonomous variant of the SPIR protocol. It follows the exact same phases (Specify → Plan → Implement → Review) with the same 3-way consultations, checks, and PR flow — but removes the `spec-approval` and `plan-approval` human gates.
+## The state machine
 
-This means the builder proceeds automatically from Specify → Plan → Implement without waiting for human approval at each gate. The `pr` gate in the Review phase is preserved — a human still reviews all code before merge.
+Phases, gates and checks — note that `specify` and `plan` carry **no gate at all**; they are not
+auto-approved, they are ungated:
 
-### Differences from SPIR
-
-| Aspect | SPIR | ASPIR |
-|--------|------|-------|
-| Spec gate (`spec-approval`) | Human must approve | Auto-approved |
-| Plan gate (`plan-approval`) | Human must approve | Auto-approved |
-| PR gate (`pr`) | Human must approve | Human must approve |
-| Phases | Specify → Plan → Implement → Review | Same |
-| 3-way consultations | Yes, every phase | Same |
-| Checks (build, tests, PR) | Yes | Same |
-| Prompts / templates | Full set | Same (copied from SPIR) |
-
-### When to Use ASPIR
-
-Use ASPIR instead of SPIR when:
-
-- The work is **trusted and low-risk** — internal tooling, protocol additions, well-understood features
-- The architect has **pre-written and approved** the spec before spawning
-- The scope is **self-contained** with low blast radius
-- You want **full SPIR discipline** (consultations, phased implementation, review) without waiting at gates
-
-### When NOT to Use ASPIR
-
-Use SPIR instead when:
-
-- The feature involves **novel architecture** or unclear requirements
-- The spec needs **iterative human feedback** during drafting
-- The work is **high-risk** — security-sensitive, user-facing, or broadly impactful
-- You want to **review and adjust** the plan before implementation starts
-
-## Baked Decisions (Optional)
-
-When filing an issue for ASPIR, 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
+```json
+{{> protocols/aspir/protocol.json}}
+```
 
-ASPIR follows the same four phases as SPIR. For full phase documentation, see the [SPIR protocol](../spir/protocol.md).
+## Everything else is SPIR
 
-### S - Specify
-Write specification with 3-way review (Gemini, Codex, Claude). **No human gate** — proceeds directly to Plan after verification.
+Artifacts (`codev/specs/`, `codev/plans/`, `codev/reviews/`, same base filename), the
+build-verify cycle per plan phase, mandatory 3-way consultation at each verify step, the
+machine-readable `phases` block in the plan, commit and branch conventions, and Baked Decisions
+handling are all identical to SPIR. ASPIR includes SPIR's templates rather than copying them, so
+there is one set to keep correct.
 
-### P - Plan
-Write implementation plan with 3-way review. **No human gate** — proceeds directly to Implement after verification and checks pass.
+See `protocols/spir/protocol.md` for that shared substance.
 
-### I - Implement
-Execute each plan phase with build-verify cycle. Same as SPIR — no gate between phases (SPIR also has no gate here).
+## Baked Decisions
 
-### R - Review
-Final review, PR preparation, and 3-way review. **PR gate preserved** — builder stops and waits for human approval before merge.
+An issue may carry a `## Baked Decisions` section pinning architectural choices the architect
+does not want re-litigated — typically **language**, **framework**, deployment shape, key
+**dependencies**, or decisions deferred to a later spec.
 
-## Usage
+Every item in it is fixed. Copy the section verbatim into the spec's Constraints and do not
+re-open it in the spec, plan, or review; CMAP reviewers will not propose alternatives unless the
+spec fails to honour one. If two items contradict each other, do not choose — surface the
+contradiction and wait.
 
-```bash
-# Spawn a builder using ASPIR
-afx spawn 42 --protocol aspir
+**Absence is the no-op default**: an issue with no such section is an invitation to explore
+freely, not an omission to be filled in.
 
-# The builder runs autonomously through Specify → Plan → Implement
-# and stops only at the PR gate in the Review phase
-```
+The architect 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`.
 
-## File Structure
-
-```
-codev/protocols/aspir/
-├── protocol.json          # Protocol definition (SPIR minus gates)
-├── protocol.md            # This file
-├── builder-prompt.md      # Builder instructions (same as SPIR)
-├── prompts/
-│   ├── specify.md         # Specify phase prompt (same as SPIR)
-│   ├── plan.md            # Plan phase prompt (same as SPIR)
-│   ├── implement.md       # Implement phase prompt (same as SPIR)
-│   └── review.md          # Review phase prompt (same as SPIR)
-├── consult-types/
-│   ├── spec-review.md     # Spec consultation guide (same as SPIR)
-│   ├── plan-review.md     # Plan consultation guide (same as SPIR)
-│   ├── impl-review.md     # Impl consultation guide (same as SPIR)
-│   ├── phase-review.md    # Phase consultation guide (same as SPIR)
-│   └── pr-review.md       # PR consultation guide (same as SPIR)
-└── templates/
-    ├── spec.md            # Spec template (same as SPIR)
-    ├── plan.md            # Plan template (same as SPIR)
-    └── review.md          # Review template (same as SPIR)
-```
+## The one thing to be careful about
 
-All files except `protocol.json` and `protocol.md` are identical to their SPIR counterparts.
+Without the spec and plan gates, nothing external catches a misread of the issue until the PR.
+If the spec you write surprises you — if it turns out larger, or more architectural, than the
+issue implied — that is the signal ASPIR was the wrong choice. Say so early rather than
+carrying the misfit through to review.