dev-playbooks-cn 1.4.0 → 1.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dev-playbooks-cn",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "description": "AI-driven spec-based development workflow",
   "keywords": [
     "devbooks",

package/skills/devbooks-convergence-audit/SKILL.md

@@ -0,0 +1,394 @@
+---
+name: devbooks-convergence-audit
+description: devbooks-convergence-audit：以证据优先、声明存疑的原则评估 DevBooks 工作流收敛性，检测"西西弗斯反模式"和"假完成"。主动验证而非信任文档声明。用户说"评估收敛性/检查升级健康度/西西弗斯检测/工作流审计"等时使用。
+allowed-tools:
+  - Glob
+  - Grep
+  - Read
+  - Bash
+---
+
+# DevBooks：收敛性审计（Convergence Audit）
+
+## 核心原则：反迷惑设计
+
+> **黄金法则**：**证据 > 声明**。永远不要相信文档中的任何断言，必须通过可验证的证据确认。
+
+### AI 容易被迷惑的场景（必须防范）
+
+| 迷惑场景 | AI 错误行为 | 正确行为 |
+|----------|-------------|----------|
+| 文档写 `Status: Done` | 相信已完成 | 验证：测试是否真的全绿？证据是否存在？ |
+| AC 矩阵全部 `[x]` | 相信全覆盖 | 验证：每个 AC 对应的测试文件是否存在且通过？ |
+| 文档写"测试通过" | 相信通过 | 验证：实际运行测试或检查 CI 日志时间戳 |
+| `evidence/` 目录存在 | 相信有证据 | 验证：目录非空？内容是否为有效测试日志？ |
+| tasks.md 全部 `[x]` | 相信已实现 | 验证：对应代码文件是否存在且有实质内容？ |
+| 提交信息说"修复了" | 相信已修复 | 验证：相关测试是否从红变绿？ |
+
+### 反迷惑三原则
+
+```
+1. 声明存疑（Distrust Declarations）
+   - 任何文档中的"完成/通过/覆盖"声明都是待验证的假设
+   - 默认立场：声明可能是错误的、过时的、或乐观的
+
+2. 证据优先（Evidence First）
+   - 代码/测试结果是唯一真理
+   - 日志时间戳必须晚于最后一次代码修改
+   - 空目录/空文件 = 无证据
+
+3. 交叉验证（Cross Validation）
+   - 声明 vs 证据：检查是否一致
+   - 代码 vs 测试：检查是否匹配
+   - 多个文档：检查是否矛盾
+```
+
+---
+
+## 验证检查清单（逐项执行）
+
+### 检查 1：Status 字段真实性验证
+
+**文档声明**：`verification.md` 中 `Status: Done` 或 `Status: Verified`
+
+**验证步骤**：
+```bash
+# 1. 检查 verification.md 是否存在
+[[ -f "verification.md" ]] || echo "❌ verification.md 不存在"
+
+# 2. 检查 evidence/green-final/ 是否有内容
+if [[ -z "$(ls -A evidence/green-final/ 2>/dev/null)" ]]; then
+  echo "❌ Status 声称完成，但 evidence/green-final/ 为空"
+fi
+
+# 3. 检查证据时间戳是否晚于代码最后修改
+code_mtime=$(stat -f %m src/ 2>/dev/null || stat -c %Y src/)
+evidence_mtime=$(stat -f %m evidence/green-final/* 2>/dev/null | sort -n | tail -1)
+if [[ $evidence_mtime -lt $code_mtime ]]; then
+  echo "❌ 证据时间早于代码修改，证据可能过时"
+fi
+```
+
+**迷惑检测**：
+- ⚠️ Status=Done 但 evidence/ 为空 → **假完成**
+- ⚠️ Status=Done 但证据时间戳过旧 → **过时证据**
+- ⚠️ Status=Done 但测试实际运行失败 → **虚假状态**
+
+---
+
+### 检查 2：AC 覆盖矩阵真实性验证
+
+**文档声明**：AC 矩阵中 `[x]` 表示已覆盖
+
+**验证步骤**：
+```bash
+# 1. 提取所有声称已覆盖的 AC
+grep -E '^\| AC-[0-9]+.*\[x\]' verification.md | while read line; do
+  ac_id=$(echo "$line" | grep -oE 'AC-[0-9]+')
+  test_id=$(echo "$line" | grep -oE 'T-[0-9]+')
+
+  # 2. 验证对应测试是否存在
+  if ! grep -rq "$test_id\|$ac_id" tests/; then
+    echo "❌ $ac_id 声称已覆盖，但找不到对应测试"
+  fi
+done
+
+# 3. 实际运行测试验证（最可靠）
+npm test 2>&1 | tee /tmp/test-output.log
+if grep -q "FAIL\|Error\|failed" /tmp/test-output.log; then
+  echo "❌ AC 声称全覆盖，但测试实际有失败"
+fi
+```
+
+**迷惑检测**：
+- ⚠️ AC 打勾但对应测试文件不存在 → **虚假覆盖**
+- ⚠️ AC 打勾但测试实际失败 → **假绿**
+- ⚠️ AC 打勾但测试内容为空/占位符 → **占位符测试**
+
+---
+
+### 检查 3：tasks.md 完成度真实性验证
+
+**文档声明**：tasks.md 中 `[x]` 表示已完成
+
+**验证步骤**：
+```bash
+# 1. 提取所有声称已完成的任务
+grep -E '^\- \[x\]' tasks.md | while read line; do
+  # 2. 提取任务描述中的关键词（函数名/文件名/功能）
+  keywords=$(echo "$line" | grep -oE '[A-Za-z]+[A-Za-z0-9]*' | head -5)
+
+  # 3. 验证代码中是否有对应实现
+  for kw in $keywords; do
+    if ! grep -rq "$kw" src/; then
+      echo "⚠️ 任务声称完成，但代码中找不到关键词: $kw"
+    fi
+  done
+done
+
+# 4. 检查是否有"骨架代码"（只有函数签名没有实现）
+grep -rE 'throw new Error\(.*not implemented|TODO|FIXME|pass$|\.\.\.}' src/ && \
+  echo "⚠️ 发现未实现的占位符代码"
+```
+
+**迷惑检测**：
+- ⚠️ 任务打勾但代码不存在 → **虚假完成**
+- ⚠️ 任务打勾但代码是占位符 → **骨架代码**
+- ⚠️ 任务打勾但功能不可调用 → **死代码**
+
+---
+
+### 检查 4：证据有效性验证
+
+**文档声明**：`evidence/` 目录包含测试证据
+
+**验证步骤**：
+```bash
+# 1. 检查目录是否存在且非空
+if [[ ! -d "evidence" ]] || [[ -z "$(ls -A evidence/)" ]]; then
+  echo "❌ evidence/ 不存在或为空"
+  exit 1
+fi
+
+# 2. 检查证据文件是否有实质内容
+for f in evidence/**/*; do
+  if [[ -f "$f" ]]; then
+    lines=$(wc -l < "$f")
+    if [[ $lines -lt 5 ]]; then
+      echo "⚠️ 证据文件内容过少: $f ($lines 行)"
+    fi
+
+    # 3. 检查是否为有效测试日志（包含测试框架输出特征）
+    if ! grep -qE 'PASS|FAIL|✓|✗|passed|failed|test|spec' "$f"; then
+      echo "⚠️ 证据文件不像测试日志: $f"
+    fi
+  fi
+done
+
+# 4. 检查 red-baseline 证据是否真的是红色（有失败）
+if [[ -d "evidence/red-baseline" ]]; then
+  if ! grep -rqE 'FAIL|Error|✗|failed' evidence/red-baseline/; then
+    echo "❌ red-baseline 声称是红色，但没有失败记录"
+  fi
+fi
+
+# 5. 检查 green-final 证据是否真的是绿色（全通过）
+if [[ -d "evidence/green-final" ]]; then
+  if grep -rqE 'FAIL|Error|✗|failed' evidence/green-final/; then
+    echo "❌ green-final 声称是绿色，但包含失败记录"
+  fi
+fi
+```
+
+**迷惑检测**：
+- ⚠️ evidence/ 存在但内容为空 → **空证据**
+- ⚠️ 证据文件太小（< 5 行）→ **占位符证据**
+- ⚠️ red-baseline 没有失败记录 → **伪造红色**
+- ⚠️ green-final 包含失败记录 → **伪造绿色**
+
+---
+
+### 检查 5：Git 历史交叉验证
+
+**原理**：Git 历史不会撒谎，用它来验证文档声明
+
+**验证步骤**：
+```bash
+# 1. 检查声称完成的变更是否有对应的代码提交
+change_id="xxx"
+commits=$(git log --oneline --all --grep="$change_id" | wc -l)
+if [[ $commits -eq 0 ]]; then
+  echo "❌ 变更 $change_id 声称完成，但 git 历史中没有相关提交"
+fi
+
+# 2. 检查测试文件是否在代码之后添加（TDD 违规检测）
+for test_file in tests/**/*.test.*; do
+  test_added=$(git log --format=%at --follow -- "$test_file" | tail -1)
+  # 找到对应的源文件
+  src_file=$(echo "$test_file" | sed 's/tests/src/' | sed 's/.test//')
+  if [[ -f "$src_file" ]]; then
+    src_added=$(git log --format=%at --follow -- "$src_file" | tail -1)
+    if [[ $test_added -gt $src_added ]]; then
+      echo "⚠️ 测试后于代码添加（非 TDD）: $test_file"
+    fi
+  fi
+done
+
+# 3. 检查是否有"一次性大提交"（可能是绕过流程）
+git log --oneline -20 | while read line; do
+  commit=$(echo "$line" | cut -d' ' -f1)
+  files_changed=$(git show --stat "$commit" | grep -E '[0-9]+ file' | grep -oE '[0-9]+' | head -1)
+  if [[ $files_changed -gt 20 ]]; then
+    echo "⚠️ 大提交检测: $commit 修改了 $files_changed 个文件，可能绕过增量验证"
+  fi
+done
+```
+
+**迷惑检测**：
+- ⚠️ 声称完成但无 git 提交 → **虚假变更**
+- ⚠️ 测试后于代码添加 → **事后补测试**
+- ⚠️ 大量文件一次提交 → **绕过增量验证**
+
+---
+
+### 检查 6：实时测试运行验证（最可靠）
+
+**原理**：不信任任何日志，实际运行测试
+
+**验证步骤**：
+```bash
+# 1. 运行完整测试
+echo "=== 实时测试验证 ==="
+npm test 2>&1 | tee /tmp/live-test.log
+
+# 2. 检查结果
+if grep -qE 'FAIL|Error|failed' /tmp/live-test.log; then
+  echo "❌ 实时测试失败，文档声明不可信"
+  grep -E 'FAIL|Error|failed' /tmp/live-test.log
+else
+  echo "✅ 实时测试通过"
+fi
+
+# 3. 对比实时结果与证据文件
+if [[ -f "evidence/green-final/latest.log" ]]; then
+  live_pass=$(grep -c 'PASS\|✓\|passed' /tmp/live-test.log)
+  evidence_pass=$(grep -c 'PASS\|✓\|passed' evidence/green-final/latest.log)
+  if [[ $live_pass -ne $evidence_pass ]]; then
+    echo "⚠️ 实时通过数 ($live_pass) ≠ 证据通过数 ($evidence_pass)"
+  fi
+fi
+```
+
+**迷惑检测**：
+- ⚠️ 证据说绿色但实时运行失败 → **过时证据/假绿**
+- ⚠️ 实时通过数与证据不符 → **证据伪造/环境差异**
+
+---
+
+## 综合评分算法
+
+### 可信度评分（0-100）
+
+```python
+def calculate_trustworthiness(checks):
+    score = 100
+
+    # 严重问题（每个 -20 分）
+    critical = [
+        "证据为空",
+        "实时测试失败",
+        "Status 声称完成但测试失败",
+        "green-final 包含失败记录"
+    ]
+
+    # 警告问题（每个 -10 分）
+    warnings = [
+        "证据时间戳过旧",
+        "AC 对应测试不存在",
+        "占位符代码",
+        "大提交检测"
+    ]
+
+    # 轻微问题（每个 -5 分）
+    minor = [
+        "测试后于代码添加",
+        "证据文件过小"
+    ]
+
+    for issue in checks.critical_issues:
+        score -= 20
+    for issue in checks.warnings:
+        score -= 10
+    for issue in checks.minor_issues:
+        score -= 5
+
+    return max(0, score)
+```
+
+### 收敛性判定
+
+| 可信度 | 判定 | 建议 |
+|--------|------|------|
+| 90-100 | ✅ 可信收敛 | 继续当前流程 |
+| 70-89 | ⚠️ 部分可信 | 需要补充验证 |
+| 50-69 | 🟠 存疑 | 需要返工部分环节 |
+| < 50 | 🔴 不可信 | 西西弗斯困境，需要全面审查 |
+
+---
+
+## 输出格式
+
+```markdown
+# DevBooks 收敛性审计报告（反迷惑版）
+
+## 审计原则
+本报告采用"证据优先、声明存疑"原则，所有结论基于可验证证据，而非文档声明。
+
+## 声明 vs 证据对比
+
+| 检查项 | 文档声明 | 实际验证 | 结论 |
+|--------|----------|----------|------|
+| Status | Done | 测试实际失败 | ❌ 假完成 |
+| AC 覆盖 | 5/5 已打勾 | 2 个 AC 无对应测试 | ❌ 虚假覆盖 |
+| 测试状态 | 全绿 | 实时运行 3 个失败 | ❌ 过时证据 |
+| tasks.md | 10/10 完成 | 3 个任务代码不存在 | ❌ 虚假完成 |
+| evidence/ | 存在 | 目录非空，内容有效 | ✅ 有效 |
+
+## 可信度评分
+
+**总分**：45/100 🔴 不可信
+
+**扣分明细**：
+- -20：Status=Done 但实时测试失败
+- -20：AC 声称全覆盖但 2 个无测试
+- -10：tasks.md 3 个任务无代码
+- -5：证据时间戳早于代码修改
+
+## 迷惑检测结果
+
+### 🔴 检测到的假完成
+1. `change-auth`：Status=Done，但 `npm test` 失败 3 个
+2. `fix-cache`：AC-003 打勾，但 `tests/cache.test.ts` 不存在
+
+### 🟡 可疑项
+1. `refactor-api`：evidence/green-final/ 时间戳早于最后代码提交 2 天
+2. `feature-login`：tasks.md 全部打勾，但 `src/login.ts` 包含 TODO
+
+## 真实状态判定
+
+| 变更包 | 声明状态 | 真实状态 | 差距 |
+|--------|----------|----------|------|
+| change-auth | Done | 测试失败 | 🔴 严重 |
+| fix-cache | Verified | 覆盖不全 | 🟠 中等 |
+| refactor-api | Ready | 证据过时 | 🟡 轻微 |
+
+## 建议行动
+
+### 立即行动
+1. 将 `change-auth` 状态回退到 `In Progress`
+2. 为 `fix-cache` 的 AC-003 补充测试
+
+### 短期改进
+1. 建立证据时效性检查（证据必须晚于代码）
+2. AC 打勾前强制运行对应测试
+
+### 流程改进
+1. 禁止手动修改 Status，只能通过脚本验证后自动更新
+2. CI 集成收敛性检查，阻止假完成合入
+```
+
+---
+
+## 完成状态
+
+**状态**：✅ AUDIT_COMPLETED
+
+**核心发现**：
+- 文档声明可信度：X%
+- 检测到的假完成：N 个
+- 需要返工的变更：M 个
+
+**下一步**：
+- 假完成 → 立即回退状态，重新验证
+- 存疑项 → 补充证据或重新运行测试
+- 可信项 → 继续当前流程