flower-trellis 0.6.6 → 0.6.7

package/enhancements/MANIFEST.json

@@ -1,7 +1,7 @@
 {
-  "syncedAt": "2026-09-07T02:30:42.961Z",
+  "syncedAt": "2026-09-07T07:30:55.059Z",
   "syncedFrom": "vendor/skill-garden",
-  "sourceCommit": "ad64c8ab30cb14184895aa31d672cf1b846e5726",
+  "sourceCommit": "3e08ded44107ae8d3e1c04e5f1cdb3014655f038",
   "common": {
     "codexSkills": [
       "aliyun-ops",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flower-trellis",
-  "version": "0.6.6",
+  "version": "0.6.7",
   "description": "一键安装/升级 Trellis 并自动融合 skill-garden 强化包(默认 Claude + agents)",
   "type": "module",
   "bin": {
@@ -70,9 +70,9 @@
     "commit-and-tag-version": "^12.7.3"
   },
   "flowerReleaseNotes": {
-    "version": "0.6.6",
+    "version": "0.6.7",
     "source": "CHANGELOG.md",
-    "body": "### 🐛 修复 Bug Fixes\n\n* **codex:** 明确 Astra 规划授权边界 ([07428f8](https://github.com/SilentFlower/flower-trellis/commit/07428f8c4406449656edfe2e6dd6463d4540370a))",
+    "body": "### ✨ 新功能 Features\n\n* **bootstrap:** 完善团队版本记录与 CLI 安装引导 ([e86217c](https://github.com/SilentFlower/flower-trellis/commit/e86217c5a121b35509ad972540c2c0adf3763b64))\n\n\n### 🐛 修复 Bug Fixes\n\n* **worktree:** 补齐 Flower 安装记录继承与版本诊断 ([17ad63e](https://github.com/SilentFlower/flower-trellis/commit/17ad63efd9f56ecf491c9402ef92469c70db3ea1))\n\n\n### ♻️ 重构 Refactor\n\n* **check-all:** 同步检查优化与回归验证 ([1409d42](https://github.com/SilentFlower/flower-trellis/commit/1409d421884cfe35a95342b6e68b3b7b80496e29))\n\n\n### 🧰 维护 Maintenance\n\n* **trellis:** 同步 Flower 0.6.6 工作流与 hooks ([11ae2b9](https://github.com/SilentFlower/flower-trellis/commit/11ae2b96b543da1a01e8a1871471d0752f1a04af))\n* **trellis:** 同步本地安装产物与 Flower 记录 ([5a78ca0](https://github.com/SilentFlower/flower-trellis/commit/5a78ca01434e26287caaed8b3e68321a1efd7cc7))",
     "truncated": false
   },
   "optionalDependencies": {

package/src/assets/flower_update_hook.py

@@ -1,16 +1,17 @@
 #!/usr/bin/env python3
 # -*- coding: utf-8 -*-
-"""SessionStart 启动更新检查 hook。
+"""复用 SessionStart 升级入口，检测 CLI 缺失并提供对话安装引导。
 
-脚本只做只读检查和上下文注入:调用 `flower-trellis self-check --json`,
-发现可执行更新时输出 `<flower-update>` 块。失败、离线、无更新或关闭检查时静默退出,
-避免影响 Codex / Claude Code 正常启动。
+只读检测，不执行 npm；CLI 已安装时沿用 self-check 更新检查。
 """
 
 from __future__ import annotations
 
+import argparse
 import json
 import os
+import re
+import shutil
 import subprocess
 import sys
 from pathlib import Path
@@ -18,6 +19,105 @@ from pathlib import Path
 
 ACTIONABLE_STATUSES = {"update_available", "project_out_of_sync"}
 SELF_CHECK_TIMEOUT_SECONDS = 30
+BOOTSTRAP_STATUSES = {"cli_missing", "cli_unavailable", "project_version_unavailable", "prerequisites_missing"}
+MAX_LOCK_BYTES = 2 * 1024 * 1024
+
+
+def _executable_status(name: str) -> str:
+    """检查 PATH，区分缺失与已有但不可执行的入口。"""
+    if shutil.which(name):
+        return "available"
+    names = [name]
+    if os.name == "nt":
+        names.extend(name + suffix for suffix in os.environ.get("PATHEXT", ".COM;.EXE;.BAT;.CMD").split(";"))
+    for directory in os.get_exec_path():
+        if any(os.path.lexists(os.path.join(directory, candidate)) for candidate in names):
+            return "unavailable"
+    return "missing"
+
+
+def _locked_flower_version(project_dir: Path) -> str:
+    """只读取受支持的内置锁条目，拒绝把未知版本拼入安装命令。"""
+    lock_path = project_dir / ".flower" / "plugin-lock.json"
+    if lock_path.parent.is_symlink() or lock_path.is_symlink() or not lock_path.is_file():
+        raise ValueError("项目缺少普通文件形式的 .flower/plugin-lock.json")
+    if lock_path.stat().st_size > MAX_LOCK_BYTES:
+        raise ValueError("项目锁超过读取上限")
+    lock = json.loads(lock_path.read_text(encoding="utf-8"))
+    if not isinstance(lock, dict) or type(lock.get("schemaVersion")) is not int or lock["schemaVersion"] != 1:
+        raise ValueError("项目锁 schema 不受支持")
+    plugins, roots = lock.get("plugins"), lock.get("roots")
+    if not isinstance(plugins, list) or not isinstance(roots, list) or any(not isinstance(root, str) for root in roots):
+        raise ValueError("项目锁 plugins/roots 结构无效")
+    if any(not isinstance(plugin, dict) for plugin in plugins):
+        raise ValueError("项目锁 Plugin 条目无效")
+    matches = [plugin for plugin in plugins if plugin.get("id") == "flower/skill-garden"]
+    if len(matches) != 1:
+        raise ValueError("项目锁缺少唯一的 flower/skill-garden 条目")
+    plugin = matches[0]
+    source = plugin.get("source")
+    if (
+        not isinstance(source, dict)
+        or source.get("id") != "flower"
+        or source.get("type") != "builtin"
+        or not isinstance(source.get("reference"), str)
+        or source.get("reference") not in {
+            "package:skill-garden:old", "package:skill-garden:0.5", "package:skill-garden:0.6",
+        }
+    ):
+        raise ValueError("项目锁的 Skill-Garden 来源不是受支持的内置来源")
+    version = plugin.get("version")
+    match = re.fullmatch(r"(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)(?:-([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?(?:\+([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?", version) if isinstance(version, str) and len(version) <= 256 else None
+    if not match or any(int(part) > 9007199254740991 for part in match.groups()[:3]):
+        raise ValueError("项目 Flower 版本不是完整有效的 SemVer")
+    if match[4] and any(part.isdigit() and len(part) > 1 and part.startswith("0") for part in match[4].split(".")):
+        raise ValueError("项目 Flower 预发布版本包含非法数字标识")
+    return version
+
+
+def _check_cli(project_dir: Path) -> dict | None:
+    """只读检查本机入口，返回安装或环境诊断；可用时返回空值。"""
+    if not project_dir.is_dir():
+        return {"status": "cli_unavailable", "reason": "目标项目目录不存在"}
+    cli_status = _executable_status("flower-trellis")
+    if cli_status == "available":
+        return None
+    if cli_status == "unavailable":
+        return {"status": "cli_unavailable", "reason": "PATH 中已有 Flower 入口但不可执行，请检查权限、链接与解释器"}
+    try:
+        version = _locked_flower_version(project_dir)
+    except (OSError, ValueError) as exc:
+        return {"status": "project_version_unavailable", "reason": f"Flower CLI 缺失，项目版本无法确认：{exc}"}
+    missing = [name for name in ("node", "npm") if _executable_status(name) != "available"]
+    if missing:
+        return {"status": "prerequisites_missing", "version": version, "reason": f"Flower CLI 缺失，请先准备可执行的 {', '.join(missing)}"}
+    return {"status": "cli_missing", "version": version, "command": f"npm install -g flower-trellis@{version}"}
+
+
+def _format_bootstrap(data: dict) -> str:
+    """生成唯一的对话安装协议，检测脚本自身不执行安装。"""
+    lines = [
+        "<flower-cli-bootstrap>",
+        "priority: blocking_confirmation_required",
+        f"status: {data['status']}",
+    ]
+    if data.get("version"):
+        lines.append(f"project_flower: {data['version']}")
+    if data.get("reason"):
+        lines.append("reason: " + json.dumps(data["reason"], ensure_ascii=False))
+    if data.get("command"):
+        lines.extend([
+            f"recommended_command: {data['command']}",
+            "ai_instruction: 告知成员本机缺少 Flower CLI，展示锁定版本和 recommended_command；说明全局 npm 安装会同步本机 Trellis 命令。先征得当前成员确认，确认前禁止执行 recommended_command；当前对话已明确授权这次安装时不重复确认。",
+            "verification: 安装返回成功后，在目标项目执行 flower-trellis -v 核对 CLI 首行版本，再执行 flower-trellis self-check --json --target <目标项目>；参数按所在 shell 引用。确认 CLI 可用后继续原请求，不把项目锁视为内容完整性证明，不隐式执行 init/update/self-update。",
+        ])
+    else:
+        lines.append("ai_instruction: 说明诊断原因与缺失前提；版本未知时请维护者补齐有效项目锁，不依据旧 manifest 或猜测 latest 安装；入口异常先修复 PATH、权限或解释器。")
+    lines.extend([
+        "failure_policy: 成员拒绝后本次对话不重复追问；安装或验证失败如实报告，不自动提权、不循环安装。依赖 CLI 的操作说明尚未满足的前提；本次已处理的相同引导不重复执行。",
+        "</flower-cli-bootstrap>",
+    ])
+    return "\n".join(lines)
 
 
 def _debug(message: str) -> None:
@@ -45,6 +145,9 @@ def _project_dir(hook_input: dict) -> Path:
 
 def _run_self_check(project_dir: Path) -> dict | None:
     """执行 flower-trellis self-check 并解析 JSON。"""
+    bootstrap = _check_cli(project_dir)
+    if bootstrap:
+        return bootstrap
     try:
         result = subprocess.run(
             [
@@ -61,18 +164,19 @@ def _run_self_check(project_dir: Path) -> dict | None:
             timeout=SELF_CHECK_TIMEOUT_SECONDS,
             cwd=str(project_dir),
         )
-    except (subprocess.TimeoutExpired, FileNotFoundError, PermissionError) as exc:
-        _debug(str(exc))
-        return None
+    except subprocess.TimeoutExpired:
+        return {"status": "cli_unavailable", "reason": "Flower CLI 检查超时，不能据此判定未安装"}
+    except OSError as exc:
+        return {"status": "cli_unavailable", "reason": f"Flower 入口存在但执行失败，请检查 PATH、权限与解释器：{exc}"}
     if result.returncode != 0:
-        _debug(result.stderr.strip() or f"退出码 {result.returncode}")
-        return None
+        _debug(result.stderr.strip())
+        return {"status": "cli_unavailable", "reason": f"Flower CLI 检查退出码 {result.returncode}，请先诊断现有安装"}
     try:
         data = json.loads(result.stdout)
     except json.JSONDecodeError as exc:
         _debug(f"JSON 解析失败:{exc}")
-        return None
-    return data if isinstance(data, dict) else None
+        return {"status": "cli_unavailable", "reason": "Flower CLI 返回的检查结果不是有效 JSON"}
+    return data if isinstance(data, dict) and isinstance(data.get("status"), str) else {"status": "cli_unavailable", "reason": "Flower CLI 检查结果结构无效"}
 
 
 def _json_bool(value: object) -> str:
@@ -219,15 +323,32 @@ def _emit_context(context: str, system_message: str) -> None:
     print(json.dumps(result, ensure_ascii=False), flush=True)
 
 
-def main() -> None:
+def main(argv: list[str] | None = None) -> None:
+    """处理宿主启动或手动只读检测入口并输出上下文。
+
+    Args:
+        argv: 显式参数列表，省略时读取进程参数。
+    Returns:
+        无返回值；通过标准输出返回宿主 JSON。
+    """
+    parser = argparse.ArgumentParser(description="Flower CLI 安装与升级只读检测")
+    parser.add_argument("--bootstrap-only", action="store_true")
+    parser.add_argument("--target", type=Path)
+    args = parser.parse_args(argv)
+    if not args.bootstrap_only and (os.environ.get("TRELLIS_HOOKS") == "0" or os.environ.get("TRELLIS_DISABLE_HOOKS") == "1" or os.environ.get("CODEX_NON_INTERACTIVE") == "1"):
+        return
     try:
-        hook_input = json.loads(sys.stdin.read() or "{}")
+        hook_input = {} if args.bootstrap_only else json.loads(sys.stdin.read() or "{}")
         if not isinstance(hook_input, dict):
             hook_input = {}
     except json.JSONDecodeError:
         hook_input = {}
 
-    data = _run_self_check(_project_dir(hook_input))
+    project_dir = args.target.resolve() if args.target else _project_dir(hook_input)
+    data = _check_cli(project_dir) if args.bootstrap_only else _run_self_check(project_dir)
+    if data and data.get("status") in BOOTSTRAP_STATUSES:
+        _emit_context(_format_bootstrap(data), "Flower CLI 需要安装确认或环境诊断")
+        return
     if not data or data.get("status") not in ACTIONABLE_STATUSES:
         return
     _emit_context(_format_context(data), _system_message(data))

package/src/builtin-plugins/skill-garden/content-adapter.js

@@ -6,6 +6,7 @@ import {
   ENHANCEMENT_SKILL_TARGETS,
 } from "../../constants.js";
 import { readLegacyManifestStatus } from "../../lib/manifest.js";
+import { projectFlowerMetadata } from "./project-metadata.js";
 import { shouldInstallName } from "../../lib/skill-filter.js";
 import { listCanonicalTreeFiles, isVolatileTreeArtifact } from "../../plugin/integrity/canonical-tree.js";
 import {
@@ -893,6 +894,9 @@ export function projectSkillGardenContent(options) {
       }
     }
   }
+  const metadata = projectFlowerMetadata(projectRoot, resolved.id);
+  mutations.push(...metadata.mutations);
+  for (const [key, value] of metadata.payloads) payloads.set(key, value);
   return {
     mutations: mutations.sort((left, right) => compareUtf8(left.target, right.target)),
     payloads,

package/src/builtin-plugins/skill-garden/project-metadata.js

@@ -0,0 +1,41 @@
+import fs from "node:fs";
+import path from "node:path";
+import { planLegacyManifestMigration } from "../../lib/manifest.js";
+import { contentMutationKey } from "../../plugin/install/content-projector.js";
+import { hashContent, hashFileIfExists } from "../../plugin/install/content-hash.js";
+import { mergeFlowerIgnoreRules } from "../../plugin/state/ignore-rules.js";
+
+/**
+ * 规划 Flower 共享记录与旧配置迁移，不声明用户配置的独占 ownership。
+ *
+ * @param {string} projectRoot 目标项目根
+ * @param {string} owner 内置 Plugin ID
+ * @returns {{mutations:object[],payloads:Map<string,Buffer>}} 事务目标及写入内容
+ */
+export function projectFlowerMetadata(projectRoot, owner) {
+  const writes = planLegacyManifestMigration(projectRoot);
+  const localIgnore = path.join(projectRoot, ".flower/.gitignore");
+  const localText = hashFileIfExists(localIgnore) === null ? "" : fs.readFileSync(localIgnore, "utf8");
+  writes.push({ path: ".flower/.gitignore", content: Buffer.from(mergeFlowerIgnoreRules(localText)) });
+  const rootIgnore = path.join(projectRoot, ".gitignore");
+  if (hashFileIfExists(rootIgnore) !== null) {
+    writes.push({ path: ".gitignore", content: Buffer.from(mergeFlowerIgnoreRules(fs.readFileSync(rootIgnore, "utf8"), { root: true })) });
+  }
+  const mutations = [];
+  const payloads = new Map();
+  for (const entry of writes) {
+    const mutation = {
+      owner,
+      target: entry.path,
+      operation: entry.content === null ? "remove" : "write",
+      beforeHash: hashFileIfExists(path.join(projectRoot, ...entry.path.split("/"))),
+      afterHash: entry.content === null ? null : hashContent(entry.content),
+      source: "flower:project-metadata",
+      allowUnownedWrite: true,
+      allowUnownedRemove: true,
+    };
+    mutations.push(mutation);
+    if (entry.content !== null) payloads.set(contentMutationKey(mutation), entry.content);
+  }
+  return { mutations, payloads };
+}

package/src/commands/self-check.js

@@ -14,7 +14,9 @@ function printSelfCheckHelp() {
   --force-remote   强制检查远端版本
   --target <dir>   要检查的项目目录
 
-该命令供 SessionStart hook 和自动化读取，成功时始终输出 JSON。`);
+该命令供 SessionStart hook 和自动化读取，成功时始终输出 JSON。
+project.flowerVersionStatus 区分 known/unknown；记录缺失且无已知更新时返回
+project_unknown，不能以 CLI 最新推断项目也已更新。`);
 }
 
 /**

package/src/commands/self-update.js

@@ -199,7 +199,9 @@ async function executeSelfUpdate(ctx) {
   }
 
   if (!shouldInstallFlower && !projectOnly && check.status !== "project_out_of_sync") {
-    console.log(`  · 当前状态:${check.status},无需执行 self-update`);
+    console.log(check.status === "project_unknown"
+      ? "  · 项目 Flower 版本无法确认，未执行更新；worktree 可先通过 prepare --inherit-flower 补齐安装记录"
+      : `  · 当前状态:${check.status},无需执行 self-update`);
     return;
   }
 

package/src/commands/update-check.js

@@ -106,11 +106,11 @@ export async function updateCheck(ctx) {
     const cachePath = updateCheckCachePath(ctx.target);
     console.log(`settings: ${settingsPath(ctx.target)}`);
     console.log(`cache: ${cachePath}`);
-    console.log(`legacy manifest: ${manifestPath(ctx.target)}`);
+    if (manifest) console.log(`legacy manifest (待迁移): ${manifestPath(ctx.target)}`);
     console.log(JSON.stringify(readUpdateCheck(ctx.target), null, 2));
-    if (!manifest) console.log("  · manifest 不存在,当前显示默认策略");
+    if (!manifest && !fs.existsSync(settingsPath(ctx.target))) console.log("  · settings 不存在,当前显示默认策略");
     if (!fs.existsSync(cachePath)) {
-      console.log("  · cache 不存在,当前显示默认或旧 manifest 兼容缓存");
+      console.log("  · cache 不存在,当前显示默认或旧记录兼容缓存");
     }
     return;
   }

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 },
     };
   }