@wooojin/forgen 0.1.0

package/dist/forge/mismatch-detector.js

@@ -0,0 +1,83 @@
+/**
+ * Forgen v1 — Pack Mismatch Detector
+ *
+ * rolling 3세션 mismatch score 계산.
+ * Authoritative spec: docs/plans/2026-04-03-forgen-onboarding-adaptation-spec.md §8
+ *
+ * 신호별 점수:
+ * - 반대 방향 explicit_correction: +2
+ * - session_summary가 반대 pack 성향 명시: +1
+ * - 같은 축 strong rule 2개+ 신규 생성: +1
+ *
+ * 후보 조건:
+ * - 최근 3세션 rolling sum >= 4 (축별)
+ * - 또는 최근 3세션에 같은 방향 explicit_correction 2회+
+ */
+/**
+ * 단일 세션의 mismatch 신호를 계산.
+ *
+ * @param sessionId 세션 ID
+ * @param corrections 해당 세션의 explicit_correction evidence
+ * @param summaries 해당 세션의 session_summary evidence
+ * @param newStrongRules 해당 세션에서 신규 생성된 strong rule
+ * @param currentQuality 현재 quality pack
+ * @param currentAutonomy 현재 autonomy pack
+ */
+export function computeSessionSignals(sessionId, corrections, summaries, newStrongRules, _currentQuality, _currentAutonomy) {
+    const signals = [];
+    // 반대 방향 explicit_correction
+    for (const c of corrections) {
+        for (const axis of c.axis_refs) {
+            if (axis === 'quality_safety' || axis === 'autonomy') {
+                // correction의 raw_payload에 direction 힌트가 있으면 pack과 비교
+                const direction = c.raw_payload?.direction;
+                if (direction === 'opposite') {
+                    signals.push({ session_id: sessionId, axis, score: 2, reason: `반대 방향 correction: ${c.summary}` });
+                }
+            }
+        }
+    }
+    // session_summary가 반대 성향 명시
+    for (const s of summaries) {
+        const packHint = s.raw_payload?.pack_direction;
+        if (packHint === 'opposite_quality') {
+            signals.push({ session_id: sessionId, axis: 'quality_safety', score: 1, reason: `session summary 반대 성향: ${s.summary}` });
+        }
+        if (packHint === 'opposite_autonomy') {
+            signals.push({ session_id: sessionId, axis: 'autonomy', score: 1, reason: `session summary 반대 성향: ${s.summary}` });
+        }
+    }
+    // 같은 축 strong rule 2개+ 신규 생성
+    const qualityStrong = newStrongRules.filter(r => r.category === 'quality' && r.strength === 'strong');
+    const autonomyStrong = newStrongRules.filter(r => r.category === 'autonomy' && r.strength === 'strong');
+    if (qualityStrong.length >= 2) {
+        signals.push({ session_id: sessionId, axis: 'quality_safety', score: 1, reason: `${qualityStrong.length}개 strong quality rule 신규 생성` });
+    }
+    if (autonomyStrong.length >= 2) {
+        signals.push({ session_id: sessionId, axis: 'autonomy', score: 1, reason: `${autonomyStrong.length}개 strong autonomy rule 신규 생성` });
+    }
+    return signals;
+}
+/**
+ * 최근 3세션 rolling sum으로 mismatch 판정.
+ */
+export function detectMismatch(recentSignals) {
+    let qualityScore = 0;
+    let autonomyScore = 0;
+    for (const s of recentSignals) {
+        if (s.axis === 'quality_safety')
+            qualityScore += s.score;
+        if (s.axis === 'autonomy')
+            autonomyScore += s.score;
+    }
+    // 같은 방향 correction 2회+ 체크
+    const qualityCorrections = recentSignals.filter(s => s.axis === 'quality_safety' && s.score === 2);
+    const autonomyCorrections = recentSignals.filter(s => s.axis === 'autonomy' && s.score === 2);
+    return {
+        quality_mismatch: qualityScore >= 4 || qualityCorrections.length >= 2,
+        autonomy_mismatch: autonomyScore >= 4 || autonomyCorrections.length >= 2,
+        quality_score: qualityScore,
+        autonomy_score: autonomyScore,
+        signals: recentSignals,
+    };
+}

package/dist/forge/onboarding-cli.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Forgen v1 — Onboarding CLI
+ *
+ * 언어 선택 + 4문항 온보딩 인터랙티브 flow.
+ */
+export declare function runOnboarding(): Promise<void>;

package/dist/forge/onboarding-cli.js

@@ -0,0 +1,89 @@
+/**
+ * Forgen v1 — Onboarding CLI
+ *
+ * 언어 선택 + 4문항 온보딩 인터랙티브 flow.
+ */
+import * as readline from 'node:readline';
+import { computeOnboarding, onboardingToRecommendation } from './onboarding.js';
+import { createProfile, saveProfile } from '../store/profile-store.js';
+import { saveRecommendation, updateRecommendationStatus } from '../store/recommendation-store.js';
+import { ensureV1Directories } from '../core/v1-bootstrap.js';
+import { ONBOARDING, qualityName, autonomyName, judgmentName, communicationName, trustName, setLocale } from '../i18n/index.js';
+import { saveGlobalConfig, loadGlobalConfig } from '../core/global-config.js';
+function askChoice(rl, question, validChoices, errorMsg) {
+    return new Promise((resolve) => {
+        const ask = () => {
+            rl.question(question, (answer) => {
+                const upper = answer.trim().toUpperCase();
+                if (validChoices.includes(upper)) {
+                    resolve(upper);
+                }
+                else {
+                    console.log(errorMsg);
+                    ask();
+                }
+            });
+        };
+        ask();
+    });
+}
+export async function runOnboarding() {
+    ensureV1Directories();
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        // 0. 언어 선택
+        console.log(`
+  ╔══════════════════════════════════════════════╗
+  ║  Forgen — Setup                             ║
+  ╚══════════════════════════════════════════════╝
+
+  Select language / 언어를 선택하세요:
+
+    1) English
+    2) 한국어
+`);
+        const langChoice = await askChoice(rl, '  Choice / 선택 (1/2): ', ['1', '2'], '  Please enter 1 or 2. / 1 또는 2를 입력하세요.');
+        const locale = langChoice === '2' ? 'ko' : 'en';
+        setLocale(locale);
+        // locale을 GlobalConfig에 저장
+        const config = loadGlobalConfig();
+        config.locale = locale;
+        saveGlobalConfig(config);
+        const strings = ONBOARDING[locale];
+        console.log(`
+  ╔══════════════════════════════════════════════╗
+  ║${strings.header.padEnd(46)}║
+  ╚══════════════════════════════════════════════╝
+
+${strings.subtitle}`);
+        // 1-4. 4문항
+        const q1 = await askChoice(rl, strings.q1, ['A', 'B', 'C'], strings.invalidChoice);
+        const q2 = await askChoice(rl, strings.q2, ['A', 'B', 'C'], strings.invalidChoice);
+        const q3 = await askChoice(rl, strings.q3, ['A', 'B', 'C'], strings.invalidChoice);
+        const q4 = await askChoice(rl, strings.q4, ['A', 'B', 'C'], strings.invalidChoice);
+        const result = computeOnboarding(q1, q2, q3, q4);
+        console.log(`
+  ─────────────────────────────────────────
+  ${strings.resultHeader}
+
+    Quality:       ${qualityName(result.qualityPack, locale)} (confidence: ${result.qualityConfidence.toFixed(2)})
+    Autonomy:      ${autonomyName(result.autonomyPack, locale)} (confidence: ${result.autonomyConfidence.toFixed(2)})
+    Judgment:      ${judgmentName(result.judgmentPack, locale)} (confidence: ${result.judgmentConfidence.toFixed(2)})
+    Communication: ${communicationName(result.communicationPack, locale)} (confidence: ${result.communicationConfidence.toFixed(2)})
+    Trust:         ${trustName(result.suggestedTrustPolicy, locale)}
+  ─────────────────────────────────────────`);
+        // Recommendation 저장
+        const rec = onboardingToRecommendation(result);
+        saveRecommendation(rec);
+        updateRecommendationStatus(rec.recommendation_id, 'accepted');
+        // Profile 생성
+        const profile = createProfile('default', result.qualityPack, result.autonomyPack, result.suggestedTrustPolicy, 'onboarding', result.judgmentPack, result.communicationPack);
+        saveProfile(profile);
+        console.log(`
+  ${strings.profileSaved}
+`);
+    }
+    finally {
+        rl.close();
+    }
+}

package/dist/forge/onboarding.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Forgen v1 — Onboarding
+ *
+ * 2문항 온보딩, 점수 계산, pack 추천.
+ * Authoritative spec: docs/plans/2026-04-03-forgen-onboarding-adaptation-spec.md §3-4
+ */
+import type { QualityPack, AutonomyPack, JudgmentPack, CommunicationPack, TrustPolicy, PackRecommendation } from '../store/types.js';
+export type ChoiceId = 'A' | 'B' | 'C';
+export interface OnboardingResult {
+    qualityScore: number;
+    autonomyScore: number;
+    judgmentScore: number;
+    communicationScore: number;
+    qualityPack: QualityPack;
+    autonomyPack: AutonomyPack;
+    judgmentPack: JudgmentPack;
+    communicationPack: CommunicationPack;
+    qualityConfidence: number;
+    autonomyConfidence: number;
+    judgmentConfidence: number;
+    communicationConfidence: number;
+    suggestedTrustPolicy: TrustPolicy;
+}
+export declare function computeOnboarding(q1: ChoiceId, q2: ChoiceId, q3?: ChoiceId, q4?: ChoiceId): OnboardingResult;
+export declare function onboardingToRecommendation(result: OnboardingResult): PackRecommendation;

package/dist/forge/onboarding.js

@@ -0,0 +1,122 @@
+/**
+ * Forgen v1 — Onboarding
+ *
+ * 2문항 온보딩, 점수 계산, pack 추천.
+ * Authoritative spec: docs/plans/2026-04-03-forgen-onboarding-adaptation-spec.md §3-4
+ */
+import { createRecommendation } from '../store/recommendation-store.js';
+// 질문 1: 애매한 구현 요청 + 인접 영향 가능성
+// 주 판별: 자율 실행 성향, 보조: 품질/안전
+const Q1_SCORES = {
+    A: { quality: -1, autonomy: -2 },
+    B: { quality: 0, autonomy: 0 },
+    C: { quality: +1, autonomy: +2 },
+};
+// 질문 2: 수정 완료 직전 + 검증 강도 vs 완료 속도
+// 주 판별: 품질/안전, 보조: 자율 실행 성향
+const Q2_SCORES = {
+    A: { quality: -2, autonomy: 0 },
+    B: { quality: 0, autonomy: 0 },
+    C: { quality: +2, autonomy: +1 },
+};
+// 질문 3: 코드 수정 접근법 — 최소변경 vs 구조적 리팩토링
+// 주 판별: 판단 철학
+const Q3_SCORES = {
+    A: { judgment: -2 }, // 최소 변경 우선
+    B: { judgment: 0 },
+    C: { judgment: +2 }, // 구조적 정리 우선
+};
+// 질문 4: 설명/보고 스타일 — 간결 vs 상세
+// 주 판별: 커뮤니케이션 스타일
+const Q4_SCORES = {
+    A: { communication: +2 }, // 상세 설명 선호
+    B: { communication: 0 },
+    C: { communication: -2 }, // 간결 선호
+};
+// ── Pack 매핑 ──
+function qualityFromScore(score) {
+    if (score <= -2)
+        return '보수형';
+    if (score >= 2)
+        return '속도형';
+    return '균형형';
+}
+function autonomyFromScore(score) {
+    if (score <= -2)
+        return '확인 우선형';
+    if (score >= 2)
+        return '자율 실행형';
+    return '균형형';
+}
+function judgmentFromScore(score) {
+    if (score <= -1)
+        return '최소변경형';
+    if (score >= 1)
+        return '구조적접근형';
+    return '균형형';
+}
+function communicationFromScore(score) {
+    if (score <= -1)
+        return '간결형';
+    if (score >= 1)
+        return '상세형';
+    return '균형형';
+}
+// ── Confidence ──
+function computeConfidence(score, q1Contribution, q2Contribution) {
+    // contradiction: 2문항 기여 부호가 반대일 때
+    const contradictions = (q1Contribution > 0 && q2Contribution < 0) || (q1Contribution < 0 && q2Contribution > 0) ? 1 : 0;
+    const raw = 0.45 + (0.2 * Math.abs(score)) - (0.15 * contradictions);
+    return Math.max(0.2, Math.min(0.95, raw));
+}
+// ── Trust Policy 추천 ──
+const TRUST_MAP = {
+    '보수형+확인 우선형': '가드레일 우선',
+    '속도형+자율 실행형': '완전 신뢰 실행',
+};
+function suggestTrustPolicy(quality, autonomy) {
+    return TRUST_MAP[`${quality}+${autonomy}`] ?? '승인 완화';
+}
+export function computeOnboarding(q1, q2, q3 = 'B', q4 = 'B') {
+    const qualityScore = Q1_SCORES[q1].quality + Q2_SCORES[q2].quality;
+    const autonomyScore = Q1_SCORES[q1].autonomy + Q2_SCORES[q2].autonomy;
+    const judgmentScore = Q3_SCORES[q3].judgment;
+    const communicationScore = Q4_SCORES[q4].communication;
+    const qualityPack = qualityFromScore(qualityScore);
+    const autonomyPack = autonomyFromScore(autonomyScore);
+    const judgmentPack = judgmentFromScore(judgmentScore);
+    const communicationPack = communicationFromScore(communicationScore);
+    const qualityConfidence = computeConfidence(qualityScore, Q1_SCORES[q1].quality, Q2_SCORES[q2].quality);
+    const autonomyConfidence = computeConfidence(autonomyScore, Q1_SCORES[q1].autonomy, Q2_SCORES[q2].autonomy);
+    // Q3, Q4는 단일 질문이므로 confidence가 낮음
+    const judgmentConfidence = Math.max(0.2, Math.min(0.75, 0.35 + 0.2 * Math.abs(judgmentScore)));
+    const communicationConfidence = Math.max(0.2, Math.min(0.75, 0.35 + 0.2 * Math.abs(communicationScore)));
+    return {
+        qualityScore,
+        autonomyScore,
+        judgmentScore,
+        communicationScore,
+        qualityPack,
+        autonomyPack,
+        judgmentPack,
+        communicationPack,
+        qualityConfidence,
+        autonomyConfidence,
+        judgmentConfidence,
+        communicationConfidence,
+        suggestedTrustPolicy: suggestTrustPolicy(qualityPack, autonomyPack),
+    };
+}
+export function onboardingToRecommendation(result) {
+    const avgConfidence = (result.qualityConfidence + result.autonomyConfidence + result.judgmentConfidence + result.communicationConfidence) / 4;
+    return createRecommendation({
+        source: 'onboarding',
+        quality_pack: result.qualityPack,
+        autonomy_pack: result.autonomyPack,
+        judgment_pack: result.judgmentPack,
+        communication_pack: result.communicationPack,
+        suggested_trust_policy: result.suggestedTrustPolicy,
+        confidence: avgConfidence,
+        reason_summary: `온보딩 4문항 결과: quality=${result.qualityScore}, autonomy=${result.autonomyScore}, judgment=${result.judgmentScore}, communication=${result.communicationScore}`,
+    });
+}

package/dist/hooks/compound-reflection.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Forgen — Compound Reflection Logic
+ *
+ * Code Reflection의 false positive를 줄이기 위한 3중 필터:
+ *   1. 시간 윈도우: 솔루션 주입 후 15분 이내만 반영으로 인정
+ *   2. 매칭 비율: 유효 식별자의 50% 이상 매칭 필요
+ *   3. 공통 식별자 차단: 프레임워크 기본 용어는 매칭에서 제외
+ *
+ * ADR: 기존 pre-tool-use.ts의 checkCompoundReflection 인라인 로직을
+ * 별도 모듈로 분리. 이유: (1) 테스트 가능성 (순수 함수), (2) false
+ * positive 문제(action-plan §2.1)의 근본 수정에 명확한 책임 경계 필요.
+ */
+/** 주입 후 이 시간 내에 코드에 식별자가 출현해야 reflection으로 인정 */
+export declare const REFLECTION_WINDOW_MS: number;
+/**
+ * 프레임워크/라이브러리 기본 식별자 블록리스트.
+ * 이 식별자들은 솔루션 주입과 무관하게 코드에 자연 출현하므로
+ * reflection 매칭에서 제외한다.
+ *
+ * 기준: "이 단어가 코드에 있다고 해서 사용자가 forgen의 솔루션을
+ * 참고했다고 볼 수 없는 단어"
+ */
+export declare const COMMON_IDENTIFIERS: Set<string>;
+export interface ReflectionInput {
+    identifiers: string[];
+    code: string;
+    injectedAt: string;
+    now?: Date;
+}
+export interface ReflectionResult {
+    reflected: boolean;
+    matchedCount: number;
+    eligibleCount: number;
+    reason?: 'outside-window' | 'low-match-ratio' | 'no-eligible-identifiers' | 'code-too-short' | 'invalid-injection-time';
+}
+/**
+ * 솔루션의 식별자가 코드에 반영되었는지 판정한다 (순수 함수).
+ *
+ * 3중 필터:
+ *   1. 코드 최소 길이 (10자)
+ *   2. 시간 윈도우 (주입 후 15분)
+ *   3. 유효 식별자 필터링 (6자 이상 + 블록리스트 제외)
+ *   4. 매칭 비율 (유효 식별자의 50% 이상, 최소 1개)
+ */
+export declare function isReflectionCandidate(input: ReflectionInput): ReflectionResult;

package/dist/hooks/compound-reflection.js

@@ -0,0 +1,82 @@
+/**
+ * Forgen — Compound Reflection Logic
+ *
+ * Code Reflection의 false positive를 줄이기 위한 3중 필터:
+ *   1. 시간 윈도우: 솔루션 주입 후 15분 이내만 반영으로 인정
+ *   2. 매칭 비율: 유효 식별자의 50% 이상 매칭 필요
+ *   3. 공통 식별자 차단: 프레임워크 기본 용어는 매칭에서 제외
+ *
+ * ADR: 기존 pre-tool-use.ts의 checkCompoundReflection 인라인 로직을
+ * 별도 모듈로 분리. 이유: (1) 테스트 가능성 (순수 함수), (2) false
+ * positive 문제(action-plan §2.1)의 근본 수정에 명확한 책임 경계 필요.
+ */
+/** 주입 후 이 시간 내에 코드에 식별자가 출현해야 reflection으로 인정 */
+export const REFLECTION_WINDOW_MS = 15 * 60 * 1000; // 15분
+/**
+ * 프레임워크/라이브러리 기본 식별자 블록리스트.
+ * 이 식별자들은 솔루션 주입과 무관하게 코드에 자연 출현하므로
+ * reflection 매칭에서 제외한다.
+ *
+ * 기준: "이 단어가 코드에 있다고 해서 사용자가 forgen의 솔루션을
+ * 참고했다고 볼 수 없는 단어"
+ */
+export const COMMON_IDENTIFIERS = new Set([
+    // React
+    'useState', 'useEffect', 'useCallback', 'useReducer', 'useContext', 'useLayoutEffect',
+    'useImperativeHandle', 'useDebugValue', 'useDeferredValue', 'useTransition', 'useSyncExternalStore',
+    'useInsertionEffect', 'createElement', 'createContext', 'createRef', 'forwardRef',
+    'ErrorBoundary', 'Suspense', 'StrictMode', 'Fragment', 'Component',
+    // Next.js
+    'getServerSideProps', 'getStaticProps', 'getStaticPaths', 'NextRequest', 'NextResponse',
+    'useRouter', 'usePathname', 'useSearchParams',
+    // Node.js / common
+    'require', 'exports', 'module', 'process', 'console', 'setTimeout', 'setInterval',
+    'Promise', 'Buffer', 'EventEmitter',
+    // Testing
+    'describe', 'expect', 'beforeEach', 'afterEach', 'beforeAll', 'afterAll',
+    // TypeScript
+    'interface', 'implements', 'extends', 'abstract', 'readonly',
+    // Common methods/patterns
+    'toString', 'valueOf', 'constructor', 'prototype', 'hasOwnProperty',
+    'addEventListener', 'removeEventListener', 'querySelector', 'getElementById',
+    // Libraries
+    'express', 'mongoose', 'sequelize', 'prisma',
+]);
+/**
+ * 솔루션의 식별자가 코드에 반영되었는지 판정한다 (순수 함수).
+ *
+ * 3중 필터:
+ *   1. 코드 최소 길이 (10자)
+ *   2. 시간 윈도우 (주입 후 15분)
+ *   3. 유효 식별자 필터링 (6자 이상 + 블록리스트 제외)
+ *   4. 매칭 비율 (유효 식별자의 50% 이상, 최소 1개)
+ */
+export function isReflectionCandidate(input) {
+    const { identifiers, code, injectedAt } = input;
+    const now = input.now ?? new Date();
+    // Gate 1: 코드 최소 길이
+    if (!code || code.length < 10) {
+        return { reflected: false, matchedCount: 0, eligibleCount: 0, reason: 'code-too-short' };
+    }
+    // Gate 2: 주입 시각 유효성 + 시간 윈도우
+    const injectedTime = new Date(injectedAt).getTime();
+    if (Number.isNaN(injectedTime)) {
+        return { reflected: false, matchedCount: 0, eligibleCount: 0, reason: 'invalid-injection-time' };
+    }
+    const elapsed = now.getTime() - injectedTime;
+    if (elapsed > REFLECTION_WINDOW_MS || elapsed < 0) {
+        return { reflected: false, matchedCount: 0, eligibleCount: 0, reason: 'outside-window' };
+    }
+    // Gate 3: 유효 식별자 필터링
+    const eligible = identifiers.filter(id => id.length >= 6 && !COMMON_IDENTIFIERS.has(id));
+    if (eligible.length === 0) {
+        return { reflected: false, matchedCount: 0, eligibleCount: 0, reason: 'no-eligible-identifiers' };
+    }
+    // Gate 4: 매칭 비율 검사
+    const matchedCount = eligible.filter(id => code.includes(id)).length;
+    const minRequired = Math.max(1, Math.ceil(eligible.length * 0.5));
+    if (matchedCount < minRequired) {
+        return { reflected: false, matchedCount, eligibleCount: eligible.length, reason: 'low-match-ratio' };
+    }
+    return { reflected: true, matchedCount, eligibleCount: eligible.length };
+}

package/dist/hooks/context-guard.d.ts

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+/**
+ * Forgen — Context Guard Hook
+ *
+ * Claude Code Stop 훅으로 등록.
+ * context window limit, edit error 등 실행 중 에러를 감지하여
+ * 사용자에게 경고하고 상태를 보존합니다.
+ *
+ * 또한 UserPromptSubmit에서 현재 대화 길이를 추적하여
+ * context 한계에 접근 시 preemptive 경고를 제공합니다.
+ */
+/** 경고 표시 여부 판정 (순수 함수) */
+export declare function shouldWarn(contextPercent: {
+    promptCount: number;
+    totalChars: number;
+    lastWarningAt: number;
+}, thresholds?: {
+    promptThreshold?: number;
+    charsThreshold?: number;
+    cooldownMs?: number;
+}): boolean;
+/** 경고 메시지 생성 (순수 함수) */
+export declare function buildContextWarningMessage(promptCount: number, totalChars: number): string;
+export declare function main(): Promise<void>;

package/dist/hooks/context-guard.js

@@ -0,0 +1,156 @@
+#!/usr/bin/env node
+/**
+ * Forgen — Context Guard Hook
+ *
+ * Claude Code Stop 훅으로 등록.
+ * context window limit, edit error 등 실행 중 에러를 감지하여
+ * 사용자에게 경고하고 상태를 보존합니다.
+ *
+ * 또한 UserPromptSubmit에서 현재 대화 길이를 추적하여
+ * context 한계에 접근 시 preemptive 경고를 제공합니다.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createLogger } from '../core/logger.js';
+import { readStdinJSON } from './shared/read-stdin.js';
+import { atomicWriteJSON } from './shared/atomic-write.js';
+import { loadHookConfig, isHookEnabled } from './hook-config.js';
+import { approve, approveWithContext, approveWithWarning, failOpen } from './shared/hook-response.js';
+import { HANDOFFS_DIR, STATE_DIR } from '../core/paths.js';
+const log = createLogger('context-guard');
+const CONTEXT_STATE_PATH = path.join(STATE_DIR, 'context-guard.json');
+// 경고 임계값: 프롬프트 50회 또는 총 문자 수 200K 이상
+const PROMPT_WARNING_THRESHOLD = 50;
+const CHARS_WARNING_THRESHOLD = 200_000;
+const WARNING_COOLDOWN_MS = 10 * 60 * 1000; // 10분 쿨다운
+/** 경고 표시 여부 판정 (순수 함수) */
+export function shouldWarn(contextPercent, thresholds = {}) {
+    const promptThreshold = thresholds.promptThreshold ?? PROMPT_WARNING_THRESHOLD;
+    const charsThreshold = thresholds.charsThreshold ?? CHARS_WARNING_THRESHOLD;
+    const cooldownMs = thresholds.cooldownMs ?? WARNING_COOLDOWN_MS;
+    const now = Date.now();
+    return ((contextPercent.promptCount >= promptThreshold || contextPercent.totalChars >= charsThreshold) &&
+        (now - contextPercent.lastWarningAt > cooldownMs));
+}
+/** 경고 메시지 생성 (순수 함수) */
+export function buildContextWarningMessage(promptCount, totalChars) {
+    return `<compound-context-warning>\n[Forgen] Context limit approaching: ${promptCount} prompts, ${Math.round(totalChars / 1000)}K characters.\nIf you have important progress, save it now:\n- Use cancelforgen to reset mode state and start a new session\n- Or continue current work (auto compaction may occur)\n</compound-context-warning>`;
+}
+function loadContextState(sessionId) {
+    try {
+        if (fs.existsSync(CONTEXT_STATE_PATH)) {
+            const data = JSON.parse(fs.readFileSync(CONTEXT_STATE_PATH, 'utf-8'));
+            if (data.sessionId === sessionId)
+                return data;
+        }
+    }
+    catch (e) {
+        log.debug('context state 파일 읽기/파싱 실패', e);
+    }
+    return { promptCount: 0, totalChars: 0, lastWarningAt: 0, sessionId };
+}
+function saveContextState(state) {
+    atomicWriteJSON(CONTEXT_STATE_PATH, state);
+}
+export async function main() {
+    const input = await readStdinJSON();
+    if (!isHookEnabled('context-guard')) {
+        console.log(approve());
+        return;
+    }
+    if (!input) {
+        console.log(approve());
+        return;
+    }
+    const sessionId = input.session_id ?? 'default';
+    // Stop 훅: stop_hook_type이 있으면 처리
+    if (input.stop_hook_type) {
+        // 에러가 포함된 경우: context limit 감지
+        if (input.error) {
+            const errorMsg = input.error;
+            if (/context.*limit|token.*limit|conversation.*too.*long/i.test(errorMsg)) {
+                saveHandoff(sessionId, 'context-limit', errorMsg);
+                console.log(approveWithWarning(`[Forgen] Context limit reached. Current state has been saved to ~/.forgen/handoffs/.\nThe previous work will be automatically recovered in the next session.`));
+                return;
+            }
+        }
+        // 정상 종료 시: 의미 있는 세션이었으면 compound 안내
+        if (input.stop_hook_type === 'user' || input.stop_hook_type === 'end_turn') {
+            const state = loadContextState(sessionId);
+            if (state.promptCount >= 10) {
+                // 10 프롬프트 이상이면 의미 있는 세션 — compound 안내
+                console.log(approveWithWarning(`[Forgen] 이 세션에서 ${state.promptCount}개의 프롬프트를 처리했습니다. /compound 를 실행하면 이 세션의 학습 내용을 축적할 수 있습니다.`));
+                return;
+            }
+        }
+        console.log(approve());
+        return;
+    }
+    // error만 있는 경우 (stop_hook_type 없이)
+    if (input.error) {
+        console.log(approve());
+        return;
+    }
+    // UserPromptSubmit 훅: 대화 길이 추적
+    if (input.prompt) {
+        const config = loadHookConfig('context-guard');
+        // maxTokens가 설정되어 있으면 chars threshold로 사용 (토큰 ≈ 4자 기준 환산)
+        const charsThreshold = typeof config?.maxTokens === 'number' ? config.maxTokens * 4 : undefined;
+        const state = loadContextState(sessionId);
+        state.promptCount++;
+        state.totalChars += input.prompt.length;
+        if (shouldWarn(state, charsThreshold !== undefined ? { charsThreshold } : {})) {
+            state.lastWarningAt = Date.now();
+            saveContextState(state);
+            console.log(approveWithContext(buildContextWarningMessage(state.promptCount, state.totalChars), 'UserPromptSubmit'));
+            return;
+        }
+        saveContextState(state);
+    }
+    console.log(approve());
+}
+function saveHandoff(sessionId, reason, detail) {
+    fs.mkdirSync(HANDOFFS_DIR, { recursive: true });
+    const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+    const handoffPath = path.join(HANDOFFS_DIR, `${timestamp}-${reason}.md`);
+    // 활성 모드 상태 수집
+    const stateDir = STATE_DIR;
+    const activeStates = [];
+    if (fs.existsSync(stateDir)) {
+        for (const f of fs.readdirSync(stateDir)) {
+            if (f.endsWith('-state.json') && !f.startsWith('skill-cache-') && !f.startsWith('context-guard')) {
+                try {
+                    const data = JSON.parse(fs.readFileSync(path.join(stateDir, f), 'utf-8'));
+                    if (data.active) {
+                        activeStates.push(`- ${f.replace('-state.json', '')}: ${data.prompt ?? 'no prompt'}`);
+                    }
+                }
+                catch (e) {
+                    log.debug(`상태 파일 파싱 실패: ${f}`, e);
+                }
+            }
+        }
+    }
+    const content = [
+        `# Handoff: ${reason}`,
+        `- Session: ${sessionId}`,
+        `- Time: ${new Date().toISOString()}`,
+        `- Reason: ${detail}`,
+        '',
+        '## Active Modes',
+        activeStates.length > 0 ? activeStates.join('\n') : '- none',
+        '',
+        '## Recovery Instructions',
+        'Automatically recovered in the next session (session-recovery hook).',
+        'Manual recovery: Check the last state of the previous work and continue from there.',
+    ].join('\n');
+    fs.writeFileSync(handoffPath, content);
+}
+// ESM main guard: import 시 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(failOpen());
+    });
+}

package/dist/hooks/dangerous-patterns.json

@@ -0,0 +1,18 @@
+[
+  { "pattern": "rm\\s+(-rf|-fr)\\s+[/~]", "description": "rm -rf on root/home path", "severity": "block" },
+  { "pattern": "rm\\s+(-rf|-fr)\\s+\\.\\s", "description": "rm -rf on current directory", "severity": "block" },
+  { "pattern": "git\\s+push\\s+.*--force(?!-)", "description": "git push --force", "severity": "warn" },
+  { "pattern": "git\\s+reset\\s+--hard", "description": "git reset --hard", "severity": "warn" },
+  { "pattern": "git\\s+clean\\s+-[a-z]*f", "description": "git clean -f", "severity": "warn" },
+  { "pattern": "drop\\s+(?:table|database)", "description": "DROP TABLE/DATABASE", "severity": "block", "flags": "i" },
+  { "pattern": "truncate\\s+table", "description": "TRUNCATE TABLE", "severity": "warn", "flags": "i" },
+  { "pattern": ">\\s*\\/dev\\/sd[a-z]", "description": "write to block device", "severity": "block" },
+  { "pattern": "mkfs\\s", "description": "mkfs (format filesystem)", "severity": "block" },
+  { "pattern": ":\\(\\)\\s*\\{\\s*:\\|:&\\s*\\}\\s*;:", "description": "fork bomb", "severity": "block" },
+  { "pattern": "\\beval\\s+[\"'`]", "description": "eval with string (injection risk)", "severity": "warn" },
+  { "pattern": "curl\\s+.*\\|\\s*(ba)?sh", "description": "curl pipe to shell", "severity": "block" },
+  { "pattern": "wget\\s+.*\\|\\s*(ba)?sh", "description": "wget pipe to shell", "severity": "block" },
+  { "pattern": "python[23]?\\s+-c\\s+['\"].*(?:import\\s+os|subprocess|exec|eval)", "description": "python -c with dangerous imports", "severity": "warn" },
+  { "pattern": "\\bchmod\\s+[0-7]*777\\b", "description": "chmod 777 (overly permissive)", "severity": "warn" },
+  { "pattern": "\\bdd\\s+.*of=\\/dev\\/", "description": "dd write to device", "severity": "block" }
+]