@kaydash9999/banker-plugins 0.25.0 → 0.26.0

package/skills/make-evidence/SKILL.md

@@ -0,0 +1,182 @@
+---
+name: make-evidence
+description: "구현한 서비스의 증거 문서 여섯(optimize, verify, flow, scale, decisions, trace)을 실제 실행으로 만들어 docs/evidence/ 에 커밋. 수치는 실행 로그에서만 옮기고, 문서마다 실행 명령과 로그 경로를 적음. 판정기는 구현을 보지 않은 새 맥락 하위 에이전트가 씀. 미구현은 숨기지 않음. 'make-evidence'/'증거 문서'/'evidence 만들어'/'검증 근거 문서' 시 사용."
+argument-hint: "[--host <host>] [--port <port>] [--only <문서,...>] [--no-commit]"
+---
+
+# make-evidence: 실행으로 만드는 증거 문서 여섯
+
+구현한 서비스가 README 의 요구를 지키는지, 실제로 실행한 결과로 보이는 문서 여섯을 만든다.
+문서는 `docs/evidence/` 에 쓰고 커밋한다. 답변은 한글.
+
+## 원칙
+
+- **수치는 손으로 쓰지 않는다.** 시간, 목적값, 차이(%), 통과 수, 건수는 실행 로그에서만 옮긴다. 로그에 없는 수는 문서에 쓰지 않는다.
+- **문서마다 실행 명령과 로그 경로를 적는다.** 읽는 사람이 같은 명령을 다시 돌려 같은 로그를 얻을 수 있어야 한다.
+- **실행하지 못한 것은 실행하지 못했다고 쓴다.** 서버가 안 뜨거나 도구가 없으면 그 칸은 `미검증` 과 까닭이다. 추정값이나 예상값으로 채우지 않는다.
+- **미구현을 숨기지 않는다.** README 요구 가운데 구현하지 않은 것은 `trace.md` 에 `미구현` 과 이유로 남긴다.
+- 문서에 비밀값을 넣지 않는다. 로그에 토큰, 비밀번호, 키가 찍혔으면 커밋 전에 값을 `***` 로 가리고, 가렸다는 사실을 그 문서에 적는다.
+
+## 인자
+
+- `--host <host>`, `--port <port>`: `flow.md` 의 종단 시험이 요청을 보낼 서버. 없으면 README, `.env.example`, 서비스 시작 스크립트에서 찾고, 그래도 없으면 사용자에게 묻는다. 찾은 값과 그 출처를 `flow.md` 에 적는다.
+- `--only <문서,...>`: 일부만 만든다(예: `--only scale,trace`). 이름은 `optimize`, `verify`, `flow`, `scale`, `decisions`, `trace`.
+- `--no-commit`: 파일만 쓰고 커밋하지 않는다.
+
+## 폴더
+
+```
+docs/evidence/
+  optimize.md  verify.md  flow.md  scale.md  decisions.md  trace.md
+  logs/        실행 로그. 문서는 이 파일들을 경로로 가리킨다
+  scripts/     데이터 생성, 측정, 완전 탐색처럼 증거를 만드는 데 쓴 스크립트
+tests/oracle/  판정기와 그 시험 (verify.md)
+```
+
+- 로그 이름은 `<문서>-<무엇>-<YYYYMMDD-HHMMSS>.log` 다. 같은 시험을 다시 돌리면 새 파일을 만들고, 문서는 마지막 로그를 가리킨다.
+- 로그는 명령의 표준 출력과 표준 오류를 함께 담고, 첫 줄에 실행한 명령, 마지막 줄에 종료 코드를 남긴다.
+
+```bash
+run_log() {  # run_log <로그 경로> <명령...>
+  mkdir -p "$(dirname "$1")"; f=$1; shift
+  { echo "\$ $*"; "$@"; echo "exit=$?"; } > "$f" 2>&1
+}
+```
+
+## 진행
+
+먼저 저장소를 읽는다: README, 시작 스크립트, 시험 실행 방법, 최적화 코드, DB 스키마, 내보내기 코드.
+문서 여섯은 아래 순서로 만든다. `verify.md` 의 판정기는 다른 문서보다 먼저 쓴다.
+
+### 1. optimize.md
+
+| 항목 | 내용 |
+|---|---|
+| 목적 함수 | 최소화 또는 최대화하는 값과 식 |
+| 제약 | 제약마다 한 줄. 강한 제약과 약한 제약(벌점)을 나눔 |
+| 알고리즘 이름 | 쓴 알고리즘의 이름(예: 정수 계획법, 담금질, 탐욕 + 지역 탐색). 라이브러리를 쓰면 그 이름과 판 |
+| 핵심 함수 | `파일:줄` 로. 목적값 계산, 제약 검사, 탐색 본체를 각각 |
+| 의사코드 | 10줄 |
+
+- `파일:줄` 은 지금 커밋에서 실제로 그 줄을 열어 확인한 것만 쓴다. 문서 끝에 확인한 커밋 해시를 적는다.
+- 이 문서에는 실행 수치가 없다. 실행 명령 칸에는 줄 번호를 확인한 명령(예: `grep -n 'def objective' src/opt.py`)과 그 출력 로그를 적는다.
+
+### 2. verify.md
+
+판정기(oracle)는 구현을 보지 않은 하위 에이전트가 쓴다. 구현을 본 맥락이 판정기를 쓰면 구현의 실수를 판정기도 따라 한다.
+
+1. **담당자 사실을 모은다.** 담당자(사용자)가 준 업무 규칙, 수치 기준, 권한 규칙을 `docs/evidence/owner-facts.md` 에 그대로 옮긴다. 담당자 사실이 없으면 사용자에게 묻는다. 그래도 없으면 README 만으로 진행하고 그 사실을 `verify.md` 에 적는다.
+2. **새 맥락 하위 에이전트를 띄운다.** 이 대화를 넘기지 않는다.
+   - Claude Code: Agent 도구를 `general-purpose` 로, `model` 없이 부른다.
+   - Codex: `spawn_agent` 를 `agent_type` 과 `model` 없이 부르고 대화를 넘기지 않는다(multi-agent v2 는 `fork_turns="none"`, v1 은 `fork_context` 를 주지 않음).
+   - 지시에 들어갈 것:
+     - 읽어도 되는 것은 `README.md` 와 `docs/evidence/owner-facts.md` 둘뿐이다.
+     - 구현 폴더와 기존 시험은 열지 않는다.
+     - 쓸 곳은 `tests/oracle/` 다.
+     - 판정기는 입력과 출력만 보고 세 가지를 판정한다.
+       - 제약을 모두 지키는가
+       - 보고된 목적값이 입력과 출력으로 다시 계산한 값과 같은가
+       - 권한 규칙을 지키는가
+     - 시험은 판정기를 쓴다.
+     - 끝에 읽은 파일 목록을 보고한다.
+3. **읽은 파일 목록을 확인한다.** 목록에 두 파일 밖의 경로가 있으면 그 판정기는 버리고 다시 띄운다. 목록은 `verify.md` 에 옮긴다.
+4. **판정기를 구현보다 먼저 커밋한다.** 커밋 메시지는 `test(oracle): ...` 다. 구현이 아직 없으면 이 커밋이 구현 커밋보다 앞선다. 구현이 이미 있으면 그 사실과 두 커밋의 순서(`git log --format='%h %ad %s' --date=iso -- tests/oracle <구현 경로>`)를 그대로 적는다. 순서를 꾸미지 않는다.
+5. **판정기를 지금 구현에 돌린다.** 명령과 로그 경로, 통과와 실패 수를 로그에서 옮긴다.
+6. **일부러 넣은 버그 셋을 판정기가 잡는지 본다.**
+
+   | 버그 | 넣는 방법의 예 |
+   |---|---|
+   | 제약 위반 | 제약 검사 한 줄을 건너뛰게 바꿈 |
+   | 목적값 오계산 | 목적값 합산에서 항 하나를 빼거나 부호를 바꿈 |
+   | 권한 우회 | 권한 확인을 늘 통과하게 바꿈 |
+
+   - 버그마다 차례로 진행한다.
+     1. 바꾼 것을 패치 파일로 남긴다: `docs/evidence/logs/verify-bug-<이름>.patch`
+     2. `git apply` 로 넣는다.
+     3. 판정기를 돌려 로그를 남긴다.
+     4. `git apply -R` 로 되돌린다.
+     5. `git status --short` 와 `git diff --stat` 이 빈 것을 로그로 남긴다.
+   - 표에는 버그마다 다섯 가지를 적는다: 패치 경로, 넣은 뒤 결과(잡음 또는 놓침), 로그 경로, 되돌린 명령, 되돌린 뒤 판정기 결과.
+   - 놓친 버그는 놓쳤다고 쓰고, 판정기의 빈틈을 한 줄로 적는다. 놓친 것을 잡게 하려고 판정기를 고치면 그 커밋과 재실행 로그를 더한다.
+   - 되돌리기가 실패하면 멈추고 사용자에게 알린다. 작업 트리를 지우거나 덮어쓰지 않는다.
+
+### 3. flow.md
+
+- 순서는 화면, API, 최적화, DB, 내보내기다.
+- 단계마다 그 단계를 처리하는 `파일:줄` 을 적는다. 화면은 요청을 보내는 코드, API 는 라우트와 처리 함수, 최적화는 호출 지점, DB 는 쓰기와 읽기 쿼리, 내보내기는 파일을 만드는 함수다.
+- **종단 시험**: `{host}:{port}` 에 떠 있는 서버에 실제 요청을 보내 다섯 단계를 끝까지 지난다.
+  - 스크립트는 `docs/evidence/scripts/e2e-flow.*` 다.
+  - 서버가 떠 있지 않으면 저장소의 시작 방법으로 띄운다. 띄운 명령과 그 로그를 적는다.
+  - 화면 단계는 브라우저 도구(Playwright 등)가 있으면 실제로 누르고, 없으면 화면 URL 의 응답과 화면이 부르는 API 요청을 그대로 보낸다. 어느 쪽인지 적는다.
+  - 단계마다 다섯 가지를 로그에 남긴다: 요청, 응답 코드, 걸린 시간, DB 에 생긴 행의 확인 쿼리 결과, 내보낸 파일의 이름과 크기.
+- 서버에 닿지 못하면 종단 시험 칸은 `미검증` 과 오류 문구다. 단위 시험으로 대신하지 않는다.
+- 운영 서버나 남의 서버에는 보내지 않는다. 대상이 로컬이나 개발 서버가 아니면 사용자에게 먼저 확인한다.
+
+### 4. scale.md
+
+- **데이터 1배, 5배, 10배**: 기준 데이터(README 의 예시나 시험 고정물)를 늘리는 스크립트 `docs/evidence/scripts/gen-scale.*` 로 만든다. 같은 시드로 다시 만들 수 있게 시드를 고정하고 적는다.
+- 배수마다 최적화를 돌려 걸린 시간과 목적값을 잰다. 한 배수를 3회 돌려 각 값과 중앙값을 로그에 남긴다.
+- **작은 사례 다섯**: 완전 탐색이 끝나는 크기로 다섯 개를 만들고, 완전 탐색 스크립트 `docs/evidence/scripts/brute-force.*` 로 정해를 구한다.
+  - 사례마다 구현의 목적값과 정해를 적는다.
+  - 차이(%)는 `|구현 - 정해| / |정해| x 100` 이다. 정해가 0 이면 차이 대신 두 값을 그대로 적는다.
+  - 차이도 스크립트가 계산해 로그에 찍는다.
+- 표의 칸마다 로그 경로를 단다. 시간 제한에 걸린 배수는 `시간 초과(제한 N초)` 로 적는다.
+
+### 5. decisions.md
+
+결정마다 한 행이다.
+
+| 결정 | 고른 것 | 버린 것 | 이유 | 확인하는 시험 |
+|---|---|---|---|---|
+
+- 결정은 코드와 커밋 기록, README, ADR 이 있으면 ADR 에서 찾는다. 찾은 곳을 적는다.
+- 확인하는 시험은 실제로 있는 시험의 이름이다. 이름마다 통과 로그 경로를 단다. 그 결정을 확인하는 시험이 없으면 `없음` 으로 적는다. 이름을 지어내지 않는다.
+
+### 6. trace.md
+
+README 의 요구마다 한 행이다.
+
+| 번호 | 요구 | 상태 | 시험 이름 | 로그 경로 |
+|---|---|---|---|---|
+
+- 번호는 README 에 나온 순서로 `R1`, `R2` 다. 요구 칸에는 README 문장을 줄이지 않고 옮긴다.
+- 상태는 셋 가운데 하나다.
+  - `완료`: 그 요구를 확인하는 시험이 있고 통과함
+  - `부분`: 일부만 구현했거나 시험이 일부만 확인함. 빠진 부분을 적음
+  - `미구현`: 이유를 적음
+- 시험이 실패하면 `완료` 로 쓰지 않는다. 시험이 없으면 `완료` 가 아니라 `부분` 이고, 시험이 없다고 적는다.
+- 마지막에 상태별 개수를 적는다. 개수도 표에서 센 것이다.
+
+## 수치 대조
+
+문서를 다 쓴 뒤, 문서에 적은 수마다 그 칸이 가리키는 로그에 같은 수가 있는지 확인한다.
+
+- 문서의 숫자(시간, 목적값, 차이, 개수)를 하나씩 뽑아 가리킨 로그에서 찾는다(`grep -F`).
+- 로그에서 찾지 못한 수는 지우거나, 그 수를 찍는 명령을 다시 돌려 로그를 만든다.
+- 대조 결과(확인한 수의 개수, 못 찾은 수)를 각 문서 끝의 `수치 대조` 줄에 적는다.
+
+## 커밋
+
+- 커밋 대상은 `docs/evidence/` 와 `tests/oracle/` 뿐이다. 다른 경로는 넣지 않는다.
+  - 증거를 만들다 구현을 고쳤다면 그 수정은 따로 커밋하고 사용자에게 알린다.
+  - 판정기 커밋은 2번의 4단계에서 이미 했다.
+- 커밋 전에 비밀값을 찾는다. 걸린 값은 가린다. 커밋 메시지는 `docs(evidence): ...` 다.
+- push 하지 않는다. 사용자가 요청할 때만 한다.
+- `--no-commit` 이면 쓸 파일 목록만 보이고 커밋하지 않는다.
+
+## 런타임
+
+- Claude Code: `/banker:make-evidence`. 하위 에이전트는 Agent 도구다.
+- Codex: npm 길 `$banker-make-evidence`, 플러그인 길 `$banker:make-evidence`. 하위 에이전트는 `spawn_agent` 다.
+  - 기본 샌드박스가 `.git` 쓰기를 막으면 커밋 명령에 `sandbox_permissions: "require_escalated"` 를 청한다.
+  - 로컬이 아닌 서버에 보내는 종단 시험은 네트워크 승인이 필요하다.
+
+## 보고
+
+끝나면 표 하나로 알린다.
+
+| 문서 | 상태 | 로그 수 | 미검증이나 미구현 |
+|---|---|---|---|
+
+- 상태는 `작성`, `일부 미검증`, `작성 안 함(까닭)` 가운데 하나다.
+- 커밋 해시를 적는다. push 는 하지 않았다고 적는다.

package/skills/motion-sites/SKILL.md

@@ -29,7 +29,7 @@ banker 는 원본을 복사하지 않는다. 원본의 예시(`examples/`)와
 |---|---|
 | `skillFile` | 설치된 원본 `SKILL.md` 경로. 없거나 꺼져 있으면 `null` |
 | `disabled` | 설치는 됐지만 꺼져 있음 |
-| `python.bin` | Playwright 를 쓸 Python |
+| `python.bin` | Playwright 를 쓸 Python. 찾는 차례는 `MOTION_SITES_PYTHON`, 캐시 폴더의 가상 환경, PATH 의 `python3`, `python`(Windows 는 `py -3`, `python`). `MOTION_SITES_PYTHON` 이 있으면 그것과 캐시 폴더의 가상 환경만 보고, 지정한 것이 실행되지 않으면 다른 Python 으로 넘어가지 않는다 |
 | `python.playwright`, `python.chromium` | Playwright 와 Chromium 이 있는지 |
 | `ready` | 셋 다 있으면 `true`(종료 0) |
 
@@ -49,6 +49,14 @@ banker 는 원본을 복사하지 않는다. 원본의 예시(`examples/`)와
 3. Codex 에서는 이 명령이 네트워크와 `~/.codex` 쓰기를 하므로 `sandbox_permissions: "require_escalated"` 로 승인을 요청한다.
 4. 출력의 `steps` 에 실패한 단계가 있으면 그 단계와 `why` 를 보여 주고 멈춘다. 설치되지 않은 것을 설치된 것처럼 말하지 않는다.
    - 네트워크가 없으면 여기서 멈춘다. 오프라인에서는 이 스킬을 쓸 수 없다.
+   - `python` 단계가 "Python 3 을 찾지 못함" 으로 실패하면, 설치한 Python 이 PATH 밖에 있는지 사용자에게 묻는다. Windows 에서 `py` 가 없고 PATH 의 `python` 이 Microsoft Store 연결 파일뿐이거나, Miniconda 를 PATH 에 넣지 않고 설치한 경우다.
+   - 있으면 그 python 실행 파일의 절대 경로를 환경 변수 `MOTION_SITES_PYTHON` 에 영구로 지정하라고 안내한다. `%USERPROFILE%`, `~` 같은 줄임은 쓰지 않는다. 셸에 따라 글자 그대로 저장되어 엔진이 찾지 못한다.
+     - Windows(cmd 나 PowerShell): `setx MOTION_SITES_PYTHON "C:\Users\<이름>\miniconda3\python.exe"`
+     - macOS, Linux: 셸 설정 파일(`~/.zshrc`, `~/.bashrc`)에 `export MOTION_SITES_PYTHON=/절대/경로/python3`
+   - 한 번만 주는 것으로는 안 된다. 다음 실행의 상태 확인도 그 Python 을 봐야 한다. 이미 떠 있는 프로그램에는 새 값이 반영되지 않으므로, Claude Code 나 Codex 를 완전히 끝내고 다시 시작한 뒤 2단계를 다시 한다.
+   - Playwright 는 지정한 Python 에 설치된다. 그 Python 을 바꾸고 싶지 않으면 `<그 python> -m venv <폴더>` 로 가상 환경을 만들고 그 안의 python 을 지정한다(Windows `<폴더>\Scripts\python.exe`, macOS 와 Linux `<폴더>/bin/python`). pip 이 시스템 Python 을 거부하는(externally managed) 경우는 엔진이 캐시 폴더에 가상 환경을 스스로 만든다.
+   - 실패 이유가 "MOTION_SITES_PYTHON 에 지정한 ... 가 실행되지 않음" 이면 지정한 경로가 틀린 것이다. 경로를 고치게 한다.
+   - Python 이 없으면 Python 3 설치를 안내한다. 직접 설치하지 않는다.
    - Linux 에서 Chromium 이 시스템 라이브러리 부족으로 뜨지 않으면 `<python.bin> -m playwright install-deps chromium` 을 안내한다. 관리자 권한이 필요하므로 직접 실행하지 않는다.
 5. 끝나면 `ready` 가 `true` 인지 확인하고 3단계로 간다.
 

package/skills/motion-sites/scripts/motion-sites.mjs

@@ -215,9 +215,16 @@ export function lookPython(py, runner = run) {
   return { bin, cmd: py, playwright: pw, chromium: exe.ok && chrome !== "" && existsSync(chrome) };
 }
 
-/** The first Python with Playwright (and Chromium, when one has both), else the first that runs. */
+/**
+ * The first Python with Playwright (and Chromium, when one has both), else the first that runs. A MOTION_SITES_PYTHON
+ * is the user's choice: only it and the cache's virtual environment (made from it when pip refuses it) are looked at,
+ * and when it does not run there is none, so Playwright never goes into a Python the user did not name.
+ */
 export function pickPython(env = process.env, runner = run) {
-  const seen = pythons(env).map((p) => lookPython(p, runner)).filter(Boolean);
+  const all = pythons(env);
+  const named = env.MOTION_SITES_PYTHON ? lookPython(all[0], runner) : null;
+  if (env.MOTION_SITES_PYTHON && !named) return null;
+  const seen = (named ? [named, lookPython(all[1], runner)] : all.map((p) => lookPython(p, runner))).filter(Boolean);
   return seen.find((p) => p.playwright && p.chromium) ?? seen.find((p) => p.playwright) ?? seen[0] ?? null;
 }
 
@@ -265,10 +272,20 @@ function enablePlugin(runtime, runner) {
   return { step: "plugin enable", ok: r.ok, why: r.why };
 }
 
+// No Python found: says where it looked and how to name one that is installed but not on PATH (Windows with only
+// Miniconda, or only the Microsoft Store link, has no py and no working python).
+export const NO_PYTHON = "Python 3 을 찾지 못함(python3, python, Windows 는 py). 설치한 Python 이 PATH 밖에 있으면 환경 변수 MOTION_SITES_PYTHON 에 그 python 실행 파일의 절대 경로를 영구로 지정한 뒤 다시 실행";
+
+/** Why no Python was found; a MOTION_SITES_PYTHON that is set but does not run is named, so a typo is not hidden. */
+export function noPython(env = process.env) {
+  if (!env.MOTION_SITES_PYTHON) return NO_PYTHON;
+  return `MOTION_SITES_PYTHON 에 지정한 ${pythons(env)[0][0]} 가 실행되지 않음. 경로를 고친 뒤 다시 실행. ${NO_PYTHON}`;
+}
+
 /** The Python steps: Playwright, then Chromium. */
 function installBrowser(env, runner) {
   let py = pickPython(env, runner);
-  if (!py) return [{ step: "python", ok: false, why: "Python 3 을 찾지 못함(python3, python, Windows 는 py)" }];
+  if (!py) return [{ step: "python", ok: false, why: noPython(env) }];
   const steps = [];
   let cmd = py.cmd;
   if (!py.playwright) {

package/skills/omc-patch/scripts/omc-patch.mjs

@@ -252,8 +252,10 @@ function gitFetch(args) {
 // ── 1. 업데이트 ──────────────────────────────────────────────────────────────
 function ensureVersion() {
   const have = installedVersions();
-  if (have.includes(TARGET_VERSION)) return useCached();
-  if (MODE === "check") { bad(`${TARGET_VERSION} 미설치 (설치된 버전: ${have.join(", ") || "없음"})`); return false; }
+  if (have.includes(TARGET_VERSION) && completeVersion(TARGET_VERSION)) return useCached();
+  // 풀다 멈춘 폴더(hooks/hooks.json 이나 scripts/ 가 없음)는 설치된 것으로 보지 않는다. 그대로 전환하면 빈 플러그인으로 바뀐다.
+  if (have.includes(TARGET_VERSION)) bad(`${TARGET_VERSION} 캐시 폴더가 불완전함 (hooks/hooks.json 이나 scripts/ 가 없음)${MODE === "check" ? "" : ". 다시 풉니다"}`);
+  if (MODE === "check") { if (!have.includes(TARGET_VERSION)) bad(`${TARGET_VERSION} 미설치 (설치된 버전: ${have.join(", ") || "없음"})`); return false; }
   if (!canInstallTarget()) return false;
 
   log(`  ${TARGET_VERSION} 설치 중...`);
@@ -265,6 +267,9 @@ function ensureVersion() {
   return switchActive(sha);
 }
 
+// 판 폴더에 훅 목록과 스크립트 폴더가 있는가.
+const completeVersion = (v) => existsSync(join(CACHE, v, "hooks", "hooks.json")) && existsSync(join(CACHE, v, "scripts"));
+
 // TARGET_VERSION 이 캐시에 있을 때. 이미 활성이면 끝, 아니면 마켓플레이스 태그의 커밋으로 전환한다.
 // 전환도 마켓플레이스와 git 이 있어야 하므로 먼저 확인한다(풀지 않으므로 tar 는 없어도 된다).
 function useCached() {
@@ -356,16 +361,27 @@ function targetSha() {
 }
 
 // git archive | tar 로 소스를 편다. 저장소에 dist/ 가 포함되어 빌드는 불필요하다.
+// 옆의 난수 이름 폴더에 다 푼 뒤에만 판 이름으로 옮긴다. 도중에 멈추면(tar 실패, 신호, 디스크 부족) 판 이름의 폴더는 생기지 않아,
+// 다음 실행이 반쯤 찬 폴더를 설치된 판으로 보고 전환하지 않는다. 옆 폴더는 판 이름 꼴이 아니라 installedVersions 가 세지 않는다.
 function unpackTarget(dest) {
-  if (existsSync(dest)) rmSync(dest, { recursive: true, force: true });
-  mkdirSync(dest, { recursive: true });
-  git(["archive", `v${TARGET_VERSION}`, "-o", join(dest, "_src.tar")]);
-  execFileSync("tar", ["-xf", join(dest, "_src.tar"), "-C", dest], { cwd: homedir(), stdio: "ignore" });
-  unlinkSync(join(dest, "_src.tar"));
+  const part = `${dest}.part-${randomBytes(6).toString("hex")}`;
+  mkdirSync(part, { recursive: true });
+  try {
+    git(["archive", `v${TARGET_VERSION}`, "-o", join(part, "_src.tar")]);
+    execFileSync("tar", ["-xf", join(part, "_src.tar"), "-C", part], { cwd: homedir(), stdio: "ignore" });
+    unlinkSync(join(part, "_src.tar"));
+    if (existsSync(dest)) rmSync(dest, { recursive: true, force: true });
+    renameSync(part, dest);
+  } catch (e) {
+    rmSync(part, { recursive: true, force: true });
+    throw e;
+  }
 }
 
 // node_modules 는 복사하지 않고 직전 버전 것을 링크한다. Windows 는 junction
 // (관리자 권한 불필요), POSIX 는 type 인자가 무시되고 디렉터리 symlink 가 된다.
+// 없어도 전환을 막지 않는다. Claude Code 가 직접 설치한 OMC 판에는 node_modules 가 없고, 실행에 쓰는 것은 dist/ 에
+// 묶여 있다(2026-11-03 실측: 5.7.21~5.7.30 모두 없음, OMC 정상 동작). 막으면 보통 PC 에서 전환이 늘 실패한다.
 function linkNodeModules(dest, have) {
   const prev = have.find((v) => v !== TARGET_VERSION);
   const nm = join(dest, "node_modules");
@@ -699,16 +715,22 @@ function openParenOf(src, j) {
 // 그 상태를 «패치됨» 으로 넘기면 --check 가 결함 트리에 «모두 적용» 을 낸다(2026-10-12 실측).
 function siteInfo(src) {
   if (src.includes("__omcRaceImport")) {
-    const why = helperDefect(scanFacts(src));
+    // 헬퍼가 있어도 적용이 감쌌어야 할 자리가 남았으면(패치 뒤 상류가 줄을 더함) 적용된 것이 아니다.
+    // 헬퍼 본문의 Promise.race 는 손으로 두른 것이 아니므로, 같은 길이의 공백으로 지운 글에서 찾는다(자리는 그대로).
+    const left = openSites(src.split(HELPER).join(" ".repeat(HELPER.length)));
+    const why = helperDefect(scanFacts(src)) ?? (left.length ? `감싸지 않은 최상위 await import 가 남음 :${left.map((p) => src.slice(0, p).split("\n").length).join(", :")}` : null);
     return why ? { state: "misplaced", sites: [], why } : { state: "patched", sites: [] };
   }
   const all = scanTopLevelAwaitImports(src);
   if (!all.length) return { state: "n/a", sites: [] };
-  const open = all.filter((p) => !/Promise\.race/.test(src.slice(Math.max(0, p - 300), p)));
+  const open = openSites(src);
   if (!open.length) return { state: "guarded", sites: [] };
   return { state: "needs", sites: open };
 }
 
+// 적용이 감싸는 자리: 최상위 await import 가운데 바로 앞(300자)에 손으로 두른 Promise.race 가 없는 것.
+const openSites = (src) => scanTopLevelAwaitImports(src).filter((p) => !/Promise\.race/.test(src.slice(Math.max(0, p - 300), p)));
+
 // 헬퍼가 쓰일 수 없는 자리면 그 이유를, 제자리면 null 을 낸다.
 //   - 선언이 블록 안(깊이 1 이상): 다른 블록의 자리에서 ReferenceError(옛 킷이 남긴 자리)
 //   - 선언을 못 찾음: 이름만으로는 «패치됨» 이라 할 근거가 없다. 앞쪽 글을 토크나이저가 잘못
@@ -834,15 +856,33 @@ function patchHooks(root) {
   // 4.15.7 이 둘 다 겪었다 — PostToolUse 를 지우면 그 스크립트가 목록에서 빠지고(그래서
   // .omcbak 이 있어도 안 돌아온다), 손으로 고친 파일은 .omcbak 조차 없어 아예 안 보인다.
   const names = MODE === "revert" ? scriptNames(root, r) : hookNames(root);
+  // 고칠 훅을 하나도 찾지 못했으면 «실패 0건» 이 아니다. 목록이 빈 hooks.json(`{}`, `[]`)은 고친 것도 확인한 것도 없다.
+  // hooks.json 이 없거나 읽히지 않으면 [3/4] 가 이름과 이유를 대고 센다. 여기서는 읽혔는데 훅이 없을 때만 센다.
+  if (MODE !== "revert" && !names.length) {
+    if (readableFile(join(root, "hooks", "hooks.json"))) notChecked(r, join(root, "hooks", "hooks.json"), "hooks.json 이 부르는 훅(scripts/*.mjs)을 하나도 찾지 못함");
+    return r;
+  }
   for (const n of names) {
     const f = join(root, "scripts", `${n}.mjs`);
-    if (!existsSync(f)) continue;
-    if (MODE === "revert") revertScript(root, n, f, r);
-    else checkOrPatchScript(root, n, f, r);
+    if (MODE === "revert") { if (existsSync(f)) revertScript(root, n, f, r); continue; }
+    // hooks.json 이 부르는데 파일이 없으면 이름을 대고 센다. 그 밖에 볼 수 없으면(권한) readHook 이 이유를 대고 센다.
+    if (missingFile(f)) { notChecked(r, f, `hooks.json 이 부르는 훅 파일이 없음: ${shown(n)}`); continue; }
+    checkOrPatchScript(root, n, f, r);
   }
   return r;
 }
 
+// 확인하지 못한 것: 이름과 이유를 대고 실패로 센다. check 는 «모두 적용» 이라 하지 않게 읽지 못한 것으로도 센다.
+function notChecked(r, f, why) {
+  bad(why);
+  r.fail++;
+  r.failed.push(f);
+  if (MODE === "check") r.unread++;
+}
+
+const readableFile = (f) => { try { readRegular(f); return true; } catch { return false; } };
+const missingFile = (f) => { try { lstatSync(f); return false; } catch (e) { return e.code === "ENOENT"; } };
+
 // revert 가 훑는 이름: scripts/ 의 .mjs 전부. scripts/ 가 없는 판 폴더는 되돌릴 훅이 없어 한 줄로 알리고 넘어간다.
 // 그 밖에 목록을 읽지 못하면(파일, 권한) 이름과 이유를 대고 실패로 센다 — 다음 판과 [3/4], [4/4] 는 그대로 간다.
 function scriptNames(root, r) {
@@ -927,12 +967,20 @@ function handRestoreHint(bak, f) {
 
 // 백업의 내용으로 파일을 바꾼다. 쓰지 못하면 그 이유, 백업이 읽으려는 순간 사라졌으면 GONE, 아니면 null.
 const GONE = "백업이 먼저 사라짐";
+// 빈 백업이나 문법 검사를 통과하지 못하는 백업(잘린 복사)으로는 되돌리지 않는다. 쓴 뒤 검사에 걸리면 쓰기 전 글로 되돌린다.
 function restoreFrom(f, bak) {
   let data;
   try { data = readRegular(bak); }
   catch (e) { return e.code === "ENOENT" ? GONE : `읽지 못함: ${failWhy(e)}`; }
-  try { writeAtomic(f, data); return null; }
+  if (!data.length) return "백업이 비어 있음";
+  let before;
+  try { before = readRegular(f); writeAtomic(f, data); }
   catch (e) { return `쓰지 못함: ${failWhy(e)}`; }
+  const err = syntaxError(f);
+  if (!err) return null;
+  try { writeAtomic(f, before); }
+  catch (e) { return `백업이 문법 검사를 통과하지 못했고 원래 글로도 되돌리지 못함 (${failWhy(e)}): ${oneLine(err)}`; }
+  return `백업이 문법 검사를 통과하지 못함: ${oneLine(err)}`;
 }
 
 // 되돌린 뒤 백업을 지운다. 다른 실행이 먼저 지웠으면(ENOENT) 된 것이다. 못 지우면 그 이유, 아니면 null.
@@ -948,6 +996,9 @@ function checkOrPatchScript(root, n, f, r) {
   // 헬퍼 자리 결함은 check 와 apply 모두 이름을 댄다. 이미 감싼 파일이라 transform 으로는
   // 고칠 수 없으므로 apply 도 건드리지 않고, 되돌린 뒤 다시 적용하라고 안내한다(misplacedHint).
   if (info.state === "misplaced") { bad(`헬퍼 자리 결함: ${n} (${info.why})`); r.misplaced++; return; }
+  // 헬퍼 이름이 있어도 잘린 파일(복사가 끊김)은 돌지 않는다. 문법 검사를 통과해야 패치된 것으로 센다.
+  const broken = info.state === "patched" ? syntaxError(f) : null;
+  if (broken) { bad(`헬퍼 자리 결함: ${n} (패치된 파일이 문법 검사를 통과하지 못함: ${oneLine(broken)})`); r.misplaced++; return; }
   if (info.state !== "needs") { r.skip++; return; }
   const bak = `${f}.omcbak`;
   const why = whyNotWrite(root, f, bak);
@@ -1079,6 +1130,7 @@ function revertHooksJson(root, hj) {
   const bak = `${hj}.omcbak`;
   const saved = readBackup(bak);
   if (saved !== null) {
+    if (!isJson(saved)) { hjBad("hooks.json 을 되돌리지 않음 (백업이 비었거나 JSON 이 아님)"); return "unsafe"; }
     if (staleHooksJson(hj, saved)) { hjBad(`hooks.json 을 되돌리지 않음 (지금 파일에 PostToolUse 가 있고 백업과 글이 다름. 백업이 옛 원본일 수 있음)`); return "unsafe"; }
     writeAtomic(hj, saved);
     log(`  되돌림  ${hjTag}hooks.json`);
@@ -1102,9 +1154,14 @@ function revertHooksJson(root, hj) {
     return "reverted";
   }
   if (usable.length > 1) { hjBad(`hooks.json 수동 백업이 여러 개라 자동 복구하지 않음: ${usable.map(shown).join(", ")}`); return "ambiguous"; }
-  return unsafe.length ? "linked" : "no-backup";
+  if (unsafe.length) return "linked";
+  // 깨진 hooks.json 에 되돌릴 백업도 없으면 «이 도구가 지운 적 없음» 이라 할 근거가 없다. 그대로 두고 실패로 센다.
+  if (!isJson(readHooksJson(hj))) { hjBad("hooks.json 이 JSON 이 아니고 되돌릴 백업도 없음"); return "unsafe"; }
+  return "no-backup";
 }
 
+const isJson = (text) => { try { JSON.parse(String(text)); return true; } catch { return false; } };
+
 // 파일에서 읽은 값(파일 이름, PINNED 의 host)과 출력하는 경로를 출력에 넣을 때 쓴다. 줄바꿈과 제어 문자를 ? 로 바꾸고 길이를 자른다.
 // SKILL 은 [!] 줄을 그대로 보고하라고 하므로, 값이 제 줄을 새로 시작하면 도구가 낸 줄처럼 읽힌다.
 // 바꾸는 문자: 제어 문자(Cc), 서식 문자(Cf: 폭 없는 공백, 방향 표시, 단어 결합자, 태그 문자), 줄과 문단 구분자,
@@ -1270,7 +1327,7 @@ function removePostToolUse(hj, why) {
 // 고정과 되돌리기가 하지 않은 일을 했다고 끝난다.
 function originUrl() {
   try { return git(["config", "--get", "remote.origin.url"]); }
-  catch (e) { return e.status === 1 ? null : { unreadable: gitLine(e) }; }
+  catch (e) { return e.status === 1 && !String(e.stderr || "").trim() ? null : { unreadable: gitLine(e) }; }
 }
 
 // git 오류의 원인 줄: `fatal:` 이나 `error:` 로 시작하는 첫 줄, 없으면 첫 줄(`warning:` 이 먼저 올 수 있다), 정화하고
@@ -1688,7 +1745,8 @@ for (const v of targets) {
   else if (hj === "needs") hjNeedBy[v] = true;
   else if (hj === "reverted" || hj === "ambiguous" || hj === "linked") { /* patchHooksJson 이 출력함 */ }
   else if (hj === "no-backup") ok(`${tag}되돌릴 백업 없음 (이 도구가 지운 적 없음)`);
-  else if (hj === "no-file") bad(`${tag}hooks.json 파일 자체가 없음`);
+  // 판 폴더에 hooks.json 이 없으면 고친 것도 확인한 것도 없다. 실패로 센다.
+  else if (hj === "no-file") { bad(`${tag}hooks.json 파일 자체가 없음`); r.fail++; hjFailBy[v] = true; failed.add(fileKey(join(root, "hooks", "hooks.json"))); }
   // "failed" 는 고친 hooks.json 이 JSON 으로 읽히지 않아 되돌린 경우다. 고치지 못했으니 실패로 센다.
   else if (hj === "unsafe" || hj === "failed") { r.fail++; hjFailBy[v] = true; failed.add(fileKey(join(root, "hooks", "hooks.json"))); }
   if (hj === "ambiguous" || hj === "linked") left.add(fileKey(join(root, "hooks", "hooks.json")));

package/skills/ralph-qa/SKILL.md

@@ -408,6 +408,7 @@ node '<R>/gate-evidence.mjs' cleanup --dir '<g>'
 
 ### 3. 판정 수신
 각 좌석에서 4값 중 하나를 받는다. 외부 좌석은 **단독 줄 `VERDICT: <값>`** 이 필수이며, 부재·중복·절단·파싱실패·거부는 `ERROR` 다.
+코드펜스(```, ~~~) 안의 `VERDICT:` 줄은 인용한 글이라 세지 않는다. 판정 줄을 코드펜스로 감싼 답은 판정 줄이 없는 답이라 `ERROR` 다. send 출력의 `answered`, `failed` 는 답한 좌석과 실패한 좌석의 수다. `ok: true` 는 send 가 돌았다는 뜻일 뿐이고, 실패한 좌석의 `facts` 에는 `verdict` 가 없다.
 
 **나눠 보낸 페이로드.** 한 좌석에 나눠 보낸 부분들은 그 좌석의 한 판정이다. 모든 부분이 `APPROVE` 일 때만 `APPROVE`, 하나라도 `ERROR` 면 `ERROR`, 그 밖은 가장 나쁜 값(`REJECT` 가 `ITERATE` 보다 나쁘다)이다. 부분끼리는 서로의 내용을 모르므로 좌석 줄에 `분할 N` 을 적는다.
 

package/skills/ralph-qa/references/seat-run.mjs

@@ -601,11 +601,24 @@ const readText = (file) => {
   }
 };
 
+// The standalone verdict lines of an answer. A line inside a code fence (``` or ~~~) is quoted text, not the seat's verdict.
+export function verdictLines(out) {
+  let fence = null;
+  const found = [];
+  for (const line of out.split(/\r?\n/)) {
+    const mark = /^\s{0,3}(`{3,}|~{3,})/.exec(line);
+    if (mark && (!fence || (mark[1][0] === fence[0] && mark[1].length >= fence.length))) { fence = fence ? null : mark[1]; continue; }
+    const m = !fence && VERDICT_LINE.exec(line);
+    if (m) found.push(m[1]);
+  }
+  return found;
+}
+
 // What a seat's answer and errors say.
 function factsOf(cli, plan) {
   const out = readText(plan.answer);
   const err = readText(plan.stderr);
-  const facts = { verdicts: out.split(/\r?\n/).map((l) => VERDICT_LINE.exec(l)).filter(Boolean).map((m) => m[1]), empty: !out.trim() };
+  const facts = { verdicts: verdictLines(out), empty: !out.trim() };
   if (cli === "codex") facts.ranModel = (/^model: (\S+)/m.exec(err.split("\n").slice(0, 40).join("\n")) || [])[1] || null;
   if (cli === "gemini") Object.assign(facts, { policyError: err.includes("Policy file error"), apiError: err.includes("Full report") });
   if (cli === "opencode") facts.fallback = err.includes("Falling back to default agent");
@@ -665,10 +678,12 @@ async function runParts(ctx, run, seat, g, parts, base) {
   }
   const last = done[done.length - 1];
   const secs = Math.round(done.reduce((t, x) => t + (x.r.secs || 0), 0) * 10) / 10;
+  // a failed seat has no verdict to count, so its facts carry none (a reader that skips `status` would count it)
+  const shownFacts = (x) => { const f = factsShown(x.f); if (x.why) delete f.verdict; return f; };
   const result = { ...base, status: last.why ? "failed" : "answered", why: last.why, exit: last.r.exit, signal: last.r.signal, secs,
-    answer: last.plan.answer, errors: last.plan.stderr, facts: factsShown(last.f) };
+    answer: last.plan.answer, errors: last.plan.stderr, facts: shownFacts(last) };
   if (!last.why && parts.length > 1) result.facts.verdict = gathered(done.map((x) => x.f.verdicts[0]));
-  if (parts.length > 1) result.parts = done.map((x) => ({ answer: x.plan.answer, errors: x.plan.stderr, why: x.why, facts: factsShown(x.f) }));
+  if (parts.length > 1) result.parts = done.map((x) => ({ answer: x.plan.answer, errors: x.plan.stderr, why: x.why, facts: shownFacts(x) }));
   return result;
 }
 
@@ -838,7 +853,9 @@ async function send(o, ctx) {
     if (thrown) throw thrown.reason;
     const seats = settled.map((x) => x.value);
     if (!a.dryRun) appendFileSync(join(d, "run.md"), seats.filter((x) => x.cliVersion).map((x) => `cli-${x.seat} ${x.cliVersion}\n`).join(""), { mode: 0o600 });
-    const result = { ok: true, ...(a.dryRun ? { dryRun: true } : {}), dir: d, out, bytes: payload.length, scan: 0, unsent: unsentCount(d), seats, declared: declared(run, payload.length, seats, d) };
+    // ok says the send ran; whether seats answered is in `answered`, `failed` and each seat's status
+    const answered = seats.filter((x) => x.status === "answered").length;
+    const result = { ok: true, ...(a.dryRun ? { dryRun: true } : {}), dir: d, out, bytes: payload.length, scan: 0, unsent: unsentCount(d), answered, failed: seats.filter((x) => x.status === "failed").length, seats, declared: declared(run, payload.length, seats, d) };
     if (!a.dryRun) writeResult(d, "send", resultJson("send", result));
     return [result, signals.code(), a.dryRun ? null : d];
   } finally {