@sienklogic/plan-build-run 2.0.2 → 2.1.1

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

@@ -0,0 +1,304 @@
+/**
+ * lib/init.cjs — Compound init commands for Plan-Build-Run tools.
+ *
+ * These aggregate state from multiple sources into single JSON payloads
+ * for skill initialization. Each init function returns everything a skill
+ * needs to start work without additional file reads.
+ *
+ * Hybrid module merging PBR reference features with GSD-unique init commands.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { stateLoad, stateCheckProgress } = require('./state.cjs');
+const { configLoad, configResolveDepth } = require('./config.cjs');
+const { phaseInfo, phasePlanIndex } = require('./phase.cjs');
+const { resolveSessionPath } = require('./core.cjs');
+
+/**
+ * Initialize context for executing a phase (building plans).
+ *
+ * @param {string} phaseNum - Phase number
+ * @param {string} [planningDir] - Path to .planning directory
+ * @param {string} [overrideModel] - Optional model override from --model CLI flag (sonnet|opus|haiku|inherit)
+ */
+function initExecutePhase(phaseNum, planningDir, overrideModel) {
+  const dir = planningDir || path.join(process.env.PBR_PROJECT_ROOT || process.cwd(), '.planning');
+  const state = stateLoad(dir);
+  if (!state.exists) return { error: "No .planning/ directory found" };
+  const phase = phaseInfo(phaseNum, dir);
+  if (phase.error) return { error: phase.error };
+  const plans = phasePlanIndex(phaseNum, dir);
+  const config = configLoad(dir) || {};
+  const depthProfile = configResolveDepth(dir);
+  const models = config.models || {};
+  let gitState = { branch: null, clean: null };
+  try {
+    const { execSync } = require("child_process");
+    const branch = execSync("git rev-parse --abbrev-ref HEAD", { encoding: "utf8", timeout: 5000 }).trim();
+    const status = execSync("git status --porcelain", { encoding: "utf8", timeout: 5000 }).trim();
+    gitState = { branch, clean: status === "" };
+  } catch (_e) { /* not a git repo */ }
+  return {
+    executor_model: overrideModel || models.executor || "sonnet",
+    verifier_model: overrideModel || models.verifier || "sonnet",
+    config: { depth: depthProfile.depth || 'standard', mode: config.mode || "interactive", parallelization: config.parallelization || { enabled: false }, planning: config.planning || {}, gates: config.gates || {}, features: config.features || {} },
+    phase: { num: phaseNum, dir: phase.phase, name: phase.name, goal: phase.goal, has_context: phase.has_context, status: phase.filesystem_status, plan_count: phase.plan_count, completed: phase.completed },
+    plans: (plans.plans || []).map(p => ({ file: p.file, plan_id: p.plan_id, wave: p.wave, autonomous: p.autonomous, has_summary: p.has_summary, must_haves_count: p.must_haves_count, depends_on: p.depends_on })),
+    waves: plans.waves || {},
+    branch_name: gitState.branch, git_clean: gitState.clean
+  };
+}
+
+/**
+ * Initialize context for planning a phase.
+ *
+ * @param {string} phaseNum - Phase number
+ * @param {string} [planningDir] - Path to .planning directory
+ * @param {string} [overrideModel] - Optional model override from --model CLI flag (sonnet|opus|haiku|inherit)
+ */
+function initPlanPhase(phaseNum, planningDir, overrideModel) {
+  const dir = planningDir || path.join(process.env.PBR_PROJECT_ROOT || process.cwd(), '.planning');
+  const state = stateLoad(dir);
+  if (!state.exists) return { error: "No .planning/ directory found" };
+  const config = configLoad(dir) || {};
+  const models = config.models || {};
+  const depthProfile = configResolveDepth(dir);
+  const phasesDir = path.join(dir, "phases");
+  const paddedPhase = String(phaseNum).padStart(2, "0");
+  let existingArtifacts = [], phaseDirName = null;
+  if (fs.existsSync(phasesDir)) {
+    const dirs = fs.readdirSync(phasesDir).filter(d => d.startsWith(paddedPhase + "-"));
+    if (dirs.length > 0) { phaseDirName = dirs[0]; existingArtifacts = fs.readdirSync(path.join(phasesDir, phaseDirName)).filter(f => f.endsWith(".md")); }
+  }
+  let phaseGoal = null, phaseDeps = null;
+  if (state.roadmap && state.roadmap.phases) {
+    const rp = state.roadmap.phases.find(p => p.number === paddedPhase);
+    if (rp) { phaseGoal = rp.goal; phaseDeps = rp.depends_on; }
+  }
+  return {
+    researcher_model: overrideModel || models.researcher || "sonnet", planner_model: overrideModel || models.planner || "sonnet", checker_model: overrideModel || models.planner || "sonnet",
+    config: { depth: depthProfile.depth || 'standard', profile: depthProfile.profile || 'balanced', features: config.features || {}, planning: config.planning || {} },
+    phase: { num: phaseNum, dir: phaseDirName, goal: phaseGoal, depends_on: phaseDeps },
+    existing_artifacts: existingArtifacts,
+    workflow: { research_phase: (config.features || {}).research_phase !== false, plan_checking: (config.features || {}).plan_checking !== false }
+  };
+}
+
+/**
+ * Initialize context for a quick task.
+ *
+ * @param {string} description - Task description
+ * @param {string} [planningDir] - Path to .planning directory
+ */
+function initQuick(description, planningDir) {
+  const dir = planningDir || path.join(process.env.PBR_PROJECT_ROOT || process.cwd(), '.planning');
+  const config = configLoad(dir) || {};
+  const quickDir = path.join(dir, "quick");
+  let nextNum = 1;
+  if (fs.existsSync(quickDir)) {
+    const dirs = fs.readdirSync(quickDir).filter(d => /^\d{3}-/.test(d)).sort();
+    if (dirs.length > 0) { nextNum = parseInt(dirs[dirs.length - 1].substring(0, 3), 10) + 1; }
+  }
+  const slug = (description || "task").toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "").substring(0, 30);
+  const paddedNum = String(nextNum).padStart(3, "0");
+  return {
+    next_task_number: paddedNum, slug, dir: path.join(".planning", "quick", paddedNum + "-" + slug),
+    dir_name: paddedNum + "-" + slug, timestamp: new Date().toISOString(),
+    config: { depth: config.depth || "standard", mode: config.mode || "interactive", models: config.models || {}, planning: config.planning || {} }
+  };
+}
+
+/**
+ * Initialize context for verifying phase work.
+ *
+ * @param {string} phaseNum - Phase number
+ * @param {string} [planningDir] - Path to .planning directory
+ * @param {string} [overrideModel] - Optional model override from --model CLI flag (sonnet|opus|haiku|inherit)
+ */
+function initVerifyWork(phaseNum, planningDir, overrideModel) {
+  const dir = planningDir || path.join(process.env.PBR_PROJECT_ROOT || process.cwd(), '.planning');
+  const phase = phaseInfo(phaseNum, dir);
+  if (phase.error) return { error: phase.error };
+  const config = configLoad(dir) || {};
+  const models = config.models || {};
+  let priorAttempts = 0;
+  if (phase.verification) { priorAttempts = parseInt(phase.verification.attempt, 10) || 0; }
+  return {
+    verifier_model: overrideModel || models.verifier || "sonnet",
+    phase: { num: phaseNum, dir: phase.phase, name: phase.name, goal: phase.goal, plan_count: phase.plan_count, completed: phase.completed },
+    has_verification: !!phase.verification, prior_attempts: priorAttempts,
+    prior_status: phase.verification ? (phase.verification.status || "unknown") : null,
+    summaries: phase.summaries || []
+  };
+}
+
+/**
+ * Initialize context for resuming work.
+ *
+ * @param {string} [planningDir] - Path to .planning directory
+ * @param {string} [sessionId] - Session identifier for session-scoped paths
+ */
+function initResume(planningDir, sessionId) {
+  const dir = planningDir || path.join(process.env.PBR_PROJECT_ROOT || process.cwd(), '.planning');
+  const state = stateLoad(dir);
+  if (!state.exists) return { error: "No .planning/ directory found" };
+  let autoNext = null, continueHere = null, activeSkill = null;
+  const autoNextPath = sessionId
+    ? resolveSessionPath(dir, '.auto-next', sessionId)
+    : path.join(dir, '.auto-next');
+  const activeSkillPath = sessionId
+    ? resolveSessionPath(dir, '.active-skill', sessionId)
+    : path.join(dir, '.active-skill');
+  try { autoNext = fs.readFileSync(autoNextPath, "utf8").trim(); } catch (_e) { /* file not found */ }
+  try { continueHere = fs.readFileSync(path.join(dir, ".continue-here"), "utf8").trim(); } catch (_e) { /* file not found */ }
+  try { activeSkill = fs.readFileSync(activeSkillPath, "utf8").trim(); } catch (_e) { /* file not found */ }
+  return { state: state.state, auto_next: autoNext, continue_here: continueHere, active_skill: activeSkill, current_phase: state.current_phase, progress: state.progress };
+}
+
+/**
+ * Initialize context for progress display.
+ *
+ * @param {string} [planningDir] - Path to .planning directory
+ */
+function initProgress(planningDir) {
+  const dir = planningDir || path.join(process.env.PBR_PROJECT_ROOT || process.cwd(), '.planning');
+  const state = stateLoad(dir);
+  if (!state.exists) return { error: "No .planning/ directory found" };
+  const progress = stateCheckProgress(dir);
+  return { current_phase: state.current_phase, total_phases: state.phase_count, status: state.state ? state.state.status : null, phases: progress.phases, total_plans: progress.total_plans, completed_plans: progress.completed_plans, percentage: progress.percentage };
+}
+
+/**
+ * Aggregate all state an orchestrator skill needs to begin work on a phase.
+ * Replaces 5-10 individual file reads with a single CLI call returning ~1,500 tokens of JSON.
+ *
+ * @param {string} phaseNum - Phase number
+ * @param {string} [planningDir] - Path to .planning directory
+ */
+function initStateBundle(phaseNum, planningDir) {
+  const dir = planningDir || path.join(process.env.PBR_PROJECT_ROOT || process.cwd(), '.planning');
+  const { parseYamlFrontmatter } = require('./core.cjs');
+
+  // 1. State
+  const stateResult = stateLoad(dir);
+  if (!stateResult.exists) return { error: 'No .planning/ directory found' };
+  const st = stateResult.state || {};
+  const state = {
+    current_phase: stateResult.current_phase,
+    status: st.status || stateResult.status || null,
+    progress: stateResult.progress,
+    total_phases: stateResult.phase_count || null,
+    last_activity: st.last_activity || null,
+    blockers: st.blockers || []
+  };
+
+  // 2. Config summary
+  const config = configLoad(dir) || {};
+  const depthProfile = configResolveDepth(dir);
+  const models = config.models || {};
+  const config_summary = {
+    depth: depthProfile.depth || 'standard',
+    mode: config.mode || 'interactive',
+    parallelization: config.parallelization || { enabled: false },
+    gates: config.gates || {},
+    features: config.features || {},
+    models: { executor: models.executor || 'sonnet', verifier: models.verifier || 'sonnet', planner: models.planner || 'sonnet' }
+  };
+
+  // 3. Phase info
+  const phaseResult = phaseInfo(phaseNum, dir);
+  if (phaseResult.error) return { error: phaseResult.error };
+  const phase = {
+    num: phaseNum,
+    dir: phaseResult.phase,
+    name: phaseResult.name,
+    goal: phaseResult.goal,
+    has_context: phaseResult.has_context,
+    status: phaseResult.filesystem_status,
+    plan_count: phaseResult.plan_count,
+    completed: phaseResult.completed
+  };
+
+  // 4. Plans
+  const plansResult = phasePlanIndex(phaseNum, dir);
+  const plans = (plansResult.plans || []).map(p => ({
+    file: p.file,
+    plan_id: p.plan_id,
+    wave: p.wave,
+    autonomous: p.autonomous,
+    has_summary: p.has_summary,
+    must_haves_count: p.must_haves_count,
+    depends_on: p.depends_on
+  }));
+  const waves = plansResult.waves || {};
+
+  // 5. Prior summaries -- scan all phase directories for SUMMARY*.md, extract frontmatter only
+  const prior_summaries = [];
+  const phasesDir = path.join(dir, 'phases');
+  if (fs.existsSync(phasesDir)) {
+    const phaseDirs = fs.readdirSync(phasesDir).filter(d => {
+      try { return fs.statSync(path.join(phasesDir, d)).isDirectory(); } catch (_e) { return false; }
+    }).sort();
+    for (const pd of phaseDirs) {
+      if (prior_summaries.length >= 10) break;
+      const pdPath = path.join(phasesDir, pd);
+      let summaryFiles;
+      try { summaryFiles = fs.readdirSync(pdPath).filter(f => /^SUMMARY.*\.md$/i.test(f)).sort(); } catch (_e) { continue; }
+      for (const sf of summaryFiles) {
+        if (prior_summaries.length >= 10) break;
+        try {
+          const content = fs.readFileSync(path.join(pdPath, sf), 'utf8');
+          const fm = parseYamlFrontmatter(content);
+          if (fm && !fm.error) {
+            const entry = {
+              phase: fm.phase !== undefined ? fm.phase : null,
+              plan: fm.plan !== undefined ? fm.plan : null,
+              status: fm.status || null,
+              provides: fm.provides || [],
+              requires: fm.requires || [],
+              key_files: fm.key_files || []
+            };
+            if (fm.key_decisions !== undefined) entry.key_decisions = fm.key_decisions;
+            prior_summaries.push(entry);
+          }
+        } catch (_e) { /* skip unreadable */ }
+      }
+    }
+  }
+
+  // 6. Context file existence
+  const has_project_context = fs.existsSync(path.join(dir, 'CONTEXT.md'));
+  const has_phase_context = phaseResult.has_context || false;
+
+  // 7. Git state
+  let git = { branch: null, clean: null };
+  try {
+    const { execSync } = require('child_process');
+    const branch = execSync('git rev-parse --abbrev-ref HEAD', { encoding: 'utf8', timeout: 5000 }).trim();
+    const status = execSync('git status --porcelain', { encoding: 'utf8', timeout: 5000 }).trim();
+    git = { branch, clean: status === '' };
+  } catch (_e) { /* not a git repo */ }
+
+  return {
+    state,
+    config_summary,
+    phase,
+    plans,
+    waves,
+    prior_summaries,
+    git,
+    has_project_context,
+    has_phase_context
+  };
+}
+
+module.exports = {
+  initExecutePhase,
+  initPlanPhase,
+  initQuick,
+  initVerifyWork,
+  initResume,
+  initProgress,
+  initStateBundle
+};

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

@@ -0,0 +1,312 @@
+'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.cjs');
+ *
+ * Usage (CLI via pbr-tools.cjs):
+ *   node pbr-tools.cjs learnings ingest <json-file>
+ *   node pbr-tools.cjs learnings query [--tags X] [--min-confidence Y] [--stack S] [--type T]
+ *   node pbr-tools.cjs 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;
+}
+
+// --- Exports ---
+
+module.exports = {
+  GLOBAL_LEARNINGS_PATH,
+  LEARNING_TYPES,
+  CONFIDENCE_TIERS,
+  DEFERRAL_THRESHOLDS,
+  computeConfidence,
+  validateEntry,
+  loadAll,
+  saveAll,
+  learningsIngest,
+  learningsQuery,
+  checkDeferralThresholds
+};

package/plan-build-run/bin/lib/local-llm/health.cjs

@@ -0,0 +1,12 @@
+'use strict';
+
+/**
+ * local-llm/health.cjs — Stub for LLM health/config subsystem.
+ * Full implementation deferred to v3 (ADV-01).
+ */
+
+function resolveConfig(config) {
+  return Object.assign({ enabled: false, provider: 'none' }, config || {});
+}
+
+module.exports = { resolveConfig };