@sienklogic/plan-build-run 2.21.1 → 2.21.2

package/plugins/pbr/scripts/lib/negative-knowledge.js

@@ -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');
+
+// ─── 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/plugins/pbr/scripts/lib/notification-throttle.js

@@ -0,0 +1,141 @@
+#!/usr/bin/env node
+
+/**
+ * Notification throttle module for hook messages.
+ *
+ * Provides time-window-based message deduplication with bypass rules
+ * for interactive mode and critical messages. Multiple hooks sharing
+ * one process (via hook-server) share the default singleton state.
+ *
+ * Usage:
+ *   const { shouldThrottle, isCriticalMessage } = require('./lib/notification-throttle');
+ *   if (shouldThrottle(state, 'hook:context-bridge:DEGRADING', { isAutonomous: true })) {
+ *     return; // suppress duplicate
+ *   }
+ */
+
+'use strict';
+
+/** Default options for shouldThrottle */
+const DEFAULTS = {
+  windowMs: 60000,
+  maxPerWindow: 3,
+  isAutonomous: false,
+  isCritical: false
+};
+
+/** Patterns that indicate a critical message (case-insensitive) */
+const CRITICAL_PATTERNS = [
+  /error/i,
+  /\bSTOP\b/,
+  /block/i,
+  /failed/i,
+  /CRITICAL/i,
+  /checkpoint/i
+];
+
+/**
+ * Create a fresh throttle state object.
+ * @returns {{ seen: Map, startTime: number }}
+ */
+function createThrottleState() {
+  return {
+    seen: new Map(),
+    startTime: Date.now()
+  };
+}
+
+/**
+ * Determine whether a message with the given key should be suppressed.
+ *
+ * @param {{ seen: Map, startTime: number }} state - Throttle state from createThrottleState()
+ * @param {string} key - Deduplication key (e.g. "hook:context-bridge:DEGRADING")
+ * @param {Object} [options] - Throttle options
+ * @param {number} [options.windowMs=60000] - Time window in milliseconds
+ * @param {number} [options.maxPerWindow=3] - Max messages allowed per window
+ * @param {boolean} [options.isAutonomous=false] - Whether running in autonomous mode
+ * @param {boolean} [options.isCritical=false] - Whether this is a critical message
+ * @returns {boolean} true if the message should be suppressed (throttled)
+ */
+function shouldThrottle(state, key, options) {
+  const opts = { ...DEFAULTS, ...options };
+
+  // Interactive mode: never throttle
+  if (!opts.isAutonomous) return false;
+
+  // Critical messages: never throttle
+  if (opts.isCritical) return false;
+
+  const now = Date.now();
+  const entry = state.seen.get(key);
+
+  // No entry or window expired: reset and allow
+  if (!entry || (now - entry.firstSeen) > opts.windowMs) {
+    state.seen.set(key, { count: 1, firstSeen: now, lastSeen: now });
+    return false;
+  }
+
+  // Within window and at or over limit: suppress
+  if (entry.count >= opts.maxPerWindow) {
+    entry.lastSeen = now;
+    return true;
+  }
+
+  // Within window, under limit: increment and allow
+  entry.count++;
+  entry.lastSeen = now;
+  return false;
+}
+
+/**
+ * Reset all throttle state, clearing tracked messages.
+ * @param {{ seen: Map, startTime: number }} state - Throttle state to reset
+ */
+function resetThrottle(state) {
+  state.seen.clear();
+  state.startTime = Date.now();
+}
+
+/**
+ * Check whether a message string contains critical content that should
+ * never be throttled (errors, blocks, checkpoints, etc.).
+ *
+ * @param {string} message - The message to check
+ * @returns {boolean} true if the message is critical
+ */
+function isCriticalMessage(message) {
+  if (typeof message !== 'string') return false;
+
+  // Check for JSON-style decision/reason keys at the start
+  const trimmed = message.trimStart();
+  if (trimmed.startsWith('"decision"') || trimmed.startsWith('"reason"') ||
+      trimmed.startsWith('{"decision"') || trimmed.startsWith('{"reason"')) {
+    return true;
+  }
+
+  return CRITICAL_PATTERNS.some(pattern => pattern.test(message));
+}
+
+/** Module-level singleton state shared across hooks in one process */
+const _defaultState = createThrottleState();
+
+/**
+ * Convenience wrapper using the module-level singleton state.
+ * Useful when multiple hooks share one process (hook-server).
+ *
+ * @param {string} key - Deduplication key
+ * @param {Object} [options] - Same options as shouldThrottle()
+ * @returns {boolean} true if the message should be suppressed
+ */
+function shouldThrottleDefault(key, options) {
+  return shouldThrottle(_defaultState, key, options);
+}
+
+module.exports = {
+  createThrottleState,
+  shouldThrottle,
+  resetThrottle,
+  isCriticalMessage,
+  shouldThrottleDefault,
+  _defaultState
+};

package/plugins/pbr/scripts/lib/onboarding-generator.js

@@ -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');
+    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,
+};