commitgate 0.2.2 → 0.3.1

package/AGENTS.template.md

@@ -30,10 +30,44 @@
 - 커밋 메시지 컨벤션: `test/feat/fix/refactor/docs/chore` 접두사. `[Codex]`/`[Claude]` 같은 메타 정보 금지(Reviewer 편향 방지).
 - HIGH 영향 phase는 `req:commit --run` 직전 사용자 확인(`state.user_commit_confirmed`).
 
+### 5. 승인 범위 해석 규칙
+
+**승인은 승인받은 문장 그대로만 유효하다.** 한 통제점의 승인은 다음 통제점으로 **이월되지 않는다**.
+
+- `PR 생성 승인`은 `PR merge 승인`이 아니다.
+- `merge/push 승인`은 `required status checks bypass 승인`이 아니다.
+- 통합 승인은 릴리즈 승인이 아니고, `tag` 승인은 `publish` 승인이 아니다.
+- **권한이 있다는 사실은 승인이 아니다.** protected branch를 우회할 권한이 있어도, 우회하려면 그 우회 자체를 승인받아야 한다.
+- 승인 문장이 모호하면 확대 해석하지 말고 **다시 묻는다**.
+
+> PR을 생략할 수 있다는 것과, 우회를 보고하지 않아도 된다는 것은 다르다. 경로는 선택이지만 **투명성은 선택이 아니다.**
+
 ## 사람에게 보고해야 할 때
 
+각 통제점은 **고유한 승인 문장**을 가진다. 그 문장 그대로 승인받지 못했으면 실행하지 않는다.
+
+protected branch에 변경을 넣는 경로는 **두 가지**이고 **둘 다 유효**하다. PR은 **의무가 아니라 선택**이다.
+
+- **경로 A (PR 경유)**: `I1` → required status checks green → `I2`
+- **경로 B (direct push)**: `B1` → push → **CI 사후 실행**
+
+| # | 통제점 | 경로 | 멈추는 시점 | 승인 문장 |
+|---|---|---|---|---|
+| `I1` | 통합 — PR 열기 | A | feature branch를 원격에 push하고 PR을 생성하기 직전 | `feature branch push + PR 생성 승인` |
+| `I2` | 통합 — PR 머지 | A | **required status checks가 전부 green으로 끝난 것을 확인한 뒤**, PR을 protected branch에 머지하기 직전 | `required checks green 확인 후 PR merge 승인` |
+| `B1` | 통합 — direct push | B | protected branch에 **direct push**하기 직전 | `branch protection bypass를 사용한 direct push 승인` |
+| `R1` | 릴리즈 — tag | — | 버전 tag 생성 및 tag push 직전 | `tag 생성·push 승인` |
+| `R2` | 릴리즈 — publish | — | 패키지 publish 직전 | `npm publish 승인` |
+| `R3` | 릴리즈 — release | — | GitHub release 생성 직전 | `GitHub release 생성 승인` |
+
+- 경로 A: `I2`는 checks 결과를 본 뒤에만 요청한다 — green 전 선승인은 받지 않는다(승인자가 볼 근거가 아직 없다).
+- 경로 B: **direct push는 required status checks를 우회한다.** 그래서 `B1` 승인이 따로 필요하다. 경로 B를 고르는 것 자체는 잘못이 아니다 — **우회 사실을 숨기는 것**이 잘못이다.
+- **push 전에 멈춰라.** 대상이 protected branch로 알려져 있거나 확인이 안 되면 push하기 전에 보고한다. push 응답의 `remote: Bypassed rule violations`는 우회가 **이미 일어난 뒤**의 사후 신호이므로 사전 정지의 근거가 될 수 없다.
+- **경로 B에서 CI는 사후 검증이다.** push 이후에 돌기 때문에, 그 green은 반영을 *사전에* 막아 준 게 아니다. 보고할 때 이 사실을 생략하지 않는다.
+- `R1`·`R2`·`R3`는 반영(`I2` 또는 `B1`) 이후 **CI green을 확인한 뒤** 각각 따로 요청한다. 경로 B였다면 그 green이 push 뒤에 나왔다는 점을 함께 보고한다. 셋을 하나의 "릴리즈 승인"으로 뭉뚱그리지 않는다.
+
+그 밖에 보고해야 할 때:
 - HIGH commit 실행 직전
-- main merge / push 직전
 - destructive 작업(reset/clean/force push) 필요
 - 설계 범위 변경 또는 비목표 추가 필요
 - Codex 리뷰 BLOCKED(exit 2) 또는 제한된 재시도 후 판단 불명확

package/README.en.md

@@ -42,9 +42,11 @@ Proceed automatically:
 - The review target is only what has been staged with git add.
 - Do not manually git add state.json or responses/.
 
-Stop for human confirmation only:
+Stop for human confirmation only (each item must be approved by that exact sentence; one approval never carries over to the next step):
 - Right before req:commit --run
-- Before merging to main or pushing
+- [Path A · optional] [I1] Before pushing the feature branch and opening a PR / [I2] Before merging the PR, after confirming the required status checks are green
+- [Path B] [B1] Before a direct push to a protected branch — get a separate "branch protection bypass를 사용한 direct push 승인". This push bypasses the required status checks, and CI runs after it
+- [R1/R2/R3] tag creation and push / npm publish / GitHub release — each approved separately, after CI is green
 - Before destructive actions such as reset, clean, or force push
 - When the requested scope must change
 - When Codex review returns BLOCKED or remains unclear after bounded retries
@@ -64,10 +66,12 @@ Branch: feat/req-2026-002-profile-edit-api
 Phases:
 - phase-1: implement PATCH /profile
 - phase-2: tests and regression checks
-Control points: before req:commit --run, before push
+Control points: before req:commit --run / [B1] before a direct push to main (or [I1] open PR → [I2] merge)
 ```
 
-After that, the agent runs design, implementation, tests, and Codex review. You only confirm at control points such as commit or push.
+After that, the agent runs design, implementation, tests, and Codex review. You only confirm at control points.
+
+Both integration paths are valid: **through a PR (optional)** and **direct push**. A PR is not mandatory. But a direct push to a protected branch **bypasses the required status checks**, so it needs a separate "branch protection bypass를 사용한 direct push 승인" — holding bypass permission is not approval. In that case CI runs **after** the push, so its green is post-hoc verification, and the agent must not omit that from its report. tag, npm publish, and GitHub release are control points of their own, requested after CI is green and never bundled with the integration approval. See [AGENTS.template.md](AGENTS.template.md) and [docs/RELEASING.md](docs/RELEASING.md) for the full contract.
 
 ---
 
@@ -114,6 +118,87 @@ npx commitgate --strict
 
 If an existing `cross-spawn` is below the verified floor, CommitGate stops before copying files.
 
+> `workflow/machine.schema.json` and `workflow/req.config.schema.json` are always copied under `workflow/`, regardless of the `ticketRoot` setting in `req.config.json`.
+
+---
+
+## Removing CommitGate
+
+First, the important part: **`npx commitgate` is not a global install.** npx downloads the package into the npm cache (`_npx/<hash>/`) and runs it once; it leaves nothing in your global `node_modules` and nothing on your PATH. The real "installation" is the set of files added to your repo, plus the `package.json` changes listed above.
+
+Start by previewing the removal plan. This command **deletes nothing**:
+
+```sh
+npx commitgate uninstall
+```
+
+It reads your repo and classifies what it finds: (1) CommitGate-owned files that are byte-identical to the package originals, (2) files that differ and need your review, (3) files that must not be removed automatically, and (4) audit evidence. Then it prints the revert commands that match your commit state. You review them and run the deletions yourself.
+
+### Why isn't removal automatic?
+
+`init` **does not record on disk what it created.** At removal time it is therefore impossible to tell apart:
+
+- `AGENTS.md` is created **only when absent**. If you already had one, init leaves it alone — so a file init wrote and a file you wrote look identical on disk.
+- `req.config.json` is **merged** (missing keys only) when it already exists. The original is not kept, so the merge cannot be undone.
+- `package.json` only gets keys that are **absent**. A pre-existing `req:doctor` or `cross-spawn` is not CommitGate's. And `ajv`, `cross-spawn`, and `tsx` are devDependencies other packages commonly use too.
+- Your `ticketRoot` (default `workflow/`) accumulates REQ ticket `state.json` and `approvals.jsonl` — this tool's **audit evidence**.
+
+Deleting all of that without a ledger would destroy user data. CommitGate installs no git hooks and touches no git config — it is a pure in-tree scaffolder, so git is the source of truth for undoing it.
+
+### If you have not committed the scaffold
+
+```sh
+git status --porcelain -uall     # see what was added
+git diff -- package.json         # see the injected req:* scripts and devDependencies
+```
+
+Then revert it yourself. Always restore `package.json` from `HEAD`:
+
+```sh
+git checkout HEAD -- package.json
+```
+
+> ⚠️ Without `HEAD`, git restores from the **index**, so after a `git add` the injected `req:*` scripts survive.
+> ⚠️ This command also discards **any other uncommitted edits** to `package.json`. Check the diff first.
+
+Delete only the paths `npx commitgate uninstall` listed. Removing `scripts/req/` or `workflow/` as whole directories would also take your own files and your ticket evidence with them.
+
+> git does not track empty directories. After deleting the files, `git status` can report a clean tree while empty `scripts/` and `workflow/` directories remain on disk.
+
+### If you already committed the scaffold
+
+Revert the commit that introduced it.
+
+```sh
+git log --diff-filter=A --format='%H %s' -- scripts/req/req-new.ts
+git revert <sha>
+```
+
+`npx commitgate uninstall` finds the introducing commit for you. If that commit also contains unrelated work, reverting it undoes that work too — inspect it with `git show <sha>` first. If the scaffold was introduced across several commits, no single revert will undo it.
+
+### Clearing the npx cache (unrelated to your repo)
+
+Check for a global install first:
+
+```sh
+npm ls -g commitgate            # empty output means it is not installed globally
+npm uninstall -g commitgate     # only if you did install it globally
+```
+
+The package npx downloaded stays under `_npx/` in the npm cache.
+
+```powershell
+# Windows (PowerShell)
+Remove-Item -Recurse -Force "$(npm config get cache)\_npx"
+```
+
+```sh
+# macOS / Linux
+rm -rf "$(npm config get cache)/_npx"
+```
+
+> ⚠️ **`npm cache clean --force` is not a CommitGate removal command.** It empties `_cacache` only and leaves `_npx` intact. It has nothing to do with the scaffolding in your repo.
+
 ---
 
 ## Prerequisites
@@ -181,6 +266,7 @@ npm run req:commit -- 2026-001 --run --message-file commit-message.txt
 | `npx commitgate` | Install CommitGate into a project |
 | `npx commitgate --dry-run` | Preview the install plan without writing files |
 | `npx commitgate --strict` | Treat low `cross-spawn` version warnings as install failures |
+| `npx commitgate uninstall` | Preview the removal plan (read-only — deletes nothing) |
 | `req:new <slug> --run` | Create a REQ ticket, branch, and design docs |
 | `req:review-codex <id> --kind design --run` | Review the design |
 | `req:review-codex <id> --kind phase --run` | Review the implementation |

package/README.md

@@ -42,9 +42,11 @@ req:new → 설계문서 작성 → Codex design 리뷰 → 구현·테스트
 - 리뷰 대상은 git add 한 파일만이다.
 - `state.json`과 `responses/`는 직접 `git add`하지 않는다.
 
-멈춰서 확인받을 때:
+멈춰서 확인받을 때(각 항목은 그 문장 그대로 승인받아야 하며, 한 승인은 다음 단계로 이월되지 않는다):
 - req:commit --run 직전
-- main 병합 또는 push 직전
+- [경로 A · 선택] [I1] feature branch push + PR 생성 직전 / [I2] required checks green 확인 후 PR merge 직전
+- [경로 B] [B1] protected branch에 direct push 직전 — "branch protection bypass를 사용한 direct push 승인"을 따로 받는다. 이 push는 required checks를 우회하고, CI는 사후에 돈다
+- [R1/R2/R3] tag 생성·push / npm publish / GitHub release — CI green 확인 후 각각 별도 승인
 - reset, clean, force push 같은 destructive 작업 전
 - 요구사항 범위를 바꿔야 할 때
 - Codex 리뷰가 BLOCKED를 반환하거나 제한된 재시도 후에도 판단이 불명확할 때
@@ -64,10 +66,12 @@ REQ-2026-002 발행
 phase:
 - phase-1: PATCH /profile 구현
 - phase-2: 테스트와 회귀 확인
-통제점: req:commit --run 직전, push 직전
+통제점: req:commit --run 직전 / [B1] main direct push 직전 (또는 [I1] PR 생성 → [I2] merge)
 ```
 
-이후에는 에이전트가 설계, 구현, 테스트, Codex 리뷰를 진행합니다. 사용자는 커밋이나 push 같은 통제점에서만 확인하면 됩니다.
+이후에는 에이전트가 설계, 구현, 테스트, Codex 리뷰를 진행합니다. 사용자는 통제점에서만 확인하면 됩니다.
+
+main에 반영하는 경로는 **PR 경유(선택)**와 **direct push** 둘 다 유효합니다. PR은 의무가 아닙니다. 다만 protected branch로 직접 push하면 required checks를 **우회**하므로 "branch protection bypass를 사용한 direct push 승인"을 따로 받아야 합니다 — bypass 권한이 있다는 사실은 승인이 아닙니다. 그리고 이때 CI는 push **이후에** 도는 **사후 검증**이라, 그 사실을 보고에서 생략하지 않습니다. tag, npm publish, GitHub release는 반영과 묶이지 않는 별도 통제점이고 CI green 이후에 요청합니다. 자세한 계약은 [AGENTS.template.md](AGENTS.template.md)와 [docs/RELEASING.md](docs/RELEASING.md)를 참고하세요.
 
 ---
 
@@ -114,6 +118,87 @@ npx commitgate --strict
 
 기존 `cross-spawn`이 검증 하한보다 낮으면 파일을 복사하기 전에 중단합니다.
 
+> `workflow/machine.schema.json`과 `workflow/req.config.schema.json`은 `req.config.json`의 `ticketRoot` 설정과 무관하게 **항상 `workflow/` 아래**에 복사됩니다.
+
+---
+
+## 제거하려면
+
+먼저 알아둘 것: **`npx commitgate`는 전역 설치가 아닙니다.** npx는 패키지를 npm 캐시(`_npx/<hash>/`)에 받아 한 번 실행할 뿐이고, 전역 `node_modules`에도 PATH에도 아무것도 남기지 않습니다. 실제 "설치물"은 위 표대로 **대상 repo에 추가된 파일과 `package.json` 변경**입니다.
+
+제거 계획을 먼저 확인하세요. 이 명령은 **아무것도 지우지 않고** 계획만 출력합니다:
+
+```sh
+npx commitgate uninstall
+```
+
+repo를 읽어 (1) CommitGate가 설치한 파일 중 패키지 원본과 바이트가 동일한 것, (2) 편집돼서 직접 확인이 필요한 것, (3) 자동 제거하면 안 되는 것, (4) 감사 증거를 분류해 보여주고, 커밋 여부에 맞는 되돌리기 명령을 출력합니다. 삭제는 사용자가 검토한 뒤 직접 실행합니다.
+
+### 왜 자동으로 지워주지 않나요?
+
+`init`은 **무엇을 새로 만들었는지 디스크에 기록하지 않습니다.** 그래서 제거 시점에는 아래를 구분할 수 없습니다.
+
+- `AGENTS.md`는 **없을 때만** 생성됩니다. 이미 있었다면 그대로 두므로, init이 만든 파일과 사용자가 쓴 파일이 디스크상 같아 보입니다.
+- `req.config.json`은 이미 있으면 **누락된 키만 병합**합니다. 원본을 보관하지 않아 병합을 되돌릴 수 없습니다.
+- `package.json`은 **없는 키만** 주입합니다. 원래 있던 `req:doctor`나 `cross-spawn`은 CommitGate 소유가 아닙니다. `ajv`·`cross-spawn`·`tsx`는 다른 패키지도 흔히 쓰는 devDependency입니다.
+- `ticketRoot`(기본 `workflow/`)에는 REQ 티켓의 `state.json`과 `approvals.jsonl` — 이 도구의 **감사 증거** — 가 쌓입니다.
+
+원장이 없는 상태에서 일괄 삭제하면 사용자 데이터를 파괴합니다. CommitGate는 git hook을 설치하지 않고 git config도 건드리지 않는 순수 in-tree 스캐폴더이므로, 되돌리기의 정본은 git입니다.
+
+### 아직 커밋하지 않았다면
+
+```sh
+git status --porcelain -uall     # 무엇이 추가됐는지 확인
+git diff -- package.json         # 주입된 req:* 스크립트와 devDependencies 확인
+```
+
+확인한 뒤 직접 되돌립니다. `package.json`은 반드시 `HEAD` 기준으로 복원하세요.
+
+```sh
+git checkout HEAD -- package.json
+```
+
+> ⚠️ `HEAD`를 빼면 **인덱스**에서 복원되어, `git add` 이후에는 주입된 `req:*` 스크립트가 그대로 남습니다.
+> ⚠️ 이 명령은 `package.json`의 **다른 미커밋 편집도 함께 버립니다.** 먼저 위 diff를 확인하세요.
+
+파일 삭제는 `npx commitgate uninstall`이 나열해 준 경로만 지우세요. `scripts/req/`나 `workflow/`를 디렉터리째 지우면 그 안의 사용자 파일이나 티켓 증거가 함께 사라집니다.
+
+> git은 빈 디렉터리를 추적하지 않습니다. 파일을 다 지운 뒤 `git status`가 clean이어도 빈 `scripts/`·`workflow/`가 파일시스템에 남을 수 있습니다.
+
+### 이미 커밋했다면
+
+스캐폴딩을 추가한 커밋을 되돌립니다.
+
+```sh
+git log --diff-filter=A --format='%H %s' -- scripts/req/req-new.ts
+git revert <sha>
+```
+
+`npx commitgate uninstall`이 도입 커밋 후보를 찾아 줍니다. 그 커밋에 다른 변경이 섞여 있으면 revert가 무관한 작업까지 되돌리므로, 먼저 `git show <sha>`로 확인하세요. 도입 커밋이 여러 개로 흩어져 있으면 단일 revert로는 되돌릴 수 없습니다.
+
+### npx 캐시 정리 (repo와 무관)
+
+전역 설치 여부부터 확인합니다.
+
+```sh
+npm ls -g commitgate            # 비어 있으면 전역 설치가 아님
+npm uninstall -g commitgate     # 전역으로 설치했던 경우에만
+```
+
+npx가 받아 둔 패키지는 npm 캐시의 `_npx/` 아래에 남습니다.
+
+```powershell
+# Windows (PowerShell)
+Remove-Item -Recurse -Force "$(npm config get cache)\_npx"
+```
+
+```sh
+# macOS / Linux
+rm -rf "$(npm config get cache)/_npx"
+```
+
+> ⚠️ **`npm cache clean --force`는 CommitGate 제거 명령이 아닙니다.** 이 명령은 `_cacache`만 비우고 `_npx`는 그대로 둡니다. repo의 스캐폴딩과도 아무 관련이 없습니다.
+
 ---
 
 ## 준비물
@@ -181,6 +266,7 @@ npm run req:commit -- 2026-001 --run --message-file commit-message.txt
 | `npx commitgate` | 프로젝트에 CommitGate 설치 |
 | `npx commitgate --dry-run` | 파일을 쓰지 않고 설치 계획 확인 |
 | `npx commitgate --strict` | 낮은 `cross-spawn` 버전 경고를 설치 실패로 처리 |
+| `npx commitgate uninstall` | 제거 계획 확인 (읽기 전용 — 아무것도 지우지 않음) |
 | `req:new <slug> --run` | REQ 티켓, 브랜치, 설계문서 생성 |
 | `req:review-codex <id> --kind design --run` | 설계 리뷰 |
 | `req:review-codex <id> --kind phase --run` | 구현 리뷰 |

package/bin/commitgate.mjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 /**
  * commitgate bin 런처(Stage A).
- * npm bin은 TS를 직접 실행 못 하므로 tsx ESM 로더를 얹어 init.ts를 실행한다.
+ * npm bin은 TS를 직접 실행 못 하므로 tsx ESM 로더를 얹어 init.ts/uninstall.ts를 실행한다.
  *
  * ⚠️ tsx는 반드시 **이 런처(=패키지) 기준**으로 해소해야 한다(호출 cwd 아님).
  *    npx로 실행하면 cwd=대상 repo인데 그곳엔 아직 tsx가 없을 수 있어,
@@ -9,6 +9,9 @@
  *    `import ... from 'tsx/esm/api'`는 이 .mjs(패키지 node_modules) 기준으로 정적 해소되므로 cwd 무관.
  *    (node:module의 register('tsx/esm')는 tsx v4가 deprecated --loader로 간주해 거부 → tsx 자체 API 사용.)
  * (Stage B에서 init.ts를 JS로 빌드하면 이 런처는 제거 가능.)
+ *
+ * verb dispatch(REQ-2026-007): `uninstall`만 별도 모듈로 보낸다. verb 없는 호출은 **현행 그대로 init**(하위호환).
+ *    dispatch를 여기(단일 bin 진입점)에 두면 uninstall.ts → init.ts 단방향 import가 되어 순환이 생기지 않는다.
  */
 import { register } from 'tsx/esm/api'
 import { fileURLToPath, pathToFileURL } from 'node:url'
@@ -16,7 +19,11 @@ import { dirname, join } from 'node:path'
 
 register()
 
-const initTs = pathToFileURL(join(dirname(fileURLToPath(import.meta.url)), 'init.ts')).href
-const mod = await import(initTs)
+const binDir = dirname(fileURLToPath(import.meta.url))
+const argv = process.argv.slice(2)
+const entry = argv[0] === 'uninstall' ? 'uninstall.ts' : 'init.ts'
+const rest = argv[0] === 'uninstall' ? argv.slice(1) : argv
+
+const mod = await import(pathToFileURL(join(binDir, entry)).href)
 // runCli = 예외를 친절한 한 줄 메시지 + exit 1로 변환하는 CLI 경계(스택트레이스 노출 방지).
-mod.runCli(process.argv.slice(2))
+mod.runCli(rest)

package/bin/init.ts

@@ -29,10 +29,20 @@ import { createGitAdapter, type GitRunner } from '../scripts/req/lib/adapters'
 import * as semver from 'semver'
 
 /** 이 패키지 루트(bin/ 기준 1단계 위). 복사 원본. */
-const PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..')
+export const PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..')
+
+/** kit 소스 디렉터리(패키지-상대 = 대상-상대). copyInto가 이 레이아웃을 그대로 재현. */
+export const KIT_SOURCE_DIR_REL = 'scripts/req'
+
+/**
+ * init이 **실제로 복사하는** 스키마 경로(패키지-상대 = 대상-상대). ⚠️ `req.config.json`의 `ticketRoot`/`schemaPath`와 무관하게
+ * 언제나 리터럴 `workflow/` 아래다 — `copyInto`가 `relative(PACKAGE_ROOT, src)`로 상대경로를 재현하기 때문.
+ * runInit(복사)과 uninstall planner(제거 후보)가 이 상수를 **공유**해야 드리프트가 없다(REQ-2026-007 design R1 P2 / D3b).
+ */
+export const KIT_SCHEMA_RELPATHS = ['workflow/machine.schema.json', 'workflow/req.config.schema.json'] as const
 
 /** 대상 package.json에 주입할 req:* 스크립트. */
-const REQ_SCRIPTS: Record<string, string> = {
+export const REQ_SCRIPTS: Record<string, string> = {
   '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',
@@ -43,7 +53,7 @@ const REQ_SCRIPTS: Record<string, string> = {
 const CROSS_SPAWN_SPEC = '^7.0.6'
 
 /** 대상 package.json에 주입할 devDeps(워크플로 실행 전제). cross-spawn = 복사된 adapters.ts의 안전 spawn(P1) 런타임 의존. */
-const REQ_DEV_DEPS: Record<string, string> = {
+export const REQ_DEV_DEPS: Record<string, string> = {
   ajv: '^8.20.0',
   'cross-spawn': CROSS_SPAWN_SPEC,
   tsx: '^4.19.1',
@@ -72,14 +82,17 @@ export interface InitResult {
 /**
  * 대상이 진짜 git work tree인지 실제 git으로 검증(D5, design R1 P2). `.git` 경로 존재만으론 부족(fake 마커 통과).
  * targetRoot가 repo top-level과 일치해야 함(하위 디렉터리에 스캐폴드 방지). git 미설치/비-repo → throw(fail-closed).
+ *
+ * `run` 주입(REQ-2026-007): uninstall planner가 자신의 감시 runner로 이 검증을 통과시켜
+ * **모든 git 호출을 단일 경계에서 관측**할 수 있게 한다. 미지정 시 기존 quiet runner(동작 불변).
  */
-function assertGitWorkTree(targetRoot: string): void {
+export function assertGitWorkTree(targetRoot: string, run?: GitRunner): void {
   // probe 전용 runner: 비-repo일 때 git이 뱉는 `fatal: not a git repository` stderr를 삼킨다.
   // 우리가 더 명확한 조치 메시지로 대체하므로 raw git stderr는 노이즈일 뿐(design 후속 UX).
   // ⚠️ 전역 GitAdapter 기본(stderr 상속)은 그대로 — 다른 git 호출(req:commit 등)의 진단 손실 방지.
   const quietRunner: GitRunner = (file, args, opts) =>
     execFileSync(file, args, { ...opts, stdio: ['ignore', 'pipe', 'ignore'] })
-  const git = createGitAdapter(targetRoot, quietRunner)
+  const git = createGitAdapter(targetRoot, run ?? quietRunner)
   let inside: string
   let topLevel: string
   try {
@@ -297,7 +310,7 @@ export function runInit(opts: InitOptions): InitResult {
   const packageManager = detectPackageManager(targetRoot)
 
   // req.config.json 계획(쓰기 없음). handoffPath:null·packageManager를 항상 보장 —
-  // 코어 DEFAULTS의 palm 고유값(handoffPath)이 기존 부분 config에서도 resurface하지 않도록(design R1 P2). 기존 키 보존.
+  // handoffPath는 프로젝트별 값이라 코어 기본이 비활성(null)이다 — 그 비활성을 config에 **명시 기록**한다(암묵 < 명시). 기존 키 보존.
   let configAction: 'created' | 'merged' | 'unchanged' = 'unchanged'
   const configKeysAdded: string[] = []
   let configToWrite: Record<string, unknown> | null = null
@@ -344,8 +357,9 @@ export function runInit(opts: InitOptions): InitResult {
   // ══ Apply: 여기부터 쓰기(preflight 전부 통과 후에만) ═════════════════
   const copied: string[] = []
   const skipped: string[] = []
-  copyInto(walkFiles(join(PACKAGE_ROOT, 'scripts', 'req')), PACKAGE_ROOT, targetRoot, opts, copied, skipped)
-  const schemaFiles = ['machine.schema.json', 'req.config.schema.json'].map((f) => join(PACKAGE_ROOT, 'workflow', f))
+  copyInto(walkFiles(join(PACKAGE_ROOT, KIT_SOURCE_DIR_REL)), PACKAGE_ROOT, targetRoot, opts, copied, skipped)
+  // ⚠️ KIT_SCHEMA_RELPATHS는 패키지-상대 = 대상-상대(리터럴 `workflow/`). ticketRoot/schemaPath 설정과 무관 — uninstall planner와 공유하는 SSOT.
+  const schemaFiles = KIT_SCHEMA_RELPATHS.map((rel) => join(PACKAGE_ROOT, rel))
   copyInto(schemaFiles, PACKAGE_ROOT, targetRoot, opts, copied, skipped)
 
   if (!opts.dryRun) {
@@ -405,6 +419,7 @@ function printHelp(): void {
 
 사용법:
   npx commitgate [--dir <대상repo>] [--force] [--dry-run] [--strict]
+  npx commitgate uninstall [--dir <대상repo>]   # 제거 계획만 출력(아무것도 지우지 않음)
 
 옵션:
   --dir <path>   대상 repo 루트(기본: 현재 디렉터리)

package/bin/uninstall.ts

@@ -0,0 +1,551 @@
+#!/usr/bin/env tsx
+/**
+ * commitgate uninstall — **읽기 전용 removal planner** (REQ-2026-007).
+ *
+ * 이 모듈은 아무것도 지우지 않는다. repo를 읽어 제거 계획과 "사용자가 직접 검토 후 실행할 명령"만 출력한다.
+ *
+ * 왜 실제 삭제를 하지 않는가:
+ *   `runInit`은 무엇을 새로 만들었고(copied) 무엇이 이미 있었는지(skipped/merged)를 계산만 하고 **디스크에 원장을 남기지 않는다**.
+ *   따라서 uninstall 시점에 `AGENTS.md`(부재 시에만 생성)·`req.config.json`(누락 키만 병합)·`package.json`(부재 키만 주입)이
+ *   CommitGate 소유인지 사용자 소유인지 구분할 수 없다. 원장 없는 blind delete는 사용자 데이터를 파괴한다.
+ *   CommitGate는 git hook·git config를 건드리지 않는 **순수 in-tree 스캐폴더**이므로 되돌리기의 정본은 git이다.
+ *
+ * 읽기 전용 계약(테스트로 고정 — tests/unit/uninstall.test.ts):
+ *   - `node:fs`에서 조회 API만 가져온다(파일을 만들거나 고치거나 지우는 API를 import하지 않는다).
+ *   - git은 read-only 서브커맨드 allowlist(`rev-parse`·`status`·`ls-files`·`log`)만 호출한다.
+ *   - 해시는 `node:crypto`로 계산한다(`git hash-object`는 objects/에 쓸 수 있어 쓰지 않는다).
+ *   - npm을 spawn하지 않는다. 캐시 정리 명령은 문자열로 출력만 한다.
+ *   - 삭제 플래그(`--run`/`--force`)를 제공하지 않는다 — 이 부재가 계약이다.
+ */
+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 { createGitAdapter, type GitAdapter, type GitRunner } from '../scripts/req/lib/adapters'
+import {
+  PACKAGE_ROOT,
+  KIT_SOURCE_DIR_REL,
+  KIT_SCHEMA_RELPATHS,
+  REQ_SCRIPTS,
+  REQ_DEV_DEPS,
+  assertGitWorkTree,
+} from './init'
+
+export interface UninstallOptions {
+  dir: string
+}
+
+/** CommitGate가 복사한 파일(kit 소스 + init이 실제로 복사한 스키마). 바이트 비교로 무결성만 표기. */
+export interface ToolArtifact {
+  path: string // repo-상대
+  present: boolean
+  /** 현재 실행 중인 패키지의 원본과 바이트 동일? `differs`는 "편집됐거나 **다른 버전**이 설치함"일 뿐 사용자 소유 단정이 아니다. */
+  match: 'identical' | 'differs' | 'absent'
+  tracked: boolean
+  /**
+   * 이 경로를 추가(A)한 **가장 최근** 커밋 sha. **현재 tracked인 파일에 한해서만** 채운다(phase R2 P2).
+   * 과거에 추가됐다가 삭제된 경로는 `git log --diff-filter=A`에 낡은 add 커밋이 남아 있어,
+   * 새로 설치한 untracked 파일을 "커밋됨"으로 오판하고 엉뚱한 커밋의 revert를 권하게 된다.
+   */
+  introducedBy: string | null
+}
+
+/** origin 판별 불가 → **항상 자동 제거 대상에서 제외**. `path`는 파일 또는 `package.json#scripts.req:new` 형태. */
+export interface AmbiguousArtifact {
+  path: string
+  present: boolean
+  note: string
+}
+
+/** 설정된 ticketRoot — REQ 티켓 state.json·approvals.jsonl 등 감사 증거. */
+export interface EvidenceDir {
+  path: string
+  ticketCount: number
+}
+
+export interface ScaffoldCommit {
+  sha: string
+  subject: string
+}
+
+export interface UninstallFacts {
+  targetRoot: string
+  /** `loadConfig` 해소값. 증거 보호 축(설치 경로 축은 KIT_SCHEMA_RELPATHS). */
+  ticketRoot: string
+  schemaPath: string
+  /** config를 읽지 못해 DEFAULTS로 강등했으면 사유. planner는 쓰기가 없으므로 강등이 안전하다. */
+  configError: string | null
+  installed: boolean
+  packageJsonDirty: boolean
+  tool: ToolArtifact[]
+  ambiguous: AmbiguousArtifact[]
+  evidence: EvidenceDir[]
+  info: string[]
+  /**
+   * kit 디렉터리(`scripts/req/`) 안에 있지만 이 패키지가 설치한 파일이 **아닌** 것들(phase R1 P1).
+   * 사용자가 직접 넣은 파일일 수 있으므로 제거 후보에 넣지 않고, 디렉터리 통삭제도 제안하지 않는다.
+   */
+  unknownKitFiles: string[]
+}
+
+export type UninstallMode = 'not-installed' | 'uncommitted' | 'committed' | 'mixed'
+
+export interface UninstallPlan {
+  facts: UninstallFacts
+  mode: UninstallMode
+  /** 패키지 원본과 바이트 동일 → 사용자가 지워도 잃을 것이 없는 파일. */
+  removable: ToolArtifact[]
+  /** 원본과 다름 → 사용자 검토 후 판단. */
+  review: ToolArtifact[]
+  /** ambiguous 중 실제로 존재하는 것 — 자동 제거 금지 목록. */
+  keep: AmbiguousArtifact[]
+  /** 티켓이 실제로 쌓인 증거 디렉터리 — 삭제 금지. */
+  protect: EvidenceDir[]
+  scaffoldCommits: ScaffoldCommit[]
+}
+
+const TICKET_DIR_RE = /^REQ-\d{4}-\d+$/
+
+// ─────────────────────────────────────────────────────── 읽기 헬퍼 ──
+
+function sha256(abs: string): string {
+  return createHash('sha256').update(readFileSync(abs)).digest('hex')
+}
+
+/** dir 하위 모든 파일의 절대경로(재귀, 조회만). */
+function walkFiles(dir: string): string[] {
+  const out: string[] = []
+  for (const entry of readdirSync(dir)) {
+    const abs = join(dir, entry)
+    if (statSync(abs).isDirectory()) out.push(...walkFiles(abs))
+    else out.push(abs)
+  }
+  return out
+}
+
+const toRel = (abs: string): string => relative(PACKAGE_ROOT, abs).replace(/\\/g, '/')
+
+/** git이 추적 중인가(인덱스에 있는가). */
+function isTracked(git: GitAdapter, rel: string): boolean {
+  return git.exec(['ls-files', '--', rel]).length > 0
+}
+
+/** 이 경로를 처음 추가한 커밋(sha, subject). HEAD 이력에 없으면 null. */
+function introducingCommit(git: GitAdapter, rel: string): ScaffoldCommit | null {
+  const out = git.exec(['log', '--diff-filter=A', '-n', '1', '--format=%H%x09%s', '--', rel])
+  if (!out) return null
+  const tab = out.indexOf('\t')
+  if (tab < 0) return null
+  return { sha: out.slice(0, tab), subject: out.slice(tab + 1) }
+}
+
+/** JSON 객체 파싱(실패/비-객체면 null — planner는 fail-closed 하지 않고 "확인 불가"로 표기). */
+function readJsonObject(abs: string): Record<string, unknown> | null {
+  try {
+    const v: unknown = JSON.parse(stripBom(readFileSync(abs, 'utf8')))
+    return typeof v === 'object' && v !== null && !Array.isArray(v) ? (v as Record<string, unknown>) : null
+  } catch {
+    return null
+  }
+}
+
+function stringMap(obj: Record<string, unknown> | null, key: string): Record<string, string> {
+  const v = obj?.[key]
+  if (v && typeof v === 'object' && !Array.isArray(v)) return v as Record<string, string>
+  return {}
+}
+
+// ──────────────────────────────────────────────── 사실 수집 (IO=읽기) ──
+
+/**
+ * 대상 repo를 읽어 `UninstallFacts`를 만든다. **읽기만 한다.**
+ * `run` 주입 시 모든 git 호출이 그 runner를 통과한다(테스트가 서브커맨드를 감시).
+ */
+export function collectFacts(opts: UninstallOptions, run?: GitRunner): UninstallFacts {
+  const targetRoot = resolve(opts.dir)
+  if (!existsSync(targetRoot) || !statSync(targetRoot).isDirectory())
+    throw new Error(`대상 디렉터리가 없음: ${targetRoot}`)
+  assertGitWorkTree(targetRoot, run)
+  const git = createGitAdapter(targetRoot, run)
+
+  // 증거 보호 축: config에서 해소. 읽지 못하면 DEFAULTS로 강등하되 그 사실을 알린다
+  // (깨진 config 때문에 제거 안내를 못 받는 건 부당하다 — planner는 쓰기가 없어 강등이 안전).
+  let ticketRoot = DEFAULTS.ticketRoot
+  let schemaPath = DEFAULTS.schemaPath
+  let configError: string | null = null
+  try {
+    const cfg = loadConfig({ root: targetRoot })
+    ticketRoot = cfg.ticketRoot
+    schemaPath = cfg.schemaPath
+  } catch (e) {
+    configError = (e as Error).message
+  }
+
+  const info: string[] = []
+  if (configError)
+    info.push(`req.config.json을 읽을 수 없어 기본값(DEFAULTS)으로 강등했습니다 — ${configError}`)
+  // 설치 경로 축(KIT_SCHEMA_RELPATHS)과 설정 경로 축(schemaPath)은 갈라질 수 있다.
+  if (!(KIT_SCHEMA_RELPATHS as readonly string[]).includes(schemaPath))
+    info.push(
+      `schemaPath=${schemaPath} — 런타임이 읽는 경로이지만 init이 복사한 파일이 아닙니다(제거 후보 아님).`,
+    )
+
+  // ── tool: kit 소스 + init이 **실제로 복사한** 스키마(항상 리터럴 workflow/ — ticketRoot 무관)
+  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)
+    if (!existsSync(dest))
+      return { path: rel, 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)
+    return {
+      path: rel,
+      present: true,
+      match,
+      tracked,
+      // untracked면 이력의 add 커밋은 "지금 이 설치본"의 도입 커밋이 아니다 → 조회조차 하지 않는다(phase R2 P2).
+      introducedBy: tracked ? (introducingCommit(git, rel)?.sha ?? null) : null,
+    }
+  })
+
+  // ── ambiguous: origin 판별 불가 → 자동 제거 대상에서 항상 제외
+  const ambiguous: AmbiguousArtifact[] = []
+
+  const agentsAbs = join(targetRoot, 'AGENTS.md')
+  if (existsSync(agentsAbs)) {
+    const tpl = join(PACKAGE_ROOT, 'AGENTS.template.md')
+    const same = existsSync(tpl) && sha256(agentsAbs) === sha256(tpl)
+    ambiguous.push({
+      path: 'AGENTS.md',
+      present: true,
+      note: same
+        ? 'init 템플릿과 동일 — 그래도 자동 제거 대상이 아닙니다(Codex 계약 파일)'
+        : '템플릿과 다름 — 사용자/팀이 작성했거나 편집했습니다',
+    })
+  }
+
+  const cfgAbs = join(targetRoot, 'req.config.json')
+  if (existsSync(cfgAbs)) {
+    const parsed = readJsonObject(cfgAbs)
+    let note: string
+    if (!parsed) note = '파싱 불가 — 내용을 직접 확인하세요'
+    else {
+      const keys = Object.keys(parsed).sort().join(',')
+      note =
+        keys === 'handoffPath,packageManager' && parsed.handoffPath === null
+          ? 'init 시드와 동일 — 그래도 자동 제거 대상이 아닙니다'
+          : '사용자 값 포함(init은 누락 키만 병합합니다) — 값을 보존하세요'
+    }
+    ambiguous.push({ path: 'req.config.json', present: true, note })
+  }
+
+  const pkgAbs = join(targetRoot, 'package.json')
+  const pkg = existsSync(pkgAbs) ? readJsonObject(pkgAbs) : null
+  const scripts = stringMap(pkg, 'scripts')
+  const devDeps = stringMap(pkg, 'devDependencies')
+  for (const [k, injected] of Object.entries(REQ_SCRIPTS)) {
+    const cur = scripts[k]
+    if (cur === undefined) continue
+    ambiguous.push({
+      path: `package.json#scripts.${k}`,
+      present: true,
+      note: cur === injected ? 'init 주입값과 동일' : `사용자 값(init 주입값과 다름): ${cur}`,
+    })
+  }
+  for (const [k, injected] of Object.entries(REQ_DEV_DEPS)) {
+    const cur = devDeps[k]
+    if (cur === undefined) continue
+    ambiguous.push({
+      path: `package.json#devDependencies.${k}`,
+      present: true,
+      note:
+        cur === injected
+          ? 'init 주입값과 동일 — 다른 곳에서도 쓰일 수 있습니다'
+          : `사용자 값(init 주입값과 다름): ${cur}`,
+    })
+  }
+
+  // ── evidence: 설정된 ticketRoot 하위 REQ-* (하드코딩 workflow/ 아님)
+  const evidence: EvidenceDir[] = []
+  const ticketRootAbs = join(targetRoot, ticketRoot)
+  if (existsSync(ticketRootAbs) && statSync(ticketRootAbs).isDirectory()) {
+    const ticketCount = readdirSync(ticketRootAbs, { withFileTypes: true }).filter(
+      (d) => d.isDirectory() && TICKET_DIR_RE.test(d.name),
+    ).length
+    evidence.push({ path: ticketRoot, ticketCount })
+  }
+
+  // ── kit 디렉터리 안의 미분류 파일(phase R1 P1): 사용자가 넣었을 수 있으므로 제거 후보에서 제외하고 통삭제도 금지.
+  const kitDirAbs = join(targetRoot, KIT_SOURCE_DIR_REL)
+  const knownKit = new Set(kitSourceRels)
+  const unknownKitFiles =
+    existsSync(kitDirAbs) && statSync(kitDirAbs).isDirectory()
+      ? walkFiles(kitDirAbs)
+          .map((abs) => relative(targetRoot, abs).replace(/\\/g, '/'))
+          .filter((rel) => !knownKit.has(rel))
+          .sort()
+      : []
+
+  const packageJsonDirty = existsSync(pkgAbs) && git.exec(['status', '--porcelain', '--', 'package.json']).length > 0
+  const installed = tool.some((t) => t.present) || ambiguous.some((a) => a.present)
+
+  return {
+    targetRoot,
+    ticketRoot,
+    schemaPath,
+    configError,
+    installed,
+    packageJsonDirty,
+    tool,
+    ambiguous,
+    evidence,
+    info,
+    unknownKitFiles,
+  }
+}
+
+// ────────────────────────────────────────────────────── 계획 (순수) ──
+
+/** facts → plan. **순수 함수**(IO 없음). */
+export function buildPlan(facts: UninstallFacts): UninstallPlan {
+  const present = facts.tool.filter((t) => t.present)
+  // 도입 커밋은 **현재 tracked인 파일**에서만 인정한다(phase R2 P2 — 낡은 add 커밋으로 인한 오판 차단).
+  const introduced = present.filter((t) => t.tracked && t.introducedBy !== null)
+
+  let mode: UninstallMode
+  if (!facts.installed) mode = 'not-installed'
+  else if (introduced.length === 0) mode = 'uncommitted'
+  else if (introduced.length === present.length) mode = 'committed'
+  else mode = 'mixed'
+
+  // 도입 커밋 후보(중복 제거, 첫 등장 순).
+  const seen = new Set<string>()
+  const scaffoldCommits: ScaffoldCommit[] = []
+  for (const t of introduced) {
+    const sha = t.introducedBy as string
+    if (seen.has(sha)) continue
+    seen.add(sha)
+    scaffoldCommits.push({ sha, subject: '' })
+  }
+
+  return {
+    facts,
+    mode,
+    removable: present.filter((t) => t.match === 'identical'),
+    review: present.filter((t) => t.match === 'differs'),
+    keep: facts.ambiguous.filter((a) => a.present),
+    protect: facts.evidence.filter((e) => e.ticketCount > 0),
+    scaffoldCommits,
+  }
+}
+
+/** subject를 붙인 scaffoldCommits(IO=git log). buildPlan은 순수하게 유지하고 여기서만 보강. */
+function enrichCommits(plan: UninstallPlan, git: GitAdapter): UninstallPlan {
+  if (plan.scaffoldCommits.length === 0) return plan
+  const anchorByS = new Map<string, string>()
+  for (const t of plan.facts.tool) {
+    if (t.introducedBy && !anchorByS.has(t.introducedBy)) anchorByS.set(t.introducedBy, t.path)
+  }
+  const scaffoldCommits = plan.scaffoldCommits.map((c) => {
+    const anchor = anchorByS.get(c.sha)
+    const found = anchor ? introducingCommit(git, anchor) : null
+    return { sha: c.sha, subject: found?.subject ?? '' }
+  })
+  return { ...plan, scaffoldCommits }
+}
+
+// ────────────────────────────────────────────────────── 출력 (순수) ──
+
+const MODE_LABEL: Record<UninstallMode, string> = {
+  'not-installed': '설치 흔적 없음',
+  uncommitted: '설치됨 — 아직 커밋되지 않음',
+  committed: '설치됨 — 커밋됨',
+  mixed: '설치됨 — 일부만 커밋됨',
+}
+
+/** plan → 사람이 읽는 계획 텍스트. **순수 함수**. 여기서 출력하는 명령은 전부 "사용자가 직접 실행할 것"이다. */
+export function renderPlan(plan: UninstallPlan): string {
+  const { facts } = plan
+  const L: string[] = []
+
+  L.push('[commitgate uninstall] 읽기 전용 제거 계획 — 이 명령은 어떤 파일도 지우지 않습니다.')
+  L.push(`  대상       : ${facts.targetRoot}`)
+  L.push(`  상태       : ${MODE_LABEL[plan.mode]}`)
+  L.push(`  ticketRoot : ${facts.ticketRoot}${facts.configError ? ' (기본값 강등)' : ''}`)
+  for (const i of facts.info) L.push(`  참고       : ${i}`)
+  L.push('')
+
+  if (plan.mode === 'not-installed') {
+    L.push('이 repo에서 CommitGate 설치 흔적을 찾지 못했습니다. 되돌릴 것이 없습니다.')
+    L.push('')
+    L.push(renderNpxSection())
+    return L.join('\n')
+  }
+
+  L.push('## 1. CommitGate 소유 파일')
+  if (plan.removable.length) {
+    L.push('   패키지 원본과 바이트 동일 — 지워도 잃을 내용이 없습니다:')
+    for (const t of plan.removable) L.push(`     - ${t.path}${t.tracked ? ' (tracked)' : ' (untracked)'}`)
+  }
+  if (plan.review.length) {
+    L.push('   원본과 다름 — 편집됐거나 다른 버전이 설치했습니다. 지우기 전에 직접 확인하세요:')
+    for (const t of plan.review) L.push(`     ~ ${t.path}${t.tracked ? ' (tracked)' : ' (untracked)'}`)
+  }
+  if (!plan.removable.length && !plan.review.length) L.push('     (없음)')
+  if (facts.unknownKitFiles.length) {
+    L.push(`   ${KIT_SOURCE_DIR_REL}/ 안에 CommitGate가 설치하지 않은 파일이 있습니다 — 건드리지 마세요:`)
+    for (const f of facts.unknownKitFiles) L.push(`     ? ${f}`)
+  }
+  L.push('')
+
+  L.push('## 2. 자동 제거 대상이 아님 — 직접 판단하세요')
+  L.push('   init은 무엇을 새로 만들었는지 디스크에 기록하지 않습니다. 따라서 아래 항목이')
+  L.push('   CommitGate 소유인지 원래 있던 것인지 이 도구는 알 수 없습니다.')
+  if (plan.keep.length) for (const a of plan.keep) L.push(`     - ${a.path}  —  ${a.note}`)
+  else L.push('     (없음)')
+  L.push('')
+
+  L.push('## 3. 감사 증거 — 삭제하지 마세요')
+  if (plan.protect.length)
+    for (const e of plan.protect) L.push(`     - ${e.path}/  (REQ 티켓 ${e.ticketCount}개 · state.json · approvals.jsonl)`)
+  else L.push(`     ${facts.ticketRoot}/ 에 REQ 티켓이 아직 없습니다. 티켓이 생기면 이 디렉터리는 감사 증거가 됩니다.`)
+  L.push('')
+
+  L.push('## 4. 되돌리는 방법 (아래 명령은 직접 실행하세요)')
+  L.push(...renderRevertSection(plan))
+  L.push('')
+
+  L.push('## 5. 잔여물 경고')
+  L.push('   - git은 빈 디렉터리를 추적하지 않습니다. 위 파일을 지운 뒤 `git status`가 clean이어도')
+  L.push(`     빈 디렉터리(scripts/ · ${facts.ticketRoot}/)가 파일시스템에 남을 수 있습니다.`)
+  L.push('   - node_modules의 ajv · cross-spawn · tsx 는 다른 패키지도 쓸 수 있어 제거를 권하지 않습니다.')
+  L.push('')
+
+  L.push(renderNpxSection())
+  return L.join('\n')
+}
+
+function renderRevertSection(plan: UninstallPlan): string[] {
+  const L: string[] = []
+  const { facts } = plan
+
+  if (plan.mode === 'committed' || plan.mode === 'mixed') {
+    if (plan.scaffoldCommits.length === 1) {
+      const c = plan.scaffoldCommits[0] as ScaffoldCommit
+      L.push('   스캐폴딩 도입 커밋:')
+      L.push(`     ${c.sha}  ${c.subject}`)
+      L.push('   이 커밋이 스캐폴딩만 담고 있다면:')
+      L.push(`     git revert ${c.sha}`)
+      L.push('   다른 변경이 섞여 있으면 revert가 무관한 작업까지 되돌립니다 — 먼저 `git show`로 확인하세요.')
+    } else {
+      L.push('   ⚠️ 스캐폴딩 도입 커밋이 여러 개로 흩어져 있어 단일 revert로 되돌릴 수 없습니다:')
+      for (const c of plan.scaffoldCommits) L.push(`     ${c.sha}  ${c.subject}`)
+      L.push('   각 커밋의 내용을 확인한 뒤(`git show <sha>`) 되돌릴 범위를 직접 정하세요.')
+    }
+    if (plan.mode === 'mixed') L.push('   일부 파일은 아직 커밋되지 않았습니다 — 아래 미커밋 절차도 함께 보세요.')
+  }
+
+  if (plan.mode === 'uncommitted' || plan.mode === 'mixed') {
+    L.push('   1) 무엇이 바뀌었는지 확인:')
+    L.push('        git status --porcelain -uall')
+    L.push('        git diff -- package.json')
+    if (facts.packageJsonDirty) {
+      L.push('   2) package.json 되돌리기:')
+      L.push('        git checkout HEAD -- package.json')
+      L.push('      ⚠️ 이 명령은 package.json의 다른 미커밋 편집도 함께 버립니다. 먼저 위 diff를 확인하세요.')
+      L.push('      ⚠️ `HEAD`를 빼면 인덱스에서 복원되어, `git add` 이후에는 주입된 req:* 스크립트가 그대로 남습니다.')
+    }
+    if (plan.removable.length) {
+      // ⚠️ 디렉터리 통삭제(`rm -rf <kit dir>`)는 제안하지 않는다(phase R1 P1): 그 디렉터리에 사용자가 넣은
+      //    미분류 파일이 있으면 함께 지워진다. **분류된 파일만 파일 단위로** 나열한다.
+      L.push('   3) 원본과 동일한 파일만 삭제(직접 실행):')
+      for (const t of plan.removable) L.push(`        rm -f ${t.path}`)
+    }
+    if (plan.review.length) L.push('   4) 위 "원본과 다름" 파일은 내용을 확인한 뒤 직접 결정하세요.')
+  }
+  return L
+}
+
+function renderNpxSection(): string {
+  return [
+    '## npx 캐시 (repo 스캐폴딩과 무관 — 별도 정리)',
+    '   `npx commitgate`는 전역 설치가 아닙니다. 패키지는 npm 캐시의 `_npx/<hash>/`에만 들어갑니다.',
+    '     확인          : npm ls -g commitgate      (비어 있으면 전역 설치 아님)',
+    '     전역이었다면  : npm uninstall -g commitgate',
+    '   캐시에 남은 npx 패키지 정리:',
+    '     Windows (PowerShell) : Remove-Item -Recurse -Force "$(npm config get cache)\\_npx"',
+    '     macOS / Linux        : rm -rf "$(npm config get cache)/_npx"',
+    '   ⚠️ `npm cache clean --force`는 `_cacache`만 비우고 `_npx`는 지우지 않습니다 — CommitGate 제거 명령이 아닙니다.',
+  ].join('\n')
+}
+
+// ─────────────────────────────────────────────────────────── 파사드 ──
+
+/** 사실 수집 → 계획. 읽기 전용. `run` 주입 시 모든 git 호출이 그 runner를 통과. */
+export function planUninstall(opts: UninstallOptions, run?: GitRunner): UninstallPlan {
+  const facts = collectFacts(opts, run)
+  const git = createGitAdapter(resolve(opts.dir), run)
+  return enrichCommits(buildPlan(facts), git)
+}
+
+/** 계획을 stdout에 출력하고 텍스트를 반환. */
+export function runUninstall(opts: UninstallOptions, run?: GitRunner): string {
+  const text = renderPlan(planUninstall(opts, run))
+  console.log(text)
+  return text
+}
+
+export function parseArgs(argv: string[]): UninstallOptions {
+  let dir = process.cwd()
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i]
+    if (a === '--dir') {
+      const v = argv[i + 1]
+      if (v === undefined) throw new Error('--dir 값 누락')
+      dir = v
+      i++
+    } else if (a === '-h' || a === '--help') {
+      printHelp()
+      process.exit(0)
+    } else {
+      throw new Error(`알 수 없는 인자: ${a}`)
+    }
+  }
+  return { dir: resolve(dir) }
+}
+
+function printHelp(): void {
+  console.log(`commitgate uninstall — 제거 계획 출력(읽기 전용)
+
+사용법:
+  npx commitgate uninstall [--dir <대상repo>]
+
+이 명령은 **아무것도 지우지 않습니다.** repo를 읽어 무엇이 설치됐는지 분류하고,
+사용자가 직접 검토 후 실행할 git/삭제 명령을 출력합니다.
+
+옵션:
+  --dir <path>   대상 repo 루트(기본: 현재 디렉터리)
+  -h, --help     도움말
+
+왜 자동 삭제가 없나:
+  init은 "무엇을 새로 만들었는지"를 디스크에 기록하지 않습니다. 그래서 AGENTS.md·req.config.json·
+  package.json의 값이 CommitGate 소유인지 사용자 소유인지 구분할 수 없고, blind 삭제는 데이터를 파괴합니다.
+  이 kit은 git repo에 파일만 추가하므로 되돌리기의 정본은 git입니다.`)
+}
+
+/** CLI 경계: 예상된 실패(throw)를 친절한 한 줄 + exit 1로 변환(스택트레이스 노출 방지). init.ts runCli와 동일 정책. */
+export function runCli(argv: string[]): void {
+  try {
+    runUninstall(parseArgs(argv))
+  } catch (err) {
+    console.error(`commitgate uninstall: ${err instanceof Error ? err.message : String(err)}`)
+    process.exitCode = 1
+  }
+}
+
+const isMain = import.meta.url === pathToFileURL(process.argv[1] ?? '').href
+if (isMain) runCli(process.argv.slice(2))

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "commitgate",
-  "version": "0.2.2",
+  "version": "0.3.1",
   "description": "CommitGate — Builder↔Reviewer(Claude↔Codex) fail-closed 커밋 게이트: 리뷰·승인·증거 없인 커밋을 통과시키지 않는 AI REQ 워크플로 kit (req:new/review-codex/doctor/commit)",
   "type": "module",
   "license": "MIT",

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로 강제.
  */
@@ -48,11 +48,21 @@ export interface ResolvedConfig {
   handoffPathAbs: string | null
 }
 
-/** ⚠️ 현재 하드코딩 값 — 변경 시 behavior-preserving(수용기준 #1) 깨짐. */
+/**
+ * 코어 기본값. `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,
   branchPrefix: 'feat/req-',
   packageManager: 'pnpm' as PackageManager,
   granularityMaxFiles: 8,

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.

package/scripts/req/review-codex.ts

@@ -2,9 +2,7 @@
 /**
  * req:review-codex — AI REQ 워크플로우 1차 (단계 2: 조립·바인딩 캡처 + 기반 검증 로직)
  *
- * SSOT 설계: palm-kiosk/docs/evaluation/ai-req-workflow-design.md
- *   §9.5 호출 문법 · §8.4 staged tree OID 바인딩 · §9.6 구조화 응답·도메인 검증
- * 0차 실측: palm-kiosk-app/workflow/00-spike/00-spike-report.md
+ * 설계 근거: 호출 문법 · staged tree OID 바인딩 · 구조화 응답·도메인 검증.
  * 리뷰 반영(Codex, 2단계): schema 버전 필드·STATUS↔COMMIT 모순 검증·state 부재 명확화·Review Context·AJV(단계3)
  *
  * 단계 2(완료): 조립(handoff·Review Context·request·staged diff) + git 바인딩(staged tree OID) + dry-run 미리보기,
@@ -17,7 +15,7 @@
  * 사용:
  *   pnpm req:review-codex <REQ-id>          # workflow/REQ-<id>/ 대상
  *   pnpm req:review-codex --ticket <dir>    # 임의 티켓 디렉터리
- *   옵션: --handoff <path>  (기본: ../palm-kiosk/docs/evaluation/project-memory/ai-handoff.md, 없으면 생략)
+ *   옵션: --handoff <path>  (미지정 시 req.config.json의 handoffPath. 둘 다 없으면 handoff 블록 생략 — 코어 기본은 비활성)
  */
 import { readFileSync, existsSync, writeFileSync, mkdirSync, readdirSync } from 'node:fs'
 import { resolve, join, relative } from 'node:path'