npm - commitgate - Versions diffs - 0.1.1 → 0.2.0 - Mend

commitgate 0.1.1 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (4) hide show

package/README.en.md CHANGED Viewed

@@ -1,341 +1,217 @@
-# CommitGate 🚦
+# CommitGate
 🌐 [한국어](./README.md) · **English**
-**A "commit gate" that lets AI-written code be committed only after a *different* AI reviews and approves it.**
+**A commit gate that blocks AI-generated code from being committed until Codex has reviewed and approved it.**
-> In one line: pair a **Builder AI** with a **Reviewer AI** so that **nothing gets committed without review, approval, and evidence.**
+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)
 ---
-## 🤔 What is this? (an analogy)
+## Quick Start
-Think of an airport security checkpoint. No matter how much of a hurry you're in, you **can't reach the gate without passing through security.**
+Run this from your project root. The project must be a **git repository with a `package.json`**.
-CommitGate works the same way. No matter how much code you produce, **`git commit` is blocked until it passes the "review → approval" gate.**
-- 🛠️ **Builder (the maker)** — you, or your AI coding tool (e.g. Claude Code). Designs the requirement and writes the code.
-- 🔎 **Reviewer (the checker)** — the **Codex CLI**. **Independently re-reviews** what the Builder made and rules pass / needs-fix.
-- 🚦 **CommitGate** — stands between them and lets **only Reviewer-approved code** be committed.
-In short, instead of "build alone, commit alone," it enforces **cross-verification between the AI that built it and the AI that checked it.**
-## 🎯 What problem does it solve?
-AI produces code **fast**, but committing it without verification is risky. CommitGate:
-- ✅ Forces **every change through review.**
-- ✅ Binds approval to **"the exact code that was reviewed."** (You can't swap in changes after approval — it's compared like a fingerprint.)
-- ✅ **Blocks by default (fail-closed)** whenever something is ambiguous or missing. "Pass only when certain" is the default, so it's safe.
-- ✅ Leaves **evidence on disk** of who approved what and when.
-## 🔄 The flow at a glance
-```
-① create ticket   →  ② write design →  ③ design review(Codex) →  ④ implement code
-      req:new                            req:review-codex
-   →  ⑤ gate check   →  ⑥ code review(Codex)  →  ⑦ commit once approved
-        req:doctor        req:review-codex           req:commit
+```sh
+npx commitgate
+npm install
+codex --version
+codex login status
 ```
-At each step, **if it doesn't pass, you can't move to the next.**
----
-## 📦 Prerequisites
+Then paste this prompt into your AI coding agent.
-You need these 4 things before starting. Check each in your terminal.
+```text
+Do not handle this as a normal implementation. Use the CommitGate workflow installed in this project.
-| What | Check command | If missing |
-|---|---|---|
-| **Git** (required) | `git --version` | install from [git-scm.com](https://git-scm.com) |
-| **Node.js 18.17+** (required) | `node --version` | install from [nodejs.org](https://nodejs.org) |
-| **Codex CLI** (for review) | `codex --version` | install OpenAI Codex CLI (without it only review is unavailable; the rest works) |
-| **Package manager** | `npm --version` | `npm` ships with Node (or use `pnpm`/`yarn`) |
-> 💡 **Reviewer = Codex CLI.** To actually run reviews, the Codex CLI must be installed. Without it, review commands **fail safely (fail-closed)** — they never silently pass.
-### 🔧 Install & log in to the Codex CLI (Reviewer setup)
+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
-Reviews in CommitGate are handled by the **OpenAI Codex CLI**. Three steps:
+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/.
-**① Install**
+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
-```sh
-# npm (all OSes)
-npm install -g @openai/codex
-# or macOS Homebrew
-brew install codex
+Requirement:
+- What:
+- Why:
+- Constraints:
+- Done when:
 ```
-Verify:
+The agent's first reply should look roughly like this.
-```sh
-codex --version      # e.g. codex-cli 0.4x.x
+```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
 ```
-**② Log in** — pick whichever is easier
-- **Option A. With a ChatGPT account (recommended, browser)**
-  ```sh
-  codex login
-  ```
-  A browser opens → sign in with your ChatGPT account → return to the terminal when done.
+After that, the agent runs design, implementation, tests, and Codex review. You only confirm at control points such as commit or push.
-- **Option B. With an OpenAI API key**
-  ```sh
-  # via environment variable (simplest)
-  export OPENAI_API_KEY=sk-...        # Windows PowerShell: $env:OPENAI_API_KEY="sk-..."
+---
-  # or store the key in Codex
-  printenv OPENAI_API_KEY | codex login --with-api-key
-  ```
-  Create an API key at [platform.openai.com](https://platform.openai.com/api-keys).
+## What Does It Enforce?
-**③ Verify login**
+CommitGate is designed to block **unreviewed changes from being committed**, not just to wrap commands.
-```sh
-codex login status     # shows login status
-codex doctor           # full diagnosis of install, auth, and environment (explains any issue)
-```
+- 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/`.
-> ✅ If `codex --version` and `codex login status` look good, the Reviewer is ready. Move on to `npx commitgate`.
-> ⚠️ If Windows can't find the `codex` command, open a **new terminal** so PATH is reloaded (a common issue right after a global install).
+In short: **approved changes pass, ambiguous changes stop.**
 ---
-## 🚀 Install (one line)
-**In your project folder** (= a git repo that has a `package.json`):
+## What Installation Adds
-```sh
-npx commitgate
-```
+`npx commitgate` adds the following to the target project. Existing files are not overwritten by default.
-What this does automatically (it **never overwrites** existing files):
-1. Copies the workflow scripts (`scripts/req/`) and schemas.
-2. Creates a `req.config.json` (settings file).
-3. Adds the `req:*` commands and required devDependencies (`tsx`, `ajv`, `cross-spawn`) to your `package.json`.
-4. Creates an `AGENTS.md` template (the rules file the Reviewer reads) if you don't have one.
+| 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 |
-After installing, fetch the newly added dependencies:
+Preview without writing files:
 ```sh
-npm install
+npx commitgate --dry-run
 ```
-> Add `--dry-run` to preview what it would do **without changing anything**: `npx commitgate --dry-run`
 ---
-## 🤖 How to use it — hand it to an AI agent via a prompt (recommended)
-Honestly, **nobody types `req:new → review → implement → review → commit` by hand, one at a time.** It's tedious.
-The real way to use CommitGate is this: **give your AI coding agent a prompt with your "requirements" plus "use this workflow," and the agent drives the whole thing.** You only approve at **control points (commit, merge, push, etc.).**
-### What this mode assumes
-- **An AI coding agent that can run shell commands** — Claude Code, Cursor (agent), Codex CLI, etc. (it must be able to run terminal commands in your repo)
-- **Codex CLI installed** — the Reviewer role. Without it, the review step stops (fail-closed).
-- **A filled-in `AGENTS.md`** — write your project's rules (coding conventions, test commands, etc.) into the template that `npx commitgate` created; it improves review quality.
-### Three steps and you're done
-1. Copy the **prompt template** below and fill the `[Requirements]` block at the bottom with your request.
-2. Paste the whole thing **into your AI agent's chat.**
-3. The agent's **first reply reports only the REQ number, branch, phase plan, and control points.** After that it asks you **only at control points** — everything else (implementation, tests, Codex review, applying NEEDS_FIX, re-review) is automatic.
-### 📋 Copy-paste prompt template
+## Prerequisites
-````text
-Do NOT handle this as a normal implementation task. You MUST use the CommitGate (AI REQ workflow) installed in this project.
-Issue a new REQ ticket for the [Requirements] below and drive it all the way through:
-  req:new → write design docs (00/01/02) → req:review-codex (design review)
-  → implement phase + tests → req:doctor (gate) → req:review-codex (phase review) → req:commit
-[Do automatically]
-- Within the approved phase scope, do implementation, tests, keeping codex-request consistent, applying NEEDS_FIX, and re-review (resume) automatically. Do not ask me every time.
-- If Codex returns NEEDS_FIX, apply the feedback and re-run the review until approved (max 3 rounds per phase).
-- Only what is `git add`ed is reviewed. NEVER `git add` state.json or responses/ (the tool manages those).
-[Control points — stop and ask me ONLY here]
-- Right before `req:commit --run` (the actual commit / HIGH impact)
-- Right before merging to main or `git push`
-- Destructive operations such as reset, clean, force push
-- When a design-scope change or a feature not in [Requirements] is needed
-- When Codex review exceeds 3 rounds without approval, or the judgment is unclear
-- When a prerequisite is missing (not a git repo, no Codex CLI / Node / package manager) and you must fail-closed
-[First reply] Report only the REQ number, branch, phase plan, and control points. After that, stop only at control points.
-[Requirements]
-- What: (e.g.) Add a user-profile edit API
-- Why:  (e.g.) Only the name is editable today — email and bio should be editable too
-- Constraints: (e.g.) Reuse the existing auth middleware, validate email format, no new external libraries
-- Done when: (e.g.) PATCH /profile works + unit tests pass + existing tests unbroken
-````
-> The `[Requirements]` example above is **just a sample.** Just replace the 4 lines (What / Why / Constraints / Done when) with your own. If the request is large, it's split into multiple phases, each going through its own review and gate.
+| 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 |
-### Example of the agent's first reply
+If Codex CLI is not installed:
-```
-Issued REQ-2026-002 · branch feat/req-2026-002-profile-edit-api
-Phase plan:
-  - phase-1: PATCH /profile handler + validation
-  - phase-2: unit tests + regression
-Control points: proceed per phase after design approval / confirm before req:commit --run / push needs separate approval
-→ Starting with the design docs. Once the design review passes, I'll move to implementation.
+```sh
+npm install -g @openai/codex
+codex login
+codex login status
 ```
-Now you just **wait** until a control-point notification arrives. When it asks "commit as-is?" right before committing, you confirm.
+On Windows, if `codex` is not found right after installation, open a new terminal so PATH is reloaded.
 ---
-## 🔧 Appendix: what the workflow actually runs under the hood (manual steps)
+## Manual Commands
-> With the prompt approach above, you **don't need to type the commands below** — the agent runs them for you.
-> These are the actual commands the workflow runs internally. Refer to them only when you need to **understand the behavior, debug, or run steps manually.**
-Let's walk the whole flow with one small feature as an example. (Commands use `npm`; arguments after `npm run` go after `--`. With `pnpm` you can drop the `--`, e.g. `pnpm req:new my-feature --run`.)
-### Step 1 — create a work ticket
+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
-```
-- A new branch (`feat/req-...`) is created, and three design docs appear under `workflow/REQ-2026-001/`.
-- The output shows a **ticket number** (e.g. `REQ-2026-001`). Later commands use just the number → `2026-001`
-### Step 2 — write the design docs
-Fill in the three files under `workflow/REQ-2026-001/`:
-- `00-requirement.md` — **what** to build and why
-- `01-design.md` — **how** to build it
-- `02-plan.md` — in what **order/phases** to proceed
-### Step 3 — get a design review (Codex)
-Stage your design (i.e. `git add`):
-```sh
+# 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
-npm run req:review-codex -- 2026-001 --kind design --run
-```
-- Codex reads the design and returns **approval** or **NEEDS_FIX**.
-- If NEEDS_FIX, apply the feedback, then **`git add` again → re-run the command.** Repeat until approved.
-### Step 4 — implement code + tests
-Once the design is approved, write the actual code and tests.
-### Step 5 — gate check
+# 3. Design review
+npm run req:review-codex -- 2026-001 --kind design --run
-Stage your changes and preview the gate status:
+# 4. Implement code, then stage source files
+git add <changed-source-files>
-```sh
-git add <files-you-changed>
+# 5. Gate check
 npm run req:doctor -- 2026-001
-```
-- It checks several things (is the design approval valid, does the staged code match the approved code, is the working tree clean, etc.) and shows **PASS/FAIL.**
-> ⚠️ **Important:** `git add` **only your own code/docs.** Do **not** stage workflow-internal files like `state.json` or `responses/` (the tool manages them; staging them by mistake gets blocked at the commit step).
-### Step 6 — get a code review (Codex)
-```sh
+# 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"
 ```
-- Codex reviews the **implementation code.** Again, apply feedback → re-run until approved.
-- Once approved, `commit_allowed=true` and the commit opens.
+Important: only stage code and documents you authored for the source commit. `state.json` and `responses/` are managed by the tool.
-### Step 7 — commit
+For multi-line commit messages, use a file instead of `-m`.
 ```sh
-npm run req:commit -- 2026-001 --run -m "feat: implement my-feature"
+npm run req:commit -- 2026-001 --run --message-file commit-message.txt
 ```
-- After passing the gate (doctor) one final time, it makes a **code commit + an evidence commit.**
-- If it isn't approved, or the code changed after approval, it **stops here.** (That's the heart of CommitGate.)
-🎉 Done! Your code is now committed safely with review, approval, and evidence all recorded.
 ---
-## 📋 Command cheat sheet
+## Command Cheat Sheet
-| Command | What it does |
+| Command | Purpose |
 |---|---|
-| `npx commitgate` | Install (scaffold) CommitGate into your project |
-| `req:new <name> --run` | Create a new ticket + branch + design docs |
-| `req:review-codex <num> --kind design --run` | **Design** review (Codex) |
-| `req:review-codex <num> --kind phase --run` | **Implementation** review (Codex) |
-| `req:doctor <num>` | Gate check (shows pass/fail) |
-| `req:commit <num> --run -m "message"` | Commit approved code (+ evidence) |
-> Instead of `-m "message"`, multi-line messages can be read from a file with `--message-file message.txt`.
+| `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 (`req.config.json`, optional)
+## Configuration
-You can tweak behavior via `req.config.json` at the project root. **Without the file it works on sensible defaults**, so you can ignore it at first.
+Defaults are enough for most projects. If needed, edit `req.config.json` in the project root.
 | Key | Default | Meaning |
 |---|---|---|
-| `branchPrefix` | `"feat/req-"` | Prefix for newly created branch names |
-| `ticketRoot` | `"workflow"` | Where ticket folders live |
-| `packageManager` | auto-detected | `npm` / `pnpm` / `yarn` |
-| `designDocs` | `00-/01-/02-*.md` | Filenames of the three design docs |
+| `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 |
-Invalid values (e.g. an empty `branchPrefix`, a path that escapes the folder) are **rejected safely.**
+Empty `branchPrefix` values and paths that escape the project root are rejected.
 ---
-## ❓ FAQ / troubleshooting
+## FAQ
-**Q. It says the `codex` command is not found.**
-A. The Reviewer (Codex CLI) must be installed for reviews to run. Before it's installed, review commands don't "silently pass" — they **fail clearly** (that's the intended fail-closed behavior).
+**What happens if Codex CLI is missing?**
+The review command fails. It is not treated as approval.
-**Q. I get an error like "staged tree != approved" at the commit step.**
-A. It means **the approved code and the code you currently staged (`git add`) differ.** If you changed code after approval, redo Step 6 (implementation review) to re-approve. (This safeguard prevents approval swapping.)
+**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.
-**Q. I get a "non-code staged not allowed (state/responses)" error.**
-A. You `git add`ed `state.json` or `responses/`. **Don't stage those** (the tool manages them); stage only your own code/docs.
+**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.
-**Q. Does running `npx commitgate` twice overwrite things?**
-A. No. **Existing files are skipped** (idempotent). To force overwrite, add `--force`.
-**Q. On Windows my commit message newlines look wrong.**
-A. For multi-line messages, use `--message-file file.txt` instead of `-m`.
+**Does running install twice overwrite files?**
+No. Existing files are skipped. Use `--force` if you intentionally want to refresh them.
 ---
-## 🔒 How is "safety" guaranteed? (fail-closed)
+## Current Scope
-CommitGate's principle is **"pass only when definitely approved; block on the slightest doubt."**
+The current release is **Stage A: vendored scaffold model**. `npx commitgate` copies workflow files into the target project.
-- Design docs missing or malformed → treated as not approved
-- Codex not installed / review failed → not a pass, fails clearly
-- The approved code fingerprint differs from the current code → commit rejected
-- The working tree is dirty (unreviewed changes mixed in) → review/commit rejected
+Future scope:
-In other words, **blocking is the default and passing is the exception**, minimizing the chance of unverified code slipping through.
+- 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
+## License
 [MIT](./LICENSE) © 2026 sol5288
-> This workflow was extracted as a standalone package from the REQ-2026-017 portability kit of `palm-kiosk-app`, and was validated by **reviewing and approving itself through this very workflow (dogfood).**

package/README.md CHANGED Viewed

@@ -1,341 +1,217 @@
-# CommitGate 🚦
+# CommitGate
 🌐 **한국어** · [English](./README.en.md)
-**AI가 짠 코드를, 다른 AI가 리뷰하고 승인해야만 커밋되게 하는 "커밋 관문(gate)".**
+**AI 코딩 변경을 Codex 리뷰 승인 없이는 커밋하지 못하게 막는 커밋 게이트입니다.**
-> 한 줄 요약: **만드는 AI(Builder)** 와 **검사하는 AI(Reviewer)** 를 짝지어, **리뷰·승인·증거 없이는 커밋이 통과하지 못하게** 막아줍니다.
+AI 에이전트가 코드를 빠르게 만들더라도, 리뷰 없이 바로 커밋되면 위험합니다. CommitGate는 변경을 티켓 단위로 묶고, Codex가 승인한 staged tree만 커밋되게 합니다. 승인 후 코드가 바뀌거나 증거가 부족하면 기본적으로 막습니다.
 [![license](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
 ---
-## 🤔 이게 뭔가요? (비유로)
+## Quick Start
-공항 보안 검색대를 떠올려 보세요. 아무리 급해도 **검색대를 통과하지 않으면** 탑승구로 갈 수 없죠.
+아래는 가장 짧은 사용 경로입니다. 프로젝트 루트는 **git 저장소이고 `package.json`이 있는 폴더**여야 합니다.
-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
+```sh
+npx commitgate
+npm install
+codex --version
+codex login status
 ```
-각 단계에서 **통과하지 못하면 다음으로 못 넘어갑니다.**
----
-## 📦 준비물 (Prerequisites)
+그다음 AI 코딩 에이전트에게 아래 프롬프트를 붙여넣습니다.
-시작 전에 아래 4가지가 필요합니다. 터미널에서 하나씩 확인해 보세요.
+```text
+이 요청은 일반 구현으로 처리하지 말고, 이 프로젝트에 설치된 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`) |
-> 💡 **Reviewer = Codex CLI** 입니다. 리뷰를 실제로 돌리려면 Codex CLI가 설치되어 있어야 해요. 없으면 리뷰 명령이 "안전하게 실패(fail-closed)"합니다 — 조용히 통과되는 일은 없습니다.
-### 🔧 Codex CLI 설치 & 로그인 (Reviewer 준비)
+새 REQ 티켓을 만들고 다음 흐름을 끝까지 진행해라:
+req:new → 설계문서 작성 → Codex design 리뷰 → 구현·테스트 → req:doctor → Codex phase 리뷰 → req:commit
-CommitGate의 리뷰는 **OpenAI Codex CLI**가 담당합니다. 아래 3단계면 끝납니다.
+자동으로 진행할 것:
+- NEEDS_FIX가 나오면 수정하고 재리뷰해 승인까지 반복한다.
+- 리뷰 대상은 git add 한 파일만이다.
+- `state.json`과 `responses/`는 직접 `git add`하지 않는다.
-**① 설치**
+멈춰서 확인받을 때:
+- req:commit --run 직전
+- main 병합 또는 push 직전
+- reset, clean, force push 같은 destructive 작업 전
+- 요구사항 범위를 바꿔야 할 때
+- Codex 리뷰가 3라운드를 넘어도 승인되지 않을 때
-```sh
-# npm (모든 OS)
-npm install -g @openai/codex
-# 또는 macOS Homebrew
-brew install codex
+요구사항:
+- 무엇을:
+- 왜:
+- 제약:
+- 완료 기준:
 ```
-설치 확인:
+첫 응답은 보통 이렇게 나와야 합니다.
-```sh
-codex --version      # 예: codex-cli 0.4x.x
+```text
+REQ-2026-002 발행
+브랜치: feat/req-2026-002-profile-edit-api
+phase:
+- phase-1: PATCH /profile 구현
+- phase-2: 테스트와 회귀 확인
+통제점: req:commit --run 직전, push 직전
 ```
-**② 로그인** — 둘 중 편한 방법 하나
-- **방법 A. ChatGPT 계정으로 (권장, 브라우저)**
-  ```sh
-  codex login
-  ```
-  브라우저가 열리면 ChatGPT 계정으로 로그인 → 터미널로 돌아오면 완료.
+이후에는 에이전트가 설계, 구현, 테스트, Codex 리뷰를 진행합니다. 사용자는 커밋이나 push 같은 통제점에서만 확인하면 됩니다.
-- **방법 B. OpenAI API 키로**
-  ```sh
-  # 환경변수로 (가장 간단)
-  export OPENAI_API_KEY=sk-...        # Windows PowerShell: $env:OPENAI_API_KEY="sk-..."
+---
-  # 또는 키를 Codex에 저장
-  printenv OPENAI_API_KEY | codex login --with-api-key
-  ```
-  API 키는 [platform.openai.com](https://platform.openai.com/api-keys) 에서 발급합니다.
+## 무엇을 보장하나요?
-**③ 로그인 확인**
+CommitGate가 막는 것은 단순한 명령 실수가 아니라 **리뷰받지 않은 변경이 커밋되는 상황**입니다.
-```sh
-codex login status     # 로그인 상태 표시
-codex doctor           # 설치·인증·환경 종합 진단(문제 있으면 원인 안내)
-```
+- Codex 리뷰가 실패하거나 없으면 커밋할 수 없습니다.
+- 승인된 staged tree와 지금 커밋하려는 staged tree가 다르면 막습니다.
+- `state.json`, `responses/` 같은 워크플로 내부 파일을 source 커밋에 섞으면 막습니다.
+- Codex CLI가 없거나 실행에 실패하면 조용히 통과하지 않고 실패합니다.
+- 승인 응답과 증거 파일은 `workflow/REQ-.../responses/`에 남습니다.
-> ✅ `codex --version` 과 `codex login status` 가 정상이면 리뷰 준비 끝. 이제 `npx commitgate` 로 넘어가세요.
-> ⚠️ Windows에서 `codex` 명령을 못 찾으면 **새 터미널**을 열어 PATH를 새로 읽게 하세요(전역 설치 직후 흔한 문제).
+한 줄로 말하면, **확실히 승인된 변경만 통과하고 애매하면 멈추는 방식**입니다.
 ---
-## 🚀 설치 (딱 한 줄)
-**당신의 프로젝트 폴더**(= git 저장소, `package.json` 있는 곳)에서:
+## 설치가 하는 일
-```sh
-npx commitgate
-```
+`npx commitgate`는 대상 프로젝트에 아래 파일과 설정을 추가합니다. 기존 파일은 기본적으로 덮어쓰지 않습니다.
-이 명령이 자동으로 해주는 일 (기존 파일은 **덮어쓰지 않아요**):
-1. 워크플로 스크립트(`scripts/req/`)와 스키마를 복사합니다.
-2. `req.config.json`(설정 파일)을 만들어 둡니다.
-3. `package.json`에 `req:*` 명령들과 필요한 devDependencies(`tsx`, `ajv`, `cross-spawn`)를 추가합니다.
-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`
 ---
-## 🤖 사용법 — AI 에이전트에게 프롬프트로 맡기기 (권장)
-솔직히, `req:new → 리뷰 → 구현 → 리뷰 → 커밋`을 **손으로 하나씩 치는 사람은 없습니다.** 피곤하니까요.
-CommitGate의 진짜 사용법은 이겁니다: **당신의 AI 코딩 에이전트에게 "요구사항"과 "이 워크플로를 쓰라"는 프롬프트를 던지면, 에이전트가 알아서 전 과정을 굴립니다.** 당신은 **통제점(커밋·머지·푸시 등)에서만** 승인하면 됩니다.
-### 이 방식의 전제
-- **셸 명령을 실행할 수 있는 AI 코딩 에이전트** — Claude Code, Cursor(agent), Codex CLI 등. (당신의 저장소에서 터미널 명령을 직접 돌릴 수 있어야 함)
-- **Codex CLI 설치** — 리뷰어(Reviewer) 역할. 없으면 리뷰 단계가 fail-closed로 멈춥니다.
-- **`AGENTS.md` 채우기** — `npx commitgate`가 만든 템플릿에 당신 프로젝트의 규칙(코딩 컨벤션·테스트 명령 등)을 적어두면 리뷰 품질이 올라갑니다.
-### 3단계면 끝
-1. 아래 **프롬프트 템플릿**을 복사하고, 맨 아래 `[요구사항]` 칸을 당신 요구로 채웁니다.
-2. 전체를 **AI 에이전트 대화창에 그대로 붙여넣습니다.**
-3. 에이전트가 **첫 응답으로 REQ 번호·브랜치·phase 계획·통제점**만 보고합니다. 이후엔 **통제점에서만** 당신에게 확인을 받습니다 — 나머지(구현·테스트·Codex 리뷰·NEEDS_FIX 반영·재리뷰)는 자동입니다.
-### 📋 복사해서 쓰는 프롬프트 템플릿
+## 준비물
-````text
-이 요청은 일반 구현으로 처리하지 말고, 반드시 이 프로젝트에 설치된 CommitGate(AI REQ workflow)를 사용해라.
-아래 [요구사항]으로 새 REQ 티켓을 발행하고 다음 흐름을 끝까지 태워라:
-  req:new → 설계문서(00/01/02) 작성 → req:review-codex(design 리뷰)
-  → phase 구현·테스트 → req:doctor(게이트) → req:review-codex(phase 리뷰) → req:commit
-[자동으로 진행할 것]
-- 승인된 phase 범위 안에서 구현·테스트·codex-request 정합·NEEDS_FIX 반영·재리뷰(resume)는 자동으로 진행해라. 매번 확인받지 마라.
-- Codex가 NEEDS_FIX를 주면 지적을 반영하고 재리뷰를 돌려 승인까지 반복해라(phase당 최대 3라운드).
-- 리뷰 대상은 git add 한 것만이다. state.json·responses/ 는 절대 git add 하지 마라(도구가 관리한다).
-[멈춰서 사람 확인을 받을 통제점 — 여기서만 멈춰라]
-- req:commit --run 직전 (실제 커밋 / HIGH 영향)
-- main 병합 또는 git push 직전
-- reset·clean·force push 등 destructive 작업
-- 설계 범위 변경 또는 [요구사항]에 없는 기능 추가가 필요할 때
-- Codex 리뷰가 3라운드를 넘겨도 승인 안 되거나 판단이 불명확할 때
-- git 저장소가 아니거나 Codex CLI·Node·패키지매니저 전제가 없어 fail-closed 해야 할 때
-[첫 응답] REQ 번호, 브랜치, phase 계획, 통제점만 간단히 보고해라. 그 뒤부터는 통제점에서만 멈춰라.
-[요구사항]
-- 무엇을: (예) 사용자 프로필 편집 API 추가
-- 왜:     (예) 지금은 이름만 수정 가능 — 이메일·소개도 편집 필요
-- 제약:   (예) 기존 인증 미들웨어 재사용, 이메일 형식 검증, 외부 라이브러리 추가 금지
-- 완료 기준: (예) PATCH /profile 동작 + 단위 테스트 통과 + 기존 테스트 무손상
-````
-> 위 `[요구사항]` 예시는 **샘플일 뿐**입니다. 4줄(무엇을/왜/제약/완료 기준)을 당신 요구로 바꾸기만 하면 됩니다. 요구가 크면 phase가 여러 개로 쪼개지고, 각 phase마다 리뷰·게이트를 거칩니다.
+| 필요 | 확인 명령 | 비고 |
+|---|---|---|
+| Git | `git --version` | 필수 |
+| Node.js 18.17+ | `node --version` | 필수 |
+| npm, pnpm, yarn 중 하나 | `npm --version` | npm 기준으로 안내 |
+| Codex CLI | `codex --version` | 리뷰 실행에 필요 |
-### 에이전트가 보고하는 첫 응답 예시
+Codex CLI가 없다면:
-```
-REQ-2026-002 발행 · 브랜치 feat/req-2026-002-profile-edit-api
-phase 계획:
-  - phase-1: PATCH /profile 핸들러 + 유효성 검증
-  - phase-2: 단위 테스트 + 회귀
-통제점: design 승인 후 phase별 진행 / req:commit --run 직전 확인 / push는 별도 승인
-→ 설계문서 작성부터 진행합니다. design 리뷰 통과하면 구현으로 넘어갑니다.
+```sh
+npm install -g @openai/codex
+codex login
+codex login status
 ```
-이제 당신은 통제점 알림이 올 때까지 **기다리기만** 하면 됩니다. 커밋 직전에 "이대로 커밋할까요?" 물으면 확인해 주면 되고요.
+Windows에서 설치 직후 `codex` 명령을 못 찾으면 새 터미널을 열어 PATH를 다시 읽게 하세요.
 ---
-## 🔧 부록: 워크플로가 내부에서 실제로 하는 일 (수동 단계)
+## 수동 명령
-> 위 프롬프트 방식이면 아래 명령을 **직접 칠 필요가 없습니다** — 에이전트가 알아서 실행합니다.
-> 아래는 워크플로가 내부에서 돌리는 실제 명령들입니다. **동작 이해·디버깅·수동 실행**이 필요할 때만 참고하세요.
-작은 기능 하나를 예로, 전체 흐름을 그대로 밟아 봅니다. (명령은 `npm` 기준이며, `npm run` 뒤 인자는 `--` 다음에 씁니다. `pnpm`을 쓰면 `pnpm req:new my-feature --run` 처럼 `--` 없이 됩니다.)
-### 1단계 — 작업 티켓 만들기
+대부분의 사용자는 위 프롬프트 방식으로 충분합니다. 아래는 내부에서 어떤 명령이 실행되는지 이해하거나 직접 디버깅할 때만 보면 됩니다.
 ```sh
+# 1. 티켓과 브랜치 생성
 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
+# 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
-npm run req:review-codex -- 2026-001 --kind design --run
-```
-- Codex가 설계를 읽고 **승인** 또는 **보완 요청(NEEDS_FIX)** 을 돌려줍니다.
-- 보완 요청이면 지적사항을 반영하고 **다시 `git add` → 위 명령을 재실행**하세요. 승인될 때까지 반복합니다.
-### 4단계 — 코드 구현 + 테스트
-설계가 승인되면 실제 코드를 짜고 테스트를 작성합니다.
-### 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/bin/init.ts CHANGED Viewed

@@ -25,6 +25,7 @@ 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 * as semver from 'semver'
 /** 이 패키지 루트(bin/ 기준 1단계 위). 복사 원본. */
 const PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..')
@@ -37,10 +38,13 @@ const REQ_SCRIPTS: Record<string, string> = {
   'req:commit': 'tsx scripts/req/req-commit.ts',
 }
+/** cross-spawn 주입 spec(= 보안 하한 SSOT). 진단(#1)과 주입이 이 값을 공유. */
+const CROSS_SPAWN_SPEC = '^7.0.6'
 /** 대상 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',
+  'cross-spawn': CROSS_SPAWN_SPEC,
   tsx: '^4.19.1',
 }
@@ -48,6 +52,7 @@ export interface InitOptions {
   dir: string
   force: boolean
   dryRun: boolean
+  strict: boolean // cross-spawn 하한 미만이면 WARN 대신 throw(#1)
 }
 export interface InitResult {
@@ -59,6 +64,7 @@ export interface InitResult {
   packageJsonAdded: string[] // 추가된 script/devDep 키
   agentsCreated: boolean
   packageManager: PackageManager
+  crossSpawnFloorWarned: boolean // 기존 cross-spawn이 보안 하한 미만이라 경고(#1)
   dryRun: boolean
 }
@@ -142,6 +148,92 @@ function parseJsonObject(path: string, label: string): Record<string, unknown> {
   return parsed as Record<string, unknown>
 }
+// ─────────────────────────────── cross-spawn 버전 하한 진단 (#1) ──
+/** 보안 하한 = 주입 spec의 최소버전(SSOT — 하드코딩 이중화 금지). '^7.0.6' → 7.0.6. */
+const CROSS_SPAWN_FLOOR = semver.minVersion(CROSS_SPAWN_SPEC)
+/** obj가 plain object일 때 obj[key](문자열). 아니면 undefined. */
+function stringField(obj: unknown, key: string): string | undefined {
+  if (obj && typeof obj === 'object' && !Array.isArray(obj)) {
+    const v = (obj as Record<string, unknown>)[key]
+    if (typeof v === 'string') return v
+  }
+  return undefined
+}
+/** 대상의 기존 cross-spawn spec(devDeps 우선, 없으면 deps). 없으면 null. */
+function existingCrossSpawnSpec(pkg: Record<string, unknown>): string | null {
+  return stringField(pkg.devDependencies, 'cross-spawn') ?? stringField(pkg.dependencies, 'cross-spawn') ?? null
+}
+/** node_modules에 실제 설치된 cross-spawn 버전(valid semver). 없으면 null. */
+function installedCrossSpawnVersion(targetRoot: string): string | null {
+  const p = join(targetRoot, 'node_modules', 'cross-spawn', 'package.json')
+  if (!existsSync(p)) return null
+  try {
+    const v = (JSON.parse(stripBom(readFileSync(p, 'utf8'))) as { version?: unknown }).version
+    return typeof v === 'string' && semver.valid(v) ? v : null
+  } catch {
+    return null
+  }
+}
+/** lockfile 해소 cross-spawn 버전(package-lock v2/v3 JSON 우선, pnpm/yarn best-effort). 없으면 null. */
+function lockedCrossSpawnVersion(targetRoot: string): string | null {
+  const pl = join(targetRoot, 'package-lock.json')
+  if (existsSync(pl)) {
+    try {
+      const j = JSON.parse(stripBom(readFileSync(pl, 'utf8'))) as {
+        packages?: Record<string, { version?: unknown }>
+        dependencies?: Record<string, { version?: unknown }>
+      }
+      const v = j.packages?.['node_modules/cross-spawn']?.version ?? j.dependencies?.['cross-spawn']?.version
+      if (typeof v === 'string' && semver.valid(v)) return v
+    } catch {
+      /* best-effort */
+    }
+  }
+  for (const [file, re] of [
+    ['pnpm-lock.yaml', /cross-spawn@(\d+\.\d+\.\d+)/],
+    ['yarn.lock', /(?:^|\n)"?cross-spawn@[^\n]*:[\s\S]*?\n\s+version:?\s+"?(\d+\.\d+\.\d+)"?/],
+  ] as const) {
+    const fp = join(targetRoot, file)
+    if (!existsSync(fp)) continue
+    try {
+      const m = readFileSync(fp, 'utf8').match(re)
+      if (m?.[1] && semver.valid(m[1])) return m[1]
+    } catch {
+      /* best-effort */
+    }
+  }
+  return null
+}
+/**
+ * 기존 cross-spawn이 보안 하한 미만인지 판정(#1). 우선순위: **설치버전 → lockfile 해소버전 → range**.
+ * range fallback은 `>=floor`로 절대 해소 불가한 spec만 below로 본다(‘^7.0.0’·‘~7.0.1’ 오탐 방지 — R1 P2).
+ * 기존 cross-spawn 없으면 null(우리가 `^7.0.6` 주입 → 진단 불필요).
+ */
+export function crossSpawnBelowFloor(
+  targetRoot: string,
+  pkg: Record<string, unknown>,
+): { below: boolean; detail: string } | null {
+  if (!CROSS_SPAWN_FLOOR) return null // 이론상 도달 불가(REQ_DEV_DEPS 고정값)
+  const floor = CROSS_SPAWN_FLOOR.version
+  const spec = existingCrossSpawnSpec(pkg)
+  if (!spec) return null
+  const installed = installedCrossSpawnVersion(targetRoot)
+  if (installed) return { below: semver.lt(installed, floor), detail: `설치버전 ${installed}` }
+  const locked = lockedCrossSpawnVersion(targetRoot)
+  if (locked) return { below: semver.lt(locked, floor), detail: `lockfile ${locked}` }
+  if (semver.validRange(spec)) return { below: !semver.intersects(spec, `>=${floor}`), detail: `범위 ${spec}` }
+  return { below: false, detail: `범위 ${spec}(파싱 불가 — 무경고)` }
+}
 /**
  * 설치 코어. IO는 여기서만(테스트가 임시 repo로 직접 호출).
  * **Preflight(전 검증·파싱) → Apply(쓰기) 2단계** — malformed 입력에 대해 어떤 파일도 복사·수정하기 전에 실패한다(부분 설치 방지, design R2 P2).
@@ -161,11 +253,23 @@ export function runInit(opts: InitOptions): InitResult {
     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) {
+  // scripts·devDependencies·dependencies가 존재하면 반드시 plain object — 배열/원시면 patch 유실(scripts/devDeps, phase R1 P2)
+  // 또는 cross-spawn 진단(dependencies, design R1 P3) 오동작. 읽기 전에 shape 검증(fail-closed).
+  for (const field of ['scripts', 'devDependencies', 'dependencies'] 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:* 주입 불가(배열/원시 미지원).`)
+      throw new Error(`package.json의 ${field} 필드가 객체가 아님(${pkgPath}) — 배열/원시 미지원.`)
+  }
+  // cross-spawn 보안 하한 진단(#1): 기존 cross-spawn이 하한 미만이면 WARN(기본)/throw(--strict). preflight라 strict throw 시 부분 설치 없음.
+  let crossSpawnFloorWarned = false
+  const floorCheck = crossSpawnBelowFloor(targetRoot, pkg as Record<string, unknown>)
+  if (floorCheck?.below) {
+    const spec = CROSS_SPAWN_SPEC
+    const msg = `기존 cross-spawn(${floorCheck.detail})이 보안 하한 >=${CROSS_SPAWN_FLOOR?.version} 미만 — CommitGate 안전 경계(safeSpawnSync)는 ${spec} 검증분입니다. 'npm i -D cross-spawn@${spec}' 권장.`
+    if (opts.strict) throw new Error(`[--strict] ${msg}`)
+    console.warn(`⚠️  ${msg} (설치는 계속 — 강제 중단하려면 --strict)`)
+    crossSpawnFloorWarned = true
   }
   const cfgPath = join(targetRoot, 'req.config.json')
@@ -247,6 +351,7 @@ export function runInit(opts: InitOptions): InitResult {
     packageJsonAdded,
     agentsCreated,
     packageManager,
+    crossSpawnFloorWarned,
     dryRun: opts.dryRun,
   }
 }
@@ -255,6 +360,7 @@ export function parseArgs(argv: string[]): InitOptions {
   let dir = process.cwd()
   let force = false
   let dryRun = false
+  let strict = false
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i]
     if (a === '--dir') {
@@ -266,6 +372,8 @@ export function parseArgs(argv: string[]): InitOptions {
       force = true
     } else if (a === '--dry-run') {
       dryRun = true
+    } else if (a === '--strict') {
+      strict = true
     } else if (a === '-h' || a === '--help') {
       printHelp()
       process.exit(0)
@@ -273,7 +381,7 @@ export function parseArgs(argv: string[]): InitOptions {
       throw new Error(`알 수 없는 인자: ${a}`)
     }
   }
-  return { dir: resolve(dir), force, dryRun }
+  return { dir: resolve(dir), force, dryRun, strict }
 }
 function printHelp(): void {
@@ -286,6 +394,7 @@ function printHelp(): void {
   --dir <path>   대상 repo 루트(기본: 현재 디렉터리)
   --force        기존 kit 파일 덮어쓰기(기본: 스킵)
   --dry-run      변경 없이 수행 예정 목록만 출력
+  --strict       기존 cross-spawn이 보안 하한(>=7.0.6) 미만이면 경고 대신 중단(fail-closed)
   -h, --help     도움말
 설치 후:
@@ -315,6 +424,7 @@ export function main(argv: string[]): void {
     `${tag}  package.json: ${r.packageJsonAdded.length > 0 ? '추가 ' + r.packageJsonAdded.join(', ') : '변경 없음'}`,
   )
   console.log(`${tag}  AGENTS.md: ${r.agentsCreated ? '템플릿 생성' : '이미 존재(유지)'}`)
+  if (r.crossSpawnFloorWarned) console.log(`${tag}  ⚠️ cross-spawn 버전 하한 경고(위 참조) — 강제 중단은 --strict`)
   if (!r.dryRun) {
     console.log(`\n다음:`)
     console.log(`  1. cd ${r.targetRoot} && ${r.packageManager} install`)

package/package.json CHANGED Viewed

@@ -1,63 +1,66 @@
-{
-  "name": "commitgate",
-  "version": "0.1.1",
-  "description": "CommitGate — Builder↔Reviewer(Claude↔Codex) fail-closed 커밋 게이트: 리뷰·승인·증거 없인 커밋을 통과시키지 않는 AI REQ 워크플로 kit (req:new/review-codex/doctor/commit)",
-  "type": "module",
-  "license": "MIT",
-  "author": "sol5288",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/sol5288/commitgate.git"
-  },
-  "homepage": "https://github.com/sol5288/commitgate#readme",
-  "bugs": {
-    "url": "https://github.com/sol5288/commitgate/issues"
-  },
-  "keywords": [
-    "ai",
-    "code-review",
-    "workflow",
-    "codex",
-    "claude",
-    "git",
-    "commit-gate",
-    "fail-closed",
-    "review-gate",
-    "cli"
-  ],
-  "bin": {
-    "commitgate": "bin/commitgate.mjs"
-  },
-  "scripts": {
-    "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",
-    "test": "vitest run",
-    "typecheck": "tsc --noEmit"
-  },
-  "files": [
-    "scripts",
-    "workflow/machine.schema.json",
-    "workflow/req.config.schema.json",
-    "bin",
-    "AGENTS.template.md",
-    "req.config.json.sample",
-    "README.md",
-    "README.en.md"
-  ],
-  "engines": {
-    "node": ">=18.17"
-  },
-  "dependencies": {
-    "ajv": "^8.20.0",
-    "cross-spawn": "^7.0.6",
-    "tsx": "^4.19.1"
-  },
-  "devDependencies": {
-    "@types/cross-spawn": "^6.0.6",
-    "@types/node": "^22.7.4",
-    "typescript": "^5.6.2",
-    "vitest": "^2.1.2"
-  }
-}
+{
+  "name": "commitgate",
+  "version": "0.2.0",
+  "description": "CommitGate — Builder↔Reviewer(Claude↔Codex) fail-closed 커밋 게이트: 리뷰·승인·증거 없인 커밋을 통과시키지 않는 AI REQ 워크플로 kit (req:new/review-codex/doctor/commit)",
+  "type": "module",
+  "license": "MIT",
+  "author": "sol5288",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sol5288/commitgate.git"
+  },
+  "homepage": "https://github.com/sol5288/commitgate#readme",
+  "bugs": {
+    "url": "https://github.com/sol5288/commitgate/issues"
+  },
+  "keywords": [
+    "ai",
+    "code-review",
+    "workflow",
+    "codex",
+    "claude",
+    "git",
+    "commit-gate",
+    "fail-closed",
+    "review-gate",
+    "cli"
+  ],
+  "bin": {
+    "commitgate": "bin/commitgate.mjs"
+  },
+  "scripts": {
+    "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",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "smoke": "node scripts/smoke.mjs"
+  },
+  "files": [
+    "scripts/req",
+    "workflow/machine.schema.json",
+    "workflow/req.config.schema.json",
+    "bin",
+    "AGENTS.template.md",
+    "req.config.json.sample",
+    "README.md",
+    "README.en.md"
+  ],
+  "engines": {
+    "node": ">=18.17"
+  },
+  "dependencies": {
+    "ajv": "^8.20.0",
+    "cross-spawn": "^7.0.6",
+    "semver": "^7.6.3",
+    "tsx": "^4.19.1"
+  },
+  "devDependencies": {
+    "@types/cross-spawn": "^6.0.6",
+    "@types/node": "^22.7.4",
+    "@types/semver": "^7.5.8",
+    "typescript": "^5.6.2",
+    "vitest": "^2.1.2"
+  }
+}