commitgate 0.9.6 → 0.9.9

package/scripts/req/req-commit.ts

@@ -12,20 +12,56 @@
  *   ⚠️ B2 도구 자체 커밋은 부트스트랩 수기(req:commit dogfood는 Phase C부터).
  */
 import { existsSync, readFileSync, readdirSync, mkdirSync, writeFileSync } from 'node:fs'
+import { createHash } from 'node:crypto'
 import { resolve, join, relative } from 'node:path'
 import { pathToFileURL } from 'node:url'
 import {
   loadState,
   writeState,
   readPhases,
-  archiveBaseName,
-  isArchiveFileName,
-  isValidIsoInstant,
+  appendCloseProofRowToDisk,
   type ApprovalEvidence,
   type ReviewKind,
   type WorkflowState,
 } from './review-codex'
-import { isConfinedArchivePath } from './req-doctor'
+import { isArchiveFileName } from './lib/scratch'
+import { LEDGER_BASENAME } from './lib/review-ledger'
+import { CLOSE_PROOF_BASENAME, parseCloseProof, deriveBaseState } from './lib/close-proof'
+import { createEvidencePorts } from './lib/evidence-ports' // 아카이브 파일명 판정의 정본은 scratch(leaf)
+// REQ-2026-048 phase-1: 매니페스트 모델·검증과 그 보조 술어는 leaf `lib/evidence.ts`가 정본.
+// 여기서 **재수출**해 기존 import 경로(`from './req-commit'`)를 쓰던 호출부·테스트를 그대로 둔다.
+import {
+  archiveBaseName,
+  buildArchiveInventory,
+  designEvidenceStagePaths,
+  durableDesignEvidence,
+  isConfinedArchivePath,
+  isValidIsoInstant,
+  buildManifestEntry,
+  expectedArchivePaths,
+  manifestHasConsumed,
+  serializeManifestLine,
+  userConfirmProblem,
+  validateManifest,
+  designHashFromManifest,
+  evidencedPhaseIdsFromManifest,
+  verifyCommittedEvidenceIntegrity,
+  type ManifestEntry,
+  type UserCommitConfirmed,
+} from './lib/evidence'
+export {
+  buildArchiveInventory,
+  buildManifestEntry,
+  designEvidenceStagePaths,
+  expectedArchivePaths,
+  manifestHasConsumed,
+  serializeManifestLine,
+  userConfirmProblem,
+  validateManifest,
+  type ManifestEntry,
+  type UserCommitConfirmed,
+  type ArchiveInventoryItem,
+} from './lib/evidence'
 import { loadConfig, packageRoot, buildScriptInvocation, DEFAULTS, type PackageManager, type ResolvedConfig } from './lib/config'
 import { createGitAdapter, safeSpawnSync, type GitAdapter } from './lib/adapters'
 
@@ -33,205 +69,28 @@ import { createGitAdapter, safeSpawnSync, type GitAdapter } from './lib/adapters
 let gitRoot = packageRoot()
 let pkgManager: PackageManager = DEFAULTS.packageManager
 let gitAdapter: GitAdapter = createGitAdapter(packageRoot())
-const SHA256_RE = /^[0-9a-f]{64}$/i
-const GIT_OID_RE = /^[0-9a-f]{40}(?:[0-9a-f]{24})?$/i // git OID: 40(SHA-1) 또는 64(SHA-256)
-// ISO 검증은 review-codex의 isValidIsoInstant(형식+달력 유효성) 재사용 — 달력 불가능 값 거부(REQ-2026-030).
+
+/**
+ * repo-상대 경로 파일의 sha256(hex). `lib/evidence`는 fs를 모르는 순수 모듈이라 여기서 주입한다.
+ * 🔴 `gitRoot`는 `main()`이 `cfg.root`로 세팅한 뒤에만 유효하다 — designFinalize는 그 이후에만 호출된다.
+ */
+function repoRelSha256(repoRel: string): string {
+  return createHash('sha256').update(readFileSync(join(gitRoot, ...repoRel.split('/')))).digest('hex')
+}
 // evidencePreflight 구조 사전검증용 placeholder(실제 sourceSha/consumedAt는 source 커밋 후 채움). valid OID/ISO 형식.
 const PREFLIGHT_PLACEHOLDER_OID = '0'.repeat(40)
 const PREFLIGHT_PLACEHOLDER_ISO = '2000-01-01T00:00:00.000Z'
-/** approvals.jsonl 엔트리 허용 top-level 키(이 외 = 주입/오염 → fail). */
-const MANIFEST_KEYS = new Set([
-  'kind',
-  'phase_id',
-  'response_path',
-  'response_sha256',
-  'review_base_sha',
-  'approved_tree',
-  'design_hash',
-  'approved_at',
-  'consumed_at',
-  'consumed_by_commit_sha',
-  'user_commit_confirmed',
-])
-
-function escapeRegExp(s: string): string {
-  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
-}
+
 
 // ───────────────────────────────── approvals.jsonl 매니페스트 모델 (B1) ──
 
-/** HIGH 사람확인 감사 기록(암호학적 증명 아님 — D-016-8). */
-export interface UserCommitConfirmed {
-  confirmed: boolean
-  method: string
-  confirmed_at: string
-  note?: string
-}
 
-/** approvals.jsonl 한 줄(D-016-3b). kind 격리: phase=approved_tree, design=design_hash. */
-export interface ManifestEntry {
-  kind: ReviewKind
-  phase_id: string | null
-  response_path: string
-  response_sha256: string
-  review_base_sha: string
-  approved_tree?: string
-  design_hash?: string
-  approved_at: string
-  consumed_at: string
-  consumed_by_commit_sha: string
-  user_commit_confirmed: UserCommitConfirmed | null
-}
 
-/**
- * 승인 증거(state pin)와 소비 정보로 매니페스트 엔트리 생성(순수, 고정 필드·키 순서).
- * kind 격리: phase→approved_tree만, design→design_hash만(반대 kind 필드 미포함).
- */
-export function buildManifestEntry(
-  ev: ApprovalEvidence,
-  consume: { consumedAt: string; consumedByCommitSha: string; userCommitConfirmed: UserCommitConfirmed | null },
-): ManifestEntry {
-  const base: ManifestEntry = {
-    kind: ev.review_kind,
-    phase_id: ev.phase_id ?? null,
-    response_path: ev.response_path,
-    response_sha256: ev.response_sha256,
-    review_base_sha: ev.review_base_sha,
-    approved_at: ev.approved_at,
-    consumed_at: consume.consumedAt,
-    consumed_by_commit_sha: consume.consumedByCommitSha,
-    user_commit_confirmed: consume.userCommitConfirmed,
-  }
-  // fail-fast: kind별 필수 바인딩 필드(phase=approved_tree, design=design_hash). 반대 kind 필드는 미포함.
-  if (ev.review_kind === 'design') {
-    const designHash = ev.design_hash
-    if (typeof designHash !== 'string' || !designHash)
-      throw new Error('buildManifestEntry: design evidence에 design_hash 누락(fail-fast)')
-    return { ...base, phase_id: null, design_hash: designHash }
-  }
-  const approvedTree = ev.approved_tree
-  if (typeof approvedTree !== 'string' || !approvedTree)
-    throw new Error('buildManifestEntry: phase evidence에 approved_tree 누락(fail-fast)')
-  return { ...base, approved_tree: approvedTree }
-}
 
-/** 매니페스트 한 줄 직렬화(JSONL): JSON + 끝 개행. 고정 키 순서라 deterministic. */
-export function serializeManifestLine(entry: ManifestEntry): string {
-  return `${JSON.stringify(entry)}\n`
-}
 
-/**
- * approvals.jsonl 내용 검증(순수, fail-closed). 문제 목록 반환(빈 배열=정상).
- * 검사: malformed JSONL · response_path confinement(현재 티켓 responses/ 직계) · SHA-256 형식 ·
- *   phase kind의 phase_id 유효성 · (kind,phase_id,sha) 중복/주입.
- */
-export function validateManifest(
-  content: string,
-  opts: { ticketRel: string; validPhaseIds: string[] },
-): string[] {
-  const problems: string[] = []
-  const seenKey = new Set<string>()
-  const seenPath = new Set<string>()
-  const lines = content.split('\n').map((l) => l.trim()).filter(Boolean)
-  for (let i = 0; i < lines.length; i++) {
-    const ln = i + 1
-    let e: Record<string, unknown>
-    try {
-      e = JSON.parse(lines[i] as string) as Record<string, unknown>
-    } catch {
-      problems.push(`line ${ln}: malformed JSON`)
-      continue
-    }
-    if (!e || typeof e !== 'object' || Array.isArray(e)) {
-      problems.push(`line ${ln}: object 아님`)
-      continue
-    }
-    // 예상 외 extra field 금지(주입 차단).
-    for (const k of Object.keys(e)) if (!MANIFEST_KEYS.has(k)) problems.push(`line ${ln}: 예상 외 필드: ${k}`)
-    const kind = e.kind
-    if (kind !== 'phase' && kind !== 'design') problems.push(`line ${ln}: kind 비유효: ${String(kind)}`)
-    // 공통: 경로 confinement, sha/OID/ISO 형식.
-    const respPath = typeof e.response_path === 'string' ? e.response_path : ''
-    if (!isConfinedArchivePath(respPath, opts.ticketRel)) problems.push(`line ${ln}: response_path 비confined: ${respPath}`)
-    // B1-P2-1: manifest 행(=소비된 승인)의 response_path basename은 그 행의 kind/phase_id **승인본**(-approved)이어야.
-    // (design→phase 아카이브·타 phase·needs-fix 가리키는 주입/변조 차단. expectedArchivePaths[chore 대상]는 needs-fix 포함 별개.)
-    if (kind === 'phase' || kind === 'design') {
-      const expBase = archiveBaseName(kind, kind === 'phase' && typeof e.phase_id === 'string' ? e.phase_id : null)
-      const name = respPath.split('/').pop() ?? ''
-      if (!new RegExp(`^${escapeRegExp(expBase)}-r\\d{2,}-approved\\.json$`).test(name))
-        problems.push(`line ${ln}: response_path가 ${expBase}-rNN-approved.json 아님: ${name}`)
-    }
-    if (typeof e.response_sha256 !== 'string' || !SHA256_RE.test(e.response_sha256)) problems.push(`line ${ln}: response_sha256 형식 오류(64hex)`)
-    if (typeof e.review_base_sha !== 'string' || !GIT_OID_RE.test(e.review_base_sha)) problems.push(`line ${ln}: review_base_sha 비-OID`)
-    if (typeof e.consumed_by_commit_sha !== 'string' || !GIT_OID_RE.test(e.consumed_by_commit_sha)) problems.push(`line ${ln}: consumed_by_commit_sha 비-OID`)
-    if (!isValidIsoInstant(e.approved_at)) problems.push(`line ${ln}: approved_at 비-ISO`)
-    if (!isValidIsoInstant(e.consumed_at)) problems.push(`line ${ln}: consumed_at 비-ISO`)
-    // kind별 strict 바인딩(반대 kind 필드 금지).
-    if (kind === 'phase') {
-      if (typeof e.phase_id !== 'string' || !e.phase_id || !opts.validPhaseIds.includes(e.phase_id))
-        problems.push(`line ${ln}: phase_id 비유효: ${String(e.phase_id)}`)
-      if (typeof e.approved_tree !== 'string' || !GIT_OID_RE.test(e.approved_tree)) problems.push(`line ${ln}: approved_tree 비-OID`)
-      if ('design_hash' in e) problems.push(`line ${ln}: phase entry에 design_hash 금지`)
-    } else if (kind === 'design') {
-      if (e.phase_id !== null) problems.push(`line ${ln}: design entry는 phase_id=null이어야`)
-      if (typeof e.design_hash !== 'string' || !SHA256_RE.test(e.design_hash)) problems.push(`line ${ln}: design_hash 비-64hex`)
-      if ('approved_tree' in e) problems.push(`line ${ln}: design entry에 approved_tree 금지`)
-    }
-    // user_commit_confirmed: null 또는 유효 감사 기록(confirmed=true·method·ISO confirmed_at)만. (B2-block3)
-    const ucc = e.user_commit_confirmed
-    if (ucc !== null) {
-      const p = userConfirmProblem(ucc)
-      if (p) problems.push(`line ${ln}: user_commit_confirmed ${p}(null 또는 confirmed=true·method·ISO confirmed_at)`)
-    }
-    // 중복: (kind/phase/sha) + response_path 두 기준 모두.
-    const key = `${String(kind)}:${String(e.phase_id)}:${String(e.response_sha256)}`
-    if (seenKey.has(key)) problems.push(`line ${ln}: 중복 entry(kind/phase/sha): ${key}`)
-    seenKey.add(key)
-    if (respPath) {
-      if (seenPath.has(respPath)) problems.push(`line ${ln}: 중복 response_path: ${respPath}`)
-      seenPath.add(respPath)
-    }
-  }
-  return problems
-}
-
-/**
- * 이번 target(kind/phaseId)의 **예상 응답 아카이브 repo-경로만** 반환(blanket `git add responses/` 금지).
- * archiveNames(responses/ 디렉터리 파일명)에서 해당 base의 rNN 아카이브만 필터 → 현재 티켓 responses/ 경로로.
- * needs-fix + approved 모두 포함(evidence chore는 실패 라운드까지 영속화) — 매니페스트 행 검증(approved만)과 별개.
- */
-export function expectedArchivePaths(
-  archiveNames: string[],
-  kind: ReviewKind,
-  phaseId: string | null,
-  ticketRel: string,
-): string[] {
-  const base = archiveBaseName(kind, phaseId)
-  const re = new RegExp(`^${escapeRegExp(base)}-r(\\d{2,})-(approved|needs-fix)\\.json$`)
-  const dir = `${ticketRel.replace(/\\/g, '/').replace(/\/+$/, '')}/responses`
-  // readdir 순서 비의존 — round(rNN) 오름차순 정렬(deterministic).
-  return archiveNames
-    .map((n) => ({ n, m: isArchiveFileName(n) ? re.exec(n) : null }))
-    .filter((x): x is { n: string; m: RegExpExecArray } => x.m !== null)
-    .sort((a, b) => Number.parseInt(a.m[1] ?? '0', 10) - Number.parseInt(b.m[1] ?? '0', 10))
-    .map((x) => `${dir}/${x.n}`)
-}
 
 // ─────────────────────────────────────── B2: HIGH 게이트 / 소비 / preflight(순수) ──
 
-/**
- * user_commit_confirmed 감사 기록 형식 검증(순수). 유효하면 null, 아니면 사유.
- * 요구: confirmed===true · method(공백 아닌 문자열) · confirmed_at(ISO).
- * ⚠️ 위조불가 증명이 아니다 — Claude가 생성 가능한 플래그. 가장 강한 보장 = 사용자가 직접 `req:commit` 실행.
- */
-export function userConfirmProblem(ucc: unknown): string | null {
-  if (!ucc || typeof ucc !== 'object') return '기록 없음'
-  const c = ucc as { confirmed?: unknown; method?: unknown; confirmed_at?: unknown }
-  if (c.confirmed !== true) return 'confirmed=true 아님'
-  if (typeof c.method !== 'string' || !c.method.trim()) return 'method(공백 아닌 문자열) 필요'
-  if (!isValidIsoInstant(c.confirmed_at)) return 'confirmed_at(ISO) 필요'
-  return null
-}
 
 /**
  * HIGH 사람확인 게이트(D-016-8, 순수). HIGH인데 유효한 `user_commit_confirmed`(confirmed=true·method·ISO confirmed_at)가 없으면 차단.
@@ -332,34 +191,6 @@ export function resolveRecoverySource(
   return { sourceSha: null, viaOrphan: false, reason: 'pending 마커 없음 + HEAD가 승인 source 아님 — 복구할 미완 작업 없음' }
 }
 
-/**
- * approvals.jsonl에 **이 evidence가** 이미 finalize된 엔트리가 있는지(순수, 멱등 finalize용).
- * ⚠️ B3-R2: consumed_by_commit_sha만으로는 부족 — 같은 source SHA를 쓰는 design-finalize row 등에 오인될 수 있음.
- *   sourceSha **+ evidence identity(kind·phase_id·response_sha256)** 전부 일치해야 동일 엔트리로 판정.
- */
-export function manifestHasConsumed(
-  content: string,
-  sourceSha: string,
-  identity: { reviewKind: ReviewKind; phaseId: string | null; responseSha256: string },
-): boolean {
-  for (const line of content.split('\n').map((l) => l.trim()).filter(Boolean)) {
-    try {
-      const e = JSON.parse(line) as { consumed_by_commit_sha?: unknown; kind?: unknown; phase_id?: unknown; response_sha256?: unknown }
-      if (
-        e &&
-        typeof e === 'object' &&
-        e.consumed_by_commit_sha === sourceSha &&
-        e.kind === identity.reviewKind &&
-        (e.phase_id ?? null) === identity.phaseId &&
-        e.response_sha256 === identity.responseSha256
-      )
-        return true
-    } catch {
-      // malformed 줄은 무시(무결성은 validateManifest 담당)
-    }
-  }
-  return false
-}
 
 export interface PreflightInput {
   existingManifest: string // 현재 approvals.jsonl 내용('' = 없음)
@@ -547,14 +378,125 @@ function stagedNames(): string[] {
     .filter(Boolean)
 }
 
+// 🔴 REQ-2026-052 phase-3b: 매니페스트 순수 파서(parseManifestEntries·evidencedPhaseIdsFromManifest·
+//    designHashFromManifest)는 **매니페스트 모델의 정본인 `lib/evidence`(leaf)로 이동**했다. req:new intake
+//    스캔(leaf `lib/intake`)이 req-commit(top-level command)에 의존하지 않고 같은 파서를 쓰기 위함이다.
+//    기존 호출부·테스트 호환을 위해 여기서 re-export한다(경로 무변경).
+export { parseManifestEntries, evidencedPhaseIdsFromManifest, designHashFromManifest } from './lib/evidence'
+
+/**
+ * 🔴 **dev-complete 발행 결정(순수, DEC-B3)** — 이 phase 커밋이 마지막 phase를 완료시키면 발행할 proof row를,
+ *    아니면 null을 낸다. runtime `state.phases`는 **inventory 산출 입력으로만** 쓴다(DEC-B4).
+ *
+ * @param phaseIds  `state.phases`의 phase id들(inventory 원천 — 정렬·중복 제거는 여기서).
+ * @param reviewKind 이 finalize의 kind(design이면 null — dev-complete 아님).
+ * @param manifestContent 이 phase 엔트리를 **포함한** 매니페스트(발행 전 prospective 검증 대상).
+ * @param nowIso 발행 시각.
+ * @returns 발행할 dev-complete `CloseProofRow` 또는 null(마지막 phase 아님/미분해/design).
+ * @throws design_ref(커밋된 design 승인)가 없으면 — 마지막 phase인데 design 증거가 없다(fail-closed).
+ */
+export function computeDevCompleteProof(args: {
+  ticketId: string
+  phaseIds: readonly string[]
+  reviewKind: ReviewKind
+  manifestContent: string
+  nowIso: string
+}): import('./lib/close-proof').CloseProofRow | null {
+  if (args.reviewKind !== 'phase') return null
+  const inventory = [...new Set(args.phaseIds)].sort()
+  if (inventory.length === 0) return null
+  const designRef = designHashFromManifest(args.manifestContent)
+  if (!designRef) throw new Error('dev-complete 발행 전 검증 실패: 커밋된 design 승인(design_hash)이 없다')
+  // 🔴 DEC-B5: **design-bound** 완전성 — 각 inventory phase가 **현재 design_ref에 결속된** 증거를 가져야 마지막
+  //    phase다. 단순 phase_id 존재로는 부족(D1 검토분이 D2 완료에 새는 P1). 결속 없는(레거시) 행은 불산입.
+  const evidenced = new Set(evidencedPhaseIdsFromManifest(args.manifestContent, designRef))
+  if (!inventory.every((id) => evidenced.has(id))) return null // 아직 (design-bound) 마지막 phase 아님(㊱·㊺·㊻)
+  return {
+    ticket_id: args.ticketId,
+    event: 'dev-complete',
+    series_id: null,
+    resolution: null,
+    phase_inventory: inventory,
+    design_ref: designRef,
+    at: args.nowIso,
+    reconstructed: false,
+    evidence_basis: null,
+  }
+}
+
+/**
+ * 🔴 REQ-2026-052 phase-3a(DEC-B3): 이 phase 커밋이 **마지막 phase**를 완료시키면 self-verifying dev-complete
+ *    proof를 발행하고, 같은 커밋에 실을 close-proof 경로를 반환한다. 아니면 `[]`.
+ *
+ * - **입력**: `state.phases`(inventory 산출 — DEC-B4: **입력으로만**) + `newContent`(이 phase 엔트리 포함 매니페스트).
+ * - **prospective 검증(발행 전)**: inventory의 모든 phase가 newContent에 phase 증거로 있고, design_ref가 커밋된
+ *   design 승인과 일치하는지 확인. 하나라도 어긋나면 발행하지 않는다(마지막 phase가 아니거나 증거 불완전).
+ * - **멱등**: close proof가 이미 dev-complete row를 갖고 있으면 append가 duplicate → `[]` 반환(중복 방지)이 아니라
+ *   **경로는 반환**하되 파일 내용이 그대로라 커밋에 diff가 없다(재시도 안전). 실제 중복 행은 자연키 멱등이 막는다.
+ */
+function emitDevCompleteIfLastPhase(ctx: FinalizeCtx, newContent: string): string[] {
+  const proof = computeDevCompleteProof({
+    ticketId: String(ctx.state.id ?? ''),
+    phaseIds: readPhases(ctx.state).map((p) => p.id),
+    reviewKind: ctx.ev.review_kind,
+    manifestContent: newContent,
+    nowIso: new Date().toISOString(),
+  })
+  if (!proof) return []
+  appendCloseProofRowToDisk(ctx.rootForClose, ctx.ticketRel, proof) // 멱등: 이미 있으면 duplicate(no-op)
+  return [`${ctx.ticketRel}/responses/${CLOSE_PROOF_BASENAME}`]
+}
+
+/**
+ * 🔴 발행 후 HEAD-only 재검증(DEC-B3 step 4). HEAD blob만 읽어 dev-complete가 성립하는지 확인 —
+ *    close proof inventory의 모든 phase evidence + design_ref 일치. 어긋나면 fail-closed.
+ */
+function verifyDevCompleteAtHead(ctx: FinalizeCtx): void {
+  const cpRel = `${ctx.ticketRel}/responses/${CLOSE_PROOF_BASENAME}`
+  const mfRel = `${ctx.ticketRel}/responses/approvals.jsonl`
+  const cpText = headBlobText(cpRel)
+  const mfText = headBlobText(mfRel)
+  if (cpText === null || mfText === null) throw new Error('dev-complete HEAD 재검증 실패: close proof·매니페스트가 HEAD에 없다')
+  const parsed = parseCloseProof(cpText)
+  if (parsed.problems.length) throw new Error(`dev-complete HEAD 재검증 실패: close proof 손상 — ${parsed.problems.join('; ')}`)
+  // 🔴 DEC-B6·B7(phase-3b2·3b3): intake와 **동일한** committed 증거(design+phase) 무결성 규칙(공유
+  //    verifyCommittedEvidenceIntegrity). 발행 후에도 design 승인 archive+inventory·모든 phase archive가 HEAD에
+  //    존재하고 SHA가 일치해야 한다 — 아니면 fail-closed(intake의 corrupt와 대칭).
+  const integrity = verifyCommittedEvidenceIntegrity({ ticketRel: ctx.ticketRel, manifestText: mfText, ports: createEvidencePorts(gitRoot, `${ctx.ticketRel}/responses`) })
+  if (integrity.problems.length)
+    throw new Error(`dev-complete HEAD 재검증 실패: committed 증거 손상 — ${integrity.problems.join('; ')}`)
+  const committedDesignRef = designHashFromManifest(mfText)
+  const state = deriveBaseState({
+    durabilityRequired: true,
+    closeProofRows: parsed.rows,
+    ledgerHasApprovedClose: false,
+    committedEvidenceComplete: true,
+    // 🔴 DEC-B5: HEAD 재검증도 design-bound — 현재 committed design_ref에 결속된 phase evidence만 산입.
+    evidencedPhaseIds: evidencedPhaseIdsFromManifest(mfText, committedDesignRef),
+    committedDesignRef,
+  })
+  if (state !== 'dev-complete')
+    throw new Error(`dev-complete HEAD 재검증 실패: 발행 후 파생 상태가 dev-complete가 아니다(${state})`)
+}
+
+/** `HEAD:<repoRel>` blob 텍스트(없으면 null). */
+function headBlobText(repoRel: string): string | null {
+  try {
+    return git(['show', `HEAD:${repoRel}`])
+  } catch {
+    return null
+  }
+}
+
 interface FinalizeCtx {
   ticketDir: string
   ticketRel: string
   responsesDir: string
   manifestPath: string
+  /** REQ-2026-052: close proof append용 repo root(디스크 경로 해소). */
+  rootForClose: string
   state: WorkflowState
   ev: ApprovalEvidence
-  existing: string
   archiveNames: string[]
   validPhaseIds: string[]
   sourceSha: string
@@ -565,13 +507,28 @@ interface FinalizeCtx {
  * 이미 sourceSha가 매니페스트에 있으면(=evidence 커밋은 됐고 consume만 못 함) append/chore를 skip하고 소비만 수행.
  * 소비는 항상 마지막. state.json은 scratch 유지(커밋 안 함).
  */
-function finalizeEvidenceAndConsume(ctx: FinalizeCtx): void {
-  // B3-R2: skip(소비-only) 경로 포함 — 변조된 매니페스트 위에서 consume 금지. 기존 무결성 먼저(복구 모드엔 preflight가 없으므로 필수).
-  if (ctx.existing.trim()) {
-    const ep = validateManifest(ctx.existing, { ticketRel: ctx.ticketRel, validPhaseIds: ctx.validPhaseIds })
-    if (ep.length) throw new Error(`기존 approvals.jsonl 무결성 실패(fail-closed): ${ep.join('; ')}`)
+/** 🔴 테스트 전용: git 경계·gitRoot를 실제 저장소로 주입한다(finalizeEvidenceAndConsume 격리 테스트용). */
+export function __setGitForTest(root: string): void {
+  gitRoot = root
+  gitAdapter = createGitAdapter(root)
+}
+
+export function finalizeEvidenceAndConsume(ctx: FinalizeCtx): void {
+  // 🔴 REQ-2026-052 phase-3a P1(리뷰 반영): finalize 멱등성을 **HEAD 기준**으로 판정한다 — 워킹 매니페스트가
+  //    아니라. 이전엔 `ctx.existing`(워킹트리 파일)을 base·멱등 판정에 썼는데, evidence commit이 실패하면
+  //    디스크엔 이미 매니페스트가 쓰였으므로 재시도가 그걸 "이미 finalize됨"으로 오판해 **HEAD에 증거가 없는데
+  //    완료로 진행**했다(dev-complete proof·archive·ledger 미커밋). HEAD blob만 base로 삼아 "커밋 성공 여부"가
+  //    아니라 "HEAD에 실제 존재하는지"로 판정한다.
+  const manifestRel = `${ctx.ticketRel}/responses/approvals.jsonl`
+  // 🔴 `git show`(gitAdapter)가 후행 개행을 제거하므로 복원한다 — 없으면 append 시 두 JSON이 한 줄로 붙어 손상된다.
+  const headManifestRaw = headBlobText(manifestRel) ?? ''
+  const headManifest = headManifestRaw && !headManifestRaw.endsWith('\n') ? `${headManifestRaw}\n` : headManifestRaw
+  // 기존 무결성 먼저(변조된 매니페스트 위에서 consume 금지). HEAD blob 검증.
+  if (headManifest.trim()) {
+    const ep = validateManifest(headManifest, { ticketRel: ctx.ticketRel, validPhaseIds: ctx.validPhaseIds })
+    if (ep.length) throw new Error(`HEAD approvals.jsonl 무결성 실패(fail-closed): ${ep.join('; ')}`)
   }
-  const already = manifestHasConsumed(ctx.existing, ctx.sourceSha, {
+  const already = manifestHasConsumed(headManifest, ctx.sourceSha, {
     reviewKind: ctx.ev.review_kind,
     phaseId: ctx.ev.phase_id ?? null,
     responseSha256: ctx.ev.response_sha256,
@@ -582,17 +539,27 @@ function finalizeEvidenceAndConsume(ctx: FinalizeCtx): void {
       consumedByCommitSha: ctx.sourceSha,
       userCommitConfirmed: (ctx.state.user_commit_confirmed as UserCommitConfirmed | null) ?? null,
     })
-    const newContent = ctx.existing + serializeManifestLine(entry)
+    // 🔴 base는 **HEAD 매니페스트** — 실패한 이전 쓰기가 남긴 디스크 엔트리를 이어붙여 중복시키지 않는다.
+    const newContent = headManifest + serializeManifestLine(entry)
     const reproblems = validateManifest(newContent, { ticketRel: ctx.ticketRel, validPhaseIds: ctx.validPhaseIds })
     if (reproblems.length)
       throw new Error(`(예상외) 매니페스트 검증 실패: ${reproblems.join('; ')} — source=${ctx.sourceSha} 커밋됨, --finalize로 복구`)
     mkdirSync(ctx.responsesDir, { recursive: true })
     writeFileSync(ctx.manifestPath, newContent, 'utf8')
     const archivePaths = expectedArchivePaths(ctx.archiveNames, ctx.ev.review_kind, ctx.ev.phase_id ?? null, ctx.ticketRel)
-    git(['add', ...archivePaths, `${ctx.ticketRel}/responses/approvals.jsonl`])
+    // REQ-2026-051 D7: 리뷰 원장이 있으면 phase 증거 커밋에 함께 싣는다. 없으면 넣지 않는다 —
+    // 없는 pathspec으로 `git add`가 실패해 증거 커밋 전체가 무산되면 본말전도다(design 경로의 ledgerExists와 대칭).
+    const ledgerRel = `${ctx.ticketRel}/responses/${LEDGER_BASENAME}`
+    const ledgerAdd = existsSync(join(ctx.ticketDir, 'responses', LEDGER_BASENAME)) ? [ledgerRel] : []
+    // 🔴 REQ-2026-052 phase-3a: 이 커밋이 **마지막 phase**를 완료시키면 self-verifying dev-complete proof를
+    //    **같은 durable 커밋**에 발행한다(DEC-B3). 아니면 발행 안 함. newContent(이 phase 엔트리 포함)로 판정.
+    const devCompleteAdd = emitDevCompleteIfLastPhase(ctx, newContent)
+    git(['add', ...archivePaths, `${ctx.ticketRel}/responses/approvals.jsonl`, ...ledgerAdd, ...devCompleteAdd])
     const choreLeak = stagedNames().filter((p) => !p.startsWith(`${ctx.ticketRel}/responses/`))
     if (choreLeak.length) throw new Error(`evidence 커밋에 responses 외 staged 금지(코드/state 누수): ${choreLeak.join(', ')}`)
-    git(['commit', '-m', `chore(${ctx.state.id}): evidence-finalize — ${ctx.ev.review_kind} ${ctx.ev.phase_id ?? ''} 아카이브·approvals.jsonl`])
+    git(['commit', '-m', `chore(${ctx.state.id}): evidence-finalize — ${ctx.ev.review_kind} ${ctx.ev.phase_id ?? ''} 아카이브·approvals.jsonl${devCompleteAdd.length ? '·dev-complete' : ''}`])
+    // 🔴 발행 후 HEAD-only 재검증(DEC-B3 step 4): 발행했으면 HEAD blob만으로 dev-complete가 성립해야 한다.
+    if (devCompleteAdd.length) verifyDevCompleteAtHead(ctx)
   } else {
     console.log('[req:commit] evidence 이미 finalize됨(멱등 skip) — 소비만 수행')
   }
@@ -617,33 +584,25 @@ function designFinalize(args: {
   if (!dev) throw new Error('design_approval_evidence 없음 — design 승인 후 실행')
   if (dev.review_kind !== 'design') throw new Error(`design_approval_evidence.review_kind != design: ${String(dev.review_kind)}`)
   runDoctor(args.doctorArgs) // design-finalize도 doctor 우회 금지(정상)
-  const opts = { ticketRel: args.ticketRel, validPhaseIds: args.validPhaseIds }
-  const existing = existsSync(args.manifestPath) ? readFileSync(args.manifestPath, 'utf8') : ''
-  // B3-P2: 기존 매니페스트 단독 무결성 먼저(중복+다른 오염 시 묵인 금지 — 오염이면 여기서 fail-closed).
-  if (existing.trim()) {
-    const existingProblems = validateManifest(existing, opts)
-    if (existingProblems.length) throw new Error(`기존 approvals.jsonl 무결성 실패(fail-closed): ${existingProblems.join('; ')}`)
-  }
-  const headSha = git(['rev-parse', 'HEAD'])
-  const entry = buildManifestEntry(dev, { consumedAt: new Date().toISOString(), consumedByCommitSha: headSha, userCommitConfirmed: null })
-  const newContent = existing + serializeManifestLine(entry)
-  const problems = validateManifest(newContent, opts)
-  // 기존이 이미 클린이므로 newContent의 문제는 후보(candidate) 때문. **오직 중복뿐**일 때만 멱등 skip, 하나라도 다른 문제면 fail.
-  if (problems.length) {
-    if (problems.every((p) => p.includes('중복'))) {
-      console.log('[req:commit] design 승인 이미 기록됨(멱등 skip)')
-      return
-    }
-    throw new Error(`design-finalize 매니페스트 검증 실패: ${problems.join('; ')}`)
+  // REQ-2026-048 phase-3: 실제 내구화는 **공유 구현**에 위임한다. 정상 승인 경로(review-codex)와
+  // 이 복구 경로가 같은 함수를 부르므로 동작이 갈라질 수 없다(DEC-1·DEC-3).
+  const r = durableDesignEvidence({
+    ticketId: String(args.state.id ?? ''),
+    ticketRel: args.ticketRel,
+    evidence: dev,
+    validPhaseIds: args.validPhaseIds,
+    nowIso: new Date().toISOString(),
+    ports: createEvidencePorts(gitRoot, `${args.ticketRel}/responses`),
+  })
+  if (r.outcome === 'already-durable') {
+    console.log('[req:commit] design 승인 이미 내구화됨(HEAD 기준 멱등 skip)')
+    return
   }
-  const responsePath = typeof dev.response_path === 'string' ? dev.response_path : ''
-  mkdirSync(args.responsesDir, { recursive: true })
-  writeFileSync(args.manifestPath, newContent, 'utf8')
-  git(['add', responsePath, `${args.ticketRel}/responses/approvals.jsonl`])
-  const leak = stagedNames().filter((p) => !p.startsWith(`${args.ticketRel}/responses/`))
-  if (leak.length) throw new Error(`design-finalize 커밋에 responses 외 staged 금지: ${leak.join(', ')}`)
-  git(['commit', '-m', `chore(${args.state.id}): design-finalize — design 승인 approvals.jsonl 기록`])
-  console.log('[req:commit] ✅ design-finalize 완료 — approvals.jsonl 기록')
+  console.log(
+    r.outcome === 'recommitted'
+      ? '[req:commit] ✅ design-finalize 복구 완료 — 매니페스트는 이미 있었고 커밋만 누락돼 재커밋했습니다'
+      : '[req:commit] ✅ design-finalize 완료 — approvals.jsonl 기록',
+  )
 }
 
 export function main(argv: string[] = process.argv.slice(2)): void {
@@ -742,7 +701,7 @@ export function main(argv: string[] = process.argv.slice(2)): void {
     runDoctor([...doctorArgs, '--finalize'])
     const gate = userConfirmGate(fstate)
     if (gate.blocked) throw new Error(gate.reason)
-    finalizeEvidenceAndConsume({ ticketDir, ticketRel, responsesDir, manifestPath, state: fstate, ev, existing, archiveNames, validPhaseIds, sourceSha })
+    finalizeEvidenceAndConsume({ ticketDir, ticketRel, responsesDir, manifestPath, state: fstate, ev, archiveNames, validPhaseIds, sourceSha, rootForClose: cfg.root })
     console.log(`[req:commit] ✅ finalize 복구 완료 — source=${sourceSha.slice(0, 8)} · evidence/consume 복구`)
     return
   }
@@ -788,7 +747,7 @@ export function main(argv: string[] = process.argv.slice(2)): void {
   // 4b) B3 복구 마커 — source 커밋됨, evidence 미완. 이후 중단 시 `req:commit <id> --finalize --run`으로 복구.
   writeState(ticketDir, markPendingEvidence(state, sourceSha))
   // 5) evidence-finalize(멱등) + 소비(마지막).
-  finalizeEvidenceAndConsume({ ticketDir, ticketRel, responsesDir, manifestPath, state, ev, existing, archiveNames, validPhaseIds, sourceSha })
+  finalizeEvidenceAndConsume({ ticketDir, ticketRel, responsesDir, manifestPath, state, ev, archiveNames, validPhaseIds, sourceSha, rootForClose: cfg.root })
   console.log(`[req:commit] ✅ 완료 — source=${sourceSha.slice(0, 8)} · evidence-finalize · commit_allowed 소비됨`)
 }