commitgate 0.9.6 → 0.9.9

package/scripts/req/lib/close-proof.ts

@@ -0,0 +1,323 @@
+/**
+ * 커밋되는 **티켓 lifecycle close proof** (REQ-2026-052).
+ *
+ * 왜 원장과 별도인가: `review-ledger.jsonl`(B1)은 **attempt 단위**(opened/closed) 감사다. close proof는
+ * **티켓/series 단위 lifecycle 전이**(replace·human-resolution 종결, 개발 완료)를 담는다. 요구가 "사람이
+ * 실행하는 종결 경로는 ledger와 close proof를 **함께** 내구화"라 명시하므로 둘을 섞지 않는다.
+ *
+ * 🔴 **모든 판정은 HEAD-committed 아티팩트만** 입력이다 — 워킹 state·워킹 승인은 절대 쓰지 않는다.
+ *    scratch state가 사라져도 HEAD만으로 티켓 상태·req:new 허용·재구성 여부를 판별할 수 있어야 한다.
+ *
+ * 🔴 **prompt·응답 본문·민감 데이터를 저장하지 않는다.** 허용키 화이트리스트가 자리 자체를 막는다.
+ *
+ * 순수 모듈 — fs·git을 모른다. 부작용은 호출부가 낸다(`lib/evidence`·`lib/review-ledger`와 같은 태도).
+ */
+import { isValidIsoInstant } from './evidence'
+
+/** close proof 파일의 basename. `approvals.jsonl`·`review-ledger.jsonl`과 같은 `responses/` 디렉터리. */
+export const CLOSE_PROOF_BASENAME = 'ticket-close.jsonl'
+
+/** 티켓 `responses/` 기준 close proof의 repo-상대 경로. */
+export function closeProofPath(ticketRel: string): string {
+  return `${ticketRel.replace(/\\/g, '/').replace(/\/+$/, '')}/responses/${CLOSE_PROOF_BASENAME}`
+}
+
+/**
+ * lifecycle 전이 종류(DEC-B).
+ * - `series-terminal`: 사람이 한 series를 replace/human-resolution으로 종결(원장과 함께 커밋).
+ * - `dev-complete`: 모든 phase 증거가 durable해진 시점(마지막 evidence-finalize 직후 방출).
+ * - `migrated-complete`(REQ-2026-053): close-proof/`phase_design_ref` regime **이전에** 완료·병합돼
+ *   dev-complete로 자기증명될 수 없는 레거시 티켓을, 운영자가 완료 확인 후 남기는 **사후 마이그레이션 종결**
+ *   (`reconstructed:true` 강제 — self-verifying dev-complete와 구별). `req:close --migrate`가 발행.
+ *
+ * 🔴 `integrated`는 여기 없다 — git ancestry로 관측하는 오버레이이지 커밋되는 전이가 아니다(DEC-B).
+ */
+export type CloseProofEvent = 'series-terminal' | 'dev-complete' | 'migrated-complete'
+
+/** series-terminal의 종결 사유(사람 결정). */
+export type TerminalResolution = 'replace' | 'human-resolution'
+
+export interface CloseProofRow {
+  ticket_id: string
+  event: CloseProofEvent
+  /** `series-terminal`일 때 그 series의 id. `dev-complete`이면 null. */
+  series_id: string | null
+  /** `series-terminal`일 때 종결 사유. `dev-complete`이면 null. */
+  resolution: TerminalResolution | null
+  /**
+   * 🔴 `dev-complete`일 때 **완료 대상으로 확정된 phase ID 목록**(정렬·중복 없음, DEC-B2). `series-terminal`이면 null.
+   *    이것이 "무엇이 완료인가"의 정본이다 — 미래 HEAD verifier는 runtime `state.phases`가 아니라 이 목록을 본다.
+   */
+  phase_inventory: string[] | null
+  /**
+   * 🔴 `dev-complete`일 때 이 inventory가 묶인 **design 승인 참조**(= 발행 시점 committed design 승인의 design_hash).
+   *    `series-terminal`이면 null. design 재승인으로 inventory가 달라지면 옛 design_ref와 섞인 proof는 무효(DEC-B2).
+   */
+  design_ref: string | null
+  at: string
+  /** 사후 복원 행인지(DEC-D). 복원본을 원본으로 위장하지 않는다. */
+  reconstructed: boolean
+  /**
+   * 복원 행일 때 그 사실을 유도한 근거(어떤 아카이브·매니페스트). 원본(비복원) 행이면 null.
+   * 🔴 본문이 아니라 **경로/식별자 목록**이다 — 민감 데이터를 담지 않는다.
+   */
+  evidence_basis: string[] | null
+}
+
+/** 직렬화 키 순서(고정 — deterministic) + 허용키 화이트리스트(여기 없는 top-level 키 = 오염 → 거부). */
+export const CLOSE_PROOF_KEYS = [
+  'ticket_id',
+  'event',
+  'series_id',
+  'resolution',
+  'phase_inventory',
+  'design_ref',
+  'at',
+  'reconstructed',
+  'evidence_basis',
+] as const
+
+const EVENTS: readonly string[] = ['series-terminal', 'dev-complete', 'migrated-complete']
+const RESOLUTIONS: readonly string[] = ['replace', 'human-resolution']
+
+/** 한 줄 직렬화(JSONL): 고정 키 순서 JSON + 끝 개행. */
+export function serializeCloseProofRow(row: CloseProofRow): string {
+  const o: Record<string, unknown> = {}
+  for (const k of CLOSE_PROOF_KEYS) o[k] = row[k]
+  return `${JSON.stringify(o)}\n`
+}
+
+/**
+ * 자연키(멱등 판정 단위). `series-terminal`은 `(ticket, event, series)`, `dev-complete`은 `(ticket, event)`.
+ * 구분자는 US(0x1F) — 식별자에 나타날 수 없는 제어문자(원장과 동일 기법, 소스에 리터럴 금지).
+ */
+const KEY_SEP = String.fromCharCode(31)
+/**
+ * 자연키(멱등·supersede 단위).
+ * - `series-terminal`: `(ticket, event, series_id)` — series별 1행.
+ * - `dev-complete`: `(ticket, event, design_ref)` 🔴 **design_ref로 키잉한다**(phase-3a r02 P1). design 재승인으로
+ *   design_ref가 바뀌면 **다른 자연키**가 되어 새 dev-complete 행이 append-only로 추가된다(옛 행은 supersede —
+ *   삭제하지 않고, verifier가 현재 design_ref에 맞는 행만 고른다). design_ref로 키잉하지 않으면 재완료가
+ *   자연키 충돌(conflict)로 영구 실패한다.
+ */
+export function closeProofRowKey(row: Pick<CloseProofRow, 'ticket_id' | 'event' | 'series_id' | 'design_ref'>): string {
+  // dev-complete: design_ref(재승인 supersede). series-terminal: series_id(series별 1행).
+  // migrated-complete(REQ-2026-053): discriminator 없음 — 티켓당 1행(마이그레이션은 일회성).
+  const discriminator =
+    row.event === 'dev-complete' ? (row.design_ref ?? '') : row.event === 'series-terminal' ? (row.series_id ?? '') : ''
+  return [row.ticket_id, row.event, discriminator].join(KEY_SEP)
+}
+
+/** `dev-complete`·`migrated-complete` 공유: phase_inventory 형식 검증(비지 않은 문자열·정렬·중복 없음). */
+function phaseInventoryProblems(v: unknown, eventLabel: string): string[] {
+  const p: string[] = []
+  if (!Array.isArray(v)) {
+    p.push(`${eventLabel}인데 phase_inventory가 배열이 아님`)
+    return p
+  }
+  if (v.length === 0) p.push(`${eventLabel}인데 phase_inventory가 비어 있음`)
+  if (!v.every((x) => typeof x === 'string' && x !== '')) p.push('phase_inventory 항목은 비지 않은 문자열')
+  const sorted = [...v].sort()
+  if (JSON.stringify(sorted) !== JSON.stringify(v)) p.push('phase_inventory가 정렬돼 있지 않음')
+  if (new Set(v).size !== v.length) p.push('phase_inventory에 중복 있음')
+  return p
+}
+
+/**
+ * 행 하나의 형식 문제 목록(순수). 빈 배열 = 정상.
+ * 🔴 모르는 top-level 키는 거부(주입·오염 방어). `dev-complete`·`migrated-complete`은 series/resolution이 null이어야 한다.
+ */
+export function closeProofRowProblems(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>(CLOSE_PROOF_KEYS)
+  for (const k of Object.keys(r)) if (!allowed.has(k)) p.push(`알 수 없는 키: ${k}`)
+  for (const k of CLOSE_PROOF_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.event !== 'string' || !EVENTS.includes(r.event)) p.push(`event 부적합: ${String(r.event)}`)
+  if (typeof r.reconstructed !== 'boolean') p.push('reconstructed는 boolean')
+  if (!isValidIsoInstant(r.at)) p.push('at이 ISO instant가 아님')
+
+  if (r.event === 'series-terminal') {
+    if (typeof r.series_id !== 'string' || r.series_id === '') p.push('series-terminal인데 series_id가 비어 있음')
+    if (typeof r.resolution !== 'string' || !RESOLUTIONS.includes(r.resolution))
+      p.push(`series-terminal인데 resolution 부적합: ${String(r.resolution)}`)
+    if (r.phase_inventory !== null) p.push('series-terminal인데 phase_inventory가 null이 아님')
+    if (r.design_ref !== null) p.push('series-terminal인데 design_ref가 null이 아님')
+  } else if (r.event === 'dev-complete') {
+    if (r.series_id !== null) p.push('dev-complete인데 series_id가 null이 아님')
+    if (r.resolution !== null) p.push('dev-complete인데 resolution이 null이 아님')
+    // 🔴 dev-complete는 self-verifying — phase_inventory(정렬·중복 없음)와 design_ref가 필수(DEC-B2).
+    p.push(...phaseInventoryProblems(r.phase_inventory, 'dev-complete'))
+    if (typeof r.design_ref !== 'string' || r.design_ref === '') p.push('dev-complete인데 design_ref가 비어 있음')
+  } else if (r.event === 'migrated-complete') {
+    // 🔴 REQ-2026-053(DEC-M2): 운영자 확인 마이그레이션 종결. dev-complete와 같은 phase_inventory·design_ref를
+    //    담되 self-verifying이 아니라 **사후 스탬프**임을 스키마가 드러낸다 — reconstructed===true 강제.
+    if (r.series_id !== null) p.push('migrated-complete인데 series_id가 null이 아님')
+    if (r.resolution !== null) p.push('migrated-complete인데 resolution이 null이 아님')
+    p.push(...phaseInventoryProblems(r.phase_inventory, 'migrated-complete'))
+    if (typeof r.design_ref !== 'string' || r.design_ref === '') p.push('migrated-complete인데 design_ref가 비어 있음')
+    // 🔴 마이그레이션은 항상 사후 스탬프 — reconstructed:true 필수(evidence_basis 비-빔은 아래 공통 규칙이 강제).
+    if (r.reconstructed !== true) p.push('migrated-complete인데 reconstructed가 true가 아님(마이그레이션은 사후 스탬프)')
+  }
+
+  if (r.evidence_basis !== null) {
+    if (!Array.isArray(r.evidence_basis)) p.push('evidence_basis는 null이거나 배열')
+    else if (!r.evidence_basis.every((x) => typeof x === 'string')) p.push('evidence_basis 항목은 문자열')
+  }
+  // 🔴 복원 행이면 근거가 있어야 하고, 비복원 행이면 근거가 없어야 한다(원본과 복원의 명확한 구별).
+  if (r.reconstructed === true && (r.evidence_basis === null || (Array.isArray(r.evidence_basis) && r.evidence_basis.length === 0)))
+    p.push('reconstructed:true인데 evidence_basis가 비어 있음(근거 없는 복원 금지)')
+  if (r.reconstructed === false && r.evidence_basis !== null) p.push('원본 행(reconstructed:false)인데 evidence_basis가 있음')
+  return p
+}
+
+export interface ParsedCloseProof {
+  rows: CloseProofRow[]
+  problems: string[]
+}
+
+/** close proof 본문 파싱(순수). 빈 줄 무시, 파싱 불가·형식 위반·자연키 중복은 problems로 드러낸다. */
+export function parseCloseProof(content: string): ParsedCloseProof {
+  const rows: CloseProofRow[] = []
+  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 = closeProofRowProblems(raw)
+    if (ps.length) {
+      problems.push(...ps.map((m) => `line ${i + 1}: ${m}`))
+      return
+    }
+    const row = raw as CloseProofRow
+    const key = closeProofRowKey(row)
+    if (seen.has(key)) problems.push(`line ${i + 1}: 자연키 중복(${row.event} ${row.series_id ?? ''})`)
+    seen.add(key)
+    rows.push(row)
+  })
+  return { rows, problems }
+}
+
+export type CloseProofAppendOutcome = 'appended' | 'duplicate' | 'conflict'
+export interface CloseProofAppendResult {
+  outcome: CloseProofAppendOutcome
+  content: string
+  problems: string[]
+}
+
+/**
+ * 멱등 append(순수 — 새 본문 반환만, 쓰기는 호출부). 원장과 같은 규칙(DEC-A3):
+ * 같은 자연키+동일 내용 → duplicate(no-op), 같은 자연키+다른 내용 → conflict(덮지 않음·fail-closed).
+ * 기존 본문 손상이면 그대로 올리고 append하지 않는다(D5 태도).
+ */
+export function appendCloseProofRow(existingContent: string, row: CloseProofRow): CloseProofAppendResult {
+  const rowProblems = closeProofRowProblems(row)
+  if (rowProblems.length) return { outcome: 'conflict', content: existingContent, problems: rowProblems }
+
+  const parsed = parseCloseProof(existingContent)
+  if (parsed.problems.length) return { outcome: 'conflict', content: existingContent, problems: parsed.problems }
+
+  const key = closeProofRowKey(row)
+  const prior = parsed.rows.find((r) => closeProofRowKey(r) === key)
+  if (prior) {
+    const same = serializeCloseProofRow(prior) === serializeCloseProofRow(row)
+    return same
+      ? { outcome: 'duplicate', content: existingContent, problems: [] }
+      : { outcome: 'conflict', content: existingContent, problems: [`같은 자연키의 기존 행과 내용이 다름(${row.event}) — 덮어쓰지 않는다`] }
+  }
+  const base = existingContent === '' || existingContent.endsWith('\n') ? existingContent : `${existingContent}\n`
+  return { outcome: 'appended', content: base + serializeCloseProofRow(row), problems: [] }
+}
+
+// ───────────────────────────────── 상태 파생(DEC-B) — 순수 ──
+
+/** 순수 파생기의 입력. 🔴 전부 **HEAD-committed 사실**만. 호출부가 포트로 채운다. runtime state 절대 미사용(DEC-B4). */
+export interface CloseStateInput {
+  /** HEAD scaffold state.json에 durability marker가 있는가(`isDurabilityRequired`). false면 legacy. */
+  durabilityRequired: boolean
+  /** HEAD close proof를 파싱한 행들(없으면 []). */
+  closeProofRows: readonly CloseProofRow[]
+  /**
+   * HEAD durable 원장이 이 티켓에 **approved인 attempt-closed**를 담고 있는가.
+   * needs-recovery 판정 입력 — 원장에 승인 흔적이 있는데 HEAD 증거가 불완전하면 recovery 필요.
+   */
+  ledgerHasApprovedClose: boolean
+  /** HEAD 증거(approvals·아카이브)가 그 승인에 대해 완비됐는가(`verifyCommittedDesignEvidence` 계열). */
+  committedEvidenceComplete: boolean
+  /**
+   * 🔴 HEAD `approvals.jsonl`에서 **현재 committed design_ref에 결속된**(`phase_design_ref === committedDesignRef`)
+   *    phase evidence의 phase ID 집합. dev-complete self-verify 입력(DEC-B2/B5).
+   *
+   * 🔴 **design-bound 필터는 호출부(manifest 읽는 경계)가 이미 적용**한다 — 이 순수 판정기는 manifest를 파싱하지
+   *    않는 leaf라 필터를 여기 넣으면 모듈 경계가 깨진다(`evidencedPhaseIdsFromManifest(content, designRef)`가
+   *    필터 지점). 단순 phase_id 존재가 아니라 **결속된 증거만** 담겨야 D1 검토분이 D2 완료에 새지 않는다(phase-3a P1).
+   *    dev-complete proof의 `phase_inventory`의 모든 phase가 이 집합에 있어야 dev-complete다.
+   */
+  evidencedPhaseIds: readonly string[]
+  /**
+   * 🔴 현재 HEAD의 committed design 승인 참조(design_hash). dev-complete proof의 `design_ref`와 일치해야 dev-complete다.
+   *    design 재승인으로 값이 바뀌면 옛 design_ref proof는 무효(DEC-B2). 계산 불가면 null(→ dev-complete 아님).
+   */
+  committedDesignRef: string | null
+}
+
+/** 기본 상태(배타·완결). `migrated-complete`(REQ-2026-053)는 dev-complete 아래·needs-recovery 위의 비차단 종결. */
+export type CloseBaseState = 'legacy' | 'series-terminal' | 'dev-complete' | 'migrated-complete' | 'needs-recovery' | 'developing'
+
+/**
+ * 🔴 dev-complete self-verify(순수, DEC-B2). HEAD close proof의 dev-complete row가 **자기 완결적으로** 증명되는가:
+ *   ① dev-complete row 존재 ② 그 row의 phase_inventory **모든 phase**가 HEAD 증거(evidencedPhaseIds)에 있음
+ *   ③ row의 design_ref = 현재 committed design 참조. runtime state는 절대 안 본다.
+ */
+export function isDevCompleteVerified(input: CloseStateInput): boolean {
+  if (input.committedDesignRef === null) return false
+  // 🔴 **현재 design_ref에 맞는** dev-complete 행을 고른다(phase-3a r02 P1). design 재승인 후 옛 design_ref
+  //    행은 무시(supersede)되고, 새 design_ref의 행이 있으면 그것으로 검증한다.
+  const dc = input.closeProofRows.find((r) => r.event === 'dev-complete' && r.design_ref === input.committedDesignRef)
+  if (!dc || !Array.isArray(dc.phase_inventory) || dc.phase_inventory.length === 0) return false
+  const evidenced = new Set(input.evidencedPhaseIds)
+  return dc.phase_inventory.every((p) => evidenced.has(p))
+}
+
+/**
+ * 기본 상태 파생(순수·배타·완결 — 항상 정확히 하나). 우선순위:
+ * `legacy` > `series-terminal` > `dev-complete` > `migrated-complete` > `needs-recovery` > `developing`(기본값).
+ *
+ * 🔴 워킹 state·워킹 승인을 절대 입력으로 받지 않는다(design-r01 P1·B4). `integrated`는 여기서 내지 않는다
+ *    — git ancestry 오버레이라 순수 파생 밖이다(design-r02 P1).
+ */
+export function deriveBaseState(input: CloseStateInput): CloseBaseState {
+  if (!input.durabilityRequired) return 'legacy'
+  const hasEvent = (e: CloseProofEvent): boolean => input.closeProofRows.some((r) => r.event === e)
+  if (hasEvent('series-terminal')) return 'series-terminal'
+  // 🔴 dev-complete는 self-verifying(DEC-B2): proof + committed evidence + design_ref로만 판정.
+  if (isDevCompleteVerified(input)) return 'dev-complete'
+  // 🔴 REQ-2026-053(DEC-M1): 마이그레이션 종결 — dev-complete **아래**(정상 완료가 이김), needs-recovery
+  //    **위**(일단 마이그레이션되면 종결). req:close가 needs-recovery/corrupt엔 스탬프를 찍지 않으므로(DEC-M3)
+  //    이 우선순위가 recovery 필요를 가리지 않는다.
+  if (hasEvent('migrated-complete')) return 'migrated-complete'
+  // 승인 흔적(원장)은 있으나 HEAD 증거가 불완전 = 복구 필요.
+  if (input.ledgerHasApprovedClose && !input.committedEvidenceComplete) return 'needs-recovery'
+  return 'developing'
+}
+
+/** `reconstructed` 오버레이(순수·blob). close proof에 복원 행이 하나라도 있으면 true. */
+export function isReconstructed(rows: readonly CloseProofRow[]): boolean {
+  return rows.some((r) => r.reconstructed === true)
+}
+
+/** req:new 게이트가 **차단**하는 기본 상태(DEC-C). 오버레이는 무관 — 기본 상태만 본다. */
+export function baseStateBlocksIntake(state: CloseBaseState): boolean {
+  return state === 'developing' || state === 'needs-recovery'
+}

package/scripts/req/lib/config.ts

@@ -64,6 +64,8 @@ export interface RawConfig {
   reviewBudget?: ReviewBudget
   /** REQ-2026-037: phase 자동 커밋 정책. 미지정 = DEFAULTS(never = 현행 매 phase 정지). */
   phaseCommit?: PhaseCommit
+  /** REQ-2026-056: true면 리뷰 프롬프트에 lockfile diff 전문을 담는다. 미지정/false = 요약(기본). */
+  lockfilePromptFull?: boolean
 }
 
 /** 해소된 config(DEFAULTS 병합 + 파생 절대경로). */
@@ -81,6 +83,7 @@ export interface ResolvedConfig {
   reviewReasoningEffort: ReviewReasoningEffort | null
   reviewBudget: ReviewBudget
   phaseCommit: PhaseCommit
+  lockfilePromptFull: boolean
   // 파생(절대경로)
   workflowDirAbs: string
   schemaPathAbs: string
@@ -132,6 +135,8 @@ export const DEFAULTS = {
   reviewBudget: { autoBudget: 5, hardCap: 8 } as ReviewBudget,
   // REQ-2026-037: phase 자동 커밋은 opt-in. 코어 기본 never = 현행(매 phase 정지) — 업그레이드로 완화되지 않는다.
   phaseCommit: { autoApprove: 'never' } as PhaseCommit,
+  // REQ-2026-056: lockfile 프롬프트 기본 요약(false). 전문이 필요하면 config에 true 명시(opt-in).
+  lockfilePromptFull: false,
 }
 
 const BASENAME_RE = '^[A-Za-z0-9][A-Za-z0-9._-]*$' // basename만(슬래시·백슬래시·선행 `.`(→`..`) 금지)
@@ -172,6 +177,8 @@ export const CONFIG_SCHEMA = {
         autoApprove: { type: 'string', enum: ['never', 'low-only'] },
       },
     },
+    // REQ-2026-056: lockfile 프롬프트 전문 opt-in.
+    lockfilePromptFull: { type: 'boolean' },
     designDocs: {
       type: 'object',
       additionalProperties: false,
@@ -259,6 +266,8 @@ export function loadConfig(opts: { root?: string | null; cwd?: string } = {}): R
     reviewBudget: raw.reviewBudget ?? DEFAULTS.reviewBudget,
     // REQ-2026-037: 미지정 → DEFAULTS(never). `?? `로 충분(phaseCommit은 nullable 아님 — null 탈출구 없음).
     phaseCommit: raw.phaseCommit ?? DEFAULTS.phaseCommit,
+    // REQ-2026-056: 미지정 → DEFAULTS(false = 요약).
+    lockfilePromptFull: raw.lockfilePromptFull ?? DEFAULTS.lockfilePromptFull,
   }
 
   // REQ-2026-028 R7: 교차검증(스키마가 표현 못 함). AJV가 이미 hardCap∈[1,8]·autoBudget≥1을 잡았고,

package/scripts/req/lib/evidence-ports.ts

@@ -0,0 +1,116 @@
+/**
+ * `EvidencePorts`의 실제 구현(fs + git) — REQ-2026-048 phase-3.
+ *
+ * `lib/evidence.ts`는 leaf(순수)라 fs·git을 모른다. 부수효과는 전부 여기로 모아 두 호출자
+ * (`review-codex`의 정상 승인 경로, `req:commit --finalize-design`의 복구 경로)가 **같은 포트**를 쓰게 한다.
+ *
+ * ⚠️ 이 모듈도 `review-codex`·`req-commit`·`req-doctor`를 import하지 않는다(leaf 유지).
+ */
+import { existsSync, readFileSync, readdirSync, mkdirSync, writeFileSync } from 'node:fs'
+import { execFileSync } from 'node:child_process'
+import { createHash } from 'node:crypto'
+import { join, dirname } from 'node:path'
+import { isArchiveFileName } from './scratch'
+import type { EvidencePorts } from './evidence'
+
+/** repo-상대 경로 → 절대 경로(구분자 정규화). */
+function abs(root: string, repoRel: string): string {
+  return join(root, ...repoRel.replace(/\\/g, '/').split('/'))
+}
+
+/**
+ * 실 파일시스템·git 기반 포트.
+ *
+ * @param root  소비 저장소 루트(=`cfg.root`).
+ * @param responsesDirRel 티켓 `responses/` repo-상대 경로(아카이브 목록용).
+ */
+export function createEvidencePorts(root: string, responsesDirRel: string): EvidencePorts {
+  /** 짧은 문자열 출력을 내는 git 호출(파일 내용용 아님). */
+  const gitText = (args: string[]): string =>
+    execFileSync('git', args, { cwd: root, encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 })
+
+  return {
+    readText(repoRel) {
+      const p = abs(root, repoRel)
+      return existsSync(p) ? readFileSync(p, 'utf8') : null
+    },
+    writeText(repoRel, content) {
+      const p = abs(root, repoRel)
+      mkdirSync(dirname(p), { recursive: true })
+      writeFileSync(p, content, 'utf8')
+    },
+    listArchiveNames() {
+      const d = abs(root, responsesDirRel)
+      return existsSync(d) ? readdirSync(d).filter(isArchiveFileName) : []
+    },
+    sha256(repoRel) {
+      return createHash('sha256').update(readFileSync(abs(root, repoRel))).digest('hex')
+    },
+    headText(repoRel) {
+      try {
+        return gitText(['show', `HEAD:${repoRel}`])
+      } catch {
+        return null // HEAD에 없는 경로
+      }
+    },
+    /**
+     * 🔴 **바이트 그대로** 읽어 해시한다.
+     *
+     * `GitAdapter.exec`는 계약상 결과의 **후행 공백을 제거**한다(`git status --porcelain` 선행 공백 보존이 목적).
+     * 그 변환은 파일 내용 해시를 **망가뜨린다**(끝 개행이 사라져 sha가 달라진다). 그래서 이 한 곳만
+     * `execFileSync(..., {encoding:'buffer'})`로 원문 바이트를 받는다 — 어댑터 우회가 아니라 **다른 계약**이 필요해서다.
+     *
+     * 또한 워킹 파일이 아니라 **blob**을 읽는 것이 핵심이다. `core.autocrlf` 환경에서 워킹 파일은 CRLF로
+     * 변환될 수 있고, 그러면 커밋된 내용과 sha가 달라져 거짓 불일치가 난다.
+     */
+    headBlobSha256(repoRel) {
+      try {
+        const buf = execFileSync('git', ['cat-file', 'blob', `HEAD:${repoRel}`], {
+          cwd: root,
+          maxBuffer: 64 * 1024 * 1024,
+        })
+        return createHash('sha256').update(buf).digest('hex')
+      } catch {
+        return null // HEAD에 없는 경로
+      }
+    },
+    /**
+     * `HEAD`에 있는 해당 디렉터리의 아카이브 **repo-상대 경로**(REQ-2026-049 DEC-4).
+     *
+     * 🔴 `git ls-tree`는 **커밋 트리**를 읽는다 — 워킹 디렉터리를 전혀 보지 않는다. 그래서 "워킹 트리만
+     *    고치고 HEAD는 손상된" 경우를 잡는다. `-z`로 NUL 구분해 공백·비ASCII 경로에서도 안전하다
+     *    (`--name-only`의 기본 출력은 특수문자를 인용해 경로가 변형된다).
+     */
+    headArchivePaths(responsesDirRel) {
+      try {
+        const out = execFileSync('git', ['ls-tree', '-r', '-z', '--name-only', 'HEAD', '--', responsesDirRel], {
+          cwd: root,
+          encoding: 'utf8',
+          maxBuffer: 64 * 1024 * 1024,
+        })
+        return out
+          .split('\0')
+          .map((p) => p.trim())
+          .filter((p) => p !== '' && isArchiveFileName(p.split('/').pop() ?? ''))
+      } catch {
+        return [] // HEAD에 그 경로가 없음
+      }
+    },
+    headCommitSha() {
+      return gitText(['rev-parse', 'HEAD']).trim()
+    },
+    /**
+     * 🔴 **pathspec 범위 커밋**. `git add <paths>` 로 새 파일을 추적 대상에 넣은 뒤,
+     * `git commit -m <msg> -- <paths>` 로 **그 경로만** 커밋한다.
+     *
+     * `-- <paths>` 가 핵심이다: pathspec을 주면 git은 그 경로들의 내용만으로 커밋을 만들고
+     * **나머지 index는 건드리지 않는다**. 설계 문서를 stage한 채 design 리뷰를 돌리는 정상 경로에서도
+     * 그 staged 변경은 evidence 커밋에 섞이지 않고 index에 그대로 남는다.
+     */
+    commitPaths(paths, message) {
+      if (paths.length === 0) return
+      execFileSync('git', ['add', '--', ...paths], { cwd: root, encoding: 'utf8' })
+      execFileSync('git', ['commit', '-m', message, '--', ...paths], { cwd: root, encoding: 'utf8' })
+    },
+  }
+}