@wooojin/forgen 0.4.0 → 0.4.3

package/dist/host/projection.js

@@ -0,0 +1,126 @@
+/**
+ * ProjectToClaudeEvent — Multi-Host Core Design §5.2 / §10 우선순위 2
+ *
+ * Codex (또는 미래의 다른 host) 의 hook 출력을 Claude Hook schema 로 사영하는
+ * 정식 계약. spec §17.4 / §18.4 에서 검증되었듯 schema-level 에서 거의 identity 이므로
+ * 본 함수는 *형식 정규화* 만 책임진다.
+ *
+ * - 입력: host-native 출력(JSON object, plaintext, exit-code 등은 별도 layer 에서 처리)
+ * - 출력: Claude HookEventOutput 동치 — `continue`, `hookSpecificOutput.permissionDecision`, etc.
+ * - 실패 정책: parse 실패 / 알 수 없는 형식 → fail-open (`{ continue: true }`)
+ *
+ * 본 모듈은 host 측 표면을 *모르고*, 받은 raw 의 형태만으로 동작한다 (1원칙: core 는 Claude
+ * semantics 알아도 됨, Codex 표면 모름). 즉 Codex CLI 의 stdout 을 받아 코어가 학습 가능한
+ * Claude 형 객체로 변환만 한다.
+ */
+function parseDecision(raw) {
+    if (typeof raw === 'boolean')
+        return { continueFlag: raw };
+    if (typeof raw === 'string') {
+        const normalized = raw.toLowerCase();
+        if (normalized === 'continue')
+            return { continueFlag: true };
+        if (normalized === 'stop' ||
+            normalized === 'deny' ||
+            normalized === 'reject' ||
+            normalized === 'block') {
+            return { continueFlag: false, permissionDecision: normalized };
+        }
+        return { continueFlag: true };
+    }
+    if (typeof raw !== 'object' || raw === null)
+        return { continueFlag: true };
+    const decision = raw.decision;
+    if (typeof decision === 'string') {
+        const normalized = decision.toLowerCase();
+        if (normalized === 'deny' || normalized === 'reject' || normalized === 'block') {
+            return { continueFlag: false, permissionDecision: normalized };
+        }
+        if (normalized === 'ask' || normalized === 'prompt' || normalized === 'confirm') {
+            return { continueFlag: true, permissionDecision: normalized };
+        }
+    }
+    if (typeof raw.approved === 'boolean') {
+        const approved = raw.approved;
+        return approved
+            ? { continueFlag: true, permissionDecision: raw.decision || 'approve' }
+            : { continueFlag: false, permissionDecision: 'deny' };
+    }
+    if (typeof raw.continue === 'boolean') {
+        return { continueFlag: raw.continue };
+    }
+    return { continueFlag: true };
+}
+/**
+ * Codex 출력 → Claude HookEventOutput 정식 사영.
+ *
+ * spec §18.2 fact #3 에 따라 PreToolUse 의 *이중* decision 필드 중 어댑터는
+ * `hookSpecificOutput.permissionDecision` 을 우선한다. 본 함수가 그 규약을 강제.
+ */
+export const projectCodexToClaude = (raw, input) => {
+    const result = { continue: true };
+    const decision = parseDecision(raw);
+    result.continue = decision.continueFlag;
+    if (typeof raw === 'object' && raw !== null) {
+        const payload = raw;
+        if (typeof payload.continue === 'boolean')
+            result.continue = payload.continue;
+        if (typeof payload.systemMessage === 'string')
+            result.systemMessage = payload.systemMessage;
+        if (typeof payload.suppressOutput === 'boolean')
+            result.suppressOutput = payload.suppressOutput;
+        if (typeof payload.hookSpecificOutput === 'object' && payload.hookSpecificOutput !== null) {
+            result.hookSpecificOutput = { ...payload.hookSpecificOutput };
+        }
+        // top-level decision (Codex 의 PreToolUse 이중 decision 중 legacy 측 또는 Stop/Post 의 단일 측)
+        // 이 있고, hookSpecificOutput.permissionDecision 이 비었을 때만 보존.
+        if (typeof payload.decision === 'string' &&
+            !(result.hookSpecificOutput && 'permissionDecision' in result.hookSpecificOutput)) {
+            result.hookSpecificOutput = {
+                ...(result.hookSpecificOutput ?? {}),
+                permissionDecision: payload.decision,
+            };
+        }
+    }
+    const eventName = result.hookSpecificOutput?.hookEventName ?? input.hookEventName ?? input.event;
+    if (eventName) {
+        result.hookSpecificOutput = {
+            hookEventName: eventName,
+            ...(result.hookSpecificOutput ?? {}),
+        };
+    }
+    if (!result.continue && !result.hookSpecificOutput?.permissionDecision) {
+        if (decision.permissionDecision) {
+            result.hookSpecificOutput = {
+                ...(result.hookSpecificOutput ?? {}),
+                permissionDecision: decision.permissionDecision,
+            };
+        }
+        else {
+            result.hookSpecificOutput = {
+                ...(result.hookSpecificOutput ?? {}),
+                permissionDecision: 'deny',
+            };
+        }
+    }
+    return result;
+};
+/**
+ * Claude 어댑터의 사영. 1원칙(Claude reference) + spec §18.4 (Codex hooks.json schema 동일성)
+ * 에 따라 본 함수는 `projectCodexToClaude` 와 *같은 normalize 로직* 을 공유한다.
+ * 둘 다 같은 canonical Claude HookEventOutput 형식을 만든다.
+ *
+ * (왜 두 함수를 별도 export 하는가: 향후 schema 가 다른 host 가 추가될 때 본 binding 만
+ * 교체하면 되도록 — `getProjection(host)` 가 단일 진입점.)
+ */
+export const projectClaudeToClaude = (raw, input) => projectCodexToClaude(raw, input);
+const PROJECTIONS = {
+    claude: projectClaudeToClaude,
+    codex: projectCodexToClaude,
+};
+export function getProjection(host) {
+    const fn = PROJECTIONS[host];
+    if (!fn)
+        throw new Error(`No ProjectToClaudeEvent registered for host: ${host}`);
+    return fn;
+}

package/dist/i18n/index.js

@@ -5,8 +5,7 @@
  * 사용자 대면 출력만 로케일에 따라 전환.
  */
 import * as fs from 'node:fs';
-import * as path from 'node:path';
-import * as os from 'node:os';
+import { GLOBAL_CONFIG } from '../core/paths.js';
 // ── Pack Display Names ──
 const QUALITY_NAMES = {
     ko: { '보수형': '보수형', '균형형': '균형형', '속도형': '속도형' },
@@ -215,10 +214,9 @@ export function getLocale() { return _currentLocale; }
 /** GlobalConfig에서 locale을 읽어 설정. 없으면 'en' 기본값. */
 export function initLocaleFromConfig() {
     try {
-        const configPath = path.join(os.homedir(), '.forgen', 'config.json');
-        if (!fs.existsSync(configPath))
+        if (!fs.existsSync(GLOBAL_CONFIG))
             return;
-        const config = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+        const config = JSON.parse(fs.readFileSync(GLOBAL_CONFIG, 'utf-8'));
         if (config.locale === 'ko' || config.locale === 'en') {
             _currentLocale = config.locale;
         }

package/dist/mcp/server.js

@@ -12,6 +12,17 @@ if (!process.env.FORGEN_CWD && !process.env.COMPOUND_CWD) {
     process.env.FORGEN_CWD = process.cwd();
     process.env.COMPOUND_CWD = process.cwd(); // legacy compat
 }
+// Multi-host evidence attribution (spec §10-5):
+// 호출 host 가 spawn 시 `--host=<claude|codex>` 인자를 넘기면 본 process 의
+// FORGEN_HOST env 를 set 한다. evidence-store 의 detectHost() 가 이 env 를 읽어
+// correction-record 가 정확한 host 로 박제되게 한다. 미지정 시 기존 fallback
+// (FORGEN_HOST > CODEX_HOME 추론 > 'claude') 그대로.
+const hostArg = process.argv
+    .find((a) => a === '--host=claude' || a === '--host=codex')
+    ?.split('=')[1];
+if (hostArg === 'claude' || hostArg === 'codex') {
+    process.env.FORGEN_HOST = hostArg;
+}
 const INSTRUCTIONS = [
     'Forgen compound knowledge — accumulated patterns and solutions from past sessions.',
     '',

package/dist/mcp/tools.js

@@ -441,4 +441,51 @@ export function registerTools(server) {
                 }],
         };
     });
+    // ── invoke-agent (P3-4/P3-5) ─────────────────────────────────────────
+    //
+    // forgen 의 13 sub-agents (assets/claude/agents/*.md) 를 MCP 도구로 노출.
+    // Claude 의 Task tool 동치를 host 무관 형태로 제공:
+    //   - Claude main agent: Task tool 우선 사용 (native, faster)
+    //   - Codex main agent: invoke-agent MCP 도구가 codex exec --json 으로 child spawn
+    // 실 작업: assets/claude/agents/<name>.md 의 system prompt 를 prefix 로,
+    // 사용자 task 를 prompt 로 child host CLI 호출 → 응답 반환.
+    server.registerTool('invoke-agent', {
+        description: [
+            'Invoke a forgen sub-agent (specialized prompt) on a task and return its summary.',
+            'Use when delegation is helpful — e.g., focused exploration (ch-explore), implementation (ch-executor),',
+            'critical review (ch-critic), test writing (ch-test-engineer).',
+            'The sub-agent runs in a separate child process with isolated context and returns just the result.',
+            'Available agent names match files under assets/claude/agents/ (e.g., ch-explore, ch-executor, ch-critic).',
+        ].join('\n'),
+        inputSchema: {
+            agent_name: z.string().describe('Sub-agent identifier (e.g., "ch-explore", "ch-executor")'),
+            task: z.string().describe('What you want the sub-agent to do — natural language task description'),
+            timeout_ms: z.number().int().positive().max(300000).optional()
+                .describe('Child timeout in ms (default 60s, max 5m)'),
+        },
+        annotations: { readOnlyHint: false },
+    }, async ({ agent_name, task, timeout_ms }) => {
+        try {
+            const { invokeAgent } = await import('../host/invoke-agent.js');
+            const result = await invokeAgent({ agentName: agent_name, task, timeoutMs: timeout_ms });
+            const lines = [
+                `[invoke-agent] ${agent_name} (${result.host}, ${result.durationMs}ms)`,
+                '',
+                result.summary,
+            ];
+            if (result.usage) {
+                lines.push('', `Usage: input=${result.usage.input_tokens ?? '?'} output=${result.usage.output_tokens ?? '?'}`);
+            }
+            return {
+                content: [{ type: 'text', text: lines.join('\n') }],
+            };
+        }
+        catch (e) {
+            const msg = e instanceof Error ? e.message : String(e);
+            return {
+                content: [{ type: 'text', text: `[invoke-agent] error: ${msg}` }],
+                isError: true,
+            };
+        }
+    });
 }

package/dist/services/session.d.ts

@@ -10,10 +10,13 @@
  * - launch context(런타임 + 정제된 args)를 단일 타입으로 통일
  * - CLI/fgx에서 수집한 런타임 값을 Harness, Spawn, Hook Generator에 일관되게 전달
  */
-import { type LaunchContext } from '../core/types.js';
+import type { LaunchContext } from '../core/types.js';
 /**
  * CLI 인자를 파싱해 런타임 결정 + 런타임 플래그 제거
- * - --runtime codex
- * - --runtime=codex
+ * 우선순위 (높음→낮음):
+ *   1. --runtime <claude|codex> flag
+ *   2. FORGEN_RUNTIME env
+ *   3. profile.default_host (P1-4)
+ *   4. 'claude' fallback (legacy 호환)
  */
 export declare function resolveLaunchContext(args: string[]): LaunchContext;

package/dist/services/session.js

@@ -10,6 +10,8 @@
  * - launch context(런타임 + 정제된 args)를 단일 타입으로 통일
  * - CLI/fgx에서 수집한 런타임 값을 Harness, Spawn, Hook Generator에 일관되게 전달
  */
+import { createRequire } from 'node:module';
+const localRequire = createRequire(import.meta.url);
 /** 런타임 정규화: 외부 문자열을 내부 enum으로 변환 */
 function parseRuntime(raw) {
     if (!raw)
@@ -24,17 +26,44 @@ function parseRuntime(raw) {
     }
 }
 const DEFAULT_RUNTIME = 'claude';
+/**
+ * profile.default_host 를 읽어 runtime 결정.
+ * 'ask' 면 별도 prompt 책임 — 본 함수는 default 'claude' 로 fallback (caller 가 --ask 처리).
+ * profile-store import 가 cycle 위험이라 require 로 lazy.
+ */
+function readProfileDefaultRuntime() {
+    try {
+        const mod = localRequire('../store/profile-store.js');
+        const stored = mod.getDefaultHost?.();
+        if (stored === 'claude' || stored === 'codex')
+            return stored;
+        return null; // 'ask' 또는 미설정
+    }
+    catch {
+        return null;
+    }
+}
 /**
  * CLI 인자를 파싱해 런타임 결정 + 런타임 플래그 제거
- * - --runtime codex
- * - --runtime=codex
+ * 우선순위 (높음→낮음):
+ *   1. --runtime <claude|codex> flag
+ *   2. FORGEN_RUNTIME env
+ *   3. profile.default_host (P1-4)
+ *   4. 'claude' fallback (legacy 호환)
  */
 export function resolveLaunchContext(args) {
     const runtimeFromEnv = parseRuntime(process.env.FORGEN_RUNTIME);
+    const runtimeFromProfile = runtimeFromEnv ? null : readProfileDefaultRuntime();
+    const initial = runtimeFromEnv ?? runtimeFromProfile ?? DEFAULT_RUNTIME;
+    const initialSource = runtimeFromEnv
+        ? 'env'
+        : runtimeFromProfile
+            ? 'profile'
+            : 'default';
     const result = {
-        runtime: runtimeFromEnv ?? DEFAULT_RUNTIME,
+        runtime: initial,
         args: [],
-        runtimeSource: runtimeFromEnv ? 'env' : 'default',
+        runtimeSource: initialSource,
     };
     for (let i = 0; i < args.length; i += 1) {
         const arg = args[i];

package/dist/store/evidence-store.d.ts

@@ -14,6 +14,7 @@ export declare function createEvidence(params: {
     candidate_rule_refs?: string[];
     confidence: number;
     raw_payload?: Record<string, unknown>;
+    host?: 'claude' | 'codex';
 }): Evidence;
 export declare function saveEvidence(evidence: Evidence): void;
 /**

package/dist/store/evidence-store.js

@@ -17,6 +17,24 @@ import { appendLifecycleEvents } from '../engine/lifecycle/meta-reclassifier.js'
 function evidencePath(evidenceId) {
     return path.join(ME_BEHAVIOR, `${evidenceId}.json`);
 }
+/**
+ * 현재 세션이 어느 host 에서 실행되는지 추론 (Multi-Host §4.2).
+ * 1) explicit `params.host`
+ * 2) env var `FORGEN_HOST` (e2e 격리용)
+ * 3) `runtime` env hint
+ * 4) Codex CLI 흔적 (`CODEX_HOME` 또는 `CODEX_SANDBOX_NETWORK_DISABLED`)
+ * 5) default 'claude' (1원칙)
+ */
+function detectHost(explicit) {
+    if (explicit)
+        return explicit;
+    const fromEnv = process.env.FORGEN_HOST;
+    if (fromEnv === 'claude' || fromEnv === 'codex')
+        return fromEnv;
+    if (process.env.CODEX_HOME || process.env.CODEX_SANDBOX_NETWORK_DISABLED)
+        return 'codex';
+    return 'claude';
+}
 export function createEvidence(params) {
     return {
         evidence_id: crypto.randomUUID(),
@@ -29,9 +47,21 @@ export function createEvidence(params) {
         candidate_rule_refs: params.candidate_rule_refs ?? [],
         confidence: params.confidence,
         raw_payload: params.raw_payload ?? {},
+        host: detectHost(params.host),
     };
 }
+/** TEST-4 / RC4: behavior_observation 의 summary 가 의미있는 내용을 담아야 분석 가능. */
+const MIN_BEHAVIOR_OBSERVATION_LEN = 20;
 export function saveEvidence(evidence) {
+    // TEST-4 / RC4: 빈/짧은 behavior_observation 은 저장 거부.
+    // 결함: ~/.forgen/me/behavior/*.json 다수에 summary="" 가 누적되어 학습 데이터가
+    // 분석 불가능한 형태로 쌓임. saveEvidence 가 마지막 게이트라 여기서 거른다.
+    // 다른 evidence type (explicit_correction, session_summary) 은 backward compat.
+    if (evidence.type === 'behavior_observation') {
+        const len = (evidence.summary ?? '').trim().length;
+        if (len < MIN_BEHAVIOR_OBSERVATION_LEN)
+            return;
+    }
     atomicWriteJSON(evidencePath(evidence.evidence_id), evidence, { pretty: true });
 }
 /**
@@ -73,8 +103,19 @@ export function appendEvidence(evidence) {
         return { saved: true, t1_events: 0 };
     }
 }
+/**
+ * 기존 evidence 에 host 필드가 없으면 'claude' 로 backfill (Multi-Host §4.2 마이그레이션 정책).
+ * 새 multi-host 도입 이전 데이터는 모두 Claude 에서 발생했음 — 이 backfill 은 무손실.
+ */
+function backfillHost(ev) {
+    if (!ev)
+        return ev;
+    if (ev.host === 'claude' || ev.host === 'codex')
+        return ev;
+    return { ...ev, host: 'claude' };
+}
 export function loadEvidence(evidenceId) {
-    return safeReadJSON(evidencePath(evidenceId), null);
+    return backfillHost(safeReadJSON(evidencePath(evidenceId), null));
 }
 export function loadAllEvidence() {
     if (!fs.existsSync(ME_BEHAVIOR))
@@ -84,8 +125,9 @@ export function loadAllEvidence() {
         if (!file.endsWith('.json'))
             continue;
         const ev = safeReadJSON(path.join(ME_BEHAVIOR, file), null);
-        if (ev)
-            items.push(ev);
+        const filled = backfillHost(ev);
+        if (filled)
+            items.push(filled);
     }
     return items;
 }

package/dist/store/host-mismatch.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Host-mismatch demote signal — Multi-Host Core Design §4.3 / §10 우선순위 5
+ *
+ * spec §12.2 / §18 결과: schema-level 등가성이 강하므로 *호스트별 가중치* 가 아니라
+ * *불일치 신호* 만 사용한다. 같은 솔루션/규칙이 한 host 에서만 자주 깨지면 그 host 한정으로
+ * demote 후보. 본 모듈은 그 신호를 *읽기만* 한다 — 실제 demote 적용은 lifecycle 트랙.
+ *
+ * 신호 정의 (Phase 1 단순 버전):
+ *   - solution_failed_to_apply_count_by_host
+ *   - block_acknowledged_then_revert_count_by_host
+ *   - drift_event_count_by_host
+ * 위 3 종 metric 을 evidence_id → host 매핑으로 집계.
+ */
+export type HostId = 'claude' | 'codex';
+export interface HostMismatchSummary {
+    readonly byHost: Record<HostId, number>;
+    readonly total: number;
+    /** ratio of host with most events to total (0..1). 0.5 = balanced, 1.0 = single-host signal. */
+    readonly skew: number;
+    /** the dominant host (or null if balanced). */
+    readonly dominantHost: HostId | null;
+    /** 본 신호가 lifecycle demote 를 권고할 정도로 강한지. 임계값은 1차 단순. */
+    readonly demoteRecommended: boolean;
+}
+/**
+ * 특정 솔루션/규칙 ID 에 대해 *부정적 evidence* (drift, revert, failure) 가 host 별로
+ * 어떻게 분포하는지 요약.
+ *
+ * 1차 구현은 evidence.summary 의 ID 매칭으로 단순 집계. 향후 evidence 가 명시적 ref 필드를
+ * 가지면 그쪽으로 전환.
+ */
+export declare function summarizeNegativeSignalsForRef(refId: string): HostMismatchSummary;
+export declare function summarizeAllByHost(): {
+    claude: number;
+    codex: number;
+    total: number;
+};
+/** 테스트 노출용 — 임계값이 변경되면 회귀 즉시 감지. */
+export declare const HOST_MISMATCH_TUNING: {
+    readonly DOMINANCE_THRESHOLD: 0.8;
+    readonly MIN_TOTAL_FOR_DEMOTE: 5;
+};

package/dist/store/host-mismatch.js

@@ -0,0 +1,65 @@
+/**
+ * Host-mismatch demote signal — Multi-Host Core Design §4.3 / §10 우선순위 5
+ *
+ * spec §12.2 / §18 결과: schema-level 등가성이 강하므로 *호스트별 가중치* 가 아니라
+ * *불일치 신호* 만 사용한다. 같은 솔루션/규칙이 한 host 에서만 자주 깨지면 그 host 한정으로
+ * demote 후보. 본 모듈은 그 신호를 *읽기만* 한다 — 실제 demote 적용은 lifecycle 트랙.
+ *
+ * 신호 정의 (Phase 1 단순 버전):
+ *   - solution_failed_to_apply_count_by_host
+ *   - block_acknowledged_then_revert_count_by_host
+ *   - drift_event_count_by_host
+ * 위 3 종 metric 을 evidence_id → host 매핑으로 집계.
+ */
+import { loadAllEvidence } from './evidence-store.js';
+const DOMINANCE_THRESHOLD = 0.8; // 80% 이상이 한 host 에서 발생하면 dominant.
+const MIN_TOTAL_FOR_DEMOTE = 5; // 너무 적은 표본은 무시.
+function summarize(events) {
+    const byHost = { claude: 0, codex: 0 };
+    for (const e of events) {
+        const h = (e.host ?? 'claude');
+        byHost[h] += 1;
+    }
+    const total = byHost.claude + byHost.codex;
+    if (total === 0) {
+        return { byHost, total, skew: 0, dominantHost: null, demoteRecommended: false };
+    }
+    const claudeShare = byHost.claude / total;
+    const codexShare = byHost.codex / total;
+    const dominant = claudeShare >= codexShare ? 'claude' : 'codex';
+    const skew = Math.max(claudeShare, codexShare);
+    const demoteRecommended = total >= MIN_TOTAL_FOR_DEMOTE && skew >= DOMINANCE_THRESHOLD;
+    return { byHost, total, skew, dominantHost: dominant, demoteRecommended };
+}
+/**
+ * 특정 솔루션/규칙 ID 에 대해 *부정적 evidence* (drift, revert, failure) 가 host 별로
+ * 어떻게 분포하는지 요약.
+ *
+ * 1차 구현은 evidence.summary 의 ID 매칭으로 단순 집계. 향후 evidence 가 명시적 ref 필드를
+ * 가지면 그쪽으로 전환.
+ */
+export function summarizeNegativeSignalsForRef(refId) {
+    const all = loadAllEvidence();
+    const matched = all.filter((e) => {
+        if (Array.isArray(e.candidate_rule_refs) && e.candidate_rule_refs.includes(refId))
+            return true;
+        if (typeof e.summary === 'string' && e.summary.includes(refId)) {
+            // 명시적 음수 키워드 (drift, revert, failed, block-revert) 가 있을 때만.
+            return /drift|revert|failed|regress/i.test(e.summary);
+        }
+        return false;
+    });
+    return summarize(matched);
+}
+export function summarizeAllByHost() {
+    const all = loadAllEvidence();
+    const r = { claude: 0, codex: 0 };
+    for (const e of all)
+        r[(e.host ?? 'claude')] += 1;
+    return { ...r, total: r.claude + r.codex };
+}
+/** 테스트 노출용 — 임계값이 변경되면 회귀 즉시 감지. */
+export const HOST_MISMATCH_TUNING = {
+    DOMINANCE_THRESHOLD,
+    MIN_TOTAL_FOR_DEMOTE,
+};

package/dist/store/implicit-feedback-store.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Forgen v0.4.1 — Implicit Feedback Store (TEST-5)
+ *
+ * `~/.forgen/state/implicit-feedback.jsonl` 의 append/read.
+ *
+ * TEST-5 / RC5: 누적된 엔트리들이 `type` 문자열만 가지고 category 없이 섞여 있어
+ *   - drift_critical / drift_warning / revert_detected / repeated_edit / agent_* 가 한 스트림에 섞여
+ *   - 집계/쿼리 시 카테고리 enum 부재로 휴리스틱 문자열 매칭에 의존
+ *   - 스키마 검증이 없어 빈/잘못된 필드로 쓰여도 나중에 분석 불가
+ * 이 모듈은 category 필드를 **필수화**하고, 기존 레거시 라인은 read 시 `type→category`
+ * 백필로 보정한다. 새 write 는 category 없으면 drift/revert 계열은 **거부**한다.
+ */
+export declare const IMPLICIT_FEEDBACK_LOG: string;
+/**
+ * TEST-5/H4: 카테고리 enum.
+ *  - drift / revert: 네거티브 signal (schema 강제)
+ *  - edit / agent: 네거티브-ish signal (휴리스틱)
+ *  - positive: H4 양수 신호 — assist (recommendation_surfaced, recall_referenced)
+ */
+export type ImplicitFeedbackCategory = 'drift' | 'revert' | 'edit' | 'agent' | 'positive';
+export interface ImplicitFeedbackEntry {
+    type: string;
+    category: ImplicitFeedbackCategory;
+    sessionId?: string;
+    at: string;
+    [key: string]: unknown;
+}
+/** 호출지 입력 — category 선택적 (schema 가 허용하면 inference 로 채움). */
+export interface ImplicitFeedbackInput {
+    type: string;
+    category?: ImplicitFeedbackCategory;
+    sessionId?: string;
+    at: string;
+    [key: string]: unknown;
+}
+/** type → category 추론. 레거시 엔트리 마이그레이션과 호출지 기본값 계산에 공용. */
+export declare function inferCategoryFromType(type: string): ImplicitFeedbackCategory | null;
+/**
+ * TEST-5 메인 라이터. 내부에서 스키마 검증 후 append.
+ * drift/revert 스키마 위반 시 silent drop (hot path 에서 throw 금지).
+ * 반환값: 실제로 기록되었는지 (테스트 검증용).
+ */
+export declare function appendImplicitFeedback(entry: ImplicitFeedbackInput): boolean;
+/**
+ * TEST-5 리더. 세션 필터링 + 레거시 라인에 대한 lazy 마이그레이션 (category 백필).
+ * 디스크 상 파일은 건드리지 않고 읽기 시점에만 category 를 보정한다 — atomic-write
+ * 없이 append-only 로그를 rewrite 하면 race 위험이 있기 때문.
+ * 영구 백필은 `migrateImplicitFeedbackLog()` 를 명시적으로 호출한다.
+ */
+export declare function loadImplicitFeedback(sessionId: string): ImplicitFeedbackEntry[];
+/**
+ * 영구 마이그레이션 — 레거시 로그 파일을 읽어 category 백필 후 원자적으로 재기록.
+ * 마이그레이션 불가 라인 (type 도 category 도 없거나 inference 실패) 은 drop.
+ * 반환: { migrated: 백필된 라인 수, dropped: 버려진 라인 수 }
+ */
+export declare function migrateImplicitFeedbackLog(): {
+    migrated: number;
+    dropped: number;
+};