@wooojin/forgen 0.4.8 → 0.4.9

package/dist/core/dashboard-cli.js

@@ -0,0 +1,226 @@
+/**
+ * Forgen — Dashboard CLI (P3)
+ *
+ * `fgx status [--watch] [--json] [--interval N]`
+ * ANSI box-drawing 기반 상태 대시보드. TUI 라이브러리 없음.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { getUsageStats } from './usage-telemetry.js';
+import { classifySolutions } from './lifecycle-classifier.js';
+import { STATE_DIR } from './paths.js';
+import { FORGEN_HOME } from './paths.js';
+// ── ANSI ──────────────────────────────────────────────────────────────────────
+const isTTY = process.stdout.isTTY;
+const C = {
+    reset: isTTY ? '\x1b[0m' : '',
+    bold: isTTY ? '\x1b[1m' : '',
+    dim: isTTY ? '\x1b[2m' : '',
+    cyan: isTTY ? '\x1b[36m' : '',
+    yellow: isTTY ? '\x1b[33m' : '',
+    green: isTTY ? '\x1b[32m' : '',
+    red: isTTY ? '\x1b[31m' : '',
+};
+const BOX_WIDTH = 66;
+function bar(pct, width = 10) {
+    const filled = Math.round(pct * width);
+    const empty = width - filled;
+    return '█'.repeat(Math.max(0, filled)) + '░'.repeat(Math.max(0, empty));
+}
+// 런타임에 정규식 구성 — biome 의 noControlCharactersInRegex 우회.
+// ESC (0x1B) 는 ANSI escape 의 시작이지만 literal regex 에는 못 박힘.
+const ANSI_STRIP_RE = new RegExp(`${String.fromCharCode(27)}\\[[0-9;]*m`, 'g');
+function boxLine(content) {
+    const plain = content.replace(ANSI_STRIP_RE, '');
+    const padding = BOX_WIDTH - 2 - plain.length;
+    return `│ ${content}${' '.repeat(Math.max(0, padding))} │`;
+}
+function boxEmpty() {
+    return `│${' '.repeat(BOX_WIDTH - 2)}│`;
+}
+function boxTop() {
+    return `┌─ ${C.bold}${C.cyan}forgen status${C.reset}` +
+        ' ' + '─'.repeat(BOX_WIDTH - 17) + '┐';
+}
+function boxBottom() {
+    return `└${'─'.repeat(BOX_WIDTH - 2)}┘`;
+}
+function collectData() {
+    const now = new Date();
+    // usage
+    const usage = (() => {
+        try {
+            return getUsageStats();
+        }
+        catch {
+            return { hour5: { claude: 0, codex: 0, total: 0 }, week: { claude: 0, codex: 0, total: 0 } };
+        }
+    })();
+    // today extracted: me/solutions/*.md mtime이 오늘인 것 (또는 last-extraction.json)
+    const todayExtracted = (() => {
+        try {
+            const lastExtPath = path.join(STATE_DIR, 'last-extraction.json');
+            if (fs.existsSync(lastExtPath)) {
+                const data = JSON.parse(fs.readFileSync(lastExtPath, 'utf-8'));
+                const ts = data.ts ?? 0;
+                const isToday = new Date(ts).toDateString() === now.toDateString();
+                if (isToday && typeof data.count === 'number')
+                    return data.count;
+            }
+        }
+        catch { /* ignore */ }
+        // fallback: count solutions modified today
+        try {
+            const solutionsDir = path.join(FORGEN_HOME, 'me', 'solutions');
+            if (!fs.existsSync(solutionsDir))
+                return 0;
+            const files = fs.readdirSync(solutionsDir).filter(f => f.endsWith('.md'));
+            const todayStr = now.toDateString();
+            return files.filter(f => {
+                try {
+                    const stat = fs.statSync(path.join(solutionsDir, f));
+                    return new Date(stat.mtimeMs).toDateString() === todayStr;
+                }
+                catch {
+                    return false;
+                }
+            }).length;
+        }
+        catch {
+            return 0;
+        }
+    })();
+    // lifecycle
+    const classified = (() => {
+        try {
+            return classifySolutions();
+        }
+        catch {
+            return [];
+        }
+    })();
+    const counts = { hot: 0, warm: 0, cold: 0, dead: 0, new: 0 };
+    for (const c of classified)
+        counts[c.lifecycle]++;
+    const topHot = classified
+        .filter(c => c.lifecycle === 'hot')
+        .sort((a, b) => b.acted_90d - a.acted_90d)
+        .slice(0, 5)
+        .map(c => ({
+        id: c.solutionId,
+        surfaced: c.surfaced_90d,
+        acted: c.acted_90d,
+        rate: c.hitRate ?? 0,
+    }));
+    // rate-limit misses (7d)
+    const rateLimitMisses7d = (() => {
+        try {
+            const missPath = path.join(STATE_DIR, 'rate-limit-misses.jsonl');
+            if (!fs.existsSync(missPath))
+                return 0;
+            const cutoff = Date.now() - 7 * 24 * 60 * 60 * 1000;
+            const lines = fs.readFileSync(missPath, 'utf-8').split('\n').filter(Boolean);
+            return lines.filter(l => {
+                try {
+                    const obj = JSON.parse(l);
+                    return typeof obj.ts === 'number' && obj.ts >= cutoff;
+                }
+                catch {
+                    return false;
+                }
+            }).length;
+        }
+        catch {
+            return 0;
+        }
+    })();
+    return {
+        timestamp: now.toISOString(),
+        usage,
+        todayExtracted,
+        solutions: {
+            total: classified.length,
+            ...counts,
+            topHot,
+            classified,
+        },
+        rateLimitMisses7d,
+    };
+}
+// ── Render ─────────────────────────────────────────────────────────────────────
+function renderTTY(data) {
+    const lines = [];
+    lines.push(boxTop());
+    lines.push(boxEmpty());
+    // Usage
+    lines.push(boxLine(`${C.bold}Usage${C.reset}`));
+    const h5total = data.usage.hour5.total;
+    const h5pct = Math.min(1, h5total / Math.max(h5total + 10, 50));
+    const h5bar = bar(h5pct);
+    lines.push(boxLine(`  5h window:    ${C.yellow}${h5bar}${C.reset}  (${h5total} tool calls)`));
+    const wktotal = data.usage.week.total;
+    const wkpct = Math.min(1, wktotal / Math.max(wktotal + 10, 100));
+    const wkbar = bar(wkpct);
+    lines.push(boxLine(`  weekly:       ${C.yellow}${wkbar}${C.reset}  (${wktotal} tool calls)`));
+    lines.push(boxEmpty());
+    // Today compound
+    lines.push(boxLine(`${C.bold}Today's compound${C.reset}`));
+    lines.push(boxLine(`  extracted:    ${data.todayExtracted} solutions`));
+    lines.push(boxEmpty());
+    // Solutions
+    lines.push(boxLine(`${C.bold}Solutions${C.reset} (${data.solutions.total} total)`));
+    const lifecycleLine = `  ${C.red}🔥 hot:${C.reset}  ${data.solutions.hot}` +
+        `   ${C.yellow}🟡 warm:${C.reset} ${data.solutions.warm}` +
+        `   ${C.cyan}🥶 cold:${C.reset} ${data.solutions.cold}` +
+        `   ${C.dim}💀 dead:${C.reset} ${data.solutions.dead}` +
+        `   ${C.green}🌱 new:${C.reset}  ${data.solutions.new}`;
+    lines.push(boxLine(lifecycleLine));
+    lines.push(boxEmpty());
+    // Top 5 hot
+    if (data.solutions.topHot.length > 0) {
+        lines.push(boxLine(`${C.bold}Top ${data.solutions.topHot.length} hot (90d)${C.reset}`));
+        for (const h of data.solutions.topHot) {
+            const pctStr = `${Math.round(h.rate * 100)}%`;
+            const idShort = h.id.length > 36 ? h.id.slice(0, 33) + '...' : h.id;
+            lines.push(boxLine(`  · ${C.yellow}${idShort}${C.reset}  surf=${h.surfaced} acted=${h.acted} (${pctStr})`));
+        }
+        lines.push(boxEmpty());
+    }
+    // Rate-limit
+    lines.push(boxLine(`${C.bold}Rate-limit${C.reset}`));
+    lines.push(boxLine(`  misses (7d):  ${data.rateLimitMisses7d}`));
+    lines.push(boxEmpty());
+    // Last update
+    lines.push(boxLine(`${C.dim}Last update:    ${data.timestamp}${C.reset}`));
+    lines.push(boxBottom());
+    return lines.join('\n');
+}
+// ── Public API ────────────────────────────────────────────────────────────────
+export async function runDashboard(opts) {
+    const intervalSec = opts.intervalSec ?? 5;
+    const render = () => {
+        const data = collectData();
+        if (opts.json) {
+            // Strip classified array (verbose) from JSON output for cleaner schema
+            const { solutions: { classified: _c, ...solutionStats }, ...rest } = data;
+            process.stdout.write(JSON.stringify({ ...rest, solutions: solutionStats }, null, 2) + '\n');
+            return;
+        }
+        const output = renderTTY(data);
+        if (opts.watch) {
+            process.stdout.write('\x1b[2J\x1b[H'); // clear screen
+        }
+        process.stdout.write(output + '\n');
+    };
+    render();
+    if (opts.watch) {
+        const interval = setInterval(render, intervalSec * 1000);
+        process.on('SIGINT', () => {
+            clearInterval(interval);
+            process.stdout.write('\n');
+            process.exit(0);
+        });
+        // Keep process alive
+        await new Promise(() => { });
+    }
+}

package/dist/core/dev-guide-injector.d.ts

@@ -0,0 +1,26 @@
+/**
+ * dev-guide-injector — fgx init 시 dev-guide principles 를
+ * Claude (.claude/rules/dev-guide-principles.md) + Codex (AGENTS.md managed block)
+ * 양쪽에 stack-aware 자동 inject.
+ */
+export interface DetectedStack {
+    side: 'fe' | 'be';
+    stack: 'react' | 'vue' | 'node' | 'go';
+    principlesFiles: string[];
+}
+export interface InjectResult {
+    stack: DetectedStack | null;
+    claudeRulePath: string;
+    claudeRuleWritten: boolean;
+    agentsMdPath: string;
+    agentsMdInjected: boolean;
+    bytesWritten: number;
+}
+export interface InjectOptions {
+    cwd: string;
+    pkgRoot: string;
+    dryRun?: boolean;
+}
+export declare function detectStack(cwd: string): DetectedStack | null;
+export declare function readPrinciples(pkgRoot: string, side: 'fe' | 'be', stack: string): string;
+export declare function injectDevGuidePrinciples(opts: InjectOptions): InjectResult;

package/dist/core/dev-guide-injector.js

@@ -0,0 +1,137 @@
+/**
+ * dev-guide-injector — fgx init 시 dev-guide principles 를
+ * Claude (.claude/rules/dev-guide-principles.md) + Codex (AGENTS.md managed block)
+ * 양쪽에 stack-aware 자동 inject.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+// ── 상수 ──────────────────────────────────────────────────────────────────────
+const AGENTS_MD_BEGIN = '<!-- >>> forgen-managed-rules -->';
+const AGENTS_MD_END = '<!-- <<< forgen-managed-rules -->';
+// ── detectStack ───────────────────────────────────────────────────────────────
+export function detectStack(cwd) {
+    const pkgPath = path.join(cwd, 'package.json');
+    if (fs.existsSync(pkgPath)) {
+        try {
+            const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
+            const deps = { ...pkg.dependencies, ...pkg.devDependencies, ...pkg.peerDependencies };
+            if ('react' in deps || 'next' in deps) {
+                return { side: 'fe', stack: 'react', principlesFiles: ['common.md', 'react.md'] };
+            }
+            if ('vue' in deps || 'nuxt' in deps) {
+                return { side: 'fe', stack: 'vue', principlesFiles: ['common.md', 'vue.md'] };
+            }
+            return { side: 'be', stack: 'node', principlesFiles: ['common.md', 'node.md'] };
+        }
+        catch {
+            // JSON parse 실패 — fall through to go.mod check
+        }
+    }
+    if (fs.existsSync(path.join(cwd, 'go.mod'))) {
+        return { side: 'be', stack: 'go', principlesFiles: ['common.md', 'go.md'] };
+    }
+    return null;
+}
+// ── readPrinciples ────────────────────────────────────────────────────────────
+export function readPrinciples(pkgRoot, side, stack) {
+    const principlesDir = path.join(pkgRoot, 'assets', 'dev-guide', side, 'principles');
+    const commonContent = fs.readFileSync(path.join(principlesDir, 'common.md'), 'utf-8');
+    const stackContent = fs.readFileSync(path.join(principlesDir, `${stack}.md`), 'utf-8');
+    return [
+        `<!-- forgen dev-guide principles (auto-generated, do not edit) -->`,
+        `<!-- source: assets/dev-guide/${side}/principles/common.md + ${stack}.md -->`,
+        ``,
+        `# common (${side})`,
+        commonContent.trimEnd(),
+        ``,
+        `---`,
+        ``,
+        `# ${stack}`,
+        stackContent.trimEnd(),
+        ``,
+    ].join('\n');
+}
+// ── injectDevGuidePrinciples ──────────────────────────────────────────────────
+export function injectDevGuidePrinciples(opts) {
+    const { cwd, pkgRoot, dryRun = false } = opts;
+    const claudeRulePath = path.join(cwd, '.claude', 'rules', 'dev-guide-principles.md');
+    const agentsMdPath = path.join(cwd, 'AGENTS.md');
+    const emptyResult = {
+        stack: null,
+        claudeRulePath,
+        claudeRuleWritten: false,
+        agentsMdPath,
+        agentsMdInjected: false,
+        bytesWritten: 0,
+    };
+    const detected = detectStack(cwd);
+    if (!detected)
+        return emptyResult;
+    const body = readPrinciples(pkgRoot, detected.side, detected.stack);
+    // ── Claude side ──
+    const claudeRuleWritten = writeClaudeRule({ claudeRulePath, body, dryRun });
+    // ── Codex side ──
+    const agentsMdInjected = upsertAgentsMd({ agentsMdPath, body, dryRun });
+    return {
+        stack: detected,
+        claudeRulePath,
+        claudeRuleWritten,
+        agentsMdPath,
+        agentsMdInjected,
+        bytesWritten: dryRun ? 0 : body.length,
+    };
+}
+// ── helpers ───────────────────────────────────────────────────────────────────
+function writeClaudeRule(opts) {
+    const { claudeRulePath, body, dryRun } = opts;
+    const existing = fs.existsSync(claudeRulePath)
+        ? fs.readFileSync(claudeRulePath, 'utf-8')
+        : null;
+    if (existing === body)
+        return false;
+    if (!dryRun) {
+        fs.mkdirSync(path.dirname(claudeRulePath), { recursive: true });
+        fs.writeFileSync(claudeRulePath, body, 'utf-8');
+    }
+    return true;
+}
+function escapeRegex(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+function buildDevGuideBlock(body) {
+    return [AGENTS_MD_BEGIN, body.trimEnd(), AGENTS_MD_END].join('\n');
+}
+function upsertAgentsMd(opts) {
+    const { agentsMdPath, body, dryRun } = opts;
+    const block = buildDevGuideBlock(body);
+    const current = fs.existsSync(agentsMdPath) ? fs.readFileSync(agentsMdPath, 'utf-8') : '';
+    const reMarker = new RegExp(`${escapeRegex(AGENTS_MD_BEGIN)}[\\s\\S]*?${escapeRegex(AGENTS_MD_END)}`);
+    const hasBlock = reMarker.test(current);
+    let newContent;
+    if (hasBlock) {
+        newContent = current.replace(reMarker, block);
+    }
+    else {
+        const beginIdx = current.indexOf(AGENTS_MD_BEGIN);
+        const endIdx = current.indexOf(AGENTS_MD_END);
+        if (beginIdx !== -1 && endIdx === -1) {
+            // self-heal: begin 만 있고 end 손상
+            newContent = `${current.slice(0, beginIdx).replace(/\s+$/, '')}\n\n${block}\n`;
+        }
+        else if (current.length === 0) {
+            // 신규 파일
+            newContent = `# Agent Instructions (forgen-managed)\n\n${block}\n`;
+        }
+        else {
+            // 기존 파일에 append
+            newContent = `${current.replace(/\s+$/, '')}\n\n${block}\n`;
+        }
+    }
+    if (newContent === current)
+        return false;
+    if (!dryRun) {
+        fs.mkdirSync(path.dirname(agentsMdPath), { recursive: true });
+        fs.writeFileSync(agentsMdPath, newContent, 'utf-8');
+    }
+    return true;
+}

package/dist/core/init.js

@@ -9,6 +9,7 @@ import * as path from 'node:path';
 import { profileExists } from '../store/profile-store.js';
 import { ensureV1Directories } from './v1-bootstrap.js';
 import { initializeForgenHome } from './init-cli.js';
+import { injectDevGuidePrinciples } from './dev-guide-injector.js';
 // ── CLI 핸들러 ──
 export async function handleInit(_args) {
     const cwd = process.cwd();
@@ -19,6 +20,21 @@ export async function handleInit(_args) {
     // 프로젝트 .claude/rules 디렉토리 생성
     const rulesDir = path.join(cwd, '.claude', 'rules');
     fs.mkdirSync(rulesDir, { recursive: true });
+    // dev-guide principles 자동 inject — profile 존재 여부와 무관한 stateless 작업.
+    // profileExists() early-return / onboarding 흐름 어디든 동일하게 통과해야 하므로
+    // 두 분기 앞쪽에 배치 (기존 위치는 unreachable 경로였음).
+    const pkgRoot = path.resolve(import.meta.dirname ?? __dirname, '..', '..');
+    const injectResult = injectDevGuidePrinciples({ cwd, pkgRoot });
+    if (injectResult.stack) {
+        const { side, stack } = injectResult.stack;
+        const stackLabel = side === 'fe'
+            ? (stack === 'react' ? 'React/Next' : 'Vue/Nuxt')
+            : (stack === 'go' ? 'Go' : 'Node.js');
+        console.log(`  💡 ${stackLabel} 프로젝트 감지됨. dev-guide principles 자동 inject:`);
+        console.log(`     ${injectResult.claudeRulePath} (Claude)`);
+        console.log(`     ${injectResult.agentsMdPath} (Codex, managed block)`);
+        suggestStackSkills(cwd);
+    }
     // v0.4.1 (2026-04-24): starter-pack 프로비저닝 — 격리 홈 / 신규 FORGEN_HOME
     // 에서 "신규 사용자 첫날 가치" 가 0이 되는 결함 해소. npm install-g 시의
     // postinstall 이 하던 starter 배포를 런타임에서도 보장.
@@ -52,3 +68,40 @@ export async function handleInit(_args) {
     console.log('    forgen inspect profile     View your profile');
     console.log('    forgen doctor              Check system health\n');
 }
+// 감지된 스택을 알리고, fgx 번들에 포함된 dev-guide 스킬을 안내.
+// 실제 설치는 install-claude.ts 가 ~/.claude/skills/ 에 처리.
+function suggestStackSkills(cwd) {
+    const pkgPath = path.join(cwd, 'package.json');
+    const goModPath = path.join(cwd, 'go.mod');
+    let stack = null;
+    let skills = [];
+    if (fs.existsSync(pkgPath)) {
+        try {
+            const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+            const deps = { ...pkg.dependencies, ...pkg.devDependencies, ...pkg.peerDependencies };
+            if ('react' in deps || 'next' in deps) {
+                stack = 'React/Next';
+                skills = ['fe-build-react', 'fe-review-react', 'fe-perf-react'];
+            }
+            else if ('vue' in deps || 'nuxt' in deps) {
+                stack = 'Vue/Nuxt';
+                skills = ['fe-build-vue', 'fe-review-vue', 'fe-perf-vue'];
+            }
+            else {
+                stack = 'Node.js';
+                skills = ['be-build-node', 'be-review-node', 'be-perf-node', 'be-security-node'];
+            }
+        }
+        catch { /* ignore */ }
+    }
+    else if (fs.existsSync(goModPath)) {
+        stack = 'Go';
+        skills = ['be-build-go', 'be-review-go', 'be-perf-go', 'be-security-go'];
+    }
+    if (!stack)
+        return;
+    console.log(`  💡 ${stack} 프로젝트로 감지됨. fgx 번들 dev-guide 스킬 사용 가능:`);
+    for (const s of skills)
+        console.log(`     /${s}`);
+    console.log('');
+}

package/dist/core/lifecycle-classifier.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Forgen — Lifecycle Classifier (P3)
+ *
+ * 솔루션 catalog (~/.forgen/me/solutions/*.md) 를 읽어 각 솔루션의
+ * lifecycle 을 hot/warm/cold/dead/new 로 분류한다.
+ */
+import type { HitRateRow } from './observability-store.js';
+export type Lifecycle = 'hot' | 'warm' | 'cold' | 'dead' | 'new';
+export interface LifecycleClass {
+    solutionId: string;
+    lifecycle: Lifecycle;
+    /** acted_90d / max(surfaced_90d, 1). surfaced_90d == 0 이면 null */
+    hitRate: number | null;
+    matched_90d: number;
+    surfaced_90d: number;
+    acted_90d: number;
+    matched_180d: number;
+    ageDays: number;
+}
+/** 분류 로직 — §5.2 */
+export declare function classifyOne(_solutionId: string, ageDays: number, rates: HitRateRow): Lifecycle;
+/** ~/.forgen/me/solutions/*.md 전체를 분류하여 반환 */
+export declare function classifySolutions(): LifecycleClass[];

package/dist/core/lifecycle-classifier.js

@@ -0,0 +1,104 @@
+/**
+ * Forgen — Lifecycle Classifier (P3)
+ *
+ * 솔루션 catalog (~/.forgen/me/solutions/*.md) 를 읽어 각 솔루션의
+ * lifecycle 을 hot/warm/cold/dead/new 로 분류한다.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { ME_SOLUTIONS } from './paths.js';
+import { parseFrontmatterOnly } from '../engine/solution-format.js';
+import { queryHitRate } from './observability-store.js';
+/** 분류 로직 — §5.2 */
+export function classifyOne(_solutionId, ageDays, rates) {
+    // new: age ≤ 30d
+    if (ageDays <= 30)
+        return 'new';
+    // dead: matched_180d == 0 AND age > 30d
+    if (rates.matched_180d === 0)
+        return 'dead';
+    // hot: acted_90d >= 3 AND (acted_90d / max(surfaced_90d, 1)) >= 0.4
+    const hitRate = rates.acted_90d / Math.max(rates.surfaced_90d, 1);
+    if (rates.acted_90d >= 3 && hitRate >= 0.4)
+        return 'hot';
+    // warm: surfaced_90d >= 3 AND acted_90d >= 1
+    if (rates.surfaced_90d >= 3 && rates.acted_90d >= 1)
+        return 'warm';
+    // cold: matched_90d >= 1 AND surfaced_90d == 0
+    if (rates.matched_90d >= 1 && rates.surfaced_90d === 0)
+        return 'cold';
+    // fallback
+    return 'cold';
+}
+/** ~/.forgen/me/solutions/*.md 전체를 분류하여 반환 */
+export function classifySolutions() {
+    const results = [];
+    let files;
+    try {
+        if (!fs.existsSync(ME_SOLUTIONS))
+            return [];
+        files = fs.readdirSync(ME_SOLUTIONS).filter(f => f.endsWith('.md'));
+    }
+    catch {
+        return [];
+    }
+    // queryHitRate() 는 전체 결과를 한 번에 가져옴
+    const rateMap = new Map();
+    try {
+        const rows = queryHitRate();
+        for (const row of rows) {
+            rateMap.set(row.solutionId, row);
+        }
+    }
+    catch {
+        // fail-open: DB 없으면 빈 map
+    }
+    const now = Date.now();
+    for (const file of files) {
+        const filePath = path.join(ME_SOLUTIONS, file);
+        let content;
+        try {
+            content = fs.readFileSync(filePath, 'utf-8');
+        }
+        catch {
+            continue;
+        }
+        const fm = parseFrontmatterOnly(content);
+        if (!fm)
+            continue;
+        const solutionId = fm.name;
+        // ageDays: frontmatter created date 에서 계산
+        let ageDays = 999;
+        try {
+            const createdMs = new Date(fm.created).getTime();
+            if (!isNaN(createdMs)) {
+                ageDays = Math.floor((now - createdMs) / (24 * 60 * 60 * 1000));
+            }
+        }
+        catch {
+            // keep 999 (treat as old)
+        }
+        const rates = rateMap.get(solutionId) ?? {
+            solutionId,
+            matched_30d: 0, surfaced_30d: 0, acted_30d: 0,
+            matched_90d: 0, surfaced_90d: 0, acted_90d: 0,
+            matched_180d: 0, surfaced_180d: 0, acted_180d: 0,
+            last_event_ts: 0,
+        };
+        const lifecycle = classifyOne(solutionId, ageDays, rates);
+        const hitRate = rates.surfaced_90d > 0
+            ? rates.acted_90d / rates.surfaced_90d
+            : null;
+        results.push({
+            solutionId,
+            lifecycle,
+            hitRate,
+            matched_90d: rates.matched_90d,
+            surfaced_90d: rates.surfaced_90d,
+            acted_90d: rates.acted_90d,
+            matched_180d: rates.matched_180d,
+            ageDays,
+        });
+    }
+    return results;
+}

package/dist/core/observability-backfill.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Forgen — Observability Backfill (Phase 2)
+ *
+ * 기존 JSONL 상태 파일에서 solution_events 를 소급 생성한다.
+ * Phase A (결정론적): match-eval-log, implicit-feedback, compound-usage, outcomes
+ * Phase B (휴리스틱): transcript 스캔 — CLI --phase B|all 로만 활성
+ *
+ * 안전성:
+ *   - 기본: events 가 이미 있으면 reject (--force 필요)
+ *   - signal_source 에 '-backfill' prefix 로 실시간 emit 과 구분
+ *   - BEGIN/COMMIT 단위 트랜잭션
+ *   - fail-open: 파일 누락은 조용히 skip
+ */
+export interface BackfillOptions {
+    force?: boolean;
+    phase?: 'A' | 'B' | 'all';
+    dryRun?: boolean;
+}
+export interface BackfillResult {
+    phaseA: {
+        matched: number;
+        surfaced: number;
+        acted_on: number;
+    };
+    phaseB: {
+        acted_on: number;
+    };
+    total: number;
+    durationMs: number;
+}
+export declare function runBackfill(opts?: BackfillOptions): Promise<BackfillResult>;