kld-sdd 2.6.9 → 2.6.11

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,14 +847,22 @@ 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）');
   return true;
 }
 
-function installGitHookShim(cwd, hookName, scriptPath) {
+function installGitHookShim(cwd, hookName, scriptPath, options = {}) {
   const hooksDir = path.join(cwd, '.git', 'hooks');
   if (!fs.existsSync(hooksDir)) {
     return;
@@ -872,11 +870,20 @@ function installGitHookShim(cwd, hookName, scriptPath) {
 
   const hookPath = path.join(hooksDir, hookName);
   const marker = 'KLD SDD quality gate';
+  // Git 把 commit-msg 文件路径放在 $1；--project 等额外参数必须跟在 "$@" 后面，
+  // 否则 trailer 脚本会把 --project=… 误当成 message 文件（argv[2]）。
+  const extraArgs = options.extraArgs || '';
+  const nodeLine = extraArgs
+    ? `  node "${scriptPath}" "$@" ${extraArgs}`
+    : `  node "${scriptPath}" "$@"`;
   const shim = [
     '#!/bin/sh',
     `# ${marker}`,
     `if [ -f "${scriptPath}" ]; then`,
-    `  node "${scriptPath}" "$@"`,
+    nodeLine,
+    'else',
+    `  echo "[kld-sdd] Hook 脚本不存在: ${scriptPath}" >&2`,
+    '  exit 1',
     'fi',
     '',
   ].join('\n');
@@ -884,10 +891,21 @@ function installGitHookShim(cwd, hookName, scriptPath) {
   if (fs.existsSync(hookPath)) {
     const existing = fs.readFileSync(hookPath, 'utf8');
     if (existing.includes(marker)) {
-      console.log(`   ✓ .git/hooks/${hookName} 已包含 SDD 质量门禁`);
-    } else {
-      console.log(`   ℹ️  .git/hooks/${hookName} 已存在，已保留不覆盖；可手动调用 ${scriptPath}`);
+      // 已是 SDD shim：若指向路径变化（如改为引用 spec 仓），允许覆盖升级
+      if (existing.includes(scriptPath) && (!extraArgs || existing.includes(extraArgs.trim()))) {
+        console.log(`   ✓ .git/hooks/${hookName} 已包含 SDD 质量门禁`);
+        return;
+      }
+      fs.writeFileSync(hookPath, shim, 'utf8');
+      try {
+        fs.chmodSync(hookPath, 0o755);
+      } catch {
+        // ignore
+      }
+      console.log(`   ✓ 更新 .git/hooks/${hookName} SDD 质量门禁`);
+      return;
     }
+    console.log(`   ℹ️  .git/hooks/${hookName} 已存在，已保留不覆盖；可手动调用 ${scriptPath}`);
     return;
   }
 
@@ -900,14 +918,52 @@ function installGitHookShim(cwd, hookName, scriptPath) {
   console.log(`   ✓ 安装 .git/hooks/${hookName} SDD 质量门禁`);
 }
 
+/**
+ * 确保 spec 包裹包内有 commit-msg 脚本（供代码仓 Hook 远程引用）。
+ */
+function ensureSpecCommitMsgScript(specRepoRoot, pkgPath = getPackagePath()) {
+  const specRoot = path.resolve(specRepoRoot);
+  const scriptPath = path.join(specRoot, 'skywalk-sdd', 'git-hooks', 'commit-msg-sdd-trailer.cjs');
+  if (fs.existsSync(scriptPath)) return { ok: true, scriptPath };
+
+  const src = path.join(pkgPath, 'templates', 'git-hooks', 'commit-msg-sdd-trailer.cjs');
+  if (!fs.existsSync(src)) {
+    return { ok: false, message: `commit-msg 模板缺失: ${src}` };
+  }
+  const ontologySrc = path.join(pkgPath, 'skywalk-sdd', 'ontology');
+  const ontologyDst = path.join(specRoot, 'skywalk-sdd', 'ontology');
+  if (fs.existsSync(ontologySrc) && !fs.existsSync(path.join(ontologyDst, 'change-key.cjs'))) {
+    copyDir(ontologySrc, ontologyDst);
+  }
+  fs.mkdirSync(path.dirname(scriptPath), { recursive: true });
+  fs.copyFileSync(src, scriptPath);
+  return { ok: true, scriptPath, deployed: true };
+}
+
+/**
+ * 代码仓 commit-msg：只写 .git/hooks，脚本与 ontology 一律用 spec 仓那一份。
+ */
+function installCodeRepoCommitMsgHook(codeRepoRoot, specRepoRoot, options = {}) {
+  const cwd = path.resolve(codeRepoRoot);
+  const ensured = ensureSpecCommitMsgScript(specRepoRoot, options.pkgPath || getPackagePath());
+  if (!ensured.ok) {
+    console.log(`   ⚠️  ${ensured.message}`);
+    return false;
+  }
+  installGitHookShim(cwd, 'commit-msg', ensured.scriptPath, {
+    extraArgs: `--project=${cwd}`,
+  });
+  return true;
+}
+
 /**
  * 部署 Git hooks / CI 兜底模板
  * 这些脚本只做质量门禁和 CI 补充记录，不替代 OPSX 主采集链路。
  *
  * @param {string} [targetCwd]
  * @param {{ mode?: 'full'|'commit-msg-only' }} [options]
- *   full: spec 仓（pre-commit/pre-push/commit-msg + CI）
- *   commit-msg-only: 代码仓（只装 Trailer Hook，不装 skills、不装文档门禁）
+ *   full: spec 包裹包（pre-commit/pre-push/commit-msg + CI）
+ *   commit-msg-only: 单仓 Git 根（本仓落 skywalk-sdd/git-hooks；多仓代码仓请用 installCodeRepoCommitMsgHook）
  */
 function deployQualityGateTemplates(targetCwd = process.cwd(), options = {}) {
   const pkgPath = getPackagePath();
@@ -948,12 +1004,12 @@ function deployQualityGateTemplates(targetCwd = process.cwd(), options = {}) {
 }
 
 /**
- * 代码仓轻量接入：只部署 Hook 运行所需 ontology + commit-msg，不部署 skills。
+ * 代码仓轻量接入：只写 .sdd.yaml + sdd.specPath + .git/hooks/commit-msg。
+ * 不在代码仓落 skywalk-sdd/——Hook 脚本与 ontology 引用 spec 包裹包那一份。
  */
 function attachCodeRepoLite(codeRepoRoot, specRepoRoot, options = {}) {
   const cwd = path.resolve(codeRepoRoot);
   const specRoot = path.resolve(specRepoRoot);
-  const pkgPath = options.pkgPath || getPackagePath();
   const label = path.basename(cwd);
 
   if (!workspaceLayout.isGitRepo(cwd)) {
@@ -963,16 +1019,7 @@ function attachCodeRepoLite(codeRepoRoot, specRepoRoot, options = {}) {
     return { ok: false, repo: label, message: `spec 路径不是 Git 仓库: ${specRoot}` };
   }
 
-  console.log(`🔗 轻量接入代码仓（无 skills）: ${label}`);
-
-  // Hook 依赖 ontology + git-hooks；不部署完整 telemetry/skills
-  const dataDir = path.join(cwd, 'skywalk-sdd');
-  const ontologySrc = path.join(pkgPath, 'skywalk-sdd', 'ontology');
-  const ontologyDst = path.join(dataDir, 'ontology');
-  if (fs.existsSync(ontologySrc)) {
-    copyDir(ontologySrc, ontologyDst);
-  }
-  deployQualityGateTemplates(cwd, { mode: 'commit-msg-only' });
+  console.log(`🔗 轻量接入代码仓（无 skywalk-sdd/、无 skills）: ${label}`);
 
   const remote = sddConfig.gitRemoteUrl(specRoot) || 'git@gitlab.example.com:biz/xxx-sdd-specs.git';
   const sddYamlPath = path.join(cwd, '.sdd.yaml');
@@ -998,6 +1045,9 @@ function attachCodeRepoLite(codeRepoRoot, specRepoRoot, options = {}) {
   }
   console.log(`   ✓ sdd.specPath = ${linked.path}`);
 
+  installCodeRepoCommitMsgHook(cwd, specRoot, options);
+  console.log('   ✓ commit-msg → spec 仓 skywalk-sdd/git-hooks/（代码仓不落 skywalk-sdd/）');
+
   return { ok: true, repo: label, path: cwd, specPath: linked.path };
 }
 
@@ -1065,32 +1115,190 @@ 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;
+}
+
+/**
+ * 工作区 / 单仓 Git 根的 skywalk-sdd/ 改为指向包裹包内唯一实体（符号链接）。
+ * skills 仍可用 `node skywalk-sdd/log.cjs`，实体文件只在 *-sdd-specs/skywalk-sdd/。
+ * 链接失败时回退为薄转发脚本（不复制 ontology）。
+ */
+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) {
+  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' };
+  }
+
+  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);
+      }
+    }
+  } catch (err) {
+    console.log(`   ⚠️  清理旧 skywalk-sdd/ 失败: ${err.message}`);
+    return deploySkywalkForwarders(anchor, specPackageAbs);
+  }
+
+  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 };
+  } catch (err) {
+    console.log(`   ⚠️  符号链接失败 (${err.message})，回退为转发脚本`);
+    return deploySkywalkForwarders(anchor, specPackageAbs);
+  }
+}
+
 /**
  * 检测当前项目已初始化的 AI 编辑器
  */
@@ -1121,6 +1329,8 @@ function updateGitignore() {
     '.agents/commands/personal-*',
     'skywalk-sdd/events/',
     'skywalk-sdd/state/',
+    '**/skywalk-sdd/events/',
+    '**/skywalk-sdd/state/',
     '.worktrees/'
   ];
 
@@ -1134,9 +1344,11 @@ function updateGitignore() {
 .workbuddy/commands/personal-*
 .agents/commands/personal-*
 
-# SDD Telemetry 数据（本地度量，可选提交；本体 JSON 与报告随 openspec/changes/<change>/ 提交）
+# SDD Telemetry 数据（实体在 *-sdd-specs/skywalk-sdd/；工作区可能是 symlink）
 skywalk-sdd/events/
 skywalk-sdd/state/
+**/skywalk-sdd/events/
+**/skywalk-sdd/state/
 
 # SDD Apply 隔离 worktree（本地临时目录）
 .worktrees/
@@ -1274,32 +1486,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 +1508,95 @@ 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);
+      // 工作区不复制 skywalk-sdd 实体，只链到包裹包（skills 路径仍可用）
+      linkSkywalkToSpecPackage(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 {
-      // 单仓模式（旧行为）：当前目录既是项目根
-      deployTelemetryDataDir(workspaceRoot);
-      deployQualityGateTemplates(workspaceRoot, { mode: 'full' });
-      deployModulesYaml(workspaceRoot);
-      deploySddConfigYaml(workspaceRoot);
-      if (workspaceLayout.isGitRepo(workspaceRoot)) {
-        // openspec 与代码同仓：显式声明单仓，Hook 才会写 Spec-Change
-        deployMonoSddYaml(workspaceRoot);
+      // 单仓：Git 根只放代码 + skills + Hook；SDD 内容进统一包裹子目录
+      const isGit = workspaceLayout.isGitRepo(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);
+        linkSkywalkToSpecPackage(workspaceRoot, specPackage.abs);
+
+        deployMonoSddYaml(workspaceRoot, { specPathRelative: specPackage.name });
+        // Hook 装在 Git 根；经 symlink 写入包裹包内的 git-hooks
+        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,
+        });
+        writeSddSpecRootHint(workspaceRoot, specPackage.abs);
+        linkSkywalkToSpecPackage(workspaceRoot, specPackage.abs);
         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,23 +1616,27 @@ 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`);
+    console.log('  🔗 skywalk-sdd/ → *-sdd-specs/skywalk-sdd/  # 符号链接，实体只在包裹包');
+    if (specPackage) {
+      console.log(`  📄 ${specPackage.name}/              # 统一 SDD 包裹包（独立 Git）`);
+      console.log('       modules.yaml / sdd.config.yaml / openspec / openspec-templates / skywalk-sdd');
     }
     for (const repo of layout.codeRepos) {
-      console.log(`  🔗 ${repo.name}/  ← commit-msg Hook + .sdd.yaml（无 skills）`);
+      console.log(`  🔗 ${repo.name}/  ← commit-msg Hook + .sdd.yaml（无 skywalk-sdd/、无 skills）`);
     }
     console.log();
     console.log('新代码仓加入后执行:');
     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');
+    console.log('  🔗 skywalk-sdd/ → *-sdd-specs/skywalk-sdd/  # 符号链接，实体只在包裹包');
   }
   if (selectedTools.includes('kunlunzhima')) {
     console.log('  📎 .kunlunzhima/commands/opsx/    # KunlunZhima OPSX command bridge（11 个）');
@@ -1397,11 +1648,6 @@ async function main() {
   if (selectedTools.includes('claude')) {
     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();
   
   // 统一的 skill 格式说明
@@ -1420,8 +1666,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 +1686,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 +1710,10 @@ module.exports = {
   deploySddConfigYaml,
   deployDotSddYaml,
   deployMonoSddYaml,
+  populateSpecPackage,
+  writeSddSpecRootHint,
+  linkSkywalkToSpecPackage,
+  deploySkywalkForwarders,
   deployQualityGateTemplates,
   deployTelemetryDataDir,
   attachCodeRepoLite,