dev-playbooks 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 Install Scope
+// ============================================================================
+
+const INSTALL_SCOPE = {
+  GLOBAL: 'global',   // Global installation (~/.claude/skills etc.)
+  PROJECT: 'project'  // Project-level installation (.claude/skills etc.)
+};
+
 // ============================================================================
 // AI 工具配置
 // ============================================================================
@@ -540,12 +549,68 @@ async function promptToolSelection(projectDir) {
   return selectedTools;
 }
 
+async function promptInstallScope(projectDir, selectedTools) {
+  // Check if any tools support full 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; // No full Skills support tools, default to project-level
+  }
+
+  // Load saved config
+  const config = loadConfig(projectDir);
+  const savedScope = config.installScope;
+
+  console.log();
+  console.log(chalk.bold('📦 Skills Installation Location'));
+  console.log(chalk.gray('─'.repeat(50)));
+  console.log();
+
+  const scope = await select({
+    message: 'Where should Skills be installed?',
+    choices: [
+      {
+        name: `Project-level ${chalk.gray('(.claude/skills etc., only for this project)')}`,
+        value: INSTALL_SCOPE.PROJECT,
+        description: 'Recommended: Skills stay with the project, no impact on other projects'
+      },
+      {
+        name: `Global ${chalk.gray('(~/.claude/skills etc., shared across all projects)')}`,
+        value: INSTALL_SCOPE.GLOBAL,
+        description: 'All projects share the same set of Skills'
+      }
+    ],
+    default: savedScope || INSTALL_SCOPE.PROJECT
+  });
+
+  return scope;
+}
+
 
 // ============================================================================
-// 安装 Skills（Claude Code, Codex CLI, Qoder）
+// Install Skills (Claude Code, Codex CLI, Qoder)
 // ============================================================================
 
-function installSkills(toolIds, update = false) {
+function getSkillsDestDir(tool, scope, projectDir) {
+  // Determine destination directory based on install scope
+  if (scope === INSTALL_SCOPE.PROJECT) {
+    // Project-level installation: use relative path within project directory
+    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');
+    }
+  }
+  // Global installation: use tool's defined global directory
+  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 (incl. oh-my-opencode) share the same Skills format
     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,13 +666,15 @@ function installSkills(toolIds, update = false) {
         type: 'skills',
         count: installedCount,
         total: skillDirs.length,
-        removed: removedCount
+        removed: removedCount,
+        scope: scope,
+        path: skillsDestDir
       });
     }
 
-    // Qoder: 创建 agents 目录结构（但不复制 Skills，因为格式不同）
+    // Qoder: Create agents directory structure (but don't copy Skills, different format)
     if (toolId === 'qoder') {
-      results.push({ tool: 'Qoder', type: 'agents', count: 0, total: 0, note: '需要手动创建 agents/' });
+      results.push({ tool: 'Qoder', type: 'agents', count: 0, total: 0, note: 'Manual agents/ creation required' });
     }
   }
 
@@ -1006,29 +1073,40 @@ function createProjectStructure(projectDir) {
 }
 
 // ============================================================================
-// 保存配置
+// Save Configuration
 // ============================================================================
 
-function saveConfig(toolIds, projectDir) {
+function saveConfig(toolIds, projectDir, installScope = INSTALL_SCOPE.PROJECT) {
   const configPath = path.join(projectDir, '.devbooks', 'config.yaml');
 
-  // 读取现有配置或创建新配置
+  // Read existing config or create new
   let configContent = '';
   if (fs.existsSync(configPath)) {
     configContent = fs.readFileSync(configPath, 'utf-8');
   }
 
-  // 更新 ai_tools 部分
+  // Update ai_tools section
   const toolsYaml = `ai_tools:\n${toolIds.map(id => `  - ${id}`).join('\n')}`;
 
   if (configContent.includes('ai_tools:')) {
-    // 替换现有的 ai_tools 部分
+    // Replace existing ai_tools section
     configContent = configContent.replace(/ai_tools:[\s\S]*?(?=\n\w|\n$|$)/, toolsYaml + '\n');
   } else {
-    // 追加 ai_tools 部分
+    // Append ai_tools section
     configContent = configContent.trimEnd() + '\n\n' + toolsYaml + '\n';
   }
 
+  // Update install_scope section
+  const scopeYaml = `install_scope: ${installScope}`;
+
+  if (configContent.includes('install_scope:')) {
+    // Replace existing install_scope section
+    configContent = configContent.replace(/install_scope:.*/, scopeYaml);
+  } else {
+    // Append install_scope section
+    configContent = configContent.trimEnd() + '\n\n' + scopeYaml + '\n';
+  }
+
   fs.writeFileSync(configPath, configContent);
 }
 
@@ -1036,38 +1114,42 @@ 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 };
+  // Parse 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())
+    : [];
+
+  // Parse install_scope
+  const scopeMatch = content.match(/install_scope:\s*(\w+)/);
+  const installScope = scopeMatch ? scopeMatch[1] : null;
+
+  return { aiTools: tools, installScope };
 }
 
 // ============================================================================
-// Init 命令
+// Init Command
 // ============================================================================
 
 async function initCommand(projectDir, options) {
   console.log();
   console.log(chalk.cyan('╔══════════════════════════════════════╗'));
-  console.log(chalk.cyan('║') + chalk.bold('         DevBooks 初始化向导         ') + chalk.cyan('║'));
+  console.log(chalk.cyan('║') + chalk.bold('       DevBooks Initialization        ') + chalk.cyan('║'));
   console.log(chalk.cyan('╚══════════════════════════════════════╝'));
   console.log();
 
-  // 确定选择的工具
+  // Determine selected tools
   let selectedTools;
+  let installScope = INSTALL_SCOPE.PROJECT; // Default to project-level installation
 
   if (options.tools) {
     if (options.tools === 'all') {
@@ -1079,27 +1161,35 @@ async function initCommand(projectDir, options) {
         AI_TOOLS.some(tool => tool.id === t)
       );
     }
-    console.log(chalk.blue('ℹ') + ` 非交互式模式：${selectedTools.length > 0 ? selectedTools.join(', ') : '无'}`);
+    console.log(chalk.blue('ℹ') + ` Non-interactive mode: ${selectedTools.length > 0 ? selectedTools.join(', ') : 'none'}`);
+
+    // In non-interactive mode, check --scope option
+    if (options.scope) {
+      installScope = options.scope === 'global' ? INSTALL_SCOPE.GLOBAL : INSTALL_SCOPE.PROJECT;
+    }
   } else {
     selectedTools = await promptToolSelection(projectDir);
+
+    // Interactive scope selection
+    installScope = await promptInstallScope(projectDir, selectedTools);
   }
 
-  // 创建项目结构
-  const spinner = ora('创建项目结构...').start();
+  // Create project structure
+  const spinner = ora('Creating project structure...').start();
   const templateCount = createProjectStructure(projectDir);
-  spinner.succeed(`创建了 ${templateCount} 个模板文件`);
+  spinner.succeed(`Created ${templateCount} template files`);
 
-  // 保存配置
-  saveConfig(selectedTools, projectDir);
+  // Save configuration (including install scope)
+  saveConfig(selectedTools, projectDir, installScope);
 
   if (selectedTools.length === 0) {
     console.log();
-    console.log(chalk.green('✓') + ' DevBooks 项目结构已创建！');
-    console.log(chalk.gray(`  运行 \`${CLI_COMMAND} init\` 并选择 AI 工具来配置集成。`));
+    console.log(chalk.green('✓') + ' DevBooks project structure created!');
+    console.log(chalk.gray(`  Run \`${CLI_COMMAND} init\` and select AI tools to configure integration.`));
     return;
   }
 
-  // 安装 Skills（仅完整支持的工具）
+  // Install Skills (only for full support tools)
   const fullSupportTools = selectedTools.filter(id => {
     const tool = AI_TOOLS.find(t => t.id === id);
     return tool && tool.skillsSupport === SKILLS_SUPPORT.FULL;
@@ -1107,12 +1197,16 @@ async function initCommand(projectDir, options) {
 
   if (fullSupportTools.length > 0) {
     const skillsSpinner = ora('Installing Skills...').start();
-    const skillsResults = installSkills(fullSupportTools);
+    const skillsResults = installSkills(fullSupportTools, projectDir, installScope);
     skillsSpinner.succeed('Skills installed');
 
     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 ? 'project-level' : 'global';
+        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}`));
       }
@@ -1127,14 +1221,14 @@ async function initCommand(projectDir, options) {
     }
   }
 
-  // 安装 Rules（Rules 类似系统的工具）
+  // Install Rules (for Rules-like system tools)
   const rulesTools = selectedTools.filter(id => {
     const tool = AI_TOOLS.find(t => t.id === id);
     return tool && tool.skillsSupport === SKILLS_SUPPORT.RULES;
   });
 
   if (rulesTools.length > 0) {
-    const rulesSpinner = ora('安装 Rules...').start();
+    const rulesSpinner = ora('Installing Rules...').start();
     const rulesResults = installRules(rulesTools, projectDir);
     rulesSpinner.succeed(`创建了 ${rulesResults.length} 个规则文件`);
 
@@ -1213,6 +1307,7 @@ async function updateCommand(projectDir) {
   // Load config
   const config = loadConfig(projectDir);
   const configuredTools = config.aiTools;
+  const installScope = config.installScope || INSTALL_SCOPE.PROJECT;
 
   if (configuredTools.length === 0) {
     console.log(chalk.yellow('⚠') + ` No AI tools configured. Run \`${CLI_COMMAND} init\` to configure.`);
@@ -1223,13 +1318,17 @@ async function updateCommand(projectDir) {
     const tool = AI_TOOLS.find(t => t.id === id);
     return tool ? tool.name : id;
   });
-  console.log(chalk.blue('ℹ') + ` Detected configured tools: ${toolNames.join(', ')}`);
+  const scopeLabel = installScope === INSTALL_SCOPE.PROJECT ? 'project-level' : 'global';
+  console.log(chalk.blue('ℹ') + ` Detected configured tools: ${toolNames.join(', ')} (${scopeLabel} installation)`);
 
-  // Update Skills (global directory)
-  const skillsResults = installSkills(configuredTools, true);
+  // Update Skills (using saved install scope from config)
+  const skillsResults = installSkills(configuredTools, projectDir, installScope, true);
   for (const result of skillsResults) {
     if (result.count > 0) {
       console.log(chalk.green('✓') + ` ${result.tool} ${result.type}: updated ${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}: removed ${result.removed} obsolete skills`);
@@ -1356,31 +1455,33 @@ async function migrateCommand(projectDir, options) {
 }
 
 // ============================================================================
-// 帮助信息
+// Help Information
 // ============================================================================
 
 function showHelp() {
   console.log();
   console.log(chalk.bold('DevBooks') + ' - AI-agnostic spec-driven development workflow');
   console.log();
-  console.log(chalk.cyan('用法:'));
-  console.log(`  ${CLI_COMMAND} init [path] [options]              初始化 DevBooks`);
-  console.log(`  ${CLI_COMMAND} update [path]                      更新已配置的工具`);
-  console.log(`  ${CLI_COMMAND} migrate --from <framework> [opts]  从其他框架迁移`);
+  console.log(chalk.cyan('Usage:'));
+  console.log(`  ${CLI_COMMAND} init [path] [options]              Initialize DevBooks`);
+  console.log(`  ${CLI_COMMAND} update [path]                      Update configured tools`);
+  console.log(`  ${CLI_COMMAND} migrate --from <framework> [opts]  Migrate from other frameworks`);
   console.log();
-  console.log(chalk.cyan('选项:'));
-  console.log('  --tools <tools>    非交互式指定 AI 工具');
-  console.log('                     可用值: all, none, 或逗号分隔的工具 ID');
-  console.log('  --from <framework> 迁移来源框架 (openspec, speckit)');
-  console.log('  --dry-run          模拟运行，不实际修改文件');
-  console.log('  --keep-old         迁移后保留原目录');
-  console.log('  --force            强制重新执行所有步骤');
-  console.log('  -h, --help         显示此帮助信息');
+  console.log(chalk.cyan('Options:'));
+  console.log('  --tools <tools>    Non-interactive AI tool selection');
+  console.log('                     Values: all, none, or comma-separated tool IDs');
+  console.log('  --scope <scope>    Skills installation location (non-interactive mode)');
+  console.log('                     Values: project (default), global');
+  console.log('  --from <framework> Migration source framework (openspec, speckit)');
+  console.log('  --dry-run          Dry run, no actual file modifications');
+  console.log('  --keep-old         Keep original directory after migration');
+  console.log('  --force            Force re-execute all steps');
+  console.log('  -h, --help         Show this help message');
   console.log('  -v, --version      Show version');
   console.log();
-  console.log(chalk.cyan('支持的 AI 工具:'));
+  console.log(chalk.cyan('Supported AI Tools:'));
 
-  // 按 Skills 支持级别分组显示
+  // Group tools by Skills support level
   const groupedTools = {
     [SKILLS_SUPPORT.FULL]: [],
     [SKILLS_SUPPORT.RULES]: [],
@@ -1393,43 +1494,44 @@ function showHelp() {
   }
 
   console.log();
-  console.log(chalk.green('  ★ 完整 Skills 支持:'));
+  console.log(chalk.green('  ★ Full Skills Support:'));
   for (const tool of groupedTools[SKILLS_SUPPORT.FULL]) {
     console.log(`    ${tool.id.padEnd(15)} ${tool.name}`);
   }
 
   console.log();
-  console.log(chalk.blue('  ◆ Rules 系统支持:'));
+  console.log(chalk.blue('  ◆ Rules System Support:'));
   for (const tool of groupedTools[SKILLS_SUPPORT.RULES]) {
     console.log(`    ${tool.id.padEnd(15)} ${tool.name}`);
   }
 
   console.log();
-  console.log(chalk.yellow('  ● 自定义指令支持:'));
+  console.log(chalk.yellow('  ● Custom Instructions Support:'));
   for (const tool of groupedTools[SKILLS_SUPPORT.AGENTS]) {
     console.log(`    ${tool.id.padEnd(15)} ${tool.name}`);
   }
 
   console.log();
   console.log();
-  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} update                      # 更新已配置的工具`);
-  console.log(`  ${CLI_COMMAND} migrate --from openspec     # 从 OpenSpec 迁移`);
-  console.log(`  ${CLI_COMMAND} migrate --from speckit      # 从 spec-kit 迁移`);
-  console.log(`  ${CLI_COMMAND} migrate --from openspec --dry-run  # 模拟迁移`);
+  console.log(chalk.cyan('Examples:'));
+  console.log(`  ${CLI_COMMAND} init                        # Interactive initialization`);
+  console.log(`  ${CLI_COMMAND} init my-project             # Initialize in my-project directory`);
+  console.log(`  ${CLI_COMMAND} init --tools claude,cursor  # Non-interactive (project-level by default)`);
+  console.log(`  ${CLI_COMMAND} init --tools claude --scope global  # Non-interactive (global installation)`);
+  console.log(`  ${CLI_COMMAND} update                      # Update configured tools`);
+  console.log(`  ${CLI_COMMAND} migrate --from openspec     # Migrate from OpenSpec`);
+  console.log(`  ${CLI_COMMAND} migrate --from speckit      # Migrate from spec-kit`);
+  console.log(`  ${CLI_COMMAND} migrate --from openspec --dry-run  # Dry run migration`);
 }
 
 // ============================================================================
-// 主入口
+// Main Entry
 // ============================================================================
 
 async function main() {
   const args = process.argv.slice(2);
 
-  // 解析参数
+  // Parse arguments
   let command = null;
   let projectPath = null;
   const options = {};
@@ -1445,6 +1547,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",
-  "version": "1.4.0",
+  "version": "1.5.1",
   "description": "AI-powered spec-driven development workflow",
   "keywords": [
     "devbooks",

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

@@ -0,0 +1,394 @@
+---
+name: devbooks-convergence-audit
+description: devbooks-convergence-audit: Evaluates DevBooks workflow convergence using "evidence first, distrust declarations" principle, detects "Sisyphus anti-patterns" and "fake completion". Actively verifies rather than trusting document claims. Use when user says "evaluate convergence/check upgrade health/Sisyphus detection/workflow audit" etc.
+allowed-tools:
+  - Glob
+  - Grep
+  - Read
+  - Bash
+---
+
+# DevBooks: Convergence Audit
+
+## Core Principle: Anti-Deception Design
+
+> **Golden Rule**: **Evidence > Declarations**. Never trust any assertions in documents; must confirm through verifiable evidence.
+
+### Scenarios Where AI Gets Deceived (Must Prevent)
+
+| Deception Scenario | AI Wrong Behavior | Correct Behavior |
+|--------------------|-------------------|------------------|
+| Document says `Status: Done` | Believes it's complete | Verify: Are tests actually all green? Does evidence exist? |
+| AC matrix all `[x]` | Believes full coverage | Verify: Does test file for each AC exist and pass? |
+| Document says "tests passed" | Believes passed | Verify: Actually run tests or check CI log timestamps |
+| `evidence/` directory exists | Believes evidence exists | Verify: Is directory non-empty? Is content valid test logs? |
+| tasks.md all `[x]` | Believes implemented | Verify: Do corresponding code files exist with substance? |
+| Commit message says "fixed" | Believes fixed | Verify: Did related tests change from red to green? |
+
+### Three Anti-Deception Principles
+
+```
+1. Distrust Declarations
+   - Any "complete/passed/covered" claims in documents are hypotheses to verify
+   - Default stance: Claims may be wrong, outdated, or optimistic
+
+2. Evidence First
+   - Code/test results are the only truth
+   - Log timestamps must be later than last code modification
+   - Empty directory/file = no evidence
+
+3. Cross Validation
+   - Declaration vs evidence: Check consistency
+   - Code vs tests: Check if they match
+   - Multiple documents: Check for contradictions
+```
+
+---
+
+## Verification Checklist (Execute Each)
+
+### Check 1: Status Field Truthfulness Verification
+
+**Document Claim**: `verification.md` contains `Status: Done` or `Status: Verified`
+
+**Verification Steps**:
+```bash
+# 1. Check if verification.md exists
+[[ -f "verification.md" ]] || echo "❌ verification.md does not exist"
+
+# 2. Check if evidence/green-final/ has content
+if [[ -z "$(ls -A evidence/green-final/ 2>/dev/null)" ]]; then
+  echo "❌ Status claims complete, but evidence/green-final/ is empty"
+fi
+
+# 3. Check if evidence timestamp is later than last code modification
+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 "❌ Evidence time is earlier than code modification, evidence may be stale"
+fi
+```
+
+**Deception Detection**:
+- ⚠️ Status=Done but evidence/ empty → **Fake Completion**
+- ⚠️ Status=Done but evidence timestamp too old → **Stale Evidence**
+- ⚠️ Status=Done but tests actually fail → **False Status**
+
+---
+
+### Check 2: AC Coverage Matrix Truthfulness Verification
+
+**Document Claim**: `[x]` in AC matrix means covered
+
+**Verification Steps**:
+```bash
+# 1. Extract all ACs claimed as covered
+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. Verify corresponding test exists
+  if ! grep -rq "$test_id\|$ac_id" tests/; then
+    echo "❌ $ac_id claims covered, but no corresponding test found"
+  fi
+done
+
+# 3. Actually run tests to verify (most reliable)
+npm test 2>&1 | tee /tmp/test-output.log
+if grep -q "FAIL\|Error\|failed" /tmp/test-output.log; then
+  echo "❌ ACs claim full coverage, but tests actually have failures"
+fi
+```
+
+**Deception Detection**:
+- ⚠️ AC checked but corresponding test file doesn't exist → **False Coverage**
+- ⚠️ AC checked but test actually fails → **Fake Green**
+- ⚠️ AC checked but test content is empty/placeholder → **Placeholder Test**
+
+---
+
+### Check 3: tasks.md Completion Truthfulness Verification
+
+**Document Claim**: `[x]` in tasks.md means completed
+
+**Verification Steps**:
+```bash
+# 1. Extract all tasks claimed as complete
+grep -E '^\- \[x\]' tasks.md | while read line; do
+  # 2. Extract keywords from task description (function name/file name/feature)
+  keywords=$(echo "$line" | grep -oE '[A-Za-z]+[A-Za-z0-9]*' | head -5)
+
+  # 3. Verify code has corresponding implementation
+  for kw in $keywords; do
+    if ! grep -rq "$kw" src/; then
+      echo "⚠️ Task claims complete, but keyword not found in code: $kw"
+    fi
+  done
+done
+
+# 4. Check for "skeleton code" (only function signatures without implementation)
+grep -rE 'throw new Error\(.*not implemented|TODO|FIXME|pass$|\.\.\.}' src/ && \
+  echo "⚠️ Found unimplemented placeholder code"
+```
+
+**Deception Detection**:
+- ⚠️ Task checked but code doesn't exist → **False Completion**
+- ⚠️ Task checked but code is placeholder → **Skeleton Code**
+- ⚠️ Task checked but feature not callable → **Dead Code**
+
+---
+
+### Check 4: Evidence Validity Verification
+
+**Document Claim**: `evidence/` directory contains test evidence
+
+**Verification Steps**:
+```bash
+# 1. Check if directory exists and is non-empty
+if [[ ! -d "evidence" ]] || [[ -z "$(ls -A evidence/)" ]]; then
+  echo "❌ evidence/ does not exist or is empty"
+  exit 1
+fi
+
+# 2. Check if evidence files have substantial content
+for f in evidence/**/*; do
+  if [[ -f "$f" ]]; then
+    lines=$(wc -l < "$f")
+    if [[ $lines -lt 5 ]]; then
+      echo "⚠️ Evidence file has too little content: $f ($lines lines)"
+    fi
+
+    # 3. Check if it's a valid test log (contains test framework output characteristics)
+    if ! grep -qE 'PASS|FAIL|✓|✗|passed|failed|test|spec' "$f"; then
+      echo "⚠️ Evidence file doesn't look like test log: $f"
+    fi
+  fi
+done
+
+# 4. Check if red-baseline evidence really is red (has failures)
+if [[ -d "evidence/red-baseline" ]]; then
+  if ! grep -rqE 'FAIL|Error|✗|failed' evidence/red-baseline/; then
+    echo "❌ red-baseline claims to be red, but no failure records"
+  fi
+fi
+
+# 5. Check if green-final evidence really is green (all pass)
+if [[ -d "evidence/green-final" ]]; then
+  if grep -rqE 'FAIL|Error|✗|failed' evidence/green-final/; then
+    echo "❌ green-final claims to be green, but contains failure records"
+  fi
+fi
+```
+
+**Deception Detection**:
+- ⚠️ evidence/ exists but content is empty → **Empty Evidence**
+- ⚠️ Evidence file too small (< 5 lines) → **Placeholder Evidence**
+- ⚠️ red-baseline has no failure records → **Fake Red**
+- ⚠️ green-final contains failure records → **Fake Green**
+
+---
+
+### Check 5: Git History Cross Validation
+
+**Principle**: Git history doesn't lie; use it to verify document claims
+
+**Verification Steps**:
+```bash
+# 1. Check if claimed-complete change has corresponding code commits
+change_id="xxx"
+commits=$(git log --oneline --all --grep="$change_id" | wc -l)
+if [[ $commits -eq 0 ]]; then
+  echo "❌ Change $change_id claims complete, but no related commits in git history"
+fi
+
+# 2. Check if test files were added after code (TDD violation detection)
+for test_file in tests/**/*.test.*; do
+  test_added=$(git log --format=%at --follow -- "$test_file" | tail -1)
+  # Find corresponding source file
+  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 "⚠️ Test added after code (non-TDD): $test_file"
+    fi
+  fi
+done
+
+# 3. Check for "one-time big commits" (may be bypassing process)
+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 "⚠️ Big commit detected: $commit modified $files_changed files, may bypass incremental verification"
+  fi
+done
+```
+
+**Deception Detection**:
+- ⚠️ Claims complete but no git commits → **Fake Change**
+- ⚠️ Tests added after code → **Retroactive Testing**
+- ⚠️ Many files in one commit → **Bypassing Incremental Verification**
+
+---
+
+### Check 6: Live Test Run Verification (Most Reliable)
+
+**Principle**: Don't trust any logs; actually run tests
+
+**Verification Steps**:
+```bash
+# 1. Run full tests
+echo "=== Live Test Verification ==="
+npm test 2>&1 | tee /tmp/live-test.log
+
+# 2. Check results
+if grep -qE 'FAIL|Error|failed' /tmp/live-test.log; then
+  echo "❌ Live tests failed, document claims not trustworthy"
+  grep -E 'FAIL|Error|failed' /tmp/live-test.log
+else
+  echo "✅ Live tests passed"
+fi
+
+# 3. Compare live results with evidence files
+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 count ($live_pass) ≠ evidence pass count ($evidence_pass)"
+  fi
+fi
+```
+
+**Deception Detection**:
+- ⚠️ Evidence says green but live run fails → **Stale Evidence/Fake Green**
+- ⚠️ Live pass count differs from evidence → **Evidence Fabrication/Environment Difference**
+
+---
+
+## Composite Scoring Algorithm
+
+### Trustworthiness Score (0-100)
+
+```python
+def calculate_trustworthiness(checks):
+    score = 100
+
+    # Critical issues (each -20 points)
+    critical = [
+        "Evidence empty",
+        "Live tests failed",
+        "Status claims complete but tests fail",
+        "green-final contains failure records"
+    ]
+
+    # Warning issues (each -10 points)
+    warnings = [
+        "Evidence timestamp too old",
+        "AC corresponding test doesn't exist",
+        "Placeholder code",
+        "Big commit detected"
+    ]
+
+    # Minor issues (each -5 points)
+    minor = [
+        "Tests added after code",
+        "Evidence file too small"
+    ]
+
+    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)
+```
+
+### Convergence Determination
+
+| Trustworthiness | Determination | Recommendation |
+|-----------------|---------------|----------------|
+| 90-100 | ✅ Trustworthy Convergence | Continue current process |
+| 70-89 | ⚠️ Partially Trustworthy | Need supplementary verification |
+| 50-69 | 🟠 Questionable | Need to rework some steps |
+| < 50 | 🔴 Untrustworthy | Sisyphus trap, need comprehensive review |
+
+---
+
+## Output Format
+
+```markdown
+# DevBooks Convergence Audit Report (Anti-Deception Edition)
+
+## Audit Principle
+This report uses "evidence first, distrust declarations" principle. All conclusions are based on verifiable evidence, not document claims.
+
+## Declaration vs Evidence Comparison
+
+| Check Item | Document Claim | Actual Verification | Conclusion |
+|------------|----------------|---------------------|------------|
+| Status | Done | Tests actually fail | ❌ Fake Completion |
+| AC Coverage | 5/5 checked | 2 ACs have no corresponding tests | ❌ False Coverage |
+| Test Status | All green | Live run 3 failures | ❌ Stale Evidence |
+| tasks.md | 10/10 complete | 3 tasks have no code | ❌ False Completion |
+| evidence/ | Exists | Non-empty, content valid | ✅ Valid |
+
+## Trustworthiness Score
+
+**Total Score**: 45/100 🔴 Untrustworthy
+
+**Deduction Details**:
+- -20: Status=Done but live tests fail
+- -20: ACs claim full coverage but 2 have no tests
+- -10: tasks.md 3 tasks have no code
+- -5: Evidence timestamp earlier than code modification
+
+## Deception Detection Results
+
+### 🔴 Detected Fake Completions
+1. `change-auth`: Status=Done, but `npm test` fails 3
+2. `fix-cache`: AC-003 checked, but `tests/cache.test.ts` doesn't exist
+
+### 🟡 Suspicious Items
+1. `refactor-api`: evidence/green-final/ timestamp 2 days earlier than last code commit
+2. `feature-login`: tasks.md all checked, but `src/login.ts` contains TODO
+
+## True Status Determination
+
+| Change Package | Claimed Status | True Status | Gap |
+|----------------|----------------|-------------|-----|
+| change-auth | Done | Tests failing | 🔴 Severe |
+| fix-cache | Verified | Coverage incomplete | 🟠 Medium |
+| refactor-api | Ready | Evidence stale | 🟡 Minor |
+
+## Recommended Actions
+
+### Immediate Action
+1. Revert `change-auth` status to `In Progress`
+2. Add tests for `fix-cache` AC-003
+
+### Short-term Improvement
+1. Establish evidence timeliness check (evidence must be later than code)
+2. Force run corresponding tests before AC check-off
+
+### Process Improvement
+1. Prohibit manual Status modification; only allow auto-update after script verification
+2. Integrate convergence check in CI, block fake completion from merging
+```
+
+---
+
+## Completion Status
+
+**Status**: ✅ AUDIT_COMPLETED
+
+**Core Findings**:
+- Document claim trustworthiness: X%
+- Detected fake completions: N
+- Changes needing rework: M
+
+**Next Step**:
+- Fake completion → Immediately revert status, re-verify
+- Suspicious items → Supplement evidence or re-run tests
+- Trustworthy items → Continue current process

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

@@ -28,7 +28,42 @@ Before execution, **must** search for configuration in the following order (stop
 
 ## Output Location
 
-- Recommended: Write to the Impact section of `<change-root>/<change-id>/proposal.md` (or create a separate analysis document and backfill later)
+- **Must** write to: The Impact section of `<change-root>/<change-id>/proposal.md`
+- Alternative: Separate `impact-analysis.md` file (to be backfilled to proposal.md later)
+
+## Output Behavior (Critical Constraint)
+
+> **Golden Rule**: **Write directly to document, do NOT output to conversation window**
+
+### Must Follow
+
+1. **Direct Write**: Use `Edit` or `Write` tool to write analysis results directly to target document
+2. **No Echo**: Do NOT display the complete analysis content in the conversation
+3. **Brief Notification**: After completion, only inform the user "Impact analysis written to `<file-path>`"
+
+### Correct vs Incorrect Behavior
+
+| Scenario | ❌ Incorrect Behavior | ✅ Correct Behavior |
+|----------|----------------------|---------------------|
+| Analysis complete | Output full Impact table in conversation | Use Edit tool to write to proposal.md |
+| Notify user | Repeat analysis content | "Impact analysis written to `changes/xxx/proposal.md`" |
+| Large results | Paginate output to conversation | Write all to file, inform file location |
+
+### Example Conversation
+
+```
+User: Analyze the impact of modifying UserService
+
+AI: [Uses Grep/CKB to analyze references]
+    [Uses Edit tool to write to proposal.md]
+
+    Impact analysis written to the Impact section of `changes/refactor-user/proposal.md`.
+    - Direct impact: 8 files
+    - Indirect impact: 12 files
+    - Risk level: Medium
+
+    Open the file to view details.
+```
 
 ## Execution Method