@wooojin/forgen 0.4.0 → 0.4.3

package/dist/core/init-cli.js

@@ -0,0 +1,104 @@
+/**
+ * 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
+ * 과 동일 규칙.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { ME_DIR } from './paths.js';
+/** 패키지 루트의 starter-pack/solutions 디렉터리. */
+function findStarterDir() {
+    // 런타임에 dist/core/init-cli.js — 패키지 루트는 상위 2단계
+    const distDir = path.dirname(fileURLToPath(import.meta.url));
+    const pkgRoot = path.resolve(distDir, '..', '..');
+    const starterDir = path.join(pkgRoot, 'starter-pack', 'solutions');
+    return fs.existsSync(starterDir) ? starterDir : null;
+}
+export function initializeForgenHome(options = {}) {
+    const solutionsDir = path.join(ME_DIR, 'solutions');
+    const starterDir = findStarterDir();
+    if (!starterDir) {
+        return {
+            solutionsInstalled: 0,
+            solutionsSkippedExisting: 0,
+            solutionsDir,
+            starterDir: null,
+            skipped: true,
+            skipReason: 'starter-pack directory not found in package',
+        };
+    }
+    let existing = 0;
+    if (fs.existsSync(solutionsDir)) {
+        existing = fs.readdirSync(solutionsDir).filter((f) => f.endsWith('.md')).length;
+    }
+    if (existing >= 5 && !options.force) {
+        return {
+            solutionsInstalled: 0,
+            solutionsSkippedExisting: existing,
+            solutionsDir,
+            starterDir,
+            skipped: true,
+            skipReason: `${existing} existing solutions (≥5) — use --force to overwrite`,
+        };
+    }
+    fs.mkdirSync(solutionsDir, { recursive: true });
+    const starterFiles = fs.readdirSync(starterDir).filter((f) => f.endsWith('.md'));
+    let installed = 0;
+    for (const file of starterFiles) {
+        const dest = path.join(solutionsDir, file);
+        if (!fs.existsSync(dest) || options.force) {
+            fs.cpSync(path.join(starterDir, file), dest);
+            installed++;
+        }
+    }
+    return {
+        solutionsInstalled: installed,
+        solutionsSkippedExisting: existing,
+        solutionsDir,
+        starterDir,
+        skipped: false,
+    };
+}
+export async function handleInit(args) {
+    const force = args.includes('--force');
+    if (args.includes('--help') || args.includes('-h')) {
+        console.log(`
+  forgen init — starter-pack 프로비저닝 (기존 솔루션 보호)
+
+  Usage:
+    forgen init            Install starter-pack if solutions/ has < 5 files
+    forgen init --force    Overwrite any existing starter files (idempotent)
+    FORGEN_HOME=... forgen init    새 홈에 격리 초기화
+
+  Starter pack = starter-* 로 시작하는 범용 개발 패턴 솔루션. 신규 사용자가
+  "compound recall" 효과를 첫날부터 체감할 수 있도록 설치 시 기본 제공되지만,
+  npm install-g 을 거치지 않은 격리/컨테이너 환경은 이 CLI 로 수동 배포.
+`);
+        return;
+    }
+    const result = initializeForgenHome({ force });
+    console.log('');
+    console.log('  forgen init');
+    console.log('  ──────────');
+    console.log(`  FORGEN_HOME           ${path.dirname(result.solutionsDir)}`);
+    console.log(`  starter-pack source   ${result.starterDir ?? 'NOT FOUND'}`);
+    console.log(`  existing solutions    ${result.solutionsSkippedExisting}`);
+    console.log(`  newly installed       ${result.solutionsInstalled}`);
+    if (result.skipped) {
+        console.log(`  status                skipped — ${result.skipReason}`);
+    }
+    else {
+        console.log(`  status                ✓ initialized`);
+    }
+    console.log('');
+}

package/dist/core/init.js

@@ -8,6 +8,7 @@ import * as fs from 'node:fs';
 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';
 // ── CLI 핸들러 ──
 export async function handleInit(_args) {
     const cwd = process.cwd();
@@ -18,6 +19,22 @@ export async function handleInit(_args) {
     // 프로젝트 .claude/rules 디렉토리 생성
     const rulesDir = path.join(cwd, '.claude', 'rules');
     fs.mkdirSync(rulesDir, { recursive: true });
+    // v0.4.1 (2026-04-24): starter-pack 프로비저닝 — 격리 홈 / 신규 FORGEN_HOME
+    // 에서 "신규 사용자 첫날 가치" 가 0이 되는 결함 해소. npm install-g 시의
+    // postinstall 이 하던 starter 배포를 런타임에서도 보장.
+    // 보수적: me/solutions 에 ≥5개면 skip — 기존 사용자 실 축적물 보호.
+    try {
+        const r = initializeForgenHome();
+        if (r.solutionsInstalled > 0) {
+            console.log(`  ✓ Starter-pack: ${r.solutionsInstalled} solutions installed.`);
+        }
+        else if (r.skipped && r.solutionsSkippedExisting > 0) {
+            console.log(`  • Starter-pack: skipped (${r.solutionsSkippedExisting} existing solutions).`);
+        }
+    }
+    catch (e) {
+        console.log(`  ⚠ Starter-pack install 실패: ${e.message}`);
+    }
     // 프로필 존재 확인
     if (profileExists()) {
         console.log('  Profile already exists. Your personalization is active.');

package/dist/core/inspect-cli.js

@@ -5,7 +5,6 @@
  * Authoritative: docs/plans/2026-04-03-forgen-rule-renderer-spec.md §6
  */
 import * as fs from 'node:fs';
-import * as os from 'node:os';
 import * as path from 'node:path';
 import { loadProfile } from '../store/profile-store.js';
 import { loadAllRules, loadActiveRules } from '../store/rule-store.js';
@@ -102,7 +101,7 @@ export async function handleInspect(args) {
             bypass: 'bypass.jsonl',
             drift: 'drift.jsonl',
         };
-        const p = path.join(os.homedir(), '.forgen', 'state', 'enforcement', fileMap[sub]);
+        const p = path.join(STATE_DIR, 'enforcement', fileMap[sub]);
         if (!fs.existsSync(p)) {
             console.log(`\n  No ${sub} data (${p} not found).\n`);
             return;

package/dist/core/installer.js

@@ -111,7 +111,7 @@ export function installAgents(cwd, pkgRoot) {
     const targetDir = path.join(cwd, '.claude', 'agents');
     fs.mkdirSync(targetDir, { recursive: true });
     const hashes = loadAgentHashes();
-    const sourceDir = path.join(pkgRoot, 'agents');
+    const sourceDir = path.join(pkgRoot, 'assets', 'claude', 'agents');
     try {
         installAgentsFromDir(sourceDir, targetDir, 'ch-', hashes);
         cleanupStaleAgents(sourceDir, targetDir, 'ch-', hashes);
@@ -159,7 +159,7 @@ function cleanupStaleCommands(commandsDir, validFiles) {
 }
 /** 스킬을 Claude Code 슬래시 명령으로 설치 (패키지 내장만) */
 export function installSlashCommands(_cwd, pkgRoot) {
-    let skillsDir = path.join(pkgRoot, 'commands');
+    let skillsDir = path.join(pkgRoot, 'assets', 'claude', 'commands');
     if (!fs.existsSync(skillsDir)) {
         skillsDir = path.join(pkgRoot, 'skills');
     }

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

@@ -0,0 +1,11 @@
+/**
+ * Forgen v0.4.1 — `forgen migrate` CLI
+ *
+ * 데이터 스키마 업그레이드를 1회성으로 돌리는 관리 명령.
+ * 현재 대상:
+ *   - implicit-feedback: TEST-5 category 필드 백필 (type → category inference).
+ *     기본은 lazy (read 시점 백필) 이지만 집계/외부 도구가 raw jsonl 을 읽는
+ *     경우 영구 재기록이 필요.
+ *   - evidence-host: ~/.forgen/me/behavior/*.json 에 host 필드가 없는 파일 백필.
+ */
+export declare function handleMigrate(args: string[]): Promise<void>;

package/dist/core/migrate-cli.js

@@ -0,0 +1,53 @@
+/**
+ * Forgen v0.4.1 — `forgen migrate` CLI
+ *
+ * 데이터 스키마 업그레이드를 1회성으로 돌리는 관리 명령.
+ * 현재 대상:
+ *   - implicit-feedback: TEST-5 category 필드 백필 (type → category inference).
+ *     기본은 lazy (read 시점 백필) 이지만 집계/외부 도구가 raw jsonl 을 읽는
+ *     경우 영구 재기록이 필요.
+ *   - evidence-host: ~/.forgen/me/behavior/*.json 에 host 필드가 없는 파일 백필.
+ */
+import { migrateImplicitFeedbackLog } from '../store/implicit-feedback-store.js';
+import { migrateEvidenceHost } from './migrate-evidence-host.js';
+const HELP = `
+  forgen migrate — one-shot schema migrations
+
+  Usage:
+    forgen migrate implicit-feedback   category 필드가 없는 레거시 엔트리 백필 + 재기록
+    forgen migrate all                 (현재는 implicit-feedback 과 동일)
+    forgen migrate evidence-host       behavior/*.json 에 host 필드 백필
+      --dry-run                          디스크 미수정, 카운트만 출력
+      --default-host <claude|codex>      host 기본값 (default: claude)
+    forgen migrate --help              이 도움말
+`;
+export async function handleMigrate(args) {
+    const sub = args[0];
+    if (!sub || sub === '--help' || sub === '-h' || sub === 'help') {
+        console.log(HELP);
+        return;
+    }
+    if (sub === 'implicit-feedback' || sub === 'all') {
+        console.log('[forgen migrate] implicit-feedback.jsonl 백필 시작...');
+        const { migrated, dropped } = migrateImplicitFeedbackLog();
+        console.log(`[forgen migrate] 백필 ${migrated}건, 드롭 ${dropped}건 — 재기록 완료.`);
+        return;
+    }
+    if (sub === 'evidence-host') {
+        const dryRun = args.includes('--dry-run');
+        const hostFlagIdx = args.indexOf('--default-host');
+        const rawHost = hostFlagIdx !== -1 ? args[hostFlagIdx + 1] : 'claude';
+        if (rawHost !== 'claude' && rawHost !== 'codex') {
+            console.error(`[forgen migrate] --default-host 는 'claude' 또는 'codex' 여야 합니다. 받은 값: ${rawHost}`);
+            process.exit(1);
+        }
+        const defaultHost = rawHost;
+        const result = migrateEvidenceHost({ defaultHost, dryRun });
+        const label = dryRun ? ' (dry-run)' : '';
+        console.log(`[forgen] migrated: ${result.migrated} (skipped: ${result.skipped}, total: ${result.total})${label}`);
+        return;
+    }
+    console.error(`[forgen migrate] unknown target: ${sub}`);
+    console.error(HELP);
+    process.exit(1);
+}

package/dist/core/migrate-evidence-host.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Forgen — Evidence Host Backfill Migration
+ *
+ * spec §10 우선순위 5 + §4.2:
+ * 사용자가 명시적으로 디스크의 evidence 파일에 host 필드를 박제하고 싶을 때 사용.
+ * (마이그레이션 박제, audit 목적)
+ *
+ * loadEvidence 의 자동 backfill (evidence-store.ts::backfillHost) 과는 독립.
+ * 이 모듈은 디스크 파일을 직접 수정하는 명시적 경로.
+ */
+export interface MigrateEvidenceHostOptions {
+    /** backfill 할 host 값 (host 필드 없는 파일에만 적용) */
+    defaultHost: 'claude' | 'codex';
+    /**
+     * true 이면 디스크를 수정하지 않고 카운트만 반환.
+     * @default false
+     */
+    dryRun?: boolean;
+}
+export interface MigrateEvidenceHostResult {
+    /** host 필드를 새로 추가한 파일 수 */
+    migrated: number;
+    /** 처리 대상 전체 .json 파일 수 */
+    total: number;
+    /** 이미 host 필드가 있어 건너뛴 파일 수 */
+    skipped: number;
+}
+/**
+ * `~/.forgen/me/behavior/*.json` 을 순회하여 host 필드가 없는 파일에
+ * `defaultHost` 를 추가한다.
+ *
+ * - dryRun=true 이면 디스크 미수정, 카운트만 반환.
+ * - 이미 host 필드가 있는 파일은 건너뜀 (idempotent).
+ * - 파싱 실패 / host 필드가 아닌 값인 파일도 건너뜀 (안전).
+ */
+export declare function migrateEvidenceHost(options: MigrateEvidenceHostOptions): MigrateEvidenceHostResult;

package/dist/core/migrate-evidence-host.js

@@ -0,0 +1,49 @@
+/**
+ * Forgen — Evidence Host Backfill Migration
+ *
+ * spec §10 우선순위 5 + §4.2:
+ * 사용자가 명시적으로 디스크의 evidence 파일에 host 필드를 박제하고 싶을 때 사용.
+ * (마이그레이션 박제, audit 목적)
+ *
+ * loadEvidence 의 자동 backfill (evidence-store.ts::backfillHost) 과는 독립.
+ * 이 모듈은 디스크 파일을 직접 수정하는 명시적 경로.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { ME_BEHAVIOR } from './paths.js';
+import { atomicWriteJSON, safeReadJSON } from '../hooks/shared/atomic-write.js';
+/**
+ * `~/.forgen/me/behavior/*.json` 을 순회하여 host 필드가 없는 파일에
+ * `defaultHost` 를 추가한다.
+ *
+ * - dryRun=true 이면 디스크 미수정, 카운트만 반환.
+ * - 이미 host 필드가 있는 파일은 건너뜀 (idempotent).
+ * - 파싱 실패 / host 필드가 아닌 값인 파일도 건너뜀 (안전).
+ */
+export function migrateEvidenceHost(options) {
+    const { defaultHost, dryRun = false } = options;
+    if (!fs.existsSync(ME_BEHAVIOR)) {
+        return { migrated: 0, total: 0, skipped: 0 };
+    }
+    const files = fs.readdirSync(ME_BEHAVIOR).filter((f) => f.endsWith('.json'));
+    let migrated = 0;
+    let skipped = 0;
+    for (const file of files) {
+        const filePath = path.join(ME_BEHAVIOR, file);
+        const data = safeReadJSON(filePath, null);
+        if (data === null || typeof data !== 'object') {
+            skipped++;
+            continue;
+        }
+        const host = data['host'];
+        if (host === 'claude' || host === 'codex') {
+            skipped++;
+            continue;
+        }
+        if (!dryRun) {
+            atomicWriteJSON(filePath, { ...data, host: defaultHost }, { pretty: true });
+        }
+        migrated++;
+    }
+    return { migrated, total: files.length, skipped };
+}

package/dist/core/paths.d.ts

@@ -2,7 +2,14 @@
 export declare const CLAUDE_DIR: string;
 /** ~/.claude/settings.json — Claude Code 설정 파일 */
 export declare const SETTINGS_PATH: string;
-/** ~/.forgen/ — v1 하네스 홈 디렉토리 */
+/**
+ * ~/.forgen/ — v1 하네스 홈 디렉토리.
+ *
+ * v0.4.1 (2026-04-24): FORGEN_HOME env 로 override 가능.
+ * 목적: CI/e2e 에서 격리된 fresh forgen 홈으로 "신규 사용자 시뮬" + 내 실 홈
+ *   (2338+ 세션 축적물) 을 건드리지 않음. README/docs 에도 "테스트 격리" 섹션
+ *   으로 노출 예정.
+ */
 export declare const FORGEN_HOME: string;
 /** ~/.forgen/me/ — 개인 공간 (v5.1: ~/.compound/ → ~/.forgen/ 통합) */
 export declare const ME_DIR: string;

package/dist/core/paths.js

@@ -5,8 +5,17 @@ const HOME = os.homedir();
 export const CLAUDE_DIR = path.join(HOME, '.claude');
 /** ~/.claude/settings.json — Claude Code 설정 파일 */
 export const SETTINGS_PATH = path.join(CLAUDE_DIR, 'settings.json');
-/** ~/.forgen/ — v1 하네스 홈 디렉토리 */
-export const FORGEN_HOME = path.join(HOME, '.forgen');
+/**
+ * ~/.forgen/ — v1 하네스 홈 디렉토리.
+ *
+ * v0.4.1 (2026-04-24): FORGEN_HOME env 로 override 가능.
+ * 목적: CI/e2e 에서 격리된 fresh forgen 홈으로 "신규 사용자 시뮬" + 내 실 홈
+ *   (2338+ 세션 축적물) 을 건드리지 않음. README/docs 에도 "테스트 격리" 섹션
+ *   으로 노출 예정.
+ */
+export const FORGEN_HOME = process.env.FORGEN_HOME
+    ? path.resolve(process.env.FORGEN_HOME)
+    : path.join(HOME, '.forgen');
 /** ~/.forgen/me/ — 개인 공간 (v5.1: ~/.compound/ → ~/.forgen/ 통합) */
 export const ME_DIR = path.join(FORGEN_HOME, 'me');
 /** ~/.forgen/me/philosophy.json — 개인 철학 */

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

@@ -0,0 +1,26 @@
+/**
+ * Forgen v0.4.1 — `forgen recall` CLI (H5)
+ *
+ * 최근 UserPromptSubmit 에서 매칭/surface 된 솔루션을 사용자에게 되짚어주는 명령.
+ *
+ * 목적: v0.4.0 에서 compound 솔루션이 8,000+ 번 recall 되었지만 사용자는 0건을
+ *   확인할 수 없었다. 이 CLI 는 `~/.forgen/state/implicit-feedback.jsonl` 과
+ *   `~/.forgen/state/match-eval-log.jsonl` 을 읽어 "최근 어떤 지식이 붙었나" 를
+ *   1초 안에 보여준다. `--show` 플래그로 솔루션 본문 preview 까지.
+ *
+ * Usage:
+ *   forgen recall              최근 10건 요약
+ *   forgen recall --limit 20   최근 N건
+ *   forgen recall --show       본문 preview 포함
+ *   forgen recall --json       JSON 출력 (script 연동용)
+ */
+interface RecallEntry {
+    at: string;
+    sessionId: string;
+    solution: string;
+    match_score?: number;
+}
+/** H5: implicit-feedback.jsonl 에서 recommendation_surfaced 만 시간역순으로 추출. */
+export declare function loadRecentRecalls(limit?: number): RecallEntry[];
+export declare function handleRecall(args: string[]): Promise<void>;
+export {};

package/dist/core/recall-cli.js

@@ -0,0 +1,125 @@
+/**
+ * Forgen v0.4.1 — `forgen recall` CLI (H5)
+ *
+ * 최근 UserPromptSubmit 에서 매칭/surface 된 솔루션을 사용자에게 되짚어주는 명령.
+ *
+ * 목적: v0.4.0 에서 compound 솔루션이 8,000+ 번 recall 되었지만 사용자는 0건을
+ *   확인할 수 없었다. 이 CLI 는 `~/.forgen/state/implicit-feedback.jsonl` 과
+ *   `~/.forgen/state/match-eval-log.jsonl` 을 읽어 "최근 어떤 지식이 붙었나" 를
+ *   1초 안에 보여준다. `--show` 플래그로 솔루션 본문 preview 까지.
+ *
+ * Usage:
+ *   forgen recall              최근 10건 요약
+ *   forgen recall --limit 20   최근 N건
+ *   forgen recall --show       본문 preview 포함
+ *   forgen recall --json       JSON 출력 (script 연동용)
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { STATE_DIR, ME_SOLUTIONS } from './paths.js';
+function readJsonl(p) {
+    if (!fs.existsSync(p))
+        return [];
+    const out = [];
+    for (const line of fs.readFileSync(p, 'utf-8').split('\n')) {
+        if (!line.trim())
+            continue;
+        try {
+            out.push(JSON.parse(line));
+        }
+        catch { /* skip malformed */ }
+    }
+    return out;
+}
+/** H5: implicit-feedback.jsonl 에서 recommendation_surfaced 만 시간역순으로 추출. */
+export function loadRecentRecalls(limit = 10) {
+    const entries = readJsonl(path.join(STATE_DIR, 'implicit-feedback.jsonl'));
+    const out = [];
+    for (const e of entries) {
+        if (e.type !== 'recommendation_surfaced')
+            continue;
+        if (typeof e.at !== 'string' || typeof e.solution !== 'string')
+            continue;
+        out.push({
+            at: e.at,
+            sessionId: typeof e.sessionId === 'string' ? e.sessionId : 'unknown',
+            solution: e.solution,
+            match_score: typeof e.match_score === 'number' ? e.match_score : undefined,
+        });
+    }
+    return out.sort((a, b) => b.at.localeCompare(a.at)).slice(0, limit);
+}
+/** 솔루션 body preview — frontmatter 뒤 첫 N줄. */
+function readSolutionPreview(solutionName, maxLines = 8) {
+    const candidates = [
+        path.join(ME_SOLUTIONS, `${solutionName}.md`),
+        path.join(ME_SOLUTIONS, solutionName),
+    ];
+    for (const p of candidates) {
+        if (!fs.existsSync(p))
+            continue;
+        try {
+            const raw = fs.readFileSync(p, 'utf-8');
+            // frontmatter block skip (--- ... ---)
+            const stripped = raw.replace(/^---[\s\S]*?---\n?/, '');
+            const lines = stripped.split('\n').filter((l) => l.length > 0).slice(0, maxLines);
+            return lines.join('\n');
+        }
+        catch {
+            return null;
+        }
+    }
+    return null;
+}
+function parseArgs(args) {
+    let limit = 10;
+    let showBody = false;
+    let json = false;
+    for (let i = 0; i < args.length; i++) {
+        const a = args[i];
+        if (a === '--limit' && i + 1 < args.length) {
+            const n = Number(args[++i]);
+            if (Number.isFinite(n) && n > 0)
+                limit = Math.min(100, Math.floor(n));
+        }
+        else if (a === '--show' || a === '--body') {
+            showBody = true;
+        }
+        else if (a === '--json') {
+            json = true;
+        }
+    }
+    return { limit, showBody, json };
+}
+export async function handleRecall(args) {
+    const { limit, showBody, json } = parseArgs(args);
+    const recalls = loadRecentRecalls(limit);
+    if (json) {
+        const payload = recalls.map((r) => ({
+            ...r,
+            preview: showBody ? readSolutionPreview(r.solution) : undefined,
+        }));
+        console.log(JSON.stringify(payload, null, 2));
+        return;
+    }
+    if (recalls.length === 0) {
+        console.log('  (no recent recalls — run a session with compound hooks enabled)');
+        return;
+    }
+    console.log('');
+    console.log(`  forgen recall — last ${recalls.length} surfaced solution${recalls.length === 1 ? '' : 's'}`);
+    console.log('  ─────────────────────────────────────────');
+    for (const r of recalls) {
+        const score = r.match_score !== undefined ? ` @${r.match_score.toFixed(2)}` : '';
+        console.log(`  ${r.at.slice(0, 19).replace('T', ' ')}  ${r.solution}${score}`);
+        if (showBody) {
+            const body = readSolutionPreview(r.solution);
+            if (body) {
+                for (const line of body.split('\n'))
+                    console.log(`    │ ${line}`);
+                console.log('');
+            }
+        }
+    }
+    console.log('');
+}

package/dist/core/recall-reference-detector.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Forgen v0.4.1 — Recall Reference Detector (H4 완결)
+ *
+ * US-06 에서 `recommendation_surfaced` (주입 = Claude 컨텍스트에 보여졌다) 는
+ * emit 경로가 있지만, `recall_referenced` (Claude 가 실제로 참조/인용했다) 는
+ * enum 만 정의되고 emit 경로가 없었다. 이 결함 때문에 "채널은 뚫렸지만 활용은
+ * 측정 불가" 상태. 이 모듈이 그 측정 경로를 닫는다.
+ *
+ * 알고리즘:
+ *   1. Stop hook 에서 lastAssistantMessage 를 읽는다.
+ *   2. 현재 세션의 injection-cache 에서 최근 주입된 솔루션 목록을 가져온다.
+ *   3. 각 솔루션의 **name** 이 메시지 텍스트에 등장하면 참조한 것으로 간주.
+ *      (tag 매칭은 false-positive 과다 — "협업" 같은 흔한 단어로 오매칭.)
+ *   4. 중복 emit 방지: injection-cache 엔트리에 `_referenced: true` 플래그 세팅.
+ *
+ * 순수 함수 설계 — Stop hook 이 inject-cache 를 읽고 쓰는 I/O 는 호출지에서.
+ */
+export interface InjectedSolutionEntry {
+    name: string;
+    identifiers?: string[];
+    tags?: string[];
+    status?: string;
+    injectedAt?: string;
+    _referenced?: boolean;
+}
+export interface RecallReferenceDetection {
+    /** 이번 턴에 처음 참조가 감지된 솔루션 이름 목록. */
+    newlyReferenced: string[];
+}
+/**
+ * 순수 판정 — text 안에 아직 참조 안 된 솔루션의 name / 고유 식별자 / 희귀 태그
+ * 조합이 등장하면 수집.
+ *
+ * v0.4.1 초기: name (slug kebab-case) literal 만 매칭 → Claude 가 content 만 인용
+ *   하고 slug 를 안 쓰면 측정 불가.
+ * v0.4.1 확장 (2026-04-24): identifier (함수/파일명 literal, >=4자) 또는 **복합
+ *   태그 2개 동시 등장** 도 weak reference 로 인정. false-positive 완화 위해:
+ *     - identifier 는 길이 ≥4
+ *     - tag 는 **복합 슬러그 (`-` 또는 `_` 포함)** 만 허용 + length ≥6
+ *       → "tdd", "test", "workflow" 같은 일반 태그 단독 매칭은 제외
+ *     - tag 매칭은 최소 2개 교차
+ */
+export declare function detectRecallReferences(text: string, injected: readonly InjectedSolutionEntry[]): RecallReferenceDetection;

package/dist/core/recall-reference-detector.js

@@ -0,0 +1,65 @@
+/**
+ * Forgen v0.4.1 — Recall Reference Detector (H4 완결)
+ *
+ * US-06 에서 `recommendation_surfaced` (주입 = Claude 컨텍스트에 보여졌다) 는
+ * emit 경로가 있지만, `recall_referenced` (Claude 가 실제로 참조/인용했다) 는
+ * enum 만 정의되고 emit 경로가 없었다. 이 결함 때문에 "채널은 뚫렸지만 활용은
+ * 측정 불가" 상태. 이 모듈이 그 측정 경로를 닫는다.
+ *
+ * 알고리즘:
+ *   1. Stop hook 에서 lastAssistantMessage 를 읽는다.
+ *   2. 현재 세션의 injection-cache 에서 최근 주입된 솔루션 목록을 가져온다.
+ *   3. 각 솔루션의 **name** 이 메시지 텍스트에 등장하면 참조한 것으로 간주.
+ *      (tag 매칭은 false-positive 과다 — "협업" 같은 흔한 단어로 오매칭.)
+ *   4. 중복 emit 방지: injection-cache 엔트리에 `_referenced: true` 플래그 세팅.
+ *
+ * 순수 함수 설계 — Stop hook 이 inject-cache 를 읽고 쓰는 I/O 는 호출지에서.
+ */
+/**
+ * 순수 판정 — text 안에 아직 참조 안 된 솔루션의 name / 고유 식별자 / 희귀 태그
+ * 조합이 등장하면 수집.
+ *
+ * v0.4.1 초기: name (slug kebab-case) literal 만 매칭 → Claude 가 content 만 인용
+ *   하고 slug 를 안 쓰면 측정 불가.
+ * v0.4.1 확장 (2026-04-24): identifier (함수/파일명 literal, >=4자) 또는 **복합
+ *   태그 2개 동시 등장** 도 weak reference 로 인정. false-positive 완화 위해:
+ *     - identifier 는 길이 ≥4
+ *     - tag 는 **복합 슬러그 (`-` 또는 `_` 포함)** 만 허용 + length ≥6
+ *       → "tdd", "test", "workflow" 같은 일반 태그 단독 매칭은 제외
+ *     - tag 매칭은 최소 2개 교차
+ */
+export function detectRecallReferences(text, injected) {
+    if (!text || injected.length === 0)
+        return { newlyReferenced: [] };
+    const newlyReferenced = [];
+    for (const sol of injected) {
+        if (sol._referenced)
+            continue;
+        if (!sol.name || sol.name.length < 4)
+            continue;
+        let matched = false;
+        // 1순위: slug name 정확 매칭 (precision 최고)
+        if (text.includes(sol.name)) {
+            matched = true;
+        }
+        // 2순위: 고유 identifier (함수/파일명 literal) 매칭
+        if (!matched && sol.identifiers) {
+            for (const id of sol.identifiers) {
+                if (typeof id === 'string' && id.length >= 4 && text.includes(id)) {
+                    matched = true;
+                    break;
+                }
+            }
+        }
+        // 3순위: 복합-슬러그 태그 2개 이상 동시 등장 (일반 단어 단독은 제외)
+        if (!matched && sol.tags) {
+            const specificTags = sol.tags.filter((t) => typeof t === 'string' && t.length >= 6 && (t.includes('-') || t.includes('_')));
+            const hits = specificTags.filter((t) => text.includes(t));
+            if (hits.length >= 2)
+                matched = true;
+        }
+        if (matched)
+            newlyReferenced.push(sol.name);
+    }
+    return { newlyReferenced };
+}

package/dist/core/settings-injector.js

@@ -7,6 +7,7 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { generateHooksJson } from '../hooks/hooks-generator.js';
+import { getHostRuntime } from '../host/host-runtime.js';
 import { ConfigError } from './errors.js';
 import { createLogger } from './logger.js';
 import { acquireLock, atomicWriteFileSync, CLAUDE_DIR, readSettingsSafely, releaseLock, rollbackSettings, SETTINGS_BACKUP_PATH, SETTINGS_PATH, } from './settings-lock.js';
@@ -74,7 +75,8 @@ function mergeHooksIntoSettings(settings, runtime, cwd, pkgRoot) {
             hooksConfig[event] = filtered;
     }
     try {
-        if (runtime === 'codex') {
+        const host = getHostRuntime(runtime);
+        if (host.hookInjectionStrategy === 'generate') {
             const generated = generateHooksJson({ cwd, runtime, pluginRoot: path.join(pkgRoot, 'dist') });
             for (const [event, handlers] of Object.entries(generated.hooks)) {
                 if (!hooksConfig[event])
@@ -83,7 +85,7 @@ function mergeHooksIntoSettings(settings, runtime, cwd, pkgRoot) {
             }
         }
         else {
-            // Read hooks.json and inject, replacing ${CLAUDE_PLUGIN_ROOT}
+            // 'pre-baked-file': pkgRoot/hooks/hooks.json 읽고 ${CLAUDE_PLUGIN_ROOT} 치환
             const hooksJsonPath = path.join(pkgRoot, 'hooks', 'hooks.json');
             if (fs.existsSync(hooksJsonPath)) {
                 const hooksJson = JSON.parse(fs.readFileSync(hooksJsonPath, 'utf-8'));

package/dist/core/spawn.d.ts

@@ -1,5 +1,5 @@
 import type { V1HarnessContext } from './harness.js';
-import { type RuntimeHost } from './types.js';
+import type { RuntimeHost } from './types.js';
 /** Claude Code를 하네스 환경으로 실행. exit code를 반환. */
 export declare function spawnClaude(args: string[], context: V1HarnessContext, runtime?: RuntimeHost): Promise<number>;
 /**