@sienklogic/plan-build-run 2.19.0 → 2.19.2

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

@@ -0,0 +1,173 @@
+#!/usr/bin/env node
+
+/**
+ * SessionStart hook: Auto-detects .planning/ directory and injects
+ * project state as additionalContext.
+ *
+ * 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 { logHook } = require('./hook-logger');
+const { logEvent } = require('./event-logger');
+const { configLoad, sessionSave } = require('./pbr-tools');
+const { ensureSessionDir, cleanStaleSessions } = require('./lib/core');
+
+// 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 {};
+}
+
+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');
+
+  // Not a Plan-Build-Run project
+  if (!fs.existsSync(planningDir)) {
+    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, sessionId);
+
+  // Reset session phase counter for new session
+  const { resetTracker } = require('./session-tracker');
+  resetTracker(planningDir, sessionId);
+
+  // 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(', ')
+        });
+      }
+    } catch (_e) { /* non-fatal */ }
+  }
+
+  // Detect other active sessions and build warning
+  let sessionWarning = '';
+  if (sessionId) {
+    try {
+      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) { /* non-fatal */ }
+  }
+
+  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);
+  }
+
+  // Auto-launch hook server
+  if (config) {
+    tryLaunchHookServer(config, planningDir);
+  }
+
+  // Write session-start timestamp to .session.json (unified session state)
+  const sessionStart = new Date().toISOString();
+  try { sessionSave(planningDir, { sessionStart }, sessionId); } catch (_e) { /* non-fatal */ }
+
+
+  // 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 */ }
+
+  if (context) {
+    const output = {
+      additionalContext: context + sessionWarning + 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 });
+  }
+
+  process.exit(0);
+}
+
+// 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 };
+
+if (require.main === module || process.argv[1] === __filename) { main().catch(() => {}); }

package/plugins/pbr/dist/prompt-guard.js

@@ -0,0 +1,114 @@
+#!/usr/bin/env node
+
+/**
+ * PreToolUse check: Advisory scan of .planning/ writes for prompt injection patterns.
+ *
+ * Scans content being written to .planning/ files for common prompt injection
+ * techniques. ADVISORY ONLY — never blocks, always exits 0.
+ *
+ * Pattern categories:
+ *   1. INSTRUCTION_OVERRIDE — "ignore previous instructions" etc.
+ *   2. ROLE_MANIPULATION — "you are now a" etc.
+ *   3. SYSTEM_PROMPT_EXTRACTION — "repeat your system prompt" etc.
+ *   4. XML_TAG_MIMICKING — fake <system>, <tool_result> etc.
+ *   5. INVISIBLE_UNICODE — zero-width chars, directional overrides
+ *
+ * Called by pre-write-dispatch.js — not wired directly in hooks.json.
+ *
+ * Exit codes:
+ *   0 = always (advisory only, never blocks)
+ */
+
+const { logHook } = require('./hook-logger');
+
+/**
+ * Paths that legitimately contain XML examples and tag references.
+ * These are excluded from XML_TAG_MIMICKING checks.
+ */
+const XML_ALLOWLIST_SEGMENTS = ['/skills/', '/agents/', '/templates/', '/references/'];
+
+const PATTERN_CATEGORIES = {
+  INSTRUCTION_OVERRIDE: [
+    /ignore\s+(all\s+)?previous\s+instructions/i,
+    /disregard\s+(all\s+)?prior/i,
+    /forget\s+everything\s+(above|before|you)/i,
+    /do\s+not\s+follow\s+(the|your)\s+(previous|above|prior)/i,
+  ],
+  ROLE_MANIPULATION: [
+    /you\s+are\s+now\s+a/i,
+    /act\s+as\s+(a|an|if)\b/i,
+    /pretend\s+(to\s+be|you\s+are)/i,
+    /from\s+now\s+on[,\s]+(you|your)\s+(are|role)/i,
+  ],
+  SYSTEM_PROMPT_EXTRACTION: [
+    /repeat\s+your\s+(system\s+)?prompt/i,
+    /show\s+me\s+your\s+(instructions|system\s+prompt)/i,
+    /what\s+(are|is)\s+your\s+(system\s+)?instructions/i,
+    /output\s+your\s+(entire\s+)?(system\s+)?prompt/i,
+  ],
+  XML_TAG_MIMICKING: [
+    /<\/?system>/,
+    /<\/?tool_result>/,
+    /<\/?function_calls>/,
+    /<\/?antml:/,
+    /<\/?human>/,
+    /<\/?assistant>/,
+  ],
+  INVISIBLE_UNICODE: [
+    /\u200B|\u200C|\u200D|\uFEFF/,
+    /[\u202A-\u202E]/,
+    /[\u2066-\u2069]/,
+  ],
+};
+
+/**
+ * Scan content written to .planning/ for prompt injection patterns.
+ * @param {Object} data - Parsed hook input (tool_input, etc.)
+ * @returns {null|{exitCode: number, output: Object}} null if clean, advisory result otherwise
+ */
+function checkPromptInjection(data) {
+  const filePath = data.tool_input?.file_path || data.tool_input?.path || '';
+  if (!filePath) return null;
+
+  const normalized = filePath.replace(/\\/g, '/');
+
+  // Only scan .planning/ writes
+  if (!normalized.includes('.planning/')) return null;
+
+  // Get content from Write (content) or Edit (new_string)
+  const content = data.tool_input?.content || data.tool_input?.new_string || '';
+  if (!content) return null;
+
+  // Check if this path is allowlisted for XML tag patterns
+  const isXmlAllowlisted = XML_ALLOWLIST_SEGMENTS.some((seg) => normalized.includes(seg));
+
+  const matches = [];
+
+  for (const [category, patterns] of Object.entries(PATTERN_CATEGORIES)) {
+    // Skip XML tag check for allowlisted paths
+    if (category === 'XML_TAG_MIMICKING' && isXmlAllowlisted) continue;
+
+    for (const pattern of patterns) {
+      if (pattern.test(content)) {
+        matches.push({ category, pattern: pattern.source });
+        break; // One match per category is enough
+      }
+    }
+  }
+
+  if (matches.length === 0) return null;
+
+  const categories = [...new Set(matches.map((m) => m.category))].join(', ');
+  const file = normalized.split('/').pop();
+
+  logHook('prompt-guard', 'PreToolUse', 'warn', { file, categories });
+
+  return {
+    exitCode: 0,
+    output: {
+      additionalContext: `[pbr:prompt-guard] Advisory: detected ${matches.length} potential prompt injection pattern(s) in .planning/ write: ${categories}. Review content for safety.`
+    }
+  };
+}
+
+module.exports = { checkPromptInjection, PATTERN_CATEGORIES };

package/plugins/pbr/dist/prompt-routing.js

@@ -0,0 +1,209 @@
+#!/usr/bin/env node
+
+/**
+ * UserPromptSubmit hook: Detects PBR-relevant intent in user prompts
+ * and injects routing hints when the user isn't using /pbr:* commands.
+ *
+ * Only activates for PBR projects (has .planning/ directory).
+ * Skips prompts that already start with /pbr: or other slash commands.
+ *
+ * Intent detection patterns:
+ *   - Bug/error reports → suggests /pbr:debug
+ *   - Feature requests or task descriptions → suggests /pbr:do
+ *   - Planning/architecture discussion → suggests /pbr:explore
+ *   - Status/progress queries → suggests /pbr:progress
+ *
+ * Exit codes:
+ *   0 = always (advisory only, never blocks user input)
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { logHook } = require('./hook-logger');
+
+// NL routing: try to load classifyIntent from intent-router.cjs
+let classifyIntent = null;
+try {
+  const intentRouter = require(path.join(__dirname, 'intent-router.cjs'));
+  classifyIntent = intentRouter.classifyIntent;
+} catch (_e) {
+  // intent-router.cjs not available — NL routing disabled gracefully
+}
+
+/**
+ * Load NL routing config from .planning/config.json.
+ * Returns { nlEnabled: boolean } based on features.natural_language_routing toggle.
+ * Defaults to true if config missing or toggle absent.
+ */
+function loadNLConfig(planningDir) {
+  try {
+    const configPath = path.join(planningDir, 'config.json');
+    if (!fs.existsSync(configPath)) return { nlEnabled: true };
+    const config = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+    const features = config.features || {};
+    return { nlEnabled: features.natural_language_routing !== false };
+  } catch (_e) {
+    return { nlEnabled: true };
+  }
+}
+
+/**
+ * Intent patterns ranked by specificity. First match wins.
+ * Each pattern maps user intent to a PBR command suggestion.
+ */
+const INTENT_PATTERNS = [
+  {
+    pattern: /\b(bug|error|crash|exception|stack\s*trace|failing|broken|doesn'?t\s+work|not\s+working)\b/i,
+    command: '/pbr:debug',
+    hint: 'This looks like a bug report. Use /pbr:debug for systematic investigation with hypothesis tracking.'
+  },
+  {
+    pattern: /\b(status|progress|where\s+(are|were)\s+we|what'?s\s+next|current\s+phase)\b/i,
+    command: '/pbr:progress',
+    hint: 'Use /pbr:progress to see project status and next steps.'
+  },
+  {
+    pattern: /\b(explore|research|how\s+(does|do|should|would)|what\s+if|compare|pros\s+and\s+cons|trade-?offs?)\b/i,
+    command: '/pbr:explore',
+    hint: 'This sounds exploratory. Use /pbr:explore for Socratic investigation.'
+  },
+  {
+    pattern: /\b(refactor|migrate|redesign|architect|restructure|overhaul|rewrite)\b/i,
+    command: '/pbr:plan-phase add',
+    hint: 'Complex work like this benefits from full planning. Use /pbr:plan-phase add.'
+  },
+  {
+    // Generic task — anything actionable that doesn't match above
+    pattern: /\b(add|create|implement|build|write|update|change|fix|remove|delete|set\s+up|configure|install)\b/i,
+    command: '/pbr:do',
+    hint: 'Use /pbr:do to auto-route this to the right PBR skill.'
+  }
+];
+
+/**
+ * Analyze a user prompt and return a routing suggestion if applicable.
+ * Returns null if no suggestion is warranted.
+ *
+ * @param {string} prompt - The user's raw prompt text
+ * @param {string} planningDir - Path to .planning/ directory
+ * @returns {{ command: string, hint: string }|null}
+ */
+function analyzePrompt(prompt, planningDir) {
+  if (!prompt || typeof prompt !== 'string') return null;
+
+  const trimmed = prompt.trim();
+
+  // Skip slash commands — user already knows what they want
+  if (trimmed.startsWith('/')) return null;
+
+  // Skip very short prompts (likely follow-up responses like "yes", "ok", "3")
+  if (trimmed.length < 15) return null;
+
+  // Skip if .planning/ doesn't exist (not a PBR project)
+  if (!fs.existsSync(planningDir)) return null;
+
+  // Skip if no active PBR project (no STATE.md)
+  if (!fs.existsSync(path.join(planningDir, 'STATE.md'))) return null;
+
+  // NL routing: use classifyIntent when available and enabled
+  const { nlEnabled } = loadNLConfig(planningDir);
+  if (nlEnabled && classifyIntent) {
+    try {
+      const hasRoadmap = fs.existsSync(path.join(planningDir, 'ROADMAP.md'));
+      const result = classifyIntent(trimmed, { hasRoadmap });
+
+      if (result && result.confidence >= 0.7) {
+        // Map intent-router route names to /pbr: commands
+        const routeCommandMap = {
+          'debug': '/pbr:debug',
+          'explore': '/pbr:explore',
+          'plan-phase': '/pbr:plan-phase add',
+          'quick': '/pbr:do',
+          'note': '/pbr:note',
+          'verify-work': '/pbr:review'
+        };
+        const command = routeCommandMap[result.route] || '/pbr:do';
+        return {
+          command,
+          hint: `This looks like a ${result.route} task. Consider using /pbr:do for automatic routing, or ${command} directly.`,
+          nlRoute: { route: result.route, confidence: result.confidence }
+        };
+      }
+      // Low confidence from classifyIntent — fall through to pattern matching
+    } catch (_e) {
+      // classifyIntent error — fall through to pattern matching
+    }
+  }
+
+  // Fallback: pattern-based routing (always available)
+  for (const intent of INTENT_PATTERNS) {
+    if (intent.pattern.test(trimmed)) {
+      return { command: intent.command, hint: intent.hint };
+    }
+  }
+
+  return null;
+}
+
+function main() {
+  let input = '';
+
+  process.stdin.setEncoding('utf8');
+  process.stdin.on('data', (chunk) => { input += chunk; });
+  process.stdin.on('end', () => {
+    try {
+      const data = JSON.parse(input);
+      const prompt = data.prompt || data.user_prompt || data.content || '';
+      const cwd = data.cwd || process.env.PBR_PROJECT_ROOT || process.cwd();
+      const planningDir = path.join(cwd, '.planning');
+
+      const suggestion = analyzePrompt(prompt, planningDir);
+
+      if (suggestion) {
+        logHook('prompt-routing', 'UserPromptSubmit', 'suggest', {
+          command: suggestion.command
+        });
+        process.stdout.write(JSON.stringify({
+          additionalContext: `[pbr] ${suggestion.hint}\n\`${suggestion.command}\``
+        }));
+      }
+
+      process.exit(0);
+    } catch (_e) {
+      // Never block on errors
+      process.stdout.write(JSON.stringify({ additionalContext: '⚠ [PBR] prompt-routing failed: ' + _e.message }));
+      process.exit(0);
+    }
+  });
+}
+
+/**
+ * HTTP handler for hook-server.js.
+ * @param {Object} reqBody - { event, tool, data, planningDir }
+ * @returns {{ additionalContext: string }|null}
+ */
+function handleHttp(reqBody) {
+  try {
+    const data = reqBody.data || {};
+    const prompt = data.prompt || data.user_prompt || data.content || '';
+    const planningDir = reqBody.planningDir || path.join(process.cwd(), '.planning');
+
+    const suggestion = analyzePrompt(prompt, planningDir);
+    if (suggestion) {
+      logHook('prompt-routing', 'UserPromptSubmit', 'suggest', {
+        command: suggestion.command
+      });
+      return {
+        additionalContext: `[pbr] ${suggestion.hint}\n\`${suggestion.command}\``
+      };
+    }
+  } catch (_e) {
+    // Never propagate
+  }
+  return null;
+}
+
+module.exports = { analyzePrompt, handleHttp, INTENT_PATTERNS };
+if (require.main === module || process.argv[1] === __filename) { main(); }

package/plugins/pbr/dist/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 };