kld-sdd 2.4.19 → 2.5.0

package/skywalk-sdd/index.cjs

@@ -18,6 +18,26 @@ const { execFileSync } = require('child_process');
 
 const SCHEMA_VERSION = 2;
 
+// result → 状态标记映射（execution-log.md 人读标记；checklist/SKILL 文档同步说明这套映射）
+const RESULT_MARK = { success: '✅OK', partial: '🟡WARN', failure: '❌FAIL' };
+
+// 返工原因 6 类（事件状态 + report-time git 推导 + agent 兜底）；agent --reason 枚举校验白名单
+// T3.6: 新增 pre-archive-recheck（check 在 test 后重跑，归档前强制复检，无 git diff 证据）
+const REWORK_REASON_CATEGORIES = ['incomplete', 'prev-failed', 'code-changed-after-pass', 'recheck-no-change', 'pre-archive-recheck', 'unspecified'];
+// 返工原因英文 code → 中文展示映射（报告面向人读，英文 code 不直观)
+// 2.6.x 术语调整：将"返工"统一改为"重复执行/流程修正"，避免误解为代码重做
+const REWORK_REASON_CN = {
+  'incomplete': '未闭环',
+  'prev-failed': '前次未完成',
+  'code-changed-after-pass': '通过后代码变更',
+  'recheck-no-change': '复检无变更',
+  'pre-archive-recheck': '归档前强制复检',
+  'unspecified': '未归类',
+};
+function createReasonCategory() {
+  return { incomplete: 0, 'prev-failed': 0, 'code-changed-after-pass': 0, 'recheck-no-change': 0, 'pre-archive-recheck': 0, unspecified: 0 };
+}
+
 // ── 配置 ──────────────────────────────────────────────
 
 /** 获取项目的 skywalk-sdd 数据目录 */
@@ -89,11 +109,25 @@ function parseJsonOption(args, inlineKey, fileKey, projectRoot, fallback = {}) {
     return JSON.parse(inlineValue);
   }
   if (fileValue) {
-    return readJsonFile(fileValue, projectRoot);
+    const resolvedFileValue = normalizeDetailsFilePath(fileValue, projectRoot);
+    return readJsonFile(resolvedFileValue, projectRoot);
   }
   return fallback;
 }
 
+/** 规范化 details-file 路径：相对路径自动归一化到 skywalk-sdd/state/，避免污染项目根目录 */
+function normalizeDetailsFilePath(fileValue, projectRoot) {
+  if (!fileValue) return fileValue;
+  if (path.isAbsolute(fileValue)) return fileValue;
+  const normalized = fileValue.replace(/\\/g, '/');
+  // 已显式指向 skywalk-sdd/ 下任意目录 → 保持原样（兼容旧路径与新的 state/ 路径）
+  if (normalized.startsWith('skywalk-sdd/')) return fileValue;
+  // 默认写入 skywalk-sdd/state/，避免根目录污染
+  const stateDir = path.join(getDataDir(projectRoot), 'state');
+  ensureDir(stateDir);
+  return path.join(stateDir, path.basename(normalized));
+}
+
 function cleanOptionalFields(event) {
   for (const key of Object.keys(event)) {
     if (event[key] == null || event[key] === '') {
@@ -299,6 +333,9 @@ function scanTaskCompletionFromFiles(projectRoot, changeName, taskFiles) {
         completed += 1;
         fileCompleted += 1;
       } else if (/\[\s\]/.test(line)) {
+        // P2-1: `- [ ] 无` 是占位符（表示"无文档更新/无风险/无遗留"），不计入 incomplete
+        const afterCheckbox = line.replace(/^\s*-\s*\[\s\]\s*/, '').trim();
+        if (afterCheckbox === '无') return;
         incomplete += 1;
         fileIncomplete += 1;
         incompleteItems.push({
@@ -328,6 +365,18 @@ function scanTaskCompletionFromFiles(projectRoot, changeName, taskFiles) {
   };
 }
 
+// P0-3: 读取 check-result state 文件（check_result 事件 details 缺 consistency_score 时 fallback）
+function readCheckResultState(projectRoot, changeName) {
+  if (!projectRoot || !changeName) return null;
+  const statePath = path.join(projectRoot, 'skywalk-sdd', 'state', `check-result-${changeName}.json`);
+  if (!fs.existsSync(statePath)) return null;
+  try {
+    return JSON.parse(fs.readFileSync(statePath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
 function scanTaskCompletion(projectRoot, changeName) {
   const normalizedRoot = normalizeProjectRoot(projectRoot);
   const taskFiles = discoverTaskFiles(normalizedRoot, changeName);
@@ -343,7 +392,77 @@ function scanTaskCompletionForArchiveDir(projectRoot, changeName, archiveDir) {
   return scanTaskCompletionFromFiles(normalizedRoot, changeName, taskFiles);
 }
 
-function discoverFullSpecFiles(changeDir) {
+// ── check-task 子命令辅助函数 ─────────────────────────────
+
+/** 在 tasks.md 文件中定位并勾选指定 task_id 的 checkbox */
+function checkTaskInFile(filePath, taskId, dryRun = false) {
+  const content = fs.readFileSync(filePath, 'utf8');
+  const eol = content.includes('\r\n') ? '\r\n' : '\n';
+  const lines = content.split(/\r?\n/);
+  const escapedTaskId = taskId.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const taskHeaderRe = new RegExp(`^###\\s*\\[?${escapedTaskId}\\]?(?:\\s|$|\\])`);
+  let inTaskSection = false;
+  let changed = false;
+  const newLines = lines.map((line) => {
+    if (/^###\s/.test(line)) {
+      inTaskSection = taskHeaderRe.test(line);
+    }
+    if (inTaskSection && (/^\s*-\s*\[\s\]/.test(line) || /^\s*\*\*状态\*\*:\s*\[\s\]/.test(line))) {
+      changed = true;
+      return line.replace(/\[ \]/, '[x]');
+    }
+    return line;
+  });
+  if (changed && !dryRun) {
+    fs.writeFileSync(filePath, newLines.join(eol), 'utf8');
+  }
+  return { changed, linesChanged: changed ? 1 : 0 };
+}
+
+/** 同步执行 check-task：扫描变更目录下的 tasks.md 并勾选对应 task_id */
+function runCheckTaskSync(projectRoot, changeName, taskId, dryRun = false) {
+  const normalizedRoot = normalizeProjectRoot(projectRoot);
+  const taskFiles = discoverTaskFiles(normalizedRoot, changeName);
+  if (taskFiles.length === 0) {
+    throw new Error(`未找到 change ${changeName} 的 tasks.md`);
+  }
+  let totalChanged = 0;
+  const changedFiles = [];
+  for (const filePath of taskFiles) {
+    const result = checkTaskInFile(filePath, taskId, dryRun);
+    if (result.changed) {
+      totalChanged += 1;
+      changedFiles.push(path.relative(normalizedRoot, filePath).replace(/\\/g, '/'));
+    }
+  }
+  return { changed: totalChanged > 0, changed_files: changedFiles, task_files_checked: taskFiles.length };
+}
+
+/** check-task 子命令 CLI */
+function cmdCheckTask(args) {
+  const projectRoot = normalizeProjectRoot(args.project || args['project-root'] || process.cwd());
+  const changeName = args.change || args['change-name'];
+  const taskId = args['task-id'] || args.task_id;
+  const dryRun = Boolean(args['dry-run']) || Boolean(args.dry_run);
+
+  if (!changeName) {
+    console.error('错误: 缺少 --change 参数');
+    process.exit(1);
+  }
+  if (!taskId) {
+    console.error('错误: 缺少 --task-id 参数');
+    process.exit(1);
+  }
+
+  const result = runCheckTaskSync(projectRoot, changeName, taskId, dryRun);
+  console.log(JSON.stringify(result, null, 2));
+  if (!result.changed && !dryRun) {
+    process.exitCode = 1;
+  }
+  return result;
+}
+
+function discoverFullSpecFiles(changeDir, changeName = null) {
   const specsDir = path.join(changeDir, 'specs');
   const specs = [];
 
@@ -359,7 +478,8 @@ function discoverFullSpecFiles(changeDir) {
 
   const simpleSpecPath = path.join(changeDir, 'spec.md');
   if (fs.existsSync(simpleSpecPath)) {
-    specs.push({ capability: path.basename(changeDir), source: simpleSpecPath });
+    // M3/N8: simple 模式 capability 优先用原始 changeName（稳定标识），避免归档后 archiveDir 带日期前缀污染
+    specs.push({ capability: changeName || path.basename(changeDir), source: simpleSpecPath });
   }
 
   return specs.sort((a, b) => a.capability.localeCompare(b.capability));
@@ -382,9 +502,9 @@ function findArchivedChangeDir(projectRoot, changeName) {
   return candidates[0] || null;
 }
 
-function syncArchivedSpecs(projectRoot, archiveDir) {
+function syncArchivedSpecs(projectRoot, archiveDir, changeName) {
   const copiedSpecs = [];
-  const specFiles = discoverFullSpecFiles(archiveDir);
+  const specFiles = discoverFullSpecFiles(archiveDir, changeName);
 
   for (const spec of specFiles) {
     const targetSpec = path.join(projectRoot, 'openspec', 'specs', spec.capability, 'spec.md');
@@ -402,15 +522,24 @@ function syncArchivedSpecs(projectRoot, archiveDir) {
 
 function ensureArchiveManifest(projectRoot, changeName, archiveDir, options = {}) {
   const manifestPath = path.join(archiveDir, 'archive-manifest.json');
-  const copiedSpecs = syncArchivedSpecs(projectRoot, archiveDir);
+  const copiedSpecs = syncArchivedSpecs(projectRoot, archiveDir, changeName);
+  // U4: 归档时拷 events jsonl 进 archive/evidence/events/，报告可从归档目录重建（源数据与产物不再分离）
+  const eventsSrcDir = path.join(getDataDir(projectRoot), 'events', safeChangeName(changeName));
+  let evidenceEventsPath = null;
+  if (fs.existsSync(eventsSrcDir)) {
+    const eventsDstDir = path.join(archiveDir, 'evidence', 'events');
+    copyDirSync(eventsSrcDir, eventsDstDir);
+    evidenceEventsPath = toProjectRelative(projectRoot, eventsDstDir);
+  }
   const manifest = {
     change: changeName,
     archived_at: options.archivedAt || nowISO(),
-    reason: options.reason || '',
+    reason: options.reason || '变更已完成实施',
     method: options.method || 'skywalk-full-spec-archive',
     source_path: `openspec/changes/${changeName}`,
     archive_path: toProjectRelative(projectRoot, archiveDir),
     copied_specs: copiedSpecs,
+    evidence_events_path: evidenceEventsPath,
   };
   fs.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2) + '\n', 'utf8');
   return {
@@ -423,10 +552,7 @@ function ensureArchiveManifest(projectRoot, changeName, archiveDir, options = {}
 function ensureArchiveSuccessArtifacts(projectRoot, changeName, details = {}, options = {}) {
   const normalizedRoot = normalizeProjectRoot(projectRoot);
   const activeChangeDir = getChangeDir(normalizedRoot, changeName);
-  const archiveReason = details.archive_result?.reason || options.reason || '';
-  const reportPath = options.reportOutput
-    ? (path.isAbsolute(options.reportOutput) ? options.reportOutput : path.resolve(normalizedRoot, options.reportOutput))
-    : '';
+  let archiveReason = details.archive_result?.reason || options.reason || '变更已完成实施';
 
   let archiveDir = details.archive_result?.archive_path
     ? path.resolve(normalizedRoot, details.archive_result.archive_path)
@@ -444,21 +570,34 @@ function ensureArchiveSuccessArtifacts(projectRoot, changeName, details = {}, op
       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`);
+
+  // P2-2: task_completion 提前计算，has_incomplete 时调整归档原因
+  const taskCompletion = details.archive_result?.task_completion || scanTaskCompletionForArchiveDir(normalizedRoot, changeName, archiveDir);
+  if (taskCompletion?.has_incomplete && !details.archive_result?.reason) {
+    archiveReason = `部分完成（${taskCompletion.incomplete} 项验收未勾选）`;
+  }
   const manifestInfo = ensureArchiveManifest(normalizedRoot, changeName, archiveDir, {
     reason: archiveReason,
     method: archiveMethod || 'skywalk-full-spec-archive',
     archivedAt: details.archive_result?.archived_at || nowISO(),
   });
-  const taskCompletion = details.archive_result?.task_completion || scanTaskCompletionForArchiveDir(normalizedRoot, changeName, archiveDir);
 
   const archiveResult = {
     reason: archiveReason,
     method: manifestInfo.manifest.method,
     archive_path: manifestInfo.manifest.archive_path,
-    report_path: reportPath ? toProjectRelative(normalizedRoot, reportPath) : (details.archive_result?.report_path || ''),
+    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,
@@ -468,6 +607,7 @@ function ensureArchiveSuccessArtifacts(projectRoot, changeName, details = {}, op
     changed: true,
     archive_result: archiveResult,
     task_completion: taskCompletion,
+    reportPath,
   };
 }
 
@@ -494,8 +634,14 @@ function archiveChangeDocs(projectRoot, changeName, options = {}) {
   const archiveDir = nextAvailableDir(archiveRoot, `${archiveDate}-${changeName}`);
 
   copyDirSync(sourceDir, archiveDir);
+  // P2-2: 根据 task_completion 调整归档原因，has_incomplete 时不写"已完成实施"
+  const tcForReason = scanTaskCompletionForArchiveDir(normalizedRoot, changeName, archiveDir);
+  let archiveReason = options.reason || '变更已完成实施';
+  if (tcForReason?.has_incomplete) {
+    archiveReason = `部分完成（${tcForReason.incomplete} 项验收未勾选）`;
+  }
   const manifestInfo = ensureArchiveManifest(normalizedRoot, changeName, archiveDir, {
-    reason: options.reason || '',
+    reason: archiveReason,
     method: 'skywalk-full-spec-archive',
   });
   const manifest = manifestInfo.manifest;
@@ -522,6 +668,89 @@ function appendEvent(dataDir, changeName, event) {
   if (!fs.existsSync(file) || fs.statSync(file).size === 0) {
     throw new Error(`事件文件写入验证失败: ${file}`);
   }
+  appendMarkdownLog(dataDir, changeName, event);
+}
+
+/** 把 ISO 时间戳格式化为本地时区 `YYYY-MM-DD HH:mm:ss (UTC±HH:MM)`。
+ *  execution-log 面向人读，统一用本地时区 + 显式偏移标注，避免 UTC 裸值与用户体感差 8 小时（N9）。 */
+function formatLocalTimestamp(iso) {
+  const d = new Date(iso || '');
+  if (Number.isNaN(d.getTime())) return String(iso || '');
+  const pad = (n) => String(n).padStart(2, '0');
+  const local = `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())} ` +
+    `${pad(d.getHours())}:${pad(d.getMinutes())}:${pad(d.getSeconds())}`;
+  const offsetMin = -d.getTimezoneOffset();
+  const sign = offsetMin >= 0 ? '+' : '-';
+  const abs = Math.abs(offsetMin);
+  return `${local} (UTC${sign}${pad(Math.floor(abs / 60))}:${pad(abs % 60)})`;
+}
+
+/** 把事件同步追加为人读 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);
+    // Q1: 未 openspec new change 前（无 .openspec.yaml 且无 archive-manifest.json）不创建 logs/，避免 propose 残留误报
+    const hasChangeMarker = fs.existsSync(path.join(activeChangeDir, '.openspec.yaml'))
+      || fs.existsSync(path.join(activeChangeDir, 'archive-manifest.json'));
+    if (!hasChangeMarker && !fs.existsSync(activeChangeDir)) {
+      // 目录本身不存在，检查是否为已归档变更
+      const archiveDir = findArchivedChangeDir(projectRoot, changeName);
+      if (!archiveDir) return; // 未 init 且未归档 → 跳过 logs/ 创建
+      const archiveLogsDir = path.join(archiveDir, 'logs');
+      ensureDir(archiveLogsDir);
+      const file = path.join(archiveLogsDir, 'execution-log.md');
+      if (!fs.existsSync(file) || fs.statSync(file).size === 0) {
+        const created = formatLocalTimestamp(event.timestamp || nowISO());
+        fs.writeFileSync(file, `# 执行日志 — ${changeName}\n\n> 变更创建时间：${created} | 变更名：${changeName}\n\n---\n\n`, 'utf8');
+      }
+      const ts = formatLocalTimestamp(event.timestamp || nowISO());
+      const stage = event.command || event.stage || 'unknown';
+      const summary = String(event.summary || '').replace(/\|/g, '/').replace(/\n/g, ' ');
+      if (event.type === 'process_note') {
+        const kind = event.details?.kind || 'note';
+        const target = event.details?.target ? ` → ${String(event.details.target).replace(/\|/g, '/')}` : '';
+        const round = Number.isFinite(event.details?.round) ? ` R${event.details.round}` : '';
+        fs.appendFileSync(file, `- [${ts}] ${stage} 📝 ${kind}${round} | ${summary}${target}\n`, 'utf8');
+        return;
+      }
+      const type = event.type || 'event';
+      const result = event.result || '';
+      const mark = RESULT_MARK[result] || '📝';
+      fs.appendFileSync(file, `- [${ts}] ${stage} ${type} → ${mark}${result ? '(' + result + ')' : ''} | ${summary}\n`, 'utf8');
+      return;
+    }
+    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 = formatLocalTimestamp(event.timestamp || nowISO());
+      fs.writeFileSync(file, `# 执行日志 — ${changeName}\n\n> 变更创建时间：${created} | 变更名：${changeName}\n\n---\n\n`, 'utf8');
+    }
+    const ts = formatLocalTimestamp(event.timestamp || nowISO());
+    const stage = event.command || event.stage || 'unknown';
+    const summary = String(event.summary || '').replace(/\|/g, '/').replace(/\n/g, ' ');
+    // process_note 渲染为带 kind/round 的叙事行（U2 叙事信号源 + U3 修复可追溯）
+    if (event.type === 'process_note') {
+      const kind = event.details?.kind || 'note';
+      const target = event.details?.target ? ` → ${String(event.details.target).replace(/\|/g, '/')}` : '';
+      const round = Number.isFinite(event.details?.round) ? ` R${event.details.round}` : '';
+      fs.appendFileSync(file, `- [${ts}] ${stage} 📝 ${kind}${round} | ${summary}${target}\n`, 'utf8');
+      return;
+    }
+    const type = event.type || 'event';
+    const result = event.result || '';
+    const mark = RESULT_MARK[result] || '📝';
+    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 的所有事件 */
@@ -659,8 +888,40 @@ function computeChangeMetrics(changeName, events) {
   const agentTypes = [...new Set(changeEvents.filter(e => e.agent_type).map(e => e.agent_type))];
   const isCompleted = !!archiveEnd;
 
+  // ── 变更摘要（execution-log 与报告共用，消除 1 vs 2 不一致；T1.3 + T4.4） ──
+  const stageStartCount = starts.length;
+  const stageEndCount = ends.length;
+  const distinctStartStages = new Set(starts.map((e) => e.command)).size;
+  const stageRepeatCount = Math.max(0, stageStartCount - distinctStartStages);
+  // A2(v3): 过滤空壳 test_result（passed=0 && failed=0 && duration_ms<=0/null），
+  // 只在真实测试结果中取最新一条。todo-cli 场景：claude-hook 空壳占位 + 真实 19/0 混合时，
+  // 旧逻辑取最晚空壳 → test_pass={0,0} 或 stage_end(无数值) → null，掩盖真实通过率。
+  // 不复用 isRealTestDetails（其要求 command 非空，会误过滤无 command 的真实 test_result）
+  const realTestEvents = testEvents.filter(e => {
+    const r = getTestResults(e);
+    if (!r) return false;
+    return r.passed > 0 || r.failed > 0 || (Number.isFinite(r.duration_ms) && r.duration_ms > 0);
+  });
+  const latestTestEvent = realTestEvents.length > 0 ? latestByTimestamp(realTestEvents) : null;
+  const latestTestResults = latestTestEvent ? getTestResults(latestTestEvent) : null;
+  const testPassSummary = latestTestResults
+    ? { passed: Number(latestTestResults.passed) || 0, failed: Number(latestTestResults.failed) || 0 }
+    : null;
+  const effectiveStageDurationMs = ends.reduce((s, e) => s + (Number(e.duration_ms) || 0), 0);
+  const idleTimeMs = changeLeadTime != null
+    ? Math.max(0, changeLeadTime - effectiveStageDurationMs)
+    : null;
+
   return {
     change: changeName,
+    change_summary: {
+      stage_start_count: stageStartCount,
+      stage_end_count: stageEndCount,
+      stage_repeat_count: stageRepeatCount,
+      test_pass: testPassSummary,
+      effective_stage_duration_ms: effectiveStageDurationMs,
+      idle_time_ms: idleTimeMs,
+    },
     process_health: {
       critical_path_coverage: criticalPathCoverage,
       covered_core_stages: coveredCoreStages,
@@ -682,9 +943,12 @@ function computeChangeMetrics(changeName, events) {
       apply_test_fix_cycles: applyCount,
       coverage_trend: coverageTrend,
       q1_spec_conformance_score: conformanceMetrics.q1_spec_conformance_score,
+      q1_human_status: conformanceMetrics.human_status,
       q4_spec_driven_test_coverage: specTestCoverageMetrics.q4_spec_driven_test_coverage,
       conformance_counts: conformanceMetrics.conformance_counts,
-      conformance_manual_confirmed: conformanceMetrics.manual_confirmed,
+      conformance_agent_confirmed: conformanceMetrics.agent_confirmed,
+      conformance_reviewer: conformanceMetrics.reviewer,
+      conformance_reviewer_independence: conformanceMetrics.reviewer_independence,
       spec_test_scenario_counts: specTestCoverageMetrics.scenario_counts,
       p2_ai_code_adoption_rate: aiAdoptionMetrics.p2_ai_code_adoption_rate,
       ai_adoption_level: aiAdoptionMetrics.adoption_level,
@@ -856,6 +1120,7 @@ function createReworkBucket(command, capability) {
     superseded_open_stages: 0,
     unresolved_open_stages: 0,
     rework_duration_ms: 0,
+    reasons_by_category: createReasonCategory(),
   };
 }
 
@@ -873,6 +1138,8 @@ function summarizeStageExecutions(events) {
     endsById.get(end.event_id).push(end);
   }
 
+  // N4: event_id 配对——cmdStart 默认每次生成新 event_id，cmdEnd 用 --event-id 配对；
+  // 若手动传同 --event-id 重跑 start 会产出同 id 多 start，配对脆弱（两个 attempt 共享同一 end）。cmdStart 默认行为已规避。
   const attempts = starts.map(start => {
     const end = latestByTimestamp(endsById.get(start.event_id) || []);
     return {
@@ -904,12 +1171,10 @@ function summarizeStageExecutions(events) {
   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;
-      })
+    // canonical：同 key 取最晚 end 的 attempt（不限 result，含 partial/failure）—— 全 partial 场景也需 canonical 驱动 rework 判定
+    const endedAttempts = groupAttempts.filter(attempt => attempt.end);
+    const canonical = endedAttempts.length
+      ? endedAttempts.reduce((a, b) => timestampMs(a.end) >= timestampMs(b.end) ? a : b)
       : null;
     if (canonical) {
       canonical.canonical = true;
@@ -930,7 +1195,17 @@ function summarizeStageExecutions(events) {
       if (attempt === canonical) continue;
 
       if (canonical && timestampMs(attempt.start) <= timestampMs(canonical.end || canonical.start)) {
-        attempt.rework_reason = attempt.end ? 'completed_rework' : 'superseded_open';
+        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.result === 'partial') {
+          attempt.rework_reason = 'prev-failed';
+        } else if (canonical.result !== 'success') {
+          attempt.rework_reason = 'prev-failed';
+        } else {
+          attempt.rework_reason = 'completed_rework_success';
+        }
         reworkAttempts.push(attempt);
         bucket.rework_attempts += 1;
         if (attempt.end) {
@@ -1020,7 +1295,7 @@ function getFormalStageRelatedEvents(events, attempt, predicate) {
   return [];
 }
 
-function compactReworkSummary(summary) {
+function compactReworkSummary(summary, reasons) {
   return {
     total_attempts: summary.total_attempts,
     canonical_attempts: summary.canonical_attempts,
@@ -1032,7 +1307,95 @@ function compactReworkSummary(summary) {
     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';
+        }
+      }
+    }
+    // T3.6 + Q6: check 在 test 之后重跑（归档前强制复检）→ pre-archive-recheck（不论原 reason）
+    // 判定：attempt 为 check 且 check 的 canonical 开始时间晚于 test 的 canonical 结束时间 → 归档前强制复检
+    if (attempt.command === 'check') {
+      const canonicalCheck = getCanonicalAttempt(executionSummary, 'check', attempt.capability);
+      // Y2 修复：test 也传 capability 避免跨 capability 取到错误 canonical（summarizeStageExecutions 按 command|capability 分桶）
+      const canonicalTest = getCanonicalAttempt(executionSummary, 'test', attempt.capability);
+      if (canonicalCheck && canonicalCheck.start && canonicalTest && canonicalTest.end
+          && timestampMs(canonicalCheck.start) > timestampMs(canonicalTest.end)) {
+        reason = 'pre-archive-recheck';
+      }
+    }
+    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) {
@@ -1124,32 +1487,70 @@ function getTaskUpdateResult(event) {
   if (!event || event.type !== 'task_update') return null;
   const build = getBuildResults(event);
   const test = getTestResults(event);
+  const taskKind = event?.details?.task_kind || event?.task_kind || null;
+  // P3: TDD 测试骨架任务（task_kind='test-skeleton'）的红灯是预期（实现尚未编写），
+  // failed>0 不计为成码失败；骨架按 TDD 节奏完成即视为一次成码，避免 E4 系统性失真。
+  if (taskKind === 'test-skeleton') {
+    return {
+      task_id: event.task_id || null,
+      task_kind: taskKind,
+      success: true,
+      build,
+      test,
+    };
+  }
   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);
+  // Q3: 三信号均 null 时，若 status=completed 则兜底 success=true（agent 只记 status 也算 E4）
+  const statusOk = event.status === 'completed' || event.details?.status === 'completed';
   return {
     task_id: event.task_id || null,
-    success: signals.length > 0 ? signals.every(Boolean) : null,
+    task_kind: taskKind,
+    success: signals.length > 0 ? signals.every(Boolean) : (statusOk ? true : null),
     build,
     test,
   };
 }
 
 function computeAiFirstPassMetrics(events) {
+  // 仅对 implementation 任务计算一次成码率；test-skeleton 不计入分母
+  // 未显式 task_kind 的 legacy 事件视为 implementation，保持向后兼容
   const taskEvents = events
-    .filter(e => e.type === 'task_update' && e.task_id)
+    .filter(e => {
+      if (e.type !== 'task_update' || !e.task_id) return false;
+      const taskKind = e.details?.task_kind || e.task_kind;
+      if (taskKind === 'test-skeleton') return false;
+      return !taskKind || taskKind === 'implementation';
+    })
     .sort((a, b) => new Date(a.timestamp).getTime() - new Date(b.timestamp).getTime());
-  const firstByTask = new Map();
+
+  // A3(v3): 从 telemetry_warning(task_update_reuse) 提取复用 task_ids，
+  // 被标记 task 不计入 first_pass 分子（分母不变）→ E4 反映复用扣分。
+  // 旧 warning 无 details.task_ids → 不扣分（向后兼容）
+  const reusedTaskIds = new Set();
+  for (const e of events) {
+    if (e?.type !== 'telemetry_warning') continue;
+    if (e.details?.warning !== 'task_update_reuse') continue;
+    const ids = e.details?.task_ids;
+    if (Array.isArray(ids)) {
+      for (const id of ids) { if (id) reusedTaskIds.add(id); }
+    }
+  }
+
+  // 按 task_id 取最终结果（时间最晚）
+  const finalByTask = new Map();
   for (const event of taskEvents) {
-    if (!firstByTask.has(event.task_id)) {
-      firstByTask.set(event.task_id, event);
+    const existing = finalByTask.get(event.task_id);
+    if (!existing || new Date(event.timestamp).getTime() > new Date(existing.timestamp).getTime()) {
+      finalByTask.set(event.task_id, event);
     }
   }
 
-  const taskResults = Array.from(firstByTask.values())
+  const taskResults = Array.from(finalByTask.values())
     .map(getTaskUpdateResult)
     .filter(result => result?.success != null);
   if (taskResults.length === 0) {
@@ -1158,15 +1559,23 @@ function computeAiFirstPassMetrics(events) {
       first_pass_tasks: 0,
       measured_tasks: 0,
       failed_tasks: [],
+      test_skeleton_tasks: 0,
+      reused_task_ids: Array.from(reusedTaskIds),
+      e4_reuse_impacted: false,
     };
   }
 
-  const passedTasks = taskResults.filter(result => result.success);
+  // A3(v3): 被复用标记的 task 从分子扣除（仍计入分母）→ E4 下降而非归零
+  const passedTasks = taskResults.filter(result => result.success && !reusedTaskIds.has(result.task_id));
+  const e4ReuseImpacted = reusedTaskIds.size > 0 && taskResults.some(r => reusedTaskIds.has(r.task_id));
   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),
+    test_skeleton_tasks: 0,
+    reused_task_ids: Array.from(reusedTaskIds),
+    e4_reuse_impacted: e4ReuseImpacted,
   };
 }
 
@@ -1239,23 +1648,39 @@ function computeSpecTestCoverageMetrics(events) {
   const coverageEvents = getSpecTestCoverageEvents(events);
   const latestCoverageEvent = latestByTimestamp(coverageEvents);
   const coverage = getSpecTestCoverage(latestCoverageEvent);
-  if (!coverage) {
+  if (coverage) {
+    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,
+      source: 'spec_test_coverage',
+    };
+  }
+  // P4: 无 spec_test_coverage 事件时，fallback 到 conformance_review 断言覆盖率（近似值，标注 source）
+  const confReview = getConformanceReview(latestByTimestamp(getConformanceReviewEvents(events)));
+  if (confReview && confReview.total > 0) {
     return {
-      q4_spec_driven_test_coverage: null,
-      scenario_counts: { total: 0, covered: 0, partial: 0, uncovered: 0 },
+      q4_spec_driven_test_coverage: roundMetric((confReview.matched + confReview.partial * 0.5) / confReview.total),
+      scenario_counts: {
+        total: confReview.total,
+        covered: confReview.matched,
+        partial: confReview.partial,
+        uncovered: confReview.missed,
+      },
       latest_review_at: null,
+      source: 'conformance-fallback',
     };
   }
-
   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,
+    q4_spec_driven_test_coverage: null,
+    scenario_counts: { total: 0, covered: 0, partial: 0, uncovered: 0 },
+    latest_review_at: null,
+    source: null,
   };
 }
 
@@ -1268,7 +1693,7 @@ function normalizeConformanceStatus(value) {
   return null;
 }
 
-function getConformanceReview(event) {
+function getConformanceReview(event, applyAgentType) {
   const review = event?.details?.conformance_review || event?.details?.conformance;
   if (!review) return null;
 
@@ -1295,6 +1720,13 @@ function getConformanceReview(event) {
   const total = matched + partial + missed;
   const computedScore = total > 0 ? roundMetric((matched + partial * 0.5) / total) : null;
 
+  // reviewer 字段：优先取 review.reviewer，否则 fallback 到事件 agent_type
+  const reviewer = review.reviewer || event?.agent_type || event?.source || null;
+  let reviewerIndependence = null;
+  if (reviewer && applyAgentType) {
+    reviewerIndependence = reviewer === applyAgentType ? 'self-review' : 'independent-review';
+  }
+
   return {
     total,
     matched,
@@ -1302,8 +1734,11 @@ function getConformanceReview(event) {
     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),
+    reviewer,
+    reviewer_independence: reviewerIndependence,
+    // T3.4/T3.5: review 级 human_status — 仅当真实人工评审（review.human_status==='matched'）才 matched，否则 unverified（AI 自评）
+    human_status: review.human_status === 'matched' ? 'matched' : 'unverified',
+    agent_confirmed: review.agent_confirmed === true || review.manual_confirmed === true || normalizedAssertions.some(a => a.human_status),
     assertions: normalizedAssertions,
   };
 }
@@ -1319,12 +1754,19 @@ function getConformanceReviewEvents(events) {
 function computeConformanceMetrics(events) {
   const reviewEvents = getConformanceReviewEvents(events);
   const latestReviewEvent = latestByTimestamp(reviewEvents);
-  const latestReview = getConformanceReview(latestReviewEvent);
+  // 取 apply 阶段最新的 agent_type 作为 reviewer 独立性比较基准
+  const applyEvents = events.filter(e => !e.orphan && (e.command === 'apply' || e.stage === 'apply'));
+  const latestApply = latestByTimestamp(applyEvents);
+  const applyAgentType = latestApply?.agent_type || latestApply?.agent;
+  const latestReview = getConformanceReview(latestReviewEvent, applyAgentType);
   if (!latestReview) {
     return {
       q1_spec_conformance_score: null,
       conformance_counts: { total: 0, matched: 0, partial: 0, missed: 0 },
-      manual_confirmed: false,
+      agent_confirmed: false,
+      reviewer: null,
+      reviewer_independence: null,
+      human_status: null,
       latest_review_at: null,
     };
   }
@@ -1337,13 +1779,17 @@ function computeConformanceMetrics(events) {
       partial: latestReview.partial,
       missed: latestReview.missed,
     },
-    manual_confirmed: latestReview.manual_confirmed,
+    agent_confirmed: latestReview.agent_confirmed,
+    reviewer: latestReview.reviewer,
+    reviewer_independence: latestReview.reviewer_independence,
+    human_status: latestReview.human_status,
     latest_review_at: latestReviewEvent.timestamp || null,
   };
 }
 
 function getAiAdoptionReview(event) {
-  const review = event?.details?.ai_adoption || event?.details?.ai_code_adoption;
+  // Q4: 兼容三 key（ai_adoption / ai_code_adoption / ai_adoption_review）
+  const review = event?.details?.ai_adoption || event?.details?.ai_code_adoption || event?.details?.ai_adoption_review;
   if (!review) return null;
 
   const retainedLines = Number.isFinite(review.retained_lines) ? review.retained_lines : null;
@@ -1385,7 +1831,8 @@ function getAiAdoptionEvents(events) {
   return events.filter(e => {
     return e.type === 'ai_adoption_review'
       || Boolean(e.details?.ai_adoption)
-      || Boolean(e.details?.ai_code_adoption);
+      || Boolean(e.details?.ai_code_adoption)
+      || Boolean(e.details?.ai_adoption_review);
   });
 }
 
@@ -1527,16 +1974,41 @@ function computeGitDocumentMetrics(projectRoot, changeName) {
 
   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 仓库，无法统计文档迭代'],
-    };
+    // 无 git 时 fallback 到 doc_update 事件按文件去重计数，并标注 source
+    try {
+      const dataDir = getDataDir(projectRoot);
+      const events = readEvents(dataDir, changeName);
+      const docFiles = new Set();
+      for (const e of events) {
+        if (e.type === 'doc_update' && e.change === changeName && e.details && e.details.file) {
+          docFiles.add(e.details.file);
+        }
+      }
+      const iterationCount = docFiles.size > 0 ? docFiles.size : null;
+      return {
+        git_available: false,
+        spec_iteration_count: iterationCount,
+        document_commit_count: iterationCount,
+        total_added_lines: null,
+        total_deleted_lines: null,
+        files: createDocFileMetrics(),
+        diff_trend: [],
+        source: iterationCount != null ? 'event-fallback' : null,
+        warnings: ['当前项目不是 Git 仓库，已 fallback 到 doc_update 事件按文件去重计数'],
+      };
+    } catch (err) {
+      return {
+        git_available: false,
+        spec_iteration_count: null,
+        document_commit_count: null,
+        total_added_lines: null,
+        total_deleted_lines: null,
+        files: createDocFileMetrics(),
+        diff_trend: [],
+        source: null,
+        warnings: ['当前项目不是 Git 仓库，无法统计文档迭代'],
+      };
+    }
   }
 
   const changePath = `openspec/changes/${changeName}`;
@@ -1630,6 +2102,7 @@ function computeSinglePdfMvpMetrics(events, options = {}) {
     .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);
 
@@ -1660,16 +2133,20 @@ function computeSinglePdfMvpMetrics(events, options = {}) {
     return getCheckResults(e)?.consistency_score != null;
   }));
   const latestCheckResults = getCheckResults(latestCheckWithScore);
+  // P0-3: check_result 事件 details 缺 consistency_score 时，fallback 读 state/check-result-<change>.json
+  const consistencyFromState = !latestCheckResults && options.projectRoot && options.change
+    ? (readCheckResultState(options.projectRoot, options.change)?.check_results?.consistency_score ?? null)
+    : null;
+  const consistencyScore = latestCheckResults?.consistency_score ?? consistencyFromState ?? null;
 
-  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;
+  // N5: 无 Git 提交历史时 P1=null（不适用），不再 fallback 到阶段 start 数（阶段数≠迭代次数，语义错误）
   const specIterationCount = gitDocumentMetrics?.spec_iteration_count != null
     ? gitDocumentMetrics.spec_iteration_count
-    : stageSpecIterationCount;
+    : null;
+  const specIterationSource = gitDocumentMetrics?.source || (gitDocumentMetrics?.git_available ? 'git' : null);
 
   const firstApply = firstByTimestamp(starts.filter(e => e.command === 'apply'));
   const qualityGateBeforeApply = firstApply
@@ -1680,9 +2157,10 @@ function computeSinglePdfMvpMetrics(events, options = {}) {
     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));
+  // Q2: P4 主指标改为"apply 前是否 check"（布尔→1/0），不再依赖 fixRateResults
+  // fixed_before_apply/total 作为辅助指标 p4b_check_fixed_rate，不覆盖 P4
+  const qualityGateRate = qualityGateBeforeApply == null ? null : (qualityGateBeforeApply ? 1 : 0);
+  const fixRate = fixRateResults ? roundMetric(fixRateResults.fixed_before_apply / fixRateResults.total) : null;
   const conformanceMetrics = computeConformanceMetrics(scopedEvents);
   const aiAdoptionMetrics = computeAiAdoptionMetrics(formalApplyEvents.length > 0 ? formalApplyEvents : scopedEvents);
   const aiFirstPassMetrics = computeAiFirstPassMetrics(formalApplyEvents.length > 0 ? formalApplyEvents : scopedEvents);
@@ -1695,6 +2173,9 @@ function computeSinglePdfMvpMetrics(events, options = {}) {
       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,
+      idle_time_ms: leadTime != null && executionSummary.summary.effective_stage_duration_ms != null
+        ? Math.max(0, leadTime - executionSummary.summary.effective_stage_duration_ms)
+        : null,
       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
@@ -1706,21 +2187,27 @@ function computeSinglePdfMvpMetrics(events, options = {}) {
     },
     quality: {
       q1_spec_conformance_score: conformanceMetrics.q1_spec_conformance_score,
+      q1_human_status: conformanceMetrics.human_status,
       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,
+      q4_source: specTestCoverageMetrics.source,
+      q5_cross_doc_consistency_score: consistencyScore,
       conformance_counts: conformanceMetrics.conformance_counts,
-      conformance_manual_confirmed: conformanceMetrics.manual_confirmed,
+      conformance_agent_confirmed: conformanceMetrics.agent_confirmed,
+      conformance_reviewer: conformanceMetrics.reviewer,
+      conformance_reviewer_independence: conformanceMetrics.reviewer_independence,
       spec_test_scenario_counts: specTestCoverageMetrics.scenario_counts,
     },
     process: {
       p1_spec_iteration_count: specIterationCount,
+      p1_spec_iteration_source: specIterationSource,
       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,
+      p4b_check_fixed_rate: fixRate,
       git_document_metrics: gitDocumentMetrics,
-      rework_summary: compactReworkSummary(executionSummary.summary),
+      rework_summary: compactReworkSummary(executionSummary.summary, reworkReasons),
     },
     manual_insights: computeManualInsightMetrics(scopedEvents),
     telemetry_health: computeTelemetryHealthMetrics(scopedEvents),
@@ -1787,6 +2274,7 @@ function computePdfMvpMetrics(events, options = {}) {
       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),
+      idle_time_ms: averageMetric(changeMetrics, m => m.efficiency.idle_time_ms),
     },
     quality: {
       q1_spec_conformance_score: averageMetric(changeMetrics, m => m.quality.q1_spec_conformance_score),
@@ -1844,9 +2332,36 @@ function renderPdfMvpMarkdown(metrics) {
   ].join('\n');
 }
 
+function formatMsHuman(ms) {
+  if (ms == null) return 'null';
+  if (ms < 60000) return `${(ms / 1000).toFixed(2)} s`;
+  if (ms < 3600000) return `≈${Math.round(ms / 60000)}分钟`;
+  return `≈${Math.floor(ms / 3600000)}小时${Math.round((ms % 3600000) / 60000)}分钟`;
+}
+
+/**
+ * 格式化毫秒为秒数 + 人类可读时长
+ * 输出格式：`{秒} s（{人类可读}）`，例如 `4482.91 s（≈1小时15分钟）`
+ * ⚠️ 非向后兼容变更：旧版本仅输出 `{秒} s`，新版本追加人类可读括号。
+ *    如有下游脚本解析此输出，需适配新的括号格式。
+ */
 function formatMsToSeconds(ms) {
   if (ms == null) return 'null';
-  return `${(ms / 1000).toFixed(2)} s`;
+  return `${(ms / 1000).toFixed(2)} s（${formatMsHuman(ms)}）`;
+}
+
+/**
+ * 格式化毫秒为分钟（HTML 报告时间单位用）。返回 { minutes, sub } 或 null。
+ * <60 分钟：sub=null（只显示「N 分钟」）；≥60 分钟：sub="≈X小时Y分钟"。
+ * 例如 3931000ms → { minutes:66, sub:"≈1小时6分钟" }；1762000ms → { minutes:29, sub:null }。
+ */
+function formatDuration(ms) {
+  if (ms == null || !Number.isFinite(ms)) return null;
+  const minutes = Math.round(ms / 60000);
+  if (minutes < 60) return { minutes, sub: null };
+  const hours = Math.floor(minutes / 60);
+  const mins = minutes % 60;
+  return { minutes, sub: `≈${hours}小时${mins}分钟` };
 }
 
 function formatRatioToPercent(ratio) {
@@ -1854,6 +2369,16 @@ function formatRatioToPercent(ratio) {
   return `${(ratio * 100).toFixed(1)}%`;
 }
 
+function formatReworkReasons(reasons) {
+  if (!reasons || !reasons.by_category) return 'null';
+  return REWORK_REASON_CATEGORIES.map(c => `${REWORK_REASON_CN[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} → ${REWORK_REASON_CN[d.reason] || 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;
@@ -1862,35 +2387,84 @@ function renderExecutiveReportMarkdown(report) {
   return [
     `# SDD 效果度量报告${report.change ? ` - ${report.change}` : ''}`,
     '',
-    `- 生成时间：${report.generated_at}`,
-    `- 项目路径：${report.project_root}`,
+    `- 生成时间：${formatLocalTimestamp(report.generated_at)}`,
+    `- 项目路径：${report.project_root ? String(report.project_root).replace(/[\\/]+$/, '').split(/[\\/]/).pop() : 'null'}`,
     `- 统计范围：${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}（存在未闭环阶段、孤儿事件或未知命令等阻断级问题的数量）`,
+    `- 严重问题数：${health.severe_issues?.length ?? '无数据'}（存在未闭环阶段、孤儿事件或未知命令等阻断级问题的数量）`,
     '',
     '## 效率指标',
     `- E1 需求到归档总时长：${formatMsToSeconds(metrics.efficiency?.e1_lead_time_ms)}`,
-    `- E2 编码时间占比：${formatRatioToPercent(metrics.efficiency?.e2_coding_time_ratio)}`,
+    `- E2 编码时间占比：${formatRatioToPercent(metrics.efficiency?.e2_coding_time_ratio)}（仅 apply 阶段；test 阶段耗时另见有效阶段总耗时）`,
     `- E3 规约时间占比：${formatRatioToPercent(metrics.efficiency?.e3_spec_time_ratio)}`,
-    `- E4 AI 一次成码率：${formatRatioToPercent(metrics.efficiency?.e4_ai_code_first_pass_rate)}`,
+    `- E4 AI 一次成码率：${formatRatioToPercent(metrics.efficiency?.e4_ai_code_first_pass_rate)}（基于 task_update 信号判定，非代码 diff）${report.telemetry_warnings?.by_type?.task_update_reuse > 0 ? '（E4 受 task_update 复用影响，已扣分）' : ''}`,
     `- 有效阶段总耗时：${formatMsToSeconds(metrics.efficiency?.effective_stage_duration_ms)}`,
-    `- 返工阶段总耗时：${formatMsToSeconds(metrics.efficiency?.rework_stage_duration_ms)}`,
+    `- 阶段间等待：${formatMsToSeconds(metrics.efficiency?.idle_time_ms)}`,
+    `- 流程修正阶段总耗时：${formatMsToSeconds(metrics.efficiency?.rework_stage_duration_ms)}`,
     '',
     '## 质量指标',
-    `- Q1 规约符合度：${metrics.quality?.q1_spec_conformance_score ?? 'null'}`,
+    `- Q1 规约符合度：${metrics.quality?.q1_spec_conformance_score ?? 'null'}${metrics.quality?.q1_human_status === 'unverified' ? '（自评，待人工确认）' : ''}`,
     `- 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'}`,
+    `- Q4 规约驱动测试覆盖率：${formatRatioToPercent(metrics.quality?.q4_spec_driven_test_coverage)}${metrics.quality?.q4_source === 'conformance-fallback' ? '（近似自 conformance_review）' : ''}`,
+    `- Q5 跨文档一致性得分：${metrics.quality?.q5_cross_doc_consistency_score ?? 'null'}（取最新 check 的 consistency_score）`,
     '',
     '## 过程指标',
-    `- P1 文档迭代次数：${metrics.process?.p1_spec_iteration_count ?? 'null'}`,
+    `- P1 文档迭代次数：${metrics.process?.p1_spec_iteration_count ?? 'null'}${metrics.process?.p1_spec_iteration_source ? `（来源：${metrics.process.p1_spec_iteration_source}）` : ''}`,
     `- 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'}`,
+    `- 阶段重复执行次数：${metrics.process?.rework_summary?.total_rework_attempts ?? 'null'}`,
+    `- 被覆盖的未闭环阶段数：${metrics.process?.rework_summary?.superseded_open_stages ?? 'null'}（start 后未 end，被后续成功执行覆盖）`,
+    `- 重复执行原因分布：${formatReworkReasons(metrics.process?.rework_summary?.reasons)}`,
+    ...formatReworkReasonDetails(metrics.process?.rework_summary?.reasons),
+    '',
+    '## 变更文件',
+    `- 数据可用：${report.changed_files?._available ? '是' : '否'}`,
+    `- 变更文件数：${report.changed_files?.files_changed ?? 'null'}${report.changed_files?.files_diff_note ? `（${report.changed_files.files_diff_note}）` : ''}`,
+    `- 新增行数：${report.changed_files?.added_lines ?? 'null'}`,
+    `- 文件清单：${Array.isArray(report.changed_files?.files) ? report.changed_files.files.join(', ') : 'null'}`,
+    '',
+    '## 时间线',
+    ...(report.timeline?._available && Array.isArray(report.timeline.nodes) && report.timeline.nodes.length > 0
+      ? report.timeline.nodes.map(n => `- ${formatLocalTimestamp(n.timestamp)} [${n.type}] ${n.command || ''}${n.result ? ` → ${n.result}` : ''}`)
+      : ['- 无时间线节点（数据不可用）']),
+    '',
+    '## 阶段状态',
+    ...(report.stage_status?._available && Array.isArray(report.stage_status.stages) && report.stage_status.stages.length > 0
+      ? report.stage_status.stages.map(s => `- ${s.command}${s.capability ? `/${s.capability}` : ''}：尝试 ${s.total_attempts} 次，成功 ${s.successful_attempts}，重复执行 ${s.rework_attempts}`)
+      : ['- 无阶段状态数据（数据不可用）']),
+    '',
+    '## 已知风险',
+    `- 数据可用：${report.known_risks?._available ? '是' : '否'}`,
+    `- 严重问题数：${report.known_risks?._available ? (report.known_risks.severe_issues?.length ?? 0) : '无数据'}`,
+    ...(Array.isArray(report.known_risks?.warnings) && report.known_risks.warnings.length > 0
+      ? report.known_risks.warnings.flatMap(w => {
+          // T2.4: 渲染 warning_items 明细；旧事件无 items 时降级为数量（DC-101）
+          const items = Array.isArray(w.items) ? w.items : null;
+          const count = items ? items.length : (w.warnings || 0);
+          // Q7: 标注已修复/待确认
+          const statusLabel = w.resolved === true ? '✅已修复' : '⏳待确认';
+          const head = `- 警告：${w.command || 'check'} 阶段 ${count} 个${statusLabel}`;
+          if (!items || items.length === 0) return [`${head}（无明细）`];
+          return [head, ...items.map(it => `  - ${it.description || '待确认项'}${it.target ? `（${it.target}）` : ''}`)];
+        })
+      : ['- 无警告']),
+    '',
+    '## 过程记录',
+    `- 数据可用：${report.process_notes?._available ? '是' : '否'}`,
+    `- 过程事件总数：${report.process_notes?.total ?? 'null'}`,
+    `- 按 kind 分布：${report.process_notes?.by_kind ? JSON.stringify(report.process_notes.by_kind) : 'null'}`,
+    ...(Array.isArray(report.process_notes?.notes) && report.process_notes.notes.length > 0
+      ? report.process_notes.notes.map(n => `- [${n.stage}] ${n.kind}${n.round ? ` R${n.round}` : ''}：${n.summary}${n.target ? ` → ${n.target}` : ''}`)
+      : ['- 无过程事件']),
+    '',
+    '## 产物清单',
+    `- 数据可用：${report.artifacts?._available ? '是' : '否'}`,
+    `- 归档目录：${report.artifacts?.archive_path ?? 'null'}`,
+    `- 归档清单：${report.artifacts?.manifest_path ?? 'null'}`,
+    `- 迁移文件数：${Array.isArray(report.artifacts?.copied_specs) ? report.artifacts.copied_specs.length : 'null'}`,
     '',
     '## 归档结果',
     `- 归档原因：${archive?.reason || 'null'}`,
@@ -1898,37 +2472,674 @@ function renderExecutiveReportMarkdown(report) {
     `- 归档目录：${archive?.archive_path || 'null'}`,
     `- 归档清单：${archive?.manifest_path || 'null'}`,
     `- 最终报告：${archive?.report_path || 'null'}`,
-    `- 已完成任务项：${taskCompletion?.completed ?? 'null'}`,
-    `- 未勾选任务项：${taskCompletion?.incomplete ?? 'null'}`,
-    `- 任务项总数：${taskCompletion?.total ?? 'null'}`,
+    `- 已完成任务项（含子项 checkbox）：${taskCompletion?.completed ?? 'null'}`,
+    `- 未勾选任务项（含子项 checkbox）：${taskCompletion?.incomplete ?? 'null'}`,
+    `- 任务项总数（含子项 checkbox）：${taskCompletion?.total ?? 'null'}`,
     '',
     '## 说明',
     '- `null` 表示当前还没有采集到对应事件或该指标暂不适用。',
     '- E4 AI 一次成码率：依赖 `task_update` 事件中的 `task_id` 和首次执行结果，若 apply 阶段未正确记录则显示 null。',
-    '- P1 文档迭代次数：优先使用 Git 提交历史统计，无 Git 仓库或无提交历史时使用阶段 start 事件数。',
+    '- P1 文档迭代次数：依赖 Git 提交历史统计；无 Git 仓库时 fallback 到 doc_update 事件计数并标注来源。apply 阶段遵循 Git 只读策略不自动 commit 时，该 change 无提交历史 → P1=null 属预期（非数据缺失）。',
     '- P2 AI 代码保留率：优先使用 `ai_adoption_review` 的 final 状态，无 final 时 fallback 到 AI 产出快照（ai_snapshot）。',
-    '- Q4 规约驱动测试覆盖率：依赖 check/test 阶段记录 spec 断言到测试用例的映射数据（spec_test_coverage 字段），属高级功能。',
+    '- Q4 规约驱动测试覆盖率：依赖 `spec_test_coverage`（spec 断言→测试用例映射）精确统计；无该事件时 fallback 到 conformance_review 断言覆盖率（近似值，报告标注 source=conformance-fallback）。',
     '- Q1 规约符合度与人工反馈类指标属于评审信号，默认不作为强阻断门禁。',
+    '- M1 stage 时长含等待/故障耗时（API 错误、换模型、用户等待），未单独度量；过程记录的 api-error/model-switch 计数可作时长虚高旁证。',
+    '- 过程记录（process_note）：阶段内修复/澄清/决策/API 故障/换模型等事件，由 agent 在关键节点记录，可统计可追溯。',
   ].join('\n');
 }
 
+function renderExecutiveReportHtml(report) {
+  const metrics = report.metrics || {};
+  const eff = metrics.efficiency || {};
+  const qual = metrics.quality || {};
+  const proc = metrics.process || {};
+  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]));
+
+  // T2.5: 分钟单位时长（<60 分无副，≥60 分加「≈X小时Y分钟」副）
+  const durHtml = (ms) => {
+    const d = formatDuration(ms);
+    if (!d) return '<span class="metric-val muted-null">null</span>';
+    return `${d.minutes}<span class="unit">分钟</span>${d.sub ? `<span class="sub">${esc(d.sub)}</span>` : ''}`;
+  };
+  const pctHtml = (ratio, sub) => {
+    if (ratio == null || !Number.isFinite(ratio)) return '<span class="metric-val muted-null">null</span>';
+    return `${(ratio * 100).toFixed(1)}<span class="unit">%</span>${sub ? `<span class="sub">${esc(sub)}</span>` : ''}`;
+  };
+  const numHtml = (v, unit, sub) => {
+    if (v == null) return '<span class="metric-val muted-null">null</span>';
+    return `${esc(v)}${unit ? `<span class="unit">${esc(unit)}</span>` : ''}${sub ? `<span class="sub">${esc(sub)}</span>` : ''}`;
+  };
+  // 指标卡：name + 值 + 通俗化说明（info-btn 点击弹窗，不泄露内部术语）
+  const metricCell = (name, valHtml, info) => `<div class="metric"><div class="metric-head"><span class="metric-name">${esc(name)}</span>${info ? `<span class="info-btn" data-title="${esc(name)}" data-info="${esc(info)}">i</span>` : ''}</div><div class="metric-val">${valHtml}</div></div>`;
+
+  // 健康分环形仪表盘
+  const hs = health.telemetry_health_score;
+  const gaugePct = hs == null ? 0 : Math.max(0, Math.min(1, hs));
+  const gaugeR = 40, gaugeC = 2 * Math.PI * gaugeR;
+  const gaugeOffset = gaugeC * (1 - gaugePct);
+  const gaugeColor = gaugePct >= 0.8 ? '#22c55e' : (gaugePct >= 0.6 ? '#f59e0b' : '#ef4444');
+  const gaugeHtml = `<div class="gauge"><svg viewBox="0 0 100 100"><circle cx="50" cy="50" r="${gaugeR}" class="gauge-track"/><circle cx="50" cy="50" r="${gaugeR}" class="gauge-fill" style="stroke:${gaugeColor};stroke-dasharray:${gaugeC.toFixed(3)};stroke-dashoffset:${gaugeOffset.toFixed(3)}"/></svg><div class="gauge-text">${hs == null ? 'N/A' : Math.round(gaugePct * 100) + '%'}</div></div>`;
+
+  // T2.3: 横向时间线（阶段级，从 stage_timeline 派生）
+  const tlNodes = report.stage_timeline?._available && Array.isArray(report.stage_timeline.nodes) ? report.stage_timeline.nodes : [];
+  const maxDur = tlNodes.reduce((m, n) => Math.max(m, n.duration_ms || 0), 0);
+  const fmtHM = (ts) => {
+    if (!ts) return '--:--';
+    const d = new Date(ts);
+    if (isNaN(d.getTime())) return '--:--';
+    return `${String(d.getHours()).padStart(2, '0')}:${String(d.getMinutes()).padStart(2, '0')}`;
+  };
+  const tlHtml = tlNodes.length > 0
+    ? `<div class="timeline-h">${tlNodes.map((n, idx) => {
+        const dur = n.duration_ms || 0;
+        const barH = maxDur > 0 ? Math.max(6, Math.round((dur / maxDur) * 54)) : 6;
+        const failed = n.result === 'failure';
+        const short = !failed && dur > 0 && dur < 60000;
+        const barCls = failed ? 'bad' : (short ? 'short' : 'ok');
+        const round = n.round || 1;
+        const nameSuffix = round > 1 ? '²' : '';
+        const nameCls = failed ? ' style="color:#fca5a5"' : '';
+        const durMin = dur > 0 ? Math.round(dur / 60000) : 0;
+        const durLabel = durMin > 0 ? `${durMin}分` : '&lt;1分';
+        const taskLabel = n.task_count > 0 ? `·${n.task_count}任务` : '';
+        const timeLabel = `${fmtHM(n.start_ts)}→${fmtHM(n.end_ts)}`;
+        const repeatInfo = round > 1
+          ? `<div class="tl-repeat" data-title="重复执行：${esc(n.stage)}" data-info="该阶段是第 ${round} 次执行。首次未通过或被门禁拦截后重跑。">R</div>`
+          : '';
+        const connector = idx < tlNodes.length - 1 ? '<div class="tl-connector"></div>' : '';
+        return `<div class="tl-node"><div class="tl-bar-wrap"><div class="tl-bar ${barCls}" style="height:${barH}px"></div></div><div class="tl-dot${failed ? ' bad' : ''}"></div><div class="tl-name"${nameCls}>${esc(n.stage)}${nameSuffix}${failed ? ' ✗' : ''}</div><div class="tl-dur">${durLabel}${taskLabel}</div><div class="tl-time">${timeLabel}</div>${repeatInfo}${connector}</div>`;
+      }).join('')}</div>`
+    : '<p class="muted">无时间线数据</p>';
+
+  // Q7: warn-status 从 archive task_completion 对比，incomplete=0 标"已修复"
+  const warns = (report.known_risks?._available && Array.isArray(report.known_risks.warnings)) ? report.known_risks.warnings : [];
+  const warnHtml = warns.length > 0
+    ? warns.map(w => {
+        const items = Array.isArray(w.items) ? w.items : null;
+        const count = items ? items.length : (w.warnings || 0);
+        const detail = items && items.length > 0
+          ? items.map(it => it.target ? `${it.description || '待确认项'}（${it.target}）` : (it.description || '待确认项')).join('；')
+          : `共 ${count} 个待确认项（无明细）`;
+        const resolved = w.resolved === true;
+        const statusText = resolved ? '已修复' : '待确认';
+        const statusStyle = resolved
+          ? 'background:rgba(34,197,94,.16);color:#86efac'
+          : 'background:rgba(250,204,21,.16);color:#fde68a';
+        return `<div class="warn-item"><div class="warn-icon">!</div><div class="warn-body"><div class="warn-title">${esc(w.command || 'check')} 阶段 ${count} 个待确认</div><div class="warn-detail">${esc(detail)}</div></div><span class="warn-status" style="${statusStyle}">${statusText}</span></div>`;
+      }).join('')
+    : `<div class="warn-item"><div class="warn-icon" style="background:rgba(96,165,250,.16);color:#bfdbfe">i</div><div class="warn-body"><div class="warn-title">严重问题：${health.severe_issues?.length || 0} 个</div><div class="warn-detail">无未闭环阶段、无孤儿事件、无未知命令（阻断级问题）</div></div><span class="warn-status" style="background:rgba(34,197,94,.16);color:#86efac">无需修复</span></div>`;
+
+  // 过程：重复执行原因
+  const rs = proc.rework_summary || {};
+  const reasonDetails = Array.isArray(rs.reasons?.details) ? rs.reasons.details : [];
+  const reasonTag = (reason) => {
+    if (reason === 'incomplete' || reason === 'prev-failed') return { cls: 'unfinished', text: reason === 'incomplete' ? '前次未完成' : '前次失败重跑' };
+    if (reason === 'completed_rework_success') return { cls: 'rework', text: '通过后复检' };
+    return { cls: 'rework', text: REWORK_REASON_CN[reason] || reason || '复检' };
+  };
+  const reasonHtml = reasonDetails.length > 0
+    ? `<div class="reasons">${reasonDetails.map(d => {
+        const t = reasonTag(d.reason);
+        const note = d.detail ? String(d.detail).replace(/[\r\n]/g, ' ').slice(0, 60) : '';
+        return `<div class="reason-item"><span class="reason-stage">${esc(d.command)}</span><span class="reason-arrow">→</span><span class="reason-tag ${t.cls}">${esc(t.text)}</span>${note ? `<span class="reason-note">${esc(note)}</span>` : ''}</div>`;
+      }).join('')}</div>`
+    : '';
+  const reworkTotal = rs.total_rework_attempts ?? 0;
+  const byCat = rs.reasons?.by_category || {};
+  const catLine = REWORK_REASON_CATEGORIES.map(c => `${REWORK_REASON_CN[c] || c}=${byCat[c] ?? 0}`).join(' · ');
+
+  // 项目名（basename，不写本机绝对路径 —— T3.7 报告路径 basename 的 HTML 侧落地）
+  const projName = report.project_root ? String(report.project_root).replace(/[\\/]+$/, '').split(/[\\/]/).pop() : '';
+  const genTime = formatLocalTimestamp(report.generated_at);
+  const severeCount = health.severe_issues?.length || 0;
+  const matchedRate = health.matched_stage_rate;
+
+  // T3.2: 过程质量信号警示条（P4=0% / 过程记录缺失 / task_update 复用）—— 摘要区橙色警示
+  const pqSignals = [];
+  if (proc.p4_quality_gate_enforcement_rate === 0) {
+    pqSignals.push('质量门前置率 0%（首次编码未先检查，被门禁拦下）');
+  }
+  const pnTotal = report.process_notes?._available ? (report.process_notes.total ?? 0) : 0;
+  if (pnTotal === 0) {
+    pqSignals.push('过程记录缺失（未采集到修复/决策/故障等过程事件）');
+  }
+  if (report.telemetry_warnings?.by_type?.task_update_reuse > 0) {
+    pqSignals.push('检测到 task_update 复用（同一测试结果被多次记录）');
+  }
+  const qualityAlertHtml = pqSignals.length > 0
+    ? `<div class="quality-alert"><span class="qa-icon">!</span><div class="qa-body"><div class="qa-title">过程质量信号</div><div class="qa-items">${pqSignals.map(s => `<div>${esc(s)}</div>`).join('')}</div></div></div>`
+    : '';
+
+  // 归档与产物
+  const cf = report.changed_files || {};
+  const arts = report.artifacts || {};
+  const movedCount = Array.isArray(arts.copied_specs) ? arts.copied_specs.length : null;
+
+  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>
+:root{
+  --bg:#0b1020;--card-bg:rgba(255,255,255,.05);--card-bg-2:rgba(255,255,255,.03);
+  --border:rgba(255,255,255,.1);--border-2:rgba(255,255,255,.06);
+  --text:#e5e7eb;--muted:#8b97a7;--muted-2:#64748b;
+  --ok:#22c55e;--warn:#f59e0b;--bad:#ef4444;--accent:#60a5fa;
+}
+*{box-sizing:border-box}
+body{font-family:-apple-system,BlinkMacSystemFont,'Segoe UI','Microsoft YaHei',sans-serif;margin:0;background:var(--bg);color:var(--text);line-height:1.5;font-size:14px}
+main{max-width:1080px;margin:0 auto;padding:20px}
+.card{background:var(--card-bg);border:1px solid var(--border);border-radius:12px;padding:16px 18px;margin:12px 0;position:relative}
+h1{margin:0;font-size:22px;font-weight:600}
+h2{margin:0 0 14px;font-size:15px;font-weight:600;color:#cbd5e1;display:flex;align-items:center;gap:8px}
+h2::before{content:"";width:3px;height:14px;background:var(--accent);border-radius:2px}
+h3{margin:0;font-size:12px;font-weight:500;color:var(--muted);text-transform:uppercase;letter-spacing:.04em}
+.muted{color:var(--muted)}
+.muted-2{color:var(--muted-2);font-size:11px}
+code{color:#bfdbfe;background:rgba(96,165,250,.1);padding:1px 5px;border-radius:4px;font-size:12px;word-break:break-all}
+.badge{display:inline-block;padding:2px 8px;border-radius:999px;font-weight:600;font-size:11px}
+.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}
+table{width:100%;border-collapse:collapse;font-size:13px}
+th,td{border-bottom:1px solid var(--border-2);padding:7px 8px;text-align:left;vertical-align:top}
+th{color:var(--muted);width:38%;font-weight:500}
+tr:last-child td,tr:last-child th{border-bottom:none}
+.header-row{display:flex;justify-content:space-between;align-items:flex-end;flex-wrap:wrap;gap:8px}
+.header-meta{font-size:11px;color:var(--muted-2);text-align:right}
+.summary{display:grid;grid-template-columns:auto 1fr 1fr;gap:14px;align-items:stretch}
+.summary .cell{background:var(--card-bg-2);border:1px solid var(--border-2);border-radius:10px;padding:14px;display:flex;flex-direction:column;justify-content:center;align-items:center;text-align:center;min-height:110px}
+.gauge{width:96px;height:96px;position:relative}
+.gauge svg{transform:rotate(-90deg);width:100%;height:100%}
+.gauge-track{fill:none;stroke:rgba(255,255,255,.1);stroke-width:7}
+.gauge-fill{fill:none;stroke-width:7;stroke-linecap:round}
+.gauge-text{position:absolute;inset:0;display:flex;align-items:center;justify-content:center;font-size:24px;font-weight:700}
+.big-num{font-size:30px;font-weight:700;line-height:1}
+.big-num.ok{color:#86efac}
+.cell-label{font-size:11px;color:var(--muted);margin-top:6px;text-transform:uppercase;letter-spacing:.04em}
+.grid{display:grid;grid-template-columns:repeat(auto-fit,minmax(150px,1fr));gap:10px}
+.metric{background:var(--card-bg-2);border:1px solid var(--border-2);border-radius:10px;padding:12px 12px 10px;position:relative;min-height:84px;display:flex;flex-direction:column;justify-content:space-between}
+.metric-head{display:flex;justify-content:space-between;align-items:flex-start;gap:6px}
+.metric-name{font-size:11px;color:var(--muted);font-weight:500;line-height:1.3}
+.metric-val{font-size:20px;font-weight:700;margin-top:6px;line-height:1.1}
+.metric-val .unit{font-size:12px;font-weight:400;color:var(--muted);margin-left:2px}
+.metric-val .sub{display:block;font-size:11px;font-weight:400;color:var(--muted-2);margin-top:2px}
+.metric-val.muted-null{color:var(--muted-2);font-size:16px}
+.info-btn{cursor:pointer;color:var(--accent);font-size:12px;background:rgba(96,165,250,.12);border-radius:50%;width:16px;height:16px;display:inline-flex;align-items:center;justify-content:center;flex-shrink:0;transition:background .15s;line-height:1;user-select:none}
+.info-btn:hover{background:rgba(96,165,250,.28)}
+.modal-mask{position:fixed;inset:0;background:rgba(0,0,0,.55);display:none;align-items:center;justify-content:center;z-index:100;padding:20px}
+.modal-mask.show{display:flex}
+.modal{background:#131a2e;border:1px solid var(--border);border-radius:12px;max-width:440px;width:100%;padding:18px 20px}
+.modal h4{margin:0 0 8px;font-size:14px;color:#cbd5e1}
+.modal p{margin:0;font-size:13px;color:var(--text);line-height:1.6}
+.modal .close{margin-top:14px;text-align:right}
+.modal .close button{background:rgba(96,165,250,.16);color:#bfdbfe;border:none;border-radius:6px;padding:5px 16px;font-size:12px;cursor:pointer}
+.timeline-h{display:flex;align-items:stretch;gap:0;overflow-x:auto;padding:4px 0 6px}
+.tl-node{flex:0 0 auto;min-width:88px;position:relative;display:flex;flex-direction:column;align-items:center;padding:0 2px}
+.tl-bar-wrap{width:100%;height:54px;display:flex;align-items:flex-end;justify-content:center}
+.tl-bar{width:100%;max-width:46px;border-radius:4px 4px 0 0;min-height:6px}
+.tl-bar.ok{background:linear-gradient(180deg,rgba(34,197,94,.85),rgba(34,197,94,.4))}
+.tl-bar.bad{background:linear-gradient(180deg,rgba(239,68,68,.85),rgba(239,68,68,.4))}
+.tl-bar.short{background:rgba(34,197,94,.35);min-height:6px}
+.tl-dot{width:10px;height:10px;border-radius:50%;margin-top:6px;background:var(--ok);border:2px solid var(--bg)}
+.tl-dot.bad{background:var(--bad)}
+.tl-name{font-size:11px;color:#cbd5e1;margin-top:6px;font-weight:500;text-align:center;line-height:1.2}
+.tl-dur{font-size:10px;color:var(--muted);margin-top:2px;text-align:center}
+.tl-time{font-size:9px;color:var(--muted-2);margin-top:1px;text-align:center;white-space:nowrap;letter-spacing:-.02em}
+.tl-repeat{position:absolute;top:-6px;right:50%;transform:translateX(20px);font-size:10px;background:var(--warn);color:#1a1f2e;border-radius:999px;padding:0 5px;font-weight:700;cursor:pointer;line-height:14px;min-width:14px;text-align:center}
+.tl-repeat:hover{background:#fbbf24}
+.tl-connector{position:absolute;top:23px;right:calc(-50% + 6px);width:calc(100% - 12px);height:2px;background:var(--border-2);z-index:0}
+.tl-legend{display:flex;gap:14px;margin-top:10px;font-size:11px;color:var(--muted);flex-wrap:wrap;align-items:center}
+.tl-legend span{display:inline-flex;align-items:center;gap:5px}
+.tl-legend i{width:10px;height:10px;border-radius:2px;display:inline-block}
+.tl-legend .r-demo{background:var(--warn);color:#1a1f2e;border-radius:999px;padding:0 5px;font-weight:700;font-size:10px}
+.reasons{display:flex;flex-direction:column;gap:6px;margin-top:10px}
+.reason-item{display:flex;align-items:center;gap:8px;background:var(--card-bg-2);border:1px solid var(--border-2);border-radius:8px;padding:8px 10px;font-size:12px}
+.reason-stage{font-weight:600;color:#cbd5e1;min-width:60px}
+.reason-arrow{color:var(--muted-2)}
+.reason-tag{padding:2px 8px;border-radius:999px;font-size:11px;font-weight:500}
+.reason-tag.unfinished{background:rgba(245,158,11,.18);color:#fcd34d}
+.reason-tag.rework{background:rgba(96,165,250,.16);color:#bfdbfe}
+.reason-note{color:var(--muted);margin-left:auto;font-size:11px}
+.warn-item{display:flex;align-items:flex-start;gap:10px;padding:8px 0;border-bottom:1px solid var(--border-2);font-size:12px}
+.warn-item:last-child{border-bottom:none}
+.warn-icon{flex-shrink:0;width:18px;height:18px;border-radius:50%;background:rgba(245,158,11,.18);color:#fcd34d;display:flex;align-items:center;justify-content:center;font-size:11px;font-weight:700;margin-top:1px}
+.warn-body{flex:1}
+.warn-title{color:#e5e7eb;font-weight:500}
+.warn-detail{color:var(--muted);margin-top:2px}
+.warn-status{font-size:11px;padding:2px 8px;border-radius:999px;flex-shrink:0}
+.warn-status.fixed{background:rgba(34,197,94,.16);color:#86efac}
+.two-col{display:grid;grid-template-columns:1fr 1fr;gap:12px}
+@media(max-width:720px){.summary{grid-template-columns:1fr}.two-col{grid-template-columns:1fr}.grid{grid-template-columns:repeat(2,1fr)}}
+.quality-alert{display:flex;align-items:flex-start;gap:10px;margin-top:12px;padding:10px 12px;background:rgba(245,158,11,.12);border:1px solid rgba(245,158,11,.4);border-radius:8px;font-size:12px}
+.quality-alert .qa-icon{flex-shrink:0;width:18px;height:18px;border-radius:50%;background:rgba(245,158,11,.25);color:#fcd34d;display:flex;align-items:center;justify-content:center;font-weight:700;font-size:11px;margin-top:1px}
+.quality-alert .qa-title{font-weight:600;color:#fcd34d;margin-bottom:2px}
+.quality-alert .qa-items div{color:#e5e7eb;line-height:1.6}
+.footer-note{font-size:11px;color:var(--muted-2);margin-top:16px;padding:12px 18px;background:var(--card-bg-2);border:1px solid var(--border-2);border-radius:10px;line-height:1.7}
+.footer-note strong{color:var(--muted)}
+.section-tag{font-size:10px;color:var(--muted-2);font-weight:400;margin-left:6px}
+</style>
+</head>
+<body><main>
+
+<div class="card">
+  <div class="header-row">
+    <div>
+      <h1>SDD 效果度量报告</h1>
+      <div class="muted-2" style="margin-top:4px">变更：<code>${esc(report.change || 'project')}</code> · 统计范围：${esc(report.change ? `change/${report.change}` : 'project')}</div>
+    </div>
+    <div class="header-meta">生成时间 ${esc(genTime)}<br>项目 ${esc(projName)}</div>
+  </div>
+</div>
+
+<div class="card">
+  <h2>执行摘要</h2>
+  <div class="summary">
+    <div class="cell">
+      ${gaugeHtml}
+      <div class="cell-label">健康分</div>
+    </div>
+    <div class="cell">
+      <div class="big-num ok">${matchedRate == null ? 'null' : (matchedRate * 100).toFixed(0)}<span style="font-size:18px">%</span></div>
+      <div class="cell-label">阶段闭环率</div>
+    </div>
+    <div class="cell">
+      <div class="big-num ${severeCount > 0 ? 'bad' : 'ok'}" style="${severeCount > 0 ? 'color:#fca5a5' : ''}">${severeCount}</div>
+      <div class="cell-label">严重问题</div>
+    </div>
+  </div>
+  ${qualityAlertHtml}
+</div>
+
+<div class="card">
+  <h2>效率指标</h2>
+  <div class="grid">
+    ${metricCell('E1 总时长', durHtml(eff.e1_lead_time_ms), '从需求规划到归档完成的总耗时，包含阶段间等待和你确认的时间。')}
+    ${metricCell('E2 编码时间占比', pctHtml(eff.e2_coding_time_ratio), '实际编码阶段占总有效耗时的比例。')}
+    ${metricCell('E3 规约时间占比', pctHtml(eff.e3_spec_time_ratio), '需求规划、规格、设计、任务拆解四个阶段的耗时占比。注意：包含等待你确认的时间，可能偏高。')}
+    ${metricCell('E4 一次成码率', pctHtml(eff.e4_ai_code_first_pass_rate), 'AI 一次性写对代码的比例。只统计实现类任务（不含测试骨架），且构建、测试、结果三项都通过才算成功。基于 task_update 信号判定，非代码 diff。' + (report.telemetry_warnings?.by_type?.task_update_reuse > 0 ? ' E4 受 task_update 复用影响，已扣分。' : ''))}
+    ${metricCell('有效阶段总耗时', durHtml(eff.effective_stage_duration_ms), '各阶段实际耗时之和，不含阶段间的等待和会话切换。')}
+    ${metricCell('阶段间等待', durHtml(eff.idle_time_ms), 'E1 总时长减去各阶段有效耗时之和，即阶段间等待、会话切换等未计入有效耗时的部分。')}
+    ${metricCell('流程修正耗时', durHtml(eff.rework_stage_duration_ms), '因门禁拦截、重做等流程返工花费的时间。')}
+  </div>
+</div>
+
+<div class="card">
+  <h2>质量指标</h2>
+  <div class="grid">
+    ${metricCell('Q1 规约符合度', numHtml(qual.q1_spec_conformance_score, '/1', qual.q1_human_status === 'unverified' ? '自评·待人工确认' : null), '实现与规格的符合程度，由 AI 评审断言判定。仅供参考，不作强制门禁。')}
+    ${metricCell('Q3 构建一次通过率', pctHtml(qual.q3_build_first_pass_rate), '编码阶段第一次构建就成功的比例。')}
+    ${metricCell('Q4 测试覆盖率', pctHtml(qual.q4_spec_driven_test_coverage, qual.q4_source === 'conformance-fallback' ? '近似' : null), '规格中的每条断言被测试用例覆盖的比例。本次为近似值。')}
+    ${metricCell('Q5 跨文档一致性', numHtml(qual.q5_cross_doc_consistency_score, '/1'), '需求、规格、设计、任务四份文档之间是否一致、无矛盾的评分。')}
+  </div>
+</div>
+
+<div class="card">
+  <h2>过程指标 <span class="section-tag">含过程记录状态</span></h2>
+  <div class="grid">
+    ${metricCell('P1 文档迭代次数', proc.p1_spec_iteration_count == null ? '<span class="metric-val muted-null">null<span class="unit">·无git</span></span>' : numHtml(proc.p1_spec_iteration_count, '次'), '文档被修改的次数。需要 Git 提交记录来统计，本次没有 Git 提交，所以缺失。')}
+    ${metricCell('P2 AI 代码保留率', pctHtml(proc.p2_ai_code_adoption_rate), 'AI 生成的代码最终保留了多少比例。需要 Git 对比来计算，本次没有 Git 提交，所以缺失。')}
+    ${metricCell('P4 质量门前置率', pctHtml(proc.p4_quality_gate_enforcement_rate), 'apply 前是否完成 check。本次 apply 前未执行 check 才为 0%。')}
+    ${metricCell('阶段重复执行', numHtml(reworkTotal, '次'), '同一阶段被重复执行的次数。本次编码和检查各重做了一次。')}
+    ${metricCell('被覆盖未闭环', numHtml(rs.superseded_open_stages ?? null), '开始后未正常结束、但被后续重新执行覆盖的阶段数。')}
+    ${metricCell('过程记录事件', (report.process_notes?._available ? (report.process_notes.total ?? 0) : null) == null ? '<span class="metric-val muted-null">0<span class="unit">·未采集</span></span>' : numHtml(report.process_notes.total ?? 0, '条'), '过程中发生的修复、澄清、决策、故障等事件数。本次没有记录到任何过程事件。')}
+  </div>
+  ${reasonHtml ? `<h3 style="margin:14px 0 4px">重复执行原因分布</h3>${reasonHtml}<div class="muted-2" style="margin-top:8px">其余归类：${esc(catLine)}</div>` : ''}
+</div>
+
+<div class="card">
+  <h2>时间线 <span class="section-tag">横向 · 含起止时间${tlNodes.length > 0 ? ` · ${tlNodes.length} 个阶段执行` : ''}</span></h2>
+  ${tlHtml}
+  ${tlNodes.length > 0 ? `<div class="tl-legend"><span><i style="background:var(--ok)"></i>成功</span><span><i style="background:var(--bad)"></i>失败/拦截</span><span><i style="background:rgba(34,197,94,.35)"></i>短阶段</span><span><span class="r-demo">R</span>重复执行（可点击查看原因）</span><span>柱高 ∝ 耗时</span></div>` : ''}
+</div>
+
+<div class="card">
+  <h2>归档与产物 <span class="section-tag">变更文件 · 产物清单 · 归档结果</span></h2>
+  <div class="two-col">
+    <table>
+      <tr><th>变更文件数</th><td>${cf._available ? esc(cf.files_changed ?? 'null') : '<span class="muted-2">无数据</span>'}${cf.files_diff_note ? `<div class="muted-2" style="margin-top:4px">${esc(cf.files_diff_note)}</div>` : ''}</td></tr>
+      <tr><th>新增行数</th><td>${cf._available && cf.added_lines != null ? esc(cf.added_lines) : '<span class="muted-2">null（无 git 提交）</span>'}</td></tr>
+      <tr><th>迁移文件数</th><td>${movedCount != null ? esc(movedCount) : '<span class="muted-2">null</span>'}</td></tr>
+      <tr><th>任务项完成</th><td>${taskCompletion ? `${esc(taskCompletion.completed ?? 'null')} / ${esc(taskCompletion.total ?? 'null')}（含子项）` : '<span class="muted-2">null</span>'}</td></tr>
+    </table>
+    <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 || arts.archive_path || 'null')}</code></td></tr>
+      <tr><th>最终报告</th><td><code>${esc(archive?.report_path || 'null')}</code></td></tr>
+    </table>
+  </div>
+</div>
+
+<div class="card">
+  <h2>已知风险</h2>
+  ${warnHtml}
+</div>
+
+<div class="footer-note">
+  <strong>说明：</strong><code>null</code> 表示该指标未采集到或暂不适用（多为无 Git 提交所致）。E4 基于 task_update 信号判定，非代码 diff。阶段时长含等待/故障耗时，未单独度量。
+</div>
+
+</main>
+
+<div class="modal-mask" id="modalMask">
+  <div class="modal">
+    <h4 id="modalTitle">说明</h4>
+    <p id="modalBody"></p>
+    <div class="close"><button id="modalClose">关闭</button></div>
+  </div>
+</div>
+
+<script>
+(function(){
+  var mask=document.getElementById('modalMask');
+  var titleEl=document.getElementById('modalTitle');
+  var bodyEl=document.getElementById('modalBody');
+  function open(title,body){titleEl.textContent=title||'说明';bodyEl.textContent=body||'';mask.classList.add('show');}
+  function close(){mask.classList.remove('show');}
+  document.addEventListener('click',function(e){
+    var btn=e.target.closest('.info-btn,.tl-repeat');
+    if(btn){e.stopPropagation();open(btn.dataset.title,btn.dataset.info);return;}
+    if(!e.target.closest('.modal')) close();
+  });
+  document.getElementById('modalClose').addEventListener('click',close);
+  document.addEventListener('keydown',function(e){if(e.key==='Escape') close();});
+})();
+</script>
+</body></html>`;
+}
+
+// ── U1 报告维度提取辅助：从 events/metrics/doctor/archive 提炼 5 维度，数据缺失诚实标注 _available: false ──
+function extractChangedFiles(events, projectRoot) {
+  const adoptionEvents = events.filter(e => e.type === 'ai_adoption_review' || Boolean(e.details?.ai_adoption) || Boolean(e.details?.ai_code_adoption));
+  const latest = latestByTimestamp(adoptionEvents);
+  const review = latest ? getAiAdoptionReview(latest) : null;
+  const aiDiff = review?.ai_diff || null;
+  const hasFiles = Array.isArray(aiDiff?.files) && aiDiff.files.length > 0;
+  // P0-4: ai_diff 无效时，从 assertions[].files 聚合兜底（补救存量 ai_adoption_review 无 ai_diff 的事件）
+  if (!aiDiff || (aiDiff.files_changed == null && aiDiff.added_lines == null && !hasFiles)) {
+    if (latest?.details) {
+      const rawReview = latest.details.ai_adoption || latest.details.ai_adoption_review || latest.details.ai_code_adoption || {};
+      const rawAssertions = rawReview.assertions;
+      if (Array.isArray(rawAssertions)) {
+        const filesFromAssertions = new Set();
+        for (const a of rawAssertions) {
+          if (Array.isArray(a.files)) {
+            for (const f of a.files) {
+              if (typeof f === 'string' && f.trim()) filesFromAssertions.add(f.trim());
+            }
+          }
+        }
+        if (filesFromAssertions.size > 0) {
+          return { _available: true, files_changed: filesFromAssertions.size, added_lines: null, files: [...filesFromAssertions] };
+        }
+      }
+    }
+    return { _available: false, files_changed: null, added_lines: null, files: null };
+  }
+  let addedLines = Number.isFinite(aiDiff.added_lines) ? aiDiff.added_lines : null;
+  const files = hasFiles ? aiDiff.files.slice() : null;
+  // T3.3: ai_git_sha=null（无 git）时，用 fs 读 files 行数作 added_lines fallback（DC-104 无 git/路径缺失不崩溃）
+  if (addedLines == null && review && review.ai_git_sha == null && hasFiles && projectRoot) {
+    let sum = 0;
+    let counted = 0;
+    const projectRootResolved = path.resolve(projectRoot);
+    for (const rel of aiDiff.files) {
+      try {
+        // Y1+Y6 修复：校验路径不穿越 projectRoot + 用 split 替代 match 减少正则数组开销
+        const abs = path.isAbsolute(rel) ? path.resolve(rel) : path.resolve(projectRoot, rel);
+        if (!abs.startsWith(projectRootResolved + path.sep) && abs !== projectRootResolved) continue;
+        const content = fs.readFileSync(abs, 'utf8');
+        const newlines = content.split('\n').length - 1;
+        sum += newlines + (content.length > 0 && !content.endsWith('\n') ? 1 : 0);
+        counted += 1;
+      } catch {
+        // 文件不存在/不可读，跳过
+      }
+    }
+    if (counted > 0) addedLines = sum;
+  }
+  // A6(v3): task_update 汇总文件数优先于 ai_diff 自报值（ai_diff 是 agent 一次性快照，
+  // task_update 累加去重更准）；两者不一致时 ai_diff 作辅助并标注差异。
+  // 兼容 task_update.details.files / details.test_results.files / details.files_changed(数组形态)
+  const taskUpdateFiles = new Set();
+  for (const e of events) {
+    if (e?.type !== 'task_update') continue;
+    const filesField = e.details?.files
+      || e.details?.test_results?.files
+      || (Array.isArray(e.details?.files_changed) ? e.details.files_changed : null);
+    if (Array.isArray(filesField)) {
+      for (const f of filesField) {
+        if (typeof f === 'string' && f.trim()) taskUpdateFiles.add(f.trim());
+      }
+    }
+  }
+  const taskUpdateFileCount = taskUpdateFiles.size;
+  const aiDiffFileCount = Number.isFinite(aiDiff.files_changed) ? aiDiff.files_changed : (files ? files.length : null);
+  let filesChanged;
+  let aiDiffFilesChanged = null;
+  let filesDiffNote = null;
+  if (taskUpdateFileCount > 0) {
+    filesChanged = taskUpdateFileCount;
+    if (aiDiffFileCount != null && aiDiffFileCount !== taskUpdateFileCount) {
+      aiDiffFilesChanged = aiDiffFileCount;
+      filesDiffNote = `ai_diff 自报 ${aiDiffFileCount} 与 task_update 汇总 ${taskUpdateFileCount} 不一致，已采用 task_update 汇总值`;
+    }
+  } else {
+    filesChanged = aiDiffFileCount;
+  }
+  return {
+    _available: true,
+    files_changed: filesChanged,
+    added_lines: addedLines,
+    files,
+    ai_diff_files_changed: aiDiffFilesChanged,
+    files_diff_note: filesDiffNote,
+  };
+}
+
+function extractTimeline(events) {
+  const nodes = events
+    .filter(e => !e.orphan && (e.type === 'stage_start' || e.type === 'stage_end' || e.type === 'build_result' || e.type === 'task_update'))
+    .sort((a, b) => timestampMs(a) - timestampMs(b));
+  if (nodes.length === 0) return { _available: false, nodes: null };
+  return {
+    _available: true,
+    nodes: nodes.map(e => ({
+      timestamp: e.timestamp || null,
+      type: e.type,
+      command: e.command || e.stage || null,
+      result: e.result || null,
+    })),
+  };
+}
+
+// ── T2.3: 阶段级时间线节点（横向时间线数据源）── 配对 stage_start/stage_end 为一次阶段执行，
+// 折叠其间的 task_update 数量，标记 round（>1 即重复执行）。按 event_id 配对（同 summarizeStageExecutions）。
+function extractStageTimeline(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');
+  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 roundCount = {};
+  // Y7 修复：预排序 task_updates 供 starts.map 扫描区间（降 O(starts×events) 为 O(starts+events)）
+  const taskUpdates = events.filter(e => e.type === 'task_update').sort((a, b) => timestampMs(a) - timestampMs(b));
+  const nodes = starts.map(start => {
+    const end = latestByTimestamp(endsById.get(start.event_id) || []);
+    const cmd = start.command || start.stage || 'unknown';
+    roundCount[cmd] = (roundCount[cmd] || 0) + 1;
+    const round = roundCount[cmd];
+    const startMs = timestampMs(start);
+    const endMs = end ? timestampMs(end) : null;
+    // Y7 修复：用预排序 taskUpdates 单次扫描区间 O(n)，替代全量 filter O(starts×events)
+    let taskCount = 0;
+    for (const t of taskUpdates) {
+      const tMs = timestampMs(t);
+      if (tMs < startMs) continue;
+      if (endMs != null && tMs > endMs) break;
+      taskCount++;
+    }
+    return {
+      stage: cmd,
+      round,
+      start_ts: start.timestamp || null,
+      end_ts: end?.timestamp || null,
+      duration_ms: end && Number.isFinite(end.duration_ms) ? end.duration_ms : null,
+      result: end?.result || null,
+      task_count: taskCount,
+    };
+  });
+  if (nodes.length === 0) return { _available: false, nodes: null };
+  return { _available: true, nodes };
+}
+
+function extractStageStatus(metrics) {
+  const byStage = metrics?.process?.rework_summary?.by_stage || [];
+  if (byStage.length === 0) return { _available: false, stages: null };
+  return {
+    _available: true,
+    stages: byStage.map(b => ({
+      command: b.command,
+      capability: b.capability,
+      total_attempts: b.total_attempts,
+      successful_attempts: b.successful_attempts,
+      rework_attempts: b.rework_attempts,
+      canonical_event_id: b.canonical_event_id || null,
+    })),
+  };
+}
+
+function extractKnownRisks(events, doctor, archiveResult) {
+  const severeIssues = doctor?.severe_issues || [];
+  const warnings = [];
+  // Q7: 从 archive task_completion 判断 warn 是否已修复（incomplete=0 → resolved）
+  const taskCompletion = archiveResult?.task_completion;
+  const allResolved = taskCompletion && Number.isFinite(taskCompletion.incomplete) && taskCompletion.incomplete === 0;
+  for (const e of events) {
+    const cr = e.details?.check_results;
+    if (cr && Number.isFinite(cr.warnings) && cr.warnings > 0) {
+      // T2.1: 携带 warning_items 明细（若有）；旧事件无该字段时降级为仅数量（DC-101/UT-202）
+      const entry = { command: e.command || e.stage || null, warnings: cr.warnings };
+      if (Array.isArray(cr.warning_items) && cr.warning_items.length > 0) {
+        entry.items = cr.warning_items;
+      }
+      // Q7: 归档后 incomplete=0 → 标已修复
+      if (allResolved) entry.resolved = true;
+      warnings.push(entry);
+    }
+    const conf = getConformanceReview(e);
+    if (conf && Array.isArray(conf.assertions)) {
+      // normalizeConformanceStatus 归一化为 matched/partial/missed；missed 表示断言未匹配（等价失败）
+      const failed = conf.assertions.filter(a => a.status === 'missed');
+      if (failed.length > 0) {
+        const confEntry = { command: e.command || 'conformance', failed_assertions: failed.length };
+        if (allResolved) confEntry.resolved = true;
+        warnings.push(confEntry);
+      }
+    }
+  }
+  if (severeIssues.length === 0 && warnings.length === 0) {
+    return { _available: false, severe_issues: null, warnings: null };
+  }
+  return { _available: true, severe_issues: severeIssues, warnings };
+}
+
+function extractArtifacts(archiveEvent) {
+  const ar = archiveEvent?.details?.archive_result;
+  if (!ar) return { _available: false, archive_path: null, manifest_path: null, moved_files: null, copied_specs: null };
+  const movedFiles = Array.isArray(ar.moved_files) ? ar.moved_files : (Array.isArray(ar.movedFiles) ? ar.movedFiles : null);
+  // P0-1: copied_specs 是归档时实际迁移的 spec 文件清单（archive-manifest 字段）
+  const copiedSpecs = Array.isArray(ar.copied_specs) ? ar.copied_specs : (Array.isArray(ar.copiedSpecs) ? ar.copiedSpecs : null);
+  return {
+    _available: true,
+    archive_path: ar.archive_path || null,
+    manifest_path: ar.manifest_path || null,
+    moved_files: movedFiles,
+    copied_specs: copiedSpecs,
+  };
+}
+
+// ── U2/U3: 过程事件（process_note）提取 —— 阶段内修复/澄清/决策/API 故障/换模型等，可统计可追溯 ──
+function extractProcessNotes(events) {
+  const notes = events.filter(e => !e.orphan && e.type === 'process_note');
+  if (notes.length === 0) return { _available: false, total: 0, by_kind: null, by_stage: null, notes: null };
+  const byKind = {};
+  const byStage = {};
+  for (const n of notes) {
+    const kind = n.details?.kind || 'other';
+    byKind[kind] = (byKind[kind] || 0) + 1;
+    const stage = n.command || n.stage || 'unknown';
+    byStage[stage] = (byStage[stage] || 0) + 1;
+  }
+  return {
+    _available: true,
+    total: notes.length,
+    by_kind: byKind,
+    by_stage: byStage,
+    notes: notes.map(n => ({
+      timestamp: n.timestamp || null,
+      stage: n.command || n.stage || null,
+      kind: n.details?.kind || 'other',
+      summary: n.summary || n.details?.summary || '',
+      target: n.details?.target || null,
+      round: Number.isFinite(n.details?.round) ? n.details.round : null,
+    })),
+  };
+}
+
+// ── T3.2: telemetry 警告提取 —— gate 记录的 task_update_reuse / process_note_missing / apply_test_missing
+// 供执行摘要「过程质量信号警示条」判定 task_update 复用。事件结构由 sdd-apply-test-gate.cjs recordWarning 写入。
+function extractTelemetryWarnings(events) {
+  const warnings = events.filter(e => !e.orphan && e.type === 'telemetry_warning');
+  if (warnings.length === 0) return { _available: false, total: 0, by_type: {}, items: [] };
+  const byType = {};
+  const items = [];
+  for (const w of warnings) {
+    const t = (w.details && (w.details.warning || w.details.type || w.details.warning_type)) || 'unknown';
+    byType[t] = (byType[t] || 0) + 1;
+    items.push({ type: t, timestamp: w.timestamp || null, message: w.summary || (w.details && w.details.message) || '' });
+  }
+  return { _available: true, total: warnings.length, by_type: byType, items };
+}
+
 function buildReport(projectRoot, events, options = {}) {
   const archiveEvent = latestByTimestamp(events.filter(e => {
     return e.command === 'archive' && e.type === 'stage_end' && !e.orphan;
   }));
+  const metrics = computePdfMvpMetrics(events, {
+    level: options.level || (options.change ? 'change' : 'project'),
+    change: options.change,
+    capability: options.capability,
+    projectRoot,
+  });
+  const doctor = computeDoctorReport(events, { change: options.change, projectRoot });
   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 }),
+    metrics,
+    doctor,
     archive_result: archiveEvent?.details?.archive_result || null,
+    changed_files: extractChangedFiles(events, projectRoot),
+    timeline: extractTimeline(events),
+    stage_timeline: extractStageTimeline(events),
+    stage_status: extractStageStatus(metrics),
+    known_risks: extractKnownRisks(events, doctor, archiveEvent?.details?.archive_result),
+    artifacts: extractArtifacts(archiveEvent),
+    process_notes: extractProcessNotes(events),
+    telemetry_warnings: extractTelemetryWarnings(events),
   };
 }
 
@@ -1948,6 +3159,7 @@ function computeDoctorReport(events, options = {}) {
     ? 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');
@@ -1960,13 +3172,13 @@ function computeDoctorReport(events, options = {}) {
 
   const matchedStarts = starts.filter(e => endsById.has(e.event_id));
   const supersededOpenIds = new Set(executionSummary.reworkAttempts
-    .filter(attempt => attempt.rework_reason === 'superseded_open')
+    .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 matchedStageRate = effectiveStartCount === 0 ? null : 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');
@@ -2011,7 +3223,7 @@ function computeDoctorReport(events, options = {}) {
 
   return {
     telemetry_health_score: telemetryHealthScore,
-    matched_stage_rate: Math.round(matchedStageRate * 100) / 100,
+    matched_stage_rate: matchedStageRate == null ? null : Math.round(matchedStageRate * 100) / 100,
     total_events: scopedEvents.length,
     stage_events: stageEvents.length,
     start_events: starts.length,
@@ -2030,7 +3242,7 @@ function computeDoctorReport(events, options = {}) {
     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),
+    rework_summary: compactReworkSummary(executionSummary.summary, reworkReasons),
     severe_issues: severeIssues,
     warnings,
   };
@@ -2090,6 +3302,13 @@ function cmdStart(args) {
     fail(`context JSON 解析失败: ${err.message}`);
   }
 
+  // apply 时记录 worktree_used/worktree_dir（从 SKILL 传入 --worktree-used --worktree-dir）
+  // CLI parseArgs 把 --worktree-used=true 解析为字符串 "true"，需同时接受布尔与字符串
+  const isTrue = (v) => v === true || v === 'true';
+  const worktreeUsed = isTrue(args['worktree-used']) || isTrue(args['worktree_used']);
+  const worktreeDir = args['worktree-dir'] || args['worktree_dir'] || null;
+  const worktreeDetails = worktreeUsed ? { worktree_used: true, worktree_dir: worktreeDir } : undefined;
+
   const event = cleanOptionalFields({
     schema_version: SCHEMA_VERSION,
     event_id: eventId,
@@ -2106,6 +3325,7 @@ function cmdStart(args) {
     git_sha: gitSha,
     timestamp,
     context,
+    details: worktreeDetails,
   });
 
   appendEvent(dataDir, event.change, event);
@@ -2125,16 +3345,22 @@ function cmdStart(args) {
  */
 function cmdEnd(args, options = {}) {
   let eventId = args['event-id'] || args.event_id;
-  const result = args.result;
-  const summary = args.summary || '';
+  let result = args.result;
+  let summary = args.summary || '';
   const projectRoot = normalizeProjectRoot(args.project || args['project-root'] || process.cwd());
-  let reportOutput = args['report-output'] || args.report_output || (args['generate-report'] ? path.join('skywalk-sdd', 'reports', `${safeChangeName(args.change || args['change-name'] || 'general')}-report.md`) : '');
+  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,
@@ -2148,6 +3374,42 @@ function cmdEnd(args, options = {}) {
   if (!eventId && startEvent) {
     eventId = startEvent.event_id;
   }
+  // stage_end 幂等性保护：同一 event_id 已存在 stage_end 时，结果相同则跳过，不同则更新（archive 命令只要存在即跳过）
+  const command = startEvent?.command || args.command || 'unknown';
+  const change = startEvent?.change || args.change || args['change-name'] || 'general';
+  const existingEnds = readAllEventEndsById(dataDir, eventId, change);
+  if (existingEnds.length > 0) {
+    const latestExisting = existingEnds.sort((a, b) => timestampMs(b) - timestampMs(a))[0];
+    // archive 命令已存在 stage_end 时直接跳过，避免 result 突变后重复写入
+    if (command === 'archive') {
+      const output = {
+        event_id: eventId,
+        duration_ms: latestExisting.duration_ms,
+        recorded_at: latestExisting.timestamp,
+        report_output: latestExisting.details?.archive_result?.report_path || '',
+        message: `SDD ${latestExisting.command || command} 阶段结束（archive，已存在相同 event_id 的 stage_end，幂等跳过）`,
+      };
+      if (!options.silent) {
+        console.log(JSON.stringify(output, null, 2));
+      }
+      return output;
+    }
+    if (latestExisting.result === result) {
+      // 结果相同：幂等跳过，返回统一 shape
+      const output = {
+        event_id: eventId,
+        duration_ms: latestExisting.duration_ms,
+        recorded_at: latestExisting.timestamp,
+        report_output: latestExisting.details?.archive_result?.report_path || '',
+        message: `SDD ${latestExisting.command || command} 阶段结束（${result}，已存在相同 event_id 的 stage_end，幂等跳过）`,
+      };
+      if (!options.silent) {
+        console.log(JSON.stringify(output, null, 2));
+      }
+      return output;
+    }
+    // 结果不同：允许继续写入新的 stage_end（覆盖/更新）
+  }
   const orphan = !startEvent;
   if (!eventId) {
     eventId = generateEventId();
@@ -2164,13 +3426,18 @@ function cmdEnd(args, options = {}) {
     ? new Date(timestamp).getTime() - new Date(startEvent.timestamp).getTime()
     : null;
 
-  const command = startEvent?.command || args.command || 'unknown';
-  const change = startEvent?.change || args.change || args['change-name'] || 'general';
-  if (command === 'archive' && result === 'success' && !reportOutput) {
-    reportOutput = path.join('skywalk-sdd', 'reports', `${safeChangeName(change)}-report.md`);
+  // command 和 change 已在幂等性检查前声明
+  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') {
-    const repaired = ensureArchiveSuccessArtifacts(projectRoot, change, details, {
+    repaired = ensureArchiveSuccessArtifacts(projectRoot, change, details, {
       reason: details.archive_result?.reason || '',
       reportOutput,
     });
@@ -2184,6 +3451,22 @@ function cmdEnd(args, options = {}) {
       };
     }
   }
+  // archive 归档完成后，扫描 task_completion，has_incomplete 降为 partial（仍归档，仅 result 标记提示未勾验收）
+  if (command === 'archive' && result === 'success') {
+    try {
+      const archiveDirRel = repaired?.archive_path || details.archive_result?.archive_path || null;
+      const archiveDirAbs = archiveDirRel ? (path.isAbsolute(archiveDirRel) ? archiveDirRel : path.join(projectRoot, archiveDirRel)) : null;
+      const taskCompletion = archiveDirAbs
+        ? scanTaskCompletionForArchiveDir(projectRoot, change, archiveDirAbs)
+        : scanTaskCompletion(projectRoot, change);
+      if (taskCompletion.has_incomplete) {
+        result = 'partial';
+        summary = `${summary}（${taskCompletion.incomplete} 项验收标准未勾选）`.trim();
+      }
+    } catch (err) {
+      try { console.error(`[telemetry] archive 降级检查失败（不阻塞）: ${err.message}`); } catch {}
+    }
+  }
   const event = cleanOptionalFields({
     schema_version: SCHEMA_VERSION,
     event_id: eventId,
@@ -2203,6 +3486,7 @@ function cmdEnd(args, options = {}) {
     result,
     summary,
     details,
+    rework_reason: reason || undefined,
     orphan: orphan ? true : undefined,
   });
 
@@ -2211,23 +3495,69 @@ function cmdEnd(args, options = {}) {
     clearActiveStage(projectRoot, startEvent);
   }
 
+  // archive 时追加"变更总结"段到 execution-log.md（T1.3：移到 appendEvent 之后，确保总结出现在 archive_end 行之后）
+  if (command === 'archive') {
+    try { appendChangeSummary(projectRoot, change, readEvents(dataDir, change)); } catch (err) {
+      try { console.error(`[telemetry] 变更总结追加失败（不阻塞）: ${err.message}`); } catch {}
+    }
+  }
+
   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);
-    resolvedReportOutput = path.isAbsolute(reportOutput)
-      ? reportOutput
-      : path.resolve(projectRoot, reportOutput);
-    ensureDir(path.dirname(resolvedReportOutput));
-    fs.writeFileSync(resolvedReportOutput, rendered + '\n', 'utf8');
+  const reportFormat = args['report-format'] || 'markdown';
+  const isHtmlPrimary = reportFormat === 'html';
+  const rendered = reportFormat === 'json'
+    ? JSON.stringify(report, null, 2)
+    : (isHtmlPrimary ? renderExecutiveReportHtml(report) : renderExecutiveReportMarkdown(report));
+  ensureDir(path.dirname(resolvedReportOutput));
+  fs.writeFileSync(resolvedReportOutput, rendered + '\n', 'utf8');
+
+  // 默认双输出：md + html，避免只生成单一格式；但仅对 .md/.html 主路径派生副本，防止非标准路径被静默覆盖
+  if (reportFormat !== 'json') {
+    try {
+      const primaryExt = path.extname(resolvedReportOutput).toLowerCase();
+      const isMdPrimary = primaryExt === '.md';
+      const isHtmlExt = primaryExt === '.html';
+      if (isMdPrimary || isHtmlExt) {
+        const companionSuffix = isHtmlExt ? '.md' : '.html';
+        const companionRender = isHtmlExt ? renderExecutiveReportMarkdown(report) : renderExecutiveReportHtml(report);
+        const htmlPath = resolvedReportOutput.replace(/\.[^.]+$/, companionSuffix);
+        if (htmlPath !== resolvedReportOutput) {
+          fs.writeFileSync(htmlPath, companionRender + '\n', 'utf8');
+        }
+      }
+    } catch (err) {
+      try { console.error(`[telemetry] ${isHtmlPrimary ? 'md' : 'html'} 报告副本写入失败（不阻塞主流程）: ${err.message}`); } catch {}
+    }
+  }
+  }
+
+  // A1(v3): appendEvent 已把 archive stage_end 写入活跃 jsonl，但上方 ensureArchiveSuccessArtifacts
+  // 在 appendEvent 之前拷贝 events → archive/evidence/jsonl 缺末条 stage_end。此处重拷覆盖，幂等。
+  // 触发条件：archive 且归档产物已生成（repaired 非空，即原始 result=success，不含 failure/纯 partial）。
+  if (command === 'archive' && repaired && details.archive_result?.archive_path) {
+    try {
+      const archiveDirAbs = path.isAbsolute(details.archive_result.archive_path)
+        ? details.archive_result.archive_path
+        : path.resolve(projectRoot, details.archive_result.archive_path);
+      const eventsSrcDir = path.join(getDataDir(projectRoot), 'events', safeChangeName(change));
+      if (fs.existsSync(eventsSrcDir) && fs.existsSync(archiveDirAbs)) {
+        copyDirSync(eventsSrcDir, path.join(archiveDirAbs, 'evidence', 'events'));
+      }
+    } catch (err) {
+      try { console.error(`[telemetry] archive events 重拷失败（不阻塞）: ${err.message}`); } catch {}
+    }
   }
 
   const output = {
@@ -2265,6 +3595,8 @@ function cmdRecord(args) {
     'baseline_record',
     'telemetry_warning',
     'worktree_finish',
+    'process_note',
+    'doc_update',
   ];
 
   if (!type) {
@@ -2278,12 +3610,75 @@ function cmdRecord(args) {
   }
 
   let details;
+  let detailsFilePath = null;
   try {
     details = parseJsonOption(args, 'details-json', 'details-file', projectRoot, {});
+    detailsFilePath = args['details-file'] || args.details_file || null;
+    // 默认清理 details-file，避免项目根目录被临时 JSON 污染；--keep-details 保留调试用
+    if (detailsFilePath && !args['keep-details'] && !args.keep_details) {
+      try {
+        const fileToRemove = normalizeDetailsFilePath(detailsFilePath, projectRoot);
+        if (fs.existsSync(fileToRemove)) {
+          fs.unlinkSync(fileToRemove);
+        }
+      } catch (cleanupErr) {
+        // 清理失败不阻塞主流程
+        try { console.error(`[telemetry] details-file 清理失败（不阻塞）: ${cleanupErr.message}`); } catch {}
+      }
+    }
   } catch (err) {
     fail(`details JSON 解析失败: ${err.message}`);
   }
 
+  // task_update 成功时自动同步 tasks.md checkbox
+  if (type === 'task_update' && args.result === 'success') {
+    try {
+      const taskId = args['task-id'] || args.task_id || details?.task_id || null;
+      if (taskId) {
+        runCheckTaskSync(projectRoot, change, taskId);
+      }
+    } catch (taskErr) {
+      // checkbox 同步失败不阻塞原流程
+      try { console.error(`[telemetry] tasks.md checkbox 自动同步失败（不阻塞）: ${taskErr.message}`); } catch {}
+    }
+  }
+
+  // conformance_review evidence 校验——assertion 必须有可验证证据：
+  //   files 含测试文件路径（test/ | .test. | .spec.）→ 强证据；
+  //   或 evidence 文本非空 → 降级证据（浏览器自动化/手动验收等无测试文件场景，与 SKILL.md schema 对齐：空 files[] 须配 evidence）；
+  //   两者皆无 → 空口断言拒绝。
+  if (type === 'conformance_review') {
+    const cr = details.conformance_review;
+    if (cr && Array.isArray(cr.assertions)) {
+      for (const a of cr.assertions) {
+        const files = Array.isArray(a.files) ? a.files : [];
+        const hasTestFile = files.some(f => /test[\\/]|\.test\.|\.spec\./.test(String(f)));
+        const hasEvidence = typeof a.evidence === 'string' && a.evidence.trim().length > 0;
+        if (!hasTestFile && !hasEvidence) {
+          fail(`conformance_review assertion "${a.id || ''}" 缺少证据：files 须含测试文件路径（test/ | .test. | .spec.），或填 evidence 文本（如浏览器自动化/手动验收证据摘要）`);
+        }
+      }
+    }
+  }
+
+  // ai_adoption_review 校验——与 conformance_review 对称的记录时硬校验（doc 早已要求必填，见 opsx-apply/SKILL.md §P1-2）：
+  //   ai_diff.files 必须填产出文件路径数组（非空），不得只发 files_changed 数字；
+  //   vcs_mode=readonly（git 仓库）时 added_lines 不得为 null——逼 agent 跑只读 "git diff --numstat HEAD"（apply Git 只读策略允许）；
+  //   vcs_mode=no-git 时 added_lines 可为 null（无 diff 可统计）。缺失 vcs_mode 字段时放宽（兼容存量事件）。
+  if (type === 'ai_adoption_review') {
+    const adoption = details.ai_adoption || details.ai_adoption_review || details.ai_code_adoption;
+    if (adoption) {
+      const aiDiff = adoption.ai_diff || {};
+      const files = Array.isArray(aiDiff.files) ? aiDiff.files : null;
+      if (!files || files.length === 0) {
+        fail(`ai_adoption_review 的 ai_diff.files 必须填产出文件路径数组（非空），不得只发 files_changed 数字；详见 opsx-apply/reference.md §5.1`);
+      }
+      if (adoption.vcs_mode === 'readonly' && (aiDiff.added_lines === null || aiDiff.added_lines === undefined)) {
+        fail(`ai_adoption_review vcs_mode=readonly 时 ai_diff.added_lines 不得为 null——请用只读 "git diff --numstat HEAD" 取值（apply Git 只读策略允许）；vcs_mode=no-git 时可填 null`);
+      }
+    }
+  }
+
   const dataDir = getDataDir(projectRoot);
   const activeStage = findActiveStage(projectRoot, {
     session_id: args['session-id'] || args.session_id,
@@ -2293,6 +3688,32 @@ function cmdRecord(args) {
   });
   const eventId = args['event-id'] || args.event_id || generateEventId();
   const timestamp = nowISO();
+  // T1.2: task_update 复用标注 — 同 session 上一条 task_update 的 test_results.duration_ms 一致且时间戳相邻(<5s) → recorded_late（提示性，不阻断）
+  if (type === 'task_update' && details && details.test_results) {
+    try {
+      const sessionId = activeStage?.session_id || args['session-id'] || args.session_id || null;
+      const priorEvents = readEvents(dataDir, change);
+      const priorUpdates = priorEvents.filter((e) =>
+        e.type === 'task_update' && e.session_id === sessionId && e.details && e.details.test_results
+      );
+      if (priorUpdates.length > 0) {
+        // Y3 修复：显式按时间排序取最新一条（原取数组末尾依赖 readEvents 文件排序=时间序，多 jsonl 文件名非时间前缀时可能错序）
+        const sorted = priorUpdates.slice().sort((a, b) => new Date(a.timestamp || 0) - new Date(b.timestamp || 0));
+        const last = sorted[sorted.length - 1];
+        const lastTr = last.details.test_results;
+        const thisTr = details.test_results;
+        const lastFp = `${Number(lastTr.passed)}|${Number(lastTr.failed)}|${Number(lastTr.duration_ms)}`;
+        const thisFp = `${Number(thisTr.passed)}|${Number(thisTr.failed)}|${Number(thisTr.duration_ms)}`;
+        // T1.5(v3): 去掉 gap<=5000 相邻限制，改用 passed+failed+duration_ms 三元组指纹（与 detectReusedTestResults 对齐）
+        if (Number.isFinite(Number(lastTr.duration_ms)) && Number.isFinite(Number(thisTr.duration_ms)) && lastFp === thisFp) {
+          details.recorded_late = true;
+          details.reused_fingerprint = thisFp;
+        }
+      }
+    } catch {
+      // recorded_late 检测失败不阻塞记录
+    }
+  }
   const event = cleanOptionalFields({
     schema_version: SCHEMA_VERSION,
     event_id: eventId,
@@ -2323,6 +3744,189 @@ function cmdRecord(args) {
   }, null, 2));
 }
 
+/** 解析 node --test 的 TAP 输出为 {passed, failed, skipped}（opsx-apply agent 跑测试后传 --test-stdout） */
+function parseTestTap(output) {
+  if (!output || typeof output !== 'string') return { passed: 0, failed: 0, skipped: 0 };
+  let passed = 0;
+  let failed = 0;
+  let skipped = 0;
+  for (const line of output.split(/\r?\n/)) {
+    if (/^ok\s+\d+/.test(line)) {
+      if (/#\s*SKIP/i.test(line)) { skipped += 1; continue; }
+      passed += 1;
+    } else if (/^not ok\s+\d+/.test(line)) {
+      if (/#\s*TODO/i.test(line)) { skipped += 1; continue; }
+      failed += 1;
+    }
+  }
+  return { passed, failed, skipped };
+}
+
+/** scan 子命令——输出全量 task_completion checkbox 统计（opsx-check 强制调用，禁止手填 completed/incomplete/total） */
+function cmdScan(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 result = scanTaskCompletion(projectRoot, changeName);
+  console.log(JSON.stringify(result, null, 2));
+  return result;
+}
+
+/** 校验 spec 场景数 == 测试数（spec.md `##### 场景：` 计数 vs 最近 test_results.passed+failed） */
+function validateScenarioCoverage(projectRoot, changeName, capability) {
+  const normalizedRoot = normalizeProjectRoot(projectRoot);
+  const changeDir = getChangeDir(normalizedRoot, changeName);
+  let specScenarios = 0;
+  const specFiles = discoverFullSpecFiles(changeDir, changeName);
+  for (const spec of specFiles) {
+    if (capability && spec.capability !== capability) continue;
+    let content = '';
+    try { content = fs.readFileSync(spec.source, 'utf8'); } catch { continue; }
+    const matches = content.match(/^#####\s*场景[：:]/gm);
+    if (matches) specScenarios += matches.length;
+  }
+  const dataDir = getDataDir(normalizedRoot);
+  const events = readEvents(dataDir, changeName);
+  const testEvents = getTestEvents(events);
+  let testCount = 0;
+  if (testEvents.length > 0) {
+    // 优先取真正含 test_results 的事件（排除 stage_end(test) 等无 results 的事件）；
+    // 都无 results 时退回最新 test 事件（testCount 保持 0）
+    const withResults = testEvents.filter(e => getTestResults(e) != null);
+    const pool = withResults.length > 0 ? withResults : testEvents;
+    const latest = pool.slice().sort((a, b) => timestampMs(a) - timestampMs(b)).pop();
+    const tr = getTestResults(latest);
+    if (tr) testCount = (Number(tr.passed) || 0) + (Number(tr.failed) || 0);
+  }
+  return { ok: specScenarios === testCount, spec: specScenarios, test: testCount };
+}
+
+function cmdValidateScenario(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'];
+  if (!changeName) {
+    console.error('错误: 缺少 --change 参数');
+    process.exit(1);
+  }
+  const result = validateScenarioCoverage(projectRoot, changeName, capability);
+  console.log(JSON.stringify(result, null, 2));
+  return result;
+}
+
+/** 扫描 src/+test/ 源文件快照（跳过 node_modules/dist/.git/build），返回 {relPath: {hash, lines}} */
+function scanSourceFiles(projectRoot) {
+  const result = {};
+  const scanDir = (dir, relBase) => {
+    if (!fs.existsSync(dir)) return;
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      if (entry.name === 'node_modules' || entry.name === 'dist' || entry.name === '.git' || entry.name === 'build') continue;
+      const full = path.join(dir, entry.name);
+      const rel = relBase ? `${relBase}/${entry.name}` : entry.name;
+      if (entry.isDirectory()) {
+        scanDir(full, rel);
+      } else if (/\.(js|cjs|mjs|ts|jsx|tsx|py|java|go|rs|rb|php)$/.test(entry.name)) {
+        const content = fs.readFileSync(full, 'utf8');
+        result[rel] = {
+          hash: crypto.createHash('sha1').update(content).digest('hex').slice(0, 16),
+          lines: content.split('\n').length,
+        };
+      }
+    }
+  };
+  scanDir(path.join(projectRoot, 'src'), 'src');
+  scanDir(path.join(projectRoot, 'test'), 'test');
+  scanDir(path.join(projectRoot, 'tests'), 'tests');
+  return result;
+}
+
+/** snapshot 子命令——apply stage_start/end 扫描 src/+test/ 文件快照，end 时输出 added/modified/deleted diff */
+function cmdSnapshot(args) {
+  const projectRoot = normalizeProjectRoot(args.project || args['project-root'] || process.cwd());
+  const changeName = args.change || args['change-name'];
+  const mode = args.mode || args['snapshot-mode'];
+  if (!changeName) { console.error('错误: 缺少 --change 参数'); process.exit(1); }
+  if (mode !== 'start' && mode !== 'end') { console.error('错误: 缺少 --mode=start|end'); process.exit(1); }
+  const stateDir = getStateDir(projectRoot);
+  ensureDir(stateDir);
+  const snapshotFile = path.join(stateDir, `apply-${safeChangeName(changeName)}-snapshot.json`);
+  const current = scanSourceFiles(projectRoot);
+  if (mode === 'start') {
+    fs.writeFileSync(snapshotFile, JSON.stringify(current, null, 2), 'utf8');
+    const result = { mode: 'start', files_scanned: Object.keys(current).length };
+    console.log(JSON.stringify(result, null, 2));
+    return result;
+  }
+  let startSnap = {};
+  try { startSnap = JSON.parse(fs.readFileSync(snapshotFile, 'utf8')); } catch {}
+  const added = [], modified = [], deleted = [];
+  let addedLines = 0, deletedLines = 0;
+  for (const [f, info] of Object.entries(current)) {
+    if (!startSnap[f]) {
+      added.push(f);
+      addedLines += info.lines;
+    } else if (info.hash !== startSnap[f].hash) {
+      modified.push(f);
+      addedLines += Math.max(0, info.lines - (startSnap[f].lines || 0));
+      deletedLines += Math.max(0, (startSnap[f].lines || 0) - info.lines);
+    }
+  }
+  for (const f of Object.keys(startSnap)) {
+    if (!current[f]) {
+      deleted.push(f);
+      deletedLines += startSnap[f].lines || 0;
+    }
+  }
+  const result = { mode: 'end', added_files: added.length, modified_files: modified.length, deleted_files: deleted.length, added_lines: addedLines, deleted_lines: deletedLines, added, modified, deleted };
+  console.log(JSON.stringify(result, null, 2));
+  return result;
+}
+
+/** archive 时聚合 events 生成"变更总结"段追加到 execution-log.md */
+function appendChangeSummary(projectRoot, changeName, events) {
+  try {
+    const changeDir = getChangeDir(projectRoot, changeName);
+    let logsDir = path.join(changeDir, 'logs');
+    if (!fs.existsSync(changeDir)) {
+      const archiveDir = findArchivedChangeDir(projectRoot, changeName);
+      if (archiveDir) logsDir = path.join(archiveDir, 'logs');
+    }
+    ensureDir(logsDir);
+    const file = path.join(logsDir, 'execution-log.md');
+    // 复用 computeChangeMetrics.change_summary，消除 execution-log 与报告的 1 vs 2 不一致（T1.3）
+    const metrics = computeChangeMetrics(changeName, events);
+    const cs = metrics && metrics.change_summary ? metrics.change_summary : null;
+    const stageStartCount = cs ? cs.stage_start_count : events.filter(e => e.type === 'stage_start' && !e.orphan).length;
+    const stageEndCount = cs ? cs.stage_end_count : events.filter(e => e.type === 'stage_end' && !e.orphan).length;
+    const repeatCount = cs ? cs.stage_repeat_count : 0;
+    const testPass = cs ? cs.test_pass : null;
+    const testPassStr = testPass ? `${testPass.passed}/${testPass.passed + testPass.failed}` : '无测试数据';
+    let unchecked = 0;
+    try {
+      const archiveDir = findArchivedChangeDir(projectRoot, changeName);
+      const tc = archiveDir
+        ? scanTaskCompletionForArchiveDir(projectRoot, changeName, archiveDir)
+        : scanTaskCompletion(projectRoot, changeName);
+      unchecked = tc.has_incomplete ? tc.incomplete : 0;
+    } catch {}
+    const summary = [
+      '',
+      '## 变更总结',
+      `- 阶段数：${stageStartCount} start / ${stageEndCount} end`,
+      `- 阶段重复执行次数：${repeatCount}`,
+      `- 测试通过率：${testPassStr}`,
+      `- 遗留问题：${unchecked > 0 ? `${unchecked} 项验收标准未勾选` : '无'}`,
+      '',
+    ].join('\n');
+    fs.appendFileSync(file, summary + '\n', 'utf8');
+  } catch (err) {
+    try { console.error(`[telemetry] 变更总结追加失败（不阻塞）: ${err.message}`); } catch {}
+  }
+}
+
 /**
  * 从事件文件中查找 start 事件（因为 CLI 无状态，需要从文件回溯）
  */
@@ -2362,6 +3966,47 @@ function searchEventInDataDir(dataDir, eventId) {
   return null;
 }
 
+/** 按 event_id 读取所有 stage_end 事件（用于 cmdEnd 幂等性保护） */
+function readAllEventEndsById(dataDir, eventId, changeName) {
+  if (!eventId) return [];
+  const eventsDir = path.join(dataDir, 'events');
+  if (!fs.existsSync(eventsDir)) return [];
+  const ends = [];
+
+  const scanDir = (dir) => {
+    if (!fs.existsSync(dir)) return;
+    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_end') {
+            ends.push(event);
+          }
+        } catch {}
+      }
+    }
+  };
+
+  // 优先扫描指定 change 目录，命中即返回
+  if (changeName) {
+    scanDir(path.join(eventsDir, changeName));
+    if (ends.length > 0) return ends;
+  }
+
+  // 未命中时回退全量扫描
+  try {
+    const changeDirs = fs.readdirSync(eventsDir).filter(d => {
+      return fs.statSync(path.join(eventsDir, d)).isDirectory();
+    });
+    for (const changeDir of changeDirs) {
+      scanDir(path.join(eventsDir, changeDir));
+    }
+  } catch {}
+  return ends;
+}
+
 /**
  * log metrics: 查询度量指标
  */
@@ -2414,7 +4059,7 @@ function cmdReport(args) {
   const capability = args.capability || args['capability-name'];
   const dateFrom = args['date-from'];
   const dateTo = args['date-to'];
-  const format = args.format || 'markdown';
+  const format = args.format || 'html';
   const outputPath = args.output || args['output-file'];
   const level = args.level || (capability ? 'capability' : (changeName ? 'change' : 'project'));
 
@@ -2429,7 +4074,9 @@ function cmdReport(args) {
   });
   const rendered = format === 'json'
     ? JSON.stringify(report, null, 2)
-    : renderExecutiveReportMarkdown(report);
+    : format === 'html'
+      ? renderExecutiveReportHtml(report)
+      : renderExecutiveReportMarkdown(report);
 
   if (outputPath) {
     const resolvedOutput = path.isAbsolute(outputPath)
@@ -2461,7 +4108,7 @@ function cmdDoctor(args) {
   let events = changeName ? readEvents(dataDir, changeName) : readAllEvents(dataDir);
   events = filterEventsByDate(events, dateFrom, dateTo);
 
-  const report = computeDoctorReport(events, { change: changeName });
+  const report = computeDoctorReport(events, { change: changeName, projectRoot });
   console.log(JSON.stringify(report, null, 2));
   if (report.severe_issues.length > 0) {
     process.exitCode = 1;
@@ -2492,8 +4139,7 @@ function cmdTasksStatus(args) {
 function cmdArchiveDocs(args) {
   const projectRoot = normalizeProjectRoot(args.project || args['project-root'] || process.cwd());
   const changeName = args.change || args['change-name'];
-  const reportOutput = args['report-output'] || args.report_output ||
-    (changeName ? path.join('skywalk-sdd', 'reports', `${safeChangeName(changeName)}-report.md`) : undefined);
+  const reportOutput = args['report-output'] || args.report_output || '';
 
   try {
     let result;
@@ -2507,7 +4153,7 @@ function cmdArchiveDocs(args) {
     } else {
       const repaired = ensureArchiveSuccessArtifacts(projectRoot, changeName, {
         archive_result: {
-          reason: args.reason || '',
+          reason: '',
           report_path: reportOutput,
         },
       }, {
@@ -2529,6 +4175,8 @@ function cmdArchiveDocs(args) {
     if (!args['keep-active']) {
       stageEnd = cmdEnd({
         ...args,
+        // 归档原因（args.reason）走 details.archive_result.reason，不应作为 cmdEnd 的返工 --reason（枚举）传入
+        reason: undefined,
         project: projectRoot,
         command: 'archive',
         change: changeName,
@@ -2537,7 +4185,7 @@ function cmdArchiveDocs(args) {
         details: {
           ...(args.details && typeof args.details === 'object' ? args.details : {}),
           archive_result: {
-            reason: args.reason || '',
+            reason: result.reason || args.reason || '',
             method: result.method,
             archive_path: result.archive_path,
             report_path: reportOutput,
@@ -2597,9 +4245,21 @@ function main() {
     case 'tasks-status':
       cmdTasksStatus(flags);
       break;
+    case 'scan':
+      cmdScan(flags);
+      break;
+    case 'validate-scenario':
+      cmdValidateScenario(flags);
+      break;
+    case 'snapshot':
+      cmdSnapshot(flags);
+      break;
     case 'archive-docs':
       cmdArchiveDocs(flags);
       break;
+    case 'check-task':
+      cmdCheckTask(flags);
+      break;
     default:
       showHelp();
       process.exit(1);
@@ -2614,8 +4274,9 @@ 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] [--output=<file>]
+  node skywalk-sdd/log.cjs report  --project=<path> [--change=<name>] [--format=html|markdown|json] [--output=<file>]（默认 html）
   node skywalk-sdd/log.cjs tasks-status --project=<path> --change=<name> [--require-complete]
+  node skywalk-sdd/log.cjs check-task --project=<path> --change=<name> --task-id=<id>
   node skywalk-sdd/log.cjs archive-docs --project=<path> --change=<name> [--reason=<text>] [--event-id=<id>] [--report-output=<file>]
 
 子命令:
@@ -2626,21 +4287,24 @@ SDD Telemetry CLI - 流程度量采集工具
   report   生成只读度量报告（不写入事件）
   doctor   诊断 Telemetry 数据质量
   tasks-status 扫描 Full/Simple 模式 tasks.md 勾选状态
+  check-task 扫描变更目录 tasks.md 并勾选指定 task_id
   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 record --type=task_update --command=apply --project=/my/project --change=user-auth --task-id=TASK-01 --status=completed --keep-details
+  node skywalk-sdd/log.cjs record --type=conformance_review --command=check --project=/my/project --change=user-auth --source=manual --details-file=skywalk-sdd/state/user-auth-conformance-review.json --keep-details
+  node skywalk-sdd/log.cjs record --type=ai_adoption_review --command=apply --project=/my/project --change=user-auth --status=final --details-file=skywalk-sdd/state/user-auth-ai-adoption.json --keep-details
+  node skywalk-sdd/log.cjs record --type=survey_result --project=/my/project --change=user-auth --source=manual --details-file=skywalk-sdd/state/user-auth-survey.json --keep-details
   node skywalk-sdd/log.cjs metrics --project=/my/project --change=user-auth
   node skywalk-sdd/log.cjs metrics --project=/my/project --change=user-auth --pdf-mvp --format=markdown
   node skywalk-sdd/log.cjs report --project=/my/project --change=user-auth --format=markdown
   node skywalk-sdd/log.cjs doctor --project=/my/project --change=user-auth
   node skywalk-sdd/log.cjs tasks-status --project=/my/project --change=user-auth --require-complete
-  node skywalk-sdd/log.cjs archive-docs --project=/my/project --change=user-auth --reason="变更已完成实施" --event-id=evt_archive --report-output=skywalk-sdd/reports/user-auth-report.md
+  node skywalk-sdd/log.cjs check-task --project=/my/project --change=user-auth --task-id=TASK-01
+  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 子命令）:
@@ -2656,6 +4320,7 @@ module.exports = {
   parseArgs,
   cmdStart,
   cmdEnd,
+  cmdCheckTask,
   cmdRecord,
   cmdMetrics,
   cmdReport,
@@ -2669,6 +4334,11 @@ module.exports = {
   computePdfMvpMetrics,
   renderPdfMvpMarkdown,
   renderExecutiveReportMarkdown,
+  renderExecutiveReportHtml,
+  formatMsHuman,
+  formatMsToSeconds,
+  formatDuration,
+  formatReworkReasons,
   buildReport,
   computeGitDocumentMetrics,
   getCheckResults,
@@ -2676,6 +4346,8 @@ module.exports = {
   getTestResults,
   getTaskUpdateResult,
   computeAiFirstPassMetrics,
+  extractProcessNotes,
+  extractStageTimeline,
   getSpecTestCoverage,
   getSpecTestCoverageEvents,
   computeSpecTestCoverageMetrics,
@@ -2690,6 +4362,12 @@ module.exports = {
   computeManualInsightMetrics,
   computeDoctorReport,
   scanTaskCompletion,
+  cmdScan,
+  cmdValidateScenario,
+  validateScenarioCoverage,
+  parseTestTap,
+  cmdSnapshot,
+  appendChangeSummary,
   archiveChangeDocs,
   filterEventsByDate,
   readEvents,
@@ -2705,6 +4383,7 @@ module.exports = {
   findActiveStage,
   clearActiveStage,
   findStartEvent,
+  runCheckTaskSync,
 };
 
 // 直接运行时执行