@wooojin/forgen 0.4.0 → 0.4.1

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://claude.ai/schemas/claude-plugin.json",
   "name": "forgen",
-  "version": "0.4.0",
+  "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,36 @@ 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

package/README.ja.md

@@ -15,6 +15,7 @@
 
 <p align="center">
   <a href="#最初のブロック-30秒">最初のブロック</a> &middot;
+  <a href="#ハーネスがあなたを運ぶ">ビジョン</a> &middot;
   <a href="#クイックスタート">クイックスタート</a> &middot;
   <a href="#仕組み">仕組み</a> &middot;
   <a href="#4軸パーソナライゼーション">4軸</a> &middot;
@@ -74,6 +75,31 @@ asciinema play docs/demo/mech-b-block-unblock.cast
 
 上記の 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行で報告させます。
@@ -171,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) — 複数回実行しても安全。
 
 ---
 

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) — 여러 번 실행 안전.
 
 ---
 

package/README.md

@@ -18,6 +18,7 @@
   <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>
@@ -37,24 +38,26 @@
 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:  "구현 완료했습니다."
+You:     "Update the auth middleware."
+Claude:  ...makes edits to src/middleware/auth.ts...
+Claude:  "구현 완료. 신뢰도 95/100."
 
-[forgen:stop-guard/L1-e2e-before-done]
-Docker e2e 증거(~/.forgen/state/e2e-result.json, 1시간 이내)가 없습니다.
-지금 실행 후 재응답하라.
+[forgen:stop-guard/builtin:self-score-inflation]
+자가 점수 상승 선언 1건 (95/100). 측정 도구 호출 0회 — 숫자를 뒷받침할
+실행/확인 증거 없음. 테스트/빌드/curl 실행 결과를 턴에 포함해 재응답.
 
-Claude:  "완료 선언을 취소합니다. 증거 파일이 없습니다. e2e 를 먼저 실행합니다..."
-         ...runs bash tests/e2e/docker/run-test.sh...
-         "63/63 pass. 구현 완료했습니다."
+Claude:  "측정 없이 점수를 매겼습니다. 실 테스트부터 실행합니다..."
+         $ npm test
+         "31 passed / 0 failed. auth middleware 구현 완료."
 
 [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.
+**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.
 
-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)).
+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):
 
@@ -92,6 +95,31 @@ Forgen profiles your work style, learns from your corrections, and renders perso
 
 ---
 
+## 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.*
+
+---
+
 ## What happens when you use forgen
 
 ### First run (one time, ~1 minute)
@@ -171,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.
 
 ---
 
@@ -283,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
 
@@ -491,7 +555,9 @@ forgen forge --export           # Export profile
 ### Inspection
 
 ```bash
-forgen stats                    # One-screen trust-layer dashboard (rules, corrections, blocks 7d)
+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
@@ -530,7 +596,9 @@ 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)

package/README.zh.md

@@ -18,6 +18,7 @@
   <a href="#快速开始">快速开始</a> &middot;
   <a href="#工作原理">工作原理</a> &middot;
   <a href="#4轴个性化">4轴</a> &middot;
+  <a href="#这个-harness-装载的是你">愿景</a> &middot;
   <a href="#命令">命令</a> &middot;
   <a href="#架构">架构</a> &middot;
   <a href="#安全">安全</a>
@@ -92,6 +93,31 @@ forgen 实现了这一切。它对你的工作风格进行画像、从你的纠
 
 ---
 
+## 这个 harness 装载的是你
+
+个性化只是表面。更深层的想法:**每次会话都留下痕迹,这些痕迹累积起来成为一个像你一样判断的 harness。** 你的修正、你的规范、你的权衡偏好 — 从对话中提取,存储在 `~/.forgen/me/` 下,并在每次后续会话中回放给 Claude。
+
+```
+对话          ──►  提取: solution / rule / behavior / profile 更新
+                    ────────────────────────────────────────────
+                                       │
+                                       ▼
+下一次会话    ◄──  注入: UserPromptSubmit 上下文 + 渲染的规则
+                    + 校准到你标准的 Stop-hook 守卫
+```
+
+几周之后,这个 harness 不再是"强制执行规则的工具",而是 **承载你如何判断工作的可携带包裹**。一条命令导出:
+
+```bash
+forgen compound export    # → forgen-knowledge-YYYY-MM-DD.tar.gz
+                          #   (rules + solutions + behavior — 你的哲学)
+forgen compound import <path>   # 在另一台机器上重放
+```
+
+这就是北极星:*你的笔记本上,一个像你一样判断的 Claude,还有你能随身携带的 tarball。*
+
+---
+
 ## 使用 forgen 会发生什么
 
 ### 首次运行（仅一次，约1分钟）

package/dist/checks/conclusion-verification-ratio.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Forgen v0.4.1 — TEST-3: 결론 vs 검증 비율 가드
+ *
+ * Claude 응답 텍스트에서 **결론 키워드** 와 **검증 키워드** 빈도 비율을 측정.
+ * 결론 / 검증 > 3 이면 "결론을 쏟아내지만 검증이 부족한" 합의-기반 완료 선언
+ * 패턴 — stop-guard 에서 block.
+ *
+ * 배경 (RC3): v0.4.0 self-interview 에서 "통과했다 / 완료됐다" 같은 결론이
+ *   한 응답에 5~8회 반복되지만 "테스트 실행했나 / 증거가 뭔가" 관련 표현은
+ *   0회인 케이스 반복 관찰. TEST-1 이 "측정 도구 호출 0건" 을 봤다면, TEST-3
+ *   은 같은 문제를 **텍스트-내부** 비율로 잡는다 (도구 호출이 있어도 서술이
+ *   결론-편향이면 감지).
+ *
+ * 순수 함수 — Stop hook 이 `block_message` 로 주입할 수 있도록 reason 문자열을
+ * 직접 반환.
+ */
+export interface RatioCheckInput {
+    text: string;
+    /** 비율 임계값. 기본 3 (결론이 검증의 3배 넘으면 block). */
+    threshold?: number;
+    /**
+     * 결론/검증 둘 다 합쳐 이 개수 미만이면 판정 보류 (sparse text).
+     * 기본 4 — 짧은 1-2줄 응답에 오탐 방지.
+     */
+    minTotal?: number;
+}
+export interface RatioCheckResult {
+    /** true = 결론 편향 감지 — block 후보. */
+    block: boolean;
+    conclusionCount: number;
+    verificationCount: number;
+    /** 검증이 0이면 Infinity, 아니면 결론/검증. */
+    ratio: number;
+    /** block 시 stop-guard block_message 로 주입할 사람-읽기 문장. */
+    reason: string;
+}
+export declare function checkConclusionVerificationRatio(input: RatioCheckInput): RatioCheckResult;

package/dist/checks/conclusion-verification-ratio.js

@@ -0,0 +1,86 @@
+/**
+ * Forgen v0.4.1 — TEST-3: 결론 vs 검증 비율 가드
+ *
+ * Claude 응답 텍스트에서 **결론 키워드** 와 **검증 키워드** 빈도 비율을 측정.
+ * 결론 / 검증 > 3 이면 "결론을 쏟아내지만 검증이 부족한" 합의-기반 완료 선언
+ * 패턴 — stop-guard 에서 block.
+ *
+ * 배경 (RC3): v0.4.0 self-interview 에서 "통과했다 / 완료됐다" 같은 결론이
+ *   한 응답에 5~8회 반복되지만 "테스트 실행했나 / 증거가 뭔가" 관련 표현은
+ *   0회인 케이스 반복 관찰. TEST-1 이 "측정 도구 호출 0건" 을 봤다면, TEST-3
+ *   은 같은 문제를 **텍스트-내부** 비율로 잡는다 (도구 호출이 있어도 서술이
+ *   결론-편향이면 감지).
+ *
+ * 순수 함수 — Stop hook 이 `block_message` 로 주입할 수 있도록 reason 문자열을
+ * 직접 반환.
+ */
+/** 결론 키워드 — 상태를 단정적으로 선언하는 어휘. */
+const CONCLUSION_PATTERNS = [
+    /\b(pass(es|ed)?|passing)\b/gi,
+    /\b(done|ready|shipped|finished|complete)\b/gi,
+    /\bLGTM\b/g,
+    /\bconfirmed\b/gi,
+    /\bverified\b/gi,
+    /\bvalidated\b/gi,
+    /(통과(했|됐|함|합니다))/g,
+    /(완료(했|됐|됨|됐습니다))/g,
+    /(성공(했|했습니다|적))/g,
+    /(동작(합니다|함|한다))/g,
+];
+/** 검증 키워드 — 측정/확인/실행 행위를 서술하는 어휘. */
+const VERIFICATION_PATTERNS = [
+    /\b(test(s|ed|ing)?|tested)\b/gi,
+    /\b(verify|verifying|verification)\b/gi,
+    /\b(check(ed|ing)?)\b/gi,
+    /\b(run|ran|running)\b/gi,
+    /\b(measure(d|ment)?)\b/gi,
+    /\bevidence\b/gi,
+    /증거/g,
+    /테스트/g,
+    /확인/g,
+    /검증/g,
+    /실행/g,
+    /측정/g,
+];
+function countMatches(text, patterns) {
+    let n = 0;
+    for (const p of patterns) {
+        const m = text.match(p);
+        if (m)
+            n += m.length;
+    }
+    return n;
+}
+export function checkConclusionVerificationRatio(input) {
+    const threshold = input.threshold ?? 3;
+    const minTotal = input.minTotal ?? 4;
+    const conclusionCount = countMatches(input.text, CONCLUSION_PATTERNS);
+    const verificationCount = countMatches(input.text, VERIFICATION_PATTERNS);
+    const total = conclusionCount + verificationCount;
+    const ratio = verificationCount === 0
+        ? (conclusionCount === 0 ? 0 : Infinity)
+        : conclusionCount / verificationCount;
+    // sparse text → 판정 보류
+    if (total < minTotal) {
+        return {
+            block: false,
+            conclusionCount,
+            verificationCount,
+            ratio,
+            reason: '',
+        };
+    }
+    // 결론이 전혀 없으면 비율 자체가 의미 없음
+    if (conclusionCount === 0) {
+        return { block: false, conclusionCount, verificationCount, ratio, reason: '' };
+    }
+    const block = ratio > threshold;
+    let reason = '';
+    if (block) {
+        reason =
+            verificationCount === 0
+                ? `결론 ${conclusionCount}건 vs 검증 0건. 완료 선언 전에 실제 실행/측정 증거 (npm test, curl, Read 결과 등) 를 턴에 포함시켜 재응답.`
+                : `결론/검증 비율 ${ratio.toFixed(1)} (${conclusionCount}/${verificationCount}) > ${threshold}. 결론에 비해 검증 서술이 적음 — 증거(실행 결과/측정값) 를 추가하여 재응답.`;
+    }
+    return { block, conclusionCount, verificationCount, ratio, reason };
+}

package/dist/checks/fact-vs-agreement.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Forgen v0.4.1 — TEST-1: 사실 vs 합의 가드
+ *
+ * 목적: Claude 가 "동작합니다 / 통과했습니다 / 검증됐습니다" 같은 **사실 주장**을
+ *   내놓을 때, 그 턴(또는 최근 N턴)에 실제 측정/검증을 수행한 도구 호출이 있었는가?
+ *   측정 없이 합의(agreement)만으로 사실로 변환된다면 alert.
+ *
+ * 배경 (RC1): v0.4.0 릴리즈 직전 self-assessment 에서 점수가 조금씩 올라가는데
+ *   측정 도구 호출은 0건인 케이스가 반복. 메타 점수 인플레이션 (TEST-2 / US-13)
+ *   의 직전 단계. 여기서는 alert 레벨까지만 — block 은 TEST-2 에서.
+ *
+ * 순수 함수 설계: I/O 없이 텍스트 + 측정 신호 메타데이터만 받아 판정.
+ *   Stop hook / session scorer / CLI 어느 쪽에서도 호출 가능.
+ */
+/** TEST-1 판정 입력. */
+export interface FactCheckInput {
+    /** Claude 의 최근 턴 응답 텍스트. */
+    text: string;
+    /**
+     * 최근 N 턴에서 실행된 도구 이름 목록 (중복 OK). 없으면 빈 배열.
+     * 호출지가 0턴/전체 세션 등 윈도우를 결정한다.
+     */
+    recentTools: string[];
+    /**
+     * optional: 측정으로 간주할 최소 tool count. 기본 1.
+     * 빌드/테스트같은 확정 측정 1회면 충분하다고 간주.
+     */
+    minMeasurements?: number;
+}
+export interface FactCheckResult {
+    /** true = 측정 없는 사실-주장 감지, alert 필요. */
+    alert: boolean;
+    /** 매칭된 사실-주장 키워드 (최대 3개). */
+    factAssertions: string[];
+    /** 감지된 합의/추측 신호 (최대 3개). */
+    agreementSofteners: string[];
+    /** 관찰된 측정성 도구 호출 수. */
+    measurementCount: number;
+    /** 호출지가 surface 하기 좋은 사람-읽기 이유. */
+    reason: string;
+}
+/**
+ * 핵심 판정 — 텍스트에 사실-주장이 있고 측정 도구가 없으면 alert.
+ * 측정이 있거나 사실-주장이 없으면 alert=false.
+ * 합의 softener 는 참고용 — softener 많을수록 reason 에 경고 추가.
+ */
+export declare function checkFactVsAgreement(input: FactCheckInput): FactCheckResult;