geobuke-code 0.1.0 → 0.2.0

package/README.md

@@ -21,7 +21,17 @@
 
 ## 설치
 
-> ⚠️ **현재 npm 미발행** — 아래 **로컬 개발 설치**가 유일한 경로다. (`npm install -g geobuke-code` 공개배포는 후속 A(public) 단계.)
+```bash
+# 1) 전역 설치
+npm install -g geobuke-code
+
+# 2) 대상 프로젝트에 게이트 설치
+cd <your-project>
+gbc init                          # .claude/settings.json에 hook + /gate skill 머지 (동의·백업)
+```
+
+<details>
+<summary>로컬 개발 설치 (소스에서 빌드)</summary>
 
 ```bash
 # 1) 클론 + 빌드 (dist/ 생성)
@@ -36,13 +46,15 @@ printf '#!/bin/sh\nexec node "%s/dist/cli.js" "$@"\n' "$PWD" > ~/.local/bin/gbc
 
 # 3) 대상 프로젝트에 게이트 설치
 cd <your-project>
-gbc init                          # .claude/settings.json에 hook + /gate skill 머지 (동의·백업)
+gbc init
 ```
 
-`gbc init`은 **프로젝트 로컬 `.claude/settings.json`만** 머지한다(append·멱등·백업). 전역 `~/.claude`는 건드리지 않는다.
-
 소스를 수정하면 `npm run build`만 다시 하면 된다 — wrapper/link는 같은 `dist/cli.js`를 가리키므로 재연결 불필요.
 
+</details>
+
+`gbc init`은 **프로젝트 로컬 `.claude/settings.json`만** 머지한다(append·멱등·백업). 전역 `~/.claude`는 건드리지 않는다. `~/.gbc/api-key`가 있으면 hook 명령에 키 주입까지 자동화한다(아래 [빠른 게이트 활성화](#빠른-게이트-활성화-api-키--선택)).
+
 ## 빠른 게이트 활성화 (API 키 — 선택)
 
 `gbc init`은 키 주입 **없는** hook을 설치한다 → 기본은 `claude -p` 폴백(~13–20s). **haiku 직접 API(~1–3s)**를 쓰려면 키를 **hook 명령에만** 주입한다.
@@ -111,16 +123,29 @@ phase-protocol/계획 → /plan(SubTask) → 【게이트: 구현 직전 케이
 | `gbc spec show` | 등록된 케이스 목록 |
 | `gbc spec clear` | 명세 비우기(작업단위 종료) |
 | `gbc gate reset` | 작업단위 게이트 리셋 |
+| `gbc metrics [--json]` | 계측 리포트(M1~M3) |
 
 우회: `GBC_NO_GATE=1` (계측됨 — 우회 자체가 게이트 가치 측정 데이터).
 
+## 계측 (M1~M3)
+
+게이트는 모든 결정을 `.gbc/events.jsonl`(append-only, 메타데이터만 — 코드 본문 미기록)에 기록한다. `gbc metrics`로 집계를 본다. 끄려면 `GBC_NO_METRICS=1`.
+
+| 지표 | 관측 | B-모드 신뢰도 |
+|---|---|---|
+| **M2** 게이트 적중 vs 도중발견 | 차단이 잡은 누락 케이스 수 vs `defer add`로 도중 등록된 수 | **강** (defer-registry와 1:1) |
+| **M3** 재호출/iteration | 작업단위당 편집 반복 횟수 | proxy |
+| **M1** post-gate 재작업 | 통과 후 churn(spec 변경·gate reset·defer) | **약** (churn proxy) |
+
+> ⚠️ **진짜 M1**(통과 후 시나리오 위반율)은 게이트가 엔진 출력을 채점하는 **사후 대조**가 필요하다 — 이는 후속 A(standalone) 모드 영역이다. B-커널(hook)은 churn 약신호만 관측한다. `events.jsonl` 원시 로그는 그때 그대로 재사용된다.
+
 ## 정직한 한계
 
 - 사후 대조가 아닌 **구현 전 게이트**다 — "도중 탈선"은 못 잡는다(설계상 후속 C 영역).
 - 판정은 LLM이라 100% 아니다. **사람이 변이 전 케이스를 리뷰/편집하는 pause**가 진짜 가치다.
-- MVP scope = **B-커널**(CC-native hook + defer-registry + /gate). standalone TUI·추출 모드·계측 대시보드는 후속.
+- MVP scope = **B-커널**(CC-native hook + defer-registry + /gate). standalone TUI·추출 모드는 후속 A(public). 계측은 B-모드 관측 프록시(M1~M3)까지 구현됨(위 [계측](#계측-m1m3)).
 - **검증 상태**: 게이트 판정 품질은 **양 트랜스포트 모두 회귀 8/8(FP0 FN0)**. 직접 API(haiku) 경로 실측 **평균 1.7s**(1.1–2.5s), claude -p 폴백 ~18s. 직접 API용 게이트 프롬프트는 최소화하면서 정확도를 유지하도록 "동작 편집 vs 비-동작 편집" 2단계 분류로 튜닝했다(`ANTHROPIC_API_KEY=… node dist/eval/regression.js`로 재현).
-- **fail-open**: 판정 호출이 실패하면(키 오류·네트워크 등) 게이트는 조용히 통과시킨다(개발 차단 방지). 게이트가 무력화돼도 경고가 약하다는 트레이드오프 — 후속 관찰 항목.
+- **fail-open**: 판정 호출이 실패하면(키 오류·네트워크 등) 게이트는 안전하게 통과시킨다(개발 차단 방지). 단 fail-open 통과는 작업단위 캐시에서 제외되고(다음 편집 재판정), `systemMessage` 경고 + `.gbc/failopen.log` 계측으로 드러난다(조용한 무력화 방지).
 
 ## 라이선스
 

package/dist/cli.js

@@ -10,6 +10,7 @@ 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 { logEvent, parseEvents, computeMetrics } from "./metrics.js";
 const CLI_PATH = fileURLToPath(import.meta.url);
 const PKG_ROOT = join(dirname(CLI_PATH), ".."); // dist/cli.js → 패키지 루트
 /** ~/.gbc/api-key 존재 여부 — 있으면 hook에 키 주입(빠른 haiku 경로). */
@@ -19,6 +20,26 @@ function hasApiKey() {
 function stopCommand() {
     return `node "${CLI_PATH}" hook stop`;
 }
+function nowIso() {
+    try {
+        return new Date().toISOString();
+    }
+    catch {
+        return "";
+    }
+}
+/**
+ * 현재 작업단위 명세 해시 (CLI 이벤트의 specHash 상관 키).
+ * 빈 spec은 ""(센티넬) — M1 churn 교차세션 합산 방지(computeMetrics가 제외).
+ */
+function curHash(cwd) {
+    const text = loadPlanSpec(cwd).text;
+    return text.trim() === "" ? "" : computeSpecHash(text);
+}
+/** CLI 변이 이벤트를 events.jsonl에 기록(메트릭 상관용). specHash는 변이 전 값을 넘긴다. */
+function logCli(cwd, kind, specHash) {
+    logEvent(cwd, { at: nowIso(), session: "", specHash, kind });
+}
 function nowStamp() {
     try {
         return new Date().toISOString().replace(/[:.]/g, "-");
@@ -133,6 +154,7 @@ function cmdDefer(args) {
             process.exit(1);
         }
         addDefer(cwd, item);
+        logCli(cwd, "defer-add", curHash(cwd));
         console.log(`🐢 미룸 등록: ${item}`);
     }
     else if (sub === "list") {
@@ -146,6 +168,8 @@ function cmdDefer(args) {
     else if (sub === "resolve") {
         const ref = args.slice(1).join(" ").trim();
         const r = resolveDefer(cwd, ref);
+        if (r)
+            logCli(cwd, "defer-resolve", curHash(cwd));
         console.log(r ? `🐢 해결 표시: ${r.item}` : `매칭되는 미룬 항목 없음: ${ref}`);
     }
     else {
@@ -163,7 +187,9 @@ function cmdSpec(args) {
             console.error('사용: gbc spec add "<케이스/시나리오>"');
             process.exit(1);
         }
+        const beforeHash = curHash(cwd); // 변이 전 해시 = 수정 대상 작업단위와 상관
         addSpecCase(cwd, item);
+        logCli(cwd, "spec-add", beforeHash);
         console.log(`🐢 명세 등록: ${item}`);
     }
     else if (sub === "show") {
@@ -175,7 +201,9 @@ function cmdSpec(args) {
         cases.forEach((c, i) => console.log(`${i + 1}. ${c}`));
     }
     else if (sub === "clear") {
+        const beforeHash = curHash(cwd);
         clearSpec(cwd);
+        logCli(cwd, "spec-clear", beforeHash);
         console.log("🐢 명세 비움 — 다음 작업단위로 깨끗이 넘어갑니다.");
     }
     else {
@@ -186,7 +214,9 @@ function cmdSpec(args) {
 // ---------- gbc gate ----------
 function cmdGate(args) {
     if (args[0] === "reset") {
-        resetGate(process.cwd());
+        const cwd = process.cwd();
+        logCli(cwd, "gate-reset", curHash(cwd));
+        resetGate(cwd);
         console.log("🐢 작업단위 게이트 리셋 — 다음 편집에서 다시 발동합니다.");
     }
     else {
@@ -194,6 +224,30 @@ function cmdGate(args) {
         process.exit(1);
     }
 }
+// ---------- gbc metrics ----------
+function cmdMetrics(args) {
+    const cwd = process.cwd();
+    const eventsPath = join(cwd, ".gbc", "events.jsonl");
+    const raw = existsSync(eventsPath) ? readFileSync(eventsPath, "utf8") : "";
+    const m = computeMetrics(parseEvents(raw));
+    if (args.includes("--json")) {
+        console.log(JSON.stringify(m, null, 2));
+        return;
+    }
+    console.log(`🐢 거북이 게이트 계측 — ${cwd}
+  이벤트 총 ${m.totalEvents}건  (.gbc/events.jsonl)
+
+  [M3] 재호출/iteration — 작업단위당 edit 반복
+    작업단위 ${m.m3.workUnits} · 총 edit ${m.m3.totalEdits} · 평균 ${m.m3.avgEditsPerUnit}/단위 · 최대 ${m.m3.maxEditsPerUnit} · 반복(>1)단위 ${m.m3.multiEditUnits}
+
+  [M2] 게이트 적중 vs 도중발견
+    게이트 적중(차단 누락케이스) ${m.m2.gateCaught} · 차단 ${m.m2.blocks}회
+    도중발견(defer 등록) ${m.m2.deferred} · 도중발견 비율 ${(m.m2.midDiscoveryRatio * 100).toFixed(1)}%
+
+  [M1] post-gate 재작업
+    게이트 리셋 ${m.m1.resets} · 통과후 churn ${m.m1.churnAfterPass}
+    ⚠️ ${m.m1.note}`);
+}
 function usage() {
     console.log(`🐢 gbc — 거북이코드 구현-전 게이트
 
@@ -207,6 +261,7 @@ function usage() {
   gbc spec show                       등록된 케이스 목록
   gbc spec clear                      명세 비우기(작업단위 종료)
   gbc gate reset                      작업단위 게이트 리셋
+  gbc metrics [--json]                계측 리포트(M1~M3, B-모드 관측 프록시)
   gbc hook pre-tool-use               (내부) PreToolUse hook
   gbc hook stop                       (내부) Stop hook
 `);
@@ -232,6 +287,8 @@ async function main() {
             return cmdSpec(rest);
         case "gate":
             return cmdGate(rest);
+        case "metrics":
+            return cmdMetrics(rest);
         case undefined:
         case "help":
         case "--help":

package/dist/hook.js

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

package/dist/metrics.js

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

package/package.json

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