@sienklogic/plan-build-run 2.1.0 → 2.1.1

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

@@ -1,12 +1,16 @@
 ---
 name: build
 description: "Execute all plans in a phase. Spawns agents to build in parallel, commits atomically."
-argument-hint: "<phase-number> [--gaps-only] [--team]"
+argument-hint: "<phase-number> [--gaps-only] [--team] [--model <model>]"
 ---
 
-# /pbr:build — Phase Execution
+**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:build`. This skill executes all plans in a phase by invoking executor agents. Plans are grouped by wave and executed in order — independent plans run in parallel, dependent plans wait. Your job is to stay lean, delegate ALL building work to agents, and keep the user's main context window clean.
+# /pbr:execute-phase — Phase Execution
+
+**References:** `@references/questioning.md`, `@references/ui-brand.md`
+
+You are the orchestrator for `/pbr:execute-phase`. This skill executes all plans in a phase by spawning executor agents. Plans are grouped by wave and executed in order — independent plans run in parallel, dependent plans wait. Your job is to stay lean, delegate ALL building work to Task() agents, and keep the user's main context window clean.
 
 ## Context Budget
 
@@ -15,19 +19,37 @@ Reference: `skills/shared/context-budget.md` for the universal orchestrator rule
 Additionally for this skill:
 - **Minimize** reading executor output — read only SUMMARY.md frontmatter, not full content
 - **Delegate** all building work to executor agents — the orchestrator routes, it doesn't build
+- **Lazy-load steps**: Instead of reading ahead, fetch the next step's instructions on demand:
+  `node ${PLUGIN_ROOT}/scripts/pbr-tools.js skill-section build "step-6"` → returns that step's content as JSON. Use this when context budget is DEGRADING.
 
 ## Step 0 — Immediate Output
 
 **Before ANY tool calls**, display this banner:
 
 ```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- PLAN-BUILD-RUN ► BUILDING PHASE {N}
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► BUILDING PHASE {N}                         ║
+╚══════════════════════════════════════════════════════════════╝
 ```
 
 Where `{N}` is the phase number from `$ARGUMENTS`. Then proceed to Step 1.
 
+## Multi-Session Sync
+
+Before any phase-modifying operations (spawning executors, writing SUMMARY.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
@@ -45,7 +67,55 @@ Parse `$ARGUMENTS` according to `skills/shared/phase-argument-parsing.md`.
 | `3` | Build phase 3 |
 | `3 --gaps-only` | Build only gap-closure plans in phase 3 |
 | `3 --team` | Use Agent Teams for complex inter-agent coordination |
+| `3 --model opus` | Use opus for all executor spawns in phase 3 (overrides config and adaptive selection) |
 | (no number) | Use current phase from STATE.md |
+| `3 --preview` | Preview what build would do for phase 3 without executing |
+
+---
+
+### --preview mode
+
+If `--preview` is present in `$ARGUMENTS`:
+
+1. Extract the phase slug from `$ARGUMENTS` (use the phase number to look up the slug, or pass the number directly — the CLI accepts partial slug matches).
+2. Run:
+
+   ```bash
+   node ${PLUGIN_ROOT}/scripts/pbr-tools.js build-preview {phase-slug}
+   ```
+
+   Capture the JSON output.
+3. Render the following preview document (do NOT proceed to Step 2):
+
+   ```
+   ╔══════════════════════════════════════════════════════════════╗
+   ║  DRY RUN — /pbr:execute-phase {N} --preview                          ║
+   ║  No executor agents will be spawned                          ║
+   ╚══════════════════════════════════════════════════════════════╝
+
+   PHASE: {phase}
+
+   ## Plans
+   {for each plan: - {id} (wave {wave}, {task_count} tasks)}
+
+   ## Wave Structure
+   {for each wave: Wave {wave}: {plan IDs} [parallel | sequential]}
+
+   ## Files That Would Be Modified
+   {for each file in files_affected: - {file}}
+   (Total: {count} files)
+
+   ## Estimated Agent Spawns
+   {agent_count} executor task(s)
+
+   ## Critical Path
+   {critical_path joined with " → "}
+
+   ## Dependency Chain
+   {for each entry in dependency_chain: - {id} (wave {wave}) depends on: {depends_on or "none"}}
+   ```
+
+4. **STOP** — do not proceed to Step 2.
 
 ---
 
@@ -62,71 +132,74 @@ Reference: `skills/shared/config-loading.md` for the tooling shortcut and config
 1. Parse `$ARGUMENTS` for phase number and flags
 2. Read `.planning/config.json` for parallelization, model, and gate settings (see config-loading.md for field reference)
 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. Write `.planning/.active-skill` with the content `build` (registers with workflow enforcement hook)
+4. **CRITICAL (hook-enforced): Write .active-skill NOW.** Write `.planning/.active-skill` with the content `build` (registers with workflow enforcement hook)
 5. Validate:
    - Phase directory exists at `.planning/phases/{NN}-{slug}/`
    - PLAN.md files exist in the directory
    - Prior phase dependencies are met (check for SUMMARY.md files in dependency phases)
 6. If no phase number given, read current phase from `.planning/STATE.md`
    - `config.models.complexity_map` — adaptive model mapping (default: `{ simple: "haiku", medium: "sonnet", complex: "inherit" }`)
-7. If `gates.confirm_execute` is true: use the yes-no pattern from `skills/shared/gate-prompts.md`:
+7. If `gates.confirm_execute` is true: use AskUserQuestion (pattern: yes-no from `skills/shared/gate-prompts.md`):
    question: "Ready to build Phase {N}? This will execute {count} plans."
    header: "Build?"
    options:
      - label: "Yes"  description: "Start building Phase {N}"
      - label: "No"   description: "Cancel — review plans first"
-   If "No" or "Other": stop and suggest `/pbr:plan {N}` to review plans
-8. If `git.branching` is `phase`: create and switch to branch `plan-build-run/phase-{NN}-{name}` before any build work begins
+   If "No" or "Other": stop and suggest `/pbr:plan-phase {N}` to review plans
+8. If `git.branching` is `phase` (the recommended default — see config Quick Start): create and switch to branch `plan-build-run/phase-{NN}-{name}` before any build work begins
 9. Record the current HEAD commit SHA: `git rev-parse HEAD` — store as `pre_build_commit` for use in Step 8-pre-c (codebase map update)
 
 **Staleness check (dependency fingerprints):**
 After validating prerequisites, check plan staleness:
-1. Read each PLAN.md file's `dependency_fingerprints` field (if present)
-2. For each fingerprinted dependency, check the current SUMMARY.md file (length + modification time)
-3. If any fingerprint doesn't match: the dependency phase was re-built after this plan was created
-4. Use the stale-continue pattern from `skills/shared/gate-prompts.md`:
-   question: "Plan {plan_id} may be stale — dependency phase {M} was re-built after this plan was created."
-   header: "Stale"
-   options:
-     - label: "Continue anyway"  description: "Proceed with existing plans (may still be valid)"
-     - label: "Re-plan"          description: "Stop and re-plan with `/pbr:plan {N}` (recommended)"
-   If "Re-plan" or "Other": stop and suggest `/pbr:plan {N}`
-   If "Continue anyway": proceed with existing plans
-10. If plans have no `dependency_fingerprints` field, fall back to timestamp-based staleness detection:
-   a. Read `.planning/ROADMAP.md` and identify the current phase's dependencies (the `depends_on` field)
-   b. For each dependency phase, find its phase directory under `.planning/phases/`
-   c. Check if any SUMMARY.md files in the dependency phase directory have a modification timestamp newer than the current phase's PLAN.md files
-   d. If any upstream dependency was modified after planning, display a warning (do NOT block):
-      ```
-      Warning: Phase {dep_phase} (dependency of Phase {N}) was modified after this phase was planned.
-      Plans may be based on outdated assumptions. Consider re-planning with `/pbr:plan {N}`.
-      ```
-   e. This is advisory only — continue with the build after displaying the warning
+
+```bash
+node ${PLUGIN_ROOT}/scripts/pbr-tools.js staleness-check {phase-slug}
+```
+
+Returns `{ stale: bool, plans: [{id, stale, reason}] }`. If `stale: true` for any plan:
+- Use AskUserQuestion (pattern: stale-continue from `skills/shared/gate-prompts.md`):
+  question: "Plan {plan_id} may be stale — {reason}"
+  options: ["Continue anyway", "Re-plan with /pbr:plan-phase {N}"]
+- If "Re-plan": stop. If "Continue anyway": proceed.
+If `stale: false`: proceed silently.
 
 **Validation errors — use branded error boxes:**
 
 If no plans found:
 ```
-ERROR
+╔══════════════════════════════════════════════════════════════╗
+║  ERROR                                                       ║
+╚══════════════════════════════════════════════════════════════╝
 
 Phase {N} has no plans.
 
-**To fix:** Run `/pbr:plan {N}` first.
+**To fix:** Run `/pbr:plan-phase {N}` first.
 ```
 
-If dependencies incomplete:
-```
-ERROR
+If dependencies incomplete, use conversational recovery:
 
-Phase {N} depends on Phase {M}, which is not complete.
+1. Run: `node ${PLUGIN_ROOT}/scripts/pbr-tools.js suggest-alternatives missing-prereq {dependency-phase-slug}`
+2. Parse the JSON response to get `existing_summaries`, `missing_summaries`, and `suggested_action`.
+3. Display what summaries exist and what is still missing.
+4. Use AskUserQuestion (pattern: yes-no from `skills/shared/gate-prompts.md`) to offer:
+   - "Build {dependency-phase} first" — stop and show: `/pbr:execute-phase {dependency-phase}`
+   - "Continue anyway (skip dependency check)" — proceed with build, note unmet deps in output
 
-**To fix:** Build Phase {M} first with `/pbr:build {M}`.
-```
+If config validation fails for a specific field, use conversational recovery:
+
+1. Run: `node ${PLUGIN_ROOT}/scripts/pbr-tools.js suggest-alternatives config-invalid {field} {value}`
+2. Parse the JSON response to get `valid_values` and `suggested_fix`.
+3. Display the invalid field, its current value, and the valid options.
+4. Use AskUserQuestion to offer: "Fix config.json now, or continue with current value?"
+   - If "Fix now": stop and display the `suggested_fix` instruction.
+   - If "Continue": proceed with default value for that field.
 
 ---
 
 ### Step 2: Load Config (inline)
 
+**Init-first pattern**: When spawning agents, pass the output of `node plugins/pbr/scripts/pbr-tools.js init execute-phase {N}` as context rather than having the agent read multiple files separately. This reduces file reads and prevents context-loading failures.
+
 Read configuration values needed for execution. See `skills/shared/config-loading.md` for the full field reference; build uses: `parallelization.*`, `features.goal_verification`, `features.inline_verify`, `features.atomic_commits`, `features.auto_continue`, `features.auto_advance`, `planning.commit_docs`, `git.commit_format`, `git.branching`.
 
 ---
@@ -149,7 +222,7 @@ This returns a JSON object with `plans` (array with plan_id, wave, depends_on, a
 4. Sort plans by plan number
 
 **If no plans match filters:**
-- With `--gaps-only`: "No gap-closure plans found. Run `/pbr:plan {N} --gaps` first."
+- With `--gaps-only`: "No gap-closure plans found. Run `/pbr:plan-phase {N} --gaps` first."
 - Without filter: "No plans found in phase directory."
 
 ---
@@ -167,14 +240,14 @@ Check for existing SUMMARY.md files from previous runs (crash recovery):
 3. Build the skip list of plans to exclude
 
 **If all plans already have completed SUMMARYs:**
-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} has already been built. All plans have completed SUMMARYs. Re-build from scratch?"
   header: "Re-build?"
   options:
     - label: "Yes"  description: "Delete existing SUMMARYs and re-execute all plans"
     - label: "No"   description: "Keep existing build — review instead"
 - If "Yes": delete SUMMARY files and proceed
-- If "No" or "Other": suggest `/pbr:review {N}`
+- If "No" or "Other": suggest `/pbr:verify-work {N}`
 
 ---
 
@@ -191,28 +264,21 @@ Validate wave consistency:
 
 ### Step 5b: Write Checkpoint Manifest (inline)
 
-Before entering the wave loop, write `.planning/phases/{NN}-{slug}/.checkpoint-manifest.json`:
+**CRITICAL (hook-enforced): Initialize checkpoint manifest NOW before entering the wave loop.**
 
-```json
-{
-  "plans": ["02-01", "02-02", "02-03"],
-  "checkpoints_resolved": [],
-  "checkpoints_pending": [],
-  "wave": 1,
-  "deferred": [],
-  "commit_log": [],
-  "last_good_commit": null
-}
+**Session affinity:** The checkpoint manifest includes a `session_id` field. Before writing any phase state, validate that the current session owns the manifest by checking `manifest.session_id` matches the active session. If mismatch, another session may have taken over — re-acquire the claim or warn the user.
+
+```bash
+node ${PLUGIN_ROOT}/scripts/pbr-tools.js checkpoint init {phase-slug} --plans "{comma-separated plan IDs}"
 ```
 
-This file tracks execution progress for crash recovery and rollback. On resume after compaction, read this manifest to determine where execution left off and which plans still need work.
+After each wave completes, update the manifest:
+
+```bash
+node ${PLUGIN_ROOT}/scripts/pbr-tools.js checkpoint update {phase-slug} --wave {N} --resolved {plan-id} --sha {commit-sha}
+```
 
-Update the manifest after each wave completes:
-- Move completed plan IDs into `checkpoints_resolved`
-- Advance the `wave` counter
-- Record commit SHAs in `commit_log` (array of `{ plan, sha, timestamp }` objects)
-- Update `last_good_commit` to the SHA of the last successfully verified commit
-- Append any deferred items collected from executor SUMMARYs
+This tracks execution for crash recovery and rollback. Read `.checkpoint-manifest.json` on resume to reconstruct which plans are complete.
 
 ---
 
@@ -235,12 +301,24 @@ For each wave, in order (Wave 1, then Wave 2, etc.):
 
 For each plan in the current wave (excluding skipped plans):
 
+**Local LLM plan quality check (optional, advisory):**
+
+Before spawning executors for this wave, if `config.local_llm.enabled` is `true`, run a quick classification on each plan to catch stubs before wasting an executor spawn:
+
+```bash
+node ${PLUGIN_ROOT}/scripts/pbr-tools.js llm classify PLAN ".planning/phases/{NN}-{slug}/{plan_id}-PLAN.md"
+```
+
+- If classification is `"stub"` or `"partial"` with confidence >= 0.7: warn the user before spawning: `"⚠ Plan {plan_id} classified as {classification} (confidence {conf}) — consider refining before building."`
+- If the command fails or returns null: skip silently (local LLM unavailable — not an error)
+- This is advisory only — never block on the result
+
 **Present plan narrative before spawning:**
 
 Display to the user before spawning:
 
 ```
-Spawning {N} executor(s) for Wave {W}...
+◆ Spawning {N} executor(s) for Wave {W}...
 ```
 
 Then present a brief narrative for each plan to give the user context on what's about to happen:
@@ -261,95 +339,66 @@ This is a read-only presentation step — extract descriptions from plan frontma
 **State fragment rule:** Executors MUST NOT modify STATE.md directly. The build skill orchestrator is the sole STATE.md writer during execution. Executors report results via SUMMARY.md only; the orchestrator reads those summaries and updates STATE.md itself.
 
 **Model Selection (Adaptive)**:
-Before invoking the executor for each plan, determine the model:
+Before spawning the executor for each plan, determine the model:
+0. If `--model <value>` was parsed from `$ARGUMENTS` (valid values: sonnet, opus, haiku, inherit), use that model for ALL executor Task() spawns in this run. Skip steps 1-4. The --model flag is the highest precedence override.
 1. Read the plan's task elements for `complexity` and `model` attributes
 2. If ANY task has an explicit `model` attribute, use the most capable model among them (inherit > sonnet > haiku)
 3. Otherwise, use the HIGHEST complexity among the plan's tasks to select the model:
    - Look up `config.models.complexity_map.{complexity}` (defaults: simple->haiku, medium->sonnet, complex->inherit)
 4. If `config.models.executor` is set (non-null), it overrides adaptive selection entirely — use that model for all executors
-5. Pass the selected model to the agent invocation
+5. Pass the selected model to the Task() spawn
+
+If `--model <value>` is present in `$ARGUMENTS`, extract the value. Valid values: `sonnet`, `opus`, `haiku`, `inherit`. If an invalid value is provided, display an error and list valid values. Store as `override_model`.
 
 Reference: `references/model-selection.md` for full details.
 
 1. Extract the `## Summary` section from the PLAN.md (everything after the `## Summary` heading to end of file). If no ## Summary section exists (legacy plans), fall back to reading the full PLAN.md content. Note: The orchestrator reads the full PLAN.md once for narrative extraction AND summary extraction; only the ## Summary portion is inlined into the executor prompt. The full PLAN.md stays on disk for the executor to Read.
-2. Read `.planning/CONTEXT.md` (if exists)
+2. Read `.planning/PROJECT.md` ## Context section (if exists; backwards compat: fall back to `.planning/CONTEXT.md` if PROJECT.md has no ## Context)
 3. Read `.planning/STATE.md`
 4. Read prior SUMMARY.md files from the same phase (completed plans in earlier waves)
 5. Read `.planning/config.json`
 
-Construct the executor prompt and invoke `@executor`:
-
-```
-You are the executor agent. Execute the following plan.
-
-<plan_summary>
-[Inline only the ## Summary section from PLAN.md]
-</plan_summary>
-
-<plan_file>
-.planning/phases/{NN}-{slug}/{plan_id}-PLAN.md
-</plan_file>
-
-<project_context>
-Project root: {absolute path to project root}
-Platform: {win32|linux|darwin}
-
-Config:
-  commit_format: {commit_format from config}
-  tdd_mode: {tdd_mode from config}
-  atomic_commits: {atomic_commits from config}
-
-Available context files (read via Read tool as needed):
-  - Config: {absolute path to config.json}
-  - State: {absolute path to STATE.md}
-{If CONTEXT.md exists:}
-  - Project context (locked decisions): {absolute path to CONTEXT.md}
-</project_context>
-
-<prior_work>
-Completed plans in this phase:
-| Plan | Status | Commits | Summary File |
-|------|--------|---------|-------------|
-| {plan_id} | complete | {hash1}, {hash2} | {absolute path to SUMMARY.md} |
-
-Read any SUMMARY file via Read tool if you need details on what prior plans produced.
-</prior_work>
+Construct the executor prompt by reading `${CLAUDE_SKILL_DIR}/templates/executor-prompt.md.tmpl` and filling in all `{placeholder}` values:
 
-Execute all tasks in the plan sequentially. For each task:
-0. Read the full plan file from the path in <plan_file> to get task details
-1. Execute the <action> steps
-2. Run the <verify> commands
-3. Create an atomic commit with format: {commit_format}
-4. Record the commit hash
+- `{NN}-{slug}` — phase directory (e.g., `02-authentication`)
+- `{plan_id}` — plan being executed (e.g., `02-01`)
+- `{commit_format}`, `{tdd_mode}`, `{atomic_commits}` — from loaded config
+- File paths: absolute paths to project root, config.json, STATE.md, PROJECT.md
+- `{prior_work table rows}` — one row per completed plan in this phase
 
-After all tasks complete:
-1. Write SUMMARY.md to .planning/phases/{NN}-{slug}/SUMMARY-{plan_id}.md
-2. Run self-check (verify files exist, commits exist, verify commands still pass)
-3. Return your SUMMARY.md content as your final response
-
-If you hit a checkpoint task, STOP and return the checkpoint response format immediately.
-```
-
-**NOTE**: The `@executor` agent is defined in `agents/executor.md`. Do NOT inline it.
+Use the filled template as the Task() prompt.
 
 **Spawn strategy based on config:**
 
 - If `parallelization.enabled: true` AND multiple plans in this wave:
-  - Invoke up to `max_concurrent_agents` executors in parallel
-  - Each invocation is independent
+  - Spawn up to `max_concurrent_agents` Task() calls in parallel
+  - Each Task() call is independent
+  - Use `run_in_background: true` for each executor
   - While waiting, display progress to the user:
     - After spawning: "Wave {W}: launched {N} executors in parallel: {list of plan names}"
+    - Periodically (~30s): check `TaskOutput` with `block: false` and report status
     - When each completes: "Plan {id} complete ({duration})"
     - When all complete: "Wave {W} finished. {passed}/{total} plans succeeded."
 
 - If `parallelization.enabled: false` OR single plan in wave:
-  - Invoke executors sequentially, one at a time
+  - Spawn Task() calls sequentially, one at a time
+
+```
+Task({
+  subagent_type: "pbr:executor",
+  prompt: <executor prompt constructed above>
+})
+
+NOTE: The pbr:executor subagent type auto-loads the agent definition.
 
-**Path resolution**: Before constructing the 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.
+After executor completes, check for completion markers: `## PLAN COMPLETE`, `## PLAN FAILED`, or `## CHECKPOINT: {TYPE}`. Route accordingly — PLAN COMPLETE proceeds to next plan, PLAN FAILED triggers failure handling, CHECKPOINT triggers checkpoint flow. Do NOT inline it.
+```
+
+**Path resolution**: Before constructing the 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.
 
 #### 6b. Wait for Wave Completion
 
-Block until all executor agents for this wave complete.
+Block until all executor Task() calls for this wave complete.
 
 #### 6c. Read Results
 
@@ -360,7 +409,7 @@ For each completed executor:
 3. Extract status: `completed` | `partial` | `checkpoint` | `failed`
 4. Display per-plan completion to the user:
    ```
-   Plan {id} complete — {brief summary from SUMMARY.md frontmatter description or first key_file}
+   ✓ Plan {id} complete — {brief summary from SUMMARY.md frontmatter description or first key_file}
    ```
    Extract the brief summary from the SUMMARY.md frontmatter (use the `description` field if present, otherwise use the first entry from `key_files`).
 5. Record commit hashes, files created, deviations
@@ -368,70 +417,78 @@ For each completed executor:
 
 **Spot-check executor claims:**
 
-After reading each SUMMARY, perform a lightweight verification:
-- Pick 2-3 files from the SUMMARY's `key_files` list and verify they exist (`ls`)
-- Run `git log --oneline -n {commit_count}` and confirm the count matches the claimed commits
-- For each spot-checked file, verify it has >10 lines (`wc -l`): warn if trivially small
-- For each spot-checked file, search for TODO/FIXME/placeholder/stub markers: warn if found
-- Check SUMMARY.md frontmatter for `self_check_failures`: if present, warn the user:
-  "Plan {id} reported self-check failures: {list failures}. Inspect before continuing?"
-- If ANY spot-check fails, warn the user before proceeding to the next wave:
-  "Spot-check failed for plan {id}: {detail}. Inspect before continuing?"
+CRITICAL (no hook): Before reading results or advancing to the next wave, run the spot-check CLI for each completed plan.
 
-**Read executor deviations:**
+For each completed plan in this wave:
+
+```bash
+node ${PLUGIN_ROOT}/scripts/pbr-tools.js spot-check {phaseSlug} {planId}
+```
 
+Where `{phaseSlug}` is the phase directory name (e.g., `49-build-workflow-hardening`) and `{planId}` is the plan identifier (e.g., `49-01`).
+
+The command returns JSON: `{ ok, summary_exists, key_files_checked, commits_present, detail }`
+
+**If `ok` is `false` for ANY plan: STOP.** Do NOT advance to the next wave. Present the user with:
+
+```
+Spot-check FAILED for plan {planId}: {detail}
+
+Choose an action:
+  Retry   — Re-spawn executor for this plan
+  Continue — Skip this plan and proceed to next wave (may leave phase incomplete)
+  Abort   — Stop the build entirely
+```
+
+Use AskUserQuestion with the three options. Route:
+
+- Retry: Re-spawn the executor for this plan (go back to Step 6a for this plan only)
+- Continue: Log the failure, skip the plan, proceed
+- Abort: Stop all build work, leave phase in partial state
+
+**If `ok` is `true` for all plans:**
+
+- Also check SUMMARY.md frontmatter for `self_check_failures`: if present, warn the user: "Plan {id} reported self-check failures: {list}. Inspect before continuing?"
+- Also search SUMMARY.md for `## Self-Check: FAILED` marker — if present, warn before next wave
+- Between waves: verify no file conflicts from parallel executors (`git status` for uncommitted changes)
+
+**Read executor deviations:**
 After all executors in the wave complete, read all SUMMARY frontmatter and:
 - Collect `deferred` items into a running list (append to `.checkpoint-manifest.json` deferred array)
 - Flag any deviation-rule-4 (architectural) stops — these require user attention
 - Present a brief wave summary to the user:
   "Wave {W} complete. {N} plans done. {D} deferred ideas logged. {A} architectural issues."
 
-Build a wave results table:
+Build a wave results table using standardized status symbols (`✓` complete, `✗` failed, `◆` in-progress, `○` pending — see `@references/ui-brand.md`):
 
 ```
 Wave {W} Results:
 | Plan | Status | Tasks | Commits | Deviations |
 |------|--------|-------|---------|------------|
-| {id} | complete | 3/3 | abc, def, ghi | 0 |
-| {id} | complete | 2/2 | jkl, mno | 1 |
+| {id} | ✓ complete | 3/3 | abc, def, ghi | 0 |
+| {id} | ✓ complete | 2/2 | jkl, mno | 1 |
 ```
 
 #### 6c-ii. Inline Per-Task Verification (conditional)
 
 **Skip if** the depth profile has `features.inline_verify: false`.
 
-To check: use the resolved depth profile. Only `comprehensive` mode enables inline verification by default.
-
-When inline verification is enabled, each completed plan gets a targeted verification pass before the orchestrator proceeds to the next wave. This catches issues early — before dependent plans build on a broken foundation.
+To check: use the resolved depth profile. Only `comprehensive` mode enables inline verification by default. When inline verification is enabled, each completed plan gets a targeted verification pass before the orchestrator proceeds to the next wave — catching issues early before dependent plans build on a broken foundation.
 
 For each plan that completed successfully in this wave:
 
 1. Read the plan's SUMMARY.md to get `key_files` (the files this plan created/modified)
-2. Display to the user: `Spawning inline verifier for plan {plan_id}...`
-
-   Invoke `@verifier` with a lightweight targeted verification prompt:
-
-```
-Targeted inline verification for plan {plan_id}.
-
-Verify ONLY these files: {comma-separated key_files list}
-
-For each file, check three layers:
-1. Existence — does the file exist?
-2. Substantiveness — is it more than a stub? (>10 lines, no TODO/FIXME placeholders)
-3. Wiring — is it imported/used by at least one other file?
+2. Display to the user: `◆ Spawning inline verifier for plan {plan_id}...`
 
-Report PASS or FAIL with a one-line reason per file.
-Write nothing to disk — just return your results as text.
-```
+   Spawn `Task({ subagent_type: "pbr:verifier", model: "haiku", prompt: ... })`. Read `${CLAUDE_SKILL_DIR}/templates/inline-verifier-prompt.md.tmpl` and fill in `{NN}-{slug}`, `{plan_id}`, and `{comma-separated key_files list}` (key_files from PLAN.md frontmatter). Use the filled template as the `prompt` value.
 
 3. If verifier reports FAIL for any file:
    - Present the failure to the user: "Inline verify failed for plan {plan_id}: {details}"
-   - Re-invoke the executor for just the failed items: include only the failing file context in the prompt
+   - Re-spawn the executor for just the failed items: include only the failing file context in the prompt
    - If the retry also fails: proceed but flag in the wave results table (don't block indefinitely)
 4. If verifier reports all PASS: continue to next wave
 
-**Note:** This adds latency (~10-20s per plan for the verifier). It's opt-in via `features.inline_verify: true` for projects where early detection outweighs speed.
+**Note:** This adds latency (~10-20s per plan for the haiku verifier). It's opt-in via `features.inline_verify: true` for projects where early detection outweighs speed.
 
 ---
 
@@ -441,7 +498,7 @@ If any executor returned `failed` or `partial`:
 
 **Handoff bug check (false-failure detection):**
 
-Before presenting failure options, check whether the executor actually completed its work despite reporting failure:
+Before presenting failure options, check whether the executor actually completed its work despite reporting failure (known Claude Code platform bug where handoff reports failure but work is done):
 
 1. Check if SUMMARY.md exists at the expected path for this plan
 2. If SUMMARY.md exists:
@@ -463,17 +520,17 @@ Plan {id} {status}:
   Last verify output: {output}
 ```
 
-Use the multi-option-failure pattern from `skills/shared/gate-prompts.md`:
+Use AskUserQuestion (pattern: multi-option-failure from `skills/shared/gate-prompts.md`):
   question: "Plan {id} failed at task {N} ({name}). How should we proceed?"
   header: "Failed"
   options:
-    - label: "Retry"     description: "Re-invoke the executor for this plan"
+    - label: "Retry"     description: "Re-spawn the executor for this plan"
     - label: "Skip"      description: "Mark as skipped, continue to next wave"
     - label: "Rollback"  description: "Undo commits from this plan, revert to last good state"
     - label: "Abort"     description: "Stop the entire build"
 
 **If user selects 'Retry':**
-- Re-invoke executor with the same prompt
+- Re-spawn executor Task() with the same prompt
 - If retry also fails: ask user again (max 2 retries total)
 
 **If user selects 'Skip':**
@@ -482,19 +539,22 @@ Use the multi-option-failure pattern from `skills/shared/gate-prompts.md`:
 - If yes: warn user that those plans will also need to be skipped or adjusted
 
 **If user selects 'Rollback':**
-- Read `last_good_commit` from `.checkpoint-manifest.json`
-- If `last_good_commit` exists:
-  - Show the user: "Rolling back to commit {sha} (last verified good state). This will soft-reset {N} commits."
-  - Run: `git reset --soft {last_good_commit}`
-  - Delete the failed plan's SUMMARY.md file if it was created
-  - Update the checkpoint manifest: remove the failed plan from `checkpoints_resolved`
-  - Continue to next wave or stop based on user preference
-- If no `last_good_commit`: warn "No rollback point available (this was the first plan). Use abort instead."
+Run the rollback CLI:
+
+```bash
+node ${PLUGIN_ROOT}/scripts/pbr-tools.js rollback .planning/phases/{NN}-{slug}/.checkpoint-manifest.json
+```
+
+Returns `{ ok, rolled_back_to, plans_invalidated, files_deleted, warnings }`.
+
+- If `ok` is `true`: display "Rolled back to commit {rolled_back_to}. {plans_invalidated.length} downstream plans invalidated."
+  Show any warnings. Continue to next wave or stop based on user preference.
+- If `ok` is `false`: display the error message. Suggest "Use abort instead."
 
 **If user selects 'Abort':**
 - Update STATE.md with current progress
 - Present what was completed before the abort
-- Suggest: "Fix the issue and run `/pbr:build {N}` to resume (completed plans will be skipped)"
+- Suggest: "Fix the issue and run `/pbr:execute-phase {N}` to resume (completed plans will be skipped)"
 
 #### 6e. Handle Checkpoints
 
@@ -514,55 +574,54 @@ Checkpoint in Plan {id}, Task {N}: {checkpoint type}
 ```
 
 3. Wait for user response
-4. Invoke a FRESH continuation executor:
+4. Spawn a FRESH continuation executor:
 
 Reference: `references/continuation-format.md` for the continuation protocol.
 
-```
-You are the executor agent. Continue executing a plan from a checkpoint.
-
-<plan_summary>
-[Inline only the ## Summary section from PLAN.md]
-</plan_summary>
+Read `${CLAUDE_SKILL_DIR}/templates/continuation-prompt.md.tmpl` and fill in:
 
-<plan_file>
-.planning/phases/{NN}-{slug}/{plan_id}-PLAN.md
-</plan_file>
+- `{NN}-{slug}`, `{plan_id}` — current phase and plan
+- `{plan_summary}` — the ## Summary section from PLAN.md
+- `{task table rows}` — one row per task with completion status
+- `{user's response}` — the checkpoint resolution from Step 3
+- `{project context key-values}` — config values + file paths
 
-<completed_tasks>
-| Task | Commit | Status |
-|------|--------|--------|
-| {task_name} | {hash} | complete |
-| {task_name} | {hash} | complete |
-| {checkpoint_task} | — | checkpoint |
-</completed_tasks>
+Use the filled template as the Task() prompt.
 
-<checkpoint_resolution>
-User response to checkpoint: {user's response}
-Resume at: Task {N+1} (or re-execute checkpoint task with user's answer)
-</checkpoint_resolution>
+#### 6e-ii. CI Gate (after wave completion, conditional)
 
-<project_context>
-{Same lean context as original spawn — config key-values + file paths, not inlined bodies}
-</project_context>
+If `config.ci.gate_enabled` is `true` AND `config.git.branching` is not `none`:
 
-Continue execution from the checkpoint. Skip completed tasks. Process the checkpoint resolution, then continue with remaining tasks. Write SUMMARY.md when done.
-```
+1. Push current commits: `git push`
+2. Wait 5 seconds for CI to trigger
+3. Get the current run ID:
+   ```bash
+   gh run list --branch $(git branch --show-current) --limit 1 --json databaseId -q '.[0].databaseId'
+   ```
+4. Poll CI status using CLI:
+   ```bash
+   node ${PLUGIN_ROOT}/scripts/pbr-tools.js ci-poll <run-id> [--timeout <seconds>]
+   ```
+   Returns `{ status, conclusion, url, next_action, elapsed_seconds }`.
+5. If `next_action` is `"continue"`: proceed to next wave
+6. If `next_action` is `"wait"`: re-run ci-poll after 15 seconds (repeat up to `config.ci.wait_timeout_seconds`)
+7. If `next_action` is `"abort"` or `status` is `"failed"`:
+   Show warning box and use AskUserQuestion: Wait / Continue anyway / Abort
+8. If "Continue anyway": log deviation — `DEVIATION: CI gate bypassed for wave {N}`
+9. If "Abort": stop build, update STATE.md
 
 #### 6f. Update STATE.md
 
 After each wave completes (all plans in the wave are done, skipped, or aborted):
 
 **SUMMARY gate — verify before updating STATE.md:**
+For every plan in the wave, run:
 
-Before writing any STATE.md update, verify these three gates for every plan in the wave:
-1. SUMMARY file exists at the expected path
-2. SUMMARY file is not empty (file size > 0)
-3. SUMMARY file has a valid title and YAML frontmatter (contains `---` delimiters and a `status:` field)
+```bash
+node ${PLUGIN_ROOT}/scripts/pbr-tools.js summary-gate {phase-slug} {plan-id}
+```
 
-Block the STATE.md update until ALL gates pass. If any gate fails:
-- Warn user: "SUMMARY gate failed for plan {id}: {which gate}. Cannot update STATE.md."
-- Ask user to retry the executor or manually inspect the SUMMARY file
+Returns `{ ok: bool, gate: string, detail: string }`. Block STATE.md update until ALL plans return `ok: true`. If any fail, warn: "SUMMARY gate failed for plan {id}: {gate} — {detail}. Cannot update STATE.md."
 
 Once gates pass, update `.planning/STATE.md`:
 
@@ -580,11 +639,20 @@ node ${PLUGIN_ROOT}/scripts/pbr-tools.js state update last_activity now
 
 **STATE.md size limit:** Follow the size limit enforcement rules in `skills/shared/state-update.md` (150 lines max — collapse completed phases, remove duplicated decisions, trim old sessions).
 
+**Completion check:** Before proceeding to next wave, confirm ALL of:
+- [ ] SUMMARY gate passed for every plan in this wave
+- [ ] STATE.md frontmatter `plans_complete` updated
+- [ ] STATE.md body progress bar updated
+- [ ] `last_activity` timestamp refreshed
+
+To verify programmatically: `node ${PLUGIN_ROOT}/scripts/pbr-tools.js step-verify build step-6f '["STATE.md updated","SUMMARY.md exists","commit made"]'`
+If any item fails, investigate before proceeding to Step 7.
+
 ---
 
 ### Step 7: Phase Verification (delegated, conditional)
 
-**Event-driven auto-verify signal:** Check if `.planning/.auto-verify` exists (written by event hooks). If the signal file exists, read it and delete it (one-shot). The signal confirms that auto-verification was triggered — proceed with verification even if the build just finished.
+**Event-driven auto-verify signal:** Check if `.planning/.auto-verify` exists (written by `event-handler.js` SubagentStop hook). If the signal file exists, read it and delete it (one-shot). The signal confirms that auto-verification was triggered — proceed with verification even if the build just finished.
 
 **Skip if:**
 - Build was aborted
@@ -596,26 +664,45 @@ To check: run `node ${PLUGIN_ROOT}/scripts/pbr-tools.js config resolve-depth` an
 This implements budget mode's "skip verifier for < 3 tasks" rule: small phases in quick mode don't need a full verification pass.
 
 **If skipping because `features.goal_verification` is `false`:**
-Note for Step 8f completion summary: append "Note: Automatic verification was skipped (goal_verification: false). Run `/pbr:review {N}` to verify what was built."
+Note for Step 8f completion summary: append "Note: Automatic verification was skipped (goal_verification: false). Run `/pbr:verify-work {N}` to verify what was built."
 
 **If verification is enabled:**
 
-Display to the user: `Spawning verifier...`
+Display to the user: `◆ Spawning verifier...`
+
+Spawn a verifier Task():
 
-Invoke the `@verifier` agent with the verifier prompt.
+```
+Task({
+  subagent_type: "pbr:verifier",
+  prompt: <verifier prompt>
+})
+
+NOTE: The pbr:verifier subagent type auto-loads the agent definition. Do NOT inline it.
 
-**NOTE**: The `@verifier` agent is defined in `agents/verifier.md`. Do NOT inline it.
+After verifier completes, check for completion marker: `## VERIFICATION COMPLETE`. Read VERIFICATION.md frontmatter for status.
+```
 
-**Path resolution**: Before constructing the 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 the 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
 
-Use the same verifier prompt template as defined in `/pbr:review`: read `skills/review/templates/verifier-prompt.md.tmpl` and fill in its placeholders with the phase's PLAN.md must_haves and SUMMARY.md file paths. This avoids maintaining duplicate verifier prompts across skills.
+Use the same verifier prompt template as defined in `/pbr:verify-work`: read `${PLUGIN_ROOT}/skills/review/templates/verifier-prompt.md.tmpl` and fill in its placeholders with the phase's PLAN.md must_haves and SUMMARY.md file paths. This avoids maintaining duplicate verifier prompts across skills.
+
+**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>
+```
 
 After the verifier returns, read the VERIFICATION.md frontmatter and display the results:
 
-- If status is `passed`: display `Verifier: {X}/{Y} must-haves verified` (where X = `must_haves_passed` and Y = `must_haves_checked`)
-- If status is `gaps_found`: display `Verifier found {N} gap(s) — see VERIFICATION.md` (where N = `must_haves_failed`)
+- If status is `passed`: display `✓ Verifier: {X}/{Y} must-haves verified` (where X = `must_haves_passed` and Y = `must_haves_checked`)
+- If status is `gaps_found`: display `⚠ Verifier found {N} gap(s) — see VERIFICATION.md` (where N = `must_haves_failed`)
 
 ---
 
@@ -631,7 +718,7 @@ If `--gaps-only` flag was used AND `features.goal_verification` is `true`:
 2. Re-run the verifier using the same Step 7 process — this produces a fresh `VERIFICATION.md` that accounts for the gap-closure work
 3. Read the new verification status for use in determining `final_status` below
 
-This ensures that `/pbr:review` after a `--gaps-only` build sees the updated verification state, not stale gaps from before the fix.
+This ensures that `/pbr:verify-work` after a `--gaps-only` build sees the updated verification state, not stale gaps from before the fix.
 
 **8-pre-b. Determine final status based on verification:**
 - If verification ran and status is `passed`: final_status = "built"
@@ -641,18 +728,39 @@ This ensures that `/pbr:review` after a `--gaps-only` build sees the updated ver
 
 **8-pre-c. Codebase map incremental update (conditional):**
 
+**CRITICAL (no hook): Run codebase map update if conditions are met. Do NOT skip this step.**
+
 Only run if ALL of these are true:
-- `.planning/codebase/` directory exists (project was previously scanned with `/pbr:scan`)
+- `.planning/codebase/` directory exists (project was previously scanned with `/pbr:map-codebase`)
 - Build was not aborted
 - `git diff --name-only {pre_build_commit}..HEAD` shows >5 files changed OR `package.json`/`requirements.txt`/`go.mod`/`Cargo.toml` was modified
 
 If triggered:
 1. Record the pre-build commit SHA at the start of Step 1 (before any executors run) for comparison
 2. Run `git diff --name-only {pre_build_commit}..HEAD` to get the list of changed files
-3. Display to the user: `Spawning codebase mapper (incremental update)...`
+3. Display to the user: `◆ Spawning codebase mapper (incremental update)...`
+
+   Spawn a lightweight mapper Task():
+   ```
+   Task({
+     subagent_type: "pbr:codebase-mapper",
+     model: "haiku",
+     prompt: "Incremental codebase map update. These files changed during the Phase {N} build:\n{diff file list}\n\nRead the existing .planning/codebase/ documents. Update ONLY the sections affected by these changes. Do NOT rewrite entire documents — make targeted updates. If a new dependency was added, update STACK.md. If new directories/modules were created, update STRUCTURE.md. If new patterns were introduced, update CONVENTIONS.md. Write updated files to .planning/codebase/."
+   })
+   ```
+4. Do NOT block on this — use `run_in_background: true` and continue to Step 8a. Report completion in Step 8f if it finishes in time.
+
+**8-pre-d. Write phase manifest (on successful completion):**
+
+If all plans completed successfully (final_status is "built" or "built (unverified)"), write `.phase-manifest.json` to the phase directory. This manifest aggregates all plan commits for the undo skill's `--phase NN` mode:
+
+```bash
+node ${PLUGIN_ROOT}/scripts/pbr-tools.js phase write-manifest {phase-slug}
+```
 
-   Invoke `@codebase-mapper` with: "Incremental codebase map update. These files changed during the Phase {N} build:\n{diff file list}\n\nRead the existing .planning/codebase/ documents. Update ONLY the sections affected by these changes. Do NOT rewrite entire documents — make targeted updates. If a new dependency was added, update STACK.md. If new directories/modules were created, update STRUCTURE.md. If new patterns were introduced, update CONVENTIONS.md. Write updated files to .planning/codebase/."
-4. Do NOT block on this — run in background and continue to Step 8a. Report completion in Step 8f if it finishes in time.
+The manifest collects commit hashes from each plan's SUMMARY.md and stores them as a single artifact that `completePhase()` uses for rollback support. If the command fails, log a warning but do not block completion.
+
+**CRITICAL (no hook): Update ROADMAP.md progress table NOW. Do NOT skip this step. (roadmap-sync warns)**
 
 **8a. Update ROADMAP.md Progress table** (REQUIRED — do this BEFORE updating STATE.md):
 
@@ -670,11 +778,20 @@ These return `{ success, old_status, new_status }` or `{ success, old_plans, new
 5. Update the `Status` column to the final_status determined in Step 8-pre
 6. Save the file — do NOT skip this step
 
-**8b. Update STATE.md:**
-- Phase status: {final_status from Step 8-pre}
-- Plan completion count
-- Last activity timestamp
-- Progress bar
+**CRITICAL (no hook): Update STATE.md NOW with phase completion status. Do NOT skip this step. (state-sync warns)**
+
+**8b. Update STATE.md (CRITICAL (no hook) — update BOTH frontmatter AND body):**
+- Frontmatter: `status`, `plans_complete`, `last_activity`, `progress_percent`, `last_command`
+- Body `## Current Position`: `Phase:` line, `Plan:` line, `Status:` line, `Last activity:` line, `Progress:` bar
+- These MUST stay in sync — the status line reads frontmatter, humans read the body
+
+**Completion check:** Before proceeding to 8c, confirm ALL of:
+- [ ] STATE.md frontmatter fields set: status, plans_complete, last_activity, progress_percent, last_command
+- [ ] STATE.md body ## Current Position updated: Phase, Status, Last activity, Progress bar
+- [ ] Frontmatter and body are consistent (same status value in both)
+
+To verify programmatically: `node ${PLUGIN_ROOT}/scripts/pbr-tools.js step-verify build step-8b '["STATE.md updated","ROADMAP.md updated","commit made"]'`
+If any item fails, investigate before marking phase complete.
 
 **8c. Commit planning docs (if configured):**
 Reference: `skills/shared/commit-planning-docs.md` for the standard commit pattern.
@@ -686,7 +803,7 @@ If `planning.commit_docs` is `true`:
 If `git.branching` is `phase`:
 - All work was done on the phase branch (created in Step 1)
 - Squash merge to main: `git checkout main && git merge --squash plan-build-run/phase-{NN}-{name}`
-- 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} complete on branch `plan-build-run/phase-{NN}-{name}`. Squash merge to main?"
   header: "Merge?"
   options:
@@ -695,6 +812,31 @@ If `git.branching` is `phase`:
 - If "Yes, merge": complete the merge and delete the phase branch
 - If "No, keep" or "Other": leave the branch as-is and inform the user
 
+**8d-ii. PR Creation (when branching enabled):**
+
+If `config.git.branching` is `phase` or `milestone` AND phase verification passed:
+
+1. Push the phase branch: `git push -u origin {branch-name}`
+2. If `config.git.auto_pr` is `true`:
+   - Run: `gh pr create --title "feat({phase-scope}): {phase-slug}" --body "$(cat <<'EOF'
+## Phase {N}: {phase name}
+
+**Goal**: {phase goal from ROADMAP.md}
+
+### Key Files
+{key_files from SUMMARY.md, bulleted}
+
+### Verification
+{pass/fail status from VERIFICATION.md}
+
+---
+Generated by Plan-Build-Run
+EOF
+)"`
+3. If `config.git.auto_pr` is `false`:
+   - Use AskUserQuestion to ask: "Phase branch pushed. Create a PR?"
+   - Options: Yes (create PR as above) / No / Later (skip)
+
 **8e. Auto-advance / auto-continue (conditional):**
 
 **If `features.auto_advance` is `true` AND `mode` is `autonomous`:**
@@ -702,26 +844,54 @@ Chain to the next skill directly within this session. This eliminates manual pha
 
 | Build Result | Next Action | How |
 |-------------|-------------|-----|
-| Verification passed, more phases | Plan next phase | Chain to `/pbr:plan {N+1}` |
-| Verification skipped | Run review | Chain to `/pbr:review {N}` |
-| Verification gaps found | **HARD STOP** — present gaps to user | Do NOT auto-advance past failures |
-| Last phase complete | **HARD STOP** — milestone boundary | Suggest `/pbr:milestone audit` |
-| Build errors occurred | **HARD STOP** — errors need human review | Do NOT auto-advance past errors |
+| Verification passed, more phases | Plan next phase | `Skill({ skill: "pbr:plan", args: "{N+1}" })` |
+| Verification skipped | Run review | `Skill({ skill: "pbr:review", args: "{N}" })` |
+| Verification gaps found | **HARD STOP** — present gaps to user | If `auto_continue` also true: write `.planning/.auto-next` with `/pbr:verify-work {N}` before stopping. Do NOT auto-advance past failures. |
+| Last phase in current milestone | **HARD STOP** — milestone boundary | If `auto_continue` also true: write `.planning/.auto-next` with `/pbr:complete-milestone` before stopping. Suggest `/pbr:audit-milestone`. Explain: "auto_advance pauses at milestone boundaries — your sign-off is required." |
+| Build errors occurred | **HARD STOP** — errors need human review | If `auto_continue` also true: write `.planning/.auto-next` with `/pbr:execute-phase {N}` before stopping. Do NOT auto-advance past errors. |
 
-After invoking the chained skill, it runs within the same session. When it completes, the chained skill may itself chain further (review->plan, plan->build) if auto_advance remains true. This creates the full cycle: build->review->plan->build->...
+After invoking the chained skill, it runs within the same session. When it completes, the chained skill may itself chain further (review→plan, plan→build) if auto_advance remains true. This creates the full cycle: build→review→plan→build→...
 
 **Else if `features.auto_continue` is `true`:**
-Write `.planning/.auto-next` containing the next logical command (e.g., `/pbr:plan {N+1}` or `/pbr:review {N}`)
+Write `.planning/.auto-next` containing the next logical command (e.g., `/pbr:plan-phase {N+1}` or `/pbr:verify-work {N}`)
 - This file signals to the user or to wrapper scripts that the next step is ready
 
+**Completion check:** Before proceeding to 8f, confirm ALL of:
+- [ ] auto_advance OR auto_continue evaluated (one path taken)
+- [ ] If auto_continue: `.auto-next` file written with correct next command
+- [ ] Pending todos evaluated (Step 8e-ii)
+- [ ] Clearly-satisfied todos auto-closed via `pbr-tools.js todo done`
+
+To verify programmatically: `node ${PLUGIN_ROOT}/scripts/pbr-tools.js step-verify build step-8e '["STATE.md updated","commit made"]'`
+If any item fails, investigate before closing the session.
+
+**8e-ii. Check Pending Todos:**
+
+**CRITICAL (no hook): Check pending todos after build. Do NOT skip this step.**
+
+After completing the build, check if any pending todos are now satisfied:
+
+1. Check if `.planning/todos/pending/` exists and contains files
+2. If no pending todos: skip to 8f
+3. If pending todos exist:
+   a. Read the title and description from each pending todo's YAML frontmatter
+   b. Compare each todo against the phase work (plans executed, files changed, features built)
+   c. If a todo is **clearly satisfied**: move it to `.planning/todos/done/`, update `status: done`, add `completed: {YYYY-MM-DD}`, delete from `pending/` via Bash `rm`. Display: `✓ Auto-closed todo {NNN}: {title} (satisfied by Phase {N} build)`
+   d. If **partially related**: display `ℹ Related pending todo {NNN}: {title} — may be partially addressed`
+   e. If unrelated: skip silently
+
+Only auto-close when the match is unambiguous. When in doubt, leave it open.
+
 **8f. Present completion summary:**
 
-Use the branded output templates from `references/ui-formatting.md`. Route based on status:
+Use the branded output templates from `references/ui-brand.md`. Route based on status:
 
 | Status | Template |
 |--------|----------|
-| `passed` + more phases | "Phase Complete" template |
-| `passed` + last phase | "Milestone Complete" template |
+| `passed` + more phases in current milestone | "Phase Complete" template |
+| `passed` + last phase in current milestone | "Milestone Complete" template |
+
+**Milestone boundary detection:** To determine "last phase in current milestone", 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. For projects with a single milestone or no explicit milestone sections, "last phase in ROADMAP" is equivalent.
 | `gaps_found` | "Gaps Found" template |
 
 Before the branded banner, include the results table:
@@ -743,100 +913,13 @@ Total files modified: {count}
 Deviations: {count}
 ```
 
-Then present the appropriate branded banner:
+Then present the appropriate branded banner from Read `references/ui-brand.md` § "Completion Summary Templates":
 
-**If `passed` + more phases:**
-```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- PLAN-BUILD-RUN ► PHASE {N} COMPLETE
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-**Phase {N}: {Name}**
+- **If `passed` + more phases:** Use the "Phase Complete" template. Fill in phase number, name, plan count, and next phase details.
+- **If `passed` + last phase:** Use the "Milestone Complete" template. Fill in phase count.
+- **If `gaps_found`:** Use the "Gaps Found" template. Fill in phase number, name, score, and gap summaries from VERIFICATION.md.
 
-{X} plans executed
-Goal verified
-
----
-
-## Next Up
-
-**Phase {N+1}: {Name}** — {Goal from ROADMAP.md}
-
-`/pbr:plan {N+1}`
-
-`/clear` first for a fresh context window
-
----
-
-**Also available:**
-- `/pbr:review {N}` — manual acceptance testing before continuing
-- `/pbr:discuss {N+1}` — talk through the next phase before planning
-- `/pbr:status` — see full project status
-
----
-```
-
-**If `passed` + last phase:**
-```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- PLAN-BUILD-RUN ► MILESTONE COMPLETE
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-{N} phases completed
-All phase goals verified
-
----
-
-## Next Up
-
-**Audit milestone** — verify requirements, cross-phase integration, E2E flows
-
-`/pbr:milestone audit`
-
-`/clear` first for a fresh context window
-
----
-
-**Also available:**
-- `/pbr:review` — manual acceptance testing
-- `/pbr:milestone complete` — skip audit, archive directly
-
----
-```
-
-**If `gaps_found`:**
-```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- PLAN-BUILD-RUN ► PHASE {N} GAPS FOUND
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-**Phase {N}: {Name}**
-
-Score: {X}/{Y} must-haves verified
-Report: .planning/phases/{phase_dir}/VERIFICATION.md
-
-### What's Missing
-
-{Extract gap summaries from VERIFICATION.md}
-
----
-
-## Next Up
-
-**Plan gap closure** — create additional plans to complete the phase
-
-`/pbr:plan {N} --gaps`
-
-`/clear` first for a fresh context window
-
----
-
-**Also available:**
-- `cat .planning/phases/{phase_dir}/VERIFICATION.md` — see full report
-- `/pbr:review {N}` — manual testing before planning
-
----
-```
+Include `<sub>/clear first → fresh context window</sub>` inside the Next Up routing block of the completion template.
 
 **8g. Display USER-SETUP.md (conditional):**
 
@@ -857,9 +940,11 @@ This ensures the user sees setup requirements prominently instead of buried in S
 ## Error Handling
 
 ### Executor agent timeout
-If an executor agent doesn't return within a reasonable time, display:
+If a Task() doesn't return within a reasonable time, display:
 ```
-ERROR
+╔══════════════════════════════════════════════════════════════╗
+║  ERROR                                                       ║
+╚══════════════════════════════════════════════════════════════╝
 
 Executor agent timed out for Plan {id}.
 
@@ -872,7 +957,7 @@ For commit conventions and git workflow details, see `references/git-integration
 ### Git lock conflicts
 If multiple parallel executors create git lock conflicts:
 - The executor agent handles retries internally (see executor agent definition)
-- If lock conflicts persist, display: "Git lock conflicts detected with parallel execution. Consider reducing max_concurrent_agents to 1."
+- If lock conflicts persist, display: `⚠ Git lock conflicts detected with parallel execution. Consider reducing max_concurrent_agents to 1.`
 
 ### Executor produces unexpected files
 If SUMMARY.md shows files not listed in the plan's `files_modified`:
@@ -887,7 +972,7 @@ If `git.branching` is `phase` but we're not on the phase branch:
 
 ---
 
-## Files Created/Modified by /pbr:build
+## Files Created/Modified by /pbr:execute-phase
 
 | File | Purpose | When |
 |------|---------|------|
@@ -896,7 +981,13 @@ If `git.branching` is `phase` but we're not on the phase branch:
 | `.planning/phases/{NN}-{slug}/USER-SETUP.md` | External setup requirements | Step 6 (executor, if needed) |
 | `.planning/phases/{NN}-{slug}/VERIFICATION.md` | Phase verification report | Step 7 |
 | `.planning/codebase/*.md` | Incremental codebase map updates | Step 8-pre-c (if codebase/ exists) |
-| `.planning/ROADMAP.md` | Plans Complete + Status -> `built` or `partial` | Step 8a |
+| `.planning/ROADMAP.md` | Plans Complete + Status → `built` or `partial` | Step 8a |
 | `.planning/STATE.md` | Updated progress | Steps 6f, 8b |
 | `.planning/.auto-next` | Next command signal (if auto_continue enabled) | Step 8e |
 | Project source files | Actual code | Step 6 (executors) |
+
+---
+
+## Cleanup
+
+Delete `.planning/.active-skill` if it exists. This must happen on all paths (success, partial, and failure) before reporting results.