@hunterzheng/kld-sdd 2.4.19

package/skywalk-sdd/index.cjs

@@ -0,0 +1,2991 @@
+#!/usr/bin/env node
+/**
+ * SDD Telemetry CLI
+ * 
+ * 本地 CLI 工具，为 SDD 工作流提供精确的流程度量采集。
+ * AI Agent 通过终端命令调用，将事件写入项目本地 skywalk-sdd/ 目录。
+ * 
+ * 用法:
+ *   node skywalk-sdd/log.cjs start  --command=propose --project=/path --change=xxx [--agent=cursor]
+ *   node skywalk-sdd/log.cjs end    --event-id=evt_xxx --result=success --summary="..."
+ *   node skywalk-sdd/log.cjs metrics --project=/path [--change=xxx]
+ */
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+const { execFileSync } = require('child_process');
+
+const SCHEMA_VERSION = 2;
+
+// result → 状态标记映射（execution-log.md 人读标记；checklist/SKILL 文档同步说明这套映射）
+const RESULT_MARK = { success: '✅OK', partial: '🟡WARN', failure: '❌FAIL' };
+
+// 返工原因 5 类（事件状态 + report-time git 推导 + agent 兜底）；agent --reason 枚举校验白名单
+const REWORK_REASON_CATEGORIES = ['incomplete', 'prev-failed', 'code-changed-after-pass', 'recheck-no-change', 'unspecified'];
+function createReasonCategory() {
+  return { incomplete: 0, 'prev-failed': 0, 'code-changed-after-pass': 0, 'recheck-no-change': 0, unspecified: 0 };
+}
+
+// ── 配置 ──────────────────────────────────────────────
+
+/** 获取项目的 skywalk-sdd 数据目录 */
+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'];
+
+// ── 工具函数 ──────────────────────────────────────────
+function ensureDir(dirPath) {
+  if (!fs.existsSync(dirPath)) {
+    fs.mkdirSync(dirPath, { recursive: true });
+  }
+}
+
+function generateEventId() {
+  return 'evt_' + crypto.randomBytes(6).toString('hex');
+}
+
+function today() {
+  return new Date().toISOString().slice(0, 10);
+}
+
+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 || '';
+
+  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,
+      reportPath: '',
+    };
+  }
+
+  // 显式 reportOutput 优先；否则默认落归档后 archive 目录的 reports/ 子目录
+  const reportPath = options.reportOutput
+    ? (path.isAbsolute(options.reportOutput) ? options.reportOutput : path.resolve(normalizedRoot, options.reportOutput))
+    : path.join(archiveDir, 'reports', `${safeChangeName(changeName)}-report.md`);
+
+  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: toProjectRelative(normalizedRoot, reportPath),
+    // report_html_path 为预期路径：由 cmdEnd 落盘阶段写入（try/catch 容错，失败时不阻塞 md 主产物）。
+    // 此处无条件派生，html 实际落盘失败时该路径可能不存在；语义为"预期路径"，消费者不应假定文件已存在。
+    report_html_path: toProjectRelative(normalizedRoot, reportPath.replace(/\.md$/i, '.html')),
+    manifest_path: toProjectRelative(normalizedRoot, manifestInfo.manifest_path),
+    task_completion: taskCompletion,
+    copied_specs: manifestInfo.copied_specs,
+  };
+
+  return {
+    changed: true,
+    archive_result: archiveResult,
+    task_completion: taskCompletion,
+    reportPath,
+  };
+}
+
+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));
+  ensureDir(dir);
+  const file = path.join(dir, `${today()}.jsonl`);
+  const line = JSON.stringify(event) + '\n';
+  fs.appendFileSync(file, line, 'utf8');
+  if (!fs.existsSync(file) || fs.statSync(file).size === 0) {
+    throw new Error(`事件文件写入验证失败: ${file}`);
+  }
+  appendMarkdownLog(dataDir, changeName, event);
+}
+
+/** 把事件同步追加为人读 markdown 行到 openspec/changes/<change>/logs/execution-log.md
+ *  （telemetry 副本；change 已归档时写入 archive 目录；失败不阻塞 telemetry 主流程） */
+function appendMarkdownLog(dataDir, changeName, event) {
+  try {
+    const projectRoot = path.dirname(dataDir);
+    const activeChangeDir = getChangeDir(projectRoot, changeName);
+    let logsDir = path.join(activeChangeDir, 'logs');
+    if (!fs.existsSync(activeChangeDir)) {
+      const archiveDir = findArchivedChangeDir(projectRoot, changeName);
+      if (archiveDir) logsDir = path.join(archiveDir, 'logs');
+    }
+    ensureDir(logsDir);
+    const file = path.join(logsDir, 'execution-log.md');
+    if (!fs.existsSync(file) || fs.statSync(file).size === 0) {
+      const created = (event.timestamp || nowISO()).slice(0, 16).replace('T', ' ');
+      fs.writeFileSync(file, `# 执行日志 — ${changeName}\n\n> 变更创建时间：${created} | 变更名：${changeName}\n\n---\n\n`, 'utf8');
+    }
+    const ts = (event.timestamp || nowISO()).replace('T', ' ').slice(0, 19);
+    const stage = event.command || event.stage || 'unknown';
+    const type = event.type || 'event';
+    const result = event.result || '';
+    const mark = RESULT_MARK[result] || '📝';
+    const summary = String(event.summary || '').replace(/\|/g, '/').replace(/\n/g, ' ');
+    fs.appendFileSync(file, `- [${ts}] ${stage} ${type} → ${mark}${result ? '(' + result + ')' : ''} | ${summary}\n`, 'utf8');
+  } catch (err) {
+    // markdown 副本失败不影响 telemetry 主流程，但输出 stderr 提示保留可观测性（避免持续性失败长期静默）
+    try { console.error(`[telemetry] execution-log 副本写入失败（不阻塞主流程）: ${err.message}`); } catch {}
+  }
+}
+
+/** 读取指定 change 的所有事件 */
+function readEvents(dataDir, changeName) {
+  try {
+    const dir = path.join(dataDir, 'events', safeChangeName(changeName));
+    if (!fs.existsSync(dir)) return [];
+
+    const events = [];
+    const files = fs.readdirSync(dir).filter(f => f.endsWith('.jsonl')).sort();
+    for (const file of files) {
+      const lines = fs.readFileSync(path.join(dir, file), 'utf-8').split('\n').filter(Boolean);
+      for (const line of lines) {
+        try { events.push(JSON.parse(line)); } catch {}
+      }
+    }
+    return events;
+  } catch (err) {
+    console.error('[sdd-telemetry] 事件读取失败:', err.message);
+    return [];
+  }
+}
+
+/** 读取所有 change 的事件 */
+function readAllEvents(dataDir) {
+  const eventsDir = path.join(dataDir, 'events');
+  if (!fs.existsSync(eventsDir)) return [];
+
+  const events = [];
+  const changeDirs = fs.readdirSync(eventsDir).filter(d => {
+    return fs.statSync(path.join(eventsDir, d)).isDirectory();
+  });
+
+  for (const changeDir of changeDirs) {
+    const changeEvents = readEvents(dataDir, changeDir);
+    events.push(...changeEvents);
+  }
+  return events;
+}
+
+// ── 四维度量指标计算 ──────────────────────────────────
+
+/**
+ * 计算单个 change 的四维指标
+ */
+function computeChangeMetrics(changeName, events) {
+  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');
+  const ends = changeEvents.filter(e => e.type === 'stage_end');
+
+  // 已执行的阶段（去重）
+  const executedStages = [...new Set(starts.map(e => e.command))];
+  const completedStages = [...new Set(ends.map(e => e.command))];
+
+  // ── 维度一：流程健康度 ──
+  const coveredCoreStages = CORE_STAGES.filter(s => executedStages.includes(s));
+  const criticalPathCoverage = coveredCoreStages.length / CORE_STAGES.length;
+
+  // 跳阶段检测
+  const stageSequence = starts.map(e => e.command);
+  const skippedStages = detectSkippedStages(stageSequence);
+
+  // 阶段回退检测
+  const regressions = detectRegressions(stageSequence);
+  const regressionRate = stageSequence.length > 1 
+    ? regressions.length / (stageSequence.length - 1) 
+    : 0;
+
+  // Spec 存在率
+  const hasSpec = executedStages.includes('spec');
+
+  // ── 维度二：交付效率 ──
+  const proposeStart = starts.find(e => e.command === 'propose');
+  const archiveEnd = ends.find(e => e.command === 'archive');
+  const changeLeadTime = (proposeStart && archiveEnd)
+    ? new Date(archiveEnd.timestamp).getTime() - new Date(proposeStart.timestamp).getTime()
+    : null;
+
+  const designEnd = ends.find(e => e.command === 'design');
+  const applyStart = starts.find(e => e.command === 'apply');
+  const designToCodeTime = (designEnd && applyStart)
+    ? new Date(applyStart.timestamp).getTime() - new Date(designEnd.timestamp).getTime()
+    : null;
+
+  // 首次 Apply 成功率
+  const testEvents = getTestEvents(changeEvents);
+  const firstTestEvent = firstByTimestamp(testEvents);
+  const firstTestSuccess = firstTestEvent
+    ? (firstTestEvent.result === 'success' || getTestResults(firstTestEvent)?.failed === 0)
+    : null;
+
+  // 阶段平均耗时
+  const stageDurations = {};
+  for (const end of ends) {
+    if (end.duration_ms) {
+      if (!stageDurations[end.command]) stageDurations[end.command] = [];
+      stageDurations[end.command].push(end.duration_ms);
+    }
+  }
+  const avgStageDurations = {};
+  for (const [stage, durations] of Object.entries(stageDurations)) {
+    avgStageDurations[stage] = Math.round(durations.reduce((a, b) => a + b, 0) / durations.length);
+  }
+
+  // ── 维度三：质量信号 ──
+  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 = 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))];
+  const isCompleted = !!archiveEnd;
+
+  return {
+    change: changeName,
+    process_health: {
+      critical_path_coverage: criticalPathCoverage,
+      covered_core_stages: coveredCoreStages,
+      regression_rate: regressionRate,
+      regressions,
+      skipped_stages: skippedStages,
+      has_spec: hasSpec,
+    },
+    delivery_efficiency: {
+      change_lead_time_ms: changeLeadTime,
+      design_to_code_time_ms: designToCodeTime,
+      first_apply_success: firstTestSuccess,
+      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,
+    },
+  };
+}
+
+/** 检测跳阶段 */
+function detectSkippedStages(sequence) {
+  const skipped = [];
+  for (let i = 1; i < sequence.length; i++) {
+    const prevIdx = STAGE_ORDER.indexOf(sequence[i - 1]);
+    const currIdx = STAGE_ORDER.indexOf(sequence[i]);
+    if (prevIdx >= 0 && currIdx >= 0 && currIdx > prevIdx + 1) {
+      const missed = STAGE_ORDER.slice(prevIdx + 1, currIdx);
+      skipped.push({ from: sequence[i - 1], to: sequence[i], missed });
+    }
+  }
+  return skipped;
+}
+
+/** 检测阶段回退 */
+function detectRegressions(sequence) {
+  const regressions = [];
+  for (let i = 1; i < sequence.length; i++) {
+    const prevIdx = STAGE_ORDER.indexOf(sequence[i - 1]);
+    const currIdx = STAGE_ORDER.indexOf(sequence[i]);
+    if (prevIdx >= 0 && currIdx >= 0 && currIdx < prevIdx) {
+      regressions.push({ from: sequence[i - 1], back_to: sequence[i] });
+    }
+  }
+  return regressions;
+}
+
+/**
+ * 计算全局概览指标
+ */
+function computeOverviewMetrics(events) {
+  const changeNames = [...new Set(events.map(e => e.change).filter(Boolean))];
+
+  const changeMetrics = changeNames
+    .map(name => computeChangeMetrics(name, events))
+    .filter(Boolean);
+
+  const totalChanges = changeMetrics.length;
+  if (totalChanges === 0) {
+    return { total_changes: 0, message: '暂无事件数据' };
+  }
+
+  // 维度一汇总
+  const avgCriticalPath = changeMetrics.reduce((s, m) => s + m.process_health.critical_path_coverage, 0) / totalChanges;
+  const specRate = changeMetrics.filter(m => m.process_health.has_spec).length / totalChanges;
+  const avgRegressionRate = changeMetrics.reduce((s, m) => s + m.process_health.regression_rate, 0) / totalChanges;
+
+  // 维度二汇总
+  const completedChanges = changeMetrics.filter(m => m.delivery_efficiency.change_lead_time_ms != null);
+  const avgLeadTime = completedChanges.length > 0
+    ? completedChanges.reduce((s, m) => s + m.delivery_efficiency.change_lead_time_ms, 0) / completedChanges.length
+    : null;
+  const firstApplySuccessRate = (() => {
+    const withTest = changeMetrics.filter(m => m.delivery_efficiency.first_apply_success != null);
+    return withTest.length > 0
+      ? withTest.filter(m => m.delivery_efficiency.first_apply_success).length / withTest.length
+      : null;
+  })();
+
+  // 维度三汇总
+  const firstCheckPassRate = (() => {
+    const withCheck = changeMetrics.filter(m => m.quality_signals.first_check_pass != null);
+    return withCheck.length > 0
+      ? withCheck.filter(m => m.quality_signals.first_check_pass).length / withCheck.length
+      : 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,
+    process_health: {
+      avg_critical_path_coverage: Math.round(avgCriticalPath * 100) / 100,
+      spec_existence_rate: Math.round(specRate * 100) / 100,
+      avg_regression_rate: Math.round(avgRegressionRate * 100) / 100,
+    },
+    delivery_efficiency: {
+      avg_lead_time_ms: avgLeadTime != null ? Math.round(avgLeadTime) : null,
+      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,
+    },
+  };
+}
+
+function roundMetric(value, digits = 2) {
+  if (value == null || Number.isNaN(value)) return null;
+  const factor = 10 ** digits;
+  return Math.round(value * factor) / factor;
+}
+
+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);
+}
+
+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);
+}
+
+function firstByTimestamp(events) {
+  return [...events].sort((a, b) => new Date(a.timestamp).getTime() - new Date(b.timestamp).getTime())[0] || null;
+}
+
+function latestByTimestamp(events) {
+  return [...events].sort((a, b) => new Date(b.timestamp).getTime() - new Date(a.timestamp).getTime())[0] || null;
+}
+
+function timestampMs(event) {
+  const value = Date.parse(event?.timestamp || '');
+  return Number.isFinite(value) ? value : 0;
+}
+
+function stageAttemptKey(event) {
+  return [
+    event?.command || event?.stage || 'unknown',
+    event?.capability || '',
+  ].join('|');
+}
+
+function createReworkBucket(command, capability) {
+  return {
+    command,
+    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,
+    reasons_by_category: createReasonCategory(),
+  };
+}
+
+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);
+  }
+
+  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);
+  }
+
+  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)) {
+        if (attempt.end && attempt.end.rework_reason) {
+          attempt.rework_reason = attempt.end.rework_reason;
+        } else if (!attempt.end) {
+          attempt.rework_reason = 'incomplete';
+        } else if (attempt.result === 'failure') {
+          attempt.rework_reason = 'prev-failed';
+        } else {
+          attempt.rework_reason = 'completed_rework_success';
+        }
+        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;
+      }
+    }
+  }
+
+  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),
+    },
+  };
+}
+
+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;
+}
+
+function hasOfficialSource(event) {
+  return !event?.source || ['opsx-command', 'manual', 'ci'].includes(event.source);
+}
+
+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 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, reasons) {
+  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,
+    reasons: reasons || { by_category: createReasonCategory(), details: [] },
+  };
+}
+
+// report-time git 推导返工原因：对 summarizeStageExecutions 产出的 reworkAttempts 细化
+// - agent override 优先（stage_end.rework_reason 由 cmdEnd --reason 写入，summarizeStageExecutions 已保留）
+// - completed_rework_success（上次成功却重跑）按 git 推导：有 commit since end → code-changed-after-pass；
+//   无 commit 但 working tree 未提交 → code-changed-after-pass(has_uncommitted)；都无 → recheck-no-change
+// - no git repo → unspecified
+// 注：用 `git log --all --since` 取所有 ref 上 commit date >= end.timestamp 的提交；reset 掉的 unreachable
+// commit 不计入（完全实现需 reflog，复杂且会 expire，本期务实按 ref 可达）
+function deriveReworkReasons(executionSummary, projectRoot) {
+  const byCategory = createReasonCategory();
+  const details = [];
+  const reworkAttempts = executionSummary.reworkAttempts || [];
+  const gitAvailable = projectRoot ? runGit(projectRoot, ['rev-parse', '--is-inside-work-tree']) === 'true' : false;
+  let uncommittedCache = null;
+  const hasUncommitted = () => {
+    if (uncommittedCache !== null) return uncommittedCache;
+    if (!gitAvailable) { uncommittedCache = false; return false; }
+    const status = runGit(projectRoot, ['status', '--porcelain']);
+    uncommittedCache = Boolean(status && status.trim());
+    return uncommittedCache;
+  };
+  const bucketByKey = new Map();
+  for (const bucket of executionSummary.summary.by_stage || []) {
+    if (!bucket.reasons_by_category) bucket.reasons_by_category = createReasonCategory();
+    bucketByKey.set(`${bucket.command}|${bucket.capability || ''}`, bucket);
+  }
+  for (const attempt of reworkAttempts) {
+    let reason = attempt.rework_reason;
+    let detail = null;
+    let hasUncommittedFlag = false;
+    if (reason === 'completed_rework_success') {
+      if (!gitAvailable) {
+        reason = 'unspecified';
+      } else {
+        const endTs = attempt.end && attempt.end.timestamp ? Date.parse(attempt.end.timestamp) : null;
+        let recentCommitMessage = null;
+        if (endTs !== null && Number.isFinite(endTs)) {
+          const sinceIso = new Date(endTs).toISOString();
+          const log = runGit(projectRoot, ['log', '--all', '--since', sinceIso, '--format=%H%x09%cI%x09%s']);
+          if (log) {
+            const lines = log.split(/\r?\n/).filter(Boolean);
+            if (lines.length > 0) {
+              const parts = lines[0].split('\t');
+              recentCommitMessage = parts[2] || '';
+            }
+          }
+        }
+        const uncommitted = hasUncommitted();
+        if (recentCommitMessage !== null) {
+          reason = 'code-changed-after-pass';
+          detail = recentCommitMessage;
+          hasUncommittedFlag = uncommitted;
+        } else if (uncommitted) {
+          reason = 'code-changed-after-pass';
+          hasUncommittedFlag = true;
+        } else {
+          reason = 'recheck-no-change';
+        }
+      }
+    }
+    attempt.rework_reason = reason;
+    byCategory[reason] = (byCategory[reason] || 0) + 1;
+    const bucket = bucketByKey.get(`${attempt.command}|${attempt.capability || ''}`);
+    if (bucket) {
+      bucket.reasons_by_category[reason] = (bucket.reasons_by_category[reason] || 0) + 1;
+    }
+    details.push({
+      command: attempt.command,
+      attempt_event_id: (attempt.start && attempt.start.event_id) || null,
+      reason,
+      detail,
+      has_uncommitted: hasUncommittedFlag,
+    });
+  }
+  return { by_category: byCategory, details };
+}
+
+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';
+  });
+  // 优先使用 final 事件，无 final 时 fallback 到 snapshot（AI 产出快照）
+  const candidates = finalEvents.length > 0 ? finalEvents : adoptionEvents;
+  const latestEvent = latestByTimestamp(candidates);
+  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 reworkReasons = deriveReworkReasons(executionSummary, options.projectRoot);
+  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?.spec_iteration_count != null
+    ? 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, reworkReasons),
+    },
+    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 formatReworkReasons(reasons) {
+  if (!reasons || !reasons.by_category) return 'null';
+  return REWORK_REASON_CATEGORIES.map(c => `${c}=${reasons.by_category[c] ?? 0}`).join(', ');
+}
+
+function formatReworkReasonDetails(reasons) {
+  if (!reasons || !Array.isArray(reasons.details) || reasons.details.length === 0) return [];
+  return reasons.details.map(d => `- ${d.command} → ${d.reason}${d.detail ? ` [${String(d.detail).replace(/[\r\n\]]/g, ' ')}]` : ''}${d.has_uncommitted ? '（含未提交变更）' : ''}`);
+}
+
+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'}`,
+    `- 返工原因分布：${formatReworkReasons(metrics.process?.rework_summary?.reasons)}`,
+    ...formatReworkReasonDetails(metrics.process?.rework_summary?.reasons),
+    '',
+    '## 归档结果',
+    `- 归档原因：${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` 表示当前还没有采集到对应事件或该指标暂不适用。',
+    '- E4 AI 一次成码率：依赖 `task_update` 事件中的 `task_id` 和首次执行结果，若 apply 阶段未正确记录则显示 null。',
+    '- P1 文档迭代次数：优先使用 Git 提交历史统计，无 Git 仓库或无提交历史时使用阶段 start 事件数。',
+    '- P2 AI 代码保留率：优先使用 `ai_adoption_review` 的 final 状态，无 final 时 fallback 到 AI 产出快照（ai_snapshot）。',
+    '- Q4 规约驱动测试覆盖率：依赖 check/test 阶段记录 spec 断言到测试用例的映射数据（spec_test_coverage 字段），属高级功能。',
+    '- Q1 规约符合度与人工反馈类指标属于评审信号，默认不作为强阻断门禁。',
+  ].join('\n');
+}
+
+function renderExecutiveReportHtml(report) {
+  const metrics = report.metrics;
+  const health = report.doctor;
+  const archive = report.archive_result || null;
+  const taskCompletion = archive?.task_completion || null;
+  const esc = (v) => String(v ?? '').replace(/[&<>"']/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[c]));
+  const badgeClass = (s) => {
+    const v = String(s ?? '').toUpperCase();
+    if (v.includes('FAIL') || v.includes('ERROR')) return 'bad';
+    if (v.includes('WARN') || v.includes('PARTIAL')) return 'warn';
+    return 'ok';
+  };
+  const badge = (s) => `<span class="badge ${badgeClass(s)}">${esc(s || 'N/A')}</span>`;
+  const reasonDetails = formatReworkReasonDetails(metrics.process?.rework_summary?.reasons)
+    .map(d => `<li>${esc(d)}</li>`).join('\n');
+  const severeList = (health.severe_issues || []).map(i => `<li>${esc(typeof i === 'string' ? i : JSON.stringify(i))}</li>`).join('\n');
+  const severeHtml = severeList ? `<ul class="severe">${severeList}</ul>` : '<span class="muted">无</span>';
+  return `<!doctype html>
+<html lang="zh-CN">
+<head>
+<meta charset="utf-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1" />
+<title>SDD 效果度量报告${report.change ? ` - ${esc(report.change)}` : ''}</title>
+<style>
+body { font-family:-apple-system,BlinkMacSystemFont,'Segoe UI','Microsoft YaHei',sans-serif; margin:0; background:#0b1020; color:#e5e7eb; }
+main { max-width:980px; margin:0 auto; padding:32px; }
+.card { background:rgba(255,255,255,.06); border:1px solid rgba(255,255,255,.12); border-radius:16px; padding:20px; margin:16px 0; }
+h1 { margin:0 0 8px; font-size:28px; }
+h2 { margin:0 0 12px; font-size:18px; }
+.muted { color:#94a3b8; }
+table { width:100%; border-collapse:collapse; }
+th,td { border-bottom:1px solid rgba(255,255,255,.12); padding:10px; text-align:left; vertical-align:top; }
+th { color:#cbd5e1; width:40%; }
+code { color:#bfdbfe; word-break:break-all; }
+.badge { display:inline-block; padding:4px 8px; border-radius:999px; font-weight:700; font-size:12px; }
+.badge.ok { background:rgba(34,197,94,.16); color:#86efac; }
+.badge.warn { background:rgba(245,158,11,.18); color:#fcd34d; }
+.badge.bad { background:rgba(239,68,68,.18); color:#fca5a5; }
+ul { margin-top:8px; }
+.severe li { color:#fca5a5; }
+</style>
+</head>
+<body><main>
+<div class="card">
+  <h1>SDD 效果度量报告${report.change ? ` - ${esc(report.change)}` : ''}</h1>
+  <p class="muted">生成时间：${esc(report.generated_at)}　项目路径：${esc(report.project_root)}　统计范围：${esc(report.change ? `change/${report.change}` : 'project')}</p>
+</div>
+<div class="card"><h2>执行摘要</h2><table>
+  <tr><th>Telemetry 健康分</th><td>${badge(formatRatioToPercent(health.telemetry_health_score))}</td></tr>
+  <tr><th>阶段闭环率</th><td>${badge(formatRatioToPercent(health.matched_stage_rate))}</td></tr>
+  <tr><th>严重问题数</th><td>${esc(health.severe_issues?.length || 0)}</td></tr>
+  <tr><th>严重问题明细</th><td>${severeHtml}</td></tr>
+</table></div>
+<div class="card"><h2>效率指标</h2><table>
+  <tr><th>E1 需求到归档总时长</th><td>${esc(formatMsToSeconds(metrics.efficiency?.e1_lead_time_ms))}</td></tr>
+  <tr><th>E2 编码时间占比</th><td>${esc(formatRatioToPercent(metrics.efficiency?.e2_coding_time_ratio))}</td></tr>
+  <tr><th>E3 规约时间占比</th><td>${esc(formatRatioToPercent(metrics.efficiency?.e3_spec_time_ratio))}</td></tr>
+  <tr><th>E4 AI 一次成码率</th><td>${esc(formatRatioToPercent(metrics.efficiency?.e4_ai_code_first_pass_rate))}</td></tr>
+  <tr><th>有效阶段总耗时</th><td>${esc(formatMsToSeconds(metrics.efficiency?.effective_stage_duration_ms))}</td></tr>
+  <tr><th>返工阶段总耗时</th><td>${esc(formatMsToSeconds(metrics.efficiency?.rework_stage_duration_ms))}</td></tr>
+</table></div>
+<div class="card"><h2>质量指标</h2><table>
+  <tr><th>Q1 规约符合度</th><td>${esc(metrics.quality?.q1_spec_conformance_score ?? 'null')}</td></tr>
+  <tr><th>Q3 构建一次通过率</th><td>${esc(formatRatioToPercent(metrics.quality?.q3_build_first_pass_rate))}</td></tr>
+  <tr><th>Q4 规约驱动测试覆盖率</th><td>${esc(formatRatioToPercent(metrics.quality?.q4_spec_driven_test_coverage))}</td></tr>
+  <tr><th>Q5 跨文档一致性得分</th><td>${esc(metrics.quality?.q5_cross_doc_consistency_score ?? 'null')}</td></tr>
+</table></div>
+<div class="card"><h2>过程指标</h2><table>
+  <tr><th>P1 文档迭代次数</th><td>${esc(metrics.process?.p1_spec_iteration_count ?? 'null')}</td></tr>
+  <tr><th>P2 AI 代码保留率</th><td>${esc(formatRatioToPercent(metrics.process?.p2_ai_code_adoption_rate))}</td></tr>
+  <tr><th>P4 质量门前置率</th><td>${esc(formatRatioToPercent(metrics.process?.p4_quality_gate_enforcement_rate))}</td></tr>
+  <tr><th>返工次数</th><td>${esc(metrics.process?.rework_summary?.total_rework_attempts ?? 'null')}</td></tr>
+  <tr><th>被覆盖未闭环阶段数</th><td>${esc(metrics.process?.rework_summary?.superseded_open_stages ?? 'null')}</td></tr>
+  <tr><th>返工原因分布</th><td>${esc(formatReworkReasons(metrics.process?.rework_summary?.reasons))}</td></tr>
+</table>
+${reasonDetails ? `<ul>${reasonDetails}</ul>` : ''}</div>
+<div class="card"><h2>归档结果</h2><table>
+  <tr><th>归档原因</th><td>${esc(archive?.reason || 'null')}</td></tr>
+  <tr><th>归档方式</th><td>${esc(archive?.method || 'null')}</td></tr>
+  <tr><th>归档目录</th><td><code>${esc(archive?.archive_path || 'null')}</code></td></tr>
+  <tr><th>归档清单</th><td><code>${esc(archive?.manifest_path || 'null')}</code></td></tr>
+  <tr><th>最终报告(md)</th><td><code>${esc(archive?.report_path || 'null')}</code></td></tr>
+  <tr><th>最终报告(html)</th><td><code>${esc(archive?.report_html_path || 'null')}</code></td></tr>
+  <tr><th>已完成任务项</th><td>${esc(taskCompletion?.completed ?? 'null')}</td></tr>
+  <tr><th>未勾选任务项</th><td>${esc(taskCompletion?.incomplete ?? 'null')}</td></tr>
+  <tr><th>任务项总数</th><td>${esc(taskCompletion?.total ?? 'null')}</td></tr>
+</table></div>
+<div class="card"><h2>说明</h2><ul>
+  <li><code>null</code> 表示当前还没有采集到对应事件或该指标暂不适用。</li>
+  <li>E4 AI 一次成码率：依赖 <code>task_update</code> 事件中的 <code>task_id</code> 和首次执行结果，若 apply 阶段未正确记录则显示 null。</li>
+  <li>P1 文档迭代次数：优先使用 Git 提交历史统计，无 Git 仓库或无提交历史时使用阶段 start 事件数。</li>
+  <li>P2 AI 代码保留率：优先使用 <code>ai_adoption_review</code> 的 final 状态，无 final 时 fallback 到 ai_snapshot。</li>
+  <li>Q4 规约驱动测试覆盖率：依赖 check/test 阶段记录 spec 断言到测试用例的映射数据（spec_test_coverage 字段），属高级功能。</li>
+  <li>Q1 规约符合度与人工反馈类指标属于评审信号，默认不作为强阻断门禁。</li>
+</ul></div>
+</main></body></html>`;
+}
+
+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, projectRoot }),
+    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 reworkReasons = deriveReworkReasons(executionSummary, options.projectRoot);
+  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 === 'incomplete')
+    .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, reworkReasons),
+    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.cjs 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 || '';
+
+  if (!result) {
+    console.error('错误: 缺少 --result 参数（success/failure/partial）');
+    process.exit(1);
+  }
+
+  const reason = args.reason;
+  if (reason !== undefined && reason !== null && !REWORK_REASON_CATEGORIES.includes(reason)) {
+    console.error(`错误: --reason 非法枚举（${reason}），合法值：${REWORK_REASON_CATEGORIES.join('/')}`);
+    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 (!reportOutput && args['generate-report']) {
+    // archive success 时归档已把 change 移到 archive 目录，此时若默认活跃路径会让
+    // ensureArchiveSuccessArtifacts 走显式分支 → 报告落活跃路径 + ensureDir 重建空 active。
+    // 故 archive success 不设活跃默认，由 repaired.reportPath 兜底到 archive 目录。
+    if (!(command === 'archive' && result === 'success')) {
+      reportOutput = path.join('openspec', 'changes', change, 'reports', `${safeChangeName(change)}-report.md`);
+    }
+  }
+  let repaired = null;
+  if (command === 'archive' && result === 'success') {
+    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,
+    rework_reason: reason || undefined,
+    orphan: orphan ? true : undefined,
+  });
+
+  appendEvent(dataDir, event.change, event);
+  if (startEvent) {
+    clearActiveStage(projectRoot, startEvent);
+  }
+
+  let resolvedReportOutput = '';
+  if (reportOutput) {
+    resolvedReportOutput = path.isAbsolute(reportOutput) ? reportOutput : path.resolve(projectRoot, reportOutput);
+  } else if (repaired && repaired.reportPath) {
+    resolvedReportOutput = repaired.reportPath;
+  }
+  if (resolvedReportOutput) {
+    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);
+    ensureDir(path.dirname(resolvedReportOutput));
+    fs.writeFileSync(resolvedReportOutput, rendered + '\n', 'utf8');
+    if (reportFormat !== 'json') {
+      // md 默认双输出：同目录 .html 副本，写入失败不阻塞 md 主产物。
+      // 仅当主路径是 .md 时才派生 .html 副本，避免自定义非 .md 主路径（如 --report-output=xxx.txt）
+      // 因 .replace(/\.md$/i,'.html') 不匹配而 htmlPath 与主路径相同，导致 html 内容静默覆盖 md 主产物。
+      try {
+        const htmlPath = resolvedReportOutput.replace(/\.md$/i, '.html');
+        if (htmlPath !== resolvedReportOutput) {
+          fs.writeFileSync(htmlPath, renderExecutiveReportHtml(report) + '\n', 'utf8');
+        }
+      } catch (err) {
+        try { console.error(`[telemetry] html 报告副本写入失败（不阻塞主流程）: ${err.message}`); } catch {}
+      }
+    }
+  }
+
+  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',
+    'worktree_finish',
+  ];
+
+  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;
+  return null;
+}
+
+function searchEventInDataDir(dataDir, eventId) {
+  const eventsDir = path.join(dataDir, 'events');
+  if (!fs.existsSync(eventsDir)) return null;
+
+  try {
+    const changeDirs = fs.readdirSync(eventsDir).filter(d => {
+      return fs.statSync(path.join(eventsDir, d)).isDirectory();
+    });
+
+    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 (const line of lines) {
+          try {
+            const event = JSON.parse(line);
+            if (event.event_id === eventId && event.type === 'stage_start') {
+              return event;
+            }
+          } catch {}
+        }
+      }
+    }
+  } catch {}
+  return null;
+}
+
+/**
+ * log metrics: 查询度量指标
+ */
+function cmdMetrics(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 || '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);
+
+  events = filterEventsByDate(events, dateFrom, dateTo);
+
+  let metrics;
+  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}" 的事件数据` }));
+      return;
+    }
+  } else {
+    metrics = computeOverviewMetrics(events);
+  }
+
+  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)
+    : format === 'html'
+      ? renderExecutiveReportHtml(report)
+      : 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, projectRoot });
+  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 || '';
+
+  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,
+        // 归档原因（args.reason）走 details.archive_result.reason，不应作为 cmdEnd 的返工 --reason（枚举）传入
+        reason: undefined,
+        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 入口 ─────────────────────────────────────────
+
+function main() {
+  // 支持两种调用方式:
+  // 1) npx kld-sdd log start ...     → argv 含 'log'
+  // 2) node skywalk-sdd/log.cjs start ... → argv 直接以子命令开头
+  const argv = process.argv.slice(2);
+  const logIdx = argv.indexOf('log');
+  const subArgs = logIdx === -1 ? argv : argv.slice(logIdx + 1);
+
+  if (!subArgs.length || subArgs[0] === '-h' || subArgs[0] === '--help') {
+    showHelp();
+    process.exit(subArgs.length ? 0 : 1);
+  }
+  const subCommand = subArgs[0];
+  const flags = parseArgs(subArgs.slice(1));
+
+  switch (subCommand) {
+    case 'start':
+      cmdStart(flags);
+      break;
+    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);
+  }
+}
+
+function showHelp() {
+  console.log(`
+SDD Telemetry CLI - 流程度量采集工具
+
+用法:
+  node skywalk-sdd/log.cjs start   --command=<cmd> --project=<path> [--change=<name>] [--agent=<type>]
+  node skywalk-sdd/log.cjs end     --event-id=<id> --result=<success|failure|partial> --summary="..."
+  node skywalk-sdd/log.cjs metrics --project=<path> [--change=<name>] [--pdf-mvp] [--format=json|markdown]
+  node skywalk-sdd/log.cjs report  --project=<path> [--change=<name>] [--format=json|markdown|html] [--output=<file>]
+  node skywalk-sdd/log.cjs tasks-status --project=<path> --change=<name> [--require-complete]
+  node skywalk-sdd/log.cjs archive-docs --project=<path> --change=<name> [--reason=<text>] [--event-id=<id>] [--report-output=<file>]
+
+子命令:
+  start    记录 SDD 阶段开始，返回 event_id
+  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.cjs start --command=propose --project=/my/project --change=user-auth --agent=cursor
+  node skywalk-sdd/log.cjs end --event-id=evt_abc123 --result=success --summary="创建 proposal.md"
+  node skywalk-sdd/log.cjs record --type=task_update --command=apply --project=/my/project --change=user-auth --task-id=TASK-01 --status=completed
+  node skywalk-sdd/log.cjs record --type=conformance_review --command=check --project=/my/project --change=user-auth --source=manual --details-file=conformance-review.json
+  node skywalk-sdd/log.cjs record --type=ai_adoption_review --command=apply --project=/my/project --change=user-auth --status=final --details-file=ai-adoption.json
+  node skywalk-sdd/log.cjs record --type=survey_result --project=/my/project --change=user-auth --source=manual --details-file=survey.json
+  node skywalk-sdd/log.cjs metrics --project=/my/project --change=user-auth
+  node skywalk-sdd/log.cjs metrics --project=/my/project --change=user-auth --pdf-mvp --format=markdown
+  node skywalk-sdd/log.cjs report --project=/my/project --change=user-auth --format=markdown
+  node skywalk-sdd/log.cjs doctor --project=/my/project --change=user-auth
+  node skywalk-sdd/log.cjs tasks-status --project=/my/project --change=user-auth --require-complete
+  node skywalk-sdd/log.cjs archive-docs --project=/my/project --change=user-auth --reason="变更已完成实施" --event-id=evt_archive
+  # archive-docs 最终报告默认生成到 openspec/changes/archive/<日期>-<change>/reports/<change>-report.md；可用 --report-output=<路径> 指定自定义路径
+  node skywalk-sdd/log.cjs record --type=worktree_finish --command=apply --project=/my/project --change=user-auth --capability=user-auth --result=success --summary="merge+remove completed"
+
+Apply worktree（主仓库根目录，非 log.cjs 子命令）:
+  node skywalk-sdd/apply-worktree-finish.cjs --record-base --change=<name> --capability=<name>
+  node skywalk-sdd/apply-worktree-finish.cjs --change=<name> --capability=<name> [--target=<integration-base>] [--dry-run]
+`);
+}
+
+// 导出供测试使用
+module.exports = {
+  SCHEMA_VERSION,
+  main,
+  parseArgs,
+  cmdStart,
+  cmdEnd,
+  cmdRecord,
+  cmdMetrics,
+  cmdReport,
+  cmdDoctor,
+  cmdTasksStatus,
+  cmdArchiveDocs,
+  computeChangeMetrics,
+  computeOverviewMetrics,
+  computeCapabilityMetrics,
+  computeTelemetryHealthMetrics,
+  computePdfMvpMetrics,
+  renderPdfMvpMarkdown,
+  renderExecutiveReportMarkdown,
+  renderExecutiveReportHtml,
+  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,
+};
+
+// 直接运行时执行
+if (require.main === module) {
+  main();
+}