commitgate 0.9.8 → 0.9.10

package/scripts/req/lib/intake.ts

@@ -0,0 +1,175 @@
+/**
+ * req:new intake gate (REQ-2026-052 phase-3b, DEC-C) — 새 REQ 생성 전, **HEAD-committed durable 증거만으로**
+ * 각 기존 티켓의 기본 상태를 파생해 미종결(developing/needs-recovery) durable 티켓이 있으면 fail-closed로 막는다.
+ *
+ * 🔴 판정 입력은 **오직 HEAD blob**: scaffold marker(`state.json`)·`approvals.jsonl`·`ticket-close.jsonl`·
+ *    `review-ledger.jsonl`. 워킹 `state.json`·워킹트리·미커밋 원장은 절대 보지 않는다(DEC-B4). 스캔은 git
+ *    **조회만**(read-only) — write-tree·commit·state 수정 없음.
+ * 🔴 **corrupt/부분 HEAD 증거**(매니페스트·close-proof 손상)는 pass 조건(dev-complete/series-terminal)이 읽는
+ *    아티팩트이므로, 손상 시 통과시키지 않고 **block**한다(fail-closed). 손상된 신호로 완료를 위장할 수 없다.
+ * 🔴 오버레이(`integrated`·`reconstructed`)는 기본 상태 판정을 바꾸지 않는다 — 게이트는 `baseStateBlocksIntake`
+ *    (기본 상태만) 으로 결정한다. legacy(durability marker 없음)는 차단하지 않고 표시만 한다.
+ *
+ * 순수 판정(`classifyIntake`)과 IO 수집(`scanTicketIntake`·`scanIntake`)을 분리한다.
+ */
+import {
+  deriveBaseState,
+  baseStateBlocksIntake,
+  isReconstructed,
+  parseCloseProof,
+  type CloseBaseState,
+  type CloseProofRow,
+} from './close-proof'
+import {
+  isDurabilityRequired,
+  verifyCommittedEvidenceIntegrity,
+  validateManifest,
+  evidencedPhaseIdsFromManifest,
+  designHashFromManifest,
+} from './evidence'
+import { parseLedger } from './review-ledger'
+import { createEvidencePorts } from './evidence-ports'
+
+export type IntakeVerdict = 'pass' | 'block' | 'legacy'
+
+export interface IntakeTicketResult {
+  ticketId: string
+  ticketRel: string
+  /** 파생 기본 상태. 매니페스트/close-proof 손상은 5-상태 밖의 `corrupt`(항상 block). */
+  baseState: CloseBaseState | 'corrupt'
+  verdict: IntakeVerdict
+  reason: string
+  /** `reconstructed` 오버레이(표시용 — 게이트 판정엔 영향 없음). */
+  reconstructed: boolean
+}
+
+export interface IntakeFacts {
+  ticketId: string
+  ticketRel: string
+  /** HEAD scaffold marker(`isDurabilityRequired`). false면 legacy. */
+  durabilityRequired: boolean
+  /** HEAD approvals.jsonl 본문(없으면 null). */
+  manifestText: string | null
+  /** `validateManifest` 결과(빈 배열=정상). 비어있지 않으면 corrupt block. */
+  manifestProblems: string[]
+  /** HEAD ticket-close.jsonl 파싱 결과. problems 비어있지 않으면 corrupt block. */
+  closeParsed: { rows: CloseProofRow[]; problems: string[] }
+  /** 🔴 committed 증거(design+phase) 무결성 문제(DEC-B6·B7). 비어있지 않으면 corrupt block(삭제/변조). */
+  evidenceIntegrityProblems: string[]
+  ledgerHasApprovedClose: boolean
+  committedEvidenceComplete: boolean
+  committedDesignRef: string | null
+  /** **design-bound**(현재 committed design_ref에 결속된) phase evidence의 phase id. */
+  evidencedPhaseIds: string[]
+}
+
+/**
+ * HEAD 사실 → intake 판정(순수). corrupt(매니페스트/close-proof 손상)는 기본 상태 밖의 별도 block 사유다.
+ */
+export function classifyIntake(facts: IntakeFacts): IntakeTicketResult {
+  const head = { ticketId: facts.ticketId, ticketRel: facts.ticketRel }
+  // legacy(durability marker 없음)는 차단하지 않고 표시만(DEC-C·요구).
+  if (!facts.durabilityRequired)
+    return { ...head, baseState: 'legacy', verdict: 'legacy', reason: 'legacy 티켓(durability marker 없음) — 표시만, 차단 안 함', reconstructed: false }
+  // 🔴 pass 조건(dev-complete/series-terminal)이 읽는 아티팩트가 손상됐으면 통과 금지(fail-closed).
+  if (facts.manifestText !== null && facts.manifestProblems.length)
+    return { ...head, baseState: 'corrupt', verdict: 'block', reason: `HEAD approvals.jsonl 손상 — 통과 불가(fail-closed): ${facts.manifestProblems.slice(0, 3).join('; ')}`, reconstructed: false }
+  if (facts.closeParsed.problems.length)
+    return { ...head, baseState: 'corrupt', verdict: 'block', reason: `HEAD ticket-close.jsonl 손상 — 통과 불가(fail-closed): ${facts.closeParsed.problems.slice(0, 3).join('; ')}`, reconstructed: false }
+  // 🔴 DEC-B6·B7: committed 증거(design·phase archive) blob 부재/변조도 통과 조건이 읽는 증거의 손상 →
+  //    corrupt block(dev-complete·series-terminal 위장 차단). design 행이 없는 미완 티켓은 손상 대상 아님(불완전≠손상).
+  if (facts.evidenceIntegrityProblems.length)
+    return { ...head, baseState: 'corrupt', verdict: 'block', reason: `committed 증거 손상 — 통과 불가(fail-closed): ${facts.evidenceIntegrityProblems.slice(0, 3).join('; ')}`, reconstructed: false }
+  const state = deriveBaseState({
+    durabilityRequired: true,
+    closeProofRows: facts.closeParsed.rows,
+    ledgerHasApprovedClose: facts.ledgerHasApprovedClose,
+    committedEvidenceComplete: facts.committedEvidenceComplete,
+    evidencedPhaseIds: facts.evidencedPhaseIds,
+    committedDesignRef: facts.committedDesignRef,
+  })
+  const blocked = baseStateBlocksIntake(state) // 기본 상태만 본다 — 오버레이 무관(요구).
+  const reason = blocked
+    ? state === 'developing'
+      ? '미종결 durable 티켓(developing) — 모든 phase 완료·커밋 또는 종결 후 재시도'
+      : 'HEAD 증거 불일치(needs-recovery) — 승인 흔적은 있으나 커밋된 증거 불완전, 복구 필요'
+    : state === 'dev-complete'
+      ? '개발 완료(dev-complete)'
+      : state === 'series-terminal'
+        ? 'series 종결(replace/human-resolution)'
+        : // 🔴 REQ-2026-053: migrated-complete는 **phase-1(커밋 3ed1b95 close-proof.ts)**에서 event·base-state·
+          //    파서·deriveBaseState(dev-complete 아래·needs-recovery 위 비차단)로 이미 확장됐다. 이 phase-2 diff는
+          //    명령(req:close)과 이 reason 케이스만 추가한다. 종결→pass 전 파이프라인은 req-close.test.ts ⑮가 실증.
+          state === 'migrated-complete'
+          ? '개발 완료(마이그레이션 종결·migrated-complete)'
+          : String(state)
+  return { ...head, baseState: state, verdict: blocked ? 'block' : 'pass', reason, reconstructed: isReconstructed(facts.closeParsed.rows) }
+}
+
+/**
+ * 한 티켓의 HEAD 사실을 모아 판정(IO — git 조회만, read-only). `ports`가 HEAD blob 접근 정본.
+ */
+export function scanTicketIntake(root: string, ticketRel: string, ticketId: string): IntakeTicketResult {
+  const ports = createEvidencePorts(root, `${ticketRel}/responses`)
+  const durabilityRequired = isDurabilityRequired(ports.headText(`${ticketRel}/state.json`))
+  if (!durabilityRequired)
+    return classifyIntake({ ticketId, ticketRel, durabilityRequired: false, manifestText: null, manifestProblems: [], closeParsed: { rows: [], problems: [] }, evidenceIntegrityProblems: [], ledgerHasApprovedClose: false, committedEvidenceComplete: false, committedDesignRef: null, evidencedPhaseIds: [] })
+  const manifestText = ports.headText(`${ticketRel}/responses/approvals.jsonl`)
+  const closeText = ports.headText(`${ticketRel}/responses/ticket-close.jsonl`)
+  const ledgerText = ports.headText(`${ticketRel}/responses/review-ledger.jsonl`)
+  // validPhaseIds는 매니페스트 자신의 phase 행 id로 만든다(HEAD state.phases는 설계상 []이므로 멤버십 검사만 무효화 —
+  // verifyCommittedDesignEvidence와 동일 기법). 나머지 구조·경로·sha·주입·kind 격리·phase_design_ref 형식은 강제된다.
+  const manifestPhaseIds = manifestText ? evidencedPhaseIdsFromManifest(manifestText) : []
+  const manifestProblems = manifestText ? validateManifest(manifestText, { ticketRel, validPhaseIds: manifestPhaseIds }) : []
+  const closeParsed = closeText ? parseCloseProof(closeText) : { rows: [], problems: [] }
+  const ledgerParsed = ledgerText ? parseLedger(ledgerText) : { rows: [], problems: [] }
+  const ledgerHasApprovedClose = ledgerParsed.rows.some((r) => r.event === 'attempt-closed' && r.outcome === 'approved')
+  const committedDesignRef = manifestText ? designHashFromManifest(manifestText) : null
+  const evidencedPhaseIds = manifestText ? evidencedPhaseIdsFromManifest(manifestText, committedDesignRef) : []
+  // 🔴 DEC-B7: committed 증거(design+phase) 무결성 종합 — intake·req:commit 공유 모듈. designEvidenceComplete로
+  //    needs-recovery 판정 입력(committedEvidenceComplete)을 같은 조회에서 얻는다(중복 조회 없음).
+  const integrity = verifyCommittedEvidenceIntegrity({ ticketRel, manifestText, ports })
+  return classifyIntake({ ticketId, ticketRel, durabilityRequired: true, manifestText, manifestProblems, closeParsed, evidenceIntegrityProblems: integrity.problems, ledgerHasApprovedClose, committedEvidenceComplete: integrity.designEvidenceComplete, committedDesignRef, evidencedPhaseIds })
+}
+
+/**
+ * HEAD tree의 `workflow/REQ-*` 디렉터리 이름(정렬). 🔴 **워킹 디렉터리를 읽지 않는다**(HEAD only).
+ *
+ * 🔴 **후행 슬래시가 load-bearing이다**: `git ls-tree -d --name-only HEAD workflow/`(슬래시 有)는 `workflow/`의
+ *    **직계 자식 tree**(= `workflow/REQ-*`)를 열거한다. 슬래시가 **없으면**(`workflow`) ls-tree는 그 항목 자신
+ *    (`workflow`) 한 줄만 낸다 → 자식을 못 보고 스캔이 통째로 비어 **게이트가 우회된다**. 그래서 아래에서 항상
+ *    `${dir}/`로 슬래시를 붙인다. 이 정상 경로는 `req-new-intake.test.ts`의 실 git 열거·생성 전 차단 e2e가 고정한다
+ *    (열거가 비면 developing 티켓이 차단되지 않아 그 테스트가 실패한다).
+ */
+export function listHeadTicketIds(workflowDirRel: string, gitFn: (a: string[]) => string): string[] {
+  const dir = workflowDirRel.replace(/\\/g, '/').replace(/\/+$/, '')
+  let out: string
+  try {
+    out = gitFn(['ls-tree', '-d', '--name-only', 'HEAD', `${dir}/`]) // 🔴 후행 슬래시 필수(직계 자식 열거).
+  } catch {
+    return [] // workflow/ 가 HEAD에 없음(첫 REQ 등) → 스캔 대상 없음.
+  }
+  return out
+    .split('\n')
+    .map((l) => l.trim())
+    .filter(Boolean)
+    .map((p) => p.split('/').pop() ?? '')
+    .filter((n) => /^REQ-\d{4}-\d+$/.test(n))
+    .sort()
+}
+
+/**
+ * HEAD의 `workflow/REQ-*` 티켓 전부를 스캔(read-only). `excludeTicketId`(대체될 부모 등)는 스캔에서 제외한다 —
+ * 그 티켓은 지금 정규 replace 흐름으로 종결되므로 후속 생성을 막아선 안 된다(제외는 부모의 replace 검증이 이미 끝난 뒤에만 쓴다).
+ */
+export function scanIntake(
+  root: string,
+  workflowDirRel: string,
+  gitFn: (a: string[]) => string,
+  excludeTicketId?: string | null,
+): { tickets: IntakeTicketResult[]; blocked: IntakeTicketResult[] } {
+  const ticketIds = listHeadTicketIds(workflowDirRel, gitFn).filter((id) => id !== excludeTicketId)
+  const dir = workflowDirRel.replace(/\\/g, '/').replace(/\/+$/, '')
+  const tickets = ticketIds.map((id) => scanTicketIntake(root, `${dir}/${id}`, id))
+  return { tickets, blocked: tickets.filter((t) => t.verdict === 'block') }
+}

package/scripts/req/lib/lockfile-diff.ts

@@ -0,0 +1,127 @@
+/**
+ * lockfile diff **요약** (REQ-2026-056·DEC-E1).
+ *
+ * `git diff --cached` 전문이 리뷰 프롬프트에 들어가는데, lockfile(`package-lock.json`·`pnpm-lock.yaml` 등)은
+ * 수천 줄 기계생성이라 토큰을 낭비하고 사람/리뷰어 신호를 묻는다. lockfile 구획의 hunk를 **요약**(경로·헤더
+ * 보존 + ±N/M + 생략분 sha256)으로 대체한다.
+ *
+ * 🔴 **프롬프트만 바꾼다** — 승인 바인딩(reviewTree = git write-tree)은 전체 index라 이 문자열 변형과 무관하다.
+ *    승인은 여전히 전체 lockfile을 결속한다(이 모듈은 그 사실을 강제하지 않지만, 호출부가 stagedDiff 문자열에만
+ *    이 변형을 적용한다).
+ *
+ * 순수 모듈 — fs·git을 모른다(deterministic·`createHash`만).
+ */
+import { createHash } from 'node:crypto'
+
+/** lockfile로 인식할 basename(정확 일치만 — 경로 부분문자열 오탐 방지). */
+export const LOCKFILE_NAMES: ReadonlySet<string> = new Set([
+  'package-lock.json',
+  'npm-shrinkwrap.json',
+  'pnpm-lock.yaml',
+  'yarn.lock',
+  'bun.lockb',
+])
+
+/** 경로 접두(`a/`·`b/`)·git C-quote(따옴표)를 벗겨 정규화한다. */
+function stripPathDecoration(raw: string): string {
+  let t = raw.trim()
+  if (t.length >= 2 && t.startsWith('"') && t.endsWith('"')) t = t.slice(1, -1) // git quoted path
+  if (t.startsWith('a/') || t.startsWith('b/')) t = t.slice(2)
+  return t
+}
+
+/**
+ * 한 구획의 **모든 후보 경로**를 헤더 줄에서 모은다(r01 P1). `diff --git`의 양쪽 경로는 공백에서 모호하므로
+ * `---`/`+++`/`rename from|to`/`copy from|to`/`Binary files … differ`의 명시 경로도 함께 본다 —
+ * rename(한쪽만 lockfile)·공백/따옴표 경로에서도 인식되게.
+ */
+function sectionPaths(section: string[]): string[] {
+  const paths: string[] = []
+  const add = (p: string | undefined): void => {
+    if (p === undefined) return
+    const s = stripPathDecoration(p)
+    if (s && s !== '/dev/null') paths.push(s)
+  }
+  for (const line of section) {
+    if (line.startsWith('--- ')) add(line.slice(4))
+    else if (line.startsWith('+++ ')) add(line.slice(4))
+    else if (line.startsWith('rename from ')) add(line.slice(12))
+    else if (line.startsWith('rename to ')) add(line.slice(10))
+    else if (line.startsWith('copy from ')) add(line.slice(10))
+    else if (line.startsWith('copy to ')) add(line.slice(8))
+    else if (line.startsWith('Binary files ')) {
+      const m = /^Binary files (.+) and (.+) differ$/.exec(line)
+      if (m) { add(m[1]); add(m[2]) }
+    } else if (line.startsWith('diff --git ')) {
+      const m = /^diff --git (.+) (.+)$/.exec(line) // best-effort(공백 경로면 ---/+++가 보완)
+      if (m) { add(m[1]); add(m[2]) }
+    }
+  }
+  return paths
+}
+
+/** 경로 basename이 lockfile인가(정확 일치). */
+export function isLockfilePath(path: string): boolean {
+  const base = path.replace(/\\/g, '/').split('/').pop() ?? ''
+  return LOCKFILE_NAMES.has(base)
+}
+
+/** 구획이 lockfile을 다루는가(양쪽 경로·rename·binary 헤더 모두 검사). */
+function sectionIsLockfile(section: string[]): { yes: boolean; display: string } {
+  const paths = sectionPaths(section)
+  const lock = paths.find(isLockfilePath)
+  return { yes: lock !== undefined, display: lock ?? paths[paths.length - 1] ?? '(lockfile)' }
+}
+
+/** 한 파일 구획(`diff --git`으로 시작하는 줄 배열)을 요약(lockfile일 때만). 비-lockfile은 그대로. */
+function summarizeSection(section: string[]): string[] {
+  const { yes, display: path } = sectionIsLockfile(section)
+  if (!yes) return section
+
+  const hunkIdx = section.findIndex((l) => l.startsWith('@@ '))
+  if (hunkIdx >= 0) {
+    const header = section.slice(0, hunkIdx)
+    const hunks = section.slice(hunkIdx)
+    // `+++`/`---`는 파일 헤더라 hunkIdx 이후엔 없지만 방어적으로 제외한다.
+    const plus = hunks.filter((l) => l.startsWith('+') && !l.startsWith('+++')).length
+    const minus = hunks.filter((l) => l.startsWith('-') && !l.startsWith('---')).length
+    const sha = createHash('sha256').update(hunks.join('\n'), 'utf8').digest('hex').slice(0, 12)
+    return [
+      ...header,
+      `# [lockfile 전문 생략 — 요약 모드] ${path}: +${plus}/-${minus} lines · sha256(생략분)=${sha} · 전문은 config lockfilePromptFull:true`,
+    ]
+  }
+  const binaryIdx = section.findIndex((l) => l.startsWith('Binary files ') && l.includes(' differ'))
+  if (binaryIdx >= 0) {
+    return [...section.slice(0, binaryIdx), `# [lockfile binary 변경 — 요약 모드] ${path} · 전문은 config lockfilePromptFull:true`]
+  }
+  // hunk도 binary도 없음(순수 rename/mode 변경 등) — 헤더만 작으니 그대로 둔다.
+  return section
+}
+
+/**
+ * staged diff의 lockfile 구획을 요약한다(순수). `opts.full`이면 원문 그대로.
+ * 🔴 lockfile 구획이 하나도 없으면 **완전 no-op**(입력===출력) — 기존 byte-identical near-e2e 무회귀.
+ */
+export function summarizeLockfileDiff(stagedDiff: string, opts: { full: boolean }): string {
+  if (opts.full || stagedDiff === '') return stagedDiff
+  const lines = stagedDiff.split('\n')
+  const starts: number[] = []
+  for (let i = 0; i < lines.length; i++) if (lines[i]!.startsWith('diff --git ')) starts.push(i)
+  if (starts.length === 0) return stagedDiff // 표준 파일 구획 없음 → 손대지 않는다.
+
+  // 구획별로 요약(비-lockfile은 그대로). 요약이 하나도 일어나지 않으면 원문 반환(no-op 보장).
+  const result: string[] = []
+  if (starts[0]! > 0) result.push(...lines.slice(0, starts[0]!)) // 첫 구획 前 preamble(있으면) 보존.
+  let changed = false
+  for (let s = 0; s < starts.length; s++) {
+    const from = starts[s]!
+    const to = s + 1 < starts.length ? starts[s + 1]! : lines.length
+    const section = lines.slice(from, to)
+    const summarized = summarizeSection(section)
+    if (summarized !== section) changed = true // summarizeSection은 요약 시에만 새 배열을 반환한다.
+    result.push(...summarized)
+  }
+  if (!changed) return stagedDiff // lockfile 구획 없음(또는 요약 대상 없음) → 원문 그대로.
+  return result.join('\n')
+}

package/scripts/req/lib/reconstruct.ts

@@ -0,0 +1,118 @@
+/**
+ * req:reconstruct 복원 가능성 매트릭스 (REQ-2026-052 phase-4·DEC-D2) — **순수** 산출.
+ *
+ * 🔴 close-proof lifecycle event는 `dev-complete`·`series-terminal` 둘뿐이다. 이 모듈은 **HEAD-committed
+ *    immutable evidence가 행의 모든 필드를 명확·모호없이 결정할 때만** 복원 후보를 낸다:
+ *   - **dev-complete**: 🔴 **절대 산출하지 않는다.** `phase_inventory`를 approvals.jsonl의 phase_id 집합으로
+ *     합성하면 계획됐으나 미커밋인 phase를 조용히 빼는 DEC-B5 P1이 재발한다. inventory 독립 기록이 없으므로
+ *     self-verifying 행이 없으면 복원 근거가 없다 → 재검토·재내구화가 유일 경로.
+ *   - **series-terminal(replace)**: 커밋된 **successor** 티켓의 `successor_of`(parent_series_id 포함)가
+ *     이 티켓 replace 종결을 완전히 증명할 때만.
+ *   - **series-terminal(terminate)**: successor를 만들지 않아 증거가 없다 → 불가.
+ *
+ * fs·git·review-codex를 모르는 leaf(부작용·evidence 추출은 CLI가 한다).
+ */
+import { type CloseProofRow, closeProofRowKey } from './close-proof'
+
+/** 이 티켓을 replace 부모로 지목하는 committed successor의 추출 증거(CLI가 HEAD blob에서 뽑아 넣는다). */
+export interface SuccessorEvidence {
+  /** successor 티켓 id(진단용). */
+  successorTicketId: string
+  /** successor `state.json`의 repo-상대 경로 — evidence_basis. */
+  successorStatePath: string
+  /** `successor_of.parent_series_id` — 부모의 replace 종결 series_id. */
+  parentSeriesId: string
+  /** 종결 사유. successor는 항상 `replace`(collect가 그렇게 거른다) — material field로 명시 검사한다. */
+  resolution: 'replace'
+  /** `successor_of.parent_replace_resolution.decided_at` — 종결 시점(부모 값). */
+  at: string
+}
+
+export interface ReconstructCandidate {
+  row: CloseProofRow
+  evidenceBasis: string[]
+}
+
+export interface ReconstructPlan {
+  /** 복원 예정(신규) 행. */
+  candidates: ReconstructCandidate[]
+  /** 복원 불가·불필요·모호 사유(진단 표시용 — write는 안 하지만 명령은 계속). */
+  refusals: string[]
+  /** 🔴 fail-closed conflict(HEAD 모순) — 하나라도 있으면 CLI는 **전체를 write 0으로 중단**한다. */
+  conflicts: string[]
+}
+
+/**
+ * 이 티켓의 복원 가능한 close-proof 행을 매트릭스(DEC-D2 multi-witness)대로 산출(순수). dev-complete는 절대 산출 안 함.
+ *
+ * 🔴 **parent_series_id별 그룹화**: 같은 series를 가리키는 복수 witness의 material field(resolution·at)가 **전부 일치**할
+ *    때만 후보 1개(evidence_basis=모든 successor state 경로 정렬·중복제거). 불일치=ambiguity refusal(그 series write 0).
+ * 🔴 **HEAD 정합**: 같은 자연키 행이 HEAD에 있으면 material 일치=멱등 no-op, 모순=**conflict**(숨기지 않고 fail-closed).
+ *
+ * @param existingRows 이 티켓 HEAD close-proof를 파싱한 행들. 손상 티켓은 CLI가 이 함수 **전에** 거른다.
+ * @param successors 이 티켓을 부모로 지목하는 committed successor 증거들.
+ */
+export function planReconstruction(args: {
+  ticketId: string
+  existingRows: readonly CloseProofRow[]
+  successors: readonly SuccessorEvidence[]
+}): ReconstructPlan {
+  const candidates: ReconstructCandidate[] = []
+  const refusals: string[] = []
+  const conflicts: string[] = []
+
+  // ① parent_series_id별 그룹화(빈 필드는 미결정으로 개별 refusal).
+  const groups = new Map<string, SuccessorEvidence[]>()
+  for (const s of args.successors) {
+    if (!s.parentSeriesId || !s.at || !s.resolution) {
+      refusals.push(`successor ${s.successorTicketId}: parent_series_id·resolution·at 중 미결정 → 복원 불가(모호)`)
+      continue
+    }
+    const g = groups.get(s.parentSeriesId)
+    if (g) g.push(s)
+    else groups.set(s.parentSeriesId, [s])
+  }
+
+  for (const seriesId of [...groups.keys()].sort()) {
+    const witnesses = groups.get(seriesId)!
+    // ② material field(resolution·at) 전부 일치해야 후보. 불일치=ambiguity(그 series 후보 없음).
+    const ats = new Set(witnesses.map((w) => w.at))
+    const resolutions = new Set(witnesses.map((w) => w.resolution))
+    if (ats.size > 1 || resolutions.size > 1) {
+      refusals.push(
+        `series ${seriesId}: 복수 successor의 material field 불일치(at=[${[...ats].sort().join(', ')}] resolution=[${[...resolutions].sort().join(', ')}]) → ambiguity 복원 불가(write 0)`,
+      )
+      continue
+    }
+    const at = witnesses[0]!.at
+    const resolution = witnesses[0]!.resolution
+    // 완전 일치하는 복수 witness → evidence_basis에 모든 경로 정렬·중복제거.
+    const evidenceBasis = [...new Set(witnesses.map((w) => w.successorStatePath))].sort()
+    const row: CloseProofRow = {
+      ticket_id: args.ticketId,
+      event: 'series-terminal',
+      series_id: seriesId,
+      resolution,
+      phase_inventory: null,
+      design_ref: null,
+      at,
+      reconstructed: true,
+      evidence_basis: evidenceBasis,
+    }
+    // ③ HEAD 정합: 같은 자연키 행이 있으면 material 일치=멱등 no-op, 모순=conflict(fail-closed).
+    const key = closeProofRowKey(row)
+    const prior = args.existingRows.find((r) => closeProofRowKey(r) === key)
+    if (prior) {
+      if (prior.resolution === resolution && prior.at === at) {
+        refusals.push(`series ${seriesId}: 동일 series-terminal 행이 HEAD에 존재 → 복원 불필요(멱등 no-op)`)
+      } else {
+        conflicts.push(
+          `series ${seriesId}: HEAD 행과 모순(HEAD at=${prior.at} resolution=${prior.resolution} ≠ 후보 at=${at} resolution=${resolution}) → fail-closed(숨기지 않음)`,
+        )
+      }
+      continue
+    }
+    candidates.push({ row, evidenceBasis })
+  }
+  return { candidates, refusals, conflicts }
+}

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 }
+}