geobuke-code 0.4.0 → 0.4.1

package/README.md

@@ -25,6 +25,7 @@
 - **크로스-repo 가시성** — 등록한 다른 repo의 미해결 defer 요약 + 게이트 hook 건강성 롤업("회사 repo에서 게이트가 조용히 안 먹는다"를 한 명령으로 진단) ([크로스-repo](#크로스-repo-가시성))
 - **판정 드리프트 회귀락** — 실제 판정을 캡처해두고 모델/프롬프트/SDK 변화 후 재판정해 pass↔block 뒤집힘을 잡는 로컬 pre-flight ([`gbc gate snapshot`](#판정-드리프트-회귀락-gbc-gate-snapshot))
 - **관측 계측(M1~M3)** — 게이트 적중·재호출·통과 후 churn. 여러 repo는 `gbc metrics --all`로 병합 ([계측](#계측-m1m3))
+- **운영 현황 관측(`/gbc-monitor` 스킬)** — 위 게이트 상태·계측·repo 건강성·드리프트락을 묶어 조회·해석하는 읽기전용 표면(상태 변경은 `/gate`) ([`/gbc-monitor`](#운영-현황-관측-gbc-monitor))
 
 ## 설치
 
@@ -34,7 +35,7 @@ npm install -g geobuke-code
 
 # 2) 대상 프로젝트에 게이트 설치
 cd <your-project>
-gbc init                          # .claude/settings.json에 hook(PreToolUse+Stop+SessionStart) + /gate skill 머지 (동의·백업)
+gbc init                          # .claude/settings.json에 hook(PreToolUse+Stop+SessionStart) + /gate · /gbc-mute · /gbc-monitor skill 머지 (동의·백업)
 ```
 
 <details>
@@ -154,7 +155,7 @@ gbc gate review --spec 1 3 --defer 2         # 1,3은 승인→spec / 2는 미
 
 | 명령 | 설명 |
 |---|---|
-| `gbc init` | hook + `/gate` · `/gbc-mute` 스킬 설치 + 크로스-repo 레지스트리 자동등록(opt-out: `--no-register`) |
+| `gbc init` | hook + `/gate` · `/gbc-mute` · `/gbc-monitor` 스킬 설치 + 크로스-repo 레지스트리 자동등록(opt-out: `--no-register`) |
 | `gbc update` | 전역 최신 설치(`npm i -g …@latest`) + 현재 프로젝트 재init 한방. `--dry-run`으로 실행 명령만 미리보기 |
 | `gbc status` | 게이트 상태 + 로드된 명세 + Stop 리마인드 음소거 여부 |
 | `gbc defer add "<케이스>"` | 케이스를 명시적으로 미루기 (→ open) |
@@ -175,6 +176,7 @@ gbc gate review --spec 1 3 --defer 2         # 1,3은 승인→spec / 2는 미
 | `gbc repos add [경로]` | 크로스-repo 레지스트리에 추가(생략 시 현재 폴더) |
 | `gbc repos list` | 등록된 repo + 각 repo의 미해결 defer 수 + **게이트 건강성**(hook 부재/구식 코호트) |
 | `gbc repos remove [경로]` | 레지스트리에서 제거 |
+| `/gbc-monitor` 스킬 | 위 관측 명령(status·metrics --all·repos list·snapshot status)을 묶어 조회·해석하는 **읽기전용** 표면. 상태 변경은 `/gate` |
 
 우회: `GBC_NO_GATE=1` (계측됨 — 우회 자체가 게이트 가치 측정 데이터).
 
@@ -259,6 +261,26 @@ gbc gate snapshot replay --samples 5  # 케이스당 5회 모달 판정(잔여
 - **캡처 시점**: judge가 *실제로 평가한* cache-miss 편집만 기록된다(cached-skip·fail-open 제외). 특정 편집을 캡처하려면 `gbc gate reset` 후 그 편집을 수행한다.
 - **⚠️ 로컬 전용(privacy)**: `golden.json`은 정규화된 **편집 본문**을 담는다 — `events.jsonl`이 불변식으로 절대 저장하지 않는 내용이다. `.gbc/`는 gitignore이므로 이 골든셋은 **로컬 드리프트 점검**이지 커밋되는 CI 스위트가 아니다. 공유 CI로 쓰려면 편집 본문을 커밋하는 privacy 트레이드오프를 명시적으로 감수해야 한다.
 
+## 운영 현황 관측 (`/gbc-monitor`)
+
+위 운영층 명령들(`gbc status`·`gbc metrics --all`·`gbc repos list`·`gbc gate snapshot status`)은 강력하지만, 세션 안에서 **발견가능성**이 없었다 — 명령·플래그를 외워 직접 치거나 매번 요청해야 했다. `/gbc-monitor` 스킬은 이들을 **묶어 조회하고 해석**하는 읽기전용 표면이다.
+
+```
+/gbc-monitor                  # 게이트 현황 종합(4개 묶음 + 해석)
+게이트 현황 보여줘 / 계측 어때 / repo 건강성  # 자연어로도 트리거(특정 항목만도 가능)
+```
+
+핵심은 **단순 별칭이 아니라 해석**이다 — 숫자가 정상/주의/행동필요 중 무엇인지 판정해준다:
+
+- `repos ✗부재` → 게이트가 조용히 죽은 상태 → 그 repo `gbc init` 재실행 안내(단 `/tmp/*` 잔재는 `gbc repos remove` 청소 후보)
+- `M1 churn` → **약신호 proxy** — "통과 후 결함 수"로 과대해석 금지(진짜 M1은 A-mode 사후대조 과제)
+- `명세 비어있음 → 차단` → 버그가 아니라 게이트가 의도대로 켜진 정상 동작
+- `M2 도중발견 비율 낮음` → 누락이 늦게 새기보다 게이트가 사전 차단을 잘 한다는 긍정 신호
+
+### 경계 — 관측하고, 액션은 가리킨다
+
+`/gbc-monitor`와 `/gate`를 가르는 단 하나의 선: **"그 명령이 상태를 바꾸거나(mutate) API를 쓰는가?"** 그렇다면 `/gate`의 영역이다(미루기·리셋·`snapshot on/off/clear`·`replay`). `/gbc-monitor`는 **읽기전용 조회만** 하고, 변경이 필요하면 직접 실행하지 않고 `/gate`로 *가리킨다*. 이 분리 덕에 모니터링은 부작용 걱정 없이 언제든 안전하게 부를 수 있다. `gbc init`이 이 스킬을 `/gate`·`/gbc-mute`와 함께 설치한다.
+
 ## 정직한 한계
 
 - 사후 대조가 아닌 **구현 전 게이트**다 — "도중 탈선"은 못 잡는다(설계상 후속 C 영역).

package/dist/cli.js

@@ -78,7 +78,7 @@ async function cmdInit(args) {
     const claudeDir = join(cwd, ".claude");
     const settingsPath = join(claudeDir, "settings.json");
     // 설치 대상 스킬들(제품소스 skills/<name>/SKILL.md → .claude/skills/<name>/SKILL.md).
-    const skillNames = ["gate", "gbc-mute"];
+    const skillNames = ["gate", "gbc-mute", "gbc-monitor"];
     if (!yes) {
         console.log(`🐢 gbc init — 다음을 수행합니다 (프로젝트 로컬만, 전역 ~/.claude 미변경):
 
@@ -669,7 +669,7 @@ function usage() {
     console.log(`🐢 gbc — 거북이코드 구현-전 게이트
 
 사용:
-  gbc init [--yes] [--no-register]    프로젝트에 hook + /gate · /gbc-mute 스킬 설치
+  gbc init [--yes] [--no-register]    프로젝트에 hook + /gate · /gbc-mute · /gbc-monitor 스킬 설치
                                       (--no-register: 크로스-repo 레지스트리 자동등록 생략)
   gbc update [--dry-run]              전역 최신 설치 + 현재 프로젝트 재init (한방 갱신)
   gbc status                          게이트 상태 + 로드된 명세 확인

package/package.json

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

package/skills/gbc-monitor/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: gbc-monitor
+description: 거북이코드(gbc) 게이트의 운영 현황을 한 번에 조회·해석하는 읽기전용 관측 표면. 게이트 상태(status)·교차repo 계측(metrics)·repo 건강성(repos)·판정 드리프트락(snapshot) 현황을 묶어 보여주고, 숫자가 무엇을 뜻하는지 해석한다. '/gbc-monitor', '게이트 현황', '게이트 상태 보여줘', '계측 어때', 'gbc 계측', 'repo 건강성', '드리프트 상태', 'gbc 모니터링', '지금 게이트 어디까지 됐어' 등 언급 시 호출한다. 상태를 바꾸는 작업(미루기·리셋·캡처 토글·replay)은 이 스킬이 아니라 `/gate`다 — 여긴 보기만 한다.
+---
+
+# /gbc-monitor — 게이트 운영 현황 관측
+
+거북이코드(`gbc`)는 게이트(차단)·defer(미루기)·계측·크로스repo 레지스트리를 운영하지만, 그 **현황을 한눈에 보는 표면**이 세션 안에 없었다. 명령(`gbc metrics --all` 등)을 외워 직접 치거나 매번 요청해야 했다. 이 스킬은 그 관측 정보를 **묶어서 조회하고 해석**하는 읽기전용 표면이다.
+
+## 핵심 원칙 — 관측하고, 액션은 가리킨다
+
+이 스킬과 `/gate`를 가르는 단 하나의 선은 **"그 명령이 상태를 바꾸거나(mutate) API를 쓰는가?"** 이다.
+
+- **읽기전용 조회만 한다.** 상태를 바꾸지 않고, judge(API)를 호출하지 않는다.
+- **액션이 필요하면 *가리킨다*, 직접 하지 않는다.** 예: 드리프트락이 꺼져 있으면 "켜라"가 아니라 "활성 검사는 `gbc gate snapshot replay`(judge 재실행·API 과금) — 필요 시 `/gate`"로 안내한다.
+
+이 경계 덕분에 `/gbc-monitor`는 부작용 없이 언제든 안전하게 부를 수 있고, 미루기·리셋·캡처 같은 변경은 전부 `/gate`로 일원화된다. 새 조회/변경 명령이 생겨도 이 규칙으로 어디 속할지 자동 결정된다.
+
+## 무엇을 보여주나 (전부 읽기전용)
+
+사용자 의도에 따라 **전체** 또는 **필요한 항목만** 조회한다. "현황/모니터링/상태"처럼 포괄적이면 4개를 다 모아 종합하고, "계측만"·"repo 건강성만"처럼 특정되면 해당 명령만 실행한다.
+
+| 보고 싶은 것 | 명령 |
+|---|---|
+| 게이트 상태·로드된 명세·defer 요약·음소거 여부 | `gbc status` |
+| 계측(M1~M3) — 등록된 모든 repo 병합 | `gbc metrics --all` |
+| 크로스repo 목록 + 게이트 건강성 + 미해결 defer 수 | `gbc repos list` |
+| 판정 드리프트락(골든셋) 캡처 상태·케이스 목록 | `gbc gate snapshot status` (필요 시 `list`) |
+
+> 단일 repo 계측만 원하면 `gbc metrics`(--all 없이). JSON이 필요하면 `gbc metrics --all --json`.
+
+## 실행 흐름 (에이전트)
+
+1. **사용자 의도에서 범위를 판정**한다 — 포괄적이면 4개 전부, 특정되면 해당 명령만.
+2. 프로젝트 루트에서 명령을 실행하고 **출력을 그대로 수집**한다.
+3. 원문을 보여준 뒤, 아래 **해석 가이드**로 숫자가 뜻하는 바를 덧붙인다. 단순 나열이 아니라 "이 신호가 정상인지/주의인지/행동이 필요한지"를 한 줄로 판정해준다.
+4. 행동이 필요한 신호면 **해당 액션을 가리킨다**(`/gate`·`gbc repos remove`·`gbc init` 등) — 단, 이 스킬이 직접 실행하지 않는다.
+
+## 해석 가이드 (이 스킬의 핵심)
+
+조회는 명령이 해주지만, **숫자→의미 번역이 이 스킬의 가치**다. 자주 나오는 신호의 뜻:
+
+- **`repos [✗부재]`** → 그 repo는 `.gbc`가 있는데 게이트 hook이 빠져 있다 = **게이트가 조용히 죽은 상태**(코드 변경이 차단 없이 통과). 행동: 그 repo에서 `gbc init` 재실행을 가리킨다. (단 `/tmp/gbc-test-*` 같은 임시 경로는 테스트 잔재이므로 청소 후보 → `gbc repos remove`.)
+- **`snapshot ... 캡처 OFF`** → 판정 드리프트락 미가동 = 같은 코드의 게이트 판정이 바뀌어도 추적 안 됨. 정상일 수 있다(로컬 회귀 점검을 안 쓰는 중). 활성 검사가 필요하면 `gbc gate snapshot replay`(API 과금)를 가리킨다.
+- **`M1` 통과후 churn** → **약신호 proxy일 뿐**이다. "churn N건"을 곧바로 "게이트 통과 후 결함 N건"으로 **과대해석하지 않는다**. 진짜 M1(post-gate 시나리오 위반율)은 A-mode 사후대조가 있어야 측정된다 — 지금 값은 "편집이 게이트 통과 후에도 계속됐다"는 거친 대리지표.
+- **`명세 비어있음 → 모든 코드변경 차단`** → **버그가 아니라 정상 동작**이다. 빈 spec은 "아직 계획 명세가 없으니 코드 변경 전 도출·검증을 강제" = 게이트가 의도대로 켜진 상태. 명세를 채우면(`gbc spec add` 또는 도출 루프) 풀린다.
+- **`M2` 도중발견 비율 낮음** → 누락이 defer로 늦게 잡히기보다 게이트가 **사전에 막고 있다**는 긍정 신호로 읽는다(높으면 반대 — 게이트를 빠져나간 뒤 수습이 잦다는 뜻).
+- **`defer 미해결 > 0` (특히 진행중)** → 착수했지만 미종결인 항목 = 레이더에서 사라지기 쉬운 잔여. 종결/이월 판단이 필요하면 `/gate`(resolve·reopen)를 가리킨다.
+
+## 읽기전용 경계 (중요)
+
+이 스킬은 **절대** 다음을 하지 않는다 — 전부 `/gate`의 영역이다:
+- `gbc defer add/start/resolve/reopen`, `gbc spec add/clear`, `gbc gate reset` (상태 변경)
+- `gbc gate snapshot on/off/clear` (골든셋 mutate), `gbc gate snapshot replay` (judge 재실행·API 과금)
+
+이들이 필요해 보이면 **실행하지 말고** 사용자에게 `/gate`로 안내한다. "보는 곳"과 "바꾸는 곳"을 분리해야, 모니터링을 부작용 걱정 없이 언제든 부를 수 있다.
+
+## Known Pitfalls
+
+- **얇은 별칭이 되지 않게 — 해석을 붙인다.** `gbc metrics`를 그냥 대신 실행만 하는 거라면 사용자가 직접 치는 것과 다를 바 없다. 가치는 4개 묶음 + "이게 정상/주의/행동필요 중 뭔지"의 판정이다.
+- **`--all`을 잊지 않는다.** 계측은 기본이 현재 repo만이다. "전체 현황" 맥락에서는 `gbc metrics --all`로 교차repo를 병합해야 그림이 맞는다.
+- **`✗부재`를 stale과 혼동하지 않는다.** `repos list`는 hook *존재 여부*만 본다(명령 freshness=설치경로 의존이라 타 repo에선 판정 불가). "명령이 구버전인지"는 그 repo에서 `gbc status`로 확인하라고 안내한다.