@sienklogic/plan-build-run 2.1.0 → 2.1.1

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

@@ -1,35 +1,53 @@
 ---
 name: review
 description: "Verify the build matched the plan. Automated checks + walkthrough with you."
-allowed-tools: Read, Write, Bash, Glob, Grep, Task, AskUserQuestion
-argument-hint: "<phase-number> [--auto-fix] [--teams]"
+allowed-tools: Read, Write, Bash, Glob, Grep, Task, AskUserQuestion, Skill
+argument-hint: "<phase-number> [--auto-fix] [--teams] [--model <model>]"
 ---
 
 **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.**
 
-# /pbr:review — Phase Review and Verification
+# /pbr:verify-work — Phase Review and Verification
 
-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.
+**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 subagent output — read only VERIFICATION.md frontmatter for summaries
+- **Minimize** reading subagent output — read only VERIFICATION.md frontmatter for summaries. Exception: if `context_window_tokens` in `.planning/config.json` is >= 500000, reading full VERIFICATION.md bodies is permitted when gap details are needed for inline presentation.
 
 ## 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
@@ -39,7 +57,7 @@ Where `{N}` is the phase number from `$ARGUMENTS`. Then proceed to Step 1.
 
 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).
 
 ---
 
@@ -52,6 +70,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 |
 
 ---
@@ -64,8 +83,12 @@ 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 ${CLAUDE_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}/`
@@ -74,7 +97,18 @@ Execute these steps in order.
 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, same pattern as auto-continue.js).
 
-**Validation errors — use branded error boxes:**
+**Validation errors:**
+
+If phase directory not found, use conversational recovery:
+
+1. Run: `node ${CLAUDE_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:
 ```
@@ -84,7 +118,7 @@ If no SUMMARY.md files:
 
 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:
@@ -95,7 +129,7 @@ If no PLAN.md files:
 
 Phase {N} has no plans.
 
-**To fix:** Run `/pbr:plan {N}` first.
+**To fix:** Run `/pbr:plan-phase {N}` first.
 ```
 
 ---
@@ -104,7 +138,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:
@@ -126,7 +160,7 @@ Check if a VERIFICATION.md already exists from `/pbr:build`'s auto-verification
 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)...`
 
    Spawn THREE verifier agents in parallel using Task():
 
@@ -143,7 +177,7 @@ If `--teams` flag is present OR `config.parallelization.use_teams` is true:
    - 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...`
 
    Spawn synthesizer:
    - subagent_type: "pbr:synthesizer"
@@ -156,13 +190,14 @@ Reference: `references/agent-teams.md`
 
 #### Single-Verifier Flow (default)
 
-Display to the user: `◐ Spawning verifier...`
+Display to the user: `◆ Spawning verifier...`
 
 Spawn a verifier Task() to run three-layer checks:
 
 ```
 Task({
   subagent_type: "pbr:verifier",
+  // After verifier completes, check for: ## VERIFICATION COMPLETE
   prompt: <verifier prompt>
 })
 ```
@@ -171,7 +206,17 @@ Task({
 
 #### 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
@@ -199,6 +244,31 @@ Then show a brief table of must-haves with pass/fail status:
 
 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 ${CLAUDE_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)
@@ -219,7 +289,7 @@ Use AskUserQuestion (pattern: multi-option-escalation from `skills/shared/gate-p
   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: "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"
 
@@ -231,16 +301,20 @@ Use AskUserQuestion (pattern: multi-option-escalation from `skills/shared/gate-p
       - 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}
@@ -248,18 +322,45 @@ 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}
 ```
 
+#### Cross-Phase Findings (conditional)
+
+**Condition:** Only display if ALL of the following are true:
+- `context_window_tokens` in `.planning/config.json` is >= 500000
+- VERIFICATION.md frontmatter contains a `cross_phase_regressions` key with at least one entry
+
+**How to check:** The `cross_phase_regressions` array was already read from VERIFICATION.md frontmatter in Step 2 or Step 4. If the array is empty or absent, skip this block entirely.
+
+If the condition is met, append a cross-phase findings section to the Step 4 output:
+
+```
+Cross-Phase Regressions: {count} found
+
+| Prior Phase | Must-Have | Status | Evidence |
+|-------------|-----------|--------|----------|
+| {phase}     | {must_have} | ✗ REGRESSION | {evidence} |
+| {phase}     | {must_have} | ✓ INTACT | — |
+
+{If regressions found:}
+⚠ These must-haves passed in prior phases but may be broken by current phase changes.
+  Treat them as additional gaps — select "Auto-fix" to create repair plans.
+```
+
+Cross-phase regressions are displayed AFTER the single-phase verification results and BEFORE the UAT walkthrough (Step 5). They are additive — they do not replace single-phase results.
+
+If regressions exist, include them in the gap count for the "Gaps Found" flow in Step 6. When presenting gap options to the user, regressions appear in the gap list labeled `[cross-phase]` to distinguish them from current-phase gaps.
+
 ---
 
 ### Step 5: Conversational UAT (inline)
@@ -268,7 +369,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:
 
@@ -330,17 +431,18 @@ 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:
@@ -350,13 +452,13 @@ Use the branded output from `references/ui-formatting.md`:
      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: `Skill({ skill: "pbr:plan", args: "{N+1}" })`
    - This continues the build→review→plan cycle automatically
-   - **If this is the last phase:** HARD STOP — do NOT auto-advance past milestone boundaries
+   - **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`
 
@@ -364,7 +466,7 @@ If gaps were found and `--auto-fix` was specified:
 
 **Step 6a: Diagnose**
 
-Display to the user: `◐ Spawning debugger...`
+Display to the user: `◆ Spawning debugger...`
 
 Spawn a debugger Task() to analyze each failure:
 
@@ -377,7 +479,17 @@ Task({
 
 ##### 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
@@ -386,7 +498,7 @@ 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)...`
 
 Spawn the planner in gap-closure mode:
 
@@ -399,7 +511,17 @@ Task({
 
 ##### 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
@@ -411,9 +533,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...`
+- Display to the user: `◆ Spawning plan checker...`
 - Spawn plan checker Task() on the new gap-closure plans
-- Same process as `/pbr:plan` Step 6
+- Same process as `/pbr:plan-phase` Step 6
 
 **Step 6d: Present gap-closure plans to user**
 
@@ -436,7 +558,7 @@ Use AskUserQuestion (pattern: approve-revise-abort from `skills/shared/gate-prom
     - 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
 
@@ -562,7 +684,7 @@ 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 |
 |------|---------|------|
@@ -573,105 +695,19 @@ Ask user: "Would you like to proceed with gap-closure plans without root cause a
 
 ---
 
-## Completion
-
-After review completes, always present a clear next action:
-
-**If verified (not final phase):**
-
-Display the "Phase Complete" banner inline:
-```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- PLAN-BUILD-RUN ► PHASE {N} COMPLETE ✓
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-**Phase {N}: {Name}**
-
-{X} plans executed
-Goal verified ✓
-```
+## Cleanup
 
-Then the branded "Next Up" block:
-```
-───────────────────────────────────────────────────────────────
-
-## ▶ Next Up
-
-**Phase {N+1}: {Name}** — {Goal from ROADMAP.md}
-
-`/pbr:plan {N+1}`
-
-<sub>`/clear` first → fresh context window</sub>
-
-───────────────────────────────────────────────────────────────
-
-**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 ⚠
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Delete `.planning/.active-skill` if it exists. This must happen on all paths (success, partial, and failure) before reporting results.
 
-**Phase {N}: {name}** — {count} gaps remaining
-
-───────────────────────────────────────────────────────────────
-
-## ▶ Next Up
-
-**Fix gaps** — diagnose and create fix plans
-
-`/pbr:review {N} --auto-fix`
-
-<sub>`/clear` first → fresh context window</sub>
-
-───────────────────────────────────────────────────────────────
-
-**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`
-
-<sub>`/clear` first → fresh context window</sub>
+## 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.
 
 ---
 
@@ -680,7 +716,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