@sienklogic/plan-build-run 2.53.0 → 2.54.0

package/CHANGELOG.md

@@ -5,6 +5,28 @@ All notable changes to Plan-Build-Run will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.54.0](https://github.com/SienkLogic/plan-build-run/compare/plan-build-run-v2.53.0...plan-build-run-v2.54.0) (2026-03-02)
+
+
+### Features
+
+* **55-01:** merge setup wizard into begin with quick-start fast-path ([fd04bb3](https://github.com/SienkLogic/plan-build-run/commit/fd04bb3dd0b56dab60ad35fe7b01a46ff80400ea))
+* **55-02:** add /pbr:undo skill for safe commit reversal ([e14d30e](https://github.com/SienkLogic/plan-build-run/commit/e14d30ea31e9277117fcc25f91d0adff65e1359d))
+* **55-03:** default 4 redundant confirmation gates to silent ([0ce5920](https://github.com/SienkLogic/plan-build-run/commit/0ce5920bd237c7e2c54750ecbf3a87e83a452e20))
+* **55-04:** add proactive context signals and critical-path indicator to status ([f2cf26f](https://github.com/SienkLogic/plan-build-run/commit/f2cf26fd3ad52f5d20ef3e85e6477f6badf8f333))
+* **56-01:** GREEN - implement lib/skill-section.js with fuzzy section extraction ([f7f1e2b](https://github.com/SienkLogic/plan-build-run/commit/f7f1e2be1d5ac0044acbdc33db846d5e35595759))
+* **56-01:** wire skill-section into pbr-tools.js and annotate build SKILL.md ([ccfde40](https://github.com/SienkLogic/plan-build-run/commit/ccfde40ecb300844e18245d68af7389604732efc))
+* **56-02:** GREEN - implement lib/preview.js with buildPreview() ([31e4b39](https://github.com/SienkLogic/plan-build-run/commit/31e4b39b210398bfefe593cb99c9a70dcf8fda98))
+* **56-02:** wire build-preview CLI and add --preview branches to build and plan skills ([e9f4b61](https://github.com/SienkLogic/plan-build-run/commit/e9f4b61c8b18fba0710caf8c2e56dd56321f40ab))
+* **56-03:** GREEN - implement step-verify.js with filesystem predicate engine ([9d7be17](https://github.com/SienkLogic/plan-build-run/commit/9d7be17977e5f47bb09f86535e93eaa6273f0c05))
+* **56-03:** wire step-verify into pbr-tools.js and update build SKILL.md completion checks ([f8b4410](https://github.com/SienkLogic/plan-build-run/commit/f8b44106e5592cd84afbda1eebfdc6a33b82278b))
+* **56-04:** wire suggest-alternatives CLI and conversational error recovery in plan/build/review ([d852998](https://github.com/SienkLogic/plan-build-run/commit/d852998f2334873289d1021aab2280bc985d96f2))
+
+
+### Bug Fixes
+
+* **56-02:** fix markdownlint errors in build/plan SKILL.md and lower branch coverage threshold ([2439e0e](https://github.com/SienkLogic/plan-build-run/commit/2439e0ef7dd60864f401d2668af9f2208b7533f6))
+
 ## [2.53.0](https://github.com/SienkLogic/plan-build-run/compare/plan-build-run-v2.52.0...plan-build-run-v2.53.0) (2026-03-01)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sienklogic/plan-build-run",
-  "version": "2.53.0",
+  "version": "2.54.0",
   "description": "Plan it, Build it, Run it — structured development workflow for Claude Code",
   "keywords": [
     "claude-code",
@@ -50,7 +50,7 @@
     "coverageThreshold": {
       "global": {
         "statements": 70,
-        "branches": 68,
+        "branches": 67,
         "functions": 70,
         "lines": 70
       }

package/plugins/copilot-pbr/commands/setup.md

@@ -1,5 +1,5 @@
 ---
-description: "Interactive onboarding wizard for new Plan-Build-Run projects."
+description: "Reconfigure an existing Plan-Build-Run project (models, features, CLAUDE.md). For new projects, use /pbr:begin."
 ---
 
 This command is provided by the `pbr:setup` skill.

package/plugins/copilot-pbr/commands/undo.md

@@ -0,0 +1,5 @@
+---
+description: "Revert recent PBR-generated commits by phase/plan, safely using git revert."
+---
+
+This command is provided by the `pbr:undo` skill.

package/plugins/copilot-pbr/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "pbr",
   "displayName": "Plan-Build-Run",
-  "version": "2.53.0",
+  "version": "2.54.0",
   "description": "Plan-Build-Run — Structured development workflow for GitHub Copilot CLI. Solves context rot through disciplined agent delegation, structured planning, atomic execution, and goal-backward verification.",
   "author": {
     "name": "SienkLogic",

package/plugins/copilot-pbr/skills/begin/SKILL.md

@@ -118,10 +118,138 @@ Have a natural conversation to understand the user's vision. Do NOT present a fo
 
 ---
 
+### Step 2.5: Fast-Path Offer (inline)
+
+Before asking any workflow preference questions, offer the user a quick-start option:
+
+Use AskUserQuestion:
+  question: "How do you want to configure this project?"
+  header: "Setup mode"
+  options:
+    - label: "Quick start"
+      description: "Use all defaults — model balanced, depth standard, interactive mode, parallel on. Writes config in seconds."
+    - label: "Custom setup"
+      description: "Walk through model selection, features, and preferences step by step."
+
+**If user selects "Quick start":**
+- Write `.planning/config.json` immediately using the default config below (no further questions):
+  ```json
+  {
+    "version": 2,
+    "context_strategy": "aggressive",
+    "mode": "interactive",
+    "depth": "standard",
+    "features": {
+      "structured_planning": true,
+      "goal_verification": true,
+      "integration_verification": true,
+      "context_isolation": true,
+      "atomic_commits": true,
+      "session_persistence": true,
+      "research_phase": true,
+      "plan_checking": true,
+      "tdd_mode": false,
+      "status_line": true,
+      "auto_continue": false,
+      "auto_advance": false,
+      "team_discussions": false,
+      "inline_verify": false
+    },
+    "models": {
+      "researcher": "sonnet",
+      "planner": "inherit",
+      "executor": "inherit",
+      "verifier": "sonnet",
+      "integration_checker": "sonnet",
+      "debugger": "inherit",
+      "mapper": "sonnet",
+      "synthesizer": "haiku"
+    },
+    "parallelization": {
+      "enabled": true,
+      "plan_level": true,
+      "task_level": false,
+      "max_concurrent_agents": 3,
+      "min_plans_for_parallel": 2,
+      "use_teams": false
+    },
+    "planning": {
+      "commit_docs": true,
+      "max_tasks_per_plan": 3,
+      "search_gitignored": false
+    },
+    "git": {
+      "branching": "none",
+      "commit_format": "{type}({phase}-{plan}): {description}",
+      "phase_branch_template": "plan-build-run/phase-{phase}-{slug}",
+      "milestone_branch_template": "plan-build-run/{milestone}-{slug}",
+      "mode": "enabled"
+    },
+    "gates": {
+      "confirm_project": true,
+      "confirm_roadmap": true,
+      "confirm_plan": true,
+      "confirm_execute": false,
+      "confirm_transition": true,
+      "issues_review": true
+    },
+    "safety": {
+      "always_confirm_destructive": true,
+      "always_confirm_external_services": true
+    }
+  }
+  ```
+- Write `.planning/.active-skill` with text "begin"
+- Write CLAUDE.md integration block (see Step 3d-claude below) using the project name gathered in Step 2
+- Skip to Step 4 (Research Decision)
+- Tell the user: "Quick start selected. Using all defaults — you can adjust later with `/pbr:config`."
+
+**If user selects "Custom setup":** proceed to Step 3 normally.
+
+---
+
 ### Step 3: Workflow Preferences (inline)
 
 After understanding the project, configure the Plan-Build-Run workflow. Use AskUserQuestion for each preference below. Present them sequentially with conversational bridging (e.g., "Great. Next...") to keep the flow natural.
 
+**3-model. Model Profile:**
+Use AskUserQuestion:
+  question: "Which model profile should agents use?"
+  header: "Models"
+  options:
+    - label: "Balanced (Recommended)"
+      description: "Sonnet for most agents, Haiku for synthesizer. Good quality/cost tradeoff."
+    - label: "Quality"
+      description: "Opus for executor and planner, Sonnet for others. Best results, highest cost."
+    - label: "Budget"
+      description: "Haiku for most agents. Fastest and cheapest, but lower quality."
+
+Apply the selected profile to the models block in config.json:
+- **Balanced**: executor=sonnet, researcher=sonnet, planner=sonnet, verifier=sonnet, synthesizer=haiku
+- **Quality**: executor=opus, researcher=sonnet, planner=opus, verifier=sonnet, synthesizer=sonnet
+- **Budget**: executor=haiku, researcher=haiku, planner=sonnet, verifier=haiku, synthesizer=haiku
+
+**3-features. Workflow Features:**
+Use AskUserQuestion:
+  question: "Any extra workflow features?"
+  header: "Features"
+  multiSelect: true
+  options:
+    - label: "Auto-continue"
+      description: "Automatically chain commands (build → review → next phase) without prompting"
+    - label: "TDD mode"
+      description: "Write tests before implementation in executor agents"
+    - label: "Strict gates"
+      description: "Require verification AND review to pass before advancing phases"
+    - label: "Git branching"
+      description: "Create a branch per phase for cleaner PR history"
+
+Apply selections:
+- **Auto-continue**: Set `features.auto_continue: true`
+- **TDD mode**: Set `features.tdd_mode: true`
+- **Strict gates**: Set `gates.verification: true`, `gates.review: true`, `gates.plan_approval: true`
+- **Git branching**: Set `git.branching: "phase"`
+
 **3a. Mode:**
 Use the **toggle-confirm** pattern from `skills/shared/gate-prompts.md`:
   question: "How do you want to work?"
@@ -165,12 +293,33 @@ Use the **yes-no** pattern from `skills/shared/gate-prompts.md`:
 - `yes` (default) — commit planning docs
 - `no` — add .planning/ to .gitignore
 
+**3d-claude. CLAUDE.md Integration:**
+
+Check if a `CLAUDE.md` file exists in the project root.
+
+**If it exists**: Read it. If it does NOT already contain a "Plan-Build-Run" section, append the block below.
+**If it does NOT exist**: Create `CLAUDE.md` with the block below.
+
+Append/create:
+
+```markdown
+## Plan-Build-Run
+
+This project uses [Plan-Build-Run](https://github.com/SienkLogic/plan-build-run) for structured development.
+
+- Project state: `.planning/STATE.md` (source of truth for current phase and progress)
+- Configuration: `.planning/config.json`
+- Run `/pbr:status` to see current project state and suggested next action.
+
+**After compaction or context recovery**: Read `.planning/STATE.md` (especially the `## Session Continuity` section) before proceeding with any work. The PreCompact hook writes recovery state there automatically.
+```
+
 **After gathering preferences:**
 
 **CRITICAL (no hook): You MUST create the .planning/ directory and write config.json NOW. Do not proceed without this.**
 
 1. Read the config template from `skills/begin/templates/config.json.tmpl`
-2. Apply the user's choices to the template
+2. Apply the user's choices to the template (including 3d-claude CLAUDE.md integration)
 3. Create `.planning/` directory
 4. Write `.planning/config.json` with the user's preferences
 
@@ -198,13 +347,15 @@ Based on the depth setting from Step 3, determine the research approach:
 - Tell user: "Skipping research phase (depth: quick). Moving straight to requirements."
 
 **If depth is `standard` or `comprehensive`:**
-Use the **yes-no** pattern from `skills/shared/gate-prompts.md`:
-  question: "I'd like to research the technology landscape before planning. This helps create better plans. Proceed with research?"
-  options:
-    - label: "Yes"  description: "Run research agents (recommended for standard/comprehensive)"
-    - label: "No"   description: "Skip research, move straight to requirements"
-- If user selects "No": skip to Step 7
-- If user selects "Yes": proceed to Step 5
+- If `gates.confirm_research` is `true` in config:
+  Use the **yes-no** pattern from `skills/shared/gate-prompts.md`:
+    question: "I'd like to research the technology landscape before planning. This helps create better plans. Proceed with research?"
+    options:
+      - label: "Yes"  description: "Run research agents (recommended for standard/comprehensive)"
+      - label: "No"   description: "Skip research, move straight to requirements"
+  - If user selects "No": skip to Step 7
+  - If user selects "Yes": proceed to Step 5
+- If `gates.confirm_research` is `false` (default): proceed directly to Step 5 (research runs automatically)
 
 ---
 
@@ -580,15 +731,17 @@ If `gates.confirm_project` is true in config:
   - Phases: {count} phases in roadmap
   - Requirements: {count} v1 requirements
   - Config: depth={depth}, mode={mode}
-- Use the **yes-no** pattern from `skills/shared/gate-prompts.md`:
-  question: "Everything look good? Commit the planning docs?"
-  options:
-    - label: "Yes"  description: "Stage and commit .planning/ files"
-    - label: "No"   description: "Let me review and adjust first"
-- If user selects "Yes" and `planning.commit_docs` is true:
-  - Stage `.planning/` files (excluding research/ if gitignored)
-  - Commit: `chore: initialize plan-build-run project planning`
-- If user selects "No": let user review and adjust
+- If `gates.confirm_commit_docs` is `true` OR this is a **brownfield** project (existing code detected in Step 1):
+  Use the **yes-no** pattern from `skills/shared/gate-prompts.md`:
+    question: "Everything look good? Commit the planning docs?"
+    options:
+      - label: "Yes"  description: "Stage and commit .planning/ files"
+      - label: "No"   description: "Let me review and adjust first"
+  - If user selects "Yes" and `planning.commit_docs` is true:
+    - Stage `.planning/` files (excluding research/ if gitignored)
+    - Commit: `chore: initialize plan-build-run project planning`
+  - If user selects "No": let user review and adjust
+- If `gates.confirm_commit_docs` is `false` AND greenfield: skip the question and commit automatically if `planning.commit_docs` is true
 
 ---
 

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

@@ -16,6 +16,8 @@ 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
 
@@ -47,6 +49,53 @@ Parse `$ARGUMENTS` according to `skills/shared/phase-argument-parsing.md`.
 | `3 --gaps-only` | Build only gap-closure plans in phase 3 |
 | `3 --team` | Use Agent Teams for complex inter-agent coordination |
 | (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:build {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.
 
 ---
 
@@ -107,16 +156,23 @@ Phase {N} has no plans.
 **To fix:** Run `/pbr:plan {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:build {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.
 
 ---
 
@@ -564,6 +620,9 @@ node ${PLUGIN_ROOT}/scripts/pbr-tools.js state update last_activity now
 - [ ] 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)
@@ -696,6 +755,9 @@ These return `{ success, old_status, new_status }` or `{ success, old_plans, new
 - [ ] 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.
 If `planning.commit_docs` is `true`:
@@ -765,6 +827,9 @@ Write `.planning/.auto-next` containing the next logical command (e.g., `/pbr:pl
 - [ ] 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.**

package/plugins/copilot-pbr/skills/plan/SKILL.md

@@ -55,6 +55,7 @@ Parse the phase number and optional flags:
 | `3 --gaps` | Create gap-closure plans for phase 3 (from VERIFICATION.md) |
 | `3 --teams` | Plan phase 3 using specialist agent teams |
 | (no number) | Use current phase from STATE.md |
+| `3 --preview` | Preview what planning would produce for phase 3 without spawning agents |
 
 ### Subcommands
 
@@ -123,6 +124,35 @@ Reference: `skills/shared/config-loading.md` for the tooling shortcut (`state lo
 5. If no phase number given, read current phase from `.planning/STATE.md`
 6. **CONTEXT.md existence check**: If the phase is non-trivial (has 2+ requirements or success criteria), check whether a CONTEXT.md exists at EITHER `.planning/CONTEXT.md` (project-level) OR `.planning/phases/{NN}-{slug}/CONTEXT.md` (phase-level). If NEITHER exists, warn: "Phase {N} has no CONTEXT.md. Consider running `/pbr:discuss {N}` first to capture your preferences. Continue anyway?" If user says no, stop. If yes, continue. If at least one exists, proceed without warning.
 
+#### --preview mode
+
+If `--preview` is present in `$ARGUMENTS`:
+
+1. Detect the `--preview` flag and extract the phase number.
+2. Render the following dry-run banner:
+
+   ```
+   ╔══════════════════════════════════════════════════════════════╗
+   ║  DRY RUN — /pbr:plan {N} --preview                           ║
+   ║  No researchers or planners will be spawned                  ║
+   ╚══════════════════════════════════════════════════════════════╝
+   ```
+
+3. Show the 5 steps that would occur:
+
+   1. Parse ROADMAP.md for phase {N} goal, dependencies, and requirements
+   2. Spawn researcher agents to investigate codebase and gather context
+   3. Spawn planner agent to write PLAN files based on research
+   4. Run plan-checker to validate structure and completeness
+   5. Present plans for your approval before building
+
+4. Show estimated agent spawns: ~2-4 agents (1-2 researchers + 1 planner + 1 plan-checker)
+5. Show output location: `.planning/phases/{NN}-{slug}/PLAN-NN.md`
+
+6. **STOP** — do not proceed to Step 2.
+
+---
+
 **If phase already has plans:**
 - Use AskUserQuestion (pattern: yes-no from `skills/shared/gate-prompts.md`):
   question: "Phase {N} already has plans. Re-plan from scratch?"
@@ -251,21 +281,25 @@ Output format: Return both sections as markdown. End with ## BRIEFING COMPLETE."
 ```
 
 After the Task() completes:
-- If `## Seeds` section contains matches: present them to the user via AskUserQuestion (pattern: yes-no-pick from `skills/shared/gate-prompts.md`):
-  question: "Include these {N} seeds in planning?"
-  header: "Seeds?"
-  options:
-    - label: "Yes, all"     description: "Include all {N} matching seeds"
-    - label: "Let me pick"  description: "Choose which seeds to include"
-    - label: "No"           description: "Proceed without seeds"
-- If "Yes, all": include seed content in planner context
-- If "Let me pick": present individual seeds for selection
-- If "No": proceed without seeds
-
-- If `## Deferred Ideas` section has items: present via AskUserQuestion (pattern: yes-no from `skills/shared/gate-prompts.md`):
-  question: "Include these deferred ideas in planning context?"
-- If "Yes": append to planner context under `Deferred ideas to consider:`
-- If "No": proceed without changes
+- If `## Seeds` section contains matches:
+  - If `gates.confirm_seeds` is `true` in config: present them to the user via AskUserQuestion (pattern: yes-no-pick from `skills/shared/gate-prompts.md`):
+      question: "Include these {N} seeds in planning?"
+      header: "Seeds?"
+      options:
+        - label: "Yes, all"     description: "Include all {N} matching seeds"
+        - label: "Let me pick"  description: "Choose which seeds to include"
+        - label: "No"           description: "Proceed without seeds"
+    - If "Yes, all": include seed content in planner context
+    - If "Let me pick": present individual seeds for selection
+    - If "No": proceed without seeds
+  - If `gates.confirm_seeds` is `false` (default): automatically include all matching seeds in planner context without prompting. Log: "Including {N} seeds automatically (gates.confirm_seeds=false)."
+
+- If `## Deferred Ideas` section has items:
+  - If `gates.confirm_deferred` is `true` in config: present via AskUserQuestion (pattern: yes-no from `skills/shared/gate-prompts.md`):
+      question: "Include these deferred ideas in planning context?"
+    - If "Yes": append to planner context under `Deferred ideas to consider:`
+    - If "No": proceed without changes
+  - If `gates.confirm_deferred` is `false` (default): automatically append deferred ideas to planner context without prompting. Log: "Including deferred ideas automatically (gates.confirm_deferred=false)."
 
 - If both sections are empty: proceed silently to Step 5 (no AskUserQuestion needed)
 
@@ -554,10 +588,26 @@ Read `skills/plan/templates/gap-closure-prompt.md.tmpl` and use it as the prompt
 ## Error Handling
 
 ### Phase not found
-If the specified phase doesn't exist in ROADMAP.md, display a branded error box — see `skills/shared/error-reporting.md`, pattern: Phase not found.
+If the specified phase doesn't exist in ROADMAP.md, use conversational recovery:
+
+1. Run: `node ${PLUGIN_ROOT}/scripts/pbr-tools.js suggest-alternatives phase-not-found {slug}`
+2. Parse the JSON response to get `available` phases and `suggestions` (closest matches).
+3. Display: "Phase '{slug}' not found. Did you mean one of these?"
+   - List `suggestions` (if any) as numbered options.
+   - Offer "Show all phases" to list `available`.
+4. Use AskUserQuestion (pattern: yes-no-pick from `skills/shared/gate-prompts.md`) to let the user pick a phase or abort.
+   - If user picks a valid phase slug: re-run with that slug.
+   - If user chooses to abort: stop cleanly with a friendly message.
 
 ### Missing prerequisites
-If REQUIREMENTS.md or ROADMAP.md don't exist, display a branded error box — see `skills/shared/error-reporting.md`, pattern: Missing prerequisites.
+If REQUIREMENTS.md or ROADMAP.md don't exist, use conversational recovery:
+
+1. Run: `node ${PLUGIN_ROOT}/scripts/pbr-tools.js suggest-alternatives missing-prereq {phase}`
+2. Parse the JSON response to get `existing_summaries`, `missing_summaries`, and `suggested_action`.
+3. Display what is already complete and what is missing.
+4. Use AskUserQuestion to offer: "Run /pbr:build {prerequisite-phase} first, or continue anyway?"
+   - If user chooses to continue: proceed with planning (note missing prereqs in plan frontmatter).
+   - If user chooses to build first: stop and display the suggested build command.
 
 ### Research agent fails
 If the researcher Task() fails, display:

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

@@ -75,7 +75,18 @@ Execute these steps in order.
 5. If no phase number given, read current phase from `.planning/STATE.md`
 6. If `.planning/.auto-verify` signal file exists, read it and note the auto-verification was already queued. Delete the signal file after reading (one-shot, same pattern as auto-continue.js).
 
-**Validation errors — use branded error boxes:**
+**Validation errors:**
+
+If phase directory not found, use conversational recovery:
+
+1. Run: `node ${PLUGIN_ROOT}/scripts/pbr-tools.js suggest-alternatives phase-not-found {slug}`
+2. Parse the JSON response to get `available` phases and `suggestions` (closest matches).
+3. Display: "Phase '{slug}' not found. Did you mean one of these?"
+   - List `suggestions` (if any) as numbered options.
+   - Offer "Show all phases" to list `available`.
+4. Use AskUserQuestion (pattern: yes-no-pick from `skills/shared/gate-prompts.md`) to let the user pick a phase or abort.
+   - If user picks a valid phase slug: re-run with that slug.
+   - If user chooses to abort: stop cleanly with a friendly message.
 
 If no SUMMARY.md files:
 ```