commitgate 0.7.0 → 0.8.1

package/bin/init.ts

@@ -95,6 +95,23 @@ export const KIT_CLAUDE_DEST_REL = 'CLAUDE.md'
  */
 export const KIT_GITIGNORE = { src: 'templates/workflow.gitignore', dest: 'workflow/.gitignore' } as const
 
+/**
+ * companion skills (REQ-2026-020). Builder용 방법론 instruction asset — 실행 코드가 아니다.
+ *
+ * ⚠️ `CONTRACT_POINTER_RELPATHS`에 **섞지 않는다**(설계 D6). 그 상수는 "계약 포인터"라는 의미를 갖고,
+ *    companion skills는 **없어도 핵심 워크플로가 동일하게 동작**한다(R10). 의미가 다르므로 별도 목록이다.
+ *    gitignore WARN/`--strict` 동작은 같은 축에서 받되, 기존 계약 포인터 경고를 약화시키지 않는다.
+ *
+ * ⚠️ `add()`를 타지 않는다(설계 D3). `add()`의 skip은 `existsSync && !force`라 **`--force`가 사용자 수정을 덮는다**.
+ *    스킬은 사용자가 고치라고 만든 자산이므로 `workflow/.gitignore`(D12)와 같은 seed-once 축으로 간다.
+ */
+export const KIT_COMPANION_SKILLS = [
+  { src: 'skills/commitgate-discovery/SKILL.md', dest: '.claude/skills/commitgate-discovery/SKILL.md' },
+  { src: 'skills/commitgate-tdd/SKILL.md', dest: '.claude/skills/commitgate-tdd/SKILL.md' },
+  { src: 'skills/commitgate-diagnosing-bugs/SKILL.md', dest: '.claude/skills/commitgate-diagnosing-bugs/SKILL.md' },
+  { src: 'skills/commitgate-research/SKILL.md', dest: '.claude/skills/commitgate-research/SKILL.md' },
+] as const
+
 /** `AGENTS.md`가 CommitGate 계약인지 판별하는 마커. 진입점 포인터들이 이 마커로 SSOT를 확인한다. */
 export const AGENTS_CONTRACT_MARKER = '<!-- commitgate:contract -->'
 
@@ -398,6 +415,86 @@ function assertConfinedDest(targetRoot: string, destRel: string): void {
   }
 }
 
+/**
+ * 쓰기 dest의 **confinement + leaf 상태를 한 번에** 판정한다 (REQ-2026-024 D1·D2).
+ *
+ * @returns 일반 파일이면 그 `Stats`, **실제 부재(ENOENT)면 `null`**. 그 밖은 전부 throw(fail-closed).
+ *
+ * 🔴 **`existsSync`를 부재 판정에 쓰면 안 된다.** 실측(REQ-2026-024 §2)으로 확인된 4가지 탈출:
+ *   - **A. dangling leaf**: `existsSync`가 **false** → "부재" 오판 → 쓰기가 링크를 따라 대상 **밖에 생성**.
+ *   - **B. ancestor dir symlink**: `existsSync`·`statSync`가 링크를 **따라가** 통과 → `mkdirSync`+쓰기가 밖에.
+ *   - **C. live leaf + `--force`**: skip 조건이 `existsSync && !force`라 force면 `copyFileSync`가 **외부를 덮어씀**.
+ *   - **D. live leaf + `writeFileSync`**: 기존 파일로 읽고 병합 → 쓰기가 링크 따라 **외부를 수정**.
+ * A만 막으면 C·D가 남는다 — 그쪽은 생성이 아니라 **기존 외부 파일 파괴**라 더 무겁다.
+ *
+ * 🔴 **반환값이 곧 부재 판정이다**(D2). 호출부가 `existsSync`를 쓸 이유를 없앤다 —
+ *    검사를 빼먹으려면 판정도 포기해야 하므로 **드리프트가 구조적으로 불가능**하다.
+ *    "쓰기 전에 검사를 호출한다"는 규율은 이미 실패했다: `workflow/.gitignore`·companion에는 붙고
+ *    나머지 7종에는 안 붙은 것이 이번 결함이다.
+ *
+ * ⚠️ 루트 직속 dest(`AGENTS.md`·`package.json` 등)에서 `assertConfinedDest`는 **무동작**이다
+ *    (`segs.length - 1 === 0`). 정상이다 — 그 상위는 `targetRoot` 자신이고 `runInit`이 이미 검사한다.
+ *    그 경우 leaf `lstat`이 방어를 맡는다.
+ *
+ * ⚠️ **TOCTOU는 막지 않는다.** 이 판정과 실제 쓰기 사이에 경로가 바뀌는 경쟁은 남는다
+ *    (Node에 `O_NOFOLLOW` 원자 API가 없다). **협조적 사용자의 우발적 symlink**를 막는 것이다.
+ */
+function statWritableDest(targetRoot: string, destRel: string): ReturnType<typeof lstatSync> | null {
+  assertConfinedDest(targetRoot, destRel) // 상위 컴포넌트 전부 lstat (leaf는 아래에서)
+  const abs = join(targetRoot, destRel)
+  let st: ReturnType<typeof lstatSync>
+  try {
+    st = lstatSync(abs)
+  } catch (e) {
+    // ⚠️ **ENOENT만** 부재로 인정한다 — EACCES·ELOOP를 부재로 삼키면 apply에서 늦게 실패해 부분 설치가 된다(롤백 0줄).
+    if ((e as NodeJS.ErrnoException).code !== 'ENOENT')
+      throw new Error(`${destRel} 상태 확인 실패(${(e as Error).message}) — fail-closed.`)
+    return null
+  }
+  if (!st.isFile())
+    throw new Error(`${destRel} 가 일반 파일이 아닙니다(symlink·디렉터리·특수파일) — 그 경로를 옮기고 재시도하십시오.`)
+  return st
+}
+
+/** companion skills 계획 결과(순수 판정 — 쓰기 없음). */
+export interface CompanionSkillsPlan {
+  /** 부재(lstat ENOENT)라 새로 만들 것. */
+  create: { srcAbs: string; destRel: string }[]
+  /** 이미 있고 **바이트 동일** = 직전 실행이 깐 것 → 설치 커밋 stage 목록에 편입. */
+  ownedSkips: string[]
+  /** 이미 있고 다름 = 사용자가 고친 것 → 보존(`--force`로도 안 덮음). */
+  userDiffers: string[]
+}
+
+/**
+ * companion skills seed-once 판정 + confinement preflight (설계 D3·D4).
+ * **순수 판정이라 아무것도 쓰지 않는다** — `--dry-run`도 이 검사를 그대로 받는다(쓰기 0건, 그러나 symlink면 실패).
+ *
+ * `workflow/.gitignore`(D12)와 같은 축이고, 다른 점은 **dest가 4개**라는 것뿐이다:
+ *
+ * 🔴 **각 최종 `SKILL.md` dest를 개별로 넘긴다.** skills 루트(`.claude/skills`)만 넘기면
+ *    `assertConfinedDest`의 `i < segs.length - 1` 루프가 **마지막 컴포넌트를 검사하지 않아**
+ *    `commitgate-<name>`이 외부 symlink여도 통과하고, `copyFileSync`가 대상 **밖에** 쓴다.
+ *
+ * confinement + leaf 판정은 `statWritableDest`가 한다 — 이 함수의 본문이 그 헬퍼의 출처다
+ * (REQ-2026-024 D1: 같은 규칙이 두 벌 있었고, 나머지 7종에 안 붙은 것이 결함이었다).
+ */
+export function planCompanionSkills(targetRoot: string): CompanionSkillsPlan {
+  const create: { srcAbs: string; destRel: string }[] = []
+  const ownedSkips: string[] = []
+  const userDiffers: string[] = []
+  for (const { src, dest } of KIT_COMPANION_SKILLS) {
+    // 상위 전부(.claude → .claude/skills → .claude/skills/commitgate-<name>) + leaf를 lstat으로 검사.
+    const st = statWritableDest(targetRoot, dest)
+    const destAbs = join(targetRoot, dest)
+    const srcAbs = join(PACKAGE_ROOT, src)
+    if (st === null) create.push({ srcAbs, destRel: dest })
+    else if (sha256File(destAbs) === sha256File(srcAbs)) ownedSkips.push(dest)
+    else userDiffers.push(dest) // 사용자가 고친 것 — `--force`도 보지 않는다(D3).
+  }
+  return { create, ownedSkips, userDiffers }
+}
+
 /**
  * `<pm> install`이 만드는 `node_modules/`가 **워킹트리를 dirty하게 만드는가**.
  * ignore되지도 tracked되지도 않으면 `?? node_modules/`로 나타나 `req:new --run`의 clean-tree 게이트를 막는다.
@@ -572,6 +669,11 @@ export interface PlanFacts {
   workflowGitignoreWillCreate: boolean
   /** 기존 `workflow/.gitignore`가 템플릿과 바이트 동일(= 직전 실행이 깐 것). ownedSkips에 직접 편입(D4 축). */
   workflowGitignoreOwnedSkip: boolean
+  /**
+   * companion skills 계획(REQ-2026-020). `add()`를 타지 않으므로(D3 seed-once) 여기로 받아
+   * copies/ownedSkips에 **직접** 편입한다 — 그러지 않으면 stageList에서 빠져 unrelated로 오분류된다.
+   */
+  companionSkills: CompanionSkillsPlan
 }
 
 /**
@@ -614,7 +716,11 @@ export function planInstall(targetRoot: string, force: boolean, pm: PackageManag
   }
   const add = (srcAbs: string, destRel: string): void => {
     const destAbs = join(targetRoot, destRel)
-    if (existsSync(destAbs) && !force) {
+    // 🔴 confinement + leaf 판정(REQ-2026-024 D2). **반환값이 곧 부재 판정이다** — `existsSync`를 쓰면
+    //    dangling leaf(A)를 부재로 오판하고, ancestor dir symlink(B)를 통과시키며, `--force`가 링크를 따라
+    //    대상 **밖** 사용자 파일을 덮어쓴다(C, 실측 E8). 검사와 판정이 같은 호출이라 빼먹을 수 없다.
+    const st = statWritableDest(targetRoot, destRel)
+    if (st !== null && !force) {
       skips.push(destRel)
       // 바이트가 같으면 CommitGate 소유(직전 실행이 깐 것). 다르면 사용자 파일 — 설치 커밋에 담지 않는다.
       const a = sha(destAbs)
@@ -634,6 +740,11 @@ export function planInstall(targetRoot: string, force: boolean, pm: PackageManag
   // workflow/.gitignore는 add()를 타지 않는다(D12: --force가 사용자 파일을 덮으면 안 됨). 바이트 동일 재실행분은
   // 여기서 ownedSkips에 **직접** 편입 — 그러지 않으면 stageList에서 빠져 unrelated로 오분류된다(phase-2 리뷰 R1).
   if (facts.workflowGitignoreOwnedSkip) ownedSkips.push(KIT_GITIGNORE.dest)
+  // companion skills도 add()를 타지 않는다(D3). 생성분은 copies로, 바이트 동일분은 ownedSkips로 직접 편입 —
+  // 그래야 artifacts·stageList·ignore 검사가 이들을 함께 본다. userDiffers는 사용자 파일이라 설치 커밋에 담지 않는다.
+  for (const c of facts.companionSkills.create) copies.push(c)
+  for (const d of facts.companionSkills.ownedSkips) ownedSkips.push(d)
+  for (const d of facts.companionSkills.userDiffers) skips.push(d)
 
   return {
     copies,
@@ -653,10 +764,20 @@ export function planInstall(targetRoot: string, force: boolean, pm: PackageManag
 }
 
 /**
- * 진입점 dest 경로들이 **실제로 만들어질 수 있는지** preflight에서 확인한다 (D8).
+ * 진입점 dest의 **ENOTDIR 조기 진단**(D8) — 더 나은 에러 메시지가 목적이다.
  *
  * `mkdirSync(recursive)`는 경로 중간 컴포넌트가 **파일**이면 ENOTDIR로 죽는다. apply 단계에서 그러면
- * 앞의 파일들은 이미 복사된 뒤라 **부분 설치**가 된다. 쓰기 전에 걸러서 preflight→apply 계약을 지킨다.
+ * 앞의 파일들은 이미 복사된 뒤라 **부분 설치**가 된다. 쓰기 전에 걸러서 preflight→apply 계약을 지키고,
+ * `--no-agent-entrypoints`라는 출구를 안내한다.
+ *
+ * 🔴 **이 함수는 confinement 방어가 아니다**(REQ-2026-024 D4). `existsSync`·`statSync`는 **링크를 따라간다** —
+ *    상위가 외부를 가리키는 symlink여도 `isDirectory()`가 true라 그대로 통과한다(실측: v0.7.0에서 `.cursor`
+ *    junction이 여기를 통과해 대상 밖에 파일을 만들었다).
+ *    **방어는 `statWritableDest`가 한다** — 이 함수 뒤의 `add()`·개별 dest 판정이 그것을 호출한다.
+ *    여기를 lstat 기반으로 바꾸지 **않는다**: 같은 규칙이 두 벌이 되고, 그 이중화가 이번 결함의 발생 방식이다.
+ *
+ * ⚠️ 순서 의존: symlink dest에 대해 이 함수가 먼저 **다른 메시지**로 throw할 수 있다(예: 상위가 파일 symlink면
+ *    "디렉터리가 아니라 파일입니다"). 보안상 무해하다 — 둘 다 쓰기 전 throw이고 메시지도 틀리지 않았다.
  */
 function assertEntrypointPathsUsable(targetRoot: string): void {
   const dests = [...KIT_AGENT_ENTRYPOINTS.map((e) => e.dest), KIT_CLAUDE_DEST_REL, KIT_AGENTS_CONTRACT_COPY_REL]
@@ -677,8 +798,23 @@ function assertEntrypointPathsUsable(targetRoot: string): void {
   }
 }
 
-/** 계획대로 복사(중첩 디렉터리 생성). `--dry-run`이면 아무것도 쓰지 않는다. */
-function applyCopies(targetRoot: string, plan: InstallPlan): void {
+/**
+ * 계획대로 복사(중첩 디렉터리 생성). 호출부가 `--dry-run`이면 이 함수를 아예 부르지 않는다.
+ *
+ * 🔴 **쓰기 전 전량 검증**(REQ-2026-024 D3). `plan.copies`는 `add()`만 채우지 않는다 —
+ *    `planCompanionSkills`의 결과가 **직접 편입**된다(REQ-2026-020 D3). 즉 `add()`의 preflight를
+ *    **우회하는 경로가 이미 존재한다.** 여기서 불변식을 강제해 미래의 우회도 잡는다.
+ *
+ * 🔴 **두 루프여야 한다.** 검사·쓰기를 한 루프에 섞으면 중간 throw 시 앞의 파일이 이미 복사돼
+ *    **부분 설치**가 된다(롤백 0줄) — preflight→apply 계약 위반이다.
+ *
+ * ⚠️ 이 검사는 **불변식 강제**지 주 방어선이 아니다. 주 방어선은 preflight(`add()`·`planCompanionSkills`)다.
+ *    preflight가 완전하면 여기는 **절대 발화하지 않는다** — 그래서 `runInit` 경유로는 검증할 수 없고
+ *    (preflight가 먼저 터진다) 이 함수를 **직접 호출**하는 테스트만이 공허하지 않다. export 이유가 그것이다.
+ *    TOCTOU도 막지 못한다 — 검사와 `copyFileSync` 사이에도 창이 있다.
+ */
+export function applyCopies(targetRoot: string, plan: InstallPlan): void {
+  for (const { destRel } of plan.copies) statWritableDest(targetRoot, destRel)
   for (const { srcAbs, destRel } of plan.copies) {
     const destAbs = join(targetRoot, destRel)
     mkdirSync(dirname(destAbs), { recursive: true })
@@ -815,7 +951,10 @@ export function runInit(opts: InitOptions): InitResult {
   assertGitWorkTree(targetRoot) // 실제 git probe(fake .git 마커 거부)
 
   const pkgPath = join(targetRoot, 'package.json')
-  if (!existsSync(pkgPath))
+  // 🔴 confinement를 **읽기보다 앞**에 둔다(REQ-2026-024 D5). symlink면 `writeFileSync`가 링크를 따라
+  //    대상 **밖** package.json을 수정한다(실측 E6). 검사를 읽기 뒤에 두면 외부 파일을 읽고 나서 막는 셈이다.
+  //    부재(null)는 기존 메시지 그대로 — 동작 변경은 symlink/특수파일 케이스에 한정된다.
+  if (statWritableDest(targetRoot, 'package.json') === null)
     throw new Error(`package.json 없음: ${targetRoot} — 'npm init' 등으로 먼저 생성(req:* 스크립트 주입 대상).`)
   const pkg = parseJsonObject(pkgPath, 'package.json') as {
     scripts?: Record<string, string>
@@ -860,7 +999,9 @@ export function runInit(opts: InitOptions): InitResult {
   }
 
   const cfgPath = join(targetRoot, 'req.config.json')
-  const existingCfg = existsSync(cfgPath) ? parseJsonObject(cfgPath, 'req.config.json') : null
+  // 🔴 confinement를 **읽기보다 앞**에(D5). dangling이면 `writeFileSync`가 대상 밖에 **생성**하고(E4),
+  //    live symlink면 외부 파일을 읽어 병합한 뒤 링크를 따라 **수정**한다(E5). 아래 loadConfig도 이 파일을 읽는다.
+  const existingCfg = statWritableDest(targetRoot, 'req.config.json') !== null ? parseJsonObject(cfgPath, 'req.config.json') : null
   // 기존 config는 워크플로 CONFIG_SCHEMA(additionalProperties·enum·type) + 경로 confinement까지 preflight 검증(phase R2 P2).
   // kit의 loadConfig를 재사용 — schema-invalid(unknown key·bad enum·escaping ticketRoot 등)면 복사 전 throw(첫 req:* 지연 실패 방지).
   // 병합은 유효 키만 추가(handoffPath:null·packageManager)라 "기존 유효 ⇒ 병합 유효".
@@ -909,7 +1050,9 @@ export function runInit(opts: InitOptions): InitResult {
   //    `REQ_DEV_DEPS` 상수는 남는다 — `bin/uninstall.ts`가 기존 Stage A 설치본의 devDeps를 분류하는 데 쓴다.
 
   const agentsPath = join(targetRoot, 'AGENTS.md')
-  const agentsCreated = !existsSync(agentsPath)
+  // 🔴 반환값이 곧 부재 판정이다(D2). `!existsSync`면 dangling을 부재로 오판해 `copyFileSync`가
+  //    링크를 따라 대상 밖에 AGENTS.md를 만든다(실측 E1). 아래 마커 읽기(readFileSync)도 이 검사 뒤에 온다.
+  const agentsCreated = statWritableDest(targetRoot, 'AGENTS.md') === null
 
   const agentEntrypointsSkipped = opts.noAgentEntrypoints === true
   if (!agentEntrypointsSkipped) assertEntrypointPathsUsable(targetRoot)
@@ -920,33 +1063,25 @@ export function runInit(opts: InitOptions): InitResult {
     !agentEntrypointsSkipped && !agentsCreated && !readFileSync(agentsPath, 'utf8').includes(AGENTS_CONTRACT_MARKER)
 
   const claudeMdPath = join(targetRoot, KIT_CLAUDE_DEST_REL)
-  const claudeMdCreated = !agentEntrypointsSkipped && !existsSync(claudeMdPath)
+  // `--no-agent-entrypoints`면 이 dest를 쓰지 않으므로 검사도 돌리지 않는다(D5/D7 의미 유지 — 단락 평가).
+  const claudeMdCreated = !agentEntrypointsSkipped && statWritableDest(targetRoot, KIT_CLAUDE_DEST_REL) === null
 
   // 마커가 없으면 포인터가 참조할 계약 템플릿을 **대상 repo에** 놓는다 — 그러지 않으면 복구 지시가 막다른 길이다.
   const contractCopyPath = join(targetRoot, KIT_AGENTS_CONTRACT_COPY_REL)
-  const agentsContractCopyCreated = agentsMarkerMissing && (!existsSync(contractCopyPath) || opts.force)
+  // `agentsMarkerMissing`가 거짓이면 이 dest를 쓰지 않으므로 검사도 돌리지 않는다(단락 평가).
+  // ⚠️ `|| opts.force`가 남아 있다 — force면 **존재해도 덮어쓴다**. 그래서 symlink 거부가 특히 중요하다:
+  //    검사가 없으면 force가 링크를 따라 대상 밖 파일을 덮어쓴다(모드 C, `add()`의 E8과 같은 축).
+  const agentsContractCopyCreated =
+    agentsMarkerMissing && (statWritableDest(targetRoot, KIT_AGENTS_CONTRACT_COPY_REL) === null || opts.force)
 
   // workflow/.gitignore(kit 파일, REQ-2026-012). AGENTS.md 정책: **부재 시에만** 생성, --force로도 안 덮음(D12).
   // --no-agent-entrypoints와 무관(D13).
   const workflowGitignorePath = join(targetRoot, KIT_GITIGNORE.dest)
   const workflowGitignoreSrcAbs = join(PACKAGE_ROOT, KIT_GITIGNORE.src)
-  // confinement: workflow/(또는 그 상위)가 symlink면 copyFileSync가 밖에 쓰거나 git이 경로를 stage하지 못한다.
-  // 상위 컴포넌트를 lstat으로 검사해 내부·외부·dangling 링크를 모두 거부한다(P1).
-  // preflight라 스키마 복사(같은 workflow/ 경유)보다 먼저 돌아 함께 보호된다.
-  assertConfinedDest(targetRoot, KIT_GITIGNORE.dest)
-  // fail-closed: 존재하면 반드시 **일반 파일**이어야 한다(P1). lstat로 symlink를 안 따라간다 —
-  //   symlink면 copyFileSync가 링크 대상을 따라 쓰고 git도 링크된 .gitignore를 규칙으로 안 읽는다. 디렉터리·특수파일도 복사 불가.
-  //   ⚠️ **ENOENT만** 부재로 인정한다 — EACCES·ELOOP 등을 부재로 삼키면 apply로 넘어가 늦게 실패한다.
-  let wgLstat: ReturnType<typeof lstatSync> | null = null
-  try {
-    wgLstat = lstatSync(workflowGitignorePath)
-  } catch (e) {
-    if ((e as NodeJS.ErrnoException).code !== 'ENOENT')
-      throw new Error(`${KIT_GITIGNORE.dest} 상태 확인 실패(${(e as Error).message}) — fail-closed.`)
-    wgLstat = null
-  }
-  if (wgLstat !== null && !wgLstat.isFile())
-    throw new Error(`${KIT_GITIGNORE.dest} 가 일반 파일이 아닙니다(symlink·디렉터리·특수파일) — 그 경로를 옮기고 재시도하십시오.`)
+  // confinement + leaf: workflow/(또는 그 상위)가 symlink면 copyFileSync가 밖에 쓰거나 git이 경로를 stage하지 못하고,
+  //   leaf가 symlink면 링크 대상을 따라 쓰며 git도 링크된 .gitignore를 규칙으로 안 읽는다. 디렉터리·특수파일도 복사 불가.
+  //   preflight라 스키마 복사(같은 workflow/ 경유)보다 먼저 돌아 함께 보호된다.
+  const wgLstat = statWritableDest(targetRoot, KIT_GITIGNORE.dest)
   const workflowGitignoreExists = wgLstat !== null // isFile 보장
   const workflowGitignoreCreated = !workflowGitignoreExists
   // 존재 & 바이트 동일 = 직전 실행이 깐 것(소유). ⚠️ add()를 타지 않으므로(D12) ownedSkips를 **직접** 채운다 —
@@ -963,6 +1098,13 @@ export function runInit(opts: InitOptions): InitResult {
     gitIsIgnored(targetRoot, KIT_GITIGNORE.dest) &&
     !gitIsTracked(targetRoot, KIT_GITIGNORE.dest)
 
+  // companion skills(REQ-2026-020 D3·D4). **preflight**라 `--dry-run`도 이 검사를 받는다 —
+  // dry-run이 조용히 통과하면 실설치 직전에야 터진다. 판정은 순수(쓰기 0건)다.
+  // `.claude/` 계층이므로 `--no-agent-entrypoints`면 통째로 건너뛴다(D5/D7 의미 유지).
+  const companionSkills: CompanionSkillsPlan = agentEntrypointsSkipped
+    ? { create: [], ownedSkips: [], userDiffers: [] }
+    : planCompanionSkills(targetRoot)
+
   // 설치 **전** 워킹트리(쓰기 전 스냅샷). `.gitignore`의 dirty 여부 판정에도 쓰이므로 계획보다 먼저 찍는다.
   const porcelain = gitStatusEntries(targetRoot)
   const nmWillDirty = nodeModulesWillDirty(targetRoot)
@@ -978,6 +1120,7 @@ export function runInit(opts: InitOptions): InitResult {
     gitignoreWillJoin: gitignoreJoinsInstall(nmWillDirty, porcelain),
     workflowGitignoreWillCreate: workflowGitignoreCreated,
     workflowGitignoreOwnedSkip,
+    companionSkills,
   })
   const artifacts = planArtifactPaths(plan)
 
@@ -1018,6 +1161,32 @@ export function runInit(opts: InitOptions): InitResult {
     if (opts.strict) throw new Error(`[--strict] ${msg}`)
     console.warn(`⚠️  ${msg}\n    (설치는 계속 — 안전한 커밋 안내는 생략됩니다)`)
   }
+  // companion skills가 ignored∧untracked면 설치 커밋에 못 담겨 팀원 fresh clone에 전달되지 않는다(REQ-2026-021 D1).
+  //
+  // 🔴 **`artifacts`로 판정하면 안 된다.** `userDiffers`는 `skips`로 가서 `planArtifactPaths`
+  //    (= `copies + ownedSkips + extras`)에 **없다** → `findIgnoredArtifacts`가 그 파일을 보지 못한다.
+  //    그러면 나머지가 전부 추적된 상태에서 사용자가 skill 하나만 고쳤을 때 **경고 없이 `--strict`가 통과**한다.
+  //    계획 3분류(create·ownedSkips·userDiffers)를 **전부** 본다 — 소유든 사용자 파일이든, 팀에 전달되지
+  //    못하면 안전한 설치 안내를 낼 수 없다. `workflowGitignorePolicyAtRisk`와 같은 축이다(D1).
+  //
+  // ⚠️ `CONTRACT_POINTER_RELPATHS`에 섞지 않는다(REQ-2026-020 D6) — companion은 계약 포인터가 아니다.
+  //    같은 WARN/strict **동작**만 별도 판정으로 준다. 기존 포인터 경고는 손대지 않는다(추가만).
+  const companionAtRisk = [
+    ...companionSkills.create.map((c) => c.destRel),
+    ...companionSkills.ownedSkips,
+    ...companionSkills.userDiffers,
+  ].filter((p) => gitIsIgnored(targetRoot, p) && !gitIsTracked(targetRoot, p))
+
+  if (companionAtRisk.length > 0) {
+    const msg =
+      `companion skills가 무시되고 있어 설치 커밋에 담을 수 없습니다:\n` +
+      companionAtRisk.map((p) => `      ${p}`).join('\n') +
+      `\n    팀원의 fresh clone·CI에는 이 스킬들이 없습니다(그쪽 Builder는 방법론 보조를 못 받습니다).\n` +
+      `    추적하려면: git add -f <위 경로>   또는 .gitignore 에서 해당 규칙을 걷어내십시오.`
+    if (opts.strict) throw new Error(`[--strict] ${msg}`)
+    console.warn(`⚠️  ${msg}\n    (설치는 계속 — 강제 중단하려면 --strict)`)
+  }
+
   // staged·overlapping이 있으면 **안전한 커밋 안내를 만들 수 없다**(커밋이 인덱스 전체를 담고, 겹침은 사후 분리 불가).
   // 기본 모드는 설치를 막지 않는다(비파괴·비-breaking) — 안내를 내지 않을 뿐. `--strict`는 쓰기 전에 중단한다.
   if (opts.strict && (preexistingDirty.staged.length > 0 || preexistingDirty.overlapping.length > 0)) {
@@ -1267,7 +1436,9 @@ function printHelp(): void {
 
 옵션:
   --dir <path>   대상 repo 루트(기본: 현재 디렉터리)
-  --force        기존 kit 파일 덮어쓰기(기본: 스킵)
+  --force        덮어쓰기 가능한 kit 항목만 갱신(기본: 스킵).
+                 AGENTS.md · CLAUDE.md · workflow/.gitignore · companion skills(.claude/skills/commitgate-*)는
+                 기존 파일을 **보존**합니다 — --force 로도 덮어쓰지 않습니다.
   --dry-run      변경 없이 수행 예정 목록만 출력
   --strict       정합성 경고를 설치 실패로 취급(fail-closed)
   --no-agent-entrypoints

package/bin/uninstall.ts

@@ -30,6 +30,7 @@ import {
   KIT_COPY_RELPATHS,
   KIT_AGENT_ENTRYPOINTS,
   KIT_GITIGNORE,
+  KIT_COMPANION_SKILLS,
   KIT_CLAUDE_TEMPLATE_REL,
   KIT_CLAUDE_DEST_REL,
   KIT_AGENTS_CONTRACT_COPY_REL,
@@ -230,6 +231,10 @@ export function collectFacts(opts: UninstallOptions, run?: GitRunner): Uninstall
     { destRel: KIT_AGENTS_CONTRACT_COPY_REL, srcRel: 'AGENTS.template.md' },
     // workflow/.gitignore(REQ-2026-012): src≠dest. identical이면 제거 대상, differs면 review(사용자 편집 보존). 부재 정상.
     { destRel: KIT_GITIGNORE.dest, srcRel: KIT_GITIGNORE.src },
+    // companion skills(REQ-2026-021 D5): src≠dest. `KIT_COMPANION_SKILLS`가 이미 `{src, dest}` shape라 직접 매핑한다.
+    // `--no-agent-entrypoints`·미설치면 부재가 **정상**이므로 present=false여도 문제 없다(entrypoint와 같은 성질).
+    // ⚠️ 분류는 기존 규칙을 그대로 탄다 — 새 예외를 만들지 않는다. `differs`는 "편집됐거나 **다른 버전**이 설치함"이다.
+    ...KIT_COMPANION_SKILLS.map((e) => ({ destRel: e.dest, srcRel: e.src })),
   ]
   const tool: ToolArtifact[] = toolEntries.map(({ destRel, srcRel }) => {
     const dest = join(targetRoot, destRel)

package/package.json

@@ -1,72 +1,73 @@
-{
-  "name": "commitgate",
-  "version": "0.7.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",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/sol5288/commitgate.git"
-  },
-  "homepage": "https://github.com/sol5288/commitgate#readme",
-  "bugs": {
-    "url": "https://github.com/sol5288/commitgate/issues"
-  },
-  "keywords": [
-    "ai",
-    "code-review",
-    "workflow",
-    "codex",
-    "claude",
-    "git",
-    "commit-gate",
-    "fail-closed",
-    "review-gate",
-    "cli"
-  ],
-  "bin": {
-    "commitgate": "bin/commitgate.mjs"
-  },
-  "scripts": {
-    "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",
-    "smoke": "node scripts/smoke.mjs",
-    "verify:overrides": "node scripts/verify-review-overrides.mjs"
-  },
-  "files": [
-    "scripts/req",
-    "scripts/verify-review-overrides.mjs",
-    "workflow/machine.schema.json",
-    "workflow/req.config.schema.json",
-    "workflow/review-persona.md",
-    "bin",
-    "templates",
-    "AGENTS.template.md",
-    "req.config.json.sample",
-    "README.md",
-    "README.en.md",
-    "CHANGELOG.md"
-  ],
-  "engines": {
-    "node": ">=18.17"
-  },
-  "dependencies": {
-    "ajv": "^8.20.0",
-    "cross-spawn": "^7.0.6",
-    "semver": "^7.6.3",
-    "tsx": "^4.19.1"
-  },
-  "devDependencies": {
-    "@types/cross-spawn": "^6.0.6",
-    "@types/node": "^22.7.4",
-    "@types/semver": "^7.5.8",
-    "typescript": "^5.6.2",
-    "vitest": "^2.1.2"
-  }
-}
+{
+  "name": "commitgate",
+  "version": "0.8.1",
+  "description": "CommitGate — Builder↔Reviewer(Claude↔Codex) fail-closed 커밋 게이트: 리뷰·승인·증거 없인 커밋을 통과시키지 않는 AI REQ 워크플로 kit (req:new/next/review-codex/doctor/commit)",
+  "type": "module",
+  "license": "MIT",
+  "author": "sol5288",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sol5288/commitgate.git"
+  },
+  "homepage": "https://github.com/sol5288/commitgate#readme",
+  "bugs": {
+    "url": "https://github.com/sol5288/commitgate/issues"
+  },
+  "keywords": [
+    "ai",
+    "code-review",
+    "workflow",
+    "codex",
+    "claude",
+    "git",
+    "commit-gate",
+    "fail-closed",
+    "review-gate",
+    "cli"
+  ],
+  "bin": {
+    "commitgate": "bin/commitgate.mjs"
+  },
+  "scripts": {
+    "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",
+    "smoke": "node scripts/smoke.mjs",
+    "verify:overrides": "node scripts/verify-review-overrides.mjs"
+  },
+  "files": [
+    "scripts/req",
+    "scripts/verify-review-overrides.mjs",
+    "workflow/machine.schema.json",
+    "workflow/req.config.schema.json",
+    "workflow/review-persona.md",
+    "bin",
+    "templates",
+    "skills",
+    "AGENTS.template.md",
+    "req.config.json.sample",
+    "README.md",
+    "README.en.md",
+    "CHANGELOG.md"
+  ],
+  "engines": {
+    "node": ">=18.17"
+  },
+  "dependencies": {
+    "ajv": "^8.20.0",
+    "cross-spawn": "^7.0.6",
+    "semver": "^7.6.3",
+    "tsx": "^4.19.1"
+  },
+  "devDependencies": {
+    "@types/cross-spawn": "^6.0.6",
+    "@types/node": "^22.7.4",
+    "@types/semver": "^7.5.8",
+    "typescript": "^5.6.2",
+    "vitest": "^2.1.2"
+  }
+}

package/req.config.json.sample

@@ -8,6 +8,7 @@
   "granularityMaxFiles": 8,
   "reviewModel": "gpt-5.6-terra",
   "reviewReasoningEffort": "high",
+  "reviewBudget": { "autoBudget": 5, "hardCap": 8 },
   "designDocs": {
     "requirement": "00-requirement.md",
     "design": "01-design.md",

package/scripts/req/lib/config.ts

@@ -27,6 +27,12 @@ export interface DesignDocs {
  */
 export type ReviewReasoningEffort = 'none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh'
 
+/** review 예산(REQ-2026-028 A-2a). config↔review-codex 순환 방지를 위해 여기(config)에 정의. */
+export interface ReviewBudget {
+  autoBudget: number
+  hardCap: number
+}
+
 /** 사용자가 `req.config.json`에 줄 수 있는 부분 config(전부 선택). */
 export interface RawConfig {
   ticketRoot?: string
@@ -42,6 +48,8 @@ export interface RawConfig {
   reviewModel?: string | null
   /** codex 리뷰 추론강도(REQ-2026-013 P1). null = `-c model_reasoning_effort=` 생략. 미지정 = DEFAULTS. */
   reviewReasoningEffort?: ReviewReasoningEffort | null
+  /** REQ-2026-028 A-2a: review 예산. 미지정 = DEFAULTS(5/8). hardCap≤8·autoBudget≤hardCap은 loadConfig 검증. */
+  reviewBudget?: ReviewBudget
 }
 
 /** 해소된 config(DEFAULTS 병합 + 파생 절대경로). */
@@ -57,6 +65,7 @@ export interface ResolvedConfig {
   designDocs: DesignDocs
   reviewModel: string | null
   reviewReasoningEffort: ReviewReasoningEffort | null
+  reviewBudget: ReviewBudget
   // 파생(절대경로)
   workflowDirAbs: string
   schemaPathAbs: string
@@ -104,6 +113,8 @@ export const DEFAULTS = {
   // `as ... | null`은 handoffPath와 같은 이유(직접 import 소비자의 `| null` 계약 보존).
   reviewModel: 'gpt-5.6-terra' as string | null,
   reviewReasoningEffort: 'high' as ReviewReasoningEffort | null,
+  // REQ-2026-028 A-2a: review 예산. autoBudget=자동 허용 회차, hardCap=절대 상한(9번째 차단 → 8).
+  reviewBudget: { autoBudget: 5, hardCap: 8 } as ReviewBudget,
 }
 
 const BASENAME_RE = '^[A-Za-z0-9][A-Za-z0-9._-]*$' // basename만(슬래시·백슬래시·선행 `.`(→`..`) 금지)
@@ -125,6 +136,16 @@ export const CONFIG_SCHEMA = {
     reviewModel: { type: ['string', 'null'], pattern: BASENAME_RE },
     // effort는 실측 확정 enum(R15) + null. null을 enum에 포함해야 `{effort:null}`이 통과(JSON Schema enum은 타입 무관 전체 적용).
     reviewReasoningEffort: { type: ['string', 'null'], enum: ['none', 'minimal', 'low', 'medium', 'high', 'xhigh', null] },
+    // REQ-2026-028 A-2a: 예산. 스키마는 타입·상한(hardCap≤8·최소 1)까지. 교차검증(autoBudget≤hardCap)은 loadConfig.
+    reviewBudget: {
+      type: 'object',
+      additionalProperties: false,
+      required: ['autoBudget', 'hardCap'],
+      properties: {
+        autoBudget: { type: 'integer', minimum: 1 },
+        hardCap: { type: 'integer', minimum: 1, maximum: 8 },
+      },
+    },
     designDocs: {
       type: 'object',
       additionalProperties: false,
@@ -209,8 +230,17 @@ export function loadConfig(opts: { root?: string | null; cwd?: string } = {}): R
     reviewModel: raw.reviewModel !== undefined ? raw.reviewModel : DEFAULTS.reviewModel,
     reviewReasoningEffort:
       raw.reviewReasoningEffort !== undefined ? raw.reviewReasoningEffort : DEFAULTS.reviewReasoningEffort,
+    reviewBudget: raw.reviewBudget ?? DEFAULTS.reviewBudget,
   }
 
+  // REQ-2026-028 R7: 교차검증(스키마가 표현 못 함). AJV가 이미 hardCap∈[1,8]·autoBudget≥1을 잡았고,
+  // 여기서 autoBudget ≤ hardCap을 강제(fail-closed). R4("9번째는 어떤 경로로도 차단")는 설정을 넘는 코드
+  // 상수 경계다 — hardCap>8은 스키마가 거부하므로 config 한 줄로 뚫을 수 없다.
+  if (merged.reviewBudget.autoBudget > merged.reviewBudget.hardCap)
+    throw new Error(
+      `req.config: reviewBudget.autoBudget(${merged.reviewBudget.autoBudget}) > hardCap(${merged.reviewBudget.hardCap}) — autoBudget는 hardCap 이하여야 한다`,
+    )
+
   // repo-내부 자원(ticketRoot·schemaPath·reviewPersonaPath)은 **상대경로 + root 하위**만(절대경로·탈출 금지 → portable).
   // handoffPath만 면제 — 형제 repo의 SSOT 문서를 읽는 **외부 참조**이기 때문.
   // reviewPersonaPath는 패키지가 배포하고 init이 repo 안에 까는 자원이라 schemaPath와 같은 축이다(REQ-2026-010 D2).

package/scripts/req/req-commit.ts

@@ -20,6 +20,7 @@ import {
   readPhases,
   archiveBaseName,
   isArchiveFileName,
+  isValidIsoInstant,
   type ApprovalEvidence,
   type ReviewKind,
   type WorkflowState,
@@ -34,7 +35,7 @@ let pkgManager: PackageManager = DEFAULTS.packageManager
 let gitAdapter: GitAdapter = createGitAdapter(packageRoot())
 const SHA256_RE = /^[0-9a-f]{64}$/i
 const GIT_OID_RE = /^[0-9a-f]{40}(?:[0-9a-f]{24})?$/i // git OID: 40(SHA-1) 또는 64(SHA-256)
-const ISO_RE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,9})?Z$/ // new Date().toISOString() 형식
+// ISO 검증은 review-codex의 isValidIsoInstant(형식+달력 유효성) 재사용 — 달력 불가능 값 거부(REQ-2026-030).
 // evidencePreflight 구조 사전검증용 placeholder(실제 sourceSha/consumedAt는 source 커밋 후 채움). valid OID/ISO 형식.
 const PREFLIGHT_PLACEHOLDER_OID = '0'.repeat(40)
 const PREFLIGHT_PLACEHOLDER_ISO = '2000-01-01T00:00:00.000Z'
@@ -163,8 +164,8 @@ export function validateManifest(
     if (typeof e.response_sha256 !== 'string' || !SHA256_RE.test(e.response_sha256)) problems.push(`line ${ln}: response_sha256 형식 오류(64hex)`)
     if (typeof e.review_base_sha !== 'string' || !GIT_OID_RE.test(e.review_base_sha)) problems.push(`line ${ln}: review_base_sha 비-OID`)
     if (typeof e.consumed_by_commit_sha !== 'string' || !GIT_OID_RE.test(e.consumed_by_commit_sha)) problems.push(`line ${ln}: consumed_by_commit_sha 비-OID`)
-    if (typeof e.approved_at !== 'string' || !ISO_RE.test(e.approved_at)) problems.push(`line ${ln}: approved_at 비-ISO`)
-    if (typeof e.consumed_at !== 'string' || !ISO_RE.test(e.consumed_at)) problems.push(`line ${ln}: consumed_at 비-ISO`)
+    if (!isValidIsoInstant(e.approved_at)) problems.push(`line ${ln}: approved_at 비-ISO`)
+    if (!isValidIsoInstant(e.consumed_at)) problems.push(`line ${ln}: consumed_at 비-ISO`)
     // kind별 strict 바인딩(반대 kind 필드 금지).
     if (kind === 'phase') {
       if (typeof e.phase_id !== 'string' || !e.phase_id || !opts.validPhaseIds.includes(e.phase_id))
@@ -228,7 +229,7 @@ export function userConfirmProblem(ucc: unknown): string | null {
   const c = ucc as { confirmed?: unknown; method?: unknown; confirmed_at?: unknown }
   if (c.confirmed !== true) return 'confirmed=true 아님'
   if (typeof c.method !== 'string' || !c.method.trim()) return 'method(공백 아닌 문자열) 필요'
-  if (typeof c.confirmed_at !== 'string' || !ISO_RE.test(c.confirmed_at)) return 'confirmed_at(ISO) 필요'
+  if (!isValidIsoInstant(c.confirmed_at)) return 'confirmed_at(ISO) 필요'
   return null
 }