geobuke-code 0.2.2 → 0.2.3

package/README.md

@@ -57,9 +57,9 @@ gbc init
 
 ## 빠른 게이트 활성화 (API 키 — 선택)
 
-키가 없으면 `claude -p` 폴백(~13–20s)으로 무설정 동작한다. **haiku 직접 API(~1–3s)**를 쓰려면 **키 파일만 만들면 된다** — gbc가 실행 시 직접 읽으므로 settings.json 수정이나 셸 주입은 불필요하다(0.2.1+).
+키가 없으면 `claude -p` 폴백(~13–20s)으로 무설정 동작한다. **haiku 직접 API(~1–3s)**를 쓰려면 **키 파일만 만들면 된다** — gbc가 실행 시 직접 읽으므로 settings.json 수정이나 셸 주입은 불필요하다.
 
-> ⚠️ **native Windows에선 API 키가 사실상 필수다.** `claude -p` 폴백은 `claude.cmd`(배치 shim)를 셸 없이 실행하지 못해(ENOENT) fail-open으로 빠질 수 있다. Windows에선 위 키 파일을 만들어 API 경로로 쓰는 것을 권장한다(WSL/Mac/Linux는 폴백 정상).
+> ⚠️ **native Windows에선 API 키를 권장한다.** 키 없는 `claude -p` 폴백도 지원하지만(win32에선 `claude.cmd` 실행을 위해 셸 경유, 프롬프트는 인젝션 회피로 stdin 전달, 무응답 방지 kill-timeout), 폴백은 느리므로(~13–20s) 위 키 파일로 API 경로(~1–3s)를 쓰는 편이 빠르고 확실하다.
 
 키 해석 순서: `ANTHROPIC_API_KEY` 환경변수 > `~/.gbc/api-key` 파일.
 
@@ -76,7 +76,7 @@ Set-Content -Path "$HOME\.gbc\api-key" -Value "sk-ant-..." -NoNewline
 
 > ⚠️ **`export ANTHROPIC_API_KEY=…` 전역 설정(또는 settings.json top-level `env`) 금지.** Claude Code 본체가 그 키로 **과금 전환**된다(구독 대신 키 과금). 키 파일 방식은 gbc 판정 호출에만 키가 쓰이므로 이 함정을 구조적으로 피한다.
 
-`gbc status`는 키 파일/환경변수를 반영해 `트랜스포트: api`로 표시한다(0.2.1+).
+`gbc status`는 키 파일/환경변수를 반영해 `트랜스포트: api`로 표시한다.
 
 ## 동작 원리
 
@@ -98,8 +98,11 @@ phase-protocol/계획 → /plan(SubTask) → 【게이트: 구현 직전 케이
 | **코드 변경 직전** | PreToolUse (`Edit\|Write\|MultiEdit`) | 명세 ↔ 변경 ↔ defer 대조 → 통과(침묵)/차단(시나리오 도출 지시)/fail-open |
 | **작업단위당 1회** | (PreToolUse 캐시) | 같은 명세 해시 내에선 첫 편집만 판정, 이후 통과 → 매 편집 지연 회피 |
 | **응답 종료** | Stop | 계측 flush(`events.jsonl`) |
+| **업데이트 필요 시** | (PreToolUse·SessionStart·`gbc status`) | hook 구버전(②) 또는 신버전 출시(①)면 갱신 안내. PreToolUse는 세션당 1회(`systemMessage` 비차단), SessionStart는 진입 시 표시. 게이트 통과/차단 동작은 불변 |
 
-> 세션 진입 알림만 끄려면 `GBC_NO_SESSION_HINT=1`. 기존 설치(0.2.1 이하 init)는 `gbc init --yes` 재실행으로 SessionStart hook이 추가된다.
+> 세션 진입 알림만 끄려면 `GBC_NO_SESSION_HINT=1`. 업데이트 안내만 끄려면 `GBC_NO_UPDATE_NOTICE=1`.
+> 프로젝트 hook이 구식이거나(SessionStart 누락·옛 명령) 새 버전이 나오면 gbc가 감지해 `gbc init --yes` 재실행 또는 `npm i -g geobuke-code@latest`를 안내한다. PreToolUse 경로로도 알리므로 "설치만 하고 init 안 한" 경우에도 도달한다.
+> **업데이트 안내(①)는 네트워크를 게이트 핫패스에 들이지 않는다**: `~/.gbc/version-check.json` 캐시만 비교하고, 갱신은 SessionStart·`gbc status`에서만 짧은 타임아웃으로. 조회 실패는 조용히 무시(fail-silent)되어 게이트 결정에 영향이 없다.
 
 ### 시나리오 도출 루프 (수기 입력 불필요)
 
@@ -119,7 +122,7 @@ phase-protocol/계획 → /plan(SubTask) → 【게이트: 구현 직전 케이
 | 조건 | 트랜스포트 | 지연 |
 |---|---|---|
 | 키 있음 (`ANTHROPIC_API_KEY` env 또는 `~/.gbc/api-key` 파일) | Anthropic API 직접 (haiku, 최소 시스템프롬프트) | ~1–3s (목표) |
-| 키 없음 | `claude -p` 폴백 (CC 인증 재사용, 무설정 / ⚠️native Windows 미지원) | ~13–20s |
+| 키 없음 | `claude -p` 폴백 (CC 인증 재사용, 무설정 · native Windows 포함) | ~13–20s |
 
 **작업단위 1회**: 게이트는 작업단위(계획 명세 해시)당 한 번만 발동한다. 명세가 바뀌거나 명세 밖 파일을 편집할 때만 재발동 → 매 편집 지연을 피한다.
 

package/dist/cli.js

@@ -10,9 +10,20 @@ import { loadState, resetGate } from "./state.js";
 import { addDefer, loadDefers, resolveDefer } from "./defer.js";
 import { selectedTransport } from "./judge.js";
 import { buildPreCommand, normalizeHooks, ensureSessionStartHook } from "./install.js";
+import { isCacheStale, readVersionCache, refreshVersionCache, buildVersionNotice, } from "./version.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 → 패키지 루트
+/** 설치된 패키지 버전(업데이트 안내 비교 기준). 읽기 실패 시 "". */
+function readPkgVersion() {
+    try {
+        return JSON.parse(readFileSync(join(PKG_ROOT, "package.json"), "utf8")).version ?? "";
+    }
+    catch {
+        return "";
+    }
+}
+const PKG_VERSION = readPkgVersion();
 /** ~/.gbc/api-key 존재 여부 — 있으면 hook에 키 주입(빠른 haiku 경로). */
 function hasApiKey() {
     return existsSync(join(homedir(), ".gbc", "api-key"));
@@ -49,7 +60,7 @@ function nowStamp() {
     }
 }
 // ---------- gbc init ----------
-function cmdInit(args) {
+async function cmdInit(args) {
     const cwd = process.cwd();
     const yes = args.includes("--yes") || args.includes("-y");
     const claudeDir = join(cwd, ".claude");
@@ -132,9 +143,28 @@ ${hasApiKey()
         ? "  (ANTHROPIC_API_KEY 설정 시 직접 API로 ~1–3s, 미설정 시 claude -p 폴백 ~13–20s)"
         : ""}
    계획 명세는 .gbc/spec.md 에 작성하세요(없으면 시나리오 미지정으로 차단 → 도출·검증 루프 발동: 에이전트가 요청에서 시나리오를 도출해 사용자 검증 후 'gbc spec add'로 등록).`);
+    // 설치 직후 버전 캐시 seed — 신버전 안내(①)가 "설치만 하고 init 안 한" 코호트에도
+    // 신뢰성 있게 동작하도록(SessionStart 없는 환경의 유일한 seed 지점일 수 있음). best-effort.
+    try {
+        if (process.env.GBC_NO_UPDATE_NOTICE !== "1" && isCacheStale(readVersionCache())) {
+            await refreshVersionCache();
+        }
+    }
+    catch {
+        /* 갱신 실패는 무시(fail-silent) */
+    }
 }
 // ---------- gbc status ----------
-function cmdStatus() {
+async function cmdStatus() {
+    // 버전 캐시가 stale면 갱신(status는 대화형이라 짧은 대기 허용). 실패는 무시.
+    try {
+        if (process.env.GBC_NO_UPDATE_NOTICE !== "1" && isCacheStale(readVersionCache())) {
+            await refreshVersionCache();
+        }
+    }
+    catch {
+        /* 갱신 실패 무시 */
+    }
     const cwd = process.cwd();
     const { text, source } = loadPlanSpec(cwd);
     const hash = computeSpecHash(text);
@@ -142,6 +172,7 @@ function cmdStatus() {
     const defers = loadDefers(cwd);
     const unresolved = defers.filter((d) => !d.resolved);
     console.log(`🐢 거북이 게이트 상태 — ${cwd}
+  버전: ${PKG_VERSION || "(불명)"}
   트랜스포트: ${selectedTransport()}
   명세 소스: ${source} ${text ? `(${text.length}자)` : "(비어있음 → 모든 코드변경 차단)"}
   명세 해시: ${hash}
@@ -150,6 +181,9 @@ function cmdStatus() {
     if (unresolved.length > 0) {
         console.log(unresolved.map((d, i) => `    ${i + 1}. ${d.item}`).join("\n"));
     }
+    const verNotice = buildVersionNotice(PKG_VERSION, readVersionCache());
+    if (verNotice)
+        console.log(`  ${verNotice}`);
 }
 // ---------- gbc defer ----------
 function cmdDefer(args) {
@@ -280,11 +314,11 @@ async function main() {
     switch (cmd) {
         case "hook":
             if (rest[0] === "pre-tool-use")
-                return runPreToolUse();
+                return runPreToolUse({ cliPath: CLI_PATH, version: PKG_VERSION });
             if (rest[0] === "stop")
                 return runStop();
             if (rest[0] === "session-start")
-                return runSessionStart();
+                return runSessionStart({ cliPath: CLI_PATH, version: PKG_VERSION });
             console.error("사용: gbc hook <pre-tool-use|stop|session-start>");
             process.exit(1);
             break;

package/dist/defer.js

@@ -1,5 +1,6 @@
 import { join } from "node:path";
 import { gbcDir, readJson, writeJson } from "./store.js";
+import { normalizeCase } from "./text.js";
 function deferPath(cwd) {
     return join(gbcDir(cwd), "defers.json");
 }
@@ -20,7 +21,7 @@ function save(cwd, defers) {
 /** 명시적으로 항목을 미룬다 (침묵 누락 차단의 유일한 정당 경로) */
 export function addDefer(cwd, item) {
     const defers = loadDefers(cwd);
-    const entry = { item, at: nowIso(), resolved: false };
+    const entry = { item: normalizeCase(item), at: nowIso(), resolved: false };
     defers.push(entry);
     save(cwd, defers);
     return entry;

package/dist/hook.js

@@ -5,6 +5,8 @@ import { isGatedTool, normalizeEdit } from "./normalize.js";
 import { loadPlanSpec, computeSpecHash } from "./spec.js";
 import { isGated, markGated } from "./state.js";
 import { activeDeferItems, unresolvedDefers, loadDefers } from "./defer.js";
+import { readProjectSettings, buildUpdateNotice, wasNotified, markNotified } from "./notice.js";
+import { isCacheStale, readVersionCache, refreshVersionCache } from "./version.js";
 import { appendFileSync } from "node:fs";
 import { join } from "node:path";
 import { gbcDir } from "./store.js";
@@ -76,8 +78,27 @@ function logFailOpen(cwd, toolName, reason) {
         /* 계측 실패는 무시 */
     }
 }
+/**
+ * 업데이트 안내 문자열(세션당 1회). 안내는 게이트와 완전 독립 — 어떤 실패도 게이트 결정에
+ * 영향 주지 않게 전체를 try/catch로 감싼다(fail-silent). cliPath 없으면(직접 hook 호출 등) "".
+ */
+function maybeUpdateNotice(cwd, session, ctx) {
+    try {
+        if (!ctx?.cliPath)
+            return "";
+        if (wasNotified(cwd, session))
+            return "";
+        const notice = buildUpdateNotice(readProjectSettings(cwd), ctx.cliPath, ctx.version ?? "");
+        if (notice)
+            markNotified(cwd, session);
+        return notice;
+    }
+    catch {
+        return "";
+    }
+}
 /** PreToolUse: 코드 변경 직전 게이트 */
-export async function runPreToolUse() {
+export async function runPreToolUse(ctx) {
     let input = {};
     try {
         const raw = await readStdin();
@@ -162,7 +183,12 @@ export async function runPreToolUse() {
             decision: "pass",
             deferCount: defers.length,
         });
-        process.exit(0); // 정상 통과 (자동승인 X — 무출력)
+        // 업데이트 안내(있으면)만 비차단 노출 — systemMessage 단독은 permissionDecision 없으니
+        // 도구를 자동승인하지 않고(통과 동작 보존) 메시지만 표시한다.
+        const passNotice = maybeUpdateNotice(cwd, session, ctx);
+        if (passNotice)
+            emit({ systemMessage: passNotice });
+        process.exit(0); // 정상 통과 (자동승인 X)
     }
     // block: 사람 pause (ask 기본) — 사유가 사용자에게 표시됨
     // 시나리오 미지정(명세 빈약)과 침묵 누락을 다르게 안내한다.
@@ -178,14 +204,19 @@ export async function runPreToolUse() {
         deferCount: defers.length,
     });
     const mode = process.env.GBC_BLOCK_MODE === "deny" ? "deny" : "ask";
-    emit({
+    const blockOut = {
         hookSpecificOutput: {
             hookEventName: "PreToolUse",
             permissionDecision: mode,
             permissionDecisionReason: reason,
             additionalContext: reason,
         },
-    });
+    };
+    // 업데이트 안내(있으면)를 같은 출력에 top-level systemMessage로 덧붙인다(차단 동작 불변).
+    const blockNotice = maybeUpdateNotice(cwd, session, ctx);
+    if (blockNotice)
+        blockOut.systemMessage = blockNotice;
+    emit(blockOut);
     process.exit(0);
 }
 /** Stop: 미해결 defer 리마인드 (stop_hook_active 가드로 1회만) */
@@ -232,9 +263,7 @@ export function buildSessionStartHint(unresolved) {
  * 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);
+export async function runSessionStart(ctx) {
     let input = {};
     try {
         const raw = await readStdin();
@@ -244,8 +273,36 @@ export async function runSessionStart() {
         process.exit(0);
     }
     const cwd = input.cwd || process.cwd();
-    const hint = buildSessionStartHint(unresolvedDefers(cwd));
-    if (hint)
-        process.stdout.write(hint);
+    const parts = [];
+    // 미해결 defer 알림(GBC_NO_SESSION_HINT로 opt-out — 기존 동작 보존).
+    if (process.env.GBC_NO_SESSION_HINT !== "1") {
+        const hint = buildSessionStartHint(unresolvedDefers(cwd));
+        if (hint)
+            parts.push(hint);
+    }
+    // 업데이트 안내(staleness + version) — SessionStart 보유 코호트(0.2.3+)용. 세션 식별자가 없어
+    // 항상 표시되므로 dedup 대신 GBC_NO_UPDATE_NOTICE opt-out에 맡긴다(buildUpdateNotice 내부).
+    try {
+        if (ctx?.cliPath) {
+            const notice = buildUpdateNotice(readProjectSettings(cwd), ctx.cliPath, ctx.version ?? "");
+            if (notice)
+                parts.push(notice);
+        }
+    }
+    catch {
+        /* 안내 실패는 무시(fail-silent) */
+    }
+    if (parts.length > 0)
+        process.stdout.write(parts.join("\n"));
+    // 버전 캐시 갱신은 '표시 후'에만(이번 출력은 캐시값 기준, 갱신은 다음 세션용). SessionStart는
+    // 게이트를 막지 않으므로 짧은 타임아웃 네트워크가 안전(advisor 승인). 실패는 조용히 무시.
+    try {
+        if (ctx?.cliPath && process.env.GBC_NO_UPDATE_NOTICE !== "1" && isCacheStale(readVersionCache())) {
+            await refreshVersionCache();
+        }
+    }
+    catch {
+        /* 갱신 실패는 무시(fail-silent) */
+    }
     process.exit(0);
 }

package/dist/install.js

@@ -35,6 +35,30 @@ export function normalizeHooks(settings, cliPath) {
 export function buildSessionStartCommand(cliPath) {
     return `node "${cliPath}" hook session-start`;
 }
+/**
+ * (read-only) PreToolUse hook 명령이 현재 표준(pure)과 다른 구버전인지. normalizeHooks의
+ * 감지부만 떼어낸 비파괴 술어 — ②init-staleness 안내가 settings를 수정하지 않고 판단하게 한다.
+ */
+export function hasStalePreToolUse(settings, cliPath) {
+    const target = buildPreCommand(cliPath);
+    for (const entry of settings.hooks?.PreToolUse ?? []) {
+        for (const h of entry.hooks ?? []) {
+            if (h.command.includes("hook pre-tool-use") && h.command !== target)
+                return true;
+        }
+    }
+    return false;
+}
+/** (read-only) SessionStart hook(session-start 명령)이 등록돼 있는지. 0.2.1 이하 init엔 없음. */
+export function hasSessionStartHook(settings) {
+    for (const entry of settings.hooks?.SessionStart ?? []) {
+        for (const h of entry.hooks ?? []) {
+            if (h.command.includes("hook session-start"))
+                return true;
+        }
+    }
+    return false;
+}
 /**
  * SessionStart hook을 멱등 등록한다. matcher "startup|resume"로 신규 진입·재개에만 발화
  * (compact마다 반복 노이즈 방지). 이미 'hook session-start' 명령이 있으면 추가하지 않는다.

package/dist/judge.js

@@ -1,10 +1,18 @@
-import { execFile } from "node:child_process";
+import { execFile, spawn } 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";
+const CLI_TIMEOUT_MS = 30000; // claude -p 폴백 상한(행 방지). 초과 시 kill → fail-open.
+/**
+ * 모델 토큰을 셸 안전 문자로 제한한다(win32 shell:true 경로의 argv 인젝션 차단).
+ * GBC_MODEL은 사용자 env지만, 셸 경로에선 메타문자가 명령으로 새지 않게 화이트리스트만 통과.
+ */
+export function safeModel(model) {
+    return /^[\w.-]+$/.test(model) ? model : "claude-haiku-4-5";
+}
 /**
  * API 키 해석 (크로스플랫폼, 셸 무관).
  * 1) ANTHROPIC_API_KEY 환경변수 우선, 2) 없으면 ~/.gbc/api-key 파일.
@@ -102,10 +110,63 @@ async function judgeViaApi(system, user) {
 }
 /** claude -p 폴백 (무설정 도그푸딩용, 느림). CC의 기존 인증 사용. */
 async function judgeViaCli(system, user) {
-    const { stdout } = await execFileAsync("claude", ["-p", user, "--append-system-prompt", system, "--model", MODEL, "--output-format", "json"], { maxBuffer: 10 * 1024 * 1024 });
+    // native Windows는 claude.cmd라 별도 경로(아래) — POSIX는 검증된 경로 그대로(8/8 회귀 보존).
+    if (process.platform === "win32")
+        return judgeViaCliWin(system, user);
+    const { stdout } = await execFileAsync("claude", ["-p", user, "--append-system-prompt", system, "--model", MODEL, "--output-format", "json"], { maxBuffer: 10 * 1024 * 1024, timeout: CLI_TIMEOUT_MS });
     const env = JSON.parse(stdout);
     return env.result ?? "";
 }
+/**
+ * native Windows 폴백. claude는 claude.cmd(배치 shim)라 Node 18+가 shell 없이 spawn 못 한다
+ * (CVE-2024-27980 → ENOENT). shell:true로 실행하되, argv엔 동적 데이터를 절대 두지 않는다:
+ * system+user를 합쳐 stdin으로 전달 → argv는 고정 플래그뿐이라 셸 메타문자 인젝션 표면이 없다.
+ * (W3 stdin 결합은 WSL에서 claude -p 실측으로 판정 품질 동일 검증함 — POSIX/win32 양 경로의
+ *  '판정 품질'만 프롬프트 전달 방식이 다르고, 이는 가시적 fail-open으로 바운드된다.)
+ * kill-timeout 필수 — 무응답 stdin이 PreToolUse를 무한 차단하면 ENOENT보다 나쁘다 → fail-open 강제.
+ */
+function judgeViaCliWin(system, user) {
+    return new Promise((resolve, reject) => {
+        const prompt = `${system}\n\n${user}`;
+        const child = spawn("claude", ["-p", "--model", safeModel(MODEL), "--output-format", "json"], {
+            shell: true,
+        });
+        let out = "";
+        let err = "";
+        let done = false;
+        const finish = (fn) => {
+            if (done)
+                return;
+            done = true;
+            clearTimeout(timer);
+            fn();
+        };
+        const timer = setTimeout(() => {
+            child.kill();
+            finish(() => reject(new Error(`claude -p 타임아웃(${CLI_TIMEOUT_MS}ms)`)));
+        }, CLI_TIMEOUT_MS);
+        child.stdout?.on("data", (d) => (out += String(d)));
+        child.stderr?.on("data", (d) => (err += String(d)));
+        child.on("error", (e) => finish(() => reject(e)));
+        child.on("close", (code) => finish(() => {
+            if (code !== 0) {
+                reject(new Error(`claude exited ${code}: ${err.slice(0, 200)}`));
+                return;
+            }
+            try {
+                resolve(JSON.parse(out).result ?? "");
+            }
+            catch (e) {
+                reject(e);
+            }
+        }));
+        child.stdin?.on("error", () => {
+            /* EPIPE 등은 close/error 핸들러가 처리 */
+        });
+        child.stdin?.write(prompt);
+        child.stdin?.end();
+    });
+}
 /**
  * 게이트 판정. ANTHROPIC_API_KEY 있으면 직접 API(빠름), 없으면 claude -p 폴백.
  * 실패 시 안전하게 pass(fail-open) — 게이트가 개발을 막아버리는 사고 방지.

package/dist/notice.js

@@ -0,0 +1,75 @@
+// 업데이트 안내 — ②init-staleness(결정론적, 네트워크 없음) + ①version(캐시 비교, ST4에서 추가).
+// PreToolUse cache-miss 경로 + SessionStart + gbc status에서 호출, 세션당 1회 dedup.
+// 게이트 판정과 완전 독립 — 안내 실패가 게이트 결정에 절대 영향 주지 않는다(fail-silent).
+import { readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { gbcDir } from "./store.js";
+import { hasStalePreToolUse, hasSessionStartHook } from "./install.js";
+import { readVersionCache, buildVersionNotice } from "./version.js";
+/** 프로젝트 로컬 .claude/settings.json 읽기(없거나 깨지면 빈 객체). read-only. */
+export function readProjectSettings(cwd) {
+    try {
+        return JSON.parse(readFileSync(join(cwd, ".claude", "settings.json"), "utf8"));
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * ②init-staleness: settings.json 상태로 hook 구버전/누락을 감지해 'gbc init --yes' 재실행을
+ * 안내한다. 버전 숫자가 아니라 실제 hook 상태로 판단 → 정말 필요한 프로젝트만 알린다.
+ * - SessionStart 미등록: 0.2.1 이하 init 코호트(가장 흔한 staleness). PreToolUse 경로로만 도달 가능.
+ * - PreToolUse 명령 구식: 옛 bash 키주입 prefix 등.
+ * 둘 다 아니면 "".
+ */
+export function buildInitStalenessNotice(settings, cliPath) {
+    const stale = hasStalePreToolUse(settings, cliPath);
+    const missingSession = !hasSessionStartHook(settings);
+    if (!stale && !missingSession)
+        return "";
+    const reasons = [];
+    if (missingSession)
+        reasons.push("SessionStart hook 미등록");
+    if (stale)
+        reasons.push("PreToolUse hook 명령 구식");
+    return (`🐢 거북이 게이트 — 이 프로젝트 hook이 최신이 아닙니다(${reasons.join(", ")}). ` +
+        `'gbc init --yes' 재실행을 권장합니다(머지·멱등·백업).`);
+}
+function notifiedPath(cwd) {
+    return join(gbcDir(cwd), "notified.json");
+}
+/** 이 세션에서 이미 안내했는지 — 같은 session_id면 true. dedup(세션당 1회). fail-silent. */
+export function wasNotified(cwd, session) {
+    try {
+        const j = JSON.parse(readFileSync(notifiedPath(cwd), "utf8"));
+        return j.session === session;
+    }
+    catch {
+        return false;
+    }
+}
+/** 이 세션을 '안내함'으로 기록. 기록 실패는 무시(안내가 게이트를 방해하지 않게). */
+export function markNotified(cwd, session) {
+    try {
+        writeFileSync(notifiedPath(cwd), JSON.stringify({ session, at: new Date().toISOString() }));
+    }
+    catch {
+        /* 안내 기록 실패는 무시(fail-silent) */
+    }
+}
+/**
+ * 업데이트 안내 조합 문자열(②init-staleness + ①신버전). 없으면 "".
+ * GBC_NO_UPDATE_NOTICE=1이면 항상 "". 네트워크 없음 — version은 캐시(~/.gbc/version-check.json)만 읽는다.
+ */
+export function buildUpdateNotice(settings, cliPath, currentVersion, home) {
+    if (process.env.GBC_NO_UPDATE_NOTICE === "1")
+        return "";
+    const lines = [];
+    const stale = buildInitStalenessNotice(settings, cliPath);
+    if (stale)
+        lines.push(stale);
+    const version = buildVersionNotice(currentVersion, readVersionCache(home));
+    if (version)
+        lines.push(version);
+    return lines.join("\n");
+}

package/dist/spec.js

@@ -1,7 +1,8 @@
 import { readFileSync, writeFileSync, appendFileSync, existsSync } from "node:fs";
-import { join } from "node:path";
+import { join, resolve, sep } from "node:path";
 import { createHash } from "node:crypto";
 import { gbcDir } from "./store.js";
+import { normalizeCase } from "./text.js";
 const MAX_SPEC = 12000; // 명세 텍스트 절단 (프롬프트 비대화 방지)
 /**
  * 계획 명세를 디스크에서 로드한다. (advisor④: durable 소스만 — 라이브 SubTask는 영속 X)
@@ -15,8 +16,17 @@ const MAX_SPEC = 12000; // 명세 텍스트 절단 (프롬프트 비대화 방
  */
 export function loadPlanSpec(cwd) {
     const candidates = [];
-    if (process.env.GBC_SPEC_FILE)
-        candidates.push(process.env.GBC_SPEC_FILE);
+    if (process.env.GBC_SPEC_FILE) {
+        // W1: 상대경로는 프로젝트 cwd 기준으로 해석한다(hook 프로세스의 cwd가 아니라). 절대경로는 그대로.
+        const resolved = resolve(cwd, process.env.GBC_SPEC_FILE);
+        // 컨테인먼트는 '차단'이 아니라 '경고만' — GBC_SPEC_FILE은 0.2.2에서 의도한 escape-hatch라
+        // cwd 밖 공유 명세를 명시 지정하는 정당 용례가 있다. env는 신뢰 경계 밖이 아니므로
+        // 막기보다, 예기치 않게 프로젝트 밖을 가리킬 때 사용자에게 보이게만 한다(stderr).
+        if (!resolved.startsWith(cwd + sep)) {
+            console.error(`🐢 gbc: GBC_SPEC_FILE이 프로젝트 밖을 가리킵니다(${resolved}). 의도한 것인지 확인하세요.`);
+        }
+        candidates.push(resolved);
+    }
     candidates.push(join(cwd, ".gbc", "spec.md"));
     for (const path of candidates) {
         if (existsSync(path)) {
@@ -39,7 +49,6 @@ export function computeSpecHash(text) {
 // --- spec.md 쓰기 (gbc spec 서브커맨드 백엔드) ---
 // 도출→검증→등록 루프에서, 사용자 승인된 시나리오를 durable 명세로 기록한다.
 // 주 경로는 에이전트가 .gbc/spec.md를 직접 작성하는 것이고, 이 CLI는 한 줄 케이스 추가용 보조.
-const MAX_CASE = 500; // 한 케이스 길이 상한 (spec.md 비대화·무제한 기록 방지)
 function specPath(cwd) {
     return join(gbcDir(cwd), "spec.md");
 }
@@ -50,8 +59,7 @@ function specPath(cwd) {
  */
 export function addSpecCase(cwd, item) {
     const path = specPath(cwd);
-    const normalized = item.trim().replace(/\s*\n+\s*/g, " ").slice(0, MAX_CASE);
-    const line = `- [ ] ${normalized}\n`;
+    const line = `- [ ] ${normalizeCase(item)}\n`;
     if (existsSync(path)) {
         appendFileSync(path, line, "utf8");
     }

package/dist/text.js

@@ -0,0 +1,12 @@
+// 케이스 텍스트 정규화 (spec.md 케이스 / defer 케이스 공용).
+// spec add와 defer add가 같은 규칙을 쓰도록 단일 소스로 추출한다(W2: 비대칭 제거).
+/** 한 케이스 길이 상한 — 무제한 기록·프롬프트 비대화 방지. spec/defer 공통. */
+export const MAX_CASE = 500;
+/**
+ * 케이스 한 줄을 정규화한다: 앞뒤 공백 제거 → 내부 줄바꿈을 단일 공백으로 접기 →
+ * 길이 상한 절단. readSpecCases의 단일라인 매칭·activeDeferItems 입력과 정합되게,
+ * 에이전트가 멀티라인/장문을 그대로 넘겨도 안전하다.
+ */
+export function normalizeCase(item) {
+    return item.trim().replace(/\s*\n+\s*/g, " ").slice(0, MAX_CASE);
+}

package/dist/version.js

@@ -0,0 +1,96 @@
+// ①신버전 안내 — npm 최신 버전을 캐시에 두고 SessionStart/PreToolUse/status에서 비교만 한다.
+// hook 핫패스에 동기 네트워크를 들이지 않는다: 표시는 캐시만 읽고, 갱신은 안전한 지점
+// (SessionStart·status)에서 짧은 타임아웃 fetch로만. 실패는 조용히 무시(게이트 무관, fail-silent).
+import { readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { homedir } from "node:os";
+const PKG = "geobuke-code";
+const TTL_MS = 24 * 60 * 60 * 1000; // 24h
+const FETCH_TIMEOUT_MS = 1500;
+export function cachePath(home = homedir()) {
+    return join(home, ".gbc", "version-check.json");
+}
+/**
+ * semver 비교(숫자 major.minor.patch만). a<b면 -1, 같으면 0, a>b면 1.
+ * prerelease/빌드메타·비숫자는 비교 불가로 보고 0(안내 안 함 → 거짓 안내 방지).
+ */
+export function compareVersions(a, b) {
+    const pa = a.split("-")[0].split(".");
+    const pb = b.split("-")[0].split(".");
+    for (let i = 0; i < 3; i++) {
+        const x = Number(pa[i] ?? 0);
+        const y = Number(pb[i] ?? 0);
+        if (Number.isNaN(x) || Number.isNaN(y))
+            return 0;
+        if (x < y)
+            return -1;
+        if (x > y)
+            return 1;
+    }
+    return 0;
+}
+export function readVersionCache(home) {
+    try {
+        const j = JSON.parse(readFileSync(cachePath(home), "utf8"));
+        if (typeof j.latest === "string" && typeof j.checkedAt === "number")
+            return j;
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+export function writeVersionCache(cache, home) {
+    try {
+        const path = cachePath(home);
+        // ~/.gbc가 없을 수 있다(api-key 없는 신규 설치 = ① 안내의 주 타깃) → 디렉토리 보장 후 기록.
+        mkdirSync(dirname(path), { recursive: true });
+        writeFileSync(path, JSON.stringify(cache));
+    }
+    catch {
+        /* 캐시 기록 실패는 무시(fail-silent) */
+    }
+}
+/** 캐시가 없거나 TTL(24h) 초과면 stale. now는 주입 가능(테스트). */
+export function isCacheStale(cache, now = Date.now()) {
+    if (!cache)
+        return true;
+    return now - cache.checkedAt > TTL_MS;
+}
+/**
+ * 신버전 안내 문자열(캐시만 비교, 네트워크 없음). cache.latest > current일 때만 안내, 아니면 "".
+ * 캐시 없음/비교불가/동일·하위면 "".
+ */
+export function buildVersionNotice(current, cache) {
+    if (!cache || !cache.latest || !current)
+        return "";
+    if (compareVersions(current, cache.latest) >= 0)
+        return "";
+    return (`🐢 거북이코드 신버전 ${cache.latest} 사용 가능(현재 ${current}). ` +
+        `갱신: npm i -g geobuke-code@latest → 각 프로젝트서 gbc init --yes`);
+}
+/**
+ * npm 레지스트리에서 최신 버전을 받아 캐시에 쓴다(짧은 타임아웃, 비차단·fail-silent).
+ * spawn(npm) 대신 fetch — Windows .cmd 실행 문제를 피한다. 실패·타임아웃은 조용히 무시.
+ */
+export async function refreshVersionCache(home, now = Date.now()) {
+    try {
+        const ctrl = new AbortController();
+        const timer = setTimeout(() => ctrl.abort(), FETCH_TIMEOUT_MS);
+        try {
+            const resp = await fetch(`https://registry.npmjs.org/${PKG}/latest`, { signal: ctrl.signal });
+            if (!resp.ok)
+                return;
+            const j = (await resp.json());
+            if (j && typeof j.version === "string") {
+                writeVersionCache({ latest: j.version, checkedAt: now }, home);
+            }
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    catch {
+        /* 네트워크 실패·타임아웃·파싱 실패 모두 무시(fail-silent) */
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "geobuke-code",
-  "version": "0.2.2",
+  "version": "0.2.3",
   "description": "거북이코드 — 구현 직전 강제 게이트. Claude Code PreToolUse hook으로 코드 변경 전 계획 케이스 누락·시나리오 미지정을 차단한다.",
   "type": "module",
   "bin": {