@wooojin/forgen 0.3.2 → 0.4.1

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

@@ -78,7 +78,8 @@ export async function handleInspect(args) {
         console.log('\n' + inspect.renderRules(rules) + '\n');
         return;
     }
-    if (sub === 'evidence') {
+    // R9-IA2: user-facing name is "corrections"; "evidence" kept as back-compat alias.
+    if (sub === 'corrections' || sub === 'evidence') {
         const evidence = loadRecentEvidence(20);
         console.log('\n' + inspect.renderEvidence(evidence) + '\n');
         return;
@@ -92,9 +93,67 @@ export async function handleInspect(args) {
         console.log('\n' + inspect.renderSession(sessions[0]) + '\n');
         return;
     }
+    // R5-G1: 2AM 디버깅용 jsonl tail — violations/bypass/drift
+    if (sub === 'violations' || sub === 'bypass' || sub === 'drift') {
+        const limit = Number(args[args.indexOf('--last') + 1]) || 20;
+        const fileMap = {
+            violations: 'violations.jsonl',
+            bypass: 'bypass.jsonl',
+            drift: 'drift.jsonl',
+        };
+        const p = path.join(STATE_DIR, 'enforcement', fileMap[sub]);
+        if (!fs.existsSync(p)) {
+            console.log(`\n  No ${sub} data (${p} not found).\n`);
+            return;
+        }
+        const lines = fs.readFileSync(p, 'utf-8').trim().split('\n').filter(Boolean);
+        const tail = lines.slice(-limit);
+        console.log(`\n  ${sub} (last ${tail.length} of ${lines.length}):`);
+        // rule_id별 집계
+        const byRule = new Map();
+        for (const line of lines) {
+            try {
+                const entry = JSON.parse(line);
+                const rid = entry.rule_id ?? 'unknown';
+                byRule.set(rid, (byRule.get(rid) ?? 0) + 1);
+            }
+            catch { /* skip malformed */ }
+        }
+        if (byRule.size > 0) {
+            console.log('  Aggregate (rule_id → count):');
+            for (const [rid, count] of [...byRule.entries()].sort((a, b) => b[1] - a[1]).slice(0, 10)) {
+                console.log(`    ${rid.slice(0, 24).padEnd(24)} ${count}`);
+            }
+        }
+        // R7-U3: rule_id 전체 표시 + kind + source 분리 + resolve hint footer.
+        console.log('\n  Recent (time — rule_id — kind@source — preview):');
+        for (const line of tail) {
+            try {
+                const e = JSON.parse(line);
+                const when = (e.at ?? '').slice(0, 19);
+                const rid = (e.rule_id ?? '-').slice(0, 24); // 8자→24자 (prefix match 가능 길이)
+                const kind = (e.kind ?? '-');
+                const source = (e.source ?? '-');
+                const preview = (e.message_preview ?? e.reason_preview ?? e.pattern_preview ?? '').slice(0, 60);
+                console.log(`    ${when}  ${rid.padEnd(24)}  ${String(kind).padEnd(10)}@${String(source).padEnd(14)}  ${preview}`);
+            }
+            catch { /* skip */ }
+        }
+        console.log('');
+        // R7-U3 footer: resolve hint
+        console.log('  Resolve:');
+        console.log('    Disable a rule:   forgen suppress-rule <rule_id>');
+        console.log('    Re-enable:        forgen activate-rule <rule_id>');
+        console.log('    Temp bypass turn: set FORGEN_USER_CONFIRMED=1 (audited)');
+        console.log('');
+        return;
+    }
     console.log(`  Usage:
-    forgen inspect profile   — 현재 profile 상태
-    forgen inspect rules     — active/suppressed 규칙 목록
-    forgen inspect evidence  — 최근 evidence 목록
-    forgen inspect session   — 현재/최근 세션 상태`);
+    forgen inspect profile               — 현재 profile 상태
+    forgen inspect rules                 — active/suppressed 규칙 목록
+    forgen inspect corrections           — 최근 corrections / behavior 기록 (alias: evidence)
+    forgen inspect session               — 현재/최근 세션 상태
+    forgen inspect violations [--last N] — 최근 block 기록
+    forgen inspect bypass     [--last N] — 사용자 우회 기록
+    forgen inspect drift      [--last N] — stuck-loop force-approve 기록`);
 }

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

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

package/dist/core/migrate-cli.js

@@ -0,0 +1,34 @@
+/**
+ * Forgen v0.4.1 — `forgen migrate` CLI
+ *
+ * 데이터 스키마 업그레이드를 1회성으로 돌리는 관리 명령.
+ * 현재 대상:
+ *   - implicit-feedback: TEST-5 category 필드 백필 (type → category inference).
+ *     기본은 lazy (read 시점 백필) 이지만 집계/외부 도구가 raw jsonl 을 읽는
+ *     경우 영구 재기록이 필요.
+ */
+import { migrateImplicitFeedbackLog } from '../store/implicit-feedback-store.js';
+const HELP = `
+  forgen migrate — one-shot schema migrations
+
+  Usage:
+    forgen migrate implicit-feedback   category 필드가 없는 레거시 엔트리 백필 + 재기록
+    forgen migrate all                 (현재는 implicit-feedback 과 동일)
+    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;
+    }
+    console.error(`[forgen migrate] unknown target: ${sub}`);
+    console.error(HELP);
+    process.exit(1);
+}

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

@@ -23,6 +23,25 @@ export interface PruneOptions {
  * deletion via `dryRun: false`.
  */
 export declare function pruneState(opts?: PruneOptions): PruneReport;
+/**
+ * ADR-002 T4 — daily rule decay scanner.
+ *
+ * `~/.forgen/me/rules` 전체를 훑어 `last_inject_at < now - decay_days` 인 active rule 을
+ * retire phase 로 전이시킨다. 실제 파일 삭제가 아니라 status='removed' + phase='retired'.
+ *
+ * 호출 지점: `forgen doctor --prune-state` 또는 `forgen lifecycle-scan --apply` 그리고
+ * 별도 cron/CI scheduler 에서도 호출 가능. dryRun=true 기본.
+ */
+export declare function runDailyT4Decay(opts?: {
+    decayDays?: number;
+    dryRun?: boolean;
+    now?: number;
+}): Promise<{
+    scanned: number;
+    retired: number;
+    sample: string[];
+    dryRun: boolean;
+}>;
 /**
  * Count session-scoped files in STATE_DIR without deleting. Used by doctor
  * to surface a warning when the directory is bloated.

package/dist/core/state-gc.js

@@ -94,15 +94,59 @@ export function pruneState(opts = {}) {
     // outcomes/*.jsonl: one file per session, session-scoped by design.
     // These compound over time exactly like state session files.
     const outcomes = pruneDir(outcomesDir, cutoff, dryRun, (n) => n.endsWith('.jsonl'));
+    // ADR-002 block-count directory — session-scoped per rule. F-M block-count GC.
+    const blockCountDir = path.join(stateDir, 'enforcement', 'block-count');
+    const blockCounters = pruneDir(blockCountDir, cutoff, dryRun, (n) => n.endsWith('.json'));
     return {
-        scanned: state.scanned + outcomes.scanned,
-        pruned: state.pruned + outcomes.pruned,
-        bytesFreed: state.bytes + outcomes.bytes,
+        scanned: state.scanned + outcomes.scanned + blockCounters.scanned,
+        pruned: state.pruned + outcomes.pruned + blockCounters.pruned,
+        bytesFreed: state.bytes + outcomes.bytes + blockCounters.bytes,
         retentionDays: Math.round(retentionMs / (24 * 60 * 60 * 1000)),
         dryRun,
-        sample: [...state.sample, ...outcomes.sample].slice(0, 20),
+        sample: [...state.sample, ...outcomes.sample, ...blockCounters.sample].slice(0, 20),
     };
 }
+/**
+ * ADR-002 T4 — daily rule decay scanner.
+ *
+ * `~/.forgen/me/rules` 전체를 훑어 `last_inject_at < now - decay_days` 인 active rule 을
+ * retire phase 로 전이시킨다. 실제 파일 삭제가 아니라 status='removed' + phase='retired'.
+ *
+ * 호출 지점: `forgen doctor --prune-state` 또는 `forgen lifecycle-scan --apply` 그리고
+ * 별도 cron/CI scheduler 에서도 호출 가능. dryRun=true 기본.
+ */
+export async function runDailyT4Decay(opts = {}) {
+    const decayDays = opts.decayDays ?? 90;
+    const dryRun = opts.dryRun ?? true;
+    const now = opts.now ?? Date.now();
+    try {
+        const [{ loadAllRules, saveRule }, { detect: detectT4 }, { collectAllSignals }, { appendLifecycleEvents }, { foldEvents }] = await Promise.all([
+            import('../store/rule-store.js'),
+            import('../engine/lifecycle/trigger-t4-decay.js'),
+            import('../engine/lifecycle/signals.js'),
+            import('../engine/lifecycle/meta-reclassifier.js'),
+            import('../engine/lifecycle/orchestrator.js'),
+        ]);
+        const rules = loadAllRules();
+        const signals = collectAllSignals(rules, { now });
+        const events = detectT4({ rules, signals, decay_days: decayDays, ts: now });
+        const report = { scanned: rules.length, retired: events.length, sample: events.map((e) => e.rule_id.slice(0, 8)), dryRun };
+        if (!dryRun && events.length > 0) {
+            const folded = foldEvents(rules, events, now);
+            for (const [id, updated] of folded.entries()) {
+                const original = rules.find((r) => r.rule_id === id);
+                if (!original || updated === original)
+                    continue;
+                saveRule(updated);
+            }
+            appendLifecycleEvents(events, now);
+        }
+        return report;
+    }
+    catch {
+        return { scanned: 0, retired: 0, sample: [], dryRun };
+    }
+}
 /**
  * Count session-scoped files in STATE_DIR without deleting. Used by doctor
  * to surface a warning when the directory is bloated.