@sienklogic/plan-build-run 2.12.0 → 2.12.1

package/plan-build-run/bin/lib/negative-knowledge.cjs

@@ -0,0 +1,194 @@
+/**
+ * Negative Knowledge — tracking, querying, and resolving failure entries
+ *
+ * Stores entries as .planning/negative-knowledge/{YYYY-MM-DD}-{slug}.md
+ * Each entry has YAML frontmatter (date, title, category, files_involved, phase, status)
+ * and body sections: What Was Tried, Why It Failed, What Worked Instead.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { extractFrontmatter, spliceFrontmatter } = require('./frontmatter.cjs');
+
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+
+function nkDir(planningDir) {
+  return path.join(planningDir, 'negative-knowledge');
+}
+
+function slugify(text) {
+  return text
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 60);
+}
+
+function todayISO() {
+  return new Date().toISOString().slice(0, 10);
+}
+
+// ─── Core functions ──────────────────────────────────────────────────────────
+
+/**
+ * Record a failure entry.
+ * @param {string} planningDir - Path to .planning directory
+ * @param {object} opts
+ * @param {string} opts.title
+ * @param {string} opts.category - One of: verification-gap, build-failure, plan-revision, debug-finding
+ * @param {string[]} opts.filesInvolved
+ * @param {string} opts.whatTried
+ * @param {string} opts.whyFailed
+ * @param {string} [opts.whatWorked='']
+ * @param {string} [opts.phase='']
+ * @returns {{ path: string, slug: string }}
+ */
+function recordFailure(planningDir, opts) {
+  const dir = nkDir(planningDir);
+  fs.mkdirSync(dir, { recursive: true });
+
+  const date = todayISO();
+  const slug = slugify(opts.title);
+  const filename = `${date}-${slug}.md`;
+  const filePath = path.join(dir, filename);
+
+  // Build YAML frontmatter
+  const filesYaml = opts.filesInvolved
+    .map(f => `  - ${f}`)
+    .join('\n');
+
+  const content = `---
+date: ${date}
+title: ${opts.title}
+category: ${opts.category}
+files_involved:
+${filesYaml}
+phase: ${opts.phase || ''}
+status: active
+---
+
+## What Was Tried
+
+${opts.whatTried}
+
+## Why It Failed
+
+${opts.whyFailed}
+
+## What Worked Instead
+
+${opts.whatWorked || 'Pending resolution.'}
+`;
+
+  fs.writeFileSync(filePath, content, 'utf8');
+  return { path: filePath, slug };
+}
+
+/**
+ * Query entries by file path overlap.
+ * @param {string} planningDir
+ * @param {string[]} filePaths - Paths to match against files_involved
+ * @returns {object[]} Matching entries sorted by date descending
+ */
+function queryByFiles(planningDir, filePaths) {
+  const entries = readAllEntries(planningDir);
+  const fileSet = new Set(filePaths);
+
+  return entries
+    .filter(entry => {
+      const involved = entry.files_involved || [];
+      return involved.some(f => fileSet.has(f));
+    })
+    .sort((a, b) => (b.date || '').localeCompare(a.date || ''));
+}
+
+/**
+ * List failure entries with optional filters.
+ * @param {string} planningDir
+ * @param {object} filters
+ * @param {string} [filters.category]
+ * @param {string} [filters.phase]
+ * @param {string} [filters.status]
+ * @returns {object[]} Matching entries sorted by date descending
+ */
+function listFailures(planningDir, filters) {
+  let entries = readAllEntries(planningDir);
+
+  if (filters.category) {
+    entries = entries.filter(e => e.category === filters.category);
+  }
+  if (filters.phase) {
+    entries = entries.filter(e => e.phase === filters.phase);
+  }
+  if (filters.status) {
+    entries = entries.filter(e => e.status === filters.status);
+  }
+
+  return entries.sort((a, b) => (b.date || '').localeCompare(a.date || ''));
+}
+
+/**
+ * Mark an entry as resolved by slug.
+ * @param {string} planningDir
+ * @param {string} slug
+ */
+function resolveEntry(planningDir, slug) {
+  const dir = nkDir(planningDir);
+  if (!fs.existsSync(dir)) return;
+
+  const files = fs.readdirSync(dir).filter(f => f.endsWith('.md'));
+  for (const file of files) {
+    if (file.includes(slug)) {
+      const filePath = path.join(dir, file);
+      const content = fs.readFileSync(filePath, 'utf8');
+      // Replace status: active with status: resolved in frontmatter
+      const fm = extractFrontmatter(content);
+      fm.status = 'resolved';
+      const newContent = spliceFrontmatter(content, fm);
+      fs.writeFileSync(filePath, newContent, 'utf8');
+      return;
+    }
+  }
+}
+
+// ─── Internal helpers ────────────────────────────────────────────────────────
+
+/**
+ * Read all entries from the negative-knowledge directory.
+ * @param {string} planningDir
+ * @returns {object[]} Array of parsed entry objects
+ */
+function readAllEntries(planningDir) {
+  const dir = nkDir(planningDir);
+  if (!fs.existsSync(dir)) return [];
+
+  const files = fs.readdirSync(dir).filter(f => f.endsWith('.md'));
+  const entries = [];
+
+  for (const file of files) {
+    const filePath = path.join(dir, file);
+    const content = fs.readFileSync(filePath, 'utf8');
+    const fm = extractFrontmatter(content);
+
+    // Parse files_involved — extractFrontmatter may return it as array or object
+    let filesInvolved = fm.files_involved || [];
+    if (!Array.isArray(filesInvolved)) {
+      filesInvolved = Object.values(filesInvolved);
+    }
+
+    entries.push({
+      slug: file.replace(/^\d{4}-\d{2}-\d{2}-/, '').replace(/\.md$/, ''),
+      date: fm.date || '',
+      title: fm.title || '',
+      category: fm.category || '',
+      files_involved: filesInvolved,
+      phase: (typeof fm.phase === 'string' ? fm.phase : '') || '',
+      status: fm.status || 'active',
+      path: filePath,
+    });
+  }
+
+  return entries;
+}
+
+module.exports = { recordFailure, queryByFiles, listFailures, resolveEntry };

package/plan-build-run/bin/lib/onboarding-generator.cjs

@@ -0,0 +1,288 @@
+'use strict';
+
+/**
+ * lib/onboarding-generator.cjs — Team onboarding guide generator.
+ *
+ * Reads ROADMAP.md, CONTEXT.md, PROJECT.md, conventions/, STATE.md, and notes/
+ * to produce a structured walkthrough document for new team members.
+ *
+ * Provides:
+ *   generateOnboardingGuide(planningDir, config) — structured guide with markdown
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+// ─── Disabled stub ────────────────────────────────────────────────────────────
+
+const DISABLED_STUB = {
+  enabled: false,
+  sections: [],
+  markdown: '',
+};
+
+// ─── Section builders ─────────────────────────────────────────────────────────
+
+/**
+ * Build project overview section from PROJECT.md.
+ */
+function buildOverviewSection(planningDir) {
+  const projectPath = path.join(planningDir, 'PROJECT.md');
+  if (!fs.existsSync(projectPath)) return null;
+
+  const content = fs.readFileSync(projectPath, 'utf8');
+  // Extract first heading as project name
+  const nameMatch = content.match(/^#\s+(.+)/m);
+  const projectName = nameMatch ? nameMatch[1].trim() : 'This Project';
+
+  // Extract a few key sections
+  const sections = [];
+  const whatMatch = content.match(/##\s+What This Is\s*\n+([\s\S]*?)(?=\n##|\n#|$)/);
+  const valueMatch = content.match(/##\s+Core Value\s*\n+([\s\S]*?)(?=\n##|\n#|$)/);
+
+  if (whatMatch) sections.push(whatMatch[1].trim());
+  if (valueMatch) sections.push(`**Core Value:** ${valueMatch[1].trim().split('\n')[0]}`);
+
+  const summaryContent = sections.join('\n\n') || content.slice(0, 500);
+
+  return {
+    title: 'Project Overview',
+    content: `**${projectName}**\n\n${summaryContent}`,
+    source: projectPath,
+  };
+}
+
+/**
+ * Build development phases section from ROADMAP.md.
+ */
+function buildPhasesSection(planningDir) {
+  const roadmapPath = path.join(planningDir, 'ROADMAP.md');
+  if (!fs.existsSync(roadmapPath)) return null;
+
+  const content = fs.readFileSync(roadmapPath, 'utf8');
+
+  // Extract phase headings
+  const phases = [];
+  const phaseRe = /^#{2,4}\s*Phase\s+(\d+(?:\.\d+)*)\s*:\s*([^\n]+)/gim;
+  let m;
+  while ((m = phaseRe.exec(content)) !== null) {
+    phases.push(`- Phase ${m[1]}: ${m[2].trim()}`);
+  }
+
+  if (phases.length === 0) return null;
+
+  return {
+    title: 'Development Phases',
+    content: `The project is organized into ${phases.length} phases:\n\n${phases.join('\n')}`,
+    source: roadmapPath,
+  };
+}
+
+/**
+ * Build key decisions section from CONTEXT.md.
+ */
+function buildDecisionsSection(planningDir) {
+  const contextPath = path.join(planningDir, 'CONTEXT.md');
+  if (!fs.existsSync(contextPath)) return null;
+
+  const content = fs.readFileSync(contextPath, 'utf8');
+
+  // Extract locked decisions section
+  const lockedMatch = content.match(/##\s+Locked\s+Decisions?\s*\n+([\s\S]*?)(?=\n##|\n#|$)/i);
+  const decisionsMatch = content.match(/##\s+Decisions?\s*\n+([\s\S]*?)(?=\n##|\n#|$)/i);
+
+  const decisionsContent = (lockedMatch || decisionsMatch);
+  if (!decisionsContent) {
+    // If no specific section, include first non-empty content
+    const lines = content.split('\n').filter(l => l.trim() && !l.startsWith('#')).slice(0, 10);
+    if (lines.length === 0) return null;
+    return {
+      title: 'Key Decisions',
+      content: lines.join('\n'),
+      source: contextPath,
+    };
+  }
+
+  return {
+    title: 'Key Decisions',
+    content: decisionsContent[1].trim(),
+    source: contextPath,
+  };
+}
+
+/**
+ * Build conventions section from .planning/conventions/ directory.
+ */
+function buildConventionsSection(planningDir) {
+  const conventionsDir = path.join(planningDir, 'conventions');
+  if (!fs.existsSync(conventionsDir)) return null;
+
+  let files;
+  try {
+    files = fs.readdirSync(conventionsDir).filter(f => f.endsWith('.md'));
+  } catch (_e) {
+    return null;
+  }
+
+  if (files.length === 0) return null;
+
+  const items = files.map(f => {
+    const filePath = path.join(conventionsDir, f);
+    const content = fs.readFileSync(filePath, 'utf8');
+    const titleMatch = content.match(/^#\s+(.+)/m);
+    const title = titleMatch ? titleMatch[1].trim() : f.replace('.md', '');
+    // Get first non-heading, non-empty line as summary
+    const summary = content.split('\n').filter(l => l.trim() && !l.startsWith('#'))[0] || '';
+    return `- **${title}**: ${summary}`;
+  });
+
+  return {
+    title: 'Conventions',
+    content: items.join('\n'),
+    source: conventionsDir,
+  };
+}
+
+/**
+ * Build current status section from STATE.md.
+ */
+function buildStatusSection(planningDir) {
+  const statePath = path.join(planningDir, 'STATE.md');
+  if (!fs.existsSync(statePath)) return null;
+
+  const content = fs.readFileSync(statePath, 'utf8');
+
+  // Extract frontmatter status
+  const statusMatch = content.match(/^status:\s*["']?([^"'\r\n]+)["']?/m);
+  const currentStatus = statusMatch ? statusMatch[1].trim() : 'unknown';
+
+  // Extract current phase reference
+  const phaseMatch = content.match(/Phase:\s*(\d+[^\n]*)/);
+  const currentPhase = phaseMatch ? phaseMatch[1].trim() : null;
+
+  const lines = [`**Current Status:** ${currentStatus}`];
+  if (currentPhase) lines.push(`**Current Phase:** ${currentPhase}`);
+  lines.push('');
+  lines.push('Run `/pbr:status` for full project details, or `/pbr:build` to continue building.');
+
+  return {
+    title: 'Current Status',
+    content: lines.join('\n'),
+    source: statePath,
+  };
+}
+
+/**
+ * Build important notes section from .planning/notes/.
+ */
+function buildNotesSection(planningDir) {
+  const notesDir = path.join(planningDir, 'notes');
+  if (!fs.existsSync(notesDir)) return null;
+
+  let files;
+  try {
+    files = fs.readdirSync(notesDir).filter(f => f.endsWith('.md'));
+  } catch (_e) {
+    return null;
+  }
+
+  if (files.length === 0) return null;
+
+  const items = files.slice(0, 10).map(f => `- ${f.replace('.md', '')}`);
+
+  return {
+    title: 'Important Notes',
+    content: `${items.length} note(s) available in .planning/notes/:\n\n${items.join('\n')}`,
+    source: notesDir,
+  };
+}
+
+// ─── Markdown renderer ────────────────────────────────────────────────────────
+
+/**
+ * Render sections into a markdown onboarding document.
+ *
+ * @param {string} projectName - Name of the project
+ * @param {Array<{title: string, content: string, source: string}>} sections
+ * @returns {string}
+ */
+function renderMarkdown(projectName, sections) {
+  const lines = [`# Getting Started with ${projectName}`, ''];
+
+  for (const section of sections) {
+    lines.push(`## ${section.title}`);
+    lines.push('');
+    lines.push(section.content);
+    lines.push('');
+    lines.push(`*Source: ${section.source}*`);
+    lines.push('');
+  }
+
+  return lines.join('\n');
+}
+
+// ─── Main function ─────────────────────────────────────────────────────────────
+
+/**
+ * Generate a structured onboarding guide from available .planning/ files.
+ *
+ * @param {string} planningDir - Path to .planning/ directory
+ * @param {object|null} config  - Parsed config object
+ * @returns {{ enabled: boolean, sections: Array, markdown: string, generatedAt: string }}
+ */
+function generateOnboardingGuide(planningDir, config) {
+  const features = (config && config.features) || {};
+
+  // Check feature toggle (default: enabled)
+  if (features.team_onboarding === false) {
+    return { ...DISABLED_STUB };
+  }
+
+  // Build sections from available files
+  const rawSections = [
+    buildOverviewSection(planningDir),
+    buildPhasesSection(planningDir),
+    buildDecisionsSection(planningDir),
+    buildConventionsSection(planningDir),
+    buildStatusSection(planningDir),
+    buildNotesSection(planningDir),
+  ].filter(Boolean);
+
+  // Determine project name
+  const projectPath = path.join(planningDir, 'PROJECT.md');
+  let projectName = 'the Project';
+  if (fs.existsSync(projectPath)) {
+    const content = fs.readFileSync(projectPath, 'utf8');
+    const m = content.match(/^#\s+(.+)/m);
+    if (m) projectName = m[1].trim();
+  }
+
+  const markdown = renderMarkdown(projectName, rawSections);
+
+  // Log audit evidence
+  try {
+    const { logAuditEvidence } = require('./progress-visualization.cjs');
+    logAuditEvidence(planningDir, 'team_onboarding', 'ok');
+  } catch (_e) {
+    // Non-fatal
+  }
+
+  return {
+    enabled: true,
+    sections: rawSections,
+    markdown,
+    generatedAt: new Date().toISOString(),
+  };
+}
+
+// ─── Exports ──────────────────────────────────────────────────────────────────
+
+module.exports = {
+  generateOnboardingGuide,
+  buildOverviewSection,
+  buildPhasesSection,
+  buildDecisionsSection,
+  buildConventionsSection,
+  buildStatusSection,
+  buildNotesSection,
+};

package/plan-build-run/bin/lib/parse-args.cjs

@@ -0,0 +1,134 @@
+/**
+ * parse-args.cjs — CLI argument parsing and validation for PBR skills.
+ *
+ * Provides structured validation of user input before skills process it,
+ * replacing fragile prose-based guards with deterministic CLI checks.
+ */
+
+'use strict';
+
+/**
+ * Parse and validate arguments for /pbr:plan
+ *
+ * Valid patterns:
+ *   ""              → empty, skill will prompt
+ *   "3" or "03"     → bare phase number
+ *   "3 --gaps"      → phase number with flags
+ *   "3 --gaps --auto" → phase number with multiple flags
+ *
+ * Invalid:
+ *   "write me a function" → freeform text
+ *   "3 4 5"               → multiple numbers
+ *   "auth-module"         → non-numeric non-flag token
+ */
+function parsePlan(rawInput) {
+  const raw = (rawInput || '').trim();
+
+  // Empty input is valid — skill will prompt for phase number
+  if (!raw) {
+    return { valid: true, phase: null, flags: {}, raw: '' };
+  }
+
+  const tokens = raw.split(/\s+/);
+  const flags = { gaps: false, auto: false };
+  const knownFlags = new Set(['--gaps', '--auto']);
+  let phase = null;
+  const nonFlagTokens = [];
+
+  for (const token of tokens) {
+    if (token.startsWith('--')) {
+      if (knownFlags.has(token)) {
+        flags[token.slice(2)] = true;
+      } else {
+        return {
+          valid: false,
+          phase: null,
+          flags: {},
+          error: `Unknown flag: '${token}'. Expected: /pbr:plan <phase-number> [--gaps] [--auto]`,
+          raw
+        };
+      }
+    } else {
+      nonFlagTokens.push(token);
+    }
+  }
+
+  // Must have exactly 0 or 1 non-flag tokens
+  if (nonFlagTokens.length > 1) {
+    return {
+      valid: false,
+      phase: null,
+      flags: {},
+      error: `Invalid argument: '${raw}'. Expected: /pbr:plan <phase-number> [--gaps] [--auto]`,
+      raw
+    };
+  }
+
+  if (nonFlagTokens.length === 1) {
+    const candidate = nonFlagTokens[0];
+    // Must be a number (with optional leading zeros)
+    if (/^\d+$/.test(candidate)) {
+      phase = parseInt(candidate, 10);
+    } else {
+      return {
+        valid: false,
+        phase: null,
+        flags: {},
+        error: `Invalid argument: '${candidate}'. Expected: /pbr:plan <phase-number> [--gaps] [--auto]`,
+        raw
+      };
+    }
+  }
+
+  // Flags without a phase number are invalid (e.g. "--gaps" alone)
+  if (phase === null && (flags.gaps || flags.auto)) {
+    return {
+      valid: false,
+      phase: null,
+      flags: {},
+      error: `Flags require a phase number. Expected: /pbr:plan <phase-number> [--gaps] [--auto]`,
+      raw
+    };
+  }
+
+  return { valid: true, phase, flags, raw };
+}
+
+/**
+ * Parse and validate arguments for /pbr:quick
+ *
+ * Quick accepts freeform text as a task description. Always valid unless empty.
+ */
+function parseQuick(rawInput) {
+  const raw = (rawInput || '').trim();
+
+  if (!raw) {
+    return {
+      valid: false,
+      description: null,
+      error: 'Description required for /pbr:quick',
+      raw: ''
+    };
+  }
+
+  return { valid: true, description: raw, raw };
+}
+
+/**
+ * Dispatch parse-args by type
+ */
+function parseArgs(type, rawInput) {
+  switch (type) {
+    case 'plan':
+      return parsePlan(rawInput);
+    case 'quick':
+      return parseQuick(rawInput);
+    default:
+      return {
+        valid: false,
+        error: `Unknown parse-args type: '${type}'. Supported: plan, quick`
+      };
+  }
+}
+
+module.exports = { parseArgs, parsePlan, parseQuick };