@sienklogic/plan-build-run 2.46.0 → 2.48.0

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

@@ -0,0 +1,454 @@
+'use strict';
+
+/**
+ * lib/build.js — Build helper functions for Plan-Build-Run orchestrator.
+ *
+ * Provides deterministic CLI-callable utilities for the build skill, replacing
+ * inline procedural blocks that the LLM is prone to skipping or misimplementing.
+ *
+ * Exported functions:
+ *   stalenessCheck(phaseSlug, planningDir)   — Check if phase plans are stale
+ *   summaryGate(phaseSlug, planId, planningDir) — Verify SUMMARY.md validity gates
+ *   checkpointInit(phaseSlug, plans, planningDir) — Initialize checkpoint manifest
+ *   checkpointUpdate(phaseSlug, opts, planningDir) — Update checkpoint manifest
+ *   seedsMatch(phaseSlug, phaseNumber, planningDir) — Find matching seed files
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Resolve the .planning directory from the given planningDir or env/cwd fallback.
+ * @param {string} [planningDir]
+ * @returns {string}
+ */
+function resolvePlanningDir(planningDir) {
+  if (planningDir) return planningDir;
+  const cwd = process.env.PBR_PROJECT_ROOT || process.cwd();
+  return path.join(cwd, '.planning');
+}
+
+// ---------------------------------------------------------------------------
+// stalenessCheck
+// ---------------------------------------------------------------------------
+
+/**
+ * Check whether any plans in a phase are stale relative to their dependencies.
+ *
+ * Staleness detection logic (two modes):
+ *   1. If any PLAN.md has a `dependency_fingerprints` field: compare the referenced
+ *      SUMMARY.md files' current byte size and mtime to the stored values.
+ *   2. Fallback: read ROADMAP.md for the phase's `depends_on`, then compare
+ *      the mtime of dependency SUMMARY.md files vs the current PLAN.md files.
+ *
+ * @param {string} phaseSlug  — Phase directory name (e.g. "52-skill-prompt-slimming")
+ * @param {string} [planningDir]
+ * @returns {{ stale: boolean, plans: Array<{ id: string, stale: boolean, reason: string }> }
+ *          | { error: string }}
+ */
+function stalenessCheck(phaseSlug, planningDir) {
+  const pd = resolvePlanningDir(planningDir);
+  const phasesDir = path.join(pd, 'phases');
+  const phaseDir = path.join(phasesDir, phaseSlug);
+
+  if (!fs.existsSync(phaseDir)) {
+    return { error: 'Phase not found: ' + phaseSlug };
+  }
+
+  // Find all PLAN-*.md files in the phase directory
+  let planFiles;
+  try {
+    planFiles = fs.readdirSync(phaseDir).filter(f => /^PLAN.*\.md$/i.test(f));
+  } catch (_e) {
+    return { error: 'Cannot read phase directory: ' + phaseSlug };
+  }
+
+  if (planFiles.length === 0) {
+    return { stale: false, plans: [] };
+  }
+
+  const planResults = [];
+  let anyStale = false;
+
+  for (const planFile of planFiles) {
+    const planPath = path.join(phaseDir, planFile);
+    let planContent;
+    try {
+      planContent = fs.readFileSync(planPath, 'utf8');
+    } catch (_e) {
+      planResults.push({ id: planFile, stale: false, reason: 'unreadable' });
+      continue;
+    }
+
+    // Extract plan_id from frontmatter
+    const idMatch = planContent.match(/^plan:\s*["']?([^"'\n]+)["']?/m);
+    const planId = idMatch ? idMatch[1].trim() : planFile.replace(/\.md$/i, '');
+
+    // Check for dependency_fingerprints in frontmatter
+    const fpMatch = planContent.match(/^dependency_fingerprints:\s*\n([\s\S]*?)(?=\n\w|\n---)/m);
+    if (fpMatch) {
+      // Mode 1: fingerprint-based check
+      const staleResult = checkFingerprintStaleness(planId, fpMatch[1], pd);
+      if (staleResult.stale) anyStale = true;
+      planResults.push(staleResult);
+    } else {
+      // Mode 2: timestamp-based fallback — check once (not per-plan)
+      // We'll do it per plan but only if there's a depends_on
+      const depsMatch = planContent.match(/^depends_on:\s*\[([^\]]*)\]/m);
+      if (!depsMatch || depsMatch[1].trim() === '') {
+        planResults.push({ id: planId, stale: false, reason: 'no dependencies' });
+        continue;
+      }
+      const deps = depsMatch[1].split(',').map(d => d.trim().replace(/['"]/g, '')).filter(Boolean);
+      const staleResult = checkTimestampStaleness(planId, planPath, deps, pd, phasesDir);
+      if (staleResult.stale) anyStale = true;
+      planResults.push(staleResult);
+    }
+  }
+
+  return { stale: anyStale, plans: planResults };
+}
+
+/**
+ * Check staleness via dependency_fingerprints field.
+ * @param {string} planId
+ * @param {string} fingerprintBlock — raw YAML block content under dependency_fingerprints
+ * @param {string} pd — planningDir
+ * @returns {{ id: string, stale: boolean, reason: string }}
+ */
+function checkFingerprintStaleness(planId, fingerprintBlock, pd) {
+  // Parse entries like:  - path: ...\n    size: N\n    mtime: N
+  const entries = [];
+  const entryRegex = /-\s+path:\s*(.+?)(?:\n|$)[\s\S]*?size:\s*(\d+)[\s\S]*?mtime:\s*(\d+)/g;
+  let m;
+  while ((m = entryRegex.exec(fingerprintBlock)) !== null) {
+    entries.push({ filePath: m[1].trim(), size: parseInt(m[2], 10), mtime: parseInt(m[3], 10) });
+  }
+
+  for (const entry of entries) {
+    const absPath = path.isAbsolute(entry.filePath)
+      ? entry.filePath
+      : path.join(pd, '..', entry.filePath);
+    try {
+      const stat = fs.statSync(absPath);
+      if (stat.size !== entry.size || Math.round(stat.mtimeMs) !== entry.mtime) {
+        return { id: planId, stale: true, reason: `dependency ${entry.filePath} changed (size or mtime mismatch)` };
+      }
+    } catch (_e) {
+      return { id: planId, stale: true, reason: `dependency ${entry.filePath} not found` };
+    }
+  }
+
+  return { id: planId, stale: false, reason: 'fingerprints match' };
+}
+
+/**
+ * Check staleness via ROADMAP depends_on + timestamp comparison.
+ * @param {string} planId
+ * @param {string} planPath — absolute path to PLAN.md file
+ * @param {string[]} deps — dependency phase slugs/IDs
+ * @param {string} pd — planningDir
+ * @param {string} phasesDir
+ * @returns {{ id: string, stale: boolean, reason: string }}
+ */
+function checkTimestampStaleness(planId, planPath, deps, pd, phasesDir) {
+  let planMtime;
+  try {
+    planMtime = fs.statSync(planPath).mtimeMs;
+  } catch (_e) {
+    return { id: planId, stale: false, reason: 'cannot stat plan file' };
+  }
+
+  for (const dep of deps) {
+    // Find the dependency phase directory
+    let depDir = null;
+    try {
+      const allDirs = fs.readdirSync(phasesDir);
+      // dep might be a plan ID like "51-01" — find phase dirs that start with the phase number
+      const phaseNumMatch = dep.match(/^(\d+)/);
+      if (phaseNumMatch) {
+        const phaseNum = phaseNumMatch[1].padStart(2, '0');
+        depDir = allDirs.find(d => d.startsWith(phaseNum + '-'));
+      }
+      if (!depDir) {
+        depDir = allDirs.find(d => d === dep || d.includes(dep));
+      }
+    } catch (_e) { continue; }
+
+    if (!depDir) continue;
+
+    const depPhaseDir = path.join(phasesDir, depDir);
+    let summaryFiles;
+    try {
+      summaryFiles = fs.readdirSync(depPhaseDir).filter(f => /^SUMMARY.*\.md$/i.test(f));
+    } catch (_e) { continue; }
+
+    for (const sf of summaryFiles) {
+      try {
+        const sfMtime = fs.statSync(path.join(depPhaseDir, sf)).mtimeMs;
+        if (sfMtime > planMtime) {
+          return { id: planId, stale: true, reason: `dependency phase ${depDir} was modified after planning (${sf} is newer)` };
+        }
+      } catch (_e) { continue; }
+    }
+  }
+
+  return { id: planId, stale: false, reason: 'timestamps ok' };
+}
+
+// ---------------------------------------------------------------------------
+// summaryGate
+// ---------------------------------------------------------------------------
+
+/**
+ * Verify that a SUMMARY.md file passes all three gates before STATE.md update.
+ *
+ * Gate 1: file exists
+ * Gate 2: file is non-empty (size > 0)
+ * Gate 3: file contains `---` delimiter AND a `status:` field
+ *
+ * @param {string} phaseSlug
+ * @param {string} planId
+ * @param {string} [planningDir]
+ * @returns {{ ok: boolean, gate: string|null, detail: string }}
+ */
+function summaryGate(phaseSlug, planId, planningDir) {
+  const pd = resolvePlanningDir(planningDir);
+  const summaryPath = path.join(pd, 'phases', phaseSlug, `SUMMARY-${planId}.md`);
+
+  // Gate 1: exists
+  if (!fs.existsSync(summaryPath)) {
+    return { ok: false, gate: 'exists', detail: `SUMMARY-${planId}.md not found in phase ${phaseSlug}` };
+  }
+
+  // Gate 2: non-empty
+  let stat;
+  try {
+    stat = fs.statSync(summaryPath);
+  } catch (_e) {
+    return { ok: false, gate: 'exists', detail: 'Cannot stat SUMMARY file' };
+  }
+  if (stat.size === 0) {
+    return { ok: false, gate: 'nonempty', detail: `SUMMARY-${planId}.md is empty` };
+  }
+
+  // Gate 3: valid frontmatter
+  let content;
+  try {
+    content = fs.readFileSync(summaryPath, 'utf8');
+  } catch (_e) {
+    return { ok: false, gate: 'valid-frontmatter', detail: 'Cannot read SUMMARY file' };
+  }
+
+  const lines = content.split(/\r?\n/).slice(0, 30);
+  const hasDashes = lines.some(l => l.trim() === '---');
+  const hasStatus = lines.some(l => /^status\s*:/i.test(l.trim()));
+
+  if (!hasDashes || !hasStatus) {
+    return { ok: false, gate: 'valid-frontmatter', detail: `SUMMARY-${planId}.md missing frontmatter (needs --- delimiters and status: field)` };
+  }
+
+  return { ok: true, gate: null, detail: 'all gates passed' };
+}
+
+// ---------------------------------------------------------------------------
+// checkpointInit
+// ---------------------------------------------------------------------------
+
+/**
+ * Initialize the checkpoint manifest for a phase before entering the wave loop.
+ *
+ * @param {string} phaseSlug
+ * @param {string|string[]} plans — comma-separated string or array of plan IDs
+ * @param {string} [planningDir]
+ * @returns {{ ok: boolean, path: string } | { error: string }}
+ */
+function checkpointInit(phaseSlug, plans, planningDir) {
+  const pd = resolvePlanningDir(planningDir);
+  const phaseDir = path.join(pd, 'phases', phaseSlug);
+  const manifestPath = path.join(phaseDir, '.checkpoint-manifest.json');
+
+  // Normalize plans to array
+  let planIds;
+  if (Array.isArray(plans)) {
+    planIds = plans.filter(Boolean);
+  } else if (typeof plans === 'string' && plans.trim()) {
+    planIds = plans.split(',').map(s => s.trim()).filter(Boolean);
+  } else {
+    planIds = [];
+  }
+
+  const manifest = {
+    plans: planIds,
+    checkpoints_resolved: [],
+    checkpoints_pending: [],
+    wave: 1,
+    deferred: [],
+    commit_log: [],
+    last_good_commit: null
+  };
+
+  try {
+    fs.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2), 'utf8');
+    return { ok: true, path: manifestPath };
+  } catch (e) {
+    return { error: 'Failed to write checkpoint manifest: ' + e.message };
+  }
+}
+
+// ---------------------------------------------------------------------------
+// checkpointUpdate
+// ---------------------------------------------------------------------------
+
+/**
+ * Update the checkpoint manifest after a wave completes.
+ *
+ * @param {string} phaseSlug
+ * @param {{ wave: number, resolved: string, sha: string }} opts
+ * @param {string} [planningDir]
+ * @returns {{ ok: boolean } | { error: string }}
+ */
+function checkpointUpdate(phaseSlug, opts, planningDir) {
+  const pd = resolvePlanningDir(planningDir);
+  const phaseDir = path.join(pd, 'phases', phaseSlug);
+  const manifestPath = path.join(phaseDir, '.checkpoint-manifest.json');
+
+  let manifest;
+  try {
+    const raw = fs.readFileSync(manifestPath, 'utf8');
+    manifest = JSON.parse(raw);
+  } catch (e) {
+    return { error: 'Cannot read checkpoint manifest: ' + e.message };
+  }
+
+  const { wave, resolved, sha } = opts || {};
+
+  // Move resolved plan from plans → checkpoints_resolved
+  if (resolved) {
+    manifest.plans = (manifest.plans || []).filter(p => p !== resolved);
+    if (!manifest.checkpoints_resolved) manifest.checkpoints_resolved = [];
+    manifest.checkpoints_resolved.push(resolved);
+  }
+
+  // Advance wave
+  if (typeof wave === 'number' && !isNaN(wave)) {
+    manifest.wave = wave;
+  }
+
+  // Append to commit_log and update last_good_commit
+  if (sha) {
+    if (!manifest.commit_log) manifest.commit_log = [];
+    manifest.commit_log.push({ plan: resolved || null, sha, timestamp: new Date().toISOString() });
+    manifest.last_good_commit = sha;
+  }
+
+  try {
+    fs.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2), 'utf8');
+    return { ok: true };
+  } catch (e) {
+    return { error: 'Failed to write checkpoint manifest: ' + e.message };
+  }
+}
+
+// ---------------------------------------------------------------------------
+// seedsMatch
+// ---------------------------------------------------------------------------
+
+/**
+ * Find seed files in .planning/seeds/ that match the given phase.
+ *
+ * A seed matches if ANY of these conditions are true:
+ *   1. trigger === phaseSlug (exact)
+ *   2. trigger is a substring of phaseSlug
+ *   3. trigger === String(phaseNumber)
+ *   4. trigger === '*'
+ *
+ * @param {string} phaseSlug    — e.g. "03-authentication"
+ * @param {string|number} phaseNumber — e.g. "3" or 3
+ * @param {string} [planningDir]
+ * @returns {{ matched: Array<{ name: string, description: string, trigger: string, path: string }> }}
+ */
+function seedsMatch(phaseSlug, phaseNumber, planningDir) {
+  const pd = resolvePlanningDir(planningDir);
+  const seedsDir = path.join(pd, 'seeds');
+
+  if (!fs.existsSync(seedsDir)) {
+    return { matched: [] };
+  }
+
+  let seedFiles;
+  try {
+    seedFiles = fs.readdirSync(seedsDir).filter(f => f.endsWith('.md'));
+  } catch (_e) {
+    return { matched: [] };
+  }
+
+  const phaseNumStr = String(phaseNumber);
+  const matched = [];
+
+  for (const seedFile of seedFiles) {
+    const seedPath = path.join(seedsDir, seedFile);
+    let content;
+    try {
+      content = fs.readFileSync(seedPath, 'utf8');
+    } catch (_e) { continue; }
+
+    // Parse frontmatter
+    const fm = parseSeedFrontmatter(content);
+    if (!fm || !fm.trigger) continue;
+
+    const trigger = String(fm.trigger).replace(/^["']|["']$/g, '');
+
+    const matches =
+      trigger === phaseSlug ||
+      phaseSlug.includes(trigger) ||
+      trigger === phaseNumStr ||
+      trigger === '*';
+
+    if (matches) {
+      matched.push({
+        name: fm.name || seedFile,
+        description: fm.description || '',
+        trigger,
+        path: seedPath
+      });
+    }
+  }
+
+  return { matched };
+}
+
+/**
+ * Minimal YAML frontmatter parser for seed files.
+ * Extracts trigger, name, description fields.
+ * @param {string} content
+ * @returns {{ trigger?: string, name?: string, description?: string } | null}
+ */
+function parseSeedFrontmatter(content) {
+  const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  if (!match) return null;
+
+  const block = match[1];
+  const result = {};
+
+  for (const line of block.split(/\r?\n/)) {
+    const m = line.match(/^(\w+):\s*(.*)$/);
+    if (m) {
+      result[m[1]] = m[2].replace(/^["']|["']$/g, '').trim();
+    }
+  }
+
+  return result;
+}
+
+// ---------------------------------------------------------------------------
+// Exports
+// ---------------------------------------------------------------------------
+
+module.exports = {
+  stalenessCheck,
+  summaryGate,
+  checkpointInit,
+  checkpointUpdate,
+  seedsMatch
+};

package/plugins/pbr/scripts/pbr-tools.js

@@ -41,6 +41,11 @@
  *   learnings query [--tags X] [--min-confidence Y] [--stack S] [--type T] — Query learnings
  *   learnings check-thresholds   — Check deferral trigger conditions
  *   spot-check <phaseSlug> <planId>  — Verify SUMMARY, key_files, and commits exist for a plan
+ *   staleness-check <phase-slug>  — Check if phase plans are stale vs dependencies
+ *   summary-gate <phase-slug> <plan-id>  — Verify SUMMARY.md exists, non-empty, valid frontmatter
+ *   checkpoint init <phase-slug> [--plans "id1,id2"]  — Initialize checkpoint manifest
+ *   checkpoint update <phase-slug> --wave N --resolved id [--sha hash]  — Update manifest
+ *   seeds match <phase-slug> <phase-number>  — Find matching seed files for a phase
  *
  * Environment: PBR_PROJECT_ROOT — Override project root directory (used when hooks fire from subagent cwd)
  */
@@ -153,6 +158,14 @@ const {
   contextTriage: _contextTriage
 } = require('./lib/context');
 
+const {
+  stalenessCheck: _stalenessCheck,
+  summaryGate: _summaryGate,
+  checkpointInit: _checkpointInit,
+  checkpointUpdate: _checkpointUpdate,
+  seedsMatch: _seedsMatch
+} = require('./lib/build');
+
 // --- Local LLM imports (not extracted — separate module tree) ---
 const { resolveConfig, checkHealth } = require('./local-llm/health');
 const { classifyArtifact } = require('./local-llm/operations/classify-artifact');
@@ -323,6 +336,12 @@ function contextTriage(options) {
   return _contextTriage(options, planningDir);
 }
 
+function stalenessCheck(phaseSlug) { return _stalenessCheck(phaseSlug, planningDir); }
+function summaryGate(phaseSlug, planId) { return _summaryGate(phaseSlug, planId, planningDir); }
+function checkpointInit(phaseSlug, plans) { return _checkpointInit(phaseSlug, plans, planningDir); }
+function checkpointUpdate(phaseSlug, opts) { return _checkpointUpdate(phaseSlug, opts, planningDir); }
+function seedsMatch(phaseSlug, phaseNum) { return _seedsMatch(phaseSlug, phaseNum, planningDir); }
+
 // --- validateProject stays here (cross-cutting across modules) ---
 
 /**
@@ -765,6 +784,41 @@ async function main() {
         error('Usage: spot-check <phaseSlug> <planId>');
       }
       output(spotCheck(phaseSlug, planId));
+    } else if (command === 'staleness-check') {
+      const slug = args[1];
+      if (!slug) { error('Usage: staleness-check <phase-slug>'); process.exit(1); }
+      output(stalenessCheck(slug));
+    } else if (command === 'summary-gate') {
+      const [slug, planId] = args.slice(1);
+      if (!slug || !planId) { error('Usage: summary-gate <phase-slug> <plan-id>'); process.exit(1); }
+      output(summaryGate(slug, planId));
+    } else if (command === 'checkpoint') {
+      const sub = args[1];
+      const slug = args[2];
+      if (sub === 'init') {
+        const plans = args[3] || '';
+        output(checkpointInit(slug, plans));
+      } else if (sub === 'update') {
+        const waveIdx = args.indexOf('--wave');
+        const wave = waveIdx !== -1 ? parseInt(args[waveIdx + 1], 10) : 1;
+        const resolvedIdx = args.indexOf('--resolved');
+        const resolved = resolvedIdx !== -1 ? args[resolvedIdx + 1] : '';
+        const shaIdx = args.indexOf('--sha');
+        const sha = shaIdx !== -1 ? args[shaIdx + 1] : '';
+        output(checkpointUpdate(slug, { wave, resolved, sha }));
+      } else {
+        error('Usage: checkpoint init|update <phase-slug> [options]'); process.exit(1);
+      }
+    } else if (command === 'seeds') {
+      const sub = args[1];
+      if (sub === 'match') {
+        const slug = args[2];
+        const num = args[3];
+        if (!slug) { error('Usage: seeds match <phase-slug> <phase-number>'); process.exit(1); }
+        output(seedsMatch(slug, num));
+      } else {
+        error('Usage: seeds match <phase-slug> <phase-number>'); process.exit(1);
+      }
     } else if (command === 'context-triage') {
       const options = {};
       const agentsIdx = args.indexOf('--agents-done');
@@ -796,6 +850,6 @@ async function main() {
 }
 
 if (require.main === module || process.argv[1] === __filename) { main().catch(err => { process.stderr.write(err.message + '\n'); process.exit(1); }); }
-module.exports = { KNOWN_AGENTS, initExecutePhase, initPlanPhase, initQuick, initVerifyWork, initResume, initProgress, initStateBundle: stateBundle, stateBundle, statePatch, stateAdvancePlan, stateRecordMetric, parseStateMd, parseRoadmapMd, parseYamlFrontmatter, parseMustHaves, countMustHaves, stateLoad, stateCheckProgress, configLoad, configClearCache, configValidate, lockedFileUpdate, planIndex, determinePhaseStatus, findFiles, atomicWrite, tailLines, frontmatter, mustHavesCollect, phaseInfo, stateUpdate, roadmapUpdateStatus, roadmapUpdatePlans, updateLegacyStateField, updateFrontmatterField, updateTableRow, findRoadmapRow, resolveDepthProfile, DEPTH_PROFILE_DEFAULTS, historyAppend, historyLoad, VALID_STATUS_TRANSITIONS, validateStatusTransition, writeActiveSkill, validateProject, phaseAdd, phaseRemove, phaseList, loadUserDefaults, saveUserDefaults, mergeUserDefaults, USER_DEFAULTS_PATH, todoList, todoGet, todoAdd, todoDone, migrate, spotCheck, referenceGet, milestoneStats, contextTriage };
+module.exports = { KNOWN_AGENTS, initExecutePhase, initPlanPhase, initQuick, initVerifyWork, initResume, initProgress, initStateBundle: stateBundle, stateBundle, statePatch, stateAdvancePlan, stateRecordMetric, parseStateMd, parseRoadmapMd, parseYamlFrontmatter, parseMustHaves, countMustHaves, stateLoad, stateCheckProgress, configLoad, configClearCache, configValidate, lockedFileUpdate, planIndex, determinePhaseStatus, findFiles, atomicWrite, tailLines, frontmatter, mustHavesCollect, phaseInfo, stateUpdate, roadmapUpdateStatus, roadmapUpdatePlans, updateLegacyStateField, updateFrontmatterField, updateTableRow, findRoadmapRow, resolveDepthProfile, DEPTH_PROFILE_DEFAULTS, historyAppend, historyLoad, VALID_STATUS_TRANSITIONS, validateStatusTransition, writeActiveSkill, validateProject, phaseAdd, phaseRemove, phaseList, loadUserDefaults, saveUserDefaults, mergeUserDefaults, USER_DEFAULTS_PATH, todoList, todoGet, todoAdd, todoDone, migrate, spotCheck, referenceGet, milestoneStats, contextTriage, stalenessCheck, summaryGate, checkpointInit, checkpointUpdate, seedsMatch };
 // NOTE: validateProject, phaseAdd, phaseRemove, phaseList were previously CLI-only (not exported).
 // They are now exported for testability. This is additive and backwards-compatible.