@wooojin/forgen 0.3.2 → 0.4.0

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.0",
   "description": "Claude Code harness — the more you use Claude, the better it gets",
   "author": {
     "name": "jang-ujin",

package/CHANGELOG.md

@@ -5,6 +5,70 @@ 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

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
@@ -403,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

@@ -414,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.
 
 ---
 
@@ -451,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
@@ -478,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
@@ -488,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 |

package/README.zh.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:     "实现登录 handler。"
+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 hook 被你定义的规则 (`L1-e2e-before-done`) 拦截。Claude 读取了 block `reason`, 撤回过早的完成声明, 产生证据, 重新提交。**零额外 API 调用** — 全部发生在 Claude 本来就会产出的同一个 session turn 内。
+
+这就是 **Mech-B 自检 prompt-inject**。它工作是因为 Claude Code 的 Stop hook 接受 `decision: "block"` + `reason`, 而 Claude 在下一轮把那个 reason 作为输入读取。我们用 10 个场景、$1.74 总成本端到端验证 ([A1 spike report](docs/spike/mech-b-a1-verification-report.md))。
+
+🎬 **观看实际运行** (27秒):
+
+```bash
+# 现场观看完整循环 — 真实的 hook、真实的规则、真实的 block/approve 周期
+bash docs/demo/mech-b-demo.sh
+
+# 或重放预录制的 asciinema cast
+asciinema play docs/demo/mech-b-block-unblock.cast
+```
+
+关于 demo 中"真实 vs 模拟"的详情见 [`docs/demo/README.md`](docs/demo/README.md)。
+
+---
+
 ## 两个开发者。同一个 Claude。完全不同的行为。
 
+上述 Trust Layer 是一根支柱。另一根是个性化 — 第一次拦截之后继续使用 forgen 的理由。
+
 开发者 A 做事谨慎。他希望 Claude 运行所有测试、解释原因，在触碰当前文件以外的内容前先征求确认。
 
 开发者 B 追求速度。他希望 Claude 自行假设、直接修复相关文件、用两行汇报结果。
@@ -57,7 +97,7 @@ forgen 实现了这一切。它对你的工作风格进行画像、从你的纠
 ### 首次运行（仅一次，约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
@@ -403,13 +443,27 @@ forgen forge --export           # 导出档案
 ### 状态查看
 
 ```bash
+forgen stats                    # 单屏 Trust Layer 仪表盘 (规则·纠正·block 7天)
+forgen last-block               # 最近一次拦截事件详情
 forgen inspect profile          # 4轴档案 + pack + facet
 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