commitgate 0.7.0 → 0.8.1

package/CHANGELOG.md

@@ -2,6 +2,51 @@
 
 이 프로젝트는 [Semantic Versioning](https://semver.org/lang/ko/)을 따릅니다.
 
+## Unreleased
+
+## 0.8.1
+
+- **README에 0.8.0 기능 문서화** — 설정 표에 `reviewBudget`(재리뷰 시도 예산·상한), "무엇을 보장하나요?"에
+  무한 재리뷰 방지(예산 게이트), "설계 재리뷰는 delta로 좁혀집니다" 절(delta review·full review escalation)을
+  한/영 README에 추가했습니다. 코드 변경 없음(문서만).
+
+## 0.8.0
+
+리뷰 루프 수렴 안정화와 design delta review가 핵심입니다. 모두 `0.7.0` 설치 모델 위의 **추가 기능**이라 기존
+사용자는 별도 조치가 필요 없습니다 — 패키지를 업그레이드한 뒤 `commitgate init`으로 갱신된 관리 자산을 받습니다.
+
+### Companion Skills
+
+- **Companion Skills 추가 및 lifecycle 문서화** — `commitgate init`이 `.claude/skills/commitgate-*/SKILL.md` 4종
+  (`discovery`·`tdd`·`diagnosing-bugs`·`research`)을 함께 설치합니다. 설치·보존·경고·제거 계획·지원 범위는
+  [README](README.md#companion-skills) / [README (English)](README.en.md#companion-skills)를 참조하세요.
+- **`init` 쓰기 경로 symlink confinement** — 설치 대상 전 경로에서 상위 디렉터리·leaf를 `lstat`으로 검사해
+  대상 루트 밖을 가리키는 symlink를 따라가지 않습니다(우발적 symlink로 인한 외부 파일 생성·덮어쓰기 차단).
+
+### 리뷰 루프 수렴 안정화
+
+- **리뷰 시도 계수·예산 게이트** — `(review_kind, phase_id)`별 review series로 시도를 계수하고, 자동 예산
+  (`reviewBudget.autoBudget`, 기본 5)을 넘으면 사람 예외 손기록이 있어야 진행, 하드캡(`reviewBudget.hardCap`,
+  기본 8)에서 완전 차단합니다. `req.config.json`의 `reviewBudget`로 조정합니다 — 무한 재리뷰 루프를 막습니다.
+- **리뷰 배칭** — 한 라운드에서 여러 P1을 함께 반환하도록 유도해 라운드 수를 줄입니다.
+- **대체 REQ lineage** — 미수렴 REQ를 사람 결정(`human-resolution`)으로 종료하고 `req:new --successor-of <REQ>`로
+  부모 이력을 보존한 대체 REQ를 만듭니다.
+
+### Design delta review
+
+- **design 재리뷰가 delta로 동작** — 승인된 설계 baseline 이후 **변경된 문서만** 심사하도록 리뷰 프롬프트를
+  구성합니다. 변경 문서는 `[변경됨]`, 미변경 문서는 `[승인 baseline]`으로 표시하고, "변경분·직접 영향만 심사,
+  승인 영역 재심사 금지" 계약을 리뷰어에게 겁니다. 미변경 문서 본문은 생략해 토큰을 절감합니다 — 승인 후
+  작은 편집이 전체 재리뷰를 유발해 승인이 되돌려지던 문제를 줄입니다.
+- **full review escalation** — 변경이 너무 근본적이라 delta로 판단할 수 없으면 리뷰어가 `full_review_requested`로
+  전체 재리뷰를 요청할 수 있습니다(다음 라운드가 full 모드로 전환). `reviewPersonaPath: null`이어도 delta
+  design 리뷰에는 내장 delta 계약이 주입됩니다.
+
+### 기타
+
+- **ISO 타임스탬프 달력 검증** — 손기록·evidence의 ISO 타임스탬프를 형식뿐 아니라 달력 유효성까지 검사합니다
+  (`2026-99-99T…` 같은 달력상 불가능한 값을 거부).
+
 ## 0.7.0
 
 **설치 모델이 바뀝니다 — 기존 사용자는 조치가 필요합니다.** 실행 코드와 런타임 의존성을 대상 프로젝트에 복사·주입하지 않고, `commitgate` 패키지에서 실행합니다. 프로젝트에는 거버넌스·감사 데이터만 남습니다.

package/README.en.md

@@ -57,7 +57,7 @@ git commit -m "chore: install commitgate"
 | File | Read by |
 |---|---|
 | `AGENTS.md` | Codex CLI, Cursor — **the contract** |
-| `.claude/skills/commitgate/SKILL.md` | Claude Code (auto-invoked when it matches) |
+| `.claude/skills/commitgate/SKILL.md` | Claude Code (auto-discovered — the model decides whether to use it) |
 | `.claude/commands/req.md` | Claude Code (`/req` explicit call) |
 | `.cursor/rules/commitgate.mdc` | Cursor (`alwaysApply`) |
 | `CLAUDE.md` | Claude Code (always loaded) — created only if absent |
@@ -117,7 +117,13 @@ Repeat this loop without stopping and it drives design → Codex review → impl
 
 `req:review-codex` puts `workflow/review-persona.md` in as the **first block** of the prompt. It is identical whether a human, Cursor, or Claude runs the command — it does not live where an agent can forget it. If the file is missing or empty, the review stops fail-closed.
 
-Edit it for your project, or point `reviewPersonaPath` in `req.config.json` at a different file. Set it to `null` to disable.
+Edit it for your project, or point `reviewPersonaPath` in `req.config.json` at a different file. Set it to `null` to disable — but **delta design reviews still inject the built-in delta contract** (the contract that tells the reviewer to re-check only what changed since the approved baseline, so it is attached regardless of the configured persona).
+
+### Design re-reviews narrow to a delta
+
+Once a design is approved, CommitGate remembers that snapshot of the design docs (default `00/01/02`, configurable via `designDocs`) as a baseline. When you then edit the design and re-review, the prompt is built so the reviewer assesses **only the changed documents and their direct impact**. Changed docs are tagged `[변경됨 — 심사 대상]` (changed — under review), unchanged docs `[승인 baseline — 변경 없음, 참조]` (approved baseline — unchanged, for reference), with a contract not to re-litigate the approved areas. Unchanged docs carry only an omission marker instead of their body, to save tokens. This reduces the failure mode where a small post-approval edit triggered a full re-review and the approval got reverted.
+
+If a change is too fundamental to judge as a delta, the reviewer requests a full re-review with `full_review_requested: "yes"` (which must come with `commit_approved: "no"`). The baseline is then cleared so the next design review returns to full mode; once that design is approved again, a new baseline is captured and delta review resumes.
 
 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.
 
@@ -133,6 +139,8 @@ CommitGate is designed to block **unreviewed changes from being committed**, not
 - If Codex CLI is missing or fails, the workflow fails instead of silently passing.
 - Review exit codes are outcome-based: `0` approved, `1` invalid/fail-closed, `2` blocked/no actionable findings, `3` needs fix.
 - A no-findings/no-approval response is BLOCKED, not NEEDS_FIX, so agents must not loop on it.
+- Re-review attempts are counted per open `(review_kind, phase_id)` review series. With `{ autoBudget: 5, hardCap: 8 }`, rounds 1–5 run automatically, rounds 6–8 each require a human exception record, and once `hardCap` is spent the next attempt (round 9 onward) is blocked even with an exception — this prevents infinite re-review loops. An approval closes the series; if a human terminates an unconverged series with a `human-resolution`, automatic resumption for that key is stopped.
+- The reviewer returns every P1 it finds in a single call together in `findings[]` (batching). This avoids the serial one-finding-per-round flow that inflated review rounds — it does not lower the P1 bar; it just stops deferring already-known P1s to a later round.
 - During install, existing `cross-spawn` versions below the verified floor warn by default and fail with `--strict`.
 - Approval responses and evidence are kept under `workflow/REQ-.../responses/`.
 
@@ -162,8 +170,57 @@ So that you do not miscalculate where your real defenses are:
 | `.claude/skills/commitgate/SKILL.md` | Claude Code skill (pointer) |
 | `.claude/commands/req.md` | `/req` slash command (pointer) |
 | `.cursor/rules/commitgate.mdc` | Cursor rule (pointer) |
+| `.claude/skills/commitgate-*/SKILL.md` | **Companion Skills** — four of them, see below (existing files preserved) |
 | `package.json` scripts | `req:new`·`req:next`·`req:review-codex`·`req:doctor`·`req:commit` = `commitgate <verb>` (missing keys only) |
 
+### Companion Skills
+
+CommitGate is a **governance layer** — `req:next` computes the next action, and review/approval/evidence gate the commit.
+What was missing was **method**: how to sharpen a vague request, how to write the test first, how to corner a bug.
+Four skills, adapted from Matt Pocock's public skills (MIT) to fit CommitGate's authority boundaries, ship with it.
+
+| Skill | When |
+|---|---|
+| `commitgate-discovery` | **Before** `req:new` — turn a vague request into a REQ Brief. **User-invoked** |
+| `commitgate-tdd` | When `req:next` returns `AGENT` — Red → Green → Refactor → stage |
+| `commitgate-diagnosing-bugs` | Bugs, regressions, perf — feedback loop → reproduce/minimise → hypothesise → instrument → fix |
+| `commitgate-research` | External technology choices — primary sources, findings with citations and limits |
+
+**Auto-discovered, model-invoked.** The harness **discovers** skills automatically, but **the model decides**
+whether to use one — that is probabilistic, so don't expect a skill to always fire. In Claude Code you can also
+invoke one directly with `/commitgate-<name>`. On other harnesses, use whatever invocation that harness offers,
+or follow the entry flow in `AGENTS.md`.
+
+**Suggested flow**: `commitgate-discovery` to sharpen the request → `/req` (Claude Code) or the `AGENTS.md` entry
+flow → `req:new` → repeat `req:next`.
+
+#### Boundaries — read this
+
+- 🔴 **`AGENTS.md` is the contract.** Skills carry **method**, not contract.
+  Without the skills installed, the **core workflow behaves identically**.
+- 🔴 **Skill output is not approval evidence.** Neither a companion skill's output nor the result of running
+  Matt's external skills separately is **approval evidence** for CommitGate or Codex. Running the review, judging
+  approval, transitioning state, and committing are **CommitGate's alone**, and `req:next` is the authority on
+  what comes next.
+- Skills are **cooperative text** — a skill doesn't block a commit; CommitGate's gate does.
+
+#### Install, preservation, options
+
+- **`--no-agent-entrypoints`**: skips the whole `.claude/` layer (including the four companion skills).
+- **Existing files preserved (seed-once)**: skills are **meant to be edited**. A skill you modified is
+  **not overwritten, even with `--force`.** `AGENTS.md`, `CLAUDE.md`, and `workflow/.gitignore` follow the same policy.
+- **gitignore warning**: if `.claude/` is gitignored, the skills never reach a teammate's fresh clone.
+  Install still proceeds, but CommitGate **warns** and tells you how to track them. **`--strict` stops before installing.**
+- **Coexists with third-party skills**: third-party `tdd`, `grill-me`, etc. live at `.claude/skills/<name>/`, companions at
+  `.claude/skills/commitgate-<name>/` — **different paths, so neither touches the other.**
+
+#### Attribution
+
+Adapted from Matt Pocock's MIT-licensed public skills at baseline SHA `d574778f94cf620fcc8ce741584093bc650a61d3`
+and **included as package payload**. CommitGate **does not run or depend on any external skill installer** at
+runtime — these are pinned copies inside the package. Each SKILL.md carries the full MIT notice; see
+`skills/ATTRIBUTION.md` in the package for details.
+
 ### What it does **not** install
 
 | Item | Where it lives instead |
@@ -236,6 +293,29 @@ npx commitgate migrate --apply # rewrites only the req:* scripts in package.json
 
 **Reproducibility**: the review model/effort pins in `req.config.json`, plus the schemas and persona, stay in your project, so past review inputs are reproducible from git history. Runtime versions are pinned by your lockfile — **commit `package-lock.json`** (or the pnpm/yarn equivalent).
 
+### Companion Skills discovery scope
+
+**Installation is identical everywhere.** What follows is about whether a harness **discovers** those files.
+
+| harness | Discovery |
+|---|---|
+| **Claude Code** | Reads `.claude/skills/<name>/SKILL.md` natively |
+| **Cursor (editor)** | Reads `.claude/skills` as a compatibility path |
+| **Cursor (CLI)** | ⚠️ **May differ by version and run mode — not guaranteed** |
+| **Codex** | **Out of product scope** — no companion entrypoint is installed. In CommitGate, Codex is the **Reviewer**; these four are **Builder aids** |
+
+⚠️ **This is based on vendor primary documentation — the CommitGate team did not verify it empirically.**
+Checked **2026-07-17** on win32 x64 / Node v20.19.5. If a vendor changes behaviour, this table goes stale.
+
+⚠️ **We do not claim Cursor CLI is either supported or unsupported.** Cursor announced Agent Skills for both
+editor and CLI, but discovery via the `.claude/skills` compatibility path is reported to differ by version and
+run mode, and we could not verify it. If discovery doesn't happen, **the core workflow is unaffected** — skills
+are a quality aid, and `AGENTS.md` is the contract.
+
+We do **not** double-install into `.cursor/skills` to work around this: that path's CLI behaviour is also
+uncertain, and the same content in two places invites drift. If the vendor fixes it, it works **with no change
+on our side** — same path.
+
 ---
 
 ## Removing CommitGate
@@ -395,7 +475,7 @@ npm run req:commit -- 2026-001 --run --message-file commit-message.txt
 | `npx commitgate migrate [--apply]` | Move an older vendored install to the runtime package (plan-only by default, non-destructive) |
 | `npx commitgate uninstall` | Preview the removal plan (read-only — deletes nothing) |
 | `npm uninstall -D commitgate` | Remove the runtime |
-| `npm run req:new -- <slug> --run` | Create a REQ ticket, branch, and design docs |
+| `npm run req:new -- <slug> --run [--successor-of <REQ-id>]` | Create a REQ ticket, branch, and design docs. `--successor-of` creates a replacement REQ (see below) |
 | `npm run req:next -- <id> [--json]` | **Compute the next action** (read-only) |
 | `npm run req:review-codex -- <id> --kind design --run` | Review the design |
 | `npm run req:review-codex -- <id> --kind phase --phase <p> --run` | Review the implementation |
@@ -410,6 +490,8 @@ pnpm req:next 2026-002           # pnpm
 yarn req:next 2026-002           # yarn
 ```
 
+**Replacement REQ (`--successor-of`)**: only when a human has terminated a review series with a `human-resolution` **replace** decision can you create a replacement REQ that preserves the parent's lineage (total attempts and the resolution record) via `req:new --successor-of <REQ-id>`. If the parent has no valid replace resolution, ticket creation fails closed — this does not block ordinary new-REQ creation.
+
 ---
 
 ## Configuration
@@ -422,9 +504,10 @@ Defaults are enough for most projects. If needed, edit `req.config.json` in the
 | `ticketRoot` | `"workflow"` | REQ ticket directory |
 | `packageManager` | auto-detected | `npm`, `pnpm`, or `yarn` |
 | `designDocs` | `00/01/02` docs | Design document filenames |
-| `reviewPersonaPath` | `"workflow/review-persona.md"` | First block of the review prompt. `null` disables it |
+| `reviewPersonaPath` | `"workflow/review-persona.md"` | First block of the review prompt. `null` disables it — but delta design reviews still inject the built-in delta contract |
 | `reviewModel` | `"gpt-5.6-terra"` | codex review model (pinned via `-c model=`). `null` inherits your global codex config |
 | `reviewReasoningEffort` | `"high"` | codex review reasoning effort. One of `none`, `minimal`, `low`, `medium`, `high`, `xhigh`. `null` inherits the global setting |
+| `reviewBudget` | `{ "autoBudget": 5, "hardCap": 8 }` | Re-review attempt budget for an open `(review_kind, phase_id)` review series. With the defaults, rounds 1–5 run automatically, rounds 6–8 each require a human exception record bound to that series and round, and once `hardCap` is spent the next attempt (round 9 onward) is blocked even with an exception. `hardCap ≤ 8`, `autoBudget ≤ hardCap` |
 
 Empty `branchPrefix` values and paths that escape the project root are rejected.
 

package/README.md

@@ -57,7 +57,7 @@ git commit -m "chore: install commitgate"
 | 파일 | 읽는 도구 |
 |---|---|
 | `AGENTS.md` | Codex CLI, Cursor — **계약 정본** |
-| `.claude/skills/commitgate/SKILL.md` | Claude Code (요청에 맞으면 자동 발동) |
+| `.claude/skills/commitgate/SKILL.md` | Claude Code (자동 발견 — 호출은 모델 판단) |
 | `.claude/commands/req.md` | Claude Code (`/req` 명시 호출) |
 | `.cursor/rules/commitgate.mdc` | Cursor (`alwaysApply`) |
 | `CLAUDE.md` | Claude Code (항상 로드) — 부재 시에만 생성 |
@@ -117,7 +117,13 @@ npm run req:next -- 2026-002
 
 `req:review-codex`는 `workflow/review-persona.md`를 프롬프트 **첫 블록**으로 넣습니다. 사람이 직접 실행하든, Cursor가 실행하든, Claude가 실행하든 동일합니다 — 에이전트가 잊을 수 있는 자리에 두지 않습니다. 파일이 없거나 비어 있으면 리뷰가 fail-closed로 멈춥니다.
 
-내용을 프로젝트에 맞게 고치거나, `req.config.json`의 `reviewPersonaPath`로 다른 파일을 지정할 수 있습니다. `null`로 두면 비활성화됩니다.
+내용을 프로젝트에 맞게 고치거나, `req.config.json`의 `reviewPersonaPath`로 다른 파일을 지정할 수 있습니다. `null`로 두면 비활성화됩니다 — 다만 **delta design 리뷰에는 내장 delta 계약이 주입된다**(승인 baseline 이후 변경분만 재검토하도록 리뷰어에게 거는 계약이라, 설정 persona와 무관하게 붙습니다).
+
+### 설계 재리뷰는 delta로 좁혀집니다
+
+설계가 한 번 승인되면 그 시점의 설계 문서(기본 `00/01/02`, `designDocs` 설정으로 변경 가능)를 baseline으로 기억합니다. 이후 설계를 고쳐 재리뷰하면, 리뷰어에게 **변경된 문서와 그 직접 영향 범위만** 심사하도록 프롬프트를 구성합니다. 변경 문서는 `[변경됨 — 심사 대상]`, 미변경 문서는 `[승인 baseline — 변경 없음, 참조]`로 표시하고, 승인된 영역을 다시 문제 삼지 말라는 계약을 겁니다. 미변경 문서는 본문 대신 생략 표식만 전달해 토큰을 아낍니다. 승인 후 작은 편집이 전체 재리뷰를 유발해 승인이 되돌려지던 문제를 줄입니다.
+
+변경이 너무 근본적이라 delta로 판단할 수 없으면 리뷰어가 `full_review_requested: "yes"`(그때 `commit_approved: "no"`)로 전체 재리뷰를 요청합니다. 그러면 baseline이 비워져 다음 설계 리뷰가 full 모드로 돌아가고, 그 설계가 다시 승인되면 새 baseline이 잡혀 delta가 재개됩니다.
 
 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)를 참고하세요.
 
@@ -133,6 +139,8 @@ CommitGate가 막는 것은 단순한 명령 실수가 아니라 **리뷰받지
 - Codex CLI가 없거나 실행에 실패하면 조용히 통과하지 않고 실패합니다.
 - 리뷰 종료코드는 outcome 기준입니다: `0` 승인, `1` 무효/fail-closed, `2` blocked(지적 없음+미승인), `3` needs-fix.
 - 지적은 없지만 승인도 없는 응답은 NEEDS_FIX가 아니라 BLOCKED이며, 에이전트는 같은 리뷰를 반복하지 않습니다.
+- 열린 `(review_kind, phase_id)` review series별로 재리뷰 시도를 계수합니다. 기본값 `{ autoBudget: 5, hardCap: 8 }`에서 1~5회차는 자동, 6~8회차는 회차마다 사람 예외 기록이 있어야 진행, `hardCap` 회를 소진하면 그 다음 시도(9회차부터)는 예외가 있어도 차단합니다 — 무한 재리뷰 루프를 막습니다. 승인되면 그 series가 닫히고, 미수렴 series를 사람이 `human-resolution`으로 종료하면 같은 키의 자동 재개가 막힙니다.
+- 리뷰어는 한 호출에서 파악한 P1을 모두 `findings[]`에 함께 반환합니다(배칭). 한 건씩 내고 재검수받는 직렬 흐름이 리뷰 라운드를 부풀리던 문제를 줄입니다 — P1 기준을 낮추는 것이 아니라, 이미 아는 P1을 다음 라운드로 미루지 않는 것입니다.
 - 설치 시 기존 `cross-spawn`이 검증 하한보다 낮으면 경고하고, `--strict`에서는 중단합니다.
 - 승인 응답과 증거 파일은 `workflow/REQ-.../responses/`에 남습니다.
 
@@ -162,8 +170,54 @@ CommitGate가 막는 것은 단순한 명령 실수가 아니라 **리뷰받지
 | `.claude/skills/commitgate/SKILL.md` | Claude Code 스킬 (포인터) |
 | `.claude/commands/req.md` | `/req` 슬래시 커맨드 (포인터) |
 | `.cursor/rules/commitgate.mdc` | Cursor 규칙 (포인터) |
+| `.claude/skills/commitgate-*/SKILL.md` | **Companion Skills** 4종 — 아래 참조 (기존 파일 보존) |
 | `package.json` 스크립트 | `req:new`·`req:next`·`req:review-codex`·`req:doctor`·`req:commit` = `commitgate <verb>` (없는 키만) |
 
+### Companion Skills
+
+CommitGate는 **거버넌스 레이어**입니다 — `req:next`가 다음 행동을 계산하고, 리뷰·승인·증거가 커밋을 게이트합니다.
+그런데 "무엇을 만들지 정리하는 법", "테스트를 어떻게 먼저 쓰는지" 같은 **방법론**은 비어 있었습니다.
+Matt Pocock의 공개 skills(MIT)를 CommitGate의 권한 경계에 맞게 적응해 4종을 함께 설치합니다.
+
+| 스킬 | 언제 |
+|---|---|
+| `commitgate-discovery` | `req:new` **전** — 모호한 요구를 REQ Brief로 정리. **사용자 호출형** |
+| `commitgate-tdd` | `req:next`가 `AGENT`일 때 — Red → Green → Refactor → stage |
+| `commitgate-diagnosing-bugs` | 버그·회귀·성능 — 피드백 루프 → 재현·최소화 → 가설 → 계측 → 수정 |
+| `commitgate-research` | 외부 기술 선택 — 1차 출처 조사, 결론·출처·한계 |
+
+**자동 발견 · 모델 판단 호출.** harness가 스킬을 자동으로 **발견**하지만, 쓸지 **판단하는 건 모델**입니다 —
+확률적이며 항상 뜬다고 기대하면 안 됩니다. Claude Code에서는 `/commitgate-<이름>`으로 **직접 호출**할 수도 있습니다.
+다른 harness에서는 그 harness가 제공하는 호출 방식을 쓰거나, `AGENTS.md`의 진입 흐름을 따르세요.
+
+**권장 흐름**: `commitgate-discovery`로 요구 정리 → `/req`(Claude Code) 또는 `AGENTS.md` 진입 → `req:new` → `req:next` 반복.
+
+#### 경계 — 반드시 알아 두세요
+
+- 🔴 **`AGENTS.md`가 계약 정본입니다.** 스킬은 **방법론**이지 계약이 아닙니다.
+  스킬을 설치하지 않아도 **핵심 워크플로는 완전히 동일하게** 동작합니다.
+- 🔴 **스킬 결과는 승인 증거가 아닙니다.** companion skills의 산출물도, 외부 Matt skills를 따로 돌린 결과도
+  CommitGate·Codex의 **승인 근거가 되지 않습니다**. 리뷰 실행·승인 판정·상태 전이·커밋은 **CommitGate만** 담당하며,
+  다음 행동은 `req:next`가 정본입니다.
+- 스킬은 **협조적 텍스트**입니다 — 스킬이 커밋을 막는 게 아니라, 막는 건 CommitGate의 게이트입니다.
+
+#### 설치·보존·옵션
+
+- **`--no-agent-entrypoints`**: `.claude/` 계층 전체를 건너뜁니다(companion 4종 포함).
+- **기존 파일 보존(seed-once)**: 스킬은 **고치라고 만든 자산**입니다. 수정한 스킬은 **`--force`로도 덮어쓰지 않습니다.**
+  `AGENTS.md`·`CLAUDE.md`·`workflow/.gitignore`도 같은 정책입니다.
+- **gitignore 경고**: `.claude/`를 gitignore하면 팀원의 fresh clone에 스킬이 전달되지 않습니다.
+  설치는 진행하되 **경고**하고 추적 방법을 안내합니다. **`--strict`면 설치 전에 중단**합니다.
+- **타사 skill과 공존**: 타사 `tdd`·`grill-me` 등은 `.claude/skills/<이름>/`, companion은 `.claude/skills/commitgate-<이름>/` —
+  **경로가 달라 서로 건드리지 않습니다.**
+
+#### 출처
+
+Matt Pocock의 MIT 공개 skills를 기준 SHA `d574778f94cf620fcc8ce741584093bc650a61d3`에서 적응해
+**패키지 payload로 포함**합니다. **외부 skill installer를 실행하거나 런타임 의존하지 않습니다** —
+패키지 안에 고정된 사본입니다. 각 SKILL.md에 MIT 고지 전문이 동행하며, 자세한 출처는 패키지의
+`skills/ATTRIBUTION.md`에 있습니다.
+
 ### 설치하지 **않는** 것
 
 | 항목 | 어디에 있나 |
@@ -241,6 +295,27 @@ npx commitgate migrate --apply # package.json 의 req:* 만 전환
 
 **재현성**: `req.config.json`의 리뷰 모델·추론강도 핀과 스키마·persona가 프로젝트에 남아 과거 리뷰 입력이 git 이력으로 재현됩니다. 런타임 버전은 **lockfile이 고정**하므로 `package-lock.json`(pnpm/yarn은 각 lockfile)을 **커밋하세요**.
 
+### Companion Skills 발견 범위
+
+**설치는 모든 환경에서 동일합니다.** 아래는 harness가 그 파일을 **발견하는지**에 대한 것입니다.
+
+| harness | 발견 |
+|---|---|
+| **Claude Code** | `.claude/skills/<이름>/SKILL.md`를 native로 읽습니다 |
+| **Cursor (editor)** | `.claude/skills`를 호환 경로로 읽습니다 |
+| **Cursor (CLI)** | ⚠️ **버전·실행 모드별 동작 차이 가능 — 보장하지 않습니다** |
+| **Codex** | **제품 범위 밖** — companion entrypoint를 설치하지 않습니다. CommitGate에서 Codex는 **Reviewer**이고 이 4종은 **Builder 보조**입니다 |
+
+⚠️ **근거는 벤더 1차 문서입니다 — CommitGate 팀이 실측한 것이 아닙니다.** 확인 시점 **2026-07-17**, 확인 환경 win32 x64 / Node v20.19.5.
+벤더가 동작을 바꾸면 이 표는 낡을 수 있습니다.
+
+⚠️ **Cursor CLI를 "지원"·"미지원" 어느 쪽으로도 단정하지 않습니다.** Cursor는 editor·CLI 양쪽의 Agent Skills 지원을
+발표했지만, `.claude/skills` 호환 경로의 CLI 발견은 버전·모드에 따라 차이가 보고돼 있고 우리는 검증하지 못했습니다.
+발견되지 않아도 **핵심 워크플로에는 영향이 없습니다** — 스킬은 품질 보조 레이어이고 계약 정본은 `AGENTS.md`입니다.
+
+우회를 위해 `.cursor/skills`에 **이중 설치하지 않습니다** — 그 경로도 CLI에서 동작이 불확실하고, 같은 내용이 두 곳에
+깔리면 drift 위험이 생깁니다. 벤더가 고치면 **우리 변경 없이** 동작합니다(같은 경로를 읽으므로).
+
 ---
 
 ## 제거하려면
@@ -400,7 +475,7 @@ npm run req:commit -- 2026-001 --run --message-file commit-message.txt
 | `npx commitgate migrate [--apply]` | 예전 vendored 설치본 → 런타임 패키지 전환 (기본: 계획만, 비파괴) |
 | `npx commitgate uninstall` | 제거 계획 확인 (읽기 전용 — 아무것도 지우지 않음) |
 | `npm uninstall -D commitgate` | 런타임 제거 |
-| `npm run req:new -- <slug> --run` | REQ 티켓, 브랜치, 설계문서 생성 |
+| `npm run req:new -- <slug> --run [--successor-of <REQ-id>]` | REQ 티켓, 브랜치, 설계문서 생성. `--successor-of`는 대체 REQ (아래 참조) |
 | `npm run req:next -- <id> [--json]` | **다음 행동 계산** (읽기 전용) |
 | `npm run req:review-codex -- <id> --kind design --run` | 설계 리뷰 |
 | `npm run req:review-codex -- <id> --kind phase --phase <p> --run` | 구현 리뷰 |
@@ -415,6 +490,8 @@ pnpm req:next 2026-002           # pnpm
 yarn req:next 2026-002           # yarn
 ```
 
+**대체 REQ (`--successor-of`)**: 어떤 review series가 미수렴이라고 판단해 사람이 그것을 `human-resolution`으로 **대체(replace)** 종결한 경우에만, `req:new --successor-of <REQ-id>`로 부모 이력(시도 합계·종결 기록)을 보존한 대체 REQ를 만들 수 있습니다. 부모에 유효한 replace 종결 기록이 없으면 티켓 생성이 fail-closed로 막힙니다 — 일반적인 새 REQ 생성 자체를 도구가 막는 것은 아닙니다.
+
 ---
 
 ## 설정
@@ -427,9 +504,10 @@ yarn req:next 2026-002           # yarn
 | `ticketRoot` | `"workflow"` | REQ 티켓 폴더 |
 | `packageManager` | 자동 감지 | `npm`, `pnpm`, `yarn` |
 | `designDocs` | `00/01/02` 문서 | 설계 문서 파일명 |
-| `reviewPersonaPath` | `"workflow/review-persona.md"` | 리뷰 프롬프트 첫 블록. `null`이면 비활성 |
+| `reviewPersonaPath` | `"workflow/review-persona.md"` | 리뷰 프롬프트 첫 블록. `null`이면 비활성 — 단 delta design 리뷰에는 내장 delta 계약이 주입된다 |
 | `reviewModel` | `"gpt-5.6-terra"` | codex 리뷰 모델(`-c model=`로 고정). `null`이면 codex 전역 설정을 상속 |
 | `reviewReasoningEffort` | `"high"` | codex 리뷰 추론강도. `none`·`minimal`·`low`·`medium`·`high`·`xhigh` 중 하나. `null`이면 전역 상속 |
+| `reviewBudget` | `{ "autoBudget": 5, "hardCap": 8 }` | 열린 `(review_kind, phase_id)` review series의 재리뷰 시도 예산. 기본값 기준 1~5회차는 자동, 6~8회차는 회차마다 그 series·회차에 바인딩된 사람 예외 기록이 있어야 진행, `hardCap` 회를 이미 소진하면 그 다음 시도(9회차부터)는 예외가 있어도 차단. `hardCap ≤ 8`·`autoBudget ≤ hardCap` |
 
 빈 `branchPrefix`나 프로젝트 밖으로 나가는 경로는 거부됩니다.