kld-sdd 2.6.14 → 2.6.16

package/skywalk-sdd/metrics-v3.cjs

@@ -1,10 +1,30 @@
 'use strict';
 
-const REPORT_SCHEMA_VERSION = 'sdd-efficiency-report/v3';
-const METRICS_CONTRACT_VERSION = '3.0';
-const CHANGE_TYPES = ['config', 'document', 'report', 'composite', 'other'];
+const REPORT_SCHEMA_VERSION = 'sdd-efficiency-report/v4';
+const METRICS_CONTRACT_VERSION = '4.0';
+const SCHEME_VERSION = 'V3.0';
+/** Writable change types (scheme 5.3). Legacy document/other read as unknown. */
+const CHANGE_TYPES = ['config', 'transaction', 'report', 'composite'];
+const LEGACY_CHANGE_TYPES = ['document', 'other'];
 const MINIMUM_METRICS = ['e1', 'q3', 'p4', 'p_r', 'p_h'];
 
+/**
+ * Format artifact byte size: <1MiB → KB, else MB; two decimals; never bare B.
+ * @param {number} bytes
+ * @returns {string}
+ */
+function formatArtifactSize(bytes) {
+  const n = Number(bytes);
+  if (!Number.isFinite(n) || n < 0) return '0.00 KB';
+  const kib = 1024;
+  const mib = 1024 * 1024;
+  if (n < mib) {
+    const kb = n / kib;
+    return `${kb.toFixed(2)} KB`;
+  }
+  return `${(n / mib).toFixed(2)} MB`;
+}
+
 const ALERT_THRESHOLDS = {
   q3: { red: 70, yellow: 85, direction: 'higher_better' },
   p4: { red: 0.4, yellow: 0.6, direction: 'higher_better' },
@@ -126,7 +146,27 @@ function countScenariosInMarkdown(text) {
 function validateChangeType(value) {
   if (typeof value !== 'string') return 'unknown';
   const normalized = value.trim().toLowerCase();
-  return CHANGE_TYPES.includes(normalized) ? normalized : 'unknown';
+  if (CHANGE_TYPES.includes(normalized)) return normalized;
+  if (LEGACY_CHANGE_TYPES.includes(normalized)) return 'unknown';
+  return 'unknown';
+}
+
+function diagnoseChangeType(value) {
+  if (typeof value !== 'string') {
+    return { change_type: 'unknown', legacy_change_type: null, warning: null };
+  }
+  const normalized = value.trim().toLowerCase();
+  if (CHANGE_TYPES.includes(normalized)) {
+    return { change_type: normalized, legacy_change_type: null, warning: null };
+  }
+  if (LEGACY_CHANGE_TYPES.includes(normalized)) {
+    return {
+      change_type: 'unknown',
+      legacy_change_type: normalized,
+      warning: `legacy_change_type:${normalized}`,
+    };
+  }
+  return { change_type: 'unknown', legacy_change_type: null, warning: 'invalid_change_type' };
 }
 
 function resolveReviewerIndependence(meta = {}) {
@@ -850,9 +890,41 @@ function buildSchemeCompliance(input = {}) {
   const minimumStatus = minimum.numeric_available === minimum.numeric_total
     ? (minimum.trusted_available === minimum.numeric_total ? 'implemented' : 'provisional')
     : 'provisional';
-  const q1Status = quality.q1_status || quality.q1_spec_conformance?.status || 'pending-upstream';
-  const q4Status = quality.q4_status || quality.q4_tdd_coverage?.status || 'pending-upstream';
-  const q3Status = quality.q3_score_status === 'verified' ? 'implemented' : 'provisional';
+  const q1Raw = quality.q1_human_status
+    || quality.q1_status
+    || quality.q1_spec_conformance?.status
+    || 'pending-upstream';
+  const q1Status = (q1Raw === 'unverified' || q1Raw === 'self-review')
+    ? 'provisional'
+    : (q1Raw === 'pending-upstream' ? 'pending-upstream' : q1Raw);
+  const q4Raw = quality.q4_status || quality.q4_tdd_coverage?.status || 'pending-upstream';
+  const q4Source = quality.q4_source || quality.q4_tdd_coverage?.source || null;
+  const q4Status = q4Source === 'conformance-fallback' || q4Raw === 'conformance-fallback'
+    ? 'pending-upstream'
+    : q4Raw;
+  const q3Independence = quality.q3_reviewer_independence || 'unknown';
+  const q3Status = quality.q3_score_status === 'verified'
+    && q3Independence === 'independent-review'
+    ? 'implemented'
+    : 'provisional';
+  const semanticParity = input.semantic_parity_status || input.semantic_parity || null;
+  const multiFormatStatus = semanticParity === 'pass'
+    ? 'implemented'
+    : (['md', 'html', 'json'].every(format => formats.includes(format)) ? 'provisional' : 'provisional');
+  const alertLoopReady = Boolean(
+    input.alert_loop
+    && input.alert_loop.root_cause
+    && input.alert_loop.owner
+    && input.alert_loop.due
+    && input.alert_loop.expected_impact
+    && input.alert_loop.two_cycle_evidence,
+  );
+  const eventContractHealth = input.evidence_contract_health
+    || input.event_contract_health
+    || null;
+  const reproducibleStatus = eventContractHealth === 'healthy' && Number(input.event_count) > 0
+    ? 'implemented'
+    : (Number(input.event_count) > 0 ? 'provisional' : 'provisional');
   const statusLabel = status => ({
     implemented: '已实现',
     provisional: '部分可用',
@@ -864,6 +936,7 @@ function buildSchemeCompliance(input = {}) {
     unknown: '未知',
     'independent-review': '独立复核',
     'self-review': '自评',
+    unverified: '未人工验证',
   }[status] || status || '未知');
 
   const items = [
@@ -886,7 +959,7 @@ function buildSchemeCompliance(input = {}) {
       label: '条件指标（Q1、Q4）',
       status: q1Status === 'pending-upstream' || q4Status === 'pending-upstream'
         ? 'pending-upstream'
-        : 'implemented',
+        : (q1Status === 'provisional' || q4Status === 'provisional' ? 'provisional' : 'implemented'),
       evidence: `Q1：${statusLabel(q1Status)}；Q4：${statusLabel(q4Status)}`,
     },
     {
@@ -899,7 +972,7 @@ function buildSchemeCompliance(input = {}) {
       requirement: 'independent-reviewer',
       label: '独立复核',
       status: q3Status,
-      evidence: `Q3：${statusLabel(quality.q3_score_status || 'provisional')}；复核方式：${statusLabel(quality.q3_reviewer_independence || 'unknown')}`,
+      evidence: `Q3：${statusLabel(quality.q3_score_status || 'provisional')}；复核方式：${statusLabel(q3Independence)}`,
     },
     {
       requirement: 'tracking-periods',
@@ -922,20 +995,30 @@ function buildSchemeCompliance(input = {}) {
     {
       requirement: 'alert-feedback-loop',
       label: '指标与证据告警闭环',
-      status: input.evidence_alerts ? 'implemented' : 'provisional',
-      evidence: input.evidence_alerts ? '稳定问题编号、未解决/已解决状态和历史记录' : '当前模型未提供告警生命周期',
+      status: alertLoopReady ? 'implemented' : 'provisional',
+      evidence: alertLoopReady
+        ? '具备根因、负责人、期限、预期影响与两周期验证'
+        : '仍缺根因/负责人/期限/预期影响/两周期验证中的完整字段',
     },
     {
       requirement: 'multi-format-same-model',
       label: 'Markdown、HTML、JSON 同源',
-      status: ['md', 'html', 'json'].every(format => formats.includes(format)) ? 'implemented' : 'provisional',
-      evidence: formats.length > 0 ? formats.map(format => ({ md: 'Markdown', html: 'HTML', json: 'JSON' }[format] || format)).join(' / ') : '格式信息未提供',
+      status: multiFormatStatus,
+      evidence: semanticParity === 'pass'
+        ? '三格式语义对账通过'
+        : (formats.length > 0
+          ? `${formats.map(format => ({ md: 'Markdown', html: 'HTML', json: 'JSON' }[format] || format)).join(' / ')} 已产出，语义对账未确认`
+          : '格式信息未提供'),
     },
     {
       requirement: 'reproducible-auditable',
       label: '可复算、可审计',
-      status: input.event_count > 0 ? 'implemented' : 'provisional',
-      evidence: input.event_count > 0 ? `${input.event_count} 条 JSONL 事件` : '未提供事件数量',
+      status: reproducibleStatus,
+      evidence: eventContractHealth === 'healthy'
+        ? `${input.event_count} 条事件且证据契约健康`
+        : (input.event_count > 0
+          ? `${input.event_count} 条 JSONL 事件；证据契约健康度未达标`
+          : '未提供事件数量'),
     },
   ];
   const counts = {};
@@ -945,6 +1028,7 @@ function buildSchemeCompliance(input = {}) {
     version: 'V3.0',
     items,
     counts,
+    evidence_contract_health: eventContractHealth || null,
   };
 }
 
@@ -1125,7 +1209,9 @@ function deriveSuccessfulReworkReason(attemptContext = {}) {
 module.exports = {
   REPORT_SCHEMA_VERSION,
   METRICS_CONTRACT_VERSION,
+  SCHEME_VERSION,
   CHANGE_TYPES,
+  LEGACY_CHANGE_TYPES,
   ALERT_THRESHOLDS,
   MINIMUM_METRICS,
   clamp,
@@ -1148,6 +1234,8 @@ module.exports = {
   findDevelopmentActivities,
   deriveSuccessfulReworkReason,
   validateChangeType,
+  diagnoseChangeType,
+  formatArtifactSize,
   createInvalidArgError,
   countScenariosInMarkdown,
 };

package/skywalk-sdd/openspec-shim.cjs

@@ -0,0 +1,48 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * openspec-shim.cjs — 自动定位 spec 包并透传 openspec 命令。
+ *
+ * 用法: node skywalk-sdd/openspec-shim.cjs <openspec-args>
+ * 示例: node skywalk-sdd/openspec-shim.cjs list
+ *       node skywalk-sdd/openspec-shim.cjs add change my-feature
+ *
+ * 自动通过 resolve-spec-root.cjs 定位 spec 包目录，
+ * 然后在该目录下执行 openspec 命令。
+ */
+
+const { resolveSpecProjectRoot } = require('./ontology/resolve-spec-root.cjs');
+
+const args = process.argv.slice(2);
+
+if (args.length === 0 || args[0] === '--help' || args[0] === '-h') {
+  console.log('用法: node skywalk-sdd/openspec-shim.cjs <openspec-args>');
+  console.log('示例: node skywalk-sdd/openspec-shim.cjs list');
+  console.log('      node skywalk-sdd/openspec-shim.cjs add change my-feature');
+  process.exit(0);
+}
+
+const projectRoot = process.cwd();
+const specRoot = resolveSpecProjectRoot(projectRoot);
+
+if (specRoot === projectRoot) {
+  console.error('⚠️  未找到 spec 包目录（未配置 .sdd-spec-root，也未检测到 *-sdd-specs 仓库）');
+  console.error('    配置方式: 在项目根目录创建 .sdd-spec-root 文件，写入 spec 包相对或绝对路径');
+  console.error('    或使用: kld-sdd link-spec --path=<spec-clone>');
+  process.exit(1);
+}
+
+const { execSync } = require('child_process');
+const openspecArgs = args.map(a => `"${a.replace(/"/g, '\\"')}"`).join(' ');
+const cmd = `openspec ${openspecArgs}`;
+
+try {
+  execSync(cmd, { cwd: specRoot, stdio: 'inherit' });
+} catch (err) {
+  if (err.status) {
+    process.exit(err.status);
+  }
+  console.error(`❌ openspec 执行失败: ${err.message}`);
+  process.exit(1);
+}

package/skywalk-sdd/reporting/change-report-markdown.cjs

@@ -0,0 +1,294 @@
+'use strict';
+
+const { buildChangeReportViewModel } = require('./change-report-view-model.cjs');
+
+function formatValue(value) {
+  if (value == null || value === '') return '暂无数据';
+  return String(value);
+}
+
+function formatRatioToPercent(ratio) {
+  if (ratio == null || !Number.isFinite(Number(ratio))) return '暂无数据';
+  return `${(Number(ratio) * 100).toFixed(1)}%`;
+}
+
+function renderSectionOverview(section, report) {
+  const minSet = report.minimum_metric_set || {};
+  const lines = [
+    '## 一句话结论',
+    '',
+    `> ${section.summary}`,
+    '',
+    `## ${section.title}`,
+    '',
+    '### 摘要卡片',
+  ];
+  for (const card of section.cards || []) {
+    lines.push(`- ${card.label}：${formatValue(card.value)}`);
+  }
+  if (report.scheme_compliance?.counts) {
+    lines.push(
+      `- 方案覆盖：${report.scheme_compliance.counts.implemented ?? 0}/${report.scheme_compliance.items?.length ?? 0} 项已完整实现`,
+    );
+  }
+  lines.push(
+    '',
+    '### 关键指标可信覆盖',
+    `- 数值覆盖：${formatRatioToPercent(minSet.numeric_coverage_rate)}（${minSet.numeric_available ?? 0}/${minSet.numeric_total ?? 5}）`,
+    `- 可信覆盖：${formatRatioToPercent(minSet.trusted_coverage_rate)}（${minSet.trusted_available ?? 0}/${minSet.numeric_total ?? 5}；临时 ${minSet.provisional ?? 0} 项）`,
+    '',
+    '## 核心指标',
+    `- 每个场景平均用时（E1）：见「指标与阶段」`,
+    `- 规约检查得分（Q3）：见「指标与阶段」`,
+    `- 编码前是否先检查（P4）：见「指标与阶段」`,
+  );
+  return lines;
+}
+
+function renderSectionMetrics(section, report) {
+  const tdd = section.tdd_pairs || {};
+  const reasons = report.metrics?.process?.rework_summary?.reasons;
+  const lines = [
+    `## ${section.title}`,
+    '',
+    section.summary,
+    '',
+    '### 关键指标',
+  ];
+  for (const metric of section.metric_cards || []) {
+    lines.push(`- ${metric.name}（${metric.code}）：${metric.value} · ${metric.state}`);
+  }
+  if (reasons?.by_category) {
+    const parts = Object.entries(reasons.by_category)
+      .map(([k, v]) => `${k}=${v}`)
+      .join(', ');
+    lines.push(`- 重复执行原因分布：${parts || '无'}`);
+  }
+  lines.push(
+    '',
+    '### TDD 对',
+    `- 完整度：${tdd.complete == null || tdd.required == null ? '暂无数据' : `${tdd.complete}/${tdd.required}`}`,
+  );
+  const incomplete = (tdd.pairs || []).filter(pair => pair.status && pair.status !== 'complete');
+  if (incomplete.length > 0) {
+    lines.push('- 缺口：');
+    for (const pair of incomplete) {
+      lines.push(`  - ${pair.pair_id}：${pair.status}`);
+    }
+  }
+  const stages = section.stages || [];
+  lines.push('', '### 阶段时间线');
+  if (stages.length === 0) {
+    lines.push('- 无阶段节点');
+  } else {
+    for (const node of stages.slice(0, 40)) {
+      lines.push(
+        `- ${node.display_stage} R${node.display_round}：${node.display_result}`
+          + `（${node.display_duration}）`,
+      );
+    }
+  }
+  return lines;
+}
+
+function renderSectionIssues(section, report) {
+  const lines = [
+    `## ${section.title}`,
+    '',
+    section.summary,
+    '',
+  ];
+  const audit = section.task_evidence_audit || {};
+  if (audit.direct_test_backlink || audit.strict_test_coverage) {
+    lines.push('### 任务证据四口径');
+    lines.push(
+      `- 文档完成：${formatValue(audit.document_completion?.completed)}/${formatValue(audit.document_completion?.total)}`,
+    );
+    lines.push(
+      `- 直接回链：${formatValue(audit.direct_test_backlink?.verified)}/${formatValue(audit.direct_test_backlink?.total)}`,
+    );
+    lines.push(
+      `- 严格覆盖：${formatValue(audit.strict_test_coverage?.verified)}/${formatValue(audit.strict_test_coverage?.total)}`,
+    );
+    lines.push('');
+  }
+  lines.push('### 问题类别');
+  const categories = section.categories || [];
+  if (categories.length === 0) {
+    lines.push('- 当前没有归并后的问题类别。');
+  } else {
+    for (const group of categories) {
+      lines.push(
+        `- ${group.label || group.code}：命中 ${group.occurrence_count || 0} 次，关联任务 ${(group.affected_tasks || []).length} 个`,
+      );
+    }
+  }
+  const findings = section.apply_findings || [];
+  const issues = section.issues || [];
+  if (issues.length > 0) {
+    lines.push('', '### 问题明细');
+    for (const issue of issues) {
+      lines.push(
+        `- [${issue.code}] ${issue.subject || '本次变更'} · 状态：${issue.status} · 判定：${issue.verdict}`,
+        `  - 根因：${issue.root_cause}`,
+        `  - 预期：${issue.expected}`,
+        `  - 实际：${issue.actual}`,
+        `  - 影响：${issue.impact}`,
+        `  - 修复建议：${issue.remediation}`,
+        `  - 证据事件：${(issue.evidence_event_ids || []).join(', ') || '暂无可定位事件'}`,
+      );
+    }
+  } else if (findings.length > 0) {
+    lines.push('', '### 审计发现');
+    for (const finding of findings) {
+      lines.push(`- [${finding.code}] ${finding.task_id || '变更'}：${finding.message || ''}`);
+    }
+  }
+  const dispositions = section.warning_dispositions
+    || section.report_warning_dispositions
+    || [];
+  if (dispositions.length > 0) {
+    lines.push('', '### 告警处置');
+    for (const item of dispositions) {
+      lines.push(`- [告警处置] ${item.warning || item.code || 'UNKNOWN'}：${item.disposition || 'open'}`);
+    }
+  }
+
+  const known = report.known_risks || {};
+  lines.push('', '### 已知风险');
+  lines.push(`- 数据可用：${known._available ? '是' : '否'}`);
+  lines.push(
+    `- 严重问题数：${known._available ? (known.severe_issues?.length ?? 0) : '无数据'}`,
+  );
+  if (Array.isArray(known.warnings) && known.warnings.length > 0) {
+    for (const warning of known.warnings) {
+      const items = Array.isArray(warning.items) ? warning.items : null;
+      const count = items ? items.length : (warning.warnings || 0);
+      const statusLabel = warning.resolved === true ? '✅已修复' : '⏳待确认';
+      lines.push(`- 警告：${warning.command || 'check'} 阶段 ${count} 个${statusLabel}`);
+      if (items && items.length > 0) {
+        for (const item of items) {
+          lines.push(
+            `  - ${item.description || '待确认项'}${item.target ? `（${item.target}）` : ''}`,
+          );
+        }
+      }
+    }
+  } else {
+    lines.push('- 无警告（无需修复）');
+  }
+
+  const notes = report.process_notes || {};
+  lines.push('', '## 过程记录');
+  lines.push(`- 数据可用：${notes._available ? '是' : '否'}`);
+  lines.push(`- 过程事件总数：${notes.total ?? 'null'}`);
+  if (notes.by_kind) {
+    lines.push(`- 按 kind 分布：${JSON.stringify(notes.by_kind)}`);
+  }
+  if (Array.isArray(notes.notes) && notes.notes.length > 0) {
+    for (const note of notes.notes) {
+      lines.push(
+        `- [${note.stage || 'unknown'}] ${note.kind || 'note'}${note.round ? ` R${note.round}` : ''}：${note.summary || ''}${note.target ? ` → ${note.target}` : ''}`,
+      );
+    }
+  } else {
+    lines.push('- 无过程事件');
+  }
+  return lines;
+}
+
+function renderSectionArtifacts(section, report) {
+  const changed = section.changed_files || {};
+  const rawChanged = report.changed_files || {};
+  const archive = report.archive_result || null;
+  const taskCompletion = archive?.task_completion || null;
+  const lines = [
+    `## ${section.title}`,
+    '',
+    section.summary,
+    '',
+    '### 变更文件',
+    `- 数据可用：${rawChanged._available ? '是' : '否'}`,
+    `- 最终变更文件数：${formatValue(changed.files_changed)}`,
+    `- 新增行数：${formatValue(changed.added_lines)}`,
+    `- 对账状态：${formatValue(changed.reconciliation_status)}`,
+  ];
+  if ((changed.only_in_task_events || []).length > 0) {
+    lines.push(`- 仅任务事件：${changed.only_in_task_events.join(', ')}`);
+  }
+  if ((changed.only_in_final_output || []).length > 0) {
+    lines.push(`- 仅最终输出：${changed.only_in_final_output.join(', ')}`);
+  }
+  lines.push('', '### 产物清单');
+  const artifacts = section.artifacts || [];
+  if (artifacts.length === 0) {
+    lines.push('- 暂无产物条目');
+  } else {
+    for (const item of artifacts) {
+      const size = item.size_display
+        || '—';
+      lines.push(
+        `- ${item.name}：${item.exists ? '已生成' : '未生成'} · ${item.path || '—'} · ${size}`,
+      );
+    }
+  }
+  const copied = report.artifacts?.copied_specs;
+  lines.push(
+    `- 迁移文件数：${Array.isArray(copied) ? copied.length : 'null'}`,
+  );
+  lines.push(
+    '',
+    '### 归因审计',
+    `- 显式关联历史事件：${section.attribution_summary?.linked_source_event_count ?? 0}`,
+    `- 有效关联：${section.attribution_summary?.active_link_count ?? 0}`,
+    `- 未归属候选：${section.attribution_summary?.unassigned_candidate_count ?? 0}`,
+    `- 被拒绝的跨变更碰撞：${section.attribution_summary?.rejected_collision_count ?? 0}`,
+    '',
+    '### 归档结果',
+    `- 归档原因：${archive?.reason || 'null'}`,
+    `- 归档方式：${archive?.method || 'null'}`,
+    `- 归档目录：${archive?.archive_path || report.artifacts?.archive_path || 'null'}`,
+    `- 归档清单：${archive?.manifest_path || report.artifacts?.manifest_path || 'null'}`,
+    `- 最终报告：${archive?.report_path || 'null'}`,
+    `- 主任务完成：${taskCompletion?.primary_tasks
+      ? `${taskCompletion.primary_tasks.completed}/${taskCompletion.primary_tasks.total}`
+      : 'null'}`,
+    `- 全部 checkbox 完成：${taskCompletion?.completed ?? 'null'}/${taskCompletion?.total ?? 'null'}（含验收子项；分母≠主任务数）`,
+    `- 未勾选 checkbox：${taskCompletion?.incomplete ?? 'null'}`,
+    `- 未勾选任务项：${taskCompletion?.incomplete ?? 'null'}`,
+  );
+  return lines;
+}
+
+function renderChangeReportMarkdown(report) {
+  const view = buildChangeReportViewModel(report);
+  const projectLabel = report.project_root
+    ? String(report.project_root).replace(/[\\/]+$/, '').split(/[\\/]/).pop()
+    : null;
+  const lines = [
+    `# SDD 效果度量报告${view.change ? ` - ${view.change}` : ''}`,
+    '',
+    `- 生成时间：${report.generated_at || '未知'}`,
+    ...(projectLabel ? [`- 项目路径：${projectLabel}`] : []),
+    `- 统计范围：change/${view.change || 'unknown'}`,
+    `- 报告 Schema：${view.schema_version || 'unknown'}（指标契约 ${view.metrics_contract || 'unknown'}）`,
+    `<!-- sdd-semantic-digest:${view.semantic_digest} -->`,
+    '',
+  ];
+
+  for (const sectionId of view.section_order) {
+    const section = view.sections[sectionId];
+    if (!section) continue;
+    if (sectionId === 'overview') lines.push(...renderSectionOverview(section, report));
+    else if (sectionId === 'metrics-stages') lines.push(...renderSectionMetrics(section, report));
+    else if (sectionId === 'issues-evidence') lines.push(...renderSectionIssues(section, report));
+    else if (sectionId === 'artifacts-trace') lines.push(...renderSectionArtifacts(section, report));
+    lines.push('');
+  }
+
+  return lines.join('\n');
+}
+
+module.exports = {
+  renderChangeReportMarkdown,
+};