flower-trellis 0.4.0 → 0.4.2

package/README.md

@@ -52,6 +52,15 @@ flower-trellis init -u <your-name> -y
 # 升级 Trellis 并按新版本重新叠加强化包
 flower-trellis update
 
+# 检查当前项目是否需要更新(稳定 JSON,供 AI / hook 使用)
+flower-trellis self-check --json --target .
+
+# 执行受控自更新:升级 flower-trellis,再默认 --force 重叠加当前项目
+flower-trellis self-update --target . --yes
+
+# 管理启动更新检查策略
+flower-trellis update-check get --target .
+
 # 交互管理通用技能,并查看工作流强化包
 flower-trellis skill
 
@@ -70,6 +79,9 @@ flower-trellis -v
 |------|------|
 | `init` | 安装 Trellis 并叠加强化包(默认命令,裸跑等同 `init`) |
 | `update` | 升级 Trellis,并按新版本重新叠加强化包 |
+| `self-check` | 输出启动更新检查 JSON,供 Codex / Claude Code hook 和 AI 自动化读取 |
+| `self-update` | 受控升级 flower-trellis 并对目标项目执行完整 `flower-trellis update` 重叠加 |
+| `update-check` | 管理 `.trellis/.flower-manifest.json` 内的启动更新检查策略 |
 | `skill` | 打开交互菜单:启用或停用通用技能,只读查看工作流强化包 |
 | `uninstall` | 移除 Trellis 本体并清理强化包残留(支持 `-y` / `--dry-run`) |
 | `<其它命令>` | 原样透传给 Trellis,覆盖其现有及未来子命令 |
@@ -99,16 +111,93 @@ flower-trellis -v
 - **非交互**(`-y` 或非 TTY):仅打印一行升级提示,不弹确认、不阻塞。
 - **跳过检测**:经 `npx` 运行(本就是最新版)、或显式 `--no-update-check` / `FLOWER_NO_UPDATE_CHECK=1` 时不检测。
 
+### 启动更新检查
+
+运行 `flower-trellis init` / `flower-trellis update` 后,目标项目会安装轻量启动 hook:
+
+- Codex:向 `.codex/hooks.json` 的 `SessionStart` 追加 `.trellis/scripts/flower_update_hook.py`。
+- Claude Code:只向 `.claude/settings.json` 的 `SessionStart` `startup` matcher 追加该 hook,不挂 `clear` / `compact`。
+
+启动 hook 不会直接安装 npm 包,也不会直接改项目文件。它只调用:
+
+```bash
+flower-trellis self-check --json --target .
+```
+
+发现可更新或项目已铺版本不一致时,向 AI 注入 `<flower-update>` 上下文。无更新、离线、关闭检查、npx 临时运行时默认不打扰。
+
+检查分两层:
+
+- **本地一致性检查**:每次启动都会比对当前安装的 `flower-trellis` / 捆绑 Trellis 版本与项目 `.trellis/.flower-manifest.json` / `.trellis/.version`;不受 `intervalHours` 限制。
+- **远程版本探测**:访问 npm registry 读取 `flower-trellis` dist-tags;受 `intervalHours` 节流,带超时,失败静默。
+
+策略和缓存统一保存在 `.trellis/.flower-manifest.json` 的 `updateCheck`:
+
+```json
+{
+  "updateCheck": {
+    "enabled": true,
+    "policy": "ask",
+    "intervalHours": 24,
+    "lastCheckedAt": "2026-07-07T00:00:00.000Z",
+    "lastRemote": { "latest": "0.4.2", "beta": null },
+    "lastStatus": "update_available",
+    "lastErrorCode": null
+  }
+}
+```
+
+`policy` 可选:
+
+| policy | 行为 |
+|--------|------|
+| `off` | 不做启动更新检查,也不联网 |
+| `notify` | 只注入提示和手动命令,AI 不主动询问或执行 |
+| `ask` | 默认值;AI 发现可更新后先询问用户 |
+| `auto` | 安全条件满足时 AI 可执行 `self-update`;dirty 工作区或活跃任务等情况会降级为 `ask` |
+
+管理策略:
+
+```bash
+flower-trellis update-check get --target .
+flower-trellis update-check set --policy auto --interval-hours 12 --target .
+flower-trellis update-check disable --target .  # 只设置 enabled=false,不改 policy
+flower-trellis update-check enable --target .   # 只设置 enabled=true,沿用原 policy
+```
+
+执行更新:
+
+```bash
+# 预览,不写入
+flower-trellis self-update --target . --dry-run
+
+# 执行:先升级全局 flower-trellis,再对项目执行完整 update
+flower-trellis self-update --target . --yes
+```
+
+项目重叠加阶段默认等价于 Trellis 交互里的 **Apply Overwrite to all**:
+
+```bash
+flower-trellis update --target . --no-update-check --force
+```
+
+如需改用其它上游冲突策略,在 `--` 后透传:
+
+```bash
+flower-trellis self-update --target . --yes -- --skip-all
+flower-trellis self-update --target . --yes -- --create-new
+```
+
 ## 工作原理
 
 `init` 的执行流程:
 
 ```
-flower banner → 平台多选菜单 → Trellis 原生交互(模板 / monorepo / 冲突)→ 叠加强化包 → codex 后处理
+flower banner → 平台多选菜单 → Trellis 原生交互(模板 / monorepo / 冲突)→ 叠加强化包 → 平台后处理
 ```
 
 - **统一品牌头部**:Trellis 子进程在伪终端(`node-pty`)中运行,其原生的模板 / monorepo / 冲突等交互完整保留,但重复打印的启动 banner 被过滤,全程只呈现一个 flower banner。
-- **按平台铺设技能**:Claude 铺到 `.claude/skills`,Codex / Gemini 等铺到 `.agents/skills`;并对 codex 做后处理(兼容清理旧 `config.toml` 的 `[features.multi_agent_v2]`,在保留上游 hooks 的基础上补全 `SessionStart`)。
+- **按平台铺设技能**:Claude 铺到 `.claude/skills`,Codex / Gemini 等铺到 `.agents/skills`;并做平台后处理:Codex 兼容清理旧 `config.toml` 的 `[features.multi_agent_v2]`,在保留上游 hooks 的基础上补全 `SessionStart`;Claude Code 只在 `startup` SessionStart 挂载启动更新检查。
 - **幂等执行**:`workflow.md` 注入前先按 `BEGIN/END` 标记清除旧块再重注入(块数恒定,不会翻倍,首次注入前备份到 `.trellis/.backup-flower/`);技能文件覆盖式铺设,并通过 `.trellis/.flower-manifest.json` 记录已铺路径,升级时删除已淘汰项。
 - **上线事项账本**:强化包通过 finish-work skill override 在归档前智能识别 SQL、配置、批处理 / 部署脚本 / 数据修复、外部系统 / 依赖平台等上线事项,必要时写入任务 `release.md`;`trellis-release` 可在正式上线前核对任务文档、`release.md` 和 git 证据,生成 `YYYY-MM-DD-<release-slug>.md` 格式的版本 / 批次操作单。
 - **安全中止**:`Ctrl+C` 取消后不会继续叠加。

package/enhancements/0.6/overrides/skills/trellis-finish-work.md

@@ -22,7 +22,7 @@ If no `release.md` exists:
 - High-confidence no release work exists after re-reading task files and git evidence: do not create `release.md`; mention in the final finish-work report that no release operations were identified.
 - Signals are uncertain but release risk exists: write `<task>/release.md` and mark the conclusion as `Needs human review`.
 
-Release-operation signals include SQL or migrations; configuration, environment variables, feature flags, permissions, secrets, or external endpoints; deployment scripts, one-off commands, data repair, scheduled task triggers, background job reruns, or other batch operations; and external systems or dependent platforms that must be released or coordinated, such as H0 API relay / gateway platforms, messaging platforms, or third-party admin consoles.
+Release-operation signals, with the `release.md` section each maps to: SQL or migrations (`SQL Changes`); configuration, environment variables, feature flags, permissions, secrets, or external endpoints (`Configuration Changes`); deployment scripts, one-off commands, data repair, scheduled task triggers, background job reruns, or other batch operations (`Batch / Deployment Scripts / Data Repair`); and external systems or dependent platforms outside the current repository that must be released or coordinated, such as H0 API relay / gateway platforms, messaging platforms, or third-party admin consoles (`External Systems / Dependent Platforms`).
 
 When writing or updating `release.md`, use this structure:
 
@@ -64,8 +64,6 @@ Rollback code only.
 Verify according to task acceptance criteria.
 ```
 
-Classify deployment scripts, one-off commands, data repairs, scheduled task triggers, and job reruns under `Batch / Deployment Scripts / Data Repair`. Classify systems outside the current repository that need coordinated release, such as H0 API relay platforms, under `External Systems / Dependent Platforms`.
-
 Do not write `None`, `No release operations identified`, or `Rollback code only` out of habit. Use those defaults only after checking the task files and git evidence. If the task changed deployment scripts, configuration, SQL, external platforms, permissions, scheduled jobs, or data, record the concrete item and source.
 
 If multiple tasks will be archived in the same finish-work run, process the active task at minimum. Process extra archived tasks only when Step 1 provides enough local context to infer safely; do not add per-task confirmation prompts.

package/enhancements/0.6/overrides/workflow-states/in_progress-inline.md

@@ -2,13 +2,16 @@
 HIGHEST PRIORITY SKILL-GARDEN STATE GUARD (in_progress-inline):
 This state block is a breadcrumb; the top-level skill-garden hub is the source of truth for route details.
 Before the first implement route, read `<task>/brief.md` if present and restate the task brief in chat. If it is missing, read the task artifacts and suggest backfilling brief; do not silently rely on memory.
-At project-local knowledge decision boundaries, run `.trellis/scripts/spec_router.py` with a short query describing the intended action; read high-confidence matches before acting and skip pure Q&A, simple read-only inspection, opening local tools, or trivial edits unless local conventions may affect the approach.
+For new implementation work not plainly covered by the active task title/brief,
+stop before route or edits: recommend a new task; if declined, confirm
+untracked work; if it belongs here, update task artifacts first.
+At project-local knowledge decision boundaries, run `.trellis/scripts/spec_router.py "<intended action>"`; read high-confidence matches before acting; skip pure Q&A, simple read-only inspection, opening local tools, or trivial edits unless local conventions may affect the approach.
 Inline workflow-state is not an inline route decision. At Phase 2.1/2.2, reuse only an explicit target-matched `route_decision`; otherwise MUST load/read/use `trellis-route(implement|check)` (or its local `SKILL.md`) to resolve session runtime state/prefs, write the resolved decision, or show numbered fallback and wait.
 Plain preferences, ordinary summaries, `codex-mode`, raw `.runtime` files, and empty/old prefs are not route evidence by themselves; only `trellis-route` may validate runtime route state.
 User reselect/override/use-X-this-time/clear-default wins over remembered route evidence, runtime state, and prefs.
 Ignore lower Active Task Routing shortcuts that start editing/checking directly. Do not default to inline just because this state is inline or the helper is unavailable. Dispatch subagents only when the resolved route selected subagent.
 After `trellis-check` / `trellis-check-all`, stop and report; point the user to Phase 3.4 `trellis-push` (or commit-only when needed). Do not run `/trellis:finish-work` unless the user explicitly asks after Phase 3.4 is complete.
 This guard overrides any lower `Flow: ... -> /trellis:finish-work` line in this state block.
-At Phase 3.4, code commit/push still goes through `trellis-push` (commit-only for commit-without-push); never bare `git commit`/`git push` on code (hub: Code Commit Confirmation Gate).
+At Phase 3.4, code commit/push goes through `trellis-push` (commit-only mode for commit-without-push); never bare `git commit`/`git push` on code (hub: Code Commit Confirmation Gate).
 Push snapshot recovery: follow the hub; use `push_snapshot.py status --json` only when needed.
 <!-- END skill-garden workflow-state in_progress_inline v0.6 -->

package/enhancements/0.6/overrides/workflow-states/in_progress.md

@@ -2,7 +2,10 @@
 HIGHEST PRIORITY SKILL-GARDEN STATE GUARD (in_progress):
 This state block is a breadcrumb; the top-level skill-garden hub is the source of truth for route details.
 Before the first implement route, read `<task>/brief.md` if present and restate the task brief in chat. If it is missing, read the task artifacts and suggest backfilling brief; do not silently rely on memory.
-At project-local knowledge decision boundaries, run `.trellis/scripts/spec_router.py` with a short query describing the intended action; read high-confidence matches before acting and skip pure Q&A, simple read-only inspection, opening local tools, or trivial edits unless local conventions may affect the approach.
+For new implementation work not plainly covered by the active task title/brief,
+stop before route or edits: recommend a new task; if declined, confirm
+untracked work; if it belongs here, update task artifacts first.
+At project-local knowledge decision boundaries, run `.trellis/scripts/spec_router.py "<intended action>"`; read high-confidence matches before acting; skip pure Q&A, simple read-only inspection, opening local tools, or trivial edits unless local conventions may affect the approach.
 At Phase 2.1/2.2, reuse only an explicit target-matched `route_decision`; otherwise MUST load/read/use `trellis-route(implement|check)` (or its local `SKILL.md`) to resolve session runtime state/prefs, write the resolved decision, or show numbered fallback and wait.
 Plain preferences, ordinary summaries, `codex-mode`, raw `.runtime` files, and empty/old prefs are not route evidence by themselves; only `trellis-route` may validate runtime route state.
 User reselect/override/use-X-this-time/clear-default wins over remembered route evidence, runtime state, and prefs.

package/enhancements/0.6/overrides/workflow-states/no_task.md

@@ -3,7 +3,7 @@ HIGHEST PRIORITY SKILL-GARDEN STATE GUARD (no_task):
 Creating or resuming a task is not implementation permission.
 After PRD is ready and the task is started, the next implementation action is Phase 2.1 `trellis-route(implement)` unless a valid current-task implement route decision already exists.
 If no active task exists, use `push_snapshot.py status --json` once per session; if it returns candidates, relay them and suggest rebinding before resuming.
-At project-local knowledge decision boundaries, run `.trellis/scripts/spec_router.py` with a short query describing the intended action; read high-confidence matches before acting and skip pure Q&A, simple read-only inspection, opening local tools, or trivial edits unless local conventions may affect the approach.
+At project-local knowledge decision boundaries, run `.trellis/scripts/spec_router.py "<intended action>"`; read high-confidence matches before acting; skip pure Q&A, simple read-only inspection, opening local tools, or trivial edits unless local conventions may affect the approach.
 Do NOT call the harness built-in plan mode (`EnterPlanMode` / `ExitPlanMode`) for Trellis planning. It is not a substitute for Trellis task-creation consent, Trellis planning, or the route gate. For complex work, classify the turn, ask for task-creation consent, then use `trellis-brainstorm`.
 If the turn is a meta edit to Trellis itself and Trellis tracking would be overkill, say so and ask to skip Trellis; never silently swap built-in plan mode in for the consent gate.
 <!-- END skill-garden workflow-state no_task v0.6 -->

package/enhancements/0.6/overrides/workflow-states/planning-inline.md

@@ -4,6 +4,6 @@ Planning is not implementation permission.
 Complete prd.md + required context first.
 If the active workflow later routes to sub-agent execution, required context includes real curated entries in both `implement.jsonl` and `check.jsonl`; the seed `_example` row alone is not ready.
 Before `task.py start`, use `trellis-task-brief` to refresh `brief.md` from the latest task artifacts and display it in chat for review.
-At project-local knowledge decision boundaries, run `.trellis/scripts/spec_router.py` with a short query describing the intended action; read high-confidence matches before acting and skip pure Q&A, simple read-only inspection, opening local tools, or trivial edits unless local conventions may affect the approach.
+At project-local knowledge decision boundaries, run `.trellis/scripts/spec_router.py "<intended action>"`; read high-confidence matches before acting; skip pure Q&A, simple read-only inspection, opening local tools, or trivial edits unless local conventions may affect the approach.
 After status becomes in_progress, next action = `trellis-route(implement)`, not direct edits.
 <!-- END skill-garden workflow-state planning_inline v0.6 -->

package/enhancements/0.6/overrides/workflow-states/planning.md

@@ -4,6 +4,6 @@ Planning is not implementation permission.
 Complete prd.md + required context first.
 For sub-agent-dispatch platforms, required context includes real curated entries in both `implement.jsonl` and `check.jsonl`; the seed `_example` row alone is not ready.
 Before `task.py start`, use `trellis-task-brief` to refresh `brief.md` from the latest task artifacts and display it in chat for review.
-At project-local knowledge decision boundaries, run `.trellis/scripts/spec_router.py` with a short query describing the intended action; read high-confidence matches before acting and skip pure Q&A, simple read-only inspection, opening local tools, or trivial edits unless local conventions may affect the approach.
+At project-local knowledge decision boundaries, run `.trellis/scripts/spec_router.py "<intended action>"`; read high-confidence matches before acting; skip pure Q&A, simple read-only inspection, opening local tools, or trivial edits unless local conventions may affect the approach.
 After status becomes in_progress, next action = `trellis-route(implement)`, not direct edits.
 <!-- END skill-garden workflow-state planning v0.6 -->

package/enhancements/0.6/overrides/workflow.md

@@ -6,17 +6,17 @@
 
 **Priority**: This hub overrides any conflicting Trellis workflow, skill, or command text for the scoped behaviors below.
 
-**Scope**: project knowledge discovery at project-local knowledge decision boundaries, Phase 1.4 task brief handoff, Phase 2.1 implement routing, Phase 2.2 check/check-all routing, current-task route reuse, post-check stop, auto-loop commit-only preauthorization, Phase 3.4 trellis-push, explicit Phase 3.5 finish-work bookkeeping, and push-progress recovery. State blocks should keep one short skill-garden sentinel; long-form rules live here.
+**Scope**: the behaviors covered by the sections below. State blocks should keep one short skill-garden sentinel; long-form rules live here.
 
 **Mechanical rule**: use this hub as the source of truth. Do not add separate top-level skill-garden override sections or multiple skill-garden sentinels inside the same `workflow-state:*` block.
 
 #### Project Knowledge Discovery
 
 Before choosing an approach for non-trivial project work, run project knowledge
-discovery when project-local SOPs, package conventions, workflow rules,
-config/state contracts, release/publish/deploy steps, git history actions,
-data changes, cross-layer design, generated artifacts, install/sync pipelines,
-or destructive operations may affect the correct approach:
+discovery when project-local SOPs, package conventions, workflow rules (CI, hooks),
+config/state contracts, release/publish/deploy/rollback steps, git history actions,
+data changes or fixes (including migrations), cross-layer design, generated artifacts,
+install/sync pipelines, or destructive operations may affect the correct approach:
 
 ```bash
 python3 ./.trellis/scripts/spec_router.py "<short query describing the intended action>"
@@ -24,8 +24,7 @@ python3 ./.trellis/scripts/spec_router.py "<short query describing the intended
 
 Build the query from the current user request plus relevant immediate context:
 the intended action, commands about to run, files or systems involved, package/layer,
-and domain words such as release, publish, deploy, migration, config, CI, workflow,
-hooks, rollback, data fix, generated artifact, install/sync pipeline, or destructive command.
+and domain words matching the trigger list above.
 
 Read high-confidence matches before acting. For medium-confidence matches, read only
 when the path, heading, index description, or reason clearly fits the intended change.
@@ -43,6 +42,16 @@ Before Phase 1.4 `task.py start`, use `trellis-task-brief` to refresh `<task>/br
 
 Before the first implement route, restate existing `<task>/brief.md` in chat. If missing, read task artifacts and suggest backfilling brief; do not invent one from memory.
 
+#### Active Task Scope Guard
+
+When a session already has an active task, do not treat unrelated new implementation
+requests as permission to implement under that task. If the work is not plainly
+covered by the active task title/brief, recommend creating a new Trellis task
+and stop before `trellis-route` or file edits. If the user explicitly declines
+task tracking, confirm untracked work first and do not use active-task artifacts
+or progress for that work. If the user says it belongs to the active task,
+update that task's artifacts before implementation.
+
 #### Routing Gate
 
 Phase 2.1 implement and Phase 2.2 check/check-all require route evidence before execution.
@@ -50,11 +59,10 @@ Phase 2.1 implement and Phase 2.2 check/check-all require route evidence before
 At each route boundary:
 
 1. Reuse only an explicit, target-matched `route_decision` already present in the current context.
-2. Otherwise you MUST load/read/use `trellis-route(target=implement|check)` before deciding. `trellis-route` owns session runtime recovery, `.route-prefs.tmp`, fallback choices, runtime-state writes, and dispatch mapping.
-3. If the platform cannot invoke skills directly, open the local `trellis-route/SKILL.md` copy first, then follow its numbered fallback choices in normal chat and wait.
-4. If the route helper cannot ask through `AskUserQuestion` / `request_user_input`, ask the same numbered choices from `trellis-route` in normal chat and wait.
+2. Otherwise you MUST invoke `trellis-route(target=implement|check)` before deciding; if the platform cannot invoke skills directly, read the local `trellis-route/SKILL.md` copy and follow its numbered fallback choices in normal chat and wait. `trellis-route` owns session runtime recovery, `.route-prefs.tmp`, fallback choices, runtime-state writes, and dispatch mapping.
+3. If the route helper cannot ask through `AskUserQuestion` / `request_user_input`, ask the same numbered choices from `trellis-route` in normal chat and wait.
 
-Plain user preference, ordinary compact/SessionStart summary, ordinary summary, replacement history, historical bare numeric replies, `codex-mode`, empty/old prefs, and raw `.trellis/.runtime/sessions/*` `route_decisions` content that has not been validated by `trellis-route` are not route evidence by themselves; numbered fallback validity is governed by `trellis-route`.
+Plain user preference, ordinary summaries (compact/SessionStart or otherwise), replacement history, historical bare numeric replies, `codex-mode`, empty/old prefs, and raw `.trellis/.runtime/sessions/*` `route_decisions` content that has not been validated by `trellis-route` are not route evidence by themselves; numbered fallback validity is governed by `trellis-route`.
 
 User reselect/override/use-X-this-time/clear-default wins over remembered route evidence, runtime state, and personal prefs.
 
@@ -62,9 +70,7 @@ At Phase 2.1/2.2, this gate overrides lower "Active Task Routing" rows that say
 
 #### Post-Check Stop Gate
 
-After `trellis-check` or `trellis-check-all` finishes, stop and report the result; point the user to Phase 3.4 `trellis-push` (or commit-only when needed). Do not run `/trellis:finish-work`, do not archive the task, and do not imply the task is ready to wrap up solely because checks passed.
-
-If checks pass, the next allowed workflow steps are Phase 3.3 `trellis-update-spec` and Phase 3.4 `trellis-push`/commit confirmation. `/trellis:finish-work` is explicit-only: run it only after Phase 3.4 is complete and the user asks to wrap up, archive, or finish the task.
+After `trellis-check` or `trellis-check-all` finishes, stop and report the result. If checks pass, the next allowed workflow steps are Phase 3.3 `trellis-update-spec` and Phase 3.4 `trellis-push`/commit confirmation (commit-only when needed); do not archive the task or imply it is ready to wrap up solely because checks passed. `/trellis:finish-work` is explicit-only: run it only after Phase 3.4 is complete and the user asks to wrap up, archive, or finish the task.
 
 During a running `trellis-auto-loop`, the runner's `record` + `next` replaces the post-check stop gate: after a check pass, record the result, then continue to spec update / commit-only according to `.trellis/scripts/auto_loop.py`. Outside auto-loop, keep the normal stop gate.
 
@@ -84,7 +90,7 @@ This exception does not apply to ordinary `trellis-push`. If the plan contains u
 
 #### Bookkeeping Auto-commit Scope
 
-`session_auto_commit` only governs the bookkeeping commits `task.py archive` / `add_session.py` make for their own `.trellis/tasks/**` and `.trellis/workspace/**` files — never code (gated above). When `false`, those archive/journal writes stay disk-only (no compensating `git commit`).
+`session_auto_commit` only governs the bookkeeping commits `task.py archive` / `add_session.py` make for their own `.trellis/tasks/**` and `.trellis/workspace/**` files. When `false`, those archive/journal writes stay disk-only (no compensating `git commit`).
 
 #### Push Progress Recovery / Snapshot
 

package/enhancements/MANIFEST.json

@@ -1,7 +1,7 @@
 {
-  "syncedAt": "2026-07-02T11:06:42.782Z",
+  "syncedAt": "2026-07-07T06:26:20.520Z",
   "syncedFrom": "vendor/skill-garden",
-  "sourceCommit": "a70185e3b372058363296e81e2138f4f239d6e3b",
+  "sourceCommit": "5fdebe60e923c91ba912461b99413b5c8e11a38c",
   "common": {
     "codexSkills": [
       "craft-rpa",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flower-trellis",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "description": "一键安装/升级 Trellis 并自动融合 skill-garden 强化包(默认 Claude + agents)",
   "type": "module",
   "bin": {

package/src/assets/flower_update_hook.py

@@ -0,0 +1,135 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""SessionStart 启动更新检查 hook。
+
+脚本只做只读检查和上下文注入:调用 `flower-trellis self-check --json`,
+发现可执行更新时输出 `<flower-update>` 块。失败、离线、无更新或关闭检查时静默退出,
+避免影响 Codex / Claude Code 正常启动。
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+
+ACTIONABLE_STATUSES = {"update_available", "project_out_of_sync"}
+
+
+def _debug(message: str) -> None:
+    """在显式调试时输出简短错误。"""
+    if os.environ.get("FLOWER_UPDATE_HOOK_DEBUG"):
+        print(f"flower_update_hook: {message}", file=sys.stderr)
+
+
+def _project_dir(hook_input: dict) -> Path:
+    """从平台环境变量或 hook stdin 解析项目目录。"""
+    for name in (
+        "CLAUDE_PROJECT_DIR",
+        "CODEX_PROJECT_DIR",
+        "CURSOR_PROJECT_DIR",
+        "GEMINI_PROJECT_DIR",
+        "QODER_PROJECT_DIR",
+        "CODEBUDDY_PROJECT_DIR",
+        "TRAE_PROJECT_DIR",
+    ):
+        value = os.environ.get(name)
+        if value:
+            return Path(value).resolve()
+    return Path(str(hook_input.get("cwd") or ".")).resolve()
+
+
+def _run_self_check(project_dir: Path) -> dict | None:
+    """执行 flower-trellis self-check 并解析 JSON。"""
+    try:
+        result = subprocess.run(
+            [
+                "flower-trellis",
+                "self-check",
+                "--json",
+                "--target",
+                str(project_dir),
+            ],
+            capture_output=True,
+            text=True,
+            encoding="utf-8",
+            errors="replace",
+            timeout=8,
+            cwd=str(project_dir),
+        )
+    except (subprocess.TimeoutExpired, FileNotFoundError, PermissionError) as exc:
+        _debug(str(exc))
+        return None
+    if result.returncode != 0:
+        _debug(result.stderr.strip() or f"退出码 {result.returncode}")
+        return None
+    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
+
+
+def _format_context(data: dict) -> str:
+    """把 self-check JSON 转成给 AI 读取的短上下文块。"""
+    current = data.get("current") or {}
+    project = data.get("project") or {}
+    remote = data.get("remote") or {}
+    ai = data.get("ai") or {}
+    safety = data.get("safety") or {}
+    lines = [
+        "<flower-update>",
+        f"status: {data.get('status')}",
+        f"policy: {data.get('policy')}",
+        f"current_flower: {current.get('flowerVersion')}",
+        f"project_flower: {project.get('flowerVersion')}",
+        f"bundled_trellis: {current.get('bundledTrellisVersion')}",
+        f"project_trellis: {project.get('trellisVersion')}",
+    ]
+    if remote.get("tags"):
+        lines.append(f"remote: {json.dumps(remote.get('tags'), ensure_ascii=False)}")
+    command = (data.get("commands") or {}).get("recommended") or ai.get("command")
+    if command:
+        lines.append(f"recommended_command: {command}")
+    if safety.get("reasons"):
+        lines.append(f"safety_reasons: {', '.join(safety.get('reasons') or [])}")
+    if ai.get("instruction"):
+        lines.append(f"ai_instruction: {ai.get('instruction')}")
+    lines.append("</flower-update>")
+    return "\n".join(lines)
+
+
+def _emit_context(context: str) -> None:
+    """同时兼容 Codex / Claude Code / Cursor 风格的 hook JSON 输出。"""
+    result = {
+        "suppressOutput": True,
+        "systemMessage": "flower-trellis update context injected",
+        "hookSpecificOutput": {
+            "hookEventName": "SessionStart",
+            "additionalContext": context,
+        },
+        "additional_context": context,
+    }
+    print(json.dumps(result, ensure_ascii=False), flush=True)
+
+
+def main() -> None:
+    try:
+        hook_input = 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))
+    if not data or data.get("status") not in ACTIONABLE_STATUSES:
+        return
+    _emit_context(_format_context(data))
+
+
+if __name__ == "__main__":
+    main()

package/src/cli.js

@@ -66,6 +66,9 @@ function printHelp() {
 用法:
   flower-trellis [init] [trellis flags] [flower flags]   安装 + 叠加强化包(默认命令)
   flower-trellis update [trellis flags] [flower flags]   升级 + 按新版本重新叠加
+  flower-trellis self-check --json [--target <dir>]      输出启动更新检查 JSON
+  flower-trellis self-update --target <dir> --yes        自更新 + 项目重叠加
+  flower-trellis update-check <get|set|disable|enable>   管理启动更新策略
   flower-trellis skill [flower flags]                    交互管理通用技能
   flower-trellis uninstall [-y | --dry-run]              卸载 + 清理强化残留
   flower-trellis <其它命令> [...]                        透传给 trellis(面向未来)
@@ -79,6 +82,12 @@ flower 自有 flag:
   --target <dir>           目标目录(默认当前目录)
   --no-update-check        本次跳过 flower-trellis 新版本检测(等价 FLOWER_NO_UPDATE_CHECK=1)
 
+启动更新检查:
+  self-check --json                 稳定输出检查 JSON
+  self-update --yes [--dry-run]     执行或预览全局更新与项目 update
+  update-check set --policy <off|notify|ask|auto> [--interval-hours <n>]
+  update-check disable|enable       只切换 enabled,不覆盖已选 policy
+
 命令别名:flower-trellis 可简写为 ftl 或 ft(三者完全等价)。
 init / update 启动时会顺带检测 flower-trellis 自身是否有新版(联网、带超时,失败静默)。
 skill 可启用或停用通用技能，并只读展示工作流强化包。
@@ -99,9 +108,17 @@ function parse(argv) {
   let updateCheck = true;
   const skills = [];
   const passthrough = [];
+  const forwarded = [];
 
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
+    if (a === "--") {
+      forwarded.push(...argv.slice(i + 1));
+      if (command !== "self-update") {
+        passthrough.push(...argv.slice(i + 1));
+      }
+      break;
+    }
     // 第一个非 flag token 视为子命令
     if (command === null && !a.startsWith("-")) {
       command = a;
@@ -143,6 +160,7 @@ function parse(argv) {
       skills,
       variant,
       updateCheck,
+      forwarded,
     },
   };
 }
@@ -179,6 +197,15 @@ async function main() {
     } else if (cmd === "update") {
       const { update } = await import("./commands/update.js");
       await update(ctx);
+    } else if (cmd === "self-check") {
+      const { selfCheck } = await import("./commands/self-check.js");
+      await selfCheck(ctx);
+    } else if (cmd === "self-update") {
+      const { selfUpdate } = await import("./commands/self-update.js");
+      await selfUpdate(ctx);
+    } else if (cmd === "update-check") {
+      const { updateCheck } = await import("./commands/update-check.js");
+      await updateCheck(ctx);
     } else if (cmd === "skill") {
       const { skill } = await import("./commands/skill.js");
       await skill(ctx);

package/src/commands/self-check.js

@@ -0,0 +1,19 @@
+import { buildSelfCheck } from "../lib/self-check.js";
+
+/**
+ * flower-trellis self-check:输出结构化启动更新检查结果。
+ *
+ * 供 Codex / Claude Code SessionStart hook 和 AI 自动化读取。无论是否发现更新,
+ * 都稳定输出 JSON,避免 hook 侧靠空 stdout 猜状态。
+ *
+ * @param {object} ctx 见 cli.js 的 parse()
+ * @returns {Promise<void>}
+ */
+export async function selfCheck(ctx) {
+  const forceRemote = ctx.passthrough.includes("--force-remote");
+  if (ctx.updateCheck === false) {
+    process.env.FLOWER_NO_UPDATE_CHECK = "1";
+  }
+  const result = await buildSelfCheck(ctx.target, { forceRemote });
+  console.log(JSON.stringify(result, null, 2));
+}

package/src/commands/self-update.js

@@ -0,0 +1,108 @@
+import { spawnSync } from "node:child_process";
+import {
+  buildSelfCheck,
+  projectUpdateCommand,
+  projectUpdateForwardArgs,
+  safetyState,
+} from "../lib/self-check.js";
+
+/** 判断参数里是否包含指定 flag。 */
+function hasFlag(args, name) {
+  return args.includes(name);
+}
+
+/** 执行命令并在失败时给出统一错误。 */
+function runCommand(command, args, cwd, failureMessage) {
+  const res = spawnSync(command, args, {
+    cwd,
+    stdio: "inherit",
+    shell: process.platform === "win32",
+  });
+  if (res.status !== 0) {
+    const reason = res.error ? res.error.message : `退出码 ${res.status ?? 1}`;
+    throw new Error(`${failureMessage}(${reason})`);
+  }
+}
+
+/**
+ * flower-trellis self-update:执行受控自更新与项目重叠加。
+ *
+ * 默认项目 update 阶段追加 `--force`,等价 Trellis 交互里的 Apply Overwrite to all。
+ * 用户可通过 `--` 透传 `--skip-all` / `--create-new` 等上游冲突策略覆盖默认。
+ *
+ * @param {object} ctx 见 cli.js 的 parse()
+ * @returns {Promise<void>}
+ */
+export async function selfUpdate(ctx) {
+  const dryRun = hasFlag(ctx.passthrough, "--dry-run");
+  const yes = hasFlag(ctx.passthrough, "--yes") || hasFlag(ctx.passthrough, "-y");
+  const projectOnly = hasFlag(ctx.passthrough, "--project-only");
+  const forwarded = ctx.forwarded || [];
+  const projectArgs = [
+    "update",
+    "--target",
+    ctx.target,
+    "--no-update-check",
+    ...projectUpdateForwardArgs(forwarded),
+  ];
+  const check = await buildSelfCheck(ctx.target, {
+    writeCache: !dryRun,
+    forceRemote: !projectOnly,
+  });
+  const shouldInstallFlower = !projectOnly && check.status === "update_available" && check.recommendation;
+  const effectiveSafety = check.safety || safetyState(
+    ctx.target,
+    projectOnly ? "project_out_of_sync" : check.status,
+    projectUpdateCommand(ctx.target, forwarded),
+  );
+
+  if (dryRun) {
+    console.log("self-update dry-run:");
+    if (shouldInstallFlower) {
+      console.log(`  · 全局升级:${check.recommendation.command}`);
+    } else {
+      console.log("  · 全局升级:跳过");
+    }
+    console.log(`  · 项目更新:${projectUpdateCommand(ctx.target, forwarded)}`);
+    console.log(`  · 当前状态:${check.status}`);
+    console.log(`  · 目标:${ctx.target}`);
+    console.log(`  · 当前 flower:${check.current?.flowerVersion || "unknown"}`);
+    console.log(`  · 项目 flower:${check.project?.flowerVersion || "unknown"}`);
+    console.log(`  · 捆绑 Trellis:${check.current?.bundledTrellisVersion || "unknown"}`);
+    console.log(`  · 项目 Trellis:${check.project?.trellisVersion || "unknown"}`);
+    console.log(
+      `  · 安全检查:${effectiveSafety.safe ? "通过" : `需确认(${effectiveSafety.reasons.join(", ") || "无可用结果"})`}`,
+    );
+    console.log(`  · 写入:否`);
+    return;
+  }
+
+  if (!yes) {
+    throw new Error("self-update 执行写入前需要 --yes;如需预览请使用 --dry-run");
+  }
+
+  if (!shouldInstallFlower && !projectOnly && check.status !== "project_out_of_sync") {
+    console.log(`  · 当前状态:${check.status},无需执行 self-update`);
+    return;
+  }
+
+  if (shouldInstallFlower) {
+    runCommand(
+      "npm",
+      ["i", "-g", `flower-trellis@${check.recommendation.tag}`],
+      ctx.target,
+      "全局 flower-trellis 升级失败",
+    );
+  } else {
+    console.log("  · 跳过全局 flower-trellis 升级");
+  }
+
+  runCommand(
+    "flower-trellis",
+    projectArgs,
+    ctx.target,
+    "目标项目重叠加失败,请手动运行:" + projectUpdateCommand(ctx.target, forwarded),
+  );
+
+  console.log(`\n🌸 flower-trellis self-update 完成 → ${ctx.target}`);
+}