@su-record/vibe 2.9.19 → 2.9.21

package/CLAUDE.md

@@ -66,7 +66,11 @@ No `console.log` in commits · No hardcoded strings/numbers · No commented-out
 
 ## Workflow
 
-`/vibe.spec` is the single entry point — orchestrates interview → plan → spec → review → `/vibe.run` → `/vibe.verify` → `/vibe.trace`. For UI types (website/webapp/mobile), `/vibe.figma` branches in parallel. Smart Resume detects existing `.claude/vibe/{interviews,plans,specs}/*.md` to skip phases.
+`/vibe.spec` is the single entry point — orchestrates interview → plan → spec → review → `/vibe.run` → `/vibe.verify` → `/vibe.contract` → `/vibe.trace`. For UI types (website/webapp/mobile), `/vibe.figma` branches in parallel. Smart Resume detects existing `.claude/vibe/{interviews,plans,specs}/*.md` to skip phases.
+
+**Quality-loop commands** (bug → prevention):
+- `/vibe.regress` — 회귀 테스트 자동 진화. `/vibe.verify` 실패 시 자동 register, `generate`로 예방 테스트 생성, `cluster`로 반복 패턴 승격.
+- `/vibe.contract` — API 계약 드리프트 감지. SPEC에서 추출한 계약과 구현 비교, P1 drift는 `/vibe.regress`로 자동 전파.
 
 | Task Size | Approach |
 |---|---|
@@ -94,7 +98,7 @@ No `console.log` in commits · No hardcoded strings/numbers · No commented-out
 
 ## Git
 
-**Include**: `.claude/vibe/{plans,specs,features,todos}/`, `.claude/vibe/config.json`, `CLAUDE.md`
+**Include**: `.claude/vibe/{plans,specs,features,todos,research,regressions,contracts}/`, `.claude/vibe/config.json`, `CLAUDE.md`
 **Exclude**: `~/.claude/{rules,commands,agents,skills}/`, `.claude/settings.local.json`
 
 <!-- VIBE:END -->

package/commands/vibe.contract.md

@@ -0,0 +1,105 @@
+---
+description: API contract drift detection — extract contracts from SPEC, compare to implementation, fail on drift
+argument-hint: "extract | check | diff [feature-name]"
+---
+
+# /vibe.contract
+
+**API Contract Drift Detection** — SPEC에 적힌 API 계약과 실제 구현이 어긋나면 즉시 잡는다.
+
+> SPEC은 진실의 원천이다. 구현이 SPEC을 소리 없이 떠나면 테스트는 통과해도 계약은 깨진다.
+
+## Usage
+
+```
+/vibe.contract extract <feature>       # SPEC에서 API 계약 추출 → .claude/vibe/contracts/<feature>.md
+/vibe.contract check <feature>         # 계약 vs 구현 비교, 드리프트 리포트
+/vibe.contract diff <feature>          # 마지막 check 이후 변경된 필드만 요약
+```
+
+## What counts as an "API contract"
+
+계약 = 외부(클라이언트, 다른 서비스)가 의존하는 **모든 인터페이스 형태**:
+
+- HTTP endpoint: method + path + request schema + response schema + status codes
+- GraphQL: query/mutation name + args + return shape
+- 이벤트/메시지: topic + payload schema
+- 내보내진 TypeScript 함수 시그니처 (public API로 명시된 경우)
+
+## Process
+
+Load skill `vibe-contract` with subcommand: `$ARGUMENTS`
+
+**핵심 단계**:
+
+1. **extract**: SPEC(.claude/vibe/specs/\<feature\>.md)의 "API" / "Endpoints" / "Interface" 섹션을 파싱, 구조화된 계약 레코드로 저장
+2. **check**: 실제 구현(코드)에서 동일 엔드포인트를 찾아 시그니처/스키마 비교 — 드리프트 발견 시 P1 리포트
+3. **diff**: 이전 check 스냅샷과 비교, **변경된 필드만** 노출 (노이즈 최소화)
+
+## Drift severity
+
+| Drift type | Severity | 예시 |
+|---|---|---|
+| Missing endpoint | P1 | SPEC에는 `GET /users/:id` 있는데 구현 없음 |
+| Missing required field in response | P1 | SPEC response에 `email` 있는데 구현에서 빠짐 |
+| Type change (breaking) | P1 | `userId: number` → `userId: string` |
+| Added required request field | P1 | 기존 클라이언트 호환성 깨짐 |
+| Added optional field | P3 | 확장은 허용 |
+| Status code added | P2 | 클라이언트가 처리해야 할 새 케이스 |
+| Status code removed | P1 | 예상 응답이 사라짐 |
+
+**P1 드리프트 발견 시**: `/vibe.verify` 통과 여부와 무관하게 실패로 간주. 테스트는 통과해도 계약은 깨질 수 있기 때문.
+
+## Storage Format
+
+```
+.claude/vibe/contracts/
+  <feature>.md           # 추출된 계약 (SSOT)
+  <feature>.snapshot.md  # 마지막 check 시점의 구현 스냅샷 (diff 비교용)
+```
+
+### Contract schema (frontmatter)
+
+```yaml
+---
+feature: string
+extracted-from: path/to/spec.md
+extracted-at: ISO timestamp
+endpoints:
+  - method: GET | POST | PUT | DELETE | PATCH
+    path: /users/:id
+    request:
+      params: { id: string }
+      body: null
+    response:
+      200: { id: string, email: string, ... }
+      404: { error: string }
+      required: [id, email]
+  - ...
+---
+```
+
+## Integration with /vibe.verify
+
+`/vibe.verify <feature>` 흐름 끝에 자동 체인:
+
+```
+scenarios pass → /vibe.contract check <feature>
+  ├─ no drift → ✅ complete
+  └─ drift found → ❌ report + auto-register to /vibe.regress (tag: integration)
+```
+
+## Integration with /vibe.spec
+
+`/vibe.spec` 작성 완료 직후 자동으로 `/vibe.contract extract` 호출하여 계약을 미리 뽑아둠. 이후 `/vibe.run` 구현 시 이 계약이 참조점.
+
+## Done Criteria
+
+- [ ] `extract`는 SPEC에 API 섹션이 없으면 **에러 없이 스킵** (모든 feature가 API를 갖진 않음)
+- [ ] `check`는 드리프트 없으면 조용히 통과, 있으면 severity별 분류 출력
+- [ ] P1 드리프트는 반드시 `/vibe.regress register --from-contract` 자동 호출
+- [ ] `diff`는 이전 스냅샷이 없으면 "첫 실행"이라 안내
+
+---
+
+ARGUMENTS: $ARGUMENTS

package/commands/vibe.regress.md

@@ -0,0 +1,73 @@
+---
+description: Regression test auto-evolution — register bugs, generate preventive tests, cluster patterns
+argument-hint: "register | generate | list | import | cluster [args]"
+---
+
+# /vibe.regress
+
+**Regression Auto-Evolution** — 같은 버그를 두 번 잡지 않기 위한 도구.
+
+> 버그는 기록되고, 예방 테스트는 자동 생성되고, 반복 패턴은 공통 테스트로 승격된다.
+
+## Usage
+
+```
+/vibe.regress register "<symptom>"           # 수동 등록 (최소, 대부분 자동)
+/vibe.regress generate <slug>                # bug → vitest 파일 생성
+/vibe.regress list                           # 미해결 목록
+/vibe.regress import                         # git log의 fix: 커밋 역추적
+/vibe.regress cluster                        # 3+ 유사 버그 → 공통 테스트 제안
+```
+
+## Auto-integration
+
+- `/vibe.verify` 실패 → 자동으로 `register` 호출 (수동 개입 없음)
+- `/vibe.run "<feature>"` 시작 → 해당 feature의 미해결 회귀 항목 경고
+
+## Process
+
+Load skill `vibe-regress` with subcommand: `$ARGUMENTS`
+
+`vibe-regress` 스킬이 등록·생성·클러스터링을 수행.
+
+**핵심 단계** (상세는 `skills/vibe-regress/SKILL.md` 참조):
+
+1. 서브커맨드 파싱
+2. `.claude/vibe/regressions/<slug>.md` 읽기/쓰기 (frontmatter 스키마 준수)
+3. `generate` 시 프로젝트 테스트 스택 감지 → 적합한 템플릿 선택 (vitest/jest)
+4. `cluster` 시 frontmatter의 `root-cause-tag`로 그룹핑 → 3개 이상이면 공통 테스트 제안
+5. `import` 시 `git log --grep='^fix:'` 파싱 → 중복 스킵, 신규만 등록
+
+## Output
+
+- `.claude/vibe/regressions/<slug>.md` — 버그 레코드 (frontmatter + 증상/재현/근본원인)
+- 프로젝트 test dir — 생성된 vitest 파일 (`*.regression.test.ts` 네이밍)
+- `list` 서브커맨드는 터미널 표
+
+## Storage Format
+
+```markdown
+---
+slug: login-jwt-expiry-off-by-one
+symptom: "JWT 만료 시간이 1초 일찍 끊김"
+root-cause-tag: timezone
+fix-commit: abc1234
+test-path: src/auth/__tests__/login.regression.test.ts
+status: open | test-generated | resolved
+registered: 2026-04-14
+feature: login
+---
+
+## Reproduction
+1. ...
+
+## Root cause
+...
+
+## Fix
+...
+```
+
+---
+
+ARGUMENTS: $ARGUMENTS

package/commands/vibe.run.md

@@ -46,6 +46,21 @@ Execute **Scenario-Driven Implementation** with automatic quality verification.
 
 > Automate **Scenario = Implementation = Verification** so even non-developers can trust quality
 
+### Pre-Run Regression Check (MANDATORY, before implementation starts)
+
+시작 직후 필수 실행:
+
+```
+Load skill `vibe-regress` with: list --feature "{feature-name}"
+```
+
+- 미해결 회귀 항목 있으면:
+  - interactive 모드: 사용자에게 "먼저 회귀 테스트 생성 후 진행?" 묻기
+  - ultrawork 모드: 자동 `/vibe.regress generate <slug>`로 예방 테스트 생성 후 진행
+- 미해결 없으면 조용히 통과
+
+또한 `.claude/vibe/contracts/{feature-name}.md`이 있으면 로드 — 구현 시 계약 준수 기준으로 사용.
+
 ### Core Flow
 
 ```

package/commands/vibe.spec.md

@@ -372,13 +372,25 @@ Load skill `vibe-spec-review` with feature: {feature-name}
 5. Review Debate Team (2+ P1/P2 이슈 시)
 6. 사용자 최종 체크포인트
 
+### Phase 4.5: Contract Extract (자동, API 있는 feature만)
+
+```
+Load skill `vibe-contract` with: extract "{feature-name}"
+```
+
+SPEC에 `## API` / `## Endpoints` / `## Interface` 섹션이 있으면 계약을 `.claude/vibe/contracts/{feature-name}.md`로 추출. 섹션이 없으면 에러 없이 스킵 (모든 feature가 API를 갖지 않음).
+
+이 계약은 Phase 5a 구현 시 참조되고, `/vibe.verify` 종료 시 drift 검사에 사용됨.
+
 ### Phase 5a: Logic Track
 
 ```
 /vibe.run "{feature-name}"
 ```
 
-SPEC → 코드 구현.
+SPEC → 코드 구현. 시작 시 자동 체크:
+- `/vibe.regress list --feature {feature-name}` — 미해결 회귀 항목 있으면 경고
+- `.claude/vibe/contracts/{feature-name}.md` — 있으면 로드하여 구현 가이드
 
 ### Phase 5b: UI Track (type ∈ {website, webapp, mobile}일 때만)
 

package/commands/vibe.verify.md

@@ -221,6 +221,24 @@ For each UI scenario in Feature file:
 └─────────────────────────────────────────────────────────────────┘
 ```
 
+### Failure Auto-Register (MANDATORY on any scenario failure)
+
+Before printing the failure report, **auto-register each failed scenario as a regression bug** so the same failure cannot silently slip through next time:
+
+```
+For each failed scenario:
+  Load skill `vibe-regress` with:
+    subcommand: register --from-verify
+    feature: {feature-name}
+    scenario: {scenario-name}
+    error: {error-summary}
+    location: {file:line}
+```
+
+- `--from-verify` 모드는 사용자 확인 없이 등록 (verify 실패 컨텍스트에서 마찰 최소화)
+- 등록된 bug의 slug를 Failure Report의 "Fix" 섹션에 링크로 노출
+- 이후 `/vibe.regress generate <slug>`로 예방 테스트 생성 가능
+
 ### Failure Report
 
 ```
@@ -384,6 +402,19 @@ node -e "import('{{VIBE_PATH_URL}}/node_modules/@su-record/vibe/dist/tools/index
 **Codex P2 발견 시:**
 - TODO 파일에 기록 후 완료 처리
 
+## Post-Verify Contract Check (자동, contract 파일 있을 때만)
+
+모든 시나리오 통과 후 자동 호출:
+
+```
+Load skill `vibe-contract` with: check "{feature-name}"
+```
+
+- `.claude/vibe/contracts/{feature-name}.md`이 없으면 스킵
+- drift 없음 → verify 통과 유지
+- **P1 drift** → verify 실패로 강등 + `/vibe.regress register --from-contract` 자동 호출
+- P2/P3 drift → 경고만, 통과 유지
+
 ## Next Step
 
 On verification pass:

package/hooks/scripts/__tests__/pre-tool-guard.test.js

@@ -280,8 +280,89 @@ describe('pre-tool-guard', () => {
         tool_name: 'Bash',
         tool_input: { command: 'DROP TABLE users' },
       });
-      // tool_input is stringified — pattern matches against the JSON string
       expect(result.exitCode).toBe(2);
+      expect(result.stdout).toContain('Database drop detected');
+    });
+  });
+
+  // ══════════════════════════════════════════════════
+  // Regression: file content false positives (issue: machine-key.ts blocked)
+  //   .claude/vibe/regressions/pre-tool-guard-content-false-positive.md
+  //
+  // 이전 구현은 tool_input 전체를 JSON.stringify해서 패턴 매칭했기 때문에
+  // 파일 내용에 '/etc/', '.env', 'secret' 같은 리터럴이 있으면 차단됐음.
+  // write/edit 패턴은 file_path만 봐야 한다.
+  // ══════════════════════════════════════════════════
+  describe('regression: write/edit content must not trigger path patterns', () => {
+    it('should ALLOW writing safe path even when content contains "/etc/" literal', () => {
+      const result = runGuardWithStdin({
+        tool_name: 'Write',
+        tool_input: {
+          file_path: 'src/machine-key.ts',
+          content: "for (const path of ['/etc/machine-id', '/var/lib/dbus/machine-id']) {}",
+        },
+      });
+      expect(result.exitCode).toBe(0);
+      expect(result.stdout).not.toContain('Writing to system directory');
+    });
+
+    it('should ALLOW writing safe path even when content contains "/usr/" literal', () => {
+      const result = runGuardWithStdin({
+        tool_name: 'Write',
+        tool_input: {
+          file_path: 'src/cli-detect.ts',
+          content: "const IOREG = '/usr/sbin/ioreg';",
+        },
+      });
+      expect(result.exitCode).toBe(0);
+      expect(result.stdout).not.toContain('Writing to system directory');
+    });
+
+    it('should ALLOW writing safe path even when content mentions ".env" / "secret"', () => {
+      const result = runGuardWithStdin({
+        tool_name: 'Write',
+        tool_input: {
+          file_path: 'src/config.ts',
+          content: "// loads from .env, never log secret values",
+        },
+      });
+      expect(result.exitCode).toBe(0);
+      expect(result.stdout).not.toContain('Writing to sensitive file');
+    });
+
+    it('should ALLOW editing safe path even when new_string contains ".env" literal', () => {
+      const result = runGuardWithStdin({
+        tool_name: 'Edit',
+        tool_input: {
+          file_path: 'src/index.ts',
+          old_string: 'const x = 1',
+          new_string: '// reads .env at startup',
+        },
+      });
+      expect(result.exitCode).toBe(0);
+      expect(result.stdout).not.toContain('Editing sensitive file');
+    });
+
+    it('should still BLOCK Write when file_path itself targets /etc/', () => {
+      const result = runGuardWithStdin({
+        tool_name: 'Write',
+        tool_input: { file_path: '/etc/passwd', content: 'root:x:0:0' },
+      });
+      expect(result.exitCode).toBe(2);
+      expect(result.stdout).toContain('Writing to system directory');
+    });
+
+    it('should still WARN Edit when file_path itself is a credentials file', () => {
+      const result = runGuardWithStdin({
+        tool_name: 'Edit',
+        tool_input: {
+          file_path: 'config/credentials.json',
+          old_string: 'a',
+          new_string: 'b',
+        },
+      });
+      expect(result.exitCode).toBe(0);
+      expect(result.stdout).toContain('Editing sensitive file');
     });
   });
 });

package/hooks/scripts/pre-tool-guard.js

@@ -7,26 +7,35 @@
 import { VIBE_PATH, PROJECT_DIR } from './utils.js';
 
 // 위험한 명령어 패턴
+//
+// 각 엔트리의 `target`은 매칭 대상 필드:
+//   - 'command'   → tool_input.command (Bash)
+//   - 'file_path' → tool_input.file_path (Write, Edit)
+//   - 'raw'       → 전체 문자열 (스키마 모를 때 폴백)
+//
+// 예전 버전은 항상 stringify된 tool_input 전체에 매칭하여 file content가
+// 패턴(예: /etc/, .env)과 일치하면 false positive로 차단되는 버그가 있었음.
+// 회귀: .claude/vibe/regressions/pre-tool-guard-content-false-positive.md
 const DANGEROUS_PATTERNS = {
   bash: [
-    { pattern: /rm\s+-rf?\s+[\/~]/, severity: 'critical', message: 'Deleting root or home directory' },
-    { pattern: /rm\s+-rf?\s+\*/, severity: 'high', message: 'Wildcard deletion detected' },
-    { pattern: /git\s+push\s+.*--force/, severity: 'high', message: 'Force push detected' },
-    { pattern: /git\s+reset\s+--hard/, severity: 'medium', message: 'Hard reset will discard changes' },
-    { pattern: /drop\s+(table|database)/i, severity: 'critical', message: 'Database drop detected' },
-    { pattern: /truncate\s+table/i, severity: 'high', message: 'Table truncate detected' },
-    { pattern: /:(){ :|:& };:/, severity: 'critical', message: 'Fork bomb detected' },
-    { pattern: /mkfs|fdisk|dd\s+if=/, severity: 'critical', message: 'Disk operation detected' },
-    { pattern: /chmod\s+-R\s+777/, severity: 'medium', message: 'Insecure permission change' },
-    { pattern: /curl.*\|\s*(ba)?sh/, severity: 'high', message: 'Piping curl to shell' },
+    { pattern: /rm\s+-rf?\s+[\/~]/, target: 'command', severity: 'critical', message: 'Deleting root or home directory' },
+    { pattern: /rm\s+-rf?\s+\*/, target: 'command', severity: 'high', message: 'Wildcard deletion detected' },
+    { pattern: /git\s+push\s+.*--force/, target: 'command', severity: 'high', message: 'Force push detected' },
+    { pattern: /git\s+reset\s+--hard/, target: 'command', severity: 'medium', message: 'Hard reset will discard changes' },
+    { pattern: /drop\s+(table|database)/i, target: 'command', severity: 'critical', message: 'Database drop detected' },
+    { pattern: /truncate\s+table/i, target: 'command', severity: 'high', message: 'Table truncate detected' },
+    { pattern: /:(){ :|:& };:/, target: 'command', severity: 'critical', message: 'Fork bomb detected' },
+    { pattern: /mkfs|fdisk|dd\s+if=/, target: 'command', severity: 'critical', message: 'Disk operation detected' },
+    { pattern: /chmod\s+-R\s+777/, target: 'command', severity: 'medium', message: 'Insecure permission change' },
+    { pattern: /curl.*\|\s*(ba)?sh/, target: 'command', severity: 'high', message: 'Piping curl to shell' },
   ],
   edit: [
-    { pattern: /\.env|credentials|secret|password|api[_-]?key/i, severity: 'medium', message: 'Editing sensitive file' },
-    { pattern: /package-lock\.json|yarn\.lock|pnpm-lock/, severity: 'low', message: 'Editing lock file directly' },
+    { pattern: /\.env|credentials|secret|password|api[_-]?key/i, target: 'file_path', severity: 'medium', message: 'Editing sensitive file' },
+    { pattern: /package-lock\.json|yarn\.lock|pnpm-lock/, target: 'file_path', severity: 'low', message: 'Editing lock file directly' },
   ],
   write: [
-    { pattern: /\.env|credentials|secret/i, severity: 'medium', message: 'Writing to sensitive file' },
-    { pattern: /\/etc\/|\/usr\/|C:\\Windows/i, severity: 'critical', message: 'Writing to system directory' },
+    { pattern: /\.env|credentials|secret/i, target: 'file_path', severity: 'medium', message: 'Writing to sensitive file' },
+    { pattern: /\/etc\/|\/usr\/|C:\\Windows/i, target: 'file_path', severity: 'critical', message: 'Writing to system directory' },
   ],
 };
 
@@ -82,10 +91,39 @@ const SAFE_ALTERNATIVES = {
   'chmod 777': 'Use specific permissions (e.g., chmod 755 for directories)',
 };
 
+/**
+ * 패턴 매칭 대상 추출
+ *
+ * tool_input이 객체이면 target 필드만 뽑아 반환. 객체가 아니거나(레거시 argv 모드)
+ * target='raw'이면 입력 전체를 그대로 반환.
+ *
+ * 핵심: write/edit 패턴은 file_path만 봐야 한다. content에 우연히 들어간
+ * 리터럴(예: 코드 안의 '/etc/machine-id' 문자열)이 차단을 일으키지 않도록.
+ */
+function extractTarget(rawInput, target) {
+  if (target === 'raw') return typeof rawInput === 'string' ? rawInput : JSON.stringify(rawInput);
+
+  // 객체로 파싱 시도
+  let obj = rawInput;
+  if (typeof rawInput === 'string') {
+    try {
+      obj = JSON.parse(rawInput);
+    } catch {
+      // JSON 아님 → 레거시 argv 모드. argv[3]은 보통 file_path 또는 command 단일 문자열.
+      // 안전하게 그 문자열을 target 값으로 간주.
+      return rawInput;
+    }
+  }
+
+  if (typeof obj !== 'object' || obj === null) return '';
+  const value = obj[target];
+  return typeof value === 'string' ? value : '';
+}
+
 /**
  * 명령어 검증
  */
-function validateCommand(toolName, input) {
+function validateCommand(toolName, rawInput) {
   const results = {
     allowed: true,
     severity: 'none',
@@ -95,8 +133,11 @@ function validateCommand(toolName, input) {
 
   const patterns = DANGEROUS_PATTERNS[toolName.toLowerCase()] || [];
 
-  for (const { pattern, severity, message } of patterns) {
-    if (pattern.test(input)) {
+  for (const { pattern, target, severity, message } of patterns) {
+    const haystack = extractTarget(rawInput, target || 'raw');
+    if (!haystack) continue;
+
+    if (pattern.test(haystack)) {
       results.warnings.push(`[${severity.toUpperCase()}] ${message}`);
 
       // 심각도에 따른 처리
@@ -109,9 +150,9 @@ function validateCommand(toolName, input) {
         results.severity = severity;
       }
 
-      // 대안 제안
+      // 대안 제안 — 매칭된 target 필드에서만 검색
       for (const [dangerous, safe] of Object.entries(SAFE_ALTERNATIVES)) {
-        if (input.includes(dangerous)) {
+        if (haystack.includes(dangerous)) {
           results.suggestions.push(safe);
         }
       }

package/package.json

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

package/skills/parallel-research/SKILL.md

@@ -63,11 +63,24 @@ Parallel research complete
     ↓
 Synthesize results
     ↓
+Persist to .claude/vibe/research/<topic-slug>/
+    ├── synthesis.md      (conversational report)
+    ├── awesome-list.md   (curated links/repos)
+    └── paper.md          (structured survey for /vibe.spec Context)
+    ↓
 Reflect in SPEC Context section
 OR
 Reference during implementation
 ```
 
+### Output Location (SSOT)
+
+All research artifacts live under `.claude/vibe/research/<topic-slug>/`. Reference `paper.md` explicitly when writing a SPEC (e.g. paste its path into the Context section). Re-running research on the same topic overwrites unless the slug collides across dates (then `-YYYYMMDD` suffix).
+
+> Wire-up note: `/vibe.spec` does **not** yet auto-scan this directory — that integration is a follow-up. For now, cite the path manually.
+
+Pass `--ephemeral` to skip persistence when exploring throwaway questions.
+
 ## When Research is NOT Needed
 
 - Simple CRUD operations
@@ -85,5 +98,7 @@ Reference during implementation
 
 - [ ] All 4 research agents returned results (or documented why not)
 - [ ] Results synthesized into actionable recommendations
+- [ ] Three artifacts written to `.claude/vibe/research/<slug>/` (synthesis / awesome-list / paper) — unless `--ephemeral`
+- [ ] Every awesome-list entry has a one-line "why"
 - [ ] Key findings reflected in SPEC Context section or implementation notes
 - [ ] Conflicting recommendations resolved with reasoning

package/skills/parallel-research/agents/synthesizer.md

@@ -12,10 +12,15 @@ Receives outputs from all parallel research agents and produces a unified, opini
 ## Responsibilities
 - Collect and read all findings from best-practices, framework-docs, codebase-patterns, and security-advisory agents
 - Identify agreements and conflicts across sources; resolve with explicit reasoning
-- Weight findings: official docs > community consensus > codebase patterns > blog posts
+- Weight findings: security > official docs > codebase patterns > community consensus > blog posts
 - Produce a ranked recommendation: primary approach + acceptable alternatives
 - Flag blockers — security issues or fundamental incompatibilities that must be resolved first
 - Summarize key trade-offs so the user can make an informed decision
+- Emit **three** persisted artifacts (unless ephemeral mode):
+  1. `synthesis.md` — conversational report (schema below)
+  2. `awesome-list.md` — curated links, repos, internal patterns, anti-patterns (from `templates/awesome-list.md`)
+  3. `paper.md` — structured survey with Abstract/Background/Method/Findings/Recommendation/References (from `templates/paper.md`)
+- Drop entries without a one-line "why". No bare link dumps.
 
 ## Input
 Markdown findings documents from all four research agents (best-practices, framework-docs, codebase-patterns, security-advisory).

package/skills/parallel-research/orchestrator.md

@@ -33,6 +33,17 @@ agents: [best-practices, framework-docs, codebase-patterns, security-advisory, s
 - **Output**: Ranked recommendations ordered by confidence and relevance
 - **Parallel**: no
 
+### Phase 5: Persist as Reusable Dataset
+- **Agent**: orchestrator (self)
+- **Input**: Synthesis (Phase 3) + ranked output (Phase 4)
+- **Output**: Three files under `.claude/vibe/research/<topic-slug>/`:
+  - `synthesis.md` — conversational synthesis (from `templates/synthesis.md`)
+  - `awesome-list.md` — curated links/repos by category (from `templates/awesome-list.md`)
+  - `paper.md` — structured survey for `/vibe.spec` Context injection (from `templates/paper.md`)
+- **Parallel**: no — write after Phase 4 completes
+- **Slug rule**: kebab-case of topic, max 50 chars, deduped with `-YYYYMMDD` suffix on collision
+- **Skip condition**: user passed `--ephemeral` or running inside `ultrawork` dry-run
+
 ## DAG (Dependency Graph)
 
 ```mermaid
@@ -43,6 +54,7 @@ graph TD
     E[Phase 1d: security-advisory] --> C
     C --> F[Phase 3: Synthesizer]
     F --> G[Phase 4: Ranked Output]
+    G --> H[Phase 5: Persist dataset]
 ```
 
 ## Error Handling
@@ -55,6 +67,8 @@ graph TD
 | Phase 2 | <2 agents return results | Warn user, proceed with partial synthesis |
 | Phase 3 | Conflicting recommendations | Flag conflict explicitly, present both sides |
 | Phase 4 | 0 actionable recommendations | Fallback — return raw findings without ranking |
+| Phase 5 | Write fails (permission, disk) | Warn user, return synthesis in-conversation without persisting |
+| Phase 5 | Slug collision | Append `-YYYYMMDD`; if still colliding, append `-<hhmm>` |
 
 ## Scalability Modes
 

package/skills/parallel-research/templates/awesome-list.md

@@ -0,0 +1,32 @@
+# Awesome {{RESEARCH_TOPIC}}
+
+> Curated from parallel research on {{DATE}}. Source agents: best-practices, framework-docs, codebase-patterns, security-advisory.
+
+## Official
+
+- [{{OFFICIAL_DOCS_TITLE}}]({{OFFICIAL_DOCS_URL}}) — {{OFFICIAL_DOCS_NOTE}}
+
+## Reference Implementations
+
+- [{{REPO_1_NAME}}]({{REPO_1_URL}}) — {{REPO_1_WHY}}
+- [{{REPO_2_NAME}}]({{REPO_2_URL}}) — {{REPO_2_WHY}}
+
+## Articles & Best Practices
+
+- [{{ARTICLE_1_TITLE}}]({{ARTICLE_1_URL}}) — {{ARTICLE_1_TAKEAWAY}}
+
+## Security Advisories
+
+- [{{CVE_OR_ADVISORY}}]({{ADVISORY_URL}}) — severity: {{SEVERITY}} · mitigation: {{MITIGATION}}
+
+## Internal Patterns (this codebase)
+
+- `{{FILE_PATH}}:{{LINE}}` — {{PATTERN_NOTE}}
+
+## Anti-patterns to Avoid
+
+- {{ANTIPATTERN_1}} — why: {{ANTIPATTERN_1_REASON}}
+
+---
+
+**Curation rules**: every entry has a one-line "why" explaining when to reach for it. Entries without a reason were dropped. Prefer primary sources over aggregators.

package/skills/parallel-research/templates/paper.md

@@ -0,0 +1,88 @@
+---
+topic: {{RESEARCH_TOPIC}}
+slug: {{SLUG}}
+date: {{DATE}}
+stack: [{{TECHNOLOGY_STACK_CSV}}]
+question: {{RESEARCH_QUESTION}}
+---
+
+# {{RESEARCH_TOPIC}}: A Structured Survey for Implementation
+
+**Date**: {{DATE}}
+**Stack**: {{TECHNOLOGY_STACK}}
+**Research question**: {{RESEARCH_QUESTION}}
+
+---
+
+## Abstract
+
+{{ONE_PARAGRAPH_ABSTRACT}}
+
+**TL;DR recommendation**: {{RECOMMENDATION}}
+
+## 1. Background
+
+{{PROBLEM_CONTEXT — why this matters now, what forced the investigation}}
+
+### 1.1 Prior art in this codebase
+
+{{EXISTING_PATTERNS — what's already here, at what file paths}}
+
+### 1.2 Scope
+
+- In scope: {{IN_SCOPE}}
+- Out of scope: {{OUT_OF_SCOPE}}
+
+## 2. Method
+
+Parallel research across four specialized agents (best-practices, framework-docs, codebase-patterns, security-advisory). Findings weighted by source priority: **security > official docs > codebase consistency > community consensus > blog posts**.
+
+## 3. Findings
+
+### 3.1 Approach A — {{APPROACH_A}}
+- Pro: {{A_PRO}}
+- Con: {{A_CON}}
+- Evidence: {{A_EVIDENCE}}
+
+### 3.2 Approach B — {{APPROACH_B}}
+- Pro: {{B_PRO}}
+- Con: {{B_CON}}
+- Evidence: {{B_EVIDENCE}}
+
+### 3.3 Conflicts and resolutions
+
+| Conflict | Position A | Position B | Resolution | Rationale |
+|----------|-----------|-----------|------------|-----------|
+| {{C_1}} | {{A_1}} | {{B_1}} | {{R_1}} | {{WHY_1}} |
+
+## 4. Security considerations
+
+| Risk | Severity | Mitigation | Blocker? |
+|------|----------|------------|----------|
+| {{RISK_1}} | {{SEV_1}} | {{MIT_1}} | {{YN}} |
+
+## 5. Recommendation
+
+**Primary**: {{PRIMARY_APPROACH}}
+**Acceptable fallback**: {{FALLBACK}}
+**Reject**: {{REJECTED}} — reason: {{REJECT_REASON}}
+
+### 5.1 Implementation starting point
+
+{{CONCRETE_FIRST_STEP — file to touch, function to add, snippet}}
+
+## 6. Open questions
+
+- [ ] {{OPEN_Q_1}} — resolve before {{PHASE}}
+- [ ] {{OPEN_Q_2}} — can proceed without
+
+## 7. References
+
+| # | Source | Agent | Confidence |
+|---|--------|-------|------------|
+| 1 | {{SRC_1}} | {{AGENT_1}} | {{CONF_1}} |
+| 2 | {{SRC_2}} | {{AGENT_2}} | {{CONF_2}} |
+
+---
+
+**Reuse**: cite this file by path (`.claude/vibe/research/{{SLUG}}/paper.md`) when writing a SPEC — paste the Findings and Recommendation sections into the SPEC's Context block.

package/skills/vibe-contract/SKILL.md

@@ -0,0 +1,166 @@
+---
+name: vibe-contract
+tier: core
+description: "API contract drift detection. Extracts HTTP/GraphQL/event/public-function contracts from SPEC into .claude/vibe/contracts/<feature>.md, compares to implementation, and fails loudly on breaking drift (missing endpoints, removed required fields, type changes). P1 drifts auto-register as regressions via vibe-regress. Must use this skill when user runs /vibe.contract, when /vibe.spec completes, when /vibe.verify passes scenarios, or when the user says 'contract', 'API schema', 'breaking change', 'drift', '계약', '스키마 바뀜'."
+triggers: [contract, drift, "계약", "API 변경", "breaking change", "schema drift"]
+priority: 70
+chain-next: []
+---
+
+# vibe.contract — API Contract Drift Detection
+
+**Purpose**: SPEC에 적힌 외부 계약과 실제 구현이 어긋나면 즉시 잡는다. 테스트 통과 ≠ 계약 준수.
+
+## Why this exists
+
+바이브코딩의 숨은 약점: 구현이 자라면서 SPEC에 명시된 응답 shape에서 조용히 벗어난다. 시나리오 테스트는 통과해도 **외부 소비자는 깨진다**. 사람이 매번 SPEC을 비교하기엔 마찰이 크므로 기계화.
+
+## Storage Contract
+
+```
+.claude/vibe/contracts/
+  <feature>.md             # 계약 SSOT (SPEC에서 추출)
+  <feature>.snapshot.md    # 구현 스냅샷 (마지막 check 시점)
+```
+
+### Contract frontmatter schema
+
+```yaml
+---
+feature: string
+extracted-from: .claude/vibe/specs/<feature>.md
+extracted-at: ISO-8601
+source-spec-hash: sha256  # SPEC 변경 감지용
+endpoints:
+  - id: unique-kebab-id         # 예: get-user-by-id
+    kind: http | graphql | event | function
+    # http
+    method: GET | POST | PUT | DELETE | PATCH
+    path: /users/:id
+    request:
+      params: { name: type, ... }
+      query: { name: type, ... }
+      body: { field: type, ... } | null
+      required: [field, ...]
+    response:
+      statusCodes:
+        200: { schema }
+        404: { error: string }
+      required-fields:
+        200: [id, email]
+    # graphql
+    operation: query | mutation
+    name: string
+    args: { ... }
+    returns: { ... }
+    # event
+    topic: string
+    payload: { ... }
+    # function
+    signature: "(a: string, b: number) => Promise<User>"
+    module: path/to/file.ts
+---
+```
+
+## Subcommands
+
+### 1. `extract <feature>` — SPEC에서 계약 추출
+
+**단계**:
+1. SPEC 파일 로드 (single file or split folder)
+2. 다음 섹션을 순서대로 탐색:
+   - `## API` / `## Endpoints` / `## Interface` / `## Contract`
+   - Markdown 테이블 (method/path/request/response 헤더)
+   - 코드 블록 안의 OpenAPI/JSON Schema 스니펫
+3. 추출 실패(해당 섹션 없음) → **에러 없이 `no-contract` 상태 기록 후 종료**. 모든 feature가 API를 갖진 않음.
+4. 추출 성공 → frontmatter 구조로 변환
+5. `source-spec-hash`: SPEC 파일 내용의 sha256 (다음 extract 시 변경 감지)
+6. `.claude/vibe/contracts/<feature>.md` 저장 (기존 파일이 있고 hash가 같으면 **no-op**)
+
+**주의**: 추출은 LLM 파싱. 신뢰도 낮은 필드는 `# unconfirmed` 주석 달아서 사용자가 검토 가능하게.
+
+### 2. `check <feature>` — 계약 vs 구현 비교
+
+**단계**:
+1. `.claude/vibe/contracts/<feature>.md` 로드. 없으면 **먼저 extract 제안**.
+2. 각 endpoint에 대해 구현 탐색:
+   - http: 프레임워크 감지 (Express, Fastify, Next.js API routes, Hono, ...)
+   - graphql: resolver 파일 찾기
+   - event: 프로듀서/컨슈머 코드
+   - function: 모듈 export
+3. 구현 시그니처/스키마를 추출 → 계약과 비교
+4. Drift 분류 (severity 표는 command file 참고)
+5. 스냅샷 저장: `.claude/vibe/contracts/<feature>.snapshot.md` (현재 구현 상태)
+
+### 3. `diff <feature>` — 이전 스냅샷 대비 변경만
+
+**단계**:
+1. `.snapshot.md`가 없으면 "첫 실행" 안내 후 종료
+2. 현재 구현 재추출 vs 기존 스냅샷 비교
+3. **변경된 필드만** 출력 (ASCII diff 형식):
+   ```
+   endpoints/get-user-by-id/response/200:
+     - email: string
+     + email: string | null   ← nullability 추가 (P1 breaking)
+     + phoneNumber: string    ← 신규 필드 (P3 safe)
+   ```
+4. 드리프트 있으면 `/vibe.regress register --from-contract` 자동 호출
+
+## Drift Severity Matrix
+
+(command file의 표와 동일 — 변경 시 양쪽 갱신)
+
+## Integration Points
+
+### From /vibe.spec
+
+SPEC 작성 완료 직후 자동 호출:
+```
+Load skill `vibe-contract` with: extract <feature>
+```
+실패해도 `/vibe.spec`은 계속 진행 (계약 추출은 옵션). 단 성공 시 `/vibe.run`이 이 계약을 참조.
+
+### From /vibe.verify
+
+모든 scenario pass 후 자동 체인:
+```
+Load skill `vibe-contract` with: check <feature>
+```
+- drift 없음 → verify 통과 유지
+- P1 drift → verify 실패로 강등, regress 자동 등록
+- P2/P3 drift → 경고만, verify 통과 유지
+
+### To /vibe.regress
+
+P1 drift 발견 시:
+```
+Load skill `vibe-regress` with:
+  subcommand: register --from-contract
+  feature: <feature>
+  symptom: "Contract drift: <endpoint-id> <drift-type>"
+  root-cause-tag: integration
+```
+
+## Framework Detection Rules
+
+HTTP framework 감지 순서:
+1. `package.json` dependencies에서: `next` → Next.js API routes
+2. `fastify` → Fastify
+3. `express` → Express
+4. `hono` → Hono
+5. `@nestjs/core` → NestJS
+6. 감지 실패 → user에게 질문 후 manual mapping
+
+감지 후 각 프레임워크의 **라우트 정의 패턴**을 Grep으로 찾아 endpoint 매핑:
+- Next.js: `pages/api/**` or `app/api/**/route.ts`
+- Express: `app.get|post|put|delete|patch\(`
+- Fastify: `fastify.get|post|...` or route configuration
+- Hono: `app.get|post|...`
+
+## Done Criteria
+
+- [ ] `extract`가 API 섹션 없는 SPEC에서 에러 내지 않음
+- [ ] `source-spec-hash` 기반 re-extract 스킵
+- [ ] `check`는 각 drift에 severity + 위치(file:line) 명시
+- [ ] P1 drift는 100% `/vibe.regress` 자동 등록
+- [ ] 프레임워크 감지 실패 시 silently skip 금지 — 반드시 user 질문

package/skills/vibe-regress/SKILL.md

@@ -0,0 +1,174 @@
+---
+name: vibe-regress
+tier: core
+description: "Regression test auto-evolution. Registers bugs (auto from /vibe.verify failures or manual), generates preventive vitest/jest files from bug records, clusters repeated patterns (3+ same root-cause-tag) into shared tests, and imports historical `fix:` commits from git log. Storage: .claude/vibe/regressions/<slug>.md. Must use this skill when user runs /vibe.regress, when /vibe.verify produces a failure, or when the user says 'don't let this happen again' / '이 버그 다시는' / 'regression test' / '회귀 테스트'."
+triggers: [regress, regression, "회귀", "다시는", "반복 버그", "fix commit"]
+priority: 70
+chain-next: []
+---
+
+# vibe.regress — Regression Auto-Evolution
+
+**Purpose**: 같은 버그를 두 번 잡지 않는다. 버그를 잡을 때마다 예방 테스트가 자라난다.
+
+## Why this exists
+
+바이브코딩의 고전적 약점: LLM이 같은 클래스의 버그를 매번 새로 만든다. 회귀 테스트는 이를 기계적으로 막는 유일한 장치. 단, 사람이 매번 회귀 테스트를 쓰면 건너뛰게 됨 — 그래서 자동화.
+
+## Storage Contract
+
+```
+.claude/vibe/regressions/
+  <bug-slug>.md       # 하나의 버그 = 하나의 파일
+  _cluster-<tag>.md   # cluster 서브커맨드가 생성한 공통 테스트 설계
+```
+
+### Frontmatter schema (엄격)
+
+```yaml
+slug: string            # kebab-case, 글로벌 유일
+symptom: string         # 1줄, 사용자 관점
+root-cause-tag: enum    # 아래 허용 태그만
+fix-commit: string      # git hash (없으면 "pending")
+test-path: string       # 생성된 테스트 파일 경로 (없으면 "pending")
+status: open | test-generated | resolved
+registered: YYYY-MM-DD
+feature: string         # 연관 feature 이름 (SPEC과 매칭)
+```
+
+### Allowed `root-cause-tag` values
+
+클러스터링의 기반이므로 **미리 정의된 집합만** 사용:
+
+- `timezone` — 시간대/DST/off-by-one
+- `nullability` — null/undefined/empty 처리
+- `concurrency` — race condition, 동시성
+- `boundary` — off-by-one, edge value
+- `encoding` — charset, URL encoding, escape
+- `validation` — 입력 검증 누락
+- `auth` — 인증/권한 로직
+- `state-sync` — 클라이언트/서버 상태 불일치
+- `integration` — 외부 API 호출 실패
+- `type-narrow` — TypeScript 타입 좁히기 실수
+- `other` — 위에 안 맞을 때 (나중에 새 태그 추가)
+
+**규칙**: 새 태그가 필요하면 기존 태그에 억지로 맞추지 말고 `other`로 등록한 뒤, `other`가 3개 이상 쌓이면 사용자에게 태그 추가를 제안.
+
+## Subcommands
+
+### 1. `register "<symptom>"` — 수동 등록
+
+대부분은 자동 호출되므로 수동 사용은 드뭅니다 (verify 실패 밖에서 발견된 버그, 또는 프로덕션 이슈용).
+
+**단계**:
+1. `getCurrentTime`으로 오늘 날짜 확보
+2. `git log -1 --format=%H`으로 현재 커밋 해시 (fix-commit 후보)
+3. Claude가 대화로 다음을 뽑아냄:
+   - Reproduction steps (Given/When/Then)
+   - Root cause 1문단
+   - Fix 설명
+4. `root-cause-tag`는 허용 집합에서 **자동 추론 후 사용자에게 확인**. 애매하면 `other`.
+5. slug 생성: symptom에서 핵심어 → kebab-case, 충돌 시 `-2` 접미사
+6. `.claude/vibe/regressions/<slug>.md` 작성 (status: `open`)
+
+### 2. `generate <slug>` — 예방 테스트 생성
+
+**단계**:
+1. bug 파일 읽기
+2. 테스트 스택 감지:
+   - `package.json`의 `devDependencies`에서 `vitest` > `jest` 순
+   - 둘 다 없으면 **user에게 질문 후 중단**
+3. 테스트 위치 결정:
+   - feature의 구현 파일 옆 `__tests__/` 또는
+   - 프로젝트의 기존 test dir (vitest config.test.include 확인)
+4. 파일명: `<original-file>.regression.test.ts`
+5. 내용: `templates/test-vitest.md` 또는 `templates/test-jest.md` 템플릿에서 치환
+6. bug 파일 frontmatter 업데이트: `test-path`, `status: test-generated`
+7. **생성 후 즉시 테스트 실행** — 실패해야 정상 (아직 수정 안 됨이면) 또는 통과 (수정 완료됨이면). 결과를 frontmatter에 기록.
+
+### 3. `list` — 미해결 목록
+
+```
+/vibe.regress list                 # status != resolved 전부
+/vibe.regress list --feature login # feature별
+/vibe.regress list --tag timezone  # tag별
+```
+
+터미널 표:
+
+```
+SLUG                              FEATURE   TAG         STATUS           AGE
+login-jwt-expiry-off-by-one       login     timezone    test-generated   3d
+cart-stock-race-double-deduct     cart      concurrency open             1d
+```
+
+### 4. `import` — git log 역추적
+
+**단계**:
+1. `git log --grep='^fix:' --format='%H|%s|%ci' --since=<last-import-date>`
+   - `last-import-date`는 `.claude/vibe/regressions/.import-cursor` 파일에서 읽음 (없으면 90일 전)
+2. 각 커밋에 대해:
+   - 이미 같은 `fix-commit`을 가진 bug 파일이 있으면 **스킵**
+   - 없으면 커밋 메시지/diff에서 symptom + root-cause-tag 추론 (LLM 호출)
+   - 신규 bug.md 작성 (status: `resolved` — 이미 고쳐졌으므로)
+3. 완료 후 `.import-cursor` 갱신
+4. 새로 import된 항목에 대해 사용자에게 `generate` 제안
+
+**주의**: `fix:` 커밋이 아닌 일반 커밋은 **무시**. Conventional Commits 규약을 사용하지 않는 프로젝트는 `--grep-pattern` 옵션으로 오버라이드.
+
+### 5. `cluster` — 반복 패턴 승격
+
+**단계**:
+1. 모든 bug 파일의 `root-cause-tag` 집계
+2. **같은 태그가 3개 이상**이면 cluster 후보
+3. 각 후보에 대해:
+   - 3개 bug의 reproduction을 LLM에게 주고 "공통 원인과 공통 테스트 케이스"를 추출
+   - `_cluster-<tag>.md` 파일 생성 (기존 bug 파일들의 slug를 링크)
+   - 공통 테스트 skeleton을 `<project-test-dir>/_cluster-<tag>.regression.test.ts`로 제안 (사용자 승인 후 생성)
+4. 클러스터 생성 시 원본 bug 파일은 **삭제하지 않음** — 이력 보존
+
+**중요**: cluster는 자동 실행 안 됨. 사용자가 명시적으로 호출해야 함 (과도한 추상화 방지).
+
+## Integration with /vibe.verify
+
+`/vibe.verify` 실패 시 verify가 다음을 호출:
+
+```
+Load skill `vibe-regress` with: register --from-verify
+  <feature>: {feature-name}
+  <scenario>: {failed-scenario}
+  <error>: {error-message}
+  <location>: {file:line}
+```
+
+`--from-verify` 플래그 동작:
+- symptom = scenario name + error summary
+- feature = 전달된 feature name
+- root-cause-tag = error pattern에서 자동 추론 (애매하면 `other`)
+- status = `open`
+- **사용자 확인 없이 등록** (verify 실패 상황은 이미 주의 집중 중이라 마찰 최소화가 중요)
+
+## Integration with /vibe.run
+
+`/vibe.run "<feature>"` 시작 시:
+
+1. `ls .claude/vibe/regressions/*.md`에서 `feature: <feature-name>` + `status != resolved` 필터
+2. 미해결 있으면 경고:
+   ```
+   ⚠️  Open regressions for this feature:
+     - login-jwt-expiry-off-by-one (timezone, 3d old)
+     - login-session-leak (auth, 1w old)
+   
+   Fix these before adding new behavior? [y/N]
+   ```
+3. `y` → `/vibe.regress generate`로 체인 (미생성 항목)
+4. `N` → 계속 진행 (ultrawork 모드는 자동 `N` + TODO 기록)
+
+## Done Criteria
+
+- [ ] 서브커맨드가 지정 없이 호출되면 usage 표시
+- [ ] frontmatter 스키마 엄격 준수 (누락 필드 있으면 거부)
+- [ ] `root-cause-tag`가 허용 집합 외 값이면 경고 + `other`로 강제
+- [ ] `generate` 후 테스트를 **실제로 실행**하여 결과 검증
+- [ ] `import`는 중복 스킵 (fix-commit 해시 기준)
+- [ ] `cluster`는 3개 미만이면 아무것도 안 함 (false positive 방지)

package/skills/vibe-regress/templates/bug.md

@@ -0,0 +1,44 @@
+---
+slug: {{SLUG}}
+symptom: "{{SYMPTOM}}"
+root-cause-tag: {{ROOT_CAUSE_TAG}}
+fix-commit: {{FIX_COMMIT}}
+test-path: {{TEST_PATH}}
+status: {{STATUS}}
+registered: {{DATE}}
+feature: {{FEATURE}}
+---
+
+# {{SLUG}}
+
+## Symptom
+
+{{SYMPTOM_DETAIL}}
+
+## Reproduction
+
+**Given**: {{GIVEN}}
+
+**When**: {{WHEN}}
+
+**Then** (broken behavior): {{THEN_BROKEN}}
+
+**Expected**: {{THEN_EXPECTED}}
+
+## Root cause
+
+{{ROOT_CAUSE_EXPLANATION}}
+
+## Fix
+
+{{FIX_EXPLANATION}}
+
+## Related
+
+- Feature: [.claude/vibe/features/{{FEATURE}}.feature](../../features/{{FEATURE}}.feature)
+- Fix commit: `{{FIX_COMMIT}}`
+- Regression test: `{{TEST_PATH}}`
+
+## Notes
+
+{{NOTES}}

package/skills/vibe-regress/templates/test-jest.md

@@ -0,0 +1,29 @@
+/**
+ * Regression test — {{SLUG}}
+ *
+ * Symptom: {{SYMPTOM}}
+ * Root cause tag: {{ROOT_CAUSE_TAG}}
+ * Fix commit: {{FIX_COMMIT}}
+ * Source record: .claude/vibe/regressions/{{SLUG}}.md
+ *
+ * DO NOT delete this test when the bug is fixed — it exists to prevent the
+ * same bug from being reintroduced. Update only if the reproduction steps
+ * in the source record change.
+ */
+
+{{IMPORTS_FROM_SUT}}
+
+describe('regression: {{SYMPTOM_SHORT}}', () => {
+  it('{{TEST_NAME}}', {{ASYNC}}() => {
+    // Given: {{GIVEN}}
+    {{GIVEN_CODE}}
+
+    // When: {{WHEN}}
+    {{WHEN_CODE}}
+
+    // Then: {{THEN}}
+    {{THEN_ASSERTIONS}}
+  });
+
+  {{EXTRA_IT_BLOCKS}}
+});

package/skills/vibe-regress/templates/test-vitest.md

@@ -0,0 +1,30 @@
+/**
+ * Regression test — {{SLUG}}
+ *
+ * Symptom: {{SYMPTOM}}
+ * Root cause tag: {{ROOT_CAUSE_TAG}}
+ * Fix commit: {{FIX_COMMIT}}
+ * Source record: .claude/vibe/regressions/{{SLUG}}.md
+ *
+ * DO NOT delete this test when the bug is fixed — it exists to prevent the
+ * same bug from being reintroduced. Update only if the reproduction steps
+ * in the source record change.
+ */
+
+import { describe, it, expect{{EXTRA_IMPORTS}} } from 'vitest';
+{{IMPORTS_FROM_SUT}}
+
+describe('regression: {{SYMPTOM_SHORT}}', () => {
+  it('{{TEST_NAME}}', {{ASYNC}}() => {
+    // Given: {{GIVEN}}
+    {{GIVEN_CODE}}
+
+    // When: {{WHEN}}
+    {{WHEN_CODE}}
+
+    // Then: {{THEN}}
+    {{THEN_ASSERTIONS}}
+  });
+
+  {{EXTRA_IT_BLOCKS}}
+});

package/skills/vibe-spec/SKILL.md

@@ -395,6 +395,30 @@ Read ~/.claude/vibe/languages/typescript-react.md
 - `config.json.references` is automatically referenced when running `/vibe.run`
 - Not copied to project (referenced from global package)
 
+### 2.9 Research Cache Check (BEFORE step 3)
+
+Before spawning any research agents, check for a prior persisted dataset:
+
+```bash
+# Slug = kebab-case of feature/topic, max 50 chars
+ls .claude/vibe/research/<slug>/paper.md 2>/dev/null
+```
+
+**If `paper.md` exists:**
+1. Read `.claude/vibe/research/<slug>/paper.md`
+2. Read `.claude/vibe/research/<slug>/awesome-list.md` (if present)
+3. Inject the **Findings**, **Recommendation**, and **Security considerations** sections into SPEC Context verbatim, prefixed with `> Source: .claude/vibe/research/<slug>/paper.md (cached {{FILE_MTIME}})`
+4. **Skip step 3** (parallel research) entirely — do not re-run GPT/Gemini/Claude agents
+5. Show message: `✅ Research cache hit: <slug> (saved ~30s of LLM calls)`
+
+**Cache invalidation:**
+- User passes `--refresh-research` → delete dir, run step 3 fresh
+- `paper.md` mtime older than 30 days → warn user, ask to refresh or reuse
+- Stack in `paper.md` header differs from current stack → auto-refresh
+
+**If `paper.md` does NOT exist:**
+Proceed to step 3. After step 3 completes, the synthesizer **must** write the 3 artifacts (see `parallel-research/orchestrator.md` Phase 5) so the next `/vibe.spec` run on this topic hits the cache.
+
 ### 3. Parallel Research (v2.5.0) - MANDATORY AFTER requirements confirmed
 
 **🚨🚨🚨 ABSOLUTE RULES FOR RESEARCH PHASE 🚨🚨🚨**
@@ -539,6 +563,22 @@ Task(subagent_type="ui-layout-architect",
 - Layout: {③ pattern + sections}
 ```
 
+### 3.9 Persist Research Cache (AFTER research completes, BEFORE SPEC write)
+
+> The "no Write during research" rule (step 3) does **not** apply here — research is done, artifacts are safe to persist.
+
+After parallel research + UI/UX intelligence complete and before writing the SPEC, save the merged research into `.claude/vibe/research/<slug>/`:
+
+1. Compute slug: kebab-case of feature name, max 50 chars
+2. Write **three files** using templates from `parallel-research/templates/`:
+   - `.claude/vibe/research/<slug>/synthesis.md` — raw merged findings (all agent outputs)
+   - `.claude/vibe/research/<slug>/awesome-list.md` — curated links/repos/patterns (each entry needs a one-line "why"; drop entries without it)
+   - `.claude/vibe/research/<slug>/paper.md` — structured survey (Abstract → Background → Method → Findings → Recommendation → Security → References)
+3. Include a frontmatter header in `paper.md` with `stack:` field so step 2.9 can detect stack drift
+4. If the directory already exists (user ran `--refresh-research`), overwrite
+
+This makes the next `/vibe.spec` or `/vibe.research` invocation on the same topic hit the cache at step 2.9.
+
 ### 4. Write SPEC Document (PTCF Structure)
 
 #### 4.0 Large Scope Detection & Auto-Split (MANDATORY)