kld-sdd 2.7.8 → 2.8.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 };

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

@@ -0,0 +1,181 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+const { execFileSync } = require('child_process');
+
+const RULE_VERSION = 'sdd-delivery-v1';
+const digest = value => crypto.createHash('sha256').update(value).digest('hex');
+const hashJson = value => digest(JSON.stringify(value));
+const slash = value => value.replace(/\\/g, '/');
+
+// Git exports these during hooks. A different cwd alone does not switch repositories.
+function gitEnv() {
+  const env = { ...process.env };
+  for (const key of Object.keys(env)) {
+    if (/^GIT_(DIR|WORK_TREE|INDEX_FILE|COMMON_DIR|OBJECT_DIRECTORY|ALTERNATE_OBJECT_DIRECTORIES|PREFIX)$/.test(key)) delete env[key];
+  }
+  return env;
+}
+
+function git(root, args, options = {}) {
+  return execFileSync('git', args, {
+    cwd: root, env: { ...gitEnv(), ...(fs.realpathSync(root) === fs.realpathSync(process.cwd()) && process.env.GIT_INDEX_FILE ? { GIT_INDEX_FILE: path.resolve(process.env.GIT_INDEX_FILE) } : {}) }, encoding: 'utf8', timeout: 10000,
+    maxBuffer: 64 * 1024 * 1024, stdio: ['pipe', 'pipe', 'pipe'], ...options,
+  });
+}
+
+function repoIdentity(root) {
+  let remote = '';
+  try { remote = git(root, ['remote', 'get-url', 'origin']).trim(); } catch { /* local repo */ }
+  // Do not persist credentials from a remote URL.
+  remote = remote.replace(/(https?:\/\/)[^/@]+@/i, '$1').replace(/\.git$/, '').replace(/\/$/, '');
+  remote = remote.replace(/^git@([^:]+):/, '$1/').replace(/^https?:\/\//i, '');
+  const common = git(root, ['rev-parse', '--git-common-dir']).trim();
+  return remote || `local:${fs.realpathSync(path.resolve(root, common))}`;
+}
+
+function entriesAt(root, scope = 'worktree', ref = 'HEAD') {
+  if (scope === 'commit') {
+    const sha = git(root, ['rev-parse', '--verify', '--end-of-options', `${ref}^{commit}`]).trim();
+    return git(root, ['ls-tree', '-r', '-z', '--full-tree', sha]).split('\0').filter(Boolean).map(row => {
+      const tab = row.indexOf('\t'), [mode, type, oid] = row.slice(0, tab).split(' ');
+      return { path: row.slice(tab + 1), mode, oid, type };
+    });
+  }
+  const entries = git(root, ['ls-files', '--stage', '-z']).split('\0').filter(Boolean).map(row => {
+    const tab = row.indexOf('\t'), [mode, oid, stage] = row.slice(0, tab).split(' ');
+    if (stage !== '0') throw new Error('UNMERGED_INDEX: 请先解决 Git 冲突');
+    return { path: row.slice(tab + 1), mode, oid, type: mode === '160000' ? 'commit' : 'blob' };
+  });
+  if (scope === 'worktree') {
+    for (const file of git(root, ['ls-files', '--others', '--exclude-standard', '-z']).split('\0').filter(Boolean)) {
+      entries.push({ path: file, mode: '100644', type: 'blob' });
+    }
+  }
+  return entries;
+}
+
+function readBlobs(root, entries) {
+  const blobs = entries.filter(e => e.type === 'blob');
+  const result = new Map();
+  if (!blobs.length) return result;
+  const out = git(root, ['cat-file', '--batch'], { input: blobs.map(e => e.oid).join('\n') + '\n', encoding: null });
+  let offset = 0;
+  for (const entry of blobs) {
+    const end = out.indexOf(10, offset);
+    const header = out.subarray(offset, end).toString('ascii').split(' ');
+    if (end < 0 || header[1] !== 'blob' || !/^\d+$/.test(header[2])) throw new Error('GIT_BLOB_UNREADABLE');
+    const size = Number(header[2]);
+    offset = end + 1;
+    if (offset + size >= out.length) throw new Error('GIT_BLOB_TRUNCATED');
+    result.set(entry.path, out.subarray(offset, offset + size));
+    offset += size + 1;
+  }
+  return result;
+}
+
+function fileMeta(file, content, mode = '100644') {
+  // Git autocrlf changes text line endings between the worktree and index.
+  // Normalize valid UTF-8 text only; binary bytes and symlink targets stay exact.
+  const text = content.toString('utf8');
+  const isText = mode !== '120000' && !content.includes(0) && Buffer.from(text, 'utf8').equals(content);
+  const bytes = isText ? Buffer.from(text.replace(/\r\n/g, '\n'), 'utf8') : content;
+  return { path: file, mode, normalization: isText ? 'utf8-lf' : 'bytes', size: bytes.length, sha256: digest(bytes) };
+}
+
+function excluded(file, specRelative) {
+  if (specRelative && specRelative !== '.' && (file === specRelative || file.startsWith(specRelative + '/'))) return true;
+  return /(^|\/)(\.git|node_modules|target|dist|build|coverage|skywalk-sdd)(\/|$)/.test(file)
+    || /(^|\/)(consistency-report(?:-result)?\.(md|json)|consistency-reviews)(\/|$)/.test(file)
+    || /^(openspec|\.claude|\.cursor|\.codex|\.agents|\.qoder)\//.test(file);
+}
+
+function codeSnapshot(root, specRoot, scope = 'worktree', ref = 'HEAD') {
+  if (!['worktree', 'index', 'commit'].includes(scope)) throw new Error('SCOPE_INVALID');
+  const relative = slash(path.relative(root, specRoot));
+  const entries = entriesAt(root, scope, ref).filter(e => !excluded(e.path, relative.startsWith('..') ? '' : relative));
+  const blobs = scope === 'worktree' ? null : readBlobs(root, entries);
+  let trustFileMode = true;
+  try { trustFileMode = git(root, ['config', '--bool', 'core.filemode']).trim() !== 'false'; } catch { /* Git default */ }
+  const files = [];
+  for (const entry of entries) {
+    if (entry.type === 'commit') {
+      // Submodules require a separate delivery check in that repository.
+      files.push({ path: entry.path, mode: entry.mode, gitlink: entry.oid });
+      continue;
+    }
+    let content, mode = entry.mode;
+    if (scope === 'worktree') {
+      const fp = path.join(root, entry.path);
+      if (!fs.existsSync(fp) && !fs.lstatSync(fp, { throwIfNoEntry: false })) continue;
+      const stat = fs.lstatSync(fp);
+      if (stat.isSymbolicLink()) { content = Buffer.from(fs.readlinkSync(fp)); mode = '120000'; }
+      else { content = fs.readFileSync(fp); mode = trustFileMode ? (stat.mode & 0o111 ? '100755' : '100644') : entry.mode; }
+    } else content = blobs.get(entry.path);
+    if (!content) throw new Error(`UNREADABLE: ${entry.path}`);
+    files.push(fileMeta(entry.path, content, mode));
+  }
+  return files.sort((a, b) => a.path.localeCompare(b.path, 'en'));
+}
+
+function isSpecInput(file, change) {
+  if (file.startsWith(`openspec/changes/${change}/logs/`) || file.startsWith(`openspec/changes/${change}/reports/`)) return false;
+  if (/(^|\/)(consistency-report(?:-result)?\.(json|md)|consistency-reviews)(\/|$)/.test(file)) return false;
+  return file === 'modules.yaml' || file === 'sdd.config.yaml' || file === 'openspec/config.yaml'
+    || file.startsWith('openspec/specs/') || file.startsWith(`openspec/changes/${change}/`);
+}
+
+function specSnapshot(specRoot, change, options = {}) {
+  if (!/^[a-z0-9][a-z0-9-]+$/.test(change)) throw new Error('CHANGE_REQUIRED: 必须明确指定 change');
+  const files = [];
+  if (options.scope === 'commit' || options.scope === 'index') {
+    const root = options.root || specRoot;
+    const prefix = slash(path.relative(root, specRoot));
+    const start = prefix ? prefix + '/' : '';
+    const entries = entriesAt(root, options.scope, options.ref).filter(e => e.path.startsWith(start) && isSpecInput(e.path.slice(start.length), change));
+    const blobs = readBlobs(root, entries);
+    for (const entry of entries) {
+      if (entry.mode === '120000' || entry.type !== 'blob') throw new Error('SPEC_INPUT_SYMLINK_OR_SUBMODULE');
+      files.push(fileMeta(entry.path.slice(start.length), blobs.get(entry.path), entry.mode));
+    }
+  } else {
+    const walk = (relative) => {
+      const fp = path.join(specRoot, relative);
+      if (!fs.existsSync(fp)) return;
+      const stat = fs.lstatSync(fp);
+      if (stat.isSymbolicLink()) throw new Error(`SPEC_INPUT_SYMLINK: ${relative}`);
+      if (stat.isDirectory()) {
+        for (const name of fs.readdirSync(fp)) walk(relative ? `${relative}/${name}` : name);
+      } else if (isSpecInput(relative, change)) files.push(fileMeta(relative, fs.readFileSync(fp)));
+    };
+    for (const relative of ['modules.yaml', 'sdd.config.yaml', 'openspec/config.yaml', 'openspec/specs', `openspec/changes/${change}`]) walk(relative);
+  }
+  if (!files.some(f => f.path === `openspec/changes/${change}/proposal.md`)) throw new Error(`CHANGE_MISSING: ${change}`);
+  files.sort((a, b) => a.path.localeCompare(b.path, 'en'));
+  return { files, sha256: hashJson(files) };
+}
+
+function changedFiles(root, scope, base, ref = 'HEAD') {
+  const args = ['diff', '--name-only', '--no-renames', '-z'];
+  if (scope === 'index') args.push('--cached');
+  if (base) args.push(base);
+  if (scope === 'commit') {
+    if (!base) throw new Error('BASE_REQUIRED: 提交校验必须明确提供比较基线');
+    args.push(ref);
+  }
+  args.push('--');
+  const result = git(root, args).split('\0').filter(Boolean);
+  if (scope === 'worktree') result.push(...git(root, ['ls-files', '--others', '--exclude-standard', '-z']).split('\0').filter(Boolean));
+  return [...new Set(result)].sort();
+}
+
+function atomicJson(file, value) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const temp = `${file}.${process.pid}.${crypto.randomBytes(6).toString('hex')}.tmp`;
+  fs.writeFileSync(temp, JSON.stringify(value, null, 2) + '\n');
+  fs.renameSync(temp, file);
+}
+
+module.exports = { RULE_VERSION, digest, hashJson, git, gitEnv, repoIdentity, entriesAt, readBlobs, fileMeta, codeSnapshot, specSnapshot, changedFiles, atomicJson, excluded };

package/templates/git-hooks/hooks.config

@@ -1,3 +1,5 @@
+# 默认仅安装 commit-msg；pre-commit/pre-push 段仅供已有显式集成使用。
+# Apply 自动运行 delivery-check；安装不会替团队开启 CI 门禁。
 # KLD SDD Hook 插件配置文件
 # 每行一个脚本名，空行和 # 开头的行会被忽略
 # 注释某行 = 禁用该插件，取消注释 = 启用该插件
@@ -9,13 +11,13 @@ commit-msg-sdd-trailer.cjs
 [pre-commit]
 # 检查 tasks.md 中是否有未完成的归档任务
 pre-commit-sdd-check.cjs
-# 检查 Spec 一致性校验报告（置信度、过期、人工确认等）
+# 检查 Spec 一致性校验报告（输入指纹、覆盖与实际检查结果）
 pre-commit-consistency-check.cjs
 
 [pre-push]
 # 运行 doctor 完整诊断（配置、Trailer 协议、活动变更等）
 pre-push-sdd-check.cjs
-# 检查待推送范围的一致性报告（存在性、过期；置信度由 pre-commit 负责）
+# 检查待推送范围的一致性报告（实际 push refs；需显式 Change 和真实测试回执）
 pre-push-consistency-check.cjs
 
 [consistency]
@@ -24,15 +26,15 @@ pre-push-consistency-check.cjs
 # Go / Kotlin 等项目按需修改：
 # 注意：新增语言的语言特定构建文件（如 Rust 的 build.rs）不在内置排除规则内，需自行确认
 # 本配置同时被 git hook（isBusinessCode）与 opsx-consistency-check skill 读取，单一来源
-# ⚠️ 清空本行 = 不拦截任何业务代码文件（一致性门禁对提交/推送失效，仅剩报告存在性/过期检查）
+# 清空本行时严格交付检查会失败，不能将范围未知视为通过。
 business_code_exts = .java,.ts,.tsx,.js,.jsx,.vue,.py
 
 # 一致性校验模式（项目级默认值，环境变量优先覆盖；三个互斥，只能启用一个）
 # 环境变量：SDD_SKIP_CONSISTENCY_CHECK=1 / SDD_STRICT_CONSISTENCY=1 / SDD_WARN_ONLY=1
 # - skip = 1：跳过一致性校验（紧急绕过，如 hotfix 仓不需要 spec 校验）
-# - strict = 1：严格模式，medium 置信度也阻止提交（仅 pre-commit 生效，pre-push 忽略）
+# - strict = 1：保留旧项目显式门禁选择；交付检查始终要求完整事实证据
 # - warn_only = 1：仅告警不拦截（CI 调试期，问题全列但不阻断提交/推送）
-# 三项均不设或均设为 0 = 默认模式（low 阻止，medium 放行，high 放行）
+# 三项均不设或均设为 0 = 检查回执、输入指纹与覆盖；不按置信度放行
 skip = 0
 strict = 0
-warn_only = 0
+warn_only = 0

package/templates/git-hooks/pre-commit

@@ -10,13 +10,24 @@ git_root=$(git rev-parse --show-toplevel 2>/dev/null) || {
   exit 1
 }
 hooks_dir=""
+# 统一反斜杠为正斜杠，保证 Windows 盘符路径（P:\a\b → P:/a/b）能被 case 判定为绝对路径
+normalize_path() {
+  printf '%s' "$1" | tr '\\' '/'
+}
+# 绝对路径（/ 开头或盘符 X: 开头）直接使用；相对路径基于 git 根拼接
+resolve_spec_dir() {
+  raw=$(normalize_path "$1")
+  case "$raw" in
+    /*|[A-Za-z]:*) printf '%s' "$raw" ;;
+    *) printf '%s' "$git_root/$raw" ;;
+  esac
+}
 spec_path=$(git -C "$git_root" config --local sdd.specPath 2>/dev/null)
 if [ -n "$spec_path" ]; then
-  case "$spec_path" in /*) ;; *) spec_path="$git_root/$spec_path" ;; esac
-  hooks_dir="$spec_path/skywalk-sdd/git-hooks"
+  hooks_dir="$(resolve_spec_dir "$spec_path")/skywalk-sdd/git-hooks"
 elif [ -f "$git_root/.sdd-spec-root" ]; then
   spec_rel=$(head -1 "$git_root/.sdd-spec-root" | sed 's/^[[:space:]]*//;s/[[:space:]]*$//')
-  case "$spec_rel" in /*) hooks_dir="$spec_rel/skywalk-sdd/git-hooks" ;; *) hooks_dir="$git_root/$spec_rel/skywalk-sdd/git-hooks" ;; esac
+  hooks_dir="$(resolve_spec_dir "$spec_rel")/skywalk-sdd/git-hooks"
 fi
 if [ -n "$hooks_dir" ] && [ ! -d "$hooks_dir" ]; then
   echo "[SDD] 已配置的 Spec 路径失效：$hooks_dir"
@@ -27,12 +38,15 @@ fi
 # 方法3: 从 git 根向上搜索 skywalk-sdd/git-hooks（spec 仓本身或父级）
 if [ -z "$hooks_dir" ]; then
   search_dir="$git_root"
-  while [ "$search_dir" != "/" ] && [ "$search_dir" != "" ]; do
+  while [ -n "$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")"
+    # Windows 盘符根（P:/）dirname 后不变，需显式收敛，避免死循环
+    parent_dir="$(dirname "$search_dir")"
+    [ "$parent_dir" = "$search_dir" ] && break
+    search_dir="$parent_dir"
   done
 fi
 

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

@@ -1,45 +1,27 @@
 #!/usr/bin/env node
-/**
- * pre-commit-consistency-check.cjs
- *
- * Pre-commit 门禁：检查本次提交 diff 涉及的 Spec 一致性校验报告。
- * - diff 驱动：仅检查 diff 文件与报告 coveredFiles 有交集的 change，无关 change 跳过
- * - 报告存在性：活跃 change 无报告 → 阻止提交
- * - 报告过期：代码在报告生成后被修改 → 阻止提交
- * - 置信度门禁：confidence=low → 阻止提交；strict 模式下 medium 也阻止
- *
- * 通过环境变量控制：
- * - SDD_SKIP_CONSISTENCY_CHECK=1 → 跳过校验
- * - SDD_STRICT_CONSISTENCY=1 → 严格模式（medium 也阻止）
- * - SDD_WARN_ONLY=1 → 仅告警不拦截
- * - 注意：三个环境变量互斥，只能启用一个
- *
- * 共享逻辑见同目录 consistency-check-core.cjs。
+/** Optional strict index verification. Not installed on daily commits by default.
+ * Checks complete coverage, input fingerprints and actual review dimensions.
+ * SDD_SKIP_CONSISTENCY_CHECK / SDD_WARN_ONLY remain explicit legacy overrides.
  */
 'use strict';
 
 const core = require('./consistency-check-core.cjs');
-const { gitDiffNameStatus } = core;
 
-/**
- * 单仓 diff 采集：工作区相对 HEAD 的变更（含 staged 与未 staged）。
- * files=修改/新增（排除删除）；deleted=删除文件。
- * 空仓（无任何 commit）时 HEAD 不存在：降级用 staged 文件列表。
- * @returns {{files: string[], deleted: string[], ok: boolean}} ok=false 表示无法确定变更范围
- */
+/** Inspect the actual staged content, including an unborn repository and deletions. */
 function gitDiffHead(repoRoot) {
-  const bases = [['diff', 'HEAD'], ['diff', '--cached']];
-  for (const base of bases) {
-    const r = gitDiffNameStatus(repoRoot, base);
-    if (r.ok) return r;
-  }
-  return { files: [], deleted: [], ok: false };
+  try {
+    const snap = require('./delivery-snapshot.cjs');
+    const changed = snap.changedFiles(repoRoot, 'index');
+    const indexed = new Set(snap.entriesAt(repoRoot, 'index').map(e => e.path));
+    return { files: changed.filter(f => indexed.has(f)), deleted: changed.filter(f => !indexed.has(f)), ok: true };
+  } catch { return { files: [], deleted: [], ok: false }; }
 }
 
 core.runConsistencyCheck({
   label: '[SDD commit-consistency-check]',
   actionNoun: '提交',
   diffFn: gitDiffHead,
-  checkConfidence: true, // 置信度校验由 pre-commit 完成
-  includeUntracked: true, // 新文件将随本次提交入库，需检查
+  checkConfidence: true, // Legacy option; factual review dimensions now decide readiness.
+  includeUntracked: false, // Only the index is part of this commit.
+  staleFromIndex: true,
 });

package/templates/git-hooks/pre-push

@@ -10,13 +10,24 @@ git_root=$(git rev-parse --show-toplevel 2>/dev/null) || {
   exit 1
 }
 hooks_dir=""
+# 统一反斜杠为正斜杠，保证 Windows 盘符路径（P:\a\b → P:/a/b）能被 case 判定为绝对路径
+normalize_path() {
+  printf '%s' "$1" | tr '\\' '/'
+}
+# 绝对路径（/ 开头或盘符 X: 开头）直接使用；相对路径基于 git 根拼接
+resolve_spec_dir() {
+  raw=$(normalize_path "$1")
+  case "$raw" in
+    /*|[A-Za-z]:*) printf '%s' "$raw" ;;
+    *) printf '%s' "$git_root/$raw" ;;
+  esac
+}
 spec_path=$(git -C "$git_root" config --local sdd.specPath 2>/dev/null)
 if [ -n "$spec_path" ]; then
-  case "$spec_path" in /*) ;; *) spec_path="$git_root/$spec_path" ;; esac
-  hooks_dir="$spec_path/skywalk-sdd/git-hooks"
+  hooks_dir="$(resolve_spec_dir "$spec_path")/skywalk-sdd/git-hooks"
 elif [ -f "$git_root/.sdd-spec-root" ]; then
   spec_rel=$(head -1 "$git_root/.sdd-spec-root" | sed 's/^[[:space:]]*//;s/[[:space:]]*$//')
-  case "$spec_rel" in /*) hooks_dir="$spec_rel/skywalk-sdd/git-hooks" ;; *) hooks_dir="$git_root/$spec_rel/skywalk-sdd/git-hooks" ;; esac
+  hooks_dir="$(resolve_spec_dir "$spec_rel")/skywalk-sdd/git-hooks"
 fi
 if [ -n "$hooks_dir" ] && [ ! -d "$hooks_dir" ]; then
   echo "[SDD] 已配置的 Spec 路径失效：$hooks_dir"
@@ -27,12 +38,15 @@ fi
 # 方法3: 从 git 根向上搜索 skywalk-sdd/git-hooks（spec 仓本身或父级）
 if [ -z "$hooks_dir" ]; then
   search_dir="$git_root"
-  while [ "$search_dir" != "/" ] && [ "$search_dir" != "" ]; do
+  while [ -n "$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")"
+    # Windows 盘符根（P:/）dirname 后不变，需显式收敛，避免死循环
+    parent_dir="$(dirname "$search_dir")"
+    [ "$parent_dir" = "$search_dir" ] && break
+    search_dir="$parent_dir"
   done
 fi