@sienklogic/plan-build-run 2.18.1 → 2.19.1

package/plugins/pbr/scripts/lib/test-cache.js

@@ -0,0 +1,54 @@
+'use strict';
+const fs = require('fs');
+const path = require('path');
+
+const CACHE_FILE = path.join(process.cwd(), '.planning', '.test-cache.json');
+
+/**
+ * Read a cached test result by key.
+ * Returns the cached entry if fresh (within TTL), or null otherwise.
+ *
+ * @param {string} key - Cache key (e.g., phase directory path)
+ * @param {number} [ttlSeconds=60] - Time-to-live in seconds
+ * @returns {{ passed: boolean, output: string, timestamp: number } | null}
+ */
+function readCache(key, ttlSeconds = 60) {
+  try {
+    if (!fs.existsSync(CACHE_FILE)) return null;
+    const data = JSON.parse(fs.readFileSync(CACHE_FILE, 'utf8'));
+    if (!data[key]) return null;
+    if (Date.now() - data[key].timestamp > ttlSeconds * 1000) return null;
+    return data[key];
+  } catch (_e) {
+    return null;
+  }
+}
+
+/**
+ * Write a test result to the cache.
+ * Uses atomic write (tmp + rename) to avoid corruption.
+ * Errors are silently swallowed — caching must never block the workflow.
+ *
+ * @param {string} key - Cache key (e.g., phase directory path)
+ * @param {{ passed: boolean, output: string }} result - Test result to cache
+ */
+function writeCache(key, result) {
+  try {
+    let data = {};
+    if (fs.existsSync(CACHE_FILE)) {
+      try {
+        data = JSON.parse(fs.readFileSync(CACHE_FILE, 'utf8'));
+      } catch (_e) {
+        data = {};
+      }
+    }
+    data[key] = { passed: result.passed, output: result.output, timestamp: Date.now() };
+    const tmpFile = CACHE_FILE + '.tmp';
+    fs.writeFileSync(tmpFile, JSON.stringify(data, null, 2), 'utf8');
+    fs.renameSync(tmpFile, CACHE_FILE);
+  } catch (_e) {
+    // Silently swallow — caching must never block the workflow
+  }
+}
+
+module.exports = { readCache, writeCache };

package/plugins/pbr/scripts/lib/test-selection.js

@@ -0,0 +1,163 @@
+/**
+ * lib/test-selection.cjs — Smart test selection for Plan-Build-Run.
+ *
+ * Maps changed source files to relevant test files using naming conventions
+ * and impact scope analysis. Reduces test run time by scoping to affected tests.
+ * Controlled by config.features.regression_prevention.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+// ─── File mapping rules ───────────────────────────────────────────────────────
+
+/**
+ * Rules for mapping source files to test files.
+ * Each rule has a pattern (regex) and a testPathFn (maps source path to test path).
+ */
+const FILE_MAPPING_RULES = [
+  {
+    // hooks/{name}.js -> tests/{name}.test.js
+    pattern: /^hooks\/(.+)\.js$/,
+    testPathFn: (match) => `tests/${match[1]}.test.js`,
+  },
+  {
+    // plugins/pbr/scripts/lib/{name}.js -> tests/{name}.test.js
+    pattern: /^plugins\/pbr\/scripts\/lib\/(.+)\.js$/,
+    testPathFn: (match) => `tests/${match[1]}.test.js`,
+  },
+  {
+    // plugins/pbr/scripts/{name}.js -> tests/{name}.test.js
+    pattern: /^plugins\/pbr\/scripts\/(.+)\.js$/,
+    testPathFn: (match) => `tests/${match[1]}.test.js`,
+  },
+  {
+    // plugins/pbr/hooks/{name}.js -> tests/{name}.test.js
+    pattern: /^plugins\/pbr\/hooks\/(.+)\.js$/,
+    testPathFn: (match) => `tests/${match[1]}.test.js`,
+  },
+];
+
+// ─── Config file patterns that trigger full suite ─────────────────────────────
+
+const CONFIG_FILE_PATTERNS = [
+  /config-schema\.json$/,
+  /config\.json$/,
+  /jest\.config\./,
+  /package\.json$/,
+  /\.babelrc/,
+  /tsconfig\.json$/,
+];
+
+// ─── Core functions ───────────────────────────────────────────────────────────
+
+/**
+ * Categorize changed files by type.
+ *
+ * @param {string[]} changedFiles - List of changed file paths (relative)
+ * @returns {{ hooks: string[], lib: string[], skills: string[], agents: string[], config: string[], tests: string[], other: string[], configChanged: boolean }}
+ */
+function getImpactScope(changedFiles) {
+  const scope = {
+    hooks: [],
+    lib: [],
+    skills: [],
+    agents: [],
+    config: [],
+    tests: [],
+    other: [],
+    configChanged: false,
+  };
+
+  for (const file of changedFiles) {
+    if (file.startsWith('hooks/') || file.startsWith('plugins/pbr/hooks/')) {
+      scope.hooks.push(file);
+    } else if (file.startsWith('plugins/pbr/scripts/lib/') || file.startsWith('plugins/pbr/lib/')) {
+      scope.lib.push(file);
+    } else if (file.includes('/skills/') || file.endsWith('SKILL.md')) {
+      scope.skills.push(file);
+    } else if (file.startsWith('agents/') || file.endsWith('.md') && file.includes('/agents/')) {
+      scope.agents.push(file);
+    } else if (file.includes('config') || file.endsWith('.json')) {
+      scope.config.push(file);
+    } else if (file.includes('test') || file.endsWith('.test.js') || file.endsWith('.spec.js')) {
+      scope.tests.push(file);
+    } else {
+      scope.other.push(file);
+    }
+
+    // Check if this is a config file that triggers a full suite run
+    if (CONFIG_FILE_PATTERNS.some(pattern => pattern.test(file))) {
+      scope.configChanged = true;
+    }
+  }
+
+  return scope;
+}
+
+/**
+ * Select relevant test files for the given set of changed source files.
+ *
+ * @param {string[]} changedFiles - List of changed file paths (relative)
+ * @param {object} config - The .planning/config.json contents
+ * @param {string} [cwd] - Working directory for checking file existence (default: process.cwd())
+ * @returns {string[]} Array of test file paths, or ['--all'] for full suite
+ */
+function selectTests(changedFiles, config, cwd) {
+  if (!config || !config.features || !config.features.regression_prevention) {
+    return [];
+  }
+
+  const workDir = cwd || process.cwd();
+  const scope = getImpactScope(changedFiles);
+
+  // Config file changed: run full suite
+  if (scope.configChanged) {
+    return ['--all'];
+  }
+
+  const candidates = new Set();
+
+  // Apply file mapping rules to each changed file
+  for (const file of changedFiles) {
+    for (const rule of FILE_MAPPING_RULES) {
+      const match = file.match(rule.pattern);
+      if (match) {
+        candidates.add(rule.testPathFn(match));
+        break;
+      }
+    }
+  }
+
+  // Filter to only files that actually exist on disk
+  const existing = Array.from(candidates).filter(testFile => {
+    const fullPath = path.join(workDir, testFile);
+    return fs.existsSync(fullPath);
+  });
+
+  return existing;
+}
+
+/**
+ * Format a Jest command for the selected test files.
+ *
+ * @param {string[]} testFiles - Array of test file paths or ['--all']
+ * @returns {string} Jest CLI command
+ */
+function formatTestCommand(testFiles) {
+  if (testFiles.includes('--all')) {
+    return 'npx jest';
+  }
+  return `npx jest ${testFiles.join(' ')}`;
+}
+
+// ─── Exports ──────────────────────────────────────────────────────────────────
+
+module.exports = {
+  FILE_MAPPING_RULES,
+  getImpactScope,
+  selectTests,
+  formatTestCommand,
+};

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

@@ -0,0 +1,300 @@
+/**
+ * lib/todo.js — File-based todo operations for Plan-Build-Run.
+ *
+ * Todos are individual .md files with YAML frontmatter stored in:
+ *   .planning/todos/pending/{NNN}-{slug}.md  — active todos
+ *   .planning/todos/done/{NNN}-{slug}.md     — completed todos
+ *
+ * Frontmatter fields: title, status, priority, source, created, completed, theme.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { parseYamlFrontmatter, atomicWrite } = require('./core');
+
+// --- Helpers ---
+
+/**
+ * Parse a todo filename into its components.
+ * @param {string} filename - e.g. "042-fix-login-bug.md"
+ * @returns {{ number: number, slug: string } | null}
+ */
+function parseTodoFilename(filename) {
+  const match = filename.match(/^(\d+)-(.+)\.md$/);
+  if (!match) return null;
+  return { number: parseInt(match[1], 10), slug: match[2] };
+}
+
+/**
+ * Read and parse a single todo file.
+ * @param {string} filePath - Absolute path to the .md file
+ * @param {string} filename - Just the filename for parsing NNN-slug
+ * @returns {object} Todo object with number, slug, title, priority, theme, etc.
+ */
+function parseTodoFile(filePath, filename) {
+  const parsed = parseTodoFilename(filename);
+  const content = fs.readFileSync(filePath, 'utf8');
+  const fm = parseYamlFrontmatter(content);
+
+  // Extract body (everything after frontmatter closing ---)
+  const bodyMatch = content.match(/^---[\s\S]*?\n---\s*\n?([\s\S]*)$/);
+  const body = bodyMatch ? bodyMatch[1].trim() : '';
+
+  return {
+    number: parsed ? parsed.number : null,
+    slug: parsed ? parsed.slug : filename.replace(/\.md$/, ''),
+    filename,
+    title: fm.title || '',
+    status: fm.status || 'pending',
+    priority: fm.priority || 'P2',
+    theme: fm.theme || 'general',
+    source: fm.source || 'conversation',
+    created: fm.created || null,
+    completed: fm.completed || null,
+    body
+  };
+}
+
+/**
+ * Scan both pending/ and done/ to find the highest existing todo number.
+ * @param {string} planningDir - Path to .planning/
+ * @returns {number} Highest number found (0 if none)
+ */
+function findHighestNumber(planningDir) {
+  let highest = 0;
+  const dirs = [
+    path.join(planningDir, 'todos', 'pending'),
+    path.join(planningDir, 'todos', 'done')
+  ];
+  for (const dir of dirs) {
+    if (!fs.existsSync(dir)) continue;
+    const files = fs.readdirSync(dir).filter(f => f.endsWith('.md'));
+    for (const file of files) {
+      const parsed = parseTodoFilename(file);
+      if (parsed && parsed.number > highest) {
+        highest = parsed.number;
+      }
+    }
+  }
+  return highest;
+}
+
+/**
+ * Generate a slug from a description.
+ * Takes first ~4 meaningful words, lowercase, hyphen-separated.
+ * @param {string} description
+ * @returns {string}
+ */
+function generateSlug(description) {
+  const stopWords = new Set(['a', 'an', 'the', 'to', 'in', 'on', 'for', 'of', 'and', 'or', 'is', 'it', 'with']);
+  const words = description
+    .toLowerCase()
+    .replace(/[^a-z0-9\s-]/g, '')
+    .split(/\s+/)
+    .filter(w => w.length > 0 && !stopWords.has(w))
+    .slice(0, 4);
+  return words.join('-') || 'untitled';
+}
+
+// --- Core operations ---
+
+/**
+ * List todos from a directory (pending or done).
+ * @param {string} planningDir - Path to .planning/
+ * @param {object} opts - { status: 'pending'|'done'|'all', theme: string|null }
+ * @returns {{ todos: object[], count: number }}
+ */
+function todoList(planningDir, opts = {}) {
+  const status = opts.status || 'pending';
+  const theme = opts.theme || null;
+  const todos = [];
+
+  const dirsToScan = status === 'all'
+    ? ['pending', 'done']
+    : [status];
+
+  for (const subdir of dirsToScan) {
+    const dir = path.join(planningDir, 'todos', subdir);
+    if (!fs.existsSync(dir)) continue;
+
+    const files = fs.readdirSync(dir).filter(f => f.endsWith('.md')).sort();
+    for (const file of files) {
+      const todo = parseTodoFile(path.join(dir, file), file);
+      if (theme && todo.theme !== theme) continue;
+      todos.push(todo);
+    }
+  }
+
+  // Sort by number
+  todos.sort((a, b) => (a.number || 0) - (b.number || 0));
+
+  return { todos, count: todos.length };
+}
+
+/**
+ * Get a specific todo by its NNN number.
+ * Searches pending first, then done.
+ * @param {string} planningDir - Path to .planning/
+ * @param {number|string} num - The todo number (e.g. 42 or "042")
+ * @returns {object} Todo object with full body, or { error: "..." }
+ */
+function todoGet(planningDir, num) {
+  const numStr = String(num).padStart(3, '0');
+  const prefix = numStr + '-';
+
+  for (const subdir of ['pending', 'done']) {
+    const dir = path.join(planningDir, 'todos', subdir);
+    if (!fs.existsSync(dir)) continue;
+
+    const files = fs.readdirSync(dir).filter(f => f.startsWith(prefix) && f.endsWith('.md'));
+    if (files.length > 0) {
+      const todo = parseTodoFile(path.join(dir, files[0]), files[0]);
+      todo.location = subdir;
+      return todo;
+    }
+  }
+
+  return { error: `Todo ${numStr} not found in pending or done` };
+}
+
+/**
+ * Add a new todo.
+ * @param {string} planningDir - Path to .planning/
+ * @param {string} title - The todo description
+ * @param {object} opts - { priority: 'P1'|'P2'|'P3', theme: string, source: string }
+ * @returns {{ success: boolean, number: number, filename: string, path: string } | { error: string }}
+ */
+function todoAdd(planningDir, title, opts = {}) {
+  if (!title || !title.trim()) {
+    return { error: 'Title is required' };
+  }
+
+  const pendingDir = path.join(planningDir, 'todos', 'pending');
+
+  // Ensure directory exists
+  fs.mkdirSync(pendingDir, { recursive: true });
+
+  const nextNum = findHighestNumber(planningDir) + 1;
+  const numStr = String(nextNum).padStart(3, '0');
+  const slug = generateSlug(title);
+  const filename = `${numStr}-${slug}.md`;
+  const filePath = path.join(pendingDir, filename);
+
+  const priority = opts.priority || 'P2';
+  const theme = opts.theme || 'general';
+  const source = opts.source || 'cli';
+  const today = new Date().toISOString().slice(0, 10);
+
+  const content = [
+    '---',
+    `title: "${title.replace(/"/g, '\\"')}"`,
+    'status: pending',
+    `priority: ${priority}`,
+    `source: ${source}`,
+    `created: ${today}`,
+    `theme: ${theme}`,
+    '---',
+    '',
+    '## Goal',
+    '',
+    title,
+    ''
+  ].join('\n');
+
+  const result = atomicWrite(filePath, content);
+  if (!result.success) {
+    return { error: `Failed to write todo file: ${result.error}` };
+  }
+
+  return {
+    success: true,
+    number: nextNum,
+    number_padded: numStr,
+    filename,
+    path: filePath
+  };
+}
+
+/**
+ * Mark a todo as done. Moves from pending/ to done/.
+ * Write to done/ first, verify, then delete from pending/.
+ * @param {string} planningDir - Path to .planning/
+ * @param {number|string} num - The todo number
+ * @returns {{ success: boolean, title: string, filename: string } | { error: string }}
+ */
+function todoDone(planningDir, num) {
+  const numStr = String(num).padStart(3, '0');
+  const prefix = numStr + '-';
+
+  const pendingDir = path.join(planningDir, 'todos', 'pending');
+  const doneDir = path.join(planningDir, 'todos', 'done');
+
+  if (!fs.existsSync(pendingDir)) {
+    return { error: `Todo ${numStr} not found — no pending directory` };
+  }
+
+  const files = fs.readdirSync(pendingDir).filter(f => f.startsWith(prefix) && f.endsWith('.md'));
+  if (files.length === 0) {
+    return { error: `Todo ${numStr} not found in pending todos` };
+  }
+
+  const filename = files[0];
+  const pendingPath = path.join(pendingDir, filename);
+  const content = fs.readFileSync(pendingPath, 'utf8');
+  const fm = parseYamlFrontmatter(content);
+  const title = fm.title || '';
+  const today = new Date().toISOString().slice(0, 10);
+
+  // Update frontmatter: status → done, add completed date
+  let updatedContent = content
+    .replace(/^status:\s*.*/m, 'status: done')
+    .replace(/^(---[\s\S]*?)(---)/, (match, front, close) => {
+      // Add completed field if not present
+      if (!/^completed:/m.test(front)) {
+        return front + `completed: ${today}\n${close}`;
+      }
+      return match.replace(/^completed:\s*.*/m, `completed: ${today}`);
+    });
+
+  // Ensure done/ directory exists
+  fs.mkdirSync(doneDir, { recursive: true });
+
+  // Write to done/ FIRST
+  const donePath = path.join(doneDir, filename);
+  const writeResult = atomicWrite(donePath, updatedContent);
+  if (!writeResult.success) {
+    return { error: `Failed to write to done/: ${writeResult.error}. Pending file preserved.` };
+  }
+
+  // Verify done/ write succeeded
+  if (!fs.existsSync(donePath)) {
+    return { error: 'Done file not found after write. Pending file preserved.' };
+  }
+
+  // Only now delete from pending/
+  try {
+    fs.unlinkSync(pendingPath);
+  } catch (e) {
+    // Non-fatal — todo is in done/ now, pending copy is just stale
+    return {
+      success: true,
+      title,
+      filename,
+      warning: `Completed but could not remove from pending/: ${e.message}`
+    };
+  }
+
+  return { success: true, title, filename };
+}
+
+module.exports = {
+  todoList,
+  todoGet,
+  todoAdd,
+  todoDone,
+  // Exported for testing
+  parseTodoFilename,
+  parseTodoFile,
+  findHighestNumber,
+  generateSlug
+};

package/plugins/pbr/scripts/lib/trust-gate.js

@@ -0,0 +1,84 @@
+/**
+ * lib/trust-gate.js — Trust-gated verification depth selector.
+ *
+ * Reads agent trust scores from .planning/trust/scores.json and returns
+ * the appropriate verification depth (light/standard/thorough) based on
+ * historical pass rates.
+ *
+ * Thresholds:
+ *   > 90% pass rate  -> "light"   (skip deep verification)
+ *   >= 70% pass rate -> "standard" (normal verification)
+ *   < 70% pass rate  -> "thorough" (extra scrutiny)
+ *
+ * Safe defaults: returns "standard" when no trust data exists,
+ * data is malformed, or the feature is disabled.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+/** Pass rate above which verification is light (trusted agents). */
+const LIGHT_THRESHOLD = 0.90;
+
+/** Pass rate below which verification is thorough (untrusted agents). */
+const THOROUGH_THRESHOLD = 0.70;
+
+/**
+ * Resolve the verification depth based on trust scores and config.
+ *
+ * @param {string} planningDir - Path to the .planning directory
+ * @param {object} config - Config object with features.graduated_verification toggle
+ * @returns {"light"|"standard"|"thorough"} Verification depth
+ */
+function resolveVerificationDepth(planningDir, config) {
+  // Feature gate: if graduated_verification is disabled, always return standard
+  if (!config || !config.features || !config.features.graduated_verification) {
+    return 'standard';
+  }
+
+  // Read trust scores
+  const scoresPath = path.join(planningDir, 'trust', 'scores.json');
+  let scores;
+  try {
+    if (!fs.existsSync(scoresPath)) {
+      return 'standard';
+    }
+    scores = JSON.parse(fs.readFileSync(scoresPath, 'utf8'));
+  } catch (_e) {
+    // Malformed JSON or read error — safe default
+    return 'standard';
+  }
+
+  // Extract overall pass rate
+  let passRate;
+  if (typeof scores.overall_pass_rate === 'number') {
+    passRate = scores.overall_pass_rate;
+  } else if (scores.agents && typeof scores.agents === 'object') {
+    // Compute average from individual agent pass rates
+    const agents = Object.values(scores.agents);
+    const rates = agents
+      .map(a => a && typeof a.pass_rate === 'number' ? a.pass_rate : null)
+      .filter(r => r !== null);
+    if (rates.length === 0) {
+      return 'standard';
+    }
+    passRate = rates.reduce((sum, r) => sum + r, 0) / rates.length;
+  } else {
+    return 'standard';
+  }
+
+  // Apply thresholds
+  if (passRate > LIGHT_THRESHOLD) {
+    return 'light';
+  }
+  if (passRate < THOROUGH_THRESHOLD) {
+    return 'thorough';
+  }
+  return 'standard';
+}
+
+module.exports = {
+  resolveVerificationDepth,
+  LIGHT_THRESHOLD,
+  THOROUGH_THRESHOLD
+};