@wooojin/forgen 0.4.7 → 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/dashboard.js

@@ -40,13 +40,13 @@ function dim(s) { return `${DIM}${s}${RESET}`; }
 function cyan(s) { return `${CYAN}${s}${RESET}`; }
 // ── Box-drawing table helpers ──
 function tableRow(cols, widths) {
-    return '  │ ' + cols.map((c, i) => c.padEnd(widths[i])).join(' │ ') + ' │';
+    return `  │ ${cols.map((c, i) => c.padEnd(widths[i])).join(' │ ')} │`;
 }
 function tableSep(widths, top = false, bottom = false) {
     const left = top ? '┌' : bottom ? '└' : '├';
     const mid = top ? '┬' : bottom ? '┴' : '┼';
     const right = top ? '┐' : bottom ? '┘' : '┤';
-    return '  ' + left + widths.map(w => '─'.repeat(w + 2)).join(mid) + right;
+    return `  ${left}${widths.map(w => '─'.repeat(w + 2)).join(mid)}${right}`;
 }
 // ── Data Collection Functions ──
 /** Read all .md files in a directory and return their frontmatter. */

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/doctor.d.ts

@@ -2,5 +2,15 @@ export interface DoctorOptions {
     /** When true, delete stale session-scoped state files instead of just
      *  reporting bloat. Triggered by `forgen doctor --prune-state`. */
     pruneState?: boolean;
+    /**
+     * When true, auto-fix recoverable failures (e.g. missing plugin cache /
+     * stale installPath) by running `npm run build` + `node scripts/postinstall.js`
+     * inside the forgen install directory. Triggered by `forgen doctor --repair`.
+     *
+     * v0.4.8 (E3) — 이전엔 안내문 ("Fix: npm run build && node scripts/postinstall.js")
+     * 만 출력했고 사용자가 직접 실행해야 했음. fail-open: repair 실패해도
+     * doctor 흐름은 정상 종료.
+     */
+    repair?: boolean;
 }
 export declare function runDoctor(opts?: DoctorOptions): Promise<void>;

package/dist/core/doctor.js

@@ -2,7 +2,8 @@ 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 { FORGEN_HOME, LAB_DIR, ME_BEHAVIOR, ME_DIR, ME_SOLUTIONS, ME_RULES, ME_SKILLS, PACKS_DIR, SESSIONS_DIR, STATE_DIR } from './paths.js';
+import { fileURLToPath } from 'node:url';
+import { FORGEN_HOME, LAB_DIR, ME_BEHAVIOR, ME_DIR, ME_SOLUTIONS, ME_RULES, ME_SKILLS, PACKS_DIR, SESSIONS_DIR, STATE_DIR, V1_SESSIONS_DIR } from './paths.js';
 import { getTimingStats } from '../hooks/shared/hook-timing.js';
 import { countSessionScopedFiles, pruneState } from './state-gc.js';
 import { summarizeAllByHost } from '../store/host-mismatch.js';
@@ -87,6 +88,29 @@ function renderCodexParity() {
         console.log(`  ✓ Codex parity green (last run: ${timeStr},${version})`);
     }
 }
+/**
+ * v0.4.8 (E3): plugin cache / installPath 진단이 실패했을 때 자동 복구.
+ * forgen 패키지 디렉토리에서 `npm run build` + postinstall 을 차례로 실행.
+ * 실패해도 doctor 자체는 계속 진행 (fail-open).
+ */
+function attemptPluginRepair() {
+    try {
+        // forgen 패키지 루트 = 현재 파일에서 dist/core/doctor.js 위치 → pkgRoot.
+        // dev (src/) 와 prod (dist/) 양쪽 모두 path.resolve(...,'..','..') 로 도달.
+        const here = path.dirname(fileURLToPath(import.meta.url));
+        const pkgRoot = path.resolve(here, '..', '..');
+        console.log(`\n  [Repair] forgen 패키지 자가복구 시도 — ${pkgRoot}`);
+        execFileSync('npm', ['run', 'build'], { cwd: pkgRoot, stdio: 'inherit' });
+        execFileSync('node', ['scripts/postinstall.js'], { cwd: pkgRoot, stdio: 'inherit' });
+        console.log('  [Repair] 완료. 진단 재실행 권장: forgen doctor');
+        return true;
+    }
+    catch (e) {
+        console.warn(`  [Repair] 실패: ${e instanceof Error ? e.message : String(e)}`);
+        console.warn('  [Repair] 수동 복구: cd <forgen pkgRoot> && npm run build && node scripts/postinstall.js');
+        return false;
+    }
+}
 export async function runDoctor(opts = {}) {
     failedChecks = [];
     console.log('\n  Forgen — Diagnostics\n');
@@ -114,7 +138,9 @@ export async function runDoctor(opts = {}) {
         });
         forgenPluginCacheOk = versions.length > 0;
     }
-    check('forgen plugin cache', forgenPluginCacheOk, 'Hook execution requires plugin cache. Fix: npm run build && node scripts/postinstall.js');
+    check('forgen plugin cache', forgenPluginCacheOk, opts.repair
+        ? 'Hook execution requires plugin cache. Attempting auto-repair (--repair)…'
+        : 'Hook execution requires plugin cache. Fix: npm run build && node scripts/postinstall.js (or rerun with --repair)');
     // installed_plugins.json 정합성 확인
     const installedPluginsPath = path.join(os.homedir(), '.claude', 'plugins', 'installed_plugins.json');
     let pluginRegistered = false;
@@ -129,7 +155,15 @@ export async function runDoctor(opts = {}) {
         }
         catch { /* ignore */ }
     }
-    check('forgen plugin registered & installPath exists', pluginRegistered, 'Plugin registered but installPath missing on disk. Fix: npm run build && node scripts/postinstall.js');
+    check('forgen plugin registered & installPath exists', pluginRegistered, opts.repair
+        ? 'Plugin registered but installPath missing on disk. Attempting auto-repair (--repair)…'
+        : 'Plugin registered but installPath missing on disk. Fix: npm run build && node scripts/postinstall.js (or rerun with --repair)');
+    // v0.4.8 (E3): plugin cache 또는 installPath 가 깨졌고 --repair 가 켜져
+    // 있으면 build + postinstall 자동 실행. doctor 진단 자체는 계속 진행하여
+    // 사용자가 다른 health 항목도 한 번에 확인 가능.
+    if (opts.repair && (!forgenPluginCacheOk || !pluginRegistered)) {
+        attemptPluginRepair();
+    }
     console.log();
     section('Directories');
     check('~/.forgen/', exists(FORGEN_HOME));
@@ -138,7 +172,8 @@ export async function runDoctor(opts = {}) {
     check('~/.forgen/me/behavior/', exists(ME_BEHAVIOR));
     check('~/.forgen/me/rules/', exists(ME_RULES));
     check('~/.forgen/packs/', exists(PACKS_DIR));
-    check('~/.forgen/sessions/', exists(SESSIONS_DIR));
+    check('~/.forgen/sessions/ (session logs)', exists(SESSIONS_DIR));
+    check('~/.forgen/state/sessions/ (v1 effective state)', exists(V1_SESSIONS_DIR));
     // R9-IA5: warn if a user dropped rule files at ~/.forgen/rules/ by mistake.
     // That path is NOT loaded — personal rules live at ~/.forgen/me/rules/.
     const legacyRulesPath = path.join(FORGEN_HOME, 'rules');
@@ -194,10 +229,16 @@ export async function runDoctor(opts = {}) {
     }
     console.log();
     console.log('  [Log Locations]');
-    console.log(`  Session logs: ${SESSIONS_DIR}`);
+    console.log(`  Session logs:       ${SESSIONS_DIR}`);
     if (exists(SESSIONS_DIR)) {
         const sessionCount = fs.readdirSync(SESSIONS_DIR).filter((f) => f.endsWith('.json')).length;
-        console.log(`  Saved sessions: ${sessionCount}`);
+        console.log(`  Saved sessions:     ${sessionCount}`);
+    }
+    // v0.4.8 (A3): v1 effective state directory 도 가시화 — 두 dir 책임 다름.
+    console.log(`  V1 effective state: ${V1_SESSIONS_DIR}`);
+    if (exists(V1_SESSIONS_DIR)) {
+        const stateCount = fs.readdirSync(V1_SESSIONS_DIR).filter((f) => f.endsWith('.json')).length;
+        console.log(`  V1 state count:     ${stateCount}`);
     }
     console.log(`  Claude Code sessions: ${CLAUDE_PROJECTS_DIR}`);
     console.log();
@@ -244,7 +285,7 @@ export async function runDoctor(opts = {}) {
     }
     else {
         console.log('  Hook                  Count   p50ms   p95ms   max ms');
-        console.log('  ' + '-'.repeat(56));
+        console.log(`  ${'-'.repeat(56)}`);
         for (const s of timingStats) {
             const hook = s.hook.padEnd(22);
             const count = String(s.count).padStart(5);
@@ -499,7 +540,7 @@ export async function runDoctor(opts = {}) {
         for (const f of failedChecks) {
             if (!bySection.has(f.section))
                 bySection.set(f.section, []);
-            bySection.get(f.section).push(f);
+            bySection.get(f.section)?.push(f);
         }
         for (const [sec, items] of bySection) {
             console.log(`    [${sec}]`);

package/dist/core/harness.js

@@ -165,7 +165,7 @@ function ensureCompoundMemory(cwd) {
             const content = fs.readFileSync(memoryMdPath, 'utf-8');
             if (content.includes('compound-index.md'))
                 return;
-            fs.writeFileSync(memoryMdPath, content.trimEnd() + '\n' + compoundPointer + '\n');
+            fs.writeFileSync(memoryMdPath, `${content.trimEnd()}\n${compoundPointer}\n`);
         }
         const indexPath = path.join(memoryDir, 'compound-index.md');
         const solutionsDir = ME_SOLUTIONS;
@@ -262,7 +262,7 @@ function migrateToForgen() {
         catch (e) {
             log.debug(`migrateToForgen: ${legacyHome} 파일 복사 중 오류`, e);
         }
-        const backupPath = legacyHome + '.bak';
+        const backupPath = `${legacyHome}.bak`;
         try {
             if (!fs.existsSync(backupPath)) {
                 fs.renameSync(legacyHome, backupPath);
@@ -348,6 +348,12 @@ export async function prepareHarness(cwd, options = {}) {
         if (v1Result.legacyBackupPath) {
             log.debug(`v1: 레거시 프로필 백업 완료 → ${v1Result.legacyBackupPath}`);
         }
+        if (v1Result.corruptProfileBackupPath) {
+            // v0.4.8 — corrupt profile auto-repair 결과는 debug 가 아닌 user-visible warning.
+            // 사용자가 onboarding 으로 보내지는 이유를 알 수 있도록.
+            console.warn(`  ⚠  forgen: profile.json 이 깨져 있어 옆에 백업해두고 onboarding 으로 보냅니다.`);
+            console.warn(`  ⚠  backup: ${v1Result.corruptProfileBackupPath}`);
+        }
         if (v1Result.session) {
             const { session } = v1Result;
             log.debug(`v1 세션 시작: ${session.quality_pack}/${session.autonomy_pack}, trust=${session.effective_trust_policy}`);

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('');
+}