geobuke-code 0.2.8 → 0.3.0

package/README.md

@@ -100,11 +100,11 @@ phase-protocol/계획 → /plan(SubTask) → 【게이트: 구현 직전 케이
 | **코드 변경 직전** | PreToolUse (`Edit\|Write\|MultiEdit`) | 명세 ↔ 변경 ↔ defer 대조 → 통과(침묵)/차단(시나리오 도출 지시)/fail-open |
 | **작업단위당 1회** | (PreToolUse 캐시) | 같은 명세 해시 내에선 첫 편집만 판정, 이후 통과 → 매 편집 지연 회피 |
 | **응답 종료** | Stop | 계측 flush(`events.jsonl`) + 미해결 defer가 있으면 리마인드(매 대화 종료마다). 거슬리면 `gbc defer mute`(또는 `/gbc-mute` 스킬)로 끈다 — SessionStart 진입 알림은 유지 |
-| **업데이트 필요 시** | (PreToolUse·SessionStart) | hook 구버전(②) 또는 신버전 출시(①)면 갱신 안내. PreToolUse는 세션당 1회(`systemMessage` 비차단), SessionStart는 진입 시 표시. `gbc status`는 캐시만 갱신하고 안내는 **표시하지 않는다**(명시 진단 명령). 게이트 통과/차단 동작은 불변 |
+| **업데이트 필요 시** | (PreToolUse·SessionStart) | hook 구버전(②) 또는 신버전 출시(①)면 갱신 안내. PreToolUse는 세션당 1회(`systemMessage` 비차단) — **통과된 작업단위(cached-skip) 편집에도 표시**(0.3.0: 평상 작업 대부분이 cached-skip이라, 여기서 빠지면 배너가 거의 안 떴음). SessionStart는 진입 시 표시(모델 컨텍스트). `gbc status`는 캐시만 갱신하고 안내는 **표시하지 않는다**(명시 진단 명령). 게이트 통과/차단 동작은 불변 |
 
 > 세션 진입 알림만 끄려면 `GBC_NO_SESSION_HINT=1`. 매 대화 종료(Stop) defer 리마인드만 끄려면 `gbc defer mute`(영속, 해제 `unmute` · 스킬 `/gbc-mute`) — 진입 알림은 남는다. 업데이트 안내만 끄려면 `GBC_NO_UPDATE_NOTICE=1`.
 > 프로젝트 hook이 구식이거나(SessionStart 누락·옛 명령) 새 버전이 나오면 gbc가 감지해 **`gbc update`**(전역 최신 + 현재 프로젝트 재init 한방) 또는 수동 `npm i -g geobuke-code@latest → gbc init --yes`를 안내한다. 단 안내는 **이미 hook이 등록된 프로젝트**(=한 번이라도 `gbc init`을 한 코호트)에만 도달한다 — 전혀 init하지 않은 프로젝트엔 실행할 hook이 없어 구조적으로 알릴 수 없다(gbc는 전역 hook을 깔지 않는다).
-> **업데이트 안내(①)는 네트워크를 게이트 핫패스에 들이지 않는다**: `~/.gbc/version-check.json` 캐시만 비교하고, 갱신 fetch는 SessionStart·`gbc status`에서만 짧은 타임아웃(1.5s)으로. SessionStart는 캐시가 stale이면 **표시 전에 갱신**해 신버전이 그 세션에 바로 뜬다(1세션 지연 없음). 조회 실패는 조용히 무시(fail-silent)되어 게이트 결정에 영향이 없다. 캐시 TTL 24h.
+> **업데이트 안내(①)는 네트워크를 게이트 핫패스에 들이지 않는다**: `~/.gbc/version-check.json` 캐시만 비교하고, 갱신 fetch는 안전한 비-핫패스에서만 짧은 타임아웃(1.5s)으로. ⓐSessionStart는 캐시가 stale이면 **표시 전에 갱신**해 신버전이 그 세션에 바로 뜬다(1세션 지연 없음). ⓑ**PreToolUse는 judge를 도는 편집(cache-miss)에서 캐시가 stale이면 refresh를 judge와 *병렬*로 건다**(0.3.0) — judge가 ≥1.5s라 지연 0이고, 사용자가 `gbc status`를 직접 치지 않아도 캐시가 최신이 된다. **cached-skip 핫패스에는 네트워크를 절대 넣지 않는다.** 조회 실패는 조용히 무시(fail-silent)되어 게이트 결정에 영향이 없다. 캐시 TTL 24h.
 
 ### 시나리오 도출 루프 (수기 입력 불필요)
 
@@ -148,9 +148,40 @@ phase-protocol/계획 → /plan(SubTask) → 【게이트: 구현 직전 케이
 | `gbc spec clear` | 명세 비우기(작업단위 종료) |
 | `gbc gate reset` | 작업단위 게이트 리셋 |
 | `gbc metrics [--json]` | 계측 리포트(M1~M3) |
+| `gbc repos add [경로]` | 크로스-repo 레지스트리에 추가(생략 시 현재 폴더) |
+| `gbc repos list` | 등록된 repo + 각 repo의 미해결 defer 수 |
+| `gbc repos remove [경로]` | 레지스트리에서 제거 |
 
 우회: `GBC_NO_GATE=1` (계측됨 — 우회 자체가 게이트 가치 측정 데이터).
 
+## 크로스-repo 가시성
+
+여러 repo를 오가며 작업할 때, **다른 repo에 걸린 미완 작업**을 그 repo를 열지 않고도 인지하기 위한 기능이다. 세션 진입(SessionStart) 시 현재 repo의 미해결 defer 상세에 더해, **등록된 다른 repo들의 미해결 defer 요약**을 한 줄로 환기한다.
+
+```bash
+# 감시할 repo를 글로벌 레지스트리(~/.gbc/repos.json)에 등록 (각 repo에서 1회, 또는 경로 지정)
+gbc repos add                 # 현재 폴더
+gbc repos add /path/to/other-repo
+gbc repos list                # 등록 현황 + 각 repo 미해결 defer 수
+```
+
+이후 등록된 repo에서 세션을 열면 진입 시 이렇게 뜬다:
+
+```
+🐢 거북이 게이트 — 미해결 defer 1건 (진행중 0 · 미착수 1, 이전 작업 잔여):
+1. [미착수] dist 재빌드 자동화                     ← 현재 repo: 번호 매긴 상세
+필요하면 사용자에게 이어서 처리할지 확인하세요. 규약 — …
+
+🌐 타 repo 미해결: dev-note 진행중1·미착수1 · fa-support 미착수1   ← 등록된 타 repo: 카운트만
+```
+
+- **카운트만** 표시한다 — 번호 매긴 상세 리스트는 **현재 repo에만**. 번호는 `gbc defer <N>` 인덱스 ref와 현재 cwd 기준으로 묶이므로, 타 repo에 번호를 주면 "어느 repo의 N"인지 ref가 깨진다. 타 repo 항목을 다루려면 그 repo로 들어가서 번호로 조작한다.
+- **SessionStart에서만** 환기한다(매 대화 종료 Stop 리마인드엔 미첨부 — 노이즈 방지). 현재 repo와 미해결 0건 repo는 요약에서 제외(전부 깨끗하면 `🌐` 줄 자체가 없다).
+- gbc가 설치되지 않은(`.gbc/` 없는) repo는 등록돼 있어도 조용히 건너뛴다(fail-silent) — 레지스트리는 넉넉히 등록해도 안전하다.
+- 끄려면 `GBC_NO_CROSS_REPO=1`(이 줄만) 또는 `GBC_NO_SESSION_HINT=1`(세션 진입 힌트 전체).
+
+> CLI에서 repo별 alias(`alias cc-x='cd <dir> && claude'`)를 쓴다면, alias에 `gbc repos add . 2>/dev/null;`를 끼워 **여는 repo를 자동 등록**할 수 있다(등록은 멱등).
+
 ## 계측 (M1~M3)
 
 게이트는 모든 결정을 `.gbc/events.jsonl`(append-only, 메타데이터만 — 코드 본문 미기록)에 기록한다. `gbc metrics`로 집계를 본다. 끄려면 `GBC_NO_METRICS=1`.

package/dist/cli.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 // gbc — 거북이코드 CLI. zero-dep 인자 파싱(핫패스 보호).
 import { fileURLToPath } from "node:url";
-import { dirname, join } from "node:path";
+import { dirname, join, resolve } from "node:path";
 import { homedir } from "node:os";
 import { spawnSync } from "node:child_process";
 import { mkdirSync, existsSync, readFileSync, writeFileSync, copyFileSync, } from "node:fs";
@@ -9,6 +9,7 @@ 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, startDefer, reopenDefer } from "./defer.js";
+import { loadRepos, addRepo, removeRepo } from "./repos.js";
 import { isStopHintMuted, setStopHintMuted } from "./config.js";
 import { selectedTransport } from "./judge.js";
 import { buildPreCommand, normalizeHooks, ensureSessionStartHook, DEV_PLACEHOLDER } from "./install.js";
@@ -372,6 +373,45 @@ function cmdUpdate(args) {
     }
     console.log("✅ gbc update 완료.");
 }
+/**
+ * 크로스-repo 레지스트리 관리(0.2.9). 등록된 타 repo의 미해결 defer가 SessionStart에 환기된다.
+ * 글로벌 ~/.gbc/repos.json. 경로 생략 시 현재 폴더(cwd).
+ */
+function cmdRepos(args) {
+    const [sub, ...rest] = args;
+    if (sub === "add") {
+        const abs = resolve(rest[0] ?? process.cwd());
+        const repos = addRepo(abs);
+        const gated = existsSync(join(abs, ".gbc"));
+        console.log(`📁 등록: ${abs}${gated ? "" : "  ⚠️ (.gbc 없음 — gbc init 전이면 표면화될 defer 없음)"}`);
+        console.log(`   현재 ${repos.length}개 등록됨.`);
+    }
+    else if (sub === "remove" || sub === "rm") {
+        const abs = resolve(rest[0] ?? process.cwd());
+        const before = loadRepos().length;
+        const repos = removeRepo(abs);
+        console.log(repos.length < before ? `🗑️  해제: ${abs}` : `(미등록 경로: ${abs})`);
+        console.log(`   현재 ${repos.length}개 등록됨.`);
+    }
+    else if (sub === "list" || sub === undefined) {
+        const repos = loadRepos();
+        if (repos.length === 0) {
+            console.log("등록된 repo 없음. 'gbc repos add [경로]'로 추가(경로 생략 시 현재 폴더).");
+            return;
+        }
+        console.log(`📁 등록된 repo ${repos.length}개:`);
+        for (const r of repos) {
+            const exists = existsSync(r);
+            const gated = exists && existsSync(join(r, ".gbc"));
+            const unresolved = gated ? loadDefers(r).filter((d) => d.status !== "resolved").length : 0;
+            const mark = !exists ? "✗부재" : !gated ? "·gbc없음" : unresolved ? `●미해결${unresolved}` : "○깨끗";
+            console.log(`  [${mark}] ${r}`);
+        }
+    }
+    else {
+        console.log("사용법: gbc repos [add|remove|list] [경로]");
+    }
+}
 function usage() {
     console.log(`🐢 gbc — 거북이코드 구현-전 게이트
 
@@ -391,6 +431,9 @@ function usage() {
   gbc spec clear                      명세 비우기(작업단위 종료)
   gbc gate reset                      작업단위 게이트 리셋
   gbc metrics [--json]                계측 리포트(M1~M3, B-모드 관측 프록시)
+  gbc repos add [경로]                크로스-repo 레지스트리에 추가(생략 시 현재 폴더)
+  gbc repos list                      등록된 repo + 미해결 defer 수
+  gbc repos remove [경로]             레지스트리에서 제거
   gbc hook pre-tool-use               (내부) PreToolUse hook
   gbc hook stop                       (내부) Stop hook
   gbc hook session-start              (내부) SessionStart hook (미해결 defer 알림)
@@ -423,6 +466,8 @@ async function main() {
             return cmdGate(rest);
         case "metrics":
             return cmdMetrics(rest);
+        case "repos":
+            return cmdRepos(rest);
         case undefined:
         case "help":
         case "--help":

package/dist/hook.js

@@ -6,10 +6,11 @@ import { loadPlanSpec, computeSpecHash } from "./spec.js";
 import { isGated, markGated } from "./state.js";
 import { activeDeferItems, loadDefers } from "./defer.js";
 import { isStopHintMuted } from "./config.js";
+import { loadRepos } from "./repos.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 { isCacheStale, readVersionCache, refreshVersionCache, shouldRefreshCache, } from "./version.js";
+import { appendFileSync, existsSync, lstatSync } from "node:fs";
+import { join, resolve } from "node:path";
 import { gbcDir } from "./store.js";
 import { logEvent } from "./metrics.js";
 /**
@@ -141,13 +142,27 @@ export async function runPreToolUse(ctx) {
             tool: toolName,
             decision: "cached",
         });
+        // 업데이트 안내(있으면)를 cached-skip에서도 노출 — 평상 작업은 대부분 통과된 작업단위라
+        // 이 경로가 가장 흔하다. 여기서 빠지면 보이는 배너(PreToolUse systemMessage)가 거의 안 떴음
+        // (0.2.x 가시성 갭). maybeUpdateNotice는 세션당 1회 dedup이라 노이즈 없음(매 세션 첫 편집 1회).
+        // permissionDecision 없음 → cached-pass 통과 동작 불변. 네트워크 없음(캐시만 읽음).
+        const cachedNotice = maybeUpdateNotice(cwd, session, ctx);
+        if (cachedNotice)
+            emit({ systemMessage: cachedNotice });
         process.exit(0);
     }
     // judge는 여기서만 동적 import (SDK lazy)
     const { judge } = await import("./judge.js");
     const editText = normalizeEdit(toolName, input.tool_input ?? {});
     const defers = activeDeferItems(cwd);
+    // ①신버전 캐시 자동 refresh(0.3.0) — 사용자가 'gbc status'를 안 쳐도 캐시가 최신이 되게.
+    // judge(네트워크·≥1.5s)와 *병렬*로만 건다 → 핫패스 지연 0. cache-miss(여기 = judge 도는
+    // 비-핫패스)에서만 stale일 때. cached-skip 핫패스엔 절대 네트워크 안 넣는다(0.2.7 원칙 보존).
+    // refreshVersionCache는 내부 fail-silent(reject 불가)라 judge 경로를 깨지 않는다.
+    const refreshP = shouldRefreshCache(Boolean(ctx?.cliPath)) ? refreshVersionCache() : null;
     const verdict = await judge(specText, editText, defers);
+    if (refreshP)
+        await refreshP; // judge 동안 이미 완료 — 이 편집의 notice가 갱신된 캐시를 읽도록
     if (verdict.verdict === "pass") {
         // fail-open(판정 실패) 먼저 분기 — 빈-spec 정상 pass가 fail-open으로 오분류되지 않게.
         if (verdict.failOpen) {
@@ -285,6 +300,43 @@ export function buildSessionStartHint(all) {
         `${formatDeferList(all)}\n` +
         `필요하면 사용자에게 이어서 처리할지 확인하세요. ${DEFER_PROTOCOL}`);
 }
+/**
+ * 등록된 타 repo들의 미해결 defer 요약 한 줄(0.2.9 크로스-repo 가시성). 없으면 "".
+ * - 현재 cwd 제외(이미 buildSessionStartHint가 상세 표시), 미해결 0건 repo 제외.
+ * - 경로 부재/비-디렉터리/읽기실패는 repo별 조용히 skip(fail-silent). hook이 cwd 밖을 읽는
+ *   유일한 지점이라 방어적으로 가드한다(사용자가 명시 등록한 경로만 대상이라 위협은 낮음).
+ * - ★ 카운트만. 번호 매긴 상세 리스트는 현재 repo만(formatDeferList) — 번호는 'gbc defer <N>'
+ *   인덱스 ref와 cwd 기준으로 묶여, 타 repo에 번호를 주면 어느 repo의 N인지 ref가 깨진다.
+ */
+export function buildCrossRepoHint(repos, cwd) {
+    const here = resolve(cwd);
+    const segs = [];
+    for (const repo of repos) {
+        const abs = resolve(repo);
+        if (abs === here)
+            continue;
+        let unresolved;
+        try {
+            // lstatSync(statSync 아님)로 심볼릭 링크를 거부한다 — 등록된 symlink가 가리키는 cwd 밖
+            // 임의 경로(/etc 등)의 .gbc/defers.json을 읽으려 시도하는 간접 확장을 막는다(보안검토 S3).
+            // 실디렉터리만 isDirectory()=true; symlink면 false라 skip된다.
+            if (!existsSync(abs) || !lstatSync(abs).isDirectory())
+                continue;
+            unresolved = loadDefers(abs).filter((d) => d.status !== "resolved");
+        }
+        catch {
+            continue;
+        }
+        if (unresolved.length === 0)
+            continue;
+        const ip = unresolved.filter((d) => d.status === "in_progress").length;
+        const op = unresolved.length - ip;
+        const counts = [ip ? `진행중${ip}` : "", op ? `미착수${op}` : ""].filter(Boolean).join("·");
+        const name = abs.split(/[\\/]/).filter(Boolean).pop() ?? abs;
+        segs.push(`${name} ${counts}`);
+    }
+    return segs.length ? `🌐 타 repo 미해결: ${segs.join(" · ")}` : "";
+}
 /**
  * Stop hook 리마인드 문자열. 없으면 "". 입력은 전체 defer 리스트(번호=전체-인덱스, 인덱스 ref 정합).
  * SessionStart와 동일하게 in_progress를 차등 표면화한다 — "착수했지만 미종결" 항목이 레이더에서
@@ -326,6 +378,18 @@ export async function runSessionStart(ctx) {
             }
         }
     }
+    // 크로스-repo defer 가시성(0.2.9) — 등록된 타 repo 미해결 요약. SessionStart만(Stop엔 미첨부).
+    // opt-out 둘: GBC_NO_SESSION_HINT(세션힌트 전체) 또는 GBC_NO_CROSS_REPO(이 줄만).
+    if (process.env.GBC_NO_SESSION_HINT !== "1" && process.env.GBC_NO_CROSS_REPO !== "1") {
+        try {
+            const xr = buildCrossRepoHint(loadRepos(), cwd);
+            if (xr)
+                parts.push(xr);
+        }
+        catch {
+            /* 레지스트리 읽기 실패는 무시(fail-silent) */
+        }
+    }
     // ①신버전 안내 — 캐시가 stale이면 '표시 전에' 먼저 갱신(1.5s 상한, fail-silent)해 이번 세션에
     // 즉시 반영한다(표시-후-갱신의 '다음 세션 지연' 제거). SessionStart는 게이트를 막지 않으므로
     // 짧은 네트워크가 안전(advisor 승인). 갱신은 24h TTL당 1회만 발생.

package/dist/repos.js

@@ -0,0 +1,32 @@
+// 크로스-repo 레지스트리 — 등록된 repo들의 미해결 defer를 SessionStart에 환기(0.2.9).
+// 글로벌(~/.gbc/repos.json)에 저장한다 — 크로스프로젝트라 project .gbc/가 아니라 홈.
+// (~/.gbc/api-key·~/.gbc/version-check.json과 동위. gbcDir(homedir())가 ~/.gbc를 보장.)
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+import { gbcDir, readJson, writeJson } from "./store.js";
+function reposPath() {
+    return join(gbcDir(homedir()), "repos.json");
+}
+/** 등록된 repo 절대경로 목록(없으면 []). */
+export function loadRepos() {
+    return readJson(reposPath(), []);
+}
+/** repo 등록(절대경로 정규화·멱등 dedup). 반환=등록 후 전체 목록. */
+export function addRepo(path) {
+    const abs = resolve(path);
+    const repos = loadRepos();
+    if (!repos.includes(abs)) {
+        repos.push(abs);
+        writeJson(reposPath(), repos);
+    }
+    return repos;
+}
+/** repo 등록 해제(절대경로 정규화). 반환=해제 후 전체 목록. */
+export function removeRepo(path) {
+    const abs = resolve(path);
+    const repos = loadRepos();
+    const next = repos.filter((r) => r !== abs);
+    if (next.length !== repos.length)
+        writeJson(reposPath(), next);
+    return next;
+}

package/dist/version.js

@@ -69,6 +69,18 @@ export function buildVersionNotice(current, cache) {
     return (`🐢 거북이코드 신버전 ${cache.latest} 사용 가능(현재 ${current}). ` +
         `갱신: 'gbc update'(전역 최신 + 현재 프로젝트 재init) 또는 수동 'npm i -g geobuke-code@latest → gbc init --yes'`);
 }
+/**
+ * 캐시 자동 refresh를 해야 하는지(순수 술어). cliPath 없으면(직접 hook 호출) X, 안내 opt-out X,
+ * 캐시가 stale일 때만 true. PreToolUse cache-miss(judge 경로)에서 judge와 병렬 refresh를 거는
+ * 게이트 — 핫패스(cached-skip)는 절대 호출 안 함. env·파일 의존이라 테스트는 home/now 주입.
+ */
+export function shouldRefreshCache(hasCliPath, home, now = Date.now()) {
+    if (!hasCliPath)
+        return false;
+    if (process.env.GBC_NO_UPDATE_NOTICE === "1")
+        return false;
+    return isCacheStale(readVersionCache(home), now);
+}
 /**
  * npm 레지스트리에서 최신 버전을 받아 캐시에 쓴다(짧은 타임아웃, 비차단·fail-silent).
  * spawn(npm) 대신 fetch — Windows .cmd 실행 문제를 피한다. 실패·타임아웃은 조용히 무시.

package/package.json

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