@wooojin/forgen 0.5.0 → 0.5.6

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://claude.ai/schemas/claude-plugin.json",
   "name": "forgen",
-  "version": "0.5.0",
+  "version": "0.5.6",
   "description": "Claude Code harness — the more you use Claude, the better it gets",
   "author": {
     "name": "jang-ujin",

package/CHANGELOG.md

@@ -7,6 +7,242 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.5.6] — 2026-10-02 — Codex notify 폴백 · 훅 번들(재승인 2건) · Claude verify 스킬 (ADR-016)
+
+> **Codex 사용자 — 재승인 필요**: 업그레이드 후 `forgen install codex` 를 다시 실행하면 훅 2개
+> (`session_start` 변경, `session_end` 신규)가 Codex `/hooks` 승인 전까지 skip 된다. 그동안 Codex 세션에
+> `<forgen-rules>` 블록이 주입되지 않는다. install 출력과 `forgen doctor` 가 대상 훅을 표시한다.
+
+### Added
+- **Codex `notify` 폴백** (`dist/host/codex-notify.js`). `forgen install codex` 가 config.toml 최상단에 마커 블록으로
+  `notify` 를 등록한다. Codex 의 notify 는 훅 신뢰와 무관하게 턴 완료마다 detached 로 실행되므로, forgen 훅이
+  미승인/변경 상태로 조용히 skip 되는 동안에도 (a) `state/codex-hooks-silent.json` 에 관측을 남겨 `forgen doctor`
+  [Codex Hooks] 가 보여주고 (b) 프롬프트 ≥10 인 세션은 Stop 훅과 같은 디바운스 경로로 auto-compound 를 띄운다.
+  훅이 정상 실행 중이면(codex-adapter 의 alive 마커) 아무것도 하지 않는다. 사용자가 이미 `notify` 를 정의했으면
+  **건드리지 않는다** (수동 체인: argv 뒤에 `"--", "<program>", …`). 끄기: `--no-notify` (기존 블록도 제거).
+  `forgen uninstall` 도 블록을 제거한다. Codex 가 블록 사이에 써 넣은 root 키(`model` 등)와 BOM/CRLF 는 보존한다.
+- **Codex `SessionEnd` 훅** — `session-end` 를 Codex 에도 등록. Stop 없이 끝나는 세션의 학습 추출 트리거.
+  Codex rollout 의 실제 사용자 프롬프트(`event_msg`/`user_message`)를 raw 바이트 스캔으로 센다.
+- **Claude `verify` 스킬** — `forgen install claude` 가 `~/.claude/skills/verify/SKILL.md` 를 설치한다. Claude Code
+  2.1.286+ 는 project/user 스킬에 `verify` 가 있으면 코드 커밋 직전에 실행하도록 모델에 안내한다 (플러그인 스킬
+  `forgen:verify` 는 대상이 아님). 본문은 "프로젝트 자체 레시피 우선 → 실제 build/type-check/lint/test 실행 →
+  confirmed / refuted / unverified 판정, mock 통과는 증거 아님". 사용자가 만든 `verify` 스킬은 덮어쓰지 않고,
+  `forgen uninstall` 은 forgen 이 설치한 것만 제거한다. 끄기: `--no-verify-skill`. (npm postinstall 은 설치하지 않음 —
+  명시적 `forgen install claude` 에서만.)
+- `forgen install` 플래그 `--no-notify`, `--no-verify-skill`.
+
+### Fixed
+- **`forgen install codex` 재실행이 Codex 훅 신뢰를 전부 지우던 결함 (0.5.3~).** 신규 설치는 MCP 마커 블록을
+  config.toml 끝에 붙이는데, Codex 는 `/hooks` 승인 시 `[hooks.state]` 테이블을 파일 끝 주석(= forgen 의 END 마커)
+  *앞* 에 써 넣는다 — 즉 블록 안. 재설치가 블록을 통째로 교체하면서 22개 신뢰 기록, `[features]`, MCP 서버의
+  `enabled = false` 등이 사라졌다. 이제 forgen 이 쓴 줄만 다시 쓰고 사이에 끼어든 내용은 블록 뒤로 옮겨 보존한다.
+  (실 Codex 0.153.4 app-server 로 재현·수정 확인: 재설치 후 22/22 유지.)
+- Codex 추출 run(`codex exec --ephemeral`)에 `FORGEN_NESTED_RUN=1` 이 전달되지 않던 것 — forgen 훅이 추출 세션에서
+  발화하지 않도록 Claude 분기와 동일하게 표식.
+- `[mcp_servers.forgen-compound]` 가 마커 없이 이미 있으면 중복 테이블을 append 하지 않는다.
+
+### Changed
+- **Codex 훅 신뢰 감사가 해시를 대조한다.** `auditCodexHookTrust` 가 Codex 0.153.4 의 핸들러 단위 trust 해시를
+  계산해 `trusted` / `modified` / `untrusted` 를 구분한다. 이전엔 `hooks.state` 키의 존재만 봐서, 핸들러가 바뀌어
+  Codex 가 skip 하는 훅을 "trusted" 로 표시했다. `/hooks` 에서 끈 훅(`enabled = false`)은 `disabled` 로 따로 센다.
+  읽기 전용 대조이며 신뢰 기록은 쓰지 않는다.
+- **`session-recovery` 의 Codex 핸들러에 `additionalContextLimit: 0`.** Codex 는 약 10KB 를 넘는
+  `additionalContext` 를 임시 파일로 스필하고 모델에는 잘린 미리보기만 준다 — 한국어 룰 블록(상한 15,000자)은 이를
+  쉽게 넘는다.
+- `post-tool-failure` 를 Codex hooks.json 에서 제외 (`PostToolUseFailure` 는 Codex 이벤트가 아니라 무시되던 죽은 엔트리).
+- `forgen install codex` 는 config.toml 내용이 바뀔 때만 파일을 쓴다.
+- CI: 태그 푸시 발행을 npm Trusted Publishing(OIDC) 으로 전환, `release.yml`/`compat.yml` 에 누락됐던
+  `hooks/hooks.json` 생성 단계 추가 (v0.5.0 이후 태그 발행이 계속 실패하던 원인).
+
+### Not done (정직 표기 — ADR-016)
+- `async: true` 훅: Codex 는 같은 이벤트의 핸들러를 이미 동시 실행한다. 어댑터 경유 훅 1회 91~137ms 실측 →
+  이득 상한 ≈130ms/이벤트. 반면 async 는 block/deny 가 적용되지 않고 핸들러마다 재승인이 든다.
+- `PostCompact` / `Interrupt` 등록: 둘 다 컨텍스트 주입이 불가능하고 forgen 이 거기서 할 일이 없다.
+- 사용자 `notify` 자동 체인: TOML 임의 배열 재작성 + 원복 보장 불가로 수동 체인 안내만 제공.
+
+### Verified
+- vitest 3161 통과 (신규: trust 해시·notify 블록 upsert·notify 폴백 분기·rollout 카운터·verify 스킬 install/uninstall).
+- trust 해시: 실머신 `~/.codex/config.toml` 의 trusted_hash 20건과 일치 (fixture 8건 vendoring), 격리 `CODEX_HOME` 에서
+  forgen 계산 해시를 기록한 뒤 Codex `hooks/list` 가 22/22 `trusted` 로 판정 (`additionalContextLimit:0`·SessionEnd 포함).
+- 격리 Codex 0.153.4 실세션 (`codex exec`):
+  - 훅 미승인: notify 발화 → silent 기록, `forgen doctor` 가 "forgen 훅 미발화" 표시.
+  - 훅 승인: alive 마커(Stop) 기록 → notify 가 silent 를 지움, hook-timing 에 `SessionEnd:session-end (rt: codex)`.
+  - 스필: 21KB SessionStart 컨텍스트 — 기본값은 "Full hook output saved to" + 중간 내용 미전달, `additionalContextLimit:0`
+    은 전문 전달.
+- notify 폴백의 auto-compound 트리거: 실 바이너리 + 12-프롬프트 rollout 으로 러너 인자(cwd, rollout, session id, 12)와
+  `FORGEN_RUNTIME=codex` 전달, 재호출 시 in-flight 게이트로 skip 확인. (러너 자체는 스텁으로 대체 — LLM 추출은 이 검증 범위 밖.)
+- fresh-context critic 리뷰 1라운드: CRITICAL 2 · MAJOR 1 · MINOR 10 → 위 Fixed 항목 포함 전부 반영 또는 한계로 명시
+  (ADR-016 Review 절). 리뷰어의 실 Codex 재현 스크립트를 수정 후 빌드에 다시 돌려 통과 확인.
+- 이 머신의 실 `~/.codex` 에는 아직 설치하지 않았다 (재승인 전까지 룰 주입이 멈추므로 오너 결정 후).
+
+
+## [0.5.5] — 2026-10-01 — Codex Stop 분기 복구 (Stop 트리거 auto-compound·finalizeSession)
+
+### Fixed
+- `context-guard` 가 Stop 이벤트를 Claude 전용 `stop_hook_type` 필드로만 판별해, Codex 의 Stop 입력
+  (`hook_event_name:"Stop"` 만 있고 `stop_hook_type` 없음) 에서는 Stop 분기 전체가 건너뛰어졌다 →
+  Codex 세션은 `finalizeSession`, Stop 트리거 auto-compound(≥10 프롬프트), rate-limit 감지, 세션 종료
+  안내가 전혀 돌지 않고 컴팩션 때만 학습 추출됐다. `hook_event_name === "Stop"` 을 `end_turn` 과 동치로
+  인정. (0.5.4 실환경 검증 중 hook-timing 의 context-guard 가 Stop 시점에 `UserPromptSubmit` 로 기록되는
+  것을 보고 발견.)
+
+### Verified
+- vitest: Codex 형 Stop 입력으로 20-프롬프트 세션 종료 안내가 나오는 테스트 추가.
+- 격리 Codex 세션: hook-timing 에 `context-guard … event:"Stop", rt:"codex"` 기록, Stop 훅 Completed.
+
+
+## [0.5.4] — 2026-10-01 — Codex 훅 출력 스키마 준수 (0.5.3 의 Stop 훅 Failed 회귀 수정)
+
+### Fixed — Codex 가 forgen Stop 훅 출력을 매 턴 "Failed" 로 버리던 회귀
+- 0.5.3 의 사영(`projectCodexToClaude`)이 모든 출력에 `hookSpecificOutput.hookEventName` 을 붙였는데,
+  Codex 0.153.4 의 Stop/SubagentStop 출력 스키마는 `additionalProperties:false` 이고 `hookSpecificOutput`
+  을 허용하지 않는다 → `parse_stop` 실패 → "hook returned invalid stop hook JSON output" → **Failed**
+  (실환경 `codex exec` 에서 `hook: Stop Failed` ×2 재현; 훅 자체는 exit 0 + 정상 JSON). 0.5.3 격리 검증은
+  당시 사영이 stdin 의 `hook_event_name` 을 못 읽어 우연히 키를 안 붙인 상태라 통과했었다.
+- 사영을 **이벤트별 allowlist** 로 재작성 (`CODEX_OUTPUT_SCHEMA`): universal 키 / `decision`·`reason` 허용
+  이벤트 / `hookSpecificOutput` 허용 이벤트와 하위 키를 Codex 스키마 그대로 따르고, 절대 새 키를 만들지
+  않는다. PostToolUse 에 PreToolUse 형 deny 가 오면 Codex 의 PostToolUse block 형으로 번역.
+- 회귀 방지: `tests/fixtures/codex-hook-schemas/` 에 rust-v0.153.4 출력 스키마 11종을 vendoring 하고,
+  `tests/host/codex-output-schema.test.ts` 가 forgen 의 모든 응답 helper × 이벤트 조합을 사영 후 스키마로
+  검증한다.
+
+### Verified
+- 격리 Codex 세션: Stop 훅 3종(forgen 2 + 서드파티 1) 전부 `Completed`; `rm -rf` 응답 → `Stop Blocked` +
+  continuation 유지. 실환경 재설치 후 동일 확인 (아래 Install 절).
+- vitest 전체, self-gate static/runtime/release.
+
+
+## [0.5.3] — 2026-10-01 — Codex 동등화 2차 (룰 주입·에이전트·훅 신뢰) + Stop block 사영 결함 수정 + 최신 호스트 갭 1차
+
+오너가 Codex 를 일상 호스트로 전환하면서 "Claude 와 동일한 forgen 경험" 을 코드·실세션 대조로
+감사. 훅/MCP/스킬은 동등했으나 **개인화 룰과 서브에이전트가 Codex 에 전달되지 않는** 구조적
+갭을 발견·수정. 결정 문서: docs/adr/ADR-014-codex-parity-rules-agents.md.
+
+### Added — ADR-014
+- **D1 개인화 룰 주입 (Codex)**: `session-recovery` 가 `FORGEN_RUNTIME=codex` 일 때
+  `generateClaudeRuleFiles()` 산출(v1-rules / project-context / forge-behavioral / user-profile)을
+  Claude 와 동일 캡(`RULE_FILE_CAPS`)으로 `<forgen-rules host="codex">` 블록에 담아 SessionStart
+  additionalContext 로 주입. 컴팩션 후에는 두 호스트 모두 SessionStart 가 `source="compact"` 로 재발화
+  하므로 같은 경로가 재주입 (별도 플래그 경로 없음). 새 모듈 `src/host/codex-rules-context.ts`.
+  - 설계 이유: hooks.json 을 바이트 동일하게 유지해야 Codex 의 훅 신뢰 기록이 유효 → 새 훅이
+    아니라 기존 훅 내부 분기. AGENTS.md 파일 주입은 사용자 저장소에 개인 룰이 커밋될 위험.
+- **D2 Codex 커스텀 에이전트**: `forgen install codex` 가 `assets/claude/agents/*.md` 14종을
+  `~/.codex/agents/ch-<name>.toml` 로 생성 (공식 스키마 name/description/developer_instructions +
+  model_reasoning_effort/sandbox_mode 만 사용; `tools`/`disallowedTools` 양쪽에서 읽기전용 판정).
+  config.toml 에 `[features] multi_agent = true` 가 없으면 install 출력에 ⚠ 안내. Claude 설치명(ch-*)과 동일해 스킬 본문의
+  `ch-planner → ch-executor → ch-verifier` 참조가 Codex 에서도 해석됨. `# forgen-managed` 마커로
+  idempotent, 사용자 toml 보존.
+- **D3 스킬 Codex 적응**: 설치 시 `$ARGUMENTS`(Codex 미지원 변수) 자연어 치환 + "Codex host note"
+  (ch-* 에이전트 위치, spawn 불가 시 `invoke-agent` MCP 대체) 부착.
+- **D4 훅 신뢰 감사**: `auditCodexHookTrust()` 가 hooks.json forgen 엔트리 vs config.toml
+  `[hooks.state."<hooks.json>:<event>:<i>:<j>"]` 를 대조 (Codex 미지원 이벤트 PostToolUseFailure 는
+  `ignoredByCodex` 로 분리). `forgen install codex` 출력과 `forgen doctor` 의 새 `[Codex Hooks]`
+  섹션에 "N/M trusted, 미승인 시 codex 안에서 `/hooks`" 안내. trusted_hash 를
+  forgen 이 쓰지 않음(신뢰 모델 우회 금지).
+- **D5 측정**: `hook-timing.jsonl` 엔트리에 `rt: claude|codex` 필드.
+
+### Fixed — ADR-015 X-G1 (결함): Codex 에 Stop block 이 전달되지 않음
+- `codex-adapter` 의 사영(`projectCodexToClaude`)이 `decision:"block"` 을 `continue:false +
+  permissionDecision:"block"` 으로 변조해 내보냈다. Codex 는 top-level `decision`/`reason` 을 읽고
+  `continue:false` 를 "처리 중단" 으로 해석하므로 **stop-guard 의 자기검증 차단이 Codex 에서 한 번도
+  continuation 을 만들지 못했다**. 사영을 host 스키마 보존(pass-through) 으로 재설계. fable 갭 분석에서
+  발견, dist 실행으로 재현, 격리 `codex exec` 에서 `hook: Stop Blocked` → 자기 교정 턴 관측.
+- PreToolUse deny 의 `continue:false` 는 Codex 가 "unsupported" 로 로그하던 것을 제거 (차단은
+  `permissionDecision` 이 표현).
+
+### Added — ADR-015 (최신 Claude Code 2.1.286 대비 갭, 0.5.3 반영분)
+- **`SessionEnd` 훅 (Claude 전용)**: 세션 종료 시 user 메시지 ≥10 이면 auto-compound 러너를 detached
+  spawn — Stop 이 안 오는 종료(Ctrl+C 등)·긴 컴팩션 세션의 후반 학습 유실 보강. registry 에
+  `hosts` 필드 도입; **Codex hooks.json 은 22개 바이트 동일 유지** (훅 신뢰 보존).
+- **중첩 실행 가드**: forgen 이 띄우는 추출용 `claude -p` 에 `FORGEN_NESTED_RUN=1` +
+  `--no-session-persistence`. 추출 run 안에서 22개 훅이 재귀 발화해 hook-timing/sessions 를 오염하고
+  다음 SessionStart 의 auto-compound 후보가 되던 문제 차단. (`--bare` 는 OAuth 를 끊어 채택 불가.)
+- **플러그인 스킬 frontmatter 보존**: `skills/<name>/SKILL.md` 가 `disable-model-invocation`(ship),
+  `allowed-tools`, `argument-hint`, `model` 을 잃던 빌드 결함 수정.
+- 백로그(설계/재승인 필요)는 docs/adr/ADR-015 표 참조 — Codex async/SessionEnd/PostCompact 등록,
+  `notify`, `--output-schema`, `.codex/rules`, `verify` 스킬 규약, `InstructionsLoaded`, plugin eval 등.
+
+### Verified
+- vitest 전체 pass (신규: codex-rules-context, install-codex ADR-014 9, hook-timing rt, projection
+  재작성, hooks-generator-hosts, session-end).
+- fresh-context critic (fable) 1라운드 → MAJOR 3 + MINOR 6 반영 (상세: ADR-014 Verification).
+  `tests/extraction-session.test.ts` 2건은 타이밍 flaky(단독 재실행 pass, 본 변경과 무관).
+- self-gate static ✓, self-gate-runtime 9/9 ✓.
+- **격리 라이브 (CODEX_HOME/FORGEN_HOME 임시, Codex 0.153.4)**:
+  - 훅 미승인 `codex exec` → forgen 훅 0건 발화 (공식 문서의 "skipped until trusted" 실증).
+  - `--dangerously-bypass-hook-trust` → rollout 에 `<forgen-rules host="codex">` 4KB 주입 확인
+    (v1-rules `## Must Not` 포함), Codex 가 ch-* 에이전트 14종 전부 열거, 생성 TOML 14/14 tomllib 파싱 OK.
+
+### Known gaps (정직 표기)
+- Codex 전용 이벤트(SessionEnd/PostCompact/Interrupt) 미사용, `PostToolUseFailure` 는 Codex 에 없어
+  dead 엔트리로 유지 — 둘 다 hooks.json 변경이 필요해 신뢰 재승인 비용 때문에 보류.
+- Codex 가 `.claude/rules` 처럼 매 턴 재로드하지는 않음 — 세션 시작 1회 + 컴팩션 시 SessionStart 재발화 1회.
+- 서브에이전트 `model` 은 Codex 기본 subagent 모델 사용 (Claude 의 opus/sonnet 지정은 effort 로만 매핑).
+
+
+## [0.5.2] — 2026-08-18 — 학습 파이프라인 무결성: 실운영 데이터 진단으로 3대 결함 수정
+
+설치 후 실제 축적 데이터를 감사한 결과, 학습 파이프라인이 "우리 생각대로" 돌지
+않는 지점 3개를 발견·근본원인 규명·수정. npm publish 는 규칙대로 보류.
+
+### Fixed — 결함1: advisory 룰 폭주 (retire→재생성 churn)
+- `compound sweep` 가 behavior_inference advisory 룰을 매 실행마다 새 UUID 로
+  재생성해 6,701 파일(distinct render_key 172, 97% 중복)까지 폭증(1,046/일). 원인:
+  `render_key` 가 영구 upsert 정체성이 아닌 "현재 active" 임시 dedup 키로만 쓰이고,
+  채굴된 Evidence 가 consumed 표시되지 않아 retire 로 풀린 render_key 를 stale
+  evidence 가 즉시 재승격(시계만 리셋).
+- 수정: `findRuleByRenderKey()`(모든 status, scope 필터) 로 기존 룰 제자리 재활성
+  (`created_at`/`rule_id` 보존, TTL=첫 채굴 이후 총수명 캡), `Evidence.candidate_rule_refs`
+  재사용한 consumed 마킹(동일 evidence replay 억제, 진짜 cross-session 반복은 Laplace
+  강화 유지), 하드닝된 `withFileLockSync` 로 retire→lookup→create 크로스-프로세스 락,
+  `forgen compound sweep --prune-removed [--apply] [--retention-days N]`(dry-run 기본).
+
+### Fixed — 결함2: solution 추출 무음 실패 (생애 최초 산출 0건) — 라이브 확증 후 재설계
+- opt-in(`autoCompoundHaiku`) 켜짐에도 `me/solutions/` 신규 산출이 forgen 생애 통틀어 0건.
+- **라이브 확증으로 초기 진단을 정정**: 처음엔 "sparse env 권한 hedge"로 보고 `--permission-mode
+  dontAsk` 를 넣었으나, 실제 A/B 결과 dontAsk 는 산출을 전혀 바꾸지 못했다(有/無 모두 0).
+  진짜 원인은 (1) 프롬프트가 "형식: forgen compound ..."(format:)이라 headless haiku 가
+  명령을 텍스트로 프린트만 하고 Bash 도구를 호출 안 함, (2) 애초에 headless haiku 의 Bash
+  도구 호출이 근본적으로 불안정(동일 조건 1↔0), (3) cron sparse PATH 에 `forgen` 부재,
+  (4) 러너가 `stdio:'ignore'` 라 이 모든 실패가 무음.
+- **재설계(결정론적)**: 모델에 Bash 도구를 아예 주지 않는다. 모델은 재사용 솔루션을
+  텍스트로만 출력하고, 러너가 `--solution "제목" "설명"` 을 파싱해 `forgen` 을 직접 실행한다
+  (behavior 경로와 동일 패턴). 부수효과로 **P1-S1 injection 표면 제거** — 모델 출력은
+  파싱·필터(`containsPromptInjection`/`filterSolutionContent`) 후 `execFileSync` 의 *인자*로만
+  쓰이고 셸을 거치지 않는다. `forgen` 은 러너 node 의 형제 바이너리를 절대경로로 호출해
+  PATH 의존을 없애고, `spawn.ts` 는 러너를 `process.execPath` 로 띄워 실 cron(nvm node)에서
+  forgen 형제경로가 성립하게 한다. 러너 stdout/stderr 는 세션별 로그로 캡처(무음 실패 제거).
+- **라이브 검증**: cron-faithful sparse env(격리 FORGEN_HOME, 절대 nvm node)에서 실제 러너
+  실행 → solution **0→1** 확인.
+- **보안 defense-in-depth**: (1) 러너에서 대시-선두 title/content 스킵(arg confusion 1차 차단),
+  (2) `handleCompound` 인자 파서 리팩터 — manual-add(`--solution`/`--rule`/…)를 서브커맨드
+  dispatch 보다 먼저 처리해, 위치인자(title/content)의 `--remove`/`clean-stale` 등이
+  `args.includes(...)` 스캔에 걸려 삭제·정리 분기를 탈취하던 경로를 CLI 레벨에서 원천 차단.
+
+### Fixed — 결함3: 전역 CLI 버전 드리프트
+- 대화형 `forgen`/`fgx` 가 0.4.12(설치 후 미갱신)로 러닝 파이프라인(dist 0.5.x)과 불일치.
+  전역 CLI 를 npm latest 로 최신화.
+
+## [0.5.1] — 2026-08-18 — docs 정직화 i18n 동기화 + consent-sync CI 가드
+
+문서/CI 전용 패치. 사용자 노출 코드·런타임 동작 변경 없음. npm publish 는 규칙대로
+보류(품질 우선 — sellable/paper grade 도달 시).
+
+### Docs
+- **ko/ja/zh README 학습-루프 정직화 동기화**: EN(0.5.0)이 "session ends → auto-compound
+  extracts" 무조건-추출 프레이밍을 opt-in consent 모델(ADR-012)로 고쳤으나 세 번역본이
+  미반영이던 갭 해소(ko 는 v0.4.4 기준까지 뒤처짐). always-on(egress 0) vs
+  opt-in(`forgen compound consent on`, 기본 off, redaction, `forgen doctor`) 이분,
+  advisory-only 채굴(ADR-013), `compound sweep` backstop(ADR-011), ASCII 다이어그램·각주까지
+  EN 과 일치화. fresh-context critic 으로 21개 검증점(7 claim × 3 언어) 전수 확인.
+
+### CI
+- **4 로케일 README consent 동기화 invariant** (`tests/readme-i18n-consent-sync.test.ts`):
+  4 로케일 모두 consent load-bearing 토큰 포함(POSITIVE: `forgen compound consent on` /
+  `opt-in` / `egress 0` / `advisory-only` / `compound sweep` / `<private>`) + 무조건-추출
+  프레이밍(`auto-compound`) 미포함(NEGATIVE) 강제. EN 정직화가 번역에 다시 누락되거나 옛
+  프레이밍이 부활하면 PR 에서 RED. vitest.config include('tests/**') → ci.yml 자동 실행.
+
 ## [0.5.0] — 2026-08-05 — cross-session δ 실증 · 학습 아키텍처 완성 (ADR-010~013)
 
 forgen 의 첫 npm 릴리스(이전 발행은 0.4.x). 헤드라인: **forgen 효과(δ)를 프론티어

package/README.ja.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 0** で動作し、私たちが測定した cross-session δ はまさにこの経路に乗っています。
+
+あなたが明示的に指摘しない柔らかい修正（「うーん…これだけ最小限に書いたら後で全部やり直しになるんじゃない?」）はリアルタイムでは捉えにくいものです。transcript 抽出（下記）に opt-in すると、forgen は会話からそうした修正も**遡って（retroactive に）マイニング**します — ただしこうして自動マイニングされたルールは **advisory-only**（コンテキストとして提示されるだけで、決してブロック・強制しない）であり、あなたが反応しなければ時間とともに age-out します。
 
 ### セッション間（自動）
 
-セッション終了時に auto-compound が抽出します:
-- ソリューション（コンテキスト付きの再利用可能なパターン）
-- 行動観察（あなたの作業の仕方）
-- セッション学習サマリー
+**Always on（決定論的、egress 0）:** 明示的な修正は恒久ルールに昇格し、ほぼ重複する修正はクラスタリングされて強化され、蓄積されたエビデンスからファセットが微調整されます。時間ベースの `compound sweep` バックストップ（オプションで cron）が、長いセッションや中断されたセッションでもその学習が失われないようにします。
+
+**Opt-in（`forgen compound consent on`）:** バックグラウンドの Haiku パスがセッション transcript の*redaction 済みサマリー*を読み、再利用可能なソリューション、行動観察、そして上記の柔らかい修正を抽出します。これは**デフォルト off** です — あなたがオンにしない限り、forgen はあなたの会話をどこにも送信せず、送信前に secret / `<private>` 範囲は除去されます。`forgen doctor` が常に現在の状態を表示します。
 
-蓄積されたエビデンスに基づいてファセットが微調整されます。修正が継続的に現在のパックと異なる方向を指している場合、3セッション後にミスマッチ検出がトリガーされ、パック変更を提案します。
+修正が継続的に現在のパックと異なる方向を指している場合、3セッション後にミスマッチ検出がトリガーされ、パック変更を提案します。
 
 ### 次のセッション
 
@@ -190,6 +191,11 @@ forgen install both          # 3択インタラクティブ: claude / codex / bo
 # または非対話:
 forgen install claude
 forgen install codex
+# Codex のみ: codex 内で `/hooks` から forgen フックを一度承認 — Codex は未承認フックをスキップ (forgen doctor の [Codex Hooks] で確認)
+#   v0.5.6 へのアップグレード: `forgen install codex` を再実行するとフック 2 件 (session_start, session_end) が変わる — `/hooks` でもう一度承認。
+#   config.toml に `notify` フォールバックも登録 (既に `notify` を定義していれば変更しない; 無効化: --no-notify)。
+# Claude のみ: `verify` スキルを ~/.claude/skills/verify にインストール — Claude Code がコードのコミット直前に実行
+#   (自作の `verify` スキルは上書きしない; 無効化: --no-verify-skill)。
 
 # 3. 初回実行 — 4問オンボーディング (英語/韓国語選択)
 forgen                        # デフォルト: Claude
@@ -300,8 +306,8 @@ env を使ってください。ホスト環境 (macOS/Linux ワークステー
            |                                                |
            v                                                |
   +------------------+                                      |
-  | セッション終了    |   auto-compound 抽出:                 |
-  |                  |   ソリューション + 観察 + サマリー       |
+  | セッション終了    |   corrections -> rules (常時, egress 0)  |
+  |                  |   transcript 抽出: opt-in (Haiku)        |
   +--------+---------+                                      |
            |                                                |
            v                                                |
@@ -331,6 +337,8 @@ experiment (0.30) → candidate (0.55) → verified (0.75) → mature (0.90)
 | **行動パターン** | 3回以上の観察で自動検出 | `forge-behavioral.md` に適用 |
 | **エビデンス** | 修正 + 観察 | ファセット調整 + ルール作成を促進 |
 
+*ソリューションと行動パターンは **opt-in** の transcript 抽出パス（`forgen compound consent on`、デフォルト off）から得られます。corrections → rules とファセット調整は always-on で、あなたのマシンから決して出ません。*
+
 ### ソリューション自動注入
 
 入力したプロンプトはすべて、蓄積されたソリューションと照合されます。関連するものはClaudeのコンテキストに自動注入されます — 手動検索は不要です。

package/README.ko.md

@@ -122,16 +122,17 @@ forgen                    # `claude` 대신 사용
 
 당신이 말합니다: "내가 요청하지 않은 파일은 리팩토링하지 마."
 
-Claude가 `correction-record` MCP 도구를 호출합니다. 교정은 축 분류(`judgment_philosophy`), 종류(`avoid-this`), 신뢰도 점수가 포함된 구조화된 evidence로 저장됩니다. 현재 세션에 즉시 효과를 주는 임시 규칙이 생성됩니다.
+Claude가 `correction-record` MCP 도구를 호출합니다. 교정은 축 분류(`judgment_philosophy`), 종류(`avoid-this`), 신뢰도 점수가 포함된 구조화된 evidence로 저장됩니다. 현재 세션에 즉시 효과를 주는 임시 규칙이 생성됩니다. 세션이 끝나면 이 규칙은 **영구 규칙**으로 승급됩니다 — 이 결정론적 corrections → rules 경로는 **네트워크 egress 0** 으로 동작하며, 우리가 측정한 cross-session δ가 바로 이 경로에 실립니다.
+
+당신이 명시적으로 짚지 않은 완곡한 교정("음… 이렇게 최소로만 짜면 나중에 다 다시 해야 하는 거 아니야?")은 실시간으로 잡기 어렵습니다. transcript 추출(아래)에 opt-in 하면 forgen이 대화에서 그런 교정도 **retroactive하게 채굴**합니다 — 단, 이렇게 자동 채굴된 규칙은 **advisory-only**(컨텍스트로 표시될 뿐 절대 차단·강제하지 않음)이며, 당신이 반응하지 않으면 시간이 지나 age-out 됩니다.
 
 ### 세션 사이 (자동)
 
-세션이 끝나면 auto-compound가 추출합니다:
-- 솔루션 (맥락이 포함된 재사용 가능한 패턴)
-- 행동 관찰 (당신의 작업 방식)
-- 세션 학습 요약
+**Always on (결정론적, egress 0):** 명시적 교정은 영구 규칙으로 승급되고, 거의 중복인 교정은 클러스터링되어 강화되며, 축적된 evidence로 facet이 미세 조정됩니다. 시간 기반 `compound sweep` backstop(선택적으로 cron)이 길거나 중단된 세션에서도 그 학습이 유실되지 않게 보장합니다.
+
+**Opt-in (`forgen compound consent on`):** 백그라운드 Haiku 패스가 세션 transcript의 *redaction된 요약*을 읽어 재사용 가능한 솔루션, 행동 관찰, 그리고 위의 완곡한 교정을 추출합니다. 이것은 **기본 off** 입니다 — 당신이 켜지 않는 한 forgen은 당신의 대화를 어디로도 보내지 않으며, 전송 전에 secret / `<private>` 범위는 제거됩니다. `forgen doctor` 가 항상 현재 상태를 보여줍니다.
 
-축적된 evidence를 기반으로 facet이 미세 조정됩니다. 교정이 지속적으로 현재 팩과 다른 방향을 가리키면, 3세션 후 mismatch 감지가 트리거되어 팩 변경을 추천합니다.
+교정이 지속적으로 현재 팩과 다른 방향을 가리키면, 3세션 후 mismatch 감지가 트리거되어 팩 변경을 추천합니다.
 
 ### 다음 세션
 
@@ -150,6 +151,11 @@ forgen install both          # 3지선다 인터랙티브: claude / codex / both
 # 또는 비대화형:
 forgen install claude
 forgen install codex
+# Codex 만: codex 안에서 `/hooks` 로 forgen 훅을 한 번 승인 — Codex 는 미승인 훅을 skip (forgen doctor 의 [Codex Hooks] 로 확인)
+#   v0.5.6 업그레이드: `forgen install codex` 를 다시 돌리면 훅 2개(session_start, session_end)가 바뀜 — `/hooks` 에서 한 번 더 승인.
+#   config.toml 에 `notify` 폴백도 등록됨 (이미 `notify` 를 쓰고 있으면 건드리지 않음; 끄기: --no-notify).
+# Claude 만: `verify` 스킬을 ~/.claude/skills/verify 에 설치 — Claude Code 가 코드 커밋 직전에 실행
+#   (직접 만든 `verify` 스킬은 덮어쓰지 않음; 끄기: --no-verify-skill).
 
 # 3. 첫 실행 — 4문항 온보딩 (영어/한국어 선택)
 forgen                        # 기본: Claude
@@ -260,8 +266,8 @@ Linux 컨테이너에서 `~/.claude.json` 만 마운트하면 refresh 토큰이
            |                                                |
            v                                                |
   +------------------+                                      |
-  |  세션 종료        |   auto-compound 추출:                 |
-  |                  |   솔루션 + 관찰 + 요약                  |
+  |  세션 종료        |   corrections -> rules (항상, egress 0)  |
+  |                  |   transcript 추출: opt-in (Haiku)        |
   +--------+---------+                                      |
            |                                                |
            v                                                |
@@ -305,6 +311,8 @@ experiment (0.30) → candidate (0.55) → verified (0.75) → mature (0.90)
 | **행동 패턴** | 3회 이상 관찰 시 자동 감지 | `forge-behavioral.md`에 적용 |
 | **Evidence** | 교정 + 관찰 | facet 조정 및 규칙 생성의 근거 |
 
+*솔루션과 행동 패턴은 **opt-in** transcript 추출 패스(`forgen compound consent on`, 기본 off)에서 나옵니다. corrections → rules 와 facet 조정은 always-on 이며 절대 당신의 머신을 떠나지 않습니다.*
+
 ### Solution 자동 주입
 
 입력하는 모든 프롬프트가 축적된 솔루션과 매칭됩니다. 관련 솔루션은 Claude의 컨텍스트에 자동 주입됩니다 — 직접 찾아볼 필요가 없습니다.
@@ -666,7 +674,7 @@ forgen는 설치 시 다른 Claude Code 플러그인(oh-my-claudecode, superpowe
 
 | 문서 | 설명 |
 |------|------|
-| [훅 레퍼런스](docs/reference/hooks-reference.md) | 3개 계층의 19개 훅 — 이벤트, 타임아웃, 동작 |
+| [훅 레퍼런스](docs/reference/hooks-reference.md) | 3개 계층의 23개 훅 — 이벤트, 타임아웃, 동작 |
 | [공존 가이드](docs/guides/with-omc.md) | oh-my-claudecode와 forgen 함께 사용하기 |
 | [CHANGELOG](CHANGELOG.md) | 버전 히스토리 및 릴리즈 노트 |
 

package/README.md

@@ -244,6 +244,11 @@ 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])
+#   Upgrading to v0.5.6: re-running `forgen install codex` changes 2 hooks (session_start, session_end) — approve them in `/hooks` once more.
+#   It also registers a `notify` fallback in config.toml (left alone if you already define `notify`; opt out: --no-notify).
+# Claude only: installs a `verify` skill to ~/.claude/skills/verify — Claude Code runs it right before code commits
+#   (your own `verify` skill is never overwritten; opt out: --no-verify-skill).
 
 # 3. First run — 4-question onboarding (English or Korean)
 forgen                       # default: Claude
@@ -923,7 +928,7 @@ See [Coexistence Guide](docs/guides/with-omc.md) for the full plugin-detection m
 
 | Document | Description |
 |----------|-------------|
-| [Hooks Reference](docs/reference/hooks-reference.md) | 19 hooks across 3 tiers — events, timeouts, behavior |
+| [Hooks Reference](docs/reference/hooks-reference.md) | 23 hooks across 3 tiers — events, timeouts, behavior |
 | [Coexistence Guide](docs/guides/with-omc.md) | Using forgen alongside oh-my-claudecode |
 | [forgen-eval testbed](packages/forgen-eval/) | Alpha self-measurement package — multi-host parity, 7-axis metrics, drift detection (private workspace, v0.4.3+) |
 | [Multi-host core design](docs/superpowers/specs/2026-04-27-forgen-multi-host-core-design.md) | Codex/Claude symmetric host adapter spec |

package/README.zh.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）确保漫长或被中断的会话不会丢失这些学习。
+
+**Opt-in（`forgen compound consent on`）:** 后台的 Haiku 通道读取会话 transcript 的*脱敏（redacted）摘要*，提取可复用的解决方案、行为观察，以及上述柔性纠正。它**默认关闭** —— 除非你开启，否则 forgen 不会把你的对话发送到任何地方，且在发送前会剥离 secret / `<private>` 区间。`forgen doctor` 始终显示当前状态。
 
-基于累积的证据对 facet 进行微调。如果你的纠正持续指向与当前 pack 不同的方向，3个会话后触发不匹配检测，推荐更换 pack。
+如果你的纠正持续指向与当前 pack 不同的方向，3个会话后触发不匹配检测，推荐更换 pack。
 
 ### 下一个会话
 
@@ -190,6 +191,11 @@ forgen install both          # 三选交互: claude / codex / both
 # 或非交互:
 forgen install claude
 forgen install codex
+# 仅 Codex: 在 codex 内用 `/hooks` 信任一次 forgen 钩子 — Codex 会跳过未信任的钩子 (用 forgen doctor 的 [Codex Hooks] 查看)
+#   升级到 v0.5.6: 重新运行 `forgen install codex` 会改动 2 个钩子 (session_start, session_end) — 在 `/hooks` 中再信任一次。
+#   同时在 config.toml 注册 `notify` 兜底 (如果你已定义 `notify` 则不改动; 关闭: --no-notify)。
+# 仅 Claude: 将 `verify` 技能安装到 ~/.claude/skills/verify — Claude Code 在提交代码前运行它
+#   (不会覆盖你自己的 `verify` 技能; 关闭: --no-verify-skill)。
 
 # 3. 首次运行 — 4题引导问卷 (英语/韩语选择)
 forgen                        # 默认: Claude
@@ -269,8 +275,8 @@ forgen config default-host codex   # 设置持久默认主机
            |                                                |
            v                                                |
   +------------------+                                      |
-  |   会话结束        |   auto-compound 提取:                 |
-  |                  |   解决方案 + 观察 + 摘要                |
+  |   会话结束        |   corrections -> rules (始终, egress 0)  |
+  |                  |   transcript 提取: opt-in (Haiku)        |
   +--------+---------+                                      |
            |                                                |
            v                                                |
@@ -300,6 +306,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/skills/verify/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: verify
+description: Confirm a code change actually works using real execution evidence — run the project's own build, type-check, lint and tests, exercise the change itself, and report a confirmed / refuted / unverified verdict. Use right before committing a code change, or when asked to verify that something works.
+---
+
+<!-- forgen-managed -->
+
+# verify — prove the change works before it is committed
+
+"Saying it is done and proving it is done are different things."
+
+This is the forgen default verification recipe. Claude Code runs a skill named `verify` right before
+commits that touch code (docs-only and tests-only commits are skipped).
+
+## 0. Prefer the repository's own recipe
+
+If this repository documents how to verify changes — its own `.claude/skills/verify/SKILL.md`, or
+verification/test commands in `CLAUDE.md`, `AGENTS.md`, `CONTRIBUTING.md` or the README — follow that
+recipe first. It knows the project better than this generic one. Use the steps below for whatever it
+does not cover, and keep the evidence rules in step 3 either way.
+
+## 1. Scope the change
+
+- `git status --short` and `git diff --stat` (staged and unstaged) to see what is about to be committed.
+- State in one sentence what the change is supposed to do. That sentence is the claim you are verifying.
+
+## 2. Run the project's real checks
+
+Find the commands the project actually uses (`package.json` scripts, `Makefile`, `justfile`,
+`pyproject.toml`, `Cargo.toml`, `go.mod`, CI workflow files) and run the ones relevant to the change:
+
+1. build / compile
+2. type-check
+3. lint
+4. tests — the tests covering the changed code first, then the full suite when it is reasonably fast
+
+Keep it proportional: a one-line fix needs its targeted test and a build, not a 20-minute end-to-end run.
+Say which checks you skipped and why.
+
+## 3. Evidence rules
+
+- Only output from commands you ran **now** counts. "It should pass" and results quoted from earlier
+  in the session are not evidence.
+- A passing test that mocks or stubs the unit you changed does not show the change works. Look for,
+  or add, a check that executes the real code path.
+- Exercise the change itself where feasible: run the CLI command, call the endpoint, load the page,
+  import and call the function. A green test suite that never touches the new behaviour is not enough.
+- Do not attach confidence percentages you did not measure.
+
+## 4. Verdict
+
+Report exactly one of:
+
+- **confirmed** — the commands ran and their output supports the claim. Quote each command and the
+  1–3 lines of output that matter.
+- **refuted** — something failed or the behaviour is wrong. Do **not** commit. Show the failing output,
+  fix the problem, then run this skill again.
+- **unverified** — you could not run what was needed (missing dependency, no test covers it, needs
+  credentials). Say precisely what could not be checked and ask before committing; never round
+  unverified up to confirmed.
+
+## 5. Riskier changes
+
+For changes that touch persistence, authentication, money, concurrency, or public interfaces, hand the
+claim to a fresh verifier sub-agent (`forgen-verify` or `ch-verifier` when available) and ask it to try
+to break the claim rather than confirm it. Include its verdict in your report.