@sienklogic/plan-build-run 2.18.1 → 2.20.0

package/CHANGELOG.md

@@ -5,6 +5,37 @@ 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.20.0](https://github.com/SienkLogic/plan-build-run/compare/plan-build-run-v2.19.0...plan-build-run-v2.20.0) (2026-02-23)
+
+
+### Features
+
+* **tools:** add worktree isolation, ConfigChange hook, and claude agents docs ([d704f34](https://github.com/SienkLogic/plan-build-run/commit/d704f340c636fa41f988d27a661a1e1918b04c87))
+
+## [2.19.0](https://github.com/SienkLogic/plan-build-run/compare/plan-build-run-v2.18.1...plan-build-run-v2.19.0) (2026-02-22)
+
+
+### Features
+
+* **dashboard:** add responsive mobile layout with sidebar hamburger menu ([5621739](https://github.com/SienkLogic/plan-build-run/commit/5621739b1b1b85bf5854bf52582908251fdeff13))
+* **tools:** add D10 test plan coverage dimension to plan-checker agent ([a4ff196](https://github.com/SienkLogic/plan-build-run/commit/a4ff19664c723861b262f9d6feccdd9e1ef95221))
+* **tools:** add PreToolUse additionalContext soft warnings for risky operations ([1d39406](https://github.com/SienkLogic/plan-build-run/commit/1d394066071959e4abafdcc1e84d472f05584018))
+* **tools:** add STATE.md backup step before health skill auto-fix regeneration ([43a52dd](https://github.com/SienkLogic/plan-build-run/commit/43a52dd36df9afc2f0aa3ddebfd588904b562bcd))
+* **tools:** require user confirmation before debugger agent applies fixes ([5446654](https://github.com/SienkLogic/plan-build-run/commit/544665487093210c6f6e412f7af79e02d33cf19a))
+* **tools:** use last_assistant_message in Stop/SubagentStop hooks ([ab73122](https://github.com/SienkLogic/plan-build-run/commit/ab731222549b6c251d93de123a3a2475b8d41a13))
+
+
+### Bug Fixes
+
+* **dashboard:** handle todo files with H1 title and high/medium/low priority ([9edb601](https://github.com/SienkLogic/plan-build-run/commit/9edb601bdeb974c3f1d47f612697516b67d5aa2e))
+* **dashboard:** show completed milestones on roadmap when all phases archived ([656ec04](https://github.com/SienkLogic/plan-build-run/commit/656ec04120931e5092ee608f23022276c5d79381))
+* **tools:** add commonjs package.json to scripts for ESM project compat ([8ca8780](https://github.com/SienkLogic/plan-build-run/commit/8ca878023ce90257ccb9fe0cdabe5a3040ece9e9))
+
+
+### Documentation
+
+* **tools:** document minimum Claude Code v2.1.47 requirement for Windows hooks ([2ecb231](https://github.com/SienkLogic/plan-build-run/commit/2ecb23172f154e1fe68460c087eb055deea1df94))
+
 ## [2.18.1](https://github.com/SienkLogic/plan-build-run/compare/plan-build-run-v2.18.0...plan-build-run-v2.18.1) (2026-02-22)
 
 

package/README.md

@@ -61,7 +61,7 @@ Works on every Claude Code plan. Use `depth: quick` on Free/Pro, `depth: standar
 
 ### Prerequisites
 
-- [Claude Code](https://docs.anthropic.com/en/docs/claude-code) 2.1.45+  (`claude --version`)
+- [Claude Code](https://docs.anthropic.com/en/docs/claude-code) 2.1.47+  (`claude --version`)
 - Node.js 18+
 
 ### Install

package/dashboard/public/css/layout.css

@@ -500,10 +500,25 @@ main > p:first-of-type > a[href="/"]:hover {
   font-size: 0.875rem;
 }
 
+/* --- Hero Stats Grid --- */
+.hero-stats {
+  display: grid;
+  grid-template-columns: repeat(4, 1fr);
+  gap: var(--space-md);
+}
+
 /* --- Stat Values --- */
 .stat-value { font-size: 2rem; font-weight: 700; line-height: 1.2; }
 .stat-unit { font-size: 0.875rem; color: var(--color-dim); margin-left: 0.25rem; }
 
+/* --- Quick Actions --- */
+.quick-actions {
+  display: flex;
+  flex-wrap: wrap;
+  gap: var(--space-sm);
+  margin-bottom: var(--space-lg);
+}
+
 /* --- Bar Chart --- */
 .bar-chart-row { display: flex; align-items: center; gap: var(--space-sm); margin-bottom: var(--space-xs); }
 .bar-chart-label { min-width: 160px; font-size: 0.875rem; white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }
@@ -531,6 +546,11 @@ main > p:first-of-type > a[href="/"]:hover {
   100% { transform: translateX(100%); }
 }
 
+/* --- Sidebar Backdrop (hidden by default, shown on mobile) --- */
+.sidebar-backdrop {
+  display: none;
+}
+
 /* --- Mobile hamburger toggle --- */
 .sidebar-toggle {
   display: none;
@@ -588,11 +608,12 @@ main > p:first-of-type > a[href="/"]:hover {
     border-bottom: none;
     padding: var(--space-lg) 0;
     overflow-y: auto;
-    background: var(--color-surface-raised);
+    background: var(--pico-background-color, #1a1a2e);
   }
 
   .page-wrapper > aside.sidebar.open {
     transform: translateX(0);
+    box-shadow: 4px 0 24px rgba(0, 0, 0, 0.3);
   }
 
   .sidebar-backdrop {
@@ -600,7 +621,7 @@ main > p:first-of-type > a[href="/"]:hover {
     position: fixed;
     inset: 0;
     top: var(--size-header);
-    background: rgba(0, 0, 0, 0.4);
+    background: rgba(0, 0, 0, 0.7);
     z-index: 19;
   }
 
@@ -615,9 +636,35 @@ main > p:first-of-type > a[href="/"]:hover {
   h1 { font-size: 1.4rem; }
   h2 { font-size: 1.15rem; }
 
+  /* Tables: ensure horizontal scroll on mobile */
   table {
     font-size: 0.8125rem;
   }
+
+  .table-wrap {
+    margin: 0 calc(-1 * var(--space-md));
+    padding: 0 var(--space-md);
+  }
+
+  /* Hero stat cards: 2-column grid on mobile */
+  .hero-stats {
+    grid-template-columns: repeat(2, 1fr);
+  }
+
+  .hero-stats .stat-value {
+    font-size: 1.5rem;
+  }
+
+  /* Bar chart: narrower labels */
+  .bar-chart-label {
+    min-width: 100px;
+    font-size: 0.75rem;
+  }
+
+  /* Filter form: compact on mobile */
+  .grid[style*="grid-template-columns: 1fr 1fr 2fr"] {
+    grid-template-columns: 1fr 1fr !important;
+  }
 }
 
 /* Small mobile */
@@ -633,4 +680,25 @@ main > p:first-of-type > a[href="/"]:hover {
   article > header {
     padding: var(--space-sm) var(--space-md);
   }
+
+  /* Stack hero stats to single column on very small screens */
+  .hero-stats {
+    grid-template-columns: 1fr;
+  }
+
+  /* Bar chart: even narrower labels */
+  .bar-chart-label {
+    min-width: 80px;
+    font-size: 0.7rem;
+  }
+
+  /* Quick action buttons: full width stack */
+  .quick-actions {
+    flex-direction: column;
+  }
+
+  .quick-actions a[role="button"] {
+    width: 100%;
+    text-align: center;
+  }
 }

package/dashboard/src/services/roadmap.service.js

@@ -94,15 +94,33 @@ function extractMilestones(roadmapContent) {
   // Parse explicit milestones: "## Milestone: Name\n\n**Goal:** ...\n**Phases:** N - M"
   const milestoneRegex = /## Milestone:\s*(.+)\n+\*\*Goal:?\*\*:?\s*(.+)\n\*\*Phases:?\*\*:?\s*(\d+)\s*-\s*(\d+)/g;
   const explicit = [];
+  const seenNames = new Set();
   for (const match of roadmapContent.matchAll(milestoneRegex)) {
+    const name = match[1].trim();
+    seenNames.add(name);
     explicit.push({
-      name: match[1].trim(),
+      name,
       goal: match[2].trim(),
       startPhase: parseInt(match[3], 10),
       endPhase: parseInt(match[4], 10)
     });
   }
 
+  // Parse completed/collapsed milestones: "## Milestone: Name -- COMPLETED\n\nPhases N-M completed..."
+  const completedRegex = /## Milestone:\s*(.+?)\s*--\s*COMPLETED\n+Phases\s+(\d+)-(\d+)\s+completed[^\n]*/g;
+  for (const match of roadmapContent.matchAll(completedRegex)) {
+    const name = match[1].trim();
+    if (seenNames.has(name)) continue; // avoid duplicates
+    seenNames.add(name);
+    explicit.push({
+      name: name + ' (Completed)',
+      goal: 'Completed',
+      startPhase: parseInt(match[2], 10),
+      endPhase: parseInt(match[3], 10),
+      completed: true
+    });
+  }
+
   // Sort explicit milestones by start phase
   explicit.sort((a, b) => a.startPhase - b.startPhase);
 
@@ -215,10 +233,6 @@ export async function generateDependencyMermaid(projectDir) {
 export async function getRoadmapData(projectDir) {
   const { phases: basePhases } = await parseRoadmapFile(projectDir);
 
-  if (basePhases.length === 0) {
-    return { phases: [], milestones: [] };
-  }
-
   // Read raw ROADMAP.md for dependencies and milestones
   let dependencyMap = new Map();
   let milestones = [];

package/dashboard/src/services/todo.service.js

@@ -3,7 +3,7 @@ import { join } from 'node:path';
 import matter from 'gray-matter';
 import { readMarkdownFile } from '../repositories/planning.repository.js';
 
-const PRIORITY_ORDER = { P0: 0, P1: 1, P2: 2, PX: 3 };
+const PRIORITY_ORDER = { P0: 0, P1: 1, P2: 2, PX: 3, high: 0, medium: 1, low: 2 };
 
 class WriteQueue {
   constructor() {
@@ -105,13 +105,22 @@ export async function listPendingTodos(projectDir, filters = {}) {
   for (let i = 0; i < results.length; i++) {
     if (results[i].status !== 'fulfilled') continue;
 
-    const { frontmatter } = results[i].value;
+    const { frontmatter, rawContent } = results[i].value;
     const { filename, fileId } = mdFiles[i];
 
-    // Skip todos missing required frontmatter fields
-    const title = frontmatter.title;
+    // Derive title: frontmatter > H1 heading in raw markdown > filename slug
+    let title = frontmatter.title;
+    if (!title && rawContent) {
+      const h1Match = rawContent.match(/^#\s+(.+)$/m);
+      if (h1Match) title = h1Match[1].trim();
+    }
+    if (!title) {
+      // Extract from filename: "003-some-slug.md" -> "Some slug"
+      const slugMatch = filename.match(/^\d{3}-(.+)\.md$/);
+      title = slugMatch ? slugMatch[1].replace(/-/g, ' ').replace(/^\w/, c => c.toUpperCase()) : 'Untitled';
+    }
     const priority = frontmatter.priority;
-    if (!title || !priority) continue;
+    if (!priority) continue;
 
     todos.push({
       id: frontmatter.id || fileId,

package/dashboard/src/views/partials/dashboard-content.ejs

@@ -2,7 +2,7 @@
 <h1><%= projectName %></h1>
 
 <!-- Hero Stat Row -->
-<div class="grid">
+<div class="hero-stats">
   <!-- Current Phase -->
   <article>
     <header><strong>Current Phase</strong></header>
@@ -54,7 +54,7 @@
 </div>
 
 <!-- Quick Actions -->
-<div>
+<div class="quick-actions">
   <% var phaseId = String(currentPhase.id).padStart(2, '0'); %>
   <a role="button" class="outline"
      href="/phases/<%= phaseId %>"

package/dashboard/src/views/partials/layout-bottom.ejs

@@ -2,5 +2,42 @@
     <%- include('footer') %>
   </div>
   <script src="/js/sse-client.js"></script>
+  <script>
+    (function() {
+      var sidebar = document.querySelector('.sidebar');
+      var backdrop = document.querySelector('.sidebar-backdrop');
+      var toggle = document.querySelector('.sidebar-toggle');
+
+      function openSidebar() {
+        sidebar.classList.add('open');
+        backdrop.classList.add('open');
+      }
+
+      function closeSidebar() {
+        sidebar.classList.remove('open');
+        backdrop.classList.remove('open');
+      }
+
+      // Expose for onclick handler on backdrop
+      window.closeSidebar = closeSidebar;
+
+      if (toggle) {
+        toggle.addEventListener('click', function() {
+          if (sidebar.classList.contains('open')) { closeSidebar(); } else { openSidebar(); }
+        });
+      }
+
+      if (backdrop) {
+        backdrop.addEventListener('click', closeSidebar);
+      }
+
+      // Auto-close sidebar on nav link click (mobile)
+      document.querySelectorAll('.sidebar nav a').forEach(function(link) {
+        link.addEventListener('click', function() {
+          if (window.innerWidth <= 768) closeSidebar();
+        });
+      });
+    })();
+  </script>
 </body>
 </html>

package/dashboard/src/views/partials/layout-top.ejs

@@ -11,5 +11,6 @@
   </script>
   <div class="page-wrapper">
     <%- include('header') %>
+    <div class="sidebar-backdrop" onclick="closeSidebar()"></div>
     <%- include('sidebar', { activePage: typeof activePage !== 'undefined' ? activePage : '' }) %>
     <main id="main-content">

package/dashboard/src/views/partials/roadmap-content.ejs

@@ -1,10 +1,35 @@
 <%- include('breadcrumbs', { breadcrumbs: typeof breadcrumbs !== 'undefined' ? breadcrumbs : [] }) %>
 <h1>Project Roadmap</h1>
 
-<% if (phases.length === 0) { %>
+<% if (phases.length === 0 && (typeof milestones === 'undefined' || milestones.length === 0)) { %>
 <article>
   <p>No phases found. Add a ROADMAP.md file to your .planning/ directory to see the roadmap here.</p>
 </article>
+<% } else if (phases.length === 0 && typeof milestones !== 'undefined' && milestones.length > 0) { %>
+<!-- All milestones completed — show summary -->
+<article>
+  <header><strong>All Milestones Completed</strong></header>
+  <p>All phases have been archived into milestones.</p>
+</article>
+<% milestones.forEach(function(ms) { %>
+<article>
+  <header>
+    <strong><%= ms.name %></strong>
+    <% if (ms.startPhase && ms.endPhase) { %>
+      <small>(Phases <%= String(ms.startPhase).padStart(2, '0') %>&ndash;<%= String(ms.endPhase).padStart(2, '0') %>)</small>
+    <% } %>
+    &mdash;
+    <span class="status-badge" data-status="complete">complete</span>
+  </header>
+  <% if (ms.goal && ms.goal !== 'Completed') { %>
+    <p><small><%= ms.goal %></small></p>
+  <% } %>
+  <p><a href="/milestones"
+        hx-get="/milestones"
+        hx-target="#main-content"
+        hx-push-url="true">View in Milestones</a></p>
+</article>
+<% }); %>
 <% } else { %>
 
 <%

package/dashboard/src/views/partials/todos-content.ejs

@@ -14,6 +14,9 @@
         Priority
         <select name="priority" onchange="this.form.requestSubmit()">
           <option value="">All</option>
+          <option value="high"<%= f.priority === 'high' ? ' selected' : '' %>>High</option>
+          <option value="medium"<%= f.priority === 'medium' ? ' selected' : '' %>>Medium</option>
+          <option value="low"<%= f.priority === 'low' ? ' selected' : '' %>>Low</option>
           <option value="P0"<%= f.priority === 'P0' ? ' selected' : '' %>>P0</option>
           <option value="P1"<%= f.priority === 'P1' ? ' selected' : '' %>>P1</option>
           <option value="P2"<%= f.priority === 'P2' ? ' selected' : '' %>>P2</option>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sienklogic/plan-build-run",
-  "version": "2.18.1",
+  "version": "2.20.0",
   "description": "Plan it, Build it, Run it — structured development workflow for Claude Code",
   "keywords": [
     "claude-code",

package/plugins/copilot-pbr/agents/debugger.agent.md

@@ -119,7 +119,16 @@ When you need human input, emit a checkpoint block. Always include `Debug file:`
 
 **CRITICAL — DO NOT SKIP steps 5-8. Uncommitted fixes and unupdated debug files cause state corruption on resume.**
 
-**Steps**: Verify root cause → plan minimal fix → predict outcome → implement → verify → check regressions → commit → update debug file.
+**CRITICAL — NEVER apply fixes without user approval.** After identifying the root cause and planning the fix, you MUST present your findings and proposed changes to the user, then wait for explicit confirmation before writing any code. Set debug status to `self-verified` while awaiting approval. Only proceed to `fixing` after the user approves.
+
+Present to the user:
+1. Root cause and mechanism
+2. Proposed fix (files to change, what changes)
+3. Predicted outcome and risk assessment
+
+Then emit a `DECISION` checkpoint asking the user to approve, modify, or reject the fix.
+
+**Steps**: Verify root cause → plan minimal fix → predict outcome → **present to user and wait for approval** → implement → verify → check regressions → commit → update debug file.
 
 **Guidelines**: Minimal change (root cause, not symptoms). One atomic commit. No refactoring or features. Test the fix.
 
@@ -156,6 +165,7 @@ Reference: `references/common-bug-patterns.md` — covers off-by-one, null/undef
 6. DO NOT assume first hypothesis is correct or fight contradicting evidence
 7. DO NOT spend too long on one hypothesis — if inconclusive, move on
 8. DO NOT trust error messages at face value — may be a deeper symptom
+9. DO NOT apply fixes without explicit user approval — present findings first, wait for confirmation
 
 ## Context Budget
 

package/plugins/copilot-pbr/agents/plan-checker.agent.md

@@ -1,6 +1,6 @@
 ---
 name: plan-checker
-description: "Verifies plans will achieve phase goals before execution. Goal-backward analysis of plan quality across 9 dimensions."
+description: "Verifies plans will achieve phase goals before execution. Goal-backward analysis of plan quality across 10 dimensions."
 tools: ["read", "search"]
 infer: true
 target: "github-copilot"
@@ -31,7 +31,7 @@ You receive: (1) plan files to check, (2) phase goal or directory path, (3) opti
 
 ---
 
-## The 9 Verification Dimensions
+## The 10 Verification Dimensions
 
 ### D1: Requirement Coverage
 Plan tasks must cover all must-haves from frontmatter (`truths`, `artifacts`, `key_links`). Each must-have needs at least one task's `<done>` mapping.
@@ -127,6 +127,15 @@ Plans declare `requirement_ids` with bidirectional coverage. Forward: IDs trace
 | ROADMAP goal not covered (no REQUIREMENTS.md) | WARNING |
 | Plan missing requirement_ids entirely | INFO |
 
+### D10: Test Plan Coverage
+Code-producing tasks should include test expectations. Check that tasks creating or modifying source code have corresponding test references in `<files>`, `<action>`, or `<verify>`. Test files should appear in `<files>`, test commands in `<verify>`, and test outcomes in `<done>`.
+
+| Condition | Severity |
+|-----------|----------|
+| Code task with no test file in `<files>` and no test command in `<verify>` | WARNING |
+| Task creates new module but no corresponding test file planned | WARNING |
+| `<verify>` uses only file-existence checks, no test runner | INFO |
+
 ---
 
 ## Verification Process
@@ -134,7 +143,7 @@ Plans declare `requirement_ids` with bidirectional coverage. Forward: IDs trace
 1. **Load Plans** — Read all plan files. Parse YAML frontmatter and XML tasks. Use `node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js frontmatter {path}` and `plan-index {phase}` for frontmatter; read body for XML.
 2. **Load Context** — If CONTEXT.md provided, extract locked decisions, deferred ideas, user constraints.
 3. **Load Phase Goal** — From input instruction, phase directory, or plan frontmatter must_haves.
-4. **Run All 9 Dimensions** — Evaluate each plan against all dimensions. Collect issues.
+4. **Run All 10 Dimensions** — Evaluate each plan against all dimensions. Collect issues.
 5. **Cross-Plan Checks** — File conflicts between same-wave plans, circular cross-plan deps, phase goal coverage, duplicate task content.
 6. **Compile Report** — Produce output in format below.
 
@@ -144,7 +153,7 @@ Plans declare `requirement_ids` with bidirectional coverage. Forward: IDs trace
 
 ```
 VERIFICATION PASSED
-Plans: {count} | Tasks: {count} | Dimensions: 9 | Issues: 0
+Plans: {count} | Tasks: {count} | Dimensions: 10 | Issues: 0
 ```
 
 Or when issues found:
@@ -170,7 +179,7 @@ Plans: {count} | Tasks: {count} | Blockers: {count} | Warnings: {count} | Info:
 - **Single-task plan**: WARNING on D5. May be too coarse; consider splitting.
 - **No CONTEXT.md**: Skip D7. Note "D7 skipped: no CONTEXT.md found".
 - **Checkpoint tasks**: `human-verify` → verify describes what to look at. `decision` → lists options. `human-action` → describes action.
-- **TDD tasks**: WARNING if verify lacks a test command.
+- **TDD tasks**: See D10. WARNING if verify lacks a test command.
 
 ---
 
@@ -193,7 +202,7 @@ Plans: {count} | Tasks: {count} | Blockers: {count} | Warnings: {count} | Info:
 2. DO NOT suggest alternative architectures — focus on plan quality
 3. DO NOT invent requirements not in the phase goal or must-haves
 4. DO NOT be lenient on blockers — if it's a blocker, flag it
-5. DO NOT nitpick working plans — if all 9 dimensions pass, say PASSED
+5. DO NOT nitpick working plans — if all 10 dimensions pass, say PASSED
 6. DO NOT check code quality — you check PLAN quality
 7. DO NOT verify that technologies are correct — that's the researcher's job
 8. DO NOT evaluate the phase goal itself — only whether the plan achieves it

package/plugins/copilot-pbr/hooks/hooks.json

@@ -139,6 +139,19 @@
         ]
       }
     ],
+    "configChange": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "bash": "node \"$(cd \"$(dirname \"$0\")\" && pwd)/../../pbr/scripts/run-hook.js\" check-config-change.js",
+            "powershell": "node (Join-Path (Split-Path -Parent $PSScriptRoot) 'pbr\\scripts\\run-hook.js') check-config-change.js",
+            "cwd": ".",
+            "timeoutSec": 15
+          }
+        ]
+      }
+    ],
     "sessionEnd": [
       {
         "hooks": [

package/plugins/copilot-pbr/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "pbr",
   "displayName": "Plan-Build-Run",
-  "version": "2.18.1",
+  "version": "2.20.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/references/agent-contracts.md

@@ -117,7 +117,7 @@ requirement_ids: []
 
 ### Expected Input
 
-Plan-Checker reads plan frontmatter + XML tasks and evaluates across 9 dimensions (D1-D9). Optionally receives CONTEXT.md path.
+Plan-Checker reads plan frontmatter + XML tasks and evaluates across 10 dimensions (D1-D10). Optionally receives CONTEXT.md path.
 
 ### Output Format
 

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

@@ -168,6 +168,15 @@ After running all 10 checks and collecting results, if any of the following auto
 
 After displaying health check results, if any auto-fixable issues were detected:
 
+**CRITICAL — Before ANY auto-fix that modifies or regenerates STATE.md (frontmatter regeneration, phase_slug correction, or line compaction), you MUST create a timestamped backup first. DO NOT SKIP THIS STEP.**
+
+```
+mkdir -p .planning/backups
+cp .planning/STATE.md .planning/backups/STATE-$(date +%Y%m%dT%H%M%S).md
+```
+
+This ensures the user can recover the original STATE.md if the fix produces incorrect results.
+
 1. Count the auto-fixable issues and present:
 
    Use AskUserQuestion:

package/plugins/cursor-pbr/.cursor-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "pbr",
   "displayName": "Plan-Build-Run",
-  "version": "2.18.1",
+  "version": "2.20.0",
   "description": "Plan-Build-Run — Structured development workflow for Cursor. Solves context rot through disciplined subagent delegation, structured planning, atomic execution, and goal-backward verification.",
   "author": {
     "name": "SienkLogic",

package/plugins/cursor-pbr/agents/debugger.md

@@ -118,7 +118,16 @@ When you need human input, emit a checkpoint block. Always include `Debug file:`
 
 **CRITICAL — DO NOT SKIP steps 5-8. Uncommitted fixes and unupdated debug files cause state corruption on resume.**
 
-**Steps**: Verify root cause → plan minimal fix → predict outcome → implement → verify → check regressions → commit → update debug file.
+**CRITICAL — NEVER apply fixes without user approval.** After identifying the root cause and planning the fix, you MUST present your findings and proposed changes to the user, then wait for explicit confirmation before writing any code. Set debug status to `self-verified` while awaiting approval. Only proceed to `fixing` after the user approves.
+
+Present to the user:
+1. Root cause and mechanism
+2. Proposed fix (files to change, what changes)
+3. Predicted outcome and risk assessment
+
+Then emit a `DECISION` checkpoint asking the user to approve, modify, or reject the fix.
+
+**Steps**: Verify root cause → plan minimal fix → predict outcome → **present to user and wait for approval** → implement → verify → check regressions → commit → update debug file.
 
 **Guidelines**: Minimal change (root cause, not symptoms). One atomic commit. No refactoring or features. Test the fix.
 
@@ -155,6 +164,7 @@ Reference: `references/common-bug-patterns.md` — covers off-by-one, null/undef
 6. DO NOT assume first hypothesis is correct or fight contradicting evidence
 7. DO NOT spend too long on one hypothesis — if inconclusive, move on
 8. DO NOT trust error messages at face value — may be a deeper symptom
+9. DO NOT apply fixes without explicit user approval — present findings first, wait for confirmation
 
 ## Context Budget
 

package/plugins/cursor-pbr/agents/plan-checker.md

@@ -1,6 +1,6 @@
 ---
 name: plan-checker
-description: "Verifies plans will achieve phase goals before execution. Goal-backward analysis of plan quality across 9 dimensions."
+description: "Verifies plans will achieve phase goals before execution. Goal-backward analysis of plan quality across 10 dimensions."
 model: sonnet
 readonly: true
 ---
@@ -30,7 +30,7 @@ You receive: (1) plan files to check, (2) phase goal or directory path, (3) opti
 
 ---
 
-## The 9 Verification Dimensions
+## The 10 Verification Dimensions
 
 ### D1: Requirement Coverage
 Plan tasks must cover all must-haves from frontmatter (`truths`, `artifacts`, `key_links`). Each must-have needs at least one task's `<done>` mapping.
@@ -126,6 +126,15 @@ Plans declare `requirement_ids` with bidirectional coverage. Forward: IDs trace
 | ROADMAP goal not covered (no REQUIREMENTS.md) | WARNING |
 | Plan missing requirement_ids entirely | INFO |
 
+### D10: Test Plan Coverage
+Code-producing tasks should include test expectations. Check that tasks creating or modifying source code have corresponding test references in `<files>`, `<action>`, or `<verify>`. Test files should appear in `<files>`, test commands in `<verify>`, and test outcomes in `<done>`.
+
+| Condition | Severity |
+|-----------|----------|
+| Code task with no test file in `<files>` and no test command in `<verify>` | WARNING |
+| Task creates new module but no corresponding test file planned | WARNING |
+| `<verify>` uses only file-existence checks, no test runner | INFO |
+
 ---
 
 ## Verification Process
@@ -133,7 +142,7 @@ Plans declare `requirement_ids` with bidirectional coverage. Forward: IDs trace
 1. **Load Plans** — Read all plan files. Parse YAML frontmatter and XML tasks. Use `node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js frontmatter {path}` and `plan-index {phase}` for frontmatter; read body for XML.
 2. **Load Context** — If CONTEXT.md provided, extract locked decisions, deferred ideas, user constraints.
 3. **Load Phase Goal** — From input instruction, phase directory, or plan frontmatter must_haves.
-4. **Run All 9 Dimensions** — Evaluate each plan against all dimensions. Collect issues.
+4. **Run All 10 Dimensions** — Evaluate each plan against all dimensions. Collect issues.
 5. **Cross-Plan Checks** — File conflicts between same-wave plans, circular cross-plan deps, phase goal coverage, duplicate task content.
 6. **Compile Report** — Produce output in format below.
 
@@ -143,7 +152,7 @@ Plans declare `requirement_ids` with bidirectional coverage. Forward: IDs trace
 
 ```
 VERIFICATION PASSED
-Plans: {count} | Tasks: {count} | Dimensions: 9 | Issues: 0
+Plans: {count} | Tasks: {count} | Dimensions: 10 | Issues: 0
 ```
 
 Or when issues found:
@@ -169,7 +178,7 @@ Plans: {count} | Tasks: {count} | Blockers: {count} | Warnings: {count} | Info:
 - **Single-task plan**: WARNING on D5. May be too coarse; consider splitting.
 - **No CONTEXT.md**: Skip D7. Note "D7 skipped: no CONTEXT.md found".
 - **Checkpoint tasks**: `human-verify` → verify describes what to look at. `decision` → lists options. `human-action` → describes action.
-- **TDD tasks**: WARNING if verify lacks a test command.
+- **TDD tasks**: See D10. WARNING if verify lacks a test command.
 
 ---
 
@@ -192,7 +201,7 @@ Plans: {count} | Tasks: {count} | Blockers: {count} | Warnings: {count} | Info:
 2. DO NOT suggest alternative architectures — focus on plan quality
 3. DO NOT invent requirements not in the phase goal or must-haves
 4. DO NOT be lenient on blockers — if it's a blocker, flag it
-5. DO NOT nitpick working plans — if all 9 dimensions pass, say PASSED
+5. DO NOT nitpick working plans — if all 10 dimensions pass, say PASSED
 6. DO NOT check code quality — you check PLAN quality
 7. DO NOT verify that technologies are correct — that's the researcher's job
 8. DO NOT evaluate the phase goal itself — only whether the plan achieves it

package/plugins/cursor-pbr/hooks/hooks.json

@@ -196,6 +196,17 @@
         ]
       }
     ],
+    "ConfigChange": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node -e \"var r=process.env.CLAUDE_PLUGIN_ROOT||'',m=r.match(/^\\/([a-zA-Z])\\/(.*)/);if(m)r=m[1]+String.fromCharCode(58)+String.fromCharCode(92)+m[2];require(require('path').resolve(r,'..','pbr','scripts','run-hook.js'))\" check-config-change.js",
+            "statusMessage": "Validating configuration..."
+          }
+        ]
+      }
+    ],
     "SessionEnd": [
       {
         "hooks": [

package/plugins/cursor-pbr/references/agent-contracts.md

@@ -117,7 +117,7 @@ requirement_ids: []
 
 ### Expected Input
 
-Plan-Checker reads plan frontmatter + XML tasks and evaluates across 9 dimensions (D1-D9). Optionally receives CONTEXT.md path.
+Plan-Checker reads plan frontmatter + XML tasks and evaluates across 10 dimensions (D1-D10). Optionally receives CONTEXT.md path.
 
 ### Output Format
 

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

@@ -168,6 +168,15 @@ After running all 10 checks and collecting results, if any of the following auto
 
 After displaying health check results, if any auto-fixable issues were detected:
 
+**CRITICAL — Before ANY auto-fix that modifies or regenerates STATE.md (frontmatter regeneration, phase_slug correction, or line compaction), you MUST create a timestamped backup first. DO NOT SKIP THIS STEP.**
+
+```
+mkdir -p .planning/backups
+cp .planning/STATE.md .planning/backups/STATE-$(date +%Y%m%dT%H%M%S).md
+```
+
+This ensures the user can recover the original STATE.md if the fix produces incorrect results.
+
 1. Count the auto-fixable issues and present:
 
    Use AskUserQuestion:

package/plugins/pbr/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "pbr",
-  "version": "2.18.1",
+  "version": "2.20.0",
   "description": "Plan-Build-Run — Structured development workflow for Claude Code. Solves context rot through disciplined subagent delegation, structured planning, atomic execution, and goal-backward verification.",
   "author": {
     "name": "SienkLogic",

package/plugins/pbr/agents/debugger.md

@@ -125,7 +125,16 @@ When you need human input, emit a checkpoint block. Always include `Debug file:`
 
 **CRITICAL — DO NOT SKIP steps 5-8. Uncommitted fixes and unupdated debug files cause state corruption on resume.**
 
-**Steps**: Verify root cause → plan minimal fix → predict outcome → implement → verify → check regressions → commit → update debug file.
+**CRITICAL — NEVER apply fixes without user approval.** After identifying the root cause and planning the fix, you MUST present your findings and proposed changes to the user, then wait for explicit confirmation before writing any code. Set debug status to `self-verified` while awaiting approval. Only proceed to `fixing` after the user approves.
+
+Present to the user:
+1. Root cause and mechanism
+2. Proposed fix (files to change, what changes)
+3. Predicted outcome and risk assessment
+
+Then emit a `DECISION` checkpoint asking the user to approve, modify, or reject the fix.
+
+**Steps**: Verify root cause → plan minimal fix → predict outcome → **present to user and wait for approval** → implement → verify → check regressions → commit → update debug file.
 
 **Guidelines**: Minimal change (root cause, not symptoms). One atomic commit. No refactoring or features. Test the fix.
 
@@ -162,6 +171,7 @@ Reference: `references/common-bug-patterns.md` — covers off-by-one, null/undef
 6. DO NOT assume first hypothesis is correct or fight contradicting evidence
 7. DO NOT spend too long on one hypothesis — if inconclusive, move on
 8. DO NOT trust error messages at face value — may be a deeper symptom
+9. DO NOT apply fixes without explicit user approval — present findings first, wait for confirmation
 
 ## Context Budget
 

package/plugins/pbr/agents/plan-checker.md

@@ -1,8 +1,9 @@
 ---
 name: plan-checker
-description: "Verifies plans will achieve phase goals before execution. Goal-backward analysis of plan quality across 9 dimensions."
+description: "Verifies plans will achieve phase goals before execution. Goal-backward analysis of plan quality across 10 dimensions."
 model: sonnet
 memory: none
+isolation: worktree
 tools:
   - Read
   - Bash
@@ -35,7 +36,7 @@ You receive: (1) plan files to check, (2) phase goal or directory path, (3) opti
 
 ---
 
-## The 9 Verification Dimensions
+## The 10 Verification Dimensions
 
 ### D1: Requirement Coverage
 Plan tasks must cover all must-haves from frontmatter (`truths`, `artifacts`, `key_links`). Each must-have needs at least one task's `<done>` mapping.
@@ -131,6 +132,15 @@ Plans declare `requirement_ids` with bidirectional coverage. Forward: IDs trace
 | ROADMAP goal not covered (no REQUIREMENTS.md) | WARNING |
 | Plan missing requirement_ids entirely | INFO |
 
+### D10: Test Plan Coverage
+Code-producing tasks should include test expectations. Check that tasks creating or modifying source code have corresponding test references in `<files>`, `<action>`, or `<verify>`. Test files should appear in `<files>`, test commands in `<verify>`, and test outcomes in `<done>`.
+
+| Condition | Severity |
+|-----------|----------|
+| Code task with no test file in `<files>` and no test command in `<verify>` | WARNING |
+| Task creates new module but no corresponding test file planned | WARNING |
+| `<verify>` uses only file-existence checks, no test runner | INFO |
+
 ---
 
 ## Verification Process
@@ -138,7 +148,7 @@ Plans declare `requirement_ids` with bidirectional coverage. Forward: IDs trace
 1. **Load Plans** — Read all plan files. Parse YAML frontmatter and XML tasks. Use `node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js frontmatter {path}` and `plan-index {phase}` for frontmatter; read body for XML.
 2. **Load Context** — If CONTEXT.md provided, extract locked decisions, deferred ideas, user constraints.
 3. **Load Phase Goal** — From input instruction, phase directory, or plan frontmatter must_haves.
-4. **Run All 9 Dimensions** — Evaluate each plan against all dimensions. Collect issues.
+4. **Run All 10 Dimensions** — Evaluate each plan against all dimensions. Collect issues.
 5. **Cross-Plan Checks** — File conflicts between same-wave plans, circular cross-plan deps, phase goal coverage, duplicate task content.
 6. **Compile Report** — Produce output in format below.
 
@@ -148,7 +158,7 @@ Plans declare `requirement_ids` with bidirectional coverage. Forward: IDs trace
 
 ```
 VERIFICATION PASSED
-Plans: {count} | Tasks: {count} | Dimensions: 9 | Issues: 0
+Plans: {count} | Tasks: {count} | Dimensions: 10 | Issues: 0
 ```
 
 Or when issues found:
@@ -174,7 +184,7 @@ Plans: {count} | Tasks: {count} | Blockers: {count} | Warnings: {count} | Info:
 - **Single-task plan**: WARNING on D5. May be too coarse; consider splitting.
 - **No CONTEXT.md**: Skip D7. Note "D7 skipped: no CONTEXT.md found".
 - **Checkpoint tasks**: `human-verify` → verify describes what to look at. `decision` → lists options. `human-action` → describes action.
-- **TDD tasks**: WARNING if verify lacks a test command.
+- **TDD tasks**: See D10. WARNING if verify lacks a test command.
 
 ---
 
@@ -197,7 +207,7 @@ Plans: {count} | Tasks: {count} | Blockers: {count} | Warnings: {count} | Info:
 2. DO NOT suggest alternative architectures — focus on plan quality
 3. DO NOT invent requirements not in the phase goal or must-haves
 4. DO NOT be lenient on blockers — if it's a blocker, flag it
-5. DO NOT nitpick working plans — if all 9 dimensions pass, say PASSED
+5. DO NOT nitpick working plans — if all 10 dimensions pass, say PASSED
 6. DO NOT check code quality — you check PLAN quality
 7. DO NOT verify that technologies are correct — that's the researcher's job
 8. DO NOT evaluate the phase goal itself — only whether the plan achieves it

package/plugins/pbr/agents/verifier.md

@@ -3,6 +3,7 @@ name: verifier
 description: "Goal-backward phase verification. Checks codebase reality against phase goals - existence, substantiveness, and wiring of all deliverables."
 model: sonnet
 memory: none
+isolation: worktree
 tools:
   - Read
   - Bash

package/plugins/pbr/hooks/hooks.json

@@ -192,6 +192,17 @@
         ]
       }
     ],
+    "ConfigChange": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node -e \"var r=process.env.CLAUDE_PLUGIN_ROOT||'',m=r.match(/^\\/([a-zA-Z])\\/(.*)/);if(m)r=m[1]+String.fromCharCode(58)+String.fromCharCode(92)+m[2];require(require('path').resolve(r,'scripts','run-hook.js'))\" check-config-change.js",
+            "statusMessage": "Validating configuration..."
+          }
+        ]
+      }
+    ],
     "SessionEnd": [
       {
         "hooks": [

package/plugins/pbr/references/agent-contracts.md

@@ -117,7 +117,7 @@ requirement_ids: []
 
 ### Expected Input
 
-Plan-Checker reads plan frontmatter + XML tasks and evaluates across 9 dimensions (D1-D9). Optionally receives CONTEXT.md path.
+Plan-Checker reads plan frontmatter + XML tasks and evaluates across 10 dimensions (D1-D10). Optionally receives CONTEXT.md path.
 
 ### Output Format
 

package/plugins/pbr/scripts/auto-continue.js

@@ -91,13 +91,19 @@ function main() {
       process.exit(0);
     }
 
-    logHook('auto-continue', 'Stop', 'continue', { next: nextCommand });
+    // Extract last_assistant_message for richer continuation context
+    const lastMsg = hookInput.last_assistant_message || '';
+    const msgSuffix = lastMsg
+      ? ` (last message excerpt: ${lastMsg.slice(0, 200)})`
+      : '';
+
+    logHook('auto-continue', 'Stop', 'continue', { next: nextCommand, hasLastMsg: !!lastMsg });
 
     // Block the stop and inject the next command as Claude's continuation reason.
     // Claude Code Stop hooks use { decision: "block", reason: "..." } to keep going.
     const output = {
       decision: 'block',
-      reason: `Auto-continue: execute ${nextCommand}`
+      reason: `Auto-continue: execute ${nextCommand}${msgSuffix}`
     };
     process.stdout.write(JSON.stringify(output));
     process.exit(0);

package/plugins/pbr/scripts/check-config-change.js

@@ -0,0 +1,130 @@
+#!/usr/bin/env node
+
+/**
+ * ConfigChange hook: Validates config.json changes and warns about inconsistencies.
+ *
+ * Fires when Claude Code detects configuration file changes (v2.1.49+).
+ * Checks .planning/config.json for:
+ *   - Required top-level keys
+ *   - Semantic conflicts (e.g., parallel agents enabled with max=1)
+ *   - Version field presence
+ *
+ * Exit codes:
+ *   0 = always (advisory hook, never blocks)
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { logHook } = require('./hook-logger');
+const { logEvent } = require('./event-logger');
+
+function readStdin() {
+  return new Promise((resolve) => {
+    let input = '';
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', (chunk) => { input += chunk; });
+    process.stdin.on('end', () => {
+      try {
+        resolve(JSON.parse(input));
+      } catch (_e) {
+        resolve({});
+      }
+    });
+  });
+}
+
+function findPlanningDir() {
+  let dir = process.cwd();
+  const root = path.parse(dir).root;
+  while (dir !== root) {
+    const candidate = path.join(dir, '.planning');
+    if (fs.existsSync(candidate)) return candidate;
+    dir = path.dirname(dir);
+  }
+  return null;
+}
+
+function validateConfig(configPath) {
+  const warnings = [];
+
+  let config;
+  try {
+    const raw = fs.readFileSync(configPath, 'utf8');
+    config = JSON.parse(raw);
+  } catch (e) {
+    warnings.push(`config.json parse error: ${e.message}`);
+    return warnings;
+  }
+
+  // Check required top-level keys
+  const requiredKeys = ['version', 'features', 'models', 'gates'];
+  for (const key of requiredKeys) {
+    if (!(key in config)) {
+      warnings.push(`Missing required key: ${key}`);
+    }
+  }
+
+  // Check version
+  if (config.version && config.version < 2) {
+    warnings.push(`Config version ${config.version} is outdated — expected version 2+`);
+  }
+
+  // Check semantic conflicts
+  if (config.parallelization) {
+    const p = config.parallelization;
+    if (p.enabled && p.max_concurrent_agents === 1) {
+      warnings.push('Semantic conflict: parallelization.enabled=true but max_concurrent_agents=1');
+    }
+    if (!p.enabled && (p.plan_level || p.task_level)) {
+      warnings.push('Semantic conflict: parallelization.enabled=false but plan_level/task_level are true');
+    }
+  }
+
+  // Check model values
+  if (config.models) {
+    const validModels = ['sonnet', 'opus', 'haiku', 'inherit'];
+    for (const [role, model] of Object.entries(config.models)) {
+      if (!validModels.includes(model)) {
+        warnings.push(`Invalid model "${model}" for ${role} — expected: ${validModels.join(', ')}`);
+      }
+    }
+  }
+
+  return warnings;
+}
+
+async function main() {
+  await readStdin();
+  const startTime = Date.now();
+
+  const planningDir = findPlanningDir();
+  if (!planningDir) {
+    logHook('check-config-change', 'ConfigChange', 'skip', { reason: 'no .planning dir' }, startTime);
+    process.exit(0);
+  }
+
+  const configPath = path.join(planningDir, 'config.json');
+  if (!fs.existsSync(configPath)) {
+    logHook('check-config-change', 'ConfigChange', 'skip', { reason: 'no config.json' }, startTime);
+    process.exit(0);
+  }
+
+  const warnings = validateConfig(configPath);
+
+  if (warnings.length > 0) {
+    const msg = `⚠️ Config validation (${warnings.length} issue${warnings.length > 1 ? 's' : ''}):\n${warnings.map(w => `  - ${w}`).join('\n')}`;
+
+    logHook('check-config-change', 'ConfigChange', 'warn', { warnings }, startTime);
+    logEvent('workflow', 'config-change', { warnings });
+
+    process.stdout.write(JSON.stringify({ additionalContext: msg }));
+  } else {
+    logHook('check-config-change', 'ConfigChange', 'ok', {}, startTime);
+    logEvent('workflow', 'config-change', { status: 'valid' });
+  }
+
+  process.exit(0);
+}
+
+if (require.main === module || process.argv[1] === __filename) main();
+module.exports = { validateConfig, findPlanningDir };

package/plugins/pbr/scripts/event-handler.js

@@ -140,8 +140,19 @@ function main() {
 
   writeAutoVerifySignal(planningDir, stateInfo.phase);
 
+  // Extract last_assistant_message for verification context hints
+  const lastMsg = data.last_assistant_message || '';
+  let verifyHint = '';
+  if (lastMsg) {
+    // Look for error/failure indicators that might inform verification priority
+    const lowerMsg = lastMsg.toLowerCase();
+    if (lowerMsg.includes('error') || lowerMsg.includes('failed') || lowerMsg.includes('warning')) {
+      verifyHint = ' Note: executor output mentions errors/warnings — verification should pay close attention.';
+    }
+  }
+
   const output = {
-    additionalContext: `Executor complete. Auto-verification queued for Phase ${stateInfo.phase}.`
+    additionalContext: `Executor complete. Auto-verification queued for Phase ${stateInfo.phase}.${verifyHint}`
   };
   process.stdout.write(JSON.stringify(output));
   process.exit(0);

package/plugins/pbr/scripts/hooks-schema.json

@@ -18,6 +18,7 @@
         "SubagentStart": { "$ref": "#/definitions/hookEntryList" },
         "SubagentStop": { "$ref": "#/definitions/hookEntryList" },
         "TaskCompleted": { "$ref": "#/definitions/hookEntryList" },
+        "ConfigChange": { "$ref": "#/definitions/hookEntryList" },
         "SessionEnd": { "$ref": "#/definitions/hookEntryList" }
       },
       "additionalProperties": false

package/plugins/pbr/scripts/package.json

@@ -0,0 +1 @@
+{"type": "commonjs"}

package/plugins/pbr/scripts/pre-bash-dispatch.js

@@ -75,6 +75,36 @@ function main() {
         process.exit(commitResult.exitCode);
       }
 
+      // Soft warnings for risky-but-allowed commands
+      const command = data.tool_input?.command || '';
+      if (command) {
+        const warnings = [];
+
+        // Warn about npm publish / deploy commands
+        if (/\bnpm\s+publish\b/.test(command)) {
+          warnings.push('npm publish detected — ensure version is correct before publishing');
+        }
+
+        // Warn about touching production config files
+        if (/\b(production|prod)\b.*\.(json|ya?ml|env|conf|cfg)\b/i.test(command) ||
+            /\.(json|ya?ml|env|conf|cfg)\b.*\b(production|prod)\b/i.test(command)) {
+          warnings.push('command references production config files');
+        }
+
+        // Warn about database operations
+        if (/\b(DROP|TRUNCATE|DELETE\s+FROM|ALTER\s+TABLE)\b/i.test(command)) {
+          warnings.push('destructive database operation detected — verify target');
+        }
+
+        if (warnings.length > 0) {
+          process.stdout.write(JSON.stringify({
+            decision: 'allow',
+            additionalContext: `[pbr] Advisory: ${warnings.join('; ')}.`
+          }));
+          process.exit(0);
+        }
+      }
+
       process.exit(0);
     } catch (_e) {
       // Don't block on errors

package/plugins/pbr/scripts/pre-write-dispatch.js

@@ -99,6 +99,33 @@ function main() {
         process.exit(sprawlResult.exitCode || 0);
       }
 
+      // Soft warning: writing outside current phase directory
+      // (only when all hard checks passed and we're in a phase)
+      const filePath = data.tool_input?.file_path || data.tool_input?.path || '';
+      if (filePath) {
+        const normalized = filePath.replace(/\\/g, '/');
+        // Warn about writes to other phase directories (not blocked, just advisory)
+        const phaseMatch = normalized.match(/\.planning\/phases\/(\d+)-/);
+        if (phaseMatch) {
+          const fs = require('fs');
+          const path = require('path');
+          const statePath = path.join(process.cwd(), '.planning', 'STATE.md');
+          try {
+            const stateContent = fs.readFileSync(statePath, 'utf8');
+            const currentPhase = stateContent.match(/Phase:\s*(\d+)\s+of/);
+            if (currentPhase && parseInt(phaseMatch[1], 10) !== parseInt(currentPhase[1], 10)) {
+              process.stdout.write(JSON.stringify({
+                decision: 'allow',
+                additionalContext: `[pbr] Advisory: writing to phase ${phaseMatch[1]} but current phase is ${currentPhase[1]}. Ensure this cross-phase write is intentional.`
+              }));
+              process.exit(0);
+            }
+          } catch (_e) {
+            // No STATE.md — skip warning
+          }
+        }
+      }
+
       process.exit(0);
     } catch (_e) {
       // Don't block on errors

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

@@ -171,6 +171,15 @@ After running all 10 checks and collecting results, if any of the following auto
 
 After displaying health check results, if any auto-fixable issues were detected:
 
+**CRITICAL — Before ANY auto-fix that modifies or regenerates STATE.md (frontmatter regeneration, phase_slug correction, or line compaction), you MUST create a timestamped backup first. DO NOT SKIP THIS STEP.**
+
+```
+mkdir -p .planning/backups
+cp .planning/STATE.md .planning/backups/STATE-$(date +%Y%m%dT%H%M%S).md
+```
+
+This ensures the user can recover the original STATE.md if the fix produces incorrect results.
+
 1. Count the auto-fixable issues and present:
 
    Use AskUserQuestion:

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

@@ -138,6 +138,7 @@ Display the following reference to the user:
 - **Depth**: `quick` (skip research, ~50% cheaper) | `standard` | `comprehensive` (~2x cost)
 - **State files**: `.planning/STATE.md` (position), `.planning/ROADMAP.md` (phases), `.planning/config.json` (settings)
 - **Configure**: `/pbr:config` to change depth, models, gates, parallelization
+- **List agents**: Run `claude agents` in your terminal to see all registered PBR agents and verify loading
 - **Tip**: Use `/pbr:quick` for creative/visual work where structured planning adds overhead without benefit.
 - **PR hygiene**: When creating PRs from a Plan-Build-Run project, `.planning/` commits can be filtered using phase branching (`git.branching: phase`) which squash-merges code-only changes to main.
 - **Seeds**: `/pbr:explore` can create seed files (`.planning/seeds/`) with trigger conditions. Seeds auto-inject into planning when their trigger phase is reached.