@sienklogic/plan-build-run 2.1.0 → 2.1.1

package/plugins/pbr/scripts/lib/state.js

@@ -0,0 +1,534 @@
+/**
+ * lib/state.js — STATE.md operations for Plan-Build-Run tools.
+ *
+ * Handles loading, parsing, updating, patching, and advancing STATE.md.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const {
+  parseYamlFrontmatter,
+  findFiles,
+  lockedFileUpdate,
+  calculateProgress,
+  determinePhaseStatus
+} = require('./core');
+
+// --- Parsers ---
+
+function parseStateMd(content) {
+  // Normalize CRLF to LF at parse boundary for cross-platform support
+  const normalized = content.replace(/\r\n/g, '\n');
+  const result = {
+    current_phase: null,
+    phase_name: null,
+    progress: null,
+    status: null,
+    line_count: normalized.split('\n').length,
+    format: 'legacy' // 'legacy' or 'frontmatter'
+  };
+
+  // Check for YAML frontmatter (version 2 format)
+  const frontmatter = parseYamlFrontmatter(normalized);
+  if (frontmatter.version === 2 || frontmatter.current_phase !== undefined) {
+    result.format = 'frontmatter';
+    result.current_phase = frontmatter.current_phase || null;
+    result.phase_name = frontmatter.phase_slug || frontmatter.phase_name || null;
+    result.status = frontmatter.status || null;
+    result.progress = frontmatter.progress_percent !== undefined ? frontmatter.progress_percent : null;
+    result.plans_total = frontmatter.plans_total || null;
+    result.plans_complete = frontmatter.plans_complete || null;
+    result.last_activity = frontmatter.last_activity || null;
+    result.last_command = frontmatter.last_command || null;
+    result.blockers = frontmatter.blockers || [];
+    return result;
+  }
+
+  // Legacy regex-based parsing (version 1 format, no frontmatter)
+  // DEPRECATED (2026-02): v1 STATE.md format (no YAML frontmatter) is deprecated.
+  // New projects should use v2 (frontmatter) format, generated by /pbr:setup.
+  // v1 support will be removed in a future major version.
+  process.stderr.write('[pbr] WARNING: STATE.md uses legacy v1 format. Run /pbr:setup to migrate to v2 format.\n');
+  // Extract "Phase: N of M"
+  const phaseMatch = normalized.match(/Phase:\s*(\d+)\s+of\s+(\d+)/);
+  if (phaseMatch) {
+    result.current_phase = parseInt(phaseMatch[1], 10);
+    result.total_phases = parseInt(phaseMatch[2], 10);
+  }
+
+  // Extract phase name (line after "Phase:")
+  const nameMatch = normalized.match(/--\s+(.+?)(?:\n|$)/);
+  if (nameMatch) {
+    result.phase_name = nameMatch[1].trim();
+  }
+
+  // Extract progress percentage
+  const progressMatch = normalized.match(/(\d+)%/);
+  if (progressMatch) {
+    result.progress = parseInt(progressMatch[1], 10);
+  }
+
+  // Extract plan status
+  const statusMatch = normalized.match(/Status:\s*(.+?)(?:\n|$)/i);
+  if (statusMatch) {
+    result.status = statusMatch[1].trim();
+  }
+
+  return result;
+}
+
+// --- Mutation helpers ---
+
+/**
+ * Update a field in legacy (non-frontmatter) STATE.md content.
+ * Pure function: content in, content out.
+ */
+function updateLegacyStateField(content, field, value) {
+  const lines = content.replace(/\r\n/g, '\n').split('\n');
+
+  switch (field) {
+    case 'current_phase': {
+      const idx = lines.findIndex(l => /Phase:\s*\d+\s+of\s+\d+/.test(l));
+      if (idx !== -1) {
+        lines[idx] = lines[idx].replace(/(Phase:\s*)\d+/, (_, prefix) => `${prefix}${value}`);
+      }
+      break;
+    }
+    case 'status': {
+      const idx = lines.findIndex(l => /^Status:/i.test(l));
+      if (idx !== -1) {
+        lines[idx] = `Status: ${value}`;
+      } else {
+        const phaseIdx = lines.findIndex(l => /Phase:/.test(l));
+        if (phaseIdx !== -1) {
+          lines.splice(phaseIdx + 1, 0, `Status: ${value}`);
+        } else {
+          lines.push(`Status: ${value}`);
+        }
+      }
+      break;
+    }
+    case 'plans_complete': {
+      const idx = lines.findIndex(l => /Plan:\s*\d+\s+of\s+\d+/.test(l));
+      if (idx !== -1) {
+        lines[idx] = lines[idx].replace(/(Plan:\s*)\d+/, (_, prefix) => `${prefix}${value}`);
+      }
+      break;
+    }
+    case 'last_activity': {
+      const idx = lines.findIndex(l => /^Last Activity:/i.test(l));
+      if (idx !== -1) {
+        lines[idx] = `Last Activity: ${value}`;
+      } else {
+        const statusIdx = lines.findIndex(l => /^Status:/i.test(l));
+        if (statusIdx !== -1) {
+          lines.splice(statusIdx + 1, 0, `Last Activity: ${value}`);
+        } else {
+          lines.push(`Last Activity: ${value}`);
+        }
+      }
+      break;
+    }
+  }
+
+  return lines.join('\n');
+}
+
+/**
+ * Update a field in YAML frontmatter content.
+ * Pure function: content in, content out.
+ */
+function updateFrontmatterField(content, field, value) {
+  const match = content.match(/^(---\s*\n)([\s\S]*?)(\n---)/);
+  if (!match) return content;
+
+  const before = match[1];
+  let yaml = match[2];
+  const after = match[3];
+  const rest = content.slice(match[0].length);
+
+  // Format value: integers stay bare, strings get quotes
+  const isNum = /^\d+$/.test(String(value));
+  const formatted = isNum ? value : `"${value}"`;
+
+  const fieldRegex = new RegExp(`^(${field})\\s*:.*$`, 'm');
+  if (fieldRegex.test(yaml)) {
+    yaml = yaml.replace(fieldRegex, () => `${field}: ${formatted}`);
+  } else {
+    yaml = yaml + `\n${field}: ${formatted}`;
+  }
+
+  return before + yaml + after + rest;
+}
+
+// --- Body sync ---
+
+/**
+ * Build a text progress bar: [████░░░░░░░░░░░░░░░░] 20%
+ * @param {number} pct - Percentage 0-100
+ * @returns {string}
+ */
+function buildProgressBar(pct) {
+  const width = 20;
+  const filled = Math.round((pct / 100) * width);
+  const empty = width - filled;
+  return `[${'█'.repeat(filled)}${'░'.repeat(empty)}] ${pct}%`;
+}
+
+/**
+ * After updating a frontmatter field, also update the corresponding body line
+ * so both representations stay in sync. Pure function: content in, content out.
+ *
+ * Field-to-body mapping:
+ *   status          → "Status: {value}"
+ *   plans_complete  → "Plan: {N} of ..." (replaces the number before "of")
+ *   progress_percent→ "Progress: [{bar}] {N}%"
+ *   last_activity   → "Last activity: {value}"
+ *   current_phase   → "Phase: {N} of ..." (replaces the number before "of")
+ *   phase_slug      → "Phase: N of M ({Name})" (replaces the parenthesized name)
+ *
+ * Fields without body equivalents (last_command, blockers) are no-ops.
+ *
+ * @param {string} content - Full STATE.md content (frontmatter already updated)
+ * @param {string} field - The field that was updated
+ * @param {string} value - The new value
+ * @returns {string} Content with body line also updated
+ */
+function syncBodyLine(content, field, value) {
+  switch (field) {
+    case 'status': {
+      const display = String(value).replace(/_/g, ' ').replace(/\b\w/g, c => c.toUpperCase());
+      return content.replace(/^Status:\s*.+/m, `Status: ${display}`);
+    }
+    case 'plans_complete': {
+      return content.replace(/^(Plan:\s*)\d+/m, `$1${value}`);
+    }
+    case 'plans_total': {
+      return content.replace(/^(Plan:\s*\d+\s+of\s+)\d+/m, `$1${value}`);
+    }
+    case 'progress_percent': {
+      const pct = parseInt(value, 10);
+      if (isNaN(pct)) return content;
+      return content.replace(/^Progress:\s*.+/m, `Progress: ${buildProgressBar(pct)}`);
+    }
+    case 'last_activity': {
+      return content.replace(/^(Last activity:\s*).+/im, `$1${value}`);
+    }
+    case 'current_phase': {
+      return content.replace(/^(Phase:\s*)\d+/m, `$1${value}`);
+    }
+    case 'phase_slug': {
+      const name = String(value).replace(/-/g, ' ').replace(/\b\w/g, c => c.toUpperCase());
+      // Replace "(OldName)" or "-- OldName" in the Phase line
+      const withParens = content.replace(/^(Phase:\s*\d+\s+of\s+\d+\s*)\(.*?\)/m, `$1(${name})`);
+      if (withParens !== content) return withParens;
+      return content.replace(/^(Phase:\s*\d+\s+of\s+\d+\s*)--\s*.+/m, `$1-- ${name}`);
+    }
+    default:
+      return content;
+  }
+}
+
+// --- Commands ---
+
+/**
+ * Load full project state from .planning/ directory.
+ *
+ * @param {string} [planningDir] - Path to .planning directory
+ * @returns {object} Full state object
+ */
+function stateLoad(planningDir) {
+  const dir = planningDir || path.join(process.env.PBR_PROJECT_ROOT || process.cwd(), '.planning');
+  const { parseRoadmapMd } = require('./roadmap');
+
+  const result = {
+    exists: false,
+    config: null,
+    state: null,
+    roadmap: null,
+    phase_count: 0,
+    current_phase: null,
+    progress: null
+  };
+
+  if (!fs.existsSync(dir)) {
+    return result;
+  }
+  result.exists = true;
+
+  // Load config.json
+  const configPath = path.join(dir, 'config.json');
+  if (fs.existsSync(configPath)) {
+    try {
+      result.config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+    } catch (_) {
+      result.config = { _error: 'Failed to parse config.json' };
+    }
+  }
+
+  // Load STATE.md
+  const statePath = path.join(dir, 'STATE.md');
+  if (fs.existsSync(statePath)) {
+    const content = fs.readFileSync(statePath, 'utf8');
+    result.state = parseStateMd(content);
+  }
+
+  // Load ROADMAP.md
+  const roadmapPath = path.join(dir, 'ROADMAP.md');
+  if (fs.existsSync(roadmapPath)) {
+    const content = fs.readFileSync(roadmapPath, 'utf8');
+    result.roadmap = parseRoadmapMd(content);
+    result.phase_count = result.roadmap.phases.length;
+  }
+
+  // Extract current phase
+  if (result.state && result.state.current_phase) {
+    result.current_phase = result.state.current_phase;
+  }
+
+  // Calculate progress
+  result.progress = calculateProgress(dir);
+
+  return result;
+}
+
+/**
+ * Recalculate progress from filesystem.
+ *
+ * @param {string} [planningDir] - Path to .planning directory
+ * @returns {object} Progress object
+ */
+function stateCheckProgress(planningDir) {
+  const dir = planningDir || path.join(process.env.PBR_PROJECT_ROOT || process.cwd(), '.planning');
+  const phasesDir = path.join(dir, 'phases');
+  if (!fs.existsSync(phasesDir)) {
+    return { phases: [], total_plans: 0, completed_plans: 0, percentage: 0 };
+  }
+
+  const phases = [];
+  let totalPlans = 0;
+  let completedPlans = 0;
+
+  const entries = fs.readdirSync(phasesDir, { withFileTypes: true })
+    .filter(e => e.isDirectory())
+    .sort((a, b) => a.name.localeCompare(b.name));
+
+  for (const entry of entries) {
+    const phaseDir = path.join(phasesDir, entry.name);
+    const plans = findFiles(phaseDir, /PLAN.*\.md$/i);
+    const summaries = findFiles(phaseDir, /^SUMMARY-.*\.md$/);
+    const verification = fs.existsSync(path.join(phaseDir, 'VERIFICATION.md'));
+
+    const completedSummaries = summaries.filter(s => {
+      const content = fs.readFileSync(path.join(phaseDir, s), 'utf8');
+      return /status:\s*["']?complete/i.test(content);
+    });
+
+    const phaseInfoObj = {
+      directory: entry.name,
+      plans: plans.length,
+      summaries: summaries.length,
+      completed: completedSummaries.length,
+      has_verification: verification,
+      status: determinePhaseStatus(plans.length, completedSummaries.length, summaries.length, verification, phaseDir)
+    };
+
+    phases.push(phaseInfoObj);
+    totalPlans += plans.length;
+    completedPlans += completedSummaries.length;
+  }
+
+  return {
+    phases,
+    total_plans: totalPlans,
+    completed_plans: completedPlans,
+    percentage: totalPlans > 0 ? Math.round((completedPlans / totalPlans) * 100) : 0
+  };
+}
+
+/**
+ * Atomically update a field in STATE.md using lockedFileUpdate.
+ * Supports both legacy and frontmatter (v2) formats.
+ *
+ * @param {string} field - One of: current_phase, status, plans_complete, last_activity,
+ *   progress_percent, phase_slug, total_phases, last_command, blockers
+ * @param {string} value - New value (use 'now' for last_activity to auto-timestamp)
+ * @param {string} [planningDir] - Path to .planning directory
+ */
+function stateUpdate(field, value, planningDir) {
+  const dir = planningDir || path.join(process.env.PBR_PROJECT_ROOT || process.cwd(), '.planning');
+  const statePath = path.join(dir, 'STATE.md');
+  if (!fs.existsSync(statePath)) {
+    return { success: false, error: 'STATE.md not found' };
+  }
+
+  // All 9 STATE.md frontmatter fields supported by stateUpdate
+  const validFields = [
+    'current_phase',
+    'status',
+    'plans_complete',
+    'plans_total',
+    'last_activity',
+    'progress_percent',
+    'phase_slug',
+    'last_command',
+    'blockers'
+  ];
+  if (!validFields.includes(field)) {
+    return { success: false, error: `Invalid field: ${field}. Valid fields: ${validFields.join(', ')}` };
+  }
+
+  // Auto-timestamp
+  if (field === 'last_activity' && value === 'now') {
+    value = new Date().toISOString().slice(0, 19).replace('T', ' ');
+  }
+
+  const result = lockedFileUpdate(statePath, (content) => {
+    const fm = parseYamlFrontmatter(content);
+    if (fm.version === 2 || fm.current_phase !== undefined) {
+      let updated = updateFrontmatterField(content, field, value);
+      updated = syncBodyLine(updated, field, value);
+      return updated;
+    }
+    return updateLegacyStateField(content, field, value);
+  });
+
+  if (result.success) {
+    return { success: true, field, value };
+  }
+  return { success: false, error: result.error };
+}
+
+/**
+ * Batch-update multiple STATE.md fields at once.
+ *
+ * @param {string} jsonStr - JSON string of field:value pairs
+ * @param {string} [planningDir] - Path to .planning directory
+ */
+function statePatch(jsonStr, planningDir) {
+  const dir = planningDir || path.join(process.env.PBR_PROJECT_ROOT || process.cwd(), '.planning');
+  const statePath = path.join(dir, 'STATE.md');
+  if (!fs.existsSync(statePath)) return { success: false, error: "STATE.md not found" };
+  let fields;
+  try { fields = JSON.parse(jsonStr); } catch (_e) { return { success: false, error: "Invalid JSON" }; }
+  const validFields = ["current_phase", "status", "plans_complete", "plans_total", "last_activity", "progress_percent", "phase_slug", "last_command", "blockers"];
+  const updates = [], errors = [];
+  for (const [field, value] of Object.entries(fields)) {
+    if (!validFields.includes(field)) { errors.push("Unknown field: " + field); continue; }
+    try { stateUpdate(field, String(value), dir); updates.push(field); } catch (e) { errors.push(field + ": " + e.message); }
+  }
+  return { success: errors.length === 0, updated: updates, errors: errors.length > 0 ? errors : undefined };
+}
+
+/**
+ * Advance the plan counter in STATE.md by 1.
+ *
+ * @param {string} [planningDir] - Path to .planning directory
+ */
+function stateAdvancePlan(planningDir) {
+  const dir = planningDir || path.join(process.env.PBR_PROJECT_ROOT || process.cwd(), '.planning');
+  const statePath = path.join(dir, 'STATE.md');
+  if (!fs.existsSync(statePath)) return { success: false, error: "STATE.md not found" };
+  const stateContent = fs.readFileSync(statePath, "utf8");
+  const planMatch = stateContent.match(/Plan:\s*(\d+)\s+of\s+(\d+)/);
+  if (!planMatch) return { success: false, error: "Could not find Plan: N of M in STATE.md" };
+  const current = parseInt(planMatch[1], 10), total = parseInt(planMatch[2], 10);
+  const next = Math.min(current + 1, total);
+  stateUpdate("plans_complete", String(next), dir);
+  const progressPct = total > 0 ? Math.round((next / total) * 100) : 0;
+  stateUpdate("progress_percent", String(progressPct), dir);
+  return { success: true, previous_plan: current, current_plan: next, total_plans: total, progress_percent: progressPct };
+}
+
+/**
+ * Record a session metric in STATE.md (history section).
+ *
+ * @param {string[]} metricArgs - CLI args like ['--duration', '30m', '--plans-completed', '3']
+ * @param {string} [planningDir] - Path to .planning directory
+ */
+function stateRecordMetric(metricArgs, planningDir) {
+  const dir = planningDir || path.join(process.env.PBR_PROJECT_ROOT || process.cwd(), '.planning');
+  const { historyAppend } = require('./history');
+  let duration = null, plansCompleted = null;
+  for (let i = 0; i < metricArgs.length; i++) {
+    if (metricArgs[i] === "--duration" && metricArgs[i + 1]) {
+      const match = metricArgs[i + 1].match(/(\d+)(m|s|h)/);
+      if (match) { const val = parseInt(match[1], 10); const unit = match[2]; duration = unit === "h" ? val * 60 : unit === "s" ? Math.round(val / 60) : val; }
+      i++;
+    } else if (metricArgs[i] === "--plans-completed" && metricArgs[i + 1]) {
+      plansCompleted = parseInt(metricArgs[i + 1], 10); i++;
+    }
+  }
+  const parts = [];
+  if (duration !== null) parts.push("duration: " + duration + "m");
+  if (plansCompleted !== null) parts.push("plans_completed: " + plansCompleted);
+  if (parts.length > 0) historyAppend({ type: "metric", title: "Session metric", body: parts.join(", ") }, dir);
+  stateUpdate("last_activity", "now", dir);
+  return { success: true, duration_minutes: duration, plans_completed: plansCompleted };
+}
+
+/**
+ * Record an activity description with today's date in STATE.md last_activity.
+ *
+ * @param {string} description - Activity description (e.g., "Built phase 3")
+ * @param {string} [planningDir] - Path to .planning directory
+ * @returns {object} { success: true, last_activity: "YYYY-MM-DD description" }
+ */
+function stateRecordActivity(description, planningDir) {
+  const dir = planningDir || path.join(process.env.PBR_PROJECT_ROOT || process.cwd(), '.planning');
+  const today = new Date().toISOString().slice(0, 10);
+  const value = `${today} ${description}`;
+  const result = stateUpdate('last_activity', value, dir);
+  if (!result.success) return result;
+  return { success: true, last_activity: value };
+}
+
+/**
+ * Recalculate progress from filesystem and atomically update STATE.md
+ * with progress_percent, plans_complete, and plans_total.
+ *
+ * @param {string} [planningDir] - Path to .planning directory
+ * @returns {object} { success, percent, completed_plans, total_plans }
+ */
+function stateUpdateProgress(planningDir) {
+  const dir = planningDir || path.join(process.env.PBR_PROJECT_ROOT || process.cwd(), '.planning');
+  const statePath = path.join(dir, 'STATE.md');
+  if (!fs.existsSync(statePath)) {
+    return { success: false, error: 'STATE.md not found' };
+  }
+
+  const progress = stateCheckProgress(dir);
+  const { percentage, completed_plans, total_plans } = progress;
+
+  const result = lockedFileUpdate(statePath, (content) => {
+    let updated = content;
+    // Update frontmatter fields
+    updated = updateFrontmatterField(updated, 'progress_percent', percentage);
+    updated = updateFrontmatterField(updated, 'plans_complete', completed_plans);
+    updated = updateFrontmatterField(updated, 'plans_total', total_plans);
+    // Update body lines
+    updated = syncBodyLine(updated, 'progress_percent', percentage);
+    updated = syncBodyLine(updated, 'plans_complete', completed_plans);
+    updated = syncBodyLine(updated, 'plans_total', total_plans);
+    return updated;
+  });
+
+  if (!result.success) return { success: false, error: result.error };
+  return { success: true, percent: percentage, completed_plans, total_plans };
+}
+
+module.exports = {
+  parseStateMd,
+  updateLegacyStateField,
+  updateFrontmatterField,
+  syncBodyLine,
+  buildProgressBar,
+  stateLoad,
+  stateCheckProgress,
+  stateUpdate,
+  statePatch,
+  stateAdvancePlan,
+  stateRecordMetric,
+  stateRecordActivity,
+  stateUpdateProgress
+};

package/plugins/pbr/scripts/lib/step-verify.js

@@ -0,0 +1,149 @@
+'use strict';
+
+/**
+ * lib/step-verify.js — Per-step completion checklist verifier for Plan-Build-Run.
+ *
+ * Provides stepVerify(skill, step, checklist, context) which maps checklist item
+ * strings to filesystem predicates using keyword matching and returns a structured
+ * pass/fail result.
+ *
+ * Usage (CLI via pbr-tools.js):
+ *   node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js step-verify build step-6f '["STATE.md updated","SUMMARY.md exists"]'
+ *
+ * Returns: { skill, step, passed: string[], failed: string[], all_passed: boolean }
+ * On invalid checklist: { error: 'Invalid checklist JSON' }
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+/**
+ * Match a single checklist item string to a filesystem predicate.
+ *
+ * @param {string} item - Checklist item string (e.g. "STATE.md updated")
+ * @param {object} context - { planningDir, phaseSlug, planId }
+ * @returns {{ passed: boolean, reason: string }}
+ */
+function matchPredicate(item, context) {
+  const lower = item.toLowerCase();
+  const { planningDir, phaseSlug, planId } = context;
+
+  const phasesDir = path.join(planningDir, 'phases');
+  const phaseDir = phaseSlug ? path.join(phasesDir, phaseSlug) : null;
+
+  // SUMMARY.md exists: check phaseDir for SUMMARY-{planId}.md or SUMMARY.md
+  if (lower.includes('summary') && lower.includes('exist')) {
+    if (!phaseDir) {
+      return { passed: false, reason: 'phaseSlug not provided in context' };
+    }
+    const summaryNamedPath = planId
+      ? path.join(phaseDir, `SUMMARY-${planId}.md`)
+      : null;
+    const summaryGenericPath = path.join(phaseDir, 'SUMMARY.md');
+    const exists =
+      (summaryNamedPath && fs.existsSync(summaryNamedPath)) ||
+      fs.existsSync(summaryGenericPath);
+    return {
+      passed: exists,
+      reason: exists ? 'SUMMARY file found' : 'No SUMMARY file in phase dir'
+    };
+  }
+
+  // STATE.md updated or exists: check planningDir/STATE.md
+  if (lower.includes('state') && (lower.includes('update') || lower.includes('exist'))) {
+    const statePath = path.join(planningDir, 'STATE.md');
+    const exists = fs.existsSync(statePath);
+    return {
+      passed: exists,
+      reason: exists ? 'STATE.md found' : 'STATE.md not found in planningDir'
+    };
+  }
+
+  // PLAN.md exists: check phaseDir has at least one PLAN*.md file
+  if (lower.includes('plan') && lower.includes('exist')) {
+    if (!phaseDir) {
+      return { passed: false, reason: 'phaseSlug not provided in context' };
+    }
+    let planFiles = [];
+    try {
+      planFiles = fs.readdirSync(phaseDir).filter(f => /^PLAN.*\.md$/i.test(f));
+    } catch (_e) {
+      return { passed: false, reason: 'Phase directory not accessible' };
+    }
+    const exists = planFiles.length > 0;
+    return {
+      passed: exists,
+      reason: exists ? `Found: ${planFiles.join(', ')}` : 'No PLAN*.md files in phase dir'
+    };
+  }
+
+  // ROADMAP.md updated: check planningDir/ROADMAP.md
+  if (lower.includes('roadmap') && lower.includes('update')) {
+    const roadmapPath = path.join(planningDir, 'ROADMAP.md');
+    const exists = fs.existsSync(roadmapPath);
+    return {
+      passed: exists,
+      reason: exists ? 'ROADMAP.md found' : 'ROADMAP.md not found in planningDir'
+    };
+  }
+
+  // commit made: spawn 'git log --oneline -1'; pass if stdout non-empty
+  if (lower.includes('commit')) {
+    const result = spawnSync('git', ['log', '--oneline', '-1'], {
+      encoding: 'utf8',
+      timeout: 5000
+    });
+    const output = (result.stdout || '').trim();
+    const passed = output.length > 0;
+    return {
+      passed,
+      reason: passed ? `Last commit: ${output}` : 'git log returned no output'
+    };
+  }
+
+  // No predicate matched
+  return {
+    passed: false,
+    reason: 'No predicate matched'
+  };
+}
+
+/**
+ * Verify a list of checklist items for a given skill step.
+ *
+ * @param {string} skill - Skill name (e.g. 'build')
+ * @param {string} step - Step label (e.g. 'step-6f')
+ * @param {Array<string>|*} checklist - Array of checklist item strings
+ * @param {object} context - { planningDir, phaseSlug, planId }
+ * @returns {{ skill, step, passed: string[], failed: string[], all_passed: boolean }
+ *           | { error: string }}
+ */
+function stepVerify(skill, step, checklist, context) {
+  if (!Array.isArray(checklist)) {
+    return { error: 'Invalid checklist JSON' };
+  }
+
+  const passed = [];
+  const failed = [];
+
+  for (const item of checklist) {
+    const { passed: itemPassed } = matchPredicate(item, context || {});
+    if (itemPassed) {
+      passed.push(item);
+    } else {
+      failed.push(item);
+    }
+  }
+
+  return {
+    skill,
+    step,
+    passed,
+    failed,
+    all_passed: failed.length === 0
+  };
+}
+
+// matchPredicate exported for unit testing of individual predicate branches
+module.exports = { stepVerify, matchPredicate };