geobuke-code 0.2.5 → 0.2.7

package/README.md

@@ -99,12 +99,12 @@ 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`.
-> 프로젝트 hook이 구식이거나(SessionStart 누락·옛 명령) 새 버전이 나오면 gbc가 감지해 `gbc init --yes` 재실행 또는 `npm i -g geobuke-code@latest`를 안내한다. PreToolUse 경로로도 알리므로 "설치만 하고 init 안 한" 경우에도 도달한다.
-> **업데이트 안내(①)는 네트워크를 게이트 핫패스에 들이지 않는다**: `~/.gbc/version-check.json` 캐시만 비교하고, 갱신은 SessionStart·`gbc status`에서만 짧은 타임아웃으로. 조회 실패는 조용히 무시(fail-silent)되어 게이트 결정에 영향이 없다.
+> 세션 진입 알림만 끄려면 `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.
 
 ### 시나리오 도출 루프 (수기 입력 불필요)
 
@@ -134,13 +134,15 @@ phase-protocol/계획 → /plan(SubTask) → 【게이트: 구현 직전 케이
 
 | 명령 | 설명 |
 |---|---|
-| `gbc init` | hook + /gate skill 설치 |
-| `gbc status` | 게이트 상태 + 로드된 명세 확인 |
+| `gbc init` | hook + `/gate` · `/gbc-mute` 스킬 설치 |
+| `gbc update` | 전역 최신 설치(`npm i -g …@latest`) + 현재 프로젝트 재init 한방. `--dry-run`으로 실행 명령만 미리보기 |
+| `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

@@ -3,11 +3,13 @@
 import { fileURLToPath } from "node:url";
 import { dirname, join } from "node:path";
 import { homedir } from "node:os";
+import { spawnSync } from "node:child_process";
 import { mkdirSync, existsSync, readFileSync, writeFileSync, copyFileSync, } from "node:fs";
 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 +67,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 +84,7 @@ ${hasApiKey()
 `);
         return;
     }
-    mkdirSync(skillDestDir, { recursive: true });
+    mkdirSync(claudeDir, { recursive: true });
     // settings.json 머지
     let settings = {};
     if (existsSync(settingsPath)) {
@@ -132,10 +134,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 +185,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 +210,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 +255,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);
     }
 }
@@ -308,17 +330,58 @@ function cmdMetrics(args) {
     게이트 리셋 ${m.m1.resets} · 통과후 churn ${m.m1.churnAfterPass}
     ⚠️ ${m.m1.note}`);
 }
+// ---------- gbc update ----------
+/**
+ * 전역 최신 설치 + (현재 프로젝트면) 재init을 한 번에. 자동 silent 업데이트가 아니라 명시 명령 —
+ * 사용자가 nag를 보고 'gbc update' 한 줄로 갱신한다(매번 두 명령 외울 필요 제거).
+ * ★재init은 '새로 깔린' 바이너리를 fresh spawn해야 신규 스킬·hook이 반영된다(현재 실행 중인 건 구버전).
+ */
+function cmdUpdate(args) {
+    const cwd = process.cwd();
+    const dry = args.includes("--dry-run");
+    const isProject = existsSync(join(cwd, ".gbc"));
+    const steps = ["npm i -g geobuke-code@latest", ...(isProject ? ["gbc init --yes"] : [])];
+    if (dry) {
+        console.log("🐢 gbc update — 실행 예정(--dry-run):");
+        steps.forEach((s) => console.log(`  $ ${s}`));
+        if (!isProject)
+            console.log("  (현재 폴더에 .gbc 없음 → init 생략. 프로젝트에서 'gbc init --yes' 실행)");
+        return;
+    }
+    console.log(`🐢 gbc update — 전역 최신 설치${isProject ? " + 현재 프로젝트 재init" : ""}`);
+    // 1) 전역 최신 설치. shell:true + 고정 명령 문자열(사용자 입력 없음 → 인젝션 무관, 크로스플랫폼).
+    const r1 = spawnSync("npm i -g geobuke-code@latest", { stdio: "inherit", shell: true });
+    if (r1.status !== 0) {
+        console.error("❌ 전역 설치 실패. 권한 문제면 관리자 권한(Windows)·sudo 또는 수동 'npm i -g geobuke-code@latest'.");
+        process.exit(1);
+    }
+    // 2) gbc 프로젝트면 재init — 신규 스킬(gbc-mute 등)·최신 hook 반영.
+    if (isProject) {
+        const r2 = spawnSync("gbc init --yes", { stdio: "inherit", shell: true, cwd });
+        if (r2.status !== 0) {
+            console.error("⚠️ 전역 설치는 됐으나 'gbc init --yes' 실패 — 프로젝트에서 수동 실행하세요.");
+            process.exit(1);
+        }
+    }
+    else {
+        console.log("ℹ️ 현재 폴더는 gbc 프로젝트 아님(.gbc 없음) → 각 프로젝트에서 'gbc init --yes' 실행하세요.");
+    }
+    console.log("✅ gbc update 완료.");
+}
 function usage() {
     console.log(`🐢 gbc — 거북이코드 구현-전 게이트
 
 사용:
-  gbc init [--yes]                    프로젝트에 hook + /gate 스킬 설치
+  gbc init [--yes]                    프로젝트에 hook + /gate · /gbc-mute 스킬 설치
+  gbc update [--dry-run]              전역 최신 설치 + 현재 프로젝트 재init (한방 갱신)
   gbc status                          게이트 상태 + 로드된 명세 확인
   gbc defer add "<케이스>"             케이스를 명시적으로 미루기 (→ open)
   gbc defer list                      미룬 항목 목록 (상태: 미해결/진행중/해결)
   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                      명세 비우기(작업단위 종료)
@@ -344,6 +407,8 @@ async function main() {
             break;
         case "init":
             return cmdInit(rest);
+        case "update":
+            return cmdUpdate(rest);
         case "status":
             return cmdStatus();
         case "defer":

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,11 +316,30 @@ 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).");
+            }
+        }
+    }
+    // ①신버전 안내 — 캐시가 stale이면 '표시 전에' 먼저 갱신(1.5s 상한, fail-silent)해 이번 세션에
+    // 즉시 반영한다(표시-후-갱신의 '다음 세션 지연' 제거). SessionStart는 게이트를 막지 않으므로
+    // 짧은 네트워크가 안전(advisor 승인). 갱신은 24h TTL당 1회만 발생.
+    try {
+        if (ctx?.cliPath && process.env.GBC_NO_UPDATE_NOTICE !== "1" && isCacheStale(readVersionCache())) {
+            await refreshVersionCache();
+        }
+    }
+    catch {
+        /* 갱신 실패는 무시(fail-silent) */
     }
     // 업데이트 안내(staleness + version) — SessionStart 보유 코호트(0.2.3+)용. 세션 식별자가 없어
     // 항상 표시되므로 dedup 대신 GBC_NO_UPDATE_NOTICE opt-out에 맡긴다(buildUpdateNotice 내부).
+    // 위에서 갱신된 캐시를 읽으므로 신버전이 뜨는 그 세션에 즉시 표시된다.
     try {
         if (ctx?.cliPath) {
             const notice = buildUpdateNotice(readProjectSettings(cwd), ctx.cliPath, ctx.version ?? "");
@@ -328,15 +352,5 @@ export async function runSessionStart(ctx) {
     }
     if (parts.length > 0)
         process.stdout.write(parts.join("\n"));
-    // 버전 캐시 갱신은 '표시 후'에만(이번 출력은 캐시값 기준, 갱신은 다음 세션용). SessionStart는
-    // 게이트를 막지 않으므로 짧은 타임아웃 네트워크가 안전(advisor 승인). 실패는 조용히 무시.
-    try {
-        if (ctx?.cliPath && process.env.GBC_NO_UPDATE_NOTICE !== "1" && isCacheStale(readVersionCache())) {
-            await refreshVersionCache();
-        }
-    }
-    catch {
-        /* 갱신 실패는 무시(fail-silent) */
-    }
     process.exit(0);
 }

package/dist/version.js

@@ -67,7 +67,7 @@ export function buildVersionNotice(current, cache) {
     if (compareVersions(current, cache.latest) >= 0)
         return "";
     return (`🐢 거북이코드 신버전 ${cache.latest} 사용 가능(현재 ${current}). ` +
-        `갱신: npm i -g geobuke-code@latest → 각 프로젝트서 gbc init --yes`);
+        `갱신: 'gbc update'(전역 최신 + 현재 프로젝트 재init) 또는 수동 'npm i -g geobuke-code@latest → gbc init --yes'`);
 }
 /**
  * npm 레지스트리에서 최신 버전을 받아 캐시에 쓴다(짧은 타임아웃, 비차단·fail-silent).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "geobuke-code",
-  "version": "0.2.5",
+  "version": "0.2.7",
   "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`)이며 의도적으로 분리돼 있다.