commitgate 0.1.0

package/AGENTS.template.md

@@ -0,0 +1,48 @@
+# AGENTS.md (AI REQ workflow — Codex/Builder 계약)
+
+> 이 파일은 `commitgate`(init)가 대상 repo에 `AGENTS.md`가 없을 때 생성한 **템플릿**이다.
+> 프로젝트 고유 규칙(SSOT 경로·포트·참조 프로젝트·phase 문서 등)은 여기에 직접 채워 넣어라.
+> Codex CLI는 repo 루트의 `AGENTS.md`를 리뷰 컨텍스트로 읽는다.
+
+## 역할
+
+- **Builder(Claude 등)**: REQ 티켓 단위로 설계→구현→테스트. `req:new`로 티켓·브랜치 생성.
+- **Reviewer(Codex)**: `req:review-codex`가 조립한 프롬프트로 design/phase 리뷰. 구조화 응답(`workflow/machine.schema.json`)만 승인 근거.
+
+## 절대 규칙 (어기면 리뷰에서 reject)
+
+### 1. Test-First
+각 phase에서 게이트를 통과시키는 테스트를 먼저 작성(Red) → 최소 구현(Green) → 리팩토링. 테스트 없는 구현은 reject.
+
+### 2. 게이트 통과 전 다음 phase 금지
+`req:doctor` PASS + Codex phase 리뷰 승인(STEP_COMPLETE) 전에는 다음 phase로 진입하지 않는다.
+
+### 3. 승인 바인딩(fail-closed) 우회 금지
+- staged tree는 승인된 tree와 일치해야 한다(D9). 승인 후 재stage/설계 변경은 stale 승인으로 거부.
+- 워킹트리는 리뷰 시점에 clean해야 한다(비-스크래치 unstaged/untracked → D10 FAIL).
+- codex 미설치/실패는 silent 처리 금지 — 명확히 fail-closed.
+
+### 4. 커밋 정책
+- 각 phase는 의미 있는 커밋. "WIP" 금지.
+- 커밋 메시지 컨벤션: `test/feat/fix/refactor/docs/chore` 접두사. `[Codex]`/`[Claude]` 같은 메타 정보 금지(Reviewer 편향 방지).
+- HIGH 영향 phase는 `req:commit --run` 직전 사용자 확인(`state.user_commit_confirmed`).
+
+## 사람에게 보고해야 할 때
+
+- HIGH commit 실행 직전
+- main merge / push 직전
+- destructive 작업(reset/clean/force push) 필요
+- 설계 범위 변경 또는 비목표 추가 필요
+- Codex 리뷰 3라운드 이상 반복 또는 판단 불명확
+- git·Codex CLI·Node·패키지매니저 등 필수 전제 미충족(fail-closed)
+
+## 워크플로 명령
+
+| 명령 | 용도 |
+|---|---|
+| `req:new <slug> --run` | REQ 티켓 생성(채번·브랜치·`00/01/02` 스캐폴드) |
+| `req:review-codex <id> --kind design\|phase [--phase <p>] --run` | Codex 리뷰 조립·호출·승인 반영 |
+| `req:doctor <id>` | 일관성 게이트(D-체크) |
+| `req:commit <id> [--run] [--message-file <f>]` | 승인된 phase 커밋 + evidence-finalize |
+
+설정은 repo 루트의 `req.config.json`(선택). 자세한 계약은 `README.md` 참조.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 sol5288
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,224 @@
+# CommitGate 🚦
+
+**AI가 짠 코드를, 다른 AI가 리뷰하고 승인해야만 커밋되게 하는 "커밋 관문(gate)".**
+
+> 한 줄 요약: **만드는 AI(Builder)** 와 **검사하는 AI(Reviewer)** 를 짝지어, **리뷰·승인·증거 없이는 커밋이 통과하지 못하게** 막아줍니다.
+
+[![license](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
+
+---
+
+## 🤔 이게 뭔가요? (비유로)
+
+공항 보안 검색대를 떠올려 보세요. 아무리 급해도 **검색대를 통과하지 않으면** 탑승구로 갈 수 없죠.
+
+CommitGate도 똑같습니다. 코드를 아무리 많이 만들어도 **"검사 → 승인"이라는 관문을 통과하지 않으면 `git commit`이 막힙니다.**
+
+- 🛠️ **Builder(만드는 쪽)** — 당신, 또는 당신의 AI 코딩 도구(예: Claude Code). 요구사항을 설계하고 코드를 짭니다.
+- 🔎 **Reviewer(검사하는 쪽)** — **Codex CLI**. Builder가 만든 걸 **독립적으로 다시 검토**해서 통과/보완을 판정합니다.
+- 🚦 **CommitGate** — 그 사이에 서서, **Reviewer가 승인한 코드만** 커밋되게 하는 규칙(관문).
+
+즉, "혼자 만들고 혼자 커밋"이 아니라 **"만든 AI ↔ 검사한 AI"의 교차 검증**을 강제합니다.
+
+## 🎯 어떤 문제를 푸나요?
+
+AI는 코드를 **빠르게** 만들지만, 검증 없이 그대로 커밋되면 위험합니다. CommitGate는:
+
+- ✅ 모든 변경이 **리뷰를 반드시 거치게** 합니다.
+- ✅ 승인은 **"리뷰한 바로 그 코드"에 묶입니다.** (승인 후 몰래 코드를 바꿔치기 못 함 — 지문처럼 대조)
+- ✅ 무언가 애매하거나 빠지면 **일단 막습니다(fail-closed).** "확실할 때만 통과"가 기본값이라 안전합니다.
+- ✅ 누가 언제 무엇을 승인했는지 **증거가 파일로 남습니다.**
+
+## 🔄 동작 흐름 한눈에
+
+```
+① 티켓 만들기      →  ② 설계 작성  →  ③ 설계 리뷰(Codex)  →  ④ 코드 구현
+      req:new                            req:review-codex
+
+   →  ⑤ 관문 점검   →  ⑥ 구현 리뷰(Codex)  →  ⑦ 승인되면 커밋
+        req:doctor        req:review-codex           req:commit
+```
+
+각 단계에서 **통과하지 못하면 다음으로 못 넘어갑니다.**
+
+---
+
+## 📦 준비물 (Prerequisites)
+
+시작 전에 아래 4가지가 필요합니다. 터미널에서 하나씩 확인해 보세요.
+
+| 필요한 것 | 확인 명령 | 없으면 |
+|---|---|---|
+| **Git** (필수) | `git --version` | [git-scm.com](https://git-scm.com) 에서 설치 |
+| **Node.js 18.17+** (필수) | `node --version` | [nodejs.org](https://nodejs.org) 에서 설치 |
+| **Codex CLI** (리뷰용) | `codex --version` | OpenAI Codex CLI 설치 (없으면 리뷰만 안 되고 나머지는 됨) |
+| **패키지 매니저** | `npm --version` | Node 설치 시 `npm`은 기본 포함 (또는 `pnpm`/`yarn`) |
+
+> 💡 **Reviewer = Codex CLI** 입니다. 리뷰를 실제로 돌리려면 Codex CLI가 설치되어 있어야 해요. 없으면 리뷰 명령이 "안전하게 실패(fail-closed)"합니다 — 조용히 통과되는 일은 없습니다.
+
+---
+
+## 🚀 설치 (딱 한 줄)
+
+**당신의 프로젝트 폴더**(= git 저장소, `package.json` 있는 곳)에서:
+
+```sh
+npx commitgate
+```
+
+이 명령이 자동으로 해주는 일 (기존 파일은 **덮어쓰지 않아요**):
+
+1. 워크플로 스크립트(`scripts/req/`)와 스키마를 복사합니다.
+2. `req.config.json`(설정 파일)을 만들어 둡니다.
+3. `package.json`에 `req:*` 명령들과 필요한 devDependencies(`tsx`, `ajv`)를 추가합니다.
+4. `AGENTS.md`(Reviewer가 읽는 규칙 파일)가 없으면 템플릿을 만들어 줍니다.
+
+설치 후, 방금 추가된 의존성을 받습니다:
+
+```sh
+npm install
+```
+
+> `--dry-run` 을 붙이면 **실제로 바꾸지 않고** 무엇을 할지 미리 볼 수 있어요: `npx commitgate --dry-run`
+
+---
+
+## 👣 처음부터 끝까지 따라하기
+
+작은 기능 하나를 예로, 전체 흐름을 그대로 밟아 봅시다. (명령은 `npm` 기준이며, `npm run` 뒤 인자는 `--` 다음에 씁니다. `pnpm`을 쓰면 `pnpm req:new my-feature --run` 처럼 `--` 없이 됩니다.)
+
+### 1단계 — 작업 티켓 만들기
+
+```sh
+npm run req:new -- my-feature --run
+```
+
+- 새 브랜치(`feat/req-...`)가 생기고, `workflow/REQ-2026-001/` 폴더에 설계 문서 3종이 만들어집니다.
+- 출력에 **티켓 번호**(예: `REQ-2026-001`)가 나옵니다. 이후 명령에선 번호만 씁니다 → `2026-001`
+
+### 2단계 — 설계 문서 작성
+
+`workflow/REQ-2026-001/` 안의 세 파일을 채웁니다:
+
+- `00-requirement.md` — **무엇을** 왜 만드는가
+- `01-design.md` — **어떻게** 만들 것인가
+- `02-plan.md` — 어떤 **순서/단계**로 진행할 것인가
+
+### 3단계 — 설계 리뷰 받기 (Codex)
+
+작성한 설계를 검사대에 올립니다(= `git add`):
+
+```sh
+git add workflow/REQ-2026-001/00-requirement.md workflow/REQ-2026-001/01-design.md workflow/REQ-2026-001/02-plan.md
+npm run req:review-codex -- 2026-001 --kind design --run
+```
+
+- Codex가 설계를 읽고 **승인** 또는 **보완 요청(NEEDS_FIX)** 을 돌려줍니다.
+- 보완 요청이면 지적사항을 반영하고 **다시 `git add` → 위 명령을 재실행**하세요. 승인될 때까지 반복합니다.
+
+### 4단계 — 코드 구현 + 테스트
+
+설계가 승인되면 실제 코드를 짜고 테스트를 작성합니다.
+
+### 5단계 — 관문 점검
+
+내 변경을 검사대에 올리고, 게이트 상태를 미리 확인합니다:
+
+```sh
+git add <내가-바꾼-코드-파일들>
+npm run req:doctor -- 2026-001
+```
+
+- 여러 항목(설계 승인 유효한지, 검사대에 올린 코드와 승인된 코드가 같은지, 워킹트리가 깨끗한지 등)을 점검해 **PASS/FAIL** 을 보여줍니다.
+
+> ⚠️ **중요:** `git add` 는 **당신이 만든 코드/문서만** 올리세요. `state.json` 이나 `responses/` 같은 워크플로 내부 파일은 **올리지 마세요.** (도구가 알아서 관리합니다. 실수로 올리면 커밋 단계에서 막힙니다.)
+
+### 6단계 — 구현 리뷰 받기 (Codex)
+
+```sh
+npm run req:review-codex -- 2026-001 --kind phase --run
+```
+
+- Codex가 **구현 코드**를 리뷰합니다. 역시 승인될 때까지 반영 → 재실행 반복.
+- 승인되면 `commit_allowed=true` 가 되어 커밋이 열립니다.
+
+### 7단계 — 커밋
+
+```sh
+npm run req:commit -- 2026-001 --run -m "feat: my-feature 구현"
+```
+
+- 관문(doctor 게이트)을 마지막으로 통과한 뒤 **코드 커밋 + 증거 커밋** 을 남깁니다.
+- 승인되지 않았거나, 승인 후 코드가 바뀌었으면 **여기서 막힙니다.** (그게 CommitGate의 핵심)
+
+🎉 끝! 이제 리뷰·승인·증거가 모두 남은 상태로 안전하게 커밋되었습니다.
+
+---
+
+## 📋 명령어 치트시트
+
+| 명령 | 하는 일 |
+|---|---|
+| `npx commitgate` | 프로젝트에 CommitGate 설치(스캐폴딩) |
+| `req:new <이름> --run` | 새 작업 티켓 + 브랜치 + 설계문서 생성 |
+| `req:review-codex <번호> --kind design --run` | **설계** 리뷰(Codex) |
+| `req:review-codex <번호> --kind phase --run` | **구현** 리뷰(Codex) |
+| `req:doctor <번호>` | 관문 점검(통과/실패 표시) |
+| `req:commit <번호> --run -m "메시지"` | 승인된 코드 커밋(+증거) |
+
+> `-m "메시지"` 대신 여러 줄 메시지는 `--message-file 메시지.txt` 로 파일에서 읽을 수 있습니다.
+
+---
+
+## ⚙️ 설정 (`req.config.json`, 선택)
+
+프로젝트 루트의 `req.config.json` 으로 동작을 바꿀 수 있습니다. **파일이 없으면 기본값**으로 잘 동작하니, 처음엔 신경 쓰지 않아도 됩니다.
+
+| 항목 | 기본값 | 뜻 |
+|---|---|---|
+| `branchPrefix` | `"feat/req-"` | 새로 만드는 브랜치 이름 앞부분 |
+| `ticketRoot` | `"workflow"` | 티켓 폴더 위치 |
+| `packageManager` | 자동 감지 | `npm` / `pnpm` / `yarn` |
+| `designDocs` | `00-/01-/02-*.md` | 설계문서 3종 파일명 |
+
+잘못된 값(예: 빈 `branchPrefix`, 폴더 밖으로 벗어나는 경로)은 **안전하게 거부**됩니다.
+
+---
+
+## ❓ 자주 묻는 질문 / 문제 해결
+
+**Q. `codex` 명령이 없다고 나와요.**
+A. Reviewer(Codex CLI)가 설치되어 있어야 리뷰가 돌아갑니다. 설치 전에는 리뷰 명령이 "조용히 통과"하지 않고 **명확히 실패**합니다 — 이게 정상 동작(fail-closed)입니다.
+
+**Q. 커밋 단계에서 "staged tree != approved" 같은 오류가 나요.**
+A. **승인받은 코드와, 지금 검사대(git add)에 올린 코드가 다르다**는 뜻입니다. 승인 후에 코드를 바꿨다면 6단계(구현 리뷰)를 다시 받아 재승인하세요. (승인 바꿔치기를 막는 안전장치입니다.)
+
+**Q. "비-코드 staged 금지(state/responses)" 오류가 나요.**
+A. `git add` 로 `state.json` 이나 `responses/` 를 올렸기 때문입니다. 그 파일들은 **올리지 말고**(도구가 관리), 내가 만든 코드/문서만 올리세요.
+
+**Q. `npx commitgate` 를 두 번 실행하면 덮어써지나요?**
+A. 아니요. **이미 있는 파일은 건너뜁니다**(멱등). 강제로 덮어쓰려면 `--force` 를 붙이세요.
+
+**Q. Windows인데 커밋 메시지 줄바꿈이 이상해요.**
+A. 여러 줄 메시지는 `-m` 대신 `--message-file 파일.txt` 를 쓰면 깔끔합니다.
+
+---
+
+## 🔒 어떻게 "안전"을 보장하나요? (fail-closed)
+
+CommitGate의 원칙은 **"확실히 승인됐을 때만 통과, 조금이라도 애매하면 막는다"** 입니다.
+
+- 설계문서가 없거나 형식이 안 맞으면 → 미승인 취급
+- Codex가 설치 안 됨 / 리뷰 실패 → 통과 아님, 명확히 실패
+- 승인된 코드 지문과 지금 코드가 다르면 → 커밋 거부
+- 워킹트리가 지저분하면(리뷰 안 한 변경 섞임) → 리뷰/커밋 거부
+
+즉, **"막히는 게 기본, 통과가 예외"** 라 실수로 미검증 코드가 새어 나갈 틈을 줄입니다.
+
+---
+
+## 📄 라이선스
+
+[MIT](./LICENSE) © 2026 sol5288
+
+> 이 워크플로는 `palm-kiosk-app`의 REQ-2026-017 portability kit에서 독립 패키지로 추출되었고, **자기 자신을 이 워크플로로 리뷰·승인(dogfood)** 하여 검증되었습니다.

package/bin/commitgate.mjs

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+/**
+ * commitgate bin 런처(Stage A).
+ * npm bin은 TS를 직접 실행 못 하므로 tsx ESM 로더를 얹어 init.ts를 실행한다.
+ *
+ * ⚠️ tsx는 반드시 **이 런처(=패키지) 기준**으로 해소해야 한다(호출 cwd 아님).
+ *    npx로 실행하면 cwd=대상 repo인데 그곳엔 아직 tsx가 없을 수 있어,
+ *    bare `--import tsx`/cwd-상대 해소는 init 전에 ERR_MODULE_NOT_FOUND로 실패한다(REQ-2026-001 design R1 P1).
+ *    `import ... from 'tsx/esm/api'`는 이 .mjs(패키지 node_modules) 기준으로 정적 해소되므로 cwd 무관.
+ *    (node:module의 register('tsx/esm')는 tsx v4가 deprecated --loader로 간주해 거부 → tsx 자체 API 사용.)
+ * (Stage B에서 init.ts를 JS로 빌드하면 이 런처는 제거 가능.)
+ */
+import { register } from 'tsx/esm/api'
+import { fileURLToPath, pathToFileURL } from 'node:url'
+import { dirname, join } from 'node:path'
+
+register()
+
+const initTs = pathToFileURL(join(dirname(fileURLToPath(import.meta.url)), 'init.ts')).href
+const mod = await import(initTs)
+mod.main(process.argv.slice(2))

package/bin/init.ts

@@ -0,0 +1,328 @@
+#!/usr/bin/env tsx
+/**
+ * commitgate init — AI REQ workflow(커밋 게이트) kit을 대상 git repo에 설치(Stage A / Model A: vendored 스캐폴딩).
+ *
+ * 동작(멱등·비파괴):
+ *   1. 대상 repo 감사(git repo·package.json 필수 → 없으면 fail-closed throw)
+ *   2. `scripts/req/**` + `workflow/{machine,req.config}.schema.json` 복사(기존 파일은 --force 없으면 스킵)
+ *   3. `req.config.json` 시드(부재 시): 감지한 packageManager + handoffPath:null(프로젝트별 값은 코어 DEFAULTS가 아니라 config에서 흡수)
+ *   4. 대상 `package.json`에 req:* 스크립트·devDeps(ajv/tsx) 주입(기존 키 미덮어씀)
+ *   5. `AGENTS.md` 부재 시 템플릿 생성(있으면 스킵 — Codex 계약 보존)
+ *
+ * 코어 승인 바인딩·staged tree 검증은 건드리지 않는다(복사만). 프로젝트 차이는 req.config.json에서만 흡수.
+ */
+import {
+  existsSync,
+  readFileSync,
+  writeFileSync,
+  mkdirSync,
+  readdirSync,
+  statSync,
+  copyFileSync,
+  realpathSync,
+} from 'node:fs'
+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'
+
+/** 이 패키지 루트(bin/ 기준 1단계 위). 복사 원본. */
+const PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..')
+
+/** 대상 package.json에 주입할 req:* 스크립트. */
+const REQ_SCRIPTS: Record<string, string> = {
+  'req:new': 'tsx scripts/req/req-new.ts',
+  'req:review-codex': 'tsx scripts/req/review-codex.ts',
+  'req:doctor': 'tsx scripts/req/req-doctor.ts',
+  'req:commit': 'tsx scripts/req/req-commit.ts',
+}
+
+/** 대상 package.json에 주입할 devDeps(워크플로 실행 전제). cross-spawn = 복사된 adapters.ts의 안전 spawn(P1) 런타임 의존. */
+const REQ_DEV_DEPS: Record<string, string> = {
+  ajv: '^8.20.0',
+  'cross-spawn': '^7.0.6',
+  tsx: '^4.19.1',
+}
+
+export interface InitOptions {
+  dir: string
+  force: boolean
+  dryRun: boolean
+}
+
+export interface InitResult {
+  targetRoot: string
+  copied: string[] // repo-상대 경로(신규 복사)
+  skipped: string[] // repo-상대 경로(이미 존재 → 미덮어씀)
+  configAction: 'created' | 'merged' | 'unchanged' // req.config.json: 신규 생성 / 누락키 병합 / 변경 없음
+  configKeysAdded: string[] // 병합 시 추가된 키(handoffPath·packageManager)
+  packageJsonAdded: string[] // 추가된 script/devDep 키
+  agentsCreated: boolean
+  packageManager: PackageManager
+  dryRun: boolean
+}
+
+/**
+ * 대상이 진짜 git work tree인지 실제 git으로 검증(D5, design R1 P2). `.git` 경로 존재만으론 부족(fake 마커 통과).
+ * targetRoot가 repo top-level과 일치해야 함(하위 디렉터리에 스캐폴드 방지). git 미설치/비-repo → throw(fail-closed).
+ */
+function assertGitWorkTree(targetRoot: string): void {
+  const git = createGitAdapter(targetRoot)
+  let inside: string
+  let topLevel: string
+  try {
+    inside = git.exec(['rev-parse', '--is-inside-work-tree'])
+    topLevel = git.exec(['rev-parse', '--show-toplevel'])
+  } catch {
+    throw new Error(`대상이 git repo가 아님: ${targetRoot} — 'git init' 후 재시도(워크플로는 git 전제).`)
+  }
+  if (inside !== 'true') throw new Error(`대상이 git work tree가 아님: ${targetRoot}`)
+  // Windows 임시경로(8.3 short name·drive/컴포넌트 case)·symlink 차이 정규화.
+  // realpathSync.native = OS API라 컴포넌트 실제 case까지 canonical(WINDOWS/TEMP → Windows/Temp).
+  const norm = (p: string): string => resolve(realpathSync.native(p))
+  if (norm(topLevel) !== norm(targetRoot))
+    throw new Error(`대상이 git repo 최상위가 아님: ${targetRoot} (top-level=${topLevel}) — repo 루트에서 실행.`)
+}
+
+/** lockfile로 대상 패키지매니저 감지(없으면 npm — 가장 보편적 기본). */
+export function detectPackageManager(root: string): PackageManager {
+  if (existsSync(join(root, 'pnpm-lock.yaml'))) return 'pnpm'
+  if (existsSync(join(root, 'yarn.lock'))) return 'yarn'
+  if (existsSync(join(root, 'package-lock.json'))) return 'npm'
+  return 'npm'
+}
+
+/** dir 하위 모든 파일의 절대경로(재귀). */
+function walkFiles(dir: string): string[] {
+  const out: string[] = []
+  for (const entry of readdirSync(dir)) {
+    const abs = join(dir, entry)
+    if (statSync(abs).isDirectory()) out.push(...walkFiles(abs))
+    else out.push(abs)
+  }
+  return out
+}
+
+/**
+ * srcAbs 파일들을 targetRoot 하위 동일 상대경로로 복사. 기존 파일은 force 없으면 스킵.
+ * srcBase는 상대경로 계산 기준(= PACKAGE_ROOT)이라 대상에서도 같은 레이아웃 유지.
+ */
+function copyInto(
+  srcFiles: string[],
+  srcBase: string,
+  targetRoot: string,
+  opts: InitOptions,
+  copied: string[],
+  skipped: string[],
+): void {
+  for (const srcAbs of srcFiles) {
+    const rel = relative(srcBase, srcAbs).replace(/\\/g, '/')
+    const destAbs = join(targetRoot, rel)
+    if (existsSync(destAbs) && !opts.force) {
+      skipped.push(rel)
+      continue
+    }
+    copied.push(rel)
+    if (opts.dryRun) continue
+    mkdirSync(dirname(destAbs), { recursive: true })
+    copyFileSync(srcAbs, destAbs)
+  }
+}
+
+/** JSON 파일을 객체로 파싱(fail-closed). 파싱 실패·비-객체(배열/원시)면 throw. */
+function parseJsonObject(path: string, label: string): Record<string, unknown> {
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(stripBom(readFileSync(path, 'utf8')))
+  } catch (e) {
+    throw new Error(`${label} 파싱 실패(${path}): ${(e as Error).message}`)
+  }
+  if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed))
+    throw new Error(`${label}이 JSON 객체가 아님(${path})`)
+  return parsed as Record<string, unknown>
+}
+
+/**
+ * 설치 코어. IO는 여기서만(테스트가 임시 repo로 직접 호출).
+ * **Preflight(전 검증·파싱) → Apply(쓰기) 2단계** — malformed 입력에 대해 어떤 파일도 복사·수정하기 전에 실패한다(부분 설치 방지, design R2 P2).
+ */
+export function runInit(opts: InitOptions): InitResult {
+  const targetRoot = resolve(opts.dir)
+
+  // ══ Preflight: 모든 검증·파싱을 어떤 쓰기보다 먼저 ═══════════════════
+  if (!existsSync(targetRoot) || !statSync(targetRoot).isDirectory())
+    throw new Error(`대상 디렉터리가 없음: ${targetRoot}`)
+  assertGitWorkTree(targetRoot) // 실제 git probe(fake .git 마커 거부)
+
+  const pkgPath = join(targetRoot, 'package.json')
+  if (!existsSync(pkgPath))
+    throw new Error(`package.json 없음: ${targetRoot} — 'npm init' 등으로 먼저 생성(req:* 스크립트 주입 대상).`)
+  const pkg = parseJsonObject(pkgPath, 'package.json') as {
+    scripts?: Record<string, string>
+    devDependencies?: Record<string, string>
+  }
+  // scripts·devDependencies가 존재하면 반드시 plain object — 배열/원시면 patch가 조용히 유실되어(성공 보고인데 req:* 미주입) fail-closed 위반(phase R1 P2).
+  for (const field of ['scripts', 'devDependencies'] as const) {
+    const v = (pkg as Record<string, unknown>)[field]
+    if (v !== undefined && (typeof v !== 'object' || v === null || Array.isArray(v)))
+      throw new Error(`package.json의 ${field} 필드가 객체가 아님(${pkgPath}) — req:* 주입 불가(배열/원시 미지원).`)
+  }
+
+  const cfgPath = join(targetRoot, 'req.config.json')
+  const existingCfg = existsSync(cfgPath) ? parseJsonObject(cfgPath, 'req.config.json') : null
+  // 기존 config는 워크플로 CONFIG_SCHEMA(additionalProperties·enum·type) + 경로 confinement까지 preflight 검증(phase R2 P2).
+  // kit의 loadConfig를 재사용 — schema-invalid(unknown key·bad enum·escaping ticketRoot 등)면 복사 전 throw(첫 req:* 지연 실패 방지).
+  // 병합은 유효 키만 추가(handoffPath:null·packageManager)라 "기존 유효 ⇒ 병합 유효".
+  loadConfig({ root: targetRoot })
+  const packageManager = detectPackageManager(targetRoot)
+
+  // req.config.json 계획(쓰기 없음). handoffPath:null·packageManager를 항상 보장 —
+  // 코어 DEFAULTS의 palm 고유값(handoffPath)이 기존 부분 config에서도 resurface하지 않도록(design R1 P2). 기존 키 보존.
+  let configAction: 'created' | 'merged' | 'unchanged' = 'unchanged'
+  const configKeysAdded: string[] = []
+  let configToWrite: Record<string, unknown> | null = null
+  if (existingCfg === null) {
+    configAction = 'created'
+    configKeysAdded.push('packageManager', 'handoffPath')
+    configToWrite = { packageManager, handoffPath: null }
+  } else {
+    const patch: Record<string, unknown> = {}
+    if (!('handoffPath' in existingCfg)) {
+      patch.handoffPath = null
+      configKeysAdded.push('handoffPath')
+    }
+    if (!('packageManager' in existingCfg)) {
+      patch.packageManager = packageManager
+      configKeysAdded.push('packageManager')
+    }
+    if (configKeysAdded.length > 0) {
+      configAction = 'merged'
+      configToWrite = { ...existingCfg, ...patch }
+    }
+  }
+
+  // package.json 패치 계획(쓰기 없음, 기존 키 미덮어씀)
+  const packageJsonAdded: string[] = []
+  const scripts = pkg.scripts ?? {}
+  const devDeps = pkg.devDependencies ?? {}
+  for (const [k, v] of Object.entries(REQ_SCRIPTS)) {
+    if (!(k in scripts)) {
+      scripts[k] = v
+      packageJsonAdded.push(`scripts.${k}`)
+    }
+  }
+  for (const [k, v] of Object.entries(REQ_DEV_DEPS)) {
+    if (!(k in devDeps)) {
+      devDeps[k] = v
+      packageJsonAdded.push(`devDependencies.${k}`)
+    }
+  }
+
+  const agentsPath = join(targetRoot, 'AGENTS.md')
+  const agentsCreated = !existsSync(agentsPath)
+
+  // ══ Apply: 여기부터 쓰기(preflight 전부 통과 후에만) ═════════════════
+  const copied: string[] = []
+  const skipped: string[] = []
+  copyInto(walkFiles(join(PACKAGE_ROOT, 'scripts', 'req')), PACKAGE_ROOT, targetRoot, opts, copied, skipped)
+  const schemaFiles = ['machine.schema.json', 'req.config.schema.json'].map((f) => join(PACKAGE_ROOT, 'workflow', f))
+  copyInto(schemaFiles, PACKAGE_ROOT, targetRoot, opts, copied, skipped)
+
+  if (!opts.dryRun) {
+    if (configToWrite) writeFileSync(cfgPath, JSON.stringify(configToWrite, null, 2) + '\n', 'utf8')
+    if (packageJsonAdded.length > 0) {
+      pkg.scripts = scripts
+      pkg.devDependencies = devDeps
+      writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + '\n', 'utf8')
+    }
+    if (agentsCreated) copyFileSync(join(PACKAGE_ROOT, 'AGENTS.template.md'), agentsPath)
+  }
+
+  return {
+    targetRoot,
+    copied,
+    skipped,
+    configAction,
+    configKeysAdded,
+    packageJsonAdded,
+    agentsCreated,
+    packageManager,
+    dryRun: opts.dryRun,
+  }
+}
+
+export function parseArgs(argv: string[]): InitOptions {
+  let dir = process.cwd()
+  let force = false
+  let dryRun = false
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i]
+    if (a === '--dir') {
+      const v = argv[i + 1]
+      if (v === undefined) throw new Error('--dir 값 누락')
+      dir = v
+      i++
+    } else if (a === '--force') {
+      force = true
+    } else if (a === '--dry-run') {
+      dryRun = true
+    } else if (a === '-h' || a === '--help') {
+      printHelp()
+      process.exit(0)
+    } else {
+      throw new Error(`알 수 없는 인자: ${a}`)
+    }
+  }
+  return { dir: resolve(dir), force, dryRun }
+}
+
+function printHelp(): void {
+  console.log(`commitgate — AI REQ workflow(커밋 게이트) kit 설치
+
+사용법:
+  npx commitgate [--dir <대상repo>] [--force] [--dry-run]
+
+옵션:
+  --dir <path>   대상 repo 루트(기본: 현재 디렉터리)
+  --force        기존 kit 파일 덮어쓰기(기본: 스킵)
+  --dry-run      변경 없이 수행 예정 목록만 출력
+  -h, --help     도움말
+
+설치 후:
+  1. <대상repo>에서 의존성 설치(감지된 패키지매니저)
+  2. codex CLI 설치 확인(리뷰 실호출용)
+  3. req.config.json 조정(branchPrefix/ticketRoot 등)
+  4. <pm> req:new <slug> --run 으로 첫 티켓 생성`)
+}
+
+export function main(argv: string[]): void {
+  const opts = parseArgs(argv)
+  const r = runInit(opts)
+  const tag = r.dryRun ? '[dry-run] ' : ''
+  console.log(`${tag}commitgate 설치: ${r.targetRoot}`)
+  console.log(`${tag}  packageManager 감지: ${r.packageManager}`)
+  console.log(`${tag}  복사 ${r.copied.length}개 / 스킵(기존) ${r.skipped.length}개`)
+  for (const f of r.copied) console.log(`${tag}    + ${f}`)
+  for (const f of r.skipped) console.log(`${tag}    = ${f} (이미 존재)`)
+  const cfgMsg =
+    r.configAction === 'created'
+      ? `생성(${r.configKeysAdded.join(', ')})`
+      : r.configAction === 'merged'
+        ? `누락키 병합(${r.configKeysAdded.join(', ')})`
+        : '변경 없음(기존 유지)'
+  console.log(`${tag}  req.config.json: ${cfgMsg}`)
+  console.log(
+    `${tag}  package.json: ${r.packageJsonAdded.length > 0 ? '추가 ' + r.packageJsonAdded.join(', ') : '변경 없음'}`,
+  )
+  console.log(`${tag}  AGENTS.md: ${r.agentsCreated ? '템플릿 생성' : '이미 존재(유지)'}`)
+  if (!r.dryRun) {
+    console.log(`\n다음:`)
+    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`)
+  }
+}
+
+const isMain = import.meta.url === pathToFileURL(process.argv[1] ?? '').href
+if (isMain) main(process.argv.slice(2))