Back to Details

ai-tool-compliance

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

ai-tool-compliance - Internal AI Tool Compliance Automation

ai-tool-compliance - 内部AI工具合规自动化

When to use this skill

何时使用该技能

  • Starting a new AI project: When scaffolding the compliance foundation (RBAC, Gateway, logs, cost tracking) from scratch
  • Pre-deploy P0 full verification: When automatically evaluating all 13 P0 mandatory requirements as pass/fail and computing a compliance score
  • RBAC design and permission matrix generation: When defining the 5 roles (Super Admin/Admin/Manager/Viewer/Guest) + granular access control per game/menu/feature unit
  • Auditing existing code for compliance: When inspecting an existing codebase against the guide and identifying violations
  • Implementing cost transparency: When building a tracking system for model/token/BQ scan volume/cost per action
  • Designing a behavior log schema: When designing a comprehensive behavior log recording system (Firestore/BigQuery)
  • Role-based verification workflow: When configuring the release approval process based on Section 14 (ServiceStability/Engineer/PM/CEO)
  • Building a criteria verification system: When setting up the Rule Registry + Evidence Collector + Verifier Engine + Risk Scorer + Gatekeeper architecture
  • 启动新AI项目时：需要从零搭建合规基础（RBAC、Gateway、日志、成本追踪）的时候
  • 部署前P0全量验证时：自动评估所有13项P0强制要求是否通过，并计算合规得分的时候
  • RBAC设计和权限矩阵生成时：需要定义5种角色（超级管理员/管理员/经理/查看者/访客）+ 按游戏/菜单/功能单元粒度设置访问控制的时候
  • 审计现有代码合规性时：对照指南检查现有代码库并识别违规项的时候
  • 落地成本透明度时：搭建按操作维度统计模型/Token/BQ扫描量/成本的追踪系统的时候
  • 设计行为日志Schema时：设计完整的行为日志记录系统（Firestore/BigQuery）的时候
  • 基于角色的验证工作流配置时：按照第14节要求配置发布审批流程（服务稳定性负责人/工程师/PM/CEO）的时候
  • 搭建标准验证系统时：搭建规则注册表 + 证据收集器 + 验证引擎 + 风险打分器 + 门禁架构的时候

Installation

安装

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

Quick Reference

快速参考

ActionCommandDescription
Project initialization
/compliance-init
Generate RBAC matrix, Gateway boilerplate, log schema, cost tracking interface
Quick scan
/compliance-scan
, 
/compliance-quick
, 
/quick
Quick inspection of P0 key items (code pattern-based)
Full verification
/compliance-verify
, 
/compliance-full
, 
/full
Full verification of 11 P0 rules + compliance score computation
Score check
/compliance-score
Display current compliance score (security/auth/cost/logging)
Deploy gate
/compliance-gate
Green/Yellow/Red verdict + deploy approve/block decision
Improvement guide
/compliance-improve
, 
/improve
Specific fix suggestions per violation + re-verification loop
操作命令描述
项目初始化
/compliance-init
生成RBAC矩阵、Gateway模板代码、日志Schema、成本追踪接口
快速扫描
/compliance-scan
, 
/compliance-quick
, 
/quick
基于代码模式快速检查P0核心项
全量验证
/compliance-verify
, 
/compliance-full
, 
/full
全量验证11条P0规则 + 计算合规得分
得分查询
/compliance-score
展示当前合规得分（安全/认证/成本/日志四个维度）
部署门禁
/compliance-gate
输出绿/黄/红判定结果 + 部署批准/拦截决策
优化指南
/compliance-improve
, 
/improve
针对每个违规项提供具体修复建议 + 重验证循环

Slash Mode Router

斜杠命令路由

Mode slash commands are mapped as follows.
  • /quick
    , 
    /compliance-quick
    -> Quick Scan (
    /compliance-scan
    )
  • /full
    , 
    /compliance-full
    -> Full Verify (
    /compliance-verify
    )
  • /improve
    -> Improve (
    /compliance-improve
    )
斜杠命令映射关系如下：
  • /quick
    , 
    /compliance-quick
    -> 快速扫描 (
    /compliance-scan
    )
  • /full
    , 
    /compliance-full
    -> 全量验证 (
    /compliance-verify
    )
  • /improve
    -> 优化修复 (
    /compliance-improve
    )

3 Execution Modes

3种执行模式

1. Quick Scan (
quick-scan
)

1. 快速扫描 (
quick-scan
)

Statically analyzes the codebase to quickly identify potential P0 violations.
How to run: 
/compliance-scan
, 
/compliance-quick
, 
/quick
or trigger keywords 
compliance scan
, 
quick scan
What it does:
  • Grep/Glob-based code pattern search
  • Detect direct external API calls (whether Gateway is bypassed)
  • Detect direct Firestore client access
  • Detect hardcoded sensitive data
  • Check for missing Guest role
Output: List of suspected violations (file path + line number + rule ID)
Duration: 1–3 minutes
对代码库进行静态分析，快速识别潜在的P0违规项。
执行方式：
/compliance-scan
, 
/compliance-quick
, 
/quick
或触发关键词 
compliance scan
, 
quick scan
功能说明：
  • 基于Grep/Glob的代码模式搜索
  • 检测是否绕过Gateway直接调用外部API
  • 检测是否直接访问Firestore客户端
  • 检测硬编码敏感数据
  • 检查是否缺失访客角色
输出：疑似违规项列表（文件路径 + 行号 + 规则ID）
耗时：1–3分钟

2. Full Verify (
full-verify
)

2. 全量验证 (
full-verify
)

Fully verifies all 11 P0 rules and computes a quantitative compliance score.
How to run: 
/compliance-verify
, 
/compliance-full
, 
/full
or trigger keywords 
P0 verification
, 
full verify
, 
deploy verification
What it does:
  • Collect Evidence and evaluate pass/fail for each of the 11 P0 rules
  • Compute scores per 4 domains (Security 40pts / Auth 25pts / Cost 20pts / Logging 15pts)
  • Calculate total compliance score (out of 100)
  • Determine deploy gate grade (Green/Yellow/Red)
  • Generate role-based approval checklist
Output: Compliance report (
compliance-report.md
)
undefined
全量验证所有11条P0规则，计算量化合规得分。
执行方式：
/compliance-verify
, 
/compliance-full
, 
/full
或触发关键词 
P0 verification
, 
full verify
, 
deploy verification
功能说明：
  • 收集证据并评估11条P0规则每条是否通过
  • 按4个维度计算得分（安全40分 / 认证25分 / 成本20分 / 日志15分）
  • 计算总合规得分（满分100）
  • 判定部署门禁等级（绿/黄/红）
  • 生成基于角色的审批检查清单
输出：合规报告 (
compliance-report.md
)
undefined

Compliance Report

合规报告

  • Date: 2026-03-03
  • Project: my-ai-tool
  • Score: 92/100 (Green)
  • 日期: 2026-03-03
  • 项目: my-ai-tool
  • 得分: 92/100 (绿)

Rule Results

规则结果

Rule IDRule NameResultEvidence
AUTH-P0-001Force Guest for New SignupsPASSsignup.ts:45 role='guest'
AUTH-P0-002Block Guest Menu/API AccessPASSmiddleware.ts:12 guestBlock
............
规则ID规则名称结果证据
AUTH-P0-001新注册用户强制分配访客角色PASSsignup.ts:45 role='guest'
AUTH-P0-002拦截访客的菜单/API访问PASSmiddleware.ts:12 guestBlock
............

Score Breakdown

得分拆解

  • Security: 33/40
  • Auth: 25/25
  • Cost: 17/20
  • Logging: 12/15
  • Total: 92/100
  • 安全: 33/40
  • 认证: 25/25
  • 成本: 17/20
  • 日志: 12/15
  • 总计: 92/100

Gate Decision: GREEN - Deploy Approved

门禁决策: 绿色 - 批准部署


**Duration**: 5–15 minutes (varies by project size)

**耗时**：5–15分钟（随项目规模变化）

3. Improve (
improve
)

3. 优化修复 (
improve
)

Provides specific fix guides for violations and runs a re-verification loop.
How to run: 
/compliance-improve
, 
/improve
or trigger keywords 
compliance improvement
, 
fix violations
What it does:
  • Code-level fix suggestions for each FAIL item (file path + before/after code)
  • Re-verify the rule after applying the fix
  • Track score changes (Before -> After)
  • Guide for gradually introducing P1 recommended requirements after passing P0
Output: Fix proposal + re-verification results
为违规项提供具体修复指南，并运行重验证循环。
执行方式：
/compliance-improve
, 
/improve
或触发关键词 
compliance improvement
, 
fix violations
功能说明：
  • 为每个未通过项提供代码层面的修复建议（文件路径 + 修复前后代码对比）
  • 应用修复后重新验证对应规则
  • 追踪得分变化（修复前 -> 修复后）
  • P0通过后，指导逐步落地P1推荐要求
输出：修复方案 + 重验证结果

Improve Mode Auto-Fix Logic

优化模式自动修复逻辑

/compliance-improve runs
       |
  1. Load latest verification-run.json
       |
  2. Extract FAIL items (rule_id + evidence)
       |
  3. For each FAIL:
       |
     a. Read violation code from evidence file:line
     b. Derive fix direction from rule.remediation + rule.check_pattern.must_contain
     c. Generate before/after code diff
     d. Apply fix via Write (after user confirmation)
     e. Re-verify only that rule (re-run Grep pattern)
     f. Confirm transition to PASS
       |
  4. Full re-verification (/compliance-verify)
       |
  5. Output Before/After score comparison
       |
  6. If no remaining FAILs → present guide for introducing P1 recommended requirements
Fix application priority:
  1. must_not_contain
    violations (requires immediate removal) → delete the code or replace with server API call
  2. must_contain
    unmet (pattern needs to be added) → insert code per the remediation guide
  3. Warning (partially met) → apply supplement only to unmet files
执行/compliance-improve
       |
  1. 加载最新的 verification-run.json
       |
  2. 提取未通过项（规则ID + 证据）
       |
  3. 遍历每个未通过项:
       |
     a. 从证据的文件:行号读取违规代码
     b. 基于规则的修复方案 + 规则检查必填模式推导修复方向
     c. 生成修复前后的代码diff
     d. 用户确认后通过写入操作应用修复
     e. 仅重新验证该规则（重新运行Grep模式匹配）
     f. 确认状态变为通过
       |
  4. 全量重验证 (/compliance-verify)
       |
  5. 输出修复前后得分对比
       |
  6. 如无剩余未通过项 → 展示P1推荐要求落地指南
修复优先级：
  1. must_not_contain
    违规（需要立即移除）→ 删除代码或替换为服务端API调用
  2. must_contain
    未满足（需要补充对应模式）→ 按照修复指南插入代码
  3. 警告（部分满足）→ 仅为未满足的文件补充对应逻辑

P0 Rule Catalog

P0规则目录

11 P0 rules based on the internal AI tool mandatory implementation guide v1.1:
Rule IDCategoryRule NameDescriptionScore
AUTH-P0-001AuthForce Guest for New SignupsAutomatically assign role=Guest on signup; elevated roles granted only via invitationAuth 8
AUTH-P0-002AuthBlock Guest Menu/API AccessDo not expose tool name, model name, internal infrastructure, cost, or structure to Guest. Only allow access to permitted menus/APIsAuth 7
AUTH-P0-003AuthServer-side Final Auth CheckServer-side auth verification middleware required for all API requests. Client-side checks alone are insufficientAuth 10
SEC-P0-004SecurityProhibit Direct Firestore AccessDirect read/write to Firestore from client is forbidden. Only via Cloud Functions is allowedSecurity 12
SEC-P0-005SecurityEnforce External API GatewayDirect calls to external AI APIs (Gemini, OpenAI, etc.) are forbidden. Must route through internal Gateway (Cloud Functions)Security 18
SEC-P0-009SecurityServer-side Sensitive Text ProcessingSensitive raw content (prompts, full responses) is processed server-side only. Only reference values (IDs) are sent to clientsSecurity 10
COST-P0-006CostModel Call Cost LogMust record model, inputTokens, outputTokens, estimatedCost for every AI model callCost 10
COST-P0-007CostBQ Scan Cost LogMust record bytesProcessed, estimatedCost when executing BigQuery queriesCost 5
COST-P0-011CostCache-first LookupCache lookup required before high-cost API calls. Actual call only on cache missCost 5
LOG-P0-008LoggingMandatory Failed Request LoggingMust log all failed requests (4xx, 5xx, timeout). No omissions allowedLogging 10
LOG-P0-010LoggingAuth Change Audit LogRecord all auth-related events: role changes, permission grants/revocations, invitation sendsLogging 5
基于内部AI工具强制落地指南v1.1制定的11条P0规则：
规则ID分类规则名称描述分值
AUTH-P0-001认证新注册用户强制分配访客角色注册时自动分配role=Guest，更高权限仅可通过邀请授予认证 8
AUTH-P0-002认证拦截访客的菜单/API访问不得向访客暴露工具名称、模型名称、内部基础设施、成本、架构信息，仅允许访问授权的菜单/API认证7
AUTH-P0-003认证服务端最终认证校验所有API请求必须经过服务端认证校验中间件，仅客户端校验不满足要求认证10
SEC-P0-004安全禁止直接访问Firestore禁止客户端直接读写Firestore，仅允许通过Cloud Functions访问安全12
SEC-P0-005安全强制使用外部API Gateway禁止直接调用外部AI API（Gemini、OpenAI等），必须通过内部Gateway（Cloud Functions）转发安全18
SEC-P0-009安全敏感文本服务端处理敏感原始内容（Prompt、完整响应）仅在服务端处理，仅向客户端返回引用值（ID）安全10
COST-P0-006成本模型调用成本日志每次AI模型调用必须记录模型、输入Token、输出Token、预估成本成本10
COST-P0-007成本BQ扫描成本日志执行BigQuery查询时必须记录处理字节数、预估成本成本5
COST-P0-011成本缓存优先查询高成本API调用前必须先查询缓存，缓存未命中时才发起实际调用成本5
LOG-P0-008日志强制记录失败请求必须记录所有失败请求（4xx、5xx、超时），不得遗漏日志10
LOG-P0-010日志认证变更审计日志记录所有认证相关事件：角色变更、权限授予/回收、邀请发送日志5

Scoring System

打分体系

DomainMax ScoreIncluded Rules
Security40SEC-P0-004, SEC-P0-005, SEC-P0-009
Auth25AUTH-P0-001, AUTH-P0-002, AUTH-P0-003
Cost20COST-P0-006, COST-P0-007, COST-P0-011
Logging15LOG-P0-008, LOG-P0-010
Total10011 P0 rules
维度满分包含规则
安全40SEC-P0-004, SEC-P0-005, SEC-P0-009
认证25AUTH-P0-001, AUTH-P0-002, AUTH-P0-003
成本20COST-P0-006, COST-P0-007, COST-P0-011
日志15LOG-P0-008, LOG-P0-010
总计10011条P0规则

Per-rule Automatic Verification Logic

每条规则自动验证逻辑

Verification for each rule is performed based on the 
check_pattern
defined in 
rules/p0-catalog.yaml
. The core mechanism is Grep/Glob static analysis.
Verdict Algorithm (per rule):
1. Glob(check_targets) → collect target files
2. grep_patterns matching → identify files using that feature
   - 0 matches → N/A (feature not used, no penalty)
3. must_not_contain check (excluding exclude_paths)
   - Match found → immediate FAIL + record evidence
4. must_contain check
   - All satisfied → PASS
   - Partially satisfied → WARNING
   - Not satisfied → FAIL
Key Grep Patterns per Rule:
Rule IDFeature Detection (grep_patterns)Compliance Check (must_contain)Violation Detection (must_not_contain)
AUTH-P0-001
signup|register|createUser
role.*['"]guest['"]
role.*['"]admin['"]
(on signup)
AUTH-P0-002
guard|middleware|authorize
guest.*block|guest.*deny
--
AUTH-P0-003
router\.(get|post|put|delete)
auth|verify|authenticate
--
SEC-P0-004-- (all targets)--
firebase/firestore|getDocs|setDoc
(client paths)
SEC-P0-005-- (all targets)--
fetch\(['"]https?://(?!localhost)
(client paths)
SEC-P0-009-- (all targets)--
res\.json\(.*password|console\.log\(.*token
COST-P0-006
openai|vertexai|gemini|anthropic
cost|token|usage|billing
--
COST-P0-007
bigquery|BigQuery|createQueryJob
totalBytesProcessed|bytesProcessed|cost
--
COST-P0-011
openai|vertexai|gemini|anthropic
cache|Cache|redis|memo
--
LOG-P0-008
catch|errorHandler|onError
logger|log\.error|winston|pino
--
LOG-P0-010
updateRole|changeRole|setRole
audit|auditLog|eventLog
--
Detailed schema: see 
rules/p0-catalog.yaml
and the "Judgment Algorithm" section in 
REFERENCE.md
每条规则基于
rules/p0-catalog.yaml
中定义的
check_pattern
执行验证，核心机制为Grep/Glob静态分析。
判定算法（单规则）：
1. Glob(check_targets) → 收集目标文件
2. grep_patterns匹配 → 识别使用对应功能的文件
   - 0匹配 → 不适用（未使用该功能，不扣分）
3. must_not_contain检查（排除exclude_paths）
   - 匹配到内容 → 直接判定未通过 + 记录证据
4. must_contain检查
   - 全部满足 → 通过
   - 部分满足 → 警告
   - 不满足 → 未通过
每条规则核心Grep模式：
规则ID功能检测（grep_patterns）合规检查（must_contain）违规检测（must_not_contain）
AUTH-P0-001
signup|register|createUser
role.*['"]guest['"]
role.*['"]admin['"]
（注册逻辑中）
AUTH-P0-002
guard|middleware|authorize
guest.*block|guest.*deny
--
AUTH-P0-003
router\.(get|post|put|delete)
auth|verify|authenticate
--
SEC-P0-004--（所有目标）--
firebase/firestore|getDocs|setDoc
（客户端路径中）
SEC-P0-005--（所有目标）--
fetch\(['"]https?://(?!localhost)
（客户端路径中）
SEC-P0-009--（所有目标）--
res\.json\(.*password|console\.log\(.*token
COST-P0-006
openai|vertexai|gemini|anthropic
cost|token|usage|billing
--
COST-P0-007
bigquery|BigQuery|createQueryJob
totalBytesProcessed|bytesProcessed|cost
--
COST-P0-011
openai|vertexai|gemini|anthropic
cache|Cache|redis|memo
--
LOG-P0-008
catch|errorHandler|onError
logger|log\.error|winston|pino
--
LOG-P0-010
updateRole|changeRole|setRole
audit|auditLog|eventLog
--
详细Schema：参考
rules/p0-catalog.yaml
和
REFERENCE.md
中的「判定算法」章节

Verification Scenarios (QA)

验证场景（QA）

5 key verification scenarios run in Full Verify mode (
/compliance-verify
). Each scenario groups related P0 rules for end-to-end verification.
IDScenarioRelated RulesVerification MethodPass Criteria
SC-001New Signup -> Guest IsolationAUTH-P0-001, AUTH-P0-002Verify role=guest assignment in signup code + confirm 403 return pattern when Guest calls protected APIPASS when role is guest and access-denied pattern exists for protected API
SC-002AI Call -> Via Gateway + Cost LoggedSEC-P0-005, COST-P0-006, COST-P0-011(1) Confirm absence of direct external API calls (2) Confirm routing via Gateway function (3) Confirm cost log fields (model, tokens, cost) recorded (4) Confirm cache lookup logic existsPASS when Gateway routing + 4 cost log fields recorded + cache layer exists
SC-003Firestore Access -> Functions-OnlySEC-P0-004, AUTH-P0-003(1) Detect direct Firestore SDK import in client code (2) Confirm server-side auth verification middleware existsPASS when 0 direct client access instances + server middleware exists
SC-004Failed Requests -> No Log GapsLOG-P0-008, LOG-P0-010(1) Confirm log call in error handler (2) Confirm no log gaps in catch blocks (3) Confirm audit log exists for auth change eventsPASS when all error handlers call log + auth change audit log exists
SC-005Sensitive Data -> Not Exposed to ClientSEC-P0-009, AUTH-P0-002(1) Confirm API responses do not include raw prompts/responses, only reference IDs (2) Confirm Guest responses do not include model name/cost/infrastructure infoPASS when raw content not in response + Guest exposure control confirmed
全量验证模式（
/compliance-verify
）中运行5个核心验证场景，每个场景分组相关P0规则进行端到端验证。
ID场景关联规则验证方法通过标准
SC-001新注册 -> 访客隔离AUTH-P0-001, AUTH-P0-002验证注册代码中role=guest分配逻辑 + 确认访客调用受保护API时返回403的模式注册时角色为guest，且受保护API存在访问拦截模式则通过
SC-002AI调用 -> 经由Gateway + 成本记录SEC-P0-005, COST-P0-006, COST-P0-011（1）确认无直接外部API调用（2）确认通过Gateway函数转发（3）确认记录了成本日志字段（模型、Token、成本）（4）确认存在缓存查询逻辑Gateway转发 + 4个成本日志字段完整记录 + 存在缓存层则通过
SC-003Firestore访问 -> 仅允许函数访问SEC-P0-004, AUTH-P0-003（1）检测客户端代码中是否直接导入Firestore SDK（2）确认存在服务端认证校验中间件客户端无直接访问实例 + 存在服务端中间件则通过
SC-004失败请求 -> 无日志遗漏LOG-P0-008, LOG-P0-010（1）确认错误处理中存在日志调用（2）确认catch块中无日志遗漏（3）确认认证变更事件存在审计日志所有错误处理都调用日志 + 存在认证变更审计日志则通过
SC-005敏感数据 -> 不暴露给客户端SEC-P0-009, AUTH-P0-002（1）确认API响应不包含原始Prompt/响应，仅返回引用ID（2）确认访客响应不包含模型名称/成本/基础设施信息响应中无原始内容 + 确认访客访问控制生效则通过

Verification Flow by Scenario

按场景的验证流程

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
SC-001: grep signup/register -> 断言role='guest' -> grep guestBlock/guestDeny -> 断言存在
SC-002: grep 客户端代码中fetch(https://) -> 断言0命中 -> grep gateway日志 -> 断言成本字段存在 -> 断言缓存检查存在
SC-003: grep client/路径下的firebase/firestore -> 断言0命中 -> grep functions/路径下的authMiddleware -> 断言存在
SC-004: grep catch块 -> 断言每个块中都有logAction调用 -> grep roleChange -> 断言auditLog存在
SC-005: grep res.json中的原始文本 -> 断言0命中 -> grep 访客响应 -> 断言无模型/成本信息

Role-based Go/No-Go Checkpoints

基于角色的通过/否决检查点

After the deploy gate verdict, the role's Go/No-Go checkpoints must be cleared based on the grade. 4 roles × 5 items = 20 checkpoints total.
部署门禁判定后，必须根据等级完成对应角色的通过/否决检查点。4个角色 × 5项 = 共20个检查点。

Service Stability (5 items)

服务稳定性负责人（5项）

#CheckpointGo ConditionNo-Go Condition
1SLA Impact AnalysisConfirmed no impact on existing service availability/response-time SLASLA impact unanalyzed or degradation expected
2Rollback ProcedureRollback procedure documented + testedRollback procedure not established
3Performance TestLoad/stress test completed + within thresholdPerformance test not run
4Incident AlertsIncident detection alert channels (Slack/PagerDuty, etc.) configuredAlert channels not configured
5Monitoring DashboardDashboard for key metrics (error rate, response time, AI cost) existsMonitoring absent
#检查点通过条件否决条件
1SLA影响分析确认对现有服务可用性/响应时间SLA无影响未分析SLA影响或预计会出现性能下降
2回滚流程回滚流程已文档化 + 经过测试未建立回滚流程
3性能测试负载/压力测试已完成 + 结果在阈值内未运行性能测试
4事件告警事件检测告警渠道（Slack/PagerDuty等）已配置未配置告警渠道
5监控大盘核心指标（错误率、响应时间、AI成本）的大盘已存在缺失监控

Engineer (5 items)

工程师（5项）

#CheckpointGo ConditionNo-Go Condition
1FAIL Rule Root Cause AnalysisRoot cause identified + documented for all FAIL rulesUnidentified items exist
2Fix Code VerificationFixed code accurately reflects the intent of the ruleFix does not match rule intent
3Re-verification PassRule transitions to PASS in re-verification after fixRe-verification not run or still FAIL
4No Regression ImpactFix confirmed to have no negative impact on other P0 rulesAnother rule newly FAILs
5Code Review DoneCode review approval completed for fixed codeCode review not completed
#检查点通过条件否决条件
1未通过规则根因分析所有未通过规则的根因已识别 + 文档化存在未识别的项
2修复代码验证修复后的代码准确符合规则要求修复不符合规则意图
3重验证通过修复后重验证对应规则状态变为通过未运行重验证或仍未通过
4无回归影响确认修复对其他P0规则无负面影响其他规则新出现未通过
5代码评审完成修复代码已完成代码评审批准未完成代码评审

PM (5 items)

PM（5项）

#CheckpointGo ConditionNo-Go Condition
1User Impact AssessmentUser impact of non-compliant items is acceptableUser impact not assessed
2Schedule RiskFix timeline is within release scheduleSchedule overrun expected
3Scope AgreementStakeholder agreement completed for scope changesAgreement not reached
4Cost ImpactAI usage cost within approved budgetBudget overrun expected
5CommunicationChanges shared with relevant teamsNot shared
#检查点通过条件否决条件
1用户影响评估不合规项对用户体验的影响可接受未评估用户影响
2排期风险修复 timeline 在发布排期范围内预计排期超期
3范围共识范围变更已完成相关方共识未达成共识
4成本影响AI使用成本在批准的预算范围内预计超出预算
5同步沟通变更已同步给相关团队未同步

CEO (5 items)

CEO（5项）

#CheckpointGo ConditionNo-Go Condition
1Cost CapMonthly AI cost within pre-approved budgetBudget cap exceeded
2Security RiskAll security P0 passed or exception reason is reasonableP0 security FAIL + insufficient exception justification
3Legal/Regulatory RiskData processing complies with applicable laws (privacy laws, etc.)Legal risks not reviewed
4Business ContinuityBusiness impact is limited if deployment failsBusiness disruption risk exists
5Final ApprovalFinal approval when all 4 above are GoDeferred if even 1 is No-Go
#检查点通过条件否决条件
1成本上限月度AI成本在预先批准的预算内超出预算上限
2安全风险所有安全P0已通过或例外原因合理安全P0未通过 + 例外理由不充分
3法律/合规风险数据处理符合适用法律（隐私法等）未评估法律风险
4业务连续性部署失败对业务影响有限存在业务中断风险
5最终批准以上4项全部通过时给予最终批准哪怕1项否决则延期

Report Format

报告格式

compliance-report.md
, generated when 
/compliance-verify
runs, consists of 6 sections.
运行
/compliance-verify
时生成的
compliance-report.md
包含6个章节。

Report Section Structure (6 sections)

报告章节结构（6章）

markdown
undefined
markdown
undefined

Compliance Report

合规报告

1. Summary

1. 概览

  • Project name, verification date/time, verification mode (quick-scan / full-verify)
  • Total compliance score / 100
  • Deploy gate grade (Green / Yellow / Red)
  • P0 FAIL count
  • Verification duration
  • 项目名称、验证日期/时间、验证模式（quick-scan / full-verify）
  • 总合规得分 / 100
  • 部署门禁等级（绿 / 黄 / 红）
  • P0未通过数量
  • 验证耗时

2. Rule Results

2. 规则结果

Rule IDCategoryRule NameResultScoreEvidence
AUTH-P0-001AuthForce Guest for New SignupsPASS10/10signup.ts:45
SEC-P0-005SecurityEnforce External API GatewayFAIL0/15client/api.ts:23 direct fetch
...
规则ID分类规则名称结果得分证据
AUTH-P0-001认证新注册用户强制分配访客角色PASS10/10signup.ts:45
SEC-P0-005安全强制使用外部API GatewayFAIL0/15client/api.ts:23 直接fetch
...

3. Score Breakdown

3. 得分拆解

DomainScoreMax%
Security204050%
Auth2525100%
Cost172085%
Logging121580%
Total7910079%
维度得分满分占比
安全204050%
认证2525100%
成本172085%
日志121580%
总计7910079%

4. Failures Detail

4. 违规详情

For each FAIL item:
  • Violation code location (file:line)
  • Description of the violation
  • Recommended fix (remediation)
  • Related verification scenario ID (SC-001–SC-005)
每个未通过项包含：
  • 违规代码位置（文件:行号）
  • 违规描述
  • 推荐修复方案
  • 关联验证场景ID（SC-001–SC-005）

5. Gate Decision

5. 门禁决策

  • Verdict grade + basis for verdict
  • List of required approval roles
  • Role-based Go/No-Go checkpoint status (unmet items out of 20 shown)
  • 判定等级 + 判定依据
  • 所需审批角色列表
  • 基于角色的通过/否决检查点状态（展示20项中未满足的项）

6. Recommendations

6. 建议

  • Immediate action: Fix P0 FAILs (file path + fix guide)
  • Short-term improvement: Path from Yellow to Green
  • Mid-term adoption: Order for introducing P1 recommended requirements
undefined
  • 紧急动作：修复P0未通过项（文件路径 + 修复指南）
  • 短期优化：从黄色等级升级到绿色等级的路径
  • 中期落地：P1推荐要求引入顺序
undefined

Report Generation Rules

报告生成规则

  1. Summary is always first: Decision-makers must be able to immediately see the score and grade
  2. Evidence required: Attach code evidence (file:line) to all PASS/FAIL items in Rule Results
  3. Failures Detail contains only FAILs: PASS items appear only in the Rule Results table
  4. Role mapping in Gate Decision: Auto-display required approval roles based on grade
  5. Recommendations priority: Sorted as Immediate > Short-term > Mid-term
  1. 概览始终放在最前：决策者可以第一时间看到得分和等级
  2. 必须包含证据：规则结果中所有通过/未通过项都要附带代码证据（文件:行号）
  3. 违规详情仅包含未通过项：通过项仅出现在规则结果表格中
  4. 门禁决策自动映射角色：基于等级自动展示所需审批角色
  5. 建议按优先级排序：紧急 > 短期 > 中期

Deploy Gate Policy

部署门禁策略

Grade Verdict Criteria

等级判定标准

GradeScoreConditionDecision
Green90–100All P0 PASS + total score ≥ 90Auto deploy approved
Yellow75–89All P0 PASS + total score 75–89Conditional approval (PM review required)
Red0–74Total score ≤ 74 or any P0 FAILDeploy blocked
等级得分条件决策
绿色90–100所有P0通过 + 总得分 ≥ 90自动批准部署
黄色75–89所有P0通过 + 总得分75–89条件批准（需要PM评审）
红色0–74总得分 ≤ 74 或 任意P0未通过拦截部署

Core Rules

核心规则

  1. P0 Absolute Rule: If even one P0 FAILs, the verdict is Red regardless of total score. Deploy automatically blocked
  2. Yellow conditional: Total score passes but not perfect. PM reviews the risk and decides approve/reject
  3. Green auto-approve: All P0 passed + score ≥ 90 allows deploy without additional approval
  1. P0绝对规则：哪怕1条P0未通过，不管总得分多少，直接判定为红色，自动拦截部署
  2. 黄色条件批准：总得分通过但不够完美，PM评审风险后决定批准/驳回
  3. 绿色自动批准：所有P0通过 + 得分 ≥ 90，无需额外审批即可部署

Gate Execution Flow

门禁执行流程

/compliance-verify runs
       |
  Full verification of 11 P0 rules
       |
  Score computed (Security+Auth+Cost+Logging)
       |
  +----+----+----+
  |         |         |
Green     Yellow    Red
  |         |         |
Auto-Approve  PM-Approve  Deploy-Block
  |       Pending   |
  v         |      After Fix
Deploy       v      Re-verify
        PM Review     |
        |    |      v
      Approve  Reject  /compliance-improve
        |    |
        v    v
      Deploy  After Fix
            Re-verify
执行/compliance-verify
       |
  全量验证11条P0规则
       |
  计算得分（安全+认证+成本+日志）
       |
  +----+----+----+
  |         |         |
绿色     黄色    红色
  |         |         |
自动批准  PM审批  拦截部署
  |       待处理   |
  v         |      修复后
部署       v      重验证
        PM评审     |
        |    |      v
      批准  驳回  /compliance-improve
        |    |
        v    v
      部署  修复后
            重验证

Role-based Approval Process

基于角色的审批流程

Based on Section 14 of the internal AI tool mandatory implementation guide. The required approval roles vary by deploy grade.
基于内部AI工具强制落地指南第14节，所需审批角色随部署等级变化。

Service Stability

服务稳定性负责人

Responsibility: Verify incident impact, performance degradation, and rollback feasibility
Checklist:
  • Does the new deployment not impact existing service SLAs?
  • Is the rollback procedure documented?
  • Has performance testing (load/stress) been completed?
  • Are incident alert channels configured?
Approval trigger: Required for Yellow/Red grade
职责：验证事件影响、性能下降、回滚可行性
检查清单：
  • 新部署不影响现有服务SLA？
  • 回滚流程已文档化？
  • 性能测试（负载/压力）已完成？
  • 事件告警渠道已配置？
审批触发条件：黄色/红色等级需要

Engineer

工程师

Responsibility: Root cause analysis of failed rules + code-level fix + re-verification
Checklist:
  • Has the cause of all FAIL rules been identified?
  • Does the fixed code accurately reflect the intent of the rule?
  • Has the rule transitioned to PASS in re-verification?
  • Does the fix have no negative impact on other rules?
Approval trigger: Required for Red grade (responsible for re-verification after fix)
职责：未通过规则根因分析 + 代码层面修复 + 重验证
检查清单：
  • 所有未通过规则的原因已识别？
  • 修复后的代码准确符合规则意图？
  • 重验证后规则状态变为通过？
  • 修复对其他规则无负面影响？
审批触发条件：红色等级需要（负责修复后重验证）

PM (Product Manager)

PM（产品经理）

Responsibility: User impact, schedule risk, scope change approval
Checklist:
  • Is the impact of non-compliant items on user experience acceptable?
  • Is the schedule impact of fixes acceptable within the overall release timeline?
  • If scope reduction/deferral is needed, has stakeholder agreement been reached?
Approval trigger: Required for Yellow grade
职责：用户影响、排期风险、范围变更审批
检查清单：
  • 不合规项对用户体验的影响可接受？
  • 修复的排期影响在整体发布 timeline 范围内可接受？
  • 如果需要缩减范围/延期，已达成相关方共识？
审批触发条件：黄色等级需要

CEO

CEO

Responsibility: Cost cap, business risk, final approval
Checklist:
  • Is AI usage cost within the pre-approved budget?
  • Is the security risk at an acceptable level for the business?
  • Are legal/regulatory risks identified and managed?
Approval trigger: When cost cap is exceeded or when approving a security P0 exception
职责：成本上限、业务风险、最终审批
检查清单：
  • AI使用成本在预先批准的预算内？
  • 安全风险对业务来说处于可接受水平？
  • 法律/合规风险已识别并管控？
审批触发条件：超出成本上限或批准安全P0例外时需要

Project Initialization (
/compliance-init
)

项目初始化 (
/compliance-init
)

Generated File Structure

生成的文件结构

project/
├── compliance/
│   ├── rbac-matrix.yaml          # 5-role × game/menu/feature permission matrix
│   ├── rules/
│   │   └── p0-rules.yaml         # 11 P0 rule definitions
│   ├── log-schema.yaml           # Behavior log schema (Firestore/BigQuery)
│   └── cost-tracking.yaml        # Cost tracking field definitions
├── compliance-config.yaml        # Project metadata + verification settings
└── compliance-report.md          # Verification result report (generated on verify run)
project/
├── compliance/
│   ├── rbac-matrix.yaml          # 5角色 × 游戏/菜单/功能权限矩阵
│   ├── rules/
│   │   └── p0-rules.yaml         # 11条P0规则定义
│   ├── log-schema.yaml           # 行为日志Schema（Firestore/BigQuery）
│   └── cost-tracking.yaml        # 成本追踪字段定义
├── compliance-config.yaml        # 项目元数据 + 验证设置
└── compliance-report.md          # 验证结果报告（运行verify时生成）

Each YAML File Schema

每个YAML文件的Schema

compliance-config.yaml (project root):
yaml
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"   # default
  exclude_paths:                                     # paths to exclude from verification
    - "node_modules/**"
    - "dist/**"
    - "**/*.test.ts"
    - "**/*.spec.ts"

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

gate:
  green_threshold: 90        # >= 90 = auto approve
  yellow_threshold: 75       # 75-89 = PM review required
  p0_fail_override: true     # Red verdict on P0 FAIL regardless of score
compliance/log-schema.yaml (behavior log schema):
yaml
log_schema:
  version: "1.0.0"
  storage:
    primary: "firestore"           # for real-time access
    archive: "bigquery"            # for analytics/audit
    retention:
      hot: 90                      # days (Firestore)
      cold: 365                    # days (BigQuery)

  fields:
    - name: userId
      type: string
      required: true
    - name: action
      type: string
      required: true
      description: "action performed (ai_call, role_change, login, etc.)"
    - name: timestamp
      type: timestamp
      required: true
    - name: model
      type: string
      required: false
      description: "AI model name (gemini-1.5-flash, etc.)"
    - name: inputTokens
      type: number
      required: false
    - name: outputTokens
      type: number
      required: false
    - name: estimatedCost
      type: number
      required: false
      description: "estimated cost in 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: "additional context (bytesProcessed, cacheHit, etc.)"
compliance/cost-tracking.yaml (cost tracking fields):
yaml
cost_tracking:
  version: "1.0.0"

  ai_models:
    required_fields:
      - model              # model identifier
      - inputTokens        # input token count
      - outputTokens       # output token count
      - estimatedCost      # estimated cost in USD
    optional_fields:
      - cacheHit           # whether cache was hit
      - latencyMs          # response latency (ms)

  bigquery:
    required_fields:
      - queryId            # query identifier
      - bytesProcessed     # bytes scanned
      - estimatedCost      # estimated cost in USD
    optional_fields:
      - slotMs             # slot usage time
      - cacheHit           # BQ cache hit indicator

  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-config.yaml（项目根目录）：
yaml
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未通过时直接判定红色，忽略得分
compliance/log-schema.yaml（行为日志Schema）：
yaml
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等）"
    - 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: "预估成本（美元）"
    - 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等）"
compliance/cost-tracking.yaml（成本追踪字段）：
yaml
cost_tracking:
  version: "1.0.0"

  ai_models:
    required_fields:
      - model              # 模型标识符
      - inputTokens        # 输入Token数量
      - outputTokens       # 输出Token数量
      - estimatedCost      # 预估成本（美元）
    optional_fields:
      - cacheHit           # 是否命中缓存
      - latencyMs          # 响应延迟（毫秒）

  bigquery:
    required_fields:
      - queryId            # 查询标识符
      - bytesProcessed     # 扫描字节数
      - estimatedCost      # 预估成本（美元）
    optional_fields:
      - slotMs             # Slot使用时间
      - cacheHit           # BQ缓存命中标识

  cost_formula:
    gemini_flash: "$0.075 / 1M输入Token, $0.30 / 1M输出Token"
    gemini_pro: "$1.25 / 1M输入Token, $5.00 / 1M输出Token"
    bigquery: "$5.00 / TB扫描量"

RBAC Matrix Base Structure

RBAC矩阵基础结构

yaml
undefined
yaml
undefined

compliance/rbac-matrix.yaml

compliance/rbac-matrix.yaml

roles:
  • id: super_admin name: Super Admin description: Full system administration + role assignment rights
  • id: admin name: Admin description: Service configuration + user management
  • id: manager name: Manager description: Team/game-level management
  • id: viewer name: Viewer description: Read-only access
  • id: guest name: Guest description: Minimum access (tool name/model name/cost/structure not exposed)
permissions:
  • resource: "dashboard" actions: super_admin: [read, write, delete, admin] admin: [read, write, delete] manager: [read, write] viewer: [read] guest: [] # no access

... expand per game/menu/feature

undefined
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: [] # 无访问权限

... 按游戏/菜单/功能扩展

undefined

Gateway Pattern Example

Gateway模式示例

typescript
// functions/src/gateway/ai-gateway.ts
// Direct external API calls forbidden - must route through this 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. Server-side auth verification (AUTH-P0-003)
  const user = await verifyRole(request.auth, ["admin", "manager"]);

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

  // 3. Cache-first lookup (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. AI call via Gateway (SEC-P0-005)
  const result = await callGeminiViaGateway(request.data.prompt);

  // 5. Record cost log (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. Sensitive raw content processed server-side only; return reference ID to client (SEC-P0-009)
  const responseRef = await storeResponse(result.text);
  return { responseId: responseRef.id, summary: result.summary };
});
<!-- TODO: Designer output supplement pending - visual format and dashboard UI for compliance-report.md -->
typescript
// 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. 拦截访客访问（AUTH-P0-002）
  if (user.role === "guest") {
    throw new HttpsError("permission-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 };
});
<!-- TODO: 待补充设计器输出 - compliance-report.md的可视化格式和大盘UI -->

Relationship with Other Skills

与其他技能的关系

Integration with bmad-orchestrator

与bmad-orchestrator的集成

Where 
bmad-orchestrator
manages the full project development phases (Analysis -> Planning -> Solutioning -> Implementation), 
ai-tool-compliance
acts as a companion tool that verifies whether each phase's outputs meet compliance requirements.
Recommended usage order:
  1. /workflow-init
    (bmad) -- establish project structure
  2. /compliance-init
    (compliance) -- generate compliance foundation
  3. After Phase 3 Architecture completes, 
    /compliance-scan
    -- architecture-level compliance check
  4. After Phase 4 Implementation completes, 
    /compliance-verify
    -- full verification + deploy gate verdict
bmad-orchestrator
负责管理完整的项目开发阶段（分析 -> 规划 -> 方案 -> 落地），
ai-tool-compliance
作为配套工具，验证每个阶段的输出是否满足合规要求。
推荐使用顺序：
  1. /workflow-init
    （bmad）-- 搭建项目结构
  2. /compliance-init
    （合规）-- 生成合规基础配置
  3. 第3阶段架构完成后，运行
    /compliance-scan
    -- 架构层面合规检查
  4. 第4阶段落地完成后，运行
    /compliance-verify
    -- 全量验证 + 部署门禁判定

Relationship with security-best-practices

与security-best-practices的关系

security-best-practices
provides general web security patterns (OWASP, HTTPS, XSS, CSRF). 
ai-tool-compliance
assumes these as prerequisites and focuses on organization-specific requirements (5-role RBAC, Gateway enforcement, cost transparency, comprehensive behavior logging).
Itemsecurity-best-practicesai-tool-compliance
RBACGeneral mention5-role + game/menu/feature matrix
API SecurityRate Limiting, CORSGateway enforcement + cost log
Data ProtectionXSS, CSRF, SQL InjectionSensitive content server-side + Firestore policy
LoggingSecurity event loggingComprehensive behavior log + schema/retention policy
Deploy GateNoneAuto-block based on compliance score
security-best-practices
提供通用Web安全模式（OWASP、HTTPS、XSS、CSRF），
ai-tool-compliance
将这些作为前置条件，聚焦于组织特定要求（5角色RBAC、Gateway强制、成本透明度、全量行为日志）。
项security-best-practicesai-tool-compliance
RBAC通用提及5角色 + 游戏/菜单/功能矩阵
API安全限流、CORSGateway强制 + 成本日志
数据保护XSS、CSRF、SQL注入敏感内容服务端处理 + Firestore策略
日志安全事件日志全量行为日志 + Schema/留存策略
部署门禁无基于合规得分自动拦截

Relationship with code-review

与code-review的关系

Where 
code-review
subjectively reviews code quality/readability/security, 
ai-tool-compliance
provides a quantitative verdict (pass/fail, out of 100) on "Does it pass the internal AI tool guide?" The 
/compliance-scan
result can be used as reference material during code review.
code-review
主观评审代码质量/可读性/安全性，
ai-tool-compliance
针对「是否符合内部AI工具指南」给出量化判定（通过/未通过，满分100）。
/compliance-scan
的结果可作为代码评审时的参考材料。

Relationship with workflow-automation

与workflow-automation的关系

Where 
workflow-automation
provides general CI/CD patterns (npm scripts, Makefile, GitHub Actions), 
ai-tool-compliance
provides the domain-specific verification step inserted into that pipeline.
workflow-automation
提供通用CI/CD模式（npm脚本、Makefile、GitHub Actions），
ai-tool-compliance
提供领域特定的验证步骤，可插入到该流水线中。

scripts/ Directory — Detailed Implementation

scripts/目录 — 详细实现

install.sh -- Skill installation and initialization

install.sh -- 技能安装和初始化

bash
bash scripts/install.sh [options]
  --dry-run        preview without making changes
  --skip-checks    skip dependency checks
What it does:
  1. Dependency check (yq, jq -- optional; falls back to default parsing if absent)
  2. Apply chmod +x to all scripts/*.sh
  3. Validate YAML syntax of rules/p0-catalog.yaml
  4. Print installation summary
bash
bash scripts/install.sh [options]
  --dry-run        预览模式，不做实际变更
  --skip-checks    跳过依赖检查
功能说明：
  1. 依赖检查（yq、jq -- 可选；缺失时回退到默认解析）
  2. 为所有scripts/*.sh添加可执行权限
  3. 验证rules/p0-catalog.yaml的YAML语法
  4. 打印安装摘要

verify.sh -- Full P0 rule verification

verify.sh -- 全量P0规则验证

bash
bash scripts/verify.sh [--rule RULE_ID] [--output JSON_PATH]
What it does:
  1. Parse 
    rules/p0-catalog.yaml
    (yq or grep-based)
  2. For each rule:
    • Collect target files via 
      check_targets
      Glob
    • Detect feature usage via 
      grep_patterns
      (N/A if not used)
    • Detect 
      must_not_contain
      violations (excluding exclude_paths)
    • Verify 
      must_contain
      compliance
    • Determine Pass/Fail/Warning/N/A + collect evidence
  3. Output results in 
    templates/verification-run.json
    format
  4. Print summary table to console
bash
bash scripts/verify.sh [--rule RULE_ID] [--output JSON_PATH]
功能说明：
  1. 解析
    rules/p0-catalog.yaml
    （基于yq或grep）
  2. 遍历每条规则：
    • 通过
      check_targets
      Glob收集目标文件
    • 通过
      grep_patterns
      检测功能使用情况（未使用则标记为不适用）
    • 检测
      must_not_contain
      违规（排除exclude_paths）
    • 校验
      must_contain
      合规性
    • 判定通过/未通过/警告/不适用 + 收集证据
  3. 按
    templates/verification-run.json
    格式输出结果
  4. 向控制台打印摘要表格

score.sh -- Compliance score computation

score.sh -- 合规得分计算

bash
bash scripts/score.sh [--input VERIFY_JSON] [--verbose]
What it does:
  1. Load verify.sh result JSON (or run verify.sh directly)
  2. Calculate scores by domain:
    • Pass = 100% of score, Warning = 50%, Fail = 0%, N/A = excluded from denominator
    • Security: sum of SEC rule scores / Security max (35)
    • Auth: sum of AUTH rule scores / Auth max (30)
    • Cost: sum of COST rule scores / Cost max (20)
    • Logging: sum of LOG rule scores / Logging max (15)
  3. Compute total score (out of 100)
  4. Render 
    templates/risk-score-report.md
  5. Generate 
    templates/remediation-task.json
    (per FAIL item)
bash
bash scripts/score.sh [--input VERIFY_JSON] [--verbose]
功能说明：
  1. 加载verify.sh的结果JSON（或直接运行verify.sh）
  2. 按维度计算得分：
    • 通过 = 100%得分，警告 = 50%得分，未通过 = 0%得分，不适用 = 不计入分母
    • 安全：SEC规则得分总和 / 安全满分（35）
    • 认证：AUTH规则得分总和 / 认证满分（30）
    • 成本：COST规则得分总和 / 成本满分（20）
    • 日志：LOG规则得分总和 / 日志满分（15）
  3. 计算总得分（满分100）
  4. 渲染
    templates/risk-score-report.md
  5. 生成
    templates/remediation-task.json
    （针对每个未通过项）

gate.sh -- Deploy gate check

gate.sh -- 部署门禁检查

bash
bash scripts/gate.sh
bash
bash scripts/gate.sh

exit 0 = Green (deploy approved)

exit 0 = 绿色（批准部署）

exit 1 = Red (deploy blocked)

exit 1 = 红色（拦截部署）

exit 2 = Yellow (conditional -- PM review required)

exit 2 = 黄色（条件批准 -- 需要PM评审）


What it does:
1. Run verify.sh + score.sh sequentially
2. Check for P0 FAIL existence
   - If any exist → Red (exit 1)
3. Determine grade based on total score
   - 90+ → Green (exit 0)
   - 75–89 → Yellow (exit 2)
   - ≤ 74 → Red (exit 1)
4. Print grade + score + list of items requiring fixes to console

**CI/CD integration example (GitHub Actions)**:

```yaml

功能说明：
1. 顺序运行verify.sh + score.sh
2. 检查是否存在P0未通过项
   - 存在 → 红色（exit 1）
3. 基于总得分判定等级
   - 90+ → 绿色（exit 0）
   - 75–89 → 黄色（exit 2）
   - ≤ 74 → 红色（exit 1）
4. 向控制台打印等级 + 得分 + 需要修复的项列表

**CI/CD集成示例（GitHub Actions）**：

```yaml

.github/workflows/compliance-gate.yml

.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
<!-- TODO: System output supplement pending - GitHub Actions workflow integration YAML -->

---
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
<!-- TODO: 待补充系统输出 - GitHub Actions流水线集成YAML -->

---

P1 Recommended Requirements (Gradual Adoption)

P1推荐要求（逐步落地）

Items recommended for gradual adoption after passing all P0 rules:
DomainRequirementDescription
Domain ManagementAllowed domain whitelistRestrict external domains callable by AI Gateway
Usage StatisticsPer-user/team usage aggregationDaily/weekly/monthly usage dashboard
Cost ControlBudget cap alertsAlert when cost threshold exceeded per team/project
Log RetentionLog retention policy90-day Hot / 365-day Cold / delete thereafter
所有P0规则通过后，推荐逐步落地的项：
维度要求描述
域名管理允许域名白名单限制AI Gateway可调用的外部域名
使用统计按用户/团队聚合使用量日/周/月使用大盘
成本控制预算上限告警每个团队/项目超出成本阈值时告警
日志留存日志留存策略90天热存储 / 365天冷存储 / 到期删除

P1 v1.1 Rule Catalog (Extended)

P1 v1.1规则目录（扩展）

Rule IDDomainCheck TypeKey CriteriaScore
P1-DOM-001Domain Managementstatic_analysisDomain CRUD history + 
createdAt/updatedAt/status/owner
metadata		7
P1-STAT-002Statisticsapi_testUser/model/period/game filter statistics + cost aggregation freshness (<1h)6
P1-COST-003Cost Controlconfig_check80% budget warning + 100% block (429/403) + reset cycle6
P1-LOG-004Loggingconfig_checkLog schema validation + 6+ month retention + search/Export6
规则ID维度检查类型核心标准分值
P1-DOM-001域名管理静态分析域名CRUD历史 + 
createdAt/updatedAt/status/owner
元数据		7
P1-STAT-002统计API测试用户/模型/周期/游戏维度过滤统计 + 成本聚合新鲜度（<1小时）6
P1-COST-003成本控制配置检查80%预算预警 + 100%拦截（429/403） + 重置周期6
P1-LOG-004日志配置检查日志Schema校验 + 6+个月留存 + 搜索/导出功能6

Standard Columns for Notion Table Sorting (Additional)

Notion表格排序标准列（附加）

ColumnDescriptionSource
Rule IDRule identifierrules/p1-catalog.yaml
Category/DomainCompliance domainrules/p1-catalog.yaml
Check TypeVerification method (static/api/config/log)rules/*-catalog.yaml
Pass/Fail ConditionVerdict criteriarules/*-catalog.yaml
Score ImpactWeightrules/*-catalog.yaml
EvidenceFile:line or config referenceverify result JSON
Owner RoleRole responsible for actioncompliance-report / role checklist
Action QueueImprovement items within 1 weekremediation-task / report
列描述来源
规则ID规则标识符rules/p1-catalog.yaml
分类/维度合规领域rules/p1-catalog.yaml
检查类型验证方法（static/api/config/log）rules/*-catalog.yaml
通过/未通过条件判定标准rules/*-catalog.yaml
得分影响权重rules/*-catalog.yaml
证据文件:行号或配置引用验证结果JSON
负责人角色负责处理的角色合规报告 / 角色检查清单
行动队列1周内的优化项修复任务 / 报告

Criteria Verification System Design (Additional)

标准验证系统设计（附加）

ComponentResponsibilityOutput
Rule RegistryP0/P1 catalog version management and load policy
rules/catalog.json
, 
rules/catalog-p1.json
, 
rules/catalog-all.json
Evidence CollectorCode/config/API evidence collection and normalizationevidence/violations from 
verify.sh
output
Verifier EnginePer-rule PASS/FAIL/WARNING/NA verdict
/tmp/compliance-verify.json
Risk ScorerCompute P0 Gate Score + P1 Maturity Score
/tmp/compliance-score.json
GatekeeperSeparate deploy block (P0) and recommendation (P1) decisions
gate.sh
exit code + gate summary
组件职责输出
规则注册表P0/P1目录版本管理和加载策略
rules/catalog.json
, 
rules/catalog-p1.json
, 
rules/catalog-all.json
证据收集器代码/配置/API证据收集和标准化
verify.sh
输出的evidence/violations
验证引擎单规则通过/未通过/警告/不适用判定
/tmp/compliance-verify.json
风险打分器计算P0门禁得分 + P1成熟度得分
/tmp/compliance-score.json
门禁器区分部署拦截（P0）和推荐优化（P1）决策
gate.sh
退出码 + 门禁摘要

Operating Modes (Additional, preserving existing flow)

运行模式（附加，兼容现有流程）

ModeCommandBehavior
P0 Default
bash scripts/verify.sh .
Verify P0 rules only (default, backward-compatible)
P0+P1 Extended
bash scripts/verify.sh . --include-p1
P0 verification + P1 recommended rules simultaneously
Gate Verdict
bash scripts/gate.sh --score-file ...
Deploy verdict based on P0; P1 tracks maturity/improvement
模式命令行为
P0默认
bash scripts/verify.sh .
仅验证P0规则（默认，向后兼容）
P0+P1扩展
bash scripts/verify.sh . --include-p1
同时验证P0规则 + P1推荐规则
门禁判定
bash scripts/gate.sh --score-file ...
基于P0给出部署判定；P1用于追踪成熟度/优化情况

Constraints

约束

Mandatory Rules (MUST)

强制规则（必须遵守）

  1. P0 Absolute Principle: All 11 P0 rules are verified without exception. Partial verification is not allowed
  2. Server final verification: All auth decisions are made server-side. Client-side checks alone cannot result in PASS
  3. Gateway enforcement: Any direct external AI API call discovered results in unconditional FAIL. No bypass allowed
  4. Guest default: If a role other than Guest is assigned on signup, FAIL
  5. Evidence-based verdict: All pass/fail verdicts must include code evidence (file path + line number)
  1. P0绝对原则：11条P0规则全部验证，无例外，不允许部分验证
  2. 服务端最终校验：所有认证决策在服务端做出，仅客户端校验不能判定为通过
  3. Gateway强制：发现任何直接调用外部AI API的情况，无条件判定为未通过，不允许绕过
  4. 访客默认角色：注册时分配访客以外的角色，判定为未通过
  5. 基于证据判定：所有通过/未通过判定必须附带代码证据（文件路径 + 行号）

Prohibited Actions (MUST NOT)

禁止行为（严禁）

  1. P0 exception abuse: P0 exceptions are never allowed without CEO approval
  2. Score manipulation: PASS verdict without Evidence is forbidden
  3. Gateway bypass: Direct external API calls are not allowed for any reason including "testing purposes"
  4. Selective logging: Logging only successful requests while omitting failed requests is not allowed
  1. 滥用P0例外：未经CEO批准，不得给予任何P0例外
  2. 操纵得分：没有证据的通过判定是禁止的
  3. 绕过Gateway：任何理由包括「测试用途」都不允许直接调用外部API
  4. 选择性日志：仅记录成功请求，遗漏失败请求是禁止的

Best practices

最佳实践

  1. Shift Left: At project start, generate the foundation with 
    /compliance-init
    before implementing business logic
  2. Gradual adoption: Adopt in order: pass all P0 first -> then P1. Do not start with P1
  3. Re-verification loop: After fixing violations, always re-run 
    /compliance-verify
    to confirm score changes
  4. BMAD integration: Adopt running compliance-verify after bmad-orchestrator Phase 4 as the standard workflow
  5. CI/CD integration: Automate by adding a compliance-gate step to GitHub Actions
  1. 左移合规：项目启动时，先运行
    /compliance-init
    生成基础配置，再实现业务逻辑
  2. 逐步落地：按顺序落地：先全部通过P0 -> 再落地P1，不要从P1开始
  3. 重验证循环：修复违规项后，始终重新运行
    /compliance-verify
    确认得分变化
  4. BMAD集成：将bmad-orchestrator第4阶段后运行compliance-verify作为标准工作流
  5. CI/CD集成：在GitHub Actions中添加compliance-gate步骤实现自动化

References

参考

Metadata

元数据

Version

版本

  • Current version: 1.0.0
  • Last updated: 2026-03-03
  • Compatible platforms: Claude, Gemini, Codex, OpenCode
  • 当前版本: 1.0.0
  • 最后更新: 2026-03-03
  • 兼容平台: Claude, Gemini, Codex, OpenCode

Related Skills

关联技能

  • bmad-orchestrator: Development phase orchestration
  • security-best-practices: General web security patterns
  • code-review: Code quality/security review
  • workflow-automation: CI/CD automation patterns
  • authentication-setup: Authentication/authorization system setup
  • firebase-ai-logic: Firebase AI integration
  • bmad-orchestrator: 开发阶段编排
  • security-best-practices: 通用Web安全模式
  • code-review: 代码质量/安全评审
  • workflow-automation: CI/CD自动化模式
  • authentication-setup: 认证/授权系统搭建
  • firebase-ai-logic: Firebase AI集成

Tags

标签

#compliance
#RBAC
#security
#cost-tracking
#audit-log
#gateway
#firestore
#deploy-gate
#P0
#AI-tool
#compliance
#RBAC
#security
#cost-tracking
#audit-log
#gateway
#firestore
#deploy-gate
#P0
#AI-tool