kld-sdd 2.4.9 → 2.4.11

package/README.md

@@ -136,9 +136,9 @@ propose → spec → design → task → check
 
 ---
 
-## 预置技能：`opsx-sdd`
+## 预置技能：`kld-sdd`
 
-初始化后，`opsx-sdd` 技能会自动部署到你的编辑器技能目录（`.*/skills/opsx-sdd/`）。
+初始化后，SDD 全套技能会统一打包部署到 `.*/skills/kld-sdd/`（与 `gitnexus/` 目录模式一致），包含 `opsx-propose`、`opsx-spec`、`opsx-design`、`opsx-task`、`opsx-check`、`opsx-apply`、`opsx-test`、`opsx-archive`、`opsx-explore`、`opsx-knowledge` 等子技能。
 
 激活后，AI 会化身 **SDD 工作流专家**，检测当前项目的文档状态，引导你从当前进度继续：
 
@@ -190,16 +190,19 @@ your-project/
 │   └── task.md
 ├── .cursor/
 │   ├── commands/opsx/               # opsx 命令（9个）
-│   └── skills/opsx-*/               # 预置 SDD 技能
+│   └── skills/kld-sdd/              # SDD 技能统一目录
+│       ├── opsx-propose/
+│       ├── opsx-spec/
+│       └── ...                      # 其他 opsx-* 子技能
 ├── .claude/
 │   ├── commands/opsx/               # opsx 命令（9个）
-│   └── skills/opsx-*/               # 预置 SDD 技能
+│   └── skills/kld-sdd/              # SDD 技能统一目录
 ├── .codebuddy/
 │   ├── commands/opsx/               # opsx 命令（9个）
-│   └── skills/opsx-*/               # 预置 SDD 技能
+│   └── skills/kld-sdd/              # SDD 技能统一目录
 └── .agents/
     ├── commands/opsx/               # Codex opsx 命令（9个）
-    └── skills/opsx-*/               # Codex 项目级技能
+    └── skills/kld-sdd/              # Codex 项目级技能
 ```
 
 ---

package/lib/init.js

@@ -327,9 +327,7 @@ function copyDir(source, target) {
 }
 
 function renderTemplate(content, config, toolKey) {
-  return content
-    .replace(/^\uFEFF/, '')
-    .replace(/<Agent(?:\u7c7b\u578b|\u7eeb\u8bf2\u7037)>/g, config.agentType || toolKey);
+  return require('./skills-bundle').renderTemplate(content, config, toolKey);
 }
 
 function copyDirRendered(source, target, config, toolKey) {
@@ -504,9 +502,50 @@ function overrideOpsxCommands(selectedTools = Object.keys(TOOL_CONFIGS)) {
   return true;
 }
 
+const {
+  SKILLS_BUNDLE_NAME,
+  OPSX_SKILL_DIRS,
+  renderTemplate
+} = require('./skills-bundle');
+
+/**
+ * 清理旧版扁平 opsx-* skills（迁移到 skills/kld-sdd/ 统一目录）
+ * @param {string[]} selectedTools - 用户选择的编辑器列表
+ */
+function cleanupLegacyFlatOpsxSkills(selectedTools = Object.keys(TOOL_CONFIGS)) {
+  console.log('🧹 正在清理旧版扁平 opsx-* skills...');
+
+  const cwd = process.cwd();
+  const legacySkillDirs = [...OPSX_SKILL_DIRS, 'opsx-sdd'];
+
+  for (const toolKey of selectedTools) {
+    const config = TOOL_CONFIGS[toolKey];
+    if (!config || !config.skillsDir) continue;
+
+    const skillsDir = path.join(cwd, config.skillsDir);
+    if (!fs.existsSync(skillsDir)) continue;
+
+    let removed = 0;
+    for (const legacySkill of legacySkillDirs) {
+      const legacySkillDir = path.join(skillsDir, legacySkill);
+      if (fs.existsSync(legacySkillDir)) {
+        fs.rmSync(legacySkillDir, { recursive: true, force: true });
+        removed++;
+      }
+    }
+
+    if (removed > 0) {
+      console.log(`   🗑  ${config.name}: 删除 ${removed} 个旧版扁平 opsx skills`);
+    }
+  }
+
+  console.log('✅ 旧版扁平 opsx skills 清理完成');
+  return true;
+}
+
 /**
- * 部署 SDD opsx skills（9 个技能文件）
- * 从 templates/skills/ 目录复制到各编辑器的 skills 目录
+ * 部署 SDD opsx skills
+ * 从 templates/skills/kld-sdd/ 复制到各编辑器的 skills/kld-sdd/ 目录
  * @param {string[]} selectedTools - 用户选择的编辑器列表
  */
 function deployOpsxSkills(selectedTools = Object.keys(TOOL_CONFIGS)) {
@@ -515,14 +554,14 @@ function deployOpsxSkills(selectedTools = Object.keys(TOOL_CONFIGS)) {
   const pkgPath = getPackagePath();
   const cwd = process.cwd();
   
-  const skillsTemplatePath = path.join(pkgPath, 'templates', 'skills');
+  const skillsTemplatePath = path.join(pkgPath, 'templates', 'skills', SKILLS_BUNDLE_NAME);
   
   if (!fs.existsSync(skillsTemplatePath)) {
     console.log(`⚠️  SDD skills 模板目录不存在: ${skillsTemplatePath}`);
     return false;
   }
   
-  // 获取所有 skill 目录
+  // 获取 bundle 内所有 skill 目录
   const skillDirs = fs.readdirSync(skillsTemplatePath).filter(d => {
     return fs.statSync(path.join(skillsTemplatePath, d)).isDirectory();
   });
@@ -537,17 +576,21 @@ function deployOpsxSkills(selectedTools = Object.keys(TOOL_CONFIGS)) {
     if (!config || !config.skillsDir) continue;
     
     const targetSkillsDir = path.join(cwd, config.skillsDir);
+    const targetBundleDir = path.join(targetSkillsDir, SKILLS_BUNDLE_NAME);
     
     // 确保 skills 目录存在
     if (!fs.existsSync(targetSkillsDir)) {
       fs.mkdirSync(targetSkillsDir, { recursive: true });
     }
+    if (!fs.existsSync(targetBundleDir)) {
+      fs.mkdirSync(targetBundleDir, { recursive: true });
+    }
     
-    console.log(`   部署 ${config.name} 的 opsx skills（${skillDirs.length} 个）...`);
+    console.log(`   部署 ${config.name} 的 ${SKILLS_BUNDLE_NAME} skills（${skillDirs.length} 个）...`);
     
     for (const skillDir of skillDirs) {
       const sourceDir = path.join(skillsTemplatePath, skillDir);
-      const targetDir = path.join(targetSkillsDir, skillDir);
+      const targetDir = path.join(targetBundleDir, skillDir);
       
       if (!fs.existsSync(targetDir)) {
         fs.mkdirSync(targetDir, { recursive: true });
@@ -555,9 +598,18 @@ function deployOpsxSkills(selectedTools = Object.keys(TOOL_CONFIGS)) {
       
       if (fs.existsSync(sourceDir)) {
         copyDirRendered(sourceDir, targetDir, config, toolKey);
-        console.log(`     ✓ ${skillDir}`);
+        console.log(`     ✓ ${SKILLS_BUNDLE_NAME}/${skillDir}`);
       }
     }
+
+    // 复制 bundle 根目录说明文件（如 SKILLS.md）
+    for (const file of fs.readdirSync(skillsTemplatePath)) {
+      const sourceFile = path.join(skillsTemplatePath, file);
+      if (!fs.statSync(sourceFile).isFile()) continue;
+      const rendered = renderTemplate(fs.readFileSync(sourceFile, 'utf8'), config, toolKey);
+      fs.writeFileSync(path.join(targetBundleDir, file), rendered, 'utf8');
+      console.log(`     ✓ ${SKILLS_BUNDLE_NAME}/${file}`);
+    }
   }
   
   console.log('✅ opsx skills 部署完成');
@@ -566,7 +618,7 @@ function deployOpsxSkills(selectedTools = Object.keys(TOOL_CONFIGS)) {
 
 /**
  * 部署 Claude Code Hook Pack（可选增强）
- * Hook 只调用 skywalk-sdd/log.js，不写私有日志，不替代 OPSX 模板采集。
+ * Hook 只调用 skywalk-sdd/log.cjs，不写私有日志，不替代 OPSX 模板采集。
  */
 function deployClaudeHookPack(selectedTools = Object.keys(TOOL_CONFIGS)) {
   if (!selectedTools.includes('claude')) {
@@ -593,7 +645,7 @@ function deployClaudeHookPack(selectedTools = Object.keys(TOOL_CONFIGS)) {
   }
 
   copyDir(hookSourceDir, targetHookDir);
-  console.log('   ✓ 部署 .claude/hooks/sdd-*.js');
+  console.log('   ✓ 部署 .claude/hooks/sdd-*.cjs');
 
   const targetSettingsPath = path.join(claudeDir, 'settings.json');
   const templateSettings = JSON.parse(fs.readFileSync(settingsTemplatePath, 'utf8'));
@@ -790,16 +842,16 @@ function deployTelemetryDataDir() {
   }
 
   // 部署项目内 Telemetry CLI（不依赖 npm 发布）
-  const telemetrySrc = path.join(pkgPath, 'skywalk-sdd', 'index.js');
-  const telemetryDst = path.join(dataDir, 'log.js');
+  const telemetrySrc = path.join(pkgPath, 'skywalk-sdd', 'index.cjs');
+  const telemetryDst = path.join(dataDir, 'log.cjs');
   if (fs.existsSync(telemetrySrc)) {
     fs.copyFileSync(telemetrySrc, telemetryDst);
-    console.log('   ✓ 部署 skywalk-sdd/log.js（本地 Telemetry CLI）');
+    console.log('   ✓ 部署 skywalk-sdd/log.cjs（本地 Telemetry CLI）');
   } else {
     console.log(`   ⚠️  Telemetry CLI 源文件缺失: ${telemetrySrc}`);
   }
 
-  console.log('   ✓ 调用方式: node skywalk-sdd/log.js start|end|metrics');
+  console.log('   ✓ 调用方式: node skywalk-sdd/log.cjs start|end|metrics');
   console.log('✅ Telemetry 已就绪（数据存储在 skywalk-sdd/，无需配置 MCP）');
   return true;
 }
@@ -869,8 +921,8 @@ function deployQualityGateTemplates() {
     console.log(`   ⚠️  CI 模板缺失: ${ciTemplateDir}`);
   }
 
-  installGitHookShim(cwd, 'pre-commit', 'skywalk-sdd/git-hooks/pre-commit-sdd-check.js');
-  installGitHookShim(cwd, 'pre-push', 'skywalk-sdd/git-hooks/pre-push-sdd-check.js');
+  installGitHookShim(cwd, 'pre-commit', 'skywalk-sdd/git-hooks/pre-commit-sdd-check.cjs');
+  installGitHookShim(cwd, 'pre-push', 'skywalk-sdd/git-hooks/pre-push-sdd-check.cjs');
 
   console.log('✅ Git hooks / CI 兜底模板已就绪');
   return true;
@@ -1019,10 +1071,13 @@ async function main() {
     // 3. 部署 SDD opsx 命令（根据编辑器类型使用不同模板）
     overrideOpsxCommands(selectedTools);
 
-    // 4. 部署 SDD opsx skills
+    // 4. 清理旧版扁平 opsx-* skills（迁移到 skills/kld-sdd/）
+    cleanupLegacyFlatOpsxSkills(selectedTools);
+
+    // 4.1 部署 SDD opsx skills（统一打包到 skills/kld-sdd/）
     deployOpsxSkills(selectedTools);
     
-    // 4.1 清理原生 openspec-* skills（防止残留）
+    // 4.2 清理原生 openspec-* skills（防止残留）
     cleanupNativeOpenspecSkills(selectedTools);
 
     // 4.2 部署 Claude Code Hook Pack（可选增强）
@@ -1086,7 +1141,7 @@ async function main() {
   console.log();
   console.log('📊 SDD Telemetry（嵌入在命令流程中，自动执行，无需配置）：');
   console.log('  - 度量数据自动采集到 skywalk-sdd/events/');
-  console.log('  - 运行 node skywalk-sdd/log.js metrics --project=. 查看四维度指标');
+  console.log('  - 运行 node skywalk-sdd/log.cjs metrics --project=. 查看四维度指标');
   console.log();
 
   rl.close();

package/lib/skills-bundle.js

@@ -0,0 +1,32 @@
+/**
+ * SDD skills bundle 共享配置与模板渲染
+ */
+
+const SKILLS_BUNDLE_NAME = 'kld-sdd';
+
+const OPSX_SKILL_DIRS = [
+  'opsx-propose',
+  'opsx-spec',
+  'opsx-design',
+  'opsx-task',
+  'opsx-check',
+  'opsx-apply',
+  'opsx-test',
+  'opsx-archive',
+  'opsx-explore',
+  'opsx-knowledge'
+];
+
+function renderTemplate(content, config, toolKey) {
+  const skillsBundlePath = `${config.skillsDir}/${SKILLS_BUNDLE_NAME}`;
+  return content
+    .replace(/^\uFEFF/, '')
+    .replace(/<Agent(?:\u7c7b\u578b|\u7eeb\u8bf2\u7037)>/g, config.agentType || toolKey)
+    .replace(/<SkillsBundlePath>/g, skillsBundlePath);
+}
+
+module.exports = {
+  SKILLS_BUNDLE_NAME,
+  OPSX_SKILL_DIRS,
+  renderTemplate
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kld-sdd",
-  "version": "2.4.9",
+  "version": "2.4.11",
   "description": "KLD SDD OpenSpec 项目初始化工具 - 内置模版一键初始化",
   "main": "index.js",
   "bin": {
@@ -8,7 +8,7 @@
     "kld-sdd-init": "bin/kld-sdd-init.js"
   },
   "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "test": "node test/validate-skills-bundle.cjs"
   },
   "keywords": [
     "kld",
@@ -30,7 +30,7 @@
     "bin/",
     "lib/",
     "templates/",
-    "skywalk-sdd/index.js",
+    "skywalk-sdd/index.cjs",
     "README.md"
   ]
 }

package/skywalk-sdd/{index.js → index.cjs}

@@ -6,9 +6,9 @@
  * AI Agent 通过终端命令调用，将事件写入项目本地 skywalk-sdd/ 目录。
  * 
  * 用法:
- *   node skywalk-sdd/log.js start  --command=propose --project=/path --change=xxx [--agent=cursor]
- *   node skywalk-sdd/log.js end    --event-id=evt_xxx --result=success --summary="..."
- *   node skywalk-sdd/log.js metrics --project=/path [--change=xxx]
+ *   node skywalk-sdd/log.cjs start  --command=propose --project=/path --change=xxx [--agent=cursor]
+ *   node skywalk-sdd/log.cjs end    --event-id=evt_xxx --result=success --summary="..."
+ *   node skywalk-sdd/log.cjs metrics --project=/path [--change=xxx]
  */
 
 const fs = require('fs');
@@ -1395,7 +1395,9 @@ function computeAiAdoptionMetrics(events) {
     const review = getAiAdoptionReview(e);
     return review?.review_status === 'final' || e.status === 'final';
   });
-  const latestEvent = latestByTimestamp(finalEvents.length > 0 ? finalEvents : adoptionEvents);
+  // 优先使用 final 事件，无 final 时 fallback 到 snapshot（AI 产出快照）
+  const candidates = finalEvents.length > 0 ? finalEvents : adoptionEvents;
+  const latestEvent = latestByTimestamp(candidates);
   const latestReview = getAiAdoptionReview(latestEvent);
   if (!latestReview) {
     return {
@@ -1665,7 +1667,7 @@ function computeSinglePdfMvpMetrics(events, options = {}) {
   const gitDocumentMetrics = options.projectRoot && options.change
     ? computeGitDocumentMetrics(options.projectRoot, options.change)
     : null;
-  const specIterationCount = gitDocumentMetrics
+  const specIterationCount = gitDocumentMetrics?.spec_iteration_count != null
     ? gitDocumentMetrics.spec_iteration_count
     : stageSpecIterationCount;
 
@@ -1902,6 +1904,10 @@ function renderExecutiveReportMarkdown(report) {
     '',
     '## 说明',
     '- `null` 表示当前还没有采集到对应事件或该指标暂不适用。',
+    '- E4 AI 一次成码率：依赖 `task_update` 事件中的 `task_id` 和首次执行结果，若 apply 阶段未正确记录则显示 null。',
+    '- P1 文档迭代次数：优先使用 Git 提交历史统计，无 Git 仓库或无提交历史时使用阶段 start 事件数。',
+    '- P2 AI 代码保留率：优先使用 `ai_adoption_review` 的 final 状态，无 final 时 fallback 到 AI 产出快照（ai_snapshot）。',
+    '- Q4 规约驱动测试覆盖率：依赖 check/test 阶段记录 spec 断言到测试用例的映射数据（spec_test_coverage 字段），属高级功能。',
     '- Q1 规约符合度与人工反馈类指标属于评审信号，默认不作为强阻断门禁。',
   ].join('\n');
 }
@@ -2064,7 +2070,7 @@ function cmdStart(args) {
 
   if (!command) {
     console.error('错误: 缺少 --command 参数');
-    console.error('用法: node skywalk-sdd/log.js start --command=propose --project=/path');
+    console.error('用法: node skywalk-sdd/log.cjs start --command=propose --project=/path');
     process.exit(1);
   }
 
@@ -2556,7 +2562,7 @@ function cmdArchiveDocs(args) {
 function main() {
   // 支持两种调用方式:
   // 1) npx kld-sdd log start ...     → argv 含 'log'
-  // 2) node skywalk-sdd/log.js start ... → argv 直接以子命令开头
+  // 2) node skywalk-sdd/log.cjs start ... → argv 直接以子命令开头
   const argv = process.argv.slice(2);
   const logIdx = argv.indexOf('log');
   const subArgs = logIdx === -1 ? argv : argv.slice(logIdx + 1);
@@ -2604,12 +2610,12 @@ function showHelp() {
 SDD Telemetry CLI - 流程度量采集工具
 
 用法:
-  node skywalk-sdd/log.js start   --command=<cmd> --project=<path> [--change=<name>] [--agent=<type>]
-  node skywalk-sdd/log.js end     --event-id=<id> --result=<success|failure|partial> --summary="..."
-  node skywalk-sdd/log.js metrics --project=<path> [--change=<name>] [--pdf-mvp] [--format=json|markdown]
-  node skywalk-sdd/log.js report  --project=<path> [--change=<name>] [--format=json|markdown] [--output=<file>]
-  node skywalk-sdd/log.js tasks-status --project=<path> --change=<name> [--require-complete]
-  node skywalk-sdd/log.js archive-docs --project=<path> --change=<name> [--reason=<text>] [--event-id=<id>] [--report-output=<file>]
+  node skywalk-sdd/log.cjs start   --command=<cmd> --project=<path> [--change=<name>] [--agent=<type>]
+  node skywalk-sdd/log.cjs end     --event-id=<id> --result=<success|failure|partial> --summary="..."
+  node skywalk-sdd/log.cjs metrics --project=<path> [--change=<name>] [--pdf-mvp] [--format=json|markdown]
+  node skywalk-sdd/log.cjs report  --project=<path> [--change=<name>] [--format=json|markdown] [--output=<file>]
+  node skywalk-sdd/log.cjs tasks-status --project=<path> --change=<name> [--require-complete]
+  node skywalk-sdd/log.cjs archive-docs --project=<path> --change=<name> [--reason=<text>] [--event-id=<id>] [--report-output=<file>]
 
 子命令:
   start    记录 SDD 阶段开始，返回 event_id
@@ -2622,18 +2628,18 @@ SDD Telemetry CLI - 流程度量采集工具
   archive-docs 将 Simple/Full spec 变更真实移动到 openspec/changes/archive/，并可结束 archive 阶段生成报告
 
 示例:
-  node skywalk-sdd/log.js start --command=propose --project=/my/project --change=user-auth --agent=cursor
-  node skywalk-sdd/log.js end --event-id=evt_abc123 --result=success --summary="创建 proposal.md"
-  node skywalk-sdd/log.js record --type=task_update --command=apply --project=/my/project --change=user-auth --task-id=TASK-01 --status=completed
-  node skywalk-sdd/log.js record --type=conformance_review --command=check --project=/my/project --change=user-auth --source=manual --details-file=conformance-review.json
-  node skywalk-sdd/log.js record --type=ai_adoption_review --command=apply --project=/my/project --change=user-auth --status=final --details-file=ai-adoption.json
-  node skywalk-sdd/log.js record --type=survey_result --project=/my/project --change=user-auth --source=manual --details-file=survey.json
-  node skywalk-sdd/log.js metrics --project=/my/project --change=user-auth
-  node skywalk-sdd/log.js metrics --project=/my/project --change=user-auth --pdf-mvp --format=markdown
-  node skywalk-sdd/log.js report --project=/my/project --change=user-auth --format=markdown
-  node skywalk-sdd/log.js doctor --project=/my/project --change=user-auth
-  node skywalk-sdd/log.js tasks-status --project=/my/project --change=user-auth --require-complete
-  node skywalk-sdd/log.js archive-docs --project=/my/project --change=user-auth --reason="变更已完成实施" --event-id=evt_archive --report-output=skywalk-sdd/reports/user-auth-report.md
+  node skywalk-sdd/log.cjs start --command=propose --project=/my/project --change=user-auth --agent=cursor
+  node skywalk-sdd/log.cjs end --event-id=evt_abc123 --result=success --summary="创建 proposal.md"
+  node skywalk-sdd/log.cjs record --type=task_update --command=apply --project=/my/project --change=user-auth --task-id=TASK-01 --status=completed
+  node skywalk-sdd/log.cjs record --type=conformance_review --command=check --project=/my/project --change=user-auth --source=manual --details-file=conformance-review.json
+  node skywalk-sdd/log.cjs record --type=ai_adoption_review --command=apply --project=/my/project --change=user-auth --status=final --details-file=ai-adoption.json
+  node skywalk-sdd/log.cjs record --type=survey_result --project=/my/project --change=user-auth --source=manual --details-file=survey.json
+  node skywalk-sdd/log.cjs metrics --project=/my/project --change=user-auth
+  node skywalk-sdd/log.cjs metrics --project=/my/project --change=user-auth --pdf-mvp --format=markdown
+  node skywalk-sdd/log.cjs report --project=/my/project --change=user-auth --format=markdown
+  node skywalk-sdd/log.cjs doctor --project=/my/project --change=user-auth
+  node skywalk-sdd/log.cjs tasks-status --project=/my/project --change=user-auth --require-complete
+  node skywalk-sdd/log.cjs archive-docs --project=/my/project --change=user-auth --reason="变更已完成实施" --event-id=evt_archive --report-output=skywalk-sdd/reports/user-auth-report.md
 `);
 }
 

package/templates/ci/github-actions-sdd.yml

@@ -28,7 +28,7 @@ jobs:
         run: npm install
 
       - name: SDD doctor
-        run: node skywalk-sdd/log.js doctor --project="$SDD_PROJECT" --change="$SDD_CHANGE"
+        run: node skywalk-sdd/log.cjs doctor --project="$SDD_PROJECT" --change="$SDD_CHANGE"
 
       - name: Build and record SDD result
         shell: bash
@@ -45,7 +45,7 @@ jobs:
             result="failure"
             success="false"
           fi
-          node skywalk-sdd/log.js record --type=build_result --command=ci --project="$SDD_PROJECT" --change="$SDD_CHANGE" --agent="$SDD_AGENT" --source=ci --session-id="$SDD_SESSION" --result="$result" --summary="CI build $result" --details-json="{\"build_results\":{\"command\":\"$SDD_BUILD_COMMAND\",\"success\":$success,\"duration_ms\":$duration,\"error_count\":0}}"
+          node skywalk-sdd/log.cjs record --type=build_result --command=ci --project="$SDD_PROJECT" --change="$SDD_CHANGE" --agent="$SDD_AGENT" --source=ci --session-id="$SDD_SESSION" --result="$result" --summary="CI build $result" --details-json="{\"build_results\":{\"command\":\"$SDD_BUILD_COMMAND\",\"success\":$success,\"duration_ms\":$duration,\"error_count\":0}}"
           exit "$status"
 
       - name: Test and record SDD result
@@ -63,5 +63,5 @@ jobs:
             result="failure"
             failed=1
           fi
-          node skywalk-sdd/log.js record --type=test_result --command=ci --project="$SDD_PROJECT" --change="$SDD_CHANGE" --agent="$SDD_AGENT" --source=ci --session-id="$SDD_SESSION" --result="$result" --summary="CI test $result" --details-json="{\"test_results\":{\"command\":\"$SDD_TEST_COMMAND\",\"passed\":0,\"failed\":$failed,\"skipped\":0,\"coverage\":null,\"duration_ms\":$duration}}"
+          node skywalk-sdd/log.cjs record --type=test_result --command=ci --project="$SDD_PROJECT" --change="$SDD_CHANGE" --agent="$SDD_AGENT" --source=ci --session-id="$SDD_SESSION" --result="$result" --summary="CI test $result" --details-json="{\"test_results\":{\"command\":\"$SDD_TEST_COMMAND\",\"passed\":0,\"failed\":$failed,\"skipped\":0,\"coverage\":null,\"duration_ms\":$duration}}"
           exit "$status"

package/templates/ci/gitlab-ci-sdd.yml

@@ -11,7 +11,7 @@ sdd_quality_gate:
   before_script:
     - npm install
   script:
-    - node skywalk-sdd/log.js doctor --project="$SDD_PROJECT" --change="$SDD_CHANGE"
+    - node skywalk-sdd/log.cjs doctor --project="$SDD_PROJECT" --change="$SDD_CHANGE"
     - |
       set +e
       start_ms=$(date +%s%3N)
@@ -25,7 +25,7 @@ sdd_quality_gate:
         result="failure"
         success="false"
       fi
-      node skywalk-sdd/log.js record --type=build_result --command=ci --project="$SDD_PROJECT" --change="$SDD_CHANGE" --agent="$SDD_AGENT" --source=ci --session-id="$SDD_SESSION" --result="$result" --summary="CI build $result" --details-json="{\"build_results\":{\"command\":\"$SDD_BUILD_COMMAND\",\"success\":$success,\"duration_ms\":$duration,\"error_count\":0}}"
+      node skywalk-sdd/log.cjs record --type=build_result --command=ci --project="$SDD_PROJECT" --change="$SDD_CHANGE" --agent="$SDD_AGENT" --source=ci --session-id="$SDD_SESSION" --result="$result" --summary="CI build $result" --details-json="{\"build_results\":{\"command\":\"$SDD_BUILD_COMMAND\",\"success\":$success,\"duration_ms\":$duration,\"error_count\":0}}"
       if [ "$status" -ne 0 ]; then exit "$status"; fi
     - |
       set +e
@@ -40,5 +40,5 @@ sdd_quality_gate:
         result="failure"
         failed=1
       fi
-      node skywalk-sdd/log.js record --type=test_result --command=ci --project="$SDD_PROJECT" --change="$SDD_CHANGE" --agent="$SDD_AGENT" --source=ci --session-id="$SDD_SESSION" --result="$result" --summary="CI test $result" --details-json="{\"test_results\":{\"command\":\"$SDD_TEST_COMMAND\",\"passed\":0,\"failed\":$failed,\"skipped\":0,\"coverage\":null,\"duration_ms\":$duration}}"
+      node skywalk-sdd/log.cjs record --type=test_result --command=ci --project="$SDD_PROJECT" --change="$SDD_CHANGE" --agent="$SDD_AGENT" --source=ci --session-id="$SDD_SESSION" --result="$result" --summary="CI test $result" --details-json="{\"test_results\":{\"command\":\"$SDD_TEST_COMMAND\",\"passed\":0,\"failed\":$failed,\"skipped\":0,\"coverage\":null,\"duration_ms\":$duration}}"
       if [ "$status" -ne 0 ]; then exit "$status"; fi

package/templates/git-hooks/{pre-push-sdd-check.js → pre-push-sdd-check.cjs}

@@ -16,7 +16,7 @@ function main() {
   const logCli = path.join(projectRoot, 'skywalk-sdd', 'log.js');
 
   if (!fs.existsSync(logCli)) {
-    console.log('SDD pre-push: skywalk-sdd/log.js not found; doctor gate skipped.');
+    console.log('SDD pre-push: skywalk-sdd/log.cjs not found; doctor gate skipped.');
     return;
   }
 

package/templates/hooks/claude/hooks/{sdd-prompt.js → sdd-prompt.cjs}

@@ -54,8 +54,8 @@ const activeStages = readActiveStages(projectRoot)
 
 const lines = [
   'SDD Telemetry reminder:',
-  '- Run skywalk-sdd/log.js start before the OPSX stage work begins.',
-  '- Run skywalk-sdd/log.js end before stopping the stage.',
+  '- Run skywalk-sdd/log.cjs start before the OPSX stage work begins.',
+  '- Run skywalk-sdd/log.cjs end before stopping the stage.',
   '- Hooks are only an enhancement; OPSX command instructions remain authoritative.',
 ];
 

package/templates/hooks/claude/hooks/{sdd-stop.js → sdd-stop.cjs}

@@ -78,5 +78,5 @@ for (const event of activeStages) {
 console.log([
   'SDD Telemetry warning: open stage(s) detected.',
   ...activeStages.map(event => `- ${event.change || 'general'}:${event.command || event.stage || 'unknown'} event_id=${event.event_id}`),
-  'Run skywalk-sdd/log.js end before closing the OPSX stage, or explicitly mark it partial/failure.',
+  'Run skywalk-sdd/log.cjs end before closing the OPSX stage, or explicitly mark it partial/failure.',
 ].join('\n'));

package/templates/hooks/claude/settings.json

@@ -5,7 +5,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node .claude/hooks/sdd-prompt.js"
+            "command": "node .claude/hooks/sdd-prompt.cjs"
           }
         ]
       }
@@ -16,7 +16,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node .claude/hooks/sdd-pre-tool.js"
+            "command": "node .claude/hooks/sdd-pre-tool.cjs"
           }
         ]
       }
@@ -27,7 +27,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node .claude/hooks/sdd-post-tool.js"
+            "command": "node .claude/hooks/sdd-post-tool.cjs"
           }
         ]
       }
@@ -37,7 +37,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node .claude/hooks/sdd-stop.js"
+            "command": "node .claude/hooks/sdd-stop.cjs"
           }
         ]
       }

package/templates/opsx-commands/apply.md

@@ -12,7 +12,7 @@ argument-hint: "[change-name] [capability-name] [上下文文件...]"
 > - 在 Windows Bash / Git Bash / Claude Bash 中，禁止裸写 Windows 反斜杠绝对路径（如 `D:\project\demo`）；如必须使用绝对路径，请写成正斜杠路径或加引号。
 > - 不要省略 `--source=opsx-command` 与 `--session-id=<会话ID>`。
 > **📊 Telemetry（必做，不得跳过）**
-> 在终端执行（必须成功）：`node skywalk-sdd/log.js start --command=apply --project=. --change=<变更名称> --capability=<capability-name> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID> --git-sha=<base_git_sha_or_none>`，记录返回的 event_id。
+> 在终端执行（必须成功）：`node skywalk-sdd/log.cjs start --command=apply --project=. --change=<变更名称> --capability=<capability-name> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID> --git-sha=<base_git_sha_or_none>`，记录返回的 event_id。
 
 > **🔒 Git 策略（只读增强，不改变开发流）**
 > - Git 只作为可选度量数据源，不是 apply 前置条件。
@@ -65,7 +65,7 @@ argument-hint: "[change-name] [capability-name] [上下文文件...]"
 
    在终端执行（若命令失败必须中止本阶段，不得跳过）：
    ```bash
-   node skywalk-sdd/log.js start --command=apply --project=. --change=<变更名称> --capability=<capability-name> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID> --git-sha=<base_git_sha_or_none>
+   node skywalk-sdd/log.cjs start --command=apply --project=. --change=<变更名称> --capability=<capability-name> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID> --git-sha=<base_git_sha_or_none>
    ```
    保存输出 JSON 中的 `event_id`，供阶段结束使用。
 
@@ -350,7 +350,7 @@ argument-hint: "[change-name] [capability-name] [上下文文件...]"
       
       5. **记录构建 Telemetry**：
          ```bash
-         node skywalk-sdd/log.js record --type=build_result --command=apply --project=. --change=<变更名称> --capability=<capability-name> --task-id=<TASK-ID> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID> --result=success/failure --summary="编译检查结果" --details-json="{\"build_results\":{\"command\":\"<实际编译命令>\",\"success\":true,\"duration_ms\":0,\"error_count\":0}}"
+         node skywalk-sdd/log.cjs record --type=build_result --command=apply --project=. --change=<变更名称> --capability=<capability-name> --task-id=<TASK-ID> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID> --result=success/failure --summary="编译检查结果" --details-json="{\"build_results\":{\"command\":\"<实际编译命令>\",\"success\":true,\"duration_ms\":0,\"error_count\":0}}"
          ```
          `build_results` 字段口径：
          - `command`: 实际执行的编译/构建命令。
@@ -402,8 +402,10 @@ argument-hint: "[change-name] [capability-name] [上下文文件...]"
 
       4. **记录任务级 Telemetry**：
          ```bash
-         node skywalk-sdd/log.js record --type=task_update --command=apply --project=. --change=<变更名称> --capability=<capability-name> --task-id=<TASK-ID> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID> --status=completed --result=success --summary="<TASK-ID> 完成" --details-json="{\"files_changed\":[],\"build_results\":{\"command\":\"<实际编译命令>\",\"success\":true,\"duration_ms\":0,\"error_count\":0},\"test_results\":{\"command\":\"<实际测试命令>\",\"passed\":0,\"failed\":0,\"skipped\":0,\"coverage\":null,\"duration_ms\":0}}"
+         node skywalk-sdd/log.cjs record --type=task_update --command=apply --project=. --change=<变更名称> --capability=<capability-name> --task-id=<TASK-ID> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID> --status=completed --result=success --summary="<TASK-ID> 完成" --details-json="{\"files_changed\":[],\"build_results\":{\"command\":\"<实际编译命令>\",\"success\":true,\"duration_ms\":0,\"error_count\":0},\"test_results\":{\"command\":\"<实际测试命令>\",\"passed\":0,\"failed\":0,\"skipped\":0,\"coverage\":null,\"duration_ms\":0}}"
          ```
+         **⚠️ 注意**：`--task-id=<TASK-ID>` 中的 `<TASK-ID>` 必须替换为当前任务的实际 ID（如 `TASK-USER-AUTH-01`），不得保留占位符，否则 E4 指标无法计算。
+
          若任务失败或暂停，`--status` 使用 `failed` / `blocked`，`--result` 使用 `failure` / `partial`，并在 details 中记录失败原因。
 
    g. **继续下一个可执行任务**
@@ -481,8 +483,8 @@ argument-hint: "[change-name] [capability-name] [上下文文件...]"
 > - 在 Windows Bash / Git Bash / Claude Bash 中，禁止裸写 Windows 反斜杠绝对路径（如 `D:\project\demo`）；如必须使用绝对路径，请写成正斜杠路径或加引号。
 > - 不要省略 `--source=opsx-command` 与 `--session-id=<会话ID>`。
 > **📊 Telemetry（必做，不得跳过）**
-> 每次编译检查后，必须记录构建事件：`node skywalk-sdd/log.js record --type=build_result --command=apply --project=. --change=<变更名称> --capability=<capability-name> --task-id=<TASK-ID> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID> --result=success/failure --summary="编译检查结果" --details-json="{\"build_results\":{\"command\":\"<实际编译命令>\",\"success\":true,\"duration_ms\":0,\"error_count\":0}}"`
-> 每完成一个任务，必须记录任务级结构化事件：`node skywalk-sdd/log.js record --type=task_update --command=apply --project=. --change=<变更名称> --capability=<capability-name> --task-id=<TASK-ID> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID> --status=completed --result=success --summary="<TASK-ID> 完成" --details-json="{\"files_changed\":[],\"build_results\":{\"command\":\"<实际编译命令>\",\"success\":true,\"duration_ms\":0,\"error_count\":0},\"test_results\":{\"command\":\"<实际测试命令>\",\"passed\":0,\"failed\":0,\"skipped\":0,\"coverage\":null,\"duration_ms\":0}}"`
-> AI 代码产出完成后，必须记录采纳率快照，但不得为了采集快照自动提交 commit。Git 可用时只读统计 SHA/diff；Git 不可用时使用 `vcs_mode=no-git` 和 `base_git_sha=null`：`node skywalk-sdd/log.js record --type=ai_adoption_review --command=apply --project=. --change=<变更名称> --capability=<capability-name> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID> --status=ai_snapshot --result=success --summary="AI 代码产出快照" --details-json="{\"ai_adoption\":{\"review_status\":\"ai_snapshot\",\"vcs_mode\":\"<readonly|no-git>\",\"base_git_sha\":\"<base_git_sha_or_null>\",\"ai_git_sha\":\"<ai_git_sha_or_null>\",\"ai_diff\":{\"files_changed\":0,\"added_lines\":null,\"deleted_lines\":null},\"notes\":\"未自动创建 Git 仓库，未自动提交 commit；仅记录可用统计\"}}"`
-> 若后续发生人工修改并完成采纳确认，必须补录最终采纳统计；若非 Git 项目，SHA 可填 `null`，采纳行数由人工或工具统计补录：`node skywalk-sdd/log.js record --type=ai_adoption_review --command=apply --project=. --change=<变更名称> --capability=<capability-name> --agent=<Agent类型> --source=manual --session-id=<会话ID> --status=final --result=success --summary="AI 代码采纳率人工确认" --details-json="{\"ai_adoption\":{\"review_status\":\"final\",\"vcs_mode\":\"<readonly|no-git>\",\"base_git_sha\":\"<base_git_sha_or_null>\",\"ai_git_sha\":\"<ai_git_sha_or_null>\",\"final_git_sha\":\"<final_git_sha_or_null>\",\"retained_lines\":0,\"rewritten_lines\":0,\"deleted_lines\":0,\"ai_diff\":{\"files_changed\":0,\"added_lines\":null,\"deleted_lines\":null},\"final_diff\":{\"files_changed\":0,\"added_lines\":null,\"deleted_lines\":null},\"notes\":\"只记录行数统计，不记录源码；非 Git 项目允许 SHA 为 null\"}}"`
-> 阶段结束时执行（必须成功）：`node skywalk-sdd/log.js end --event-id=<开头记录的event_id> --command=apply --project=. --change=<变更名称> --capability=<capability-name> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID> --result=success/failure --summary="实施结果摘要"`
+> 每次编译检查后，必须记录构建事件：`node skywalk-sdd/log.cjs record --type=build_result --command=apply --project=. --change=<变更名称> --capability=<capability-name> --task-id=<TASK-ID> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID> --result=success/failure --summary="编译检查结果" --details-json="{\"build_results\":{\"command\":\"<实际编译命令>\",\"success\":true,\"duration_ms\":0,\"error_count\":0}}"`
+> 每完成一个任务，必须记录任务级结构化事件：`node skywalk-sdd/log.cjs record --type=task_update --command=apply --project=. --change=<变更名称> --capability=<capability-name> --task-id=<TASK-ID> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID> --status=completed --result=success --summary="<TASK-ID> 完成" --details-json="{\"files_changed\":[],\"build_results\":{\"command\":\"<实际编译命令>\",\"success\":true,\"duration_ms\":0,\"error_count\":0},\"test_results\":{\"command\":\"<实际测试命令>\",\"passed\":0,\"failed\":0,\"skipped\":0,\"coverage\":null,\"duration_ms\":0}}"`
+> AI 代码产出完成后，必须记录采纳率快照，但不得为了采集快照自动提交 commit。Git 可用时只读统计 SHA/diff；Git 不可用时使用 `vcs_mode=no-git` 和 `base_git_sha=null`：`node skywalk-sdd/log.cjs record --type=ai_adoption_review --command=apply --project=. --change=<变更名称> --capability=<capability-name> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID> --status=ai_snapshot --result=success --summary="AI 代码产出快照" --details-json="{\"ai_adoption\":{\"review_status\":\"ai_snapshot\",\"vcs_mode\":\"<readonly|no-git>\",\"base_git_sha\":\"<base_git_sha_or_null>\",\"ai_git_sha\":\"<ai_git_sha_or_null>\",\"ai_diff\":{\"files_changed\":0,\"added_lines\":null,\"deleted_lines\":null},\"notes\":\"未自动创建 Git 仓库，未自动提交 commit；仅记录可用统计\"}}"`
+> 若后续发生人工修改并完成采纳确认，必须补录最终采纳统计；若非 Git 项目，SHA 可填 `null`，采纳行数由人工或工具统计补录：`node skywalk-sdd/log.cjs record --type=ai_adoption_review --command=apply --project=. --change=<变更名称> --capability=<capability-name> --agent=<Agent类型> --source=manual --session-id=<会话ID> --status=final --result=success --summary="AI 代码采纳率人工确认" --details-json="{\"ai_adoption\":{\"review_status\":\"final\",\"vcs_mode\":\"<readonly|no-git>\",\"base_git_sha\":\"<base_git_sha_or_null>\",\"ai_git_sha\":\"<ai_git_sha_or_null>\",\"final_git_sha\":\"<final_git_sha_or_null>\",\"retained_lines\":0,\"rewritten_lines\":0,\"deleted_lines\":0,\"ai_diff\":{\"files_changed\":0,\"added_lines\":null,\"deleted_lines\":null},\"final_diff\":{\"files_changed\":0,\"added_lines\":null,\"deleted_lines\":null},\"notes\":\"只记录行数统计，不记录源码；非 Git 项目允许 SHA 为 null\"}}"`
+> 阶段结束时执行（必须成功）：`node skywalk-sdd/log.cjs end --event-id=<开头记录的event_id> --command=apply --project=. --change=<变更名称> --capability=<capability-name> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID> --result=success/failure --summary="实施结果摘要"`