@netpilot/skills 0.4.0 → 0.7.0

package/.claude-plugin/marketplace.json

@@ -4,13 +4,13 @@
   "owner": {
     "name": "NetPilot"
   },
-  "description": "NetPilot 个人 AI 工程协作插件目录",
+  "description": "NetPilot AI 工程协作插件目录",
   "plugins": [
     {
       "name": "netpilot-skills",
       "source": "./",
       "description": "中文工程协作 skills 与可组合工作流",
-      "version": "0.4.0",
+      "version": "0.7.0",
       "author": {
         "name": "NetPilot"
       },

package/.claude-plugin/plugin.json

@@ -2,7 +2,7 @@
   "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
   "name": "netpilot-skills",
   "displayName": "NetPilot Skills",
-  "version": "0.4.0",
+  "version": "0.7.0",
   "description": "面向 Claude Code 的中文工程协作 skills 与可组合工作流",
   "author": {
     "name": "NetPilot"

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "netpilot-skills",
-  "version": "0.4.0",
+  "version": "0.7.0",
   "description": "面向 Codex 的中文工程协作 skills 与可组合工作流",
   "author": {
     "name": "NetPilot"

package/CHANGELOG.md

@@ -4,6 +4,19 @@
 
 ## Unreleased
 
+## 0.7.0
+
+- 新增用户级 `security-reviewer` 与 `migration-reviewer`：前者按应用、Agent/Tool 与供应链 profile 审查信任边界，后者按 Expand → Migrate → Contract 审查 schema、回填、兼容切换与恢复；两者均保持 high / read-only 和统一 P0–P3 证据契约。
+- 扩展 `backend-reviewer` 的 API 消费者兼容、查询、索引、Redis 与 fail-safe 检查，扩展 `frontend-reviewer` 的 contract 漂移、服务端授权和浏览器 console/network 证据要求。
+- 在 Agent 编写规范中固定六个默认角色的主任务路由、去重与串行降级边界；打包、README 与 roster 测试同步覆盖 6 个 Codex Agents。
+- 与 `@netpilot/harness` 协调发布同一 `v0.7.0` 标签；Harness 只路由用户级安全与 migration reviewer，不在项目 `.codex/agents` 复制同名角色。
+
+## 0.6.0
+
+- 将用户级与项目级安装状态迁移到中性的 `.agents/.state/skills-installer`；旧 `.netpilot-skills` 在 apply 时经锁保护、目录身份复核后原子迁移，preview 仅报告计划。旧版客户端留下的精确空目录可安全自愈，真实双状态或目标冲突仍整批停止。
+- 项目安装继续只写入 `.agents/skills`，不安装项目级 Agents；用户级默认仍安装 Codex Skills 与少量 Codex Agents。
+- 与 `@netpilot/harness` 协调发布同一 `v0.6.0` 标签，便于在新电脑或新项目中识别兼容的一组安装器能力；两个包仍保持独立职责和发布契约。
+
 ## 0.4.0
 
 - 将工程与生产力方法扩展为 21 个去个人化 skills，按上游原有结构恢复完整工作流、步骤内门禁、方法自身的反模式，以及有实际价值的 `references/` 和跨平台脚本；不再为每个 skill 强加统一尾部章节。

package/README.md

@@ -42,7 +42,7 @@ npm install --global @netpilot/skills
 netpilot-skills
 ```
 
-安装器不会覆盖未受管理或用户修改过的同名文件；发生冲突时整批停止。项目范围只安装 Skills，项目级 Agents 仍由 [NetPilot Harness](https://github.com/netpilot-z/harness) 管理。
+安装器不会覆盖未受管理或用户修改过的同名文件；发生冲突时整批停止。同步状态保存在 `.agents/.state/skills-installer`：用户安装位于 home，项目安装位于项目根；旧 `.netpilot-skills` 会在下一次实际安装时原子迁移，预览只展示计划。旧版安装器在新状态旁留下的空旧目录会安全自愈，含内容的双状态仍会阻断。项目范围只安装 Skills，项目级 Agents 仍由 [NetPilot Harness](https://github.com/netpilot-z/harness) 管理。
 
 ## 核心用法
 
@@ -93,6 +93,8 @@ Codex 使用 `$skill-name`；Claude Code 用户级安装使用 `/skill-name`。
 | --- | --- | --- |
 | `frontend-reviewer` | 前端状态、交互、可访问性和测试审查 | high / read-only |
 | `backend-reviewer` | 接口、权限、事务和数据一致性审查 | high / read-only |
+| `security-reviewer` | 应用、Agent、Tool 与供应链安全审查 | high / read-only |
+| `migration-reviewer` | schema、回填、兼容切换与恢复审查 | high / read-only |
 | `architecture-designer` | 模块边界、依赖和迁移方案比较 | high / read-only |
 | `test-verifier` | 执行测试、类型检查、lint 和构建 | medium / workspace-write |
 

package/agents/codex/backend-reviewer.toml

@@ -1,11 +1,13 @@
 name = "backend-reviewer"
-description = "只读审查后端与接口变更的契约、权限、数据一致性、事务并发、幂等性、可观测性和测试风险。"
+description = "只读审查后端、接口与数据访问变更的契约兼容、权限、事务并发、幂等性、可观测性和测试风险。"
 model_reasoning_effort = "high"
 sandbox_mode = "read-only"
 developer_instructions = """
 像后端代码所有者一样审查，优先正确性、安全边界和数据完整性。
 先读取适用的 AGENTS.md、规格、后端标准、接口契约、数据模型和完整 diff，再追踪必要的调用方、迁移与测试。
-重点检查输入验证、认证授权、租户隔离、事务边界、并发与竞态、幂等、错误语义、重试、资源释放、日志与指标以及回归测试。
+重点检查输入验证、认证授权、租户隔离、事务边界、并发与竞态、幂等、错误语义、有限重试、资源释放、日志与指标以及回归测试。
+接口变更同时检查字段、枚举、分页、错误码、deprecation 和消费者兼容；数据库与缓存变更检查查询规模、索引、N+1、连接生命周期、Redis 失效与 fail-safe 行为。
+破坏性 schema 变更、回填或数据修复交给 migration reviewer；需要完整攻击路径或供应链判断时交给 security reviewer，避免在本角色重复专项清单。
 不要修改文件，不要执行生产或数据写入，不要把缺少个人偏好的抽象当成问题。
 返回固定结果：status 只能是 completed 或 blocked；finding priority 只能是 P0、P1、P2 或 P3。
 每个 finding 返回 file 与 line、trigger、impact、evidence 和 minimal fix，并明确区分已证实问题、未知项和建议验证。

package/agents/codex/frontend-reviewer.toml

@@ -5,7 +5,8 @@ sandbox_mode = "read-only"
 developer_instructions = """
 像前端代码所有者一样审查，但只报告有证据、可触发且值得修复的问题。
 先读取适用的 AGENTS.md、规格、前端标准、设计系统约束和完整 diff，再检查必要的调用方与测试。
-重点检查行为正确性、状态同步、竞态与取消、错误和加载状态、键盘与屏幕阅读器可用性、组件职责、渲染成本以及测试缺口。
+重点检查行为正确性、状态同步、竞态与取消、loading、error、empty 与 success 状态、键盘与屏幕阅读器可用性、组件职责、渲染成本以及测试缺口。
+检查前端 contract 与真实接口是否漂移，路由、菜单和按钮权限是否被误作服务端授权；涉及运行时交互时要求可复现的浏览器、console 与 network 证据，不能用静态推断冒充真实验收。
 不要修改文件，不要安装依赖，不要把纯风格偏好或无法证明影响的猜测列为 finding。
 返回固定结果：status 只能是 completed 或 blocked；finding priority 只能是 P0、P1、P2 或 P3。
 每个 finding 返回 file 与 line、trigger、impact、evidence 和 minimal fix，并明确区分已证实问题与推断。

package/agents/codex/migration-reviewer.toml

@@ -0,0 +1,14 @@
+name = "migration-reviewer"
+description = "只读审查 schema migration、回填、数据修复、兼容切换与旧路径删除的安全性和可恢复性。"
+model_reasoning_effort = "high"
+sandbox_mode = "read-only"
+developer_instructions = """
+只做迁移审查，不修改文件，不执行数据库或数据写入，不连接生产环境。
+先读取适用的 AGENTS.md、CONTEXT、数据库与兼容性标准、schema diff、migration、回填脚本、数据规模、消费者清单、发布与恢复证据。
+以 Expand → Migrate → Contract 为默认顺序，检查新旧代码与数据的兼容窗口、部署顺序、锁表与长事务、索引构建、默认值和非空约束、大表批处理、限速、checkpoint、可重入、幂等、差异核对和失败样本。
+检查旧写冻结、双写或双读的事实源、消费者迁移、删除前零使用证据，以及 backup restore、rollback 或 forward-fix 是否与真实失败模式匹配。
+不要把本地 schema 校验当成生产可执行证据；生产数据量、隔离级别、执行计划、维护窗口或恢复演练缺失时明确列为 unknown。
+返回固定结果：status 只能是 completed 或 blocked；finding priority 只能是 P0、P1、P2 或 P3。
+每个 finding 返回 file 与 line、phase、trigger、数据量或并发假设、impact、evidence 和 minimal fix，并区分已证实问题、推断和开放问题。
+没有可执行问题时显式返回 no findings；最后列出 unknowns、未覆盖消费者与未执行验证。
+"""

package/agents/codex/security-reviewer.toml

@@ -0,0 +1,13 @@
+name = "security-reviewer"
+description = "只读审查应用、Agent 与供应链变更中的信任边界、权限、敏感数据、注入和特权工具风险。"
+model_reasoning_effort = "high"
+sandbox_mode = "read-only"
+developer_instructions = """
+只做安全审查，不修改文件，不执行外部写入、生产操作或攻击性探测。
+先读取适用的 AGENTS.md、CONTEXT、security standards、威胁模型、完整 diff、配置、契约和拒绝路径测试，再标出 trusted source、untrusted source、transform、sink、数据敏感度与授权点。
+按变更选择最小必要 profile：应用安全检查认证授权、租户隔离、输入验证、XSS、CSRF、SSRF、SQL、shell 与 path 注入、文件上传、Webhook 重放、secrets、PII 和支付边界；Agent 与 Tool 安全检查外部内容到 privileged sink 的 source → transform → sink 路径、工具组合权限、持久记忆和 prompt injection；供应链安全检查依赖与 lockfile、CI action、Plugin、MCP、构建脚本的 provenance、版本固定、最小权限、更新和撤销证据。
+不要把已连接工具等同于授权，不要仅依赖 prompt 过滤或模型自律宣称风险已消除；未命中的 profile 不展开通用清单。
+返回固定结果：status 只能是 completed 或 blocked；finding priority 只能是 P0、P1、P2 或 P3。
+每个 finding 返回 file 与 line、profile、source、transform、sink、trigger、impact、evidence 和 minimal fix，并区分已证实问题、推断和开放问题。
+没有可执行问题时显式返回 no findings；最后列出 unknowns、未验证边界与未执行验证，不把未覆盖范围写成通过。
+"""

package/docs/agent-authoring.md

@@ -48,6 +48,21 @@ Agent 不应成为完整工作流、项目规范副本或长期人格。实现
 
 只读 Agent 返回事实、可定位证据、推断、未知项和建议下一步。Reviewer 使用 `completed | blocked` 状态和 P0–P3 finding，并返回 trigger、impact、evidence 与 minimal fix。Architecture designer 固定返回 current state、options、recommendation、migration slices、validation、decisions 与 unknowns。Verifier 使用 `passed | failed | blocked`，返回实际命令、退出码、关键输出、未执行项、执行前后工作树、环境限制和 `workspace_change`；新增 tracked diff 时不得返回 passed。不得把建议写成已经验证的结论。
 
+## 默认路由
+
+主 agent 按任务的主要风险面选择最少数量的角色；同一 finding 不交给多个 reviewer 重复判断。Agent 不可用时由主 agent 串行执行相同检查，并保留相同证据与失败标准。
+
+| 主任务类型 | Agent | 不应代替 |
+| --- | --- | --- |
+| 模块 Interface、依赖方向、数据流与迁移方案比较 | `architecture-designer` | diff finding 或实现 |
+| 后端、接口、事务、查询与缓存审查 | `backend-reviewer` | 专项安全或 migration 审查 |
+| 前端状态、交互、可访问性与浏览器证据审查 | `frontend-reviewer` | 真实浏览器验收或服务端授权 |
+| 应用、Agent、Tool 与供应链安全审查 | `security-reviewer` | 渗透测试或外部 mutation |
+| schema、回填、数据修复与兼容切换审查 | `migration-reviewer` | 数据库写入或生产执行 |
+| 执行已有测试、typecheck、lint 与 build | `test-verifier` | 测试设计审查或实现修复 |
+
+普通代码定位继续使用内置 `explorer`，实现继续使用内置 `worker`。测试质量由适用 reviewer 或 `code-review` 的 Standards 轴判断，不能把 `test-verifier` 扩成既执行又评价自身证据的万能角色。
+
 ## 双宿主策略
 
 Skills 保持 Codex 与 Claude Code 共用单源。Agent 配置是宿主专用适配，不强求两种宿主使用相同格式、模型名或权限语义。真正支持 Claude Code Agent 时，在独立宿主目录中实现并建立能力映射，不复制 Skill 工作流。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@netpilot/skills",
-  "version": "0.4.0",
+  "version": "0.7.0",
   "description": "面向 Codex 与 Claude Code 的中文工程协作 skills 与可选 Codex agents",
   "keywords": [
     "codex",

package/scripts/sync.mjs

@@ -24,6 +24,10 @@ const HOST_DESTINATIONS = {
 };
 
 const CODEX_AGENT_DESTINATION = [".codex", "agents"];
+const CURRENT_STATE_DESTINATION = [".agents", ".state", "skills-installer"];
+const LEGACY_STATE_DESTINATION = [".netpilot-skills"];
+const LAYOUT_LOCK_DIRECTORY = [".agents", ".state"];
+const LAYOUT_LOCK_NAME = "skills-installer.layout.lock";
 
 const ALL_HOSTS = Object.freeze(Object.keys(HOST_DESTINATIONS));
 const ALL_COMPONENTS = Object.freeze(["skills", "agents"]);
@@ -354,6 +358,100 @@ async function assertSafeHomeRoot(homeDir) {
   ]);
 }
 
+function resolveStatePaths(homeDir) {
+  const currentStateDir = path.join(homeDir, ...CURRENT_STATE_DESTINATION);
+  const legacyStateDir = path.join(homeDir, ...LEGACY_STATE_DESTINATION);
+  return {
+    currentStateDir,
+    currentManifestPath: path.join(currentStateDir, "manifest.json"),
+    legacyStateDir,
+    legacyManifestPath: path.join(legacyStateDir, "manifest.json"),
+    layoutLockDir: path.join(homeDir, ...LAYOUT_LOCK_DIRECTORY),
+  };
+}
+
+function stateLayoutConflict(homeDir, reason, targetPath = homeDir) {
+  return new SyncConflictError([
+    {
+      host: "state",
+      component: "layout",
+      assetName: "state-layout",
+      skillName: "state-layout",
+      relativePath: ".",
+      targetPath,
+      action: "conflict",
+      reason,
+    },
+  ]);
+}
+
+async function inspectStateDirectory(homeDir, targetPath) {
+  const ancestor = await inspectAncestorPath(homeDir, targetPath);
+  if (!ancestor.safe) {
+    throw stateLayoutConflict(
+      homeDir,
+      `${ancestor.reason}：${ancestor.path}`,
+      targetPath,
+    );
+  }
+  try {
+    const stats = await lstat(targetPath);
+    if (stats.isSymbolicLink() || !stats.isDirectory()) {
+      throw stateLayoutConflict(
+        homeDir,
+        "状态路径必须是非符号链接目录",
+        targetPath,
+      );
+    }
+    return {
+      exists: true,
+      path: targetPath,
+      identity: { dev: stats.dev, ino: stats.ino },
+    };
+  } catch (error) {
+    if (error.code === "ENOENT") return { exists: false, path: targetPath };
+    throw error;
+  }
+}
+
+function sameStateDirectoryIdentity(left, right) {
+  return left?.dev === right?.dev && left?.ino === right?.ino;
+}
+
+async function inspectStateLayout(homeDir, paths = resolveStatePaths(homeDir)) {
+  const [current, legacy] = await Promise.all([
+    inspectStateDirectory(homeDir, paths.currentStateDir),
+    inspectStateDirectory(homeDir, paths.legacyStateDir),
+  ]);
+  if (current.exists && legacy.exists) {
+    const legacyEntries = await readdir(legacy.path);
+    const latestLegacy = await inspectStateDirectory(homeDir, legacy.path);
+    if (
+      legacyEntries.length === 0 &&
+      latestLegacy.exists &&
+      sameStateDirectoryIdentity(legacy.identity, latestLegacy.identity)
+    ) {
+      return {
+        kind: "current-with-empty-legacy",
+        current,
+        legacy: latestLegacy,
+        paths,
+      };
+    }
+    throw stateLayoutConflict(
+      homeDir,
+      "新旧状态目录同时存在，拒绝自动合并 ownership",
+      paths.currentStateDir,
+    );
+  }
+  return {
+    kind: current.exists ? "current" : legacy.exists ? "legacy" : "fresh",
+    current,
+    legacy,
+    paths,
+  };
+}
+
 function parseLockRecord(content) {
   const trimmed = content.trim();
   if (/^[1-9][0-9]*$/u.test(trimmed)) {
@@ -411,9 +509,13 @@ async function moveLockForCompare({ lockPath, expectedContent, stateDir, purpose
   throw error;
 }
 
-async function acquireSyncLock({ homeDir, stateDir, transactionHooks = {} }) {
-  await mkdir(stateDir, { recursive: true });
-  const stateSafety = await inspectAncestorPath(homeDir, stateDir);
+async function acquireSyncLock({
+  homeDir,
+  stateDir,
+  lockName = "sync.lock",
+  beforeLockPublish,
+}) {
+  let stateSafety = await inspectAncestorPath(homeDir, stateDir);
   if (!stateSafety.safe) {
     throw new SyncConflictError([
       {
@@ -421,15 +523,24 @@ async function acquireSyncLock({ homeDir, stateDir, transactionHooks = {} }) {
         component: "lock",
         assetName: "sync",
         skillName: "sync",
-        relativePath: "sync.lock",
-        targetPath: path.join(stateDir, "sync.lock"),
+        relativePath: lockName,
+        targetPath: path.join(stateDir, lockName),
         action: "conflict",
         reason: `${stateSafety.reason}：${stateSafety.path}`,
       },
     ]);
   }
+  await mkdir(stateDir, { recursive: true });
+  stateSafety = await inspectAncestorPath(homeDir, stateDir);
+  if (!stateSafety.safe) {
+    throw stateLayoutConflict(
+      homeDir,
+      `${stateSafety.reason}：${stateSafety.path}`,
+      stateDir,
+    );
+  }
 
-  const lockPath = path.join(stateDir, "sync.lock");
+  const lockPath = path.join(stateDir, lockName);
   const owner = randomUUID();
   const recordContent = `${JSON.stringify({
     schemaVersion: 1,
@@ -437,7 +548,10 @@ async function acquireSyncLock({ homeDir, stateDir, transactionHooks = {} }) {
     owner,
     createdAt: new Date().toISOString(),
   })}\n`;
-  const stagedLockPath = path.join(stateDir, `sync-lock-${owner}.tmp`);
+  const stagedLockPath = path.join(
+    stateDir,
+    `${lockName.replaceAll(".", "-")}-${owner}.tmp`,
+  );
   await writeFile(stagedLockPath, recordContent, { encoding: "utf8", flag: "wx" });
   if ((await readFile(stagedLockPath, "utf8")) !== recordContent) {
     await rm(stagedLockPath, { force: true });
@@ -445,7 +559,7 @@ async function acquireSyncLock({ homeDir, stateDir, transactionHooks = {} }) {
   }
 
   try {
-    await transactionHooks.beforeLockPublish?.();
+    await beforeLockPublish?.();
     for (let attempt = 0; attempt < 3; attempt += 1) {
       try {
         await link(stagedLockPath, lockPath);
@@ -1303,6 +1417,111 @@ async function applyOperationsTransactional({
   }
 }
 
+async function migrateLegacyState({
+  homeDir,
+  paths,
+  transactionHooks,
+}) {
+  let syncLock = await acquireSyncLock({
+    homeDir,
+    stateDir: paths.legacyStateDir,
+    beforeLockPublish: transactionHooks.beforeLockPublish,
+  });
+  let moved = false;
+  try {
+    const freshLayout = await inspectStateLayout(homeDir, paths);
+    if (freshLayout.kind !== "legacy") {
+      throw stateLayoutConflict(
+        homeDir,
+        "获取旧状态锁后布局发生变化，拒绝继续迁移",
+        paths.legacyStateDir,
+      );
+    }
+    const lockedSourceIdentity = freshLayout.legacy.identity;
+    const legacyManifest = await inspectTarget(paths.legacyManifestPath);
+    if (!legacyManifest.exists || !legacyManifest.regularFile) {
+      throw stateLayoutConflict(
+        homeDir,
+        "旧状态目录缺少可信的普通 manifest.json",
+        paths.legacyManifestPath,
+      );
+    }
+    await readManifest(paths.legacyManifestPath);
+    await transactionHooks.beforeStateMigrationRename?.();
+    const beforeRename = await inspectStateLayout(homeDir, paths);
+    if (
+      beforeRename.kind !== "legacy" ||
+      !sameStateDirectoryIdentity(
+        lockedSourceIdentity,
+        beforeRename.legacy.identity,
+      )
+    ) {
+      throw stateLayoutConflict(
+        homeDir,
+        "旧状态目录身份在迁移提交前发生变化",
+        paths.currentStateDir,
+      );
+    }
+    try {
+      await rename(paths.legacyStateDir, paths.currentStateDir);
+    } catch (error) {
+      if (error.code === "EXDEV") {
+        throw stateLayoutConflict(
+          homeDir,
+          "新旧状态目录不在同一文件系统，拒绝退化为非原子复制",
+          paths.currentStateDir,
+        );
+      }
+      if (["EEXIST", "ENOTEMPTY"].includes(error.code)) {
+        throw stateLayoutConflict(
+          homeDir,
+          "新状态目录在原子迁移前已出现",
+          paths.currentStateDir,
+        );
+      }
+      throw error;
+    }
+    moved = true;
+    syncLock = {
+      ...syncLock,
+      stateDir: paths.currentStateDir,
+      lockPath: path.join(paths.currentStateDir, "sync.lock"),
+    };
+    const migratedLayout = await inspectStateLayout(homeDir, paths);
+    if (
+      migratedLayout.kind !== "current" ||
+      !sameStateDirectoryIdentity(
+        lockedSourceIdentity,
+        migratedLayout.current.identity,
+      )
+    ) {
+      const error = new Error("状态目录迁移后的目标身份不一致");
+      error.preserveEvidence = true;
+      throw error;
+    }
+    const migratedManifest = await inspectTarget(paths.currentManifestPath);
+    if (
+      !migratedManifest.regularFile ||
+      migratedManifest.hash !== legacyManifest.hash
+    ) {
+      const error = new Error("状态目录迁移后 manifest digest 不一致");
+      error.preserveEvidence = true;
+      throw error;
+    }
+    await transactionHooks.afterStateMigrationRename?.();
+    return syncLock;
+  } catch (error) {
+    try {
+      await releaseSyncLock(syncLock);
+    } catch (releaseError) {
+      error.releaseError = releaseError;
+      error.preserveEvidence = true;
+    }
+    if (moved) error.stateMigrationCommitted = true;
+    throw error;
+  }
+}
+
 export async function syncSkills({
   rootDir,
   homeDir,
@@ -1329,14 +1548,114 @@ export async function syncSkills({
   const resolvedRoot = path.resolve(rootDir);
   const resolvedHome = path.resolve(homeDir);
   await assertSafeHomeRoot(resolvedHome);
-  const manifestPath = path.join(resolvedHome, ".netpilot-skills", "manifest.json");
-  const stateDir = path.dirname(manifestPath);
-  const syncLock = apply
-    ? await acquireSyncLock({ homeDir: resolvedHome, stateDir, transactionHooks })
-    : null;
+  const statePaths = resolveStatePaths(resolvedHome);
+  let stateLayout = await inspectStateLayout(resolvedHome, statePaths);
+  let stateDir =
+    stateLayout.kind === "legacy"
+      ? statePaths.legacyStateDir
+      : statePaths.currentStateDir;
+  let manifestPath =
+    stateLayout.kind === "legacy"
+      ? statePaths.legacyManifestPath
+      : statePaths.currentManifestPath;
+  let stateMigration =
+    stateLayout.kind === "legacy"
+      ? {
+          action: "move",
+          from: statePaths.legacyStateDir,
+          to: statePaths.currentStateDir,
+        }
+      : null;
+  let stateRepair =
+    stateLayout.kind === "current-with-empty-legacy"
+      ? {
+          action: "remove-empty-legacy-state",
+          target: statePaths.legacyStateDir,
+        }
+      : null;
+  let layoutLock = null;
+  let syncLock = null;
   let syncError = null;
 
   try {
+    if (apply) {
+      layoutLock = await acquireSyncLock({
+        homeDir: resolvedHome,
+        stateDir: statePaths.layoutLockDir,
+        lockName: LAYOUT_LOCK_NAME,
+        beforeLockPublish: transactionHooks.beforeLayoutLockPublish,
+      });
+      stateLayout = await inspectStateLayout(resolvedHome, statePaths);
+      if (stateLayout.kind === "current-with-empty-legacy") {
+        stateRepair = {
+          action: "remove-empty-legacy-state",
+          target: statePaths.legacyStateDir,
+        };
+        const expectedCurrentIdentity = stateLayout.current.identity;
+        try {
+          await rmdir(statePaths.legacyStateDir);
+        } catch (error) {
+          if (["ENOTEMPTY", "EEXIST"].includes(error.code)) {
+            throw stateLayoutConflict(
+              resolvedHome,
+              "空旧状态目录在清理前出现内容，拒绝继续",
+              statePaths.legacyStateDir,
+            );
+          }
+          throw error;
+        }
+        const repairedLayout = await inspectStateLayout(
+          resolvedHome,
+          statePaths,
+        );
+        if (
+          repairedLayout.kind !== "current" ||
+          !sameStateDirectoryIdentity(
+            expectedCurrentIdentity,
+            repairedLayout.current.identity,
+          )
+        ) {
+          throw stateLayoutConflict(
+            resolvedHome,
+            "清理旧状态残留后当前状态目录身份发生变化",
+            statePaths.currentStateDir,
+          );
+        }
+        stateLayout = repairedLayout;
+      }
+      if (stateLayout.kind === "legacy") {
+        stateMigration = {
+          action: "move",
+          from: statePaths.legacyStateDir,
+          to: statePaths.currentStateDir,
+        };
+        syncLock = await migrateLegacyState({
+          homeDir: resolvedHome,
+          paths: statePaths,
+          transactionHooks,
+        });
+      } else {
+        syncLock = await acquireSyncLock({
+          homeDir: resolvedHome,
+          stateDir: statePaths.currentStateDir,
+          beforeLockPublish: transactionHooks.beforeLockPublish,
+        });
+      }
+      const lockedLayout = await inspectStateLayout(
+        resolvedHome,
+        statePaths,
+      );
+      if (lockedLayout.kind !== "current") {
+        throw stateLayoutConflict(
+          resolvedHome,
+          "获取同步锁后项目状态布局发生变化，拒绝继续",
+          statePaths.currentStateDir,
+        );
+      }
+      stateLayout = lockedLayout;
+      stateDir = statePaths.currentStateDir;
+      manifestPath = statePaths.currentManifestPath;
+    }
     if (syncLock) await transactionHooks.afterLockAcquired?.();
   const stateSafety = await inspectAncestorPath(resolvedHome, stateDir);
   if (!stateSafety.safe) {
@@ -1468,7 +1787,12 @@ export async function syncSkills({
   const result = {
     mode: apply ? "apply" : "dry-run",
     homeDir: resolvedHome,
-    manifestPath,
+    manifestPath: statePaths.currentManifestPath,
+    ...(manifestPath !== statePaths.currentManifestPath
+      ? { sourceManifestPath: manifestPath }
+      : {}),
+    ...(stateMigration ? { stateMigration } : {}),
+    ...(stateRepair ? { stateRepair } : {}),
     operations,
     conflicts,
   };
@@ -1488,18 +1812,21 @@ export async function syncSkills({
     syncError = error;
     throw error;
   } finally {
-    if (syncLock) {
+    let releaseFailure = null;
+    for (const lock of [syncLock, layoutLock]) {
+      if (!lock) continue;
       try {
-        await releaseSyncLock(syncLock);
+        await releaseSyncLock(lock);
       } catch (releaseError) {
         if (syncError) {
           syncError.releaseError = releaseError;
           syncError.preserveEvidence = true;
         } else {
-          throw releaseError;
+          releaseFailure ??= releaseError;
         }
       }
     }
+    if (!syncError && releaseFailure) throw releaseFailure;
   }
 }
 
@@ -1518,6 +1845,16 @@ Claude Code 目标：~/.claude/skills（选择 --host claude 时默认只安装
 }
 
 function printPlan(result) {
+  if (result.stateRepair) {
+    console.log(
+      `[remove-empty] state ${result.stateRepair.target}`,
+    );
+  }
+  if (result.stateMigration) {
+    console.log(
+      `[move] state ${result.stateMigration.from} -> ${result.stateMigration.to}`,
+    );
+  }
   for (const operation of result.operations) {
     const reason = operation.reason ? `（${operation.reason}）` : "";
     const component = operation.component === "skills" ? "skills" : operation.component;