@wooojin/forgen 0.3.1 → 0.4.0

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://claude.ai/schemas/claude-plugin.json",
   "name": "forgen",
-  "version": "5.1.2",
+  "version": "0.4.0",
   "description": "Claude Code harness — the more you use Claude, the better it gets",
   "author": {
     "name": "jang-ujin",
@@ -10,7 +10,12 @@
   "repository": "https://github.com/wooo-jin/forgen",
   "homepage": "https://github.com/wooo-jin/forgen",
   "license": "MIT",
-  "keywords": ["claude-code", "harness", "personalization", "forge"],
+  "keywords": [
+    "claude-code",
+    "harness",
+    "personalization",
+    "forge"
+  ],
   "skills": "./skills/",
   "agents": "agents/",
   "statusLine": {

package/CHANGELOG.md

@@ -5,6 +5,170 @@ 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.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
+
+Independent read-only audit (docs/claude-audit-brief.md) surfaced 10 structural
+issues plus 2 follow-up findings. All 12 are fixed with invariant tests.
+
+**P0 — data loss / code injection**
+- **Settings parse-failure data loss** (#2, #10): `settings-injector.ts` and
+  `scripts/postinstall.js` no longer silently replace a malformed settings.json
+  with `{}`. New `readSettingsSafely()` preserves the corrupt original to
+  `settings.json.corrupt-<ts>` and throws; writers release the lock and abort.
+  postinstall settings + `~/.claude.json` now use tmp-file + rename atomic write.
+- **Code injection via node -e** (#5): `session-recovery.ts` no longer
+  interpolates a user-supplied sessionId into a `-e` template literal. A
+  dedicated runner at `dist/hooks/internal/run-lifecycle-check.js` reads the id
+  from argv — no shell, no eval surface.
+- **solution-outcomes race** (#9): all pending-state mutations are now serialised
+  under `withFileLockSync` + `atomicWriteJSON`. Concurrent inject / correction /
+  error hooks on the same session no longer lose or duplicate events.
+- **Archive path traversal** (follow-up #A): `compound-export.importKnowledge`
+  rejects entries whose resolved destination sits outside ME_DIR, including
+  sibling-directory prefix collisions (e.g. `../me-evil/…`).
+
+**P1 — lock semantics, trust, uninstall, injection precision**
+- **Settings-lock live-holder handling** (#1): acquireLock now throws
+  `SettingsLockError` on live-PID timeout instead of overwriting the lock;
+  releaseLock verifies ownership before deleting.
+- **Trust silent escalation** (#3): `preset-manager.computeEffectiveTrust`
+  returns a `Trust 상승` warning when runtime is more permissive than desired;
+  harness surfaces it to the user; fgx cautions `가드레일 우선`/`승인 완화`
+  profile users.
+- **Install/uninstall symmetry** (#7): `uninstall` now strips `FORGEN_*` env
+  keys (previously only `COMPOUND_*`) and recognises `forgen me` (previously
+  only `forgen status`) as the forgen-owned statusLine.
+- **Legacy profile guard** (#6): `loadProfile` runs `isV1Profile` and returns
+  null on legacy shapes so bootstrap re-runs cutover instead of typing stale
+  JSON as v1.
+- **secret-filter vendor tokens** (follow-up #B): GitHub PATs (ghp_/gho_/
+  ghs_/ghu_/ghr_), Google API keys (AIza…), and Slack tokens (xox[abpors]-…)
+  are now detected.
+
+**P2 — label truth, transcript attribution**
+- **permission-handler labels** (#4): `approve()`/`approveWithWarning()` never
+  set `permissionDecision: 'allow'`; they are pass-through. Log and API labels
+  renamed to `safe-pass-through` / `autopilot-warn-pass-through` /
+  `autopilot-pass-through` / `pass-through` so audit trails match reality.
+- **Transcript per-session attribution** (#8): `spawn.ts` snapshots existing
+  transcripts before launching claude and diffs after exit; concurrent sessions
+  in the same cwd no longer cross-attribute. Transcript reading switched to
+  streaming (`createReadStream` + `readline`).
+
+### Added — Data hygiene
+
+Field audit on a ~2-week-old install found 10,802 files in `~/.forgen/state/`
+across 12 filename prefixes, 4.3 MB `match-eval-log.jsonl`, and 80% of
+error-attribution events concentrated on 3 solutions injected at relevance
+0.15–0.21.
+
+- `forgen doctor --prune-state` (new `src/core/state-gc.ts`): removes session-
+  scoped files older than 7 days (checkpoint-, injection-cache-, modified-
+  files-, outcome-pending-, permissions-, skill-trigger-, tool-state-,
+  reminder-, context-, last-). Aggregate jsonl logs are preserved.
+- `solution-outcomes.attributeError` gates: match_score ≥ 0.3,
+  injection-lag ≤ 5 min, top-3 by relevance. Prevents blanket blaming of
+  every injected solution when a tool fails.
+- `solution-injector.MIN_INJECT_RELEVANCE = 0.3` + multi-tag precision gate
+  (`matchedIdentifiers ≥ 1 OR matchedTags ≥ 2`): the matcher remains
+  permissive for recall@5; only the injection step enforces the stricter
+  gate. Zero single-tag high-score injections observed in the field corpus
+  after landing.
+- `match-eval-log.jsonl` size-based rotation at 10 MB (one generation
+  retained).
+
+### Fixed — e2e test isolation
+
+Docker-spawned hooks in `tests/e2e/*.test.ts` were writing session state
+(`e2e-tool-chain`, `chain5-test`, etc.) into the developer's real
+`~/.forgen/state/`. Each e2e file now allocates a fresh `mkdtempSync` HOME
+and injects it into the spawn env; `afterAll` cleans up. Likewise
+`tests/hook-response-tracking.test.ts` now mocks `node:os` so the tracking
+log never lands outside `/tmp/`.
+
+### Fixed — Stale Docker verify checks
+
+`tests/e2e/docker/verify.sh` was asserting three skills that were deleted in
+commit f534227 (v0.3 quality refactor). Result goes from 62/4/6 to 63/0/6
+without touching runtime code.
+
+### Notes
+
+- All fixes confirmed via invariant tests (1732/1732 pass across 143 files),
+  7 real-world attack scenarios (injection, concurrent mutation, corrupt
+  settings, path traversal, prune, doctor smoke), and Linux-clean-environment
+  Docker verification.
+- Upgrade path from 0.3.1 verified (profile + solutions + non-forgen settings
+  byte-identical after upgrade).
+- Windows code paths exist but runtime validation is deferred to GH Actions
+  Windows runner — see P-D note in release audit.
+
 ## [0.3.1] - 2026-04-16
 
 ### Added — Self-Evolving Harness (inspired by Stanford meta-harness)

package/README.ja.md

@@ -3,18 +3,18 @@
 </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="#4軸パーソナライゼーション">4軸</a> &middot;
@@ -32,8 +32,48 @@
 
 ---
 
+## 最初のブロック (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 を使い続ける理由です。
+
 開発者 A は慎重派です。Claude にすべてのテストを実行させ、理由を説明させ、現在のファイル以外を変更する前に必ず確認を求めます。
 
 開発者 B はスピード重視です。Claude に前提を置いて判断させ、関連ファイルも直接修正させ、結果を2行で報告させます。
@@ -57,7 +97,7 @@ forgen がこれを実現します。作業スタイルをプロファイリン
 ### 初回実行（1回のみ、約1分）
 
 ```bash
-npm install -g /forgen
+npm install -g @wooojin/forgen
 forgen
 ```
 
@@ -117,7 +157,7 @@ Claude が `correction-record` MCP ツールを呼び出します。修正は、
 
 ```bash
 # 1. インストール
-npm install -g /forgen
+npm install -g @wooojin/forgen
 
 # 2. 初回実行 — 4問オンボーディング（英語/韓国語選択）
 forgen
@@ -131,6 +171,35 @@ 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 か
+
+|                        | Generic Claude Code | oh-my-claudecode | forgen          |
+|------------------------|:-------------------:|:----------------:|:---------------:|
+| 全員に同じ             | Yes                 | Yes              | **No**          |
+| 修正から学習           | No                  | No               | **Yes**         |
+| エビデンスベースのライフサイクル| No          | No               | **Yes**         |
+| 悪いパターンを自動リタイア| No              | No               | **Yes**         |
+| パーソナライズされたルール| No               | No               | **Yes**         |
+| ランタイム依存関係     | -                   | many             | **3**           |
+
+### forgen が向いているケース
+
+**向いている場合:**
+- 数週間かけて Claude があなたのパターンを学習する長期プロジェクト
+- AI の振る舞いに強いこだわりがある開発者
+- Compound 知識の恩恵を受ける繰り返しパターンがあるコードベース
+
+**向いていない場合:**
+- 使い捨てのスクリプトや一時的なプロトタイプ
+- Claude Code がない環境
+- すべてのメンバーに同じ AI 動作が必要なチーム（forgen は個人用であり、チーム向けではありません）
+
+**forgen + oh-my-claudecode:** 一緒に使えます。OMC はオーケストレーション（エージェント、ワークフロー）を、forgen はパーソナライゼーション（プロファイル、学習）を担当します。[共存ガイド](docs/guides/with-omc.md) を参照してください。
+
 ---
 
 ## 仕組み
@@ -374,13 +443,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

@@ -131,6 +131,35 @@ 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인가
+
+|                        | Generic Claude Code | oh-my-claudecode | forgen          |
+|------------------------|:-------------------:|:----------------:|:---------------:|
+| 모두에게 동일           | Yes                 | Yes              | **No**          |
+| 교정에서 학습           | No                  | No               | **Yes**         |
+| Evidence 기반 라이프사이클| No               | No               | **Yes**         |
+| 나쁜 패턴 자동 은퇴      | No                  | No               | **Yes**         |
+| 개인화된 규칙           | No                  | No               | **Yes**         |
+| 런타임 의존성           | -                   | many             | **3**           |
+
+### 언제 사용하면 좋은가
+
+**잘 맞는 경우:**
+- 몇 주에 걸쳐 Claude가 패턴을 학습하는 장기 프로젝트
+- AI 행동 방식에 강한 선호가 있는 개발자
+- Compound 지식의 혜택을 받는 반복 패턴이 있는 코드베이스
+
+**맞지 않는 경우:**
+- 일회성 스크립트나 임시 프로토타입
+- Claude Code가 없는 환경
+- 모든 구성원이 동일한 AI 행동이 필요한 팀 (forgen은 개인용이지, 팀용이 아님)
+
+**forgen + oh-my-claudecode:** 함께 사용할 수 있습니다. OMC는 오케스트레이션(에이전트, 워크플로우)을, forgen은 개인화(프로필, 학습)를 담당합니다. [공존 가이드](docs/guides/with-omc.md)를 참고하세요.
+
 ---
 
 ## 동작 방식
@@ -385,13 +414,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,18 +3,18 @@
 </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;
@@ -32,8 +32,48 @@
 
 ---
 
+## 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:     "Implement the login handler."
+Claude:  ...makes edits...
+Claude:  "구현 완료했습니다."
+
+[forgen:stop-guard/L1-e2e-before-done]
+Docker e2e 증거(~/.forgen/state/e2e-result.json, 1시간 이내)가 없습니다.
+지금 실행 후 재응답하라.
+
+Claude:  "완료 선언을 취소합니다. 증거 파일이 없습니다. e2e 를 먼저 실행합니다..."
+         ...runs bash tests/e2e/docker/run-test.sh...
+         "63/63 pass. 구현 완료했습니다."
+
+[forgen] ✓ approved
+```
+
+**What just happened**: Claude's Stop hook was blocked by a rule you defined (`L1-e2e-before-done`). Claude read the block `reason`, retracted its premature claim, produced evidence, and re-submitted. **Zero extra API calls** — it all happened in the same session turn Claude was going to produce anyway.
+
+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)).
+
+🎬 **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 +88,7 @@ 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.
 
 ---
 
@@ -109,7 +149,7 @@ Facets are micro-adjusted based on accumulated evidence. If your corrections con
 
 ### Next session
 
-Updated rules are rendered with your corrections included. Compound knowledge is searchable via MCP. Claude gets better at being *your* Claude.
+Updated rules are rendered with your corrections included. Compound knowledge is searchable via MCP. Retrieval precision grows as your personal accumulation grows — the mechanism is in place from day 1 (starter-pack covers common dev queries on a fresh install), and the signal-to-noise ratio improves over roughly 2–4 weeks of real use as low-fitness solutions are auto-demoted and your specific patterns get promoted.
 
 ---
 
@@ -131,6 +171,35 @@ 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.
+
+---
+
+## Why forgen
+
+|                        | Generic Claude Code | oh-my-claudecode | forgen          |
+|------------------------|:-------------------:|:----------------:|:---------------:|
+| Same for everyone      | Yes                 | Yes              | **No**          |
+| Learns from corrections| No                  | No               | **Yes**         |
+| Evidence-based lifecycle| No                 | No               | **Yes**         |
+| Auto-retires bad patterns| No               | No               | **Yes**         |
+| Personalized rules     | No                  | No               | **Yes**         |
+| Runtime dependencies   | -                   | many             | **3**           |
+
+### When to use forgen
+
+**Good fit:**
+- Long-running projects where Claude learns your patterns over weeks
+- Developers with strong preferences about how AI should behave
+- Codebases with recurring patterns that benefit from compound knowledge
+
+**Not a fit:**
+- One-off scripts or throwaway prototypes
+- Environments without Claude Code
+- Teams that need identical AI behavior for all members (forgen is personal, not team-wide)
+
+**forgen + oh-my-claudecode:** They work together. OMC provides orchestration (agents, workflows); forgen provides personalization (profile, learning). See [Coexistence Guide](docs/guides/with-omc.md).
+
 ---
 
 ## How It Works
@@ -209,12 +278,16 @@ solution-injector matches: starter-error-handling-patterns (0.70)
 Claude sees: "Matched solutions: error-handling-patterns [pattern|0.70]
              Use try/catch with specific error types. Always log original error..."
                     ↓
-Claude writes better error handling code, informed by your accumulated patterns.
+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.
+
 ### 10 built-in skills
 
-Curated, compound-native skills. Each one integrates with accumulated knowledge — they get better every session.
+Curated, compound-native skills. Each integrates with your accumulated knowledge — effectiveness compounds as your personal solution base grows.
 
 **Core chain** (build → learn):
 
@@ -418,13 +491,27 @@ forgen forge --export           # Export profile
 ### Inspection
 
 ```bash
+forgen stats                    # One-screen trust-layer dashboard (rules, corrections, blocks 7d)
+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
@@ -445,6 +532,7 @@ forgen skill list               # List promoted skills
 ```bash
 forgen init                     # Initialize project
 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
@@ -455,6 +543,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 |