@wooojin/forgen 0.3.2 → 0.4.1

package/.claude-plugin/plugin.json

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

package/CHANGELOG.md

@@ -5,6 +5,100 @@ All notable changes to forgen will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.4.1] - 2026-04-24
+
+### v0.4.1 — 하네스가 당신을 담고 간다
+
+v0.4.0 이 Trust Layer (Claude 가 "완료"라고 하면 forgen 이 증명하게 한다) 를 세웠다면, v0.4.1 은 **구매자가 첫 block 을 즉시 경험**하고 **README 만 봐도 "하네스가 당신을 담고 간다" 는 비전을 이해**하게 만드는 릴리스. 내부적으로는 직전 회차에서 scope-out 했던 측정 갭 3건을 정직하게 재평가 → 실제로 닫았고, 10 시나리오 실 Claude signal 누적으로 검증.
+
+**3개 구조적 갭 마감** (`feat`)
+- `recall_referenced` 측정: name literal 단일 매칭 → identifier / 복합 태그 2개 교차 fallback 추가. Claude 가 slug 이름 대신 solution content 만 인용해도 잡힘. 일반 단어 단독은 false-positive 방지 위해 제외.
+- `Rule.lifecycle` 자동 초기화: `saveRule` 이 lifecycle 없으면 `phase='active'` + counters=0 주입. suppressed rule 의 audit trail (누가 언제 왜) 추적 가능.
+- `forgen compound list` 출력: `inj: / ref: / neg:` 컬럼에 "ref 측정은 v0.4.1+ 부터 시작됨" 주석. legacy 데이터 `ref:0` 을 "도움 안 됨" 으로 오독하는 혼란 해소.
+
+**README 리프레시** (`docs`)
+- **The harness carries you 섹션 신설**: "대화 → 추출 → 주입 → 반복" cycle + `forgen compound export/import` (개인 철학 번들을 tar.gz 로 이식) 연결. forgen 을 "rule 주입 tool" 로 축소 해석하는 오독 해소.
+- 한국어/일본어/중국어 README 동기화 ("하네스가 당신을 담고 간다" / "ハーネスがあなたを運ぶ" / "这个 harness 装载的是你").
+- **The first block 데모 일반화**: forgen-repo 전용 L1 rule → v0.4.1 내장 `builtin:self-score-inflation` (TEST-2) 기반 일반 시나리오로 교체. 구매자가 rule 작성 없이도 첫 block 을 바로 체감.
+- Commands 섹션에 `forgen recall` / `forgen migrate` / `forgen init` 추가.
+- Cold-start boost 설명: champion/active 솔루션 < 5 이면 `MIN_INJECT_RELEVANCE` 0.3 → 0.2 완화.
+
+**natural-accumulation e2e** (`test`)
+- 격리 `FORGEN_HOME` + 실 Claude API 10 시나리오로 "시간이 답" 이던 open signal 4종을 수십 분 내 실증:
+  - `recall_referenced` 0 → 2 (33% 참조율)
+  - `recommendation_surfaced` 1 → 6 (60% 주입률, cold-start boost 실효 확인)
+  - TEST-2 자연 block 0 → 3
+  - TEST-3 자연 block 0 → 2
+  - hook-errors 0 (전 경로 clean)
+
+**회귀**: vitest 2114/2114 (신규 테스트 4건 포함). typecheck 0.
+
+---
+
+## [0.4.0] - 2026-04-23
+
+### v0.4.0 — The Trust Layer
+
+**When Claude says "done", forgen makes it prove it.** v0.4.0 adds turn-level self-verification at the Stop hook: Claude's completion claims get checked against rules you define, and blocks are fed back as `reason` that Claude reads and complies with on the next turn — **zero extra API calls**. Verified end-to-end on 10 scenarios at $1.74 total ([A1 spike report](docs/spike/mech-b-a1-verification-report.md)).
+
+Built on top of the v0.3.x personalization core (4-axis profile + compound knowledge + rule rendering): the Trust Layer = 3-axis enforcement (Mech-A/B/C) + rule lifecycle (T1-T5 + Meta) + release self-gate. Interview rounds 9~10 mission "forgen 이 자기 규칙을 forgen 자신에게 강제 적용" achieved — this repo's own development was stopped mid-commit by its own L1 rule when the maintainer claimed "완결" without running Docker e2e (evidence preserved in `.forgen/state/enforcement/violations.jsonl`).
+
+**ADR-001 — Mech-A/B/C 3축 강제 메커니즘** (Accepted)
+- Mech-A (hook-BLOCK): 기계 판정 가능 규칙 — PreToolUse deny / Stop artifact_check.
+- Mech-B (self-check prompt-inject): 자연어 판정 규칙 — Stop hook `decision:"block"` + `reason` 으로 Claude 자가점검 강제. **β1 ($0): 외부 LLM 호출 없음.**
+- Mech-C (drift-measure): 정량 판정 불가 규칙 — 장기 편향만 측정.
+- A1 검증 스파이크 10/10 PASS ($1.74, 3분): block 수용률 1.00, FP 0.00, hook p95 7ms, 추가 API 0.
+
+**신규 타입** (`src/store/types.ts`):
+- `EnforcementMech`, `HookPoint`, `VerifierSpec`, `EnforceSpec` — `Rule.enforce_via` 에 붙음 (optional, 기존 rule 하위 호환).
+- `EnforceSpec.trigger_keywords_regex` / `trigger_exclude_regex` / `system_tag` — Stop hook 전용 발화 조건.
+- `LifecyclePhase`, `LifecycleState`, `MetaPromotion` — `Rule.lifecycle` 에 붙음.
+
+**신규 Hook**:
+- `src/hooks/stop-guard.ts` — Stop hook. Production `rulesFromStore(loadActiveRules())` 로드, spike scenarios.json fallback. `last_assistant_message` 직접 read. stuck-loop guard (threshold 3 초과 시 force approve + drift 이벤트). `compoundCritical: true` (보호 hook).
+- `src/hooks/shared/hook-response.ts::blockStop(reason, systemMessage?)` helper.
+
+**ADR-002 — Rule Lifecycle Engine** (Accepted)
+- T1 explicit_correction: `evidence-store.appendEvidence` → `detectT1` → rule retire/supersede/flag. axis + render_key 이중 매칭으로 FP 차단.
+- T2 repeated_violation: 30d rolling window `violations_30d ≥ 3 AND rate > 0.3` → flag. 데이터 소스: `~/.forgen/state/enforcement/violations.jsonl` (stop-guard block 시 자동 append).
+- T3 user_bypass: `post-tool-use` 에서 `bypass-detector.scanForBypass` → `recordBypass`. 7d `bypass_count ≥ 5` → suppress.
+- T4 time_decay: `state-gc.runDailyT4Decay` — `forgen doctor --prune-state` 실행 시 90d 미주입 rule retire (별도 scheduler 없음; 사용자가 명시적으로 실행).
+- T5 conflict_detected: `rule-store.appendRule` 에서 T5 감지, 양쪽 `conflict_refs` 기록.
+- Meta 양방향: drift.jsonl 누적 → 강등 (A→B→C); rolling 20 injects + 0 violations → 승급 (B→A, C→B).
+- Orchestrator `applyEvent` / `foldEvents` pure — rule 파일 쓰기는 호출자 책임.
+- `src/store/rule-store.ts::markRulesInjected` — `v1-bootstrap` 이 renderRules 후 호출해 Meta 롤링 카운터를 채움.
+
+**ADR-003 — Release Self-Gate** (Accepted)
+- `.github/workflows/self-gate.yml` — push main / PR main / tag v* 에서 3-stage 검증.
+- `scripts/self-gate.cjs` — 정적 스캔: mock-in-production, secrets-leak (AWS 공식 EXAMPLE fixture allow list), enforce_via-missing, release-artifact.
+- `scripts/self-gate-runtime.cjs` — 6 hook 시나리오 smoke (완료 선언 block / retraction approve / shipped block / mock-context approve 등). 격리 HOME.
+- `scripts/self-gate-release.cjs` — tag-only: version/tag match, CHANGELOG section, dist freshness, .forgen-release/e2e-report.json.
+
+**신규 CLI**:
+- `forgen rule <list|suppress|activate|scan|health-scan|classify>` — 규칙 관리 네임스페이스. 기존 플랫 커맨드(suppress-rule, activate-rule, lifecycle-scan, rule-meta-scan, classify-enforce)는 하위 호환 alias 로 유지.
+- `forgen stats` — 한 화면 대시보드 (active rules, corrections, blocks/bypass/drift 7d, retired 7d, last extraction). 기존 jsonl 집계; 신규 telemetry 없음.
+- `forgen inspect corrections` — `forgen inspect evidence` 의 사용자 친화 이름. evidence 는 alias 로 유지.
+- `forgen last-block` — 가장 최근 block 이벤트 상세.
+
+**내부 CLI (하위 호환, alias 로 유지)**:
+- `forgen classify-enforce [--apply] [--force]` → `forgen rule classify`.
+- `forgen rule-meta-scan [--apply]` → `forgen rule health-scan`.
+- `forgen lifecycle-scan [--apply]` → `forgen rule scan`.
+
+**Upgrade notes (v0.3.x → v0.4.0)**:
+- 첫 `forgen` 실행 시 기존 rule 파일 (`~/.forgen/me/rules/*.json`) 에 `lifecycle` 블록이 자동 주입됩니다 (inject_count, phase='active' 등). 기존 필드는 보존됨.
+- 프로젝트 로컬 `.forgen/rules/*.json` 이 자동 로드됩니다 (runtime 병합). 팀 dogfood 경로. 테스트/격리 필요 시 `FORGEN_DISABLE_PROJECT_RULES=1`.
+- `FORGEN_USER_CONFIRMED=1` 으로 Mech-A PreToolUse 우회 시 violations.jsonl 에 `kind:'correction'` audit 엔트리 기록.
+
+**운영 지표**:
+- 전체 회귀 1973/1973 pass (169 files), TypeScript clean.
+- forgen doctor 20/20 hooks active; legacy `~/.forgen/rules/` orphan 감지 추가.
+- Self-gate 정적 ✓ + 런타임 7/7 (SG-ACK round-trip 포함); Docker e2e 77/77 (Phase 9 R9 전체 검증).
+- `npm pack` tarball 539.3 kB, 332 파일, v0.4.0 메타데이터 확인.
+
+**관측성**:
+- `acknowledgments.jsonl` 신규 — Mech-B block → retract → pass 루프가 실제 작동한 세션 기록. `forgen stats` 의 `X% acknowledged` 라벨로 집계.
+
 ## [0.3.2] - 2026-04-21
 
 ### Security — Audit findings landed

package/README.ja.md

@@ -3,18 +3,19 @@
 </p>
 
 <p align="center">
-  <strong>Claude Code パーソナライゼーション ハーネス。</strong><br/>
-  <strong>使えば使うほど、あなたを理解する Claude。</strong>
+  <strong>Claude が「完了しました」と言ったら、forgen がそれを証明させる。</strong><br/>
+  ターンレベルの自己検証 + パーソナライズドルール、<strong>追加 API コスト $0</strong>。
 </p>
 
 <p align="center">
-  <a href="https://www.npmjs.com/package//forgen"><img src="https://img.shields.io/npm/v//forgen.svg" alt="npm version"/></a>
+  <a href="https://www.npmjs.com/package/@wooojin/forgen"><img src="https://img.shields.io/npm/v/@wooojin/forgen.svg" alt="npm version"/></a>
   <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT"/></a>
   <a href="https://nodejs.org"><img src="https://img.shields.io/badge/node-%3E%3D20-brightgreen.svg" alt="Node.js >= 20"/></a>
 </p>
 
 <p align="center">
-  <a href="#forgen-を使うと起こること">動作フロー</a> &middot;
+  <a href="#最初のブロック-30秒">最初のブロック</a> &middot;
+  <a href="#ハーネスがあなたを運ぶ">ビジョン</a> &middot;
   <a href="#クイックスタート">クイックスタート</a> &middot;
   <a href="#仕組み">仕組み</a> &middot;
   <a href="#4軸パーソナライゼーション">4軸</a> &middot;
@@ -32,8 +33,73 @@
 
 ---
 
+## 最初のブロック (30秒)
+
+あなたは何度も騙されてきました。Claude は「テスト通過、実装完了」と言う — 実際に動かすと — 動かない。forgen はそのギャップを塞ぎます。
+
+```
+You:     「ログインハンドラを実装してください。」
+Claude:  ...編集中...
+Claude:  "구현 완료했습니다。"
+
+[forgen:stop-guard/L1-e2e-before-done]
+Docker e2e 証拠 (~/.forgen/state/e2e-result.json, 1時間以内) がありません。
+実行してから再応答してください。
+
+Claude:  「完了宣言を取り消します。証拠ファイルがありません。e2e を先に実行します...」
+         ...bash tests/e2e/docker/run-test.sh 実行...
+         「63/63 通過。구현 완료했습니다。」
+
+[forgen] ✓ approved
+```
+
+**何が起きたか**: Claude の Stop フックが、あなたが定義したルール (`L1-e2e-before-done`) によってブロックされました。Claude はブロック `reason` を読み、早すぎた完了宣言を撤回し、証拠を生成して再提出しました。**追加 API コール 0** — Claude が元々生成する予定だった同じセッションのターン内で全て起きました。
+
+これが **Mech-B セルフチェックプロンプトインジェクト** です。Claude Code の Stop フックが `decision: "block"` + `reason` を受け入れ、Claude が次のターンでその reason を入力として読むから成り立ちます。10 シナリオ $1.74 で end-to-end 検証済み ([A1 spike report](docs/spike/mech-b-a1-verification-report.md))。
+
+🎬 **動作を見る** (27秒):
+
+```bash
+# 実際のフック・実際のルール・実際の block/approve サイクルをライブで
+bash docs/demo/mech-b-demo.sh
+
+# または録画済み asciinema キャストを再生
+asciinema play docs/demo/mech-b-block-unblock.cast
+```
+
+デモの「本物/シミュレーション」の区別は [`docs/demo/README.md`](docs/demo/README.md) を参照。
+
+---
+
 ## 2人の開発者。同じ Claude。まったく異なる振る舞い。
 
+上記の Trust Layer は柱の1つです。もう1つはパーソナライゼーション — 最初のブロック後に forgen を使い続ける理由です。
+
+---
+
+## ハーネスがあなたを運ぶ
+
+パーソナライゼーションは表面です。より深いアイデア: **すべてのセッションが痕跡を残し、その痕跡が蓄積されてあなたのように判断するハーネスになります。** 修正、規約、トレードオフの好み — 会話から抽出され、`~/.forgen/me/` に保存され、次のセッションで Claude に再注入されます。
+
+```
+会話          ──►  抽出: solution / rule / behavior / profile 更新
+                    ────────────────────────────────────────────
+                                       │
+                                       ▼
+次のセッション  ◄──  注入: UserPromptSubmit コンテキスト + レンダリングされた
+                    ルール + あなたの基準に合わせた Stop-hook ガード
+```
+
+数週間経つと、このハーネスは「ルールを強制するツール」ではなく、**あなたが仕事を判断する方法が詰まった持ち運べるバンドル** になります。一行で export:
+
+```bash
+forgen compound export    # → forgen-knowledge-YYYY-MM-DD.tar.gz
+                          #   (rules + solutions + behavior — あなたの哲学)
+forgen compound import <path>   # 別のマシンで再現
+```
+
+これが北極星: *ノートパソコン上で、あなたのように判断する Claude と、持ち運べる tarball.*
+
 開発者 A は慎重派です。Claude にすべてのテストを実行させ、理由を説明させ、現在のファイル以外を変更する前に必ず確認を求めます。
 
 開発者 B はスピード重視です。Claude に前提を置いて判断させ、関連ファイルも直接修正させ、結果を2行で報告させます。
@@ -57,7 +123,7 @@ forgen がこれを実現します。作業スタイルをプロファイリン
 ### 初回実行（1回のみ、約1分）
 
 ```bash
-npm install -g /forgen
+npm install -g @wooojin/forgen
 forgen
 ```
 
@@ -117,7 +183,7 @@ Claude が `correction-record` MCP ツールを呼び出します。修正は、
 
 ```bash
 # 1. インストール
-npm install -g /forgen
+npm install -g @wooojin/forgen
 
 # 2. 初回実行 — 4問オンボーディング（英語/韓国語選択）
 forgen
@@ -131,7 +197,38 @@ forgen
 - **Node.js** >= 20（SQLite セッション検索には >= 22 を推奨）
 - **Claude Code** インストール・認証済み（`npm i -g @anthropic-ai/claude-code`）
 
-> **ベンダー依存:** forgen は Claude Code をラップします。Anthropic API または Claude Code の変更が動作に影響する可能性があります。Claude Code 1.0.x でテスト済みです。
+> **ベンダー依存:** forgen は Claude Code をラップします。Anthropic API または Claude Code の変更が動作に影響する可能性があります。Claude Code 1.0.x / 2.1.x でテスト済み。
+
+### 隔離 / CI / Docker での利用
+
+forgen のホームはデフォルト `~/.forgen` ですが、プロセス毎に上書き可能:
+
+```bash
+# クリーンな隔離ホーム — 実 ~/.forgen は触らない
+FORGEN_HOME=/tmp/forgen-clean forgen init    # starter-pack 15件を自動配置
+FORGEN_HOME=/tmp/forgen-clean forgen stats   # 隔離ホームの統計のみ表示
+FORGEN_HOME=/tmp/forgen-clean claude -p "…"  # フックが env を継承 → ログ隔離
+```
+
+Claude Code のフックプロセスは親 env を継承するため、`FORGEN_HOME=...` プレ
+フィックス一つで全状態 (rules/solutions/behavior/enforcement) がそのディレ
+クトリに隔離されます。用途:
+
+- CI パイプラインで固定シードに対する forgen 検証
+- 実ホーム汚染なしの「新規ユーザー初日体験」再現
+- 1 台のマシンで複数ペルソナ運用
+
+**Docker / リモートサーバー (OAuth 制約):** Claude Code は OAuth セッションを
+**OS キーチェーン** (macOS Keychain / libsecret / Windows Credential Manager)
+に保存するため、新規 Linux コンテナで `~/.claude.json` のみマウントしても
+refresh トークンが無く認証できません。コンテナ環境では `ANTHROPIC_API_KEY`
+env を使ってください。ホスト環境 (macOS/Linux ワークステーション) は通常の
+`claude login` フローで動作 — API キー不要。
+
+### マイグレーション
+
+`forgen migrate implicit-feedback` — pre-v0.4.1 ログの `category` フィールド
+バックフィル。冪等 (idempotent) — 複数回実行しても安全。
 
 ---
 
@@ -403,13 +500,27 @@ forgen forge --export           # プロファイルをエクスポート
 ### 状態確認
 
 ```bash
+forgen stats                    # 1画面 Trust Layer ダッシュボード (ルール・修正・block 7日)
+forgen last-block               # 直近のブロックイベント詳細
 forgen inspect profile          # 4軸プロファイル + パック + ファセット
 forgen inspect rules            # アクティブ/抑制されたルール
-forgen inspect evidence         # 修正履歴
+forgen inspect corrections      # 修正履歴 (alias: evidence)
 forgen inspect session          # 現在のセッション状態
+forgen inspect violations       # 最近のブロック記録 (--last N)
 forgen me                       # パーソナルダッシュボード（inspect profile のショートカット）
 ```
 
+### ルール管理
+
+```bash
+forgen rule list                # アクティブ + suppressed ルール一覧
+forgen rule suppress <id>       # ルールを無効化 (hard ルールは拒否)
+forgen rule activate <id>       # suppressed ルールを再アクティブ化
+forgen rule scan [--apply]      # ライフサイクルトリガー実行 (昇格/降格/引退)
+forgen rule health-scan         # drift → Mech 降格候補をスキャン
+forgen rule classify            # 既存ルールに enforce_via を自動提案
+```
+
 ### 知識管理
 
 ```bash

package/README.ko.md

@@ -14,6 +14,7 @@
 </p>
 
 <p align="center">
+  <a href="#하네스가-당신을-담고-간다">비전</a> &middot;
   <a href="#forgen를-쓰면-일어나는-일">동작 흐름</a> &middot;
   <a href="#빠른-시작">빠른 시작</a> &middot;
   <a href="#동작-방식">동작 방식</a> &middot;
@@ -52,6 +53,31 @@ forgen가 이것을 가능하게 합니다. 작업 스타일을 프로파일링
 
 ---
 
+## 하네스가 당신을 담고 간다
+
+개인화는 표면입니다. 더 깊은 아이디어: **매 세션이 흔적을 남기고, 그 흔적들이 쌓여 당신처럼 판단하는 하네스가 됩니다.** 교정, 컨벤션, 트레이드오프 선호 — 대화에서 추출되어 `~/.forgen/me/` 에 저장되고, 다음 세션마다 Claude 에 다시 주입됩니다.
+
+```
+대화       ──►  추출: solution / rule / behavior / profile 업데이트
+                 ──────────────────────────────────────────────
+                                   │
+                                   ▼
+다음 세션  ◄──  주입: UserPromptSubmit 컨텍스트 + 렌더된 규칙
+                 + 당신의 기준에 맞춘 Stop-hook 가드
+```
+
+몇 주가 지나면 이 하네스는 "규칙을 강제하는 도구"가 아니라 **당신이 일을 판단하는 방식이 담긴 휴대 가능한 번들** 이 됩니다. 한 줄로 export:
+
+```bash
+forgen compound export    # → forgen-knowledge-YYYY-MM-DD.tar.gz
+                          #   (rules + solutions + behavior — 당신의 철학)
+forgen compound import <path>   # 다른 머신에서 그대로 재연
+```
+
+그게 북극성입니다: *노트북 위에 있는, 당신처럼 판단하는 Claude, 그리고 들고 다닐 수 있는 tarball.*
+
+---
+
 ## forgen를 쓰면 일어나는 일
 
 ### 첫 실행 (1회, 약 1분)
@@ -131,7 +157,38 @@ forgen
 - **Node.js** >= 20 (SQLite 세션 검색은 >= 22 권장)
 - **Claude Code** 설치 및 인증 (`npm i -g @anthropic-ai/claude-code`)
 
-> **벤더 의존성:** forgen은 Claude Code를 래핑합니다. Anthropic API 또는 Claude Code 변경이 동작에 영향을 줄 수 있습니다. Claude Code 1.0.x 기준으로 테스트되었습니다.
+> **벤더 의존성:** forgen은 Claude Code를 래핑합니다. Anthropic API 또는 Claude Code 변경이 동작에 영향을 줄 수 있습니다. Claude Code 1.0.x / 2.1.x 에서 테스트됨.
+
+### 격리 / CI / Docker 사용
+
+forgen 홈은 기본 `~/.forgen` 이지만 프로세스별 override 가능:
+
+```bash
+# 깨끗한 격리 홈 — 실제 ~/.forgen 은 건드리지 않음
+FORGEN_HOME=/tmp/forgen-clean forgen init    # starter-pack 15개 자동 배포
+FORGEN_HOME=/tmp/forgen-clean forgen stats   # 격리 홈의 통계만 표시
+FORGEN_HOME=/tmp/forgen-clean claude -p "…"  # 훅이 env 상속 → 격리된 로그
+```
+
+Claude Code 훅 프로세스가 부모 env 를 상속하므로 `FORGEN_HOME=...` 프리픽스
+하나면 모든 상태(rules/solutions/behavior/enforcement)가 해당 디렉터리로 격리.
+쓰임새:
+
+- CI 파이프라인에서 고정 시드로 forgen 검증
+- 실 홈 오염 없이 "신규 사용자 첫날 경험" 재현
+- 한 머신에서 여러 페르소나 운영
+
+**Docker / 원격 서버 (OAuth 제약):** Claude Code 는 OAuth 세션을 **OS 키체인**
+(macOS Keychain / libsecret / Windows Credential Manager) 에 저장하므로, 새
+Linux 컨테이너에서 `~/.claude.json` 만 마운트하면 refresh 토큰이 없어서 인증이
+안 됩니다. 컨테이너 환경에서는 `ANTHROPIC_API_KEY` env 를 사용하세요. 호스트
+기반 사용(macOS/Linux 워크스테이션) 은 `claude login` 흐름 그대로 동작 — API
+키 불필요.
+
+### 마이그레이션
+
+`forgen migrate implicit-feedback` — pre-v0.4.1 로그의 `category` 필드 백필.
+멱등(idempotent) — 여러 번 실행 안전.
 
 ---
 
@@ -414,13 +471,27 @@ forgen forge --export           # 프로필 내보내기
 ### 상태 확인
 
 ```bash
+forgen stats                    # 한 화면 Trust Layer 대시보드 (규칙·교정·block 7일)
+forgen last-block               # 가장 최근 block 이벤트와 rule 상세
 forgen inspect profile          # 4축 프로필 + 팩 + facet
 forgen inspect rules            # 활성/비활성 규칙
-forgen inspect evidence         # 교정 기록
+forgen inspect corrections      # 교정 기록 (alias: evidence)
 forgen inspect session          # 현재 세션 상태
+forgen inspect violations       # 최근 block 기록 (--last N)
 forgen me                       # 개인 대시보드 (inspect profile 단축키)
 ```
 
+### 규칙 관리
+
+```bash
+forgen rule list                # 활성 + suppressed 규칙 목록
+forgen rule suppress <id>       # 규칙 비활성화 (hard 규칙은 거부)
+forgen rule activate <id>       # suppressed 규칙 재활성화
+forgen rule scan [--apply]      # 수명주기 트리거 실행 (승격/강등/은퇴)
+forgen rule health-scan         # drift → Mech 강등 후보 스캔
+forgen rule classify            # 레거시 규칙에 enforce_via 자동 제안
+```
+
 ### 지식 관리
 
 ```bash

package/README.md

@@ -3,21 +3,22 @@
 </p>
 
 <p align="center">
-  <strong>The Claude Code personalization harness.</strong><br/>
-  <strong>The more you use Claude, the better it knows you.</strong>
+  <strong>When Claude says "done", forgen makes it prove it.</strong><br/>
+  Turn-level self-verification + personalized rules, at <strong>$0 extra API cost</strong>.
 </p>
 
 <p align="center">
-  <a href="https://www.npmjs.com/package//forgen"><img src="https://img.shields.io/npm/v//forgen.svg" alt="npm version"/></a>
+  <a href="https://www.npmjs.com/package/@wooojin/forgen"><img src="https://img.shields.io/npm/v/@wooojin/forgen.svg" alt="npm version"/></a>
   <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT"/></a>
   <a href="https://nodejs.org"><img src="https://img.shields.io/badge/node-%3E%3D20-brightgreen.svg" alt="Node.js >= 20"/></a>
 </p>
 
 <p align="center">
-  <a href="#what-happens-when-you-use-forgen">What Happens</a> &middot;
+  <a href="#the-first-block-30-seconds">First Block</a> &middot;
   <a href="#quick-start">Quick Start</a> &middot;
   <a href="#how-it-works">How It Works</a> &middot;
   <a href="#4-axis-personalization">4-Axis</a> &middot;
+  <a href="#the-harness-carries-you">Harness Vision</a> &middot;
   <a href="#commands">Commands</a> &middot;
   <a href="#architecture">Architecture</a> &middot;
   <a href="#safety">Safety</a>
@@ -32,8 +33,50 @@
 
 ---
 
+## The first block (30 seconds)
+
+You've been burned: Claude says "tests pass, implementation done" — you run it — it doesn't work. forgen closes that gap.
+
+```
+You:     "Update the auth middleware."
+Claude:  ...makes edits to src/middleware/auth.ts...
+Claude:  "구현 완료. 신뢰도 95/100."
+
+[forgen:stop-guard/builtin:self-score-inflation]
+자가 점수 상승 선언 1건 (95/100). 측정 도구 호출 0회 — 숫자를 뒷받침할
+실행/확인 증거 없음. 테스트/빌드/curl 실행 결과를 턴에 포함해 재응답.
+
+Claude:  "측정 없이 점수를 매겼습니다. 실 테스트부터 실행합니다..."
+         $ npm test
+         "31 passed / 0 failed. auth middleware 구현 완료."
+
+[forgen] ✓ approved
+```
+
+**What just happened**: Claude's Stop hook detected a score claim (`95/100`) without any measurement tool call (`Bash` / `NotebookEdit`) in the turn — one of forgen's **three built-in meta guards** (TEST-1 fact vs agreement, **TEST-2 self-score inflation**, TEST-3 conclusion/verification ratio). Claude read the block `reason`, retracted, ran the real test, and re-submitted. **Zero extra API calls** — it all happened in the same session turn Claude was going to produce anyway.
+
+The same mechanism also fires when Claude writes conclusions faster than evidence ("done. passed. shipped. verified." with no measurement context), or claims facts ("테스트가 통과합니다") without ever having executed them. You can also define **custom rules** (e.g. "require npm test evidence before saying 'done' in this repo") via `forgen compound --rule` — they slot into the same Stop-hook dispatcher.
+
+This is **Mech-B self-check prompt-inject**. It works because Claude Code's Stop hook accepts `decision: "block"` + `reason`, and Claude in the next turn reads that reason as input. We verified it end-to-end on 10 scenarios at $1.74 total cost ([A1 spike report](docs/spike/mech-b-a1-verification-report.md)), and v0.4.1 added built-in guards so you get the first block **without writing any rule**.
+
+🎬 **See it happen** (27 seconds):
+
+```bash
+# Watch the full loop live — actual hook, actual rule, actual block/approve cycle
+bash docs/demo/mech-b-demo.sh
+
+# Or replay the pre-recorded asciinema cast
+asciinema play docs/demo/mech-b-block-unblock.cast
+```
+
+See [`docs/demo/README.md`](docs/demo/README.md) for what's real vs simulated in the demo.
+
+---
+
 ## Two developers. Same Claude. Completely different behavior.
 
+The Trust Layer above is one pillar. The other is personalization — still the reason you'd keep forgen around after the first block.
+
 Developer A is careful. They want Claude to run all tests, explain reasoning, and ask before touching anything outside the current file.
 
 Developer B moves fast. They want Claude to make assumptions, fix related files automatically, and report results in two lines.
@@ -48,7 +91,32 @@ fix the session handler? Here's           timeout not covered. Done."
 my analysis of each..."
 ```
 
-Forgen makes this happen. It profiles your work style, learns from your corrections, and renders personalized rules that Claude follows every session.
+Forgen profiles your work style, learns from your corrections, and renders personalized rules that Claude follows every session.
+
+---
+
+## The harness carries you
+
+Personalization is the surface. The deeper idea: **every session leaves a trace, and those traces compound into a harness that reasons like you do.** Your corrections, your conventions, your trade-off preferences — extracted from conversation, stored under `~/.forgen/me/`, and replayed back to Claude on every future session.
+
+```
+Conversation  ──►  Extracted: solution / rule / behavior / profile update
+                   ─────────────────────────────────────────────────────
+                                         │
+                                         ▼
+Next session  ◄──  Injected: UserPromptSubmit context + rendered rules
+                   + Stop-hook guards calibrated to *your* standards
+```
+
+After a few weeks this harness stops being "a tool that enforces rules" and starts being **a portable bundle of how you judge work**. One command exports it:
+
+```bash
+forgen compound export    # → forgen-knowledge-YYYY-MM-DD.tar.gz
+                          #   (rules + solutions + behavior — your philosophy)
+forgen compound import <path>   # replay it on another machine
+```
+
+That's the north star: *a Claude on your laptop that judges like you do, and a tarball you can carry.*
 
 ---
 
@@ -131,7 +199,39 @@ forgen
 - **Node.js** >= 20 (>= 22 recommended for SQLite session search)
 - **Claude Code** installed and authenticated (`npm i -g @anthropic-ai/claude-code`)
 
-> **Vendor dependency:** Forgen wraps Claude Code. Anthropic API or Claude Code changes may affect behavior. Tested with Claude Code 1.0.x.
+> **Vendor dependency:** Forgen wraps Claude Code. Anthropic API or Claude Code changes may affect behavior. Tested with Claude Code 1.0.x / 2.1.x.
+
+### Isolated / CI / Docker usage
+
+Forgen's home directory is `~/.forgen` by default, but can be overridden per-process:
+
+```bash
+# Fresh isolated home — does NOT touch your real ~/.forgen
+FORGEN_HOME=/tmp/forgen-clean forgen init       # provisions 15-solution starter pack
+FORGEN_HOME=/tmp/forgen-clean forgen stats      # shows stats from the isolated home
+FORGEN_HOME=/tmp/forgen-clean claude -p "..."   # hooks inherit the env → isolated logs
+```
+
+Claude Code hook processes inherit the parent env, so any `claude` command
+prefixed with `FORGEN_HOME=...` routes all state (rules, solutions, behavior,
+enforcement logs) into that directory. Useful for:
+
+- CI pipelines validating forgen against a pinned seed set
+- Reproducing buyer-first-day experience without polluting your real home
+- Running multiple personas on one machine
+
+**Docker / remote servers (OAuth limitation):** Claude Code stores its OAuth
+session in the **OS keychain** (macOS Keychain / libsecret / Windows Credential
+Manager). Mounting `~/.claude.json` alone is **not enough** in a fresh Linux
+container because the keychain-bound refresh is missing. For container use, set
+`ANTHROPIC_API_KEY` in the container env instead. Host-native usage (macOS,
+Linux workstations) works with the normal `claude login` flow — no API key
+needed.
+
+### Migrations
+
+`forgen migrate implicit-feedback` backfills the `category` field on pre-v0.4.1
+entries in `~/.forgen/state/implicit-feedback.jsonl`. Idempotent — safe to re-run.
 
 ---
 
@@ -243,7 +343,11 @@ Claude has your accumulated patterns in context while drafting the response.
 
 Precision gates (v0.3.2+): matches below relevance 0.3 or with only a single
 common-word tag overlap are filtered before injection so Claude's context
-doesn't get polluted by low-signal hits.
+doesn't get polluted by low-signal hits. **Cold-start boost (v0.4.1+)**: when
+your outcome history has < 5 champion/active solutions (first days after
+install), the injection threshold is relaxed to 0.2 so starter-pack solutions
+can actually surface; once your own patterns accumulate the threshold returns
+to the standard 0.3.
 
 ### 10 built-in skills
 
@@ -451,13 +555,29 @@ forgen forge --export           # Export profile
 ### Inspection
 
 ```bash
+forgen stats                    # Trust-layer dashboard (rules, corrections, blocks 7d, assist today, philosophy)
+forgen recall [--limit N] [--show]
+                                # Recent compound recalls surfaced to Claude (with body preview)
+forgen last-block               # Most recent block event with rule detail
 forgen inspect profile          # 4-axis profile with packs and facets
 forgen inspect rules            # Active and suppressed rules
-forgen inspect evidence         # Correction history
+forgen inspect corrections      # Correction history (alias: evidence)
 forgen inspect session          # Current session state
+forgen inspect violations       # Recent block events (--last N)
 forgen me                       # Personal dashboard (shortcut for inspect profile)
 ```
 
+### Rule management
+
+```bash
+forgen rule list                # List active + suppressed rules
+forgen rule suppress <id>       # Disable a rule (hard rules refused)
+forgen rule activate <id>       # Re-activate a suppressed rule
+forgen rule scan [--apply]      # Run lifecycle triggers (promote/demote/retire)
+forgen rule health-scan         # Scan drift → Mech downgrade candidates
+forgen rule classify            # Propose enforce_via for legacy rules
+```
+
 ### Knowledge management
 
 ```bash
@@ -476,8 +596,11 @@ forgen skill list               # List promoted skills
 ### System
 
 ```bash
-forgen init                     # Initialize project
+forgen init                     # Initialize project (+ 15 starter-pack solutions)
+forgen migrate [implicit-feedback|all]
+                                # One-shot schema migrations (idempotent)
 forgen doctor                   # System diagnostics (10 categories + harness maturity)
+forgen doctor --prune-state     # Daily hygiene: state GC + T4 rule decay (90d idle → retire)
 forgen dashboard                # Knowledge overview (6 sections)
 forgen config hooks             # View hook status + context budget
 forgen config hooks --regenerate # Regenerate hooks
@@ -488,6 +611,37 @@ forgen notepad show             # View session notepad
 forgen uninstall                # Remove forgen cleanly
 ```
 
+### Rule lifecycle (v0.4.0, ADR-001/002)
+
+```bash
+forgen classify-enforce          # Preview enforce_via proposals for existing rules
+forgen classify-enforce --apply  # Save proposed enforce_via (skips already-set rules)
+forgen classify-enforce --apply --force  # Overwrite existing enforce_via
+forgen rule-meta-scan            # Preview Mech demotion candidates (drift.jsonl → A→B→C)
+forgen rule-meta-scan --apply    # Persist demotions + meta_promotions history
+forgen lifecycle-scan            # Preview T2~T5 + Meta (T1 fires inline on correction, not via CLI)
+forgen lifecycle-scan --apply    # Apply all lifecycle state transitions
+```
+
+Rule enforcement is 3-axis (ADR-001):
+- **Mech-A** (hook-BLOCK) — mechanical checks (`rm -rf`, artifact presence). Violation blocks immediately.
+- **Mech-B** (self-check) — natural-language rules. Stop hook feeds self-check question back to Claude via `decision: "block"` + `reason`. Zero extra API cost.
+- **Mech-C** (drift-measure) — long-term bias tracking only.
+
+Rule lifecycle (ADR-002): rules auto-flag / suppress / retire / merge / supersede based on T1~T5 + Meta signals. Details in [docs/adr/ADR-002-rule-lifecycle-engine.md](docs/adr/ADR-002-rule-lifecycle-engine.md).
+
+### Release self-gate (v0.4.0, ADR-003)
+
+Three CI gates prove forgen does not violate its own L1 rules before release:
+
+```bash
+node scripts/self-gate.cjs          # Static: mock-in-prod, secrets, enforce_via, release-artifact
+node scripts/self-gate-runtime.cjs  # Runtime smoke: 6 hook scenarios
+node scripts/self-gate-release.cjs  # Tag-only: version/tag/CHANGELOG/dist/e2e-report consistency
+```
+
+Triggered by `.github/workflows/self-gate.yml` on push main / PR main / tag v*. Dogfood opt-in: see [.forgen/README.md](.forgen/README.md).
+
 ### MCP tools (available to Claude during sessions)
 
 | Tool | Purpose |