mindforge-cc 8.1.1 → 8.2.0

package/.mindforge/mirrors/mirror-sre-776a1cf9/bin/skills-builder/skill-registrar.js

@@ -0,0 +1,107 @@
+/**
+ * MindForge v2 — Skill Registrar
+ * Registers a generated skill in the MANIFEST.md at the specified tier,
+ * updates the trigger index, and writes an AUDIT entry.
+ */
+'use strict';
+
+const fs   = require('fs');
+const path = require('path');
+
+const MANIFEST_PATH = path.join(process.cwd(), '.mindforge', 'org', 'skills', 'MANIFEST.md');
+const AUDIT_PATH    = path.join(process.cwd(), '.planning', 'AUDIT.jsonl');
+
+const TIER_PATHS = {
+  core:    path.join(process.cwd(), '.mindforge', 'skills'),
+  org:     path.join(process.cwd(), '.mindforge', 'org', 'skills'),
+  project: path.join(process.cwd(), '.mindforge', 'skills'),
+};
+
+const TIER_LABELS = { core: 'T1 Core', org: 'T2 Org', project: 'T3 Project' };
+
+/**
+ * Register a skill in MANIFEST.md.
+ * @param {object} params
+ * @param {string} params.skillName    - Kebab-case skill name
+ * @param {string} params.skillPath    - Path to the SKILL.md file
+ * @param {string} params.tier         - 'core' | 'org' | 'project'
+ * @param {number} params.qualityScore - Quality score from skill-scorer
+ * @param {string} params.sourceType   - 'url' | 'local' | 'session' | 'npm'
+ * @param {string} params.source       - The source URL/path
+ */
+function register(params) {
+  const {
+    skillName,
+    skillPath,
+    tier        = 'project',
+    qualityScore = 0,
+    sourceType   = 'unknown',
+    source       = '',
+  } = params;
+
+  const relativePath = path.relative(process.cwd(), skillPath).replace(/\\/g, '/');
+
+  // Update MANIFEST.md
+  if (fs.existsSync(MANIFEST_PATH)) {
+    const content = fs.readFileSync(MANIFEST_PATH, 'utf8');
+
+    // Check if skill already registered
+    if (content.includes(skillName)) {
+      process.stderr.write(`[skill-registrar] ⚠️  Skill "${skillName}" already in MANIFEST.md — skipping\n`);
+    } else {
+      // Find the right tier table and insert a new row
+      const tierLabel  = TIER_LABELS[tier] || 'T3 Project';
+      const newRow     = `| ${skillName} | ${tierLabel} | ${relativePath} | ${qualityScore}/100 | v1.0.0 |`;
+
+      // Find the section and replace
+      const sectionHeader = `## ${tierLabel === 'T1 Core' ? 'Core' : tierLabel === 'T2 Org' ? 'Org' : 'Project'} Skills`;
+      if (content.includes(sectionHeader)) {
+          // Find next header or end of file
+          const regex = new RegExp(`(${sectionHeader}[\\s\\S]*?)(?=\\n## |$)`);
+          const match = content.match(regex);
+          if (match) {
+              const updatedSection = match[1].trimEnd() + `\n${newRow}\n`;
+              const updatedContent = content.replace(match[1], updatedSection);
+              fs.writeFileSync(MANIFEST_PATH, updatedContent);
+          } else {
+              fs.appendFileSync(MANIFEST_PATH, `\n${newRow}\n`);
+          }
+      } else {
+          fs.appendFileSync(MANIFEST_PATH, `\n${sectionHeader}\n\n| Skill | Tier | Path | Quality | Version |\n|---|---|---|---|---|\n${newRow}\n`);
+      }
+    }
+  } else {
+    // Create minimal MANIFEST.md
+    fs.mkdirSync(path.dirname(MANIFEST_PATH), { recursive: true });
+    fs.writeFileSync(MANIFEST_PATH,
+      '# MindForge Skills Manifest\n\n' +
+      '## Project Skills\n\n' +
+      '| Skill | Tier | Path | Quality | Version |\n' +
+      '|---|---|---|---|---|\n' +
+      `| ${skillName} | ${TIER_LABELS[tier] || 'T3 Project'} | ${relativePath} | ${qualityScore}/100 | v1.0.0 |\n`
+    );
+  }
+
+  // Write AUDIT entry
+  if (fs.existsSync(path.dirname(AUDIT_PATH))) {
+    const entry = {
+      id:            require('crypto').randomBytes(8).toString('hex'),
+      timestamp:     new Date().toISOString(),
+      event:         'skill_learned',
+      agent:         'mindforge-skills-builder',
+      phase:         null,
+      session_id:    'skill-learn',
+      skill_name:    skillName,
+      tier,
+      quality_score: qualityScore,
+      source_type:   sourceType,
+      source:        String(source).slice(0, 200),
+      skill_path:    relativePath,
+    };
+    fs.appendFileSync(AUDIT_PATH, JSON.stringify(entry) + '\n');
+  }
+
+  return { registered: true, skillName, tier, qualityScore };
+}
+
+module.exports = { register };

package/.mindforge/mirrors/mirror-sre-776a1cf9/bin/skills-builder/skill-scorer.js

@@ -0,0 +1,263 @@
+/**
+ * MindForge v2 — Skill Scorer
+ * 7-dimension quality scoring system for SKILL.md files.
+ * Total: 100 points.
+ *
+ * This is a static analysis scorer — no AI calls needed.
+ * Runs in < 100ms on any SKILL.md.
+ */
+'use strict';
+
+const fs   = require('fs');
+const path = require('path');
+
+// ── Injection guard patterns (from skill-loader.md) ───────────────────────────
+const INJECTION_PATTERNS = [
+  /IGNORE ALL PREVIOUS INSTRUCTIONS/i,
+  /IGNORE PREVIOUS INSTRUCTIONS/i,
+  /DISREGARD YOUR INSTRUCTIONS/i,
+  /FORGET YOUR TRAINING/i,
+  /YOU ARE NOW/i,
+  /YOUR NEW INSTRUCTIONS ARE/i,
+  /OVERRIDE:/i,
+  /SYSTEM PROMPT:/i,
+];
+
+// ── Placeholder detection ─────────────────────────────────────────────────────
+const PLACEHOLDER_PATTERNS = [
+  /\[your description here\]/i,
+  /\[fill in\]/i,
+  /\[TODO\]/i,
+  /\btodo\b/i,
+  /\bfixme\b/i,
+  /<description>/i,
+  /\.\.\.fill in\.\.\./i,
+  /\[your [a-z\s]+ here\]/i,
+  /\[replace with\]/i,
+];
+
+// ── Generic trigger words (penalty list) ─────────────────────────────────────
+const GENERIC_TRIGGERS = new Set([
+  'database', 'api', 'model', 'service', 'component', 'function',
+  'class', 'method', 'type', 'interface', 'module', 'package',
+  'file', 'config', 'test', 'error', 'data', 'query', 'request',
+  'response', 'handler', 'controller', 'repository', 'schema',
+]);
+
+// ── SKILL.md parser ───────────────────────────────────────────────────────────
+function parseSkill(content) {
+  const frontmatterMatch = content.match(/^---\n([\s\S]*?)\n---/);
+  const frontmatter      = frontmatterMatch?.[1] || '';
+
+  // Extract triggers from frontmatter
+  const triggersSection = frontmatter.match(/^triggers:\n((?: {2}- .+\n?)*)/m);
+  const triggers        = (triggersSection?.[1] || '')
+    .split('\n')
+    .map(l => l.replace(/^\s*- /, '').trim())
+    .filter(Boolean);
+
+  // Count code blocks with ≥ 3 lines (meaningful examples, not one-liners)
+  const codeBlockMatches = content.match(/```[\s\S]*?```/g) || [];
+  const codeBlocks       = codeBlockMatches.length;
+  const meaningfulBlocks = codeBlockMatches.filter(block => {
+    const lines = block.split('\n').length;
+    return lines >= 4; // ``` + at least 3 content lines + ```
+  }).length;
+
+  // Count checklist items (both checked and unchecked)
+  const checklistItems = (content.match(/^- \[[ xX]\] /gm) || []).length;
+
+  // Has version history?
+  const hasVersionHistory = /## Version History/i.test(content);
+  const versionEntries    = (content.match(/^### v\d+\.\d+\.\d+/gm) || []).length;
+
+  // Mandatory action counts
+  const alwaysRules  = (content.match(/\b(Always|Must|Required|mandatory|MUST)\b/gi) || []).length;
+  const neverRules   = (content.match(/\b(Never|Don't|Do not|Avoid|NEVER)\b/gi) || []).length;
+  const hasSecuritySection  = /security|auth|SECURITY|AUTH/i.test(content);
+  const hasPerformanceSection = /performance|perf|optimiz|PERFORMANCE/i.test(content);
+  const hasErrorSection    = /error handling|exception|catch|Error/i.test(content);
+
+  return {
+    triggers, codeBlocks, meaningfulBlocks, checklistItems,
+    hasVersionHistory, versionEntries,
+    alwaysRules, neverRules,
+    hasSecuritySection, hasPerformanceSection, hasErrorSection,
+    content,
+  };
+}
+
+// ── Dimension scorers ─────────────────────────────────────────────────────────
+function scoreTriggerCoverage(parsed) {
+  const { triggers } = parsed;
+  let score = 0;
+
+  if (triggers.length >= 25) score = 30;
+  else if (triggers.length >= 20) score = 24;
+  else if (triggers.length >= 15) score = 18;
+  else if (triggers.length >= 10) score = 12;
+  else if (triggers.length >= 5)  score = 6;
+
+  // Penalty for generic triggers
+  const genericCount = triggers.filter(t => GENERIC_TRIGGERS.has(t.toLowerCase())).length;
+  const penalty      = genericCount * 2;
+
+  return {
+    score: Math.max(0, score - penalty),
+    max: 30,
+    details: `${triggers.length} triggers, ${genericCount} generic (penalty: -${penalty})`,
+  };
+}
+
+function scoreMandatoryActions(parsed) {
+  const { alwaysRules, neverRules, hasSecuritySection, hasPerformanceSection, hasErrorSection } = parsed;
+  let score = 0;
+
+  if (alwaysRules >= 5)           score += 5;
+  else if (alwaysRules >= 3)      score += 3;
+  else if (alwaysRules >= 1)      score += 1;
+
+  if (neverRules >= 3)            score += 5;
+  else if (neverRules >= 2)       score += 3;
+  else if (neverRules >= 1)       score += 2;
+
+  if (hasSecuritySection)         score += 5;
+  if (hasPerformanceSection)      score += 5;
+  if (hasErrorSection)            score += 5;
+
+  return {
+    score: Math.min(25, score),
+    max: 25,
+    details: `${alwaysRules} always-rules, ${neverRules} never-rules, security:${hasSecuritySection}, perf:${hasPerformanceSection}, errors:${hasErrorSection}`,
+  };
+}
+
+function scoreCodeExamples(parsed) {
+  const { meaningfulBlocks, content } = parsed;
+  let score = 0;
+
+  if (meaningfulBlocks >= 5)      score = 20;
+  else if (meaningfulBlocks >= 3) score = 14;
+  else if (meaningfulBlocks >= 1) score = 7;
+
+  // Bonus: side-by-side correct/incorrect examples
+  const hasSideBySide = content.includes('✅') && content.includes('❌');
+  if (hasSideBySide) score = Math.min(20, score + 2);
+
+  return { score: Math.min(20, score), max: 20, details: `${meaningfulBlocks} meaningful code blocks, side-by-side:${hasSideBySide}` };
+}
+
+function scoreSelfCheck(parsed) {
+  const { checklistItems } = parsed;
+  let score = 0;
+
+  if (checklistItems >= 10)     score = 15;
+  else if (checklistItems >= 7) score = 10;
+  else if (checklistItems >= 4) score = 7;
+  else if (checklistItems >= 1) score = 3;
+
+  return { score, max: 15, details: `${checklistItems} checklist items` };
+}
+
+function scoreInjectionSafe(parsed) {
+  const hasInjection = INJECTION_PATTERNS.some(p => p.test(parsed.content));
+  return {
+    score: hasInjection ? 0 : 10,
+    max: 10,
+    details: hasInjection ? 'INJECTION PATTERN DETECTED — score 0' : 'clean',
+    fail:    hasInjection,
+  };
+}
+
+function scoreNoPlaceholders(parsed) {
+  const placeholderCount = PLACEHOLDER_PATTERNS.filter(p => p.test(parsed.content)).length;
+  let score = 0;
+  if (placeholderCount === 0)      score = 10;
+  else if (placeholderCount <= 2)  score = 5;
+
+  return { score, max: 10, details: `${placeholderCount} placeholder patterns found` };
+}
+
+function scoreVersionHistory(parsed) {
+  const { hasVersionHistory, versionEntries } = parsed;
+  let score = 0;
+  if (hasVersionHistory && versionEntries >= 1) score = 10;
+  else if (versionEntries > 0) score = 5;
+
+  const bonus = versionEntries > 1 ? 2 : 0;
+  const MAX = 10;
+  return { score: Math.min(MAX, score + bonus), max: MAX, details: `${versionEntries} version entries` };
+}
+
+// ── Main score function ───────────────────────────────────────────────────────
+/**
+ * Score a SKILL.md file.
+ * @param {string} skillPathOrContent - Path to SKILL.md or content string
+ * @returns {object} Full scoring result
+ */
+function score(skillPathOrContent) {
+  let content;
+  if (typeof skillPathOrContent === 'string' && fs.existsSync(skillPathOrContent)) {
+    content = fs.readFileSync(skillPathOrContent, 'utf8');
+  } else {
+    content = skillPathOrContent;
+  }
+
+  const parsed = parseSkill(content);
+
+  const dimensions = {
+    trigger_coverage:    scoreTriggerCoverage(parsed),
+    mandatory_actions:   scoreMandatoryActions(parsed),
+    code_examples:       scoreCodeExamples(parsed),
+    self_check:          scoreSelfCheck(parsed),
+    injection_safe:      scoreInjectionSafe(parsed),
+    no_placeholders:     scoreNoPlaceholders(parsed),
+    version_history:     scoreVersionHistory(parsed),
+  };
+
+  const total = Object.values(dimensions).reduce((s, d) => s + d.score, 0);
+
+  // Determine thresholds
+  let threshold_status = 'insufficient';
+  if (total >= 90)      threshold_status = 'excellent';
+  else if (total >= 80) threshold_status = 'good';
+  else if (total >= 70) threshold_status = 'acceptable';
+  else if (total >= 60) threshold_status = 'minimum';
+
+  const can_register = total >= 60 && !dimensions.injection_safe.fail;
+  const can_publish  = total >= 80 && !dimensions.injection_safe.fail;
+
+  // Improvement suggestions
+  const suggestions = [];
+  if (dimensions.trigger_coverage.score < 24) {
+    suggestions.push(`Add ${25 - parsed.triggers.length} more triggers to reach 25+ (currently ${parsed.triggers.length})`);
+  }
+  if (dimensions.mandatory_actions.score < 20) {
+    if (!parsed.hasSecuritySection)     suggestions.push('Add a security considerations section');
+    if (!parsed.hasPerformanceSection)  suggestions.push('Add a performance considerations section');
+    if (!parsed.hasErrorSection)        suggestions.push('Add an error handling section');
+  }
+  if (dimensions.code_examples.score < 14) {
+    suggestions.push(`Add ${5 - parsed.codeBlocks} more code examples (currently ${parsed.codeBlocks})`);
+  }
+  if (dimensions.self_check.score < 10) {
+    suggestions.push(`Add ${10 - parsed.checklistItems} more checklist items (currently ${parsed.checklistItems})`);
+  }
+  if (!dimensions.version_history.score) {
+    suggestions.push('Add a ## Version History section with a v1.0.0 entry');
+  }
+
+  return {
+    quality_score:    total,
+    threshold_status,
+    can_register,
+    can_publish,
+    score_breakdown:  Object.fromEntries(Object.entries(dimensions).map(([k, v]) => [k, v.score])),
+    dimension_details: Object.fromEntries(Object.entries(dimensions).map(([k, v]) => [k, v.details])),
+    improvement_suggestions: suggestions,
+    trigger_count:    parsed.triggers.length,
+    injection_safe:   !dimensions.injection_safe.fail,
+  };
+}
+
+module.exports = { score, parseSkill, INJECTION_PATTERNS, PLACEHOLDER_PATTERNS, GENERIC_TRIGGERS };

package/.mindforge/mirrors/mirror-sre-776a1cf9/bin/skills-builder/source-loader.js

@@ -0,0 +1,268 @@
+/**
+ * MindForge v2 — Source Loader
+ * Loads documentation from URLs, local files/dirs, npm packages,
+ * and the current session (SUMMARY files + HANDOFF.json).
+ *
+ * All URL fetches have SSRF protection (Day 10 pattern).
+ * Local reads use walkDir() to safely enumerate files.
+ */
+'use strict';
+
+const fs   = require('fs');
+const path = require('path');
+const dns  = require('dns').promises;
+
+const PLANNING_DIR   = path.join(process.cwd(), '.planning');
+const MINDFORGE_DIR  = path.join(process.cwd(), '.mindforge');
+
+// ── SSRF protection (reused from research-engine.js, Day 10) ─────────────────
+const PRIVATE_RANGES = [
+  /^127\./,
+  /^10\./,
+  /^172\.(1[6-9]|2\d|3[01])\./,
+  /^192\.168\./,
+  /^169\.254\./,  // AWS metadata
+  /^::1$/,
+  /^fc00:/,
+  /^fe80:/,
+];
+
+async function isSafeUrl(rawUrl) {
+  let parsed;
+  try { parsed = new URL(rawUrl); } catch { return false; }
+  if (!['http:', 'https:'].includes(parsed.protocol)) return false;
+
+  try {
+    const { address } = await dns.lookup(parsed.hostname);
+    if (PRIVATE_RANGES.some(r => r.test(address))) {
+      process.stderr.write(`[source-loader] SSRF blocked: ${rawUrl} → ${address}\n`);
+      return false;
+    }
+  } catch {
+    process.stderr.write(`[source-loader] DNS resolution failed for: ${parsed.hostname}\n`);
+    return false;
+  }
+  return true;
+}
+
+// ── URL fetcher ───────────────────────────────────────────────────────────────
+async function fetchUrl(rawUrl, maxChars = 400_000, _redirectCount = 0) {
+  if (_redirectCount > 5) {
+    throw new Error(`Too many redirects (>5) for URL: ${rawUrl}`);
+  }
+
+  if (!await isSafeUrl(rawUrl)) {
+    throw new Error(`URL blocked by SSRF protection: ${rawUrl}`);
+  }
+
+  return new Promise((resolve, reject) => {
+    const protocol = rawUrl.startsWith('https') ? require('https') : require('http');
+    let settled = false;
+    const settle = (fn, val) => { if (!settled) { settled = true; fn(val); } };
+
+    const hardTimer = setTimeout(() => {
+      settle(reject, new Error(`Fetch timeout (30s): ${rawUrl}`));
+    }, 30_000);
+
+    const req = protocol.get(rawUrl, { headers: { 'User-Agent': 'MindForge-Learn/2.0' } }, res => {
+      // Follow redirects (up to 5)
+      if ([301, 302, 303, 307, 308].includes(res.statusCode) && res.headers.location) {
+        clearTimeout(hardTimer);
+        // Pass incremented redirect count — SSRF re-checked in recursive call
+        // Comment: Each redirect hop calls isSafeUrl() — open redirect chains through private IPs are blocked
+        fetchUrl(res.headers.location, maxChars, _redirectCount + 1).then(settle.bind(null, resolve), settle.bind(null, reject));
+        return;
+      }
+      if (res.statusCode !== 200) {
+        clearTimeout(hardTimer);
+        settle(reject, new Error(`HTTP ${res.statusCode} for: ${rawUrl}`));
+        return;
+      }
+
+      let body = '';
+      res.on('data', chunk => { body += chunk; if (body.length > maxChars) res.destroy(); });
+      res.on('end', () => { clearTimeout(hardTimer); settle(resolve, body.slice(0, maxChars)); });
+      res.on('error', err => { clearTimeout(hardTimer); settle(reject, err); });
+    });
+    req.on('error', err => { clearTimeout(hardTimer); settle(reject, err); });
+    req.end();
+  });
+}
+
+// ── HTML → text (strip tags for cleaner model context) ───────────────────────
+function htmlToText(html) {
+  return html
+    .replace(/<script[\s\S]*?<\/script>/gi, '')   // Remove scripts
+    .replace(/<style[\s\S]*?<\/style>/gi, '')      // Remove styles
+    .replace(/<[^>]+>/g, ' ')                      // Strip remaining tags
+    .replace(/&nbsp;/g, ' ')
+    .replace(/&amp;/g, '&')
+    .replace(/&lt;/g, '<')
+    .replace(/&gt;/g, '>')
+    .replace(/&quot;/g, '"')
+    .replace(/&#39;/g, '\'')
+    .replace(/\s{3,}/g, '\n\n')                   // Collapse excessive whitespace
+    .trim();
+}
+
+// ── npm package loader ────────────────────────────────────────────────────────
+async function loadNpmPackage(packageName) {
+  // Sanitize package name (prevent path injection)
+  if (!/^(@[a-z0-9-~][a-z0-9-._~]*\/)?[a-z0-9-~][a-z0-9-._~]*$/.test(packageName)) {
+    throw new Error(`Invalid npm package name: ${packageName}`);
+  }
+
+  const registryUrl = `https://registry.npmjs.org/${encodeURIComponent(packageName)}`;
+  const raw         = await fetchUrl(registryUrl, 500_000);
+  const data        = JSON.parse(raw);
+
+  const latest  = data['dist-tags']?.latest || Object.keys(data.versions || {}).pop();
+  const version = data.versions?.[latest];
+  const readme  = data.readme || version?.readme || '';
+
+  return {
+    name:        packageName,
+    version:     latest,
+    description: data.description || '',
+    homepage:    data.homepage || '',
+    repository:  version?.repository?.url || '',
+    readme:      readme.slice(0, 200_000),
+    keywords:    data.keywords || [],
+  };
+}
+
+// ── Local file/directory loader ───────────────────────────────────────────────
+const SKIP_DIRS = new Set(['node_modules', '.git', 'dist', 'build', '.next', 'coverage', '.planning']);
+const DOC_EXTENSIONS = new Set(['.md', '.mdx', '.txt', '.rst', '.html', '.json', '.yaml', '.yml']);
+const CODE_EXTENSIONS = new Set(['.ts', '.tsx', '.js', '.jsx', '.py', '.go', '.rs', '.java']);
+
+function walkDir(dir, extensions, maxFiles = 50) {
+  const results = [];
+  function walk(d) {
+    if (results.length >= maxFiles) return;
+    let entries;
+    try { entries = fs.readdirSync(d, { withFileTypes: true }); } catch { return; }
+    for (const e of entries) {
+      if (results.length >= maxFiles) break;
+      if (SKIP_DIRS.has(e.name)) continue;
+      const full = path.join(d, e.name);
+      if (e.isDirectory()) walk(full);
+      else if (extensions.has(path.extname(e.name).toLowerCase())) results.push(full);
+    }
+  }
+  walk(dir);
+  return results;
+}
+
+function loadLocal(localPath, maxCharsPerFile = 50_000) {
+  const resolved = path.resolve(localPath);
+
+  // Safety check: resolved path must be inside cwd or be absolute
+  const stat = fs.statSync(resolved);
+  let content = '';
+
+  if (stat.isDirectory()) {
+    const allExts = new Set([...DOC_EXTENSIONS, ...CODE_EXTENSIONS]);
+    const files   = walkDir(resolved, allExts, 30);
+    for (const f of files) {
+      const text = fs.readFileSync(f, 'utf8').slice(0, maxCharsPerFile);
+      content += `\n\n### ${path.relative(process.cwd(), f)}\n${text}`;
+      if (content.length > 600_000) break;
+    }
+  } else {
+    content = fs.readFileSync(resolved, 'utf8').slice(0, maxCharsPerFile);
+  }
+
+  return { path: resolved, content: content.slice(0, 800_000) };
+}
+
+// ── Session loader ────────────────────────────────────────────────────────────
+function loadSession(phaseNum = null) {
+  const phasesDir = path.join(PLANNING_DIR, 'phases');
+  if (!fs.existsSync(phasesDir)) return { content: '', sources: [] };
+
+  // Determine phase to analyse
+  let targetPhase = phaseNum;
+  if (!targetPhase) {
+    // Find the most recent phase with SUMMARY files
+    const phaseDirs = fs.readdirSync(phasesDir)
+      .filter(d => /^\d+$/.test(d))
+      .map(Number).sort((a, b) => b - a); // Descending
+    targetPhase = phaseDirs[0];
+  }
+
+  if (!targetPhase) return { content: '', sources: [] };
+
+  const phaseDir = path.join(phasesDir, String(targetPhase));
+  const sources  = [];
+  let content    = `# Session Analysis — Phase ${targetPhase}\n\n`;
+
+  // SUMMARY files
+  const summaryFiles = fs.existsSync(phaseDir)
+    ? fs.readdirSync(phaseDir).filter(f => f.startsWith('SUMMARY-') && f.endsWith('.md'))
+    : [];
+  for (const f of summaryFiles) {
+    const text = fs.readFileSync(path.join(phaseDir, f), 'utf8');
+    content += `## ${f}\n${text.slice(0, 10_000)}\n\n`;
+    sources.push(f);
+  }
+
+  // HANDOFF.json implicit_knowledge
+  const handoffPath = path.join(PLANNING_DIR, 'HANDOFF.json');
+  if (fs.existsSync(handoffPath)) {
+    try {
+      const handoff = JSON.parse(fs.readFileSync(handoffPath, 'utf8'));
+      const implicit = handoff.implicit_knowledge || [];
+      if (implicit.length > 0) {
+        content += '## Implicit Knowledge (from HANDOFF.json)\n';
+        implicit
+          .filter(i => (i.confidence || 0) >= 0.65)
+          .forEach(i => { content += `- ${i.topic || i.text}: ${i.content || i.text}\n`; });
+        content += '\n';
+        sources.push('HANDOFF.json:implicit_knowledge');
+      }
+    } catch { /* ignore malformed HANDOFF */ }
+  }
+
+  // ADR files from this phase
+  const decisionsDir = path.join(PLANNING_DIR, 'decisions');
+  if (fs.existsSync(decisionsDir)) {
+    const recentAdrs = fs.readdirSync(decisionsDir)
+      .filter(f => f.startsWith('ADR-') && f.endsWith('.md'))
+      .slice(-5); // Last 5 ADRs
+    for (const f of recentAdrs) {
+      const text = fs.readFileSync(path.join(decisionsDir, f), 'utf8');
+      content += `## ${f}\n${text.slice(0, 5_000)}\n\n`;
+      sources.push(f);
+    }
+  }
+
+  return { content: content.slice(0, 800_000), sources, phase: targetPhase };
+}
+
+// ── Main load function ────────────────────────────────────────────────────────
+async function load(source) {
+  if (source === '--session') {
+    const result = loadSession();
+    return { type: 'session', content: result.content, metadata: { sources: result.sources, phase: result.phase } };
+  }
+
+  if (source.startsWith('npm:')) {
+    const pkg = source.slice(4);
+    const result = await loadNpmPackage(pkg);
+    const content = `# ${result.name} v${result.version}\n${result.description}\n\n${result.readme}`;
+    return { type: 'npm', content, metadata: result };
+  }
+
+  if (source.startsWith('http://') || source.startsWith('https://')) {
+    const raw  = await fetchUrl(source);
+    const text = raw.includes('<html') || raw.includes('<HTML') ? htmlToText(raw) : raw;
+    return { type: 'url', content: text, metadata: { url: source, length: raw.length } };
+  }
+
+  // Local path
+  const result = loadLocal(source);
+  return { type: 'local', content: result.content, metadata: { path: result.path } };
+}
+
+module.exports = { load, fetchUrl, isSafeUrl, htmlToText, loadNpmPackage, loadLocal, loadSession };