kld-sdd 2.7.8-1 → 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

@@ -82,3 +82,75 @@ SDD 应帮助团队留下三类东西：明确的业务约定、能够证明实
 新增回归覆盖 Full/Simple 结果等价、正文增改删后的重新校验、跨 Change 身份冲突、strict profile、结束时重新解析、strict JSON 记录拒绝占位值，以及八种 Agent 的参考文件渲染。消费方需要重新安装/更新技能和 skywalk-sdd 运行时才能使用新参数；只更新技能文件会导致旧运行时缺少合并输出。
 
 验证结果（2026-09-08，本次 Check 优化）：完整 `npm test` 通过，包含新增 6 组 Check 回归与全部既有用例；`npm run bench:check` 的 7 轮结论与任务计数等价断言全部通过。
+
+## 2026-09-10：真实执行与故障恢复
+
+本次承接已发布的 `2.7.8-1`，继续提交在 `codex/sdd-usability`。以下新增能力尚未重新发布 npm；原有身份、入库协议、七种 Skill 使用上报保持兼容。
+
+- `kld-sdd log` 修正为实际打包的 `index.cjs` 入口。strict 记录失败会保留 details 文件，成功持久化后才清理。
+- `test-run` 执行真实命令，保存退出码、耗时、原始 stdout/stderr 及 SHA-256。当前自动识别 Node TAP/原生测试摘要；未识别的 runner 仍保存输出，标记计数未知，不能自动完成任务。
+- `test-run --completion-file` 为明确声明的任务关联实际测试事件并同步 checkbox。命令执行成功不等于业务覆盖充分，任务与测试的对应关系仍需评审核验；缺少测试、路径错误、超时不能记成有效 RED。
+- `check-record` 接收实际检查项与真实评审身份，自动计算分类统计、任务缺口和结果，可通过 `--end-event-id` 一次记录并结束。按预检 profile 重新核对正文和历史身份；变化时拒绝旧评审。结束阶段复用本次刚完成的校验，避免再跑一次同样的对账。
+- Archive 在启动归档阶段前运行 doctor；终态通知独立记为 `run_end`，旧 `stage_end + run_ended` 在计算时兼容归一化，避免虚增阶段或孤儿日志。通知保留，原始旧日志不改写。
+- 修复进程锁发布窗口：完整锁文件原子发布，其他进程不能把尚未写完的锁当作失效锁抢走。
+- 文档按实际业务决策与验收行为组织，不为填模板反复复制背景、堆空章节或按每个参数值拆一次任务。
+
+详细参数与示例在 [Apply 参考](templates/skills/kld-sdd/opsx-apply/reference.md) 和 [Check 指南](templates/skills/kld-sdd/opsx-check/SKILL.md)。新命令需要更新运行时和 Skills，旧 `record --strict` 仍可使用。
+
+验证：完整 `npm test` 通过；新增 19 个真实执行/恢复回归，涵盖测试输出篡改、零测试、超时、RED、任务关联、旧评审拒绝、单次最终复核、真实归档和六进程竞争。打包及初始化器均部署两个新模块，安装后的真实入口也有回归覆盖。预检基准七轮中位数由 294.6 ms 降至 156.3 ms，减少 46.9%；它仅测程序预检，不代表模型评审总耗时。
+
+本机独立后端联调确认七种 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/bin/kld-sdd-init.js

@@ -16,7 +16,7 @@ const args = process.argv.slice(2);
 
 if (args[0] === 'log') {
   // Telemetry CLI 模式
-  require('../skywalk-sdd/index.js').main();
+  require('../skywalk-sdd/index.cjs').main();
 } else if (args[0] === 'link-spec') {
   const sddConfig = require('../skywalk-sdd/ontology/sdd-config.cjs');
   const pathArg = args.find((item) => item.startsWith('--path='));

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

@@ -1018,6 +1018,13 @@ function deployTelemetryDataDir(targetCwd = process.cwd()) {
   if (!fs.existsSync(sharedLibDir)) {
     fs.mkdirSync(sharedLibDir, { recursive: true });
   }
+  for (const name of ['test-execution.cjs', 'check-review.cjs']) {
+    const src = path.join(pkgPath, 'skywalk-sdd', 'lib', name);
+    if (!fs.existsSync(src)) throw new Error(`E_INIT_MISSING_CRITICAL: lib/${name} 源文件缺失`);
+    fs.copyFileSync(src, path.join(sharedLibDir, name));
+    deployedModules += 1;
+    vlog(`   ✓ 部署 skywalk-sdd/lib/${name}`);
+  }
   const sharedSrc = path.join(pkgPath, 'skywalk-sdd', 'lib', 'shared.cjs');
   const sharedDst = path.join(sharedLibDir, 'shared.cjs');
   if (fs.existsSync(sharedSrc)) {
@@ -1144,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）');
@@ -1154,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);
@@ -1233,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 };
 }
@@ -1285,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;
-  }
-  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/');
+  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);
   }
-
-  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 = {}) {
@@ -1357,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');
@@ -1383,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 };
@@ -1463,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：补写相对路径
@@ -1920,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, {
@@ -1940,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-1",
+  "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/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",