commitgate 0.2.1 → 0.2.2

package/README.md

@@ -1,238 +1,246 @@
-# CommitGate
-
-🌐 **한국어** · [English](./README.en.md)
-
-**AI 코딩 변경을 Codex 리뷰 승인 없이는 커밋하지 못하게 막는 커밋 게이트입니다.**
-
-AI 에이전트가 코드를 빠르게 만들더라도, 리뷰 없이 바로 커밋되면 위험합니다. CommitGate는 변경을 티켓 단위로 묶고, Codex가 승인한 staged tree만 커밋되게 합니다. 승인 후 코드가 바뀌거나 증거가 부족하면 기본적으로 막습니다.
-
-[![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)
-
----
-
-## Quick Start
-
-아래는 가장 짧은 사용 경로입니다. 프로젝트 루트는 **git 저장소이고 `package.json`이 있는 폴더**여야 합니다.
-
-```sh
-npx commitgate
-npm install
-codex --version
-codex login status
-```
-
-그다음 AI 코딩 에이전트에게 아래 프롬프트를 붙여넣습니다.
-
-```text
-이 요청은 일반 구현으로 처리하지 말고, 이 프로젝트에 설치된 CommitGate를 사용해라.
-
-새 REQ 티켓을 만들고 다음 흐름을 끝까지 진행해라:
-req:new → 설계문서 작성 → Codex design 리뷰 → 구현·테스트 → req:doctor → Codex phase 리뷰 → req:commit
-
-자동으로 진행할 것:
-- NEEDS_FIX가 나오면 수정하고 재리뷰해 승인까지 반복한다.
-- 리뷰 대상은 git add 한 파일만이다.
-- `state.json`과 `responses/`는 직접 `git add`하지 않는다.
-
-멈춰서 확인받을 때:
-- req:commit --run 직전
-- main 병합 또는 push 직전
-- reset, clean, force push 같은 destructive 작업 전
-- 요구사항 범위를 바꿔야 할 때
-- Codex 리뷰가 3라운드를 넘어도 승인되지 않을 때
-
-요구사항:
-- 무엇을:
-- 왜:
-- 제약:
-- 완료 기준:
-```
-
-첫 응답은 보통 이렇게 나와야 합니다.
-
-```text
-REQ-2026-002 발행
-브랜치: feat/req-2026-002-profile-edit-api
-phase:
-- phase-1: PATCH /profile 구현
-- phase-2: 테스트와 회귀 확인
-통제점: req:commit --run 직전, push 직전
-```
-
-이후에는 에이전트가 설계, 구현, 테스트, Codex 리뷰를 진행합니다. 사용자는 커밋이나 push 같은 통제점에서만 확인하면 됩니다.
-
----
-
-## 무엇을 보장하나요?
-
-CommitGate가 막는 것은 단순한 명령 실수가 아니라 **리뷰받지 않은 변경이 커밋되는 상황**입니다.
-
-- Codex 리뷰가 실패하거나 없으면 커밋할 수 없습니다.
-- 승인된 staged tree와 지금 커밋하려는 staged tree가 다르면 막습니다.
-- `state.json`, `responses/` 같은 워크플로 내부 파일을 source 커밋에 섞으면 막습니다.
-- Codex CLI가 없거나 실행에 실패하면 조용히 통과하지 않고 실패합니다.
-- 설치 시 기존 `cross-spawn`이 검증 하한보다 낮으면 경고하고, `--strict`에서는 중단합니다.
-- 승인 응답과 증거 파일은 `workflow/REQ-.../responses/`에 남습니다.
-
-한 줄로 말하면, **확실히 승인된 변경만 통과하고 애매하면 멈추는 방식**입니다.
-
----
-
-## 설치가 하는 일
-
-`npx commitgate`는 대상 프로젝트에 아래 파일과 설정을 추가합니다. 기존 파일은 기본적으로 덮어쓰지 않습니다.
-
-| 추가 항목 | 설명 |
-|---|---|
-| `scripts/req/` | `req:new`, `req:review-codex`, `req:doctor`, `req:commit` 스크립트 |
-| `workflow/*.schema.json` | Codex 응답과 설정 검증 스키마 |
-| `req.config.json` | 프로젝트별 설정 |
-| `AGENTS.md` | 에이전트와 Reviewer가 읽는 규칙 템플릿 |
-| `package.json` 스크립트 | `req:*` 명령과 필요한 devDependencies |
-
-미리보기만 하려면:
-
-```sh
-npx commitgate --dry-run
-```
-
-보안 하한 경고를 설치 실패로 취급하려면:
-
-```sh
-npx commitgate --strict
-```
-
-기존 `cross-spawn`이 검증 하한보다 낮으면 파일을 복사하기 전에 중단합니다.
-
----
-
-## 준비물
-
-| 필요 | 확인 명령 | 비고 |
-|---|---|---|
-| Git | `git --version` | 필수 |
-| Node.js 18.17+ | `node --version` | 필수 |
-| npm, pnpm, yarn 중 하나 | `npm --version` | npm 기준으로 안내 |
-| Codex CLI | `codex --version` | 리뷰 실행에 필요 |
-
-Codex CLI가 없다면:
-
-```sh
-npm install -g @openai/codex
-codex login
-codex login status
-```
-
-Windows에서 설치 직후 `codex` 명령을 못 찾으면 새 터미널을 열어 PATH를 다시 읽게 하세요.
-
----
-
-## 수동 명령
-
-대부분의 사용자는 위 프롬프트 방식으로 충분합니다. 아래는 내부에서 어떤 명령이 실행되는지 이해하거나 직접 디버깅할 때만 보면 됩니다.
-
-```sh
-# 1. 티켓과 브랜치 생성
-npm run req:new -- my-feature --run
-
-# 2. 설계 문서 작성 후 stage
-git add workflow/REQ-2026-001/00-requirement.md workflow/REQ-2026-001/01-design.md workflow/REQ-2026-001/02-plan.md
-
-# 3. 설계 리뷰
-npm run req:review-codex -- 2026-001 --kind design --run
-
-# 4. 코드 구현 후 stage
-git add <changed-source-files>
-
-# 5. 게이트 점검
-npm run req:doctor -- 2026-001
-
-# 6. 구현 리뷰
-npm run req:review-codex -- 2026-001 --kind phase --run
-
-# 7. 승인된 코드 커밋
-npm run req:commit -- 2026-001 --run -m "feat: my feature"
-```
-
-중요: source 커밋에는 내가 만든 코드와 문서만 stage하세요. `state.json`과 `responses/`는 도구가 관리합니다.
-
-여러 줄 커밋 메시지는 `-m` 대신 파일을 사용하세요.
-
-```sh
-npm run req:commit -- 2026-001 --run --message-file commit-message.txt
-```
-
----
-
-## 명령어 요약
-
-| 명령 | 용도 |
-|---|---|
-| `npx commitgate` | 프로젝트에 CommitGate 설치 |
-| `npx commitgate --dry-run` | 파일을 쓰지 않고 설치 계획 확인 |
-| `npx commitgate --strict` | 낮은 `cross-spawn` 버전 경고를 설치 실패로 처리 |
-| `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"` | 승인된 변경 커밋 |
-
----
-
-## 설정
-
-대부분은 기본값으로 충분합니다. 필요하면 프로젝트 루트의 `req.config.json`을 수정하세요.
-
-| 항목 | 기본값 | 설명 |
-|---|---|---|
-| `branchPrefix` | `"feat/req-"` | 새 브랜치 prefix |
-| `ticketRoot` | `"workflow"` | REQ 티켓 폴더 |
-| `packageManager` | 자동 감지 | `npm`, `pnpm`, `yarn` |
-| `designDocs` | `00/01/02` 문서 | 설계 문서 파일명 |
-
-빈 `branchPrefix`나 프로젝트 밖으로 나가는 경로는 거부됩니다.
-
----
-
-## FAQ
-
-**Codex CLI가 없으면 어떻게 되나요?**
-리뷰 명령이 실패합니다. 조용히 승인 처리하지 않습니다.
-
-**승인 후 코드를 조금 고치면 커밋되나요?**
-안 됩니다. 승인된 staged tree와 달라지면 stale 승인으로 보고 다시 리뷰를 요구합니다.
-
-**`state.json`이나 `responses/`는 왜 stage하면 안 되나요?**
-워크플로 증거와 상태 파일입니다. source 커밋에 섞이면 승인 바인딩이 흐려지므로 `req:commit`이 막습니다.
-
-**cross-spawn 버전 경고가 나오면 어떻게 하나요?**
-대상 프로젝트의 기존 `cross-spawn`이 CommitGate가 검증한 하한보다 낮을 수 있다는 뜻입니다. `npm i -D cross-spawn@^7.0.6`으로 올리세요. CI나 보안 민감 환경에서는 `npx commitgate --strict`를 사용해 경고를 실패로 다루세요.
-
-**두 번 설치하면 덮어쓰나요?**
-아니요. 기존 파일은 건너뜁니다. 강제로 갱신하려면 `--force`를 사용하세요.
-
----
-
-## 현재 범위
-
-현재 버전은 **Stage A: vendored scaffold 모델**입니다. 즉 `npx commitgate`가 대상 프로젝트에 워크플로 파일을 복사합니다.
-
-현재 운영 중인 검증입니다.
-
-- GitHub Actions에서 `ubuntu-latest`, `macos-latest`, `windows-latest` × Node 18/20/22 매트릭스를 실행합니다.
-- `npm run smoke`는 pack tarball 설치본의 `commitgate` bin을 실행합니다.
-- Windows `.cmd` 래퍼 주입 회귀 테스트가 패키지 매니저와 Codex wrapper 경로를 보호합니다.
-
-아래는 후속 범위입니다.
-
-- `node_modules`에서 직접 실행하는 라이브러리 모델
-- 비-git VCS 지원
-- 더 다양한 설계문서 템플릿
-
----
-
-## License
-
-[MIT](./LICENSE) © 2026 sol5288
+# CommitGate
+
+🌐 **한국어** · [English](./README.en.md)
+
+**AI 코딩 변경을 Codex 리뷰 승인 없이는 커밋하지 못하게 막는 커밋 게이트입니다.**
+
+AI 에이전트가 코드를 빠르게 만들더라도, 리뷰 없이 바로 커밋되면 위험합니다. CommitGate는 변경을 티켓 단위로 묶고, Codex가 승인한 staged tree만 커밋되게 합니다. 승인 후 코드가 바뀌거나 증거가 부족하면 기본적으로 막습니다.
+
+[![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)
+
+---
+
+## Quick Start
+
+아래는 가장 짧은 사용 경로입니다. 프로젝트 루트는 **git 저장소이고 `package.json`이 있는 폴더**여야 합니다.
+
+```sh
+# 아직 git 저장소가 아니거나 package.json이 없는 새 폴더라면 먼저:
+git init
+npm init -y
+
+# 그다음 설치:
+npx commitgate
+npm install
+codex --version
+codex login status
+```
+
+그다음 AI 코딩 에이전트에게 아래 프롬프트를 붙여넣습니다.
+
+```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 직전
+- main 병합 또는 push 직전
+- reset, clean, force push 같은 destructive 작업 전
+- 요구사항 범위를 바꿔야 할 때
+- Codex 리뷰가 BLOCKED를 반환하거나 제한된 재시도 후에도 판단이 불명확할 때
+
+요구사항:
+- 무엇을:
+- 왜:
+- 제약:
+- 완료 기준:
+```
+
+첫 응답은 보통 이렇게 나와야 합니다.
+
+```text
+REQ-2026-002 발행
+브랜치: feat/req-2026-002-profile-edit-api
+phase:
+- phase-1: PATCH /profile 구현
+- phase-2: 테스트와 회귀 확인
+통제점: req:commit --run 직전, push 직전
+```
+
+이후에는 에이전트가 설계, 구현, 테스트, Codex 리뷰를 진행합니다. 사용자는 커밋이나 push 같은 통제점에서만 확인하면 됩니다.
+
+---
+
+## 무엇을 보장하나요?
+
+CommitGate가 막는 것은 단순한 명령 실수가 아니라 **리뷰받지 않은 변경이 커밋되는 상황**입니다.
+
+- Codex 리뷰가 실패하거나 없으면 커밋할 수 없습니다.
+- 승인된 staged tree와 지금 커밋하려는 staged tree가 다르면 막습니다.
+- `state.json`, `responses/` 같은 워크플로 내부 파일을 source 커밋에 섞으면 막습니다.
+- Codex CLI가 없거나 실행에 실패하면 조용히 통과하지 않고 실패합니다.
+- 리뷰 종료코드는 outcome 기준입니다: `0` 승인, `1` 무효/fail-closed, `2` blocked(지적 없음+미승인), `3` needs-fix.
+- 지적은 없지만 승인도 없는 응답은 NEEDS_FIX가 아니라 BLOCKED이며, 에이전트는 같은 리뷰를 반복하지 않습니다.
+- 설치 시 기존 `cross-spawn`이 검증 하한보다 낮으면 경고하고, `--strict`에서는 중단합니다.
+- 승인 응답과 증거 파일은 `workflow/REQ-.../responses/`에 남습니다.
+
+한 줄로 말하면, **확실히 승인된 변경만 통과하고 애매하면 멈추는 방식**입니다.
+
+---
+
+## 설치가 하는 일
+
+`npx commitgate`는 대상 프로젝트에 아래 파일과 설정을 추가합니다. 기존 파일은 기본적으로 덮어쓰지 않습니다.
+
+| 추가 항목 | 설명 |
+|---|---|
+| `scripts/req/` | `req:new`, `req:review-codex`, `req:doctor`, `req:commit` 스크립트 |
+| `workflow/*.schema.json` | Codex 응답과 설정 검증 스키마 |
+| `req.config.json` | 프로젝트별 설정 |
+| `AGENTS.md` | 에이전트와 Reviewer가 읽는 규칙 템플릿 |
+| `package.json` 스크립트 | `req:*` 명령과 필요한 devDependencies |
+
+미리보기만 하려면:
+
+```sh
+npx commitgate --dry-run
+```
+
+보안 하한 경고를 설치 실패로 취급하려면:
+
+```sh
+npx commitgate --strict
+```
+
+기존 `cross-spawn`이 검증 하한보다 낮으면 파일을 복사하기 전에 중단합니다.
+
+---
+
+## 준비물
+
+| 필요 | 확인 명령 | 비고 |
+|---|---|---|
+| Git | `git --version` | 필수 |
+| Node.js 18.17+ | `node --version` | 필수 |
+| npm, pnpm, yarn 중 하나 | `npm --version` | npm 기준으로 안내 |
+| Codex CLI | `codex --version` | 리뷰 실행에 필요 |
+
+Codex CLI가 없다면:
+
+```sh
+npm install -g @openai/codex
+codex login
+codex login status
+```
+
+Windows에서 설치 직후 `codex` 명령을 못 찾으면 새 터미널을 열어 PATH를 다시 읽게 하세요.
+
+---
+
+## 수동 명령
+
+대부분의 사용자는 위 프롬프트 방식으로 충분합니다. 아래는 내부에서 어떤 명령이 실행되는지 이해하거나 직접 디버깅할 때만 보면 됩니다.
+
+```sh
+# 1. 티켓과 브랜치 생성
+npm run req:new -- my-feature --run
+
+# 2. 설계 문서 작성 후 stage
+git add workflow/REQ-2026-001/00-requirement.md workflow/REQ-2026-001/01-design.md workflow/REQ-2026-001/02-plan.md
+
+# 3. 설계 리뷰
+npm run req:review-codex -- 2026-001 --kind design --run
+
+# 4. 코드 구현 후 stage
+git add <changed-source-files>
+
+# 5. 게이트 점검
+npm run req:doctor -- 2026-001
+
+# 6. 구현 리뷰
+npm run req:review-codex -- 2026-001 --kind phase --run
+
+# 7. 승인된 코드 커밋
+npm run req:commit -- 2026-001 --run -m "feat: my feature"
+```
+
+중요: source 커밋에는 내가 만든 코드와 문서만 stage하세요. `state.json`과 `responses/`는 도구가 관리합니다.
+
+여러 줄 커밋 메시지는 `-m` 대신 파일을 사용하세요.
+
+```sh
+npm run req:commit -- 2026-001 --run --message-file commit-message.txt
+```
+
+---
+
+## 명령어 요약
+
+| 명령 | 용도 |
+|---|---|
+| `npx commitgate` | 프로젝트에 CommitGate 설치 |
+| `npx commitgate --dry-run` | 파일을 쓰지 않고 설치 계획 확인 |
+| `npx commitgate --strict` | 낮은 `cross-spawn` 버전 경고를 설치 실패로 처리 |
+| `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"` | 승인된 변경 커밋 |
+
+---
+
+## 설정
+
+대부분은 기본값으로 충분합니다. 필요하면 프로젝트 루트의 `req.config.json`을 수정하세요.
+
+| 항목 | 기본값 | 설명 |
+|---|---|---|
+| `branchPrefix` | `"feat/req-"` | 새 브랜치 prefix |
+| `ticketRoot` | `"workflow"` | REQ 티켓 폴더 |
+| `packageManager` | 자동 감지 | `npm`, `pnpm`, `yarn` |
+| `designDocs` | `00/01/02` 문서 | 설계 문서 파일명 |
+
+빈 `branchPrefix`나 프로젝트 밖으로 나가는 경로는 거부됩니다.
+
+---
+
+## FAQ
+
+**Codex CLI가 없으면 어떻게 되나요?**
+리뷰 명령이 실패합니다. 조용히 승인 처리하지 않습니다.
+
+**승인 후 코드를 조금 고치면 커밋되나요?**
+안 됩니다. 승인된 staged tree와 달라지면 stale 승인으로 보고 다시 리뷰를 요구합니다.
+
+**`state.json`이나 `responses/`는 왜 stage하면 안 되나요?**
+워크플로 증거와 상태 파일입니다. source 커밋에 섞이면 승인 바인딩이 흐려지므로 `req:commit`이 막습니다.
+
+**cross-spawn 버전 경고가 나오면 어떻게 하나요?**
+대상 프로젝트의 기존 `cross-spawn`이 CommitGate가 검증한 하한보다 낮을 수 있다는 뜻입니다. `npm i -D cross-spawn@^7.0.6`으로 올리세요. CI나 보안 민감 환경에서는 `npx commitgate --strict`를 사용해 경고를 실패로 다루세요.
+
+**두 번 설치하면 덮어쓰나요?**
+아니요. 기존 파일은 건너뜁니다. 강제로 갱신하려면 `--force`를 사용하세요.
+
+---
+
+## 현재 범위
+
+현재 버전은 **Stage A: vendored scaffold 모델**입니다. 즉 `npx commitgate`가 대상 프로젝트에 워크플로 파일을 복사합니다.
+
+현재 운영 중인 검증입니다.
+
+- GitHub Actions에서 `ubuntu-latest`, `macos-latest`, `windows-latest` × Node 18/20/22 매트릭스를 실행합니다.
+- `npm run smoke`는 pack tarball 설치본의 `commitgate` bin을 실행합니다.
+- Windows `.cmd` 래퍼 주입 회귀 테스트가 패키지 매니저와 Codex wrapper 경로를 보호합니다.
+
+아래는 후속 범위입니다.
+
+- `node_modules`에서 직접 실행하는 라이브러리 모델
+- 비-git VCS 지원
+- 더 다양한 설계문서 템플릿
+
+---
+
+## License
+
+[MIT](./LICENSE) © 2026 sol5288

package/bin/commitgate.mjs

@@ -18,4 +18,5 @@ register()
 
 const initTs = pathToFileURL(join(dirname(fileURLToPath(import.meta.url)), 'init.ts')).href
 const mod = await import(initTs)
-mod.main(process.argv.slice(2))
+// runCli = 예외를 친절한 한 줄 메시지 + exit 1로 변환하는 CLI 경계(스택트레이스 노출 방지).
+mod.runCli(process.argv.slice(2))

package/bin/init.ts

@@ -21,10 +21,11 @@ import {
   copyFileSync,
   realpathSync,
 } from 'node:fs'
+import { execFileSync } from 'node:child_process'
 import { resolve, join, dirname, relative } from 'node:path'
 import { fileURLToPath, pathToFileURL } from 'node:url'
 import { loadConfig, stripBom, type PackageManager } from '../scripts/req/lib/config'
-import { createGitAdapter } from '../scripts/req/lib/adapters'
+import { createGitAdapter, type GitRunner } from '../scripts/req/lib/adapters'
 import * as semver from 'semver'
 
 /** 이 패키지 루트(bin/ 기준 1단계 위). 복사 원본. */
@@ -73,7 +74,12 @@ export interface InitResult {
  * targetRoot가 repo top-level과 일치해야 함(하위 디렉터리에 스캐폴드 방지). git 미설치/비-repo → throw(fail-closed).
  */
 function assertGitWorkTree(targetRoot: string): void {
-  const git = createGitAdapter(targetRoot)
+  // probe 전용 runner: 비-repo일 때 git이 뱉는 `fatal: not a git repository` stderr를 삼킨다.
+  // 우리가 더 명확한 조치 메시지로 대체하므로 raw git stderr는 노이즈일 뿐(design 후속 UX).
+  // ⚠️ 전역 GitAdapter 기본(stderr 상속)은 그대로 — 다른 git 호출(req:commit 등)의 진단 손실 방지.
+  const quietRunner: GitRunner = (file, args, opts) =>
+    execFileSync(file, args, { ...opts, stdio: ['ignore', 'pipe', 'ignore'] })
+  const git = createGitAdapter(targetRoot, quietRunner)
   let inside: string
   let topLevel: string
   try {
@@ -98,6 +104,16 @@ export function detectPackageManager(root: string): PackageManager {
   return 'npm'
 }
 
+/**
+ * 대상 pm에 맞는 package.json script 실행 커맨드 문자열.
+ * npm은 임의 스크립트를 `npm run <script>`로만 실행하고 인자 전달에 `--` 구분자가 필요하다
+ * (`npm req:new …`은 "Unknown command"로 실패). pnpm/yarn은 bare script + 인자 직접 전달을 지원.
+ * → 안내 문구가 실제로 복붙 가능한 유효 커맨드가 되도록 pm별로 분기(README 수동 명령과 동일 형태).
+ */
+export function runScriptCmd(pm: PackageManager, script: string, args: string): string {
+  return pm === 'npm' ? `npm run ${script} -- ${args}` : `${pm} ${script} ${args}`
+}
+
 /** dir 하위 모든 파일의 절대경로(재귀). */
 function walkFiles(dir: string): string[] {
   const out: string[] = []
@@ -388,7 +404,7 @@ function printHelp(): void {
   console.log(`commitgate — AI REQ workflow(커밋 게이트) kit 설치
 
 사용법:
-  npx commitgate [--dir <대상repo>] [--force] [--dry-run]
+  npx commitgate [--dir <대상repo>] [--force] [--dry-run] [--strict]
 
 옵션:
   --dir <path>   대상 repo 루트(기본: 현재 디렉터리)
@@ -401,7 +417,10 @@ function printHelp(): void {
   1. <대상repo>에서 의존성 설치(감지된 패키지매니저)
   2. codex CLI 설치 확인(리뷰 실호출용)
   3. req.config.json 조정(branchPrefix/ticketRoot 등)
-  4. <pm> req:new <slug> --run 으로 첫 티켓 생성`)
+  4. 첫 티켓 생성:
+       npm  → npm run req:new -- <slug> --run
+       pnpm → pnpm req:new <slug> --run
+       yarn → yarn req:new <slug> --run`)
 }
 
 export function main(argv: string[]): void {
@@ -430,9 +449,24 @@ export function main(argv: string[]): void {
     console.log(`  1. cd ${r.targetRoot} && ${r.packageManager} install`)
     console.log(`  2. codex --version   # 리뷰 실호출 전제(미설치면 review-codex --run이 fail-closed)`)
     console.log(`  3. req.config.json 확인(branchPrefix 등)`)
-    console.log(`  4. ${r.packageManager} req:new <slug> --run`)
+    console.log(`  4. ${runScriptCmd(r.packageManager, 'req:new', '<slug> --run')}`)
+  }
+}
+
+/**
+ * CLI 경계: main을 실행하되 사전조건 미충족 등 예상된 실패(throw)는
+ * raw 스택트레이스가 아니라 친절한 한 줄 메시지 + 종료코드 1로 표면화한다.
+ * (에러 문구 자체가 이미 조치 안내를 담고 있어 스택트레이스는 노이즈일 뿐 — REQ 후속 UX 개선.)
+ * bin/commitgate.mjs 런처와 직접 실행(`tsx bin/init.ts`)이 공유하는 단일 경계.
+ */
+export function runCli(argv: string[]): void {
+  try {
+    main(argv)
+  } catch (err) {
+    console.error(`commitgate: ${err instanceof Error ? err.message : String(err)}`)
+    process.exitCode = 1
   }
 }
 
 const isMain = import.meta.url === pathToFileURL(process.argv[1] ?? '').href
-if (isMain) main(process.argv.slice(2))
+if (isMain) runCli(process.argv.slice(2))

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "commitgate",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "CommitGate — Builder↔Reviewer(Claude↔Codex) fail-closed 커밋 게이트: 리뷰·승인·증거 없인 커밋을 통과시키지 않는 AI REQ 워크플로 kit (req:new/review-codex/doctor/commit)",
   "type": "module",
   "license": "MIT",