@sienklogic/plan-build-run 2.21.0 → 2.21.1

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

@@ -152,21 +152,76 @@ const AGENT_OUTPUTS = {
   }
 };
 
+/**
+ * Extract current phase number from STATE.md, preferring frontmatter over body.
+ * @param {string} stateContent - Full STATE.md content
+ * @returns {string|null} Phase number string or null
+ */
+function getCurrentPhase(stateContent) {
+  // Prefer frontmatter (always up-to-date)
+  const fmMatch = stateContent.match(/^current_phase:\s*(\d+)/m);
+  if (fmMatch) return fmMatch[1];
+  // Fall back to body text
+  const bodyMatch = stateContent.match(/Phase:\s*(\d+)\s+of\s+\d+/);
+  return bodyMatch ? bodyMatch[1] : null;
+}
+
+/**
+ * Check if ROADMAP.md is stale after executor/verifier completion.
+ * Detects: (1) no Progress table for current milestone, (2) table exists but
+ * phase row is out of date vs. phase artifacts on disk.
+ *
+ * @param {string} planningDir - Path to .planning/
+ * @returns {string|null} Warning message or null if in sync
+ */
+function checkRoadmapStaleness(planningDir) {
+  const roadmapPath = path.join(planningDir, 'ROADMAP.md');
+  if (!fs.existsSync(roadmapPath)) return null;
+
+  try {
+    const content = fs.readFileSync(roadmapPath, 'utf8');
+
+    // Check if there's a Progress table at all
+    const hasProgressTable = /Plans\s*Complete/i.test(content);
+    if (!hasProgressTable) {
+      return 'ROADMAP.md has no Progress table for the current milestone. The orchestrator should add a Progress table with columns: Phase | Plans Complete | Status | Completed. See skills/shared/state-update.md for format.';
+    }
+
+    // If table exists, check if current phase row is present
+    const stateFile = path.join(planningDir, 'STATE.md');
+    if (fs.existsSync(stateFile)) {
+      const stateContent = fs.readFileSync(stateFile, 'utf8');
+      const currentPhase = getCurrentPhase(stateContent);
+      if (currentPhase) {
+        const paddedPhase = currentPhase.padStart(2, '0');
+        const phaseInTable = new RegExp(`\\|\\s*${paddedPhase}\\.`).test(content) ||
+          new RegExp(`\\|\\s*${parseInt(currentPhase, 10)}\\.`).test(content);
+        if (!phaseInTable) {
+          return `ROADMAP.md Progress table exists but has no row for Phase ${currentPhase}. Add a row for the current phase.`;
+        }
+      }
+    }
+  } catch (_e) {
+    // best-effort
+  }
+  return null;
+}
+
 function findInPhaseDir(planningDir, pattern) {
   const matches = [];
   const phasesDir = path.join(planningDir, 'phases');
   if (!fs.existsSync(phasesDir)) return matches;
 
   try {
-    // Find the active phase from STATE.md
+    // Find the active phase from STATE.md (prefer frontmatter over body)
     const stateFile = path.join(planningDir, 'STATE.md');
     if (!fs.existsSync(stateFile)) return matches;
 
     const stateContent = fs.readFileSync(stateFile, 'utf8');
-    const phaseMatch = stateContent.match(/Phase:\s*(\d+)\s+of\s+\d+/);
-    if (!phaseMatch) return matches;
+    const phaseNum = getCurrentPhase(stateContent);
+    if (!phaseNum) return matches;
 
-    const currentPhase = phaseMatch[1].padStart(2, '0');
+    const currentPhase = phaseNum.padStart(2, '0');
     const dirs = fs.readdirSync(phasesDir).filter(d => d.startsWith(currentPhase));
     if (dirs.length === 0) return matches;
 
@@ -288,6 +343,23 @@ function main() {
   // Skill-specific post-completion validation
   const skillWarnings = [];
 
+  // ACTIVE-SKILL ENFORCEMENT: Warn when no .active-skill file exists.
+  // Skills are instructed (with CRITICAL markers) to write this file, but LLMs
+  // skip it under cognitive load. This warning reminds the orchestrator.
+  if (!activeSkill && agentType !== 'pbr:general' && agentType !== 'pbr:plan-checker' && agentType !== 'pbr:integration-checker') {
+    skillWarnings.push('.active-skill file is missing — the orchestrating skill never wrote it. This means skill-workflow guards were inactive for this entire operation. CRITICAL: Write the skill name to .planning/.active-skill BEFORE spawning agents.');
+  }
+
+  // ROADMAP.md SYNC: After executor or verifier completes, check if ROADMAP.md
+  // needs updating. Subagent writes (SUMMARY/VERIFICATION) trigger check-state-sync
+  // in the subagent context, but the main context ROADMAP.md may still be stale.
+  if (agentType === 'pbr:executor' || agentType === 'pbr:verifier') {
+    const roadmapWarning = checkRoadmapStaleness(planningDir);
+    if (roadmapWarning) {
+      skillWarnings.push(roadmapWarning);
+    }
+  }
+
   // Mtime-based recency check for researcher and synthesizer
   if (found._stale && (agentType === 'pbr:researcher' || agentType === 'pbr:synthesizer')) {
     const label = agentType === 'pbr:researcher' ? 'Researcher' : 'Synthesizer';
@@ -333,7 +405,7 @@ function main() {
     const verFiles = findInPhaseDir(planningDir, /^VERIFICATION\.md$/i);
     for (const vf of verFiles) {
       try {
-        const content = fs.readFileSync(vf, 'utf8');
+        const content = fs.readFileSync(path.join(planningDir, vf), 'utf8');
         const statusMatch = content.match(/^status:\s*(\S+)/mi);
         if (statusMatch && statusMatch[1] === 'gaps_found') {
           skillWarnings.push('Review verifier: VERIFICATION.md has status "gaps_found" — ensure gaps are surfaced to the user.');
@@ -386,5 +458,5 @@ function main() {
   process.exit(0);
 }
 
-module.exports = { AGENT_OUTPUTS, findInPhaseDir, findInQuickDir, checkSummaryCommits, isRecent };
+module.exports = { AGENT_OUTPUTS, findInPhaseDir, findInQuickDir, checkSummaryCommits, isRecent, getCurrentPhase, checkRoadmapStaleness };
 if (require.main === module || process.argv[1] === __filename) { main(); }

package/plugins/pbr/scripts/log-tool-failure.js

@@ -55,10 +55,7 @@ async function main() {
   // Provide recovery hints for Bash failures (most common actionable failure)
   if (toolName === 'Bash' && !isInterrupt) {
     const output = {
-      hookSpecificOutput: {
-        hookEventName: 'PostToolUseFailure',
-        additionalContext: 'Bash command failed. If this is a recurring issue, consider using /pbr:debug for systematic investigation.'
-      }
+      additionalContext: 'Bash command failed. If this is a recurring issue, consider using /pbr:debug for systematic investigation.'
     };
     process.stdout.write(JSON.stringify(output));
   }

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

@@ -115,7 +115,6 @@ function main() {
             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);

package/plugins/pbr/scripts/status-line.js

@@ -197,6 +197,23 @@ function main() {
   process.exit(0);
 }
 
+/**
+ * Parse YAML frontmatter from STATE.md content.
+ * Returns an object with frontmatter fields, or null if no frontmatter.
+ */
+function parseFrontmatter(content) {
+  if (!content.startsWith('---')) return null;
+  const endIdx = content.indexOf('---', 3);
+  if (endIdx === -1) return null;
+  const fm = content.substring(3, endIdx);
+  const result = {};
+  for (const line of fm.split(/\r?\n/)) {
+    const m = line.match(/^(\w[\w_]*):\s*"?([^"]*)"?\s*$/);
+    if (m) result[m[1]] = m[2];
+  }
+  return result;
+}
+
 function buildStatusLine(content, ctxPercent, cfg, stdinData) {
   const config = cfg || DEFAULTS;
   const sections = config.sections || DEFAULTS.sections;
@@ -205,15 +222,26 @@ function buildStatusLine(content, ctxPercent, cfg, stdinData) {
   const barCfg = config.context_bar || DEFAULTS.context_bar;
   const sd = stdinData || {};
 
+  // Prefer frontmatter (always up-to-date) over body text (may be stale)
+  const fm = parseFrontmatter(content);
+
   const parts = [];
 
   // Phase section (always includes brand text)
   if (sections.includes('phase')) {
+    const fmPhase = fm && fm.current_phase;
+    const fmTotal = fm && fm.total_phases;
+    const fmName = fm && fm.phase_name;
     const phaseMatch = content.match(/Phase:\s*(\d+)\s*of\s*(\d+)\s*(?:\(([^)]+)\))?/);
-    if (phaseMatch) {
-      parts.push(`${c.boldCyan}${brandText}${c.reset} ${c.bold}Phase ${phaseMatch[1]}/${phaseMatch[2]}${c.reset}`);
-      if (phaseMatch[3]) {
-        parts.push(`${c.magenta}${phaseMatch[3]}${c.reset}`);
+
+    const phaseNum = fmPhase || (phaseMatch && phaseMatch[1]);
+    const phaseTotal = fmTotal || (phaseMatch && phaseMatch[2]);
+    const phaseName = fmName || (phaseMatch && phaseMatch[3]);
+
+    if (phaseNum && phaseTotal) {
+      parts.push(`${c.boldCyan}${brandText}${c.reset} ${c.bold}Phase ${phaseNum}/${phaseTotal}${c.reset}`);
+      if (phaseName) {
+        parts.push(`${c.magenta}${phaseName}${c.reset}`);
       }
     } else {
       parts.push(`${c.boldCyan}${brandText}${c.reset}`);
@@ -222,10 +250,14 @@ function buildStatusLine(content, ctxPercent, cfg, stdinData) {
 
   // Plan section
   if (sections.includes('plan')) {
+    const fmComplete = fm && fm.plans_complete;
+    const fmTotal = fm && fm.plans_total;
     const planMatch = content.match(/Plan:\s*(\d+)\s*of\s*(\d+)/);
-    if (planMatch) {
-      const done = parseInt(planMatch[1], 10);
-      const total = parseInt(planMatch[2], 10);
+
+    const done = fmComplete != null ? parseInt(fmComplete, 10) : (planMatch ? parseInt(planMatch[1], 10) : null);
+    const total = fmTotal != null ? parseInt(fmTotal, 10) : (planMatch ? parseInt(planMatch[2], 10) : null);
+
+    if (done != null && total != null && total > 0) {
       const planColor = done === total ? c.green : c.white;
       parts.push(`${planColor}Plan ${done}/${total}${c.reset}`);
     }
@@ -233,9 +265,10 @@ function buildStatusLine(content, ctxPercent, cfg, stdinData) {
 
   // Status section
   if (sections.includes('status')) {
-    const statusMatch = content.match(/Status:\s*(.+)/);
-    if (statusMatch) {
-      const text = statusMatch[1].trim();
+    const fmStatus = fm && fm.status;
+    const statusMatch = content.match(/^Status:\s*(.+)/m);
+    const text = fmStatus || (statusMatch && statusMatch[1].trim());
+    if (text) {
       const short = text.length > maxLen ? text.slice(0, maxLen - 3) + '...' : text;
       parts.push(`${statusColor(text)}${short}${c.reset}`);
     }
@@ -285,4 +318,4 @@ function buildStatusLine(content, ctxPercent, cfg, stdinData) {
 }
 
 if (require.main === module || process.argv[1] === __filename) { main(); }
-module.exports = { buildStatusLine, buildContextBar, getContextPercent, getGitInfo, formatDuration, loadStatusLineConfig, DEFAULTS };
+module.exports = { buildStatusLine, buildContextBar, getContextPercent, getGitInfo, formatDuration, loadStatusLineConfig, parseFrontmatter, DEFAULTS };

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

@@ -178,6 +178,14 @@ function isGitCommit(command) {
 }
 
 function extractCommitMessage(command) {
+  // Try heredoc first: -m "$(cat <<'EOF'\n...\nEOF\n)" or -m "$(cat <<EOF\n...\nEOF\n)"
+  // Must check before generic -m patterns to avoid capturing heredoc syntax as the message
+  const heredocMatch = command.match(/<<'?EOF'?\s*\n([\s\S]*?)\nEOF/);
+  if (heredocMatch) {
+    // First line of heredoc is the commit message
+    return heredocMatch[1].trim().split('\n')[0].trim();
+  }
+
   // Try -m "message" or -m 'message'
   const mFlagMatch = command.match(/-m\s+["']([^"']+)["']/);
   if (mFlagMatch) return mFlagMatch[1];
@@ -186,13 +194,6 @@ function extractCommitMessage(command) {
   const mFlagMatch2 = command.match(/-m\s+"([^"]+)"/);
   if (mFlagMatch2) return mFlagMatch2[1];
 
-  // Try heredoc: -m "$(cat <<'EOF'\n...\nEOF\n)"
-  const heredocMatch = command.match(/<<'?EOF'?\s*\n([\s\S]*?)\nEOF/);
-  if (heredocMatch) {
-    // First line of heredoc is the commit message
-    return heredocMatch[1].trim().split('\n')[0].trim();
-  }
-
   return null;
 }
 

package/plugins/pbr/scripts/validate-skill-args.js

@@ -101,7 +101,8 @@ function checkSkillArgs(data) {
 
   return {
     output: {
-      additionalContext: [
+      decision: 'block',
+      reason: [
         'BLOCKED: /pbr:plan received freeform text instead of a phase number.',
         '',
         'The arguments "' + args.substring(0, 80) + (args.length > 80 ? '...' : '') + '" do not match any valid pattern.',

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

@@ -567,11 +567,6 @@ function checkBuildDependencyGate(data) {
   return null;
 }
 
-/**
- * Advisory check: when active skill is "build" and an executor is being
- * 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.

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

@@ -720,11 +720,10 @@ These return `{ success, old_status, new_status }` or `{ success, old_plans, new
 
 **CRITICAL: Update STATE.md NOW with phase completion status. Do NOT skip this step.**
 
-**8b. Update STATE.md:**
-- Phase status: {final_status from Step 8-pre}
-- Plan completion count
-- Last activity timestamp
-- Progress bar
+**8b. Update STATE.md (CRITICAL — update BOTH frontmatter AND body):**
+- Frontmatter: `status`, `plans_complete`, `last_activity`, `progress_percent`, `last_command`
+- Body `## Current Position`: `Phase:` line, `Plan:` line, `Status:` line, `Last activity:` line, `Progress:` bar
+- These MUST stay in sync — the status line reads frontmatter, humans read the body
 
 **8c. Commit planning docs (if configured):**
 Reference: `skills/shared/commit-planning-docs.md` for the standard commit pattern.

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

@@ -209,8 +209,6 @@ This ensures the user can recover the original STATE.md if the fix produces inco
 
 4. If "Skip": Do nothing, continue to the rest of the output.
 
-**Note:** When auto-fix is active, the health skill is no longer strictly read-only. The `allowed-tools` frontmatter must include `Write` and `AskUserQuestion` for auto-fix to work. Update the frontmatter accordingly.
-
 ---
 
 ## Bonus: Recent Decisions

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

@@ -492,7 +492,7 @@ Use AskUserQuestion (pattern: approve-revise-abort from `skills/shared/gate-prom
   4. Update the `Plans Complete` column to `0/{N}` where N = number of plan files just created
   5. Update the `Status` column to `planned`
   6. Save the file — do NOT skip this step
-- Update STATE.md: set current phase plan status to "planned"
+- Update STATE.md **(CRITICAL — update BOTH frontmatter AND body)**: set `status: "planned"`, `plans_total`, `last_command` in frontmatter AND update `Status:`, `Plan:` lines in body `## Current Position`
 - **If `features.auto_advance` is `true` AND `mode` is `autonomous`:** Chain directly to build: `Skill({ skill: "pbr:build", args: "{N}" })`. This continues the build→review→plan→build cycle automatically.
 - **Otherwise:** Suggest next action: `/pbr:build {N}`
 

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

@@ -331,10 +331,10 @@ If all automated checks and UAT items passed:
    4. Update the `Status` column to `verified`
    5. Update the `Completed` column to the current date (YYYY-MM-DD)
    6. Save the file — do NOT skip this step
-2. Update `.planning/STATE.md`:
-   - Phase status: "verified"
-   - Progress updated
-   - Last activity timestamp
+2. Update `.planning/STATE.md` **(CRITICAL — update BOTH frontmatter AND body):**
+   - Frontmatter: `status: "verified"`, `progress_percent`, `last_activity`, `last_command`
+   - Body `## Current Position`: `Status:` line, `Last activity:` line, `Progress:` bar
+   - These MUST stay in sync — see `skills/shared/state-update.md`
    - **STATE.md size limit:** Follow size limit enforcement rules in `skills/shared/state-update.md` (150 lines max).
 3. Update VERIFICATION.md with UAT results (append UAT section)
 3. Present completion:

package/plugins/pbr/skills/shared/state-update.md

@@ -4,12 +4,17 @@ Standard pattern for updating `.planning/STATE.md`. Include this fragment in ski
 
 ---
 
+**CRITICAL: STATE.md has TWO representations — YAML frontmatter AND markdown body. You MUST update BOTH when changing state. The status line reads frontmatter; humans and hooks read the body. If you only update frontmatter, the body goes stale and the status line shows wrong data. Do NOT skip body updates under any circumstances.**
+
+---
+
 ## When to Update STATE.md
 
 | Event | What to Update |
 |-------|---------------|
-| Phase status changes (planned, building, verified) | Current Position section |
-| Plan completes or fails | Plan counter, status, last activity |
+| Phase status changes (planned, building, verified) | Frontmatter fields AND Current Position section |
+| Plan completes or fails | Frontmatter fields AND Plan counter, status, last activity |
+| Phase advances to next phase | Frontmatter fields AND Phase line, Status, Last activity, Progress bar |
 | New decision made | Accumulated Context > Decisions |
 | Blocker discovered or resolved | Accumulated Context > Blockers/Concerns |
 | Session starts or ends | Session Continuity section |
@@ -31,6 +36,9 @@ See: .planning/PROJECT.md (updated {date})
 Update `Current focus` when phase changes.
 
 ### 2. Current Position (lines 9-14)
+
+**CRITICAL: This section MUST match the frontmatter fields above it. When you update `current_phase` or `status` in frontmatter, you MUST also update the corresponding lines below. A hook will auto-fix drift, but do not rely on it.**
+
 ```
 ## Current Position
 Phase: {N} of {total} ({Phase name})

package/plugins/pbr/templates/ROADMAP.md.tmpl

@@ -28,6 +28,8 @@ Phase 01 ──→ Phase 02 ──→ Phase 04
 **Goal:** {overall project goal from requirements}
 **Phases:** 1 - {n}
 
+## Phase Details
+
 ### Phase 01: Project Setup
 
 **Goal**: {goal statement}