commitgate 0.3.0 → 0.4.0

package/bin/uninstall.ts

@@ -21,12 +21,17 @@ import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs'
 import { createHash } from 'node:crypto'
 import { resolve, join, relative } from 'node:path'
 import { pathToFileURL } from 'node:url'
-import { loadConfig, stripBom, DEFAULTS } from '../scripts/req/lib/config'
+import { loadConfig, stripBom, DEFAULTS, DEFAULT_REVIEW_PERSONA_RELPATH } from '../scripts/req/lib/config'
 import { createGitAdapter, type GitAdapter, type GitRunner } from '../scripts/req/lib/adapters'
 import {
   PACKAGE_ROOT,
   KIT_SOURCE_DIR_REL,
   KIT_SCHEMA_RELPATHS,
+  KIT_COPY_RELPATHS,
+  KIT_AGENT_ENTRYPOINTS,
+  KIT_CLAUDE_TEMPLATE_REL,
+  KIT_CLAUDE_DEST_REL,
+  KIT_AGENTS_CONTRACT_COPY_REL,
   REQ_SCRIPTS,
   REQ_DEV_DEPS,
   assertGitWorkTree,
@@ -36,7 +41,11 @@ export interface UninstallOptions {
   dir: string
 }
 
-/** CommitGate가 복사한 파일(kit 소스 + init이 실제로 복사한 스키마). 바이트 비교로 무결성만 표기. */
+/**
+ * CommitGate가 복사한 파일. `path`는 **대상 repo의 경로(dest)**다.
+ * 원본(src)은 패키지 안에서 경로가 다를 수 있다(`templates/claude-skill.md` → `.claude/skills/commitgate/SKILL.md`).
+ * 바이트 비교로 무결성만 표기.
+ */
 export interface ToolArtifact {
   path: string // repo-상대
   present: boolean
@@ -173,11 +182,13 @@ export function collectFacts(opts: UninstallOptions, run?: GitRunner): Uninstall
   // (깨진 config 때문에 제거 안내를 못 받는 건 부당하다 — planner는 쓰기가 없어 강등이 안전).
   let ticketRoot = DEFAULTS.ticketRoot
   let schemaPath = DEFAULTS.schemaPath
+  let reviewPersonaPath = DEFAULTS.reviewPersonaPath
   let configError: string | null = null
   try {
     const cfg = loadConfig({ root: targetRoot })
     ticketRoot = cfg.ticketRoot
     schemaPath = cfg.schemaPath
+    reviewPersonaPath = cfg.reviewPersonaPath
   } catch (e) {
     configError = (e as Error).message
   }
@@ -190,25 +201,41 @@ export function collectFacts(opts: UninstallOptions, run?: GitRunner): Uninstall
     info.push(
       `schemaPath=${schemaPath} — 런타임이 읽는 경로이지만 init이 복사한 파일이 아닙니다(제거 후보 아님).`,
     )
+  // reviewPersonaPath도 같은 축 분기(REQ-2026-010). null=의도적 비활성이므로 알릴 것이 없다.
+  if (reviewPersonaPath !== null && reviewPersonaPath !== DEFAULT_REVIEW_PERSONA_RELPATH)
+    info.push(
+      `reviewPersonaPath=${reviewPersonaPath} — 런타임이 읽는 경로이지만 init이 복사한 파일이 아닙니다(제거 후보 아님).`,
+    )
 
-  // ── tool: kit 소스 + init이 **실제로 복사한** 스키마(항상 리터럴 workflow/ — ticketRoot 무관)
+  // ── tool: kit 소스 + init이 **실제로 복사한** 파일들.
+  //
+  // ⚠️ `src`와 `dest`가 다른 항목이 있다(REQ-2026-010 D8). `KIT_AGENT_ENTRYPOINTS`는 `templates/*` →
+  //    `.claude/…`·`.cursor/…`로 가고, `AGENTS.commitgate.md`는 `AGENTS.template.md`의 사본이다.
+  //    "원본을 `join(PACKAGE_ROOT, rel)`로 찾는다"는 가정을 버리고 매핑을 명시한다.
+  // 복사 축(KIT_COPY_RELPATHS)을 쓴다. 위 info의 스키마 축(KIT_SCHEMA_RELPATHS)과 의도적으로 다른 상수다.
   const kitSourceRels = walkFiles(join(PACKAGE_ROOT, KIT_SOURCE_DIR_REL)).map(toRel)
-  const toolRels = [...kitSourceRels, ...KIT_SCHEMA_RELPATHS]
-  const tool: ToolArtifact[] = toolRels.map((rel) => {
-    const dest = join(targetRoot, rel)
-    const src = join(PACKAGE_ROOT, rel)
+  const toolEntries: { destRel: string; srcRel: string }[] = [
+    ...kitSourceRels.map((r) => ({ destRel: r, srcRel: r })),
+    ...KIT_COPY_RELPATHS.map((r) => ({ destRel: r, srcRel: r })),
+    ...KIT_AGENT_ENTRYPOINTS.map((e) => ({ destRel: e.dest, srcRel: e.src })),
+    // 마커 없는 AGENTS.md 경로에서만 설치되는 계약 템플릿 사본. 부재가 정상이므로 present=false여도 문제 없다.
+    { destRel: KIT_AGENTS_CONTRACT_COPY_REL, srcRel: 'AGENTS.template.md' },
+  ]
+  const tool: ToolArtifact[] = toolEntries.map(({ destRel, srcRel }) => {
+    const dest = join(targetRoot, destRel)
+    const src = join(PACKAGE_ROOT, srcRel)
     if (!existsSync(dest))
-      return { path: rel, present: false, match: 'absent', tracked: false, introducedBy: null }
+      return { path: destRel, present: false, match: 'absent', tracked: false, introducedBy: null }
     const match: ToolArtifact['match'] =
       existsSync(src) && sha256(dest) === sha256(src) ? 'identical' : 'differs'
-    const tracked = isTracked(git, rel)
+    const tracked = isTracked(git, destRel)
     return {
-      path: rel,
+      path: destRel,
       present: true,
       match,
       tracked,
       // untracked면 이력의 add 커밋은 "지금 이 설치본"의 도입 커밋이 아니다 → 조회조차 하지 않는다(phase R2 P2).
-      introducedBy: tracked ? (introducingCommit(git, rel)?.sha ?? null) : null,
+      introducedBy: tracked ? (introducingCommit(git, destRel)?.sha ?? null) : null,
     }
   })
 
@@ -228,6 +255,21 @@ export function collectFacts(opts: UninstallOptions, run?: GitRunner): Uninstall
     })
   }
 
+  // CLAUDE.md는 AGENTS.md와 같은 계층이다 — init이 **부재 시에만** 만들고 `--force`로도 덮어쓰지 않는다.
+  // 사용자 파일일 수 있으므로 자동 제거 대상이 아니다(REQ-2026-010 D7).
+  const claudeAbs = join(targetRoot, KIT_CLAUDE_DEST_REL)
+  if (existsSync(claudeAbs)) {
+    const tpl = join(PACKAGE_ROOT, KIT_CLAUDE_TEMPLATE_REL)
+    const same = existsSync(tpl) && sha256(claudeAbs) === sha256(tpl)
+    ambiguous.push({
+      path: KIT_CLAUDE_DEST_REL,
+      present: true,
+      note: same
+        ? 'init 템플릿과 동일 — 그래도 자동 제거 대상이 아닙니다(에이전트 지침 파일)'
+        : '템플릿과 다름 — 사용자/팀이 작성했거나 편집했습니다',
+    })
+  }
+
   const cfgAbs = join(targetRoot, 'req.config.json')
   if (existsSync(cfgAbs)) {
     const parsed = readJsonObject(cfgAbs)
@@ -421,7 +463,7 @@ export function renderPlan(plan: UninstallPlan): string {
 
   L.push('## 5. 잔여물 경고')
   L.push('   - git은 빈 디렉터리를 추적하지 않습니다. 위 파일을 지운 뒤 `git status`가 clean이어도')
-  L.push(`     빈 디렉터리(scripts/ · ${facts.ticketRoot}/)가 파일시스템에 남을 수 있습니다.`)
+  L.push(`     빈 디렉터리(scripts/ · ${facts.ticketRoot}/ · .claude/ · .cursor/)가 파일시스템에 남을 수 있습니다.`)
   L.push('   - node_modules의 ajv · cross-spawn · tsx 는 다른 패키지도 쓸 수 있어 제거를 권하지 않습니다.')
   L.push('')
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "commitgate",
-  "version": "0.3.0",
-  "description": "CommitGate — Builder↔Reviewer(Claude↔Codex) fail-closed 커밋 게이트: 리뷰·승인·증거 없인 커밋을 통과시키지 않는 AI REQ 워크플로 kit (req:new/review-codex/doctor/commit)",
+  "version": "0.4.0",
+  "description": "CommitGate — Builder↔Reviewer(Claude↔Codex) fail-closed 커밋 게이트: 리뷰·승인·증거 없인 커밋을 통과시키지 않는 AI REQ 워크플로 kit (req:new/next/review-codex/doctor/commit)",
   "type": "module",
   "license": "MIT",
   "author": "sol5288",
@@ -32,6 +32,7 @@
     "req:new": "tsx scripts/req/req-new.ts",
     "req:review-codex": "tsx scripts/req/review-codex.ts",
     "req:doctor": "tsx scripts/req/req-doctor.ts",
+    "req:next": "tsx scripts/req/req-next.ts",
     "req:commit": "tsx scripts/req/req-commit.ts",
     "test": "vitest run",
     "typecheck": "tsc --noEmit",
@@ -41,7 +42,9 @@
     "scripts/req",
     "workflow/machine.schema.json",
     "workflow/req.config.schema.json",
+    "workflow/review-persona.md",
     "bin",
+    "templates",
     "AGENTS.template.md",
     "req.config.json.sample",
     "README.md",

package/req.config.json.sample

@@ -1,13 +1,14 @@
-{
-  "ticketRoot": "workflow",
-  "schemaPath": "workflow/machine.schema.json",
-  "handoffPath": null,
-  "branchPrefix": "feat/req-",
-  "packageManager": "npm",
-  "granularityMaxFiles": 8,
-  "designDocs": {
-    "requirement": "00-requirement.md",
-    "design": "01-design.md",
-    "plan": "02-plan.md"
-  }
-}
+{
+  "ticketRoot": "workflow",
+  "schemaPath": "workflow/machine.schema.json",
+  "handoffPath": null,
+  "reviewPersonaPath": "workflow/review-persona.md",
+  "branchPrefix": "feat/req-",
+  "packageManager": "npm",
+  "granularityMaxFiles": 8,
+  "designDocs": {
+    "requirement": "00-requirement.md",
+    "design": "01-design.md",
+    "plan": "02-plan.md"
+  }
+}

package/scripts/req/lib/config.ts

@@ -1,8 +1,8 @@
 /**
- * req 워크플로 config 모듈 (REQ-2026-017 Phase 1, portability kit).
+ * req 워크플로 config 모듈 (portability kit).
  *
- * 목적: 경로·이름·패키지매니저를 `req.config.json`으로 외부화하되, **파일 부재 시 현재 동작 100% 유지**(DEFAULTS=현재 하드코딩 값).
- * 본 Phase는 **모듈만** 제공 — 4 스크립트 배선·`--root` CLI는 Phase 2, 어댑터는 Phase 3.
+ * 목적: 경로·이름·패키지매니저를 `req.config.json`으로 외부화한다. 파일이 없으면 `DEFAULTS`로 해소된다.
+ *   ⚠️ `DEFAULTS`는 **모든 프로젝트에 유효한 중립 기본값**만 담는다(REQ-2026-009). 프로젝트 고유 값은 config가 흡수한다.
  *
  * 안전(fail-closed): config가 게이트를 무력화하거나 경로를 탈출하지 못하도록 AJV 스키마 + 해상도 confinement로 강제.
  */
@@ -26,6 +26,8 @@ export interface RawConfig {
   ticketRoot?: string
   schemaPath?: string
   handoffPath?: string | null
+  /** null = 의도적 비활성(persona 블록 생략). 미지정 = DEFAULTS(활성). */
+  reviewPersonaPath?: string | null
   branchPrefix?: string
   packageManager?: PackageManager
   granularityMaxFiles?: number
@@ -38,6 +40,7 @@ export interface ResolvedConfig {
   ticketRoot: string
   schemaPath: string
   handoffPath: string | null
+  reviewPersonaPath: string | null
   branchPrefix: string
   packageManager: PackageManager
   granularityMaxFiles: number
@@ -46,13 +49,40 @@ export interface ResolvedConfig {
   workflowDirAbs: string
   schemaPathAbs: string
   handoffPathAbs: string | null
+  reviewPersonaPathAbs: string | null
 }
 
-/** ⚠️ 현재 하드코딩 값 — 변경 시 behavior-preserving(수용기준 #1) 깨짐. */
+/**
+ * Codex 리뷰 프롬프트에 주입되는 **리뷰어 페르소나** 문서의 repo-상대 경로(코어 기본값).
+ *
+ * ⚠️ 이 상수는 두 축의 SSOT다(REQ-2026-010 D3-1).
+ *   - **설치 축**: `bin/init.ts`의 `KIT_COPY_RELPATHS`가 이 경로를 대상 repo에 복사한다.
+ *   - **설정 축**: `DEFAULTS.reviewPersonaPath`가 이 값으로 해소된다(phase-1b에서 도입).
+ *
+ * 둘이 갈라지면 신규 설치본은 프롬프트 조립 시 이 파일을 찾지 못하고 **모든 리뷰가 fail-closed로 멈춘다.**
+ * `tests/unit/init.test.ts`의 "설치 축 SSOT"가 그 드리프트를 회귀로 잡는다.
+ * `package.json`의 `files[]`는 또 **다른 축**(npm tarball 적재분)이므로 함께 갱신해야 한다.
+ */
+export const DEFAULT_REVIEW_PERSONA_RELPATH = 'workflow/review-persona.md'
+
+/**
+ * 코어 기본값. `req.config.json` 부재 시 이 값으로 해소된다.
+ *
+ * ⚠️ 여기 있는 값은 **모든 대상 프로젝트에 유효한 중립 기본값**이어야 한다.
+ *    특정 프로젝트에만 의미 있는 값(경로·문서 위치 등)은 코어가 아니라 `req.config.json`이 흡수한다.
+ *    `handoffPath`가 그 예다 — 코어 기본은 **비활성(null)**이고, 쓰려면 config에 명시하거나 `--handoff <path>`로 준다.
+ *    (REQ-2026-009: 이전 기본값은 특정 사설 프로젝트의 문서 경로였다.)
+ *
+ * `handoffPath`의 `as string | null`은 의도적이다. 없으면 TS가 리터럴 `null`로 좁혀
+ * `DEFAULTS`를 직접 import하는 소비자의 `string | null` 계약이 깨진다.
+ */
 export const DEFAULTS = {
   ticketRoot: 'workflow',
   schemaPath: 'workflow/machine.schema.json',
-  handoffPath: '../palm-kiosk/docs/evaluation/project-memory/ai-handoff.md',
+  handoffPath: null as string | null,
+  // ⚠️ handoffPath와 달리 코어 기본이 **활성**이다. init이 이 경로에 파일을 깔기 때문(KIT_COPY_RELPATHS).
+  //    비활성이 필요하면 config에 `null`을 명시한다. `as string | null`은 handoffPath와 같은 이유(직접 import 소비자 계약).
+  reviewPersonaPath: DEFAULT_REVIEW_PERSONA_RELPATH as string | null,
   branchPrefix: 'feat/req-',
   packageManager: 'pnpm' as PackageManager,
   granularityMaxFiles: 8,
@@ -69,6 +99,8 @@ export const CONFIG_SCHEMA = {
     ticketRoot: { type: 'string', minLength: 1 },
     schemaPath: { type: 'string', minLength: 1 },
     handoffPath: { type: ['string', 'null'] },
+    // null = 의도적 비활성. 문자열이면 minLength 1(빈 문자열은 "비활성"의 애매한 표현 → 거부, null을 쓰게 한다).
+    reviewPersonaPath: { type: ['string', 'null'], minLength: 1 },
     branchPrefix: { type: 'string', minLength: 1 }, // 빈 prefix는 D11 무력화 → 금지
     packageManager: { type: 'string', enum: ['pnpm', 'npm', 'yarn'] },
     granularityMaxFiles: { type: 'integer', minimum: 1 },
@@ -146,17 +178,25 @@ export function loadConfig(opts: { root?: string | null; cwd?: string } = {}): R
     ticketRoot: raw.ticketRoot ?? DEFAULTS.ticketRoot,
     schemaPath: raw.schemaPath ?? DEFAULTS.schemaPath,
     handoffPath: raw.handoffPath !== undefined ? raw.handoffPath : DEFAULTS.handoffPath, // null = 명시적 비활성
+    reviewPersonaPath:
+      raw.reviewPersonaPath !== undefined ? raw.reviewPersonaPath : DEFAULTS.reviewPersonaPath, // null = 명시적 비활성
     branchPrefix: raw.branchPrefix ?? DEFAULTS.branchPrefix,
     packageManager: raw.packageManager ?? DEFAULTS.packageManager,
     granularityMaxFiles: raw.granularityMaxFiles ?? DEFAULTS.granularityMaxFiles,
     designDocs: { ...DEFAULTS.designDocs, ...(raw.designDocs ?? {}) },
   }
 
-  // repo-내부 자원(ticketRoot·schemaPath)은 **상대경로 + root 하위**만(절대경로·탈출 금지 → portable). handoffPath는 읽기 전용 참조라 면제.
+  // repo-내부 자원(ticketRoot·schemaPath·reviewPersonaPath)은 **상대경로 + root 하위**만(절대경로·탈출 금지 → portable).
+  // handoffPath만 면제 — 형제 repo의 SSOT 문서를 읽는 **외부 참조**이기 때문.
+  // reviewPersonaPath는 패키지가 배포하고 init이 repo 안에 까는 자원이라 schemaPath와 같은 축이다(REQ-2026-010 D2).
   assertRelative(merged.ticketRoot, 'ticketRoot')
   assertRelative(merged.schemaPath, 'schemaPath')
   assertUnderRoot(rootAbs, merged.ticketRoot, 'ticketRoot')
   assertUnderRoot(rootAbs, merged.schemaPath, 'schemaPath')
+  if (merged.reviewPersonaPath !== null) {
+    assertRelative(merged.reviewPersonaPath, 'reviewPersonaPath')
+    assertUnderRoot(rootAbs, merged.reviewPersonaPath, 'reviewPersonaPath')
+  }
 
   return {
     root: rootAbs,
@@ -164,6 +204,7 @@ export function loadConfig(opts: { root?: string | null; cwd?: string } = {}): R
     workflowDirAbs: resolve(rootAbs, merged.ticketRoot),
     schemaPathAbs: resolve(rootAbs, merged.schemaPath),
     handoffPathAbs: merged.handoffPath ? resolve(rootAbs, merged.handoffPath) : null,
+    reviewPersonaPathAbs: merged.reviewPersonaPath ? resolve(rootAbs, merged.reviewPersonaPath) : null,
   }
 }
 

package/scripts/req/req-commit.ts

@@ -2,7 +2,7 @@
 /**
  * req:commit — AI REQ 워크플로우 Phase B (REQ-2026-016). 승인된 phase를 커밋하는 래퍼.
  *
- * SSOT 설계: ../palm-kiosk/docs/evaluation/ai-req-workflow-design.md / 본 티켓 01-design.md D-016-3·3b·7·8·9.
+ * 설계 근거: 본 티켓 01-design.md D-016-3·3b·7·8·9.
  * 책임(전체): req:doctor 통과 게이트 → HIGH 사람확인 게이트 → source 커밋(승인 코드만) →
  *   commit_allowed 소비 → evidence-finalize(approvals.jsonl 매니페스트 append + responses chore 커밋) → 2-커밋.
  *   복구/finalize 모드(pending_evidence_for)·design-finalize 포함.

package/scripts/req/req-doctor.ts

@@ -2,7 +2,6 @@
 /**
  * req:doctor — AI REQ 워크플로우 1차 (단계 4B): 일관성 점검(fail-closed).
  *
- * SSOT: palm-kiosk/docs/evaluation/ai-req-workflow-design.md §8.3.
  * 1차 최소셋(registry 비의존): D2·D3·D5·D6·D9·D10·D11 + D13(design 선행·freshness)·D15(NEEDS_FIX actionable). (D1/D7/D7b·D4a 등 registry/merge 의존은 2차)
  * FAIL 1건 이상 → exit 1, 자동 보정 금지(P9). review-codex 헬퍼 재사용.
  *

package/scripts/req/req-new.ts

@@ -2,7 +2,7 @@
 /**
  * req:new — AI REQ 워크플로우 1차 (단계 4A): REQ 티켓 + feat/req-* 브랜치 생성.
  *
- * SSOT: palm-kiosk/docs/evaluation/ai-req-workflow-design.md §9.1·§9.2·DEC-WF-020(D11).
+ * 설계 근거: DEC-WF-020(D11) — REQ는 main에서 feat/req-* 브랜치로 시작한다.
  *   - state.json은 **BOM 없이** 생성(Node, review-codex의 writeState 재사용).
  *   - 기본 dry-run(계획 출력), `--run` 시 실제 브랜치 생성·티켓 파일·스캐폴드 커밋.
  *   - REQ id 채번은 registry 미사용(1차) — workflow/REQ-* 디렉터리 스캔으로 max+1.