commitgate 0.9.0 → 0.9.1

package/AGENTS.template.md

@@ -8,6 +8,28 @@
 > ⚠️ 첫 줄의 `<!-- commitgate:contract -->` 마커를 지우지 마라. `.claude/`·`.cursor/` 진입점 파일이
 > "이 `AGENTS.md`가 CommitGate 계약인가"를 그 마커로 판별하고, `npx commitgate`도 부재 시 경고한다.
 
+<!-- commitgate:quickstart -->
+## CommitGate — 빠른 시작 (첫 요청에서 이대로)
+
+이 저장소의 코드/문서 변경은 CommitGate REQ 워크플로로만 처리한다. 일반 구현으로 바로 커밋하지 않는다.
+
+1. 요청이 [무엇 / 왜 / 제약 / 완료 기준]으로 정리되지 않았으면 **먼저 사용자에게 확인**한다. 추측해서 채우지 않는다.
+2. `package.json`의 `req:new` 스크립트와 `req.config.json`의 `packageManager`를 확인해, 이 저장소의
+   패키지매니저 실행 형식으로 `req:new <슬러그>`를 실행해 REQ 티켓·브랜치를 만든다. 형식을 추측하지 않는다.
+3. 그다음부터 매 단계는 `req:next <REQ-id>`의 출력만 따른다. `kind`가 정본이다:
+   - `RUN`         → 출력된 명령을 그대로 실행하고 다시 `req:next`
+   - `AGENT`       → 구현·검증·명시적 `git add` 후 다시 `req:next`
+   - `AWAIT_HUMAN` → **멈춘다.** 출력된 승인 문장을 그대로 받기 전에는 진행하지 않는다
+   - `DONE`        → 이 티켓 종료. 통합·릴리즈는 별도 통제점
+   - `BLOCKED`     → 사람에게 보고. **같은 리뷰를 재시도하지 않는다**
+4. 리뷰가 `NEEDS_FIX`면 지적(findings)을 고친 뒤 다시 `req:next`로 돌아간다.
+5. `state.json`·`responses/`는 직접 `git add` 하지 않는다 — 도구가 관리한다.
+6. 커밋은 `req:next`가 `RUN`으로 지시할 때 `req:commit`으로만 한다. 스스로 `req:commit`을 호출하지 않는다.
+   직접 `git commit`은 CommitGate 자체 스캐폴딩 산출물(`init`·`migrate`·`sync`가 쓴 파일)을 커밋할 때만 쓴다.
+<!-- /commitgate:quickstart -->
+
+> 위는 빠른 시작 요약이다. 아래가 정본 계약(절대 규칙·통제점·승인 문장)이다.
+
 ## 역할
 
 - **Builder(Claude 등)**: REQ 티켓 단위로 설계→구현→테스트. `req:new`로 티켓·브랜치 생성.

package/CHANGELOG.md

@@ -2,6 +2,20 @@
 
 이 프로젝트는 [Semantic Versioning](https://semver.org/lang/ko/)을 따릅니다.
 
+## 0.9.1
+
+신규 설치의 온보딩을 개선하는 **문서 릴리스**입니다(REQ-2026-039). 실행 코드·의존성 변경이 없어 기존
+사용자는 무회귀이고, **신규 설치에만** 반영됩니다(seed-once — 기존 `CLAUDE.md`/`AGENTS.md`는 보존).
+
+- **온보딩 Quick Start — always-loaded 템플릿 자립화** (REQ-2026-039). 신규 설치가 생성하는
+  `CLAUDE.md`(Claude Code가 항상 로드)와 `AGENTS.md`(Codex·Cursor가 항상 읽는 계약) **앞부분**에,
+  첫 요청에서 올바른 첫 행동을 고를 수 있는 자립형 Quick Start 블록(`req:new` → `req:next` 루프 · 5
+  kind · `state.json`/`responses` staging 금지 · `git commit` 직접 사용 예외)을 넣습니다. 이전엔 이
+  앞부분이 "`AGENTS.md`를 읽어라"는 이정표라, 에이전트가 계약 존재는 알아도 **첫 조작에서 멈추곤**
+  했습니다. 두 템플릿의 블록은 **바이트 동일**(단위 테스트로 강제 — 한쪽만 고치는 drift 방지).
+  **신규 설치에만 반영**(seed-once — 기존 `CLAUDE.md`/`AGENTS.md`는 보존). 기존 파일에 Quick Start를
+  주입하는 UX는 후속(REQ-040).
+
 ## 0.9.0
 
 phase 자동 커밋 opt-in(REQ-2026-037)과 업그레이드 자산 skew 감지·복구(REQ-2026-038)가 핵심입니다. 둘 다 0.8.x 위

package/README.en.md

@@ -62,6 +62,8 @@ git commit -m "chore: install commitgate"
 | `.cursor/rules/commitgate.mdc` | Cursor (`alwaysApply`) |
 | `CLAUDE.md` | Claude Code (always loaded) — created only if absent |
 
+> **On a fresh install, `CLAUDE.md` and `AGENTS.md` open with a self-sufficient Quick Start** (clarify the four-box requirement → `req:new` → the `req:next` loop). Because these are always-loaded channels, the agent picks the correct first action on the first request without reading the full contract. An existing `CLAUDE.md`/`AGENTS.md` is preserved — the Quick Start is not injected in that case.
+
 Just give the agent a requirement.
 
 ```text

package/README.md

@@ -62,6 +62,8 @@ git commit -m "chore: install commitgate"
 | `.cursor/rules/commitgate.mdc` | Cursor (`alwaysApply`) |
 | `CLAUDE.md` | Claude Code (항상 로드) — 부재 시에만 생성 |
 
+> **신규 설치에서 `CLAUDE.md`와 `AGENTS.md`는 맨 앞에 자립형 Quick Start**(요구 4칸 확인 → `req:new` → `req:next` 루프)를 담습니다. 항상 읽히는 채널이라, 에이전트가 계약 본문을 더 읽지 않아도 첫 요청에서 올바른 첫 행동을 고릅니다. 기존 `CLAUDE.md`/`AGENTS.md`가 있으면 보존되어 이때 Quick Start는 새로 주입되지 않습니다.
+
 에이전트에게 요구사항만 주면 됩니다.
 
 ```text

package/package.json

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

package/templates/CLAUDE.template.md

@@ -1,16 +1,27 @@
-# 프로젝트 지침
-
-<!-- 이 파일은 `npx commitgate`가 CLAUDE.md가 없을 때만 생성한 템플릿입니다. 자유롭게 수정하세요. -->
-
-## CommitGate
-
-이 저장소는 **CommitGate**를 쓴다. 코드 변경은 REQ 티켓 단위로 묶이고, Codex가 승인한 staged tree만 커밋된다.
-
-코드를 커밋하게 되는 요청은 일반 구현으로 처리하지 말고 이 워크플로를 따른다.
-
-- **계약 정본**: 저장소 루트의 [`AGENTS.md`](./AGENTS.md). 절대 규칙·통제점·승인 문장이 거기 있다.
-  (`<!-- commitgate:contract -->` 마커가 없으면 CommitGate 계약이 아니다 — init이 함께 설치한 루트의 `AGENTS.commitgate.md`를 계약으로 읽고, 사용자에게 `AGENTS.md`로의 병합을 요청하라.)
-- **다음 행동은 추측하지 않는다**: `req:next <REQ-id>`가 알려 준다.
-  `RUN`은 그대로 실행, `AGENT`는 그 작업 수행 후 `git add`, `AWAIT_HUMAN`은 **멈추고 승인 문장을 그대로** 받는다.
-  워크플로 명령은 이 저장소의 **패키지매니저 실행 형식**으로 돌린다. `req:next`의 `RUN` 출력이 정확한 형태를 그대로 보여 준다.
-- 자세한 진입 절차는 `/req` 슬래시 커맨드 또는 `.claude/skills/commitgate/SKILL.md`에 있다.
+# 프로젝트 지침
+
+<!-- 이 파일은 `npx commitgate`가 CLAUDE.md가 없을 때만 생성한 템플릿입니다. 자유롭게 수정하세요. -->
+
+<!-- commitgate:quickstart -->
+## CommitGate — 빠른 시작 (첫 요청에서 이대로)
+
+이 저장소의 코드/문서 변경은 CommitGate REQ 워크플로로만 처리한다. 일반 구현으로 바로 커밋하지 않는다.
+
+1. 요청이 [무엇 / 왜 / 제약 / 완료 기준]으로 정리되지 않았으면 **먼저 사용자에게 확인**한다. 추측해서 채우지 않는다.
+2. `package.json`의 `req:new` 스크립트와 `req.config.json`의 `packageManager`를 확인해, 이 저장소의
+   패키지매니저 실행 형식으로 `req:new <슬러그>`를 실행해 REQ 티켓·브랜치를 만든다. 형식을 추측하지 않는다.
+3. 그다음부터 매 단계는 `req:next <REQ-id>`의 출력만 따른다. `kind`가 정본이다:
+   - `RUN`         → 출력된 명령을 그대로 실행하고 다시 `req:next`
+   - `AGENT`       → 구현·검증·명시적 `git add` 후 다시 `req:next`
+   - `AWAIT_HUMAN` → **멈춘다.** 출력된 승인 문장을 그대로 받기 전에는 진행하지 않는다
+   - `DONE`        → 이 티켓 종료. 통합·릴리즈는 별도 통제점
+   - `BLOCKED`     → 사람에게 보고. **같은 리뷰를 재시도하지 않는다**
+4. 리뷰가 `NEEDS_FIX`면 지적(findings)을 고친 뒤 다시 `req:next`로 돌아간다.
+5. `state.json`·`responses/`는 직접 `git add` 하지 않는다 — 도구가 관리한다.
+6. 커밋은 `req:next`가 `RUN`으로 지시할 때 `req:commit`으로만 한다. 스스로 `req:commit`을 호출하지 않는다.
+   직접 `git commit`은 CommitGate 자체 스캐폴딩 산출물(`init`·`migrate`·`sync`가 쓴 파일)을 커밋할 때만 쓴다.
+<!-- /commitgate:quickstart -->
+
+- 세부 규칙·통제점·승인 문장의 **정본**은 루트 [`AGENTS.md`](./AGENTS.md)이다.
+  (`<!-- commitgate:contract -->` 마커가 없으면 CommitGate 계약이 아니다 — init이 함께 설치한 루트의 `AGENTS.commitgate.md`를 계약으로 읽고, 사용자에게 `AGENTS.md`로의 병합을 요청하라.)
+- Claude Code에서는 `/req` 슬래시 커맨드로 시작할 수도 있다. 진입 절차 상세는 `.claude/skills/commitgate/SKILL.md`.