@sienklogic/plan-build-run 2.1.0 → 2.1.1

package/plugins/cursor-pbr/skills/review/SKILL.md

@@ -1,32 +1,52 @@
 ---
 name: review
 description: "Verify the build matched the plan. Automated checks + walkthrough with you."
-argument-hint: "<phase-number> [--auto-fix] [--teams]"
+argument-hint: "<phase-number> [--auto-fix] [--teams] [--model <model>]"
 ---
 
-# /pbr:review — Phase Review and Verification
+**STOP — DO NOT READ THIS FILE. You are already reading it. This prompt was injected into your context by Claude Code's plugin system. Using the Read tool on this SKILL.md file wastes ~7,600 tokens. Begin executing Step 1 immediately.**
 
-You are the orchestrator for `/pbr:review`. This skill verifies that what was built matches what was planned. It runs automated three-layer checks against must-haves, then walks the user through a conversational UAT (user acceptance testing) for each deliverable. Your job is to present findings clearly and help the user decide what's good enough versus what needs fixes.
+# /pbr:verify-work — Phase Review and Verification
+
+**References:** `@references/questioning.md`, `@references/ui-brand.md`
+
+You are the orchestrator for `/pbr:verify-work`. This skill verifies that what was built matches what was planned. It runs automated three-layer checks against must-haves, then walks the user through a conversational UAT (user acceptance testing) for each deliverable. Your job is to present findings clearly and help the user decide what's good enough versus what needs fixes.
 
 ## Context Budget
 
 Reference: `skills/shared/context-budget.md` for the universal orchestrator rules.
 
 Additionally for this skill:
-- **Minimize** reading agent output — read only VERIFICATION.md frontmatter for summaries
+- **Minimize** reading subagent output — read only VERIFICATION.md frontmatter for summaries
 
 ## Step 0 — Immediate Output
 
 **Before ANY tool calls**, display this banner:
 
 ```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- PLAN-BUILD-RUN ► REVIEWING PHASE {N}
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► REVIEWING PHASE {N}                        ║
+╚══════════════════════════════════════════════════════════════╝
 ```
 
 Where `{N}` is the phase number from `$ARGUMENTS`. Then proceed to Step 1.
 
+## Multi-Session Sync
+
+Before any phase-modifying operations (writing VERIFICATION.md, updating STATE.md/ROADMAP.md), acquire a claim:
+
+```
+acquireClaim(phaseDir, sessionId)
+```
+
+If the claim fails (another session owns this phase), display: "Another session owns this phase. Use `/pbr:progress` to see active claims."
+
+On completion or error (including all exit paths), release the claim:
+
+```
+releaseClaim(phaseDir, sessionId)
+```
+
 ## Prerequisites
 
 - `.planning/config.json` exists
@@ -34,9 +54,9 @@ Where `{N}` is the phase number from `$ARGUMENTS`. Then proceed to Step 1.
 
 ### Event-Driven Auto-Verification
 
-When `features.goal_verification` is enabled and depth is "standard" or "comprehensive", event hooks automatically queue verification after executor completion. The hook writes `.planning/.auto-verify` as a signal file. The build skill's orchestrator detects this signal and invokes the verifier agent.
+When `features.goal_verification` is enabled and depth is "standard" or "comprehensive", the `event-handler.js` hook automatically queues verification after executor completion. The hook writes `.planning/.auto-verify` as a signal file. The build skill's orchestrator detects this signal and spawns the verifier agent.
 
-**This is additive**: `/pbr:review` can always be invoked manually regardless of auto-verification settings. If auto-verification already ran, `/pbr:review` re-runs verification (useful for re-checking after fixes).
+**This is additive**: `/pbr:verify-work` can always be invoked manually regardless of auto-verification settings. If auto-verification already ran, `/pbr:verify-work` re-runs verification (useful for re-checking after fixes).
 
 ---
 
@@ -49,6 +69,7 @@ Parse `$ARGUMENTS` according to `skills/shared/phase-argument-parsing.md`.
 | `3` | Review phase 3 |
 | `3 --auto-fix` | Review phase 3, automatically diagnose and create gap-closure plans for failures |
 | `3 --teams` | Review phase 3 with parallel specialist verifiers (functional + security + performance) |
+| `3 --model opus` | Use opus for all verifier spawns in phase 3 (overrides config verifier_model) |
 | (no number) | Use current phase from STATE.md |
 
 ---
@@ -61,34 +82,53 @@ Execute these steps in order.
 
 ### Step 1: Parse and Validate (inline)
 
+**Init-first pattern**: When spawning agents, pass the output of `node plugins/pbr/scripts/pbr-tools.js init verify-work {N}` as context rather than having the agent read multiple files separately. This reduces file reads and prevents context-loading failures.
+
 1. Parse `$ARGUMENTS` for phase number and `--auto-fix` flag
+   - If `--model <value>` is present in `$ARGUMENTS`, extract the value (sonnet, opus, haiku, inherit). Store as `override_model`. When spawning verifier Task() agents, use `override_model` instead of the config-derived verifier_model. If an invalid value is provided, display an error and list valid values.
 2. Read `.planning/config.json`
+   **CRITICAL (hook-enforced): Write .active-skill NOW.** Write the text "review" to `.planning/.active-skill` using the Write tool.
 3. Resolve depth profile: run `node ${PLUGIN_ROOT}/scripts/pbr-tools.js config resolve-depth` to get the effective feature/gate settings for the current depth. Store the result for use in later gating decisions.
 4. Validate:
    - Phase directory exists at `.planning/phases/{NN}-{slug}/`
    - SUMMARY.md files exist (phase has been built)
    - PLAN.md files exist (needed for must-have extraction)
 5. If no phase number given, read current phase from `.planning/STATE.md`
-6. If `.planning/.auto-verify` signal file exists, read it and note the auto-verification was already queued. Delete the signal file after reading (one-shot).
+6. If `.planning/.auto-verify` signal file exists, read it and note the auto-verification was already queued. Delete the signal file after reading (one-shot, same pattern as auto-continue.js).
+
+**Validation errors:**
+
+If phase directory not found, use conversational recovery:
 
-**Validation errors — use branded error boxes:**
+1. Run: `node ${PLUGIN_ROOT}/scripts/pbr-tools.js suggest-alternatives phase-not-found {slug}`
+2. Parse the JSON response to get `available` phases and `suggestions` (closest matches).
+3. Display: "Phase '{slug}' not found. Did you mean one of these?"
+   - List `suggestions` (if any) as numbered options.
+   - Offer "Show all phases" to list `available`.
+4. Use AskUserQuestion (pattern: yes-no-pick from `skills/shared/gate-prompts.md`) to let the user pick a phase or abort.
+   - If user picks a valid phase slug: re-run with that slug.
+   - If user chooses to abort: stop cleanly with a friendly message.
 
 If no SUMMARY.md files:
 ```
-ERROR
+╔══════════════════════════════════════════════════════════════╗
+║  ERROR                                                       ║
+╚══════════════════════════════════════════════════════════════╝
 
 Phase {N} hasn't been built yet.
 
-**To fix:** Run `/pbr:build {N}` first.
+**To fix:** Run `/pbr:execute-phase {N}` first.
 ```
 
 If no PLAN.md files:
 ```
-ERROR
+╔══════════════════════════════════════════════════════════════╗
+║  ERROR                                                       ║
+╚══════════════════════════════════════════════════════════════╝
 
 Phase {N} has no plans.
 
-**To fix:** Run `/pbr:plan {N}` first.
+**To fix:** Run `/pbr:plan-phase {N}` first.
 ```
 
 ---
@@ -97,7 +137,7 @@ Phase {N} has no plans.
 
 Reference: `skills/shared/config-loading.md` for the tooling shortcut (`phase-info`) and config field reference.
 
-Check if a VERIFICATION.md already exists from `/pbr:build`'s auto-verification step:
+Check if a VERIFICATION.md already exists from `/pbr:execute-phase`'s auto-verification step:
 
 1. Look for `.planning/phases/{NN}-{slug}/VERIFICATION.md`
 2. If it exists:
@@ -112,30 +152,35 @@ Check if a VERIFICATION.md already exists from `/pbr:build`'s auto-verification
 
 ### Step 3: Automated Verification (delegated)
 
-**Depth profile gate:** Before invoking the verifier, resolve the depth profile. If `features.goal_verification` is false in the profile, skip automated verification and proceed directly to Step 5 (Conversational UAT). Note to user: "Automated verification skipped (depth: {depth}). Proceeding to manual review."
+**Depth profile gate:** Before spawning the verifier, resolve the depth profile. If `features.goal_verification` is false in the profile, skip automated verification and proceed directly to Step 5 (Conversational UAT). Note to user: "Automated verification skipped (depth: {depth}). Proceeding to manual review."
 
 #### Team Review Mode
 
 If `--teams` flag is present OR `config.parallelization.use_teams` is true:
 
 1. Create team output directory: `.planning/phases/{NN}-{slug}/team/` (if not exists)
-2. Display to the user: `Spawning 3 verifiers in parallel (functional, security, performance)...`
+2. Display to the user: `◆ Spawning 3 verifiers in parallel (functional, security, performance)...`
 
-   Invoke THREE `@verifier` agents in parallel:
+   Spawn THREE verifier agents in parallel using Task():
 
    **Agent 1 -- Functional Reviewer**:
-   - Invoke `@verifier` with: "You are the FUNCTIONAL REVIEWER in a review team. Focus on: must-haves met, code correctness, completeness, integration points. Write output to `.planning/phases/{NN}-{slug}/team/functional-VERIFY.md`."
+   - subagent_type: "pbr:verifier"
+   - Prompt includes: "You are the FUNCTIONAL REVIEWER in a review team. Focus on: must-haves met, code correctness, completeness, integration points. Write output to `.planning/phases/{NN}-{slug}/team/functional-VERIFY.md`."
 
    **Agent 2 -- Security Auditor**:
-   - Invoke `@verifier` with: "You are the SECURITY AUDITOR in a review team. Focus on: vulnerabilities, auth bypass paths, injection risks, secrets exposure, permission escalation. Write output to `.planning/phases/{NN}-{slug}/team/security-VERIFY.md`."
+   - subagent_type: "pbr:verifier"
+   - Prompt includes: "You are the SECURITY AUDITOR in a review team. Focus on: vulnerabilities, auth bypass paths, injection risks, secrets exposure, permission escalation. Write output to `.planning/phases/{NN}-{slug}/team/security-VERIFY.md`."
 
    **Agent 3 -- Performance Analyst**:
-   - Invoke `@verifier` with: "You are the PERFORMANCE ANALYST in a review team. Focus on: N+1 queries, memory leaks, unnecessary allocations, bundle size impact, blocking operations. Write output to `.planning/phases/{NN}-{slug}/team/performance-VERIFY.md`."
+   - subagent_type: "pbr:verifier"
+   - Prompt includes: "You are the PERFORMANCE ANALYST in a review team. Focus on: N+1 queries, memory leaks, unnecessary allocations, bundle size impact, blocking operations. Write output to `.planning/phases/{NN}-{slug}/team/performance-VERIFY.md`."
 
 3. Wait for all three to complete
-4. Display to the user: `Spawning synthesizer...`
+4. Display to the user: `◆ Spawning synthesizer...`
 
-   Invoke `@synthesizer` with: "Read all *-VERIFY.md files in `.planning/phases/{NN}-{slug}/team/`. Synthesize into a unified VERIFICATION.md. Merge pass/fail verdicts -- a must-have fails if ANY reviewer flags it. Combine gap lists. Security and performance findings go into dedicated sections."
+   Spawn synthesizer:
+   - subagent_type: "pbr:synthesizer"
+   - Prompt: "Read all *-VERIFY.md files in `.planning/phases/{NN}-{slug}/team/`. Synthesize into a unified VERIFICATION.md. Merge pass/fail verdicts -- a must-have fails if ANY reviewer flags it. Combine gap lists. Security and performance findings go into dedicated sections."
 5. Proceed to UAT walkthrough with the unified VERIFICATION.md
 
 If teams not enabled, proceed with existing single-verifier flow.
@@ -144,15 +189,33 @@ Reference: `references/agent-teams.md`
 
 #### Single-Verifier Flow (default)
 
-Display to the user: `Spawning verifier...`
+Display to the user: `◆ Spawning verifier...`
 
-Invoke the `@verifier` agent to run three-layer checks.
+Spawn a verifier Task() to run three-layer checks:
+
+```
+Task({
+  subagent_type: "pbr:verifier",
+  // After verifier completes, check for: ## VERIFICATION COMPLETE
+  prompt: <verifier prompt>
+})
+```
 
-**Path resolution**: Before constructing any agent prompt, resolve plugin root to its absolute path. Do not pass the variable literally in prompts. Use the resolved absolute path for any pbr-tools.js or template references included in the prompt.
+**Path resolution**: Before constructing any agent prompt, resolve `${PLUGIN_ROOT}` to its absolute path. Do not pass the variable literally in prompts — Task() contexts may not expand it. Use the resolved absolute path for any pbr-tools.js or template references included in the prompt.
 
 #### Verifier Prompt Template
 
-Read `skills/review/templates/verifier-prompt.md.tmpl` and use its content as the verifier prompt.
+Read `${CLAUDE_SKILL_DIR}/templates/verifier-prompt.md.tmpl` and use its content as the verifier prompt.
+
+**Prepend this block to the verifier prompt before sending:**
+```
+<files_to_read>
+CRITICAL (no hook): Read these files BEFORE any other action:
+1. .planning/phases/{NN}-{slug}/PLAN-*.md — must-haves to verify against
+2. .planning/phases/{NN}-{slug}/SUMMARY-*.md — executor build summaries
+3. .planning/phases/{NN}-{slug}/VERIFICATION.md — prior verification results (if exists)
+</files_to_read>
+```
 
 **Placeholders to fill before sending:**
 - `{For each PLAN.md file in the phase directory:}` — inline each plan's must_haves frontmatter block
@@ -166,7 +229,7 @@ Wait for the verifier to complete.
 **After the verifier completes**, read VERIFICATION.md frontmatter and display a quick summary before the full results:
 
 ```
-Verifier: {passed}/{total} must-haves verified
+✓ Verifier: {passed}/{total} must-haves verified
 ```
 
 Then show a brief table of must-haves with pass/fail status:
@@ -174,12 +237,37 @@ Then show a brief table of must-haves with pass/fail status:
 ```
 | Must-Have | Status |
 |-----------|--------|
-| {name}    | PASS   |
-| {name}    | FAIL   |
+| {name}    | ✓      |
+| {name}    | ✗      |
 ```
 
 Then display the overall verdict (`PASSED`, `GAPS FOUND`, or `HUMAN NEEDED`) before proceeding to the full results presentation.
 
+### Step 3a: Spot-Check Verifier Output
+
+CRITICAL (no hook): Verify verifier output before proceeding.
+
+1. **VERIFICATION.md exists**: Check `.planning/phases/{NN}-{slug}/VERIFICATION.md` exists on disk
+2. **Status field present**: Read VERIFICATION.md frontmatter — verify `status` field is present and is one of: pass, fail, partial
+3. **Must-haves checked**: Verify `must_haves_checked` count > 0 in frontmatter
+4. **Completion marker**: Look for `## VERIFICATION COMPLETE` in the Task() output
+
+If ANY spot-check fails, present the user with options: **Retry** / **Continue anyway** / **Abort**
+
+---
+
+### Step 3b: Local LLM Verification Quality Check (optional, advisory)
+
+After the verifier completes and writes VERIFICATION.md, if `config.local_llm.enabled` is `true`, run a quality classification:
+
+```bash
+node ${PLUGIN_ROOT}/scripts/pbr-tools.js llm classify SUMMARY ".planning/phases/{NN}-{slug}/VERIFICATION.md"
+```
+
+- If classification is `"thin"` with confidence >= 0.7: warn `"⚠ Verification report appears thin on details — UAT may not catch all gaps. Consider re-running with /pbr:verify-work {N}."`
+- If the command fails or returns null: skip silently (local LLM unavailable)
+- This is advisory only — never block on the result
+
 ---
 
 ### Step 4: Present Verification Results (inline)
@@ -195,16 +283,16 @@ The same gaps have persisted across {attempt} verification attempts.
 Remaining gaps: {count}
 ```
 
-Use the multi-option-escalation pattern from `skills/shared/gate-prompts.md`:
+Use AskUserQuestion (pattern: multi-option-escalation from `skills/shared/gate-prompts.md`):
   question: "Phase {N} has failed verification {attempt} times with {count} persistent gaps. How should we proceed?"
   header: "Escalate"
   options:
     - label: "Accept gaps"   description: "Mark as complete-with-gaps and move on"
-    - label: "Re-plan"       description: "Go back to /pbr:plan {N} with gap context"
-    - label: "Debug"         description: "Invoke /pbr:debug to investigate root causes"
+    - label: "Re-plan"       description: "Go back to /pbr:plan-phase {N} with gap context"
+    - label: "Debug"         description: "Spawn /pbr:debug to investigate root causes"
     - label: "Retry"         description: "Try one more verification cycle"
 
-- **If user selects "Accept gaps":** Follow up with a second question:
+- **If user selects "Accept gaps":** Follow up with a second AskUserQuestion:
     question: "Accept all gaps or pick specific ones to override?"
     header: "Override?"
     options:
@@ -212,16 +300,20 @@ Use the multi-option-escalation pattern from `skills/shared/gate-prompts.md`:
       - label: "Pick specific"  description: "Choose which gaps to mark as false positives"
   - If "Accept all": Update STATE.md status to `complete-with-gaps`, update ROADMAP.md to `verified*`, add a note in VERIFICATION.md about accepted gaps. Proceed to next phase.
   - If "Pick specific": Use the override flow from Step 6 "Gaps Found" section (present each gap for selection).
-- **If user selects "Re-plan":** Suggest `/pbr:plan {N} --gaps` to create targeted fix plans.
+- **If user selects "Re-plan":** Suggest `/pbr:plan-phase {N} --gaps` to create targeted fix plans.
 - **If user selects "Debug":** Suggest `/pbr:debug` with the gap details as starting context.
 - **If user selects "Retry":** Continue with normal Step 5 flow.
 
-**Otherwise**, present results normally:
+**Otherwise**, present results normally using standardized status symbols (`✓` pass, `✗` fail, `⚠` warning — see `@references/ui-brand.md`):
 
 ```
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► VERIFYING                                  ║
+╚══════════════════════════════════════════════════════════════╝
+
 Phase {N}: {name} — Verification Results
 
-Status: {PASSED | GAPS FOUND | HUMAN NEEDED}
+Status: {✓ PASSED | ✗ GAPS FOUND | ⚠ HUMAN NEEDED}
 Attempt: {attempt}
 
 Must-have truths:  {passed}/{total}
@@ -229,15 +321,15 @@ Must-have artifacts: {passed}/{total}
 Must-have key links: {passed}/{total}
 
 {If all passed:}
-All automated checks passed.
+✓ All automated checks passed.
 
 {If gaps found:}
-Gaps found:
+✗ Gaps found:
   1. {gap description} — {failed layer}
   2. {gap description} — {failed layer}
 
 {If human needed:}
-Items requiring your verification:
+⚠ Items requiring your verification:
   1. {item} — {why automated check couldn't verify}
 ```
 
@@ -249,7 +341,7 @@ Walk the user through each deliverable one by one. This is an interactive conver
 
 **For each plan in the phase:**
 
-0. **Filter out ineligible plans**: Read each plan's SUMMARY.md `status` field. Skip plans with `status: failed`, `status: incomplete`, or `status: partial` that have zero committed tasks (check `commits` frontmatter field). Only walk through plans that completed successfully (`status: complete`) or partially with at least one committed task. For each skipped plan, note it to the user: "Skipping plan {plan_id} ({status}) — not eligible for UAT." If ALL plans in the phase are skipped, display: "No plans eligible for UAT walkthrough. All plans in Phase {N} are incomplete or failed. Run `/pbr:build {N}` to retry." and stop.
+0. **Filter out ineligible plans**: Read each plan's SUMMARY.md `status` field. Skip plans with `status: failed`, `status: incomplete`, or `status: partial` that have zero committed tasks (check `commits` frontmatter field). Only walk through plans that completed successfully (`status: complete`) or partially with at least one committed task. For each skipped plan, note it to the user: "Skipping plan {plan_id} ({status}) — not eligible for UAT." If ALL plans in the phase are skipped, display: "No plans eligible for UAT walkthrough. All plans in Phase {N} are incomplete or failed. Run `/pbr:execute-phase {N}` to retry." and stop.
 1. Read the plan's must-haves and SUMMARY.md
 2. Present what was built:
 
@@ -311,33 +403,34 @@ If all automated checks and UAT items passed:
    4. Update the `Status` column to `verified`
    5. Update the `Completed` column to the current date (YYYY-MM-DD)
    6. Save the file — do NOT skip this step
-2. Update `.planning/STATE.md`:
-   - Phase status: "verified"
-   - Progress updated
-   - Last activity timestamp
+2. Update `.planning/STATE.md` **(CRITICAL (no hook) — update BOTH frontmatter AND body):**
+   - Frontmatter: `status: "verified"`, `progress_percent`, `last_activity`, `last_command`
+   - Body `## Current Position`: `Status:` line, `Last activity:` line, `Progress:` bar
+   - These MUST stay in sync — see `skills/shared/state-update.md`
    - **STATE.md size limit:** Follow size limit enforcement rules in `skills/shared/state-update.md` (150 lines max).
 3. Update VERIFICATION.md with UAT results (append UAT section)
 3. Present completion:
 
-Use the branded output from `references/ui-formatting.md`:
+Use the branded output from `references/ui-brand.md`:
 - If more phases remain: use the "Phase Complete" banner template
-- If this was the last phase: use the "Milestone Complete" banner template
+- If this was the last phase in the current milestone: use the "Milestone Complete" banner template
+- **Milestone boundary detection:** Read ROADMAP.md and find the `## Milestone:` section containing the current phase. Check its `**Phases:** start - end` range. If the current phase equals `end`, this is the last phase in the milestone.
 - Always include the "Next Up" routing block
 
 4. If `gates.confirm_transition` is true in config AND `features.auto_advance` is NOT true:
-   - Use the yes-no pattern from `skills/shared/gate-prompts.md`:
+   - Use AskUserQuestion (pattern: yes-no from `skills/shared/gate-prompts.md`):
      question: "Phase {N} verified. Ready to move to Phase {N+1}?"
      header: "Continue?"
      options:
        - label: "Yes"  description: "Proceed to plan Phase {N+1}"
        - label: "No"   description: "Stay on Phase {N} for now"
-   - If "Yes": suggest `/pbr:plan {N+1}`
+   - If "Yes": suggest `/pbr:plan-phase {N+1}`
    - If "No" or "Other": stop
 
 5. **If `features.auto_advance` is `true` AND `mode` is `autonomous` AND more phases remain:**
-   - Chain directly to plan next phase
-   - This continues the build->review->plan cycle automatically
-   - **If this is the last phase:** HARD STOP — do NOT auto-advance past milestone boundaries
+   - Chain directly to plan: `Skill({ skill: "pbr:plan", args: "{N+1}" })`
+   - This continues the build→review→plan cycle automatically
+   - **If this is the last phase in the current milestone:** HARD STOP — do NOT auto-advance past milestone boundaries. Display: "auto_advance pauses at milestone boundaries — your sign-off is required."
 
 #### Gaps Found WITH `--auto-fix`
 
@@ -345,13 +438,30 @@ If gaps were found and `--auto-fix` was specified:
 
 **Step 6a: Diagnose**
 
-Display to the user: `Spawning debugger...`
+Display to the user: `◆ Spawning debugger...`
 
-Invoke the `@debugger` agent to analyze each failure.
+Spawn a debugger Task() to analyze each failure:
+
+```
+Task({
+  subagent_type: "pbr:debugger",
+  prompt: <debugger prompt>
+})
+```
 
 ##### Debugger Prompt Template
 
-Read `skills/review/templates/debugger-prompt.md.tmpl` and use its content as the debugger prompt.
+Read `${CLAUDE_SKILL_DIR}/templates/debugger-prompt.md.tmpl` and use its content as the debugger prompt.
+
+**Prepend this block to the debugger prompt before sending:**
+```
+<files_to_read>
+CRITICAL (no hook): Read these files BEFORE any other action:
+1. .planning/phases/{NN}-{slug}/VERIFICATION.md — gaps and failure details
+2. .planning/phases/{NN}-{slug}/SUMMARY-*.md — what was built
+3. .planning/phases/{NN}-{slug}/PLAN-*.md — original plan must-haves
+</files_to_read>
+```
 
 **Placeholders to fill before sending:**
 - `[Inline the VERIFICATION.md content]` — provide file path; debugger reads via Read tool
@@ -360,13 +470,30 @@ Read `skills/review/templates/debugger-prompt.md.tmpl` and use its content as th
 
 **Step 6b: Create Gap-Closure Plans**
 
-After receiving the root cause analysis, display to the user: `Spawning planner (gap closure)...`
+After receiving the root cause analysis, display to the user: `◆ Spawning planner (gap closure)...`
 
-Invoke the `@planner` agent in gap-closure mode.
+Spawn the planner in gap-closure mode:
+
+```
+Task({
+  subagent_type: "pbr:planner",
+  prompt: <gap planner prompt>
+})
+```
 
 ##### Gap Planner Prompt Template
 
-Read `skills/review/templates/gap-planner-prompt.md.tmpl` and use its content as the gap planner prompt.
+Read `${CLAUDE_SKILL_DIR}/templates/gap-planner-prompt.md.tmpl` and use its content as the gap planner prompt.
+
+**Prepend this block to the gap planner prompt before sending:**
+```
+<files_to_read>
+CRITICAL (no hook): Read these files BEFORE any other action:
+1. .planning/phases/{NN}-{slug}/VERIFICATION.md — gaps to close
+2. .planning/phases/{NN}-{slug}/PLAN-*.md — existing plans for context
+3. .planning/CONTEXT.md — locked decisions and constraints (if exists)
+</files_to_read>
+```
 
 **Placeholders to fill before sending:**
 - `[Inline VERIFICATION.md]` — provide file path; planner reads via Read tool
@@ -378,9 +505,9 @@ Read `skills/review/templates/gap-planner-prompt.md.tmpl` and use its content as
 **Step 6c: Validate gap-closure plans (conditional)**
 
 If `features.plan_checking` is true in config:
-- Display to the user: `Spawning plan checker...`
-- Invoke `@plan-checker` on the new gap-closure plans
-- Same process as `/pbr:plan` Step 6
+- Display to the user: `◆ Spawning plan checker...`
+- Spawn plan checker Task() on the new gap-closure plans
+- Same process as `/pbr:plan-phase` Step 6
 
 **Step 6d: Present gap-closure plans to user**
 
@@ -395,7 +522,7 @@ Plans:
   {plan_id}: {name} — fixes: {gap description} ({difficulty})
   {plan_id}: {name} — fixes: {gap description} ({difficulty})
 
-Use the approve-revise-abort pattern from `skills/shared/gate-prompts.md`:
+Use AskUserQuestion (pattern: approve-revise-abort from `skills/shared/gate-prompts.md`):
   question: "Approve these {count} gap-closure plans?"
   header: "Approve?"
   options:
@@ -403,7 +530,7 @@ Use the approve-revise-abort pattern from `skills/shared/gate-prompts.md`:
     - label: "Review first"     description: "Let me review the plans before approving"
     - label: "Fix manually"     description: "I'll fix these gaps myself"
 
-- If "Approve": suggest `/pbr:build {N} --gaps-only`
+- If "Approve": suggest `/pbr:execute-phase {N} --gaps-only`
 - If "Review first" or "Other": present the full plan files for inspection
 - If "Fix manually": suggest relevant files to inspect based on gap details
 
@@ -426,7 +553,7 @@ Phase {N}: {name} — Gaps Found
 2. {gap description}
    ...
 
-Use the multi-option-gaps pattern from `skills/shared/gate-prompts.md`:
+Use AskUserQuestion (pattern: multi-option-gaps from `skills/shared/gate-prompts.md`):
   question: "{count} verification gaps need attention. How should we proceed?"
   header: "Gaps"
   options:
@@ -491,9 +618,11 @@ After Step 3, also check cross-phase integration:
 ## Error Handling
 
 ### Verifier agent fails
-If the verifier agent fails, display:
+If the verifier Task() fails, display:
 ```
-ERROR
+╔══════════════════════════════════════════════════════════════╗
+║  ERROR                                                       ║
+╚══════════════════════════════════════════════════════════════╝
 
 Automated verification failed.
 
@@ -503,7 +632,7 @@ Fall back to manual UAT only (skip automated checks).
 
 ### No must-haves to check
 If plans have empty must_haves:
-- Warn user: "Plans don't have defined must-haves. UAT will be based on plan descriptions only."
+- Warn user: `⚠ Plans don't have defined must-haves. UAT will be based on plan descriptions only.`
 - Use SUMMARY.md content as the basis for UAT
 
 ### User can't verify something
@@ -513,9 +642,11 @@ If user can't verify an item (e.g., needs server running, needs credentials):
 - Suggest how to verify later
 
 ### Debugger fails during auto-fix
-If the debugger agent fails, display:
+If the debugger Task() fails, display:
 ```
-ERROR
+╔══════════════════════════════════════════════════════════════╗
+║  ERROR                                                       ║
+╚══════════════════════════════════════════════════════════════╝
 
 Auto-diagnosis failed.
 
@@ -525,116 +656,30 @@ Ask user: "Would you like to proceed with gap-closure plans without root cause a
 
 ---
 
-## Files Created/Modified by /pbr:review
+## Files Created/Modified by /pbr:verify-work
 
 | File | Purpose | When |
 |------|---------|------|
 | `.planning/phases/{NN}-{slug}/VERIFICATION.md` | Verification report | Step 3 (created or updated with UAT) |
 | `.planning/phases/{NN}-{slug}/*-PLAN.md` | Gap-closure plans | Step 6b (--auto-fix only) |
-| `.planning/ROADMAP.md` | Status -> `verified` + Completed date | Step 6 |
+| `.planning/ROADMAP.md` | Status → `verified` + Completed date | Step 6 |
 | `.planning/STATE.md` | Updated with review status | Step 6 |
 
 ---
 
-## Completion
-
-After review completes, always present a clear next action:
+## Cleanup
 
-**If verified (not final phase):**
+Delete `.planning/.active-skill` if it exists. This must happen on all paths (success, partial, and failure) before reporting results.
 
-Display the "Phase Complete" banner inline:
-```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- PLAN-BUILD-RUN ► PHASE {N} COMPLETE
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-**Phase {N}: {Name}**
-
-{X} plans executed
-Goal verified
-```
-
-Then the branded "Next Up" block:
-```
----
-
-## Next Up
-
-**Phase {N+1}: {Name}** — {Goal from ROADMAP.md}
-
-`/pbr:plan {N+1}`
-
-`/clear` first for a fresh context window
-
----
-
-**Also available:**
-- `/pbr:discuss {N+1}` — talk through details before planning
-- `/pbr:status` — see full project status
-
----
-```
-
-**If gaps remain:**
-```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- PLAN-BUILD-RUN ► PHASE {N} GAPS FOUND
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-**Phase {N}: {name}** — {count} gaps remaining
-
----
-
-## Next Up
-
-**Fix gaps** — diagnose and create fix plans
-
-`/pbr:review {N} --auto-fix`
-
-`/clear` first for a fresh context window
-
----
-
-**Also available:**
-- `/pbr:plan {N} --gaps` — create fix plans manually
-- Fix manually, then `/pbr:review {N}`
-
----
-```
-
-**If final phase:**
-
-Display the "Milestone Complete" banner inline:
-```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- PLAN-BUILD-RUN ► MILESTONE COMPLETE
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-{N} phases completed
-All phase goals verified
-```
-
-Then:
-```
----
-
-## Next Up
-
-**Audit milestone** — verify cross-phase integration
-
-`/pbr:milestone audit`
-
-`/clear` first for a fresh context window
+## Completion
 
----
+After review completes, always present a clear next action using the completion banners from Read `references/ui-brand.md` § "Completion Summary Templates":
 
-**Also available:**
-- `/pbr:milestone complete` — archive this milestone and tag it
-- `/pbr:milestone new` — start planning next features
-- `/pbr:status` — see final project status
+- **If verified (not final phase):** Use the "Phase Complete" template. Fill in phase number, name, plan count, and next phase details.
+- **If gaps remain:** Use the "Gaps Found" template. Fill in phase number, name, gap count, and gap summaries.
+- **If final phase:** Use the "Milestone Complete" template. Fill in phase count.
 
----
-```
+Include `<sub>/clear first → fresh context window</sub>` inside the Next Up routing block of the completion template.
 
 ---
 
@@ -643,7 +688,7 @@ Then:
 For user-friendly interpretation of verification results, see `references/reading-verification.md`.
 
 - The verifier agent has NO Write/Edit tools for project source code — it can only read, check, and write VERIFICATION.md
-- Re-running `/pbr:review` after gap closure triggers fresh verification
+- Re-running `/pbr:verify-work` after gap closure triggers fresh verification
 - UAT results are conversational — user responses are captured inline
 - VERIFICATION.md is persistent and serves as the ground truth for gap closure
 - The three-layer check (existence -> substantiveness -> wiring) catches progressively deeper issues