kld-sdd 2.6.16 → 2.6.21

package/skywalk-sdd/reporting/change-report-view-model.cjs

@@ -1,6 +1,13 @@
 'use strict';
 
 const crypto = require('crypto');
+const {
+  localizeIssueStatus,
+  localizeMetricStatus,
+  localizeStageName,
+  ISSUE_STATUS_LABELS,
+  validateCoreMetricResult,
+} = require('./core-metric-definitions.cjs');
 
 /**
  * Shared change-report view model for Markdown / HTML / parity digests.
@@ -27,13 +34,22 @@ function fractionText(verified, total) {
 }
 
 function percentText(value, digits = 2) {
-  return Number.isFinite(Number(value))
+  return value !== null
+    && value !== undefined
+    && value !== ''
+    && Number.isFinite(Number(value))
     ? `${(Number(value) * 100).toFixed(digits)}%`
     : '暂无数据';
 }
 
 function durationText(value) {
-  if (!Number.isFinite(Number(value))) return '暂无数据';
+  if (value === null
+      || value === undefined
+      || value === ''
+      || !Number.isFinite(Number(value))
+      || Number(value) < 0) {
+    return '暂无数据';
+  }
   const totalSeconds = Math.round(Number(value) / 1000);
   const hours = Math.floor(totalSeconds / 3600);
   const minutes = Math.floor((totalSeconds % 3600) / 60);
@@ -51,6 +67,119 @@ function localTimeText(value) {
     : parsed.toLocaleTimeString('zh-CN', { hour: '2-digit', minute: '2-digit' });
 }
 
+function resultText(value) {
+  return ({
+    success: '成功',
+    partial: '部分通过',
+    failure: '失败',
+    failed: '失败',
+    error: '错误',
+    blocked: '已阻断',
+    unknown: '未知',
+  }[value] || String(value || '未知'));
+}
+
+function reviewIndependenceText(value) {
+  return ({
+    'independent-review': '独立复核',
+    'self-review': '自查',
+    unknown: '无法确认',
+  }[value] || '未记录');
+}
+
+const PROCESS_NOTE_KIND_LABELS = Object.freeze({
+  fix: '修复记录',
+  clarification: '需求澄清',
+  decision: '决策记录',
+  'api-error': '接口错误',
+  'model-switch': '模型切换',
+  user_decision: '用户决策',
+  scope_change: '范围调整',
+  api_error: '接口错误',
+  model_error: '模型错误',
+  recovery: '恢复处理',
+  test_exception: '测试例外',
+  note: '过程说明',
+});
+
+const RECONCILIATION_STATUS_LABELS = Object.freeze({
+  consistent: '两个口径一致',
+  unavailable: '暂无可对账数据',
+  'task-evidence-missing': '缺少任务过程文件记录',
+  'final-snapshot-missing': '缺少最终输出快照',
+  'count-mismatch': '两个口径的文件数量不同',
+  'list-mismatch': '两个口径的文件清单不同',
+});
+
+const FILE_SOURCE_LABELS = Object.freeze({
+  'task_update.files': '任务完成事件中的文件清单（task_update.files）',
+  'final_output_snapshot.files': '最终输出快照中的文件清单（final_output_snapshot.files）',
+  'ai_adoption_review.ai_diff.files': '旧版最终差异记录（ai_adoption_review.ai_diff.files）',
+  'test_results.assertions': '测试断言提到的文件（test_results.assertions）',
+  'dual-source': '任务事件与最终输出快照双来源（dual-source）',
+});
+
+function processNoteKindText(value) {
+  return PROCESS_NOTE_KIND_LABELS[value] || String(value || '过程说明');
+}
+
+function fileSourceText(value) {
+  return FILE_SOURCE_LABELS[value] || String(value || '未记录');
+}
+
+function metricStateForDetail(
+  detail,
+  fallbackState,
+  fallbackCode = null,
+  provisionalLabel = '临时结果',
+) {
+  const status = detail?.trust?.status || fallbackCode;
+  const label = ({
+    trusted: '可信',
+    verified: '已独立验证',
+    provisional: provisionalLabel,
+    available: '可计算',
+    inconsistent: '计算不一致',
+    missing: '需补证',
+    unavailable: '需补证',
+    'pending-upstream': '需补证',
+  }[status] || fallbackState);
+  return { label, code: status || null };
+}
+
+function translateProcessNotes(value) {
+  if (typeof value === 'string') {
+    return value.replace(/本轮不种桥/g, '本次未建立外部需求与本地能力的关联');
+  }
+  if (Array.isArray(value)) return value.map(translateProcessNotes);
+  if (value && typeof value === 'object') {
+    return Object.fromEntries(
+      Object.entries(value).map(([key, item]) => [key, translateProcessNotes(item)]),
+    );
+  }
+  return value;
+}
+
+function localizeProcessNotes(value) {
+  const translated = translateProcessNotes(value);
+  if (!translated || typeof translated !== 'object') return translated;
+  return {
+    ...translated,
+    by_kind: translated.by_kind && typeof translated.by_kind === 'object'
+      ? Object.fromEntries(
+        Object.entries(translated.by_kind).map(([kind, count]) => [processNoteKindText(kind), count]),
+      )
+      : translated.by_kind,
+    notes: Array.isArray(translated.notes)
+      ? translated.notes.map(note => ({
+        ...note,
+        kind_code: note.kind || null,
+        kind: processNoteKindText(note.kind),
+      }))
+      : translated.notes,
+  };
+}
+
 function buildSemanticDigestInput(report, sections) {
   const audit = report.task_evidence_audit || {};
   const tdd = report.tdd_pair_audit || {};
@@ -99,7 +228,7 @@ function buildSemanticDigestInput(report, sections) {
       diff_source: changed.diff_source ?? null,
       reconciliation_status: changed.reconciliation_status ?? null,
     },
-    attribution: report.attribution_audit || null,
+    metric_details: report.metric_details || null,
     artifact_sizes: Object.fromEntries(
       Object.entries(artifacts).map(([name, item]) => [name, item?.size_bytes ?? null]),
     ),
@@ -122,11 +251,20 @@ function buildChangeReportViewModel(report = {}) {
   const process = metrics.process || {};
   const telemetry = metrics.telemetry_health || {};
   const minSet = report.minimum_metric_set || {};
-  const openIssueCount = (report.evidence_alerts?.open || []).length;
-  const totalDurationMs = efficiency.total_duration_ms
+  const localizedIssues = (evidence.issues || []).map(issue => ({
+    ...issue,
+    status_label: localizeIssueStatus(
+      Object.hasOwn(ISSUE_STATUS_LABELS, issue.disposition)
+        ? issue.disposition
+        : issue.status,
+    ),
+  }));
+  const openIssueCount = localizedIssues.filter(issue => issue.status === 'open').length;
+  const totalDurationMs = efficiency.total_stage_duration_ms
+    ?? efficiency.measurement_stage_duration_ms
     ?? efficiency.effective_stage_duration_including_rework_ms
-    ?? efficiency.e1_lead_time_ms
     ?? null;
+  const endpointElapsedMs = efficiency.e1_lead_time_ms ?? null;
   const e1 = efficiency.e1_scenario_delivery_efficiency_ms ?? null;
   const e2 = efficiency.e2_coding_time_ratio_including_rework
     ?? efficiency.e2_coding_time_ratio
@@ -134,54 +272,99 @@ function buildChangeReportViewModel(report = {}) {
   const e3 = efficiency.e3_spec_time_ratio_including_rework
     ?? efficiency.e3_spec_time_ratio
     ?? null;
+  const e1State = metricStateForDetail(
+    report.metric_details?.e1,
+    (
+      minSet.evidence_status?.e1 === 'trusted'
+      || minSet.trusted_metrics?.includes?.('e1')
+      || minSet.trusted?.includes?.('e1')
+    ) ? '可信' : '需补证',
+    minSet.evidence_status?.e1 || null,
+  );
+  const q3State = metricStateForDetail(
+    report.metric_details?.q3,
+    quality.q3_score_status === 'verified' ? '已独立验证' : '尚未独立验证',
+    quality.q3_score_status || null,
+    '尚未独立验证',
+  );
+  const p4State = metricStateForDetail(
+    report.metric_details?.p4,
+    Number.isFinite(process.p4_quality_gate_enforcement_rate) ? '可计算' : '需补证',
+    Number.isFinite(process.p4_quality_gate_enforcement_rate) ? 'available' : 'missing',
+  );
+  const pRState = metricStateForDetail(
+    report.metric_details?.p_r,
+    process.rework_summary ? '可计算' : '需补证',
+    process.rework_summary ? 'available' : 'missing',
+  );
+  const pHState = metricStateForDetail(
+    report.metric_details?.p_h,
+    telemetry.p_h_telemetry_health_score == null ? '需补证' : '可计算',
+    telemetry.p_h_telemetry_health_score == null ? 'missing' : 'available',
+  );
   const metricCards = [
     {
-      name: '每个场景平均用时',
+      name: '场景交付效率（每个场景平均用时）',
       code: 'E1',
-      value: Number.isFinite(e1) ? `${durationText(e1)} / 场景` : '暂无数据',
-      state: (
-        minSet.evidence_status?.e1 === 'trusted'
-        || minSet.trusted_metrics?.includes?.('e1')
-        || minSet.trusted?.includes?.('e1')
-      ) ? '可信' : '需补证',
+      value: validateCoreMetricResult('e1', e1).valid
+        ? `${durationText(e1)} / 场景`
+        : '暂无数据',
+      state: e1State.label,
+      state_code: e1State.code,
       explanation: '七个标准阶段总耗时（含返工）÷ 验收场景数。',
       source: `公式：标准阶段总耗时 ÷ 场景数。场景数：${efficiency.scenario_count ?? '未知'}；当前值：${e1 ?? '不可计算'} ms。`,
+      detail: report.metric_details?.e1 || null,
     },
     {
-      name: '规约检查得分',
+      name: '规约质量评分（规约检查得分）',
       code: 'Q3',
-      value: quality.q3_spec_quality_score == null ? '暂无数据' : `${quality.q3_spec_quality_score} / 100`,
-      state: quality.q3_score_status === 'verified' ? '已验证' : '临时',
+      value: validateCoreMetricResult('q3', quality.q3_spec_quality_score).valid
+        ? `${quality.q3_spec_quality_score} / 100`
+        : '暂无数据',
+      state: q3State.label,
+      state_code: q3State.code,
       explanation: '最新规约检查结果；独立复核后才标记为已验证。',
-      source: `评审独立性：${quality.q3_reviewer_independence || '未知'}；证据状态：${quality.q3_score_status || '未知'}。`,
+      source: `评审独立性：${reviewIndependenceText(quality.q3_reviewer_independence)}；证据状态：${localizeMetricStatus(quality.q3_score_status)}。`,
+      detail: report.metric_details?.q3 || null,
     },
     {
-      name: '编码前是否先检查',
+      name: '质量门禁执行率（编码前是否先检查）',
       code: 'P4',
-      value: percentText(process.p4_quality_gate_enforcement_rate),
-      state: Number.isFinite(process.p4_quality_gate_enforcement_rate) ? '可计算' : '需补证',
+      value: validateCoreMetricResult('p4', process.p4_quality_gate_enforcement_rate).valid
+        ? percentText(process.p4_quality_gate_enforcement_rate)
+        : '暂无数据',
+      state: p4State.label,
+      state_code: p4State.code,
       explanation: '首次进入编码前，是否存在已配对且成功或部分通过的检查。',
       source: '只接受能与 check 开始事件配对、且发生在首次 apply 之前的成功或部分通过结果。',
+      detail: report.metric_details?.p4 || null,
     },
     {
-      name: '阶段重复次数',
+      name: '阶段重复执行（阶段重复次数）',
       code: 'P-R',
-      value: process.rework_summary?.total_rework_attempts == null
-        ? '暂无数据'
-        : `${process.rework_summary.total_rework_attempts} 次`,
-      state: process.rework_summary ? '可计算' : '需补证',
+      value: validateCoreMetricResult(
+        'p_r',
+        process.rework_summary?.total_rework_attempts,
+      ).valid
+        ? `${process.rework_summary.total_rework_attempts} 次`
+        : '暂无数据',
+      state: pRState.label,
+      state_code: pRState.code,
       explanation: '七个标准阶段中，首次执行之后的重复尝试次数。',
       source: '辅助 test / explore 阶段不计入标准阶段重复总数。',
+      detail: report.metric_details?.p_r || null,
     },
     {
-      name: '执行记录是否完整',
+      name: '数据质量分（执行记录是否完整）',
       code: 'P-H',
-      value: telemetry.p_h_telemetry_health_score == null
-        ? '暂无数据'
-        : `${telemetry.p_h_telemetry_health_score} / 100`,
-      state: telemetry.p_h_telemetry_health_score == null ? '需补证' : '可计算',
+      value: validateCoreMetricResult('p_h', telemetry.p_h_telemetry_health_score).valid
+        ? `${telemetry.p_h_telemetry_health_score} / 100`
+        : '暂无数据',
+      state: pHState.label,
+      state_code: pHState.code,
       explanation: '标准阶段的身份、开始结束配对和数据质量综合评分。',
       source: '沿用既有权重，但只以 propose、spec、design、task、check、apply、archive 七阶段为计算范围。',
+      detail: report.metric_details?.p_h || null,
     },
   ];
 
@@ -242,7 +425,8 @@ function buildChangeReportViewModel(report = {}) {
       },
       metric_cards: metricCards,
       metric_rows: [
-        { label: '七阶段总耗时', value: durationText(totalDurationMs) },
+        { label: '标准阶段有效耗时（含返工）', value: durationText(totalDurationMs) },
+        { label: '端到端经过时间（含阶段间空隙）', value: durationText(endpointElapsedMs) },
         { label: '每个场景平均用时', code: 'E1', value: metricCards[0].value },
         { label: '编码时间占比', code: 'E2', value: percentText(e2) },
         { label: '规划与规约时间占比', code: 'E3', value: percentText(e3) },
@@ -250,12 +434,12 @@ function buildChangeReportViewModel(report = {}) {
       ],
       stages: (report.stage_timeline?.nodes || []).map((node) => ({
         ...node,
-        display_stage: node.stage || node.command || '未知阶段',
+        display_stage: localizeStageName(node.stage || node.command),
         display_round: node.round || 1,
         display_start: localTimeText(node.start_ts),
         display_end: localTimeText(node.end_ts),
         display_duration: durationText(node.duration_ms),
-        display_result: node.result || '未知',
+        display_result: resultText(node.result),
       })),
       tdd_pairs: {
         required: tdd.required ?? null,
@@ -269,11 +453,30 @@ function buildChangeReportViewModel(report = {}) {
       summary: evidence.note
         || `${evidence.category_count || 0} 类问题，${evidence.occurrence_count || 0} 次规则命中`,
       categories: evidence.categories || [],
-      issues: evidence.issues || [],
+      collection_method: '系统先读取规则检查结果，再核对任务状态、测试结果和阶段事件，把同一问题的出现、处置和解决记录合并后展示。',
+      functional_result: {
+        summary: summary.tests?.status === 'passed'
+          ? `最终功能测试通过：${summary.tests.passed}/${summary.tests.total}。`
+          : '最终功能测试没有形成可确认的全通过结果。',
+        explanation: '功能测试回答“功能是否正确”，不直接证明任务、测试和事件之间的记录是否完整。',
+      },
+      traceability_result: {
+        summary: openIssueCount === 0
+          ? '证据链没有待处理问题。'
+          : `证据链仍有 ${openIssueCount} 个待处理问题。`,
+        explanation: openIssueCount === 0
+          ? '历史问题仍按“已解决 / 已接受 / 不重要”保留。'
+          : '功能测试与 Check 可以通过，但记录和关联仍可能有缺口；这不等同于功能失败。',
+      },
+      issues: localizedIssues,
       open_alerts: report.evidence_alerts?.open || [],
       task_evidence_audit: audit,
       apply_findings: report.apply_evidence_audit?.findings || [],
-      warning_dispositions: report.warning_dispositions || [],
+      warning_dispositions: (report.warning_dispositions || []).map(item => ({
+        ...item,
+        disposition_label: localizeIssueStatus(item.disposition),
+      })),
+      process_notes: localizeProcessNotes(report.process_notes || null),
     },
     'artifacts-trace': {
       id: 'artifacts-trace',
@@ -286,10 +489,43 @@ function buildChangeReportViewModel(report = {}) {
         deleted_lines: changed.deleted_lines ?? null,
         diff_source: changed.diff_source || null,
         reconciliation_status: changed.reconciliation_status ?? null,
+        reconciliation_status_label: RECONCILIATION_STATUS_LABELS[
+          changed.reconciliation_status
+        ] || String(changed.reconciliation_status || '未记录'),
         reconciliation_note: changed.reconciliation_note || null,
         final_output_files: changed.final_output_files || changed.files || null,
+        task_event_files: changed.task_event_files || null,
         only_in_task_events: changed.only_in_task_events || [],
         only_in_final_output: changed.only_in_final_output || [],
+        task_scope: {
+          label: '任务过程中涉及的文件',
+          explanation: '汇总各条任务完成事件中记录的文件，回答“任务过程中动过哪些文件”。同一文件只计一次。',
+          count: changed.task_event_files_changed ?? null,
+          files: changed.task_event_files || null,
+          source: fileSourceText(changed.task_event_source || 'task_update.files'),
+          task_ids: changed.task_event_task_ids || [],
+          event_ids: changed.task_event_ids || [],
+          latest_at: changed.task_event_latest_at || null,
+          no_file_change_reasons: changed.no_file_change_reasons || [],
+        },
+        final_scope: {
+          label: '最终实际交付的文件',
+          explanation: '读取最后一次输出快照，回答“归档时最终实际交付了哪些文件”。它不与任务过程口径混为一谈。',
+          count: changed.final_output_files_changed ?? null,
+          files: changed.final_output_files || changed.files || null,
+          source: fileSourceText(
+            changed.final_output_source || changed.diff_source || null,
+          ),
+          event_id: changed.final_output_event_id || null,
+          captured_at: changed.final_output_captured_at || null,
+          no_output_reason: changed.final_output_no_output_reason || null,
+          vcs_mode: changed.final_output_vcs_mode || null,
+          line_statistics_explanation: changed.final_output_vcs_mode === 'no-git'
+            ? '当前环境没有 Git 差异记录，因此无法统计新增和删除行数；文件清单仍来自最终输出快照。'
+            : ((changed.added_lines == null || changed.deleted_lines == null)
+              ? '最终输出快照没有完整的行数差异，因此新增和删除行数不可用。'
+              : '新增和删除行数来自最终输出快照中的 Git 差异统计。'),
+        },
       },
       artifacts: Object.entries(artifacts).map(([name, item]) => ({
         name,
@@ -300,13 +536,6 @@ function buildChangeReportViewModel(report = {}) {
         sha256: item?.sha256 ?? null,
         integrity_note: item?.integrity_note || null,
       })),
-      attribution: report.attribution_audit || null,
-      attribution_summary: {
-        linked_source_event_count: report.attribution_audit?.linked_source_event_count ?? 0,
-        active_link_count: report.attribution_audit?.active_links?.length ?? 0,
-        unassigned_candidate_count: report.attribution_audit?.unassigned_candidate_event_ids?.length ?? 0,
-        rejected_collision_count: report.attribution_audit?.rejected_direct_collision_event_ids?.length ?? 0,
-      },
     },
   };
 
@@ -319,7 +548,7 @@ function buildChangeReportViewModel(report = {}) {
     minimum_metric_set: report.minimum_metric_set || null,
     scheme_compliance: report.scheme_compliance || null,
     known_risks: report.known_risks || null,
-    process_notes: report.process_notes || null,
+    process_notes: localizeProcessNotes(report.process_notes || null),
     telemetry_warnings: report.telemetry_warnings || null,
     archive_result: report.archive_result || null,
     report_scope: report.report_scope || null,

package/skywalk-sdd/reporting/core-metric-definitions.cjs

@@ -0,0 +1,192 @@
+'use strict';
+
+/**
+ * 核心指标的单一文字口径。
+ * JSON 事实模型、Markdown 与 HTML 必须复用这里的定义，避免同一指标出现多套解释。
+ */
+const CORE_METRIC_DEFINITIONS = Object.freeze({
+  e1: Object.freeze({
+    code: 'E1',
+    name: '场景交付效率',
+    english_name: 'Scenario Delivery Efficiency (SDE)',
+    definition: '每交付一个验收场景所需的平均有效耗时。',
+    purpose: '衡量在包含正常返工的情况下，交付一个可验证业务场景平均需要投入多少阶段执行时间。',
+    formula: '场景交付效率 = 标准阶段总耗时（含返工） ÷ 验收场景总数',
+    source_description: '场景数来自 spec.md 中“##### 场景”标题；耗时来自 skywalk-sdd 记录的标准阶段开始和结束事件。',
+    scheme_reference: '《3.3.4.2 SDD赋能提效评估与追踪方案》[E1]',
+    scheme_notes: [
+      '总耗时等于各标准阶段最终执行耗时加返工执行耗时，不含阶段之间的等待空隙。',
+      '标准阶段是 propose、spec、design、task、check、apply、archive；test 和 explore 只作辅助证据，不进入 E1。',
+      '验收场景数与阶段执行记录数是两种不同数据，不能互相替代。',
+    ],
+  }),
+  q3: Object.freeze({
+    code: 'Q3',
+    name: '规约质量评分',
+    english_name: 'Spec Quality Score (SQS)',
+    definition: 'Check 阶段检查项的通过率，反映 spec、design、task 文档质量。',
+    purpose: '直接衡量规约文档质量，并与只判断“是否先做了 Check”的 P4 区分。',
+    formula: '规约质量评分 = (检查项总数 - 错误数) ÷ 检查项总数 × 100',
+    source_description: '来自 skywalk-sdd 在 Check 阶段记录的检查项总数、错误数、分类明细和评审执行信息。',
+    scheme_reference: '《3.3.4.2 SDD赋能提效评估与追踪方案》[Q3]',
+    scheme_notes: [
+      '警告和建议单独展示，当前不进入扣分公式。',
+      '只有真实独立子代理、新旧会话不同且记录了评审者身份时，结果才标记为“已独立验证”。',
+      '完整性、一致性、可执行性等分类用于下钻说明，不改变总分公式。',
+    ],
+  }),
+  p4: Object.freeze({
+    code: 'P4',
+    name: '质量门禁执行率',
+    english_name: 'Quality Gate Enforcement Rate',
+    definition: '首次 Apply 之前是否执行了有效 Check。',
+    purpose: '回答“实现前有没有先做质量检查”，不评价检查内容本身的质量。',
+    formula: '首次 Apply 前存在已配对且结果为成功或部分通过的 Check = 1（100%）；否则 = 0（0%）',
+    source_description: '来自 skywalk-sdd 的 Check 开始/结束事件、Check 结果和首次 Apply 开始时间的时序比较。',
+    scheme_reference: '《3.3.4.2 SDD赋能提效评估与追踪方案》[P4]',
+    scheme_notes: [
+      '单次变更只有 100% 或 0% 两种结果；周期报告才对多次变更求执行率。',
+      'P4 衡量“有没有做 Check”，Q3 衡量“Check 结果如何”。',
+    ],
+  }),
+  p_r: Object.freeze({
+    code: 'P-R',
+    name: '阶段重复执行',
+    english_name: 'Stage Rework',
+    definition: '同一标准阶段被执行多次时，除第一次执行外的重复尝试次数及原因。',
+    purpose: '说明哪些阶段发生了重复执行、重复了几次，以及系统根据事件推导出的原因。',
+    formula: '单次变更重复次数 = Σ max(阶段执行次数 - 1, 0)',
+    source_description: '来自 skywalk-sdd 对各标准阶段开始和结束事件的配对、排序和重复轮次识别。',
+    scheme_reference: '《3.3.4.2 SDD赋能提效评估与追踪方案》[P-R]',
+    scheme_notes: [
+      '单次报告展示实际重复次数；周期报告中的平均返工次数是另一种统计口径。',
+      '原因由事件状态、Git 记录或遥测活动自动推导，不要求开发者手工标注。',
+    ],
+  }),
+  p_h: Object.freeze({
+    code: 'P-H',
+    name: '数据质量分',
+    english_name: 'Telemetry Health Score',
+    definition: '标准阶段遥测数据完整性的综合评分（0-100%）。',
+    purpose: '判断用于计算核心指标的数据链是否完整、可信，避免把采集缺口误当成功能问题。',
+    formula: '数据质量分 = (1 - 加权问题值 ÷ 标准阶段事件总数) × 100',
+    source_description: '由 skywalk-sdd 诊断标准阶段事件后，按问题数量和内置影响权重自动计算。',
+    scheme_reference: '《3.3.4.2 SDD赋能提效评估与追踪方案》[P-H]',
+    scheme_notes: [
+      '只使用 propose、spec、design、task、check、apply、archive 七个标准阶段。',
+      '未闭环、孤儿事件等问题按其对指标计算的影响程度加权；权重是项目经验值，不是行业标准。',
+    ],
+  }),
+});
+
+const CORE_METRIC_RESULT_RULES = Object.freeze({
+  e1: Object.freeze({
+    description: '大于等于 0 的有限数值',
+    validate: value => value >= 0,
+  }),
+  q3: Object.freeze({
+    description: '0 到 100 之间的分数',
+    validate: value => value >= 0 && value <= 100,
+  }),
+  p4: Object.freeze({
+    description: '0 或 1',
+    validate: value => value === 0 || value === 1,
+  }),
+  p_r: Object.freeze({
+    description: '大于等于 0 的整数',
+    validate: value => Number.isInteger(value) && value >= 0,
+  }),
+  p_h: Object.freeze({
+    description: '0 到 100 之间的分数',
+    validate: value => value >= 0 && value <= 100,
+  }),
+});
+
+function validateCoreMetricResult(metricKey, value) {
+  const hasNumber = (typeof value === 'number' && Number.isFinite(value))
+    || (typeof value === 'string' && value.trim() && Number.isFinite(Number(value)));
+  if (!hasNumber) {
+    return {
+      valid: false,
+      status: 'missing',
+      numeric_value: null,
+      explanation: '报告结果缺失或不是有效数字。',
+    };
+  }
+  const numericValue = Number(value);
+  const rule = CORE_METRIC_RESULT_RULES[metricKey];
+  if (!rule || rule.validate(numericValue)) {
+    return {
+      valid: true,
+      status: 'valid',
+      numeric_value: numericValue,
+      explanation: null,
+    };
+  }
+  return {
+    valid: false,
+    status: 'invalid',
+    numeric_value: numericValue,
+    explanation: `报告结果 ${value} 不符合“${rule.description}”的取值要求。`,
+  };
+}
+
+const METRIC_STATUS_LABELS = Object.freeze({
+  trusted: '可信',
+  verified: '已独立验证',
+  provisional: '已有计算结果，尚未独立验证',
+  missing: '当前缺少数据',
+  unavailable: '当前无法计算',
+  available: '可以计算',
+  inconsistent: '计算明细与结果不一致',
+  'pending-upstream': '等待上游数据',
+});
+
+const STAGE_LABELS = Object.freeze({
+  propose: '提出变更',
+  spec: '编写规约',
+  design: '设计方案',
+  task: '拆分任务',
+  check: '规约检查',
+  apply: '实施变更',
+  archive: '归档',
+  test: '测试（辅助阶段）',
+  explore: '探索（辅助阶段）',
+  'pre-archive': '归档前复检',
+});
+
+const ISSUE_STATUS_LABELS = Object.freeze({
+  open: '待处理',
+  resolved: '已解决',
+  fixed: '已解决',
+  accepted: '已接受',
+  waived: '已豁免',
+  informational: '仅供参考',
+  ignored: '不重要，已标记',
+  needs_input: '等待补充信息',
+  'not-applicable': '不适用',
+});
+
+function localizeMetricStatus(value) {
+  return METRIC_STATUS_LABELS[value] || String(value || '未记录');
+}
+
+function localizeStageName(value) {
+  return STAGE_LABELS[value] || String(value || '未记录阶段');
+}
+
+function localizeIssueStatus(value) {
+  return ISSUE_STATUS_LABELS[value] || String(value || '未记录状态');
+}
+
+module.exports = {
+  CORE_METRIC_DEFINITIONS,
+  CORE_METRIC_RESULT_RULES,
+  METRIC_STATUS_LABELS,
+  STAGE_LABELS,
+  ISSUE_STATUS_LABELS,
+  localizeMetricStatus,
+  localizeStageName,
+  localizeIssueStatus,
+  validateCoreMetricResult,
+};

package/skywalk-sdd/spec-root.cjs

@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * spec-root.cjs — 输出 SDD spec 包裹包的绝对路径。
+ *
+ * 设计目标：替代 SKILL 模板中脆弱的 $(cat .sdd-spec-root) 模式。
+ *
+ * 用法:
+ *   node sdd-sdd-specs/skywalk-sdd/spec-root.cjs
+ *   # 输出: C:\Users\zcc\Desktop\sdd\sdd-sdd-specs
+ *
+ *   SPEC=$(node sdd-sdd-specs/skywalk-sdd/spec-root.cjs)
+ *   node "$SPEC/skywalk-sdd/log.cjs" start --command=propose ...
+ *
+ * 核心特性:
+ *   - 基于 __dirname（脚本自身位置）向上遍历查找 .sdd-spec-root
+ *   - 不依赖 CWD，从任意子目录运行均可正确解析
+ *   - 兼容 Windows PowerShell / macOS / Linux
+ *   - 复用 lib/shared.cjs 的 resolveSpecRootFast（统一逻辑）
+ */
+
+const { resolveSpecRootFast } = require('./lib/shared.cjs');
+
+try {
+  const specRoot = resolveSpecRootFast(__dirname);
+  console.log(specRoot);
+} catch (e) {
+  console.error(`⚠️  ${e.message}`);
+  process.exit(1);
+}