kld-sdd 2.6.16 → 2.6.17

package/skywalk-sdd/index.cjs

@@ -17,6 +17,16 @@ const { resolveProjectArg } = require('./ontology/resolve-spec-root.cjs');
 const crypto = require('crypto');
 const { execFileSync } = require('child_process');
 const metricsV3 = require('./metrics-v3.cjs');
+const {
+  parseArgs,
+  ensureDir: sharedEnsureDir,
+  writeTextAtomic,
+  copyDirRecursive,
+  readJson: sharedReadJson,
+  stripBom,
+  today: sharedToday,
+  nowISO: sharedNowISO,
+} = require('./lib/shared.cjs');
 
 const SCHEMA_VERSION = 2;
 
@@ -58,11 +68,8 @@ const MEASUREMENT_STAGES = ['propose', 'spec', 'design', 'task', 'check', 'apply
 const AUXILIARY_STAGES = ['test', 'explore'];
 
 // ── 工具函数 ──────────────────────────────────────────
-function ensureDir(dirPath) {
-  if (!fs.existsSync(dirPath)) {
-    fs.mkdirSync(dirPath, { recursive: true });
-  }
-}
+// ensureDir 已迁移至 lib/shared.cjs
+const ensureDir = sharedEnsureDir;
 
 function generateEventId() {
   return 'evt_' + crypto.randomBytes(6).toString('hex');
@@ -99,7 +106,7 @@ function readJsonFile(filePath, projectRoot) {
   const resolved = path.isAbsolute(filePath)
     ? filePath
     : path.resolve(projectRoot || process.cwd(), filePath);
-  return JSON.parse(fs.readFileSync(resolved, 'utf8'));
+  return sharedReadJson(resolved);
 }
 
 function parseJsonOption(args, inlineKey, fileKey, projectRoot, fallback = {}) {
@@ -152,25 +159,8 @@ 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;
-  }
-}
+// atomicWriteText 已迁移至 lib/shared.cjs
+const atomicWriteText = writeTextAtomic;
 
 function requireValidChangeName(name) {
   if (typeof name === 'string'
@@ -320,19 +310,8 @@ function walkFiles(dirPath, predicate, files = []) {
   return files;
 }
 
-function copyDirSync(sourceDir, targetDir) {
-  ensureDir(targetDir);
-  for (const entry of fs.readdirSync(sourceDir, { withFileTypes: true })) {
-    const sourcePath = path.join(sourceDir, entry.name);
-    const targetPath = path.join(targetDir, entry.name);
-    if (entry.isDirectory()) {
-      copyDirSync(sourcePath, targetPath);
-    } else {
-      ensureDir(path.dirname(targetPath));
-      fs.copyFileSync(sourcePath, targetPath);
-    }
-  }
-}
+// copyDirSync 已迁移至 lib/shared.cjs（copyDirRecursive）
+const copyDirSync = copyDirRecursive;
 
 function nextAvailableDir(baseDir, preferredName) {
   let candidate = path.join(baseDir, preferredName);
@@ -849,9 +828,10 @@ function countSpecScenarios(projectRoot, changeName) {
     seen.add(abs);
     let text = '';
     try { text = fs.readFileSync(abs, 'utf8'); } catch { text = ''; }
-    const count = metricsV3.countScenariosInMarkdown(text);
+    const scenarios = metricsV3.extractScenariosInMarkdown(text);
+    const count = scenarios.length;
     total += count;
-    files.push({ path: toProjectRelative(projectRoot, abs), count });
+    files.push({ path: toProjectRelative(projectRoot, abs), count, scenarios });
   }
   return { scenario_count: total, files, source, root: toProjectRelative(projectRoot, root) };
 }
@@ -893,7 +873,9 @@ function buildV3ChangeContext(events, executionSummary, options = {}) {
   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,
+    total_stage_duration_ms: Object.prototype.hasOwnProperty.call(options, '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,
@@ -1905,7 +1887,9 @@ function summarizeStageExecutions(events) {
       start,
       end,
       result: end?.result || null,
-      duration_ms: Number.isFinite(end?.duration_ms) ? end.duration_ms : 0,
+      duration_ms: Number.isFinite(end?.duration_ms) && end.duration_ms >= 0
+        ? end.duration_ms
+        : null,
       canonical: false,
       rework_reason: null,
     };
@@ -1935,7 +1919,7 @@ function summarizeStageExecutions(events) {
     if (canonical) {
       canonical.canonical = true;
       canonicalAttempts.push(canonical);
-      effectiveStageDurationMs += canonical.duration_ms;
+      effectiveStageDurationMs += Number.isFinite(canonical.duration_ms) ? canonical.duration_ms : 0;
     }
 
     for (const attempt of groupAttempts) {
@@ -1967,8 +1951,9 @@ function summarizeStageExecutions(events) {
         if (attempt.end) {
           completedReworkAttempts += 1;
           bucket.completed_rework_attempts += 1;
-          bucket.rework_duration_ms += attempt.duration_ms;
-          reworkStageDurationMs += attempt.duration_ms;
+          const reworkDurationMs = Number.isFinite(attempt.duration_ms) ? attempt.duration_ms : 0;
+          bucket.rework_duration_ms += reworkDurationMs;
+          reworkStageDurationMs += reworkDurationMs;
         } else {
           supersededOpenStages += 1;
           bucket.superseded_open_stages += 1;
@@ -2250,9 +2235,14 @@ function getCheckResults(event) {
     categories: results.categories || {},
     // V3 Q3: reviewer 元信息，用于评估 reviewer_independence/score_status（缺失时保持 null，不影响旧字段）
     reviewer: results.reviewer || null,
+    review_execution_mode: results.review_execution_mode || null,
+    reviewer_agent_id: results.reviewer_agent_id || null,
     review_session_id: results.review_session_id || null,
+    reviewer_session_id: results.reviewer_session_id || null,
     author_session_id: results.author_session_id || null,
     reviewer_independence: results.reviewer_independence || null,
+    fallback_reason_code: results.fallback_reason_code || null,
+    fallback_reason: results.fallback_reason || null,
     warning_items: Array.isArray(results.warning_items) ? results.warning_items : [],
     warning_dispositions: Array.isArray(results.warning_dispositions) ? results.warning_dispositions : [],
   };
@@ -2967,7 +2957,20 @@ function computeSinglePdfMvpMetrics(events, options = {}) {
     ? new Date(archiveEnd.timestamp).getTime() - new Date(proposeStart.timestamp).getTime()
     : null;
 
-  const totalStageDuration = executionSummary.summary.total_stage_duration_ms;
+  // E1 只在全部纳入加总的已结束阶段都有合法耗时时发布：
+  // 没有配对记录或任一耗时缺失都代表“没有足够证据”，不能解释为真实耗时为 0。
+  const e1DurationAttempts = [
+    ...executionSummary.canonicalAttempts,
+    ...executionSummary.reworkAttempts.filter(attempt => attempt.end),
+  ];
+  const hasCompleteE1DurationEvidence = e1DurationAttempts.length > 0
+    && e1DurationAttempts.every(attempt => (
+      Number.isFinite(attempt.end?.duration_ms)
+      && attempt.end.duration_ms >= 0
+    ));
+  const totalStageDuration = hasCompleteE1DurationEvidence
+    ? executionSummary.summary.total_stage_duration_ms
+    : null;
   const codingDuration = sumDurations(ends, ['apply']);
   const specDuration = sumDurations(ends, ['propose', 'spec', 'design', 'task']);
   const reworkCodingDuration = sumAttemptDurations(executionSummary.reworkAttempts, ['apply']);
@@ -3020,6 +3023,26 @@ function computeSinglePdfMvpMetrics(events, options = {}) {
       && timestampMs(attempt.end) <= timestampMs(firstApply)
     ))
     : null;
+  const qualifyingCheckAttempts = firstApply
+    ? executionSummary.attempts.filter(attempt => (
+      attempt.command === 'check'
+      && attempt.end
+      && ['success', 'partial'].includes(attempt.result)
+      && timestampMs(attempt.end) <= timestampMs(firstApply)
+    ))
+    : [];
+  const p4Evidence = {
+    first_apply_started_at: firstApply?.timestamp || null,
+    first_apply_event_id: firstApply?.event_id || null,
+    qualifying_check_count: qualifyingCheckAttempts.length,
+    qualifying_checks: qualifyingCheckAttempts.map(attempt => ({
+      result: attempt.result,
+      started_at: attempt.start?.timestamp || null,
+      ended_at: attempt.end?.timestamp || null,
+      start_event_id: attempt.start?.event_id || null,
+      end_event_id: attempt.end?.event_id || null,
+    })),
+  };
   const latestCheckWithFixRate = latestByTimestamp(checkEvents.filter(e => {
     const results = getCheckResults(e);
     return results?.total > 0 && results.fixed_before_apply != null;
@@ -3049,8 +3072,13 @@ function computeSinglePdfMvpMetrics(events, options = {}) {
     reviewer: latestCheckResultsV3?.reviewer || null,
     author: formalApplyAttempt?.start?.session_id || formalApplyAttempt?.start?.agent_type || null,
     reviewer_independence: latestCheckResultsV3?.reviewer_independence || null,
+    review_execution_mode: latestCheckResultsV3?.review_execution_mode || null,
+    reviewer_agent_id: latestCheckResultsV3?.reviewer_agent_id || null,
     review_session_id: latestCheckResultsV3?.review_session_id || null,
+    reviewer_session_id: latestCheckResultsV3?.reviewer_session_id || null,
     author_session_id: latestCheckResultsV3?.author_session_id || formalApplyAttempt?.start?.session_id || null,
+    fallback_reason_code: latestCheckResultsV3?.fallback_reason_code || null,
+    fallback_reason: latestCheckResultsV3?.fallback_reason || null,
   };
   const q3Result = metricsV3.computeSpecQualityScore(latestCheckResultsV3, checkMeta);
 
@@ -3074,11 +3102,21 @@ function computeSinglePdfMvpMetrics(events, options = {}) {
     completed_stages: completedStages,
     missing: missingRequiredStages,
   };
-  const pHTelemetryHealthScore = Number.isFinite(telemetryHealth.telemetry_health_score)
-    ? metricsV3.round(telemetryHealth.telemetry_health_score * 100, 2)
-    : null;
+  const pHTelemetryHealthScore = measurementEvents.length === 0
+    ? null
+    : (Number.isFinite(telemetryHealth.telemetry_health_score_percent)
+      ? telemetryHealth.telemetry_health_score_percent
+      : (Number.isFinite(telemetryHealth.telemetry_health_score)
+        ? metricsV3.round(telemetryHealth.telemetry_health_score * 100, 2)
+        : null));
 
-  const reworkSummary = compactReworkSummary(executionSummary.summary, reworkReasons);
+  const compactedReworkSummary = compactReworkSummary(executionSummary.summary, reworkReasons);
+  const reworkSummary = executionSummary.attempts.length === 0
+    ? {
+      ...compactedReworkSummary,
+      total_rework_attempts: null,
+    }
+    : compactedReworkSummary;
 
   const v3Context = buildV3ChangeContext(scopedEvents, executionSummary, {
     change_name: options.change || null,
@@ -3117,6 +3155,7 @@ function computeSinglePdfMvpMetrics(events, options = {}) {
         : (completeMeasurementJourney ? 'trusted' : 'provisional'),
       reason: e1AvailabilityReason || incompleteJourneyReason,
       source_event_count: measurementEvents.length,
+      event_ids: measurementEvents.map(event => event.event_id).filter(Boolean),
     },
     q3: {
       status: v3.quality.q3_score_status === 'verified'
@@ -3125,6 +3164,7 @@ function computeSinglePdfMvpMetrics(events, options = {}) {
         : (v3.quality.q3_availability ? 'provisional' : 'missing'),
       reason: v3.quality.q3_availability_reason,
       source_event_count: checkEvents.length,
+      event_ids: checkEvents.map(event => event.event_id).filter(Boolean),
     },
     p4: {
       status: !firstApply
@@ -3132,6 +3172,10 @@ function computeSinglePdfMvpMetrics(events, options = {}) {
         : (completeMeasurementJourney ? 'trusted' : 'provisional'),
       reason: firstApply ? incompleteJourneyReason : 'missing-apply-stage',
       source_event_count: executionSummary.attempts.filter(attempt => attempt.command === 'check').length,
+      event_ids: [
+        p4Evidence.first_apply_event_id,
+        ...p4Evidence.qualifying_checks.flatMap(item => [item.start_event_id, item.end_event_id]),
+      ].filter(Boolean),
     },
     p_r: {
       status: executionSummary.attempts.length === 0
@@ -3139,6 +3183,9 @@ function computeSinglePdfMvpMetrics(events, options = {}) {
         : (completeMeasurementJourney ? 'trusted' : 'provisional'),
       reason: executionSummary.attempts.length > 0 ? incompleteJourneyReason : 'missing-stage-events',
       source_event_count: executionSummary.attempts.length,
+      event_ids: executionSummary.attempts
+        .flatMap(attempt => [attempt.start?.event_id, attempt.end?.event_id])
+        .filter(Boolean),
     },
     p_h: {
       status: measurementEvents.length === 0
@@ -3146,6 +3193,7 @@ function computeSinglePdfMvpMetrics(events, options = {}) {
         : (completeMeasurementJourney ? 'trusted' : 'provisional'),
       reason: measurementEvents.length > 0 ? incompleteJourneyReason : 'missing-stage-events',
       source_event_count: measurementEvents.length,
+      event_ids: measurementEvents.map(event => event.event_id).filter(Boolean),
     },
   };
 
@@ -3167,7 +3215,7 @@ function computeSinglePdfMvpMetrics(events, options = {}) {
         ? Math.max(0, leadTime - executionSummary.summary.effective_stage_duration_ms)
         : null,
       rework_stage_duration_ms: executionSummary.summary.rework_stage_duration_ms,
-      total_stage_duration_ms: executionSummary.summary.total_stage_duration_ms,
+      total_stage_duration_ms: totalStageDuration,
       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)
@@ -3199,6 +3247,11 @@ function computeSinglePdfMvpMetrics(events, options = {}) {
       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_total: v3.quality.q3_total,
+      q3_errors: v3.quality.q3_errors,
+      q3_warnings: v3.quality.q3_warnings,
+      q3_suggestions: v3.quality.q3_suggestions,
+      q3_review: v3.quality.q3_review,
       q3_availability: v3.quality.q3_availability,
       // Q1/Q4 上游信号未就绪时用 pending-upstream 标注，不把 null 误转成 0
       q1_status: v3.quality.q1_spec_conformance.status,
@@ -3211,6 +3264,7 @@ function computeSinglePdfMvpMetrics(events, options = {}) {
       p2_ai_code_adoption_level: aiAdoptionMetrics.adoption_level,
       ai_adoption_counts: aiAdoptionMetrics.adoption_counts,
       p4_quality_gate_enforcement_rate: qualityGateRate,
+      p4_evidence: p4Evidence,
       p4b_check_fixed_rate: fixRate,
       git_document_metrics: gitDocumentMetrics,
       rework_summary: reworkSummary,
@@ -3354,9 +3408,11 @@ function computePdfMvpMetrics(events, options = {}) {
       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,
+        p_h_telemetry_health_score: Number.isFinite(health.telemetry_health_score_percent)
+          ? health.telemetry_health_score_percent
+          : (Number.isFinite(health.telemetry_health_score)
+            ? metricsV3.round(health.telemetry_health_score * 100, 2)
+            : null),
       };
     })(),
     by_change: byChange,
@@ -4247,6 +4303,17 @@ function fileListSymmetricDiff(left, right) {
 
 // ── U1 报告维度提取辅助：从 events/metrics/doctor/archive 提炼 5 维度，数据缺失诚实标注 _available: false ──
 function extractChangedFiles(events, projectRoot) {
+  const snapshotEvents = events.filter(event => (
+    event?.type === 'final_output_snapshot'
+    && event.details?.final_output_snapshot
+    && typeof event.details.final_output_snapshot === 'object'
+  ));
+  const latestSnapshotEvent = latestByTimestamp(snapshotEvents);
+  const snapshotValidation = latestSnapshotEvent
+    ? validateFinalOutputSnapshot(latestSnapshotEvent.details.final_output_snapshot)
+    : null;
+  const finalSnapshot = snapshotValidation?.ok ? snapshotValidation.snapshot : null;
+  const invalidFinalSnapshot = Boolean(latestSnapshotEvent && !snapshotValidation?.ok);
   const adoptionEvents = getAiAdoptionEvents(events);
   const finalAdoptionEvents = adoptionEvents.filter((event) => {
     const review = getAiAdoptionReview(event);
@@ -4258,25 +4325,47 @@ function extractChangedFiles(events, projectRoot) {
     finalAdoptionEvents.length > 0 ? finalAdoptionEvents : adoptionEvents,
   );
   const review = latest ? getAiAdoptionReview(latest) : null;
-  const aiDiff = review?.ai_diff || null;
+  const aiDiff = latestSnapshotEvent ? null : (review?.ai_diff || null);
   const taskUpdateFiles = new Set();
+  const taskEventIds = [];
+  const taskIds = [];
+  const noFileChangeReasons = [];
+  let taskEventLatestAt = null;
   for (const e of events) {
     if (e?.type !== 'task_update') continue;
-    const filesField = e.details?.files
+    const taskUpdate = e.details?.task_update || {};
+    const filesField = taskUpdate.files
+      || e.details?.files
       || e.details?.test_results?.files
       || (Array.isArray(e.details?.files_changed) ? e.details.files_changed : null);
-    if (Array.isArray(filesField)) {
+    const reason = taskUpdate.no_file_change_reason || e.details?.no_file_change_reason;
+    if (typeof reason === 'string' && reason.trim()) {
+      noFileChangeReasons.push({
+        task_id: e.task_id || taskUpdate.task_id || null,
+        event_id: e.event_id || null,
+        reason: reason.trim(),
+      });
+    }
+    if (Array.isArray(filesField) && filesField.length > 0) {
+      if (e.event_id) taskEventIds.push(e.event_id);
+      const taskId = e.task_id || taskUpdate.task_id;
+      if (taskId) taskIds.push(taskId);
+      if (!taskEventLatestAt || timestampMs(e) > Date.parse(taskEventLatestAt)) {
+        taskEventLatestAt = e.timestamp || null;
+      }
       for (const f of filesField) {
         if (typeof f === 'string' && f.trim()) taskUpdateFiles.add(f.trim());
       }
     }
   }
   const finalOutputFiles = new Set(
-    Array.isArray(aiDiff?.files)
-      ? aiDiff.files.filter(file => typeof file === 'string' && file.trim()).map(file => file.trim())
-      : [],
+    Array.isArray(finalSnapshot?.files)
+      ? finalSnapshot.files.filter(file => typeof file === 'string' && file.trim()).map(file => file.trim())
+      : (Array.isArray(aiDiff?.files)
+        ? aiDiff.files.filter(file => typeof file === 'string' && file.trim()).map(file => file.trim())
+        : [])
   );
-  if (finalOutputFiles.size === 0 && latest?.details) {
+  if (!finalSnapshot && finalOutputFiles.size === 0 && latest?.details) {
     const rawReview = latest.details.ai_adoption
       || latest.details.ai_adoption_review
       || latest.details.ai_code_adoption
@@ -4290,23 +4379,40 @@ function extractChangedFiles(events, projectRoot) {
 
   const taskEventFileList = sortedUniqueFileList([...taskUpdateFiles]);
   const finalOutputFileList = sortedUniqueFileList([...finalOutputFiles]);
-  const taskUpdateFileCount = taskEventFileList.length;
-  const finalOutputFileCount = Number.isFinite(aiDiff?.files_changed)
-    ? aiDiff.files_changed
-    : (finalOutputFileList.length > 0 ? finalOutputFileList.length : null);
-  const snapshotKind = aiDiff?.snapshot_kind
-    || ((review?.review_status === 'final' || latest?.status === 'final') ? 'final' : null);
+  const taskEvidenceAvailable = taskEventFileList.length > 0 || noFileChangeReasons.length > 0;
+  const taskUpdateFileCount = taskEvidenceAvailable ? taskEventFileList.length : null;
+  const finalOutputFileCount = finalSnapshot
+    ? (Number.isFinite(finalSnapshot.files_changed)
+      ? finalSnapshot.files_changed
+      : finalOutputFileList.length)
+    : (Number.isFinite(aiDiff?.files_changed)
+      ? aiDiff.files_changed
+      : (finalOutputFileList.length > 0 ? finalOutputFileList.length : null));
+  const snapshotKind = finalSnapshot
+    ? finalSnapshot.snapshot_kind
+    : (latestSnapshotEvent
+      ? null
+      : (aiDiff?.snapshot_kind
+        || ((review?.review_status === 'final' || latest?.status === 'final') ? 'final' : 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);
+  const addedLines = finalSnapshot
+    ? (Number.isFinite(finalSnapshot.added_lines) ? finalSnapshot.added_lines : null)
+    : (Number.isFinite(aiDiff?.added_lines)
+      ? aiDiff.added_lines
+      : (Number.isFinite(review?.final_diff?.added_lines) ? review.final_diff.added_lines : null));
+  const deletedLines = finalSnapshot
+    ? (Number.isFinite(finalSnapshot.deleted_lines) ? finalSnapshot.deleted_lines : null)
+    : (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 && finalOutputFileList.length > 0 && projectRoot) {
+  if (!finalSnapshot
+    && addedLines == null
+    && review?.ai_git_sha == null
+    && finalOutputFileList.length > 0
+    && projectRoot) {
     let lines = 0;
     let countedFiles = 0;
     const root = path.resolve(projectRoot);
@@ -4331,27 +4437,26 @@ function extractChangedFiles(events, projectRoot) {
       };
     }
   }
-  // Prefer final AI snapshot for public files_changed when available.
-  const filesChanged = finalOutputStatus === 'final' && finalOutputFileCount != null
-    ? finalOutputFileCount
-    : (taskUpdateFileCount > 0 ? taskUpdateFileCount : finalOutputFileCount);
-  const countsDiffer = taskUpdateFileCount > 0
+  // 对外的 files_changed 只代表最终实际交付；任务事件文件始终使用独立字段。
+  const filesChanged = finalOutputStatus === 'final' ? finalOutputFileCount : null;
+  const countsDiffer = taskUpdateFileCount != null
     && finalOutputFileCount != null
     && taskUpdateFileCount !== finalOutputFileCount;
   const listDiff = fileListSymmetricDiff(taskEventFileList, finalOutputFileList);
-  const listsDiffer = taskUpdateFileCount > 0
-    && finalOutputFileList.length > 0
+  const listsDiffer = taskUpdateFileCount != null
+    && finalOutputFileCount != null
     && (listDiff.only_in_task_events.length > 0 || listDiff.only_in_final_output.length > 0);
   let reconciliationStatus = 'unavailable';
   let reconciliationNote = '没有可用的文件变更证据。';
-  if (taskUpdateFileCount === 0 && finalOutputFileCount == null) {
+  if (taskUpdateFileCount == null && finalOutputFileCount == null) {
     reconciliationStatus = 'unavailable';
     reconciliationNote = '没有可用的文件变更证据。';
-  } else if (taskUpdateFileCount === 0 || finalOutputFileCount == null) {
-    reconciliationStatus = 'unavailable';
-    reconciliationNote = finalOutputFileCount == null
-      ? '最终输出文件快照不可用，无法与任务事件对账。'
-      : '任务事件未记录文件清单；仅展示最终输出快照。';
+  } else if (finalOutputFileCount == null) {
+    reconciliationStatus = 'final-snapshot-missing';
+    reconciliationNote = '最终输出文件快照不可用，无法与任务事件对账。';
+  } else if (taskUpdateFileCount == null) {
+    reconciliationStatus = 'task-evidence-missing';
+    reconciliationNote = '任务事件未记录文件清单或无文件原因；仅展示最终输出快照。';
   } else if (countsDiffer) {
     reconciliationStatus = 'count-mismatch';
     reconciliationNote = `任务事件累计涉及 ${taskUpdateFileCount} 个文件；最终输出快照包含 ${finalOutputFileCount} 个文件。两者用途不同，不应合并为一个口径。`;
@@ -4363,17 +4468,37 @@ function extractChangedFiles(events, projectRoot) {
     reconciliationNote = '任务事件与最终输出文件口径一致。';
   }
   return {
-    _available: filesChanged != null,
+    _available: filesChanged != null || taskUpdateFileCount != null,
     files_changed: filesChanged,
     added_lines: addedLines,
     deleted_lines: deletedLines,
     files: finalOutputFileList.length > 0 ? finalOutputFileList : null,
-    task_event_files: taskUpdateFileCount > 0 ? taskEventFileList : null,
-    task_event_files_changed: taskUpdateFileCount > 0 ? taskUpdateFileCount : null,
+    task_event_files: taskUpdateFileCount != null ? taskEventFileList : null,
+    task_event_files_changed: taskUpdateFileCount,
+    task_event_source: 'task_update.files',
+    task_event_task_ids: [...new Set(taskIds)],
+    task_event_ids: [...new Set(taskEventIds)],
+    task_event_latest_at: taskEventLatestAt,
+    no_file_change_reasons: noFileChangeReasons,
     final_output_files: finalOutputFileList.length > 0 ? finalOutputFileList : null,
     final_output_files_changed: finalOutputFileCount,
     final_output_status: finalOutputStatus,
-    diff_source: snapshotKind === 'final' ? 'ai-diff-final' : (aiDiff ? 'ai-diff-provisional' : 'task-events'),
+    final_output_source: finalSnapshot
+      ? 'final_output_snapshot.files'
+      : (snapshotKind === 'final' ? 'ai-diff-final（旧事件兼容）' : null),
+    final_output_event_id: latestSnapshotEvent?.event_id || latest?.event_id || null,
+    final_output_captured_at: latestSnapshotEvent?.timestamp || latest?.timestamp || null,
+    final_output_no_output_reason: finalSnapshot?.no_output_reason || null,
+    final_output_vcs_mode: finalSnapshot?.vcs_mode || null,
+    final_output_validation_status: invalidFinalSnapshot ? 'invalid' : (finalSnapshot ? 'valid' : 'unavailable'),
+    final_output_validation_reason: invalidFinalSnapshot
+      ? `${snapshotValidation.code}: ${snapshotValidation.message}`
+      : null,
+    diff_source: finalSnapshot
+      ? 'final-output-snapshot'
+      : (invalidFinalSnapshot
+        ? 'invalid-final-output-snapshot'
+        : (snapshotKind === 'final' ? 'ai-diff-final' : (aiDiff ? 'ai-diff-provisional' : 'task-events'))),
     line_count_estimate: lineCountEstimate,
     reconciliation_status: reconciliationStatus,
     reconciliation_note: reconciliationNote,
@@ -4434,6 +4559,8 @@ function extractStageTimeline(events) {
     return {
       stage: cmd,
       round,
+      start_event_id: start.event_id || null,
+      end_event_id: end?.event_id || null,
       start_ts: start.timestamp || null,
       end_ts: end?.timestamp || null,
       duration_ms: end && Number.isFinite(end.duration_ms) ? end.duration_ms : null,
@@ -5141,11 +5268,14 @@ function computeDoctorReport(events, options = {}) {
     outdatedSchemaEvents.length * 0.06 +
     missingChangeEvents.length * 0.04 +
     missingCapabilityEvents.length * 0.01;
-  const denominator = Math.max(stageEvents.length, 1);
-  const telemetryHealthScore = Math.max(0, Math.round((1 - penalty / denominator) * 100) / 100);
+  const telemetryHealth = metricsV3.computeTelemetryHealthScore({
+    weighted_issue_value: penalty,
+    stage_event_count: stageEvents.length,
+  });
 
   return {
-    telemetry_health_score: telemetryHealthScore,
+    telemetry_health_score: telemetryHealth.ratio,
+    telemetry_health_score_percent: telemetryHealth.score,
     matched_stage_rate: matchedStageRate == null ? null : Math.round(matchedStageRate * 100) / 100,
     total_events: scopedEvents.length,
     stage_events: stageEvents.length,
@@ -5173,19 +5303,8 @@ function computeDoctorReport(events, options = {}) {
 
 // ── CLI 参数解析 ──────────────────────────────────────
 
-/** 解析 --key=value 格式的参数 */
-function parseArgs(argv) {
-  const args = {};
-  for (const arg of argv) {
-    const match = arg.match(/^--([a-zA-Z_-]+)=(.*)$/);
-    if (match) {
-      args[match[1]] = match[2];
-    } else if (arg.match(/^--([a-zA-Z_-]+)$/)) {
-      args[arg.slice(2)] = true;
-    }
-  }
-  return args;
-}
+// parseArgs 已迁移至 lib/shared.cjs（统一 5 份实现）
+// 本文件顶部已通过 require 引入，此处保留 const 别名以兼容内部引用
 
 // ── CLI 命令实现 ─────────────────────────────────────
 
@@ -5348,7 +5467,21 @@ function cmdEnd(args, options = {}) {
     fail('E_CHANGE_REQUIRED: 无法解析 start 的 end 必须显式提供 --change');
   }
   if (startEvent && requestedChange && startEvent.change !== requestedChange) {
-    fail(`E_CHANGE_CONFLICT: end 指定 change "${requestedChange}"，但 active stage 属于 "${startEvent.change}"`);
+    // BUGFIX: 允许 start 使用占位 change（如 pending）时 end 指定真实 change-key 自动迁移
+    // 场景：propose 阶段初期不知道最终 change-key，start 使用 --change=pending 占位，
+    // 后期生成 change-key 后 end 使用真实名称。此时应允许并自动迁移事件文件。
+    const PLACEHOLDER_CHANGES = new Set(['pending']);
+    if (PLACEHOLDER_CHANGES.has(startEvent.change)) {
+      // 将 start 事件复制到新的 change 文件下，保持 event_id 连续性
+      if (process.env.SDD_DEBUG_TELEMETRY) {
+        console.error(`[telemetry] migrating start event from placeholder "${startEvent.change}" → "${requestedChange}" (event_id=${eventId})`);
+      }
+      appendEvent(dataDir, requestedChange, startEvent, { lockHeld: false });
+      // 更新内存中的 startEvent.change 供后续使用
+      startEvent = { ...startEvent, change: requestedChange };
+    } else {
+      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';
@@ -5693,6 +5826,426 @@ function strictInteger(value, code, fieldName, minimum = 0) {
   return number;
 }
 
+function strictStructuredInteger(value, code, fieldName, minimum = 0) {
+  if (!Number.isInteger(value) || value < minimum) {
+    fail(`${code}: ${fieldName} 必须是大于等于 ${minimum} 的整数`);
+  }
+  return value;
+}
+
+const CHECK_FALLBACK_REASON_CODES = new Set([
+  'SUBAGENT_CAPABILITY_UNAVAILABLE',
+  'SUBAGENT_PERMISSION_DENIED',
+  'SUBAGENT_START_FAILED',
+  'SUBAGENT_TIMEOUT',
+  'SUBAGENT_RESULT_INVALID',
+]);
+
+const CHECK_IDENTITY_PLACEHOLDERS = new Set([
+  'unknown',
+  'none',
+  'null',
+  'n/a',
+  'na',
+  '未记录',
+  '未知',
+]);
+
+function isMeaningfulCheckIdentity(value) {
+  const normalized = String(value || '').trim();
+  if (!normalized) return false;
+  if (CHECK_IDENTITY_PLACEHOLDERS.has(normalized.toLowerCase())) return false;
+  if (/^<[^>]+>$/.test(normalized) || /^\[[^\]]+\]$/.test(normalized)) return false;
+  return true;
+}
+
+function normalizeRepositoryRelativeFiles(files, {
+  requiredCode,
+  invalidCode,
+  fieldName,
+} = {}) {
+  if (!Array.isArray(files)) {
+    const code = requiredCode || invalidCode || 'REPOSITORY_FILE_PATH_INVALID';
+    throw new Error(`${code}: ${fieldName || 'files'} 必须是数组`);
+  }
+  if (files.length === 0) {
+    if (requiredCode) {
+      throw new Error(`${requiredCode}: ${fieldName || 'files'} 必须是非空数组`);
+    }
+    return [];
+  }
+  const normalized = [];
+  for (const value of files) {
+    if (typeof value !== 'string') {
+      throw new Error(`${invalidCode || 'REPOSITORY_FILE_PATH_INVALID'}: ${fieldName || 'files'} 只能包含字符串路径`);
+    }
+    const raw = value.trim().replace(/\\/g, '/');
+    const segments = raw.split('/');
+    if (!raw
+      || path.isAbsolute(raw)
+      || /^[A-Za-z]:/.test(raw)
+      || segments.includes('..')
+      || segments.includes('.')
+      || raw.startsWith('/')) {
+      throw new Error(`${invalidCode || 'REPOSITORY_FILE_PATH_INVALID'}: 非法仓库相对路径 "${raw || String(value)}"`);
+    }
+    normalized.push(raw);
+  }
+  return [...new Set(normalized)].sort();
+}
+
+function normalizeStrictCheckResult(details, result) {
+  const input = details?.check_results;
+  if (!input || typeof input !== 'object' || Array.isArray(input)) {
+    fail('CHECK_RESULT_REQUIRED: strict check_result 缺少 details.check_results');
+  }
+  const total = strictStructuredInteger(
+    input.total,
+    'CHECK_RESULT_TOTAL_REQUIRED',
+    'check_results.total',
+    1,
+  );
+  const errors = strictStructuredInteger(
+    input.errors,
+    'CHECK_RESULT_ERRORS_REQUIRED',
+    'check_results.errors',
+  );
+  if (errors > total) {
+    fail('CHECK_RESULT_ERRORS_INVALID: check_results.errors 不能大于 check_results.total');
+  }
+  const warnings = strictStructuredInteger(
+    input.warnings,
+    'CHECK_RESULT_WARNINGS_REQUIRED',
+    'check_results.warnings',
+  );
+  const suggestions = strictStructuredInteger(
+    input.suggestions,
+    'CHECK_RESULT_SUGGESTIONS_REQUIRED',
+    'check_results.suggestions',
+  );
+  const fixedBeforeApply = strictStructuredInteger(
+    input.fixed_before_apply,
+    'CHECK_RESULT_FIXED_REQUIRED',
+    'check_results.fixed_before_apply',
+  );
+  if (fixedBeforeApply > total) {
+    fail('CHECK_RESULT_FIXED_INVALID: fixed_before_apply 不能大于 check_results.total');
+  }
+  const categoryNames = [
+    'completeness',
+    'consistency',
+    'executability',
+    'tdd_compliance',
+  ];
+  const categoryInput = input.categories;
+  if (!categoryInput || typeof categoryInput !== 'object' || Array.isArray(categoryInput)) {
+    fail('CHECK_RESULT_CATEGORIES_REQUIRED: strict check_result 缺少 check_results.categories');
+  }
+  const categories = {};
+  let categoryTotalSum = 0;
+  let categoryErrorSum = 0;
+  for (const categoryName of categoryNames) {
+    const category = categoryInput[categoryName];
+    if (!category || typeof category !== 'object' || Array.isArray(category)) {
+      fail(`CHECK_RESULT_CATEGORY_REQUIRED: check_results.categories.${categoryName} 必须是对象`);
+    }
+    const categoryTotal = strictStructuredInteger(
+      category.total,
+      'CHECK_RESULT_CATEGORY_TOTAL_REQUIRED',
+      `check_results.categories.${categoryName}.total`,
+    );
+    const categoryPassed = strictStructuredInteger(
+      category.passed,
+      'CHECK_RESULT_CATEGORY_PASSED_REQUIRED',
+      `check_results.categories.${categoryName}.passed`,
+    );
+    if (categoryPassed > categoryTotal) {
+      fail(`CHECK_RESULT_CATEGORY_INVALID: ${categoryName}.passed 不能大于 total`);
+    }
+    categories[categoryName] = {
+      ...category,
+      passed: categoryPassed,
+      total: categoryTotal,
+    };
+    categoryTotalSum += categoryTotal;
+    categoryErrorSum += categoryTotal - categoryPassed;
+  }
+  if (categoryTotalSum !== total) {
+    fail('CHECK_RESULT_CATEGORY_TOTAL_MISMATCH: 四类 categories.total 合计必须等于 check_results.total');
+  }
+  if (categoryErrorSum !== errors) {
+    fail('CHECK_RESULT_CATEGORY_ERRORS_MISMATCH: 四类未通过数合计必须等于 check_results.errors');
+  }
+  const taskInput = input.task_completion;
+  if (!taskInput || typeof taskInput !== 'object' || Array.isArray(taskInput)) {
+    fail('CHECK_RESULT_TASK_COMPLETION_REQUIRED: strict check_result 缺少 check_results.task_completion');
+  }
+  const taskCompleted = strictStructuredInteger(
+    taskInput.completed,
+    'CHECK_RESULT_TASK_COMPLETED_REQUIRED',
+    'check_results.task_completion.completed',
+  );
+  const taskIncomplete = strictStructuredInteger(
+    taskInput.incomplete,
+    'CHECK_RESULT_TASK_INCOMPLETE_REQUIRED',
+    'check_results.task_completion.incomplete',
+  );
+  const taskTotal = strictStructuredInteger(
+    taskInput.total,
+    'CHECK_RESULT_TASK_TOTAL_REQUIRED',
+    'check_results.task_completion.total',
+  );
+  if (taskCompleted + taskIncomplete !== taskTotal) {
+    fail('CHECK_RESULT_TASK_COUNTS_INVALID: completed + incomplete 必须等于 task_completion.total');
+  }
+  if (typeof taskInput.has_incomplete !== 'boolean'
+      || taskInput.has_incomplete !== (taskIncomplete > 0)) {
+    fail('CHECK_RESULT_TASK_FLAG_INVALID: has_incomplete 必须与 incomplete 是否大于 0 一致');
+  }
+  if (typeof taskInput.checked_for_archive_readiness !== 'boolean') {
+    fail('CHECK_RESULT_ARCHIVE_READINESS_REQUIRED: checked_for_archive_readiness 必须是布尔值');
+  }
+  const normalizedResult = requireStrictString(
+    result,
+    'CHECK_RESULT_STATUS_REQUIRED',
+    'result',
+  );
+  if (!['success', 'partial', 'failure'].includes(normalizedResult)) {
+    fail(`CHECK_RESULT_STATUS_INVALID: 非法 check_result.result "${normalizedResult}"`);
+  }
+  if (taskIncomplete > 0 && normalizedResult === 'success') {
+    fail('CHECK_RESULT_TASK_STATUS_INVALID: 存在未完成任务时 check_result.result 不能是 success');
+  }
+  const warningItems = input.warning_items;
+  if (taskIncomplete > 0 && (
+    !Array.isArray(warningItems)
+    || !warningItems.some(item => item?.category === 'task_completion')
+  )) {
+    fail('CHECK_RESULT_TASK_WARNING_REQUIRED: 存在未完成任务时 warning_items 必须包含 task_completion 明细');
+  }
+  const taskCompletion = {
+    ...taskInput,
+    completed: taskCompleted,
+    incomplete: taskIncomplete,
+    total: taskTotal,
+    has_incomplete: taskInput.has_incomplete,
+    checked_for_archive_readiness: taskInput.checked_for_archive_readiness,
+  };
+  const executionMode = requireStrictString(
+    input.review_execution_mode,
+    'CHECK_REVIEW_EXECUTION_MODE_REQUIRED',
+    'review_execution_mode',
+  );
+  if (!['subagent', 'main-agent-fallback'].includes(executionMode)) {
+    fail(`CHECK_REVIEW_EXECUTION_MODE_INVALID: 非法 review_execution_mode "${executionMode}"`);
+  }
+  const reviewerIndependence = requireStrictString(
+    input.reviewer_independence,
+    'CHECK_REVIEW_INDEPENDENCE_REQUIRED',
+    'reviewer_independence',
+  );
+  if (!['independent-review', 'self-review', 'unknown'].includes(reviewerIndependence)) {
+    fail(`CHECK_REVIEW_INDEPENDENCE_INVALID: 非法 reviewer_independence "${reviewerIndependence}"`);
+  }
+  const reviewSessionId = requireStrictString(
+    input.review_session_id || input.reviewer_session_id,
+    'CHECK_REVIEW_SESSION_REQUIRED',
+    'review_session_id',
+  );
+  const authorSessionId = requireStrictString(
+    input.author_session_id,
+    'CHECK_AUTHOR_SESSION_REQUIRED',
+    'author_session_id',
+  );
+  const parentSessionId = String(input.parent_session_id || '').trim();
+  const fallbackReasonCode = String(input.fallback_reason_code || '').trim();
+  const fallbackReason = String(input.fallback_reason || '').trim();
+
+  if (executionMode === 'subagent') {
+    if (!parentSessionId) {
+      fail('CHECK_PARENT_SESSION_REQUIRED: 子代理评审必须记录 parent_session_id');
+    }
+    if (!isMeaningfulCheckIdentity(input.reviewer_agent_id)
+      || !isMeaningfulCheckIdentity(parentSessionId)
+      || !isMeaningfulCheckIdentity(reviewSessionId)
+      || !isMeaningfulCheckIdentity(authorSessionId)) {
+      fail('CHECK_REVIEW_IDENTITY_INVALID: 子代理评审必须记录真实且非占位的评审者、父会话、评审会话和作者会话身份');
+    }
+    if (reviewerIndependence !== 'independent-review'
+      || reviewSessionId === authorSessionId
+      || fallbackReasonCode
+      || fallbackReason) {
+      fail('CHECK_REVIEW_METADATA_INVALID: 子代理评审必须具有独立评审标记、不同会话、评审者身份且不能带回退原因');
+    }
+  } else {
+    if (!fallbackReasonCode || !fallbackReason) {
+      fail('CHECK_FALLBACK_REASON_REQUIRED: 主 Agent 回退检查必须记录 fallback_reason_code 和 fallback_reason');
+    }
+    if (!CHECK_FALLBACK_REASON_CODES.has(fallbackReasonCode)) {
+      fail(`CHECK_FALLBACK_REASON_INVALID: 非法回退原因 "${fallbackReasonCode}"`);
+    }
+    if (!['self-review', 'unknown'].includes(reviewerIndependence)) {
+      fail('CHECK_REVIEW_METADATA_INVALID: 主 Agent 回退检查只能声明为 self-review 或 unknown');
+    }
+  }
+
+  return {
+    ...details,
+    check_results: {
+      ...input,
+      total,
+      errors,
+      warnings,
+      suggestions,
+      fixed_before_apply: fixedBeforeApply,
+      categories,
+      task_completion: taskCompletion,
+      review_execution_mode: executionMode,
+      reviewer_independence: reviewerIndependence,
+      reviewer_agent_id: executionMode === 'subagent'
+        ? String(input.reviewer_agent_id).trim()
+        : undefined,
+      parent_session_id: parentSessionId || undefined,
+      review_session_id: reviewSessionId,
+      author_session_id: authorSessionId,
+      fallback_reason_code: fallbackReasonCode || undefined,
+      fallback_reason: fallbackReason || undefined,
+    },
+  };
+}
+
+function validateFinalOutputSnapshot(input) {
+  if (!input || typeof input !== 'object' || Array.isArray(input)) {
+    return {
+      ok: false,
+      code: 'FINAL_OUTPUT_SNAPSHOT_REQUIRED',
+      message: 'strict final_output_snapshot 缺少 details.final_output_snapshot',
+    };
+  }
+  const snapshotKind = typeof input.snapshot_kind === 'string' ? input.snapshot_kind.trim() : '';
+  if (!snapshotKind) {
+    return {
+      ok: false,
+      code: 'FINAL_OUTPUT_SNAPSHOT_KIND_REQUIRED',
+      message: 'strict 事件缺少 final_output_snapshot.snapshot_kind',
+    };
+  }
+  if (snapshotKind !== 'final') {
+    return {
+      ok: false,
+      code: 'FINAL_OUTPUT_SNAPSHOT_KIND_INVALID',
+      message: `snapshot_kind 必须是 final，收到 "${snapshotKind}"`,
+    };
+  }
+  const vcsMode = typeof input.vcs_mode === 'string' ? input.vcs_mode.trim() : '';
+  if (!vcsMode) {
+    return {
+      ok: false,
+      code: 'FINAL_OUTPUT_VCS_MODE_REQUIRED',
+      message: 'strict 事件缺少 final_output_snapshot.vcs_mode',
+    };
+  }
+  if (!['readonly', 'no-git'].includes(vcsMode)) {
+    return {
+      ok: false,
+      code: 'FINAL_OUTPUT_VCS_MODE_INVALID',
+      message: `vcs_mode 必须是 readonly 或 no-git，收到 "${vcsMode}"`,
+    };
+  }
+  if (!Array.isArray(input.files)) {
+    return {
+      ok: false,
+      code: 'FINAL_OUTPUT_PATH_INVALID',
+      message: 'final_output_snapshot.files 必须显式提供数组；没有交付文件时请使用空数组并填写 no_output_reason',
+    };
+  }
+  let files;
+  try {
+    files = normalizeRepositoryRelativeFiles(input.files, {
+      invalidCode: 'FINAL_OUTPUT_PATH_INVALID',
+      fieldName: 'final_output_snapshot.files',
+    });
+  } catch (error) {
+    return {
+      ok: false,
+      code: 'FINAL_OUTPUT_PATH_INVALID',
+      message: String(error?.message || error).replace(/^FINAL_OUTPUT_PATH_INVALID:\s*/, ''),
+    };
+  }
+  const noOutputReason = String(input.no_output_reason || '').trim();
+  if (files.length === 0 && !noOutputReason) {
+    return {
+      ok: false,
+      code: 'FINAL_OUTPUT_FILES_OR_REASON_REQUIRED',
+      message: '最终快照必须提供 files，或说明 no_output_reason',
+    };
+  }
+  if (files.length > 0 && noOutputReason) {
+    return {
+      ok: false,
+      code: 'FINAL_OUTPUT_REASON_CONFLICT',
+      message: '有最终交付文件时不能同时填写 no_output_reason',
+    };
+  }
+  const filesChanged = input.files_changed;
+  if (typeof filesChanged !== 'number'
+      || !Number.isInteger(filesChanged)
+      || filesChanged < 0) {
+    return {
+      ok: false,
+      code: 'FINAL_OUTPUT_FILES_CHANGED_INVALID',
+      message: 'final_output_snapshot.files_changed 必须是大于等于 0 的整数',
+    };
+  }
+  if (filesChanged !== files.length) {
+    return {
+      ok: false,
+      code: 'FINAL_OUTPUT_FILE_COUNT_MISMATCH',
+      message: `files_changed=${filesChanged} 与去重后的 files 数量 ${files.length} 不一致`,
+    };
+  }
+  const normalizeLineCount = (fieldName, code) => {
+    if (vcsMode === 'no-git' && (input[fieldName] === undefined || input[fieldName] === null)) {
+      return { ok: true, value: null };
+    }
+    const value = input[fieldName];
+    if (typeof value !== 'number' || !Number.isInteger(value) || value < 0) {
+      return {
+        ok: false,
+        code,
+        message: `final_output_snapshot.${fieldName} 必须是大于等于 0 的整数`,
+      };
+    }
+    return { ok: true, value };
+  };
+  const addedLines = normalizeLineCount('added_lines', 'FINAL_OUTPUT_ADDED_LINES_INVALID');
+  if (!addedLines.ok) return addedLines;
+  const deletedLines = normalizeLineCount('deleted_lines', 'FINAL_OUTPUT_DELETED_LINES_INVALID');
+  if (!deletedLines.ok) return deletedLines;
+  return {
+    ok: true,
+    snapshot: {
+      ...input,
+      snapshot_kind: snapshotKind,
+      vcs_mode: vcsMode,
+      files,
+      files_changed: filesChanged,
+      added_lines: addedLines.value,
+      deleted_lines: deletedLines.value,
+      no_output_reason: files.length === 0 ? noOutputReason : undefined,
+    },
+  };
+}
+
+function normalizeStrictFinalOutputSnapshot(details) {
+  const validation = validateFinalOutputSnapshot(details?.final_output_snapshot);
+  if (!validation.ok) fail(`${validation.code}: ${validation.message}`);
+  return {
+    ...details,
+    final_output_snapshot: validation.snapshot,
+  };
+}
+
 function normalizeStrictTestResult(args, details) {
   const input = details?.test_results;
   if (!input || typeof input !== 'object' || Array.isArray(input)) {
@@ -5979,6 +6532,20 @@ function normalizeStrictTaskUpdate(args, details, dataDir, change) {
       || details?.verification_reason
       || '',
   ).trim();
+  const rawTaskFiles = input && Object.hasOwn(input, 'files') ? input.files : [];
+  let taskFiles;
+  try {
+    taskFiles = normalizeRepositoryRelativeFiles(rawTaskFiles, {
+      invalidCode: 'TASK_FILE_PATH_INVALID',
+      fieldName: 'task_update.files',
+    });
+  } catch (error) {
+    fail(String(error?.message || error));
+  }
+  const noFileChangeReason = String(input?.no_file_change_reason || '').trim();
+  if (taskFiles.length === 0 && !noFileChangeReason) {
+    fail('TASK_FILES_OR_REASON_REQUIRED: strict task_update 必须提供 files，或说明 no_file_change_reason');
+  }
 
   let resolvedTestEventId = testEventId;
   let resolvedTestRunId = testRunId || undefined;
@@ -6031,6 +6598,8 @@ function normalizeStrictTaskUpdate(args, details, dataDir, change) {
           || (verificationNotApplicable ? verificationReason : undefined),
         verification_not_applicable: verificationNotApplicable,
         verification_not_applicable_reason: verificationNotApplicable ? verificationReason : undefined,
+        files: taskFiles,
+        no_file_change_reason: taskFiles.length === 0 ? noFileChangeReason : undefined,
       },
     },
   };
@@ -6624,6 +7193,7 @@ function cmdRecord(args) {
     'quality_gate_result',
     'conformance_review',
     'ai_adoption_review',
+    'final_output_snapshot',
     'survey_result',
     'baseline_record',
     'telemetry_warning',
@@ -6787,6 +7357,12 @@ function cmdRecord(args) {
     strictTaskId = taskUpdate.taskId;
     eventStatus = taskUpdate.status;
     details = taskUpdate.details;
+  } else if (strict && type === 'check_result') {
+    strictRunId = requireStrictString(strictRunId, 'EVENT_RUN_ID_REQUIRED', 'run_id');
+    details = normalizeStrictCheckResult(details, args.result);
+  } else if (strict && type === 'final_output_snapshot') {
+    strictRunId = requireStrictString(strictRunId, 'EVENT_RUN_ID_REQUIRED', 'run_id');
+    details = normalizeStrictFinalOutputSnapshot(details);
   } else if (strict) {
     strictRunId = requireStrictString(strictRunId, 'EVENT_RUN_ID_REQUIRED', 'run_id');
   }
@@ -7521,6 +8097,33 @@ function cmdSemanticObserve(args) {
   return observer;
 }
 
+/**
+ * kb-upload: 知识库上传（文件夹 / zip）
+ * 委托给 skywalk-sdd/kb-upload.cjs 执行
+ */
+function cmdKbUpload(args) {
+  // 将 args 还原为 --key=value 格式，传递给 kb-upload.cjs
+  const passThrough = [];
+  for (const [key, value] of Object.entries(args)) {
+    if (value === true) {
+      passThrough.push(`--${key}`);
+    } else if (value !== undefined && value !== null && value !== false) {
+      passThrough.push(`--${key}=${value}`);
+    }
+  }
+
+  const scriptPath = path.join(__dirname, 'kb-upload.cjs');
+  try {
+    const output = execFileSync(process.execPath, [scriptPath, ...passThrough], {
+      encoding: 'utf8',
+      stdio: 'inherit',
+    });
+    return output;
+  } catch (err) {
+    process.exitCode = 1;
+  }
+}
+
 /**
  * log archive-docs: 真实归档 Simple/Full spec，结束 archive 阶段并生成最终报告
  */
@@ -7716,6 +8319,9 @@ function main() {
     case 'check-task':
       cmdCheckTask(flags);
       break;
+    case 'kb-upload':
+      cmdKbUpload(flags);
+      break;
     default:
       showHelp();
       process.exit(1);
@@ -7734,6 +8340,8 @@ SDD Telemetry CLI - 流程度量采集工具
   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>]
+  node skywalk-sdd/log.cjs kb-upload --folder=<path> [--minimum-level=propose-spec] [--validate-only] [--project=<spec-root>]
+  node skywalk-sdd/log.cjs kb-upload --package=<zip-path> [--project=<spec-root>]
   node skywalk-sdd/log.cjs semantic-identity --delta-state=added
   node skywalk-sdd/log.cjs semantic-identity --delta-state=modified --entity-id=<uuid> --predecessor-version=<uuid>
   node skywalk-sdd/log.cjs semantic-identity --delta-state=unchanged --entity-id=<uuid> --version-id=<uuid>
@@ -7752,6 +8360,7 @@ SDD Telemetry CLI - 流程度量采集工具
   tasks-status 扫描 Full/Simple 模式 tasks.md 勾选状态
   check-task 扫描变更目录 tasks.md 并勾选指定 task_id
   archive-docs 将 Simple/Full spec 变更真实移动到 openspec/changes/archive/，并可结束 archive 阶段生成报告
+  kb-upload 知识库上传（文件夹自动打包 / zip 直传），支持随时入库
   semantic-identity 生成或复用实体/版本 ID（8 位十六进制）；无需网络和中央 ID 服务
   semantic-scan 只读解析并校验当前 Change
   semantic-reconcile 全量对账文件与本地工作态本体实例
@@ -7775,6 +8384,8 @@ SDD Telemetry CLI - 流程度量采集工具
   node skywalk-sdd/log.cjs check-task --project=/my/project --change=user-auth --task-id=TASK-01
   node skywalk-sdd/log.cjs archive-docs --project=/my/project --change=user-auth --reason="变更已完成实施" --event-id=evt_archive
   # archive-docs 最终报告默认生成到 openspec/changes/archive/<日期>-<change>/reports/<change>-report.md；可用 --report-output=<路径> 指定自定义路径
+  node skywalk-sdd/log.cjs kb-upload --folder=openspec/changes/user-auth --minimum-level=propose-spec --project=/my/project
+  node skywalk-sdd/log.cjs kb-upload --package=openspec/changes/archive/2026-07-31-user-auth.zip --project=/my/project
   node skywalk-sdd/log.cjs record --type=worktree_finish --command=apply --project=/my/project --change=user-auth --capability=user-auth --result=success --summary="merge+remove completed"
 
 Apply worktree（主仓库根目录，非 log.cjs 子命令）: