@sienklogic/plan-build-run 2.1.0 → 2.1.1

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

@@ -20,6 +20,78 @@ const { logEvent } = require('./event-logger');
 
 const LIFECYCLE_STATUSES = ['planned', 'built', 'partial', 'verified'];
 
+/** Ordered lifecycle statuses for regression detection. Higher index = more advanced. */
+const STATUS_ORDER = ['planned', 'partial', 'built', 'verified'];
+
+/**
+ * Determine if a STATE.md → ROADMAP.md mismatch is high-risk.
+ * High-risk scenarios:
+ *   1. Status regression: ROADMAP status is earlier in lifecycle than STATE status
+ *   2. Phase ordering gap: ROADMAP table skips phase numbers (e.g., 01 then 03)
+ *
+ * @param {string} stateContent - Contents of STATE.md
+ * @param {string} roadmapContent - Contents of ROADMAP.md
+ * @returns {boolean}
+ */
+function isHighRisk(stateContent, roadmapContent) {
+  const stateInfo = parseState(stateContent);
+  if (!stateInfo || !stateInfo.phase || !stateInfo.status) return false;
+
+  // Check status regression
+  const roadmapStatus = getRoadmapPhaseStatus(roadmapContent, stateInfo.phase);
+  if (roadmapStatus) {
+    const stateIdx = STATUS_ORDER.indexOf(stateInfo.status);
+    const roadmapIdx = STATUS_ORDER.indexOf(roadmapStatus.toLowerCase());
+    if (stateIdx !== -1 && roadmapIdx !== -1 && roadmapIdx < stateIdx) {
+      return true;
+    }
+  }
+
+  // Check phase ordering gaps
+  const phaseNumbers = getAllRoadmapPhaseNumbers(roadmapContent);
+  if (phaseNumbers.length >= 2) {
+    for (let i = 1; i < phaseNumbers.length; i++) {
+      if (phaseNumbers[i] - phaseNumbers[i - 1] > 1) {
+        return true;
+      }
+    }
+  }
+
+  return false;
+}
+
+/**
+ * Extract all phase numbers from ROADMAP.md table, sorted ascending.
+ * @param {string} content - ROADMAP.md content
+ * @returns {number[]}
+ */
+function getAllRoadmapPhaseNumbers(content) {
+  const lines = content.split('\n');
+  const numbers = [];
+  let inTable = false;
+  let phaseColIndex = -1;
+
+  for (const line of lines) {
+    if (!inTable) {
+      if (line.includes('|') && /Phase/i.test(line) && /Status/i.test(line)) {
+        const cols = splitTableRow(line);
+        phaseColIndex = cols.findIndex(c => /^Phase$/i.test(c));
+        if (phaseColIndex !== -1) inTable = true;
+      }
+      continue;
+    }
+    if (/^\s*\|[\s-:|]+\|\s*$/.test(line)) continue;
+    if (!line.includes('|')) break;
+    const cols = splitTableRow(line);
+    if (cols.length > phaseColIndex) {
+      const num = parseInt(normalizePhaseNum(cols[phaseColIndex]), 10);
+      if (!isNaN(num)) numbers.push(num);
+    }
+  }
+
+  return numbers.sort((a, b) => a - b);
+}
+
 function main() {
   let input = '';
 
@@ -48,6 +120,10 @@ function main() {
       const stateInfo = parseState(stateContent);
       if (!stateInfo || !stateInfo.phase || !stateInfo.status) {
         logHook('check-roadmap-sync', 'PostToolUse', 'skip', { reason: 'could not parse STATE.md' });
+        const output = {
+          additionalContext: '[Roadmap Sync — WARN] Could not parse STATE.md: missing **Phase**: or **Status**: fields. Expected format: "**Phase**: 3 of 8" and "**Status**: Planning". To fix: run /pbr:health for a guided repair, or manually add the missing fields to .planning/STATE.md.'
+        };
+        process.stdout.write(JSON.stringify(output));
         process.exit(0);
       }
 
@@ -60,9 +136,18 @@ function main() {
 
       const roadmapStatus = getRoadmapPhaseStatus(roadmapContent, stateInfo.phase);
       if (!roadmapStatus) {
-        logHook('check-roadmap-sync', 'PostToolUse', 'skip', {
+        logHook('check-roadmap-sync', 'PostToolUse', 'warn', {
           reason: `phase ${stateInfo.phase} not found in ROADMAP.md table`
         });
+        logEvent('workflow', 'roadmap-sync', {
+          phase: stateInfo.phase,
+          stateStatus: stateInfo.status,
+          status: 'missing-phase'
+        });
+        const output = {
+          additionalContext: `CRITICAL: Phase ${stateInfo.phase} has status "${stateInfo.status}" in STATE.md but is not listed in ROADMAP.md Progress table. Update the ROADMAP.md Progress table NOW before continuing. Run: \`node plugins/pbr/scripts/pbr-tools.js state load\` to check current state.`
+        };
+        process.stdout.write(JSON.stringify(output));
         process.exit(0);
       }
 
@@ -80,7 +165,7 @@ function main() {
         });
 
         const output = {
-          additionalContext: `ROADMAP.md out of sync: Phase ${stateInfo.phase} is "${roadmapStatus}" in ROADMAP.md but "${stateInfo.status}" in STATE.md. Update the Phase Overview table in ROADMAP.md to match.`
+          additionalContext: `CRITICAL: ROADMAP.md out of sync — Phase ${stateInfo.phase} is "${roadmapStatus}" in ROADMAP.md but "${stateInfo.status}" in STATE.md. Update the ROADMAP.md Progress table NOW before continuing. Run: \`node plugins/pbr/scripts/pbr-tools.js state load\` to check current state.`
         };
         process.stdout.write(JSON.stringify(output));
       } else {
@@ -95,7 +180,12 @@ function main() {
       }
 
       process.exit(0);
-    } catch (_e) {
+    } catch (e) {
+      logHook('check-roadmap-sync', 'PostToolUse', 'error', { reason: 'parse failure in main', error: e.message });
+      const output = {
+        additionalContext: `[Roadmap Sync] Warning: Failed to parse STATE.md or ROADMAP.md — ${e.message}. Run /pbr:health to diagnose.`
+      };
+      process.stdout.write(JSON.stringify(output));
       process.exit(0);
     }
   });
@@ -211,7 +301,11 @@ function checkSync(data) {
   const stateInfo = parseState(stateContent);
   if (!stateInfo || !stateInfo.phase || !stateInfo.status) {
     logHook('check-roadmap-sync', 'PostToolUse', 'skip', { reason: 'could not parse STATE.md' });
-    return null;
+    return {
+      output: {
+        additionalContext: '[Roadmap Sync] Could not parse phase/status from STATE.md — ensure it contains **Phase**: and **Status**: fields.'
+      }
+    };
   }
 
   if (!LIFECYCLE_STATUSES.includes(stateInfo.status)) {
@@ -223,10 +317,17 @@ function checkSync(data) {
 
   const roadmapStatus = getRoadmapPhaseStatus(roadmapContent, stateInfo.phase);
   if (!roadmapStatus) {
-    logHook('check-roadmap-sync', 'PostToolUse', 'skip', {
+    logHook('check-roadmap-sync', 'PostToolUse', 'warn', {
       reason: `phase ${stateInfo.phase} not found in ROADMAP.md table`
     });
-    return null;
+    logEvent('workflow', 'roadmap-sync', {
+      phase: stateInfo.phase, stateStatus: stateInfo.status, status: 'missing-phase'
+    });
+    return {
+      output: {
+        additionalContext: `CRITICAL: Phase ${stateInfo.phase} has status "${stateInfo.status}" in STATE.md but is not listed in ROADMAP.md Progress table. Update the ROADMAP.md Progress table NOW before continuing. Run: \`node plugins/pbr/scripts/pbr-tools.js state load\` to check current state.`
+      }
+    };
   }
 
   if (roadmapStatus.toLowerCase() !== stateInfo.status) {
@@ -236,9 +337,20 @@ function checkSync(data) {
     logEvent('workflow', 'roadmap-sync', {
       phase: stateInfo.phase, stateStatus: stateInfo.status, roadmapStatus, status: 'out-of-sync'
     });
+
+    // Block on high-risk regressions, advise on non-critical drift
+    if (isHighRisk(stateContent, roadmapContent)) {
+      return {
+        output: {
+          decision: 'block',
+          reason: `ROADMAP.md status regression detected for phase ${stateInfo.phase}.\n\nPhase ${stateInfo.phase} is "${stateInfo.status}" in STATE.md but "${roadmapStatus}" in ROADMAP.md. Writing a lower-lifecycle status to ROADMAP.md would corrupt milestone tracking.\n\nUpdate ROADMAP.md to match STATE.md status ("${stateInfo.status}") or fix STATE.md if the regression is intentional.`
+        }
+      };
+    }
+
     return {
       output: {
-        additionalContext: `ROADMAP.md out of sync: Phase ${stateInfo.phase} is "${roadmapStatus}" in ROADMAP.md but "${stateInfo.status}" in STATE.md. Update the Phase Overview table in ROADMAP.md to match.`
+        additionalContext: `CRITICAL: ROADMAP.md out of sync — Phase ${stateInfo.phase} is "${roadmapStatus}" in ROADMAP.md but "${stateInfo.status}" in STATE.md. Update the ROADMAP.md Progress table NOW before continuing. Run: \`node plugins/pbr/scripts/pbr-tools.js state load\` to check current state.`
       }
     };
   }
@@ -302,7 +414,8 @@ function checkFilesystemDrift(roadmapContent, phasesDir) {
   let entries;
   try {
     entries = fs.readdirSync(phasesDir, { withFileTypes: true });
-  } catch (_e) {
+  } catch (e) {
+    logHook('check-roadmap-sync', 'PostToolUse', 'error', { reason: 'failed to read phases dir', error: e.message });
     return warnings;
   }
 
@@ -318,5 +431,61 @@ function checkFilesystemDrift(roadmapContent, phasesDir) {
   return warnings;
 }
 
-module.exports = { parseState, getRoadmapPhaseStatus, checkSync, parseRoadmapPhases, checkFilesystemDrift };
+/**
+ * Validate ROADMAP.md after a milestone is marked complete.
+ * All phases in the roadmap table must be "Verified" or "Archived".
+ * If the milestone section is already collapsed (contains "COMPLETED"), passes.
+ *
+ * @param {string} roadmapContent - ROADMAP.md content
+ * @param {string} completedMilestone - Milestone identifier (e.g., "v1.0")
+ * @returns {null|{decision: string, reason: string}} null if valid, blocking result if not
+ */
+function validatePostMilestone(roadmapContent, completedMilestone) {
+  // If milestone section is already collapsed/completed, pass
+  const collapsedPattern = new RegExp(`##\\s+Milestone\\s+${completedMilestone.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}.*COMPLETED`, 'i');
+  if (collapsedPattern.test(roadmapContent)) return null;
+
+  // Parse all phase statuses from the table
+  const lines = roadmapContent.split('\n');
+  let inTable = false;
+  let phaseColIndex = -1;
+  let statusColIndex = -1;
+  const unverified = [];
+
+  for (const line of lines) {
+    if (!inTable) {
+      if (line.includes('|') && /Phase/i.test(line) && /Status/i.test(line)) {
+        const cols = splitTableRow(line);
+        phaseColIndex = cols.findIndex(c => /^Phase$/i.test(c));
+        statusColIndex = cols.findIndex(c => /^Status$/i.test(c));
+        if (phaseColIndex !== -1 && statusColIndex !== -1) inTable = true;
+      }
+      continue;
+    }
+    if (/^\s*\|[\s-:|]+\|\s*$/.test(line)) continue;
+    if (!line.includes('|')) break;
+
+    const cols = splitTableRow(line);
+    if (cols.length <= Math.max(phaseColIndex, statusColIndex)) continue;
+
+    const phaseNum = normalizePhaseNum(cols[phaseColIndex]);
+    const status = cols[statusColIndex].toLowerCase().trim();
+
+    if (status !== 'verified' && status !== 'archived') {
+      unverified.push({ phase: phaseNum, status });
+    }
+  }
+
+  if (unverified.length > 0) {
+    const details = unverified.map(u => `Phase ${u.phase} (${u.status})`).join(', ');
+    return {
+      decision: 'block',
+      reason: `Cannot complete milestone ${completedMilestone}: unverified phases remain.\n\nThe following phases are not yet Verified or Archived: ${details}. All phases must reach Verified or Archived status before milestone completion.\n\nRun /pbr:verify-work on each unverified phase to advance it to Verified status.`
+    };
+  }
+
+  return null;
+}
+
+module.exports = { parseState, getRoadmapPhaseStatus, checkSync, parseRoadmapPhases, checkFilesystemDrift, isHighRisk, validatePostMilestone };
 if (require.main === module || process.argv[1] === __filename) { main(); }

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

@@ -10,6 +10,8 @@
  *   - /pbr:quick: Cannot write files outside .planning/ until a PLAN.md
  *     exists in .planning/quick/. This prevents the orchestrator from
  *     skipping the planning steps and jumping straight to implementation.
+ *   - /pbr:milestone, /pbr:explore, /pbr:import, /pbr:map-codebase: Read-only skills
+ *     that cannot write files outside .planning/.
  *
  * Skills opt in by writing .planning/.active-skill at the start of
  * their execution. If the file doesn't exist, this hook does nothing.
@@ -23,6 +25,8 @@ const fs = require('fs');
 const path = require('path');
 const { logHook } = require('./hook-logger');
 const { logEvent } = require('./event-logger');
+const { sessionLoad } = require('./pbr-tools');
+const { resolveSessionPath } = require('./lib/core');
 
 function main() {
   let input = '';
@@ -41,8 +45,9 @@ function main() {
       const cwd = process.cwd();
       const planningDir = path.join(cwd, '.planning');
 
-      // Read active skill
-      const activeSkill = readActiveSkill(planningDir);
+      // Read active skill (session-scoped)
+      const sessionId = data.session_id || null;
+      const activeSkill = readActiveSkill(planningDir, sessionId);
       if (!activeSkill) {
         process.exit(0);
       }
@@ -77,16 +82,16 @@ function main() {
   });
 }
 
-function readActiveSkill(planningDir) {
-  const skillFile = path.join(planningDir, '.active-skill');
-  if (!fs.existsSync(skillFile)) return null;
-
-  try {
-    const content = fs.readFileSync(skillFile, 'utf8').trim();
-    return content || null;
-  } catch (_e) {
-    return null;
+function readActiveSkill(planningDir, sessionId) {
+  // Try .session.json first, fall back to .active-skill (session-scoped when sessionId available)
+  let activeSkill = sessionLoad(planningDir, sessionId).activeSkill || null;
+  if (!activeSkill) {
+    const skillPath = sessionId
+      ? resolveSessionPath(planningDir, '.active-skill', sessionId)
+      : path.join(planningDir, '.active-skill');
+    try { activeSkill = fs.readFileSync(skillPath, 'utf8').trim(); } catch (_) { /* file missing */ }
   }
+  return activeSkill || null;
 }
 
 /**
@@ -111,9 +116,31 @@ function checkSkillRules(skill, filePath, planningDir) {
 
   switch (skill) {
   case 'quick':
+  case 'do':
     return checkQuickRules(filePath, isInPlanning, planningDir);
   case 'build':
     return checkBuildRules(filePath, isInPlanning, planningDir);
+  case 'statusline':
+    return checkStatuslineRules(filePath, isInPlanning, planningDir);
+  case 'plan':
+  case 'review':
+  case 'discuss':
+  case 'begin':
+  case 'milestone':
+  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;
   }
@@ -164,7 +191,7 @@ function checkQuickRules(filePath, isInPlanning, planningDir) {
 }
 
 /**
- * /pbr:build rules:
+ * /pbr:execute-phase rules:
  * - Cannot write files outside .planning/ unless a PLAN.md exists for the current phase
  */
 function checkBuildRules(filePath, isInPlanning, planningDir) {
@@ -176,7 +203,7 @@ function checkBuildRules(filePath, isInPlanning, planningDir) {
   if (!fs.existsSync(phasesDir)) {
     return {
       rule: 'build-requires-plan',
-      message: `Workflow violation: /pbr:build requires a planned phase before writing source code.\n\nBlocked: ${filePath}\n\nRun /pbr:plan first to create a phase plan.`
+      message: `Workflow violation: /pbr:execute-phase requires a planned phase before writing source code.\n\nBlocked: ${filePath}\n\nRun /pbr:plan-phase first to create a phase plan.`
     };
   }
 
@@ -198,13 +225,62 @@ function checkBuildRules(filePath, isInPlanning, planningDir) {
 
     return {
       rule: 'build-requires-plan',
-      message: `Workflow violation: /pbr:build requires a PLAN.md for phase ${currentPhase} before writing source code.\n\nBlocked: ${filePath}\n\nRun /pbr:plan ${currentPhase} first.`
+      message: `Workflow violation: /pbr:execute-phase requires a PLAN.md for phase ${currentPhase} before writing source code.\n\nBlocked: ${filePath}\n\nRun /pbr:plan-phase ${currentPhase} first.`
     };
   } catch (_e) {
     return null;
   }
 }
 
+/**
+ * /pbr:statusline rules:
+ * Content check requires full hook data — handled by checkStatuslineContent() in main()
+ */
+function checkStatuslineRules(_filePath, _isInPlanning, _planningDir) {
+  // Content check requires full hook data — handled by checkStatuslineContent() in main()
+  return null;
+}
+
+/**
+ * Extended statusline check that includes content inspection.
+ * Called from checkWorkflow/main where we have access to full hook data.
+ */
+function checkStatuslineContent(data) {
+  const filePath = data.tool_input?.file_path || data.tool_input?.path || '';
+  const normalizedPath = filePath.replace(/\\/g, '/');
+
+  if (!normalizedPath.endsWith('settings.json')) return null;
+
+  // Check new_string (Edit) or content (Write) for hardcoded home paths
+  const content = data.tool_input?.new_string || data.tool_input?.content || '';
+  const oldString = data.tool_input?.old_string || '';
+  const textToCheck = content + ' ' + oldString;
+
+  // Hardcoded home directory paths — warn, don't block (may be legitimately resolved)
+  const hardcodedPathPattern = /(\/home\/|C:\\Users\\|\/Users\/)[^"'\s]*\.claude/i;
+  if (hardcodedPathPattern.test(textToCheck)) {
+    return {
+      rule: 'statusline-hardcoded-path',
+      message: `Warning: settings.json write appears to contain a hardcoded home directory path.\n\nFile: ${filePath}\n\nCRITICAL: Do NOT hardcode paths. Use dynamic path resolution to find the correct plugin installation directory.`
+    };
+  }
+
+  return null;
+}
+
+/**
+ * Read-only skill rules (review, discuss, begin):
+ * - Cannot write files outside .planning/
+ */
+function checkReadOnlySkillRules(skill, filePath, isInPlanning) {
+  if (isInPlanning) return null;
+
+  return {
+    rule: `${skill}-readonly`,
+    message: `Workflow violation: /pbr:${skill} should only write to .planning/ files.\n\nBlocked: ${filePath}\n\nThe ${skill} skill is not intended to modify source code.`
+  };
+}
+
 /**
  * Check if any PLAN.md file exists in a directory (recursive one level).
  */
@@ -214,10 +290,10 @@ function hasPlanFile(dir) {
   try {
     const entries = fs.readdirSync(dir, { withFileTypes: true });
     for (const entry of entries) {
-      if (entry.isFile() && entry.name.endsWith('PLAN.md')) return true;
+      if (entry.isFile() && /^PLAN.*\.md$/i.test(entry.name)) return true;
       if (entry.isDirectory()) {
         const subEntries = fs.readdirSync(path.join(dir, entry.name));
-        if (subEntries.some(f => f.endsWith('PLAN.md'))) return true;
+        if (subEntries.some(f => /^PLAN.*\.md$/i.test(f))) return true;
       }
     }
   } catch (_e) {
@@ -238,7 +314,8 @@ function checkWorkflow(data) {
   const cwd = process.cwd();
   const planningDir = path.join(cwd, '.planning');
 
-  const activeSkill = readActiveSkill(planningDir);
+  const sessionId = data.session_id || null;
+  const activeSkill = readActiveSkill(planningDir, sessionId);
   if (!activeSkill) return null;
 
   const violation = checkSkillRules(activeSkill, filePath, planningDir);
@@ -255,8 +332,22 @@ function checkWorkflow(data) {
     };
   }
 
+  // Statusline content check (needs full data for content inspection)
+  if (activeSkill === 'statusline') {
+    const contentViolation = checkStatuslineContent(data);
+    if (contentViolation) {
+      logHook('check-skill-workflow', 'PreToolUse', 'warn', {
+        skill: activeSkill, file: path.basename(filePath), rule: contentViolation.rule
+      });
+      return {
+        exitCode: 0,
+        output: { additionalContext: contentViolation.message }
+      };
+    }
+  }
+
   return null;
 }
 
-module.exports = { readActiveSkill, checkSkillRules, hasPlanFile, checkWorkflow };
+module.exports = { readActiveSkill, checkSkillRules, hasPlanFile, checkWorkflow, checkStatuslineContent, checkReadOnlySkillRules };
 if (require.main === module || process.argv[1] === __filename) { main(); }