commitgate 0.4.0 → 0.8.0

package/scripts/req/req-next.ts

@@ -15,22 +15,28 @@
  * ⚠️ **강제(enforcement)가 아니라 자문(advisory)이다.** 승인 게이트는 여전히 `req:review-codex`/`req:commit`에 있다.
  * `req:next`가 틀려도 게이트는 뚫리지 않는다. 그래서 애매하면 `RUN` 쪽으로 기운다(fail-forward).
  *
- * 사용: npm run req:next -- <REQ-id> [--json] [--root <path>] [--ticket <dir>]
+ * 사용: req:next <REQ-id> [--json] [--root <path>] [--ticket <dir>]   (저장소 패키지매니저의 실행 형식으로)
  */
 import { resolve, join, relative } from 'node:path'
 import { pathToFileURL } from 'node:url'
 import { loadConfig, buildScriptInvocation, type PackageManager } from './lib/config'
 import { createGitAdapter, type GitAdapter } from './lib/adapters'
+import { parseStatusZ, STATUS_Z_ARGS } from './lib/porcelain'
+import { reviewScratchPaths } from './lib/scratch'
 import {
   loadState,
   readPhases,
   captureDesignBinding,
   captureIndexHash,
   findUnstagedOrUntracked,
+  isLegacyTicket,
+  openSeriesAttempts,
+  isSeriesKeyTerminal,
   type WorkflowState,
   type ReviewKind,
   type LastReviewMarker,
 } from './review-codex'
+import type { ReviewBudget } from './lib/config'
 
 // ─────────────────────────────────────────────── 읽기 전용 git 경계 (D6-1) ──
 
@@ -128,6 +134,8 @@ export interface NextInput {
   worktreeReviewClean: boolean
   /** 현재 인덱스 전체 해시(`captureIndexHash`). 계산 불가면 null. */
   currentIndexHash: string | null
+  /** REQ-2026-028 A-2a: review 예산(G3 escalated 판정용). main이 cfg에서 채운다. */
+  reviewBudget: ReviewBudget
 }
 
 /** `consumed_approvals[]`에서 phase_id를 안전하게 읽는다. */
@@ -317,6 +325,14 @@ function commitCmd(pm: PackageManager, target: NextTarget): string {
   return buildScriptInvocation(pm, 'req:commit', [...targetArgs(target), '--run']).join(' ')
 }
 
+/**
+ * 대상(REQ id 또는 `--ticket`) 미지정 에러 문구(DEC-011-1). **config 로드 이후**라 pm별로 파생한다.
+ * 리터럴을 박으면 다른 pm 프로젝트의 사용자가 그대로 따라 할 수 없는 명령을 안내받는다.
+ */
+export function missingTargetHint(pm: PackageManager): string {
+  return `REQ id 또는 --ticket <dir> 필요 (예: ${buildScriptInvocation(pm, 'req:next', ['2026-010']).join(' ')})`
+}
+
 interface RunCandidate {
   command: string
   kind: ReviewKind
@@ -345,6 +361,48 @@ function gateRunCandidate(input: NextInput, cand: RunCandidate): NextAction {
         '워킹트리에 unstaged/untracked 변경이 있어 리뷰(D10)가 실패한다. 의도한 변경은 `git add`, 그 외는 정리한 뒤 다시 req:next.',
     }
 
+  // terminal (REQ-2026-029 A-2b): human-resolution으로 종결된 키 → AWAIT_HUMAN. **G3보다 앞**(R4) — 종결된
+  // series는 예산 안내("고치고 예외 받으라")가 아니라 "이미 끝났다 — 대체 REQ" 안내가 맞다. G1보다는 뒤
+  // (dirty면 정리 먼저). 우선순위: G1 → terminal → G3 → G2.
+  if (isSeriesKeyTerminal(input.state, cand.kind, cand.phaseId))
+    return {
+      kind: 'AWAIT_HUMAN',
+      detail: '이 series는 human-resolution으로 종결됐다. 같은 키에서 자동으로 재개하지 않는다.',
+      controlPoint: 'human-resolution 종결됨',
+      approvalSentence: '대체가 필요하면 `req:new --successor-of <이 REQ>`로 만든다(종결 상태 유지 결정도 사람이 한다)',
+      diagnostics: ['종결 사유: human-resolution', '재개는 자동으로 일어나지 않는다 — 대체 REQ 또는 종결 유지.'],
+    }
+
+  // G3 (REQ-2026-028 A-2a): 자동 예산 소진(escalated) → AWAIT_HUMAN. **G2보다 앞**(R13) — 5회차 NEEDS_FIX
+  // 직후엔 escalated와 같은 바인딩 needs-fix가 동시 성립하는데, G2가 먼저 "findings 고치고 다시 add"(AGENT)를
+  // 내면 그 조언이 거짓이다(고쳐도 사람 승인 없이 6회차가 안 열린다). escalated는 파생값(저장 안 함, R11).
+  const openAttempts = openSeriesAttempts(input.state, cand.kind, cand.phaseId)
+  const { autoBudget, hardCap } = input.reviewBudget
+  if (openAttempts >= autoBudget) {
+    const nextAttempt = openAttempts + 1
+    const lrOutcome = (input.state.last_review as LastReviewMarker | undefined)?.outcome ?? '(없음)'
+    const hardBlocked = openAttempts >= hardCap
+    // ⚠️ "위험 수용"은 어느 문구에도 넣지 않는다(배분표 ④ — 부정문으로도 금지). 긍정 선택지만 나열.
+    const options = hardBlocked
+      ? '예외로도 진행 불가 — 종료하거나 정합한 대체 REQ를 작성한다.'
+      : '사람 승인 시 1회 예외 가능(review_exception_confirmed) · 종료 · 정합한 대체 REQ 작성.'
+    return {
+      kind: 'AWAIT_HUMAN',
+      detail: hardBlocked
+        ? `이 series는 하드 상한(hardCap=${hardCap})에 도달했다. ${nextAttempt}회차는 어떤 경로로도 실행하지 않는다.`
+        : `이 series는 자동 예산(autoBudget=${autoBudget})을 소진했다. ${nextAttempt}회차는 사람 결정이 필요하다.`,
+      controlPoint: 'review 예산 소진(escalated)',
+      approvalSentence: hardBlocked
+        ? 'review 하드 상한 도달 — 종료 또는 대체 REQ 작성(둘 중 하나를 사람이 결정)'
+        : `review ${nextAttempt}회차 예외 승인(또는 종료·대체 REQ 작성)`,
+      diagnostics: [
+        `series 시도 수(openAttempts)=${openAttempts} · 다음 회차=${nextAttempt}`,
+        `직전 리뷰 outcome=${lrOutcome}`,
+        `선택지: ${options}`,
+      ],
+    }
+  }
+
   // G2
   const lr = input.state.last_review as LastReviewMarker | undefined
   const sameTarget =
@@ -428,6 +486,18 @@ export function resolveNext(input: NextInput): NextAction {
       approvalSentence: 'req:commit --run 승인',
     }
 
+  // 1.5 legacy ticket(REQ-2026-027 D1): 모델 버전 부재 = legacy. 살아 있는 승인(1번)보다는 뒤 —
+  // 그건 소비만 하면 되고 새 외부 호출이 아니다. design/phase RUN 후보(2·3번)보다는 **앞** — 그 후보를
+  // 내면 사용자가 실행한 뒤에야 호출 지점에서 throw된다(R2는 AWAIT_HUMAN을 요구). 자동 초기화하지 않는다.
+  if (isLegacyTicket(state))
+    return {
+      kind: 'AWAIT_HUMAN',
+      detail:
+        'legacy ticket(review_series_model_version 부재)이다. 자동으로 새 모델로 초기화하지 않는다 — 사람이 이 티켓을 새 series 모델로 채택할지 결정해야 한다.',
+      controlPoint: 'legacy 티켓 채택',
+      approvalSentence: 'state.json에 review_series_model_version: 1 추가(이 티켓을 새 모델로 채택) 승인',
+    }
+
   // 2. 설계 문서가 인덱스에 없으면 3번의 freshness 판정(captureDesignBinding)이 throw한다. 여기서 먼저 거른다.
   if (!input.designDocsInIndex)
     return {
@@ -553,7 +623,11 @@ export function parseArgs(argv: string[]): Opts {
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i]
     if (a === undefined) continue
-    if (a === '--json') o.json = true
+    // bare `--`는 옵션이 아니라 POSIX end-of-options 마커다(DEC-011-3). npm은 `npm run x -- a`에서
+    // 이를 제거하지만 pnpm/yarn은 그대로 넘긴다 → 흡수한다. 이후 인자도 계속 옵션으로 파싱한다
+    // (전부 위치인자로 삼키면 `req:commit <id> -- --run`이 조용히 dry-run이 된다).
+    if (a === '--') continue
+    else if (a === '--json') o.json = true
     else if (a === '--ticket') o.ticket = argv[++i] ?? null
     else if (a === '--root') {
       const v = argv[++i]
@@ -578,15 +652,14 @@ export function renderAction(displayId: string, a: NextAction): string {
   return lines.join('\n')
 }
 
-function main(): void {
-  const opts = parseArgs(process.argv.slice(2))
+export function main(argv: string[] = process.argv.slice(2)): void {
+  const opts = parseArgs(argv)
   const cfg = loadConfig({ root: opts.root })
   const roGit = createReadOnlyGit(createGitAdapter(cfg.root))
 
   // target은 **사용자가 티켓을 지목한 방식 그대로** 보존한다(R5). `--ticket`으로 읽었으면 후속 명령도 `--ticket`을 쓴다 —
   // 그러지 않으면 `req:review-codex -- <reqId>`가 기본 위치의 **다른 티켓**을 리뷰한다.
-  if (!opts.ticket && !opts.reqId)
-    throw new Error('REQ id 또는 --ticket <dir> 필요 (예: npm run req:next -- 2026-010)')
+  if (!opts.ticket && !opts.reqId) throw new Error(missingTargetHint(cfg.packageManager))
   const target: NextTarget = opts.ticket
     ? { kind: 'ticket', ticketDir: opts.ticket }
     : { kind: 'req', reqId: (opts.reqId as string).replace(/^REQ-/, '') }
@@ -605,16 +678,9 @@ function main(): void {
     currentDesignHash = null
   }
 
-  const statusLines = roGit(['-c', 'core.quotePath=false', 'status', '--porcelain', '--untracked-files=all'])
-    .split('\n')
-    .filter(Boolean)
-  // review-codex/doctor와 동일한 스크래치 집합 — 워크플로 도구가 쓰는 메타데이터는 D10 대상이 아니다.
-  const repoRel = (abs: string) => relative(cfg.root, abs).replace(/\\/g, '/')
-  const scratch = [
-    repoRel(join(ticketDir, 'codex-response.json')),
-    repoRel(join(ticketDir, '.review-preview.txt')),
-    repoRel(join(ticketDir, 'state.json')),
-  ]
+  const statusEntries = parseStatusZ(roGit([...STATUS_Z_ARGS]))
+  // review-codex/doctor와 동일한 스크래치 집합(lib/scratch SSOT) — 워크플로 도구가 쓰는 메타데이터는 D10 대상이 아니다.
+  const scratch = reviewScratchPaths(ticketRel)
 
   const action = resolveNext({
     target,
@@ -623,8 +689,9 @@ function main(): void {
     designDocsInIndex: currentDesignHash !== null,
     currentDesignHash,
     hasStagedChanges: roGit(['diff', '--cached', '--name-only']).trim().length > 0,
-    worktreeReviewClean: findUnstagedOrUntracked(statusLines, scratch, ticketRel).length === 0,
+    worktreeReviewClean: findUnstagedOrUntracked(statusEntries, scratch, ticketRel).length === 0,
     currentIndexHash: captureIndexHash(roGit),
+    reviewBudget: cfg.reviewBudget,
   })
 
   if (opts.json) console.log(JSON.stringify({ req_id: state.id, ...action }, null, 2))
@@ -634,5 +701,15 @@ function main(): void {
   if (code !== 0) process.exit(code)
 }
 
+/** bin dispatch 진입점(친절한 1줄 오류 + exit 1 경계). 직접 `tsx` 실행은 아래 `if (isMain) main()`이 그대로 담당(하위호환). */
+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()