commitgate 0.3.1 → 0.7.0

package/bin/migrate.ts

@@ -0,0 +1,244 @@
+#!/usr/bin/env tsx
+/**
+ * commitgate migrate — **Stage A(vendored scaffold) → Stage B(런타임 패키지)** 비파괴 전환 (REQ-2026-014 R5).
+ *
+ * 이 명령이 하는 일은 **하나뿐**이다: 대상 `package.json`의 `req:*` 중 **현재 값이 정확히 Stage A 주입값인 키만**
+ * `commitgate <verb>`로 바꾼다. 그 외에는 아무것도 하지 않는다.
+ *
+ * 비파괴 계약(PM 결정):
+ *   - **아무것도 삭제하지 않는다.** `scripts/req/**`·schema·persona·`req.config.json`·진입점·`workflow/REQ-*` 증거를
+ *     자동 삭제하지 않는다. 정리는 읽기 전용 `commitgate uninstall` 계획 또는 `git revert` 안내로만.
+ *   - **사용자 정의 script를 절대 덮어쓰지 않는다.** 정확한 Stage A 주입값이 아니면 보존하고 수동 조치를 안내한다.
+ *   - **커밋하지 않는다.** 사용자가 검토 후 stage/commit 한다.
+ *   - 기본은 **dry-run**(쓰기 0건). `--apply`에서만 쓴다.
+ *
+ * 쓰기 범위는 **`package.json` 한 파일**이다. 그래서 다중 파일 rollback 프레임워크가 필요 없다
+ * (REQ-2026-014 D11 제거와 일관 — 기존 init도 rollback이 없고 "쓰기 前 실패"가 계약이다).
+ *
+ * ⚠️ **동기(sync) 구현이어야 한다.** launcher(`bin/commitgate.mjs`)가 `mod.runCli(rest)`를 **await 없이** 호출하고
+ *    기존 7개 runCli가 전부 sync `void`다. async면 promise가 버려져 오류가 unhandledRejection이 되고 exit code가 소실된다.
+ *
+ * ⚠️ **대상 root는 `--dir`(기본 cwd)로만 해소한다.** `resolveRoot`(scripts/req/lib/config.ts)는 config를 못 찾으면
+ *    fallback으로 **패키지 자신의 root**를 반환한다 — package.json을 쓰는 이 명령이 그 fallback을 타면
+ *    CommitGate 패키지 자신의 package.json을 재작성한다. init·uninstall과 같은 `--dir` 방식을 쓴다.
+ */
+import { existsSync, readFileSync, writeFileSync, statSync } from 'node:fs'
+import { resolve, join } from 'node:path'
+import { pathToFileURL } from 'node:url'
+import { stripBom } from '../scripts/req/lib/config'
+import { REQ_SCRIPTS, STAGE_B_REQ_SCRIPTS, KIT_SOURCE_DIR_REL, assertGitWorkTree, commitgateDeclared } from './init'
+
+export interface MigrateOptions {
+  dir: string
+  /** 기본 false = dry-run(쓰기 0건). true면 package.json 한 파일을 쓴다. */
+  apply: boolean
+}
+
+/** `req:*` 키 하나의 전환 판정. */
+export interface ScriptDecision {
+  key: string
+  current: string | undefined
+  /** 'convert' = 정확한 Stage A 값 → 전환 대상. 'stage-b' = 이미 전환됨. 'custom' = 사용자 값(보존). 'absent' = 키 없음. */
+  kind: 'convert' | 'stage-b' | 'custom' | 'absent'
+  next: string | undefined
+}
+
+export interface MigratePlan {
+  targetRoot: string
+  decisions: ScriptDecision[]
+  /** 실제로 바꿀 키(kind==='convert'). 비어 있으면 쓸 것이 없다. */
+  converts: ScriptDecision[]
+  /** 보존하는 사용자 정의 키(kind==='custom') — 수동 조치 안내 대상. */
+  customs: ScriptDecision[]
+  /** vendored `scripts/req/**`가 남아 있는가(삭제하지 않는다 — 안내만). */
+  vendoredPresent: boolean
+}
+
+/**
+ * `req:*` 전환 판정(순수 — REQ-2026-014 D5).
+ *
+ * **정확한 바이트 일치일 때만 전환**한다. 이 술어는 `bin/uninstall.ts:295-303`의 `cur === injected`와 같은 계약이며
+ * `REQ_SCRIPTS`가 그 SSOT다. 사용자 정의 값(`req:new = "node custom.mjs"` 등)은 **절대 덮어쓰지 않는다**.
+ */
+export function decideScripts(scripts: Record<string, string>): ScriptDecision[] {
+  return Object.keys(REQ_SCRIPTS).map((key) => {
+    const current = scripts[key]
+    const stageA = REQ_SCRIPTS[key]
+    const stageB = STAGE_B_REQ_SCRIPTS[key]
+    if (current === undefined) return { key, current, kind: 'absent' as const, next: undefined }
+    if (current === stageA) return { key, current, kind: 'convert' as const, next: stageB }
+    if (current === stageB) return { key, current, kind: 'stage-b' as const, next: undefined }
+    return { key, current, kind: 'custom' as const, next: undefined }
+  })
+}
+
+/** 대상을 읽어 계획을 만든다(**쓰기 0건**). */
+export function planMigrate(opts: MigrateOptions): MigratePlan {
+  const targetRoot = resolve(opts.dir)
+  if (!existsSync(targetRoot) || !statSync(targetRoot).isDirectory())
+    throw new Error(`대상 디렉터리가 없음: ${targetRoot}`)
+  assertGitWorkTree(targetRoot) // 실제 git probe(fake .git 마커 거부)
+
+  const pkgPath = join(targetRoot, 'package.json')
+  if (!existsSync(pkgPath)) throw new Error(`package.json 없음: ${targetRoot}`)
+  const pkg = parsePkg(pkgPath)
+  const scripts = pkg.scripts ?? {}
+
+  const decisions = decideScripts(scripts)
+  return {
+    targetRoot,
+    decisions,
+    converts: decisions.filter((d) => d.kind === 'convert'),
+    customs: decisions.filter((d) => d.kind === 'custom'),
+    vendoredPresent: existsSync(join(targetRoot, KIT_SOURCE_DIR_REL)),
+  }
+}
+
+/** package.json 파싱(BOM 허용 — PowerShell `Set-Content -Encoding UTF8`). shape 검증 포함(fail-closed). */
+function parsePkg(pkgPath: string): { scripts?: Record<string, string>; devDependencies?: Record<string, string> } {
+  let raw: unknown
+  try {
+    raw = JSON.parse(stripBom(readFileSync(pkgPath, 'utf8')))
+  } catch (err) {
+    throw new Error(`package.json 파싱 실패(${pkgPath}): ${err instanceof Error ? err.message : String(err)}`)
+  }
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) throw new Error(`package.json이 JSON 객체가 아님: ${pkgPath}`)
+  for (const field of ['scripts', 'devDependencies'] as const) {
+    const v = (raw as Record<string, unknown>)[field]
+    if (v !== undefined && (typeof v !== 'object' || v === null || Array.isArray(v)))
+      throw new Error(`package.json의 ${field} 필드가 객체가 아님(${pkgPath}) — 배열/원시 미지원.`)
+  }
+  return raw as { scripts?: Record<string, string>; devDependencies?: Record<string, string> }
+}
+
+/** 계획을 사람이 읽는 줄 배열로. **shell 연산자(`&&`)를 쓰지 않는다**(Windows PowerShell 5.1·cmd.exe 비호환 — DEC-011-8). */
+export function renderPlan(plan: MigratePlan, apply: boolean): string[] {
+  const L: string[] = []
+  L.push('')
+  L.push(`[commitgate migrate] Stage A → Stage B 전환 ${apply ? '(--apply: package.json 을 씁니다)' : '계획 (dry-run — 아무것도 쓰지 않습니다)'}`)
+  L.push(`  대상: ${plan.targetRoot}`)
+  L.push('')
+
+  if (plan.converts.length > 0) {
+    L.push(`  전환 대상 — 현재 값이 정확히 Stage A 주입값인 키 ${plan.converts.length}개:`)
+    for (const d of plan.converts) L.push(`    package.json#scripts.${d.key}:  "${d.current}"  →  "${d.next}"`)
+  } else {
+    L.push('  전환 대상 없음 — 정확한 Stage A 주입값인 req:* 키가 없습니다.')
+  }
+  L.push('')
+
+  const stageB = plan.decisions.filter((d) => d.kind === 'stage-b')
+  if (stageB.length > 0) L.push(`  이미 Stage B: ${stageB.map((d) => d.key).join(', ')}`)
+
+  if (plan.customs.length > 0) {
+    L.push('')
+    L.push('  ⚠️  사용자 정의 값 — **덮어쓰지 않습니다**. 수동 조치가 필요합니다:')
+    for (const d of plan.customs) L.push(`    package.json#scripts.${d.key} = "${d.current}"`)
+    L.push('    Stage B 런타임을 쓰려면 그 스크립트가 `commitgate <verb>` 를 호출하도록 직접 고치십시오.')
+  }
+
+  if (plan.vendoredPresent) {
+    L.push('')
+    L.push(`  ℹ️  ${KIT_SOURCE_DIR_REL}/ 가 남아 있습니다 — migrate 는 **아무것도 삭제하지 않습니다**(비파괴).`)
+    L.push('     Stage B 에서 실행 코드는 node_modules/commitgate 에서 돕니다. 남은 vendored 파일은 사용하지 않습니다.')
+    L.push('     정리하려면 먼저 읽기 전용 계획을 보십시오: npx commitgate uninstall')
+  }
+
+  L.push('')
+  if (!apply) {
+    L.push('  적용하려면: npx commitgate migrate --apply')
+    L.push('  (--apply 는 package.json 만 씁니다. 커밋하지 않습니다 — 직접 검토 후 stage/commit 하십시오.)')
+  } else if (plan.converts.length > 0) {
+    L.push('  다음: git diff package.json 으로 확인한 뒤 커밋하십시오.')
+    L.push('    git add -- package.json')
+    L.push('    git commit -m "chore: migrate commitgate to Stage B runtime"')
+  }
+  return L
+}
+
+/**
+ * 실행. 기본 dry-run(쓰기 0건), `--apply`에서만 `package.json` 한 파일을 쓴다.
+ *
+ * `--apply` 전 **선행 설치 확인**: Stage B 스크립트(`commitgate <verb>`)를 심으므로 대상에 commitgate가
+ * devDependency로 있어야 한다. init의 D14와 **같은 축소 규칙** — **키 존재만** 보고 값 형태는 검증하지 않는다
+ * (`npm i -D <tgz>`는 `file:…tgz`를 쓴다).
+ */
+export function runMigrate(opts: MigrateOptions): MigratePlan {
+  const plan = planMigrate(opts)
+
+  if (opts.apply) {
+    const pkgPath = join(plan.targetRoot, 'package.json')
+    const pkg = parsePkg(pkgPath)
+    if (!commitgateDeclared(pkg.devDependencies ?? {}))
+      throw new Error(
+        `devDependencies.commitgate 선언이 없습니다 — Stage B 는 req:* 를 'commitgate <verb>' 로 심으므로 ` +
+          `대상에 commitgate 가 devDependency 로 있어야 합니다. 먼저 'npm install -D commitgate' 를 실행한 뒤 다시 시도하십시오.`,
+      )
+    if (plan.converts.length > 0) {
+      const scripts = pkg.scripts ?? {}
+      for (const d of plan.converts) if (d.next !== undefined) scripts[d.key] = d.next
+      pkg.scripts = scripts
+      writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + '\n', 'utf8')
+    }
+  }
+
+  for (const line of renderPlan(plan, opts.apply)) console.log(line)
+  return plan
+}
+
+/** CLI 파싱(fail-closed). 기존 `bin/init.ts`·`bin/uninstall.ts` 관례를 따른다 — `--flag=value` 미지원, 미지 토큰은 throw. */
+export function parseArgs(argv: string[]): MigrateOptions {
+  let dir = process.cwd()
+  let apply = false
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i]
+    if (a === '--dir') {
+      const v = argv[i + 1]
+      if (v === undefined) throw new Error('--dir 값 누락')
+      dir = v
+      i++
+    } else if (a === '--apply') {
+      apply = true
+    } else if (a === '--dry-run') {
+      apply = false // 기본값이지만 명시 허용(문서화된 의도 표현)
+    } else if (a === '-h' || a === '--help') {
+      printHelp()
+      process.exit(0)
+    } else {
+      throw new Error(`알 수 없는 인자: ${a}`)
+    }
+  }
+  return { dir: resolve(dir), apply }
+}
+
+function printHelp(): void {
+  console.log(`commitgate migrate — Stage A(vendored) → Stage B(런타임 패키지) 비파괴 전환
+
+사용법:
+  npx commitgate migrate [--dir <대상repo>]            계획만 출력(기본 — 아무것도 쓰지 않음)
+  npx commitgate migrate --apply [--dir <대상repo>]    package.json 의 req:* 전환
+
+하는 일:
+  package.json 의 req:* 중 **현재 값이 정확히 Stage A 주입값인 키만** "commitgate <verb>" 로 바꿉니다.
+
+하지 않는 일:
+  - 아무것도 삭제하지 않습니다(scripts/req/**·schema·persona·config·진입점·workflow 증거 전부 보존).
+  - 사용자 정의 script 를 덮어쓰지 않습니다(보존 + 수동 조치 안내).
+  - 커밋하지 않습니다.
+
+--apply 전제:
+  대상 package.json 에 devDependencies.commitgate 선언이 있어야 합니다(먼저 'npm install -D commitgate').
+`)
+}
+
+export function runCli(argv: string[]): void {
+  try {
+    runMigrate(parseArgs(argv))
+  } catch (err) {
+    console.error(`commitgate migrate: ${err instanceof Error ? err.message : String(err)}`)
+    process.exitCode = 1
+  }
+}
+
+const isMain = import.meta.url === pathToFileURL(process.argv[1] ?? '').href
+if (isMain) runCli(process.argv.slice(2))

package/bin/uninstall.ts

@@ -21,12 +21,18 @@ import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs'
 import { createHash } from 'node:crypto'
 import { resolve, join, relative } from 'node:path'
 import { pathToFileURL } from 'node:url'
-import { loadConfig, stripBom, DEFAULTS } from '../scripts/req/lib/config'
+import { loadConfig, stripBom, DEFAULTS, DEFAULT_REVIEW_PERSONA_RELPATH } from '../scripts/req/lib/config'
 import { createGitAdapter, type GitAdapter, type GitRunner } from '../scripts/req/lib/adapters'
 import {
   PACKAGE_ROOT,
   KIT_SOURCE_DIR_REL,
   KIT_SCHEMA_RELPATHS,
+  KIT_COPY_RELPATHS,
+  KIT_AGENT_ENTRYPOINTS,
+  KIT_GITIGNORE,
+  KIT_CLAUDE_TEMPLATE_REL,
+  KIT_CLAUDE_DEST_REL,
+  KIT_AGENTS_CONTRACT_COPY_REL,
   REQ_SCRIPTS,
   REQ_DEV_DEPS,
   assertGitWorkTree,
@@ -36,7 +42,11 @@ export interface UninstallOptions {
   dir: string
 }
 
-/** CommitGate가 복사한 파일(kit 소스 + init이 실제로 복사한 스키마). 바이트 비교로 무결성만 표기. */
+/**
+ * CommitGate가 복사한 파일. `path`는 **대상 repo의 경로(dest)**다.
+ * 원본(src)은 패키지 안에서 경로가 다를 수 있다(`templates/claude-skill.md` → `.claude/skills/commitgate/SKILL.md`).
+ * 바이트 비교로 무결성만 표기.
+ */
 export interface ToolArtifact {
   path: string // repo-상대
   present: boolean
@@ -87,6 +97,13 @@ export interface UninstallFacts {
    * 사용자가 직접 넣은 파일일 수 있으므로 제거 후보에 넣지 않고, 디렉터리 통삭제도 제안하지 않는다.
    */
   unknownKitFiles: string[]
+  /**
+   * 대상 `package.json`의 `devDependencies.commitgate` **선언값**(없으면 null) — REQ-2026-014 R4.
+   *
+   * Stage B 런타임 제거 안내(`npm uninstall -D commitgate`)를 낼지 판정하는 데만 쓴다. **진단용 표시**이고
+   * 이 값으로 무엇을 삭제하지 않는다. 값의 형태는 검증하지 않는다(`file:…tgz`·`workspace:*` 전부 정당한 설치 형태).
+   */
+  commitgateDevDependency: string | null
 }
 
 export type UninstallMode = 'not-installed' | 'uncommitted' | 'committed' | 'mixed'
@@ -173,11 +190,13 @@ export function collectFacts(opts: UninstallOptions, run?: GitRunner): Uninstall
   // (깨진 config 때문에 제거 안내를 못 받는 건 부당하다 — planner는 쓰기가 없어 강등이 안전).
   let ticketRoot = DEFAULTS.ticketRoot
   let schemaPath = DEFAULTS.schemaPath
+  let reviewPersonaPath = DEFAULTS.reviewPersonaPath
   let configError: string | null = null
   try {
     const cfg = loadConfig({ root: targetRoot })
     ticketRoot = cfg.ticketRoot
     schemaPath = cfg.schemaPath
+    reviewPersonaPath = cfg.reviewPersonaPath
   } catch (e) {
     configError = (e as Error).message
   }
@@ -190,25 +209,43 @@ export function collectFacts(opts: UninstallOptions, run?: GitRunner): Uninstall
     info.push(
       `schemaPath=${schemaPath} — 런타임이 읽는 경로이지만 init이 복사한 파일이 아닙니다(제거 후보 아님).`,
     )
+  // reviewPersonaPath도 같은 축 분기(REQ-2026-010). null=의도적 비활성이므로 알릴 것이 없다.
+  if (reviewPersonaPath !== null && reviewPersonaPath !== DEFAULT_REVIEW_PERSONA_RELPATH)
+    info.push(
+      `reviewPersonaPath=${reviewPersonaPath} — 런타임이 읽는 경로이지만 init이 복사한 파일이 아닙니다(제거 후보 아님).`,
+    )
 
-  // ── tool: kit 소스 + init이 **실제로 복사한** 스키마(항상 리터럴 workflow/ — ticketRoot 무관)
+  // ── tool: kit 소스 + init이 **실제로 복사한** 파일들.
+  //
+  // ⚠️ `src`와 `dest`가 다른 항목이 있다(REQ-2026-010 D8). `KIT_AGENT_ENTRYPOINTS`는 `templates/*` →
+  //    `.claude/…`·`.cursor/…`로 가고, `AGENTS.commitgate.md`는 `AGENTS.template.md`의 사본이다.
+  //    "원본을 `join(PACKAGE_ROOT, rel)`로 찾는다"는 가정을 버리고 매핑을 명시한다.
+  // 복사 축(KIT_COPY_RELPATHS)을 쓴다. 위 info의 스키마 축(KIT_SCHEMA_RELPATHS)과 의도적으로 다른 상수다.
   const kitSourceRels = walkFiles(join(PACKAGE_ROOT, KIT_SOURCE_DIR_REL)).map(toRel)
-  const toolRels = [...kitSourceRels, ...KIT_SCHEMA_RELPATHS]
-  const tool: ToolArtifact[] = toolRels.map((rel) => {
-    const dest = join(targetRoot, rel)
-    const src = join(PACKAGE_ROOT, rel)
+  const toolEntries: { destRel: string; srcRel: string }[] = [
+    ...kitSourceRels.map((r) => ({ destRel: r, srcRel: r })),
+    ...KIT_COPY_RELPATHS.map((r) => ({ destRel: r, srcRel: r })),
+    ...KIT_AGENT_ENTRYPOINTS.map((e) => ({ destRel: e.dest, srcRel: e.src })),
+    // 마커 없는 AGENTS.md 경로에서만 설치되는 계약 템플릿 사본. 부재가 정상이므로 present=false여도 문제 없다.
+    { destRel: KIT_AGENTS_CONTRACT_COPY_REL, srcRel: 'AGENTS.template.md' },
+    // workflow/.gitignore(REQ-2026-012): src≠dest. identical이면 제거 대상, differs면 review(사용자 편집 보존). 부재 정상.
+    { destRel: KIT_GITIGNORE.dest, srcRel: KIT_GITIGNORE.src },
+  ]
+  const tool: ToolArtifact[] = toolEntries.map(({ destRel, srcRel }) => {
+    const dest = join(targetRoot, destRel)
+    const src = join(PACKAGE_ROOT, srcRel)
     if (!existsSync(dest))
-      return { path: rel, present: false, match: 'absent', tracked: false, introducedBy: null }
+      return { path: destRel, present: false, match: 'absent', tracked: false, introducedBy: null }
     const match: ToolArtifact['match'] =
       existsSync(src) && sha256(dest) === sha256(src) ? 'identical' : 'differs'
-    const tracked = isTracked(git, rel)
+    const tracked = isTracked(git, destRel)
     return {
-      path: rel,
+      path: destRel,
       present: true,
       match,
       tracked,
       // untracked면 이력의 add 커밋은 "지금 이 설치본"의 도입 커밋이 아니다 → 조회조차 하지 않는다(phase R2 P2).
-      introducedBy: tracked ? (introducingCommit(git, rel)?.sha ?? null) : null,
+      introducedBy: tracked ? (introducingCommit(git, destRel)?.sha ?? null) : null,
     }
   })
 
@@ -228,6 +265,21 @@ export function collectFacts(opts: UninstallOptions, run?: GitRunner): Uninstall
     })
   }
 
+  // CLAUDE.md는 AGENTS.md와 같은 계층이다 — init이 **부재 시에만** 만들고 `--force`로도 덮어쓰지 않는다.
+  // 사용자 파일일 수 있으므로 자동 제거 대상이 아니다(REQ-2026-010 D7).
+  const claudeAbs = join(targetRoot, KIT_CLAUDE_DEST_REL)
+  if (existsSync(claudeAbs)) {
+    const tpl = join(PACKAGE_ROOT, KIT_CLAUDE_TEMPLATE_REL)
+    const same = existsSync(tpl) && sha256(claudeAbs) === sha256(tpl)
+    ambiguous.push({
+      path: KIT_CLAUDE_DEST_REL,
+      present: true,
+      note: same
+        ? 'init 템플릿과 동일 — 그래도 자동 제거 대상이 아닙니다(에이전트 지침 파일)'
+        : '템플릿과 다름 — 사용자/팀이 작성했거나 편집했습니다',
+    })
+  }
+
   const cfgAbs = join(targetRoot, 'req.config.json')
   if (existsSync(cfgAbs)) {
     const parsed = readJsonObject(cfgAbs)
@@ -293,6 +345,9 @@ export function collectFacts(opts: UninstallOptions, run?: GitRunner): Uninstall
   const packageJsonDirty = existsSync(pkgAbs) && git.exec(['status', '--porcelain', '--', 'package.json']).length > 0
   const installed = tool.some((t) => t.present) || ambiguous.some((a) => a.present)
 
+  // Stage B 런타임 제거 안내용(REQ-2026-014 R4) — 선언값 표시만. 값 형태는 검증하지 않는다.
+  const commitgateDevDependency = devDeps['commitgate'] ?? null
+
   return {
     targetRoot,
     ticketRoot,
@@ -305,6 +360,7 @@ export function collectFacts(opts: UninstallOptions, run?: GitRunner): Uninstall
     evidence,
     info,
     unknownKitFiles,
+    commitgateDevDependency,
   }
 }
 
@@ -419,9 +475,13 @@ export function renderPlan(plan: UninstallPlan): string {
   L.push(...renderRevertSection(plan))
   L.push('')
 
-  L.push('## 5. 잔여물 경고')
+  L.push('## 5. 런타임 패키지 제거 (Stage B)')
+  L.push(...renderRuntimeRemovalSection(plan))
+  L.push('')
+
+  L.push('## 6. 잔여물 경고')
   L.push('   - git은 빈 디렉터리를 추적하지 않습니다. 위 파일을 지운 뒤 `git status`가 clean이어도')
-  L.push(`     빈 디렉터리(scripts/ · ${facts.ticketRoot}/)가 파일시스템에 남을 수 있습니다.`)
+  L.push(`     빈 디렉터리(scripts/ · ${facts.ticketRoot}/ · .claude/ · .cursor/)가 파일시스템에 남을 수 있습니다.`)
   L.push('   - node_modules의 ajv · cross-spawn · tsx 는 다른 패키지도 쓸 수 있어 제거를 권하지 않습니다.')
   L.push('')
 
@@ -429,6 +489,30 @@ export function renderPlan(plan: UninstallPlan): string {
   return L.join('\n')
 }
 
+/**
+ * **Stage B 런타임 제거 안내**(REQ-2026-014 R4). Stage B에서 실행 코드는 이 저장소가 아니라
+ * `node_modules/commitgate`에 있으므로, 런타임 제거는 **package manager의 책임**이다.
+ *
+ * ⚠️ **문자열로 출력만 한다 — npm을 spawn하지 않는다.** 이 파일의 읽기 전용 불변식이다(`node:fs` 조회 API만 쓰고
+ *    `node:child_process`를 import하지 않는다). 이 안내를 실제 실행으로 바꾸지 말 것.
+ */
+function renderRuntimeRemovalSection(plan: UninstallPlan): string[] {
+  const declared = plan.facts.commitgateDevDependency
+  const L: string[] = []
+  if (declared !== null) {
+    L.push(`   package.json 에 devDependencies.commitgate = "${declared}" 가 선언돼 있습니다(Stage B 런타임).`)
+    L.push('   실행 코드(scripts/req/**)는 이 저장소가 아니라 node_modules/commitgate 에 있습니다.')
+    L.push('   런타임 제거는 package manager 가 담당합니다 — 이 명령은 실행하지 않습니다. 직접 실행하세요:')
+    L.push('     npm uninstall -D commitgate       (pnpm: pnpm remove -D commitgate · yarn: yarn remove commitgate)')
+    L.push('   그러면 devDependencies 선언 · node_modules · lockfile 항목이 함께 정리됩니다.')
+  } else {
+    L.push('   devDependencies.commitgate 선언이 없습니다 — Stage B 런타임 패키지로 설치된 상태가 아닙니다.')
+    L.push('   (Stage A vendored 설치본이거나 `npx commitgate` 일회 실행인 경우입니다 — 아래 npx 캐시 항목 참고.)')
+  }
+  L.push('   package.json 의 req:* 스크립트는 **수동 정리 후보**입니다 — 이 명령은 고치지 않습니다(2번 항목 참조).')
+  return L
+}
+
 function renderRevertSection(plan: UninstallPlan): string[] {
   const L: string[] = []
   const { facts } = plan

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "commitgate",
-  "version": "0.3.1",
-  "description": "CommitGate — Builder↔Reviewer(Claude↔Codex) fail-closed 커밋 게이트: 리뷰·승인·증거 없인 커밋을 통과시키지 않는 AI REQ 워크플로 kit (req:new/review-codex/doctor/commit)",
+  "version": "0.7.0",
+  "description": "CommitGate — Builder↔Reviewer(Claude↔Codex) fail-closed 커밋 게이트: 리뷰·승인·증거 없인 커밋을 통과시키지 않는 AI REQ 워크플로 kit (req:new/next/review-codex/doctor/commit)",
   "type": "module",
   "license": "MIT",
   "author": "sol5288",
@@ -32,20 +32,26 @@
     "req:new": "tsx scripts/req/req-new.ts",
     "req:review-codex": "tsx scripts/req/review-codex.ts",
     "req:doctor": "tsx scripts/req/req-doctor.ts",
+    "req:next": "tsx scripts/req/req-next.ts",
     "req:commit": "tsx scripts/req/req-commit.ts",
     "test": "vitest run",
     "typecheck": "tsc --noEmit",
-    "smoke": "node scripts/smoke.mjs"
+    "smoke": "node scripts/smoke.mjs",
+    "verify:overrides": "node scripts/verify-review-overrides.mjs"
   },
   "files": [
     "scripts/req",
+    "scripts/verify-review-overrides.mjs",
     "workflow/machine.schema.json",
     "workflow/req.config.schema.json",
+    "workflow/review-persona.md",
     "bin",
+    "templates",
     "AGENTS.template.md",
     "req.config.json.sample",
     "README.md",
-    "README.en.md"
+    "README.en.md",
+    "CHANGELOG.md"
   ],
   "engines": {
     "node": ">=18.17"

package/req.config.json.sample

@@ -1,13 +1,16 @@
-{
-  "ticketRoot": "workflow",
-  "schemaPath": "workflow/machine.schema.json",
-  "handoffPath": null,
-  "branchPrefix": "feat/req-",
-  "packageManager": "npm",
-  "granularityMaxFiles": 8,
-  "designDocs": {
-    "requirement": "00-requirement.md",
-    "design": "01-design.md",
-    "plan": "02-plan.md"
-  }
-}
+{
+  "ticketRoot": "workflow",
+  "schemaPath": "workflow/machine.schema.json",
+  "handoffPath": null,
+  "reviewPersonaPath": "workflow/review-persona.md",
+  "branchPrefix": "feat/req-",
+  "packageManager": "npm",
+  "granularityMaxFiles": 8,
+  "reviewModel": "gpt-5.6-terra",
+  "reviewReasoningEffort": "high",
+  "designDocs": {
+    "requirement": "00-requirement.md",
+    "design": "01-design.md",
+    "plan": "02-plan.md"
+  }
+}

package/scripts/req/lib/adapters.ts

@@ -76,6 +76,10 @@ export interface ReviewRequest {
   schemaPath: string
   resumeThreadId: string | null
   cwd: string
+  /** REQ-2026-013 P1: codex `-c model=` override. null = 생략(전역 상속). */
+  model: string | null
+  /** REQ-2026-013 P1: codex `-c model_reasoning_effort=` override. null = 생략. */
+  reasoningEffort: string | null
 }
 export interface ReviewResult {
   rawStdout: string
@@ -109,18 +113,55 @@ const defaultCodexRunner: CodexRunner = (args, input, cwd) =>
   // ⚠️ 과거 `shell:true`는 args(schemaPath·resumeThreadId 등)의 메타문자로 **명령 주입**이 가능했고 공백 경로도 깨졌음 — P1 수정.
   safeSpawnSync('codex', args, { cwd, input, maxBuffer: 64 * 1024 * 1024 })
 
+/** unknown → 평범한 객체(배열·null 제외). 스키마 경로 탐색용. */
+function asPlainObject(v: unknown): Record<string, unknown> | null {
+  return typeof v === 'object' && v !== null && !Array.isArray(v) ? (v as Record<string, unknown>) : null
+}
+
+/**
+ * 출력 스키마의 `findings[].severity`를 **P1만** 허용하도록 좁힌다(REQ-2026-018 D2).
+ *
+ * **왜 출력 스키마에서만 강제하는가(D1)**: 검증 SSOT(`machine.schema.json`)의 enum을 P1로 좁히면 P2/P3를 담은
+ * **기존 archive가 전부 invalid**가 된다(하위호환 파괴). 반면 목표는 "리뷰어가 P2를 findings에 **낼 수 없게**"이므로
+ * 리뷰어가 실제로 보는 출력 스키마 한 곳만 좁히면 충분하다. 그러면 비차단 지적은 `observations`로 갈 수밖에 없고,
+ * `classifyReview`의 "findings 있으면 차단"은 고칠 필요 없이 그대로 옳아진다.
+ *
+ * **왜 조용히 건너뛰지 않고 throw하는가(D3)**: 건너뛰면 P2가 다시 차단 채널로 들어오는 **정책 구멍**이 열리는데,
+ * 그 구멍은 스키마가 깨진 순간에만 열려 아무도 눈치채지 못한다. throw는 리뷰 실패 = 승인 불가 = fail-closed.
+ * `machine_schema_version`이 `1.1`로 고정된 MANAGED 파일이므로 정상 경로에서 이 throw는 발생하지 않는다.
+ */
+function narrowFindingsSeverityToP1(schema: Record<string, unknown>): void {
+  const properties = asPlainObject(schema.properties)
+  const findings = asPlainObject(properties?.findings)
+  const items = asPlainObject(findings?.items)
+  const itemProps = asPlainObject(items?.properties)
+  const severity = asPlainObject(itemProps?.severity)
+  if (!severity || !Array.isArray(severity.enum)) {
+    throw new Error(
+      '출력 스키마 파생 실패: `properties.findings.items.properties.severity.enum` 경로가 없음 — ' +
+        'findings를 P1 전용(차단)으로 강제할 수 없어 중단합니다(REQ-2026-018 D3, fail-closed).',
+    )
+  }
+  severity.enum = ['P1']
+}
+
 /**
- * Codex `--output-schema`용 **strict copy** 파생(REQ-2026-005). OpenAI structured-outputs strict mode는
- * root `required`가 `properties`의 **모든 키**를 포함해야 한다 — optional 필드(예: observations)가 있으면 400 invalid_json_schema.
- * 원본 스키마(`workflow/machine.schema.json`)는 **검증 SSOT로 불변**(observations optional → 기존 archive 하위호환)이고,
- * codex 호출 직전에만 root.required를 `properties` 전체로 확장한 copy를 파생한다. 응답/archive 검증은 계속 원본으로 한다.
- * 중첩 객체(findings/observations items)는 이미 모든 필드 required + additionalProperties:false라 root만 확장하면 충분.
+ * Codex `--output-schema`용 **strict copy** 파생(REQ-2026-005 + REQ-2026-018). 원본 스키마
+ * (`workflow/machine.schema.json`)는 **검증 SSOT로 불변**이고, codex 호출 직전에만 아래 두 가지를 적용한 copy를 파생한다.
+ * 응답/archive 검증은 계속 원본으로 한다.
+ *
+ * 1. **root `required` = `properties` 전체 키**(REQ-2026-005) — OpenAI structured-outputs strict mode는 root required가
+ *    properties의 모든 키를 포함해야 한다. optional 필드(예: observations)가 있으면 400 invalid_json_schema.
+ *    중첩 객체(findings/observations items)는 이미 모든 필드 required + additionalProperties:false라 root만 확장하면 충분.
+ * 2. **`findings[].severity` = `["P1"]`**(REQ-2026-018) — 차단 채널에 P2/P3가 들어오지 못하게 구조적으로 막는다.
+ *    상세 근거는 `narrowFindingsSeverityToP1` 참조.
  */
 export function deriveStrictOutputSchema(schemaText: string): string {
   const schema = JSON.parse(schemaText) as { properties?: Record<string, unknown>; required?: string[]; [k: string]: unknown }
   if (schema && typeof schema === 'object' && schema.properties && typeof schema.properties === 'object') {
     schema.required = Object.keys(schema.properties)
   }
+  narrowFindingsSeverityToP1(schema)
   return JSON.stringify(schema)
 }
 
@@ -136,15 +177,22 @@ export function deriveStrictOutputSchema(schemaText: string): string {
  */
 export function createCodexReviewerAdapter(run: CodexRunner = defaultCodexRunner): ReviewerAdapter {
   return {
-    review({ prompt, schemaPath, resumeThreadId, cwd }) {
+    review({ prompt, schemaPath, resumeThreadId, cwd, model, reasoningEffort }) {
       const tmpDir = mkdtempSync(join(tmpdir(), 'req-codex-'))
       const lastPath = join(tmpDir, 'last.json')
       // 원본(검증 SSOT)을 읽어 strict copy 파생 → temp에 기록 → --output-schema로 전달(archive 검증엔 원본 사용).
       const outputSchemaPath = join(tmpDir, 'output-schema.json')
       writeFileSync(outputSchemaPath, deriveStrictOutputSchema(readFileSync(schemaPath, 'utf8')), 'utf8')
+      // REQ-2026-013 P1: 리뷰 모델·추론강도 override(D2·D2-1). null이면 생략(전역 상속).
+      // 값은 TOML 문자열 리터럴(`sandbox_mode="read-only"`와 동형). 주입 안전은 스키마 제약(model=slug 패턴·effort=enum)이
+      // `"`·개행을 입력단에서 차단하므로 조립부 escaping 불필요 — 이 안전은 config.ts CONFIG_SCHEMA에 의존한다.
+      const overrideArgs: string[] = []
+      if (model) overrideArgs.push('-c', `model="${model}"`)
+      if (reasoningEffort) overrideArgs.push('-c', `model_reasoning_effort="${reasoningEffort}"`)
+      // exec·resume 양쪽에 동일 주입(codex `-c`는 두 서브커맨드 모두 받음 — 실측).
       const args = resumeThreadId
-        ? ['exec', 'resume', resumeThreadId, '-c', 'sandbox_mode="read-only"', '--json', '--output-schema', outputSchemaPath, '--output-last-message', lastPath, '-']
-        : ['exec', '--json', '--sandbox', 'read-only', '--output-schema', outputSchemaPath, '--output-last-message', lastPath, '-']
+        ? ['exec', 'resume', resumeThreadId, '-c', 'sandbox_mode="read-only"', ...overrideArgs, '--json', '--output-schema', outputSchemaPath, '--output-last-message', lastPath, '-']
+        : ['exec', ...overrideArgs, '--json', '--sandbox', 'read-only', '--output-schema', outputSchemaPath, '--output-last-message', lastPath, '-']
       const rawStdout = run(args, prompt, cwd)
       const threadId = resumeThreadId ?? parseThreadId(rawStdout)
       const lastMessage = existsSync(lastPath) ? readFileSync(lastPath, 'utf8') : ''