geobuke-code 0.1.0 → 0.2.1

package/README.md

@@ -21,7 +21,17 @@
 
 ## 설치
 
-> ⚠️ **현재 npm 미발행** — 아래 **로컬 개발 설치**가 유일한 경로다. (`npm install -g geobuke-code` 공개배포는 후속 A(public) 단계.)
+```bash
+# 1) 전역 설치
+npm install -g geobuke-code
+
+# 2) 대상 프로젝트에 게이트 설치
+cd <your-project>
+gbc init                          # .claude/settings.json에 hook + /gate skill 머지 (동의·백업)
+```
+
+<details>
+<summary>로컬 개발 설치 (소스에서 빌드)</summary>
 
 ```bash
 # 1) 클론 + 빌드 (dist/ 생성)
@@ -36,32 +46,37 @@ printf '#!/bin/sh\nexec node "%s/dist/cli.js" "$@"\n' "$PWD" > ~/.local/bin/gbc
 
 # 3) 대상 프로젝트에 게이트 설치
 cd <your-project>
-gbc init                          # .claude/settings.json에 hook + /gate skill 머지 (동의·백업)
+gbc init
 ```
 
-`gbc init`은 **프로젝트 로컬 `.claude/settings.json`만** 머지한다(append·멱등·백업). 전역 `~/.claude`는 건드리지 않는다.
-
 소스를 수정하면 `npm run build`만 다시 하면 된다 — wrapper/link는 같은 `dist/cli.js`를 가리키므로 재연결 불필요.
 
+</details>
+
+`gbc init`은 **프로젝트 로컬 `.claude/settings.json`만** 머지한다(append·멱등·백업). 전역 `~/.claude`는 건드리지 않는다. hook 명령은 **셸 무관 순수 형태**(`node "<path>" hook pre-tool-use`)라 Windows(cmd.exe)/bash/zsh/Mac에서 동일하게 동작한다.
+
 ## 빠른 게이트 활성화 (API 키 — 선택)
 
-`gbc init`은 키 주입 **없는** hook을 설치한다 → 기본은 `claude -p` 폴백(~13–20s). **haiku 직접 API(~1–3s)**를 쓰려면 키를 **hook 명령에만** 주입한다.
+키가 없으면 `claude -p` 폴백(~13–20s)으로 무설정 동작한다. **haiku 직접 API(~1–3s)**를 쓰려면 **키 파일만 만들면 된다** — gbc가 실행 시 직접 읽으므로 settings.json 수정이나 셸 주입은 불필요하다(0.2.1+).
+
+> ⚠️ **native Windows에선 API 키가 사실상 필수다.** `claude -p` 폴백은 `claude.cmd`(배치 shim)를 셸 없이 실행하지 못해(ENOENT) fail-open으로 빠질 수 있다. Windows에선 위 키 파일을 만들어 API 경로로 쓰는 것을 권장한다(WSL/Mac/Linux는 폴백 정상).
 
-> ⚠️ **`export ANTHROPIC_API_KEY=…` 전역 설정 금지.** Claude Code 본체가 그 키로 **과금 전환**된다(구독 대신 키 과금). 게이트 hook 서브프로세스에만 주입해야 안전하다.
+키 해석 순서: `ANTHROPIC_API_KEY` 환경변수 > `~/.gbc/api-key` 파일.
 
 ```bash
-# 1) 키를 파일에 저장 (권한 600)
+# bash / zsh / WSL / Mac
 mkdir -p ~/.gbc && printf '%s' 'sk-ant-...' > ~/.gbc/api-key && chmod 600 ~/.gbc/api-key
 ```
 
-```jsonc
-// 2) 대상 프로젝트 .claude/settings.json의 PreToolUse command 앞에 키 주입을 추가:
-//    "command": "node \"…/dist/cli.js\" hook pre-tool-use"
-// →
-"command": "ANTHROPIC_API_KEY=\"$(cat ~/.gbc/api-key)\" node \"…/dist/cli.js\" hook pre-tool-use"
+```powershell
+# native Windows (PowerShell) — -NoNewline 필수(끝에 개행 붙으면 키 오염)
+New-Item -ItemType Directory -Force -Path "$HOME\.gbc" | Out-Null
+Set-Content -Path "$HOME\.gbc\api-key" -Value "sk-ant-..." -NoNewline
 ```
 
-`gbc status`엔 `트랜스포트: cli`로 보일 수 있다(status 명령 자체엔 키가 없어서). 무관하다 — 실제 hook 발동 시엔 위 주입으로 `api(haiku)` 경로로 동작한다.
+> ⚠️ **`export ANTHROPIC_API_KEY=…` 전역 설정(또는 settings.json top-level `env`) 금지.** Claude Code 본체가 그 키로 **과금 전환**된다(구독 대신 키 과금). 키 파일 방식은 gbc 판정 호출에만 키가 쓰이므로 이 함정을 구조적으로 피한다.
+
+`gbc status`는 키 파일/환경변수를 반영해 `트랜스포트: api`로 표시한다(0.2.1+).
 
 ## 동작 원리
 
@@ -91,12 +106,12 @@ phase-protocol/계획 → /plan(SubTask) → 【게이트: 구현 직전 케이
 
 | 조건 | 트랜스포트 | 지연 |
 |---|---|---|
-| `ANTHROPIC_API_KEY` 설정됨 | Anthropic API 직접 (haiku, 최소 시스템프롬프트) | ~1–3s (목표) |
-| 미설정 | `claude -p` 폴백 (CC 인증 재사용, 무설정) | ~13–20s |
+| 키 있음 (`ANTHROPIC_API_KEY` env 또는 `~/.gbc/api-key` 파일) | Anthropic API 직접 (haiku, 최소 시스템프롬프트) | ~1–3s (목표) |
+| 키 없음 | `claude -p` 폴백 (CC 인증 재사용, 무설정 / ⚠️native Windows 미지원) | ~13–20s |
 
 **작업단위 1회**: 게이트는 작업단위(계획 명세 해시)당 한 번만 발동한다. 명세가 바뀌거나 명세 밖 파일을 편집할 때만 재발동 → 매 편집 지연을 피한다.
 
-> 빠른 게이트를 원하면 `ANTHROPIC_API_KEY`를 설정하라(설정법·과금 주의: 위 [「빠른 게이트 활성화」](#빠른-게이트-활성화-api-키--선택)). 없으면 `claude -p` 폴백으로 무설정 동작하되 작업단위당 한 번 느리다.
+> 빠른 게이트를 원하면 `~/.gbc/api-key` 키 파일을 만들어라(설정법·과금 주의: 위 [「빠른 게이트 활성화」](#빠른-게이트-활성화-api-키--선택)). 없으면 `claude -p` 폴백으로 무설정 동작하되 작업단위당 한 번 느리다.
 
 ## 명령
 
@@ -111,16 +126,29 @@ phase-protocol/계획 → /plan(SubTask) → 【게이트: 구현 직전 케이
 | `gbc spec show` | 등록된 케이스 목록 |
 | `gbc spec clear` | 명세 비우기(작업단위 종료) |
 | `gbc gate reset` | 작업단위 게이트 리셋 |
+| `gbc metrics [--json]` | 계측 리포트(M1~M3) |
 
 우회: `GBC_NO_GATE=1` (계측됨 — 우회 자체가 게이트 가치 측정 데이터).
 
+## 계측 (M1~M3)
+
+게이트는 모든 결정을 `.gbc/events.jsonl`(append-only, 메타데이터만 — 코드 본문 미기록)에 기록한다. `gbc metrics`로 집계를 본다. 끄려면 `GBC_NO_METRICS=1`.
+
+| 지표 | 관측 | B-모드 신뢰도 |
+|---|---|---|
+| **M2** 게이트 적중 vs 도중발견 | 차단이 잡은 누락 케이스 수 vs `defer add`로 도중 등록된 수 | **강** (defer-registry와 1:1) |
+| **M3** 재호출/iteration | 작업단위당 편집 반복 횟수 | proxy |
+| **M1** post-gate 재작업 | 통과 후 churn(spec 변경·gate reset·defer) | **약** (churn proxy) |
+
+> ⚠️ **진짜 M1**(통과 후 시나리오 위반율)은 게이트가 엔진 출력을 채점하는 **사후 대조**가 필요하다 — 이는 후속 A(standalone) 모드 영역이다. B-커널(hook)은 churn 약신호만 관측한다. `events.jsonl` 원시 로그는 그때 그대로 재사용된다.
+
 ## 정직한 한계
 
 - 사후 대조가 아닌 **구현 전 게이트**다 — "도중 탈선"은 못 잡는다(설계상 후속 C 영역).
 - 판정은 LLM이라 100% 아니다. **사람이 변이 전 케이스를 리뷰/편집하는 pause**가 진짜 가치다.
-- MVP scope = **B-커널**(CC-native hook + defer-registry + /gate). standalone TUI·추출 모드·계측 대시보드는 후속.
+- MVP scope = **B-커널**(CC-native hook + defer-registry + /gate). standalone TUI·추출 모드는 후속 A(public). 계측은 B-모드 관측 프록시(M1~M3)까지 구현됨(위 [계측](#계측-m1m3)).
 - **검증 상태**: 게이트 판정 품질은 **양 트랜스포트 모두 회귀 8/8(FP0 FN0)**. 직접 API(haiku) 경로 실측 **평균 1.7s**(1.1–2.5s), claude -p 폴백 ~18s. 직접 API용 게이트 프롬프트는 최소화하면서 정확도를 유지하도록 "동작 편집 vs 비-동작 편집" 2단계 분류로 튜닝했다(`ANTHROPIC_API_KEY=… node dist/eval/regression.js`로 재현).
-- **fail-open**: 판정 호출이 실패하면(키 오류·네트워크 등) 게이트는 조용히 통과시킨다(개발 차단 방지). 게이트가 무력화돼도 경고가 약하다는 트레이드오프 — 후속 관찰 항목.
+- **fail-open**: 판정 호출이 실패하면(키 오류·네트워크 등) 게이트는 안전하게 통과시킨다(개발 차단 방지). 단 fail-open 통과는 작업단위 캐시에서 제외되고(다음 편집 재판정), `systemMessage` 경고 + `.gbc/failopen.log` 계측으로 드러난다(조용한 무력화 방지).
 
 ## 라이선스
 

package/dist/cli.js

@@ -9,7 +9,8 @@ import { loadPlanSpec, computeSpecHash, addSpecCase, readSpecCases, clearSpec }
 import { loadState, resetGate } from "./state.js";
 import { addDefer, loadDefers, resolveDefer } from "./defer.js";
 import { selectedTransport } from "./judge.js";
-import { buildPreCommand, upgradeKeylessHooks } from "./install.js";
+import { buildPreCommand, normalizeHooks } from "./install.js";
+import { logEvent, parseEvents, computeMetrics } from "./metrics.js";
 const CLI_PATH = fileURLToPath(import.meta.url);
 const PKG_ROOT = join(dirname(CLI_PATH), ".."); // dist/cli.js → 패키지 루트
 /** ~/.gbc/api-key 존재 여부 — 있으면 hook에 키 주입(빠른 haiku 경로). */
@@ -19,6 +20,26 @@ function hasApiKey() {
 function stopCommand() {
     return `node "${CLI_PATH}" hook stop`;
 }
+function nowIso() {
+    try {
+        return new Date().toISOString();
+    }
+    catch {
+        return "";
+    }
+}
+/**
+ * 현재 작업단위 명세 해시 (CLI 이벤트의 specHash 상관 키).
+ * 빈 spec은 ""(센티넬) — M1 churn 교차세션 합산 방지(computeMetrics가 제외).
+ */
+function curHash(cwd) {
+    const text = loadPlanSpec(cwd).text;
+    return text.trim() === "" ? "" : computeSpecHash(text);
+}
+/** CLI 변이 이벤트를 events.jsonl에 기록(메트릭 상관용). specHash는 변이 전 값을 넘긴다. */
+function logCli(cwd, kind, specHash) {
+    logEvent(cwd, { at: nowIso(), session: "", specHash, kind });
+}
 function nowStamp() {
     try {
         return new Date().toISOString().replace(/[:.]/g, "-");
@@ -42,8 +63,10 @@ function cmdInit(args) {
   1) ${settingsPath} 에 PreToolUse(Edit|Write) + Stop hook 추가 (머지·멱등)
      - 기존 settings.json 있으면 백업: settings.json.bak-<시각>
   2) ${join(skillDestDir, "SKILL.md")} 에 /gate 스킬 설치
-  3) hook 명령: ${buildPreCommand(CLI_PATH, hasApiKey())}
-
+  3) hook 명령: ${buildPreCommand(CLI_PATH)}
+${hasApiKey()
+            ? "     (~/.gbc/api-key 감지됨 → 빠른 haiku API 경로로 동작)"
+            : "     (~/.gbc/api-key 없음 → claude -p 폴백. 빠른 경로 원하면 키 파일 생성)"}
   실행하려면: gbc init --yes
 `);
         return;
@@ -65,21 +88,20 @@ function cmdInit(args) {
     }
     const hooks = (settings.hooks ??= {});
     const serialized = JSON.stringify(settings);
-    const useKey = hasApiKey();
-    // PreToolUse (멱등). 신규면 추가, 이미 있으면 keyless→키주입 업그레이드(skip만 하지 않음).
+    // PreToolUse (멱등). 신규면 추가, 이미 있으면 옛 명령(keyless·bash 키주입)을 pure로 정규화.
     if (!serialized.includes("hook pre-tool-use")) {
         (hooks.PreToolUse ??= []).push({
             matcher: "Edit|Write|MultiEdit",
-            hooks: [{ type: "command", command: buildPreCommand(CLI_PATH, useKey) }],
+            hooks: [{ type: "command", command: buildPreCommand(CLI_PATH) }],
         });
-        console.log(`  + PreToolUse hook 추가${useKey ? " (API 키 주입)" : ""}`);
+        console.log(`  + PreToolUse hook 추가`);
     }
     else {
-        const n = useKey ? upgradeKeylessHooks(settings, CLI_PATH, true) : 0;
+        const n = normalizeHooks(settings, CLI_PATH);
         if (n > 0)
-            console.log(`  ↑ PreToolUse hook 키주입 업그레이드 (${n}건)`);
+            console.log(`  ↑ PreToolUse hook 정규화 (${n}건, 셸 무관 명령으로)`);
         else
-            console.log(`  = PreToolUse hook 이미 존재 (skip)`);
+            console.log(`  = PreToolUse hook 이미 표준 (skip)`);
     }
     // Stop (멱등)
     if (!serialized.includes("hook stop")) {
@@ -133,6 +155,7 @@ function cmdDefer(args) {
             process.exit(1);
         }
         addDefer(cwd, item);
+        logCli(cwd, "defer-add", curHash(cwd));
         console.log(`🐢 미룸 등록: ${item}`);
     }
     else if (sub === "list") {
@@ -146,6 +169,8 @@ function cmdDefer(args) {
     else if (sub === "resolve") {
         const ref = args.slice(1).join(" ").trim();
         const r = resolveDefer(cwd, ref);
+        if (r)
+            logCli(cwd, "defer-resolve", curHash(cwd));
         console.log(r ? `🐢 해결 표시: ${r.item}` : `매칭되는 미룬 항목 없음: ${ref}`);
     }
     else {
@@ -163,7 +188,9 @@ function cmdSpec(args) {
             console.error('사용: gbc spec add "<케이스/시나리오>"');
             process.exit(1);
         }
+        const beforeHash = curHash(cwd); // 변이 전 해시 = 수정 대상 작업단위와 상관
         addSpecCase(cwd, item);
+        logCli(cwd, "spec-add", beforeHash);
         console.log(`🐢 명세 등록: ${item}`);
     }
     else if (sub === "show") {
@@ -175,7 +202,9 @@ function cmdSpec(args) {
         cases.forEach((c, i) => console.log(`${i + 1}. ${c}`));
     }
     else if (sub === "clear") {
+        const beforeHash = curHash(cwd);
         clearSpec(cwd);
+        logCli(cwd, "spec-clear", beforeHash);
         console.log("🐢 명세 비움 — 다음 작업단위로 깨끗이 넘어갑니다.");
     }
     else {
@@ -186,7 +215,9 @@ function cmdSpec(args) {
 // ---------- gbc gate ----------
 function cmdGate(args) {
     if (args[0] === "reset") {
-        resetGate(process.cwd());
+        const cwd = process.cwd();
+        logCli(cwd, "gate-reset", curHash(cwd));
+        resetGate(cwd);
         console.log("🐢 작업단위 게이트 리셋 — 다음 편집에서 다시 발동합니다.");
     }
     else {
@@ -194,6 +225,30 @@ function cmdGate(args) {
         process.exit(1);
     }
 }
+// ---------- gbc metrics ----------
+function cmdMetrics(args) {
+    const cwd = process.cwd();
+    const eventsPath = join(cwd, ".gbc", "events.jsonl");
+    const raw = existsSync(eventsPath) ? readFileSync(eventsPath, "utf8") : "";
+    const m = computeMetrics(parseEvents(raw));
+    if (args.includes("--json")) {
+        console.log(JSON.stringify(m, null, 2));
+        return;
+    }
+    console.log(`🐢 거북이 게이트 계측 — ${cwd}
+  이벤트 총 ${m.totalEvents}건  (.gbc/events.jsonl)
+
+  [M3] 재호출/iteration — 작업단위당 edit 반복
+    작업단위 ${m.m3.workUnits} · 총 edit ${m.m3.totalEdits} · 평균 ${m.m3.avgEditsPerUnit}/단위 · 최대 ${m.m3.maxEditsPerUnit} · 반복(>1)단위 ${m.m3.multiEditUnits}
+
+  [M2] 게이트 적중 vs 도중발견
+    게이트 적중(차단 누락케이스) ${m.m2.gateCaught} · 차단 ${m.m2.blocks}회
+    도중발견(defer 등록) ${m.m2.deferred} · 도중발견 비율 ${(m.m2.midDiscoveryRatio * 100).toFixed(1)}%
+
+  [M1] post-gate 재작업
+    게이트 리셋 ${m.m1.resets} · 통과후 churn ${m.m1.churnAfterPass}
+    ⚠️ ${m.m1.note}`);
+}
 function usage() {
     console.log(`🐢 gbc — 거북이코드 구현-전 게이트
 
@@ -207,6 +262,7 @@ function usage() {
   gbc spec show                       등록된 케이스 목록
   gbc spec clear                      명세 비우기(작업단위 종료)
   gbc gate reset                      작업단위 게이트 리셋
+  gbc metrics [--json]                계측 리포트(M1~M3, B-모드 관측 프록시)
   gbc hook pre-tool-use               (내부) PreToolUse hook
   gbc hook stop                       (내부) Stop hook
 `);
@@ -232,6 +288,8 @@ async function main() {
             return cmdSpec(rest);
         case "gate":
             return cmdGate(rest);
+        case "metrics":
+            return cmdMetrics(rest);
         case undefined:
         case "help":
         case "--help":

package/dist/hook.js

@@ -8,6 +8,7 @@ import { activeDeferItems, unresolvedDefers, loadDefers } from "./defer.js";
 import { appendFileSync } from "node:fs";
 import { join } from "node:path";
 import { gbcDir } from "./store.js";
+import { logEvent } from "./metrics.js";
 /**
  * 차단 사유 메시지를 빌드한다. 두 차단 종류를 다르게 안내한다:
  * - specEmpty=true (시나리오 미지정): 에이전트가 요청에서 시나리오를 도출 → 사용자 검증 →
@@ -48,6 +49,14 @@ function readStdin() {
 function emit(obj) {
     process.stdout.write(JSON.stringify(obj));
 }
+function nowIso() {
+    try {
+        return new Date().toISOString();
+    }
+    catch {
+        return "";
+    }
+}
 function logBypass(cwd, toolName) {
     try {
         appendFileSync(join(gbcDir(cwd), "bypass.log"), `${new Date().toISOString()} ${toolName}\n`);
@@ -78,19 +87,34 @@ export async function runPreToolUse() {
     }
     const toolName = input.tool_name ?? "";
     const cwd = input.cwd || process.cwd();
+    const session = input.session_id ?? "";
     // 코드 변경 도구가 아니면 즉시 통과
     if (!isGatedTool(toolName))
         process.exit(0);
     // 명시적 우회 (계측됨)
     if (process.env.GBC_NO_GATE === "1") {
         logBypass(cwd, toolName);
+        logEvent(cwd, { at: nowIso(), session, specHash: "", kind: "bypass", tool: toolName });
         process.exit(0);
     }
     const { text: specText, source } = loadPlanSpec(cwd);
     const specHash = computeSpecHash(specText);
+    // 계측용 해시: 빈 spec은 ""(센티넬)로 기록 → M1 churn 교차세션 합산 방지.
+    // (게이트 캐시용 specHash는 그대로 — markGated/isGated 동작 불변)
+    const logHash = specText.trim() === "" ? "" : specHash;
     // 작업단위 1회: 이미 게이트 통과한 단위면 즉시 통과 (judge 미호출, 핫패스)
-    if (isGated(cwd, specHash))
+    // 계측: cached-skip도 기록해야 M3(작업단위당 edit 반복)이 진짜 횟수를 잡는다.
+    if (isGated(cwd, specHash)) {
+        logEvent(cwd, {
+            at: nowIso(),
+            session,
+            specHash: logHash,
+            kind: "gate",
+            tool: toolName,
+            decision: "cached",
+        });
         process.exit(0);
+    }
     // judge는 여기서만 동적 import (SDK lazy)
     const { judge } = await import("./judge.js");
     const editText = normalizeEdit(toolName, input.tool_input ?? {});
@@ -99,11 +123,28 @@ export async function runPreToolUse() {
     if (verdict.verdict === "pass") {
         if (shouldCacheVerdict(verdict)) {
             markGated(cwd, specHash, verdict.reason);
+            logEvent(cwd, {
+                at: nowIso(),
+                session,
+                specHash: logHash,
+                kind: "gate",
+                tool: toolName,
+                decision: "pass",
+                deferCount: defers.length,
+            });
             process.exit(0); // 정상 통과 (자동승인 X — 무출력)
         }
         // fail-open: 판정 실패로 안전 통과. 캐시하지 않아(작업단위 무력화 방지) 다음 편집에서 재판정.
         // 계측 + systemMessage로 사용자에게 "게이트가 검사 못 했음"을 알린다(조용한 무력화 방지).
         logFailOpen(cwd, toolName, verdict.reason);
+        logEvent(cwd, {
+            at: nowIso(),
+            session,
+            specHash: logHash,
+            kind: "gate",
+            tool: toolName,
+            decision: "failopen",
+        });
         emit({
             systemMessage: `🐢 거북이 게이트 — 판정 실패로 안전 통과(fail-open). 이 편집은 게이트 검사를 받지 못했습니다: ${verdict.reason}`,
             hookSpecificOutput: {
@@ -117,6 +158,16 @@ export async function runPreToolUse() {
     // block: 사람 pause (ask 기본) — 사유가 사용자에게 표시됨
     // 시나리오 미지정(명세 빈약)과 침묵 누락을 다르게 안내한다.
     const reason = buildBlockReason(verdict, specText.trim() === "", source);
+    logEvent(cwd, {
+        at: nowIso(),
+        session,
+        specHash: logHash,
+        kind: "gate",
+        tool: toolName,
+        decision: "block",
+        missing: verdict.missing,
+        deferCount: defers.length,
+    });
     const mode = process.env.GBC_BLOCK_MODE === "deny" ? "deny" : "ask";
     emit({
         hookSpecificOutput: {

package/dist/install.js

@@ -1,39 +1,33 @@
 // gbc init 설치 로직 (순수함수 — cli.ts main() 부작용 없이 단위테스트 가능).
-// 키 주입은 셸 확장($HOME)으로 머신 독립적이게 한다(하드코딩 홈경로 금지).
+// 키 주입은 셸이 아니라 gbc 코드(judge.ts resolveApiKey)가 처리한다 → hook 명령은
+// 셸 무관 순수 형태라 native Windows(cmd.exe)/bash/zsh/Mac에서 동일하게 동작한다.
 /**
- * PreToolUse hook 명령 생성.
- * useKey=true면 ANTHROPIC_API_KEY를 $HOME/.gbc/api-key에서 읽어 주입(빠른 haiku 경로).
- * 경로는 셸이 확장하는 $HOME을 써 머신 독립적이게 한다.
+ * PreToolUse hook 명령 생성 — 셸 무관 순수 명령.
+ * `node "<cliPath>" hook pre-tool-use` 형태만 생성한다. 키 주입(셸 prefix)·셸 확장 없음.
+ * - cliPath는 큰따옴표로만 감싼다(공백 포함 경로 안전). 큰따옴표는 cmd.exe·POSIX sh 공통.
+ * - 백슬래시를 이스케이프하지 않는다: Windows 경로(C:\...)의 구분자이며, settings.json에
+ *   기록될 때 cli.ts의 JSON.stringify가 `\`→`\\` 처리를 담당한다(여기서 또 하면 이중).
+ * - cliPath는 import.meta.url 기반 설치 경로(사용자 입력 아님)라 셸 인젝션 위험이 실질적으로
+ *   없어 별도 메타문자 이스케이프를 두지 않는다(이전 shDquote 방어 제거 — 보안 재검토 반영).
  */
-/**
- * 더블쿼트 컨텍스트용 이스케이프. 셸이 확장하거나 따옴표를 벗어나지 못하도록
- * `"` 백틱 `$` `\` 를 백슬래시 처리한다(settings.json 명령 인젝션 방지).
- */
-function shDquote(s) {
-    return s.replace(/(["`$\\])/g, "\\$1");
-}
-export function buildPreCommand(cliPath, useKey) {
-    const base = `node "${shDquote(cliPath)}" hook pre-tool-use`;
-    // $HOME·$(...)는 의도된 셸 확장이므로 이스케이프하지 않는다.
-    return useKey ? `ANTHROPIC_API_KEY="$(cat "$HOME/.gbc/api-key")" ${base}` : base;
+export function buildPreCommand(cliPath) {
+    return `node "${cliPath}" hook pre-tool-use`;
 }
 /**
- * 이미 설치된 keyless PreToolUse hook command를 키 주입 버전으로 업그레이드.
- * settings를 제자리 수정하고, 업그레이드한 건수를 반환한다(멱등: 이미 키주입된 건 건너뜀).
+ * 기존 PreToolUse hook 명령을 현재 표준(셸 무관 pure 명령)으로 정규화한다.
+ * keyless 명령·옛 bash 키주입 prefix 명령을 모두 pure로 교체 → "모든 OS 동일 명령" 목표 달성.
+ * settings를 제자리 수정하고 변경 건수를 반환한다(멱등: 이미 표준이면 0건).
  */
-export function upgradeKeylessHooks(settings, cliPath, useKey) {
-    if (!useKey)
-        return 0;
-    const target = buildPreCommand(cliPath, true);
-    let upgraded = 0;
+export function normalizeHooks(settings, cliPath) {
+    const target = buildPreCommand(cliPath);
+    let changed = 0;
     for (const entry of settings.hooks?.PreToolUse ?? []) {
         for (const h of entry.hooks ?? []) {
-            // pre-tool-use hook인데 아직 키 주입이 없으면(keyless) 교체
-            if (h.command.includes("hook pre-tool-use") && !h.command.includes("ANTHROPIC_API_KEY")) {
+            if (h.command.includes("hook pre-tool-use") && h.command !== target) {
                 h.command = target;
-                upgraded++;
+                changed++;
             }
         }
     }
-    return upgraded;
+    return changed;
 }

package/dist/judge.js

@@ -1,7 +1,31 @@
 import { execFile } from "node:child_process";
 import { promisify } from "node:util";
+import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
 const execFileAsync = promisify(execFile);
 const MODEL = process.env.GBC_MODEL ?? "claude-haiku-4-5";
+/**
+ * API 키 해석 (크로스플랫폼, 셸 무관).
+ * 1) ANTHROPIC_API_KEY 환경변수 우선, 2) 없으면 ~/.gbc/api-key 파일.
+ * STUB
+ */
+export function resolveApiKey(opts = {}) {
+    const env = opts.env ?? process.env;
+    const fromEnv = env.ANTHROPIC_API_KEY;
+    if (fromEnv && fromEnv.trim())
+        return fromEnv;
+    const home = opts.homeDir ?? homedir();
+    const read = opts.readFile ?? ((p) => readFileSync(p, "utf8"));
+    try {
+        // bash `$(cat)`는 trailing newline을 벗기지만 readFileSync는 안 벗긴다 → 명시 trim 필수.
+        const key = read(join(home, ".gbc", "api-key")).trim();
+        return key || null;
+    }
+    catch {
+        return null; // 파일 부재/읽기 실패 → 키 없음(claude -p 폴백)
+    }
+}
 /**
  * 최소 게이트 시스템 프롬프트.
  * 의미론(핵심): 한 편집이 모든 케이스를 *완전 구현*할 필요는 없다.
@@ -53,15 +77,16 @@ function parseVerdict(raw) {
         reason: typeof j.reason === "string" ? j.reason : "",
     };
 }
-/** 트랜스포트 선택 결과 (디버그/리포트용) */
+/** 트랜스포트 선택 결과 (디버그/리포트용). env 또는 키파일에 키가 있으면 api. */
 export function selectedTransport() {
-    return process.env.ANTHROPIC_API_KEY ? "api" : "cli";
+    return resolveApiKey() ? "api" : "cli";
 }
 /** 직접 Anthropic API (haiku). SDK는 여기서만 lazy import → hook 핫패스 보호. */
 async function judgeViaApi(system, user) {
     const mod = await import("@anthropic-ai/sdk");
     const Anthropic = mod.default;
-    const client = new Anthropic(); // ANTHROPIC_API_KEY 환경변수 사용
+    // 키를 코드에서 해석(env 또는 ~/.gbc/api-key)해 명시 전달 — 셸 주입 불필요(크로스플랫폼).
+    const client = new Anthropic({ apiKey: resolveApiKey() ?? undefined });
     const resp = await client.messages.create({
         model: MODEL,
         max_tokens: 1024,

package/dist/metrics.js

@@ -0,0 +1,120 @@
+// 거북이코드 계측 레이어 (M1~M3) — B-모드 hook 관측 프록시.
+// 1차 자산 = 원시 events.jsonl(append-only). 메트릭은 그 위의 thin 집계.
+// ⚠️ 진짜 M1(post-gate 시나리오위반율)은 A-mode 사후대조 필요 — B-모드는 churn 약신호만.
+import { appendFileSync } from "node:fs";
+import { join } from "node:path";
+import { gbcDir } from "./store.js";
+/** 한 줄 이벤트의 최대 바이트 — O_APPEND atomic 보장(미만 길이) */
+const MAX_LINE = 4096;
+/** missing[] 캡 (항목 수 / 항목당 길이) */
+const MAX_MISSING_ITEMS = 20;
+const MAX_MISSING_LEN = 200;
+/** missing[]을 항목 수/길이로 캡 */
+function capMissing(missing) {
+    return missing
+        .slice(0, MAX_MISSING_ITEMS)
+        .map((m) => (m.length > MAX_MISSING_LEN ? m.slice(0, MAX_MISSING_LEN) : m));
+}
+/**
+ * 이벤트를 한 줄 JSON으로 직렬화. missing[]을 캡하고, 그래도 MAX_LINE을 넘으면
+ * missing을 요약 토큰으로 대체해 라인 길이를 보장한다(O_APPEND atomic).
+ */
+export function serializeEvent(e) {
+    const out = { ...e };
+    if (out.missing)
+        out.missing = capMissing(out.missing);
+    let line = JSON.stringify(out);
+    if (line.length >= MAX_LINE && out.missing) {
+        out.missing = [`${e.missing?.length ?? 0} items (truncated)`];
+        line = JSON.stringify(out);
+    }
+    // 극단적 경우(다른 필드가 비대)에도 캡 — 한 줄 보장
+    if (line.length >= MAX_LINE)
+        line = line.slice(0, MAX_LINE - 1);
+    return line;
+}
+/** jsonl 원시 텍스트를 이벤트 배열로 파싱 (빈 줄·깨진 줄 skip) */
+export function parseEvents(raw) {
+    const out = [];
+    for (const line of raw.split("\n")) {
+        const t = line.trim();
+        if (!t)
+            continue;
+        try {
+            const obj = JSON.parse(t);
+            if (obj && typeof obj === "object" && typeof obj.kind === "string") {
+                out.push(obj);
+            }
+        }
+        catch {
+            /* 깨진 줄 skip */
+        }
+    }
+    return out;
+}
+const M1_NOTE = "B-모드 약신호(churn proxy) — 진짜 M1(post-gate 시나리오 위반율)은 A-mode 사후대조 필요. " +
+    "spec.md 비었을 때(specHash='')는 작업단위 식별 불가라 churn 집계에서 제외(교차세션 합산 방지).";
+/** 그룹핑 키: session 우선, 없으면 specHash(CLI 이벤트 상관) */
+function groupKey(e) {
+    return e.session || e.specHash;
+}
+function round3(n) {
+    return Math.round(n * 1000) / 1000;
+}
+/** 이벤트 배열 → M1/M2/M3 집계. 순수함수(파일 I/O 없음). */
+export function computeMetrics(events) {
+    const gate = events.filter((e) => e.kind === "gate");
+    // M3 — 작업단위(session||specHash)별 gate 이벤트 수 = edit 반복 proxy
+    const perUnit = new Map();
+    for (const e of gate)
+        perUnit.set(groupKey(e), (perUnit.get(groupKey(e)) ?? 0) + 1);
+    const counts = [...perUnit.values()];
+    const workUnits = counts.length;
+    const totalEdits = gate.length;
+    const maxEditsPerUnit = counts.length ? Math.max(...counts) : 0;
+    const multiEditUnits = counts.filter((c) => c > 1).length;
+    const avgEditsPerUnit = workUnits ? round3(totalEdits / workUnits) : 0;
+    // M2 — 게이트적중(Σ block.missing) vs 도중발견(defer-add)
+    const blockEvents = gate.filter((e) => e.decision === "block");
+    const gateCaught = blockEvents.reduce((s, e) => s + (e.missing?.length ?? 0), 0);
+    const deferred = events.filter((e) => e.kind === "defer-add").length;
+    const denom = gateCaught + deferred;
+    const midDiscoveryRatio = denom ? round3(deferred / denom) : 0;
+    // M1 — specHash별 first pass 이후의 churn(spec-add/clear/gate-reset/defer-add).
+    // ⚠️ 빈 specHash("")는 spec.md 없는 작업단위라 식별 불가 → 교차세션 합산을 막기 위해 제외.
+    const firstPassAt = new Map();
+    for (const e of gate) {
+        if (e.decision !== "pass" || !e.specHash)
+            continue;
+        const cur = firstPassAt.get(e.specHash);
+        if (cur === undefined || e.at < cur)
+            firstPassAt.set(e.specHash, e.at);
+    }
+    const CHURN_KINDS = ["spec-add", "spec-clear", "gate-reset", "defer-add"];
+    let churnAfterPass = 0;
+    for (const e of events) {
+        if (!CHURN_KINDS.includes(e.kind) || !e.specHash)
+            continue;
+        const passAt = firstPassAt.get(e.specHash);
+        if (passAt !== undefined && e.at > passAt)
+            churnAfterPass++;
+    }
+    const resets = events.filter((e) => e.kind === "gate-reset").length;
+    return {
+        totalEvents: events.length,
+        m3: { workUnits, totalEdits, avgEditsPerUnit, maxEditsPerUnit, multiEditUnits },
+        m2: { gateCaught, blocks: blockEvents.length, deferred, midDiscoveryRatio },
+        m1: { resets, churnAfterPass, note: M1_NOTE },
+    };
+}
+/** events.jsonl에 이벤트 1줄 append. 실패는 무시(계측이 개발 흐름을 막지 않음). */
+export function logEvent(cwd, event) {
+    if (process.env.GBC_NO_METRICS === "1")
+        return;
+    try {
+        appendFileSync(join(gbcDir(cwd), "events.jsonl"), serializeEvent(event) + "\n");
+    }
+    catch {
+        /* 계측 실패는 무시 */
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "geobuke-code",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "거북이코드 — 구현 직전 강제 게이트. Claude Code PreToolUse hook으로 코드 변경 전 계획 케이스 누락·시나리오 미지정을 차단한다.",
   "type": "module",
   "bin": {
@@ -18,7 +18,8 @@
     "test": "node --test 'test/**/*.test.mjs'",
     "eval": "node dist/eval/regression.js",
     "prepare": "tsc",
-    "prepublishOnly": "npm run build && npm test"
+    "prepublishOnly": "npm run build && npm test",
+    "release": "sh scripts/publish.sh"
   },
   "keywords": [
     "claude-code",