@tienne/gestalt 0.80.0 → 0.81.1

package/dist/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tienne/gestalt",
-  "version": "0.80.0",
+  "version": "0.81.1",
   "description": "TypeScript AI Development Harness - Gestalt psychology-driven requirement clarification",
   "repository": {
     "type": "git",

package/dist/plugin/review-agents/writing-reviewer/AGENT.md

@@ -56,7 +56,7 @@ git diff --word-diff=porcelain -- <파일>
 **정적 탐지를 먼저 돌립니다.** 정규식으로 잡히는 룰은 사람이 눈으로 세는 것보다 정확합니다.
 
 ```bash
-pnpm tsx bin/gestalt.ts humanize-check --before <파일> --after <파일> --register doc --json
+gestalt humanize-check --before <파일> --after <파일> --register doc --json
 ```
 
 같은 파일을 `--before`와 `--after`에 둘 다 넘기면 윤문 전후 비교가 아니라 그 파일에 남아 있는 S1 패턴을 세어 줍니다. 잡히는 룰은 21개뿐이니 나머지는 읽고 판정합니다.

package/dist/plugin/role-agents/code-review-writer/AGENT.md

@@ -92,6 +92,12 @@ voice 모델을 따른다. 초안 작성 후 반드시 [`../_shared/references/a
 [`../_shared/references/ai-tell-quick-rules.md`](../_shared/references/ai-tell-quick-rules.md)이며
 인라인 코멘트엔 특히 다음을 적용한다.
 
+**아래 표가 인라인 코멘트에 걸리는 자리를 추려 담고 있으니 첫 판에 그 파일을 통째로 열지
+않는다.** 부르는 쪽이 어투 검사 결과를 프롬프트에 실어 재작성을 시켰으면 그때도 마찬가지다 —
+걸린 룰의 처방이 그 출력에 이미 들어 있어서 44KB를 다시 읽어도 같은 내용이다. 확인해야 할
+ID가 따로 있으면 그 행만 찾아 읽는다. `author-voice.md`는 다르다 — 코멘트를 쓰는 기준이라
+초안을 쓰기 전에 읽는다.
+
 **제거할 패턴 (S1 — 반드시 교정)**
 
 | 패턴 | 예시 | 교정 |

package/dist/plugin/role-agents/humanize-monolith/AGENT.md

@@ -84,6 +84,8 @@ gestalt humanize-scan --file <원문> --register <doc|chat|report>
 종료 코드로도 답한다. 걸린 게 있으면 0, 어투는 깨끗한데 맞춤법만 걸리면 11, 탐지기가 가리는 범위에서 0건이면 10이다. 11이면 어투는 그대로 두고 맞춤법 절만 고쳐서 낸다.
 파일이 없으면 3이다. 셸에서 분기할 때 stdout 을 파싱하지 않아도 된다.
 
+`--file`은 여러 번 줄 수 있다. 초안이 여러 개면 한 번에 넘겨 한 프로세스에서 각각 독립적으로 스캔한다.
+
 스캔이 내놓는 것만 본다.
 
 - **걸린 룰**: ID, 건수, 실제 표현, 처방이 함께 나온다. 이번 윤문의 작업 목록이다
@@ -100,6 +102,12 @@ gestalt humanize-scan --file <원문> --register <doc|chat|report>
 인라인 텍스트만 받아 스캔을 못 돌리는 경우에만 룰북을 직접 읽는다. 이때도 말투에 해당하는
 S1부터 본다. 전 카테고리를 훑지 않는다.
 
+**부르는 쪽이 스캔 결과를 프롬프트에 실어 보냈으면 `ai-tell-quick-rules.md`를 다시 열지
+않는다.** 걸린 룰의 처방이 그 출력에 이미 들어 있어서 같은 내용을 44KB 더 읽는 셈이 된다.
+`author-voice.md`는 다르다 — 보존 기준은 스캔이 내놓는 값이 아니라 필요하면 그대로 읽는다.
+다만 '탐지기가 못 가리는 S1' 줄은 ID만 오고 처방이 안 딸려 온다. 그 ID를 확인해야 하면
+`ai-tell-quick-rules.md`에서 해당 행만 찾아 읽고 파일 전체를 읽지 않는다.
+
 ### 1단계 — 탐지
 
 스캔 결과에 탐지기가 못 가리는 S1을 더해 이번 작업 목록을 확정한다.

package/dist/plugin/skills/_shared/cli-launcher.md

@@ -0,0 +1,45 @@
+# gestalt CLI를 어떻게 부르는지 먼저 판정한다
+
+이 문서는 여러 스킬이 공유하는 규칙이다. `gestalt` CLI(`humanize-scan`, `pr`, `review-loop`, `setup` 등)를 셸로 부르는 단계에서 적용한다.
+
+## 왜 필요한가
+
+플러그인으로 설치되면 호스트가 복사해 가는 건 `plugin/` 아래뿐이다. `bin/`도 `package.json`도 `node_modules`도 그 안에 없다. 그래서 스킬 본문에 `pnpm tsx bin/gestalt.ts ...`만 적혀 있으면 게슈탈트 레포 밖에서는 그 명령이 원리상 안 돈다.
+
+그때 읽는 쪽이 하는 말이 "의존성이 안 깔려 있어서 못 돌립니다"다. 실제로는 전역 `gestalt`가 깔려 있어 돌릴 수 있는데도 스킬이 적어준 형태 하나가 막혀서 포기한다. 어투 검사처럼 **필수 검사인 단계가 이렇게 조용히 건너뛰어지면** 막으려던 문장이 그대로 나간다.
+
+그래서 호출 형태를 스킬마다 박아두지 않고 한 번 판정해서 쓴다.
+
+## 판정
+
+CLI를 처음 부르기 전에 한 번 돌린다.
+
+```bash
+if gestalt --version >/dev/null 2>&1; then
+  echo "OK gestalt"
+elif pnpm tsx bin/gestalt.ts --version >/dev/null 2>&1; then
+  echo "OK pnpm"
+else
+  echo "MISSING"
+fi
+```
+
+- **`OK gestalt`** — 스킬 본문의 예시를 그대로 쓴다. 본문은 전부 `gestalt ...` 형태로 적혀 있다.
+- **`OK pnpm`** — 게슈탈트 레포 안이라는 뜻이다. 그 뒤로 모든 호출의 `gestalt`를 `pnpm tsx bin/gestalt.ts`로 바꿔 쓴다.
+- **`MISSING`** — 아래 "없을 때"를 따른다.
+
+한 번 확인하고 그 뒤로는 같은 형태를 쓴다. 단계마다 다시 찌르지 않는다.
+
+**쓰려는 하위 명령이 최근에 생긴 것이면 그 하위 명령으로 찌른다.** `--version`은 설치본이 뒤처져 하위 명령만 없는 경우를 못 잡는다. 그 상태로 라운드를 돌다 `unknown option`으로 죽으면 앞선 단계가 통째로 헛돈다.
+
+**명령을 변수에 담아 함수로 넘기지 않는다.** zsh는 인용 안 한 변수 전개에서 단어 분리를 안 해 `$cmd`가 통째로 명령 이름이 된다. 실제로 깔려 있어도 `MISSING`이 나온다. 같은 코드가 bash에서는 도는 탓에 눈으로는 안 걸린다.
+
+## 없을 때
+
+`MISSING`이면 **그 단계가 필수 검사인지로 갈린다.**
+
+- **필수 검사면 멈춘다.** 어투 검사(`humanize-scan`)가 그렇다. 검사를 못 돌린 걸 통과로 읽으면 검사가 없는 것과 같다. 무엇을 못 돌렸는지와 `npm i -g @tienne/gestalt`를 함께 알리고 사용자가 그대로 진행할지 정하게 둔다.
+- **판정에 쓰는 수를 그 명령이 내면 멈춘다.** `review-loop`처럼 모든 단계가 한 명령에 매달린 자리다.
+- **그 밖에는 알리고 건너뛴다.** 없다고 스킬 전체를 막을 이유는 없다. 대신 완료 보고에 어느 단계를 안 돌렸는지 적는다.
+
+어느 쪽이든 **직접 흉내내지 않는다.** 스캔 결과를 지어내거나 룰북을 눈으로 훑어 "깨끗합니다"로 답하지 않는다 ([`tool-availability.md`](./tool-availability.md)와 같은 규칙이다).

package/dist/plugin/skills/local-pr/SKILL.md

@@ -56,7 +56,7 @@ outputs:
 
 git 저장소이기만 하면 된다. 인증도 원격도 안 본다.
 
-명령은 `gestalt pr ...`이다. 게슈탈트 레포 안에서 돌 때는 전역 설치가 없을 수 있으므로 `pnpm tsx bin/gestalt.ts pr ...`로 부른다. 한 번 확인하고 그 뒤로는 같은 형태를 쓴다.
+명령은 `gestalt pr ...`이다. 부르는 형태는 [`../_shared/cli-launcher.md`](../_shared/cli-launcher.md)의 판정을 따른다 — 게슈탈트 레포 안에서는 전역 설치가 없을 수 있어 형태가 갈린다. 한 번 확인하고 그 뒤로는 같은 형태를 쓴다.
 
 `--json`을 붙이면 객체만 나온다. 에이전트가 값을 읽어야 하는 자리에서는 이쪽을 쓴다.
 

package/dist/plugin/skills/pr/SKILL.md

@@ -30,6 +30,9 @@ outputs:
 # PR Skill
 
 > **에이전트 tier로 모델 고르기** → [`../_shared/agent-model.md`](../_shared/agent-model.md)
+>
+> **`gestalt` CLI를 부르는 형태** → [`../_shared/cli-launcher.md`](../_shared/cli-launcher.md)
+> 본문의 셸 예시는 `gestalt ...`입니다. 게슈탈트 레포 안에서는 `pnpm tsx bin/gestalt.ts ...`로 바꿔 부릅니다. description 어투 검사가 이 CLI에 매달려 있고 **그건 필수 검사라 못 돌리면 멈춥니다.**
 레포의 PR 규칙을 먼저 탐색하고 미니 인터뷰로 컨텍스트를 수집한 뒤, diff를 분석해 레포 규칙에 맞는 PR description을 생성하고 `gh pr create`로 제출합니다.
 
 ## 사용 방법
@@ -287,7 +290,21 @@ echo "$scanTmp"
 윤문된 제목과 본문을 합쳐 `"$scanTmp/description.md"`에 씁니다.
 
 ```bash
-pnpm tsx bin/gestalt.ts humanize-scan --file "$scanTmp/description.md" --register report
+if gestalt --version >/dev/null 2>&1; then
+  echo "OK gestalt"
+elif pnpm tsx bin/gestalt.ts --version >/dev/null 2>&1; then
+  echo "OK pnpm"
+else
+  echo "MISSING"
+fi
+```
+
+`OK pnpm`이면 아래 호출의 `gestalt`를 `pnpm tsx bin/gestalt.ts`로 바꿔 부릅니다.
+
+**`MISSING`이면 검사를 건너뛰지 않고 멈춥니다.** 못 돌린 걸 통과로 읽으면 검사가 없는 것과 같습니다. `npm i -g @tienne/gestalt`를 함께 알리고 그대로 진행할지 사용자가 정하게 둡니다.
+
+```bash
+gestalt humanize-scan --file "$scanTmp/description.md" --register report
 ```
 
 - **10 / 11** — 통과입니다. 11이면 어투는 안 걸렸고 맞춤법만 고칩니다.

package/dist/plugin/skills/review/SKILL.md

@@ -59,6 +59,9 @@ execute 세션 없이 PR, 브랜치, 커밋의 변경사항을 직접 리뷰 파
 >
 > **도구가 없을 때** → [`../_shared/tool-availability.md`](../_shared/tool-availability.md)
 >
+> **`gestalt` CLI를 부르는 형태** → [`../_shared/cli-launcher.md`](../_shared/cli-launcher.md)
+> 본문의 셸 예시는 전부 `gestalt ...`입니다. 게슈탈트 레포 안에서는 `pnpm tsx bin/gestalt.ts ...`로 바꿔 부릅니다. 어투 검사(1.5, 4.5, 4.7단계)가 이 CLI에 매달려 있고 **그 셋은 필수 검사라 못 돌리면 멈춥니다.**
+>
 > **에이전트 tier로 모델 고르기** → [`../_shared/agent-model.md`](../_shared/agent-model.md)
 >
 > **에이전트를 서브에이전트로 위임하기** → [`../_shared/agent-delegation.md`](../_shared/agent-delegation.md)
@@ -95,7 +98,7 @@ execute 세션 없이 PR, 브랜치, 커밋의 변경사항을 직접 리뷰 파
 `gestalt pr list`에는 브랜치 필터가 없습니다. `--status`만 받습니다. `headRef`도 못 믿습니다 — 워크트리에서 detached로 만든 PR은 거기에 브랜치 이름이 아니라 sha가 들어갑니다. 그래서 이름이 아니라 커밋으로 가릅니다.
 
 ```bash
-pnpm tsx bin/gestalt.ts pr --json list
+gestalt pr --json list
 git merge-base --is-ancestor <PR의 headSha> HEAD   # 종료 코드 0이면 내 브랜치의 PR
 ```
 
@@ -128,7 +131,7 @@ id를 직접 주면 아래 1번의 첫 수단이 브랜치를 안 따지고 잡
 **명시 지정이 가장 셉니다. 그다음이 안 끝난 로컬 PR입니다.** 아래 순서대로 훑어 처음 걸리는 것을 택하고 나머지는 보지 않습니다.
 
 1. **로컬 지정** — `local` 입력이 true거나(`--local` 플래그) `target`이 로컬 PR id 형식(`gestalt pr list`에 뜨는 id)인 경우입니다. 이때는 로컬 PR을 두 수단으로 찾습니다.
-   - `target`에 id가 있으면 먼저 `pnpm tsx bin/gestalt.ts pr --json show <id>`로 실제 존재를 확인합니다. 사용자가 id를 짚었으면 그 PR이 현재 브랜치 것인지는 안 따집니다.
+   - `target`에 id가 있으면 먼저 `gestalt pr --json show <id>`로 실제 존재를 확인합니다. 사용자가 id를 짚었으면 그 PR이 현재 브랜치 것인지는 안 따집니다.
    - id가 없거나(`--local`만 준 경우) `show`가 빈 결과를 내면 위의 가리는 법으로 현재 브랜치의 로컬 PR을 찾습니다.
    - 둘 중 하나로 찾으면 `local`입니다. 어느 쪽으로도 못 찾으면 그 사실을 한 줄 알리고 2번으로 내려갑니다.
 
@@ -226,7 +229,7 @@ git diff --name-only <commit>^ <commit>
 **`target`이 로컬 PR id 형식(8자리 16진수)이면 git이 그 값을 리비전으로 못 읽습니다.** `git diff main...<id>`는 `fatal: ambiguous argument`로 죽습니다. 이 경우는 PR에서 sha를 받아 옵니다.
 
 ```bash
-pnpm tsx bin/gestalt.ts pr --json show <id>          # baseSha, headSha
+gestalt pr --json show <id>          # baseSha, headSha
 git diff --name-only <baseSha>..<headSha>            # 점 두 개 — pr diff와 같은 범위
 ```
 
@@ -263,14 +266,14 @@ git diff --name-only <baseSha>..<headSha>            # 점 두 개 — pr diff
 리뷰어의 워크트리는 자기 브랜치에 올라타 있어서 PR 코드가 거기 없습니다. 떼어냅니다.
 
 ```bash
-pnpm tsx bin/gestalt.ts pr checkout <id> --json   # { path, created, headSha }
+gestalt pr checkout <id> --json   # { path, created, headSha }
 ```
 
 `path`로 옮겨 가 테스트를 돌리고 핵심 줄을 일부러 깨봅니다. 같은 PR을 두 번 불러도 워크트리는
 하나이고 그 안의 변경은 살아남습니다. 끝나면 정리합니다.
 
 ```bash
-pnpm tsx bin/gestalt.ts pr checkout <id> --remove --json
+gestalt pr checkout <id> --remove --json
 ```
 
 정리 결과는 `status`로 분기합니다 — 산문 `reason`을 부분 문자열로 긁지 않습니다.
@@ -306,7 +309,7 @@ pnpm tsx bin/gestalt.ts pr checkout <id> --remove --json
 - `local` — 1단계나 판별 1번의 `pr --json show <id>` 결과에 `title`과 `body`가 이미 들어 있습니다(`PullRequest` 전체가 그대로 나옵니다). 조회를 안 거쳐 왔으면 여기서 한 번 부릅니다.
 
   ```bash
-  pnpm tsx bin/gestalt.ts pr --json show <id>   # title, body
+  gestalt pr --json show <id>   # title, body
   ```
 
 - `none` — 이 단계를 건너뛰고 `prContext`를 `"(없음)"`으로 둡니다. 브랜치나 커밋 범위 리뷰에는 본문이랄 게 없습니다.
@@ -364,6 +367,8 @@ Agent {
 
 1단계에서 수집한 변경 파일을 바탕으로 변경의 기획적 의도와 동작 변화를 분석한다.
 
+**이 호출은 따로 내보내지 않고 3단계의 병렬 메시지에 함께 담아 띄운다.** 아래 프롬프트가 받는 입력은 diff와 PR 제목/본문뿐이고 리뷰어의 판정(`mergedIssues` 등)은 받지 않으므로 리뷰어를 먼저 기다릴 이유가 없다. 실행 순서만 앞당겨질 뿐 **표시 순서는 그대로다** — 어투 검사는 파도가 다 돌아온 뒤에 하고 문서도 리뷰 결과보다 먼저 사용자에게 보여준다(결과 표시 절 참고).
+
 **서브에이전트에 위임한다.** 메인 세션에서 `ges_agent get`을 하지 않는다.
 
 ```
@@ -400,7 +405,7 @@ Agent {
 
 #### 기획 컨텍스트 어투 검사 (필수)
 
-사용자에게 표시하기 전에 스캔한다. `change-context-writer`가 자체 humanize를 거쳐도 별도 검증 없이 그대로 나가면, 리포트(4.5단계)보다 먼저 보이는 이 문서가 유일하게 어투 검사를 안 거친 자리로 남는다.
+사용자에게 표시하기 전에 스캔한다. `change-context-writer`가 자체 humanize를 거쳐도 별도 검증 없이 그대로 나가면, 리포트(4.5단계)보다 먼저 보이는 이 문서가 유일하게 어투 검사를 안 거친 자리로 남는다. **이 검사는 3단계 파도가 전부 돌아온 뒤에 한다** — 병렬로 띄운 호출이라고 검사까지 다른 결과와 뒤섞어 하지 않는다.
 
 ```bash
 scanTmp="$(cd "$(git rev-parse --git-common-dir)" && pwd)/gestalt-review/<PR 식별자 또는 target>/$$"
@@ -411,7 +416,21 @@ echo "$scanTmp"
 작성된 컨텍스트 문서를 `"$scanTmp/change-context.md"`에 쓴다 (파일 쓰기 도구 사용, 셸로 넘기지 않는다).
 
 ```bash
-pnpm tsx bin/gestalt.ts humanize-scan --file "$scanTmp/change-context.md" --register report
+if gestalt --version >/dev/null 2>&1; then
+  echo "OK gestalt"
+elif pnpm tsx bin/gestalt.ts --version >/dev/null 2>&1; then
+  echo "OK pnpm"
+else
+  echo "MISSING"
+fi
+```
+
+`OK pnpm`이면 아래 호출의 `gestalt`를 `pnpm tsx bin/gestalt.ts`로 바꿔 부릅니다. 한 번 확인하고 그 뒤로는(4.5, 4.7단계 포함) 같은 형태를 씁니다.
+
+**`MISSING`이면 검사를 건너뛰지 않고 멈춥니다.** 못 돌린 걸 통과로 읽으면 검사가 없는 것과 같습니다. `npm i -g @tienne/gestalt`를 함께 알리고 그대로 진행할지 사용자가 정하게 둡니다.
+
+```bash
+gestalt humanize-scan --file "$scanTmp/change-context.md" --register report
 ```
 
 - **10 / 11** — 통과. 11이면 어투는 두고 맞춤법만 고친다.
@@ -451,7 +470,9 @@ ges_execute {
 
 ### 3단계: 에이전트별 리뷰 제출 (review_submit × N)
 
-**에이전트마다 서브에이전트를 하나씩 띄웁니다.** 리뷰어끼리 서로 볼 이유가 없으므로 **한 메시지에 전부 담아 병렬로 돌립니다.** 메인 세션에서 `ges_agent get`을 하지 않습니다.
+**에이전트마다 서브에이전트를 하나씩 띄웁니다.** 리뷰어끼리 서로 볼 이유가 없으므로 **한 메시지에 전부 담아 병렬로 돌립니다.** 이 메시지에는 리뷰어들뿐 아니라 **1.5단계 change-context-writer 호출과 3.5단계 continuity-judge 호출도 함께 담습니다.** 셋 다 입력으로 받는 건 diff와 PR 제목/본문, 스펙 제약 정도이고 서로의 산출물(리뷰어의 `issues`, continuity-judge의 `continuityVerdict` 등)은 아무도 받지 않으므로 순서를 나눌 이유가 없습니다. 셋을 한 파도로 띄우고 각자 결과를 받습니다. 메인 세션에서 `ges_agent get`을 하지 않습니다.
+
+코드 그래프의 영향 범위(`diff_radius`, `co_change`)를 이 프롬프트에 얹는 안은 한 번 재보고 접었습니다 — 리뷰어가 그 목록을 열지 않았고 토큰만 늘었습니다. 근거는 `docs/experiments/review-impact-radius.md`에 있습니다.
 
 ```
 Agent {
@@ -528,9 +549,13 @@ ges_execute {
 
 ### 3.5단계: 정합 심급 판단 (continuity-judge)
 
-`review_consensus`를 호출하기 **전에** 정합 심급을 먼저 판단합니다. 결함 심급(3단계 리뷰 에이전트)이 "부분에 결함이 있나"를 봤다면, 정합 심급은 "부분의 합이 목표를 이루나"를 봅니다 — 국소 결함으로는 안 잡히는 **목표 이탈(drift)과 전체 일관성**입니다.
+`review_consensus`를 호출하기 **전에** 정합 심급을 먼저 판단합니다. 이 문장이 가리키는 건 **결과를 넘기는 순서**이지 **호출을 내보내는 순서**가 아닙니다 — 아래 프롬프트는 3단계의 병렬 메시지에 함께 담아 리뷰어들과 같은 파도로 띄웁니다. `continuity-judge`는 diff와 목표, PR 제목/본문, 스펙 제약만 보고 리뷰어의 `issues`를 보지 않으므로 리뷰어 결과를 기다릴 이유가 없습니다. 순서가 남는 자리는 **소비 시점**뿐입니다 — `continuityVerdict`는 파도가 다 돌아온 뒤 3단계 리뷰 결과와 나란히 4단계 `review_consensus`로 넘깁니다.
+
+결함 심급(3단계 리뷰 에이전트)이 "부분에 결함이 있나"를 봤다면, 정합 심급은 "부분의 합이 목표를 이루나"를 봅니다 — 국소 결함으로는 안 잡히는 **목표 이탈(drift)과 전체 일관성**입니다.
+
+**`continuity-judge`는 3단계 리뷰어의 `issues`를 입력으로 받지 않습니다** — 보는 자료는 diff 전체와 목표, PR 제목과 본문, 스펙 제약뿐입니다. 그래서 리뷰어 판정을 기다리지 않고 같은 파도에 태울 수 있습니다. 이 프롬프트에 `issues`나 `review_submit` 산출물을 끼워 넣는 변경은 이 전제와 정면으로 부딪힙니다.
 
-**서브에이전트에 위임합니다.** `continuity-judge`는 tier가 `frontier`라 모델도 그에 맞춰 넘깁니다(`agent-model.md`).
+**서브에이전트에 위임합니다.** `continuity-judge`는 tier가 `frontier`라 모델도 그에 맞춰 넘깁니다(`agent-model.md`). 이 호출도 3단계, 1.5단계와 같은 메시지에 담습니다.
 
 ```
 Agent {
@@ -629,7 +654,35 @@ ges_execute {
 
 `review_consensus`가 반환한 마크다운 리포트를 `humanize-monolith` 에이전트로 전달해 AI 말투, 번역투를 제거합니다.
 
-**서브에이전트에 위임합니다.** humanize-monolith는 룰북 두 개(`author-voice.md` 19KB, `ai-tell-quick-rules.md` 21KB)를 딸고 오므로, 메인 세션에서 가져오면 이 단계 하나로 50KB가 실립니다.
+**서브에이전트에 위임합니다.** humanize-monolith는 룰북 두 개(`author-voice.md` 23KB, `ai-tell-quick-rules.md` 44KB)를 딸고 오므로, 메인 세션에서 가져오면 이 단계 하나로 67KB가 실립니다.
+
+**그 67KB를 통째로 딸려 보내지도 않습니다.** 윤문에 넘기기 전에 먼저 스캔을 돌려 이번 리포트에서 실제로 걸린 룰만 처방과 함께 프롬프트에 싣습니다. 걸린 게 서너 개인데 예순 개가 넘는 룰북을 라운드마다 펼치면 모델이 나눠 쓰는 주의가 안 걸린 룰까지 흩어집니다. `ship`이 이 파이프라인을 라운드로 돌리는 자리라 그 낭비가 라운드마다 되풀이됩니다.
+
+#### 사전 스캔 (필수)
+
+`review_consensus`가 돌려준 리포트를 윤문에 넘기기 전에 먼저 스캔합니다. 이 스캔의 출력이 아래 윤문 프롬프트의 입력이 됩니다.
+
+**셸로 넘기지 않고 파일 쓰기 도구를 씁니다.** 리포트에는 한글과 백틱, 코드펜스가 섞입니다.
+
+```bash
+# --git-common-dir 는 워크트리 여럿이 같은 자리를 가리킵니다. 대상으로 칸을 나누고
+# 그 아래 실행 단위로 한 겹 더 나눕니다 — 같은 대상을 두 세션이 동시에 리뷰할 수 있습니다
+scanTmp="$(cd "$(git rev-parse --git-common-dir)" && pwd)/gestalt-review/<PR 식별자 또는 target>/$$"
+mkdir -p "$scanTmp"
+echo "$scanTmp"
+```
+
+윤문 전 리포트 전문을 `"$scanTmp/consensus.md"`에 쓰고 스캔합니다.
+
+```bash
+gestalt humanize-scan --file "$scanTmp/consensus.md" --register report
+```
+
+출력 전문을 그대로 아래 윤문 프롬프트의 `사전 스캔` 자리에 싣습니다. 종료 코드로 걸러 내지 않습니다 — 0건일 때의 출력도 "무엇을 직접 확인해야 하는가"를 담고 있어서 윤문하는 쪽이 읽을 값이 있습니다.
+
+**이 스캔은 판정하는 자리가 아닙니다.** 판정은 윤문이 끝난 뒤 아래 `리포트 어투 검사`가 합니다. 여기서 0건이 나와도 윤문은 그대로 돌립니다. 탐지기가 가리는 범위는 룰북 전체와 같지 않습니다. voice를 맞추는 일은 애초에 스캔이 재는 대상이 아닙니다.
+
+#### 윤문 위임
 
 ```
 Agent {
@@ -642,8 +695,16 @@ Agent {
     읽기와 보고만 한다. 파일 수정, 커밋, 외부 전송은 하지 않는다.
 
     ges_agent { action: \"get\", name: \"humanize-monolith\" } 로 시스템 프롬프트를 가져와
-    본문이 참조하는 룰북(author-voice.md, ai-tell-quick-rules.md)까지 읽고
-    아래 리포트를 윤문한다.
+    본문이 참조하는 author-voice.md 를 읽고 아래 리포트를 윤문한다.
+
+    ai-tell-quick-rules.md 는 통째로 열지 않는다. 아래 사전 스캔이 이번 리포트에서
+    걸린 룰을 처방까지 붙여 주므로 그 목록이 이번에 걷어낼 전부다. 스캔이 0건이면
+    그 파일은 아예 열 이유가 없다.
+    다만 '탐지기가 못 가리는 S1' 줄의 ID 들은 처방이 안 딸려 온다. 그것들을 확인해야
+    하면 ai-tell-quick-rules.md 에서 해당 행만 찾아 읽고 파일 전체를 읽지 않는다.
+
+    사전 스캔:
+    <humanize-scan --register report 출력 전문>
 
     보존 규칙:
     - 이슈 내용(severity, file, line, message)은 수정하지 않는다. 설명 문장의 어투만 다듬는다.
@@ -668,16 +729,12 @@ Agent {
 
 **셸로 넘기지 않고 파일 쓰기 도구를 씁니다.** 리포트에는 한글과 백틱, 코드펜스가 섞입니다.
 
-```bash
-scanTmp="$(cd "$(git rev-parse --git-common-dir)" && pwd)/gestalt-review/<PR 식별자 또는 target>/$$"
-mkdir -p "$scanTmp"
-echo "$scanTmp"
-```
+사전 스캔에서 만든 그 칸을 그대로 씁니다. `mkdir`을 다시 돌리지 않습니다 — `$$`는 Bash 호출마다 달라서 다시 만들면 앞의 `consensus.md`와 다른 자리가 됩니다.
 
-윤문된 리포트 전문을 `"$scanTmp/report.md"`에 씁니다.
+윤문된 리포트 전문을 사전 스캔이 출력한 경로 아래 `report.md`에 씁니다.
 
 ```bash
-pnpm tsx bin/gestalt.ts humanize-scan --file "$scanTmp/report.md" --register report
+gestalt humanize-scan --file "$scanTmp/report.md" --register report
 ```
 
 - **10 / 11** — 통과입니다. 11이면 어투는 안 걸렸고 맞춤법만 고칩니다.
@@ -712,7 +769,7 @@ git rev-parse HEAD && git status --porcelain
 gh pr view <target> --json headRefOid
 
 # local: PR head도 함께 확인
-pnpm tsx bin/gestalt.ts pr --json show <id>   # headSha 필드로 비교
+gestalt pr --json show <id>   # headSha 필드로 비교
 ```
 
 판단 기준:
@@ -733,7 +790,7 @@ pnpm tsx bin/gestalt.ts pr --json show <id>   # headSha 필드로 비교
 gh pr view <number> --json number,headRefName,baseRefName,url 2>/dev/null
 
 # local
-pnpm tsx bin/gestalt.ts pr --json show <id> 2>/dev/null
+gestalt pr --json show <id> 2>/dev/null
 ```
 
 여기서 PR이 사라졌으면 게시하지 않고 그 사실을 알립니다. 판별을 다시 돌려 다른 자리에 옮겨 붙이지 않습니다.
@@ -744,7 +801,9 @@ pnpm tsx bin/gestalt.ts pr --json show <id> 2>/dev/null
 
 #### 코멘트 본문 작성 (code-review-writer)
 
-**서브에이전트에 위임합니다.** 이 에이전트는 본문 18.8KB에 `author-voice.md` 19KB를 딸고 오는, 이 스킬에서 제일 무거운 자리입니다.
+**서브에이전트에 위임합니다.** 이 에이전트는 본문 18.8KB에 `author-voice.md` 23KB를 딸고 오는, 이 스킬에서 제일 무거운 자리입니다.
+
+**`author-voice.md`는 읽고 `ai-tell-quick-rules.md`는 첫 판에 안 엽니다.** 앞의 것은 코멘트를 쓰는 기준이라 없으면 쓰기 자체가 안 됩니다. 뒤의 것은 다 쓴 뒤에 무엇이 걸렸는지 보는 기준입니다. 그 답은 아래 `어투 검사`가 걸린 룰의 처방까지 붙여 돌려줍니다. 44KB를 미리 펼쳐 놓고 그중 서너 줄을 쓰는 대신, 걸린 자리의 처방만 재작성 판에 실어 보냅니다.
 
 ```
 Agent {
@@ -760,9 +819,14 @@ Agent {
     읽기와 보고만 한다. 파일 수정, 커밋, 외부 전송은 하지 않는다.
 
     ges_agent { action: \"get\", name: \"code-review-writer\" } 로 시스템 프롬프트를 가져와
-    본문이 참조하는 룰북까지 읽고 그 관점으로 아래 이슈들의 코멘트 본문을 쓴다.
+    본문이 참조하는 author-voice.md 를 읽고 그 관점으로 아래 이슈들의 코멘트 본문을 쓴다.
     레포 자체 리뷰 컨벤션은 AGENT.md의 '레포 규칙 우선 탐색'에 따라 직접 확인한다.
 
+    ai-tell-quick-rules.md 는 이 판에서 통째로 열지 않는다. AGENT.md 의 Humanize 절이
+    인라인 코멘트에 걸리는 패턴을 이미 추려 담고 있다. 그걸로 안 걸러진 자리는 뒤따르는
+    어투 검사가 걸린 룰과 처방을 함께 돌려준다. 그때 그 처방만 받아 다시 쓴다.
+    지금 확인해야 할 ID 가 따로 있으면 그 행만 찾아 읽고 파일 전체를 읽지 않는다.
+
     audience: <peer | junior — 0.5단계에서 잡고 1.05단계가 확정한 값>
     AGENT.md의 '대상 눈높이 (audience)' 절을 그 값으로 적용한다. 그 절이 자기 완결이다 —
     junior 기준을 찾겠다고 다른 파일을 열지 않는다. 특히 작업 디렉토리(= 리뷰 대상 레포)에서
@@ -784,7 +848,7 @@ Agent {
 
 아래 규칙은 `code-review-writer` AGENT.md에 있어서 서브에이전트가 읽습니다. 여기 적어두는 건 사람이 읽을 계약이고 두 곳이 갈라지면 AGENT.md가 기준입니다. (바로 위 `path`·`line`·`side` 규칙은 반대로 **스킬 쪽에만** 있습니다 — 메인 세션이 하는 일이라 AGENT.md에 없습니다.)
 
-- code-review-writer는 `author-voice.md`(제안형·온기·물결·이모지)와 `ai-tell-quick-rules.md`(음차 교정)를 이미 내장하므로 **리포트처럼 humanize-monolith로 통째로 윤문하지는 않습니다.** 대신 위의 `humanize-scan` 검사를 거칩니다 — 내장이 자가점검을 시키는 것이고 검사는 그게 실제로 됐는지 보는 것이라 층이 다릅니다.
+- code-review-writer는 `author-voice.md`(제안형·온기·물결·이모지)를 읽고 음차 교정 규칙은 AGENT.md의 Humanize 절에 추려 들고 있으므로 **리포트처럼 humanize-monolith로 통째로 윤문하지는 않습니다.** 대신 위의 `humanize-scan` 검사를 거칩니다 — 내장이 자가점검을 시키는 것이고 검사는 그게 실제로 됐는지 보는 것이라 층이 다릅니다.
 - 에이전트 룰에 따라 `[출처]` 태깅, "…권장." 체언 종지는 쓰지 않습니다. 이건 Claude artifact이지 실제 리뷰어 어투가 아닙니다.
 - **출처를 밝히는 태그는 형태를 가리지 않고 쓰지 않습니다.** `[게슈탈트 리뷰]`, `[Gestalt]`, `[AI 리뷰]`, 🤖 처럼 도구가 썼다는 표시를 붙이지 않습니다. 리뷰는 계정 주인이 남기는 것입니다. **내부 리뷰 에이전트 이름(QA, Architect, security-reviewer 등)도 본문에 드러내지 않습니다** — 관점이 여럿이어도 코멘트는 리뷰어 한 사람이 남긴 것처럼 씁니다.
 - **강제성은 `r:`/`c:`/`a:` 접두어로 표기합니다** (레포에 자체 리뷰 컨벤션이 없을 때의 기본값). 코멘트 본문 맨 앞에 severity에 따라 붙입니다 — `r:` 꼭 반영(critical/high), `c:` 웬만하면 반영(warning), `a:` 사소한 의견(suggestion). 접두어는 강제성 라벨이고 본문 어투는 그대로 제안형입니다. **접두어 앞에는 아무것도 오지 않습니다** — 출처 태그나 굵은 제목 줄이 접두어를 밀어내면 리뷰이가 강제성을 한눈에 못 봅니다. (리뷰 이벤트 판정은 접두어가 아니라 `severity`로 하므로 그쪽은 영향받지 않습니다.)
@@ -818,24 +882,31 @@ echo "$scanTmp"
 found=$(find "$scanTmp" -maxdepth 1 -name '*.md' | wc -l | tr -d ' ')
 echo "파일 $found 개"
 
-find "$scanTmp" -maxdepth 1 -name '*.md' | sort | while read -r f; do
-  pnpm tsx bin/gestalt.ts humanize-scan --file "$f" --register chat
-  echo "$(basename "$f" .md) EXIT=$?"
-done
+# 파일마다 프로세스를 새로 띄우지 않고 한 번의 호출에 전부 실어 보냅니다.
+# humanize-scan 은 넘겨받은 파일 각각을 읽고 스캔을 따로 돌리므로 결과는 파일별로 갈립니다.
+find "$scanTmp" -maxdepth 1 -name '*.md' | sort | sed 's/^/--file /' \
+  | xargs gestalt humanize-scan --register chat
 ```
 
 `found` 가 코멘트 수와 다르면 **검사 실패입니다.** 그 자리에서 멈추고 무엇이 어긋났는지 알립니다. 파일 쓰기가 어긋났는데 조용히 넘어가면 이 검사가 막으려던 상황이 그대로 재현됩니다.
 
-종료 코드는 코멘트마다 봅니다.
+이 호출이 답하는 질문은 두 층입니다.
+
+- **프로세스 종료 코드**는 파일 전체를 합친 값입니다 — 하나라도 0이면 0, 아니면 하나라도 12면 12, 아니면 하나라도 11이면 11, 나머지는 10입니다. "게시를 미뤄야 하는가"는 이 값 하나로 답이 납니다.
+- **어느 코멘트를 다시 써야 하는가**는 출력에 파일마다 찍히는 `== <경로> EXIT=<코드>` 줄로 답이 납니다. 파일별로 스캔을 따로 돌린 결과라 이 코드는 코멘트 단위 그대로입니다.
 
-- **0** — 걸렸습니다. 스캔 결과(걸린 룰, 사례, 처방)를 **그대로 `code-review-writer`에 돌려주고 그 코멘트만 다시 쓰게 합니다.** 안 걸린 코멘트는 건드리지 않습니다.
+각 줄의 EXIT 값이 뜻하는 바는 다음과 같습니다.
+
+- **0** — 걸렸습니다. 스캔 결과(걸린 룰, 사례, 처방)를 **그대로 `code-review-writer`에 돌려주고 그 코멘트만 다시 쓰게 합니다.** 안 걸린 코멘트는 건드리지 않습니다. 걸린 룰의 처방이 그 출력에 이미 들어 있으니 재작성 판에서도 `ai-tell-quick-rules.md`를 통째로 열 이유가 없습니다.
 - **10** — 걸린 게 없습니다.
 - **11** — 어투는 깨끗하고 맞춤법만 걸렸습니다. 그것만 고칩니다.
 - **12** — **검사할 산문이 없습니다.** 코멘트가 인용줄뿐이라 검사가 안 된 것이지 통과가 아닙니다. 자기 문장을 인용 밖에 두고 다시 쓰게 합니다.
 - 재작성은 **한 번만** 돕니다. 두 번째도 걸리면 무엇이 남았는지 사용자에게 알리고 게시할지 묻습니다.
-- 전부 10이나 11이면 게시합니다. 게시가 끝나면 `rm -rf "$scanTmp"`로 그 실행 칸만 치웁니다 — 상위 `gestalt-review`나 PR 칸을 통째로 지우면 다른 세션이 쓰는 중인 파일까지 날아갑니다.
+- 프로세스 종료 코드가 10이나 11이면 게시합니다. 게시가 끝나면 `rm -rf "$scanTmp"`로 그 실행 칸만 치웁니다 — 상위 `gestalt-review`나 PR 칸을 통째로 지우면 다른 세션이 쓰는 중인 파일까지 날아갑니다.
+
+**코멘트 여러 개를 파일 하나에 모아 담으면 이 검사가 무력화됩니다.** 인용 판정이 그 파일 전체를 한 덩어리로 보기 때문에 코멘트 하나를 통째로 인용으로 감싸도 같은 파일 안 다른 코멘트의 산문에 묻혀 안 걸립니다. 파일 하나에 코멘트 하나가 이 검사가 서는 조건입니다. 이 조건은 지금도 바뀌지 않았습니다.
 
-**이 반복문을 벗어나 코멘트를 합쳐 한 번에 돌리면 이 검사가 무력화됩니다.** 한 파일에 여러 코멘트를 넣으면 인용 판정이 배치 전체로 서서, 코멘트 하나를 통째로 인용으로 감싸도 다른 코멘트의 산문에 묻힙니다. 파일 하나에 코멘트 하나가 이 검사가 서는 조건입니다.
+파일 여러 개를 한 프로세스 호출에 실어 보내는 것은 다른 이야기입니다. `humanize-scan`은 넘겨받은 파일마다 읽기와 스캔을 독립적으로 돌려 인용 판정이 파일 경계를 넘지 않게 막습니다. 그래서 위 호출처럼 파일을 한 번에 묶어 넘겨도 코멘트별 판정은 그대로 섭니다.
 
 표 셀 검사는 끌 수 없습니다. 룰 문서인지는 `humanize-scan` 이 경로로 스스로 판정하고 그걸 바꾸는 옵션을 안 받습니다 — 검사를 끄는 스위치가 밖에 있으면 리뷰 대상 텍스트가 그걸 붙이라고 시키는 자리가 열립니다.
 
@@ -944,7 +1015,7 @@ ges_execute {
 
 `prContext`가 `"(없음)"`이면 PR 본문 줄만 뺍니다. 리뷰 의도와 PR 본문이 어긋났으면 그 줄 아래에 무엇이 어긋났는지 한 줄 더 적습니다 (1.15단계).
 
-그다음 기획 컨텍스트 문서(1.5단계)를 리뷰 리포트 앞에 먼저 표시한 뒤, 코드 리뷰 결과를 표시합니다.
+**실행은 병렬이고 표시만 순서를 지킵니다.** 1.5단계 호출은 3단계 파도에 실어 리뷰어들, 3.5단계와 동시에 내보냈지만 그건 실행 순서일 뿐입니다. 사용자에게 보여줄 때는 기획 컨텍스트 문서(1.5단계)를 리뷰 리포트 앞에 먼저 표시한 뒤, 코드 리뷰 결과를 표시합니다.
 
 ```
 {1.5단계 기획 컨텍스트 마크다운}

package/dist/plugin/skills/review-loop/SKILL.md

@@ -202,13 +202,12 @@ gh repo view --json owner,name,nameWithOwner
 
 **판정에 쓰는 수를 전부 이 명령이 낸다.** 없으면 첫 단계부터 아무것도 못 한다 — 설치본이 뒤처져 있으면 `unknown option` 으로 죽는데, 그걸 라운드를 돌다가 알면 늦다.
 
+먼저 [`../_shared/cli-launcher.md`](../_shared/cli-launcher.md)의 판정을 돌려 `gestalt`를 어떤 형태로 부르는지 정한다. 그다음 그 형태로 하위 명령을 찌른다.
+
 ```bash
 if gestalt review-loop parse 1 >/dev/null 2>&1 \
   && gestalt review-loop dir >/dev/null 2>&1; then
-  echo "OK gestalt"
-elif pnpm tsx bin/gestalt.ts review-loop parse 1 >/dev/null 2>&1 \
-  && pnpm tsx bin/gestalt.ts review-loop dir >/dev/null 2>&1; then
-  echo "OK pnpm"
+  echo "OK"
 else
   echo "MISSING"
   exit 1
@@ -217,7 +216,7 @@ fi
 
 **명령을 변수에 담아 함수로 넘기지 않는다.** zsh는 인용 안 한 변수 전개에서 단어 분리를 안 해 `$cmd`가 통째로 명령 이름이 된다. 그러면 실제로 깔려 있어도 `MISSING`이 나온다. 같은 코드가 bash에서는 도는 탓에 눈으로는 안 걸린다.
 
-`OK gestalt`면 아래 예시를 그대로 쓴다. `OK pnpm`이면 게슈탈트 레포 안이라는 뜻이라 모든 호출을 `pnpm tsx bin/gestalt.ts review-loop ...`로 바꾼다. **`MISSING`이면 라운드를 시작하지 않는다.**
+`OK`면 아래 예시를 앞의 판정에서 정한 형태로 쓴다. **`MISSING`이면 라운드를 시작하지 않는다.**
 
 **하위 명령을 둘 다 찔러본다.** 하나만 보면 그것만 있고 나머지가 없는 중간 설치본이 통과해 라운드 중간에 죽는다. 1.1이 입력 하나가 아니라 셋을 보는 이유와 같다.
 
@@ -532,7 +531,7 @@ gestalt humanize-scan --file "$stateDir/verdict-r<N>.md" --register chat
 echo "EXIT=$?"
 ```
 
-게슈탈트 레포 안에서는 `pnpm tsx bin/gestalt.ts humanize-scan ...`이다. 한 번 확인하고 그 뒤로는 같은 형태를 쓴다.
+부르는 형태는 위 "조회 명령이 있는지 먼저 본다"에서 판정한 것을 그대로 쓴다.
 
 | 종료 코드 | 무엇 |
 | --- | --- |

package/dist/plugin/skills/review-reply/SKILL.md

@@ -49,6 +49,9 @@ outputs:
 >
 > **도구가 없을 때** → [`../_shared/tool-availability.md`](../_shared/tool-availability.md)
 >
+> **`gestalt` CLI를 부르는 형태** → [`../_shared/cli-launcher.md`](../_shared/cli-launcher.md)
+> 본문의 셸 예시는 전부 `gestalt ...`다. 게슈탈트 레포 안에서는 `pnpm tsx bin/gestalt.ts ...`로 바꿔 부른다. 답글 어투 검사가 이 CLI에 매달려 있고 **그건 필수 검사라 못 돌리면 멈춘다.**
+>
 > **에이전트 tier로 모델 고르기** → [`../_shared/agent-model.md`](../_shared/agent-model.md)
 > GitHub PR은 `gh` CLI(REST + GraphQL)에, 로컬 PR은 `gestalt pr` CLI에 의존한다 (대상 판별은 아래). 둘 다 실패하면 거기서 멈추고 알린다. 스레드 목록을 손으로 지어내지 않는다.
 
@@ -82,7 +85,7 @@ outputs:
 `gestalt pr list`에는 브랜치 필터가 없다. `--status`만 받는다. `headRef`도 못 믿는다 — 워크트리에서 detached로 만든 PR은 거기에 브랜치 이름이 아니라 sha가 들어간다. 그래서 이름이 아니라 커밋으로 가른다.
 
 ```bash
-pnpm tsx bin/gestalt.ts pr --json list
+gestalt pr --json list
 git merge-base --is-ancestor <PR의 headSha> HEAD   # 종료 코드 0이면 내 브랜치의 PR
 ```
 
@@ -115,7 +118,7 @@ id를 직접 주면 아래 1번의 첫 수단이 브랜치를 안 따지고 잡
 **명시 지정이 가장 세다. 그다음이 안 끝난 로컬 PR이다.** 아래 순서대로 훑어 처음 걸리는 것을 택한다.
 
 1. **로컬 지정** — `local` 입력이 true거나(`--local` 플래그) `target`이 로컬 PR id 형식(`gestalt pr list`에 뜨는 id)인 경우다. 이때는 로컬 PR을 두 수단으로 찾는다.
-   - `target`에 id가 있으면 먼저 `pnpm tsx bin/gestalt.ts pr --json show <id>`로 실제 존재를 확인한다. 사용자가 id를 짚었으면 그 PR이 현재 브랜치 것인지는 안 따진다.
+   - `target`에 id가 있으면 먼저 `gestalt pr --json show <id>`로 실제 존재를 확인한다. 사용자가 id를 짚었으면 그 PR이 현재 브랜치 것인지는 안 따진다.
    - id가 없거나(`--local`만 준 경우) `show`가 빈 결과를 내면 위의 가리는 법으로 현재 브랜치의 로컬 PR을 찾는다.
    - 둘 중 하나로 찾으면 `local`. 어느 쪽으로도 못 찾으면 그 사실을 한 줄 알리고 2번으로 내려간다.
 
@@ -168,7 +171,7 @@ gh api user --jq .login
 **local**: 대상 PR은 판별에서 이미 정해졌다. 여기서 다시 조회하지 않고 그때 잡은 id를 그대로 쓴다. 본문과 상태가 필요하면 `show` 한 번이면 된다.
 
 ```bash
-pnpm tsx bin/gestalt.ts pr --json show <판별에서 잡은 id>
+gestalt pr --json show <판별에서 잡은 id>
 ```
 
 `prTarget`이 `none`이면 0단계에 들어오지 않는다. 판별 4번에서 이미 멈춘 뒤다.
@@ -238,7 +241,7 @@ gh api --paginate 'repos/<owner>/<repo>/issues/<number>/comments?per_page=100' \
 로컬 PR에는 GraphQL이 없다. `gestalt pr comments`가 resolved 여부를 이미 필드로 준다 — 페이지네이션 걱정도 없다(단일 프로세스, SQLite 기반이라 상한이 없다).
 
 ```bash
-pnpm tsx bin/gestalt.ts pr --json comments <id> --unresolved
+gestalt pr --json comments <id> --unresolved
 ```
 
 반환된 코멘트를 스레드로 재구성한다. `replyTo`로 이어지는 코멘트를 한 체인으로 묶는다. 체인의 마지막 작성자가 나 자신이면 제외한다(이미 답했음). `line`이 `null`인 항목이 PR 전반 코멘트다 — 별도 API가 없다. `isOutdated` 개념은 로컬 PR에 없으므로 그 필터는 건너뛴다.
@@ -390,13 +393,27 @@ echo "$scanTmp"
 
 **본문만 쓴다** — 표지 줄을 붙이면 그 줄이 산문으로 세어져 인용 판정이 어긋난다.
 
+```bash
+if gestalt --version >/dev/null 2>&1; then
+  echo "OK gestalt"
+elif pnpm tsx bin/gestalt.ts --version >/dev/null 2>&1; then
+  echo "OK pnpm"
+else
+  echo "MISSING"
+fi
+```
+
+`OK pnpm`이면 아래 호출의 `gestalt`를 `pnpm tsx bin/gestalt.ts`로 바꿔 부른다.
+
+**`MISSING`이면 검사를 건너뛰지 않고 멈춘다.** 못 돌린 걸 통과로 읽으면 검사가 없는 것과 같다. `npm i -g @tienne/gestalt`를 함께 알리고 그대로 진행할지 사용자가 정하게 둔다.
+
 ```bash
 # 개수를 먼저 센다. 글롭으로 바로 돌면 파일이 0개일 때 셸마다 다르게 죽는다
 found=$(find "$scanTmp" -maxdepth 1 -name '*.md' | wc -l | tr -d ' ')
 echo "파일 $found 개"
 
 find "$scanTmp" -maxdepth 1 -name '*.md' | sort | while read -r f; do
-  pnpm tsx bin/gestalt.ts humanize-scan --file "$f" --register chat
+  gestalt humanize-scan --file "$f" --register chat
   echo "$(basename "$f" .md) EXIT=$?"
 done
 ```
@@ -456,7 +473,7 @@ gh api repos/<owner>/<repo>/issues/<number>/comments -f body="..."
 **local**:
 
 ```bash
-pnpm tsx bin/gestalt.ts pr comment <id> \
+gestalt pr comment <id> \
   --path "<원 코멘트의 path>" \
   --line <원 코멘트의 line — 없으면 생략> \
   --reply-to <원 코멘트 id> \
@@ -487,7 +504,7 @@ mutation($threadId:ID!) {
 **local**:
 
 ```bash
-pnpm tsx bin/gestalt.ts pr resolve <id> <commentId>
+gestalt pr resolve <id> <commentId>
 ```
 
 종료하더라도 `accept`·`alternate`만 종료한다. `defer`·`clarify`는 대화가 남아 있으므로 열어둔다. (github·local 공통)

package/dist/plugin/skills/setup/SKILL.md

@@ -64,14 +64,10 @@ multiSelect: true
 **파일이 없으면**: Bash로 생성한다.
 
 ```bash
-! pnpm tsx bin/gestalt.ts setup
+! gestalt setup
 ```
 
-또는 npx로 설치된 환경이면:
-
-```bash
-! npx @tienne/gestalt setup
-```
+부르는 형태는 [`../_shared/cli-launcher.md`](../_shared/cli-launcher.md)의 판정을 따른다. 전역 설치도 게슈탈트 레포도 아니면 `npx @tienne/gestalt setup`으로 부른다.
 
 **파일이 이미 존재하면**: 사용자에게 덮어쓸지 확인 후 진행한다.
 
@@ -107,14 +103,10 @@ ges_code_graph({ action: "build", repoRoot: "<현재 디렉토리 절대경로>"
 ### Step 4 — post-commit 훅 설치 (선택된 경우)
 
 ```bash
-! pnpm tsx bin/gestalt.ts init --skip-graph
+! gestalt init --skip-graph
 ```
 
-또는:
-
-```bash
-! npx @tienne/gestalt init --skip-graph
-```
+부르는 형태는 위 Step 2와 같다.
 
 성공 시 출력:
 ```