commitgate 0.4.0 → 0.8.0

package/scripts/verify-review-overrides.mjs

@@ -0,0 +1,96 @@
+#!/usr/bin/env node
+/**
+ * REQ-2026-013 P1 — 리뷰 모델·추론강도 override **실효성** live 검증(수동/smoke).
+ *
+ * arg-캡처 단위 테스트(tests/unit/req-adapters.test.ts)는 도구가 `-c` 를 **넘기는지**만 본다.
+ * codex가 그 override를 **존중하는지**(무시하고 전역 상속하지 않는지)는 live로만 확인된다 —
+ * 자기-리뷰 성공은 "적용"과 "무시하고 ultra 상속"을 구분 못 하기 때문(설계 D7).
+ *
+ * 그래서 **bogus 값**을 주고 codex가 **거부**하면 override가 codex에 도달·해석됐다는 증거다:
+ *   - bogus model → `... model is not supported` / `Model metadata for ... not found`
+ *   - bogus effort → `[reasoning.effort] [invalid_enum_value]`
+ * exec·resume 두 경로 각각에 대해 확인한다(어댑터가 `-c` 를 양쪽에 주입하므로).
+ *
+ * ⚠️ 실제 codex CLI + 인증이 필요하다(CI 게이트 아님 — 로컬/수동 실행). exit 0 = 4/4 통과.
+ * 사용: `node scripts/verify-review-overrides.mjs`
+ */
+import spawn from 'cross-spawn'
+
+const BOGUS_MODEL = '__bogus_model_xyz__'
+const BOGUS_EFFORT = '__bogus_effort_xyz__'
+const VALID_MODEL = 'gpt-5.6-terra'
+const VALID_EFFORT = 'high'
+
+/** 어댑터(adapters.ts:review)와 동일한 `-c` 오버라이드 조립. */
+function overrideArgs(model, effort) {
+  const a = []
+  if (model) a.push('-c', `model="${model}"`)
+  if (effort) a.push('-c', `model_reasoning_effort="${effort}"`)
+  return a
+}
+
+/** codex 한 번 실행(exec 또는 resume) → { text: 합쳐진 오류 메시지, code }. cross-spawn(어댑터와 동일 spawn). */
+function runCodex({ resumeThreadId, model, effort }) {
+  const base = resumeThreadId
+    ? ['exec', 'resume', resumeThreadId, '-c', 'sandbox_mode="read-only"', ...overrideArgs(model, effort), '--json', '-']
+    : ['exec', ...overrideArgs(model, effort), '--json', '--sandbox', 'read-only', '-']
+  const r = spawn.sync('codex', base, { input: 'reply with the single word ok', encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 })
+  const out = (r.stdout || '') + '\n' + (r.stderr || '')
+  // JSONL에서 turn.failed/error/item.completed(error)의 message를 모은다(실측 계약).
+  let msgs = ''
+  let threadId = null
+  for (const line of out.split('\n')) {
+    const t = line.trim()
+    if (!t) continue
+    try {
+      const ev = JSON.parse(t)
+      if (ev.type === 'thread.started' && typeof ev.thread_id === 'string') threadId = ev.thread_id
+      if (ev.type === 'error' && typeof ev.message === 'string') msgs += ev.message + '\n'
+      if (ev.type === 'turn.failed' && ev.error?.message) msgs += ev.error.message + '\n'
+      if (ev.type === 'item.completed' && ev.item?.type === 'error' && ev.item?.message) msgs += ev.item.message + '\n'
+    } catch {
+      msgs += t + '\n' // 비-JSONL(에러 텍스트)도 포함
+    }
+  }
+  return { text: msgs + out, code: r.status, threadId }
+}
+
+let pass = 0
+let fail = 0
+function check(label, cond, detail) {
+  if (cond) {
+    pass++
+    console.log(`PASS  ${label}`)
+  } else {
+    fail++
+    console.log(`FAIL  ${label}\n      ${detail}`)
+  }
+}
+
+const modelRejected = (t) => /not supported|not found|invalid.*model|unknown model/i.test(t)
+const effortRejected = (t) => /reasoning.?effort|invalid_enum_value/i.test(t)
+
+console.log('REQ-2026-013 P1 override 실효성 live 검증 (codex CLI 필요)\n')
+
+// 1) 유효 override로 throwaway 스레드 확보(resume 검증용).
+const seed = runCodex({ resumeThreadId: null, model: VALID_MODEL, effort: VALID_EFFORT })
+if (!seed.threadId) {
+  console.log(`FAIL  seed exec가 thread_id를 반환하지 못함 — 유효 model/effort(${VALID_MODEL}/${VALID_EFFORT})로 실행 실패?\n      ${seed.text.slice(0, 400)}`)
+  process.exit(1)
+}
+console.log(`(seed thread = ${seed.threadId})\n`)
+
+// 2) exec — bogus model / bogus effort
+const em = runCodex({ resumeThreadId: null, model: BOGUS_MODEL, effort: VALID_EFFORT })
+check('exec  + bogus model  → codex 거부', modelRejected(em.text), em.text.slice(0, 300))
+const ee = runCodex({ resumeThreadId: null, model: VALID_MODEL, effort: BOGUS_EFFORT })
+check('exec  + bogus effort → codex 거부', effortRejected(ee.text), ee.text.slice(0, 300))
+
+// 3) resume — bogus model / bogus effort (override가 resume에서도 재적용됨을 확인)
+const rm = runCodex({ resumeThreadId: seed.threadId, model: BOGUS_MODEL, effort: VALID_EFFORT })
+check('resume + bogus model  → codex 거부', modelRejected(rm.text), rm.text.slice(0, 300))
+const re = runCodex({ resumeThreadId: seed.threadId, model: VALID_MODEL, effort: BOGUS_EFFORT })
+check('resume + bogus effort → codex 거부', effortRejected(re.text), re.text.slice(0, 300))
+
+console.log(`\n${pass}/${pass + fail} 통과`)
+process.exit(fail === 0 ? 0 : 1)

package/skills/ATTRIBUTION.md

@@ -0,0 +1,85 @@
+# Companion Skills — 출처·라이선스 고지
+
+CommitGate가 번들하는 companion skills(`skills/commitgate-*/SKILL.md`)는 Matt Pocock의 공개 skills를
+**적응(adapt)** 한 파생물이다. 원문은 MIT 라이선스다.
+
+## 기준 upstream
+
+| 항목 | 값 |
+|---|---|
+| 저장소 | https://github.com/mattpocock/skills |
+| 기준 commit | `d574778f94cf620fcc8ce741584093bc650a61d3` |
+| 기준 릴리스 | `v1.1.0` (2026-07-08) |
+| 라이선스 | MIT — `Copyright (c) 2026 Matt Pocock` |
+
+⚠️ **commit SHA가 식별자다.** upstream은 디렉터리 경로를 버전 간 이동시키므로(`in-progress/review` → `engineering/code-review`)
+경로를 기준으로 삼지 않는다. tag도 이론상 이동 가능하므로 SHA로 고정한다.
+
+⚠️ upstream은 **npm에 발행되지 않는다**(`"private": true`). 레지스트리 아티팩트가 없으므로 git SHA가 유일한 pin 수단이다.
+
+⚠️ `npx skills` 설치기는 **Matt의 것이 아니다**(npm `skills` = `vercel-labs/skills`). CommitGate는 **어떤 외부 installer도
+실행하거나 의존하지 않는다** — 이 번들은 패키지 안에 고정된 사본이다.
+
+## 대응 관계
+
+| CommitGate 스킬 | upstream 원문 |
+|---|---|
+| `commitgate-discovery` | `skills/productivity/grilling/SKILL.md` + `skills/engineering/domain-modeling/SKILL.md` |
+| `commitgate-tdd` | `skills/engineering/tdd/SKILL.md` |
+| `commitgate-diagnosing-bugs` | `skills/engineering/diagnosing-bugs/SKILL.md` |
+| `commitgate-research` | `skills/engineering/research/SKILL.md` |
+
+각 SKILL.md 하단의 `## 출처·라이선스` 절에 개별 적응 내용이 기록되어 있다.
+
+## 무엇이 누구의 것인가
+
+바탕 **아이디어**는 prior art이며 Pocock의 것이 아니다 — TDD의 red/green(Kent Beck), 유비쿼터스 언어(Eric Evans),
+델타 디버깅·최소화(Andreas Zeller), ADR(Michael Nygard). 그 아이디어를 쓰는 것은 라이선스 대상이 아니다.
+
+라이선스 대상은 그의 **특정 표현**이다 — 조어("seams", "tracer bullet", "red-capable", 예광탄), 문구, 단계 구조와 순서.
+CommitGate의 스킬은 그 표현과 구조를 알아볼 수 있게 재사용하므로 **파생물로 취급하고 고지를 보존한다.**
+
+## 라이선스 고지가 사는 곳
+
+MIT §2는 고지가 *"all copies or substantial portions of the Software"* 를 따라다닐 것을 요구한다.
+
+→ **각 `SKILL.md`가 저작권 표기와 permission notice 전문을 자체적으로 담는다.** `commitgate init`이 대상 프로젝트에
+설치하는 것은 그 SKILL.md들이므로, 고지가 파일과 함께 이동한다.
+
+⚠️ **이 `ATTRIBUTION.md`는 provenance 상세용이며 대상 프로젝트에 설치되지 않는다. 라이선스 준수 수단이 아니다** —
+준수는 각 SKILL.md 안의 전문이 담당한다.
+
+CommitGate 자신의 루트 `LICENSE`(MIT, `Copyright (c) 2026 sol5288`)는 이 고지와 별개이며 영향을 받지 않는다.
+
+## upstream LICENSE 원문
+
+`https://raw.githubusercontent.com/mattpocock/skills/d574778f94cf620fcc8ce741584093bc650a61d3/LICENSE`
+
+```
+MIT License
+
+Copyright (c) 2026 Matt Pocock
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+```
+
+## 갱신
+
+기준 upstream을 올리려면 새 SHA를 골라 4종 SKILL.md의 `## 출처·라이선스`와 이 문서를 함께 갱신하고,
+`tests/unit/package-payload.test.ts`의 `UPSTREAM_SHA`를 바꾼다. **자동 동기화는 없다**(의도된 경계 — REQ-2026-019 §4).

package/skills/commitgate-diagnosing-bugs/SKILL.md

@@ -0,0 +1,149 @@
+---
+name: commitgate-diagnosing-bugs
+description: 버그·회귀·성능 문제를 피드백 루프부터 만들어 좁혀 간다. 뭔가 깨졌다/던진다/느리다는 보고를 받았을 때, 또는 phase 구현 중 원인 불명 실패를 만났을 때 쓴다. 재현→최소화→가설→계측→수정→회귀 테스트 순서이며, 끝나면 req:next 로 돌아간다.
+---
+
+# CommitGate — 버그 진단
+
+어려운 버그를 위한 규율. **정당한 이유 없이 단계를 건너뛰지 않는다.**
+
+## 전제
+
+버그·회귀·성능 문제일 때만 쓴다. 일반 기능 구현이면 `commitgate-tdd`다.
+
+REQ 안에서 쓴다면 `req:next`가 `AGENT`일 때다. **끝나면 반드시 `req:next`로 돌아간다.**
+진단 결과가 요구·설계를 바꾼다면 `00-requirement.md`/`01-design.md`/`02-plan.md`에 반영해야 하고, 설계가 바뀌면 **재승인**이 필요하다.
+
+## 방법
+
+### Phase 1 — 피드백 루프를 만든다
+
+**이게 이 스킬의 전부다.** 나머지는 기계적이다. *이 버그*에 빨간불이 켜지는 **팽팽한** pass/fail 신호가 있으면 원인은 찾아진다.
+없으면 코드를 아무리 노려봐도 소용없다. **여기에 불균형하게 많이 투자한다.**
+
+만드는 법 — 대략 이 순서로 시도한다:
+
+1. **실패하는 테스트** — 버그에 닿는 seam이면 unit·integration·e2e 아무거나.
+2. **CLI 호출** — 픽스처 입력으로 돌리고 stdout을 known-good과 diff.
+3. **스크립트 재현** — 실제 입력/이벤트를 디스크에 저장해 해당 코드 경로에 격리 재생.
+4. **일회용 하네스** — 최소 부분만 띄워 함수 하나로 버그 경로를 때린다.
+5. **속성/퍼즈 루프** — "가끔 틀림"이면 랜덤 입력 1000개를 돌려 실패 양상을 찾는다.
+6. **차등 루프** — 같은 입력을 구/신 버전에 넣고 출력을 diff.
+
+🔴 **활성 REQ worktree에서 HEAD를 움직이지 마라** — 이분 탐색(bisect)·`reset`·`checkout`으로 과거 상태를 오가는 조사는 이 워크트리에서 **금지**한다. REQ 상태와 staged 승인 바인딩이 깨지고, 승인된 tree가 사라지면 커밋이 막힌다.
+
+🔴 **진단·조사를 위한 커밋은 금지**다 — 진단은 커밋 사유가 **아니다**. 미승인 변경을 커밋하면 리뷰 게이트를 우회하는 것이라, 사람이 승인해도 허용되지 않는다.
+
+**그래서 이분해야 하면 이렇게 한다 — 대개 물어볼 필요가 없다:**
+
+- **이미 커밋되어 있고 깨끗한 승인 baseline**이 있으면, 그것을 활성 worktree **밖의** 버릴 clone/사본으로 복제해 거기서 bisect한다. **사람 승인 없이 진행한다** — 이건 Phase 1 사다리의 일회용 하네스와 같은 급의 **진단 기법**이지 범위 변경이 아니다.
+- 활성 worktree의 HEAD·인덱스·작업물은 건드리지 않는다. **결과(원인 커밋·증상 경계)만** 가져오고 clone은 버린다.
+- 복제할 **깨끗한 승인 baseline이 없다면** 멈추고 사람에게 보고한다 — 미승인 변경을 커밋해서 baseline을 만드는 것은 위 금지에 걸린다.
+- 진단 결과가 **설계·계획·비목표를 바꿔야** 하면 보고해 재승인을 받는다 — 이미 계약의 보고 사유다.
+
+> 멈추는 기준은 **"bisect가 필요해서"가 아니라 "경계를 어기지 않고는 못 해서"** 다. 승인된 범위 안의 진단은 네가 진행한다.
+
+**루프를 조인다.** 일단 루프가 생기면 제품처럼 다룬다 — 더 빠르게(불필요한 초기화 제거), 신호를 더 날카롭게("안 죽었다"가 아니라 **정확한 증상**을 단언), 더 결정적으로(시간 고정·RNG 시드·파일시스템 격리).
+**30초짜리 flaky 루프는 없는 것보다 조금 나을 뿐이고, 2초짜리 결정적 루프는 초능력이다.**
+
+비결정적 버그는 깨끗한 재현이 목표가 아니라 **재현율**이 목표다. 50%면 디버깅 가능하고 1%면 불가능하다 — 될 때까지 올린다.
+
+**완료 기준**: 이미 **최소 한 번 실행해 본** 명령 하나를 댈 수 있고(호출과 출력을 붙인다), 그것이 ① 이 버그의 코드 경로를 실제로 밟으며 **사용자가 말한 바로 그 증상**을 단언하고 ② 결정적이고 ③ 초 단위로 빠르고 ④ 무인 실행 가능할 때.
+
+🔴 **그 명령이 존재하기 전에 이론을 세우려고 코드를 읽고 있다면 멈춰라** — 가설로 직행하는 것이 이 스킬이 막으려는 바로 그 실패다. **red 가능한 명령이 없으면 Phase 2로 가지 않는다.**
+
+루프를 도저히 못 만들겠으면 **그렇다고 명시적으로 말한다.** 시도한 것을 나열하고, 재현 환경 접근·캡처된 아티팩트(로그 덤프·HAR)·임시 계측 허가를 요청한다. **루프 없이 가설로 넘어가지 않는다.**
+
+### Phase 2 — 재현 + 최소화
+
+루프를 돌려 빨간불을 확인한다. **사용자가 말한 그 실패 양상**인지 확인한다 — 근처의 다른 실패면 엉뚱한 버그를 고치게 된다.
+
+빨간불이 켜지면 **여전히 빨간불인 가장 작은 시나리오**로 줄인다. 입력·호출자·설정·데이터·단계를 **하나씩** 잘라내고 매번 다시 돌린다.
+**남은 요소 전부가 필수일 때** 끝이다 — 하나라도 빼면 초록이 된다.
+
+### Phase 3 — 가설
+
+**아무것도 테스트하기 전에 3~5개 가설을 순위 매겨 만든다.** 하나만 세우면 첫 그럴듯한 생각에 닻이 내린다.
+
+각 가설은 **반증 가능**해야 한다: "X가 원인이면, Y를 바꾸면 버그가 사라진다 / Z를 바꾸면 심해진다."
+예측을 못 대면 그건 느낌이다 — 버리거나 날카롭게 한다.
+
+**순위 목록을 사용자에게 보여 준다.** 도메인 지식으로 즉시 재정렬해 주는 경우가 많다. 싼 체크포인트다. 단, 사용자가 자리에 없으면 막히지 말고 진행한다.
+
+### Phase 4 — 계측
+
+각 프로브는 Phase 3의 **특정 예측에 대응**해야 한다. **한 번에 한 변수만** 바꾼다.
+
+1. 가능하면 **디버거/REPL** — 중단점 하나가 로그 열 줄을 이긴다.
+2. 가설을 가르는 **경계에 표적 로그**.
+3. **"전부 찍고 grep" 금지.**
+
+모든 디버그 로그에 **고유 접두사**(`[DEBUG-a4f2]`)를 붙인다 — 정리가 grep 한 번이 된다.
+
+**성능은 다른 갈래다.** 로그가 아니라 기준 측정치(타이밍 하네스·프로파일러·쿼리 플랜)를 먼저 잡고 이분한다. **재고 나서 고친다.**
+
+### Phase 5 — 수정 + 회귀 테스트
+
+**수정 전에** 회귀 테스트를 쓴다 — 단, **올바른 seam이 있을 때만.**
+
+올바른 seam이란 버그가 실제로 일어나는 호출 지점의 **진짜 패턴**을 밟는 곳이다. 너무 얕은 seam(버그는 여러 호출자가 필요한데 단일 호출자 테스트)이면 거짓 안심을 준다.
+
+**올바른 seam이 없으면 그 자체가 발견이다.** 기록한다 — 아키텍처가 버그를 못 잡게 막고 있다는 뜻이다.
+
+있으면: 최소 재현을 그 seam의 실패 테스트로 → 실패 확인 → 수정 → 통과 확인 → **원래(최소화 전) 시나리오로 Phase 1 루프 재실행.**
+
+### Phase 6 — 정리 + 사후
+
+끝났다고 선언하기 전에 필수:
+
+- 원래 재현이 더는 재현되지 않는다(Phase 1 루프 재실행)
+- 회귀 테스트가 통과한다(또는 seam 부재를 문서화했다)
+- 모든 `[DEBUG-...]` 계측을 제거했다(접두사 grep)
+- 일회용 프로토타입을 지웠다
+- **맞았던 가설을 커밋/PR 메시지에 적는다** — 다음 사람이 배운다
+
+**그리고 묻는다: 무엇이 이 버그를 막을 수 있었나?** 답이 아키텍처 변경이면 **수정이 들어간 뒤에** 제안한다 — 지금이 시작할 때보다 아는 게 많다.
+CommitGate에서는 그 제안을 **후속 REQ 또는 backlog**로 보낸다. 현재 phase에 끌어들이지 않는다.
+
+## 경계
+
+- **`git commit`·`git push`·`req:commit` 직접 호출 금지.** `state.json`·`responses/` 스테이징 금지.
+- 진단 결과 자체는 승인 근거가 **아니다.** 설계를 바꾸면 `00`/`01`/`02`에 반영하고 **재승인**을 받는다.
+- 계측·프로토타입을 남긴 채 phase 리뷰에 올리지 않는다.
+- 끝나면 **반드시 `req:next`로 돌아간다.** 다음 행동을 추측하지 않는다. 계약 정본은 저장소 루트의 `AGENTS.md`다.
+
+## 출처·라이선스
+
+Adapted from https://github.com/mattpocock/skills @ `d574778f94cf620fcc8ce741584093bc650a61d3` (v1.1.0).
+Upstream: `skills/engineering/diagnosing-bugs/SKILL.md`.
+적응 내용: CommitGate의 `req:next` 복귀·재승인 경계를 추가하고, 루프 구성 사다리에서 이 저장소에 해당 없는 항목(헤드리스 브라우저·HITL 스크립트)을 덜어 냈다.
+upstream의 **이분 탐색 하네스(`git bisect run`) 항목은 채택하지 않고 명시적 금지로 뒤집었다** — 활성 REQ worktree에서 HEAD가 움직이면
+REQ 상태와 staged 승인 바인딩이 깨진다. 대신 이미 커밋된 깨끗한 승인 baseline의 버릴 clone에서 수행하게 했고,
+그 경로는 **사람 승인을 요구하지 않는다** — "bisect가 필요하다"는 범위 변경이 아니므로 거기에 승인 게이트를 걸면
+`req:next`=AGENT의 정상 진행을 막는 계약 위반이 된다. 멈추는 기준은 경계 위반(깨끗한 baseline 부재 → 미승인 커밋 필요,
+또는 설계·비목표 변경)일 때로 한정했다.
+"무엇이 이 버그를 막을 수 있었나"의 후속 조치도 upstream처럼 다른 스킬로 넘기지 않고 **후속 REQ·backlog**로 보내게 했다.
+
+```
+MIT License
+
+Copyright (c) 2026 Matt Pocock
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+```

package/skills/commitgate-discovery/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: commitgate-discovery
+description: 모호한 요구를 REQ Brief로 정리한다. req:new 로 티켓을 만들기 전에 사용자가 직접 부른다. "뭘 만들지 아직 모르겠다", "이거 정리부터 하자", "요구사항 좀 잡아줘" 같은 상황에서 쓴다. 파일·브랜치·커밋을 만들지 않는다.
+disable-model-invocation: true
+---
+
+# CommitGate — 요구 정리(Discovery)
+
+`req:new` **전에** 쓴다. 산출물은 **REQ Brief 텍스트 하나뿐**이다.
+
+## 전제
+
+- 이 스킬은 **티켓 생성 전** 단계다. 이미 REQ가 있고 `req:next`가 `AGENT`를 반환했다면 이 스킬이 아니다 — 그 작업을 하라.
+- **파일·브랜치·커밋·`state.json`을 만들거나 바꾸지 않는다.** Brief는 대화 안에 머문다.
+
+## 방법
+
+### 사실과 결정을 가른다
+
+**사실**은 찾고, **결정**은 묻는다.
+
+- 코드베이스를 뒤져 알 수 있는 것(현재 구조·기존 관례·의존성·무엇이 이미 있는지)은 **묻지 말고 직접 찾는다.**
+- 트레이드오프가 있는 선택은 **사용자의 것**이다. 하나씩 내놓고 답을 기다린다.
+
+### 한 번에 하나씩 묻는다
+
+질문을 몰아서 던지면 사용자는 압도된다. **하나 묻고, 답을 받고, 다음으로 간다.**
+설계 트리의 가지를 하나씩 내려가며 결정 간 의존을 먼저 푼다.
+
+**각 질문에는 네가 추천하는 답을 함께 낸다.** "어떻게 할까요?"보다 "A를 추천합니다. 이유는 X. 어떻게 할까요?"가 훨씬 빠르다.
+
+### Brief가 채워졌는지 본다
+
+다음이 다 차면 충분하다. 빈 칸이 있으면 그게 다음 질문이다.
+
+- **무엇을 / 왜** — 해결하려는 문제. 기능 목록이 아니라 문제.
+- **제약** — 지켜야 하는 것(호환성·보안·성능·기한).
+- **완료 기준** — 무엇이 참이면 끝인가. 검증 가능한 문장으로.
+- **비목표** — 이번에 **하지 않을** 것. 명시된 경계는 결함이 아니다.
+- **대표 예시** — 정상 경로 하나를 구체적으로.
+- **예외·실패** — 무엇이 잘못될 수 있고 그때 어떻게 되나.
+- **용어** — 프로젝트 용어·새로 만드는 용어·기존 용어와 충돌하는 것.
+- **미결 질문** — 아직 답이 없는 것. 비워 두지 말고 **명시**한다.
+
+### 용어를 벼린다
+
+- 사용자가 흐릿한 낱말("처리한다", "관리한다", "제대로")을 쓰면 **그 자리에서 되묻는다.**
+- 같은 것을 두 이름으로 부르고 있으면 드러낸다. 새 용어를 만들면 기존 용어와 충돌하는지 확인한다.
+- 구체적인 시나리오로 압박한다 — "그럼 X가 비어 있으면요?"
+
+## 경계
+
+- **합의 전에 실행하지 않는다.** 사용자가 "이해가 맞다"고 확인하기 전에 Brief를 코드나 티켓으로 옮기지 않는다.
+- Brief가 충분해지면 기존 CommitGate 흐름으로 넘긴다. **진입 명령은 harness마다 다르다:**
+  - **Claude Code**: `/req` 로 시작한 뒤 `req:new` → `req:next` 반복.
+  - **그 외(Codex CLI·Cursor 등)**: `/req` 같은 command가 **없다.** 저장소 루트 `AGENTS.md`의 워크플로 명령 표를 보고
+    `req:new` → `req:next` 반복으로 들어간다.
+
+  어느 쪽이든 티켓 생성 후의 정본은 `req:next`다.
+- Brief는 승인 근거가 **아니다.** 요구·설계의 정본은 `00-requirement.md`·`01-design.md`이고, 승인 정본은 Codex 리뷰다.
+- `git commit`·`git push`·`req:commit` 직접 호출·`state.json`/`responses` 스테이징을 하지 않는다.
+- 다음 행동을 추측하지 않는다 — **`req:next`가 정본이다.** 계약 정본은 저장소 루트의 `AGENTS.md`다.
+
+## 출처·라이선스
+
+Adapted from https://github.com/mattpocock/skills @ `d574778f94cf620fcc8ce741584093bc650a61d3` (v1.1.0).
+Upstream: `skills/productivity/grilling/SKILL.md`, `skills/engineering/domain-modeling/SKILL.md`.
+적응 내용: CommitGate의 REQ Brief 산출물과 `req:new` 전 권한 경계를 추가하고, 용어 관리는 별도 `CONTEXT.md`/ADR 없이 Brief 안으로 축약했다.
+진입 흐름은 harness별로 분기했다 — `/req`는 Claude Code 전용 command이므로 단정하지 않는다.
+
+```
+MIT License
+
+Copyright (c) 2026 Matt Pocock
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+```

package/skills/commitgate-research/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: commitgate-research
+description: 외부 기술 선택·라이브러리·규격을 1차 출처로 조사한다. 근거가 필요한 결정(어떤 라이브러리를 쓸지, 이 API가 실제로 어떻게 동작하는지, 이 규격이 뭘 요구하는지)일 때 쓴다. 조사 결과는 보조 자료이며 승인 근거가 아니다 — 설계에 영향을 주면 00/01 문서에 반영해야 한다.
+---
+
+# CommitGate — 근거 조사
+
+**근거가 필요한 경우에만** 쓴다. 코드베이스 안에서 답이 나오는 질문은 그냥 코드를 읽어라 — 이 스킬이 아니다.
+
+## 전제
+
+REQ 안에서 쓴다면 `req:next`가 `AGENT`일 때다. 조사는 **보조**이지 그 자체가 진행이 아니다.
+
+쓸 때: 외부 라이브러리·프레임워크 선택, 규격·프로토콜 확인, 벤더 API의 실제 동작, 버전 간 차이.
+쓰지 말 때: 이 저장소가 어떻게 동작하는지(코드를 읽어라), 이미 아는 것(추측을 조사로 포장하지 마라).
+
+## 방법
+
+### 1차 출처를 따른다
+
+**1차 출처**로 조사한다 — 공식 문서, 소스 코드, 규격, 퍼스트파티 API. 그것을 **요약한 2차 글이 아니다.**
+**모든 주장을 그것을 소유한 출처까지 되짚는다.**
+
+블로그·튜토리얼·AI 요약은 출발점일 수는 있어도 **근거가 아니다.** 블로그가 X라고 하면 벤더 문서에서 X를 확인한다.
+둘이 어긋나면 **1차가 이기고, 어긋났다는 사실 자체를 기록한다.**
+
+### 정직하게 등급을 매긴다
+
+각 주장에 신뢰도를 붙인다:
+
+- **verified-primary** — 1차 출처에서 직접 확인했다. URL을 댈 수 있다.
+- **secondary** — 2차 출처만 있다. 1차로 확인 못 했다.
+- **unverified** — 확인하지 못했다. **추측하지 말고 이렇게 표시한다.**
+
+**모르면 모른다고 한다.** 라이선스·보안·호환성처럼 틀리면 비싼 주제에서 추측한 확신은 최악이다.
+
+### 간결하게 정리한다
+
+- **결론** — 질문에 대한 답. 먼저.
+- **출처** — 각 주장마다. URL 또는 파일 경로.
+- **한계** — 확인하지 못한 것, 어긋난 것, 곧 바뀔 것.
+
+가능하면 실측한다. 문서가 X라고 해도 **이 환경에서 실제로 X인지** 확인할 수 있으면 확인하는 편이 낫다.
+
+## 경계
+
+🔴 **조사 결과 자체는 승인 근거가 아니다.**
+
+- 조사가 **설계 결정에 영향을 주면**, 핵심 결론과 인용을 `00-requirement.md` 또는 `01-design.md`에 **반영해야 한다.**
+  그 문서가 정본이고, 그 문서가 Codex 리뷰를 받는다.
+- 외부 조사 문서를 **정본화하지 않는다.** 별도 조사 노트를 만들어 놓고 그것을 근거로 설계 바인딩을 우회하지 않는다.
+- 설계가 이미 승인된 뒤 조사가 그것을 뒤집으면, 조용히 구현을 바꾸지 말고 **설계를 고쳐 재승인**을 받는다.
+- 조사를 이유로 범위를 넓히지 않는다. 흥미롭지만 범위 밖인 발견은 **backlog**로 보낸다.
+- `git commit`·`git push`·`req:commit` 직접 호출 금지. `state.json`·`responses/` 스테이징 금지.
+- 다음 행동을 추측하지 않는다 — **`req:next`가 정본이다.** 계약 정본은 저장소 루트의 `AGENTS.md`다.
+
+## 출처·라이선스
+
+Adapted from https://github.com/mattpocock/skills @ `d574778f94cf620fcc8ce741584093bc650a61d3` (v1.1.0).
+Upstream: `skills/engineering/research/SKILL.md`.
+적응 내용: upstream은 배경 에이전트를 띄워 결과를 저장소의 Markdown 파일로 남기지만, CommitGate는 **설계 문서가 정본**이므로 별도 노트 정본화를 금지하고 `00`/`01` 반영 의무와 신뢰도 등급을 추가했다.
+
+```
+MIT License
+
+Copyright (c) 2026 Matt Pocock
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+```

package/skills/commitgate-tdd/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: commitgate-tdd
+description: CommitGate phase 구현을 Red→Green→Refactor 루프로 돌린다. req:next 가 AGENT 를 반환해 phase 를 구현할 때 쓴다. 테스트를 먼저 쓰고, 최소 구현으로 통과시키고, stage 한 뒤 req:next 로 돌아간다. 직접 커밋하지 않는다.
+---
+
+# CommitGate — Test-First 구현 루프
+
+`AGENTS.md`의 절대 규칙 1(Test-First)을 **실행 가능한 순서**로 편 것이다. 규칙 자체는 `AGENTS.md`가 정본이다.
+
+## 전제
+
+**`req:next`가 `AGENT`를 반환해 phase 구현을 지시했을 때만 유효하다.** 아니면 이 스킬을 쓰지 말고 즉시 `req:next`로 돌아가라.
+
+구현 전에 그 phase의 인수 기준을 `02-plan.md`에서 확인한다. **그 phase의 인수 기준만 구현한다** — 다음 phase 기능을 미리 만들지 않는다.
+
+## 방법
+
+### 1. Seam을 먼저 정한다
+
+**seam**은 테스트를 붙이는 공개 경계다 — 내부를 들추지 않고 동작을 관찰하는 지점.
+
+테스트를 쓰기 전에 **어느 seam에서 테스트할지 적는다.** 전부를 테스트할 수는 없다 — seam을 먼저 정하는 것이
+노력을 임계 경로에 쓰는 방법이다.
+
+**근거는 이미 승인되어 있다.** `02-plan.md`의 phase별 테스트 oracle과 `01-design.md`의 인수 기준이 seam을 정해 뒀다.
+그것을 따른다. 문서가 seam을 특정하지 않았으면 **승인된 인수 기준을 관찰할 수 있는 공개 경계**를 네가 고른다 —
+그 판단은 이미 승인된 범위 안이다.
+
+⚠️ **여기서 사람 승인을 새로 만들지 마라.** `req:next`가 `AGENT`를 준 것은 "그 범위 안에서 구현하라"는 뜻이다.
+사람에게 가야 할 때는 **승인된 범위를 벗어나야 할 때뿐**이다 — 인수 기준이 틀렸거나, seam이 없어서 설계를 바꿔야 하거나,
+비목표를 건드려야 할 때. 그건 이미 계약의 보고 사유이고, 그때는 설계를 고쳐 **재승인**을 받는다.
+
+### 2. Red — 실패하는 테스트를 먼저
+
+게이트를 통과시킬 테스트를 **먼저** 쓰고, **실제로 실패하는 것을 눈으로 본다.**
+실패를 보지 않은 테스트는 통과해도 아무것도 증명하지 않는다.
+
+### 3. Green — 통과시킬 최소 구현
+
+그 테스트를 통과시킬 **딱 그만큼만** 쓴다. 다음 테스트를 앞질러 가거나 추측성 기능을 넣지 않는다.
+
+### 4. Refactor
+
+동작을 바꾸지 않고 정리한다. 테스트는 계속 초록이어야 한다.
+
+### 5. 검증하고 stage
+
+- 관련 단위 테스트 → typecheck → 전체 테스트 순으로 돌린다.
+  ⚠️ **명령을 추측하지 마라.** `02-plan.md`의 그 phase 검증 명령을 그대로 쓰고, 없으면 프로젝트의 script 정의와
+  `req.config.json`의 `packageManager`(npm·pnpm·yarn)를 보고 맞춘다. **패키지매니저를 단정하면 다른 매니저를 쓰는 프로젝트가 깨진다.**
+- staged 범위를 **그 phase의 파일로 제한**한다. `git add -A` 금지.
+- `git diff --cached --check`(공백)·`--stat`(범위) 확인.
+- **`state.json`·`responses/`는 스테이징하지 않는다** — 스크래치로 남겨야 D10이 통과한다.
+
+### 6. `req:next`로 돌아간다
+
+stage했으면 끝이다. 다음 행동은 `req:next`가 계산한다.
+
+## 좋은 테스트
+
+공개 인터페이스로 **동작**을 검증한다. 구현이 통째로 바뀌어도 테스트는 안 바뀌어야 한다.
+좋은 테스트는 명세처럼 읽힌다 — 이름만 보고 어떤 기능이 있는지 알 수 있다.
+
+### 안티패턴
+
+- **구현 결합** — 내부 협력자를 mock하거나, private을 테스트하거나, 옆문(인터페이스 대신 DB 직접 조회)으로 검증한다.
+  징후: 동작은 그대로인데 리팩토링하면 테스트가 깨진다.
+- **동어반복** — 단언이 기대값을 코드와 **같은 방식으로** 다시 계산한다(`expect(add(a,b)).toBe(a+b)`, 손으로 같은 식으로 만든 스냅샷).
+  통과가 구조적으로 보장되니 코드와 절대 어긋날 수 없다. **기대값은 독립적인 근거에서 와야 한다** — 알려진 리터럴, 손으로 푼 예제, 명세.
+- **수평 분할** — 테스트를 다 쓰고 구현을 다 쓴다. 뭉텅이 테스트는 *상상한* 동작을 검증한다 — 실제 동작이 아니라 *모양*을 테스트하게 되고,
+  진짜 변경에 둔감해진다. 대신 **수직 슬라이스**로 간다: 테스트 하나 → 구현 하나 → 반복. 각 테스트가 **예광탄**이라 직전 사이클에서 배운 것에 반응한다.
+
+## 경계
+
+- **`git commit`·`git push`·`req:commit` 직접 호출 금지.** 커밋은 CommitGate의 통제점이다 — 리뷰 승인 후 `req:next`가 지시하고 사용자가 승인한다.
+- **`state.json`·`responses/` 스테이징 금지.**
+- 리뷰 실행·승인 판정·상태 전이는 CommitGate만 한다. 이 스킬은 승인 근거가 **아니다.**
+- 테스트를 건너뛰거나 비활성화해 게이트를 통과시키지 않는다. 실패하면 원인을 고친다.
+- 다음 행동을 추측하지 않는다 — **`req:next`가 정본이다.** 계약 정본은 저장소 루트의 `AGENTS.md`다.
+
+## 출처·라이선스
+
+Adapted from https://github.com/mattpocock/skills @ `d574778f94cf620fcc8ce741584093bc650a61d3` (v1.1.0).
+Upstream: `skills/engineering/tdd/SKILL.md`.
+적응 내용: CommitGate의 phase 루프(`req:next`=AGENT → stage → `req:next`)에 맞추고, 커밋·스테이징 권한 경계를 추가했다.
+upstream은 리팩토링을 루프에서 빼 `code-review` 스킬로 넘기지만, CommitGate는 Codex 리뷰가 그 역할을 하므로 리팩토링을 루프 안에 둔다(`AGENTS.md` 규칙 1과 일치).
+upstream의 *"seam을 사용자에게 확인받아라"*는 **채택하지 않았다** — CommitGate에서 seam 근거는 이미 승인된 `01-design.md`/`02-plan.md`이고,
+`AGENT` 단계에 새 사람 승인 지점을 만드는 것은 계약 위반이다. 사람에게 가는 경우는 **승인된 범위를 벗어날 때**로 한정했다.
+검증 명령도 upstream처럼 특정 매니저를 단정하지 않고 `02-plan.md`·감지된 `packageManager`를 따르게 했다.
+
+```
+MIT License
+
+Copyright (c) 2026 Matt Pocock
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+```

package/templates/CLAUDE.template.md

@@ -10,6 +10,7 @@
 
 - **계약 정본**: 저장소 루트의 [`AGENTS.md`](./AGENTS.md). 절대 규칙·통제점·승인 문장이 거기 있다.
   (`<!-- commitgate:contract -->` 마커가 없으면 CommitGate 계약이 아니다 — init이 함께 설치한 루트의 `AGENTS.commitgate.md`를 계약으로 읽고, 사용자에게 `AGENTS.md`로의 병합을 요청하라.)
-- **다음 행동은 추측하지 않는다**: `npm run req:next -- <REQ-id>`가 알려 준다.
+- **다음 행동은 추측하지 않는다**: `req:next <REQ-id>`가 알려 준다.
   `RUN`은 그대로 실행, `AGENT`는 그 작업 수행 후 `git add`, `AWAIT_HUMAN`은 **멈추고 승인 문장을 그대로** 받는다.
+  워크플로 명령은 이 저장소의 **패키지매니저 실행 형식**으로 돌린다. `req:next`의 `RUN` 출력이 정확한 형태를 그대로 보여 준다.
 - 자세한 진입 절차는 `/req` 슬래시 커맨드 또는 `.claude/skills/commitgate/SKILL.md`에 있다.

package/templates/claude-command.md

@@ -25,8 +25,11 @@ $ARGUMENTS
 
 ## 절차
 
-1. `npm run req:new -- <slug> --run` — 티켓과 브랜치를 만든다.
-2. 그다음부터는 **`npm run req:next -- <REQ-id>`가 시키는 대로** 한다.
+> 아래 명령은 **저장소의 패키지매니저 실행 형식**으로 돌린다(npm은 `run`과 `--` 구분자가 필요하고, pnpm·yarn은 스크립트 이름을 바로 받는다).
+> `npx commitgate` 설치 출력과 `req:next`의 `RUN` 출력이 언제나 이 저장소에 맞는 정확한 형태를 보여 준다 — 그걸 그대로 쓰면 된다.
+
+1. `req:new <slug> --run` — 티켓과 브랜치를 만든다.
+2. 그다음부터는 **`req:next <REQ-id>`가 시키는 대로** 한다.
    - `RUN` → 출력된 명령을 그대로 실행 → 다시 `req:next`
    - `AGENT` → 그 작업을 하고 `git add` → 다시 `req:next`
    - `AWAIT_HUMAN` → **멈추고** 출력된 승인 문장을 그대로 받는다