@sienklogic/plan-build-run 2.18.1 → 2.19.1

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

@@ -2,21 +2,26 @@
 name: review
 description: "Verify the build matched the plan. Automated checks + walkthrough with you."
 allowed-tools: Read, Write, Bash, Glob, Grep, Task, AskUserQuestion, Skill
-argument-hint: "<phase-number> [--auto-fix] [--teams]"
+argument-hint: "<phase-number> [--auto-fix] [--teams] [--model <model>] [--auto]"
 ---
 
 **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.
+Reference: `@references/verification-overrides.md` for verification override handling and gap acceptance.
+
+**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.
+Reference: `skills/shared/agent-type-resolution.md` for agent type fallback when spawning Task() subagents.
 
 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
 
@@ -30,6 +35,22 @@ Additionally for this skill:
 
 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 +60,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 +73,8 @@ 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) |
+| `3 --auto` | Review phase 3 with auto mode — skip interactive UAT, auto-accept if verification passes |
 | (no number) | Use current phase from STATE.md |
 
 ---
@@ -65,17 +88,41 @@ Execute these steps in order.
 ### Step 1: Parse and Validate (inline)
 
 1. Parse `$ARGUMENTS` for phase number and `--auto-fix` flag
-2. Read `.planning/config.json`
-   **CRITICAL: Write .active-skill NOW.** Write the text "review" to `.planning/.active-skill` using the Write tool.
+   - 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 `blob.verifier_model`. If an invalid value is provided, display an error and list valid values.
+   - If `--auto` is present in `$ARGUMENTS`: set `auto_mode = true`. Log: "Auto mode enabled — skipping interactive UAT walkthrough"
+2. **CRITICAL — Init first.** Run the init CLI call as the FIRST action after argument parsing:
+   ```bash
+   node plugins/pbr/scripts/pbr-tools.js init verify-work {N}
+   ```
+   Store the JSON result as `blob`. All downstream steps MUST reference `blob` fields instead of re-reading files. Key fields: `blob.phase.dir`, `blob.phase.name`, `blob.phase.goal`, `blob.phase.plan_count`, `blob.phase.completed`, `blob.verifier_model`, `blob.has_verification`, `blob.prior_attempts`, `blob.prior_status`, `blob.summaries`.
+   **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}/`
-   - 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`
+4. Validate using blob fields:
+   - If `blob.error`: display error and stop
+   - If `blob.summaries` is empty: display "Phase hasn't been built yet" error (see error box below)
+   - If `blob.phase.plan_count === 0`: display "Phase has no plans" error (see error box below)
+5. If no phase number given, use `blob.phase.number` (already resolved from STATE.md by init)
 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:**
+7. Resolve verification depth:
+   - Run: `node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js trust-gate {N}`
+   - Parse the JSON response to get `depth` (light/standard/thorough)
+   - Log: "Verification depth: {depth} (trust-based)"
+   - Store as `verification_depth` for use in Step 3
+   - If the command fails or graduated_verification is disabled, default to "standard"
+
+**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. **CRITICAL -- DO NOT SKIP**: Present the following choice to the user via AskUserQuestion before proceeding:
+   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:
 ```
@@ -85,7 +132,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:
@@ -96,22 +143,22 @@ 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.
 ```
 
 ---
 
 ### Step 2: Check Existing Verification (inline)
 
-Reference: `skills/shared/config-loading.md` for the tooling shortcut (`phase-info`) and config field reference.
+Check if a VERIFICATION.md already exists using `blob.has_verification` and `blob.prior_status` from the init blob:
 
-Check if a VERIFICATION.md already exists from `/pbr:build`'s auto-verification step:
-
-1. Look for `.planning/phases/{NN}-{slug}/VERIFICATION.md`
-2. If it exists:
+1. Check `blob.has_verification` — if `true`, a VERIFICATION.md exists at `.planning/phases/{blob.phase.dir}/VERIFICATION.md`
+2. If it exists (use `blob.prior_status` and `blob.prior_attempts` for status checks):
    - Read it and check the status
    - If `status: passed` and no `--auto-fix` flag: skip to Step 4 (conversational UAT)
    - If `status: gaps_found`: present gaps and proceed to Step 4
+     - Check for `fix_plans:` in frontmatter. If present, summarize each fix plan (gap, effort, tasks) before presenting gaps.
+     - Classify gaps by severity: Critical (blocks functionality) vs Non-Critical (cosmetic, optional). Display severity counts: "Critical: {N}, Non-Critical: {N}"
    - If `status: human_needed`: proceed to Step 4
 
 3. If it does NOT exist: proceed to Step 3 (automated verification)
@@ -124,10 +171,12 @@ Check if a VERIFICATION.md already exists from `/pbr:build`'s auto-verification
 
 #### Team Review Mode
 
-If `--teams` flag is present OR `config.parallelization.use_teams` is true:
+If `--teams` flag is present OR `config.parallelization.use_teams` is true OR `features.extended_context` is `true` in `.planning/config.json`:
+
+When triggered by `extended_context`, log: "Extended context: auto-enabling team review (3 parallel verifiers)"
 
 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():
 
@@ -144,7 +193,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"
@@ -157,13 +206,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>
 })
 ```
@@ -172,7 +222,18 @@ 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)
+4. .planning/phases/{NN}-{slug}/CONTEXT.md — locked decisions and phase constraints (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
@@ -180,6 +241,16 @@ Read `skills/review/templates/verifier-prompt.md.tmpl` and use its content as th
 - `{NN}-{slug}` — the phase directory name
 - `{N}` — the phase number
 - `{date}`, `{count}`, `{phase name}` — fill from context
+- `{verification_depth}` — the depth resolved in Step 1.7 (light/standard/thorough)
+
+**Append this block to the verifier prompt after the placeholders:**
+
+```
+**Verification depth:** {verification_depth}
+- light: Check L1 (existence) and basic frontmatter only. Skip L2/L3/L4 and anti-pattern scan. Budget: <=400 tokens output.
+- standard: Full 3-layer verification (L1-L3). Current default behavior.
+- thorough: Full 4-layer verification (L1-L4) + cross-phase regression check (even if context_window_tokens < 500000) + full anti-pattern scan.
+```
 
 Wait for the verifier to complete.
 
@@ -200,6 +271,17 @@ 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 4: Present Verification Results (inline)
@@ -220,7 +302,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"
 
@@ -232,16 +314,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}
@@ -249,27 +335,63 @@ 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)
 
+**Skip if:** `auto_mode` is true — skip the interactive UAT walkthrough entirely. Still run automated verification (Step 3). If automated verification passed, auto-accept and proceed to Step 6 "All Items Pass" path. If automated verification found gaps, proceed to Step 6 "Gaps Found" path.
+
+**Autonomy gate:** Read `autonomy.level` from config.
+- If level is "guided", "collaborative", or "adaptive" AND automated verification passed (status: passed):
+  Skip interactive UAT. Log: "UAT skipped (autonomy: {level}, verification: passed)."
+  Proceed directly to Step 6 "All Items Pass" path.
+- If level is "supervised" OR verification has gaps:
+  Run full interactive UAT as currently defined.
+
 Walk the user through each deliverable one by one. This is an interactive conversation, not an automated check.
 
 **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:
 
@@ -318,31 +440,29 @@ If all automated checks and UAT items passed:
 
 1. **Update `.planning/ROADMAP.md` Progress table** (REQUIRED — do this BEFORE updating STATE.md):
 
-   **Tooling shortcut**: Use the CLI for atomic ROADMAP.md and STATE.md updates:
+   > Note: Use CLI for atomic writes — direct Write bypasses file locking.
+
    ```bash
    node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js roadmap update-status {phase} verified
-   node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js state update status verified
-   node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js state update last_activity now
+   node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js state patch '{"status":"verified","last_activity":"now"}'
    ```
 
-   1. Open `.planning/ROADMAP.md`
-   2. Find the `## Progress` table
-   3. Locate the row matching this phase number
-   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` via CLI **(CRITICAL (no hook) — update BOTH frontmatter AND body):**
+
+   > Note: Use CLI for atomic writes — direct Write bypasses file locking.
+
+   ```bash
+   node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js state patch '{"status":"verified","last_activity":"now","last_command":"/pbr:verify-work {N}"}'
+   ```
+   These update both frontmatter (`status`, `progress_percent`, `last_activity`, `last_command`) and body `## Current Position` (`Status:`, `Last activity:`, `Progress:` bar) atomically — they 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 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.
+- **Milestone boundary detection:** Read ROADMAP.md and find the `## Milestone:` section containing the current phase. Active milestones use `## Milestone:` headings directly; completed milestones are wrapped in `<details><summary>## Milestone:` blocks or use the legacy `-- COMPLETED` suffix. Check the active milestone's `**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:
@@ -352,10 +472,12 @@ 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:**
+5. **If `auto_mode` is `true` AND more phases remain:** Set `features.auto_advance = true` and `mode = autonomous` behavior for the remainder of this invocation. Chain directly to plan: `Skill({ skill: "pbr:plan", args: "{N+1} --auto" })`. This continues the review→plan→build 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."
+
+   **Else 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 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."
@@ -366,7 +488,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:
 
@@ -379,7 +501,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
@@ -388,7 +520,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:
 
@@ -401,7 +533,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
@@ -413,9 +555,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**
 
@@ -438,7 +580,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
 
@@ -446,8 +588,11 @@ Use AskUserQuestion (pattern: approve-revise-abort from `skills/shared/gate-prom
 
 If gaps were found and `--auto-fix` was NOT specified:
 
-1. List all gaps clearly
-2. **Default to auto-fix** — offer it as the recommended action, not a hidden flag
+1. List all gaps clearly, grouped by severity (Critical first, then Non-Critical)
+2. If VERIFICATION.md frontmatter contains `fix_plans:`, present existing fix plans:
+   - For each fix plan: show gap, estimated effort, and planned tasks
+   - Offer to create these as follow-up plans directly
+3. **Default to auto-fix** — offer it as the recommended action, not a hidden flag
 
 ```
 Phase {N}: {name} — Gaps Found
@@ -490,6 +635,8 @@ After adding overrides, re-evaluate: if all remaining gaps are now overridden, m
 
 ## UAT Result Recording
 
+**Template reference:** Read `${CLAUDE_PLUGIN_ROOT}/templates/UAT.md.tmpl` for the persistent UAT session format. Use this template when creating standalone UAT tracking files for complex phases. For simpler phases, append UAT results directly to VERIFICATION.md as shown below.
+
 After conversational UAT, append UAT results to VERIFICATION.md:
 
 ```markdown
@@ -564,15 +711,17 @@ 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}/VERIFICATION.md` | Verification report (depth-aware) | 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/STATE.md` | Updated with review status | Step 6 |
 
+**Graduated depth behavior:** Step 1.7 resolves verification depth via trust-gate. Step 3 passes depth to verifier. Step 5 checks autonomy.level to gate UAT.
+
 ---
 
 ## Cleanup
@@ -581,109 +730,13 @@ Delete `.planning/.active-skill` if it exists. This must happen on all paths (su
 
 ## 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 ✓
-```
-
-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 ⚠                     ║
-╚══════════════════════════════════════════════════════════════╝
-
-**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 🎉                      ║
-╚══════════════════════════════════════════════════════════════╝
+After review completes, always present a clear next action using the completion banners from Read `references/ui-brand.md` § "Completion Summary Templates":
 
-{N} phases completed
-All phase goals verified ✓
-```
-
-Then:
-```
-
-
-╔══════════════════════════════════════════════════════════════╗
-║  ▶ NEXT UP                                                   ║
-╚══════════════════════════════════════════════════════════════╝
-
-**Audit milestone** — verify cross-phase integration
+- **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.
 
-`/pbr:milestone audit`
-
-<sub>`/clear` first → fresh context window</sub>
-
-
-
-**Also available:**
-- `/pbr:milestone complete` — archive milestone after audit passes
-- `/pbr:milestone new` — start planning next features
-- `/pbr:status` — see final project status
-
-
-```
+Include `<sub>/clear first → fresh context window</sub>` inside the Next Up routing block of the completion template.
 
 ---
 
@@ -692,7 +745,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