@cluesmith/codev 3.2.4 → 3.3.1

package/skeleton/protocols/air/protocol.md

@@ -1,91 +1,60 @@
 # AIR Protocol
 
-> **AIR** = **A**utonomous **I**mplement & **R**eview
->
-> A lightweight protocol for small features that are fully specified by their GitHub issue.
-> Two phases: Implement → Review. No spec/plan artifacts.
+**A**utonomous **I**mplement → **R**eview. The lightest protocol that still produces a reviewed
+PR: no spec, no plan, no artifact files. The GitHub issue *is* the specification, and the review
+lives in the PR body.
 
-## What is AIR?
+Use AIR when a small feature (roughly <300 LOC) is fully described by its issue and needs no
+architectural decision, no new abstraction, and no significant refactor. If the issue leaves the
+approach genuinely open, the cost of a spec is lower than the cost of building the wrong thing —
+use SPIR or ASPIR. For a defect rather than a feature, use BUGFIX.
 
-AIR is a minimal protocol for implementing small features (< 300 LOC) where the GitHub issue provides all the requirements. It skips the Specify and Plan phases entirely — the builder implements directly from the issue and creates a PR with the review embedded in the PR body.
+## The state machine
 
-### How AIR Compares
-
-| Aspect | BUGFIX | AIR | ASPIR/SPIR |
-|--------|--------|-----|------------|
-| **Use case** | Bug fixes | Small features | New features |
-| **Input** | GitHub Issue | GitHub Issue | GitHub Issue → Spec |
-| **Phases** | Investigate → Fix → PR | Implement → PR | Specify → Plan → Implement → Review |
-| **Artifacts** | None | None | Spec, plan, review files |
-| **Review location** | PR body | PR body | `codev/reviews/` file |
-| **Consultation** | PR phase only | Optional (builder decides) | Every phase (3-way) |
-| **Human gates** | None (PR gate) | None (PR gate) | Spec + Plan + PR gates (SPIR) |
-| **LOC limit** | < 300 | < 300 | No limit |
-
-### When to Use AIR
-
-- Small features (< 300 LOC)
-- Requirements are clear from the GitHub issue
-- No architectural decisions needed
-- No new abstractions or significant refactoring required
-- Would be overkill for full SPIR/ASPIR ceremony
-
-### When NOT to Use AIR
-
-- Bug fixes → use **BUGFIX**
-- Features needing spec discussion → use **SPIR** or **ASPIR**
-- Architectural changes → use **SPIR**
-- Complex features with multiple phases → use **SPIR** or **ASPIR**
-
-## Baked Decisions (Optional)
+```json
+{{> protocols/air/protocol.json}}
+```
 
-When filing an issue for AIR, 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 treat each listed item as fixed during implementation; CMAP reviewers will not propose alternatives unless the implementation 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`.
+## Artifacts
 
-## Protocol Phases
+**None on disk.** The issue carries the requirements; the review goes in the PR body. That is
+the whole economy of AIR — a `codev/reviews/` file for a 200-line change costs more to maintain
+than it ever repays.
 
-### I - Implement
+## Consultation
 
-The builder reads the GitHub issue and implements the feature:
+At the builder's discretion, unlike SPIR's mandatory 3-way at every phase. Reach for it when the
+change touches shared code or you are unsure the approach is right; skip it when the issue is
+unambiguous and the diff is small.
 
-1. Read and understand the issue requirements
-2. Implement the feature (< 300 LOC)
-3. Write tests
-4. Verify build and tests pass
-5. Commit with descriptive message
+## Gate
 
-If the feature grows beyond 300 LOC or requires architectural decisions, the builder signals `TOO_COMPLEX` to escalate to ASPIR.
+The `pr` gate is human. There are no pre-implementation gates — which is precisely why AIR is
+only appropriate when the issue has already settled the questions a spec would ask.
 
-### R - Review (PR)
+## Baked Decisions
 
-The builder creates a PR with the review embedded in the PR body:
+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.
 
-1. Create PR linking to the issue
-2. Include a review section in the PR body (summary, key decisions, test plan)
-3. Optionally run CMAP consultation if the builder judges the complexity warrants it
-4. Notify the architect
+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.
 
-The **PR gate** is preserved — a human reviews all code before merge.
+**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.
 
-## Usage
+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`.
 
-```bash
-# Spawn a builder using AIR
-afx spawn 42 --protocol air
+## Escalation
 
-# The builder implements autonomously and stops at the PR gate
-```
+If implementation reveals that the change is not small, or that it needs a decision the issue
+does not make, **stop and say so** rather than growing an AIR project into an unplanned SPIR.
+Escalating early is cheap; discovering it at PR review is not.
 
-## File Structure
+## Branch naming
 
-```
-codev-skeleton/protocols/air/
-├── protocol.json          # Protocol definition
-├── protocol.md            # This file
-├── builder-prompt.md      # Builder instructions (Handlebars template)
-├── prompts/
-│   ├── implement.md       # Implement phase prompt
-│   └── pr.md              # PR phase prompt
-└── consult-types/
-    ├── impl-review.md     # Implementation consultation guide
-    └── pr-review.md       # PR consultation guide
-```
+`builder/air-<issue>-<short-description>`

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

@@ -4,36 +4,33 @@ You are implementing {{input_description}}.
 
 {{#if mode_soft}}
 ## Mode: SOFT
-You are running in SOFT mode. This means:
-- You follow the 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 the 3-way review** — always follow porch next → porch done cycle
-- **NEVER advance plan phases manually** — porch handles phase transitions after unanimous review 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 ASPIR protocol. Read and internalize the protocol before starting any work. The full protocol text is included below under **## Protocol Reference (full text)**.
+
+Follow the ASPIR protocol. The full protocol text is inlined below under **## Protocol Reference (full text)** — you do not
+need to fetch it.
 
 ## 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 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 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
@@ -53,37 +50,25 @@ Follow the implementation plan at: `{{plan.path}}`
 {{issue.body}}
 {{/if}}
 
-{{#if task}}
-## Task
-{{task_text}}
-{{/if}}
-
 ## 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.
+**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.
 
-### Multi-PR Mechanics (when the architect requests sequential PRs)
+By default, the PR is opened during/after the final implement phase, with all phase-commits
+already on the branch.
 
-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:
+The architect MAY request a PR at any point — follow that direction when they do; the
+prohibition is on *you* deciding to open per-phase PRs unasked.
 
-1. Cut a branch, open a PR, wait for merge
-2. After merge: `git fetch origin <integration-branch> && git checkout -b <next-branch> origin/<integration-branch>` — where `<integration-branch>` is the branch the architect targets PRs at (usually `main`; check the open PR's `baseRefName` if unsure)
-3. Continue to the next slice, open another PR
-
-**Important**: Do NOT run `git checkout <integration-branch>` — git worktrees cannot check out a branch that's checked out elsewhere. Always branch off `origin/<integration-branch>` via fetch.
-
-Record PRs: `porch done {{project_id}} --pr <N> --branch <name>`
-Record merges: `porch done {{project_id}} --merged <N>`
+Record them: `porch done {{project_id}} --pr <N> --branch <name>`, and
+`porch done {{project_id}} --merged <N>`.
 
 ## Verify Phase
 
-After the final PR merges, the project enters the **verify** phase. You stay alive through verify:
+After the final PR merges the project enters **verify**, and you stay alive through it:
+
 1. Pull the integration branch into your worktree
 2. Run `porch done {{project_id}}` to signal verification is ready
 3. The architect approves `verify-approval` when satisfied
@@ -91,28 +76,6 @@ After the final PR merges, the project enters the **verify** phase. You stay ali
 If verification is not needed: `porch verify {{project_id}} --skip "reason"`
 
 ## Notifications
-Always use `afx send architect "..."` to notify the architect at key moments:
-- **Gate reached**: `afx send architect "Project {{project_id}}: <gate-name> ready for approval"`
-- **PR ready**: `afx send architect "PR #N ready for review (project {{project_id}})"`
-- **PR merged**: `afx send architect "Project {{project_id}} PR merged. Entering verify phase."`
-- **Blocked**: `afx send architect "Blocked on project {{project_id}}: [reason]"`
-
-## 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 your review under a `## Flaky Tests` section
-5. Commit the skip and continue with your work
-
-## Getting Started
-1. Read the protocol document thoroughly
-2. Review the spec and plan (if available)
-3. Begin implementation following the protocol phases
-
----
-
-## Protocol Reference (full text)
 
-{{protocol_reference}}
+The architect is not watching. `afx send architect "..."` at each of: gate reached, PR ready, PR
+merged, blocked.

package/skeleton/protocols/aspir/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/aspir/consult-types/phase-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/aspir/consult-types/plan-review.md

@@ -1,44 +1,28 @@
 # Plan Review Prompt
 
 ## 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.
+
+You are reviewing an implementation plan during the Plan phase. The spec is already approved; judge 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 issue body or the approved 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; 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.
+If the baked decisions themselves contradict each other, do not pick one — `REQUEST_CHANGES` and ask the architect to clarify before proceeding.
 
 ## Focus Areas
 
-1. **Spec Coverage**
-   - Does the plan address all requirements in the spec?
-   - Are there spec requirements not covered by any phase?
-   - Are there phases that go beyond the spec scope?
-
-2. **Phase Breakdown**
-   - Are phases appropriately sized (not too large or too small)?
-   - Is the sequence logical (dependencies respected)?
-   - Can each phase be completed and committed independently?
-
-3. **Technical Approach**
-   - Is the implementation approach sound?
-   - Are the right files/modules being modified?
-   - Are there obvious better approaches being missed?
+- **Spec coverage** — every spec requirement is addressed by some phase; nothing goes beyond the spec's scope.
+- **Phase breakdown** — phases are appropriately sized, logically sequenced (dependencies respected), and each can be completed and committed independently.
+- **Technical approach** — the approach is sound, the right files/modules are targeted, and no obviously better approach is being missed.
+- **Testability** — each phase has clear test criteria and the spec's edge cases are addressable.
+- **Risk** — blockers and cross-system dependencies are identified; the plan is realistic given the constraints.
 
-4. **Testability**
-   - Does each phase have clear test criteria?
-   - Will the Defend step (writing tests) be feasible?
-   - Are edge cases from the spec addressable?
-
-5. **Risk Assessment**
-   - Are there potential blockers not addressed?
-   - Are dependencies on other systems identified?
-   - Is the plan realistic given constraints?
+The spec is already approved — do not re-litigate spec decisions. Judge the plan as a guide a builder can follow successfully; verify referenced file paths look accurate.
 
 ## Verdict Format
 
-After your review, provide your verdict in exactly this format:
+Provide your verdict in exactly this format — `consult` parses it:
 
 ```
 ---
@@ -52,14 +36,6 @@ KEY_ISSUES:
 ...
 ```
 
-**Verdict meanings:**
-- `APPROVE`: Plan is ready for human review
-- `REQUEST_CHANGES`: Significant issues with approach or coverage
-- `COMMENT`: Minor suggestions, plan is workable but could improve
-
-## Notes
-
-- The spec has already been approved - don't re-litigate spec decisions
-- Focus on the quality of the plan as a guide for builders
-- Consider: Would a builder be able to follow this plan successfully?
-- If referencing existing code, verify file paths seem accurate
+- `APPROVE`: plan is ready for human review.
+- `REQUEST_CHANGES`: significant issues with approach or coverage.
+- `COMMENT`: minor suggestions; the plan is workable but could improve.

package/skeleton/protocols/aspir/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.