kld-sdd 2.7.8-2 → 2.7.8-4

package/skywalk-sdd/ontology/spec-detect.cjs

@@ -0,0 +1,421 @@
+'use strict';
+
+/**
+ * spec 目录识别 —— **唯一判据入口**。
+ *
+ * 本模块只回答两个问题，不负责定位（定位在 resolve-spec-root.cjs）：
+ *
+ *   1. 「这个目录是不是 spec 包？」        → classifySpecDir / isSpecCandidate
+ *   2. 「候选有哪些、优先级如何？」        → detectSpecCandidates
+ *
+ * 为什么需要分级而不是单一布尔值：两类调用方的松紧要求本来就不同。
+ *
+ * - **检测**（"这个目录是不是当前项目的 spec 仓"）→ 严，避免误报。
+ *   例：`sddmult-sdd-specs` 是个只有 .git 的空壳，若仅凭目录名就认定，
+ *   会被当成 spec 包采纳（init 往里灌内容、sync-repos 把它的路径写进代码仓
+ *   git config）。故名称判定必须附带"至少一项 SDD 产物"。
+ * - **校验**（"用户显式给的路径能不能当 spec 用"）→ 宽，接受半成品。
+ *   例：`--skip-openspec` 时 `openspec/changes` 永不创建，四结构必然不齐，
+ *   但包裹包是合法的。
+ *
+ * 因此不是"同一个布尔值到处用"，而是**同一个函数返回等级，调用方按需取阈值**。
+ *
+ * 等级（tier 越小优先级越高）：
+ *
+ * | tier | 来源            | 判据                                              |
+ * |------|-----------------|---------------------------------------------------|
+ * | 0    | 显式声明        | `.sdd-spec-root` / `git config` / `.sdd.yaml mono` |
+ * |      |                 | / `.sdd-workspace.yaml spec_path`                  |
+ * | 1    | 四结构齐全      | modules.yaml + sdd.config.yaml + openspec/changes |
+ * |      |                 | + openspec/specs/overview.md                       |
+ * | 2    | 目录名          | `*-sdd-specs`（**含预填空壳**：用户先建目录后填充） |
+ * | —    | 非候选          | 无结构证据且目录名不匹配                           |
+ *
+ * 依赖方向：本模块是叶子节点，加载期不 require 任何其它 ontology 模块
+ * （需要 sdd-config / workspace-layout 时在函数内惰性 require），
+ * 因此 workspace-layout / resolve-spec-root / sdd-config 都可以安全依赖它。
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+/** tier 常量 */
+const TIER = Object.freeze({
+  /** 显式声明：.sdd-spec-root / git config sdd.specPath / .sdd.yaml layout: mono */
+  DECLARED: 0,
+  /** 四结构齐全 */
+  STRUCTURE: 1,
+  /** 目录名 `*-sdd-specs`（含预填空壳） */
+  NAME: 2,
+});
+
+/**
+ * 四结构标记 —— tier 1 判据，**四项必须同时满足**。
+ *
+ * 与"名称判定"的关键区别：四结构不看目录名，因此用户自定义命名的包裹包
+ * （如 `erp-specs`）只要内容齐全也能被识别。
+ */
+const SPEC_STRUCTURE_MARKS = Object.freeze([
+  'modules.yaml',
+  'sdd.config.yaml',
+  'openspec/changes',
+  'openspec/specs/overview.md',
+]);
+
+/**
+ * 半成品标记 —— 用于「显式给定路径」的宽松校验（任一满足即可）。
+ *
+ * 为什么比四结构宽：`--skip-openspec` 下 `openspec/changes` 永不创建
+ *（openspec init 是唯一创建者），但包裹包合法。此判据只用于
+ * `validateSpecPath({ allowNestedPackage: true })` —— 路径是用户显式给的，
+ * 只需确认"内容像 spec 包"，无需确认"是不是当前项目的 spec 仓"。
+ */
+const SPEC_ARTIFACT_MARKS = Object.freeze([
+  'modules.yaml',
+  'sdd.config.yaml',
+  'openspec/changes',
+]);
+
+/**
+ * 候选来源的中文标签（供 init / uninstall / sync-repos 展示，唯一真相源）。
+ *
+ * **来源表示「怎么找到的」，判据强度由候选的 `tier` 字段承载**：
+ * - hint / git / mono  显式声明（权威）
+ * - workspace          工作区探测（子仓目录被识别为 spec 包）
+ * - scan               裸目录扫描命中（结构或命名，具体见 `evidence`）
+ *
+ * ⚠️ 历史文案 `workspace: '工作区探测：子仓结构判据命中'` 有误 —— 该来源
+ * 实际也可能由**目录名** `*-sdd-specs` 命中（空壳子仓即如此）。故标签不再
+ * 声称具体判据，避免与 `tier` 冲突。
+ */
+const SPEC_SOURCE_LABELS = Object.freeze({
+  hint: '权威：.sdd-spec-root 指向',
+  git: '权威：git config sdd.specPath',
+  mono: '权威：.sdd.yaml layout: mono',
+  'workspace-yaml': '权威：.sdd-workspace.yaml spec_path',
+  scan: '推测：目录内容或命名命中',
+});
+
+/** tier 内来源优先级（数值越小越靠前） */
+const SOURCE_RANK = Object.freeze({
+  hint: 0,
+  git: 1,
+  mono: 2,
+  'workspace-yaml': 3,
+  scan: 4,
+});
+
+/**
+ * 目录名是否符合 `*-sdd-specs` 命名约定。
+ *
+ * 单独导出是因为「名称命中」与「结构命中」是两个不同强度的证据，
+ * 调用方有时需要区分（如提示文案、诊断）。
+ *
+ * @param {string} dir
+ * @returns {boolean}
+ */
+function isSpecDirName(dir) {
+  if (!dir) return false;
+  const name = path.basename(path.resolve(dir)).toLowerCase();
+  return /-sdd-specs$/.test(name) || name.endsWith('sdd-specs');
+}
+
+/** 列出实际存在的标记（相对路径用 posix 形式，便于展示与断言） */
+function listExistingMarks(dir, marks) {
+  return marks.filter((mark) => {
+    try {
+      return fs.existsSync(path.join(dir, ...mark.split('/')));
+    } catch {
+      return false;
+    }
+  });
+}
+
+/**
+ * 对目录做分级判定 —— **本模块的核心，全仓唯一的 spec 判据**。
+ *
+ * @param {string} dir 候选目录
+ * @returns {{tier: number, source: 'structure'|'name', evidence: string[]}|null}
+ *          null 表示不是 spec 候选
+ */
+function classifySpecDir(dir) {
+  if (!dir) return null;
+  const abs = path.resolve(dir);
+  let st;
+  try {
+    st = fs.statSync(abs);
+  } catch {
+    return null;
+  }
+  if (!st.isDirectory()) return null;
+
+  // tier 1：四结构齐全（不看目录名 —— 支持用户自定义命名）
+  const structure = listExistingMarks(abs, SPEC_STRUCTURE_MARKS);
+  if (structure.length === SPEC_STRUCTURE_MARKS.length) {
+    return { tier: TIER.STRUCTURE, source: 'structure', evidence: structure };
+  }
+
+  // tier 2：目录名命中。**空壳（evidence 为空）仍是候选** ——
+  // 典型场景是用户预建目录待填充；由调用方按 tier 排序决定取舍。
+  if (!isSpecDirName(abs)) return null;
+  return {
+    tier: TIER.NAME,
+    source: 'name',
+    evidence: listExistingMarks(abs, SPEC_ARTIFACT_MARKS),
+  };
+}
+
+/**
+ * 严格判据：是否可作为 spec 候选（检测用）。
+ *
+ * 与历史 `looksLikeSpecRepo` 语义等价 —— 名称命中**或**四结构齐全。
+ * 保留"名称即命中"是刻意的：空壳 `*-sdd-specs` 是预填场景，必须入选。
+ *
+ * @param {string} dir
+ * @returns {boolean}
+ */
+function isSpecCandidate(dir) {
+  return classifySpecDir(dir) !== null;
+}
+
+/**
+ * 校验判据：目录是否可作为 kb-state.json 的宿主 / spec 根。
+ *
+ * 比 `isSpecCandidate` 多一条 `openspec/` 兜底 —— 半成品包裹包
+ * （`--skip-openspec` 产物，只有 openspec/ 目录树）也是合法的 spec 根。
+ *
+ * @param {string} dir
+ * @returns {boolean}
+ */
+function isSpecPackageRoot(dir) {
+  if (!dir) return false;
+  const abs = path.resolve(dir);
+  if (classifySpecDir(abs)) return true;
+  try {
+    return fs.existsSync(path.join(abs, 'openspec'));
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * 宽松判据：目录内容是否"像 spec 包"（任一产物标记存在）。
+ *
+ * 仅用于用户**显式给定**路径的校验（`validateSpecPath` 的 allowNestedPackage）。
+ * 不可用于检测 —— 单仓代码仓根可能有 modules.yaml 而无 openspec。
+ *
+ * @param {string} dir
+ * @returns {boolean}
+ */
+function hasSpecPackageContent(dir) {
+  if (!dir) return false;
+  const abs = path.resolve(dir);
+  try {
+    if (!fs.statSync(abs).isDirectory()) return false;
+  } catch {
+    return false;
+  }
+  return listExistingMarks(abs, SPEC_ARTIFACT_MARKS).length > 0;
+}
+
+/** 向上逐级读取 `.sdd-spec-root` 指针（内容为相对路径） */
+function resolveHintUpward(anchorRoot) {
+  let current = path.resolve(anchorRoot);
+  const stop = path.parse(current).root;
+  for (;;) {
+    const hintPath = path.join(current, '.sdd-spec-root');
+    if (fs.existsSync(hintPath)) {
+      try {
+        const rel = String(fs.readFileSync(hintPath, 'utf8') || '')
+          .trim()
+          .split(/\r?\n/)[0]
+          .trim();
+        if (rel) {
+          const abs = path.resolve(current, rel);
+          if (fs.existsSync(abs)) return abs;
+        }
+      } catch { /* 指针损坏：继续向上，不阻断 */ }
+    }
+    if (current === stop) break;
+    current = path.dirname(current);
+  }
+  return null;
+}
+
+/** 向上逐级查找 `.sdd.yaml` 的 `layout: mono` 声明 */
+function resolveMonoUpward(anchorRoot) {
+  let current = path.resolve(anchorRoot);
+  const stop = path.parse(current).root;
+  for (;;) {
+    try {
+      const sddConfig = require('./sdd-config.cjs');
+      if (sddConfig.isMonoLayout(current)) {
+        const resolved = sddConfig.resolveMonoSpecRoot(current);
+        if (resolved && fs.existsSync(resolved)) return resolved;
+      }
+    } catch { /* sdd-config 不可用时跳过该来源 */ }
+    if (current === stop) break;
+    current = path.dirname(current);
+  }
+  return null;
+}
+
+/**
+ * 向上逐级查找 `.sdd-workspace.yaml` 的 `spec_path` 声明（多仓布局）。
+ *
+ * 与 `resolveMonoUpward` 的区别：`.sdd.yaml layout: mono` 描述**单仓内**的包裹包，
+ * `.sdd-workspace.yaml` 描述**多仓工作区**的编排（spec 是兄弟目录的独立 Git 仓）。
+ * 二者都是显式声明，属权威来源。
+ *
+ * 解析委托 `workspace-layout.parseWorkspaceYaml`（唯一解析实现），避免此处
+ * 再写一遍正则 —— 历史上 skills 的 `opsx-consistency-check/scripts.cjs` 就是
+ * 自己解析该文件，导致「权威链不认这个来源、技能自己认」的不一致。
+ *
+ * @param {string} anchorRoot 搜索起点
+ * @returns {string|null} spec 根绝对路径；未声明 / 指向不存在时 null
+ */
+function resolveWorkspaceYamlUpward(anchorRoot) {
+  let current = path.resolve(anchorRoot);
+  const stop = path.parse(current).root;
+  for (;;) {
+    try {
+      const workspaceLayout = require('./workspace-layout.cjs');
+      const loaded = workspaceLayout.loadWorkspaceFile(current);
+      if (loaded.ok && loaded.data && loaded.data.spec_path) {
+        // spec_path 相对清单所在目录解析（清单是工作区级文件）
+        const abs = path.resolve(current, loaded.data.spec_path);
+        if (fs.existsSync(abs)) return abs;
+      }
+    } catch { /* 解析异常：继续向上，不阻断 */ }
+    if (current === stop) break;
+    current = path.dirname(current);
+  }
+  return null;
+}
+
+/**
+ * 枚举 spec 候选集合，按优先级排序。
+ *
+ * 这是 init / uninstall / sync-repos 三个 CLI 场景**共用**的入口：
+ * 三处都要求「多候选时让用户单选」，故必须返回集合而非单值。
+ *
+ * 来源与 tier：
+ * - hint / git / mono          → tier 0（显式声明，权威）
+ * - 子仓 / 子目录 / 根自身命中  → tier 1（四结构）或 tier 2（名称）
+ *
+ * 排序：tier 升序 → 来源优先级 → 名称升序（保证输出稳定、可断言）。
+ *
+ * @param {string} anchorRoot 探测起点（工作目录 / 工作区根）
+ * @param {{gitSpecPath?: string, includeRoot?: boolean}} [options]
+ *        gitSpecPath 由调用方读取后传入，避免本模块反向依赖 sdd-config 的 git 逻辑
+ * @returns {Array<{abs: string, name: string, source: string, tier: number, evidence: string[]}>}
+ */
+function detectSpecCandidates(anchorRoot, options = {}) {
+  const root = path.resolve(anchorRoot || process.cwd());
+  const includeRoot = options.includeRoot !== false;
+  const out = [];
+  const seen = new Set();
+
+  const push = (candidate, source, tier, evidence) => {
+    if (!candidate) return;
+    const abs = path.resolve(candidate);
+    if (seen.has(abs)) return;
+    let st;
+    try {
+      st = fs.statSync(abs);
+    } catch {
+      return;
+    }
+    if (!st.isDirectory()) return;
+    seen.add(abs);
+    out.push({
+      abs,
+      name: path.basename(abs),
+      source,
+      tier,
+      evidence: evidence || [],
+    });
+  };
+
+  // ── tier 0：显式声明（权威）──────────────────────────────
+  push(resolveHintUpward(root), 'hint', TIER.DECLARED, ['.sdd-spec-root']);
+  push(options.gitSpecPath, 'git', TIER.DECLARED, ['git config sdd.specPath']);
+  push(resolveMonoUpward(root), 'mono', TIER.DECLARED, ['.sdd.yaml layout: mono']);
+  push(resolveWorkspaceYamlUpward(root), 'workspace-yaml', TIER.DECLARED,
+    ['.sdd-workspace.yaml spec_path']);
+
+  // ── tier 1/2：结构 / 名称判据扫描（来源统一记 'scan'）──────
+  // 判据强度由 `tier` 承载，来源只表示「怎么找到的」，不表示判据类型 ——
+  // 否则 UI 无法解释「同一来源却强度不同」。具体命中判据见 `evidence`。
+  const pushClassified = (dir) => {
+    const classified = classifySpecDir(dir);
+    if (!classified) return;
+    push(dir, 'scan', classified.tier, classified.evidence);
+  };
+
+  // 根自身
+  if (includeRoot) pushClassified(root);
+
+  // 一级子目录（含非 Git 目录 —— 单仓包裹包不是独立 Git）
+  try {
+    const workspaceLayout = require('./workspace-layout.cjs');
+    for (const child of workspaceLayout.listChildDirectories(root)) {
+      pushClassified(child.abs);
+    }
+  } catch { /* workspace-layout 不可用时退化为仅根目录 */ }
+
+  out.sort((a, b) => {
+    if (a.tier !== b.tier) return a.tier - b.tier;
+    const rankA = SOURCE_RANK[a.source] ?? 99;
+    const rankB = SOURCE_RANK[b.source] ?? 99;
+    if (rankA !== rankB) return rankA - rankB;
+    return a.name.localeCompare(b.name);
+  });
+
+  return out;
+}
+
+/**
+ * 枚举候选集合，并自动读取 `git config --local sdd.specPath` 作为 tier 0 来源。
+ *
+ * 这是 CLI 三个场景（init / uninstall / sync-repos）**共用的唯一枚举入口**。
+ * 历史上 init 与 uninstall 各写了一份完全相同的实现（都只是「读 git config
+ * 后调 listSpecCandidates」），本函数把它收敛为一处。
+ *
+ * 为什么 git 读取放在这里而不是让调用方传入：读取逻辑需要 sdd-config，
+ * 而 sdd-config 顶层 require 本模块 —— 放在函数内惰性 require 可避免加载期
+ * 循环依赖（本模块顶层只依赖 fs/path）。
+ *
+ * @param {string} anchorRoot 探测起点（工作目录 / 工作区根）
+ * @returns {Array<{abs: string, name: string, source: string, tier: number, evidence: string[]}>}
+ */
+function detectSpecCandidatesWithGit(anchorRoot) {
+  const root = path.resolve(anchorRoot || process.cwd());
+  let gitSpecPath = '';
+  try {
+    gitSpecPath = require('./sdd-config.cjs').gitConfig(root, 'sdd.specPath') || '';
+  } catch { /* 非 Git 仓或 git 不可用：跳过该来源 */ }
+  return detectSpecCandidates(root, { gitSpecPath });
+}
+
+/** 取候选来源的中文标签；未知来源原样返回 */
+function specSourceLabel(source) {
+  return SPEC_SOURCE_LABELS[source] || source || '未知来源';
+}
+
+module.exports = {
+  TIER,
+  SPEC_STRUCTURE_MARKS,
+  SPEC_ARTIFACT_MARKS,
+  SPEC_SOURCE_LABELS,
+  SOURCE_RANK,
+  isSpecDirName,
+  classifySpecDir,
+  isSpecCandidate,
+  isSpecPackageRoot,
+  hasSpecPackageContent,
+  resolveWorkspaceYamlUpward,
+  detectSpecCandidates,
+  detectSpecCandidatesWithGit,
+  specSourceLabel,
+};

package/skywalk-sdd/ontology/workspace-layout.cjs

@@ -3,6 +3,10 @@
 const fs = require('fs');
 const path = require('path');
 
+// spec 判据的唯一真相源。spec-detect 对 workspace-layout 的依赖是惰性（函数内
+// require），故此处顶层 require 不构成循环依赖。
+const specDetect = require('./spec-detect.cjs');
+
 const WORKSPACE_FILE = '.sdd-workspace.yaml';
 const IGNORE_DIR_NAMES = new Set([
   'node_modules',
@@ -24,19 +28,19 @@ function isGitRepo(dir) {
   return fs.existsSync(path.join(dir, '.git'));
 }
 
+/**
+ * 是否像 SDD spec 包裹包。
+ *
+ * ⚠️ 判据已收敛到 `spec-detect.cjs#isSpecCandidate`（全仓唯一判据入口），
+ * 本函数保留仅为向后兼容既有调用点，**不得再在此处新增判据**。
+ *
+ * 语义（与 spec-detect 一致）：
+ * - 四结构齐全（modules.yaml + sdd.config.yaml + openspec/changes
+ *   + openspec/specs/overview.md）→ 命中，**不看目录名**
+ * - 目录名 `*-sdd-specs` → 命中（含预填空壳，由 tier 排序决定取舍）
+ */
 function looksLikeSpecRepo(dir) {
-  const name = path.basename(dir).toLowerCase();
-  // 命名约定：*-sdd-specs 目录名直接命中
-  if (/-sdd-specs$/.test(name) || name.endsWith('sdd-specs')) return true;
-  // 结构判据（四项同时满足）：
-  // modules.yaml（模块登记）+ sdd.config.yaml（活动变更登记）
-  // + openspec/changes（变更结构）+ openspec/specs/overview.md（全局契约）
-  return (
-    fs.existsSync(path.join(dir, 'modules.yaml'))
-    && fs.existsSync(path.join(dir, 'sdd.config.yaml'))
-    && fs.existsSync(path.join(dir, 'openspec', 'changes'))
-    && fs.existsSync(path.join(dir, 'openspec', 'specs', 'overview.md'))
-  );
+  return specDetect.isSpecCandidate(dir);
 }
 
 function listChildGitRepos(workspaceRoot) {
@@ -88,7 +92,6 @@ function detectWorkspaceLayout(workspaceRoot = process.cwd()) {
     rootIsGit,
     specRepo: spec,
     codeRepos,
-    allChildGitRepos: children,
   };
 }
 
@@ -228,6 +231,22 @@ function findNestedSpecPackage(parentDir) {
   );
 }
 
+/**
+ * 取候选来源的中文标签；未知来源原样返回。
+ *
+ * ⚠️ 标签表与候选枚举均已收敛到 `spec-detect.cjs`（唯一真相源）：
+ * - 枚举用 `detectSpecCandidates` / `detectSpecCandidatesWithGit`
+ * - 标签用 `spec-detect#specSourceLabel`
+ *
+ * 本模块曾另有一份 `listSpecCandidates`（多出一个 'workspace' 来源标签），
+ * 现已删除 —— 它只是给「扫描已能找到的同一个目录」换个标签，对候选集合
+ * 无增量，反而造成「同一目录两种来源说法」。判据强度统一由候选的 `tier`
+ * 承载（0=显式声明 / 1=四结构 / 2=名称含空壳）。
+ */
+function specSourceLabel(source) {
+  return specDetect.specSourceLabel(source);
+}
+
 /**
  * 确保父目录下存在统一的 SDD 包裹包目录。
  * @param {{ name?: string, initGit?: boolean }} options
@@ -278,18 +297,29 @@ function ensureSpecPackage(parentDir, options = {}) {
   return { name, abs, created: !existed, isGit };
 }
 
+/**
+ * 公开 API —— 只导出「有跨模块消费者」的符号。
+ *
+ * 刻意不导出（函数体保留，模块内部使用）：
+ * - `WORKSPACE_FILE`    仅本模块 loadWorkspaceFile / writeWorkspaceFile 使用
+ * - `listChildGitRepos` 仅 detectWorkspaceLayout 使用
+ * - `parseWorkspaceYaml` 仅 loadWorkspaceFile 使用
+ *
+ * 标签表 `SPEC_SOURCE_LABELS` 已迁至 `spec-detect.cjs`（唯一真相源），
+ * 本模块仅转发 `specSourceLabel()`；如需直接读表请从 spec-detect 引入。
+ *
+ * 如需外部使用请重新加入本表，而不是依赖 `module.exports` 的隐式宽松。
+ */
 module.exports = {
-  WORKSPACE_FILE,
   isGitRepo,
   looksLikeSpecRepo,
-  listChildGitRepos,
   listChildDirectories,
   detectWorkspaceLayout,
-  parseWorkspaceYaml,
   loadWorkspaceFile,
   writeWorkspaceFile,
   findNewCodeRepos,
   deriveSpecPackageName,
   findNestedSpecPackage,
+  specSourceLabel,
   ensureSpecPackage,
 };

package/templates/git-hooks/commit-msg

@@ -1,104 +1,22 @@
 #!/bin/sh
-# KLD SDD Commit-MSG Hook
-# 在下方 SCRIPTS 列表中声明要加载的 .cjs 脚本
-# 删除某行 = 禁用该插件
+# KLD SDD provenance hook v2
 # marker: KLD SDD quality gate
-
-# Git supplies the working tree context; this also supports worktrees and core.hooksPath.
-git_root=$(git rev-parse --show-toplevel 2>/dev/null) || {
-  echo "[SDD] 无法定位当前 Git 工作区"
-  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
-  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:]]*$//')
-  hooks_dir="$(resolve_spec_dir "$spec_rel")/skywalk-sdd/git-hooks"
+# Ordinary commits save work; delivery-check verifies readiness at Apply completion.
+git_root=$(git rev-parse --show-toplevel 2>/dev/null) || exit 0
+spec_path=$(git config --local sdd.specPath 2>/dev/null)
+if [ -z "$spec_path" ] && [ -f "$git_root/.sdd-spec-root" ]; then
+  IFS= read -r spec_path < "$git_root/.sdd-spec-root"
 fi
-if [ -n "$hooks_dir" ] && [ ! -d "$hooks_dir" ]; then
-  echo "[SDD] 已配置的 Spec 路径失效：$hooks_dir"
-  echo "[SDD] 请恢复 Spec 仓，或修正 sdd.specPath / .sdd-spec-root 后重试"
-  exit 1
-fi
-
-# 方法3: 从 git 根向上搜索 skywalk-sdd/git-hooks（spec 仓本身或父级）
-if [ -z "$hooks_dir" ]; then
-  search_dir="$git_root"
-  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
-    # Windows 盘符根（P:/）dirname 后不变，需显式收敛，避免死循环
-    parent_dir="$(dirname "$search_dir")"
-    [ "$parent_dir" = "$search_dir" ] && break
-    search_dir="$parent_dir"
-  done
-fi
-
-if [ -z "$hooks_dir" ]; then
-  echo "[SDD] 未找到 spec 仓的 skywalk-sdd/git-hooks 目录，跳过 commit-msg"
-  exit 0
-fi
-
-# 从配置文件读取插件列表
-config_file="$hooks_dir/hooks.config"
-if [ ! -f "$config_file" ]; then
-  echo "[SDD] ⚠️  配置文件不存在：hooks.config，使用默认插件"
-  SCRIPTS="commit-msg-sdd-trailer.cjs"
-else
-  # 读取 [commit-msg] 段落的配置
-  in_section=0
-  SCRIPTS=""
-  CR=$(printf '\r')
-  while IFS= read -r line; do
-    line=${line%"$CR"}
-    case "$line" in
-      "[commit-msg]") in_section=1 ;;
-      "["*) in_section=0 ;;
-      "#"*|"") ;;
-      *)
-        if [ "$in_section" -eq 1 ]; then
-          SCRIPTS="$SCRIPTS $line"
-        fi
-        ;;
-    esac
-  done < "$config_file"
-fi
-
-executed=0
-failed=0
-for script_name in $SCRIPTS; do
-  script="$hooks_dir/$script_name"
-  if [ ! -f "$script" ]; then
-    echo "[SDD] ❌ 已配置的插件不存在：$script_name"
-    failed=$((failed + 1))
-    continue
-  fi
-  executed=$((executed + 1))
-  echo "[SDD] 执行 commit-msg 插件：$script_name"
-  node "$script" "$1" --project="$git_root" || failed=$((failed + 1))
-done
-
-if [ "$failed" -gt 0 ]; then
-  echo "[SDD] ❌ 共执行 $executed 个 commit-msg 插件，$failed 个失败"
-  exit 1
-elif [ "$executed" -eq 0 ]; then
-  echo "[SDD] 配置已禁用 commit-msg 插件"
+if [ -z "$spec_path" ]; then spec_path="$git_root"; fi
+spec_path=$(printf '%s' "$spec_path" | tr '\\' '/' | tr -d '\r')
+case "$spec_path" in
+  /*|[A-Za-z]:*) ;;
+  *) spec_path="$git_root/$spec_path" ;;
+esac
+runner="$spec_path/skywalk-sdd/git-hooks/commit-msg-runner.cjs"
+if [ -f "$runner" ]; then
+  node "$runner" "$1" --project="$git_root" || echo '[SDD] 关联待补充，本次提交继续' >&2
 else
-  echo "[SDD] ✅ 共执行 $executed 个 commit-msg 插件，全部通过"
+  echo '[SDD] Spec 运行时未就绪，关联待补充；可重装或修正 sdd.specPath，本次提交继续' >&2
 fi
+exit 0

package/templates/git-hooks/commit-msg-runner.cjs

@@ -0,0 +1,44 @@
+#!/usr/bin/env node
+'use strict';
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+// Only the managed provenance worker is advisory. User hooks are never run here.
+const original = process.argv[2];
+let tempDir;
+try {
+  const config = path.join(__dirname, 'hooks.config');
+  if (fs.existsSync(config)) {
+    const text = fs.readFileSync(config, 'utf8');
+    const section = text.split(/\[commit-msg\]\s*\r?\n/)[1]?.split(/^\[/m)[0] || '';
+    if (!section.split(/\r?\n/).some(line => line.trim() === 'commit-msg-sdd-trailer.cjs')) process.exit(0);
+  }
+  if (!String(process.env.KLD_SDD_CHANGE || '').trim()
+      && !fs.existsSync(path.join(__dirname, '../state/delivery-associations'))) {
+    // No explicit or recorded association exists. Avoid starting a second Node
+    // process and loading ontology just to discover that there is nothing to add.
+    const message = fs.readFileSync(original, 'utf8').replace(/^Spec-(?:Change|Revision):[^\n]*\n?/gim, '');
+    fs.writeFileSync(original, message);
+    console.error('[SDD] 本次提交的 Change 待关联；保存不受影响');
+    process.exit(0);
+  }
+  tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'sdd-msg-'));
+  const copy = path.join(tempDir, 'message');
+  fs.copyFileSync(original, copy);
+  const result = spawnSync(process.execPath, [path.join(__dirname, 'commit-msg-sdd-trailer.cjs'), copy, ...process.argv.slice(3)], {
+    encoding: 'utf8', timeout: 1500, maxBuffer: 256 * 1024,
+  });
+  if (result.stderr) process.stderr.write(result.stderr);
+  if (result.status === 0 && !result.error) fs.copyFileSync(copy, original);
+  else {
+    const message = fs.readFileSync(original, 'utf8').replace(/^Spec-(?:Change|Revision):[^\n]*\n?/gim, '');
+    fs.writeFileSync(original, message);
+    console.error('[SDD] 关联待补充（超时或运行失败），本次提交继续');
+  }
+} catch (error) {
+  console.error(`[SDD] 关联待补充：${error.message}；本次提交继续`);
+} finally {
+  if (tempDir) fs.rmSync(tempDir, { recursive: true, force: true });
+}