commitgate 0.2.0 → 0.2.2

package/scripts/req/lib/adapters.ts

@@ -9,7 +9,7 @@
  * 본 모듈은 req 스크립트에 의존하지 않는 leaf(순환 의존 금지) — parseThreadId도 여기로 이동(codex CLI 전용 로직).
  */
 import { execFileSync } from 'node:child_process'
-import { existsSync, readFileSync, mkdtempSync } from 'node:fs'
+import { existsSync, readFileSync, writeFileSync, mkdtempSync } from 'node:fs'
 import { join } from 'node:path'
 import { tmpdir } from 'node:os'
 import spawn from 'cross-spawn'
@@ -54,15 +54,19 @@ export interface GitAdapter {
 }
 
 /** GitAdapter default 구현의 내부 실행자(주입 가능 — 테스트). encoding:'utf8'이라 string 반환. */
-export type GitRunner = (file: string, args: string[], opts: { cwd: string; encoding: 'utf8' }) => string
+export type GitRunner = (file: string, args: string[], opts: { cwd: string; encoding: 'utf8'; maxBuffer: number }) => string
 const defaultGitRunner: GitRunner = (file, args, opts) => execFileSync(file, args, opts)
 
+/** git stdout 상한 — codex 경로(safeSpawnSync)와 동일 64 MiB. 큰 staged diff/status에서 Node 기본 1 MiB의 ENOBUFS throw 방지. */
+const GIT_MAX_BUFFER = 64 * 1024 * 1024
+
 /**
- * default GitAdapter — `execFileSync('git', args, {cwd: root, encoding:'utf8'})` 후 **trailing 공백만 제거**.
+ * default GitAdapter — `execFileSync('git', args, {cwd: root, encoding:'utf8', maxBuffer})` 후 **trailing 공백만 제거**.
  * ⚠️ `.trim()`이 아니라 `.replace(/\s+$/, '')` — `git status --porcelain`의 **선행 공백(XY 코드)**을 보존(behavior-preserving).
+ * maxBuffer=64MiB: `git diff --cached`/`git show :<path>`가 1 MiB 기본 상한을 넘겨 codex 호출 전에 하드 실패하는 것 방지.
  */
 export function createGitAdapter(root: string, run: GitRunner = defaultGitRunner): GitAdapter {
-  return { exec: (args) => run('git', args, { cwd: root, encoding: 'utf8' }).replace(/\s+$/, '') }
+  return { exec: (args) => run('git', args, { cwd: root, encoding: 'utf8', maxBuffer: GIT_MAX_BUFFER }).replace(/\s+$/, '') }
 }
 
 // ─────────────────────────────────────────────── Reviewer (codex) ──
@@ -105,19 +109,42 @@ const defaultCodexRunner: CodexRunner = (args, input, cwd) =>
   // ⚠️ 과거 `shell:true`는 args(schemaPath·resumeThreadId 등)의 메타문자로 **명령 주입**이 가능했고 공백 경로도 깨졌음 — P1 수정.
   safeSpawnSync('codex', args, { cwd, input, maxBuffer: 64 * 1024 * 1024 })
 
+/**
+ * Codex `--output-schema`용 **strict copy** 파생(REQ-2026-005). OpenAI structured-outputs strict mode는
+ * root `required`가 `properties`의 **모든 키**를 포함해야 한다 — optional 필드(예: observations)가 있으면 400 invalid_json_schema.
+ * 원본 스키마(`workflow/machine.schema.json`)는 **검증 SSOT로 불변**(observations optional → 기존 archive 하위호환)이고,
+ * codex 호출 직전에만 root.required를 `properties` 전체로 확장한 copy를 파생한다. 응답/archive 검증은 계속 원본으로 한다.
+ * 중첩 객체(findings/observations items)는 이미 모든 필드 required + additionalProperties:false라 root만 확장하면 충분.
+ */
+export function deriveStrictOutputSchema(schemaText: string): string {
+  const schema = JSON.parse(schemaText) as { properties?: Record<string, unknown>; required?: string[]; [k: string]: unknown }
+  if (schema && typeof schema === 'object' && schema.properties && typeof schema.properties === 'object') {
+    schema.required = Object.keys(schema.properties)
+  }
+  return JSON.stringify(schema)
+}
+
 /**
  * default ReviewerAdapter(codex CLI). exec(신규)/resume(thread_id) 분기 + `--output-last-message`(임시파일) 캡처 + thread 파싱.
- * - resume은 `--sandbox` 미수용(0차 실측) → 생략(정책 상속). exec은 `--sandbox read-only`.
+ * - **read-only 리뷰어 강제(양 라운드, REQ-2026-006/R9)**: exec은 `--sandbox read-only`. resume은 `-s/--sandbox` 플래그를 **거부**하므로
+ *   (`error: unexpected argument '--sandbox'` — spike 확인) `-c sandbox_mode="read-only"` **config override**로 read-only를 강제한다.
+ *   행동 검증: resume(무 override)은 실제 write 성공(sandbox drop=갭 실재), resume(override)은 write가 `Access is denied`로 차단(enforced).
+ *   `-c`가 향후 CLI에서 거부되면 resume 자체가 실패=fail-closed(리뷰 미승인).
+ * - `--output-schema`에는 원본이 아니라 **strict 파생 copy**를 넘긴다(codex strict mode 400 방지, REQ-2026-005). 원본은 검증 SSOT.
  * - threadId: resume이면 resumeThreadId, exec이면 parseThreadId(stdout)(없으면 null → 호출처가 fail-closed).
  * - codex 미설치/실패 → runner가 throw(그대로 전파, fail-closed).
  */
 export function createCodexReviewerAdapter(run: CodexRunner = defaultCodexRunner): ReviewerAdapter {
   return {
     review({ prompt, schemaPath, resumeThreadId, cwd }) {
-      const lastPath = join(mkdtempSync(join(tmpdir(), 'req-codex-')), 'last.json')
+      const tmpDir = mkdtempSync(join(tmpdir(), 'req-codex-'))
+      const lastPath = join(tmpDir, 'last.json')
+      // 원본(검증 SSOT)을 읽어 strict copy 파생 → temp에 기록 → --output-schema로 전달(archive 검증엔 원본 사용).
+      const outputSchemaPath = join(tmpDir, 'output-schema.json')
+      writeFileSync(outputSchemaPath, deriveStrictOutputSchema(readFileSync(schemaPath, 'utf8')), 'utf8')
       const args = resumeThreadId
-        ? ['exec', 'resume', resumeThreadId, '--json', '--output-schema', schemaPath, '--output-last-message', lastPath, '-']
-        : ['exec', '--json', '--sandbox', 'read-only', '--output-schema', schemaPath, '--output-last-message', lastPath, '-']
+        ? ['exec', 'resume', resumeThreadId, '-c', 'sandbox_mode="read-only"', '--json', '--output-schema', outputSchemaPath, '--output-last-message', lastPath, '-']
+        : ['exec', '--json', '--sandbox', 'read-only', '--output-schema', outputSchemaPath, '--output-last-message', lastPath, '-']
       const rawStdout = run(args, prompt, cwd)
       const threadId = resumeThreadId ?? parseThreadId(rawStdout)
       const lastMessage = existsSync(lastPath) ? readFileSync(lastPath, 'utf8') : ''

package/scripts/req/review-codex.ts

@@ -191,13 +191,22 @@ export function readDesignDocsFromIndex(
 // 구조(필수 키·enum)는 단계 3에서 AJV(machine.schema.json)로 강제.
 // 여기서는 AJV가 표현 못 하는 교차필드 모순·버전·git 바인딩을 fail-closed로 검사(§9.6 rule 2~3).
 
-/** 리뷰 지적 항목 (machine.schema.json 1.1 findings[]). file은 nullable(전역 지적 등). */
+/** 리뷰 지적 항목 (machine.schema.json 1.1 findings[]). file은 nullable(전역 지적 등). severity=blocking 신호. */
 export interface Finding {
   severity?: string
   detail?: string
   file?: string | null
 }
 
+/**
+ * 비차단 코멘트(observations[], REQ-2026-005). 승인/차단 판정에 영향 없음(순수 정보).
+ * **severity 없음** — severity가 붙는 순간 blocking(findings)/non-blocking(observations) 경계가 흐려진다(스키마가 구조적으로 거부).
+ */
+export interface Observation {
+  detail?: string
+  file?: string | null
+}
+
 export interface Verdict {
   machine_schema_version?: string
   review_base_sha?: string
@@ -208,6 +217,8 @@ export interface Verdict {
   review_kind?: string
   findings?: Finding[]
   next_action?: string
+  // REQ-2026-005: optional 비차단 코멘트. classifyReview는 이 필드를 보지 않는다(findings 존재만으로 분류).
+  observations?: Observation[]
 }
 
 const STATUS_VALUES = ['NEEDS_FIX', 'STEP_COMPLETE', 'COMPLETE']
@@ -253,6 +264,12 @@ export function validateVerdict(
   if (v.merge_ready === 'yes' && v.commit_approved !== 'yes')
     errors.push('모순: merge_ready=yes 인데 commit_approved≠yes')
 
+  // R10 (safety, fail-closed): 승인(commit_approved=yes)은 findings가 0건이어야 한다.
+  //   findings는 **승인 차단 신호**이므로, 지적이 있는데 승인은 모순 — 미검토/미조치 코드가 승인되는 구멍을 막는다.
+  //   비차단 코멘트가 필요하면 findings가 아니라 별도 필드(예: observations)를 도입해야 한다(findings 오버로드 금지).
+  if (v.commit_approved === 'yes' && Array.isArray(v.findings) && v.findings.length > 0)
+    errors.push('모순: commit_approved=yes 인데 findings가 비어있지 않음 (승인은 findings 0건 — 지적이 있으면 미승인)')
+
   return { ok: errors.length === 0, errors }
 }
 
@@ -283,6 +300,35 @@ export interface ApprovalEvidence {
   approved_at: string
 }
 
+export type ReviewOutcome = 'approved' | 'needs-fix' | 'blocked' | 'invalid'
+
+export const REVIEW_EXIT_CODES: Record<ReviewOutcome, number> = {
+  approved: 0,
+  invalid: 1,
+  blocked: 2,
+  'needs-fix': 3,
+}
+
+export interface ProcessResponseResult {
+  ok: boolean
+  errors: string[]
+  nextState: WorkflowState
+  verdict: Verdict
+}
+
+export interface BlockedReviewTarget {
+  review_kind: ReviewKind
+  phase_id: string | null
+  review_base_sha: string
+  review_binding: string
+}
+
+export interface BlockedReviewMarker extends BlockedReviewTarget {
+  count: number
+  response_sha256: string | null
+  blocked_at: string
+}
+
 export interface WorkflowState {
   id: string
   phase: string
@@ -295,6 +341,7 @@ export interface WorkflowState {
   // REQ-016 A1: 승인 증거 핀(kind 격리) + grandfathering 트리거. 반대 kind 증거는 미오염.
   approval_evidence?: ApprovalEvidence
   design_approval_evidence?: ApprovalEvidence
+  blocked_review?: BlockedReviewMarker
   approval_evidence_required?: boolean
   [k: string]: unknown
 }
@@ -464,7 +511,7 @@ export function processResponse(args: {
   // REQ-016 A1: 승인 시 증거 핀 정본(아카이브 경로+sha). 미제공 시 evidence 미부착(하위호환).
   archive?: { path: string; sha256: string }
   approvedAt?: string
-}): { ok: boolean; errors: string[]; nextState: WorkflowState } {
+}): ProcessResponseResult {
   const { ticketDir, state, binding, threadId, designHash, schemaPath } = args
   const kind: ReviewKind = args.kind ?? 'phase'
   const respPath = join(ticketDir, 'codex-response.json')
@@ -478,6 +525,10 @@ export function processResponse(args: {
 
   const struct = validateResponseStructure(verdict, schemaPath ?? MACHINE_SCHEMA_PATH)
   const domain = validateVerdict(verdict, { reviewBaseSha: binding.reviewBaseSha })
+  // REQ-2026-005 defaulting layer: **검증(원본, observations optional) 이후** 결측/비배열 observations를 []로 정규화한다.
+  //   strict 출력 스키마(codex는 항상 observations emit)와 optional 검증 스키마(구 archive는 결측 허용) 사이의 계약을 내부적으로 일관화 —
+  //   하류(classifyReview·표출·evidence)는 observations를 **항상 배열**로 취급. 검증 전에 하지 않는 이유: 비배열(파손) observations는 AJV가 먼저 invalid로 잡아야 하기 때문.
+  verdict.observations = Array.isArray(verdict.observations) ? verdict.observations : []
   const kindMismatch = verdict.review_kind !== kind
   // design 승인엔 non-null designHash 필수(freshness anchor) — 누락은 fail-closed(Codex P3).
   const designHashMissing = kind === 'design' && !(typeof designHash === 'string' && designHash.trim().length > 0)
@@ -510,7 +561,7 @@ export function processResponse(args: {
         approvedAt: args.approvedAt ?? new Date().toISOString(),
       })
     }
-    return { ok, errors, nextState }
+    return { ok, errors, nextState, verdict }
   }
 
   // A1-P2-1: 같은 kind(phase)의 기존 증거는 항상 stale로 보고 제거(base에서 omit). 반대 kind(design)는 보존.
@@ -539,7 +590,7 @@ export function processResponse(args: {
     })
   }
 
-  return { ok, errors, nextState }
+  return { ok, errors, nextState, verdict }
 }
 
 /** state.json 기록 — UTF-8(BOM 없음), 2-space + 끝 개행. */
@@ -547,6 +598,115 @@ export function writeState(ticketDir: string, state: WorkflowState): void {
   writeFileSync(join(ticketDir, 'state.json'), `${JSON.stringify(state, null, 2)}\n`, 'utf8')
 }
 
+function verdictHasFindings(verdict: Verdict): boolean {
+  return Array.isArray(verdict.findings) && verdict.findings.length > 0
+}
+
+function isOutcomeApproved(result: ProcessResponseResult, kind: ReviewKind): boolean {
+  return kind === 'phase' ? result.nextState.commit_allowed === true : result.nextState.design_approved === true
+}
+
+/**
+ * 검증 유효성(result.ok)과 게이트 승인 여부를 분리한 최종 리뷰 outcome.
+ * - invalid  ⟺ !result.ok (구조/도메인 검증 실패). errors[]가 진단 정본.
+ * - approved  = 게이트 승인(phase=commit_allowed·design=design_approved).
+ * - needs-fix = 유효·미승인·**조치할 findings 있음**(NEEDS_FIX든 STEP_COMPLETE든 findings가 있으면 여기 — 조치 가능하므로).
+ * - blocked   = 유효·미승인·**findings 없음**(결정적 고착 — 같은 바인딩 재리뷰는 순수 낭비).
+ * ⚠️ status 기반이 아니라 **findings 존재** 기반으로 분기 — "미승인인데 findings=[]"만 blocked로 격리해야
+ *    (a) 조치할 게 있는 verdict가 진단 없이 invalid로 새는 것을 막고 (b) blocked 회로차단기가 오탐 없이 동작한다.
+ *    (NEEDS_FIX + findings=[]는 validateVerdict가 invalid로 잡으므로 여기 도달하지 않는다.)
+ */
+export function classifyReview(result: ProcessResponseResult, kind: ReviewKind): ReviewOutcome {
+  if (!result.ok) return 'invalid'
+  if (isOutcomeApproved(result, kind)) return 'approved'
+  if (verdictHasFindings(result.verdict)) return 'needs-fix'
+  return 'blocked'
+}
+
+export function reviewOutcomeExitCode(outcome: ReviewOutcome): number {
+  return REVIEW_EXIT_CODES[outcome]
+}
+
+/**
+ * 리뷰 결과 → 최종 outcome·종료코드·기록할 state(순수). main() 종료 배선의 **단일 정본**
+ * (main이 이 함수를 호출하므로 병렬 재구현으로 인한 drift가 없다 — exit-code 계약을 테스트로 고정 가능).
+ * - outcome = classifyReview
+ * - blocked → 회로차단기 마커 기록(같은 target이면 count 증가), 그 외 → 마커 제거(clear)
+ * - exitCode: approved=0 · invalid=1 · blocked=2 · needs-fix=3
+ */
+export function resolveReviewOutcome(args: {
+  result: ProcessResponseResult
+  kind: ReviewKind
+  blockedTarget: BlockedReviewTarget
+  responseSha256: string | null
+  blockedAt: string
+}): { outcome: ReviewOutcome; exitCode: number; finalState: WorkflowState } {
+  const outcome = classifyReview(args.result, args.kind)
+  const finalState =
+    outcome === 'blocked'
+      ? recordBlockedReview(args.result.nextState, args.blockedTarget, args.responseSha256, args.blockedAt)
+      : clearBlockedReview(args.result.nextState)
+  return { outcome, exitCode: reviewOutcomeExitCode(outcome), finalState }
+}
+
+export function buildBlockedReviewTarget(args: {
+  kind: ReviewKind
+  phaseId: string | null
+  binding: Binding
+  designHash?: string | null
+}): BlockedReviewTarget {
+  return {
+    review_kind: args.kind,
+    phase_id: args.kind === 'phase' ? args.phaseId ?? null : null,
+    review_base_sha: args.binding.reviewBaseSha,
+    review_binding: args.kind === 'design' ? args.designHash ?? args.binding.reviewTree : args.binding.reviewTree,
+  }
+}
+
+function sameBlockedReviewTarget(a: BlockedReviewMarker | undefined, b: BlockedReviewTarget): boolean {
+  return (
+    !!a &&
+    a.review_kind === b.review_kind &&
+    a.phase_id === b.phase_id &&
+    a.review_base_sha === b.review_base_sha &&
+    a.review_binding === b.review_binding
+  )
+}
+
+export function shouldShortCircuitBlockedReview(
+  state: WorkflowState,
+  target: BlockedReviewTarget,
+  limit = 2,
+): boolean {
+  const marker = state.blocked_review
+  if (!marker || !sameBlockedReviewTarget(marker, target)) return false
+  return marker.count >= limit
+}
+
+export function recordBlockedReview(
+  state: WorkflowState,
+  target: BlockedReviewTarget,
+  responseSha256: string | null,
+  blockedAt: string,
+): WorkflowState {
+  const marker = state.blocked_review
+  const count = marker && sameBlockedReviewTarget(marker, target) ? marker.count + 1 : 1
+  return {
+    ...state,
+    blocked_review: {
+      ...target,
+      count,
+      response_sha256: responseSha256,
+      blocked_at: blockedAt,
+    },
+  }
+}
+
+export function clearBlockedReview(state: WorkflowState): WorkflowState {
+  const { blocked_review: _blocked, ...rest } = state
+  return rest
+}
+
 // parseThreadId는 lib/adapters로 이동(codex CLI 전용 로직) — 상단에서 re-export.
 
 /**
@@ -668,13 +828,48 @@ export function buildApprovalEvidence(args: {
  * 유효 + 승인(phase=commit_allowed·design=design_approved) → 'approved', 그 외(유효 NEEDS_FIX) → 'needs-fix'.
  */
 export function archiveDecision(
-  result: { ok: boolean; nextState: WorkflowState },
+  result: ProcessResponseResult,
   kind: ReviewKind,
 ): 'approved' | 'needs-fix' | null {
-  if (!result.ok) return null
-  const approved =
-    kind === 'phase' ? result.nextState.commit_allowed === true : result.nextState.design_approved === true
-  return approved ? 'approved' : 'needs-fix'
+  const outcome = classifyReview(result, kind)
+  if (outcome === 'approved') return 'approved'
+  if (outcome === 'needs-fix') return 'needs-fix'
+  return null
+}
+
+function outcomeLabel(outcome: ReviewOutcome): string {
+  if (outcome === 'needs-fix') return 'NEEDS_FIX'
+  return outcome.toUpperCase()
+}
+
+/** 비차단 코멘트(observations) 표출 — REQ-2026-005. 승인에서도 보이게(사용자가 놓치지 않게). 판정엔 영향 없음. */
+function printObservations(verdict: Verdict): void {
+  const obs = Array.isArray(verdict.observations) ? verdict.observations : []
+  if (!obs.length) return
+  console.error('   observations (non-blocking):')
+  for (const o of obs) {
+    const where = o.file ? ` ${o.file}` : ''
+    console.error(`   -${where}: ${o.detail ?? ''}`)
+  }
+}
+
+function printOutcomeDetails(outcome: ReviewOutcome, result: ProcessResponseResult): void {
+  if (outcome === 'needs-fix') {
+    for (const f of result.verdict.findings ?? []) {
+      const where = f.file ? ` ${f.file}` : ''
+      console.error(`   - ${f.severity ?? 'P?'}${where}: ${f.detail ?? ''}`)
+    }
+    if (typeof result.verdict.next_action === 'string' && result.verdict.next_action.trim())
+      console.error(`   next_action: ${result.verdict.next_action}`)
+  } else if (outcome === 'blocked') {
+    console.error('   - Codex returned no actionable findings but did not approve the gate.')
+    console.error('   - Do not retry the same review without changing the binding or escalating to a human.')
+  } else if (outcome === 'invalid') {
+    for (const e of result.errors) console.error(`   - ${e}`)
+    return // invalid는 errors만 — observations 미표출
+  }
+  // approved/needs-fix/blocked에서 비차단 코멘트 표출(특히 approved에서 사용자가 코멘트를 놓치지 않게).
+  printObservations(result.verdict)
 }
 
 // ──────────────────────────────────────────────────────────────── CLI ──
@@ -687,11 +882,15 @@ export interface Opts {
   kind: ReviewKind
   phase: string | null
   root: string | null
+  freshThread: boolean
 }
 
-/** CLI 파싱. `--kind design|phase`(기본 phase, 하위호환)·`--phase <id>`(phase kind 대상). 잘못된 --kind/--phase 값은 fail-closed throw. */
+/**
+ * CLI 파싱. `--kind design|phase`(기본 phase, 하위호환)·`--phase <id>`(phase kind 대상). 잘못된 --kind/--phase 값은 fail-closed throw.
+ * `--fresh-thread`: blocked 회로차단기의 명시적 회복 경로 — blocked_review 마커를 초기화하고 codex 스레드를 새로 시작(고착된 resume 스레드를 끊는다).
+ */
 export function parseArgs(argv: string[]): Opts {
-  const opts: Opts = { ticket: null, reqId: null, handoff: null, run: false, kind: 'phase', phase: null, root: null }
+  const opts: Opts = { ticket: null, reqId: null, handoff: null, run: false, kind: 'phase', phase: null, root: null, freshThread: false }
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i]
     if (a === undefined) continue
@@ -713,6 +912,7 @@ export function parseArgs(argv: string[]): Opts {
       opts.phase = v
     } else if (a === '--run') opts.run = true // 라이브 codex 호출(미지정 시 dry-run 미리보기)
     else if (a === '--dry-run') opts.run = false
+    else if (a === '--fresh-thread') opts.freshThread = true // blocked 회복: 마커 초기화 + 새 스레드
     else if (!a.startsWith('-')) opts.reqId = a
   }
   return opts
@@ -758,7 +958,9 @@ function main(): void {
   const cfg = loadConfig({ root: opts.root })
   gitAdapter = createGitAdapter(cfg.root) // 모든 git 호출 cwd = config.root
   const ticketDir = resolveTicketDir(opts, cfg)
-  const state = loadState(ticketDir) // 부재 시 명확한 에러
+  let state = loadState(ticketDir) // 부재 시 명확한 에러
+  // --fresh-thread: blocked 회로차단기 명시적 회복 — 마커 제거(단락 해제) + resume 대신 새 스레드(고착 resume 끊기).
+  if (opts.freshThread) state = clearBlockedReview(state)
 
   const requestPath = join(ticketDir, 'codex-request.md')
   if (!existsSync(requestPath)) throw new Error(`codex-request.md 없음: ${requestPath}`)
@@ -801,6 +1003,12 @@ function main(): void {
   } else {
     stagedDiff = git(['diff', '--cached'])
   }
+  const blockedTarget = buildBlockedReviewTarget({
+    kind: opts.kind,
+    phaseId,
+    binding: { reviewBaseSha, reviewTree },
+    designHash,
+  })
 
   const reviewContext: ReviewContext = {
     branch,
@@ -839,7 +1047,8 @@ function main(): void {
   // 워크플로 도구가 쓰는 메타데이터(응답·프리뷰·state)는 리뷰 대상 아님 → exact 경로로 허용(precondition/무수정검증 제외).
   // 특히 state.json은 직전 라운드 writeState로 unstaged가 되므로 resume(2회차) precondition 통과에 필수(4C e2e 발견).
   const SCRATCH = [repoRel(respPath), repoRel(previewPath), repoRel(join(ticketDir, 'state.json'))]
-  const isResume = typeof state.codex_thread_id === 'string' && state.codex_thread_id.length > 0
+  // --fresh-thread면 codex_thread_id가 있어도 resume하지 않고 새 exec으로 시작(고착 스레드 회복).
+  const isResume = !opts.freshThread && typeof state.codex_thread_id === 'string' && state.codex_thread_id.length > 0
 
   // Phase 4: 추적 phase는 유효 design 승인 전제(D13 동일) — 미충족 시 호출 전 fail-closed(불필요 codex 호출 방지).
   if (phaseId && !designValid)
@@ -855,6 +1064,12 @@ function main(): void {
       `리뷰 전 워킹트리에 unstaged/untracked 존재(D10) — 의도 변경은 git add, 그 외 정리 필요:\n  ${preDirty.join('\n  ')}`,
     )
 
+  if (shouldShortCircuitBlockedReview(state, blockedTarget)) {
+    console.error('[req:review-codex] BLOCKED  repeated blocked result for the same review binding')
+    console.error('  Codex will not be called again for this unchanged target. Change the staged binding or escalate.')
+    process.exit(reviewOutcomeExitCode('blocked'))
+  }
+
   console.warn(`⚠️  codex 실제 호출 (${isResume ? 'resume' : 'exec'}) — 호출 1회 발생 (DEC-WF-026: 호출 직전 확인)`)
 
   // ReviewerAdapter 경유(Phase 3). exec/resume 분기·--output-last-message·thread 파싱은 어댑터가 담당.
@@ -911,16 +1126,24 @@ function main(): void {
     decision === 'approved' && archiveDesc
       ? processResponse({ ...baseArgs, archive: archiveDesc, approvedAt })
       : probe
-  writeState(ticketDir, result.nextState)
+  const responseSha256 = existsSync(respPath)
+    ? createHash('sha256').update(readFileSync(respPath)).digest('hex')
+    : null
+  const { outcome, exitCode, finalState } = resolveReviewOutcome({
+    result,
+    kind: opts.kind,
+    blockedTarget,
+    responseSha256,
+    blockedAt: approvedAt,
+  })
+  writeState(ticketDir, finalState)
 
-  console.log(`[req:review-codex] ${result.ok ? 'OK' : 'FAIL(fail-closed)'}  thread=${threadId}`)
+  console.log(`[req:review-codex] ${outcomeLabel(outcome)}  thread=${threadId}`)
   console.log(
-    `  commit_allowed=${String(result.nextState.commit_allowed)}  approved=${String(result.nextState.approved_diff_hash ?? 'null')}`,
+    `  commit_allowed=${String(finalState.commit_allowed)}  approved=${String(finalState.approved_diff_hash ?? 'null')}`,
   )
-  if (!result.ok) {
-    for (const e of result.errors) console.error(`   - ${e}`)
-    process.exit(1)
-  }
+  printOutcomeDetails(outcome, result)
+  if (exitCode !== 0) process.exit(exitCode)
 }
 
 const isMain = import.meta.url === pathToFileURL(process.argv[1] ?? '').href

package/workflow/machine.schema.json

@@ -16,7 +16,11 @@
     "machine_schema_version": { "type": "string", "enum": ["1.1"] },
     "review_base_sha": { "type": "string" },
     "status": { "type": "string", "enum": ["NEEDS_FIX", "STEP_COMPLETE", "COMPLETE"] },
-    "commit_approved": { "type": "string", "enum": ["yes", "no"] },
+    "commit_approved": {
+      "type": "string",
+      "enum": ["yes", "no"],
+      "description": "Gate approval for this review. For review_kind=design, yes means the design is approved to proceed (nothing is committed); approve a good design with commit_approved=yes and merge_ready=no. For review_kind=phase, yes means the staged tree is approved to commit. Approve (yes) ONLY when findings is empty: any finding is a blocking signal, so commit_approved=yes with a non-empty findings array is a contradiction and is rejected. Conversely, returning no with an empty findings array is also a contradiction and is rejected as BLOCKED — if you have no findings you must approve. Minor/non-blocking remarks do NOT belong in findings; put them in observations and still approve."
+    },
     "merge_ready": { "type": "string", "enum": ["yes", "no"] },
     "risk_level": { "type": "string", "enum": ["LOW", "HIGH"] },
     "review_kind": { "type": "string", "enum": ["design", "phase"] },
@@ -33,6 +37,19 @@
         }
       }
     },
-    "next_action": { "type": "string" }
+    "next_action": { "type": "string" },
+    "observations": {
+      "type": "array",
+      "description": "Optional non-blocking comments that do NOT block approval or gate the commit. Use this (NOT findings) for minor/nit remarks when approving. Items carry detail and file only — deliberately NO severity (severity belongs to blocking findings). commit_approved=yes with findings=[] and observations present is still approved. observations never substitute for findings: commit_approved=no with findings=[] and observations only is still BLOCKED.",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["detail", "file"],
+        "properties": {
+          "detail": { "type": "string" },
+          "file": { "type": ["string", "null"] }
+        }
+      }
+    }
   }
 }