kld-sdd 2.7.8-4 → 2.7.8-6

package/README.md

@@ -6,6 +6,30 @@ KLD SDD OpenSpec 工程增强工具：一键初始化 AI 编辑器技能、语
 
 日常提交默认只保留本地关联 Hook；Apply 自动执行代码/Spec 检查、真实测试与交付验证。旧项目升级、备份回退、多仓和 CI 边界见 [Git Hook 调整说明](USABILITY.md#2026-09-10git-hook-收缩与交付验证)。
 
+## 工具更新与卸载
+
+**更新不需要先卸载。** 在原工作目录重新运行安装器，覆盖运行脚本、Skills 和只读模板；Spec 文档、KB 绑定、项目身份、历史数据、用户配置和自定义 Hook 保留。先确认目标编辑器及 Spec 目录，完成后检查实际部署版本。下载失败不启动安装；执行中断后可以重跑补齐，不承诺整个项目的事务回滚。
+
+```bash
+# 选择包含本次修复的新发布版本，在原工作目录更新
+npx kld-sdd@<新版版本号> --tool=cursor --spec-path=team-sdd-specs --skip-openspec
+
+# 卸载只有工具一种方式；可以先看计划
+npx kld-sdd@<新版版本号> uninstall --dry-run
+npx kld-sdd@<新版版本号> uninstall
+```
+
+卸载不再提供全量删除，旧 `--purge` 参数会报错退出。`openspec/`（含活动变更、归档和规格）、KB 配置、身份、历史数据、`.sdd.yaml`、`.sdd-spec-root`、`.sdd-workspace.yaml`、Git 关联和隐私忽略规则始终保留。工具目录内的未知文件和自建规则也保留；Git Hook 只有完整匹配受管版本时才删除。预览后文件改变需要重新预览。
+
+多仓注意：
+
+- 升级沿用已有清单，只维护登记的代码仓；多个 Spec 和备份不会互相接入。新代码仓通过 `kld-sdd sync-repos` 明确接入，追加清单时保留注释、自定义字段和原有记录。
+- 本地路径、团队远程声明或工作区清单冲突时，先停止更新并提示核对，不自动换绑。
+- 从单个代码仓卸载时，工作目录外的共享 Spec 工具保留。从 worktree 卸载时，共用的 Git Hook 保留，应从主仓库管理。
+- 旧平铺 `skywalk-sdd/` 只清理已知工具，历史数据原位保留，不自动合并两份项目身份或运行状态。
+
+以上行为需要使用包含本次改动的新版本；修改此源码不会改变已经发布的 npm 包。安装包通过 `sddMaintenance.toolOnly: 1` 声明该维护契约，托盘据此避免用旧安装器处理存在已知清理风险的布局。
+
 ## 这是什么？
 
 **SDD（Specification-Driven Development）** 是一种以文档链驱动 AI 编码的研发方法：先写清楚"要做什么"，再让 AI 去实现，避免 AI 乱猜、反复返工。

package/bin/kld-sdd-init.js

@@ -12,7 +12,7 @@
  *   log          SDD Telemetry CLI（记录阶段事件、查询指标）
  *   link-spec    将代码仓关联到本地 spec clone（git config sdd.specPath）
  *   sync-repos   工作目录下发现新增代码仓并轻量接入（不装 skills）
- *   uninstall    卸载 SDD 产物（渐进式：先选方式，再预览计划，最后确认执行）
+ *   uninstall    卸载 SDD 产物（渐进式：先预览工具范围，最后确认执行）
  */
 
 'use strict';
@@ -20,7 +20,8 @@
 const path = require('path');
 const { listToolProfileIds, buildToolConfigs } = require('../lib/tool-profiles');
 const { MODE, OP, modeLabel } = require('../lib/uninstall');
-const { specSourceLabel } = require('../skywalk-sdd/ontology/spec-detect.cjs');
+const specDetect = require('../skywalk-sdd/ontology/spec-detect.cjs');
+const { specSourceLabel } = specDetect;
 // spec 候选单选交互（唯一实现，与 lib/init.js 共用）
 const { selectSpecRoot: selectSpecChoice } = require('../lib/spec-choice');
 
@@ -125,6 +126,9 @@ function parseInitArgs(argv = cliArgs(), env = process.env) {
     verbose: isVerbose(argv, env),
     skipOpenspec: argv.includes('--skip-openspec'),
     skipTemplate: argv.includes('--skip-template'),
+    repairGit: argv[0] === 'repair-git' || argv.includes('--repair-git'),
+    applyRepair: argv.includes('--apply'),
+    json: argv.includes('--json'),
     tools,
     // 显式给了 --tool 即自动化场景：lib 据此抑制 spec 路径的交互询问
     hasToolArg: tools !== null,
@@ -136,19 +140,19 @@ function parseInitArgs(argv = cliArgs(), env = process.env) {
  * kld-sdd uninstall [选项]
  *
  * 卸载产物与编辑器无关（8 个编辑器的产物全量扫描），工作目录固定为当前目录，
- * 故不提供 --tool / --project：卸载范围由「方式选择」决定，目录由 cwd 决定。
+ * 故不提供 --tool / --project：仅卸载当前范围的工具，目录由 cwd 决定。
  *
  * --spec-path 用于无人值守场景：多候选（如用户复制的备份）时无法自动判定，
  * 需显式指定要卸载的 spec 仓库。
  */
 function parseUninstallArgs(argv = cliArgs()) {
-  const purge = argv.includes('--purge');
+  if (argv.some(arg => arg === '--purge' || arg.startsWith('--purge=') || arg === '--full' || arg.startsWith('--mode'))) {
+    throw new Error('已取消全量删除，仅支持卸载工具；Spec 文档、配置与历史数据始终保留');
+  }
   return {
     cwd: process.cwd(),
     specPath: parseSpecPathOption(argv),
-    mode: purge ? MODE.FULL : MODE.TOOLS_ONLY,
-    // 是否显式指定了方式：未指定且未跳过交互时，进入渐进式方式选择
-    modeExplicit: purge,
+    mode: MODE.TOOLS_ONLY,
     dryRun: argv.includes('--dry-run'),
     yes: hasFlag(argv, '--yes', '-y'),
     help: hasFlag(argv, '-h', '--help'),
@@ -325,78 +329,26 @@ async function selectSpecRoot(prompt, candidates, options = {}) {
   return selectSpecChoice(prompt, candidates, options);
 }
 
-/**
- * 渐进式选择卸载方式。
- * 默认「1 卸载工具内容」为保守选项，回车即安全；无效输入重新询问。
- *
- * @returns {Promise<string|null>} MODE 之一；null 表示用户取消
- */
-async function selectUninstallMode(prompt) {
-  while (true) {
-    // 选项文本并入 question：readline 重绘提示行会发 \x1b[0J（清除光标之后内容），
-    // 提问前的 console.log 会被抹掉，导致用户看不到选项。
-    const question = [
-      '请选择卸载方式:',
-      '  1. 卸载工具内容（默认，保留用户配置与运行时数据）',
-      '     删除 编辑器 skills / hook 脚本 / skywalk-sdd 工具脚本 / 文档模版',
-      '     保留 modules.yaml、sdd.config.yaml、.sdd.yaml、events/、state/',
-      '  2. 全量卸载（含用户配置、运行时数据与文档工作区）',
-      '     在「1」的基础上，额外删除上述用户配置、历史度量数据与 openspec/ 整目录',
-      '     ⚠️  openspec/ 内含 changes/ 变更提案与 specs/ 业务规格文档，将一并删除',
-      '  0. 取消',
-      '\n请输入选项 (0-2，直接回车=1): ',
-    ].join('\n');
-
-    const answer = await prompt.ask(question);
-    if (answer === '' || answer === '1') return MODE.TOOLS_ONLY;
-    if (answer === '2') return MODE.FULL;
-    if (answer === '0' || /^(q|quit|exit)$/i.test(answer)) return null;
-    console.log(`❌ 无效选项 "${answer}"，请输入 0-2 之间的数字\n`);
-  }
-}
-
 /** 显示卸载帮助信息 */
 function showUninstallHelp() {
   console.log(`
-KLD SDD 卸载工具
+KLD SDD 工具卸载
 
 用法:
-  kld-sdd uninstall               # 渐进式交互（推荐）：选方式 → 预览计划 → 确认
-  kld-sdd uninstall [选项]        # 非交互：显式给出方式与确认
+  kld-sdd uninstall                 # 选择 Spec → 预览范围 → 确认
+  kld-sdd uninstall --dry-run       # 只看计划，不修改文件
+  kld-sdd uninstall --yes --spec-path <dir>  # 明确范围后用于脚本
 
-选项:
-  -h, --help       显示本帮助
-  --purge          全量卸载（含用户配置与运行时数据）；不指定则只卸载工具内容
-  --dry-run        预演，打印计划预览但不落盘（不进入交互）
-  --spec-path <dir> 显式指定要卸载的 spec 仓库（无人值守时多候选必须指定）
-  -y, --yes        跳过最后的执行确认（CI / 脚本用）
-
-说明:
-  卸载在「当前目录」执行，产物范围为全部 8 个编辑器（cursor, claude, codebuddy,
-  qoder, opencode, kunlunzhima, workbuddy, codex），无需也无法指定编辑器。
-  卸载范围由方式选择（工具内容 / 全量）决定。需在目标项目目录下执行本命令。
-
-  交互流程：spec 仓库选择 → 卸载方式选择 → 计划预览 → 确认执行。
-  若检测到多个 spec 仓库（例如您手动复制了一份备份），会列出候选让您单选；
-  无人值守（--yes / 无 TTY）时多候选会直接报错，请用 --spec-path 指定。
-
-两种方式的区别:
-  工具内容卸载（默认）:
-    删除  编辑器 skills（opsx-* / tdd-* / openspec-*）、sdd-*.cjs hook 脚本、
-          hook-gate-core.cjs、skywalk-sdd/ 工具脚本、openspec-templates/、操作手册
-    保留  settings.json 文件本身（仅摘除 SDD 受管 hook）、modules.yaml、
-          sdd.config.yaml、.sdd.yaml、.sdd-spec-root、skywalk-sdd/events/ 与 state/、
-          openspec/ 文档工作区
-  全量卸载（--purge）:
-    在「工具内容卸载」基础上，额外删除上述保留项中的用户配置、历史度量数据，
-    以及 openspec/ 整目录（含 changes/ 变更提案、specs/ 业务规格与 overview.md、
-    config.yaml）。执行前会打印待删目录与文件数，需二次确认。
+仅删除可识别的 SDD Skills、运行脚本、只读模板与受管 Hook。
+始终保留 openspec/ 全部文档、KB 配置、项目身份、历史数据、多仓关联和 Git 历史。
+自定义 Hook、规则、未知文件与隐私忽略规则保留。不提供全量删除模式。
 
-示例:
-  kld-sdd uninstall                          # 交互式，最常用（在项目目录下执行）
-  kld-sdd uninstall --dry-run                # 只看计划
-  kld-sdd uninstall --purge --dry-run        # 全量预演
-  kld-sdd uninstall --purge --yes            # 全量执行，不询问
+-h, --help         显示本帮助
+--spec-path <dir>  指定目标 Spec；多个候选时必须选择，备份不受影响
+--dry-run          只预览
+-y, --yes          确认工具卸载；非交互执行必须提供
+
+升级不需要先卸载：重新运行 init 覆盖工具文件，保留已有文档及配置。
 `);
 }
 
@@ -409,8 +361,9 @@ KLD SDD 项目初始化工具
   kld-sdd-init [选项]
   npx kld-sdd [选项]
   kld-sdd sync-repos           # 工作目录下发现新增代码仓并轻量接入（多 spec 候选时单选）
-  kld-sdd uninstall [选项]     # 卸载 SDD 产物（渐进式：选方式 → 预览 → 确认）
-  kld-sdd uninstall --help     # 查看卸载选项与两种方式的区别
+  kld-sdd repair-git           # 检查并清理旧 Spec 仓的工具跟踪噪声（默认只预览）
+  kld-sdd uninstall [选项]     # 卸载 SDD 产物（渐进式：预览工具范围 → 确认）
+  kld-sdd uninstall --help     # 查看工具卸载与保留范围
 
 选项:
   -h, --help       显示帮助信息
@@ -418,6 +371,9 @@ KLD SDD 项目初始化工具
   --verbose        输出每个安装文件/目录的明细日志（默认仅摘要，亦可用 KLD_SDD_VERBOSE=1）
   --skip-openspec  跳过 openspec init 步骤
   --skip-template  跳过复制内置模版
+  --repair-git     检查 Spec 仓中被 Git 跟踪的安装器工具（默认只预览）
+  --apply          与 --repair-git 同用：保留本地文件，仅从 Git 索引移除工具
+  --json           --repair-git 输出机器可读 JSON，供托盘健康检查使用
   --tool <name>     指定编辑器，可用值: cursor, claude, codebuddy, qoder, opencode, kunlunzhima, workbuddy, codex, all
   --spec-path <dir> 指定 spec 包裹包目录（必须是当前目录的子目录）。
                     不指定时（交互终端）：自动检测已有 spec 目录（目录名 *-sdd-specs，
@@ -437,6 +393,8 @@ KLD SDD 项目初始化工具
   kld-sdd-init --skip-openspec # 跳过 openspec，直接部署 skills
   kld-sdd-init --tool codex    # 仅部署 Codex 配置
   kld-sdd-init --spec-path erp-sdd-specs  # 指定 spec 目录（当前目录的子目录）
+  kld-sdd repair-git --spec-path=.          # 预览旧仓工具跟踪问题
+  kld-sdd repair-git --apply --spec-path=.  # 一次迁出工具，文件仍留在磁盘
   kld-sdd sync-repos           # 新代码仓加入后同步接入
 `);
 }
@@ -445,6 +403,72 @@ KLD SDD 项目初始化工具
 // 子命令路由：解析参数后调用 lib/ 业务实现
 // ═══════════════════════════════════════════════════════════════
 
+function resolveRepairSpecRoot(parsed, cwd = process.cwd()) {
+  const root = path.resolve(cwd);
+  if (parsed.specPath) {
+    const explicit = path.resolve(root, parsed.specPath);
+    if (!specDetect.isSpecPackageRoot(explicit)) {
+      throw new Error(`指定目录不是有效的 Spec 包裹包: ${explicit}`);
+    }
+    return explicit;
+  }
+  if (specDetect.isSpecPackageRoot(root)) return root;
+  const candidates = specDetect.detectSpecCandidatesWithGit(root);
+  if (candidates.length === 1) return candidates[0].abs;
+  if (candidates.length === 0) throw new Error('未发现 Spec 包裹包，请用 --spec-path=<dir> 指定');
+  throw new Error(`发现 ${candidates.length} 个 Spec 包裹包，请用 --spec-path=<dir> 指定，不自动猜测`);
+}
+
+function runGitRepair(parsed) {
+  const init = require('../lib/init');
+  const maintenance = require('../lib/maintenance');
+  const specRoot = resolveRepairSpecRoot(parsed);
+  const plan = maintenance.trackedManagedSpecTools(specRoot);
+  if (!plan.ok) throw new Error(plan.error);
+
+  if (!parsed.applyRepair) {
+    const payload = {
+      mode: 'preview',
+      specRoot,
+      trackedToolCount: plan.files.length,
+      trackedTools: plan.files.map((file) => file.relative),
+      businessFilesAffected: 0,
+    };
+    if (parsed.json) {
+      console.log(JSON.stringify(payload, null, 2));
+      return;
+    }
+    console.log(`🧹 Spec Git 清洁度检查: ${path.basename(specRoot)}`);
+    console.log(`   被 Git 跟踪的可再生成工具: ${plan.files.length} 个`);
+    for (const file of plan.files.slice(0, 8)) console.log(`   - ${file.relative}`);
+    if (plan.files.length > 8) console.log(`   … 其余 ${plan.files.length - 8} 个`);
+    console.log('   业务 Spec、配置、项目身份与 Hook 参数: 不处理');
+    if (plan.files.length) console.log('   执行 --repair-git --apply 可一次迁出工具；不会删除磁盘文件。');
+    return;
+  }
+
+  const existingBefore = plan.files.filter((file) => require('fs').existsSync(path.join(specRoot, file.relative)));
+  init.updateGitignore(specRoot, { specPackage: true });
+  const result = maintenance.untrackManagedSpecTools(specRoot);
+  if (!result.ok) throw new Error(result.error);
+  const payload = {
+    mode: 'applied',
+    specRoot,
+    untrackedToolCount: result.files.length,
+    filesRemainOnDisk: existingBefore.every((file) => require('fs').existsSync(path.join(specRoot, file.relative))),
+    retainedLocalToolCount: existingBefore.length,
+    alreadyMissingToolCount: result.files.length - existingBefore.length,
+    businessFilesAffected: 0,
+  };
+  if (parsed.json) {
+    console.log(JSON.stringify(payload, null, 2));
+    return;
+  }
+  console.log(`✅ 已将 ${result.files.length} 个安装器工具移出 Git 跟踪，现存的 ${existingBefore.length} 个本地文件全部保留`);
+  if (payload.alreadyMissingToolCount) console.log(`   ℹ️ 其中 ${payload.alreadyMissingToolCount} 个文件在修复前已从磁盘删除`);
+  console.log('   请审阅一次 git status 并提交迁移；以后升级不再污染业务改动列表。');
+}
+
 async function runInit() {
   let parsed;
   try {
@@ -464,6 +488,15 @@ async function runInit() {
     return;
   }
 
+  if (parsed.repairGit) {
+    try {
+      runGitRepair(parsed);
+    } catch (error) {
+      fail(`Git 清洁度修复失败: ${error.message}`);
+    }
+    return;
+  }
+
   const init = require('../lib/init');
   init.setVerbose(parsed.verbose);
 
@@ -484,7 +517,7 @@ async function runInit() {
 /**
  * 卸载（渐进式）：方式选择 → 计划预览 → 确认执行。
  *
- * 交互编排全部在本函数（CLI 输入层）；lib/uninstall 只提供纯计算与执行：
+ * 交互编排全部在本函数（CLI 输入层）；仅选择 Spec、预览工具范围并确认：
  * - buildUninstallPlan  纯计算计划，不落盘
  * - main                按给定计划执行，无交互
  *
@@ -524,7 +557,7 @@ async function runUninstall(argv = args, deps = {}) {
   // 候选枚举：结构判据无法区分「当前项目的 spec 仓」与「用户复制的备份」
   //（如 `erp-sdd-specs copy` 结构标记齐全），故由用户单选裁决。
   // 显式 --spec-path 时跳过枚举（调用方已指定）。
-  let specRoot = opts.specPath ? path.resolve(opts.specPath) : undefined;
+  let specRoot = opts.specPath ? path.resolve(cwd, opts.specPath) : undefined;
   const candidates = specRoot ? [] : listSpecCandidatesForUninstall(cwd);
 
   if (!specRoot && candidates.length > 1 && !canPrompt) {
@@ -539,6 +572,7 @@ async function runUninstall(argv = args, deps = {}) {
     throw new Error('多个 spec 仓库候选，需 --spec-path 显式指定');
   }
 
+  if (!specRoot && !canPrompt && candidates.length === 1) specRoot = candidates[0].abs;
   const prompt = canPrompt ? promptFactory() : null;
 
   // 步骤 1：spec 仓库选择（多候选 → 用户单选；单候选 → 确认）
@@ -563,31 +597,15 @@ async function runUninstall(argv = args, deps = {}) {
     }
 
     if (!prompt) {
+      if (!dryRun && !opts.yes) throw new Error('非交互卸载需要 --yes；可先用 --dry-run 预览');
       printUninstallHeader(cwd, planned.specRoot, mode, dryRun);
       if (dryRun) printPlanPreview(planned.plan);
       // 已打印过预览（含警告）时不重复；直接执行时由 lib 打印
-      runUninstallPlan({ cwd, mode, dryRun, plan: planned.plan, showWarnings: !dryRun });
+      const result = runUninstallPlan({ cwd, mode, dryRun, plan: planned.plan, showWarnings: !dryRun });
+      if (!result.ok) throw new Error(result.errors.join('; '));
       return;
     }
 
-    // 步骤 3：方式选择（已显式 --purge 则跳过）
-    if (!opts.modeExplicit) {
-      const chosen = await selectUninstallMode(prompt);
-      if (chosen === null) {
-        console.log('已取消');
-        return;
-      }
-      if (chosen !== mode) {
-        mode = chosen;
-        planned = buildUninstallPlan({ cwd, mode, specRoot });
-        if (planned.plan.ops.length === 0) {
-          printUninstallHeader(cwd, planned.specRoot, mode, dryRun);
-          console.log('ℹ️  未发现需要处理的 SDD 产物（可能未初始化或已卸载）');
-          return;
-        }
-      }
-    }
-
     // 步骤 4：计划预览
     printUninstallHeader(cwd, planned.specRoot, mode, dryRun);
     printPlanPreview(planned.plan);
@@ -602,7 +620,8 @@ async function runUninstall(argv = args, deps = {}) {
     console.log('');
 
     // 交互路径：警告已由 printPlanPreview 打印过，不再重复
-    runUninstallPlan({ cwd, mode, dryRun, plan: planned.plan, showWarnings: false });
+    const result = runUninstallPlan({ cwd, mode, dryRun, plan: planned.plan, showWarnings: false });
+    if (!result.ok) throw new Error(result.errors.join('; '));
   } finally {
     if (prompt) prompt.close();
   }
@@ -724,7 +743,6 @@ module.exports = {
   runUninstall,
   parseUninstallArgs,
   printPlanPreview,
-  selectUninstallMode,
   selectSpecRoot,
   showUninstallHelp,
 };

package/lib/init.js

@@ -31,6 +31,7 @@ const {
 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');
@@ -336,6 +337,7 @@ function copyDirRendered(source, target, config, toolKey) {
   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);
       return rendered;
@@ -1077,6 +1079,9 @@ function attachCodeRepoLite(codeRepoRoot, specRepoRoot, options = {}) {
     return { ok: false, repo: label, message: `spec 路径不是 Git 仓库: ${specRoot}` };
   }
 
+  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';
@@ -1277,6 +1282,9 @@ 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 };
 }
@@ -1347,13 +1355,20 @@ 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 };
@@ -1364,7 +1379,7 @@ function removeOuterSkywalk(anchorDir) {
  * 创建 / 更新 .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 = [
@@ -1383,6 +1398,10 @@ function updateGitignore(cwd = process.cwd()) {
     '**/skywalk-sdd/state/',
     '.worktrees/'
   ];
+  const specPackageLines = options.specPackage ? maintenance.specPackageIgnoreLines() : [];
+  if (options.specPackage) {
+    requiredLines.push(...specPackageLines);
+  }
 
   const sddConfig = `
 # KLD SDD AI 编辑器个人配置（请勿提交）
@@ -1406,6 +1425,10 @@ skywalk-sdd/state/
 
 # SDD Apply 隔离 worktree（本地临时目录）
 .worktrees/
+${options.specPackage ? `
+# KLD SDD 安装器工具（可由 init/升级重新生成，不属于业务 Spec）
+${specPackageLines.join('\n')}
+` : ''}
 `;
 
   const result = deployFile(null, gitignorePath, {
@@ -1505,6 +1528,9 @@ function syncWorkspaceRepos(workspaceRoot = process.cwd(), options = {}) {
     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 filteredTargets) {
@@ -1513,7 +1539,9 @@ function syncWorkspaceRepos(workspaceRoot = process.cwd(), options = {}) {
     else failed.push(result);
   }
 
-  // 刷新清单（spec 指向用户确认的那个；代码仓排除 spec 包自身）
+  if (failed.length) return { ok: false, attached, failed, layout, specRoot: specRootAbs };
+
+  // 显式 sync-repos 成功后才刷新清单
   const layoutForFile = {
     ...layout,
     specRepo: { name: specName, abs: specRootAbs },
@@ -1614,6 +1642,12 @@ async function main(options = {}) {
     }
   }
 
+  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
@@ -1650,18 +1684,18 @@ async function main(options = {}) {
         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);
@@ -1684,7 +1718,7 @@ async function main(options = {}) {
         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
@@ -1713,7 +1747,7 @@ async function main(options = {}) {
   // 7. 更新工作目录 .gitignore
   updateGitignore(workspaceRoot);
 
-  // 8. 收尾：无论前面是否走过 symlink/旧副本路径，强制清掉工作区/Git 根多余 skywalk-sdd/
+  // 8. 收尾：清理可识别的旧工具，保留历史配置和数据
   if (specPackage && fs.existsSync(specPackage.abs)) {
     writeSddSpecRootHint(workspaceRoot, specPackage.abs);
   }
@@ -1845,4 +1879,5 @@ module.exports = {
   promptSpecPath,
   listSpecCandidatesForInit,
   deployCodeRepoHooks,
+  updateGitignore,
 };