commitgate 0.1.0 → 0.1.2

package/README.en.md

@@ -0,0 +1,217 @@
+# CommitGate
+
+🌐 [한국어](./README.md) · **English**
+
+**A commit gate that blocks AI-generated code from being committed until Codex has reviewed and approved it.**
+
+AI coding agents can move quickly, but unreviewed changes should not go straight into your history. CommitGate wraps each change in a REQ ticket and only allows the staged tree approved by Codex to be committed. If the code changes after approval, or if evidence is missing, it fails closed.
+
+[![license](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
+
+---
+
+## Quick Start
+
+Run this from your project root. The project must be a **git repository with a `package.json`**.
+
+```sh
+npx commitgate
+npm install
+codex --version
+codex login status
+```
+
+Then paste this prompt into your AI coding agent.
+
+```text
+Do not handle this as a normal implementation. Use the CommitGate workflow installed in this project.
+
+Create a new REQ ticket and run this flow end to end:
+req:new → write design docs → Codex design review → implement and test → req:doctor → Codex phase review → req:commit
+
+Proceed automatically:
+- If Codex returns NEEDS_FIX, fix the findings and rerun review until approved.
+- The review target is only what has been staged with git add.
+- Do not manually git add state.json or responses/.
+
+Stop for human confirmation only:
+- Right before req:commit --run
+- Before merging to main or pushing
+- Before destructive actions such as reset, clean, or force push
+- When the requested scope must change
+- When Codex review is still not approved after 3 rounds
+
+Requirement:
+- What:
+- Why:
+- Constraints:
+- Done when:
+```
+
+The agent's first reply should look roughly like this.
+
+```text
+REQ-2026-002 created
+Branch: feat/req-2026-002-profile-edit-api
+Phases:
+- phase-1: implement PATCH /profile
+- phase-2: tests and regression checks
+Control points: before req:commit --run, before push
+```
+
+After that, the agent runs design, implementation, tests, and Codex review. You only confirm at control points such as commit or push.
+
+---
+
+## What Does It Enforce?
+
+CommitGate is designed to block **unreviewed changes from being committed**, not just to wrap commands.
+
+- No Codex approval means no commit.
+- If the approved staged tree differs from the current staged tree, the commit is blocked.
+- Workflow files such as `state.json` and `responses/` cannot be mixed into the source commit.
+- If Codex CLI is missing or fails, the workflow fails instead of silently passing.
+- Approval responses and evidence are kept under `workflow/REQ-.../responses/`.
+
+In short: **approved changes pass, ambiguous changes stop.**
+
+---
+
+## What Installation Adds
+
+`npx commitgate` adds the following to the target project. Existing files are not overwritten by default.
+
+| Added item | Purpose |
+|---|---|
+| `scripts/req/` | `req:new`, `req:review-codex`, `req:doctor`, `req:commit` scripts |
+| `workflow/*.schema.json` | Schemas for Codex responses and config |
+| `req.config.json` | Project-level configuration |
+| `AGENTS.md` | Template rules for the agent and reviewer |
+| `package.json` scripts | `req:*` commands and required devDependencies |
+
+Preview without writing files:
+
+```sh
+npx commitgate --dry-run
+```
+
+---
+
+## Prerequisites
+
+| Requirement | Check | Notes |
+|---|---|---|
+| Git | `git --version` | Required |
+| Node.js 18.17+ | `node --version` | Required |
+| npm, pnpm, or yarn | `npm --version` | Examples use npm |
+| Codex CLI | `codex --version` | Required for review runs |
+
+If Codex CLI is not installed:
+
+```sh
+npm install -g @openai/codex
+codex login
+codex login status
+```
+
+On Windows, if `codex` is not found right after installation, open a new terminal so PATH is reloaded.
+
+---
+
+## Manual Commands
+
+Most users should use the prompt flow above. This section is for understanding what the workflow runs internally or for debugging.
+
+```sh
+# 1. Create a ticket and branch
+npm run req:new -- my-feature --run
+
+# 2. Write design docs, then stage them
+git add workflow/REQ-2026-001/00-requirement.md workflow/REQ-2026-001/01-design.md workflow/REQ-2026-001/02-plan.md
+
+# 3. Design review
+npm run req:review-codex -- 2026-001 --kind design --run
+
+# 4. Implement code, then stage source files
+git add <changed-source-files>
+
+# 5. Gate check
+npm run req:doctor -- 2026-001
+
+# 6. Implementation review
+npm run req:review-codex -- 2026-001 --kind phase --run
+
+# 7. Commit approved code
+npm run req:commit -- 2026-001 --run -m "feat: my feature"
+```
+
+Important: only stage code and documents you authored for the source commit. `state.json` and `responses/` are managed by the tool.
+
+For multi-line commit messages, use a file instead of `-m`.
+
+```sh
+npm run req:commit -- 2026-001 --run --message-file commit-message.txt
+```
+
+---
+
+## Command Cheat Sheet
+
+| Command | Purpose |
+|---|---|
+| `npx commitgate` | Install CommitGate into a project |
+| `req:new <slug> --run` | Create a REQ ticket, branch, and design docs |
+| `req:review-codex <id> --kind design --run` | Review the design |
+| `req:review-codex <id> --kind phase --run` | Review the implementation |
+| `req:doctor <id>` | Check gate status |
+| `req:commit <id> --run -m "message"` | Commit approved changes |
+
+---
+
+## Configuration
+
+Defaults are enough for most projects. If needed, edit `req.config.json` in the project root.
+
+| Key | Default | Meaning |
+|---|---|---|
+| `branchPrefix` | `"feat/req-"` | Prefix for new branches |
+| `ticketRoot` | `"workflow"` | REQ ticket directory |
+| `packageManager` | auto-detected | `npm`, `pnpm`, or `yarn` |
+| `designDocs` | `00/01/02` docs | Design document filenames |
+
+Empty `branchPrefix` values and paths that escape the project root are rejected.
+
+---
+
+## FAQ
+
+**What happens if Codex CLI is missing?**
+The review command fails. It is not treated as approval.
+
+**Can I edit code after approval and still commit?**
+No. If the staged tree changes after approval, CommitGate treats the approval as stale and requires review again.
+
+**Why should I not stage `state.json` or `responses/`?**
+They are workflow state and evidence files. Mixing them into the source commit weakens the approval binding, so `req:commit` blocks it.
+
+**Does running install twice overwrite files?**
+No. Existing files are skipped. Use `--force` if you intentionally want to refresh them.
+
+---
+
+## Current Scope
+
+The current release is **Stage A: vendored scaffold model**. `npx commitgate` copies workflow files into the target project.
+
+Future scope:
+
+- Running directly from `node_modules` as a library-style model
+- Non-git VCS support
+- More design document templates
+- Broader Linux/macOS CI smoke coverage
+
+---
+
+## License
+
+[MIT](./LICENSE) © 2026 sol5288

package/README.md

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "commitgate",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "CommitGate — Builder↔Reviewer(Claude↔Codex) fail-closed 커밋 게이트: 리뷰·승인·증거 없인 커밋을 통과시키지 않는 AI REQ 워크플로 kit (req:new/review-codex/doctor/commit)",
   "type": "module",
   "license": "MIT",
@@ -43,7 +43,8 @@
     "bin",
     "AGENTS.template.md",
     "req.config.json.sample",
-    "README.md"
+    "README.md",
+    "README.en.md"
   ],
   "engines": {
     "node": ">=18.17"