kld-sdd 2.6.11 → 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

@@ -1208,94 +1208,62 @@ function writeSddSpecRootHint(anchorDir, specPackageAbs) {
 }
 
 /**
- * 工作区 / 单仓 Git 根的 skywalk-sdd/ 改为指向包裹包内唯一实体（符号链接）。
- * skills 仍可用 `node skywalk-sdd/log.cjs`，实体文件只在 *-sdd-specs/skywalk-sdd/。
- * 链接失败时回退为薄转发脚本（不复制 ontology）。
+ * 移除工作区 / Git 根上多余的 skywalk-sdd（符号链接或旧完整副本）。
+ * 唯一实体只保留在 *-sdd-specs/skywalk-sdd/。
+ *
+ * 触发条件（满足其一即可）：
+ * - 存在 .sdd-spec-root
+ * - 同级已有 *-sdd-specs/skywalk-sdd（多仓/单仓包裹包）
  */
-function deploySkywalkForwarders(anchorDir, specPackageAbs) {
-  const anchor = path.resolve(anchorDir);
-  const specAbs = path.resolve(specPackageAbs);
-  const relSpec = path.relative(anchor, specAbs).replace(/\\/g, '/');
-  const skywalkDir = path.join(anchor, 'skywalk-sdd');
-  const targetSkywalk = path.join(specAbs, 'skywalk-sdd');
-  fs.mkdirSync(path.join(skywalkDir, 'ontology'), { recursive: true });
-
-  const writeForwarder = (destRel, targetAbsPath) => {
-    const dest = path.join(skywalkDir, destRel);
-    fs.mkdirSync(path.dirname(dest), { recursive: true });
-    const relFromDestDir = path.relative(path.dirname(dest), targetAbsPath).replace(/\\/g, '/');
-    const body = [
-      '#!/usr/bin/env node',
-      "'use strict';",
-      "const { spawnSync } = require('child_process');",
-      "const path = require('path');",
-      `const target = path.resolve(__dirname, ${JSON.stringify(relFromDestDir)});`,
-      'const r = spawnSync(process.execPath, [target, ...process.argv.slice(2)], { stdio: \'inherit\' });',
-      'process.exit(r.status === null ? 1 : r.status);',
-      '',
-    ].join('\n');
-    fs.writeFileSync(dest, body, 'utf8');
-  };
-
-  const entries = [
-    'log.cjs',
-    'openspec-shim.cjs',
-    'context-client.cjs',
-    'apply-worktree-finish.cjs',
-  ];
-  for (const name of entries) {
-    writeForwarder(name, path.join(targetSkywalk, name));
-  }
-  writeForwarder(path.join('ontology', 'cli.cjs'), path.join(targetSkywalk, 'ontology', 'cli.cjs'));
-  console.log(`   ✓ skywalk-sdd/ 转发脚本 → ${relSpec}/skywalk-sdd/（实体在包裹包）`);
-  return { ok: true, mode: 'forwarders', relSpec };
-}
-
-function linkSkywalkToSpecPackage(anchorDir, specPackageAbs) {
+function removeOuterSkywalk(anchorDir) {
   const anchor = path.resolve(anchorDir);
-  const targetAbs = path.join(path.resolve(specPackageAbs), 'skywalk-sdd');
-  const linkAbs = path.join(anchor, 'skywalk-sdd');
-
-  if (!fs.existsSync(targetAbs)) {
-    console.log('   ⚠️  包裹包尚无 skywalk-sdd/，跳过工作区链接');
-    return { ok: false, message: 'spec skywalk-sdd missing' };
+  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 {
-    let st = null;
-    try {
-      st = fs.lstatSync(linkAbs);
-    } catch (err) {
-      if (!err || err.code !== 'ENOENT') throw err;
-    }
-    if (st) {
-      if (st.isSymbolicLink()) {
-        const current = fs.realpathSync(linkAbs);
-        if (current === fs.realpathSync(targetAbs)) {
-          console.log('   ✓ skywalk-sdd/ 已链接到包裹包（唯一实体）');
-          return { ok: true, mode: 'symlink', linkAbs, targetAbs };
-        }
-        fs.unlinkSync(linkAbs);
-      } else if (st.isDirectory()) {
-        // 旧完整副本 → 删除后改链接（权威数据在包裹包）
-        fs.rmSync(linkAbs, { recursive: true, force: true });
-      } else {
-        fs.unlinkSync(linkAbs);
+    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 (err) {
-    console.log(`   ⚠️  清理旧 skywalk-sdd/ 失败: ${err.message}`);
-    return deploySkywalkForwarders(anchor, specPackageAbs);
+  } catch {
+    // ignore
+  }
+
+  if (!hasHint && !hasNestedEntity) {
+    // 无包裹包迹象时不贸然删除（可能是旧平铺布局）
+    return { ok: true, removed: false, skipped: true };
   }
 
-  const rel = path.relative(anchor, targetAbs);
   try {
-    fs.symlinkSync(rel, linkAbs, process.platform === 'win32' ? 'junction' : 'dir');
-    console.log(`   ✓ skywalk-sdd/ → ${rel.replace(/\\/g, '/')}（唯一实体在包裹包）`);
-    return { ok: true, mode: 'symlink', linkAbs, targetAbs, rel };
+    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(`   ⚠️  符号链接失败 (${err.message})，回退为转发脚本`);
-    return deploySkywalkForwarders(anchor, specPackageAbs);
+    console.log(`   ⚠️  未能移除根目录 skywalk-sdd/: ${err.message}`);
+    return { ok: false, message: err.message };
   }
 }
 
@@ -1519,8 +1487,7 @@ async function main() {
         asIndependentGit: true,
       });
       writeSddSpecRootHint(workspaceRoot, specPackage.abs);
-      // 工作区不复制 skywalk-sdd 实体，只链到包裹包（skills 路径仍可用）
-      linkSkywalkToSpecPackage(workspaceRoot, specPackage.abs);
+      removeOuterSkywalk(workspaceRoot);
 
       // 重新探测，刷新 layout.specRepo / codeRepos
       layout = workspaceLayout.detectWorkspaceLayout(workspaceRoot);
@@ -1549,11 +1516,11 @@ async function main() {
           asIndependentGit: false,
         });
         writeSddSpecRootHint(workspaceRoot, specPackage.abs);
-        linkSkywalkToSpecPackage(workspaceRoot, specPackage.abs);
+        removeOuterSkywalk(workspaceRoot);
 
         deployMonoSddYaml(workspaceRoot, { specPathRelative: specPackage.name });
-        // Hook 装在 Git 根；经 symlink 写入包裹包内的 git-hooks
-        deployQualityGateTemplates(workspaceRoot, { mode: 'commit-msg-only' });
+        // Hook 装在 Git 根，脚本在包裹包内（Git 根不落 skywalk-sdd/）
+        installCodeRepoCommitMsgHook(workspaceRoot, specPackage.abs);
         const linked = sddConfig.setSpecPath(workspaceRoot, specPackage.abs, {
           allowNestedPackage: true,
         });
@@ -1571,7 +1538,7 @@ async function main() {
           asIndependentGit: false,
         });
         writeSddSpecRootHint(workspaceRoot, specPackage.abs);
-        linkSkywalkToSpecPackage(workspaceRoot, specPackage.abs);
+        removeOuterSkywalk(workspaceRoot);
         deployDotSddYaml(workspaceRoot);
       }
     }
@@ -1603,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();
@@ -1616,7 +1589,8 @@ async function main() {
     console.log('工作区部署结果:');
     console.log('  🎯 工作目录 .*/skills/opsx-*/     # skills 只装这一份');
     console.log('  📋 .sdd-workspace.yaml           # 子仓编排清单');
-    console.log('  🔗 skywalk-sdd/ → *-sdd-specs/skywalk-sdd/  # 符号链接，实体只在包裹包');
+    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');
@@ -1635,8 +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('  🔗 skywalk-sdd/ → *-sdd-specs/skywalk-sdd/  # 符号链接，实体只在包裹包');
+    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 个）');
@@ -1712,8 +1686,7 @@ module.exports = {
   deployMonoSddYaml,
   populateSpecPackage,
   writeSddSpecRootHint,
-  linkSkywalkToSpecPackage,
-  deploySkywalkForwarders,
+  removeOuterSkywalk,
   deployQualityGateTemplates,
   deployTelemetryDataDir,
   attachCodeRepoLite,

package/package.json

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

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（串行、强依赖、沙箱回退）→ 跳过本节
 

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

@@ -11,13 +11,13 @@ description: opsx-apply 的详细模板：telemetry 命令、worktree 全套策
 
 ## 📊 Telemetry 命令模板（必做，不得跳过）
 
-> 阶段开始：`node skywalk-sdd/log.cjs start --command=apply --project=. --change=<变更名称> --capability=<capability-name> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID> --git-sha=<base_git_sha_or_none>`（保存 event_id）
-> 阶段结束：`node skywalk-sdd/log.cjs end --event-id=<event_id> --command=apply --project=. --change=<变更名称> --capability=<capability-name> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID> --result=success|failure --summary="摘要"`
+> 阶段开始：`node "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" start --command=apply --project=. --change=<变更名称> --capability=<capability-name> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID> --git-sha=<base_git_sha_or_none>`（保存 event_id）
+> 阶段结束：`node "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" end --event-id=<event_id> --command=apply --project=. --change=<变更名称> --capability=<capability-name> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID> --result=success|failure --summary="摘要"`
 
 ### task_update（每完成一个任务记录）
 
 ```bash
-node skywalk-sdd/log.cjs record --type=task_update --command=apply --project=. --change=<变更名称> --capability=<capability-name> --task-id=<TASK-ID> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID> --status=completed --result=success --summary="<TASK-ID> 完成" --details-json="{\"files_changed\":[],\"build_results\":{\"command\":\"<实际编译命令>\",\"success\":true,\"duration_ms\":0,\"error_count\":0},\"test_results\":{\"command\":\"<实际测试命令>\",\"passed\":0,\"failed\":0,\"skipped\":0,\"coverage\":null,\"duration_ms\":0}}"
+node "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" record --type=task_update --command=apply --project=. --change=<变更名称> --capability=<capability-name> --task-id=<TASK-ID> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID> --status=completed --result=success --summary="<TASK-ID> 完成" --details-json="{\"files_changed\":[],\"build_results\":{\"command\":\"<实际编译命令>\",\"success\":true,\"duration_ms\":0,\"error_count\":0},\"test_results\":{\"command\":\"<实际测试命令>\",\"passed\":0,\"failed\":0,\"skipped\":0,\"coverage\":null,\"duration_ms\":0}}"
 ```
 
 **⚠️ 注意**：`--task-id=<TASK-ID>` 必须替换为实际任务 ID，否则 E4 指标无法计算。
@@ -26,16 +26,16 @@ node skywalk-sdd/log.cjs record --type=task_update --command=apply --project=. -
 
 > 完整 test-skeleton telemetry 模板见 opsx-tdd-rules/rules/test-skeleton-telemetry.md
 
-**📄 通过文件传递大 payload**：若 `details-json` 内容过长，可先写入 `skywalk-sdd/state/<变更名称>-task-update.json`，再使用 `--details-file` 指定该文件：
+**📄 通过文件传递大 payload**：若 `details-json` 内容过长，可先写入 `"$(cat .sdd-spec-root)/skywalk-sdd/state/<变更名称>-task-update.json`，再使用 `--details-file` 指定该文件：
 
 ```bash
-node skywalk-sdd/log.cjs record --type=task_update --command=apply --project=. --change=<变更名称> --capability=<capability-name> --task-id=<TASK-ID> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID> --status=completed --result=success --summary="<TASK-ID> 完成" --details-file=skywalk-sdd/state/<变更名称>-task-update.json
+node "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" record --type=task_update --command=apply --project=. --change=<变更名称> --capability=<capability-name> --task-id=<TASK-ID> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID> --status=completed --result=success --summary="<TASK-ID> 完成" --details-file="$(cat .sdd-spec-root)/skywalk-sdd/state/<变更名称>-task-update.json"
 ```
 
 **✅ 验证 checkbox 已更新**：`task_update` 记录成功后会自动调用 `check-task` 更新 `tasks.md` 中的任务 checkbox。需要显式校验时可执行：
 
 ```bash
-node skywalk-sdd/log.cjs check-task --project=. --change=<变更名称> --task-id=<TASK-ID>
+node "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" check-task --project=. --change=<变更名称> --task-id=<TASK-ID>
 ```
 
 **【Q3 details schema 字段说明】**：`details-json` 中的 `test_results` 和 `build_results` 字段非强制，但提供后能让 E4 一次成码率更准确：
@@ -59,7 +59,7 @@ node skywalk-sdd/log.cjs check-task --project=. --change=<变更名称> --task-i
 | `manual-action` | 用户手动操作 | 用户手动改配置 |
 
 ```bash
-node skywalk-sdd/log.cjs record --type=process_note --command=<stage> --project=. --change=<变更名称> --capability=<capability-name> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID> --summary="<人读摘要>" --details-json="{\"kind\":\"<fix|clarification|decision|api-error|model-switch|manual-action>\",\"target\":\"<可选，关联对象>\",\"round\":<可选，clarification 轮次整数>}"
+node "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" record --type=process_note --command=<stage> --project=. --change=<变更名称> --capability=<capability-name> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID> --summary="<人读摘要>" --details-json="{\"kind\":\"<fix|clarification|decision|api-error|model-switch|manual-action>\",\"target\":\"<可选，关联对象>\",\"round\":<可选，clarification 轮次整数>}"
 ```
 
 **使用时机**：
@@ -94,13 +94,13 @@ node skywalk-sdd/log.cjs record --type=process_note --command=<stage> --project=
 Git 可用时只读统计 SHA/diff；Git 不可用时使用 `vcs_mode=no-git` 和 `base_git_sha=null`：
 
 ```bash
-node skywalk-sdd/log.cjs record --type=ai_adoption_review --command=apply --project=. --change=<变更名称> --capability=<capability-name> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID> --status=ai_snapshot --result=success --summary="AI 代码产出快照" --details-json="{\"ai_adoption\":{\"review_status\":\"ai_snapshot\",\"vcs_mode\":\"<readonly|no-git>\",\"base_git_sha\":\"<base_git_sha_or_null>\",\"ai_git_sha\":\"<ai_git_sha_or_null>\",\"ai_diff\":{\"files_changed\":<N>,\"files\":[\"<产出文件路径1>\",\"<产出文件路径2>\"],\"added_lines\":<git_diff_numstat_HEAD_取值或0>,\"deleted_lines\":<同左>},\"notes\":\"未自动提交 commit；vcs_mode=readonly 时 added_lines 用只读 git diff --numstat HEAD 取值（不得填 null，工具侧硬校验）；vcs_mode=no-git 时可填 null\"}}"
+node "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" record --type=ai_adoption_review --command=apply --project=. --change=<变更名称> --capability=<capability-name> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID> --status=ai_snapshot --result=success --summary="AI 代码产出快照" --details-json="{\"ai_adoption\":{\"review_status\":\"ai_snapshot\",\"vcs_mode\":\"<readonly|no-git>\",\"base_git_sha\":\"<base_git_sha_or_null>\",\"ai_git_sha\":\"<ai_git_sha_or_null>\",\"ai_diff\":{\"files_changed\":<N>,\"files\":[\"<产出文件路径1>\",\"<产出文件路径2>\"],\"added_lines\":<git_diff_numstat_HEAD_取值或0>,\"deleted_lines\":<同左>},\"notes\":\"未自动提交 commit；vcs_mode=readonly 时 added_lines 用只读 git diff --numstat HEAD 取值（不得填 null，工具侧硬校验）；vcs_mode=no-git 时可填 null\"}}"
 ```
 
 ### worktree_finish（收尾 Telemetry，推荐）
 
 ```bash
-node skywalk-sdd/log.cjs record --type=worktree_finish \
+node "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" record --type=worktree_finish \
   --command=apply --project=. --change=<变更名称> --capability=<capability-name> \
   --agent=<Agent类型> --source=opsx-command --session-id=<会话ID> \
   --result=success --summary="merge+remove completed" \
@@ -243,12 +243,12 @@ node skywalk-sdd/log.cjs record --type=worktree_finish \
 在主仓库根目录、**尚未** `cd` 进 `.worktrees/` 时执行：
 
 ```bash
-node skywalk-sdd/apply-worktree-finish.cjs --record-base \
+node "$(cat .sdd-spec-root)/skywalk-sdd/apply-worktree-finish.cjs" --record-base \
   --change=<变更名称> \
   --capability=<capability-name>
 ```
 
-- 将当前具名分支写入 `skywalk-sdd/state/apply-<change>-<capability>.json` 的 `integration_base`
+- 将当前具名分支写入 `"$(cat .sdd-spec-root)/skywalk-sdd/state/apply-<change>-<capability>.json` 的 `integration_base`
 - 若为 detached HEAD，先 `git checkout` 到具名分支再记录
 - simple 模式可省略 `--capability`（默认与 change 相同）
 
@@ -340,7 +340,7 @@ Agent("实现 TASK-03: 创建权限数据模型", ...)
 Git 可用时只读统计 SHA/diff；Git 不可用时使用 `vcs_mode=no-git` 和 `base_git_sha=null`：
 
 ```bash
-node skywalk-sdd/log.cjs record --type=ai_adoption_review --command=apply --project=. --change=<变更名称> --capability=<capability-name> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID> --status=ai_snapshot --result=success --summary="AI 代码产出快照" --details-json="{\"ai_adoption\":{\"review_status\":\"ai_snapshot\",\"vcs_mode\":\"<readonly|no-git>\",\"base_git_sha\":\"<base_git_sha_or_null>\",\"ai_git_sha\":\"<ai_git_sha_or_null>\",\"ai_diff\":{\"files_changed\":<N>,\"files\":[\"<产出文件路径1>\",\"<产出文件路径2>\"],\"added_lines\":<git_diff_numstat_HEAD_取值或0>,\"deleted_lines\":<同左>},\"notes\":\"未自动提交 commit；vcs_mode=readonly 时 added_lines 用只读 git diff --numstat HEAD 取值（不得填 null，工具侧硬校验）；vcs_mode=no-git 时可填 null\"}}"
+node "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" record --type=ai_adoption_review --command=apply --project=. --change=<变更名称> --capability=<capability-name> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID> --status=ai_snapshot --result=success --summary="AI 代码产出快照" --details-json="{\"ai_adoption\":{\"review_status\":\"ai_snapshot\",\"vcs_mode\":\"<readonly|no-git>\",\"base_git_sha\":\"<base_git_sha_or_null>\",\"ai_git_sha\":\"<ai_git_sha_or_null>\",\"ai_diff\":{\"files_changed\":<N>,\"files\":[\"<产出文件路径1>\",\"<产出文件路径2>\"],\"added_lines\":<git_diff_numstat_HEAD_取值或0>,\"deleted_lines\":<同左>},\"notes\":\"未自动提交 commit；vcs_mode=readonly 时 added_lines 用只读 git diff --numstat HEAD 取值（不得填 null，工具侧硬校验）；vcs_mode=no-git 时可填 null\"}}"
 ```
 
 > 该命令亦见上文「📊 Telemetry 命令模板 → ai_adoption_review」。
@@ -377,7 +377,7 @@ node skywalk-sdd/log.cjs record --type=ai_adoption_review --command=apply --proj
 
 **执行**（主仓库根目录）：
 ```bash
-node skywalk-sdd/apply-worktree-finish.cjs \
+node "$(cat .sdd-spec-root)/skywalk-sdd/apply-worktree-finish.cjs" \
   --change=<变更名称> \
   --capability=<capability-name>
 ```

package/templates/skills/kld-sdd/opsx-apply/worktree-setup.md

@@ -72,7 +72,7 @@
 ### record-base
 
 ```bash
-node skywalk-sdd/apply-worktree-finish.cjs --record-base \
+node "$(cat .sdd-spec-root)/skywalk-sdd/apply-worktree-finish.cjs" --record-base \
   --change=<change> --capability=<capability>
 ```
 
@@ -88,10 +88,10 @@ git worktree add .worktrees/apply-<change>-<capability> -b kld-sdd/<change>/<cap
 ### finish
 
 ```bash
-node skywalk-sdd/apply-worktree-finish.cjs --change=<change> --capability=<capability>
+node "$(cat .sdd-spec-root)/skywalk-sdd/apply-worktree-finish.cjs" --change=<change> --capability=<capability>
 ```
 
-状态文件：`skywalk-sdd/state/apply-<change>-<capability>.json`
+状态文件：`"$(cat .sdd-spec-root)/skywalk-sdd/state/apply-<change>-<capability>.json`
 
 ## 快速参考
 

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

@@ -21,8 +21,8 @@ allowed-tools:
 
 > **跨平台执行规则**
 > - **SDD 文档根** = `*-sdd-specs` 包裹包（含 `openspec/`、`modules.yaml`），不是 Git 根或工作区根。
-> - `openspec` 命令：优先 `node skywalk-sdd/openspec-shim.cjs list`（自动 cd 到包裹包），或先 `cd` 到包裹包再执行。
-> - `skywalk-sdd/log.cjs` / `ontology/cli.cjs`：`--project=.` 在 Git 根/工作区根会自动解析；也可 `node skywalk-sdd/ontology/cli.cjs spec-root` 查看路径。
+> - `openspec` 命令：优先 `node "$(cat .sdd-spec-root)/skywalk-sdd/openspec-shim.cjs" list`（自动 cd 到包裹包），或先 `cd` 到包裹包再执行。
+> - Telemetry / ontology：`node "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" …`（Git 根无 skywalk-sdd/）；`spec-root` 可用 `node "$(cat .sdd-spec-root)/skywalk-sdd/ontology/cli.cjs" spec-root`。
 > - Telemetry 命令默认使用 `--project=.`，兼容 Windows、macOS、Linux。
 > - 不要裸写 Windows 反斜杠绝对路径；如必须使用绝对路径，请加引号或改成正斜杠。
 > - 不要省略 `--source=opsx-command` 和 `--session-id=<会话ID>`。
@@ -53,7 +53,7 @@ openspec list
 让用户选择现有变更。确认后记录阶段开始：
 
 ```bash
-node skywalk-sdd/log.cjs start --command=archive --project=. --change=<变更名称> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID>
+node "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" start --command=archive --project=. --change=<变更名称> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID>
 ```
 
 保存 `event_id`。
@@ -78,12 +78,12 @@ node skywalk-sdd/log.cjs start --command=archive --project=. --change=<变更名
 git worktree list
 ```
 
-应仅剩主工作区；或 telemetry 中存在 `worktree_finish` + `result=success` 事件。若仍有 `.worktrees/apply-*`，先执行 `node skywalk-sdd/apply-worktree-finish.cjs` 或手工清理。
+应仅剩主工作区；或 telemetry 中存在 `worktree_finish` + `result=success` 事件。若仍有 `.worktrees/apply-*`，先执行 `node "$(cat .sdd-spec-root)/skywalk-sdd/apply-worktree-finish.cjs"` 或手工清理。
 
 ### 3. 运行 telemetry doctor
 
 ```bash
-node skywalk-sdd/log.cjs doctor --project=. --change=<变更名称>
+node "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" doctor --project=. --change=<变更名称>
 ```
 
 如果存在 `severe_issues`，暂停归档并说明必须先修复。`superseded_open_stages` 和 `rework_summary` 只作为返工/重复执行展示，不要求用户人工区分测试回滚或真实研发返工。
@@ -91,7 +91,7 @@ node skywalk-sdd/log.cjs doctor --project=. --change=<变更名称>
 ### 4. 扫描 tasks 完成状态
 
 ```bash
-node skywalk-sdd/log.cjs tasks-status --project=. --change=<变更名称>
+node "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" tasks-status --project=. --change=<变更名称>
 ```
 
 即使用户选择“变更已完成实施”，未勾选项也不阻断归档。它可能代表任务真实未完成，也可能代表代码已完成但文档未同步；不要猜测，也不要静默忽略。最终必须让 `archive-docs` 将其写入 `archive_result.task_completion` 和报告。
@@ -105,7 +105,7 @@ node skywalk-sdd/log.cjs tasks-status --project=. --change=<变更名称>
 执行唯一归档命令：
 
 ```bash
-node skywalk-sdd/log.cjs archive-docs --project=. --change=<变更名称> --reason="变更已完成实施" --event-id=<event_id> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID>
+node "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" archive-docs --project=. --change=<变更名称> --reason="变更已完成实施" --event-id=<event_id> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID>
 ```
 
 > `--reason` 默认值为 `变更已完成实施`；如果用户选择了其他归档原因，请将上述 `--reason` 的值替换为对应原因。
@@ -125,7 +125,7 @@ node skywalk-sdd/log.cjs archive-docs --project=. --change=<变更名称> --reas
 归档成功后立即执行（不询问用户）：
 
 ```bash
-node skywalk-sdd/ontology/cli.cjs active-change --remove --change=<变更名称> --project=.
+node "$(cat .sdd-spec-root)/skywalk-sdd/ontology/cli.cjs" active-change --remove --change=<变更名称> --project=.
 ```
 
 把该 change 从 spec 仓 `sdd.config.yaml` 的 `active_changes` 移除，避免已归档 change 继续被代码 commit 写成 `Spec-Change`。该操作幂等；条目本就不存在时不报错。
@@ -136,12 +136,12 @@ node skywalk-sdd/ontology/cli.cjs active-change --remove --change=<变更名称>
 2. 归档 zip 生成后，**加载并执行** **`opsx-kb-ingest`** 上传（勿只口头提示而不走技能流程）；成功则写 `ingest-receipt.json`。
 3. 若返回 `EXTERNAL_REF_CONFLICT`，引导回 spec/check 修正后重入，**禁止**在 KB 内现场改绑。
 
-> 注意：`archive-docs` 成功执行后已经在内部写入 `stage_end`，因此**不要在成功的归档后再单独运行 `node skywalk-sdd/log.cjs end --command=archive ...`**。仅在第 5 步归档命令失败时，才需要运行下方的失败分支 `end`。
+> 注意：`archive-docs` 成功执行后已经在内部写入 `stage_end`，因此**不要在成功的归档后再单独运行 `node "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" end --command=archive ...`**。仅在第 5 步归档命令失败时，才需要运行下方的失败分支 `end`。
 
 如果该命令失败，以失败状态结束 telemetry：
 
 ```bash
-node skywalk-sdd/log.cjs end --event-id=<event_id> --command=archive --project=. --change=<变更名称> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID> --result=failure --summary="归档失败：<失败原因>"
+node "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" end --event-id=<event_id> --command=archive --project=. --change=<变更名称> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID> --result=failure --summary="归档失败：<失败原因>"
 ```
 
 失败时不要输出“归档完成”。
@@ -168,21 +168,21 @@ node skywalk-sdd/log.cjs end --event-id=<event_id> --command=archive --project=.
 如用户愿意提供反馈，可补录问卷结果：
 
 ```bash
-node skywalk-sdd/log.cjs record --type=survey_result --command=archive --project=. --change=<变更名称> --agent=<Agent类型> --source=manual --session-id=<会话ID> --result=success --summary="SDD 人工反馈" --details-json="{\"survey_result\":{\"nps\":9,\"cognitive_load\":3,\"spec_fatigue_index\":2,\"satisfaction\":8,\"respondent_role\":\"developer\",\"collected_at\":\"<ISO时间>\",\"notes\":\"\"}}"
+node "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" record --type=survey_result --command=archive --project=. --change=<变更名称> --agent=<Agent类型> --source=manual --session-id=<会话ID> --result=success --summary="SDD 人工反馈" --details-json="{\"survey_result\":{\"nps\":9,\"cognitive_load\":3,\"spec_fatigue_index\":2,\"satisfaction\":8,\"respondent_role\":\"developer\",\"collected_at\":\"<ISO时间>\",\"notes\":\"\"}}"
 ```
 
 如团队有传统方式工时基线，可补录 baseline：
 
 ```bash
-node skywalk-sdd/log.cjs record --type=baseline_record --command=archive --project=. --change=<变更名称> --agent=<Agent类型> --source=manual --session-id=<会话ID> --result=success --summary="传统工时基线" --details-json="{\"baseline_record\":{\"traditional_hours\":10,\"sdd_hours\":6,\"task_type\":\"feature\",\"baseline_source\":\"manual-estimate\",\"collected_at\":\"<ISO时间>\",\"notes\":\"\"}}"
+node "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" record --type=baseline_record --command=archive --project=. --change=<变更名称> --agent=<Agent类型> --source=manual --session-id=<会话ID> --result=success --summary="传统工时基线" --details-json="{\"baseline_record\":{\"traditional_hours\":10,\"sdd_hours\":6,\"task_type\":\"feature\",\"baseline_source\":\"manual-estimate\",\"collected_at\":\"<ISO时间>\",\"notes\":\"\"}}"
 ```
 
 ---
 
 ## 本体语义归档门禁
 
-- 归档前必须运行 `node skywalk-sdd/log.cjs semantic-reconcile --project=. --change=<变更名称>`，不能只信任文件观察事件。
-- 随后必须运行 `node skywalk-sdd/log.cjs semantic-check --project=. --change=<变更名称>`；有阻断诊断时禁止移动活动 Change。
+- 归档前必须运行 `node "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" semantic-reconcile --project=. --change=<变更名称>`，不能只信任文件观察事件。
+- 随后必须运行 `node "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" semantic-check --project=. --change=<变更名称>`；有阻断诊断时禁止移动活动 Change。
 - Archive 不负责首次生成 propose/spec/design/tasks 的工作态事实；它重新解析原文核对 pending revision，补充 `OntologySnapshot/project_id/archive_id` 后冻结为 confirmed。
 - `archive-docs` 成功后必须在归档目录生成 `archive-ontology.json`，并将 `review_status` 标记为 `confirmed`。
 - 生产端必须把 confirmed 本体转换为 `canonical-facts.json`；实体固定为 `fact_kind=semantic`、`assertion_type=asserted`、`review_status=confirmed`，关系必须补齐对应语义边界字段。

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

@@ -9,8 +9,8 @@ description: "opsx-archive 前后日志/总结自检清单 — 仅在 archive
 
 ## A. 归档前自检
 
-- [ ] `node skywalk-sdd/log.cjs doctor --project=. --change=<变更名称>` 无 `severe_issues`（`superseded_open_stages`/`rework_summary` 仅展示，不阻断）
-- [ ] `node skywalk-sdd/log.cjs tasks-status --project=. --change=<变更名称>` 已运行；未勾选项将进入 `archive_result.task_completion`，不阻断归档但必须如实记录
+- [ ] `node "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" doctor --project=. --change=<变更名称>` 无 `severe_issues`（`superseded_open_stages`/`rework_summary` 仅展示，不阻断）
+- [ ] `node "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" tasks-status --project=. --change=<变更名称>` 已运行；未勾选项将进入 `archive_result.task_completion`，不阻断归档但必须如实记录
 - [ ] `openspec/changes/<变更名称>/logs/execution-log.md` 各阶段条目齐全：propose/spec/design/task/check/apply/test/archive 的 `stage_start`/`stage_end` 闭环
 - [ ] execution-log 状态标记规范：成功 `✅OK`、部分 `🟡WARN`、失败 `❌FAIL`；未闭环阶段已修复或标记 partial
 - [ ] 无残留 Apply worktree（`git worktree list` 仅主工作区，或 telemetry 存在 `worktree_finish`+success 事件）

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

@@ -33,15 +33,15 @@ allowed-tools:
 
 > **🖥️ 跨平台执行规则**
 > - **SDD 文档根** = `*-sdd-specs` 包裹包（含 `openspec/`、`modules.yaml`），不是 Git 根或工作区根。
-> - `openspec` 命令：优先 `node skywalk-sdd/openspec-shim.cjs list`（自动 cd 到包裹包），或先 `cd` 到包裹包再执行。
-> - `skywalk-sdd/log.cjs` / `ontology/cli.cjs`：`--project=.` 在 Git 根/工作区根会自动解析；也可 `node skywalk-sdd/ontology/cli.cjs spec-root` 查看路径。
+> - `openspec` 命令：优先 `node "$(cat .sdd-spec-root)/skywalk-sdd/openspec-shim.cjs" list`（自动 cd 到包裹包），或先 `cd` 到包裹包再执行。
+> - Telemetry / ontology：`node "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" …`（Git 根无 skywalk-sdd/）；`spec-root` 可用 `node "$(cat .sdd-spec-root)/skywalk-sdd/ontology/cli.cjs" spec-root`。
 > - Telemetry 命令默认使用 `--project=.`，兼容 Windows、macOS、Linux。
 > - ${SHELL_GUIDANCE}
 > - 不要省略 `--source=opsx-command` 与 `--session-id=<会话ID>`。
 > **📊 Telemetry（必做，不得跳过）**
-> - 阶段开始：`node skywalk-sdd/log.cjs start --command=check --project=. --change=<变更名称> --capability=<可选capability-name> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID>`（保存 event_id）
-> - 检查报告生成后，必须先记录结构化检查结果：`node skywalk-sdd/log.cjs record --type=check_result --command=check --project=. --change=<变更名称> --capability=<可选capability-name> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID> --result=success/partial/failure --summary="检查结果摘要" --details-json="{\"check_results\":{\"total\":0,\"errors\":0,\"warnings\":0,\"warning_items\":[],\"suggestions\":0,\"fixed_before_apply\":0,\"consistency_score\":null,\"categories\":{\"completeness\":{\"passed\":0,\"total\":0},\"consistency\":{\"passed\":0,\"total\":0},\"executability\":{\"passed\":0,\"total\":0},\"tdd_compliance\":{\"passed\":0,\"total\":0}},\"task_completion\":{\"completed\":0,\"incomplete\":0,\"total\":0,\"has_incomplete\":false,\"checked_for_archive_readiness\":false}}}"`
-> - `check_result` 记录成功后，才允许阶段结束：`node skywalk-sdd/log.cjs end --event-id=<event_id> --command=check --project=. --change=<变更名称> --capability=<可选capability-name> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID> --result=success/partial/failure --summary="摘要"`
+> - 阶段开始：`node "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" start --command=check --project=. --change=<变更名称> --capability=<可选capability-name> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID>`（保存 event_id）
+> - 检查报告生成后，必须先记录结构化检查结果：`node "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" record --type=check_result --command=check --project=. --change=<变更名称> --capability=<可选capability-name> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID> --result=success/partial/failure --summary="检查结果摘要" --details-json="{\"check_results\":{\"total\":0,\"errors\":0,\"warnings\":0,\"warning_items\":[],\"suggestions\":0,\"fixed_before_apply\":0,\"consistency_score\":null,\"categories\":{\"completeness\":{\"passed\":0,\"total\":0},\"consistency\":{\"passed\":0,\"total\":0},\"executability\":{\"passed\":0,\"total\":0},\"tdd_compliance\":{\"passed\":0,\"total\":0}},\"task_completion\":{\"completed\":0,\"incomplete\":0,\"total\":0,\"has_incomplete\":false,\"checked_for_archive_readiness\":false}}}"`
+> - `check_result` 记录成功后，才允许阶段结束：`node "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" end --event-id=<event_id> --command=check --project=. --change=<变更名称> --capability=<可选capability-name> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID> --result=success/partial/failure --summary="摘要"`
 > - **【B1 摘要数字校验】** `stage_end --summary` 中的数字（如「N 个场景」「N 层 DAG」「N 个任务」）必须与 `spec.md`/`tasks.md`/`test-scenarios.md` 的实统计交叉校验一致后再填写，不得凭记忆自填。典型失真：summary 写「11 个场景」实际 spec 含 13 条断言、「5 层 DAG」实际 tasks 修复后为 6 层。check 阶段发现不一致时，修正 summary 或补齐文档，使三者数字自洽。
 
 ---
@@ -82,10 +82,10 @@ openspec list
 
 ```bash
 # 在 spec 仓库：
-node skywalk-sdd/ontology/cli.cjs diagnose-naming --project=. --change=<change-key>
+node "$(cat .sdd-spec-root)/skywalk-sdd/ontology/cli.cjs" diagnose-naming --project=. --change=<change-key>
 
 # 在代码仓库：
-node skywalk-sdd/ontology/cli.cjs diagnose-naming --project=. --mode=code-repo
+node "$(cat .sdd-spec-root)/skywalk-sdd/ontology/cli.cjs" diagnose-naming --project=. --mode=code-repo
 ```
 
 诊断结果三类：
@@ -122,7 +122,7 @@ node skywalk-sdd/ontology/cli.cjs diagnose-naming --project=. --mode=code-repo
    - 若未标记 → 继续检查。
 2. 运行 KB 就绪检查（程序化检测，自动搜索多 IDE 目录，消除路径歧义）：
    ```bash
-   node skywalk-sdd/context-client.cjs --check-only
+   node "$(cat .sdd-spec-root)/skywalk-sdd/context-client.cjs" --check-only
    ```
    - 输出 `"available": true` → KB 已配置
    - 输出 `"available": false` → KB 未配置
@@ -207,7 +207,7 @@ node skywalk-sdd/ontology/cli.cjs diagnose-naming --project=. --mode=code-repo
 `task` 阶段允许 `tasks.md` 出现未完成项；这只是计划状态。但如果当前变更已经进入 apply 之后，或本次 check 发现实现代码、测试报告、`build_result/test_result/task_update/conformance_review` 等实施证据，必须检查任务勾选状态：
 
 ```bash
-node skywalk-sdd/log.cjs tasks-status --project=. --change=<变更名称>
+node "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" tasks-status --project=. --change=<变更名称>
 ```
 
 判定规则：
@@ -250,7 +250,7 @@ node skywalk-sdd/log.cjs tasks-status --project=. --change=<变更名称>
 
 在终端执行（必须成功）：
 ```bash
-node skywalk-sdd/log.cjs record --type=check_result --command=check --project=. --change=<变更名称> --capability=<可选capability-name> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID> --result=success/partial/failure --summary="检查结果摘要" --details-json="{\"check_results\":{\"total\":0,\"errors\":0,\"warnings\":0,\"warning_items\":[],\"suggestions\":0,\"fixed_before_apply\":0,\"consistency_score\":null,\"categories\":{\"completeness\":{\"passed\":0,\"total\":0},\"consistency\":{\"passed\":0,\"total\":0},\"executability\":{\"passed\":0,\"total\":0},\"tdd_compliance\":{\"passed\":0,\"total\":0}},\"task_completion\":{\"completed\":0,\"incomplete\":0,\"total\":0,\"has_incomplete\":false,\"checked_for_archive_readiness\":false}}}"
+node "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" record --type=check_result --command=check --project=. --change=<变更名称> --capability=<可选capability-name> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID> --result=success/partial/failure --summary="检查结果摘要" --details-json="{\"check_results\":{\"total\":0,\"errors\":0,\"warnings\":0,\"warning_items\":[],\"suggestions\":0,\"fixed_before_apply\":0,\"consistency_score\":null,\"categories\":{\"completeness\":{\"passed\":0,\"total\":0},\"consistency\":{\"passed\":0,\"total\":0},\"executability\":{\"passed\":0,\"total\":0},\"tdd_compliance\":{\"passed\":0,\"total\":0}},\"task_completion\":{\"completed\":0,\"incomplete\":0,\"total\":0,\"has_incomplete\":false,\"checked_for_archive_readiness\":false}}}"
 ```
 
 > **⚠️ P1-1 check_result details 不得为空**：`--details-json` 必须含 `consistency_score` / `categories` / `task_completion` 等字段，**禁止传空对象 `{}`**。空 details 会导致 report 的 Q5 跨文档一致性得分、P4b 修复率为 null（工具侧虽有 state fallback 兜底，但事件 details 是主数据源）。
@@ -259,7 +259,7 @@ node skywalk-sdd/log.cjs record --type=check_result --command=check --project=.
 
 若当前已有实现代码，并且能够验证 spec 断言，还应记录 `conformance_review`（用于 Q1 规约符合度）：
 ```bash
-node skywalk-sdd/log.cjs record --type=conformance_review --command=check --project=. --change=<变更名称> --capability=<可选capability-name> --agent=<Agent类型> --source=manual --session-id=<会话ID> --result=success --summary="规约符合度评审" --details-json="{\"conformance_review\":{\"method\":\"llm-as-judge\",\"agent_confirmed\":true,\"human_status\":\"unverified\",\"reviewer\":\"<reviewer-identifier>\",\"assertions\":[{\"id\":\"ASSERT-001\",\"description\":\"规约中的可验证断言\",\"judge_status\":\"matched\",\"human_status\":\"matched\",\"evidence\":\"代码、测试或文档证据摘要\",\"files\":[],\"notes\":\"\"}]}}"
+node "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" record --type=conformance_review --command=check --project=. --change=<变更名称> --capability=<可选capability-name> --agent=<Agent类型> --source=manual --session-id=<会话ID> --result=success --summary="规约符合度评审" --details-json="{\"conformance_review\":{\"method\":\"llm-as-judge\",\"agent_confirmed\":true,\"human_status\":\"unverified\",\"reviewer\":\"<reviewer-identifier>\",\"assertions\":[{\"id\":\"ASSERT-001\",\"description\":\"规约中的可验证断言\",\"judge_status\":\"matched\",\"human_status\":\"matched\",\"evidence\":\"代码、测试或文档证据摘要\",\"files\":[],\"notes\":\"\"}]}}"
 ```
 
 > **human_status 说明（T3.4）**：`conformance_review.human_status` 标识本次评审是否经真实人工确认：`unverified`（AI 自评，待人工确认，默认）或 `matched`（已由人工评审确认）。**仅当真实人工评审时才填 `matched`**，避免 AI 自评被误标为已确认。报告 Q1 规约符合度会据此标注「自评，待人工确认」。
@@ -314,8 +314,8 @@ node skywalk-sdd/log.cjs record --type=conformance_review --command=check --proj
 在其他质量检查前必须运行：
 
 ```bash
-node skywalk-sdd/log.cjs semantic-reconcile --project=. --change=<变更名称> --profile=<simple|full|strict>
-node skywalk-sdd/log.cjs semantic-check --project=. --change=<变更名称> --profile=<simple|full|strict>
+node "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" semantic-reconcile --project=. --change=<变更名称> --profile=<simple|full|strict>
+node "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" semantic-check --project=. --change=<变更名称> --profile=<simple|full|strict>
 ```
 
 - `simple` 必须阻断 STMT 无 AC；没有 design/tasks 时跳过对应链路，不得误报。

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

@@ -31,7 +31,7 @@ allowed-tools:
 > 1. 检查 proposal.md frontmatter `kb-status`：若 `degraded(by-user-choice)` → 跳过 KB，仅用本地上下文。
 > 2. 否则运行 KB 就绪检查：
 > ```bash
-> node skywalk-sdd/context-client.cjs --check-only
+> node "$(cat .sdd-spec-root)/skywalk-sdd/context-client.cjs" --check-only
 > ```
 > - `"available": true` → 若需查历史设计参考，先 `Read` `opsx-ontology-query/phase-2-during.md` §1
 > - `"available": false` → **KB 不可用不阻塞 design 流程**，仅跳过历史设计参考查询
@@ -47,8 +47,8 @@ allowed-tools:
 
 > **🖥️ 跨平台执行规则**
 > - **SDD 文档根** = `*-sdd-specs` 包裹包（含 `openspec/`、`modules.yaml`），不是 Git 根或工作区根。
-> - `openspec` 命令：优先 `node skywalk-sdd/openspec-shim.cjs list`（自动 cd 到包裹包），或先 `cd` 到包裹包再执行。
-> - `skywalk-sdd/log.cjs` / `ontology/cli.cjs`：`--project=.` 在 Git 根/工作区根会自动解析；也可 `node skywalk-sdd/ontology/cli.cjs spec-root` 查看路径。
+> - `openspec` 命令：优先 `node "$(cat .sdd-spec-root)/skywalk-sdd/openspec-shim.cjs" list`（自动 cd 到包裹包），或先 `cd` 到包裹包再执行。
+> - Telemetry / ontology：`node "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" …`（Git 根无 skywalk-sdd/）；`spec-root` 可用 `node "$(cat .sdd-spec-root)/skywalk-sdd/ontology/cli.cjs" spec-root`。
 > - Telemetry 命令默认使用 `--project=.`，兼容 Windows、macOS、Linux。
 > - ${SHELL_GUIDANCE}
 > - 不要省略 `--source=opsx-command` 与 `--session-id=<会话ID>`。
@@ -184,7 +184,7 @@ design.md 中若使用 version 正则约束（如格式校验 `^\d+\.\d+\.\d+$`
 - 每个 DES 必须同时写 `entity-id`、`version-id`、`delta-state` 和按需的 `predecessor-version`；新增用 `semantic-identity --delta-state=added`，修改时复用实体 UUID 并生成新版本 UUID。
 - 每个 DES 必须通过 `**realizes**: STMT-*` 显式引用一个或多个真实 STMT。
 - 不得仅凭文本相似创建 realizes；没有上游 STMT 时必须标记 unresolved。
-- 生成结束后必须运行 `node skywalk-sdd/log.cjs semantic-reconcile --project=. --change=<name>`。
+- 生成结束后必须运行 `node "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" semantic-reconcile --project=. --change=<name>`。
 - reconcile 必须立即生成 `openspec/changes/<name>/artifacts/.../design.ontology.json`，其中 DES 和 realizes 关系保留原文 source；不得推迟到 check/archive。
 - 阶段 `stage_end` 会在无 Hook 环境下幂等执行同步兜底。
 

package/templates/skills/kld-sdd/opsx-design/reference.md

@@ -11,8 +11,8 @@ description: opsx-design 的详细模板：telemetry 命令、上下文类型表
 
 ## 📊 Telemetry 命令模板（必做，不得跳过）
 
-> 阶段开始：`node skywalk-sdd/log.cjs start --command=design --project=. --change=<变更名称> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID>`（保存 event_id）
-> 阶段结束：`node skywalk-sdd/log.cjs end --event-id=<event_id> --command=design --project=. --change=<变更名称> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID> --result=success|failure --summary="摘要"`
+> 阶段开始：`node "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" start --command=design --project=. --change=<变更名称> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID>`（保存 event_id）
+> 阶段结束：`node "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" end --event-id=<event_id> --command=design --project=. --change=<变更名称> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID> --result=success|failure --summary="摘要"`
 
 ---
 

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

@@ -17,14 +17,14 @@ allowed-tools:
 
 > **🖥️ 跨平台执行规则**
 > - **SDD 文档根** = `*-sdd-specs` 包裹包（含 `openspec/`、`modules.yaml`），不是 Git 根或工作区根。
-> - `openspec` 命令：优先 `node skywalk-sdd/openspec-shim.cjs list`（自动 cd 到包裹包），或先 `cd` 到包裹包再执行。
-> - `skywalk-sdd/log.cjs` / `ontology/cli.cjs`：`--project=.` 在 Git 根/工作区根会自动解析；也可 `node skywalk-sdd/ontology/cli.cjs spec-root` 查看路径。
+> - `openspec` 命令：优先 `node "$(cat .sdd-spec-root)/skywalk-sdd/openspec-shim.cjs" list`（自动 cd 到包裹包），或先 `cd` 到包裹包再执行。
+> - Telemetry / ontology：`node "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" …`（Git 根无 skywalk-sdd/）；`spec-root` 可用 `node "$(cat .sdd-spec-root)/skywalk-sdd/ontology/cli.cjs" spec-root`。
 > - Telemetry 命令默认使用 `--project=.`，兼容 Windows、macOS、Linux。
 > - ${SHELL_GUIDANCE}
 > - 不要省略 `--source=opsx-command` 与 `--session-id=<会话ID>`。
 > **📊 Telemetry（必做，不得跳过）**
-> - 阶段开始：`node skywalk-sdd/log.cjs start --command=explore --project=. --change=<变更名称> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID>`（保存 event_id）
-> - 阶段结束：`node skywalk-sdd/log.cjs end --event-id=<event_id> --command=explore --project=. --change=<变更名称> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID> --result=success|failure --summary="摘要"`
+> - 阶段开始：`node "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" start --command=explore --project=. --change=<变更名称> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID>`（保存 event_id）
+> - 阶段结束：`node "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" end --event-id=<event_id> --command=explore --project=. --change=<变更名称> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID> --result=success|failure --summary="摘要"`
 
 ---
 
@@ -44,7 +44,7 @@ allowed-tools:
 
 优先使用命名协议分组：
 ```bash
-node skywalk-sdd/ontology/cli.cjs list-changes --project=.
+node "$(cat .sdd-spec-root)/skywalk-sdd/ontology/cli.cjs" list-changes --project=.
 # 需要结构化数据时加 --json
 ```
 

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

@@ -35,8 +35,8 @@ allowed-tools:
 
 > **🖥️ 跨平台执行规则**
 > - **SDD 文档根** = `*-sdd-specs` 包裹包（含 `openspec/`、`modules.yaml`），不是 Git 根或工作区根。
-> - `openspec` 命令：优先 `node skywalk-sdd/openspec-shim.cjs list`（自动 cd 到包裹包），或先 `cd` 到包裹包再执行。
-> - `skywalk-sdd/log.cjs` / `ontology/cli.cjs`：`--project=.` 在 Git 根/工作区根会自动解析；也可 `node skywalk-sdd/ontology/cli.cjs spec-root` 查看路径。
+> - `openspec` 命令：优先 `node "$(cat .sdd-spec-root)/skywalk-sdd/openspec-shim.cjs" list`（自动 cd 到包裹包），或先 `cd` 到包裹包再执行。
+> - Telemetry / ontology：`node "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" …`（Git 根无 skywalk-sdd/）；`spec-root` 可用 `node "$(cat .sdd-spec-root)/skywalk-sdd/ontology/cli.cjs" spec-root`。
 > - Telemetry 命令默认使用 `--project=.`，兼容 Windows、macOS、Linux。
 > - ${SHELL_GUIDANCE}
 > - 不要省略 `--source=opsx-command` 与 `--session-id=<会话ID>`。
@@ -70,7 +70,7 @@ allowed-tools:
 5. 生成英文短 slug（小写、连字符、建议 ≤48 字符）
 6. 用本地日历日 `YYMMDD` 生成 change-key，并做冲突消解：
    ```bash
-   node skywalk-sdd/ontology/cli.cjs change-key --generate --module=<code> --slug=<slug> --project=.
+   node "$(cat .sdd-spec-root)/skywalk-sdd/ontology/cli.cjs" change-key --generate --module=<code> --slug=<slug> --project=.
    ```
 7. 得到：
    - `change-key`：spec 仓目录名 `openspec/changes/<change-key>/`（权威名称；不等于代码分支名）
@@ -92,7 +92,7 @@ allowed-tools:
 
 **重要**：未明确需求前不得继续。change-key 必须通过校验，禁止手写不合规目录名：
 ```bash
-node skywalk-sdd/ontology/cli.cjs change-key --validate <change-key> --project=.
+node "$(cat .sdd-spec-root)/skywalk-sdd/ontology/cli.cjs" change-key --validate <change-key> --project=.
 ```
 
 ### 2. 【上下文加载】识别并读取用户提供的文件
@@ -136,7 +136,7 @@ openspec new change "<change-key>"
 
 **第 4 步：隐式登记活动变更**（创建目录后立即执行，不询问用户）：
 ```bash
-node skywalk-sdd/ontology/cli.cjs active-change --register --change=<change-key> \
+node "$(cat .sdd-spec-root)/skywalk-sdd/ontology/cli.cjs" active-change --register --change=<change-key> \
   --title="<中文标题>" --module=<code> --summary="<一句话摘要>" --project=.
 ```
 
@@ -199,14 +199,14 @@ openspec instructions proposal --change "<name>" --json
 1. 收集 REQ 号（含可选 `feature-id`）；没有则问一次。
 2. 逐个验号（确定性入口，禁止肉眼判正则）：
 ```bash
-node skywalk-sdd/ontology/cli.cjs external-key --validate "<REQ-...>" --type requirement
+node "$(cat .sdd-spec-root)/skywalk-sdd/ontology/cli.cjs" external-key --validate "<REQ-...>" --type requirement
 # 若有 feature-id：
-node skywalk-sdd/ontology/cli.cjs external-key --validate "<FEAT-...>" --type feature
+node "$(cat .sdd-spec-root)/skywalk-sdd/ontology/cli.cjs" external-key --validate "<FEAT-...>" --type feature
 ```
    - REQ/FEAT 不合规 → **拒绝进入 resolve**，告知「编号不合规，请回需求管理系统核实/换发」；Agent 不得猜测、补位、改写。
    - 用户明确说「没有外部需求号」→ 走 `numbering-waiver.reason`（必填理由）；`requirement-refs` 必须为空；提示本轮不种桥。
 3. **先加载依赖技能**：确认 `${AGENT_SKILL_DIR}/opsx-ontology-query/SKILL.md` 存在并 Read；按该技能完成 API Key / 空间与 KB 选择（`../.shared/kb-state.json`，与 `opsx-kb-ingest` 共用）。未安装则停止本步。
-   - **KB 就绪检查**：运行 `node skywalk-sdd/context-client.cjs --check-only`，若 `"available": false`，使用 **AskUserQuestion** 询问用户：
+   - **KB 就绪检查**：运行 `node "$(cat .sdd-spec-root)/skywalk-sdd/context-client.cjs" --check-only`，若 `"available": false`，使用 **AskUserQuestion** 询问用户：
      > "📡 **Engineering KB 未配置**
      > KB 可以提供 Continuity 身份验证和 Capability 复用。是否现在配置？
      > - A. **配置 KB**（加载 opsx-ontology-query 走 Session 启动）
@@ -217,7 +217,7 @@ node skywalk-sdd/ontology/cli.cjs external-key --validate "<FEAT-...>" --type fe
      - **选 C** → 终止 propose。
 4. 验号通过后才 resolve：
 ```bash
-node skywalk-sdd/context-client.cjs --mode=resolve \
+node "$(cat .sdd-spec-root)/skywalk-sdd/context-client.cjs" --mode=resolve \
   --external-system=requirement-mgmt \
   --external-object-type=requirement \
   --external-id="<REQ-...>" \
@@ -315,10 +315,10 @@ Read openspec/changes/archive/*/ontology-identities.json
 - 每个新增 Capability 必须写成 `[CAP-<CAPABILITY>] <slug>: <说明>`。
 - 修改既有 Capability 时必须复用已有 CAP ID，不得修改或重新分配已有实体 ID。
 - 分配新 CAP ID 前必须扫描当前 proposal 和归档中的显式编号；不得只凭标题认定跨 Change 同一性。
-- 每个 Change/Capability 同时写人工锚点、`entity-id`、`version-id` 和 `delta-state`。新增时必须调用 `node skywalk-sdd/log.cjs semantic-identity --delta-state=added`，不得手写或复制 UUID。
+- 每个 Change/Capability 同时写人工锚点、`entity-id`、`version-id` 和 `delta-state`。新增时必须调用 `node "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" semantic-identity --delta-state=added`，不得手写或复制 UUID。
 - 修改既有 Capability 时调用 `semantic-identity --delta-state=modified --entity-id=<历史实体UUID> --predecessor-version=<直接前序版本UUID>`；复用实体 UUID，但必须生成新版本 UUID。
 - 本阶段只声明 Change 和 Capability，不得提前生成 STMT、AC、DES 或 TASK 事实。
-- proposal.md 写入结束后必须立即运行 `node skywalk-sdd/log.cjs semantic-reconcile --project=. --change=<name>`，生成 `openspec/changes/<name>/artifacts/proposal.ontology.json`；不得等到 check 或 archive 才首次生成 JSON。
+- proposal.md 写入结束后必须立即运行 `node "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" semantic-reconcile --project=. --change=<name>`，生成 `openspec/changes/<name>/artifacts/proposal.ontology.json`；不得等到 check 或 archive 才首次生成 JSON。
 - 阶段 `stage_end` 会在无 Hook 环境下幂等执行同一次同步作为兜底，结果中的 `semantic_state.artifact_json_paths` 必须包含 proposal 对应 JSON。
 
 ## Guardrails

package/templates/skills/kld-sdd/opsx-propose/reference.md

@@ -11,8 +11,8 @@ description: opsx-propose 的详细模板：telemetry 命令、文档拆分模
 
 ## 📊 Telemetry 命令模板（必做，不得跳过）
 
-> 阶段开始：`node skywalk-sdd/log.cjs start --command=propose --project=. --change=<变更名称> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID>`（保存 event_id）
-> 阶段结束：`node skywalk-sdd/log.cjs end --event-id=<event_id> --command=propose --project=. --change=<变更名称> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID> --result=success|failure --summary="摘要"`
+> 阶段开始：`node "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" start --command=propose --project=. --change=<变更名称> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID>`（保存 event_id）
+> 阶段结束：`node "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" end --event-id=<event_id> --command=propose --project=. --change=<变更名称> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID> --result=success|failure --summary="摘要"`
 
 ---
 

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

@@ -19,9 +19,9 @@ allowed-tools:
 你是一个 SDD 项目规则生成与维护专家。激活本技能后，你将扫描项目事实，为已部署的 Agent 生成或审查规则文件。
 
 > **🖥️ 跨平台执行规则**
-> - **SDD 文档根** = `*-sdd-specs` 包裹包（含 `openspec/`、`modules.yaml`），不是 Git 根或工作区根。
-> - `openspec` 命令：优先 `node skywalk-sdd/openspec-shim.cjs list`（自动 cd 到包裹包），或先 `cd` 到包裹包再执行。
-> - `skywalk-sdd/log.cjs` / `ontology/cli.cjs`：`--project=.` 在 Git 根/工作区根会自动解析；也可 `node skywalk-sdd/ontology/cli.cjs spec-root` 查看路径。
+> - **SDD 文档根** = `*-sdd-specs` 包裹包（含 `openspec/`、`modules.yaml`、`skywalk-sdd/`），不是 Git 根。
+> - **CLI 前缀**：Git/工作区根执行时用 `node "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" …`；**不要**在 Git 根另建 `skywalk-sdd/`。
+> - `openspec`：优先 `node "$(cat .sdd-spec-root)/skywalk-sdd/openspec-shim.cjs" list`，或先 `cd` 到包裹包再执行。
 > - ${SHELL_GUIDANCE}
 > - **本技能不写入 SkyWalk Telemetry**（与 `opsx-knowledge` 同属辅助技能，不走 `log.cjs start/end`）。
 

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

@@ -35,8 +35,8 @@ allowed-tools:
 
 > **🖥️ 跨平台执行规则**
 > - **SDD 文档根** = `*-sdd-specs` 包裹包（含 `openspec/`、`modules.yaml`），不是 Git 根或工作区根。
-> - `openspec` 命令：优先 `node skywalk-sdd/openspec-shim.cjs list`（自动 cd 到包裹包），或先 `cd` 到包裹包再执行。
-> - `skywalk-sdd/log.cjs` / `ontology/cli.cjs`：`--project=.` 在 Git 根/工作区根会自动解析；也可 `node skywalk-sdd/ontology/cli.cjs spec-root` 查看路径。
+> - `openspec` 命令：优先 `node "$(cat .sdd-spec-root)/skywalk-sdd/openspec-shim.cjs" list`（自动 cd 到包裹包），或先 `cd` 到包裹包再执行。
+> - Telemetry / ontology：`node "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" …`（Git 根无 skywalk-sdd/）；`spec-root` 可用 `node "$(cat .sdd-spec-root)/skywalk-sdd/ontology/cli.cjs" spec-root`。
 > - Telemetry 命令默认使用 `--project=.`，兼容 Windows、macOS、Linux。
 > - ${SHELL_GUIDANCE}
 > - 不要省略 `--source=opsx-command` 与 `--session-id=<会话ID>`。
@@ -117,7 +117,7 @@ openspec list
    - 若未标记 → 继续检查。
 2. 运行 KB 就绪检查（程序化检测，自动搜索多 IDE 目录，消除路径歧义）：
    ```bash
-   node skywalk-sdd/context-client.cjs --check-only
+   node "$(cat .sdd-spec-root)/skywalk-sdd/context-client.cjs" --check-only
    ```
    - 输出 `"available": true` → KB 已配置
    - 输出 `"available": false` → KB 未配置
@@ -148,7 +148,7 @@ openspec list
 2. 读取 proposal Continuity。对**当前 Capability** 各调一次（「全部」= 循环 N 次，不是一次大查询）——优先走 **`opsx-ontology-query`** 的 `match-requirement`；薄封装仅作参数拼装：
 
 ```bash
-node skywalk-sdd/context-client.cjs \
+node "$(cat .sdd-spec-root)/skywalk-sdd/context-client.cjs" \
   --query="<当前 Capability 的自然语言需求>" \
   --target-stage=spec \
   --entity-id="<该 CAP 的 entity_id>" \
@@ -260,7 +260,7 @@ node skywalk-sdd/context-client.cjs \
 - 对 `reuseMode=REFERENCE` 的历史候选必须创建新的实体身份；禁止因为内容相似而复用历史 `entity-id`。
 - 对 `reuseMode=INHERIT` 的历史事实，必须使用返回的实体与版本来源完成 unchanged/modified 身份参数校验。
 - unchanged 内容只写人工锚点、历史实体 UUID、历史版本 UUID 和来源引用，不复制历史原文；调用 `semantic-identity --delta-state=unchanged --entity-id=<UUID> --version-id=<UUID>` 校验复用参数，引用断链时保持 unresolved 并交由 check 阻断。
-- 生成结束后必须运行 `node skywalk-sdd/log.cjs semantic-reconcile --project=. --change=<name>`，根据诊断修复缺号、重号和悬空引用。
+- 生成结束后必须运行 `node "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" semantic-reconcile --project=. --change=<name>`，根据诊断修复缺号、重号和悬空引用。
 - reconcile 必须在 change 目录生成 `openspec/changes/<name>/artifacts/spec.ontology.json` 或 `openspec/changes/<name>/artifacts/specs/<capability>/spec.ontology.json`；该 JSON 是 draft 工作事实，不得等待 check/archive 才生成。
 - 阶段 `stage_end` 会在无 Hook 环境下幂等执行同步兜底，并返回 `semantic_state.artifact_json_paths`。
 

package/templates/skills/kld-sdd/opsx-spec/reference.md

@@ -11,8 +11,8 @@ description: opsx-spec 的详细模板：telemetry 命令、上下文类型表
 
 ## 📊 Telemetry 命令模板（必做，不得跳过）
 
-> 阶段开始：`node skywalk-sdd/log.cjs start --command=spec --project=. --change=<变更名称> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID>`（保存 event_id）
-> 阶段结束：`node skywalk-sdd/log.cjs end --event-id=<event_id> --command=spec --project=. --change=<变更名称> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID> --result=success|failure --summary="摘要"`
+> 阶段开始：`node "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" start --command=spec --project=. --change=<变更名称> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID>`（保存 event_id）
+> 阶段结束：`node "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" end --event-id=<event_id> --command=spec --project=. --change=<变更名称> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID> --result=success|failure --summary="摘要"`
 
 ---
 

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

@@ -32,7 +32,7 @@ allowed-tools:
 > 1. 检查 proposal.md frontmatter `kb-status`：若 `degraded(by-user-choice)` → 跳过 KB，仅用本地上下文。
 > 2. 否则运行 KB 就绪检查：
 > ```bash
-> node skywalk-sdd/context-client.cjs --check-only
+> node "$(cat .sdd-spec-root)/skywalk-sdd/context-client.cjs" --check-only
 > ```
 > - `"available": true` → 若需查历史任务参考，先 `Read` `opsx-ontology-query/phase-2-during.md` §2
 > - `"available": false` → **KB 不可用不阻塞 task 流程**，仅跳过历史任务追溯参考
@@ -48,8 +48,8 @@ allowed-tools:
 
 > **🖥️ 跨平台执行规则**
 > - **SDD 文档根** = `*-sdd-specs` 包裹包（含 `openspec/`、`modules.yaml`），不是 Git 根或工作区根。
-> - `openspec` 命令：优先 `node skywalk-sdd/openspec-shim.cjs list`（自动 cd 到包裹包），或先 `cd` 到包裹包再执行。
-> - `skywalk-sdd/log.cjs` / `ontology/cli.cjs`：`--project=.` 在 Git 根/工作区根会自动解析；也可 `node skywalk-sdd/ontology/cli.cjs spec-root` 查看路径。
+> - `openspec` 命令：优先 `node "$(cat .sdd-spec-root)/skywalk-sdd/openspec-shim.cjs" list`（自动 cd 到包裹包），或先 `cd` 到包裹包再执行。
+> - Telemetry / ontology：`node "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" …`（Git 根无 skywalk-sdd/）；`spec-root` 可用 `node "$(cat .sdd-spec-root)/skywalk-sdd/ontology/cli.cjs" spec-root`。
 > - Telemetry 命令默认使用 `--project=.`，兼容 Windows、macOS、Linux。
 > - ${SHELL_GUIDANCE}
 > - 不要省略 `--source=opsx-command` 与 `--session-id=<会话ID>`。
@@ -236,7 +236,7 @@ Simple 模式或单文件能力域下，**不要拆成多个同文件任务**。
 - 每个 TASK 必须同时写 `entity-id`、`version-id` 和 `delta-state`；新增任务调用 `semantic-identity --delta-state=added`，不得复用其他任务 UUID。
 - 每个 TASK 必须写 `**implements**: DES-*` 或 `**covers**: STMT-*`，不得生成无上游来源任务。
 - 任务依赖必须写 `**dependsOn**: TASK-*`；无依赖显式写“无”，所有依赖必须构成 DAG。
-- 生成结束后必须运行 `node skywalk-sdd/log.cjs semantic-reconcile --project=. --change=<name>`。
+- 生成结束后必须运行 `node "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" semantic-reconcile --project=. --change=<name>`。
 - reconcile 必须立即生成 `openspec/changes/<name>/artifacts/.../tasks.ontology.json`，包含 TASK、implements/covers/dependsOn 及原文 source；不得推迟到 check/archive。
 - 阶段 `stage_end` 会在无 Hook 环境下幂等执行同步兜底。
 

package/templates/skills/kld-sdd/opsx-task/reference.md

@@ -11,8 +11,8 @@ description: opsx-task 的详细模板：telemetry 命令、DAG 生成规则表
 
 ## 📊 Telemetry 命令模板（必做，不得跳过）
 
-> 阶段开始：`node skywalk-sdd/log.cjs start --command=task --project=. --change=<变更名称> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID>`（保存 event_id）
-> 阶段结束：`node skywalk-sdd/log.cjs end --event-id=<event_id> --command=task --project=. --change=<变更名称> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID> --result=success|failure --summary="摘要"`
+> 阶段开始：`node "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" start --command=task --project=. --change=<变更名称> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID>`（保存 event_id）
+> 阶段结束：`node "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" end --event-id=<event_id> --command=task --project=. --change=<变更名称> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID> --result=success|failure --summary="摘要"`
 
 ---
 

package/templates/skills/kld-sdd/opsx-tdd-core/reference.md

@@ -123,13 +123,13 @@ description: "opsx-tdd-core 详细参考 — 执行步骤、拆分示例、DAG
 **TDD 测试骨架任务**（`task_kind:"test-skeleton"`）：
 
 ```bash
-node skywalk-sdd/log.cjs record --type=task_update --command=apply --project=. --change=<变更名称> --capability=<capability-name> --task-id=<TASK-ID> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID> --status=completed --result=success --summary="<TASK-ID> 测试骨架完成（TDD 红灯）" --details-json='{"task_kind":"test-skeleton","test_results":{"command":"<实际测试命令>","passed":0,"failed":<红灯数>,"skipped":0,"duration_ms":0}}'
+node "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" record --type=task_update --command=apply --project=. --change=<变更名称> --capability=<capability-name> --task-id=<TASK-ID> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID> --status=completed --result=success --summary="<TASK-ID> 测试骨架完成（TDD 红灯）" --details-json='{"task_kind":"test-skeleton","test_results":{"command":"<实际测试命令>","passed":0,"failed":<红灯数>,"skipped":0,"duration_ms":0}}'
 ```
 
 **实现任务**（不带 `task_kind`）：
 
 ```bash
-node skywalk-sdd/log.cjs record --type=task_update --command=apply --project=. --change=<变更名称> --capability=<capability-name> --task-id=<TASK-ID> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID> --status=completed --result=success --summary="<TASK-ID> 完成" --details-json='{"files_changed":[],"test_results":{"command":"<实际测试命令>","passed":<通过数>,"failed":0,"skipped":0,"duration_ms":0}}'
+node "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" record --type=task_update --command=apply --project=. --change=<变更名称> --capability=<capability-name> --task-id=<TASK-ID> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID> --status=completed --result=success --summary="<TASK-ID> 完成" --details-json='{"files_changed":[],"test_results":{"command":"<实际测试命令>","passed":<通过数>,"failed":0,"skipped":0,"duration_ms":0}}'
 ```
 
 ## §9 单元测试真实执行
@@ -138,7 +138,7 @@ node skywalk-sdd/log.cjs record --type=task_update --command=apply --project=. -
 
 1. 在结束 apply 或执行收尾之前，必须真实运行单元测试命令
 2. 须留下可核验 telemetry 证据（任选其一）：
-   - `node skywalk-sdd/log.cjs record --type=test_result ...`（`test_results.command` 非空，且 `passed`/`failed`/`duration_ms` 有实际值）
+   - `node "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" record --type=test_result ...`（`test_results.command` 非空，且 `passed`/`failed`/`duration_ms` 有实际值）
    - `task_update` 的 `details-json` 中 `test_results` 含真实执行数据
    - 或单独运行 `/opsx-test` 并完成 `command=test` 的 `stage_end`
 3. `sdd-apply-test-gate.cjs` 会在 `log.cjs end`、`apply-worktree-finish`、会话 Stop 时自动校验，无证据则阻断

package/templates/skills/kld-sdd/opsx-tdd-rules/rules/test-skeleton-telemetry.md

@@ -7,7 +7,7 @@
 当任务是"测试骨架"（仅编写测试用例、实现尚未编写，测试预期失败/红灯）时，`task_update` 必须在 `--details-json` 中带 `"task_kind":"test-skeleton"`，`--result=success`（骨架按 TDD 计划完成即成功），`test_results.failed` 如实记录红灯数。
 
 ```bash
-node skywalk-sdd/log.cjs record --type=task_update --command=apply --project=. --change=<变更名称> --capability=<capability-name> --task-id=<TASK-ID> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID> --status=completed --result=success --summary="<TASK-ID> 测试骨架完成（TDD 红灯）" --details-json='{"task_kind":"test-skeleton","test_results":{"command":"<实际测试命令>","passed":0,"failed":<红灯数>,"skipped":0,"duration_ms":0}}'
+node "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" record --type=task_update --command=apply --project=. --change=<变更名称> --capability=<capability-name> --task-id=<TASK-ID> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID> --status=completed --result=success --summary="<TASK-ID> 测试骨架完成（TDD 红灯）" --details-json='{"task_kind":"test-skeleton","test_results":{"command":"<实际测试命令>","passed":0,"failed":<红灯数>,"skipped":0,"duration_ms":0}}'
 ```
 
 ## 实现任务
@@ -15,5 +15,5 @@ node skywalk-sdd/log.cjs record --type=task_update --command=apply --project=. -
 实现任务不带 `task_kind`（默认 implementation），按真实测试结果记录。
 
 ```bash
-node skywalk-sdd/log.cjs record --type=task_update --command=apply --project=. --change=<变更名称> --capability=<capability-name> --task-id=<TASK-ID> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID> --status=completed --result=success --summary="<TASK-ID> 完成" --details-json='{"files_changed":[],"test_results":{"command":"<实际测试命令>","passed":<通过数>,"failed":0,"skipped":0,"duration_ms":0}}'
+node "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" record --type=task_update --command=apply --project=. --change=<变更名称> --capability=<capability-name> --task-id=<TASK-ID> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID> --status=completed --result=success --summary="<TASK-ID> 完成" --details-json='{"files_changed":[],"test_results":{"command":"<实际测试命令>","passed":<通过数>,"failed":0,"skipped":0,"duration_ms":0}}'
 ```

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

@@ -25,14 +25,14 @@ allowed-tools:
 
 > **🖥️ 跨平台执行规则**
 > - **SDD 文档根** = `*-sdd-specs` 包裹包（含 `openspec/`、`modules.yaml`），不是 Git 根或工作区根。
-> - `openspec` 命令：优先 `node skywalk-sdd/openspec-shim.cjs list`（自动 cd 到包裹包），或先 `cd` 到包裹包再执行。
-> - `skywalk-sdd/log.cjs` / `ontology/cli.cjs`：`--project=.` 在 Git 根/工作区根会自动解析；也可 `node skywalk-sdd/ontology/cli.cjs spec-root` 查看路径。
+> - `openspec` 命令：优先 `node "$(cat .sdd-spec-root)/skywalk-sdd/openspec-shim.cjs" list`（自动 cd 到包裹包），或先 `cd` 到包裹包再执行。
+> - Telemetry / ontology：`node "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" …`（Git 根无 skywalk-sdd/）；`spec-root` 可用 `node "$(cat .sdd-spec-root)/skywalk-sdd/ontology/cli.cjs" spec-root`。
 > - Telemetry 命令默认使用 `--project=.`，兼容 Windows、macOS、Linux。
 > - ${SHELL_GUIDANCE}
 > - 不要省略 `--source=opsx-command` 与 `--session-id=<会话ID>`。
 > **📊 Telemetry（必做，不得跳过）**
-> - 阶段开始：`node skywalk-sdd/log.cjs start --command=test --project=. --change=<变更名称> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID>`（保存 event_id）
-> - 阶段结束：`node skywalk-sdd/log.cjs end --event-id=<event_id> --command=test --project=. --change=<变更名称> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID> --result=success|failure --summary="摘要"`
+> - 阶段开始：`node "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" start --command=test --project=. --change=<变更名称> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID>`（保存 event_id）
+> - 阶段结束：`node "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" end --event-id=<event_id> --command=test --project=. --change=<变更名称> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID> --result=success|failure --summary="摘要"`
 
 ---
 
@@ -108,7 +108,7 @@ allowed-tools:
 测试执行完成后，在 stage_end 之前记录 `test_result` 事件：
 
 ```bash
-node skywalk-sdd/log.cjs record --type=test_result --command=test --project=. --change=<变更名称> --capability=<可选capability-name> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID> --result=success/failure --summary="[passed]/[total] passed" --details-json="{\"test_results\":{\"command\":\"<实际测试命令>\",\"passed\":<passed>,\"failed\":<failed>,\"skipped\":<skipped>,\"coverage\":<coverage>,\"duration_ms\":<duration_ms>}}"
+node "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" record --type=test_result --command=test --project=. --change=<变更名称> --capability=<可选capability-name> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID> --result=success/failure --summary="[passed]/[total] passed" --details-json="{\"test_results\":{\"command\":\"<实际测试命令>\",\"passed\":<passed>,\"failed\":<failed>,\"skipped\":<skipped>,\"coverage\":<coverage>,\"duration_ms\":<duration_ms>}}"
 ```
 
 此事件供 report 的 `test_pass_summary` 采集（M3），确保报告能显示真实测试通过率。