geobuke-code 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 cubha
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,127 @@
+# 거북이코드 (geobuke-code)
+
+> **구현 직전 강제 게이트.** Claude Code의 PreToolUse hook으로, 코드를 쓰기 *전에* 계획 케이스의 침묵 누락과 시나리오 미지정을 차단한다.
+
+`gbc`는 기존 코딩 에이전트(Claude Code) 위에 얹는 **얇은 게이트**다. 모델 계층을 소유하지 않는다 — 판단용 작은 호출(haiku)만 직접 하고, 코드 생성은 그대로 Claude Code가 한다.
+
+## 무엇을 푸는가
+
+구현 전에 강제되지 않는 두 가지가 반복 통증을 만든다:
+
+1. **선행 케이스를 "추후작업"으로 미루다 누락** → 설계 공백 → 큰 결함
+2. **시나리오 미지정으로 임의 구현** → 의도와 다른 동작
+
+게이트는 코드 변경(Edit/Write/MultiEdit) 직전에 끼어들어:
+
+- 계획 명세에 있는 케이스가 **침묵 누락**(언급도 등록도 없이 빠짐)되면 차단
+- 의도·동작 **시나리오가 미지정**인 채 구현되면 차단
+- **미루기는 명시 등록(`gbc defer add`)만 허용** — 침묵 누락 차단의 forcing function
+
+게이트는 *완전 구현*을 요구하지 않는다. 케이스가 다뤄지기 시작했거나 명시 defer되면 통과한다.
+
+## 설치
+
+> ⚠️ **현재 npm 미발행** — 아래 **로컬 개발 설치**가 유일한 경로다. (`npm install -g geobuke-code` 공개배포는 후속 A(public) 단계.)
+
+```bash
+# 1) 클론 + 빌드 (dist/ 생성)
+git clone https://github.com/cubha/geobuke-code.git
+cd geobuke-code
+npm install && npm run build
+
+# 2) gbc 명령 연결 — 택1
+npm link                          # 권한 OK면 전역 gbc 생성
+# ↑ EACCES(전역 node_modules가 root 소유)면 sudo 없이 PATH의 ~/.local/bin에 wrapper:
+printf '#!/bin/sh\nexec node "%s/dist/cli.js" "$@"\n' "$PWD" > ~/.local/bin/gbc && chmod +x ~/.local/bin/gbc
+
+# 3) 대상 프로젝트에 게이트 설치
+cd <your-project>
+gbc init                          # .claude/settings.json에 hook + /gate skill 머지 (동의·백업)
+```
+
+`gbc init`은 **프로젝트 로컬 `.claude/settings.json`만** 머지한다(append·멱등·백업). 전역 `~/.claude`는 건드리지 않는다.
+
+소스를 수정하면 `npm run build`만 다시 하면 된다 — wrapper/link는 같은 `dist/cli.js`를 가리키므로 재연결 불필요.
+
+## 빠른 게이트 활성화 (API 키 — 선택)
+
+`gbc init`은 키 주입 **없는** hook을 설치한다 → 기본은 `claude -p` 폴백(~13–20s). **haiku 직접 API(~1–3s)**를 쓰려면 키를 **hook 명령에만** 주입한다.
+
+> ⚠️ **`export ANTHROPIC_API_KEY=…` 전역 설정 금지.** Claude Code 본체가 그 키로 **과금 전환**된다(구독 대신 키 과금). 게이트 hook 서브프로세스에만 주입해야 안전하다.
+
+```bash
+# 1) 키를 파일에 저장 (권한 600)
+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"
+```
+
+`gbc status`엔 `트랜스포트: cli`로 보일 수 있다(status 명령 자체엔 키가 없어서). 무관하다 — 실제 hook 발동 시엔 위 주입으로 `api(haiku)` 경로로 동작한다.
+
+## 동작 원리
+
+```
+phase-protocol/계획 → /plan(SubTask) → 【게이트: 구현 직전 케이스확정】 → 구현(Claude Code) → 검증
+```
+
+게이트는 계획 명세를 다음 우선순위로 읽는다(durable 소스):
+`$GBC_SPEC_FILE` > `.gbc/spec.md` > `scratch.md`
+
+코드 변경 직전 PreToolUse hook이 명세 ↔ 변경 ↔ 미룬 항목을 대조해 통과/차단을 판정한다.
+
+### 시나리오 도출 루프 (수기 입력 불필요)
+
+명세가 비어 **시나리오 미지정**으로 차단되면, 사용자가 파일을 직접 쓰지 않는다. 차단 메시지가 코딩 에이전트에게 다음을 지시한다:
+
+```
+요청에서 시나리오 도출 → 사용자에게 제시·검증 → gbc spec add로 등록 → 재시도
+```
+
+- **도출**은 코딩 에이전트 본체(Opus, 대화 맥락 보유)가, **게이트 판정**은 haiku가 한다 — 두 작업/두 모델 분리. gbc는 모델 계층을 소유하지 않는다(판단용 작은 호출만).
+- **사용자 검증은 양보 불가**다 — 같은 에이전트가 도출+구현까지 자동으로 하면 자기 시나리오만 통과시키는 고무도장이 된다. 승인 없는 자동 등록을 금지한다.
+
+## 지연(latency)과 트랜스포트
+
+판정은 작은 LLM 호출이다. 두 트랜스포트:
+
+| 조건 | 트랜스포트 | 지연 |
+|---|---|---|
+| `ANTHROPIC_API_KEY` 설정됨 | Anthropic API 직접 (haiku, 최소 시스템프롬프트) | ~1–3s (목표) |
+| 미설정 | `claude -p` 폴백 (CC 인증 재사용, 무설정) | ~13–20s |
+
+**작업단위 1회**: 게이트는 작업단위(계획 명세 해시)당 한 번만 발동한다. 명세가 바뀌거나 명세 밖 파일을 편집할 때만 재발동 → 매 편집 지연을 피한다.
+
+> 빠른 게이트를 원하면 `ANTHROPIC_API_KEY`를 설정하라(설정법·과금 주의: 위 [「빠른 게이트 활성화」](#빠른-게이트-활성화-api-키--선택)). 없으면 `claude -p` 폴백으로 무설정 동작하되 작업단위당 한 번 느리다.
+
+## 명령
+
+| 명령 | 설명 |
+|---|---|
+| `gbc init` | hook + /gate skill 설치 |
+| `gbc status` | 게이트 상태 + 로드된 명세 확인 |
+| `gbc defer add "<케이스>"` | 케이스를 명시적으로 미루기 |
+| `gbc defer list` | 미룬 항목 목록 |
+| `gbc defer resolve <번호\|텍스트>` | 미룬 항목 해결 |
+| `gbc spec add "<케이스>"` | 승인된 시나리오를 `.gbc/spec.md`에 등록 |
+| `gbc spec show` | 등록된 케이스 목록 |
+| `gbc spec clear` | 명세 비우기(작업단위 종료) |
+| `gbc gate reset` | 작업단위 게이트 리셋 |
+
+우회: `GBC_NO_GATE=1` (계측됨 — 우회 자체가 게이트 가치 측정 데이터).
+
+## 정직한 한계
+
+- 사후 대조가 아닌 **구현 전 게이트**다 — "도중 탈선"은 못 잡는다(설계상 후속 C 영역).
+- 판정은 LLM이라 100% 아니다. **사람이 변이 전 케이스를 리뷰/편집하는 pause**가 진짜 가치다.
+- MVP scope = **B-커널**(CC-native hook + defer-registry + /gate). standalone TUI·추출 모드·계측 대시보드는 후속.
+- **검증 상태**: 게이트 판정 품질은 **양 트랜스포트 모두 회귀 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**: 판정 호출이 실패하면(키 오류·네트워크 등) 게이트는 조용히 통과시킨다(개발 차단 방지). 게이트가 무력화돼도 경고가 약하다는 트레이드오프 — 후속 관찰 항목.
+
+## 라이선스
+
+MIT

package/dist/cli.js

@@ -0,0 +1,249 @@
+#!/usr/bin/env node
+// gbc — 거북이코드 CLI. zero-dep 인자 파싱(핫패스 보호).
+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 { 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";
+const CLI_PATH = fileURLToPath(import.meta.url);
+const PKG_ROOT = join(dirname(CLI_PATH), ".."); // dist/cli.js → 패키지 루트
+/** ~/.gbc/api-key 존재 여부 — 있으면 hook에 키 주입(빠른 haiku 경로). */
+function hasApiKey() {
+    return existsSync(join(homedir(), ".gbc", "api-key"));
+}
+function stopCommand() {
+    return `node "${CLI_PATH}" hook stop`;
+}
+function nowStamp() {
+    try {
+        return new Date().toISOString().replace(/[:.]/g, "-");
+    }
+    catch {
+        return "backup";
+    }
+}
+// ---------- gbc init ----------
+function cmdInit(args) {
+    const cwd = process.cwd();
+    const yes = args.includes("--yes") || args.includes("-y");
+    const claudeDir = join(cwd, ".claude");
+    const settingsPath = join(claudeDir, "settings.json");
+    const skillDestDir = join(claudeDir, "skills", "gate");
+    const skillSrc = join(PKG_ROOT, "skills", "gate", "SKILL.md");
+    if (!yes) {
+        console.log(`🐢 gbc init — 다음을 수행합니다 (프로젝트 로컬만, 전역 ~/.claude 미변경):
+
+  대상 프로젝트: ${cwd}
+  1) ${settingsPath} 에 PreToolUse(Edit|Write) + Stop hook 추가 (머지·멱등)
+     - 기존 settings.json 있으면 백업: settings.json.bak-<시각>
+  2) ${join(skillDestDir, "SKILL.md")} 에 /gate 스킬 설치
+  3) hook 명령: ${buildPreCommand(CLI_PATH, hasApiKey())}
+
+  실행하려면: gbc init --yes
+`);
+        return;
+    }
+    mkdirSync(skillDestDir, { recursive: true });
+    // settings.json 머지
+    let settings = {};
+    if (existsSync(settingsPath)) {
+        const backup = `${settingsPath}.bak-${nowStamp()}`;
+        copyFileSync(settingsPath, backup);
+        console.log(`  백업: ${backup}`);
+        try {
+            settings = JSON.parse(readFileSync(settingsPath, "utf8"));
+        }
+        catch {
+            console.error(`  ⚠️ 기존 settings.json 파싱 실패 — 중단(수동 확인 필요). 백업은 보존됨.`);
+            process.exit(1);
+        }
+    }
+    const hooks = (settings.hooks ??= {});
+    const serialized = JSON.stringify(settings);
+    const useKey = hasApiKey();
+    // PreToolUse (멱등). 신규면 추가, 이미 있으면 keyless→키주입 업그레이드(skip만 하지 않음).
+    if (!serialized.includes("hook pre-tool-use")) {
+        (hooks.PreToolUse ??= []).push({
+            matcher: "Edit|Write|MultiEdit",
+            hooks: [{ type: "command", command: buildPreCommand(CLI_PATH, useKey) }],
+        });
+        console.log(`  + PreToolUse hook 추가${useKey ? " (API 키 주입)" : ""}`);
+    }
+    else {
+        const n = useKey ? upgradeKeylessHooks(settings, CLI_PATH, true) : 0;
+        if (n > 0)
+            console.log(`  ↑ PreToolUse hook 키주입 업그레이드 (${n}건)`);
+        else
+            console.log(`  = PreToolUse hook 이미 존재 (skip)`);
+    }
+    // Stop (멱등)
+    if (!serialized.includes("hook stop")) {
+        (hooks.Stop ??= []).push({
+            hooks: [{ type: "command", command: stopCommand() }],
+        });
+        console.log(`  + Stop hook 추가`);
+    }
+    else {
+        console.log(`  = Stop hook 이미 존재 (skip)`);
+    }
+    writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + "\n", "utf8");
+    // /gate 스킬 설치
+    if (existsSync(skillSrc)) {
+        copyFileSync(skillSrc, join(skillDestDir, "SKILL.md"));
+        console.log(`  + /gate 스킬 설치`);
+    }
+    const transport = selectedTransport();
+    console.log(`
+✅ 설치 완료. 트랜스포트: ${transport}${transport === "cli"
+        ? "  (ANTHROPIC_API_KEY 설정 시 직접 API로 ~1–3s, 미설정 시 claude -p 폴백 ~13–20s)"
+        : ""}
+   계획 명세는 scratch.md 또는 .gbc/spec.md 에 작성하세요(없으면 시나리오 미지정으로 차단).`);
+}
+// ---------- gbc status ----------
+function cmdStatus() {
+    const cwd = process.cwd();
+    const { text, source } = loadPlanSpec(cwd);
+    const hash = computeSpecHash(text);
+    const state = loadState(cwd);
+    const defers = loadDefers(cwd);
+    const unresolved = defers.filter((d) => !d.resolved);
+    console.log(`🐢 거북이 게이트 상태 — ${cwd}
+  트랜스포트: ${selectedTransport()}
+  명세 소스: ${source} ${text ? `(${text.length}자)` : "(비어있음 → 모든 코드변경 차단)"}
+  명세 해시: ${hash}
+  작업단위 게이트: ${state && state.specHash === hash && state.gated ? "통과됨(이 단위 재게이트 안 함)" : "미통과(다음 편집에서 발동)"}
+  defer: 전체 ${defers.length} / 미해결 ${unresolved.length}`);
+    if (unresolved.length > 0) {
+        console.log(unresolved.map((d, i) => `    ${i + 1}. ${d.item}`).join("\n"));
+    }
+}
+// ---------- gbc defer ----------
+function cmdDefer(args) {
+    const cwd = process.cwd();
+    const sub = args[0];
+    if (sub === "add") {
+        const item = args.slice(1).join(" ").trim();
+        if (!item) {
+            console.error('사용: gbc defer add "<케이스 설명>"');
+            process.exit(1);
+        }
+        addDefer(cwd, item);
+        console.log(`🐢 미룸 등록: ${item}`);
+    }
+    else if (sub === "list") {
+        const defers = loadDefers(cwd);
+        if (defers.length === 0) {
+            console.log("(미룬 항목 없음)");
+            return;
+        }
+        defers.forEach((d, i) => console.log(`${i + 1}. [${d.resolved ? "해결" : "미해결"}] ${d.item}`));
+    }
+    else if (sub === "resolve") {
+        const ref = args.slice(1).join(" ").trim();
+        const r = resolveDefer(cwd, ref);
+        console.log(r ? `🐢 해결 표시: ${r.item}` : `매칭되는 미룬 항목 없음: ${ref}`);
+    }
+    else {
+        console.error("사용: gbc defer <add|list|resolve> ...");
+        process.exit(1);
+    }
+}
+// ---------- gbc spec ----------
+function cmdSpec(args) {
+    const cwd = process.cwd();
+    const sub = args[0];
+    if (sub === "add") {
+        const item = args.slice(1).join(" ").trim();
+        if (!item) {
+            console.error('사용: gbc spec add "<케이스/시나리오>"');
+            process.exit(1);
+        }
+        addSpecCase(cwd, item);
+        console.log(`🐢 명세 등록: ${item}`);
+    }
+    else if (sub === "show") {
+        const cases = readSpecCases(cwd);
+        if (cases.length === 0) {
+            console.log("(등록된 케이스 없음 — .gbc/spec.md 비어있음)");
+            return;
+        }
+        cases.forEach((c, i) => console.log(`${i + 1}. ${c}`));
+    }
+    else if (sub === "clear") {
+        clearSpec(cwd);
+        console.log("🐢 명세 비움 — 다음 작업단위로 깨끗이 넘어갑니다.");
+    }
+    else {
+        console.error("사용: gbc spec <add|show|clear> ...");
+        process.exit(1);
+    }
+}
+// ---------- gbc gate ----------
+function cmdGate(args) {
+    if (args[0] === "reset") {
+        resetGate(process.cwd());
+        console.log("🐢 작업단위 게이트 리셋 — 다음 편집에서 다시 발동합니다.");
+    }
+    else {
+        console.error("사용: gbc gate reset");
+        process.exit(1);
+    }
+}
+function usage() {
+    console.log(`🐢 gbc — 거북이코드 구현-전 게이트
+
+사용:
+  gbc init [--yes]                    프로젝트에 hook + /gate 스킬 설치
+  gbc status                          게이트 상태 + 로드된 명세 확인
+  gbc defer add "<케이스>"             케이스를 명시적으로 미루기
+  gbc defer list                      미룬 항목 목록
+  gbc defer resolve <번호|텍스트>      미룬 항목 해결
+  gbc spec add "<케이스>"              승인된 시나리오를 .gbc/spec.md에 등록
+  gbc spec show                       등록된 케이스 목록
+  gbc spec clear                      명세 비우기(작업단위 종료)
+  gbc gate reset                      작업단위 게이트 리셋
+  gbc hook pre-tool-use               (내부) PreToolUse hook
+  gbc hook stop                       (내부) Stop hook
+`);
+}
+async function main() {
+    const [cmd, ...rest] = process.argv.slice(2);
+    switch (cmd) {
+        case "hook":
+            if (rest[0] === "pre-tool-use")
+                return runPreToolUse();
+            if (rest[0] === "stop")
+                return runStop();
+            console.error("사용: gbc hook <pre-tool-use|stop>");
+            process.exit(1);
+            break;
+        case "init":
+            return cmdInit(rest);
+        case "status":
+            return cmdStatus();
+        case "defer":
+            return cmdDefer(rest);
+        case "spec":
+            return cmdSpec(rest);
+        case "gate":
+            return cmdGate(rest);
+        case undefined:
+        case "help":
+        case "--help":
+        case "-h":
+            return usage();
+        default:
+            console.error(`알 수 없는 명령: ${cmd}`);
+            usage();
+            process.exit(1);
+    }
+}
+main().catch((e) => {
+    console.error(`gbc 오류: ${String(e)}`);
+    process.exit(1);
+});

package/dist/defer.js

@@ -0,0 +1,54 @@
+import { join } from "node:path";
+import { gbcDir, readJson, writeJson } from "./store.js";
+function deferPath(cwd) {
+    return join(gbcDir(cwd), "defers.json");
+}
+function nowIso() {
+    try {
+        return new Date().toISOString();
+    }
+    catch {
+        return "";
+    }
+}
+export function loadDefers(cwd) {
+    return readJson(deferPath(cwd), []);
+}
+function save(cwd, defers) {
+    writeJson(deferPath(cwd), defers);
+}
+/** 명시적으로 항목을 미룬다 (침묵 누락 차단의 유일한 정당 경로) */
+export function addDefer(cwd, item) {
+    const defers = loadDefers(cwd);
+    const entry = { item, at: nowIso(), resolved: false };
+    defers.push(entry);
+    save(cwd, defers);
+    return entry;
+}
+/** 미해결 defer 항목 텍스트만 (게이트 판정 입력용) */
+export function activeDeferItems(cwd) {
+    return loadDefers(cwd)
+        .filter((d) => !d.resolved)
+        .map((d) => d.item);
+}
+/** 미해결 defer 엔트리 (Stop hook 리마인드용) */
+export function unresolvedDefers(cwd) {
+    return loadDefers(cwd).filter((d) => !d.resolved);
+}
+/** 인덱스(1-base) 또는 부분 텍스트 매칭으로 defer 해결 표시 */
+export function resolveDefer(cwd, ref) {
+    const defers = loadDefers(cwd);
+    let target;
+    const idx = Number.parseInt(ref, 10);
+    if (!Number.isNaN(idx) && idx >= 1 && idx <= defers.length) {
+        target = defers[idx - 1];
+    }
+    else {
+        target = defers.find((d) => !d.resolved && d.item.includes(ref));
+    }
+    if (!target)
+        return null;
+    target.resolved = true;
+    save(cwd, defers);
+    return target;
+}

package/dist/eval/regression.js

@@ -0,0 +1,36 @@
+// 회귀 하네스: gate-spike의 cases.json을 production judge로 돌려 판정 품질을 확인한다.
+// 트랜스포트는 judge가 자동 선택(ANTHROPIC_API_KEY 있으면 API, 없으면 claude -p).
+// 사용: node dist/eval/regression.js [cases.json 경로]
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+import { judge, selectedTransport } from "../judge.js";
+const here = dirname(fileURLToPath(import.meta.url));
+const casesPath = process.argv[2] ?? join(here, "..", "..", "test", "cases.json");
+const cases = JSON.parse(readFileSync(casesPath, "utf8"));
+console.log(`트랜스포트: ${selectedTransport()}  ·  케이스 ${cases.length}개  ·  파일 ${casesPath}\n`);
+const results = [];
+for (const c of cases) {
+    const t0 = Date.now();
+    // 회귀는 defer 없는 기본 상태에서의 판정 품질을 본다.
+    const v = await judge(c.plan_spec, c.edit_diff, []);
+    const ms = Date.now() - t0;
+    const ok = v.verdict === c.expected;
+    results.push({ id: c.id, expected: c.expected, got: v.verdict, ok, ms, reason: v.reason });
+    console.log(`${ok ? "✓" : "✗"} ${c.id}: exp=${c.expected} got=${v.verdict} (${ms}ms) — ${v.reason}`);
+}
+const tp = results.filter((r) => r.expected === "block" && r.got === "block").length;
+const tn = results.filter((r) => r.expected === "pass" && r.got === "pass").length;
+const fp = results.filter((r) => r.expected === "pass" && r.got === "block").length;
+const fn = results.filter((r) => r.expected === "block" && r.got === "pass").length;
+const avg = Math.round(results.reduce((s, r) => s + r.ms, 0) / results.length);
+const pass = tp + tn;
+console.log(`\n===== 결과 =====`);
+console.log(`TP=${tp}(누락차단) TN=${tn}(정상통과) FP=${fp}(오탐) FN=${fn}(미탐)`);
+console.log(`정확도 ${pass}/${results.length}  ·  평균지연 ${avg}ms`);
+// 회귀 기준: 8/8 (스파이크 baseline). 미달 시 비정상 종료로 신호.
+if (pass < results.length) {
+    console.error(`\n⚠️ 회귀 실패: ${pass}/${results.length} (baseline 8/8 미달)`);
+    process.exit(1);
+}
+console.log(`\n✅ 회귀 통과: baseline 유지`);

package/dist/hook.js

@@ -0,0 +1,159 @@
+// PreToolUse / Stop hook 핸들러.
+// 핫패스 보호: 이 파일은 SDK를 import하지 않는다. judge.ts가 API 호출 시에만 lazy import.
+// "이미 게이트됨 → exit 0"은 상태파일만 읽고 즉시 종료(judge 미호출).
+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 { appendFileSync } from "node:fs";
+import { join } from "node:path";
+import { gbcDir } from "./store.js";
+/**
+ * 차단 사유 메시지를 빌드한다. 두 차단 종류를 다르게 안내한다:
+ * - specEmpty=true (시나리오 미지정): 에이전트가 요청에서 시나리오를 도출 → 사용자 검증 →
+ *   'gbc spec add'로 등록 후 재시도하도록 지시한다(도출 루프 트리거). 자동 등록 금지.
+ * - specEmpty=false (침묵 누락): 지금 다루거나 'gbc defer add'로 명시 미루도록 안내한다.
+ */
+export function buildBlockReason(verdict, specEmpty, source) {
+    if (specEmpty) {
+        return (`🐢 거북이 게이트 — ${verdict.reason}\n` +
+            `→ [에이전트] 사용자 요청에서 의도·동작 시나리오를 도출해 사용자에게 제시·검증받은 뒤, ` +
+            `승인된 케이스를 'gbc spec add "<케이스>"'로 등록하고 재시도하세요. ` +
+            `사용자 승인 없이 자동 등록하지 마세요. (명세 소스: ${source})`);
+    }
+    const missingLine = verdict.missing.length > 0 ? `\n누락(침묵): ${verdict.missing.join(", ")}` : "";
+    return (`🐢 거북이 게이트 — ${verdict.reason}${missingLine}\n` +
+        `→ 지금 이 변경에서 다루거나, 의도적으로 미룰 거면 'gbc defer add "<케이스>"'로 명시 등록 후 진행하세요.` +
+        ` (명세 소스: ${source})`);
+}
+/**
+ * pass verdict를 작업단위 캐시(markGated)에 넣어도 되는가.
+ * fail-open(판정 실패 안전통과)은 제외 — 일시 장애가 작업단위 내내 게이트를 무력화하는 것을 막는다.
+ */
+export function shouldCacheVerdict(verdict) {
+    return verdict.verdict === "pass" && !verdict.failOpen;
+}
+function readStdin() {
+    return new Promise((resolve) => {
+        let data = "";
+        process.stdin.setEncoding("utf8");
+        process.stdin.on("data", (c) => (data += c));
+        process.stdin.on("end", () => resolve(data));
+        process.stdin.on("error", () => resolve(data));
+        // stdin이 비어있는 경우 대비
+        if (process.stdin.isTTY)
+            resolve("");
+    });
+}
+function emit(obj) {
+    process.stdout.write(JSON.stringify(obj));
+}
+function logBypass(cwd, toolName) {
+    try {
+        appendFileSync(join(gbcDir(cwd), "bypass.log"), `${new Date().toISOString()} ${toolName}\n`);
+    }
+    catch {
+        /* 계측 실패는 무시 */
+    }
+}
+/** fail-open(판정 실패 안전통과) 계측 — 게이트가 무력화된 편집을 사후 추적할 수 있게 한다. */
+function logFailOpen(cwd, toolName, reason) {
+    try {
+        appendFileSync(join(gbcDir(cwd), "failopen.log"), `${new Date().toISOString()} ${toolName} ${reason}\n`);
+    }
+    catch {
+        /* 계측 실패는 무시 */
+    }
+}
+/** PreToolUse: 코드 변경 직전 게이트 */
+export async function runPreToolUse() {
+    let input = {};
+    try {
+        const raw = await readStdin();
+        input = raw ? JSON.parse(raw) : {};
+    }
+    catch {
+        // 입력 파싱 실패 → 안전하게 통과(fail-open)
+        process.exit(0);
+    }
+    const toolName = input.tool_name ?? "";
+    const cwd = input.cwd || process.cwd();
+    // 코드 변경 도구가 아니면 즉시 통과
+    if (!isGatedTool(toolName))
+        process.exit(0);
+    // 명시적 우회 (계측됨)
+    if (process.env.GBC_NO_GATE === "1") {
+        logBypass(cwd, toolName);
+        process.exit(0);
+    }
+    const { text: specText, source } = loadPlanSpec(cwd);
+    const specHash = computeSpecHash(specText);
+    // 작업단위 1회: 이미 게이트 통과한 단위면 즉시 통과 (judge 미호출, 핫패스)
+    if (isGated(cwd, specHash))
+        process.exit(0);
+    // judge는 여기서만 동적 import (SDK lazy)
+    const { judge } = await import("./judge.js");
+    const editText = normalizeEdit(toolName, input.tool_input ?? {});
+    const defers = activeDeferItems(cwd);
+    const verdict = await judge(specText, editText, defers);
+    if (verdict.verdict === "pass") {
+        if (shouldCacheVerdict(verdict)) {
+            markGated(cwd, specHash, verdict.reason);
+            process.exit(0); // 정상 통과 (자동승인 X — 무출력)
+        }
+        // fail-open: 판정 실패로 안전 통과. 캐시하지 않아(작업단위 무력화 방지) 다음 편집에서 재판정.
+        // 계측 + systemMessage로 사용자에게 "게이트가 검사 못 했음"을 알린다(조용한 무력화 방지).
+        logFailOpen(cwd, toolName, verdict.reason);
+        emit({
+            systemMessage: `🐢 거북이 게이트 — 판정 실패로 안전 통과(fail-open). 이 편집은 게이트 검사를 받지 못했습니다: ${verdict.reason}`,
+            hookSpecificOutput: {
+                hookEventName: "PreToolUse",
+                permissionDecision: "allow",
+                permissionDecisionReason: verdict.reason,
+            },
+        });
+        process.exit(0);
+    }
+    // block: 사람 pause (ask 기본) — 사유가 사용자에게 표시됨
+    // 시나리오 미지정(명세 빈약)과 침묵 누락을 다르게 안내한다.
+    const reason = buildBlockReason(verdict, specText.trim() === "", source);
+    const mode = process.env.GBC_BLOCK_MODE === "deny" ? "deny" : "ask";
+    emit({
+        hookSpecificOutput: {
+            hookEventName: "PreToolUse",
+            permissionDecision: mode,
+            permissionDecisionReason: reason,
+            additionalContext: reason,
+        },
+    });
+    process.exit(0);
+}
+/** Stop: 미해결 defer 리마인드 (stop_hook_active 가드로 1회만) */
+export async function runStop() {
+    let input = {};
+    try {
+        const raw = await readStdin();
+        input = raw ? JSON.parse(raw) : {};
+    }
+    catch {
+        process.exit(0);
+    }
+    // 이미 한 번 리마인드해 계속 진행 중이면 루프 방지 위해 통과
+    if (input.stop_hook_active === true)
+        process.exit(0);
+    const cwd = input.cwd || process.cwd();
+    // defers.json 없으면(파일 부재) 조용히 통과
+    if (loadDefers(cwd).length === 0)
+        process.exit(0);
+    const un = unresolvedDefers(cwd);
+    if (un.length === 0)
+        process.exit(0);
+    const items = un.map((d, i) => `${i + 1}. ${d.item}`).join("\n");
+    emit({
+        decision: "block",
+        reason: `🐢 미해결 defer ${un.length}건이 남아 있습니다:\n${items}\n` +
+            `해결했으면 'gbc defer resolve <번호>', 다음 세션으로 이월할 거면 의식적으로 확인하세요. ` +
+            `(이 리마인드는 1회만 표시됩니다.)`,
+    });
+    process.exit(0);
+}

package/dist/install.js

@@ -0,0 +1,39 @@
+// gbc init 설치 로직 (순수함수 — cli.ts main() 부작용 없이 단위테스트 가능).
+// 키 주입은 셸 확장($HOME)으로 머신 독립적이게 한다(하드코딩 홈경로 금지).
+/**
+ * PreToolUse hook 명령 생성.
+ * useKey=true면 ANTHROPIC_API_KEY를 $HOME/.gbc/api-key에서 읽어 주입(빠른 haiku 경로).
+ * 경로는 셸이 확장하는 $HOME을 써 머신 독립적이게 한다.
+ */
+/**
+ * 더블쿼트 컨텍스트용 이스케이프. 셸이 확장하거나 따옴표를 벗어나지 못하도록
+ * `"` 백틱 `$` `\` 를 백슬래시 처리한다(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;
+}
+/**
+ * 이미 설치된 keyless PreToolUse hook command를 키 주입 버전으로 업그레이드.
+ * settings를 제자리 수정하고, 업그레이드한 건수를 반환한다(멱등: 이미 키주입된 건 건너뜀).
+ */
+export function upgradeKeylessHooks(settings, cliPath, useKey) {
+    if (!useKey)
+        return 0;
+    const target = buildPreCommand(cliPath, true);
+    let upgraded = 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")) {
+                h.command = target;
+                upgraded++;
+            }
+        }
+    }
+    return upgraded;
+}

package/dist/judge.js

@@ -0,0 +1,113 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+const execFileAsync = promisify(execFile);
+const MODEL = process.env.GBC_MODEL ?? "claude-haiku-4-5";
+/**
+ * 최소 게이트 시스템 프롬프트.
+ * 의미론(핵심): 한 편집이 모든 케이스를 *완전 구현*할 필요는 없다.
+ * 침묵 누락(언급도 명시 defer도 없이 빠뜨림)과 시나리오 미지정만 차단한다.
+ */
+const GATE_SYSTEM = `너는 코드 구현 직전에 동작하는 "게이트"다. 개발자가 막 파일을 편집하려 한다.
+[계획 명세]·[현재 편집]·[명시적으로 미룬 항목]을 보고 통과(pass)/차단(block)을 판정하라.
+
+[1단계 — 편집의 종류 분류]
+이 편집이 프로그램의 *동작(behavior)을 구현하거나 바꾸는* 코드 편집인가, 아니면 동작과 무관한 편집인가?
+- 동작과 무관한 편집 → **무조건 pass.** 예: 문서/README 수정, 단순 변수·함수 리네임, 포매팅/들여쓰기, 주석만 추가, 동작 불변 리팩터, 설정/빌드 파일 변경.
+  (판별 팁: 함수 본문의 로직/검증/분기/반환을 새로 쓰거나 바꾸면 "동작 편집". 이름만 바꾸거나 글자만 옮기면 "무관".)
+- 동작을 구현/변경하는 코드 편집 → 2단계로.
+
+[2단계 — 동작 편집일 때만 검사]
+(a) [계획 명세]가 없거나 빈약해서 이 동작의 의도·시나리오가 미지정인 채 구현되고 있는가? → **block** (시나리오 미지정).
+(b) 계획 명세가 있다면: 이 편집이 작성/수정하는 *바로 그 기능*에 대해 계획에 적힌 형제 케이스 중, 이 편집에서도 안 다뤄지고 [명시적으로 미룬 항목]에도 없는 것이 있는가? → **block** (침묵 누락).
+    - 예: 로그인 검증 함수를 쓰면서 계획의 로그인 검증 케이스(중복 이메일·비밀번호 길이 등)를 언급·등록 없이 빠뜨림.
+    - 코드 주석으로 "나중에"라고만 적고 미룬 항목에 등록 안 한 것도 침묵 누락이다.
+    - 계획이 요구한 동작 형태(예: 인라인 에러 메시지)를 충족 못 하고 다른 형태(예: bool만 반환)로 빠뜨린 것도 누락이다.
+(c) 위에 해당 없으면 → **pass**.
+
+핵심 균형:
+- 무관한 편집(1단계)을 "계획 케이스를 안 다뤘다"는 이유로 차단하지 마라(가장 흔한 오탐).
+- 그러나 *같은 기능을 구현하는* 동작 편집이 계획된 형제 케이스를 침묵 누락하면 반드시 차단하라. "첫 케이스를 시작했다"는 이유로 나머지 침묵 누락을 눈감지 마라(가장 흔한 미탐). 한 편집이 모든 케이스를 *완전 구현*할 필요는 없지만, 형제 케이스는 최소한 다뤄지거나 명시 defer돼 있어야 한다.
+
+오직 아래 JSON만 출력(설명·마크다운 펜스 금지):
+{"verdict":"block"|"pass","missing":["누락된 케이스"],"reason":"한 줄 사유"}`;
+function buildUserMessage(planSpec, editText, defers) {
+    const deferText = defers.length > 0 ? defers.map((d) => `- ${d}`).join("\n") : "(없음)";
+    return `[계획 명세]
+${planSpec.trim() || "(계획 명세 없음 — 개발자가 곧바로 구현을 시작함)"}
+
+[명시적으로 미룬 항목]
+${deferText}
+
+[현재 편집]
+${editText}`;
+}
+function parseVerdict(raw) {
+    const m = raw.match(/\{[\s\S]*\}/);
+    if (!m)
+        throw new Error(`게이트 응답에서 JSON을 찾지 못함: ${raw.slice(0, 200)}`);
+    const j = JSON.parse(m[0]);
+    const verdict = j.verdict === "block" ? "block" : "pass";
+    return {
+        verdict,
+        missing: Array.isArray(j.missing) ? j.missing.map(String) : [],
+        reason: typeof j.reason === "string" ? j.reason : "",
+    };
+}
+/** 트랜스포트 선택 결과 (디버그/리포트용) */
+export function selectedTransport() {
+    return process.env.ANTHROPIC_API_KEY ? "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 환경변수 사용
+    const resp = await client.messages.create({
+        model: MODEL,
+        max_tokens: 1024,
+        system,
+        messages: [{ role: "user", content: user }],
+    });
+    const texts = [];
+    for (const block of resp.content) {
+        if (block.type === "text")
+            texts.push(block.text);
+    }
+    return texts.join("");
+}
+/** 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 });
+    const env = JSON.parse(stdout);
+    return env.result ?? "";
+}
+/**
+ * 게이트 판정. ANTHROPIC_API_KEY 있으면 직접 API(빠름), 없으면 claude -p 폴백.
+ * 실패 시 안전하게 pass(fail-open) — 게이트가 개발을 막아버리는 사고 방지.
+ */
+export async function judge(planSpec, editText, defers = []) {
+    const user = buildUserMessage(planSpec, editText, defers);
+    const transport = selectedTransport();
+    try {
+        const raw = transport === "api"
+            ? await judgeViaApi(GATE_SYSTEM, user)
+            : await judgeViaCli(GATE_SYSTEM, user);
+        return parseVerdict(raw);
+    }
+    catch (e) {
+        return failOpenVerdict(e);
+    }
+}
+/**
+ * 판정 호출 실패 시의 안전 통과(fail-open) verdict.
+ * failOpen=true로 표시해 hook이 캐시 제외·계측할 수 있게 한다.
+ */
+export function failOpenVerdict(e) {
+    return {
+        verdict: "pass",
+        missing: [],
+        reason: `게이트 판정 실패(fail-open): ${String(e).slice(0, 160)}`,
+        failOpen: true,
+    };
+}
+export { GATE_SYSTEM, buildUserMessage, parseVerdict };

package/dist/normalize.js

@@ -0,0 +1,28 @@
+const MAX_FIELD = 4000; // 프롬프트 비대화/지연 방지용 필드 절단 길이
+function clip(s) {
+    if (!s)
+        return "";
+    return s.length > MAX_FIELD ? s.slice(0, MAX_FIELD) + "\n…(절단됨)" : s;
+}
+/**
+ * PreToolUse tool_input(Edit/Write/MultiEdit)을 게이트 프롬프트용
+ * diff 유사 텍스트로 정규화한다. tool_name으로 분기.
+ */
+export function normalizeEdit(toolName, input) {
+    const file = input.file_path ?? "(파일경로 없음)";
+    // Write: 파일 전체 생성/덮어쓰기
+    if (toolName === "Write" || (input.content !== undefined && !input.old_string && !input.edits)) {
+        return `--- ${file} (전체 작성/덮어쓰기)\n+ ${clip(input.content)}`;
+    }
+    // MultiEdit: edits 배열
+    if (toolName === "MultiEdit" || Array.isArray(input.edits)) {
+        const parts = (input.edits ?? []).map((e, i) => `# 편집 ${i + 1}\n- ${clip(e.old_string)}\n+ ${clip(e.new_string)}`);
+        return `--- ${file} (다중 편집)\n${parts.join("\n")}`;
+    }
+    // Edit: 단일 치환
+    return `--- ${file}\n- ${clip(input.old_string)}\n+ ${clip(input.new_string)}`;
+}
+/** 게이트 대상(코드 변경)인 도구인지 */
+export function isGatedTool(toolName) {
+    return toolName === "Edit" || toolName === "Write" || toolName === "MultiEdit";
+}

package/dist/spec.js

@@ -0,0 +1,75 @@
+import { readFileSync, writeFileSync, appendFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { createHash } from "node:crypto";
+import { gbcDir } from "./store.js";
+const MAX_SPEC = 12000; // 명세 텍스트 절단 (프롬프트 비대화 방지)
+/**
+ * 계획 명세를 디스크에서 로드한다. (advisor④: durable 소스만 — 라이브 SubTask는 영속 X)
+ * 우선순위: GBC_SPEC_FILE > .gbc/spec.md > scratch.md > "" (빈 명세 = 시나리오 미지정 → 통증#2 차단)
+ *
+ * 느슨 매칭은 게이트 LLM이 담당한다(체크리스트 라인/SubTask 항목). 로더는 텍스트만 제공.
+ */
+export function loadPlanSpec(cwd) {
+    const candidates = [];
+    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 {
+                const raw = readFileSync(path, "utf8");
+                const text = raw.length > MAX_SPEC ? raw.slice(0, MAX_SPEC) + "\n…(절단됨)" : raw;
+                return { text, source: path };
+            }
+            catch {
+                // 읽기 실패는 다음 후보로
+            }
+        }
+    }
+    return { text: "", source: "(없음)" };
+}
+/** 명세 해시 — 작업단위 식별용. 명세가 바뀌면 새 작업단위로 간주해 재게이트. */
+export function computeSpecHash(text) {
+    return createHash("sha256").update(text).digest("hex").slice(0, 16);
+}
+// --- spec.md 쓰기 (gbc spec 서브커맨드 백엔드) ---
+// 도출→검증→등록 루프에서, 사용자 승인된 시나리오를 durable 명세로 기록한다.
+// 주 경로는 에이전트가 .gbc/spec.md를 직접 작성하는 것이고, 이 CLI는 한 줄 케이스 추가용 보조.
+const MAX_CASE = 500; // 한 케이스 길이 상한 (spec.md 비대화·무제한 기록 방지)
+function specPath(cwd) {
+    return join(gbcDir(cwd), "spec.md");
+}
+/**
+ * 케이스 한 줄을 .gbc/spec.md에 append. 파일 없으면 헤더와 함께 생성.
+ * 입력은 한 줄로 정규화한다: 줄바꿈→공백(readSpecCases 단일라인 매칭과 정합),
+ * 길이 상한 절단(에이전트가 멀티라인/장문 출력을 그대로 add해도 안전).
+ */
+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`;
+    if (existsSync(path)) {
+        appendFileSync(path, line, "utf8");
+    }
+    else {
+        writeFileSync(path, `# 작업 명세\n\n${line}`, "utf8");
+    }
+}
+/** 현재 spec.md의 케이스(체크리스트 라인) 텍스트만 추출. */
+export function readSpecCases(cwd) {
+    const path = specPath(cwd);
+    if (!existsSync(path))
+        return [];
+    const cases = [];
+    for (const raw of readFileSync(path, "utf8").split("\n")) {
+        const m = raw.match(/^\s*-\s*\[[ xX]\]\s*(.+?)\s*$/);
+        if (m)
+            cases.push(m[1]);
+    }
+    return cases;
+}
+/** 작업단위 완료 시 spec.md를 비운다 (다음 작업단위로 깨끗이 넘어가기). */
+export function clearSpec(cwd) {
+    writeFileSync(specPath(cwd), "", "utf8");
+}

package/dist/state.js

@@ -0,0 +1,41 @@
+import { join } from "node:path";
+import { gbcDir, readJson, writeJson } from "./store.js";
+function statePath(cwd) {
+    return join(gbcDir(cwd), "state.json");
+}
+export function loadState(cwd) {
+    return readJson(statePath(cwd), null);
+}
+function nowIso() {
+    // Date.now/new Date()는 일부 실행환경에서 금지될 수 있어 안전하게 처리
+    try {
+        return new Date().toISOString();
+    }
+    catch {
+        return "";
+    }
+}
+/**
+ * 이 작업단위(specHash)가 이미 게이트를 통과했는가?
+ * 명세가 바뀌면(specHash 불일치) 새 작업단위 → 미게이트로 간주.
+ */
+export function isGated(cwd, specHash) {
+    const s = loadState(cwd);
+    return !!s && s.specHash === specHash && s.gated;
+}
+/** 이 작업단위를 게이트 통과로 표시 (작업단위 1회 캐시) */
+export function markGated(cwd, specHash, reason) {
+    const state = { specHash, gated: true, lastReason: reason, at: nowIso() };
+    writeJson(statePath(cwd), state);
+}
+/** 작업단위 리셋 — 다음 편집에서 다시 게이트 발동 */
+export function resetGate(cwd) {
+    const s = loadState(cwd);
+    const state = {
+        specHash: s?.specHash ?? "",
+        gated: false,
+        lastReason: "수동 리셋",
+        at: nowIso(),
+    };
+    writeJson(statePath(cwd), state);
+}

package/dist/store.js

@@ -0,0 +1,22 @@
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+/** .gbc 디렉토리 경로 보장 */
+export function gbcDir(cwd) {
+    const dir = join(cwd, ".gbc");
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true });
+    return dir;
+}
+export function readJson(path, fallback) {
+    if (!existsSync(path))
+        return fallback;
+    try {
+        return JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch {
+        return fallback;
+    }
+}
+export function writeJson(path, data) {
+    writeFileSync(path, JSON.stringify(data, null, 2) + "\n", "utf8");
+}

package/dist/types.js

@@ -0,0 +1,2 @@
+// 거북이코드 게이트 공통 타입
+export {};

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "geobuke-code",
+  "version": "0.1.0",
+  "description": "거북이코드 — 구현 직전 강제 게이트. Claude Code PreToolUse hook으로 코드 변경 전 계획 케이스 누락·시나리오 미지정을 차단한다.",
+  "type": "module",
+  "bin": {
+    "gbc": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "skills"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "node --test 'test/**/*.test.mjs'",
+    "eval": "node dist/eval/regression.js",
+    "prepare": "tsc",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "keywords": [
+    "claude-code",
+    "hook",
+    "gate",
+    "pre-implementation",
+    "code-review"
+  ],
+  "license": "MIT",
+  "author": "cubha",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/cubha/geobuke-code.git"
+  },
+  "dependencies": {
+    "@anthropic-ai/sdk": "^0.40.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.6.0"
+  }
+}

package/skills/gate/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: gate
+description: 거북이코드 구현-전 게이트를 관리한다. 로드된 계획 명세 확인, 미룬(defer) 항목 등록·조회·해결, 작업단위 게이트 리셋. PreToolUse hook이 코드 변경을 차단했을 때 이 스킬로 케이스를 명시적으로 미루거나 게이트 상태를 점검한다. '/gate', '게이트 상태', '케이스 미루기', 'defer 등록', '게이트 리셋', '게이트가 막아' 등 언급 시 호출.
+---
+
+# /gate — 구현-전 게이트 관리
+
+거북이코드(`gbc`)는 코드 변경(Edit/Write/MultiEdit) 직전에 PreToolUse hook으로 동작해, **계획 명세의 케이스를 침묵 누락하거나 시나리오 미지정으로 구현이 진행되는 것**을 차단한다. 이 스킬은 그 게이트를 사람이 관리하는 표면이다.
+
+## 핵심 원칙
+
+- **미루기는 명시 등록만 허용한다.** "추후작업"이라고 머릿속/주석으로만 미루면 게이트가 침묵 누락으로 차단한다. 정당한 미루기는 반드시 `gbc defer add`로 등록해야 통과된다. (= 통증 "추후작업 미루다 누락" 직격)
+- **게이트는 완전구현을 요구하지 않는다.** 케이스가 다뤄지기 시작했거나 명시 defer되면 통과. 침묵 누락과 시나리오 미지정만 막는다.
+
+## 명령 (bash로 실행)
+
+게이트는 현재 프로젝트 루트의 `gbc`를 사용한다. 작업 디렉토리에서 실행:
+
+| 의도 | 명령 |
+|---|---|
+| 게이트 상태·로드된 명세 확인 | `gbc status` |
+| 미룬 항목 목록 | `gbc defer list` |
+| 케이스를 명시적으로 미루기 | `gbc defer add "<케이스 설명>"` |
+| 미룬 항목 해결 표시 | `gbc defer resolve <번호 또는 텍스트>` |
+| 승인된 시나리오를 명세에 등록 | `gbc spec add "<케이스>"` |
+| 등록된 케이스 목록 | `gbc spec show` |
+| 명세 비우기(작업단위 종료) | `gbc spec clear` |
+| 작업단위 게이트 리셋(다음 편집에서 재발동) | `gbc gate reset` |
+
+## 사용 흐름
+
+1. **게이트가 변경을 차단했을 때**: hook이 사유와 누락 케이스를 알려준다. 두 갈래로 해소한다:
+   - (a) 누락 케이스를 **지금 이 변경에서 다룬다** → 다시 시도하면 통과.
+   - (b) 의도적으로 나중에 할 케이스면 **`gbc defer add "케이스"`로 명시 등록** → 통과. (절대 주석으로만 미루지 말 것)
+2. **시나리오 미지정으로 차단됐을 때 — 에이전트 도출 루프**: 사용자가 명세를 수기로 쓰지 않는다. 에이전트가 다음을 수행한다:
+   1. 사용자 요청에서 의도·동작 시나리오와 형제 케이스를 **도출**한다.
+   2. 도출한 케이스를 사용자에게 **제시하고 검증받는다** — **사용자 승인 없이 자동 등록·구현 금지**(같은 에이전트가 도출+구현하면 고무도장이 됨).
+   3. 승인된 케이스를 `gbc spec add "<케이스>"`로 등록하거나 `.gbc/spec.md`에 직접 작성한다.
+   4. 재시도하면 통과한다.
+   > 시나리오 도출은 코딩 에이전트 본체(Opus)가 대화 맥락으로, 게이트 판정은 haiku가 — 두 작업/두 모델 분리(gbc는 모델 계층을 소유하지 않는다).
+3. **세션 종료 시**: Stop hook이 미해결 defer를 리마인드한다. `gbc defer list`로 확인하고 해결하거나 다음 세션으로 의식적으로 이월한다.
+
+## 명세 소스
+
+게이트는 다음 우선순위로 계획 명세를 읽는다(durable 소스만):
+`$GBC_SPEC_FILE` > `.gbc/spec.md` > `scratch.md`
+
+명세가 비면 "시나리오 미지정"으로 모든 코드 변경이 차단된다. 작업 전 `scratch.md`에 SubTask/체크리스트를 적거나 `.gbc/spec.md`를 만든다.
+
+## Known Pitfalls
+
+- **주석 defer는 defer가 아니다.** `// 비밀번호 검증은 다음에` 같은 코드 주석은 게이트가 침묵 누락으로 본다. 반드시 `gbc defer add`로 레지스트리에 등록해야 한다.
+- **게이트는 작업단위당 1회만 발동한다.** 명세가 바뀌거나 명세 밖 파일을 편집할 때 재발동한다. 강제로 다시 점검하려면 `gbc gate reset`.
+- **`--no-gate` / `GBC_NO_GATE=1` 우회는 계측된다.** 우회 자체가 게이트 가치 측정 데이터가 된다.