geobuke-code 0.2.5 → 0.2.6

package/README.md

@@ -99,10 +99,10 @@ phase-protocol/계획 → /plan(SubTask) → 【게이트: 구현 직전 케이
 | **세션 시작·재개** | SessionStart (`startup\|resume`) | `.gbc/defers.json`의 미해결 항목을 "진행중 N · 미착수 M"로 구분 표면화(이전 작업 잔여 환기). 잔여 없으면 무출력. `compact`엔 발화 안 함(노이즈 방지) |
 | **코드 변경 직전** | PreToolUse (`Edit\|Write\|MultiEdit`) | 명세 ↔ 변경 ↔ defer 대조 → 통과(침묵)/차단(시나리오 도출 지시)/fail-open |
 | **작업단위당 1회** | (PreToolUse 캐시) | 같은 명세 해시 내에선 첫 편집만 판정, 이후 통과 → 매 편집 지연 회피 |
-| **응답 종료** | Stop | 계측 flush(`events.jsonl`) |
+| **응답 종료** | Stop | 계측 flush(`events.jsonl`) + 미해결 defer가 있으면 리마인드(매 대화 종료마다). 거슬리면 `gbc defer mute`(또는 `/gbc-mute` 스킬)로 끈다 — SessionStart 진입 알림은 유지 |
 | **업데이트 필요 시** | (PreToolUse·SessionStart) | hook 구버전(②) 또는 신버전 출시(①)면 갱신 안내. PreToolUse는 세션당 1회(`systemMessage` 비차단), SessionStart는 진입 시 표시. `gbc status`는 캐시만 갱신하고 안내는 **표시하지 않는다**(명시 진단 명령). 게이트 통과/차단 동작은 불변 |
 
-> 세션 진입 알림만 끄려면 `GBC_NO_SESSION_HINT=1`. 업데이트 안내만 끄려면 `GBC_NO_UPDATE_NOTICE=1`.
+> 세션 진입 알림만 끄려면 `GBC_NO_SESSION_HINT=1`. 매 대화 종료(Stop) defer 리마인드만 끄려면 `gbc defer mute`(영속, 해제 `unmute` · 스킬 `/gbc-mute`) — 진입 알림은 남는다. 업데이트 안내만 끄려면 `GBC_NO_UPDATE_NOTICE=1`.
 > 프로젝트 hook이 구식이거나(SessionStart 누락·옛 명령) 새 버전이 나오면 gbc가 감지해 `gbc init --yes` 재실행 또는 `npm i -g geobuke-code@latest`를 안내한다. PreToolUse 경로로도 알리므로 "설치만 하고 init 안 한" 경우에도 도달한다.
 > **업데이트 안내(①)는 네트워크를 게이트 핫패스에 들이지 않는다**: `~/.gbc/version-check.json` 캐시만 비교하고, 갱신은 SessionStart·`gbc status`에서만 짧은 타임아웃으로. 조회 실패는 조용히 무시(fail-silent)되어 게이트 결정에 영향이 없다.
 
@@ -134,13 +134,14 @@ phase-protocol/계획 → /plan(SubTask) → 【게이트: 구현 직전 케이
 
 | 명령 | 설명 |
 |---|---|
-| `gbc init` | hook + /gate skill 설치 |
-| `gbc status` | 게이트 상태 + 로드된 명세 확인 |
+| `gbc init` | hook + `/gate` · `/gbc-mute` 스킬 설치 |
+| `gbc status` | 게이트 상태 + 로드된 명세 + Stop 리마인드 음소거 여부 |
 | `gbc defer add "<케이스>"` | 케이스를 명시적으로 미루기 (→ open) |
 | `gbc defer list` | 미룬 항목 목록 (상태: 미해결/진행중/해결) |
 | `gbc defer start <번호\|텍스트\|all>` | 착수 표시 (open → 진행중) |
 | `gbc defer resolve <번호\|텍스트\|all>` | 종결 표시 (→ 해결) |
 | `gbc defer reopen <번호\|텍스트\|all>` | 백로그로 되돌리기 (→ open) |
+| `gbc defer mute` / `unmute` | 대화 종료(Stop)마다 뜨는 defer 리마인드 끄기/켜기 (영속) · 스킬: `/gbc-mute` |
 | `gbc spec add "<케이스>"` | 승인된 시나리오를 `.gbc/spec.md`에 등록 |
 | `gbc spec show` | 등록된 케이스 목록 |
 | `gbc spec clear` | 명세 비우기(작업단위 종료) |

package/dist/cli.js

@@ -8,6 +8,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 { isStopHintMuted, setStopHintMuted } from "./config.js";
 import { selectedTransport } from "./judge.js";
 import { buildPreCommand, normalizeHooks, ensureSessionStartHook } from "./install.js";
 import { isCacheStale, readVersionCache, refreshVersionCache, } from "./version.js";
@@ -65,15 +66,15 @@ async function cmdInit(args) {
     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");
+    // 설치 대상 스킬들(제품소스 skills/<name>/SKILL.md → .claude/skills/<name>/SKILL.md).
+    const skillNames = ["gate", "gbc-mute"];
     if (!yes) {
         console.log(`🐢 gbc init — 다음을 수행합니다 (프로젝트 로컬만, 전역 ~/.claude 미변경):
 
   대상 프로젝트: ${cwd}
   1) ${settingsPath} 에 PreToolUse(Edit|Write) + Stop + SessionStart hook 추가 (머지·멱등)
      - 기존 settings.json 있으면 백업: settings.json.bak-<시각>
-  2) ${join(skillDestDir, "SKILL.md")} 에 /gate 스킬 설치
+  2) ${join(claudeDir, "skills")} 에 ${skillNames.map((n) => `/${n}`).join(", ")} 스킬 설치
   3) hook 명령: ${buildPreCommand(CLI_PATH)}
 ${hasApiKey()
             ? "     (~/.gbc/api-key 감지됨 → 빠른 haiku API 경로로 동작)"
@@ -82,7 +83,7 @@ ${hasApiKey()
 `);
         return;
     }
-    mkdirSync(skillDestDir, { recursive: true });
+    mkdirSync(claudeDir, { recursive: true });
     // settings.json 머지
     let settings = {};
     if (existsSync(settingsPath)) {
@@ -132,10 +133,15 @@ ${hasApiKey()
         console.log(`  = SessionStart hook 이미 존재 (skip)`);
     }
     writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + "\n", "utf8");
-    // /gate 스킬 설치
-    if (existsSync(skillSrc)) {
-        copyFileSync(skillSrc, join(skillDestDir, "SKILL.md"));
-        console.log(`  + /gate 스킬 설치`);
+    // 스킬 설치 (gate + gbc-mute)
+    for (const name of skillNames) {
+        const src = join(PKG_ROOT, "skills", name, "SKILL.md");
+        if (existsSync(src)) {
+            const destDir = join(claudeDir, "skills", name);
+            mkdirSync(destDir, { recursive: true });
+            copyFileSync(src, join(destDir, "SKILL.md"));
+            console.log(`  + /${name} 스킬 설치`);
+        }
     }
     const transport = selectedTransport();
     console.log(`
@@ -178,7 +184,8 @@ async function cmdStatus() {
   명세 소스: ${source} ${text ? `(${text.length}자)` : "(비어있음 → 모든 코드변경 차단)"}
   명세 해시: ${hash}
   작업단위 게이트: ${state && state.specHash === hash && state.gated ? "통과됨(이 단위 재게이트 안 함)" : "미통과(다음 편집에서 발동)"}
-  defer: 전체 ${defers.length} / 미해결 ${unresolved.length} (진행중 ${inProgress} · 미착수 ${unresolved.length - inProgress})`);
+  defer: 전체 ${defers.length} / 미해결 ${unresolved.length} (진행중 ${inProgress} · 미착수 ${unresolved.length - inProgress})
+  Stop 리마인드: ${isStopHintMuted(cwd) ? "🔕 음소거 (해제: /gbc-mute)" : "🔔 켜짐"}`);
     if (unresolved.length > 0) {
         console.log(unresolved
             .map((d, i) => `    ${i + 1}. ${d.status === "in_progress" ? "▶[진행중] " : ""}${d.item}`)
@@ -202,8 +209,22 @@ function cmdDefer(args) {
         logCli(cwd, "defer-add", curHash(cwd));
         console.log(`🐢 미룸 등록: ${item}`);
     }
+    else if (sub === "mute" || sub === "unmute") {
+        const muted = sub === "mute";
+        setStopHintMuted(cwd, muted);
+        if (muted) {
+            console.log("🔕 Stop 리마인드 음소거됨 — 대화 종료마다 뜨던 defer 알림을 끕니다.\n" +
+                "   (SessionStart 진입 시엔 계속 표시 · 해제는 'gbc defer unmute')");
+        }
+        else {
+            console.log("🔔 Stop 리마인드 음소거 해제됨 — 대화 종료 시 미해결 defer 알림이 다시 표시됩니다.");
+        }
+    }
     else if (sub === "list") {
         const defers = loadDefers(cwd);
+        if (isStopHintMuted(cwd)) {
+            console.log("🔕 Stop 리마인드 음소거 중 (해제: gbc defer unmute)");
+        }
         if (defers.length === 0) {
             console.log("(미룬 항목 없음)");
             return;
@@ -233,7 +254,7 @@ function cmdDefer(args) {
         }
     }
     else {
-        console.error("사용: gbc defer <add|list|start|resolve|reopen> ...");
+        console.error("사용: gbc defer <add|list|start|resolve|reopen|mute|unmute> ...");
         process.exit(1);
     }
 }
@@ -319,6 +340,8 @@ function usage() {
   gbc defer start <번호|텍스트|all>    착수 표시 (open → 진행중)
   gbc defer resolve <번호|텍스트|all>  종결 표시 (→ 해결; 항상 사용자 점검 후)
   gbc defer reopen <번호|텍스트|all>   백로그로 되돌리기 (→ open)
+  gbc defer mute                      대화 종료(Stop)마다 뜨는 defer 알림 끄기 (영속)
+  gbc defer unmute                    Stop defer 알림 다시 켜기
   gbc spec add "<케이스>"              승인된 시나리오를 .gbc/spec.md에 등록
   gbc spec show                       등록된 케이스 목록
   gbc spec clear                      명세 비우기(작업단위 종료)

package/dist/config.js

@@ -0,0 +1,18 @@
+import { join } from "node:path";
+import { gbcDir, readJson, writeJson } from "./store.js";
+function configPath(cwd) {
+    return join(gbcDir(cwd), "config.json");
+}
+function readConfig(cwd) {
+    return readJson(configPath(cwd), {});
+}
+/** Stop hook defer 리마인드가 음소거 상태인지. 파일/키 부재 시 false(기본=노출). */
+export function isStopHintMuted(cwd) {
+    return readConfig(cwd).stopHintMuted === true;
+}
+/** Stop hook defer 리마인드 음소거 토글을 영속 저장(수동 unmute 전까지 유지). */
+export function setStopHintMuted(cwd, muted) {
+    const cfg = readConfig(cwd);
+    cfg.stopHintMuted = muted;
+    writeJson(configPath(cwd), cfg);
+}

package/dist/hook.js

@@ -5,6 +5,7 @@ import { isGatedTool, normalizeEdit } from "./normalize.js";
 import { loadPlanSpec, computeSpecHash } from "./spec.js";
 import { isGated, markGated } from "./state.js";
 import { activeDeferItems, loadDefers } from "./defer.js";
+import { isStopHintMuted } from "./config.js";
 import { readProjectSettings, buildUpdateNotice, wasNotified, markNotified } from "./notice.js";
 import { isCacheStale, readVersionCache, refreshVersionCache } from "./version.js";
 import { appendFileSync } from "node:fs";
@@ -233,6 +234,10 @@ export async function runStop() {
     if (input.stop_hook_active === true)
         process.exit(0);
     const cwd = input.cwd || process.cwd();
+    // 사용자가 'gbc defer mute'로 Stop 리마인드를 음소거했으면 조용히 통과(unmute 전까지 영속).
+    // SessionStart 진입 알림은 별개 채널이라 영향 없음. emit 없이 종료 = Claude 정상 stop 허용.
+    if (isStopHintMuted(cwd))
+        process.exit(0);
     // defers.json 없으면(파일 부재) 조용히 통과
     if (loadDefers(cwd).length === 0)
         process.exit(0);
@@ -311,8 +316,15 @@ export async function runSessionStart(ctx) {
     // 미해결 defer 알림(GBC_NO_SESSION_HINT로 opt-out — 기존 동작 보존).
     if (process.env.GBC_NO_SESSION_HINT !== "1") {
         const hint = buildSessionStartHint(loadDefers(cwd));
-        if (hint)
+        if (hint) {
             parts.push(hint);
+            // Stop 리마인드 음소거 중이면 진입 시 1회 환기("꺼둔 걸 잊지 않게"). hint가 있을 때만
+            // = 미해결 defer가 있을 때만(잔여 0이면 음소거 무관·노이즈). buildSessionStartHint는
+            // 순수 유지하고 오케스트레이션에서만 한 줄 첨부(시그니처 미오염).
+            if (isStopHintMuted(cwd)) {
+                parts.push("🔕 Stop 리마인드 음소거 중 — 매 대화 종료 알림은 꺼져 있습니다 (해제: /gbc-mute).");
+            }
+        }
     }
     // 업데이트 안내(staleness + version) — SessionStart 보유 코호트(0.2.3+)용. 세션 식별자가 없어
     // 항상 표시되므로 dedup 대신 GBC_NO_UPDATE_NOTICE opt-out에 맡긴다(buildUpdateNotice 내부).

package/package.json

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

package/skills/gate/SKILL.md

@@ -63,9 +63,11 @@ defer 항목은 **open(미착수) → in_progress(진행중) → resolved(해결
 ## 명세 소스
 
 게이트는 다음 우선순위로 계획 명세를 읽는다(durable 소스만):
-`$GBC_SPEC_FILE` > `.gbc/spec.md` > `scratch.md`
+`$GBC_SPEC_FILE` > `.gbc/spec.md`
 
-명세가 비면 "시나리오 미지정"으로 모든 코드 변경이 차단된다. 작업 전 `scratch.md`에 SubTask/체크리스트를 적거나 `.gbc/spec.md`를 만든다.
+`.gbc/spec.md`가 단일 정본(canonical)이다. `scratch.md` 자동 폴백은 0.2.2에서 제거됐다(진행추적 파일을 명세로 오인하던 거짓음성 차단) — 다른 파일을 명세로 쓰려면 `$GBC_SPEC_FILE`로 명시 지정한다.
+
+명세가 비면 "시나리오 미지정"으로 모든 코드 변경이 차단된다. 보통 위 「사용 흐름」 2의 도출 루프가 `gbc spec add`로 `.gbc/spec.md`를 채운다(수기 작성 불필요).
 
 ## Known Pitfalls
 

package/skills/gbc-mute/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: gbc-mute
+description: 거북이코드(gbc)의 defer Stop 리마인드를 on/off 토글한다. 미해결 defer가 있으면 Stop hook이 매 대화 종료(턴)마다 리마인드를 띄우는데, 이게 거슬릴 때 이 스킬로 음소거하거나 다시 켠다. '/gbc-mute', 'defer 알림 꺼줘', 'defer 알림 그만', '매번 뜨는 거 꺼줘', 'defer 음소거', 'Stop 리마인드 음소거', 'defer 알림 다시 켜줘', '음소거 해제', '리마인드 상태' 등 언급 시 호출.
+---
+
+# /gbc-mute — defer Stop 리마인드 음소거 토글
+
+미해결 defer가 있으면 거북이코드 **Stop hook이 매 대화 종료(턴)마다** 리마인드를 띄운다. `stop_hook_active` 가드는 한 턴 안의 루프만 끊을 뿐 세션 영속 억제가 아니라, **새 턴마다 재발화**한다(이월해도 계속 노출됨). 이 스킬은 그 매-턴 리마인드를 켜고 끄는 전용 토글이다.
+
+## 동작
+
+토글은 `.gbc/config.json`의 `stopHintMuted` 플래그로 영속된다(`gbc defer unmute` 전까지 유지 — 새 defer·세션 교체·`gbc gate reset`에도 풀리지 않음).
+
+| 사용자 의도 | 명령 |
+|---|---|
+| 현재 상태 확인 | `gbc defer list` (상단에 음소거 여부 표기) |
+| 음소거 켜기 (매-턴 Stop 리마인드 끄기) | `gbc defer mute` |
+| 음소거 끄기 (리마인드 다시 켜기) | `gbc defer unmute` |
+
+## 실행 흐름 (에이전트)
+
+1. **먼저 현재 상태를 확인**한다 — `gbc defer list`로 음소거 여부를 읽는다.
+2. 사용자 발화에서 의도를 판정해 토글한다:
+   - "꺼줘 / 그만 / 음소거 / 조용히" → `gbc defer mute`
+   - "켜줘 / 다시 / 해제" → `gbc defer unmute`
+   - 의도가 모호하면(예: "/gbc-mute"만 입력) → **현재 상태를 보여주고** 켤지 끌지 사용자에게 묻는다(상태-인지 토글, 무턱대고 뒤집지 않는다).
+3. 실행 결과를 **사용자에게 표면화**한다(`gbc defer mute`/`unmute`의 출력을 그대로 전달).
+
+## 끄는 범위 (중요)
+
+- **Stop 채널만** 끈다 — 매 대화 종료마다 강요되던 알림.
+- **SessionStart(세션 진입) 알림은 유지**한다. 새 세션 시작 시 "이전 작업 잔여"를 **한 번은** 회상하도록(완전 망각 방지). 즉 음소거는 "매 턴 강요"만 제거하고, 진입 시 1회 환기는 남긴다.
+- 음소거 중이면 SessionStart 진입 알림 끝에 `🔕 음소거 중 (해제: /gbc-mute)` 한 줄이 따라붙고, `gbc status`·`gbc defer list`에도 상태가 표기되므로 "꺼둔 걸 잊는" 일이 없다.
+
+## Known Pitfalls
+
+- **음소거는 defer를 지우지 않는다.** 항목은 그대로 남아 게이트 판정·SessionStart 회상에 계속 쓰인다. 끄는 건 "매-턴 알림"뿐이다. 항목을 끝낸 거면 음소거가 아니라 `gbc defer resolve`다(→ `/gate`).
+- **SessionStart는 음소거 대상이 아니다.** "진입 시에도 안 뜨게" 해달라는 요청이면 음소거로는 안 된다 — 그건 별개 채널(`GBC_NO_SESSION_HINT=1`)이며 의도적으로 분리돼 있다.