commitgate 0.2.0 → 0.2.2
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.
- package/AGENTS.template.md +51 -48
- package/README.en.md +246 -217
- package/README.md +246 -217
- package/bin/commitgate.mjs +2 -1
- package/bin/init.ts +40 -6
- package/package.json +1 -1
- package/scripts/req/lib/adapters.ts +35 -8
- package/scripts/req/review-codex.ts +243 -20
- package/workflow/machine.schema.json +19 -2
package/AGENTS.template.md
CHANGED
|
@@ -1,48 +1,51 @@
|
|
|
1
|
-
# AGENTS.md (AI REQ workflow — Codex/Builder 계약)
|
|
2
|
-
|
|
3
|
-
> 이 파일은 `commitgate`(init)가 대상 repo에 `AGENTS.md`가 없을 때 생성한 **템플릿**이다.
|
|
4
|
-
> 프로젝트 고유 규칙(SSOT 경로·포트·참조 프로젝트·phase 문서 등)은 여기에 직접 채워 넣어라.
|
|
5
|
-
> Codex CLI는 repo 루트의 `AGENTS.md`를 리뷰 컨텍스트로 읽는다.
|
|
6
|
-
|
|
7
|
-
## 역할
|
|
8
|
-
|
|
9
|
-
- **Builder(Claude 등)**: REQ 티켓 단위로 설계→구현→테스트. `req:new`로 티켓·브랜치 생성.
|
|
10
|
-
- **Reviewer(Codex)**: `req:review-codex`가 조립한 프롬프트로 design/phase 리뷰. 구조화 응답(`workflow/machine.schema.json`)만 승인 근거.
|
|
11
|
-
|
|
12
|
-
## 절대 규칙 (어기면 리뷰에서 reject)
|
|
13
|
-
|
|
14
|
-
### 1. Test-First
|
|
15
|
-
각 phase에서 게이트를 통과시키는 테스트를 먼저 작성(Red) → 최소 구현(Green) → 리팩토링. 테스트 없는 구현은 reject.
|
|
16
|
-
|
|
17
|
-
### 2. 게이트 통과 전 다음 phase 금지
|
|
18
|
-
`req:doctor` PASS + Codex phase 리뷰 승인(STEP_COMPLETE) 전에는 다음 phase로 진입하지 않는다.
|
|
19
|
-
|
|
20
|
-
### 3. 승인 바인딩(fail-closed) 우회 금지
|
|
21
|
-
- staged tree는 승인된 tree와 일치해야 한다(D9). 승인 후 재stage/설계 변경은 stale 승인으로 거부.
|
|
22
|
-
- 워킹트리는 리뷰 시점에 clean해야 한다(비-스크래치 unstaged/untracked → D10 FAIL).
|
|
23
|
-
- codex 미설치/실패는 silent 처리 금지 — 명확히 fail-closed.
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
-
|
|
36
|
-
-
|
|
37
|
-
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
|
45
|
-
|
|
46
|
-
| `req:
|
|
47
|
-
|
|
48
|
-
|
|
1
|
+
# AGENTS.md (AI REQ workflow — Codex/Builder 계약)
|
|
2
|
+
|
|
3
|
+
> 이 파일은 `commitgate`(init)가 대상 repo에 `AGENTS.md`가 없을 때 생성한 **템플릿**이다.
|
|
4
|
+
> 프로젝트 고유 규칙(SSOT 경로·포트·참조 프로젝트·phase 문서 등)은 여기에 직접 채워 넣어라.
|
|
5
|
+
> Codex CLI는 repo 루트의 `AGENTS.md`를 리뷰 컨텍스트로 읽는다.
|
|
6
|
+
|
|
7
|
+
## 역할
|
|
8
|
+
|
|
9
|
+
- **Builder(Claude 등)**: REQ 티켓 단위로 설계→구현→테스트. `req:new`로 티켓·브랜치 생성.
|
|
10
|
+
- **Reviewer(Codex)**: `req:review-codex`가 조립한 프롬프트로 design/phase 리뷰. 구조화 응답(`workflow/machine.schema.json`)만 승인 근거.
|
|
11
|
+
|
|
12
|
+
## 절대 규칙 (어기면 리뷰에서 reject)
|
|
13
|
+
|
|
14
|
+
### 1. Test-First
|
|
15
|
+
각 phase에서 게이트를 통과시키는 테스트를 먼저 작성(Red) → 최소 구현(Green) → 리팩토링. 테스트 없는 구현은 reject.
|
|
16
|
+
|
|
17
|
+
### 2. 게이트 통과 전 다음 phase 금지
|
|
18
|
+
`req:doctor` PASS + Codex phase 리뷰 승인(STEP_COMPLETE) 전에는 다음 phase로 진입하지 않는다.
|
|
19
|
+
|
|
20
|
+
### 3. 승인 바인딩(fail-closed) 우회 금지
|
|
21
|
+
- staged tree는 승인된 tree와 일치해야 한다(D9). 승인 후 재stage/설계 변경은 stale 승인으로 거부.
|
|
22
|
+
- 워킹트리는 리뷰 시점에 clean해야 한다(비-스크래치 unstaged/untracked → D10 FAIL).
|
|
23
|
+
- codex 미설치/실패는 silent 처리 금지 — 명확히 fail-closed.
|
|
24
|
+
- `req:review-codex` exit 0만 승인이다. exit 3(NEEDS_FIX)은 수정 후 재리뷰, exit 2(BLOCKED)는 같은 리뷰 재시도 금지. BLOCKED가 스레드 고착으로 의심되면 `--fresh-thread`로 1회만 회복 시도, 그래도 BLOCKED면 사람 보고.
|
|
25
|
+
- 승인(`commit_approved=yes`)은 `findings`가 0건일 때만이다. 지적이 하나라도 있으면 승인 불가(모순 → 거부). 비차단 코멘트를 `findings`에 섞지 말 것.
|
|
26
|
+
- 비차단(사소한/제안성) 코멘트는 optional `observations`(`{detail,file}`, **severity 없음**)에만 넣는다. `observations`는 승인/차단 판정에 영향 없고 승인 시에도 표출된다. `observations`만 있고 `findings`가 비어 있으면 승인 가능(단, `commit_approved=no`면 여전히 BLOCKED — observations는 findings를 대체하지 않음).
|
|
27
|
+
|
|
28
|
+
### 4. 커밋 정책
|
|
29
|
+
- 각 phase는 의미 있는 커밋. "WIP" 금지.
|
|
30
|
+
- 커밋 메시지 컨벤션: `test/feat/fix/refactor/docs/chore` 접두사. `[Codex]`/`[Claude]` 같은 메타 정보 금지(Reviewer 편향 방지).
|
|
31
|
+
- HIGH 영향 phase는 `req:commit --run` 직전 사용자 확인(`state.user_commit_confirmed`).
|
|
32
|
+
|
|
33
|
+
## 사람에게 보고해야 할 때
|
|
34
|
+
|
|
35
|
+
- HIGH commit 실행 직전
|
|
36
|
+
- main merge / push 직전
|
|
37
|
+
- destructive 작업(reset/clean/force push) 필요
|
|
38
|
+
- 설계 범위 변경 또는 비목표 추가 필요
|
|
39
|
+
- Codex 리뷰 BLOCKED(exit 2) 또는 제한된 재시도 후 판단 불명확
|
|
40
|
+
- git·Codex CLI·Node·패키지매니저 등 필수 전제 미충족(fail-closed)
|
|
41
|
+
|
|
42
|
+
## 워크플로 명령
|
|
43
|
+
|
|
44
|
+
| 명령 | 용도 |
|
|
45
|
+
|---|---|
|
|
46
|
+
| `req:new <slug> --run` | REQ 티켓 생성(채번·브랜치·`00/01/02` 스캐폴드) |
|
|
47
|
+
| `req:review-codex <id> --kind design\|phase [--phase <p>] --run` | Codex 리뷰 조립·호출·승인 반영 |
|
|
48
|
+
| `req:doctor <id>` | 일관성 게이트(D-체크) |
|
|
49
|
+
| `req:commit <id> [--run] [--message-file <f>]` | 승인된 phase 커밋 + evidence-finalize |
|
|
50
|
+
|
|
51
|
+
설정은 repo 루트의 `req.config.json`(선택). 자세한 계약은 `README.md` 참조.
|
package/README.en.md
CHANGED
|
@@ -1,217 +1,246 @@
|
|
|
1
|
-
# CommitGate
|
|
2
|
-
|
|
3
|
-
🌐 [한국어](./README.md) · **English**
|
|
4
|
-
|
|
5
|
-
**A commit gate that blocks AI-generated code from being committed until Codex has reviewed and approved it.**
|
|
6
|
-
|
|
7
|
-
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.
|
|
8
|
-
|
|
9
|
-
[ · **English**
|
|
4
|
+
|
|
5
|
+
**A commit gate that blocks AI-generated code from being committed until Codex has reviewed and approved it.**
|
|
6
|
+
|
|
7
|
+
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.
|
|
8
|
+
|
|
9
|
+
[](https://github.com/sol5288/commitgate/actions/workflows/ci.yml)
|
|
10
|
+
[](https://www.npmjs.com/package/commitgate)
|
|
11
|
+
[](./LICENSE)
|
|
12
|
+
|
|
13
|
+
---
|
|
14
|
+
|
|
15
|
+
## Quick Start
|
|
16
|
+
|
|
17
|
+
Run this from your project root. The project must be a **git repository with a `package.json`**.
|
|
18
|
+
|
|
19
|
+
```sh
|
|
20
|
+
# If this is a fresh folder that is not yet a git repo or has no package.json, first:
|
|
21
|
+
git init
|
|
22
|
+
npm init -y
|
|
23
|
+
|
|
24
|
+
# Then install:
|
|
25
|
+
npx commitgate
|
|
26
|
+
npm install
|
|
27
|
+
codex --version
|
|
28
|
+
codex login status
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
Then paste this prompt into your AI coding agent.
|
|
32
|
+
|
|
33
|
+
```text
|
|
34
|
+
Do not handle this as a normal implementation. Use the CommitGate workflow installed in this project.
|
|
35
|
+
|
|
36
|
+
Create a new REQ ticket and run this flow end to end:
|
|
37
|
+
req:new → write design docs → Codex design review → implement and test → req:doctor → Codex phase review → req:commit
|
|
38
|
+
|
|
39
|
+
Proceed automatically:
|
|
40
|
+
- If `req:review-codex` returns NEEDS_FIX/exit 3, fix the findings and rerun review.
|
|
41
|
+
- If it returns BLOCKED/exit 2, do not retry the same review; escalate or change the review target. If a stuck thread is suspected, you may retry once with `--fresh-thread`.
|
|
42
|
+
- The review target is only what has been staged with git add.
|
|
43
|
+
- Do not manually git add state.json or responses/.
|
|
44
|
+
|
|
45
|
+
Stop for human confirmation only:
|
|
46
|
+
- Right before req:commit --run
|
|
47
|
+
- Before merging to main or pushing
|
|
48
|
+
- Before destructive actions such as reset, clean, or force push
|
|
49
|
+
- When the requested scope must change
|
|
50
|
+
- When Codex review returns BLOCKED or remains unclear after bounded retries
|
|
51
|
+
|
|
52
|
+
Requirement:
|
|
53
|
+
- What:
|
|
54
|
+
- Why:
|
|
55
|
+
- Constraints:
|
|
56
|
+
- Done when:
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
The agent's first reply should look roughly like this.
|
|
60
|
+
|
|
61
|
+
```text
|
|
62
|
+
REQ-2026-002 created
|
|
63
|
+
Branch: feat/req-2026-002-profile-edit-api
|
|
64
|
+
Phases:
|
|
65
|
+
- phase-1: implement PATCH /profile
|
|
66
|
+
- phase-2: tests and regression checks
|
|
67
|
+
Control points: before req:commit --run, before push
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
After that, the agent runs design, implementation, tests, and Codex review. You only confirm at control points such as commit or push.
|
|
71
|
+
|
|
72
|
+
---
|
|
73
|
+
|
|
74
|
+
## What Does It Enforce?
|
|
75
|
+
|
|
76
|
+
CommitGate is designed to block **unreviewed changes from being committed**, not just to wrap commands.
|
|
77
|
+
|
|
78
|
+
- No Codex approval means no commit.
|
|
79
|
+
- If the approved staged tree differs from the current staged tree, the commit is blocked.
|
|
80
|
+
- Workflow files such as `state.json` and `responses/` cannot be mixed into the source commit.
|
|
81
|
+
- If Codex CLI is missing or fails, the workflow fails instead of silently passing.
|
|
82
|
+
- Review exit codes are outcome-based: `0` approved, `1` invalid/fail-closed, `2` blocked/no actionable findings, `3` needs fix.
|
|
83
|
+
- A no-findings/no-approval response is BLOCKED, not NEEDS_FIX, so agents must not loop on it.
|
|
84
|
+
- During install, existing `cross-spawn` versions below the verified floor warn by default and fail with `--strict`.
|
|
85
|
+
- Approval responses and evidence are kept under `workflow/REQ-.../responses/`.
|
|
86
|
+
|
|
87
|
+
In short: **approved changes pass, ambiguous changes stop.**
|
|
88
|
+
|
|
89
|
+
---
|
|
90
|
+
|
|
91
|
+
## What Installation Adds
|
|
92
|
+
|
|
93
|
+
`npx commitgate` adds the following to the target project. Existing files are not overwritten by default.
|
|
94
|
+
|
|
95
|
+
| Added item | Purpose |
|
|
96
|
+
|---|---|
|
|
97
|
+
| `scripts/req/` | `req:new`, `req:review-codex`, `req:doctor`, `req:commit` scripts |
|
|
98
|
+
| `workflow/*.schema.json` | Schemas for Codex responses and config |
|
|
99
|
+
| `req.config.json` | Project-level configuration |
|
|
100
|
+
| `AGENTS.md` | Template rules for the agent and reviewer |
|
|
101
|
+
| `package.json` scripts | `req:*` commands and required devDependencies |
|
|
102
|
+
|
|
103
|
+
Preview without writing files:
|
|
104
|
+
|
|
105
|
+
```sh
|
|
106
|
+
npx commitgate --dry-run
|
|
107
|
+
```
|
|
108
|
+
|
|
109
|
+
Treat the security floor warning as an install failure:
|
|
110
|
+
|
|
111
|
+
```sh
|
|
112
|
+
npx commitgate --strict
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
If an existing `cross-spawn` is below the verified floor, CommitGate stops before copying files.
|
|
116
|
+
|
|
117
|
+
---
|
|
118
|
+
|
|
119
|
+
## Prerequisites
|
|
120
|
+
|
|
121
|
+
| Requirement | Check | Notes |
|
|
122
|
+
|---|---|---|
|
|
123
|
+
| Git | `git --version` | Required |
|
|
124
|
+
| Node.js 18.17+ | `node --version` | Required |
|
|
125
|
+
| npm, pnpm, or yarn | `npm --version` | Examples use npm |
|
|
126
|
+
| Codex CLI | `codex --version` | Required for review runs |
|
|
127
|
+
|
|
128
|
+
If Codex CLI is not installed:
|
|
129
|
+
|
|
130
|
+
```sh
|
|
131
|
+
npm install -g @openai/codex
|
|
132
|
+
codex login
|
|
133
|
+
codex login status
|
|
134
|
+
```
|
|
135
|
+
|
|
136
|
+
On Windows, if `codex` is not found right after installation, open a new terminal so PATH is reloaded.
|
|
137
|
+
|
|
138
|
+
---
|
|
139
|
+
|
|
140
|
+
## Manual Commands
|
|
141
|
+
|
|
142
|
+
Most users should use the prompt flow above. This section is for understanding what the workflow runs internally or for debugging.
|
|
143
|
+
|
|
144
|
+
```sh
|
|
145
|
+
# 1. Create a ticket and branch
|
|
146
|
+
npm run req:new -- my-feature --run
|
|
147
|
+
|
|
148
|
+
# 2. Write design docs, then stage them
|
|
149
|
+
git add workflow/REQ-2026-001/00-requirement.md workflow/REQ-2026-001/01-design.md workflow/REQ-2026-001/02-plan.md
|
|
150
|
+
|
|
151
|
+
# 3. Design review
|
|
152
|
+
npm run req:review-codex -- 2026-001 --kind design --run
|
|
153
|
+
|
|
154
|
+
# 4. Implement code, then stage source files
|
|
155
|
+
git add <changed-source-files>
|
|
156
|
+
|
|
157
|
+
# 5. Gate check
|
|
158
|
+
npm run req:doctor -- 2026-001
|
|
159
|
+
|
|
160
|
+
# 6. Implementation review
|
|
161
|
+
npm run req:review-codex -- 2026-001 --kind phase --run
|
|
162
|
+
|
|
163
|
+
# 7. Commit approved code
|
|
164
|
+
npm run req:commit -- 2026-001 --run -m "feat: my feature"
|
|
165
|
+
```
|
|
166
|
+
|
|
167
|
+
Important: only stage code and documents you authored for the source commit. `state.json` and `responses/` are managed by the tool.
|
|
168
|
+
|
|
169
|
+
For multi-line commit messages, use a file instead of `-m`.
|
|
170
|
+
|
|
171
|
+
```sh
|
|
172
|
+
npm run req:commit -- 2026-001 --run --message-file commit-message.txt
|
|
173
|
+
```
|
|
174
|
+
|
|
175
|
+
---
|
|
176
|
+
|
|
177
|
+
## Command Cheat Sheet
|
|
178
|
+
|
|
179
|
+
| Command | Purpose |
|
|
180
|
+
|---|---|
|
|
181
|
+
| `npx commitgate` | Install CommitGate into a project |
|
|
182
|
+
| `npx commitgate --dry-run` | Preview the install plan without writing files |
|
|
183
|
+
| `npx commitgate --strict` | Treat low `cross-spawn` version warnings as install failures |
|
|
184
|
+
| `req:new <slug> --run` | Create a REQ ticket, branch, and design docs |
|
|
185
|
+
| `req:review-codex <id> --kind design --run` | Review the design |
|
|
186
|
+
| `req:review-codex <id> --kind phase --run` | Review the implementation |
|
|
187
|
+
| `req:doctor <id>` | Check gate status |
|
|
188
|
+
| `req:commit <id> --run -m "message"` | Commit approved changes |
|
|
189
|
+
|
|
190
|
+
---
|
|
191
|
+
|
|
192
|
+
## Configuration
|
|
193
|
+
|
|
194
|
+
Defaults are enough for most projects. If needed, edit `req.config.json` in the project root.
|
|
195
|
+
|
|
196
|
+
| Key | Default | Meaning |
|
|
197
|
+
|---|---|---|
|
|
198
|
+
| `branchPrefix` | `"feat/req-"` | Prefix for new branches |
|
|
199
|
+
| `ticketRoot` | `"workflow"` | REQ ticket directory |
|
|
200
|
+
| `packageManager` | auto-detected | `npm`, `pnpm`, or `yarn` |
|
|
201
|
+
| `designDocs` | `00/01/02` docs | Design document filenames |
|
|
202
|
+
|
|
203
|
+
Empty `branchPrefix` values and paths that escape the project root are rejected.
|
|
204
|
+
|
|
205
|
+
---
|
|
206
|
+
|
|
207
|
+
## FAQ
|
|
208
|
+
|
|
209
|
+
**What happens if Codex CLI is missing?**
|
|
210
|
+
The review command fails. It is not treated as approval.
|
|
211
|
+
|
|
212
|
+
**Can I edit code after approval and still commit?**
|
|
213
|
+
No. If the staged tree changes after approval, CommitGate treats the approval as stale and requires review again.
|
|
214
|
+
|
|
215
|
+
**Why should I not stage `state.json` or `responses/`?**
|
|
216
|
+
They are workflow state and evidence files. Mixing them into the source commit weakens the approval binding, so `req:commit` blocks it.
|
|
217
|
+
|
|
218
|
+
**What should I do if I see a cross-spawn version warning?**
|
|
219
|
+
It means the target project may already have a `cross-spawn` version below CommitGate's verified floor. Upgrade it with `npm i -D cross-spawn@^7.0.6`. In CI or security-sensitive installs, use `npx commitgate --strict` to treat the warning as a failure.
|
|
220
|
+
|
|
221
|
+
**Does running install twice overwrite files?**
|
|
222
|
+
No. Existing files are skipped. Use `--force` if you intentionally want to refresh them.
|
|
223
|
+
|
|
224
|
+
---
|
|
225
|
+
|
|
226
|
+
## Current Scope
|
|
227
|
+
|
|
228
|
+
The current release is **Stage A: vendored scaffold model**. `npx commitgate` copies workflow files into the target project.
|
|
229
|
+
|
|
230
|
+
Current verification:
|
|
231
|
+
|
|
232
|
+
- GitHub Actions runs a `ubuntu-latest`, `macos-latest`, `windows-latest` × Node 18/20/22 matrix.
|
|
233
|
+
- `npm run smoke` installs the packed tarball and runs the installed `commitgate` bin.
|
|
234
|
+
- A Windows `.cmd` wrapper injection regression test protects package-manager and Codex wrapper paths.
|
|
235
|
+
|
|
236
|
+
Future scope:
|
|
237
|
+
|
|
238
|
+
- Running directly from `node_modules` as a library-style model
|
|
239
|
+
- Non-git VCS support
|
|
240
|
+
- More design document templates
|
|
241
|
+
|
|
242
|
+
---
|
|
243
|
+
|
|
244
|
+
## License
|
|
245
|
+
|
|
246
|
+
[MIT](./LICENSE) © 2026 sol5288
|