@sienklogic/plan-build-run 2.1.0 → 2.1.1

package/plan-build-run/bin/lib/step-verify.cjs

@@ -0,0 +1,149 @@
+'use strict';
+
+/**
+ * lib/step-verify.cjs -- 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.cjs):
+ *   node pbr-tools.cjs 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 };

package/plan-build-run/bin/lib/template.cjs

@@ -0,0 +1,222 @@
+/**
+ * Template — Template selection and fill operations
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { normalizePhaseName, findPhaseInternal, generateSlugInternal, toPosixPath, output, error } = require('./core.cjs');
+const { reconstructFrontmatter } = require('./frontmatter.cjs');
+
+function cmdTemplateSelect(cwd, planPath, raw) {
+  if (!planPath) {
+    error('plan-path required');
+  }
+
+  try {
+    const fullPath = path.join(cwd, planPath);
+    const content = fs.readFileSync(fullPath, 'utf-8');
+
+    // Simple heuristics
+    const taskMatch = content.match(/###\s*Task\s*\d+/g) || [];
+    const taskCount = taskMatch.length;
+
+    const decisionMatch = content.match(/decision/gi) || [];
+    const hasDecisions = decisionMatch.length > 0;
+
+    // Count file mentions
+    const fileMentions = new Set();
+    const filePattern = /`([^`]+\.[a-zA-Z]+)`/g;
+    let m;
+    while ((m = filePattern.exec(content)) !== null) {
+      if (m[1].includes('/') && !m[1].startsWith('http')) {
+        fileMentions.add(m[1]);
+      }
+    }
+    const fileCount = fileMentions.size;
+
+    let template = 'templates/summary-standard.md';
+    let type = 'standard';
+
+    if (taskCount <= 2 && fileCount <= 3 && !hasDecisions) {
+      template = 'templates/summary-minimal.md';
+      type = 'minimal';
+    } else if (hasDecisions || fileCount > 6 || taskCount > 5) {
+      template = 'templates/summary-complex.md';
+      type = 'complex';
+    }
+
+    const result = { template, type, taskCount, fileCount, hasDecisions };
+    output(result, raw, template);
+  } catch (e) {
+    // Fallback to standard
+    output({ template: 'templates/summary-standard.md', type: 'standard', error: e.message }, raw, 'templates/summary-standard.md');
+  }
+}
+
+function cmdTemplateFill(cwd, templateType, options, raw) {
+  if (!templateType) { error('template type required: summary, plan, or verification'); }
+  if (!options.phase) { error('--phase required'); }
+
+  const phaseInfo = findPhaseInternal(cwd, options.phase);
+  if (!phaseInfo || !phaseInfo.found) { output({ error: 'Phase not found', phase: options.phase }, raw); return; }
+
+  const padded = normalizePhaseName(options.phase);
+  const today = new Date().toISOString().split('T')[0];
+  const phaseName = options.name || phaseInfo.phase_name || 'Unnamed';
+  const phaseSlug = phaseInfo.phase_slug || generateSlugInternal(phaseName);
+  const phaseId = `${padded}-${phaseSlug}`;
+  const planNum = (options.plan || '01').padStart(2, '0');
+  const fields = options.fields || {};
+
+  let frontmatter, body, fileName;
+
+  switch (templateType) {
+    case 'summary': {
+      frontmatter = {
+        phase: phaseId,
+        plan: planNum,
+        subsystem: '[primary category]',
+        tags: [],
+        provides: [],
+        affects: [],
+        'tech-stack': { added: [], patterns: [] },
+        'key-files': { created: [], modified: [] },
+        'key-decisions': [],
+        'patterns-established': [],
+        duration: '[X]min',
+        completed: today,
+        ...fields,
+      };
+      body = [
+        `# Phase ${options.phase}: ${phaseName} Summary`,
+        '',
+        '**[Substantive one-liner describing outcome]**',
+        '',
+        '## Performance',
+        '- **Duration:** [time]',
+        '- **Tasks:** [count completed]',
+        '- **Files modified:** [count]',
+        '',
+        '## Accomplishments',
+        '- [Key outcome 1]',
+        '- [Key outcome 2]',
+        '',
+        '## Task Commits',
+        '1. **Task 1: [task name]** - `hash`',
+        '',
+        '## Files Created/Modified',
+        '- `path/to/file.ts` - What it does',
+        '',
+        '## Decisions & Deviations',
+        '[Key decisions or "None - followed plan as specified"]',
+        '',
+        '## Next Phase Readiness',
+        '[What\'s ready for next phase]',
+      ].join('\n');
+      fileName = `${padded}-${planNum}-SUMMARY.md`;
+      break;
+    }
+    case 'plan': {
+      const planType = options.type || 'execute';
+      const wave = parseInt(options.wave) || 1;
+      frontmatter = {
+        phase: phaseId,
+        plan: planNum,
+        type: planType,
+        wave,
+        depends_on: [],
+        files_modified: [],
+        autonomous: true,
+        user_setup: [],
+        must_haves: { truths: [], artifacts: [], key_links: [] },
+        ...fields,
+      };
+      body = [
+        `# Phase ${options.phase} Plan ${planNum}: [Title]`,
+        '',
+        '## Objective',
+        '- **What:** [What this plan builds]',
+        '- **Why:** [Why it matters for the phase goal]',
+        '- **Output:** [Concrete deliverable]',
+        '',
+        '## Context',
+        '@.planning/PROJECT.md',
+        '@.planning/ROADMAP.md',
+        '@.planning/STATE.md',
+        '',
+        '## Tasks',
+        '',
+        '<task type="code">',
+        '  <name>[Task name]</name>',
+        '  <files>[file paths]</files>',
+        '  <action>[What to do]</action>',
+        '  <verify>[How to verify]</verify>',
+        '  <done>[Definition of done]</done>',
+        '</task>',
+        '',
+        '## Verification',
+        '[How to verify this plan achieved its objective]',
+        '',
+        '## Success Criteria',
+        '- [ ] [Criterion 1]',
+        '- [ ] [Criterion 2]',
+      ].join('\n');
+      fileName = `${padded}-${planNum}-PLAN.md`;
+      break;
+    }
+    case 'verification': {
+      frontmatter = {
+        phase: phaseId,
+        verified: new Date().toISOString(),
+        status: 'pending',
+        score: '0/0 must-haves verified',
+        ...fields,
+      };
+      body = [
+        `# Phase ${options.phase}: ${phaseName} — Verification`,
+        '',
+        '## Observable Truths',
+        '| # | Truth | Status | Evidence |',
+        '|---|-------|--------|----------|',
+        '| 1 | [Truth] | pending | |',
+        '',
+        '## Required Artifacts',
+        '| Artifact | Expected | Status | Details |',
+        '|----------|----------|--------|---------|',
+        '| [path] | [what] | pending | |',
+        '',
+        '## Key Link Verification',
+        '| From | To | Via | Status | Details |',
+        '|------|----|----|--------|---------|',
+        '| [source] | [target] | [connection] | pending | |',
+        '',
+        '## Requirements Coverage',
+        '| Requirement | Status | Blocking Issue |',
+        '|-------------|--------|----------------|',
+        '| [req] | pending | |',
+        '',
+        '## Result',
+        '[Pending verification]',
+      ].join('\n');
+      fileName = `${padded}-VERIFICATION.md`;
+      break;
+    }
+    default:
+      error(`Unknown template type: ${templateType}. Available: summary, plan, verification`);
+      return;
+  }
+
+  const fullContent = `---\n${reconstructFrontmatter(frontmatter)}\n---\n\n${body}\n`;
+  const outPath = path.join(cwd, phaseInfo.directory, fileName);
+
+  if (fs.existsSync(outPath)) {
+    output({ error: 'File already exists', path: toPosixPath(path.relative(cwd, outPath)) }, raw);
+    return;
+  }
+
+  fs.writeFileSync(outPath, fullContent, 'utf-8');
+  const relPath = toPosixPath(path.relative(cwd, outPath));
+  output({ created: true, path: relPath, template: templateType }, raw, relPath);
+}
+
+module.exports = { cmdTemplateSelect, cmdTemplateFill };

package/plan-build-run/bin/lib/todo.cjs

@@ -0,0 +1,300 @@
+/**
+ * lib/todo.cjs -- 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.cjs');
+
+// --- 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
+};