@wooojin/forgen 0.4.13 → 0.5.5

package/README.md

@@ -3,8 +3,9 @@
 </p>
 
 <p align="center">
-  <strong>When your agent says "done", forgen makes it prove it.</strong><br/>
-  Turn-level self-verification + personalized rules for <strong>Claude Code</strong> and <strong>Codex CLI</strong>, at <strong>$0 extra API cost</strong>.
+  <strong>forgen makes Claude fit <em>you</em> — and measures whether that actually helps, honestly.</strong><br/>
+  Your corrections become persistent rules; past solutions resurface when relevant; stale ones fade.<br/>
+  For <strong>Claude Code</strong> and <strong>Codex CLI</strong>, at <strong>$0 extra API cost</strong>.
 </p>
 
 <p align="center">
@@ -35,7 +36,7 @@
 
 ## 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.
+Here's forgen's most *visible* mechanism — a live guard you can trigger in 30 seconds. Fair warning up front (this is the honest-measurement tool, after all): on current frontier models this particular guard rarely fires, because Opus 4.8 / Sonnet 5 mostly stopped making unverified "done" claims on their own (we measured **blocks = 0** — see the caveat below). So treat this as a **safety net for weaker models and the occasional tail case**, not forgen's daily value. The daily value is quieter: your corrections becoming rules, and past solutions resurfacing. But the guard is the fastest thing to *see*, so we lead with it.
 
 ```
 You:     "Update the auth middleware."
@@ -57,7 +58,7 @@ Claude:  "측정 없이 점수를 매겼습니다. 실 테스트부터 실행합
 
 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. Codex CLI gets the same treatment via the symmetric host adapter (v0.4.3, [multi-host core design](docs/superpowers/specs/2026-04-27-forgen-multi-host-core-design.md)). 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**.
+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. Codex CLI gets the same treatment via the symmetric host adapter (v0.4.3, [multi-host core design](docs/superpowers/specs/2026-04-27-forgen-multi-host-core-design.md)). We verified it end-to-end on 10 scenarios at $1.74 total cost (A1 spike report — archived in git history, `docs/spike/` pre-v0.5.0), and v0.4.1 added built-in guards so you get the first block **without writing any rule**.
 
 > **v0.4.3 self-correction story:** the same guards detected their own 16-day false-positive (strict φ 65.66% — 84% from a single Korean-regex bug), and the [`forgen-eval`](packages/forgen-eval/) introspect testbed (alpha) flagged a `TEST-1` wiring gap on top of it. Both fixes shipped in v0.4.3 — forgen finding and fixing forgen. Details in [CHANGELOG](CHANGELOG.md).
 
@@ -73,18 +74,53 @@ This is **Mech-B self-check prompt-inject**. It works because Claude Code's Stop
 > is rescinded as a broken-testbed artifact; ψ (forgen+mem coexistence) is
 > confirmed as ≈0 — **forgen alone is the recommended path**. See
 > [`docs/release/v0.4.5-draft.md`](docs/release/v0.4.5-draft.md).
-
-🎬 **See it happen** (27 seconds):
+>
+> **Scope caveat (v0.5.0, ADR-010 + 2026-07-20 honest null):** the δ numbers
+> above were measured on the **models of their era** (Claude Sonnet 4.x-class,
+> Codex) and we do **not** carry them forward as a claim about current frontier
+> models. Two separate current-model findings, kept distinct:
+>
+> 1. **Completion-guard / false-completion pressure → null (honest).** On
+> **Opus 4.8** and **Sonnet 5** we measured completion-guard **blocks = 0** —
+> frontier models got honest on their own. Our v0.5.0 judge redesign re-scored the
+> hard "false-completion pressure" cases and found **no measurable behavioral δ
+> on that dataset** (all arms avoid blatant false completion;
+> [`docs/release/v0.5.0-recalibration.md`](docs/release/v0.5.0-recalibration.md)).
+> We publish that null rather than bury it.
+>
+> 2. **Cross-session user-specific policy adherence → δ > 0 (measured).** forgen's
+> real mechanism is not blocking but *re-injecting your corrections in a later
+> session where a vanilla model has no memory of them*. On that — the honest place
+> the effect lives — we measured a **significant δ**: forgen makes the model follow
+> the user's prior-session policies **14/14**, vanilla **4/14 (Sonnet 5)** / **7/14
+> (Opus 4.8)** → **δ = 0.714, 95% CI [0.429, 0.929]** (Sonnet 5) and **δ = 0.500,
+> 95% CI [0.214, 0.786]** (Opus 4.8), confirmed by a blind human rater (Cohen's
+> κ = 0.748 vs the LLM judge)
+> ([`docs/release/v0.5.0-persistence-delta.md`](docs/release/v0.5.0-persistence-delta.md)).
+> **δ is orthogonal to model capability** — the stronger model (Opus) follows more
+> general good-practice on its own, so δ shrinks there, but on *user-specific*
+> policies neither model guesses right and only forgen does. This is
+> **"internal measurement" grade**: the dataset is maintainer-authored (bootstrap),
+> the judge is intra-family (Claude), and only one human rater has confirmed it. We
+> do **not** make external effect claims until an independent rater panel + external
+> reviewer + a cross-family judge reproduce it.
+>
+> What forgen reliably provides: **personalization** (corrections → persistent
+> rules, cross-session δ above), **recall** (past solutions injected when relevant),
+> **ROI demotion** of stale knowledge, and **deterministic guards** (secrets,
+> destructive commands) that fire regardless of model honesty. Per-model guard
+> behavior: measured-honest models get advisory mode instead of blocking.
+
+🎬 **See it happen** — try the guard live on your own install:
 
 ```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
+# Real hook, real block: a self-score claim with zero measurement evidence
+echo '{"session_id":"demo","last_assistant_message":"이번 작업 신뢰도 90% 로 평가됩니다."}' \
+  | node "$(npm root -g)/@wooojin/forgen/dist/hooks/stop-guard.js"
+# → decision:"block" + the exact reason Claude reads on its next turn
 ```
 
-See [`docs/demo/README.md`](docs/demo/README.md) for what's real vs simulated in the demo.
+(The pre-v0.5.0 scripted demo lived in `docs/demo/` — archived in git history.)
 
 ---
 
@@ -179,20 +215,21 @@ Behind the scenes:
 
 You say: "Don't refactor files I didn't ask you to touch."
 
-Claude calls the `correction-record` MCP tool. The correction is stored as structured evidence with axis classification (`judgment_philosophy`), kind (`avoid-this`), and confidence score. A temporary rule is created for immediate effect in the current session.
+Claude calls the `correction-record` MCP tool. The correction is stored as structured evidence with axis classification (`judgment_philosophy`), kind (`avoid-this`), and confidence score. A temporary rule is created for immediate effect in the current session. At session end it promotes to a **permanent rule** — this deterministic corrections → rules path runs with **zero network egress** and is what our measured cross-session δ rides on.
+
+Softer corrections you never explicitly flag ("음… 이렇게 최소로만 짜면 나중에 다 다시 해야 하는 거 아니야?") are harder to catch in real time. If you opt into transcript extraction (below), forgen also **retroactively mines** those from the conversation — but such auto-mined rules are **advisory-only** (they surface as context, never block or enforce) and age out if you never act on them.
 
 ### Between sessions (automatic)
 
-When a session ends, auto-compound extracts:
-- Solutions (reusable patterns with context)
-- Behavioral observations (how you work)
-- A session learning summary
+**Always on (deterministic, zero egress):** your explicit corrections promote to permanent rules; near-duplicate corrections cluster and strengthen; facets micro-adjust from accumulated evidence; a time-based `compound sweep` backstop (optionally on cron) makes sure long or interrupted sessions don't lose that learning.
 
-Facets are micro-adjusted based on accumulated evidence. If your corrections consistently point away from your current pack, mismatch detection triggers after 3 sessions and recommends a pack change.
+**Opt-in (`forgen compound consent on`):** a background Haiku pass reads a *redacted summary* of the session transcript to extract reusable solutions, behavioral observations, and the softer corrections above. This is **off by default** — forgen does not send your conversations anywhere unless you turn it on, and secrets / `<private>` ranges are stripped before anything is sent. `forgen doctor` always shows the current state.
+
+If your corrections consistently point away from your current pack, mismatch detection triggers after 3 sessions and recommends a pack change.
 
 ### Next session
 
-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.
+Updated rules are rendered with your corrections included. Compound knowledge is searchable via MCP. The retrieval mechanism is in place from day 1 (starter-pack covers common dev queries on a fresh install); as you accumulate your own solutions, low-fitness ones get auto-demoted (ROI loop) and your specific patterns get promoted, so what surfaces skews toward *your* corpus over time. We describe this as a mechanism, not a measured speedup — we make no effect-size claim (see the honest-null caveat above).
 
 ---
 
@@ -207,6 +244,7 @@ forgen install both         # 3-choice interactive: claude / codex / both
 # or non-interactive:
 forgen install claude
 forgen install codex
+# Codex only: trust the forgen hooks once with `/hooks` inside codex — Codex skips untrusted hooks (forgen doctor shows [Codex Hooks])
 
 # 3. First run — 4-question onboarding (English or Korean)
 forgen                       # default: Claude
@@ -229,7 +267,7 @@ forgen doctor --quick
 
 > **Vendor dependency:** Forgen wraps Claude Code and Codex CLI symmetrically (Claude is the behavior reference; Codex extends with equivalence). Upstream API/CLI changes may affect behavior. Tested with Claude Code 1.0.x / 2.1.x and Codex 0.x.
 
-> **Upgrading from v0.4.x?** Run `forgen install claude` (or `codex` / `both`) after upgrading — v0.4.3+ requires explicit host registration. Then `forgen doctor --quick` to verify.
+> **Upgrading from v0.4.x?** Run `forgen install claude` (or `codex` / `both`) after upgrading — v0.4.3+ requires explicit host registration. Then run `forgen migrate tenetx --dry-run` to preview and reclaim legacy global rule sprawl (v0.5.0 moved ALL rule injection to project scope — stale `~/.claude/rules/forge-*.md` from older versions should be reclaimed; see CHANGELOG). Finally `forgen doctor --quick` to verify.
 
 ### Try your first block
 
@@ -349,8 +387,8 @@ entries in `~/.forgen/state/implicit-feedback.jsonl`. Idempotent — safe to re-
            |                                                |
            v                                                |
   +------------------+                                      |
-  | Session Ends     |   auto-compound extracts:            |
-  |                  |   solutions + observations + summary  |
+  | Session Ends     |   corrections -> rules (always, egress 0) |
+  |                  |   transcript extract: opt-in (Haiku)     |
   +--------+---------+                                      |
            |                                                |
            v                                                |
@@ -399,6 +437,30 @@ Each solution starts as an `experiment`. As it gets reflected in your code acros
 | **Behavioral patterns** | Auto-detected at 3+ observations | Applied to `forge-behavioral.md` |
 | **Evidence** | Corrections + observations | Drives facet adjustments + rule creation |
 
+*Solutions and behavioral patterns come from the **opt-in** transcript-extraction pass (`forgen compound consent on`, off by default). Corrections → rules and facet adjustments are always-on and never leave your machine.*
+
+### Keeping things out of the corpus (`<private>`)
+
+Wrap anything you don't want learned in a `<private>…</private>` block, or end a
+line with a `// forgen:private` marker (`#` and `/*` comment styles also work):
+
+```
+Here's the approach — <private>internal API key rotation playbook</private> — use it.
+const token = "…";  // forgen:private
+```
+
+Those ranges are stripped before every learning-corpus capture path: correction
+records, solution extraction, the automatic session-end compound runner,
+prompt-history, and session-search indexing. Unclosed or malformed tags **fail
+closed** (treated as private to end-of-text) so a forgotten `</private>` never
+leaks.
+
+> **Scope:** `<private>` controls **what forgen learns from**, not what the model
+> sees. The text was already sent to Claude as part of your conversation — the tag
+> excludes it from persistent capture (compound solutions, evidence, search index),
+> it does not make the current turn private. This is a separate axis from the
+> secret-filter, which blocks credentials from being committed.
+
 ### Solution auto-injection
 
 Every prompt you type is matched against your accumulated solutions. Relevant ones are automatically injected into Claude's context — no manual lookup needed.
@@ -672,9 +734,10 @@ forgen skill list               # List promoted skills
 
 ```bash
 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 migrate [implicit-feedback|evidence-host|tenetx|all]
+                                # One-shot migrations (idempotent). tenetx: reclaim
+                                # legacy global rules (--dry-run/--yes/--apply-settings)
+forgen doctor                   # Forgen-specific diagnostics (plugin cache, hooks, state, parity, gates — env health: native /doctor)
 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
@@ -712,7 +775,7 @@ 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
+node scripts/self-gate-release.cjs  # Tag-only: version/tag/CHANGELOG/dist/smoke-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).
@@ -843,7 +906,7 @@ forgen and [claude-mem](https://github.com/thedotmack/claude-mem) solve **comple
 | **Trigger** | Stop / PreToolUse hooks | UserPromptSubmit hook |
 | **Cost** | $0 (in-turn block/reason) | $0 (vector recall, local) |
 
-Install both as separate Claude Code plugins (Plugin model — forgen does not bundle claude-mem; AGPL-3.0 stays at arm's length). When both are present forgen's auto-detect yields context budget so claude-mem's recall has room to land, and the orchestration contract — order, failure isolation, Stop-hook ownership — is documented in [ADR-004](docs/adr/ADR-004-claude-mem-hook-orchestration.md). The pairing is one of the 5 arms tracked by [forgen-eval](packages/forgen-eval/) (see [claude-mem spike](docs/spike/2026-04-28-claude-mem-spike.md)).
+Install both as separate Claude Code plugins (Plugin model — forgen does not bundle claude-mem; AGPL-3.0 stays at arm's length). When both are present forgen's auto-detect yields context budget so claude-mem's recall has room to land, and the orchestration contract — order, failure isolation, Stop-hook ownership — is documented in [ADR-004](docs/adr/ADR-004-claude-mem-hook-orchestration.md). The pairing is one of the 5 arms tracked by [forgen-eval](packages/forgen-eval/) (claude-mem spike report — archived in git history, `docs/spike/` pre-v0.5.0).
 
 ```
 You:        "fix the auth flow"

package/README.zh.md

@@ -55,19 +55,19 @@ Claude:  "撤回完成声明。证据文件不存在。先执行 e2e..."
 
 **刚刚发生了什么**: 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))。
+这就是 **Mech-B 自检 prompt-inject**。它工作是因为 Claude Code 的 Stop hook 接受 `decision: "block"` + `reason`, 而 Claude 在下一轮把那个 reason 作为输入读取。我们用 10 个场景、$1.74 总成本端到端验证 (A1 spike report — 已归档于 git 历史, `docs/spike/` pre-v0.5.0)。
 
 🎬 **观看实际运行** (27秒):
 
 ```bash
 # 现场观看完整循环 — 真实的 hook、真实的规则、真实的 block/approve 周期
-bash docs/demo/mech-b-demo.sh
+# demo 脚本已归档于 git 历史 (docs/demo/ pre-v0.5.0)
 
 # 或重放预录制的 asciinema cast
-asciinema play docs/demo/mech-b-block-unblock.cast
+# asciinema cast 同上
 ```
 
-关于 demo 中"真实 vs 模拟"的详情见 [`docs/demo/README.md`](docs/demo/README.md)。
+
 
 ---
 
@@ -162,16 +162,17 @@ forgen                    # 用它代替 `claude`
 
 你说: "不要重构我没要求你动的文件。"
 
-Claude 调用 `correction-record` MCP 工具。纠正作为结构化证据存储，包含轴分类（`judgment_philosophy`）、种类（`avoid-this`）和置信度分数。为当前会话创建一条临时规则以立即生效。
+Claude 调用 `correction-record` MCP 工具。纠正作为结构化证据存储，包含轴分类（`judgment_philosophy`）、种类（`avoid-this`）和置信度分数。为当前会话创建一条临时规则以立即生效。会话结束时，该规则会晋升为**永久规则** —— 这条确定性的 corrections → rules 路径以**零网络 egress** 运行，我们测得的 cross-session δ 正是建立在这条路径上。
+
+那些你从未明确指出的柔性纠正（"嗯…只写这么点最小实现，以后不会全部返工吗?"）在实时中更难捕捉。如果你 opt-in 启用 transcript 提取（见下文），forgen 还会从对话中**回溯挖掘（retroactively mine）**这类纠正 —— 但这样自动挖掘出的规则是 **advisory-only**（仅作为上下文呈现，绝不阻断或强制），若你始终不采纳，它们会随时间 age-out。
 
 ### 会话之间（自动）
 
-会话结束时，auto-compound 提取:
-- 解决方案（带上下文的可复用模式）
-- 行为观察（你的工作方式）
-- 会话学习摘要
+**Always on（确定性，egress 0）:** 你的明确纠正晋升为永久规则; 近乎重复的纠正被聚类并强化; facet 基于累积证据微调; 一个基于时间的 `compound sweep` 兜底机制（可选择挂到 cron）确保漫长或被中断的会话不会丢失这些学习。
 
-基于累积的证据对 facet 进行微调。如果你的纠正持续指向与当前 pack 不同的方向，3个会话后触发不匹配检测，推荐更换 pack。
+**Opt-in（`forgen compound consent on`）:** 后台的 Haiku 通道读取会话 transcript 的*脱敏（redacted）摘要*，提取可复用的解决方案、行为观察，以及上述柔性纠正。它**默认关闭** —— 除非你开启，否则 forgen 不会把你的对话发送到任何地方，且在发送前会剥离 secret / `<private>` 区间。`forgen doctor` 始终显示当前状态。
+
+如果你的纠正持续指向与当前 pack 不同的方向，3个会话后触发不匹配检测，推荐更换 pack。
 
 ### 下一个会话
 
@@ -190,6 +191,7 @@ forgen install both          # 三选交互: claude / codex / both
 # 或非交互:
 forgen install claude
 forgen install codex
+# 仅 Codex: 在 codex 内用 `/hooks` 信任一次 forgen 钩子 — Codex 会跳过未信任的钩子 (用 forgen doctor 的 [Codex Hooks] 查看)
 
 # 3. 首次运行 — 4题引导问卷 (英语/韩语选择)
 forgen                        # 默认: Claude
@@ -269,8 +271,8 @@ forgen config default-host codex   # 设置持久默认主机
            |                                                |
            v                                                |
   +------------------+                                      |
-  |   会话结束        |   auto-compound 提取:                 |
-  |                  |   解决方案 + 观察 + 摘要                |
+  |   会话结束        |   corrections -> rules (始终, egress 0)  |
+  |                  |   transcript 提取: opt-in (Haiku)        |
   +--------+---------+                                      |
            |                                                |
            v                                                |
@@ -300,6 +302,8 @@ experiment (0.30) → candidate (0.55) → verified (0.75) → mature (0.90)
 | **行为模式** | 3次以上观察时自动检测 | 应用到 `forge-behavioral.md` |
 | **证据** | 纠正 + 观察 | 驱动 facet 调整 + 规则创建 |
 
+*解决方案与行为模式来自 **opt-in** 的 transcript 提取通道（`forgen compound consent on`，默认关闭）。corrections → rules 与 facet 调整则始终在线（always-on），绝不离开你的机器。*
+
 ### 解决方案自动注入
 
 你输入的每个提示都会与你积累的解决方案进行匹配。相关的解决方案会自动注入 Claude 的上下文 — 无需手动查找。

package/assets/claude/commands/forge-loop.md

@@ -88,13 +88,19 @@ PRD 확정 직후 **반드시** `~/.forgen/state/forge-loop.json`에 저장:
 mkdir -p ~/.forgen/state
 cat > ~/.forgen/state/forge-loop.json <<EOF
 {"active":true,"startedAt":"$(date -u +%Y-%m-%dT%H:%M:%SZ)","stories":[
-  {"id":"US-001","title":"...","passes":false,"attempts":0}
+  {"id":"US-001","title":"...","passes":false,"attempts":0,"acceptanceCriteria":["..."]}
 ]}
 EOF
 ```
 
 이 파일이 있어야 Claude가 중간에 멈추지 않도록 Stop 훅이 차단합니다.
+소유 세션은 최초 차단 시점에 Stop 훅이 자동 귀속하므로(`sessionId` 필드) 이
+파일을 쓸 때 세션 ID를 직접 넣을 필요는 없습니다 — 단, 귀속된 세션과 다른
+세션에서는 이 루프가 차단하지 않습니다. 24시간 이상 갱신이 없으면 자동
+해제(1회성 안내 포함)되며, 연속 30회 차단 시에도 안전 상한으로 자동 해제됩니다.
 스토리 완료 시 `passes: true`로 업데이트. 전체 완료는 Stop 훅이 자동 처리.
+`acceptanceCriteria[0]`은 차단 메시지에 `AC1:`로 노출되므로 있으면 첫 항목을
+구체적이고 검증 가능한 문장으로 작성하세요 (없어도 정상 동작).
 
 ### goal-only 모드 — Phase 1 종료 분기
 

package/assets/claude/commands/ship.md

@@ -166,10 +166,27 @@ npm version {patch|minor|major} --no-git-tag-version
 
 커밋을 주제별 그룹핑 -> CHANGELOG.md 상단에 추가.
 
+## Step 6.5: Smoke 증거 생성 (forgen 레포 한정)
+
+forgen 레포 자체를 ship 할 때는 릴리스 커밋 전에 smoke 증거를 생성한다
+(ADR-010 W0-2 — CI self-gate 가 릴리스 커밋에서 smoke-report 를 요구).
+
+```bash
+# forgen 레포에서만. vitest 는 Step 3 에서 이미 돌았지만 게이트 증거는
+# smoke.cjs 산출물만 인정 — 전체 실행 (실제 프로세스 산출물 원칙).
+if [ -f scripts/smoke.cjs ]; then
+  node scripts/smoke.cjs || ABORT
+fi
+```
+
+- 실패 -> ABORT ("smoke 증거 생성 실패 — 게이트 통과 불가")
+
 ## Step 7: 릴리스 커밋
 
 ```bash
-git add package.json CHANGELOG.md
+git add package.json package-lock.json CHANGELOG.md
+# forgen 레포: smoke 증거 포함
+[ -f .forgen-release/smoke-report.json ] && git add .forgen-release/smoke-report.json
 git commit -m "release: v{version}"
 ```
 

package/assets/opencode/forgen.ts

@@ -0,0 +1,52 @@
+// forgen-managed — do not edit; regenerated by `forgen install opencode`
+/**
+ * forgen — OpenCode plugin (W3-3 P1). forgen 결정적 가드 + 개인화 브릿지:
+ *   - tool.execute.before → forgen opencode-guard → block 이면 throw(도구 차단).
+ *   - experimental.session.compacting → forgen opencode-context → forge-loop 상태 유지.
+ * 얇은 shim — 로직은 forgen 소유(drift-free). async execFile(이벤트루프 비차단).
+ * GUARD_CMD/CONTEXT_CMD 는 install-opencode 가 절대경로로 치환(런타임 PATH 비의존).
+ */
+import { execFile } from "node:child_process"
+
+// forgen:guard-cmd — install-opencode 가 [node, <절대 cli 경로>, opencode-guard] 로 치환
+const GUARD_CMD: string[] = ["forgen", "opencode-guard"]
+// forgen:context-cmd — install-opencode 가 [node, <절대 cli 경로>, opencode-context] 로 치환
+const CONTEXT_CMD: string[] = ["forgen", "opencode-context"]
+
+function runForgen(cmd: string[], stdin: string, timeout: number): Promise<string> {
+  return new Promise((resolve) => {
+    const [bin, ...rest] = cmd
+    const child = execFile(bin, rest, { timeout, encoding: "utf-8" }, (err, stdout) => {
+      if (err) console.error("[forgen] 호출 실패(fail-open):", err.message)
+      resolve(stdout || "")
+    })
+    child.stdin?.end(stdin)
+  })
+}
+
+export const forgen = async () => ({
+  "tool.execute.before": async (
+    input: { tool?: string },
+    output: { args?: Record<string, unknown> },
+  ) => {
+    const out = await runForgen(GUARD_CMD, JSON.stringify({ tool: input?.tool, args: output?.args }), 8000)
+    let decision: { block?: boolean; reason?: string } = { block: false }
+    try {
+      if (out) decision = JSON.parse(out)
+    } catch {
+      /* fail-open */
+    }
+    if (decision.block) throw new Error(decision.reason || "[forgen] blocked by guard")
+  },
+  "experimental.session.compacting": async (
+    _input: unknown,
+    output: { context?: string[] },
+  ) => {
+    const ctx = await runForgen(CONTEXT_CMD, "", 5000)
+    if (ctx.trim() && Array.isArray(output?.context)) {
+      output.context.push(ctx.trim())
+    }
+  },
+})
+
+export default forgen

package/assets/shared/hook-registry.json

@@ -1,24 +1,212 @@
 [
-  { "name": "notepad-injector",       "tier": "compound-core", "event": "UserPromptSubmit",   "matcher": "*",          "script": "hooks/notepad-injector.js",       "timeout": 3, "compoundCritical": false },
-  { "name": "context-guard",          "tier": "compound-core", "event": "UserPromptSubmit",   "matcher": "*",          "script": "hooks/context-guard.js",          "timeout": 2, "compoundCritical": false },
-  { "name": "session-recovery",       "tier": "compound-core", "event": "SessionStart",       "matcher": "*",          "script": "hooks/session-recovery.js",       "timeout": 3, "compoundCritical": true  },
-  { "name": "post-tool-use",          "tier": "compound-core", "event": "PostToolUse",        "matcher": "*",          "script": "hooks/post-tool-use.js",          "timeout": 3, "compoundCritical": true  },
-  { "name": "pre-compact",            "tier": "compound-core", "event": "PreCompact",         "matcher": "*",          "script": "hooks/pre-compact.js",            "timeout": 3, "compoundCritical": false },
-  { "name": "context-guard-stop",     "tier": "compound-core", "event": "Stop",               "matcher": "*",          "script": "hooks/context-guard.js",          "timeout": 5, "compoundCritical": false },
-  { "name": "stop-guard",             "tier": "compound-core", "event": "Stop",               "matcher": "*",          "script": "hooks/stop-guard.js",             "timeout": 10, "compoundCritical": true  },
-  { "name": "pre-tool-use",           "tier": "compound-core", "event": "PreToolUse",         "matcher": "*",          "script": "hooks/pre-tool-use.js",           "timeout": 3, "compoundCritical": true  },
-  { "name": "secret-filter",          "tier": "safety",        "event": "PostToolUse",        "matcher": "Write|Edit|Bash", "script": "hooks/secret-filter.js",     "timeout": 3, "compoundCritical": false },
-  { "name": "slop-detector",          "tier": "safety",        "event": "PostToolUse",        "matcher": "Write|Edit",      "script": "hooks/slop-detector.js",     "timeout": 3, "compoundCritical": false },
-  { "name": "db-guard",               "tier": "safety",        "event": "PreToolUse",         "matcher": "Bash",            "script": "hooks/db-guard.js",          "timeout": 3, "compoundCritical": false },
-  { "name": "rate-limiter",           "tier": "safety",        "event": "PreToolUse",         "matcher": "*",          "script": "hooks/rate-limiter.js",           "timeout": 2, "compoundCritical": false },
-  { "name": "intent-classifier",      "tier": "workflow",      "event": "UserPromptSubmit",   "matcher": "*",          "script": "hooks/intent-classifier.js",      "timeout": 3, "compoundCritical": false },
-  { "name": "keyword-detector",       "tier": "workflow",      "event": "UserPromptSubmit",   "matcher": "*",          "script": "hooks/keyword-detector.js",       "timeout": 5, "compoundCritical": false },
-  { "name": "permission-handler",     "tier": "workflow",      "event": "PermissionRequest",  "matcher": "*",          "script": "hooks/permission-handler.js",     "timeout": 2, "compoundCritical": false },
-  { "name": "subagent-tracker-start", "tier": "workflow",      "event": "SubagentStart",      "matcher": "*",          "script": "hooks/subagent-tracker.js start", "timeout": 2, "compoundCritical": false },
-  { "name": "subagent-tracker-stop",  "tier": "workflow",      "event": "SubagentStop",       "matcher": "*",          "script": "hooks/subagent-tracker.js stop",  "timeout": 2, "compoundCritical": false },
-  { "name": "subagent-stop-guard",    "tier": "workflow",      "event": "SubagentStop",       "matcher": "*",          "script": "hooks/subagent-stop-guard.js",    "timeout": 10, "compoundCritical": false },
-  { "name": "post-tool-failure",      "tier": "workflow",      "event": "PostToolUseFailure", "matcher": "*",          "script": "hooks/post-tool-failure.js",      "timeout": 3, "compoundCritical": false },
-  { "name": "solution-injector",     "tier": "compound-core", "event": "UserPromptSubmit",   "matcher": "*",          "script": "hooks/solution-injector.js",      "timeout": 5, "compoundCritical": true  },
-  { "name": "skill-injector",        "tier": "compound-core", "event": "UserPromptSubmit",   "matcher": "*",          "script": "hooks/skill-injector.js",         "timeout": 5, "compoundCritical": true  },
-  { "name": "forge-loop-progress",   "tier": "compound-core", "event": "UserPromptSubmit",   "matcher": "*",          "script": "hooks/forge-loop-progress.js",    "timeout": 2, "compoundCritical": false }
+  {
+    "name": "notepad-injector",
+    "tier": "compound-core",
+    "event": "UserPromptSubmit",
+    "matcher": "*",
+    "script": "hooks/notepad-injector.js",
+    "timeout": 3,
+    "compoundCritical": false
+  },
+  {
+    "name": "context-guard",
+    "tier": "compound-core",
+    "event": "UserPromptSubmit",
+    "matcher": "*",
+    "script": "hooks/context-guard.js",
+    "timeout": 2,
+    "compoundCritical": false
+  },
+  {
+    "name": "session-recovery",
+    "tier": "compound-core",
+    "event": "SessionStart",
+    "matcher": "*",
+    "script": "hooks/session-recovery.js",
+    "timeout": 3,
+    "compoundCritical": true
+  },
+  {
+    "name": "post-tool-use",
+    "tier": "compound-core",
+    "event": "PostToolUse",
+    "matcher": "*",
+    "script": "hooks/post-tool-use.js",
+    "timeout": 3,
+    "compoundCritical": true
+  },
+  {
+    "name": "pre-compact",
+    "tier": "compound-core",
+    "event": "PreCompact",
+    "matcher": "*",
+    "script": "hooks/pre-compact.js",
+    "timeout": 3,
+    "compoundCritical": false
+  },
+  {
+    "name": "context-guard-stop",
+    "tier": "compound-core",
+    "event": "Stop",
+    "matcher": "*",
+    "script": "hooks/context-guard.js",
+    "timeout": 5,
+    "compoundCritical": false
+  },
+  {
+    "name": "stop-guard",
+    "tier": "compound-core",
+    "event": "Stop",
+    "matcher": "*",
+    "script": "hooks/stop-guard.js",
+    "timeout": 10,
+    "compoundCritical": true
+  },
+  {
+    "name": "pre-tool-use",
+    "tier": "compound-core",
+    "event": "PreToolUse",
+    "matcher": "*",
+    "script": "hooks/pre-tool-use.js",
+    "timeout": 3,
+    "compoundCritical": true
+  },
+  {
+    "name": "secret-filter",
+    "tier": "safety",
+    "event": "PostToolUse",
+    "matcher": "Write|Edit|Bash",
+    "script": "hooks/secret-filter.js",
+    "timeout": 3,
+    "compoundCritical": false
+  },
+  {
+    "name": "slop-detector",
+    "tier": "safety",
+    "event": "PostToolUse",
+    "matcher": "Write|Edit",
+    "script": "hooks/slop-detector.js",
+    "timeout": 3,
+    "compoundCritical": false
+  },
+  {
+    "name": "db-guard",
+    "tier": "safety",
+    "event": "PreToolUse",
+    "matcher": "Bash",
+    "script": "hooks/db-guard.js",
+    "timeout": 3,
+    "compoundCritical": false
+  },
+  {
+    "name": "rate-limiter",
+    "tier": "safety",
+    "event": "PreToolUse",
+    "matcher": "*",
+    "script": "hooks/rate-limiter.js",
+    "timeout": 2,
+    "compoundCritical": false
+  },
+  {
+    "name": "intent-classifier",
+    "tier": "workflow",
+    "event": "UserPromptSubmit",
+    "matcher": "*",
+    "script": "hooks/intent-classifier.js",
+    "timeout": 3,
+    "compoundCritical": false
+  },
+  {
+    "name": "keyword-detector",
+    "tier": "workflow",
+    "event": "UserPromptSubmit",
+    "matcher": "*",
+    "script": "hooks/keyword-detector.js",
+    "timeout": 5,
+    "compoundCritical": false
+  },
+  {
+    "name": "permission-handler",
+    "tier": "workflow",
+    "event": "PermissionRequest",
+    "matcher": "*",
+    "script": "hooks/permission-handler.js",
+    "timeout": 2,
+    "compoundCritical": false
+  },
+  {
+    "name": "subagent-tracker-start",
+    "tier": "workflow",
+    "event": "SubagentStart",
+    "matcher": "*",
+    "script": "hooks/subagent-tracker.js start",
+    "timeout": 2,
+    "compoundCritical": false
+  },
+  {
+    "name": "subagent-tracker-stop",
+    "tier": "workflow",
+    "event": "SubagentStop",
+    "matcher": "*",
+    "script": "hooks/subagent-tracker.js stop",
+    "timeout": 2,
+    "compoundCritical": false
+  },
+  {
+    "name": "subagent-stop-guard",
+    "tier": "workflow",
+    "event": "SubagentStop",
+    "matcher": "*",
+    "script": "hooks/subagent-stop-guard.js",
+    "timeout": 10,
+    "compoundCritical": false
+  },
+  {
+    "name": "post-tool-failure",
+    "tier": "workflow",
+    "event": "PostToolUseFailure",
+    "matcher": "*",
+    "script": "hooks/post-tool-failure.js",
+    "timeout": 3,
+    "compoundCritical": false
+  },
+  {
+    "name": "solution-injector",
+    "tier": "compound-core",
+    "event": "UserPromptSubmit",
+    "matcher": "*",
+    "script": "hooks/solution-injector.js",
+    "timeout": 5,
+    "compoundCritical": true
+  },
+  {
+    "name": "skill-injector",
+    "tier": "compound-core",
+    "event": "UserPromptSubmit",
+    "matcher": "*",
+    "script": "hooks/skill-injector.js",
+    "timeout": 5,
+    "compoundCritical": true
+  },
+  {
+    "name": "forge-loop-progress",
+    "tier": "compound-core",
+    "event": "UserPromptSubmit",
+    "matcher": "*",
+    "script": "hooks/forge-loop-progress.js",
+    "timeout": 2,
+    "compoundCritical": false
+  },
+  {
+    "name": "session-end",
+    "tier": "compound-core",
+    "event": "SessionEnd",
+    "matcher": "*",
+    "script": "hooks/session-end.js",
+    "timeout": 3,
+    "compoundCritical": true,
+    "hosts": [
+      "claude"
+    ]
+  }
 ]