@sienklogic/plan-build-run 2.18.0 → 2.19.0

package/CHANGELOG.md

@@ -5,6 +5,38 @@ 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.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)
+
+
+### Bug Fixes
+
+* **tools:** add Skill tool to 4 PBR skills that use auto-advance chaining ([2be11a4](https://github.com/SienkLogic/plan-build-run/commit/2be11a4dd4fe0ad875787fc65d7f217919f4a662))
+* **tools:** update critical agents to use model: sonnet instead of inherit ([6d66573](https://github.com/SienkLogic/plan-build-run/commit/6d66573b72352a1c412ff7e1e74adee2e1d2b59f))
+
 ## [2.18.0](https://github.com/SienkLogic/plan-build-run/compare/plan-build-run-v2.17.1...plan-build-run-v2.18.0) (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.0",
+  "version": "2.19.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/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "pbr",
   "displayName": "Plan-Build-Run",
-  "version": "2.18.0",
+  "version": "2.19.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.0",
+  "version": "2.19.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

@@ -1,7 +1,7 @@
 ---
 name: debugger
 description: "Systematic debugging using scientific method. Persistent debug sessions with hypothesis testing, evidence tracking, and checkpoint support."
-model: inherit
+model: sonnet
 readonly: false
 ---
 
@@ -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/executor.md

@@ -1,7 +1,7 @@
 ---
 name: executor
 description: "Executes plan tasks with atomic commits, deviation handling, checkpoint protocols, TDD support, and self-verification."
-model: inherit
+model: sonnet
 readonly: false
 ---
 

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

@@ -1,7 +1,7 @@
 ---
 name: general
 description: "Lightweight Plan-Build-Run-aware agent for ad-hoc tasks that don't fit specialized roles."
-model: inherit
+model: sonnet
 readonly: false
 ---
 

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/agents/planner.md

@@ -1,7 +1,7 @@
 ---
 name: planner
 description: "Creates executable phase plans with task breakdown, dependency analysis, wave assignment, and goal-backward verification. Also creates roadmaps."
-model: inherit
+model: sonnet
 readonly: false
 ---
 

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.0",
+  "version": "2.19.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

@@ -1,7 +1,7 @@
 ---
 name: debugger
 description: "Systematic debugging using scientific method. Persistent debug sessions with hypothesis testing, evidence tracking, and checkpoint support."
-model: inherit
+model: sonnet
 memory: project
 tools:
   - Read
@@ -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/executor.md

@@ -1,7 +1,7 @@
 ---
 name: executor
 description: "Executes plan tasks with atomic commits, deviation handling, checkpoint protocols, TDD support, and self-verification."
-model: inherit
+model: sonnet
 memory: project
 tools:
   - Read

package/plugins/pbr/agents/general.md

@@ -1,7 +1,7 @@
 ---
 name: general
 description: "Lightweight Plan-Build-Run-aware agent for ad-hoc tasks that don't fit specialized roles."
-model: inherit
+model: sonnet
 memory: none
 tools:
   - Read

package/plugins/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
 memory: none
 tools:
@@ -35,7 +35,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 +131,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 +147,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 +157,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 +183,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 +206,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/planner.md

@@ -1,7 +1,7 @@
 ---
 name: planner
 description: "Creates executable phase plans with task breakdown, dependency analysis, wave assignment, and goal-backward verification. Also creates roadmaps."
-model: inherit
+model: sonnet
 memory: project
 tools:
   - Read

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-state-sync.js

@@ -190,28 +190,28 @@ function updateStatePosition(content, updates) {
       const body = content.substring(fmEnd + 3);
 
       if (updates.fmCurrentPhase !== undefined) {
-        fm = fm.replace(/^(current_phase:\s*).*/m, `$1${updates.fmCurrentPhase}`);
+        fm = fm.replace(/^(current_phase:\s*).*/m, (_, p) => `${p}${updates.fmCurrentPhase}`);
       }
       if (updates.fmTotalPhases !== undefined) {
-        fm = fm.replace(/^(total_phases:\s*).*/m, `$1${updates.fmTotalPhases}`);
+        fm = fm.replace(/^(total_phases:\s*).*/m, (_, p) => `${p}${updates.fmTotalPhases}`);
       }
       if (updates.fmPhaseSlug !== undefined) {
-        fm = fm.replace(/^(phase_slug:\s*).*/m, `$1"${updates.fmPhaseSlug}"`);
+        fm = fm.replace(/^(phase_slug:\s*).*/m, (_, p) => `${p}"${updates.fmPhaseSlug}"`);
       }
       if (updates.fmPhaseName !== undefined) {
-        fm = fm.replace(/^(phase_name:\s*).*/m, `$1"${updates.fmPhaseName}"`);
+        fm = fm.replace(/^(phase_name:\s*).*/m, (_, p) => `${p}"${updates.fmPhaseName}"`);
       }
       if (updates.fmPlansComplete !== undefined) {
-        fm = fm.replace(/^(plans_complete:\s*).*/m, `$1${updates.fmPlansComplete}`);
+        fm = fm.replace(/^(plans_complete:\s*).*/m, (_, p) => `${p}${updates.fmPlansComplete}`);
       }
       if (updates.fmStatus !== undefined) {
-        fm = fm.replace(/^(status:\s*).*/m, `$1"${updates.fmStatus}"`);
+        fm = fm.replace(/^(status:\s*).*/m, (_, p) => `${p}"${updates.fmStatus}"`);
       }
       if (updates.fmLastActivity !== undefined) {
-        fm = fm.replace(/^(last_activity:\s*).*/m, `$1"${updates.fmLastActivity}"`);
+        fm = fm.replace(/^(last_activity:\s*).*/m, (_, p) => `${p}"${updates.fmLastActivity}"`);
       }
       if (updates.fmProgressPct !== undefined) {
-        fm = fm.replace(/^(progress_percent:\s*).*/m, `$1${updates.fmProgressPct}`);
+        fm = fm.replace(/^(progress_percent:\s*).*/m, (_, p) => `${p}${updates.fmProgressPct}`);
       }
 
       // Reconstruct with updated frontmatter + body with line updates

package/plugins/pbr/scripts/context-budget-check.js

@@ -80,7 +80,7 @@ function main() {
       // Replace existing section
       content = content.replace(
         /## Session Continuity[\s\S]*?(?=\n## |\n---|\s*$)/,
-        `${continuityHeader}\n${continuityContent}\n`
+        () => `${continuityHeader}\n${continuityContent}\n`
       );
     } else {
       // Append section

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/package.json

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

package/plugins/pbr/scripts/pbr-tools.js

@@ -823,7 +823,7 @@ function updateLegacyStateField(content, field, value) {
     case 'current_phase': {
       const idx = lines.findIndex(l => /Phase:\s*\d+\s+of\s+\d+/.test(l));
       if (idx !== -1) {
-        lines[idx] = lines[idx].replace(/(Phase:\s*)\d+/, `$1${value}`);
+        lines[idx] = lines[idx].replace(/(Phase:\s*)\d+/, (_, prefix) => `${prefix}${value}`);
       }
       break;
     }
@@ -844,7 +844,7 @@ function updateLegacyStateField(content, field, value) {
     case 'plans_complete': {
       const idx = lines.findIndex(l => /Plan:\s*\d+\s+of\s+\d+/.test(l));
       if (idx !== -1) {
-        lines[idx] = lines[idx].replace(/(Plan:\s*)\d+/, `$1${value}`);
+        lines[idx] = lines[idx].replace(/(Plan:\s*)\d+/, (_, prefix) => `${prefix}${value}`);
       }
       break;
     }
@@ -886,7 +886,7 @@ function updateFrontmatterField(content, field, value) {
 
   const fieldRegex = new RegExp(`^(${field})\\s*:.*$`, 'm');
   if (fieldRegex.test(yaml)) {
-    yaml = yaml.replace(fieldRegex, `${field}: ${formatted}`);
+    yaml = yaml.replace(fieldRegex, () => `${field}: ${formatted}`);
   } else {
     yaml = yaml + `\n${field}: ${formatted}`;
   }

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/build/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: build
 description: "Execute all plans in a phase. Spawns agents to build in parallel, commits atomically."
-allowed-tools: Read, Write, Edit, Bash, Glob, Grep, Task, AskUserQuestion
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep, Task, AskUserQuestion, Skill
 argument-hint: "<phase-number> [--gaps-only] [--team]"
 ---
 

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

@@ -1,7 +1,7 @@
 ---
 name: continue
 description: "Execute the next logical step automatically. No prompts, no decisions — just do it."
-allowed-tools: Read, Write, Bash, Glob, Grep, Task
+allowed-tools: Read, Write, Bash, Glob, Grep, Task, Skill
 ---
 
 **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.**

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/plan/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: plan
 description: "Create a detailed plan for a phase. Research, plan, and verify before building."
-allowed-tools: Read, Write, Bash, Glob, Grep, WebFetch, WebSearch, Task, AskUserQuestion
+allowed-tools: Read, Write, Bash, Glob, Grep, WebFetch, WebSearch, Task, AskUserQuestion, Skill
 argument-hint: "<phase-number> [--skip-research] [--assumptions] [--gaps] | add | insert <N> | remove <N>"
 ---
 

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

@@ -1,7 +1,7 @@
 ---
 name: review
 description: "Verify the build matched the plan. Automated checks + walkthrough with you."
-allowed-tools: Read, Write, Bash, Glob, Grep, Task, AskUserQuestion
+allowed-tools: Read, Write, Bash, Glob, Grep, Task, AskUserQuestion, Skill
 argument-hint: "<phase-number> [--auto-fix] [--teams]"
 ---