@wooojin/forgen 0.3.2 → 0.4.0

package/dist/store/rule-lifecycle.js

@@ -0,0 +1,63 @@
+/**
+ * Rule lifecycle factory + helpers — single source of truth for defaults/normalization.
+ *
+ * R6-F1 (2026-04-22): 이전에는 `rule.lifecycle ?? { phase: 'active', inject_count: 0, ... }`
+ * 리터럴이 rule-store, orchestrator, meta-reclassifier 등 5곳에 복제되어 필드 추가 시 동시
+ * 수정 필수였다. 한 곳에서 불변식을 걸고 모든 호출자가 이 함수를 통해 lifecycle 을 얻도록 통합.
+ *
+ * root-cause-analyst (R6) 분석: "Rule 이 data file + state machine 이중 정체성을 가지면서
+ * 기본값 재합성이 N 군데에 분산" 이 R4-B2(음수 corruption)/R5-B1(orphan)/R5-B2(mutex)/api-H1
+ * 등 버그 클러스터의 공통 뿌리. 이 factory 가 그 뿌리를 차단.
+ */
+/** safe non-negative integer normalization — 파일 corruption / 다중 writer race 방어. */
+export function safeCount(n) {
+    return typeof n === 'number' && Number.isFinite(n) && n >= 0 ? n : 0;
+}
+/**
+ * Rule 에 대해 정규화된 LifecycleState 반환 (pure — rule 을 변경하지 않음).
+ * 기존 lifecycle 이 있으면 카운터를 safeCount 로 정규화한 사본, 없으면 초기 상태.
+ */
+export function initLifecycle(rule) {
+    const existing = rule.lifecycle;
+    if (existing) {
+        return {
+            phase: existing.phase,
+            first_active_at: existing.first_active_at,
+            last_inject_at: existing.last_inject_at,
+            last_violation_at: existing.last_violation_at,
+            inject_count: safeCount(existing.inject_count),
+            accept_count: safeCount(existing.accept_count),
+            violation_count: safeCount(existing.violation_count),
+            bypass_count: safeCount(existing.bypass_count),
+            conflict_refs: Array.isArray(existing.conflict_refs) ? [...existing.conflict_refs] : [],
+            merged_into: existing.merged_into,
+            superseded_by: existing.superseded_by,
+            meta_promotions: Array.isArray(existing.meta_promotions) ? [...existing.meta_promotions] : [],
+        };
+    }
+    return {
+        phase: 'active',
+        first_active_at: rule.created_at,
+        inject_count: 0,
+        accept_count: 0,
+        violation_count: 0,
+        bypass_count: 0,
+        conflict_refs: [],
+        meta_promotions: [],
+    };
+}
+/** inject count + last_inject_at 을 한 단계 증가 — markRulesInjected 의 공통 로직. */
+export function bumpInject(lifecycle, nowIso) {
+    return {
+        ...lifecycle,
+        inject_count: lifecycle.inject_count + 1,
+        last_inject_at: nowIso,
+    };
+}
+/** meta_promotions 에 새 entry append (immutable). */
+export function appendMetaPromotion(lifecycle, promotion) {
+    return {
+        ...lifecycle,
+        meta_promotions: [...lifecycle.meta_promotions, promotion],
+    };
+}

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

@@ -16,9 +16,30 @@ export declare function createRule(params: {
     render_key: string;
 }): Rule;
 export declare function saveRule(rule: Rule): void;
+/**
+ * ADR-002 T5 — rule 저장 + 기존 active rules 와 자연어 충돌 감지 + 양쪽 conflict_refs 기록.
+ *
+ * saveRule 과의 차이:
+ *   - 저장 직후 T5 detect 실행 → 충돌 발견 시 신규 rule + 반대편 rule 모두 conflict_refs 업데이트.
+ *   - auto-merge 안 함 (ADR-002 §Risks — 사용자 수동 해소).
+ *   - T5 감지 실패는 저장 자체를 막지 않음 (fail-open).
+ *
+ * 반환: 저장된 rule + 감지된 충돌 rule_id 목록.
+ */
+export declare function appendRule(rule: Rule): Promise<{
+    saved: true;
+    conflicts_with: string[];
+}>;
 export declare function loadRule(ruleId: string): Rule | null;
 export declare function loadAllRules(): Rule[];
 export declare function loadActiveRules(): Rule[];
+/**
+ * ADR-002 Meta signal — rule 들이 프롬프트에 inject 되었음을 기록.
+ * rule.lifecycle.inject_count +1, last_inject_at = now.
+ * lifecycle 없던 rule 은 auto-init 하고 phase='active'.
+ * Meta promotion (B→A) 의 rolling window 집계가 이 카운터를 소비한다.
+ */
+export declare function markRulesInjected(ruleIds: string[], nowIso?: string): void;
 export declare function updateRuleStatus(ruleId: string, status: RuleStatus): boolean;
 /**
  * 현재 세션 ID와 다른 scope:'session' 규칙을 비활성화.

package/dist/store/rule-store.js

@@ -9,6 +9,8 @@ import * as path from 'node:path';
 import * as crypto from 'node:crypto';
 import { ME_RULES } from '../core/paths.js';
 import { atomicWriteJSON, safeReadJSON } from '../hooks/shared/atomic-write.js';
+import { CURRENT_RULE_SCHEMA_VERSION } from './types.js';
+import { initLifecycle, bumpInject } from './rule-lifecycle.js';
 function rulePath(ruleId) {
     return path.join(ME_RULES, `${ruleId}.json`);
 }
@@ -33,25 +35,143 @@ export function saveRule(rule) {
     rule.updated_at = new Date().toISOString();
     atomicWriteJSON(rulePath(rule.rule_id), rule, { pretty: true });
 }
+/**
+ * ADR-002 T5 — rule 저장 + 기존 active rules 와 자연어 충돌 감지 + 양쪽 conflict_refs 기록.
+ *
+ * saveRule 과의 차이:
+ *   - 저장 직후 T5 detect 실행 → 충돌 발견 시 신규 rule + 반대편 rule 모두 conflict_refs 업데이트.
+ *   - auto-merge 안 함 (ADR-002 §Risks — 사용자 수동 해소).
+ *   - T5 감지 실패는 저장 자체를 막지 않음 (fail-open).
+ *
+ * 반환: 저장된 rule + 감지된 충돌 rule_id 목록.
+ */
+export async function appendRule(rule) {
+    saveRule(rule);
+    try {
+        const [{ detect: detectT5 }, { appendLifecycleEvents }] = await Promise.all([
+            import('../engine/lifecycle/trigger-t5-conflict.js'),
+            import('../engine/lifecycle/meta-reclassifier.js'),
+        ]);
+        const all = loadAllRules();
+        const events = detectT5({ rules: all });
+        const relevant = events.filter((e) => e.evidence?.refs?.includes(rule.rule_id));
+        if (relevant.length === 0)
+            return { saved: true, conflicts_with: [] };
+        // conflict_refs 양방향 업데이트
+        const affected = new Set();
+        for (const ev of relevant)
+            affected.add(ev.rule_id);
+        for (const id of affected) {
+            const target = all.find((r) => r.rule_id === id);
+            if (!target)
+                continue;
+            const refs = relevant
+                .filter((ev) => ev.rule_id === id)
+                .flatMap((ev) => (ev.evidence?.refs ?? []).filter((r) => r !== id));
+            const currentConflicts = target.lifecycle?.conflict_refs ?? [];
+            const merged = [...new Set([...currentConflicts, ...refs])];
+            const lifecycle = target.lifecycle ?? {
+                phase: 'active',
+                first_active_at: target.created_at,
+                inject_count: 0, accept_count: 0, violation_count: 0, bypass_count: 0,
+                conflict_refs: [], meta_promotions: [],
+            };
+            saveRule({ ...target, lifecycle: { ...lifecycle, conflict_refs: merged } });
+        }
+        appendLifecycleEvents(relevant);
+        const conflicts_with = [
+            ...new Set(relevant
+                .filter((e) => e.rule_id === rule.rule_id)
+                .flatMap((e) => (e.evidence?.refs ?? []).filter((r) => r !== rule.rule_id))),
+        ];
+        return { saved: true, conflicts_with };
+    }
+    catch {
+        return { saved: true, conflicts_with: [] };
+    }
+}
 export function loadRule(ruleId) {
     return safeReadJSON(rulePath(ruleId), null);
 }
 export function loadAllRules() {
-    if (!fs.existsSync(ME_RULES))
-        return [];
     const rules = [];
-    for (const file of fs.readdirSync(ME_RULES)) {
-        if (!file.endsWith('.json'))
-            continue;
-        const rule = safeReadJSON(path.join(ME_RULES, file), null);
-        if (rule)
-            rules.push(rule);
+    // 1) 사용자 개인 rules: ~/.forgen/me/rules
+    if (fs.existsSync(ME_RULES)) {
+        for (const file of fs.readdirSync(ME_RULES)) {
+            if (!file.endsWith('.json'))
+                continue;
+            const rule = safeReadJSON(path.join(ME_RULES, file), null);
+            if (rule && isCompatibleSchema(rule, file))
+                rules.push(rule);
+        }
+    }
+    // 2) 프로젝트 로컬 rules: <cwd>/.forgen/rules
+    // ADR-003 Phase 1 Dogfood — 팀/프로젝트가 git 에 committed 한 L1 정책을 자동 로드.
+    // 같은 rule_id 가 me 와 project 양쪽에 있으면 project 가 우선 (git 소스가 정책 진실).
+    const projectRulesDir = resolveProjectRulesDir();
+    if (projectRulesDir && fs.existsSync(projectRulesDir)) {
+        for (const file of fs.readdirSync(projectRulesDir)) {
+            if (!file.endsWith('.json'))
+                continue;
+            const rule = safeReadJSON(path.join(projectRulesDir, file), null);
+            if (!rule || !isCompatibleSchema(rule, file))
+                continue;
+            const existingIdx = rules.findIndex((r) => r.rule_id === rule.rule_id);
+            if (existingIdx >= 0)
+                rules[existingIdx] = rule; // project override
+            else
+                rules.push(rule);
+        }
     }
     return rules;
 }
+/**
+ * R5-B3: schema_version 호환성 체크.
+ * - undefined / 0 / CURRENT_RULE_SCHEMA_VERSION: OK
+ * - > CURRENT: 상위 버전 → graceful skip (downgrade 시 silent corruption 방지)
+ */
+function isCompatibleSchema(rule, filename) {
+    const v = rule.schema_version;
+    if (v == null || v <= CURRENT_RULE_SCHEMA_VERSION)
+        return true;
+    if (process.env.FORGEN_DEBUG_SIGNALS === '1') {
+        process.stderr.write(`[forgen:rule-store] ${filename} schema_version=${v} > supported ${CURRENT_RULE_SCHEMA_VERSION} — skipped\n`);
+    }
+    return false;
+}
+/**
+ * 현재 프로젝트 cwd 의 `.forgen/rules/` 경로. FORGEN_CWD/COMPOUND_CWD 우선.
+ * 테스트 / CI 에서 프로젝트 스코프 로딩을 비활성화하려면 FORGEN_DISABLE_PROJECT_RULES=1.
+ */
+function resolveProjectRulesDir() {
+    if (process.env.FORGEN_DISABLE_PROJECT_RULES === '1')
+        return null;
+    const cwd = process.env.FORGEN_CWD ?? process.env.COMPOUND_CWD ?? process.cwd();
+    return path.join(cwd, '.forgen', 'rules');
+}
 export function loadActiveRules() {
     return loadAllRules().filter(r => r.status === 'active');
 }
+/**
+ * ADR-002 Meta signal — rule 들이 프롬프트에 inject 되었음을 기록.
+ * rule.lifecycle.inject_count +1, last_inject_at = now.
+ * lifecycle 없던 rule 은 auto-init 하고 phase='active'.
+ * Meta promotion (B→A) 의 rolling window 집계가 이 카운터를 소비한다.
+ */
+export function markRulesInjected(ruleIds, nowIso = new Date().toISOString()) {
+    for (const id of ruleIds) {
+        const rule = loadRule(id);
+        if (!rule)
+            continue;
+        // R6-F1: initLifecycle 이 정규화(카운터 ≥0, 배열 보장) 까지 포함.
+        const lifecycle = initLifecycle(rule);
+        const updated = {
+            ...rule,
+            lifecycle: bumpInject(lifecycle, nowIso),
+        };
+        atomicWriteJSON(rulePath(rule.rule_id), updated, { pretty: true });
+    }
+}
 export function updateRuleStatus(ruleId, status) {
     const rule = loadRule(ruleId);
     if (!rule)

package/dist/store/types.d.ts

@@ -14,7 +14,79 @@ export type RuleScope = 'me' | 'session';
 export type RuleStrength = 'soft' | 'default' | 'strong' | 'hard';
 export type RuleSource = 'onboarding' | 'explicit_correction' | 'behavior_inference' | 'pack_overlay';
 export type RuleStatus = 'active' | 'suppressed' | 'removed' | 'superseded';
+export type EnforcementMech = 'A' | 'B' | 'C';
+export type HookPoint = 'PreToolUse' | 'PostToolUse' | 'Stop' | 'UserPromptSubmit';
+export type VerifierKind = 'file_exists' | 'pattern_match' | 'tool_arg_regex' | 'artifact_check' | 'self_check_prompt';
+export interface VerifierSpec {
+    kind: VerifierKind;
+    /** 각 kind 별로 의미가 다름 — 예: self_check_prompt 는 `question`, artifact_check 는 `path`+`max_age_s`. */
+    params: Record<string, string | number | boolean>;
+}
+export interface EnforceSpec {
+    mech: EnforcementMech;
+    hook: HookPoint;
+    /** Mech-A/B 에서 필수, Mech-C 에서는 미사용. */
+    verifier?: VerifierSpec;
+    /** Mech-A BLOCK / Mech-B self-check 시 Claude 에게 전달할 reason. */
+    block_message?: string;
+    /** Mech-C drift-score.ts 키 — 정량 판정 불가 규칙의 장기 누적 편향 축. */
+    drift_key?: string;
+    /**
+     * Stop hook 전용: 어시스턴트 응답 텍스트에서 이 규칙을 발화시킬 정규식.
+     * 미지정 시 shared default (완료 선언 키워드 regex) 사용.
+     */
+    trigger_keywords_regex?: string;
+    /**
+     * Stop hook 전용: trigger 가 매칭되더라도 이 regex 가 매칭되면 발화 안 함.
+     * retraction/meta/테스트-맥락 등 false-positive 컨텍스트 차단용.
+     */
+    trigger_exclude_regex?: string;
+    /**
+     * UI 표시용 한 줄 태그 (Stop hook 의 `systemMessage` 로 전달).
+     * 예: "rule:R-B1 — e2e-before-done"
+     */
+    system_tag?: string;
+}
+export type LifecyclePhase = 'active' | 'flagged' | 'suppressed' | 'retired' | 'merged' | 'superseded';
+export interface MetaPromotion {
+    at: string;
+    from_mech: EnforcementMech;
+    to_mech: EnforcementMech;
+    reason: 'consistent_adherence' | 'repeated_violation' | 'user_override' | 'stuck_loop_force_approve';
+    trigger_stats: {
+        window_n: number;
+        adherence_rate?: number;
+        violation_count?: number;
+    };
+}
+export interface LifecycleState {
+    phase: LifecyclePhase;
+    first_active_at: string;
+    last_inject_at?: string;
+    last_violation_at?: string;
+    inject_count: number;
+    accept_count: number;
+    violation_count: number;
+    /** T3: 사용자가 rule 과 반대로 행동한 횟수 */
+    bypass_count: number;
+    /** T5: 충돌하는 rule_id 목록 */
+    conflict_refs: string[];
+    /** T5: 이 rule 이 흡수된 대상 rule_id */
+    merged_into?: string;
+    /** T1: 이 rule 을 교체한 rule_id */
+    superseded_by?: string;
+    /** Meta: mech 변경 이력 */
+    meta_promotions: MetaPromotion[];
+}
+/**
+ * Rule JSON schema version. v0.4.0 introduces `enforce_via` + `lifecycle` — 이들을
+ * 포함하는 schema 의 공식 버전은 1. 누락된 rule 파일은 pre-v0.4.0 으로 취급 (optional fields
+ * 만 비어있을 뿐 로드 가능). 미래 breaking change 시 이 값을 증가시키고 `migrate()` 체인으로 흡수.
+ */
+export declare const CURRENT_RULE_SCHEMA_VERSION = 1;
 export interface Rule {
+    /** R5-B3: 미래 breaking schema change 를 위한 version 필드. 없으면 v0 (pre-0.4.0) 으로 취급. */
+    schema_version?: number;
     rule_id: string;
     category: RuleCategory;
     scope: RuleScope;
@@ -27,6 +99,17 @@ export interface Rule {
     render_key: string;
     created_at: string;
     updated_at: string;
+    /**
+     * 이 rule 이 어떤 hook/verifier 로 강제되는가. optional — 기존 rule 은 null.
+     * `forgen classify-enforce` 명령이 기존 rule 을 자동 분류하여 채운다.
+     * ADR-001 §Data Model.
+     */
+    enforce_via?: EnforceSpec[];
+    /**
+     * Lifecycle 상태. optional — 기존 rule 은 load 시 phase='active' 로 auto-initialize.
+     * ADR-002 §Data Model.
+     */
+    lifecycle?: LifecycleState;
 }
 export type EvidenceType = 'explicit_correction' | 'behavior_observation' | 'session_summary';
 export interface Evidence {

package/dist/store/types.js

@@ -4,4 +4,10 @@
  * Authoritative source: docs/plans/2026-04-03-forgen-data-model-storage-spec.md
  * Runtime contracts: docs/plans/2026-04-03-forgen-component-interface-design.md
  */
-export {};
+// ── Rule ────────────────────────────────────────────────────────────────────
+/**
+ * Rule JSON schema version. v0.4.0 introduces `enforce_via` + `lifecycle` — 이들을
+ * 포함하는 schema 의 공식 버전은 1. 누락된 rule 파일은 pre-v0.4.0 으로 취급 (optional fields
+ * 만 비어있을 뿐 로드 가능). 미래 breaking change 시 이 값을 증가시키고 `migrate()` 체인으로 흡수.
+ */
+export const CURRENT_RULE_SCHEMA_VERSION = 1;

package/hooks/hook-registry.json

@@ -5,6 +5,7 @@
   { "name": "post-tool-use",          "tier": "compound-core", "event": "PostToolUse",        "matcher": "*",          "script": "hooks/post-tool-use.js",          "timeout": 3, "compoundCritical": true  },
   { "name": "pre-compact",            "tier": "compound-core", "event": "PreCompact",         "matcher": "*",          "script": "hooks/pre-compact.js",            "timeout": 3, "compoundCritical": false },
   { "name": "context-guard-stop",     "tier": "compound-core", "event": "Stop",               "matcher": "*",          "script": "hooks/context-guard.js",          "timeout": 5, "compoundCritical": false },
+  { "name": "stop-guard",             "tier": "compound-core", "event": "Stop",               "matcher": "*",          "script": "hooks/stop-guard.js",             "timeout": 10, "compoundCritical": true  },
   { "name": "pre-tool-use",           "tier": "compound-core", "event": "PreToolUse",         "matcher": "*",          "script": "hooks/pre-tool-use.js",           "timeout": 3, "compoundCritical": true  },
   { "name": "secret-filter",          "tier": "safety",        "event": "PostToolUse",        "matcher": "Write|Edit|Bash", "script": "hooks/secret-filter.js",     "timeout": 3, "compoundCritical": false },
   { "name": "slop-detector",          "tier": "safety",        "event": "PostToolUse",        "matcher": "Write|Edit",      "script": "hooks/slop-detector.js",     "timeout": 3, "compoundCritical": false },

package/hooks/hooks.json

@@ -1,5 +1,5 @@
 {
-  "description": "Forgen harness hooks (auto-generated, 19/19 active)",
+  "description": "Forgen harness hooks (auto-generated, 20/20 active)",
   "hooks": {
     "UserPromptSubmit": [
       {
@@ -102,6 +102,11 @@
             "type": "command",
             "command": "node \"${CLAUDE_PLUGIN_ROOT}/dist/hooks/context-guard.js\"",
             "timeout": 5
+          },
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/dist/hooks/stop-guard.js\"",
+            "timeout": 10
           }
         ]
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wooojin/forgen",
-  "version": "0.3.2",
+  "version": "0.4.0",
   "preferGlobal": true,
   "main": "dist/lib.js",
   "types": "./dist/lib.d.ts",
@@ -34,7 +34,7 @@
   },
   "author": "jang-ujin",
   "license": "MIT",
-  "description": "Code, forged for you — personalized Claude Code harness",
+  "description": "When Claude says 'done', forgen makes it prove it — turn-level self-verification + personalized rules, at $0 extra API cost.",
   "keywords": [
     "claude-code",
     "forgen",
@@ -86,5 +86,13 @@
     "@modelcontextprotocol/sdk": "^1.28.0",
     "js-yaml": "^4.1.1",
     "zod": "^4.3.6"
+  },
+  "peerDependencies": {
+    "@anthropic-ai/claude-code": ">=2.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@anthropic-ai/claude-code": {
+      "optional": true
+    }
   }
 }

package/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://claude.ai/schemas/claude-plugin.json",
   "name": "forgen",
-  "version": "0.3.2",
+  "version": "0.4.0",
   "description": "Claude Code harness — the more you use Claude, the better it gets",
   "author": {
     "name": "jang-ujin",