npx skills add https://github.com/supercent-io/skills-template --skill ai-tool-compliance

## Compliance Report
- Date: 2026-03-03
- Project: my-ai-tool
- Score: 92/100 (Green)

### Rule Results
| Rule ID | Rule Name | Result | Evidence |
|---------|-----------|--------|----------|
| AUTH-P0-001 | 신규 가입자 Guest 강제 | PASS | signup.ts:45 role='guest' |
| AUTH-P0-002 | Guest 메뉴/API 접근 차단 | PASS | middleware.ts:12 guestBlock |
| ... | ... | ... | ... |

### Score Breakdown
- 보안: 33/40
- 권한: 25/25
- 비용: 17/20
- 로그: 12/15
- Total: 92/100

### Gate Decision: GREEN - 배포 승인

/compliance-improve 실행
       |
  1. 최근 verification-run.json 로드
       |
  2. FAIL 항목 추출 (rule_id + evidence)
       |
  3. 각 FAIL에 대해:
       |
     a. evidence 파일:줄번호에서 위반 코드 Read
     b. rule.remediation + rule.check_pattern.must_contain에서 수정 방향 도출
     c. 변경 전/후 코드 diff 생성
     d. Write로 수정 적용 (사용자 확인 후)
     e. 해당 룰만 재검증 (Grep 패턴 재실행)
     f. PASS 전환 확인
       |
  4. 전체 재검증 (/compliance-verify)
       |
  5. Before/After 점수 비교 출력
       |
  6. 잔여 FAIL 없으면 → P1 권장 요건 도입 가이드 제시

1. Glob(check_targets) → 대상 파일 수집
2. grep_patterns 매칭 → 해당 기능 사용 파일 식별
   - 매칭 0건 → N/A (해당 기능 미사용, 패널티 없음)
3. must_not_contain 검사 (exclude_paths 제외)
   - 매칭 발견 → 즉시 FAIL + evidence 기록
4. must_contain 검사
   - 전체 충족 → PASS
   - 부분 충족 → WARNING
   - 미충족 → FAIL

SC-001: grep signup/register -> assert role='guest' -> grep guestBlock/guestDeny -> assert exists
SC-002: grep fetch(https://) in client -> assert 0 hits -> grep gateway log -> assert cost fields -> assert cache check
SC-003: grep firebase/firestore in client/ -> assert 0 hits -> grep authMiddleware in functions/ -> assert exists
SC-004: grep catch blocks -> assert logAction in each -> grep roleChange -> assert auditLog
SC-005: grep res.json for raw text -> assert 0 hits -> grep guest response -> assert no model/cost info

# Compliance Report

## 1. Summary (요약)
- 프로젝트명, 검증 일시, 검증 모드 (quick-scan / full-verify)
- 총 준수 점수 / 100
- 배포 게이트 등급 (Green / Yellow / Red)
- P0 FAIL 건수
- 검증 소요 시간

## 2. Rule Results (룰별 결과)
| Rule ID | Category | Rule Name | Result | Score | Evidence |
|---------|----------|-----------|--------|-------|----------|
| AUTH-P0-001 | 권한 | 신규 가입자 Guest 강제 | PASS | 10/10 | signup.ts:45 |
| SEC-P0-005 | 보안 | 외부 API Gateway 강제 | FAIL | 0/15 | client/api.ts:23 직접 fetch |
| ...

## 3. Score Breakdown (영역별 점수)
| 영역 | 획득 | 만점 | 비율 |
|------|------|------|------|
| 보안 | 20 | 40 | 50% |
| 권한 | 25 | 25 | 100% |
| 비용 | 17 | 20 | 85% |
| 로그 | 12 | 15 | 80% |
| **합계** | **79** | **100** | **79%** |

## 4. Failures Detail (실패 상세)
각 FAIL 항목에 대해:
- 위반 코드 위치 (파일:라인)
- 위반 내용 설명
- 권장 수정 방법 (remediation)
- 관련 검증 시나리오 ID (SC-001~SC-005)

## 5. Gate Decision (배포 판정)
- 판정 등급 + 판정 근거
- 필요한 승인 역할 목록
- 역할별 Go/No-Go 체크포인트 현황 (20개 중 미충족 항목 표시)

## 6. Recommendations (권고 사항)
- 즉시 조치: P0 FAIL 수정 (파일 경로 + 수정 가이드)
- 단기 개선: Yellow -> Green 달성 방안
- 중기 도입: P1 권장 요건 도입 순서

/compliance-verify 실행
       |
  11개 P0 룰 전수 검증
       |
  점수 산출 (보안+권한+비용+로그)
       |
  +----+----+----+
  |         |         |
Green     Yellow    Red
  |         |         |
자동 승인  PM 승인   배포 차단
  |       대기      |
  v         |      수정 후
배포       v      재검증
        PM 확인     |
        |    |      v
      승인  반려   /compliance-improve
        |    |
        v    v
      배포  수정 후
            재검증

project/
├── compliance/
│   ├── rbac-matrix.yaml          # 5역할 x 게임/메뉴/기능 권한 매트릭스
│   ├── rules/
│   │   └── p0-rules.yaml         # 11개 P0 룰 정의
│   ├── log-schema.yaml           # 행동 로그 스키마 (Firestore/BigQuery)
│   └── cost-tracking.yaml        # 비용 추적 필드 정의
├── compliance-config.yaml        # 프로젝트 메타 + 검증 설정
└── compliance-report.md          # 검증 결과 리포트 (verify 실행 시 생성)

project:
  name: "my-ai-tool"
  type: "web-app"           # web-app | api | mobile-app | library
  tech_stack: ["typescript", "firebase", "next.js"]

verification:
  catalog_path: "compliance/rules/p0-rules.yaml"   # 기본값
  exclude_paths:                                     # 검증 제외 경로
    - "node_modules/**"
    - "dist/**"
    - "**/*.test.ts"
    - "**/*.spec.ts"

scoring:
  domain_weights:            # 합계 = 100
    security: 40
    auth: 25
    cost: 20
    logging: 15

gate:
  green_threshold: 90        # 90점 이상 = 자동 승인
  yellow_threshold: 75       # 75~89점 = PM 확인 필요
  p0_fail_override: true     # P0 FAIL 시 점수 무관 Red 판정

log_schema:
  version: "1.0.0"
  storage:
    primary: "firestore"           # 실시간 접근용
    archive: "bigquery"            # 분석/감사용
    retention:
      hot: 90                      # 일 (Firestore)
      cold: 365                    # 일 (BigQuery)

  fields:
    - name: userId
      type: string
      required: true
    - name: action
      type: string
      required: true
      description: "수행 동작 (ai_call, role_change, login, etc.)"
    - name: timestamp
      type: timestamp
      required: true
    - name: model
      type: string
      required: false
      description: "AI 모델명 (gemini-1.5-flash 등)"
    - name: inputTokens
      type: number
      required: false
    - name: outputTokens
      type: number
      required: false
    - name: estimatedCost
      type: number
      required: false
      description: "USD 기준 예상 비용"
    - name: status
      type: string
      required: true
      enum: [success, fail, timeout, error]
    - name: errorMessage
      type: string
      required: false
    - name: metadata
      type: map
      required: false
      description: "추가 컨텍스트 (bytesProcessed, cacheHit 등)"

cost_tracking:
  version: "1.0.0"

  ai_models:
    required_fields:
      - model              # 모델 식별자
      - inputTokens        # 입력 토큰 수
      - outputTokens       # 출력 토큰 수
      - estimatedCost      # USD 예상 비용
    optional_fields:
      - cacheHit           # 캐시 히트 여부
      - latencyMs          # 응답 지연 (ms)

  bigquery:
    required_fields:
      - queryId            # 쿼리 식별자
      - bytesProcessed     # 스캔 바이트
      - estimatedCost      # USD 예상 비용
    optional_fields:
      - slotMs             # 슬롯 사용 시간
      - cacheHit           # BQ 캐시 히트 여부

  cost_formula:
    gemini_flash: "$0.075 / 1M input tokens, $0.30 / 1M output tokens"
    gemini_pro: "$1.25 / 1M input tokens, $5.00 / 1M output tokens"
    bigquery: "$5.00 / TB scanned"

# compliance/rbac-matrix.yaml
roles:
  - id: super_admin
    name: Super Admin
    description: 전체 시스템 관리 + 역할 부여 권한
  - id: admin
    name: Admin
    description: 서비스 설정 + 사용자 관리
  - id: manager
    name: Manager
    description: 팀/게임 단위 관리
  - id: viewer
    name: Viewer
    description: 읽기 전용 접근
  - id: guest
    name: Guest
    description: 최소 접근 (툴명/모델명/비용/구조 비노출)

permissions:
  - resource: "dashboard"
    actions:
      super_admin: [read, write, delete, admin]
      admin: [read, write, delete]
      manager: [read, write]
      viewer: [read]
      guest: []  # 접근 불가
  # ... 게임/메뉴/기능별 확장

// functions/src/gateway/ai-gateway.ts
// 외부 API 직접 호출 금지 - 반드시 이 Gateway 경유

import { onCall, HttpsError } from "firebase-functions/v2/https";
import { verifyRole } from "../auth/rbac";
import { logAction } from "../logging/audit";
import { checkCache } from "../cache/cost-cache";

export const callAIModel = onCall(async (request) => {
  // 1. 서버 사이드 권한 검증 (AUTH-P0-003)
  const user = await verifyRole(request.auth, ["admin", "manager"]);

  // 2. Guest 접근 차단 (AUTH-P0-002)
  if (user.role === "guest") {
    throw new HttpsError("permission-denied", "Access denied");
  }

  // 3. 캐시 우선 조회 (COST-P0-011)
  const cached = await checkCache(request.data.prompt);
  if (cached) {
    await logAction({
      userId: user.uid,
      action: "ai_call",
      source: "cache",
      cost: 0,
    });
    return { result: cached, fromCache: true };
  }

  // 4. Gateway 경유 AI 호출 (SEC-P0-005)
  const result = await callGeminiViaGateway(request.data.prompt);

  // 5. 비용 로그 기록 (COST-P0-006)
  await logAction({
    userId: user.uid,
    action: "ai_call",
    model: result.model,
    inputTokens: result.usage.inputTokens,
    outputTokens: result.usage.outputTokens,
    estimatedCost: result.usage.estimatedCost,
  });

  // 6. 민감 원문은 서버에서만 처리, 클라이언트에는 참조 ID 반환 (SEC-P0-009)
  const responseRef = await storeResponse(result.text);
  return { responseId: responseRef.id, summary: result.summary };
});

bash scripts/install.sh [options]
  --dry-run        변경 없이 미리보기
  --skip-checks    의존성 확인 건너뛰기

bash scripts/verify.sh [--rule RULE_ID] [--output JSON_PATH]

bash scripts/score.sh [--input VERIFY_JSON] [--verbose]

bash scripts/gate.sh
# exit 0 = Green (배포 승인)
# exit 1 = Red (배포 차단)
# exit 2 = Yellow (조건부 -- PM 확인 필요)

# .github/workflows/compliance-gate.yml
name: Compliance Gate
on: [pull_request]
jobs:
  compliance:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run compliance gate
        run: bash .agent-skills/ai-tool-compliance/scripts/gate.sh