kld-sdd 2.7.8-2 → 2.7.8-3

package/templates/git-hooks/consistency-check-core.cjs

@@ -1,26 +1,10 @@
 #!/usr/bin/env node
 'use strict';
 
-/**
- * consistency-check-core.cjs
- *
- * pre-commit / pre-push 一致性校验 hook 的共享核心（非独立插件，不在 hooks.config 中登记）。
- * 两个入口脚本通过 require 引用本模块，注入各自差异配置：
- * - diff 采集方式（pre-commit: git diff HEAD；pre-push: 待推送范围 @{push}..HEAD）
- * - 是否检查置信度（pre-commit 检查；pre-push 轻量跳过）
- * - strict 模式（仅 pre-commit 支持 SDD_STRICT_CONSISTENCY）
- * - 过期比对来源（pre-commit: 工作区内容；pre-push: HEAD 已提交内容，staleFromHead）
- * - 提示文案（提交 / 推送）
- *
- * 核心行为（简化版）：
- * - diff 驱动：仅检查 diff 文件与报告 coveredFiles 有交集的 change，无关 change 跳过
- * - 多仓归属过滤：报告 repositories 已声明覆盖仓库且不含当前仓的 change 静默跳过（不输出、不拦截）
- * - 纯注释/空行/空格变更过滤：diff 中所有变更行均为注释/空行/空格的文件直接跳过，不参与校验
- * - 报告存在性：活跃 change 无报告 → 阻止
- * - 报告过期：diff 业务代码与 coveredFiles 交集文件内容变化（size 短路 + SHA-256）→ 阻止
- * - 置信度门禁（仅 pre-commit）：low → 阻止；strict 时 medium 也阻止
- * - 无活跃 change 但 diff 有业务代码 → 阻止（提示先执行 opsx-propose）
- * - 变更范围采集失败 → 阻止（避免静默放行的 fail-open）
+/** Shared collection utilities and the optional strict index entry.
+ * Delivery readiness uses delivery-check.cjs receipts with complete input fingerprints.
+ * Legacy JSON parsing helpers remain available for readers; old confidence-only reports
+ * cannot satisfy the strict entry. Daily commit/push do not call this module by default.
  */
 
 const fs = require('fs');
@@ -105,7 +89,7 @@ function parseReport(reportPath) {
         : raw;
       const t = new Date(normalized.replace(/-/g, '/')).getTime();
       if (!isNaN(t)) {
-        generatedAtMs = t + 1000;
+        generatedAtMs = t;
       } else {
         generatedAtFormatError = `generatedAt 无法解析（实际: ${raw}，应为 YYYY-MM-DD HH:mm:ss 本地时间）`;
       }
@@ -417,8 +401,7 @@ function getModifiedFiles(projectRoot, diffFn, options = {}) {
 /**
  * 解析 INI 风格的 [consistency] 段，返回段内所有 key=value。
  */
-function parseConsistencySection() {
-  const configPath = path.join(__dirname, 'hooks.config');
+function parseConsistencySection(configPath = path.join(__dirname, 'hooks.config')) {
   const values = {};
   try {
     const content = fs.readFileSync(configPath, 'utf8');
@@ -448,8 +431,8 @@ const CONSISTENCY_CONFIG = parseConsistencySection();
  * 业务代码扩展名白名单（business_code_exts，唯一来源为 hooks.config，无内置默认值）。
  * @returns {{exts: Set<string>, source: 'config'|'missing'|'empty', configPath: string|null}}
  */
-function loadBusinessCodeExts() {
-  const { configPath, values } = CONSISTENCY_CONFIG;
+function loadBusinessCodeExts(file) {
+  const { configPath, values } = file ? parseConsistencySection(file) : CONSISTENCY_CONFIG;
   const rawValue = Object.prototype.hasOwnProperty.call(values, 'business_code_exts')
     ? values.business_code_exts : null;
 
@@ -490,14 +473,14 @@ const CONSISTENCY_MODE = loadConsistencyMode();
 const TOOLCHAIN_CONFIG_RE = /^(?:vite|vitest|next|nuxt|astro|svelte|remix|webpack|rollup|babel|jest|playwright|cypress|eslint|prettier|tailwind|postcss|karma|wrangler|nest-cli|angular|vue|craco|rspack|metro|tsconfig|jsconfig|turbo|nx)\.(?:config|conf)\.[a-z]+$/i;
 const DOTFILE_CONFIG_RE = /^\.?(?:eslintrc|babelrc|prettierrc|stylelintrc)\.[a-z]+$/i;
 
-function isBusinessCode(file) {
+function isBusinessCode(file, exts = BUSINESS_CODE_EXTS) {
   const normalized = String(file).replace(/\\/g, '/');
   const base = normalized.split('/').pop() || '';
 
   const dot = base.lastIndexOf('.');
   if (dot < 0) return false;
   const ext = base.slice(dot).toLowerCase();
-  if (!BUSINESS_CODE_EXTS.has(ext)) return false;
+  if (!(exts instanceof Set ? exts : BUSINESS_CODE_EXTS).has(ext)) return false;
 
   if (/\.d\.tsx?$/i.test(base)) return false;
   if (/(^|\/)(dist|build|target|out|node_modules)\//.test(normalized)) return false;
@@ -634,25 +617,12 @@ function normalizeEolLf(buf) {
   return Buffer.from(str.replace(/\r\n/g, '\n'), 'binary');
 }
 
-/**
- * 单文件过期判断（mtime 快速跳过 + size 短路 + SHA-256，行尾归一化）。
- * mtime 快速路径：文件修改时间早于报告生成时间 → 报告生成后从未被碰过 → 内容必然未变，
- * 跳过读取和哈希（大变更场景省 100-300ms/百文件）。mtime 晚于报告时间才做精确哈希判断，
- * 因此 git pull/checkout 重置 mtime（内容未变）只会多算一次哈希，不会误判过期。
- */
+/** 内容哈希是有效性依据，mtime 不参与正确性判断。 */
 function isFileChangedOnDisk(fp, metas, reportTime, readContent = readWorkingFile, relFile = '') {
   const list = Array.isArray(metas) ? metas : (metas ? [metas] : []);
   const hashed = list.filter(m => m && m.sha256);
 
   if (hashed.length) {
-    // mtime 快速跳过：仅在能拿到本地文件时（readContent 为工作区读取）且 mtime 可信时启用
-    if (readContent === readWorkingFile) {
-      try {
-        if (fs.statSync(fp).mtimeMs <= reportTime) return false;
-      } catch {
-        return true; // 文件不存在 → 过期
-      }
-    }
     const content = readContent(fp, relFile);
     if (content === null) return true;
     const normalized = normalizeEolLf(content);
@@ -663,14 +633,8 @@ function isFileChangedOnDisk(fp, metas, reportTime, readContent = readWorkingFil
     return !candidates.some(m => hash === String(m.sha256).toLowerCase());
   }
 
-  // 无哈希条目：mtime 比较
-  let stat;
-  try {
-    stat = fs.statSync(fp);
-  } catch {
-    return true;
-  }
-  return stat.mtimeMs > reportTime;
+  // mtime cannot prove content equality. Legacy entries without hashes need review.
+  return true;
 }
 
 /**
@@ -773,205 +737,62 @@ function generateInstructions(opts, result, warnOnly) {
  * @param {object} opts 入口差异配置
  */
 function runConsistencyCheck(opts) {
-  const {
-    label, actionNoun, diffFn,
-    checkConfidence = false, includeUntracked = true,
-    staleFromHead = false,
-  } = opts;
+  const { label, actionNoun, diffFn, includeUntracked = false, staleFromHead = false, staleFromIndex = false } = opts;
   const projectRoot = path.resolve(readArg('project') || process.env.SDD_PROJECT || process.cwd());
-
-  // 模式解析
-  const envSkip = process.env.SDD_SKIP_CONSISTENCY_CHECK;
-  const envStrict = process.env.SDD_STRICT_CONSISTENCY;
-  const envWarnOnly = process.env.SDD_WARN_ONLY;
-  const skip = envSkip !== undefined ? envSkip === '1' : CONSISTENCY_MODE.skip;
-  const strict = envStrict !== undefined ? envStrict === '1' : CONSISTENCY_MODE.strict;
-  const warnOnly = envWarnOnly !== undefined ? envWarnOnly === '1' : CONSISTENCY_MODE.warnOnly;
-
-  // 互斥检查
-  const activeModes = [skip, strict, warnOnly].filter(Boolean).length;
-  if (activeModes > 1) {
-    const names = [
-      ...(skip ? ['SDD_SKIP_CONSISTENCY_CHECK' + (envSkip === undefined ? '(hooks.config)' : '')] : []),
-      ...(strict ? ['SDD_STRICT_CONSISTENCY' + (envStrict === undefined ? '(hooks.config)' : '')] : []),
-      ...(warnOnly ? ['SDD_WARN_ONLY' + (envWarnOnly === undefined ? '(hooks.config)' : '')] : []),
-    ];
-    console.error(`${label} 错误：${names.join('、')} 互斥，只能启用一个`);
-    process.exit(1);
-  }
-
-  if (skip) {
-    console.log(`${label} 跳过校验`);
-    process.exit(0);
-  }
-
-  if (warnOnly) console.log(`${label} 仅告警模式`);
-
-  // 配置缺失/空清单显式告警
-  if (BUSINESS_CODE_EXTS_INFO.source !== 'config') {
-    const reason = BUSINESS_CODE_EXTS_INFO.source === 'missing'
-      ? '未配置 business_code_exts（hooks.config 缺失或无 [consistency] 段）'
-      : 'business_code_exts 为空清单';
-    console.warn(`${label} ⚠️  ${reason}，一致性校验不拦截任何业务代码文件（仅保留报告存在性/过期检查）`);
-    console.warn(`${label} ℹ️  请在 ${BUSINESS_CODE_EXTS_INFO.configPath || path.join(__dirname, 'hooks.config')} 的 [consistency] 段配置 business_code_exts`);
-  }
-
-  const specRoot = resolveSpecRoot();
-
-  // 1. 采集 diff 文件
-  const { files: modifiedFiles, deleted: deletedFiles, failed: diffFailed } =
-    getModifiedFiles(projectRoot, diffFn, { includeUntracked });
-
-  if (diffFailed) {
-    console.log(`${label} ❌ 无法确定本次${actionNoun}的变更范围（git diff 采集失败），拒绝${actionNoun}`);
-    if (warnOnly) {
-      console.log(`${label} 仅告警模式，放行${actionNoun}`);
-      process.exit(0);
-    }
+  const mode = loadConsistencyMode();
+  const skip = process.env.SDD_SKIP_CONSISTENCY_CHECK === undefined ? mode.skip : process.env.SDD_SKIP_CONSISTENCY_CHECK === '1';
+  const strict = process.env.SDD_STRICT_CONSISTENCY === undefined ? mode.strict : process.env.SDD_STRICT_CONSISTENCY === '1';
+  const warnOnly = process.env.SDD_WARN_ONLY === undefined ? mode.warnOnly : process.env.SDD_WARN_ONLY === '1';
+  if ([skip, strict, warnOnly].filter(Boolean).length > 1) {
+    console.error(`${label} skip / strict / warn_only 互斥`);
     process.exit(1);
   }
-
-  // 2. 筛选业务代码文件
-  const diffBusinessFiles = modifiedFiles.filter(isBusinessCode);
-  const deletedBusinessFiles = deletedFiles.filter(isBusinessCode);
-
-  // 3. 无业务代码文件 → 放行
-  if (diffBusinessFiles.length === 0 && deletedBusinessFiles.length === 0) {
+  if (skip) { console.log(`${label} 跳过校验`); process.exit(0); }
+  const problems = [];
+  const { files, deleted, failed } = getModifiedFiles(projectRoot, diffFn, { includeUntracked });
+  if (failed) problems.push('无法确定变更范围');
+  if (BUSINESS_CODE_EXTS_INFO.source !== 'config') problems.push('business_code_exts 未配置，不能证明检查完整');
+  const required = [...new Set([...files, ...deleted])].filter(isBusinessCode);
+  if (!problems.length && !required.length) {
     console.log(`${label} 本次${actionNoun}无业务代码文件，跳过一致性校验`);
     process.exit(0);
   }
-
-  // 4. 活跃 change 发现
-  const changes = discoverActiveChanges(specRoot);
-  if (!changes.length) {
-    console.log([
-      '', '==========================================',
-      `${label} 存在业务代码变更但无活跃 change 可归属，拒绝${actionNoun}：`,
-      '',
-      '  请先执行 opsx-propose 创建变更（登记到 sdd.config.yaml 的 active_changes），',
-      '  再执行 opsx-consistency-check 生成一致性报告。',
-      '==========================================', '',
-    ].join('\n'));
-    if (warnOnly) {
-      console.log(`${label} 仅告警模式，放行${actionNoun}`);
-      process.exit(0);
-    }
-    process.exit(1);
-  }
-
-  // 5. 逐 change 解析报告
-  const parseError = [];
-  const invalid = [];
-  const lowConfidence = [];
-  const stale = [];
-  const missing = [];
-  const parsedReports = new Map();
-
-  // 当前代码仓目录名（多仓布局下用于报告归属过滤 + normalizeCoveredFiles 兜底前缀剥离）
-  const currentRepoName = path.basename(projectRoot).toLowerCase();
-
-  for (const cn of changes) {
-    const rp = findReportJson(specRoot, cn);
-    if (!rp) {
-      missing.push(cn);
-      continue;
-    }
-
-    const report = parseReport(rp);
-    if (report.parseError) {
-      console.warn(`${label} ⚠️  ${cn} 报告解析失败`);
-      parseError.push(cn);
-      continue;
-    }
-
-    // 旧格式报告（无 coveredFiles）
-    if (!report.coveredFiles) {
-      console.log(`${label} ⚠️  ${cn}: 报告为旧格式（缺少 coveredFiles），建议重新生成`);
-      missing.push(cn);
-      continue;
-    }
-
-    // 字段合法性校验（仅 confidence + generatedAt）
-    const fieldErrors = validateReportFields(report);
-    if (fieldErrors.length) {
-      console.warn(`${label} ⚠️  ${cn} 报告字段不合法：${fieldErrors.join('；')}`);
-      invalid.push({ cn, errors: fieldErrors });
-      continue;
-    }
-
-    const covered = normalizeCoveredFiles(report, currentRepoName);
-    parsedReports.set(cn, { report, covered });
-  }
-
-  // 6. 对 diff（含删除）与 coveredFiles 有交集的 change 检查报告
-  const checkFiles = [...new Set([...diffBusinessFiles, ...deletedBusinessFiles])];
-  const checkFilesLower = checkFiles.map(f => f.toLowerCase());
-
-  let headContentCache = null;
-  const readContent = staleFromHead
-    ? (fp, relFile) => {
-        if (headContentCache === null) {
-          headContentCache = gitShowHeadContentBatch(projectRoot, checkFiles);
-        }
-        const fromHead = headContentCache.get(relFile);
-        return fromHead !== undefined && fromHead !== null ? fromHead : readWorkingFile(fp);
-      }
-    : readWorkingFile;
-
-  for (const [cn, { report, covered }] of parsedReports) {
-    // 多仓归属过滤：报告显式声明了覆盖仓库且不含当前仓 → 与本仓无关，静默跳过
-    // （repositories 为空视为未声明，保持原交集判断行为，兼容单仓与旧报告）
-    const declaredRepos = (report.repositories || [])
-      .map(r => String(r && r.path || '').replace(/\\/g, '/').replace(/\/+$/, '').toLowerCase())
-      .filter(Boolean);
-    if (declaredRepos.length && !declaredRepos.includes(currentRepoName)) {
-      continue;
-    }
-
-    const hasIntersection = checkFilesLower.some(f => covered.has(f));
-    if (!hasIntersection) {
-      console.log(`${label} ⏭️  ${cn}: 与本次${actionNoun}无交集，跳过`);
-      continue;
-    }
-
-    if (isReportStale(report, covered, checkFiles, projectRoot, readContent)) {
-      console.log(`${label} ⚠️  ${cn}: 报告已过期`);
-      stale.push(cn);
-      continue;
-    }
-
-    if (checkConfidence) {
-      const c = report.confidence;
-      if (c === 'low' || (c === 'medium' && strict)) {
-        console.log(`${label} ❌ ${cn}: 置信度 ${c}`);
-        lowConfidence.push(cn);
+  const delivery = require('./delivery-check.cjs');
+  const snap = require('./delivery-snapshot.cjs');
+  const specRoot = resolveSpecRoot();
+  const explicit = String(readArg('change') || process.env.KLD_SDD_CHANGE || '').split(/[,\s]+/).filter(Boolean);
+  const changes = explicit.length ? explicit : discoverActiveChanges(specRoot);
+  const covered = new Set();
+  for (const change of changes) {
+    try {
+      const identity = snap.repoIdentity(projectRoot);
+      const rp = delivery.reviewPath({ specRoot, change, identity });
+      if (!fs.existsSync(rp)) {
+        // Unrelated active changes do not require a report for this commit.
+        if (explicit.includes(change)) problems.push(`${change}: 缺少一致性检查回执，请运行 opsx-consistency-check`);
         continue;
       }
-      console.log(`${label} ✅ ${cn}: 置信度 ${c}`);
-    } else {
-      console.log(`${label} ✅ ${cn}: 报告有效`);
-    }
-  }
-
-  const result = {
-    missing, parseError, invalid, lowConfidence, stale,
-  };
-
-  const hasBlocking = missing.length || parseError.length || invalid.length || lowConfidence.length
-    || stale.length;
-
-  if (hasBlocking) {
-    console.log(generateInstructions(opts, result, warnOnly));
-
-    if (warnOnly) {
-      console.log(`${label} 仅告警模式，放行${actionNoun}`);
-      process.exit(0);
-    }
-
-    process.exit(1);
-  }
-
-  console.log(`\n${label} ✅ 本次${actionNoun}涉及的业务代码均已通过一致性校验，放行${actionNoun}`);
+      const report = JSON.parse(fs.readFileSync(rp, 'utf8'));
+      if (!explicit.includes(change) && !required.some(f => (report.reviewedFiles || []).includes(f))) continue;
+      const ctx = delivery.context({ project: projectRoot, 'spec-root': specRoot, change,
+        scope: staleFromHead ? 'commit' : staleFromIndex ? 'index' : 'worktree',
+        base: opts.base || report.base, ref: opts.ref || 'HEAD', 'spec-ref': opts.specRef });
+      // This report need only cover its own files; union coverage is asserted below.
+      ctx.required = required.filter(f => (report.reviewedFiles || []).includes(f));
+      const errors = delivery.reviewErrors(ctx, report);
+      if (errors.length) problems.push(`${change}: 报告过期或未完成：${errors.join('；')}`);
+      else for (const file of ctx.required) covered.add(file);
+    } catch (error) { problems.push(`${change}: ${error.message}`); }
+  }
+  const uncovered = required.filter(file => !covered.has(file));
+  if (uncovered.length) problems.push(`缺少有效检查覆盖（UNCOVERED_FILES）：${uncovered.join(', ')}`);
+  if (problems.length) {
+    console.log(`${label} 未通过：\n${problems.map(p => `  - ${p}`).join('\n')}`);
+    console.log('请由 opsx-consistency-check 更新回执；日常提交默认不运行此严格入口。');
+    if (warnOnly) console.log(`${label} 仅告警模式，放行${actionNoun}（不代表已通过检查）`);
+    process.exit(warnOnly ? 0 : 1);
+  }
+  console.log(`${label} 本次${actionNoun}涉及的业务代码均已通过一致性校验`);
   process.exit(0);
 }
 

package/templates/git-hooks/delivery-check.cjs

@@ -0,0 +1,231 @@
+#!/usr/bin/env node
+'use strict';
+
+// Deterministic evidence checking. This command never performs or invents an AI review.
+const fs = require('fs');
+const path = require('path');
+const snap = require('./delivery-snapshot.cjs');
+const DIMENSIONS = ['interfaceContract', 'businessRules', 'validationRules', 'errorCodes'];
+
+function readJson(file) { return JSON.parse(fs.readFileSync(file, 'utf8')); }
+function optionalJson(file) { try { return readJson(file); } catch { return null; } }
+
+function context(args) {
+  const project = fs.realpathSync(path.resolve(args.project || process.cwd()));
+  const specRoot = fs.realpathSync(path.resolve(args['spec-root'] || path.join(__dirname, '..', '..')));
+  const projectTop = fs.realpathSync(snap.git(project, ['rev-parse', '--show-toplevel']).trim());
+  if (projectTop !== project) throw new Error('PROJECT_ROOT_REQUIRED: --project 请指定代码仓 Git 根');
+  const change = args.change;
+  if (!change || !/^[a-z0-9][a-z0-9-]+$/.test(change)) throw new Error('CHANGE_REQUIRED: --change 必须明确指定');
+  const scope = args.scope || 'worktree';
+  const ref = args.ref || 'HEAD';
+  const identity = snap.repoIdentity(project);
+  const key = snap.hashJson({ identity, change });
+  const dir = path.join(specRoot, 'skywalk-sdd/state/delivery', key);
+  const prepared = optionalJson(path.join(dir, 'prepared.json'));
+  let base = args.base || prepared?.base;
+  if (scope === 'commit' && !args.base) throw new Error('BASE_REQUIRED: --scope=commit 必须明确提供 --base');
+  if (!base) {
+    try { base = snap.git(project, ['rev-parse', '--verify', 'HEAD']).trim(); }
+    catch { base = snap.git(project, ['mktree'], { input: '' }).trim(); }
+  }
+  base = snap.git(project, ['rev-parse', '--verify', '--end-of-options', `${base}^{object}`]).trim();
+  const baseType = snap.git(project, ['cat-file', '-t', base]).trim();
+  if (!['tree', 'commit'].includes(baseType)) throw new Error('BASE_INVALID');
+  // Freeze named refs before reading any files, including a CI target that is not HEAD.
+  const resolvedRef = scope === 'commit' ? snap.git(project, ['rev-parse', '--verify', '--end-of-options', `${ref}^{commit}`]).trim() : ref;
+  const relative = path.relative(project, specRoot);
+  let specRepository = `local:${specRoot}`, specTop = '';
+  try { specTop = fs.realpathSync(snap.git(specRoot, ['rev-parse', '--show-toplevel']).trim()); specRepository = snap.repoIdentity(specTop); } catch { /* uncommitted standalone Spec folder */ }
+  const mono = specTop === project;
+  if (!mono && fs.existsSync(path.join(project, '.sdd.yaml'))) {
+    const configModule = [path.join(__dirname, '../ontology/sdd-config.cjs'), path.join(__dirname, '../../skywalk-sdd/ontology/sdd-config.cjs')].find(fs.existsSync);
+    if (!configModule) throw new Error('SDD_CONFIG_RUNTIME_MISSING');
+    const sdd = require(configModule);
+    const declared = sdd.loadSddYaml(project);
+    if (!declared.ok) throw new Error('SDD_CONFIG_INVALID');
+    const actual = snap.git(specRoot, ['remote', 'get-url', 'origin']).trim();
+    if (!sdd.remotesMatch(declared.spec_repository, actual)) throw new Error('SPEC_REMOTE_MISMATCH');
+  }
+  let specOptions = {};
+  if (scope !== 'worktree') {
+    if (mono) specOptions = { root: project, scope, ref: resolvedRef };
+    else {
+      if (scope === 'commit' && !args['spec-ref']) throw new Error('SPEC_REF_REQUIRED: 多仓提交校验必须提供 --spec-ref 的完整提交 SHA');
+      const specRef = args['spec-ref'] || 'HEAD';
+      if (scope === 'commit' && !/^[a-f0-9]{40}$|^[a-f0-9]{64}$/.test(specRef)) throw new Error('SPEC_REF_INVALID: 需要完整 SHA');
+      specOptions = { root: specRoot, scope: 'commit', ref: specRef };
+    }
+  }
+  const code = snap.codeSnapshot(project, specRoot, scope, resolvedRef);
+  const spec = snap.specSnapshot(specRoot, change, specOptions);
+  const core = require('./consistency-check-core.cjs');
+  const configFile = path.join(specRoot, 'skywalk-sdd/git-hooks/hooks.config');
+  const config = core.loadBusinessCodeExts(configFile);
+  if (config.source !== 'config') throw new Error('BUSINESS_SCOPE_UNCONFIGURED: hooks.config 缺少业务文件扩展名');
+  const inputs = { ruleVersion: snap.RULE_VERSION, ruleConfig: snap.fileMeta('hooks.config', fs.readFileSync(configFile)).sha256, repository: identity, specRepository, change, code, spec };
+  const fingerprint = snap.hashJson(inputs);
+  const required = snap.changedFiles(project, scope, base, resolvedRef).filter(file => core.isBusinessCode(file, config.exts) && !snap.excluded(file, relative.startsWith('..') ? '' : relative.replace(/\\/g, '/')));
+  return { project, specRoot, change, scope, ref: resolvedRef, mono, identity, dir, base, inputs, fingerprint, required };
+}
+
+function reviewPath(ctx) {
+  return path.join(ctx.specRoot, 'openspec/changes', ctx.change, 'consistency-reviews', `${snap.digest(ctx.identity)}.json`);
+}
+
+function reviewErrors(ctx, review) {
+  if (!review) return ['REVIEW_MISSING: 缺少代码与 Spec 一致性检查回执'];
+  const errors = [];
+  if (review.inputFingerprint !== ctx.fingerprint || !review.inputs || snap.hashJson(review.inputs) !== ctx.fingerprint) errors.push('REVIEW_STALE: 代码、Spec、依赖或规则版本已变化');
+  const covered = new Set(Array.isArray(review.reviewedFiles) ? review.reviewedFiles : []);
+  const uncovered = ctx.required.filter(file => !covered.has(file));
+  if (uncovered.length) errors.push(`UNCOVERED_FILES: ${uncovered.join(', ')}`);
+  for (const name of DIMENSIONS) {
+    const item = review.dimensions?.[name];
+    if (!item || !['pass', 'na'].includes(item.status)) errors.push(`REVIEW_INCOMPLETE: ${name}=${item?.status || 'not_checked'}`);
+    else if (item.status === 'na' && !String(item.reason || '').trim()) errors.push(`NA_REASON_REQUIRED: ${name}`);
+    else if (item.status === 'pass' && (!Array.isArray(item.evidence) || !item.evidence.length || item.evidence.some(e => typeof e !== 'string' || !e.trim()))) errors.push(`EVIDENCE_REQUIRED: ${name}`);
+  }
+  if (review.issues != null && !Array.isArray(review.issues)) errors.push('REVIEW_ISSUES_INVALID');
+  if (Array.isArray(review.issues) && review.issues.length) errors.push('REVIEW_ISSUES: 存在未解决问题');
+  return errors;
+}
+
+function saveAssociation(ctx, review) {
+  const file = path.join(ctx.specRoot, 'skywalk-sdd/state/delivery-associations', `${snap.digest(ctx.identity)}.json`);
+  const previous = optionalJson(file) || { repository: ctx.identity, changes: {} };
+  const byPath = new Map(ctx.inputs.code.map(f => [f.path, f]));
+  previous.changes[ctx.change] = {
+    coveredFiles: review.reviewedFiles.map(file => byPath.get(file) || { path: file, deleted: true }),
+  };
+  snap.atomicJson(file, previous);
+}
+
+function prepare(args) {
+  const ctx = context(args);
+  const old = optionalJson(reviewPath(ctx));
+  const errors = reviewErrors(ctx, old);
+  const value = {
+    base: ctx.base, inputFingerprint: ctx.fingerprint, inputs: ctx.inputs,
+    requiredFiles: ctx.required, scope: ctx.scope, ref: ctx.ref,
+  };
+  const file = path.join(ctx.dir, 'prepared.json');
+  snap.atomicJson(file, value);
+  return { ...value, preparedFile: file, reviewFile: reviewPath(ctx), reuseReview: errors.length === 0, reviewErrors: errors };
+}
+
+function recordReview(args) {
+  const ctx = context(args);
+  const prepared = readJson(path.join(ctx.dir, 'prepared.json'));
+  const input = readJson(args.input);
+  if (prepared.inputFingerprint !== ctx.fingerprint || input.inputFingerprint !== ctx.fingerprint) throw new Error('REVIEW_STALE: 取证后输入已改变；重新 prepare 并复核变化');
+  if (!Array.isArray(input.reviewedFiles) || input.reviewedFiles.some(f => typeof f !== 'string')) throw new Error('REVIEW_FILES_REQUIRED');
+  const allowed = new Set([...ctx.inputs.code.map(f => f.path), ...ctx.required]);
+  if (input.reviewedFiles.some(f => !allowed.has(f))) throw new Error('REVIEW_FILE_OUT_OF_SCOPE');
+  const review = {
+    changeName: ctx.change, generatedAt: new Date().toISOString(),
+    origin: 'agent-review', inputFingerprint: ctx.fingerprint, inputs: ctx.inputs,
+    reviewedFiles: [...new Set(input.reviewedFiles)], dimensions: input.dimensions,
+    issues: input.issues || [], tests: input.tests || null, base: ctx.base,
+  };
+  // Save incomplete/failed reviews as such; never relabel them as passed.
+  snap.atomicJson(reviewPath(ctx), review);
+  const errors = reviewErrors(ctx, review);
+  if (!errors.length) saveAssociation(ctx, review);
+  return { ok: errors.length === 0, status: errors.length ? 'pending' : 'reviewed', errors, reviewFile: reviewPath(ctx) };
+}
+
+function testRuntime() {
+  for (const candidate of [path.join(__dirname, '../lib/test-execution.cjs'), path.join(__dirname, '../../skywalk-sdd/lib/test-execution.cjs')]) {
+    if (fs.existsSync(candidate)) return require(candidate);
+  }
+  throw new Error('TEST_RUNTIME_MISSING');
+}
+
+function runTests(args) {
+  if ((args.scope || 'worktree') !== 'worktree') throw new Error('TEST_WORKTREE_REQUIRED: 请在待测提交的独立 checkout/worktree 执行测试');
+  const ctx = context(args);
+  const command = args['command-file'] ? JSON.stringify(readJson(args['command-file'])) : args['command-json'];
+  if (!args['session-id']) throw new Error('TEST_SESSION_REQUIRED: --session-id');
+  const logger = [path.join(__dirname, '../log.cjs'), path.join(__dirname, '../../skywalk-sdd/index.cjs')].find(fs.existsSync);
+  if (!logger) throw new Error('TEST_LOGGER_MISSING');
+  const { spawnSync } = require('child_process');
+  const child = spawnSync(process.execPath, [logger, 'test-run', `--project=${ctx.specRoot}`,
+    `--change=${ctx.change}`, `--session-id=${args['session-id']}`, `--cwd=${ctx.project}`,
+    `--task-ids=${args['task-ids'] || ''}`, `--command-json=${command}`,
+    `--timeout-ms=${args['timeout-ms'] || 120000}`], {
+    cwd: ctx.project, encoding: 'utf8', maxBuffer: 32 * 1024 * 1024,
+    timeout: Number(args['timeout-ms'] || 120000) + 30000,
+  });
+  let output;
+  try { output = JSON.parse(child.stdout); }
+  catch { throw new Error(`TEST_RECORD_FAILED: ${(child.stderr || child.error?.message || '').slice(-2000)}`); }
+  if (!output.test_results || !output.event_id) throw new Error('TEST_RECORD_FAILED: 未保存严格测试事件');
+  const result = { testResults: output.test_results, receipt: output.receipt };
+  const after = context(args);
+  const stable = ctx.fingerprint === after.fingerprint;
+  const changedInputs = {};
+  for (const kind of ['code', 'spec']) {
+    const beforeFiles = kind === 'code' ? ctx.inputs.code : ctx.inputs.spec.files;
+    const afterFiles = kind === 'code' ? after.inputs.code : after.inputs.spec.files;
+    const before = new Map(beforeFiles.map(f => [f.path, snap.hashJson(f)]));
+    const next = new Map(afterFiles.map(f => [f.path, snap.hashJson(f)]));
+    changedInputs[kind] = [...new Set([...before.keys(), ...next.keys()])].filter(p => before.get(p) !== next.get(p));
+  }
+  const value = { inputFingerprint: ctx.fingerprint, stable, changedInputs, testResults: result.testResults, receipt: result.receipt };
+  snap.atomicJson(path.join(ctx.dir, 'tests.json'), value);
+  const ok = stable && result.testResults.exit_code === 0 && result.testResults.failure_type === 'none'
+    && result.testResults.counts_known && result.testResults.passed > 0;
+  return { ok, status: ok ? 'tested' : 'pending', ...value, errors: stable ? [] : ['INPUT_CHANGED_DURING_TEST'] };
+}
+
+function verify(args) {
+  const ctx = context(args);
+  const review = optionalJson(reviewPath(ctx));
+  const errors = reviewErrors(ctx, review);
+  const tests = optionalJson(path.join(ctx.dir, 'tests.json'));
+  const testsNotApplicable = ctx.required.length === 0 && review?.tests?.status === 'na'
+    && typeof review.tests.reason === 'string' && review.tests.reason.trim().length > 0
+    && DIMENSIONS.every(name => review.dimensions?.[name]?.status === 'na');
+  if (testsNotApplicable) { /* explicitly reviewed as no implementation/contract change */ }
+  else if (!tests || tests.inputFingerprint !== ctx.fingerprint || !tests.stable) errors.push('TESTS_MISSING_OR_STALE: 需要对当前输入执行测试');
+  else {
+    try { testRuntime().verifyCapture(tests.testResults, ctx.specRoot); }
+    catch (error) { errors.push(error.message); }
+    if (tests.testResults.exit_code !== 0 || tests.testResults.failure_type !== 'none') errors.push('TESTS_FAILED');
+    if (!tests.testResults.counts_known || tests.testResults.passed < 1) errors.push('NO_PASSING_TESTS');
+  }
+  const result = {
+    ok: !errors.length, status: errors.length ? 'pending' : 'ready', errors,
+    change: ctx.change, repository: ctx.identity, scope: ctx.scope,
+    codeRevision: ctx.scope === 'commit' ? ctx.ref : null,
+    specRevision: ctx.scope === 'commit' ? (ctx.mono ? ctx.ref : args['spec-ref']) : null,
+    inputFingerprint: ctx.fingerprint,
+    testStatus: testsNotApplicable ? 'not_applicable' : errors.some(e => /TEST|CAPTURE/.test(e)) ? 'pending' : 'passed',
+    testNotApplicableReason: testsNotApplicable ? review.tests.reason : null,
+    testReceipt: testsNotApplicable ? null : tests?.receipt || null, reviewFile: reviewPath(ctx),
+  };
+  snap.atomicJson(path.join(ctx.dir, 'verification.json'), result);
+  return result;
+}
+
+function main(argv = process.argv.slice(2)) {
+  const command = argv.shift();
+  const args = {};
+  for (const arg of argv) {
+    const match = /^--([\w-]+)=(.*)$/s.exec(arg);
+    if (!match) throw new Error(`ARG_INVALID: 使用 --参数=值: ${arg}`);
+    args[match[1]] = match[2];
+  }
+  const handlers = { prepare, 'record-review': recordReview, test: runTests, verify };
+  if (!handlers[command]) throw new Error('用法: delivery-check.cjs prepare|record-review|test|verify --project=<代码仓> --change=<变更> [--scope=worktree|index|commit]');
+  const result = handlers[command](args);
+  process.stdout.write(JSON.stringify(result, null, 2) + '\n');
+  if (result.ok === false) process.exitCode = 1;
+}
+
+if (require.main === module) {
+  try { main(); }
+  catch (error) { console.error(`[SDD delivery] ${error.message}`); process.exitCode = 1; }
+}
+module.exports = { context, prepare, recordReview, runTests, verify, reviewPath, reviewErrors, DIMENSIONS };