@sienklogic/plan-build-run 2.11.0 → 2.12.1

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

@@ -20,6 +20,82 @@ 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) {
+  // Strip <details>/<summary> HTML tags so phases inside collapsed milestone blocks are found
+  const stripped = content
+    .replace(/<\/?details>/gi, '')
+    .replace(/<\/?summary>/gi, '');
+  const lines = stripped.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 +124,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);
       }
 
@@ -69,7 +149,7 @@ function main() {
           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.`
+          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 pbr-tools.js state load\` to check current state.`
         };
         process.stdout.write(JSON.stringify(output));
         process.exit(0);
@@ -89,7 +169,7 @@ function main() {
         });
 
         const output = {
-          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.`
+          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 pbr-tools.js state load\` to check current state.`
         };
         process.stdout.write(JSON.stringify(output));
       } else {
@@ -104,7 +184,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);
     }
   });
@@ -144,7 +229,11 @@ function parseState(content) {
  *   | 01    | ...  | ...  | ...   | ...  | pending |
  */
 function getRoadmapPhaseStatus(content, phaseNum) {
-  const lines = content.split('\n');
+  // Strip <details>/<summary> HTML tags so phases inside collapsed milestone blocks are found
+  const stripped = content
+    .replace(/<\/?details>/gi, '')
+    .replace(/<\/?summary>/gi, '');
+  const lines = stripped.split('\n');
 
   let statusColIndex = -1;
   let phaseColIndex = -1;
@@ -220,7 +309,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)) {
@@ -240,7 +333,7 @@ function checkSync(data) {
     });
     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.`
+        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 pbr-tools.js state load\` to check current state.`
       }
     };
   }
@@ -252,9 +345,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: `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.`
+        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 pbr-tools.js state load\` to check current state.`
       }
     };
   }
@@ -272,7 +376,11 @@ function checkSync(data) {
  */
 function parseRoadmapPhases(content) {
   const phases = new Set();
-  const lines = content.split('\n');
+  // Strip <details>/<summary> HTML tags so phases inside collapsed milestone blocks are found
+  const stripped = content
+    .replace(/<\/?details>/gi, '')
+    .replace(/<\/?summary>/gi, '');
+  const lines = stripped.split('\n');
 
   for (const line of lines) {
     // Match NN-slug patterns (at least two-digit prefix with hyphen and slug)
@@ -318,7 +426,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;
   }
 
@@ -334,5 +443,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,7 +10,7 @@
  *   - /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:scan: Read-only skills
+ *   - /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
@@ -25,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 = '';
@@ -43,14 +45,15 @@ 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);
       }
 
       // Apply skill-specific rules
-      const violation = checkSkillRules(activeSkill, filePath, planningDir);
+      const violation = checkSkillRules(activeSkill, filePath, planningDir, sessionId);
       if (violation) {
         logHook('check-skill-workflow', 'PreToolUse', 'block', {
           skill: activeSkill,
@@ -79,23 +82,23 @@ 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;
 }
 
 /**
  * Check skill-specific workflow rules.
  * Returns { rule, message } if violated, null if OK.
  */
-function checkSkillRules(skill, filePath, planningDir) {
+function checkSkillRules(skill, filePath, planningDir, sessionId) {
   const normalizedPath = filePath.replace(/\\/g, '/');
   const normalizedPlanning = planningDir.replace(/\\/g, '/');
   // Check with both raw paths and resolved symlinks (macOS /var → /private/var)
@@ -108,7 +111,7 @@ function checkSkillRules(skill, filePath, planningDir) {
   }
 
   // Check for orchestrator writing agent artifacts (any skill)
-  const artifactViolation = checkArtifactRules(filePath, planningDir);
+  const artifactViolation = checkArtifactRules(filePath, planningDir, sessionId);
   if (artifactViolation) return artifactViolation;
 
   switch (skill) {
@@ -149,7 +152,7 @@ function checkSkillRules(skill, filePath, planningDir) {
  * - If .active-agent exists, a subagent is running (allow writes)
  * - If .active-agent does NOT exist, the orchestrator is writing (block)
  */
-function checkArtifactRules(filePath, planningDir) {
+function checkArtifactRules(filePath, planningDir, sessionId) {
   const basename = path.basename(filePath);
 
   // Only check SUMMARY and VERIFICATION files in phase directories
@@ -158,8 +161,16 @@ function checkArtifactRules(filePath, planningDir) {
   if (!isSummary && !isVerification) return null;
 
   // If .active-agent exists, a subagent is running — allow
-  const activeAgentFile = path.join(planningDir, '.active-agent');
-  if (fs.existsSync(activeAgentFile)) return null;
+  // Try session-scoped path first, fall back to global
+  let agentExists = false;
+  if (sessionId) {
+    const sessionPath = resolveSessionPath(planningDir, '.active-agent', sessionId);
+    agentExists = fs.existsSync(sessionPath);
+  }
+  if (!agentExists) {
+    agentExists = fs.existsSync(path.join(planningDir, '.active-agent'));
+  }
+  if (agentExists) return null;
 
   const artifactType = isSummary ? 'SUMMARY.md' : 'VERIFICATION.md';
   return {
@@ -188,7 +199,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) {
@@ -200,7 +211,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.`
     };
   }
 
@@ -222,7 +233,7 @@ 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;
@@ -231,18 +242,10 @@ function checkBuildRules(filePath, isInPlanning, planningDir) {
 
 /**
  * /pbr:statusline rules:
- * - Warn when writing settings.json with hardcoded home directory paths
+ * Content check requires full hook data — handled by checkStatuslineContent() in main()
  */
-function checkStatuslineRules(filePath, _isInPlanning, _planningDir) {
-  const normalizedPath = filePath.replace(/\\/g, '/');
-
-  // Only check settings.json writes
-  if (!normalizedPath.endsWith('settings.json')) return null;
-
-  // Check tool_input content isn't available here — we only have filePath.
-  // The hardcoded path check needs content, which we get from the hook data.
-  // This function is called from checkSkillRules which only passes filePath.
-  // We'll check in the wrapper instead. For now, return null (pass).
+function checkStatuslineRules(_filePath, _isInPlanning, _planningDir) {
+  // Content check requires full hook data — handled by checkStatuslineContent() in main()
   return null;
 }
 
@@ -319,10 +322,11 @@ 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);
+  const violation = checkSkillRules(activeSkill, filePath, planningDir, sessionId);
   if (violation) {
     logHook('check-skill-workflow', 'PreToolUse', 'block', {
       skill: activeSkill, file: path.basename(filePath), rule: violation.rule