kld-sdd 2.6.10 → 2.6.12

package/lib/hook-gate-core.js

@@ -50,16 +50,45 @@ function normalizeHookInput(input) {
   return normalized;
 }
 
+function resolveSkywalkDir(dir) {
+  const root = path.resolve(dir || '.');
+  const direct = path.join(root, 'skywalk-sdd');
+  if (
+    fs.existsSync(path.join(direct, 'log.cjs'))
+    || fs.existsSync(path.join(direct, 'log.js'))
+  ) {
+    return direct;
+  }
+  const hintFile = path.join(root, '.sdd-spec-root');
+  if (fs.existsSync(hintFile)) {
+    const rel = String(fs.readFileSync(hintFile, 'utf8') || '')
+      .trim()
+      .split(/\r?\n/)[0]
+      .trim();
+    if (rel) {
+      const nested = path.join(root, rel, 'skywalk-sdd');
+      if (
+        fs.existsSync(path.join(nested, 'log.cjs'))
+        || fs.existsSync(path.join(nested, 'log.js'))
+      ) {
+        return nested;
+      }
+    }
+  }
+  return null;
+}
+
 function hasTelemetryCli(dir) {
-  return fs.existsSync(path.join(dir, 'skywalk-sdd', 'log.cjs')) ||
-    fs.existsSync(path.join(dir, 'skywalk-sdd', 'log.js'));
+  return Boolean(resolveSkywalkDir(dir));
 }
 
 function findProjectRoot(startDir) {
   if (!startDir) return '';
   let current = path.resolve(startDir);
   for (let i = 0; i < 25; i++) {
-    if (hasTelemetryCli(current)) return current;
+    if (hasTelemetryCli(current) || fs.existsSync(path.join(current, '.sdd-spec-root'))) {
+      return current;
+    }
     const parent = path.dirname(current);
     if (parent === current) return '';
     current = parent;
@@ -96,7 +125,10 @@ function safeChangeName(name) {
 }
 
 function findActiveApplyStage(projectRoot) {
-  const stateDir = path.join(projectRoot, 'skywalk-sdd', 'state');
+  const skywalk = resolveSkywalkDir(projectRoot);
+  const stateDir = skywalk
+    ? path.join(skywalk, 'state')
+    : path.join(projectRoot, 'skywalk-sdd', 'state');
   if (!fs.existsSync(stateDir)) return null;
 
   let latest = null;
@@ -118,7 +150,10 @@ function findActiveApplyStage(projectRoot) {
 
 function hasCompletedCheck(projectRoot, changeName) {
   const safeName = safeChangeName(changeName);
-  const eventsChangeDir = path.join(projectRoot, 'skywalk-sdd', 'events', safeName);
+  const skywalk = resolveSkywalkDir(projectRoot);
+  const eventsChangeDir = skywalk
+    ? path.join(skywalk, 'events', safeName)
+    : path.join(projectRoot, 'skywalk-sdd', 'events', safeName);
   if (!fs.existsSync(eventsChangeDir)) return false;
 
   const jsonlFiles = fs.readdirSync(eventsChangeDir)
@@ -316,6 +351,7 @@ module.exports = {
   readStdin,
   parseHookInput,
   normalizeHookInput,
+  resolveSkywalkDir,
   hasTelemetryCli,
   findProjectRoot,
   getProjectRoot,

package/lib/init.js

@@ -862,7 +862,7 @@ function deployTelemetryDataDir(targetCwd = process.cwd()) {
   return true;
 }
 
-function installGitHookShim(cwd, hookName, scriptPath) {
+function installGitHookShim(cwd, hookName, scriptPath, options = {}) {
   const hooksDir = path.join(cwd, '.git', 'hooks');
   if (!fs.existsSync(hooksDir)) {
     return;
@@ -870,11 +870,20 @@ function installGitHookShim(cwd, hookName, scriptPath) {
 
   const hookPath = path.join(hooksDir, hookName);
   const marker = 'KLD SDD quality gate';
+  // Git 把 commit-msg 文件路径放在 $1；--project 等额外参数必须跟在 "$@" 后面，
+  // 否则 trailer 脚本会把 --project=… 误当成 message 文件（argv[2]）。
+  const extraArgs = options.extraArgs || '';
+  const nodeLine = extraArgs
+    ? `  node "${scriptPath}" "$@" ${extraArgs}`
+    : `  node "${scriptPath}" "$@"`;
   const shim = [
     '#!/bin/sh',
     `# ${marker}`,
     `if [ -f "${scriptPath}" ]; then`,
-    `  node "${scriptPath}" "$@"`,
+    nodeLine,
+    'else',
+    `  echo "[kld-sdd] Hook 脚本不存在: ${scriptPath}" >&2`,
+    '  exit 1',
     'fi',
     '',
   ].join('\n');
@@ -882,10 +891,21 @@ function installGitHookShim(cwd, hookName, scriptPath) {
   if (fs.existsSync(hookPath)) {
     const existing = fs.readFileSync(hookPath, 'utf8');
     if (existing.includes(marker)) {
-      console.log(`   ✓ .git/hooks/${hookName} 已包含 SDD 质量门禁`);
-    } else {
-      console.log(`   ℹ️  .git/hooks/${hookName} 已存在，已保留不覆盖；可手动调用 ${scriptPath}`);
+      // 已是 SDD shim：若指向路径变化（如改为引用 spec 仓），允许覆盖升级
+      if (existing.includes(scriptPath) && (!extraArgs || existing.includes(extraArgs.trim()))) {
+        console.log(`   ✓ .git/hooks/${hookName} 已包含 SDD 质量门禁`);
+        return;
+      }
+      fs.writeFileSync(hookPath, shim, 'utf8');
+      try {
+        fs.chmodSync(hookPath, 0o755);
+      } catch {
+        // ignore
+      }
+      console.log(`   ✓ 更新 .git/hooks/${hookName} SDD 质量门禁`);
+      return;
     }
+    console.log(`   ℹ️  .git/hooks/${hookName} 已存在，已保留不覆盖；可手动调用 ${scriptPath}`);
     return;
   }
 
@@ -898,14 +918,52 @@ function installGitHookShim(cwd, hookName, scriptPath) {
   console.log(`   ✓ 安装 .git/hooks/${hookName} SDD 质量门禁`);
 }
 
+/**
+ * 确保 spec 包裹包内有 commit-msg 脚本（供代码仓 Hook 远程引用）。
+ */
+function ensureSpecCommitMsgScript(specRepoRoot, pkgPath = getPackagePath()) {
+  const specRoot = path.resolve(specRepoRoot);
+  const scriptPath = path.join(specRoot, 'skywalk-sdd', 'git-hooks', 'commit-msg-sdd-trailer.cjs');
+  if (fs.existsSync(scriptPath)) return { ok: true, scriptPath };
+
+  const src = path.join(pkgPath, 'templates', 'git-hooks', 'commit-msg-sdd-trailer.cjs');
+  if (!fs.existsSync(src)) {
+    return { ok: false, message: `commit-msg 模板缺失: ${src}` };
+  }
+  const ontologySrc = path.join(pkgPath, 'skywalk-sdd', 'ontology');
+  const ontologyDst = path.join(specRoot, 'skywalk-sdd', 'ontology');
+  if (fs.existsSync(ontologySrc) && !fs.existsSync(path.join(ontologyDst, 'change-key.cjs'))) {
+    copyDir(ontologySrc, ontologyDst);
+  }
+  fs.mkdirSync(path.dirname(scriptPath), { recursive: true });
+  fs.copyFileSync(src, scriptPath);
+  return { ok: true, scriptPath, deployed: true };
+}
+
+/**
+ * 代码仓 commit-msg：只写 .git/hooks，脚本与 ontology 一律用 spec 仓那一份。
+ */
+function installCodeRepoCommitMsgHook(codeRepoRoot, specRepoRoot, options = {}) {
+  const cwd = path.resolve(codeRepoRoot);
+  const ensured = ensureSpecCommitMsgScript(specRepoRoot, options.pkgPath || getPackagePath());
+  if (!ensured.ok) {
+    console.log(`   ⚠️  ${ensured.message}`);
+    return false;
+  }
+  installGitHookShim(cwd, 'commit-msg', ensured.scriptPath, {
+    extraArgs: `--project=${cwd}`,
+  });
+  return 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: 代码仓（只装 Trailer Hook，不装 skills、不装文档门禁）
+ *   full: spec 包裹包（pre-commit/pre-push/commit-msg + CI）
+ *   commit-msg-only: 单仓 Git 根（本仓落 skywalk-sdd/git-hooks；多仓代码仓请用 installCodeRepoCommitMsgHook）
  */
 function deployQualityGateTemplates(targetCwd = process.cwd(), options = {}) {
   const pkgPath = getPackagePath();
@@ -946,12 +1004,12 @@ function deployQualityGateTemplates(targetCwd = process.cwd(), options = {}) {
 }
 
 /**
- * 代码仓轻量接入：只部署 Hook 运行所需 ontology + commit-msg，不部署 skills。
+ * 代码仓轻量接入：只写 .sdd.yaml + sdd.specPath + .git/hooks/commit-msg。
+ * 不在代码仓落 skywalk-sdd/——Hook 脚本与 ontology 引用 spec 包裹包那一份。
  */
 function attachCodeRepoLite(codeRepoRoot, specRepoRoot, options = {}) {
   const cwd = path.resolve(codeRepoRoot);
   const specRoot = path.resolve(specRepoRoot);
-  const pkgPath = options.pkgPath || getPackagePath();
   const label = path.basename(cwd);
 
   if (!workspaceLayout.isGitRepo(cwd)) {
@@ -961,16 +1019,7 @@ function attachCodeRepoLite(codeRepoRoot, specRepoRoot, options = {}) {
     return { ok: false, repo: label, message: `spec 路径不是 Git 仓库: ${specRoot}` };
   }
 
-  console.log(`🔗 轻量接入代码仓（无 skills）: ${label}`);
-
-  // Hook 依赖 ontology + git-hooks；不部署完整 telemetry/skills
-  const dataDir = path.join(cwd, 'skywalk-sdd');
-  const ontologySrc = path.join(pkgPath, 'skywalk-sdd', 'ontology');
-  const ontologyDst = path.join(dataDir, 'ontology');
-  if (fs.existsSync(ontologySrc)) {
-    copyDir(ontologySrc, ontologyDst);
-  }
-  deployQualityGateTemplates(cwd, { mode: 'commit-msg-only' });
+  console.log(`🔗 轻量接入代码仓（无 skywalk-sdd/、无 skills）: ${label}`);
 
   const remote = sddConfig.gitRemoteUrl(specRoot) || 'git@gitlab.example.com:biz/xxx-sdd-specs.git';
   const sddYamlPath = path.join(cwd, '.sdd.yaml');
@@ -996,6 +1045,9 @@ function attachCodeRepoLite(codeRepoRoot, specRepoRoot, options = {}) {
   }
   console.log(`   ✓ sdd.specPath = ${linked.path}`);
 
+  installCodeRepoCommitMsgHook(cwd, specRoot, options);
+  console.log('   ✓ commit-msg → spec 仓 skywalk-sdd/git-hooks/（代码仓不落 skywalk-sdd/）');
+
   return { ok: true, repo: label, path: cwd, specPath: linked.path };
 }
 
@@ -1155,6 +1207,66 @@ function writeSddSpecRootHint(anchorDir, specPackageAbs) {
   return filePath;
 }
 
+/**
+ * 移除工作区 / Git 根上多余的 skywalk-sdd（符号链接或旧完整副本）。
+ * 唯一实体只保留在 *-sdd-specs/skywalk-sdd/。
+ *
+ * 触发条件（满足其一即可）：
+ * - 存在 .sdd-spec-root
+ * - 同级已有 *-sdd-specs/skywalk-sdd（多仓/单仓包裹包）
+ */
+function removeOuterSkywalk(anchorDir) {
+  const anchor = path.resolve(anchorDir);
+  const outer = path.join(anchor, 'skywalk-sdd');
+  let st = null;
+  try {
+    st = fs.lstatSync(outer);
+  } catch (err) {
+    if (err && err.code === 'ENOENT') return { ok: true, removed: false };
+    throw err;
+  }
+
+  const hint = path.join(anchor, '.sdd-spec-root');
+  const hasHint = fs.existsSync(hint);
+  let hasNestedEntity = false;
+  try {
+    for (const name of fs.readdirSync(anchor)) {
+      if (!/-sdd-specs$/i.test(name)) continue;
+      const entity = path.join(anchor, name, 'skywalk-sdd', 'log.cjs');
+      if (fs.existsSync(entity)) {
+        hasNestedEntity = true;
+        break;
+      }
+    }
+  } catch {
+    // ignore
+  }
+
+  if (!hasHint && !hasNestedEntity) {
+    // 无包裹包迹象时不贸然删除（可能是旧平铺布局）
+    return { ok: true, removed: false, skipped: true };
+  }
+
+  try {
+    if (st.isSymbolicLink()) {
+      fs.unlinkSync(outer);
+      console.log('   ✓ 已移除 Git/工作区根多余的 skywalk-sdd 符号链接（实体在包裹包）');
+      return { ok: true, removed: true, mode: 'symlink' };
+    }
+    if (st.isDirectory()) {
+      fs.rmSync(outer, { recursive: true, force: true });
+      console.log('   ✓ 已移除 Git/工作区根多余的 skywalk-sdd/（实体在包裹包）');
+      return { ok: true, removed: true, mode: 'directory' };
+    }
+    fs.unlinkSync(outer);
+    console.log('   ✓ 已移除 Git/工作区根多余的 skywalk-sdd');
+    return { ok: true, removed: true, mode: 'file' };
+  } catch (err) {
+    console.log(`   ⚠️  未能移除根目录 skywalk-sdd/: ${err.message}`);
+    return { ok: false, message: err.message };
+  }
+}
+
 /**
  * 检测当前项目已初始化的 AI 编辑器
  */
@@ -1185,6 +1297,8 @@ function updateGitignore() {
     '.agents/commands/personal-*',
     'skywalk-sdd/events/',
     'skywalk-sdd/state/',
+    '**/skywalk-sdd/events/',
+    '**/skywalk-sdd/state/',
     '.worktrees/'
   ];
 
@@ -1198,9 +1312,11 @@ function updateGitignore() {
 .workbuddy/commands/personal-*
 .agents/commands/personal-*
 
-# SDD Telemetry 数据（本地度量，可选提交；本体 JSON 与报告随 openspec/changes/<change>/ 提交）
+# SDD Telemetry 数据（实体在 *-sdd-specs/skywalk-sdd/；工作区可能是 symlink）
 skywalk-sdd/events/
 skywalk-sdd/state/
+**/skywalk-sdd/events/
+**/skywalk-sdd/state/
 
 # SDD Apply 隔离 worktree（本地临时目录）
 .worktrees/
@@ -1360,8 +1476,6 @@ async function main() {
     deployProfileArtifacts(selectedTools, workspaceRoot, getPackagePath());
 
     if (layout.isWorkspace) {
-      deployTelemetryDataDir(workspaceRoot);
-
       if (!specPackage) {
         console.log('📦 未发现 spec 仓，正在创建统一 SDD 包裹包（独立 Git）...');
         specPackage = workspaceLayout.ensureSpecPackage(workspaceRoot, { initGit: true });
@@ -1373,6 +1487,7 @@ async function main() {
         asIndependentGit: true,
       });
       writeSddSpecRootHint(workspaceRoot, specPackage.abs);
+      removeOuterSkywalk(workspaceRoot);
 
       // 重新探测，刷新 layout.specRepo / codeRepos
       layout = workspaceLayout.detectWorkspaceLayout(workspaceRoot);
@@ -1390,7 +1505,6 @@ async function main() {
     } else {
       // 单仓：Git 根只放代码 + skills + Hook；SDD 内容进统一包裹子目录
       const isGit = workspaceLayout.isGitRepo(workspaceRoot);
-      deployTelemetryDataDir(workspaceRoot);
 
       if (isGit) {
         console.log('📦 单仓模式：创建/复用仓内统一 SDD 包裹目录...');
@@ -1402,10 +1516,11 @@ async function main() {
           asIndependentGit: false,
         });
         writeSddSpecRootHint(workspaceRoot, specPackage.abs);
+        removeOuterSkywalk(workspaceRoot);
 
         deployMonoSddYaml(workspaceRoot, { specPathRelative: specPackage.name });
-        // Hook 装在 Git 根；Trailer 读包裹目录里的 sdd.config / openspec
-        deployQualityGateTemplates(workspaceRoot, { mode: 'commit-msg-only' });
+        // Hook 装在 Git 根，脚本在包裹包内（Git 根不落 skywalk-sdd/）
+        installCodeRepoCommitMsgHook(workspaceRoot, specPackage.abs);
         const linked = sddConfig.setSpecPath(workspaceRoot, specPackage.abs, {
           allowNestedPackage: true,
         });
@@ -1422,6 +1537,8 @@ async function main() {
           skipOpenspec,
           asIndependentGit: false,
         });
+        writeSddSpecRootHint(workspaceRoot, specPackage.abs);
+        removeOuterSkywalk(workspaceRoot);
         deployDotSddYaml(workspaceRoot);
       }
     }
@@ -1453,6 +1570,12 @@ async function main() {
   // 7. 更新工作目录 .gitignore
   updateGitignore();
 
+  // 8. 收尾：无论前面是否走过 symlink/旧副本路径，强制清掉工作区/Git 根多余 skywalk-sdd/
+  if (specPackage && fs.existsSync(specPackage.abs)) {
+    writeSddSpecRootHint(workspaceRoot, specPackage.abs);
+  }
+  removeOuterSkywalk(workspaceRoot);
+
   const selectedNames = selectedTools.map(t => TOOL_CONFIGS[t].name).join(', ');
 
   console.log();
@@ -1466,12 +1589,14 @@ async function main() {
     console.log('工作区部署结果:');
     console.log('  🎯 工作目录 .*/skills/opsx-*/     # skills 只装这一份');
     console.log('  📋 .sdd-workspace.yaml           # 子仓编排清单');
+    console.log('  📌 .sdd-spec-root                 # 指向包裹包；CLI 用 $(cat .sdd-spec-root)/skywalk-sdd/…');
+    console.log('  ✗ 工作区根无 skywalk-sdd/          # 实体只在包裹包内');
     if (specPackage) {
       console.log(`  📄 ${specPackage.name}/              # 统一 SDD 包裹包（独立 Git）`);
       console.log('       modules.yaml / sdd.config.yaml / openspec / openspec-templates / skywalk-sdd');
     }
     for (const repo of layout.codeRepos) {
-      console.log(`  🔗 ${repo.name}/  ← commit-msg Hook + .sdd.yaml（无 skills）`);
+      console.log(`  🔗 ${repo.name}/  ← commit-msg Hook + .sdd.yaml（无 skywalk-sdd/、无 skills）`);
     }
     console.log();
     console.log('新代码仓加入后执行:');
@@ -1484,7 +1609,8 @@ async function main() {
       console.log(`  📄 ${specPackage.name}/              # 统一 SDD 包裹包（仓内子目录）`);
       console.log('       modules.yaml / sdd.config.yaml / openspec / openspec-templates / skywalk-sdd');
     }
-    console.log('  🔗 .sdd.yaml (layout: mono) + commit-msg Hook');
+    console.log('  🔗 .sdd.yaml (layout: mono) + commit-msg Hook（脚本在包裹包）');
+    console.log('  📌 .sdd-spec-root → 包裹包；无根目录 skywalk-sdd/');
   }
   if (selectedTools.includes('kunlunzhima')) {
     console.log('  📎 .kunlunzhima/commands/opsx/    # KunlunZhima OPSX command bridge（11 个）');
@@ -1496,10 +1622,6 @@ async function main() {
   if (selectedTools.includes('claude')) {
     console.log('  🪝 .claude/hooks/                 # Claude Code SDD Hook Pack（可选增强）');
   }
-  if (!layout.isWorkspace) {
-    console.log('  📊 skywalk-sdd/                  # Hook 运行时 ontology（Git 根）');
-    console.log('  🧰 skywalk-sdd/git-hooks/        # commit-msg Trailer Hook');
-  }
   console.log();
   
   // 统一的 skill 格式说明
@@ -1564,6 +1686,7 @@ module.exports = {
   deployMonoSddYaml,
   populateSpecPackage,
   writeSddSpecRootHint,
+  removeOuterSkywalk,
   deployQualityGateTemplates,
   deployTelemetryDataDir,
   attachCodeRepoLite,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kld-sdd",
-  "version": "2.6.10",
+  "version": "2.6.12",
   "description": "KLD SDD OpenSpec 项目初始化工具 - 一键部署 SDD skills",
   "main": "index.js",
   "bin": {

package/skywalk-sdd/ontology/naming-diagnose.cjs

@@ -67,17 +67,40 @@ function detectEntryMode(projectRoot) {
   return 'unknown';
 }
 
+function resolveCommitMsgScriptPath(projectRoot) {
+  const localScript = path.join(projectRoot, 'skywalk-sdd', 'git-hooks', 'commit-msg-sdd-trailer.cjs');
+  if (fs.existsSync(localScript)) return localScript;
+  // 多仓代码仓：脚本在 spec 包裹包，不在本仓 skywalk-sdd/
+  try {
+    const context = sddConfig.resolveCodeRepoContext(projectRoot);
+    if (context && context.specPath) {
+      const remote = path.join(context.specPath, 'skywalk-sdd', 'git-hooks', 'commit-msg-sdd-trailer.cjs');
+      if (fs.existsSync(remote)) return remote;
+    }
+  } catch {
+    // ignore
+  }
+  if (sddConfig.isMonoLayout(projectRoot)) {
+    const monoSpec = sddConfig.resolveMonoSpecRoot(projectRoot);
+    if (monoSpec) {
+      const nested = path.join(monoSpec, 'skywalk-sdd', 'git-hooks', 'commit-msg-sdd-trailer.cjs');
+      if (fs.existsSync(nested)) return nested;
+    }
+  }
+  return null;
+}
+
 function checkHookInstalled(projectRoot) {
   const hookPath = path.join(projectRoot, '.git', 'hooks', 'commit-msg');
-  const scriptPath = path.join(projectRoot, 'skywalk-sdd', 'git-hooks', 'commit-msg-sdd-trailer.cjs');
+  const scriptPath = resolveCommitMsgScriptPath(projectRoot);
   if (!fs.existsSync(path.join(projectRoot, '.git'))) {
     return { status: STATUS.SKIP, message: '非 Git 仓库，跳过 Hook 检查' };
   }
-  if (!fs.existsSync(scriptPath)) {
+  if (!scriptPath) {
     return {
       status: STATUS.FIXABLE,
       code: 'HOOK_SCRIPT_MISSING',
-      message: 'commit-msg 脚本未部署，可重新执行 kld-sdd-init 或手动复制模板',
+      message: 'commit-msg 脚本未找到（本仓或 sdd.specPath 下均无 skywalk-sdd/git-hooks/），可重新执行 kld-sdd-init',
       fix: { type: 'deploy-hook-script' },
     };
   }

package/templates/git-hooks/commit-msg-sdd-trailer.cjs

@@ -169,8 +169,18 @@ function upsertTrailers(message, trailers) {
   return body;
 }
 
+function resolveMsgFile(argv = process.argv) {
+  // Git 传入的 message 文件路径；跳过 --project= 等可选参数
+  for (let i = 2; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (!arg || arg.startsWith('--')) continue;
+    return arg;
+  }
+  return null;
+}
+
 function main(env = process.env) {
-  const msgFile = process.argv[2];
+  const msgFile = resolveMsgFile();
   if (!msgFile) {
     fail('缺少 commit message 文件参数');
   }

package/templates/hooks/claude/hooks/sdd-prompt.cjs

@@ -18,9 +18,26 @@ function parseInput(raw) {
   }
 }
 
+function resolveSkywalkDir(dir) {
+  const direct = path.join(dir, 'skywalk-sdd');
+  if (fs.existsSync(path.join(direct, 'log.cjs')) || fs.existsSync(path.join(direct, 'log.js'))) {
+    return direct;
+  }
+  const hintFile = path.join(dir, '.sdd-spec-root');
+  if (fs.existsSync(hintFile)) {
+    const rel = String(fs.readFileSync(hintFile, 'utf8') || '').trim().split(/\r?\n/)[0].trim();
+    if (rel) {
+      const nested = path.join(dir, rel, 'skywalk-sdd');
+      if (fs.existsSync(path.join(nested, 'log.cjs')) || fs.existsSync(path.join(nested, 'log.js'))) {
+        return nested;
+      }
+    }
+  }
+  return null;
+}
+
 function hasTelemetryCli(dir) {
-  return fs.existsSync(path.join(dir, 'skywalk-sdd', 'log.cjs')) ||
-    fs.existsSync(path.join(dir, 'skywalk-sdd', 'log.js'));
+  return Boolean(resolveSkywalkDir(dir));
 }
 
 function findTelemetryRoot(startDir) {
@@ -51,7 +68,8 @@ function findProjectRoot(input) {
 }
 
 function readActiveStages(projectRoot) {
-  const stateDir = path.join(projectRoot, 'skywalk-sdd', 'state');
+  const skywalk = resolveSkywalkDir(projectRoot);
+  const stateDir = skywalk ? path.join(skywalk, 'state') : path.join(projectRoot, 'skywalk-sdd', 'state');
   if (!fs.existsSync(stateDir)) return [];
   return fs.readdirSync(stateDir)
     .filter(file => file.endsWith('.json'))
@@ -76,8 +94,8 @@ const activeStages = readActiveStages(projectRoot)
 
 const lines = [
   'SDD Telemetry reminder:',
-  '- Run skywalk-sdd/log.cjs start before the OPSX stage work begins.',
-  '- Run skywalk-sdd/log.cjs end before stopping the stage.',
+  '- Run node "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" start before the OPSX stage work begins.',
+  '- Run node "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" end before stopping the stage.',
   '- Hooks are only an enhancement; OPSX skill instructions remain authoritative.',
 ];
 

package/templates/hooks/codebuddy/hooks/sdd-prompt.cjs

@@ -13,8 +13,27 @@ if (!/\/opsx[:|-]/.test(prompt)) {
   process.exit(0);
 }
 
+function resolveSkywalkDir(dir) {
+  const direct = path.join(dir, 'skywalk-sdd');
+  if (fs.existsSync(path.join(direct, 'log.cjs')) || fs.existsSync(path.join(direct, 'log.js'))) {
+    return direct;
+  }
+  const hintFile = path.join(dir, '.sdd-spec-root');
+  if (fs.existsSync(hintFile)) {
+    const rel = String(fs.readFileSync(hintFile, 'utf8') || '').trim().split(/\r?\n/)[0].trim();
+    if (rel) {
+      const nested = path.join(dir, rel, 'skywalk-sdd');
+      if (fs.existsSync(path.join(nested, 'log.cjs')) || fs.existsSync(path.join(nested, 'log.js'))) {
+        return nested;
+      }
+    }
+  }
+  return null;
+}
+
 function readActiveStages(projectRoot) {
-  const stateDir = path.join(projectRoot, 'skywalk-sdd', 'state');
+  const skywalk = resolveSkywalkDir(projectRoot);
+  const stateDir = skywalk ? path.join(skywalk, 'state') : path.join(projectRoot, 'skywalk-sdd', 'state');
   if (!fs.existsSync(stateDir)) return [];
   return fs.readdirSync(stateDir)
     .filter((file) => file.endsWith('.json'))
@@ -35,8 +54,8 @@ const activeStages = readActiveStages(projectRoot)
 
 const lines = [
   'SDD Telemetry reminder:',
-  '- Run skywalk-sdd/log.cjs start before the OPSX stage work begins.',
-  '- Run skywalk-sdd/log.cjs end before stopping the stage.',
+  '- Run node "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" start before the OPSX stage work begins.',
+  '- Run node "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" end before stopping the stage.',
   '- Hooks are only an enhancement; OPSX skill instructions remain authoritative.',
 ];
 

package/templates/skills/kld-sdd/opsx-apply/SKILL.md

@@ -27,15 +27,15 @@ allowed-tools:
 > - ⛔ **隔离红线**：绝对禁止加载同级其他 Capability 的文档
 
 > **🖥️ 跨平台执行规则**
-> - **写代码**：cwd 保持在 Git 根（含 `src/`）；**文档 / telemetry**：`--project` 指向 SDD 包裹包（`node skywalk-sdd/ontology/cli.cjs spec-root` 可查看）。
-> - `openspec` 命令：优先 `node skywalk-sdd/openspec-shim.cjs list`（自动 cd 到包裹包）。
+> - **写代码**：cwd 保持在 Git 根（含 `src/`）；**文档 / telemetry**：`--project` 指向 SDD 包裹包（`node "$(cat .sdd-spec-root)/skywalk-sdd/ontology/cli.cjs" spec-root` 可查看）。
+> - `openspec` 命令：优先 `node "$(cat .sdd-spec-root)/skywalk-sdd/openspec-shim.cjs" list`（自动 cd 到包裹包）。
 > - Telemetry 命令默认使用 `--project=.`，兼容 Windows、macOS、Linux。
 > - ${SHELL_GUIDANCE}
 > - 不要省略 `--source=opsx-command` 与 `--session-id=<会话ID>`。
 > **📊 Telemetry（必做，不得跳过）**
 > - 阶段开始 / 阶段结束 / `task_update` / `ai_adoption_review` / `worktree_finish` 的**完整命令模板**见 `./reference.md`「📊 Telemetry 命令模板」。
 > - 不得跳过任何 telemetry 记录；`task_update` 的 `--task-id=<TASK-ID>` 必须替换为实际任务 ID，否则 E4 指标无法计算；TDD 测试骨架任务须在 `--details-json` 带 `"task_kind":"test-skeleton"`（P3，详见 `./reference.md`）。
-> - 较大的 `--details-json` 负载可先写入文件，再通过 `--details-file=skywalk-sdd/state/<变更名称>-<type>.json` 传递（例如 `task_update` 对应 `<变更名称>-task-update.json`）。
+> - 较大的 `--details-json` 负载可先写入文件，再通过 `--details-file="$(cat .sdd-spec-root)/skywalk-sdd/state/<变更名称>-<type>.json"` 传递（例如 `task_update` 对应 `<变更名称>-task-update.json`）。
 > - `task_update` 记录成功后会自动调用 `check-task` 更新 `tasks.md` 中的 checkbox；录入成功后，agent 可以通过 `check-task` 命令验证该 checkbox 已更新。
 > - **⚠️ P1-2 ai_adoption_review 必填 ai_diff**：记录 AI 产出快照时，`--details-json` 必须含 `ai_diff.files_changed`（即使=0）与 `ai_diff.files`（产出文件路径数组，非空），**不得只发 `assertions`**。`vcs_mode=readonly` 时 `ai_diff.added_lines` 不得为 null——用只读 `git diff --numstat HEAD` 取值（apply Git 只读策略允许）；`vcs_mode=no-git` 时可填 null。工具侧已加记录时硬校验：`files` 空数组或 `readonly` 下 `added_lines=null` 将 **拒绝记录**（与 conformance_review 校验对称）。缺失 `ai_diff` 会导致 report 变更文件数为 null（工具侧已加 `assertions[].files` 兜底，但 `ai_diff` 是主数据源）。完整模板见 `./reference.md`「§5.1」。
 > - **⚠️ P1-3 process_note 必记**：阶段内发生 修复/澄清/决策/API 故障/换模型 时，**必须**记 `process_note` 事件（`kind` 见 `./reference.md`「必记节点清单」）。全程 0 条 process_note 视为过程记录缺失，report 过程记录区显示空。

package/templates/skills/kld-sdd/opsx-apply/checklist.md

@@ -14,7 +14,7 @@ description: opsx-apply 的阶段强制检查点与自检清单。仅在执行 a
 ### §1.2 Check 门禁（apply 前必做）
 
 - [ ] 读取 telemetry 事件数据，检查当前 change 是否已有完成的 check 阶段
-  - `node skywalk-sdd/log.cjs doctor --project=. --change=<change-name>` 或搜 `skywalk-sdd/data/events/<change-name>/` 的 `stage_end` + `command=check` + `result=success`
+  - `node "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" doctor --project=. --change=<change-name>` 或搜 `skywalk-sdd/data/events/<change-name>/` 的 `stage_end` + `command=check` + `result=success`
 - [ ] check 已完成 ✅ → 继续 apply 流程
 - [ ] check 未完成 ❌ → **强制拒绝** apply，引导用户先执行 `/opsx-check <change-name>`（不得跳过）
 - [ ] telemetry 数据缺失（新项目无历史） → 提示首次执行先运行 `/opsx-check`，询问是否现在执行
@@ -82,7 +82,7 @@ description: opsx-apply 的阶段强制检查点与自检清单。仅在执行 a
 - [ ] 两种格式同步更新，不可遗漏
 - [ ] 显示进度：`✅ [TASK-ID] 已完成 [N/M]`
 - [ ] 记录任务级 Telemetry（`task_update`，`--task-id=<TASK-ID>` 必填，否则 E4 指标无法计算）；TDD 测试骨架任务须在 `--details-json` 带 `"task_kind":"test-skeleton"`（P3，避免红灯误判拉低 E4）
-- [ ] ⛔ **task_update 后必须验证 checkbox 已更新**：执行 `node skywalk-sdd/index.cjs check-task --project=. --change=<变更名称> --task-id=<TASK-ID>` 确认 tasks.md 中对应行已从 `- [ ]` 变为 `- [x]`；若未更新，手动修改 tasks.md 并报告
+- [ ] ⛔ **task_update 后必须验证 checkbox 已更新**：执行 `node "$(cat .sdd-spec-root)/skywalk-sdd/index.cjs" check-task --project=. --change=<变更名称> --task-id=<TASK-ID>` 确认 tasks.md 中对应行已从 `- [ ]` 变为 `- [x]`；若未更新，手动修改 tasks.md 并报告
 
 ### §5f.1 apply 结束前 checkbox 全量同步校验
 
@@ -112,7 +112,7 @@ description: opsx-apply 的阶段强制检查点与自检清单。仅在执行 a
 - [ ] 主仓库无与 merge 冲突的未跟踪文件（见 §1.5 Step 0.5）
 - [ ] `test-strategy` 为 `tdd`/`impl-first` 时，§6.0 测试证据已存在
 - [ ] 在**主仓库根目录**执行收尾脚本（禁止在 `.worktrees/...` 内执行）
-- [ ] 执行：`node skywalk-sdd/apply-worktree-finish.cjs --change=<变更名称> --capability=<capability-name>`
+- [ ] 执行：`node "$(cat .sdd-spec-root)/skywalk-sdd/apply-worktree-finish.cjs" --change=<变更名称> --capability=<capability-name>`
 - [ ] 默认 merge 目标 = §1.5 `--record-base` 写入的 `integration_base`（**不是**默认 master）
 - [ ] 若 §1.5 判定未建 worktree（串行、强依赖、沙箱回退）→ 跳过本节