kld-sdd 2.6.9 → 2.6.10

package/lib/init.js

@@ -687,14 +687,13 @@ function cleanupNativeOpenspecSkills(selectedTools = Object.keys(TOOL_CONFIGS))
 }
 
 /**
- * 复制标准文档模版到项目
+ * 复制标准文档模版到项目（openspec-templates/）
  */
-function copyTemplatesToProject() {
+function copyTemplatesToProject(cwd = process.cwd()) {
   console.log('📄 正在复制标准文档模版到项目...');
   
   const pkgPath = getPackagePath();
   const templatePath = path.join(pkgPath, 'templates', 'openspec');
-  const cwd = process.cwd();
   const targetDir = path.join(cwd, 'openspec-templates');
   
   if (!fs.existsSync(templatePath)) {
@@ -702,12 +701,10 @@ function copyTemplatesToProject() {
     return false;
   }
   
-  // 创建目标目录
   if (!fs.existsSync(targetDir)) {
     fs.mkdirSync(targetDir, { recursive: true });
   }
   
-  // 复制模版文件
   copyDir(templatePath, targetDir);
   
   console.log(`✅ 标准文档模版已复制到: ${targetDir}`);
@@ -724,29 +721,24 @@ function copyTemplatesToProject() {
  * 初始化全局 overview.md 到 openspec/specs/ 目录
  * overview.md 是全局架构约束，所有 Capability 的设计都必须遵守
  */
-function initGlobalOverview() {
+function initGlobalOverview(cwd = process.cwd()) {
   console.log('🌐 正在初始化全局架构约束 (overview.md)...');
   
   const pkgPath = getPackagePath();
   const overviewSource = path.join(pkgPath, 'templates', 'openspec', 'overview.md');
-  const cwd = process.cwd();
   const targetDir = path.join(cwd, 'openspec', 'specs');
   const targetFile = path.join(targetDir, 'overview.md');
   
-  // 检查源文件是否存在
   if (!fs.existsSync(overviewSource)) {
     console.log(`⚠️  overview.md 源文件不存在: ${overviewSource}`);
     return false;
   }
   
-  // 创建目标目录
   if (!fs.existsSync(targetDir)) {
     fs.mkdirSync(targetDir, { recursive: true });
   }
   
-  // 检查目标文件是否已存在
   if (fs.existsSync(targetFile)) {
-    // 读取现有文件，检查是否需要更新
     const existingContent = fs.readFileSync(targetFile, 'utf-8');
     const newContent = fs.readFileSync(overviewSource, 'utf-8');
     
@@ -755,13 +747,11 @@ function initGlobalOverview() {
       return true;
     }
     
-    // 备份现有文件
     const backupFile = path.join(targetDir, 'overview.md.backup');
     fs.copyFileSync(targetFile, backupFile);
     console.log(`   ℹ️  已备份现有 overview.md 到 ${backupFile}`);
   }
   
-  // 复制 overview.md
   fs.copyFileSync(overviewSource, targetFile);
   
   console.log(`✅ 全局架构约束已初始化: ${targetFile}`);
@@ -857,7 +847,15 @@ function deployTelemetryDataDir(targetCwd = process.cwd()) {
     console.log('   ✓ 部署 skywalk-sdd/apply-worktree-finish.cjs（Apply 收尾脚本）');
   }
 
+  const openspecShimSrc = path.join(pkgPath, 'skywalk-sdd', 'openspec-shim.cjs');
+  const openspecShimDst = path.join(dataDir, 'openspec-shim.cjs');
+  if (fs.existsSync(openspecShimSrc)) {
+    fs.copyFileSync(openspecShimSrc, openspecShimDst);
+    console.log('   ✓ 部署 skywalk-sdd/openspec-shim.cjs（openspec 包裹包路径 shim）');
+  }
+
   console.log('   ✓ 调用方式: node skywalk-sdd/log.cjs start|end|metrics|semantic-identity|semantic-reconcile|semantic-check');
+  console.log('   ✓ openspec: node skywalk-sdd/openspec-shim.cjs list（自动 cd 到 *-sdd-specs）');
   console.log('   ✓ Spec Context: node skywalk-sdd/context-client.cjs --query="<自然语言需求>" --target-stage=spec');
   console.log('   ✓ Apply worktree: record-base 在 §1.5；收尾 apply-worktree-finish.cjs --change=<name>');
   console.log('✅ Telemetry 已就绪（数据存储在 skywalk-sdd/，无需配置 MCP）');
@@ -1065,32 +1063,98 @@ function deployDotSddYaml(cwd = process.cwd(), pkgPath = getPackagePath()) {
 }
 
 /**
- * 单仓（openspec 与代码同仓）声明 layout: mono。
+ * 单仓声明 layout: mono，并记录仓内统一包裹目录相对路径。
  * commit-msg Hook 靠它跳过「spec 工作区干净」检查并只写 Spec-Change。
  */
-function deployMonoSddYaml(cwd = process.cwd()) {
+function deployMonoSddYaml(cwd = process.cwd(), options = {}) {
   const target = path.join(cwd, '.sdd.yaml');
+  const specRel = options.specPathRelative
+    ? String(options.specPathRelative).replace(/\\/g, '/')
+    : '';
+
   if (fs.existsSync(target)) {
     const existing = fs.readFileSync(target, 'utf8');
     if (/^layout:\s*mono\s*$/m.test(existing)) {
+      if (specRel && !new RegExp(`^spec_path:\\s*${specRel.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\s*$`, 'm').test(existing)) {
+        // 已有 mono 但缺/错 spec_path：补写相对路径
+        let next = existing.replace(/\s*$/, '');
+        if (/^spec_path:\s*.+$/m.test(next)) {
+          next = next.replace(/^spec_path:\s*.+$/m, `spec_path: ${specRel}`);
+        } else {
+          next = `${next}\nspec_path: ${specRel}`;
+        }
+        fs.writeFileSync(target, `${next}\n`, 'utf8');
+        console.log(`   ✓ 已更新 .sdd.yaml spec_path → ${specRel}`);
+        return true;
+      }
       console.log('   ✓ .sdd.yaml 已声明 layout: mono，跳过');
       return true;
     }
-    console.log('⚠️  .sdd.yaml 已存在但未声明 layout: mono；单仓请手动补一行 `layout: mono`');
+    console.log('⚠️  .sdd.yaml 已存在但未声明 layout: mono；单仓请手动补 `layout: mono`');
     return false;
   }
   const lines = [
-    '# 单仓布局：openspec 文档与代码在同一个仓库',
-    '# commit-msg 只写 Spec-Change（spec 与代码同属一次 commit，无需 Spec-Revision 指针）',
+    '# 单仓布局：业务代码与 SDD 包裹包在同一个 Git 仓库',
+    '# SDD 内容统一在 spec_path 目录内（openspec / modules / sdd.config / 模版）',
+    '# commit-msg 只写 Spec-Change（同仓一次 commit，无需 Spec-Revision 指针）',
     'version: 1',
     'layout: mono',
-    '',
   ];
+  if (specRel) lines.push(`spec_path: ${specRel}`);
+  lines.push('');
   fs.writeFileSync(target, lines.join('\n'), 'utf8');
-  console.log(`✅ 已创建 .sdd.yaml（layout: mono）: ${target}`);
+  console.log(`✅ 已创建 .sdd.yaml（layout: mono${specRel ? `, spec_path: ${specRel}` : ''}）: ${target}`);
   return true;
 }
 
+/**
+ * 向统一 SDD 包裹目录写入完整内容（多仓兄弟仓 / 单仓内部子目录共用）。
+ * 不在此部署编辑器 skills——skills 只装工作目录或单仓 Git 根。
+ */
+async function populateSpecPackage(specRoot, options = {}) {
+  const root = path.resolve(specRoot);
+  const skipOpenspec = Boolean(options.skipOpenspec);
+  const asIndependentGit = Boolean(options.asIndependentGit);
+  console.log(`📦 正在填充 SDD 包裹包: ${root}`);
+
+  if (!skipOpenspec) {
+    const prev = process.cwd();
+    try {
+      process.chdir(root);
+      // 包裹包内只建 openspec 目录结构，不把编辑器配置写进文档仓
+      await runOpenspecInit([]);
+    } finally {
+      process.chdir(prev);
+    }
+  }
+
+  deployTelemetryDataDir(root);
+  if (asIndependentGit || workspaceLayout.isGitRepo(root)) {
+    deployQualityGateTemplates(root, { mode: 'full' });
+  }
+  deployModulesYaml(root);
+  deploySddConfigYaml(root);
+  copyTemplatesToProject(root);
+  initGlobalOverview(root);
+  deploySddGuideManual(root);
+  console.log(`✅ SDD 包裹包已就绪: ${path.basename(root)}`);
+  return { ok: true, path: root };
+}
+
+/**
+ * 在工作区 / Git 根写入 .sdd-spec-root，供 shell 与 skills 引用相对包裹包路径。
+ */
+function writeSddSpecRootHint(anchorDir, specPackageAbs) {
+  const anchor = path.resolve(anchorDir);
+  const specAbs = path.resolve(specPackageAbs);
+  const rel = path.relative(anchor, specAbs).replace(/\\/g, '/');
+  if (!rel || rel.startsWith('..')) return null;
+  const filePath = path.join(anchor, '.sdd-spec-root');
+  fs.writeFileSync(filePath, `${rel}\n`, 'utf8');
+  console.log(`   ✓ 已写入 .sdd-spec-root → ${rel}`);
+  return filePath;
+}
+
 /**
  * 检测当前项目已初始化的 AI 编辑器
  */
@@ -1274,32 +1338,21 @@ async function main() {
   }
 
   const workspaceRoot = process.cwd();
-  const layout = workspaceLayout.detectWorkspaceLayout(workspaceRoot);
+  let layout = workspaceLayout.detectWorkspaceLayout(workspaceRoot);
+  let specPackage = layout.specRepo
+    ? { name: layout.specRepo.name, abs: layout.specRepo.abs, created: false, isGit: true }
+    : null;
+
   if (layout.isWorkspace) {
     console.log('📂 检测到个人工作目录布局（子目录 Git 仓库）');
-    console.log(`   Spec: ${layout.specRepo ? layout.specRepo.name : '(未发现)'}`);
+    console.log(`   Spec: ${specPackage ? specPackage.name : '(未发现，将自动创建包裹包)'}`);
     console.log(`   代码仓: ${layout.codeRepos.map((c) => c.name).join(', ') || '(无)'}`);
-    console.log('   → skills 只部署到本工作目录；代码仓仅轻量接入 Hook/关联');
+    console.log('   → skills 只部署到本工作目录；SDD 文档统一进 *-sdd-specs 包裹包');
     console.log();
   }
 
-  // 1. openspec init：工作区模式下若有 spec 仓则在其内执行
-  if (!skipOpenspec) {
-    if (layout.isWorkspace && layout.specRepo) {
-      const prev = process.cwd();
-      try {
-        process.chdir(layout.specRepo.abs);
-        await runOpenspecInit(selectedTools);
-      } finally {
-        process.chdir(prev);
-      }
-    } else {
-      await runOpenspecInit(selectedTools);
-    }
-  }
-
   if (!skipTemplate) {
-    // 2/3. skills 与编辑器产物：永远只装在当前工作目录一次
+    // skills / 编辑器产物：永远只装在当前工作目录一次
     cleanupNativeOpenspecCommands(selectedTools);
     cleanupLegacyBundledOpsxSkills(selectedTools);
     deployOpsxSkills(selectedTools);
@@ -1307,49 +1360,93 @@ async function main() {
     deployProfileArtifacts(selectedTools, workspaceRoot, getPackagePath());
 
     if (layout.isWorkspace) {
-      // 工作目录本身保留一份 telemetry，供 skills 调用
       deployTelemetryDataDir(workspaceRoot);
 
-      if (layout.specRepo) {
-        const prev = process.cwd();
-        try {
-          process.chdir(layout.specRepo.abs);
-          deployTelemetryDataDir(layout.specRepo.abs);
-          deployQualityGateTemplates(layout.specRepo.abs, { mode: 'full' });
-          deployModulesYaml(layout.specRepo.abs);
-          deploySddConfigYaml(layout.specRepo.abs);
-          copyTemplatesToProject();
-          initGlobalOverview();
-          deploySddGuideManual(layout.specRepo.abs);
-        } finally {
-          process.chdir(prev);
-        }
+      if (!specPackage) {
+        console.log('📦 未发现 spec 仓，正在创建统一 SDD 包裹包（独立 Git）...');
+        specPackage = workspaceLayout.ensureSpecPackage(workspaceRoot, { initGit: true });
+        console.log(`   ✓ ${specPackage.created ? '已创建' : '已复用'}: ${specPackage.name}`);
+      }
 
-        console.log();
-        console.log('🔗 正在为子代码仓做轻量接入（不安装 skills）...');
-        for (const repo of layout.codeRepos) {
-          attachCodeRepoLite(repo.abs, layout.specRepo.abs);
-        }
-        const wsFile = workspaceLayout.writeWorkspaceFile(workspaceRoot, layout);
-        console.log(`✅ 工作区清单: ${wsFile}`);
-      } else {
-        console.log('⚠️  未发现 spec 仓，已跳过代码仓 Hook 接入。请先准备 *-sdd-specs 子目录后执行: kld-sdd sync-repos');
+      await populateSpecPackage(specPackage.abs, {
+        skipOpenspec,
+        asIndependentGit: true,
+      });
+      writeSddSpecRootHint(workspaceRoot, specPackage.abs);
+
+      // 重新探测，刷新 layout.specRepo / codeRepos
+      layout = workspaceLayout.detectWorkspaceLayout(workspaceRoot);
+      if (!layout.specRepo) {
+        layout.specRepo = { name: specPackage.name, abs: specPackage.abs };
+      }
+
+      console.log();
+      console.log('🔗 正在为子代码仓做轻量接入（不安装 skills）...');
+      for (const repo of layout.codeRepos) {
+        attachCodeRepoLite(repo.abs, specPackage.abs);
       }
+      const wsFile = workspaceLayout.writeWorkspaceFile(workspaceRoot, layout);
+      console.log(`✅ 工作区清单: ${wsFile}`);
     } else {
-      // 单仓模式（旧行为）：当前目录既是项目根
+      // 单仓：Git 根只放代码 + skills + Hook；SDD 内容进统一包裹子目录
+      const isGit = workspaceLayout.isGitRepo(workspaceRoot);
       deployTelemetryDataDir(workspaceRoot);
-      deployQualityGateTemplates(workspaceRoot, { mode: 'full' });
-      deployModulesYaml(workspaceRoot);
-      deploySddConfigYaml(workspaceRoot);
-      if (workspaceLayout.isGitRepo(workspaceRoot)) {
-        // openspec 与代码同仓：显式声明单仓，Hook 才会写 Spec-Change
-        deployMonoSddYaml(workspaceRoot);
+
+      if (isGit) {
+        console.log('📦 单仓模式：创建/复用仓内统一 SDD 包裹目录...');
+        specPackage = workspaceLayout.ensureSpecPackage(workspaceRoot, { initGit: false });
+        console.log(`   ✓ ${specPackage.created ? '已创建' : '已复用'}: ${specPackage.name}`);
+
+        await populateSpecPackage(specPackage.abs, {
+          skipOpenspec,
+          asIndependentGit: false,
+        });
+        writeSddSpecRootHint(workspaceRoot, specPackage.abs);
+
+        deployMonoSddYaml(workspaceRoot, { specPathRelative: specPackage.name });
+        // Hook 装在 Git 根；Trailer 读包裹目录里的 sdd.config / openspec
+        deployQualityGateTemplates(workspaceRoot, { mode: 'commit-msg-only' });
+        const linked = sddConfig.setSpecPath(workspaceRoot, specPackage.abs, {
+          allowNestedPackage: true,
+        });
+        if (linked.ok) {
+          console.log(`   ✓ sdd.specPath = ${linked.path}`);
+        } else {
+          console.log(`   ⚠️  未能写入 sdd.specPath: ${linked.message}`);
+        }
       } else {
+        // 非 Git 目录：仍创建包裹包，便于随后 git init
+        console.log('📦 当前目录不是 Git 仓：仍创建 SDD 包裹包（请稍后 git init）...');
+        specPackage = workspaceLayout.ensureSpecPackage(workspaceRoot, { initGit: false });
+        await populateSpecPackage(specPackage.abs, {
+          skipOpenspec,
+          asIndependentGit: false,
+        });
         deployDotSddYaml(workspaceRoot);
       }
-      copyTemplatesToProject();
-      initGlobalOverview();
-      deploySddGuideManual(workspaceRoot);
+    }
+  } else if (!skipOpenspec) {
+    // 仅 openspec、跳过模版时：仍尊重包裹包，避免在工作区根平铺
+    if (layout.isWorkspace) {
+      if (!specPackage) {
+        specPackage = workspaceLayout.ensureSpecPackage(workspaceRoot, { initGit: true });
+      }
+      const prev = process.cwd();
+      try {
+        process.chdir(specPackage.abs);
+        await runOpenspecInit([]);
+      } finally {
+        process.chdir(prev);
+      }
+    } else {
+      specPackage = workspaceLayout.ensureSpecPackage(workspaceRoot, { initGit: false });
+      const prev = process.cwd();
+      try {
+        process.chdir(specPackage.abs);
+        await runOpenspecInit([]);
+      } finally {
+        process.chdir(prev);
+      }
     }
   }
 
@@ -1369,8 +1466,9 @@ async function main() {
     console.log('工作区部署结果:');
     console.log('  🎯 工作目录 .*/skills/opsx-*/     # skills 只装这一份');
     console.log('  📋 .sdd-workspace.yaml           # 子仓编排清单');
-    if (layout.specRepo) {
-      console.log(`  📄 ${layout.specRepo.name}/modules.yaml + openspec-templates`);
+    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）`);
@@ -1380,12 +1478,13 @@ async function main() {
     console.log('  kld-sdd sync-repos');
     console.log('Trailer 仍在各代码仓 git commit 时由 Hook 写入。');
   } else {
-    console.log('已生成/覆盖:');
-    console.log('  🌐 openspec/specs/overview.md     # 全局架构约束（数据字典、接口规范）');
-    console.log('  📖 openspec/kld-sdd操作手册.html   # SDD 操作手册（HTML）');
-    console.log('  📄 openspec-templates/           # 标准文档模版（参考用）');
-    console.log('  📦 modules.yaml / .sdd.yaml      # 多仓库命名与关联配置');
-    console.log('  🎯 .*/skills/opsx-*/              # SDD skills（扁平一层）');
+    console.log('单仓部署结果:');
+    console.log('  🎯 .*/skills/opsx-*/              # SDD skills（装在 Git 根）');
+    if (specPackage) {
+      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');
   }
   if (selectedTools.includes('kunlunzhima')) {
     console.log('  📎 .kunlunzhima/commands/opsx/    # KunlunZhima OPSX command bridge（11 个）');
@@ -1398,9 +1497,8 @@ async function main() {
     console.log('  🪝 .claude/hooks/                 # Claude Code SDD Hook Pack（可选增强）');
   }
   if (!layout.isWorkspace) {
-    console.log('  📊 skywalk-sdd/                  # SDD Telemetry 数据目录');
-    console.log('  🧰 skywalk-sdd/git-hooks/        # Git hooks 质量门禁模板');
-    console.log('  🧪 skywalk-sdd/ci/               # CI 兜底采集模板');
+    console.log('  📊 skywalk-sdd/                  # Hook 运行时 ontology（Git 根）');
+    console.log('  🧰 skywalk-sdd/git-hooks/        # commit-msg Trailer Hook');
   }
   console.log();
   
@@ -1420,8 +1518,10 @@ async function main() {
     
   console.log();
   console.log('后续步骤:');
-  if (layout.isWorkspace && layout.specRepo) {
-    console.log(`  0. 文档类命令请以 spec 仓为 --project（例: --project=${layout.specRepo.name}）`);
+  if (layout.isWorkspace && specPackage) {
+    console.log(`  0. 文档类命令请以包裹包为 --project（例: --project=${specPackage.name}）`);
+  } else if (specPackage) {
+    console.log(`  0. 文档类命令请以包裹包为 --project（例: --project=${specPackage.name}）`);
   }
   console.log('  1. 激活 opsx-propose skill，输入变更名称开始创建文档');
   console.log('  2. 按顺序执行 propose → spec → design → task');
@@ -1438,8 +1538,12 @@ async function main() {
   }
   console.log();
   console.log('📊 SDD Telemetry（嵌入在 skill 流程中，自动执行，无需配置）：');
-  console.log('  - 度量数据自动采集到 skywalk-sdd/events/');
-  console.log('  - 运行 node skywalk-sdd/log.cjs metrics --project=. 查看四维度指标');
+  if (specPackage) {
+    console.log(`  - 文档侧度量在 ${specPackage.name}/skywalk-sdd/events/`);
+  } else {
+    console.log('  - 度量数据自动采集到 skywalk-sdd/events/');
+  }
+  console.log('  - 运行 node skywalk-sdd/log.cjs metrics --project=<包裹包> 查看四维度指标');
   console.log();
 
   rl.close();
@@ -1458,6 +1562,8 @@ module.exports = {
   deploySddConfigYaml,
   deployDotSddYaml,
   deployMonoSddYaml,
+  populateSpecPackage,
+  writeSddSpecRootHint,
   deployQualityGateTemplates,
   deployTelemetryDataDir,
   attachCodeRepoLite,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kld-sdd",
-  "version": "2.6.9",
+  "version": "2.6.10",
   "description": "KLD SDD OpenSpec 项目初始化工具 - 一键部署 SDD skills",
   "main": "index.js",
   "bin": {
@@ -8,7 +8,7 @@
     "kld-sdd-init": "bin/kld-sdd-init.js"
   },
   "scripts": {
-    "test": "node test/external-key.cjs && node test/change-key.cjs && node test/modules-and-sdd-config.cjs && node test/active-changes.cjs && node test/hook-layouts.cjs && node test/workspace-layout.cjs && node test/ontology-release-blockers.cjs && node test/ontology-semantic-core.cjs && node test/ontology-identity-versioning.cjs && node test/ontology-identity-continuity.cjs && node test/ontology-state-transaction.cjs && node test/ontology-process-concurrency.cjs && node test/ontology-observer-convergence.cjs && node test/ontology-working-runtime.cjs && node test/ontology-stage-materialization.cjs && node test/ontology-template-contract.cjs && node test/ontology-cli-archive.cjs && node test/archive-package-producer.cjs && node test/validate-skills-bundle.cjs && node test/tool-profiles.cjs && node test/settings-merge.cjs && node test/command-bridge.cjs && node test/codebuddy-hooks.cjs && node test/skill-content-contract.cjs && node test/init-agent-profiles.cjs"
+    "test": "node test/external-key.cjs && node test/change-key.cjs && node test/modules-and-sdd-config.cjs && node test/active-changes.cjs && node test/hook-layouts.cjs && node test/spec-package-init.cjs && node test/workspace-layout.cjs && node test/ontology-release-blockers.cjs && node test/ontology-semantic-core.cjs && node test/ontology-identity-versioning.cjs && node test/ontology-identity-continuity.cjs && node test/ontology-state-transaction.cjs && node test/ontology-process-concurrency.cjs && node test/ontology-observer-convergence.cjs && node test/ontology-working-runtime.cjs && node test/ontology-stage-materialization.cjs && node test/ontology-template-contract.cjs && node test/ontology-cli-archive.cjs && node test/archive-package-producer.cjs && node test/validate-skills-bundle.cjs && node test/tool-profiles.cjs && node test/settings-merge.cjs && node test/command-bridge.cjs && node test/codebuddy-hooks.cjs && node test/skill-content-contract.cjs && node test/init-agent-profiles.cjs"
   },
   "keywords": [
     "kld",

package/skywalk-sdd/index.cjs

@@ -13,6 +13,7 @@
 
 const fs = require('fs');
 const path = require('path');
+const { resolveProjectArg } = require('./ontology/resolve-spec-root.cjs');
 const crypto = require('crypto');
 const { execFileSync } = require('child_process');
 
@@ -73,11 +74,11 @@ function nowISO() {
 }
 
 function normalizeProjectRoot(projectRoot) {
-  const rawProjectRoot = projectRoot || process.cwd();
+  const rawProjectRoot = projectRoot || '.';
   if (process.platform === 'win32' && /^[a-zA-Z]:[^\\/]/.test(String(rawProjectRoot))) {
     fail(`Windows 项目路径格式不安全: ${rawProjectRoot}。请使用 --project=.，或使用正斜杠路径如 D:/project/demo，或给路径加引号。`);
   }
-  return path.resolve(rawProjectRoot);
+  return resolveProjectArg(rawProjectRoot, process.cwd());
 }
 
 function inferAgentType(args) {

package/skywalk-sdd/ontology/cli.cjs

@@ -17,6 +17,7 @@ const namingDiagnose = require('./naming-diagnose.cjs');
 const listChanges = require('./list-changes.cjs');
 const sddConfig = require('./sdd-config.cjs');
 const activeChanges = require('./active-changes.cjs');
+const { resolveProjectArg } = require('./resolve-spec-root.cjs');
 
 function parseArgs(argv) {
   const result = { _: [] };
@@ -70,6 +71,7 @@ function showHelp() {
   node skywalk-sdd/ontology/cli.cjs active-change --register --change=<key> [--title=] [--summary=] [--module=]
   node skywalk-sdd/ontology/cli.cjs active-change --remove --change=<key>
   node skywalk-sdd/ontology/cli.cjs active-change --list [--json]
+  node skywalk-sdd/ontology/cli.cjs spec-root [--project=.] [--json]
   node skywalk-sdd/ontology/cli.cjs reconcile --project=. --change=<name> [--profile=...]
   node skywalk-sdd/ontology/cli.cjs check     --project=. --change=<name> [--profile=...]
   node skywalk-sdd/ontology/cli.cjs status    --project=. --change=<name>
@@ -79,6 +81,10 @@ function showHelp() {
 observe 只负责采集和同步；check/archive 前仍必须执行 reconcile。`);
 }
 
+function resolveCliProject(args, options = {}) {
+  return resolveProjectArg(args.project || '.', process.cwd(), options);
+}
+
 function main(argv = process.argv.slice(2)) {
   const args = parseArgs(argv);
   const command = args._[0];
@@ -109,7 +115,7 @@ function main(argv = process.argv.slice(2)) {
   }
   if (command === 'change-key') {
     if (args.generate || args._[1] === 'generate') {
-      const projectRoot = path.resolve(args.project || '.');
+      const projectRoot = resolveCliProject(args);
       const registry = modules.loadModulesYaml(projectRoot);
       const existing = listChanges.listActiveChanges(projectRoot);
       const built = changeKey.buildChangeKey(args.module, args.slug, {
@@ -123,7 +129,7 @@ function main(argv = process.argv.slice(2)) {
     }
     const key = args.validate || args._[1];
     if (!key) throw new Error('用法: change-key --validate <key> | --generate --module= --slug=');
-    const projectRoot = path.resolve(args.project || '.');
+    const projectRoot = resolveCliProject(args);
     const registry = modules.loadModulesYaml(projectRoot);
     const result = changeKey.validate(key, {
       registeredModules: registry.ok ? registry.codes : null,
@@ -140,7 +146,7 @@ function main(argv = process.argv.slice(2)) {
     return;
   }
   if (command === 'modules') {
-    const projectRoot = path.resolve(args.project || '.');
+    const projectRoot = resolveCliProject(args);
     const result = modules.loadModulesYaml(projectRoot);
     console.log(JSON.stringify({
       ok: result.ok,
@@ -170,7 +176,7 @@ function main(argv = process.argv.slice(2)) {
     return;
   }
   if (command === 'list-changes') {
-    const projectRoot = path.resolve(args.project || '.');
+    const projectRoot = resolveCliProject(args);
     const result = listChanges.groupChanges(projectRoot);
     if (args.json) {
       console.log(JSON.stringify(result, null, 2));
@@ -179,8 +185,29 @@ function main(argv = process.argv.slice(2)) {
     }
     return;
   }
+  if (command === 'spec-root') {
+    const start = path.resolve(args.project || '.');
+    const { resolveSpecProjectRoot, isSpecPackageRoot } = require('./resolve-spec-root.cjs');
+    const specRoot = resolveSpecProjectRoot(start);
+    const payload = {
+      start,
+      specRoot,
+      resolved: specRoot !== start || isSpecPackageRoot(start),
+      openspecShim: 'node skywalk-sdd/openspec-shim.cjs <openspec-args>',
+    };
+    if (args.json) {
+      console.log(JSON.stringify(payload, null, 2));
+    } else {
+      console.log(`start: ${payload.start}`);
+      console.log(`specRoot: ${payload.specRoot}`);
+      console.log(`resolved: ${payload.resolved}`);
+      console.log(`openspec: cd "${payload.specRoot}" && openspec list`);
+      console.log(`shim: ${payload.openspecShim}`);
+    }
+    return;
+  }
   if (command === 'link-spec') {
-    const projectRoot = path.resolve(args.project || '.');
+    const projectRoot = resolveCliProject(args, { forCodeRepo: true });
     const specPath = args.path || args._[1];
     if (!specPath) throw new Error('用法: link-spec --path=<spec-clone> [--project=.]');
     const result = sddConfig.setSpecPath(projectRoot, specPath);
@@ -189,7 +216,7 @@ function main(argv = process.argv.slice(2)) {
     return;
   }
   if (command === 'active-change') {
-    const specRoot = path.resolve(args.project || '.');
+    const specRoot = resolveCliProject(args);
     if (args.list || args._[1] === 'list') {
       const config = activeChanges.loadSddConfig(specRoot);
       if (args.json) {
@@ -227,7 +254,7 @@ function main(argv = process.argv.slice(2)) {
     if (!result.ok) process.exitCode = 1;
     return;
   }
-  const projectRoot = path.resolve(args.project || '.');
+  const projectRoot = resolveCliProject(args);
   const changeName = args.change;
   if (!changeName) throw new Error('缺少 --change 参数');
   const profile = args.profile || 'auto';

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

@@ -57,6 +57,7 @@ function readProposalFrontmatter(changeDir) {
 }
 
 function detectEntryMode(projectRoot) {
+  if (sddConfig.isMonoLayout(projectRoot)) return 'mono-repo';
   const hasModules = fs.existsSync(path.join(projectRoot, 'modules.yaml'));
   const hasOpenspecChanges = fs.existsSync(path.join(projectRoot, 'openspec', 'changes'));
   const hasSddYaml = fs.existsSync(path.join(projectRoot, '.sdd.yaml'));
@@ -281,40 +282,94 @@ function diagnoseSpecRepo(projectRoot, changeName) {
     ...diagnoseActiveChanges(projectRoot, changeName),
   });
 
-  // 单仓（openspec 与代码同仓）：Hook 装在本仓，应就地检查
-  if (isMonoRepoLayout(projectRoot)) {
+  checks.push({
+    id: 'code-repo-association',
+    status: STATUS.SKIP,
+    message: '当前位于 spec 仓库：代码仓 .sdd.yaml / Hook 请在各代码仓库或工作目录诊断',
+  });
+
+  return {
+    mode: 'spec-repo',
+    checks,
+    summary: summarize(checks),
+  };
+}
+
+/**
+ * 单仓：Git 根有 layout: mono；SDD 内容在仓内统一包裹目录。
+ */
+function diagnoseMonoRepo(gitRoot, changeName) {
+  const root = path.resolve(gitRoot);
+  const specRoot = sddConfig.resolveMonoSpecRoot(root);
+  const checks = [];
+
+  checks.push({
+    id: 'spec-git',
+    status: workspaceLayout.isGitRepo(root) ? STATUS.PASS : STATUS.FAIL,
+    message: workspaceLayout.isGitRepo(root)
+      ? '单仓 Git 根可用'
+      : '单仓目录不是 Git 仓库',
+  });
+
+  const remote = sddConfig.gitRemoteUrl(root);
+  checks.push({
+    id: 'spec-remote',
+    status: remote ? STATUS.PASS : STATUS.NEEDS_INPUT,
+    message: remote ? `remote 可识别: ${remote}` : '无法识别 git remote',
+    remote,
+  });
+
+  const registry = modules.loadModulesYaml(specRoot);
+  checks.push({
+    id: 'modules-yaml',
+    status: registry.ok ? STATUS.PASS : (registry.code === modules.CODES.MISSING ? STATUS.NEEDS_INPUT : STATUS.FAIL),
+    message: registry.ok
+      ? `modules.yaml 合法（${registry.codes.size} 个模块，路径 ${path.relative(root, specRoot) || '.'}）`
+      : registry.message,
+    registry,
+  });
+
+  if (changeName) {
+    const naming = diagnoseChangeNaming(specRoot, changeName, registry.ok ? registry : null);
     checks.push({
-      id: 'commit-hook',
-      ...checkHookInstalled(projectRoot),
+      id: 'change-naming',
+      status: naming.status,
+      message: naming.message,
+      detail: naming,
     });
+  } else {
     checks.push({
-      id: 'code-repo-association',
-      status: STATUS.PASS,
-      message: '单仓布局（.sdd.yaml layout: mono）：commit 写 Spec-Change，不写 Spec-Revision',
+      id: 'change-naming',
+      status: STATUS.SKIP,
+      message: '未指定 --change，跳过命名一致性检查',
     });
-    return {
-      mode: 'mono-repo',
-      checks,
-      summary: summarize(checks),
-    };
   }
 
+  checks.push({
+    id: 'active-changes',
+    ...diagnoseActiveChanges(specRoot, changeName),
+  });
+
+  checks.push({
+    id: 'commit-hook',
+    ...checkHookInstalled(root),
+  });
   checks.push({
     id: 'code-repo-association',
-    status: STATUS.SKIP,
-    message: '当前位于 spec 仓库：代码仓 .sdd.yaml / Hook 请在各代码仓库或工作目录诊断',
+    status: STATUS.PASS,
+    message: `单仓布局（layout: mono，包裹包 ${path.relative(root, specRoot) || '.'}）：commit 写 Spec-Change，不写 Spec-Revision`,
   });
 
   return {
-    mode: 'spec-repo',
+    mode: 'mono-repo',
     checks,
     summary: summarize(checks),
+    specRoot,
   };
 }
 
 /**
- * 单仓：openspec 与代码同仓，由 .sdd.yaml 的 layout: mono 显式声明。
- * 不用启发式，否则独立的 spec 仓 clone 会被误判成单仓。
+ * 单仓：由 .sdd.yaml 的 layout: mono 显式声明。
  */
 function isMonoRepoLayout(projectRoot) {
   return sddConfig.isMonoLayout(path.resolve(projectRoot));
@@ -532,6 +587,10 @@ function diagnose(projectRoot, options = {}) {
     };
   }
 
+  if (mode === 'mono-repo' || isMonoRepoLayout(root)) {
+    return diagnoseMonoRepo(root, options.change);
+  }
+
   if (mode === 'code-repo') {
     return diagnoseCodeRepo(root);
   }
@@ -586,6 +645,7 @@ module.exports = {
   diagnoseChangeNaming,
   diagnoseActiveChanges,
   diagnoseWorkspaceRepos,
+  diagnoseMonoRepo,
   isMonoRepoLayout,
   diagnose,
   diagnoseTrailer,

package/skywalk-sdd/ontology/resolve-spec-root.cjs

@@ -0,0 +1,102 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const sddConfig = require('./sdd-config.cjs');
+const workspaceLayout = require('./workspace-layout.cjs');
+
+function isSpecPackageRoot(dir) {
+  const root = path.resolve(dir);
+  return (
+    fs.existsSync(path.join(root, 'openspec', 'changes'))
+    || fs.existsSync(path.join(root, 'modules.yaml'))
+    || fs.existsSync(path.join(root, 'sdd.config.yaml'))
+  );
+}
+
+/**
+ * 解析 SDD 文档根（*-sdd-specs 包裹包或旧平铺 spec 根）。
+ * openspec CLI 只认 cwd 下的 openspec/；本函数供 log.cjs / ontology cli 自动定位包裹包。
+ *
+ * 解析顺序：
+ * 1. start 本身已是 spec 包根
+ * 2. KLD_SDD_SPEC_ROOT（绝对或相对 start）
+ * 3. 单仓 layout: mono → spec_path / 子目录 *-sdd-specs
+ * 4. 工作区 layout → specRepo
+ * 5. start 下嵌套包裹包
+ * 6. 代码仓 git config sdd.specPath（含仓内 nested 包裹）
+ * 7. 向上最多 3 层找 mono / 嵌套包（Git 根、工作区根常见）
+ * 8. 回退 start
+ */
+function resolveSpecProjectRoot(startDir = process.cwd(), options = {}) {
+  const start = path.resolve(startDir || process.cwd());
+  if (options.skipResolve || options.forCodeRepo) return start;
+  if (isSpecPackageRoot(start)) return start;
+
+  const envRoot = process.env.KLD_SDD_SPEC_ROOT && String(process.env.KLD_SDD_SPEC_ROOT).trim();
+  if (envRoot) {
+    const candidate = path.isAbsolute(envRoot) ? envRoot : path.resolve(start, envRoot);
+    if (fs.existsSync(candidate)) return candidate;
+  }
+
+  if (sddConfig.isMonoLayout(start)) {
+    const monoRoot = sddConfig.resolveMonoSpecRoot(start);
+    if (fs.existsSync(monoRoot)) return monoRoot;
+  }
+
+  const layout = workspaceLayout.detectWorkspaceLayout(start);
+  if (layout.specRepo && fs.existsSync(layout.specRepo.abs)) {
+    return layout.specRepo.abs;
+  }
+
+  const nested = workspaceLayout.findNestedSpecPackage(start);
+  if (nested) return nested.abs;
+
+  const specPathResult = sddConfig.resolveSpecPath(start);
+  if (specPathResult.ok) {
+    const valid = sddConfig.validateSpecPath(specPathResult.path, { allowNestedPackage: true });
+    if (valid.ok) return valid.path;
+  }
+
+  let dir = start;
+  for (let depth = 0; depth < 3; depth += 1) {
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    if (sddConfig.isMonoLayout(parent)) {
+      const monoRoot = sddConfig.resolveMonoSpecRoot(parent);
+      if (fs.existsSync(monoRoot)) return monoRoot;
+    }
+    const parentNested = workspaceLayout.findNestedSpecPackage(parent);
+    if (parentNested) return parentNested.abs;
+    const parentLayout = workspaceLayout.detectWorkspaceLayout(parent);
+    if (parentLayout.specRepo && fs.existsSync(parentLayout.specRepo.abs)) {
+      return parentLayout.specRepo.abs;
+    }
+    dir = parent;
+  }
+
+  return start;
+}
+
+/**
+ * CLI / skills 用：解析 --project 参数。
+ * '.' 或未显式绝对 spec 根时走 resolve；link-spec 等代码仓命令传 forCodeRepo:true。
+ */
+function resolveProjectArg(projectArg, startDir = process.cwd(), options = {}) {
+  const raw = projectArg == null || projectArg === '' ? '.' : String(projectArg);
+  const resolved = path.resolve(startDir, raw);
+  if (options.forCodeRepo) return resolved;
+  if (raw !== '.' && raw !== './' && path.isAbsolute(raw)) {
+    return isSpecPackageRoot(resolved) ? resolved : resolveSpecProjectRoot(resolved, options);
+  }
+  if (raw !== '.' && raw !== './') {
+    if (isSpecPackageRoot(resolved)) return resolved;
+  }
+  return resolveSpecProjectRoot(startDir, options);
+}
+
+module.exports = {
+  isSpecPackageRoot,
+  resolveSpecProjectRoot,
+  resolveProjectArg,
+};

package/skywalk-sdd/ontology/sdd-config.cjs

@@ -35,15 +35,17 @@ function stripYamlQuotes(value) {
  *   version: 1
  *   spec_repository: git@host:group/repo.git
  *
- * 单仓：openspec 与代码同仓，无外部 spec 可指
+ * 单仓：同一 Git 仓内用统一包裹目录存放 openspec / 配置
  *   version: 1
  *   layout: mono
+ *   spec_path: myapp-sdd-specs
  */
 function parseSddYaml(text) {
   const lines = String(text || '').split(/\r?\n/);
   let version = null;
   let specRepository = null;
   let layout = null;
+  let specPathRel = null;
 
   for (let index = 0; index < lines.length; index += 1) {
     const raw = lines[index];
@@ -76,6 +78,12 @@ function parseSddYaml(text) {
       continue;
     }
 
+    const pathMatch = /^spec_path:\s*(.+?)\s*$/.exec(line);
+    if (pathMatch) {
+      specPathRel = stripYamlQuotes(pathMatch[1]);
+      continue;
+    }
+
     return {
       ok: false,
       code: CODES.FORMAT_INVALID,
@@ -108,6 +116,7 @@ function parseSddYaml(text) {
     version,
     layout: resolvedLayout,
     spec_repository: specRepository || '',
+    spec_path: specPathRel || '',
   };
 }
 
@@ -132,6 +141,29 @@ function isMonoLayout(repoRoot) {
   return loaded.ok && loaded.layout === LAYOUTS.MONO;
 }
 
+/**
+ * 单仓 SDD 包裹根：优先 .sdd.yaml spec_path → 子目录 *-sdd-specs → 兼容旧平铺根目录。
+ */
+function resolveMonoSpecRoot(repoRoot) {
+  const root = path.resolve(repoRoot);
+  const loaded = loadSddYaml(root);
+  if (loaded.ok && loaded.spec_path) {
+    return path.resolve(root, loaded.spec_path);
+  }
+  const workspaceLayout = require('./workspace-layout.cjs');
+  const nested = workspaceLayout.findNestedSpecPackage(root);
+  if (nested) return nested.abs;
+  return root;
+}
+
+function looksLikeSpecPackageContent(dir) {
+  return (
+    fs.existsSync(path.join(dir, 'modules.yaml'))
+    || fs.existsSync(path.join(dir, 'sdd.config.yaml'))
+    || fs.existsSync(path.join(dir, 'openspec', 'changes'))
+  );
+}
+
 function gitConfig(cwd, key) {
   try {
     return execFileSync('git', ['config', '--local', '--get', key], {
@@ -203,7 +235,7 @@ function resolveSpecPath(codeRepoRoot, env = process.env) {
   };
 }
 
-function validateSpecPath(specPath) {
+function validateSpecPath(specPath, options = {}) {
   if (!specPath || !fs.existsSync(specPath)) {
     return {
       ok: false,
@@ -211,25 +243,37 @@ function validateSpecPath(specPath) {
       message: `spec 路径不存在: ${specPath}`,
     };
   }
-  if (!fs.existsSync(path.join(specPath, '.git'))) {
-    return {
-      ok: false,
-      code: CODES.SPEC_PATH_INVALID,
-      message: `spec 路径不是 Git 仓库: ${specPath}`,
-    };
+  if (fs.existsSync(path.join(specPath, '.git'))) {
+    return { ok: true, path: specPath, nested: false };
+  }
+  // 单仓内部包裹包：不是独立 Git，但内容齐全且落在某个 Git 仓内
+  if (options.allowNestedPackage && looksLikeSpecPackageContent(specPath)) {
+    return { ok: true, path: specPath, nested: true };
   }
-  return { ok: true, path: specPath };
+  return {
+    ok: false,
+    code: CODES.SPEC_PATH_INVALID,
+    message: `spec 路径不是 Git 仓库: ${specPath}`,
+  };
 }
 
-function setSpecPath(codeRepoRoot, specPath) {
+function setSpecPath(codeRepoRoot, specPath, options = {}) {
   const absolute = path.resolve(specPath);
-  const valid = validateSpecPath(absolute);
+  const valid = validateSpecPath(absolute, options);
   if (!valid.ok) return valid;
-  execFileSync('git', ['config', '--local', 'sdd.specPath', absolute], {
-    cwd: codeRepoRoot,
-    stdio: ['ignore', 'pipe', 'pipe'],
-  });
-  return { ok: true, path: absolute };
+  try {
+    execFileSync('git', ['config', '--local', 'sdd.specPath', absolute], {
+      cwd: codeRepoRoot,
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+  } catch (error) {
+    return {
+      ok: false,
+      code: CODES.SPEC_PATH_INVALID,
+      message: `无法写入 git config sdd.specPath（请确认目录是真实 Git 仓库）: ${error.message}`,
+    };
+  }
+  return { ok: true, path: absolute, nested: Boolean(valid.nested) };
 }
 
 function resolveCodeRepoContext(codeRepoRoot, env = process.env) {
@@ -320,6 +364,8 @@ module.exports = {
   LAYOUTS,
   parseSddYaml,
   isMonoLayout,
+  resolveMonoSpecRoot,
+  looksLikeSpecPackageContent,
   loadSddYaml,
   gitConfig,
   gitRemoteUrl,

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

@@ -181,14 +181,95 @@ function findNewCodeRepos(workspaceRoot) {
   };
 }
 
+/**
+ * 推导统一 SDD 包裹目录名：`<parentBasename>-sdd-specs`
+ */
+function deriveSpecPackageName(parentDir) {
+  const base = path.basename(path.resolve(parentDir)).toLowerCase();
+  if (!base || base === '.' || base === '/' || base === '\\') return 'project-sdd-specs';
+  if (base.endsWith('sdd-specs')) return path.basename(path.resolve(parentDir));
+  return `${path.basename(path.resolve(parentDir))}-sdd-specs`;
+}
+
+function listChildDirectories(parentDir) {
+  const root = path.resolve(parentDir);
+  if (!fs.existsSync(root)) return [];
+  return fs.readdirSync(root)
+    .filter((name) => !name.startsWith('.') && !IGNORE_DIR_NAMES.has(name))
+    .map((name) => ({ name, abs: path.join(root, name) }))
+    .filter((entry) => {
+      try {
+        return fs.statSync(entry.abs).isDirectory();
+      } catch {
+        return false;
+      }
+    })
+    .sort((a, b) => a.name.localeCompare(b.name));
+}
+
+/**
+ * 在父目录下查找已有的 SDD 包裹包（不必是独立 Git）。
+ * 优先：modules.yaml → 目录名 *-sdd-specs → openspec/changes。
+ */
+function findNestedSpecPackage(parentDir) {
+  const children = listChildDirectories(parentDir);
+  const candidates = children.filter((c) => looksLikeSpecRepo(c.abs));
+  if (candidates.length === 0) return null;
+  return (
+    candidates.find((c) => fs.existsSync(path.join(c.abs, 'modules.yaml')))
+    || candidates.find((c) => /-sdd-specs$/i.test(c.name))
+    || candidates[0]
+  );
+}
+
+/**
+ * 确保父目录下存在统一的 SDD 包裹包目录。
+ * @param {{ name?: string, initGit?: boolean }} options
+ *   initGit=true：多仓兄弟目录，包裹包本身是独立 Git 仓
+ *   initGit=false：单仓内部子目录，共用外层 Git
+ */
+function ensureSpecPackage(parentDir, options = {}) {
+  const { execFileSync } = require('child_process');
+  const root = path.resolve(parentDir);
+  const existing = findNestedSpecPackage(root);
+  if (existing) {
+    return {
+      name: existing.name,
+      abs: existing.abs,
+      created: false,
+      isGit: isGitRepo(existing.abs),
+    };
+  }
+
+  const name = options.name || deriveSpecPackageName(root);
+  const abs = path.join(root, name);
+  const existed = fs.existsSync(abs);
+  fs.mkdirSync(abs, { recursive: true });
+
+  let isGit = isGitRepo(abs);
+  if (options.initGit && !isGit) {
+    execFileSync('git', ['init'], {
+      cwd: abs,
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    isGit = true;
+  }
+
+  return { name, abs, created: !existed, isGit };
+}
+
 module.exports = {
   WORKSPACE_FILE,
   isGitRepo,
   looksLikeSpecRepo,
   listChildGitRepos,
+  listChildDirectories,
   detectWorkspaceLayout,
   parseWorkspaceYaml,
   loadWorkspaceFile,
   writeWorkspaceFile,
   findNewCodeRepos,
+  deriveSpecPackageName,
+  findNestedSpecPackage,
+  ensureSpecPackage,
 };

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

@@ -60,7 +60,7 @@ function resolveLayout(repoRoot, env = process.env) {
     return { mode: 'unlinked' };
   }
   if (sddConfig.isMonoLayout(repoRoot)) {
-    return { mode: 'mono', specPath: repoRoot };
+    return { mode: 'mono', specPath: sddConfig.resolveMonoSpecRoot(repoRoot) };
   }
 
   const context = sddConfig.resolveCodeRepoContext(repoRoot, env);
@@ -70,9 +70,14 @@ function resolveLayout(repoRoot, env = process.env) {
   if (context.code === sddConfig.CODES.SPEC_PATH_INVALID) {
     fail(context.message);
   }
-  // specPath 指回本仓：等同单仓，不能按外部 spec 校验干净度
-  if (path.resolve(context.specPath) === path.resolve(repoRoot)) {
-    return { mode: 'mono', specPath: repoRoot, context };
+  // specPath 指回本仓根：等同单仓（兼容旧平铺）；若指向仓内包裹包仍按 mono
+  const resolvedSpec = path.resolve(context.specPath);
+  const resolvedRoot = path.resolve(repoRoot);
+  if (resolvedSpec === resolvedRoot) {
+    return { mode: 'mono', specPath: sddConfig.resolveMonoSpecRoot(repoRoot), context };
+  }
+  if (resolvedSpec.startsWith(`${resolvedRoot}${path.sep}`)) {
+    return { mode: 'mono', specPath: resolvedSpec, context };
   }
   return { mode: 'multi', specPath: context.specPath, context };
 }

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

@@ -27,7 +27,8 @@ allowed-tools:
 > - ⛔ **隔离红线**：绝对禁止加载同级其他 Capability 的文档
 
 > **🖥️ 跨平台执行规则**
-> - 先确认当前终端工作目录是项目根目录；若不是，先 `cd` 到项目根目录。
+> - **写代码**：cwd 保持在 Git 根（含 `src/`）；**文档 / telemetry**：`--project` 指向 SDD 包裹包（`node skywalk-sdd/ontology/cli.cjs spec-root` 可查看）。
+> - `openspec` 命令：优先 `node skywalk-sdd/openspec-shim.cjs list`（自动 cd 到包裹包）。
 > - Telemetry 命令默认使用 `--project=.`，兼容 Windows、macOS、Linux。
 > - ${SHELL_GUIDANCE}
 > - 不要省略 `--source=opsx-command` 与 `--session-id=<会话ID>`。

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

@@ -20,7 +20,9 @@ allowed-tools:
 > **硬依赖（收尾入库）**：zip 生成后的上传依赖同级已部署的 **`opsx-kb-ingest`**。进入 §5.5 前必须先 `Read` 该技能的 `SKILL.md` 并完成其 Session 启动。入库成功后，`Read` `opsx-ontology-query/phase-3-postchange.md` 验证版本生效、AC 保留、关系完整性。缺失则提示用户重新 `kld-sdd-init`，**不要**自造另一套入库协议。
 
 > **跨平台执行规则**
-> - 先确认当前终端工作目录是项目根目录；若不是，先 `cd` 到项目根目录。
+> - **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` 查看路径。
 > - Telemetry 命令默认使用 `--project=.`，兼容 Windows、macOS、Linux。
 > - 不要裸写 Windows 反斜杠绝对路径；如必须使用绝对路径，请加引号或改成正斜杠。
 > - 不要省略 `--source=opsx-command` 和 `--session-id=<会话ID>`。

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

@@ -32,7 +32,9 @@ allowed-tools:
 
 
 > **🖥️ 跨平台执行规则**
-> - 先确认当前终端工作目录是项目根目录；若不是，先 `cd` 到项目根目录。
+> - **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` 查看路径。
 > - Telemetry 命令默认使用 `--project=.`，兼容 Windows、macOS、Linux。
 > - ${SHELL_GUIDANCE}
 > - 不要省略 `--source=opsx-command` 与 `--session-id=<会话ID>`。

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

@@ -46,7 +46,9 @@ allowed-tools:
 > - ⛔ **隔离红线**：绝对禁止跨目录读取同级其他 Capability 的 spec 或 design（Full 模式）
 
 > **🖥️ 跨平台执行规则**
-> - 先确认当前终端工作目录是项目根目录；若不是，先 `cd` 到项目根目录。
+> - **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` 查看路径。
 > - Telemetry 命令默认使用 `--project=.`，兼容 Windows、macOS、Linux。
 > - ${SHELL_GUIDANCE}
 > - 不要省略 `--source=opsx-command` 与 `--session-id=<会话ID>`。

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

@@ -16,7 +16,9 @@ allowed-tools:
 
 
 > **🖥️ 跨平台执行规则**
-> - 先确认当前终端工作目录是项目根目录；若不是，先 `cd` 到项目根目录。
+> - **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` 查看路径。
 > - Telemetry 命令默认使用 `--project=.`，兼容 Windows、macOS、Linux。
 > - ${SHELL_GUIDANCE}
 > - 不要省略 `--source=opsx-command` 与 `--session-id=<会话ID>`。

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

@@ -34,7 +34,9 @@ allowed-tools:
 > 阶段边界自检见 `./checklist.md`「阶段边界⛔」。
 
 > **🖥️ 跨平台执行规则**
-> - 先确认当前终端工作目录是项目根目录；若不是，先 `cd` 到项目根目录。
+> - **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` 查看路径。
 > - Telemetry 命令默认使用 `--project=.`，兼容 Windows、macOS、Linux。
 > - ${SHELL_GUIDANCE}
 > - 不要省略 `--source=opsx-command` 与 `--session-id=<会话ID>`。

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

@@ -19,7 +19,9 @@ allowed-tools:
 你是一个 SDD 项目规则生成与维护专家。激活本技能后，你将扫描项目事实，为已部署的 Agent 生成或审查规则文件。
 
 > **🖥️ 跨平台执行规则**
-> - 先确认当前终端工作目录是项目根目录；若不是，先 `cd` 到项目根目录。
+> - **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` 查看路径。
 > - ${SHELL_GUIDANCE}
 > - **本技能不写入 SkyWalk Telemetry**（与 `opsx-knowledge` 同属辅助技能，不走 `log.cjs start/end`）。
 

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

@@ -34,7 +34,9 @@ allowed-tools:
 > 阶段边界自检见 `./checklist.md`「阶段边界⛔」。
 
 > **🖥️ 跨平台执行规则**
-> - 先确认当前终端工作目录是项目根目录；若不是，先 `cd` 到项目根目录。
+> - **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` 查看路径。
 > - Telemetry 命令默认使用 `--project=.`，兼容 Windows、macOS、Linux。
 > - ${SHELL_GUIDANCE}
 > - 不要省略 `--source=opsx-command` 与 `--session-id=<会话ID>`。

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

@@ -47,7 +47,9 @@ allowed-tools:
 > - ⛔ **隔离红线**：绝对禁止跨目录读取同级其他 Capability 的文档（Full 模式）
 
 > **🖥️ 跨平台执行规则**
-> - 先确认当前终端工作目录是项目根目录；若不是，先 `cd` 到项目根目录。
+> - **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` 查看路径。
 > - Telemetry 命令默认使用 `--project=.`，兼容 Windows、macOS、Linux。
 > - ${SHELL_GUIDANCE}
 > - 不要省略 `--source=opsx-command` 与 `--session-id=<会话ID>`。

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

@@ -24,7 +24,9 @@ allowed-tools:
 > - 输出标准化测试报告，便于质量追踪
 
 > **🖥️ 跨平台执行规则**
-> - 先确认当前终端工作目录是项目根目录；若不是，先 `cd` 到项目根目录。
+> - **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` 查看路径。
 > - Telemetry 命令默认使用 `--project=.`，兼容 Windows、macOS、Linux。
 > - ${SHELL_GUIDANCE}
 > - 不要省略 `--source=opsx-command` 与 `--session-id=<会话ID>`。