kld-sdd 2.6.17 → 2.7.3

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

@@ -2,196 +2,435 @@
 /**
  * pre-push-consistency-check.cjs
  *
- * Pre-push 门禁：检查活跃变更的 Spec 一致性校验报告。
- * 与 pre-commit-consistency-check.cjs 类似，但更严格：
- *   - confidence=low → 阻止推送
- *   - 缺少报告 → 警告（默认放行）；strict 模式下阻止推送
+ * Pre-push 轻量门禁：仅检查报告是否存在、是否过期。
+ * 完整的置信度校验由 pre-commit 完成，push 阶段不再重复。
  *
- * 用法: node pre-push-consistency-check.cjs --project=<project-root> [--change=<change-name>]
+ * 通过环境变量控制：
+ * - SDD_SKIP_CONSISTENCY_CHECK=1 → 跳过校验
+ * - SDD_WARN_ONLY=1 → 仅告警不拦截
+ * - 注意：两个环境变量互斥，只能启用一个
  */
-
 'use strict';
 
 const fs = require('fs');
 const path = require('path');
+const { execFileSync } = require('child_process');
 
-function readArg(name) {
+const readArg = (name) => {
   const prefix = `--${name}=`;
-  const found = process.argv.find(arg => arg.startsWith(prefix));
+  const found = process.argv.find(a => a.startsWith(prefix));
   return found ? found.slice(prefix.length) : '';
+};
+
+// --- Spec 根路径解析 ---
+
+function resolveSpecRoot() {
+  // .cjs 位于 <spec-root>/skywalk-sdd/git-hooks/，直接用 __dirname 推算
+  return path.resolve(__dirname, '..', '..');
 }
 
-function hasFlag(name) {
-  return process.argv.includes(`--${name}`);
+function discoverActiveChanges(specRoot) {
+  const changesDir = path.join(specRoot, 'openspec', 'changes');
+  if (!fs.existsSync(changesDir)) return [];
+
+  return fs.readdirSync(changesDir).filter(name => {
+    const p = path.join(changesDir, name);
+    return fs.statSync(p).isDirectory() && !name.startsWith('.') && name !== 'archive';
+  });
 }
 
+// --- Push 范围收敛 ---
+
 /**
- * 从 .sdd-spec-root 文件读取 spec 包裹包相对路径（单仓 mono 布局）
+ * 读取 pre-push 引用范围。
+ * 优先从 shell hook 通过环境变量 SDD_PRE_PUSH_REFS 传入（shell hook 已消费 stdin），
+ * 降级时尝试直接读 stdin。
  */
-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;
-      }
-    }
+function readPushRefLines() {
+  const envRefs = process.env.SDD_PRE_PUSH_REFS;
+  if (envRefs) {
+    // shell hook 用 \n 字面量拼接，也可能含真实换行符
+    return envRefs.split(/\\n|\n/).filter(Boolean);
   }
 
-  // 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;
+  try {
+    if (process.stdin.isTTY) return [];
+    const buffer = fs.readFileSync(0, 'utf8'); // fd 0 = stdin
+    return buffer.split(/\r?\n/).filter(Boolean);
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * 从 pre-push stdin 行解析 commit 范围，获取本次 push 实际变更的文件列表
+ */
+function getPushRangeFiles(projectRoot) {
+  const lines = readPushRefLines();
+  if (lines.length === 0) return null;
+
+  const files = new Set();
+  for (const line of lines) {
+    const parts = line.split(/\s+/);
+    if (parts.length < 4) continue;
+    const localSha = parts[1];
+    const remoteSha = parts[3];
+
+    // 删除分支：localSha 为全 0
+    if (localSha === '0000000000000000000000000000000000000000') continue;
+
+    try {
+      let diffFiles;
+      if (remoteSha === '0000000000000000000000000000000000000000') {
+        // 新建分支：用 git show 获取该 commit 引入的文件
+        diffFiles = execFileSync('git', ['show', '--name-only', '--pretty=format:', localSha], {
+          cwd: projectRoot, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'],
+        }).split(/\r?\n/).filter(Boolean);
+      } else {
+        // 已有分支：用 git diff 获取范围变更
+        diffFiles = execFileSync('git', ['diff', `${remoteSha}..${localSha}`, '--name-only'], {
+          cwd: projectRoot, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'],
+        }).split(/\r?\n/).filter(Boolean);
       }
+      for (const f of diffFiles) files.add(f.replace(/\\/g, '/'));
+    } catch {
+      // 单个 ref 失败不阻断，继续处理其他 ref
     }
   }
 
-  // 3. 项目根本身就是 spec 仓
-  if (fs.existsSync(path.join(projectRoot, 'openspec', 'changes'))) {
-    return projectRoot;
-  }
+  return files.size > 0 ? Array.from(files) : null;
+}
+
+function normalizePath(filePath) {
+  return filePath.replace(/\\/g, '/');
+}
 
-  return null;
+function getChangeNameFromPath(filePath) {
+  const normalized = normalizePath(filePath);
+  const match = normalized.match(/^openspec\/changes\/([^/]+)\//);
+  return match ? match[1] : '';
 }
 
 /**
- * 发现活跃变更列表
+ * 从 push 的变更文件列表中提取涉及的 change name
  */
-function discoverActiveChanges(specRoot, explicitChange) {
-  if (explicitChange) {
-    return [explicitChange];
+function discoverChangesFromPushFiles(projectRoot, specRoot) {
+  const pushFiles = getPushRangeFiles(projectRoot);
+  if (!pushFiles) return null; // 降级信号
+
+  const changes = new Set();
+  for (const file of pushFiles) {
+    const changeName = getChangeNameFromPath(file);
+    if (changeName) changes.add(changeName);
   }
 
-  const changesDir = path.join(specRoot, 'openspec', 'changes');
-  if (!fs.existsSync(changesDir)) {
-    return [];
+  if (changes.size === 0) {
+    console.log('[SDD push-consistency-check] 本次 push 不涉及 openspec 变更，跳过');
+    process.exit(0);
   }
 
-  return fs.readdirSync(changesDir)
-    .filter(name => {
-      const fullPath = path.join(changesDir, name);
-      return fs.statSync(fullPath).isDirectory()
-        && !name.startsWith('.')
-        && name !== 'archive';
-    });
+  // 过滤掉已归档的 change
+  const activeChanges = new Set(discoverActiveChanges(specRoot));
+  return Array.from(changes).filter(cn => activeChanges.has(cn));
 }
 
-/**
- * 查找变更的一致性报告 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;
-    }
+function findReport(specRoot, changeName, type) {
+  const names = type === 'json'
+    ? ['consistency-report-result.json', 'consistency-report-self-review-result.json']
+    : ['consistency-report.md', 'consistency-report-self-review.md'];
+
+  const found = [];
+  for (const n of names) {
+    const p = path.join(specRoot, 'openspec', 'changes', changeName, n);
+    if (fs.existsSync(p)) found.push(p);
+  }
+
+  // 如果两种模式的报告都存在，返回错误标记
+  if (found.length > 1) {
+    return { error: 'duplicate', paths: found };
   }
 
-  return null;
+  return found.length === 1 ? found[0] : null;
 }
 
-/**
- * 解析一致性报告，返回置信度
- */
 function parseReport(reportPath) {
   try {
-    const content = fs.readFileSync(reportPath, 'utf8');
-    const data = JSON.parse(content);
+    const data = JSON.parse(fs.readFileSync(reportPath, 'utf8'));
     return {
       confidence: (data.confidence || '').toLowerCase(),
-      overallResult: (data.overallResult || '').toLowerCase(),
-      changeName: data.changeName || '',
+      reviewMode: data.reviewMode || 'independent-review',
+      humanConfirmed: data.humanConfirmed === true,
       reportPath,
     };
   } catch (err) {
-    return { confidence: '', overallResult: '', changeName: '', reportPath, parseError: err.message };
+    return { confidence: '', reviewMode: '', humanConfirmed: false, reportPath, parseError: err.message };
   }
 }
 
+// --- 变更文件采集（基于配置文件精准定位） ---
+
+/**
+ * 简易 YAML 解析器：仅提取 code_repos 列表
+ */
+function parseCodeRepos(yamlPath) {
+  try {
+    const content = fs.readFileSync(yamlPath, 'utf8');
+    const match = content.match(/code_repos:\s*\n((?:\s+-\s+\S+\n?)+)/);
+    if (!match) return null;
+    return match[1]
+      .split('\n')
+      .map(line => line.replace(/^\s+-\s+/, '').trim())
+      .filter(Boolean);
+  } catch {
+    return null;
+  }
+}
+
+function gitDiff(repoRoot) {
+  try {
+    return execFileSync('git', ['diff', 'HEAD', '--name-only'], {
+      cwd: repoRoot, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'],
+    }).split(/\r?\n/).filter(Boolean);
+  } catch {
+    return [];
+  }
+}
+
+function getModifiedFiles(projectRoot) {
+  // 工作区模式：读 .sdd-workspace.yaml 的 code_repos
+  const wsYaml = path.join(projectRoot, '.sdd-workspace.yaml');
+  if (fs.existsSync(wsYaml)) {
+    const repos = parseCodeRepos(wsYaml);
+    if (repos && repos.length > 0) {
+      const files = [];
+      for (const repo of repos) {
+        const repoRoot = path.join(projectRoot, repo);
+        for (const f of gitDiff(repoRoot)) {
+          files.push(path.join(repo, f).replace(/\\/g, '/'));
+        }
+      }
+      return [...new Set(files)];
+    }
+  }
+
+  // 单仓模式 / 兜底：直接对 projectRoot 做 diff
+  return gitDiff(projectRoot);
+}
+
+/**
+ * 获取报告生成时间：优先用 JSON 中的 generatedAt，降级用文件 mtime
+ */
+function getReportTime(jsonPath) {
+  try {
+    const data = JSON.parse(fs.readFileSync(jsonPath, 'utf8'));
+    if (data.generatedAt) {
+      const t = new Date(data.generatedAt).getTime();
+      if (!isNaN(t)) return t;
+    }
+  } catch {}
+  // 降级：用文件 mtime
+  return fs.statSync(jsonPath).mtimeMs;
+}
+
+function isReportStale(specRoot, changeName, modifiedFiles, projectRoot) {
+  const jsonPath = findReport(specRoot, changeName, 'json');
+  if (!jsonPath) return false;
+
+  const reportTime = getReportTime(jsonPath);
+
+  // 排除报告文件本身
+  const reportFiles = [
+    'consistency-report.md',
+    'consistency-report-self-review.md',
+    'consistency-report-result.json',
+    'consistency-report-self-review-result.json',
+  ];
+
+  return modifiedFiles.some(file => {
+    if (reportFiles.includes(path.basename(file))) return false;
+    const fp = path.join(projectRoot, file);
+    return fs.existsSync(fp) && fs.statSync(fp).mtimeMs > reportTime;
+  });
+}
+
+// --- 提示信息 ---
+
+function generateInstructions(missing, stale, needsConfirmation, warnOnly) {
+  const lines = ['', '=========================================='];
+  const needsRegenerate = [...new Set([...missing, ...stale])];
+
+  if (warnOnly) {
+    lines.push('[SDD push-consistency-check] ⚠️  仅告警模式（SDD_WARN_ONLY=1），以下问题不会阻止推送：');
+  } else {
+    lines.push('[SDD push-consistency-check] 以下变更存在问题，拒绝推送：');
+  }
+
+  lines.push('');
+
+  if (missing.length) {
+    lines.push('  缺少一致性报告：');
+    missing.forEach(c => lines.push(`    - ${c}`));
+  }
+
+  if (stale.length) {
+    lines.push('  报告已过期（代码在报告生成后被修改）：');
+    stale.forEach(c => lines.push(`    - ${c}`));
+  }
+
+  if (needsConfirmation.length) {
+    lines.push('  自审模式需人工确认：');
+    needsConfirmation.forEach(c => lines.push(`    - ${c}`));
+  }
+
+  // 只有需要重新生成报告时才显示 skill 执行建议
+  if (needsRegenerate.length > 0) {
+    lines.push('');
+    lines.push(warnOnly
+      ? '建议执行 opsx-consistency-check skill 更新报告：'
+      : '请执行 opsx-consistency-check skill 更新报告后再推送：');
+    lines.push('');
+
+    if (needsRegenerate.length === 1) {
+      lines.push(`  skill: opsx-consistency-check ${needsRegenerate[0]}`);
+    } else {
+      lines.push('  skill（逐个执行）：');
+      needsRegenerate.forEach(c => lines.push(`    opsx-consistency-check ${c}`));
+    }
+
+    lines.push(
+      '',
+      '  💡 建议：新开对话窗口执行校验，以获得独立、客观的审核结果',
+    );
+  }
+
+  // 自审模式人工确认指引
+  if (needsConfirmation.length > 0) {
+    lines.push('');
+    lines.push('  人工确认步骤：');
+    lines.push('  1. 打开 consistency-report-self-review.md，找到「人工确认（自审模式）」章节');
+    lines.push('  2. 逐条核对断言，在「人工确认」列填写 ✅ 已确认 或 ❌ 有误');
+    lines.push('  3. 确认无误后，编辑 consistency-report-self-review-result.json，将 humanConfirmed 从 false 改为 true');
+    lines.push('');
+    lines.push('  报告路径: openspec/changes/<change-name>/consistency-report-self-review.md');
+    lines.push('  JSON 路径: openspec/changes/<change-name>/consistency-report-self-review-result.json');
+  }
+
+  // 如果没有需要重新生成的报告，但有其他问题，显示默认报告路径
+  if (needsRegenerate.length > 0 && needsConfirmation.length === 0) {
+    lines.push(
+      '',
+      '  报告路径: openspec/changes/<change-name>/consistency-report.md',
+      '  JSON 路径: openspec/changes/<change-name>/consistency-report-result.json',
+    );
+  }
+
+  lines.push('==========================================', '');
+
+  return lines.join('\n');
+}
+
+// --- 主流程 ---
+
 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 looseMode = hasFlag('no-strict') || process.env.SDD_LOOSE_CONSISTENCY === '1';
 
-  const specRoot = resolveSpecRoot(projectRoot);
-  if (!specRoot) {
-    console.log('SDD consistency-check (pre-push): 未找到 spec 仓库，跳过一致性校验');
-    return;
+  const skip = process.env.SDD_SKIP_CONSISTENCY_CHECK === '1';
+  const warnOnly = process.env.SDD_WARN_ONLY === '1';
+
+  // 互斥检查
+  if (skip && warnOnly) {
+    console.error('[SDD push-consistency-check] 错误：SDD_SKIP_CONSISTENCY_CHECK 与 SDD_WARN_ONLY 互斥，只能启用一个');
+    process.exit(1);
+  }
+
+  if (skip) {
+    console.log('[SDD push-consistency-check] 跳过校验');
+    process.exit(0);
+  }
+
+  if (warnOnly) console.log('[SDD push-consistency-check] 仅告警模式');
+
+  const specRoot = resolveSpecRoot();
+
+  // 优先尝试按本次 push 范围收敛变更
+  let changes = discoverChangesFromPushFiles(projectRoot, specRoot);
+  let modifiedFiles = null;
+
+  if (changes === null) {
+    // 降级：stdin 读取失败，回退到现有行为
+    console.log('[SDD push-consistency-check] 无法读取 push 范围，降级为全量检查');
+    changes = discoverActiveChanges(specRoot);
+    modifiedFiles = getModifiedFiles(projectRoot);
+  } else if (changes.length === 0) {
+    console.log('[SDD push-consistency-check] 无相关活跃变更，跳过');
+    process.exit(0);
+  } else {
+    // 收敛成功：用 push 范围文件做过期判定
+    modifiedFiles = getPushRangeFiles(projectRoot) || [];
   }
 
-  const changes = discoverActiveChanges(specRoot, explicitChange);
-  if (changes.length === 0) {
-    console.log('SDD consistency-check (pre-push): 无活跃变更，跳过一致性校验');
-    return;
+  if (!changes.length) {
+    console.log('[SDD push-consistency-check] 无活跃变更，跳过');
+    process.exit(0);
   }
 
-  const blockers = [];
   const missing = [];
-  const passed = [];
+  const stale = [];
+  const needsConfirmation = [];
 
-  for (const changeName of changes) {
-    const reportPath = findConsistencyReport(specRoot, changeName);
-    if (!reportPath) {
-      missing.push(changeName);
+  for (const cn of changes) {
+    const rp = findReport(specRoot, cn, 'json');
+    if (!rp) {
+      missing.push(cn);
       continue;
     }
 
-    const report = parseReport(reportPath);
-    if (report.parseError) {
-      console.warn(`SDD consistency-check (pre-push): ⚠️  ${changeName} 报告解析失败: ${report.parseError}`);
-      missing.push(changeName);
+    // 检查是否存在两种模式的报告
+    if (rp.error === 'duplicate') {
+      console.warn(`[SDD push-consistency-check] ⚠️  ${cn} 存在两种模式的报告，请删除其中一个：`);
+      rp.paths.forEach(p => console.warn(`    - ${p}`));
+      missing.push(cn);
       continue;
     }
 
-    if (report.confidence === 'low' || report.overallResult === 'fail') {
-      blockers.push({ changeName, report });
-    } else {
-      passed.push({ changeName, report });
+    const report = parseReport(rp);
+    if (report.parseError) {
+      console.warn(`[SDD push-consistency-check] ⚠️  ${cn}: 报告解析失败`);
+      missing.push(cn);
+      continue;
     }
-  }
 
-  // 输出摘要
-  if (passed.length > 0) {
-    for (const item of passed) {
-      console.log(`SDD consistency-check (pre-push): ✅ ${item.changeName} 置信度=${item.report.confidence}`);
+    if (isReportStale(specRoot, cn, modifiedFiles, projectRoot)) {
+      console.log(`[SDD push-consistency-check] ⚠️  ${cn}: 报告已过期`);
+      stale.push(cn);
+      continue;
     }
-  }
 
-  if (missing.length > 0) {
-    console.warn(`SDD consistency-check (pre-push): ⚠️  以下变更缺少一致性校验报告:`);
-    for (const name of missing) {
-      console.warn(`  - ${name}`);
-    }
-    if (strictMode && !looseMode) {
-      console.error('SDD consistency-check (pre-push): ❌ strict 模式已启用，缺少报告的变更不允许推送。');
-      console.error('请先执行 opsx-consistency-check 生成报告，或使用 --no-verify 跳过（不推荐）。');
-      process.exit(1);
+    // 自审模式需要人工确认
+    if (report.reviewMode === 'self-review' && !report.humanConfirmed) {
+      console.log(`[SDD push-consistency-check] ⚠️  ${cn}: 自审模式需人工确认`);
+      needsConfirmation.push(cn);
+      continue;
     }
-    console.warn('  → 推送已放行，建议尽快执行 opsx-consistency-check');
+
+    console.log(`[SDD push-consistency-check] ✅ ${cn}: 报告有效`);
   }
 
-  if (blockers.length > 0) {
-    console.error(`SDD consistency-check (pre-push): ❌ 以下变更的一致性校验未通过（confidence=low），阻止推送:`);
-    for (const item of blockers) {
-      console.error(`  - ${item.changeName} (confidence=${item.report.confidence}, result=${item.report.overallResult})`);
-      console.error(`    报告路径: ${item.report.reportPath}`);
+  if (missing.length || stale.length || needsConfirmation.length) {
+    console.log(generateInstructions(missing, stale, needsConfirmation, warnOnly));
+
+    if (warnOnly) {
+      console.log('[SDD push-consistency-check] 仅告警模式，放行推送');
+      process.exit(0);
     }
-    console.error('');
-    console.error('请修复不一致项后重新执行 opsx-consistency-check，或使用 --no-verify 跳过（不推荐）。');
+
     process.exit(1);
   }
+
+  console.log('\n[SDD push-consistency-check] ✅ 所有变更均已通过一致性校验，放行推送');
+  process.exit(0);
 }
 
 main();

package/templates/skills/kld-sdd/opsx-check/SKILL.md

@@ -4,10 +4,10 @@ description: "质量检查技能 - 验证文档完整性、一致性、算法正
 argument-hint: "[change-name] [上下文文件...]"
 license: MIT
 compatibility: Requires openspec CLI; depends on opsx-ontology-query for external-key validation and baseline checks.
-  depends-on: opsx-ontology-query
 metadata:
   author: sdd-team
   version: "3.0"
+  depends-on: opsx-ontology-query
 allowed-tools:
   - Bash
   - Read