kld-sdd 2.4.7 → 2.4.9

package/skywalk-sdd/index.js

@@ -14,6 +14,9 @@
 const fs = require('fs');
 const path = require('path');
 const crypto = require('crypto');
+const { execFileSync } = require('child_process');
+
+const SCHEMA_VERSION = 2;
 
 // ── 配置 ──────────────────────────────────────────────
 
@@ -22,6 +25,10 @@ function getDataDir(projectRoot) {
   return path.join(projectRoot, 'skywalk-sdd');
 }
 
+function getStateDir(projectRoot) {
+  return path.join(getDataDir(projectRoot), 'state');
+}
+
 // SDD 标准阶段顺序
 const STAGE_ORDER = ['propose', 'spec', 'design', 'task', 'check', 'apply', 'test', 'archive', 'explore'];
 const CORE_STAGES = ['propose', 'spec', 'design', 'apply', 'test'];
@@ -45,12 +52,466 @@ function nowISO() {
   return new Date().toISOString();
 }
 
+function normalizeProjectRoot(projectRoot) {
+  const rawProjectRoot = projectRoot || process.cwd();
+  if (process.platform === 'win32' && /^[a-zA-Z]:[^\\/]/.test(String(rawProjectRoot))) {
+    fail(`Windows 项目路径格式不安全: ${rawProjectRoot}。请使用 --project=.，或使用正斜杠路径如 D:/project/demo，或给路径加引号。`);
+  }
+  return path.resolve(rawProjectRoot);
+}
+
+function inferAgentType(args) {
+  const explicit = args.agent || args['agent-type'];
+  if (explicit) return explicit;
+
+  return process.env.SDD_AGENT_TYPE
+    || process.env.AI_AGENT_TYPE
+    || process.env.CLAUDE_CODE
+    || process.env.CURSOR_AGENT
+    || 'unknown';
+}
+
+function readJsonFile(filePath, projectRoot) {
+  const resolved = path.isAbsolute(filePath)
+    ? filePath
+    : path.resolve(projectRoot || process.cwd(), filePath);
+  return JSON.parse(fs.readFileSync(resolved, 'utf8'));
+}
+
+function parseJsonOption(args, inlineKey, fileKey, projectRoot, fallback = {}) {
+  const inlineValue = args[inlineKey];
+  const fileValue = args[fileKey];
+
+  if (inlineValue && fileValue) {
+    throw new Error(`不能同时指定 --${inlineKey} 和 --${fileKey}`);
+  }
+  if (inlineValue) {
+    return JSON.parse(inlineValue);
+  }
+  if (fileValue) {
+    return readJsonFile(fileValue, projectRoot);
+  }
+  return fallback;
+}
+
+function cleanOptionalFields(event) {
+  for (const key of Object.keys(event)) {
+    if (event[key] == null || event[key] === '') {
+      delete event[key];
+    }
+  }
+  return event;
+}
+
+function fail(message) {
+  console.error(`错误: ${message}`);
+  process.exit(1);
+}
+
 /** 安全化 change name，防止路径穿越 */
 function safeChangeName(name) {
   if (!name) return 'general';
   return name.replace(/[^a-zA-Z0-9_-]/g, '-').replace(/^-+|-+$/g, '') || 'general';
 }
 
+function getActiveStageKey(criteria) {
+  if (criteria.session_id) {
+    return `session-${safeChangeName(criteria.session_id)}`;
+  }
+  const parts = [
+    criteria.change || 'general',
+    criteria.command || criteria.stage || 'unknown',
+    criteria.agent_type || 'unknown',
+  ];
+  return safeChangeName(parts.join('-'));
+}
+
+function getActiveStageFile(projectRoot, criteria) {
+  return path.join(getStateDir(projectRoot), `${getActiveStageKey(criteria)}.json`);
+}
+
+function writeActiveStage(projectRoot, event) {
+  const stateDir = getStateDir(projectRoot);
+  ensureDir(stateDir);
+  fs.writeFileSync(
+    getActiveStageFile(projectRoot, event),
+    JSON.stringify({ updated_at: nowISO(), event }, null, 2),
+    'utf8'
+  );
+}
+
+function readStateFile(filePath) {
+  try {
+    const data = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+    return data.event || null;
+  } catch {
+    return null;
+  }
+}
+
+function findActiveStage(projectRoot, criteria) {
+  const exactFile = getActiveStageFile(projectRoot, criteria);
+  if (fs.existsSync(exactFile)) {
+    const exact = readStateFile(exactFile);
+    if (exact) return exact;
+  }
+
+  const stateDir = getStateDir(projectRoot);
+  if (!fs.existsSync(stateDir)) return null;
+
+  const candidates = fs.readdirSync(stateDir)
+    .filter(file => file.endsWith('.json'))
+    .map(file => readStateFile(path.join(stateDir, file)))
+    .filter(Boolean)
+    .filter(event => {
+      if (criteria.change && event.change !== criteria.change) return false;
+      if (criteria.command && event.command !== criteria.command) return false;
+      if (criteria.agent_type && event.agent_type !== criteria.agent_type) return false;
+      return true;
+    })
+    .sort((a, b) => new Date(b.timestamp).getTime() - new Date(a.timestamp).getTime());
+
+  if (candidates.length > 0) return candidates[0];
+
+  // 跨 session 匹配：当 session_id 变化（如 compaction 恢复）但 command+change 相同时，
+  // 在 events 目录中搜索最近的 stage_start 事件
+  if (criteria.command && criteria.change) {
+    const dataDir = getDataDir(projectRoot);
+    const eventsDir = path.join(dataDir, 'events');
+    if (fs.existsSync(eventsDir)) {
+      const changeDirs = fs.readdirSync(eventsDir).filter(d => {
+        return fs.statSync(path.join(eventsDir, d)).isDirectory();
+      });
+      const matchingStarts = [];
+      for (const changeDir of changeDirs) {
+        const dir = path.join(eventsDir, changeDir);
+        const files = fs.readdirSync(dir).filter(f => f.endsWith('.jsonl')).sort().reverse();
+        for (const file of files) {
+          const lines = fs.readFileSync(path.join(dir, file), 'utf-8').split('\n').filter(Boolean);
+          for (let i = lines.length - 1; i >= 0; i--) {
+            try {
+              const event = JSON.parse(lines[i]);
+              if (event.type === 'stage_start' &&
+                  event.command === criteria.command &&
+                  event.change === criteria.change &&
+                  (!criteria.capability || event.capability === criteria.capability)) {
+                matchingStarts.push(event);
+              }
+            } catch {}
+          }
+        }
+      }
+      if (matchingStarts.length > 0) {
+        matchingStarts.sort((a, b) => new Date(b.timestamp).getTime() - new Date(a.timestamp).getTime());
+        return matchingStarts[0];
+      }
+    }
+  }
+
+  return null;
+}
+
+function clearActiveStage(projectRoot, event) {
+  const files = [
+    getActiveStageFile(projectRoot, event),
+  ];
+  if (event.session_id) {
+    files.push(getActiveStageFile(projectRoot, { session_id: event.session_id }));
+  }
+
+  for (const file of [...new Set(files)]) {
+    if (fs.existsSync(file)) {
+      fs.unlinkSync(file);
+    }
+  }
+}
+
+function walkFiles(dirPath, predicate, files = []) {
+  if (!fs.existsSync(dirPath)) return files;
+
+  for (const entry of fs.readdirSync(dirPath, { withFileTypes: true })) {
+    const fullPath = path.join(dirPath, entry.name);
+    if (entry.isDirectory()) {
+      walkFiles(fullPath, predicate, files);
+    } else if (!predicate || predicate(fullPath)) {
+      files.push(fullPath);
+    }
+  }
+
+  return files;
+}
+
+function copyDirSync(sourceDir, targetDir) {
+  ensureDir(targetDir);
+  for (const entry of fs.readdirSync(sourceDir, { withFileTypes: true })) {
+    const sourcePath = path.join(sourceDir, entry.name);
+    const targetPath = path.join(targetDir, entry.name);
+    if (entry.isDirectory()) {
+      copyDirSync(sourcePath, targetPath);
+    } else {
+      ensureDir(path.dirname(targetPath));
+      fs.copyFileSync(sourcePath, targetPath);
+    }
+  }
+}
+
+function nextAvailableDir(baseDir, preferredName) {
+  let candidate = path.join(baseDir, preferredName);
+  let suffix = 2;
+  while (fs.existsSync(candidate)) {
+    candidate = path.join(baseDir, `${preferredName}-${suffix}`);
+    suffix += 1;
+  }
+  return candidate;
+}
+
+function getChangeDir(projectRoot, changeName) {
+  return path.join(projectRoot, 'openspec', 'changes', changeName);
+}
+
+function getArchiveRoot(projectRoot) {
+  return path.join(projectRoot, 'openspec', 'changes', 'archive');
+}
+
+function discoverTaskFiles(projectRoot, changeName) {
+  const changeDir = getChangeDir(projectRoot, changeName);
+  return walkFiles(changeDir, filePath => {
+    const fileName = path.basename(filePath).toLowerCase();
+    return fileName === 'tasks.md' || fileName === 'task.md';
+  }).sort();
+}
+
+function scanTaskCompletionFromFiles(projectRoot, changeName, taskFiles) {
+  const normalizedRoot = normalizeProjectRoot(projectRoot);
+  const files = [];
+  let completed = 0;
+  let incomplete = 0;
+  const incompleteItems = [];
+
+  for (const filePath of taskFiles) {
+    const relPath = path.relative(normalizedRoot, filePath).replace(/\\/g, '/');
+    const lines = fs.readFileSync(filePath, 'utf8').split(/\r?\n/);
+    let fileCompleted = 0;
+    let fileIncomplete = 0;
+
+    lines.forEach((line, index) => {
+      if (/\[[xX]\]/.test(line)) {
+        completed += 1;
+        fileCompleted += 1;
+      } else if (/\[\s\]/.test(line)) {
+        incomplete += 1;
+        fileIncomplete += 1;
+        incompleteItems.push({
+          file: relPath,
+          line: index + 1,
+          text: line.trim(),
+        });
+      }
+    });
+
+    files.push({
+      path: relPath,
+      completed: fileCompleted,
+      incomplete: fileIncomplete,
+      total: fileCompleted + fileIncomplete,
+    });
+  }
+
+  return {
+    change: changeName,
+    task_files: files,
+    completed,
+    incomplete,
+    total: completed + incomplete,
+    has_incomplete: incomplete > 0,
+    incomplete_items: incompleteItems,
+  };
+}
+
+function scanTaskCompletion(projectRoot, changeName) {
+  const normalizedRoot = normalizeProjectRoot(projectRoot);
+  const taskFiles = discoverTaskFiles(normalizedRoot, changeName);
+  return scanTaskCompletionFromFiles(normalizedRoot, changeName, taskFiles);
+}
+
+function scanTaskCompletionForArchiveDir(projectRoot, changeName, archiveDir) {
+  const normalizedRoot = normalizeProjectRoot(projectRoot);
+  const taskFiles = walkFiles(archiveDir, filePath => {
+    const fileName = path.basename(filePath).toLowerCase();
+    return fileName === 'tasks.md' || fileName === 'task.md';
+  }).sort();
+  return scanTaskCompletionFromFiles(normalizedRoot, changeName, taskFiles);
+}
+
+function discoverFullSpecFiles(changeDir) {
+  const specsDir = path.join(changeDir, 'specs');
+  const specs = [];
+
+  if (fs.existsSync(specsDir)) {
+    for (const entry of fs.readdirSync(specsDir, { withFileTypes: true })) {
+      if (!entry.isDirectory()) continue;
+      const specPath = path.join(specsDir, entry.name, 'spec.md');
+      if (fs.existsSync(specPath)) {
+        specs.push({ capability: entry.name, source: specPath });
+      }
+    }
+  }
+
+  const simpleSpecPath = path.join(changeDir, 'spec.md');
+  if (fs.existsSync(simpleSpecPath)) {
+    specs.push({ capability: path.basename(changeDir), source: simpleSpecPath });
+  }
+
+  return specs.sort((a, b) => a.capability.localeCompare(b.capability));
+}
+
+function toProjectRelative(projectRoot, targetPath) {
+  return path.relative(projectRoot, targetPath).replace(/\\/g, '/');
+}
+
+function findArchivedChangeDir(projectRoot, changeName) {
+  const archiveRoot = getArchiveRoot(projectRoot);
+  if (!fs.existsSync(archiveRoot)) return null;
+
+  const prefix = `-${changeName}`;
+  const candidates = fs.readdirSync(archiveRoot, { withFileTypes: true })
+    .filter(entry => entry.isDirectory() && entry.name.includes(prefix))
+    .map(entry => path.join(archiveRoot, entry.name))
+    .sort((a, b) => fs.statSync(b).mtimeMs - fs.statSync(a).mtimeMs);
+
+  return candidates[0] || null;
+}
+
+function syncArchivedSpecs(projectRoot, archiveDir) {
+  const copiedSpecs = [];
+  const specFiles = discoverFullSpecFiles(archiveDir);
+
+  for (const spec of specFiles) {
+    const targetSpec = path.join(projectRoot, 'openspec', 'specs', spec.capability, 'spec.md');
+    ensureDir(path.dirname(targetSpec));
+    fs.copyFileSync(spec.source, targetSpec);
+    copiedSpecs.push({
+      capability: spec.capability,
+      source: toProjectRelative(projectRoot, spec.source),
+      target: toProjectRelative(projectRoot, targetSpec),
+    });
+  }
+
+  return copiedSpecs;
+}
+
+function ensureArchiveManifest(projectRoot, changeName, archiveDir, options = {}) {
+  const manifestPath = path.join(archiveDir, 'archive-manifest.json');
+  const copiedSpecs = syncArchivedSpecs(projectRoot, archiveDir);
+  const manifest = {
+    change: changeName,
+    archived_at: options.archivedAt || nowISO(),
+    reason: options.reason || '',
+    method: options.method || 'skywalk-full-spec-archive',
+    source_path: `openspec/changes/${changeName}`,
+    archive_path: toProjectRelative(projectRoot, archiveDir),
+    copied_specs: copiedSpecs,
+  };
+  fs.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2) + '\n', 'utf8');
+  return {
+    manifest,
+    manifest_path: manifestPath,
+    copied_specs: copiedSpecs,
+  };
+}
+
+function ensureArchiveSuccessArtifacts(projectRoot, changeName, details = {}, options = {}) {
+  const normalizedRoot = normalizeProjectRoot(projectRoot);
+  const activeChangeDir = getChangeDir(normalizedRoot, changeName);
+  const archiveReason = details.archive_result?.reason || options.reason || '';
+  const reportPath = options.reportOutput
+    ? (path.isAbsolute(options.reportOutput) ? options.reportOutput : path.resolve(normalizedRoot, options.reportOutput))
+    : '';
+
+  let archiveDir = details.archive_result?.archive_path
+    ? path.resolve(normalizedRoot, details.archive_result.archive_path)
+    : findArchivedChangeDir(normalizedRoot, changeName);
+  let archiveMethod = details.archive_result?.method || '';
+
+  if (!archiveDir && fs.existsSync(activeChangeDir)) {
+    const archived = archiveChangeDocs(normalizedRoot, changeName, { reason: archiveReason || '' });
+    archiveDir = archived.archive_path;
+    archiveMethod = archived.method;
+  }
+
+  if (!archiveDir || !fs.existsSync(archiveDir)) {
+    return {
+      changed: false,
+      archive_result: details.archive_result || {},
+      task_completion: details.archive_result?.task_completion || null,
+    };
+  }
+
+  const manifestInfo = ensureArchiveManifest(normalizedRoot, changeName, archiveDir, {
+    reason: archiveReason,
+    method: archiveMethod || 'skywalk-full-spec-archive',
+    archivedAt: details.archive_result?.archived_at || nowISO(),
+  });
+  const taskCompletion = details.archive_result?.task_completion || scanTaskCompletionForArchiveDir(normalizedRoot, changeName, archiveDir);
+
+  const archiveResult = {
+    reason: archiveReason,
+    method: manifestInfo.manifest.method,
+    archive_path: manifestInfo.manifest.archive_path,
+    report_path: reportPath ? toProjectRelative(normalizedRoot, reportPath) : (details.archive_result?.report_path || ''),
+    manifest_path: toProjectRelative(normalizedRoot, manifestInfo.manifest_path),
+    task_completion: taskCompletion,
+    copied_specs: manifestInfo.copied_specs,
+  };
+
+  return {
+    changed: true,
+    archive_result: archiveResult,
+    task_completion: taskCompletion,
+  };
+}
+
+function archiveChangeDocs(projectRoot, changeName, options = {}) {
+  const normalizedRoot = normalizeProjectRoot(projectRoot);
+  if (!changeName) {
+    throw new Error('缺少 change 名称');
+  }
+  if (safeChangeName(changeName) !== changeName) {
+    throw new Error(`change 名称不安全: ${changeName}`);
+  }
+
+  const sourceDir = getChangeDir(normalizedRoot, changeName);
+  if (!fs.existsSync(sourceDir)) {
+    throw new Error(`变更目录不存在: ${sourceDir}`);
+  }
+  if (path.basename(sourceDir) === 'archive') {
+    throw new Error('不能归档 archive 目录本身');
+  }
+
+  const archiveRoot = getArchiveRoot(normalizedRoot);
+  ensureDir(archiveRoot);
+  const archiveDate = options.date || today();
+  const archiveDir = nextAvailableDir(archiveRoot, `${archiveDate}-${changeName}`);
+
+  copyDirSync(sourceDir, archiveDir);
+  const manifestInfo = ensureArchiveManifest(normalizedRoot, changeName, archiveDir, {
+    reason: options.reason || '',
+    method: 'skywalk-full-spec-archive',
+  });
+  const manifest = manifestInfo.manifest;
+
+  if (!options.keepActive) {
+    fs.rmSync(sourceDir, { recursive: true, force: true });
+  }
+
+  return {
+    ...manifest,
+    project_root: normalizedRoot,
+    archive_path: archiveDir,
+    active_change_exists: fs.existsSync(sourceDir),
+  };
+}
+
 /** 追加一行 JSONL 到事件文件（写入失败时抛出异常） */
 function appendEvent(dataDir, changeName, event) {
   const dir = path.join(dataDir, 'events', safeChangeName(changeName));
@@ -107,7 +568,7 @@ function readAllEvents(dataDir) {
  * 计算单个 change 的四维指标
  */
 function computeChangeMetrics(changeName, events) {
-  const changeEvents = events.filter(e => e.change === changeName);
+  const changeEvents = events.filter(e => e.change === changeName && !e.orphan);
   if (changeEvents.length === 0) return null;
 
   const starts = changeEvents.filter(e => e.type === 'stage_start');
@@ -148,8 +609,11 @@ function computeChangeMetrics(changeName, events) {
     : null;
 
   // 首次 Apply 成功率
-  const testEnds = ends.filter(e => e.command === 'test');
-  const firstTestSuccess = testEnds.length > 0 ? testEnds[0].result === 'success' : null;
+  const testEvents = getTestEvents(changeEvents);
+  const firstTestEvent = firstByTimestamp(testEvents);
+  const firstTestSuccess = firstTestEvent
+    ? (firstTestEvent.result === 'success' || getTestResults(firstTestEvent)?.failed === 0)
+    : null;
 
   // 阶段平均耗时
   const stageDurations = {};
@@ -165,24 +629,31 @@ function computeChangeMetrics(changeName, events) {
   }
 
   // ── 维度三：质量信号 ──
-  const firstTestResult = testEnds.length > 0 ? testEnds[0] : null;
-  const firstTestPassRate = firstTestResult?.details?.test_results
-    ? firstTestResult.details.test_results.passed / 
-      (firstTestResult.details.test_results.passed + firstTestResult.details.test_results.failed + (firstTestResult.details.test_results.skipped || 0))
-    : null;
-
-  const checkEnds = ends.filter(e => e.command === 'check');
-  const firstCheckPass = checkEnds.length > 0 
-    ? (checkEnds[0].details?.check_results?.errors || 0) === 0 
+  const stageTestEvent = firstByTimestamp(testEvents.filter(e => {
+    return e.command === 'test' || e.type === 'test_result';
+  }));
+  const firstTestPassRate = getTestPassRate(stageTestEvent || firstTestEvent);
+
+  const checkEvents = getCheckEvents(changeEvents);
+  const firstCheckEvent = firstByTimestamp(checkEvents);
+  const firstCheckPass = firstCheckEvent
+    ? (getCheckResults(firstCheckEvent)?.errors || 0) === 0
     : null;
 
   // Apply-Test-Fix 循环次数
   const applyCount = starts.filter(e => e.command === 'apply').length;
 
   // 测试覆盖率趋势
-  const coverageTrend = testEnds
-    .filter(e => e.details?.test_results?.coverage != null)
-    .map(e => ({ timestamp: e.timestamp, coverage: e.details.test_results.coverage }));
+  const coverageTrend = testEvents
+    .map(e => ({ event: e, results: getTestResults(e) }))
+    .filter(item => item.results?.coverage != null)
+    .map(item => ({ timestamp: item.event.timestamp, coverage: item.results.coverage }));
+
+  const conformanceMetrics = computeConformanceMetrics(changeEvents);
+  const aiAdoptionMetrics = computeAiAdoptionMetrics(changeEvents);
+  const aiFirstPassMetrics = computeAiFirstPassMetrics(changeEvents);
+  const specTestCoverageMetrics = computeSpecTestCoverageMetrics(changeEvents);
+  const manualInsightMetrics = computeManualInsightMetrics(changeEvents);
 
   // ── 维度四：团队洞察 ──
   const agentTypes = [...new Set(changeEvents.filter(e => e.agent_type).map(e => e.agent_type))];
@@ -205,16 +676,25 @@ function computeChangeMetrics(changeName, events) {
       avg_stage_durations_ms: avgStageDurations,
     },
     quality_signals: {
+      e4_ai_code_first_pass_rate: aiFirstPassMetrics.e4_ai_code_first_pass_rate,
       first_test_pass_rate: firstTestPassRate,
       first_check_pass: firstCheckPass,
       apply_test_fix_cycles: applyCount,
       coverage_trend: coverageTrend,
+      q1_spec_conformance_score: conformanceMetrics.q1_spec_conformance_score,
+      q4_spec_driven_test_coverage: specTestCoverageMetrics.q4_spec_driven_test_coverage,
+      conformance_counts: conformanceMetrics.conformance_counts,
+      conformance_manual_confirmed: conformanceMetrics.manual_confirmed,
+      spec_test_scenario_counts: specTestCoverageMetrics.scenario_counts,
+      p2_ai_code_adoption_rate: aiAdoptionMetrics.p2_ai_code_adoption_rate,
+      ai_adoption_level: aiAdoptionMetrics.adoption_level,
     },
     team_insights: {
       agent_types: agentTypes,
       is_completed: isCompleted,
       total_stages_executed: stageSequence.length,
       executed_stages: executedStages,
+      manual_insights: manualInsightMetrics,
     },
   };
 }
@@ -286,12 +766,17 @@ function computeOverviewMetrics(events) {
       : null;
   })();
   const avgApplyTestCycles = changeMetrics.reduce((s, m) => s + m.quality_signals.apply_test_fix_cycles, 0) / totalChanges;
+  const avgAiFirstPassRate = averageMetric(changeMetrics, m => m.quality_signals.e4_ai_code_first_pass_rate);
+  const avgConformanceScore = averageMetric(changeMetrics, m => m.quality_signals.q1_spec_conformance_score);
+  const avgSpecDrivenTestCoverage = averageMetric(changeMetrics, m => m.quality_signals.q4_spec_driven_test_coverage);
+  const avgAiAdoptionRate = averageMetric(changeMetrics, m => m.quality_signals.p2_ai_code_adoption_rate);
 
   // 维度四汇总
   const completedCount = changeMetrics.filter(m => m.team_insights.is_completed).length;
   const changeCompletionRate = completedCount / totalChanges;
   const activeChanges = totalChanges - completedCount;
   const allAgents = [...new Set(changeMetrics.flatMap(m => m.team_insights.agent_types))];
+  const manualInsightMetrics = computeManualInsightMetrics(events.filter(e => !e.orphan));
 
   return {
     total_changes: totalChanges,
@@ -305,140 +790,1537 @@ function computeOverviewMetrics(events) {
       first_apply_success_rate: firstApplySuccessRate != null ? Math.round(firstApplySuccessRate * 100) / 100 : null,
     },
     quality_signals: {
+      avg_e4_ai_code_first_pass_rate: avgAiFirstPassRate,
       first_check_pass_rate: firstCheckPassRate != null ? Math.round(firstCheckPassRate * 100) / 100 : null,
       avg_apply_test_fix_cycles: Math.round(avgApplyTestCycles * 10) / 10,
+      avg_q1_spec_conformance_score: avgConformanceScore,
+      avg_q4_spec_driven_test_coverage: avgSpecDrivenTestCoverage,
+      avg_p2_ai_code_adoption_rate: avgAiAdoptionRate,
     },
     team_insights: {
       change_completion_rate: Math.round(changeCompletionRate * 100) / 100,
       active_changes: activeChanges,
       agent_distribution: allAgents,
+      manual_insights: manualInsightMetrics,
     },
   };
 }
 
-// ── CLI 参数解析 ──────────────────────────────────────
+function roundMetric(value, digits = 2) {
+  if (value == null || Number.isNaN(value)) return null;
+  const factor = 10 ** digits;
+  return Math.round(value * factor) / factor;
+}
 
-/** 解析 --key=value 格式的参数 */
-function parseArgs(argv) {
-  const args = {};
-  for (const arg of argv) {
-    const match = arg.match(/^--([a-zA-Z_-]+)=(.*)$/);
-    if (match) {
-      args[match[1]] = match[2];
-    } else if (arg.match(/^--([a-zA-Z_-]+)$/)) {
-      args[arg.slice(2)] = true;
-    }
-  }
-  return args;
+function sumDurations(events, commands) {
+  return events
+    .filter(e => e.type === 'stage_end' && commands.includes(e.command) && e.duration_ms != null)
+    .reduce((sum, e) => sum + e.duration_ms, 0);
 }
 
-// ── CLI 命令实现 ─────────────────────────────────────
+function sumAttemptDurations(attempts, commands) {
+  return attempts
+    .filter(attempt => commands.includes(attempt.command))
+    .reduce((sum, attempt) => sum + (Number.isFinite(attempt.duration_ms) ? attempt.duration_ms : 0), 0);
+}
 
-/**
- * log start: 记录阶段开始
- */
-function cmdStart(args) {
-  const command = args.command;
-  const projectRoot = args.project || args['project-root'] || process.cwd();
-  const changeName = args.change || args['change-name'] || '';
-  const agentType = args.agent || args['agent-type'] || 'unknown';
+function firstByTimestamp(events) {
+  return [...events].sort((a, b) => new Date(a.timestamp).getTime() - new Date(b.timestamp).getTime())[0] || null;
+}
 
-  if (!command) {
-    console.error('错误: 缺少 --command 参数');
-    console.error('用法: node skywalk-sdd/log.js start --command=propose --project=/path');
-    process.exit(1);
-  }
+function latestByTimestamp(events) {
+  return [...events].sort((a, b) => new Date(b.timestamp).getTime() - new Date(a.timestamp).getTime())[0] || null;
+}
 
-  const validCommands = ['propose', 'spec', 'design', 'task', 'check', 'apply', 'test', 'archive', 'explore'];
-  if (!validCommands.includes(command)) {
-    console.error(`错误: 无效的 command "${command}"，有效值: ${validCommands.join(', ')}`);
-    process.exit(1);
-  }
+function timestampMs(event) {
+  const value = Date.parse(event?.timestamp || '');
+  return Number.isFinite(value) ? value : 0;
+}
 
-  const dataDir = getDataDir(projectRoot);
-  const eventId = generateEventId();
-  const timestamp = nowISO();
+function stageAttemptKey(event) {
+  return [
+    event?.command || event?.stage || 'unknown',
+    event?.capability || '',
+  ].join('|');
+}
 
-  const event = {
-    event_id: eventId,
-    type: 'stage_start',
+function createReworkBucket(command, capability) {
+  return {
     command,
-    change: changeName || 'general',
-    agent_type: agentType,
-    project_root: projectRoot,
-    timestamp,
-    context: {},
-  };
-
-  appendEvent(dataDir, event.change, event);
-
-  // 输出 JSON，方便 AI Agent 解析 event_id
-  const output = {
-    event_id: eventId,
-    started_at: timestamp,
-    message: `SDD ${command} 阶段开始记录（change: ${event.change}）`,
+    capability: capability || null,
+    total_attempts: 0,
+    canonical_event_id: null,
+    successful_attempts: 0,
+    rework_attempts: 0,
+    completed_rework_attempts: 0,
+    superseded_open_stages: 0,
+    unresolved_open_stages: 0,
+    rework_duration_ms: 0,
   };
-  console.log(JSON.stringify(output, null, 2));
 }
 
-/**
- * log end: 记录阶段结束
- */
-function cmdEnd(args) {
-  const eventId = args['event-id'] || args.event_id;
-  const result = args.result;
-  const summary = args.summary || '';
-  const projectRoot = args.project || args['project-root'] || process.cwd();
+function summarizeStageExecutions(events) {
+  const stageEvents = events.filter(e => !e.orphan && (e.type === 'stage_start' || e.type === 'stage_end'));
+  const starts = stageEvents
+    .filter(e => e.type === 'stage_start')
+    .sort((a, b) => timestampMs(a) - timestampMs(b));
+  const ends = stageEvents
+    .filter(e => e.type === 'stage_end')
+    .sort((a, b) => timestampMs(a) - timestampMs(b));
+  const endsById = new Map();
+  for (const end of ends) {
+    if (!endsById.has(end.event_id)) endsById.set(end.event_id, []);
+    endsById.get(end.event_id).push(end);
+  }
 
-  if (!eventId) {
-    console.error('错误: 缺少 --event-id 参数');
-    console.error('用法: node skywalk-sdd/log.js end --event-id=evt_xxx --result=success --summary="..." --project=/path');
-    process.exit(1);
+  const attempts = starts.map(start => {
+    const end = latestByTimestamp(endsById.get(start.event_id) || []);
+    return {
+      key: stageAttemptKey(start),
+      command: start.command || start.stage || 'unknown',
+      capability: start.capability || null,
+      start,
+      end,
+      result: end?.result || null,
+      duration_ms: Number.isFinite(end?.duration_ms) ? end.duration_ms : 0,
+      canonical: false,
+      rework_reason: null,
+    };
+  });
+
+  const groups = new Map();
+  for (const attempt of attempts) {
+    if (!groups.has(attempt.key)) groups.set(attempt.key, []);
+    groups.get(attempt.key).push(attempt);
   }
-  if (!result) {
-    console.error('错误: 缺少 --result 参数（success/failure/partial）');
-    process.exit(1);
+
+  const canonicalAttempts = [];
+  const reworkAttempts = [];
+  const byStage = {};
+  let effectiveStageDurationMs = 0;
+  let reworkStageDurationMs = 0;
+  let completedReworkAttempts = 0;
+  let supersededOpenStages = 0;
+  let unresolvedOpenStages = 0;
+
+  for (const groupAttempts of groups.values()) {
+    const successfulAttempts = groupAttempts.filter(attempt => attempt.end && attempt.result === 'success');
+    const canonical = latestByTimestamp(successfulAttempts.map(attempt => attempt.end))
+      ? successfulAttempts.find(attempt => {
+        const latestEnd = latestByTimestamp(successfulAttempts.map(item => item.end));
+        return attempt.end === latestEnd;
+      })
+      : null;
+    if (canonical) {
+      canonical.canonical = true;
+      canonicalAttempts.push(canonical);
+      effectiveStageDurationMs += canonical.duration_ms;
+    }
+
+    for (const attempt of groupAttempts) {
+      const bucketKey = stageAttemptKey(attempt.start);
+      if (!byStage[bucketKey]) {
+        byStage[bucketKey] = createReworkBucket(attempt.command, attempt.capability);
+      }
+      const bucket = byStage[bucketKey];
+      bucket.total_attempts += 1;
+      if (attempt.result === 'success') bucket.successful_attempts += 1;
+      if (canonical) bucket.canonical_event_id = canonical.start.event_id;
+
+      if (attempt === canonical) continue;
+
+      if (canonical && timestampMs(attempt.start) <= timestampMs(canonical.end || canonical.start)) {
+        attempt.rework_reason = attempt.end ? 'completed_rework' : 'superseded_open';
+        reworkAttempts.push(attempt);
+        bucket.rework_attempts += 1;
+        if (attempt.end) {
+          completedReworkAttempts += 1;
+          bucket.completed_rework_attempts += 1;
+          bucket.rework_duration_ms += attempt.duration_ms;
+          reworkStageDurationMs += attempt.duration_ms;
+        } else {
+          supersededOpenStages += 1;
+          bucket.superseded_open_stages += 1;
+        }
+      } else if (!attempt.end) {
+        attempt.rework_reason = 'unresolved_open';
+        unresolvedOpenStages += 1;
+        bucket.unresolved_open_stages += 1;
+      }
+    }
   }
 
-  // 从事件文件中查找对应的 start 事件
-  const dataDir = getDataDir(projectRoot);
-  const startEvent = searchEventInDataDir(dataDir, eventId);
-  const timestamp = nowISO();
+  return {
+    attempts,
+    canonicalAttempts,
+    reworkAttempts,
+    summary: {
+      total_attempts: attempts.length,
+      canonical_attempts: canonicalAttempts.length,
+      total_rework_attempts: reworkAttempts.length,
+      completed_rework_attempts: completedReworkAttempts,
+      superseded_open_stages: supersededOpenStages,
+      unresolved_open_stages: unresolvedOpenStages,
+      effective_stage_duration_ms: effectiveStageDurationMs,
+      rework_stage_duration_ms: reworkStageDurationMs,
+      total_stage_duration_ms: effectiveStageDurationMs + reworkStageDurationMs,
+      by_stage: Object.values(byStage),
+    },
+  };
+}
 
-  const durationMs = startEvent
-    ? new Date(timestamp).getTime() - new Date(startEvent.timestamp).getTime()
+function getCanonicalAttempt(executionSummary, command, capability) {
+  const candidates = executionSummary.canonicalAttempts.filter(attempt => {
+    if (attempt.command !== command) return false;
+    if (capability && attempt.capability !== capability) return false;
+    return true;
+  });
+  return latestByTimestamp(candidates.map(attempt => attempt.end))
+    ? candidates.find(attempt => {
+      const latestEnd = latestByTimestamp(candidates.map(item => item.end));
+      return attempt.end === latestEnd;
+    })
     : null;
+}
 
-  const event = {
-    event_id: eventId,
-    type: 'stage_end',
-    command: startEvent?.command || 'unknown',
-    change: startEvent?.change || 'general',
-    agent_type: startEvent?.agent_type || 'unknown',
-    project_root: projectRoot,
-    timestamp,
-    duration_ms: durationMs,
-    result,
-    summary,
-    details: {},
-  };
+function hasOfficialSource(event) {
+  return !event?.source || ['opsx-command', 'manual', 'ci'].includes(event.source);
+}
 
-  appendEvent(dataDir, event.change, event);
+function getFormalStageRelatedEvents(events, attempt, predicate) {
+  const candidates = events
+    .filter(e => !e.orphan)
+    .filter(predicate)
+    .filter(e => {
+      if (attempt.capability && e.capability && e.capability !== attempt.capability) return false;
+      return true;
+    })
+    .sort((a, b) => timestampMs(a) - timestampMs(b));
+  if (!attempt || candidates.length === 0) return [];
+
+  const sessionId = attempt.start.session_id || attempt.end?.session_id;
+  if (sessionId) {
+    const sessionMatches = candidates.filter(e => e.session_id === sessionId);
+    const officialSessionMatches = sessionMatches.filter(hasOfficialSource);
+    if (officialSessionMatches.length > 0) return officialSessionMatches;
+    if (sessionMatches.length > 0) return sessionMatches;
+  }
 
-  const output = {
-    event_id: eventId,
-    duration_ms: durationMs,
-    recorded_at: timestamp,
-    message: `SDD ${event.command} 阶段结束（${result}，耗时 ${durationMs ? (durationMs / 1000).toFixed(1) + 's' : '未知'}）`,
+  const startMs = timestampMs(attempt.start);
+  const afterStart = candidates.filter(e => timestampMs(e) >= startMs);
+  const officialAfterStart = afterStart.filter(hasOfficialSource);
+  if (officialAfterStart.length > 0) return officialAfterStart;
+  if (afterStart.length > 0) return afterStart;
+
+  const endMs = timestampMs(attempt.end);
+  const beforeEnd = candidates.filter(e => timestampMs(e) <= endMs);
+  const officialBeforeEnd = beforeEnd.filter(hasOfficialSource);
+  if (officialBeforeEnd.length > 0) return [latestByTimestamp(officialBeforeEnd)];
+  if (beforeEnd.length > 0) return [latestByTimestamp(beforeEnd)];
+  return [];
+}
+
+function compactReworkSummary(summary) {
+  return {
+    total_attempts: summary.total_attempts,
+    canonical_attempts: summary.canonical_attempts,
+    total_rework_attempts: summary.total_rework_attempts,
+    completed_rework_attempts: summary.completed_rework_attempts,
+    superseded_open_stages: summary.superseded_open_stages,
+    unresolved_open_stages: summary.unresolved_open_stages,
+    effective_stage_duration_ms: summary.effective_stage_duration_ms,
+    rework_stage_duration_ms: summary.rework_stage_duration_ms,
+    total_stage_duration_ms: summary.total_stage_duration_ms,
+    by_stage: summary.by_stage,
   };
-  console.log(JSON.stringify(output, null, 2));
 }
 
-/**
- * 从事件文件中查找 start 事件（因为 CLI 无状态，需要从文件回溯）
- */
-function findStartEvent(eventId) {
-  // 尝试从当前目录的 skywalk-sdd 查找
+function readSuccessSignal(event, detailKeys) {
+  if (!event) return null;
+  if (event.result === 'success') return true;
+  if (event.result === 'failure') return false;
+  for (const key of detailKeys) {
+    const value = event.details?.[key];
+    if (typeof value?.success === 'boolean') return value.success;
+    if (typeof value?.passed === 'boolean') return value.passed;
+  }
+  return null;
+}
+
+function getCheckResults(event) {
+  const results = event?.details?.check_results;
+  if (!results) return null;
+  return {
+    total: Number.isFinite(results.total) ? results.total : null,
+    errors: Number.isFinite(results.errors) ? results.errors : 0,
+    warnings: Number.isFinite(results.warnings) ? results.warnings : 0,
+    suggestions: Number.isFinite(results.suggestions) ? results.suggestions : 0,
+    fixed_before_apply: Number.isFinite(results.fixed_before_apply) ? results.fixed_before_apply : null,
+    consistency_score: Number.isFinite(results.consistency_score) ? results.consistency_score : null,
+    categories: results.categories || {},
+  };
+}
+
+function getCheckEvents(events) {
+  return events.filter(e => {
+    return e.type === 'check_result'
+      || Boolean(e.details?.check_results)
+      || (e.command === 'check' && e.type === 'stage_end');
+  });
+}
+
+function getBuildResults(event) {
+  const results = event?.details?.build_results || event?.details?.build;
+  if (!results) return null;
+  return {
+    command: results.command || null,
+    success: typeof results.success === 'boolean'
+      ? results.success
+      : (event.result === 'success' ? true : (event.result === 'failure' ? false : null)),
+    duration_ms: Number.isFinite(results.duration_ms) ? results.duration_ms : null,
+    error_count: Number.isFinite(results.error_count) ? results.error_count : null,
+  };
+}
+
+function getBuildEvents(events) {
+  return events.filter(e => {
+    return e.type === 'build_result'
+      || Boolean(e.details?.build_results)
+      || Boolean(e.details?.build);
+  });
+}
+
+function getTestResults(event) {
+  const results = event?.details?.test_results || event?.details?.test;
+  if (!results) return null;
+  return {
+    command: results.command || null,
+    passed: Number.isFinite(results.passed) ? results.passed : 0,
+    failed: Number.isFinite(results.failed) ? results.failed : 0,
+    skipped: Number.isFinite(results.skipped) ? results.skipped : 0,
+    coverage: Number.isFinite(results.coverage) ? results.coverage : null,
+    duration_ms: Number.isFinite(results.duration_ms) ? results.duration_ms : null,
+  };
+}
+
+function getTestEvents(events) {
+  return events.filter(e => {
+    return e.type === 'test_result'
+      || Boolean(e.details?.test_results)
+      || Boolean(e.details?.test)
+      || (e.command === 'test' && e.type === 'stage_end');
+  });
+}
+
+function getTestPassRate(event) {
+  const results = getTestResults(event);
+  if (!results) return null;
+  const total = results.passed + results.failed + results.skipped;
+  if (total === 0) return null;
+  return results.passed / total;
+}
+
+function getTaskUpdateResult(event) {
+  if (!event || event.type !== 'task_update') return null;
+  const build = getBuildResults(event);
+  const test = getTestResults(event);
+  const buildOk = build?.success;
+  const testOk = test ? test.failed === 0 : null;
+  const resultOk = event.result === 'success'
+    ? true
+    : (event.result === 'failure' ? false : null);
+  const signals = [buildOk, testOk, resultOk].filter(value => value != null);
+  return {
+    task_id: event.task_id || null,
+    success: signals.length > 0 ? signals.every(Boolean) : null,
+    build,
+    test,
+  };
+}
+
+function computeAiFirstPassMetrics(events) {
+  const taskEvents = events
+    .filter(e => e.type === 'task_update' && e.task_id)
+    .sort((a, b) => new Date(a.timestamp).getTime() - new Date(b.timestamp).getTime());
+  const firstByTask = new Map();
+  for (const event of taskEvents) {
+    if (!firstByTask.has(event.task_id)) {
+      firstByTask.set(event.task_id, event);
+    }
+  }
+
+  const taskResults = Array.from(firstByTask.values())
+    .map(getTaskUpdateResult)
+    .filter(result => result?.success != null);
+  if (taskResults.length === 0) {
+    return {
+      e4_ai_code_first_pass_rate: null,
+      first_pass_tasks: 0,
+      measured_tasks: 0,
+      failed_tasks: [],
+    };
+  }
+
+  const passedTasks = taskResults.filter(result => result.success);
+  return {
+    e4_ai_code_first_pass_rate: roundMetric(passedTasks.length / taskResults.length),
+    first_pass_tasks: passedTasks.length,
+    measured_tasks: taskResults.length,
+    failed_tasks: taskResults.filter(result => !result.success).map(result => result.task_id).filter(Boolean),
+  };
+}
+
+function normalizeScenarioCoverageStatus(value) {
+  if (!value) return null;
+  const normalized = String(value).toLowerCase();
+  if (['covered', 'partial', 'uncovered'].includes(normalized)) {
+    return normalized;
+  }
+  return null;
+}
+
+function getSpecTestCoverage(event) {
+  const coverage = event?.details?.spec_test_coverage || event?.details?.scenario_coverage;
+  if (!coverage) return null;
+
+  const mappings = Array.isArray(coverage.mappings) ? coverage.mappings : [];
+  const normalizedMappings = mappings.map((mapping, index) => {
+    const status = normalizeScenarioCoverageStatus(mapping.status);
+    return {
+      scenario_id: mapping.scenario_id || mapping.id || `SCENARIO-${index + 1}`,
+      description: mapping.description || '',
+      test_ids: Array.isArray(mapping.test_ids) ? mapping.test_ids : [],
+      status,
+      notes: mapping.notes || '',
+    };
+  }).filter(mapping => mapping.status);
+
+  const mappedCounts = {
+    covered: normalizedMappings.filter(m => m.status === 'covered').length,
+    partial: normalizedMappings.filter(m => m.status === 'partial').length,
+    uncovered: normalizedMappings.filter(m => m.status === 'uncovered').length,
+  };
+  const mappedTotal = mappedCounts.covered + mappedCounts.partial + mappedCounts.uncovered;
+  const totalScenarios = Number.isFinite(coverage.total_scenarios)
+    ? coverage.total_scenarios
+    : mappedTotal;
+  const coveredScenarios = Number.isFinite(coverage.covered_scenarios)
+    ? coverage.covered_scenarios
+    : mappedCounts.covered;
+  const partialScenarios = Number.isFinite(coverage.partial_scenarios)
+    ? coverage.partial_scenarios
+    : mappedCounts.partial;
+  const uncoveredScenarios = Number.isFinite(coverage.uncovered_scenarios)
+    ? coverage.uncovered_scenarios
+    : mappedCounts.uncovered;
+  const computedRate = totalScenarios > 0
+    ? roundMetric((coveredScenarios + partialScenarios * 0.5) / totalScenarios)
+    : null;
+
+  return {
+    total_scenarios: totalScenarios,
+    covered_scenarios: coveredScenarios,
+    partial_scenarios: partialScenarios,
+    uncovered_scenarios: uncoveredScenarios,
+    coverage_rate: Number.isFinite(coverage.coverage_rate) ? coverage.coverage_rate : computedRate,
+    mappings: normalizedMappings,
+  };
+}
+
+function getSpecTestCoverageEvents(events) {
+  return events.filter(e => {
+    return e.type === 'coverage_result'
+      || Boolean(e.details?.spec_test_coverage)
+      || Boolean(e.details?.scenario_coverage);
+  });
+}
+
+function computeSpecTestCoverageMetrics(events) {
+  const coverageEvents = getSpecTestCoverageEvents(events);
+  const latestCoverageEvent = latestByTimestamp(coverageEvents);
+  const coverage = getSpecTestCoverage(latestCoverageEvent);
+  if (!coverage) {
+    return {
+      q4_spec_driven_test_coverage: null,
+      scenario_counts: { total: 0, covered: 0, partial: 0, uncovered: 0 },
+      latest_review_at: null,
+    };
+  }
+
+  return {
+    q4_spec_driven_test_coverage: coverage.coverage_rate,
+    scenario_counts: {
+      total: coverage.total_scenarios,
+      covered: coverage.covered_scenarios,
+      partial: coverage.partial_scenarios,
+      uncovered: coverage.uncovered_scenarios,
+    },
+    latest_review_at: latestCoverageEvent.timestamp || null,
+  };
+}
+
+function normalizeConformanceStatus(value) {
+  if (!value) return null;
+  const normalized = String(value).toLowerCase();
+  if (['matched', 'partial', 'missed'].includes(normalized)) {
+    return normalized;
+  }
+  return null;
+}
+
+function getConformanceReview(event) {
+  const review = event?.details?.conformance_review || event?.details?.conformance;
+  if (!review) return null;
+
+  const assertions = Array.isArray(review.assertions) ? review.assertions : [];
+  const normalizedAssertions = assertions.map((assertion, index) => {
+    const judgeStatus = normalizeConformanceStatus(assertion.judge_status);
+    const humanStatus = normalizeConformanceStatus(assertion.human_status);
+    const status = normalizeConformanceStatus(assertion.status) || humanStatus || judgeStatus;
+    return {
+      id: assertion.id || `ASSERT-${index + 1}`,
+      description: assertion.description || assertion.text || '',
+      status,
+      judge_status: judgeStatus,
+      human_status: humanStatus,
+      evidence: assertion.evidence || '',
+      files: Array.isArray(assertion.files) ? assertion.files : [],
+      notes: assertion.notes || '',
+    };
+  }).filter(assertion => assertion.status);
+
+  const matched = normalizedAssertions.filter(a => a.status === 'matched').length;
+  const partial = normalizedAssertions.filter(a => a.status === 'partial').length;
+  const missed = normalizedAssertions.filter(a => a.status === 'missed').length;
+  const total = matched + partial + missed;
+  const computedScore = total > 0 ? roundMetric((matched + partial * 0.5) / total) : null;
+
+  return {
+    total,
+    matched,
+    partial,
+    missed,
+    score: Number.isFinite(review.score) ? review.score : computedScore,
+    method: review.method || null,
+    reviewer: review.reviewer || null,
+    manual_confirmed: review.manual_confirmed === true || normalizedAssertions.some(a => a.human_status),
+    assertions: normalizedAssertions,
+  };
+}
+
+function getConformanceReviewEvents(events) {
+  return events.filter(e => {
+    return e.type === 'conformance_review'
+      || Boolean(e.details?.conformance_review)
+      || Boolean(e.details?.conformance);
+  });
+}
+
+function computeConformanceMetrics(events) {
+  const reviewEvents = getConformanceReviewEvents(events);
+  const latestReviewEvent = latestByTimestamp(reviewEvents);
+  const latestReview = getConformanceReview(latestReviewEvent);
+  if (!latestReview) {
+    return {
+      q1_spec_conformance_score: null,
+      conformance_counts: { total: 0, matched: 0, partial: 0, missed: 0 },
+      manual_confirmed: false,
+      latest_review_at: null,
+    };
+  }
+
+  return {
+    q1_spec_conformance_score: latestReview.score,
+    conformance_counts: {
+      total: latestReview.total,
+      matched: latestReview.matched,
+      partial: latestReview.partial,
+      missed: latestReview.missed,
+    },
+    manual_confirmed: latestReview.manual_confirmed,
+    latest_review_at: latestReviewEvent.timestamp || null,
+  };
+}
+
+function getAiAdoptionReview(event) {
+  const review = event?.details?.ai_adoption || event?.details?.ai_code_adoption;
+  if (!review) return null;
+
+  const retainedLines = Number.isFinite(review.retained_lines) ? review.retained_lines : null;
+  const rewrittenLines = Number.isFinite(review.rewritten_lines) ? review.rewritten_lines : null;
+  const deletedLines = Number.isFinite(review.deleted_lines) ? review.deleted_lines : null;
+  const denominator = [retainedLines, rewrittenLines, deletedLines]
+    .filter(value => value != null)
+    .reduce((sum, value) => sum + value, 0);
+  const computedRate = retainedLines != null && denominator > 0
+    ? roundMetric(retainedLines / denominator)
+    : null;
+  const adoptionRate = Number.isFinite(review.adoption_rate)
+    ? review.adoption_rate
+    : computedRate;
+  let adoptionLevel = review.adoption_level || null;
+  if (!adoptionLevel && adoptionRate != null) {
+    if (adoptionRate >= 0.95) adoptionLevel = 'full';
+    else if (adoptionRate >= 0.5) adoptionLevel = 'partial';
+    else adoptionLevel = 'rewritten';
+  }
+
+  return {
+    base_git_sha: review.base_git_sha || null,
+    ai_git_sha: review.ai_git_sha || null,
+    final_git_sha: review.final_git_sha || null,
+    review_status: review.review_status || event.status || null,
+    adoption_rate: adoptionRate,
+    adoption_level: adoptionLevel,
+    retained_lines: retainedLines,
+    rewritten_lines: rewrittenLines,
+    deleted_lines: deletedLines,
+    ai_diff: review.ai_diff || {},
+    final_diff: review.final_diff || {},
+    notes: review.notes || '',
+  };
+}
+
+function getAiAdoptionEvents(events) {
+  return events.filter(e => {
+    return e.type === 'ai_adoption_review'
+      || Boolean(e.details?.ai_adoption)
+      || Boolean(e.details?.ai_code_adoption);
+  });
+}
+
+function computeAiAdoptionMetrics(events) {
+  const adoptionEvents = getAiAdoptionEvents(events);
+  const finalEvents = adoptionEvents.filter(e => {
+    const review = getAiAdoptionReview(e);
+    return review?.review_status === 'final' || e.status === 'final';
+  });
+  const latestEvent = latestByTimestamp(finalEvents.length > 0 ? finalEvents : adoptionEvents);
+  const latestReview = getAiAdoptionReview(latestEvent);
+  if (!latestReview) {
+    return {
+      p2_ai_code_adoption_rate: null,
+      adoption_level: null,
+      adoption_counts: { retained_lines: null, rewritten_lines: null, deleted_lines: null },
+      latest_review_at: null,
+    };
+  }
+
+  return {
+    p2_ai_code_adoption_rate: latestReview.adoption_rate,
+    adoption_level: latestReview.adoption_level,
+    adoption_counts: {
+      retained_lines: latestReview.retained_lines,
+      rewritten_lines: latestReview.rewritten_lines,
+      deleted_lines: latestReview.deleted_lines,
+    },
+    latest_review_at: latestEvent.timestamp || null,
+  };
+}
+
+function getSurveyResult(event) {
+  const survey = event?.details?.survey_result || event?.details?.survey;
+  if (!survey) return null;
+  return {
+    nps: Number.isFinite(survey.nps) ? survey.nps : null,
+    cognitive_load: Number.isFinite(survey.cognitive_load) ? survey.cognitive_load : null,
+    spec_fatigue_index: Number.isFinite(survey.spec_fatigue_index) ? survey.spec_fatigue_index : null,
+    satisfaction: Number.isFinite(survey.satisfaction) ? survey.satisfaction : null,
+    respondent_role: survey.respondent_role || null,
+    collected_at: survey.collected_at || event.timestamp || null,
+    source: event.source || 'manual',
+    notes: survey.notes || '',
+  };
+}
+
+function getSurveyEvents(events) {
+  return events.filter(e => e.type === 'survey_result' || Boolean(e.details?.survey_result) || Boolean(e.details?.survey));
+}
+
+function getBaselineRecord(event) {
+  const baseline = event?.details?.baseline_record || event?.details?.baseline;
+  if (!baseline) return null;
+  return {
+    traditional_hours: Number.isFinite(baseline.traditional_hours) ? baseline.traditional_hours : null,
+    sdd_hours: Number.isFinite(baseline.sdd_hours) ? baseline.sdd_hours : null,
+    task_type: baseline.task_type || null,
+    baseline_source: baseline.baseline_source || event.source || 'manual',
+    collected_at: baseline.collected_at || event.timestamp || null,
+    notes: baseline.notes || '',
+  };
+}
+
+function getBaselineEvents(events) {
+  return events.filter(e => e.type === 'baseline_record' || Boolean(e.details?.baseline_record) || Boolean(e.details?.baseline));
+}
+
+function computeManualInsightMetrics(events) {
+  const surveyResults = getSurveyEvents(events).map(getSurveyResult).filter(Boolean);
+  const baselineRecords = getBaselineEvents(events).map(getBaselineRecord).filter(Boolean);
+  const latestSurveyEvent = latestByTimestamp(getSurveyEvents(events));
+  const latestBaselineEvent = latestByTimestamp(getBaselineEvents(events));
+  const latestSurvey = getSurveyResult(latestSurveyEvent);
+  const latestBaseline = getBaselineRecord(latestBaselineEvent);
+  const timeSavedRatio = latestBaseline?.traditional_hours > 0 && latestBaseline?.sdd_hours != null
+    ? roundMetric((latestBaseline.traditional_hours - latestBaseline.sdd_hours) / latestBaseline.traditional_hours)
+    : null;
+
+  return {
+    survey_count: surveyResults.length,
+    baseline_count: baselineRecords.length,
+    avg_nps: averageMetric(surveyResults, item => item.nps),
+    avg_cognitive_load: averageMetric(surveyResults, item => item.cognitive_load),
+    avg_spec_fatigue_index: averageMetric(surveyResults, item => item.spec_fatigue_index),
+    latest_survey: latestSurvey,
+    latest_baseline: latestBaseline,
+    baseline_time_saved_ratio: timeSavedRatio,
+  };
+}
+
+function runGit(projectRoot, args) {
+  try {
+    return execFileSync('git', args, {
+      cwd: projectRoot,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'pipe'],
+    }).trim();
+  } catch {
+    return null;
+  }
+}
+
+function classifyOpenSpecDoc(filePath) {
+  const normalized = filePath.replace(/\\/g, '/');
+  const fileName = normalized.split('/').pop();
+  if (fileName === 'proposal.md') return 'proposal';
+  if (fileName === 'spec.md') return 'spec';
+  if (fileName === 'design.md') return 'design';
+  if (fileName === 'tasks.md' || fileName === 'task.md') return 'tasks';
+  return null;
+}
+
+function createDocFileMetrics() {
+  return {
+    proposal: { commit_count: 0, added_lines: 0, deleted_lines: 0 },
+    spec: { commit_count: 0, added_lines: 0, deleted_lines: 0 },
+    design: { commit_count: 0, added_lines: 0, deleted_lines: 0 },
+    tasks: { commit_count: 0, added_lines: 0, deleted_lines: 0 },
+  };
+}
+
+function computeGitDocumentMetrics(projectRoot, changeName) {
+  const warnings = [];
+  if (!projectRoot || !changeName) {
+    return {
+      git_available: false,
+      spec_iteration_count: null,
+      document_commit_count: null,
+      total_added_lines: null,
+      total_deleted_lines: null,
+      files: createDocFileMetrics(),
+      diff_trend: [],
+      warnings: ['缺少 projectRoot 或 changeName，无法统计 Git 文档迭代'],
+    };
+  }
+
+  const isRepo = runGit(projectRoot, ['rev-parse', '--is-inside-work-tree']);
+  if (isRepo !== 'true') {
+    return {
+      git_available: false,
+      spec_iteration_count: null,
+      document_commit_count: null,
+      total_added_lines: null,
+      total_deleted_lines: null,
+      files: createDocFileMetrics(),
+      diff_trend: [],
+      warnings: ['当前项目不是 Git 仓库，无法统计文档迭代'],
+    };
+  }
+
+  const changePath = `openspec/changes/${changeName}`;
+  const output = runGit(projectRoot, [
+    'log',
+    '--numstat',
+    '--format=commit:%H%x09%cI',
+    '--',
+    changePath,
+  ]);
+  if (!output) {
+    return {
+      git_available: true,
+      spec_iteration_count: null,
+      document_commit_count: null,
+      total_added_lines: 0,
+      total_deleted_lines: 0,
+      files: createDocFileMetrics(),
+      diff_trend: [],
+      warnings: [`未找到 ${changePath} 的 Git 提交历史`],
+    };
+  }
+
+  const fileMetrics = createDocFileMetrics();
+  const fileCommits = {
+    proposal: new Set(),
+    spec: new Set(),
+    design: new Set(),
+    tasks: new Set(),
+  };
+  const docCommits = new Set();
+  const diffTrend = [];
+  let currentCommit = null;
+
+  for (const line of output.split(/\r?\n/)) {
+    if (!line.trim()) continue;
+    if (line.startsWith('commit:')) {
+      const [, hash, timestamp] = line.match(/^commit:([^\t]+)\t(.+)$/) || [];
+      currentCommit = {
+        commit: hash || line.slice('commit:'.length),
+        timestamp: timestamp || null,
+        added_lines: 0,
+        deleted_lines: 0,
+        files: [],
+      };
+      diffTrend.push(currentCommit);
+      continue;
+    }
+
+    if (!currentCommit) continue;
+    const [addedRaw, deletedRaw, filePath] = line.split('\t');
+    const docType = filePath ? classifyOpenSpecDoc(filePath) : null;
+    if (!docType) continue;
+
+    const added = addedRaw === '-' ? 0 : Number(addedRaw) || 0;
+    const deleted = deletedRaw === '-' ? 0 : Number(deletedRaw) || 0;
+    currentCommit.added_lines += added;
+    currentCommit.deleted_lines += deleted;
+    currentCommit.files.push({ path: filePath, doc_type: docType, added_lines: added, deleted_lines: deleted });
+
+    fileMetrics[docType].added_lines += added;
+    fileMetrics[docType].deleted_lines += deleted;
+    fileCommits[docType].add(currentCommit.commit);
+    docCommits.add(currentCommit.commit);
+  }
+
+  const filteredTrend = diffTrend.filter(item => item.files.length > 0);
+  for (const [docType, commits] of Object.entries(fileCommits)) {
+    fileMetrics[docType].commit_count = commits.size;
+  }
+
+  if (docCommits.size === 0) {
+    warnings.push(`未找到 ${changePath} 下 proposal/spec/design/tasks 文档的提交历史`);
+  }
+
+  return {
+    git_available: true,
+    spec_iteration_count: docCommits.size > 0 ? docCommits.size : null,
+    document_commit_count: docCommits.size > 0 ? docCommits.size : null,
+    total_added_lines: filteredTrend.reduce((sum, item) => sum + item.added_lines, 0),
+    total_deleted_lines: filteredTrend.reduce((sum, item) => sum + item.deleted_lines, 0),
+    files: fileMetrics,
+    diff_trend: filteredTrend,
+    warnings,
+  };
+}
+
+function computeSinglePdfMvpMetrics(events, options = {}) {
+  const scopedEvents = events
+    .filter(e => !e.orphan)
+    .filter(e => !options.change || e.change === options.change)
+    .filter(e => !options.capability || e.capability === options.capability);
+  const executionSummary = summarizeStageExecutions(scopedEvents);
+  const starts = executionSummary.canonicalAttempts.map(attempt => attempt.start);
+  const ends = executionSummary.canonicalAttempts.map(attempt => attempt.end).filter(Boolean);
+
+  const proposeStart = firstByTimestamp(starts.filter(e => e.command === 'propose'));
+  const archiveEnd = latestByTimestamp(ends.filter(e => e.command === 'archive'));
+  const leadTime = proposeStart && archiveEnd
+    ? new Date(archiveEnd.timestamp).getTime() - new Date(proposeStart.timestamp).getTime()
+    : null;
+
+  const totalStageDuration = executionSummary.summary.effective_stage_duration_ms;
+  const codingDuration = sumDurations(ends, ['apply']);
+  const specDuration = sumDurations(ends, ['propose', 'spec', 'design', 'task']);
+  const reworkCodingDuration = sumAttemptDurations(executionSummary.reworkAttempts, ['apply']);
+  const reworkSpecDuration = sumAttemptDurations(executionSummary.reworkAttempts, ['propose', 'spec', 'design', 'task']);
+
+  const formalApplyAttempt = getCanonicalAttempt(executionSummary, 'apply', options.capability);
+  const formalApplyEvents = formalApplyAttempt
+    ? getFormalStageRelatedEvents(scopedEvents, formalApplyAttempt, e => e.command === 'apply' || e.stage === 'apply')
+    : [];
+  const buildEvents = formalApplyAttempt
+    ? getFormalStageRelatedEvents(scopedEvents, formalApplyAttempt, e => getBuildEvents([e]).length > 0)
+    : getBuildEvents(scopedEvents);
+  const firstBuild = firstByTimestamp(buildEvents);
+  const firstBuildSuccess = getBuildResults(firstBuild)?.success ?? readSuccessSignal(firstBuild, ['build_results', 'build']);
+
+  const checkEvents = getCheckEvents(scopedEvents);
+  const latestCheckWithScore = latestByTimestamp(checkEvents.filter(e => {
+    return getCheckResults(e)?.consistency_score != null;
+  }));
+  const latestCheckResults = getCheckResults(latestCheckWithScore);
+
+  const stageSpecIterationCount = starts.filter(e => {
+    return ['propose', 'spec', 'design', 'task'].includes(e.command);
+  }).length;
+  const gitDocumentMetrics = options.projectRoot && options.change
+    ? computeGitDocumentMetrics(options.projectRoot, options.change)
+    : null;
+  const specIterationCount = gitDocumentMetrics
+    ? gitDocumentMetrics.spec_iteration_count
+    : stageSpecIterationCount;
+
+  const firstApply = firstByTimestamp(starts.filter(e => e.command === 'apply'));
+  const qualityGateBeforeApply = firstApply
+    ? checkEvents.some(e => new Date(e.timestamp).getTime() <= new Date(firstApply.timestamp).getTime())
+    : null;
+  const latestCheckWithFixRate = latestByTimestamp(checkEvents.filter(e => {
+    const results = getCheckResults(e);
+    return results?.total > 0 && results.fixed_before_apply != null;
+  }));
+  const fixRateResults = getCheckResults(latestCheckWithFixRate);
+  const qualityGateRate = fixRateResults
+    ? roundMetric(fixRateResults.fixed_before_apply / fixRateResults.total)
+    : (qualityGateBeforeApply == null ? null : (qualityGateBeforeApply ? 1 : 0));
+  const conformanceMetrics = computeConformanceMetrics(scopedEvents);
+  const aiAdoptionMetrics = computeAiAdoptionMetrics(formalApplyEvents.length > 0 ? formalApplyEvents : scopedEvents);
+  const aiFirstPassMetrics = computeAiFirstPassMetrics(formalApplyEvents.length > 0 ? formalApplyEvents : scopedEvents);
+  const specTestCoverageMetrics = computeSpecTestCoverageMetrics(scopedEvents);
+
+  return {
+    efficiency: {
+      e1_lead_time_ms: leadTime,
+      e2_coding_time_ratio: totalStageDuration > 0 ? roundMetric(codingDuration / totalStageDuration) : null,
+      e3_spec_time_ratio: totalStageDuration > 0 ? roundMetric(specDuration / totalStageDuration) : null,
+      e4_ai_code_first_pass_rate: aiFirstPassMetrics.e4_ai_code_first_pass_rate,
+      effective_stage_duration_ms: executionSummary.summary.effective_stage_duration_ms,
+      rework_stage_duration_ms: executionSummary.summary.rework_stage_duration_ms,
+      total_stage_duration_ms: executionSummary.summary.total_stage_duration_ms,
+      e2_coding_time_ratio_including_rework: executionSummary.summary.total_stage_duration_ms > 0
+        ? roundMetric((codingDuration + reworkCodingDuration) / executionSummary.summary.total_stage_duration_ms)
+        : null,
+      e3_spec_time_ratio_including_rework: executionSummary.summary.total_stage_duration_ms > 0
+        ? roundMetric((specDuration + reworkSpecDuration) / executionSummary.summary.total_stage_duration_ms)
+        : null,
+    },
+    quality: {
+      q1_spec_conformance_score: conformanceMetrics.q1_spec_conformance_score,
+      q3_build_first_pass_rate: firstBuildSuccess == null ? null : (firstBuildSuccess ? 1 : 0),
+      q4_spec_driven_test_coverage: specTestCoverageMetrics.q4_spec_driven_test_coverage,
+      q5_cross_doc_consistency_score: latestCheckResults?.consistency_score ?? null,
+      conformance_counts: conformanceMetrics.conformance_counts,
+      conformance_manual_confirmed: conformanceMetrics.manual_confirmed,
+      spec_test_scenario_counts: specTestCoverageMetrics.scenario_counts,
+    },
+    process: {
+      p1_spec_iteration_count: specIterationCount,
+      p2_ai_code_adoption_rate: aiAdoptionMetrics.p2_ai_code_adoption_rate,
+      p2_ai_code_adoption_level: aiAdoptionMetrics.adoption_level,
+      ai_adoption_counts: aiAdoptionMetrics.adoption_counts,
+      p4_quality_gate_enforcement_rate: qualityGateRate,
+      git_document_metrics: gitDocumentMetrics,
+      rework_summary: compactReworkSummary(executionSummary.summary),
+    },
+    manual_insights: computeManualInsightMetrics(scopedEvents),
+    telemetry_health: computeTelemetryHealthMetrics(scopedEvents),
+  };
+}
+
+function averageMetric(items, selector) {
+  const values = items.map(selector).filter(v => v != null && !Number.isNaN(v));
+  if (values.length === 0) return null;
+  return roundMetric(values.reduce((sum, v) => sum + v, 0) / values.length);
+}
+
+function sumMetric(items, selector) {
+  const values = items.map(selector).filter(v => v != null && !Number.isNaN(v));
+  if (values.length === 0) return null;
+  return values.reduce((sum, value) => sum + value, 0);
+}
+
+function computeCapabilityMetrics(capabilityName, events, options = {}) {
+  return computeSinglePdfMvpMetrics(events, {
+    change: options.change,
+    capability: capabilityName,
+    projectRoot: options.projectRoot,
+  });
+}
+
+function computeTelemetryHealthMetrics(events, options = {}) {
+  const report = computeDoctorReport(events, options);
+  return {
+    telemetry_health_score: report.telemetry_health_score,
+    matched_stage_rate: report.matched_stage_rate,
+    open_stages: report.open_stages,
+    superseded_open_stages: report.superseded_open_stages,
+    orphan_events: report.orphan_events,
+    unknown_command_events: report.unknown_command_events,
+    rework_attempts: report.rework_attempts,
+    warnings: report.warnings,
+  };
+}
+
+function computePdfMvpMetrics(events, options = {}) {
+  if (options.level === 'capability' || options.capability) {
+    return computeCapabilityMetrics(options.capability, events, options);
+  }
+
+  if (options.level === 'change' || options.change) {
+    return computeSinglePdfMvpMetrics(events, {
+      change: options.change,
+      projectRoot: options.projectRoot,
+    });
+  }
+
+  const changeNames = [...new Set(events.map(e => e.change).filter(Boolean))];
+  const changeMetrics = changeNames
+    .map(change => computeSinglePdfMvpMetrics(events, {
+      change,
+      projectRoot: options.projectRoot,
+    }))
+    .filter(Boolean);
+
+  return {
+    efficiency: {
+      e1_lead_time_ms: averageMetric(changeMetrics, m => m.efficiency.e1_lead_time_ms),
+      e2_coding_time_ratio: averageMetric(changeMetrics, m => m.efficiency.e2_coding_time_ratio),
+      e3_spec_time_ratio: averageMetric(changeMetrics, m => m.efficiency.e3_spec_time_ratio),
+      e4_ai_code_first_pass_rate: averageMetric(changeMetrics, m => m.efficiency.e4_ai_code_first_pass_rate),
+    },
+    quality: {
+      q1_spec_conformance_score: averageMetric(changeMetrics, m => m.quality.q1_spec_conformance_score),
+      q3_build_first_pass_rate: averageMetric(changeMetrics, m => m.quality.q3_build_first_pass_rate),
+      q4_spec_driven_test_coverage: averageMetric(changeMetrics, m => m.quality.q4_spec_driven_test_coverage),
+      q5_cross_doc_consistency_score: averageMetric(changeMetrics, m => m.quality.q5_cross_doc_consistency_score),
+    },
+    process: {
+      p1_spec_iteration_count: sumMetric(changeMetrics, m => m.process.p1_spec_iteration_count),
+      p2_ai_code_adoption_rate: averageMetric(changeMetrics, m => m.process.p2_ai_code_adoption_rate),
+      p4_quality_gate_enforcement_rate: averageMetric(changeMetrics, m => m.process.p4_quality_gate_enforcement_rate),
+    },
+    manual_insights: computeManualInsightMetrics(events.filter(e => !e.orphan)),
+    telemetry_health: computeTelemetryHealthMetrics(events),
+  };
+}
+
+function renderPdfMvpMarkdown(metrics) {
+  return [
+    '# SDD PDF MVP Metrics',
+    '',
+    '## Efficiency',
+    `- E1 Lead Time: ${metrics.efficiency.e1_lead_time_ms ?? 'null'} ms`,
+    `- E2 Coding Time Ratio: ${metrics.efficiency.e2_coding_time_ratio ?? 'null'}`,
+    `- E3 Spec Time Ratio: ${metrics.efficiency.e3_spec_time_ratio ?? 'null'}`,
+    `- E4 AI Code First Pass Rate: ${metrics.efficiency.e4_ai_code_first_pass_rate ?? 'null'}`,
+    `- Effective Stage Duration: ${metrics.efficiency.effective_stage_duration_ms ?? 'null'} ms`,
+    `- Rework Stage Duration: ${metrics.efficiency.rework_stage_duration_ms ?? 'null'} ms`,
+    '',
+    '## Quality',
+    `- Q1 Spec Conformance Score: ${metrics.quality.q1_spec_conformance_score ?? 'null'}`,
+    `- Q3 Build First Pass Rate: ${metrics.quality.q3_build_first_pass_rate ?? 'null'}`,
+    `- Q4 Spec-driven Test Coverage: ${metrics.quality.q4_spec_driven_test_coverage ?? 'null'}`,
+    `- Q5 Cross Doc Consistency Score: ${metrics.quality.q5_cross_doc_consistency_score ?? 'null'}`,
+    '',
+    '## Process',
+    `- P1 Spec Iteration Count: ${metrics.process.p1_spec_iteration_count ?? 'null'}`,
+    `- P2 AI Code Adoption Rate: ${metrics.process.p2_ai_code_adoption_rate ?? 'null'}`,
+    `- P4 Quality Gate Enforcement Rate: ${metrics.process.p4_quality_gate_enforcement_rate ?? 'null'}`,
+    `- Rework Attempts: ${metrics.process.rework_summary?.total_rework_attempts ?? 'null'}`,
+    `- Superseded Open Stages: ${metrics.process.rework_summary?.superseded_open_stages ?? 'null'}`,
+    '',
+    '## Manual Insights',
+    `- Avg NPS: ${metrics.manual_insights?.avg_nps ?? 'null'}`,
+    `- Avg Cognitive Load: ${metrics.manual_insights?.avg_cognitive_load ?? 'null'}`,
+    `- Avg Spec Fatigue Index: ${metrics.manual_insights?.avg_spec_fatigue_index ?? 'null'}`,
+    `- Baseline Time Saved Ratio: ${metrics.manual_insights?.baseline_time_saved_ratio ?? 'null'}`,
+    '',
+    '## Telemetry Health',
+    `- Health Score: ${metrics.telemetry_health.telemetry_health_score ?? 'null'}`,
+    `- Matched Stage Rate: ${metrics.telemetry_health.matched_stage_rate ?? 'null'}`,
+    `- Open Stages: ${metrics.telemetry_health.open_stages ?? 'null'}`,
+    `- Superseded Open Stages: ${metrics.telemetry_health.superseded_open_stages ?? 'null'}`,
+    `- Orphan Events: ${metrics.telemetry_health.orphan_events ?? 'null'}`,
+  ].join('\n');
+}
+
+function formatMsToSeconds(ms) {
+  if (ms == null) return 'null';
+  return `${(ms / 1000).toFixed(2)} s`;
+}
+
+function formatRatioToPercent(ratio) {
+  if (ratio == null) return 'null';
+  return `${(ratio * 100).toFixed(1)}%`;
+}
+
+function renderExecutiveReportMarkdown(report) {
+  const metrics = report.metrics;
+  const health = report.doctor;
+  const archive = report.archive_result || null;
+  const taskCompletion = archive?.task_completion || null;
+  return [
+    `# SDD 效果度量报告${report.change ? ` - ${report.change}` : ''}`,
+    '',
+    `- 生成时间：${report.generated_at}`,
+    `- 项目路径：${report.project_root}`,
+    `- 统计范围：${report.change ? `change/${report.change}` : 'project'}`,
+    '',
+    '## 执行摘要',
+    `- Telemetry 健康分：${formatRatioToPercent(health.telemetry_health_score)}（0-100%，反映遥测数据的完整性，扣分项包括未闭环阶段、孤儿事件等）`,
+    `- 阶段闭环率：${formatRatioToPercent(health.matched_stage_rate)}（已配对 start/end 的阶段占有效阶段总数的比例）`,
+    `- 严重问题数：${health.severe_issues?.length || 0}（存在未闭环阶段、孤儿事件或未知命令等阻断级问题的数量）`,
+    '',
+    '## 效率指标',
+    `- E1 需求到归档总时长：${formatMsToSeconds(metrics.efficiency?.e1_lead_time_ms)}`,
+    `- E2 编码时间占比：${formatRatioToPercent(metrics.efficiency?.e2_coding_time_ratio)}`,
+    `- E3 规约时间占比：${formatRatioToPercent(metrics.efficiency?.e3_spec_time_ratio)}`,
+    `- E4 AI 一次成码率：${formatRatioToPercent(metrics.efficiency?.e4_ai_code_first_pass_rate)}`,
+    `- 有效阶段总耗时：${formatMsToSeconds(metrics.efficiency?.effective_stage_duration_ms)}`,
+    `- 返工阶段总耗时：${formatMsToSeconds(metrics.efficiency?.rework_stage_duration_ms)}`,
+    '',
+    '## 质量指标',
+    `- Q1 规约符合度：${metrics.quality?.q1_spec_conformance_score ?? 'null'}`,
+    `- Q3 构建一次通过率：${formatRatioToPercent(metrics.quality?.q3_build_first_pass_rate)}`,
+    `- Q4 规约驱动测试覆盖率：${formatRatioToPercent(metrics.quality?.q4_spec_driven_test_coverage)}`,
+    `- Q5 跨文档一致性得分：${metrics.quality?.q5_cross_doc_consistency_score ?? 'null'}`,
+    '',
+    '## 过程指标',
+    `- P1 文档迭代次数：${metrics.process?.p1_spec_iteration_count ?? 'null'}`,
+    `- P2 AI 代码保留率：${formatRatioToPercent(metrics.process?.p2_ai_code_adoption_rate)}`,
+    `- P4 质量门前置率：${formatRatioToPercent(metrics.process?.p4_quality_gate_enforcement_rate)}`,
+    `- 返工次数：${metrics.process?.rework_summary?.total_rework_attempts ?? 'null'}`,
+    `- 被后续成功执行覆盖的未闭环阶段数：${metrics.process?.rework_summary?.superseded_open_stages ?? 'null'}`,
+    '',
+    '## 归档结果',
+    `- 归档原因：${archive?.reason || 'null'}`,
+    `- 归档方式：${archive?.method || 'null'}`,
+    `- 归档目录：${archive?.archive_path || 'null'}`,
+    `- 归档清单：${archive?.manifest_path || 'null'}`,
+    `- 最终报告：${archive?.report_path || 'null'}`,
+    `- 已完成任务项：${taskCompletion?.completed ?? 'null'}`,
+    `- 未勾选任务项：${taskCompletion?.incomplete ?? 'null'}`,
+    `- 任务项总数：${taskCompletion?.total ?? 'null'}`,
+    '',
+    '## 说明',
+    '- `null` 表示当前还没有采集到对应事件或该指标暂不适用。',
+    '- Q1 规约符合度与人工反馈类指标属于评审信号，默认不作为强阻断门禁。',
+  ].join('\n');
+}
+
+function buildReport(projectRoot, events, options = {}) {
+  const archiveEvent = latestByTimestamp(events.filter(e => {
+    return e.command === 'archive' && e.type === 'stage_end' && !e.orphan;
+  }));
+  return {
+    generated_at: nowISO(),
+    project_root: projectRoot,
+    change: options.change || null,
+    level: options.level || (options.change ? 'change' : 'project'),
+    metrics: computePdfMvpMetrics(events, {
+      level: options.level || (options.change ? 'change' : 'project'),
+      change: options.change,
+      capability: options.capability,
+      projectRoot,
+    }),
+    doctor: computeDoctorReport(events, { change: options.change }),
+    archive_result: archiveEvent?.details?.archive_result || null,
+  };
+}
+
+function filterEventsByDate(events, dateFrom, dateTo) {
+  if (!dateFrom && !dateTo) return events;
+  return events.filter(e => {
+    const d = e.timestamp?.slice(0, 10);
+    if (!d) return false;
+    if (dateFrom && d < dateFrom) return false;
+    if (dateTo && d > dateTo) return false;
+    return true;
+  });
+}
+
+function computeDoctorReport(events, options = {}) {
+  const scopedEvents = options.change
+    ? events.filter(e => e.change === options.change)
+    : events;
+  const executionSummary = summarizeStageExecutions(scopedEvents);
+  const stageEvents = scopedEvents.filter(e => e.type === 'stage_start' || e.type === 'stage_end');
+  const starts = stageEvents.filter(e => e.type === 'stage_start');
+  const ends = stageEvents.filter(e => e.type === 'stage_end');
+  const startsById = new Map(starts.map(e => [e.event_id, e]));
+  const endsById = new Map();
+  for (const end of ends) {
+    if (!endsById.has(end.event_id)) endsById.set(end.event_id, []);
+    endsById.get(end.event_id).push(end);
+  }
+
+  const matchedStarts = starts.filter(e => endsById.has(e.event_id));
+  const supersededOpenIds = new Set(executionSummary.reworkAttempts
+    .filter(attempt => attempt.rework_reason === 'superseded_open')
+    .map(attempt => attempt.start.event_id));
+  const supersededOpenStages = starts.filter(e => supersededOpenIds.has(e.event_id));
+  const openStages = starts.filter(e => !endsById.has(e.event_id) && !supersededOpenIds.has(e.event_id));
+  const orphanEnds = ends.filter(e => e.orphan || !startsById.has(e.event_id));
+  const effectiveStartCount = starts.length - supersededOpenStages.length;
+  const matchedStageRate = effectiveStartCount === 0 ? 1 : matchedStarts.length / effectiveStartCount;
+
+  const unknownCommandEvents = stageEvents.filter(e => !e.command || e.command === 'unknown');
+  const unknownAgentEvents = stageEvents.filter(e => !e.agent_type || e.agent_type === 'unknown');
+  const nullDurationEnds = ends.filter(e => !e.orphan && e.duration_ms == null);
+  const outdatedSchemaEvents = scopedEvents.filter(e => !e.schema_version || e.schema_version < SCHEMA_VERSION);
+  const invalidStageEvents = stageEvents.filter(e => {
+    const stage = e.stage || e.command;
+    return !stage || !STAGE_ORDER.includes(stage);
+  });
+  const missingChangeEvents = stageEvents.filter(e => !e.change || e.change === 'general');
+  const missingCapabilityEvents = stageEvents.filter(e => !e.capability);
+
+  const warnings = [];
+  if (openStages.length) warnings.push(`${openStages.length} stage(s) have start events without matching end events`);
+  if (supersededOpenStages.length) warnings.push(`${supersededOpenStages.length} open stage(s) were superseded by later successful runs and counted as rework`);
+  if (orphanEnds.length) warnings.push(`${orphanEnds.length} end event(s) have no matching start event`);
+  if (unknownCommandEvents.length) warnings.push(`${unknownCommandEvents.length} event(s) have unknown command`);
+  if (unknownAgentEvents.length) warnings.push(`${unknownAgentEvents.length} event(s) have unknown agent_type`);
+  if (nullDurationEnds.length) warnings.push(`${nullDurationEnds.length} end event(s) have null duration_ms`);
+  if (outdatedSchemaEvents.length) warnings.push(`${outdatedSchemaEvents.length} event(s) use missing or outdated schema_version`);
+  if (invalidStageEvents.length) warnings.push(`${invalidStageEvents.length} event(s) use invalid stage/command names`);
+  if (missingChangeEvents.length) warnings.push(`${missingChangeEvents.length} event(s) have missing or general change`);
+  if (missingCapabilityEvents.length) warnings.push(`${missingCapabilityEvents.length} event(s) are missing capability`);
+
+  const severeIssues = [];
+  if (openStages.length) severeIssues.push('open_stages');
+  if (orphanEnds.length) severeIssues.push('orphan_events');
+  if (unknownCommandEvents.length) severeIssues.push('unknown_command_events');
+  if (invalidStageEvents.length) severeIssues.push('invalid_stage_events');
+
+  const penalty =
+    openStages.length * 0.18 +
+    orphanEnds.length * 0.18 +
+    unknownCommandEvents.length * 0.12 +
+    invalidStageEvents.length * 0.12 +
+    nullDurationEnds.length * 0.08 +
+    outdatedSchemaEvents.length * 0.06 +
+    missingChangeEvents.length * 0.04 +
+    missingCapabilityEvents.length * 0.01;
+  const denominator = Math.max(stageEvents.length, 1);
+  const telemetryHealthScore = Math.max(0, Math.round((1 - penalty / denominator) * 100) / 100);
+
+  return {
+    telemetry_health_score: telemetryHealthScore,
+    matched_stage_rate: Math.round(matchedStageRate * 100) / 100,
+    total_events: scopedEvents.length,
+    stage_events: stageEvents.length,
+    start_events: starts.length,
+    end_events: ends.length,
+    matched_stages: matchedStarts.length,
+    open_stages: openStages.length,
+    superseded_open_stages: supersededOpenStages.length,
+    orphan_events: orphanEnds.length,
+    unknown_command_events: unknownCommandEvents.length,
+    unknown_agent_events: unknownAgentEvents.length,
+    null_duration_stages: nullDurationEnds.length,
+    outdated_schema_events: outdatedSchemaEvents.length,
+    invalid_stage_events: invalidStageEvents.length,
+    missing_change_events: missingChangeEvents.length,
+    missing_capability_events: missingCapabilityEvents.length,
+    rework_attempts: executionSummary.summary.total_rework_attempts,
+    completed_rework_attempts: executionSummary.summary.completed_rework_attempts,
+    rework_stage_duration_ms: executionSummary.summary.rework_stage_duration_ms,
+    rework_summary: compactReworkSummary(executionSummary.summary),
+    severe_issues: severeIssues,
+    warnings,
+  };
+}
+
+// ── CLI 参数解析 ──────────────────────────────────────
+
+/** 解析 --key=value 格式的参数 */
+function parseArgs(argv) {
+  const args = {};
+  for (const arg of argv) {
+    const match = arg.match(/^--([a-zA-Z_-]+)=(.*)$/);
+    if (match) {
+      args[match[1]] = match[2];
+    } else if (arg.match(/^--([a-zA-Z_-]+)$/)) {
+      args[arg.slice(2)] = true;
+    }
+  }
+  return args;
+}
+
+// ── CLI 命令实现 ─────────────────────────────────────
+
+/**
+ * log start: 记录阶段开始
+ */
+function cmdStart(args) {
+  const command = args.command;
+  const projectRoot = normalizeProjectRoot(args.project || args['project-root'] || process.cwd());
+  const changeName = args.change || args['change-name'] || '';
+  const agentType = inferAgentType(args);
+  const source = args.source || 'opsx-command';
+  const capability = args.capability || args['capability-name'];
+  const taskId = args['task-id'] || args.task_id;
+  const sessionId = args['session-id'] || args.session_id;
+  const gitSha = args['git-sha'] || args.git_sha;
+
+  if (!command) {
+    console.error('错误: 缺少 --command 参数');
+    console.error('用法: node skywalk-sdd/log.js start --command=propose --project=/path');
+    process.exit(1);
+  }
+
+  const validCommands = ['propose', 'spec', 'design', 'task', 'check', 'apply', 'test', 'archive', 'explore'];
+  if (!validCommands.includes(command)) {
+    console.error(`错误: 无效的 command "${command}"，有效值: ${validCommands.join(', ')}`);
+    process.exit(1);
+  }
+
+  const dataDir = getDataDir(projectRoot);
+  const eventId = generateEventId();
+  const timestamp = nowISO();
+  let context;
+  try {
+    context = parseJsonOption(args, 'context-json', 'context-file', projectRoot, {});
+  } catch (err) {
+    fail(`context JSON 解析失败: ${err.message}`);
+  }
+
+  const event = cleanOptionalFields({
+    schema_version: SCHEMA_VERSION,
+    event_id: eventId,
+    type: 'stage_start',
+    source,
+    command,
+    stage: command,
+    change: changeName || 'general',
+    capability,
+    task_id: taskId,
+    agent_type: agentType,
+    project_root: projectRoot,
+    session_id: sessionId,
+    git_sha: gitSha,
+    timestamp,
+    context,
+  });
+
+  appendEvent(dataDir, event.change, event);
+  writeActiveStage(projectRoot, event);
+
+  // 输出 JSON，方便 AI Agent 解析 event_id
+  const output = {
+    event_id: eventId,
+    started_at: timestamp,
+    message: `SDD ${command} 阶段开始记录（change: ${event.change}）`,
+  };
+  console.log(JSON.stringify(output, null, 2));
+}
+
+/**
+ * log end: 记录阶段结束
+ */
+function cmdEnd(args, options = {}) {
+  let eventId = args['event-id'] || args.event_id;
+  const result = args.result;
+  const summary = args.summary || '';
+  const projectRoot = normalizeProjectRoot(args.project || args['project-root'] || process.cwd());
+  let reportOutput = args['report-output'] || args.report_output || (args['generate-report'] ? path.join('skywalk-sdd', 'reports', `${safeChangeName(args.change || args['change-name'] || 'general')}-report.md`) : '');
+
+  if (!result) {
+    console.error('错误: 缺少 --result 参数（success/failure/partial）');
+    process.exit(1);
+  }
+
+  const dataDir = getDataDir(projectRoot);
+  const activeCriteria = {
+    session_id: args['session-id'] || args.session_id,
+    change: args.change || args['change-name'],
+    command: args.command,
+    agent_type: args.agent || args['agent-type'],
+  };
+  const startEvent = eventId
+    ? searchEventInDataDir(dataDir, eventId)
+    : findActiveStage(projectRoot, activeCriteria);
+  if (!eventId && startEvent) {
+    eventId = startEvent.event_id;
+  }
+  const orphan = !startEvent;
+  if (!eventId) {
+    eventId = generateEventId();
+  }
+  const timestamp = nowISO();
+  let details;
+  try {
+    details = args.details || parseJsonOption(args, 'details-json', 'details-file', projectRoot, {});
+  } catch (err) {
+    fail(`details JSON 解析失败: ${err.message}`);
+  }
+
+  const durationMs = startEvent
+    ? new Date(timestamp).getTime() - new Date(startEvent.timestamp).getTime()
+    : null;
+
+  const command = startEvent?.command || args.command || 'unknown';
+  const change = startEvent?.change || args.change || args['change-name'] || 'general';
+  if (command === 'archive' && result === 'success' && !reportOutput) {
+    reportOutput = path.join('skywalk-sdd', 'reports', `${safeChangeName(change)}-report.md`);
+  }
+  if (command === 'archive' && result === 'success') {
+    const repaired = ensureArchiveSuccessArtifacts(projectRoot, change, details, {
+      reason: details.archive_result?.reason || '',
+      reportOutput,
+    });
+    if (repaired.archive_result && Object.keys(repaired.archive_result).length > 0) {
+      details = {
+        ...details,
+        archive_result: {
+          ...(details.archive_result || {}),
+          ...repaired.archive_result,
+        },
+      };
+    }
+  }
+  const event = cleanOptionalFields({
+    schema_version: SCHEMA_VERSION,
+    event_id: eventId,
+    type: 'stage_end',
+    source: args.source || startEvent?.source || 'opsx-command',
+    command,
+    stage: startEvent?.stage || command,
+    change,
+    capability: args.capability || args['capability-name'] || startEvent?.capability,
+    task_id: args['task-id'] || args.task_id || startEvent?.task_id,
+    agent_type: args.agent || args['agent-type'] || startEvent?.agent_type || 'unknown',
+    project_root: projectRoot,
+    session_id: startEvent?.session_id || args['session-id'] || args.session_id,
+    git_sha: args['git-sha'] || args.git_sha || startEvent?.git_sha,
+    timestamp,
+    duration_ms: durationMs,
+    result,
+    summary,
+    details,
+    orphan: orphan ? true : undefined,
+  });
+
+  appendEvent(dataDir, event.change, event);
+  if (startEvent) {
+    clearActiveStage(projectRoot, startEvent);
+  }
+
+  let resolvedReportOutput = '';
+  if (reportOutput) {
+    const events = readEvents(dataDir, event.change);
+    const report = buildReport(projectRoot, events, {
+      level: args['report-level'] || 'change',
+      change: event.change,
+      capability: args.capability || args['capability-name'] || startEvent?.capability,
+    });
+    const reportFormat = args['report-format'] || 'markdown';
+    const rendered = reportFormat === 'json'
+      ? JSON.stringify(report, null, 2)
+      : renderExecutiveReportMarkdown(report);
+    resolvedReportOutput = path.isAbsolute(reportOutput)
+      ? reportOutput
+      : path.resolve(projectRoot, reportOutput);
+    ensureDir(path.dirname(resolvedReportOutput));
+    fs.writeFileSync(resolvedReportOutput, rendered + '\n', 'utf8');
+  }
+
+  const output = {
+    event_id: eventId,
+    duration_ms: durationMs,
+    recorded_at: timestamp,
+    report_output: resolvedReportOutput || undefined,
+    message: `SDD ${event.command} 阶段结束（${result}，耗时 ${durationMs ? (durationMs / 1000).toFixed(1) + 's' : '未知'}）`,
+  };
+  if (!options.silent) {
+    console.log(JSON.stringify(output, null, 2));
+  }
+  return output;
+}
+
+/**
+ * log record: 记录非阶段类结构化事件
+ */
+function cmdRecord(args) {
+  const type = args.type || args['event-type'];
+  const projectRoot = normalizeProjectRoot(args.project || args['project-root'] || process.cwd());
+  const change = args.change || args['change-name'] || 'general';
+  const source = args.source || 'opsx-command';
+  const agentType = inferAgentType(args);
+  const allowedTypes = [
+    'task_update',
+    'check_result',
+    'build_result',
+    'test_result',
+    'coverage_result',
+    'quality_gate_result',
+    'conformance_review',
+    'ai_adoption_review',
+    'survey_result',
+    'baseline_record',
+    'telemetry_warning',
+  ];
+
+  if (!type) {
+    console.error('错误: 缺少 --type 参数');
+    console.error(`有效值: ${allowedTypes.join(', ')}`);
+    process.exit(1);
+  }
+  if (!allowedTypes.includes(type)) {
+    console.error(`错误: 无效的 type "${type}"，有效值: ${allowedTypes.join(', ')}`);
+    process.exit(1);
+  }
+
+  let details;
+  try {
+    details = parseJsonOption(args, 'details-json', 'details-file', projectRoot, {});
+  } catch (err) {
+    fail(`details JSON 解析失败: ${err.message}`);
+  }
+
+  const dataDir = getDataDir(projectRoot);
+  const activeStage = findActiveStage(projectRoot, {
+    session_id: args['session-id'] || args.session_id,
+    change,
+    command: args.command,
+    agent_type: agentType,
+  });
+  const eventId = args['event-id'] || args.event_id || generateEventId();
+  const timestamp = nowISO();
+  const event = cleanOptionalFields({
+    schema_version: SCHEMA_VERSION,
+    event_id: eventId,
+    type,
+    source,
+    command: args.command,
+    stage: args.stage || args.command,
+    change,
+    capability: args.capability || args['capability-name'],
+    task_id: args['task-id'] || args.task_id,
+    agent_type: agentType,
+    project_root: projectRoot,
+    session_id: activeStage?.session_id || args['session-id'] || args.session_id,
+    git_sha: args['git-sha'] || args.git_sha,
+    timestamp,
+    result: args.result,
+    status: args.status,
+    summary: args.summary,
+    details,
+  });
+
+  appendEvent(dataDir, event.change, event);
+  console.log(JSON.stringify({
+    event_id: eventId,
+    type,
+    recorded_at: timestamp,
+    message: `SDD ${type} 事件已记录（change: ${event.change}）`,
+  }, null, 2));
+}
+
+/**
+ * 从事件文件中查找 start 事件（因为 CLI 无状态，需要从文件回溯）
+ */
+function findStartEvent(eventId) {
+  // 尝试从当前目录的 skywalk-sdd 查找
   const cwdDataDir = getDataDir(process.cwd());
   const found = searchEventInDataDir(cwdDataDir, eventId);
   if (found) return found;
@@ -477,26 +2359,29 @@ function searchEventInDataDir(dataDir, eventId) {
  * log metrics: 查询度量指标
  */
 function cmdMetrics(args) {
-  const projectRoot = args.project || args['project-root'] || process.cwd();
+  const projectRoot = normalizeProjectRoot(args.project || args['project-root'] || process.cwd());
   const changeName = args.change || args['change-name'];
+  const capability = args.capability || args['capability-name'];
   const dateFrom = args['date-from'];
   const dateTo = args['date-to'];
+  const format = args.format || 'json';
+  const level = args.level || (capability ? 'capability' : (changeName ? 'change' : 'project'));
+  const pdfMvp = Boolean(args['pdf-mvp']);
 
   const dataDir = getDataDir(projectRoot);
   let events = changeName ? readEvents(dataDir, changeName) : readAllEvents(dataDir);
 
-  // 日期过滤
-  if (dateFrom || dateTo) {
-    events = events.filter(e => {
-      const d = e.timestamp?.slice(0, 10);
-      if (dateFrom && d < dateFrom) return false;
-      if (dateTo && d > dateTo) return false;
-      return true;
-    });
-  }
+  events = filterEventsByDate(events, dateFrom, dateTo);
 
   let metrics;
-  if (changeName) {
+  if (pdfMvp) {
+    metrics = computePdfMvpMetrics(events, {
+      level,
+      change: changeName,
+      capability,
+      projectRoot,
+    });
+  } else if (changeName) {
     metrics = computeChangeMetrics(changeName, events);
     if (!metrics) {
       console.log(JSON.stringify({ error: `未找到变更 "${changeName}" 的事件数据` }));
@@ -506,7 +2391,164 @@ function cmdMetrics(args) {
     metrics = computeOverviewMetrics(events);
   }
 
-  console.log(JSON.stringify(metrics, null, 2));
+  if (format === 'markdown' && pdfMvp) {
+    console.log(renderPdfMvpMarkdown(metrics));
+  } else {
+    console.log(JSON.stringify(metrics, null, 2));
+  }
+}
+
+/**
+ * log report: 生成只读度量报告
+ */
+function cmdReport(args) {
+  const projectRoot = normalizeProjectRoot(args.project || args['project-root'] || process.cwd());
+  const changeName = args.change || args['change-name'];
+  const capability = args.capability || args['capability-name'];
+  const dateFrom = args['date-from'];
+  const dateTo = args['date-to'];
+  const format = args.format || 'markdown';
+  const outputPath = args.output || args['output-file'];
+  const level = args.level || (capability ? 'capability' : (changeName ? 'change' : 'project'));
+
+  const dataDir = getDataDir(projectRoot);
+  let events = changeName ? readEvents(dataDir, changeName) : readAllEvents(dataDir);
+  events = filterEventsByDate(events, dateFrom, dateTo);
+
+  const report = buildReport(projectRoot, events, {
+    level,
+    change: changeName,
+    capability,
+  });
+  const rendered = format === 'json'
+    ? JSON.stringify(report, null, 2)
+    : renderExecutiveReportMarkdown(report);
+
+  if (outputPath) {
+    const resolvedOutput = path.isAbsolute(outputPath)
+      ? outputPath
+      : path.resolve(projectRoot, outputPath);
+    ensureDir(path.dirname(resolvedOutput));
+    fs.writeFileSync(resolvedOutput, rendered + '\n', 'utf8');
+    console.log(JSON.stringify({
+      output: resolvedOutput,
+      format,
+      message: 'SDD report 已生成',
+    }, null, 2));
+    return;
+  }
+
+  console.log(rendered);
+}
+
+/**
+ * log doctor: 诊断 Telemetry 数据质量
+ */
+function cmdDoctor(args) {
+  const projectRoot = normalizeProjectRoot(args.project || args['project-root'] || process.cwd());
+  const changeName = args.change || args['change-name'];
+  const dateFrom = args['date-from'];
+  const dateTo = args['date-to'];
+
+  const dataDir = getDataDir(projectRoot);
+  let events = changeName ? readEvents(dataDir, changeName) : readAllEvents(dataDir);
+  events = filterEventsByDate(events, dateFrom, dateTo);
+
+  const report = computeDoctorReport(events, { change: changeName });
+  console.log(JSON.stringify(report, null, 2));
+  if (report.severe_issues.length > 0) {
+    process.exitCode = 1;
+  }
+}
+
+/**
+ * log tasks-status: 扫描 Full/Simple 模式 tasks.md 勾选状态
+ */
+function cmdTasksStatus(args) {
+  const projectRoot = normalizeProjectRoot(args.project || args['project-root'] || process.cwd());
+  const changeName = args.change || args['change-name'];
+  if (!changeName) {
+    console.error('错误: 缺少 --change 参数');
+    process.exit(1);
+  }
+
+  const status = scanTaskCompletion(projectRoot, changeName);
+  console.log(JSON.stringify(status, null, 2));
+  if (args['require-complete'] && (status.task_files.length === 0 || status.has_incomplete)) {
+    process.exitCode = 1;
+  }
+}
+
+/**
+ * log archive-docs: 真实归档 Simple/Full spec，结束 archive 阶段并生成最终报告
+ */
+function cmdArchiveDocs(args) {
+  const projectRoot = normalizeProjectRoot(args.project || args['project-root'] || process.cwd());
+  const changeName = args.change || args['change-name'];
+  const reportOutput = args['report-output'] || args.report_output ||
+    (changeName ? path.join('skywalk-sdd', 'reports', `${safeChangeName(changeName)}-report.md`) : undefined);
+
+  try {
+    let result;
+    const activeChangeDir = getChangeDir(projectRoot, changeName);
+    if (fs.existsSync(activeChangeDir)) {
+      result = archiveChangeDocs(projectRoot, changeName, {
+        reason: args.reason || '',
+        date: args.date,
+        keepActive: Boolean(args['keep-active']),
+      });
+    } else {
+      const repaired = ensureArchiveSuccessArtifacts(projectRoot, changeName, {
+        archive_result: {
+          reason: args.reason || '',
+          report_path: reportOutput,
+        },
+      }, {
+        reason: args.reason || '',
+        reportOutput,
+      });
+      if (!repaired.archive_result || !repaired.archive_result.archive_path) {
+        throw new Error(`change directory not found and no archive directory was detected: ${changeName}`);
+      }
+      result = {
+        project_root: projectRoot,
+        ...repaired.archive_result,
+        archive_path: path.resolve(projectRoot, repaired.archive_result.archive_path),
+        active_change_exists: false,
+      };
+    }
+
+    let stageEnd = null;
+    if (!args['keep-active']) {
+      stageEnd = cmdEnd({
+        ...args,
+        project: projectRoot,
+        command: 'archive',
+        change: changeName,
+        result: args.result || 'success',
+        summary: args.summary || '变更已真实归档，最终度量报告已生成',
+        details: {
+          ...(args.details && typeof args.details === 'object' ? args.details : {}),
+          archive_result: {
+            reason: args.reason || '',
+            method: result.method,
+            archive_path: result.archive_path,
+            report_path: reportOutput,
+          },
+        },
+        'report-output': reportOutput,
+      }, { silent: true });
+    }
+
+    console.log(JSON.stringify({
+      ...result,
+      report_output: stageEnd ? stageEnd.report_output : reportOutput,
+      stage_end_event_id: stageEnd ? stageEnd.event_id : undefined,
+    }, null, 2));
+  } catch (err) {
+    console.error(`错误: ${err.message}`);
+    process.exit(1);
+  }
 }
 
 // ── CLI 入口 ─────────────────────────────────────────
@@ -533,9 +2575,24 @@ function main() {
     case 'end':
       cmdEnd(flags);
       break;
+    case 'record':
+      cmdRecord(flags);
+      break;
     case 'metrics':
       cmdMetrics(flags);
       break;
+    case 'report':
+      cmdReport(flags);
+      break;
+    case 'doctor':
+      cmdDoctor(flags);
+      break;
+    case 'tasks-status':
+      cmdTasksStatus(flags);
+      break;
+    case 'archive-docs':
+      cmdArchiveDocs(flags);
+      break;
     default:
       showHelp();
       process.exit(1);
@@ -549,35 +2606,92 @@ 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>]
+  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>]
 
 子命令:
   start    记录 SDD 阶段开始，返回 event_id
   end      记录 SDD 阶段结束，关联 event_id
+  record   记录 task_update/check_result/test_result 等结构化事件
   metrics  查询度量指标（四维分析）
+  report   生成只读度量报告（不写入事件）
+  doctor   诊断 Telemetry 数据质量
+  tasks-status 扫描 Full/Simple 模式 tasks.md 勾选状态
+  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
 `);
 }
 
 // 导出供测试使用
 module.exports = {
+  SCHEMA_VERSION,
   main,
   parseArgs,
   cmdStart,
   cmdEnd,
+  cmdRecord,
   cmdMetrics,
+  cmdReport,
+  cmdDoctor,
+  cmdTasksStatus,
+  cmdArchiveDocs,
   computeChangeMetrics,
   computeOverviewMetrics,
+  computeCapabilityMetrics,
+  computeTelemetryHealthMetrics,
+  computePdfMvpMetrics,
+  renderPdfMvpMarkdown,
+  renderExecutiveReportMarkdown,
+  buildReport,
+  computeGitDocumentMetrics,
+  getCheckResults,
+  getBuildResults,
+  getTestResults,
+  getTaskUpdateResult,
+  computeAiFirstPassMetrics,
+  getSpecTestCoverage,
+  getSpecTestCoverageEvents,
+  computeSpecTestCoverageMetrics,
+  getConformanceReview,
+  getConformanceReviewEvents,
+  computeConformanceMetrics,
+  getAiAdoptionReview,
+  getAiAdoptionEvents,
+  computeAiAdoptionMetrics,
+  getSurveyResult,
+  getBaselineRecord,
+  computeManualInsightMetrics,
+  computeDoctorReport,
+  scanTaskCompletion,
+  archiveChangeDocs,
+  filterEventsByDate,
   readEvents,
   readAllEvents,
   appendEvent,
   getDataDir,
+  getStateDir,
   safeChangeName,
   generateEventId,
+  normalizeProjectRoot,
+  parseJsonOption,
+  writeActiveStage,
+  findActiveStage,
+  clearActiveStage,
   findStartEvent,
 };