@sienklogic/plan-build-run 2.9.1 → 2.11.0

package/plugins/pbr/references/ui-formatting.md

@@ -7,9 +7,9 @@ Consistent output formatting for all Plan-Build-Run skills. Every skill that pro
 Use for major workflow transitions. Always use `PLAN-BUILD-RUN` prefix.
 
 ```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- PLAN-BUILD-RUN ► {STAGE NAME}
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► {STAGE NAME}                              ║
+╚══════════════════════════════════════════════════════════════╝
 ```
 
 **Stage names (uppercase):**
@@ -21,7 +21,7 @@ Use for major workflow transitions. Always use `PLAN-BUILD-RUN` prefix.
 - `EXECUTING WAVE {N}`
 - `VERIFYING`
 - `PHASE {N} COMPLETE ✓`
-- `MILESTONE COMPLETE 🎉`
+- `MILESTONE COMPLETE`
 - `SCANNING CODEBASE`
 - `DEBUGGING`
 
@@ -33,9 +33,9 @@ Use for major workflow transitions. Always use `PLAN-BUILD-RUN` prefix.
 
 Format:
 ```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- PLAN-BUILD-RUN ► {SKILL NAME}
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► {SKILL NAME}                              ║
+╚══════════════════════════════════════════════════════════════╝
 ```
 
 **Skill names (uppercase):**
@@ -155,7 +155,7 @@ For research agents:
 
 ## Checkpoint Boxes
 
-User action required. Use double-line box drawing, 62-character width.
+User action required. Use double-line box drawing, 62-character inner width.
 
 ```
 ╔══════════════════════════════════════════════════════════════╗
@@ -164,9 +164,7 @@ User action required. Use double-line box drawing, 62-character width.
 
 {Content}
 
-──────────────────────────────────────────────────────────────
 → {ACTION PROMPT}
-──────────────────────────────────────────────────────────────
 ```
 
 **Types:**
@@ -260,25 +258,21 @@ Use plain conversational prompts for these cases instead.
 Always present at end of major completions (phase complete, milestone complete, project init).
 
 ```
-───────────────────────────────────────────────────────────────
-
-## ▶ Next Up
+╔══════════════════════════════════════════════════════════════╗
+║  ▶ NEXT UP                                                   ║
+╚══════════════════════════════════════════════════════════════╝
 
 **{Identifier}: {Name}** — {one-line description}
 
 `{copy-paste command}`
 
 <sub>`/clear` first → fresh context window</sub>
-
-───────────────────────────────────────────────────────────────
+```
 
 **Also available:**
 - `/pbr:alternative-1` — description
 - `/pbr:alternative-2` — description
 
-───────────────────────────────────────────────────────────────
-```
-
 **Shorter routing (for minor completions):**
 ```
 What's next?
@@ -333,18 +327,18 @@ Use tables for structured data:
 ### Phase Complete
 
 ```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- PLAN-BUILD-RUN ► PHASE {N} COMPLETE ✓
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► PHASE {N} COMPLETE ✓                      ║
+╚══════════════════════════════════════════════════════════════╝
 
 **Phase {N}: {Name}**
 
 {X} plans executed
 Goal verified ✓
 
-───────────────────────────────────────────────────────────────
-
-## ▶ Next Up
+╔══════════════════════════════════════════════════════════════╗
+║  ▶ NEXT UP                                                   ║
+╚══════════════════════════════════════════════════════════════╝
 
 **Phase {N+1}: {Name}** — {Goal from ROADMAP.md}
 
@@ -352,30 +346,26 @@ Goal verified ✓
 
 <sub>/clear first → fresh context window</sub>
 
-───────────────────────────────────────────────────────────────
-
 **Also available:**
 - /pbr:plan {N+1} — skip discussion, plan directly
 - /pbr:review {N} — manual acceptance testing before continuing
-
-───────────────────────────────────────────────────────────────
 ```
 
 ### Milestone Complete
 
 ```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- PLAN-BUILD-RUN ► MILESTONE COMPLETE 🎉
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► MILESTONE COMPLETE                         ║
+╚══════════════════════════════════════════════════════════════╝
 
 **{version}**
 
 {N} phases completed
 All phase goals verified ✓
 
-───────────────────────────────────────────────────────────────
-
-## ▶ Next Up
+╔══════════════════════════════════════════════════════════════╗
+║  ▶ NEXT UP                                                   ║
+╚══════════════════════════════════════════════════════════════╝
 
 **Audit milestone** — verify requirements, cross-phase integration, E2E flows
 
@@ -383,21 +373,17 @@ All phase goals verified ✓
 
 <sub>/clear first → fresh context window</sub>
 
-───────────────────────────────────────────────────────────────
-
 **Also available:**
 - /pbr:review — manual acceptance testing
 - /pbr:milestone complete — archive milestone after audit passes
-
-───────────────────────────────────────────────────────────────
 ```
 
 ### Gaps Found
 
 ```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- PLAN-BUILD-RUN ► PHASE {N} GAPS FOUND ⚠
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► PHASE {N} GAPS FOUND ⚠                    ║
+╚══════════════════════════════════════════════════════════════╝
 
 **Phase {N}: {Name}**
 
@@ -408,9 +394,9 @@ Report: .planning/phases/{phase_dir}/VERIFICATION.md
 
 {Extract gap summaries from VERIFICATION.md}
 
-───────────────────────────────────────────────────────────────
-
-## ▶ Next Up
+╔══════════════════════════════════════════════════════════════╗
+║  ▶ NEXT UP                                                   ║
+╚══════════════════════════════════════════════════════════════╝
 
 **Plan gap closure** — create additional plans to complete the phase
 
@@ -418,13 +404,9 @@ Report: .planning/phases/{phase_dir}/VERIFICATION.md
 
 <sub>/clear first → fresh context window</sub>
 
-───────────────────────────────────────────────────────────────
-
 **Also available:**
 - cat .planning/phases/{phase_dir}/VERIFICATION.md — see full report
 - /pbr:review {N} — manual testing before planning
-
-───────────────────────────────────────────────────────────────
 ```
 
 ---
@@ -434,9 +416,9 @@ Report: .planning/phases/{phase_dir}/VERIFICATION.md
 Use for session lifecycle transitions (pause/resume):
 
 ```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- PLAN-BUILD-RUN ► SESSION RESTORED ✓
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► SESSION RESTORED ✓                         ║
+╚══════════════════════════════════════════════════════════════╝
 
 Position: Phase {N} — {phase name}, Plan {M}
 Paused: {ISO datetime}
@@ -452,10 +434,11 @@ Other session banners: `SESSION SAVED ✓` (pause), `RESUMING SESSION` (resume s
 ## Anti-Patterns
 
 Do NOT:
-- Use varying box/banner widths
-- Mix banner styles (`===`, `---`, `***`) with `━━━` banners
+- Use varying box/banner widths — always 62-character inner width
+- Use `━━━` heavy bars or `───` thin dividers for banners/sections — use `╔═╗║╚═╝` boxes
+- Mix banner styles (`===`, `---`, `***`) with double-line boxes
 - Skip `PLAN-BUILD-RUN ►` prefix in stage banners
-- Use random emoji (only `🎉` for milestone complete, `✓` for phase complete)
+- Use random emoji (only for milestone complete, `✓` for phase complete)
 - Skip the "Next Up" block after major completions
 - Reference non-Plan-Build-Run commands (always use `/pbr:*` commands)
 - Use non-Plan-Build-Run branding in banners

package/plugins/pbr/scripts/check-skill-workflow.js

@@ -113,6 +113,7 @@ function checkSkillRules(skill, filePath, planningDir) {
 
   switch (skill) {
   case 'quick':
+  case 'do':
     return checkQuickRules(filePath, isInPlanning, planningDir);
   case 'build':
     return checkBuildRules(filePath, isInPlanning, planningDir);
@@ -126,6 +127,16 @@ function checkSkillRules(skill, filePath, planningDir) {
   case 'explore':
   case 'import':
   case 'scan':
+  case 'note':
+  case 'todo':
+  case 'health':
+  case 'help':
+  case 'config':
+  case 'continue':
+  case 'resume':
+  case 'pause':
+  case 'status':
+  case 'dashboard':
     return checkReadOnlySkillRules(skill, filePath, isInPlanning);
   default:
     return null;

package/plugins/pbr/scripts/check-state-sync.js

@@ -161,6 +161,10 @@ function updateStatePosition(content, updates) {
   for (let i = 0; i < lines.length; i++) {
     const line = lines[i];
 
+    if (updates.phaseLine !== undefined && /^Phase:\s/.test(line)) {
+      lines[i] = `Phase: ${updates.phaseLine}`;
+    }
+
     if (updates.planLine !== undefined && /^Plan:\s/.test(line)) {
       lines[i] = `Plan: ${updates.planLine}`;
     }
@@ -185,6 +189,18 @@ function updateStatePosition(content, updates) {
       let fm = content.substring(0, fmEnd + 3);
       const body = content.substring(fmEnd + 3);
 
+      if (updates.fmCurrentPhase !== undefined) {
+        fm = fm.replace(/^(current_phase:\s*).*/m, `$1${updates.fmCurrentPhase}`);
+      }
+      if (updates.fmTotalPhases !== undefined) {
+        fm = fm.replace(/^(total_phases:\s*).*/m, `$1${updates.fmTotalPhases}`);
+      }
+      if (updates.fmPhaseSlug !== undefined) {
+        fm = fm.replace(/^(phase_slug:\s*).*/m, `$1"${updates.fmPhaseSlug}"`);
+      }
+      if (updates.fmPhaseName !== undefined) {
+        fm = fm.replace(/^(phase_name:\s*).*/m, `$1"${updates.fmPhaseName}"`);
+      }
       if (updates.fmPlansComplete !== undefined) {
         fm = fm.replace(/^(plans_complete:\s*).*/m, `$1${updates.fmPlansComplete}`);
       }
@@ -216,6 +232,9 @@ function updateStatePositionBody(body, updates) {
   for (let i = 0; i < lines.length; i++) {
     const line = lines[i];
 
+    if (updates.phaseLine !== undefined && /^Phase:\s/.test(line)) {
+      lines[i] = `Phase: ${updates.phaseLine}`;
+    }
     if (updates.planLine !== undefined && /^Plan:\s/.test(line)) {
       lines[i] = `Plan: ${updates.planLine}`;
     }
@@ -323,6 +342,17 @@ function checkStateSync(data) {
   const today = new Date().toISOString().slice(0, 10);
   const messages = [];
 
+  // Derive phase metadata for potential phase-line sync
+  const phaseNumInt = parseInt(phaseNum, 10);
+  const phaseSlug = phaseDirName.replace(/^\d+-/, '');
+  const phaseName = phaseSlug.replace(/-/g, ' ')
+    .replace(/\b\w/g, c => c.toUpperCase());
+  let totalPhases = 0;
+  try {
+    totalPhases = fs.readdirSync(phasesDir, { withFileTypes: true })
+      .filter(e => e.isDirectory() && /^\d+-/.test(e.name)).length;
+  } catch (_e) { /* leave as 0 */ }
+
   if (isSummary) {
     const plansComplete = `${artifacts.completeSummaries}/${artifacts.plans}`;
     const allComplete = artifacts.completeSummaries >= artifacts.plans;
@@ -358,6 +388,20 @@ function checkStateSync(data) {
           fmLastActivity: today,
           fmProgressPct: overallPct
         };
+
+        // Detect phase mismatch and add phase updates
+        const currentPhaseMatch = stateContent.match(/^current_phase:\s*(\d+)/m)
+          || stateContent.match(/^Phase:\s*(\d+)\s/m);
+        const currentPhase = currentPhaseMatch ? parseInt(currentPhaseMatch[1], 10) : null;
+        if (currentPhase !== null && currentPhase !== phaseNumInt) {
+          stateUpdates.phaseLine = `${phaseNumInt} of ${totalPhases} (${phaseName})`;
+          stateUpdates.fmCurrentPhase = phaseNumInt;
+          stateUpdates.fmTotalPhases = totalPhases;
+          stateUpdates.fmPhaseSlug = phaseSlug;
+          stateUpdates.fmPhaseName = phaseName;
+          messages.push(`STATE.md: Phase ${currentPhase} → ${phaseNumInt}`);
+        }
+
         const updatedState = updateStatePosition(stateContent, stateUpdates);
         if (updatedState !== stateContent) {
           atomicWrite(statePath, updatedState);
@@ -422,6 +466,20 @@ function checkStateSync(data) {
           fmLastActivity: today,
           fmProgressPct: overallPct
         };
+
+        // Detect phase mismatch and add phase updates
+        const currentPhaseMatch = stateContent.match(/^current_phase:\s*(\d+)/m)
+          || stateContent.match(/^Phase:\s*(\d+)\s/m);
+        const currentPhase = currentPhaseMatch ? parseInt(currentPhaseMatch[1], 10) : null;
+        if (currentPhase !== null && currentPhase !== phaseNumInt) {
+          stateUpdates.phaseLine = `${phaseNumInt} of ${totalPhases} (${phaseName})`;
+          stateUpdates.fmCurrentPhase = phaseNumInt;
+          stateUpdates.fmTotalPhases = totalPhases;
+          stateUpdates.fmPhaseSlug = phaseSlug;
+          stateUpdates.fmPhaseName = phaseName;
+          messages.push(`STATE.md: Phase ${currentPhase} → ${phaseNumInt}`);
+        }
+
         const updatedState = updateStatePosition(stateContent, stateUpdates);
         if (updatedState !== stateContent) {
           atomicWrite(statePath, updatedState);

package/plugins/pbr/scripts/check-subagent-output.js

@@ -21,6 +21,19 @@ const fs = require('fs');
 const path = require('path');
 const { logHook } = require('./hook-logger');
 
+/**
+ * Check if a file was modified recently (within thresholdMs).
+ * Returns false if file doesn't exist or on error.
+ */
+function isRecent(filePath, thresholdMs = 300000) {
+  try {
+    const stat = fs.statSync(filePath);
+    return (Date.now() - stat.mtimeMs) < thresholdMs;
+  } catch (_e) {
+    return false;
+  }
+}
+
 // Agent type → expected output patterns
 const AGENT_OUTPUTS = {
   'pbr:executor': {
@@ -46,9 +59,16 @@ const AGENT_OUTPUTS = {
       const researchDir = path.join(planningDir, 'research');
       if (!fs.existsSync(researchDir)) return [];
       try {
-        return fs.readdirSync(researchDir)
+        const allFiles = fs.readdirSync(researchDir)
           .filter(f => f.endsWith('.md'))
           .map(f => path.join('research', f));
+        if (allFiles.length === 0) return [];
+        const recentFiles = allFiles.filter(f => isRecent(path.join(planningDir, f)));
+        if (recentFiles.length === 0) {
+          // Files exist but none are recent — return them but flag staleness
+          allFiles._stale = true;
+        }
+        return allFiles;
       } catch (_e) {
         return [];
       }
@@ -61,14 +81,27 @@ const AGENT_OUTPUTS = {
       if (fs.existsSync(researchDir)) {
         try {
           const files = fs.readdirSync(researchDir).filter(f => f.endsWith('.md'));
-          if (files.length > 0) return files.map(f => path.join('research', f));
+          if (files.length > 0) {
+            const allFiles = files.map(f => path.join('research', f));
+            const recentFiles = allFiles.filter(f => isRecent(path.join(planningDir, f)));
+            if (recentFiles.length === 0) {
+              allFiles._stale = true;
+            }
+            return allFiles;
+          }
         } catch (_e) { /* best-effort */ }
       }
       const contextFile = path.join(planningDir, 'CONTEXT.md');
       if (fs.existsSync(contextFile)) {
         try {
           const stat = fs.statSync(contextFile);
-          if (stat.size > 0) return ['CONTEXT.md'];
+          if (stat.size > 0) {
+            const result = ['CONTEXT.md'];
+            if (!isRecent(contextFile)) {
+              result._stale = true;
+            }
+            return result;
+          }
         } catch (_e) { /* best-effort */ }
       }
       return [];
@@ -255,6 +288,12 @@ function main() {
   // Skill-specific post-completion validation
   const skillWarnings = [];
 
+  // Mtime-based recency check for researcher and synthesizer
+  if (found._stale && (agentType === 'pbr:researcher' || agentType === 'pbr:synthesizer')) {
+    const label = agentType === 'pbr:researcher' ? 'Researcher' : 'Synthesizer';
+    skillWarnings.push(`${label} output may be stale — no recent output files detected.`);
+  }
+
   // GAP-04: Begin planner must produce core files
   if (activeSkill === 'begin' && agentType === 'pbr:planner') {
     const coreFiles = ['REQUIREMENTS.md', 'ROADMAP.md', 'STATE.md'];
@@ -317,5 +356,5 @@ function main() {
   process.exit(0);
 }
 
-module.exports = { AGENT_OUTPUTS, findInPhaseDir, findInQuickDir, checkSummaryCommits };
+module.exports = { AGENT_OUTPUTS, findInPhaseDir, findInQuickDir, checkSummaryCommits, isRecent };
 if (require.main === module || process.argv[1] === __filename) { main(); }

package/plugins/pbr/scripts/validate-task.js

@@ -114,7 +114,8 @@ function checkQuickExecutorGate(data) {
     return {
       block: true,
       reason: 'Cannot spawn executor: .planning/quick/ directory does not exist. ' +
-        'You must create the quick task directory and PLAN.md first (Steps 4-6).'
+        'You must create the quick task directory and PLAN.md first (Steps 4-6). ' +
+        'To fix: Re-run /pbr:quick to create the quick task directory and PLAN.md.'
     };
   }
 
@@ -138,13 +139,15 @@ function checkQuickExecutorGate(data) {
       return {
         block: true,
         reason: 'Cannot spawn executor: no PLAN.md found in any .planning/quick/*/ directory. ' +
-          'You must create .planning/quick/{NNN}-{slug}/PLAN.md first (Steps 4-6).'
+          'You must create .planning/quick/{NNN}-{slug}/PLAN.md first (Steps 4-6). ' +
+          'To fix: Re-run /pbr:quick to create the quick task directory and PLAN.md.'
       };
     }
   } catch (_e) {
     return {
       block: true,
-      reason: 'Cannot spawn executor: failed to read .planning/quick/ directory.'
+      reason: 'Cannot spawn executor: failed to read .planning/quick/ directory. ' +
+        'To fix: Re-run /pbr:quick to create the quick task directory and PLAN.md.'
     };
   }
 
@@ -187,7 +190,7 @@ function checkBuildExecutorGate(data) {
     if (!fs.existsSync(phasesDir)) {
       return {
         block: true,
-        reason: 'Cannot spawn executor: .planning/phases/ directory does not exist. Run /pbr:plan first.'
+        reason: 'Cannot spawn executor: .planning/phases/ directory does not exist. To fix: Run /pbr:plan {N} to create plans first.'
       };
     }
 
@@ -195,7 +198,7 @@ function checkBuildExecutorGate(data) {
     if (dirs.length === 0) {
       return {
         block: true,
-        reason: `Cannot spawn executor: no phase directory found for phase ${currentPhase}. Run /pbr:plan first.`
+        reason: `Cannot spawn executor: no phase directory found for phase ${currentPhase}. To fix: Run /pbr:plan ${currentPhase} to create plans first.`
       };
     }
 
@@ -213,7 +216,7 @@ function checkBuildExecutorGate(data) {
     if (!hasPlan) {
       return {
         block: true,
-        reason: `Cannot spawn executor: no PLAN.md found in .planning/phases/${dirs[0]}/. Run /pbr:plan first.`
+        reason: `Cannot spawn executor: no PLAN.md found in .planning/phases/${dirs[0]}/. To fix: Run /pbr:plan ${currentPhase} to create plans first.`
       };
     }
   } catch (_e) {
@@ -248,7 +251,7 @@ function checkPlanExecutorGate(data) {
 
   return {
     block: true,
-    reason: 'Plan skill should not spawn executors. Use /pbr:build to execute plans.'
+    reason: 'Plan skill should not spawn executors. To fix: Run /pbr:build to execute plans. The plan skill creates plans; the build skill executes them.'
   };
 }
 
@@ -296,7 +299,7 @@ function checkReviewPlannerGate(data) {
     if (!hasVerification) {
       return {
         block: true,
-        reason: 'Review planner gate: Cannot spawn planner for gap closure without a VERIFICATION.md. Run /pbr:review first to generate verification results.'
+        reason: 'Review planner gate: Cannot spawn planner for gap closure without a VERIFICATION.md. To fix: Run /pbr:review {N} to create VERIFICATION.md first.'
       };
     }
   } catch (_e) {
@@ -358,7 +361,7 @@ function checkReviewVerifierGate(data) {
     if (!hasSummary) {
       return {
         block: true,
-        reason: 'Review verifier gate: Cannot spawn verifier without SUMMARY.md in phase directory. Run /pbr:build first.'
+        reason: 'Review verifier gate: Cannot spawn verifier without SUMMARY.md in phase directory. To fix: Run /pbr:build {N} to create SUMMARY.md first.'
       };
     }
   } catch (_e) {
@@ -443,14 +446,22 @@ function checkMilestoneCompleteGate(data) {
         if (pDirs.length === 0) {
           return {
             block: true,
-            reason: `Milestone complete gate: Phase ${paddedPhase} directory not found. All milestone phases must be verified before completing milestone.`
+            reason: `Milestone complete gate: Phase ${paddedPhase} directory not found. All milestone phases must be verified before completing milestone. To fix: Run /pbr:review ${paddedPhase} — phase must have status: passed.`
           };
         }
-        const hasVerification = fs.existsSync(path.join(phasesDir, pDirs[0], 'VERIFICATION.md'));
+        const verificationFile = path.join(phasesDir, pDirs[0], 'VERIFICATION.md');
+        const hasVerification = fs.existsSync(verificationFile);
         if (!hasVerification) {
           return {
             block: true,
-            reason: `Milestone complete gate: Phase ${paddedPhase} (${pDirs[0]}) lacks VERIFICATION.md. All milestone phases must be verified before completing milestone.`
+            reason: `Milestone complete gate: Phase ${paddedPhase} (${pDirs[0]}) lacks VERIFICATION.md. All milestone phases must be verified before completing milestone. To fix: Run /pbr:review ${paddedPhase} — phase must have status: passed.`
+          };
+        }
+        const verStatus = getVerificationStatus(verificationFile);
+        if (verStatus === 'gaps_found') {
+          return {
+            block: true,
+            reason: `Milestone complete gate: Phase ${paddedPhase} VERIFICATION.md has status: gaps_found. Close all gaps before completing milestone. To fix: Run /pbr:review ${paddedPhase} — phase must have status: passed.`
           };
         }
       }
@@ -538,14 +549,14 @@ function checkBuildDependencyGate(data) {
       if (pDirs.length === 0) {
         return {
           block: true,
-          reason: `Build dependency gate: Dependent phase ${paddedPhase} lacks VERIFICATION.md. Run /pbr:review on dependent phases first.`
+          reason: `Build dependency gate: Dependent phase ${paddedPhase} lacks VERIFICATION.md. To fix: Run /pbr:review on the dependency phase first.`
         };
       }
       const hasVerification = fs.existsSync(path.join(phasesDir, pDirs[0], 'VERIFICATION.md'));
       if (!hasVerification) {
         return {
           block: true,
-          reason: `Build dependency gate: Dependent phase ${paddedPhase} lacks VERIFICATION.md. Run /pbr:review on dependent phases first.`
+          reason: `Build dependency gate: Dependent phase ${paddedPhase} lacks VERIFICATION.md. To fix: Run /pbr:review on the dependency phase first.`
         };
       }
     }
@@ -561,6 +572,45 @@ function checkBuildDependencyGate(data) {
  * spawned, warn if .checkpoint-manifest.json is missing in the phase dir.
  * Returns a warning string or null.
  */
+/**
+ * Parse VERIFICATION.md frontmatter to extract status field.
+ * Returns the status string or 'unknown' if not parseable.
+ */
+function getVerificationStatus(filePath) {
+  try {
+    const content = fs.readFileSync(filePath, 'utf8');
+    const fmMatch = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+    if (!fmMatch) return 'unknown';
+    const statusMatch = fmMatch[1].match(/^status:\s*(\S+)/m);
+    return statusMatch ? statusMatch[1] : 'unknown';
+  } catch (_e) {
+    return 'unknown';
+  }
+}
+
+/**
+ * Advisory check: when pbr:debugger is spawned and .active-skill is 'debug',
+ * warn if .planning/debug/ directory does not exist.
+ * Returns a warning string or null.
+ */
+function checkDebuggerAdvisory(data) {
+  const subagentType = data.tool_input?.subagent_type || '';
+  if (subagentType !== 'pbr:debugger') return null;
+  // Only advise when spawned from the debug skill
+  const activeSkillPath = path.join(process.cwd(), '.planning', '.active-skill');
+  try {
+    const activeSkill = fs.readFileSync(activeSkillPath, 'utf8').trim();
+    if (activeSkill !== 'debug') return null;
+  } catch (_e) {
+    return null; // No .active-skill file — skip advisory
+  }
+  const debugDir = path.join(process.cwd(), '.planning', 'debug');
+  if (!fs.existsSync(debugDir)) {
+    return 'Debugger advisory: .planning/debug/ does not exist. Create it before spawning the debugger so output has a target location.';
+  }
+  return null;
+}
+
 function checkCheckpointManifest(data) {
   const toolInput = data.tool_input || {};
   const subagentType = toolInput.subagent_type || '';
@@ -595,7 +645,7 @@ function checkCheckpointManifest(data) {
     const phaseDir = path.join(phasesDir, dirs[0]);
     const manifestFile = path.join(phaseDir, '.checkpoint-manifest.json');
     if (!fs.existsSync(manifestFile)) {
-      return 'Build advisory: .checkpoint-manifest.json not found in phase directory. The build skill should write this before spawning executors.';
+      return 'Build advisory: .checkpoint-manifest.json not found in phase directory. The build skill should write this before spawning executors. To fix: Run /pbr:health to regenerate checkpoint manifest.';
     }
   } catch (_e) {
     return null;
@@ -624,7 +674,7 @@ function checkActiveSkillIntegrity(data) {
 
   const activeSkillFile = path.join(planningDir, '.active-skill');
   if (!fs.existsSync(activeSkillFile)) {
-    return 'Active-skill integrity: .planning/.active-skill not found. Skill-specific enforcement is disabled. The invoking skill should write this file.';
+    return 'Active-skill integrity: .planning/.active-skill not found. Skill-specific enforcement is disabled. The invoking skill should write this file. To fix: Wait for the current skill to finish, or delete .planning/.active-skill if stale.';
   }
 
   return null;
@@ -727,6 +777,8 @@ function main() {
       const warnings = checkTask(data);
       const manifestWarning = checkCheckpointManifest(data);
       if (manifestWarning) warnings.push(manifestWarning);
+      const debuggerWarning = checkDebuggerAdvisory(data);
+      if (debuggerWarning) warnings.push(debuggerWarning);
       const activeSkillWarning = checkActiveSkillIntegrity(data);
       if (activeSkillWarning) warnings.push(activeSkillWarning);
 
@@ -747,5 +799,5 @@ function main() {
   });
 }
 
-module.exports = { checkTask, checkQuickExecutorGate, checkBuildExecutorGate, checkPlanExecutorGate, checkReviewPlannerGate, checkReviewVerifierGate, checkMilestoneCompleteGate, checkBuildDependencyGate, checkCheckpointManifest, checkActiveSkillIntegrity, KNOWN_AGENTS, MAX_DESCRIPTION_LENGTH };
+module.exports = { checkTask, checkQuickExecutorGate, checkBuildExecutorGate, checkPlanExecutorGate, checkReviewPlannerGate, checkReviewVerifierGate, checkMilestoneCompleteGate, checkBuildDependencyGate, checkCheckpointManifest, checkDebuggerAdvisory, getVerificationStatus, checkActiveSkillIntegrity, KNOWN_AGENTS, MAX_DESCRIPTION_LENGTH };
 if (require.main === module || process.argv[1] === __filename) { main(); }