commitgate 0.3.1 → 0.7.0

package/scripts/req/req-doctor.ts

@@ -5,12 +5,14 @@
  * 1차 최소셋(registry 비의존): D2·D3·D5·D6·D9·D10·D11 + D13(design 선행·freshness)·D15(NEEDS_FIX actionable). (D1/D7/D7b·D4a 등 registry/merge 의존은 2차)
  * FAIL 1건 이상 → exit 1, 자동 보정 금지(P9). review-codex 헬퍼 재사용.
  *
- * 사용: pnpm req:doctor <REQ-id>  |  pnpm req:doctor --ticket <dir>
+ * 사용: req:doctor <REQ-id>  |  req:doctor --ticket <dir>   (저장소 패키지매니저의 실행 형식으로)
  */
 import { existsSync, readFileSync } from 'node:fs'
 import { resolve, join, relative } from 'node:path'
 import { pathToFileURL } from 'node:url'
 import { createHash } from 'node:crypto'
+import { parseStatusZ, entryPaths, formatStatusEntry, STATUS_Z_ARGS, type StatusEntry } from './lib/porcelain'
+import { isArchiveFileName, isAllowedResponsesScratch, reviewScratchPaths } from './lib/scratch'
 import {
   loadState,
   validateVerdict,
@@ -18,13 +20,11 @@ import {
   findUnstagedOrUntracked,
   captureDesignBinding,
   designDocPaths,
-  isArchiveFileName,
-  isAllowedResponsesScratch,
   type WorkflowState,
   type Verdict,
   type ApprovalEvidence,
 } from './review-codex'
-import { loadConfig, packageRoot, type ResolvedConfig } from './lib/config'
+import { loadConfig, packageRoot, stripBom, type ResolvedConfig } from './lib/config'
 import { createGitAdapter, type GitAdapter } from './lib/adapters'
 
 // 모든 git 호출은 GitAdapter 경유(D-017-3). main()이 loadConfig 후 config.root로 재생성(기본 = packageRoot — config 부재 시 현재 동작 보존).
@@ -52,7 +52,7 @@ export interface DoctorInputs {
   // D18 granularity 임계(config, advisory). 미지정 시 GRANULARITY_MAX_FILES(현재 동작). main이 cfg.granularityMaxFiles 주입.
   granularityMaxFiles?: number
   stagedTree: string
-  statusLines: string[]
+  statusEntries: StatusEntry[]
   scratch: string[]
   responseVerdict: Verdict | null
   responseStructureOk: boolean
@@ -72,6 +72,15 @@ export interface DoctorInputs {
   // B3: finalize(복구) 모드. D9 비교 대상을 staged tree → pending_evidence_for.source_commit_sha의 source 커밋 tree로 교체(우회 아님).
   finalize?: boolean
   finalizeSourceTree?: string | null // git rev-parse <pending.source_commit_sha>^{tree}
+  /**
+   * D19(REQ-2026-014): 대상 `package.json`의 `scripts` 맵. main()이 읽어 채운다(runChecks는 순수).
+   *   - `undefined` = main()이 조회하지 않음(legacy/2-arg 호출) → OK '점검 불요'
+   *   - `null`      = package.json 없음/파손 → OK '점검 불요'(읽기 전용 advisory라 FAIL 아님)
+   *   - object      = 파싱된 scripts 맵
+   * ⚠️ **optional이어야 한다** — required면 `tests/unit/req-doctor.test.ts`의 `const base: DoctorInputs = {…}`
+   *    리터럴이 즉시 tsc 오류가 난다(기존 optional 필드 관례와 동일).
+   */
+  reqScripts?: Record<string, string> | null
 }
 
 /**
@@ -114,6 +123,48 @@ export function phaseGranularityWarnings(codeFiles: string[], maxFiles: number):
   return []
 }
 
+/** 설치 모드(REQ-2026-014 D19 진단). `req:*` 스크립트 **값의 형태**로만 판정한다. */
+export type InstallMode = 'stage-a' | 'stage-b' | 'mixed' | 'none' | 'custom'
+
+/**
+ * 진단 대상 `req:*` 키.
+ *
+ * 설치 축의 SSOT는 `bin/init.ts`의 `REQ_SCRIPTS`지만 여기서 import하지 않는다(아래 `classifyInstallMode` 주석 — 레이어 역전).
+ * 키가 늘면 이 목록도 늘려야 한다. 드리프트가 나도 이 검사는 **advisory(WARN 상한)** 라 게이트를 깨지 않는다.
+ */
+const REQ_SCRIPT_KEYS = ['req:new', 'req:next', 'req:review-codex', 'req:doctor', 'req:commit'] as const
+
+/** Stage A 형태: `tsx scripts/req/<file>.ts` (과거 vendored scaffold가 주입하던 모양). */
+const STAGE_A_SCRIPT_RE = /^tsx\s+scripts\/req\/[A-Za-z0-9._-]+\.ts$/
+/** Stage B 형태: `commitgate <verb>` (설치된 패키지 bin dispatch). */
+const STAGE_B_SCRIPT_RE = /^commitgate\s+req:[A-Za-z0-9-]+$/
+
+/**
+ * 설치 모드 진단(REQ-2026-014 D19 — doctor D19, 순수).
+ *
+ * **`package.json`의 `req:*` 값 형태만** 본다. manifest·lockfile·node_modules·버전에 의존하지 않는다.
+ *
+ * ⚠️ **`bin/init.ts`를 import하지 않는다**(레이어 역전 방지). init.ts는 cross-spawn·semver·git spawn을 끌고 오는
+ * ~1250줄 설치 CLI이고, 매 커밋 게이트로 도는 이 스크립트가 그것을 로드해선 안 된다. 그래서 바이트 일치(`REQ_SCRIPTS`)가
+ * 아니라 **shape**로 판정한다 — 요구(R7)도 "script 형태를 기준으로"다.
+ *
+ * ⚠️ **migrate와의 비대칭은 의도적이다**: `bin/migrate.ts`의 전환은 **쓰기**라 `REQ_SCRIPTS` 바이트 정확 일치를
+ * 요구한다(사용자 값을 덮지 않기 위해). 이 진단은 **읽기 전용 advisory**라 shape로 충분하다. 강도를 바꿔야 하는 쪽은 migrate다.
+ *
+ * @param scripts `package.json`의 `scripts` 맵. `undefined`/`null`이면 판정 불가 → 호출부가 '점검 불요'.
+ */
+export function classifyInstallMode(scripts: Record<string, string>): InstallMode {
+  const values = REQ_SCRIPT_KEYS.map((k) => scripts[k]).filter((v): v is string => typeof v === 'string')
+  if (values.length === 0) return 'none'
+  const a = values.filter((v) => STAGE_A_SCRIPT_RE.test(v)).length
+  const b = values.filter((v) => STAGE_B_SCRIPT_RE.test(v)).length
+  if (a > 0 && b > 0) return 'mixed'
+  if (a > 0 && a === values.length) return 'stage-a'
+  if (b > 0 && b === values.length) return 'stage-b'
+  // Stage A/B 형태가 하나도 없거나(전부 사용자 값), 일부만 kit 형태이고 나머지는 사용자 값.
+  return 'custom'
+}
+
 /** 승인 증거 아카이브 파일의 온디스크 검사(main이 읽어 채움 — runChecks는 순수). */
 export interface ArchiveCheck {
   exists: boolean
@@ -189,18 +240,8 @@ function evidenceProblems(
   return r
 }
 
-/**
- * porcelain v1 라인의 **모든** 변경 경로 추출. 비-ASCII는 core.quotePath=false 전제.
- * rename/copy(`R`/`C`, ` -> `)는 [원본, 목적지] **둘 다** 반환 — D13이 양쪽 모두 검사하여
- * 비허용 경로→허용 경로 rename으로 코드 삭제를 우회하는 것을 차단(Codex P2). 그 외는 단일 경로.
- */
-export function statusPaths(line: string): string[] {
-  if (line.length < 4) return []
-  const body = line.slice(3).replace(/\\/g, '/')
-  const arrow = body.indexOf(' -> ')
-  if (arrow >= 0) return [body.slice(0, arrow), body.slice(arrow + 4)]
-  return [body]
-}
+// statusPaths는 lib/porcelain의 entryPaths로 대체(REQ-2026-012). `-z`가 rename의 src·dest를
+// 필드로 확실히 주므로 ` -> ` 분할과 인용 해제가 필요 없다.
 
 /** 순수: 입력으로부터 1차 최소셋 점검 결과 산출(부수효과 없음 — 테스트 용이). */
 export function runChecks(inp: DoctorInputs): Check[] {
@@ -269,8 +310,9 @@ export function runChecks(inp: DoctorInputs): Check[] {
   }
 
   // D10: unstaged/untracked(비-스크래치) — review용 클린. A2: ticketRel 전달 시 responses/ untracked 아카이브만 스크래치 허용(tracked 변조·approvals.jsonl·타 티켓 flag).
-  const dirty = findUnstagedOrUntracked(inp.statusLines, inp.scratch, inp.ticketRel)
-  if (dirty.length) c.push({ id: 'D10', level: 'FAIL', msg: `unstaged/untracked 존재:\n  ${dirty.join('\n  ')}` })
+  const dirty = findUnstagedOrUntracked(inp.statusEntries, inp.scratch, inp.ticketRel)
+  if (dirty.length)
+    c.push({ id: 'D10', level: 'FAIL', msg: `unstaged/untracked 존재:\n  ${dirty.map(formatStatusEntry).join('\n  ')}` })
   else c.push({ id: 'D10', level: 'OK', msg: '워킹트리 클린(staged + 스크래치)' })
 
   // D11: phase≠DONE인데 main 또는 비-<branchPrefix>* 브랜치(DEC-WF-020). branchPrefix=config(기본 feat/req-).
@@ -293,10 +335,10 @@ export function runChecks(inp: DoctorInputs): Check[] {
   // A2(A2-R2-P2-1): 허용된 untracked 응답 아카이브(D10 scratch)는 D13 코드변경 분류에서도 제외 — D10/D13 scratch 정책 일치.
   // (tracked evidence 변조·approvals.jsonl·타 티켓·collapsed dir은 isAllowedResponsesScratch=false라 제외되지 않음 → D10/D13 모두 FAIL 유지.)
   const responsesScratch = inp.ticketRel
-    ? inp.statusLines.filter((l) => isAllowedResponsesScratch(l, inp.ticketRel as string)).flatMap(statusPaths)
+    ? inp.statusEntries.filter((e) => isAllowedResponsesScratch(e, inp.ticketRel as string)).flatMap(entryPaths)
     : []
   const allowD13 = new Set([...inp.ticketDocs, ...inp.scratch, ...responsesScratch].map((p) => p.replace(/\\/g, '/')))
-  const codeChanges = [...new Set(inp.statusLines.flatMap(statusPaths).filter((p) => p !== '' && !allowD13.has(p)))]
+  const codeChanges = [...new Set(inp.statusEntries.flatMap(entryPaths).filter((p) => p !== '' && !allowD13.has(p)))]
   if (!validDesign && codeChanges.length)
     c.push({
       id: 'D13',
@@ -361,9 +403,37 @@ export function runChecks(inp: DoctorInputs): Check[] {
     }
   } else c.push({ id: 'D17', level: 'OK', msg: 'design_approved=false(점검 불요)' })
 
+  // D19(REQ-2026-014): 설치 모드 진단 — `req:*` 값의 **형태**만 본다(manifest·lockfile·node_modules 미사용).
+  //
+  // 🔴 **level 상한은 WARN — 절대 FAIL이 아니다.** CommitGate 자신의 package.json이 Stage A 형태이고(개발 repo가
+  //    자기 스크립트를 직접 실행하므로 정상), `req:commit`이 이 doctor를 exit≠0에 throw하는 하드 게이트로 spawn한다.
+  //    FAIL이면 **이 저장소 자신의 커밋과 정당한 Stage A 소비자 전원의 커밋이 영구 차단**된다.
+  //    Stage A는 결함이 아니라 지원되는 설치 형태다 → mixed만 WARN한다.
+  if (inp.reqScripts === undefined || inp.reqScripts === null) {
+    c.push({ id: 'D19', level: 'OK', msg: 'package.json scripts 미조회/없음(점검 불요)' })
+  } else {
+    const mode = classifyInstallMode(inp.reqScripts)
+    if (mode === 'mixed')
+      c.push({
+        id: 'D19',
+        level: 'WARN',
+        msg: 'req:* 스크립트에 Stage A(tsx scripts/req/*.ts)와 Stage B(commitgate <verb>) 형태가 섞여 있습니다 — `commitgate migrate` 로 전환하세요(형태 기준 진단)',
+      })
+    else c.push({ id: 'D19', level: 'OK', msg: `설치 모드: ${INSTALL_MODE_LABEL[mode]}(req:* 스크립트 형태 기준)` })
+  }
+
   return c
 }
 
+/** D19 메시지용 라벨. */
+const INSTALL_MODE_LABEL: Record<InstallMode, string> = {
+  'stage-a': 'Stage A(vendored — scripts/req/** 를 직접 실행)',
+  'stage-b': 'Stage B(런타임 패키지 — commitgate <verb> dispatch)',
+  mixed: 'mixed',
+  none: 'req:* 스크립트 없음',
+  custom: '사용자 정의 req:* 값(kit 형태 아님)',
+}
+
 // ──────────────────────────────────────────────────────────────── CLI ──
 
 export interface DoctorArgs {
@@ -382,7 +452,9 @@ export function parseArgs(argv: string[]): DoctorArgs {
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i]
     if (a === undefined) continue
-    if (a === '--ticket') ticket = argv[++i] ?? null
+    // bare `--`는 POSIX end-of-options 마커(DEC-011-3). pnpm/yarn은 이를 스크립트에 그대로 넘긴다.
+    if (a === '--') continue
+    else if (a === '--ticket') ticket = argv[++i] ?? null
     else if (a === '--finalize') finalize = true // B3: D9를 finalize(source tree) 모드로
     else if (a === '--root') {
       const v = argv[++i]
@@ -394,6 +466,31 @@ export function parseArgs(argv: string[]): DoctorArgs {
   return { ticket, reqId, finalize, root }
 }
 
+/**
+ * D19(REQ-2026-014): 대상 `package.json`의 `scripts` 맵을 읽는다. 없거나 파손이면 `null`(→ D19는 '점검 불요' OK).
+ *
+ * **읽기 전용 advisory이므로 throw하지 않는다** — package.json이 깨졌다는 사실은 다른 게이트(init·migrate)가
+ * fail-closed로 알린다. 여기서 throw하면 무관한 이유로 `req:commit`의 doctor 게이트가 죽는다.
+ *
+ * `stripBom` 필수: PowerShell `Set-Content -Encoding UTF8`이 만든 BOM'd package.json은 이 플랫폼에서 실제로
+ * 발생하는 실패다. 없으면 정상 파일을 '파손'으로 오분류한다.
+ */
+function readReqScripts(root: string): Record<string, string> | null {
+  const p = join(root, 'package.json')
+  if (!existsSync(p)) return null
+  try {
+    const raw: unknown = JSON.parse(stripBom(readFileSync(p, 'utf8')))
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return null
+    const s = (raw as { scripts?: unknown }).scripts
+    if (!s || typeof s !== 'object' || Array.isArray(s)) return null
+    const out: Record<string, string> = {}
+    for (const [k, v] of Object.entries(s as Record<string, unknown>)) if (typeof v === 'string') out[k] = v
+    return out
+  } catch {
+    return null
+  }
+}
+
 function resolveTicketDir(opts: DoctorArgs, cfg: ResolvedConfig): string {
   if (opts.ticket) return resolve(opts.ticket)
   if (opts.reqId) return join(cfg.workflowDirAbs, `REQ-${opts.reqId.replace(/^REQ-/, '')}`)
@@ -410,8 +507,8 @@ function branchExistsLocal(branch: string): boolean {
   }
 }
 
-function main(): void {
-  const opts = parseArgs(process.argv.slice(2))
+export function main(argv: string[] = process.argv.slice(2)): void {
+  const opts = parseArgs(argv)
   const cfg = loadConfig({ root: opts.root })
   gitAdapter = createGitAdapter(cfg.root) // 모든 git 호출 cwd = config.root
   const ticketDir = resolveTicketDir(opts, cfg)
@@ -490,13 +587,9 @@ function main(): void {
     branchPrefix: cfg.branchPrefix,
     granularityMaxFiles: cfg.granularityMaxFiles,
     stagedTree: git(['write-tree']),
-    // --untracked-files=all: untracked 디렉터리 collapse(`?? responses/`) 방지 — responses/ 아카이브를 개별 파일로 판단(A2-P2 후속).
-    statusLines: git(['-c', 'core.quotePath=false', 'status', '--porcelain', '--untracked-files=all']).split('\n').filter(Boolean),
-    scratch: [
-      repoRel(join(ticketDir, 'codex-response.json')),
-      repoRel(join(ticketDir, '.review-preview.txt')),
-      repoRel(join(ticketDir, 'state.json')), // 도구가 쓰는 메타데이터(4C e2e: review-codex 후 unstaged) — D10 제외
-    ],
+    // `-z`: 경로 인용 없음(설계 D11) → core.quotePath 불필요. --untracked-files=all: `?? responses/` collapse 방지.
+    statusEntries: parseStatusZ(git([...STATUS_Z_ARGS])),
+    scratch: reviewScratchPaths(ticketRel),
     responseVerdict,
     responseStructureOk,
     designApproved: state.design_approved === true,
@@ -512,6 +605,7 @@ function main(): void {
     liveResponseSha256,
     finalize,
     finalizeSourceTree,
+    reqScripts: readReqScripts(cfg.root),
   }
 
   const checks = runChecks(inp)
@@ -521,5 +615,15 @@ function main(): void {
   if (fails.length) process.exit(1)
 }
 
+/** bin dispatch 진입점(친절한 1줄 오류 + exit 1 경계). 직접 `tsx` 실행은 아래 `if (isMain) main()`이 그대로 담당(하위호환). */
+export function runCli(argv: string[]): void {
+  try {
+    main(argv)
+  } catch (err) {
+    console.error(`commitgate: ${err instanceof Error ? err.message : String(err)}`)
+    process.exitCode = 1
+  }
+}
+
 const isMain = import.meta.url === pathToFileURL(process.argv[1] ?? '').href
 if (isMain) main()

package/scripts/req/req-new.ts

@@ -7,14 +7,16 @@
  *   - 기본 dry-run(계획 출력), `--run` 시 실제 브랜치 생성·티켓 파일·스캐폴드 커밋.
  *   - REQ id 채번은 registry 미사용(1차) — workflow/REQ-* 디렉터리 스캔으로 max+1.
  *
- * 사용: pnpm req:new <slug> [--run] [--risk LOW|HIGH] [--title "..."]
+ * 사용: req:new <slug> [--run] [--risk LOW|HIGH] [--title "..."]   (저장소 패키지매니저의 실행 형식으로)
  */
 import { mkdirSync, writeFileSync, readdirSync, existsSync } from 'node:fs'
 import { join, relative } from 'node:path'
 import { pathToFileURL } from 'node:url'
 import { writeState, type WorkflowState } from './review-codex'
-import { loadConfig, packageRoot, type DesignDocs } from './lib/config'
+import { loadConfig, packageRoot, buildScriptInvocation, type DesignDocs, type PackageManager } from './lib/config'
 import { createGitAdapter, type GitAdapter } from './lib/adapters'
+import { parseStatusZ, formatStatusEntry, STATUS_Z_ARGS, type StatusEntry } from './lib/porcelain'
+import { isToolOutputScratch } from './lib/scratch'
 
 // 모든 git 호출은 GitAdapter 경유(D-017-3). main()이 loadConfig 후 config.root로 재생성(기본 = packageRoot — 현재 동작 보존).
 let gitAdapter: GitAdapter = createGitAdapter(packageRoot())
@@ -23,6 +25,17 @@ function git(args: string[]): string {
   return gitAdapter.exec(args)
 }
 
+/**
+ * `req:new` 전용 clean-tree 위반 목록(REQ-2026-012 D7·D8).
+ *
+ * 허용하는 것은 기존 티켓 직계의 **untracked 도구 산출물** 두 종류뿐이다. `state.json`, `responses/**`,
+ * staged-only 변경, rename/copy 등 그 밖의 모든 상태는 그대로 위반이다. review용
+ * `findUnstagedOrUntracked`는 staged-only(`M `)를 통과시키므로 여기서 재사용하지 않는다.
+ */
+export function findReqNewDirtyEntries(rawStatusZ: string, ticketRoot: string): StatusEntry[] {
+  return parseStatusZ(rawStatusZ).filter((entry) => !isToolOutputScratch(entry, ticketRoot))
+}
+
 /** slug 검증: kebab-case(a-z0-9, '-' 구분). */
 export function validateSlug(slug: string): void {
   if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(slug))
@@ -44,6 +57,18 @@ export function branchName(reqId: string, slug: string, branchPrefix: string): s
   return `${branchPrefix}${reqId.replace(/^REQ-/, '')}-${slug}`
 }
 
+/**
+ * `--run` 성공 후 다음 단계 안내(DEC-011-1). **config 로드 이후**이므로 pm별 실행 형식으로 파생한다.
+ *
+ * ⚠️ `DEFAULTS.packageManager`(= `'pnpm'`)를 폴백으로 쓰지 마라. `bin/init.ts`의 감지 폴백은 `'npm'`이라
+ * 두 값이 갈라져 있고, 그걸 문구에 끌어오면 npm 프로젝트가 pnpm 명령을 안내받는다 — 이 REQ가 고치는 결함이다.
+ * config가 없는 지점(헤더 주석·early throw)은 pm-중립 bare 표기를 쓴다.
+ */
+export function nextStepHint(pm: PackageManager, reqId: string): string {
+  const id = reqId.replace(/^REQ-/, '')
+  return `코드 변경 → git add → ${buildScriptInvocation(pm, 'req:review-codex', [id, '--run']).join(' ')}`
+}
+
 export function buildInitialState(reqId: string, branch: string, risk: 'LOW' | 'HIGH'): WorkflowState {
   return {
     id: reqId,
@@ -86,7 +111,10 @@ export function parseArgs(argv: string[]): Opts {
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i]
     if (a === undefined) continue
-    if (a === '--run') {
+    // bare `--`는 POSIX end-of-options 마커(DEC-011-3). pnpm/yarn은 이를 스크립트에 그대로 넘긴다.
+    if (a === '--') {
+      continue
+    } else if (a === '--run') {
       o.run = true
     } else if (a === '--root') {
       const v = argv[++i]
@@ -110,9 +138,10 @@ export function parseArgs(argv: string[]): Opts {
   return o
 }
 
-function main(): void {
-  const o = parseArgs(process.argv.slice(2))
-  if (!o.slug) throw new Error('slug 필요 (예: pnpm req:new camera-hardfail --run)')
+export function main(argv: string[] = process.argv.slice(2)): void {
+  const o = parseArgs(argv)
+  // ⚠️ loadConfig 이전이라 pm을 모른다 → pm-중립 bare 표기(DEFAULTS 폴백 금지, DEC-011-1).
+  if (!o.slug) throw new Error('slug 필요 (예: req:new camera-hardfail --run)')
   validateSlug(o.slug)
 
   const cfg = loadConfig({ root: o.root })
@@ -123,6 +152,8 @@ function main(): void {
   const reqId = nextReqId(year, listExistingReqIds(cfg.workflowDirAbs))
   const branch = branchName(reqId, o.slug, cfg.branchPrefix)
   const ticketDir = join(cfg.workflowDirAbs, reqId)
+  // config 문자열이 `.`·`workflow/.`처럼 같은 위치를 다르게 표현해도 Git이 내는 canonical repo-relative 경로와 맞춘다.
+  const ticketRootRel = relative(cfg.root, cfg.workflowDirAbs).replace(/\\/g, '/')
   const ticketRel = relative(cfg.root, ticketDir).replace(/\\/g, '/')
 
   if (!o.run) {
@@ -134,9 +165,18 @@ function main(): void {
     return
   }
 
-  // 클린 트리 요구(새 브랜치 깨끗이 시작 — 의도 변경 섞임 방지)
-  const dirty = git(['-c', 'core.quotePath=false', 'status', '--porcelain'])
-  if (dirty) throw new Error(`워킹트리가 clean이어야 req:new --run 가능:\n${dirty}`)
+  // 클린 트리 요구(새 브랜치 깨끗이 시작 — 의도 변경 섞임 방지).
+  // 단, gitignore 규칙이 없는 레거시 설치본도 기존 티켓의 순수 untracked 도구 산출물만 좁게 허용한다(D6·D7).
+  const dirtyEntries = findReqNewDirtyEntries(git([...STATUS_Z_ARGS]), ticketRootRel)
+  if (dirtyEntries.length > 0) {
+    const dirty = dirtyEntries.map(formatStatusEntry).join('\n')
+    throw new Error(
+      `워킹트리가 clean이어야 req:new --run 가능:\n${dirty}\n` +
+        `힌트: 방금 \`npx commitgate\`를 실행했다면 **설치분만** 먼저 커밋하십시오(\`git add -A\` 금지 —\n` +
+        `      무관한 변경·.env가 함께 커밋되고, 이어지는 req:review-codex가 그것을 외부로 전송합니다).\n` +
+        `      설치 출력의 "다음:" 안내가 stage할 정확한 경로 목록을 알려 줍니다.`,
+    )
+  }
   const cur = git(['rev-parse', '--abbrev-ref', 'HEAD'])
   if (cur !== 'main') console.warn(`⚠️  현재 브랜치가 main이 아님(${cur}) — REQ는 main에서 시작 권장(DEC-WF-020)`)
 
@@ -166,7 +206,17 @@ function main(): void {
   console.log(`[req:new] 생성 완료: ${reqId}`)
   console.log(`  branch : ${branch} (체크아웃됨)`)
   console.log(`  ticket : ${ticketRel}/  (스캐폴드 커밋)`)
-  console.log(`  다음   : 코드 변경 → git add → pnpm req:review-codex ${reqId.replace(/^REQ-/, '')} --run`)
+  console.log(`  다음   : ${nextStepHint(cfg.packageManager, reqId)}`)
+}
+
+/** bin dispatch 진입점(친절한 1줄 오류 + exit 1 경계). 직접 `tsx` 실행은 아래 `if (isMain) main()`이 그대로 담당(하위호환). */
+export function runCli(argv: string[]): void {
+  try {
+    main(argv)
+  } catch (err) {
+    console.error(`commitgate: ${err instanceof Error ? err.message : String(err)}`)
+    process.exitCode = 1
+  }
 }
 
 const isMain = import.meta.url === pathToFileURL(process.argv[1] ?? '').href