commitgate 0.4.0 → 0.7.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/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` → **멈추고** 출력된 승인 문장을 그대로 받는다

package/templates/claude-skill.md

@@ -35,9 +35,12 @@ description: 이 저장소의 REQ 워크플로(CommitGate)로 요구사항을
 **다음 행동을 스스로 추측하지 마라.** 도구가 상태에서 계산해 준다.
 
 ```sh
-npm run req:next -- <REQ-id>
+req:next <REQ-id>
 ```
 
+> 워크플로 명령은 이 저장소의 **패키지매니저 실행 형식**으로 돌린다(npm은 `run`과 `--` 구분자가 필요하고, pnpm·yarn은 스크립트 이름을 바로 받는다).
+> `req:next`의 `RUN` 출력이 언제나 정확한 형태를 그대로 보여 주므로, 그 줄을 복사해 쓰면 된다.
+
 출력의 `kind`가 정본이다(`--json`으로 기계 판독 가능).
 
 | kind | 할 일 |

package/templates/cursor-rule.mdc

@@ -33,10 +33,13 @@ alwaysApply: true
 다음 행동을 스스로 추측하지 마라. 도구가 상태에서 계산한다.
 
 ```sh
-npm run req:new -- <slug> --run     # 티켓·브랜치 생성
-npm run req:next -- <REQ-id>        # 그다음은 항상 이것
+req:new <slug> --run     # 티켓·브랜치 생성
+req:next <REQ-id>        # 그다음은 항상 이것
 ```
 
+> 이 명령들은 저장소의 **패키지매니저 실행 형식**으로 돌린다(npm은 `run`과 `--` 구분자가 필요하고, pnpm·yarn은 스크립트 이름을 바로 받는다).
+> `req:next`의 `RUN` 출력이 정확한 형태를 그대로 보여 준다.
+
 | kind | 할 일 |
 |---|---|
 | `RUN` | 출력된 명령을 그대로 실행하고 다시 `req:next` |

package/templates/workflow.gitignore

@@ -0,0 +1,8 @@
+# CommitGate 워크플로 스크래치 산출물(티켓 내부) — commitgate init이 대상 repo의 workflow/.gitignore로 설치.
+#
+# ⚠️ 이 패턴은 **이 .gitignore 파일이 있는 디렉터리(= workflow/) 기준 상대경로**다(중첩 .gitignore, gitignore(5)).
+#    루트 .gitignore가 쓰는 `workflow/**/…` 형태를 여기 그대로 복사하면 `workflow/workflow/…`를 찾아 무효가 된다.
+#    `/REQ-*/…`로 **앵커드**해 티켓 직계만 무시한다 — 티켓 밖에 흘러든 동명 파일까지 숨기지 않는다(fail-closed 정합).
+/REQ-*/codex-response.json
+/REQ-*/.review-preview.txt
+/REQ-*/.codex-*.tmp

package/workflow/machine.schema.json

@@ -31,7 +31,11 @@
         "additionalProperties": false,
         "required": ["severity", "detail", "file"],
         "properties": {
-          "severity": { "type": "string", "enum": ["P1", "P2", "P3"] },
+          "severity": {
+            "type": "string",
+            "enum": ["P1", "P2", "P3"],
+            "description": "Blocking severity. ONLY P1 belongs in findings, and the output schema you are given permits P1 only — P2/P3 remain in this enum solely so previously archived reviews still validate, and you MUST NOT emit them. A defect is P1 only when ALL THREE hold. (1) CATEGORY: it is a requirement violation, data loss or corruption, a security hole, a monetary error, or a fail-closed bypass. (2) NORMAL PATH: it reproduces on the normal supported usage path — this project supports a single active worktree and a cooperative worker, so rare recovery races, multi-worktree divergence and full distributed consistency are outside the supported model. (3) EVIDENCE: you state a concrete reproduction path or failure scenario ('with this input/state, this wrong result occurs'). EXCLUSION RULE: if it is not in the CATEGORY list it is NOT P1 — even if it reproduces on the normal path, and even if it is genuinely worth fixing. Portability, structure, maintainability, readability, naming, future extensibility, scope-adjacent improvements and follow-up debt all belong in observations, never in findings. If you are guessing or it 'might' be a problem, that is observations too. Putting non-P1 remarks in findings is the failure mode this field exists to prevent: it blocks approval indefinitely and the review never converges."
+          },
           "detail": { "type": "string" },
           "file": { "type": ["string", "null"] }
         }

package/workflow/req.config.schema.json

@@ -9,6 +9,11 @@
     "branchPrefix": { "type": "string", "minLength": 1 },
     "packageManager": { "type": "string", "enum": ["pnpm", "npm", "yarn"] },
     "granularityMaxFiles": { "type": "integer", "minimum": 1 },
+    "reviewModel": { "type": ["string", "null"], "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]*$" },
+    "reviewReasoningEffort": {
+      "type": ["string", "null"],
+      "enum": ["none", "minimal", "low", "medium", "high", "xhigh", null]
+    },
     "designDocs": {
       "type": "object",
       "additionalProperties": false,

package/workflow/review-persona.md

@@ -4,7 +4,28 @@
 
 - Builder가 작성한 리뷰 요청서(`codex-request.md`)의 "리뷰 포인트"는 심사 범위의 **하한**이지 상한이 아니다. 요청서가 묻지 않은 결함도 스스로 분석해 지적하라.
 - Builder가 짜 놓은 리뷰 프레임에 갇히지 마라. 무엇을 봐야 하는지는 네가 판단한다.
-- 개발 부채가 남지 않도록 하라. 지금 넘어가면 나중에 갚아야 하는 것을 식별하라.
+- 개발 부채를 식별하되 **`observations`에 기록해 다음 티켓의 입력으로 만들어라**. 지금 넘어가도 되는 부채까지 차단하는 것은 리뷰의 실패다.
+
+## 보장 범위 경계 (이 경계 밖은 결함이 아니다)
+
+**넓게 보되, 이 프로젝트가 약속한 범위 안에서 판정하라.** 탐색 범위와 차단 범위는 다르다.
+
+- 이 프로젝트는 **하나의 활성 worktree와 협조적 작업자**만 지원한다. CommitGate는 정상적인 반복 호출에서 실수를 막는 도구이지, 비협조적·분산 동시 실행을 합의 없이 해결하는 시스템이 아니다.
+- 따라서 **다중 worktree state 발산·드문 recovery 경합·완전한 분산 정합성**은 지원 범위 밖이다. 이것들은 결함이 아니라 **명시된 경계**다.
+- 지원하지 않는 운영 모델을 근거로 차단하지 마라. 그 경계를 푸는 **새 서브시스템을 요구하지 마라**.
+- **정상 사용 경로를 우선하라.** 정상 경로에서 재현되지 않는 이론적 조합은 `observations`다.
+
+## P1 정의 (차단의 유일한 기준)
+
+`findings`에는 **P1만** 넣는다. P1은 아래 셋을 **모두** 만족할 때만 성립한다.
+
+1. **카테고리**: 요구 위반 · 데이터 손상 · 보안 구멍 · 금전 오류 · fail-closed 우회 중 하나다.
+2. **정상 경로**: 정상 사용 경로에서 재현된다.
+3. **증거**: 재현 경로나 실패 시나리오를 명시했다.
+
+**배제 규칙**: 카테고리에 없으면 **정상 경로에서 재현되더라도, 고칠 가치가 있더라도 P1이 아니다.** 포터빌리티·구조·유지보수·가독성·이름·장래 확장성·범위 인접 개선·후속 부채는 전부 `observations`다. 추측이면 `observations`다.
+
+**절대 표현 금지**: "모든 경우"·"우회 불가"·"어떤 worktree에서도"는 transactional backend가 있을 때만 쓸 수 있다. 설계가 그런 절대 보장을 약속하지 않았다는 이유로 차단하지 마라.
 
 ## 판정은 구조화 응답 필드로만 낸다