commitgate 0.9.6 → 0.9.9

package/scripts/req/req-doctor.ts

@@ -12,7 +12,10 @@ 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 { isAllowedResponsesScratch, reviewScratchPaths } from './lib/scratch'
+// REQ-2026-048 phase-1: confinement 술어는 leaf `lib/evidence.ts`가 정본 — 여기서 재수출(기존 경로 보존).
+import { isConfinedArchivePath } from './lib/evidence'
+export { isConfinedArchivePath } from './lib/evidence'
 import {
   loadState,
   validateVerdict,
@@ -20,11 +23,12 @@ import {
   findUnstagedOrUntracked,
   captureDesignBinding,
   designDocPaths,
+  REVIEW_CALL_LOG_REL,
   type WorkflowState,
   type Verdict,
   type ApprovalEvidence,
 } from './review-codex'
-import { loadConfig, packageRoot, stripBom, DEFAULTS, type ResolvedConfig } from './lib/config'
+import { loadConfig, packageRoot, stripBom, DEFAULTS, type ResolvedConfig, type PackageManager } from './lib/config'
 import { createGitAdapter, type GitAdapter } from './lib/adapters'
 import { missingQuickstartFiles } from '../../bin/quickstart'
 
@@ -98,6 +102,18 @@ export interface DoctorInputs {
   //   undefined = 미계산(2-arg/legacy) → OK. [] = 없음/최신/대상없음 → OK. 비어있지 않음 → WARN.
   //   dev/dogfood(packageRootDiffers===false)면 D20처럼 skip. optional이어야 테스트 base 리터럴이 안 깨진다.
   quickstartMissing?: string[]
+  // D22(REQ-2026-047): repo-root 런타임 스크래치 경로 중 **ignore도 tracked도 아닌** 것(= 다음 review가 만들면 D10이 막는 것).
+  //   런타임이 소비 repo 루트에 만드는 스크래치(현재 `workflow/.review-calls.jsonl`)는 티켓 밖이라 `/REQ-*/` 앵커에
+  //   걸리지 않고 `reviewScratchPaths` 허용목록에도 없다 → **gitignore가 유일한 방어**다. 0.9.6 이하 설치본은 배포
+  //   템플릿에 그 규칙이 없어, 첫 리뷰 뒤 D10 FAIL로 커밋이 전부 막혔다.
+  //   undefined = 미계산(2-arg/legacy) → OK. [] = 전부 보호됨 → OK. 비어있지 않음 → WARN.
+  //   dev/dogfood(packageRootDiffers===false)면 D20/D21처럼 skip. optional이어야 테스트 base 리터럴이 안 깨진다.
+  repoRootScratchUnprotected?: string[]
+  // D23(REQ-2026-056): frozen-lockfile 위생. 감지된 PM의 lockfile이 없거나 untracked면 재현 가능한 설치
+  //   (`<pm> ci`/`--frozen-lockfile`)가 불가하다. undefined = 미계산(2-arg/legacy) → OK.
+  //   'no-package-json'/'ok' → OK. 'missing'/'untracked' → **WARN**(FAIL 아님 — D19~D22 근거 동일).
+  //   optional이어야 테스트 base 리터럴이 안 깨진다.
+  lockfileStatus?: 'ok' | 'missing' | 'untracked' | 'no-package-json'
 }
 
 /**
@@ -190,20 +206,9 @@ export interface ArchiveCheck {
   structureOk: boolean
 }
 
-/**
- * evidence `response_path`가 **현재 티켓 `responses/` 직계 아카이브**인지(D-016 confinement).
- * 절대경로·`..`·다른 티켓·중첩경로·`approvals.jsonl` 등 비아카이브는 거부. ticketRel 미지정 시 false(fail-closed).
- */
-export function isConfinedArchivePath(p: string, ticketRel: string | undefined): boolean {
-  if (!ticketRel || typeof p !== 'string' || !p) return false
-  const norm = p.replace(/\\/g, '/')
-  if (norm.includes('..') || norm.startsWith('/') || /^[a-zA-Z]:\//.test(norm)) return false
-  const prefix = `${ticketRel.replace(/\\/g, '/').replace(/\/+$/, '')}/responses/`
-  if (!norm.startsWith(prefix)) return false
-  const name = norm.slice(prefix.length)
-  if (!name || name.includes('/')) return false
-  return isArchiveFileName(name)
-}
+// `isConfinedArchivePath`는 REQ-2026-048 phase-1에서 `lib/evidence.ts`로 이동했다 — 매니페스트 검증이
+// 같은 술어를 쓰는데 여기 두면 `lib/evidence → req-doctor` 런타임 간선이 생겨 순환이 된다. 아래 re-export로
+// 기존 import 경로(`from './req-doctor'`)를 보존한다.
 
 /**
  * 승인 증거(evidence)와 그 아카이브 파일의 정합 문제 목록(순수, A2/D-016-5).
@@ -482,6 +487,52 @@ export function runChecks(inp: DoctorInputs): Check[] {
     })
   }
 
+  // D22(REQ-2026-047): repo-root 런타임 스크래치가 ignore도 tracked도 아님 → 다음 review 뒤 D10이 커밋을 막는다.
+  //
+  // 🔴 **level 상한은 WARN — 절대 FAIL이 아니다**(D19:425-428·D20:443-447·D21과 동일 근거). `req:commit`이 이 doctor를
+  //    exit≠0에 throw하는 하드 게이트로 spawn하므로, FAIL이면 백필 전까지 소비자의 모든 커밋이 벽돌이 된다.
+  //    더구나 이 드리프트는 **이미** D10 FAIL로 발현한다 — 신규 진단이 차단을 만드는 것이 아니라, 불투명한
+  //    `D10: unstaged/untracked workflow/.review-calls.jsonl`을 **행동 가능한 안내로 번역**하는 것이 역할이다.
+  //
+  // tracked인 경우는 여기서 경고하지 않는다(이미 커밋된 상태 = 다른 문제). 그 복구는 `git rm --cached` 절차로
+  //    troubleshooting 문서가 다룬다 — ignore 규칙만 넣어서는 tracked 파일이 빠지지 않기 때문이다.
+  if (inp.packageRootDiffers === false) {
+    c.push({ id: 'D22', level: 'OK', msg: 'repo-root 스크래치 보호 점검 불요(dev repo/dogfood — packageRoot === config root)' })
+  } else if (inp.repoRootScratchUnprotected === undefined) {
+    c.push({ id: 'D22', level: 'OK', msg: 'repo-root 스크래치 보호 점검 불요(2-arg/미계산)' })
+  } else if (inp.repoRootScratchUnprotected.length === 0) {
+    c.push({ id: 'D22', level: 'OK', msg: 'repo-root 런타임 스크래치가 모두 ignore(또는 tracked)됨' })
+  } else {
+    c.push({
+      id: 'D22',
+      level: 'WARN',
+      msg:
+        `${inp.repoRootScratchUnprotected.join(', ')} 이(가) gitignore로 무시되지 않습니다 — ` +
+        '다음 review가 이 파일을 만들면 **D10이 FAIL하여 커밋이 막힙니다**. ' +
+        '`commitgate sync --gitignore --apply` 로 배포 템플릿의 누락 규칙을 보강하세요(기존 행은 변경하지 않습니다, REQ-2026-047).',
+    })
+  }
+
+  // D23(REQ-2026-056): frozen-lockfile 위생 진단.
+  //
+  // 🔴 **level 상한은 WARN — 절대 FAIL이 아니다**(D19~D22와 동일 근거). `req:commit`이 doctor를 하드 게이트로
+  //    spawn하므로 FAIL이면 lockfile 없는 프로젝트의 모든 커밋이 벽돌이 된다. lockfile ↔ package.json 동기
+  //    여부는 검사하지 않는다(PM 실행 없이 신뢰 불가) — 존재·tracked 위생만.
+  if (inp.lockfileStatus === undefined || inp.lockfileStatus === 'ok') {
+    c.push({ id: 'D23', level: 'OK', msg: inp.lockfileStatus === undefined ? 'lockfile 위생 점검 불요(미계산)' : 'lockfile 존재·git-tracked — 재현 가능한 설치(--frozen-lockfile) 가능' })
+  } else if (inp.lockfileStatus === 'no-package-json') {
+    c.push({ id: 'D23', level: 'OK', msg: 'lockfile 위생 점검 불요(package.json 없음)' })
+  } else {
+    c.push({
+      id: 'D23',
+      level: 'WARN',
+      msg:
+        inp.lockfileStatus === 'missing'
+          ? '감지된 패키지 매니저의 lockfile이 없습니다 — 재현 가능한 설치(`<pm> ci` / `--frozen-lockfile`)가 불가합니다. lockfile을 생성·커밋하세요.'
+          : 'lockfile이 git-tracked가 아닙니다(untracked) — 재현 가능한 설치가 불가합니다. lockfile을 커밋하세요.',
+    })
+  }
+
   return c
 }
 
@@ -583,6 +634,38 @@ export function safeSha256(abs: string): string | null {
   }
 }
 
+/**
+ * D22(REQ-2026-047): repo-root 런타임 스크래치 중 **ignore도 tracked도 아닌** 경로.
+ *
+ * 판정은 **로컬 git 상태 그대로**다(전역 excludes 포함) — D10이 보는 `git status`와 같은 기준이어야
+ * "다음 review 뒤 D10이 막는다"는 예측이 맞는다. 파일이 아직 없어도 `check-ignore`는 패턴 매칭이라
+ * 동작한다(그래서 **첫 리뷰 전에 미리** 경고할 수 있다 — 이 검사의 존재 이유).
+ *
+ * 읽기 전용 advisory라 어떤 오류도 삼킨다(조회 실패 = 보호됨으로 간주 → WARN 안 냄. fail-safe: 게이트를 막지 않는다).
+ */
+export function unprotectedRepoRootScratch(paths: readonly string[], gitFn: (a: string[]) => string): string[] {
+  const out: string[] = []
+  for (const p of paths) {
+    let ignored = false
+    let tracked = false
+    try {
+      gitFn(['check-ignore', '-q', '--', p])
+      ignored = true
+    } catch {
+      ignored = false
+    }
+    if (!ignored) {
+      try {
+        tracked = gitFn(['ls-files', '--', p]).trim() !== ''
+      } catch {
+        tracked = true // 조회 불가 → 보호됨으로 간주(경고하지 않음)
+      }
+    }
+    if (!ignored && !tracked) out.push(p)
+  }
+  return out
+}
+
 /** package.json의 version 문자열. 부재·파손 시 null(D20 WARN 메시지용 — 없어도 무해). */
 function safeReadVersion(pkgAbs: string): string | null {
   try {
@@ -593,6 +676,29 @@ function safeReadVersion(pkgAbs: string): string | null {
   }
 }
 
+/** PM별 기대 lockfile 후보(npm은 둘 다 유효). */
+const LOCKFILES_FOR_PM: Record<PackageManager, string[]> = {
+  npm: ['package-lock.json', 'npm-shrinkwrap.json'],
+  pnpm: ['pnpm-lock.yaml'],
+  yarn: ['yarn.lock'],
+}
+
+/**
+ * frozen-lockfile 위생 판정(D23·REQ-2026-056). package.json 없으면 점검 불요. PM 기대 lockfile이 하나라도
+ * 존재+tracked면 ok, 존재하나 전부 untracked면 untracked, 하나도 없으면 missing.
+ * 🔴 lockfile↔package.json **동기 검사는 안 한다**(PM 실행 없이 신뢰 불가) — 존재·tracked 위생만.
+ */
+export function lockfileHygiene(
+  root: string,
+  pm: PackageManager,
+  isTracked: (rel: string) => boolean,
+): 'ok' | 'missing' | 'untracked' | 'no-package-json' {
+  if (!existsSync(join(root, 'package.json'))) return 'no-package-json'
+  const present = LOCKFILES_FOR_PM[pm].filter((f) => existsSync(join(root, f)))
+  if (present.length === 0) return 'missing'
+  return present.some((f) => isTracked(f)) ? 'ok' : 'untracked'
+}
+
 export function main(argv: string[] = process.argv.slice(2)): void {
   const opts = parseArgs(argv)
   const cfg = loadConfig({ root: opts.root })
@@ -699,6 +805,18 @@ export function main(argv: string[] = process.argv.slice(2)): void {
     schemaPathIsDefault: cfg.schemaPathAbs === resolve(cfg.root, DEFAULTS.schemaPath), // 정규화 절대경로 비교(동치 상대경로 포함)
     installedVersion: safeReadVersion(join(packageRoot(), 'package.json')),
     quickstartMissing: missingQuickstartFiles(cfg.root),
+    // D22(REQ-2026-047): 현재 repo-root 런타임 스크래치 축은 review-call 측정 로그 1건.
+    // 새 축이 생기면 이 배열에 추가하고 packed-consumer smoke 단언도 함께 늘린다(docs 인벤토리 표의 유지 규칙).
+    repoRootScratchUnprotected: unprotectedRepoRootScratch([REVIEW_CALL_LOG_REL], git),
+    // D23(REQ-2026-056): frozen-lockfile 위생(존재·tracked). tracked 판정은 read-only `git ls-files`.
+    lockfileStatus: lockfileHygiene(cfg.root, cfg.packageManager, (rel) => {
+      try {
+        git(['ls-files', '--error-unmatch', '--', rel])
+        return true
+      } catch {
+        return false
+      }
+    }),
   }
 
   const checks = runChecks(inp)

package/scripts/req/req-new.ts

@@ -14,11 +14,12 @@
 import { mkdirSync, writeFileSync, readdirSync, existsSync } from 'node:fs'
 import { join, relative } from 'node:path'
 import { pathToFileURL } from 'node:url'
-import { writeState, loadState, resolveSuccessorLineage, type WorkflowState, type SuccessorOf } from './review-codex'
+import { writeState, loadState, resolveSuccessorLineage, durableParentSeriesTerminal, type WorkflowState, type SuccessorOf } from './review-codex'
 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'
+import { scanIntake, type IntakeTicketResult } from './lib/intake'
 
 // 모든 git 호출은 GitAdapter 경유(D-017-3). main()이 loadConfig 후 config.root로 재생성(기본 = packageRoot — 현재 동작 보존).
 let gitAdapter: GitAdapter = createGitAdapter(packageRoot())
@@ -71,6 +72,24 @@ export function nextStepHint(pm: PackageManager, reqId: string): string {
   return `코드 변경 → git add → ${buildScriptInvocation(pm, 'req:review-codex', [id, '--run']).join(' ')}`
 }
 
+/**
+ * intake 게이트 결과 요약(순수). 차단 티켓 목록·복구 안내 + legacy 표시 문구.
+ * 🔴 `blocked`가 비어있지 않으면 호출부가 fail-closed(throw)한다 — 이 함수는 문구만 만든다.
+ */
+export function renderIntakeSummary(tickets: readonly IntakeTicketResult[]): string {
+  const blocked = tickets.filter((t) => t.verdict === 'block')
+  const legacy = tickets.filter((t) => t.verdict === 'legacy')
+  const lines: string[] = []
+  if (blocked.length) {
+    lines.push('🔴 미종결 durable 티켓이 있어 새 REQ를 만들 수 없습니다(HEAD 커밋 증거 기준):')
+    for (const t of blocked) lines.push(`  - ${t.ticketId}: ${t.baseState} — ${t.reason}`)
+    lines.push('  → 위 티켓을 완료(모든 phase 커밋)·종결하거나 복구한 뒤 다시 시도하세요.')
+    lines.push('    복구가 필요하면 `req:commit <REQ> --finalize --run`(승인 tree==HEAD tree인 미완 evidence 내구화) 등을 사용합니다.')
+  }
+  if (legacy.length) lines.push(`ℹ️  legacy 티켓(표시만, 차단 안 함): ${legacy.map((t) => t.ticketId).join(', ')}`)
+  return lines.join('\n')
+}
+
 export function buildInitialState(reqId: string, branch: string, risk: 'LOW' | 'HIGH', successorOf?: SuccessorOf): WorkflowState {
   return {
     id: reqId,
@@ -89,6 +108,9 @@ export function buildInitialState(reqId: string, branch: string, risk: 'LOW' | '
     phases: [],
     // REQ-016 A1(D-016-6): grandfathering 트리거 — 신규 REQ는 승인 증거를 강제(FAIL), legacy(필드 부재)는 WARN.
     approval_evidence_required: true,
+    // REQ-2026-048 DEC-4: design 증거 내구성 marker. **이 스캐폴드가 커밋되므로 HEAD blob에 영속**한다 —
+    // req:next의 DONE 게이트가 워킹 캐시가 아니라 그 커밋본을 읽어 신규/legacy를 판별한다(캐시 소실로 우회 불가).
+    evidence_durability_required: true,
     // REQ-2026-027 D1: review series 모델 버전. 첫 리뷰 전에도 존재해 "새 ticket(레코드 없음)"과
     // "legacy(필드 부재)"를 구분한다. 필드 부재 = legacy → 새 재리뷰 시 AWAIT_HUMAN/throw(자동 초기화 금지).
     review_series_model_version: 1,
@@ -171,6 +193,7 @@ export function main(argv: string[] = process.argv.slice(2)): void {
   // REQ-2026-029 D3: --successor-of lineage 해소. **branch 생성·mkdir 前**에 검증(design-r01 observation) —
   // 부모 없음·replace 기록 없음·형식 위반이면 여기서 throw해 티켓이 생성되지 않는다(R6 fail-closed).
   let successorOf: SuccessorOf | undefined
+  let parentTerminal: { parentId: string; parentTicketRel: string; parentState: WorkflowState } | undefined
   if (o.successorOf !== null) {
     const parentId = o.successorOf.startsWith('REQ-') ? o.successorOf : `REQ-${o.successorOf}`
     const parentDir = join(cfg.workflowDirAbs, parentId)
@@ -182,8 +205,15 @@ export function main(argv: string[] = process.argv.slice(2)): void {
     }
     // recorded_at은 자식 생성 시각(부모 값 아님). dry-run에선 검증만 하고 값은 버린다.
     successorOf = resolveSuccessorLineage(parentState, parentId, new Date().toISOString())
+    parentTerminal = { parentId, parentTicketRel: relative(cfg.root, parentDir).replace(/\\/g, '/'), parentState }
   }
 
+  // 🔴 REQ-2026-052 phase-3b: intake 게이트 — HEAD-committed durable 증거만으로 기존 티켓을 스캔(read-only).
+  //    대체될 부모(successor)는 정규 replace 흐름으로 종결되므로 제외한다(부모 replace 검증은 위에서 끝났다).
+  //    미종결(developing/needs-recovery)·손상 티켓이 있으면 아래에서 fail-closed. 스캔 자체는 write 없음.
+  const intake = scanIntake(cfg.root, ticketRootRel, (args) => git(args), parentTerminal?.parentId ?? null)
+  const intakeSummary = renderIntakeSummary(intake.tickets)
+
   if (!o.run) {
     console.log('[req:new] DRY-RUN (--run 시 실제 생성)')
     console.log(`  REQ    : ${reqId}`)
@@ -191,9 +221,16 @@ export function main(argv: string[] = process.argv.slice(2)): void {
     console.log(`  ticket : ${ticketRel}/ (state.json·${dd.requirement}·${dd.design}·${dd.plan}·codex-request.md)`)
     console.log(`  risk   : ${o.risk}`)
     if (successorOf) console.log(`  successor_of : ${successorOf.req_id} (부모 ${successorOf.parent_attempts_total}회 · replace 승인 확인)`)
+    if (intakeSummary) console.log(intakeSummary)
+    if (intake.blocked.length) console.log('  ⚠️  위 차단 사유로 --run은 실패합니다.')
     return
   }
 
+  // 🔴 intake 게이트 강제(write 전) — 미종결 durable 티켓이 있으면 티켓 생성 없이 즉시 fail-closed.
+  //    durableParentSeriesTerminal·checkout·티켓 커밋보다 **먼저** 검사해, 차단 시 어떤 write도 하지 않는다.
+  if (intake.blocked.length) throw new Error(renderIntakeSummary(intake.tickets))
+  if (intakeSummary) console.log(intakeSummary) // legacy 표시(차단 없음).
+
   // 클린 트리 요구(새 브랜치 깨끗이 시작 — 의도 변경 섞임 방지).
   // 단, gitignore 규칙이 없는 레거시 설치본도 기존 티켓의 순수 untracked 도구 산출물만 좁게 허용한다(D6·D7).
   const dirtyEntries = findReqNewDirtyEntries(git([...STATUS_Z_ARGS]), ticketRootRel)
@@ -209,6 +246,21 @@ export function main(argv: string[] = process.argv.slice(2)): void {
   const cur = git(['rev-parse', '--abbrev-ref', 'HEAD'])
   if (cur !== 'main') console.warn(`⚠️  현재 브랜치가 main이 아님(${cur}) — REQ는 main에서 시작 권장(DEC-WF-020)`)
 
+  // 🔴 REQ-2026-052 test #3: 부모의 replace/human-resolution 종결을 durable화(ledger + series-terminal
+  //    close proof를 커밋). 브랜치 체크아웃 **전**(현재 브랜치에서) — clean tree는 위에서 확인됐고, 이 커밋이
+  //    부모 종결을 HEAD에 남긴다. 멱등이라 재실행에 중복 없음.
+  if (parentTerminal) {
+    const committed = durableParentSeriesTerminal({
+      root: cfg.root,
+      gitFn: (args) => git(args),
+      parentTicketRel: parentTerminal.parentTicketRel,
+      parentState: parentTerminal.parentState,
+      parentId: parentTerminal.parentId,
+      nowIso: new Date().toISOString(),
+    })
+    if (committed) console.log(`  부모 ${parentTerminal.parentId} series-terminal close proof·ledger 커밋(durable 종결)`)
+  }
+
   git(['checkout', '-b', branch]) // D11/DEC-WF-020: feat/req-* 생성·체크아웃
   mkdirSync(ticketDir, { recursive: true })
   writeState(ticketDir, buildInitialState(reqId, branch, o.risk, successorOf))

package/scripts/req/req-next.ts

@@ -21,8 +21,11 @@ import { resolve, join, relative } from 'node:path'
 import { pathToFileURL } from 'node:url'
 import { loadConfig, buildScriptInvocation, type PackageManager } from './lib/config'
 import { createGitAdapter, type GitAdapter } from './lib/adapters'
+import { isDurabilityRequired, verifyCommittedDesignEvidence } from './lib/evidence'
+import { createEvidencePorts } from './lib/evidence-ports'
 import { parseStatusZ, STATUS_Z_ARGS } from './lib/porcelain'
 import { reviewScratchPaths } from './lib/scratch'
+import { computeReviewSemanticIdentity } from './lib/review-target'
 import {
   loadState,
   readPhases,
@@ -127,13 +130,19 @@ export interface NextInput {
   packageManager: PackageManager
   /** 설계 문서 3종이 git 인덱스에 전부 있는가. */
   designDocsInIndex: boolean
-  /** 현재 설계문서 바인딩 해시. 계산 불가면 null. */
+  /** 현재 설계문서 바인딩 해시(design **freshness** 판정용 — approval binding, compare_hash 아님). 계산 불가면 null. */
   currentDesignHash: string | null
   hasStagedChanges: boolean
   /** G1: `findUnstagedOrUntracked`가 비었는가(리뷰 가능한 워킹트리). */
   worktreeReviewClean: boolean
-  /** 현재 인덱스 전체 해시(`captureIndexHash`). 계산 불가면 null. */
+  /** 현재 인덱스 전체 해시(`captureIndexHash`). 계산 불가면 null. (레거시 경로 호환용 — G2 compare는 아래 semantic identity를 쓴다.) */
   currentIndexHash: string | null
+  /**
+   * 🔴 REQ-2026-052: 현재 **semantic identity**(review-target.ts, `responses/` 제외). G2 compare_hash 재계산 정본.
+   * review-codex가 `last_review.compare_hash`에 semantic identity를 기록하므로, req:next도 같은 값으로 비교한다.
+   * pre-call 원장 커밋·evidence-finalize에 불변이라 방금 승인한 리뷰를 stale로 오판하지 않는다. 계산 불가면 null.
+   */
+  currentSemanticIdentity: string | null
   /** REQ-2026-028 A-2a: review 예산(G3 escalated 판정용). main이 cfg에서 채운다. */
   reviewBudget: ReviewBudget
   /**
@@ -141,6 +150,14 @@ export interface NextInput {
    * 필수 필드다(선택 아님): 해소는 config 계층에서 끝나므로 resolveNext는 내부 기본값을 두지 않는다.
    */
   phaseCommitAutoApprove: PhaseCommitPolicy
+  /**
+   * REQ-2026-048 DEC-4: **커밋된** design 증거 검증 결과. `main()`이 `HEAD` blob으로 계산해 채운다.
+   *
+   * - `undefined` = 미계산(2-arg/legacy 호출) → 기존 DONE 동작 그대로.
+   * - `{ required:false }` = legacy 티켓(HEAD 스캐폴드에 marker 없음) → 기존 DONE 동작 그대로.
+   * - `{ required:true, durable:false }` = 신규 티켓인데 증거가 커밋되지 않음 → **DONE 대신 BLOCKED**.
+   */
+  designEvidenceDurability?: { required: boolean; durable: boolean; reason: string }
 }
 
 /** `consumed_approvals[]`에서 phase_id를 안전하게 읽는다. */
@@ -559,7 +576,7 @@ export function resolveNext(input: NextInput): NextAction {
       command: reviewCmd(pm, target, 'design', null),
       kind: 'design',
       phaseId: null,
-      compareHash: input.currentDesignHash,
+      compareHash: input.currentSemanticIdentity,
       detail: state.design_approved === true ? '설계 문서가 승인 이후 변경됐다(stale). 재승인이 필요하다.' : '설계 승인이 필요하다.',
     })
 
@@ -595,11 +612,32 @@ export function resolveNext(input: NextInput): NextAction {
       command: reviewCmd(pm, target, 'phase', pending),
       kind: 'phase',
       phaseId: pending,
-      compareHash: input.currentIndexHash,
+      compareHash: input.currentSemanticIdentity,
       detail: `phase \`${pending}\`의 staged 변경을 리뷰받는다.`,
     })
   }
 
+  // ── REQ-2026-048 DEC-4: 완료 선언 직전 **커밋된** design 증거 검증(신규 티켓 전용) ──
+  // 🔴 여기서만 fail-closed다. `req:doctor`·일반 `req:commit`에는 넣지 않는다 — doctor는 req:commit의
+  //    하드 게이트라 FAIL이면 기존 소비자의 모든 커밋이 벽돌이 된다. 완료 판정만 막으면 충분하다.
+  // 🔴 온디스크가 아니라 HEAD blob 기준이다(D17이 온디스크로 통과해 이 갭이 조용했다).
+  {
+    const dur = input.designEvidenceDurability
+    if (input.worktreeReviewClean && !input.hasStagedChanges && dur?.required === true && dur.durable !== true) {
+      const cmd = buildScriptInvocation(input.packageManager, 'req:commit', [
+        ...targetArgs(input.target),
+        '--finalize-design',
+        '--run',
+      ]).join(' ')
+      return {
+        kind: 'BLOCKED',
+        detail:
+          `모든 phase가 끝났지만 **커밋된** design 승인 증거가 완비되지 않았다: ${dur.reason}. ` +
+          `이 상태로 통합하면 fresh clone에 설계 승인 감사 증거가 남지 않는다. 복구: \`${cmd}\``,
+      }
+    }
+  }
+
   if (input.worktreeReviewClean && !input.hasStagedChanges) {
     // REQ-2026-037 R5: 자동 커밋(low-only)에선 매 phase 정지가 없으므로, 병합 전 **단일** 사람 확인을
     // 종단에서 실체화한다 — DONE(exit 11)이 아니라 AWAIT_HUMAN(exit 10)으로 루프를 확실히 멈춘다.
@@ -647,7 +685,7 @@ function resolveLegacy(input: NextInput, consumed: { phase_id: string | null }[]
       command: reviewCmd(pm, target, 'phase', null),
       kind: 'phase',
       phaseId: null,
-      compareHash: input.currentIndexHash,
+      compareHash: input.currentSemanticIdentity,
       detail: '레거시 티켓(phase 미추적)의 staged 변경을 리뷰받는다.',
     })
 
@@ -750,8 +788,24 @@ export function main(argv: string[] = process.argv.slice(2)): void {
     hasStagedChanges: roGit(['diff', '--cached', '--name-only']).trim().length > 0,
     worktreeReviewClean: findUnstagedOrUntracked(statusEntries, scratch, ticketRel).length === 0,
     currentIndexHash: captureIndexHash(roGit),
+    // 🔴 REQ-2026-052: G2 compare_hash 재계산 정본(read-only ls-files, responses/ 제외). review-codex가
+    //    last_review.compare_hash에 이 값을 기록하므로 같은 값으로 비교한다.
+    currentSemanticIdentity: (() => {
+      try {
+        return computeReviewSemanticIdentity(ticketRel, roGit)
+      } catch {
+        return null // ls-files 실패 등 → null(G2 통과·fail-forward, 게이트 강제는 review-codex에 있다).
+      }
+    })(),
     reviewBudget: cfg.reviewBudget,
     phaseCommitAutoApprove: cfg.phaseCommit.autoApprove,
+    // REQ-2026-048 DEC-4: marker와 증거 모두 **HEAD blob**에서 읽는다(워킹 캐시 신뢰 금지).
+    designEvidenceDurability: (() => {
+      const ports = createEvidencePorts(cfg.root, `${ticketRel}/responses`)
+      const required = isDurabilityRequired(ports.headText(`${ticketRel}/state.json`))
+      if (!required) return { required: false, durable: true, reason: 'legacy 티켓(marker 없음) — 점검 불요' }
+      return { required: true, ...verifyCommittedDesignEvidence({ ticketRel, ports }) }
+    })(),
   })
 
   if (opts.json) console.log(JSON.stringify({ req_id: state.id, ...action }, null, 2))

package/scripts/req/req-reconstruct.ts

@@ -0,0 +1,217 @@
+#!/usr/bin/env tsx
+/**
+ * req:reconstruct — 소실된 close-proof lifecycle 행을 **HEAD-committed immutable evidence만으로** 복원한다
+ * (REQ-2026-052 phase-4·DEC-D2). 복원 가능성 매트릭스는 `lib/reconstruct`(순수)가 판정하고, 이 CLI는 evidence를
+ * HEAD blob에서 뽑아 넣고 부작용(durable commit)을 낸다.
+ *
+ * 🔴 **HEAD blob만** 읽는다 — runtime state·워킹트리·미커밋 원장·추정 phase 목록을 근거로 쓰지 않는다.
+ * 🔴 `verifyCommittedEvidenceIntegrity`가 실패한(손상) 티켓은 **복원하지 않고 fail-closed**한다.
+ * 🔴 **dev-complete·phase_design_ref·design/phase archive는 절대 합성하지 않는다.** state.json을 고치지 않는다.
+ * 🔴 기본 **dry-run**. `--run` + **`--confirm`(사람 확인)** 후에만 write. 새 행은 `reconstructed:true` +
+ *    비어있지 않은 `evidence_basis`. append-only·자연키 멱등 → 재시도가 중복 행/추가 커밋을 만들지 않는다.
+ *
+ * 사용: req:reconstruct <REQ> [--run] [--confirm] [--root <dir>]
+ */
+import { writeFileSync } from 'node:fs'
+import { join, relative } from 'node:path'
+import { pathToFileURL } from 'node:url'
+import { loadConfig, packageRoot } from './lib/config'
+import { createGitAdapter, type GitAdapter } from './lib/adapters'
+import { createEvidencePorts } from './lib/evidence-ports'
+import { verifyCommittedEvidenceIntegrity } from './lib/evidence'
+import { parseCloseProof, appendCloseProofRow, closeProofPath, type CloseProofRow } from './lib/close-proof'
+import { planReconstruction, type SuccessorEvidence, type ReconstructPlan } from './lib/reconstruct'
+import { listHeadTicketIds } from './lib/intake'
+import { isValidHumanResolution } from './review-codex'
+
+let gitAdapter: GitAdapter = createGitAdapter(packageRoot())
+function git(args: string[]): string {
+  return gitAdapter.exec(args)
+}
+/** `HEAD:<repoRel>` blob 텍스트(없으면 null). */
+function headBlob(repoRel: string): string | null {
+  try {
+    return git(['show', `HEAD:${repoRel}`])
+  } catch {
+    return null
+  }
+}
+
+export interface Opts {
+  reqId: string | null
+  run: boolean
+  confirm: boolean
+  root: string | null
+}
+
+/** 인자 파싱(fail-closed): 값 누락·알 수 없는 옵션은 즉시 throw. */
+export function parseArgs(argv: string[]): Opts {
+  const o: Opts = { reqId: null, run: false, confirm: false, root: null }
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i]
+    if (a === undefined) continue
+    if (a === '--') continue
+    else if (a === '--run') o.run = true
+    else if (a === '--confirm') o.confirm = true
+    else if (a === '--root') {
+      const v = argv[++i]
+      if (v === undefined) throw new Error('--root 값 필요')
+      o.root = v
+    } else if (a.startsWith('-')) throw new Error(`알 수 없는 옵션: ${a}`)
+    else o.reqId = a
+  }
+  return o
+}
+
+/**
+ * 이 티켓을 replace 부모로 지목하는 committed successor 증거를 HEAD tree에서 수집(read-only).
+ * 🔴 구식 successor_of(`parent_series_id` 없음)·비-replace·형식 무효는 제외한다(복원 불가 — 수집 안 함).
+ */
+export function collectSuccessorEvidence(workflowDirRel: string, parentReqId: string, gitFn: (a: string[]) => string): SuccessorEvidence[] {
+  const headBlobVia = (rel: string): string | null => {
+    try {
+      return gitFn(['show', `HEAD:${rel}`])
+    } catch {
+      return null
+    }
+  }
+  const out: SuccessorEvidence[] = []
+  for (const id of listHeadTicketIds(workflowDirRel, gitFn)) {
+    if (id === parentReqId) continue
+    const rel = `${workflowDirRel}/${id}`
+    const stateText = headBlobVia(`${rel}/state.json`)
+    if (stateText === null) continue
+    let so: unknown
+    try {
+      so = (JSON.parse(stateText) as { successor_of?: unknown }).successor_of
+    } catch {
+      continue
+    }
+    if (!so || typeof so !== 'object') continue
+    const s = so as { req_id?: unknown; parent_series_id?: unknown; parent_replace_resolution?: unknown }
+    if (s.req_id !== parentReqId) continue
+    if (typeof s.parent_series_id !== 'string' || !s.parent_series_id) continue // 구식 → 복원 불가
+    const hr = s.parent_replace_resolution
+    if (!isValidHumanResolution(hr) || (hr as { decision?: unknown }).decision !== 'replace') continue
+    out.push({
+      successorTicketId: id,
+      successorStatePath: `${rel}/state.json`,
+      parentSeriesId: s.parent_series_id,
+      resolution: 'replace', // collect는 decision==='replace'만 통과시킨다(material field로 명시).
+      at: (hr as { decided_at: string }).decided_at,
+    })
+  }
+  return out
+}
+
+function renderPlan(reqId: string, plan: ReconstructPlan): string {
+  const lines: string[] = [`[req:reconstruct] ${reqId} — 복원 계획(HEAD-committed 증거 기준)`]
+  if (plan.candidates.length) {
+    lines.push('  복원 예정 행:')
+    for (const c of plan.candidates)
+      lines.push(`    - series-terminal series_id=${c.row.series_id} resolution=${c.row.resolution} at=${c.row.at} · evidence_basis=[${c.evidenceBasis.join(', ')}]`)
+  } else {
+    lines.push('  복원 예정 행: 없음')
+  }
+  if (plan.refusals.length) {
+    lines.push('  복원 불가·불필요·모호:')
+    for (const r of plan.refusals) lines.push(`    - ${r}`)
+  }
+  if (plan.conflicts.length) {
+    lines.push('  🔴 fail-closed conflict(HEAD 모순 — write 0):')
+    for (const c of plan.conflicts) lines.push(`    - ${c}`)
+  }
+  return lines.join('\n')
+}
+
+export function main(argv: string[] = process.argv.slice(2)): void {
+  const o = parseArgs(argv)
+  if (!o.reqId) throw new Error('REQ 필요 (예: req:reconstruct 2026-029)')
+  const cfg = loadConfig({ root: o.root })
+  gitAdapter = createGitAdapter(cfg.root)
+  const reqId = o.reqId.startsWith('REQ-') ? o.reqId : `REQ-${o.reqId}`
+  const ticketDir = join(cfg.workflowDirAbs, reqId)
+  const ticketRel = relative(cfg.root, ticketDir).replace(/\\/g, '/')
+  const workflowDirRel = relative(cfg.root, cfg.workflowDirAbs).replace(/\\/g, '/')
+
+  // 🔴 1. 손상 티켓은 복원하지 않는다(fail-closed) — verifyCommittedEvidenceIntegrity(design+phase HEAD 무결성).
+  const ports = createEvidencePorts(cfg.root, `${ticketRel}/responses`)
+  const manifestText = ports.headText(`${ticketRel}/responses/approvals.jsonl`)
+  const integrity = verifyCommittedEvidenceIntegrity({ ticketRel, manifestText, ports })
+  if (integrity.problems.length)
+    throw new Error(`${reqId}: committed 증거 손상 — 복원 거부(fail-closed): ${integrity.problems.slice(0, 3).join('; ')}`)
+
+  // 2. 이 티켓 HEAD close-proof(모순/중복 판정 기준). 손상이면 거부.
+  const cpRel = closeProofPath(ticketRel)
+  const cpText = headBlob(cpRel)
+  const parsed = cpText ? parseCloseProof(cpText) : { rows: [], problems: [] }
+  if (parsed.problems.length)
+    throw new Error(`${reqId}: HEAD close-proof 손상 — 복원 거부: ${parsed.problems.slice(0, 3).join('; ')}`)
+
+  // 3. successor 증거 수집(HEAD tree) → 매트릭스(순수) 판정.
+  const successors = collectSuccessorEvidence(workflowDirRel, reqId, (a) => git(a))
+  const plan = planReconstruction({ ticketId: reqId, existingRows: parsed.rows, successors })
+  console.log(renderPlan(reqId, plan))
+
+  // 🔴 conflict(HEAD 모순)는 dry-run/`--run` 무관하게 **명령 전체를 fail-closed**한다 — 멱등으로 숨기지 않는다.
+  if (plan.conflicts.length)
+    throw new Error(`${reqId}: HEAD close-proof와 모순되는 복원 대상(conflict) — fail-closed(write 0): ${plan.conflicts.join('; ')}`)
+
+  // 4. 실행 모델.
+  if (!o.run) {
+    console.log('[req:reconstruct] DRY-RUN — write 없음(--run 시 실행).')
+    return
+  }
+  if (!o.confirm) {
+    console.log('[req:reconstruct] --run 지정됐으나 사람 확인 없음 — write 0. 위 계획을 확인했으면 `--confirm` 을 추가하세요.')
+    return
+  }
+  if (plan.candidates.length === 0) {
+    console.log('[req:reconstruct] 복원 가능한 행이 없습니다 — no-op(write 0).')
+    return
+  }
+
+  // 🔴 5. 쓰기 전 안전: 대상 close-proof가 **HEAD와 동일**(워킹트리·인덱스에 미커밋 변경 없음)이어야 한다.
+  //    아니면 HEAD 기반으로 덮어쓰다 사용자의 미커밋 close-proof 행을 **잃는다**(리뷰 P1). 불일치면 fail-closed.
+  const cpDirty = git(['status', '--porcelain', '--', cpRel]).trim()
+  if (cpDirty)
+    throw new Error(
+      `${reqId}: close-proof(${cpRel})에 미커밋 변경이 있어 복원을 거부합니다(fail-closed) — HEAD 기반 쓰기가 미커밋 행을 덮어쓸 수 있습니다.\n` +
+        `  먼저 미커밋 close-proof 변경을 커밋하거나 정리한 뒤 다시 실행하세요.`,
+    )
+
+  // 6. 쓰기: append(자연키 멱등) → durable commit(pathspec). 재시도는 duplicate라 커밋 diff 없음.
+  let content = cpText ?? ''
+  let appended = 0
+  for (const c of plan.candidates) {
+    const res = appendCloseProofRow(content, c.row)
+    if (res.outcome === 'appended') {
+      content = res.content
+      appended++
+    } else if (res.outcome === 'conflict') {
+      throw new Error(`복원 충돌(fail-closed): ${res.problems.join('; ')}`)
+    }
+    // duplicate → 이미 존재(멱등 skip).
+  }
+  if (appended === 0) {
+    console.log('[req:reconstruct] 대상 행이 이미 모두 존재 — no-op(멱등).')
+    return
+  }
+  writeFileSync(join(cfg.root, cpRel), content, 'utf8')
+  git(['add', '--', cpRel])
+  git(['commit', '-m', `chore(${reqId}): reconstruct series-terminal close proof (evidence-based)`, '--', cpRel])
+  console.log(`[req:reconstruct] ✅ ${appended}행 복원·durable commit(reconstructed:true·evidence_basis).`)
+}
+
+/** bin dispatch 진입점(친절한 1줄 오류 + exit 1 경계). */
+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()