kld-sdd 2.6.14 → 2.6.16

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

@@ -0,0 +1,340 @@
+'use strict';
+
+const crypto = require('crypto');
+
+/**
+ * Shared change-report view model for Markdown / HTML / parity digests.
+ * Four desktop tabs: 概览 / 指标与阶段 / 问题与证据 / 产物与追溯
+ */
+
+const SECTION_ORDER = [
+  'overview',
+  'metrics-stages',
+  'issues-evidence',
+  'artifacts-trace',
+];
+
+const SECTION_TITLES = {
+  overview: '概览',
+  'metrics-stages': '指标与阶段',
+  'issues-evidence': '问题与证据',
+  'artifacts-trace': '产物与追溯',
+};
+
+function fractionText(verified, total) {
+  if (verified == null || total == null) return '暂无数据';
+  return `${verified}/${total}`;
+}
+
+function percentText(value, digits = 2) {
+  return Number.isFinite(Number(value))
+    ? `${(Number(value) * 100).toFixed(digits)}%`
+    : '暂无数据';
+}
+
+function durationText(value) {
+  if (!Number.isFinite(Number(value))) return '暂无数据';
+  const totalSeconds = Math.round(Number(value) / 1000);
+  const hours = Math.floor(totalSeconds / 3600);
+  const minutes = Math.floor((totalSeconds % 3600) / 60);
+  const seconds = totalSeconds % 60;
+  return [hours ? `${hours}小时` : '', minutes ? `${minutes}分` : '', `${seconds}秒`]
+    .filter(Boolean)
+    .join('');
+}
+
+function localTimeText(value) {
+  if (!value) return '—';
+  const parsed = new Date(value);
+  return Number.isNaN(parsed.getTime())
+    ? '—'
+    : parsed.toLocaleTimeString('zh-CN', { hour: '2-digit', minute: '2-digit' });
+}
+
+function buildSemanticDigestInput(report, sections) {
+  const audit = report.task_evidence_audit || {};
+  const tdd = report.tdd_pair_audit || {};
+  const changed = report.changed_files || {};
+  const evidence = report.change_summary?.evidence || {};
+  const artifacts = report.artifacts?.files || {};
+  return {
+    schema_version: report.schema_version || null,
+    metrics_contract: report.metrics_contract || null,
+    change: report.change || null,
+    section_ids: SECTION_ORDER.slice(),
+    conclusion_status: report.conclusion?.status || null,
+    tasks: {
+      document: report.change_summary?.tasks?.document || null,
+      direct_test_backlink: audit.direct_test_backlink || null,
+      strict_test_coverage: audit.strict_test_coverage || null,
+      traceability: report.change_summary?.tasks?.traceability || null,
+    },
+    tdd_pairs: {
+      required: tdd.required ?? null,
+      complete: tdd.complete ?? null,
+    },
+    tests: report.change_summary?.tests || null,
+    evidence: {
+      category_count: evidence.category_count ?? null,
+      occurrence_count: evidence.occurrence_count ?? null,
+      issues: (evidence.issues || []).map((issue) => ({
+        issue_id: issue.issue_id,
+        code: issue.code,
+        status: issue.status,
+        verdict: issue.verdict,
+        subject: issue.subject,
+        expected: issue.expected,
+        actual: issue.actual,
+        root_cause: issue.root_cause,
+        remediation: issue.remediation,
+        evidence_event_ids: issue.evidence_event_ids,
+        disposition: issue.disposition,
+      })),
+    },
+    changed_files: {
+      task_event_files_changed: changed.task_event_files_changed ?? null,
+      final_output_files_changed: changed.final_output_files_changed ?? null,
+      added_lines: changed.added_lines ?? null,
+      deleted_lines: changed.deleted_lines ?? null,
+      diff_source: changed.diff_source ?? null,
+      reconciliation_status: changed.reconciliation_status ?? null,
+    },
+    attribution: report.attribution_audit || null,
+    artifact_sizes: Object.fromEntries(
+      Object.entries(artifacts).map(([name, item]) => [name, item?.size_bytes ?? null]),
+    ),
+    section_summaries: Object.fromEntries(
+      SECTION_ORDER.map((id) => [id, sections[id]?.summary || null]),
+    ),
+  };
+}
+
+function buildChangeReportViewModel(report = {}) {
+  const summary = report.change_summary || {};
+  const audit = report.task_evidence_audit || {};
+  const tdd = report.tdd_pair_audit || {};
+  const changed = report.changed_files || {};
+  const evidence = summary.evidence || { categories: [], category_count: 0, occurrence_count: 0 };
+  const artifacts = report.artifacts?.files || {};
+  const metrics = report.metrics || {};
+  const efficiency = metrics.efficiency || {};
+  const quality = metrics.quality || {};
+  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
+    ?? efficiency.effective_stage_duration_including_rework_ms
+    ?? 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
+    ?? null;
+  const e3 = efficiency.e3_spec_time_ratio_including_rework
+    ?? efficiency.e3_spec_time_ratio
+    ?? null;
+  const metricCards = [
+    {
+      name: '每个场景平均用时',
+      code: 'E1',
+      value: Number.isFinite(e1) ? `${durationText(e1)} / 场景` : '暂无数据',
+      state: (
+        minSet.evidence_status?.e1 === 'trusted'
+        || minSet.trusted_metrics?.includes?.('e1')
+        || minSet.trusted?.includes?.('e1')
+      ) ? '可信' : '需补证',
+      explanation: '七个标准阶段总耗时（含返工）÷ 验收场景数。',
+      source: `公式：标准阶段总耗时 ÷ 场景数。场景数：${efficiency.scenario_count ?? '未知'}；当前值：${e1 ?? '不可计算'} ms。`,
+    },
+    {
+      name: '规约检查得分',
+      code: 'Q3',
+      value: quality.q3_spec_quality_score == null ? '暂无数据' : `${quality.q3_spec_quality_score} / 100`,
+      state: quality.q3_score_status === 'verified' ? '已验证' : '临时',
+      explanation: '最新规约检查结果；独立复核后才标记为已验证。',
+      source: `评审独立性：${quality.q3_reviewer_independence || '未知'}；证据状态：${quality.q3_score_status || '未知'}。`,
+    },
+    {
+      name: '编码前是否先检查',
+      code: 'P4',
+      value: percentText(process.p4_quality_gate_enforcement_rate),
+      state: Number.isFinite(process.p4_quality_gate_enforcement_rate) ? '可计算' : '需补证',
+      explanation: '首次进入编码前，是否存在已配对且成功或部分通过的检查。',
+      source: '只接受能与 check 开始事件配对、且发生在首次 apply 之前的成功或部分通过结果。',
+    },
+    {
+      name: '阶段重复次数',
+      code: 'P-R',
+      value: process.rework_summary?.total_rework_attempts == null
+        ? '暂无数据'
+        : `${process.rework_summary.total_rework_attempts} 次`,
+      state: process.rework_summary ? '可计算' : '需补证',
+      explanation: '七个标准阶段中，首次执行之后的重复尝试次数。',
+      source: '辅助 test / explore 阶段不计入标准阶段重复总数。',
+    },
+    {
+      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 ? '需补证' : '可计算',
+      explanation: '标准阶段的身份、开始结束配对和数据质量综合评分。',
+      source: '沿用既有权重，但只以 propose、spec、design、task、check、apply、archive 七阶段为计算范围。',
+    },
+  ];
+
+  const sections = {
+    overview: {
+      id: 'overview',
+      title: SECTION_TITLES.overview,
+      summary: report.conclusion?.text || '当前证据不足，暂不能形成可信结论。',
+      scope_duration: durationText(totalDurationMs),
+      cards: [
+        {
+          key: 'final_tests',
+          label: '最终测试',
+          value: fractionText(summary.tests?.passed, summary.tests?.total),
+        },
+        {
+          key: 'document_tasks',
+          label: '文档任务完成',
+          value: fractionText(summary.tasks?.document?.completed, summary.tasks?.document?.total),
+        },
+        {
+          key: 'direct_backlink',
+          label: '直接测试回链',
+          value: fractionText(
+            audit.direct_test_backlink?.verified,
+            audit.direct_test_backlink?.total,
+          ),
+        },
+        {
+          key: 'strict_coverage',
+          label: '严格测试覆盖',
+          value: fractionText(
+            audit.strict_test_coverage?.verified ?? summary.tasks?.traceability?.verified,
+            audit.strict_test_coverage?.total ?? summary.tasks?.traceability?.total,
+          ),
+        },
+        {
+          key: 'open_issues',
+          label: '开放证据问题',
+          value: String(openIssueCount),
+        },
+      ],
+      metric_cards: metricCards,
+    },
+    'metrics-stages': {
+      id: 'metrics-stages',
+      title: SECTION_TITLES['metrics-stages'],
+      summary: '本次变更效率、质量、过程与阶段执行',
+      metrics: {
+        total_duration_ms: totalDurationMs,
+        e1,
+        e2,
+        e3,
+        q3: quality.q3_spec_quality_score ?? null,
+        p4: process.p4_quality_gate_enforcement_rate ?? null,
+        p_r: process.rework_summary?.total_rework_attempts ?? null,
+        p_h: telemetry.p_h_telemetry_health_score ?? null,
+      },
+      metric_cards: metricCards,
+      metric_rows: [
+        { label: '七阶段总耗时', value: durationText(totalDurationMs) },
+        { label: '每个场景平均用时', code: 'E1', value: metricCards[0].value },
+        { label: '编码时间占比', code: 'E2', value: percentText(e2) },
+        { label: '规划与规约时间占比', code: 'E3', value: percentText(e3) },
+        { label: '阶段重复执行', code: 'P-R', value: metricCards[3].value },
+      ],
+      stages: (report.stage_timeline?.nodes || []).map((node) => ({
+        ...node,
+        display_stage: 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 || '未知',
+      })),
+      tdd_pairs: {
+        required: tdd.required ?? null,
+        complete: tdd.complete ?? null,
+        pairs: tdd.pairs || [],
+      },
+    },
+    'issues-evidence': {
+      id: 'issues-evidence',
+      title: SECTION_TITLES['issues-evidence'],
+      summary: evidence.note
+        || `${evidence.category_count || 0} 类问题，${evidence.occurrence_count || 0} 次规则命中`,
+      categories: evidence.categories || [],
+      issues: evidence.issues || [],
+      open_alerts: report.evidence_alerts?.open || [],
+      task_evidence_audit: audit,
+      apply_findings: report.apply_evidence_audit?.findings || [],
+      warning_dispositions: report.warning_dispositions || [],
+    },
+    'artifacts-trace': {
+      id: 'artifacts-trace',
+      title: SECTION_TITLES['artifacts-trace'],
+      summary: changed.reconciliation_note || '产物与文件对账',
+      changed_files: {
+        task_event_files_changed: changed.task_event_files_changed ?? null,
+        final_output_files_changed: changed.final_output_files_changed ?? null,
+        added_lines: changed.added_lines ?? null,
+        deleted_lines: changed.deleted_lines ?? null,
+        diff_source: changed.diff_source || null,
+        reconciliation_status: changed.reconciliation_status ?? null,
+        reconciliation_note: changed.reconciliation_note || null,
+        final_output_files: changed.final_output_files || changed.files || null,
+        only_in_task_events: changed.only_in_task_events || [],
+        only_in_final_output: changed.only_in_final_output || [],
+      },
+      artifacts: Object.entries(artifacts).map(([name, item]) => ({
+        name,
+        path: item?.path || null,
+        exists: Boolean(item?.exists),
+        size_bytes: item?.size_bytes ?? null,
+        size_display: item?.size_display || null,
+        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,
+      },
+    },
+  };
+
+  return {
+    change: report.change || null,
+    schema_version: report.schema_version || null,
+    metrics_contract: report.metrics_contract || null,
+    generated_at: report.generated_at || null,
+    conclusion: report.conclusion || null,
+    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,
+    telemetry_warnings: report.telemetry_warnings || null,
+    archive_result: report.archive_result || null,
+    report_scope: report.report_scope || null,
+    section_order: SECTION_ORDER.slice(),
+    sections,
+    semantic_digest_input: buildSemanticDigestInput(report, sections),
+    semantic_digest: crypto.createHash('sha256')
+      .update(JSON.stringify(buildSemanticDigestInput(report, sections)))
+      .digest('hex'),
+  };
+}
+
+module.exports = {
+  SECTION_ORDER,
+  SECTION_TITLES,
+  buildChangeReportViewModel,
+  buildSemanticDigestInput,
+};

package/templates/git-hooks/commit-msg

@@ -0,0 +1,46 @@
+#!/bin/sh
+# KLD SDD Commit-MSG Hook
+# 自动查找 commit-msg-sdd-trailer.cjs，兼容单仓库/多仓库/单仓mono布局
+# marker: KLD SDD quality gate
+
+# 从 hook 所在目录推算 git 根目录
+hook_dir="$(cd "$(dirname "$0")" && pwd)"
+git_dir="$(dirname "$hook_dir")"
+git_root="$(dirname "$git_dir")"
+
+script=""
+
+# 方法1: git config sdd.specPath（多仓布局：spec 是独立 clone）
+spec_path=$(git config --local sdd.specPath 2>/dev/null)
+if [ -n "$spec_path" ] && [ -f "$spec_path/skywalk-sdd/git-hooks/commit-msg-sdd-trailer.cjs" ]; then
+  script="$spec_path/skywalk-sdd/git-hooks/commit-msg-sdd-trailer.cjs"
+fi
+
+# 方法2: .sdd-spec-root（单仓 mono 布局：skywalk-sdd 在 spec 包裹包子目录内）
+if [ -z "$script" ] && [ -f "$git_root/.sdd-spec-root" ]; then
+  spec_rel=$(cat "$git_root/.sdd-spec-root" | head -1 | tr -d '[:space:]')
+  if [ -n "$spec_rel" ] && [ -f "$git_root/$spec_rel/skywalk-sdd/git-hooks/commit-msg-sdd-trailer.cjs" ]; then
+    script="$git_root/$spec_rel/skywalk-sdd/git-hooks/commit-msg-sdd-trailer.cjs"
+  fi
+fi
+
+# 方法3: 从 git 根向上搜索 skywalk-sdd/git-hooks（spec 仓本身或父级）
+if [ -z "$script" ]; then
+  search_dir="$git_root"
+  while [ "$search_dir" != "/" ] && [ "$search_dir" != "" ]; do
+    if [ -f "$search_dir/skywalk-sdd/git-hooks/commit-msg-sdd-trailer.cjs" ]; then
+      script="$search_dir/skywalk-sdd/git-hooks/commit-msg-sdd-trailer.cjs"
+      break
+    fi
+    search_dir="$(dirname "$search_dir")"
+  done
+fi
+
+if [ -z "$script" ]; then
+  echo "[SDD] 未找到 commit-msg-sdd-trailer.cjs，跳过 commit-msg trailer"
+  exit 0
+fi
+
+# $1 = Git 传入的 commit message 文件路径
+# --project 告诉 .cjs 脚本代码仓根目录（用于解析 spec 布局）
+node "$script" "$1" --project="$git_root"

package/templates/git-hooks/pre-commit

@@ -0,0 +1,57 @@
+#!/bin/sh
+# KLD SDD Pre-Commit Hook
+# 远程引用 spec 仓 skywalk-sdd/git-hooks/ 下的 .cjs 脚本
+# 兼容单仓库/多仓库/单仓mono布局
+# marker: KLD SDD quality gate
+
+# 从 hook 所在目录推算 git 根目录
+hook_dir="$(cd "$(dirname "$0")" && pwd)"
+git_dir="$(dirname "$hook_dir")"
+git_root="$(dirname "$git_dir")"
+
+hooks_dir=""
+
+# 方法1: git config sdd.specPath（多仓布局：spec 是独立 clone）
+spec_path=$(git config --local sdd.specPath 2>/dev/null)
+if [ -n "$spec_path" ] && [ -d "$spec_path/skywalk-sdd/git-hooks" ]; then
+  hooks_dir="$spec_path/skywalk-sdd/git-hooks"
+fi
+
+# 方法2: .sdd-spec-root（单仓 mono 布局：skywalk-sdd 在 spec 包裹包子目录内）
+if [ -z "$hooks_dir" ] && [ -f "$git_root/.sdd-spec-root" ]; then
+  spec_rel=$(cat "$git_root/.sdd-spec-root" | head -1 | tr -d '[:space:]')
+  if [ -n "$spec_rel" ] && [ -d "$git_root/$spec_rel/skywalk-sdd/git-hooks" ]; then
+    hooks_dir="$git_root/$spec_rel/skywalk-sdd/git-hooks"
+  fi
+fi
+
+# 方法3: 从 git 根向上搜索 skywalk-sdd/git-hooks（spec 仓本身或父级）
+if [ -z "$hooks_dir" ]; then
+  search_dir="$git_root"
+  while [ "$search_dir" != "/" ] && [ "$search_dir" != "" ]; do
+    if [ -d "$search_dir/skywalk-sdd/git-hooks" ]; then
+      hooks_dir="$search_dir/skywalk-sdd/git-hooks"
+      break
+    fi
+    search_dir="$(dirname "$search_dir")"
+  done
+fi
+
+if [ -z "$hooks_dir" ]; then
+  echo "[SDD] 未找到 spec 仓的 skywalk-sdd/git-hooks 目录，跳过 pre-commit 检查"
+  exit 0
+fi
+
+echo "[SDD] 执行提交前检查..."
+
+# 1. tasks.md 完成度检查
+if [ -f "$hooks_dir/pre-commit-sdd-check.cjs" ]; then
+  node "$hooks_dir/pre-commit-sdd-check.cjs" --project="$git_root" "$@" || exit 1
+fi
+
+# 2. 代码-spec 一致性检查
+if [ -f "$hooks_dir/pre-commit-consistency-check.cjs" ]; then
+  node "$hooks_dir/pre-commit-consistency-check.cjs" --project="$git_root" "$@" || exit 1
+fi
+
+echo "[SDD] ✅ 所有 pre-commit 检查通过"

package/templates/git-hooks/pre-commit-consistency-check.cjs

@@ -0,0 +1,193 @@
+#!/usr/bin/env node
+/**
+ * pre-commit-consistency-check.cjs
+ *
+ * Pre-commit 门禁：检查活跃变更的 Spec 一致性校验报告。
+ * 若 confidence=low 则阻止提交；缺少报告则警告但放行（向后兼容）。
+ *
+ * 用法: node pre-commit-consistency-check.cjs --project=<project-root> [--change=<change-name>]
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+function readArg(name) {
+  const prefix = `--${name}=`;
+  const found = process.argv.find(arg => arg.startsWith(prefix));
+  return found ? found.slice(prefix.length) : '';
+}
+
+function hasFlag(name) {
+  return process.argv.includes(`--${name}`);
+}
+
+/**
+ * 从 .sdd-spec-root 文件读取 spec 包裹包相对路径（单仓 mono 布局）
+ */
+function resolveSpecRoot(projectRoot) {
+  // 1. 检查 .sdd-spec-root（单仓 mono 模式）
+  const hintPath = path.join(projectRoot, '.sdd-spec-root');
+  if (fs.existsSync(hintPath)) {
+    const rel = fs.readFileSync(hintPath, 'utf8').trim();
+    if (rel) {
+      const specAbs = path.resolve(projectRoot, rel);
+      if (fs.existsSync(specAbs)) {
+        return specAbs;
+      }
+    }
+  }
+
+  // 2. 查找 *-sdd-specs 子目录（多仓工作区模式）
+  const entries = fs.existsSync(projectRoot) ? fs.readdirSync(projectRoot) : [];
+  for (const name of entries) {
+    if (/-sdd-specs$/i.test(name)) {
+      const candidate = path.join(projectRoot, name);
+      if (fs.statSync(candidate).isDirectory() && fs.existsSync(path.join(candidate, 'openspec'))) {
+        return candidate;
+      }
+    }
+  }
+
+  // 3. 项目根本身就是 spec 仓
+  if (fs.existsSync(path.join(projectRoot, 'openspec', 'changes'))) {
+    return projectRoot;
+  }
+
+  return null;
+}
+
+/**
+ * 发现活跃变更列表
+ */
+function discoverActiveChanges(specRoot, explicitChange) {
+  if (explicitChange) {
+    return [explicitChange];
+  }
+
+  const changesDir = path.join(specRoot, 'openspec', 'changes');
+  if (!fs.existsSync(changesDir)) {
+    return [];
+  }
+
+  return fs.readdirSync(changesDir)
+    .filter(name => {
+      const fullPath = path.join(changesDir, name);
+      return fs.statSync(fullPath).isDirectory()
+        && !name.startsWith('.')
+        && name !== 'archive';
+    });
+}
+
+/**
+ * 查找变更的一致性报告 JSON
+ */
+function findConsistencyReport(specRoot, changeName) {
+  const patterns = [
+    'consistency-report-result.json',
+    'consistency-report-self-review-result.json',
+  ];
+
+  for (const pattern of patterns) {
+    const reportPath = path.join(specRoot, 'openspec', 'changes', changeName, pattern);
+    if (fs.existsSync(reportPath)) {
+      return reportPath;
+    }
+  }
+
+  return null;
+}
+
+/**
+ * 解析一致性报告，返回置信度
+ */
+function parseReport(reportPath) {
+  try {
+    const content = fs.readFileSync(reportPath, 'utf8');
+    const data = JSON.parse(content);
+    return {
+      confidence: (data.confidence || '').toLowerCase(),
+      overallResult: (data.overallResult || '').toLowerCase(),
+      changeName: data.changeName || '',
+      reportPath,
+    };
+  } catch (err) {
+    return { confidence: '', overallResult: '', changeName: '', reportPath, parseError: err.message };
+  }
+}
+
+function main() {
+  const projectRoot = path.resolve(readArg('project') || process.env.SDD_PROJECT || process.cwd());
+  const explicitChange = readArg('change') || process.env.SDD_CHANGE || process.env.OPENSPEC_CHANGE || '';
+  const strictMode = hasFlag('strict') || process.env.SDD_STRICT_CONSISTENCY === '1';
+
+  const specRoot = resolveSpecRoot(projectRoot);
+  if (!specRoot) {
+    console.log('SDD consistency-check: 未找到 spec 仓库，跳过一致性校验');
+    return;
+  }
+
+  const changes = discoverActiveChanges(specRoot, explicitChange);
+  if (changes.length === 0) {
+    console.log('SDD consistency-check: 无活跃变更，跳过一致性校验');
+    return;
+  }
+
+  const blockers = [];
+  const missing = [];
+  const passed = [];
+
+  for (const changeName of changes) {
+    const reportPath = findConsistencyReport(specRoot, changeName);
+    if (!reportPath) {
+      missing.push(changeName);
+      continue;
+    }
+
+    const report = parseReport(reportPath);
+    if (report.parseError) {
+      console.warn(`SDD consistency-check: ⚠️  ${changeName} 报告解析失败: ${report.parseError}`);
+      missing.push(changeName);
+      continue;
+    }
+
+    if (report.confidence === 'low' || report.overallResult === 'fail') {
+      blockers.push({ changeName, report });
+    } else {
+      passed.push({ changeName, report });
+    }
+  }
+
+  // 输出摘要
+  if (passed.length > 0) {
+    for (const item of passed) {
+      console.log(`SDD consistency-check: ✅ ${item.changeName} 置信度=${item.report.confidence}`);
+    }
+  }
+
+  if (missing.length > 0) {
+    console.warn(`SDD consistency-check: ⚠️  以下变更缺少一致性校验报告（允许提交，建议执行 opsx-consistency-check）:`);
+    for (const name of missing) {
+      console.warn(`  - ${name}`);
+    }
+  }
+
+  if (blockers.length > 0) {
+    console.error(`SDD consistency-check: ❌ 以下变更的一致性校验未通过（confidence=low），阻止提交:`);
+    for (const item of blockers) {
+      console.error(`  - ${item.changeName} (confidence=${item.report.confidence}, result=${item.report.overallResult})`);
+      console.error(`    报告路径: ${item.report.reportPath}`);
+    }
+    console.error('');
+    console.error('请修复不一致项后重新执行 opsx-consistency-check，或使用 --no-verify 跳过（不推荐）。');
+    process.exit(1);
+  }
+
+  if (strictMode && missing.length > 0) {
+    console.error('SDD consistency-check: ❌ strict 模式已启用，缺少报告的变更不允许提交。');
+    process.exit(1);
+  }
+}
+
+main();

package/templates/git-hooks/pre-push

@@ -0,0 +1,57 @@
+#!/bin/sh
+# KLD SDD Pre-Push Hook
+# 远程引用 spec 仓 skywalk-sdd/git-hooks/ 下的 .cjs 脚本
+# 兼容单仓库/多仓库/单仓mono布局
+# marker: KLD SDD quality gate
+
+# 从 hook 所在目录推算 git 根目录
+hook_dir="$(cd "$(dirname "$0")" && pwd)"
+git_dir="$(dirname "$hook_dir")"
+git_root="$(dirname "$git_dir")"
+
+hooks_dir=""
+
+# 方法1: git config sdd.specPath（多仓布局：spec 是独立 clone）
+spec_path=$(git config --local sdd.specPath 2>/dev/null)
+if [ -n "$spec_path" ] && [ -d "$spec_path/skywalk-sdd/git-hooks" ]; then
+  hooks_dir="$spec_path/skywalk-sdd/git-hooks"
+fi
+
+# 方法2: .sdd-spec-root（单仓 mono 布局：skywalk-sdd 在 spec 包裹包子目录内）
+if [ -z "$hooks_dir" ] && [ -f "$git_root/.sdd-spec-root" ]; then
+  spec_rel=$(cat "$git_root/.sdd-spec-root" | head -1 | tr -d '[:space:]')
+  if [ -n "$spec_rel" ] && [ -d "$git_root/$spec_rel/skywalk-sdd/git-hooks" ]; then
+    hooks_dir="$git_root/$spec_rel/skywalk-sdd/git-hooks"
+  fi
+fi
+
+# 方法3: 从 git 根向上搜索 skywalk-sdd/git-hooks（spec 仓本身或父级）
+if [ -z "$hooks_dir" ]; then
+  search_dir="$git_root"
+  while [ "$search_dir" != "/" ] && [ "$search_dir" != "" ]; do
+    if [ -d "$search_dir/skywalk-sdd/git-hooks" ]; then
+      hooks_dir="$search_dir/skywalk-sdd/git-hooks"
+      break
+    fi
+    search_dir="$(dirname "$search_dir")"
+  done
+fi
+
+if [ -z "$hooks_dir" ]; then
+  echo "[SDD] 未找到 spec 仓的 skywalk-sdd/git-hooks 目录，跳过 pre-push 检查"
+  exit 0
+fi
+
+echo "[SDD] 执行推送前检查..."
+
+# 1. doctor 质量门禁检查
+if [ -f "$hooks_dir/pre-push-sdd-check.cjs" ]; then
+  node "$hooks_dir/pre-push-sdd-check.cjs" --project="$git_root" "$@" || exit 1
+fi
+
+# 2. 代码-spec 一致性检查（推送前更严格）
+if [ -f "$hooks_dir/pre-push-consistency-check.cjs" ]; then
+  node "$hooks_dir/pre-push-consistency-check.cjs" --project="$git_root" "$@" || exit 1
+fi
+
+echo "[SDD] ✅ 所有 pre-push 检查通过"