commitgate 0.9.8 → 0.9.10

package/bin/uninstall.ts

@@ -35,6 +35,7 @@ import {
   KIT_CLAUDE_DEST_REL,
   KIT_AGENTS_CONTRACT_COPY_REL,
   REQ_SCRIPTS,
+  STAGE_B_REQ_SCRIPTS,
   REQ_DEV_DEPS,
   assertGitWorkTree,
 } from './init'
@@ -121,6 +122,11 @@ export interface UninstallPlan {
   /** 티켓이 실제로 쌓인 증거 디렉터리 — 삭제 금지. */
   protect: EvidenceDir[]
   scaffoldCommits: ScaffoldCommit[]
+  /**
+   * 도입 커밋 revert가 `workflow/.gitignore`를 함께 되돌려 **보존 대상 티켓의 scratch가 드러나는가**
+   * (REQ-2026-058 F-6). git 조회가 필요하므로 순수 `buildPlan`은 항상 `false`로 두고 `enrichCommits`가 채운다.
+   */
+  revertDropsWorkflowGitignore: boolean
 }
 
 const TICKET_DIR_RE = /^REQ-\d{4}-\d+$/
@@ -304,13 +310,18 @@ export function collectFacts(opts: UninstallOptions, run?: GitRunner): Uninstall
   const pkg = existsSync(pkgAbs) ? readJsonObject(pkgAbs) : null
   const scripts = stringMap(pkg, 'scripts')
   const devDeps = stringMap(pkg, 'devDependencies')
-  for (const [k, injected] of Object.entries(REQ_SCRIPTS)) {
+  // 🔴 DEC-D3: req:* script를 **Stage-A 서명(REQ_SCRIPTS) ∪ Stage-B 값(STAGE_B_REQ_SCRIPTS)** 양쪽 기준으로
+  //    분류한다. 현재 값이 둘 중 하나와 일치하면 CommitGate 주입값(제거 대상 표시), 아니면 사용자 정의(보존).
+  //    Stage-B 표면(dispatch 파생)이라 reconstruct 등 신규 verb도 포함된다.
+  const reqKeys = [...new Set([...Object.keys(REQ_SCRIPTS), ...Object.keys(STAGE_B_REQ_SCRIPTS)])].sort()
+  for (const k of reqKeys) {
     const cur = scripts[k]
     if (cur === undefined) continue
+    const isInjected = cur === REQ_SCRIPTS[k] || cur === STAGE_B_REQ_SCRIPTS[k]
     ambiguous.push({
       path: `package.json#scripts.${k}`,
       present: true,
-      note: cur === injected ? 'init 주입값과 동일' : `사용자 값(init 주입값과 다름): ${cur}`,
+      note: isInjected ? 'init 주입값과 동일' : `사용자 값(init 주입값과 다름): ${cur}`,
     })
   }
   for (const [k, injected] of Object.entries(REQ_DEV_DEPS)) {
@@ -401,6 +412,7 @@ export function buildPlan(facts: UninstallFacts): UninstallPlan {
     keep: facts.ambiguous.filter((a) => a.present),
     protect: facts.evidence.filter((e) => e.ticketCount > 0),
     scaffoldCommits,
+    revertDropsWorkflowGitignore: false, // git 조회는 enrichCommits가 한다(순수 유지)
   }
 }
 
@@ -416,7 +428,10 @@ function enrichCommits(plan: UninstallPlan, git: GitAdapter): UninstallPlan {
     const found = anchor ? introducingCommit(git, anchor) : null
     return { sha: c.sha, subject: found?.subject ?? '' }
   })
-  return { ...plan, scaffoldCommits }
+  // F-6: 보존할 증거가 있을 때만 판정한다 — 증거가 없으면 드러날 scratch도 없어 경고가 소음이다.
+  const revertDropsWorkflowGitignore =
+    plan.protect.length > 0 && revertDropsWorkflowGitignoreCheck(scaffoldCommits, git)
+  return { ...plan, scaffoldCommits, revertDropsWorkflowGitignore }
 }
 
 // ────────────────────────────────────────────────────── 출력 (순수) ──
@@ -442,6 +457,15 @@ export function renderPlan(plan: UninstallPlan): string {
 
   if (plan.mode === 'not-installed') {
     L.push('이 repo에서 CommitGate 설치 흔적을 찾지 못했습니다. 되돌릴 것이 없습니다.')
+    // 🔴 REQ-2026-058 F-8: "되돌릴 것이 없다"와 "감사 증거가 남아 있다"는 **동시에 참일 수 있다**.
+    //    제거를 마친 뒤의 정상적인 모습이 정확히 이것이다 — 티켓 디렉터리는 보존하도록 안내했기 때문이다.
+    //    이 절을 건너뛰면 사용자는 남은 증거의 존재를 모른 채 "아무것도 없다"고 읽는다.
+    if (plan.protect.length) {
+      L.push('')
+      L.push('## 남아 있는 감사 증거 — 삭제하지 마세요')
+      for (const e of plan.protect) L.push(`     - ${e.path}/  (REQ 티켓 ${e.ticketCount}개 · state.json · approvals.jsonl)`)
+      L.push('   설치는 제거됐지만 이 기록은 남습니다. 이력을 보존할 것인지 함께 정리할 것인지는 직접 판단하세요.')
+    }
     L.push('')
     L.push(renderNpxSection())
     return L.join('\n')
@@ -477,7 +501,7 @@ export function renderPlan(plan: UninstallPlan): string {
   L.push('')
 
   L.push('## 4. 되돌리는 방법 (아래 명령은 직접 실행하세요)')
-  L.push(...renderRevertSection(plan))
+  L.push(...renderRevertSection(plan, plan.revertDropsWorkflowGitignore))
   L.push('')
 
   L.push('## 5. 런타임 패키지 제거 (Stage B)')
@@ -485,8 +509,13 @@ export function renderPlan(plan: UninstallPlan): string {
   L.push('')
 
   L.push('## 6. 잔여물 경고')
+  // 🔴 REQ-2026-058 F-7: `scripts/`는 **Stage A(vendored) 설치본에만** 존재한다. Stage B init은 실행 코드를
+  //    복사하지 않으므로 그 디렉터리가 애초에 생기지 않는다 — 나열하면 없는 잔여물을 찾게 만든다.
+  //    `unknownKitFiles`/tool 분류에 kit 디렉터리 흔적이 있을 때만 언급한다.
+  const hasVendoredDir = facts.tool.some((t) => t.present && t.path.startsWith(`${KIT_SOURCE_DIR_REL}/`)) || facts.unknownKitFiles.length > 0
+  const emptyDirs = [...(hasVendoredDir ? [`${KIT_SOURCE_DIR_REL}/`] : []), `${facts.ticketRoot}/`, '.claude/', '.cursor/']
   L.push('   - git은 빈 디렉터리를 추적하지 않습니다. 위 파일을 지운 뒤 `git status`가 clean이어도')
-  L.push(`     빈 디렉터리(scripts/ · ${facts.ticketRoot}/ · .claude/ · .cursor/)가 파일시스템에 남을 수 있습니다.`)
+  L.push(`     빈 디렉터리(${emptyDirs.join(' · ')})가 파일시스템에 남을 수 있습니다.`)
   L.push('   - node_modules의 ajv · cross-spawn · tsx 는 다른 패키지도 쓸 수 있어 제거를 권하지 않습니다.')
   L.push('')
 
@@ -518,7 +547,37 @@ function renderRuntimeRemovalSection(plan: UninstallPlan): string[] {
   return L
 }
 
-function renderRevertSection(plan: UninstallPlan): string[] {
+/**
+ * revert가 `workflow/.gitignore`를 함께 되돌려 **기존 티켓 scratch가 드러나는** 파급을 경고할 것인가
+ * (REQ-2026-058 F-6).
+ *
+ * 두 조건이 모두 참일 때만 낸다:
+ *   1. 그 도입 커밋이 실제로 `KIT_GITIGNORE.dest`를 담고 있다(git이 오라클 — 추측하지 않는다).
+ *   2. 보존해야 할 티켓 증거가 있다(`plan.protect`). 증거가 없으면 드러날 scratch도 없어 경고가 소음이다.
+ *
+ * 이 경고가 없으면 계획이 스스로 모순된다 — §3은 "증거 디렉터리를 보존하라"고 하면서 §4는 그 디렉터리의
+ * 무시 규칙을 지우는 명령을 권하게 된다(Nuxt 소비자 감사에서 scratch 5건 노출로 실측).
+ */
+function revertDropsWorkflowGitignoreCheck(commits: readonly ScaffoldCommit[], git: GitAdapter): boolean {
+  for (const c of commits) {
+    let names: string
+    try {
+      names = git.exec(['show', '--pretty=format:', '--name-only', c.sha])
+    } catch {
+      continue // 조회 실패는 경고 근거로 삼지 않는다(읽기 전용 planner — 추측 금지)
+    }
+    if (
+      names
+        .split('\n')
+        .map((l) => l.trim())
+        .includes(KIT_GITIGNORE.dest)
+    )
+      return true
+  }
+  return false
+}
+
+function renderRevertSection(plan: UninstallPlan, gitignoreWarning: boolean): string[] {
   const L: string[] = []
   const { facts } = plan
 
@@ -535,6 +594,13 @@ function renderRevertSection(plan: UninstallPlan): string[] {
       for (const c of plan.scaffoldCommits) L.push(`     ${c.sha}  ${c.subject}`)
       L.push('   각 커밋의 내용을 확인한 뒤(`git show <sha>`) 되돌릴 범위를 직접 정하세요.')
     }
+    if (gitignoreWarning) {
+      L.push(`   ⚠️ 이 커밋에는 ${KIT_GITIGNORE.dest} 가 들어 있습니다 — revert하면 그 파일도 함께 사라집니다.`)
+      L.push('      그러면 위 3번의 티켓 안 scratch(codex-response.json · .review-preview.txt · .review-calls.jsonl)가')
+      L.push('      무시되지 않아 `git status`에 드러납니다. 둘 중 하나를 고르십시오:')
+      L.push(`        - 증거를 계속 쓸 것이면: revert 뒤 ${KIT_GITIGNORE.dest} 를 복원하거나 그 규칙을 루트 .gitignore로 옮기십시오.`)
+      L.push('        - 티켓 증거까지 정리할 것이면: 그 scratch 파일들도 함께 지우십시오(그때는 노출이 문제가 아닙니다).')
+    }
     if (plan.mode === 'mixed') L.push('   일부 파일은 아직 커밋되지 않았습니다 — 아래 미커밋 절차도 함께 보세요.')
   }
 
@@ -565,6 +631,9 @@ function renderNpxSection(): string {
     '   `npx commitgate`는 전역 설치가 아닙니다. 패키지는 npm 캐시의 `_npx/<hash>/`에만 들어갑니다.',
     '     확인          : npm ls -g commitgate      (비어 있으면 전역 설치 아님)',
     '     전역이었다면  : npm uninstall -g commitgate',
+    // 🔴 REQ-2026-058 F-9: 이 명령의 범위를 밝힌다 — CommitGate만 지우는 것이 **아니다**.
+    '   ⚠️ 아래 명령은 CommitGate 것만이 아니라 이 사용자가 npx 로 실행한 모든 패키지 캐시를 삭제합니다.',
+    '      CommitGate만 정리하려면 `_npx/<hash>/` 중 해당 항목만 골라 지우십시오(선택적 · 필수 아님).',
     '   캐시에 남은 npx 패키지 정리:',
     '     Windows (PowerShell) : Remove-Item -Recurse -Force "$(npm config get cache)\\_npx"',
     '     macOS / Linux        : rm -rf "$(npm config get cache)/_npx"',

package/package.json

@@ -1,76 +1,76 @@
-{
-  "name": "commitgate",
-  "version": "0.9.8",
-  "description": "CommitGate — Builder↔Reviewer(Claude↔Codex) fail-closed 커밋 게이트: 리뷰·승인·증거 없인 커밋을 통과시키지 않는 AI REQ 워크플로 kit (req:new/next/review-codex/doctor/commit)",
-  "type": "module",
-  "license": "MIT",
-  "author": "sol5288",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/sol5288/commitgate.git"
-  },
-  "homepage": "https://github.com/sol5288/commitgate#readme",
-  "bugs": {
-    "url": "https://github.com/sol5288/commitgate/issues"
-  },
-  "keywords": [
-    "ai",
-    "code-review",
-    "workflow",
-    "codex",
-    "claude",
-    "git",
-    "commit-gate",
-    "fail-closed",
-    "review-gate",
-    "cli"
-  ],
-  "bin": {
-    "commitgate": "bin/commitgate.mjs"
-  },
-  "scripts": {
-    "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",
-    "verify:overrides": "node scripts/verify-review-overrides.mjs",
-    "docs:lint": "remark docs README.md README.en.md --quiet --frail"
-  },
-  "files": [
-    "scripts/req",
-    "scripts/verify-review-overrides.mjs",
-    "workflow/machine.schema.json",
-    "workflow/req.config.schema.json",
-    "workflow/review-persona.md",
-    "bin",
-    "templates",
-    "skills",
-    "AGENTS.template.md",
-    "req.config.json.sample",
-    "README.md",
-    "README.en.md",
-    "CHANGELOG.md"
-  ],
-  "engines": {
-    "node": ">=18.17"
-  },
-  "dependencies": {
-    "ajv": "^8.20.0",
-    "cross-spawn": "^7.0.6",
-    "semver": "^7.6.3",
-    "tsx": "^4.19.1"
-  },
-  "devDependencies": {
-    "@types/cross-spawn": "^6.0.6",
-    "@types/node": "^22.7.4",
-    "@types/semver": "^7.5.8",
-    "remark-cli": "^12.0.1",
-    "remark-validate-links": "^13.1.0",
-    "typescript": "^5.6.2",
-    "vitest": "^2.1.2"
-  }
-}
+{
+  "name": "commitgate",
+  "version": "0.9.10",
+  "description": "CommitGate — Builder↔Reviewer(Claude↔Codex) fail-closed 커밋 게이트: 리뷰·승인·증거 없인 커밋을 통과시키지 않는 AI REQ 워크플로 kit (req:new/next/review-codex/doctor/commit)",
+  "type": "module",
+  "license": "MIT",
+  "author": "sol5288",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sol5288/commitgate.git"
+  },
+  "homepage": "https://github.com/sol5288/commitgate#readme",
+  "bugs": {
+    "url": "https://github.com/sol5288/commitgate/issues"
+  },
+  "keywords": [
+    "ai",
+    "code-review",
+    "workflow",
+    "codex",
+    "claude",
+    "git",
+    "commit-gate",
+    "fail-closed",
+    "review-gate",
+    "cli"
+  ],
+  "bin": {
+    "commitgate": "bin/commitgate.mjs"
+  },
+  "scripts": {
+    "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",
+    "verify:overrides": "node scripts/verify-review-overrides.mjs",
+    "docs:lint": "remark docs README.md README.en.md --quiet --frail"
+  },
+  "files": [
+    "scripts/req",
+    "scripts/verify-review-overrides.mjs",
+    "workflow/machine.schema.json",
+    "workflow/req.config.schema.json",
+    "workflow/review-persona.md",
+    "bin",
+    "templates",
+    "skills",
+    "AGENTS.template.md",
+    "req.config.json.sample",
+    "README.md",
+    "README.en.md",
+    "CHANGELOG.md"
+  ],
+  "engines": {
+    "node": ">=18.17"
+  },
+  "dependencies": {
+    "ajv": "^8.20.0",
+    "cross-spawn": "^7.0.6",
+    "semver": "^7.6.3",
+    "tsx": "^4.19.1"
+  },
+  "devDependencies": {
+    "@types/cross-spawn": "^6.0.6",
+    "@types/node": "^22.7.4",
+    "@types/semver": "^7.5.8",
+    "remark-cli": "^12.0.1",
+    "remark-validate-links": "^13.1.0",
+    "typescript": "^5.6.2",
+    "vitest": "^2.1.2"
+  }
+}

package/scripts/req/lib/adapters.ts

@@ -46,6 +46,38 @@ export function safeSpawnSync(file: string, args: readonly string[], opts: SafeS
   return res.stdout ? res.stdout.toString('utf8') : ''
 }
 
+/**
+ * `safeSpawnSync`의 **exit code 보존** 변형 (REQ-2026-050 D5).
+ *
+ * `safeSpawnSync`는 non-zero를 전부 실패로 보고 throw한다. 그러나 **non-zero가 정상 신호**인 명령이 있다 —
+ * `git diff --no-index`는 두 파일 내용이 다르면 exit **1**을 낸다(정상 결과이지 오류가 아니다).
+ * 그런 명령에 `safeSpawnSync`를 쓰면 정상 결과를 오류로 오판한다.
+ *
+ * 🔴 **새 spawn 경로를 만드는 것이 아니다.** shell 없는 `cross-spawn` 단일 경로(주입 차단 경계)를 그대로
+ *    재사용하고, 달라지는 것은 **exit code 해석을 호출자에게 넘긴다**는 것뿐이다. 어떤 code가 정상인지는
+ *    명령마다 다르므로 여기서 정책을 갖지 않는다.
+ *
+ * spawn 자체의 실패(`res.error` — 예: git 부재 ENOENT)는 여기서도 throw한다. 그건 code 해석의 문제가 아니다.
+ */
+export function safeSpawnSyncStatus(
+  file: string,
+  args: readonly string[],
+  opts: SafeSpawnOptions = {},
+): { status: number | null; stdout: string; stderr: string } {
+  const res = spawn.sync(file, args as string[], {
+    cwd: opts.cwd,
+    input: opts.input,
+    stdio: opts.stdio ?? 'pipe',
+    maxBuffer: opts.maxBuffer ?? 64 * 1024 * 1024,
+  })
+  if (res.error) throw res.error
+  return {
+    status: res.status,
+    stdout: res.stdout ? res.stdout.toString('utf8') : '',
+    stderr: res.stderr ? res.stderr.toString('utf8') : '',
+  }
+}
+
 // ──────────────────────────────────────────────────────────── Git ──
 
 /** git 호출 경계(D-017-3). exec(args) = trim된 stdout, 실패 시 throw(fail-closed). */
@@ -57,6 +89,20 @@ export interface GitAdapter {
 export type GitRunner = (file: string, args: string[], opts: { cwd: string; encoding: 'utf8'; maxBuffer: number }) => string
 const defaultGitRunner: GitRunner = (file, args, opts) => execFileSync(file, args, opts)
 
+/**
+ * **부재가 정상인 조회** 전용 runner — git의 stderr를 버린다 (REQ-2026-058 F-5).
+ *
+ * `git show HEAD:<path>` 류는 "아직 커밋되지 않음"이 **정상 상태**이고 호출부가 `catch → null`로 처리한다.
+ * 그런데 `execFileSync`는 기본적으로 자식 stderr를 부모로 흘리므로, 정상 경로에서
+ * `fatal: path '…' does not exist in 'HEAD'`가 사용자 화면에 뜬다 — 실패로 오해된다(Nuxt 소비자 감사 실측).
+ *
+ * 🔴 **전역으로 쓰지 말 것.** 진짜 오류(권한·손상·잠금)의 진단까지 사라진다. `bin/init.ts`의
+ *    `assertGitWorkTree`가 probe 전용 quiet runner를 쓰는 것과 같은 좁은 용도다.
+ * ⚠️ 판정은 바뀌지 않는다 — 실패는 여전히 throw이고 호출부의 `catch`가 부재로 해석한다.
+ */
+export const quietGitRunner: GitRunner = (file, args, opts) =>
+  execFileSync(file, args, { ...opts, stdio: ['ignore', 'pipe', 'ignore'] })
+
 /** git stdout 상한 — codex 경로(safeSpawnSync)와 동일 64 MiB. 큰 staged diff/status에서 Node 기본 1 MiB의 ENOBUFS throw 방지. */
 const GIT_MAX_BUFFER = 64 * 1024 * 1024
 
@@ -106,12 +152,48 @@ export function parseThreadId(jsonl: string): string | null {
   return null
 }
 
-/** codex 실행자(주입 가능 — 테스트). stdout 반환, 실패 시 throw. */
+/**
+ * 리뷰 호출 실패의 **타입된 분류**(REQ-2026-054·DEC-C1). 예산 환불·lifecycle 판정이 메시지 문자열 sniffing이
+ * 아니라 이 타입으로 결정된다.
+ * - `pre-dispatch`: reviewer subprocess가 **기동조차 못 함**(spawn 실패·ENOENT). 청구 불가 → 환불 대상.
+ * - `dispatched`: subprocess는 떴으나 사용 가능한 결과 없음(non-zero exit·thread_id 없음). 청구 가능성 → 차감.
+ */
+export class ReviewCallError extends Error {
+  readonly dispatchPhase: 'pre-dispatch' | 'dispatched'
+  constructor(dispatchPhase: 'pre-dispatch' | 'dispatched', message: string) {
+    super(message)
+    this.name = 'ReviewCallError'
+    this.dispatchPhase = dispatchPhase
+  }
+}
+
+/** codex 실행자(주입 가능 — 테스트). stdout 반환, 실패 시 throw(`ReviewCallError`로 dispatch 단계 분류). */
 export type CodexRunner = (args: string[], input: string, cwd: string) => string
-const defaultCodexRunner: CodexRunner = (args, input, cwd) =>
-  // shell 없이 안전 실행(safeSpawnSync/cross-spawn). 프롬프트는 stdin(input)으로 전달.
-  // ⚠️ 과거 `shell:true`는 args(schemaPath·resumeThreadId 등)의 메타문자로 **명령 주입**이 가능했고 공백 경로도 깨졌음 — P1 수정.
-  safeSpawnSync('codex', args, { cwd, input, maxBuffer: 64 * 1024 * 1024 })
+
+/** status 보존 spawn 함수 타입(주입 seam — `safeSpawnSyncStatus` 서명). */
+export type StatusSpawn = (file: string, args: readonly string[], opts?: SafeSpawnOptions) => { status: number | null; stdout: string; stderr: string }
+
+/**
+ * codex 러너 팩토리(REQ-2026-054·DEC-C1). spawn을 주입해 분류 로직을 테스트 가능하게 한다.
+ * - spawn 자체 실패(`res.error` throw — ENOENT 등): subprocess 미기동 = `pre-dispatch`(청구 불가·환불 대상).
+ * - `res.status !== 0`(subprocess는 떴고 non-zero — usage limit 등 모델 부분 실행 가능): `dispatched`(차감).
+ */
+export function makeCodexRunner(spawn: StatusSpawn): CodexRunner {
+  return (args, input, cwd) => {
+    // shell 없이 안전 실행(cross-spawn). 프롬프트는 stdin(input). 과거 `shell:true`의 명령 주입/공백 경로 결함 방지.
+    let res: { status: number | null; stdout: string; stderr: string }
+    try {
+      res = spawn('codex', args, { cwd, input, maxBuffer: 64 * 1024 * 1024 })
+    } catch (err) {
+      throw new ReviewCallError('pre-dispatch', `codex 실행(spawn) 실패 — subprocess 미기동: ${err instanceof Error ? err.message : String(err)}`)
+    }
+    if (res.status !== 0)
+      throw new ReviewCallError('dispatched', `codex 종료 코드 ${res.status ?? 'null'}: ${res.stderr.trim()}`.trim())
+    return res.stdout
+  }
+}
+
+const defaultCodexRunner: CodexRunner = makeCodexRunner(safeSpawnSyncStatus)
 
 /** unknown → 평범한 객체(배열·null 제외). 스키마 경로 탐색용. */
 function asPlainObject(v: unknown): Record<string, unknown> | null {
@@ -202,13 +284,37 @@ export function createCodexReviewerAdapter(run: CodexRunner = defaultCodexRunner
 }
 
 /** 테스트 전용 ReviewerAdapter — canned 응답 반환 + 받은 요청 기록(live codex 없이 review-codex 플로 검증, 수용기준 #4). */
-export function createFakeReviewerAdapter(result: ReviewResult): ReviewerAdapter & { requests: ReviewRequest[] } {
+export function createFakeReviewerAdapter(
+  result: ReviewResult,
+  opts: {
+    /**
+     * REQ-2026-052: `true`(기본)면 응답의 `review_base_sha`를 **프롬프트의 `REVIEW_BASE_SHA`로 덮어쓴다**.
+     * pre-call 원장 커밋이 HEAD를 옮겨 실제 approval base가 테스트 setup 시점의 head와 달라지므로, 고정
+     * canned 응답의 base가 stale해진다. 프롬프트 base를 echo하면 near-e2e가 그 커밋을 신경 쓰지 않아도 된다.
+     * base 불일치(invalid)를 **의도적으로** 테스트하려면 `echoPromptBase:false`로 끈다.
+     */
+    echoPromptBase?: boolean
+  } = {},
+): ReviewerAdapter & { requests: ReviewRequest[] } {
   const requests: ReviewRequest[] = []
+  const echo = opts.echoPromptBase !== false
   return {
     requests,
     review(req: ReviewRequest): ReviewResult {
       requests.push(req)
-      return result
+      if (!echo) return result
+      // 프롬프트에서 `REVIEW_BASE_SHA: <sha>` 추출.
+      const m = /^REVIEW_BASE_SHA:\s*([0-9a-f]{7,64})\s*$/m.exec(req.prompt)
+      if (!m) return result
+      let parsed: unknown
+      try {
+        parsed = JSON.parse(result.lastMessage)
+      } catch {
+        return result // JSON이 아니면 손대지 않는다.
+      }
+      if (!parsed || typeof parsed !== 'object' || !('review_base_sha' in parsed)) return result
+      const patched = { ...(parsed as Record<string, unknown>), review_base_sha: m[1] }
+      return { ...result, lastMessage: JSON.stringify(patched) }
     },
   }
 }

package/scripts/req/lib/close-migrate.ts

@@ -0,0 +1,135 @@
+/**
+ * `req:close --migrate`의 **순수 판정기** (REQ-2026-053·DEC-M3/M7).
+ *
+ * close-proof/`phase_design_ref` regime **이전에** 완료·병합돼 dev-complete로 자기증명될 수 없는 레거시
+ * durable 티켓을, HEAD-committed 증거만으로 마이그레이션 종결 자격을 판정한다. IO는 호출부(`req-close.ts`)가 낸다 —
+ * 이 모듈은 fs·git을 모른다(`lib/close-proof`·`lib/reconstruct`와 같은 태도).
+ *
+ * 🔴 자격은 좁다: **손상 아님 + durable + 커밋된 design 승인 + phase 증거 ≥1 + 정상 dev-complete 불가 +
+ *    integrated(본선 병합)**. 하나라도 어긋나면 fail-closed 거부. 이미 종결이면 거부가 아니라 성공 no-op(멱등).
+ *
+ * 🔴 **`migrated-complete` close 이벤트·기본 상태·파서·`deriveBaseState` 확장(dev-complete 아래·needs-recovery
+ *    위 비차단)은 phase-1(커밋 `3ed1b95` `close-proof.ts`)에 이미 landed.** 이 모듈(phase-2)은 그 이벤트를
+ *    **발행할지 판정**만 한다. 종결→intake pass 전 파이프라인은 `req-close.test.ts` ⑮가 실 git으로 실증한다.
+ */
+import type { CloseProofRow, CloseProofEvent } from './close-proof'
+
+/** 판정 입력 — 전부 HEAD-committed 사실 + integrated(git ancestry, 호출부가 계산). */
+export interface MigrationFacts {
+  ticketId: string
+  ticketRel: string
+  /** HEAD scaffold marker(`isDurabilityRequired`). false면 legacy. */
+  durabilityRequired: boolean
+  /** HEAD approvals.jsonl 본문(없으면 null). */
+  manifestText: string | null
+  /** `validateManifest` 결과(빈 배열=정상). 비어있지 않으면 corrupt 거부. */
+  manifestProblems: readonly string[]
+  /** HEAD ticket-close.jsonl 파싱 problems. 비어있지 않으면 corrupt 거부. */
+  closeProblems: readonly string[]
+  /** HEAD ticket-close.jsonl 파싱 행(이미 종결 여부 판정). */
+  closeRows: readonly CloseProofRow[]
+  /** committed 증거(design+phase) 무결성 problems(DEC-B6·B7). 비어있지 않으면 corrupt 거부. */
+  evidenceIntegrityProblems: readonly string[]
+  /** 커밋된 design 승인 참조(design_hash). 없으면 null. */
+  committedDesignRef: string | null
+  /** 매니페스트의 **모든** phase-evidenced id(결속 무관). 완료 inventory 원천. */
+  evidencedPhaseIdsAll: readonly string[]
+  /** **현재 design_ref에 결속된** phase id(정상 dev-complete 가능성 판정). */
+  evidencedPhaseIdsBound: readonly string[]
+  /**
+   * 🔴 티켓의 **커밋된 phase 계획**(HEAD state.json `phases[].id`). r02 P1 대응 — integrated(마지막 매니페스트
+   *    커밋이 본선 조상)만으로는 "앞 phase만 병합되고 뒷 phase가 진행 중/중단"인 부분 완료를 못 거른다.
+   *    커밋된 계획이 있으면 그 **모든** phase가 증거로 있어야 완료로 본다. 계획이 비었으면(레거시 스캐폴드
+   *    state.phases=[]) 이 검사는 vacuous — dev-completable(결속) 검사와 integrated가 남은 방어다.
+   */
+  committedPlannedPhaseIds: readonly string[]
+  /** 티켓 증거가 본선(mainline)의 조상인가(완료성 증명 — DEC-M3.7). 호출부가 git ancestry로 계산. */
+  integrated: boolean
+  /** 발행 시각(ISO, 호출부가 실시계로 넣음). */
+  nowIso: string
+  /** 발행 행의 evidence_basis(마이그레이션 근거 아티팩트 경로 — 비어있으면 안 됨). */
+  evidenceBasis: readonly string[]
+}
+
+export type MigrationPlan =
+  | { kind: 'stamp'; row: CloseProofRow }
+  /** 이미 terminal close(dev-complete/series-terminal/migrated-complete) — 성공 no-op(DEC-M7). */
+  | { kind: 'noop'; existingState: CloseProofEvent }
+  /** 자격 미달 — fail-closed 거부(비-스탬프). */
+  | { kind: 'refuse'; reason: string; hint: string }
+
+function refuse(reason: string, hint: string): MigrationPlan {
+  return { kind: 'refuse', reason, hint }
+}
+
+/**
+ * 마이그레이션 종결 계획(순수·DEC-M3/M7). 판정 순서가 계약이다:
+ * corrupt 가드 → durability → **이미 종결이면 no-op** → design 승인 → phase 증거 → 정상 dev-complete 불가 →
+ * integrated. 마지막에만 stamp.
+ */
+export function planMigrationClose(f: MigrationFacts): MigrationPlan {
+  // 🔴 corrupt 가드 — pass 조건이 읽는 아티팩트가 손상됐으면 완료를 스탬프하지 않는다(fail-closed).
+  if (f.manifestText !== null && f.manifestProblems.length)
+    return refuse(`HEAD approvals.jsonl 손상: ${f.manifestProblems.slice(0, 3).join('; ')}`, '손상 증거에는 완료를 스탬프하지 않습니다 — 먼저 정정/복구')
+  if (f.closeProblems.length)
+    return refuse(`HEAD ticket-close.jsonl 손상: ${f.closeProblems.slice(0, 3).join('; ')}`, '손상 close-proof 정리 후 재시도')
+  if (f.evidenceIntegrityProblems.length)
+    return refuse(`committed 증거(design·phase archive) 손상/부재: ${f.evidenceIntegrityProblems.slice(0, 3).join('; ')}`, 'req:reconstruct 등으로 복구 후 재시도')
+
+  // durability marker 없음 = legacy → intake가 애초에 차단하지 않으므로 종결 불필요.
+  if (!f.durabilityRequired)
+    return refuse('legacy 티켓(durability marker 없음) — intake가 차단하지 않아 종결이 불필요', '조치 불필요')
+
+  // 🔴 DEC-M7: 이미 terminal close면 거부가 아니라 성공 no-op(재실행 멱등). 다른 검사보다 앞에 둬 재실행이
+  //    깨끗한 no-op이 되게 한다(기존 행의 at을 보존).
+  const terminal = f.closeRows.find(
+    (r) => r.event === 'series-terminal' || r.event === 'dev-complete' || r.event === 'migrated-complete',
+  )
+  if (terminal) return { kind: 'noop', existingState: terminal.event }
+
+  // 커밋된 design 승인 — 무엇에 대한 완료인지 불명이면 거부.
+  if (f.committedDesignRef === null)
+    return refuse('커밋된 design 승인(design_hash)이 없다 — 무엇에 대한 완료인지 불명', 'design 승인 증거 없이 마이그레이션 불가')
+
+  // phase 증거 ≥1 — 실제 phase를 거친 티켓만.
+  const inventory = [...new Set(f.evidencedPhaseIdsAll)].sort()
+  if (inventory.length === 0)
+    return refuse('커밋된 phase 증거가 없다 — 실제 phase를 거친 티켓만 마이그레이션', 'phase 리뷰·커밋을 먼저 완료')
+
+  // 🔴 r02 P1: **부분 완료(진행 중/중단) 배제** — 커밋된 phase 계획(state.phases)이 있으면 그 모든 phase가
+  //    증거로 있어야 한다. integrated는 "마지막 매니페스트 커밋이 본선 조상"만 봐서, 앞 phase만 병합되고 뒤
+  //    phase가 아직 증거를 안 낸 티켓을 통과시킨다 — 이 committed 계획 검사가 그 틈을 닫는다.
+  const evidencedSet = new Set(inventory)
+  const missingPlanned = f.committedPlannedPhaseIds.filter((id) => !evidencedSet.has(id))
+  if (missingPlanned.length)
+    return refuse(
+      `커밋된 phase 계획 중 증거 없는 phase: ${missingPlanned.join(', ')} — 부분 완료(진행 중/중단) 티켓은 마이그레이션 불가`,
+      '모든 계획 phase를 완료·커밋(정상 dev-complete)하거나 종결한 뒤 재시도',
+    )
+
+  // 🔴 정상 dev-complete가 가능하면 거부 — 마이그레이션으로 강한 경로를 우회하지 않는다(DEC-M3.6).
+  const bound = new Set(f.evidencedPhaseIdsBound)
+  if (inventory.every((id) => bound.has(id)))
+    return refuse('phase 증거가 현재 design_ref에 전부 결속됨 — 정상 dev-complete 가능', '`req:commit --finalize --run`(정상 완료 경로)을 사용')
+
+  // 🔴 완료성 증명 = integrated(DEC-M3.7·P1-1) — 본선 미병합이면 진행 중일 수 있어 거부.
+  if (!f.integrated)
+    return refuse('티켓 작업이 본선(mainline)에 병합되지 않음 — 미완료/진행 중 가능성', '완료·병합 후 재시도(마이그레이션은 병합된 완료 티켓만)')
+
+  // 방어: evidence_basis 비어있으면 스키마 위반(reconstructed:true는 근거 필수). 호출부가 항상 채운다.
+  if (f.evidenceBasis.length === 0)
+    return refuse('evidence_basis가 비어 있음(내부 오류 — 마이그레이션 근거 경로 미제공)', '버그 신고')
+
+  const row: CloseProofRow = {
+    ticket_id: f.ticketId,
+    event: 'migrated-complete',
+    series_id: null,
+    resolution: null,
+    phase_inventory: inventory,
+    design_ref: f.committedDesignRef,
+    at: f.nowIso,
+    reconstructed: true,
+    evidence_basis: [...f.evidenceBasis],
+  }
+  return { kind: 'stamp', row }
+}