@su-record/vibe 3.2.32 → 3.2.34

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "vibe",
   "displayName": "Vibe",
-  "version": "3.2.32",
+  "version": "3.2.34",
   "description": "Verification harness for AI coding agents — \"done\" is decided by deterministic gates (test exit codes, run-ledger, regression memory), not the model self-report.",
   "author": {
     "name": "su-record",

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "vibe",
-  "version": "3.2.32",
+  "version": "3.2.34",
   "description": "Verification harness for AI coding agents — \"done\" is decided by deterministic gates (test exit codes, run-ledger, regression memory), not the model self-report.",
   "author": {
     "name": "su-record",

package/CLAUDE.md

@@ -53,6 +53,19 @@ Loop semantics SSOT: `vibe/rules/loop-contract.md` (ANCHOR→ACT→JUDGE→RECOR
 - ESM only (`"type": "module"`) — imports need `.js` extension
 - Build before test: `npm run build && npx vitest run`
 
+### Release Gates (전부 exit 0 이어야 배포)
+| 명령 | 막는 것 |
+|---|---|
+| `npm run build && npx vitest run` | 타입·동작 회귀 |
+| `npm run gen:skill-docs:check` | SKILL-CATALOG.md 드리프트 |
+| `npm run validate:counts` | README/package.json 개수 주장과 실제 불일치 |
+| `npm run validate:skill-invocation` | 스킬 invocation 선언 오류 |
+| `npm run sync:agent-models:check` | 에이전트 모델 섹션 드리프트 |
+| `npm run gen:plugin-hooks:check` | 훅 정의 세 벌의 드리프트 |
+| `npm run validate:plugin-tree` | 배포 트리와 소스 불일치 |
+
+마지막 둘은 CI(`test.yml`)에서도 돈다. **배포 순서는 PR 병합 먼저, 태그는 그다음** — 태그를 먼저 밀면 보호 브랜치에 막혀 병합이 실패해도 CI 가 이미 npm 에 게시한다(실측 v3.2.19).
+
 ### Config Locations
 | Path | Purpose |
 |---|---|
@@ -61,6 +74,11 @@ Loop semantics SSOT: `vibe/rules/loop-contract.md` (ANCHOR→ACT→JUDGE→RECOR
 | `.claude/settings.local.json` | Claude Code hooks (auto-generated, don't commit) |
 | `.codex/hooks.json` | Codex native hooks (auto-generated, don't commit) |
 | `~/.codex/config.toml` | Codex `notify` (turn-complete lifecycle hook, auto-installed) |
+| `.claude-plugin/plugin.json` | Claude Code 플러그인 매니페스트 (버전은 package.json 이 SSOT) |
+| `.claude-plugin/marketplace.json` | Claude Code 마켓플레이스 — `source: ./plugins/vibe` |
+| `.codex-plugin/plugin.json` | Codex/ChatGPT 플러그인 매니페스트 |
+| `.agents/plugins/marketplace.json` | Codex 마켓플레이스 — 같은 배포 트리를 가리킨다 |
+| `plugins/vibe/` | **커밋되는** 배포 트리 (`npm run build:plugin`) — 아래 배포 3경로 참조 |
 
 > ⚠️ 훅은 **프로젝트 로컬** 아티팩트다 — `vibe upgrade` 는 전역 자산만 갱신하므로 upgrade 만 쓰면 훅이 설치되지 않는다. `vibe upgrade` 가 현재 프로젝트의 누락 훅을 복구하고, `vibe status` 가 하네스별 설치 여부를 보고한다.
 
@@ -82,12 +100,39 @@ Legacy: 기존 `.claude/vibe/` 는 런타임에 자동 인식되며 `vibe init`/
 ### Dual-Harness Doctrine
 하네스 차이는 경로가 아니라 **인지 방식**(CC=추론 / Codex=직역)에 있다. 원칙: **암묵적 동작에 의존하지 않는다 — 추론은 `/vibe` 디스패처가 앞단에서, skill 본문은 전부 명시적으로.** ("명시성 공통분모 + 추론 앞단"). Hook은 의도별 매핑: 라이프사이클(turn 완료) → Codex `config.toml notify`, 나머지(SessionStart·UserPromptSubmit·Pre/PostToolUse·Pre/PostCompact) → Codex 네이티브 hook(`.codex/hooks.json` + `codex-hook-adapter.js`). **`PostCompact` 는 압축 직후 `loop-ledger.js anchor` 로 재고정한다** — ANCHOR 가 컨텍스트 소실에 대비하는 장치인데 정작 압축 시점에 자동 실행이 없었다. AGENTS.md soft-hook 은 폐기하지 않고 **훅 미설치 환경의 2차 방어선**으로 유지(직역이라 신뢰성↑). 전문: `vibe/rules/principles/dual-harness-doctrine.md`.
 
+### 배포 3경로 (npm · Claude Code 플러그인 · Codex 플러그인)
+같은 자산을 세 경로로 내보낸다. **경로가 늘어난 만큼 정의도 갈라진다** — 갈라지면 한쪽 하네스에서만 게이트가 죽고, 그건 조용히 일어난다. 그래서 SSOT 를 하나로 묶고 생성·검증한다.
+
+| 경로 | 설치 | 훅 정의 | 경로 변수 |
+|---|---|---|---|
+| npm | `npm i -g @su-record/vibe` | `hooks/hooks.json` (**SSOT**) | `{{VIBE_PATH}}` — postinstall 이 치환 |
+| Claude Code | `claude plugin marketplace add su-record/vibe` | `hooks/claude-plugin-hooks.json` (생성물) | `${CLAUDE_PLUGIN_ROOT}` |
+| Codex/ChatGPT | `vibe plugin install` → `codex plugin add vibe@vibe` | `hooks/plugin-hooks.json` (생성물) | `${PLUGIN_ROOT}` |
+
+- **생성**: `npm run gen:plugin-hooks` — `--check` 가 CI 게이트. 손으로 고치지 않는다
+- **이중 실행 가드**: 플러그인 훅은 `plugin-hook-entry.js` 를 거친다. 프로젝트에 **vibe 훅**이 있으면 플러그인 쪽이 물러난다 — 없으면 게이트가 2회, Stop auto-commit 도 2회 돈다. 판정은 "훅 키가 있다" 가 아니라 "vibe 훅이 있다" (사용자 자작 훅만 있는 프로젝트에서 침묵하면 설치한 의미가 없다). 실행은 spawn 이 아니라 in-process `import` — 위 훅 실행 모델 규약을 플러그인 경로에서도 지킨다
+- **배포 트리를 커밋하는 이유**: Claude Code 마켓플레이스는 저장소를 **클론**해서 읽는다. `dist/` 는 gitignore 대상이고 `agents/*.md` 의 frontmatter 는 postinstall 이 만든다 — 저장소를 그대로 가리키면 기능이 빠진 플러그인이 된다(실측: 에이전트 11개 중 7개만, description 없이 로드). `plugins/vibe/` 를 커밋하고 드리프트는 `npm run validate:plugin-tree` 가 막는다. `.gitignore` 의 `dist/` 가 이 트리까지 삼키므로 `!/plugins/vibe/dist/` 예외가 필수다
+
+### 폭이 큰 작업 — 네이티브 workflow 로 라우팅 (Claude Code)
+Claude Code 는 `Workflow` 도구(dynamic workflows)를 제공한다 — 한 실행에서 **누적 1000 에이전트**, **동시 min(16, cores-2)**. vibe 의 병렬 ACT 는 그보다 앞서 만든 자체 팬아웃이라 이 상한을 쓰지 않는다.
+
+**언제 넘길지**: 독립 작업 단위가 **수십 개 이상**이고(파일별 감사·전면 마이그레이션·다각도 탐색), 중간 결과가 세션 컨텍스트에 쌓이면 안 될 때. 조율 비용은 스크립트 변수로 빠지지만 **에이전트 사용량 자체는 그대로 든다** — 절약되는 것은 조율이지 작업이 아니다.
+
+**넘기지 않을 때**: 단위가 한 자릿수, 단계가 진짜로 서로 의존, 매 단계 사람 승인이 필요, 또는 아직 뭘 찾는지 모르는 탐색. 이 경우 워크플로는 순수 오버헤드다.
+
+- **자동 라우팅하지 않는다** — 워크플로는 사용자가 명시적으로 옵트인해야 하는 도구다. vibe 는 조건에 맞을 때 **제안만** 하고, 기본은 자체 병렬 ACT 를 유지한다
+- **Codex 에는 등가물이 없다** — 하네스별 능력 차이지 워크플로 분기가 아니다. vibe 코어의 루프 계약은 양쪽에서 동일하게 남는다 (Dual-Harness Doctrine)
+- 넘기더라도 **격리·검증 규정은 그대로** 적용된다 — 파일을 쓰는 병렬 단위는 worktree, 검증자는 독립 컨텍스트
+
 ### Gotchas
 - `better-sqlite3` WAL mode — synchronous API
 - `crypto.timingSafeEqual` requires same-length buffers — check length first
 - **Stack → asset SSOT**: `GLOBAL_SKILLS_*`, `STACK_TO_SKILLS`, `CAPABILITY_SKILLS` in `src/cli/postinstall/constants.ts`
 - **Hook dispatch order**: `prompt-dispatcher.js` → `llm-orchestrate.js` (매직 키워드 배너 훅 없음 — deprecated 별칭은 "Deprecated aliases" 표가 SSOT, 모델이 직접 해석)
 - **Hook 실행 모델**: per-event process spawn 유지 — **daemon/IPC 지양** (무상태·크래시 격리·인프라 제로가 ~20ms VM 기동 절감보다 우선). 훅 레이턴시 최적화는 dispatcher in-process 평탄화(자식 spawn → `import` 실행)로만 접근한다
+- **npm 12 `allowScripts`**: install 스크립트가 **기본 차단**된다. 설치는 ✅ 인데 vibe postinstall 도 `better-sqlite3` 네이티브 바인딩도 안 만들어진다 — 둘 다 자기복구(`runInstalledPostinstall`, `repairNativeDeps`)로 덮고 `vibe status` 가 보고한다. 근본 처방은 사용자 레벨 승인 하나뿐이다: `npm config set allow-scripts=@su-record/vibe,better-sqlite3 --location=user`. `npm install-scripts approve` 는 설치본 package.json 에 쓰므로 다음 설치에 지워진다(실측)
+- **에이전트 frontmatter 는 따옴표 필수**: description 에 `: ` 가 들어가면 YAML 평문 스칼라가 매핑으로 해석돼 **frontmatter 전체가 버려진다** — 에러 없이. 실측으로 설치본 11개 중 4개가 그 상태였다 (`convertAgentToClaude` 의 `yamlString`)
+- **Claude Code 는 `agents/*.md` 평면만 스캔**한다 — 하위 디렉토리 에이전트는 경고 없이 사라진다. 배포 트리는 평면화해서 굽는다
 
 ## Workflow
 
@@ -141,7 +186,7 @@ Public skills use the `vibe.*` namespace and are classified as **entry** / **sta
 
 ## Git
 
-**Include**: `.vibe/{plans,specs,features,todos,research,regressions,contracts,recipes,anti-patterns,loops,config.json,constitution.md}`, `CLAUDE.md`
+**Include**: `.vibe/{plans,specs,features,todos,research,regressions,contracts,recipes,anti-patterns,loops,config.json,constitution.md}`, `CLAUDE.md`, `plugins/vibe/` (배포 트리 — 생성물이지만 커밋한다, 위 "배포 3경로" 참조)
 **Vibe-global (not project-local)**: `~/.vibe/test-reports/` — `/vibe.test` artifacts live with the vibe install, not with the project
 **Exclude**: `~/.claude/{rules,commands,agents,skills}/`, `.claude/settings.local.json`, `.codex/hooks.json`, `.vibe/{memories,checkpoints,metrics,gates}/`
 

package/README.en.md

@@ -81,6 +81,52 @@ codex
 /vibe "add user authentication"
 ```
 
+> **On npm 12** — npm 12 blocks install scripts by default (`allowScripts`). Installation succeeds but the
+> `better-sqlite3` native binding is never built, so memory/RAG die on every hook. `vibe upgrade` repairs it
+> automatically; to prevent it at the source, approve once:
+>
+> ```bash
+> npm config set allow-scripts=@su-record/vibe,better-sqlite3 --location=user
+> ```
+>
+> Check with the `Native bindings` row in `vibe status`.
+
+---
+
+## Install as a plugin (experimental)
+
+An alternative to the npm install. The same distribution tree (`plugins/vibe`) ships to Claude Code, Codex, and ChatGPT.
+
+**Claude Code — straight from the repo** (no npm needed)
+
+```bash
+claude plugin marketplace add su-record/vibe
+claude plugin install vibe@vibe
+claude plugin details vibe          # Skills 52 · Agents 11 · Hooks 6
+```
+
+**If you already installed via npm**
+
+```bash
+vibe plugin install                 # assemble the tree + register both marketplaces
+vibe plugin status
+
+claude plugin marketplace add ~/.vibe/plugin
+claude plugin install vibe@vibe
+
+codex plugin marketplace add ~
+codex plugin add vibe@vibe
+```
+
+> **Double execution is prevented automatically.** If the npm install's project hooks are already present,
+> the plugin hooks stand down (`plugin-hook-entry.js`). Otherwise every gate would run twice — and so would
+> the auto-commit on Stop.
+>
+> **`plugins/vibe/` is a committed build artifact.** The Claude Code marketplace clones the repository, but
+> `dist/` is gitignored and the frontmatter in `agents/*.md` is generated by postinstall — pointing at the
+> repository itself yields a plugin with pieces missing (measured: only 7 of 11 agents loaded, and those
+> without descriptions). CI's `validate:plugin-tree` blocks drift.
+
 ---
 
 ## Harness Engineering
@@ -237,6 +283,14 @@ Start with `/vibe` and it routes the rest. Below is the list for when you want t
 | `/vibe.verify` | Verify implementation against SPEC Done criteria — result recorded in the run ledger |
 | `/vibe.continue` | Session restore — pick up after `save_memory` → `/new` at 85%+ context |
 
+**CLI**
+
+| Command | Purpose |
+|---------|---------|
+| `vibe status` | Harness state — hooks per harness, native bindings, LLM auth |
+| `vibe upgrade` | Upgrade + self-repair (global assets, project hooks, native bindings) |
+| `vibe plugin install` | Assemble the plugin tree and register the marketplaces |
+
 **Verification & quality**
 
 | Command | Purpose |

package/README.md

@@ -244,13 +244,15 @@ ChatGPT 데스크톱 앱에서는 앱을 **재시작**한 뒤 Plugins Directory
 > `source.path` 는 저장소 루트가 아니라 빌드 산출물(`./plugins/vibe`)을 가리킨다.
 > 루트를 가리키면 워킹트리가 통째로 캐시에 복사된다 (실측 655MB, 그중 620MB 가 `node_modules`).
 
-| 번들 | ChatGPT 앱 | Codex CLI |
-|---|---|---|
-| skills (52) | ✅ | ✅ |
-| hooks | **미확인** — 훅 문서가 Codex 아래에만 있다 | ✅ (trust 승인 후) |
+| 번들 | Claude Code | Codex CLI | ChatGPT 앱 |
+|---|---|---|---|
+| skills (52) | ✅ | ✅ | ✅ |
+| agents (11) | ✅ | — | — |
+| hooks (6 이벤트) | ✅ | ✅ (trust 승인 후) | **미확인** — 훅 문서가 Codex 아래에만 있다 |
 
-> ⚠️ 훅은 설치·활성화만으로 신뢰되지 않는다 — Codex 가 정의를 검토·승인할 때까지 건너뛴다.
-> `vibe init`·`vibe upgrade` 같은 CLI 와 프로젝트 로컬 훅 설치는 플러그인이 대체하지 못하므로 npm 설치는 계속 필요하다.
+> ⚠️ Codex 에서 훅은 설치·활성화만으로 신뢰되지 않는다 — Codex 가 정의를 검토·승인할 때까지 건너뛴다.
+> `vibe init` 이 만드는 프로젝트 로컬 설정과 `vibe upgrade` 의 자기복구는 플러그인이 대체하지 못한다 —
+> 그 둘이 필요하면 npm 설치를 함께 쓴다.
 
 ---
 
@@ -278,6 +280,14 @@ ChatGPT 데스크톱 앱에서는 앱을 **재시작**한 뒤 Plugins Directory
 | `/vibe.verify` | 구현이 SPEC Done 기준에 맞는지 검증 — 결과는 run-ledger 에 기록 |
 | `/vibe.continue` | 세션 복원 — 85%+ 컨텍스트에서 `save_memory` → `/new` 후 이어서 |
 
+**CLI**
+
+| 명령 | 용도 |
+|---|---|
+| `vibe status` | 하네스 상태 — 하네스별 훅, 네이티브 바인딩, LLM 인증 |
+| `vibe upgrade` | 업그레이드 + 자기복구 (전역 자산 · 프로젝트 훅 · 네이티브 바인딩) |
+| `vibe plugin install` | 플러그인 배포 트리 조립 + 마켓플레이스 등록 |
+
 **검증 · 품질**
 
 | 명령어 | 용도 |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@su-record/vibe",
-  "version": "3.2.32",
+  "version": "3.2.34",
   "description": "AI Coding Framework for Claude Code — 7+ agents, 52 skills, multi-LLM orchestration",
   "type": "module",
   "main": "dist/cli/index.js",
@@ -40,7 +40,7 @@
     "build:plugin": "npx tsx scripts/build-plugin.ts",
     "gen:plugin-hooks": "npx tsx scripts/gen-plugin-hooks.ts",
     "gen:plugin-hooks:check": "npx tsx scripts/gen-plugin-hooks.ts --check",
-    "validate:plugin-tree": "npx tsx scripts/build-plugin.ts && git diff --exit-code --stat plugins/"
+    "validate:plugin-tree": "npx tsx scripts/build-plugin.ts && git diff --exit-code --stat HEAD -- plugins/"
   },
   "keywords": [
     "ai",

package/skills/vibe.review/SKILL.md

@@ -219,6 +219,11 @@ After agent results:
 
 > P1/P2 findings 를 검증하기 위해 네이티브 서브에이전트를 병렬로 스폰한다 —
 > `security-reviewer` + `code-reviewer` 인스턴스(서로 다른 focus)가 각 finding 을 교차 검증(validate / upgrade / downgrade / remove)한다.
+>
+> **검증자에게 실행자의 컨텍스트를 넘기지 않는다.** 새 서브에이전트로 스폰하는 것 자체가
+> 이 규정이다 — finding 과 대상 파일만 주고, 리뷰 과정의 대화는 주지 않는다.
+> 같은 컨텍스트를 물려받은 검증자는 검증하지 않고 **자기 자신에게 동의한다**.
+> 그러면 교차 검증은 이름만 남고 단일 리뷰와 같아진다 — 더 비싸고, 통과 신호만 늘어난 채로.
 
 > Read `references/worked-examples.md` for the full Review Debate example output.
 

package/skills/vibe.run/SKILL.md

@@ -100,6 +100,12 @@ test -f DESIGN.md
 └─────────────────────────────────────────────────────────────────┘
 ```
 
+> **병렬 쓰기는 격리 없이 하지 않는다.** 병렬 항목이 **파일을 수정하면** 항목별 worktree 에서 실행한다 (`vibe.git-worktree` 패턴, `vibe.loop` 의 `isolation: worktree` 와 같은 축). 읽기 전용 병렬 탐색은 격리 불필요.
+>
+> WHY: 같은 워킹트리에서 두 에이전트가 쓰면 경합한다 — 파일 덮어쓰기, 공유 git 명령 충돌. 프롬프트로 막을 수 있는 종류가 아니라 **구조로만** 막힌다. 실측 사례: Bun 팀이 대규모 포팅을 여러 에이전트로 팬아웃했을 때 공유 워크스페이스에서 서로를 덮어써 운영상 실패했고, 해결책은 프롬프트가 아니라 그룹별 worktree 분리였다.
+>
+> 팬아웃 전에 답이 있어야 하는 3가지: **어디서 작업하는가 · 결과를 어떻게 병합하는가 · 둘이 충돌하면 어떻게 하는가.** 답이 없으면 병렬로 가지 않는다.
+
 > **하네스-안전 증분 (Dual-Harness Doctrine)**: 시나리오는 **가장 작은 검증 단위**다. 한 시나리오 구현 → 즉시 검증 → 다음. `automationLevel: autonomous`이라도 이 단위는 무너뜨리지 않는다 (병렬은 시나리오 간, 검증은 시나리오별). 전문: `vibe/rules/principles/dual-harness-doctrine.md`.
 
 ### Automated Verification (Closed Loop)
@@ -179,7 +185,7 @@ Default: a
 | 1-1 | Phase Isolation Protocol | 3+ phase SPEC 은 phase 단위 격리 + 체크포인트 필수 |
 | 1-2 | SPEC-First Gate | SPEC 에 없는 것을 구현하지 않는다 |
 | 2 | Extract Scenario List | Feature 파일의 시나리오가 작업 단위 |
-| 3 | Scenario-by-Scenario Implementation | 기본 순차. **구현→검증 쌍은 시나리오 단위로 쪼개지 않는다**. `autonomous` 에서 서로 의존하지 않는 시나리오는 병렬 가능하되 검증은 시나리오별로 각각 (SSOT: 위 "하네스-안전 증분") |
+| 3 | Scenario-by-Scenario Implementation | 기본 순차. **구현→검증 쌍은 시나리오 단위로 쪼개지 않는다**. `autonomous` 에서 서로 의존하지 않는 시나리오는 병렬 가능하되 검증은 시나리오별로 각각 (SSOT: 위 "하네스-안전 증분"), **병렬 시 격리 필수** (아래) |
 | 4 | Brand Assets | 신규 프로젝트만 (`references/brand-assets.md`) |
 | 5 | Race Code Review | `references/race-review.md` |
 | 6 | Quality Report | 자동 생성 |

package/vibe/rules/loop-contract.md

@@ -193,4 +193,6 @@ JUDGE는 이번 feature의 **신규 생성 파일** 기준으로 검증 코드
 | `verify` | 기본 동작과 동일 (no-op) — JUDGE는 항상 결정론 검증 |
 | `quick` | `--max-iter 1` + 최소 JUDGE |
 | `ralplan` | 같은 계약을 계획 단계에 적용 |
-| `ultrawork` / `ulw` | `automationLevel: autonomous` + 병렬 ACT — 루프 시맨틱이 아니라 자율성·병렬성 축 |
+| `ultrawork` / `ulw` | `automationLevel: autonomous` + 병렬 ACT — 루프 시맨틱이 아니라 자율성·병렬성 축. **병렬 항목이 파일을 수정하면 항목별 worktree 격리 필수** (`vibe.loop` 의 `isolation` 축과 같은 규칙) |
+
+> **폭이 수십 단위를 넘으면** Claude Code 네이티브 `Workflow`(누적 1000 에이전트 / 동시 min(16, cores-2))를 **제안**한다 — 자동 전환하지 않는다. 옵트인 도구이고, 조율 비용만 절약될 뿐 에이전트 사용량은 그대로 든다. Codex 에는 등가물이 없으므로 루프 계약 자체는 양쪽 동일하게 유지한다. 넘기더라도 위의 격리 규정과 검증자 컨텍스트 규정은 그대로 적용된다. 상세: `CLAUDE.md` "폭이 큰 작업 — 네이티브 workflow 로 라우팅".

package/vibe/rules/principles/dual-harness-doctrine.md

@@ -56,3 +56,19 @@ Codex는 네이티브 hook을 지원한다(`codex features list` → `hooks: sta
 **핵심 통찰: Codex의 직역 성향이 AGENTS.md "soft hook"을 신뢰성 있게 만든다.** CC는 soft 지시를 가끔 무시해 hard hook이 필요하지만, Codex는 적힌 대로 실행한다. 따라서 AGENTS.md 운영 규칙은 네이티브 hook이 생긴 뒤에도 **폐기하지 않고 2차 방어선으로 유지한다** — hook이 설치되지 않은 환경(전역 설치만 한 경우, 다른 클론)에서도 가드가 남는다.
 
 > ⚠️ **훅은 "설치돼 있다"고 가정하지 않는다.** 훅은 프로젝트 로컬 아티팩트라 `vibe upgrade` 만으로는 설치되지 않는다(전역 자산만 갱신). `vibe status` 가 하네스별 훅 설치 여부를 보고하고, `vibe upgrade` 는 현재 프로젝트의 누락 훅을 복구한다. 결정론적 가드의 생사는 **관측 가능해야** 한다 — 조용히 죽은 가드는 없는 가드보다 나쁘다.
+
+## 훅 정의가 세 벌이 됐다 (배포 경로별)
+
+배포 경로가 npm · Claude Code 플러그인 · Codex 플러그인 셋으로 늘면서 훅 정의도 셋이 됐다. 경로 변수가 다르기 때문이다 — 그리고 **정의가 갈라지면 한쪽 하네스에서만 게이트가 죽고, 그건 조용히 일어난다.** 이 문서가 반복해서 말하는 실패 모드다.
+
+| 파일 | 경로 | 변수 | 생성 |
+|---|---|---|---|
+| `hooks/hooks.json` | npm | `{{VIBE_PATH}}` — postinstall 이 치환 | **SSOT** (손으로 고치는 유일한 파일) |
+| `hooks/claude-plugin-hooks.json` | Claude Code 플러그인 | `${CLAUDE_PLUGIN_ROOT}` | `gen-plugin-hooks.ts` |
+| `hooks/plugin-hooks.json` | Codex 플러그인 | `${PLUGIN_ROOT}` | `gen-plugin-hooks.ts` |
+
+- 드리프트는 `npm run gen:plugin-hooks:check` 가 CI 에서 막는다. 손으로 맞추는 선택지는 두지 않는다
+- **이중 실행 가드**: npm 설치본과 플러그인이 겹치면 같은 6개 이벤트가 두 벌 등록돼 게이트가 2회, Stop 의 auto-commit 도 2회 돈다. 플러그인 훅은 `plugin-hook-entry.js` 를 거쳐, 프로젝트에 **vibe 훅**이 있으면 물러난다. 판정 기준이 "훅 키가 있다" 가 아니라 "vibe 훅이 있다" 인 이유는 사용자 자작 훅만 있는 프로젝트에서까지 침묵하면 설치한 의미가 없기 때문이다
+- 실행은 자식 spawn 이 아니라 in-process `import` 다 — 훅 실행 모델 규약을 플러그인 경로에서도 지킨다
+
+> 하네스가 늘어날 때 늘려야 하는 것은 **정의가 아니라 생성기**다. 정의를 늘리면 그 수만큼 갈라질 자리가 생긴다.