kld-sdd 2.6.9 → 2.6.11

package/package.json

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