@wooojin/forgen 0.4.0 → 0.4.3

package/.claude-plugin/plugin.json

@@ -1,14 +1,14 @@
 {
   "$schema": "https://claude.ai/schemas/claude-plugin.json",
   "name": "forgen",
-  "version": "0.4.0",
+  "version": "0.4.3",
   "description": "Claude Code harness — the more you use Claude, the better it gets",
   "author": {
     "name": "jang-ujin",
-    "url": "https://github.com/wooo-jin"
+    "url": "https://github.com/forgen-team"
   },
-  "repository": "https://github.com/wooo-jin/forgen",
-  "homepage": "https://github.com/wooo-jin/forgen",
+  "repository": "https://github.com/forgen-team/forgen",
+  "homepage": "https://github.com/forgen-team/forgen",
   "license": "MIT",
   "keywords": [
     "claude-code",
@@ -17,7 +17,7 @@
     "forge"
   ],
   "skills": "./skills/",
-  "agents": "agents/",
+  "agents": "assets/claude/agents/",
   "statusLine": {
     "type": "command",
     "command": "forgen me"

package/CHANGELOG.md

@@ -5,6 +5,185 @@ 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.3] — 2026-04-30 — Self-correcting hotfix + testbed prep (alpha)
+
+forgen-eval introspect testbed (이번 릴리즈에 포함된 자기 측정 시스템) 가
+release-blocker 두 결함을 자가 진단 + fix 까지 한 사이클에 검증한 릴리즈.
+큰 v0.5.0 testbed-proof 셀링은 실 PASS gate 통과 후로 미루고, 본 릴리즈는
+*hotfix + testbed scaffolding alpha* 로 정직하게 박음.
+
+### Hotfix (forgen body)
+
+**TEST-6 — bypass-detector false-positive fix** (`fix`)
+- `src/engine/lifecycle/bypass-detector.ts`: Korean stop list (실행/사용/선언/수행/처리/작성/호출/적용 + 변형) + parens-heuristic 정밀화
+- 기존 root cause: Korean regex `(\S+)\s*(?:말라|금지|하지\s*마|쓰지\s*마)` 가 정책 텍스트 "rm -rf 실행하지 마라" 에서 "실행" 만 추출 → 모든 코드의 "실행" 단어가 false positive (RC5/E9).
+- Parens-heuristic: `(rm -rf, DROP, force-push)` 같은 *예시 목록*은 토큰 추출하되, file path (`tests/e2e/docker/run-test.sh`) 와 exclusion notes (`프로덕션 코드 맥락 한정, 테스트 파일 내 vi.mock 은 제외`) 는 skip.
+- 자기증거: 16일 사용 데이터에서 strict φ 65.66% 의 84% 가 이 단일 버그 (3 L1 rules: no-rm-rf-unconfirmed, e2e-before-done, no-mock-as-proof). 향후 0 false positive 박힘.
+
+**TEST-1 — fact-vs-agreement Stop hook wiring** (`fix`)
+- `src/hooks/stop-guard.ts`: `checkFactVsAgreement` import + alert-level invocation. `kind: 'correction'` (no block) — 원 design intent ("alert level only — block 은 TEST-2 에서") 준수.
+- 기존 결함: `src/checks/fact-vs-agreement.ts` 코드 존재했으나 어떤 hook 도 호출 안 함 (forgen-eval introspect 가 발견한 wiring gap).
+
+### Repo / infra
+
+**GitHub repo migration** (`chore`)
+- `wooo-jin/forgen` → `forgen-team/forgen` 이전 (1 star + 6 issues 자동 마이그레이션, redirect 자동)
+- npm scope `@wooojin/forgen` 그대로 유지 (npm scope ≠ GitHub org 정상 패턴)
+- 11 파일 URL bulk 갱신 (READMEs + plugin.json + CONTRIBUTING + CHANGELOG + SECURITY)
+
+**npm workspaces enable** (`chore`)
+- `"workspaces": ["packages/*"]` 추가 — forgen-eval 같은 부속 alpha package 호스팅용
+- 본 forgen 패키지 무게 영향 0 (peerDep 모델, forgen-eval은 별도 publish)
+
+### Testbed scaffolding (alpha — private workspace)
+
+**`@wooojin/forgen-eval@0.4.3-alpha.0` (private, not published)** (`feat`)
+- `packages/forgen-eval/` — forgen 효용 검증 testbed scaffolding
+- 7-축 메트릭: γ_slope (Cohen's d + Wilcoxon r), β_likert, δ/ε/ζ rate, φ Wilson-CI master gate, ψ weighted synergy
+- κ (Cohen's + Fleiss') judge agreement
+- 5 arms (vanilla / forgen-only / claude-mem-only via CLI invoke / forgen+mem / gstack)
+- DEV (Sonnet 4.6 + Qwen + Llama Triple) + PUBLIC (Qwen + Llama Dual) judge tracks
+- vitest 22/22 PASS
+
+**`forgen-team/forgen-eval-data` 외부 dataset repo** (`feat`)
+- https://github.com/forgen-team/forgen-eval-data — CC-BY-SA-4.0
+- 10 personas (4 academic + 3 github-issue + 3 forgen-user-anonymized, seed-unreviewed)
+- CURATION.md — 외부 PR 정책 (자체 작성 금지, 2-reviewer 강제)
+
+**claude-mem coexistence (Plugin model)** (`design`)
+- ADR-004 amendment — orchestration 가설 폐기, Plugin model 확정 (사용자가 둘 다 별도 plugin install)
+- forgen 본체에 claude-mem 의존성 추가 안 함 (AGPL-3.0 회피)
+- spec §10a — 6 사용자 시나리오 → 메트릭 매핑 narrative
+
+### Documentation
+
+- `docs/plans/2026-04-28-forgen-testbed-proof-spec.md` — Deep Interview 11라운드 spec
+- `docs/spike/2026-04-28-claude-mem-spike.md` — claude-mem 실측 (AGPL/Plugin model 발견)
+- `docs/adr/ADR-004/005/006-*.md` — coexistence / module / metrics ADRs
+- `docs/release/v0.5.0-checklist.md` — 미래 v0.5.0 게이트 (이 릴리즈는 *준비*)
+
+### 알려진 한계 — 정직 disclosure
+
+**φ master gate 미통과 (current 10.53%, target ≤ 5%)** — 이 릴리즈는 *측정 시스템*이지 *PASS 입증*이 아님:
+- TEST-6 fix 적용으로 strict φ 65.66% → 10.53% (84% reduction). 미래 introspect 사이클에서 추가 감소 예상.
+- 남은 5.53pp 는 user-rule scope 영역 (예: `.then` async/await 룰의 사용자 우회). Pattern bug 아님.
+- 진짜 PASS gate (φ ≤ 5%) 통과 시 v0.5.0 출시.
+
+**Self-evidence**: forgen 의 자기 검증 시스템 (`packages/forgen-eval/src/runners/introspect.ts`) 이 자기 자신의 패턴 매칭 버그를 6주 만에 정밀하게 짚어내고 fix 까지 검증한 첫 사이클. v0.4.0 trust restoration 미션이 self-correcting harness 로 한 발자국 더.
+
+### 회귀 검증
+- vitest: 2356/2356 (216 files)
+- bypass-detector: 14/14 (3 RC5/E9 regression 신규)
+- forgen-eval: 22/22
+- Docker e2e: 77/77 (`~/.forgen/state/e2e-result.json` round 14)
+- 회귀: 0
+
+## [0.4.2] - 2026-04-27
+
+### v0.4.2 — Trust hotfix + 학습 회로 4축 확장
+
+v0.4.1 이 신뢰 회복 릴리스였다면, v0.4.2 는 **외부 진단(trust-hotfix-report)을 측정으로 검증해 5개 W 를 닫고**, 동시에 v0.4.1 자기 분석에서 발견된 **자동 학습이 4축 중 2축에만 닿는 결함(D1)** 과 **검증 레이어 invariant 부재(P1~P4)** 까지 한 사이클에 통합한 릴리스.
+
+**M1 — RC6 가드: forge-loop findings 자동 inject** (`feat`)
+- `src/hooks/shared/forge-loop-state.ts` 신규 — readForgeLoopState / renderForgeLoopForSession / renderForgeLoopForPrompt
+- `session-recovery` (SessionStart) + `forge-loop-progress` (UserPromptSubmit) 신규 hook 이 직전 forge-loop findings 또는 진행 중 stories 를 ≤1KB 로 inject
+- 자기증거: head -80 truncation 으로 directly 유실됐던 사례 invariant 박제
+- Stale 24h soft / 7d hard cap, XML escape
+
+**D1'' — auto-compound axis_refs 4축 분류 확장** (`feat`)
+- `src/core/behavior-classifier.ts` 신규 — 5분기 (workflow/thinking/preference + **safety/autonomy** 신규)
+- LLM prompt 카테고리 7종으로 확장 ([품질안전], [자율성] 추가)
+- 결과: behavior_observation 자동 추출이 4축 모두에 닿음 (이전 2축 → 4축)
+- 측정 자기증거: behavior 627건 중 quality 7 / autonomy 6 만 explicit_correction 경로로 들어왔던 결함 해결
+
+**P2 — false-positive corpus golden test** (`test`)
+- `tests/invariants/no-false-positive-block.test.ts` (FP1~5 + RC5-E9, 8 케이스)
+- `tests/invariants/true-positive-block.test.ts` (E5/E6 정당 block 5 케이스)
+- 신규 detector CI gate — vitest 가 tests/invariants/* 자동 포함
+
+**P3' — Blocking ALLOW-LIST 정책 + denyOrObserve helper** (`feat`)
+- `src/hooks/shared/blocking-allowlist.ts` (4개 멤버: stop-guard / pre-tool-use / secret-filter / db-guard)
+- `denyOrObserve(hookName, reason, observer?)` helper — ALLOW-LIST 외 hook 의 deny 시도가 자동 관찰 모드로 강등
+- 점진 마이그레이션 시작점 (기존 hook 들은 별도 PR)
+
+**P4 — fix:feat 비율 셀프 가드** (`feat`)
+- `src/core/git-stats.ts` — 최근 30커밋 fix:feat 비율 측정 (fix(test):/fix(docs): 제외)
+- forgen stats 에 "Repo health" 섹션 + forgen doctor 가 30% 초과 시 경고
+- v0.4.2 릴리즈 시점 측정값: **29%** (정상 범위, ⚠ 미발생)
+
+**W1 — 한국어 README 설치 명령 오타 fix** (`fix`)
+- `README.ko.md:86, 146` 의 `npm install -g /forgen` → `@wooojin/forgen`
+- `tests/readme-install-contract.test.ts` 4 로케일 일치 invariant
+
+**W2 — 온보딩 2/4 문항 계약 통일** (`fix`)
+- `src/cli.ts:164, 469` 도움말 `2-question` → `4-question`
+- `src/forge/onboarding.ts` 주석 4문항 갱신 + spec 경로 정정 (docs/history/)
+- `tests/onboarding-contract.test.ts` — askChoice 호출 수 vs help text 일치
+
+**W3 — agent 인벤토리 12↔13 정렬** (`fix`)
+- `README.md:381` "12 built-in agents" → "13" + ch-solution-evolver Plan-only 표 추가
+- `tests/agent-inventory-contract.test.ts` — agents/ 디렉토리 = README + verify-v3.sh 단일 source
+
+**W4 — hooks-generator releaseMode 옵션** (`feat`)
+- `generateHooksJson({ releaseMode: true })` 환경 독립 모드 — plugin 감지 + hook-config 비활성화 모두 무시
+- `prepack-hooks.cjs` 가 releaseMode=true 사용 (HOME swap 도 유지하여 double safety)
+- `tests/hooks-generator-release-mode.test.ts` — mock plugin / mock disable 양쪽 검증
+
+**W5 — 하드코딩 → HOOK_REGISTRY.length 동적 read** (`refactor`)
+- 3 자리 (plugin-coexistence / harness-e2e / chain-verification) 의 `21` 하드코딩 제거 → 동적 length
+- `tests/contract-single-source.test.ts` 자체 invariant — 향후 하드코딩 추가 시 자동 fail
+- A3 false-positive 가드: hook-timing/cache-lock-integration 의 다른 의미 20 은 건드리지 않음
+
+**D2 — autonomy axis confidence 직접 경로** (`fix`)
+- `bumpAxisConfidence(axis, delta)` — explicit_correction 의 axis_hint 가 즉시 confidence bump
+- `evidence-processor.ts` 에서 호출: avoid-this +0.04, 그 외 +0.02
+- 자기증거: autonomy explicit_correction 6건이 score 못 움직였던 결함 해결
+- facet 값은 안 건드리고 confidence 만 — 회귀 위험 최소
+
+**자기증거 박제** (`docs`)
+- `docs/issues/D2-autonomy-facet-stuck.md` — D2 root cause 추적
+- `docs/issues/W4-W5-self-evidence.md` — 본 forge-loop 1차에서 W4/W5 antipattern 을 단기 회피로 재생산한 사례 (RC7 후보)
+- compound 4 박제: rc6-meta-amnesia, rc7-diagnostic-self-fix, validator-layer-invariant, interview-axes-disconnect-RETRACTED
+
+**회귀**:
+- vitest **2215/2215** (199 files, 신규 13 테스트 파일)
+- Docker e2e **77/77 + ALL CHECKS PASSED** (round 12, mock_detected:false)
+- typecheck 0
+
+**Outstanding (별도 PR)**: P3' enforcement 의 기존 hook 마이그레이션, prepack-hooks.cjs 의 HOME swap 단순화
+
+---
+
+## [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
@@ -434,7 +613,7 @@ Three-phase evolution loop around the existing compound solution store:
 - **Pack Marketplace** — GitHub-based community pack sharing
   - `forgen pack publish <name>` — publish verified solutions to GitHub + registry PR
   - `forgen pack search <query>` — search community registry
-  - Registry: [wooo-jin/forgen-registry](https://github.com/wooo-jin/forgen-registry)
+  - Registry: [forgen-team/forgen-registry](https://github.com/forgen-team/forgen-registry)
 - **Lab compound events** — 6 new event types (compound-injected, compound-reflected, compound-negative, compound-extracted, compound-promoted, compound-demoted)
 - 83 new tests (solution-format, prompt-injection-filter, solution-index, compound-lifecycle, compound-extractor)
 
@@ -605,17 +784,17 @@ Three-phase evolution loop around the existing compound solution store:
 - Bilingual documentation (EN/KO)
 - Core CLI commands: `fgx` entrypoint
 
-[Unreleased]: https://github.com/wooo-jin/forgen/compare/v3.0.0...HEAD
-[3.0.0]: https://github.com/wooo-jin/forgen/compare/v2.1.0...v3.0.0
-[2.1.0]: https://github.com/wooo-jin/forgen/compare/v2.0.0...v2.1.0
-[2.0.0]: https://github.com/wooo-jin/forgen/compare/v1.7.0...v2.0.0
-[1.7.0]: https://github.com/wooo-jin/forgen/compare/v1.6.3...v1.7.0
-[1.6.3]: https://github.com/wooo-jin/forgen/compare/v1.6.2...v1.6.3
-[1.6.2]: https://github.com/wooo-jin/forgen/compare/v1.6.1...v1.6.2
-[1.6.1]: https://github.com/wooo-jin/forgen/compare/v1.6.0...v1.6.1
-[1.6.0]: https://github.com/wooo-jin/forgen/compare/v1.4.0...v1.6.0
-[1.4.0]: https://github.com/wooo-jin/forgen/compare/v1.3.0...v1.4.0
-[1.3.0]: https://github.com/wooo-jin/forgen/compare/v1.1.0...v1.3.0
-[1.1.0]: https://github.com/wooo-jin/forgen/compare/v1.0.1...v1.1.0
-[1.0.1]: https://github.com/wooo-jin/forgen/compare/v1.0.0...v1.0.1
-[1.0.0]: https://github.com/wooo-jin/forgen/releases/tag/v1.0.0
+[Unreleased]: https://github.com/forgen-team/forgen/compare/v3.0.0...HEAD
+[3.0.0]: https://github.com/forgen-team/forgen/compare/v2.1.0...v3.0.0
+[2.1.0]: https://github.com/forgen-team/forgen/compare/v2.0.0...v2.1.0
+[2.0.0]: https://github.com/forgen-team/forgen/compare/v1.7.0...v2.0.0
+[1.7.0]: https://github.com/forgen-team/forgen/compare/v1.6.3...v1.7.0
+[1.6.3]: https://github.com/forgen-team/forgen/compare/v1.6.2...v1.6.3
+[1.6.2]: https://github.com/forgen-team/forgen/compare/v1.6.1...v1.6.2
+[1.6.1]: https://github.com/forgen-team/forgen/compare/v1.6.0...v1.6.1
+[1.6.0]: https://github.com/forgen-team/forgen/compare/v1.4.0...v1.6.0
+[1.4.0]: https://github.com/forgen-team/forgen/compare/v1.3.0...v1.4.0
+[1.3.0]: https://github.com/forgen-team/forgen/compare/v1.1.0...v1.3.0
+[1.1.0]: https://github.com/forgen-team/forgen/compare/v1.0.1...v1.1.0
+[1.0.1]: https://github.com/forgen-team/forgen/compare/v1.0.0...v1.0.1
+[1.0.0]: https://github.com/forgen-team/forgen/releases/tag/v1.0.0

package/CONTRIBUTING.md

@@ -5,7 +5,7 @@ Thank you for your interest in contributing! forgen is a philosophy-driven Claud
 ## Quick Start
 
 ```bash
-git clone https://github.com/wooo-jin/forgen.git
+git clone https://github.com/forgen-team/forgen.git
 cd forgen
 npm install
 npm run build
@@ -95,4 +95,4 @@ forgen is built around five principles: `understand-before-act`, `decompose-to-c
 
 ## Questions
 
-Open a [GitHub Issue](https://github.com/wooo-jin/forgen/issues) for questions, bug reports, or feature proposals.
+Open a [GitHub Issue](https://github.com/forgen-team/forgen/issues) for questions, bug reports, or feature proposals.

package/README.ja.md

@@ -1,5 +1,5 @@
 <p align="center">
-  <img src="https://raw.githubusercontent.com/wooo-jin/forgen/main/assets/banner.png" alt="Forgen" width="100%"/>
+  <img src="https://raw.githubusercontent.com/forgen-team/forgen/main/assets/banner.png" alt="Forgen" width="100%"/>
 </p>
 
 <p align="center">
@@ -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行で報告させます。
@@ -156,22 +182,61 @@ Claude が `correction-record` MCP ツールを呼び出します。修正は、
 ## クイックスタート
 
 ```bash
-# 1. インストール
+# 1. インストール (グローバル CLI なので必ず -g)
 npm install -g @wooojin/forgen
 
-# 2. 初回実行 — 4問オンボーディング（英語/韓国語選択）
-forgen
+# 2. ホスト登録 — Claude Code / Codex / 両方
+forgen install both          # 3択インタラクティブ: claude / codex / both
+# または非対話:
+forgen install claude
+forgen install codex
 
-# 3. 以降毎日
-forgen
+# 3. 初回実行 — 4問オンボーディング (英語/韓国語選択)
+forgen                        # デフォルト: Claude
+forgen --runtime codex        # Codex で実行
+forgen config default-host codex   # 永続デフォルトホスト設定
 ```
 
 ### 前提条件
 
-- **Node.js** >= 20（SQLite セッション検索には >= 22 を推奨）
-- **Claude Code** インストール・認証済み（`npm i -g @anthropic-ai/claude-code`）
+- **Node.js** >= 20 (SQLite セッション検索には >= 22 を推奨)
+- **少なくとも 1 つのホスト** インストール・認証済み:
+  - **Claude Code** — `npm i -g @anthropic-ai/claude-code`
+  - **Codex CLI** — [Codex docs](https://github.com/openai/codex) を参照
+  - 両方利用可 — `forgen install both` が両方に hook/MCP を対称登録
+
+> **ベンダー依存:** forgen は Claude Code と Codex CLI を対称ラップします (Claude が動作基準、Codex が同等性拡張)。上流 API/CLI の変更が動作に影響する可能性があります。Claude Code 1.0.x / 2.1.x、Codex 0.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 は Claude Code をラップします。Anthropic API または Claude Code の変更が動作に影響する可能性があります。Claude Code 1.0.x でテスト済みです。
+`forgen migrate implicit-feedback` — pre-v0.4.1 ログの `category` フィールド
+バックフィル。冪等 (idempotent) — 複数回実行しても安全。
 
 ---
 

package/README.ko.md

@@ -1,5 +1,5 @@
 <p align="center">
-  <img src="https://raw.githubusercontent.com/wooo-jin/forgen/main/assets/banner.png" alt="Forgen" width="100%"/>
+  <img src="https://raw.githubusercontent.com/forgen-team/forgen/main/assets/banner.png" alt="Forgen" width="100%"/>
 </p>
 
 <p align="center">
@@ -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,12 +53,37 @@ 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분)
 
 ```bash
-npm install -g /forgen
+npm install -g @wooojin/forgen
 forgen
 ```
 
@@ -116,22 +142,61 @@ Claude가 `correction-record` MCP 도구를 호출합니다. 교정은 축 분
 ## 빠른 시작
 
 ```bash
-# 1. 설치
-npm install -g /forgen
-
-# 2. 첫 실행 — 4문항 온보딩 (영어/한국어 선택)
-forgen
-
-# 3. 이후 매일
-forgen
+# 1. 설치 (반드시 -g — forgen 은 글로벌 CLI)
+npm install -g @wooojin/forgen
+
+# 2. 호스트 등록 — Claude Code / Codex / 양쪽
+forgen install both          # 3지선다 인터랙티브: claude / codex / both
+# 또는 비대화형:
+forgen install claude
+forgen install codex
+
+# 3. 첫 실행 — 4문항 온보딩 (영어/한국어 선택)
+forgen                        # 기본: Claude
+forgen --runtime codex        # Codex 로 실행
+forgen config default-host codex   # 영구 기본 호스트 설정
 ```
 
 ### 사전 요구사항
 
 - **Node.js** >= 20 (SQLite 세션 검색은 >= 22 권장)
-- **Claude Code** 설치 및 인증 (`npm i -g @anthropic-ai/claude-code`)
+- **하나 이상의 호스트** 설치 및 인증:
+  - **Claude Code** — `npm i -g @anthropic-ai/claude-code`
+  - **Codex CLI** — [Codex docs](https://github.com/openai/codex) 참고
+  - 둘 다 사용 가능 — `forgen install both` 가 양쪽에 hook/MCP 를 대칭 등록
+
+> **벤더 의존성:** forgen 은 Claude Code 와 Codex CLI 를 대칭 래핑합니다 (Claude 가 동작 기준, Codex 가 동등성 확장). 상위 API/CLI 변경이 동작에 영향을 줄 수 있습니다. Claude Code 1.0.x / 2.1.x, Codex 0.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은 Claude Code를 래핑합니다. Anthropic API 또는 Claude Code 변경이 동작에 영향을 줄 수 있습니다. Claude Code 1.0.x 기준으로 테스트되었습니다.
+`forgen migrate implicit-feedback` — pre-v0.4.1 로그의 `category` 필드 백필.
+멱등(idempotent) — 여러 번 실행 안전.
 
 ---