geobuke-code 0.2.3 → 0.2.5

package/README.md

@@ -61,6 +61,8 @@ gbc init
 
 > ⚠️ **native Windows에선 API 키를 권장한다.** 키 없는 `claude -p` 폴백도 지원하지만(win32에선 `claude.cmd` 실행을 위해 셸 경유, 프롬프트는 인젝션 회피로 stdin 전달, 무응답 방지 kill-timeout), 폴백은 느리므로(~13–20s) 위 키 파일로 API 경로(~1–3s)를 쓰는 편이 빠르고 확실하다.
 
+> 🔒 **회사·보안통제(EDR/그룹정책) 환경에선 API 키가 사실상 필수다.** native Windows에서 `claude.exe`가 EDR·정책에 막히면(증상: `claude exited 1: 액세스가 거부되었습니다`), 키 없는 `claude -p` 폴백 호출이 매번 실패해 게이트가 **조용히 fail-open**된다 — 게이트가 느려지는 게 아니라 **꺼진다**(`.gbc/failopen.log`에 누적). 이때 `ANTHROPIC_API_KEY`(또는 키 파일)를 설정하면 CLI spawn을 건너뛰고 직접 API로 판정하므로 **막힌 환경에서도 게이트가 살아 있다**. 즉 이 경우 키는 속도가 아니라 **게이트 작동 자체**의 문제다. (깨끗한 native Windows에선 keyless 폴백도 정상 동작함이 검증됨 — 실패는 환경의 CLI 차단에서 비롯된다.)
+
 키 해석 순서: `ANTHROPIC_API_KEY` 환경변수 > `~/.gbc/api-key` 파일.
 
 ```bash
@@ -94,11 +96,11 @@ 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`) |
-| **업데이트 필요 시** | (PreToolUse·SessionStart·`gbc status`) | hook 구버전(②) 또는 신버전 출시(①)면 갱신 안내. PreToolUse는 세션당 1회(`systemMessage` 비차단), 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 안 한" 경우에도 도달한다.
@@ -134,9 +136,11 @@ phase-protocol/계획 → /plan(SubTask) → 【게이트: 구현 직전 케이
 |---|---|
 | `gbc init` | hook + /gate skill 설치 |
 | `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 spec add "<케이스>"` | 승인된 시나리오를 `.gbc/spec.md`에 등록 |
 | `gbc spec show` | 등록된 케이스 목록 |
 | `gbc spec clear` | 명세 비우기(작업단위 종료) |

package/dist/cli.js

@@ -7,10 +7,10 @@ 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 { selectedTransport } from "./judge.js";
 import { buildPreCommand, normalizeHooks, ensureSessionStartHook } from "./install.js";
-import { isCacheStale, readVersionCache, refreshVersionCache, buildVersionNotice, } from "./version.js";
+import { isCacheStale, readVersionCache, refreshVersionCache, } from "./version.js";
 import { logEvent, parseEvents, computeMetrics } from "./metrics.js";
 const CLI_PATH = fileURLToPath(import.meta.url);
 const PKG_ROOT = join(dirname(CLI_PATH), ".."); // dist/cli.js → 패키지 루트
@@ -170,20 +170,23 @@ 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})`);
     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"));
     }
-    const verNotice = buildVersionNotice(PKG_VERSION, readVersionCache());
-    if (verNotice)
-        console.log(`  ${verNotice}`);
+    // 신버전 업데이트 안내(buildVersionNotice)는 여기서 출력하지 않는다 — 안내 자리는
+    // SessionStart·PreToolUse 자동 채널 전용이고, status는 명시 진단 명령이라 나그 부적절.
+    // (캐시 stale-refresh는 위에서 유지: SessionStart seed 신선도 목적, 표시와 무관.)
 }
 // ---------- gbc defer ----------
 function cmdDefer(args) {
@@ -205,17 +208,32 @@ function cmdDefer(args) {
             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> ...");
         process.exit(1);
     }
 }
@@ -296,9 +314,11 @@ 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 spec add "<케이스>"              승인된 시나리오를 .gbc/spec.md에 등록
   gbc spec show                       등록된 케이스 목록
   gbc spec clear                      명세 비우기(작업단위 종료)

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,7 @@
 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 { readProjectSettings, buildUpdateNotice, wasNotified, markNotified } from "./notice.js";
 import { isCacheStale, readVersionCache, refreshVersionCache } from "./version.js";
 import { appendFileSync } from "node:fs";
@@ -236,28 +236,62 @@ export async function runStop() {
     // 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(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}`);
+}
+/**
+ * Stop hook 리마인드 문자열. 없으면 "". 입력은 전체 defer 리스트(번호=전체-인덱스, 인덱스 ref 정합).
+ * SessionStart와 동일하게 in_progress를 차등 표면화한다 — "착수했지만 미종결" 항목이 레이더에서
+ * 사라지지 않게(resolve가 리마인드에서 항목을 떨구는 harm 완화).
  */
-export function buildSessionStartHint(unresolved) {
+export function buildStopReminder(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} 다음 세션으로 이월할 거면 의식적으로 확인하세요. (이 리마인드는 1회만 표시됩니다.)`);
 }
 /**
  * SessionStart: 세션 진입 시 미해결 defer를 stdout(plain text)으로 표면화 → Claude 컨텍스트 주입.
@@ -276,7 +310,7 @@ 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));
+        const hint = buildSessionStartHint(loadDefers(cwd));
         if (hint)
             parts.push(hint);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "geobuke-code",
-  "version": "0.2.3",
+  "version": "0.2.5",
   "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,7 +58,7 @@ 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에 표면화).
 
 ## 명세 소스