kld-sdd 2.7.8 → 2.8.0

package/lib/init.js

@@ -9,6 +9,8 @@
  * 5. 更新 .gitignore
  */
 
+'use strict';
+
 const fs = require('fs');
 const path = require('path');
 const { execSync } = require('child_process');
@@ -16,7 +18,6 @@ const readline = require('readline');
 const os = require('os');
 const {
   SKILLS_BUNDLE_NAME,
-  OPSX_SKILL_DIRS,
   OPSX_SKILL_METADATA,
   renderTemplate,
   validateRenderedContent,
@@ -28,8 +29,20 @@ const {
   BRIDGE_MARKER,
 } = require('./command-bridge');
 const { deployCodebuddyHookPack } = require('./deploy-codebuddy-hooks');
+const { PROVIDERS, computeMergedSettings } = require('./settings-merge');
 const workspaceLayout = require('./workspace-layout');
+const maintenance = require('./maintenance');
 const sddConfig = require('../skywalk-sdd/ontology/sdd-config.cjs');
+// spec 判据与候选枚举的唯一入口（tier 分级 + 排序）
+const specDetect = require('../skywalk-sdd/ontology/spec-detect.cjs');
+// spec 候选单选交互（init / uninstall / sync-repos 共用）
+const { selectSpecRoot } = require('./spec-choice');
+const {
+  STRATEGY,
+  ACTION,
+  deployFile,
+  deployDir,
+} = require('./deploy-strategy');
 
 let rl = null;
 
@@ -63,14 +76,19 @@ function ask(question) {
 }
 
 /**
- * 输出详细度判定（惰性读取，便于测试在运行期注入）
- * 触发条件：argv 含 --verbose，或 KLD_SDD_VERBOSE 为 1/true（大小写不敏感）
- * 注意：-v 已被 --version 占用，不复用
+ * 输出详细度开关。
+ *
+ * 判定（--verbose / KLD_SDD_VERBOSE）属 CLI 输入层职责，由 bin/kld-sdd-init.js 解析后
+ * 通过 setVerbose 注入；lib 不读取 process.argv。
  */
+let verboseEnabled = false;
+
+function setVerbose(value) {
+  verboseEnabled = Boolean(value);
+}
+
 function isVerbose() {
-  if (process.argv.includes('--verbose')) return true;
-  const env = process.env.KLD_SDD_VERBOSE;
-  return typeof env === 'string' && /^(1|true)$/i.test(env);
+  return verboseEnabled;
 }
 
 /**
@@ -82,57 +100,6 @@ function vlog(...args) {
   }
 }
 
-/**
- * 从命令行参数读取指定编辑器
- * 支持：--tool codex、--tool=codex、--tool cursor,codex、--tool all
- */
-function parseSelectedTools(args) {
-  const toolArgIndex = args.findIndex(arg => arg === '--tool' || arg.startsWith('--tool='));
-  if (toolArgIndex === -1) return null;
-
-  const rawValue = args[toolArgIndex] === '--tool'
-    ? args[toolArgIndex + 1]
-    : args[toolArgIndex].slice('--tool='.length);
-
-  if (!rawValue) {
-    throw new Error('缺少 --tool 参数值，请指定编辑器名称');
-  }
-
-  const normalized = rawValue.trim().toLowerCase();
-  if (normalized === 'all' || normalized === '全部') {
-    return Object.keys(TOOL_CONFIGS);
-  }
-
-  const selected = normalized.split(',').map(item => item.trim()).filter(Boolean);
-  const invalid = selected.filter(tool => !TOOL_CONFIGS[tool]);
-  if (invalid.length > 0) {
-    throw new Error(`不支持的编辑器: ${invalid.join(', ')}。可用值: ${Object.keys(TOOL_CONFIGS).join(', ')}, all`);
-  }
-
-  return selected;
-}
-
-/**
- * 从命令行参数读取自定义 spec 目录
- * 支持：--spec-path erp-sdd-specs、--spec-path=./specs、--spec-path=/abs/path/specs
- * 返回相对/绝对路径字符串，未指定时返回 null。
- */
-function parseSpecPathArg(args) {
-  const index = args.findIndex(
-    (arg) => arg === '--spec-path' || arg.startsWith('--spec-path='),
-  );
-  if (index === -1) return null;
-
-  const rawValue = args[index] === '--spec-path'
-    ? args[index + 1]
-    : args[index].slice('--spec-path='.length);
-
-  if (!rawValue || rawValue.startsWith('--')) {
-    throw new Error('缺少 --spec-path 参数值，请指定 spec 仓库目录（相对或绝对路径）');
-  }
-  return rawValue.trim();
-}
-
 /**
  * 将 --spec-path 解析为 { name, abs }。
  * - 绝对路径：直接使用
@@ -156,82 +123,76 @@ function resolveSpecPathOption(specPathArg, workspaceRoot) {
 }
 
 /**
- * 交互提示前的 spec 目录兜底检测：
- * detectWorkspaceLayout 的 specRepo 只覆盖「子目录是 Git 仓」的场景，
- * 这里补充两种常见形态，避免已有 spec 产物被漏检：
- * 1. .sdd-spec-root 指针文件（历史初始化产物）
- * 2. 非 Git 子目录的 spec 产物（findNestedSpecPackage 不要求子目录是 Git 仓）
+ * 枚举交互提示用的 spec 目录候选（与卸载共用同一套识别）。
+ *
+ * 委托 `spec-detect.detectSpecCandidatesWithGit` —— 判据与「读 git config」
+ * 均在全仓唯一入口内完成，本函数只是 init 侧的命名别名。
+ * 历史上 init 与 uninstall 各写一份相同实现，是「一处改、一处漏」的来源。
+ *
+ * @returns {Array<{abs: string, name: string, source: string, tier: number, evidence: string[]}>}
  */
-function detectSpecCandidateForPrompt(workspaceRoot) {
-  try {
-    const hintPath = path.join(workspaceRoot, '.sdd-spec-root');
-    if (fs.existsSync(hintPath)) {
-      const rel = String(fs.readFileSync(hintPath, 'utf8') || '')
-        .trim()
-        .split(/\r?\n/)[0]
-        .trim();
-      if (rel) {
-        const abs = path.resolve(workspaceRoot, rel);
-        if (fs.existsSync(abs) && workspaceLayout.looksLikeSpecRepo(abs)) {
-          return { name: path.basename(abs), abs };
-        }
-      }
-    }
-  } catch { /* 指针读取异常时继续兜底 */ }
-
-  const nested = workspaceLayout.findNestedSpecPackage(workspaceRoot);
-  return nested ? { name: nested.name, abs: nested.abs } : null;
+function listSpecCandidatesForInit(workspaceRoot) {
+  return specDetect.detectSpecCandidatesWithGit(workspaceRoot);
 }
 
 /**
  * 交互式确定 spec 包裹包目录（--spec-path 未显式指定时）：
- * 1. 自动检测到已有 spec 产物（modules.yaml / openspec/changes / *-sdd-specs）→ 提醒用户确认是否使用
- * 2. 未检测到 → 要求用户输入相对路径指定（回车则用默认推导名 <当前目录名>-sdd-specs）
+ * 1. 检测到候选 → 单选确认（0 个 / 1 个 / N 个 的行为见 lib/spec-choice.js）
+ * 2. 未检测到、或用户拒绝候选 → 要求输入相对路径
+ *    （回车则用默认推导名 `<当前目录名>-sdd-specs`）
  *
  * 非交互环境（CI / 管道 / --tool 自动化）不询问，保持原自动推导行为。
  *
- * @param {object} [options] - 测试注入：{ askFn, interactive }
+ * 单选交互委托 `lib/spec-choice.js#selectSpecRoot` —— 与 uninstall /
+ * sync-repos 共用同一实现。历史上这里另写了一套「确认检测目录」逻辑，
+ * 导致 init 只能确认单个候选（多候选时静默取第一个），与另两个场景不一致。
+ *
+ * @param {Array<{abs: string, name: string, source: string, tier?: number}>} candidates
+ *        spec 候选集合（由 spec-detect 枚举，已按 tier 排序）；空数组表示未检测到
+ * @param {object} [options] - 测试/调用方注入：{ askFn, interactive, hasToolArg, isTTY }
+ *   - hasToolArg：命令行是否显式指定了编辑器（自动化场景，不询问）。由 bin 层解析后注入，
+ *     本函数不读取 process.argv。
+ *   - isTTY：覆盖 TTY 判定，便于测试
  * @returns {{ name: string, abs: string, rel: string, display: string } | null}
  *          null 表示未选择自定义目录，走默认推导逻辑
  */
-async function promptSpecPath(workspaceRoot, detectedSpec, options = {}) {
+async function promptSpecPath(workspaceRoot, candidates, options = {}) {
   const askUser = options.askFn || ask;
   let interactive = options.interactive;
   if (typeof interactive !== 'boolean') {
     // 非交互环境：无 TTY 或显式给了 --tool（自动化场景），不询问
-    const isTTY = process.stdin && process.stdin.isTTY;
-    const hasToolArg = process.argv.slice(2).some((arg) => arg === '--tool' || arg.startsWith('--tool='));
-    interactive = Boolean(isTTY) && !hasToolArg;
+    const isTTY = options.isTTY !== undefined
+      ? options.isTTY
+      : Boolean(process.stdin && process.stdin.isTTY);
+    interactive = Boolean(isTTY) && !options.hasToolArg;
   }
   if (!interactive) return null;
 
-  if (detectedSpec) {
-    console.log(`\n🔍 检测到已有 spec 目录（命名约定或完整结构标记）: ${detectedSpec.name}`);
-    console.log(`   位置: ${detectedSpec.abs}`);
-    while (true) {
-      const answer = await askUser(`是否使用该 spec 仓库？(Y=使用 / n=重新指定路径，默认 Y): `);
-      const normalized = (answer || '').trim().toLowerCase();
-      if (!normalized || normalized === 'y' || normalized === 'yes') {
-        const relPosix = path.relative(workspaceRoot, detectedSpec.abs).replace(/\\/g, '/') || detectedSpec.name;
-        return { name: relPosix, abs: detectedSpec.abs, rel: relPosix, display: detectedSpec.name };
-      }
-      if (normalized === 'n' || normalized === 'no') break;
-      console.log(`❌ 无效输入 "${answer}"，请输入 Y 或 n`);
+  const list = Array.isArray(candidates) ? candidates : (candidates ? [candidates] : []);
+  const hasCandidate = list.length > 0;
+
+  if (hasCandidate) {
+    const chosen = await selectSpecRoot({ ask: askUser }, list, { actionLabel: '使用' });
+    if (chosen) {
+      const name = path.basename(chosen);
+      const relPosix = path.relative(workspaceRoot, chosen).replace(/\\/g, '/') || name;
+      return { name: relPosix, abs: chosen, rel: relPosix, display: name };
     }
+    // 取消（多候选选 0 / 唯一候选拒绝）→ 转入手动输入路径
   } else {
     console.log('\n🔍 未检测到已有 spec 目录（目录名 *-sdd-specs，或 modules.yaml + sdd.config.yaml + openspec/changes + openspec/specs/overview.md 齐全）');
   }
 
-  // 未确认使用检测目录（或未检测到）：要求输入相对路径
+  // 未确认使用候选（或未检测到）：要求输入相对路径
   const defaultName = workspaceLayout.deriveSpecPackageName(workspaceRoot);
   while (true) {
     const input = await askUser(`请输入 spec 目录的相对路径（直接回车使用默认 ${defaultName}）: `);
     const trimmed = (input || '').trim();
     if (!trimmed) {
       // 回车 = 使用默认推导名。
-      // 若用户刚用 n 拒绝了检测到的目录，必须显式返回默认目录：
+      // 若此前拒绝了检测到的候选，必须显式返回默认目录：
       // 返回 null 会让主流程走自动探测，重新命中刚被拒绝的目录。
-      if (detectedSpec) {
+      if (hasCandidate) {
         return resolveSpecPathOption(defaultName, workspaceRoot);
       }
       return null; // 未检测到场景：走主流程默认创建
@@ -245,49 +206,6 @@ async function promptSpecPath(workspaceRoot, detectedSpec, options = {}) {
   }
 }
 
-/**
- * 让用户选择编辑器
- * 无效输入时重新询问，不允许默认
- */
-async function selectEditor() {
-  const mapping = {
-    '1': ['cursor'],
-    '2': ['claude'],
-    '3': ['codebuddy'],
-    '4': ['qoder'],
-    '5': ['opencode'],
-    '6': ['kunlunzhima'],
-    '7': ['workbuddy'],
-    '8': ['codex'],
-    '9': ['cursor', 'claude', 'codebuddy', 'qoder', 'opencode', 'kunlunzhima', 'workbuddy', 'codex']
-  };
-
-  while (true) {
-    console.log('\n请选择您使用的 AI 编辑器:');
-    console.log('  1. Cursor');
-    console.log('  2. Claude Code');
-    console.log('  3. CodeBuddy');
-    console.log('  4. Qoder');
-    console.log('  5. OpenCode');
-    console.log('  6. KunlunZhima');
-    console.log('  7. WorkBuddy');
-    console.log('  8. Codex');
-    console.log('  9. 全部（为所有编辑器生成 skills）');
-    
-    const answer = await ask('请输入选项 (1-9): ');
-    const selected = mapping[answer];
-    
-    if (!selected) {
-      console.log(`❌ 无效选项 "${answer}"，请输入 1-9 之间的数字\n`);
-      continue;  // 重新循环询问
-    }
-    
-    const names = selected.map(k => TOOL_CONFIGS[k].name).join(', ');
-    console.log(`✓ 已选择: ${names}\n`);
-    return selected;
-  }
-}
-
 /**
  * 检查命令是否可用
  */
@@ -319,14 +237,6 @@ function getPackagePath() {
   }
 }
 
-/**
- * 获取模版路径
- */
-function getTemplatePath() {
-  const pkgPath = getPackagePath();
-  return path.join(pkgPath, 'templates', 'openspec');
-}
-
 /**
  * 自动安装 openspec
  */
@@ -420,48 +330,19 @@ async function runOpenspecInit(selectedTools = []) {
 }
 
 /**
- * 递归复制目录
+ * 递归复制并渲染模板目录（工具产物 → OVERWRITE）
  */
-function copyDir(source, target) {
-  if (!fs.existsSync(target)) {
-    fs.mkdirSync(target, { recursive: true });
-  }
-  
-  const files = fs.readdirSync(source);
-  for (const file of files) {
-    const srcPath = path.join(source, file);
-    const tgtPath = path.join(target, file);
-    
-    const stat = fs.statSync(srcPath);
-    if (stat.isDirectory()) {
-      copyDir(srcPath, tgtPath);
-    } else {
-      fs.copyFileSync(srcPath, tgtPath);
-    }
-  }
-}
-
 function copyDirRendered(source, target, config, toolKey) {
   const profile = getToolProfile(toolKey);
-
-  if (!fs.existsSync(target)) {
-    fs.mkdirSync(target, { recursive: true });
-  }
-
-  const files = fs.readdirSync(source);
-  for (const file of files) {
-    const srcPath = path.join(source, file);
-    const tgtPath = path.join(target, file);
-
-    const stat = fs.statSync(srcPath);
-    if (stat.isDirectory()) {
-      copyDirRendered(srcPath, tgtPath, config, toolKey);
-    } else {
+  return deployDir(source, target, {
+    strategy: STRATEGY.OVERWRITE,
+    render: (srcPath, tgtPath) => {
+      if (path.basename(srcPath) === 'config.json' && fs.existsSync(tgtPath)) return fs.readFileSync(tgtPath, 'utf8');
       const rendered = renderTemplate(fs.readFileSync(srcPath, 'utf8'), config, toolKey, profile);
       validateRenderedContent(rendered, profile, tgtPath);
-      fs.writeFileSync(tgtPath, rendered, 'utf8');
-    }
-  }
+      return rendered;
+    },
+  });
 }
 
 /** OpenSpec init 生成的 4 个官方 slash command（KLD-SDD 使用 skills，不保留 command） */
@@ -715,37 +596,10 @@ function deployProfileArtifacts(selectedTools = Object.keys(TOOL_CONFIGS), cwd =
 /**
  * 部署 Claude Code Hook Pack（可选增强）
  * Hook 只调用 skywalk-sdd/log.cjs，不写私有日志，不替代 OPSX 模板采集。
+ *
+ * SDD 受管 hook 的识别/合并/摘除统一由 lib/settings-merge.js 提供，
+ * 保证安装与卸载共用同一套归属判定（装得进去的一定摘得掉）。
  */
-function hookCommandText(hook) {
-  const args = Array.isArray(hook.args) ? hook.args : [];
-  return [hook.command, ...args].filter(Boolean).join(' ').replace(/\s+/g, ' ').trim();
-}
-
-function isSddClaudeHook(hook) {
-  const text = hookCommandText(hook);
-  return /(?:^|\s|["'])\.claude[\\/]+hooks[\\/]+sdd-(?:prompt|pre-tool|post-tool|stop|apply-gate|apply-test-gate|skill-apply-gate)\.(?:cjs|js)(?=$|\s|["'])/i.test(text) ||
-    /(?:^|\s|["'])\$\{CLAUDE_PROJECT_DIR\}[\\/]+\.claude[\\/]+hooks[\\/]+sdd-(?:prompt|pre-tool|post-tool|stop|apply-gate|apply-test-gate|skill-apply-gate)\.(?:cjs|js)(?=$|\s|["'])/i.test(text);
-}
-
-function sameHookCommand(left, right) {
-  return hookCommandText(left) === hookCommandText(right) &&
-    String(left.type || '') === String(right.type || '');
-}
-
-function removeManagedSddHooks(entries) {
-  return entries
-    .map(entry => {
-      if (!Array.isArray(entry.hooks)) {
-        return entry;
-      }
-      return {
-        ...entry,
-        hooks: entry.hooks.filter(hook => !isSddClaudeHook(hook)),
-      };
-    })
-    .filter(entry => !Array.isArray(entry.hooks) || entry.hooks.length > 0);
-}
-
 function deployClaudeHookPack(selectedTools = Object.keys(TOOL_CONFIGS)) {
   if (!selectedTools.includes('claude')) {
     return true;
@@ -770,41 +624,45 @@ function deployClaudeHookPack(selectedTools = Object.keys(TOOL_CONFIGS)) {
     fs.mkdirSync(targetHookDir, { recursive: true });
   }
 
-  copyDir(hookSourceDir, targetHookDir);
+  deployDir(hookSourceDir, targetHookDir, { strategy: STRATEGY.OVERWRITE });
   console.log('   ✓ 部署 .claude/hooks/sdd-*.cjs');
 
   const targetSettingsPath = path.join(claudeDir, 'settings.json');
-  const templateSettings = JSON.parse(fs.readFileSync(settingsTemplatePath, 'utf8'));
-  let existingSettings = {};
-  if (fs.existsSync(targetSettingsPath)) {
-    try {
-      existingSettings = JSON.parse(fs.readFileSync(targetSettingsPath, 'utf8'));
-    } catch {
-      const backupPath = `${targetSettingsPath}.backup`;
-      fs.copyFileSync(targetSettingsPath, backupPath);
-      console.log(`   ℹ️  settings.json 不是合法 JSON，已备份到 ${backupPath}`);
-      existingSettings = {};
-    }
-  }
+  // 结构化配置 → MERGE：保留用户已有字段，只剔除并重装 SDD 受管 hook，幂等
+  const mergeResult = deployFile(settingsTemplatePath, targetSettingsPath, {
+    strategy: STRATEGY.MERGE,
+    label: 'settings.json',
+    mergeFn: ({ readSource, readTarget }) => {
+      const templateSettings = JSON.parse(readSource());
+      const rawExisting = readTarget();
+      // 非法 JSON：备份后按空配置重建，避免覆盖用户其它配置时无迹可循
+      if (rawExisting !== null) {
+        try {
+          JSON.parse(rawExisting);
+        } catch {
+          const backupPath = `${targetSettingsPath}.backup`;
+          fs.copyFileSync(targetSettingsPath, backupPath);
+          console.log(`   ℹ️  settings.json 不是合法 JSON，已备份到 ${backupPath} 后重建`);
+        }
+      }
 
-  existingSettings.hooks = existingSettings.hooks || {};
-  for (const [eventName, entries] of Object.entries(templateSettings.hooks || {})) {
-    existingSettings.hooks[eventName] = removeManagedSddHooks(existingSettings.hooks[eventName] || []);
-    for (const entry of entries) {
-      const templateHooks = entry.hooks || [];
-      const exists = existingSettings.hooks[eventName].some(existingEntry => {
-        const existingHooks = existingEntry.hooks || [];
-        return templateHooks.every(templateHook => {
-          return existingHooks.some(existingHook => sameHookCommand(existingHook, templateHook));
-        });
-      });
-      if (!exists) {
-        existingSettings.hooks[eventName].push(entry);
+      const computed = computeMergedSettings(rawExisting, templateSettings, PROVIDERS.CLAUDE);
+      if (!computed.ok) {
+        return { ok: false, error: `${computed.error}: ${targetSettingsPath}` };
       }
-    }
-  }
 
-  fs.writeFileSync(targetSettingsPath, JSON.stringify(existingSettings, null, 2) + '\n', 'utf8');
+      fs.writeFileSync(targetSettingsPath, JSON.stringify(computed.merged, null, 2) + '\n', 'utf8');
+      return { ok: true, action: ACTION.MERGED };
+    },
+  });
+
+  if (!mergeResult.ok) {
+    console.log(`   ⚠️  合并 .claude/settings.json 失败: ${mergeResult.message}`);
+    return false;
+  }
+  if (mergeResult.message) {
+    console.log(`   ℹ️  ${mergeResult.message}`);
+  }
   console.log('   ✓ 合并 .claude/settings.json hooks 配置');
   console.log('✅ Claude Code SDD Hook Pack 已就绪（可选增强，核心采集仍由 OPSX skills 完成）');
   return true;
@@ -855,27 +713,32 @@ function cleanupNativeOpenspecSkills(selectedTools = Object.keys(TOOL_CONFIGS))
 
 /**
  * 复制标准文档模版到项目（openspec-templates/）
+ *
+ * 定位：**只读模板**。skills 强制以它作为文档骨架（opsx-propose §4「不得使用
+ * openspec instructions 返回的简化 template」），因此每次 init 全量覆盖更新。
+ * 项目若需自定义文档结构，应改 skill 或另建文件，不要就地修改本目录。
  */
 function copyTemplatesToProject(cwd = process.cwd()) {
   console.log('📄 正在复制标准文档模版到项目...');
-  
+
   const pkgPath = getPackagePath();
   const templatePath = path.join(pkgPath, 'templates', 'openspec');
   const targetDir = path.join(cwd, 'openspec-templates');
-  
+
   if (!fs.existsSync(templatePath)) {
     console.log(`⚠️  模版源目录不存在: ${templatePath}`);
     return false;
   }
-  
-  if (!fs.existsSync(targetDir)) {
-    fs.mkdirSync(targetDir, { recursive: true });
-  }
-  
-  copyDir(templatePath, targetDir);
+
+  // 只读模板 → OVERWRITE：每次覆盖更新，保证文档骨架与当前 skills 版本一致
+  deployDir(templatePath, targetDir, {
+    strategy: STRATEGY.OVERWRITE,
+    label: 'openspec-templates',
+  });
 
   const files = fs.readdirSync(targetDir);
   console.log(`✅ 标准文档模版已复制到: ${targetDir}（${files.length} 个文件）`);
+  vlog('   ℹ️  只读模板：每次 init 全量覆盖更新，请勿就地修改本目录');
   vlog('   包含文件:');
   files.forEach(file => {
     vlog(`     - ${file}`);
@@ -886,45 +749,38 @@ function copyTemplatesToProject(cwd = process.cwd()) {
 
 /**
  * 初始化全局 overview.md 到 openspec/specs/ 目录
- * overview.md 是全局架构约束，所有 Capability 的设计都必须遵守
+ *
+ * overview.md 是全局架构约束，也是**用户产物**：由项目团队按 opsx-propose §3.5
+ * 的引导填充（技术栈 / 数据字典 / 接口规范 / 错误码），AI 在 design / task 阶段读取。
+ * 因此首次创建模板，之后**绝不覆盖**——否则一次重跑就会清空已填充的全局契约。
  */
 function initGlobalOverview(cwd = process.cwd()) {
   console.log('🌐 正在初始化全局架构约束 (overview.md)...');
-  
+
   const pkgPath = getPackagePath();
   const overviewSource = path.join(pkgPath, 'templates', 'openspec', 'overview.md');
   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');
-    
-    if (existingContent === newContent) {
-      console.log('   ✓ overview.md 已是最新版本，跳过');
-      return true;
-    }
-    
-    const backupFile = path.join(targetDir, 'overview.md.backup');
-    fs.copyFileSync(targetFile, backupFile);
-    console.log(`   ℹ️  已备份现有 overview.md 到 ${backupFile}`);
+
+  const result = deployFile(overviewSource, targetFile, {
+    strategy: STRATEGY.SKIP_IF_EXISTS,
+    label: 'overview.md',
+  });
+
+  if (result.action === ACTION.SKIPPED) {
+    console.log('   ✓ overview.md 已存在（用户产物），保留不覆盖');
+    return true;
   }
-  
-  fs.copyFileSync(overviewSource, targetFile);
-  
+
   console.log(`✅ 全局架构约束已初始化: ${targetFile}`);
   console.log('   ℹ️  此文件定义了全局数据字典、接口规范、共享实体等约束');
   console.log('   ℹ️  执行 opsx-design 或 opsx-task 时会自动读取此文件');
-  
+
   return true;
 }
 
@@ -943,15 +799,43 @@ function deploySddGuideManual(cwd = process.cwd(), pkgPath = getPackagePath()) {
     return false;
   }
 
-  if (!fs.existsSync(targetDir)) {
-    fs.mkdirSync(targetDir, { recursive: true });
-  }
-
-  fs.copyFileSync(source, targetFile);
+  deployFile(source, targetFile, {
+    strategy: STRATEGY.OVERWRITE,
+    label: 'kld-sdd操作手册.html',
+  });
   console.log(`✅ SDD 操作手册已部署: openspec/kld-sdd操作手册.html`);
   return true;
 }
 
+/**
+ * 部署 skywalk-sdd/ 下的单个运行时模块（工具产物 → OVERWRITE）。
+ *
+ * 统一「源存在则覆盖部署并计数、缺失则告警」这一重复模式，
+ * 避免每个模块各写一遍 existsSync + copyFileSync。
+ *
+ * @param {string} src 源文件绝对路径
+ * @param {string} dst 目标文件绝对路径
+ * @param {string} desc 日志用描述（verbose 下输出）
+ * @param {string} [missingHint] 源缺失时的告警文案
+ * @returns {boolean} 是否成功部署
+ */
+function deployRuntimeModule(src, dst, desc, missingHint) {
+  if (!fs.existsSync(src)) {
+    console.log(`   ⚠️  ${missingHint || `${desc} 源文件缺失`}: ${src}`);
+    return false;
+  }
+  const result = deployFile(src, dst, {
+    strategy: STRATEGY.OVERWRITE,
+    label: path.basename(dst),
+  });
+  if (!result.ok) {
+    console.log(`   ⚠️  部署 ${desc} 失败: ${result.message}`);
+    return false;
+  }
+  vlog(`   ✓ 部署 ${desc}`);
+  return true;
+}
+
 /**
  * 部署 SDD Telemetry 数据目录
  * 创建本地数据目录用于存储事件和活跃状态（最终报告落 openspec/changes/<change>/reports/，不再写 skywalk-sdd/reports/）
@@ -984,33 +868,21 @@ function deployTelemetryDataDir(targetCwd = process.cwd()) {
   // 部署项目内 Telemetry CLI（不依赖 npm 发布）
   const telemetrySrc = path.join(pkgPath, 'skywalk-sdd', 'index.cjs');
   const telemetryDst = path.join(dataDir, 'log.cjs');
-  if (fs.existsSync(telemetrySrc)) {
-    fs.copyFileSync(telemetrySrc, telemetryDst);
+  if (deployRuntimeModule(telemetrySrc, telemetryDst, 'skywalk-sdd/log.cjs（本地 Telemetry CLI）', 'Telemetry CLI 源文件缺失')) {
     deployedModules += 1;
-    vlog('   ✓ 部署 skywalk-sdd/log.cjs（本地 Telemetry CLI）');
-  } else {
-    console.log(`   ⚠️  Telemetry CLI 源文件缺失: ${telemetrySrc}`);
   }
 
   const metricsV3Src = path.join(pkgPath, 'skywalk-sdd', 'metrics-v3.cjs');
   const metricsV3Dst = path.join(dataDir, 'metrics-v3.cjs');
-  if (fs.existsSync(metricsV3Src)) {
-    fs.copyFileSync(metricsV3Src, metricsV3Dst);
+  if (deployRuntimeModule(metricsV3Src, metricsV3Dst, 'skywalk-sdd/metrics-v3.cjs（V3 指标运行时）', 'V3 指标模块源文件缺失（report/metrics 可能无法加载 metrics-v3）')) {
     deployedModules += 1;
-    vlog('   ✓ 部署 skywalk-sdd/metrics-v3.cjs（V3 指标运行时）');
-  } else {
-    console.log(`   ⚠️  V3 指标模块源文件缺失: ${metricsV3Src}（report/metrics 可能无法加载 metrics-v3）`);
   }
 
   // 部署 spec-root.cjs（替代脆弱的 $(cat .sdd-spec-root)，CWD 无关）
   const specRootSrc = path.join(pkgPath, 'skywalk-sdd', 'spec-root.cjs');
   const specRootDst = path.join(dataDir, 'spec-root.cjs');
-  if (fs.existsSync(specRootSrc)) {
-    fs.copyFileSync(specRootSrc, specRootDst);
+  if (deployRuntimeModule(specRootSrc, specRootDst, 'skywalk-sdd/spec-root.cjs（CWD 无关的 spec 根路径解析器）', 'spec-root.cjs 源文件缺失，$(cat .sdd-spec-root) 模式可能受影响')) {
     deployedModules += 1;
-    vlog('   ✓ 部署 skywalk-sdd/spec-root.cjs（CWD 无关的 spec 根路径解析器）');
-  } else {
-    console.log('   ⚠️  spec-root.cjs 源文件缺失，$(cat .sdd-spec-root) 模式可能受影响');
   }
 
   // 部署 lib/shared.cjs（共用工具模块：parseArgs/readJson/atomicWrite/HTTP/specRoot/KB状态）
@@ -1018,14 +890,17 @@ function deployTelemetryDataDir(targetCwd = process.cwd()) {
   if (!fs.existsSync(sharedLibDir)) {
     fs.mkdirSync(sharedLibDir, { recursive: true });
   }
+  for (const name of ['test-execution.cjs', 'check-review.cjs']) {
+    const src = path.join(pkgPath, 'skywalk-sdd', 'lib', name);
+    if (!fs.existsSync(src)) throw new Error(`E_INIT_MISSING_CRITICAL: lib/${name} 源文件缺失`);
+    fs.copyFileSync(src, path.join(sharedLibDir, name));
+    deployedModules += 1;
+    vlog(`   ✓ 部署 skywalk-sdd/lib/${name}`);
+  }
   const sharedSrc = path.join(pkgPath, 'skywalk-sdd', 'lib', 'shared.cjs');
   const sharedDst = path.join(sharedLibDir, 'shared.cjs');
-  if (fs.existsSync(sharedSrc)) {
-    fs.copyFileSync(sharedSrc, sharedDst);
+  if (deployRuntimeModule(sharedSrc, sharedDst, 'skywalk-sdd/lib/shared.cjs（共用工具：parseArgs/JSON/BOM/HTTP/specRoot/KB）', 'lib/shared.cjs 源文件缺失，多个脚本将缺少共用工具依赖')) {
     deployedModules += 1;
-    vlog('   ✓ 部署 skywalk-sdd/lib/shared.cjs（共用工具：parseArgs/JSON/BOM/HTTP/specRoot/KB）');
-  } else {
-    console.log('   ⚠️  lib/shared.cjs 源文件缺失，多个脚本将缺少共用工具依赖');
   }
 
   // kld-fixback: 部署使用统计上报模块（usage-contract/usage-reporter/user-config/git-identity）
@@ -1042,40 +917,33 @@ function deployTelemetryDataDir(targetCwd = process.cwd()) {
   for (const mod of usageModules) {
     const src = path.join(pkgPath, 'skywalk-sdd', 'lib', mod.src);
     const dst = path.join(sharedLibDir, mod.src);
-    if (fs.existsSync(src)) {
-      fs.copyFileSync(src, dst);
+    if (deployRuntimeModule(src, dst, `skywalk-sdd/lib/${mod.src}（${mod.desc}）`, `${mod.src} 源文件缺失，使用统计上报将不可用`)) {
       deployedModules += 1;
-      vlog(`   ✓ 部署 skywalk-sdd/lib/${mod.src}（${mod.desc}）`);
-    } else {
-      console.log(`   ⚠️  ${mod.src} 源文件缺失，使用统计上报将不可用`);
     }
   }
 
   // 部署 scale-thresholds.json（Simple/Full 模式判定阈值，opsx-propose §6.8 自动规模判定依赖）
   const thresholdsSrc = path.join(pkgPath, 'lib', 'scale-thresholds.json');
   const thresholdsDst = path.join(sharedLibDir, 'scale-thresholds.json');
-  if (fs.existsSync(thresholdsSrc)) {
-    fs.copyFileSync(thresholdsSrc, thresholdsDst);
+  if (deployRuntimeModule(thresholdsSrc, thresholdsDst, 'skywalk-sdd/lib/scale-thresholds.json（Simple/Full 判定阈值）', 'scale-thresholds.json 源文件缺失，propose 自动规模判定将使用内置默认值')) {
     deployedModules += 1;
-    vlog('   ✓ 部署 skywalk-sdd/lib/scale-thresholds.json（Simple/Full 判定阈值）');
-  } else {
-    console.log('   ⚠️  scale-thresholds.json 源文件缺失，propose 自动规模判定将使用内置默认值');
   }
 
+  // 运行时身份：内容由生成器产出（版本号写死），升级时必须重写以反映当前 kld-sdd 版本
   const packageVersion = require(path.join(pkgPath, 'package.json')).version;
   const runtimeMetadataDst = path.join(dataDir, 'runtime-metadata.cjs');
-  fs.writeFileSync(
-    runtimeMetadataDst,
-    `'use strict';\nmodule.exports = { resolveRuntimeMetadata() { return { version: '${packageVersion}', producer: 'kld-sdd@${packageVersion}' }; } };\n`,
-    'utf8',
-  );
+  deployFile(null, runtimeMetadataDst, {
+    strategy: STRATEGY.GENERATE,
+    label: 'runtime-metadata.cjs',
+    generate: () => `'use strict';\nmodule.exports = { resolveRuntimeMetadata() { return { version: '${packageVersion}', producer: 'kld-sdd@${packageVersion}' }; } };\n`,
+  });
   deployedModules += 1;
   vlog(`   ✓ 部署 kld-sdd 运行时身份（${packageVersion}）`);
 
   const reportingSrc = path.join(pkgPath, 'skywalk-sdd', 'reporting');
   const reportingDst = path.join(dataDir, 'reporting');
   if (fs.existsSync(reportingSrc)) {
-    copyDir(reportingSrc, reportingDst);
+    deployDir(reportingSrc, reportingDst, { strategy: STRATEGY.OVERWRITE });
     deployedModules += 1;
     vlog('   ✓ 部署 skywalk-sdd/reporting/（V3 单次变更报告）');
   } else {
@@ -1084,18 +952,14 @@ function deployTelemetryDataDir(targetCwd = process.cwd()) {
 
   const contextClientSrc = path.join(pkgPath, 'skywalk-sdd', 'context-client.cjs');
   const contextClientDst = path.join(dataDir, 'context-client.cjs');
-  if (fs.existsSync(contextClientSrc)) {
-    fs.copyFileSync(contextClientSrc, contextClientDst);
+  if (deployRuntimeModule(contextClientSrc, contextClientDst, 'skywalk-sdd/context-client.cjs（工程 Spec 上下文客户端）', '工程 Spec 上下文客户端缺失')) {
     deployedModules += 1;
-    vlog('   ✓ 部署 skywalk-sdd/context-client.cjs（工程 Spec 上下文客户端）');
-  } else {
-    console.log(`   ⚠️  工程 Spec 上下文客户端缺失: ${contextClientSrc}`);
   }
 
   const ontologySrc = path.join(pkgPath, 'skywalk-sdd', 'ontology');
   const ontologyDst = path.join(dataDir, 'ontology');
   if (fs.existsSync(ontologySrc)) {
-    copyDir(ontologySrc, ontologyDst);
+    deployDir(ontologySrc, ontologyDst, { strategy: STRATEGY.OVERWRITE });
     deployedModules += 1;
     vlog('   ✓ 部署 skywalk-sdd/ontology/（本地本体语义运行时）');
   } else {
@@ -1104,46 +968,32 @@ function deployTelemetryDataDir(targetCwd = process.cwd()) {
 
   const worktreeFinishSrc = path.join(pkgPath, 'skywalk-sdd', 'apply-worktree-finish.cjs');
   const worktreeFinishDst = path.join(dataDir, 'apply-worktree-finish.cjs');
-  if (fs.existsSync(worktreeFinishSrc)) {
-    fs.copyFileSync(worktreeFinishSrc, worktreeFinishDst);
+  if (deployRuntimeModule(worktreeFinishSrc, worktreeFinishDst, 'skywalk-sdd/apply-worktree-finish.cjs（Apply 收尾脚本）', 'apply-worktree-finish.cjs 源文件缺失，Apply 阶段收尾需要手动执行')) {
     deployedModules += 1;
-    vlog('   ✓ 部署 skywalk-sdd/apply-worktree-finish.cjs（Apply 收尾脚本）');
-  } else {
-    console.log('   ⚠️  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);
+  if (deployRuntimeModule(openspecShimSrc, openspecShimDst, 'skywalk-sdd/openspec-shim.cjs（openspec 包裹包路径 shim）', 'openspec-shim.cjs 源文件缺失，openspec 命令需要手动 cd 到 spec 包执行')) {
     deployedModules += 1;
-    vlog('   ✓ 部署 skywalk-sdd/openspec-shim.cjs（openspec 包裹包路径 shim）');
-  } else {
-    console.log('   ⚠️  openspec-shim.cjs 源文件缺失，openspec 命令需要手动 cd 到 spec 包执行');
   }
 
   // 部署 kb-upload.cjs（知识库上传脚本，支持文件夹/zip 双模式随时入库）
   const kbUploadSrc = path.join(pkgPath, 'skywalk-sdd', 'kb-upload.cjs');
   const kbUploadDst = path.join(dataDir, 'kb-upload.cjs');
-  if (fs.existsSync(kbUploadSrc)) {
-    fs.copyFileSync(kbUploadSrc, kbUploadDst);
+  if (deployRuntimeModule(kbUploadSrc, kbUploadDst, 'skywalk-sdd/kb-upload.cjs（知识库上传：文件夹/zip 双模式）', 'kb-upload.cjs 源文件缺失，随时入库功能不可用')) {
     deployedModules += 1;
-    vlog('   ✓ 部署 skywalk-sdd/kb-upload.cjs（知识库上传：文件夹/zip 双模式）');
-  } else {
-    console.log('   ⚠️  kb-upload.cjs 源文件缺失，随时入库功能不可用');
   }
 
   // 部署 kb-sync-identity.cjs（KB 身份同步脚本，重新入库前同步 version-id）
   const kbSyncIdentitySrc = path.join(pkgPath, 'skywalk-sdd', 'kb-sync-identity.cjs');
   const kbSyncIdentityDst = path.join(dataDir, 'kb-sync-identity.cjs');
-  if (fs.existsSync(kbSyncIdentitySrc)) {
-    fs.copyFileSync(kbSyncIdentitySrc, kbSyncIdentityDst);
+  if (deployRuntimeModule(kbSyncIdentitySrc, kbSyncIdentityDst, 'skywalk-sdd/kb-sync-identity.cjs（KB 身份同步：重新入库前同步 version-id）', 'kb-sync-identity.cjs 源文件缺失，重新入库身份同步不可用')) {
     deployedModules += 1;
-    vlog('   ✓ 部署 skywalk-sdd/kb-sync-identity.cjs（KB 身份同步：重新入库前同步 version-id）');
-  } else {
-    console.log('   ⚠️  kb-sync-identity.cjs 源文件缺失，重新入库身份同步不可用');
   }
 
+  require('./hook-install.js').deployRuntime(cwd, pkgPath);
+
   console.log(`   ✓ 部署 skywalk-sdd/ 运行时（events/state 数据目录 + ${deployedModules} 个模块）`);
   vlog('   ✓ 调用方式: node skywalk-sdd/log.cjs start|end|metrics|semantic-identity|semantic-reconcile|semantic-check');
   vlog('   ✓ openspec: node skywalk-sdd/openspec-shim.cjs list（自动 cd 到 *-sdd-specs）');
@@ -1154,76 +1004,12 @@ function deployTelemetryDataDir(targetCwd = process.cwd()) {
   return true;
 }
 
-/**
- * 安装 SDD shell hook（多脚本调用型 hook，如 pre-commit / pre-push / commit-msg）。
- * 直接部署完整的 shell 脚本到 .git/hooks/，脚本内部远程引用 spec 仓的 .cjs 脚本。
- *
- * shell hook 运行时通过 git config sdd.specPath / .sdd-spec-root / 向上搜索
- * 定位 spec 仓的 skywalk-sdd/git-hooks/ 目录，兼容单仓/多仓/mono 布局。
- *
- * @param {string} cwd - Git 仓库根目录
- * @param {string} hookName - hook 名称（如 'pre-commit'、'pre-push'）
- * @param {string} pkgPath - kld-sdd 包路径（用于读取模板）
- */
-function installSddShellHook(cwd, hookName, pkgPath = getPackagePath()) {
-  const hooksDir = path.join(cwd, '.git', 'hooks');
-  if (!fs.existsSync(hooksDir)) {
-    return;
-  }
-
-  const templatePath = path.join(pkgPath, 'templates', 'git-hooks', hookName);
-  if (!fs.existsSync(templatePath)) {
-    console.log(`   ⚠️  Hook 模板不存在: ${templatePath}`);
-    return;
-  }
-
-  const hookPath = path.join(hooksDir, hookName);
-  const marker = 'KLD SDD quality gate';
-  const content = fs.readFileSync(templatePath, 'utf8');
-
-  if (fs.existsSync(hookPath)) {
-    const existing = fs.readFileSync(hookPath, 'utf8');
-    if (existing.includes(marker)) {
-      // 已是 SDD hook：允许覆盖升级
-      fs.writeFileSync(hookPath, content, 'utf8');
-      try {
-        // 0o700：仅属主可执行（git 以属主身份执行 hook），避免 S2612 对组/其他用户放权的告警
-        fs.chmodSync(hookPath, 0o700);
-      } catch {
-        // ignore
-      }
-      console.log(`   ✓ 更新 .git/hooks/${hookName} SDD 质量门禁（多脚本）`);
-      return;
-    }
-    console.log(`   ℹ️  .git/hooks/${hookName} 已存在且非 SDD 受管 hook，已保留不覆盖`);
-    return;
-  }
-
-  fs.writeFileSync(hookPath, content, 'utf8');
-  try {
-    fs.chmodSync(hookPath, 0o755);
-  } catch {
-    // Windows 上 chmod 可能没有实际效果
-  }
-  console.log(`   ✓ 安装 .git/hooks/${hookName} SDD 质量门禁（多脚本）`);
+/** 安全升级 commit-msg、备份并退役受管旧门禁，保留用户 Hook 与管理器。 */
+function installSddShellHook(cwd, hookName, pkgPath = getPackagePath(), configFile) {
+  return require('./hook-install.js').updateHook(cwd, hookName, pkgPath, configFile);
 }
 
-/**
- * 部署代码仓全部 Git hooks（commit-msg + pre-commit + pre-push）。
- *
- * 统一入口，封装三种 hook 的部署逻辑。代码仓**不落 skywalk-sdd/**，
- * 只在 .git/hooks/ 安装 shell hook 模板，远程引用 spec 仓的 .cjs 脚本：
- *
- * - **spec 仓**：确保 skywalk-sdd/git-hooks/ 下有全部 .cjs 脚本
- *   （commit-msg-sdd-trailer + pre-commit-* + pre-push-* + ontology）。
- * - **代码仓 .git/hooks/**：仅安装 3 个 shell hook 模板，运行时通过
- *   git config sdd.specPath / .sdd-spec-root / 向上搜索定位 spec 仓的脚本。
- *
- * @param {string} codeRepoRoot - 代码仓根目录
- * @param {string} specRepoRoot - spec 包裹包根目录
- * @param {object} options - { pkgPath }
- * @returns {{ ok: boolean, message?: string }}
- */
+/** 代码仓只安装 commit-msg；验证脚本集中部署在 Spec 包。 */
 function deployCodeRepoHooks(codeRepoRoot, specRepoRoot, options = {}) {
   const cwd = path.resolve(codeRepoRoot);
   const specRoot = path.resolve(specRepoRoot);
@@ -1233,32 +1019,11 @@ function deployCodeRepoHooks(codeRepoRoot, specRepoRoot, options = {}) {
     return { ok: false, message: '不是 Git 仓库' };
   }
 
-  // ── 1. 确保 spec 仓有全部 hook 脚本 + ontology ──
-  // commit-msg .cjs + ontology（ensureSpecCommitMsgScript 已处理）
   ensureSpecCommitMsgScript(specRoot, pkgPath);
-  // pre-commit / pre-push .cjs 脚本
-  const specHooksDir = path.join(specRoot, 'skywalk-sdd', 'git-hooks');
-  const gitHooksTemplateDir = path.join(pkgPath, 'templates', 'git-hooks');
-  if (!fs.existsSync(specHooksDir)) {
-    fs.mkdirSync(specHooksDir, { recursive: true });
-  }
-  // 复制全部 .cjs 脚本 + hooks.config 配置文件
-  const hookScripts = fs.existsSync(gitHooksTemplateDir)
-    ? fs.readdirSync(gitHooksTemplateDir).filter(f => f.endsWith('.cjs') || f === 'hooks.config')
-    : [];
-  for (const script of hookScripts) {
-    const src = path.join(gitHooksTemplateDir, script);
-    const dst = path.join(specHooksDir, script);
-    // 始终覆盖，与 shell hook 的 marker 覆盖策略保持一致
-    fs.copyFileSync(src, dst);
-  }
-  console.log(`   ✓ 确保 spec 仓 skywalk-sdd/git-hooks/ 脚本齐全（${hookScripts.length} 个文件）`);
-
-  // ── 2. 安装三个 shell hooks 到代码仓 .git/hooks/ ──
-  // 模板 hook 运行时自动定位 spec 仓的 .cjs 脚本
-  installSddShellHook(cwd, 'commit-msg', pkgPath);
-  installSddShellHook(cwd, 'pre-commit', pkgPath);
-  installSddShellHook(cwd, 'pre-push', pkgPath);
+  const configFile = require('./hook-install.js').deployRuntime(specRoot, pkgPath);
+  for (const name of ['commit-msg', 'pre-commit', 'pre-push']) {
+    installSddShellHook(cwd, name, pkgPath, configFile);
+  }
 
   return { ok: true };
 }
@@ -1278,71 +1043,28 @@ function ensureSpecCommitMsgScript(specRepoRoot, pkgPath = getPackagePath()) {
   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);
+    deployDir(ontologySrc, ontologyDst, { strategy: STRATEGY.OVERWRITE });
   }
   fs.mkdirSync(path.dirname(scriptPath), { recursive: true });
   fs.copyFileSync(src, scriptPath);
   return { ok: true, scriptPath, deployed: 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: 仅安装 commit-msg hook（跳过 pre-commit/pre-push）
- */
+/** 部署验证运行时与轻量 Hook；不自动启用 CI。options 为旧调用兼容保留。 */
 function deployQualityGateTemplates(targetCwd = process.cwd(), options = {}) {
   const pkgPath = getPackagePath();
   const cwd = path.resolve(targetCwd);
-  const mode = options.mode || 'full';
-  // U4: 非 Git 项目跳过 Git hooks / CI 兜底模板（按需部署，不污染非 Git 项目根）
-  if (!fs.existsSync(path.join(cwd, '.git'))) {
-    console.log('🧰 非 Git 项目，跳过 Git hooks / CI 兜底模板部署');
-    return false;
-  }
-  console.log(`🧰 正在部署 SDD Git hooks（${mode}）: ${cwd}`);
-  const dataDir = path.join(cwd, 'skywalk-sdd');
-  const gitHooksTemplateDir = path.join(pkgPath, 'templates', 'git-hooks');
-  const ciTemplateDir = path.join(pkgPath, 'templates', 'ci');
-  const targetGitHooksDir = path.join(dataDir, 'git-hooks');
-  const targetCiDir = path.join(dataDir, 'ci');
-
-  if (fs.existsSync(gitHooksTemplateDir)) {
-    // 复制 .cjs 脚本 + hooks.config 到 skywalk-sdd/git-hooks/
-    // shell hook 模板（commit-msg/pre-commit/pre-push）不落此目录
-    if (!fs.existsSync(targetGitHooksDir)) {
-      fs.mkdirSync(targetGitHooksDir, { recursive: true });
-    }
-    for (const file of fs.readdirSync(gitHooksTemplateDir)) {
-      if (file.endsWith('.cjs') || file === 'hooks.config') {
-        fs.copyFileSync(path.join(gitHooksTemplateDir, file), path.join(targetGitHooksDir, file));
-      }
-    }
-    console.log('   ✓ 部署 skywalk-sdd/git-hooks/（.cjs 脚本 + hooks.config）');
-  } else {
-    console.log(`   ⚠️  Git hooks 模板缺失: ${gitHooksTemplateDir}`);
+  const configFile = require('./hook-install.js').deployRuntime(cwd, pkgPath);
+  if (!workspaceLayout.isGitRepo(cwd)) return false;
+  for (const name of ['commit-msg', 'pre-commit', 'pre-push']) {
+    installSddShellHook(cwd, name, pkgPath, configFile);
   }
-
-  if (mode === 'full' && fs.existsSync(ciTemplateDir)) {
-    copyDir(ciTemplateDir, targetCiDir);
-    console.log('   ✓ 部署 skywalk-sdd/ci/');
-  }
-
-  if (mode === 'full') {
-    installSddShellHook(cwd, 'pre-commit', pkgPath);
-    installSddShellHook(cwd, 'pre-push', pkgPath);
-  }
-  installSddShellHook(cwd, 'commit-msg', pkgPath);
-
-  console.log('✅ Git hooks 已就绪');
+  // CI is an explicit team integration; installing SDD does not enable a merge gate.
   return true;
 }
 
 /**
- * 代码仓轻量接入：写 .sdd.yaml + sdd.specPath + .git/hooks/（commit-msg + pre-commit + pre-push）。
+ * 代码仓轻量接入：写 .sdd.yaml + sdd.specPath + 轻量 commit-msg。
  * 代码仓不落 skywalk-sdd/，shell hook 远程引用 spec 仓 skywalk-sdd/git-hooks/ 下的 .cjs 脚本。
  */
 function attachCodeRepoLite(codeRepoRoot, specRepoRoot, options = {}) {
@@ -1357,21 +1079,25 @@ function attachCodeRepoLite(codeRepoRoot, specRepoRoot, options = {}) {
     return { ok: false, repo: label, message: `spec 路径不是 Git 仓库: ${specRoot}` };
   }
 
-  console.log(`🔗 轻量接入代码仓（commit-msg + pre-commit + pre-push）: ${label}`);
+  const conflict = maintenance.associationConflict(cwd, specRoot);
+  if (conflict) return { ok: false, repo: label, message: conflict };
+
+  console.log(`🔗 轻量接入代码仓（本地关联 Hook）: ${label}`);
 
   const remote = sddConfig.gitRemoteUrl(specRoot) || 'git@gitlab.example.com:biz/xxx-sdd-specs.git';
   const sddYamlPath = path.join(cwd, '.sdd.yaml');
-  if (!fs.existsSync(sddYamlPath)) {
-    fs.writeFileSync(
-      sddYamlPath,
-      [
-        '# 代码仓库关联团队 spec Git 仓库（个人绝对路径勿写入本文件）',
-        'version: 1',
-        `spec_repository: ${remote}`,
-        '',
-      ].join('\n'),
-      'utf8',
-    );
+  // 用户产物 → SKIP_IF_EXISTS：代码仓的 spec_repository 由团队填写，升级不覆盖
+  const yamlResult = deployFile(null, sddYamlPath, {
+    strategy: STRATEGY.SKIP_IF_EXISTS,
+    label: '.sdd.yaml',
+    generate: () => [
+      '# 代码仓库关联团队 spec Git 仓库（个人绝对路径勿写入本文件）',
+      'version: 1',
+      `spec_repository: ${remote}`,
+      '',
+    ].join('\n'),
+  });
+  if (yamlResult.action === ACTION.CREATED) {
     console.log(`   ✓ 写入 .sdd.yaml → ${remote}`);
   } else {
     console.log('   ✓ .sdd.yaml 已存在，跳过覆盖');
@@ -1383,14 +1109,15 @@ function attachCodeRepoLite(codeRepoRoot, specRepoRoot, options = {}) {
   }
   console.log(`   ✓ sdd.specPath = ${linked.path}`);
 
-  // 部署代码仓全部 Git hooks（commit-msg + pre-commit + pre-push）
+  // 部署轻量关联 Hook，并迁移可识别的旧门禁
   deployCodeRepoHooks(cwd, specRoot, options);
 
   return { ok: true, repo: label, path: cwd, specPath: linked.path };
 }
 
 /**
- * 部署 modules.yaml 到 spec 仓库根目录（若不存在）
+ * 部署 modules.yaml 到 spec 仓库根目录（用户产物 → SKIP_IF_EXISTS）
+ * 模块代号由项目团队维护，升级不得覆盖。
  */
 function deployModulesYaml(cwd = process.cwd(), pkgPath = getPackagePath()) {
   console.log('📦 正在检查 modules.yaml...');
@@ -1400,18 +1127,22 @@ function deployModulesYaml(cwd = process.cwd(), pkgPath = getPackagePath()) {
     console.log(`⚠️  modules.yaml 模板缺失: ${source}`);
     return false;
   }
-  if (fs.existsSync(target)) {
-    console.log('   ✓ modules.yaml 已存在，跳过');
+  const result = deployFile(source, target, {
+    strategy: STRATEGY.SKIP_IF_EXISTS,
+    label: 'modules.yaml',
+  });
+  if (result.action === ACTION.SKIPPED) {
+    console.log('   ✓ modules.yaml 已存在（用户产物），跳过');
     return true;
   }
-  fs.copyFileSync(source, target);
   console.log(`✅ 已创建 modules.yaml: ${target}`);
   return true;
 }
 
 /**
- * 部署 sdd.config.yaml（活动变更登记表）到 spec 仓库根目录（若不存在）
- * propose 隐式写入、archive 隐式移除；代码仓 AI 与 commit-msg Hook 读取
+ * 部署 sdd.config.yaml（活动变更登记表）到 spec 仓库根目录（用户产物 → SKIP_IF_EXISTS）
+ * propose 隐式写入、archive 隐式移除；代码仓 AI 与 commit-msg Hook 读取。
+ * 存在即跳过：避免清空 active_changes 导致活跃变更登记静默丢失。
  */
 function deploySddConfigYaml(cwd = process.cwd(), pkgPath = getPackagePath()) {
   console.log('📦 正在检查 sdd.config.yaml...');
@@ -1421,40 +1152,25 @@ function deploySddConfigYaml(cwd = process.cwd(), pkgPath = getPackagePath()) {
     console.log(`⚠️  sdd.config.yaml 模板缺失: ${source}`);
     return false;
   }
-  if (fs.existsSync(target)) {
-    console.log('   ✓ sdd.config.yaml 已存在，跳过');
+  const result = deployFile(source, target, {
+    strategy: STRATEGY.SKIP_IF_EXISTS,
+    label: 'sdd.config.yaml',
+  });
+  if (result.action === ACTION.SKIPPED) {
+    console.log('   ✓ sdd.config.yaml 已存在（含活跃变更登记），跳过');
     return true;
   }
-  fs.copyFileSync(source, target);
   console.log(`✅ 已创建 sdd.config.yaml: ${target}`);
   return true;
 }
 
-/**
- * 部署 .sdd.yaml 示例到代码仓库（若不存在且不像 spec 仓）
- * spec 仓特征：存在 openspec/changes 或 modules.yaml
- */
-function deployDotSddYaml(cwd = process.cwd(), pkgPath = getPackagePath()) {
-  const hasSpecLayout =
-    fs.existsSync(path.join(cwd, 'openspec', 'changes')) ||
-    fs.existsSync(path.join(cwd, 'modules.yaml'));
-  if (hasSpecLayout) {
-    return false;
-  }
-  const source = path.join(pkgPath, 'templates', 'dot-sdd.yaml');
-  const target = path.join(cwd, '.sdd.yaml');
-  if (!fs.existsSync(source) || fs.existsSync(target)) {
-    return false;
-  }
-  console.log('🔗 检测到代码仓库布局，部署 .sdd.yaml 示例...');
-  fs.copyFileSync(source, target);
-  console.log(`✅ 已创建 .sdd.yaml（请修改 spec_repository）: ${target}`);
-  return true;
-}
-
 /**
  * 单仓声明 layout: mono，并记录仓内统一包裹目录相对路径。
  * commit-msg Hook 靠它跳过「spec 工作区干净」检查并只写 Spec-Change。
+ *
+ * 策略为 MERGE：`.sdd.yaml` 是用户产物，只在缺失时创建；
+ * 已存在时仅当「已声明 mono 但 spec_path 缺失/不符」才定向补写该字段，
+ * 其余内容（用户注释、自定义键）原样保留。
  */
 function deployMonoSddYaml(cwd = process.cwd(), options = {}) {
   const target = path.join(cwd, '.sdd.yaml');
@@ -1462,27 +1178,6 @@ function deployMonoSddYaml(cwd = process.cwd(), options = {}) {
     ? 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`');
-    return false;
-  }
   const lines = [
     '# 单仓布局：业务代码与 SDD 包裹包在同一个 Git 仓库',
     '# SDD 内容统一在 spec_path 目录内（openspec / modules / sdd.config / 模版）',
@@ -1492,7 +1187,67 @@ function deployMonoSddYaml(cwd = process.cwd(), options = {}) {
   ];
   if (specRel) lines.push(`spec_path: ${specRel}`);
   lines.push('');
-  fs.writeFileSync(target, lines.join('\n'), 'utf8');
+
+  const result = deployFile(null, target, {
+    strategy: STRATEGY.MERGE,
+    label: '.sdd.yaml',
+    mergeFn: ({ readTarget }) => {
+      let existing = readTarget();
+      if (existing === null) {
+        // 不存在 → 首次创建
+        fs.writeFileSync(target, lines.join('\n'), 'utf8');
+        return { ok: true, action: ACTION.CREATED };
+      }
+
+      // 仍是模板占位（代码仓示例）→ 备份后转为单仓声明。
+      // 必须先于 mono 判定：占位内容不含 layout，否则会被下面的
+      // 「未声明 mono」分支挡掉，单仓初始化直接失败。
+      const placeholder = fs.readFileSync(path.join(getPackagePath(), 'templates/dot-sdd.yaml'), 'utf8');
+      if (existing === placeholder && specRel) {
+        fs.copyFileSync(target, `${target}.pre-mono.bak`);
+        existing = 'version: 1\nlayout: mono\n';
+        fs.writeFileSync(target, existing, 'utf8');
+      }
+
+      if (!/^layout:\s*mono\s*$/m.test(existing)) {
+        return {
+          ok: false,
+          error: '.sdd.yaml 已存在但未声明 layout: mono；单仓请手动补 `layout: mono`',
+        };
+      }
+
+      const specPathPattern = new RegExp(
+        `^spec_path:\\s*${specRel.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\s*$`,
+        'm',
+      );
+      if (!specRel || specPathPattern.test(existing)) {
+        return { ok: true, action: ACTION.SKIPPED };
+      }
+
+      // 已有 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');
+      return { ok: true, action: ACTION.MERGED, message: `已更新 .sdd.yaml spec_path → ${specRel}` };
+    },
+  });
+
+  if (!result.ok) {
+    console.log(`⚠️  ${result.message}`);
+    return false;
+  }
+  if (result.action === ACTION.MERGED) {
+    console.log(`   ✓ ${result.message}`);
+    return true;
+  }
+  if (result.action === ACTION.SKIPPED) {
+    console.log('   ✓ .sdd.yaml 已声明 layout: mono，跳过');
+    return true;
+  }
   console.log(`✅ 已创建 .sdd.yaml（layout: mono${specRel ? `, spec_path: ${specRel}` : ''}）: ${target}`);
   return true;
 }
@@ -1527,12 +1282,16 @@ async function populateSpecPackage(specRoot, options = {}) {
   copyTemplatesToProject(root);
   initGlobalOverview(root);
   deploySddGuideManual(root);
+  // Spec 包可能是独立 Git 仓或单仓内的子目录；忽略规则必须落在它自身，
+  // 不能只写工作区根，否则升级会把整套可再生成运行时显示为业务改动。
+  updateGitignore(root, { specPackage: true });
   console.log(`✅ SDD 包裹包已就绪: ${path.basename(root)}`);
   return { ok: true, path: root };
 }
 
 /**
  * 在工作区 / Git 根写入 .sdd-spec-root，供 shell 与 skills 引用相对包裹包路径。
+ * 内容完全由目录关系推导（派生状态）→ GENERATE，总是重写。
  */
 function writeSddSpecRootHint(anchorDir, specPackageAbs) {
   const anchor = path.resolve(anchorDir);
@@ -1540,7 +1299,11 @@ function writeSddSpecRootHint(anchorDir, 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');
+  deployFile(null, filePath, {
+    strategy: STRATEGY.GENERATE,
+    label: '.sdd-spec-root',
+    generate: () => `${rel}\n`,
+  });
   console.log(`   ✓ 已写入 .sdd-spec-root → ${rel}`);
   return filePath;
 }
@@ -1592,38 +1355,31 @@ function removeOuterSkywalk(anchorDir) {
       return { ok: true, removed: true, mode: 'symlink' };
     }
     if (st.isDirectory()) {
-      fs.rmSync(outer, { recursive: true, force: true });
-      console.log('   ✓ 已移除 Git/工作区根多余的 skywalk-sdd/（实体在包裹包）');
-      return { ok: true, removed: true, mode: 'directory' };
+      // 旧目录可能存有 KB 身份、待上报事件和用户文件，不能整目录删除。
+      for (const file of maintenance.runtimeToolFiles(outer)) fs.unlinkSync(file);
+      const prune = dir => {
+        for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+          if (entry.isDirectory() && !['events', 'state'].includes(entry.name)) prune(path.join(dir, entry.name));
+        }
+        if (!fs.readdirSync(dir).length) fs.rmdirSync(dir);
+      };
+      prune(outer);
+      const retained = fs.existsSync(outer);
+      console.log(retained ? '   ℹ️ 旧 skywalk-sdd/ 的配置、历史数据和未知文件已保留；仅清理工具脚本' : '   ✓ 已清理根目录旧工具脚本');
+      return { ok: true, removed: !retained, retained, mode: 'directory' };
     }
-    fs.unlinkSync(outer);
-    console.log('   ✓ 已移除 Git/工作区根多余的 skywalk-sdd');
-    return { ok: true, removed: true, mode: 'file' };
+    return { ok: true, removed: false, skipped: true }; // 同名用户文件不处理
   } catch (err) {
     console.log(`   ⚠️  未能移除根目录 skywalk-sdd/: ${err.message}`);
     return { ok: false, message: err.message };
   }
 }
 
-/**
- * 检测当前项目已初始化的 AI 编辑器
- */
-function detectTools() {
-  const detected = [];
-  const cwd = process.cwd();
-  for (const [key, config] of Object.entries(TOOL_CONFIGS)) {
-    if (fs.existsSync(path.join(cwd, config.configDir))) {
-      detected.push(key);
-    }
-  }
-  return detected;
-}
-
 /**
  * 创建 / 更新 .gitignore
  * @param {string} [cwd=process.cwd()]
  */
-function updateGitignore(cwd = process.cwd()) {
+function updateGitignore(cwd = process.cwd(), options = {}) {
   const root = path.resolve(cwd);
   const gitignorePath = path.join(root, '.gitignore');
   const requiredLines = [
@@ -1636,14 +1392,16 @@ function updateGitignore(cwd = process.cwd()) {
     '.agents/commands/personal-*',
     'kb-state.json',
     '**/kb-state.json',
-    'skywalk-sdd/kb-state.json',
-    '**/skywalk-sdd/kb-state.json',
     'skywalk-sdd/events/',
     'skywalk-sdd/state/',
     '**/skywalk-sdd/events/',
     '**/skywalk-sdd/state/',
     '.worktrees/'
   ];
+  const specPackageLines = options.specPackage ? maintenance.specPackageIgnoreLines() : [];
+  if (options.specPackage) {
+    requiredLines.push(...specPackageLines);
+  }
 
   const sddConfig = `
 # KLD SDD AI 编辑器个人配置（请勿提交）
@@ -1655,11 +1413,9 @@ function updateGitignore(cwd = process.cwd()) {
 .workbuddy/commands/personal-*
 .agents/commands/personal-*
 
-# KB 绑定状态（含 API Key，勿提交）
+# KB 绑定状态（含 API Key，勿提交；唯一权威位置 = spec 包裹包根目录）
 kb-state.json
 **/kb-state.json
-skywalk-sdd/kb-state.json
-**/skywalk-sdd/kb-state.json
 
 # SDD Telemetry 数据（实体在 *-sdd-specs/skywalk-sdd/；工作区可能是 symlink）
 skywalk-sdd/events/
@@ -1669,140 +1425,172 @@ skywalk-sdd/state/
 
 # SDD Apply 隔离 worktree（本地临时目录）
 .worktrees/
+${options.specPackage ? `
+# KLD SDD 安装器工具（可由 init/升级重新生成，不属于业务 Spec）
+${specPackageLines.join('\n')}
+` : ''}
 `;
 
-  if (fs.existsSync(gitignorePath)) {
-    const content = fs.readFileSync(gitignorePath, 'utf-8');
-    if (!content.includes('KLD SDD')) {
-      fs.appendFileSync(gitignorePath, sddConfig);
-      console.log('✅ 已更新 .gitignore');
-    } else {
-      const missingLines = requiredLines.filter(line => !content.includes(line));
-      if (missingLines.length > 0) {
-        fs.appendFileSync(gitignorePath, `\n# KLD SDD 补充忽略规则\n${missingLines.join('\n')}\n`);
-        console.log('✅ 已补充 .gitignore');
-      }
-    }
-  } else {
-    fs.writeFileSync(gitignorePath, sddConfig.trim());
+  const result = deployFile(null, gitignorePath, {
+    strategy: STRATEGY.APPEND_LINES,
+    label: '.gitignore',
+    lines: requiredLines,
+    block: sddConfig,
+    requiresMarker: 'KLD SDD',
+    supplementHeader: '# KLD SDD 补充忽略规则',
+  });
+
+  if (!result.ok) {
+    console.log(`⚠️  更新 .gitignore 失败: ${result.message}`);
+    return result;
+  }
+  if (result.action === ACTION.CREATED) {
     console.log('✅ 已创建 .gitignore');
+  } else if (result.action === ACTION.APPENDED) {
+    console.log(`✅ 已${result.message && result.message.includes('完整') ? '更新' : '补充'} .gitignore`);
   }
-}
-
-/**
- * 显示帮助信息
- */
-function showHelp() {
-  console.log(`
-KLD SDD 项目初始化工具
-
-用法:
-  kld-sdd-init [选项]
-  npx kld-sdd [选项]
-  kld-sdd sync-repos           # 工作目录下发现新增代码仓并轻量接入
-
-选项:
-  -h, --help       显示帮助信息
-  -v, --version    显示版本号
-  --verbose        输出每个安装文件/目录的明细日志（默认仅摘要，亦可用 KLD_SDD_VERBOSE=1）
-  --skip-openspec  跳过 openspec init 步骤
-  --skip-template  跳过复制内置模版
-  --tool <name>     指定编辑器，可用值: cursor, claude, codebuddy, qoder, opencode, kunlunzhima, workbuddy, codex, all
-  --spec-path <dir> 指定 spec 包裹包目录（必须是当前目录的子目录）。
-                    不指定时（交互终端）：自动检测已有 spec 目录（目录名 *-sdd-specs，
-                    或 modules.yaml + sdd.config.yaml + openspec/changes + openspec/specs/overview.md 齐全），
-                    检测到则询问是否使用；未检测到则要求输入相对路径（回车用默认 <当前目录名>-sdd-specs）。
-                    例: 在 erp-klny-all 下 --spec-path erp-sdd-specs
-
-工作区模式（在个人工作目录执行）:
-  - skills / 编辑器配置只部署一次到当前工作目录
-  - 自动发现子目录 Git 仓库
-  - spec 仓：modules.yaml / openspec 模板 / 文档门禁
-  - 代码仓：仅 commit-msg Hook + .sdd.yaml + link-spec（不装 skills）
-  - Trailer 数据仍在代码 commit 时由 Hook 写入
-
-示例:
-  kld-sdd-init                 # 完整初始化流程
-  kld-sdd-init --skip-openspec # 跳过 openspec，直接部署 skills
-  kld-sdd-init --tool codex    # 仅部署 Codex 配置
-  kld-sdd-init --spec-path erp-sdd-specs  # 指定 spec 目录（当前目录的子目录）
-  kld-sdd sync-repos           # 新代码仓加入后同步接入
-`);
+  return result;
 }
 
 /**
  * 工作区：为已发现的代码仓做轻量接入，并刷新 .sdd-workspace.yaml
+ *
+ * spec 定位遵循与 init / uninstall 相同的「候选集合 → 用户单选」契约：
+ * - `options.specRoot` 已由 CLI 层确认 → 直接采用（不重新探测）
+ * - 未提供 → 枚举候选；**唯一候选**自动采用，**多候选**返回错误交由调用方
+ *   裁决（不静默挑一个）
+ *
+ * 为什么多候选必须停下：本函数会把 spec 根路径**永久写进每个代码仓**的
+ * `git config sdd.specPath`（见 attachCodeRepoLite），挑错等于污染所有代码仓
+ * 的关联关系。历史上这里直接取 `layout.specRepo`（多候选时静默挑第一个），
+ * 与 init / uninstall 的交互契约不一致。
+ *
+ * @param {string} [workspaceRoot]
+ * @param {{onlyNew?: boolean, specRoot?: string}} [options]
+ * @returns {{ok: boolean, attached: Array, failed?: Array, layout: object,
+ *            specRoot?: string|null, filePath?: string, message?: string}}
  */
 function syncWorkspaceRepos(workspaceRoot = process.cwd(), options = {}) {
   const root = path.resolve(workspaceRoot);
   const { layout, newcomers, saved } = workspaceLayout.findNewCodeRepos(root);
   const onlyNew = options.onlyNew !== false;
 
-  if (!layout.specRepo) {
-    console.log('❌ 未发现 spec 仓库（需子目录含 modules.yaml / openspec/changes / *-sdd-specs）');
-    return { ok: false, attached: [], layout };
+  // ── spec 定位：显式指定 > 唯一候选自动采用 > 多候选交调用方裁决 ──
+  let specRootAbs = options.specRoot ? path.resolve(options.specRoot) : null;
+  if (!specRootAbs) {
+    const candidates = specDetect.detectSpecCandidatesWithGit(root);
+    if (candidates.length === 0) {
+      console.log('❌ 未发现 spec 仓库（需子目录含 modules.yaml / openspec/changes / *-sdd-specs）');
+      return { ok: false, attached: [], layout, specRoot: null };
+    }
+    if (candidates.length > 1) {
+      // 交由 CLI 层让用户单选后带 specRoot 重新调用；此处不猜。
+      return {
+        ok: false,
+        attached: [],
+        layout,
+        specRoot: null,
+        candidates,
+        message: `检测到 ${candidates.length} 个 spec 仓库候选，需用户单选`,
+      };
+    }
+    specRootAbs = candidates[0].abs;
   }
 
+  const specName = path.basename(specRootAbs);
+
+  // 代码仓清单必须排除**全部** spec 候选，而不只是被选中的那个。
+  //
+  // 原因：`detectWorkspaceLayout` 的 codeRepos 由 spec 反推
+  //（`children.filter(c => c.abs !== spec.abs)`），只排除它自己挑中的那一个。
+  // 其余候选（如用户复制的 `erp-sdd-specs copy`、未被选中的另一个 spec 包）
+  // 会落进 codeRepos，进而被 attachCodeRepoLite 写入 `.sdd.yaml` 并挂代码仓
+  // hook —— 那不是代码仓，是 spec 仓库/备份。uninstall 侧已有同样的排除逻辑
+  //（见 lib/uninstall.js 的 specDirs 集合）。
+  const specDirs = new Set(
+    specDetect.detectSpecCandidatesWithGit(root).map((c) => path.resolve(c.abs)),
+  );
+  specDirs.add(specRootAbs);
+  const codeRepos = layout.codeRepos.filter(
+    (c) => !specDirs.has(path.resolve(c.abs)),
+  );
+
   console.log(`📂 工作目录: ${root}`);
-  console.log(`📄 Spec 仓: ${layout.specRepo.name}`);
-  console.log(`🔎 已发现代码仓: ${layout.codeRepos.map((c) => c.name).join(', ') || '(无)'}`);
+  console.log(`📄 Spec 仓: ${specName}`);
+  console.log(`🔎 已发现代码仓: ${codeRepos.map((c) => c.name).join(', ') || '(无)'}`);
 
-  const targets = onlyNew && saved.ok
-    ? newcomers
-    : layout.codeRepos;
+  const targets = onlyNew && saved.ok ? newcomers : codeRepos;
+  const filteredTargets = targets.filter(
+    (c) => !specDirs.has(path.resolve(c.abs)),
+  );
 
   if (onlyNew && saved.ok) {
-    console.log(`🆕 待接入新仓: ${newcomers.map((c) => c.name).join(', ') || '(无)'}`);
+    console.log(`🆕 待接入新仓: ${filteredTargets.map((c) => c.name).join(', ') || '(无)'}`);
   }
 
+  const conflicts = maintenance.maintenanceConflicts(root, specRootAbs, codeRepos);
+  if (conflicts.length) return { ok: false, attached: [], failed: conflicts, layout, specRoot: specRootAbs, message: conflicts.map(c => c.repo + ': ' + c.message).join('; ') };
+
   const attached = [];
   const failed = [];
-  for (const repo of targets) {
-    const result = attachCodeRepoLite(repo.abs, layout.specRepo.abs);
+  for (const repo of filteredTargets) {
+    const result = attachCodeRepoLite(repo.abs, specRootAbs);
     if (result.ok) attached.push(result);
     else failed.push(result);
   }
 
-  // 刷新清单（包含本次发现的全部代码仓）
-  const filePath = workspaceLayout.writeWorkspaceFile(root, layout);
+  if (failed.length) return { ok: false, attached, failed, layout, specRoot: specRootAbs };
+
+  // 显式 sync-repos 成功后才刷新清单
+  const layoutForFile = {
+    ...layout,
+    specRepo: { name: specName, abs: specRootAbs },
+    codeRepos,
+  };
+  const filePath = workspaceLayout.writeWorkspaceFile(root, layoutForFile);
   console.log(`✅ 已更新 ${path.basename(filePath)}`);
 
-  return { ok: failed.length === 0, attached, failed, layout, filePath };
+  return {
+    ok: failed.length === 0,
+    attached,
+    failed,
+    layout: layoutForFile,
+    specRoot: specRootAbs,
+    filePath,
+  };
 }
 
 /**
  * 主函数
+ *
+ * CLI 参数解析（argv / 帮助 / 版本 / 编辑器交互选择）全部在 bin/ 层完成，
+ * 本函数只接收已解析的选项对象，不读取 process.argv。
+ * 参数非法时抛错，由 bin 层统一转成 stderr + 非零退出码。
+ *
+ * @param {object} [options]
+ * @param {string[]} [options.tools]       已选编辑器 id 列表；缺省时调用 selectTools 交互选择
+ * @param {Function} [options.selectTools] 交互式选择编辑器（由 bin 注入）
+ * @param {boolean} [options.hasToolArg]   命令行是否显式指定了编辑器（抑制 spec 路径交互询问）
+ * @param {string} [options.specPath]      spec 包裹包目录原始值（相对/绝对），在此做语义校验
+ * @param {boolean} [options.skipOpenspec] 跳过 openspec init 步骤
+ * @param {boolean} [options.skipTemplate] 跳过复制内置模版
+ * @param {string} [options.cwd]           工作目录，缺省 process.cwd()
  */
-async function main() {
-  const args = process.argv.slice(2);
-  
-  // 解析参数
-  if (args.includes('-h') || args.includes('--help')) {
-    showHelp();
-    closeRl();
-    return;
-  }
-  
-  if (args.includes('-v') || args.includes('--version')) {
-    const pkg = require('../package.json');
-    console.log(pkg.version);
-    closeRl();
-    return;
-  }
-  
-  const skipOpenspec = args.includes('--skip-openspec');
-  const skipTemplate = args.includes('--skip-template');
+async function main(options = {}) {
+  const workspaceRoot = path.resolve(options.cwd || process.cwd());
+  const skipOpenspec = Boolean(options.skipOpenspec);
+  const skipTemplate = Boolean(options.skipTemplate);
+  const hasToolArg = options.hasToolArg !== undefined
+    ? Boolean(options.hasToolArg)
+    : Boolean(options.tools && options.tools.length);
 
   // 自定义 spec 目录（--spec-path）：未指定时交互询问（自动检测确认 / 输入相对路径）
-  let customSpec = null;
-  try {
-    const specPathArg = parseSpecPathArg(args);
-    if (specPathArg) customSpec = resolveSpecPathOption(specPathArg, process.cwd());
-  } catch (error) {
-    console.error(`❌ ${error.message}`);
-    closeRl();
-    process.exit(1);
-  }
+  // 路径语义校验（必须落在工作目录内）属业务规则，在此完成；非法时抛错交由 bin 出口处理。
+  // 注意：下面交互分支会回填 customSpec，故必须用 let（const 会抛
+  // "Assignment to constant variable"，导致交互输入路径时初始化直接失败）。
+  let customSpec = options.specPath
+    ? resolveSpecPathOption(options.specPath, workspaceRoot)
+    : null;
 
   console.log('╔════════════════════════════════════════╗');
   console.log('║     KLD SDD 项目初始化工具             ║');
@@ -1810,17 +1598,12 @@ async function main() {
   console.log('╚════════════════════════════════════════╝');
   console.log();
 
-  // 0. 选择编辑器
-  let selectedTools;
-  try {
-    selectedTools = parseSelectedTools(args) || await selectEditor();
-  } catch (error) {
-    console.error(`❌ ${error.message}`);
-    closeRl();
-    process.exit(1);
-  }
-
-  const workspaceRoot = process.cwd();
+  // 0. 选择编辑器（--tool 已指定时直接用；否则由 bin 注入的 selectTools 交互选择）
+  const selectedTools = options.tools && options.tools.length
+    ? options.tools
+    : await (typeof options.selectTools === 'function'
+      ? options.selectTools()
+      : Promise.reject(new Error('未指定编辑器且未注入 selectTools，CLI 入口应传入 bin/kld-sdd-init.js 的 selectEditor')));
   let layout = workspaceLayout.detectWorkspaceLayout(workspaceRoot);
   let specPackage = layout.specRepo
     ? { name: layout.specRepo.name, abs: layout.specRepo.abs, created: false, isGit: true }
@@ -1841,11 +1624,11 @@ async function main() {
     console.log(`📌 使用自定义 spec 目录: ${customSpec.rel}`);
     console.log();
   } else {
-    // 交互提示前兜底检测：Git 仓探测（layout.specRepo）漏掉的非 Git spec 产物
-    const promptCandidate = layout.specRepo
-      ? { name: layout.specRepo.name, abs: layout.specRepo.abs }
-      : detectSpecCandidateForPrompt(workspaceRoot);
-    const interactiveSpec = await promptSpecPath(workspaceRoot, promptCandidate);
+    // 交互提示：传入**完整候选集合**（多候选让用户单选），而不是只传一个。
+    // 集合由 spec-detect 枚举（含 hint/git/mono 权威来源与结构/名称扫描），
+    // 与 uninstall / sync-repos 同源；Git 仓探测漏掉的非 Git spec 产物也在其中。
+    const candidates = listSpecCandidatesForInit(workspaceRoot);
+    const interactiveSpec = await promptSpecPath(workspaceRoot, candidates, { hasToolArg });
     if (interactiveSpec) {
       customSpec = interactiveSpec;
       specPackage = workspaceLayout.ensureSpecPackage(workspaceRoot, {
@@ -1859,6 +1642,12 @@ async function main() {
     }
   }
 
+  if (specPackage) {
+    if (layout.isWorkspace) layout.codeRepos = maintenance.workspaceCodeRepos(workspaceRoot, specPackage.abs, layout, { respectManifest: true });
+    const conflicts = maintenance.maintenanceConflicts(workspaceRoot, specPackage.abs, layout.isWorkspace ? layout.codeRepos : []);
+    if (conflicts.length) throw new Error('未更新工具：' + conflicts.map(c => c.repo + ': ' + c.message).join('; '));
+  }
+
   if (layout.isWorkspace) {
     // 显示层同步过滤：用户交互选择的 spec 目录可能原被分类为代码仓
     const displayCodeRepos = specPackage
@@ -1895,18 +1684,18 @@ async function main() {
         if (!layout.specRepo || path.resolve(layout.specRepo.abs) !== path.resolve(specPackage.abs)) {
           layout.specRepo = { name: specPackage.name, abs: specPackage.abs };
         }
-        layout.codeRepos = layout.codeRepos.filter(
-          (c) => path.resolve(c.abs) !== path.resolve(specPackage.abs),
-        );
+        layout.codeRepos = maintenance.workspaceCodeRepos(workspaceRoot, specPackage.abs, layout, { respectManifest: true });
       }
 
       console.log();
       console.log('🔗 正在为子代码仓做轻量接入（不安装 skills）...');
       for (const repo of layout.codeRepos) {
-        attachCodeRepoLite(repo.abs, specPackage.abs);
+        const result = attachCodeRepoLite(repo.abs, specPackage.abs);
+        if (!result.ok) throw new Error(`${repo.name}: ${result.message}`);
       }
-      const wsFile = workspaceLayout.writeWorkspaceFile(workspaceRoot, layout);
-      console.log(`✅ 工作区清单: ${wsFile}`);
+      const savedWorkspace = workspaceLayout.loadWorkspaceFile(workspaceRoot);
+      const wsFile = savedWorkspace.ok ? savedWorkspace.path : workspaceLayout.writeWorkspaceFile(workspaceRoot, layout);
+      console.log(`✅ 工作区清单${savedWorkspace.ok ? '已保留（新增仓用 sync-repos 接入）' : ''}: ${wsFile}`);
     } else {
       // 单仓：Git 根只放代码 + skills + Hook；SDD 内容进统一包裹子目录
       const isGit = workspaceLayout.isGitRepo(workspaceRoot);
@@ -1920,7 +1709,7 @@ async function main() {
         removeOuterSkywalk(workspaceRoot);
 
         deployMonoSddYaml(workspaceRoot, { specPathRelative: specPackage.name });
-        // 部署代码仓全部 Git hooks（commit-msg + pre-commit + pre-push）
+        // 部署轻量关联 Hook，并迁移可识别的旧门禁
         // 单仓 mono：hook 通过 .sdd-spec-root 定位包裹包的 skywalk-sdd/git-hooks/
         deployCodeRepoHooks(workspaceRoot, specPackage.abs);
         const linked = sddConfig.setSpecPath(workspaceRoot, specPackage.abs, {
@@ -1929,7 +1718,7 @@ async function main() {
         if (linked.ok) {
           console.log(`   ✓ sdd.specPath = ${linked.path}`);
         } else {
-          console.log(`   ⚠️  未能写入 sdd.specPath: ${linked.message}`);
+          throw new Error(`未能写入 sdd.specPath: ${linked.message}`);
         }
       } else {
         // 非 Git 目录：仍创建包裹包，便于随后 git init
@@ -1940,7 +1729,7 @@ async function main() {
         });
         writeSddSpecRootHint(workspaceRoot, specPackage.abs);
         removeOuterSkywalk(workspaceRoot);
-        deployDotSddYaml(workspaceRoot);
+        deployMonoSddYaml(workspaceRoot, { specPathRelative: specPackage.name });
       }
     }
   } else if (!skipOpenspec) {
@@ -1958,7 +1747,7 @@ async function main() {
   // 7. 更新工作目录 .gitignore
   updateGitignore(workspaceRoot);
 
-  // 8. 收尾：无论前面是否走过 symlink/旧副本路径，强制清掉工作区/Git 根多余 skywalk-sdd/
+  // 8. 收尾：清理可识别的旧工具，保留历史配置和数据
   if (specPackage && fs.existsSync(specPackage.abs)) {
     writeSddSpecRootHint(workspaceRoot, specPackage.abs);
   }
@@ -2068,35 +1857,27 @@ async function main() {
 // kld-T06: Progress Runtime 已删除，用户级 workspace 注册函数一并移除。
 // 使用统计按本机 git 身份（user.name/user.email）上报，无需任何账号绑定。
 
+/**
+ * 对外导出面（仅 CLI 入口与测试实际消费的符号）。
+ * 内部实现函数不导出，避免被外部当作稳定契约而阻碍重构。
+ */
 module.exports = {
   main,
-  detectTools,
-  getTemplatePath,
-  getPackagePath,
-  selectEditor,
+  setVerbose,
   isVerbose,
-  vlog,
   deployOpsxSkills,
+  copyDirRendered,
   copyTemplatesToProject,
-  deployProfileArtifacts,
-  deploySddGuideManual,
-  deployModulesYaml,
-  deploySddConfigYaml,
-  deployDotSddYaml,
   deployMonoSddYaml,
   populateSpecPackage,
   writeSddSpecRootHint,
   removeOuterSkywalk,
   deployQualityGateTemplates,
   deployTelemetryDataDir,
-  updateGitignore,
   attachCodeRepoLite,
   syncWorkspaceRepos,
-  copyDirRendered,
-  parseSelectedTools,
   promptSpecPath,
-  detectSpecCandidateForPrompt,
-  installSddShellHook,
+  listSpecCandidatesForInit,
   deployCodeRepoHooks,
-  TOOL_CONFIGS,
+  updateGitignore,
 };