@su-record/vibe 3.2.21 → 3.2.22

package/CLAUDE.md

@@ -143,6 +143,6 @@ Public skills use the `vibe.*` namespace and are classified as **entry** / **sta
 
 **Include**: `.vibe/{plans,specs,features,todos,research,regressions,contracts,recipes,anti-patterns,loops,config.json,constitution.md}`, `CLAUDE.md`
 **Vibe-global (not project-local)**: `~/.vibe/test-reports/` — `/vibe.test` artifacts live with the vibe install, not with the project
-**Exclude**: `~/.claude/{rules,commands,agents,skills}/`, `.claude/settings.local.json`, `.codex/hooks.json`, `.vibe/{memories,checkpoints,metrics}/`
+**Exclude**: `~/.claude/{rules,commands,agents,skills}/`, `.claude/settings.local.json`, `.codex/hooks.json`, `.vibe/{memories,checkpoints,metrics,gates}/`
 
 <!-- VIBE:END -->

package/hooks/scripts/lib/anchor.js

@@ -10,6 +10,7 @@ import path from 'path';
 import { readLedger } from './run-ledger.js';
 import { projectVibePath } from '../utils.js';
 import { inboxPath } from './inbox.js';
+import { listOpenGates } from './gates.js';
 
 /** 우선순위대로 첫 번째로 존재하는 경로를 고른다 */
 function firstExisting(projectDir, candidates) {
@@ -65,7 +66,8 @@ function readLatestInboxBlock(projectDir) {
  * @param {string} projectDir
  * @param {string} [feature] - 생략 시 `.vibe/.last-feature`
  * @returns {{ feature: string|null, spec: string|null, scope: string|null,
- *             ledger: object|null, latestInbox: string|null, missing: string[] }}
+ *             ledger: object|null, latestInbox: string|null, openGates: object[],
+ *             missing: string[] }}
  */
 export function buildAnchor(projectDir, feature) {
   const resolved = feature || readLastFeature(projectDir);
@@ -81,5 +83,17 @@ export function buildAnchor(projectDir, feature) {
   if (!spec) missing.push('spec');
   if (!ledger) missing.push('run-ledger');
 
-  return { feature: resolved, spec, scope, ledger, latestInbox: readLatestInboxBlock(projectDir), missing };
+  // 열린 게이트는 재고정 대상이다 — 사람이 무엇을 기다리는지 모르면 다음 턴이
+  // 같은 질문을 다시 만들거나, 답을 기다리는 줄도 모르고 진행한다
+  const openGates = listOpenGates(projectDir);
+
+  return {
+    feature: resolved,
+    spec,
+    scope,
+    ledger,
+    latestInbox: readLatestInboxBlock(projectDir),
+    openGates,
+    missing,
+  };
 }

package/hooks/scripts/lib/gates.js

@@ -0,0 +1,138 @@
+/**
+ * 사람 판단 게이트 — 대기 중인 질문을 디스크에 남긴다.
+ *
+ * 배경: vibe 의 사람 개입 지점(SPEC 승인 · stuck 질문 · 비용 게이트)은 전부
+ * 모델이 그 자리에서 만들어 출력하는 텍스트였다. 세션이 죽거나 컨텍스트가
+ * 압축되면 **무엇을 묻고 있었는지가 사라진다** — 사람은 돌아왔는데 답할 대상이
+ * 없다. run-ledger·loop-history·인박스가 전부 디스크에 사는데 정작 "지금 사람을
+ * 기다리는 이유"만 컨텍스트에 살고 있었다.
+ *
+ * 게이트는 **모호한 상태가 아니라 구체적 질문**을 담는다. "승인 대기" 는 게이트가
+ * 아니다 — 무엇을 묻는지, 어떤 선택지가 있는지, 답이 무엇을 바꾸는지가 있어야
+ * 다음 턴(또는 다음 사람)이 이어받을 수 있다.
+ *
+ * 저장: `.vibe/gates/<id>.json` — 파일 하나가 게이트 하나. 동시에 여러 루프가
+ * 게이트를 열어도 서로 덮어쓰지 않는다.
+ *
+ * fail-open — 기록 실패가 루프를 멈추지 않는다.
+ */
+import fs from 'fs';
+import path from 'path';
+import { projectVibePath, projectVibePathPreferred } from '../utils.js';
+
+/** 읽기용 게이트 디렉토리 (레거시 인식) */
+export function gatesDir(projectDir) {
+  return projectVibePath(projectDir, 'gates');
+}
+
+/** 쓰기용 게이트 디렉토리 — 항상 신규 레이아웃 */
+function gatesWriteDir(projectDir) {
+  return projectVibePathPreferred(projectDir, 'gates');
+}
+
+/** 파일명에 쓸 수 있는 형태로 정규화 — 경로 이탈 방지 */
+function safeId(id) {
+  return String(id).replace(/[^a-zA-Z0-9._-]/g, '-').slice(0, 80);
+}
+
+/**
+ * 게이트를 연다.
+ *
+ * @param {string} projectDir
+ * @param {{
+ *   id: string,
+ *   question: string,
+ *   options?: string[],
+ *   kind?: 'spec-approval'|'stuck'|'cost'|'other',
+ *   context?: Record<string, unknown>,
+ *   at: string,
+ * }} gate - `at` 은 호출자가 넘긴다 (이 모듈은 시각을 읽지 않는다 — 테스트 결정성)
+ * @returns {string|null} 기록된 파일 경로, 실패 시 null
+ */
+export function openGate(projectDir, gate) {
+  try {
+    if (!gate?.id || !gate?.question || !gate?.at) return null;
+    // 구체적 질문이 아니면 게이트가 아니다 — 빈 질문·모호한 상태 문구를 거른다
+    if (gate.question.trim().length < 5) return null;
+
+    const dir = gatesWriteDir(projectDir);
+    fs.mkdirSync(dir, { recursive: true });
+    const file = path.join(dir, `${safeId(gate.id)}.json`);
+
+    const record = {
+      id: gate.id,
+      kind: gate.kind ?? 'other',
+      question: gate.question,
+      options: Array.isArray(gate.options) ? gate.options : [],
+      context: gate.context ?? {},
+      status: 'open',
+      openedAt: gate.at,
+    };
+    fs.writeFileSync(file, JSON.stringify(record, null, 2) + '\n', 'utf-8');
+    return file;
+  } catch {
+    return null;
+  }
+}
+
+/** 게이트 파일 하나를 읽는다. 손상된 파일은 무시한다. */
+function readGate(file) {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(file, 'utf-8'));
+    return parsed && typeof parsed === 'object' ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * 열려 있는 게이트 목록 — 오래된 것부터.
+ * @returns {Array<object>}
+ */
+export function listOpenGates(projectDir) {
+  try {
+    const dir = gatesDir(projectDir);
+    return fs.readdirSync(dir)
+      .filter(f => f.endsWith('.json'))
+      .map(f => readGate(path.join(dir, f)))
+      .filter(g => g && g.status === 'open')
+      .sort((a, b) => String(a.openedAt).localeCompare(String(b.openedAt)));
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * 게이트에 답한다 — 파일은 남기고 status 만 바꾼다.
+ * 지우지 않는 이유: 무엇을 물었고 무엇으로 답했는지가 증거다.
+ *
+ * @returns {boolean} 성공 여부
+ */
+export function answerGate(projectDir, id, answer, at) {
+  try {
+    if (!id || !answer || !at) return false;
+    const file = path.join(gatesDir(projectDir), `${safeId(id)}.json`);
+    const gate = readGate(file);
+    if (!gate || gate.status !== 'open') return false;
+
+    fs.writeFileSync(
+      file,
+      JSON.stringify({ ...gate, status: 'answered', answer, answeredAt: at }, null, 2) + '\n',
+      'utf-8',
+    );
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** 사람이 읽는 요약 — 스킬이 그대로 출력한다 */
+export function formatOpenGates(gates) {
+  if (gates.length === 0) return '열린 게이트 없음';
+  return gates.map(g => {
+    const opts = g.options.length > 0
+      ? '\n' + g.options.map((o, i) => `     [${i + 1}] ${o}`).join('\n')
+      : '';
+    return `⏸️ ${g.id} (${g.kind}, ${g.openedAt})\n   ${g.question}${opts}`;
+  }).join('\n\n');
+}

package/hooks/scripts/loop-ledger.js

@@ -8,6 +8,9 @@
  *   node hooks/scripts/loop-ledger.js check-stuck <name> <discoverHash>
  *   node hooks/scripts/loop-ledger.js anchor [feature]
  *   node hooks/scripts/loop-ledger.js inbox <name> <ok|fail|stuck> [line...]
+ *   node hooks/scripts/loop-ledger.js gate open <id> <question> [option...]
+ *   node hooks/scripts/loop-ledger.js gate list
+ *   node hooks/scripts/loop-ledger.js gate answer <id> <answer>
  *
  * check-stuck: 'stuck' 또는 'ok'를 stdout에 출력하고 항상 exit 0.
  * anchor: 재고정 번들 JSON을 stdout에 출력한다 (loop-contract ANCHOR 절).
@@ -17,6 +20,7 @@
 import { appendLoopEvent, isStuck } from './lib/loop-ledger.js';
 import { buildAnchor } from './lib/anchor.js';
 import { prependInboxBlock } from './lib/inbox.js';
+import { openGate, listOpenGates, answerGate, formatOpenGates } from './lib/gates.js';
 
 const [, , subcommand, ...args] = process.argv;
 const projectDir = process.env.CLAUDE_PROJECT_DIR || process.cwd();
@@ -69,10 +73,39 @@ if (subcommand === 'start') {
        : '[loop-ledger] WARNING: inbox write failed\n'
   );
 
+} else if (subcommand === 'gate') {
+  // 사람 판단 지점을 디스크에 남긴다 — 세션이 죽어도 무엇을 묻고 있었는지 남는다
+  const [action, id, ...rest] = args;
+
+  if (action === 'list') {
+    process.stdout.write(formatOpenGates(listOpenGates(projectDir)) + '\n');
+
+  } else if (action === 'open') {
+    const [question, ...options] = rest;
+    if (!id || !question) {
+      process.stdout.write('[loop-ledger] error: gate open 에 id 와 구체적 질문이 필요합니다\n');
+      process.exit(0);
+    }
+    const file = openGate(projectDir, { id, question, options, at: new Date().toISOString() });
+    process.stdout.write(file
+      ? `[loop-ledger] gate opened: ${id}\n`
+      : '[loop-ledger] WARNING: gate open failed (질문이 너무 짧거나 쓰기 실패)\n');
+
+  } else if (action === 'answer') {
+    const answer = rest.join(' ');
+    const ok = answerGate(projectDir, id, answer, new Date().toISOString());
+    process.stdout.write(ok
+      ? `[loop-ledger] gate answered: ${id}\n`
+      : `[loop-ledger] WARNING: gate not found or already answered: ${id}\n`);
+
+  } else {
+    process.stdout.write('[loop-ledger] 사용법: gate open <id> <question> [option...] | gate list | gate answer <id> <answer>\n');
+  }
+
 } else {
   process.stdout.write(
     '[loop-ledger] 사용법: start <name> | end <name> <ok|fail|stuck> [summary] | '
-    + 'check-stuck <name> <hash> | anchor [feature] | inbox <name> <ok|fail|stuck> [line...]\n'
+    + 'check-stuck <name> <hash> | anchor [feature] | inbox <name> <ok|fail|stuck> [line...] | gate <open|list|answer> …\n'
   );
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@su-record/vibe",
-  "version": "3.2.21",
+  "version": "3.2.22",
   "description": "AI Coding Framework for Claude Code — 7+ agents, 52 skills, multi-LLM orchestration",
   "type": "module",
   "main": "dist/cli/index.js",

package/skills/vibe/SKILL.md

@@ -208,7 +208,7 @@ Phase 4: /vibe.verify → 검증
 각 phase 종료 후 JUDGE 단계:
 - 게이트 통과 (**측정된** P1=0 ∧ verifyPassed) → 루프 종료, Phase 5 보고. 판정된 P1(리뷰어 findings)은 단독으로 게이트를 막지 않는다 — SSOT: `vibe/rules/loop-contract.md` Judge 권한 경계
 - 게이트 미통과 → RECORD(run-ledger + loop-history.jsonl) 후 다음 ANCHOR로
-- stuck(연속 2회 동일 findings 해시) → **어느 automationLevel 에서도 루프를 종료한다.** `confirm`이면 사용자 질문, `autonomous`이면 질문 없이 TODO 기록 후 다음 독립 단위로. 미달을 완료로 기록하지 않는다 (SSOT: `vibe/rules/loop-contract.md` stuck 절)
+- stuck(연속 2회 동일 findings 해시) → **어느 automationLevel 에서도 루프를 종료한다.** `confirm` 이면 사용자에게 묻되 질문을 컨텍스트에만 두지 말고 `loop-ledger.js gate open stuck-{feature} "<무엇이 막혔는지>" "<선택지…>"` 로 남긴다 — 세션이 끊겨도 무엇을 기다리는지 살아남는다 (게이트 객체 절). `autonomous` 면 질문 없이 TODO 기록 후 다음 독립 단위로. 미달을 완료로 기록하지 않는다 (SSOT: `vibe/rules/loop-contract.md` stuck 절)
 - max_iterations(기본 10) 도달 → 잔여를 인박스로 이월
 - **실행 실패(error)** — 스킬 미설치·도구 부재·파일 없음·명령 비정상 종료는 stuck 이 아니다(해시 비교로 안 잡힌다). 같은 방식으로 재시도하지 않고 루프를 종료한다: `confirm` 이면 원인을 제시하고 조치/건너뛰기/중단을 묻고, `autonomous` 이면 `loop-ledger.js inbox <name> fail "<원인>"` 기록 후 다음 독립 단위로. 실행 실패도 완료로 기록하지 않는다 (SSOT: `vibe/rules/loop-contract.md` 실행 실패 절)
 

package/skills/vibe.spec/SKILL.md

@@ -86,6 +86,20 @@ node -e "import('{{VIBE_PATH_URL}}/node_modules/@su-record/vibe/dist/tools/index
 
 **P1 이 하나라도 있으면 승인 요청으로 넘어가지 않는다** — SPEC 작성으로 되돌아가 고치고 다시 검사한다 (backward edge). 2회 연속 같은 findings 면 stuck 으로 처리한다 (SSOT: `vibe/rules/loop-contract.md`). P2 는 통과를 막지 않고 승인 메시지에 함께 표시한다.
 
+## 승인 게이트를 디스크에 남긴다
+
+승인을 요청하기 **전에** 게이트를 연다. 세션이 끊겨도 무엇을 묻고 있었는지 남는다
+(SSOT: `vibe/rules/loop-contract.md` 게이트 객체 절):
+
+```bash
+node "$HOOKS_DIR/loop-ledger.js" gate open spec-{feature-name} \
+  "SPEC '{feature-name}' 로 진행할까요? {가정 1건 명시}" \
+  "승인 → run 진행" "수정 후 재작성" "중단"
+```
+
+사용자가 답하면 `gate answer spec-{feature-name} "<선택>"` 으로 닫는다. 이미 열린
+게이트가 있으면(ANCHOR 의 `openGates`) 같은 질문을 새로 만들지 말고 그것을 이어받는다.
+
 ## 승인과 루프
 
 SPEC 승인이 `vibe/rules/loop-contract.md` 가 정의하는 **유일한 의무적 사람 개입**이다. 승인 후에는 ANCHOR→ACT→JUDGE→RECORD 루프가 게이트 통과까지 자동 반복한다 (`/vibe.run` → `/vibe.verify`). 별도의 파이프라인 승인·단계별 stop gate 는 없다.

package/vibe/rules/loop-contract.md

@@ -62,6 +62,27 @@ node "$HOOKS_DIR/loop-ledger.js" anchor [feature]
 
 > `autonomous` 의 "계속" 은 **stuck 난 루프를 더 돌린다는 뜻이 아니다** — 2회 연속 동일 발견은 정의상 재시도가 무의미하다. 같은 목표를 붙잡지 않고 다음 단위로 넘어간다는 뜻이며, 미달은 TODO/인박스에 남는다. 미달 상태를 **완료로 기록하지 않는다.**
 
+### 게이트 객체 — 사람을 기다리는 이유는 디스크에 산다
+
+사람 개입 지점의 질문이 컨텍스트에만 있으면, 세션이 죽거나 compact 로 소실될 때 **무엇을 묻고 있었는지가 사라진다.** 사람은 돌아왔는데 답할 대상이 없다. run-ledger·loop-history·인박스가 전부 디스크에 사는데 "지금 왜 멈춰 있는가"만 컨텍스트에 있었다.
+
+```bash
+node "$HOOKS_DIR/loop-ledger.js" gate open <id> "<구체적 질문>" "<선택지1>" "<선택지2>" …
+node "$HOOKS_DIR/loop-ledger.js" gate list      # 열린 게이트
+node "$HOOKS_DIR/loop-ledger.js" gate answer <id> "<답>"
+```
+
+- **모호한 상태는 게이트가 아니다.** "승인 대기" 는 질문이 아니다 — 무엇을 묻는지, 선택지가 무엇인지, 답이 무엇을 바꾸는지가 있어야 다음 턴(또는 다음 사람)이 이어받는다. 너무 짧은 문구는 `gate open` 이 거부한다.
+- 답한 게이트는 **지우지 않는다** — 무엇을 묻고 무엇으로 답했는지가 증거다 (`status: answered` 로 남는다).
+- ANCHOR 가 `openGates` 로 함께 재고정한다. 열린 게이트가 있으면 같은 질문을 다시 만들지 말고 그것을 이어받는다.
+- **게이트와 인박스의 경계**: 게이트는 *지금 답을 기다리는 살아 있는 질문*이라 런타임 상태다(`.vibe/gates/` — gitignore). 결정이 끝난 뒤 남길 기록은 인박스가 맡는다(`.vibe/loops/` — 커밋). 진행 중인 질문을 커밋하면 동시 실행마다 충돌한다.
+
+| 게이트 지점 | kind | 질문 |
+|---|---|---|
+| SPEC 승인 | `spec-approval` | 이 SPEC 으로 진행할지 — 승인 / 수정 / 중단 |
+| stuck (`confirm`) | `stuck` | 무엇이 막혔는지 + 값 채우기 / sub-100 승인 / 중단 |
+| 비용 게이트 `ask` | `cost` | 무엇을 얼마나 쓸지 — 진행 / 축소 / 중단 |
+
 ### 비용 게이트 — 사람은 시작점에만 서지 않는다
 
 SPEC 승인은 **유일한 의무 게이트**로 남는다. 다만 승인 이후 max_iterations 까지 무인이라, 그 안의 되돌릴 수 없는 지출과 이상 규모 팬아웃을 아무도 보지 못했다. 비용 게이트는 그 둘만 잡는다 — 평상시 규모는 그대로 통과시킨다.