@mseep/core 3.0.0

package/lib/engine/session-manager.js

@@ -0,0 +1,375 @@
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import os from 'os';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+export class BookLibSessionManager {
+  constructor(projectRoot = process.cwd()) {
+    this.projectRoot = projectRoot;
+    this.sessionsDir = path.join(projectRoot, '.booklib/sessions');
+    this.globalSessionsDir = path.join(os.homedir(), '.booklib/sessions');
+    this.archiveDir = path.join(this.sessionsDir, '_archive');
+    this.templatesDir = path.join(this.sessionsDir, '_templates');
+    this.tagsFile = path.join(this.sessionsDir, '_tags.json');
+    this.versionsDir = path.join(this.sessionsDir, '_versions');
+    this.configFile = path.join(projectRoot, '.booklib/config.json');
+    this.hooksDir = path.join(projectRoot, '.git/hooks');
+  }
+
+  findSession(sessionName, options = {}) {
+    const { searchGlobal = false } = options;
+    const projectSession = path.join(this.sessionsDir, `${sessionName}.md`);
+    if (fs.existsSync(projectSession)) {
+      return { path: projectSession, scope: 'project' };
+    }
+    if (searchGlobal || this._getConfig().indexFallback === 'global') {
+      if (fs.existsSync(this.globalSessionsDir)) {
+        const globalSession = path.join(this.globalSessionsDir, `${sessionName}.md`);
+        if (fs.existsSync(globalSession)) {
+          return { path: globalSession, scope: 'global' };
+        }
+      }
+    }
+    return null;
+  }
+
+  cleanupSessions(options = {}) {
+    const { beforeDays = 90, archive = true, dryRun = false } = options;
+    if (!fs.existsSync(this.sessionsDir)) return { archived: 0, deleted: 0 };
+    
+    const cutoffTime = Date.now() - (beforeDays * 24 * 60 * 60 * 1000);
+    const files = fs.readdirSync(this.sessionsDir)
+      .filter(f => f.endsWith('.md') && !f.startsWith('_'));
+    
+    let archived = 0, deleted = 0;
+    const result = [];
+
+    for (const file of files) {
+      const filePath = path.join(this.sessionsDir, file);
+      const stat = fs.statSync(filePath);
+
+      if (stat.mtime.getTime() < cutoffTime) {
+        const action = archive ? 'archive' : 'delete';
+        result.push({ file, action, mtime: stat.mtime });
+
+        if (!dryRun) {
+          if (archive) {
+            this._archiveFile(filePath);
+            archived++;
+          } else {
+            fs.unlinkSync(filePath);
+            deleted++;
+          }
+        }
+      }
+    }
+
+    return { archived, deleted, preview: result };
+  }
+
+  diffSessions(session1Name, session2Name) {
+    const s1 = this.findSession(session1Name);
+    const s2 = this.findSession(session2Name);
+
+    if (!s1 || !s2) {
+      return { error: 'Session not found' };
+    }
+
+    const data1 = this._parseSession(fs.readFileSync(s1.path, 'utf8'));
+    const data2 = this._parseSession(fs.readFileSync(s2.path, 'utf8'));
+
+    return {
+      session1: session1Name,
+      session2: session2Name,
+      goal: {
+        s1: data1.goal,
+        s2: data2.goal,
+        changed: data1.goal !== data2.goal
+      },
+      progress: {
+        s1: data1.progress,
+        s2: data2.progress,
+        changed: data1.progress !== data2.progress
+      },
+      tasks: {
+        s1: data1.pending_tasks,
+        s2: data2.pending_tasks,
+        conflicts: this._detectConflicts(data1.pending_tasks, data2.pending_tasks)
+      },
+      skills: {
+        s1: data1.skills,
+        s2: data2.skills,
+        added: data2.skills.filter(s => !data1.skills.includes(s)),
+        removed: data1.skills.filter(s => !data2.skills.includes(s))
+      }
+    };
+  }
+
+  createFromTemplate(templateName, sessionName, overrides = {}) {
+    const templatePath = path.join(this.templatesDir, `${templateName}.md`);
+    
+    if (!fs.existsSync(templatePath)) {
+      return { error: `Template not found: ${templateName}` };
+    }
+
+    let content = fs.readFileSync(templatePath, 'utf8');
+    content = content.replace(/\{\{session_name\}\}/g, sessionName);
+    content = content.replace(/\{\{timestamp\}\}/g, new Date().toISOString());
+    
+    if (overrides.goal) {
+      content = content.replace(/goal>.+?<\/goal/, `goal>${overrides.goal}</goal`);
+    }
+
+    const sessionPath = path.join(this.sessionsDir, `${sessionName}.md`);
+    fs.writeFileSync(sessionPath, content);
+
+    return { created: sessionPath, template: templateName };
+  }
+
+  searchSessions(query, options = {}) {
+    if (!fs.existsSync(this.sessionsDir)) return [];
+
+    const files = fs.readdirSync(this.sessionsDir)
+      .filter(f => f.endsWith('.md') && !f.startsWith('_'));
+    
+    const results = [];
+    const lowerQuery = query.toLowerCase();
+
+    for (const file of files) {
+      const filePath = path.join(this.sessionsDir, file);
+      const content = fs.readFileSync(filePath, 'utf8');
+      const data = this._parseSession(content);
+
+      const matches = 
+        data.goal.toLowerCase().includes(lowerQuery) ||
+        data.progress.toLowerCase().includes(lowerQuery) ||
+        (data.tags && data.tags.some(t => t.toLowerCase().includes(lowerQuery)));
+
+      if (matches) {
+        results.push({
+          name: file.replace('.md', ''),
+          goal: data.goal.substring(0, 50),
+          tags: data.tags || [],
+          timestamp: data.timestamp
+        });
+      }
+    }
+
+    return results.sort((a, b) => new Date(b.timestamp) - new Date(a.timestamp));
+  }
+
+  tagSession(sessionName, tags, action = 'add') {
+    let allTags = this._loadTags();
+    
+    if (!allTags[sessionName]) {
+      allTags[sessionName] = [];
+    }
+
+    if (action === 'add') {
+      allTags[sessionName] = [...new Set([...allTags[sessionName], ...tags])];
+    } else if (action === 'remove') {
+      allTags[sessionName] = allTags[sessionName].filter(t => !tags.includes(t));
+    }
+
+    this._saveTags(allTags);
+    return { session: sessionName, tags: allTags[sessionName] };
+  }
+
+  generateReport(options = {}) {
+    const { since = null, groupBy = null } = options;
+    
+    if (!fs.existsSync(this.sessionsDir)) {
+      return { sessions: 0, report: {} };
+    }
+
+    const files = fs.readdirSync(this.sessionsDir)
+      .filter(f => f.endsWith('.md') && !f.startsWith('_'));
+    
+    const sessions = [];
+    const sinceTime = since ? new Date(since).getTime() : 0;
+
+    for (const file of files) {
+      const filePath = path.join(this.sessionsDir, file);
+      const content = fs.readFileSync(filePath, 'utf8');
+      const data = this._parseSession(content);
+
+      if (new Date(data.timestamp).getTime() >= sinceTime) {
+        sessions.push(data);
+      }
+    }
+
+    const stats = {
+      total_sessions: sessions.length,
+      total_tasks: sessions.reduce((sum, s) => sum + (s.pending_tasks ? s.pending_tasks.split('\n').length : 0), 0),
+      total_skills: [...new Set(sessions.flatMap(s => s.skills || []))].length,
+      unique_skills: [...new Set(sessions.flatMap(s => s.skills || []))],
+      by_branch: this._groupBy(sessions, 'branch'),
+      recent_activity: sessions.slice(0, 5).map(s => ({
+        name: s.session_id,
+        timestamp: s.timestamp,
+        goal: s.goal
+      }))
+    };
+
+    return stats;
+  }
+
+  validateSession(sessionName) {
+    const session = this.findSession(sessionName);
+    if (!session) return { valid: false, errors: ['Session not found'] };
+
+    const content = fs.readFileSync(session.path, 'utf8');
+    const data = this._parseSession(content);
+    const errors = [];
+    const warnings = [];
+
+    if (!data.goal || data.goal.length < 10) {
+      errors.push('Goal too vague (< 10 characters)');
+    }
+
+    if (!data.progress || data.progress.length < 10) {
+      warnings.push('Progress not detailed enough');
+    }
+
+    if (!data.pending_tasks || data.pending_tasks.length === 0) {
+      warnings.push('No pending tasks defined');
+    }
+
+    if (!data.skills || data.skills.length === 0) {
+      warnings.push('No skills specified');
+    }
+
+    return {
+      valid: errors.length === 0,
+      errors,
+      warnings,
+      score: this._calculateSessionScore(data)
+    };
+  }
+
+  saveVersion(sessionName, reason = 'auto-save') {
+    const session = this.findSession(sessionName);
+    if (!session) return { error: 'Session not found' };
+
+    if (!fs.existsSync(this.versionsDir)) {
+      fs.mkdirSync(this.versionsDir, { recursive: true });
+    }
+
+    const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+    const versionDir = path.join(this.versionsDir, sessionName);
+    if (!fs.existsSync(versionDir)) {
+      fs.mkdirSync(versionDir, { recursive: true });
+    }
+
+    const versionPath = path.join(versionDir, `${timestamp}.md`);
+    const content = fs.readFileSync(session.path, 'utf8');
+    fs.writeFileSync(versionPath, content);
+
+    return { saved: versionPath, reason, timestamp };
+  }
+
+  getVersionHistory(sessionName) {
+    const versionDir = path.join(this.versionsDir, sessionName);
+    if (!fs.existsSync(versionDir)) return [];
+
+    return fs.readdirSync(versionDir)
+      .map(f => path.join(versionDir, f))
+      .sort((a, b) => fs.statSync(b).mtime - fs.statSync(a).mtime)
+      .map((p, i) => ({
+        version: i + 1,
+        timestamp: path.basename(p, '.md'),
+        path: p
+      }));
+  }
+
+  // PRIVATE METHODS
+
+  _parseSession(content) {
+    const extract = (tag) => {
+      const regex = new RegExp(`<${tag}>([\\s\\S]*?)</${tag}>`);
+      const match = content.match(regex);
+      return match ? match[1].trim() : '';
+    };
+
+    const skillRegex = /<skill id="([^"]+)"/g;
+    const skills = [];
+    let match;
+    while ((match = skillRegex.exec(content)) !== null) {
+      skills.push(match[1]);
+    }
+
+    return {
+      timestamp: extract('timestamp'),
+      session_id: extract('session_id'),
+      branch: extract('branch'),
+      goal: extract('goal'),
+      progress: extract('progress'),
+      pending_tasks: extract('pending_tasks'),
+      skills,
+      tags: this._extractTags(extract('session_id'))
+    };
+  }
+
+  _extractTags(sessionId) {
+    const tagsFile = this._loadTags();
+    return tagsFile[sessionId] || [];
+  }
+
+  _loadTags() {
+    if (fs.existsSync(this.tagsFile)) {
+      return JSON.parse(fs.readFileSync(this.tagsFile, 'utf8'));
+    }
+    return {};
+  }
+
+  _saveTags(tags) {
+    if (!fs.existsSync(this.sessionsDir)) {
+      fs.mkdirSync(this.sessionsDir, { recursive: true });
+    }
+    fs.writeFileSync(this.tagsFile, JSON.stringify(tags, null, 2));
+  }
+
+  _archiveFile(filePath) {
+    if (!fs.existsSync(this.archiveDir)) {
+      fs.mkdirSync(this.archiveDir, { recursive: true });
+    }
+    const fileName = path.basename(filePath);
+    const destPath = path.join(this.archiveDir, fileName);
+    fs.copyFileSync(filePath, destPath);
+    fs.unlinkSync(filePath);
+  }
+
+  _detectConflicts(tasks1, tasks2) {
+    if (!tasks1 || !tasks2) return [];
+    const t1Array = tasks1.split('\n');
+    const t2Array = tasks2.split('\n');
+    return t1Array.filter(t => t2Array.some(t2 => t.toLowerCase() === t2.toLowerCase()));
+  }
+
+  _calculateSessionScore(data) {
+    let score = 0;
+    if (data.goal && data.goal.length > 10) score += 25;
+    if (data.progress && data.progress.length > 20) score += 25;
+    if (data.pending_tasks && data.pending_tasks.length > 0) score += 25;
+    if (data.skills && data.skills.length > 0) score += 25;
+    return score;
+  }
+
+  _groupBy(items, key) {
+    return items.reduce((acc, item) => {
+      const groupKey = item[key] || 'unknown';
+      if (!acc[groupKey]) acc[groupKey] = [];
+      acc[groupKey].push(item);
+      return acc;
+    }, {});
+  }
+
+  _getConfig() {
+    if (fs.existsSync(this.configFile)) {
+      return JSON.parse(fs.readFileSync(this.configFile, 'utf8'));
+    }
+    return {};
+  }
+}

package/lib/engine/source-detector.js

@@ -0,0 +1,240 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+const HEURISTICS = {
+  'framework-docs': [
+    { pattern: /```[\s\S]*?```/g, weight: 2, name: 'code-blocks' },
+    { pattern: /\bimport\s+|require\s*\(/gi, weight: 3, name: 'imports' },
+    { pattern: /\b(npm|yarn|pnpm)\s+(install|add|run)/gi, weight: 2, name: 'package-mgr' },
+    { pattern: /\b(config|configuration|setup|getting.started)\b/gi, weight: 1, name: 'setup-words' },
+  ],
+  'api-reference': [
+    { pattern: /\b(GET|POST|PUT|DELETE|PATCH)\s+\//gi, weight: 3, name: 'http-methods' },
+    { pattern: /\/api\//gi, weight: 2, name: 'api-paths' },
+    { pattern: /\b(endpoint|request|response|header|status.code)\b/gi, weight: 1, name: 'api-words' },
+    { pattern: /\b(200|201|400|401|403|404|500)\b/g, weight: 1, name: 'status-codes' },
+  ],
+  'release-notes': [
+    { pattern: /^#{1,3}\s*v?\d+\.\d+/gm, weight: 4, name: 'version-headers' },
+    { pattern: /\b(breaking|deprecated|removed)\b/gi, weight: 3, name: 'breaking-words' },
+    { pattern: /\b(added|fixed|changed|updated)\b/gi, weight: 2, name: 'changelog-words' },
+    { pattern: /\bchangelog\b/gi, weight: 2, name: 'changelog-mention' },
+  ],
+  'spec': [
+    { pattern: /\b(requirement|acceptance.criteria|user.story)\b/gi, weight: 4, name: 'spec-terms' },
+    { pattern: /\b(shall|must|should)\b/gi, weight: 2, name: 'rfc-modals' },
+    { pattern: /given.*when.*then/gi, weight: 4, name: 'gherkin' },
+    { pattern: /\b(feature|scenario|priority)\b/gi, weight: 1, name: 'spec-words' },
+  ],
+  'team-decision': [
+    { pattern: /##\s*(Context|Decision|Consequences)/gi, weight: 5, name: 'adr-headers' },
+    { pattern: /\bStatus:\s*(Accepted|Proposed|Deprecated)/gi, weight: 4, name: 'adr-status' },
+    { pattern: /\b(ADR|architecture.decision)\b/gi, weight: 3, name: 'adr-mention' },
+  ],
+  'tutorial': [
+    { pattern: /\bstep\s+\d+/gi, weight: 3, name: 'step-numbers' },
+    { pattern: /^#{1,3}\s*step\s+\d+/gim, weight: 4, name: 'step-headers' },
+    { pattern: /\b(first|next|then|finally|let's)\b/gi, weight: 1, name: 'sequence-words' },
+  ],
+  // Spec-driven development frameworks: SpecKit, GSD, Kiro, Superpowers
+  'sdd-spec': [
+    { pattern: /\b(GOAL|DELIVERS|NOT.DOING|ASSUMPTIONS)\b/g, weight: 5, name: 'spec-card' },
+    { pattern: /\b(requirement|acceptance.criteria|user.story)\b/gi, weight: 3, name: 'req-terms' },
+    { pattern: /^#{1,3}\s*Task\s+\d+/gm, weight: 4, name: 'task-headers' },
+    { pattern: /- \[ \]/g, weight: 2, name: 'task-checkboxes' },
+    { pattern: /\b(implementation.plan|design.doc|architecture)\b/gi, weight: 2, name: 'plan-words' },
+    { pattern: /\b(spec|specification|roadmap|milestone)\b/gi, weight: 2, name: 'spec-words' },
+    { pattern: /\b(constitution|steering|constraints)\b/gi, weight: 3, name: 'speckit-terms' },
+    { pattern: /\b(STATE|REQUIREMENTS|ROADMAP|PROJECT)\.md\b/g, weight: 4, name: 'gsd-files' },
+  ],
+  // OpenAPI, AsyncAPI, GraphQL SDL, Protocol Buffers
+  'api-spec': [
+    { pattern: /\bopenapi:\s*["']?3\./gi, weight: 6, name: 'openapi-version' },
+    { pattern: /\bswagger:\s*["']?2\./gi, weight: 6, name: 'swagger-version' },
+    { pattern: /\basyncapi:\s*["']?[23]\./gi, weight: 6, name: 'asyncapi-version' },
+    { pattern: /\bpaths:\s*$/gm, weight: 4, name: 'openapi-paths' },
+    { pattern: /\bschemas?:\s*$/gm, weight: 3, name: 'openapi-schemas' },
+    { pattern: /\b(operationId|requestBody|responses):/gi, weight: 3, name: 'openapi-keywords' },
+    { pattern: /^type\s+(Query|Mutation|Subscription)\s*\{/gm, weight: 6, name: 'graphql-types' },
+    { pattern: /^(input|enum|interface|union)\s+\w+/gm, weight: 3, name: 'graphql-defs' },
+    { pattern: /^service\s+\w+\s*\{/gm, weight: 5, name: 'grpc-service' },
+    { pattern: /^message\s+\w+\s*\{/gm, weight: 3, name: 'proto-message' },
+  ],
+  // Gherkin BDD specs (.feature files)
+  'bdd-spec': [
+    { pattern: /^Feature:\s+/gm, weight: 6, name: 'feature-keyword' },
+    { pattern: /^\s*Scenario(?:\s+Outline)?:\s+/gm, weight: 5, name: 'scenario-keyword' },
+    { pattern: /^\s*Given\s+/gm, weight: 3, name: 'given-step' },
+    { pattern: /^\s*When\s+/gm, weight: 3, name: 'when-step' },
+    { pattern: /^\s*Then\s+/gm, weight: 3, name: 'then-step' },
+    { pattern: /^\s*And\s+/gm, weight: 1, name: 'and-step' },
+    { pattern: /^\s*Background:/gm, weight: 4, name: 'background' },
+    { pattern: /^\s*Examples:/gm, weight: 4, name: 'examples-table' },
+  ],
+  // Architecture: Structurizr DSL, C4 model
+  'architecture': [
+    { pattern: /\bworkspace\s*\{/gi, weight: 6, name: 'structurizr-workspace' },
+    { pattern: /\b(softwareSystem|container|component|person)\s+/gi, weight: 5, name: 'c4-elements' },
+    { pattern: /\b(deploymentEnvironment|infrastructureNode)\b/gi, weight: 4, name: 'c4-deployment' },
+    { pattern: /\b(System.Context|Container|Component|Dynamic|Deployment)\s+(Diagram|View)/gi, weight: 5, name: 'c4-diagrams' },
+    { pattern: /\b(arc42|architecture.overview|building.block)/gi, weight: 3, name: 'arc42-terms' },
+    { pattern: /\b(quality.requirements|runtime.view|deployment.view)\b/gi, weight: 3, name: 'arc42-sections' },
+  ],
+  // Internal project documentation with code examples and spec terms
+  'project-docs': [
+    { pattern: /```[\s\S]*?```/g, weight: 1, name: 'code-blocks' },
+    { pattern: /\bimport\s+|require\s*\(/gi, weight: 1, name: 'imports' },
+    { pattern: /\b(acceptance.criteria|user.stor(?:y|ies))\b/gi, weight: 4, name: 'project-spec-terms' },
+    { pattern: /##\s*(Context|Decision|Consequences)/gi, weight: 3, name: 'adr-headers' },
+    { pattern: /\b(implementation.plan|design.doc|technical.design)\b/gi, weight: 3, name: 'internal-plan-terms' },
+    { pattern: /\b(sprint|backlog|epic|milestone)\b/gi, weight: 2, name: 'agile-terms' },
+    { pattern: /\b(TODO|FIXME|HACK|NOTE):/g, weight: 2, name: 'dev-markers' },
+    { pattern: /\b(refactor|deprecate|migrate|upgrade)\b/gi, weight: 1, name: 'maintenance-words' },
+  ],
+  // Personal knowledge management: Obsidian, Logseq, Foam, Dendron
+  'pkm': [
+    { pattern: /\[\[([^\]]+)\]\]/g, weight: 4, name: 'wikilinks' },
+    { pattern: /\(\(([a-f0-9-]+)\)\)/g, weight: 5, name: 'logseq-block-refs' },
+    { pattern: /^tags:\s*\[/gm, weight: 3, name: 'yaml-tags-array' },
+    { pattern: /^aliases:\s*\[/gm, weight: 4, name: 'obsidian-aliases' },
+    { pattern: /^cssclass:/gm, weight: 5, name: 'obsidian-cssclass' },
+    { pattern: /^publish:\s*(true|false)/gm, weight: 4, name: 'obsidian-publish' },
+    { pattern: /^date:\s*\d{4}-\d{2}-\d{2}/gm, weight: 2, name: 'dated-notes' },
+    { pattern: /#[a-zA-Z][\w/-]+/g, weight: 1, name: 'hashtags' },
+    { pattern: /^\s*- \[\[/gm, weight: 3, name: 'linked-list-items' },
+    { pattern: /\^[a-f0-9]{6}/g, weight: 4, name: 'obsidian-block-ids' },
+  ],
+};
+
+/** Penalty patterns that reduce scores for misclassified types. */
+const NEGATIVE_SIGNALS = {
+  'framework-docs': [
+    { pattern: /\b(acceptance.criteria|user.stor(?:y|ies))\b/gi, weight: -5, name: 'project-spec-terms' },
+    { pattern: /##\s*(Context|Decision|Consequences)/gi, weight: -4, name: 'adr-headers' },
+    { pattern: /\bStatus:\s*(Accepted|Proposed|Deprecated)/gi, weight: -4, name: 'adr-status' },
+    { pattern: /\b(sprint|backlog|epic|kanban)\b/gi, weight: -3, name: 'agile-terms' },
+    { pattern: /\b(implementation.plan|design.doc|technical.design)\b/gi, weight: -3, name: 'internal-plan-terms' },
+  ],
+};
+
+/**
+ * Detect the source type of a directory by analyzing file contents.
+ * Scores each file against keyword/pattern heuristics and picks the highest-scoring type.
+ * Falls back to 'wiki' when no type scores above the threshold.
+ *
+ * @param {string} dirPath - directory to analyze
+ * @param {object} [opts]
+ * @param {number} [opts.maxFiles=10] - max files to sample
+ * @param {number} [opts.minScore=5] - minimum score to beat 'wiki' default
+ * @returns {{ type: string, scores: Record<string, number>, confidence: string }}
+ */
+export function detectSourceType(dirPath, opts = {}) {
+  const { maxFiles = 10, minScore = 5 } = opts;
+
+  if (maxFiles < 1) throw new Error('maxFiles must be >= 1');
+  if (minScore < 0) throw new Error('minScore must be >= 0');
+
+  let files;
+  try {
+    files = findContentFiles(dirPath).slice(0, maxFiles);
+  } catch {
+    return { type: 'wiki', scores: {}, confidence: 'none' };
+  }
+
+  if (files.length === 0) {
+    return { type: 'wiki', scores: {}, confidence: 'none' };
+  }
+
+  // Directory-level signals: config dirs that strongly indicate a tool
+  const dirBonus = detectDirSignals(dirPath);
+
+  const parts = [];
+  for (const f of files) {
+    const text = fs.readFileSync(f, 'utf8').trim();
+    if (text.length > 0) parts.push(text);
+  }
+  if (parts.length === 0) {
+    return { type: 'wiki', scores: {}, confidence: 'none' };
+  }
+  const content = parts.join('\n');
+
+  const scores = {};
+  for (const [type, rules] of Object.entries(HEURISTICS)) {
+    let score = 0;
+    for (const rule of rules) {
+      const matches = content.match(rule.pattern);
+      if (matches) score += matches.length * rule.weight;
+    }
+    // Apply negative signals (penalties for misclassification)
+    const penalties = NEGATIVE_SIGNALS[type];
+    if (penalties) {
+      for (const rule of penalties) {
+        const matches = content.match(rule.pattern);
+        if (matches) score += matches.length * rule.weight;
+      }
+    }
+    scores[type] = Math.max(0, score + (dirBonus[type] ?? 0));
+  }
+
+  const sorted = Object.entries(scores).sort((a, b) => b[1] - a[1]);
+  const [bestType, bestScore] = sorted[0];
+
+  if (bestScore < minScore) {
+    return { type: 'wiki', scores, confidence: 'low' };
+  }
+
+  const runnerUp = sorted[1]?.[1] ?? 0;
+  const confidence = bestScore >= runnerUp * 2 ? 'high' : 'medium';
+
+  return { type: bestType, scores, confidence };
+}
+
+/** Check for tool-specific config directories that strongly signal a source type. */
+function detectDirSignals(dirPath) {
+  const bonus = {};
+  const DIR_SIGNALS = {
+    '.obsidian': { type: 'pkm', score: 100 },
+    '.logseq': { type: 'pkm', score: 100 },
+    '.foam': { type: 'pkm', score: 100 },
+    '.specify': { type: 'sdd-spec', score: 100 },
+    '.planning': { type: 'sdd-spec', score: 100 },
+    '.gsd': { type: 'sdd-spec', score: 100 },
+    '.kiro': { type: 'sdd-spec', score: 100 },
+    'docs': { type: 'project-docs', score: 100 },
+    'doc': { type: 'project-docs', score: 100 },
+  };
+
+  // Check the directory name itself (fixes BUG 9: self-check)
+  const selfSignal = DIR_SIGNALS[path.basename(dirPath)];
+  if (selfSignal) bonus[selfSignal.type] = (bonus[selfSignal.type] ?? 0) + selfSignal.score;
+
+  try {
+    const entries = fs.readdirSync(dirPath);
+    for (const name of entries) {
+      const signal = DIR_SIGNALS[name];
+      if (signal) bonus[signal.type] = (bonus[signal.type] ?? 0) + signal.score;
+    }
+  } catch { /* best effort */ }
+  return bonus;
+}
+
+/** Recursively find content files, skipping common noise directories.
+ *  Includes markdown, YAML, JSON, GraphQL, Gherkin, and proto files
+ *  so structured formats (OpenAPI, GraphQL SDL, .feature) are detected. */
+function findContentFiles(dirPath) {
+  const results = [];
+  const walk = (dir) => {
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        if (!['node_modules', '.git', '.booklib'].includes(entry.name)) {
+          walk(full);
+        }
+      } else if (/\.(md|mdx|txt|rst|ya?ml|json|graphql|gql|feature|proto|dsl)$/i.test(entry.name)) {
+        results.push(full);
+      }
+    }
+  };
+  walk(dirPath);
+  return results;
+}