geobuke-code 0.2.4 → 0.2.6

package/README.md

@@ -96,13 +96,13 @@ phase-protocol/계획 → /plan(SubTask) → 【게이트: 구현 직전 케이
 
 | 시점 | hook (matcher) | 동작 |
 |---|---|---|
-| **세션 시작·재개** | SessionStart (`startup\|resume`) | `.gbc/defers.json`의 미해결 항목을 표면화(이전 작업 잔여 환기). 잔여 없으면 무출력. `compact`엔 발화 안 함(노이즈 방지) |
+| **세션 시작·재개** | 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,11 +134,14 @@ phase-protocol/계획 → /plan(SubTask) → 【게이트: 구현 직전 케이
 
 | 명령 | 설명 |
 |---|---|
-| `gbc init` | hook + /gate skill 설치 |
-| `gbc status` | 게이트 상태 + 로드된 명세 확인 |
-| `gbc defer add "<케이스>"` | 케이스를 명시적으로 미루기 |
-| `gbc defer list` | 미룬 항목 목록 |
-| `gbc defer resolve <번호\|텍스트>` | 미룬 항목 해결 |
+| `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

@@ -7,7 +7,8 @@ import { mkdirSync, existsSync, readFileSync, writeFileSync, copyFileSync, } fro
 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 } from "./defer.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(`
@@ -170,16 +176,20 @@ async function cmdStatus() {
     const hash = computeSpecHash(text);
     const state = loadState(cwd);
     const defers = loadDefers(cwd);
-    const unresolved = defers.filter((d) => !d.resolved);
+    const unresolved = defers.filter((d) => d.status !== "resolved");
+    const inProgress = defers.filter((d) => d.status === "in_progress").length;
     console.log(`🐢 거북이 게이트 상태 — ${cwd}
   버전: ${PKG_VERSION || "(불명)"}
   트랜스포트: ${selectedTransport()}
   명세 소스: ${source} ${text ? `(${text.length}자)` : "(비어있음 → 모든 코드변경 차단)"}
   명세 해시: ${hash}
   작업단위 게이트: ${state && state.specHash === hash && state.gated ? "통과됨(이 단위 재게이트 안 함)" : "미통과(다음 편집에서 발동)"}
-  defer: 전체 ${defers.length} / 미해결 ${unresolved.length}`);
+  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.item}`).join("\n"));
+        console.log(unresolved
+            .map((d, i) => `    ${i + 1}. ${d.status === "in_progress" ? "▶[진행중] " : ""}${d.item}`)
+            .join("\n"));
     }
     // 신버전 업데이트 안내(buildVersionNotice)는 여기서 출력하지 않는다 — 안내 자리는
     // SessionStart·PreToolUse 자동 채널 전용이고, status는 명시 진단 명령이라 나그 부적절.
@@ -199,23 +209,52 @@ 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;
         }
-        defers.forEach((d, i) => console.log(`${i + 1}. [${d.resolved ? "해결" : "미해결"}] ${d.item}`));
-    }
-    else if (sub === "resolve") {
+        const label = {
+            open: "미해결",
+            in_progress: "진행중",
+            resolved: "해결",
+        };
+        defers.forEach((d, i) => console.log(`${i + 1}. [${label[d.status]}] ${d.item}`));
+    }
+    else if (sub === "start" || sub === "resolve" || sub === "reopen") {
         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}`);
+        if (!ref) {
+            console.error(`사용: gbc defer ${sub} <번호|텍스트|all>`);
+            process.exit(1);
+        }
+        const fn = sub === "start" ? startDefer : sub === "resolve" ? resolveDefer : reopenDefer;
+        const verb = sub === "start" ? "착수" : sub === "resolve" ? "해결" : "되돌림(open)";
+        const changed = fn(cwd, ref);
+        if (changed.length > 0) {
+            logCli(cwd, `defer-${sub}`, curHash(cwd));
+            console.log(`🐢 ${verb} ${changed.length}건: ${changed.map((d) => d.item).join(", ")}`);
+        }
+        else {
+            console.log(`매칭되는 항목 없음(0건): ${ref}`);
+        }
     }
     else {
-        console.error("사용: gbc defer <add|list|resolve> ...");
+        console.error("사용: gbc defer <add|list|start|resolve|reopen|mute|unmute> ...");
         process.exit(1);
     }
 }
@@ -296,9 +335,13 @@ function usage() {
 사용:
   gbc init [--yes]                    프로젝트에 hook + /gate 스킬 설치
   gbc status                          게이트 상태 + 로드된 명세 확인
-  gbc defer add "<케이스>"             케이스를 명시적으로 미루기
-  gbc defer list                      미룬 항목 목록
-  gbc defer resolve <번호|텍스트>      미룬 항목 해결
+  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                      명세 비우기(작업단위 종료)

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/defer.js

@@ -12,44 +12,93 @@ function nowIso() {
         return "";
     }
 }
+/**
+ * 원시 엔트리를 status 단일 소스로 정규화한다(마이그레이션).
+ * 옛 0.2.4 이하 포맷 {resolved:boolean}을 읽을 때 status로 승격:
+ * resolved:true→"resolved", false/부재→"open". 이미 status가 있으면 그대로.
+ */
+function promote(raw) {
+    const status = raw.status ?? (raw.resolved === true ? "resolved" : "open");
+    return { item: raw.item, at: raw.at, status };
+}
+/** 디스크에서 defer 엔트리를 읽어 status 포맷으로 정규화 반환(읽기 시 자동 승격) */
 export function loadDefers(cwd) {
-    return readJson(deferPath(cwd), []);
+    return readJson(deferPath(cwd), []).map(promote);
 }
+/** 저장은 항상 status 포맷으로 통일 — promote가 옛 resolved 필드를 떨궈 단일 소스 보장(drift 방지) */
 function save(cwd, defers) {
     writeJson(deferPath(cwd), defers);
 }
 /** 명시적으로 항목을 미룬다 (침묵 누락 차단의 유일한 정당 경로) */
 export function addDefer(cwd, item) {
     const defers = loadDefers(cwd);
-    const entry = { item: normalizeCase(item), at: nowIso(), resolved: false };
+    const entry = { item: normalizeCase(item), at: nowIso(), status: "open" };
     defers.push(entry);
     save(cwd, defers);
     return entry;
 }
-/** 미해결 defer 항목 텍스트만 (게이트 판정 입력용) */
+/**
+ * 미해결(=resolved 아님) defer 항목 텍스트만 (게이트 판정 입력용).
+ * gate-neutral: open + in_progress 모두 '아직 안 끝난 의도적 미룸'으로 judge에 전달 → 차단 로직 무변경.
+ */
 export function activeDeferItems(cwd) {
     return loadDefers(cwd)
-        .filter((d) => !d.resolved)
+        .filter((d) => d.status !== "resolved")
         .map((d) => d.item);
 }
-/** 미해결 defer 엔트리 (Stop hook 리마인드용) */
+/** 미해결(open+in_progress) defer 엔트리 (Stop hook·SessionStart 리마인드용) */
 export function unresolvedDefers(cwd) {
-    return loadDefers(cwd).filter((d) => !d.resolved);
+    return loadDefers(cwd).filter((d) => d.status !== "resolved");
 }
-/** 인덱스(1-base) 또는 부분 텍스트 매칭으로 defer 해결 표시 */
-export function resolveDefer(cwd, ref) {
-    const defers = loadDefers(cwd);
-    let target;
-    const idx = Number.parseInt(ref, 10);
-    if (!Number.isNaN(idx) && idx >= 1 && idx <= defers.length) {
-        target = defers[idx - 1];
+/**
+ * ref 문자열로 전환 대상 엔트리를 고른다. 세 형태 지원:
+ * - "all": eligibleFrom 상태에 해당하는 전부
+ * - 공백구분 토큰이 전부 정수: 복수 인덱스(1-base). 인덱스는 명시 지정이라 적격 무시(사용자가 번호를 안다)
+ * - 그 외: 통째로 부분 텍스트 1건 매칭(적격 항목 중) — 공백 포함 문구 하위호환
+ */
+function selectTargets(defers, ref, eligibleFrom) {
+    const trimmed = ref.trim();
+    // 빈 ref 가드: includes("")는 항상 첫 항목을 매칭하므로 빈 문자열이 엉뚱한 항목을 고른다.
+    // CLI(cli.ts)는 이미 빈 ref를 사전 차단하지만, selectTargets가 라이브러리로 직접 호출될 때를 위한 방어.
+    if (trimmed === "")
+        return [];
+    const eligible = (d) => eligibleFrom.includes(d.status);
+    if (trimmed === "all")
+        return defers.filter(eligible);
+    const tokens = trimmed.split(/\s+/).filter(Boolean);
+    const allInts = tokens.length > 0 && tokens.every((t) => /^\d+$/.test(t));
+    if (allInts) {
+        const out = [];
+        for (const t of tokens) {
+            const idx = Number.parseInt(t, 10);
+            if (idx >= 1 && idx <= defers.length && !out.includes(defers[idx - 1])) {
+                out.push(defers[idx - 1]);
+            }
+        }
+        return out;
     }
-    else {
-        target = defers.find((d) => !d.resolved && d.item.includes(ref));
-    }
-    if (!target)
-        return null;
-    target.resolved = true;
-    save(cwd, defers);
-    return target;
+    const t = defers.find((d) => eligible(d) && d.item.includes(trimmed));
+    return t ? [t] : [];
+}
+/** 선택된 대상을 toStatus로 전환하고 저장. 전환된 엔트리 배열 반환(매칭 0건이면 빈 배열). */
+function transition(cwd, ref, toStatus, eligibleFrom) {
+    const defers = loadDefers(cwd);
+    const targets = selectTargets(defers, ref, eligibleFrom);
+    for (const t of targets)
+        t.status = toStatus;
+    if (targets.length > 0)
+        save(cwd, defers);
+    return targets;
+}
+/** open → in_progress (착수). 텍스트/all 적격 = open. 인덱스는 명시 지정. */
+export function startDefer(cwd, ref) {
+    return transition(cwd, ref, "in_progress", ["open"]);
+}
+/** → resolved (종결, 항상 사람 선언). 텍스트/all 적격 = open + in_progress. */
+export function resolveDefer(cwd, ref) {
+    return transition(cwd, ref, "resolved", ["open", "in_progress"]);
+}
+/** → open (백로그로 되돌리기: 보류/이월 또는 잘못된 resolve 취소). 텍스트/all 적격 = in_progress + resolved. */
+export function reopenDefer(cwd, ref) {
+    return transition(cwd, ref, "open", ["in_progress", "resolved"]);
 }

package/dist/hook.js

@@ -4,7 +4,8 @@
 import { isGatedTool, normalizeEdit } from "./normalize.js";
 import { loadPlanSpec, computeSpecHash } from "./spec.js";
 import { isGated, markGated } from "./state.js";
-import { activeDeferItems, unresolvedDefers, loadDefers } from "./defer.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,31 +234,69 @@ 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);
-    const un = unresolvedDefers(cwd);
-    if (un.length === 0)
+    const all = loadDefers(cwd);
+    if (all.filter((d) => d.status !== "resolved").length === 0)
         process.exit(0);
-    const items = un.map((d, i) => `${i + 1}. ${d.item}`).join("\n");
-    emit({
-        decision: "block",
-        reason: `🐢 미해결 defer ${un.length}건이 남아 있습니다:\n${items}\n` +
-            `해결했으면 'gbc defer resolve <번호>', 다음 세션으로 이월할 거면 의식적으로 확인하세요. ` +
-            `(이 리마인드는 1회만 표시됩니다.)`,
-    });
+    emit({ decision: "block", reason: buildStopReminder(all) });
     process.exit(0);
 }
+/**
+ * defer 전환 행동 규약 — SessionStart/Stop 알림 문자열에 임베드한다.
+ * 규약 발화 자리가 hint 문자열인 이유: SKILL.md는 skill 실행 시점에만 읽혀 자유 편집·대화 중엔
+ * dead doc이 된다. 매 세션 컨텍스트에 신뢰성 있게 규약을 주입하는 유일한 결정론 채널이 이 문자열이다.
+ * (hook엔 추론을 넣지 않는다 — 텍스트만. 자연어/대상 감지·전환 실행은 에이전트 측 책임.)
+ */
+const DEFER_PROTOCOL = "규약 — 항목 착수 시 'gbc defer start <ref>'로 진행중 표시, 사용자가 완료를 명시하면 'gbc defer resolve <ref>'로 종결(신호가 모호하면 resolve하지 말고 확인). 되돌리기는 'gbc defer reopen <ref>'. ref=번호|텍스트|all. 모든 자동 전환은 사용자에게 표면화.";
+/**
+ * 전체 defer 리스트에서 미해결(open+in_progress)만 골라 상태 마커와 함께 한 줄씩 포맷한다.
+ * ★ 번호는 전체-리스트 위치(인덱스+1)로 매긴다 — `gbc defer list`·`gbc defer <N>` 인덱스 ref와 동일.
+ * 부분집합 번호를 쓰면 resolved가 앞에 있을 때 표시 번호 ≠ 실제 인덱스가 되어 엉뚱한 항목을 친다.
+ */
+function formatDeferList(all) {
+    return all
+        .map((d, i) => ({ d, n: i + 1 }))
+        .filter((x) => x.d.status !== "resolved")
+        .map((x) => `${x.n}. ${x.d.status === "in_progress" ? "▶[진행중]" : "[미착수]"} ${x.d.item}`)
+        .join("\n");
+}
+/** 미해결 건수를 진행중/미착수로 분해한 머리말 조각 */
+function statusBreakdown(unresolved) {
+    const inProgress = unresolved.filter((d) => d.status === "in_progress").length;
+    return `진행중 ${inProgress} · 미착수 ${unresolved.length - inProgress}`;
+}
 /**
  * 세션 진입(startup|resume) 시 미해결 defer 잔여를 표면화하는 알림 문자열. 없으면 "".
+ * 입력은 전체 defer 리스트(loadDefers) — 표시 번호를 전체-인덱스로 맞추기 위함(인덱스 ref 정합).
  * gbc 자기 소유 데이터(.gbc/defers.json)만 사용 — scratch/메모리 미접근(다른 하네스와 혼재·환각 방지).
+ * in_progress를 open과 구분 표면화("진행중 N · 미착수 M") — 착수했지만 미종결 항목이 잊히지 않게.
  */
-export function buildSessionStartHint(unresolved) {
+export function buildSessionStartHint(all) {
+    const unresolved = all.filter((d) => d.status !== "resolved");
     if (unresolved.length === 0)
         return "";
-    const items = unresolved.map((d, i) => `${i + 1}. ${d.item}`).join("\n");
-    return (`🐢 거북이 게이트 — 미해결 defer ${unresolved.length}건 (이전 작업 잔여):\n${items}\n` +
-        `필요하면 사용자에게 이어서 처리할지 확인하세요. 해결은 'gbc defer resolve <번호>'.`);
+    return (`🐢 거북이 게이트 — 미해결 defer ${unresolved.length}건 (${statusBreakdown(unresolved)}, 이전 작업 잔여):\n` +
+        `${formatDeferList(all)}\n` +
+        `필요하면 사용자에게 이어서 처리할지 확인하세요. ${DEFER_PROTOCOL}`);
+}
+/**
+ * Stop hook 리마인드 문자열. 없으면 "". 입력은 전체 defer 리스트(번호=전체-인덱스, 인덱스 ref 정합).
+ * SessionStart와 동일하게 in_progress를 차등 표면화한다 — "착수했지만 미종결" 항목이 레이더에서
+ * 사라지지 않게(resolve가 리마인드에서 항목을 떨구는 harm 완화).
+ */
+export function buildStopReminder(all) {
+    const unresolved = all.filter((d) => d.status !== "resolved");
+    if (unresolved.length === 0)
+        return "";
+    return (`🐢 미해결 defer ${unresolved.length}건이 남아 있습니다 (${statusBreakdown(unresolved)}):\n` +
+        `${formatDeferList(all)}\n` +
+        `${DEFER_PROTOCOL} 다음 세션으로 이월할 거면 의식적으로 확인하세요. (이 리마인드는 1회만 표시됩니다.)`);
 }
 /**
  * SessionStart: 세션 진입 시 미해결 defer를 stdout(plain text)으로 표면화 → Claude 컨텍스트 주입.
@@ -276,9 +315,16 @@ export async function runSessionStart(ctx) {
     const parts = [];
     // 미해결 defer 알림(GBC_NO_SESSION_HINT로 opt-out — 기존 동작 보존).
     if (process.env.GBC_NO_SESSION_HINT !== "1") {
-        const hint = buildSessionStartHint(unresolvedDefers(cwd));
-        if (hint)
+        const hint = buildSessionStartHint(loadDefers(cwd));
+        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.4",
+  "version": "0.2.6",
   "description": "거북이코드 — 구현 직전 강제 게이트. Claude Code PreToolUse hook으로 코드 변경 전 계획 케이스 누락·시나리오 미지정을 차단한다.",
   "type": "module",
   "bin": {

package/skills/gate/SKILL.md

@@ -12,6 +12,24 @@ description: 거북이코드 구현-전 게이트를 관리한다. 로드된 계
 - **미루기는 명시 등록만 허용한다.** "추후작업"이라고 머릿속/주석으로만 미루면 게이트가 침묵 누락으로 차단한다. 정당한 미루기는 반드시 `gbc defer add`로 등록해야 통과된다. (= 통증 "추후작업 미루다 누락" 직격)
 - **게이트는 완전구현을 요구하지 않는다.** 케이스가 다뤄지기 시작했거나 명시 defer되면 통과. 침묵 누락과 시나리오 미지정만 막는다.
 
+## defer 수명주기 — 자연어로 전환한다 (사용자가 명령을 직접 칠 필요 없음)
+
+defer 항목은 **open(미착수) → in_progress(진행중) → resolved(해결)** 3상태를 갖는다. 대부분의 경우 사용자는 `gbc defer …`를 직접 입력하지 않는다 — **에이전트가 대화(자연어)와 편집 대상을 감지해 백그라운드에서 전환을 실행**하고, 사용자에게 표면화한다. (명령은 수동 보정용으로 항상 사용 가능.)
+
+| 전환 | 트리거(감지) | 에이전트 행동 |
+|---|---|---|
+| **start** (open→진행중) | 그 defer 항목을 **실제로 착수**할 때(NL "이거 할게" 또는 해당 코드 편집 시작) | `gbc defer start <ref>` 자동 실행 + 표면화. 보수적으로 — 실제 착수할 때만(투기적 표시 금지). |
+| **resolve** (→해결) | **사용자의 명시적 완료 선언**("X 끝났어", "점검 OK") | 명확하면 `gbc defer resolve <ref>` 실행 + **반드시 표면화**. |
+| **reopen** (→open) | 사용자가 보류/이월/잘못된 resolve 취소를 요청 | `gbc defer reopen <ref>` 실행 + 표면화. |
+
+**resolve 모호성 규칙 (load-bearing — 미완성 항목이 조용히 잊히는 harm 차단):**
+- **명확한 완료 선언**("로그인 검증 끝냈어") → 자동 resolve + 표면화.
+- **모호한 신호**("다음으로 넘어가자", "대충 됐어") → **resolve하지 말고 사용자에게 확인**한다. resolve된 항목은 리마인드/SessionStart에서 사라지므로, 잘못 resolve하면 미완성인 채 잊힌다.
+- resolve는 **절대 게이트(judge)가 편집을 보고 추론하지 않는다** — 항상 사람의 명시 선언이 트리거. (start만 편집 감지로 자동.)
+- 모든 자동 전환은 **사용자에게 표면화**해 catch·reopen할 수 있게 한다.
+
+> 이상적 흐름: defer 확인 → (특정/전체 항목) start → 구현 → **사용자 점검** → resolve. 세션 내 완전 해소 안 되는 항목은 in_progress로 이월되고, SessionStart가 "진행중 N · 미착수 M"으로 구분 표면화한다.
+
 ## 명령 (bash로 실행)
 
 게이트는 현재 프로젝트 루트의 `gbc`를 사용한다. 작업 디렉토리에서 실행:
@@ -19,9 +37,11 @@ description: 거북이코드 구현-전 게이트를 관리한다. 로드된 계
 | 의도 | 명령 |
 |---|---|
 | 게이트 상태·로드된 명세 확인 | `gbc status` |
-| 미룬 항목 목록 | `gbc defer list` |
-| 케이스를 명시적으로 미루기 | `gbc defer add "<케이스 설명>"` |
-| 미룬 항목 해결 표시 | `gbc defer resolve <번호 또는 텍스트>` |
+| 미룬 항목 목록(상태: 미해결/진행중/해결) | `gbc defer list` |
+| 케이스를 명시적으로 미루기 (→ open) | `gbc defer add "<케이스 설명>"` |
+| 착수 표시 (open → 진행중) | `gbc defer start <번호\|텍스트\|all>` |
+| 종결 표시 (→ 해결) | `gbc defer resolve <번호\|텍스트\|all>` |
+| 백로그로 되돌리기 (→ open) | `gbc defer reopen <번호\|텍스트\|all>` |
 | 승인된 시나리오를 명세에 등록 | `gbc spec add "<케이스>"` |
 | 등록된 케이스 목록 | `gbc spec show` |
 | 명세 비우기(작업단위 종료) | `gbc spec clear` |
@@ -38,14 +58,16 @@ description: 거북이코드 구현-전 게이트를 관리한다. 로드된 계
    3. 승인된 케이스를 `gbc spec add "<케이스>"`로 등록하거나 `.gbc/spec.md`에 직접 작성한다.
    4. 재시도하면 통과한다.
    > 시나리오 도출은 코딩 에이전트 본체(Opus)가 대화 맥락으로, 게이트 판정은 haiku가 — 두 작업/두 모델 분리(gbc는 모델 계층을 소유하지 않는다).
-3. **세션 종료 시**: Stop hook이 미해결 defer를 리마인드한다. `gbc defer list`로 확인하고 해결하거나 다음 세션으로 의식적으로 이월한다.
+3. **세션 종료 시**: Stop hook이 미해결 defer를 "진행중 N · 미착수 M"으로 구분 리마인드한다. `gbc defer list`로 확인하고, 사용자 완료 선언이 있었으면 resolve, 아니면 다음 세션으로 의식적으로 이월한다(진행중 항목은 in_progress 그대로 남아 다음 SessionStart에 표면화).
 
 ## 명세 소스
 
 게이트는 다음 우선순위로 계획 명세를 읽는다(durable 소스만):
-`$GBC_SPEC_FILE` > `.gbc/spec.md` > `scratch.md`
+`$GBC_SPEC_FILE` > `.gbc/spec.md`
+
+`.gbc/spec.md`가 단일 정본(canonical)이다. `scratch.md` 자동 폴백은 0.2.2에서 제거됐다(진행추적 파일을 명세로 오인하던 거짓음성 차단) — 다른 파일을 명세로 쓰려면 `$GBC_SPEC_FILE`로 명시 지정한다.
 
-명세가 비면 "시나리오 미지정"으로 모든 코드 변경이 차단된다. 작업 전 `scratch.md`에 SubTask/체크리스트를 적거나 `.gbc/spec.md`를 만든다.
+명세가 비면 "시나리오 미지정"으로 모든 코드 변경이 차단된다. 보통 위 「사용 흐름」 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`)이며 의도적으로 분리돼 있다.