commitgate 0.3.1 → 0.7.0

package/README.md

@@ -6,6 +6,11 @@
 
 AI 에이전트가 코드를 빠르게 만들더라도, 리뷰 없이 바로 커밋되면 위험합니다. CommitGate는 변경을 티켓 단위로 묶고, Codex가 승인한 staged tree만 커밋되게 합니다. 승인 후 코드가 바뀌거나 증거가 부족하면 기본적으로 막습니다.
 
+> **⚠️ 시작하기 전에 두 가지를 알아 두세요.**
+>
+> 1. **리뷰는 staged diff를 외부로 전송합니다.** `req:review-codex`는 `git diff --cached` **전문**을 Codex(OpenAI)로 보냅니다. codex는 `--sandbox read-only`로 저장소 루트를 읽으므로 diff에 없는 파일도 읽힐 수 있습니다. 마스킹·필터·길이 상한은 **없습니다.** 리뷰 전에 staged 내용에 자격증명·토큰·개인정보가 없는지 확인하세요.
+> 2. **git hook을 설치하지 않습니다.** `req:commit` 대신 `git commit`을 직접 치면 게이트·승인 바인딩·증거 기록이 전부 우회됩니다. CommitGate의 강제력은 **협조하는 에이전트를 계약 궤도에 유지하는 것**에 있지, 사람의 우회를 막는 데 있지 않습니다.
+
 [![CI](https://github.com/sol5288/commitgate/actions/workflows/ci.yml/badge.svg)](https://github.com/sol5288/commitgate/actions/workflows/ci.yml)
 [![npm version](https://img.shields.io/npm/v/commitgate.svg)](https://www.npmjs.com/package/commitgate)
 [![license](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
@@ -21,44 +26,56 @@ AI 에이전트가 코드를 빠르게 만들더라도, 리뷰 없이 바로 커
 git init
 npm init -y
 
-# 그다음 설치:
-npx commitgate
-npm install
+# 1) CommitGate를 devDependency로 설치합니다 — 실행 코드가 여기 들어옵니다:
+npm install -D commitgate
+
+# 2) 프로젝트에 설정·계약·스키마와 req:* 스크립트를 깝니다:
+npx commitgate init
+
 codex --version
 codex login status
 ```
 
-그다음 AI 코딩 에이전트에게 아래 프롬프트를 붙여넣습니다.
+> **왜 두 단계인가요?** CommitGate는 실행 코드를 프로젝트에 **복사하지 않습니다**. 1단계가 런타임을 `node_modules/commitgate`에 넣고, 2단계는 프로젝트에 **거버넌스 자산**(설정·계약·스키마·persona)과 `req:* = commitgate <verb>` 스크립트만 깝니다.
+> 그래서 업데이트는 `npm update commitgate` 한 번이고, 런타임 제거는 `npm uninstall -D commitgate`입니다.
+> `init`은 `devDependencies.commitgate` 선언이 없으면 **중단**합니다 — `req:*`가 가리킬 런타임이 없기 때문입니다.
+
+설치는 파일을 놓기만 하고 커밋하지 않습니다. `req:new`는 **clean 워킹트리를 요구**하므로, 설치분을 먼저 커밋하세요. 설치 출력의 `다음:` 안내가 stage할 정확한 경로 목록을 알려 줍니다.
+
+```sh
+git add -- <설치 출력이 알려 준 경로들>
+git status                    # 의도한 것만 staged 인지 눈으로 확인
+git commit -m "chore: install commitgate"
+```
+
+> **전체를 담는 stage(`-A` / `.`)를 쓰지 마세요.** 기존 프로젝트의 무관한 변경과 `.env` 같은 미추적 파일이 함께 커밋되고, 이어지는 `req:review-codex`가 그 staged diff 전문을 외부로 전송합니다.
+> 설치 전부터 있던 무관한 변경은 설치 커밋 뒤에 **경로를 명시해** 치우세요: `git stash push -u -- <경로들>`.
+> `-u` 없이는 untracked가 남아 `req:new`가 막히고, 경로 없이 `git stash -u`만 쓰면 `node_modules/`처럼 무시되지 않은 디렉터리까지 딸려 갑니다. 설치 출력이 그 경로 목록도 알려 줍니다.
+
+**긴 프롬프트를 붙여넣을 필요가 없습니다.** 설치가 에이전트 진입점을 함께 깝니다.
+
+| 파일 | 읽는 도구 |
+|---|---|
+| `AGENTS.md` | Codex CLI, Cursor — **계약 정본** |
+| `.claude/skills/commitgate/SKILL.md` | Claude Code (요청에 맞으면 자동 발동) |
+| `.claude/commands/req.md` | Claude Code (`/req` 명시 호출) |
+| `.cursor/rules/commitgate.mdc` | Cursor (`alwaysApply`) |
+| `CLAUDE.md` | Claude Code (항상 로드) — 부재 시에만 생성 |
+
+에이전트에게 요구사항만 주면 됩니다.
 
 ```text
-이 요청은 일반 구현으로 처리하지 말고, 이 프로젝트에 설치된 CommitGate를 사용해라.
-
-새 REQ 티켓을 만들고 다음 흐름을 끝까지 진행해라:
-req:new → 설계문서 작성 → Codex design 리뷰 → 구현·테스트 → req:doctor → Codex phase 리뷰 → req:commit
-
-자동으로 진행할 것:
-- `req:review-codex`가 NEEDS_FIX/exit 3을 반환하면 findings를 수정하고 재리뷰한다.
-- BLOCKED/exit 2를 반환하면 같은 리뷰를 재시도하지 말고 사람에게 보고하거나 리뷰 대상을 바꾼다. 스레드 고착이 의심되면 `--fresh-thread`로 한 번만 회복을 시도할 수 있다.
-- 리뷰 대상은 git add 한 파일만이다.
-- `state.json`과 `responses/`는 직접 `git add`하지 않는다.
-
-멈춰서 확인받을 때(각 항목은 그 문장 그대로 승인받아야 하며, 한 승인은 다음 단계로 이월되지 않는다):
-- req:commit --run 직전
-- [경로 A · 선택] [I1] feature branch push + PR 생성 직전 / [I2] required checks green 확인 후 PR merge 직전
-- [경로 B] [B1] protected branch에 direct push 직전 — "branch protection bypass를 사용한 direct push 승인"을 따로 받는다. 이 push는 required checks를 우회하고, CI는 사후에 돈다
-- [R1/R2/R3] tag 생성·push / npm publish / GitHub release — CI green 확인 후 각각 별도 승인
-- reset, clean, force push 같은 destructive 작업 전
-- 요구사항 범위를 바꿔야 할 때
-- Codex 리뷰가 BLOCKED를 반환하거나 제한된 재시도 후에도 판단이 불명확할 때
-
-요구사항:
-- 무엇을:
-- 왜:
-- 제약:
-- 완료 기준:
+/req 프로필 수정 API를 추가해줘
+
+- 무엇을: PATCH /profile 로 닉네임·소개글 수정
+- 왜: 지금은 가입 후 프로필을 바꿀 방법이 없다
+- 제약: 기존 인증 미들웨어 재사용, 스키마 변경 없음
+- 완료 기준: 단위 테스트 통과, 권한 없는 사용자는 403
 ```
 
-첫 응답은 보통 이렇게 나와야 합니다.
+Claude Code가 아니면 슬래시 커맨드 없이 요구사항만 주어도 됩니다(`.cursor/rules`·`AGENTS.md`가 규칙을 로드합니다). 네 칸이 비어 있으면 에이전트가 먼저 물어봅니다.
+
+첫 응답은 보통 이렇게 나옵니다.
 
 ```text
 REQ-2026-002 발행
@@ -69,7 +86,38 @@ phase:
 통제점: req:commit --run 직전 / [B1] main direct push 직전 (또는 [I1] PR 생성 → [I2] merge)
 ```
 
-이후에는 에이전트가 설계, 구현, 테스트, Codex 리뷰를 진행합니다. 사용자는 통제점에서만 확인하면 됩니다.
+### 에이전트는 `req:next`가 시키는 대로 진행합니다
+
+다음 행동을 에이전트가 추측하지 않습니다. 도구가 `state.json`과 git 상태에서 계산합니다.
+
+```sh
+npm run req:next -- 2026-002
+```
+
+```text
+[req:next] RUN  REQ-2026-002
+  phase `phase-1`의 staged 변경을 리뷰받는다.
+
+  $ npm run req:review-codex -- 2026-002 --kind phase --phase phase-1 --run
+```
+
+| kind | 뜻 | exit |
+|---|---|---|
+| `RUN` | 출력된 명령을 그대로 실행하고 다시 `req:next` | 0 |
+| `AGENT` | 도구가 대신 못 하는 작업(구현·문서 작성·`git add`) | 0 |
+| `AWAIT_HUMAN` | **통제점** — 출력된 승인 문장을 그대로 받기 전엔 진행 금지 | 10 |
+| `DONE` | 이 티켓에서 도구가 할 일 없음. 통합은 별도 통제점 | 11 |
+| `BLOCKED` | 사람에게 보고. 같은 리뷰 재시도 금지 | 2 |
+
+`--json`으로 기계 판독할 수 있습니다. **읽기 전용**이라 어떤 상태도 바꾸지 않습니다.
+
+이 루프를 끊지 말고 반복하면 설계 → Codex 리뷰 → 구현 → 재리뷰 → 커밋이 진행됩니다. 사용자는 `AWAIT_HUMAN`에서만 확인하면 됩니다.
+
+### 리뷰어 페르소나는 도구가 주입합니다
+
+`req:review-codex`는 `workflow/review-persona.md`를 프롬프트 **첫 블록**으로 넣습니다. 사람이 직접 실행하든, Cursor가 실행하든, Claude가 실행하든 동일합니다 — 에이전트가 잊을 수 있는 자리에 두지 않습니다. 파일이 없거나 비어 있으면 리뷰가 fail-closed로 멈춥니다.
+
+내용을 프로젝트에 맞게 고치거나, `req.config.json`의 `reviewPersonaPath`로 다른 파일을 지정할 수 있습니다. `null`로 두면 비활성화됩니다.
 
 main에 반영하는 경로는 **PR 경유(선택)**와 **direct push** 둘 다 유효합니다. PR은 의무가 아닙니다. 다만 protected branch로 직접 push하면 required checks를 **우회**하므로 "branch protection bypass를 사용한 direct push 승인"을 따로 받아야 합니다 — bypass 권한이 있다는 사실은 승인이 아닙니다. 그리고 이때 CI는 push **이후에** 도는 **사후 검증**이라, 그 사실을 보고에서 생략하지 않습니다. tag, npm publish, GitHub release는 반영과 묶이지 않는 별도 통제점이고 CI green 이후에 요청합니다. 자세한 계약은 [AGENTS.template.md](AGENTS.template.md)와 [docs/RELEASING.md](docs/RELEASING.md)를 참고하세요.
 
@@ -90,19 +138,52 @@ CommitGate가 막는 것은 단순한 명령 실수가 아니라 **리뷰받지
 
 한 줄로 말하면, **확실히 승인된 변경만 통과하고 애매하면 멈추는 방식**입니다.
 
+### 보장하지 않는 것
+
+방어선을 잘못 계산하지 않도록, 이 도구가 **하지 않는 일**을 분명히 해 둡니다.
+
+- **하드 강제가 아닙니다.** git hook을 설치하지 않으므로 `req:commit` 대신 `git commit`을 직접 치면 doctor·승인 바인딩·증거 기록이 전부 우회됩니다. 운영 반영의 실제 방어선은 여전히 CI와 배포 파이프라인입니다.
+- **staged 내용의 비밀을 지켜 주지 않습니다.** `req:review-codex`는 `git diff --cached` 전문을 Codex(OpenAI)로 전송하고, codex는 `--sandbox read-only`로 저장소 루트를 읽습니다. 마스킹·스크러빙·길이 상한이 없습니다. 결제·자격증명처럼 민감한 코드베이스라면 리뷰 전 staged diff를 육안으로 확인하는 절차를 계약(`AGENTS.md`)에 명문화하세요.
+- **커밋 이후를 보장하지 않습니다.** 승인은 커밋 시점의 staged tree에 대한 것이고, 머지·태그·publish는 각각 별도 통제점입니다.
+
 ---
 
 ## 설치가 하는 일
 
-`npx commitgate`는 대상 프로젝트에 아래 파일과 설정을 추가합니다. 기존 파일은 기본적으로 덮어쓰지 않습니다.
+`npx commitgate init`은 대상 프로젝트에 아래 파일과 설정을 추가합니다. 기존 파일은 기본적으로 덮어쓰지 않습니다.
 
 | 추가 항목 | 설명 |
 |---|---|
-| `scripts/req/` | `req:new`, `req:review-codex`, `req:doctor`, `req:commit` 스크립트 |
 | `workflow/*.schema.json` | Codex 응답과 설정 검증 스키마 |
+| `workflow/review-persona.md` | Codex 리뷰 프롬프트에 주입되는 리뷰어 페르소나 (없을 때만 생성) |
 | `req.config.json` | 프로젝트별 설정 |
-| `AGENTS.md` | 에이전트와 Reviewer가 읽는 규칙 템플릿 |
-| `package.json` 스크립트 | `req:*` 명령과 필요한 devDependencies |
+| `AGENTS.md` | 계약 정본 (없을 때만 생성) |
+| `CLAUDE.md` | Claude Code 지침 포인터 (없을 때만 생성) |
+| `.claude/skills/commitgate/SKILL.md` | Claude Code 스킬 (포인터) |
+| `.claude/commands/req.md` | `/req` 슬래시 커맨드 (포인터) |
+| `.cursor/rules/commitgate.mdc` | Cursor 규칙 (포인터) |
+| `package.json` 스크립트 | `req:new`·`req:next`·`req:review-codex`·`req:doctor`·`req:commit` = `commitgate <verb>` (없는 키만) |
+
+### 설치하지 **않는** 것
+
+| 항목 | 어디에 있나 |
+|---|---|
+| `scripts/req/**` 실행 코드 | `node_modules/commitgate` — 프로젝트에 복사하지 않습니다 |
+| `tsx` · `ajv` · `cross-spawn` | `commitgate` 패키지의 runtime dependency — 대상 `package.json`에 주입하지 않습니다 |
+
+프로젝트에 남는 것은 **거버넌스·감사 데이터**(설정·계약·스키마·persona·`workflow/REQ-*` 증거)뿐입니다. 실행 코드는 패키지에만 있으므로 `npm update commitgate` 한 번으로 갱신되고, 복사본 버전이 갈라지지 않습니다.
+
+`req:*` 스크립트는 설치된 패키지 bin을 호출합니다 — `npm run req:new -- <slug>` → `commitgate req:new <slug>` → `node_modules/.bin/commitgate`.
+
+진입점 파일들은 **얇은 포인터**입니다. 계약 본문은 `AGENTS.md` 하나에만 있습니다.
+
+`.claude/`·`.cursor/`를 다른 도구가 쓰고 있다면 건너뛸 수 있습니다.
+
+```sh
+npx commitgate --no-agent-entrypoints
+```
+
+기존 `AGENTS.md`가 있는데 CommitGate 계약 마커(`<!-- commitgate:contract -->`)가 없으면, 계약 템플릿을 `AGENTS.commitgate.md`로 함께 놓고 병합을 안내합니다. 기존 파일은 건드리지 않습니다.
 
 미리보기만 하려면:
 
@@ -110,21 +191,69 @@ CommitGate가 막는 것은 단순한 명령 실수가 아니라 **리뷰받지
 npx commitgate --dry-run
 ```
 
-보안 하한 경고를 설치 실패로 취급하려면:
+정합성 경고를 설치 실패로 취급하려면:
 
 ```sh
 npx commitgate --strict
 ```
 
-기존 `cross-spawn`이 검증 하한보다 낮으면 파일을 복사하기 전에 중단합니다.
+**파일을 하나도 쓰기 전에** 중단합니다. 대상은 다음과 같습니다.
+
+- 계약 포인터(`.claude/`·`.cursor/`·`AGENTS.md`·`CLAUDE.md`)가 `.gitignore`에 걸려 팀·CI에 공유되지 않을 때
+- `workflow/.gitignore` 정책 파일이 무시돼 fresh clone·CI에 scratch 규칙이 전달되지 않을 때
+- 설치 전 워킹트리에 staged 변경이 있거나 설치 산출물과 겹치는 수정이 있어, 설치분만 담은 커밋을 만들 수 없을 때
+- 기존 `cross-spawn`이 검증 하한보다 낮을 때(프로젝트가 그 패키지를 이미 쓰는 경우)
+
+> `--strict`는 **선행 `npm install -D commitgate`가 남긴 `package.json`·lockfile 변경도** preexisting-dirty로 봅니다. 권장 순서: `npm i -D commitgate` → **커밋** → `npx commitgate init --strict` → 설치분 커밋.
 
 > `workflow/machine.schema.json`과 `workflow/req.config.schema.json`은 `req.config.json`의 `ticketRoot` 설정과 무관하게 **항상 `workflow/` 아래**에 복사됩니다.
 
 ---
 
+## 예전 설치본에서 옮겨오기 (`migrate`)
+
+`scripts/req/`가 프로젝트에 복사돼 있고 `req:*`가 `tsx scripts/req/*.ts`를 가리킨다면 **예전(vendored) 설치본**입니다. `init`은 이 상태를 감지하면 조용히 섞이지 않도록 **중단하고** 이 명령을 안내합니다.
+
+```sh
+npm install -D commitgate      # 아직 devDependency가 아니라면 먼저
+npx commitgate migrate         # 계획만 출력 — 아무것도 쓰지 않습니다
+npx commitgate migrate --apply # package.json 의 req:* 만 전환
+```
+
+`migrate`가 하는 일은 **하나**입니다: `req:*` 중 **현재 값이 정확히 예전 주입값인 키만** `commitgate <verb>`로 바꿉니다.
+
+- **아무것도 삭제하지 않습니다.** `scripts/req/`·스키마·persona·설정·진입점·`workflow/REQ-*` 증거를 전부 그대로 둡니다. 남은 `scripts/req/`는 더 이상 실행되지 않으니, 정리하려면 `npx commitgate uninstall` 계획을 먼저 확인하세요.
+- **직접 고친 스크립트는 덮어쓰지 않습니다.** 값이 한 글자라도 다르면 사용자 값으로 보고 보존한 뒤 수동 조치를 안내합니다.
+- **커밋하지 않습니다.** `package.json` 한 파일만 쓰고, 검토는 사용자 몫입니다.
+
+`req:doctor`도 설치 모드(예전/현재/혼합)를 진단해 알려 줍니다.
+
+---
+
+## 지원 범위
+
+| 환경 | 상태 |
+|---|---|
+| **npm** | 완전 지원 — 매 릴리스 packed tarball smoke로 검증합니다 |
+| **pnpm · yarn** (`node_modules` linker) | 지원 — `node_modules/.bin/commitgate`로 해소되는 표준 경로를 씁니다 |
+| **Yarn PnP** | **이번 릴리스 미지원**(검증하지 않았습니다). `nodeLinker: node-modules`를 쓰세요 |
+| **workspace/monorepo** | **워크스페이스 root 설치**를 지원합니다(root에 `req.config.json`·`workflow/`). 하위 패키지에 독립 설치하는 배치는 미지원 |
+
+**재현성**: `req.config.json`의 리뷰 모델·추론강도 핀과 스키마·persona가 프로젝트에 남아 과거 리뷰 입력이 git 이력으로 재현됩니다. 런타임 버전은 **lockfile이 고정**하므로 `package-lock.json`(pnpm/yarn은 각 lockfile)을 **커밋하세요**.
+
+---
+
 ## 제거하려면
 
-먼저 알아둘 것: **`npx commitgate`는 전역 설치가 아닙니다.** npx는 패키지를 npm 캐시(`_npx/<hash>/`)에 받아 한 번 실행할 뿐이고, 전역 `node_modules`에도 PATH에도 아무것도 남기지 않습니다. 실제 "설치물"은 위 표대로 **대상 repo에 추가된 파일과 `package.json` 변경**입니다.
+CommitGate는 두 곳에 있습니다. **런타임**(`node_modules/commitgate`)과 **프로젝트에 깔린 거버넌스 파일**입니다.
+
+런타임은 package manager가 지웁니다:
+
+```sh
+npm uninstall -D commitgate      # pnpm remove -D commitgate · yarn remove commitgate
+```
+
+프로젝트 파일은 아래 계획을 보고 직접 정리하세요. 먼저 알아둘 것: **`npx commitgate`는 전역 설치가 아닙니다.** npx는 패키지를 npm 캐시(`_npx/<hash>/`)에 받아 한 번 실행할 뿐이고, 전역 `node_modules`에도 PATH에도 아무것도 남기지 않습니다.
 
 제거 계획을 먼저 확인하세요. 이 명령은 **아무것도 지우지 않고** 계획만 출력합니다:
 
@@ -163,7 +292,7 @@ git checkout HEAD -- package.json
 
 파일 삭제는 `npx commitgate uninstall`이 나열해 준 경로만 지우세요. `scripts/req/`나 `workflow/`를 디렉터리째 지우면 그 안의 사용자 파일이나 티켓 증거가 함께 사라집니다.
 
-> git은 빈 디렉터리를 추적하지 않습니다. 파일을 다 지운 뒤 `git status`가 clean이어도 빈 `scripts/`·`workflow/`가 파일시스템에 남을 수 있습니다.
+> git은 빈 디렉터리를 추적하지 않습니다. 파일을 다 지운 뒤 `git status`가 clean이어도 빈 `scripts/`·`workflow/`·`.claude/`·`.cursor/`가 파일시스템에 남을 수 있습니다.
 
 ### 이미 커밋했다면
 
@@ -224,7 +353,7 @@ Windows에서 설치 직후 `codex` 명령을 못 찾으면 새 터미널을 열
 
 ## 수동 명령
 
-대부분의 사용자는 위 프롬프트 방식으로 충분합니다. 아래는 내부에서 어떤 명령이 실행되는지 이해하거나 직접 디버깅할 때만 보면 됩니다.
+대부분의 사용자는 `req:next`가 시키는 대로만 하면 됩니다. 아래는 내부에서 어떤 명령이 실행되는지 이해하거나 직접 디버깅할 때만 보면 됩니다.
 
 ```sh
 # 1. 티켓과 브랜치 생성
@@ -263,15 +392,28 @@ npm run req:commit -- 2026-001 --run --message-file commit-message.txt
 
 | 명령 | 용도 |
 |---|---|
-| `npx commitgate` | 프로젝트에 CommitGate 설치 |
-| `npx commitgate --dry-run` | 파일을 쓰지 않고 설치 계획 확인 |
-| `npx commitgate --strict` | 낮은 `cross-spawn` 버전 경고를 설치 실패로 처리 |
+| `npm install -D commitgate` | **런타임 설치 (선행 필수)** — 실행 코드가 `node_modules/commitgate`에 들어옵니다 |
+| `npx commitgate init` | 프로젝트에 설정·계약·스키마와 `req:*` 스크립트 설치 |
+| `npx commitgate init --dry-run` | 파일을 쓰지 않고 설치 계획 확인 |
+| `npx commitgate init --strict` | 정합성 경고를 설치 실패로 처리 (gitignore된 계약 포인터, 설치 커밋을 안전하게 만들 수 없는 워킹트리 등) — 파일을 하나도 쓰기 전에 중단 |
+| `npx commitgate init --no-agent-entrypoints` | `.claude/`·`.cursor/`·`CLAUDE.md` 설치 건너뛰기 |
+| `npx commitgate migrate [--apply]` | 예전 vendored 설치본 → 런타임 패키지 전환 (기본: 계획만, 비파괴) |
 | `npx commitgate uninstall` | 제거 계획 확인 (읽기 전용 — 아무것도 지우지 않음) |
-| `req:new <slug> --run` | REQ 티켓, 브랜치, 설계문서 생성 |
-| `req:review-codex <id> --kind design --run` | 설계 리뷰 |
-| `req:review-codex <id> --kind phase --run` | 구현 리뷰 |
-| `req:doctor <id>` | 게이트 상태 확인 |
-| `req:commit <id> --run -m "message"` | 승인된 변경 커밋 |
+| `npm uninstall -D commitgate` | 런타임 제거 |
+| `npm run req:new -- <slug> --run` | REQ 티켓, 브랜치, 설계문서 생성 |
+| `npm run req:next -- <id> [--json]` | **다음 행동 계산** (읽기 전용) |
+| `npm run req:review-codex -- <id> --kind design --run` | 설계 리뷰 |
+| `npm run req:review-codex -- <id> --kind phase --phase <p> --run` | 구현 리뷰 |
+| `npm run req:doctor -- <id>` | 게이트 상태 확인 |
+| `npm run req:commit -- <id> --run -m "message"` | 승인된 변경 커밋 |
+
+`req:*`는 PATH에 잡히는 실행 파일이 아니라 **`package.json` 스크립트**입니다. npm은 인자 전달에 `--` 구분자가 필요합니다.
+
+```sh
+npm  run req:next -- 2026-002    # npm
+pnpm req:next 2026-002           # pnpm
+yarn req:next 2026-002           # yarn
+```
 
 ---
 
@@ -285,9 +427,16 @@ npm run req:commit -- 2026-001 --run --message-file commit-message.txt
 | `ticketRoot` | `"workflow"` | REQ 티켓 폴더 |
 | `packageManager` | 자동 감지 | `npm`, `pnpm`, `yarn` |
 | `designDocs` | `00/01/02` 문서 | 설계 문서 파일명 |
+| `reviewPersonaPath` | `"workflow/review-persona.md"` | 리뷰 프롬프트 첫 블록. `null`이면 비활성 |
+| `reviewModel` | `"gpt-5.6-terra"` | codex 리뷰 모델(`-c model=`로 고정). `null`이면 codex 전역 설정을 상속 |
+| `reviewReasoningEffort` | `"high"` | codex 리뷰 추론강도. `none`·`minimal`·`low`·`medium`·`high`·`xhigh` 중 하나. `null`이면 전역 상속 |
 
 빈 `branchPrefix`나 프로젝트 밖으로 나가는 경로는 거부됩니다.
 
+**리뷰 모델·추론강도 고정**: `req:review-codex`는 codex 인자에 `-c model=`·`-c model_reasoning_effort=`를 주입해 **모델과 추론강도를 고정**합니다. 고정하지 않으면 리뷰가 사용자 전역 `~/.codex/config.toml`(예: `model_reasoning_effort="ultra"`)을 상속해 리뷰 1회가 수 분·토큰 과다가 됩니다. 기본값은 `gpt-5.6-terra`/`high`이고, 프로젝트의 codex가 그 모델을 지원하지 않으면 `req.config.json`에서 바꾸거나 `null`로 두어 전역 설정을 상속시킵니다. override가 실제로 존중되는지는 `npm run verify:overrides`(codex CLI 필요)로 확인할 수 있습니다.
+
+**재리뷰는 stateless**: 재리뷰는 매번 **새 codex 스레드**로 시작합니다(이전 대화를 resume해 누적하지 않음 — 토큰 증가와 findings 심화·이동을 막습니다). 직전 같은 대상의 NEEDS_FIX findings만 참고용으로 프롬프트에 담겨 해소 여부(closure)를 확인합니다.
+
 ---
 
 ## FAQ
@@ -311,17 +460,18 @@ npm run req:commit -- 2026-001 --run --message-file commit-message.txt
 
 ## 현재 범위
 
-현재 버전은 **Stage A: vendored scaffold 모델**입니다. 즉 `npx commitgate`가 대상 프로젝트에 워크플로 파일을 복사합니다.
+현재 버전은 **런타임 패키지 모델**입니다. 실행 코드와 런타임 의존성은 `node_modules/commitgate`에만 있고, 프로젝트에는 거버넌스·감사 데이터와 `req:* = commitgate <verb>` 스크립트만 남습니다. (예전 vendored scaffold 설치본은 [`migrate`](#예전-설치본에서-옮겨오기-migrate)로 전환합니다.)
 
 현재 운영 중인 검증입니다.
 
 - GitHub Actions에서 `ubuntu-latest`, `macos-latest`, `windows-latest` × Node 18/20/22 매트릭스를 실행합니다.
-- `npm run smoke`는 pack tarball 설치본의 `commitgate` bin을 실행합니다.
+- `npm run smoke`는 pack tarball을 임시 프로젝트에 실제로 설치해, 대상에 `scripts/req/`가 **없고** `tsx`·`ajv`·`cross-spawn`이 **주입되지 않으며** 다섯 `req:*`가 패키지 bin을 가리키는지, 그리고 `npm run req:doctor`가 실제로 패키지 안의 모듈까지 dispatch되는지 확인합니다. `migrate` 비파괴성도 같은 방식으로 검증합니다.
 - Windows `.cmd` 래퍼 주입 회귀 테스트가 패키지 매니저와 Codex wrapper 경로를 보호합니다.
 
 아래는 후속 범위입니다.
 
-- `node_modules`에서 직접 실행하는 라이브러리 모델
+- Yarn PnP 지원, 워크스페이스 하위 패키지 독립 설치
+- 자산↔런타임 버전 드리프트 탐지
 - 비-git VCS 지원
 - 더 다양한 설계문서 템플릿
 

package/bin/commitgate.mjs

@@ -10,20 +10,29 @@
  *    (node:module의 register('tsx/esm')는 tsx v4가 deprecated --loader로 간주해 거부 → tsx 자체 API 사용.)
  * (Stage B에서 init.ts를 JS로 빌드하면 이 런처는 제거 가능.)
  *
- * verb dispatch(REQ-2026-007): `uninstall`만 별도 모듈로 보낸다. verb 없는 호출은 **현행 그대로 init**(하위호환).
- *    dispatch를 여기(단일 bin 진입점)에 두면 uninstall.ts → init.ts 단방향 import가 되어 순환이 생기지 않는다.
+ * verb dispatch(REQ-2026-014 Stage B, 설계 D3): 로컬 패키지 bin이 `req:*`를 dispatch한다.
+ *    - 알려진 verb(`req:new`/`req:next`/`req:review-codex`/`req:doctor`/`req:commit`/`uninstall`/`init`) → 해당 모듈(verb 토큰 소비).
+ *    - argv 없음 **또는 첫 인자가 `-` 옵션**(`--dry-run`·`--dir`·`--strict`·`--force`·`--no-agent-entrypoints`·`-h`) → **init에 argv 전체 전달**(하위호환).
+ *    - 그 외 비-옵션 미지 토큰 → fail-closed(오타를 조용히 init으로 보내지 않는다). `migrate`는 Phase 3에서 등록.
+ *    각 대상 모듈은 `runCli(argv)`(예외→친절한 1줄+exit1 경계)를 export한다. import되면 대상의 `if (isMain)` 가드는 발화하지 않으므로 중복 실행 없음.
  */
 import { register } from 'tsx/esm/api'
 import { fileURLToPath, pathToFileURL } from 'node:url'
 import { dirname, join } from 'node:path'
+import { resolveDispatch } from './dispatch.mjs'
 
 register()
 
 const binDir = dirname(fileURLToPath(import.meta.url))
 const argv = process.argv.slice(2)
-const entry = argv[0] === 'uninstall' ? 'uninstall.ts' : 'init.ts'
-const rest = argv[0] === 'uninstall' ? argv.slice(1) : argv
 
-const mod = await import(pathToFileURL(join(binDir, entry)).href)
+const decision = resolveDispatch(argv)
+if ('unknown' in decision) {
+  // 비-옵션 미지 토큰: fail-closed(스택트레이스 없이 한 줄).
+  console.error(`commitgate: 알 수 없는 명령: ${decision.unknown}`)
+  process.exit(1)
+}
+
+const mod = await import(pathToFileURL(join(binDir, decision.entry)).href)
 // runCli = 예외를 친절한 한 줄 메시지 + exit 1로 변환하는 CLI 경계(스택트레이스 노출 방지).
-mod.runCli(rest)
+mod.runCli(decision.rest)

package/bin/dispatch.d.mts

@@ -0,0 +1,6 @@
+/** 타입 선언 — `bin/dispatch.mjs`(런타임은 tsx 없이 로드돼야 하므로 순수 .mjs로 유지)의 타입. */
+export declare const VERB_MODULES: Record<string, string>
+
+export type DispatchDecision = { entry: string; rest: string[] } | { unknown: string }
+
+export declare function resolveDispatch(argv: string[]): DispatchDecision

package/bin/dispatch.mjs

@@ -0,0 +1,38 @@
+/**
+ * commitgate bin verb dispatch — 순수 결정 로직(부작용 없음, 테스트 가능).
+ *
+ * `bin/commitgate.mjs`(register tsx·동적 import 부작용 포함)와 `tests/unit/dispatch.test.ts`가 공유한다.
+ * 설계 D3(REQ-2026-014 Stage B):
+ *   - 알려진 verb → 해당 모듈(verb 토큰 소비).
+ *   - argv 없음 **또는 첫 인자가 `-` 옵션** → init에 argv 전체 전달(하위호환: `npx commitgate --dry-run` 등).
+ *   - 그 외 비-옵션 미지 토큰 → `unknown`(호출부가 fail-closed).
+ *
+ * `migrate`는 **파일 생성과 동시에**(Phase 3) 등록했다. Phase 1이 미리 등록하지 않은 이유는, 등록만 하고 모듈이 없으면
+ * 깨진 동적 import가 raw unhandled rejection으로 터지기 때문이다(`unknown` 분기의 친절한 1줄 오류가 낫다).
+ */
+
+/** verb → 대상 모듈(binDir 기준 상대). req:* 는 패키지의 scripts/req/*.ts 에서 실행(Stage B: 대상 프로젝트에 복사하지 않음). */
+export const VERB_MODULES = {
+  'req:new': '../scripts/req/req-new.ts',
+  'req:next': '../scripts/req/req-next.ts',
+  'req:review-codex': '../scripts/req/review-codex.ts',
+  'req:doctor': '../scripts/req/req-doctor.ts',
+  'req:commit': '../scripts/req/req-commit.ts',
+  uninstall: 'uninstall.ts',
+  migrate: 'migrate.ts',
+  init: 'init.ts',
+}
+
+/**
+ * argv → { entry, rest } 또는 { unknown }.
+ * @param {string[]} argv  process.argv.slice(2)
+ * @returns {{ entry: string, rest: string[] } | { unknown: string }}
+ */
+export function resolveDispatch(argv) {
+  const verb = argv[0]
+  // verb 없음 / init 옵션(`-`로 시작) → init에 argv 전체 전달(D3).
+  if (verb === undefined || verb.startsWith('-')) return { entry: 'init.ts', rest: argv }
+  if (Object.prototype.hasOwnProperty.call(VERB_MODULES, verb)) return { entry: VERB_MODULES[verb], rest: argv.slice(1) }
+  // 비-옵션 미지 토큰: 호출부가 fail-closed 처리(오타를 조용히 init으로 보내지 않는다).
+  return { unknown: verb }
+}