flower-trellis 0.6.5 → 0.6.7

package/src/commands/worktree.js

@@ -1,6 +1,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
 import { ENHANCEMENTS_ROOT } from "../lib/paths.js";
 import {
   resolveTrellisPythonCommand,
@@ -17,8 +18,9 @@ const VALUE_OPTIONS = new Set([
   "--task-description",
   "--developer",
   "--plan-fingerprint",
+  "--source",
 ]);
-const BOOLEAN_OPTIONS = new Set(["--json", "--dry-run", "--yes", "--inherit-route-prefs"]);
+const BOOLEAN_OPTIONS = new Set(["--json", "--dry-run", "--yes", "--inherit-route-prefs", "--inherit-flower"]);
 
 /**
  * 识别 worktree 根级或子命令级帮助请求。
@@ -64,9 +66,12 @@ needs-migration 状态选择下一步。`);
 用法:
   flower-trellis worktree prepare [--target <dir>] [--developer <name>]
                                    [--inherit-route-prefs] [--json]
+                                   [--inherit-flower --source <dir>]
 
 prepare 不创建 Git worktree，只补齐目标分支本地的 developer、runtime 和 registry 状态。
-仅在确实需要继承当前控制 worktree 的个人路由偏好时使用 --inherit-route-prefs。`);
+仅在确实需要继承当前控制 worktree 的个人路由偏好时使用 --inherit-route-prefs。
+Flower 记录缺失时，用 --inherit-flower --source <同仓 worktree> 补齐可验证的独立安装信息。
+即使 Trellis 已 ready-local，也可以运行此补配；已有目标记录不会被覆盖。`);
     return;
   }
   if (command === "migrate") {
@@ -96,7 +101,9 @@ prepare 不创建 Git worktree，只补齐目标分支本地的 developer、runt
     git worktree add <target> <existing-branch>
     flower-trellis worktree status --target <target>
   若 status 返回 needs-prepare，再运行:
-    flower-trellis worktree prepare --target <target> [--developer <name>]`);
+    flower-trellis worktree prepare --target <target> [--developer <name>]
+  create 自动将缺失的 Flower 安装信息纳入计划；目标内容不匹配时停止并回滚。
+  已有 worktree 缺少 Flower 记录时，使用 prepare --inherit-flower --source <source>。`);
     return;
   }
   if (command === "remove") {
@@ -177,6 +184,15 @@ export function parseWorktreeArgs(args) {
   if (command !== "prepare" && options.has("--inherit-route-prefs")) {
     throw new Error("--inherit-route-prefs 只用于 worktree prepare");
   }
+  if (command !== "prepare" && (options.has("--inherit-flower") || options.has("--source"))) {
+    throw new Error("--inherit-flower 和 --source 只用于 worktree prepare");
+  }
+  if (options.has("--inherit-flower") && !options.has("--source")) {
+    throw new Error("--inherit-flower 需要 --source 指定同仓来源");
+  }
+  if (options.has("--source") && !options.has("--inherit-flower")) {
+    throw new Error("--source 需要显式 --inherit-flower");
+  }
   return { command, options, json: options.has("--json") };
 }
 
@@ -194,7 +210,7 @@ export function worktreeEngineArgs(parsed, target, source) {
     args.push("--source", source, "--target", target);
   } else {
     args.push("--target", target);
-    if (parsed.command === "prepare" && parsed.options.has("--inherit-route-prefs")) {
+    if (parsed.command === "prepare" && parsed.options.has("--inherit-route-prefs") && !parsed.options.has("--source")) {
       args.push("--source", source);
     }
   }
@@ -244,6 +260,17 @@ export function printWorktreeResult(payload) {
   if (payload.localStateTransfer?.routePreferences?.action) {
     console.log(`route preferences: ${payload.localStateTransfer.routePreferences.action}`);
   }
+  if (payload.localStateTransfer?.flower) {
+    const flower = payload.localStateTransfer.flower;
+    console.log(`flower transfer: ${flower.action}${flower.reason ? ` (${flower.reason})` : ""}`);
+    if (flower.source) console.log(`flower source: ${flower.source}`);
+    if (flower.paths?.length) console.log(`flower paths: ${flower.paths.join(", ")}`);
+    if (flower.validationPending) console.log("flower validation: checkout 后核验目标内容，失败回滚创建");
+  }
+  if (payload.flower) {
+    console.log(`flower: ${payload.flower.installation}; version: ${payload.flower.version || "unknown"}`);
+    if (payload.flower.reason) console.log(`flower reason: ${payload.flower.reason}`);
+  }
   if (payload.requiresConfirmation && payload.confirmation?.fingerprint) {
     console.log(`confirmation: 使用 --yes --plan-fingerprint ${payload.confirmation.fingerprint}`);
   }
@@ -284,7 +311,11 @@ export async function worktree(ctx) {
     [...invocation.args, script, ...worktreeEngineArgs(parsed, ctx.target, source)],
     {
       cwd: source,
-      env: process.env,
+      env: {
+        ...process.env,
+        FLOWER_WORKTREE_NODE: process.execPath,
+        FLOWER_WORKTREE_HELPER: fileURLToPath(new URL("../lib/worktree-flower-state.js", import.meta.url)),
+      },
       encoding: "utf8",
       windowsHide: true,
     },

package/src/lib/apply-enhancements.js

@@ -6,7 +6,7 @@ import { formatPatchDiagnostic } from "./patch-conflicts.js";
  * 叠加强化包的兼容 facade。
  *
  * 成功状态统一由 Plugin Runtime 写入 `.flower/`；旧
- * `.trellis/.flower-manifest.json` 只作为迁移证据读取，不再更新。
+ * `.trellis/.flower-manifest.json` 作为迁移证据读取，迁移成功后由同一事务删除。
  *
  * @param {string} target 目标项目根
  * @param {{variant?:string|null,skills?:string[],dryRun?:boolean}} [opts] 兼容参数

package/src/lib/manifest.js

@@ -4,13 +4,7 @@ import crypto from "node:crypto";
 import { ProjectStore } from "../plugin/state/project-store.js";
 
 /**
- * flower-trellis 自己的安装清单。
- *
- * 记录「flower 上一次为该项目铺设了哪些强化文件」,使升级(如 0.5/old → 0.6)时
- * 能精确删除当前变体不再包含的过期 skill / command —— 只删自己铺过的路径,
- * 绝不误删用户或 Trellis 本体的文件。
- *
- * 放在 .trellis/ 下,随项目的 Trellis 生命周期存在(uninstall 删 .trellis 时一并消失)。
+ * 旧安装清单的兼容读取入口；成功迁移后删除，现代状态由 ProjectStore 管理。
  */
 const MANIFEST_REL = path.join(".trellis", ".flower-manifest.json");
 const LEGACY_UPDATE_CHECK_CACHE_REL = path.join(".trellis", ".flower-update-check.tmp");
@@ -148,7 +142,7 @@ function normalizeLastRemote(value) {
  * @param {object|null|undefined} value 原始 updateCheck 字段
  * @returns {{enabled:boolean,policy:string,intervalHours:number}} 归一化后的策略
  */
-function normalizeUpdateCheckPolicy(value) {
+export function normalizeUpdateCheckPolicy(value) {
   const raw = value && typeof value === "object" ? value : {};
   const policy = UPDATE_POLICIES.has(raw.policy) ? raw.policy : DEFAULT_UPDATE_CHECK.policy;
   const interval = Number(raw.intervalHours);
@@ -374,18 +368,51 @@ export function readManifest(target) {
  * @returns {{status:"missing"|"valid"|"corrupt",manifest:object|null,error?:Error}} 迁移证据
  */
 export function readLegacyManifestStatus(target) {
-  const filePath = manifestPath(target);
-  try {
-    const text = fs.readFileSync(filePath, "utf8");
-    const manifest = JSON.parse(text);
-    if (!isPlainObject(manifest)) {
-      return { status: "corrupt", manifest: null, error: new Error("旧 manifest 必须是对象") };
+  const result = readJsonFileStatus(manifestPath(target));
+  if (result.status === "valid" && !isPlainObject(result.value)) {
+    return { status: "corrupt", manifest: null, error: new Error("旧 manifest 必须是对象") };
+  }
+  return { status: result.status, manifest: result.value, ...(result.error ? { error: result.error } : {}) };
+}
+
+/**
+ * 规划旧清单退出所需的配置写入及文件删除，保持 preflight 只读。
+ *
+ * @param {string} target 项目根
+ * @returns {Array<{path:string,content:Buffer|null}>} 固定目标及内容，null 表示删除
+ */
+export function planLegacyManifestMigration(target) {
+  const legacy = readLegacyManifestStatus(target);
+  if (legacy.status === "missing") return [];
+  if (legacy.status === "corrupt") throw new Error(`旧 flower manifest 损坏，拒绝删除:${manifestPath(target)}`, { cause: legacy.error });
+  const writes = [];
+  const settings = readSettingsStatus(target);
+  if (settings.status === "corrupt") throw new Error(`update-check settings 损坏，拒绝迁移:${settingsPath(target)}`, { cause: settings.error });
+  const updateCheck = legacy.manifest.updateCheck;
+  if (settings.status === "missing" && hasAnyOwn(updateCheck, UPDATE_CHECK_POLICY_KEYS)) {
+    writes.push({
+      path: ".flower/settings.json",
+      content: Buffer.from(JSON.stringify({ schemaVersion: 1, updateCheck: normalizeUpdateCheckPolicy(updateCheck) }, null, 2) + "\n"),
+    });
+  }
+  const cache = readJsonFileStatus(updateCheckCachePath(target));
+  if (cache.status === "corrupt" || (cache.status === "valid" && !isPlainObject(cache.value))) {
+    throw new Error(`update-check cache 损坏，拒绝迁移:${updateCheckCachePath(target)}`);
+  }
+  if (cache.status === "missing") {
+    const oldCache = readJsonFileStatus(path.join(target, LEGACY_UPDATE_CHECK_CACHE_REL));
+    if (oldCache.status === "corrupt" || (oldCache.status === "valid" && !isPlainObject(oldCache.value))) {
+      throw new Error("旧 update-check cache 损坏，拒绝丢失迁移证据");
+    }
+    if (oldCache.status === "valid" || hasLegacyUpdateCheckCache(updateCheck)) {
+      writes.push({
+        path: ".flower/update-check.tmp",
+        content: Buffer.from(JSON.stringify(normalizeUpdateCheckCache(oldCache.value || updateCheck), null, 2) + "\n"),
+      });
     }
-    return { status: "valid", manifest };
-  } catch (error) {
-    if (error?.code === "ENOENT") return { status: "missing", manifest: null };
-    return { status: "corrupt", manifest: null, error };
   }
+  writes.push({ path: ".trellis/.flower-manifest.json", content: null });
+  return writes;
 }
 
 /**
@@ -406,7 +433,7 @@ export function normalizeUpdateCheck(value) {
 /**
  * 读取启动更新检查配置。
  *
- * 返回 manifest 策略与 tmp 运行缓存的合并视图;tmp 不存在时兼容读取旧 manifest 缓存字段。
+ * 返回现代 settings 策略与 tmp 缓存的合并视图，尚未迁移时兼容旧记录。
  *
  * @param {string} target 目标项目根
  * @returns {ReturnType<typeof normalizeUpdateCheck>} 归一化后的配置
@@ -464,27 +491,3 @@ export function writeUpdateCheck(target, patch) {
   }
   return readUpdateCheck(target);
 }
-
-/**
- * 写入 manifest。
- *
- * 若调用方没有显式传入 `updateCheck`,保留目标项目已有策略,避免全装重写时覆盖用户选择。
- * 运行缓存会迁移到 `.flower-update-check.tmp`,不得继续写入 manifest。
- *
- * @param {string} target 目标项目根
- * @param {object} data manifest 新内容
- */
-export function writeManifest(target, data) {
-  const current = readManifest(target);
-  const next = { ...data };
-  if (hasLegacyUpdateCheckCache(current?.updateCheck)) {
-    migrateLegacyUpdateCheckCache(target, current.updateCheck);
-  }
-  if (Object.prototype.hasOwnProperty.call(data, "updateCheck")) {
-    migrateLegacyUpdateCheckCache(target, data.updateCheck);
-    next.updateCheck = normalizeUpdateCheckPolicy(data.updateCheck);
-  } else {
-    next.updateCheck = normalizeUpdateCheckPolicy(current?.updateCheck);
-  }
-  fs.writeFileSync(manifestPath(target), JSON.stringify(next, null, 2) + "\n");
-}

package/src/lib/self-check.js

@@ -572,8 +572,9 @@ export async function buildSelfCheck(target, options = {}) {
   const projectTrellis = readProjectTrellisVersion(absoluteTarget);
   const skillGardenLock = pluginLock?.plugins.find(({ id }) => id === SKILL_GARDEN_PLUGIN_ID);
   const projectFlower = skillGardenLock?.version || (
-    typeof manifest?.flowerVersion === "string" ? manifest.flowerVersion : null
+    typeof manifest?.flowerVersion === "string" && manifest.flowerVersion.trim() ? manifest.flowerVersion : null
   );
+  const flowerVersionSource = skillGardenLock?.version ? "plugin-lock" : projectFlower ? "legacy-manifest" : null;
   const projectOutOfSyncReasons = [];
   if (projectFlower && projectFlower !== currentFlower) {
     projectOutOfSyncReasons.push("flower_version_mismatch");
@@ -602,6 +603,8 @@ export async function buildSelfCheck(target, options = {}) {
     },
     project: {
       flowerVersion: projectFlower,
+      flowerVersionStatus: projectFlower ? "known" : "unknown",
+      flowerVersionSource,
       trellisVersion: projectTrellis,
       manifestPresent: Boolean(manifest),
       pluginStatePresent: Boolean(pluginLock && pluginState),
@@ -689,8 +692,8 @@ export async function buildSelfCheck(target, options = {}) {
     }
     return {
       ...base,
-      status: "skipped",
-      reason: "interval_not_elapsed",
+      status: projectFlower ? "skipped" : "project_unknown",
+      reason: projectFlower ? "interval_not_elapsed" : "project_flower_version_unknown",
       remote: { ...base.remote, tags, fromCache: true, skipped: true },
     };
   }
@@ -744,7 +747,8 @@ export async function buildSelfCheck(target, options = {}) {
     }
     return {
       ...resultBase,
-      status: remoteStatus,
+      status: projectFlower ? remoteStatus : "project_unknown",
+      reason: projectFlower ? null : "project_flower_version_unknown",
       remote: { ...resultBase.remote, tags },
     };
   }

package/src/lib/worktree-flower-state.js

@@ -0,0 +1,347 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import semver from "semver";
+import { REQUIRED_IGNORE_RULES } from "../plugin/state/project-store.js";
+import { validatePluginsFile, validatePluginLock, validatePluginState } from "../plugin/schemas/project-files.js";
+import { assertSafePosixRelativePath } from "../plugin/schemas/shared.js";
+import { stringifyCanonicalJson } from "../plugin/integrity/canonical-json.js";
+import { classifyLockReachability } from "../plugin/lock-reachability.js";
+import { contentSelectionsEqual } from "../plugin/content-selection.js";
+import { hashContent, hashDirectoryIfExists } from "../plugin/install/content-hash.js";
+import { assertPluginStateMatches } from "../plugin/install/state-validation.js";
+import { normalizeUpdateCheckPolicy } from "./manifest.js";
+
+const RECORDS = ["plugins.json", "plugin-lock.json", "state.json"];
+const FILES = [...RECORDS, "settings.json"];
+
+/** 构造含稳定原因和路径的继承错误。 */
+function failure(reason, message, relative = null) {
+  return Object.assign(new Error(message), { reason, path: relative });
+}
+
+/** 校验完整路径链，拒绝祖先目录和末级软链接。 */
+function ordinaryPath(root, relative) {
+  assertSafePosixRelativePath(relative, "worktree Flower 路径");
+  const parts = relative.split("/");
+  let current = path.resolve(root);
+  for (let index = -1; index < parts.length; index += 1) {
+    if (index >= 0) current = path.join(current, parts[index]);
+    try {
+      const stat = fs.lstatSync(current);
+      if (stat.isSymbolicLink() || (index < parts.length - 1 && !stat.isDirectory())) {
+        throw failure("flower-path-conflict", `Flower 路径不能包含软链或非目录:${relative}`, relative);
+      }
+    } catch (error) {
+      if (error.code === "ENOENT") break;
+      throw error;
+    }
+  }
+  return path.join(root, ...parts);
+}
+
+/** 只读普通文件，缺失与损坏分开处理。 */
+function readText(root, relative) {
+  const file = ordinaryPath(root, relative);
+  try {
+    if (!fs.lstatSync(file).isFile()) throw failure("flower-path-conflict", `Flower 记录必须是普通文件:${relative}`, relative);
+    return fs.readFileSync(file, "utf8");
+  } catch (error) {
+    if (error.code === "ENOENT") return null;
+    throw error;
+  }
+}
+
+/** 执行只读 Git 查询，失败不能解释为缺少安装记录。 */
+function git(root, args) {
+  const result = spawnSync("git", ["-C", root, ...args], { encoding: "utf8", timeout: 10000 });
+  if (result.error || result.status !== 0) throw failure("flower-git-error", `无法查询 Flower 所属 Git 仓库:${result.error?.message || result.stderr}`);
+  return result.stdout;
+}
+
+/** 从目标 base commit 读取普通 blob，不创建临时 checkout。 */
+function readBaseText(source, commit, relative) {
+  const parts = relative.split("/");
+  for (let length = 1; length <= parts.length; length += 1) {
+    const entry = git(source, ["ls-tree", "-z", commit, "--", parts.slice(0, length).join("/")]);
+    if (!entry) return null;
+    const mode = entry.slice(0, 6);
+    if ((length < parts.length && mode !== "040000") || (length === parts.length && !["100644", "100755"].includes(mode))) {
+      throw failure("flower-path-conflict", `base 中的 Flower 路径不是普通文件:${relative}`, relative);
+    }
+  }
+  return git(source, ["show", `${commit}:${relative}`]);
+}
+
+/** 读取白名单记录及其原始字节；用于指纹检测未提交记录变化。 */
+function snapshot(root, source, baseCommit) {
+  const read = baseCommit ? (relative) => readBaseText(source, baseCommit, relative) : (relative) => readText(root, relative);
+  const texts = Object.fromEntries(FILES.map((name) => [name, read(`.flower/${name}`)]));
+  if (read(".flower/trellis-control.json") !== null) throw failure("flower-control-active", "Flower 来源或目标处于禁用/恢复状态，不能继承安装记录", ".flower/trellis-control.json");
+  const values = {};
+  for (const [name, text] of Object.entries(texts)) {
+    if (text === null) { values[name] = null; continue; }
+    try {
+      values[name] = JSON.parse(text);
+    } catch {
+      throw failure("flower-record-invalid", `Flower 安装状态 JSON 损坏:.flower/${name}`, `.flower/${name}`);
+    }
+  }
+  for (const [name, validate] of [["plugins.json", validatePluginsFile], ["plugin-lock.json", validatePluginLock], ["state.json", validatePluginState]]) {
+    if (texts[name] !== null) validate(values[name]);
+  }
+  if (texts["settings.json"] !== null) {
+    const settings = values["settings.json"];
+    if (!settings || settings.schemaVersion !== 1 || !settings.updateCheck || typeof settings.updateCheck !== "object" || Array.isArray(settings.updateCheck)) {
+      throw failure("flower-settings-invalid", "Flower settings 结构无效", ".flower/settings.json");
+    }
+  }
+  return { texts, values };
+}
+
+/** 验证完整安装集合及可选的当前内容，不访问包缓存或远端。 */
+function validateInstallation(root, values, content = true) {
+  const declarations = values["plugins.json"].plugins;
+  const lock = values["plugin-lock.json"];
+  const state = values["state.json"];
+  const equalIds = (left, right) => JSON.stringify([...left].sort()) === JSON.stringify([...right].sort());
+  const reachability = classifyLockReachability(declarations, lock);
+  if (!equalIds(declarations.map(({ id }) => id), lock.roots) || reachability.missingIds.size || reachability.orphanIds.size ||
+      !equalIds(lock.plugins.map(({ id }) => id), state.plugins.map(({ id }) => id))) {
+    throw failure("flower-installation-conflict", "Flower 声明、lock 与 state 的插件集合冲突", ".flower/state.json");
+  }
+  for (const locked of lock.plugins) {
+    const applied = state.plugins.find(({ id }) => id === locked.id);
+    const declaration = declarations.find(({ id }) => id === locked.id);
+    if (applied.version !== locked.version || !contentSelectionsEqual(applied.contentSelection, locked.contentSelection) ||
+        (declaration && (!semver.satisfies(locked.version, declaration.version) ||
+          !contentSelectionsEqual(declaration.contentSelection, locked.contentSelection) ||
+          (declaration.platforms?.length && !equalIds(declaration.platforms, applied.platforms))))) {
+      throw failure("flower-installation-conflict", `Flower 安装约束冲突:${locked.id}`, ".flower/state.json");
+    }
+    for (const [id, range] of Object.entries(locked.dependencies)) {
+      if (!semver.satisfies(lock.plugins.find((entry) => entry.id === id).version, range)) {
+        throw failure("flower-installation-conflict", `Flower 依赖版本冲突:${id}`, ".flower/plugin-lock.json");
+      }
+    }
+    if (!content) continue;
+    if (locked.compatibility.trellis) {
+      const version = readText(root, ".trellis/.version")?.trim();
+      if (!version || !semver.satisfies(version, locked.compatibility.trellis)) {
+        throw failure("flower-trellis-incompatible", `目标 Trellis 版本不满足 Plugin 兼容范围:${locked.id}`, ".trellis/.version");
+      }
+    }
+    for (const relative of [...applied.paths.map((entry) => entry.path), ...applied.patches.map((entry) => entry.target)]) ordinaryPath(root, relative);
+    assertPluginStateMatches(root, locked, applied);
+    if (locked.source.type === "local") {
+      const local = ordinaryPath(root, locked.source.reference);
+      if (hashDirectoryIfExists(local) === null) throw failure("flower-local-source-missing", `目标缺少本地 Plugin 来源:${locked.source.reference}`, locked.source.reference);
+    }
+  }
+}
+
+/** 构造内部载荷和公开计划，完整目标校验在真实 checkout 后执行。 */
+function transfer(input) {
+  const { source, target, baseCommit = null, sourceDeveloper = null, targetDeveloper = null } = input;
+  if (!baseCommit) {
+    const sourceCommon = fs.realpathSync(git(source, ["rev-parse", "--path-format=absolute", "--git-common-dir"]).trim());
+    const targetCommon = fs.realpathSync(git(target, ["rev-parse", "--path-format=absolute", "--git-common-dir"]).trim());
+    if (sourceCommon !== targetCommon) throw failure("flower-repository-mismatch", "Flower 来源与目标必须属于同一 Git 仓库");
+  }
+  const destination = snapshot(target, source, baseCommit);
+  const complete = RECORDS.every((name) => destination.values[name] !== null);
+  const origin = complete ? null : snapshot(source);
+  const digest = hashContent(stringifyCanonicalJson({ source: path.resolve(source), target: path.resolve(target), sourceDeveloper, targetDeveloper, origin: origin?.texts || null, destination: destination.texts }));
+  const plan = { action: "preserved", source: complete ? null : source, paths: [], digest, validationPending: Boolean(baseCommit), reason: null };
+  if (complete) {
+    validateInstallation(target, destination.values, !baseCommit);
+    return { plan, files: [] };
+  }
+  if (RECORDS.some((name) => origin.values[name] === null)) {
+    return { plan: { ...plan, action: "unavailable", reason: "source-installation-missing" }, files: [] };
+  }
+  validateInstallation(source, origin.values);
+  for (const name of RECORDS) {
+    if (destination.values[name] !== null && stringifyCanonicalJson(destination.values[name]) !== stringifyCanonicalJson(origin.values[name])) {
+      throw failure("flower-installation-conflict", `目标已有 Flower 记录与来源冲突:.flower/${name}`, `.flower/${name}`);
+    }
+  }
+  validateInstallation(target, origin.values, !baseCommit);
+  if (!baseCommit) {
+    for (const locked of origin.values["plugin-lock.json"].plugins.filter((entry) => entry.source.type === "local")) {
+      const relative = locked.source.reference;
+      if (hashDirectoryIfExists(ordinaryPath(source, relative)) !== hashDirectoryIfExists(ordinaryPath(target, relative))) {
+        throw failure("flower-local-source-conflict", `本地 Plugin 来源内容冲突:${relative}`, relative);
+      }
+    }
+  }
+  const files = RECORDS.filter((name) => destination.texts[name] === null).map((name) => ({ path: `.flower/${name}`, content: stringifyCanonicalJson(origin.values[name]) }));
+  if (destination.texts["settings.json"] === null && origin.values["settings.json"] && sourceDeveloper && sourceDeveloper === targetDeveloper) {
+    files.unshift({ path: ".flower/settings.json", content: stringifyCanonicalJson({ schemaVersion: 1, updateCheck: normalizeUpdateCheckPolicy(origin.values["settings.json"].updateCheck) }) });
+  }
+  const ignore = baseCommit ? readBaseText(source, baseCommit, ".flower/.gitignore") : readText(target, ".flower/.gitignore");
+  if (!baseCommit && ignore !== null && destination.texts["state.json"] === null) {
+    const ignored = spawnSync("git", ["-C", target, "check-ignore", "--no-index", "-q", ".flower/state.json"], { timeout: 10000 });
+    if (ignored.error || ignored.status !== 0) throw failure("flower-ignore-conflict", "现有忽略规则未覆盖 .flower/state.json，请先完善目标忽略规则", ".flower/.gitignore");
+  }
+  if (ignore === null) files.unshift({ path: ".flower/.gitignore", content: `${REQUIRED_IGNORE_RULES.join("\n")}\n` });
+  return { plan: { ...plan, action: "inherited", paths: files.map((file) => file.path), digest: hashContent(`${digest}\n${ignore ?? ""}`) }, files };
+}
+
+/**
+ * 只读计算同仓 worktree 的 Flower 继承计划。
+ * @param {object} input 来源、目标、可选 baseCommit 及开发者身份
+ * @returns {object} 不含配置原文的继承计划
+ */
+export function planFlowerTransfer(input) {
+  return transfer(input).plan;
+}
+
+/** 将回执原子存入 engine 提供的项目外临时文件，支持子进程失败后恢复。 */
+function saveReceipt(journal, receipt) {
+  if (!journal) return;
+  const temporary = `${journal}.tmp`;
+  fs.writeFileSync(temporary, JSON.stringify(receipt), { mode: 0o600 });
+  fs.renameSync(temporary, journal);
+}
+
+/**
+ * 仅清理回执中仍为本操作所创建且未被修改的文件。
+ * @param {string} target 目标根
+ * @param {object} receipt 本次写入回执
+ * @returns {void}
+ */
+export function rollbackFlowerTransfer(target, receipt) {
+  if (!receipt || receipt.target !== path.resolve(target)) throw failure("flower-rollback-invalid", "Flower 回滚回执与目标不一致");
+  const errors = [];
+  for (const entry of [...receipt.files].reverse()) {
+    for (const relative of [entry.path, entry.temporary].filter(Boolean)) {
+      try {
+        const allowed = [...FILES, ".gitignore"].some((name) => relative === `.flower/${name}`) || /^\.flower\/\.inherit-[a-f0-9]{16}\.tmp$/.test(relative);
+        if (!allowed) throw new Error("回执路径不在白名单");
+        const file = ordinaryPath(target, relative);
+        const stat = fs.lstatSync(file);
+        if (stat.dev !== entry.dev || stat.ino !== entry.ino || hashContent(fs.readFileSync(file)) !== entry.hash) {
+          throw new Error(`Flower 文件已由其它操作修改:${relative}`);
+        }
+        fs.unlinkSync(file);
+      } catch (error) {
+        if (error.code !== "ENOENT") errors.push(error.message);
+      }
+    }
+  }
+  if (receipt.directory) {
+    try {
+      const directory = ordinaryPath(target, ".flower");
+      const stat = fs.lstatSync(directory);
+      if (stat.dev === receipt.directory.dev && stat.ino === receipt.directory.ino) fs.rmdirSync(directory);
+    } catch (error) {
+      if (!["ENOENT", "ENOTEMPTY", "EEXIST"].includes(error.code)) errors.push(error.message);
+    }
+  }
+  if (errors.length) throw failure("flower-rollback-conflict", errors.join("; "));
+}
+
+/**
+ * 校验后补齐缺失安装记录，失败时撤销本次文件写入。
+ * @param {object} input 继承参数，含可选 expectedDigest、journal 和测试回调 onWrite
+ * @returns {object} 继承结果和本轮回执
+ */
+export function applyFlowerTransfer(input) {
+  const planned = transfer(input);
+  if (input.expectedDigest && input.expectedDigest !== planned.plan.digest) throw failure("flower-plan-changed", "Flower 继承计划已变化，请重新预检");
+  const { plan, files } = input.baseCommit ? transfer({ ...input, baseCommit: null }) : planned;
+  if (plan.digest !== planned.plan.digest) throw failure("flower-plan-changed", "目标 Flower 继承计划已变化，请重新预检");
+  const receipt = { target: path.resolve(input.target), files: [], directory: null };
+  saveReceipt(input.journal, receipt);
+  if (!files.length) return { ...plan, receipt };
+  try {
+    const directory = ordinaryPath(input.target, ".flower");
+    if (!fs.existsSync(directory)) {
+      fs.mkdirSync(directory);
+      const stat = fs.statSync(directory);
+      receipt.directory = { dev: stat.dev, ino: stat.ino };
+      saveReceipt(input.journal, receipt);
+    }
+    for (const entry of files) {
+      const target = ordinaryPath(input.target, entry.path);
+      const temporary = path.join(directory, `.inherit-${crypto.randomBytes(8).toString("hex")}.tmp`);
+      let linked = false;
+      try {
+        const descriptor = fs.openSync(temporary, "wx", 0o600);
+        try {
+          fs.writeFileSync(descriptor, entry.content);
+          fs.fsyncSync(descriptor);
+          const stat = fs.fstatSync(descriptor);
+          receipt.files.push({ path: entry.path, temporary: `.flower/${path.basename(temporary)}`, hash: hashContent(entry.content), dev: stat.dev, ino: stat.ino });
+          saveReceipt(input.journal, receipt);
+        } finally { fs.closeSync(descriptor); }
+        // 同目录临时文件先完整写入，再以排他 link 发布，避免 rename 覆盖并发创建的目标。
+        fs.linkSync(temporary, target);
+        linked = true;
+      } finally {
+        fs.rmSync(temporary, { force: true });
+        if (!linked) {
+          receipt.files = receipt.files.filter((file) => file.path !== entry.path);
+          saveReceipt(input.journal, receipt);
+        }
+      }
+      input.onWrite?.(entry.path);
+    }
+    validateInstallation(input.target, snapshot(input.target).values);
+    return { ...plan, validationPending: false, receipt };
+  } catch (error) {
+    try { rollbackFlowerTransfer(input.target, receipt); }
+    catch (rollbackError) { error.message += `; 回滚失败:${rollbackError.message}`; }
+    throw error;
+  }
+}
+
+/**
+ * 只读诊断目标 Flower 版本证据及安装记录完整性。
+ * @param {string} target 目标根
+ * @returns {object} 安装状态、版本来源和具体错误
+ */
+export function inspectWorktreeFlower(target) {
+  let version = null;
+  let source = null;
+  try {
+    const { values } = snapshot(target);
+    version = values["plugin-lock.json"]?.plugins.find(({ id }) => id === "flower/skill-garden")?.version || null;
+    if (version) source = "plugin-lock";
+    if (!version) {
+      const legacy = readText(target, ".trellis/.flower-manifest.json");
+      if (legacy !== null) {
+        const manifest = JSON.parse(legacy);
+        version = typeof manifest?.flowerVersion === "string" && manifest.flowerVersion.trim() ? manifest.flowerVersion : null;
+        if (version) source = "legacy-manifest";
+      }
+    }
+    const complete = RECORDS.every((name) => values[name] !== null);
+    if (complete) validateInstallation(target, values);
+    return { installation: complete ? "complete" : "incomplete", version, source, reason: complete ? null : "flower-records-missing" };
+  } catch (error) {
+    return { installation: "invalid", version, source, reason: error.reason || "flower-record-invalid", path: error.path || null, message: error.message };
+  }
+}
+
+// 仅 Flower facade 提供本入口；目标分支脚本不能替换 schema 或写入实现。
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  try {
+    const input = JSON.parse(fs.readFileSync(0, "utf8"));
+    let result;
+    if (input.operation === "status") result = inspectWorktreeFlower(input.target);
+    else if (input.operation === "plan") result = planFlowerTransfer(input);
+    else if (input.operation === "apply") result = applyFlowerTransfer(input);
+    else if (input.operation === "rollback") {
+      if (fs.existsSync(input.journal)) rollbackFlowerTransfer(input.target, JSON.parse(fs.readFileSync(input.journal, "utf8")));
+      result = { action: "rolledBack" };
+    } else throw failure("flower-operation-invalid", "未知 Flower worktree 内部操作");
+    console.log(JSON.stringify({ ok: true, result }));
+  } catch (error) {
+    console.log(JSON.stringify({ ok: false, reason: error.reason || "flower-installation-invalid", message: error.message, path: error.path || null }));
+    process.exitCode = 1;
+  }
+}