commitgate 0.9.8 → 0.9.10

package/scripts/req/req-reconstruct.ts

@@ -0,0 +1,224 @@
+#!/usr/bin/env tsx
+/**
+ * req:reconstruct — 소실된 close-proof lifecycle 행을 **HEAD-committed immutable evidence만으로** 복원한다
+ * (REQ-2026-052 phase-4·DEC-D2). 복원 가능성 매트릭스는 `lib/reconstruct`(순수)가 판정하고, 이 CLI는 evidence를
+ * HEAD blob에서 뽑아 넣고 부작용(durable commit)을 낸다.
+ *
+ * 🔴 **HEAD blob만** 읽는다 — runtime state·워킹트리·미커밋 원장·추정 phase 목록을 근거로 쓰지 않는다.
+ * 🔴 `verifyCommittedEvidenceIntegrity`가 실패한(손상) 티켓은 **복원하지 않고 fail-closed**한다.
+ * 🔴 **dev-complete·phase_design_ref·design/phase archive는 절대 합성하지 않는다.** state.json을 고치지 않는다.
+ * 🔴 기본 **dry-run**. `--run` + **`--confirm`(사람 확인)** 후에만 write. 새 행은 `reconstructed:true` +
+ *    비어있지 않은 `evidence_basis`. append-only·자연키 멱등 → 재시도가 중복 행/추가 커밋을 만들지 않는다.
+ *
+ * 사용: req:reconstruct <REQ> [--run] [--confirm] [--root <dir>]
+ */
+import { writeFileSync } from 'node:fs'
+import { join, relative } from 'node:path'
+import { pathToFileURL } from 'node:url'
+import { loadConfig, packageRoot } from './lib/config'
+import { createGitAdapter, quietGitRunner, type GitAdapter } from './lib/adapters'
+import { createEvidencePorts } from './lib/evidence-ports'
+import { verifyCommittedEvidenceIntegrity } from './lib/evidence'
+import { parseCloseProof, appendCloseProofRow, closeProofPath, type CloseProofRow } from './lib/close-proof'
+import { planReconstruction, type SuccessorEvidence, type ReconstructPlan } from './lib/reconstruct'
+import { listHeadTicketIds } from './lib/intake'
+import { isValidHumanResolution } from './review-codex'
+
+let gitAdapter: GitAdapter = createGitAdapter(packageRoot())
+/**
+ * **부재가 정상인 HEAD 조회 전용** 어댑터(REQ-2026-058 F-5). 이 명령의 HEAD 조회는 "아직 없음"이 정상이라
+ * git stderr의 `fatal: … does not exist in 'HEAD'`가 사용자에게 실패로 보인다. 판정은 그대로 `catch → null`.
+ */
+let quietGitAdapter: GitAdapter = createGitAdapter(packageRoot(), quietGitRunner)
+function git(args: string[]): string {
+  return gitAdapter.exec(args)
+}
+/** `HEAD:<repoRel>` blob 텍스트(없으면 null). 부재가 정상이므로 quiet 어댑터를 쓴다(F-5). */
+function headBlob(repoRel: string): string | null {
+  try {
+    return quietGitAdapter.exec(['show', `HEAD:${repoRel}`])
+  } catch {
+    return null
+  }
+}
+
+export interface Opts {
+  reqId: string | null
+  run: boolean
+  confirm: boolean
+  root: string | null
+}
+
+/** 인자 파싱(fail-closed): 값 누락·알 수 없는 옵션은 즉시 throw. */
+export function parseArgs(argv: string[]): Opts {
+  const o: Opts = { reqId: null, run: false, confirm: 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 === '--run') o.run = true
+    else if (a === '--confirm') o.confirm = 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
+}
+
+/**
+ * 이 티켓을 replace 부모로 지목하는 committed successor 증거를 HEAD tree에서 수집(read-only).
+ * 🔴 구식 successor_of(`parent_series_id` 없음)·비-replace·형식 무효는 제외한다(복원 불가 — 수집 안 함).
+ */
+export function collectSuccessorEvidence(workflowDirRel: string, parentReqId: string, gitFn: (a: string[]) => string): SuccessorEvidence[] {
+  const headBlobVia = (rel: string): string | null => {
+    try {
+      return gitFn(['show', `HEAD:${rel}`])
+    } catch {
+      return null
+    }
+  }
+  const out: SuccessorEvidence[] = []
+  for (const id of listHeadTicketIds(workflowDirRel, gitFn)) {
+    if (id === parentReqId) continue
+    const rel = `${workflowDirRel}/${id}`
+    const stateText = headBlobVia(`${rel}/state.json`)
+    if (stateText === null) continue
+    let so: unknown
+    try {
+      so = (JSON.parse(stateText) as { successor_of?: unknown }).successor_of
+    } catch {
+      continue
+    }
+    if (!so || typeof so !== 'object') continue
+    const s = so as { req_id?: unknown; parent_series_id?: unknown; parent_replace_resolution?: unknown }
+    if (s.req_id !== parentReqId) continue
+    if (typeof s.parent_series_id !== 'string' || !s.parent_series_id) continue // 구식 → 복원 불가
+    const hr = s.parent_replace_resolution
+    if (!isValidHumanResolution(hr) || (hr as { decision?: unknown }).decision !== 'replace') continue
+    out.push({
+      successorTicketId: id,
+      successorStatePath: `${rel}/state.json`,
+      parentSeriesId: s.parent_series_id,
+      resolution: 'replace', // collect는 decision==='replace'만 통과시킨다(material field로 명시).
+      at: (hr as { decided_at: string }).decided_at,
+    })
+  }
+  return out
+}
+
+function renderPlan(reqId: string, plan: ReconstructPlan): string {
+  const lines: string[] = [`[req:reconstruct] ${reqId} — 복원 계획(HEAD-committed 증거 기준)`]
+  if (plan.candidates.length) {
+    lines.push('  복원 예정 행:')
+    for (const c of plan.candidates)
+      lines.push(`    - series-terminal series_id=${c.row.series_id} resolution=${c.row.resolution} at=${c.row.at} · evidence_basis=[${c.evidenceBasis.join(', ')}]`)
+  } else {
+    lines.push('  복원 예정 행: 없음')
+  }
+  if (plan.refusals.length) {
+    lines.push('  복원 불가·불필요·모호:')
+    for (const r of plan.refusals) lines.push(`    - ${r}`)
+  }
+  if (plan.conflicts.length) {
+    lines.push('  🔴 fail-closed conflict(HEAD 모순 — write 0):')
+    for (const c of plan.conflicts) lines.push(`    - ${c}`)
+  }
+  return lines.join('\n')
+}
+
+export function main(argv: string[] = process.argv.slice(2)): void {
+  const o = parseArgs(argv)
+  if (!o.reqId) throw new Error('REQ 필요 (예: req:reconstruct 2026-029)')
+  const cfg = loadConfig({ root: o.root })
+  gitAdapter = createGitAdapter(cfg.root)
+  quietGitAdapter = createGitAdapter(cfg.root, quietGitRunner) // HEAD 부재 조회 전용(F-5)
+  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 workflowDirRel = relative(cfg.root, cfg.workflowDirAbs).replace(/\\/g, '/')
+
+  // 🔴 1. 손상 티켓은 복원하지 않는다(fail-closed) — verifyCommittedEvidenceIntegrity(design+phase HEAD 무결성).
+  const ports = createEvidencePorts(cfg.root, `${ticketRel}/responses`)
+  const manifestText = ports.headText(`${ticketRel}/responses/approvals.jsonl`)
+  const integrity = verifyCommittedEvidenceIntegrity({ ticketRel, manifestText, ports })
+  if (integrity.problems.length)
+    throw new Error(`${reqId}: committed 증거 손상 — 복원 거부(fail-closed): ${integrity.problems.slice(0, 3).join('; ')}`)
+
+  // 2. 이 티켓 HEAD close-proof(모순/중복 판정 기준). 손상이면 거부.
+  const cpRel = closeProofPath(ticketRel)
+  const cpText = headBlob(cpRel)
+  const parsed = cpText ? parseCloseProof(cpText) : { rows: [], problems: [] }
+  if (parsed.problems.length)
+    throw new Error(`${reqId}: HEAD close-proof 손상 — 복원 거부: ${parsed.problems.slice(0, 3).join('; ')}`)
+
+  // 3. successor 증거 수집(HEAD tree) → 매트릭스(순수) 판정.
+  // 🔴 quiet 어댑터를 넘긴다 — 이 함수의 git 호출은 전부 **HEAD 조회**이고 부재가 정상이다(F-5).
+  const successors = collectSuccessorEvidence(workflowDirRel, reqId, (a) => quietGitAdapter.exec(a))
+  const plan = planReconstruction({ ticketId: reqId, existingRows: parsed.rows, successors })
+  console.log(renderPlan(reqId, plan))
+
+  // 🔴 conflict(HEAD 모순)는 dry-run/`--run` 무관하게 **명령 전체를 fail-closed**한다 — 멱등으로 숨기지 않는다.
+  if (plan.conflicts.length)
+    throw new Error(`${reqId}: HEAD close-proof와 모순되는 복원 대상(conflict) — fail-closed(write 0): ${plan.conflicts.join('; ')}`)
+
+  // 4. 실행 모델.
+  if (!o.run) {
+    console.log('[req:reconstruct] DRY-RUN — write 없음(--run 시 실행).')
+    return
+  }
+  if (!o.confirm) {
+    console.log('[req:reconstruct] --run 지정됐으나 사람 확인 없음 — write 0. 위 계획을 확인했으면 `--confirm` 을 추가하세요.')
+    return
+  }
+  if (plan.candidates.length === 0) {
+    console.log('[req:reconstruct] 복원 가능한 행이 없습니다 — no-op(write 0).')
+    return
+  }
+
+  // 🔴 5. 쓰기 전 안전: 대상 close-proof가 **HEAD와 동일**(워킹트리·인덱스에 미커밋 변경 없음)이어야 한다.
+  //    아니면 HEAD 기반으로 덮어쓰다 사용자의 미커밋 close-proof 행을 **잃는다**(리뷰 P1). 불일치면 fail-closed.
+  const cpDirty = git(['status', '--porcelain', '--', cpRel]).trim()
+  if (cpDirty)
+    throw new Error(
+      `${reqId}: close-proof(${cpRel})에 미커밋 변경이 있어 복원을 거부합니다(fail-closed) — HEAD 기반 쓰기가 미커밋 행을 덮어쓸 수 있습니다.\n` +
+        `  먼저 미커밋 close-proof 변경을 커밋하거나 정리한 뒤 다시 실행하세요.`,
+    )
+
+  // 6. 쓰기: append(자연키 멱등) → durable commit(pathspec). 재시도는 duplicate라 커밋 diff 없음.
+  let content = cpText ?? ''
+  let appended = 0
+  for (const c of plan.candidates) {
+    const res = appendCloseProofRow(content, c.row)
+    if (res.outcome === 'appended') {
+      content = res.content
+      appended++
+    } else if (res.outcome === 'conflict') {
+      throw new Error(`복원 충돌(fail-closed): ${res.problems.join('; ')}`)
+    }
+    // duplicate → 이미 존재(멱등 skip).
+  }
+  if (appended === 0) {
+    console.log('[req:reconstruct] 대상 행이 이미 모두 존재 — no-op(멱등).')
+    return
+  }
+  writeFileSync(join(cfg.root, cpRel), content, 'utf8')
+  git(['add', '--', cpRel])
+  git(['commit', '-m', `chore(${reqId}): reconstruct series-terminal close proof (evidence-based)`, '--', cpRel])
+  console.log(`[req:reconstruct] ✅ ${appended}행 복원·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()

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

@@ -0,0 +1,197 @@
+#!/usr/bin/env tsx
+/**
+ * req:review-exception — needs-exception 구간의 사람 예외를 **검증·원자 기록**한다(REQ-2026-055·DEC-RE).
+ *
+ * 지금까지 `state.json`의 `review_exception_confirmed`를 손으로 편집하던 것을 대체한다: 현재 예산이 실제
+ * needs-exception인지·어느 series·회차인지 **소비 게이트와 같은 함수**로 계산하고, 구조화 rationale을 durable하게
+ * 남긴 **뒤에만** 소비 가능한 state를 기록한다(부분 실패 시 rationale 없는 예외 방지).
+ *
+ * 🔴 durable 먼저(review-exceptions.jsonl 커밋) → state.json 마지막. 🔴 confirmed_at 실시계(날조 금지).
+ * 🔴 소비 로직(consumeReviewException)·예산 게이트 무변경 — 이 명령은 **기록만** 한다.
+ *
+ * 사용: req:review-exception <REQ> --kind design|phase [--phase <id>] --method "<승인문장>" --rationale-file <path> [--run]
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { dirname, join, relative, resolve } from 'node:path'
+import { pathToFileURL } from 'node:url'
+import { loadConfig, packageRoot, type ReviewBudget } from './lib/config'
+import { createGitAdapter, type GitAdapter } from './lib/adapters'
+import {
+  loadState,
+  writeState,
+  openSeriesRecord,
+  openSeriesAttempts,
+  checkReviewBudget,
+  isSeriesKeyTerminal,
+  type WorkflowState,
+  type ReviewKind,
+  type ReviewExceptionConfirmed,
+} from './review-codex'
+import {
+  exceptionsPath,
+  appendExceptionGrant,
+  findExistingGrant,
+  parseRationale,
+  type ExceptionGrantRow,
+} from './lib/review-exception'
+
+let gitAdapter: GitAdapter = createGitAdapter(packageRoot())
+function git(args: string[]): string {
+  return gitAdapter.exec(args)
+}
+
+export interface Opts {
+  reqId: string | null
+  kind: ReviewKind | null
+  phase: string | null
+  method: string | null
+  rationaleFile: string | null
+  run: boolean
+  root: string | null
+}
+
+/** 인자 파싱(fail-closed): 값 누락·알 수 없는 옵션은 즉시 throw. */
+export function parseArgs(argv: string[]): Opts {
+  const o: Opts = { reqId: null, kind: null, phase: null, method: null, rationaleFile: null, 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 === '--run') o.run = true
+    else if (a === '--kind') {
+      const v = argv[++i]
+      if (v !== 'design' && v !== 'phase') throw new Error(`--kind 값은 design 또는 phase여야 함 (받음: ${v ?? '(없음)'})`)
+      o.kind = v
+    } else if (a === '--phase') {
+      const v = argv[++i]
+      if (v === undefined) throw new Error('--phase 값 필요')
+      o.phase = v
+    } else if (a === '--method') {
+      const v = argv[++i]
+      if (v === undefined) throw new Error('--method 값 필요')
+      o.method = v
+    } else if (a === '--rationale-file') {
+      const v = argv[++i]
+      if (v === undefined) throw new Error('--rationale-file 값 필요')
+      o.rationaleFile = v
+    } 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
+}
+
+export type ReviewExceptionPlan =
+  | { ok: true; seriesId: string; forAttempt: number }
+  | { ok: false; reason: string; hint: string }
+
+/**
+ * 예외 부여 자격 판정(순수·DEC-RE1). 🔴 회차를 **소비 게이트와 같은 함수**(openSeriesAttempts·checkReviewBudget)로
+ * 계산 → consumeReviewException의 for_attempt 검증과 정확히 일치(REQ-2026-054 유효 회차 기준).
+ */
+export function planReviewException(state: WorkflowState, kind: ReviewKind, phaseId: string | null, budget: ReviewBudget): ReviewExceptionPlan {
+  if (isSeriesKeyTerminal(state, kind, phaseId))
+    return { ok: false, reason: '이 series는 human-resolution으로 종결됨', hint: '예산 예외가 아니라 대체 REQ가 필요(req:new --successor-of)' }
+  const open = openSeriesRecord(state, kind, phaseId)
+  if (!open) return { ok: false, reason: '열린 series가 없음 — 예외 걸 대상이 없다', hint: '먼저 req:review-codex로 리뷰를 시작하세요' }
+  const openAttempts = openSeriesAttempts(state, kind, phaseId)
+  const decision = checkReviewBudget(openAttempts, budget)
+  if (decision.kind === 'allow')
+    return { ok: false, reason: `아직 예외 불요(유효 회차 ${openAttempts} < autoBudget ${budget.autoBudget})`, hint: '그냥 req:review-codex로 리뷰하세요' }
+  if (decision.kind === 'hard-blocked')
+    return { ok: false, reason: `예산 소진 — 예외로도 불가(hardCap ${budget.hardCap})`, hint: '종료하거나 정합한 대체 REQ를 작성하세요' }
+  return { ok: true, seriesId: open.series_id, forAttempt: decision.attempt }
+}
+
+export function main(argv: string[] = process.argv.slice(2)): void {
+  const o = parseArgs(argv)
+  if (!o.reqId) throw new Error('REQ 필요 (예: req:review-exception 2026-001 --kind design --method "…" --rationale-file r.md)')
+  if (!o.kind) throw new Error('--kind design|phase 필요')
+  if (o.kind === 'phase' && !o.phase) throw new Error('--kind phase는 --phase <id> 필요')
+  if (!o.method || o.method.trim() === '') throw new Error('--method "<승인문장>" 필요')
+  if (!o.rationaleFile) throw new Error('--rationale-file <path> 필요')
+
+  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 state = loadState(ticketDir)
+  const phaseId = o.kind === 'phase' ? o.phase : null
+
+  // 1. 자격 판정 + rationale 검증(순수 — write 前 모든 거부 조건).
+  const plan = planReviewException(state, o.kind, phaseId, cfg.reviewBudget)
+  const rp = parseRationale(readFileSync(resolve(o.rationaleFile), 'utf8'))
+  if (!plan.ok) throw new Error(`${reqId} 예외 부여 불가: ${plan.reason}\n  → ${plan.hint}`)
+  if (!rp.ok) throw new Error(`rationale 검증 실패(--rationale-file):\n  - ${rp.problems.join('\n  - ')}`)
+
+  console.log(`[req:review-exception] ${reqId} 예외 부여 계획: series=${plan.seriesId} for_attempt=${plan.forAttempt} (kind=${o.kind}${phaseId ? ` phase=${phaseId}` : ''})`)
+  if (!o.run) {
+    console.log('[req:review-exception] DRY-RUN — write 없음(--run 시 실행). rationale 4섹션 검증 OK.')
+    return
+  }
+
+  // 2. 🔴 clean 가드 — state 변경 前(DEC-RE4·r01 P1). 미커밋 review-exceptions를 HEAD 기반이 덮지 않게.
+  const exRel = exceptionsPath(ticketRel)
+  const exDirty = git(['status', '--porcelain', '--', exRel]).trim()
+  if (exDirty)
+    throw new Error(
+      `${reqId}: ${exRel}에 미커밋 변경이 있어 예외 기록을 거부합니다(fail-closed) — HEAD 기반 append가 미커밋 행을 덮을 수 있습니다.\n` +
+        `  먼저 미커밋 변경을 커밋/정리한 뒤 다시 실행하세요.`,
+    )
+
+  // 3. 🔴 durable rationale 먼저. 기존 행이 있으면 confirmed_at 재사용(재실행 복구·conflict 아님).
+  const abs = join(cfg.root, exRel)
+  const existing = existsSync(abs) ? readFileSync(abs, 'utf8') : ''
+  const naturalKey = { ticket_id: reqId, series_id: plan.seriesId, for_attempt: plan.forAttempt }
+  const prior = findExistingGrant(existing, naturalKey)
+  const confirmedAt = prior ? prior.confirmed_at : new Date().toISOString()
+  const row: ExceptionGrantRow = {
+    ticket_id: reqId,
+    review_kind: o.kind,
+    phase_id: phaseId,
+    series_id: plan.seriesId,
+    for_attempt: plan.forAttempt,
+    method: o.method,
+    confirmed_at: confirmedAt,
+    rationale: rp.rationale,
+    reconstructed: false,
+  }
+  const res = appendExceptionGrant(existing, row)
+  if (res.outcome === 'conflict') throw new Error(`${reqId}: 예외 원장 충돌(fail-closed): ${res.problems.join('; ')}`)
+  if (res.outcome === 'appended') {
+    mkdirSync(dirname(abs), { recursive: true })
+    writeFileSync(abs, res.content, 'utf8')
+    git(['add', '--', exRel])
+    git(['commit', '-m', `chore(${reqId}): review exception grant ${plan.seriesId} #${plan.forAttempt}`, '--', exRel])
+  }
+  // res.outcome === 'duplicate' → durable 이미 존재(멱등·커밋 없음).
+
+  // 4. durable 확정 후에만 소비 가능한 state 기록(scratch). confirmed_at은 durable 행과 동일 값.
+  const exception: ReviewExceptionConfirmed = {
+    confirmed: true,
+    method: o.method,
+    confirmed_at: confirmedAt,
+    for_series_id: plan.seriesId,
+    for_attempt: plan.forAttempt,
+    note: rp.rationale.prev_findings.split('\n')[0]?.slice(0, 200) ?? '',
+  }
+  writeState(ticketDir, { ...state, review_exception_confirmed: exception } as WorkflowState)
+  console.log(`[req:review-exception] ✅ ${reqId} 예외 기록 완료 — rationale durable(${res.outcome === 'appended' ? '신규 커밋' : '기존 재사용'}) + review_exception_confirmed 기록. 이제 req:review-codex를 실행하세요.`)
+}
+
+/** 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()