geobuke-code 0.2.1 → 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>
@@ -84,11 +84,23 @@ Set-Content -Path "$HOME\.gbc\api-key" -Value "sk-ant-..." -NoNewline
 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이 추가된다.
+
 ### 시나리오 도출 루프 (수기 입력 불필요)
 
 명세가 비어 **시나리오 미지정**으로 차단되면, 사용자가 파일을 직접 쓰지 않는다. 차단 메시지가 코딩 에이전트에게 다음을 지시한다:

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, normalizeHooks } 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,7 +60,7 @@ 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)}
@@ -113,6 +113,13 @@ ${hasApiKey()
     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)) {
@@ -124,7 +131,7 @@ ${hasApiKey()
 ✅ 설치 완료. 트랜스포트: ${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() {
@@ -265,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() {
@@ -275,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

@@ -31,3 +31,26 @@ export function normalizeHooks(settings, cliPath) {
     }
     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/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.1",
+  "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",