@wooojin/forgen 0.4.0 → 0.4.3

package/dist/core/dashboard.js

@@ -23,6 +23,7 @@ const require = createRequire(import.meta.url);
 import { ME_SOLUTIONS, ME_RULES, ME_BEHAVIOR, STATE_DIR, } from './paths.js';
 import { parseFrontmatterOnly } from '../engine/solution-format.js';
 import { readMatchEvalLog } from '../engine/match-eval-log.js';
+import { summarizeAllByHost } from '../store/host-mismatch.js';
 // ── ANSI color helpers ──
 const BOLD = '\x1b[1m';
 const DIM = '\x1b[2m';
@@ -356,6 +357,34 @@ function renderHookHealth(data) {
     lines.push(tableSep(widths, false, true));
     return lines.join('\n');
 }
+/** Collect multi-host evidence distribution from host-mismatch store. */
+export function collectMultiHostData() {
+    try {
+        return summarizeAllByHost();
+    }
+    catch {
+        return { claude: 0, codex: 0, total: 0 };
+    }
+}
+function renderMultiHost(data) {
+    const lines = [];
+    lines.push(`  ${bold(cyan('Multi-Host Evidence'))}`);
+    lines.push('');
+    if (data.total === 0) {
+        lines.push(`  ${dim('No evidence recorded yet.')}`);
+        return lines.join('\n');
+    }
+    const claudePct = Math.round((data.claude / data.total) * 100);
+    const codexPct = Math.round((data.codex / data.total) * 100);
+    lines.push(`  Hosts        claude:${data.claude} (${claudePct}%)  codex:${data.codex} (${codexPct}%)  total:${data.total}`);
+    // skew 경고: 80%+ 집중
+    const maxShare = Math.max(claudePct, codexPct);
+    if (data.total >= 5 && maxShare >= 80) {
+        const dominant = data.claude >= data.codex ? 'claude' : 'codex';
+        lines.push(`  ${yellow(`⚠ ${dominant} 에 ${maxShare}% 집중 — 다른 host 데이터 부족`)}`);
+    }
+    return lines.join('\n');
+}
 /**
  * Learning Curve 수집.
  * evidence 파일(교정 기록)과 compound 활용률을 교차 분석하여 "쓸수록 나아진다"를 정량화.
@@ -372,9 +401,15 @@ export function collectLearningCurve() {
             const files = fs.readdirSync(ME_BEHAVIOR).filter(f => f.endsWith('.json'));
             for (const f of files) {
                 try {
+                    // v0.4.1 정확도 수정: "교정 추이" 라벨은 explicit_correction evidence 만 포함.
+                    // 이전에는 behavior_observation + session_summary 까지 전부 "교정" 으로
+                    // 카운트되어 실측 488건 중 ~1건만 실제 교정인데 신뢰도 훼손. axis_hint 는
+                    // raw_payload 에도 저장되므로 fallback 체크.
                     const data = JSON.parse(fs.readFileSync(path.join(ME_BEHAVIOR, f), 'utf-8'));
                     if (!data.timestamp)
                         continue;
+                    if (data.type && data.type !== 'explicit_correction')
+                        continue;
                     const ts = new Date(data.timestamp).getTime();
                     if (!Number.isFinite(ts))
                         continue;
@@ -383,8 +418,9 @@ export function collectLearningCurve() {
                         correctionsLast7d++;
                     else if (age < 2 * SEVEN_DAYS_MS)
                         correctionsPrev7d++;
-                    if (data.axis_hint) {
-                        axisCounts.set(data.axis_hint, (axisCounts.get(data.axis_hint) ?? 0) + 1);
+                    const axisHint = data.axis_hint ?? data.raw_payload?.axis_hint;
+                    if (axisHint) {
+                        axisCounts.set(axisHint, (axisCounts.get(axisHint) ?? 0) + 1);
                     }
                     uniqueDays.add(new Date(ts).toISOString().slice(0, 10));
                 }
@@ -516,6 +552,7 @@ export function renderDashboard() {
     const session = collectSessionHistory();
     const hookHealth = collectHookHealth();
     const learning = collectLearningCurve();
+    const multiHost = collectMultiHostData();
     const divider = `  ${dim('─'.repeat(50))}`;
     const sections = [
         '',
@@ -531,6 +568,8 @@ export function renderDashboard() {
         divider,
         renderInjectionActivity(injection),
         divider,
+        renderMultiHost(multiHost),
+        divider,
         renderReflectionData(reflection),
         divider,
         renderLifecycleActivity(lifecycle),

package/dist/core/doctor.js

@@ -5,6 +5,7 @@ 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 { getTimingStats } from '../hooks/shared/hook-timing.js';
 import { countSessionScopedFiles, pruneState } from './state-gc.js';
+import { summarizeAllByHost } from '../store/host-mismatch.js';
 /** ~/.claude/projects/ — Claude Code 세션 저장 경로 */
 const CLAUDE_PROJECTS_DIR = path.join(os.homedir(), '.claude', 'projects');
 let currentSection = '';
@@ -34,6 +35,58 @@ function commandExists(cmd) {
         return false;
     }
 }
+/** parity-result.json 내용에서 경과 시간을 사람이 읽기 좋은 문자열로 변환 */
+function relativeTime(isoString) {
+    const diffMs = Date.now() - new Date(isoString).getTime();
+    const diffDays = Math.floor(diffMs / (1000 * 60 * 60 * 24));
+    if (diffDays === 0) {
+        const diffHours = Math.floor(diffMs / (1000 * 60 * 60));
+        if (diffHours === 0) {
+            const diffMins = Math.floor(diffMs / (1000 * 60));
+            return `${diffMins}m ago`;
+        }
+        return `${diffHours}h ago`;
+    }
+    return `${diffDays}d ago`;
+}
+/** [Codex Parity] 섹션 렌더링 — ~/.forgen/state/parity-result.json 신선도 검사 */
+function renderCodexParity() {
+    console.log('  [Codex Parity]');
+    const parityPath = path.join(STATE_DIR, 'parity-result.json');
+    if (!fs.existsSync(parityPath)) {
+        console.log('  △ Codex parity 미실행 — tests/e2e/codex/run-parity.sh 또는 forgen parity codex');
+        return;
+    }
+    let data;
+    try {
+        data = JSON.parse(fs.readFileSync(parityPath, 'utf-8'));
+    }
+    catch {
+        console.log('  ✗ Codex parity — parity-result.json 파싱 실패');
+        return;
+    }
+    if (data.passed === null || data.passed === undefined) {
+        console.log('  △ Codex parity dry-run only — 실 실행 필요');
+        return;
+    }
+    if (!data.passed) {
+        const timeStr = data.at ? relativeTime(data.at) : 'unknown';
+        const detail = data.result ?? data.note ?? 'no detail';
+        console.log(`  ✗ Codex parity FAILED (at: ${timeStr}, detail: ${detail})`);
+        return;
+    }
+    // passed === true
+    const timeStr = data.at ? relativeTime(data.at) : 'unknown';
+    const version = data.version ? ` version ${data.version}` : '';
+    const diffMs = data.at ? Date.now() - new Date(data.at).getTime() : Infinity;
+    const sevenDaysMs = 7 * 24 * 60 * 60 * 1000;
+    if (diffMs > sevenDaysMs) {
+        console.log(`  △ Codex parity green but stale (last run: ${timeStr}) — 재실행 권장`);
+    }
+    else {
+        console.log(`  ✓ Codex parity green (last run: ${timeStr},${version})`);
+    }
+}
 export async function runDoctor(opts = {}) {
     failedChecks = [];
     console.log('\n  Forgen — Diagnostics\n');
@@ -105,18 +158,39 @@ export async function runDoctor(opts = {}) {
     check('Inside tmux session', !!process.env.TMUX, 'FORGEN auto-compound relies on tmux. Launch: tmux new -s forgen');
     check('FORGEN_HARNESS env var', (process.env.FORGEN_HARNESS ?? process.env.COMPOUND_HARNESS) === '1', 'Set by `forgen` / `fgx` launcher. Hooks assume harness mode is active.');
     console.log();
-    // 솔루션/규칙 수
+    // v0.4.1 파일 확장자 버그 수정: rules 는 .json, behavior 도 대부분 .json 포맷.
+    // 이전에 .md 만 count 해서 실 rules 4개인데 0 으로 표시되는 incident 관찰.
+    // (compound-export countFiles 와 동일 결함 — 일관된 수정).
+    const isKnowledgeFile = (f) => f.endsWith('.md') || f.endsWith('.json');
     if (exists(ME_SOLUTIONS)) {
-        const solutions = fs.readdirSync(ME_SOLUTIONS).filter((f) => f.endsWith('.md')).length;
+        const solutions = fs.readdirSync(ME_SOLUTIONS).filter(isKnowledgeFile).length;
         console.log(`  Personal solutions: ${solutions}`);
     }
     if (exists(ME_BEHAVIOR)) {
-        const behavior = fs.readdirSync(ME_BEHAVIOR).filter((f) => f.endsWith('.md')).length;
+        const behavior = fs.readdirSync(ME_BEHAVIOR).filter(isKnowledgeFile).length;
         console.log(`  Behavioral patterns: ${behavior}`);
     }
     if (exists(ME_RULES)) {
-        const rules = fs.readdirSync(ME_RULES).filter((f) => f.endsWith('.md')).length;
-        console.log(`  Personal rules: ${rules}`);
+        // v0.4.1 정확도: removed 상태 rule 은 "학습된 규칙" 에서 제외하고 별도 표시.
+        // 이전에는 디렉터리 파일 수만 세어 이미 제거된 rule 도 count 되어 판매 관점
+        // "살아있는 규칙" 수치가 부풀려짐. 실제 구매자 가치는 active + suppressed.
+        const ruleFiles = fs.readdirSync(ME_RULES).filter(isKnowledgeFile);
+        let active = 0, suppressed = 0, removed = 0;
+        for (const f of ruleFiles) {
+            try {
+                const d = JSON.parse(fs.readFileSync(path.join(ME_RULES, f), 'utf-8'));
+                if (d.status === 'active')
+                    active++;
+                else if (d.status === 'suppressed')
+                    suppressed++;
+                else if (d.status === 'removed' || d.status === 'superseded')
+                    removed++;
+            }
+            catch { /* skip */ }
+        }
+        const live = active + suppressed;
+        const removedTag = removed > 0 ? ` (${removed} removed/superseded)` : '';
+        console.log(`  Personal rules: ${live}  [active:${active} suppressed:${suppressed}]${removedTag}`);
     }
     console.log();
     console.log('  [Log Locations]');
@@ -365,6 +439,45 @@ export async function runDoctor(opts = {}) {
         // git 저장소가 아니거나 origin이 없으면 표시하지 않음
         console.log('  git remote: (none)');
     }
+    // P4 셀프 가드: fix:feat 비율 30% 초과 시 회귀 패턴 의심 경고.
+    try {
+        const { computeFixFeatRatio, formatFixRatio } = await import('./git-stats.js');
+        const ratio = computeFixFeatRatio();
+        if (ratio.available) {
+            console.log(`  ${formatFixRatio(ratio)}`);
+            if (ratio.exceedsThreshold) {
+                console.log('  ⚠ fix:feat 비율이 임계값을 초과했습니다. "이거 고치면 저거 버그난다" 패턴 의심 — 검증 레이어 invariant 점검 권장.');
+            }
+        }
+    }
+    catch { /* fail-open */ }
+    console.log();
+    // [Multi-Host] — host 별 evidence 분포
+    console.log('  [Multi-Host]');
+    try {
+        const hostStats = summarizeAllByHost();
+        if (hostStats.total === 0) {
+            console.log('  No evidence recorded yet.');
+        }
+        else {
+            const claudePct = hostStats.total > 0 ? Math.round((hostStats.claude / hostStats.total) * 100) : 0;
+            const codexPct = hostStats.total > 0 ? Math.round((hostStats.codex / hostStats.total) * 100) : 0;
+            console.log(`  Registered hosts: claude, codex`);
+            console.log(`  Evidence by host: claude:${hostStats.claude} (${claudePct}%)  codex:${hostStats.codex} (${codexPct}%)  total:${hostStats.total}`);
+            // 한 host 가 80% 이상이면 skew 경고
+            const maxShare = Math.max(claudePct, codexPct);
+            if (hostStats.total >= 5 && maxShare >= 80) {
+                const dominant = claudePct >= codexPct ? 'claude' : 'codex';
+                console.log(`  ⚠ evidence 가 ${dominant} 에 ${maxShare}% 집중됨 — 다른 host 에서 학습 데이터 부족 가능`);
+            }
+        }
+    }
+    catch {
+        console.log('  Unable to read host evidence data.');
+    }
+    console.log();
+    // [Codex Parity] — parity-result.json 신선도 검사 (v0.4.2 패턴 확장)
+    renderCodexParity();
     console.log();
     // [Summary] — 최종 상태 요약과 복구 액션을 한눈에 보이게
     console.log('  [Summary]');

package/dist/core/extraction-notice.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Forgen v0.4.1 — Extraction Notice (H2)
+ *
+ * `~/.forgen/state/last-auto-compound.json` 에 기록된 이전 세션의 추출 결과를
+ * Stop hook 에서 1회 surface. noticeShown 플래그로 한번 보여주면 다시 안뜸.
+ *
+ * 목적: v0.4.0 에서 auto-compound 가 8,000+ 번 돌았는데 사용자는 0건 노출. 추출이
+ *   실제로 일어났는지 사용자가 확인할 수 없었다. H2 는 "세션 종료 시 N개 패턴
+ *   학습됨" 1줄을 Stop hook UI (systemMessage) 로 밀어넣는다.
+ */
+/**
+ * Stop hook approve 경로에서 호출. 보여줄 알림이 있으면 1줄 문자열 반환하고
+ * noticeShown=true 로 파일 업데이트 (한 번만 surface). 없으면 null.
+ *
+ * 신선도 컷오프: completedAt 이 30분 이상 지나면 stale 로 간주하고 surface 안함.
+ * 이미 다른 세션에서 본 알림이 튀어나오는 걸 방지.
+ */
+export declare function takeLastExtractionNotice(nowMs?: number): string | null;

package/dist/core/extraction-notice.js

@@ -0,0 +1,64 @@
+/**
+ * Forgen v0.4.1 — Extraction Notice (H2)
+ *
+ * `~/.forgen/state/last-auto-compound.json` 에 기록된 이전 세션의 추출 결과를
+ * Stop hook 에서 1회 surface. noticeShown 플래그로 한번 보여주면 다시 안뜸.
+ *
+ * 목적: v0.4.0 에서 auto-compound 가 8,000+ 번 돌았는데 사용자는 0건 노출. 추출이
+ *   실제로 일어났는지 사용자가 확인할 수 없었다. H2 는 "세션 종료 시 N개 패턴
+ *   학습됨" 1줄을 Stop hook UI (systemMessage) 로 밀어넣는다.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { STATE_DIR } from './paths.js';
+const LAST_AUTO_COMPOUND_PATH = path.join(STATE_DIR, 'last-auto-compound.json');
+/** 정상 실행이면 건너뛰기 좋게 fail-open. */
+function readRecord() {
+    try {
+        if (!fs.existsSync(LAST_AUTO_COMPOUND_PATH))
+            return null;
+        return JSON.parse(fs.readFileSync(LAST_AUTO_COMPOUND_PATH, 'utf-8'));
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Stop hook approve 경로에서 호출. 보여줄 알림이 있으면 1줄 문자열 반환하고
+ * noticeShown=true 로 파일 업데이트 (한 번만 surface). 없으면 null.
+ *
+ * 신선도 컷오프: completedAt 이 30분 이상 지나면 stale 로 간주하고 surface 안함.
+ * 이미 다른 세션에서 본 알림이 튀어나오는 걸 방지.
+ */
+export function takeLastExtractionNotice(nowMs = Date.now()) {
+    const record = readRecord();
+    if (!record || record.noticeShown)
+        return null;
+    const completed = Date.parse(record.completedAt);
+    if (!Number.isFinite(completed))
+        return null;
+    const ageMs = nowMs - completed;
+    if (ageMs > 30 * 60 * 1000)
+        return null; // stale
+    const extracted = record.extractedSolutions ?? 0;
+    const promoted = record.promotedRules ?? 0;
+    if (extracted === 0 && promoted === 0) {
+        // 아무것도 학습되지 않았으면 노이즈. 알림을 소비한 상태로만 마킹.
+        try {
+            fs.writeFileSync(LAST_AUTO_COMPOUND_PATH, JSON.stringify({ ...record, noticeShown: true }));
+        }
+        catch { /* fail-open */ }
+        return null;
+    }
+    // 마킹 — race 는 있으나 double-notice 가 치명적이지 않음 (fail-open).
+    try {
+        fs.writeFileSync(LAST_AUTO_COMPOUND_PATH, JSON.stringify({ ...record, noticeShown: true }));
+    }
+    catch { /* fail-open */ }
+    const parts = [];
+    if (extracted > 0)
+        parts.push(`${extracted}개 패턴 추출`);
+    if (promoted > 0)
+        parts.push(`${promoted}개 규칙 승격`);
+    return `[Forgen] 🧠 세션 학습 완료 — ${parts.join(', ')}`;
+}

package/dist/core/git-stats.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Git Stats — P4 셀프 가드 (2026-04-27)
+ *
+ * 최근 N커밋의 conventional commit 분포를 측정해 fix:feat 비율을 계산.
+ * 정상 OSS 권장은 fix < 20%. 36% 초과 시 회귀 패턴 의심 — forgen 의 자기 메타 가드.
+ *
+ * 이번 세션 측정값: v0.4.1 시점 fix 비율 36% (정상의 약 2배). 이 코드가 다음 릴리즈
+ * 시 같은 비율을 자동 노출하여 사용자가 회귀 패턴을 빠르게 인지하게 한다.
+ */
+export interface FixRatioStats {
+    windowSize: number;
+    fixCount: number;
+    featCount: number;
+    /** fix / (fix + feat), 0~1. fix+feat=0 이면 0. */
+    ratio: number;
+    threshold: number;
+    exceedsThreshold: boolean;
+    /** git 명령이 성공했는지 (저장소 외부 또는 git 미설치 시 false). */
+    available: boolean;
+}
+/**
+ * git log --no-merges -N 결과에서 conventional commit 형식의 fix/feat 만 카운트.
+ *
+ * 분류:
+ *   - `feat: ...` / `feat(scope): ...` → feat
+ *   - `fix: ...` / `fix(scope): ...` → fix (단, scope ∈ {test, tests, docs, doc} 제외)
+ *   - 그 외 (chore, refactor, docs, style, test, hash 없는 라인) → 무시
+ *
+ * fix(test):, fix(docs): 가 제외되는 이유: 사소한 노이즈 fix 가 회귀 신호를
+ * 흐리지 않도록. 진짜 위험은 fix(core), fix(hook), fix(api) 같은 logic fix.
+ */
+export declare function computeFixFeatRatio(cwd?: string, windowSize?: number, threshold?: number): FixRatioStats;
+/** 테스트용 — git log 출력 텍스트를 직접 파싱. */
+export declare function parseGitLog(rawLog: string, windowSize?: number, threshold?: number): FixRatioStats;
+/** 사람용 한 줄 라벨. */
+export declare function formatFixRatio(s: FixRatioStats): string;

package/dist/core/git-stats.js

@@ -0,0 +1,79 @@
+/**
+ * Git Stats — P4 셀프 가드 (2026-04-27)
+ *
+ * 최근 N커밋의 conventional commit 분포를 측정해 fix:feat 비율을 계산.
+ * 정상 OSS 권장은 fix < 20%. 36% 초과 시 회귀 패턴 의심 — forgen 의 자기 메타 가드.
+ *
+ * 이번 세션 측정값: v0.4.1 시점 fix 비율 36% (정상의 약 2배). 이 코드가 다음 릴리즈
+ * 시 같은 비율을 자동 노출하여 사용자가 회귀 패턴을 빠르게 인지하게 한다.
+ */
+import { execFileSync } from 'node:child_process';
+const DEFAULT_THRESHOLD = 0.30;
+const DEFAULT_WINDOW = 30;
+const SCOPE_EXCLUSIONS = new Set(['test', 'tests', 'docs', 'doc']);
+/**
+ * git log --no-merges -N 결과에서 conventional commit 형식의 fix/feat 만 카운트.
+ *
+ * 분류:
+ *   - `feat: ...` / `feat(scope): ...` → feat
+ *   - `fix: ...` / `fix(scope): ...` → fix (단, scope ∈ {test, tests, docs, doc} 제외)
+ *   - 그 외 (chore, refactor, docs, style, test, hash 없는 라인) → 무시
+ *
+ * fix(test):, fix(docs): 가 제외되는 이유: 사소한 노이즈 fix 가 회귀 신호를
+ * 흐리지 않도록. 진짜 위험은 fix(core), fix(hook), fix(api) 같은 logic fix.
+ */
+export function computeFixFeatRatio(cwd = process.cwd(), windowSize = DEFAULT_WINDOW, threshold = DEFAULT_THRESHOLD) {
+    try {
+        const out = execFileSync('git', ['log', '--no-merges', '--oneline', `-${windowSize}`], { cwd, encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'] });
+        return parseGitLog(out, windowSize, threshold);
+    }
+    catch {
+        return makeUnavailable(windowSize, threshold);
+    }
+}
+/** 테스트용 — git log 출력 텍스트를 직접 파싱. */
+export function parseGitLog(rawLog, windowSize = DEFAULT_WINDOW, threshold = DEFAULT_THRESHOLD) {
+    const lines = rawLog.trim().split('\n').filter(Boolean);
+    let fix = 0;
+    let feat = 0;
+    for (const line of lines) {
+        const msg = line.replace(/^[a-f0-9]{4,40}\s+/, '');
+        const m = msg.match(/^(fix|feat)(?:\(([^)]+)\))?:/);
+        if (!m)
+            continue;
+        const type = m[1];
+        const scope = (m[2] ?? '').toLowerCase().trim();
+        if (type === 'fix' && SCOPE_EXCLUSIONS.has(scope))
+            continue;
+        if (type === 'fix')
+            fix++;
+        else
+            feat++;
+    }
+    const total = fix + feat;
+    const ratio = total === 0 ? 0 : fix / total;
+    return {
+        windowSize,
+        fixCount: fix,
+        featCount: feat,
+        ratio,
+        threshold,
+        exceedsThreshold: ratio > threshold,
+        available: true,
+    };
+}
+function makeUnavailable(windowSize, threshold) {
+    return {
+        windowSize, fixCount: 0, featCount: 0, ratio: 0,
+        threshold, exceedsThreshold: false, available: false,
+    };
+}
+/** 사람용 한 줄 라벨. */
+export function formatFixRatio(s) {
+    if (!s.available)
+        return 'fix:feat ratio    n/a    (git unavailable)';
+    const pct = (s.ratio * 100).toFixed(0);
+    const thresholdPct = (s.threshold * 100).toFixed(0);
+    const flag = s.exceedsThreshold ? `  ⚠ over ${thresholdPct}%` : '';
+    return `fix:feat ratio    ${pct}%   (${s.fixCount}/${s.fixCount + s.featCount} in last ${s.windowSize})${flag}`;
+}

package/dist/core/harness.d.ts

@@ -9,7 +9,7 @@
  * - Lines 50-120: Rule file injection, gitignore, compound memory
  * - Lines 120+: prepareHarness — main orchestration
  */
-import { type RuntimeHost } from './types.js';
+import type { RuntimeHost } from './types.js';
 import { rollbackSettings } from './settings-lock.js';
 import { type V1BootstrapResult } from './v1-bootstrap.js';
 export interface V1HarnessContext {

package/dist/core/harness.js

@@ -326,32 +326,39 @@ export async function prepareHarness(cwd, options = {}) {
         }
         // 3. 환경 확인
         const inTmux = !!process.env.TMUX;
-        // 4. Claude Code 설정 주입 (환경변수 + trust 기반 permissions).
+        // 4-7. Claude artifact 작업 (settings.json + agents + rules + slash commands).
         //
-        // Audit fix #1 (2026-04-21): acquireLock에서 live holder 감지 시
-        // SettingsLockError가 throw될 수 있다. 사용자 작업 자체를 실패시키지
-        // 않도록 warn 후 계속 진행 (이번 실행에서 settings는 기존 값 유지).
+        // feat/codex-support P1-7 (2026-04-27): runtime === 'codex' 시 *.claude/* 계열
+        // 작업은 *no-op*. Codex 측 동치 prep 은 Phase 3 (install-codex.ts 의 prompts +
+        // AGENTS.md inject) 에서 처리. 본 분기는 *Claude artifact 가 Codex 환경을
+        // 오염시키지 않도록* 보호하는 비대칭 게이트.
         const pkgRoot = getPackageRoot();
         const env = buildEnv(cwd, v1Result.session?.session_id, runtime);
-        try {
-            injectSettings(env, v1Result, runtime, cwd, pkgRoot);
-        }
-        catch (e) {
-            const msg = e instanceof Error ? e.message : String(e);
-            if (msg.includes('settings.json lock') || msg.includes('SettingsLockError')) {
-                console.error(`[forgen] ${msg} — settings 갱신 스킵, 이전 값 유지`);
+        if (runtime === 'claude') {
+            // 4. settings.json 인젝션
+            try {
+                injectSettings(env, v1Result, runtime, cwd, pkgRoot);
             }
-            else {
-                throw e;
+            catch (e) {
+                const msg = e instanceof Error ? e.message : String(e);
+                if (msg.includes('settings.json lock') || msg.includes('SettingsLockError')) {
+                    console.error(`[forgen] ${msg} — settings 갱신 스킵, 이전 값 유지`);
+                }
+                else {
+                    throw e;
+                }
             }
+            // 5. 에이전트 설치
+            installAgents(cwd, pkgRoot);
+            // 6. 규칙 파일 생성 + 주입
+            const ruleFiles = generateClaudeRuleFiles(cwd, v1Result.renderedRules);
+            injectClaudeRuleFiles(cwd, ruleFiles);
+            // 7. 슬래시 명령 설치
+            installSlashCommands(cwd, pkgRoot);
+        }
+        else {
+            log.debug(`prepareHarness: runtime=${runtime} — Claude artifact prep skipped (Phase 3 handles Codex prep)`);
         }
-        // 5. 에이전트 설치
-        installAgents(cwd, pkgRoot);
-        // 6. 규칙 파일 생성 및 주입 (v1 부트스트랩 결과의 renderedRules를 직접 전달)
-        const ruleFiles = generateClaudeRuleFiles(cwd, v1Result.renderedRules);
-        injectClaudeRuleFiles(cwd, ruleFiles);
-        // 7. 슬래시 명령 설치
-        installSlashCommands(cwd, pkgRoot);
         // 8. tmux 바인딩 등록
         if (inTmux) {
             await registerTmuxBindings();

package/dist/core/host-detect.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Host detection — feat/codex-support Phase 1
+ *
+ * `forgen install` interactive 의 prerequisite — 사용자 환경에 어떤 host (Claude/Codex)
+ * 가 가용한지 탐지. spec §10 Phase 1 + interview R3.
+ *
+ * 탐지 신호 (각 host 별):
+ *   - binary 가 PATH 에 있음 (`which claude` / `which codex`)
+ *   - host 디렉토리 존재 (~/.claude/ / ~/.codex/)
+ *   - (Codex 만) `~/.codex/auth.json` 존재 (로그인 흔적)
+ *
+ * detect 결과는 *추론* 만. install 강제 안 함.
+ */
+import type { HostId } from './trust-layer-intent.js';
+export interface HostAvailability {
+    readonly host: HostId;
+    /** binary 가 PATH 에 있음. */
+    readonly binaryFound: boolean;
+    /** binary 절대경로 (없으면 null). */
+    readonly binaryPath: string | null;
+    /** host home 디렉토리 존재 (~/.claude/ 또는 ~/.codex/). */
+    readonly homeExists: boolean;
+    /** host home 절대경로. */
+    readonly homePath: string;
+    /** Codex 의 경우 auth.json 존재 (로그인 흔적). Claude 는 항상 null. */
+    readonly authPresent: boolean | null;
+    /**
+     * 종합 판단 — *install 후보로 적합한가*.
+     * - binaryFound 또는 homeExists 중 하나 이상이면 true.
+     * - 둘 다 없으면 false (사용자가 host 를 안 쓸 가능성 높음).
+     */
+    readonly available: boolean;
+}
+export interface HostDetectionResult {
+    readonly claude: HostAvailability;
+    readonly codex: HostAvailability;
+    /** 둘 다 사용 가능. */
+    readonly bothAvailable: boolean;
+    /** 하나도 사용 가능하지 않음 (warn). */
+    readonly noneAvailable: boolean;
+}
+export declare function detectAvailableHosts(): HostDetectionResult;

package/dist/core/host-detect.js

@@ -0,0 +1,68 @@
+/**
+ * Host detection — feat/codex-support Phase 1
+ *
+ * `forgen install` interactive 의 prerequisite — 사용자 환경에 어떤 host (Claude/Codex)
+ * 가 가용한지 탐지. spec §10 Phase 1 + interview R3.
+ *
+ * 탐지 신호 (각 host 별):
+ *   - binary 가 PATH 에 있음 (`which claude` / `which codex`)
+ *   - host 디렉토리 존재 (~/.claude/ / ~/.codex/)
+ *   - (Codex 만) `~/.codex/auth.json` 존재 (로그인 흔적)
+ *
+ * detect 결과는 *추론* 만. install 강제 안 함.
+ */
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { execFileSync } from 'node:child_process';
+function which(binary) {
+    try {
+        const out = execFileSync('which', [binary], { encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'] });
+        const trimmed = out.trim();
+        return trimmed.length > 0 ? trimmed : null;
+    }
+    catch {
+        return null;
+    }
+}
+function detectClaude() {
+    const binaryPath = which('claude');
+    const homePath = path.join(os.homedir(), '.claude');
+    const homeExists = fs.existsSync(homePath);
+    const binaryFound = binaryPath !== null;
+    return {
+        host: 'claude',
+        binaryFound,
+        binaryPath,
+        homeExists,
+        homePath,
+        authPresent: null, // Claude 는 별도 auth.json 패턴이 없음 (subscription 통합)
+        available: binaryFound || homeExists,
+    };
+}
+function detectCodex() {
+    const binaryPath = which('codex');
+    const codexHome = process.env.CODEX_HOME ?? path.join(os.homedir(), '.codex');
+    const homeExists = fs.existsSync(codexHome);
+    const binaryFound = binaryPath !== null;
+    const authPresent = fs.existsSync(path.join(codexHome, 'auth.json'));
+    return {
+        host: 'codex',
+        binaryFound,
+        binaryPath,
+        homeExists,
+        homePath: codexHome,
+        authPresent,
+        available: binaryFound || homeExists,
+    };
+}
+export function detectAvailableHosts() {
+    const claude = detectClaude();
+    const codex = detectCodex();
+    return {
+        claude,
+        codex,
+        bothAvailable: claude.available && codex.available,
+        noneAvailable: !claude.available && !codex.available,
+    };
+}

package/dist/core/init-cli.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Forgen v0.4.1 — `forgen init` CLI
+ *
+ * 빈 FORGEN_HOME (또는 기존에 starter 미설치 홈) 에 starter-pack 솔루션을
+ * 프로비저닝. npm install-g 시의 postinstall 이 하던 starter 배포 로직을 런타임
+ * CLI 로 노출해 다음 시나리오 지원:
+ *   - `FORGEN_HOME=/tmp/fresh forgen init` — 격리 테스트 환경
+ *   - CI pipeline 신규 컨테이너 프로비저닝
+ *   - 사용자가 실수로 me/solutions 전부 삭제한 뒤 복구
+ *
+ * 보수적 정책: me/solutions 에 **≥5개 파일**이 이미 있으면 건너뜀 (사용자
+ * 실 축적물 보호). `--force` 플래그로 우회 가능. postinstall 의 installStarterPack
+ * 과 동일 규칙.
+ */
+export interface InitResult {
+    solutionsInstalled: number;
+    solutionsSkippedExisting: number;
+    solutionsDir: string;
+    starterDir: string | null;
+    skipped: boolean;
+    skipReason?: string;
+}
+export declare function initializeForgenHome(options?: {
+    force?: boolean;
+}): InitResult;
+export declare function handleInit(args: string[]): Promise<void>;