geobuke-code 0.2.0 → 0.2.2

package/README.md

@@ -27,7 +27,7 @@ npm install -g geobuke-code
 
 # 2) 대상 프로젝트에 게이트 설치
 cd <your-project>
-gbc init                          # .claude/settings.json에 hook + /gate skill 머지 (동의·백업)
+gbc init                          # .claude/settings.json에 hook(PreToolUse+Stop+SessionStart) + /gate skill 머지 (동의·백업)
 ```
 
 <details>
@@ -53,27 +53,30 @@ gbc init
 
 </details>
 
-`gbc init`은 **프로젝트 로컬 `.claude/settings.json`만** 머지한다(append·멱등·백업). 전역 `~/.claude`는 건드리지 않는다. `~/.gbc/api-key`가 있으면 hook 명령에 키 주입까지 자동화한다(아래 [빠른 게이트 활성화](#빠른-게이트-활성화-api-키--선택)).
+`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+).
 
-> ⚠️ **`export ANTHROPIC_API_KEY=…` 전역 설정 금지.** Claude Code 본체가 그 키로 **과금 전환**된다(구독 대신 키 과금). 게이트 hook 서브프로세스에만 주입해야 안전하다.
+> ⚠️ **native Windows에선 API 키가 사실상 필수다.** `claude -p` 폴백은 `claude.cmd`(배치 shim)를 셸 없이 실행하지 못해(ENOENT) fail-open으로 빠질 수 있다. Windows에선 위 키 파일을 만들어 API 경로로 쓰는 것을 권장한다(WSL/Mac/Linux는 폴백 정상).
+
+키 해석 순서: `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+).
 
 ## 동작 원리
 
@@ -81,11 +84,23 @@ mkdir -p ~/.gbc && printf '%s' 'sk-ant-...' > ~/.gbc/api-key && chmod 600 ~/.gbc
 phase-protocol/계획 → /plan(SubTask) → 【게이트: 구현 직전 케이스확정】 → 구현(Claude Code) → 검증
 ```
 
-게이트는 계획 명세를 다음 우선순위로 읽는다(durable 소스):
-`$GBC_SPEC_FILE` > `.gbc/spec.md` > `scratch.md`
+게이트는 계획 명세를 `.gbc/spec.md`(단일 정본)에서 읽는다. 다른 파일을 명세로 쓰려면 `$GBC_SPEC_FILE` 환경변수로 그 경로를 명시 지정한다(우선순위 `$GBC_SPEC_FILE` > `.gbc/spec.md`). gbc가 소유하지 않은 파일을 자동 폴백하지 않으므로, 진행추적 파일 등이 명세로 오인되지 않는다.
 
 코드 변경 직전 PreToolUse hook이 명세 ↔ 변경 ↔ 미룬 항목을 대조해 통과/차단을 판정한다.
 
+### 동작 시점
+
+`gbc init`이 프로젝트 `.claude/settings.json`에 아래 hook을 멱등 등록한다. gbc는 `.gbc/`만 읽으므로(다른 하네스의 메모리·진행추적 파일 미접근) 어떤 환경에서든 동일하게 동작한다.
+
+| 시점 | hook (matcher) | 동작 |
+|---|---|---|
+| **세션 시작·재개** | SessionStart (`startup\|resume`) | `.gbc/defers.json`의 미해결 항목을 표면화(이전 작업 잔여 환기). 잔여 없으면 무출력. `compact`엔 발화 안 함(노이즈 방지) |
+| **코드 변경 직전** | PreToolUse (`Edit\|Write\|MultiEdit`) | 명세 ↔ 변경 ↔ defer 대조 → 통과(침묵)/차단(시나리오 도출 지시)/fail-open |
+| **작업단위당 1회** | (PreToolUse 캐시) | 같은 명세 해시 내에선 첫 편집만 판정, 이후 통과 → 매 편집 지연 회피 |
+| **응답 종료** | Stop | 계측 flush(`events.jsonl`) |
+
+> 세션 진입 알림만 끄려면 `GBC_NO_SESSION_HINT=1`. 기존 설치(0.2.1 이하 init)는 `gbc init --yes` 재실행으로 SessionStart hook이 추가된다.
+
 ### 시나리오 도출 루프 (수기 입력 불필요)
 
 명세가 비어 **시나리오 미지정**으로 차단되면, 사용자가 파일을 직접 쓰지 않는다. 차단 메시지가 코딩 에이전트에게 다음을 지시한다:
@@ -103,12 +118,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` 폴백으로 무설정 동작하되 작업단위당 한 번 느리다.
 
 ## 명령
 

package/dist/cli.js

@@ -4,12 +4,12 @@ import { fileURLToPath } from "node:url";
 import { dirname, join } from "node:path";
 import { homedir } from "node:os";
 import { mkdirSync, existsSync, readFileSync, writeFileSync, copyFileSync, } from "node:fs";
-import { runPreToolUse, runStop } from "./hook.js";
+import { runPreToolUse, runStop, runSessionStart } from "./hook.js";
 import { loadPlanSpec, computeSpecHash, addSpecCase, readSpecCases, clearSpec } from "./spec.js";
 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, ensureSessionStartHook } 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 → 패키지 루트
@@ -60,11 +60,13 @@ function cmdInit(args) {
         console.log(`🐢 gbc init — 다음을 수행합니다 (프로젝트 로컬만, 전역 ~/.claude 미변경):
 
   대상 프로젝트: ${cwd}
-  1) ${settingsPath} 에 PreToolUse(Edit|Write) + Stop hook 추가 (머지·멱등)
+  1) ${settingsPath} 에 PreToolUse(Edit|Write) + Stop + SessionStart 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;
@@ -86,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")) {
@@ -112,6 +113,13 @@ function cmdInit(args) {
     else {
         console.log(`  = Stop hook 이미 존재 (skip)`);
     }
+    // SessionStart (멱등) — 세션 진입(startup|resume) 시 미해결 defer 알림
+    if (ensureSessionStartHook(settings, CLI_PATH)) {
+        console.log(`  + SessionStart hook 추가`);
+    }
+    else {
+        console.log(`  = SessionStart hook 이미 존재 (skip)`);
+    }
     writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + "\n", "utf8");
     // /gate 스킬 설치
     if (existsSync(skillSrc)) {
@@ -123,7 +131,7 @@ function cmdInit(args) {
 ✅ 설치 완료. 트랜스포트: ${transport}${transport === "cli"
         ? "  (ANTHROPIC_API_KEY 설정 시 직접 API로 ~1–3s, 미설정 시 claude -p 폴백 ~13–20s)"
         : ""}
-   계획 명세는 scratch.md 또는 .gbc/spec.md 에 작성하세요(없으면 시나리오 미지정으로 차단).`);
+   계획 명세는 .gbc/spec.md 에 작성하세요(없으면 시나리오 미지정으로 차단 → 도출·검증 루프 발동: 에이전트가 요청에서 시나리오를 도출해 사용자 검증 후 'gbc spec add'로 등록).`);
 }
 // ---------- gbc status ----------
 function cmdStatus() {
@@ -264,6 +272,7 @@ function usage() {
   gbc metrics [--json]                계측 리포트(M1~M3, B-모드 관측 프록시)
   gbc hook pre-tool-use               (내부) PreToolUse hook
   gbc hook stop                       (내부) Stop hook
+  gbc hook session-start              (내부) SessionStart hook (미해결 defer 알림)
 `);
 }
 async function main() {
@@ -274,7 +283,9 @@ async function main() {
                 return runPreToolUse();
             if (rest[0] === "stop")
                 return runStop();
-            console.error("사용: gbc hook <pre-tool-use|stop>");
+            if (rest[0] === "session-start")
+                return runSessionStart();
+            console.error("사용: gbc hook <pre-tool-use|stop|session-start>");
             process.exit(1);
             break;
         case "init":

package/dist/hook.js

@@ -29,10 +29,12 @@ export function buildBlockReason(verdict, specEmpty, source) {
 }
 /**
  * pass verdict를 작업단위 캐시(markGated)에 넣어도 되는가.
- * fail-open(판정 실패 안전통과)은 제외 — 일시 장애가 작업단위 내내 게이트를 무력화하는 것을 막는다.
+ * - fail-open(판정 실패 안전통과)은 제외 — 일시 장애가 작업단위 내내 게이트를 무력화하는 것을 막는다.
+ * - 빈 명세(specEmpty)도 제외 — 빈-spec hash는 상수라 한번 캐시되면 영원히 무효화 안 됨
+ *   (= 게이트 교차세션 영구 우회, 2026-06-22 진단·수정). 빈 명세는 항상 재판정해야 한다.
  */
-export function shouldCacheVerdict(verdict) {
-    return verdict.verdict === "pass" && !verdict.failOpen;
+export function shouldCacheVerdict(verdict, specEmpty) {
+    return verdict.verdict === "pass" && !verdict.failOpen && !specEmpty;
 }
 function readStdin() {
     return new Promise((resolve) => {
@@ -99,12 +101,16 @@ export async function runPreToolUse() {
     }
     const { text: specText, source } = loadPlanSpec(cwd);
     const specHash = computeSpecHash(specText);
+    const specEmpty = specText.trim() === "";
     // 계측용 해시: 빈 spec은 ""(센티넬)로 기록 → M1 churn 교차세션 합산 방지.
-    // (게이트 캐시용 specHash는 그대로 — markGated/isGated 동작 불변)
-    const logHash = specText.trim() === "" ? "" : specHash;
+    const logHash = specEmpty ? "" : specHash;
     // 작업단위 1회: 이미 게이트 통과한 단위면 즉시 통과 (judge 미호출, 핫패스)
     // 계측: cached-skip도 기록해야 M3(작업단위당 edit 반복)이 진짜 횟수를 잡는다.
-    if (isGated(cwd, specHash)) {
+    // ⚠️ 빈 명세는 캐시를 절대 조회하지 않는다(read-side 가드) — 빈-spec hash는 상수라
+    //    한번 캐시된 pass가 영원히 무효화되지 않아 게이트가 교차세션으로 영구 무력화되던
+    //    결함(2026-06-22 진단)을 근본 차단. 빈 명세는 항상 재판정: judge [1단계] 사소한
+    //    편집 pass, [2단계]a 동작 편집 block. (기존에 오염된 state.json도 자동으로 무시됨)
+    if (!specEmpty && isGated(cwd, specHash)) {
         logEvent(cwd, {
             at: nowIso(),
             session,
@@ -121,39 +127,42 @@ export async function runPreToolUse() {
     const defers = activeDeferItems(cwd);
     const verdict = await judge(specText, editText, defers);
     if (verdict.verdict === "pass") {
-        if (shouldCacheVerdict(verdict)) {
-            markGated(cwd, specHash, verdict.reason);
+        // fail-open(판정 실패) 먼저 분기 — 빈-spec 정상 pass가 fail-open으로 오분류되지 않게.
+        if (verdict.failOpen) {
+            // 판정 실패로 안전 통과. 캐시하지 않아(작업단위 무력화 방지) 다음 편집에서 재판정.
+            // 계측 + systemMessage로 사용자에게 "게이트가 검사 못 했음"을 알린다(조용한 무력화 방지).
+            logFailOpen(cwd, toolName, verdict.reason);
             logEvent(cwd, {
                 at: nowIso(),
                 session,
                 specHash: logHash,
                 kind: "gate",
                 tool: toolName,
-                decision: "pass",
-                deferCount: defers.length,
+                decision: "failopen",
+            });
+            emit({
+                systemMessage: `🐢 거북이 게이트 — 판정 실패로 안전 통과(fail-open). 이 편집은 게이트 검사를 받지 못했습니다: ${verdict.reason}`,
+                hookSpecificOutput: {
+                    hookEventName: "PreToolUse",
+                    permissionDecision: "allow",
+                    permissionDecisionReason: verdict.reason,
+                },
             });
-            process.exit(0); // 정상 통과 (자동승인 X — 무출력)
+            process.exit(0);
         }
-        // fail-open: 판정 실패로 안전 통과. 캐시하지 않아(작업단위 무력화 방지) 다음 편집에서 재판정.
-        // 계측 + systemMessage로 사용자에게 "게이트가 검사 못 했음"을 알린다(조용한 무력화 방지).
-        logFailOpen(cwd, toolName, verdict.reason);
+        // 정상 pass. 단 빈 명세 pass는 절대 캐시하지 않는다(상수 hash 영구 우회 방지).
+        if (shouldCacheVerdict(verdict, specEmpty))
+            markGated(cwd, specHash, verdict.reason);
         logEvent(cwd, {
             at: nowIso(),
             session,
             specHash: logHash,
             kind: "gate",
             tool: toolName,
-            decision: "failopen",
+            decision: "pass",
+            deferCount: defers.length,
         });
-        emit({
-            systemMessage: `🐢 거북이 게이트 — 판정 실패로 안전 통과(fail-open). 이 편집은 게이트 검사를 받지 못했습니다: ${verdict.reason}`,
-            hookSpecificOutput: {
-                hookEventName: "PreToolUse",
-                permissionDecision: "allow",
-                permissionDecisionReason: verdict.reason,
-            },
-        });
-        process.exit(0);
+        process.exit(0); // 정상 통과 (자동승인 X — 무출력)
     }
     // block: 사람 pause (ask 기본) — 사유가 사용자에게 표시됨
     // 시나리오 미지정(명세 빈약)과 침묵 누락을 다르게 안내한다.
@@ -208,3 +217,35 @@ export async function runStop() {
     });
     process.exit(0);
 }
+/**
+ * 세션 진입(startup|resume) 시 미해결 defer 잔여를 표면화하는 알림 문자열. 없으면 "".
+ * gbc 자기 소유 데이터(.gbc/defers.json)만 사용 — scratch/메모리 미접근(다른 하네스와 혼재·환각 방지).
+ */
+export function buildSessionStartHint(unresolved) {
+    if (unresolved.length === 0)
+        return "";
+    const items = unresolved.map((d, i) => `${i + 1}. ${d.item}`).join("\n");
+    return (`🐢 거북이 게이트 — 미해결 defer ${unresolved.length}건 (이전 작업 잔여):\n${items}\n` +
+        `필요하면 사용자에게 이어서 처리할지 확인하세요. 해결은 'gbc defer resolve <번호>'.`);
+}
+/**
+ * SessionStart: 세션 진입 시 미해결 defer를 stdout(plain text)으로 표면화 → Claude 컨텍스트 주입.
+ * 잔여 없으면 무출력. GBC_NO_SESSION_HINT=1로 opt-out. 결정론적(LLM·코드비교 없음).
+ */
+export async function runSessionStart() {
+    if (process.env.GBC_NO_SESSION_HINT === "1")
+        process.exit(0);
+    let input = {};
+    try {
+        const raw = await readStdin();
+        input = raw ? JSON.parse(raw) : {};
+    }
+    catch {
+        process.exit(0);
+    }
+    const cwd = input.cwd || process.cwd();
+    const hint = buildSessionStartHint(unresolvedDefers(cwd));
+    if (hint)
+        process.stdout.write(hint);
+    process.exit(0);
+}

package/dist/install.js

@@ -1,39 +1,56 @@
 // 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;
+}
+/** SessionStart hook 명령 — 셸 무관 순수 명령(buildPreCommand와 동일 규약). */
+export function buildSessionStartCommand(cliPath) {
+    return `node "${cliPath}" hook session-start`;
+}
+/**
+ * SessionStart hook을 멱등 등록한다. matcher "startup|resume"로 신규 진입·재개에만 발화
+ * (compact마다 반복 노이즈 방지). 이미 'hook session-start' 명령이 있으면 추가하지 않는다.
+ * settings를 제자리 수정하고, 새로 추가했으면 true(이미 있으면 false)를 반환한다.
+ */
+export function ensureSessionStartHook(settings, cliPath) {
+    for (const entry of settings.hooks?.SessionStart ?? []) {
+        for (const h of entry.hooks ?? []) {
+            if (h.command.includes("hook session-start"))
+                return false;
+        }
+    }
+    const hooks = (settings.hooks ??= {});
+    (hooks.SessionStart ??= []).push({
+        matcher: "startup|resume",
+        hooks: [{ type: "command", command: buildSessionStartCommand(cliPath) }],
+    });
+    return true;
 }

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/spec.js

@@ -5,7 +5,11 @@ import { gbcDir } from "./store.js";
 const MAX_SPEC = 12000; // 명세 텍스트 절단 (프롬프트 비대화 방지)
 /**
  * 계획 명세를 디스크에서 로드한다. (advisor④: durable 소스만 — 라이브 SubTask는 영속 X)
- * 우선순위: GBC_SPEC_FILE > .gbc/spec.md > scratch.md > "" (빈 명세 = 시나리오 미지정 → 통증#2 차단)
+ * 우선순위: GBC_SPEC_FILE > .gbc/spec.md > "" (빈 명세 = 시나리오 미지정 → 통증#2 차단)
+ *
+ * .gbc/spec.md가 단일 정본(canonical). 다른 파일(예: 하네스의 scratch.md)을 명세로 쓰려면
+ * GBC_SPEC_FILE로 명시 지정한다 — gbc가 소유 안 한 파일을 자동 폴백하지 않는다(0.2.2:
+ * scratch.md 자동 폴백 제거. 진행추적 파일을 시나리오 명세로 오인하던 거짓음성 차단).
  *
  * 느슨 매칭은 게이트 LLM이 담당한다(체크리스트 라인/SubTask 항목). 로더는 텍스트만 제공.
  */
@@ -14,7 +18,6 @@ export function loadPlanSpec(cwd) {
     if (process.env.GBC_SPEC_FILE)
         candidates.push(process.env.GBC_SPEC_FILE);
     candidates.push(join(cwd, ".gbc", "spec.md"));
-    candidates.push(join(cwd, "scratch.md"));
     for (const path of candidates) {
         if (existsSync(path)) {
             try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "geobuke-code",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "거북이코드 — 구현 직전 강제 게이트. Claude Code PreToolUse hook으로 코드 변경 전 계획 케이스 누락·시나리오 미지정을 차단한다.",
   "type": "module",
   "bin": {
@@ -15,6 +15,7 @@
   },
   "scripts": {
     "build": "tsc",
+    "dev": "tsc --watch",
     "test": "node --test 'test/**/*.test.mjs'",
     "eval": "node dist/eval/regression.js",
     "prepare": "tsc",