commitgate 0.7.0 → 0.8.1

package/scripts/req/req-new.ts

@@ -7,12 +7,14 @@
  *   - 기본 dry-run(계획 출력), `--run` 시 실제 브랜치 생성·티켓 파일·스캐폴드 커밋.
  *   - REQ id 채번은 registry 미사용(1차) — workflow/REQ-* 디렉터리 스캔으로 max+1.
  *
- * 사용: req:new <slug> [--run] [--risk LOW|HIGH] [--title "..."]   (저장소 패키지매니저의 실행 형식으로)
+ * 사용: req:new <slug> [--run] [--risk LOW|HIGH] [--title "..."] [--successor-of <REQ-id>]
+ *   --successor-of: 대체 REQ. 부모에 replace 종결(human-resolution) 기록이 있어야 하며, 없으면 fail-closed
+ *     (티켓 미생성). lineage는 부모 state에서 읽는다(REQ-2026-029 A-2b).
  */
 import { mkdirSync, writeFileSync, readdirSync, existsSync } from 'node:fs'
 import { join, relative } from 'node:path'
 import { pathToFileURL } from 'node:url'
-import { writeState, type WorkflowState } from './review-codex'
+import { writeState, loadState, resolveSuccessorLineage, type WorkflowState, type SuccessorOf } from './review-codex'
 import { loadConfig, packageRoot, buildScriptInvocation, type DesignDocs, type PackageManager } from './lib/config'
 import { createGitAdapter, type GitAdapter } from './lib/adapters'
 import { parseStatusZ, formatStatusEntry, STATUS_Z_ARGS, type StatusEntry } from './lib/porcelain'
@@ -69,7 +71,7 @@ export function nextStepHint(pm: PackageManager, reqId: string): string {
   return `코드 변경 → git add → ${buildScriptInvocation(pm, 'req:review-codex', [id, '--run']).join(' ')}`
 }
 
-export function buildInitialState(reqId: string, branch: string, risk: 'LOW' | 'HIGH'): WorkflowState {
+export function buildInitialState(reqId: string, branch: string, risk: 'LOW' | 'HIGH', successorOf?: SuccessorOf): WorkflowState {
   return {
     id: reqId,
     branch,
@@ -87,7 +89,12 @@ export function buildInitialState(reqId: string, branch: string, risk: 'LOW' | '
     phases: [],
     // REQ-016 A1(D-016-6): grandfathering 트리거 — 신규 REQ는 승인 증거를 강제(FAIL), legacy(필드 부재)는 WARN.
     approval_evidence_required: true,
-  }
+    // REQ-2026-027 D1: review series 모델 버전. 첫 리뷰 전에도 존재해 "새 ticket(레코드 없음)"과
+    // "legacy(필드 부재)"를 구분한다. 필드 부재 = legacy → 새 재리뷰 시 AWAIT_HUMAN/throw(자동 초기화 금지).
+    review_series_model_version: 1,
+    // REQ-2026-029 D3: 대체 REQ면 부모 lineage(--successor-of). 빈 review_series로 새 예산 — 부모 이력만 보존.
+    ...(successorOf ? { successor_of: successorOf } : {}),
+  } as WorkflowState
 }
 
 function listExistingReqIds(workflowDir: string): string[] {
@@ -103,11 +110,12 @@ export interface Opts {
   title: string | null
   run: boolean
   root: string | null
+  successorOf: string | null // REQ-2026-029 D3: 부모 REQ id(대체 REQ lineage)
 }
 
 /** 인자 파싱(fail-closed): 잘못된 --risk·값 누락·알 수 없는 옵션은 즉시 throw(조용한 fallback 금지). */
 export function parseArgs(argv: string[]): Opts {
-  const o: Opts = { slug: null, risk: 'LOW', title: null, run: false, root: null }
+  const o: Opts = { slug: null, risk: 'LOW', title: null, run: false, root: null, successorOf: null }
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i]
     if (a === undefined) continue
@@ -120,6 +128,10 @@ export function parseArgs(argv: string[]): Opts {
       const v = argv[++i]
       if (v === undefined) throw new Error('--root 값 필요')
       o.root = v
+    } else if (a === '--successor-of') {
+      const v = argv[++i]
+      if (v === undefined) throw new Error('--successor-of 값 필요(부모 REQ id)')
+      o.successorOf = v
     } else if (a === '--risk') {
       const v = argv[++i]
       if (v !== 'LOW' && v !== 'HIGH')
@@ -156,12 +168,29 @@ export function main(argv: string[] = process.argv.slice(2)): void {
   const ticketRootRel = relative(cfg.root, cfg.workflowDirAbs).replace(/\\/g, '/')
   const ticketRel = relative(cfg.root, ticketDir).replace(/\\/g, '/')
 
+  // REQ-2026-029 D3: --successor-of lineage 해소. **branch 생성·mkdir 前**에 검증(design-r01 observation) —
+  // 부모 없음·replace 기록 없음·형식 위반이면 여기서 throw해 티켓이 생성되지 않는다(R6 fail-closed).
+  let successorOf: SuccessorOf | undefined
+  if (o.successorOf !== null) {
+    const parentId = o.successorOf.startsWith('REQ-') ? o.successorOf : `REQ-${o.successorOf}`
+    const parentDir = join(cfg.workflowDirAbs, parentId)
+    let parentState: WorkflowState
+    try {
+      parentState = loadState(parentDir)
+    } catch {
+      throw new Error(`--successor-of ${parentId}: 부모 티켓 state를 읽을 수 없다(${parentDir})`)
+    }
+    // recorded_at은 자식 생성 시각(부모 값 아님). dry-run에선 검증만 하고 값은 버린다.
+    successorOf = resolveSuccessorLineage(parentState, parentId, new Date().toISOString())
+  }
+
   if (!o.run) {
     console.log('[req:new] DRY-RUN (--run 시 실제 생성)')
     console.log(`  REQ    : ${reqId}`)
     console.log(`  branch : ${branch}`)
     console.log(`  ticket : ${ticketRel}/ (state.json·${dd.requirement}·${dd.design}·${dd.plan}·codex-request.md)`)
     console.log(`  risk   : ${o.risk}`)
+    if (successorOf) console.log(`  successor_of : ${successorOf.req_id} (부모 ${successorOf.parent_attempts_total}회 · replace 승인 확인)`)
     return
   }
 
@@ -182,7 +211,7 @@ export function main(argv: string[] = process.argv.slice(2)): void {
 
   git(['checkout', '-b', branch]) // D11/DEC-WF-020: feat/req-* 생성·체크아웃
   mkdirSync(ticketDir, { recursive: true })
-  writeState(ticketDir, buildInitialState(reqId, branch, o.risk))
+  writeState(ticketDir, buildInitialState(reqId, branch, o.risk, successorOf))
   writeFileSync(join(ticketDir, dd.requirement), `# ${reqId} 요구사항\n\n${o.title ?? '(요구사항 작성)'}\n`, 'utf8')
   // DEC-WF-027 design-first: design·plan 스캐폴드도 함께 생성 — 첫 --kind design 리뷰가 문서 누락으로 fail-closed 되지 않게.
   writeFileSync(

package/scripts/req/req-next.ts

@@ -29,10 +29,14 @@ import {
   captureDesignBinding,
   captureIndexHash,
   findUnstagedOrUntracked,
+  isLegacyTicket,
+  openSeriesAttempts,
+  isSeriesKeyTerminal,
   type WorkflowState,
   type ReviewKind,
   type LastReviewMarker,
 } from './review-codex'
+import type { ReviewBudget } from './lib/config'
 
 // ─────────────────────────────────────────────── 읽기 전용 git 경계 (D6-1) ──
 
@@ -130,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를 안전하게 읽는다. */
@@ -355,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 =
@@ -438,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 {
@@ -631,6 +691,7 @@ export function main(argv: string[] = process.argv.slice(2)): void {
     hasStagedChanges: roGit(['diff', '--cached', '--name-only']).trim().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))