oh-my-customcode 0.139.0 → 0.141.0

package/README.md

@@ -13,7 +13,7 @@
 
 **[한국어 문서 (Korean)](./README_ko.md)**
 
-49 agents. 118 skills. 23 rules. One command.
+49 agents. 119 skills. 23 rules. One command.
 
 ```bash
 npm install -g oh-my-customcode && cd your-project && omcustom init
@@ -132,7 +132,7 @@ Each agent declares its tools, model, memory scope, and limitations in YAML fron
 
 ---
 
-### Skills (118)
+### Skills (119)
 
 | Category | Count | Includes |
 |----------|-------|----------|
@@ -222,7 +222,7 @@ Key rules: R010 (orchestrator never writes files), R009 (parallel execution mand
 
 ---
 
-### Guides (53)
+### Guides (54)
 
 Reference documentation covering best practices, architecture decisions, and integration patterns. Located in `guides/` at project root, covering topics from agent design to CI/CD to observability.
 
@@ -272,14 +272,14 @@ your-project/
 ├── CLAUDE.md                   # Entry point
 ├── .claude/
 │   ├── agents/                 # 49 agent definitions
-│   ├── skills/                 # 118 skill modules
+│   ├── skills/                 # 119 skill modules
 │   ├── rules/                  # 22 governance rules (R000-R021)
 │   ├── hooks/                  # 15 lifecycle hook scripts
 │   ├── schemas/                # Tool input validation schemas
 │   ├── specs/                  # Extracted canonical specs
 │   ├── contexts/               # 4 shared context files
 │   └── ontology/               # Knowledge graph for RAG
-└── guides/                     # 50 reference documents
+└── guides/                     # 54 reference documents
 ```
 
 ---

package/dist/cli/index.js

@@ -2334,7 +2334,7 @@ var init_package = __esm(() => {
     workspaces: [
       "packages/*"
     ],
-    version: "0.139.0",
+    version: "0.141.0",
     description: "Batteries-included agent harness for Claude Code",
     type: "module",
     bin: {

package/dist/index.js

@@ -2014,7 +2014,7 @@ var package_default = {
   workspaces: [
     "packages/*"
   ],
-  version: "0.139.0",
+  version: "0.141.0",
   description: "Batteries-included agent harness for Claude Code",
   type: "module",
   bin: {

package/package.json

@@ -3,7 +3,7 @@
   "workspaces": [
     "packages/*"
   ],
-  "version": "0.139.0",
+  "version": "0.141.0",
   "description": "Batteries-included agent harness for Claude Code",
   "type": "module",
   "bin": {

package/templates/.claude/skills/adversarial-review/SKILL.md

@@ -79,6 +79,27 @@ Fix: Recommended remediation
 - [ ] Are domain boundaries respected (backend agent not editing frontend files)?
 - [ ] Could an agent's task contract be tightened without losing functionality?
 
+## CRG Integration (Optional Token-Efficiency)
+
+공격 표면 분석에 `crg-integration` 스킬을 우선 호출하여 트러스트 boundary를 빠르게 매핑한다:
+
+| Phase | CRG Tool | Purpose |
+|-------|----------|---------|
+| Attack surface | `get_impact_radius` | 보안 변경의 영향 추적 (recall-우선) |
+| Caller analysis | `query_graph` | 신뢰 boundary 함수의 모든 caller 추적 |
+| Diff focus | `get_minimal_context` | 보안 변경의 최소 review unit |
+| Regression detect | `detect_changes` | 보안 의미 변경 감지 |
+
+### Fallback (CRG 미설치 시)
+
+CRG MCP 미연결 시 sec-codeql-expert + grep 조합으로 fallback. CRG의 recall-우선 특성 보완 위해 sec-codeql-expert (precision-우선)와 병행 권장.
+
+### R013 Ecomode 정합
+
+대규모 변경 PR (>50 lines) 또는 context >= 60% 시 CRG 호출 권장.
+
+Refs: #1171 (CRG 통합), #1180 (본 cross-ref 추가)
+
 ## Permission Mode
 
 When spawning agents via the Agent tool during this skill's execution, always pass `mode: "bypassPermissions"`. The Agent tool default (`acceptEdits`) overrides agent frontmatter `permissionMode`, causing permission prompts during unattended execution.

package/templates/.claude/skills/dev-review/SKILL.md

@@ -137,6 +137,30 @@ Reference: `feedback_sensitive_path_tmp_bypass.md`, R006 sensitive-path handling
    ```
    The review agent creates the directory and writes the artifact before returning results (R010 compliance).
 
+## CRG Integration (Optional Token-Efficiency)
+
+`crg-integration` 스킬이 사용 가능한 경우 (MCP `code-review-graph` 연결 시), 리뷰 시작 전 먼저 호출하여 토큰 비용을 절감한다:
+
+| Phase | CRG Tool | Purpose |
+|-------|----------|---------|
+| Pre-review | `get_impact_radius` | 변경 영향 범위 사전 파악 (recall-우선) |
+| Search | `query_graph` | AST 기반 호출자/피호출자 추적 |
+| Diff analysis | `get_minimal_context` | 변경 코드의 최소 컨텍스트 |
+| Semantic check | `detect_changes` | 두 시점 의미적 차이 |
+
+### Fallback (CRG 미설치 시)
+
+CRG MCP 미연결 시 자동 fallback:
+1. grep/Grep 도구로 영향 범위 추적
+2. `claude-mem:smart-explore` (Phase β 이후 deprecated)
+3. 전체 디렉토리 읽기 (R013 ecomode 트리거 가능성)
+
+### R013 Ecomode 정합
+
+context >= 60% 시 CRG 호출 적극 권장. 8.2× 토큰 절감 (`guides/token-efficiency/crg.md` 벤치마크).
+
+Refs: #1171 (CRG 통합), #1180 (본 cross-ref 추가)
+
 ## Agent Selection
 
 | File Extension | Agent | Skill |

package/templates/.claude/skills/semble-integration/SKILL.md

@@ -0,0 +1,169 @@
+---
+name: semble-integration
+description: Semble (MinishLab) MCP wrapper — semantic code search via embeddings (98% token reduction vs grep+read, NDCG@10=0.854)
+scope: core
+version: 0.1.0
+user-invocable: true
+effort: low
+---
+
+# Semble Integration Skill
+
+[MinishLab/semble](https://github.com/MinishLab/semble) MCP 서버의 의미 기반 코드 검색 도구를 노출하는 wrapper 스킬.
+코드 인식 청킹 + 정적 임베딩 + BM25 + RRF 조합으로 transformer 수준 정확도를 CPU에서 달성한다.
+
+## 목적
+
+- **~98% 토큰 절감** (grep+Read 대비): 전체 파일 읽기 없이 의미적으로 관련된 코드 청크만 반환
+- **의미 기반 검색**: 자연어 쿼리로 "비슷한 코드 찾기", "에러 핸들링 패턴 검색" 등 구조 검색이 어려운 작업에 특화
+- **NDCG@10 = 0.854**: transformer 모델 수준 정확도를 CPU 인덱싱 (~250ms), 쿼리 (~1.5ms)로 달성
+- **R013 ecomode 보완**: context 사용량 ≥ 60% 시점에 Semble 호출로 추가 파일 읽기 비용 절감
+
+## CRG와의 보완 관계
+
+Semble과 CRG는 서로 다른 검색 축을 담당하며 상호 보완적이다.
+
+| 도구 | 검색 유형 | 강점 | 약점 |
+|------|----------|------|------|
+| `crg-integration` | 구조 (AST) | 호출 그래프, 영향 분석, recall-우선 | 의미 검색 약함 |
+| `semble-integration` | 의미 (임베딩) | 자연어 쿼리, "비슷한 코드 찾기" | 구조 정보 없음 |
+
+**사용 가이드**:
+- "이 함수의 caller는?" → CRG (`query_graph`)
+- "에러 핸들링 코드 패턴" → Semble
+- "변경 영향 범위" → CRG (`get_impact_radius`)
+- "인증 관련 코드 전부 찾기" → Semble (자연어 쿼리)
+
+## 노출 도구
+
+Semble MCP 서버가 제공하는 도구를 통해 다음 기능을 수행한다.
+구체적인 tool 이름은 MCP 서버 설치 후 Claude Code MCP introspection으로 확인한다.
+
+| 기능 | 설명 |
+|------|------|
+| 의미 검색 | 자연어 쿼리로 코드베이스 내 관련 청크 반환 |
+| 인덱싱 | 코드베이스를 code-aware 청킹 + 정적 임베딩으로 인덱싱 (CPU ~250ms) |
+| 결과 ranking | BM25 + RRF + embedding fusion으로 최종 랭킹 결정 |
+
+> 자세한 tool 사양은 `guides/token-efficiency/semble.md` 참조.
+
+## 설치 가이드
+
+> R001 정책: auto-install 스크립트 금지. 아래 명령어는 **사용자가 직접** 실행한다.
+
+### 1단계: 패키지 설치
+
+```bash
+# uv 기반 설치 (권장)
+uv tool install semble
+```
+
+### 2단계: MCP 서버 등록
+
+```bash
+# 방법 A: claude mcp 명령어 (권장)
+claude mcp add semble -- semble mcp
+
+# 방법 B: .mcp.json 수동 편집
+# 프로젝트 루트 또는 ~/.claude/.mcp.json 직접 수정
+```
+
+`.mcp.json` 수동 설정 예시:
+
+```json
+{
+  "mcpServers": {
+    "semble": {
+      "command": "semble",
+      "args": ["mcp"]
+    }
+  }
+}
+```
+
+auto-install hook 또는 스크립트로 `.mcp.json`을 자동 수정하는 방식은 R001 위반이다.
+
+### 3단계: 인덱싱
+
+```bash
+# 명시적 인덱싱 (선택 — 첫 MCP 호출 시 lazy 인덱싱도 가능)
+semble index
+```
+
+자세한 설치/설정 절차는 `guides/token-efficiency/semble.md` 참조.
+
+## 사용 패턴
+
+### 의미 기반 코드 검색
+
+```
+"인증 미들웨어 관련 코드 찾아줘"
+→ Semble 의미 검색 → 관련 청크 반환 → 전체 파일 읽기 없이 컨텍스트 주입
+```
+
+### 패턴 검색
+
+```
+"에러 핸들링 컨벤션이 어떻게 되어 있어?"
+→ Semble "error handling convention" 쿼리 → 패턴 예시 청크 반환
+```
+
+### dev-review/adversarial-review와 조합
+
+```
+1. Semble로 유사 패턴 사전 조사
+2. /dev-review {focused_files} → 범위를 좁힌 리뷰
+```
+
+### CRG와 결합 사용
+
+```
+1. Semble "authentication related code" → 관련 파일 목록 식별
+2. CRG get_impact_radius(identified_files) → 영향 범위 확인
+3. 두 결과를 조합하여 완전한 컨텍스트 구성
+```
+
+## R013 Ecomode와의 관계
+
+R013 ecomode가 자동 활성화되는 시점 (context 사용량 ≥ 60%)에서 Semble을 적극 활용한다:
+
+| Ecomode 상황 | Semble 활용법 |
+|-------------|--------------|
+| 광범위 grep 대신 | Semble 의미 검색 → 관련 청크만 추출 |
+| 파일 전체 읽기 대신 | Semble으로 관련 섹션만 수신 |
+| 패턴 파악 시 | Semble 쿼리 → 대표 예시만 수집 |
+
+## 다른 자산과의 관계
+
+### 보완 관계 (함께 사용)
+
+| 자산 | 조합 방식 |
+|------|----------|
+| `crg-integration` | Semble (의미) + CRG (구조) 결합으로 완전한 코드 이해 |
+| `dev-review` | Semble로 유사 패턴 사전 조사 → dev-review 입력 최적화 |
+| `adversarial-review` | Semble로 관련 보안 패턴 수집 → adversarial-review 컨텍스트 보강 |
+
+### 대체 후보 (일부 use case)
+
+| 기존 방식 | Semble 대체 가능 여부 |
+|----------|---------------------|
+| `claude-mem:smart-explore` 의 자연어 탐색 | 일부 대체 가능 — 구조 탐색은 CRG 유지 |
+| grep + Read 조합의 패턴 검색 | 대체 권장 (98% 토큰 절감) |
+
+## 트러블슈팅
+
+| 증상 | 원인 | 해결 |
+|------|------|------|
+| MCP 도구가 보이지 않음 | `.mcp.json` 미설정 또는 `claude mcp add` 미실행 | MCP 등록 확인, Claude Code 재시작 |
+| `command not found: semble` | uv tool install 미실행 또는 PATH 누락 | `uv tool install semble` 재실행, `which semble` 확인 |
+| 인덱싱 오류 | 초기 인덱싱 미완료 | `semble index` 실행 후 재시도 |
+| 검색 결과 없음 | 인덱싱 범위 외 또는 쿼리 불명확 | 인덱싱 재실행, 쿼리 구체화 |
+| 서버 연결 실패 | Semble MCP 서버 미실행 | MCP 서버 로그 확인, Claude Code 재시작 |
+| uv 미설치 | uv 패키지 매니저 없음 | `curl -LsSf https://astral.sh/uv/install.sh \| sh` (사용자 직접 실행) |
+
+## 참고
+
+- 상세 설치/설정: `guides/token-efficiency/semble.md`
+- 관련 이슈: #1173 (scout:integrate Semble)
+- 기술 출처: [MinishLab/semble](https://github.com/MinishLab/semble)
+- 보완 자산: `crg-integration` (구조 기반 검색)

package/templates/CLAUDE.md

@@ -117,11 +117,11 @@ project/
 +-- CLAUDE.md                    # 진입점
 +-- .claude/
 |   +-- agents/                  # 서브에이전트 정의 (49 파일)
-|   +-- skills/                  # 스킬 (117 디렉토리)
-|   +-- rules/                   # 전역 규칙 (R000-R022)
+|   +-- skills/                  # 스킬 (119 디렉토리)
+|   +-- rules/                   # 전역 규칙 (R000-R023)
 |   +-- hooks/                   # 훅 스크립트 (보안, 검증, HUD)
 |   +-- contexts/                # 컨텍스트 파일 (ecomode)
-+-- guides/                      # 레퍼런스 문서 (49 토픽)
++-- guides/                      # 레퍼런스 문서 (54 토픽)
 ```
 
 ## 오케스트레이션
@@ -246,6 +246,8 @@ Claude Code의 Agent Teams 기능이 활성화되어 있으면 (`CLAUDE_CODE_EXP
 | 서버 | 용도 |
 |------|------|
 | claude-mem | 세션 메모리 영속성 (Chroma 기반) |
+| code-review-graph | Token-efficient AST 기반 context retrieval (8.2× 토큰 절감) — wrapper: `crg-integration` 스킬 (#1171) |
+| semble | Semantic code search via embeddings (98% 토큰 절감, NDCG@10=0.854) — wrapper: `semble-integration` 스킬 (#1173) |
 
 ### 설치 명령어
 
@@ -261,6 +263,15 @@ Claude Code의 Agent Teams 기능이 활성화되어 있으면 (`CLAUDE_CODE_EXP
 # MCP 설정 (claude-mem)
 npm install -g claude-mem
 claude-mem setup
+
+# CRG MCP 설치 (token efficiency)
+pipx install code-review-graph
+# .mcp.json 에 code-review-graph 서버 수동 추가 (R001 auto-install 금지)
+
+# Semble MCP 설치 (semantic code search)
+uv tool install semble
+claude mcp add semble -- semble mcp
+# 또는 .mcp.json 수동 편집 (R001 auto-install 금지)
 ```
 
 <!-- omcustom:git-workflow -->

package/templates/README.md

@@ -48,14 +48,14 @@ templates/
 ├── manifest.json                    # 배포 컴포넌트 카운트 및 메타데이터
 ├── .claude/
 │   ├── agents/                      # 에이전트 정의 파일 (*.md, 49개)
-│   ├── skills/                      # 스킬 모듈 (각 디렉토리에 SKILL.md, 118개)
+│   ├── skills/                      # 스킬 모듈 (각 디렉토리에 SKILL.md, 119개)
 │   ├── rules/                       # 전역 규칙 (R000–R023, 23개)
 │   ├── hooks/
 │   │   ├── hooks.json               # 훅 이벤트 설정 (PreToolUse/PostToolUse 등)
 │   │   └── scripts/                 # 훅 셸 스크립트 (34개)
 │   ├── contexts/                    # 컨텍스트 설정 파일 (ecomode 등)
 │   └── ontology/                    # Ontology-RAG 지식 그래프
-└── guides/                          # 레퍼런스 문서 디렉토리 (50개)
+└── guides/                          # 레퍼런스 문서 디렉토리 (54개)
 ```
 
 ---
@@ -86,7 +86,7 @@ CI의 `verify-template-sync.sh`가 소스와 templates/ 간 일치를 검증합
 | Manager | 6 |
 | System | 4 |
 
-### Skills (118)
+### Skills (119)
 
 `.claude/skills/*/SKILL.md` — 재사용 가능한 스킬 모듈.
 
@@ -109,7 +109,7 @@ CI의 `verify-template-sync.sh`가 소스와 templates/ 간 일치를 검증합
 | `SHOULD` | 강력 권장 | R003 상호작용, R013 Ecomode |
 | `MAY` | 선택 | R005 최적화 |
 
-### Guides (51)
+### Guides (54)
 
 `guides/*/` — 레퍼런스 문서 디렉토리.
 

package/templates/guides/agentmemory-migration/measure-step-zero.md

@@ -0,0 +1,120 @@
+# AgentMemory 마이그레이션 — 단계 0: MEASURE (사용 빈도 측정)
+
+> **목적**: Phase 1 (COEXIST) 진입 전, claude-mem skill 실제 호출 빈도 데이터를 수집하여 가설 기반 자산 처리표를 검증한다.
+> **관련 이슈**: #1169 본문 조치 5
+> **참고 메모리**: `feedback_claude_mem_maintenance`, `project_sequencing_alpha_beta_gamma`
+
+---
+
+## 1. 목적
+
+AgentMemory 마이그레이션 계획(`feedback_claude_mem_maintenance.md`)에는 12개 claude-mem skill의 처리 방향이 가설로 기재되어 있다. 특히 폐기 후보 5종(`make-plan`, `do`, `babysit`, `wowerpoint`, `knowledge-agent`, `pathfinder`)은 "미사용 또는 저빈도"라는 가정 위에 놓여 있다.
+
+이 단계에서는 실측 데이터로 가설을 검증한다. 데이터 없이 Phase 1에 진입하면:
+- 실제로 자주 쓰이던 skill을 폐기하여 사용자 워크플로우가 깨질 수 있다.
+- 자산 처리표 재설계 비용이 Phase 2~3로 이월된다.
+
+---
+
+## 2. 실행 방법
+
+```bash
+# 기본 실행 (최근 7일, 리포트를 ~/.claude/measure-claude-mem-usage-YYYY-MM-DD.md 에 저장)
+bash scripts/measure-claude-mem-usage.sh
+
+# 최근 14일 스캔
+bash scripts/measure-claude-mem-usage.sh --days 14
+
+# 출력 경로 지정
+bash scripts/measure-claude-mem-usage.sh --output ~/Documents/claude-mem-usage.md
+
+# 헤더 없이 실행 (CI/파이프라인 삽입용)
+bash scripts/measure-claude-mem-usage.sh --quiet
+```
+
+### 스캔 대상 경로
+
+| 경로 | 설명 |
+|------|------|
+| `~/.claude-mem/archives/` | claude-mem MCP 아카이브 (`.jsonl`, `.json`) |
+| `~/.claude/projects/*/session-*.jsonl` | Claude Code 세션 로그 |
+
+둘 중 하나가 없어도 스크립트는 조용히 skip하고 나머지를 스캔한다.
+
+---
+
+## 3. 1주 수집 계획
+
+| 시점 | 작업 |
+|------|------|
+| **Day 1** | 첫 측정 — 베이스라인 (`--days 7` 기준 기존 archives 기반) |
+| **Day 4** | 중간 측정 — 추이 확인 (`--days 4`) |
+| **Day 7** | 최종 측정 — 자산 처리표 재검토 및 Phase 1 GO/NO-GO 결정 |
+
+세 시점 모두 `--output` 경로를 달리 지정하여 비교 가능한 파일로 보관한다:
+
+```bash
+bash scripts/measure-claude-mem-usage.sh --output ~/.claude/claude-mem-day1.md
+bash scripts/measure-claude-mem-usage.sh --days 4 --output ~/.claude/claude-mem-day4.md
+bash scripts/measure-claude-mem-usage.sh --days 7 --output ~/.claude/claude-mem-day7.md
+```
+
+---
+
+## 4. 해석 기준
+
+| 호출 수 | 신호 | 권장 조치 |
+|---------|------|----------|
+| **0** | 미사용 | 폐기 안전 — 1주 후 처리 결정 |
+| **1-3** | 가끔 사용 | wrapper 또는 대체 도구 매핑 필요 |
+| **4+** | 정기 사용 | 폐기 시 대체 도구 명확화 필수 |
+
+폐기 후보 5종 기준 예상:
+- `make-plan`, `do`, `babysit` → 0 예상 (native AgentMemory로 대체 완료)
+- `wowerpoint`, `knowledge-agent`, `pathfinder` → 0~1 예상 (특수 목적 skill)
+
+실측값이 예상과 다를 경우 자산 처리표를 수정한 후 Phase 1에 진입한다.
+
+---
+
+## 5. 결과 활용
+
+### 5-1. #1169에 리포트 첨부
+
+```bash
+gh issue comment 1169 --body-file ~/.claude/claude-mem-day7.md
+```
+
+### 5-2. 자산 처리표 갱신
+
+`.claude/agent-memory/sys-memory-keeper/feedback_claude_mem_maintenance.md` 내 "처리 방향" 열을 실측값 기반으로 업데이트한다.
+
+### 5-3. Phase 1 GO/NO-GO 결정
+
+| 조건 | 결정 |
+|------|------|
+| 폐기 후보 모두 호출 수 0 | GO — Phase 1 진입 |
+| 폐기 후보 중 1개 이상 호출 수 1-3 | CONDITIONAL GO — 대체 도구 매핑 완료 후 진입 |
+| 폐기 후보 중 1개 이상 호출 수 4+ | NO-GO — 처리표 재설계 후 재측정 |
+
+---
+
+## 6. 한계 및 주의사항
+
+| 항목 | 설명 |
+|------|------|
+| archives 미존재 | `~/.claude-mem/archives/` 없으면 카운트 0 (정상 — silent skip) |
+| 세션 로그 형식 변경 | Claude Code 업데이트로 `session-*.jsonl` 구조가 변경되면 grep 패턴 수정 필요 |
+| claude-mem MCP telemetry 미사용 | 외부 도구 의존 최소화 원칙에 따라 MCP 자체 지표는 사용하지 않음 |
+| grep 기반 측정 | 같은 파일에 skill 이름이 여러 줄 등장하면 복수 카운트됨 (과대 계산 가능성) |
+| macOS/Linux 호환 | `stat` 옵션 차이를 스크립트 내에서 자동 처리 (`-f %m` vs `-c %Y`) |
+
+---
+
+## 7. 참고
+
+- **이슈**: [#1169](../../.github/ — `gh issue view 1169`)
+- **자산 처리표**: `.claude/agent-memory/sys-memory-keeper/feedback_claude_mem_maintenance.md`
+- **시퀀싱 메모리**: `.claude/agent-memory/mgr-creator/project_sequencing_alpha_beta_gamma.md` (또는 해당 메모리 파일)
+- **스크립트**: `scripts/measure-claude-mem-usage.sh`
+- **Phase 1 가이드**: `guides/agentmemory-migration/` (이 디렉토리에 추가 예정)

package/templates/guides/token-efficiency/crg.md

@@ -159,7 +159,7 @@ AST 노드 그래프에 자연어 쿼리를 실행한다.
 2. /adversarial-review {minimal_context} → 보안/논리 취약점 검토
 ```
 
-<!-- TODO: 향후 cross-ref 추가 — adversarial-review 스킬 업데이트 시 -->
+> **Cross-ref**: `dev-review` 및 `adversarial-review` 스킬에 CRG 호출 패턴 통합됨 (v0.140.0, #1180).
 
 ### R013 Ecomode 활성 시
 

package/templates/guides/token-efficiency/semble.md

@@ -0,0 +1,188 @@
+# Semble 통합 가이드
+
+> **출처**: [MinishLab/semble](https://github.com/MinishLab/semble)
+> **관련 이슈**: #1173 (scout:integrate Semble)
+> **wrapper 스킬**: `.claude/skills/semble-integration/SKILL.md`
+
+## Semble 개요
+
+Semble은 [MinishLab](https://github.com/MinishLab)이 개발한 MCP(Model Context Protocol) 서버로, 코드 인식 청킹(Chonkie) + 정적 임베딩(Model2Vec potion-code-16M) + BM25 + RRF 조합으로 의미 기반 코드 검색을 제공한다.
+
+### 핵심 특성
+
+| 항목 | 값 |
+|------|-----|
+| 구현 | Python MCP server |
+| 청킹 엔진 | Chonkie (code-aware chunking) |
+| 임베딩 모델 | Model2Vec potion-code-16M (정적 임베딩) |
+| 검색 방식 | BM25 + RRF + embedding fusion |
+| GitHub | ~1.5k stars (2026-05 기준) |
+| 토큰 절감 | **~98%** (grep+Read 대비) |
+| 정확도 | NDCG@10 = **0.854** (transformer 모델 수준) |
+
+### R013 Ecomode 정합성
+
+Semble의 ~98% 토큰 절감은 R013 ecomode의 목표와 직접 정합한다. ecomode가 context 사용량 ≥ 60%에서 자동 활성화될 때, Semble 호출로 광범위한 grep+Read 비용을 대폭 줄일 수 있다.
+
+## 벤치마크 요약
+
+| 지표 | 값 | 비고 |
+|------|-----|------|
+| CPU 인덱싱 | ~250ms (레포당 평균) | GPU 불필요 |
+| 쿼리 응답 | ~1.5ms | 실시간 응답 수준 |
+| NDCG@10 | 0.854 | transformer 모델 대비 동급 |
+| 토큰 사용량 | ~98% 절감 | grep+Read 전략 대비 |
+
+> **출처**: #1173 이슈 본문 및 MinishLab/semble 공식 벤치마크
+
+### CRG와의 비교
+
+| 항목 | Semble | CRG (code-review-graph) |
+|------|--------|------------------------|
+| 검색 방식 | 의미 기반 (임베딩) | 구조 기반 (AST) |
+| 강점 | 자연어 쿼리, 패턴 유사성 | 호출 그래프, 의존성 분석 |
+| 약점 | 구조 정보 없음 | 의미 검색 약함 |
+| 토큰 절감 | ~98% (grep+Read 대비) | 8.2× |
+| 정확도 | NDCG@10 = 0.854 | precision 0.38 (recall-우선) |
+
+두 도구는 서로 다른 검색 축을 담당하며 결합 시 시너지 효과가 크다.
+
+## 설치
+
+> **R001 정책**: auto-install 스크립트 또는 hook 작성 금지. 아래 명령어는 개발자가 직접 실행한다.
+
+### 패키지 설치
+
+```bash
+# uv 기반 설치 (권장)
+uv tool install semble
+```
+
+uv가 없는 경우 먼저 설치한다 (사용자 직접 실행):
+
+```bash
+curl -LsSf https://astral.sh/uv/install.sh | sh
+```
+
+### MCP 서버 등록
+
+```bash
+# 방법 A: claude mcp 명령어 (권장)
+claude mcp add semble -- semble mcp
+
+# 방법 B: .mcp.json 수동 편집
+```
+
+`.mcp.json` 수동 설정 (프로젝트 루트 또는 `~/.claude/.mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "semble": {
+      "command": "semble",
+      "args": ["mcp"]
+    }
+  }
+}
+```
+
+**주의**: `.mcp.json`을 자동으로 수정하는 스크립트나 hook은 R001 위반이다. 반드시 수동 편집한다.
+
+설정 후 Claude Code를 재시작하면 MCP 도구가 활성화된다.
+
+### 설치 확인
+
+```bash
+# 바이너리 확인
+which semble
+
+# 버전 확인
+semble --version
+```
+
+## 인덱싱
+
+Semble은 첫 MCP 호출 시 lazy 인덱싱을 수행하지만, 대용량 코드베이스의 경우 명시적 인덱싱을 권장한다:
+
+```bash
+# 프로젝트 루트에서 실행
+semble index
+
+# 특정 경로만 인덱싱
+semble index --path src/
+```
+
+인덱싱은 로컬 캐시에 저장된다. `.gitignore`에 추가를 권장한다.
+
+## 사용 시나리오
+
+### 의미 검색 → Semble
+
+자연어 쿼리로 코드 의미를 파악해야 할 때 Semble을 사용한다:
+
+| 작업 | 도구 | 이유 |
+|------|------|------|
+| "인증 관련 코드 전부 찾기" | Semble | 자연어 의미 검색 |
+| "에러 핸들링 컨벤션 파악" | Semble | 패턴 유사성 검색 |
+| "이 로직과 비슷한 코드 찾기" | Semble | 의미 유사성 |
+| "데이터 직렬화 예시 수집" | Semble | 코드 패턴 검색 |
+
+### 구조 분석 → CRG
+
+코드 구조와 의존성을 파악해야 할 때 CRG를 사용한다:
+
+| 작업 | 도구 | 이유 |
+|------|------|------|
+| "이 함수의 caller는?" | CRG (`query_graph`) | AST 기반 호출 그래프 |
+| "변경 영향 범위 파악" | CRG (`get_impact_radius`) | 의존성 트리 분석 |
+| "PR 리뷰 전 변경 폭 파악" | CRG (`detect_changes`) | 의미적 diff |
+
+### 결합 사용 예시
+
+두 도구를 결합하면 의미 + 구조 양면에서 완전한 코드 이해가 가능하다:
+
+```
+1. Semble "authentication middleware" → 관련 파일 목록 식별
+2. CRG get_impact_radius(identified_files) → 영향 범위 확인
+3. Semble "auth error handling" → 에러 처리 패턴 수집
+4. /dev-review {focused_files} → 좁혀진 범위의 상세 리뷰
+```
+
+## R013 Ecomode 통합
+
+context ≥ 60%에서 광범위한 파일 읽기 대신 Semble을 우선 사용한다:
+
+| 기존 방식 | Semble 대체 |
+|----------|-----------|
+| `Grep(pattern, recursive)` + `Read(file)` | Semble 의미 검색 단일 호출 |
+| `Read(multiple_files[])` 패턴 파악 목적 | Semble 쿼리 → 관련 청크만 수신 |
+| grep으로 키워드 검색 후 파일 읽기 | Semble 자연어 쿼리로 직접 청크 추출 |
+
+## Explore 에이전트 힌트
+
+Explore 에이전트가 Semble MCP를 사용 가능한 환경에서는, 코드베이스 탐색 시 grep+Read 조합보다 Semble 의미 검색을 우선 호출하는 것을 권장한다.
+
+> Explore 에이전트 description 갱신은 별도 이슈로 추적 가능 (본 PR scope 외).
+
+## 트러블슈팅
+
+| 증상 | 원인 | 해결 방법 |
+|------|------|---------|
+| MCP 도구가 Claude Code에 보이지 않음 | `.mcp.json` 미설정 또는 `claude mcp add` 미실행 | MCP 등록 확인 후 Claude Code 재시작 |
+| `command not found: semble` | 패키지 미설치 또는 PATH 누락 | `uv tool install semble`, `which semble` 확인 |
+| uv 명령어 없음 | uv 미설치 | `curl -LsSf https://astral.sh/uv/install.sh \| sh` 실행 |
+| 첫 호출이 느림 | lazy 인덱싱 진행 중 | 정상 동작. `semble index`로 사전 인덱싱 권장 |
+| 검색 결과 없음 | 인덱싱 범위 외 또는 쿼리 불명확 | `semble index` 재실행, 쿼리 구체화 |
+| MCP 연결 실패 | Semble MCP 서버 미실행 | MCP 서버 로그 확인, `semble --version`으로 바이너리 확인 |
+| 인덱싱 실패 | 권한 문제 또는 코드베이스 경로 오류 | 실행 경로 확인, `semble index --path .` 시도 |
+
+## 참고 자료
+
+- **GitHub**: [MinishLab/semble](https://github.com/MinishLab/semble)
+- **wrapper 스킬**: `.claude/skills/semble-integration/SKILL.md`
+- **관련 이슈**: #1173 (scout:integrate Semble)
+- **보완 도구**: `guides/token-efficiency/crg.md` (구조 기반 검색)
+- **관련 규칙**:
+  - [[r001]] (MUST-safety.md): auto-install 금지 정책
+  - [[r013]] (SHOULD-ecomode.md): context budget 관리, ecomode 통합
+  - [[crg-integration]]: 구조 기반 검색 — 의미 검색 보완 대상

package/templates/manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.139.0",
+  "version": "0.141.0",
   "lastUpdated": "2026-05-18T00:00:00.000Z",
   "omcustomMinClaudeCode": "2.1.121",
   "omcustomMinClaudeCodeReason": "Sensitive-path direct Write/Edit on .claude/** under bypassPermissions (R010 deprecation, #1101)",
@@ -20,13 +20,13 @@
       "name": "skills",
       "path": ".claude/skills",
       "description": "Reusable skill modules (includes slash commands)",
-      "files": 118
+      "files": 119
     },
     {
       "name": "guides",
       "path": "guides",
       "description": "Reference documentation",
-      "files": 53
+      "files": 54
     },
     {
       "name": "hooks",