@wooojin/forgen 0.1.1 → 0.2.1

package/dist/core/drift-score.js

@@ -0,0 +1,87 @@
+/**
+ * Forgen — Drift Score (Session Drift Detection)
+ *
+ * 세션 내 수정 패턴을 추적하여 drift(산만/반복 수정)를 감지.
+ * EWMA(Exponentially Weighted Moving Average) 기반 이동평균으로
+ * 최근 수정 강도를 측정하고, 임계값 초과 시 경고.
+ *
+ * Codex 합의: DriftState + evaluateDrift 2개만. 최소 인터페이스.
+ */
+const DEFAULTS = {
+    alpha: 0.35,
+    warningEdits: 15,
+    criticalEdits: 30,
+    criticalReverts: 2,
+    hardCapEdits: 50,
+    warningCooldownMs: 5 * 60 * 1000,
+    criticalCooldownMs: 10 * 60 * 1000,
+};
+/** EWMA 업데이트 (순수 함수) */
+export function updateEwma(prev, sample, alpha) {
+    return alpha * sample + (1 - alpha) * prev;
+}
+/** 새 DriftState 생성 */
+export function createDriftState(sessionId) {
+    return {
+        sessionId,
+        totalEdits: 0,
+        totalReverts: 0,
+        ewmaEditRate: 0,
+        ewmaRevertRate: 0,
+        lastWarningAt: 0,
+        lastCriticalAt: 0,
+        hardCapReached: false,
+    };
+}
+/**
+ * 도구 호출 이벤트로 drift 상태를 갱신하고 평가 결과를 반환.
+ * @param state 현재 상태 (mutate됨)
+ * @param isEdit Write/Edit 도구 호출 여부
+ * @param isRevert revert 감지 여부
+ * @param thresholds 커스텀 임계치 (hook-config에서 로드)
+ */
+export function evaluateDrift(state, isEdit, isRevert, thresholds = {}) {
+    const t = { ...DEFAULTS, ...thresholds };
+    const now = Date.now();
+    // Update counters
+    if (isEdit)
+        state.totalEdits++;
+    if (isRevert)
+        state.totalReverts++;
+    // Update EWMA
+    state.ewmaEditRate = updateEwma(state.ewmaEditRate, isEdit ? 1 : 0, t.alpha);
+    state.ewmaRevertRate = updateEwma(state.ewmaRevertRate, isRevert ? 1 : 0, t.alpha);
+    // Calculate drift score: edit rate 65% + revert rate 35%
+    const rawScore = (state.ewmaEditRate * 65) + (state.ewmaRevertRate * 35);
+    const score = Math.min(100, Math.max(0, Math.round(rawScore)));
+    // Hard cap
+    if (state.totalEdits >= t.hardCapEdits) {
+        state.hardCapReached = true;
+        return {
+            level: 'hardcap',
+            score: 100,
+            message: `[Forgen] ⛔ Session drift hard cap reached (${state.totalEdits} edits). Stop and reassess the approach before continuing.`,
+        };
+    }
+    // Critical: 2+ reverts OR 30+ edits OR score >= 78
+    if ((state.totalReverts >= t.criticalReverts || state.totalEdits >= t.criticalEdits || score >= 78) &&
+        (now - state.lastCriticalAt > t.criticalCooldownMs)) {
+        state.lastCriticalAt = now;
+        return {
+            level: 'critical',
+            score,
+            message: `[Forgen] ⚠ High drift detected (score: ${score}, edits: ${state.totalEdits}, reverts: ${state.totalReverts}). Consider stopping to redesign the approach.`,
+        };
+    }
+    // Warning: 15+ edits OR score >= 52
+    if ((state.totalEdits >= t.warningEdits || score >= 52) &&
+        (now - state.lastWarningAt > t.warningCooldownMs)) {
+        state.lastWarningAt = now;
+        return {
+            level: 'warning',
+            score,
+            message: `[Forgen] Drift building up (score: ${score}, edits: ${state.totalEdits}). Review your approach if changes feel repetitive.`,
+        };
+    }
+    return { level: 'normal', score, message: null };
+}

package/dist/core/inspect-cli.js

@@ -4,11 +4,15 @@
  * forgen inspect profile|rules|evidence|session
  * Authoritative: docs/plans/2026-04-03-forgen-rule-renderer-spec.md §6
  */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
 import { loadProfile } from '../store/profile-store.js';
-import { loadAllRules } from '../store/rule-store.js';
+import { loadAllRules, loadActiveRules } from '../store/rule-store.js';
 import { loadRecentEvidence } from '../store/evidence-store.js';
 import { loadRecentSessions } from '../store/session-state-store.js';
 import * as inspect from '../renderer/inspect-renderer.js';
+import { ME_BEHAVIOR, ME_SOLUTIONS, STATE_DIR } from './paths.js';
+import { safeReadJSON } from '../hooks/shared/atomic-write.js';
 export async function handleInspect(args) {
     const sub = args[0];
     if (sub === 'profile') {
@@ -18,6 +22,55 @@ export async function handleInspect(args) {
             return;
         }
         console.log('\n' + inspect.renderProfile(profile) + '\n');
+        // ── Learning Loop Status ──
+        const activeRules = loadActiveRules();
+        const rulesByScope = {
+            me: activeRules.filter(r => r.scope === 'me').length,
+            session: activeRules.filter(r => r.scope === 'session').length,
+        };
+        const evidenceCount = (() => {
+            if (!fs.existsSync(ME_BEHAVIOR))
+                return 0;
+            return fs.readdirSync(ME_BEHAVIOR).filter(f => f.endsWith('.json')).length;
+        })();
+        const sevenDaysAgo = new Date(Date.now() - 7 * 24 * 60 * 60 * 1000).toISOString();
+        const recentEvidence = loadRecentEvidence(100);
+        const recentCount = recentEvidence.filter(e => e.timestamp >= sevenDaysAgo).length;
+        const solutionCount = (() => {
+            if (!fs.existsSync(ME_SOLUTIONS))
+                return 0;
+            return fs.readdirSync(ME_SOLUTIONS).filter(f => f.endsWith('.md')).length;
+        })();
+        const lastExtractionData = safeReadJSON(path.join(STATE_DIR, 'last-extraction.json'), null);
+        const lastExtractionTs = lastExtractionData?.timestamp ?? lastExtractionData?.date;
+        const lastExtractionLabel = (() => {
+            if (!lastExtractionTs)
+                return 'never';
+            const d = new Date(lastExtractionTs);
+            const diffDays = Math.floor((Date.now() - d.getTime()) / (24 * 60 * 60 * 1000));
+            const dateStr = d.toISOString().slice(0, 10);
+            return diffDays === 0 ? `${dateStr} (today)` : `${dateStr} (${diffDays} day${diffDays > 1 ? 's' : ''} ago)`;
+        })();
+        console.log('── Learning Loop Status ──');
+        console.log(`Rules:      ${activeRules.length} active (${rulesByScope.me} me, ${rulesByScope.session} session)`);
+        console.log(`Evidence:   ${evidenceCount} corrections (last 7 days: ${recentCount})`);
+        console.log(`Compound:   ${solutionCount} solutions`);
+        console.log(`Last extraction: ${lastExtractionLabel}`);
+        console.log('');
+        // ── Recent Corrections ──
+        const corrections = recentEvidence
+            .filter(e => e.type === 'explicit_correction')
+            .slice(0, 3);
+        if (corrections.length > 0) {
+            console.log('── Recent Corrections ──');
+            for (const ev of corrections) {
+                const kind = ev.raw_payload?.kind;
+                const axis = ev.axis_refs[0] ?? 'general';
+                const dateStr = ev.timestamp.slice(0, 10);
+                console.log(`• [${axis}] ${ev.summary} (${kind ?? 'correction'}, ${dateStr})`);
+            }
+            console.log('');
+        }
         return;
     }
     if (sub === 'rules') {

package/dist/core/mcp-config.d.ts

@@ -11,6 +11,8 @@ export interface McpServerConfig {
     command: string;
     args: string[];
     env?: Record<string, string>;
+    /** HTTP/SSE transport URL (alternative to command+args) */
+    url?: string;
 }
 /**
  * 기본 MCP 서버 템플릿 목록 반환

package/dist/core/mcp-config.js

@@ -101,7 +101,12 @@ export async function handleMcp(args) {
             for (const name of names) {
                 const cfg = installed[name];
                 console.log(`    ${name}`);
-                console.log(`      command: ${cfg.command} ${cfg.args.join(' ')}`);
+                if (cfg.command) {
+                    console.log(`      command: ${cfg.command} ${(cfg.args ?? []).join(' ')}`);
+                }
+                else if (cfg.url) {
+                    console.log(`      url: ${cfg.url}`);
+                }
                 if (cfg.env && Object.keys(cfg.env).length > 0) {
                     console.log(`      env: ${JSON.stringify(cfg.env)}`);
                 }

package/dist/core/paths.d.ts

@@ -74,7 +74,7 @@ export declare const V1_RAW_LOGS_DIR: string;
 /** @deprecated use GLOBAL_CONFIG */
 export declare const V1_GLOBAL_CONFIG: string;
 /** 모든 실행 모드 이름 (cancel/recovery 시 사용) */
-export declare const ALL_MODES: readonly ["ralph", "autopilot", "ultrawork", "team", "pipeline", "ccg", "ralplan", "deep-interview", "ecomode"];
+export declare const ALL_MODES: readonly ["ralph", "autopilot", "ultrawork", "team", "pipeline", "ccg", "ralplan", "deep-interview", "ecomode", "specify"];
 /** {repo}/.compound/ — 프로젝트 로컬 디렉토리 */
 export declare function projectDir(cwd: string): string;
 /** {repo}/.compound/pack.link — 팀 팩 연결 파일 */

package/dist/core/paths.js

@@ -81,7 +81,7 @@ export const V1_GLOBAL_CONFIG = GLOBAL_CONFIG;
 /** 모든 실행 모드 이름 (cancel/recovery 시 사용) */
 export const ALL_MODES = [
     'ralph', 'autopilot', 'ultrawork', 'team', 'pipeline',
-    'ccg', 'ralplan', 'deep-interview', 'ecomode',
+    'ccg', 'ralplan', 'deep-interview', 'ecomode', 'specify',
 ];
 /** {repo}/.compound/ — 프로젝트 로컬 디렉토리 */
 export function projectDir(cwd) {

package/dist/core/spawn.d.ts

@@ -1,3 +1,8 @@
 import type { V1HarnessContext } from './harness.js';
-/** Claude Code를 하네스 환경으로 실행 */
-export declare function spawnClaude(args: string[], context: V1HarnessContext): Promise<void>;
+/** Claude Code를 하네스 환경으로 실행. exit code를 반환. */
+export declare function spawnClaude(args: string[], context: V1HarnessContext): Promise<number>;
+/**
+ * 토큰 한도 도달 시 자동 재시작을 지원하는 claude 실행 래퍼.
+ * context-guard가 pending-resume.json 마커를 생성하면 쿨다운 후 재시작.
+ */
+export declare function spawnClaudeWithResume(args: string[], context: V1HarnessContext, contextFactory: () => Promise<V1HarnessContext>): Promise<void>;

package/dist/core/spawn.js

@@ -6,6 +6,7 @@ import { fileURLToPath } from 'node:url';
 import { buildEnv } from './config-injector.js';
 import { loadGlobalConfig } from './global-config.js';
 import { createLogger } from './logger.js';
+import { STATE_DIR } from './paths.js';
 const log = createLogger('spawn');
 /** claude CLI 경로 탐색 */
 function findClaude() {
@@ -58,7 +59,7 @@ async function indexTranscriptToFTS(cwd, transcriptPath, sessionId) {
         log.debug('FTS5 인덱싱 실패 (session-store 미구현 시 정상)', e);
     }
 }
-/** Claude Code를 하네스 환경으로 실행 */
+/** Claude Code를 하네스 환경으로 실행. exit code를 반환. */
 export async function spawnClaude(args, context) {
     const claudePath = findClaude();
     const env = buildEnv(context.cwd);
@@ -124,12 +125,49 @@ export async function spawnClaude(args, context) {
             catch (e) {
                 console.error('[forgen] 세션 종료 후 처리 실패:', e instanceof Error ? e.message : e);
             }
-            if (code === 0 || code === null) {
-                resolve();
-            }
-            else {
-                process.exit(code);
-            }
+            resolve(code ?? 0);
         });
     });
 }
+const RESUME_COOLDOWN_MS = 30_000;
+const MAX_RESUMES = 3;
+/**
+ * 토큰 한도 도달 시 자동 재시작을 지원하는 claude 실행 래퍼.
+ * context-guard가 pending-resume.json 마커를 생성하면 쿨다운 후 재시작.
+ */
+export async function spawnClaudeWithResume(args, context, contextFactory) {
+    let resumeCount = 0;
+    let currentContext = context;
+    while (true) {
+        const exitCode = await spawnClaude(args, currentContext);
+        const resumePath = path.join(STATE_DIR, 'pending-resume.json');
+        if (!fs.existsSync(resumePath)) {
+            if (exitCode !== 0)
+                process.exit(exitCode);
+            break;
+        }
+        try {
+            const marker = JSON.parse(fs.readFileSync(resumePath, 'utf-8'));
+            fs.unlinkSync(resumePath);
+            if (marker.reason !== 'token-limit') {
+                if (exitCode !== 0)
+                    process.exit(exitCode);
+                break;
+            }
+            if (resumeCount >= MAX_RESUMES) {
+                console.log(`[forgen] 최대 자동 재시작 횟수(${MAX_RESUMES}) 도달. 수동으로 다시 시작하세요.`);
+                break;
+            }
+            resumeCount++;
+            console.log(`[forgen] 토큰 한도 도달. ${RESUME_COOLDOWN_MS / 1000}초 후 자동 재시작합니다... (${resumeCount}/${MAX_RESUMES})`);
+            await new Promise(resolve => setTimeout(resolve, RESUME_COOLDOWN_MS));
+            console.log('[forgen] 세션 재시작 중...');
+            currentContext = await contextFactory();
+        }
+        catch {
+            if (exitCode !== 0)
+                process.exit(exitCode);
+            break;
+        }
+    }
+}

package/dist/core/v1-bootstrap.js

@@ -19,7 +19,7 @@ import { FORGEN_HOME, V1_ME_DIR, V1_RULES_DIR, V1_EVIDENCE_DIR, V1_RECOMMENDATIO
 import { checkLegacyProfile, runLegacyCutover } from './legacy-detector.js';
 import { detectRuntimeCapability } from './runtime-detector.js';
 import { loadProfile, profileExists } from '../store/profile-store.js';
-import { loadActiveRules } from '../store/rule-store.js';
+import { loadActiveRules, cleanupStaleSessionRules } from '../store/rule-store.js';
 import { composeSession } from '../preset/preset-manager.js';
 import { renderRules, DEFAULT_CONTEXT } from '../renderer/rule-renderer.js';
 import { saveSessionState, loadRecentSessions } from '../store/session-state-store.js';
@@ -61,8 +61,15 @@ export function bootstrapV1Session() {
     // 3. Runtime capability 감지
     const runtime = detectRuntimeCapability();
     // 4. Rules 로드 + Session 합성
-    const personalRules = loadActiveRules();
     const sessionId = crypto.randomUUID();
+    // 이전 세션의 scope:'session' 임시 규칙 정리
+    try {
+        cleanupStaleSessionRules(sessionId);
+    }
+    catch {
+        // 정리 실패는 세션 시작을 막지 않음
+    }
+    const personalRules = loadActiveRules();
     const session = composeSession({
         session_id: sessionId,
         profile,

package/dist/engine/compound-export.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Forgen — Compound Knowledge Export/Import
+ *
+ * Provides backup, migration, and sharing of accumulated personal knowledge
+ * stored under ~/.forgen/me/ (solutions/, rules/, behavior/).
+ *
+ * Export creates a tar.gz archive; Import extracts it while skipping existing
+ * files to prevent accidental overwrites.
+ */
+export interface ExportResult {
+    outputPath: string;
+    counts: Record<string, number>;
+    totalFiles: number;
+}
+export interface ImportResult {
+    imported: number;
+    skipped: number;
+    details: {
+        file: string;
+        action: 'imported' | 'skipped';
+    }[];
+}
+/**
+ * Export knowledge directories to a tar.gz archive.
+ *
+ * Uses `tar czf` via child_process for simplicity and reliability.
+ * Only archives solutions/, rules/, behavior/ under ME_DIR.
+ */
+export declare function exportKnowledge(outputPath?: string): ExportResult;
+/**
+ * Import knowledge from a tar.gz archive.
+ *
+ * For each file in the archive, if a file with the same name already exists
+ * in the target directory, it is SKIPPED (no overwrite). Only new files are
+ * added.
+ */
+export declare function importKnowledge(archivePath: string): ImportResult;
+/** CLI handler: forgen compound export */
+export declare function handleExport(args: string[]): Promise<void>;
+/** CLI handler: forgen compound import */
+export declare function handleImport(args: string[]): Promise<void>;

package/dist/engine/compound-export.js

@@ -0,0 +1,169 @@
+/**
+ * Forgen — Compound Knowledge Export/Import
+ *
+ * Provides backup, migration, and sharing of accumulated personal knowledge
+ * stored under ~/.forgen/me/ (solutions/, rules/, behavior/).
+ *
+ * Export creates a tar.gz archive; Import extracts it while skipping existing
+ * files to prevent accidental overwrites.
+ */
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { execFileSync } from 'node:child_process';
+import { ME_DIR } from '../core/paths.js';
+/** Directories within ME_DIR to include in the archive. */
+const KNOWLEDGE_DIRS = ['solutions', 'rules', 'behavior'];
+/**
+ * Count .md files in a directory (non-recursive).
+ * Returns 0 if the directory does not exist.
+ */
+function countFiles(dir) {
+    try {
+        if (!fs.existsSync(dir))
+            return 0;
+        return fs.readdirSync(dir).filter(f => f.endsWith('.md')).length;
+    }
+    catch {
+        return 0;
+    }
+}
+/**
+ * Export knowledge directories to a tar.gz archive.
+ *
+ * Uses `tar czf` via child_process for simplicity and reliability.
+ * Only archives solutions/, rules/, behavior/ under ME_DIR.
+ */
+export function exportKnowledge(outputPath) {
+    const date = new Date().toISOString().split('T')[0];
+    const resolved = outputPath ?? path.join(process.cwd(), `forgen-knowledge-${date}.tar.gz`);
+    // Gather counts before archiving
+    const counts = {};
+    const existingDirs = [];
+    for (const name of KNOWLEDGE_DIRS) {
+        const dir = path.join(ME_DIR, name);
+        const count = countFiles(dir);
+        counts[name] = count;
+        if (fs.existsSync(dir)) {
+            existingDirs.push(name);
+        }
+    }
+    const totalFiles = Object.values(counts).reduce((a, b) => a + b, 0);
+    if (existingDirs.length === 0) {
+        throw new Error('No knowledge directories found to export.');
+    }
+    // Ensure output directory exists
+    const outDir = path.dirname(resolved);
+    fs.mkdirSync(outDir, { recursive: true });
+    // Create tar.gz relative to ME_DIR so archive paths are solutions/*, rules/*, behavior/*
+    execFileSync('tar', ['czf', resolved, ...existingDirs], {
+        cwd: ME_DIR,
+        timeout: 30000,
+        stdio: ['pipe', 'pipe', 'pipe'],
+    });
+    return { outputPath: resolved, counts, totalFiles };
+}
+/**
+ * Import knowledge from a tar.gz archive.
+ *
+ * For each file in the archive, if a file with the same name already exists
+ * in the target directory, it is SKIPPED (no overwrite). Only new files are
+ * added.
+ */
+export function importKnowledge(archivePath) {
+    if (!fs.existsSync(archivePath)) {
+        throw new Error(`Archive not found: ${archivePath}`);
+    }
+    // List files in the archive
+    const listOutput = execFileSync('tar', ['tzf', archivePath], {
+        timeout: 30000,
+        encoding: 'utf-8',
+        stdio: ['pipe', 'pipe', 'pipe'],
+    });
+    const archiveFiles = listOutput
+        .split('\n')
+        .map(f => f.trim())
+        .filter(f => f && !f.endsWith('/'));
+    // Extract to a temp directory first, then selectively copy
+    const tmpDir = fs.mkdtempSync(path.join(fs.realpathSync(os.tmpdir()), 'forgen-import-'));
+    try {
+        execFileSync('tar', ['xzf', archivePath, '-C', tmpDir], {
+            timeout: 30000,
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        const result = { imported: 0, skipped: 0, details: [] };
+        for (const relFile of archiveFiles) {
+            const srcPath = path.join(tmpDir, relFile);
+            const destPath = path.join(ME_DIR, relFile);
+            // Security: ensure the dest path stays within ME_DIR
+            const realDest = path.resolve(destPath);
+            if (!realDest.startsWith(ME_DIR)) {
+                result.skipped++;
+                result.details.push({ file: relFile, action: 'skipped' });
+                continue;
+            }
+            if (fs.existsSync(destPath)) {
+                result.skipped++;
+                result.details.push({ file: relFile, action: 'skipped' });
+            }
+            else {
+                fs.mkdirSync(path.dirname(destPath), { recursive: true });
+                fs.copyFileSync(srcPath, destPath);
+                result.imported++;
+                result.details.push({ file: relFile, action: 'imported' });
+            }
+        }
+        return result;
+    }
+    finally {
+        // Clean up temp directory
+        fs.rmSync(tmpDir, { recursive: true, force: true });
+    }
+}
+/** CLI handler: forgen compound export */
+export async function handleExport(args) {
+    const outputIdx = args.indexOf('--output');
+    const outputPath = outputIdx !== -1 ? args[outputIdx + 1] : undefined;
+    try {
+        const result = exportKnowledge(outputPath);
+        console.log('\n  Compound Knowledge Export\n');
+        console.log(`  Output: ${result.outputPath}`);
+        console.log();
+        for (const [category, count] of Object.entries(result.counts)) {
+            console.log(`    ${category}: ${count} files`);
+        }
+        console.log(`\n  Total: ${result.totalFiles} files exported.\n`);
+    }
+    catch (e) {
+        console.error(`\n  Export failed: ${e.message}\n`);
+        process.exit(1);
+    }
+}
+/** CLI handler: forgen compound import */
+export async function handleImport(args) {
+    const archivePath = args[0];
+    if (!archivePath || archivePath.startsWith('--')) {
+        console.log('  Usage: forgen compound import <path-to-archive>\n');
+        return;
+    }
+    try {
+        const resolved = path.resolve(archivePath);
+        const result = importKnowledge(resolved);
+        console.log('\n  Compound Knowledge Import\n');
+        console.log(`  Archive: ${resolved}`);
+        console.log(`  Imported: ${result.imported} new files`);
+        console.log(`  Skipped: ${result.skipped} existing files`);
+        if (result.details.length > 0 && result.details.length <= 20) {
+            console.log();
+            for (const d of result.details) {
+                const icon = d.action === 'imported' ? '+' : '-';
+                console.log(`    ${icon} ${d.file}`);
+            }
+        }
+        console.log();
+    }
+    catch (e) {
+        console.error(`\n  Import failed: ${e.message}\n`);
+        process.exit(1);
+    }
+}

package/dist/engine/compound-extractor.js

@@ -636,6 +636,41 @@ function updateReExtractedCounter(tags) {
         return;
     }
 }
+/**
+ * Optional LLM enrichment for thin solution content.
+ * Uses execFileSync (synchronous) to keep callers synchronous.
+ * Completely fail-open: any error returns null and the regex-extracted content is kept.
+ * Budget: max 2 calls per extraction run, 15s timeout each.
+ */
+function enrichSolutionContent(solution, diffSnippet) {
+    try {
+        const prompt = [
+            '다음 코드 변경에서 감지된 패턴을 2-3문장으로 설명해주세요.',
+            '무엇이 바뀌었는지가 아니라, **왜 이 패턴이 유용한지**와 **언제 적용해야 하는지**를 설명하세요.',
+            '',
+            `패턴 이름: ${solution.name}`,
+            `감지된 컨텍스트: ${solution.context}`,
+            `태그: ${solution.tags.join(', ')}`,
+            '',
+            '코드 변경 (일부):',
+            diffSnippet.slice(0, 2000),
+        ].join('\n');
+        const result = execFileSync('claude', ['-p', prompt, '--model', 'haiku'], {
+            timeout: 15000,
+            encoding: 'utf-8',
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        const enriched = result.trim();
+        if (enriched.length > 30 && enriched.length < 1000) {
+            return enriched;
+        }
+        return null;
+    }
+    catch {
+        // fail-open: LLM enrichment failure should never block extraction
+        return null;
+    }
+}
 /** Main extraction function — called from SessionStart or CLI */
 function analyzeExtraction(cwd, options) {
     const state = loadLastExtraction();
@@ -732,6 +767,7 @@ function analyzeExtraction(cwd, options) {
         extracted,
         stats,
         persistStateWithoutSaving: false,
+        gitDiff,
     };
 }
 function evaluateExtractedSolution(sol) {
@@ -784,6 +820,19 @@ export async function runExtraction(cwd, sessionId) {
         return { ...result, reason: analysis.reason };
     }
     if (analysis.extracted.length > 0) {
+        // Enrich thin solutions with LLM context — max 2 per run, fail-open
+        let enrichCount = 0;
+        for (const sol of analysis.extracted) {
+            if (enrichCount >= 2)
+                break;
+            if (sol.content.length < 100 && analysis.state.extractionsToday < MAX_EXTRACTIONS_PER_DAY) {
+                const enriched = enrichSolutionContent(sol, analysis.gitDiff ?? '');
+                if (enriched) {
+                    sol.content = enriched;
+                    enrichCount++;
+                }
+            }
+        }
         const { saved, skipped } = processExtractionResults(JSON.stringify(analysis.extracted), sessionId);
         result.extracted = saved;
         result.skipped = skipped;

package/dist/engine/compound-loop.js

@@ -190,6 +190,11 @@ export async function handleCompound(args) {
     forgen compound --lifecycle      Run promotion/demotion/circuit-breaker check
     forgen compound --verify <name>  Manually promote solution to verified
 
+  Export/Import:
+    forgen compound export [--output path]
+                                     Export knowledge to tar.gz archive
+    forgen compound import <path>    Import knowledge from archive (skip existing)
+
   Auto-extraction:
     forgen compound --pause-auto     Pause auto-extraction
     forgen compound --resume-auto    Resume auto-extraction
@@ -199,6 +204,18 @@ export async function handleCompound(args) {
 `);
         return;
     }
+    // --- export command ---
+    if (args[0] === 'export') {
+        const { handleExport } = await import('./compound-export.js');
+        await handleExport(args.slice(1));
+        return;
+    }
+    // --- import command ---
+    if (args[0] === 'import') {
+        const { handleImport } = await import('./compound-export.js');
+        await handleImport(args.slice(1));
+        return;
+    }
     // --pause-auto / --resume-auto
     if (args.includes('--pause-auto') || args.includes('pause-auto')) {
         const { pauseExtraction } = await import('./compound-extractor.js');
@@ -375,6 +392,7 @@ export async function handleCompound(args) {
         '--lifecycle', '--verify', '--save', '--interactive',
         'list', 'inspect', 'remove', 'rollback', 'retag', 'lifecycle',
         '--list', '--inspect', '--remove', '--rollback', '--retag', '--since', 'interactive',
+        'export', 'import', '--output',
     ];
     const hasTypeFlag = knownFlags.some(f => args.includes(f));
     if (!hasTypeFlag) {

package/dist/engine/solution-matcher.d.ts

@@ -6,6 +6,27 @@ import type { SolutionStatus, SolutionType } from './solution-format.js';
  * `synonym-tfidf.test.ts` and any external consumers.
  */
 export declare function expandTagsWithSynonyms(tags: string[]): string[];
+/**
+ * Compute the Dice coefficient between two strings using character bigrams.
+ *
+ * Dice = 2 * |intersection| / (|A| + |B|)
+ *
+ * Both strings are lowercased and whitespace-stripped before bigram generation.
+ * Returns 0 for empty strings or single-character strings (no bigrams possible).
+ * Returns 1.0 for identical non-trivial strings.
+ *
+ * This is used as a lightweight fuzzy matching signal for borderline cases
+ * where the TF-IDF tag intersection produces a low score but the query and
+ * solution tags are character-similar (e.g., "database" vs "데이터베이스"
+ * won't match, but "database" vs "databse" will get a high score).
+ */
+export declare function bigramSimilarity(a: string, b: string): number;
+/**
+ * Simplified BM25 score for a single query-document pair.
+ * Uses tag overlap with term frequency normalization.
+ * k1=1.2, b=0.75 (standard BM25 parameters).
+ */
+export declare function bm25Score(queryTags: string[], docTags: string[], avgDocLength: number): number;
 /** Apply IDF-like weight: common tags get reduced weight */
 export declare function tagWeight(tag: string): number;
 export interface SolutionMatch {
@@ -42,6 +63,8 @@ export interface CalculateRelevanceOptions {
      * pair — `solutionTagsExpanded` MUST be a superset of `solutionTags`.
      */
     solutionTagsExpanded?: string[];
+    /** Average document (solution) tag count for BM25 normalization. Defaults to 6. */
+    avgDocLength?: number;
 }
 export declare function calculateRelevance(promptTags: string[], solutionTags: string[], confidence: number, options?: CalculateRelevanceOptions): {
     relevance: number;