@sienklogic/plan-build-run 2.12.0 → 2.12.1

package/plugins/pbr/scripts/progress-tracker.js

@@ -6,18 +6,57 @@
  *
  * If no .planning/ directory exists, exits silently (non-Plan-Build-Run project).
  * If STATE.md exists, reads and outputs a concise summary.
+ *
+ * Heavy lifting delegated to:
+ *   - ./lib/session-briefing.js  (context building, health, intel, decisions)
+ *   - ./lib/dashboard-launch.js  (dashboard + hook-server launchers, enriched context)
  */
 
 const fs = require('fs');
 const path = require('path');
-const os = require('os');
-const { execSync } = require('child_process');
 const { logHook } = require('./hook-logger');
 const { logEvent } = require('./event-logger');
-const { configLoad } = require('./pbr-tools');
+const { configLoad, sessionSave } = require('./pbr-tools');
+const { ensureSessionDir, cleanStaleSessions } = require('./lib/core');
+const { resolveConfig, checkHealth, warmUp } = require('./local-llm/health');
+
+// Re-export from extracted modules for backward compatibility
+const {
+  buildEnhancedBriefing,
+  buildContext,
+  getHookHealthSummary,
+  getDecisionBriefing,
+  getNegativeKnowledgeBriefing,
+  getIntelContext,
+  getIntelStalenessWarning,
+  checkLearningsDeferrals,
+  detectOtherSessions,
+  extractSection,
+  findContinueFiles,
+  countNotes,
+  FAILURE_DECISIONS,
+  HOOK_HEALTH_MAX_ENTRIES,
+} = require('./lib/session-briefing');
+
+const {
+  tryLaunchDashboard,
+  tryLaunchHookServer,
+  getEnrichedContext,
+} = require('./lib/dashboard-launch');
+
+function readStdin() {
+  try {
+    const input = fs.readFileSync(0, 'utf8').trim();
+    if (input) return JSON.parse(input);
+  } catch (_e) {
+    // empty or non-JSON stdin
+  }
+  return {};
+}
 
-function main() {
-  const cwd = process.cwd();
+async function main() {
+  const data = readStdin();
+  const cwd = process.env.PBR_PROJECT_ROOT || process.cwd();
   const planningDir = path.join(cwd, '.planning');
   const stateFile = path.join(planningDir, 'STATE.md');
 
@@ -26,319 +65,134 @@ function main() {
     process.exit(0);
   }
 
+  // Extract session_id from hook input
+  const sessionId = data.session_id || null;
+
   // Reset compaction counter for new session
   const { resetCounter } = require('./suggest-compact');
-  resetCounter(planningDir);
-
-  const context = buildContext(planningDir, stateFile);
-
-  // Auto-launch dashboard if configured
-  const config = configLoad(planningDir);
-  if (config && config.dashboard && config.dashboard.auto_launch) {
-    tryLaunchDashboard(config.dashboard.port || 3000, planningDir, cwd);
-  }
-
-  if (context) {
-    const output = {
-      additionalContext: context
-    };
-    process.stdout.write(JSON.stringify(output));
-    logHook('progress-tracker', 'SessionStart', 'injected', { hasState: true });
-    logEvent('workflow', 'session-start', { hasState: true });
-  } else {
-    logHook('progress-tracker', 'SessionStart', 'skipped', { hasState: false });
-    logEvent('workflow', 'session-start', { hasState: false });
-  }
-
-  process.exit(0);
-}
-
-function buildContext(planningDir, stateFile) {
-  const parts = [];
+  resetCounter(planningDir, sessionId);
 
-  parts.push('[Plan-Build-Run Project Detected]');
+  // Reset session phase counter for new session
+  const { resetTracker } = require('./session-tracker');
+  resetTracker(planningDir, sessionId);
 
-  // Git context
-  try {
-    const branch = execSync('git rev-parse --abbrev-ref HEAD', { encoding: 'utf8', timeout: 3000 }).trim();
-    const porcelain = execSync('git status --porcelain', { encoding: 'utf8', timeout: 3000 }).trim();
-    const uncommitted = porcelain ? porcelain.split('\n').length : 0;
-    const recentCommits = execSync('git log -5 --oneline', { encoding: 'utf8', timeout: 3000 }).trim();
-    parts.push(`\nGit: ${branch} (${uncommitted} uncommitted file${uncommitted !== 1 ? 's' : ''})`);
-    if (recentCommits) {
-      parts.push(`Recent commits:\n${recentCommits}`);
-    }
-  } catch (_e) {
-    // Not a git repo or git not available — skip
-  }
-
-  // Read STATE.md if it exists
-  if (fs.existsSync(stateFile)) {
-    const state = fs.readFileSync(stateFile, 'utf8');
-
-    // Extract key sections
-    const position = extractSection(state, 'Current Position');
-    if (position) {
-      parts.push(`\nPosition:\n${position}`);
-    }
-
-    const blockers = extractSection(state, 'Blockers/Concerns');
-    if (blockers && !blockers.includes('None')) {
-      parts.push(`\nBlockers:\n${blockers}`);
-    }
-
-    const continuity = extractSection(state, 'Session Continuity');
-    if (continuity) {
-      parts.push(`\nLast Session:\n${continuity}`);
-    }
-
-    // Detect stale "Building" status — likely a crashed executor
-    const statusMatch = state.match(/\*{0,2}(?:Phase\s+)?Status\*{0,2}:\s*["']?(\w+)["']?/i);
-    if (statusMatch && statusMatch[1].toLowerCase() === 'building') {
-      try {
-        const stateStat = fs.statSync(stateFile);
-        const ageMs = Date.now() - stateStat.mtimeMs;
-        const ageMinutes = Math.round(ageMs / 60000);
-        if (ageMinutes > 30) {
-          parts.push(`\nWarning: STATE.md shows status "Building" but was last modified ${ageMinutes} minutes ago. This may indicate a crashed executor. Run /pbr:health to diagnose.`);
-          logHook('progress-tracker', 'SessionStart', 'stale-building', { ageMinutes });
-        }
-      } catch (_e) { /* best-effort */ }
-    }
-  } else {
-    parts.push('\nNo STATE.md found. Run /pbr:begin to initialize or /pbr:status to check.');
-  }
-
-  // Check for .continue-here.md files
-  const phasesDir = path.join(planningDir, 'phases');
-  if (fs.existsSync(phasesDir)) {
-    const continueFiles = findContinueFiles(phasesDir);
-    if (continueFiles.length > 0) {
-      parts.push(`\nPaused work found: ${continueFiles.join(', ')}`);
-      parts.push('Run /pbr:resume to pick up where you left off.');
-    }
-  }
-
-  // Check for config and validate
-  const config = configLoad(planningDir);
-  if (config) {
-    parts.push(`\nConfig: depth=${config.depth || 'standard'}, mode=${config.mode || 'interactive'}`);
-
-    // Validate config against schema (reuse already-loaded config)
-    const schemaPath = path.join(__dirname, 'config-schema.json');
-    if (fs.existsSync(schemaPath)) {
-      const { configValidate } = require('./pbr-tools');
-      const validation = configValidate(config);
-      if (validation.warnings.length > 0) {
-        parts.push(`\nConfig warnings: ${validation.warnings.join('; ')}`);
-      }
-      if (validation.errors.length > 0) {
-        parts.push(`\nConfig errors: ${validation.errors.join('; ')}`);
+  // Create session directory and clean stale sessions
+  if (sessionId) {
+    try {
+      ensureSessionDir(planningDir, sessionId);
+    } catch (_e) { /* non-fatal */ }
+    try {
+      const staleRemoved = cleanStaleSessions(planningDir);
+      if (staleRemoved.length > 0) {
+        logHook('progress-tracker', 'SessionStart', 'stale-sessions-removed', {
+          count: staleRemoved.length,
+          removed: staleRemoved.map(s => s.sessionId).join(', ')
+        });
       }
-    }
-  }
-
-  // Check for quick notes
-  const projectNotesDir = path.join(planningDir, 'notes');
-  const globalNotesDir = path.join(os.homedir(), '.claude', 'notes');
-  const projectNoteCount = countNotes(projectNotesDir);
-  const globalNoteCount = countNotes(globalNotesDir);
-  if (projectNoteCount > 0 || globalNoteCount > 0) {
-    const noteParts = [];
-    if (projectNoteCount > 0) noteParts.push(`${projectNoteCount} project`);
-    if (globalNoteCount > 0) noteParts.push(`${globalNoteCount} global`);
-    parts.push(`\nNotes: ${noteParts.join(', ')}. \`/pbr:note list\` to review.`);
+    } catch (_e) { /* non-fatal */ }
   }
 
-  // Check ROADMAP/STATE sync (S>M-2)
-  const roadmapFile = path.join(planningDir, 'ROADMAP.md');
-  if (fs.existsSync(stateFile) && fs.existsSync(roadmapFile)) {
+  // Detect other active sessions and build warning
+  let sessionWarning = '';
+  if (sessionId) {
     try {
-      const roadmap = fs.readFileSync(roadmapFile, 'utf8');
-      const state = fs.readFileSync(stateFile, 'utf8');
-
-      // Extract current phase from STATE.md
-      const phaseMatch = state.match(/Phase:\s*(\d+)\s+of\s+\d+/);
-      if (phaseMatch) {
-        const currentPhase = parseInt(phaseMatch[1], 10);
-        // Check if ROADMAP shows this phase as already verified/complete
-        const progressTable = roadmap.match(/## Progress[\s\S]*?\|[\s\S]*?(?=\n##|\s*$)/);
-        if (progressTable) {
-          const rows = progressTable[0].split('\n').filter(r => r.includes('|'));
-          for (const row of rows) {
-            const cols = row.split('|').map(c => c.trim()).filter(Boolean);
-            if (cols.length >= 4) {
-              const phaseNum = parseInt(cols[0], 10);
-              const status = cols[3] ? cols[3].toLowerCase() : '';
-              if (phaseNum === currentPhase && (status === 'verified' || status === 'complete')) {
-                parts.push(`\nWarning: STATE.md may be outdated — ROADMAP.md shows phase ${currentPhase} as ${status}.`);
-              }
-            }
+      const otherSessions = detectOtherSessions(planningDir, sessionId);
+      if (otherSessions.length > 0) {
+        // Read current phase from STATE.md for conflict detection context
+        let currentPhase = 'unknown';
+        try {
+          if (fs.existsSync(stateFile)) {
+            const stateContent = fs.readFileSync(stateFile, 'utf8');
+            const phaseMatch = stateContent.match(/Phase:\s*(\d+)\s+of\s+\d+/);
+            if (phaseMatch) currentPhase = phaseMatch[1];
           }
-        }
+        } catch (_e) { /* best-effort */ }
+
+        const warnings = otherSessions.map(s => {
+          const skillPart = s.skill ? `skill: ${s.skill}` : 'no active skill';
+          return `WARNING: Another PBR session is active (${skillPart}, phase: ${currentPhase}, age: ${s.age}min). Working on different phases is safe; same phase will conflict.`;
+        });
+        sessionWarning = '\n' + warnings.join('\n');
+        logHook('progress-tracker', 'SessionStart', 'other-sessions-detected', {
+          count: otherSessions.length,
+          sessions: otherSessions.map(s => s.sessionId).join(', ')
+        });
       }
-    } catch (_e) {
-      // Ignore parse errors
-    }
+    } catch (_e) { /* non-fatal */ }
   }
 
-  // Check for stale .auto-next signal (S>M-9)
-  const autoNextFile = path.join(planningDir, '.auto-next');
-  if (fs.existsSync(autoNextFile)) {
-    try {
-      const stats = fs.statSync(autoNextFile);
-      const ageMs = Date.now() - stats.mtimeMs;
-      const ageMinutes = Math.floor(ageMs / 60000);
-      if (ageMinutes > 10) {
-        parts.push(`\nWarning: Stale .auto-next signal found (${ageMinutes} minutes old). This may trigger an unexpected command. Consider deleting .planning/.auto-next.`);
-        logHook('progress-tracker', 'SessionStart', 'stale-auto-next', { ageMinutes });
-      }
-    } catch (_e) {
-      // Ignore errors
-    }
-  }
+  const context = buildContext(planningDir, stateFile);
 
-  // Hook health summary from recent log entries
-  const hookHealth = getHookHealthSummary(planningDir);
-  if (hookHealth) {
-    parts.push(`\n${hookHealth}`);
+  // Auto-launch dashboard if configured
+  const config = configLoad(planningDir);
+  if (config && config.dashboard && config.dashboard.auto_launch) {
+    tryLaunchDashboard(config.dashboard.port || 3000, planningDir, cwd);
   }
 
-  parts.push('\nAvailable commands: /pbr:status, /pbr:plan, /pbr:build, /pbr:review, /pbr:help');
-
-  return parts.join('\n');
-}
-
-function extractSection(content, heading) {
-  const regex = new RegExp(`##\\s+${escapeRegex(heading)}\\s*\\n([\\s\\S]*?)(?=\\n##\\s|$)`);
-  const match = content.match(regex);
-  if (!match) return null;
-  const section = match[1].trim();
-  // Return first 5 lines max
-  return section.split('\n').slice(0, 5).join('\n');
-}
-
-function escapeRegex(str) {
-  return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-}
-
-function findContinueFiles(dir) {
-  const results = [];
-  try {
-    const entries = fs.readdirSync(dir, { withFileTypes: true });
-    for (const entry of entries) {
-      const fullPath = path.join(dir, entry.name);
-      if (entry.isDirectory()) {
-        results.push(...findContinueFiles(fullPath));
-      } else if (entry.name.includes('.continue-here')) {
-        results.push(path.relative(dir, fullPath));
-      }
-    }
-  } catch (_e) {
-    // Ignore permission errors
+  // Auto-launch hook server
+  if (config) {
+    tryLaunchHookServer(config, planningDir);
   }
-  return results;
-}
 
-function countNotes(notesDir) {
+  // Write session-start timestamp for local-llm metrics correlation
+  // Primary: write to .session.json (unified session state)
+  // Legacy: also write .session-start file for session-cleanup.js backward compat
+  const sessionStart = new Date().toISOString();
+  try { sessionSave(planningDir, { sessionStart }, sessionId); } catch (_e) { /* non-fatal */ }
+  const sessionStartFile = path.join(planningDir, '.session-start');
   try {
-    if (!fs.existsSync(notesDir)) return 0;
-    const files = fs.readdirSync(notesDir).filter(f => f.endsWith('.md'));
-    let count = 0;
-    for (const file of files) {
-      const content = fs.readFileSync(path.join(notesDir, file), 'utf8');
-      if (!content.includes('promoted: true')) count++;
-    }
-    return count;
-  } catch (_e) {
-    return 0;
-  }
-}
+    fs.writeFileSync(sessionStartFile, sessionStart, 'utf8');
+  } catch (_e) { /* non-fatal */ }
 
-const FAILURE_DECISIONS = /^(block|error|warn|warning|block-coauthor|block-sensitive|unlink-failed)$/;
-const HOOK_HEALTH_MAX_ENTRIES = 50;
-
-function getHookHealthSummary(planningDir) {
-  const logPath = path.join(planningDir, 'logs', 'hooks.jsonl');
+  // Local LLM health check (advisory only -- never blocks SessionStart)
+  let llmContext = '';
   try {
-    if (!fs.existsSync(logPath)) return null;
-    const content = fs.readFileSync(logPath, 'utf8').trim();
-    if (!content) return null;
-
-    const lines = content.split('\n');
-    // Take only the last N entries
-    const recent = lines.slice(-HOOK_HEALTH_MAX_ENTRIES);
-
-    const failuresByHook = {};
-    let totalFailures = 0;
-
-    for (const line of recent) {
-      try {
-        const entry = JSON.parse(line);
-        if (entry.decision && FAILURE_DECISIONS.test(entry.decision)) {
-          const hookName = entry.hook || 'unknown';
-          failuresByHook[hookName] = (failuresByHook[hookName] || 0) + 1;
-          totalFailures++;
+    const rawLlmConfig = config && config.local_llm;
+    const llmConfig = resolveConfig(rawLlmConfig);
+    if (llmConfig.enabled) {
+      const health = await checkHealth(llmConfig);
+      if (health.available) {
+        llmContext = `\nLocal LLM: ${llmConfig.model} (${health.warm ? 'warm' : 'cold start'})`;
+        if (!health.warm) {
+          // Fire warm-up without awaiting -- 23s cold start must not block hook
+          warmUp(llmConfig);
         }
-      } catch (_e) {
-        // Skip malformed lines
+      } else if (health.reason !== 'disabled') {
+        llmContext = `\nLocal LLM: unavailable -- ${health.detail || health.reason}`;
       }
     }
+  } catch (_e) { /* graceful degradation -- never surface to user */ }
 
-    if (totalFailures === 0) return null;
-
-    // Sort hooks by failure count descending
-    const sorted = Object.entries(failuresByHook)
-      .sort((a, b) => b[1] - a[1])
-      .map(([hook, count]) => `${hook}: ${count}`)
-      .join(', ');
-
-    return `Hook health: ${totalFailures} failure${totalFailures !== 1 ? 's' : ''} in last ${recent.length} entries (${sorted})`;
-  } catch (_e) {
-    return null;
-  }
-}
-
-/**
- * Attempt to launch the dashboard in a detached background process.
- * Checks if the port is already in use before spawning.
- */
-function tryLaunchDashboard(port, _planningDir, projectDir) {
-  const net = require('net');
-  const { spawn } = require('child_process');
-
-  // Quick port probe — if something is already listening, skip launch
-  const probe = net.createConnection({ port, host: '127.0.0.1' });
-  probe.on('connect', () => {
-    probe.destroy();
-    logHook('progress-tracker', 'SessionStart', 'dashboard-already-running', { port });
-  });
-  probe.on('error', () => {
-    // Port is free — launch dashboard
-    const cliPath = path.join(__dirname, '..', 'dashboard', 'bin', 'cli.js');
-    if (!fs.existsSync(cliPath)) {
-      logHook('progress-tracker', 'SessionStart', 'dashboard-cli-missing', { cliPath });
-      return;
+  // Enrich context with recent session activity from hook server (advisory, fail-open)
+  let enrichedContext = '';
+  try {
+    const enriched = await getEnrichedContext(config, planningDir);
+    if (enriched && typeof enriched === 'object' && Array.isArray(enriched.recentEvents)) {
+      const skillList = Array.isArray(enriched.activeSkillHistory) ? enriched.activeSkillHistory.join(', ') || 'none' : 'none';
+      enrichedContext = `\n## Recent Session Activity\n- ${enriched.recentEvents.length} recent events tracked\n- Active skills: ${skillList}`;
+      if (Array.isArray(enriched.advisoryMessages) && enriched.advisoryMessages.length > 0) {
+        const lastThree = enriched.advisoryMessages.slice(-3);
+        enrichedContext += '\n- Recent advisories: ' + lastThree.map(m => m.additionalContext || '').filter(Boolean).join(' | ');
+      }
     }
+  } catch (_e) { /* graceful degradation */ }
 
-    try {
-      const child = spawn(process.execPath, [cliPath, '--dir', projectDir, '--port', String(port)], {
-        detached: true,
-        stdio: 'ignore',
-        cwd: projectDir
-      });
-      child.unref();
-      logHook('progress-tracker', 'SessionStart', 'dashboard-launched', { port, pid: child.pid });
-    } catch (e) {
-      logHook('progress-tracker', 'SessionStart', 'dashboard-launch-error', { error: e.message });
-    }
-  });
+  if (context) {
+    const output = {
+      additionalContext: context + sessionWarning + llmContext + enrichedContext
+    };
+    process.stdout.write(JSON.stringify(output));
+    logHook('progress-tracker', 'SessionStart', 'injected', { hasState: true });
+    logEvent('workflow', 'session-start', { hasState: true });
+  } else {
+    logHook('progress-tracker', 'SessionStart', 'skipped', { hasState: false });
+    logEvent('workflow', 'session-start', { hasState: false });
+  }
 
-  // Don't let the probe keep the process alive
-  probe.unref();
+  process.exit(0);
 }
 
-// Exported for testing
-module.exports = { getHookHealthSummary, FAILURE_DECISIONS, HOOK_HEALTH_MAX_ENTRIES, tryLaunchDashboard };
+// Exported for testing — re-exports from extracted modules
+module.exports = { buildEnhancedBriefing, buildContext, getHookHealthSummary, checkLearningsDeferrals, getEnrichedContext, detectOtherSessions, getIntelContext, getIntelStalenessWarning, getDecisionBriefing, getNegativeKnowledgeBriefing, FAILURE_DECISIONS, HOOK_HEALTH_MAX_ENTRIES, tryLaunchDashboard, tryLaunchHookServer };
 
-main();
+if (require.main === module || process.argv[1] === __filename) { main().catch(() => {}); }

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

@@ -0,0 +1,179 @@
+#!/usr/bin/env node
+
+/**
+ * quick-status.js -- Lightweight status snapshot for Plan-Build-Run.
+ *
+ * Reads ONLY STATE.md and ROADMAP.md to produce a 10-line plain text summary.
+ * Designed to complete in <2 seconds with minimal I/O.
+ *
+ * Usage:
+ *   node quick-status.js                    # standalone
+ *   node pbr-tools.js quick-status          # via dispatcher
+ *
+ * Programmatic:
+ *   const { quickStatus } = require('./quick-status');
+ *   const { text, data } = quickStatus(planningDir);
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { parseYamlFrontmatter } = require('./lib/core');
+
+/**
+ * Parse milestone information from ROADMAP.md content.
+ * Returns { activeName, activeVersion, phaseCount, shippedCount }.
+ */
+function parseRoadmapInfo(content) {
+  if (!content) {
+    return { activeName: 'none', activeVersion: '', phaseCount: 0, shippedCount: 0 };
+  }
+
+  const normalized = content.replace(/\r\n/g, '\n');
+  const lines = normalized.split('\n');
+
+  let activeName = 'none';
+  let activeVersion = '';
+  let phaseCount = 0;
+  let shippedCount = 0;
+  let inActiveMilestone = false;
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+
+    // Detect ## Milestone: Name (vX.Y) headings
+    const msMatch = line.match(/^##\s+Milestone[:\s]+(.+)/i);
+    if (msMatch) {
+      const raw = msMatch[1].trim();
+      const isCompleted = /COMPLETED/i.test(raw) || /SHIPPED/i.test(raw);
+
+      if (isCompleted) {
+        shippedCount++;
+        inActiveMilestone = false;
+        continue;
+      }
+
+      // This is an active milestone
+      const versionMatch = raw.match(/\(?(v[\d.]+)\)?/i);
+      activeVersion = versionMatch ? versionMatch[1] : '';
+      activeName = raw
+        .replace(/\(v[\d.]+\)/i, '')
+        .replace(/\bCOMPLETED\b/i, '')
+        .replace(/\bSHIPPED\b/i, '')
+        .replace(/[[\]]/g, '')
+        .replace(/--?\s*$/, '')
+        .trim()
+        .replace(/\s+/g, ' ');
+      inActiveMilestone = true;
+      phaseCount = 0;
+      continue;
+    }
+
+    // Count phases under active milestone
+    if (inActiveMilestone) {
+      // Stop at next ## heading that isn't a milestone phase
+      if (/^##\s/.test(line) && !msMatch) {
+        inActiveMilestone = false;
+        continue;
+      }
+      if (/^###\s+Phase\s+\d+/i.test(line)) {
+        phaseCount++;
+      }
+    }
+  }
+
+  // Also count shipped milestones from the summary table
+  // Table rows like: | vX.Y | Name | SHIPPED | date |
+  const tableShipped = lines.filter(l => /^\|.*SHIPPED/i.test(l)).length;
+  if (tableShipped > shippedCount) {
+    shippedCount = tableShipped;
+  }
+
+  return { activeName, activeVersion, phaseCount, shippedCount };
+}
+
+/**
+ * Produce a lightweight 10-line status snapshot.
+ *
+ * @param {string} planningDir - Path to .planning/ directory
+ * @returns {{ text: string, data: object }}
+ */
+function quickStatus(planningDir) {
+  // Resolve planningDir from env if not provided
+  if (!planningDir) {
+    let cwd = process.env.PBR_PROJECT_ROOT || process.cwd();
+    const msysMatch = cwd.match(/^\/([a-zA-Z])\/(.*)/);
+    if (msysMatch) cwd = msysMatch[1] + ':' + path.sep + msysMatch[2].replace(/\//g, path.sep);
+    planningDir = path.join(cwd, '.planning');
+  }
+
+  // --- Read STATE.md ---
+  let stateFm = {};
+  const statePath = path.join(planningDir, 'STATE.md');
+  try {
+    if (fs.existsSync(statePath)) {
+      const stateContent = fs.readFileSync(statePath, 'utf8');
+      stateFm = parseYamlFrontmatter(stateContent) || {};
+    }
+  } catch (_e) { /* graceful fallback */ }
+
+  const currentPhase = stateFm.current_phase != null ? stateFm.current_phase : 'unknown';
+  const phaseSlug = stateFm.phase_slug || stateFm.phase_name || 'unknown';
+  const status = stateFm.status || 'unknown';
+  const plansTotal = stateFm.plans_total != null ? stateFm.plans_total : 0;
+  const plansComplete = stateFm.plans_complete != null ? stateFm.plans_complete : 0;
+  const progressPercent = stateFm.progress_percent != null ? stateFm.progress_percent : 0;
+  const lastActivity = stateFm.last_activity || 'none';
+
+  // --- Read ROADMAP.md ---
+  let roadmapInfo = { activeName: 'none', activeVersion: '', phaseCount: 0, shippedCount: 0 };
+  const roadmapPath = path.join(planningDir, 'ROADMAP.md');
+  try {
+    if (fs.existsSync(roadmapPath)) {
+      const roadmapContent = fs.readFileSync(roadmapPath, 'utf8');
+      roadmapInfo = parseRoadmapInfo(roadmapContent);
+    }
+  } catch (_e) { /* graceful fallback */ }
+
+  // --- Build data object ---
+  const data = {
+    current_phase: currentPhase,
+    phase_slug: phaseSlug,
+    status,
+    plans_total: plansTotal,
+    plans_complete: plansComplete,
+    progress_percent: progressPercent,
+    milestone_name: roadmapInfo.activeName,
+    milestone_version: roadmapInfo.activeVersion,
+    phases_in_milestone: roadmapInfo.phaseCount,
+    milestones_shipped: roadmapInfo.shippedCount,
+    last_activity: lastActivity
+  };
+
+  // --- Build 10-line text output ---
+  const milestoneLabel = roadmapInfo.activeVersion
+    ? `${roadmapInfo.activeName} (${roadmapInfo.activeVersion})`
+    : roadmapInfo.activeName;
+
+  const text = [
+    'PBR Quick Status',
+    '================',
+    `Phase: ${currentPhase} (${phaseSlug})`,
+    `Status: ${status}`,
+    `Progress: ${plansComplete}/${plansTotal} plans (${progressPercent}%)`,
+    `Milestone: ${milestoneLabel}`,
+    `Phases in milestone: ${roadmapInfo.phaseCount}`,
+    `Milestones shipped: ${roadmapInfo.shippedCount}`,
+    `Last activity: ${lastActivity}`,
+    '================'
+  ].join('\n');
+
+  return { text, data };
+}
+
+// --- CLI entry point ---
+if (require.main === module || process.argv[1] === __filename) {
+  const result = quickStatus();
+  process.stdout.write(result.text + '\n');
+}
+
+module.exports = { quickStatus };