kld-sdd 2.6.11 → 2.6.13

package/skywalk-sdd/index.cjs

@@ -16,6 +16,7 @@ const path = require('path');
 const { resolveProjectArg } = require('./ontology/resolve-spec-root.cjs');
 const crypto = require('crypto');
 const { execFileSync } = require('child_process');
+const metricsV3 = require('./metrics-v3.cjs');
 
 const SCHEMA_VERSION = 2;
 
@@ -53,6 +54,8 @@ function getStateDir(projectRoot) {
 // SDD 标准阶段顺序
 const STAGE_ORDER = ['propose', 'spec', 'design', 'task', 'check', 'apply', 'test', 'archive', 'explore'];
 const CORE_STAGES = ['propose', 'spec', 'design', 'apply', 'test'];
+const MEASUREMENT_STAGES = ['propose', 'spec', 'design', 'task', 'check', 'apply', 'archive'];
+const AUXILIARY_STAGES = ['test', 'explore'];
 
 // ── 工具函数 ──────────────────────────────────────────
 function ensureDir(dirPath) {
@@ -149,6 +152,37 @@ function safeChangeName(name) {
   return name.replace(/[^a-zA-Z0-9_-]/g, '-').replace(/^-+|-+$/g, '') || 'general';
 }
 
+function atomicWriteText(filePath, content) {
+  ensureDir(path.dirname(filePath));
+  const tempPath = `${filePath}.${process.pid}.${crypto.randomBytes(4).toString('hex')}.tmp`;
+  let fd;
+  try {
+    fd = fs.openSync(tempPath, 'w');
+    fs.writeFileSync(fd, content, 'utf8');
+    fs.fsyncSync(fd);
+    fs.closeSync(fd);
+    fd = null;
+    fs.renameSync(tempPath, filePath);
+  } catch (error) {
+    if (fd != null) {
+      try { fs.closeSync(fd); } catch {}
+    }
+    try { fs.rmSync(tempPath, { force: true }); } catch {}
+    throw error;
+  }
+}
+
+function requireValidChangeName(name) {
+  if (typeof name === 'string'
+      && (path.isAbsolute(name) || /[\\/]/.test(name) || name === '.' || name === '..')) {
+    fail('E_PATH_OUTSIDE_CHANGE: change 路径不能超出 openspec/changes');
+  }
+  if (typeof name !== 'string' || !name || safeChangeName(name) !== name) {
+    fail(`E_CHANGE_NAME_INVALID: change 名称仅允许字母、数字、下划线和连字符，且不能以连字符开头或结尾`);
+  }
+  return name;
+}
+
 function getActiveStageKey(criteria) {
   if (criteria.session_id) {
     return `session-${safeChangeName(criteria.session_id)}`;
@@ -188,7 +222,7 @@ function findActiveStage(projectRoot, criteria) {
   const exactFile = getActiveStageFile(projectRoot, criteria);
   if (fs.existsSync(exactFile)) {
     const exact = readStateFile(exactFile);
-    if (exact) return exact;
+    if (exact && activeStageMatches(exact, criteria)) return exact;
   }
 
   const stateDir = getStateDir(projectRoot);
@@ -246,6 +280,16 @@ function findActiveStage(projectRoot, criteria) {
   return null;
 }
 
+function activeStageMatches(event, criteria = {}) {
+  if (!event) return false;
+  if (criteria.session_id && event.session_id !== criteria.session_id) return false;
+  if (criteria.change && event.change !== criteria.change) return false;
+  if (criteria.command && event.command !== criteria.command) return false;
+  if (criteria.agent_type && event.agent_type !== criteria.agent_type) return false;
+  if (criteria.capability && event.capability !== criteria.capability) return false;
+  return true;
+}
+
 function clearActiveStage(projectRoot, event) {
   const files = [
     getActiveStageFile(projectRoot, event),
@@ -301,7 +345,28 @@ function nextAvailableDir(baseDir, preferredName) {
 }
 
 function getChangeDir(projectRoot, changeName) {
-  return path.join(projectRoot, 'openspec', 'changes', changeName);
+  const changesRoot = path.resolve(projectRoot, 'openspec', 'changes');
+  const changeDir = path.resolve(changesRoot, changeName);
+  if (changeDir === changesRoot || !changeDir.startsWith(`${changesRoot}${path.sep}`)) {
+    throw new Error('E_PATH_OUTSIDE_CHANGE: change 路径超出 openspec/changes');
+  }
+  for (const candidate of [
+    path.resolve(projectRoot, 'openspec'),
+    changesRoot,
+    changeDir,
+  ]) {
+    if (fs.existsSync(candidate) && fs.lstatSync(candidate).isSymbolicLink()) {
+      throw new Error(`E_PATH_OUTSIDE_CHANGE: change 路径不能经过符号链接或 junction: ${candidate}`);
+    }
+  }
+  if (fs.existsSync(changesRoot) && fs.existsSync(changeDir)) {
+    const canonicalRoot = fs.realpathSync.native(changesRoot);
+    const canonicalChange = fs.realpathSync.native(changeDir);
+    if (!canonicalChange.startsWith(`${canonicalRoot}${path.sep}`)) {
+      throw new Error('E_PATH_OUTSIDE_CHANGE: change 的真实路径超出 openspec/changes');
+    }
+  }
+  return changeDir;
 }
 
 function getArchiveRoot(projectRoot) {
@@ -316,36 +381,142 @@ function discoverTaskFiles(projectRoot, changeName) {
   }).sort();
 }
 
+function checklistEntriesOutsideCodeFences(lines) {
+  const entries = [];
+  let inCodeFence = false;
+  lines.forEach((line, index) => {
+    if (/^\s*```/.test(line)) {
+      inCodeFence = !inCodeFence;
+      return;
+    }
+    if (inCodeFence) return;
+    const match = line.match(/^\s*-\s*\[([ xX])\]\s*(.*)$/);
+    if (!match || match[2].trim() === '无') return;
+    entries.push({
+      checked: /[xX]/.test(match[1]),
+      line: index + 1,
+      text: match[2].trim(),
+      raw: line,
+    });
+  });
+  return entries;
+}
+
+function checkboxTokensOutsideCodeFences(lines) {
+  const entries = [];
+  let inCodeFence = false;
+  lines.forEach((line, index) => {
+    if (/^\s*```/.test(line)) {
+      inCodeFence = !inCodeFence;
+      return;
+    }
+    if (inCodeFence) return;
+    if (/\[[xX]\]/.test(line)) {
+      entries.push({ checked: true, line: index + 1, raw: line });
+      return;
+    }
+    if (/\[\s\]/.test(line)) {
+      const afterCheckbox = line.replace(/^\s*-\s*\[\s\]\s*/, '').trim();
+      if (afterCheckbox !== '无') {
+        entries.push({ checked: false, line: index + 1, raw: line });
+      }
+    }
+  });
+  return entries;
+}
+
 function scanTaskCompletionFromFiles(projectRoot, changeName, taskFiles) {
   const normalizedRoot = normalizeProjectRoot(projectRoot);
   const files = [];
   let completed = 0;
   let incomplete = 0;
   const incompleteItems = [];
+  const primaryTasks = [];
+  const acceptanceItems = [];
+  let structuredTaskCount = 0;
 
   for (const filePath of taskFiles) {
     const relPath = path.relative(normalizedRoot, filePath).replace(/\\/g, '/');
     const lines = fs.readFileSync(filePath, 'utf8').split(/\r?\n/);
     let fileCompleted = 0;
     let fileIncomplete = 0;
+    let currentTask = null;
+    let inCodeFence = false;
+
+    const finishTask = () => {
+      if (!currentTask) return;
+      if (currentTask.statuses.length > 0) structuredTaskCount += 1;
+      const completedStatus = currentTask.statuses.length === 1 && currentTask.statuses[0].checked;
+      primaryTasks.push({
+        task_id: currentTask.taskId,
+        file: relPath,
+        line: currentTask.line,
+        completed: completedStatus,
+        ambiguous: currentTask.statuses.length !== 1,
+        status_count: currentTask.statuses.length,
+      });
+      currentTask = null;
+    };
 
-    lines.forEach((line, index) => {
-      if (/\[[xX]\]/.test(line)) {
+    const checkboxTokens = checkboxTokensOutsideCodeFences(lines);
+    for (const entry of checkboxTokens) {
+      if (entry.checked) {
         completed += 1;
         fileCompleted += 1;
-      } else if (/\[\s\]/.test(line)) {
-        // P2-1: `- [ ] 无` 是占位符（表示"无文档更新/无风险/无遗留"），不计入 incomplete
-        const afterCheckbox = line.replace(/^\s*-\s*\[\s\]\s*/, '').trim();
-        if (afterCheckbox === '无') return;
+      } else {
         incomplete += 1;
         fileIncomplete += 1;
         incompleteItems.push({
           file: relPath,
+          line: entry.line,
+          text: entry.raw.trim(),
+        });
+      }
+    }
+
+    lines.forEach((line, index) => {
+      if (/^\s*```/.test(line)) {
+        inCodeFence = !inCodeFence;
+        return;
+      }
+      if (inCodeFence) return;
+      const taskHeader = line.match(/^###\s*\[([^\]]+)\]/);
+      if (taskHeader) {
+        finishTask();
+        currentTask = {
+          taskId: taskHeader[1].trim(),
+          line: index + 1,
+          statuses: [],
+        };
+        return;
+      }
+      if (/^###\s/.test(line)) {
+        finishTask();
+        return;
+      }
+      if (!currentTask) return;
+
+      const statusMatch = line.match(/^\s*(?:-\s*)?\*\*状态\*\*\s*[:：]\s*\[([ xX])\]\s*(.*)$/);
+      if (statusMatch) {
+        currentTask.statuses.push({
+          checked: /[xX]/.test(statusMatch[1]),
           line: index + 1,
           text: line.trim(),
         });
+        return;
+      }
+      const acceptanceMatch = line.match(/^\s*-\s*\[([ xX])\]\s*(.*)$/);
+      if (acceptanceMatch && acceptanceMatch[2].trim() !== '无') {
+        acceptanceItems.push({
+          task_id: currentTask.taskId,
+          file: relPath,
+          line: index + 1,
+          confirmed: /[xX]/.test(acceptanceMatch[1]),
+          text: acceptanceMatch[2].trim(),
+        });
       }
     });
+    finishTask();
 
     files.push({
       path: relPath,
@@ -355,6 +526,37 @@ function scanTaskCompletionFromFiles(projectRoot, changeName, taskFiles) {
     });
   }
 
+  const taskIdCounts = new Map();
+  for (const task of primaryTasks) {
+    taskIdCounts.set(task.task_id, (taskIdCounts.get(task.task_id) || 0) + 1);
+  }
+  for (const task of primaryTasks) {
+    if ((taskIdCounts.get(task.task_id) || 0) > 1) {
+      task.completed = false;
+      task.ambiguous = true;
+      task.ambiguity_reason = 'duplicate-task-id';
+    }
+  }
+
+  const useLegacyFallback = structuredTaskCount === 0;
+  const normalizedPrimaryTasks = useLegacyFallback
+    ? files.flatMap((file) => {
+      const sourceLines = fs.readFileSync(path.resolve(normalizedRoot, file.path), 'utf8').split(/\r?\n/);
+      return checklistEntriesOutsideCodeFences(sourceLines).map(entry => ({
+          task_id: null,
+          file: file.path,
+          line: entry.line,
+          completed: entry.checked,
+          ambiguous: false,
+          status_count: 1,
+        }));
+    })
+    : primaryTasks;
+  const primaryCompleted = normalizedPrimaryTasks.filter(task => task.completed).length;
+  const primaryIncomplete = normalizedPrimaryTasks.length - primaryCompleted;
+  const acceptanceConfirmed = acceptanceItems.filter(item => item.confirmed).length;
+  const acceptanceUnconfirmed = acceptanceItems.length - acceptanceConfirmed;
+
   return {
     change: changeName,
     task_files: files,
@@ -363,6 +565,23 @@ function scanTaskCompletionFromFiles(projectRoot, changeName, taskFiles) {
     total: completed + incomplete,
     has_incomplete: incomplete > 0,
     incomplete_items: incompleteItems,
+    primary_tasks: {
+      completed: primaryCompleted,
+      incomplete: primaryIncomplete,
+      total: normalizedPrimaryTasks.length,
+      has_incomplete: primaryIncomplete > 0,
+      status: primaryIncomplete > 0 ? 'incomplete' : 'complete',
+      ambiguous: normalizedPrimaryTasks.filter(task => task.ambiguous).length,
+      parser: useLegacyFallback ? 'legacy-fallback' : 'structured-status',
+      tasks: normalizedPrimaryTasks,
+    },
+    acceptance_evidence: {
+      confirmed: acceptanceConfirmed,
+      unconfirmed: acceptanceUnconfirmed,
+      total: acceptanceItems.length,
+      status: acceptanceUnconfirmed > 0 ? 'pending' : 'confirmed',
+      items: acceptanceItems,
+    },
   };
 }
 
@@ -395,25 +614,60 @@ function scanTaskCompletionForArchiveDir(projectRoot, changeName, archiveDir) {
 
 // ── check-task 子命令辅助函数 ─────────────────────────────
 
-/** 在 tasks.md 文件中定位并勾选指定 task_id 的 checkbox */
-function checkTaskInFile(filePath, taskId, dryRun = false) {
+function inspectTaskInFile(filePath, taskId) {
   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) => {
+  let inCodeFence = false;
+  const headerIndexes = [];
+  const statusIndexes = [];
+  lines.forEach((line, index) => {
+    if (/^\s*```/.test(line)) {
+      inCodeFence = !inCodeFence;
+      return;
+    }
+    if (inCodeFence) return;
     if (/^###\s/.test(line)) {
       inTaskSection = taskHeaderRe.test(line);
+      if (inTaskSection) headerIndexes.push(index);
     }
-    if (inTaskSection && (/^\s*-\s*\[\s\]/.test(line) || /^\s*\*\*状态\*\*:\s*\[\s\]/.test(line))) {
-      changed = true;
-      return line.replace(/\[ \]/, '[x]');
+    if (inTaskSection && /^\s*(?:-\s*)?\*\*状态\*\*\s*[:：]\s*\[[ xX]\]/.test(line)) {
+      statusIndexes.push(index);
     }
-    return line;
   });
+  return { content, eol, lines, headerIndexes, statusIndexes };
+}
+
+/** 在 tasks.md 文件中定位并勾选指定 task_id 的唯一状态行 */
+function checkTaskInFile(filePath, taskId, dryRun = false) {
+  const inspection = inspectTaskInFile(filePath, taskId);
+  const { content, eol, lines, headerIndexes, statusIndexes } = inspection;
+  if (headerIndexes.length !== 1) {
+    return {
+      changed: false,
+      linesChanged: 0,
+      reason: headerIndexes.length === 0 ? 'task-id-not-found' : 'task-id-ambiguous',
+    };
+  }
+  if (statusIndexes.length !== 1) {
+    return {
+      changed: false,
+      linesChanged: 0,
+      reason: statusIndexes.length === 0 ? 'status-line-missing' : 'status-line-ambiguous',
+    };
+  }
+  const statusIndex = statusIndexes[0];
+  if (/\[[xX]\]/.test(lines[statusIndex])) {
+    return { changed: false, linesChanged: 0, reason: 'already-completed' };
+  }
+  const newLines = lines.slice();
+  newLines[statusIndex] = newLines[statusIndex]
+    .replace(/\[ \]/, '[x]')
+    .replace(/(\[x\])(?:\s+未完成)?\s*$/, '$1 已完成');
+  const changed = true;
   if (changed && !dryRun) {
     fs.writeFileSync(filePath, newLines.join(eol), 'utf8');
   }
@@ -427,16 +681,42 @@ function runCheckTaskSync(projectRoot, changeName, taskId, dryRun = false) {
   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 };
+  const inspections = taskFiles.map(filePath => ({
+    filePath,
+    inspection: inspectTaskInFile(filePath, taskId),
+  }));
+  const headerCount = inspections.reduce(
+    (total, item) => total + item.inspection.headerIndexes.length,
+    0,
+  );
+  if (headerCount === 0) {
+    const error = new Error(`TASK_ID_NOT_FOUND: 未找到任务 "${taskId}"`);
+    error.code = 'TASK_ID_NOT_FOUND';
+    throw error;
+  }
+  if (headerCount !== 1) {
+    const error = new Error(`TASK_ID_AMBIGUOUS: 任务 "${taskId}" 在 change 中出现 ${headerCount} 次`);
+    error.code = 'TASK_ID_AMBIGUOUS';
+    throw error;
+  }
+  const target = inspections.find(item => item.inspection.headerIndexes.length === 1);
+  if (target.inspection.statusIndexes.length !== 1) {
+    const code = target.inspection.statusIndexes.length === 0
+      ? 'TASK_STATUS_MISSING'
+      : 'TASK_STATUS_AMBIGUOUS';
+    const error = new Error(`${code}: 任务 "${taskId}" 必须恰好有一条状态行`);
+    error.code = code;
+    throw error;
+  }
+  const result = checkTaskInFile(target.filePath, taskId, dryRun);
+  return {
+    changed: result.changed,
+    changed_files: result.changed
+      ? [path.relative(normalizedRoot, target.filePath).replace(/\\/g, '/')]
+      : [],
+    task_files_checked: taskFiles.length,
+    reason: result.reason,
+  };
 }
 
 /** check-task 子命令 CLI */
@@ -494,13 +774,146 @@ function findArchivedChangeDir(projectRoot, changeName) {
   const archiveRoot = getArchiveRoot(projectRoot);
   if (!fs.existsSync(archiveRoot)) return null;
 
-  const prefix = `-${changeName}`;
+  const escapedChangeName = String(changeName).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const exactArchiveName = new RegExp(`^(\\d{4}-\\d{2}-\\d{2})-${escapedChangeName}(?:-(\\d+))?$`);
   const candidates = fs.readdirSync(archiveRoot, { withFileTypes: true })
-    .filter(entry => entry.isDirectory() && entry.name.includes(prefix))
-    .map(entry => path.join(archiveRoot, entry.name))
-    .sort((a, b) => fs.statSync(b).mtimeMs - fs.statSync(a).mtimeMs);
+    .filter(entry => entry.isDirectory())
+    .map(entry => {
+      const match = entry.name.match(exactArchiveName);
+      if (!match) return null;
+      const archivePath = path.join(archiveRoot, entry.name);
+      return {
+        path: archivePath,
+        date: match[1],
+        suffix: match[2] ? Number(match[2]) : 1,
+        mtimeMs: fs.statSync(archivePath).mtimeMs,
+      };
+    })
+    .filter(Boolean)
+    .sort((a, b) => (
+      b.date.localeCompare(a.date)
+      || b.suffix - a.suffix
+      || b.mtimeMs - a.mtimeMs
+    ));
+
+  return candidates[0]?.path || null;
+}
+
+// V3: 统一解析变更文档根目录（active 优先，找不到再找 archive），供场景计数/变更类型读取复用
+function resolveChangeDocumentRoot(projectRoot, changeName) {
+  const activeDir = getChangeDir(projectRoot, changeName);
+  if (fs.existsSync(activeDir)) {
+    return { root: activeDir, source: 'active' };
+  }
+  const archiveDir = findArchivedChangeDir(projectRoot, changeName);
+  if (archiveDir) {
+    return { root: archiveDir, source: 'archive' };
+  }
+  return { root: null, source: null };
+}
+
+// V3: 收集一个变更目录下的 spec.md 文件（优先 specs/**/spec.md，Simple 模式 fallback 根 spec.md）
+function collectSpecFiles(changeRoot) {
+  if (!changeRoot || !fs.existsSync(changeRoot)) return [];
+  const specsDir = path.join(changeRoot, 'specs');
+  if (fs.existsSync(specsDir) && fs.statSync(specsDir).isDirectory()) {
+    return walkFiles(specsDir, filePath => path.basename(filePath).toLowerCase() === 'spec.md').sort();
+  }
+  const rootSpec = path.join(changeRoot, 'spec.md');
+  if (fs.existsSync(rootSpec)) return [rootSpec];
+  return [];
+}
+
+// V3 E1: 统计变更规约文档中的场景数（##### 场景/Scenario：标题计数），按绝对路径去重
+function countSpecScenarios(projectRoot, changeName) {
+  const { root, source } = resolveChangeDocumentRoot(projectRoot, changeName);
+  if (!root) {
+    return { scenario_count: 0, files: [], source: null, root: null, availability_reason: 'change-not-found' };
+  }
+  const specFiles = collectSpecFiles(root);
+  if (specFiles.length === 0) {
+    return {
+      scenario_count: 0,
+      files: [],
+      source,
+      root: toProjectRelative(projectRoot, root),
+      availability_reason: 'no-spec-files',
+    };
+  }
+  const seen = new Set();
+  const files = [];
+  let total = 0;
+  for (const filePath of specFiles) {
+    const abs = path.resolve(filePath);
+    if (seen.has(abs)) continue;
+    seen.add(abs);
+    let text = '';
+    try { text = fs.readFileSync(abs, 'utf8'); } catch { text = ''; }
+    const count = metricsV3.countScenariosInMarkdown(text);
+    total += count;
+    files.push({ path: toProjectRelative(projectRoot, abs), count });
+  }
+  return { scenario_count: total, files, source, root: toProjectRelative(projectRoot, root) };
+}
+
+// 极简 yaml-like frontmatter 解析：仅支持 --- 围栏内的单行 key: value（够用，不引入外部 yaml 依赖）
+function parseSimpleFrontmatter(text) {
+  if (typeof text !== 'string' || !text) return {};
+  const normalized = text.replace(/\r\n/g, '\n');
+  const match = /^---\n([\s\S]*?)\n---/.exec(normalized);
+  if (!match) return {};
+  const result = {};
+  for (const line of match[1].split('\n')) {
+    const kv = /^([A-Za-z0-9_-]+):\s*(.*)$/.exec(line.trim());
+    if (!kv) continue;
+    let value = kv[2].trim();
+    if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
+      value = value.slice(1, -1);
+    }
+    result[kv[1]] = value;
+  }
+  return result;
+}
+
+// V3: 从 proposal.md frontmatter 读取 change-type（active 优先，缺失/非法/找不到 → unknown）
+function readChangeType(projectRoot, changeName) {
+  const { root } = resolveChangeDocumentRoot(projectRoot, changeName);
+  if (!root) return 'unknown';
+  const proposalPath = path.join(root, 'proposal.md');
+  if (!fs.existsSync(proposalPath)) return 'unknown';
+  let text = '';
+  try { text = fs.readFileSync(proposalPath, 'utf8'); } catch { return 'unknown'; }
+  const frontmatter = parseSimpleFrontmatter(text);
+  return metricsV3.validateChangeType(frontmatter['change-type']);
+}
 
-  return candidates[0] || null;
+// V3: 组装喂给 metricsV3.computeV3ChangeMetrics 的 context；executionSummary 提供阶段耗时兜底
+function buildV3ChangeContext(events, executionSummary, options = {}) {
+  const summary = executionSummary?.summary || {};
+  return {
+    change_name: options.change_name || null,
+    change_type: options.change_type || 'unknown',
+    total_stage_duration_ms: options.total_stage_duration_ms ?? summary.total_stage_duration_ms ?? null,
+    canonical_stage_duration_ms: options.canonical_stage_duration_ms ?? summary.effective_stage_duration_ms ?? null,
+    rework_stage_duration_ms: options.rework_stage_duration_ms ?? summary.rework_stage_duration_ms ?? null,
+    scenario_count: options.scenario_count ?? 0,
+    scenario_sources: options.scenario_sources || [],
+    check_results: options.check_results || null,
+    check_meta: options.check_meta || {},
+    q3: options.q3 || undefined,
+    coding_duration_ms: options.coding_duration_ms ?? 0,
+    spec_duration_ms: options.spec_duration_ms ?? 0,
+    rework_coding_duration_ms: options.rework_coding_duration_ms ?? 0,
+    rework_spec_duration_ms: options.rework_spec_duration_ms ?? 0,
+    p4_quality_gate_enforcement_rate: options.p4_quality_gate_enforcement_rate ?? null,
+    p_c_stage_closure_rate: options.p_c_stage_closure_rate ?? null,
+    p_h_telemetry_health_score: options.p_h_telemetry_health_score ?? null,
+    rework_summary: options.rework_summary || {},
+    q1_spec_conformance: options.q1_spec_conformance ?? null,
+    q1_source: options.q1_source || null,
+    q4_tdd_coverage: options.q4_tdd_coverage ?? null,
+    q4_source: options.q4_source || null,
+  };
 }
 
 function syncArchivedSpecs(projectRoot, archiveDir, changeName) {
@@ -601,43 +1014,85 @@ function assertConfirmedArchive(projectRoot, changeName, archiveDir, options = {
 }
 
 function ensureArchiveManifest(projectRoot, changeName, archiveDir, options = {}) {
-  const copiedSpecs = Array.isArray(options.copiedSpecs)
-    ? options.copiedSpecs
-    : syncArchivedSpecs(projectRoot, archiveDir, changeName);
   const committedArchiveDir = options.archivePath || archiveDir;
-  // 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(
+  const prepare = () => {
+    const copiedSpecs = Array.isArray(options.copiedSpecs)
+      ? options.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,
+        path.join(committedArchiveDir, 'evidence', 'events'),
+      );
+    }
+    return {
+      archiveDir,
+      archivePath: committedArchiveDir,
+      packagePath: Object.prototype.hasOwnProperty.call(options, 'packagePath')
+        ? options.packagePath
+        : `${committedArchiveDir}.zip`,
+      archivedAt: options.archivedAt,
+      reason: options.reason || '变更已完成实施',
+      method: options.method || 'skywalk-full-spec-archive',
+      sourcePath: `openspec/changes/${changeName}`,
+      copiedSpecs,
+      evidenceEventsPath,
+    };
+  };
+  const {
+    finalizeArchivePackageAfterReports,
+    materializeArchivePackage,
+  } = require('./ontology/archive-package.cjs');
+  const produced = options.finalizeAfterReports
+    ? finalizeArchivePackageAfterReports({
       projectRoot,
-      path.join(committedArchiveDir, 'evidence', 'events'),
-    );
-  }
-  const { materializeArchivePackage } = require('./ontology/archive-package.cjs');
-  const produced = materializeArchivePackage({
-    projectRoot,
-    changeName,
-    archiveDir,
-    archivePath: committedArchiveDir,
-    packagePath: Object.prototype.hasOwnProperty.call(options, 'packagePath')
-      ? options.packagePath
-      : `${committedArchiveDir}.zip`,
-    archivedAt: options.archivedAt,
-    reason: options.reason || '变更已完成实施',
-    method: options.method || 'skywalk-full-spec-archive',
-    sourcePath: `openspec/changes/${changeName}`,
-    copiedSpecs,
-    evidenceEventsPath,
-  });
+      changeName,
+      runIdentity: options.runIdentity,
+      lockOptions: options.lockOptions,
+      prepare,
+    })
+    : materializeArchivePackage({
+      projectRoot,
+      changeName,
+      ...prepare(),
+    });
   return {
     ...produced,
-    copied_specs: copiedSpecs,
+    copied_specs: produced.manifest.copied_specs || [],
   };
 }
 
+function normalizeKnownReportExtension(reportPath, expectedExtension) {
+  const currentExtension = path.extname(reportPath).toLowerCase();
+  if (['.md', '.html', '.json'].includes(currentExtension) && currentExtension !== expectedExtension) {
+    return reportPath.slice(0, -currentExtension.length) + expectedExtension;
+  }
+  return reportPath;
+}
+
+function taskCompletionArchiveReason(taskCompletion, fallbackReason) {
+  const primary = taskCompletion?.primary_tasks;
+  if (primary?.parser === 'structured-status') {
+    if (primary.has_incomplete) {
+      return `尚有 ${primary.incomplete} 个主任务未完成`;
+    }
+    const pendingEvidence = taskCompletion?.acceptance_evidence?.unconfirmed || 0;
+    if (pendingEvidence > 0) {
+      return `任务已完成；仍有 ${pendingEvidence} 项验收证据待确认`;
+    }
+    return fallbackReason;
+  }
+  if (taskCompletion?.has_incomplete) {
+    return `部分完成（${taskCompletion.incomplete} 项验收未勾选）`;
+  }
+  return fallbackReason;
+}
+
 function ensureArchiveSuccessArtifacts(projectRoot, changeName, details = {}, options = {}) {
   const normalizedRoot = normalizeProjectRoot(projectRoot);
   const activeChangeDir = getChangeDir(normalizedRoot, changeName);
@@ -666,14 +1121,15 @@ function ensureArchiveSuccessArtifacts(projectRoot, changeName, details = {}, op
   assertConfirmedArchive(normalizedRoot, changeName, archiveDir);
 
   // 显式 reportOutput 优先；否则默认落归档后 archive 目录的 reports/ 子目录
-  const reportPath = options.reportOutput
+  const requestedReportPath = options.reportOutput
     ? (path.isAbsolute(options.reportOutput) ? options.reportOutput : path.resolve(normalizedRoot, options.reportOutput))
     : path.join(archiveDir, 'reports', `${safeChangeName(changeName)}-report.md`);
+  const reportPath = normalizeKnownReportExtension(requestedReportPath, '.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} 项验收未勾选）`;
+  if (!details.archive_result?.reason) {
+    archiveReason = taskCompletionArchiveReason(taskCompletion, archiveReason);
   }
   const manifestInfo = ensureArchiveManifest(normalizedRoot, changeName, archiveDir, {
     reason: archiveReason,
@@ -692,9 +1148,6 @@ function ensureArchiveSuccessArtifacts(projectRoot, changeName, details = {}, op
     created_at: manifestInfo.manifest.created_at,
     archive_path: manifestInfo.manifest.archive_path,
     report_path: toProjectRelative(normalizedRoot, reportPath),
-    // report_html_path 为预期路径：由 cmdEnd 落盘阶段写入（try/catch 容错，失败时不阻塞 md 主产物）。
-    // 此处无条件派生，html 实际落盘失败时该路径可能不存在；语义为"预期路径"，消费者不应假定文件已存在。
-    report_html_path: toProjectRelative(normalizedRoot, reportPath.replace(/\.md$/i, '.html')),
     manifest_path: toProjectRelative(normalizedRoot, manifestInfo.manifest_path),
     canonical_facts_path: toProjectRelative(normalizedRoot, manifestInfo.canonical_facts_path),
     conversion_report_path: toProjectRelative(normalizedRoot, manifestInfo.conversion_report_path),
@@ -772,9 +1225,7 @@ function archiveChangeDocs(projectRoot, changeName, options = {}) {
 
     const tcForReason = scanTaskCompletionForArchiveDir(normalizedRoot, changeName, stagingDir);
     let archiveReason = options.reason || '变更已完成实施';
-    if (tcForReason?.has_incomplete) {
-      archiveReason = `部分完成（${tcForReason.incomplete} 项验收未勾选）`;
-    }
+    archiveReason = taskCompletionArchiveReason(tcForReason, archiveReason);
     specTransaction = prepareArchivedSpecSync(
       normalizedRoot,
       stagingDir,
@@ -852,8 +1303,85 @@ function archiveChangeDocs(projectRoot, changeName, options = {}) {
   }
 }
 
-/** 追加一行 JSONL 到事件文件（写入失败时抛出异常） */
-function appendEvent(dataDir, changeName, event) {
+const EVENT_LOCK_WAIT_BUFFER = new Int32Array(new SharedArrayBuffer(4));
+
+function isProcessAlive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return error?.code === 'EPERM';
+  }
+}
+
+function acquireEventWriteLock(dataDir, changeName, options = {}) {
+  const locksDir = path.join(dataDir, 'events', '.locks');
+  ensureDir(locksDir);
+  const lockPath = path.join(locksDir, `${safeChangeName(changeName)}.lock`);
+  const timeoutMs = Math.max(1000, Number(options.timeoutMs || 10000));
+  const staleMs = Math.max(timeoutMs, Number(options.staleMs || 5 * 60 * 1000));
+  const deadline = Date.now() + timeoutMs;
+
+  while (Date.now() <= deadline) {
+    const token = crypto.randomUUID();
+    const payload = {
+      token,
+      pid: process.pid,
+      created_at: nowISO(),
+      change: safeChangeName(changeName),
+    };
+    let descriptor;
+    try {
+      descriptor = fs.openSync(lockPath, 'wx');
+      fs.writeFileSync(descriptor, JSON.stringify(payload), 'utf8');
+      fs.closeSync(descriptor);
+      return { ...payload, path: lockPath };
+    } catch (error) {
+      if (descriptor !== undefined) fs.closeSync(descriptor);
+      if (error?.code !== 'EEXIST') throw error;
+      let existing = null;
+      try {
+        existing = JSON.parse(fs.readFileSync(lockPath, 'utf8'));
+      } catch {}
+      const createdAt = Date.parse(existing?.created_at || '');
+      const stale = !Number.isFinite(createdAt)
+        || Date.now() - createdAt > staleMs
+        || !isProcessAlive(Number(existing?.pid));
+      if (stale) {
+        try { fs.rmSync(lockPath, { force: true }); } catch {}
+        continue;
+      }
+      Atomics.wait(EVENT_LOCK_WAIT_BUFFER, 0, 0, 10);
+    }
+  }
+  const error = new Error(`EVENT_WRITE_LOCK_TIMEOUT: 等待 change "${changeName}" 的事件写锁超时`);
+  error.code = 'EVENT_WRITE_LOCK_TIMEOUT';
+  throw error;
+}
+
+function releaseEventWriteLock(lock) {
+  if (!lock?.path || !lock.token) return false;
+  try {
+    const current = JSON.parse(fs.readFileSync(lock.path, 'utf8'));
+    if (current.token !== lock.token) return false;
+    fs.rmSync(lock.path, { force: true });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function withEventWriteLock(dataDir, changeName, action) {
+  const lock = acquireEventWriteLock(dataDir, changeName);
+  try {
+    return action(lock);
+  } finally {
+    releaseEventWriteLock(lock);
+  }
+}
+
+function appendEventUnlocked(dataDir, changeName, event) {
   const dir = path.join(dataDir, 'events', safeChangeName(changeName));
   ensureDir(dir);
   const file = path.join(dir, `${today()}.jsonl`);
@@ -865,6 +1393,31 @@ function appendEvent(dataDir, changeName, event) {
   appendMarkdownLog(dataDir, changeName, event);
 }
 
+/** 追加一行 JSONL 到事件文件；同一 change 的事实写入和日志投影共享跨进程锁。 */
+function appendEvent(dataDir, changeName, event, options = {}) {
+  if (options.lockHeld) {
+    return appendEventUnlocked(dataDir, changeName, event);
+  }
+  return withEventWriteLock(dataDir, changeName, () => {
+    if (event?.type === 'stage_end') {
+      const existing = readAllEventEndsById(dataDir, event.event_id, changeName);
+      if (existing.length > 0) {
+        const latest = existing.sort((a, b) => timestampMs(b) - timestampMs(a))[0];
+        if (latest.result !== event.result) {
+          const error = new Error(
+            `E_STAGE_END_CONFLICT: event_id "${event.event_id}" 已记录 result=${latest.result}，不能改为 ${event.result}`,
+          );
+          error.code = 'E_STAGE_END_CONFLICT';
+          throw error;
+        }
+        return { idempotent: true, event: latest };
+      }
+    }
+    appendEventUnlocked(dataDir, changeName, event);
+    return { idempotent: false, event };
+  });
+}
+
 /** 把 ISO 时间戳格式化为本地时区 `YYYY-MM-DD HH:mm:ss (UTC±HH:MM)`。
  *  execution-log 面向人读，统一用本地时区 + 显式偏移标注，避免 UTC 裸值与用户体感差 8 小时（N9）。 */
 function formatLocalTimestamp(iso) {
@@ -881,66 +1434,75 @@ function formatLocalTimestamp(iso) {
 
 /** 把事件同步追加为人读 markdown 行到 openspec/changes/<change>/logs/execution-log.md
  *  （telemetry 副本；change 已归档时写入 archive 目录；失败不阻塞 telemetry 主流程） */
+function executionLogEventMarker(event) {
+  return event?.event_id ? `<!-- event:${event.type || 'event'}:${event.event_id} -->` : '';
+}
+
+function formatExecutionLogEntry(event) {
+  const ts = formatLocalTimestamp(event.timestamp || nowISO());
+  const stage = event.command || event.stage || 'unknown';
+  const summary = String(event.summary || '').replace(/\|/g, '/').replace(/\n/g, ' ');
+  const marker = executionLogEventMarker(event);
+  if (event.type === 'process_note') {
+    const kind = event.details?.kind || event.details?.process_note?.kind || 'note';
+    const target = event.details?.target ? ` → ${String(event.details.target).replace(/\|/g, '/')}` : '';
+    const round = Number.isFinite(event.details?.round) ? ` R${event.details.round}` : '';
+    return `- [${ts}] ${stage} 📝 ${kind}${round} | ${summary}${target}${marker ? ` ${marker}` : ''}\n`;
+  }
+  if (event.type === 'check_result') {
+    const dispositions = event.details?.check_results?.warning_dispositions;
+    if (Array.isArray(dispositions) && dispositions.length > 0) {
+      const counts = dispositions.reduce((result, item) => {
+        const key = item.disposition || 'open';
+        result[key] = (result[key] || 0) + 1;
+        return result;
+      }, {});
+      const dispositionText = Object.entries(counts)
+        .map(([key, count]) => `${key}=${count}`)
+        .join(', ');
+      return `- [${ts}] ${stage} check_result → ${RESULT_MARK[event.result] || '📝'}${event.result ? `(${event.result})` : ''} | ${summary} | 告警处置：${dispositionText}${marker ? ` ${marker}` : ''}\n`;
+    }
+  }
+  const type = event.type || 'event';
+  const result = event.result || '';
+  const mark = RESULT_MARK[result] || '📝';
+  return `- [${ts}] ${stage} ${type} → ${mark}${result ? '(' + result + ')' : ''} | ${summary}${marker ? ` ${marker}` : ''}\n`;
+}
+
+function renderExecutionLog(changeName, events) {
+  const sorted = events.slice().sort((a, b) => timestampMs(a) - timestampMs(b));
+  const created = formatLocalTimestamp(sorted[0]?.timestamp || nowISO());
+  return `# 执行日志 — ${changeName}\n\n> 变更创建时间：${created} | 变更名：${changeName}\n\n---\n\n`
+    + sorted.map(formatExecutionLogEntry).join('');
+}
+
 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');
-    }
+    const archiveDir = findArchivedChangeDir(projectRoot, changeName);
+    if (!fs.existsSync(activeChangeDir) && !archiveDir) return;
+
+    const targetChangeDir = fs.existsSync(activeChangeDir) ? activeChangeDir : archiveDir;
+    const logsDir = path.join(targetChangeDir, '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');
+    if (fs.existsSync(file) && !fs.statSync(file).isFile()) {
+      throw new Error(`execution-log 路径不是文件: ${file}`);
     }
-    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');
+
+    const current = fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : '';
+    const hasMarkers = /<!-- event:[^>]+ -->/.test(current);
+    if (!current || !hasMarkers) {
+      const allEvents = readEvents(dataDir, changeName);
+      fs.writeFileSync(file, renderExecutionLog(changeName, allEvents), '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');
+
+    const marker = executionLogEventMarker(event);
+    if (!marker || !current.includes(marker)) {
+      fs.appendFileSync(file, formatExecutionLogEntry(event), 'utf8');
+    }
   } catch (err) {
     // markdown 副本失败不影响 telemetry 主流程，但输出 stderr 提示保留可观测性（避免持续性失败长期静默）
     try { console.error(`[telemetry] execution-log 副本写入失败（不阻塞主流程）: ${err.message}`); } catch {}
@@ -948,7 +1510,7 @@ function appendMarkdownLog(dataDir, changeName, event) {
 }
 
 /** 读取指定 change 的所有事件 */
-function readEvents(dataDir, changeName) {
+function readEventsRaw(dataDir, changeName) {
   try {
     const dir = path.join(dataDir, 'events', safeChangeName(changeName));
     if (!fs.existsSync(dir)) return [];
@@ -1505,76 +2067,143 @@ function compactReworkSummary(summary, reasons) {
   };
 }
 
-// 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) {
+// report-time 推导返工原因：对 summarizeStageExecutions 产出的 reworkAttempts 细化
+// - incomplete/prev-failed/pre-archive-recheck 为确定性判定（不依赖 git/telemetry），保持不变
+// - completed_rework_success（上次成功却重跑）按窗口 [本次 end, 同 key 下一次 start) 推导证据：
+//   1) agent override（stage_end.rework_reason 合法枚举且非占位符 completed_rework_success）优先
+//   2) git log --all --since=window_start [--until=window_end]：窗口内有 commit → code-changed-after-pass
+//   3) 无 git 证据时退化到 metricsV3.findDevelopmentActivities 扫描 scopedEvents 同窗口的开发活动事件
+//   4) 都无证据 → recheck-no-change；委托 metricsV3.deriveSuccessfulReworkReason 统一裁决
+// 注：不再用 working tree 是否 dirty 作为全局证据（当前 dirty 状态无法归因到具体某次窗口，误报风险高）
+function readGitCommitTimeline(projectRoot) {
+  if (!projectRoot || runGit(projectRoot, ['rev-parse', '--is-inside-work-tree']) !== 'true') {
+    return null;
+  }
+  const log = runGit(projectRoot, ['log', '--all', '--format=%H%x09%cI%x09%s']);
+  if (!log) return [];
+  return log.split(/\r?\n/).filter(Boolean).map(line => {
+    const parts = line.split('\t');
+    return {
+      sha: parts[0] || '',
+      timestamp: parts[1] || null,
+      timestamp_ms: Date.parse(parts[1]),
+      subject: parts.slice(2).join('\t'),
+    };
+  }).filter(commit => Number.isFinite(commit.timestamp_ms));
+}
+
+function findGitCommitInWindow(timeline, windowStart, windowEnd) {
+  if (!Array.isArray(timeline) || !windowStart) return null;
+  const startMs = Date.parse(windowStart);
+  const endMs = windowEnd ? Date.parse(windowEnd) : null;
+  if (!Number.isFinite(startMs)) return null;
+  return timeline.find(commit => (
+    commit.timestamp_ms >= startMs
+      && (!Number.isFinite(endMs) || commit.timestamp_ms <= endMs)
+  )) || null;
+}
+
+function resolveGitCommitTimeline(events, projectRoot, providedTimeline) {
+  if (providedTimeline !== undefined) return providedTimeline;
+  const startCounts = new Map();
+  let hasRepeatedStage = false;
+  for (const event of events) {
+    if (event.orphan || event.type !== 'stage_start') continue;
+    const key = `${event.change || ''}|${event.command || ''}|${event.capability || ''}`;
+    const count = (startCounts.get(key) || 0) + 1;
+    startCounts.set(key, count);
+    if (count > 1) {
+      hasRepeatedStage = true;
+      break;
+    }
+  }
+  return hasRepeatedStage ? readGitCommitTimeline(projectRoot) : null;
+}
+
+function deriveReworkReasons(executionSummary, projectRoot, scopedEvents = [], options = {}) {
   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 auxiliaryExecutionSummary = summarizeStageExecutions(
+    scopedEvents.filter(event => AUXILIARY_STAGES.includes(event.command || event.stage)),
+  );
+  const needsGitEvidence = reworkAttempts.some(attempt => attempt.rework_reason === 'completed_rework_success');
+  const gitCommitTimeline = options.gitCommitTimeline !== undefined
+    ? options.gitCommitTimeline
+    : (needsGitEvidence ? readGitCommitTimeline(projectRoot) : null);
+
   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);
   }
+
+  const attemptsByKey = new Map();
+  for (const attempt of executionSummary.attempts || []) {
+    const key = attempt.key || stageAttemptKey(attempt.start);
+    if (!attemptsByKey.has(key)) attemptsByKey.set(key, []);
+    attemptsByKey.get(key).push(attempt);
+  }
+  for (const list of attemptsByKey.values()) {
+    list.sort((a, b) => timestampMs(a.start) - timestampMs(b.start));
+  }
+
   for (const attempt of reworkAttempts) {
     let reason = attempt.rework_reason;
     let detail = null;
-    let hasUncommittedFlag = false;
+    let reasonSource = 'deterministic';
+    let windowStart = null;
+    let windowEnd = null;
+    let evidenceEventIds = [];
+    let evidenceTypes = [];
+
     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';
-        }
+      const endIso = attempt.end && attempt.end.timestamp ? attempt.end.timestamp : null;
+      const endMs = endIso ? Date.parse(endIso) : null;
+      windowStart = Number.isFinite(endMs) ? endIso : null;
+
+      const key = attempt.key || stageAttemptKey(attempt.start);
+      const siblings = attemptsByKey.get(key) || [];
+      const idx = siblings.indexOf(attempt);
+      const nextAttempt = idx >= 0 ? siblings[idx + 1] : null;
+      windowEnd = nextAttempt ? nextAttempt.start.timestamp : null;
+
+      const commit = findGitCommitInWindow(gitCommitTimeline, windowStart, windowEnd);
+      const gitHasCommit = Boolean(commit);
+      const commitMessage = commit?.subject || null;
+
+      let devActivities = [];
+      if (!gitHasCommit) {
+        const endMsForScan = windowEnd ? Date.parse(windowEnd) : null;
+        devActivities = metricsV3.findDevelopmentActivities(scopedEvents, endMs, endMsForScan);
       }
+
+      const derived = metricsV3.deriveSuccessfulReworkReason({
+        base_reason: 'completed_rework_success',
+        agent_override_reason: attempt.end?.rework_reason || null,
+        git_has_commit_in_window: gitHasCommit,
+        dev_activities: devActivities,
+        window: { start: windowStart, end: windowEnd },
+      });
+
+      reason = derived.reason;
+      reasonSource = derived.reason_source;
+      evidenceEventIds = derived.evidence_event_ids || [];
+      evidenceTypes = devActivities.map(e => e.type || e.event_type).filter(Boolean);
+      detail = commitMessage;
     }
-    // T3.6 + Q6: check 在 test 之后重跑（归档前强制复检）→ pre-archive-recheck（不论原 reason）
-    // 判定：attempt 为 check 且 check 的 canonical 开始时间晚于 test 的 canonical 结束时间 → 归档前强制复检
+
+    // T3.6 + Q6: check 在 test 之后重跑（归档前强制复检）→ pre-archive-recheck（不论原 reason，确定性，优先级最高）
     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);
+      const canonicalTest = getCanonicalAttempt(auxiliaryExecutionSummary, 'test', attempt.capability);
       if (canonicalCheck && canonicalCheck.start && canonicalTest && canonicalTest.end
           && timestampMs(canonicalCheck.start) > timestampMs(canonicalTest.end)) {
         reason = 'pre-archive-recheck';
+        reasonSource = 'deterministic';
       }
     }
+
     attempt.rework_reason = reason;
     byCategory[reason] = (byCategory[reason] || 0) + 1;
     const bucket = bucketByKey.get(`${attempt.command}|${attempt.capability || ''}`);
@@ -1585,8 +2214,12 @@ function deriveReworkReasons(executionSummary, projectRoot) {
       command: attempt.command,
       attempt_event_id: (attempt.start && attempt.start.event_id) || null,
       reason,
+      reason_source: reasonSource,
+      window_start: windowStart,
+      window_end: windowEnd,
+      evidence_event_ids: evidenceEventIds,
+      evidence_types: evidenceTypes,
       detail,
-      has_uncommitted: hasUncommittedFlag,
     });
   }
   return { by_category: byCategory, details };
@@ -1615,6 +2248,13 @@ function getCheckResults(event) {
     fixed_before_apply: Number.isFinite(results.fixed_before_apply) ? results.fixed_before_apply : null,
     consistency_score: Number.isFinite(results.consistency_score) ? results.consistency_score : null,
     categories: results.categories || {},
+    // V3 Q3: reviewer 元信息，用于评估 reviewer_independence/score_status（缺失时保持 null，不影响旧字段）
+    reviewer: results.reviewer || null,
+    review_session_id: results.review_session_id || null,
+    author_session_id: results.author_session_id || null,
+    reviewer_independence: results.reviewer_independence || null,
+    warning_items: Array.isArray(results.warning_items) ? results.warning_items : [],
+    warning_dispositions: Array.isArray(results.warning_dispositions) ? results.warning_dispositions : [],
   };
 }
 
@@ -2293,10 +2933,18 @@ function computeGitDocumentMetrics(projectRoot, changeName) {
 function computeSinglePdfMvpMetrics(events, options = {}) {
   const scopedEvents = events
     .filter(e => !e.orphan)
-    .filter(e => !options.change || e.change === options.change)
+    .filter(e => !options.change
+      || e.change === options.change
+      || e.attribution?.target_change === options.change)
     .filter(e => !options.capability || e.capability === options.capability);
-  const executionSummary = summarizeStageExecutions(scopedEvents);
-  const reworkReasons = deriveReworkReasons(executionSummary, options.projectRoot);
+  const measurementEvents = scopedEvents.filter((event) => {
+    const stage = event.command || event.stage;
+    return MEASUREMENT_STAGES.includes(stage);
+  });
+  const executionSummary = summarizeStageExecutions(measurementEvents);
+  const reworkReasons = deriveReworkReasons(executionSummary, options.projectRoot, scopedEvents, {
+    gitCommitTimeline: options.gitCommitTimeline,
+  });
   const starts = executionSummary.canonicalAttempts.map(attempt => attempt.start);
   const ends = executionSummary.canonicalAttempts.map(attempt => attempt.end).filter(Boolean);
 
@@ -2306,11 +2954,13 @@ function computeSinglePdfMvpMetrics(events, options = {}) {
     ? new Date(archiveEnd.timestamp).getTime() - new Date(proposeStart.timestamp).getTime()
     : null;
 
-  const totalStageDuration = executionSummary.summary.effective_stage_duration_ms;
+  const totalStageDuration = executionSummary.summary.total_stage_duration_ms;
   const codingDuration = sumDurations(ends, ['apply']);
   const specDuration = sumDurations(ends, ['propose', 'spec', 'design', 'task']);
   const reworkCodingDuration = sumAttemptDurations(executionSummary.reworkAttempts, ['apply']);
   const reworkSpecDuration = sumAttemptDurations(executionSummary.reworkAttempts, ['propose', 'spec', 'design', 'task']);
+  const codingDurationIncludingRework = codingDuration + reworkCodingDuration;
+  const specDurationIncludingRework = specDuration + reworkSpecDuration;
 
   const formalApplyAttempt = getCanonicalAttempt(executionSummary, 'apply', options.capability);
   const formalApplyEvents = formalApplyAttempt
@@ -2342,9 +2992,20 @@ function computeSinglePdfMvpMetrics(events, options = {}) {
     : null;
   const specIterationSource = gitDocumentMetrics?.source || (gitDocumentMetrics?.git_available ? 'git' : null);
 
-  const firstApply = firstByTimestamp(starts.filter(e => e.command === 'apply'));
+  // P4 的边界必须是第一次实际进入 apply，而不是“最终 canonical apply”。
+  // 否则先 apply 失败、后补 check、再 apply 成功会被误判为门禁前置。
+  const firstApply = firstByTimestamp(
+    executionSummary.attempts
+      .filter(attempt => attempt.command === 'apply')
+      .map(attempt => attempt.start),
+  );
   const qualityGateBeforeApply = firstApply
-    ? checkEvents.some(e => new Date(e.timestamp).getTime() <= new Date(firstApply.timestamp).getTime())
+    ? executionSummary.attempts.some(attempt => (
+      attempt.command === 'check'
+      && attempt.end
+      && ['success', 'partial'].includes(attempt.result)
+      && timestampMs(attempt.end) <= timestampMs(firstApply)
+    ))
     : null;
   const latestCheckWithFixRate = latestByTimestamp(checkEvents.filter(e => {
     const results = getCheckResults(e);
@@ -2360,11 +3021,133 @@ function computeSinglePdfMvpMetrics(events, options = {}) {
   const aiFirstPassMetrics = computeAiFirstPassMetrics(formalApplyEvents.length > 0 ? formalApplyEvents : scopedEvents);
   const specTestCoverageMetrics = computeSpecTestCoverageMetrics(scopedEvents);
 
+  // ── V3 ────────────────────────────────────────────────────────────
+  const scenarioData = (options.projectRoot && options.change)
+    ? countSpecScenarios(options.projectRoot, options.change)
+    : { scenario_count: 0, files: [], source: null, root: null, availability_reason: 'no-change-scope' };
+  const changeType = (options.projectRoot && options.change)
+    ? readChangeType(options.projectRoot, options.change)
+    : 'unknown';
+
+  // Q3: 优先取最新一次 total>0 的 check（而非仅要求带 consistency_score，兼容旧 Q5 逻辑保持不变）
+  const latestCheckWithTotal = latestByTimestamp(checkEvents.filter(e => (getCheckResults(e)?.total ?? 0) > 0));
+  const latestCheckResultsV3 = getCheckResults(latestCheckWithTotal);
+  const checkMeta = {
+    reviewer: latestCheckResultsV3?.reviewer || null,
+    author: formalApplyAttempt?.start?.session_id || formalApplyAttempt?.start?.agent_type || null,
+    reviewer_independence: latestCheckResultsV3?.reviewer_independence || null,
+    review_session_id: latestCheckResultsV3?.review_session_id || null,
+    author_session_id: latestCheckResultsV3?.author_session_id || formalApplyAttempt?.start?.session_id || null,
+  };
+  const q3Result = metricsV3.computeSpecQualityScore(latestCheckResultsV3, checkMeta);
+
+  const telemetryHealth = computeTelemetryHealthMetrics(measurementEvents);
+  const pairedMeasurementAttempts = executionSummary.attempts.filter(attempt => attempt.end).length;
+  const observedPairRate = executionSummary.attempts.length > 0
+    ? pairedMeasurementAttempts / executionSummary.attempts.length
+    : null;
+  const completedStages = MEASUREMENT_STAGES.filter(stage => (
+    executionSummary.attempts.some(attempt => (
+      attempt.command === stage
+      && attempt.end
+      && ['success', 'partial'].includes(attempt.result)
+    ))
+  ));
+  const missingRequiredStages = MEASUREMENT_STAGES.filter(stage => !completedStages.includes(stage));
+  const requiredStageCompleteness = {
+    completed: completedStages.length,
+    required: MEASUREMENT_STAGES.length,
+    rate: completedStages.length / MEASUREMENT_STAGES.length,
+    completed_stages: completedStages,
+    missing: missingRequiredStages,
+  };
+  const pHTelemetryHealthScore = Number.isFinite(telemetryHealth.telemetry_health_score)
+    ? metricsV3.round(telemetryHealth.telemetry_health_score * 100, 2)
+    : null;
+
+  const reworkSummary = compactReworkSummary(executionSummary.summary, reworkReasons);
+
+  const v3Context = buildV3ChangeContext(scopedEvents, executionSummary, {
+    change_name: options.change || null,
+    change_type: changeType,
+    scenario_count: scenarioData.scenario_count,
+    scenario_sources: scenarioData.files,
+    check_results: latestCheckResultsV3,
+    check_meta: checkMeta,
+    q3: q3Result,
+    total_stage_duration_ms: totalStageDuration,
+    coding_duration_ms: codingDurationIncludingRework,
+    spec_duration_ms: specDurationIncludingRework,
+    rework_coding_duration_ms: 0,
+    rework_spec_duration_ms: 0,
+    p4_quality_gate_enforcement_rate: qualityGateRate,
+    p_c_stage_closure_rate: observedPairRate,
+    p_h_telemetry_health_score: pHTelemetryHealthScore,
+    rework_summary: reworkSummary,
+    q1_spec_conformance: conformanceMetrics.q1_spec_conformance_score,
+    q1_source: 'conformance_review',
+    q4_tdd_coverage: specTestCoverageMetrics.q4_spec_driven_test_coverage,
+    q4_source: specTestCoverageMetrics.source,
+  });
+  const v3 = metricsV3.computeV3ChangeMetrics(v3Context);
+  const e1AvailabilityReason = v3.efficiency.e1_availability_reason === 'no-scenarios' && scenarioData.availability_reason
+    ? scenarioData.availability_reason
+    : v3.efficiency.e1_availability_reason;
+  const completeMeasurementJourney = missingRequiredStages.length === 0;
+  const incompleteJourneyReason = completeMeasurementJourney
+    ? null
+    : `missing-required-stages:${missingRequiredStages.join(',')}`;
+  const metricEvidence = {
+    e1: {
+      status: !v3.efficiency.e1_availability
+        ? 'missing'
+        : (completeMeasurementJourney ? 'trusted' : 'provisional'),
+      reason: e1AvailabilityReason || incompleteJourneyReason,
+      source_event_count: measurementEvents.length,
+    },
+    q3: {
+      status: v3.quality.q3_score_status === 'verified'
+        && v3.quality.q3_reviewer_independence === 'independent-review'
+        ? 'trusted'
+        : (v3.quality.q3_availability ? 'provisional' : 'missing'),
+      reason: v3.quality.q3_availability_reason,
+      source_event_count: checkEvents.length,
+    },
+    p4: {
+      status: !firstApply
+        ? 'missing'
+        : (completeMeasurementJourney ? 'trusted' : 'provisional'),
+      reason: firstApply ? incompleteJourneyReason : 'missing-apply-stage',
+      source_event_count: executionSummary.attempts.filter(attempt => attempt.command === 'check').length,
+    },
+    p_r: {
+      status: executionSummary.attempts.length === 0
+        ? 'missing'
+        : (completeMeasurementJourney ? 'trusted' : 'provisional'),
+      reason: executionSummary.attempts.length > 0 ? incompleteJourneyReason : 'missing-stage-events',
+      source_event_count: executionSummary.attempts.length,
+    },
+    p_h: {
+      status: measurementEvents.length === 0
+        ? 'missing'
+        : (completeMeasurementJourney ? 'trusted' : 'provisional'),
+      reason: measurementEvents.length > 0 ? incompleteJourneyReason : 'missing-stage-events',
+      source_event_count: measurementEvents.length,
+    },
+  };
+
   return {
+    measurement_scope: {
+      stages: MEASUREMENT_STAGES,
+      excluded_auxiliary_stages: AUXILIARY_STAGES,
+      source_event_count: measurementEvents.length,
+      attribution: 'direct-or-explicit-link',
+    },
+    metric_evidence: metricEvidence,
     efficiency: {
       e1_lead_time_ms: leadTime,
-      e2_coding_time_ratio: totalStageDuration > 0 ? roundMetric(codingDuration / totalStageDuration) : null,
-      e3_spec_time_ratio: totalStageDuration > 0 ? roundMetric(specDuration / totalStageDuration) : null,
+      e2_coding_time_ratio: totalStageDuration > 0 ? roundMetric(codingDurationIncludingRework / totalStageDuration, 4) : null,
+      e3_spec_time_ratio: totalStageDuration > 0 ? roundMetric(specDurationIncludingRework / totalStageDuration, 4) : 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
@@ -2372,12 +3155,19 @@ function computeSinglePdfMvpMetrics(events, options = {}) {
         : null,
       rework_stage_duration_ms: executionSummary.summary.rework_stage_duration_ms,
       total_stage_duration_ms: executionSummary.summary.total_stage_duration_ms,
+      measurement_stage_duration_ms: totalStageDuration,
       e2_coding_time_ratio_including_rework: executionSummary.summary.total_stage_duration_ms > 0
         ? roundMetric((codingDuration + reworkCodingDuration) / executionSummary.summary.total_stage_duration_ms)
         : null,
       e3_spec_time_ratio_including_rework: executionSummary.summary.total_stage_duration_ms > 0
         ? roundMetric((specDuration + reworkSpecDuration) / executionSummary.summary.total_stage_duration_ms)
         : null,
+      // V3 主指标：场景交付效率（ms/场景）
+      e1_scenario_delivery_efficiency_ms: v3.efficiency.e1_scenario_delivery_efficiency_ms,
+      scenario_count: v3.efficiency.scenario_count,
+      scenario_sources: v3.efficiency.scenario_sources,
+      e1_availability: v3.efficiency.e1_availability,
+      e1_availability_reason: e1AvailabilityReason,
     },
     quality: {
       q1_spec_conformance_score: conformanceMetrics.q1_spec_conformance_score,
@@ -2391,6 +3181,15 @@ function computeSinglePdfMvpMetrics(events, options = {}) {
       conformance_reviewer: conformanceMetrics.reviewer,
       conformance_reviewer_independence: conformanceMetrics.reviewer_independence,
       spec_test_scenario_counts: specTestCoverageMetrics.scenario_counts,
+      // V3 主指标：规约质量评分（0-100）
+      q3_spec_quality_score: v3.quality.q3_spec_quality_score,
+      q3_score_status: v3.quality.q3_score_status,
+      q3_reviewer_independence: v3.quality.q3_reviewer_independence,
+      q3_category_scores: v3.quality.q3_category_scores,
+      q3_availability: v3.quality.q3_availability,
+      // Q1/Q4 上游信号未就绪时用 pending-upstream 标注，不把 null 误转成 0
+      q1_status: v3.quality.q1_spec_conformance.status,
+      q4_status: v3.quality.q4_tdd_coverage.status,
     },
     process: {
       p1_spec_iteration_count: specIterationCount,
@@ -2401,10 +3200,34 @@ function computeSinglePdfMvpMetrics(events, options = {}) {
       p4_quality_gate_enforcement_rate: qualityGateRate,
       p4b_check_fixed_rate: fixRate,
       git_document_metrics: gitDocumentMetrics,
-      rework_summary: compactReworkSummary(executionSummary.summary, reworkReasons),
+      rework_summary: reworkSummary,
+      // V3: 阶段闭环率别名（来自 telemetry_health.matched_stage_rate）
+      p_c_stage_closure_rate: observedPairRate,
+      observed_stage_pairing: {
+        paired: pairedMeasurementAttempts,
+        starts: executionSummary.attempts.length,
+        rate: observedPairRate,
+      },
+      required_stage_completeness: requiredStageCompleteness,
     },
     manual_insights: computeManualInsightMetrics(scopedEvents),
-    telemetry_health: computeTelemetryHealthMetrics(scopedEvents),
+    telemetry_health: {
+      ...telemetryHealth,
+      p_h_telemetry_health_score: pHTelemetryHealthScore,
+    },
+    change_type: changeType,
+    change_name: options.change || null,
+    v3,
+    legacy_metrics: {
+      e1_lead_time_ms: leadTime,
+      e4_ai_code_first_pass_rate: aiFirstPassMetrics.e4_ai_code_first_pass_rate,
+      p1_spec_iteration_count: specIterationCount,
+      p2_ai_code_adoption_rate: aiAdoptionMetrics.p2_ai_code_adoption_rate,
+      q3_build_first_pass_rate: firstBuildSuccess == null ? null : (firstBuildSuccess ? 1 : 0),
+      q5_cross_doc_consistency_score: consistencyScore,
+      deprecated: true,
+      notes: '旧版指标，保留用于兼容。新版主指标见 v3 字段（E1=场景交付效率 ms/场景，Q3=规约质量评分 0-100）。',
+    },
   };
 }
 
@@ -2431,6 +3254,7 @@ function computeCapabilityMetrics(capabilityName, events, options = {}) {
 function computeTelemetryHealthMetrics(events, options = {}) {
   const report = computeDoctorReport(events, options);
   return {
+    ...report,
     telemetry_health_score: report.telemetry_health_score,
     matched_stage_rate: report.matched_stage_rate,
     open_stages: report.open_stages,
@@ -2448,20 +3272,52 @@ function computePdfMvpMetrics(events, options = {}) {
   }
 
   if (options.level === 'change' || options.change) {
+    const gitCommitTimeline = resolveGitCommitTimeline(
+      events,
+      options.projectRoot,
+      options.gitCommitTimeline,
+    );
     return computeSinglePdfMvpMetrics(events, {
       change: options.change,
       projectRoot: options.projectRoot,
+      gitCommitTimeline,
     });
   }
 
+  const gitCommitTimeline = resolveGitCommitTimeline(
+    events,
+    options.projectRoot,
+    options.gitCommitTimeline,
+  );
   const changeNames = [...new Set(events.map(e => e.change).filter(Boolean))];
   const changeMetrics = changeNames
     .map(change => computeSinglePdfMvpMetrics(events, {
       change,
       projectRoot: options.projectRoot,
+      gitCommitTimeline,
     }))
     .filter(Boolean);
 
+  const byChange = changeMetrics.map(m => ({
+    change_name: m.change_name,
+    change_type: m.change_type,
+    e1_scenario_delivery_efficiency_ms: m.efficiency.e1_scenario_delivery_efficiency_ms,
+    q3_spec_quality_score: m.quality.q3_spec_quality_score,
+    p4_quality_gate_enforcement_rate: m.process.p4_quality_gate_enforcement_rate,
+    p_c_stage_closure_rate: m.process.p_c_stage_closure_rate,
+    p_h_telemetry_health_score: m.telemetry_health.p_h_telemetry_health_score,
+    rework_summary: m.process.rework_summary,
+  }));
+  const v3ChangeMetrics = changeMetrics.map(m => m.v3).filter(Boolean);
+  const aggregated = metricsV3.aggregateV3Metrics(v3ChangeMetrics);
+  const totalReworkAttempts = sumMetric(
+    changeMetrics,
+    m => m.process.rework_summary?.total_rework_attempts,
+  );
+  const avgReworkCount = changeMetrics.length > 0
+    ? metricsV3.round(totalReworkAttempts / changeMetrics.length)
+    : null;
+
   return {
     efficiency: {
       e1_lead_time_ms: averageMetric(changeMetrics, m => m.efficiency.e1_lead_time_ms),
@@ -2469,20 +3325,42 @@ function computePdfMvpMetrics(events, options = {}) {
       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),
+      // V3 主指标：场景交付效率均值（跨变更）
+      e1_scenario_delivery_efficiency_ms: averageMetric(changeMetrics, m => m.efficiency.e1_scenario_delivery_efficiency_ms),
     },
     quality: {
       q1_spec_conformance_score: averageMetric(changeMetrics, m => m.quality.q1_spec_conformance_score),
       q3_build_first_pass_rate: averageMetric(changeMetrics, m => m.quality.q3_build_first_pass_rate),
       q4_spec_driven_test_coverage: averageMetric(changeMetrics, m => m.quality.q4_spec_driven_test_coverage),
       q5_cross_doc_consistency_score: averageMetric(changeMetrics, m => m.quality.q5_cross_doc_consistency_score),
+      // V3 主指标：规约质量评分均值（跨变更）
+      q3_spec_quality_score: averageMetric(changeMetrics, m => m.quality.q3_spec_quality_score),
     },
     process: {
       p1_spec_iteration_count: sumMetric(changeMetrics, m => m.process.p1_spec_iteration_count),
       p2_ai_code_adoption_rate: averageMetric(changeMetrics, m => m.process.p2_ai_code_adoption_rate),
       p4_quality_gate_enforcement_rate: averageMetric(changeMetrics, m => m.process.p4_quality_gate_enforcement_rate),
+      p_c_stage_closure_rate: averageMetric(changeMetrics, m => m.process.p_c_stage_closure_rate),
+      rework_summary: {
+        total_rework_attempts: totalReworkAttempts,
+        avg_rework_count: avgReworkCount,
+      },
     },
     manual_insights: computeManualInsightMetrics(events.filter(e => !e.orphan)),
-    telemetry_health: computeTelemetryHealthMetrics(events),
+    telemetry_health: (() => {
+      const health = computeTelemetryHealthMetrics(events);
+      return {
+        ...health,
+        p_h_telemetry_health_score: Number.isFinite(health.telemetry_health_score)
+          ? metricsV3.round(health.telemetry_health_score * 100, 2)
+          : null,
+      };
+    })(),
+    by_change: byChange,
+    by_change_type: aggregated.by_change_type,
+    distribution: aggregated.distribution,
+    unknown_change_type_count: aggregated.unknown_change_type_count,
+    change_count: aggregated.change_count,
   };
 }
 
@@ -2573,24 +3451,146 @@ function formatReworkReasonDetails(reasons) {
   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 ? '（含未提交变更）' : ''}`);
 }
 
+// V3: 最小指标集完整性 section
+function formatMinimumMetricSetMarkdown(minSet) {
+  if (!minSet) return ['- 数据不可用'];
+  const available = Array.isArray(minSet.available) ? minSet.available : [];
+  const missing = Array.isArray(minSet.missing) ? minSet.missing : [];
+  const minimumMetrics = Array.isArray(minSet.minimum_metrics) ? minSet.minimum_metrics : [];
+  const labels = {
+    e1: '每个场景平均用时（E1）',
+    q3: '规约检查得分（Q3）',
+    p4: '编码前已完成检查（P4）',
+    p_r: '阶段重复次数（P-R）',
+    p_h: '执行记录完整度（P-H）',
+  };
+  return [
+    `- 覆盖率：${formatRatioToPercent(minSet.coverage_rate)}（${available.length}/${minimumMetrics.length}）`,
+    `- 已覆盖：${available.map(k => labels[k] || k).join(', ') || '无'}`,
+    `- 缺失：${missing.map(k => labels[k] || k).join(', ') || '无'}`,
+  ];
+}
+
+function formatAlertsMarkdown(alerts) {
+  if (!Array.isArray(alerts) || alerts.length === 0) return ['- 无预警'];
+  return alerts.map(a => `- [${(a.level || 'info').toUpperCase()}] ${a.metric || ''}：${a.reason || ''}`);
+}
+
+function formatMaturityMarkdown(maturity) {
+  if (!maturity) return ['- 数据不可用'];
+  return [
+    `- 当前成熟度等级：${maturity.current_level}`,
+    `- 可达成熟度上限：${maturity.eligible_max_level}`,
+    `- 未满足条件：${(maturity.unmet_criteria || []).join(', ') || '无'}`,
+  ];
+}
+
+function reportStatusLabel(status) {
+  return ({
+    implemented: '已实现',
+    provisional: '部分可用',
+    'pending-upstream': '待补数据',
+    'not-applicable': '本报告不适用',
+    verified: '已验证',
+    trusted: '可信',
+    missing: '缺失',
+  }[status] || status || '未知');
+}
+
 function renderExecutiveReportMarkdown(report) {
+  if (report?.level === 'change' && report.change) {
+    report = require('./reporting/change-report-model.cjs').buildChangeReportModel(report);
+  }
   const metrics = report.metrics;
-  const health = report.doctor;
+  const health = report.doctor || {};
   const archive = report.archive_result || null;
   const taskCompletion = archive?.task_completion || null;
+  const v3 = metrics?.v3 || null;
+  const eff = metrics?.efficiency || {};
+  const qual = metrics?.quality || {};
+  const proc = metrics?.process || {};
+  const th = metrics?.telemetry_health || {};
+  const e2IncludingRework = eff.e2_coding_time_ratio_including_rework ?? eff.e2_coding_time_ratio;
+  const e3IncludingRework = eff.e3_spec_time_ratio_including_rework ?? eff.e3_spec_time_ratio;
+  const q1Status = qual.q1_status || (qual.q1_spec_conformance_score != null ? 'available' : 'pending-upstream');
+  const q4Status = qual.q4_status || (qual.q4_spec_driven_test_coverage != null ? 'available' : 'pending-upstream');
   return [
     `# SDD 效果度量报告${report.change ? ` - ${report.change}` : ''}`,
     '',
     `- 生成时间：${formatLocalTimestamp(report.generated_at)}`,
     `- 项目路径：${report.project_root ? String(report.project_root).replace(/[\\/]+$/, '').split(/[\\/]/).pop() : 'null'}`,
     `- 统计范围：${report.change ? `change/${report.change}` : 'project'}`,
+    `- 报告 Schema：${report.schema_version || metricsV3.REPORT_SCHEMA_VERSION}（指标契约 ${report.metrics_contract || metricsV3.METRICS_CONTRACT_VERSION}）`,
+    ...(report.window?.period ? [`- 统计周期：${report.window.period}（${report.window.date_from || ''} ~ ${report.window.date_to || ''}）`] : []),
+    '',
+    '## 一句话结论',
+    `> ${report.conclusion?.text || '当前证据不足，暂不能形成可信结论。'}`,
+    '',
+    '## 摘要',
+    `- 任务完成：${report.conclusion?.task_statement || '尚无结构化主任务结论'}`,
+    `- 证据可信度：${report.conclusion?.trust_statement || '尚无可信度结论'}`,
+    `- 方案覆盖：${report.scheme_compliance?.counts?.implemented ?? 0}/${report.scheme_compliance?.items?.length ?? 0} 项已完整实现`,
+    ...(report.change_summary ? [
+      `- 文档任务完成：${report.change_summary.tasks?.document?.completed ?? '暂无数据'}/${report.change_summary.tasks?.document?.total ?? '暂无数据'}`,
+      `- 事件可追溯：${report.change_summary.tasks?.traceability?.verified ?? '暂无数据'}/${report.change_summary.tasks?.traceability?.total ?? '暂无数据'}`,
+      `- 最终测试：${report.change_summary.tests ? `${report.change_summary.tests.passed}/${report.change_summary.tests.total}（${report.change_summary.tests.status}）` : '暂无数据'}`,
+      `- 问题与证据：${report.change_summary.evidence?.category_count ?? 0} 类问题，${report.change_summary.evidence?.occurrence_count ?? 0} 次规则命中`,
+    ] : []),
+    '',
+    '## 需要处理',
+    ...(report.evidence_alerts?.open?.length > 0
+      ? report.evidence_alerts.open.map(alert => `- [${alert.severity === 'error' ? '阻断' : '提醒'}] ${alert.warning}（${alert.subject || '本次变更'}，出现 ${alert.occurrences} 次）`)
+      : ['- 当前没有未解决的证据问题。']),
+    ...((report.metric_alerts || []).map(alert => `- [指标] ${alert.metric || ''}：${alert.reason || ''}`)),
+    ...((report.warning_dispositions || []).map(item => (
+      `- [告警处置] ${item.warning}：${item.disposition}${item.reason ? `（${item.reason}）` : ''}`
+    ))),
+    '',
+    '## 本次变更的关键指标',
+    ...formatMinimumMetricSetMarkdown(report.minimum_metric_set),
+    `- 数值覆盖：${formatRatioToPercent(report.minimum_metric_set?.numeric_coverage_rate)}（${report.minimum_metric_set?.numeric_available ?? 0}/${report.minimum_metric_set?.numeric_total ?? 5}）`,
+    `- 可信覆盖：${formatRatioToPercent(report.minimum_metric_set?.trusted_coverage_rate)}（${report.minimum_metric_set?.trusted_available ?? 0}/${report.minimum_metric_set?.numeric_total ?? 5}；临时 ${report.minimum_metric_set?.provisional ?? 0} 项）`,
+    '',
+    '## 核心指标',
+    '## 效率 E1/E2/E3',
+    `- 每个场景平均用时（E1）：${eff.e1_scenario_delivery_efficiency_ms != null ? `${formatMsHuman(eff.e1_scenario_delivery_efficiency_ms)}/场景` : '暂无数据'}（场景数：${eff.scenario_count ?? 0}${eff.e1_availability === false ? `，原因：${eff.e1_availability_reason || 'unknown'}` : ''}）`,
+    `- 编码时间占比（E2，含流程修正）：${formatRatioToPercent(e2IncludingRework)}（不含流程修正：${formatRatioToPercent(eff.e2_coding_time_ratio)}）`,
+    `- 写需求、方案和任务的时间占比（E3，含流程修正）：${formatRatioToPercent(e3IncludingRework)}（不含流程修正：${formatRatioToPercent(eff.e3_spec_time_ratio)}）`,
+    '',
+    '## 质量 Q1/Q3/Q4',
+    `- Q1 规约符合度：${qual.q1_spec_conformance_score ?? 'null'}（状态：${q1Status}）`,
+    `- 规约检查得分（Q3）：${qual.q3_spec_quality_score ?? '暂无数据'}${qual.q3_spec_quality_score != null ? '/100' : ''}（${qual.q3_score_status === 'verified' ? '已验证' : '临时'}，评审独立性：${qual.q3_reviewer_independence || 'unknown'}）`,
+    `- Q4 规约驱动测试覆盖率：${formatRatioToPercent(qual.q4_spec_driven_test_coverage)}（状态：${q4Status}）`,
+    '',
+    '## 过程 P4/P-R/P-C',
+    `- 编码前是否先检查（P4）：${formatRatioToPercent(proc.p4_quality_gate_enforcement_rate)}`,
+    `- 阶段重复次数（P-R）：${proc.rework_summary?.total_rework_attempts ?? '暂无数据'}`,
+    `- 步骤是否有始有终（P-C）：${formatRatioToPercent(proc.p_c_stage_closure_rate)}`,
+    '',
+    '## 遥测健康 P-H',
+    `- 执行记录是否完整（P-H）：${th.p_h_telemetry_health_score ?? '暂无数据'}${th.p_h_telemetry_health_score != null ? '/100' : ''}`,
+    ...(Array.isArray(metrics?.by_change_type) || metrics?.by_change_type
+      ? ['', '## 分层统计与趋势', `- 按变更类型分布：${metrics.by_change_type ? JSON.stringify(metrics.by_change_type) : 'null'}`, `- 未分类变更数：${metrics.unknown_change_type_count ?? 'null'}`]
+      : []),
+    '',
+    '## 预警与成熟度',
+    '### 预警',
+    ...formatAlertsMarkdown(report.alerts),
+    '### 成熟度',
+    ...formatMaturityMarkdown(report.maturity),
+    '',
+    '## 3.3.4.2 方案对齐',
+    ...(report.scheme_compliance?.items || []).map(item => `- ${item.label}：${reportStatusLabel(item.status)}（${item.evidence}）`),
     '',
     '## 执行摘要',
     `- Telemetry 健康分：${formatRatioToPercent(health.telemetry_health_score)}（0-100%，反映遥测数据的完整性，扣分项包括未闭环阶段、孤儿事件等）`,
     `- 阶段闭环率：${formatRatioToPercent(health.matched_stage_rate)}（已配对 start/end 的阶段占有效阶段总数的比例）`,
     `- 严重问题数：${health.severe_issues?.length ?? '无数据'}（存在未闭环阶段、孤儿事件或未知命令等阻断级问题的数量）`,
     '',
-    '## 效率指标',
+    '<details>',
+    '<summary>历史兼容数据（旧版指标，仅供已有消费者对照）</summary>',
+    '',
+    '## Legacy 效率指标（v2，兼容展示，非主指标）',
     `- E1 需求到归档总时长：${formatMsToSeconds(metrics.efficiency?.e1_lead_time_ms)}`,
     `- E2 编码时间占比：${formatRatioToPercent(metrics.efficiency?.e2_coding_time_ratio)}（仅 apply 阶段；test 阶段耗时另见有效阶段总耗时）`,
     `- E3 规约时间占比：${formatRatioToPercent(metrics.efficiency?.e3_spec_time_ratio)}`,
@@ -2599,13 +3599,13 @@ function renderExecutiveReportMarkdown(report) {
     `- 阶段间等待：${formatMsToSeconds(metrics.efficiency?.idle_time_ms)}`,
     `- 流程修正阶段总耗时：${formatMsToSeconds(metrics.efficiency?.rework_stage_duration_ms)}`,
     '',
-    '## 质量指标',
+    '## Legacy 质量指标（v2，兼容展示，非主指标）',
     `- 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)}${metrics.quality?.q4_source === 'conformance-fallback' ? '（近似自 conformance_review）' : ''}`,
     `- Q5 跨文档一致性得分：${metrics.quality?.q5_cross_doc_consistency_score ?? 'null'}（取最新 check 的 consistency_score）`,
     '',
-    '## 过程指标',
+    '## Legacy 过程指标（v2，兼容展示，非主指标）',
     `- 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)}`,
@@ -2614,6 +3614,8 @@ function renderExecutiveReportMarkdown(report) {
     `- 重复执行原因分布：${formatReworkReasons(metrics.process?.rework_summary?.reasons)}`,
     ...formatReworkReasonDetails(metrics.process?.rework_summary?.reasons),
     '',
+    '</details>',
+    '',
     '## 变更文件',
     `- 数据可用：${report.changed_files?._available ? '是' : '否'}`,
     `- 变更文件数：${report.changed_files?.files_changed ?? 'null'}${report.changed_files?.files_diff_note ? `（${report.changed_files.files_diff_note}）` : ''}`,
@@ -2656,8 +3658,12 @@ function renderExecutiveReportMarkdown(report) {
     '',
     '## 产物清单',
     `- 数据可用：${report.artifacts?._available ? '是' : '否'}`,
-    `- 归档目录：${report.artifacts?.archive_path ?? 'null'}`,
-    `- 归档清单：${report.artifacts?.manifest_path ?? 'null'}`,
+    ...((report.artifacts?.files && Object.keys(report.artifacts.files).length > 0)
+      ? Object.entries(report.artifacts.files).map(([name, item]) => `- ${name}：${item.path ?? 'null'}（${item.exists ? '存在' : '缺失'}）`)
+      : [
+        `- 归档目录：${report.artifacts?.archive_path ?? 'null'}`,
+        `- 归档清单：${report.artifacts?.manifest_path ?? 'null'}`,
+      ]),
     `- 迁移文件数：${Array.isArray(report.artifacts?.copied_specs) ? report.artifacts.copied_specs.length : 'null'}`,
     '',
     '## 归档结果',
@@ -2683,15 +3689,35 @@ function renderExecutiveReportMarkdown(report) {
 }
 
 function renderExecutiveReportHtml(report) {
+  if (report?.level === 'change' && report?.change) {
+    return require('./reporting/change-report-renderer.cjs').renderChangeReportHtml(report);
+  }
   const metrics = report.metrics || {};
   const eff = metrics.efficiency || {};
   const qual = metrics.quality || {};
   const proc = metrics.process || {};
+  const th = metrics.telemetry_health || {};
   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]));
 
+  // V3 主指标衍生值
+  const v3Eff = metrics.v3?.efficiency || eff;
+  const e2IncludingRework = eff.e2_coding_time_ratio_including_rework ?? eff.e2_coding_time_ratio;
+  const e3IncludingRework = eff.e3_spec_time_ratio_including_rework ?? eff.e3_spec_time_ratio;
+  const q1Status = qual.q1_status || (qual.q1_spec_conformance_score != null ? 'available' : 'pending-upstream');
+  const q4Status = qual.q4_status || (qual.q4_spec_driven_test_coverage != null ? 'available' : 'pending-upstream');
+  const minMetricSet = report.minimum_metric_set || null;
+  const alertsList = Array.isArray(report.alerts) ? report.alerts : [];
+  const alertsHtml = alertsList.length > 0
+    ? `<h3 style="margin:0 0 6px">预警</h3><div class="reasons">${alertsList.map(a => `<div class="reason-item"><span class="reason-tag ${a.level === 'red' ? 'unfinished' : 'rework'}">${esc((a.level || 'info').toUpperCase())}</span><span class="reason-stage">${esc(a.metric || '')}</span><span class="reason-note">${esc(a.reason || '')}</span></div>`).join('')}</div>`
+    : `<h3 style="margin:0 0 6px">预警</h3><p class="muted">无预警</p>`;
+  const maturityInfo = report.maturity || null;
+  const maturityHtml = maturityInfo
+    ? `<h3 style="margin:14px 0 6px">成熟度</h3><p>当前等级 <strong>${esc(maturityInfo.current_level)}</strong>（可达上限 ${esc(maturityInfo.eligible_max_level)}）</p>`
+    : `<h3 style="margin:14px 0 6px">成熟度</h3><p class="muted">数据不可用</p>`;
+
   // T2.5: 分钟单位时长（<60 分无副，≥60 分加「≈X小时Y分钟」副）
   const durHtml = (ms) => {
     const d = formatDuration(ms);
@@ -2702,12 +3728,27 @@ function renderExecutiveReportHtml(report) {
     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 pctHtmlFriendly = (ratio, sub) => (
+    ratio == null || !Number.isFinite(ratio)
+      ? '<span class="metric-val muted-null">暂无数据</span>'
+      : pctHtml(ratio, sub)
+  );
   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>`;
+  // 指标卡：真实 button 打开可访问对话框；打印/无 JS 时 title 仍保留关键解释。
+  const metricCell = (name, valHtml, info) => {
+    const explanation = info
+      ? `${info} 本次可信状态会根据数据来源、复核独立性和缺失项标记为“已验证 / 临时 / 缺失”。关注异常下降或长期缺失；“查看证据”可定位到对应阶段和事件。`
+      : '';
+    return `<div class="metric"><div class="metric-head"><span class="metric-name">${esc(name)}</span>${explanation ? `<button type="button" class="info-btn" aria-haspopup="dialog" data-title="${esc(name)}" data-info="${esc(explanation)}" title="${esc(explanation)}">?</button>` : ''}</div><div class="metric-val">${valHtml}</div></div>`;
+  };
+  const numHtmlFriendly = (v, unit, sub) => (
+    v == null
+      ? '<span class="metric-val muted-null">暂无数据</span>'
+      : numHtml(v, unit, sub)
+  );
 
   // 健康分环形仪表盘
   const hs = health.telemetry_health_score;
@@ -2735,7 +3776,7 @@ function renderExecutiveReportHtml(report) {
         const barCls = failed ? 'bad' : (short ? 'short' : 'ok');
         const round = n.round || 1;
         const nameSuffix = round > 1 ? '²' : '';
-        const nameCls = failed ? ' style="color:#fca5a5"' : '';
+        const nameCls = failed ? ' style="color:#a72c2c"' : '';
         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}任务` : '';
@@ -2760,11 +3801,11 @@ function renderExecutiveReportHtml(report) {
         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';
+          ? 'background:#e9f7ee;color:#116b32'
+          : 'background:#fff3db;color:#92530a';
         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>`;
+    : `<div class="warn-item"><div class="warn-icon" style="background:#edf4ff;color:#2459a8">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:#e9f7ee;color:#116b32">无需修复</span></div>`;
 
   // 过程：重复执行原因
   const rs = proc.rework_summary || {};
@@ -2811,35 +3852,53 @@ function renderExecutiveReportHtml(report) {
   const cf = report.changed_files || {};
   const arts = report.artifacts || {};
   const movedCount = Array.isArray(arts.copied_specs) ? arts.copied_specs.length : null;
+  const trustRate = minMetricSet?.trusted_coverage_rate ?? 0;
+  const numericRate = minMetricSet?.numeric_coverage_rate ?? minMetricSet?.coverage_rate ?? 0;
+  const evidenceOpen = report.evidence_alerts?.open || [];
+  const evidenceLabel = (warning) => ({
+    apply_test_missing: '缺少任务测试证据',
+    tdd_red_missing: 'TDD 缺少有效 RED 证据',
+    process_note_missing: '缺少过程记录',
+    task_update_reuse: '测试结果被重复引用',
+    TASK_UPDATE_MISSING: '已完成任务缺少状态事件',
+    TASK_TEST_EVIDENCE_MISSING: '已完成任务缺少有效验证',
+    TDD_RED_GREEN_INCOMPLETE: 'TDD 缺少 RED→GREEN 证据',
+    LEGACY_TASK_PARSER: '任务文档仍使用旧格式',
+  }[warning] || warning || '证据问题');
+  const needAttentionHtml = evidenceOpen.length > 0
+    ? evidenceOpen.map(alert => `<li><span class="status-text ${alert.severity === 'error' ? 'bad' : 'warn'}">${alert.severity === 'error' ? '阻断' : '提醒'}</span><strong>${esc(evidenceLabel(alert.warning))}</strong><span>${esc(alert.message || alert.subject || '本次变更')}${alert.occurrences > 1 ? ` · 出现 ${esc(alert.occurrences)} 次` : ''}</span></li>`).join('')
+    : '<li class="empty-state">当前没有未解决的证据问题。</li>';
+  const complianceItems = report.scheme_compliance?.items || [];
+  const complianceHtml = complianceItems.map(item => `<tr><th>${esc(item.label)}</th><td><span class="status-text ${item.status === 'implemented' ? 'ok' : (item.status === 'provisional' ? 'warn' : '')}">${esc(reportStatusLabel(item.status))}</span><div class="muted-2">${esc(item.evidence)}</div></td></tr>`).join('');
 
   return `<!doctype html>
-<html lang="zh-CN">
+<html lang="zh-CN" data-theme="light">
 <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;
+  --bg:#f3f6fb;--card-bg:#fff;--card-bg-2:#f8fafc;
+  --border:#dbe3ef;--border-2:#e8edf4;
+  --text:#172033;--muted:#5e6c82;--muted-2:#7b8798;
+  --ok:#16803a;--warn:#b66a08;--bad:#c73737;--accent:#2768d7;
 }
 *{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}
+body{font-family:-apple-system,BlinkMacSystemFont,'Segoe UI','Microsoft YaHei','PingFang SC',sans-serif;margin:0;background:var(--bg);color:var(--text);line-height:1.6;font-size:14px}
+main{max-width:1180px;margin:0 auto;padding:28px 22px 48px}
+.card{background:var(--card-bg);border:1px solid var(--border);border-radius:16px;padding:20px 22px;margin:14px 0;position:relative;box-shadow:0 8px 28px rgba(41,58,86,.06)}
+h1{margin:0;font-size:26px;font-weight:720;letter-spacing:-.02em}
+h2{margin:0 0 14px;font-size:17px;font-weight:680;color:#25324a;display:flex;align-items:center;gap:8px}
+h2::before{content:"";width:4px;height:16px;background:var(--accent);border-radius:3px}
+h3{margin:0;font-size:12px;font-weight:600;color:var(--muted);letter-spacing:.03em}
 .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}
+code{color:#2459a8;background:#edf4ff;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}
+.badge.ok{background:#e9f7ee;color:#116b32}
+.badge.warn{background:#fff3db;color:#92530a}
+.badge.bad{background:#fdecec;color:#a72c2c}
 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}
@@ -2850,11 +3909,11 @@ tr:last-child td,tr:last-child th{border-bottom:none}
 .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-track{fill:none;stroke:#e5eaf1;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}
+.big-num.ok{color:var(--ok)}
 .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}
@@ -2864,15 +3923,15 @@ tr:last-child td,tr:last-child th{border-bottom:none}
 .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)}
+.info-btn{cursor:pointer;color:var(--accent);font-size:12px;font-weight:700;background:#edf4ff;border:1px solid #cfe0fb;border-radius:50%;width:20px;height:20px;display:inline-flex;align-items:center;justify-content:center;flex-shrink:0;transition:background .15s,box-shadow .15s;line-height:1}
+.info-btn:hover,.info-btn:focus-visible{background:#dceafe;box-shadow:0 0 0 3px rgba(39,104,215,.16);outline:none}
 .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{background:#fff;border:1px solid var(--border);border-radius:16px;max-width:560px;width:100%;padding:22px 24px;box-shadow:0 24px 80px rgba(17,32,58,.22)}
+.modal h4{margin:0 0 8px;font-size:18px;color:#25324a}
 .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}
+.modal .close button{background:#2768d7;color:#fff;border:none;border-radius:8px;padding:8px 18px;font-size:13px;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}
@@ -2882,7 +3941,7 @@ tr:last-child td,tr:last-child th{border-bottom:none}
 .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-name{font-size:11px;color:#34425a;margin-top:6px;font-weight:600;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}
@@ -2894,29 +3953,46 @@ tr:last-child td,tr:last-child th{border-bottom:none}
 .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-stage{font-weight:600;color:#34425a;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-tag.unfinished{background:#fff3db;color:#92530a}
+.reason-tag.rework{background:#eaf2ff;color:#2459a8}
 .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-icon{flex-shrink:0;width:18px;height:18px;border-radius:50%;background:#fff3db;color:#92530a;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-title{color:#25324a;font-weight:600}
 .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}
+.warn-status.fixed{background:#e9f7ee;color:#116b32}
 .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)}}
+@media(max-width:720px){main{padding:14px}.summary{grid-template-columns:1fr}.two-col{grid-template-columns:1fr}.grid{grid-template-columns:1fr}.header-meta{text-align:left}.card{overflow:hidden}table{display:block;overflow-x:auto;white-space:normal}}
 .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}
+.quality-alert .qa-icon{flex-shrink:0;width:18px;height:18px;border-radius:50%;background:#fff3db;color:#92530a;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:#8b520b;margin-bottom:2px}
+.quality-alert .qa-items div{color:#473719;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}
+.conclusion{background:linear-gradient(135deg,#f7fbff,#eef5ff);border-color:#cfe0fb}
+.conclusion h2{margin-bottom:8px}.conclusion-text{font-size:18px;font-weight:650;color:#203b69;margin:0}
+.summary-cards{display:grid;grid-template-columns:repeat(3,1fr);gap:12px}
+.summary-card{background:#fff;border:1px solid var(--border);border-radius:13px;padding:16px}
+.summary-card strong{display:block;font-size:20px;font-variant-numeric:tabular-nums;margin-top:5px}
+.status-text{display:inline-block;border-radius:999px;padding:2px 8px;margin-right:8px;font-size:11px;font-weight:700;background:#eef2f7;color:#516078}
+.status-text.ok{background:#e9f7ee;color:#116b32}.status-text.warn{background:#fff3db;color:#92530a}.status-text.bad{background:#fdecec;color:#a72c2c}
+.attention-list{list-style:none;padding:0;margin:0}.attention-list li{display:flex;align-items:center;gap:8px;padding:10px 0;border-bottom:1px solid var(--border-2)}.attention-list li:last-child{border-bottom:0}.attention-list .empty-state{color:var(--muted)}
+.legacy-appendix{margin:14px 0;border:1px solid var(--border);border-radius:16px;background:#fff}
+.legacy-appendix>summary{cursor:pointer;padding:16px 22px;font-weight:650;color:#42516a}.legacy-appendix[open]>summary{border-bottom:1px solid var(--border)}
+.legacy-appendix .card{border:0;border-radius:0;box-shadow:none;margin:0;border-bottom:1px solid var(--border-2)}
+@media(max-width:720px){.summary-cards{grid-template-columns:1fr}}
+@media print{
+  body{background:#fff;color:#111;font-size:11pt}main{max-width:none;padding:0}.card,.legacy-appendix{box-shadow:none;break-inside:avoid;border-color:#bbb}
+  .info-btn,.modal-mask{display:none!important}.legacy-appendix>summary{display:none}.legacy-appendix:not([open])>*{display:block}.legacy-appendix:not([open])>summary{display:none}
+  .muted,.muted-2{color:#444}
+}
 </style>
 </head>
 <body><main>
@@ -2931,6 +4007,78 @@ tr:last-child td,tr:last-child th{border-bottom:none}
   </div>
 </div>
 
+<div class="card conclusion">
+  <h2>一句话结论</h2>
+  <p class="conclusion-text">${esc(report.conclusion?.text || '当前证据不足，暂不能形成可信结论。')}</p>
+</div>
+
+<div class="summary-cards" aria-label="报告摘要">
+  <div class="summary-card"><span class="muted">任务完成</span><strong>${esc(report.conclusion?.task_statement || '尚无结论')}</strong></div>
+  <div class="summary-card"><span class="muted">证据可信度</span><strong>${(trustRate * 100).toFixed(0)}%</strong><span class="muted-2">数值覆盖 ${(numericRate * 100).toFixed(0)}%</span></div>
+  <div class="summary-card"><span class="muted">方案覆盖</span><strong>${esc(report.scheme_compliance?.counts?.implemented ?? 0)}/${esc(complianceItems.length)}</strong><span class="muted-2">按 3.3.4.2 V3.0 逐项检查</span></div>
+</div>
+
+<div class="card">
+  <h2>需要处理</h2>
+  <ul class="attention-list">${needAttentionHtml}</ul>
+</div>
+
+<div class="card">
+  <h2>最小指标集完整性 <span class="section-tag">E1 · Q3 · P4 · P-R · P-H</span></h2>
+  <div class="grid">
+    ${metricCell('数值覆盖', pctHtml(numericRate, `${minMetricSet?.numeric_available ?? 0}/${minMetricSet?.numeric_total ?? 5}`), '五个最小指标中，已经能计算出数字的比例；有数字不等于已经独立验证。')}
+    ${metricCell('可信覆盖', pctHtml(trustRate, `${minMetricSet?.trusted_available ?? 0}/${minMetricSet?.numeric_total ?? 5}`), '五个最小指标中，证据来源和复核条件均满足要求的比例。')}
+    ${metricCell('临时数据', numHtml(minMetricSet?.provisional ?? 0, '项'), '已有数值但仍需独立复核或补充证据的指标数量。')}
+    ${metricCell('缺失数据', numHtml((minMetricSet?.missing || []).length, '项'), (minMetricSet?.missing || []).join(', ') || '无')}
+  </div>
+  <noscript><div class="footer-note"><strong>指标怎么读：</strong>“数值覆盖”只表示已经算出数字；“可信覆盖”还要求证据来源和独立复核都满足要求；“临时”表示可参考但仍需补证据，“缺失”表示当前不能下结论。</div></noscript>
+</div>
+
+<div class="card">
+  <h2>效率 E1/E2/E3 <span class="section-tag">V3 主指标</span></h2>
+  <div class="grid">
+    ${metricCell('每个场景平均用时（E1）', v3Eff.e1_scenario_delivery_efficiency_ms != null ? `${esc(formatMsHuman(v3Eff.e1_scenario_delivery_efficiency_ms))}<span class="unit">/场景</span>` : '<span class="metric-val muted-null">暂无数据</span>', `有效阶段耗时除以场景数。场景数：${v3Eff.scenario_count ?? 0}。没有历史基线时只显示当前值，不推断提效。`)}
+    ${metricCell('编码时间占比（E2）', pctHtmlFriendly(e2IncludingRework, '含流程修正'), '实际编码阶段（含流程修正）占总耗时的比例。')}
+    ${metricCell('写需求、方案和任务的时间占比（E3）', pctHtmlFriendly(e3IncludingRework, '含流程修正'), '需求规划到任务拆解阶段（含流程修正）占总耗时的比例。')}
+  </div>
+</div>
+
+<div class="card">
+  <h2>质量 Q1/Q3/Q4 <span class="section-tag">V3 主指标</span></h2>
+  <div class="grid">
+    ${metricCell('Q1 规约符合度', numHtmlFriendly(qual.q1_spec_conformance_score, '/1', q1Status === 'pending-upstream' ? '待补数据' : null), '实现与规格的符合程度。')}
+    ${metricCell('规约检查得分（Q3）', qual.q3_spec_quality_score != null ? numHtml(qual.q3_spec_quality_score, '/100', `${qual.q3_score_status === 'verified' ? '已验证' : '临时'}·${qual.q3_reviewer_independence || 'unknown'}`) : '<span class="metric-val muted-null">暂无数据</span>', '基于最新一次检查结果计算；只有独立 reviewer 且复核会话与执行会话不同，才计为已验证。')}
+    ${metricCell('Q4 测试覆盖率', pctHtmlFriendly(qual.q4_spec_driven_test_coverage, q4Status === 'pending-upstream' ? '待补数据' : null), '规格中的每条断言被测试用例覆盖的比例。')}
+  </div>
+</div>
+
+<div class="card">
+  <h2>过程 P4/P-R/P-C <span class="section-tag">V3 主指标</span></h2>
+  <div class="grid">
+    ${metricCell('编码前是否先检查（P4）', pctHtmlFriendly(proc.p4_quality_gate_enforcement_rate), '进入编码前是否已经完成质量检查。')}
+    ${metricCell('阶段重复次数（P-R）', numHtml(proc.rework_summary?.total_rework_attempts ?? null, '次'), '同一阶段被重复执行的次数。')}
+    ${metricCell('步骤是否有始有终（P-C）', pctHtmlFriendly(proc.p_c_stage_closure_rate), '有开始且有结束记录的步骤，占所有有效步骤的比例。')}
+  </div>
+</div>
+
+<div class="card">
+  <h2>遥测健康 P-H <span class="section-tag">V3 主指标</span></h2>
+  <div class="grid">
+    ${metricCell('执行记录是否完整（P-H）', th.p_h_telemetry_health_score != null ? numHtml(th.p_h_telemetry_health_score, '/100') : '<span class="metric-val muted-null">暂无数据</span>', '检查阶段是否闭环、事件是否能配对、命令是否可识别的综合完整性评分。')}
+  </div>
+</div>
+
+<div class="card">
+  <h2>预警与成熟度</h2>
+  ${alertsHtml}
+  ${maturityHtml}
+</div>
+
+<div class="card">
+  <h2>3.3.4.2 方案对齐</h2>
+  <table>${complianceHtml || '<tr><td class="muted">暂无合规检查结果</td></tr>'}</table>
+</div>
+
 <div class="card">
   <h2>执行摘要</h2>
   <div class="summary">
@@ -2939,19 +4087,21 @@ tr:last-child td,tr:last-child th{border-bottom:none}
       <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="big-num ok">${matchedRate == 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="big-num ${severeCount > 0 ? 'bad' : 'ok'}" style="${severeCount > 0 ? 'color:#a72c2c' : ''}">${severeCount}</div>
       <div class="cell-label">严重问题</div>
     </div>
   </div>
   ${qualityAlertHtml}
 </div>
 
+<details class="legacy-appendix">
+<summary>历史兼容数据（旧版指标，仅供已有消费者对照）</summary>
 <div class="card">
-  <h2>效率指标</h2>
+  <h2>Legacy 效率指标 <span class="section-tag">v2，兼容展示</span></h2>
   <div class="grid">
     ${metricCell('E1 总时长', durHtml(eff.e1_lead_time_ms), '从需求规划到归档完成的总耗时，包含阶段间等待和你确认的时间。')}
     ${metricCell('E2 编码时间占比', pctHtml(eff.e2_coding_time_ratio), '实际编码阶段占总有效耗时的比例。')}
@@ -2964,7 +4114,7 @@ tr:last-child td,tr:last-child th{border-bottom:none}
 </div>
 
 <div class="card">
-  <h2>质量指标</h2>
+  <h2>Legacy 质量指标 <span class="section-tag">v2，兼容展示</span></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), '编码阶段第一次构建就成功的比例。')}
@@ -2974,7 +4124,7 @@ tr:last-child td,tr:last-child th{border-bottom:none}
 </div>
 
 <div class="card">
-  <h2>过程指标 <span class="section-tag">含过程记录状态</span></h2>
+  <h2>Legacy 过程指标 <span class="section-tag">v2，兼容展示 · 含过程记录状态</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 提交，所以缺失。')}
@@ -2985,6 +4135,7 @@ tr:last-child td,tr:last-child th{border-bottom:none}
   </div>
   ${reasonHtml ? `<h3 style="margin:14px 0 4px">重复执行原因分布</h3>${reasonHtml}<div class="muted-2" style="margin-top:8px">其余归类：${esc(catLine)}</div>` : ''}
 </div>
+</details>
 
 <div class="card">
   <h2>时间线 <span class="section-tag">横向 · 含起止时间${tlNodes.length > 0 ? ` · ${tlNodes.length} 个阶段执行` : ''}</span></h2>
@@ -3005,7 +4156,9 @@ tr:last-child td,tr:last-child th{border-bottom:none}
       <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>
+      <tr><th>最终报告 Markdown</th><td><code>${esc(archive?.report_path || 'null')}</code></td></tr>
+      <tr><th>最终报告 HTML</th><td><code>${esc(archive?.report_html_path || 'null')}</code></td></tr>
+      <tr><th>最终报告 JSON</th><td><code>${esc(archive?.report_json_path || 'null')}</code></td></tr>
     </table>
   </div>
 </div>
@@ -3022,9 +4175,10 @@ tr:last-child td,tr:last-child th{border-bottom:none}
 </main>
 
 <div class="modal-mask" id="modalMask">
-  <div class="modal">
+  <div class="modal" role="dialog" aria-modal="true" aria-labelledby="modalTitle" aria-describedby="modalBody" tabindex="-1">
     <h4 id="modalTitle">说明</h4>
     <p id="modalBody"></p>
+    <p class="muted-2" style="margin-top:12px">查看证据：请在“时间线”“需要处理”及 JSON 报告的事件引用中定位对应阶段。</p>
     <div class="close"><button id="modalClose">关闭</button></div>
   </div>
 </div>
@@ -3034,15 +4188,32 @@ tr:last-child td,tr:last-child th{border-bottom:none}
   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');}
+  var modal=mask.querySelector('.modal');
+  var lastFocus=null;
+  function open(title,body){lastFocus=document.activeElement;titleEl.textContent=title||'说明';bodyEl.textContent=body||'';mask.classList.add('show');modal.focus();}
+  function close(){if(!mask.classList.contains('show'))return;mask.classList.remove('show');if(lastFocus&&lastFocus.focus)lastFocus.focus();}
   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();});
+  document.addEventListener('keydown',function(e){
+    if(e.key==='Escape'){close();return;}
+    if(e.key==='Tab'&&mask.classList.contains('show')){
+      var focusable=modal.querySelectorAll('button,[href],input,select,textarea,[tabindex]:not([tabindex="-1"])');
+      if(!focusable.length){e.preventDefault();modal.focus();return;}
+      var first=focusable[0],last=focusable[focusable.length-1];
+      if(e.shiftKey&&document.activeElement===first){e.preventDefault();last.focus();}
+      else if(!e.shiftKey&&document.activeElement===last){e.preventDefault();first.focus();}
+    }
+  });
+  var printOpened=[];
+  window.addEventListener('beforeprint',function(){
+    printOpened=[];
+    document.querySelectorAll('details').forEach(function(item){if(!item.open){printOpened.push(item);item.open=true;}});
+  });
+  window.addEventListener('afterprint',function(){printOpened.forEach(function(item){item.open=false;});printOpened=[];});
 })();
 </script>
 </body></html>`;
@@ -3054,53 +4225,6 @@ function extractChangedFiles(events, projectRoot) {
   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;
@@ -3113,27 +4237,81 @@ function extractChangedFiles(events, projectRoot) {
       }
     }
   }
+  const finalOutputFiles = new Set(
+    Array.isArray(aiDiff?.files)
+      ? aiDiff.files.filter(file => typeof file === 'string' && file.trim()).map(file => file.trim())
+      : [],
+  );
+  if (finalOutputFiles.size === 0 && latest?.details) {
+    const rawReview = latest.details.ai_adoption || latest.details.ai_adoption_review || latest.details.ai_code_adoption || {};
+    for (const assertion of rawReview.assertions || []) {
+      for (const file of assertion.files || []) {
+        if (typeof file === 'string' && file.trim()) finalOutputFiles.add(file.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 汇总值`;
+  const finalOutputFileCount = Number.isFinite(aiDiff?.files_changed)
+    ? aiDiff.files_changed
+    : (finalOutputFiles.size > 0 ? finalOutputFiles.size : null);
+  const snapshotKind = aiDiff?.snapshot_kind || null;
+  const finalOutputStatus = snapshotKind === 'final' ? 'final' : (finalOutputFileCount == null ? 'unavailable' : 'provisional');
+  const addedLines = Number.isFinite(aiDiff?.added_lines)
+    ? aiDiff.added_lines
+    : (Number.isFinite(review?.final_diff?.added_lines) ? review.final_diff.added_lines : null);
+  const deletedLines = Number.isFinite(aiDiff?.deleted_lines)
+    ? aiDiff.deleted_lines
+    : (Number.isFinite(review?.final_diff?.deleted_lines) ? review.final_diff.deleted_lines : null);
+  let lineCountEstimate = null;
+  if (addedLines == null && review?.ai_git_sha == null && finalOutputFiles.size > 0 && projectRoot) {
+    let lines = 0;
+    let countedFiles = 0;
+    const root = path.resolve(projectRoot);
+    for (const relativePath of finalOutputFiles) {
+      try {
+        const absolutePath = path.isAbsolute(relativePath)
+          ? path.resolve(relativePath)
+          : path.resolve(root, relativePath);
+        if (absolutePath !== root && !absolutePath.startsWith(`${root}${path.sep}`)) continue;
+        const content = fs.readFileSync(absolutePath, 'utf8');
+        lines += content.split('\n').length - (content.endsWith('\n') ? 1 : 0);
+        countedFiles += 1;
+      } catch {
+        // 无 Git 时只统计可安全读取的当前文件；不可读文件不伪造行数。
+      }
+    }
+    if (countedFiles > 0) {
+      lineCountEstimate = {
+        current_lines: lines,
+        counted_files: countedFiles,
+        note: '无 Git diff，仅统计当前文件总行数；不能解释为新增行数。',
+      };
     }
-  } else {
-    filesChanged = aiDiffFileCount;
   }
+  const filesChanged = taskUpdateFileCount > 0 ? taskUpdateFileCount : finalOutputFileCount;
+  const countsDiffer = taskUpdateFileCount > 0
+    && finalOutputFileCount != null
+    && taskUpdateFileCount !== finalOutputFileCount;
+  const reconciliationNote = countsDiffer
+    ? `任务事件累计涉及 ${taskUpdateFileCount} 个文件；最终输出快照包含 ${finalOutputFileCount} 个文件。两者用途不同，不应合并为一个口径。`
+    : (filesChanged == null ? '没有可用的文件变更证据。' : '任务事件与最终输出文件口径一致。');
   return {
-    _available: true,
+    _available: filesChanged != null,
     files_changed: filesChanged,
     added_lines: addedLines,
-    files,
-    ai_diff_files_changed: aiDiffFilesChanged,
-    files_diff_note: filesDiffNote,
+    deleted_lines: deletedLines,
+    files: finalOutputFiles.size > 0 ? [...finalOutputFiles] : null,
+    task_event_files: taskUpdateFileCount > 0 ? [...taskUpdateFiles] : null,
+    task_event_files_changed: taskUpdateFileCount > 0 ? taskUpdateFileCount : null,
+    final_output_files: finalOutputFiles.size > 0 ? [...finalOutputFiles] : null,
+    final_output_files_changed: finalOutputFileCount,
+    final_output_status: finalOutputStatus,
+    diff_source: snapshotKind === 'final' ? 'ai-diff-final' : (aiDiff ? 'ai-diff-provisional' : 'task-events'),
+    line_count_estimate: lineCountEstimate,
+    reconciliation_note: reconciliationNote,
+    ai_diff_files_changed: countsDiffer ? finalOutputFileCount : null,
+    files_diff_note: countsDiffer ? reconciliationNote : null,
   };
 }
 
@@ -3217,19 +4395,34 @@ function extractStageStatus(metrics) {
 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;
+        const dispositionsByWarning = new Map((cr.warning_dispositions || []).map(item => [
+          item.warning || item.id || item.code,
+          item,
+        ]));
+        entry.items = cr.warning_items.map(item => {
+          const disposition = dispositionsByWarning.get(item.warning || item.id || item.code);
+          return disposition
+            ? {
+              ...item,
+              disposition: disposition.disposition,
+              disposition_reason: disposition.reason || null,
+            }
+            : item;
+        });
+      }
+      const dispositions = Array.isArray(cr.warning_dispositions) ? cr.warning_dispositions : [];
+      if (dispositions.length > 0) {
+        entry.warning_dispositions = dispositions;
+        entry.resolved = dispositions.every(item => (
+          ['fixed', 'accepted', 'waived'].includes(item.disposition)
+        ));
       }
-      // Q7: 归档后 incomplete=0 → 标已修复
-      if (allResolved) entry.resolved = true;
       warnings.push(entry);
     }
     const conf = getConformanceReview(e);
@@ -3238,7 +4431,6 @@ function extractKnownRisks(events, doctor, archiveResult) {
       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);
       }
     }
@@ -3307,23 +4499,254 @@ function extractTelemetryWarnings(events) {
   return { _available: true, total: warnings.length, by_type: byType, items };
 }
 
+function validateMaturityEvidenceDetails(details) {
+  const evidence = details?.maturity_evidence;
+  const invalid = error => ({ valid: false, evidence: null, error });
+  if (!evidence || typeof evidence !== 'object' || Array.isArray(evidence)) {
+    return invalid('details.maturity_evidence 必须是对象');
+  }
+
+  const changeType = String(evidence.change_type || '').trim().toLowerCase();
+  if (!metricsV3.CHANGE_TYPES.includes(changeType)) {
+    return invalid(`change_type 必须是 ${metricsV3.CHANGE_TYPES.join('|')} 之一`);
+  }
+  if (!Number.isFinite(evidence.e1_actual_ms) || evidence.e1_actual_ms < 0) {
+    return invalid('e1_actual_ms 必须是大于等于 0 的有限数字');
+  }
+  if (!Number.isFinite(evidence.e1_target_ms) || evidence.e1_target_ms <= 0) {
+    return invalid('e1_target_ms 必须是大于 0 的有限数字');
+  }
+  if (typeof evidence.e1_type_target_met !== 'boolean') {
+    return invalid('e1_type_target_met 必须是布尔值');
+  }
+  const derivedTargetMet = evidence.e1_actual_ms <= evidence.e1_target_ms;
+  if (evidence.e1_type_target_met !== derivedTargetMet) {
+    return invalid('e1_type_target_met 必须与 e1_actual_ms <= e1_target_ms 的计算结果一致');
+  }
+  if (typeof evidence.code_fully_spec_generated !== 'boolean') {
+    return invalid('code_fully_spec_generated 必须是布尔值');
+  }
+
+  if (evidence.code_fully_spec_generated) {
+    const generatedFiles = Array.isArray(evidence.generated_files)
+      ? evidence.generated_files.filter(file => typeof file === 'string' && file.trim())
+      : [];
+    if (generatedFiles.length === 0) {
+      return invalid('code_fully_spec_generated=true 时 generated_files 必须是非空文件路径数组');
+    }
+    if (evidence.manual_code_lines !== 0) {
+      return invalid('code_fully_spec_generated=true 时 manual_code_lines 必须严格等于 0');
+    }
+    if (typeof evidence.evidence_summary !== 'string' || !evidence.evidence_summary.trim()) {
+      return invalid('code_fully_spec_generated=true 时 evidence_summary 必须非空');
+    }
+    if (typeof evidence.reviewer !== 'string' || !evidence.reviewer.trim()) {
+      return invalid('code_fully_spec_generated=true 时 reviewer 必须非空');
+    }
+    if (evidence.reviewer_independence !== 'independent-review') {
+      return invalid('code_fully_spec_generated=true 时 reviewer_independence 必须是 independent-review');
+    }
+    const reviewSessionId = String(evidence.review_session_id || '').trim();
+    const authorSessionId = String(evidence.author_session_id || '').trim();
+    if (!reviewSessionId || !authorSessionId || reviewSessionId === authorSessionId) {
+      return invalid('独立评审要求 review_session_id 与 author_session_id 均非空且不同');
+    }
+  }
+
+  return {
+    valid: true,
+    error: '',
+    evidence: {
+      ...evidence,
+      change_type: changeType,
+      e1_type_target_met: derivedTargetMet,
+    },
+  };
+}
+
 function buildReport(projectRoot, events, options = {}) {
   const archiveEvent = latestByTimestamp(events.filter(e => {
     return e.command === 'archive' && e.type === 'stage_end' && !e.orphan;
   }));
+  const gitCommitTimeline = resolveGitCommitTimeline(
+    events,
+    projectRoot,
+    options.gitCommitTimeline,
+  );
   const metrics = computePdfMvpMetrics(events, {
     level: options.level || (options.change ? 'change' : 'project'),
     change: options.change,
     capability: options.capability,
     projectRoot,
+    gitCommitTimeline,
   });
-  const doctor = computeDoctorReport(events, { change: options.change, projectRoot });
-  return {
+  const doctor = computeDoctorReport(events, {
+    change: options.change,
+    projectRoot,
+    gitCommitTimeline,
+  });
+  const level = options.level || (options.change ? 'change' : 'project');
+  const isProjectLevel = level === 'project';
+
+  let alerts = [];
+  let maturity = null;
+  if (isProjectLevel && options.trackingPeriods && options.trackingPeriods.length > 0) {
+    alerts = metricsV3.evaluateAlerts(options.trackingPeriods);
+  }
+  const maturityEvidence = events
+    .filter(e => (
+      !e.orphan
+        && e.type === 'maturity_evidence'
+        && (!options.change || e.change === options.change)
+    ))
+    .sort((a, b) => timestampMs(b) - timestampMs(a))
+    .map(event => validateMaturityEvidenceDetails(event.details).evidence)
+    .find(Boolean) || {};
+  try {
+    maturity = metricsV3.evaluateMaturity({
+      p4_quality_gate_enforcement_rate: metrics.process?.p4_quality_gate_enforcement_rate ?? null,
+      p_c_stage_closure_rate: metrics.process?.p_c_stage_closure_rate ?? null,
+      q1_spec_conformance: metrics.quality?.q1_spec_conformance_score ?? null,
+      q3_spec_quality_score: metrics.quality?.q3_spec_quality_score ?? null,
+      p_r_avg_rework_count: metrics.process?.rework_summary?.avg_rework_count
+        ?? metrics.process?.rework_summary?.total_rework_attempts
+        ?? null,
+    }, {
+      has_sdd_flow: (metrics.change_count ?? (options.change ? 1 : (metrics.by_change?.length || 0))) !== 0,
+      e1_type_target_met: maturityEvidence.e1_type_target_met === true,
+      code_fully_spec_generated: maturityEvidence.code_fully_spec_generated === true,
+    });
+  } catch { maturity = null; }
+
+  const archiveTaskCompletion = archiveEvent?.details?.archive_result?.task_completion || null;
+  const applyEvidenceAudit = options.change && archiveTaskCompletion
+    ? buildApplyEvidenceAudit(options.change, archiveTaskCompletion, events, { mode: 'report-only' })
+    : null;
+  const baseEvidenceAlerts = metricsV3.buildEvidenceAlerts(events);
+  const auditAlerts = (applyEvidenceAudit?.findings || []).map((finding) => ({
+    key: `${finding.code}:${finding.task_id || options.change || 'change'}`,
+    category: 'evidence',
+    warning: finding.code,
+    subject: finding.task_id || options.change || null,
+    message: finding.message,
+    severity: finding.severity || 'warning',
+    status: 'open',
+    occurrences: 1,
+    opened_by_event_id: null,
+    first_seen_at: null,
+    last_seen_event_id: null,
+    last_seen_at: null,
+    resolved_by_event_id: null,
+    resolved_at: null,
+  }));
+  if (archiveTaskCompletion?.primary_tasks?.parser === 'legacy-fallback') {
+    auditAlerts.push({
+      key: `LEGACY_TASK_PARSER:${options.change || 'change'}`,
+      category: 'evidence',
+      warning: 'LEGACY_TASK_PARSER',
+      subject: options.change || null,
+      message: '任务文档仍使用旧复选框格式，报告已兼容读取；建议迁移为每个任务一条“状态”行。',
+      severity: 'warning',
+      status: 'open',
+      occurrences: 1,
+      opened_by_event_id: null,
+      first_seen_at: null,
+      last_seen_event_id: null,
+      last_seen_at: null,
+      resolved_by_event_id: null,
+      resolved_at: null,
+    });
+  }
+  const evidenceHistory = [...baseEvidenceAlerts.history, ...auditAlerts];
+  const evidenceOpen = evidenceHistory.filter(alert => alert.status === 'open');
+  const evidenceResolved = evidenceHistory.filter(alert => alert.status === 'resolved');
+  const evidenceAlerts = {
+    open: evidenceOpen,
+    resolved: evidenceResolved,
+    history: evidenceHistory,
+    counts: {
+      open: evidenceOpen.length,
+      resolved: evidenceResolved.length,
+      total: evidenceHistory.length,
+    },
+  };
+  const latestCheckWithDispositions = latestByTimestamp(
+    getCheckEvents(events).filter(event => (
+      Array.isArray(event.details?.check_results?.warning_dispositions)
+      && event.details.check_results.warning_dispositions.length > 0
+    )),
+  );
+  const checkWarningDispositions = latestCheckWithDispositions
+    ? latestCheckWithDispositions.details.check_results.warning_dispositions.map(item => ({
+      warning: item.warning || item.id || item.code || 'UNKNOWN',
+      disposition: item.disposition || 'open',
+      reason: item.reason || null,
+      evidence_event_id: latestCheckWithDispositions.event_id || null,
+    }))
+    : [];
+  const minimumMetricSet = metricsV3.buildMinimumMetricStatus(metrics);
+  const metricAlerts = alerts;
+  const latestArchiveResult = [...events].reverse()
+    .map(item => item?.details?.archive_result)
+    .find(Boolean) || {};
+  const observedFormats = options.formats || [
+    latestArchiveResult.report_path && 'md',
+    latestArchiveResult.report_html_path && 'html',
+    latestArchiveResult.report_json_path && 'json',
+  ].filter(Boolean);
+  const schemeCompliance = metricsV3.buildSchemeCompliance({
+    minimum_metric_set: minimumMetricSet,
+    metrics,
+    level,
+    period: options.period || null,
+    formats: observedFormats,
+    evidence_alerts: evidenceAlerts,
+    check_warning_dispositions: checkWarningDispositions,
+    event_count: events.length,
+  });
+  const primaryTasks = archiveTaskCompletion?.primary_tasks || null;
+  const taskStatement = primaryTasks
+    ? (primaryTasks.has_incomplete
+      ? `仍有 ${primaryTasks.incomplete} 个主任务未完成`
+      : `主任务已完成 ${primaryTasks.completed}/${primaryTasks.total}`)
+    : '尚未读取到结构化任务状态';
+  const trustRate = minimumMetricSet.trusted_coverage_rate;
+  const trustStatement = trustRate === 1
+    ? '核心指标证据已全部验证'
+    : `核心指标可信覆盖 ${Math.round((trustRate || 0) * 100)}%`;
+  const alertStatement = evidenceAlerts.open.length > 0
+    ? `有 ${evidenceAlerts.open.length} 个证据问题需要处理`
+    : '没有未解决的证据问题';
+
+  const baseReport = {
+    schema_version: metricsV3.REPORT_SCHEMA_VERSION,
+    metrics_contract: metricsV3.METRICS_CONTRACT_VERSION,
     generated_at: nowISO(),
     project_root: projectRoot,
     change: options.change || null,
-    level: options.level || (options.change ? 'change' : 'project'),
+    level,
+    window: {
+      period: options.period || null,
+      date_from: options.dateFrom || null,
+      date_to: options.dateTo || null,
+    },
+    minimum_metric_set: minimumMetricSet,
+    measurement_scope: metrics.measurement_scope || null,
+    metric_evidence: metrics.metric_evidence || null,
+    attribution_audit: options.attributionAudit || {
+      linked_source_event_count: 0,
+      active_links: [],
+      unassigned_candidate_event_ids: [],
+    },
+    conclusion: {
+      status: evidenceAlerts.open.length > 0 || trustRate < 1 || primaryTasks?.has_incomplete ? 'attention' : 'trusted',
+      text: `${taskStatement}；${trustStatement}；${alertStatement}。`,
+      task_statement: taskStatement,
+      trust_statement: trustStatement,
+      alert_statement: alertStatement,
+    },
     metrics,
+    legacy_metrics: metrics.legacy_metrics || null,
     doctor,
     archive_result: archiveEvent?.details?.archive_result || null,
     changed_files: extractChangedFiles(events, projectRoot),
@@ -3334,7 +4757,18 @@ function buildReport(projectRoot, events, options = {}) {
     artifacts: extractArtifacts(archiveEvent),
     process_notes: extractProcessNotes(events),
     telemetry_warnings: extractTelemetryWarnings(events),
+    distribution: isProjectLevel ? (metrics.distribution || null) : null,
+    by_change_type: isProjectLevel ? (metrics.by_change_type || null) : null,
+    by_change: isProjectLevel ? (metrics.by_change || null) : null,
+    alerts,
+    metric_alerts: metricAlerts,
+    evidence_alerts: evidenceAlerts,
+    check_warning_dispositions: checkWarningDispositions,
+    apply_evidence_audit: applyEvidenceAudit,
+    scheme_compliance: schemeCompliance,
+    maturity,
   };
+  return require('./reporting/change-report-model.cjs').buildChangeReportModel(baseReport, events);
 }
 
 function filterEventsByDate(events, dateFrom, dateTo) {
@@ -3353,7 +4787,9 @@ function computeDoctorReport(events, options = {}) {
     ? events.filter(e => e.change === options.change)
     : events;
   const executionSummary = summarizeStageExecutions(scopedEvents);
-  const reworkReasons = deriveReworkReasons(executionSummary, options.projectRoot);
+  const reworkReasons = deriveReworkReasons(executionSummary, options.projectRoot, scopedEvents, {
+    gitCommitTimeline: options.gitCommitTimeline,
+  });
   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');
@@ -3480,6 +4916,15 @@ function cmdStart(args) {
     process.exit(1);
   }
 
+  if (!changeName) {
+    fail('E_CHANGE_REQUIRED: start 必须显式提供 --change');
+  }
+  requireValidChangeName(changeName);
+  if (changeName === 'general'
+      && (command !== 'explore' || !isTrueOption(args['allow-general'] || args.allow_general))) {
+    fail('E_GENERAL_SCOPE_FORBIDDEN: general 仅允许 explore 配合 --allow-general 显式使用');
+  }
+
   const validCommands = ['propose', 'spec', 'design', 'task', 'check', 'apply', 'test', 'archive', 'explore'];
   if (!validCommands.includes(command)) {
     console.error(`错误: 无效的 command "${command}"，有效值: ${validCommands.join(', ')}`);
@@ -3510,7 +4955,7 @@ function cmdStart(args) {
     source,
     command,
     stage: command,
-    change: changeName || 'general',
+    change: changeName,
     capability,
     task_id: taskId,
     agent_type: agentType,
@@ -3519,7 +4964,10 @@ function cmdStart(args) {
     git_sha: gitSha,
     timestamp,
     context,
-    details: worktreeDetails,
+    details: {
+      ...(worktreeDetails || {}),
+      ...(changeName === 'general' ? { scope: 'explicit-general' } : {}),
+    },
   });
 
   appendEvent(dataDir, event.change, event);
@@ -3599,14 +5047,47 @@ function cmdEnd(args, options = {}) {
   if (!eventId && startEvent) {
     eventId = startEvent.event_id;
   }
+  const requestedChange = args.change || args['change-name'];
+  if (requestedChange) {
+    requireValidChangeName(requestedChange);
+  }
+  if (!startEvent && !requestedChange) {
+    fail('E_CHANGE_REQUIRED: 无法解析 start 的 end 必须显式提供 --change');
+  }
+  if (startEvent && requestedChange && startEvent.change !== requestedChange) {
+    fail(`E_CHANGE_CONFLICT: end 指定 change "${requestedChange}"，但 active stage 属于 "${startEvent.change}"`);
+  }
   // stage_end 幂等性保护：同一 event_id 已存在 stage_end 时，结果相同则跳过，不同则更新（archive 命令只要存在即跳过）
   const command = startEvent?.command || args.command || 'unknown';
   const change = startEvent?.change || args.change || args['change-name'] || 'general';
+  requireValidChangeName(change);
+  if (change === 'general'
+      && (command !== 'explore' || !isTrueOption(args['allow-general'] || args.allow_general))) {
+    fail('E_GENERAL_SCOPE_FORBIDDEN: general 仅允许 explore 配合 --allow-general 显式使用');
+  }
   const existingEnds = readAllEventEndsById(dataDir, eventId, change);
   if (existingEnds.length > 0) {
     const latestExisting = existingEnds.sort((a, b) => timestampMs(b) - timestampMs(a))[0];
+    if (latestExisting.result !== result) {
+      fail(`E_STAGE_END_CONFLICT: event_id "${eventId}" 已记录 result=${latestExisting.result}，不能改为 ${result}`);
+    }
     // archive 命令已存在 stage_end 时直接跳过，避免 result 突变后重复写入
     if (command === 'archive') {
+      const archiveResult = latestExisting.details?.archive_result || {};
+      if (archiveResult.archive_path) {
+        const archiveDirAbs = path.isAbsolute(archiveResult.archive_path)
+          ? archiveResult.archive_path
+          : path.resolve(projectRoot, archiveResult.archive_path);
+        ensureArchiveManifest(projectRoot, change, archiveDirAbs, {
+          reason: archiveResult.reason || '',
+          method: archiveResult.method || 'skywalk-full-spec-archive',
+          archivePath: archiveDirAbs,
+          archivedAt: archiveResult.created_at || archiveResult.archived_at,
+          copiedSpecs: archiveResult.copied_specs,
+          finalizeAfterReports: true,
+          runIdentity: latestExisting.event_id,
+        });
+      }
       const output = {
         event_id: eventId,
         duration_ms: latestExisting.duration_ms,
@@ -3633,7 +5114,6 @@ function cmdEnd(args, options = {}) {
       }
       return output;
     }
-    // 结果不同：允许继续写入新的 stage_end（覆盖/更新）
   }
   const orphan = !startEvent;
   if (!eventId) {
@@ -3700,7 +5180,7 @@ function cmdEnd(args, options = {}) {
       };
     }
   }
-  // archive 归档完成后，扫描 task_completion，has_incomplete 降为 partial（仍归档，仅 result 标记提示未勾验收）
+  // archive 归档完成后，仅主任务未完成时降为 partial；验收证据单独提示，不再冒充任务进度。
   if (command === 'archive' && result === 'success') {
     try {
       const archiveDirRel = repaired?.archive_path || details.archive_result?.archive_path || null;
@@ -3708,7 +5188,13 @@ function cmdEnd(args, options = {}) {
       const taskCompletion = archiveDirAbs
         ? scanTaskCompletionForArchiveDir(projectRoot, change, archiveDirAbs)
         : scanTaskCompletion(projectRoot, change);
-      if (taskCompletion.has_incomplete) {
+      const primary = taskCompletion.primary_tasks;
+      if (primary?.has_incomplete) {
+        result = 'partial';
+        summary = `${summary}（尚有 ${primary.incomplete} 个主任务未完成）`.trim();
+      } else if ((taskCompletion.acceptance_evidence?.unconfirmed || 0) > 0) {
+        summary = `${summary}（主任务已完成；仍有 ${taskCompletion.acceptance_evidence.unconfirmed} 项验收证据待确认）`.trim();
+      } else if (!primary && taskCompletion.has_incomplete) {
         result = 'partial';
         summary = `${summary}（${taskCompletion.incomplete} 项验收标准未勾选）`.trim();
       }
@@ -3739,76 +5225,131 @@ function cmdEnd(args, options = {}) {
     orphan: orphan ? true : undefined,
   });
 
-  appendEvent(dataDir, event.change, event);
-  if (startEvent) {
-    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 = '';
+  const writtenReportPaths = [];
   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);
+    // archive 的 stage_end 尚未入库时，先用待写事件生成报告；实际成功路径随后写回事件。
+    const events = [...readEvents(dataDir, event.change), event];
     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 requestedReportFormat = args['report-format'] || 'markdown';
+  const reportFormat = command === 'archive' ? 'markdown' : requestedReportFormat;
+  const expectedExtension = reportFormat === 'json' ? '.json' : reportFormat === 'html' ? '.html' : '.md';
+  resolvedReportOutput = normalizeKnownReportExtension(resolvedReportOutput, expectedExtension);
   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');
+  atomicWriteText(resolvedReportOutput, rendered + '\n');
+  writtenReportPaths.push(resolvedReportOutput);
 
-  // 默认双输出：md + html，避免只生成单一格式；但仅对 .md/.html 主路径派生副本，防止非标准路径被静默覆盖
+  // 默认三输出：md + html + json（同源 Report Model）；显式 format=json 时只写用户指定文件
+  // 仅对 .md/.html 主路径派生 companion，防止非标准路径被静默覆盖
   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');
+    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 companionPath = resolvedReportOutput.replace(/\.[^.]+$/, companionSuffix);
+      if (companionPath !== resolvedReportOutput) {
+        try {
+          atomicWriteText(companionPath, companionRender + '\n');
+          writtenReportPaths.push(companionPath);
+        } catch (err) {
+          if (command === 'archive') {
+            throw new Error(`E_REPORT_ARTIFACT_WRITE: ${companionSuffix.slice(1)} 报告写入失败: ${err.message}`);
+          }
+          try { console.error(`[telemetry] 报告 companion 写入失败（${companionSuffix.slice(1)}，不阻塞主流程）: ${err.message}`); } catch {}
+        }
+      }
+      const jsonPath = resolvedReportOutput.replace(/\.[^.]+$/, '.json');
+      if (jsonPath !== resolvedReportOutput) {
+        try {
+          atomicWriteText(jsonPath, JSON.stringify(report, null, 2) + '\n');
+          writtenReportPaths.push(jsonPath);
+        } catch (err) {
+          if (command === 'archive') {
+            throw new Error(`E_REPORT_ARTIFACT_WRITE: json 报告写入失败: ${err.message}`);
+          }
+          try { console.error(`[telemetry] 报告 companion 写入失败（json，不阻塞主流程）: ${err.message}`); } catch {}
         }
       }
-    } 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 {}
+  if (command === 'archive' && event.details?.archive_result) {
+    const byExtension = Object.fromEntries(writtenReportPaths.map((filePath) => [path.extname(filePath).toLowerCase(), filePath]));
+    const actualPaths = {};
+    if (byExtension['.md']) actualPaths.report_path = toProjectRelative(projectRoot, byExtension['.md']);
+    if (byExtension['.html']) actualPaths.report_html_path = toProjectRelative(projectRoot, byExtension['.html']);
+    if (byExtension['.json']) actualPaths.report_json_path = toProjectRelative(projectRoot, byExtension['.json']);
+    event.details.archive_result = {
+      ...event.details.archive_result,
+      ...actualPaths,
+    };
+  }
+
+  appendEvent(dataDir, event.change, event);
+  if (startEvent) {
+    clearActiveStage(projectRoot, startEvent);
+  }
+
+  // 终态摘要必须基于已经落库的 archive stage_end。
+  if (command === 'archive') {
+    try { appendChangeSummary(projectRoot, change, readEvents(dataDir, change)); } catch (err) {
+      try { console.error(`[telemetry] 变更总结追加失败（不阻塞）: ${err.message}`); } catch {}
     }
   }
 
+  // 报告初稿生成时 archive stage_end 尚未入库。事件落库后使用同一模型重写已成功
+  // 生成的格式，使 md/html/json 与最终 JSONL 保持一致；失败的 companion 不会被虚构。
+  if (command === 'archive' && writtenReportPaths.length > 0) {
+    const finalEvents = readEvents(dataDir, event.change);
+    const finalReport = buildReport(projectRoot, finalEvents, {
+      level: args['report-level'] || 'change',
+      change: event.change,
+      capability: args.capability || args['capability-name'] || startEvent?.capability,
+    });
+    for (const filePath of writtenReportPaths) {
+      const extension = path.extname(filePath).toLowerCase();
+      const content = extension === '.json'
+        ? JSON.stringify(finalReport, null, 2)
+        : (extension === '.html'
+          ? renderExecutiveReportHtml(finalReport)
+          : renderExecutiveReportMarkdown(finalReport));
+      atomicWriteText(filePath, content + '\n');
+    }
+  }
+
+  // 最终封装统一发生在事件、摘要和三格式报告都落盘之后，保证 manifest/ZIP
+  // 收录的是同一次变更的真实终态。
+  if (command === 'archive' && repaired && event.details?.archive_result?.archive_path) {
+    const finalArchiveResult = event.details.archive_result;
+    const archiveDirAbs = path.isAbsolute(finalArchiveResult.archive_path)
+      ? finalArchiveResult.archive_path
+      : path.resolve(projectRoot, finalArchiveResult.archive_path);
+    ensureArchiveManifest(projectRoot, change, archiveDirAbs, {
+      reason: finalArchiveResult.reason || '',
+      method: finalArchiveResult.method || 'skywalk-full-spec-archive',
+      archivePath: archiveDirAbs,
+      archivedAt: finalArchiveResult.created_at || finalArchiveResult.archived_at,
+      copiedSpecs: finalArchiveResult.copied_specs,
+      finalizeAfterReports: true,
+      runIdentity: event.event_id,
+    });
+  }
+
   const output = {
     event_id: eventId,
     duration_ms: durationMs,
@@ -3826,11 +5367,456 @@ function cmdEnd(args, options = {}) {
 /**
  * log record: 记录非阶段类结构化事件
  */
+function isTrueOption(value) {
+  return value === true || String(value || '').toLowerCase() === 'true';
+}
+
+function requireStrictString(value, code, fieldName) {
+  const normalized = String(value || '').trim();
+  if (!normalized) fail(`${code}: strict 事件缺少 ${fieldName}`);
+  return normalized;
+}
+
+function strictInteger(value, code, fieldName, minimum = 0) {
+  const number = Number(value);
+  if (!Number.isInteger(number) || number < minimum) {
+    fail(`${code}: ${fieldName} 必须是大于等于 ${minimum} 的整数`);
+  }
+  return number;
+}
+
+function normalizeStrictTestResult(args, details) {
+  const input = details?.test_results;
+  if (!input || typeof input !== 'object' || Array.isArray(input)) {
+    fail('TEST_RESULT_REQUIRED: strict test_result 缺少 details.test_results');
+  }
+  const tddPhase = requireStrictString(input.tdd_phase, 'TEST_RESULT_TDD_PHASE_REQUIRED', 'tdd_phase');
+  if (!['red', 'green', 'refactor', 'regression', 'not-applicable'].includes(tddPhase)) {
+    fail(`TEST_RESULT_TDD_PHASE_INVALID: 非法 tdd_phase "${tddPhase}"`);
+  }
+  const command = requireStrictString(input.command || args.command, 'TEST_RESULT_COMMAND_REQUIRED', 'command');
+  const result = requireStrictString(input.result || args.result, 'E_STRICT_FIELD_REQUIRED', 'result');
+  if (!['success', 'failure'].includes(result)) {
+    fail(`TEST_RESULT_INVALID: 非法 result "${result}"`);
+  }
+  const exitCode = strictInteger(input.exit_code, 'TEST_RESULT_EXIT_CODE_INVALID', 'exit_code', 0);
+  const durationMs = strictInteger(input.duration_ms, 'TEST_RESULT_DURATION_INVALID', 'duration_ms', 0);
+  if (typeof input.counts_known !== 'boolean') {
+    fail('TEST_RESULT_COUNTS_KNOWN_REQUIRED: counts_known 必须是 boolean');
+  }
+  const failureType = requireStrictString(input.failure_type, 'TEST_RESULT_FAILURE_TYPE_REQUIRED', 'failure_type');
+  if (!['assertion', 'contract', 'compile', 'infrastructure', 'timeout', 'none'].includes(failureType)) {
+    fail(`TEST_RESULT_FAILURE_TYPE_INVALID: 非法 failure_type "${failureType}"`);
+  }
+  const expectedFailure = input.expected_failure === true;
+  if (expectedFailure && tddPhase !== 'red') {
+    fail('TEST_RESULT_EXPECTED_FAILURE_INVALID: expected_failure 仅允许用于 red 阶段');
+  }
+  if (exitCode === 0 && failureType !== 'none') {
+    fail('TEST_RESULT_FAILURE_TYPE_CONFLICT: exit_code=0 时 failure_type 必须为 none');
+  }
+  if (exitCode !== 0 && failureType === 'none') {
+    fail('TEST_RESULT_FAILURE_TYPE_CONFLICT: exit_code 非 0 时 failure_type 不能为 none');
+  }
+  if ((exitCode === 0 && result !== 'success') || (exitCode !== 0 && result !== 'failure')) {
+    fail(`E_RESULT_EXIT_CONFLICT: result=${result} 与 exit_code=${exitCode} 不一致`);
+  }
+
+  const taskId = String(args['task-id'] || args.task_id || input.task_id || '').trim();
+  const verifiedTaskIds = Array.isArray(input.verified_task_ids)
+    ? [...new Set(input.verified_task_ids.map(value => String(value || '').trim()).filter(Boolean))].sort()
+    : [];
+  if (!taskId && verifiedTaskIds.length === 0) {
+    fail('E_STRICT_FIELD_REQUIRED: strict test_result 必须提供 task_id 或 verified_task_ids');
+  }
+  if (taskId && !verifiedTaskIds.includes(taskId)) verifiedTaskIds.push(taskId);
+  verifiedTaskIds.sort();
+
+  const normalized = {
+    run_id: requireStrictString(args['run-id'] || args.run_id || input.run_id, 'EVENT_RUN_ID_REQUIRED', 'run_id'),
+    task_id: taskId || undefined,
+    verified_task_ids: verifiedTaskIds,
+    tdd_phase: tddPhase,
+    command,
+    result,
+    exit_code: exitCode,
+    counts_known: input.counts_known,
+    duration_ms: durationMs,
+    failure_type: failureType,
+    expected_failure: expectedFailure,
+    evidence_tier: 'strict',
+    valid_red: tddPhase === 'red'
+      ? expectedFailure && exitCode !== 0 && ['assertion', 'contract'].includes(failureType)
+      : false,
+  };
+  if (input.counts_known) {
+    normalized.passed = strictInteger(input.passed, 'TEST_RESULT_COUNTS_INVALID', 'passed', 0);
+    normalized.failed = strictInteger(input.failed, 'TEST_RESULT_COUNTS_INVALID', 'failed', 0);
+    normalized.skipped = strictInteger(input.skipped, 'TEST_RESULT_COUNTS_INVALID', 'skipped', 0);
+    if (normalized.exit_code === 0 && normalized.failed > 0) {
+      fail('TEST_RESULT_COUNTS_CONFLICT: exit_code=0 时 failed 不能大于 0');
+    }
+  }
+  return normalized;
+}
+
+function isValidCompletionTestResults(testResults) {
+  if (!testResults || typeof testResults !== 'object') return false;
+  if (!['green', 'refactor', 'regression'].includes(testResults.tdd_phase)) return false;
+  if (testResults.exit_code !== 0 || testResults.failure_type !== 'none') return false;
+  if (testResults.counts_known === true && Number(testResults.failed) !== 0) return false;
+  return true;
+}
+
+function normalizeStrictProcessNote(args, details) {
+  const input = details?.process_note && typeof details.process_note === 'object'
+    ? details.process_note
+    : details;
+  const kind = requireStrictString(input?.kind, 'PROCESS_NOTE_KIND_REQUIRED', 'kind');
+  if (!['user_decision', 'scope_change', 'api_error', 'model_error', 'recovery', 'test_exception'].includes(kind)) {
+    fail(`PROCESS_NOTE_KIND_INVALID: 非法 kind "${kind}"`);
+  }
+  const summary = String(args.summary || input?.summary || '').trim();
+  if (!summary) {
+    fail('PROCESS_NOTE_SUMMARY_REQUIRED: strict process_note 必须提供 summary');
+  }
+  return {
+    details: {
+      ...details,
+      kind,
+      process_note: {
+        ...(details.process_note || {}),
+        kind,
+        summary,
+      },
+    },
+    summary,
+    runId: requireStrictString(args['run-id'] || args.run_id || input?.run_id, 'EVENT_RUN_ID_REQUIRED', 'run_id'),
+  };
+}
+
+function normalizeStrictTaskUpdate(args, details, dataDir, change) {
+  const input = details?.task_update && typeof details.task_update === 'object'
+    ? details.task_update
+    : details;
+  const taskId = requireStrictString(
+    args['task-id'] || args.task_id || input?.task_id,
+    'EVENT_TASK_ID_REQUIRED',
+    'task_id',
+  );
+  const status = requireStrictString(args.status || input?.status, 'TASK_STATUS_REQUIRED', 'status');
+  if (!['started', 'blocked', 'completed', 'reopened'].includes(status)) {
+    fail(`TASK_STATUS_INVALID: 非法任务状态 "${status}"`);
+  }
+  const runId = requireStrictString(
+    args['run-id'] || args.run_id || input?.run_id,
+    'EVENT_RUN_ID_REQUIRED',
+    'run_id',
+  );
+  const testEventId = input?.test_event_id || details?.test_event_id || null;
+  const verificationNotApplicable = input?.verification_not_applicable === true
+    || details?.verification_not_applicable === true;
+  const verificationReason = String(
+    input?.verification_not_applicable_reason
+      || input?.verification_reason
+      || details?.verification_not_applicable_reason
+      || details?.verification_reason
+      || '',
+  ).trim();
+
+  if (status === 'completed') {
+    if (!testEventId && !verificationNotApplicable) {
+      fail('TASK_TEST_REFERENCE_MISSING: completed 任务必须引用 test_event_id，或声明 verification_not_applicable=true 并说明原因');
+    }
+    if (verificationNotApplicable && !verificationReason) {
+      fail('TASK_VERIFICATION_REASON_REQUIRED: verification_not_applicable 必须说明原因');
+    }
+    if (testEventId) {
+      const referenced = readEvents(dataDir, change).find(event => event.event_id === testEventId);
+      if (!referenced || referenced.type !== 'test_result') {
+        fail(`TASK_TEST_REFERENCE_MISSING: 同一 change 中不存在 test_result "${testEventId}"`);
+      }
+      const testResults = referenced.details?.test_results || {};
+      if (!isValidCompletionTestResults(testResults)) {
+        fail(`TASK_TEST_REFERENCE_INVALID: test_result "${testEventId}" 不能证明任务完成`);
+      }
+      const verifiedTaskIds = new Set([
+        referenced.task_id,
+        testResults.task_id,
+        ...(Array.isArray(testResults.verified_task_ids) ? testResults.verified_task_ids : []),
+      ].filter(Boolean));
+      if (testResults.evidence_tier !== 'strict' || !verifiedTaskIds.has(taskId)) {
+        fail(`E_TEST_IDENTITY_MISMATCH: test_result "${testEventId}" 未严格验证任务 "${taskId}"`);
+      }
+      if (typeof input?.tdd_required !== 'boolean') {
+        fail('TASK_TDD_REQUIRED_MISSING: completed 任务引用测试时必须明确 tdd_required=true/false');
+      }
+    }
+  }
+
+  return {
+    taskId,
+    status,
+    runId,
+    details: {
+      ...details,
+      task_update: {
+        ...(details.task_update || {}),
+        task_id: taskId,
+        status,
+        test_event_id: testEventId,
+        tdd_required: typeof input?.tdd_required === 'boolean' ? input.tdd_required : undefined,
+        test_requirement: input?.test_requirement
+          || (verificationNotApplicable ? 'not_applicable' : 'required'),
+        test_waiver_reason: input?.test_waiver_reason
+          || (verificationNotApplicable ? verificationReason : undefined),
+        verification_not_applicable: verificationNotApplicable,
+        verification_not_applicable_reason: verificationNotApplicable ? verificationReason : undefined,
+      },
+    },
+  };
+}
+
+function eventIdempotencyFingerprint(event) {
+  return JSON.stringify({
+    type: event.type,
+    source: event.source,
+    command: event.command,
+    stage: event.stage,
+    change: event.change,
+    capability: event.capability,
+    task_id: event.task_id,
+    run_id: event.run_id,
+    result: event.result,
+    status: event.status,
+    summary: event.summary,
+    details: event.details,
+  });
+}
+
+function buildApplyEvidenceAudit(change, taskModel, events = [], options = {}) {
+  const strict = options.mode !== 'report-only';
+  const completedTasks = (taskModel?.primary_tasks?.tasks || []).filter(task => task.completed);
+  const latestTaskUpdates = new Map();
+  const testEvents = new Map();
+  const testsByTask = new Map();
+  const uniqueTestRuns = new Set();
+  for (const event of events) {
+    if (event.change !== change) continue;
+    if (event.type === 'task_update'
+        && (event.status === 'completed' || event.details?.task_update?.status === 'completed')) {
+      const existing = latestTaskUpdates.get(event.task_id);
+      if (!existing || timestampMs(event) > timestampMs(existing)) {
+        latestTaskUpdates.set(event.task_id, event);
+      }
+      continue;
+    }
+    if (event.type === 'test_result') {
+      testEvents.set(event.event_id, event);
+      uniqueTestRuns.add(event.event_id);
+      const testResults = event.details?.test_results || {};
+      const verifiedTaskIds = [...new Set([
+        event.task_id,
+        testResults.task_id,
+        ...(Array.isArray(testResults.verified_task_ids) ? testResults.verified_task_ids : []),
+      ].filter(Boolean))];
+      for (const verifiedTaskId of verifiedTaskIds) {
+        const related = testsByTask.get(verifiedTaskId) || [];
+        related.push(event);
+        testsByTask.set(verifiedTaskId, related);
+      }
+    }
+  }
+  for (const related of testsByTask.values()) {
+    related.sort((a, b) => timestampMs(a) - timestampMs(b));
+  }
+  let withUpdate = 0;
+  let withTestEvidence = 0;
+  let tddRequired = 0;
+  let redGreenComplete = 0;
+  const findings = [];
+
+  for (const task of completedTasks) {
+    const update = latestTaskUpdates.get(task.task_id);
+    if (!update) {
+      findings.push({
+        code: 'TASK_UPDATE_MISSING',
+        severity: strict ? 'error' : 'warning',
+        task_id: task.task_id,
+        message: '主任务已标完成，但缺少 completed task_update 事件',
+      });
+      continue;
+    }
+    withUpdate += 1;
+    const updateDetails = update.details?.task_update || update.details || {};
+    const notApplicable = updateDetails.verification_not_applicable === true
+      && Boolean(String(updateDetails.verification_not_applicable_reason || '').trim());
+    const testEvent = updateDetails.test_event_id ? testEvents.get(updateDetails.test_event_id) : null;
+    const testResults = testEvent?.details?.test_results || {};
+    const verifiedTaskIds = new Set([
+      testEvent?.task_id,
+      testResults.task_id,
+      ...(Array.isArray(testResults.verified_task_ids) ? testResults.verified_task_ids : []),
+    ].filter(Boolean));
+    const validTest = Boolean(testEvent)
+      && testResults.evidence_tier === 'strict'
+      && verifiedTaskIds.has(task.task_id)
+      && isValidCompletionTestResults(testResults);
+    if (validTest || notApplicable) {
+      withTestEvidence += 1;
+    } else {
+      findings.push({
+        code: 'TASK_TEST_EVIDENCE_MISSING',
+        severity: strict ? 'error' : 'warning',
+        task_id: task.task_id,
+        message: 'completed task_update 没有有效测试引用或不适用理由',
+      });
+    }
+
+    if (updateDetails.tdd_required === true) {
+      tddRequired += 1;
+      const related = testsByTask.get(task.task_id) || [];
+      const redIndex = related.findIndex(event => event.details?.test_results?.valid_red === true);
+      const greenIndex = related.findIndex((event, index) => (
+        index > redIndex
+          && event.details?.test_results?.exit_code === 0
+          && ['green', 'regression'].includes(event.details?.test_results?.tdd_phase)
+      ));
+      if (redIndex >= 0 && greenIndex > redIndex) {
+        redGreenComplete += 1;
+      } else {
+        findings.push({
+          code: 'TDD_RED_GREEN_INCOMPLETE',
+          severity: strict ? 'error' : 'warning',
+          task_id: task.task_id,
+          message: 'TDD 任务缺少有效 RED→GREEN 顺序证据',
+        });
+      }
+    }
+  }
+
+  return {
+    mode: strict ? 'strict' : 'report-only',
+    status: findings.some(finding => finding.severity === 'error') ? 'blocked' : 'pass',
+    tasks: {
+      completed: completedTasks.length,
+      with_update: withUpdate,
+      with_test_evidence: withTestEvidence,
+    },
+    tdd: {
+      required: tddRequired,
+      red_green_complete: redGreenComplete,
+    },
+    tests: {
+      unique_runs: uniqueTestRuns.size,
+    },
+    findings,
+  };
+}
+
+function readEvents(dataDir, changeName) {
+  return readEventsRaw(dataDir, changeName)
+    .filter(event => event.change === changeName);
+}
+
+function scopeAttributionKey(sourceChange, targetEventId) {
+  return `${sourceChange}:${targetEventId}`;
+}
+
+function buildScopeAttributionState(events) {
+  const active = new Map();
+  const history = events
+    .filter(event => event.type === 'scope_link' || event.type === 'scope_unlink')
+    .sort((a, b) => timestampMs(a) - timestampMs(b));
+  for (const event of history) {
+    const details = event.details?.scope_attribution || {};
+    const sourceChange = details.source_change;
+    const targetEventId = details.target_event_id;
+    if (!sourceChange || !targetEventId) continue;
+    const key = scopeAttributionKey(sourceChange, targetEventId);
+    if (event.type === 'scope_link') {
+      active.set(key, {
+        source_change: sourceChange,
+        target_event_id: targetEventId,
+        target_change: event.change,
+        link_event_id: event.event_id,
+      });
+    } else {
+      const current = active.get(key);
+      if (current && current.target_change === event.change) active.delete(key);
+    }
+  }
+  return { active, history };
+}
+
+function resolveChangeEventsWithAttribution(dataDir, change) {
+  const allEvents = readAllEvents(dataDir);
+  const rawDirect = readEventsRaw(dataDir, change);
+  const direct = rawDirect.filter(event => event.change === change);
+  const rejectedDirectCollisions = rawDirect
+    .filter(event => event.change !== change)
+    .map(event => event.event_id);
+  const attribution = buildScopeAttributionState(allEvents);
+  const links = [...attribution.active.values()]
+    .filter(link => link.target_change === change);
+  const linked = [];
+  for (const link of links) {
+    linked.push(...readEvents(dataDir, link.source_change)
+      .filter(event => event.event_id === link.target_event_id)
+      .map(event => ({
+        ...event,
+        attribution: {
+          provenance: 'explicit-link',
+          source_change: link.source_change,
+          target_change: link.target_change,
+          link_event_id: link.link_event_id,
+        },
+      })));
+  }
+  const seen = new Set();
+  const events = [...direct, ...linked].filter((event) => {
+    const key = `${event.type}:${event.event_id}:${event.timestamp}`;
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+  const assignedSourceIds = new Set(
+    [...attribution.active.values()].map(link => scopeAttributionKey(
+      link.source_change,
+      link.target_event_id,
+    )),
+  );
+  const unassignedCandidates = readEvents(dataDir, 'general')
+    .filter(event => !assignedSourceIds.has(scopeAttributionKey('general', event.event_id)))
+    .map(event => event.event_id);
+  return {
+    events,
+    audit: {
+      linked_source_event_count: new Set(linked.map(event => event.event_id)).size,
+      active_links: links,
+      rejected_direct_collision_event_ids: [...new Set(rejectedDirectCollisions)],
+      unassigned_candidate_event_ids: [...new Set(unassignedCandidates)],
+    },
+  };
+}
+
 function cmdRecord(args) {
   const type = args.type || args['event-type'];
   const projectRoot = normalizeProjectRoot(args.project || args['project-root'] || process.cwd());
-  const change = args.change || args['change-name'] || 'general';
-  const source = args.source || 'opsx-command';
+  const strict = isTrueOption(args.strict);
+  const requestedChange = args.change || args['change-name'];
+  if (strict && !requestedChange) {
+    fail('EVENT_CHANGE_REQUIRED: strict 流程事件必须显式提供 --change');
+  }
+  if (requestedChange) {
+    requireValidChangeName(requestedChange);
+  }
+  if (strict && requestedChange === 'general') {
+    fail('E_GENERAL_SCOPE_FORBIDDEN: strict 流程事件不能写入 general');
+  }
+  const change = requestedChange || 'general';
+  const requestedSource = args.source;
+  const source = requestedSource || 'opsx-command';
   const agentType = inferAgentType(args);
   const allowedTypes = [
     'task_update',
@@ -3847,6 +5833,9 @@ function cmdRecord(args) {
     'worktree_finish',
     'process_note',
     'doc_update',
+    'maturity_evidence',
+    'scope_link',
+    'scope_unlink',
   ];
 
   if (!type) {
@@ -3880,19 +5869,6 @@ function cmdRecord(args) {
     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）；
@@ -3929,7 +5905,95 @@ function cmdRecord(args) {
     }
   }
 
+  if (type === 'maturity_evidence') {
+    const maturityValidation = validateMaturityEvidenceDetails(details);
+    if (!maturityValidation.valid) {
+      fail(`maturity_evidence 校验失败: ${maturityValidation.error}`);
+    }
+    details = {
+      ...details,
+      maturity_evidence: maturityValidation.evidence,
+    };
+  }
+
   const dataDir = getDataDir(projectRoot);
+  let strictRunId = args['run-id'] || args.run_id || details?.run_id;
+  let strictTaskId = args['task-id'] || args.task_id || details?.task_id;
+  let eventSummary = args.summary;
+  let eventStatus = args.status;
+  if (strict) {
+    const missingIdentity = [
+      ['session_id', args['session-id'] || args.session_id],
+      ['stage', args.stage || args.command],
+      ['source', requestedSource],
+      ['summary', args.summary],
+      ['run_id', strictRunId],
+    ].find(([, value]) => !String(value || '').trim());
+    if (missingIdentity) {
+      fail(`E_STRICT_FIELD_REQUIRED: strict 事件缺少 ${missingIdentity[0]}`);
+    }
+  }
+  if (type === 'scope_link' || type === 'scope_unlink') {
+    if (!strict) fail('E_SCOPE_ATTRIBUTION_STRICT_REQUIRED: scope 归属事件必须使用 --strict');
+    const sourceChange = requireStrictString(
+      args['source-change'] || args.source_change,
+      'E_STRICT_FIELD_REQUIRED',
+      'source_change',
+    );
+    requireValidChangeName(sourceChange);
+    const targetEventId = requireStrictString(
+      args['target-event-id'] || args.target_event_id,
+      'E_STRICT_FIELD_REQUIRED',
+      'target_event_id',
+    );
+    const attributionReason = requireStrictString(args.reason, 'E_STRICT_FIELD_REQUIRED', 'reason');
+    const sourceEvents = readEvents(dataDir, sourceChange)
+      .filter(event => event.event_id === targetEventId);
+    if (sourceEvents.length === 0) {
+      fail(`E_SCOPE_SOURCE_NOT_FOUND: ${sourceChange} 中不存在事件 "${targetEventId}"`);
+    }
+    const attribution = buildScopeAttributionState(readAllEvents(dataDir));
+    const key = scopeAttributionKey(sourceChange, targetEventId);
+    const current = attribution.active.get(key);
+    if (type === 'scope_link' && current && current.target_change !== change) {
+      fail(`E_SCOPE_LINK_CONFLICT: 事件已关联到 "${current.target_change}"，须先追加 scope_unlink`);
+    }
+    if (type === 'scope_unlink' && (!current || current.target_change !== change)) {
+      fail(`E_SCOPE_UNLINK_NOT_ACTIVE: 事件当前未关联到 "${change}"`);
+    }
+    details = {
+      ...details,
+      scope_attribution: {
+        source_change: sourceChange,
+        target_event_id: targetEventId,
+        target_change: change,
+        reason: attributionReason,
+      },
+    };
+  }
+  if (strict && type === 'test_result') {
+    const testResults = normalizeStrictTestResult(args, details);
+    strictRunId = testResults.run_id;
+    strictTaskId = testResults.task_id;
+    details = {
+      ...details,
+      test_results: testResults,
+    };
+  } else if (strict && type === 'process_note') {
+    const processNote = normalizeStrictProcessNote(args, details);
+    strictRunId = processNote.runId;
+    eventSummary = processNote.summary;
+    details = processNote.details;
+  } else if (strict && type === 'task_update') {
+    const taskUpdate = normalizeStrictTaskUpdate(args, details, dataDir, change);
+    strictRunId = taskUpdate.runId;
+    strictTaskId = taskUpdate.taskId;
+    eventStatus = taskUpdate.status;
+    details = taskUpdate.details;
+  } else if (strict) {
+    strictRunId = requireStrictString(strictRunId, 'EVENT_RUN_ID_REQUIRED', 'run_id');
+  }
+
   const activeStage = findActiveStage(projectRoot, {
     session_id: args['session-id'] || args.session_id,
     change,
@@ -3973,25 +6037,103 @@ function cmdRecord(args) {
     stage: args.stage || args.command,
     change,
     capability: args.capability || args['capability-name'],
-    task_id: args['task-id'] || args.task_id,
+    task_id: strictTaskId,
+    run_id: strictRunId,
     agent_type: agentType,
     project_root: projectRoot,
     session_id: activeStage?.session_id || args['session-id'] || args.session_id,
     git_sha: args['git-sha'] || args.git_sha,
     timestamp,
     result: args.result,
-    status: args.status,
-    summary: args.summary,
+    status: eventStatus,
+    summary: eventSummary,
     details,
   });
 
-  appendEvent(dataDir, event.change, event);
-  console.log(JSON.stringify({
-    event_id: eventId,
-    type,
-    recorded_at: timestamp,
-    message: `SDD ${type} 事件已记录（change: ${event.change}）`,
-  }, null, 2));
+  const syncTaskProjection = () => {
+    if (type !== 'task_update' || (args.result !== 'success' && eventStatus !== 'completed')) return;
+    try {
+      const taskId = strictTaskId || details?.task_id || null;
+      if (taskId) runCheckTaskSync(projectRoot, change, taskId);
+    } catch (taskErr) {
+      try { console.error(`[telemetry] tasks.md 主任务状态自动同步失败（不阻塞）: ${taskErr.message}`); } catch {}
+    }
+  };
+
+  const persistEvent = (lockHeld = false) => {
+    if (strict && event.run_id) {
+      const existing = readEvents(dataDir, change)
+        .find(candidate => candidate.type === event.type && candidate.run_id === event.run_id);
+      if (existing) {
+        if (eventIdempotencyFingerprint(existing) !== eventIdempotencyFingerprint(event)) {
+          const error = new Error(
+            `EVENT_RUN_ID_CONFLICT: ${event.type} 的 run_id "${event.run_id}" 已存在且内容不同`,
+          );
+          error.code = 'EVENT_RUN_ID_CONFLICT';
+          throw error;
+        }
+        syncTaskProjection();
+        return {
+          event_id: existing.event_id,
+          type,
+          recorded_at: existing.timestamp,
+          idempotent: true,
+          message: `SDD ${type} 事件已存在，幂等返回（change: ${existing.change}）`,
+        };
+      }
+    }
+
+    // scope_link/scope_unlink 的冲突判断必须与追加事实共用同一事件锁；
+    // 否则两个不同 run_id 的并发 link 都可能在锁外看到“未关联”并同时写入。
+    if (type === 'scope_link' || type === 'scope_unlink') {
+      const scopeDetails = event.details?.scope_attribution || {};
+      const key = scopeAttributionKey(scopeDetails.source_change, scopeDetails.target_event_id);
+      const current = buildScopeAttributionState(readAllEvents(dataDir)).active.get(key);
+      if (type === 'scope_link' && current && current.target_change !== change) {
+        const error = new Error(
+          `E_SCOPE_LINK_CONFLICT: 事件已关联到 "${current.target_change}"，须先追加 scope_unlink`,
+        );
+        error.code = 'E_SCOPE_LINK_CONFLICT';
+        throw error;
+      }
+      if (type === 'scope_unlink' && (!current || current.target_change !== change)) {
+        const error = new Error(`E_SCOPE_UNLINK_NOT_ACTIVE: 事件当前未关联到 "${change}"`);
+        error.code = 'E_SCOPE_UNLINK_NOT_ACTIVE';
+        throw error;
+      }
+    }
+
+    appendEvent(dataDir, event.change, event, { lockHeld });
+    // 事实先持久化，任务文档作为可重放投影；幂等重试会再次尝试补齐投影。
+    syncTaskProjection();
+    return {
+      event_id: eventId,
+      type,
+      recorded_at: timestamp,
+      idempotent: false,
+      message: `SDD ${type} 事件已记录（change: ${event.change}）`,
+    };
+  };
+
+  let output;
+  try {
+    if (type === 'scope_link' || type === 'scope_unlink') {
+      const scopeDetails = event.details.scope_attribution;
+      const scopeLockName = `scope-${crypto.createHash('sha256')
+        .update(scopeAttributionKey(scopeDetails.source_change, scopeDetails.target_event_id))
+        .digest('hex')
+        .slice(0, 24)}`;
+      output = withEventWriteLock(dataDir, scopeLockName, () => persistEvent(false));
+    } else {
+      output = strict && event.run_id
+        ? withEventWriteLock(dataDir, change, () => persistEvent(true))
+        : persistEvent(false);
+    }
+  } catch (error) {
+    fail(error.message || String(error));
+  }
+  console.log(JSON.stringify(output, null, 2));
+  return output;
 }
 
 /** 解析 node --test 的 TAP 输出为 {passed, failed, skipped}（opsx-apply agent 跑测试后传 --test-stdout） */
@@ -4135,7 +6277,7 @@ function cmdSnapshot(args) {
   return result;
 }
 
-/** archive 时聚合 events 生成"变更总结"段追加到 execution-log.md */
+/** archive 时从统一 Report Model 生成终态摘要，并通过受控 marker 幂等替换。 */
 function appendChangeSummary(projectRoot, changeName, events) {
   try {
     const changeDir = getChangeDir(projectRoot, changeName);
@@ -4146,34 +6288,49 @@ function appendChangeSummary(projectRoot, changeName, events) {
     }
     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 report = buildReport(projectRoot, events, { level: 'change', change: changeName });
+    const execution = computeChangeMetrics(changeName, events)?.change_summary || {};
+    const tests = report.change_summary?.tests || {};
+    const legacyTestEvent = tests.total == null
+      ? [...events].reverse().find((event) => {
+        const result = event?.details?.test_results;
+        return event?.type === 'test_result'
+          && Number.isFinite(Number(result?.passed))
+          && Number.isFinite(Number(result?.failed));
+      })
+      : null;
+    const documentTasks = report.change_summary?.tasks?.document || {};
+    const traceability = report.change_summary?.tasks?.traceability || {};
+    const evidence = report.change_summary?.evidence || {};
+    const legacyTests = legacyTestEvent?.details?.test_results;
+    const testPassStr = tests.total != null
+      ? `${tests.passed}/${tests.total}`
+      : (legacyTests
+        ? `${Number(legacyTests.passed)}/${Number(legacyTests.passed) + Number(legacyTests.failed) + Number(legacyTests.skipped || 0)}（历史事件兼容口径）`
+        : '无权威测试数据');
+    const markerStart = '<!-- change-summary:start -->';
+    const markerEnd = '<!-- change-summary:end -->';
     const summary = [
       '',
+      markerStart,
       '## 变更总结',
-      `- 阶段数：${stageStartCount} start / ${stageEndCount} end`,
-      `- 阶段重复执行次数：${repeatCount}`,
-      `- 测试通过率：${testPassStr}`,
-      `- 遗留问题：${unchecked > 0 ? `${unchecked} 项验收标准未勾选` : '无'}`,
+      `- 阶段数：${execution.stage_start_count ?? 0} start / ${execution.stage_end_count ?? 0} end`,
+      `- 阶段重复执行次数：${execution.stage_repeat_count ?? 0}`,
+      `- 最终测试（测试通过率）：${testPassStr}`,
+      `- 文档任务完成：${documentTasks.completed ?? '无数据'}/${documentTasks.total ?? '无数据'}`,
+      `- 事件可追溯：${traceability.verified ?? '无数据'}/${traceability.total ?? '无数据'}`,
+      `- 证据问题：${evidence.category_count ?? 0} 类，${evidence.occurrence_count ?? 0} 次规则命中`,
+      `- 结论：${report.conclusion?.text || '证据不足'}`,
+      markerEnd,
       '',
     ].join('\n');
-    fs.appendFileSync(file, summary + '\n', 'utf8');
+    const current = fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : renderExecutionLog(changeName, events);
+    const escapedStart = markerStart.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    const escapedEnd = markerEnd.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    const withoutOldSummary = current.replace(new RegExp(`\\n?${escapedStart}[\\s\\S]*?${escapedEnd}\\n?`, 'g'), '\n');
+    fs.writeFileSync(file, `${withoutOldSummary.trimEnd()}\n${summary}\n`, 'utf8');
   } catch (err) {
-    try { console.error(`[telemetry] 变更总结追加失败（不阻塞）: ${err.message}`); } catch {}
+    try { console.error(`[telemetry] 变更总结更新失败（不阻塞）: ${err.message}`); } catch {}
   }
 }
 
@@ -4271,7 +6428,9 @@ function cmdMetrics(args) {
   const pdfMvp = Boolean(args['pdf-mvp']);
 
   const dataDir = getDataDir(projectRoot);
-  let events = changeName ? readEvents(dataDir, changeName) : readAllEvents(dataDir);
+  let events = changeName
+    ? resolveChangeEventsWithAttribution(dataDir, changeName).events
+    : readAllEvents(dataDir);
 
   events = filterEventsByDate(events, dateFrom, dateTo);
 
@@ -4303,25 +6462,105 @@ function cmdMetrics(args) {
 /**
  * log report: 生成只读度量报告
  */
+function buildPeriodMetricSnapshot(metrics) {
+  return {
+    q3: metrics?.quality?.q3_spec_quality_score ?? null,
+    p4: metrics?.process?.p4_quality_gate_enforcement_rate ?? null,
+    p_h: metrics?.telemetry_health?.p_h_telemetry_health_score ?? null,
+    p_c: metrics?.process?.p_c_stage_closure_rate ?? null,
+    q1: metrics?.quality?.q1_spec_conformance_score ?? null,
+  };
+}
+
 function cmdReport(args) {
   const projectRoot = normalizeProjectRoot(args.project || args['project-root'] || process.cwd());
   const changeName = args.change || args['change-name'];
   const capability = args.capability || args['capability-name'];
   const dateFrom = args['date-from'];
   const dateTo = args['date-to'];
+  const period = args.period || null;
   const format = args.format || 'html';
   const outputPath = args.output || args['output-file'];
   const level = args.level || (capability ? 'capability' : (changeName ? 'change' : 'project'));
 
   const dataDir = getDataDir(projectRoot);
-  let events = changeName ? readEvents(dataDir, changeName) : readAllEvents(dataDir);
-  events = filterEventsByDate(events, dateFrom, dateTo);
+  if (level === 'change' && !changeName) {
+    fail('E_CHANGE_REQUIRED: change 级报告必须显式提供 --change');
+  }
+  if (changeName) {
+    requireValidChangeName(changeName);
+    const hasChangeData = fs.existsSync(getChangeDir(projectRoot, changeName))
+      || Boolean(findArchivedChangeDir(projectRoot, changeName))
+      || readEvents(dataDir, changeName).length > 0;
+    if (!hasChangeData) {
+      fail(`E_CHANGE_NOT_FOUND: 未找到变更 "${changeName}" 的目录、归档或事件`);
+    }
+  }
+  // 周期比较前保留完整事件集；日期过滤只作用于主报告窗口
+  const attributionResolution = changeName
+    ? resolveChangeEventsWithAttribution(dataDir, changeName)
+    : null;
+  const allEvents = attributionResolution ? attributionResolution.events : readAllEvents(dataDir);
+  let events = allEvents;
+  let trackingPeriods = null;
+
+  if (period && period !== 'change') {
+    if (period !== 'biweekly' && period !== 'monthly') {
+      console.error(JSON.stringify({
+        error: 'invalid-period',
+        message: `不支持的 period=${period}，仅支持 change|biweekly|monthly`,
+      }, null, 2));
+      process.exitCode = 1;
+      return;
+    }
+    if (!dateFrom || !dateTo) {
+      console.error(JSON.stringify({
+        error: 'invalid-window',
+        message: `${period} 报告需要同时提供 --date-from 与 --date-to`,
+      }, null, 2));
+      process.exitCode = 1;
+      return;
+    }
+    let windows;
+    try {
+      windows = metricsV3.buildTrackingPeriods({ period, dateFrom, dateTo });
+    } catch (err) {
+      console.error(JSON.stringify({
+        error: err.code || 'invalid-window',
+        message: err.message || String(err),
+      }, null, 2));
+      process.exitCode = 1;
+      return;
+    }
+    trackingPeriods = windows.map((window) => {
+      const windowEvents = filterEventsByDate(allEvents, window.date_from, window.date_to);
+      const windowMetrics = computePdfMvpMetrics(windowEvents, {
+        level: 'project',
+        projectRoot,
+      });
+      return {
+        ...window,
+        metrics: buildPeriodMetricSnapshot(windowMetrics),
+      };
+    });
+    events = filterEventsByDate(allEvents, dateFrom, dateTo);
+  } else {
+    events = filterEventsByDate(allEvents, dateFrom, dateTo);
+  }
 
   const report = buildReport(projectRoot, events, {
     level,
     change: changeName,
     capability,
+    period: period || null,
+    dateFrom: dateFrom || null,
+    dateTo: dateTo || null,
+    trackingPeriods,
+    attributionAudit: attributionResolution?.audit || null,
   });
+  if (trackingPeriods) {
+    report.tracking_periods = trackingPeriods;
+  }
   const rendered = format === 'json'
     ? JSON.stringify(report, null, 2)
     : format === 'html'
@@ -4355,7 +6594,9 @@ function cmdDoctor(args) {
   const dateTo = args['date-to'];
 
   const dataDir = getDataDir(projectRoot);
-  let events = changeName ? readEvents(dataDir, changeName) : readAllEvents(dataDir);
+  let events = changeName
+    ? resolveChangeEventsWithAttribution(dataDir, changeName).events
+    : readAllEvents(dataDir);
   events = filterEventsByDate(events, dateFrom, dateTo);
 
   const report = computeDoctorReport(events, { change: changeName, projectRoot });
@@ -4553,6 +6794,8 @@ function cmdArchiveDocs(args) {
       archivePath: archiveDir,
       archivedAt: result.created_at || result.archived_at,
       copiedSpecs: result.copied_specs,
+      finalizeAfterReports: true,
+      runIdentity: stageEnd?.event_id || `archive-docs:${changeName}`,
     });
     result = {
       ...result,
@@ -4665,7 +6908,7 @@ 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=html|markdown|json] [--output=<file>]（默认 html）
+  node skywalk-sdd/log.cjs report  --project=<path> [--change=<name>] [--format=html|markdown|json] [--output=<file>] [--period=change|biweekly|monthly] [--date-from=YYYY-MM-DD] [--date-to=YYYY-MM-DD]（默认 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>]
@@ -4700,6 +6943,7 @@ SDD Telemetry CLI - 流程度量采集工具
   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=maturity_evidence --command=archive --project=/my/project --change=user-auth --source=manual --details-file=skywalk-sdd/state/user-auth-maturity-evidence.json
   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
@@ -4750,6 +6994,7 @@ module.exports = {
   formatDuration,
   formatReworkReasons,
   buildReport,
+  buildApplyEvidenceAudit,
   computeGitDocumentMetrics,
   getCheckResults,
   getBuildResults,
@@ -4791,9 +7036,17 @@ module.exports = {
   parseJsonOption,
   writeActiveStage,
   findActiveStage,
+  resolveChangeEventsWithAttribution,
   clearActiveStage,
   findStartEvent,
   runCheckTaskSync,
+  resolveChangeDocumentRoot,
+  collectSpecFiles,
+  countSpecScenarios,
+  readChangeType,
+  buildV3ChangeContext,
+  parseSimpleFrontmatter,
+  buildPeriodMetricSnapshot,
 };
 
 // 直接运行时执行