jinhak-ai-standard 2.7.0 → 3.7.0

package/.claude/scripts/cleanup-nul.cjs

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+
+/**
+ * PostToolUse Hook — Windows nul 파일 자동 삭제
+ *
+ * Windows에서 `> nul` 리다이렉션 사용 시 예약 디바이스 이름 충돌로
+ * 실제 `nul` 파일이 생성되는 문제를 방지합니다.
+ * \\?\ prefix로 Windows 예약어를 우회하여 삭제합니다.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const nulPath = '\\\\?\\' + path.resolve('nul');
+
+try {
+  fs.unlinkSync(nulPath);
+} catch {
+  // 파일이 없으면 무시
+}

package/.claude/scripts/commit-guard.cjs

@@ -0,0 +1,82 @@
+#!/usr/bin/env node
+/**
+ * commit-guard.cjs
+ *
+ * PreToolUse Hook — git commit 실행 시 JINHAK 표준 커밋 형식을 검증합니다.
+ *
+ * 검증 항목:
+ * 1. 커밋 메시지가 <type>: <한글 설명> 형식인가
+ * 2. Co-Authored-By 태그가 포함되어 있는가
+ * 3. /commit 스킬을 통하지 않은 직접 커밋이면 경고
+ *
+ * Hook 결과:
+ * - exit 0 + stdout 비어있음 → 통과 (아무 출력도 안 하면 통과)
+ * - exit 0 + stdout에 메시지 → 경고 표시 (진행은 됨)
+ * - exit 2 → 차단 (커밋 실행 불가)
+ */
+'use strict';
+
+const VALID_TYPES = ['feat', 'fix', 'docs', 'style', 'refactor', 'test', 'chore'];
+const TYPE_PATTERN = new RegExp(`^(${VALID_TYPES.join('|')}):\\s*.+`);
+const CO_AUTHOR_PATTERN = /Co-Authored-By:/i;
+
+// Hook에서 전달받는 환경변수/인자에서 커밋 메시지 추출
+const input = process.env.CLAUDE_TOOL_INPUT || process.argv.slice(2).join(' ');
+
+// git commit 명령인지 확인
+if (!input.includes('git commit') && !input.includes('git -c') ) {
+  // git commit이 아니면 무시
+  process.exit(0);
+}
+
+// 커밋 메시지 추출 시도
+let commitMsg = '';
+
+// -m "메시지" 또는 -m '메시지' 패턴
+const mFlag = input.match(/-m\s+["']([\s\S]*?)["']/);
+if (mFlag) {
+  commitMsg = mFlag[1];
+}
+
+// HEREDOC 패턴: -m "$(cat <<'EOF' ... EOF )"
+const heredoc = input.match(/cat\s*<<['"]?EOF['"]?\n([\s\S]*?)\nEOF/);
+if (heredoc) {
+  commitMsg = heredoc[1];
+}
+
+if (!commitMsg) {
+  // 메시지를 파싱할 수 없으면 경고만
+  console.log('⚠️ [commit-guard] 커밋 메시지를 파싱할 수 없습니다. /commit 스킬 사용을 권장합니다.');
+  process.exit(0);
+}
+
+// 첫 줄(subject) 추출
+const subject = commitMsg.split('\n')[0].trim();
+const errors = [];
+
+// 1. type: 한글 형식 검증
+if (!TYPE_PATTERN.test(subject)) {
+  errors.push(`커밋 메시지 형식 위반: "${subject}"`);
+  errors.push(`  필수 형식: <type>: <한글 설명>`);
+  errors.push(`  유효 type: ${VALID_TYPES.join(', ')}`);
+}
+
+// 2. Co-Authored-By 검증
+if (!CO_AUTHOR_PATTERN.test(commitMsg)) {
+  errors.push(`Co-Authored-By 태그 누락`);
+  errors.push(`  필수: Co-Authored-By: Claude <noreply@anthropic.com>`);
+}
+
+if (errors.length > 0) {
+  console.log('');
+  console.log('❌ [commit-guard] JINHAK 커밋 표준 위반:');
+  errors.forEach(e => console.log(`   ${e}`));
+  console.log('');
+  console.log('💡 /commit 스킬을 사용하면 자동으로 표준에 맞는 커밋이 생성됩니다.');
+  console.log('');
+  // exit 2 = 차단
+  process.exit(2);
+}
+
+// 통과 — 아무것도 출력하지 않음
+process.exit(0);

package/.claude/scripts/npm-tag-guard.cjs

@@ -0,0 +1,85 @@
+#!/usr/bin/env node
+/**
+ * npm Tag Guard Hook
+ *
+ * git push 시점에 package.json 버전이 변경되었는데
+ * 해당 버전의 git tag가 없으면 push를 차단합니다.
+ *
+ * 이 프로젝트는 npm 패키지(jinhak-ai-standard)이므로
+ * 버전 변경 시 반드시 태그를 생성해야 npm publish가 트리거됩니다.
+ */
+
+const { execSync } = require('child_process');
+
+// push 명령이 아니면 무시
+const command = process.env.command || '';
+if (!command.includes('push')) {
+  process.exit(0);
+}
+
+try {
+  const pkg = require('../../package.json');
+  const version = pkg.version;
+  const tagName = `v${version}`;
+
+  // 해당 버전의 태그가 존재하는지 확인
+  let tagExists = false;
+  try {
+    execSync(`git tag -l "${tagName}"`, { encoding: 'utf-8' }).trim();
+    const result = execSync(`git tag -l "${tagName}"`, { encoding: 'utf-8' }).trim();
+    tagExists = result === tagName;
+  } catch {
+    tagExists = false;
+  }
+
+  if (tagExists) {
+    // 태그가 이미 push되었는지 확인
+    let tagPushed = false;
+    try {
+      const remoteTag = execSync(`git ls-remote --tags origin "refs/tags/${tagName}"`, { encoding: 'utf-8' }).trim();
+      tagPushed = remoteTag.length > 0;
+    } catch {
+      tagPushed = false;
+    }
+
+    if (!tagPushed) {
+      console.log(`[npm Guard] ⚠️ 태그 ${tagName}가 로컬에 있지만 원격에 push되지 않았습니다.
+
+이 프로젝트는 npm 패키지이므로 태그를 push해야 npm publish가 트리거됩니다.
+코드 push 후 반드시 실행하세요:
+  git push origin ${tagName}`);
+    }
+    process.exit(0);
+  }
+
+  // 태그가 없음 — 버전이 원격의 최신 태그와 다른지 확인
+  let latestRemoteTag = '';
+  try {
+    latestRemoteTag = execSync('git describe --tags --abbrev=0 2>/dev/null', { encoding: 'utf-8' }).trim();
+  } catch {
+    // 태그가 하나도 없는 경우
+    latestRemoteTag = '';
+  }
+
+  const latestVersion = latestRemoteTag.replace(/^v/, '');
+
+  if (version !== latestVersion) {
+    // 버전이 변경되었는데 태그가 없음 → 차단
+    console.log(`[npm Guard] 🚫 PUSH 차단 — package.json 버전(${version})에 대한 태그(${tagName})가 없습니다!
+
+이 프로젝트는 npm 패키지(jinhak-ai-standard)입니다.
+버전을 올렸으면 반드시 태그를 생성하고 함께 push해야 합니다.
+
+필요한 명령:
+  git tag ${tagName}
+  git push origin master ${tagName}
+
+태그 없이 push하면 npm에 새 버전이 배포되지 않습니다.
+반드시 태그를 먼저 생성한 후 push를 진행하세요.`);
+    process.exit(1);
+  }
+
+} catch (e) {
+  // 스크립트 오류 시 push를 막지 않음
+  process.exit(0);
+}

package/.claude/scripts/readme-guard.cjs

@@ -0,0 +1,99 @@
+#!/usr/bin/env node
+/**
+ * README Guard Hook
+ *
+ * git commit 시점에 README.md 업데이트 누락을 감지합니다.
+ * PreToolUse (Bash - git commit) 에서 실행됩니다.
+ *
+ * 동작:
+ * 1. staged 파일 목록을 확인
+ * 2. "중요 파일"이 변경되었는데 README.md가 staged에 없으면 경고
+ * 3. additionalContext로 Claude에게 README 업데이트를 요청
+ */
+
+const { execSync } = require('child_process');
+
+// 커밋 명령이 아니면 무시
+const command = process.env.command || '';
+if (!command.includes('commit')) {
+  process.exit(0);
+}
+
+try {
+  // staged 파일 목록
+  const staged = execSync('git diff --cached --name-only', { encoding: 'utf-8' })
+    .trim()
+    .split('\n')
+    .filter(Boolean);
+
+  if (staged.length === 0) {
+    process.exit(0);
+  }
+
+  // README.md가 이미 staged에 포함되어 있으면 OK
+  const readmeIncluded = staged.some(f =>
+    f.toLowerCase() === 'readme.md'
+  );
+
+  if (readmeIncluded) {
+    process.exit(0);
+  }
+
+  // README 업데이트가 필요할 수 있는 "중요 변경" 패턴
+  const significantPatterns = [
+    // 구조/설정 변경
+    /^CLAUDE\.md$/,
+    /^CHANGELOG\.md$/,
+    /^RELEASE_NOTES\.md$/,
+    /^QUICK_START_PROMPT\.md$/,
+    /^package\.json$/,
+    /^bin\//,
+    // 새 기능/스킬 추가
+    /^\.claude\/skills\//,
+    /^\.claude\/settings\.json$/,
+    /^\.claude\/scripts\//,
+    // 문서 구조 변경
+    /^templates\//,
+    /^security\//,
+    /^prompts\//,
+    // 주요 가이드 문서
+    /^VIBE_CODING_GUIDE\.md$/,
+    /^CODING_CONVENTIONS\.md$/,
+    /^ARCHITECTURE\.md$/,
+    /^PROJECT_STRUCTURE\.md$/,
+    /^SECURITY_ISMS\.md$/,
+    /^PROMPT-LIBRARY\.md$/,
+    /^PROMPT_LIBRARY_USAGE\.md$/,
+    // 스크립트/자동화
+    /^scripts\//,
+  ];
+
+  const significantChanges = staged.filter(file =>
+    significantPatterns.some(pattern => pattern.test(file))
+  );
+
+  if (significantChanges.length === 0) {
+    // 중요 변경이 아니면 무시
+    process.exit(0);
+  }
+
+  // 경고 출력 (additionalContext로 Claude에게 전달)
+  const fileList = significantChanges.map(f => `  - ${f}`).join('\n');
+
+  console.log(`[README Guard] ⚠️ README.md 업데이트 필요 가능성 감지
+
+다음 중요 파일이 변경되었지만 README.md가 커밋에 포함되지 않았습니다:
+${fileList}
+
+README.md에 반영이 필요한 변경인지 확인하세요.
+- 새 기능/스킬 추가 → README에 설명 추가
+- 버전 변경 → README 버전 번호 갱신
+- 구조 변경 → README 구조 설명 업데이트
+- 적용 방법 변경 → README 설치/적용 가이드 업데이트
+
+커밋을 진행하기 전에 사용자에게 README.md 업데이트 여부를 확인하세요.`);
+
+} catch (e) {
+  // git 명령 실패 시 조용히 무시 (hook이 커밋을 막지 않도록)
+  process.exit(0);
+}

package/.claude/scripts/session-briefing.cjs

@@ -126,3 +126,5 @@ output.push('');
 output.push('위 컨텍스트를 참고하여 이전 작업 맥락을 이어서 진행하세요.');
 
 console.log(output.join('\n'));
+
+try { require(require('path').join(require('os').homedir(), '.claude', 'scripts', 'retry-pending-records.cjs')); } catch(e) { /* 글로벌 스크립트 미설치 시 무시 */ }

package/.claude/settings.json

@@ -68,7 +68,34 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node scripts/security-check-hook.cjs"
+            "command": "node \"$(git rev-parse --show-toplevel)/scripts/security-check-hook.cjs\""
+          }
+        ]
+      },
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node .claude/scripts/readme-guard.cjs"
+          }
+        ]
+      },
+      {
+        "matcher": "Bash(git*commit*)",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node .claude/scripts/commit-guard.cjs"
+          }
+        ]
+      },
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node .claude/scripts/npm-tag-guard.cjs"
           }
         ]
       }
@@ -101,7 +128,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node scripts/session-end-reminder.cjs"
+            "command": "node \"$(git rev-parse --show-toplevel)/scripts/session-end-reminder.cjs\""
           }
         ]
       }

package/.claude/skills/apply-standard/SKILL.md

@@ -141,7 +141,7 @@ Auto Memory가 활성화되어 있습니다.
 
 > **중요**: `deny` 규칙은 프로젝트 전체에 **강제 적용**됩니다. `settings.local.json`이나 `~/.claude/settings.json`으로 우회할 수 없으므로, 위험 명령 차단에 가장 확실한 방법입니다. `deny`가 `allow`보다 우선합니다.
 
-> Hook은 Node.js 기반으로 작성되어 OS별 변환이 필요 없습니다. Windows/macOS/Linux 모두 동일한 설정을 사용합니다.
+> Hook은 bash 셸에서 실행됩니다. Unix 문법을 사용할 수 있으며, Windows 전용 문법(`> nul`, `powershell`)만 피하면 OS 무관하게 동작합니다.
 
 **Scripts 복사** - 표준 저장소의 세션 브리핑 스크립트를 복사:
 - `/tmp/jinhak-standards/.claude/scripts/session-briefing.cjs` → `.claude/scripts/session-briefing.cjs`

package/.claude/skills/code-garden/SKILL.md

@@ -0,0 +1,112 @@
+---
+name: code-garden
+description: 코드 품질 점검 및 엔트로피 관리 — 아키텍처 린트, 중복 코드, 복잡도 급증, 미사용 코드 탐지
+---
+
+# /code-garden
+
+코드 품질을 종합 점검하고 엔트로피(코드 복잡도 증가)를 관리합니다.
+
+## 사용법
+
+```
+/code-garden [옵션]
+```
+
+**옵션:**
+- `--check <type>`: 특정 검사만 실행 (`duplicates`, `complexity`, `unused`, `grade`, `all`)
+- `--dir <path>`: 대상 디렉토리 지정
+- `--auto-fix`: 자동 수정 안내 포함
+- (기본: 전체 검사 + 리포트 출력)
+
+## 절차
+
+### 1단계: 도구 실행
+
+`tools/code-garden/` 도구를 실행하여 코드 품질 지표를 수집합니다.
+
+```bash
+# 전체 검사
+cd tools/code-garden && node dist/index.js --check all --dir <프로젝트_루트>
+
+# 개별 검사
+node dist/index.js --check duplicates --dir <프로젝트_루트>
+node dist/index.js --check complexity --dir <프로젝트_루트>
+node dist/index.js --check unused --dir <프로젝트_루트>
+node dist/index.js --check grade --dir <프로젝트_루트>
+```
+
+수집 항목:
+1. **중복 코드 탐지** — 10줄 이상, 85%+ 유사도 코드 블록 탐지
+2. **복잡도 급증 감지** — 최근 7일 대비 50%+ 복잡도 증가 파일
+3. **미사용 코드 탐지** — export 했지만 다른 파일에서 import하지 않는 심볼
+4. **품질 등급 산정** — 도메인(디렉토리)별 A~D 등급
+
+### 2단계: 결과 분석 + 등급 산정
+
+도구 출력 결과를 분석하여 도메인별 등급을 확인합니다.
+
+| 등급 | 기준 |
+|------|------|
+| A | 린트 에러 0, 복잡도 낮음, 중복 코드 없음 |
+| B | 린트 에러 5개 미만, 복잡도 중간 이하 |
+| C | 린트 에러 10개 미만 |
+| D | 위 기준 미달 |
+
+분석 포인트:
+- 등급이 하락한 도메인이 있는지 확인
+- 복잡도 급증 파일의 원인 파악 (대규모 기능 추가? 리팩토링 필요?)
+- 중복 코드가 공통 모듈로 추출 가능한지 검토
+- 미사용 export가 의도적인지(향후 사용 예정) 확인
+
+### 3단계: 리포트 출력
+
+결과를 사용자에게 보고합니다. 형식:
+
+```
+## 코드 품질 리포트 (YYYY-MM-DD)
+
+### 전체 요약
+- 전체 등급: X
+- 총 파일 수: N
+- 중복 코드: N건
+- 복잡도 급증: N건
+- 미사용 export: N건
+
+### 도메인별 등급
+| 도메인 | 등급 | 상세 |
+|--------|------|------|
+| ... | ... | ... |
+
+### 주요 이슈
+1. ...
+2. ...
+
+### 권장 조치
+- ...
+```
+
+`docs/quality/grades.md`를 도구 출력의 Markdown 리포트로 업데이트합니다.
+
+### 4단계: 자동 수정 (--auto-fix 옵션 시)
+
+`--auto-fix` 옵션이 지정된 경우, 자동 수정 가능한 항목을 안내합니다:
+
+- **중복 코드**: 공통 함수/유틸로 추출할 위치 제안
+- **미사용 export**: `export` 키워드 제거 또는 파일 삭제 제안
+- **복잡도 급증**: 함수 분리, 조건문 단순화 등 리팩토링 제안
+
+자동 수정은 직접 코드를 변경하며, 변경 전 확인을 요청합니다.
+
+## 도구 경로
+
+- **도구 위치**: `tools/code-garden/`
+- **빌드**: `cd tools/code-garden && npm run build`
+- **테스트**: `cd tools/code-garden && npm test`
+- **CLI**: `node tools/code-garden/dist/index.js`
+
+## 참고
+
+- `docs/quality/grades-template.md` — 등급 문서 템플릿
+- `docs/quality/tech-debt-template.md` — 기술 부채 추적 템플릿
+- `docs/quality/daily-report-template.md` — 일일 리포트 템플릿

package/.claude/skills/debug/SKILL.md

@@ -24,6 +24,11 @@ $ARGUMENTS - 버그 증상 또는 에러 메시지 (필수)
 
 ---
 
+## 사전 참조
+
+- `docs/standards/clarification-protocol.md` — 에러 정보가 부족하면 HIGH/MEDIUM 판정 후 질문
+- `docs/standards/difficulty-guide.md` — 버그 복잡도에 따라 Phase 깊이 조절 (Simple 버그는 Phase 2에서 바로 수정 가능)
+
 ## 실행 절차 (4단계, 순서 엄수)
 
 ### Phase 1: 증상 수집 (Observe)

package/.claude/skills/deep-plan/SKILL.md

@@ -26,14 +26,47 @@ $ARGUMENTS - 구현할 기능/작업에 대한 설명 (필수)
 
 > 간단한 작업은 Plan 모드(`EnterPlanMode`)로 충분합니다. `/deep-plan`은 **계획 자체의 품질 검증**이 필요할 때 사용합니다.
 
+## 적응적 추천 (Auto-Suggest)
+
+Plan 모드(`EnterPlanMode`) 진입 후 코드베이스를 탐색하면서 다음 조건 중 2개 이상 해당되면 `/deep-plan` 사용을 **추천**합니다. 최종 결정은 사용자에게 맡깁니다.
+
+**복잡도 판정 기준:**
+- 수정 대상 파일 5개 이상
+- 2가지 이상 구현 방식 선택이 필요
+- Human-in-the-Loop 필수 영역 해당 (인증/인가, 결제/정산, 개인정보, 암호화, 인프라, 마이그레이션)
+- 신규 모듈/서비스 생성 포함
+
+**추천 흐름:**
+```
+EnterPlanMode → 코드베이스 탐색 (Glob, Grep, Read)
+    ↓
+[복잡도 판정: 위 기준 2개+ 해당?]
+    ├─ 예 → "이 작업은 L3 이상 복잡도입니다. `/deep-plan`으로 심층 계획을 수립하시겠습니까?"
+    │       → 사용자 승인 → `/deep-plan` 전환
+    │       → 사용자 거절 → 일반 Plan 모드 계속
+    └─ 아니오 → 일반 Plan 모드 진행
+```
+
+**핵심: 추천은 하되 강제하지 않는다.** 사용자가 거절하면 일반 Plan 모드로 진행한다.
+
 ---
 
 ## 실행 절차
 
 ### 0단계: 사전 분석 및 요구사항 정제
 
-1. 사용자의 요청(`$ARGUMENTS`)을 분석하여 **명시적 요구사항**과 **암묵적 요구사항** 분리
-2. **작업 유형 태그 자동 분류:**
+> **필수 참조**: 이 단계에서 `docs/standards/prompt-structure.md`(4요소 구조), `docs/standards/clarification-protocol.md`(불확실성 대응)를 적용합니다.
+
+1. 사용자의 요청(`$ARGUMENTS`)을 **4요소 프레임워크**로 분석:
+   - **Goal**: 명시적 요구사항과 암묵적 요구사항 분리
+   - **Context**: 관련 코드베이스 탐색 (Glob, Grep, Read)
+   - **Constraints**: CLAUDE.md 절대 규칙 + 작업 유형별 제약
+   - **Done When**: 검증 가능한 완료 기준 도출
+2. **불확실성 판정** (`docs/standards/clarification-protocol.md`):
+   - LOW → 가정 기록 후 진행
+   - MEDIUM → 옵션 제시 + 사용자 선택
+   - HIGH → 질문 후 답변 받을 때까지 대기
+3. **작업 유형 태그 자동 분류:**
 
 | 태그 | 해당 조건 | Critic 가중치 영향 |
 |------|----------|-------------------|
@@ -44,10 +77,6 @@ $ARGUMENTS - 구현할 기능/작업에 대한 설명 (필수)
 | `비즈니스` | 핵심 도메인 로직, 결제/정산 | C6 가중 ×1.5, C4 가중 ×1.5 |
 | `일반` | 위에 해당하지 않는 경우 | 기본 가중치 (모두 ×1.0) |
 
-3. 모호하거나 결정이 필요한 부분이 있으면 `AskUserQuestion`으로 먼저 확인:
-   - 기술적 선택지 (예: JWT vs 세션, Redis vs 인메모리)
-   - 범위 확인 (어디까지 포함하는가)
-   - 우선순위 (성능 vs 구현 속도 vs 유지보수성)
 4. 관련 코드베이스 탐색 (Glob, Grep, Read)으로 현재 상태 파악
 
 ### 1단계: 팀 구성
@@ -217,20 +246,6 @@ Task({
 - 라운드 간 가중 비율 개선이 **+5%p 미만**이면 → 정체로 판단, 사용자 위임
 - 3라운드 초과 시 → 전체 계획 + 비평 이력을 사용자에게 제시하고 판단 위임
 
-**NightBuilder 환경 분기:**
-
-NightBuilder(무인 자동 개발) 환경에서 3라운드 내 미수렴 시:
-1. 현재까지의 계획서 + 비평 이력을 `.ai/PENDING_PLANS.md`에 저장:
-   ```markdown
-   ## [보류] YYYY-MM-DD HH:mm - [작업요약]
-   - 상태: 미수렴 (라운드 N, 가중 비율 NN.N%)
-   - C6 Hard Gate: 통과/실패/해당없음
-   - 저장된 계획서: `.ai/plans/YYYY-MM-DD_HHmm_[작업요약].md`
-   - 사유: [정체/라운드 초과/C6 Hard Gate 실패]
-   ```
-2. 다음 태스크로 진행 (교착 방지)
-3. 다음 세션(사람 참여) 시 `session-briefing.cjs`가 보류 건을 감지하여 안내
-
 **재작성 지시 시:**
 ```
 SendMessage({
@@ -452,7 +467,7 @@ TeamDelete()
 - Planner와 Critic은 **읽기 전용** 에이전트 (Plan 타입) — 코드를 직접 수정하지 않음
 - Plan 타입이 사용 불가능한 경우 Explore → general-purpose(파일 수정 금지 지시) 순으로 폴백
 - 비평은 냉혹하게 하되, **건설적인 대안**을 반드시 제시
-- 3라운드 내 수렴하지 않으면 무한 반복하지 않고 사용자에게 위임 (NightBuilder는 PENDING_PLANS.md 저장)
+- 3라운드 내 수렴하지 않으면 무한 반복하지 않고 사용자에게 위임
 - C6 Hard Gate는 보안/비즈니스 유형에서만 적용 — 일반 작업에 과도한 보안 검증을 강제하지 않음
 
 ---

package/.claude/skills/dependency-guardian/SKILL.md

@@ -0,0 +1,97 @@
+# dependency-guardian
+
+npm 패키지 설치 안전성을 검증합니다.
+
+## 트리거
+
+사용자가 새로운 npm 패키지를 설치하려 할 때, 또는 `npm install`, `pnpm add` 등 패키지 추가 명령 실행 전에 이 스킬을 실행합니다.
+
+## 데이터 소스 우선순위
+
+패키지 상태 조회 시 아래 순서로 시도합니다:
+
+### 1순위: JABIS API 실시간 조회
+- URL: `{JABIS_API_URL}/api/v1/packages/check/{packageName}?mode={mode}`
+- JABIS_API_URL은 프로젝트 CLAUDE.md의 `jabis_api_url` 설정에서 읽음
+- 타임아웃: 3초
+- 인증: JABIS JWT 토큰 (환경변수 `JABIS_API_TOKEN`)
+
+### 2순위: 로컬 캐시 (assets/cache/*.json)
+- `scripts/sync-jabis-cache.sh`로 주기적 동기화 (1일 1회 권장)
+- 캐시 유효기간: 24시간 (파일 수정 시간 기준)
+- 캐시 만료 시: "⚠️ JABIS 캐시가 24시간 이상 경과. sync-jabis-cache.sh 실행을 권장합니다."
+
+### 3순위: 정적 파일 fallback
+- `assets/BLOCKLIST.md`, `assets/ALLOWLIST_STRICT.md`
+- API와 캐시 모두 실패 시 최종 fallback
+- "⚠️ JABIS API 연결 불가. 정적 파일 기반 검사. 결과가 최신이 아닐 수 있습니다."
+
+### 자동 모드 감지
+- CLAUDE.md에 `jabis_api_url`이 없으면 → 정적 파일 모드로 동작 (기존 호환)
+- `dependency_guard_mode: strict` 또는 `standard` (기본: standard)
+
+## 실행 절차
+
+### Step 0: JABIS 레지스트리 조회
+1. JABIS API 호출 (또는 캐시/정적 파일 조회)
+2. 응답 status에 따른 판정:
+   - **BLOCKED** → 즉시 ❌ BLOCK. reason과 alternative 표시. 이후 Step 스킵.
+   - **RECOMMENDED/ALLOWED** → 즉시 ✅ PASS. 이후 Step 스킵.
+   - **CAUTION** → ⚠️ WARN 후 Step 1~3 추가 검증 진행.
+   - **UNREGISTERED** → Step 1~3 일반 검사 플로우 진행.
+   - API 실패 → fallback 후 Step 1~3 진행.
+3. STRICT 모드 + UNREGISTERED → 즉시 ❌ BLOCK:
+   "STRICT 모드에서 미등록 패키지는 설치 불가. JABIS 패키지 레지스트리에서 승인 요청을 먼저 진행하세요."
+
+### Step 1: npm 메타데이터 검사
+패키지의 npm 레지스트리 메타데이터를 확인합니다:
+- 주간 다운로드 수 (1,000 미만 → 위험)
+- 최종 발행일 (2년 초과 → 위험)
+- 메인테이너 수 (1명 → 위험)
+- install 스크립트 존재 여부
+
+`references/check-package.md` 참조.
+
+### Step 2: 취약점 검사
+- `npm audit` 결과 확인
+- Critical/High 취약점 → BLOCK
+- Moderate → WARN
+
+### Step 3: risk_score 계산
+`references/scoring-criteria.md`의 기준으로 0~100 점수 산출.
+
+## 결과 출력 형식
+
+```
+📦 패키지: {name}@{version}
+🔒 모드: STRICT | STANDARD
+📡 소스: JABIS API | 로컬 캐시 ({N}시간 전) | 정적 파일 (fallback)
+━━━━━━━━━━━━━━━━━━━━━━━━━━━
+✅ PASS | ⚠️ WARN | ❌ BLOCK
+
+📊 위험도: {score}/100
+📋 사유: {reason}
+🔄 대안: {alternative} (BLOCK/CAUTION 시)
+```
+
+## Lock 파일 전수 검사
+
+`/dependency-guardian audit` 명령으로 package-lock.json 전체 패키지를 검사합니다.
+- JABIS bulk-check API 활용 (가능한 경우)
+- `references/audit-lockfile.md` 참조.
+
+
+## CLAUDE.md 설정 예시
+
+```markdown
+## Dependency Guardian 설정
+dependency_guard_mode: strict
+jabis_api_url: https://jabis.jinhakapply.com
+jabis_api_token: ${JABIS_API_TOKEN}
+```
+
+## 참조 문서
+- `references/check-package.md` — 단일 패키지 검사 상세
+- `references/audit-lockfile.md` — Lock 파일 전수 검사
+- `references/scoring-criteria.md` — risk_score 계산 기준
+- `references/jabis-api-guide.md` — JABIS API 연동 가이드