@sienklogic/plan-build-run 2.19.0 → 2.19.2

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

@@ -0,0 +1,511 @@
+'use strict';
+
+/**
+ * learnings.cjs -- Global cross-project learnings store for Plan-Build-Run.
+ *
+ * Storage: JSONL at ~/.claude/learnings.jsonl
+ * Schema v1: id, source_project, type, tags, confidence, occurrences, summary, detail, custom_tags
+ *
+ * Usage (library):
+ *   const { learningsIngest, learningsQuery } = require('./learnings');
+ *
+ * Usage (CLI via pbr-tools.js):
+ *   node pbr-tools.js learnings ingest <json-file>
+ *   node pbr-tools.js learnings query [--tags X] [--min-confidence Y] [--stack S] [--type T]
+ *   node pbr-tools.js learnings check-thresholds
+ */
+
+const os = require('os');
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+
+// --- Constants ---
+
+const GLOBAL_LEARNINGS_PATH = path.join(os.homedir(), '.claude', 'learnings.jsonl');
+
+// Schema v1 type taxonomy
+const LEARNING_TYPES = [
+  'tech-pattern',        // positive: "this tech/pattern worked well"
+  'anti-pattern',        // negative: "avoid this approach"
+  'estimation-metric',   // timing/sizing data (e.g., "OAuth takes ~3 phases")
+  'planning-failure',    // what went wrong in planning
+  'deferred-item',       // common deferrals with trigger conditions
+  'stack-insight',       // tech stack compatibility facts
+  'process-win',         // positive process patterns
+  'process-failure'      // negative process patterns
+];
+
+// Confidence tiers based on occurrence count
+const CONFIDENCE_TIERS = { low: 1, medium: 2, high: 3 };
+
+// Deferral thresholds for the 4 deferred items from phase 45
+const DEFERRAL_THRESHOLDS = [
+  { key: 'organic-taxonomy',       trigger: 'count > 50',   check: (count) => count > 50 },
+  { key: 'statistical-confidence', trigger: 'any_tag >= 20', check: (_c, tagMax) => tagMax >= 20 },
+  { key: 'audit-integration',      trigger: 'audits > 10',  check: (_c, _t, audits) => audits > 10 },
+  { key: 'executor-injection',     trigger: 'queries > 30', check: (_c, _t, _a, queries) => queries > 30 }
+];
+
+// --- Core functions ---
+
+/**
+ * Compute confidence tier from occurrence count.
+ * @param {number} occurrences
+ * @returns {'low'|'medium'|'high'}
+ */
+function computeConfidence(occurrences) {
+  if (occurrences >= 3) return 'high';
+  if (occurrences === 2) return 'medium';
+  return 'low';
+}
+
+/**
+ * Validate a learning entry against schema v1.
+ * @param {object} entry
+ * @returns {{ valid: boolean, errors: string[] }}
+ */
+function validateEntry(entry) {
+  const errors = [];
+
+  if (!entry) {
+    return { valid: false, errors: ['entry is null or undefined'] };
+  }
+
+  // Required fields
+  const required = ['id', 'source_project', 'type', 'tags', 'confidence', 'occurrences', 'summary'];
+  for (const field of required) {
+    if (entry[field] === undefined || entry[field] === null) {
+      errors.push(`missing required field: ${field}`);
+    }
+  }
+
+  // Type must be in taxonomy
+  if (entry.type !== undefined && !LEARNING_TYPES.includes(entry.type)) {
+    errors.push(`invalid type: "${entry.type}". Must be one of: ${LEARNING_TYPES.join(', ')}`);
+  }
+
+  // Confidence must be valid tier
+  if (entry.confidence !== undefined && !['low', 'medium', 'high'].includes(entry.confidence)) {
+    errors.push(`invalid confidence: "${entry.confidence}". Must be one of: low, medium, high`);
+  }
+
+  // Occurrences must be positive integer
+  if (entry.occurrences !== undefined) {
+    if (!Number.isInteger(entry.occurrences) || entry.occurrences < 1) {
+      errors.push(`occurrences must be a positive integer, got: ${entry.occurrences}`);
+    }
+  }
+
+  // Tags must be a non-empty array of strings
+  if (entry.tags !== undefined) {
+    if (!Array.isArray(entry.tags)) {
+      errors.push('tags must be an array');
+    } else if (entry.tags.length === 0) {
+      errors.push('tags must be a non-empty array');
+    } else {
+      const nonStrings = entry.tags.filter(t => typeof t !== 'string');
+      if (nonStrings.length > 0) {
+        errors.push(`all tags must be strings; got ${nonStrings.length} non-string value(s)`);
+      }
+    }
+  }
+
+  return { valid: errors.length === 0, errors };
+}
+
+/**
+ * Load all entries from the learnings JSONL file.
+ * @param {string} [filePath] -- defaults to GLOBAL_LEARNINGS_PATH
+ * @returns {object[]}
+ */
+function loadAll(filePath) {
+  const target = filePath || GLOBAL_LEARNINGS_PATH;
+  if (!fs.existsSync(target)) {
+    return [];
+  }
+  const content = fs.readFileSync(target, 'utf8');
+  return content
+    .split('\n')
+    .filter(line => line.trim().length > 0)
+    .reduce((acc, line) => {
+      try {
+        acc.push(JSON.parse(line));
+      } catch (_e) {
+        console.error(`[learnings] Skipping malformed line: ${line.slice(0, 80)}`);
+      }
+      return acc;
+    }, []);
+}
+
+/**
+ * Save all entries to the learnings JSONL file.
+ * @param {object[]} entries
+ * @param {string} [filePath] -- defaults to GLOBAL_LEARNINGS_PATH
+ */
+function saveAll(entries, filePath) {
+  const target = filePath || GLOBAL_LEARNINGS_PATH;
+  const dir = path.dirname(target);
+  fs.mkdirSync(dir, { recursive: true });
+  const content = entries.map(e => JSON.stringify(e)).join('\n') + (entries.length > 0 ? '\n' : '');
+  fs.writeFileSync(target, content, 'utf8');
+}
+
+/**
+ * Ingest a learning entry into the global store.
+ * Deduplicates by source_project + type + summary.
+ * If a duplicate is found, increments occurrences and updates confidence.
+ * @param {object} rawEntry
+ * @param {{ filePath?: string }} [options]
+ * @returns {{ action: 'created'|'updated', entry: object }}
+ */
+function learningsIngest(rawEntry, options = {}) {
+  const filePath = options.filePath || GLOBAL_LEARNINGS_PATH;
+
+  // Fill in generated fields if missing
+  const entry = Object.assign({}, rawEntry);
+  if (!entry.id) {
+    try {
+      entry.id = crypto.randomUUID();
+    } catch (_e) {
+      entry.id = Date.now().toString(36) + Math.random().toString(36).slice(2);
+    }
+  }
+  if (!entry.created_at) {
+    entry.created_at = new Date().toISOString();
+  }
+
+  const existing = loadAll(filePath);
+
+  // Dedup check: same source_project + type + summary
+  const dupIndex = existing.findIndex(
+    e => e.source_project === entry.source_project &&
+         e.type === entry.type &&
+         e.summary === entry.summary
+  );
+
+  if (dupIndex !== -1) {
+    // Update existing entry
+    const dup = existing[dupIndex];
+    dup.occurrences = (dup.occurrences || 1) + 1;
+    dup.confidence = computeConfidence(dup.occurrences);
+    dup.updated_at = new Date().toISOString();
+    saveAll(existing, filePath);
+    return { action: 'updated', entry: dup };
+  }
+
+  // New entry -- validate before saving
+  const validation = validateEntry(entry);
+  if (!validation.valid) {
+    throw new Error(`Invalid learning entry: ${validation.errors.join('; ')}`);
+  }
+
+  existing.push(entry);
+  saveAll(existing, filePath);
+  return { action: 'created', entry };
+}
+
+/**
+ * Query learnings with optional filters.
+ * @param {{ tags?: string[], minConfidence?: string, stack?: string, type?: string }} [filters]
+ * @param {{ filePath?: string }} [options]
+ * @returns {object[]} Matching entries sorted by occurrences descending
+ */
+function learningsQuery(filters = {}, options = {}) {
+  const filePath = options.filePath || GLOBAL_LEARNINGS_PATH;
+  let entries = loadAll(filePath);
+
+  // Filter by tags (ALL listed tags must be present)
+  if (filters.tags && filters.tags.length > 0) {
+    entries = entries.filter(e => {
+      const entryTags = e.tags || [];
+      return filters.tags.every(t => entryTags.includes(t));
+    });
+  }
+
+  // Filter by minConfidence (entry confidence must be >= threshold)
+  if (filters.minConfidence && filters.minConfidence !== 'low') {
+    const minLevel = CONFIDENCE_TIERS[filters.minConfidence];
+    if (minLevel !== undefined) {
+      entries = entries.filter(e => {
+        const entryLevel = CONFIDENCE_TIERS[e.confidence] || 0;
+        return entryLevel >= minLevel;
+      });
+    }
+  }
+
+  // Filter by stack: matches if tags include "stack:<value>" OR stack_tags includes value
+  if (filters.stack) {
+    const stackTag = `stack:${filters.stack}`;
+    entries = entries.filter(e => {
+      const entryTags = e.tags || [];
+      const stackTags = e.stack_tags || [];
+      return entryTags.includes(stackTag) || stackTags.includes(filters.stack);
+    });
+  }
+
+  // Filter by type (exact match)
+  if (filters.type) {
+    entries = entries.filter(e => e.type === filters.type);
+  }
+
+  // Sort by occurrences descending
+  entries.sort((a, b) => (b.occurrences || 1) - (a.occurrences || 1));
+
+  return entries;
+}
+
+/**
+ * Check deferral thresholds against current learnings data.
+ * @param {{ filePath?: string }} [options]
+ * @returns {Array<{ key: string, trigger: string, message: string }>} Triggered thresholds
+ */
+function checkDeferralThresholds(options = {}) {
+  const filePath = options.filePath || GLOBAL_LEARNINGS_PATH;
+  const entries = loadAll(filePath);
+
+  const totalCount = entries.length;
+
+  // Compute max occurrences for any single tag
+  const tagCounts = {};
+  for (const entry of entries) {
+    for (const tag of (entry.tags || [])) {
+      tagCounts[tag] = (tagCounts[tag] || 0) + (entry.occurrences || 1);
+    }
+  }
+  const tagMax = Object.values(tagCounts).reduce((max, v) => Math.max(max, v), 0);
+
+  // Count audit-type entries
+  const auditCount = entries.filter(e => e.type === 'planning-failure' || e.type === 'process-failure').length;
+
+  // Query count: default 0 (separate counter not implemented in v1)
+  const queryCount = 0;
+
+  const triggered = [];
+  for (const threshold of DEFERRAL_THRESHOLDS) {
+    if (threshold.check(totalCount, tagMax, auditCount, queryCount)) {
+      triggered.push({
+        key: threshold.key,
+        trigger: threshold.trigger,
+        message: `Deferral threshold met: ${threshold.key} (${threshold.trigger})`
+      });
+    }
+  }
+
+  return triggered;
+}
+
+// --- Cross-project knowledge ---
+
+const GLOBAL_KNOWLEDGE_DIR = path.join(os.homedir(), '.claude', 'pbr-knowledge');
+
+/**
+ * Parse simple YAML frontmatter from a markdown string.
+ * Returns an object with string and array values, or null if no frontmatter.
+ * @param {string} content
+ * @returns {object|null}
+ */
+function parseLearningsFrontmatter(content) {
+  const normalized = content.replace(/\r\n/g, '\n');
+  const match = normalized.match(/^---\n([\s\S]*?)\n---/);
+  if (!match) return null;
+
+  const yaml = match[1];
+  const result = {};
+  const lines = yaml.split('\n');
+  let currentKey = null;
+
+  for (const line of lines) {
+    const listMatch = line.match(/^\s+-\s+"?([^"]*?)"?\s*$/);
+    if (listMatch) {
+      if (currentKey !== null) {
+        if (!Array.isArray(result[currentKey])) result[currentKey] = [];
+        result[currentKey].push(listMatch[1].trim());
+      }
+      continue;
+    }
+    const kvMatch = line.match(/^(\w[\w_-]*):\s*(.*)/);
+    if (kvMatch) {
+      currentKey = kvMatch[1];
+      const rawVal = kvMatch[2].trim();
+      if (rawVal === '' || rawVal === '[]') {
+        result[currentKey] = [];
+      } else {
+        result[currentKey] = rawVal.replace(/^["']|["']$/g, '');
+      }
+    }
+  }
+  return result;
+}
+
+/**
+ * Copy a LEARNINGS.md file to the global knowledge directory if marked cross_project: true.
+ * @param {string} learningsMdPath - Path to LEARNINGS.md file
+ * @param {string} projectName - Project name (used in destination filename)
+ * @returns {{ copied: boolean, dest?: string, reason?: string }}
+ */
+function copyToGlobal(learningsMdPath, projectName) {
+  if (!fs.existsSync(learningsMdPath)) {
+    return { copied: false, reason: 'file not found' };
+  }
+
+  const content = fs.readFileSync(learningsMdPath, 'utf8');
+  const fm = parseLearningsFrontmatter(content);
+
+  if (!fm || fm.cross_project !== 'true') {
+    return { copied: false, reason: 'not marked cross_project' };
+  }
+
+  const phase = fm.phase || 'unknown';
+  const sanitizedProject = projectName.replace(/[^a-zA-Z0-9]/g, '-');
+  const destFilename = `${sanitizedProject}--${phase}.md`;
+
+  fs.mkdirSync(GLOBAL_KNOWLEDGE_DIR, { recursive: true });
+  const destPath = path.join(GLOBAL_KNOWLEDGE_DIR, destFilename);
+  fs.copyFileSync(learningsMdPath, destPath);
+
+  return { copied: true, dest: destPath };
+}
+
+/**
+ * Query all global knowledge files with optional filters.
+ * @param {{ tags?: string[], project?: string }} [filters]
+ * @returns {Array<{ file: string, phase: string, key_insights: string[], patterns: string[] }>}
+ */
+function queryGlobal(filters = {}) {
+  if (!fs.existsSync(GLOBAL_KNOWLEDGE_DIR)) {
+    return [];
+  }
+
+  const files = fs.readdirSync(GLOBAL_KNOWLEDGE_DIR).filter(f => f.endsWith('.md'));
+  const results = [];
+
+  for (const file of files) {
+    // Filter by project name prefix
+    if (filters.project && !file.startsWith(filters.project)) {
+      continue;
+    }
+
+    const fullPath = path.join(GLOBAL_KNOWLEDGE_DIR, file);
+    const content = fs.readFileSync(fullPath, 'utf8');
+    const fm = parseLearningsFrontmatter(content);
+    if (!fm) continue;
+
+    const keyInsights = Array.isArray(fm.key_insights) ? fm.key_insights : [];
+    const patterns = Array.isArray(fm.patterns) ? fm.patterns : [];
+
+    // Filter by tags (substring match against insights and patterns)
+    if (filters.tags && filters.tags.length > 0) {
+      const allText = [...keyInsights, ...patterns].join(' ').toLowerCase();
+      const hasMatch = filters.tags.some(tag => allText.includes(tag.toLowerCase()));
+      if (!hasMatch) continue;
+    }
+
+    results.push({
+      file,
+      phase: fm.phase || 'unknown',
+      key_insights: keyInsights,
+      patterns
+    });
+  }
+
+  return results;
+}
+
+/**
+ * Aggregate all learnings into summary statistics.
+ * Groups by type and project; identifies cross-project patterns.
+ *
+ * @param {{ project?: string, type?: string, topN?: number }} [filters]
+ * @param {{ filePath?: string, configFeatures?: object }} [options]
+ * @returns {{ total, by_type, by_project, cross_project_patterns, top_insights } | { enabled: false }}
+ */
+function learningsAggregate(filters = {}, options = {}) {
+  const configFeatures = options.configFeatures || {};
+  if (configFeatures.global_learnings === false) {
+    return { enabled: false };
+  }
+
+  const filePath = options.filePath || GLOBAL_LEARNINGS_PATH;
+  let entries = loadAll(filePath);
+
+  // Apply filters
+  if (filters.project) {
+    entries = entries.filter(e => e.source_project === filters.project);
+  }
+  if (filters.type) {
+    entries = entries.filter(e => e.type === filters.type);
+  }
+
+  const topN = filters.topN !== undefined ? filters.topN : 10;
+
+  // Group by type
+  const by_type = {};
+  for (const entry of entries) {
+    by_type[entry.type] = (by_type[entry.type] || 0) + 1;
+  }
+
+  // Group by project
+  const by_project = {};
+  for (const entry of entries) {
+    const proj = entry.source_project || 'unknown';
+    by_project[proj] = (by_project[proj] || 0) + 1;
+  }
+
+  // Identify cross-project patterns: entries with same summary in 2+ projects
+  const summaryMap = {};
+  for (const entry of entries) {
+    const key = entry.summary;
+    if (!summaryMap[key]) {
+      summaryMap[key] = { summary: key, projects: new Set(), entries: [] };
+    }
+    summaryMap[key].projects.add(entry.source_project);
+    summaryMap[key].entries.push(entry);
+  }
+  const cross_project_patterns = Object.values(summaryMap)
+    .filter(g => g.projects.size >= 2)
+    .map(g => ({
+      summary: g.summary,
+      projects: Array.from(g.projects),
+      count: g.entries.length,
+    }));
+
+  // Top insights sorted by occurrences descending
+  const sorted = [...entries].sort((a, b) => (b.occurrences || 1) - (a.occurrences || 1));
+  const top_insights = sorted.slice(0, topN).map(e => ({
+    id: e.id,
+    summary: e.summary,
+    type: e.type,
+    source_project: e.source_project,
+    occurrences: e.occurrences || 1,
+    confidence: e.confidence,
+  }));
+
+  return {
+    total: entries.length,
+    by_type,
+    by_project,
+    cross_project_patterns,
+    top_insights,
+  };
+}
+
+// --- Exports ---
+
+module.exports = {
+  GLOBAL_LEARNINGS_PATH,
+  GLOBAL_KNOWLEDGE_DIR,
+  LEARNING_TYPES,
+  CONFIDENCE_TIERS,
+  DEFERRAL_THRESHOLDS,
+  computeConfidence,
+  validateEntry,
+  loadAll,
+  saveAll,
+  learningsIngest,
+  learningsQuery,
+  learningsAggregate,
+  checkDeferralThresholds,
+  copyToGlobal,
+  queryGlobal
+};