commitgate 0.9.8 → 0.9.9

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

@@ -0,0 +1,233 @@
+/**
+ * 커밋되는 **리뷰 예외 부여 원장** (REQ-2026-055·DEC-RE3).
+ *
+ * needs-exception 구간에서 사람이 부여한 예외의 **구조화 rationale**을 durable하게 남긴다. `review_exception_confirmed`
+ * (state.json scratch)는 소비 후 null이 되지만 이 파일은 남아 "왜 예산을 넘겼나"의 감사가 된다.
+ *
+ * 🔴 **B1 review-ledger 스키마를 건드리지 않는다**(전용 sibling 파일) — 릴리스된 원장에 필수 키를 더하면 기존
+ *    커밋 원장이 "필수 키 누락"으로 D5 fail-closed된다(B1 자체 경고). 이 파일은 자체 스키마다.
+ * 🔴 review-ledger가 본문을 뺀 것과 달리 이 파일은 rationale **본문을 담는다** — 이 파일의 목적이 그 내용이다.
+ *
+ * 순수 모듈 — fs·git을 모른다. 부작용은 호출부가 낸다(`lib/review-ledger`·`lib/close-proof`와 같은 태도).
+ */
+import { isValidIsoInstant } from './evidence'
+import type { ReviewKind } from '../review-codex'
+
+/** 예외 부여 파일의 basename. `review-ledger.jsonl`·`ticket-close.jsonl`과 같은 `responses/` 디렉터리. */
+export const EXCEPTION_BASENAME = 'review-exceptions.jsonl'
+
+/** 티켓 `responses/` 기준 예외 원장의 repo-상대 경로. */
+export function exceptionsPath(ticketRel: string): string {
+  return `${ticketRel.replace(/\\/g, '/').replace(/\/+$/, '')}/responses/${EXCEPTION_BASENAME}`
+}
+
+/** 구조화 rationale 4섹션(전부 비어있지 않아야 함). */
+export interface Rationale {
+  prev_findings: string
+  changes: string
+  unresolved: string
+  retry_justification: string
+}
+export const RATIONALE_KEYS = ['prev_findings', 'changes', 'unresolved', 'retry_justification'] as const
+
+export interface ExceptionGrantRow {
+  ticket_id: string
+  review_kind: ReviewKind
+  phase_id: string | null
+  series_id: string
+  /** 이 예외가 유효한 회차(= consumeReviewException의 for_attempt·checkReviewBudget의 attempt). */
+  for_attempt: number
+  /** 받은 승인 문장 그대로. */
+  method: string
+  confirmed_at: string
+  rationale: Rationale
+  /** 사후 복원 행인지(원본과 구별). 정상 부여는 false. */
+  reconstructed: boolean
+}
+
+/** 직렬화 키 순서(고정) + 허용키 화이트리스트. */
+export const EXCEPTION_KEYS = [
+  'ticket_id',
+  'review_kind',
+  'phase_id',
+  'series_id',
+  'for_attempt',
+  'method',
+  'confirmed_at',
+  'rationale',
+  'reconstructed',
+] as const
+
+/** 한 줄 직렬화(JSONL): 고정 키 순서(rationale 내부도 고정) + 끝 개행. */
+export function serializeExceptionGrantRow(row: ExceptionGrantRow): string {
+  const rationale: Record<string, unknown> = {}
+  for (const k of RATIONALE_KEYS) rationale[k] = row.rationale[k]
+  const o: Record<string, unknown> = {}
+  for (const k of EXCEPTION_KEYS) o[k] = k === 'rationale' ? rationale : row[k]
+  return `${JSON.stringify(o)}\n`
+}
+
+/** 자연키 구분자 — US(0x1F). 식별자에 나타날 수 없는 제어문자(review-ledger와 같은 기법·소스에 리터럴 금지). */
+const KEY_SEP = String.fromCharCode(31)
+
+/** 자연키 — `(ticket, series, for_attempt)`. 한 series의 한 회차에 예외 1개. */
+export function exceptionGrantRowKey(row: Pick<ExceptionGrantRow, 'ticket_id' | 'series_id' | 'for_attempt'>): string {
+  return [row.ticket_id, row.series_id, String(row.for_attempt)].join(KEY_SEP)
+}
+
+/** rationale 객체 형식 문제(순수). 빈 배열=정상. 4섹션 전부 비어있지 않은 문자열. */
+function rationaleProblems(raw: unknown): string[] {
+  const p: string[] = []
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return ['rationale가 객체가 아님']
+  const r = raw as Record<string, unknown>
+  const allowed = new Set<string>(RATIONALE_KEYS)
+  for (const k of Object.keys(r)) if (!allowed.has(k)) p.push(`rationale 알 수 없는 키: ${k}`)
+  for (const k of RATIONALE_KEYS) {
+    const v = r[k]
+    if (typeof v !== 'string' || v.trim() === '') p.push(`rationale.${k}가 비어 있음`)
+  }
+  return p
+}
+
+/** 행 하나의 형식 문제 목록(순수). 빈 배열 = 정상. 모르는 top-level 키는 거부(주입 방어). */
+export function exceptionGrantRowProblems(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>(EXCEPTION_KEYS)
+  for (const k of Object.keys(r)) if (!allowed.has(k)) p.push(`알 수 없는 키: ${k}`)
+  for (const k of EXCEPTION_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 (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.series_id !== 'string' || r.series_id === '') p.push('series_id가 비어 있음')
+  if (typeof r.for_attempt !== 'number' || !Number.isInteger(r.for_attempt) || r.for_attempt < 1) p.push('for_attempt는 1 이상 정수')
+  if (typeof r.method !== 'string' || r.method.trim() === '') p.push('method가 비어 있음')
+  if (!isValidIsoInstant(r.confirmed_at)) p.push('confirmed_at이 ISO instant가 아님')
+  if (typeof r.reconstructed !== 'boolean') p.push('reconstructed는 boolean')
+  p.push(...rationaleProblems(r.rationale))
+  return p
+}
+
+export interface ParsedExceptions {
+  rows: ExceptionGrantRow[]
+  problems: string[]
+}
+
+/** 본문 파싱(순수). 빈 줄 무시, 파싱 불가·형식 위반·자연키 중복은 problems로 드러낸다(조용히 건너뛰지 않음). */
+export function parseExceptions(content: string): ParsedExceptions {
+  const rows: ExceptionGrantRow[] = []
+  const problems: string[] = []
+  const seen = new Set<string>()
+  content.split('\n').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 = exceptionGrantRowProblems(raw)
+    if (ps.length) {
+      problems.push(...ps.map((m) => `line ${i + 1}: ${m}`))
+      return
+    }
+    const row = raw as ExceptionGrantRow
+    const key = exceptionGrantRowKey(row)
+    if (seen.has(key)) problems.push(`line ${i + 1}: 자연키 중복(${row.series_id} for_attempt=${row.for_attempt})`)
+    seen.add(key)
+    rows.push(row)
+  })
+  return { rows, problems }
+}
+
+/** material 동일성(순수) — method + rationale만 비교(confirmed_at 제외). 재실행 멱등 판정용. */
+export function materialEqual(a: ExceptionGrantRow, b: ExceptionGrantRow): boolean {
+  if (a.method !== b.method) return false
+  return RATIONALE_KEYS.every((k) => a.rationale[k] === b.rationale[k])
+}
+
+/** 자연키로 기존 부여 행 조회(순수). 없으면 null. 호출부가 confirmed_at 재사용에 쓴다(재실행 복구). */
+export function findExistingGrant(content: string, key: Pick<ExceptionGrantRow, 'ticket_id' | 'series_id' | 'for_attempt'>): ExceptionGrantRow | null {
+  const parsed = parseExceptions(content)
+  if (parsed.problems.length) return null // 손상은 append 단계가 conflict로 처리한다.
+  const k = exceptionGrantRowKey(key)
+  return parsed.rows.find((r) => exceptionGrantRowKey(r) === k) ?? null
+}
+
+export type ExceptionAppendOutcome = 'appended' | 'duplicate' | 'conflict'
+export interface ExceptionAppendResult {
+  outcome: ExceptionAppendOutcome
+  content: string
+  problems: string[]
+}
+
+/**
+ * 멱등 append(순수 — 새 본문 반환만). 🔴 **material 멱등**(DEC-RE3): 같은 자연키 + method·rationale 같으면
+ * duplicate(confirmed_at 달라도), material 다르면 conflict(같은 회차 다른 예외 — 덮지 않음·fail-closed).
+ * 기존 본문 손상이면 그대로 올리고 append하지 않는다(D5 태도).
+ */
+export function appendExceptionGrant(existingContent: string, row: ExceptionGrantRow): ExceptionAppendResult {
+  const rowProblems = exceptionGrantRowProblems(row)
+  if (rowProblems.length) return { outcome: 'conflict', content: existingContent, problems: rowProblems }
+
+  const parsed = parseExceptions(existingContent)
+  if (parsed.problems.length) return { outcome: 'conflict', content: existingContent, problems: parsed.problems }
+
+  const key = exceptionGrantRowKey(row)
+  const prior = parsed.rows.find((r) => exceptionGrantRowKey(r) === key)
+  if (prior) {
+    return materialEqual(prior, row)
+      ? { outcome: 'duplicate', content: existingContent, problems: [] }
+      : {
+          outcome: 'conflict',
+          content: existingContent,
+          problems: [`같은 회차(${row.series_id} #${row.for_attempt})에 다른 예외가 이미 있음 — 덮지 않는다`],
+        }
+  }
+  const base = existingContent === '' || existingContent.endsWith('\n') ? existingContent : `${existingContent}\n`
+  return { outcome: 'appended', content: base + serializeExceptionGrantRow(row), problems: [] }
+}
+
+// ───────────────────────────────── rationale 파일 파서(순수) ──
+
+/** rationale 마크다운 섹션 헤더 → 필드. */
+const RATIONALE_SECTIONS: ReadonlyArray<{ header: string; field: keyof Rationale }> = [
+  { header: '직전 findings', field: 'prev_findings' },
+  { header: '이번 변경', field: 'changes' },
+  { header: '미해결', field: 'unresolved' },
+  { header: '재시도 근거', field: 'retry_justification' },
+]
+
+export type RationaleParse = { ok: true; rationale: Rationale } | { ok: false; problems: string[] }
+
+/**
+ * rationale 마크다운 파싱(순수). `## <헤더>` 4섹션의 본문을 뽑아 전부 비어있지 않으면 ok.
+ * 형식은 자유(마크다운) — 존재·비-빔만 강제한다. 누락·빈 섹션은 어느 것인지 알린다.
+ */
+export function parseRationale(text: string): RationaleParse {
+  const lines = text.split('\n')
+  const bodies = new Map<keyof Rationale, string[]>()
+  let current: keyof Rationale | null = null
+  for (const line of lines) {
+    const m = /^##\s+(.+?)\s*$/.exec(line)
+    if (m) {
+      const sec = RATIONALE_SECTIONS.find((s) => m[1] === s.header)
+      current = sec ? sec.field : null // 알 수 없는 헤더는 어느 섹션에도 안 담는다.
+      if (current && !bodies.has(current)) bodies.set(current, [])
+      continue
+    }
+    if (current) bodies.get(current)!.push(line)
+  }
+  const problems: string[] = []
+  const rationale = {} as Rationale
+  for (const { header, field } of RATIONALE_SECTIONS) {
+    const body = (bodies.get(field) ?? []).join('\n').trim()
+    if (body === '') problems.push(`rationale 섹션 "## ${header}"가 없거나 비어 있음`)
+    rationale[field] = body
+  }
+  return problems.length ? { ok: false, problems } : { ok: true, rationale }
+}

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,61 @@
+/**
+ * 현재 리뷰의 **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가 불변이다.
+ *
+ * 🔴 **읽기 전용**: `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/` 아래인 줄을 제외 ).
+ *
+ * 원장·approvals·아카이브가 untracked/modified/committed 어느 상태든 `responses/` 경로라 제외되므로
+ * identity가 그 변화에 불변이다. 리뷰 대상(문서·코드)과 `responses/` 밖의 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 파일·문서·코드 미제외.
+  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/` 하위일 때만.
+      return p === null ? true : !p.startsWith(responsesPrefix)
+    })
+  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). */