commitgate 0.9.8 → 0.9.10

package/scripts/req/lib/review-ledger.ts

@@ -0,0 +1,257 @@
+/**
+ * 커밋되는 **append-only 리뷰 원장** (REQ-2026-051).
+ *
+ * 왜 존재하나: `state.json`은 scratch로 설계돼 커밋되지 않는다(`req-commit.ts` — "state.json은 scratch 유지").
+ * 그래서 런타임 원장이 미커밋으로 남고, 다음 티켓의 `req:new`가 clean tree를 요구하는 순간 폐기된다.
+ * 소비자 저장소에서 실제로 한 REQ의 원장(설계 승인 + phase 3건 승인 이력)이 통째로 사라졌고,
+ * 이 저장소의 REQ-2026-049도 같은 상태다(`phases: []`·`review_series: 0`).
+ *
+ * 🔴 **`approvals.jsonl`을 중복하지 않는다.** 그쪽 `archive_inventory`가 아카이브된 전 라운드를
+ *    `response_path`+`sha256`으로 이미 담는다. 이 원장은 **아카이브가 보여줄 수 없는 것만** 담는다:
+ *      1. 아카이브를 남기지 않은 시도(호출 실패·무효 응답) — attempt는 호출 **전**에 확정되고
+ *         아카이브는 유효 응답에만 생기므로, 그 차이가 어디에도 안 남는다.
+ *      2. 사람 예외 소비 — `review_exception_confirmed`는 소비 후 `null`로 지워진다.
+ *      3. series 종결 사유 · 4. lineage · 5. 재구성 여부.
+ *
+ * 🔴 **프롬프트·응답 본문을 저장하지 않는다.** 해시까지만. 응답 본문은 이미 아카이브에 있고
+ *    `archive_sha256`이 그것을 가리킨다. 허용키 화이트리스트가 본문이 들어갈 자리 자체를 막는다.
+ *
+ * 이 모듈은 **순수**하다 — fs·git을 모른다. 부작용은 호출부가 낸다(`lib/evidence`와 같은 태도).
+ */
+import { isValidIsoInstant } from './evidence'
+import type { ReviewKind } from '../review-codex'
+
+/** 원장 파일의 티켓-상대 경로. `approvals.jsonl`과 같은 디렉터리 — 기존 내구화 경로 2곳을 그대로 재사용한다. */
+export const LEDGER_BASENAME = 'review-ledger.jsonl'
+
+/** 티켓 `responses/` 기준 원장의 repo-상대 경로. */
+export function ledgerPath(ticketRel: string): string {
+  return `${ticketRel.replace(/\\/g, '/').replace(/\/+$/, '')}/responses/${LEDGER_BASENAME}`
+}
+
+/**
+ * 이벤트 2종 (D2).
+ *
+ * attempt는 외부 호출 **전**에 확정되고 결과는 **후**에 나온다. 한 행에 담으면 나중에 그 행을 고쳐야 하는데
+ * 그것은 append-only가 아니다. 그래서 나눈다.
+ *
+ * 부수 효과가 이 설계의 핵심 이득이다: `attempt-opened`만 있고 `attempt-closed`가 없는 attempt가 곧
+ * **"예산은 깎였는데 완료되지 않은 호출"**이다. 별도 필드 없이 원장 **구조 자체로** 관측된다.
+ */
+export type LedgerEvent = 'attempt-opened' | 'attempt-closed'
+
+/** 완료된 attempt의 판정. 미완(`attempt-opened`)이면 null. */
+export type LedgerOutcome = 'approved' | 'needs-fix' | 'blocked' | 'invalid'
+
+export interface LedgerRow {
+  ticket_id: string
+  series_id: string
+  review_kind: ReviewKind
+  phase_id: string | null
+  attempt: number
+  event: LedgerEvent
+  /**
+   * 호출 수명주기. **이 REQ는 `completed`만 쓴다.** `pre_dispatch_failed`·`dispatch_confirmed`·
+   * `dispatched_unknown` 및 예산 차감 규칙 변경은 후속 REQ 소관이다.
+   * `attempt-opened`에서는 null.
+   */
+  lifecycle: string | null
+  outcome: LedgerOutcome | null
+  /** 이 attempt가 autoBudget 초과라 사람 예외를 소비했는지. scratch에서 지워지는 유일한 사실이라 여기서만 살아남는다. */
+  exception_consumed: boolean
+  // 🔴 **archive path·sha256을 담지 않는다**(phase-2 리뷰 P1). 아카이브된 라운드의 경로·해시는 이미
+  //    `approvals.jsonl`의 `archive_inventory`가 단일 출처로 보관한다. 원장이 그걸 복제하면 두 사본이
+  //    갈라질 수 있고, 이 REQ의 헤드라인 원칙("approvals.jsonl을 중복하지 않는다")을 스스로 어긴다.
+  //    아카이브 존재 여부는 `outcome`이 이미 알려 준다(approved/needs-fix=아카이브됨, blocked/invalid=아님).
+  /** 🔴 프롬프트 **해시만**. 본문은 원장에 들어가지 않는다. */
+  prompt_sha256: string | null
+  at: string
+  /** 사후 복원한 기록인지. 원본과 구별할 수단이 없으면 재구성본이 원본으로 위장한다. */
+  reconstructed: boolean
+}
+
+/**
+ * 직렬화 키 순서(고정 — deterministic). `serializeManifestLine`과 같은 방식.
+ * 허용키 화이트리스트로도 쓰인다 — 여기 없는 top-level 키는 오염 신호로 거부한다.
+ *
+ * 🔴 **릴리스 후 스키마 변경은 additive-only여야 한다.** 키를 **제거**하면, 옛 스키마로 커밋된 기존 원장이
+ *    새 검증기에서 "알 수 없는 키"로 거부되고 D5 fail-closed가 그 티켓의 모든 리뷰를 막는다(실제로 이
+ *    REQ의 phase-2 개발 중 dogfood에서 발생했다 — 미커밋 원장이라 재생성으로 해결). 이 REQ는 **릴리스 전**이라
+ *    archive_path·archive_sha256을 제거해도 야생에 옛 원장이 없어 안전하다. 릴리스 후에는 키 추가만 하고,
+ *    값 확장은 forward-compatible하게(모르는 값은 거부 안 함, `lifecycle` 참조).
+ */
+export const LEDGER_KEYS = [
+  'ticket_id',
+  'series_id',
+  'review_kind',
+  'phase_id',
+  'attempt',
+  'event',
+  'lifecycle',
+  'outcome',
+  'exception_consumed',
+  'prompt_sha256',
+  'at',
+  'reconstructed',
+] as const
+
+const OUTCOMES: readonly string[] = ['approved', 'needs-fix', 'blocked', 'invalid']
+const EVENTS: readonly string[] = ['attempt-opened', 'attempt-closed']
+
+/** 한 줄 직렬화(JSONL): 고정 키 순서 JSON + 끝 개행. */
+export function serializeLedgerRow(row: LedgerRow): string {
+  const o: Record<string, unknown> = {}
+  for (const k of LEDGER_KEYS) o[k] = row[k]
+  return `${JSON.stringify(o)}\n`
+}
+
+/**
+ * 자연키 구분자 — **US(0x1F, unit separator)**.
+ *
+ * 왜 제어문자인가: 티켓 id·series id·phase id 어디에도 나타날 수 없어야 구분자 충돌로 서로 다른
+ * attempt가 같은 키로 접히지 않는다. 가시 문자(공백·`|`·`:`)는 series id(`design:-#1`)나 장래의
+ * phase id에 나타날 수 있다.
+ *
+ * 🔴 **소스에 제어문자 리터럴을 넣지 않는다** — `String.fromCharCode`로 만든다. 이 phase에서 실제로
+ *    원시 NUL 바이트가 소스에 박혀 git이 파일을 **binary로 취급**했고 grep·diff·리뷰가 전부 깨졌다.
+ *    테스트(`제어문자 리터럴 없음`)가 이 재발을 잠근다.
+ */
+const KEY_SEP = String.fromCharCode(31) // US(unit separator)
+
+/** 자연키 — 멱등 판정의 단위(D5). */
+export function ledgerRowKey(row: Pick<LedgerRow, 'ticket_id' | 'series_id' | 'attempt' | 'event'>): string {
+  return [row.ticket_id, row.series_id, String(row.attempt), row.event].join(KEY_SEP)
+}
+
+/**
+ * 행 하나의 형식 문제 목록(순수). 빈 배열 = 정상.
+ *
+ * 🔴 **비대칭이 의도다**(D3): 모르는 `lifecycle` **값**은 거부하지 않고(forward-compatible — 후속 REQ가
+ *    값을 늘리는 것이 정상 경로다), 모르는 top-level **키**는 거부한다(주입·오염 신호).
+ */
+export function ledgerRowProblems(raw: unknown): string[] {
+  const p: string[] = []
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return ['객체가 아님']
+  const r = raw as Record<string, unknown>
+
+  const allowed = new Set<string>(LEDGER_KEYS)
+  for (const k of Object.keys(r)) if (!allowed.has(k)) p.push(`알 수 없는 키: ${k}`)
+  for (const k of LEDGER_KEYS) if (!(k in r)) p.push(`필수 키 누락: ${k}`)
+  if (p.length) return p
+
+  if (typeof r.ticket_id !== 'string' || r.ticket_id === '') p.push('ticket_id가 비어 있음')
+  if (typeof r.series_id !== 'string' || r.series_id === '') p.push('series_id가 비어 있음')
+  if (r.review_kind !== 'design' && r.review_kind !== 'phase') p.push(`review_kind 부적합: ${String(r.review_kind)}`)
+  if (r.phase_id !== null && (typeof r.phase_id !== 'string' || r.phase_id === '')) p.push('phase_id는 null이거나 비지 않은 문자열')
+  if (typeof r.attempt !== 'number' || !Number.isInteger(r.attempt) || r.attempt < 1) p.push('attempt는 1 이상 정수')
+  if (typeof r.event !== 'string' || !EVENTS.includes(r.event)) p.push(`event 부적합: ${String(r.event)}`)
+  if (typeof r.exception_consumed !== 'boolean') p.push('exception_consumed는 boolean')
+  if (typeof r.reconstructed !== 'boolean') p.push('reconstructed는 boolean')
+  if (!isValidIsoInstant(r.at)) p.push('at이 ISO instant가 아님')
+  if (r.lifecycle !== null && typeof r.lifecycle !== 'string') p.push('lifecycle은 null이거나 문자열')
+  if (r.prompt_sha256 !== null && typeof r.prompt_sha256 !== 'string') p.push('prompt_sha256는 null이거나 문자열')
+
+  if (r.outcome !== null && (typeof r.outcome !== 'string' || !OUTCOMES.includes(r.outcome)))
+    p.push(`outcome 부적합: ${String(r.outcome)}`)
+
+  // 🔴 `attempt-opened`는 결과를 알 수 없는 시점이다 — 결과 필드가 채워져 있으면 순서가 뒤집힌 기록이다.
+  if (r.event === 'attempt-opened') {
+    for (const k of ['outcome', 'lifecycle'] as const) if (r[k] !== null) p.push(`attempt-opened인데 ${k}가 채워져 있음`)
+  }
+
+  // 🔴 `attempt-closed`는 판정이 끝난 시점이다 — 최소한 outcome·lifecycle은 있어야 한다(design 리뷰 observation).
+  //    이게 없으면 outcome=null인 closed 행이 통과해 "완료됐지만 판정 불명"이라는 자기모순 상태가 원장에 남는다.
+  if (r.event === 'attempt-closed') {
+    if (r.outcome === null) p.push('attempt-closed인데 outcome이 null')
+    if (r.lifecycle === null) p.push('attempt-closed인데 lifecycle이 null')
+  }
+  return p
+}
+
+export interface ParsedLedger {
+  rows: LedgerRow[]
+  /** 파싱·검증 문제. 비어 있지 않으면 손상 — 조용히 건너뛰지 않는다(D5). */
+  problems: string[]
+}
+
+/** 원장 본문 파싱(순수). 빈 줄은 무시하고, 파싱 불가·형식 위반은 problems로 드러낸다. */
+export function parseLedger(content: string): ParsedLedger {
+  const rows: LedgerRow[] = []
+  const problems: string[] = []
+  const lines = content.split('\n')
+  const seen = new Set<string>()
+  lines.forEach((line, i) => {
+    if (line.trim() === '') return
+    let raw: unknown
+    try {
+      raw = JSON.parse(line)
+    } catch {
+      problems.push(`line ${i + 1}: JSON 파싱 실패`)
+      return
+    }
+    const ps = ledgerRowProblems(raw)
+    if (ps.length) {
+      problems.push(...ps.map((m) => `line ${i + 1}: ${m}`))
+      return
+    }
+    const row = raw as LedgerRow
+    const key = ledgerRowKey(row)
+    if (seen.has(key)) problems.push(`line ${i + 1}: 자연키 중복(${row.series_id} attempt=${row.attempt} ${row.event})`)
+    seen.add(key)
+    rows.push(row)
+  })
+  return { rows, problems }
+}
+
+/** 멱등 append 결과. `appended`=신규 기록, `duplicate`=동일 내용 재기록(no-op), `conflict`=같은 키 다른 내용(fail-closed). */
+export type AppendOutcome = 'appended' | 'duplicate' | 'conflict'
+
+export interface AppendResult {
+  outcome: AppendOutcome
+  /** append 후 본문. `duplicate`·`conflict`면 입력과 동일하다(쓰기 금지). */
+  content: string
+  problems: string[]
+}
+
+/**
+ * 멱등 append(순수 — 새 본문을 **반환**만 한다. 쓰기는 호출부).
+ *
+ * - 같은 자연키 + 동일 내용 → `duplicate`(행 수 불변). crash 후 재실행이 중복을 만들지 않는다.
+ * - 같은 자연키 + 다른 내용 → `conflict`. **append하지도 덮지도 않는다.** 조용한 덮어쓰기는
+ *   append-only 원장의 신뢰를 무너뜨린다.
+ * - 기존 본문이 손상이면 그 문제를 그대로 올리고 append하지 않는다.
+ */
+export function appendLedgerRow(existingContent: string, row: LedgerRow): AppendResult {
+  const rowProblems = ledgerRowProblems(row)
+  if (rowProblems.length) return { outcome: 'conflict', content: existingContent, problems: rowProblems }
+
+  const parsed = parseLedger(existingContent)
+  if (parsed.problems.length) return { outcome: 'conflict', content: existingContent, problems: parsed.problems }
+
+  const key = ledgerRowKey(row)
+  const prior = parsed.rows.find((r) => ledgerRowKey(r) === key)
+  if (prior) {
+    const same = serializeLedgerRow(prior) === serializeLedgerRow(row)
+    return same
+      ? { outcome: 'duplicate', content: existingContent, problems: [] }
+      : {
+          outcome: 'conflict',
+          content: existingContent,
+          problems: [`같은 자연키의 기존 행과 내용이 다름(${row.series_id} attempt=${row.attempt} ${row.event}) — 덮어쓰지 않는다`],
+        }
+  }
+
+  const base = existingContent === '' || existingContent.endsWith('\n') ? existingContent : `${existingContent}\n`
+  return { outcome: 'appended', content: base + serializeLedgerRow(row), problems: [] }
+}
+
+/**
+ * `attempt-opened`만 있고 대응하는 `attempt-closed`가 없는 attempt (요구사항 #1).
+ *
+ * 이것이 곧 **"예산은 깎였는데 완료되지 않은 호출"**이다 — 외부 호출 실패나 응답 처리 실패로
+ * 아카이브도 측정 로그도 남지 않은 시도. 소비자 저장소에서 실측 1건(attempts 4 vs 아카이브 3)이 있었다.
+ */
+export function unclosedAttempts(rows: readonly LedgerRow[]): LedgerRow[] {
+  const closed = new Set(rows.filter((r) => r.event === 'attempt-closed').map((r) => [r.series_id, String(r.attempt)].join(KEY_SEP)))
+  return rows.filter((r) => r.event === 'attempt-opened' && !closed.has([r.series_id, String(r.attempt)].join(KEY_SEP)))
+}

package/scripts/req/lib/review-target.ts

@@ -0,0 +1,72 @@
+/**
+ * 현재 리뷰의 **semantic identity** 계산 (REQ-2026-052 phase-2).
+ *
+ * 왜 필요한가: pre-call 원장 커밋(DEC-A)이 매 라운드 HEAD·인덱스를 바꾸므로, approval binding
+ * (`reviewBaseSha`/`reviewTree`)은 라운드마다 값이 달라진다. 그런데 두 판정은 **같은 리뷰의 반복**을
+ * 감지해야 하므로 audit bookkeeping 변화에 흔들리면 안 된다:
+ *   - blocked-review circuit breaker(무한 재리뷰 차단)
+ *   - `last_review.compare_hash` · req:next G2(바인딩 신선도)
+ *
+ * 그래서 approval binding과 **분리된** semantic identity를 둔다: 리뷰 대상(design 문서·phase 코드)은
+ * 반영하되, 티켓의 `responses/` audit 산출물(ledger·approvals·아카이브·close-proof·codex-response·
+ * preview)의 변화는 **무시**한다.
+ *
+ * 🔴 **`responses/` 전체를 제외한다**(design-r03-delta P1): 처음엔 `review-ledger.jsonl` 한 줄만
+ *    제외했으나, evidence-finalize가 approvals·아카이브를 커밋하면 identity가 바뀌어 방금 승인한 리뷰를
+ *    req:next G2가 stale로 오판했다(요구 #4 위반). `responses/`는 **순수 audit**이고 리뷰 대상은 절대
+ *    그 안에 없다(design 문서=티켓 루트 `0N-*.md`, phase 코드=`workflow/` 밖). 따라서 `responses/`를
+ *    통째로 제외해도 리뷰 대상 손실 없이 pre-call 커밋·evidence-finalize 양쪽에 identity가 불변이다.
+ *
+ * 🔴 **`state.json`도 같은 이유로 제외한다**(REQ-2026-057). durable state checkpoint가 승인 상태를
+ *    커밋하면서 **인덱스의 `state.json` 항목**을 갱신하는데, 그것이 identity에 잡히면 방금 승인한 리뷰가
+ *    다시 stale로 오판된다 — `responses/`에서 이미 한 번 겪은 결함과 같은 형태다.
+ *    `state.json`은 **도구가 쓰는 작업 상태**이고 리뷰 대상이 아니다(사람이 리뷰받는 것은 설계 문서와
+ *    staged 코드다). 제외해도 승인 바인딩(D9 staged tree == approved tree)은 그대로이므로 방어가 약해지지
+ *    않는다 — identity는 "같은 리뷰의 반복인가"를 볼 뿐 승인 근거가 아니다.
+ *
+ * 🔴 **읽기 전용**: `git ls-files -s`만 쓴다. `git write-tree`는 object DB에 tree를 쓰므로 금지
+ *    (`captureIndexHash`와 같은 기법 — req:next가 재계산할 수 있어야 한다).
+ *
+ * 인터페이스는 이 함수 하나. git 필터링·정렬·hash 규칙을 전부 이 모듈에 숨긴다.
+ * 호출자: `review-codex`(생성) · `req:next`(G2 재계산) · 테스트.
+ */
+import { createHash } from 'node:crypto'
+
+/** `git ...` 실행 경계(review-codex의 `GitFn`과 호환 — 주입 가능·테스트용). */
+export type GitFn = (args: string[]) => string
+
+/** `git ls-files -s` 한 줄에서 경로(탭 뒤)를 뽑는다. 형식: `<mode> <oid> <stage>\t<path>`. */
+function pathOfLsFilesLine(line: string): string | null {
+  const tab = line.indexOf('\t')
+  return tab < 0 ? null : line.slice(tab + 1)
+}
+
+/**
+ * 현재 리뷰의 semantic identity(hex SHA256).
+ *
+ * = SHA256( 정렬된 `git ls-files -s` 줄들 중, 경로가 `<ticketRel>/responses/` 아래이거나
+ *   정확히 `<ticketRel>/state.json`인 줄을 제외 ).
+ *
+ * 원장·approvals·아카이브·작업 상태가 untracked/modified/committed 어느 상태든 제외되므로 identity가
+ * 그 변화에 불변이다. 리뷰 대상(문서·코드)과 그 밖의 non-audit 변경은 반영된다.
+ */
+export function computeReviewSemanticIdentity(ticketRel: string, gitFn: GitFn): string {
+  const normTicket = ticketRel.replace(/\\/g, '/').replace(/\/+$/, '')
+  // 🔴 ticketRel 경계가 애매하면(빈 값) fail-closed — 잘못된 접두사로 무언가를 조용히 제외하지 않는다.
+  if (normTicket === '') throw new Error('computeReviewSemanticIdentity: ticketRel이 비어 있음(제외 경계 불명 — fail-closed)')
+  const responsesPrefix = `${normTicket}/responses/` // 🔴 정확히 이 티켓의 responses/ 하위만. 다른 workflow 파일·문서·코드 미제외.
+  // 🔴 `state.json`은 **정확 일치**로만 제외한다(REQ-2026-057). 접두사 매칭으로 넓히면
+  //    `state.json.bak` 같은 사용자 파일까지 조용히 사라진다.
+  const statePath = `${normTicket}/state.json`
+  const lines = gitFn(['ls-files', '-s'])
+    .split('\n')
+    .map((l) => l.replace(/\r$/, ''))
+    .filter((l) => l.trim() !== '')
+    .filter((l) => {
+      const p = pathOfLsFilesLine(l)
+      // 🔴 경로를 못 뽑으면(malformed) **보수적으로 포함**한다 — 모호한 경로를 제외하지 않는다(constraint 3).
+      //    제외는 명확히 `<ticketRel>/responses/` 하위이거나 `<ticketRel>/state.json`일 때만.
+      return p === null ? true : !p.startsWith(responsesPrefix) && p !== statePath
+    })
+  return createHash('sha256').update([...lines].sort().join('\n')).digest('hex')
+}

package/scripts/req/lib/scratch.ts

@@ -20,6 +20,14 @@ import { isUntracked } from './porcelain'
 /** 티켓 디렉터리 안의 순수 untracked 도구 산출물. 커밋된 적이 없고 승인 증거가 아니다. */
 export const TOOL_OUTPUT_BASENAMES = ['codex-response.json', '.review-preview.txt'] as const
 
+/**
+ * 리뷰 원장(REQ-2026-051)의 티켓-상대 경로. `state.json`과 **같은 범주**다 — 워크플로가 리뷰 중에
+ * (attempt-opened/closed) `responses/` 아래에 쓰는 메타데이터이고, 승인 시점에 커밋된다.
+ * 🔴 exact 경로로만 허용한다(rename/카피는 아래 responses/ 규칙으로 여전히 차단) — `responses/**` 전체를
+ *    scratch로 열면 승인 아카이브 변조 구멍이 된다(REQ-2026-012 D8).
+ */
+export const REVIEW_LEDGER_RELNAME = 'responses/review-ledger.jsonl' as const
+
 /** 경로 정규화: 역슬래시→슬래시(호출부가 넘기는 repo-상대는 이미 `/`지만 방어), 후행 슬래시 제거. */
 function normDir(dirRel: string): string {
   return dirRel.replace(/\\/g, '/').replace(/\/+$/, '')
@@ -31,7 +39,12 @@ function normDir(dirRel: string): string {
  */
 export function reviewScratchPaths(ticketDirRel: string): string[] {
   const dir = normDir(ticketDirRel)
-  return [`${dir}/${TOOL_OUTPUT_BASENAMES[0]}`, `${dir}/${TOOL_OUTPUT_BASENAMES[1]}`, `${dir}/state.json`]
+  return [
+    `${dir}/${TOOL_OUTPUT_BASENAMES[0]}`,
+    `${dir}/${TOOL_OUTPUT_BASENAMES[1]}`,
+    `${dir}/state.json`,
+    `${dir}/${REVIEW_LEDGER_RELNAME}`, // REQ-2026-051: 리뷰 중 append되는 원장(state.json과 동종). exact 경로만.
+  ]
 }
 
 /** `REQ-<4자리>-<숫자>` 디렉터리명인가(문자열 분해 — 정규식 보간 금지, 설계 D7). */

package/scripts/req/lib/state-checkpoint.ts

@@ -0,0 +1,78 @@
+/**
+ * 티켓 `state.json`의 **durable checkpoint** (REQ-2026-057).
+ *
+ * 존재 이유: 승인 증거(`responses/**`)는 커밋되는데 그 승인을 반영한 **작업 상태는 커밋되지 않아**,
+ * 티켓을 정상 완주해도 `state.json`이 dirty로 남는다. 그 결과 (1) 다음 `req:new`가 clean-tree 게이트에서
+ * 막히고(`lib/scratch.ts`의 `isToolOutputScratch`는 `state.json`을 **의도적으로** 제외한다),
+ * (2) 계약이 시키는 대로 그 변경을 버리면 커밋된 증거가 있는데도 `req:next`가 재리뷰를 요구한다.
+ * 남겨도 막히고 버려도 안 되는 상태를 없애려면 상태가 증거와 함께 Git에 남아야 한다.
+ *
+ * 🔴 **leaf 모듈이다.** `review-codex`·`req-commit` 양쪽이 값으로 import하므로 여기서 그것들을 값으로
+ *    import하면 런타임 순환이 생긴다(`lib/scratch.ts`가 leaf인 이유와 같다). 상태 타입은
+ *    `import type`(컴파일 시 소거)으로만 받는다.
+ *
+ * 🔴 **증거 커밋에 상태를 끼워 넣지 않는다**(설계 DEC-1). 그러려면 `req-commit`의 "`responses/` 외 staged
+ *    금지" 가드를 완화해야 하는데, 그 가드는 코드/state 누수를 막는 마지막 방어선이다. 대신 티켓
+ *    `state.json` **한 경로만** 담는 자기 커밋을 낸다 — `precallCommitLedgerRow`와 같은 pathspec 관용구다.
+ *
+ * ⚠️ 원자성: 증거 커밋과 이 커밋 사이에서 중단되면 `state.json`이 dirty로 남는다. 그것은 **이 REQ 이전의
+ *    기존 동작**이므로 회귀가 아니고, 재실행(멱등)이나 다음 경계의 checkpoint가 흡수한다.
+ */
+import { existsSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+/** `state.json` 직렬화의 **단일 지점**. `review-codex`의 `writeState`가 이 함수를 쓴다(포맷 드리프트 금지). */
+export function serializeState(state: unknown): string {
+  return `${JSON.stringify(state, null, 2)}\n`
+}
+
+export interface StateCheckpointArgs {
+  /** 소비 저장소 루트(절대 경로). */
+  root: string
+  /** 티켓 디렉터리의 repo-상대 경로(예: `workflow/REQ-2026-057`). */
+  ticketRel: string
+  /** 대상 티켓 id. 디스크 상태의 `id`와 대조한다. */
+  ticketId: string
+  /** 호출자가 **방금 `writeState`로 기록한** 상태 객체. 디스크 내용과 바이트 대조한다. */
+  state: { id?: unknown }
+  /** 커밋 메시지에 들어갈 사유(예: `design 승인`, `phase phase-1-x 소비`). */
+  reason: string
+  /** git 실행기(호출부의 어댑터를 그대로 받는다 — 테스트가 주입 가능). */
+  gitFn: (args: string[]) => string
+}
+
+/**
+ * 티켓 `state.json`을 pathspec 커밋한다.
+ *
+ * @returns 커밋했으면 `true`, **변경이 없어 무동작이면 `false`**(멱등 — 빈 커밋을 만들지 않는다).
+ *
+ * fail-closed 조건(둘 다 커밋 없이 throw):
+ *   - 디스크 내용이 `state`의 직렬화와 다르다 → 외부 편집·경쟁 쓰기. 도구가 쓴 값만 커밋한다.
+ *   - 디스크 상태의 `id`가 `ticketId`와 다르다 → 다른 티켓 상태를 이 티켓 커밋에 싣지 않는다.
+ */
+export function commitStateCheckpoint(args: StateCheckpointArgs): boolean {
+  const { root, ticketRel, ticketId, state, reason, gitFn } = args
+  const stateRel = `${ticketRel}/state.json`
+  const stateAbs = join(root, ...stateRel.split('/'))
+
+  // 멱등: 워킹트리·인덱스 어느 쪽에도 변화가 없으면 낼 커밋이 없다.
+  if (gitFn(['status', '--porcelain', '--', stateRel]).trim() === '') return false
+
+  if (!existsSync(stateAbs)) throw new Error(`state checkpoint 거부: ${stateRel} 이 없습니다.`)
+  const onDisk = readFileSync(stateAbs, 'utf8')
+  if (onDisk !== serializeState(state))
+    throw new Error(
+      `state checkpoint 거부: ${stateRel} 의 디스크 내용이 도구가 기록한 상태와 다릅니다(외부 편집·경쟁 쓰기 의심) — 커밋하지 않았습니다.`,
+    )
+
+  // `state`가 아니라 **디스크**의 id를 본다 — 커밋되는 것이 디스크 내용이기 때문이다.
+  // (위 바이트 대조를 통과했으므로 두 값은 같지만, 판정 대상을 커밋 대상과 일치시켜 둔다.)
+  const diskId = (JSON.parse(onDisk) as { id?: unknown }).id
+  if (diskId !== ticketId)
+    throw new Error(`state checkpoint 거부: ${stateRel} 의 id(${String(diskId)})가 대상 티켓(${ticketId})과 다릅니다.`)
+
+  // 🔴 pathspec 커밋 — 이 경로만. 사용자가 stage해 둔 코드/문서는 인덱스에 그대로 남는다.
+  gitFn(['add', '--', stateRel])
+  gitFn(['commit', '-m', `chore(${ticketId}): state checkpoint — ${reason}`, '--', stateRel])
+  return true
+}

package/scripts/req/req-close.ts

@@ -0,0 +1,222 @@
+#!/usr/bin/env tsx
+/**
+ * req:close — 레거시 완료 티켓 **마이그레이션 종결**(REQ-2026-053·DEC-M).
+ *
+ * close-proof/`phase_design_ref` regime **이전에** 완료·병합돼 dev-complete로 자기증명될 수 없는 durable
+ * 티켓을, 운영자 확인 후 `migrated-complete` close-proof 행으로 감사 가능하게 종결한다. 자격 판정은
+ * `lib/close-migrate`(순수)가, HEAD blob 수집·integrated 계산·durable 커밋은 이 CLI가 낸다.
+ *
+ * 🔴 **HEAD-committed 증거 + git ancestry만** 근거로 쓴다 — 워킹 state·미커밋 원장·추정 phase 목록 미사용.
+ * 🔴 완료성 증명 = **integrated**(티켓 매니페스트 커밋이 본선 조상). mainline ref는 **운영자 입력을 받지 않고**
+ *    신뢰된 ref로만 해소(origin/HEAD→origin/main→로컬 main). 미해소면 fail-closed.
+ * 🔴 기본 **dry-run**. `--run` 후에만 write. 새 행은 `reconstructed:true` + 비어있지 않은 evidence_basis.
+ *    쓰기 전 close-proof clean 가드(미커밋 close-proof를 HEAD 기반 쓰기가 덮지 않게). append-only·자연키 멱등.
+ *
+ * 사용: req:close <REQ> --migrate [--run] [--root <dir>]
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { dirname, join, relative } from 'node:path'
+import { pathToFileURL } from 'node:url'
+import { loadConfig, packageRoot } from './lib/config'
+import { createGitAdapter, safeSpawnSyncStatus, type GitAdapter } from './lib/adapters'
+import { createEvidencePorts } from './lib/evidence-ports'
+import {
+  isDurabilityRequired,
+  verifyCommittedEvidenceIntegrity,
+  validateManifest,
+  evidencedPhaseIdsFromManifest,
+  designHashFromManifest,
+} from './lib/evidence'
+import { parseCloseProof, appendCloseProofRow, closeProofPath } from './lib/close-proof'
+import { planMigrationClose, type MigrationFacts } from './lib/close-migrate'
+
+let gitAdapter: GitAdapter = createGitAdapter(packageRoot())
+function git(args: string[]): string {
+  return gitAdapter.exec(args)
+}
+
+export interface Opts {
+  reqId: string | null
+  migrate: boolean
+  run: boolean
+  root: string | null
+}
+
+/** 인자 파싱(fail-closed): 값 누락·알 수 없는 옵션은 즉시 throw. mainline override는 **의도적으로 없다**(DEC-M3.7). */
+export function parseArgs(argv: string[]): Opts {
+  const o: Opts = { reqId: null, migrate: false, run: 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 === '--migrate') o.migrate = true
+    else if (a === '--run') o.run = 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
+}
+
+/**
+ * 🔴 mainline ref를 **신뢰된 소스로만** 해소한다(DEC-M3.7·r02 P1). 운영자 입력을 받지 않는다 —
+ *    임의 feature/HEAD ref로 integrated를 통과시키는 우회를 막는다. 순서:
+ *    ① origin/HEAD(원격이 선언한 기본 브랜치) → ② origin/main·master → ③ 로컬 main·master. 없으면 null(fail-closed).
+ */
+export function resolveMainline(gitFn: (a: string[]) => string): string | null {
+  try {
+    const sym = gitFn(['symbolic-ref', '--quiet', 'refs/remotes/origin/HEAD']).trim()
+    if (sym) return sym.replace(/^refs\/remotes\//, '') // 예: refs/remotes/origin/main → origin/main
+  } catch {
+    /* origin/HEAD 없음 — 다음 후보로 */
+  }
+  for (const ref of ['origin/main', 'origin/master', 'main', 'master']) {
+    try {
+      if (gitFn(['rev-parse', '--verify', '--quiet', ref]).trim()) return ref
+    } catch {
+      /* 해당 ref 없음 */
+    }
+  }
+  return null
+}
+
+/** `git merge-base --is-ancestor a b` — a가 b의 조상이면 true(exit 0), 아니면 false(exit 1), 그 외는 throw. */
+export function isAncestor(root: string, a: string, b: string): boolean {
+  const res = safeSpawnSyncStatus('git', ['merge-base', '--is-ancestor', a, b], { cwd: root })
+  if (res.status === 0) return true
+  if (res.status === 1) return false
+  throw new Error(`git merge-base --is-ancestor 실패(status=${res.status ?? 'null'}): ${res.stderr.trim()}`)
+}
+
+/** HEAD state.json 본문에서 커밋된 phase 계획 id(`phases[].id`)를 뽑는다(파싱 불가·부재 → []). r02 P1 완료성 기준. */
+export function committedPlannedPhaseIds(stateText: string | null): string[] {
+  if (!stateText) return []
+  let raw: unknown
+  try {
+    raw = JSON.parse(stateText)
+  } catch {
+    return []
+  }
+  const phases = (raw as { phases?: unknown }).phases
+  if (!Array.isArray(phases)) return []
+  return phases
+    .map((p) => (p && typeof p === 'object' ? (p as { id?: unknown }).id : undefined))
+    .filter((id): id is string => typeof id === 'string' && id.length > 0)
+}
+
+export function main(argv: string[] = process.argv.slice(2)): void {
+  const o = parseArgs(argv)
+  if (!o.reqId) throw new Error('REQ 필요 (예: req:close 2026-049 --migrate)')
+  if (!o.migrate) throw new Error('현재 --migrate 모드만 지원합니다 (예: req:close 2026-049 --migrate --run)')
+  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 manifestRel = `${ticketRel}/responses/approvals.jsonl`
+
+  // 1. HEAD 사실 수집(read-only). intake와 같은 포트·함수.
+  const ports = createEvidencePorts(cfg.root, `${ticketRel}/responses`)
+  const stateText = ports.headText(`${ticketRel}/state.json`)
+  const durabilityRequired = isDurabilityRequired(stateText)
+  const manifestText = ports.headText(manifestRel)
+  const closeText = ports.headText(closeProofPath(ticketRel))
+  const evidencedPhaseIdsAll = manifestText ? evidencedPhaseIdsFromManifest(manifestText) : []
+  const manifestProblems = manifestText ? validateManifest(manifestText, { ticketRel, validPhaseIds: evidencedPhaseIdsAll }) : []
+  const closeParsed = closeText ? parseCloseProof(closeText) : { rows: [], problems: [] }
+  const committedDesignRef = manifestText ? designHashFromManifest(manifestText) : null
+  const evidencedPhaseIdsBound = manifestText ? evidencedPhaseIdsFromManifest(manifestText, committedDesignRef) : []
+  const integrity = verifyCommittedEvidenceIntegrity({ ticketRel, manifestText, ports })
+
+  // 2. integrated(완료성 증명) — 티켓 매니페스트를 마지막으로 수정한 HEAD 커밋이 mainline의 조상인가.
+  const mainline = resolveMainline((a) => git(a))
+  if (!mainline)
+    throw new Error(
+      `${reqId}: mainline(main/origin/main)을 결정할 수 없어 integrated(완료성)를 판정할 수 없습니다 — fail-closed. ` +
+        `본선 브랜치가 존재하는 저장소에서 실행하세요.`,
+    )
+  let lastManifestCommit = ''
+  try {
+    lastManifestCommit = git(['rev-list', '-1', 'HEAD', '--', manifestRel]).trim()
+  } catch {
+    lastManifestCommit = ''
+  }
+  const integrated = !!lastManifestCommit && isAncestor(cfg.root, lastManifestCommit, mainline)
+
+  // 3. 순수 판정.
+  const facts: MigrationFacts = {
+    ticketId: reqId,
+    ticketRel,
+    durabilityRequired,
+    manifestText,
+    manifestProblems,
+    closeProblems: closeParsed.problems,
+    closeRows: closeParsed.rows,
+    evidenceIntegrityProblems: integrity.problems,
+    committedDesignRef,
+    evidencedPhaseIdsAll,
+    evidencedPhaseIdsBound,
+    committedPlannedPhaseIds: committedPlannedPhaseIds(stateText),
+    integrated,
+    nowIso: new Date().toISOString(),
+    evidenceBasis: [manifestRel], // 마이그레이션 근거: 티켓 매니페스트(design_hash·phase_design_ref·archive_inventory의 단일 출처).
+  }
+  const plan = planMigrationClose(facts)
+
+  if (plan.kind === 'refuse')
+    throw new Error(`${reqId} 마이그레이션 종결 불가: ${plan.reason}\n  → ${plan.hint}`)
+  if (plan.kind === 'noop') {
+    console.log(`[req:close] ${reqId} 이미 종결(${plan.existingState}) — no-op(write 0).`)
+    return
+  }
+
+  // plan.kind === 'stamp'
+  console.log(`[req:close] ${reqId} 마이그레이션 종결(migrated-complete) 계획 (integrated=본선 조상, mainline=${mainline}):`)
+  console.log(
+    `  phase_inventory=[${plan.row.phase_inventory?.join(', ')}] design_ref=${(plan.row.design_ref ?? '').slice(0, 12)} ` +
+      `evidence_basis=[${plan.row.evidence_basis?.join(', ')}]`,
+  )
+  if (!o.run) {
+    console.log('[req:close] DRY-RUN — write 없음(--run 시 실행).')
+    return
+  }
+
+  // 🔴 쓰기 전 clean 가드: close-proof가 HEAD와 동일해야(미커밋 close-proof를 HEAD 기반 쓰기가 잃지 않게).
+  const cpRel = closeProofPath(ticketRel)
+  const cpDirty = git(['status', '--porcelain', '--', cpRel]).trim()
+  if (cpDirty)
+    throw new Error(
+      `${reqId}: close-proof(${cpRel})에 미커밋 변경이 있어 종결을 거부합니다(fail-closed) — HEAD 기반 쓰기가 미커밋 행을 덮을 수 있습니다.\n` +
+        `  먼저 미커밋 close-proof 변경을 커밋/정리한 뒤 다시 실행하세요.`,
+    )
+
+  const abs = join(cfg.root, cpRel)
+  const existing = existsSync(abs) ? readFileSync(abs, 'utf8') : ''
+  const res = appendCloseProofRow(existing, plan.row)
+  if (res.outcome === 'conflict') throw new Error(`close proof 충돌(fail-closed): ${res.problems.join('; ')}`)
+  if (res.outcome === 'duplicate') {
+    console.log('[req:close] 동일 migrated-complete 행이 이미 존재 — no-op(멱등).')
+    return
+  }
+  mkdirSync(dirname(abs), { recursive: true })
+  writeFileSync(abs, res.content, 'utf8')
+  git(['add', '--', cpRel])
+  git(['commit', '-m', `chore(${reqId}): migrated-complete close proof (레거시 마이그레이션 종결·REQ-2026-053)`, '--', cpRel])
+  console.log(`[req:close] ✅ ${reqId} migrated-complete 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()