@wooojin/forgen 0.4.12 → 0.5.0

package/dist/engine/extraction-session.js

@@ -8,6 +8,7 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { CLAUDE_DIR, STATE_DIR } from '../core/paths.js';
 import { createLogger } from '../core/logger.js';
+import { stripPrivate } from './private-filter.js';
 const log = createLogger('extraction-session');
 function normalizeProjectPath(cwd) {
     const resolved = path.resolve(cwd);
@@ -119,7 +120,12 @@ function collectClaudeProjectSessionContext(files, cwdCandidates, cutoffMs) {
             if (entry.type === 'user') {
                 const message = entry.message;
                 if (message?.role === 'user' && typeof message.content === 'string') {
-                    prompts.push(message.content);
+                    // W2-5 (private 태그): 이 함수는 ~/.claude/projects/ 원시 트랜스크립트를 직접
+                    // 읽는 마지막 캡처 경로다(prompt-history·session-store 와 별개 소스). <private>
+                    // 범위를 제거해 학습 신호에서 배제하고, 통째 private 프롬프트는 push 하지 않는다.
+                    const cleaned = stripPrivate(message.content).cleaned;
+                    if (cleaned.trim())
+                        prompts.push(cleaned);
                 }
                 continue;
             }
@@ -137,8 +143,9 @@ function collectClaudeProjectSessionContext(files, cwdCandidates, cutoffMs) {
                 if (toolUse.name !== 'Write' && toolUse.name !== 'Edit')
                     continue;
                 const filePath = String(toolUse.input?.file_path ?? toolUse.input?.filePath ?? '');
-                const content = String(toolUse.input?.content ?? toolUse.input?.new_string ?? '');
-                if (!filePath || !content)
+                // W2-5: write 스니펫도 원시 코드(<private> 가능) — 캡처 전 strip.
+                const content = stripPrivate(String(toolUse.input?.content ?? toolUse.input?.new_string ?? '')).cleaned;
+                if (!filePath || !content.trim())
                     continue;
                 writes.push({
                     filePath: filePath.slice(-100),

package/dist/engine/private-filter.d.ts

@@ -0,0 +1,36 @@
+/**
+ * private-filter — <private> 캡처 제외 태그 (Wave 2 W2-5, feature-audit 2026-07-21).
+ *
+ * 사용자가 응답/교정/코드에 민감 내용을 담을 때, 그 범위를 compound 추출·correction
+ * 캡처·solution 저장·세션 인덱싱에서 제외한다. secret-filter(비밀키 커밋 차단)와는
+ * 별개 축 — 이건 "학습 코퍼스에 넣지 말라"는 사용자 의도 마킹이다. $0-로컬·프라이버시
+ * 우선 도구에 정합하며, 캡처 신뢰도를 높인다(사용자가 안심하고 교정할 수 있음).
+ *
+ * 마커 (claude-mem <private> 대응 + 편의 라인 마커):
+ *   1. 블록:  <private> … </private>   (다중 라인, 대소문자 무시, 속성/공백 허용)
+ *   2. 라인:  // forgen:private        (해당 라인 전체 제외)
+ *             # forgen:private          (동일, 해시 주석 스타일)
+ *             /* forgen:private          (동일, 블록주석 시작 스타일)
+ *
+ * fail-closed 원칙 (프라이버시 필터의 핵심): 사용자가 닫는 태그를 잊거나 오타를
+ * 내는 것이 가장 흔한 실수다. 미닫힘 <private> 는 *조용히 누출*하지 않고 EOF 까지
+ * private 로 취급한다(fail-closed). 중첩은 depth 카운팅으로 바깥까지 제거한다.
+ *
+ * 제외는 *조용히* 하지 않는다 — 호출측이 hadPrivate 로 로그/공지할 수 있게 반환한다.
+ */
+export interface StripPrivateResult {
+    /** private 범위를 제거한 텍스트. */
+    cleaned: string;
+    /** 제거된 private 범위가 하나라도 있었는지 (조용한 제외 방지 — 호출측 공지용). */
+    hadPrivate: boolean;
+}
+/**
+ * <private> 블록 및 라인 마커 범위를 제거한다.
+ * 완전히 private 이면 cleaned 는 (공백만 남아) '' 에 가깝다 — isFullyPrivate 로 판정.
+ */
+export declare function stripPrivate(text: string): StripPrivateResult;
+/**
+ * 캡처 대상이 *통째로* private 인지 — private 제거 후 의미 있는 내용이 남지 않으면 true.
+ * (공백/개행만 남는 경우 포함) → 호출측은 저장 자체를 skip.
+ */
+export declare function isFullyPrivate(text: string): boolean;

package/dist/engine/private-filter.js

@@ -0,0 +1,100 @@
+/**
+ * private-filter — <private> 캡처 제외 태그 (Wave 2 W2-5, feature-audit 2026-07-21).
+ *
+ * 사용자가 응답/교정/코드에 민감 내용을 담을 때, 그 범위를 compound 추출·correction
+ * 캡처·solution 저장·세션 인덱싱에서 제외한다. secret-filter(비밀키 커밋 차단)와는
+ * 별개 축 — 이건 "학습 코퍼스에 넣지 말라"는 사용자 의도 마킹이다. $0-로컬·프라이버시
+ * 우선 도구에 정합하며, 캡처 신뢰도를 높인다(사용자가 안심하고 교정할 수 있음).
+ *
+ * 마커 (claude-mem <private> 대응 + 편의 라인 마커):
+ *   1. 블록:  <private> … </private>   (다중 라인, 대소문자 무시, 속성/공백 허용)
+ *   2. 라인:  // forgen:private        (해당 라인 전체 제외)
+ *             # forgen:private          (동일, 해시 주석 스타일)
+ *             /* forgen:private          (동일, 블록주석 시작 스타일)
+ *
+ * fail-closed 원칙 (프라이버시 필터의 핵심): 사용자가 닫는 태그를 잊거나 오타를
+ * 내는 것이 가장 흔한 실수다. 미닫힘 <private> 는 *조용히 누출*하지 않고 EOF 까지
+ * private 로 취급한다(fail-closed). 중첩은 depth 카운팅으로 바깥까지 제거한다.
+ *
+ * 제외는 *조용히* 하지 않는다 — 호출측이 hadPrivate 로 로그/공지할 수 있게 반환한다.
+ */
+/** 여는 태그: 속성/공백 허용 (<private>, <private >, <private foo="x">). */
+const PRIVATE_OPEN_RE = /<private(?:\s[^>]*)?>/i;
+/** 닫는 태그: 공백 허용 (</private>, </private >). */
+const PRIVATE_CLOSE_RE = /<\/private\s*>/i;
+/** 라인 마커: //, #, /* 주석 스타일 + forgen:private. 해당 라인 전체 제거. */
+const PRIVATE_LINE_RE = /^.*(?:\/\/|#|\/\*)\s*forgen:private.*$/gim;
+/**
+ * <private> 블록 범위를 fail-closed 로 제거한다.
+ *   - 닫힌 블록: 여는~닫는 태그 사이 제거 (중첩은 depth 카운팅).
+ *   - 미닫힘 블록: 여는 태그부터 EOF 까지 제거 (닫기를 잊은 사용자 보호).
+ */
+function stripBlocks(text) {
+    let hadPrivate = false;
+    let result = '';
+    let i = 0;
+    while (i < text.length) {
+        const rest = text.slice(i);
+        const open = rest.match(PRIVATE_OPEN_RE);
+        if (!open || open.index === undefined) {
+            result += rest;
+            break;
+        }
+        const openAbs = i + open.index;
+        // 여는 태그 앞 텍스트는 유지
+        result += text.slice(i, openAbs);
+        hadPrivate = true;
+        // 여는 태그 뒤부터 nesting 을 고려해 매칭 닫는 태그를 찾는다.
+        let depth = 1;
+        let j = openAbs + open[0].length;
+        while (j < text.length && depth > 0) {
+            const tail = text.slice(j);
+            const nextOpen = tail.match(PRIVATE_OPEN_RE);
+            const nextClose = tail.match(PRIVATE_CLOSE_RE);
+            const openIdx = nextOpen?.index ?? Infinity;
+            const closeIdx = nextClose?.index ?? Infinity;
+            if (openIdx === Infinity && closeIdx === Infinity) {
+                // 닫는 태그 없음 → fail-closed: EOF 까지 private 취급.
+                j = text.length;
+                depth = 0;
+                break;
+            }
+            if (openIdx < closeIdx) {
+                depth++;
+                j += openIdx + (nextOpen[0].length);
+            }
+            else {
+                depth--;
+                j += closeIdx + (nextClose[0].length);
+            }
+        }
+        // depth>0 로 루프 종료 = EOF 도달(미닫힘) → 이미 j=text.length. 블록 전체 건너뜀.
+        i = j;
+    }
+    return { cleaned: result, hadPrivate };
+}
+/**
+ * <private> 블록 및 라인 마커 범위를 제거한다.
+ * 완전히 private 이면 cleaned 는 (공백만 남아) '' 에 가깝다 — isFullyPrivate 로 판정.
+ */
+export function stripPrivate(text) {
+    if (!text)
+        return { cleaned: text ?? '', hadPrivate: false };
+    const blocks = stripBlocks(text);
+    let hadPrivate = blocks.hadPrivate;
+    const cleaned = blocks.cleaned.replace(PRIVATE_LINE_RE, () => {
+        hadPrivate = true;
+        return '';
+    });
+    return { cleaned, hadPrivate };
+}
+/**
+ * 캡처 대상이 *통째로* private 인지 — private 제거 후 의미 있는 내용이 남지 않으면 true.
+ * (공백/개행만 남는 경우 포함) → 호출측은 저장 자체를 skip.
+ */
+export function isFullyPrivate(text) {
+    if (!text)
+        return false; // 빈 입력은 private 이 아니라 그냥 없음
+    const { cleaned, hadPrivate } = stripPrivate(text);
+    return hadPrivate && cleaned.trim().length === 0;
+}

package/dist/engine/ranking-pipeline.js

@@ -7,7 +7,7 @@
  */
 import { maskBlockedTokens } from './phrase-blocklist.js';
 import { calculateRelevance } from './relevance-scorer.js';
-import { expandCompoundTags, expandQueryBigrams } from './solution-format.js';
+import { expandCompoundTags, expandQueryBigrams, expandQueryKoreanStems } from './solution-format.js';
 import { shouldRejectByR4T3Rules } from './precision-guards.js';
 import { defaultNormalizer } from './term-normalizer.js';
 /**
@@ -26,7 +26,9 @@ export function rankCandidates(promptTags, promptLower, solutions, ensembleWeigh
     if (maskedPromptTags.length === 0)
         return [];
     // R4-T1: expand prompt tags with adjacent-token bigrams
-    const promptTagsWithBigrams = expandQueryBigrams(maskedPromptTags);
+    // R5(vec-probe): 한국어 활용형 어간 회복 — `검증해줘` 류 회화체 쿼리가
+    // `검증` 계열 솔루션 태그에 도달하게 한다 (쿼리 사이드 전용, 인덱스 불변).
+    const promptTagsWithBigrams = expandQueryKoreanStems(expandQueryBigrams(maskedPromptTags));
     const normalizedPromptTags = defaultNormalizer.normalizeTerms(promptTagsWithBigrams);
     return solutions
         .map((sol) => {

package/dist/engine/relevance-gate.d.ts

@@ -0,0 +1,12 @@
+/**
+ * relevance-gate — TF-IDF/BM25/bigram relevance 매칭의 *정준* 게이트 임계(단일 소스).
+ *
+ * 2026-04-21 gate sweep(100% precision/60% recall 데이터)로 실측 튜닝된 값. 동일한
+ * relevance-scorer 표현을 쓰는 소비자들이 이 상수 하나를 공유한다:
+ *   - solution 주입 게이트 (solution-injector.MIN_INJECT_RELEVANCE)
+ *   - 교정 클러스터링 편입 임계 (correction-clustering.CLUSTER_SIMILARITY_TAU)
+ *
+ * W3-2 리뷰(SEV-3 #1): 이전엔 각 소비자가 리터럴 0.3 을 복제해 "상속"이 주석뿐이었다.
+ * 여기로 단일화해 한쪽만 바뀌는 근거-정직성 드리프트를 코드로 방지한다.
+ */
+export declare const RELEVANCE_MATCH_GATE = 0.3;

package/dist/engine/relevance-gate.js

@@ -0,0 +1,12 @@
+/**
+ * relevance-gate — TF-IDF/BM25/bigram relevance 매칭의 *정준* 게이트 임계(단일 소스).
+ *
+ * 2026-04-21 gate sweep(100% precision/60% recall 데이터)로 실측 튜닝된 값. 동일한
+ * relevance-scorer 표현을 쓰는 소비자들이 이 상수 하나를 공유한다:
+ *   - solution 주입 게이트 (solution-injector.MIN_INJECT_RELEVANCE)
+ *   - 교정 클러스터링 편입 임계 (correction-clustering.CLUSTER_SIMILARITY_TAU)
+ *
+ * W3-2 리뷰(SEV-3 #1): 이전엔 각 소비자가 리터럴 0.3 을 복제해 "상속"이 주석뿐이었다.
+ * 여기로 단일화해 한쪽만 바뀌는 근거-정직성 드리프트를 코드로 방지한다.
+ */
+export const RELEVANCE_MATCH_GATE = 0.3;

package/dist/engine/roi-demotion.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Forgen v0.5.0 — Injection ROI 루프 (ADR-010 W3-1, F2)
+ *
+ * 근거: v0.4.11 실측에서 forgen 의 δ 는 100% injection 에서 나왔다 (blocks=0).
+ * 따라서 injection 품질 = 효과 그 자체다. "surfaced 는 많은데 acted_on 이
+ * 없는" 솔루션은 컨텍스트 비용만 내는 저 ROI 주입이므로 자동 강등한다.
+ * native 메모리(claude-mem 등)에는 없는 acted-on 피드백 루프 — moat 기능.
+ *
+ * 설계 (Rev 2 — 리뷰에서 기존 solution-quarantine 재사용 불가 확정):
+ *  - 전용 저장소 `~/.forgen/state/roi-demotions.json`
+ *    (기존 quarantine 은 frontmatter 파스 에러 기반 — 시맨틱 불일치)
+ *  - `ranking-pipeline.ts` 는 순수 유지 — 강등은 matchSolutions 결과 후처리
+ *  - 판정 갱신은 auto-compound 세션 종료 시 (updateRoiDemotions)
+ *  - 임계 (config.json roiDemotion 으로 조정 가능):
+ *      surfaced_90d >= 3 && acted/surfaced < 0.1  → 강등 (relevance ×0.5)
+ *      2회 연속 강등 유지                          → 격리 (주입 제외)
+ *      acted_on 신규 발생                          → 즉시 해제
+ */
+import { type HitRateRow } from '../core/observability-store.js';
+export interface RoiDemotionEntry {
+    solutionId: string;
+    reason: 'low-roi';
+    demotedAt: string;
+    /** 연속 강등 유지 윈도 수 — 2 이상이면 격리(주입 제외) */
+    windowCount: number;
+    /** 마지막 windowCount 증가 시점 — 24h 미만 재평가는 증가 없음 (리뷰 SEV-2:
+     *  평가는 auto-compound 세션마다 도는데, 같은 날 2세션으로 격리되면
+     *  "2회 연속 윈도" 설계 의도 위반. 90d 통계는 당일 내 사실상 불변이라
+     *  같은 날 재평가는 새 정보가 없다.) */
+    lastEvaluatedAt: string;
+    surfaced: number;
+    actedOn: number;
+}
+export type RoiDemotions = Record<string, RoiDemotionEntry>;
+export interface RoiThresholds {
+    /** 판정에 필요한 최소 노출 수 (90d). 소규모 사용자에서 dead-code 방지 위해 3. */
+    surfacedMin: number;
+    /** 이 미만이면 저 ROI (acted/surfaced) */
+    rateMax: number;
+}
+export declare const DEFAULT_ROI_THRESHOLDS: RoiThresholds;
+export declare function roiDemotionsPath(home?: string): string;
+export declare function loadRoiDemotions(home?: string): RoiDemotions;
+export declare function saveRoiDemotions(demotions: RoiDemotions, home?: string): void;
+/**
+ * 90d 윈도 기준 재판정. 반환값이 새 저장 상태다.
+ *
+ *  - 신규 강등: surfaced ≥ min && rate < max → windowCount=1
+ *  - 유지: 이미 강등 && 여전히 저 ROI → windowCount+1 (2부터 격리)
+ *  - 해제: acted_on 이 저장 시점보다 증가 (사용자가 실제로 씀) 또는
+ *          rate 가 임계 이상으로 회복 → 엔트리 제거
+ *  - 유예: surfaced < min 인 솔루션은 판정하지 않음 (신규/저노출 보호)
+ */
+export declare function evaluateRoiDemotions(rows: HitRateRow[], prev: RoiDemotions, thresholds?: RoiThresholds, now?: () => string): RoiDemotions;
+/** 격리 여부 — 2회 연속 윈도 강등 유지 시 주입에서 제외 */
+export declare function isRoiQuarantined(entry: RoiDemotionEntry): boolean;
+export interface RoiAdjustable {
+    name: string;
+    relevance: number;
+}
+/**
+ * 강등 ×0.5, 격리는 제외. relevance 변경 후 내림차순 재정렬.
+ * fail-open: demotions 가 비면 원본 그대로.
+ *
+ * 실효 (리뷰에서 명시화): injector 의 MIN_INJECT_RELEVANCE 가 0.3 이므로
+ * relevance < 0.6 인 강등 솔루션은 사실상 주입 차단된다 — 강등은
+ * "중간 신뢰도엔 soft-block, 고신뢰도(≥0.6)엔 우선순위 하락"으로 동작하고,
+ * 격리는 relevance 무관 hard-block. 이 기울기는 의도된 것: δ 가 injection
+ * 품질에서 나오므로 저 ROI 주입엔 보수적으로 군다.
+ */
+export declare function applyRoiDemotions<T extends RoiAdjustable>(matches: T[], demotions: RoiDemotions): T[];
+/**
+ * observability 이벤트 → 판정 → 저장. fail-open.
+ * @returns 강등/격리 수 (로그용) 또는 null (판정 불가)
+ */
+export declare function updateRoiDemotions(home?: string): {
+    demoted: number;
+    quarantined: number;
+} | null;

package/dist/engine/roi-demotion.js

@@ -0,0 +1,159 @@
+/**
+ * Forgen v0.5.0 — Injection ROI 루프 (ADR-010 W3-1, F2)
+ *
+ * 근거: v0.4.11 실측에서 forgen 의 δ 는 100% injection 에서 나왔다 (blocks=0).
+ * 따라서 injection 품질 = 효과 그 자체다. "surfaced 는 많은데 acted_on 이
+ * 없는" 솔루션은 컨텍스트 비용만 내는 저 ROI 주입이므로 자동 강등한다.
+ * native 메모리(claude-mem 등)에는 없는 acted-on 피드백 루프 — moat 기능.
+ *
+ * 설계 (Rev 2 — 리뷰에서 기존 solution-quarantine 재사용 불가 확정):
+ *  - 전용 저장소 `~/.forgen/state/roi-demotions.json`
+ *    (기존 quarantine 은 frontmatter 파스 에러 기반 — 시맨틱 불일치)
+ *  - `ranking-pipeline.ts` 는 순수 유지 — 강등은 matchSolutions 결과 후처리
+ *  - 판정 갱신은 auto-compound 세션 종료 시 (updateRoiDemotions)
+ *  - 임계 (config.json roiDemotion 으로 조정 가능):
+ *      surfaced_90d >= 3 && acted/surfaced < 0.1  → 강등 (relevance ×0.5)
+ *      2회 연속 강등 유지                          → 격리 (주입 제외)
+ *      acted_on 신규 발생                          → 즉시 해제
+ */
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { queryHitRate } from '../core/observability-store.js';
+export const DEFAULT_ROI_THRESHOLDS = { surfacedMin: 3, rateMax: 0.1 };
+export function roiDemotionsPath(home = os.homedir()) {
+    return path.join(home, '.forgen', 'state', 'roi-demotions.json');
+}
+export function loadRoiDemotions(home = os.homedir()) {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(roiDemotionsPath(home), 'utf-8'));
+        return typeof parsed === 'object' && parsed !== null ? parsed : {};
+    }
+    catch {
+        return {};
+    }
+}
+export function saveRoiDemotions(demotions, home = os.homedir()) {
+    try {
+        const p = roiDemotionsPath(home);
+        fs.mkdirSync(path.dirname(p), { recursive: true });
+        // tmp+rename 원자 교체 — 동시 세션(auto-compound 병행 종료)에서 부분 쓰기로
+        // 파일이 깨지는 것을 방지. rename 은 동일 fs 내 원자적.
+        const tmp = `${p}.${process.pid}.tmp`;
+        fs.writeFileSync(tmp, `${JSON.stringify(demotions, null, 2)}\n`);
+        fs.renameSync(tmp, p);
+    }
+    catch { /* fail-open — 강등 실패가 주입을 막지 않는다 */ }
+}
+// ── 판정 (순수 함수 — 테스트 결정성) ──
+/**
+ * 90d 윈도 기준 재판정. 반환값이 새 저장 상태다.
+ *
+ *  - 신규 강등: surfaced ≥ min && rate < max → windowCount=1
+ *  - 유지: 이미 강등 && 여전히 저 ROI → windowCount+1 (2부터 격리)
+ *  - 해제: acted_on 이 저장 시점보다 증가 (사용자가 실제로 씀) 또는
+ *          rate 가 임계 이상으로 회복 → 엔트리 제거
+ *  - 유예: surfaced < min 인 솔루션은 판정하지 않음 (신규/저노출 보호)
+ */
+export function evaluateRoiDemotions(rows, prev, thresholds = DEFAULT_ROI_THRESHOLDS, now = () => new Date().toISOString()) {
+    const next = {};
+    for (const row of rows) {
+        const surfaced = row.surfaced_90d;
+        const acted = row.acted_90d;
+        const existing = prev[row.solutionId];
+        // 해제 1: 실제 사용 발생 (저장 시점 대비 acted 증가)
+        if (existing && acted > existing.actedOn)
+            continue;
+        if (surfaced < thresholds.surfacedMin) {
+            // 유예 — 단, 기존 강등 엔트리는 노출이 줄었어도 유지 (회복은 acted 로만)
+            if (existing)
+                next[row.solutionId] = existing;
+            continue;
+        }
+        const rate = acted / surfaced;
+        if (rate < thresholds.rateMax) {
+            // windowCount 증가는 최소 24h 간격 — 같은 날 다중 세션의 재평가는
+            // 동일 스냅샷 재확인일 뿐이므로 증가 없이 엔트리를 유지한다.
+            const nowIso = now();
+            const elapsed = existing
+                ? new Date(nowIso).getTime() - new Date(existing.lastEvaluatedAt).getTime()
+                : Number.POSITIVE_INFINITY;
+            const advanceWindow = elapsed >= 24 * 60 * 60 * 1000;
+            next[row.solutionId] = existing && !advanceWindow
+                ? existing // 24h 미만 — 그대로 유지 (카운트/스냅샷 불변)
+                : {
+                    solutionId: row.solutionId,
+                    reason: 'low-roi',
+                    demotedAt: existing?.demotedAt ?? nowIso,
+                    windowCount: (existing?.windowCount ?? 0) + 1,
+                    lastEvaluatedAt: nowIso,
+                    surfaced,
+                    actedOn: acted,
+                };
+        }
+        // 해제 2: rate 회복 → next 에 없음 = 제거
+    }
+    // rows 에 없는 기존 엔트리(이벤트가 180d 밖으로 age-out)는 함께 소멸 —
+    // 오래 안 쓰인 솔루션은 T4 time-decay 가 별도로 처리한다.
+    //
+    // 의도된 장주기 순환 (리뷰에서 명시화): 격리된 솔루션은 surfaced 이벤트가
+    // 더 이상 쌓이지 않아 ~6개월 뒤 rows 에서 사라지고 → 엔트리 소멸 → 주입
+    // 풀로 복귀한다. 영구 추방이 아니라 "재시도 기회"다 — 프로젝트 맥락이
+    // 바뀌면 같은 솔루션이 유효해질 수 있고, 여전히 안 쓰이면 다시 강등된다.
+    return next;
+}
+/** 격리 여부 — 2회 연속 윈도 강등 유지 시 주입에서 제외 */
+export function isRoiQuarantined(entry) {
+    return entry.windowCount >= 2;
+}
+/**
+ * 강등 ×0.5, 격리는 제외. relevance 변경 후 내림차순 재정렬.
+ * fail-open: demotions 가 비면 원본 그대로.
+ *
+ * 실효 (리뷰에서 명시화): injector 의 MIN_INJECT_RELEVANCE 가 0.3 이므로
+ * relevance < 0.6 인 강등 솔루션은 사실상 주입 차단된다 — 강등은
+ * "중간 신뢰도엔 soft-block, 고신뢰도(≥0.6)엔 우선순위 하락"으로 동작하고,
+ * 격리는 relevance 무관 hard-block. 이 기울기는 의도된 것: δ 가 injection
+ * 품질에서 나오므로 저 ROI 주입엔 보수적으로 군다.
+ */
+export function applyRoiDemotions(matches, demotions) {
+    if (Object.keys(demotions).length === 0)
+        return matches;
+    const adjusted = [];
+    for (const m of matches) {
+        const entry = demotions[m.name];
+        if (!entry) {
+            adjusted.push(m);
+            continue;
+        }
+        if (isRoiQuarantined(entry))
+            continue; // 격리 — 주입 제외
+        adjusted.push({ ...m, relevance: m.relevance * 0.5 });
+    }
+    adjusted.sort((a, b) => b.relevance - a.relevance);
+    return adjusted;
+}
+// ── 갱신 진입점 (auto-compound 세션 종료 시) ──
+/**
+ * observability 이벤트 → 판정 → 저장. fail-open.
+ * @returns 강등/격리 수 (로그용) 또는 null (판정 불가)
+ */
+export function updateRoiDemotions(home = os.homedir()) {
+    try {
+        // observability-store 는 sqlite 미지원/DB 부재 시 내부 fail-open ([] 반환)
+        const rows = queryHitRate();
+        if (rows.length === 0)
+            return { demoted: 0, quarantined: 0 };
+        const prev = loadRoiDemotions(home);
+        const next = evaluateRoiDemotions(rows, prev);
+        saveRoiDemotions(next, home);
+        const entries = Object.values(next);
+        return {
+            demoted: entries.filter(e => !isRoiQuarantined(e)).length,
+            quarantined: entries.filter(isRoiQuarantined).length,
+        };
+    }
+    catch {
+        return null;
+    }
+}

package/dist/engine/solution-format.d.ts

@@ -162,5 +162,6 @@ export declare function expandCompoundTags(tags: readonly string[]): string[];
  * two adjacent tokens). Only ASCII-letter pairs participate.
  */
 export declare function expandQueryBigrams(tags: readonly string[]): string[];
+export declare function expandQueryKoreanStems(tags: readonly string[]): string[];
 /** Migrate a V1-format solution file to V3 format */
 export declare function migrateV1toV3(content: string, filePath: string): string;

package/dist/engine/solution-format.js

@@ -590,6 +590,32 @@ export function expandQueryBigrams(tags) {
     }
     return [...out];
 }
+/**
+ * 한국어 활용형 어간 회복 (매칭 **쿼리 전용** — vec-probe 2026-07-20 실측 갭).
+ *
+ * `KO_SUFFIXES`(조사)와 term-matcher의 `KO_VERBAL_SUFFIXES`(`중`,`시`)는
+ * `검증해줘`·`최적화하자`·`배포하면` 같은 회화체 활용형에 도달하지 못한다 —
+ * 자연어 한국어 프롬프트에서 `검증` 계열 솔루션 태그가 영원히 매칭 불가.
+ * (match-eval-log 2,371행 기준 한국어 장형 토큰의 지배적 형태가 이 부류.)
+ *
+ * 규칙: `어간(≥2자) + (했|하|해|됐|되|돼) + 나머지` 형태에서 어간을 **추가**한다
+ * — 원본 토큰은 유지(치환 아님)라 오탐은 확장 노이즈에 그치고, ≥2자 어간
+ * 요구가 `이해`·`피해`·`유해물질`(하/해가 1번째 위치) 류 명사를 보호한다.
+ * 쿼리 사이드만 확장하므로 인덱스 재구축·ROUND3_BASELINE 재측정이 불필요
+ * (expandQueryBigrams와 같은 계약).
+ */
+const KO_CONJUGATION_RE = /^([가-힣]{2,}?)(했|하|해|됐|되|돼)[가-힣]*$/;
+export function expandQueryKoreanStems(tags) {
+    const out = new Set(tags);
+    for (const tag of tags) {
+        if (!/^[가-힣]+$/.test(tag))
+            continue;
+        const m = tag.match(KO_CONJUGATION_RE);
+        if (m)
+            out.add(m[1]);
+    }
+    return [...out];
+}
 // ── Migration ──
 const V1_TYPE_MAP = {
     solution: 'pattern',

package/dist/engine/solution-matcher.js

@@ -19,6 +19,7 @@ import { getOrBuildIndex } from './solution-index.js';
 import { defaultNormalizer } from './term-normalizer.js';
 import { rankCandidates } from './ranking-pipeline.js';
 import { loadTunedMatcherWeights } from './meta-learning/matcher-weight-loader.js';
+import { applyRoiDemotions, loadRoiDemotions } from './roi-demotion.js';
 // ── Re-exports (backward compatibility) ──
 export { bigramSimilarity, bm25Score, COMMON_TAGS, tagWeight } from './scoring-algorithms.js';
 export { calculateRelevance } from './relevance-scorer.js';
@@ -54,7 +55,9 @@ export function matchSolutions(prompt, scope, cwd) {
     const promptLower = prompt.toLowerCase();
     const tunedWeights = loadTunedMatcherWeights();
     const ranked = rankCandidates(promptTags, promptLower, allSolutions, tunedWeights);
-    return ranked.map((c) => ({
+    // ADR-010 W3-1 (F2): 저 ROI 강등 — ranking-pipeline 은 순수 유지, 여기서
+    // 후처리. surfaced≫acted_on 솔루션은 ×0.5, 2윈도 연속이면 주입 제외.
+    const matches = ranked.map((c) => ({
         name: c.solution.name,
         path: c.solution.filePath,
         scope: c.solution.scope,
@@ -68,4 +71,10 @@ export function matchSolutions(prompt, scope, cwd) {
         matchedTags: [...c.matchedTags, ...c.matchedIdentifiers],
         matchedIdentifiers: c.matchedIdentifiers,
     }));
+    try {
+        return applyRoiDemotions(matches, loadRoiDemotions());
+    }
+    catch {
+        return matches; // fail-open — 강등 실패가 주입을 막지 않는다
+    }
 }

package/dist/fgx.js

@@ -14,12 +14,13 @@ const args = process.argv.slice(2);
 // v0.4.10: forgen 서브커맨드 인벤토리. src/cli.ts 의 commands[] 와 sync 유지.
 // 첫 비-플래그 인자가 이 집합에 들어가면 forgen cli 로 라우팅.
 const FORGEN_SUBCOMMANDS = new Set([
-    'forge', 'compound', 'skill', 'dashboard', 'learn', 'me', 'statusline',
-    'config', 'mcp', 'init', 'install', 'status', 'maintenance', 'parity',
-    'notepad', 'inspect', 'onboarding', 'doctor', 'uninstall', 'rule',
+    // Wave 1 통합(feature-audit 2026-07-21): status(←stats/health/dashboard/me/
+    // recall/explain/last-block/watch), dev(←probe-workflow/parity/migrate/regress-map).
+    'forge', 'compound', 'skill', 'status', 'learn', 'statusline',
+    'config', 'mcp', 'init', 'install', 'maintenance', 'dev',
+    'notepad', 'inspect', 'doctor', 'uninstall', 'rule',
     'classify-enforce', 'rule-meta-scan', 'lifecycle-scan',
-    'stats', 'last-block', 'recall', 'migrate', 'suppress-rule', 'activate-rule',
-    'regress-map', 'watch', 'health', 'probe-workflow', 'workflows', 'explain', 'changelog',
+    'suppress-rule', 'activate-rule', 'workflows', 'changelog',
     // 메타 명령도 cli.ts 가 처리 (fgx claude spawn 으로는 의미 없음)
     'help', '--help', '-h', '--version', '-V',
 ]);
@@ -61,7 +62,7 @@ async function runClaudeLauncher() {
     if (firstRun) {
         console.log('\n  Forgen — Setting up for the first time.\n');
         console.log('  Creating ~/.forgen/ directory and default philosophy.');
-        console.log('  Run `forgen onboarding` afterwards to complete personalization.\n');
+        console.log('  Run `forgen forge --onboarding` afterwards to complete personalization.\n');
     }
     const context = await prepareHarness(process.cwd(), { runtime });
     if (firstRun) {
@@ -80,10 +81,22 @@ async function runClaudeLauncher() {
 async function main() {
     const sub = findFirstSubcommand(args);
     if (sub !== null) {
+        // cli.js 위임 경로는 건드리지 않는다. watch/dashboard/workflows 등 long-running
+        // 서브커맨드가 여기서 강제 종료되면 잘린다. cli.js 가 자체 process.exit 를 책임진다.
         await routeToCli();
         return;
     }
     await runClaudeLauncher();
+    // 대화형 세션 종료 후 fgx 프로세스 종료를 명시적으로 보장한다.
+    //
+    // WHY: spawnClaude 는 세션 종료 시 auto-compound-runner 를 detached + unref 로 띄우고
+    // 즉시 resolve 한다(설계상 비차단). 그런데 fgx 는 성공 경로에서 process.exit 를 호출하지
+    // 않고 Node 이벤트 루프 자연 배수에 의존해 왔다. 지금은 미해제 핸들이 없어 정상 종료하지만,
+    // 향후 post-session 경로에 닫히지 않은 핸들(SQLite 커넥션, 타이머, 소켓 등)이 하나라도
+    // 생기면 fgx 가 종료하지 못하고 셸 프롬프트가 돌아오지 않는다(= 터미널 물림). 명시 종료로
+    // 이 종류의 회귀를 원천 차단한다. detached 자식은 unref 되어 독립 실행되므로 백그라운드
+    // compound 는 영향받지 않고 계속된다.
+    process.exit(0);
 }
 main().catch((err) => {
     console.error('[forgen] Error:', err instanceof Error ? err.message : err);

package/dist/forge/cli.js

@@ -12,6 +12,12 @@ import { loadProfile, profileExists } from '../store/profile-store.js';
 import { renderProfile } from '../renderer/inspect-renderer.js';
 import { runOnboarding } from './onboarding-cli.js';
 export async function handleForge(args) {
+    // W1-4 (feature-audit 2026-07-21): forge 를 개인화 단일 관문으로.
+    // --onboarding 은 프로필 유무와 무관하게 4질문 온보딩을 재실행 (구 `forgen onboarding`).
+    if (args.includes('--onboarding')) {
+        await runOnboarding();
+        return;
+    }
     if (args.includes('--profile')) {
         handleShowProfile();
         return;
@@ -36,7 +42,7 @@ export async function handleForge(args) {
 function handleShowProfile() {
     const profile = loadProfile();
     if (!profile) {
-        console.log('\n  No v1 profile found. Run `forgen forge` or `forgen onboarding`.\n');
+        console.log('\n  No v1 profile found. Run `forgen forge` (or `forgen forge --onboarding` to re-run).\n');
         return;
     }
     console.log(`\n${renderProfile(profile)}\n`);
@@ -95,6 +101,6 @@ async function handleReset(level) {
         await runOnboarding();
     }
     else {
-        console.log('  forgen forge 또는 forgen onboarding 으로 새 프로필을 생성하세요.\n');
+        console.log('  forgen forge (또는 forgen forge --onboarding) 으로 새 프로필을 생성하세요.\n');
     }
 }

package/dist/hooks/compound-reflection.js

@@ -10,6 +10,7 @@
  * 별도 모듈로 분리. 이유: (1) 테스트 가능성 (순수 함수), (2) false
  * positive 문제(action-plan §2.1)의 근본 수정에 명확한 책임 경계 필요.
  */
+import { stripPrivate } from '../engine/private-filter.js';
 /** 주입 후 이 시간 내에 코드에 식별자가 출현해야 reflection으로 인정 */
 export const REFLECTION_WINDOW_MS = 15 * 60 * 1000; // 15분
 /**
@@ -52,8 +53,12 @@ export const COMMON_IDENTIFIERS = new Set([
  *   4. 매칭 비율 (유효 식별자의 50% 이상, 최소 1개)
  */
 export function isReflectionCandidate(input) {
-    const { identifiers, code, injectedAt } = input;
+    const { identifiers, injectedAt } = input;
     const now = input.now ?? new Date();
+    // W2-5 (private 태그): 사용자가 <private> 로 표시한 코드 범위는 reflection 관측에서
+    // 제외한다. private 범위 안의 식별자 출현을 "솔루션이 반영됐다"는 신호로 세면
+    // 사용자가 학습 제외를 의도한 코드를 관측하는 셈이 되므로, 매칭 전에 스트립한다.
+    const code = stripPrivate(input.code ?? '').cleaned;
     // Gate 1: 코드 최소 길이
     if (!code || code.length < 10) {
         return { reflected: false, matchedCount: 0, eligibleCount: 0, reason: 'code-too-short' };