dev-playbooks-cn 1.4.0 → 1.5.1

package/bin/devbooks.js

@@ -24,7 +24,7 @@ import path from 'path';
 import os from 'os';
 import { fileURLToPath } from 'url';
 import { spawn } from 'child_process';
-import { checkbox, confirm } from '@inquirer/prompts';
+import { checkbox, confirm, select } from '@inquirer/prompts';
 import chalk from 'chalk';
 import ora from 'ora';
 
@@ -45,6 +45,15 @@ const SKILLS_SUPPORT = {
   BASIC: 'basic'     // 仅基础指令（无独立 Skills 概念）
 };
 
+// ============================================================================
+// Skills 安装范围
+// ============================================================================
+
+const INSTALL_SCOPE = {
+  GLOBAL: 'global',   // 全局安装（~/.claude/skills 等）
+  PROJECT: 'project'  // 项目级安装（.claude/skills 等）
+};
+
 // ============================================================================
 // AI 工具配置
 // ============================================================================
@@ -540,12 +549,68 @@ async function promptToolSelection(projectDir) {
   return selectedTools;
 }
 
+async function promptInstallScope(projectDir, selectedTools) {
+  // 检查是否有需要安装 Skills 的工具
+  const fullSupportTools = selectedTools.filter(id => {
+    const tool = AI_TOOLS.find(t => t.id === id);
+    return tool && tool.skillsSupport === SKILLS_SUPPORT.FULL;
+  });
+
+  if (fullSupportTools.length === 0) {
+    return INSTALL_SCOPE.PROJECT; // 没有完整 Skills 支持的工具，默认项目级
+  }
+
+  // 读取已保存的配置
+  const config = loadConfig(projectDir);
+  const savedScope = config.installScope;
+
+  console.log();
+  console.log(chalk.bold('📦 Skills 安装位置'));
+  console.log(chalk.gray('─'.repeat(50)));
+  console.log();
+
+  const scope = await select({
+    message: 'Skills 安装到哪里？',
+    choices: [
+      {
+        name: `项目级 ${chalk.gray('(.claude/skills 等，仅当前项目可用)')}`,
+        value: INSTALL_SCOPE.PROJECT,
+        description: '推荐：Skills 随项目走，不影响其他项目'
+      },
+      {
+        name: `全局 ${chalk.gray('(~/.claude/skills 等，所有项目共享)')}`,
+        value: INSTALL_SCOPE.GLOBAL,
+        description: '所有项目共享同一套 Skills'
+      }
+    ],
+    default: savedScope || INSTALL_SCOPE.PROJECT
+  });
+
+  return scope;
+}
+
 
 // ============================================================================
 // 安装 Skills（Claude Code, Codex CLI, Qoder）
 // ============================================================================
 
-function installSkills(toolIds, update = false) {
+function getSkillsDestDir(tool, scope, projectDir) {
+  // 根据安装范围确定目标目录
+  if (scope === INSTALL_SCOPE.PROJECT) {
+    // 项目级安装：使用项目目录下的相对路径
+    if (tool.id === 'claude') {
+      return path.join(projectDir, '.claude', 'skills');
+    } else if (tool.id === 'codex') {
+      return path.join(projectDir, '.codex', 'skills');
+    } else if (tool.id === 'opencode') {
+      return path.join(projectDir, '.opencode', 'skill');
+    }
+  }
+  // 全局安装：使用工具定义的全局目录
+  return tool.skillsDir;
+}
+
+function installSkills(toolIds, projectDir, scope = INSTALL_SCOPE.GLOBAL, update = false) {
   const results = [];
 
   for (const toolId of toolIds) {
@@ -555,7 +620,7 @@ function installSkills(toolIds, update = false) {
     // Claude Code / Codex CLI / OpenCode（含 oh-my-opencode）支持相同格式的 Skills
     if ((toolId === 'claude' || toolId === 'codex' || toolId === 'opencode') && tool.skillsDir) {
       const skillsSrcDir = path.join(__dirname, '..', 'skills');
-      const skillsDestDir = tool.skillsDir;
+      const skillsDestDir = getSkillsDestDir(tool, scope, projectDir);
 
       if (!fs.existsSync(skillsSrcDir)) continue;
 
@@ -601,7 +666,9 @@ function installSkills(toolIds, update = false) {
         type: 'skills',
         count: installedCount,
         total: skillDirs.length,
-        removed: removedCount
+        removed: removedCount,
+        scope: scope,
+        path: skillsDestDir
       });
     }
 
@@ -1013,7 +1080,7 @@ function createProjectStructure(projectDir) {
 // 保存配置
 // ============================================================================
 
-function saveConfig(toolIds, projectDir) {
+function saveConfig(toolIds, projectDir, installScope = INSTALL_SCOPE.PROJECT) {
   const configPath = path.join(projectDir, '.devbooks', 'config.yaml');
 
   // 读取现有配置或创建新配置
@@ -1033,6 +1100,17 @@ function saveConfig(toolIds, projectDir) {
     configContent = configContent.trimEnd() + '\n\n' + toolsYaml + '\n';
   }
 
+  // 更新 install_scope 部分
+  const scopeYaml = `install_scope: ${installScope}`;
+
+  if (configContent.includes('install_scope:')) {
+    // 替换现有的 install_scope 部分
+    configContent = configContent.replace(/install_scope:.*/, scopeYaml);
+  } else {
+    // 追加 install_scope 部分
+    configContent = configContent.trimEnd() + '\n\n' + scopeYaml + '\n';
+  }
+
   fs.writeFileSync(configPath, configContent);
 }
 
@@ -1040,23 +1118,26 @@ function loadConfig(projectDir) {
   const configPath = path.join(projectDir, '.devbooks', 'config.yaml');
 
   if (!fs.existsSync(configPath)) {
-    return { aiTools: [] };
+    return { aiTools: [], installScope: null };
   }
 
   const content = fs.readFileSync(configPath, 'utf-8');
-  const match = content.match(/ai_tools:\s*([\s\S]*?)(?=\n\w|\n$|$)/);
-
-  if (!match) {
-    return { aiTools: [] };
-  }
-
-  const tools = match[1]
-    .split('\n')
-    .map(line => line.trim())
-    .filter(line => line.startsWith('-'))
-    .map(line => line.replace(/^-\s*/, '').trim());
 
-  return { aiTools: tools };
+  // 解析 ai_tools
+  const toolsMatch = content.match(/ai_tools:\s*([\s\S]*?)(?=\n\w|\n$|$)/);
+  const tools = toolsMatch
+    ? toolsMatch[1]
+        .split('\n')
+        .map(line => line.trim())
+        .filter(line => line.startsWith('-'))
+        .map(line => line.replace(/^-\s*/, '').trim())
+    : [];
+
+  // 解析 install_scope
+  const scopeMatch = content.match(/install_scope:\s*(\w+)/);
+  const installScope = scopeMatch ? scopeMatch[1] : null;
+
+  return { aiTools: tools, installScope };
 }
 
 // ============================================================================
@@ -1072,6 +1153,7 @@ async function initCommand(projectDir, options) {
 
   // 确定选择的工具
   let selectedTools;
+  let installScope = INSTALL_SCOPE.PROJECT; // 默认项目级安装
 
   if (options.tools) {
     if (options.tools === 'all') {
@@ -1084,8 +1166,16 @@ async function initCommand(projectDir, options) {
       );
     }
     console.log(chalk.blue('ℹ') + ` 非交互式模式：${selectedTools.length > 0 ? selectedTools.join(', ') : '无'}`);
+
+    // 非交互式模式下，检查 --scope 选项
+    if (options.scope) {
+      installScope = options.scope === 'global' ? INSTALL_SCOPE.GLOBAL : INSTALL_SCOPE.PROJECT;
+    }
   } else {
     selectedTools = await promptToolSelection(projectDir);
+
+    // 交互式选择安装范围
+    installScope = await promptInstallScope(projectDir, selectedTools);
   }
 
   // 创建项目结构
@@ -1093,8 +1183,8 @@ async function initCommand(projectDir, options) {
   const templateCount = createProjectStructure(projectDir);
   spinner.succeed(`创建了 ${templateCount} 个模板文件`);
 
-  // 保存配置
-  saveConfig(selectedTools, projectDir);
+  // 保存配置（包含安装范围）
+  saveConfig(selectedTools, projectDir, installScope);
 
   if (selectedTools.length === 0) {
     console.log();
@@ -1111,12 +1201,16 @@ async function initCommand(projectDir, options) {
 
   if (fullSupportTools.length > 0) {
     const skillsSpinner = ora('安装 Skills...').start();
-    const skillsResults = installSkills(fullSupportTools);
+    const skillsResults = installSkills(fullSupportTools, projectDir, installScope);
     skillsSpinner.succeed('Skills 安装完成');
 
     for (const result of skillsResults) {
       if (result.count > 0) {
-        console.log(chalk.gray(`  └ ${result.tool}: ${result.count}/${result.total} 个 ${result.type}`));
+        const scopeLabel = result.scope === INSTALL_SCOPE.PROJECT ? '项目级' : '全局';
+        console.log(chalk.gray(`  └ ${result.tool}: ${result.count}/${result.total} 个 ${result.type} (${scopeLabel})`));
+        if (result.path) {
+          console.log(chalk.gray(`    → ${result.path}`));
+        }
       } else if (result.note) {
         console.log(chalk.gray(`  └ ${result.tool}: ${result.note}`));
       }
@@ -1217,6 +1311,7 @@ async function updateCommand(projectDir) {
   // 加载配置
   const config = loadConfig(projectDir);
   const configuredTools = config.aiTools;
+  const installScope = config.installScope || INSTALL_SCOPE.PROJECT;
 
   if (configuredTools.length === 0) {
     console.log(chalk.yellow('⚠') + ` 未配置任何 AI 工具。运行 \`${CLI_COMMAND} init\` 进行配置。`);
@@ -1227,13 +1322,17 @@ async function updateCommand(projectDir) {
     const tool = AI_TOOLS.find(t => t.id === id);
     return tool ? tool.name : id;
   });
-  console.log(chalk.blue('ℹ') + ` 检测到已配置的工具: ${toolNames.join(', ')}`);
+  const scopeLabel = installScope === INSTALL_SCOPE.PROJECT ? '项目级' : '全局';
+  console.log(chalk.blue('ℹ') + ` 检测到已配置的工具: ${toolNames.join(', ')} (${scopeLabel}安装)`);
 
-  // 更新 Skills（全局目录）
-  const skillsResults = installSkills(configuredTools, true);
+  // 更新 Skills（使用配置中保存的安装范围）
+  const skillsResults = installSkills(configuredTools, projectDir, installScope, true);
   for (const result of skillsResults) {
     if (result.count > 0) {
       console.log(chalk.green('✓') + ` ${result.tool} ${result.type}: 更新了 ${result.count}/${result.total} 个`);
+      if (result.path) {
+        console.log(chalk.gray(`    → ${result.path}`));
+      }
     }
     if (result.removed && result.removed > 0) {
       console.log(chalk.green('✓') + ` ${result.tool} ${result.type}: 清理了 ${result.removed} 个已删除的技能`);
@@ -1375,6 +1474,8 @@ function showHelp() {
   console.log(chalk.cyan('选项:'));
   console.log('  --tools <tools>    非交互式指定 AI 工具');
   console.log('                     可用值: all, none, 或逗号分隔的工具 ID');
+  console.log('  --scope <scope>    Skills 安装位置 (非交互式模式)');
+  console.log('                     可用值: project (默认), global');
   console.log('  --from <framework> 迁移来源框架 (openspec, speckit)');
   console.log('  --dry-run          模拟运行，不实际修改文件');
   console.log('  --keep-old         迁移后保留原目录');
@@ -1419,7 +1520,8 @@ function showHelp() {
   console.log(chalk.cyan('示例:'));
   console.log(`  ${CLI_COMMAND} init                        # 交互式初始化`);
   console.log(`  ${CLI_COMMAND} init my-project             # 在 my-project 目录初始化`);
-  console.log(`  ${CLI_COMMAND} init --tools claude,cursor  # 非交互式`);
+  console.log(`  ${CLI_COMMAND} init --tools claude,cursor  # 非交互式（默认项目级安装）`);
+  console.log(`  ${CLI_COMMAND} init --tools claude --scope global  # 非交互式（全局安装）`);
   console.log(`  ${CLI_COMMAND} update                      # 更新已配置的工具`);
   console.log(`  ${CLI_COMMAND} migrate --from openspec     # 从 OpenSpec 迁移`);
   console.log(`  ${CLI_COMMAND} migrate --from speckit      # 从 spec-kit 迁移`);
@@ -1449,6 +1551,8 @@ async function main() {
       process.exit(0);
     } else if (arg === '--tools') {
       options.tools = args[++i];
+    } else if (arg === '--scope') {
+      options.scope = args[++i];
     } else if (arg === '--from') {
       options.from = args[++i];
     } else if (arg === '--dry-run') {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dev-playbooks-cn",
-  "version": "1.4.0",
+  "version": "1.5.1",
   "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 个
+
+**下一步**：
+- 假完成 → 立即回退状态，重新验证
+- 存疑项 → 补充证据或重新运行测试
+- 可信项 → 继续当前流程

package/skills/devbooks-impact-analysis/SKILL.md

@@ -28,7 +28,42 @@ allowed-tools:
 
 ## 产物落点
 
-- 推荐写入：`<change-root>/<change-id>/proposal.md` 的 Impact 部分（或独立分析文档后再回填）
+- **必须**写入：`<change-root>/<change-id>/proposal.md` 的 Impact 部分
+- 备选：独立 `impact-analysis.md` 文件（后续回填到 proposal.md）
+
+## 输出行为（关键约束）
+
+> **黄金法则**：**直接写入文档，禁止输出到对话窗口**
+
+### 必须遵守
+
+1. **直接写入**：使用 `Edit` 或 `Write` 工具将分析结果直接写入目标文档
+2. **禁止回显**：不要在对话中显示完整的分析内容
+3. **简短通知**：完成后只需告知用户"影响分析已写入 `<文件路径>`"
+
+### 正确行为 vs 错误行为
+
+| 场景 | ❌ 错误行为 | ✅ 正确行为 |
+|------|------------|------------|
+| 分析完成 | 在对话中输出完整 Impact 表格 | 使用 Edit 工具写入 proposal.md |
+| 通知用户 | 复述分析内容 | "影响分析已写入 `changes/xxx/proposal.md`" |
+| 大量结果 | 分页输出到对话 | 全部写入文件，告知文件位置 |
+
+### 示例对话
+
+```
+用户：分析一下修改 UserService 的影响
+
+AI：[使用 Grep/CKB 分析引用]
+    [使用 Edit 工具写入 proposal.md]
+
+    影响分析已写入 `changes/refactor-user/proposal.md` 的 Impact 部分。
+    - 直接影响：8 个文件
+    - 间接影响：12 个文件
+    - 风险等级：中等
+
+    如需查看详情，请打开该文件。
+```
 
 ## 执行方式