@cluesmith/codev 3.2.4 → 3.3.0

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.

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

@@ -1,40 +1,28 @@
 # Specification Review Prompt
 
 ## Context
-You are reviewing a feature specification during the Specify phase. Your role is to ensure the spec is complete, correct, and feasible before it moves to human approval.
+
+You are reviewing a feature specification during the Specify phase, before it goes to human approval. Judge whether the spec is complete, correct, feasible, and clear enough for a builder to plan from.
 
 ## Baked Decisions
 
 If the issue body or the spec's Constraints section includes content under a "Baked Decisions" heading, the architect has marked those choices as fixed. Do not autonomously challenge them: do not propose alternative languages, frameworks, deployment shapes, or dependencies that contradict a baked decision. You may `COMMENT` with concerns about a baked decision (the architect decides whether to rescind it); reserve `REQUEST_CHANGES` for the case where the spec **fails to honor** a stated baked decision — that is a real defect.
 
-If the baked decisions themselves contain contradictions (e.g., two different language choices), do not pick one — `REQUEST_CHANGES` and ask the architect to clarify before proceeding.
+If the baked decisions themselves contradict each other (e.g., two different language choices), do not pick one — `REQUEST_CHANGES` and ask the architect to clarify before proceeding.
 
 ## Focus Areas
 
-1. **Completeness**
-   - Are all requirements clearly stated?
-   - Are success criteria defined?
-   - Are edge cases considered?
-   - Is scope well-bounded (not too broad or vague)?
-
-2. **Correctness**
-   - Do requirements make sense technically?
-   - Are there contradictions?
-   - Is the problem statement accurate?
-
-3. **Feasibility**
-   - Can this be implemented with available tools/constraints?
-   - Are there obvious technical blockers?
-   - Is the scope realistic for a single spec?
+- **Completeness** — requirements, success criteria, and edge cases are stated; scope is bounded, not vague.
+- **Correctness** — the requirements are technically sound and internally consistent; the problem statement is accurate.
+- **Feasibility** — implementable within the stated tools and constraints, with no obvious blockers.
+- **Clarity** — a builder would know what to build; acceptance criteria are testable; terminology is consistent.
+- **Structure** — the spec follows the delivered template (`protocols/spir/templates/spec.md`), which the specify prompt inlines. A spec that ignores the template's headings — usually because the builder pattern-matched an older spec in `codev/specs/` — is a defect: `REQUEST_CHANGES` for a wholesale departure (most headings missing or renamed). A single genuinely-inapplicable section reduced to a one-line "N/A — [reason]" with its heading kept is fine, not grounds for `REQUEST_CHANGES`.
 
-4. **Clarity**
-   - Would a builder understand what to build?
-   - Are acceptance criteria testable?
-   - Is terminology consistent?
+You are reviewing the specification (WHAT is built), not code or implementation (HOW) — that is the plan and implementation reviews. Be constructive: name the issue and suggest a fix.
 
 ## Verdict Format
 
-After your review, provide your verdict in exactly this format:
+Provide your verdict in exactly this format — `consult` parses it:
 
 ```
 ---
@@ -48,14 +36,6 @@ KEY_ISSUES:
 ...
 ```
 
-**Verdict meanings:**
-- `APPROVE`: Spec is ready for human review
-- `REQUEST_CHANGES`: Significant issues must be fixed before proceeding
-- `COMMENT`: Minor suggestions, can proceed but consider feedback
-
-## Notes
-
-- You are NOT reviewing code - you are reviewing the specification document
-- Focus on WHAT is being built, not HOW it will be implemented (that's for plan review)
-- Be constructive - identify issues AND suggest solutions
-- If the spec references other specs, note if context seems missing
+- `APPROVE`: spec is ready for human review.
+- `REQUEST_CHANGES`: significant issues must be fixed first.
+- `COMMENT`: minor suggestions; can proceed but consider the feedback.