@wooojin/forgen 0.4.0 → 0.4.1

package/dist/hooks/post-tool-use.js

@@ -20,6 +20,8 @@ import { approve, approveWithWarning, failOpenWithTracking } from './shared/hook
 import { STATE_DIR } from '../core/paths.js';
 import { recordHookTiming } from './shared/hook-timing.js';
 import { createDriftState, evaluateDrift } from '../core/drift-score.js';
+import { appendImplicitFeedback } from '../store/implicit-feedback-store.js';
+const RECENT_TOOL_NAMES_WINDOW = 20;
 /** Lightweight hash for content comparison (not cryptographic) */
 function simpleHash(content) {
     let hash = 0;
@@ -30,15 +32,6 @@ function simpleHash(content) {
     }
     return hash.toString(36);
 }
-const IMPLICIT_FEEDBACK_LOG = path.join(STATE_DIR, 'implicit-feedback.jsonl');
-/** Record implicit feedback signal to JSONL */
-function recordImplicitFeedback(entry) {
-    try {
-        fs.mkdirSync(STATE_DIR, { recursive: true });
-        fs.appendFileSync(IMPLICIT_FEEDBACK_LOG, JSON.stringify(entry) + '\n');
-    }
-    catch { /* fail-open: implicit feedback recording must not throw */ }
-}
 // ── State management ──
 function getModifiedFilesPath(sessionId) {
     return path.join(STATE_DIR, `modified-files-${sanitizeId(sessionId)}.json`);
@@ -125,6 +118,15 @@ async function main() {
         const sessionId = data.session_id ?? 'default';
         const modState = loadModifiedFiles(sessionId);
         modState.toolCallCount = (modState.toolCallCount ?? 0) + 1;
+        // TEST-2: recent tool name window — stop-guard 의 self-score inflation 가드가
+        // "최근 세션에서 측정 도구 몇 번 불렸나?" 를 이 배열로 계산한다.
+        if (toolName) {
+            const names = modState.recentToolNames ?? [];
+            names.push(toolName);
+            if (names.length > RECENT_TOOL_NAMES_WINDOW)
+                names.splice(0, names.length - RECENT_TOOL_NAMES_WINDOW);
+            modState.recentToolNames = names;
+        }
         const messages = [];
         let revertDetected = false;
         // 1. Checkpoint (every 5 calls)
@@ -152,8 +154,9 @@ async function main() {
                     // Implicit feedback: repeated edit detection (5+ edits on same file)
                     if (count >= 5) {
                         messages.push(`<compound-tool-warning>\n[Forgen] ⚠ ${path.basename(filePath)} has been modified ${count} times.\nConsider redesigning the overall structure and restarting.\n</compound-tool-warning>`);
-                        recordImplicitFeedback({
+                        appendImplicitFeedback({
                             type: 'repeated_edit',
+                            category: 'edit',
                             file: filePath,
                             editCount: count,
                             at: new Date().toISOString(),
@@ -172,8 +175,9 @@ async function main() {
                         // Skip the most recent hash (which would be the write being "reverted from")
                         if (prevHashes.length >= 2 && prevHashes.slice(0, -1).includes(hash)) {
                             revertDetected = true;
-                            recordImplicitFeedback({
+                            appendImplicitFeedback({
                                 type: 'revert_detected',
+                                category: 'revert',
                                 file: filePath,
                                 at: new Date().toISOString(),
                                 sessionId,
@@ -198,8 +202,9 @@ async function main() {
             const driftResult = evaluateDrift(modState.drift, true, revertDetected);
             if (driftResult.message) {
                 messages.push(`<compound-tool-warning>\n${driftResult.message}\n</compound-tool-warning>`);
-                recordImplicitFeedback({
+                appendImplicitFeedback({
                     type: driftResult.level === 'critical' || driftResult.level === 'hardcap' ? 'drift_critical' : 'drift_warning',
+                    category: 'drift',
                     score: driftResult.score,
                     totalEdits: modState.drift.totalEdits,
                     totalReverts: modState.drift.totalReverts,
@@ -213,8 +218,9 @@ async function main() {
             const agentResult = validateAgentOutput(toolResponse);
             if (agentResult) {
                 messages.push(`<compound-agent-validation>\n[Forgen] ${agentResult.severity === 'error' ? '⛔' : '⚠'} ${agentResult.message}\n</compound-agent-validation>`);
-                recordImplicitFeedback({
+                appendImplicitFeedback({
                     type: `agent_${agentResult.signal}`,
+                    category: 'agent',
                     severity: agentResult.severity,
                     outputLength: toolResponse.trim().length,
                     at: new Date().toISOString(),
@@ -254,14 +260,18 @@ async function main() {
             })() || toolResponse;
             if (target) {
                 try {
-                    const [{ loadActiveRules }, { recordViolation, recordBypass }, { scanForBypass }, { compileSafeRegex, safeRegexTest },] = await Promise.all([
+                    const [{ loadActiveRules }, { recordViolation, recordBypass }, { scanForBypass }, { compileSafeRegex, safeRegexTest }, { preprocessForMatch },] = await Promise.all([
                         import('../store/rule-store.js'),
                         import('../engine/lifecycle/signals.js'),
                         import('../engine/lifecycle/bypass-detector.js'),
                         import('./shared/safe-regex.js'),
+                        import('./shared/command-parser.js'),
                     ]);
                     const rules = loadActiveRules();
-                    // Mech-A pattern_match dispatcher
+                    // Mech-A pattern_match dispatcher — match_target 은 **rule-per-rule**.
+                    // AWS key / DROP 류 secret/dangerous SQL 은 파일 content 에 들어있어도
+                    // 실제 leak 이라 raw 검사가 맞고, rm -rf 류 shell 명령은 quote 안 본문이면
+                    // false-positive 이므로 masked 가 맞다. pre-tool-use 와 동일한 spec 기반 분기.
                     for (const rule of rules) {
                         for (const spec of rule.enforce_via ?? []) {
                             if (spec.hook !== 'PostToolUse' || spec.mech !== 'A')
@@ -277,7 +287,9 @@ async function main() {
                                 log.debug(`rule ${rule.rule_id} unsafe regex: ${re.reason}`);
                                 continue;
                             }
-                            if (!safeRegexTest(re.regex, target))
+                            const matchTarget = (v.params?.match_target ?? 'raw');
+                            const mechTarget = preprocessForMatch(target, matchTarget);
+                            if (!safeRegexTest(re.regex, mechTarget))
                                 continue;
                             recordViolation({
                                 rule_id: rule.rule_id, session_id: sessionId,
@@ -288,8 +300,14 @@ async function main() {
                             messages.push(`<compound-rule-violation>\n[Forgen] Rule ${rule.rule_id.slice(0, 8)} pattern matched in ${toolName} output.\n${spec.block_message ?? rule.policy.slice(0, 120)}\n</compound-rule-violation>`);
                         }
                     }
-                    // T3 bypass detection (same rules, same target)
-                    const candidates = scanForBypass({ rules, tool_name: toolName, tool_output: target, session_id: sessionId });
+                    // T3 bypass detection — scanForBypass 는 rule.policy 자연어에서 패턴 추출이라
+                    // match_target 개념 없음. Write/Edit 는 파일 본문이라 bypass-detector 의
+                    // 자연어 휴리스틱이 false-positive 과다 (L1-no-rm-rf-unconfirmed bypass 20건
+                    // 중 Write/Edit 15건이 실측). 이 경로만 masked. Bash 는 실제 실행된 명령이라
+                    // raw 유지. Mech-A pattern_match 는 위에서 rule-per-rule 로 이미 처리.
+                    const isFileContentTool = toolName === 'Write' || toolName === 'Edit';
+                    const bypassTarget = isFileContentTool ? preprocessForMatch(target, 'masked') : target;
+                    const candidates = scanForBypass({ rules, tool_name: toolName, tool_output: bypassTarget, session_id: sessionId });
                     for (const c of candidates) {
                         recordBypass({ rule_id: c.rule_id, session_id: c.session_id, tool: c.tool, pattern_preview: c.pattern_preview });
                     }
@@ -322,5 +340,5 @@ async function main() {
 }
 main().catch((e) => {
     process.stderr.write(`[ch-hook] ${e instanceof Error ? e.message : String(e)}\n`);
-    console.log(failOpenWithTracking('post-tool-use'));
+    console.log(failOpenWithTracking('post-tool-use', e));
 });

package/dist/hooks/pre-compact.js

@@ -271,5 +271,5 @@ Rules:
 }
 main().catch((e) => {
     process.stderr.write(`[ch-hook] ${e instanceof Error ? e.message : String(e)}\n`);
-    console.log(failOpenWithTracking('pre-compact'));
+    console.log(failOpenWithTracking('pre-compact', e));
 });

package/dist/hooks/pre-tool-use.d.ts

@@ -10,6 +10,13 @@ interface DangerousPatternEntry {
     pattern: RegExp;
     description: string;
     severity: 'block' | 'warn';
+    /**
+     * match_target (v0.4.1): 'masked' (default) — quote/heredoc 본문 제거 후 매칭.
+     *   실 shell 실행 토큰 검사에 적합. 'raw' — 원본 command 그대로 매칭.
+     *   `python -c "..."`, `eval "..."` 처럼 **quote 안 본문이 실제 payload 로 실행**
+     *   되는 패턴에 사용.
+     */
+    matchTarget?: 'raw' | 'masked';
 }
 /** 위험 Bash 명령어 패턴 (패키지 내장 + 사용자 커스텀 병합) */
 export declare const DANGEROUS_PATTERNS: DangerousPatternEntry[];

package/dist/hooks/pre-tool-use.js

@@ -22,6 +22,7 @@ import { isHookEnabled } from './hook-config.js';
 import { approve, approveWithWarning, deny, failOpenWithTracking } from './shared/hook-response.js';
 import { FORGEN_HOME, STATE_DIR } from '../core/paths.js';
 import { recordHookTiming } from './shared/hook-timing.js';
+import { maskQuotedContent } from './shared/command-parser.js';
 const FAIL_COUNTER_PATH = path.join(STATE_DIR, 'pre-tool-fail-counter.json');
 const FAIL_CLOSE_THRESHOLD = 3; // 연속 3회 파싱 실패 시에만 reject
 /** RegExp 안전성 검증 (ReDoS 방지) — 매칭/비매칭 양쪽 모두 테스트 */
@@ -59,12 +60,16 @@ function loadDangerousPatterns() {
                 pattern: new RegExp(entry.pattern, entry.flags ?? ''),
                 description: entry.description,
                 severity: entry.severity,
+                matchTarget: entry.match_target === 'raw' ? 'raw' : 'masked',
             });
         }
     }
     catch {
         // JSON 로드 실패 시 하드코딩 폴백 (최소 안전장치)
-        results.push({ pattern: /rm\s+(-rf|-fr)\s+[/~]/, description: 'rm -rf on root/home path', severity: 'block' }, { pattern: /curl\s+.*\|\s*(ba)?sh/, description: 'curl pipe to shell', severity: 'block' }, { pattern: /:\(\)\s*\{\s*:\|:&\s*\}\s*;:/, description: 'fork bomb', severity: 'block' });
+        results.push(
+        // v0.4.1 false-positive fix: /tmp, /var/folders, /var/tmp 같은 임시 경로는
+        // 일반 개발에서 매일 정리 대상. 위험한 시스템 경로만 blacklist.
+        { pattern: /rm\s+(-rf|-fr)\s+(\/(?!tmp\b|var\/folders\b|var\/tmp\b)|~)/, description: 'rm -rf on root/home path', severity: 'block' }, { pattern: /curl\s+.*\|\s*(ba)?sh/, description: 'curl pipe to shell', severity: 'block' }, { pattern: /:\(\)\s*\{\s*:\|:&\s*\}\s*;:/, description: 'fork bomb', severity: 'block' });
     }
     // 2. 사용자 커스텀 패턴 (~/.compound/dangerous-patterns.json)
     try {
@@ -100,8 +105,14 @@ export function checkDangerousCommand(toolName, toolInput) {
     const command = typeof toolInput === 'string'
         ? toolInput
         : (toolInput.command ?? '');
-    for (const { pattern, description, severity } of DANGEROUS_PATTERNS) {
-        if (pattern.test(command)) {
+    // v0.4.1 (2026-04-24) quote-aware built-in scan:
+    // 기본은 masked (quote/heredoc 본문 제거) — shell 실행 토큰 검사. 하지만
+    // `python -c "..."` / `eval "..."` 처럼 quote 안 본문이 실 payload 로 실행되는
+    // 패턴은 match_target:raw 로 지정해 원본 command 전체 검사.
+    const maskedCommand = maskQuotedContent(command);
+    for (const { pattern, description, severity, matchTarget } of DANGEROUS_PATTERNS) {
+        const target = matchTarget === 'raw' ? command : maskedCommand;
+        if (pattern.test(target)) {
             return { action: severity, description, command: command.slice(0, 100) };
         }
     }
@@ -315,10 +326,11 @@ async function main() {
         // 이렇게 해야 rule.block_message (맥락 있는 안내) 가 제네릭 "Dangerous command blocked" 대신 노출됨.
         // fail-open: 예외는 hook 차단 안 함.
         try {
-            const [{ loadActiveRules }, { recordViolation }, { compileSafeRegex, safeRegexTest },] = await Promise.all([
+            const [{ loadActiveRules }, { recordViolation }, { compileSafeRegex, safeRegexTest }, { preprocessForMatch },] = await Promise.all([
                 import('../store/rule-store.js'),
                 import('../engine/lifecycle/signals.js'),
                 import('./shared/safe-regex.js'),
+                import('./shared/command-parser.js'),
             ]);
             const rules = loadActiveRules();
             const command = typeof toolInput.command === 'string'
@@ -339,7 +351,13 @@ async function main() {
                         log.debug(`rule ${rule.rule_id} unsafe regex: ${re.reason}`);
                         continue;
                     }
-                    if (!safeRegexTest(re.regex, command))
+                    // TEST-6 / RC5: quote-aware preprocessing. Default 'raw' = backward compat.
+                    // Rules that target real command invocations should set match_target: 'masked'
+                    // so quoted argument text (e.g. body of `forgen compound --solution "..."`)
+                    // doesn't trigger false positive blocks.
+                    const matchTarget = (v.params?.match_target ?? 'raw');
+                    const target = preprocessForMatch(command, matchTarget);
+                    if (!safeRegexTest(re.regex, target))
                         continue;
                     const requiresFlag = v.params?.requires_flag;
                     const confirmed = process.env.FORGEN_USER_CONFIRMED === '1';
@@ -413,5 +431,5 @@ main().catch((e) => {
     });
     process.stderr.write(`[ch-hook] ${hookErr.name}: ${hookErr.message}\n`);
     // fail-open: approve on internal error to avoid blocking all tool calls
-    console.log(failOpenWithTracking('pre-tool-use'));
+    console.log(failOpenWithTracking('pre-tool-use', e));
 });

package/dist/hooks/rate-limiter.js

@@ -82,5 +82,5 @@ async function main() {
 }
 main().catch((e) => {
     process.stderr.write(`[ch-hook] ${e instanceof Error ? e.message : String(e)}\n`);
-    console.log(failOpenWithTracking('rate-limiter'));
+    console.log(failOpenWithTracking('rate-limiter', e));
 });

package/dist/hooks/secret-filter.js

@@ -87,5 +87,5 @@ main().catch((e) => {
         hookName: 'secret-filter', eventType: 'PostToolUse', cause: e,
     });
     process.stderr.write(`[ch-hook] ${hookErr.name}: ${hookErr.message}\n`);
-    console.log(failOpenWithTracking('secret-filter'));
+    console.log(failOpenWithTracking('secret-filter', e));
 });

package/dist/hooks/session-recovery.js

@@ -429,6 +429,6 @@ async function main() {
 if (process.argv[1] && fs.realpathSync(path.resolve(process.argv[1])) === fileURLToPath(import.meta.url)) {
     main().catch((e) => {
         process.stderr.write(`[ch-hook] ${e instanceof Error ? e.message : String(e)}\n`);
-        console.log(failOpenWithTracking('session-recovery'));
+        console.log(failOpenWithTracking('session-recovery', e));
     });
 }

package/dist/hooks/shared/command-parser.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Command-token parser — quote-aware shell command preprocessing.
+ *
+ * 목적: PreToolUse enforce_via 룰의 정규식이 quote된 인자 텍스트와
+ * 명령 토큰을 구분 못 해서 false positive block 발생 (TEST-6, RC5).
+ *
+ * 사례: forgen compound --solution "title" "본문에 rm -rf 텍스트 포함" 명령이
+ * "rm\s+-rf" 패턴에 매칭되어 차단됨. 실제 rm 명령이 아닌데도.
+ *
+ * 해법: quote된 문자열을 마스킹한 뒤 패턴 매칭. 99% 케이스 커버.
+ * 완벽한 shell 파싱은 아니지만 정직하게 한정된 범위.
+ */
+/**
+ * Mask quoted string contents in a shell command so that text inside
+ * single/double quotes, backticks, or $(...) is not matched by patterns
+ * intended for command tokens.
+ *
+ * Examples:
+ *   maskQuotedContent('rm -rf /')                                → 'rm -rf /'
+ *   maskQuotedContent('echo "rm -rf foo"')                       → 'echo ""'
+ *   maskQuotedContent("forgen save 'rm -rf body'")               → "forgen save ''"
+ *   maskQuotedContent('rm -rf $(pwd)')                           → 'rm -rf $()'
+ *   maskQuotedContent('echo `rm -rf x`')                         → 'echo ``'
+ *
+ * Limitations (documented, not silently broken):
+ *   - escaped quotes inside quoted strings: best-effort only
+ *   - heredoc bodies (<<EOF ... EOF): masked as `<<HEREDOC>>` (v0.4.1+)
+ *   - nested $(...) / `...`: outer level masked
+ */
+export declare function maskQuotedContent(cmd: string): string;
+/**
+ * Decide if a verifier should match against the raw command, masked command,
+ * or the leading command tokens of each statement.
+ *
+ * 'raw'             — backward compat. Match against the unmodified command string.
+ * 'masked'          — Strip quoted contents first. Use this when the rule wants to
+ *                     guard a real command invocation (e.g. rm -rf) and not text
+ *                     inside string literals passed as arguments to other commands.
+ * 'command_tokens'  — Reserved for future use (per-statement leading-token check).
+ *                     Currently behaves like 'masked' to avoid silently breaking
+ *                     when rule files use it.
+ */
+export type MatchTarget = 'raw' | 'masked' | 'command_tokens';
+export declare function preprocessForMatch(cmd: string, target: MatchTarget | undefined): string;

package/dist/hooks/shared/command-parser.js

@@ -0,0 +1,50 @@
+/**
+ * Command-token parser — quote-aware shell command preprocessing.
+ *
+ * 목적: PreToolUse enforce_via 룰의 정규식이 quote된 인자 텍스트와
+ * 명령 토큰을 구분 못 해서 false positive block 발생 (TEST-6, RC5).
+ *
+ * 사례: forgen compound --solution "title" "본문에 rm -rf 텍스트 포함" 명령이
+ * "rm\s+-rf" 패턴에 매칭되어 차단됨. 실제 rm 명령이 아닌데도.
+ *
+ * 해법: quote된 문자열을 마스킹한 뒤 패턴 매칭. 99% 케이스 커버.
+ * 완벽한 shell 파싱은 아니지만 정직하게 한정된 범위.
+ */
+/**
+ * Mask quoted string contents in a shell command so that text inside
+ * single/double quotes, backticks, or $(...) is not matched by patterns
+ * intended for command tokens.
+ *
+ * Examples:
+ *   maskQuotedContent('rm -rf /')                                → 'rm -rf /'
+ *   maskQuotedContent('echo "rm -rf foo"')                       → 'echo ""'
+ *   maskQuotedContent("forgen save 'rm -rf body'")               → "forgen save ''"
+ *   maskQuotedContent('rm -rf $(pwd)')                           → 'rm -rf $()'
+ *   maskQuotedContent('echo `rm -rf x`')                         → 'echo ``'
+ *
+ * Limitations (documented, not silently broken):
+ *   - escaped quotes inside quoted strings: best-effort only
+ *   - heredoc bodies (<<EOF ... EOF): masked as `<<HEREDOC>>` (v0.4.1+)
+ *   - nested $(...) / `...`: outer level masked
+ */
+export function maskQuotedContent(cmd) {
+    if (!cmd)
+        return cmd;
+    let out = cmd;
+    // v0.4.1 (2026-04-24) — heredoc body 마스킹 추가. 이전엔 `cat > f <<EOF\n rm -rf /tmp \nEOF`
+    // 처럼 heredoc 본문이 command string 에 포함돼 false-positive block 발생.
+    // 지원 형식: <<EOF / <<'EOF' / <<"EOF" / <<-EOF (indent 무시 변종).
+    // <<-MARK 은 indent 허용 (terminator 앞 whitespace). `\n\s*\2` 로 반영.
+    out = out.replace(/<<-?\s*(['"]?)([A-Za-z_][A-Za-z0-9_]*)\1[\s\S]*?\n\s*\2\b/g, '<<HEREDOC>>');
+    // Order matters: command substitution before plain quotes (they may contain quotes themselves).
+    out = out.replace(/\$\([^)]*\)/g, '$()');
+    out = out.replace(/`[^`]*`/g, '``');
+    out = out.replace(/'[^']*'/g, "''");
+    out = out.replace(/"[^"]*"/g, '""');
+    return out;
+}
+export function preprocessForMatch(cmd, target) {
+    if (!target || target === 'raw')
+        return cmd;
+    return maskQuotedContent(cmd);
+}

package/dist/hooks/shared/hook-response.d.ts

@@ -18,8 +18,13 @@ export declare function approve(): string;
 /**
  * 통과 + 모델에 컨텍스트 주입.
  * UserPromptSubmit, SessionStart 이벤트에서만 모델에 도달함.
+ *
+ * H1 (v0.4.1): optional `userNotice` 로 사용자 UI (systemMessage) 에도 동시
+ * 1줄 노출. additionalContext 는 모델 전용이라 기존 recall hit 이 8,000+ 번
+ * 주입되었는데도 사용자는 0 건을 봤음. userNotice 로 같은 hit 을 사용자
+ * 에게 가시화한다.
  */
-export declare function approveWithContext(context: string, eventName: string): string;
+export declare function approveWithContext(context: string, eventName: string, userNotice?: string): string;
 /**
  * 통과 + UI 경고 표시 (모델에는 전달되지 않음).
  * PostToolUse, PreToolUse 경고 등 모델 도달이 불필요한 경우 사용.
@@ -44,6 +49,11 @@ export declare function blockStop(reason: string, systemMessage?: string): strin
  * fail-open with error tracking: 에러 시 안전하게 통과하되, 실패 정보를 기록.
  * forgen doctor의 Hook Health 섹션에서 실패 이력을 표시할 수 있도록 JSONL 로그에 기록.
  *
+ * v0.4.1 (2026-04-24): optional `err` 매개변수 추가. 실 데이터상 106건의 hook 에러가
+ * 누적됐으나 전부 `{hook,at}` 만이라 근원 조사 불가했다. 이제 `error`/`stack` 을
+ * 함께 기록해 `forgen doctor` 가 원인 카테고리별로 빈도 surface 가능.
+ * payload 는 한 줄 cap(400자)로 잘라 JSONL 크기 폭주 방지.
+ *
  * @fail-open: hook failure must never block the user's workflow
  */
-export declare function failOpenWithTracking(hookName: string): string;
+export declare function failOpenWithTracking(hookName: string, err?: unknown): string;

package/dist/hooks/shared/hook-response.js

@@ -23,11 +23,17 @@ export function approve() {
 /**
  * 통과 + 모델에 컨텍스트 주입.
  * UserPromptSubmit, SessionStart 이벤트에서만 모델에 도달함.
+ *
+ * H1 (v0.4.1): optional `userNotice` 로 사용자 UI (systemMessage) 에도 동시
+ * 1줄 노출. additionalContext 는 모델 전용이라 기존 recall hit 이 8,000+ 번
+ * 주입되었는데도 사용자는 0 건을 봤음. userNotice 로 같은 hit 을 사용자
+ * 에게 가시화한다.
  */
-export function approveWithContext(context, eventName) {
+export function approveWithContext(context, eventName, userNotice) {
     return JSON.stringify({
         continue: true,
         hookSpecificOutput: { hookEventName: eventName, additionalContext: context },
+        ...(userNotice ? { systemMessage: userNotice } : {}),
     });
 }
 /**
@@ -81,13 +87,34 @@ export function blockStop(reason, systemMessage) {
  * fail-open with error tracking: 에러 시 안전하게 통과하되, 실패 정보를 기록.
  * forgen doctor의 Hook Health 섹션에서 실패 이력을 표시할 수 있도록 JSONL 로그에 기록.
  *
+ * v0.4.1 (2026-04-24): optional `err` 매개변수 추가. 실 데이터상 106건의 hook 에러가
+ * 누적됐으나 전부 `{hook,at}` 만이라 근원 조사 불가했다. 이제 `error`/`stack` 을
+ * 함께 기록해 `forgen doctor` 가 원인 카테고리별로 빈도 surface 가능.
+ * payload 는 한 줄 cap(400자)로 잘라 JSONL 크기 폭주 방지.
+ *
  * @fail-open: hook failure must never block the user's workflow
  */
-export function failOpenWithTracking(hookName) {
+export function failOpenWithTracking(hookName, err) {
     try {
         fs.mkdirSync(STATE_DIR, { recursive: true });
         const logPath = path.join(STATE_DIR, 'hook-errors.jsonl');
-        const entry = JSON.stringify({ hook: hookName, at: Date.now() });
+        const payload = { hook: hookName, at: Date.now() };
+        if (err !== undefined && err !== null) {
+            if (err instanceof Error) {
+                payload.error = err.message.slice(0, 400);
+                if (err.stack) {
+                    // 스택 첫 3줄만 — 어느 파일/라인에서 throw 됐는지만 알면 충분.
+                    payload.stack = err.stack.split('\n').slice(0, 3).join(' | ').slice(0, 400);
+                }
+                const maybeCode = err.code;
+                if (typeof maybeCode === 'string')
+                    payload.code = maybeCode;
+            }
+            else {
+                payload.error = String(err).slice(0, 400);
+            }
+        }
+        const entry = JSON.stringify(payload);
         fs.appendFileSync(logPath, entry + '\n');
     }
     catch { /* fail-open: tracking itself must not throw */ }

package/dist/hooks/skill-injector.js

@@ -312,5 +312,5 @@ async function main() {
 }
 main().catch((e) => {
     process.stderr.write(`[ch-hook] ${e instanceof Error ? e.message : String(e)}\n`);
-    console.log(failOpenWithTracking('skill-injector'));
+    console.log(failOpenWithTracking('skill-injector', e));
 });

package/dist/hooks/slop-detector.js

@@ -84,10 +84,10 @@ async function main() {
     }
     catch (e) {
         log.debug('슬롭 감지 실패', e);
-        console.log(failOpenWithTracking('slop-detector'));
+        console.log(failOpenWithTracking('slop-detector', e));
     }
 }
 main().catch((e) => {
     process.stderr.write(`[ch-hook] ${e instanceof Error ? e.message : String(e)}\n`);
-    console.log(failOpenWithTracking('slop-detector'));
+    console.log(failOpenWithTracking('slop-detector', e));
 });

package/dist/hooks/solution-injector.d.ts

@@ -28,6 +28,15 @@
  */
 export declare const MIN_INJECT_RELEVANCE = 0.3;
 export declare const MIN_INJECT_RELEVANCE_TRUSTED = 0.25;
+/**
+ * v0.4.1 — cold-start 사용자 threshold. outcomes 이벤트가 거의 없는 신규 사용자
+ * 는 starter-pack 이 champion/active 로 승격될 기회가 없어 0.3 gate 에 막혀 주입 0.
+ * 실측 (buyer-day1 v2): starter 15개 중 recall 5건 전부 relevance 0.08~0.25, 주입 0.
+ * 이 값으로 첫날부터 매칭 가능성 제공 + 누적 후엔 표준 threshold 로 자연 전환.
+ */
+export declare const MIN_INJECT_RELEVANCE_COLD_START = 0.2;
+/** cold-start 판정 임계 — fitness state 있는 솔루션이 이 수 미만이면 신규 사용자 간주. */
+export declare const COLD_START_FITNESS_THRESHOLD = 5;
 interface SessionCacheCommitResult {
     /**
      * commit 상태:

package/dist/hooks/solution-injector.js

@@ -29,6 +29,7 @@ import { approve, approveWithContext, failOpenWithTracking } from './shared/hook
 import { STATE_DIR } from '../core/paths.js';
 import { recordHookTiming } from './shared/hook-timing.js';
 import { appendPending, flushAccept } from '../engine/solution-outcomes.js';
+import { appendImplicitFeedback } from '../store/implicit-feedback-store.js';
 const MAX_SOLUTIONS_PER_SESSION = 10;
 /**
  * Minimum relevance thresholds by fitness state (2026-04-21 gate sweep).
@@ -51,6 +52,15 @@ const MAX_SOLUTIONS_PER_SESSION = 10;
  */
 export const MIN_INJECT_RELEVANCE = 0.3;
 export const MIN_INJECT_RELEVANCE_TRUSTED = 0.25;
+/**
+ * v0.4.1 — cold-start 사용자 threshold. outcomes 이벤트가 거의 없는 신규 사용자
+ * 는 starter-pack 이 champion/active 로 승격될 기회가 없어 0.3 gate 에 막혀 주입 0.
+ * 실측 (buyer-day1 v2): starter 15개 중 recall 5건 전부 relevance 0.08~0.25, 주입 0.
+ * 이 값으로 첫날부터 매칭 가능성 제공 + 누적 후엔 표준 threshold 로 자연 전환.
+ */
+export const MIN_INJECT_RELEVANCE_COLD_START = 0.2;
+/** cold-start 판정 임계 — fitness state 있는 솔루션이 이 수 미만이면 신규 사용자 간주. */
+export const COLD_START_FITNESS_THRESHOLD = 5;
 /** 세션별 이미 주입된 솔루션 추적 (중복 방지) */
 function getSessionCachePath(sessionId) {
     return path.join(STATE_DIR, `solution-cache-${sanitizeId(sessionId)}.json`);
@@ -347,11 +357,17 @@ async function main() {
         catch (e) {
             log.debug('fitness state load 실패 — default 0.3 적용', e);
         }
+        // v0.4.1 cold-start boost: outcome 이벤트가 누적되지 않은 신규 사용자 (fitness
+        // state 있는 솔루션 < THRESHOLD) 는 champion/active 로 승격될 기회가 없으므로
+        // 보정된 낮은 threshold 적용. 누적되면 자동으로 표준 경로로 전환.
+        const isColdStart = fitnessStateMap.size < COLD_START_FITNESS_THRESHOLD;
         function minRelevanceFor(name) {
             const state = fitnessStateMap.get(name);
-            return (state === 'champion' || state === 'active')
-                ? MIN_INJECT_RELEVANCE_TRUSTED
-                : MIN_INJECT_RELEVANCE;
+            if (state === 'champion' || state === 'active')
+                return MIN_INJECT_RELEVANCE_TRUSTED;
+            if (isColdStart)
+                return MIN_INJECT_RELEVANCE_COLD_START;
+            return MIN_INJECT_RELEVANCE;
         }
         let experimentCount = 0;
         const toInject = [];
@@ -530,7 +546,34 @@ async function main() {
         catch (e) {
             log.debug('outcome appendPending 실패', e);
         }
-        console.log(approveWithContext(fullInjection, 'UserPromptSubmit'));
+        // H4: 양수 implicit-feedback — 솔루션이 실제로 사용자에게 surface 되었음을 기록.
+        // v0.4.0 의 enforcement 축은 block/violation 만 카운트했고 assist (solution 노출)
+        // 은 0건이었다. 이 emit 으로 forgen stats / session-quality-scorer 가 "오늘
+        // N개 surfaced" 를 계산할 수 있다.
+        try {
+            const now = new Date().toISOString();
+            for (const sol of effectiveToInject) {
+                appendImplicitFeedback({
+                    type: 'recommendation_surfaced',
+                    category: 'positive',
+                    solution: sol.name,
+                    match_score: sol.relevance,
+                    at: now,
+                    sessionId,
+                });
+            }
+        }
+        catch (e) {
+            log.debug('recommendation_surfaced emit 실패', e);
+        }
+        // H1: 사용자 UI 에 recall hit 1줄 노출. additionalContext 는 모델 전용이라
+        // v0.4.0 에서 8,000+ 주입이 발생했는데도 사용자는 0건을 봤다. systemMessage
+        // 로 "N개 솔루션 참조" 를 surface → 사용자가 어떤 축적 지식이 붙었는지 인식.
+        const topNames = effectiveToInject.slice(0, 3).map((s) => s.name);
+        const more = effectiveToInject.length - topNames.length;
+        const noticeNames = more > 0 ? `${topNames.join(', ')} (+${more})` : topNames.join(', ');
+        const userNotice = `[Forgen] 🔎 ${effectiveToInject.length} solution${effectiveToInject.length === 1 ? '' : 's'} recalled: ${noticeNames}`;
+        console.log(approveWithContext(fullInjection, 'UserPromptSubmit', userNotice));
     }
     finally {
         recordHookTiming('solution-injector', Date.now() - _hookStart, 'UserPromptSubmit');
@@ -538,5 +581,5 @@ async function main() {
 }
 main().catch((e) => {
     process.stderr.write(`[ch-hook] solution-injector: ${e instanceof Error ? e.message : String(e)}\n`);
-    console.log(failOpenWithTracking('solution-injector'));
+    console.log(failOpenWithTracking('solution-injector', e));
 });