chore(marketplace): update req-retro karpathy-score dimension, req-test-gate gate-0b docs

- req-retro: 新增 karpathy_score × 0.20 维度，QS 公式扩展为 5 维
- req-test-gate: Gate 0B 新增 check-surgical.sh Ratchet 文档

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

.claude-plugin/marketplace.json

@@ -338,6 +338,18 @@
       ],
       "strict": false
     },
+    {
+      "name": "karpathy-guidelines-plugin",
+      "source": "./skills-dev/karpathy-guidelines-plugin",
+      "description": "Karpathy 四原则编码行为守则（Think Before Coding / Simplicity First / Surgical Changes / Goal-Driven Execution）。已深度融合到 req 技能工作流各阶段，可独立激活用于任意编码场景。",
+      "version": "1.0.0",
+      "category": "utility",
+      "keywords": [
+        "utility",
+        "tools"
+      ],
+      "strict": false
+    },
     {
       "name": "pull-request-plugin",
       "source": "./skills-dev/pull-request-plugin",

skills-dev/dev-coding-plugin/skills/SKILL.md

@@ -73,6 +73,72 @@ ai-proj task append-doc --id <taskId> --content "实现说明"
 
 ---
 
+## Step 0：验证优先（Karpathy: Goal-Driven Execution）
+
+**编写任何代码前，必须先写验证脚本。** 规则来源：Karpathy "Goal-Driven Execution" 原则。
+
+> "Define success criteria. Loop until verified."
+> "Fix the bug" → "Write a test that reproduces it, then make it pass"
+
+### 执行流程
+
+```
+① 写验证脚本（按类型选择）
+② 运行一遍，确认全部 FAIL（证明功能确实不存在 / bug 确实存在）
+③ 编码实现
+④ 再次运行验证脚本，全部 PASS → 完成
+```
+
+### 后端验证脚本模板
+
+实现 API 前，先写好所有 curl 命令并标注期望结果：
+
+```bash
+# 验证脚本：REQ-XXXX [功能名]
+BASE="http://localhost:8080"
+TOKEN="<JWT>"
+
+echo "=== T1: 正常创建 ==="
+curl -s -X POST "$BASE/api/v1/xxx" \
+  -H "Authorization: Bearer $TOKEN" \
+  -d '{"name":"test"}' | jq '.code'
+# 期望: 0
+
+echo "=== T2: 缺少必填字段 ==="
+curl -s -X POST "$BASE/api/v1/xxx" \
+  -H "Authorization: Bearer $TOKEN" \
+  -d '{}' | jq '.code'
+# 期望: 非 0（参数错误）
+
+echo "=== T3: 跨租户访问 ==="
+curl -s -X GET "$BASE/api/v1/xxx/999" \
+  -H "Authorization: Bearer $TOKEN_OTHER_TENANT" | jq '.code'
+# 期望: 403
+```
+
+**先运行 → 全部 FAIL → 编码 → 再次运行 → 全部 PASS**
+
+### 前端验证脚本模板
+
+实现页面前，先列出所有 `data-testid` 和期望的 DOM 状态：
+
+```
+验证清单（编码前先确认这些状态不存在 / 行为不正确）：
+- data-testid="xxx-btn-submit"  点击 → 列表刷新，行数增加 1
+- data-testid="xxx-table"       行数 === API 返回 total
+- data-testid="xxx-input-name"  空值提交 → 显示「请输入名称」提示
+```
+
+### 与 VP 三件套的关系
+
+| VP 协议 | 验证优先对应 |
+|---------|------------|
+| VP-Data | 先在环境建好测试数据（curl 确认成功） |
+| VP-Steps | **即为本节验证脚本** — 编码前写好，编码后执行 |
+| VP-Pass | 验证脚本每条命令的期望输出值 |
+
+---
+
 ## Go 后端开发
 
 ### 分层架构

skills-dev/dev-review-plugin/skills/SKILL.md

@@ -1,13 +1,13 @@
 ---
 name: dev-review
-description: 代码评审技能。五视角对抗性扫描法，用于 PR 代码审查、安全评审、质量检查。当执行 /req cr 或独立 PR review 时自动激活。
+description: 代码评审技能。六视角对抗性扫描法（含 Karpathy Scope 审计），用于 PR 代码审查、安全评审、质量检查。当执行 /req cr 或独立 PR review 时自动激活。
 ---
 
 # 代码评审 Skill (dev-review)
 
 ## 概述
 
-独立的代码评审技能，核心方法论是**五视角对抗性扫描法**。
+独立的代码评审技能，核心方法论是**六视角对抗性扫描法**（五个传统安全/健壮性视角 + Karpathy Scope 审计视角）。
 
 **适用场景**：
 - `/req cr [REQ-ID]` — 需求流程中的代码评审阶段
@@ -22,7 +22,7 @@ description: 代码评审技能。五视角对抗性扫描法，用于 PR 代码
 
 | 上游 | 本技能输入 | 本技能输出 | 下游 |
 |------|-----------|-----------|------|
-| dev-coding | PR diff + 开发设计文档 | CR 报告（五视角扫描 + 发现汇总 + 结论） | dev-test |
+| dev-coding | PR diff + 开发设计文档 | CR 报告（六视角扫描 + 发现汇总 + 结论） | dev-test |
 
 ---
 
@@ -67,7 +67,7 @@ description: 代码评审技能。五视角对抗性扫描法，用于 PR 代码
 
 ---
 
-## 五视角对抗性扫描法
+## 六视角对抗性扫描法
 
 ### 总览
 
@@ -146,6 +146,28 @@ file:line — Store.GetByID(id) 缺少 tenant_id 过滤，
 - [ ] Redis 不可用时是否有降级方案？（缓存穿透到数据库）
 - [ ] token 过期/刷新逻辑是否正确？（access vs refresh 不同策略）
 
+### 视角6：Scope 审计者（Karpathy: Simplicity + Surgical）
+
+**思维模式**：每一行变更，需求有没有要求它？
+
+> "Touch only what you must. Clean up only your own mess."
+> "Every changed line should trace directly to the user's request."
+
+扫描清单：
+- [ ] diff 中变更的**每个文件**，是否都在 req-design 变更文件清单中？（超出清单 = 疑似顺手重构）
+- [ ] 新增的函数/方法/结构体，每个都有对应 AC 需要它？
+- [ ] 是否引入了"未来可能用到"的参数、配置项、可选字段、接口抽象？
+- [ ] 是否修改了本次 AC 无关的注释、格式、变量名、import 顺序？
+- [ ] 代码量是否合理？实现简单 AC 超过 200 行须说明必要性
+  （"If you write 200 lines and it could be 50, rewrite it"）
+- [ ] 错误处理是否只覆盖真实会发生的场景？不为不可能的情况写防御代码
+
+**典型发现示例**：
+```
+backend/services/user_service.go:45 — 新增了 WithRetry 参数，但 AC 中无重试需求。
+建议：移除该参数，AC 有需要时再添加。严重度：Low
+```
+
 ---
 
 ## CR 报告模板
@@ -160,7 +182,7 @@ file:line — Store.GetByID(id) 缺少 tenant_id 过滤，
 ### 变更概要
 {1-3 句描述本次变更的目的和范围}
 
-### 五视角扫描结果
+### 六视角扫描结果
 
 #### 1. 攻击者视角
 {扫描发现，或 "未发现问题"}
@@ -177,6 +199,9 @@ file:line — Store.GetByID(id) 缺少 tenant_id 过滤，
 #### 5. 依赖者视角
 {扫描发现，或 "未发现问题"}
 
+#### 6. Scope 审计者视角（Karpathy）
+{扫描发现，或 "所有变更文件均在设计清单范围内，无过度实现"}
+
 ### 审查发现汇总
 
 | # | 严重度 | 文件:行号 | <20><><EFBFBD>角 | 描述 | 建议 |
@@ -221,7 +246,7 @@ file:line — Store.GetByID(id) 缺少 tenant_id 过滤，
 | 文档存在 | CR 任务有附加文档 |
 | 字数 | ≥ 500 字 |
 | 代码引用 | 含 `file:line` 格式的引用 |
-| 五视角扫描 | 含全部 5 个视角章节 |
+| 六视角扫描 | 含全部 6 个视角章节（含 Scope 审计者） |
 | 结论章节 | 含明确的通过/不通过结论 |
 
 ---

skills-dev/karpathy-guidelines-plugin/.claude-plugin/plugin.json

@@ -0,0 +1,9 @@
+{
+  "name": "karpathy-guidelines",
+  "description": "Karpathy 四原则编码行为守则（Think Before Coding / Simplicity First / Surgical Changes / Goal-Driven Execution）。已深度融合到 req 技能工作流各阶段，可独立激活用于任意编码场景。",
+  "version": "1.0.0",
+  "author": "qiudl",
+  "source": "https://github.com/forrestchang/andrej-karpathy-skills",
+  "tags": ["coding-guidelines", "karpathy", "simplicity", "surgical", "goal-driven"],
+  "skills": ["karpathy-guidelines"]
+}

skills-dev/karpathy-guidelines-plugin/skills/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: karpathy-guidelines
+description: Karpathy 四原则编码行为守则。减少 LLM 常见编码错误：过度实现、静默假设、顺手重构、无验证标准。在任意编码场景激活。
+---
+
+# Karpathy Guidelines Skill
+
+> 来源：[andrej-karpathy-skills](https://github.com/forrestchang/andrej-karpathy-skills)
+> 在本项目中已深度融合到 req 技能工作流各阶段。
+
+## 四原则
+
+### 1. Think Before Coding（编前推理）
+> "Don't assume. Don't hide confusion. Surface tradeoffs."
+
+**在写第一行代码前：**
+- 显式列出本次实现的假设（数据格式、边界条件、依赖接口）
+- 如存在多种解读，列出所有方案（附估算），不要静默选择
+- 如有更简单的实现方式，说出来
+- 遇到不清晰的地方，停下来，指出混乱点，提问
+
+**在 req 工作流中：** → 已嵌入 `req-prd` 的「Phase 0 假设倾倒协议」
+
+---
+
+### 2. Simplicity First（简单优先）
+> "Minimum code that solves the problem. Nothing speculative."
+
+**禁止：**
+- 添加未被需求要求的功能
+- 为单次使用的代码添加抽象
+- 添加未被请求的"灵活性"或"可配置性"
+- 为不可能发生的场景写错误处理
+- 写了 200 行但 50 行就够的代码 → 重写
+
+**自检：** "一个高级工程师看这段代码会觉得过度设计吗？" 如果是 → 简化
+
+**在 req 工作流中：** → 已嵌入 `req-design` 过度设计检查 + `dev-review` 第六视角
+
+---
+
+### 3. Surgical Changes（手术式修改）
+> "Touch only what you must. Clean up only your own mess."
+
+**修改现有代码时：**
+- 不要"顺手改进"相邻代码、注释或格式
+- 不要重构没有损坏的代码
+- 匹配现有代码风格，即使你会做不同的选择
+- 发现不相关的死代码 → 提及但不删除
+
+**你的变更造成的孤儿：**
+- 删除你的变更导致的无用 import/变量/函数
+- 不要删除已存在的死代码（除非被要求）
+
+**铁律：** diff 中每一行修改都应该可以追溯到用户的需求
+
+**在 req 工作流中：** → 已嵌入 `dev-review` 第六视角 + `check-surgical.sh` Harness 脚本
+
+---
+
+### 4. Goal-Driven Execution（目标驱动执行）
+> "Define success criteria. Loop until verified."
+
+**将请求转化为可验证目标：**
+- "加验证" → "为无效输入写测试，然后让它通过"
+- "修 bug" → "写一个复现 bug 的测试，然后让它通过"
+- "重构 X" → "确保测试在重构前后都通过"
+
+**多步任务需要说明计划：**
+```
+1. [步骤] → 验证: [检查项]
+2. [步骤] → 验证: [检查项]
+3. [步骤] → 验证: [检查项]
+```
+
+**在 req 工作流中：** → 已嵌入 `dev-coding` 的「Step 0 验证优先」+ VP 三件套协议
+
+---
+
+## 与 req 工作流的映射
+
+| 原则 | 生效阶段 | 落地机制 |
+|------|---------|---------|
+| Think Before Coding | req-prd 启动前 | Phase 0 假设倾倒协议 |
+| Simplicity First | req-design + dev-review | 过度设计检查 + 第六视角 |
+| Surgical Changes | dev-review + CI | 第六视角 + check-surgical.sh |
+| Goal-Driven Execution | dev-coding | Step 0 验证优先 + VP 三件套 |
+
+## 反模式速查
+
+| 场景 | ❌ LLM 常犯 | ✅ 正确做法 |
+|------|-----------|-----------|
+| "做个导出功能" | 静默假设格式/字段，直接实现 | 列出3种解读，等用户确认 |
+| "让搜索更快" | 同时加缓存+索引+async | 列出3种"更快"含义，确认再做 |
+| "加折扣计算" | Strategy+Abstract+Enum，50行 | 一个函数，3行 |
+| "修空邮件bug" | 顺手加用户名校验+类型注解 | 只改空邮件的那2行 |
+| "修认证bug" | 直接修改，无验证标准 | 先写复现测试，修复后验证通过 |

skills-dev/review-checklist-plugin/checklists/general.md

@@ -1,6 +1,27 @@
 # 通用代码评审检查清单
 
-适用于所有项目，补充五视角扫描法。
+适用于所有项目，补充六视角扫描法（五传统视角 + Karpathy Scope 视角）。
+
+## Karpathy 反模式速查（Scope 审计者视角辅助）
+
+基于 [andrej-karpathy-skills](https://github.com/forrestchang/andrej-karpathy-skills) EXAMPLES.md 提炼。
+
+### ❌ 反模式 → ✅ 正确做法
+
+| 场景 | 反模式（LLM 常犯） | 正确做法 |
+|------|-----------------|---------|
+| "做个导出功能" | 静默假设文件格式/字段/分页，直接实现 | 列出3种解读（API/文件/任务队列），问用户选哪种 |
+| "让搜索更快" | 同时加缓存+索引+async，200行 | 列出3种"更快"含义+估算，等确认再做 |
+| "加个折扣计算" | Strategy+Abstract+Enum+DataClass，50行 | `def calc_discount(amount, pct): return amount * pct / 100` |
+| "修保存偏好的bug" | 顺手加 merge/validate/notify/cache | 只改最小范围，加注释"其他特性按需再加" |
+| "修空邮件校验bug" | 顺手加用户名校验+类型注解+docstring | 只改空邮件的那2行 |
+| "加日志到上传函数" | 改引号风格+加类型注解+重构return逻辑 | 只加日志，保持原有代码风格 |
+| "修认证bug" | "我会检查代码并做改进"（无标准） | 先写测试复现bug，再实现修复，再跑测试 |
+| "加限流" | 一次提交Redis+多策略+配置系统+监控 | 分4步，每步独立可验证可部署 |
+
+### 触发关键词（出现时加强 Scope 审计）
+
+`export/导出` `faster/更快` `manage/管理` `notify/通知` `fix/修复` `improve/改进` `refactor/重构` `add/添加`
 
 ## API 设计
 - [ ] RESTful 命名是否规范？（复数名词、无动词）

skills-req/req-prototype-plugin/skills/SKILL.md

@@ -286,6 +286,24 @@ generated_at: "<timestamp>"
 | HTML 文件超过 5MB | 精简样式或拆分多版本上传 |
 | iframe 不显示 | 检查 `prototype_urls` 字段是否非空：`mcp__ai-proj__get_requirement` 确认 |
 
+### 原型展示规则
+
+**原型必须用 iframe 展示**（不得用截图、图片嵌入或内联 HTML 方式替代）。
+
+- PRD 文档的「4.2 界面原型」章节：使用 `<iframe>` 标签嵌入原型 URL，而非 `![](...)` 图片
+- 需求详情页原型预览卡片：后端渲染 iframe，前端不得将 `prototype_urls` 内容渲染为 `<img>`
+- 典型正确写法（PRD 文档内）：
+
+```html
+<iframe src="/api/v1/uploads/prototypes/proto_xxx.html"
+        width="100%" height="600" frameborder="0"
+        style="border-radius:8px;border:1px solid #e5e7eb;">
+</iframe>
+```
+
+> 背景：REQ-20260420-0031 反馈原型图用图片方式展示，无法交互预览，改为 iframe 后可正常使用。
+
+
 ### Stitch 模式
 
 | 异常 | 处理 |

skills-req/req-retro-plugin/skills/SKILL.md

@@ -23,10 +23,11 @@ description: 复盘总结。自动采集数据、计算质量评分、跨需求
 ### 2. 质量评分（Quality Score）
 
 ```
-QS = lookback_pass_rate × 0.3
+QS = lookback_pass_rate × 0.25
-   + audit_defect_score × 0.3
+   + audit_defect_score × 0.25
-   + cr_density_score × 0.2
+   + cr_density_score × 0.15
-   + test_pass_rate × 0.2
+   + test_pass_rate × 0.15
+   + karpathy_score × 0.20        ← Karpathy 四原则执行质量
 
 audit_defect_score:
   0 缺陷 = 100
@@ -38,8 +39,26 @@ audit_defect_score:
 cr_density_score:
   100 - (发现数 / 变更行数 × 1000)
   下限 0，上限 100
+
+karpathy_score（四原则执行质量，各 25 分，共 100）:
+  Think Before PRD (25):
+    PRD 无返工 → 25 | 因需求误解返工 1 次 → 15 | ≥2 次 → 0
+  Simplicity (25):
+    CR 第六视角无 Scope 违规 → 25 | 1 个 Low → 20 | ≥1 个 Medium+ → 10 | High+ → 0
+  Surgical (25):
+    check-surgical.sh PASS + CR 无顺手改 → 25 | 警告但未阻塞 → 15 | FAIL → 0
+  Goal-Driven (25):
+    dev-coding 有验证脚本记录（VP-Steps 先于代码执行）→ 25 | 事后补写 → 15 | 无 → 0
 ```
 
+**Karpathy 数据来源**（按优先级）：
+1. dev-coding 任务文档中是否有「验证脚本」节
+2. CR 报告第六视角的发现数和严重度
+3. `git log` 中是否有 check-surgical.sh baseline 更新提交（说明有过违规）
+4. PRD 任务文档的版本数（> 1 说明有返工）
+
+**无数据时**：各维度默认 20 分（中性），在报告中标注 `(无记录，按中性计算)`
+
 ### 3. 历史趋势对比
 
 读取 `memory/retro_metrics.md` 的明细数据：
@@ -87,10 +106,12 @@ AI: "近 5 次需求中 3 次 audit 发现了 {缺陷类型}。
 
 追加一行到明细：
 ```
-| REQ-xxx | 2026-04-18 | 5h44m | 92 | 2 | 279 | 3 | frontend |
+| REQ-xxx | 2026-04-18 | 5h44m | 92 | 2 | 279 | 3 | frontend | 85 |
 ```
 
-更新汇总：重新计算近 10 次平均值和趋势箭头（↑↓→）。
+列说明：`REQ | date | time | QS | audit_defects | changed_lines | cr_findings | type | karpathy_score`
+
+更新汇总：重新计算近 10 次平均值和趋势箭头（↑↓→），包含 karpathy_score 趋势。
 
 超过 30 条明细 → 最早的移入 `retro_metrics_archive.md`。
 
@@ -116,10 +137,19 @@ AI: "近 5 次需求中 3 次 audit 发现了 {缺陷类型}。
 ## 质量指标
 | 指标 | 本次 | 近10次均 | 对比 |
 |------|------|---------|------|
-| 质量分 | 92 | 85 | ↑ |
+| 质量分 (QS) | 92 | 85 | ↑ |
 | audit 缺陷 | 2(低) | 3.2 | ↓ |
 | CR 发现 | 0 | 1.5 | ↓ |
 | 测试通过率 | 100% | 95% | ↑ |
+| Karpathy 分 | 85 | 78 | ↑ |
+
+## Karpathy 四原则评分
+| 原则 | 得分 | 说明 |
+|------|------|------|
+| Think Before PRD | 25/25 | PRD 无返工 |
+| Simplicity | 20/25 | CR 第六视角发现 1 个 Low |
+| Surgical | 25/25 | check-surgical.sh PASS |
+| Goal-Driven | 15/25 | 验证脚本为事后补写 |
 
 ## git 统计
 | 提交数 | 变更文件 | +行 | -行 |

skills-req/req-test-gate-plugin/skills/SKILL.md

@@ -87,12 +87,24 @@ done
 **报告格式**：
 ```
 ### 约定检查 (Gate 0B)
-| 脚本 | 结果 | 详情 |
+| 脚本 | 类型 | 结果 | 详情 |
-|------|------|------|
+|------|------|------|------|
-| check-architecture.sh | ✅ PASS | 5 rules, all within baseline |
+| check-architecture.sh | Ratchet | ✅ PASS | 5 rules, all within baseline |
-| check-modal-safety.sh | ✅ PASS | 0 violations |
+| check-modal-safety.sh | Hard wall | ✅ PASS | 0 violations |
+| check-surgical.sh | Ratchet | ✅ PASS | 0 format-only violations (baseline=0) |
 ```
 
+**本项目已建立的约定检查脚本**：
+
+| 脚本 | 类型 | 检测内容 | 来源 |
+|------|------|---------|------|
+| `check-architecture.sh` | Ratchet | Handler 直接引用 database/ 层 | 分层架构规范 |
+| `check-modal-safety.sh` | Hard wall | Modal.success 后立即操作 UI | REQ-20260416 |
+| `check-surgical.sh` | Ratchet | PR diff 中疑似仅注释/格式变更的文件 | Karpathy Surgical（REQ-20260421-0003）|
+
+> `check-surgical.sh` 使用 Ratchet 模式：`.surgical-baseline.json` 记录基线，违规数只能降不能升。
+> 首次无基线时仅告警，不阻塞。运行 `./scripts/check-surgical.sh baseline` 建立基线。
+
 > 这样 Harness 建立的约定脚本会在每次 `/req test` 时自动运行，无需手动执行 `/harness report`。
 
 ---