commitgate 0.9.3 → 0.9.4

package/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 이 프로젝트는 [Semantic Versioning](https://semver.org/lang/ko/)을 따릅니다.
 
+## 0.9.4
+
+**README 랜딩 서사 보강 + 히어로 이미지** (문서 릴리스). 0.9.3의 랜딩 위에 제품 서사를 강화했습니다 — "코드는 한 AI가 만들고, 다른 AI가 다시 봅니다"(자기 검수의 맹점 → 교대 검수 동기), "사람은 결정에만 참여합니다"(직접 챙기던 일 ↔ CommitGate가 연결 표), 4단계 흐름, 그리고 워크플로를 나타내는 히어로 이미지(빌더 AI → 리뷰어 AI → 사람 확인 → 커밋 게이트)를 추가했습니다. 이미지는 **WebP(~70KB)**로 GitHub raw URL에서 서빙 — `files[]`·npm tarball·payload 축은 **무변경**입니다. 실행 코드·의존성 변경이 없어 기존 사용자는 무회귀입니다.
+
 ## 0.9.3
 
 **README 전면 개편 — 랜딩 페이지 + `docs/` 분리(한/영)** (REQ-2026-042). ~620줄의 `README.md`가 제품 소개·온보딩·운영·제거·안전 계약·개발 현황을 한 화면에 섞어 초점이 흐렸습니다. **README를 랜딩(제품 1줄·핵심 보장·⚠️ 주의·3분 시작·작동 방식·자주 쓰는 명령·docs 허브)으로 줄이고**, 상세를 `docs/` 9종(quick-start·agent-prompt·workflow·guarantees·configuration·upgrade·uninstall·troubleshooting·development)으로 **손실 없이 이동**했습니다. `README.md`/`README.en.md`는 각각 랜딩으로, `docs/*.md`·`docs/*.en.md`로 완전 이중언어. 순수 문서 재배치 — 코드·런타임·게이트·npm payload 축은 **무변경**(`docs/`는 `files[]`에 넣지 않아 tarball 비대화 없음, README→docs 링크는 GitHub 절대 blob URL이라 npm 페이지에서도 해소됨). 링크·앵커 무결성은 `remark-validate-links`로, README→docs 절대 URL·안전 4문구 존재·위치는 전용 테스트로 검증합니다. 기존 사용자 무회귀(설치본에 영향 없음).

package/README.en.md

@@ -8,9 +8,35 @@
 [![npm version](https://img.shields.io/npm/v/commitgate.svg)](https://www.npmjs.com/package/commitgate)
 [![license](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
 
-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 lets **the staged tree Codex approved** be committed. If the code changes after approval, or if evidence is missing, it fails closed by default.
+<p align="center">
+  <img src="https://raw.githubusercontent.com/sol5288/commitgate/main/assets/commitgate-workflow-hero.webp" alt="A builder AI and an independent reviewer AI are followed by a human approval point and a final commit gate" width="1200">
+</p>
 
-## What it blocks
+## One AI builds. Another one reviews.
+
+AI coding agents can plan, implement, and test at remarkable speed. But when the same agent also reviews its own change, it can miss defects through the same assumptions and context that produced the code.
+
+The usual workaround is to copy a change into another model and ask for a second opinion. That is tedious, and it leaves you to track which diff was reviewed, whether it changed afterwards, and when a person actually needs to decide.
+
+CommitGate turns that handoff into a REQ workflow. **Your builder AI makes the change, Codex reviews it independently, and a human is asked only at the control points that need a decision.**
+
+## Humans decide only at control points
+
+| What you would otherwise track yourself | What CommitGate connects |
+|---|---|
+| Copy a builder's change into another model for review | Send the current **staged tree** to the Codex Reviewer |
+| Check manually whether code changed after review | Bind the approved tree to the staged tree and require a new review when it moves |
+| Decide what to check before commit, push, or release | Let `req:next` compute the next action and human control point |
+| Step into every stage | Request an explicit approval only at an `AWAIT_HUMAN` control point |
+
+## The workflow
+
+1. **A builder AI starts the work.** `req:new` creates the REQ ticket, branch, and design documents.
+2. **Codex reviews from an independent perspective.** It reviews the staged tree for design and implementation, then approves it or returns findings.
+3. **A human confirms the important decisions.** Commit, integration, and release are explicit control points because they can be hard to undo or have broader impact.
+4. **The final gate binds the commit.** `req:commit` commits only the exact staged tree that passed the human confirmation and Codex approval.
+
+## What it guarantees
 
 - 🔒 **Nothing is committed without an approved Codex review.** If the review fails or is absent, `req:commit` does not let it through.
 - 🔁 **A staged change that moves after approval is re-reviewed.** If the approved tree differs from the tree you are about to commit, it is blocked as stale.

package/README.md

@@ -8,9 +8,35 @@
 [![npm version](https://img.shields.io/npm/v/commitgate.svg)](https://www.npmjs.com/package/commitgate)
 [![license](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
 
-AI 에이전트가 코드를 빠르게 만들어도, 리뷰 없이 바로 커밋되면 위험합니다. CommitGate는 변경을 티켓(REQ) 단위로 묶고, **Codex가 승인한 staged tree만** 커밋되게 합니다. 승인 후 코드가 바뀌거나 증거가 부족하면 기본적으로 막습니다.
+<p align="center">
+  <img src="https://raw.githubusercontent.com/sol5288/commitgate/main/assets/commitgate-workflow-hero.webp" alt="개발 AI와 독립 검수 AI가 검토한 뒤 사람이 확인하고 최종 커밋 게이트를 통과하는 모습" width="1200">
+</p>
 
-## 무엇을 막아 주나요
+## 코드는 한 AI가 만들고, 다른 AI가 다시 봅니다
+
+AI 코딩 에이전트는 설계·구현·테스트를 아주 빠르게 처리합니다. 하지만 한 에이전트가 자기 변경까지 검수하면, 같은 가정과 같은 작업 맥락 안에서 결함을 놓치기 쉽습니다.
+
+그래서 개발 AI가 만든 변경을 다른 AI에 복사해 붙여 넣고 다시 검수하는 방식이 생깁니다. 문제는 그 과정이 번거롭고, 어느 diff를 검수했는지·검수 뒤 코드가 바뀌었는지·언제 사람이 결정해야 하는지를 계속 사람이 챙겨야 한다는 점입니다.
+
+CommitGate는 이 교대 작업을 REQ 워크플로로 묶습니다. **개발 AI는 만들고, Codex는 독립 Reviewer로 검수하고, 사람은 결정이 필요한 통제점에서만 확인합니다.**
+
+## 사람은 결정에만 참여합니다
+
+| 매번 직접 챙기던 일 | CommitGate가 연결하는 흐름 |
+|---|---|
+| 개발 AI의 변경을 다른 모델에 복사해 검수 요청 | 현재 **staged tree**를 Codex Reviewer에게 검수 요청 |
+| 검수 뒤 코드가 바뀌었는지 수동 대조 | 승인된 tree와 현재 staged tree를 바인딩해 변경 시 재검수 요구 |
+| 커밋·push·릴리스 전에 무엇을 확인할지 판단 | `req:next`가 다음 행동과 사람 확인 지점을 계산 |
+| 모든 단계에 사람이 개입 | `AWAIT_HUMAN` 통제점에서만 명시적인 승인 요청 |
+
+## 이렇게 흘러갑니다
+
+1. **개발 AI가 작업을 시작합니다.** `req:new`가 REQ 티켓·브랜치·설계 문서를 만듭니다.
+2. **Codex가 별도 관점으로 검수합니다.** 설계와 구현의 staged tree를 보고, 승인하거나 수정 사항을 남깁니다.
+3. **사람이 중요한 결정을 확인합니다.** 커밋, 통합, 릴리스처럼 되돌리기 어렵거나 영향이 큰 통제점에서만 승인을 요청합니다.
+4. **최종 게이트가 커밋을 묶습니다.** 사람 확인과 Codex 승인을 통과한, 바로 그 staged tree만 `req:commit`이 커밋합니다.
+
+## 무엇을 보장하나요
 
 - 🔒 **Codex 리뷰 승인 없이는 커밋되지 않습니다.** 리뷰가 실패하거나 아예 없으면 `req:commit`이 통과시키지 않습니다.
 - 🔁 **승인 후 staged 변경이 바뀌면 다시 리뷰를 요구합니다.** 승인된 tree와 지금 커밋하려는 tree가 다르면 stale로 보고 막습니다.

package/package.json

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