kld-sdd 2.7.8-2 → 2.7.8-3

package/README.md

@@ -4,6 +4,8 @@ KLD SDD OpenSpec 工程增强工具：一键初始化 AI 编辑器技能、语
 
 本分支已调整使用方式：模式与测试策略自动选择，按已有授权连续处理，KB 断连时继续本地工作，发布时核对真实基线。新规则、设计依据与尚未完成的结构调整见 [使用摩擦分析](USABILITY.md)。旧安装副本需要更新后才会应用这些规则。
 
+日常提交默认只保留本地关联 Hook；Apply 自动执行代码/Spec 检查、真实测试与交付验证。旧项目升级、备份回退、多仓和 CI 边界见 [Git Hook 调整说明](USABILITY.md#2026-09-10git-hook-收缩与交付验证)。
+
 ## 这是什么？
 
 **SDD（Specification-Driven Development）** 是一种以文档链驱动 AI 编码的研发方法：先写清楚"要做什么"，再让 AI 去实现，避免 AI 乱猜、反复返工。

package/USABILITY.md

@@ -102,3 +102,55 @@ SDD 应帮助团队留下三类东西：明确的业务约定、能够证明实
 本机独立后端联调确认七种 Skill 的使用事件均成功写入，断网事件保留并恢复补报，服务端统计为 8 次、覆盖 7 阶段。使用统计是独立的 usage 事件，不等于测试通过、归档完成或 Spec 已入库；当前服务端按提交次数计数，网络响应丢失后的重复提交不提供 exactly-once 保证。
 
 配置 Skill 与参考同步去除默认首目标、截短 UUID 和旧监控项目绑定步骤，修正 KB API 字段映射；切换查询目标不再引导改写团队项目身份，权限失败也不清空其他目标可能仍有效的密钥。
+
+## 2026-09-10：Git Hook 收缩与交付验证
+
+日常 commit 负责保存工作，Apply 收尾负责检查交付，Spec 入库负责发布知识。新安装只自动接入一个本地 `commit-msg`，它不请求 KB、不调用模型、不扫描整个工作区，也不重复执行文档 Check。
+
+| 场景 | 当前行为 |
+|---|---|
+| 本次明确指定 Change | `KLD_SDD_CHANGE` 支持逗号分隔的多个 Change，校验目录后写关联 |
+| 未显式指定 Change | 只复用能与暂存文件内容逐项匹配的检查关联；多个候选或没有证据时提示待关联 |
+| Spec 仓尚未提交 | 允许保存代码，不写旧 HEAD 冒充当前 `Spec-Revision` |
+| 独立 Spec 仓干净且远端关系匹配 | 写完整不可变 Spec SHA；单仓不写自指 Revision |
+| 路径失效、Node 缺失或关联脚本超时 | 本次提交继续，显示待关联，不表示交付检查通过 |
+| 实施收尾 | Agent 自动进行代码/Spec 检查、真实测试和 `delivery-check verify` |
+
+关联 worker 设置 1.5 秒超时上限。这个上限不是性能测试结果；用户自有 Hook 的耗时不受 SDD 控制。
+
+### 一个验证入口，四个内部步骤
+
+入口是 `<spec-root>/skywalk-sdd/git-hooks/delivery-check.cjs`。Apply 自动串联，用户不需要记忆四条命令：
+
+1. `prepare --project=<代码仓Git根> --change=<Change> --base=<实施前SHA>`：记录输入，返回本次需要检查的文件和是否可复用旧回执。
+2. `record-review --project=... --change=... --input=<检查JSON>`：收录实际检查结果；输入改变、漏覆盖、失败、未检查都会明确显示。
+3. `test --project=... --change=... --session-id=... --task-ids=... --command-file=<命令数组JSON>`：内部复用原 `test-run`，保留严格测试事件、命令退出码及原始输出。
+4. `verify --project=... --change=...`：判断当前快照的证据是否完整。`ready` 与 `pending` 分开，不把 KB 入库或合并状态混入测试结果。
+
+机器回执绑定代码仓身份、Spec 仓身份、明确 Change、代码和 Spec 内容、规则版本与配置。当前保守地纳入本仓依赖文件及全局规格；相同指纹可复用，变化后再定向取证。它尚未实现自动跨仓依赖图或逐规则的最小重查。mtime 不再作为内容一致的证据。UTF-8 文本统一 LF 以兼容 Git autocrlf，二进制和符号链接目标按原始字节检查。
+
+检查结果分别记录接口、业务、校验和错误处理；`pass` 需要证据，`na` 需要理由，`not_checked` 与 `fail` 都不能算通过。回执记录 Agent 做过的检查及其输入，不单靠模型自报置信度判断正确性。
+
+测试计数支持 Node TAP 与 Maven Surefire/Failsafe 的结果摘要；未知测试格式保留实际输出并显示待验证，不编造计数。只有无业务代码变更、四个维度都经检查判为不适用，且回执有明确测试不适用理由时，才允许 `testStatus=not_applicable`，不会显示“测试通过”。
+
+### 多仓与正式提交
+
+每个代码仓分别存回执，同一 Change 的多仓结果互不覆盖。Spec 可以先于代码完成并入库；“规格已发布”和“实现已验证”是两个状态。
+
+需要核对已提交代码时使用 `verify --scope=commit --ref=<目标提交> --base=<实施前提交>`；独立 Spec 仓额外提供 `--spec-ref=<完整Spec SHA>`。命令读取指定 Git 对象，可以验证非当前 HEAD，不会用工作区替代。冲突解决改变内容后需重新检查和测试。
+
+本次没有自动启用团队 CI。现有 CI 样例不等于已接入的合并门禁。团队接入时需要在受信任的执行环境生成或提供相应回执与原始测试日志；当前测试回执包含本地路径，复制到另一机器不能直接当作可移植的验证包。可以在目标 checkout 上重新执行同一入口。
+
+### 已有项目升级与回退
+
+重新运行安装器会更新运行时与 Skills，并迁移已识别的原版 SDD Hook。已退役或更新的 Hook 先备份到 Git 公共目录的 `kld-sdd-hook-backups/`；回退时把对应 `.bak` 复制回 hooks 同名路径并恢复执行权限。
+
+只含 marker 不足以证明文件受管：追加过用户逻辑、Hook 符号链接、修改过插件列表、显式旧门禁设置都会保留并提示。`core.hooksPath`（包括 Husky）交给现有管理器维护；安装器不会接管其目录。普通 worktree 使用 Git 解析出的公共 hooks 目录。`hooks.config` 保留用户内容，重新安装不重置选项。
+
+空目录首次安装声明正确的 mono 布局；此前生成的原样多仓占位配置可备份后自动迁移，真实团队配置不会被猜测改写。只有一个无效 `.git` 目录时明确提示 Hook 未安装，本地文档与运行时仍可部署。
+
+### 上报与知识链路的边界
+
+原 Skill 使用上报、严格测试事件和 KB 上传/查询 API 保留。默认移除旧 pre-commit 后，不再采集那条仅凭“本次提交有代码而没有文档”推断的 bypass 事件；这类旧统计与真实 Skill 使用量不能混为一谈。
+
+`kb-upload --validate-only` 在未连接 KB 时可做本地语义校验，并明确说明未验证权限、发布基线及入库状态；正式上传仍严格检查项目与目标配置，连接或身份异常不能伪装为入库成功。UUID 继续完整保存，仅修正帮助中残留的 8 位说明。

package/lib/hook-install.js

@@ -0,0 +1,75 @@
+'use strict';
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+const { execFileSync } = require('child_process');
+const known = require('./managed-hook-hashes.json');
+const hash = text => crypto.createHash('sha256').update(text).digest('hex');
+
+function section(text, name) {
+  let active = false;
+  const result = [];
+  for (const raw of text.split(/\r?\n/)) {
+    const line = raw.trim();
+    if (line.startsWith('[')) active = line === `[${name}]`;
+    else if (active && line && !line.startsWith('#')) result.push(line);
+  }
+  return result.join('\n');
+}
+
+function updateHook(root, name, pkgPath, configFile) {
+  const git = args => execFileSync('git', args, { cwd: root, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }).trim();
+  let configured = '';
+  try { configured = git(['config', '--get', 'core.hooksPath']); } catch { /* default path */ }
+  if (configured) {
+    console.log(`   ℹ️ 保留 core.hooksPath=${configured}；由现有 Hook 管理器接入，SDD 不覆盖它`);
+    return;
+  }
+  let hookPath;
+  try { hookPath = path.resolve(root, git(['rev-parse', '--git-path', `hooks/${name}`])); }
+  catch { console.log(`   ⚠️ ${root} 不是有效 Git 仓库，未安装 ${name} Hook`); return; }
+  const templateDir = path.join(pkgPath, 'templates/git-hooks');
+  const content = fs.readFileSync(path.join(templateDir, name));
+  const stat = fs.lstatSync(hookPath, { throwIfNoEntry: false });
+  if (stat && !stat.isFile()) { console.log(`   ℹ️ 保留 Hook 链接或特殊文件：${hookPath}`); return; }
+  const existing = stat ? fs.readFileSync(hookPath) : null;
+  const customizedConfig = configFile && fs.existsSync(configFile)
+    && section(fs.readFileSync(configFile, 'utf8'), name) !== section(fs.readFileSync(path.join(templateDir, 'hooks.config'), 'utf8'), name);
+  const explicitGate = name !== 'commit-msg' && configFile && fs.existsSync(configFile)
+    && /^(?:strict|skip|warn_only)\s*=\s*(?:1|true|yes)$/m.test(section(fs.readFileSync(configFile, 'utf8'), 'consistency'));
+  if (existing && (explicitGate || customizedConfig ||
+      (!known[name].includes(hash(existing)) && hash(existing) !== hash(content)))) {
+    console.log(`   ℹ️ 保留自定义 Hook：${hookPath}；可审阅后自行移除旧 SDD 调用`);
+    return;
+  }
+  if (existing && hash(existing) === hash(content) && name === 'commit-msg') return;
+  if (existing) {
+    const common = path.resolve(root, git(['rev-parse', '--git-common-dir']));
+    const backup = path.join(common, 'kld-sdd-hook-backups', `${name}.${hash(existing)}.bak`);
+    fs.mkdirSync(path.dirname(backup), { recursive: true });
+    if (!fs.existsSync(backup)) fs.copyFileSync(hookPath, backup);
+    console.log(`   ✓ 旧 Hook 已备份：${backup}`);
+  }
+  if (name !== 'commit-msg') {
+    if (existing) fs.unlinkSync(hookPath);
+    return;
+  }
+  fs.mkdirSync(path.dirname(hookPath), { recursive: true });
+  fs.writeFileSync(hookPath, content, { mode: 0o755 });
+  fs.chmodSync(hookPath, 0o755);
+  console.log('   ✓ commit-msg 已更新为本地关联提示；交付验证由 Apply 收尾执行');
+}
+
+function deployRuntime(specRoot, pkgPath) {
+  const dir = path.join(specRoot, 'skywalk-sdd/git-hooks');
+  const source = path.join(pkgPath, 'templates/git-hooks');
+  fs.mkdirSync(dir, { recursive: true });
+  for (const file of fs.readdirSync(source)) {
+    const target = path.join(dir, file);
+    const stat = fs.lstatSync(target, { throwIfNoEntry: false });
+    if (stat && !stat.isFile()) { console.log(`   ℹ️ 保留运行时链接：${target}`); continue; }
+    if (file.endsWith('.cjs') || (file === 'hooks.config' && !stat)) fs.copyFileSync(path.join(source, file), target);
+  }
+  return path.join(dir, 'hooks.config');
+}
+module.exports = { updateHook, deployRuntime };

package/lib/init.js

@@ -1151,6 +1151,8 @@ function deployTelemetryDataDir(targetCwd = process.cwd()) {
     console.log('   ⚠️  kb-sync-identity.cjs 源文件缺失，重新入库身份同步不可用');
   }
 
+  require('./hook-install.js').deployRuntime(cwd, pkgPath);
+
   console.log(`   ✓ 部署 skywalk-sdd/ 运行时（events/state 数据目录 + ${deployedModules} 个模块）`);
   vlog('   ✓ 调用方式: node skywalk-sdd/log.cjs start|end|metrics|semantic-identity|semantic-reconcile|semantic-check');
   vlog('   ✓ openspec: node skywalk-sdd/openspec-shim.cjs list（自动 cd 到 *-sdd-specs）');
@@ -1161,76 +1163,12 @@ function deployTelemetryDataDir(targetCwd = process.cwd()) {
   return true;
 }
 
-/**
- * 安装 SDD shell hook（多脚本调用型 hook，如 pre-commit / pre-push / commit-msg）。
- * 直接部署完整的 shell 脚本到 .git/hooks/，脚本内部远程引用 spec 仓的 .cjs 脚本。
- *
- * shell hook 运行时通过 git config sdd.specPath / .sdd-spec-root / 向上搜索
- * 定位 spec 仓的 skywalk-sdd/git-hooks/ 目录，兼容单仓/多仓/mono 布局。
- *
- * @param {string} cwd - Git 仓库根目录
- * @param {string} hookName - hook 名称（如 'pre-commit'、'pre-push'）
- * @param {string} pkgPath - kld-sdd 包路径（用于读取模板）
- */
-function installSddShellHook(cwd, hookName, pkgPath = getPackagePath()) {
-  const hooksDir = path.join(cwd, '.git', 'hooks');
-  if (!fs.existsSync(hooksDir)) {
-    return;
-  }
-
-  const templatePath = path.join(pkgPath, 'templates', 'git-hooks', hookName);
-  if (!fs.existsSync(templatePath)) {
-    console.log(`   ⚠️  Hook 模板不存在: ${templatePath}`);
-    return;
-  }
-
-  const hookPath = path.join(hooksDir, hookName);
-  const marker = 'KLD SDD quality gate';
-  const content = fs.readFileSync(templatePath, 'utf8');
-
-  if (fs.existsSync(hookPath)) {
-    const existing = fs.readFileSync(hookPath, 'utf8');
-    if (existing.includes(marker)) {
-      // 已是 SDD hook：允许覆盖升级
-      fs.writeFileSync(hookPath, content, 'utf8');
-      try {
-        // 0o700：仅属主可执行（git 以属主身份执行 hook），避免 S2612 对组/其他用户放权的告警
-        fs.chmodSync(hookPath, 0o700);
-      } catch {
-        // ignore
-      }
-      console.log(`   ✓ 更新 .git/hooks/${hookName} SDD 质量门禁（多脚本）`);
-      return;
-    }
-    console.log(`   ℹ️  .git/hooks/${hookName} 已存在且非 SDD 受管 hook，已保留不覆盖`);
-    return;
-  }
-
-  fs.writeFileSync(hookPath, content, 'utf8');
-  try {
-    fs.chmodSync(hookPath, 0o755);
-  } catch {
-    // Windows 上 chmod 可能没有实际效果
-  }
-  console.log(`   ✓ 安装 .git/hooks/${hookName} SDD 质量门禁（多脚本）`);
+/** 安全升级 commit-msg、备份并退役受管旧门禁，保留用户 Hook 与管理器。 */
+function installSddShellHook(cwd, hookName, pkgPath = getPackagePath(), configFile) {
+  return require('./hook-install.js').updateHook(cwd, hookName, pkgPath, configFile);
 }
 
-/**
- * 部署代码仓全部 Git hooks（commit-msg + pre-commit + pre-push）。
- *
- * 统一入口，封装三种 hook 的部署逻辑。代码仓**不落 skywalk-sdd/**，
- * 只在 .git/hooks/ 安装 shell hook 模板，远程引用 spec 仓的 .cjs 脚本：
- *
- * - **spec 仓**：确保 skywalk-sdd/git-hooks/ 下有全部 .cjs 脚本
- *   （commit-msg-sdd-trailer + pre-commit-* + pre-push-* + ontology）。
- * - **代码仓 .git/hooks/**：仅安装 3 个 shell hook 模板，运行时通过
- *   git config sdd.specPath / .sdd-spec-root / 向上搜索定位 spec 仓的脚本。
- *
- * @param {string} codeRepoRoot - 代码仓根目录
- * @param {string} specRepoRoot - spec 包裹包根目录
- * @param {object} options - { pkgPath }
- * @returns {{ ok: boolean, message?: string }}
- */
+/** 代码仓只安装 commit-msg；验证脚本集中部署在 Spec 包。 */
 function deployCodeRepoHooks(codeRepoRoot, specRepoRoot, options = {}) {
   const cwd = path.resolve(codeRepoRoot);
   const specRoot = path.resolve(specRepoRoot);
@@ -1240,32 +1178,11 @@ function deployCodeRepoHooks(codeRepoRoot, specRepoRoot, options = {}) {
     return { ok: false, message: '不是 Git 仓库' };
   }
 
-  // ── 1. 确保 spec 仓有全部 hook 脚本 + ontology ──
-  // commit-msg .cjs + ontology（ensureSpecCommitMsgScript 已处理）
   ensureSpecCommitMsgScript(specRoot, pkgPath);
-  // pre-commit / pre-push .cjs 脚本
-  const specHooksDir = path.join(specRoot, 'skywalk-sdd', 'git-hooks');
-  const gitHooksTemplateDir = path.join(pkgPath, 'templates', 'git-hooks');
-  if (!fs.existsSync(specHooksDir)) {
-    fs.mkdirSync(specHooksDir, { recursive: true });
-  }
-  // 复制全部 .cjs 脚本 + hooks.config 配置文件
-  const hookScripts = fs.existsSync(gitHooksTemplateDir)
-    ? fs.readdirSync(gitHooksTemplateDir).filter(f => f.endsWith('.cjs') || f === 'hooks.config')
-    : [];
-  for (const script of hookScripts) {
-    const src = path.join(gitHooksTemplateDir, script);
-    const dst = path.join(specHooksDir, script);
-    // 始终覆盖，与 shell hook 的 marker 覆盖策略保持一致
-    fs.copyFileSync(src, dst);
-  }
-  console.log(`   ✓ 确保 spec 仓 skywalk-sdd/git-hooks/ 脚本齐全（${hookScripts.length} 个文件）`);
-
-  // ── 2. 安装三个 shell hooks 到代码仓 .git/hooks/ ──
-  // 模板 hook 运行时自动定位 spec 仓的 .cjs 脚本
-  installSddShellHook(cwd, 'commit-msg', pkgPath);
-  installSddShellHook(cwd, 'pre-commit', pkgPath);
-  installSddShellHook(cwd, 'pre-push', pkgPath);
+  const configFile = require('./hook-install.js').deployRuntime(specRoot, pkgPath);
+  for (const name of ['commit-msg', 'pre-commit', 'pre-push']) {
+    installSddShellHook(cwd, name, pkgPath, configFile);
+  }
 
   return { ok: true };
 }
@@ -1292,64 +1209,21 @@ function ensureSpecCommitMsgScript(specRepoRoot, pkgPath = getPackagePath()) {
   return { ok: true, scriptPath, deployed: true };
 }
 
-/**
- * 部署 Git hooks / CI 兜底模板
- * 这些脚本只做质量门禁和 CI 补充记录，不替代 OPSX 主采集链路。
- *
- * @param {string} [targetCwd]
- * @param {{ mode?: 'full'|'commit-msg-only' }} [options]
- *   full: spec 包裹包（pre-commit/pre-push/commit-msg + CI）
- *   commit-msg-only: 仅安装 commit-msg hook（跳过 pre-commit/pre-push）
- */
+/** 部署验证运行时与轻量 Hook；不自动启用 CI。options 为旧调用兼容保留。 */
 function deployQualityGateTemplates(targetCwd = process.cwd(), options = {}) {
   const pkgPath = getPackagePath();
   const cwd = path.resolve(targetCwd);
-  const mode = options.mode || 'full';
-  // U4: 非 Git 项目跳过 Git hooks / CI 兜底模板（按需部署，不污染非 Git 项目根）
-  if (!fs.existsSync(path.join(cwd, '.git'))) {
-    console.log('🧰 非 Git 项目，跳过 Git hooks / CI 兜底模板部署');
-    return false;
+  const configFile = require('./hook-install.js').deployRuntime(cwd, pkgPath);
+  if (!workspaceLayout.isGitRepo(cwd)) return false;
+  for (const name of ['commit-msg', 'pre-commit', 'pre-push']) {
+    installSddShellHook(cwd, name, pkgPath, configFile);
   }
-  console.log(`🧰 正在部署 SDD Git hooks（${mode}）: ${cwd}`);
-  const dataDir = path.join(cwd, 'skywalk-sdd');
-  const gitHooksTemplateDir = path.join(pkgPath, 'templates', 'git-hooks');
-  const ciTemplateDir = path.join(pkgPath, 'templates', 'ci');
-  const targetGitHooksDir = path.join(dataDir, 'git-hooks');
-  const targetCiDir = path.join(dataDir, 'ci');
-
-  if (fs.existsSync(gitHooksTemplateDir)) {
-    // 复制 .cjs 脚本 + hooks.config 到 skywalk-sdd/git-hooks/
-    // shell hook 模板（commit-msg/pre-commit/pre-push）不落此目录
-    if (!fs.existsSync(targetGitHooksDir)) {
-      fs.mkdirSync(targetGitHooksDir, { recursive: true });
-    }
-    for (const file of fs.readdirSync(gitHooksTemplateDir)) {
-      if (file.endsWith('.cjs') || file === 'hooks.config') {
-        fs.copyFileSync(path.join(gitHooksTemplateDir, file), path.join(targetGitHooksDir, file));
-      }
-    }
-    console.log('   ✓ 部署 skywalk-sdd/git-hooks/（.cjs 脚本 + hooks.config）');
-  } else {
-    console.log(`   ⚠️  Git hooks 模板缺失: ${gitHooksTemplateDir}`);
-  }
-
-  if (mode === 'full' && fs.existsSync(ciTemplateDir)) {
-    copyDir(ciTemplateDir, targetCiDir);
-    console.log('   ✓ 部署 skywalk-sdd/ci/');
-  }
-
-  if (mode === 'full') {
-    installSddShellHook(cwd, 'pre-commit', pkgPath);
-    installSddShellHook(cwd, 'pre-push', pkgPath);
-  }
-  installSddShellHook(cwd, 'commit-msg', pkgPath);
-
-  console.log('✅ Git hooks 已就绪');
+  // CI is an explicit team integration; installing SDD does not enable a merge gate.
   return true;
 }
 
 /**
- * 代码仓轻量接入：写 .sdd.yaml + sdd.specPath + .git/hooks/（commit-msg + pre-commit + pre-push）。
+ * 代码仓轻量接入：写 .sdd.yaml + sdd.specPath + 轻量 commit-msg。
  * 代码仓不落 skywalk-sdd/，shell hook 远程引用 spec 仓 skywalk-sdd/git-hooks/ 下的 .cjs 脚本。
  */
 function attachCodeRepoLite(codeRepoRoot, specRepoRoot, options = {}) {
@@ -1364,7 +1238,7 @@ function attachCodeRepoLite(codeRepoRoot, specRepoRoot, options = {}) {
     return { ok: false, repo: label, message: `spec 路径不是 Git 仓库: ${specRoot}` };
   }
 
-  console.log(`🔗 轻量接入代码仓（commit-msg + pre-commit + pre-push）: ${label}`);
+  console.log(`🔗 轻量接入代码仓（本地关联 Hook）: ${label}`);
 
   const remote = sddConfig.gitRemoteUrl(specRoot) || 'git@gitlab.example.com:biz/xxx-sdd-specs.git';
   const sddYamlPath = path.join(cwd, '.sdd.yaml');
@@ -1390,7 +1264,7 @@ function attachCodeRepoLite(codeRepoRoot, specRepoRoot, options = {}) {
   }
   console.log(`   ✓ sdd.specPath = ${linked.path}`);
 
-  // 部署代码仓全部 Git hooks（commit-msg + pre-commit + pre-push）
+  // 部署轻量关联 Hook，并迁移可识别的旧门禁
   deployCodeRepoHooks(cwd, specRoot, options);
 
   return { ok: true, repo: label, path: cwd, specPath: linked.path };
@@ -1470,7 +1344,13 @@ function deployMonoSddYaml(cwd = process.cwd(), options = {}) {
     : '';
 
   if (fs.existsSync(target)) {
-    const existing = fs.readFileSync(target, 'utf8');
+    let existing = fs.readFileSync(target, 'utf8');
+    const placeholder = fs.readFileSync(path.join(getPackagePath(), 'templates/dot-sdd.yaml'), 'utf8');
+    if (existing === placeholder && specRel) {
+      fs.copyFileSync(target, target + '.pre-mono.bak');
+      existing = `version: 1\nlayout: mono\n`;
+      fs.writeFileSync(target, existing, 'utf8');
+    }
     if (/^layout:\s*mono\s*$/m.test(existing)) {
       if (specRel && !new RegExp(`^spec_path:\\s*${specRel.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\s*$`, 'm').test(existing)) {
         // 已有 mono 但缺/错 spec_path：补写相对路径
@@ -1927,7 +1807,7 @@ async function main() {
         removeOuterSkywalk(workspaceRoot);
 
         deployMonoSddYaml(workspaceRoot, { specPathRelative: specPackage.name });
-        // 部署代码仓全部 Git hooks（commit-msg + pre-commit + pre-push）
+        // 部署轻量关联 Hook，并迁移可识别的旧门禁
         // 单仓 mono：hook 通过 .sdd-spec-root 定位包裹包的 skywalk-sdd/git-hooks/
         deployCodeRepoHooks(workspaceRoot, specPackage.abs);
         const linked = sddConfig.setSpecPath(workspaceRoot, specPackage.abs, {
@@ -1947,7 +1827,7 @@ async function main() {
         });
         writeSddSpecRootHint(workspaceRoot, specPackage.abs);
         removeOuterSkywalk(workspaceRoot);
-        deployDotSddYaml(workspaceRoot);
+        deployMonoSddYaml(workspaceRoot, { specPathRelative: specPackage.name });
       }
     }
   } else if (!skipOpenspec) {

package/lib/managed-hook-hashes.json

@@ -0,0 +1,24 @@
+{
+  "pre-commit": [
+    "497f012da027df5c26af3c501126e9a1c26276b038ee3b1edaaf5ab4401aa95c",
+    "7322d9aecafb497a5f40171a6bd7daeaadd7d2056b4a253cb0ee1a128faea36e",
+    "8fcdd74a3d2afaa823f9038c477c9dfd6fe53e2bccbe48cecd01535794862e4a",
+    "c8546c6c96adc3ecc32a15a689c59189543c2454f47998c46fbd5a0bf810cf30",
+    "e3b6776af51df76ff04b528152d0049a6c45d94d96a19bd2bc5ca2cc9786b22c"
+  ],
+  "pre-push": [
+    "405debb5e6f9186e95b727e6013b06ef3e06c598b6d2b96678d34554d3530e8c",
+    "461abd16663757c5a092103ac2ecae8453891c0c817d1c763369e0cdd0a8ec7b",
+    "80f710ff647ce8b216fb1c081fb3e22f6ee8be25847b6d02921668ba83fb1965",
+    "d49eb8794fde4b0d7847a876cc7083d161b290a44990ff8a036c2ebb8a00ec21",
+    "e6e125cbf9d7424c01b249ce03197cef9e1923ed2974a53656084488a0de60c4",
+    "ebf628481ae93ac0c4c6649b204449f6825291dc6b6550a71563bebec1f3ad92"
+  ],
+  "commit-msg": [
+    "15083d5165bff965ab2feba9a55dfedcecd54cb577c06fd11f4d1b9672d978b6",
+    "3b0ee15f5a126d159e14c5a3681cb7820cbf9c5e0c134ee6812053bc34330b85",
+    "6db7adbf17905bf14915d7e57a3c5ac46030ee3282fea5d5b211c80065406d48",
+    "9c5a86761b36d71b655f804a822eff675a244175799736c803e1f7379c638609",
+    "fc390776720393f100712fa02d5e143c2927fbb0d605a4a0242824ff7ea84574"
+  ]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kld-sdd",
-  "version": "2.7.8-2",
+  "version": "2.7.8-3",
   "description": "KLD SDD OpenSpec 项目初始化工具 - 一键部署 SDD skills",
   "main": "index.js",
   "bin": {
@@ -9,7 +9,7 @@
   },
   "scripts": {
     "bench:check": "node test/benchmark-check.cjs",
-    "test": "node --test test/execution-friction.test.cjs test/kb-fact-lifecycle.test.cjs test/workflow-usability.test.cjs test/check-efficiency.test.cjs && node test/external-key.cjs && node test/change-key.cjs && node test/modules-and-sdd-config.cjs && node test/active-changes.cjs && node test/hook-layouts.cjs && node test/spec-package-init.cjs && node test/prompt-spec-path.cjs && node test/workspace-layout.cjs && node test/ontology-release-blockers.cjs && node test/ontology-semantic-core.cjs && node test/ontology-identity-versioning.cjs && node test/ontology-identity-continuity.cjs && node test/ontology-state-transaction.cjs && node test/ontology-process-concurrency.cjs && node test/ontology-observer-convergence.cjs && node test/ontology-working-runtime.cjs && node test/ontology-stage-materialization.cjs && node test/ontology-template-contract.cjs && node test/ontology-cli-archive.cjs && node test/archive-package-producer.cjs && node --test test/evidence-integrity-oracle.cjs test/evidence-integrity-wiring.cjs test/change-report-correctness.cjs test/report-metrics-correctness.cjs test/change-report-model-ui.cjs && node test/validate-skills-bundle.cjs && node test/tool-profiles.cjs && node test/settings-merge.cjs && node test/command-bridge.cjs && node test/codebuddy-hooks.cjs && node test/skill-content-contract.cjs && node test/init-agent-profiles.cjs && node test/init-report-runtime.cjs && node test/init-output-verbosity.cjs && node --test test/usage-contract.test.cjs test/user-config.test.cjs test/usage-runtime-removal.test.cjs skywalk-sdd/usage-reporter.test.cjs skywalk-sdd/usage-reporting.test.cjs && node test/progress-package-artifact.test.cjs && node --test test/progress-package-install.e2e.cjs && node test/consistency-check-core.cjs"
+    "test": "node --test test/delivery-hooks.test.cjs test/execution-friction.test.cjs test/kb-fact-lifecycle.test.cjs test/workflow-usability.test.cjs test/check-efficiency.test.cjs && node test/external-key.cjs && node test/change-key.cjs && node test/modules-and-sdd-config.cjs && node test/active-changes.cjs && node test/hook-layouts.cjs && node test/spec-package-init.cjs && node test/prompt-spec-path.cjs && node test/workspace-layout.cjs && node test/ontology-release-blockers.cjs && node test/ontology-semantic-core.cjs && node test/ontology-identity-versioning.cjs && node test/ontology-identity-continuity.cjs && node test/ontology-state-transaction.cjs && node test/ontology-process-concurrency.cjs && node test/ontology-observer-convergence.cjs && node test/ontology-working-runtime.cjs && node test/ontology-stage-materialization.cjs && node test/ontology-template-contract.cjs && node test/ontology-cli-archive.cjs && node test/archive-package-producer.cjs && node --test test/evidence-integrity-oracle.cjs test/evidence-integrity-wiring.cjs test/change-report-correctness.cjs test/report-metrics-correctness.cjs test/change-report-model-ui.cjs && node test/validate-skills-bundle.cjs && node test/tool-profiles.cjs && node test/settings-merge.cjs && node test/command-bridge.cjs && node test/codebuddy-hooks.cjs && node test/skill-content-contract.cjs && node test/init-agent-profiles.cjs && node test/init-report-runtime.cjs && node test/init-output-verbosity.cjs && node --test test/usage-contract.test.cjs test/user-config.test.cjs test/usage-runtime-removal.test.cjs skywalk-sdd/usage-reporter.test.cjs skywalk-sdd/usage-reporting.test.cjs && node test/progress-package-artifact.test.cjs && node --test test/progress-package-install.e2e.cjs && node test/consistency-check-core.cjs"
   },
   "keywords": [
     "kld",

package/skywalk-sdd/index.cjs

@@ -8610,7 +8610,7 @@ SDD Telemetry CLI - 流程度量采集工具
   check-task 扫描变更目录 tasks.md 并勾选指定 task_id
   archive-docs 将 Simple/Full spec 变更真实移动到 openspec/changes/archive/，并可结束 archive 阶段生成报告
   kb-upload 知识库上传（文件夹自动打包 / zip 直传），支持随时入库
-  semantic-identity 生成或复用实体/版本 ID（8 位十六进制）；无需网络和中央 ID 服务
+  semantic-identity 生成或复用实体/版本 ID（完整 UUID，界面可显示短标识）；无需网络和中央 ID 服务
   semantic-scan 只读解析并校验当前 Change
   semantic-reconcile 全量对账文件与本地工作态本体实例
   semantic-check 全量对账并在通过时标记 pending；--include-tasks 同时返回任务状态、评审输入清单和程序耗时

package/skywalk-sdd/kb-upload.cjs

@@ -332,6 +332,7 @@ async function main() {
   try {
     // ── Zip 模式 ──
     if (args.package) {
+      if (args['validate-only']) throw new Error('--validate-only 仅支持 --folder/--change 本地语义校验；未执行归档上传');
       const zipPath = path.resolve(args.package);
       if (!fs.existsSync(zipPath)) {
         throw new Error(`zip 文件不存在: ${zipPath}`);
@@ -370,9 +371,12 @@ async function main() {
       changeName = path.basename(folderPath);
     }
 
-    const expectedFolder = path.resolve(specRoot, 'openspec', 'changes', changeName);
-    if (path.resolve(folderPath) !== expectedFolder || !expectedFolder.startsWith(path.resolve(specRoot, 'openspec', 'changes') + path.sep)) {
-      throw new Error('文件夹上传仅接受当前 Spec 仓 openspec/changes/<change>；已归档内容请用 --zip 指定归档包');
+    const changesRoot = fs.realpathSync(path.resolve(specRoot, 'openspec', 'changes'));
+    const expectedPath = path.resolve(changesRoot, changeName);
+    const expectedFolder = fs.existsSync(expectedPath) ? fs.realpathSync(expectedPath) : expectedPath;
+    const suppliedFolder = fs.existsSync(folderPath) ? fs.realpathSync(folderPath) : path.resolve(folderPath);
+    if (suppliedFolder !== expectedFolder || !expectedFolder.startsWith(changesRoot + path.sep)) {
+      throw new Error('文件夹上传仅接受当前 Spec 仓 openspec/changes/<change>；已归档内容请用 --package 指定归档包');
     }
 
     if (!fs.existsSync(folderPath)) {
@@ -389,19 +393,6 @@ async function main() {
     // 1. 校验必需文件
     validateRequiredFiles(folderPath, minimumLevel);
 
-    // 2. 解析 project_id
-    const projectId = resolveProjectId(specRoot);
-    console.log(`✓ project_id: ${projectId}`);
-
-    // 3. 读取 KB 配置 + 预检
-    const state = readKbState(specRoot);
-    if (!state.apiKey) {
-      throw new Error('KB 配置中无 apiKey，请运行 /opsx-kb-config 配置知识库。');
-    }
-    const target = resolveUploadTarget(state, { spaceId: args['space-id'], kbId: args['kb-id'] });
-    preCheckProjectId(projectId, state, target);
-    const cacheContext = { api: state.api || 'http://localhost:8090/api', spaceId: target.spaceId, kbId: target.kbId };
-
     // 4. 仅校验模式（含语义校验）
     if (args['validate-only']) {
       const runtime = require('./ontology/runtime.cjs');
@@ -417,10 +408,23 @@ async function main() {
         throw new Error(`语义校验失败:\n${errors.join('\n')}`);
       }
       console.log(`✓ 语义校验通过 (profile: ${semanticResult.profile}, revision: ${semanticResult.revision})`);
-      console.log('\n✓ 校验完成（--validate-only，未上传）');
+      console.log('\n✓ 本地语义校验完成（--validate-only，未联网；不代表权限、发布基线或入库已验证）');
       return;
     }
 
+    // 2. 解析 project_id
+    const projectId = resolveProjectId(specRoot);
+    console.log(`✓ project_id: ${projectId}`);
+
+    // 3. 读取 KB 配置 + 预检
+    const state = readKbState(specRoot);
+    if (!state.apiKey) {
+      throw new Error('KB 配置中无 apiKey，请运行 /opsx-kb-config 配置知识库。');
+    }
+    const target = resolveUploadTarget(state, { spaceId: args['space-id'], kbId: args['kb-id'] });
+    preCheckProjectId(projectId, state, target);
+    const cacheContext = { api: state.api || 'http://localhost:8090/api', spaceId: target.spaceId, kbId: target.kbId };
+
     // 5. 构建 Archive Package
     console.log('');
     const { zipPath, manifest, stagingDir } = buildPackageFromFolder(specRoot, changeName, {

package/skywalk-sdd/lib/test-execution.cjs

@@ -17,6 +17,26 @@ function parseCounts(output) {
       && total === passed + failed + (skipped || 0) + (todo || 0)) {
     return { counts_known: true, passed, failed, skipped: (skipped || 0) + (todo || 0) };
   }
+  // Surefire/Failsafe print per-class counts and a Results section. Count only
+  // the latter, once per module/execution, to avoid double-counting classes.
+  const summaries = [];
+  let inResults = false;
+  for (const raw of output.replace(/\u001b\[[0-9;]*m/g, '').split(/\r?\n/)) {
+    const line = raw.replace(/^\[(?:INFO|WARNING|ERROR)\]\s*/, '').trim();
+    if (line === 'Results:') { inResults = true; continue; }
+    if (!inResults) continue;
+    const match = /^Tests run:\s*(\d+),\s*Failures:\s*(\d+),\s*Errors:\s*(\d+),\s*Skipped:\s*(\d+)\b/.exec(line);
+    if (!match) continue;
+    const [, count, failures, errors, ignored] = match.map(Number);
+    if (count < failures + errors + ignored) return { counts_known: false };
+    summaries.push({ passed: count - failures - errors - ignored, failed: failures + errors, skipped: ignored });
+    inResults = false;
+  }
+  if (summaries.length) {
+    return summaries.reduce((sum, item) => ({ counts_known: true, passed: sum.passed + item.passed,
+      failed: sum.failed + item.failed, skipped: sum.skipped + item.skipped }),
+    { counts_known: true, passed: 0, failed: 0, skipped: 0 });
+  }
   return { counts_known: false };
 }