flower-trellis 0.6.0-beta.3 → 0.6.0-beta.5

package/enhancements/0.6/.agents/skills/trellis-flower-update/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: trellis-flower-update
+description: "手动检查和执行已安装 Flower/Trellis 强化包升级。用于用户明确要求更新或升级 flower-trellis、Flower、Trellis 强化包、skill-garden 快照、项目 flower 版本追平，或自动更新提示被稍后/跳过后仍想在对话里升级时。不要用于用户说想发版、发布版本、release、打 tag、npm publish 或修改 package 版本号；这些属于项目发版流程。"
+---
+
+# Trellis Flower Update
+
+用于用户主动要求升级已安装的 Flower/Trellis 强化层时。自动 SessionStart 提示的 snooze、skip 和 cooldown 只是不主动打扰，不能阻止用户显式要求升级。
+
+本 skill 不是发版入口。用户说“我想发版了”、release、打 tag、npm publish、更新 package 版本号或准备发布包时，不使用本 skill；按当前项目的 release SOP、`trellis-release` 或发布规范处理。
+
+## Workflow
+
+1. 确认目标项目。用户给出路径时使用该路径，否则使用当前工作目录。
+2. 运行人工检查，默认强制刷新远端版本证据：
+
+```bash
+flower-trellis self-check --json --manual --force-remote --target <target>
+```
+
+3. 解析 JSON：
+   - `update_available`：展示当前版本、推荐版本、release notes 摘要和 `commands.recommended`。
+   - `project_out_of_sync`：展示当前 Flower/Trellis 与项目记录的差异，并展示 `commands.recommended`。
+   - `up_to_date`：说明当前安装和项目记录已一致。
+   - `disabled` / `offline` / `skipped`：说明原因；不要靠重置缓存伪造可执行状态。
+4. 写入前遵守确认和安全门槛：
+   - 用户当前消息已经明确要求执行升级时，可以执行 `commands.recommended`。
+   - 用户只是询问、查看或比较版本时，只展示结果并等待确认。
+   - `safety.reasons` 非空时，先说明风险，再等待用户明确确认。
+5. 执行推荐命令后读取 `<flower-update-result>`。如果结果要求 `run_trellis_push_confirmation`，进入 `trellis-push`，展示文件和 commit message 后等待确认。
+
+## Rules
+
+- 不直接读写 `.flower/update-check.tmp`。
+- 不使用 `update-check reset`、`snooze` 或 `skip` 作为升级绕过手段。
+- 不运行 `npm run release`、不打 tag、不 publish，也不修改 `package.json` 版本号。
+- 不把 `self-check --manual` 用在 SessionStart 自动 hook；自动路径必须继续尊重提示节流。
+- 目标项目有脏文件、活动任务或命令缺失时，按 `safety.reasons` 报告并等待用户确认。

package/enhancements/0.6/.agents/skills/trellis-worktree/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: trellis-worktree
+description: "Prepare and diagnose Trellis usage inside linked Git worktrees. Use when the user mentions worktree, linked worktree, worktree development, missing .trellis in a worktree, or asks to make .claude/.codex/.agents/Trellis files work from a worktree."
+---
+
+# Trellis Worktree
+
+Use this skill before normal Trellis routing when the user's current request is about using Trellis from a linked Git worktree.
+
+The problem is usually not task or untracked routing itself: linked worktrees often do not contain the untracked `.trellis`, `.agents`, `.codex`, or `.claude` directories that AI tools need before any Trellis hook or skill can run.
+
+## Workflow
+
+1. Identify the target worktree. Use the user's explicit path if present; otherwise use the current working directory.
+2. Locate a source worktree in the same Git worktree set that contains `.trellis/scripts/worktree_setup.py`.
+3. Run read-only diagnosis first:
+
+```bash
+python3 <source-worktree>/.trellis/scripts/worktree_setup.py status --target <target-worktree> --json
+```
+
+4. If status is `needs-prepare`, run:
+
+```bash
+python3 <source-worktree>/.trellis/scripts/worktree_setup.py prepare --target <target-worktree> --json
+```
+
+5. If status is `blocked` or `error`, stop and report the reason and conflict paths. Do not overwrite or delete user files.
+6. After `ready` or `prepared`, return to the user's original Trellis intent and follow the normal workflow state.
+
+## Source Worktree Discovery
+
+If `<source-worktree>` is not obvious, inspect Git worktrees:
+
+```bash
+git -C <target-worktree> worktree list --porcelain
+```
+
+Choose a listed worktree that contains `.trellis/scripts/worktree_setup.py`. If none exists, report that this project has not been updated with `trellis-worktree` support yet.
+
+## Safety Rules
+
+- The helper only projects source paths that already exist.
+- MVP projection paths are `.trellis`, `.agents`, `.codex`, and `.claude`.
+- Projection uses symlinks and records `<target-worktree>/.trellis-worktree.json`.
+- Existing non-managed `.codex`, `.claude`, `.agents`, or `.trellis` paths are conflicts.
+- Do not hand-copy platform directories. Copying creates drift between worktrees.
+- Do not treat successful setup as task approval, check approval, or push approval.
+
+## Expected Results
+
+- `ready`: target worktree already has valid Trellis entry points.
+- `needs-prepare`: target worktree is safe to prepare; run `prepare`.
+- `prepared`: symlinks and manifest were created or repaired.
+- `blocked`: user-owned paths would be overwritten; stop and report `conflicts`.
+- `error`: Git or source-root resolution failed; stop and report `reason`.

package/enhancements/0.6/.claude/skills/trellis-flower-update/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: trellis-flower-update
+description: "手动检查和执行已安装 Flower/Trellis 强化包升级。用于用户明确要求更新或升级 flower-trellis、Flower、Trellis 强化包、skill-garden 快照、项目 flower 版本追平，或自动更新提示被稍后/跳过后仍想在对话里升级时。不要用于用户说想发版、发布版本、release、打 tag、npm publish 或修改 package 版本号；这些属于项目发版流程。"
+---
+
+# Trellis Flower Update
+
+用于用户主动要求升级已安装的 Flower/Trellis 强化层时。自动 SessionStart 提示的 snooze、skip 和 cooldown 只是不主动打扰，不能阻止用户显式要求升级。
+
+本 skill 不是发版入口。用户说“我想发版了”、release、打 tag、npm publish、更新 package 版本号或准备发布包时，不使用本 skill；按当前项目的 release SOP、`trellis-release` 或发布规范处理。
+
+## Workflow
+
+1. 确认目标项目。用户给出路径时使用该路径，否则使用当前工作目录。
+2. 运行人工检查，默认强制刷新远端版本证据：
+
+```bash
+flower-trellis self-check --json --manual --force-remote --target <target>
+```
+
+3. 解析 JSON：
+   - `update_available`：展示当前版本、推荐版本、release notes 摘要和 `commands.recommended`。
+   - `project_out_of_sync`：展示当前 Flower/Trellis 与项目记录的差异，并展示 `commands.recommended`。
+   - `up_to_date`：说明当前安装和项目记录已一致。
+   - `disabled` / `offline` / `skipped`：说明原因；不要靠重置缓存伪造可执行状态。
+4. 写入前遵守确认和安全门槛：
+   - 用户当前消息已经明确要求执行升级时，可以执行 `commands.recommended`。
+   - 用户只是询问、查看或比较版本时，只展示结果并等待确认。
+   - `safety.reasons` 非空时，先说明风险，再等待用户明确确认。
+5. 执行推荐命令后读取 `<flower-update-result>`。如果结果要求 `run_trellis_push_confirmation`，进入 `trellis-push`，展示文件和 commit message 后等待确认。
+
+## Rules
+
+- 不直接读写 `.flower/update-check.tmp`。
+- 不使用 `update-check reset`、`snooze` 或 `skip` 作为升级绕过手段。
+- 不运行 `npm run release`、不打 tag、不 publish，也不修改 `package.json` 版本号。
+- 不把 `self-check --manual` 用在 SessionStart 自动 hook；自动路径必须继续尊重提示节流。
+- 目标项目有脏文件、活动任务或命令缺失时，按 `safety.reasons` 报告并等待用户确认。

package/enhancements/0.6/.claude/skills/trellis-worktree/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: trellis-worktree
+description: "Prepare and diagnose Trellis usage inside linked Git worktrees. Use when the user mentions worktree, linked worktree, worktree development, missing .trellis in a worktree, or asks to make .claude/.codex/.agents/Trellis files work from a worktree."
+---
+
+# Trellis Worktree
+
+Use this skill before normal Trellis routing when the user's current request is about using Trellis from a linked Git worktree.
+
+The problem is usually not task or untracked routing itself: linked worktrees often do not contain the untracked `.trellis`, `.agents`, `.codex`, or `.claude` directories that AI tools need before any Trellis hook or skill can run.
+
+## Workflow
+
+1. Identify the target worktree. Use the user's explicit path if present; otherwise use the current working directory.
+2. Locate a source worktree in the same Git worktree set that contains `.trellis/scripts/worktree_setup.py`.
+3. Run read-only diagnosis first:
+
+```bash
+python3 <source-worktree>/.trellis/scripts/worktree_setup.py status --target <target-worktree> --json
+```
+
+4. If status is `needs-prepare`, run:
+
+```bash
+python3 <source-worktree>/.trellis/scripts/worktree_setup.py prepare --target <target-worktree> --json
+```
+
+5. If status is `blocked` or `error`, stop and report the reason and conflict paths. Do not overwrite or delete user files.
+6. After `ready` or `prepared`, return to the user's original Trellis intent and follow the normal workflow state.
+
+## Source Worktree Discovery
+
+If `<source-worktree>` is not obvious, inspect Git worktrees:
+
+```bash
+git -C <target-worktree> worktree list --porcelain
+```
+
+Choose a listed worktree that contains `.trellis/scripts/worktree_setup.py`. If none exists, report that this project has not been updated with `trellis-worktree` support yet.
+
+## Safety Rules
+
+- The helper only projects source paths that already exist.
+- MVP projection paths are `.trellis`, `.agents`, `.codex`, and `.claude`.
+- Projection uses symlinks and records `<target-worktree>/.trellis-worktree.json`.
+- Existing non-managed `.codex`, `.claude`, `.agents`, or `.trellis` paths are conflicts.
+- Do not hand-copy platform directories. Copying creates drift between worktrees.
+- Do not treat successful setup as task approval, check approval, or push approval.
+
+## Expected Results
+
+- `ready`: target worktree already has valid Trellis entry points.
+- `needs-prepare`: target worktree is safe to prepare; run `prepare`.
+- `prepared`: symlinks and manifest were created or repaired.
+- `blocked`: user-owned paths would be overwritten; stop and report `conflicts`.
+- `error`: Git or source-root resolution failed; stop and report `reason`.

package/enhancements/0.6/overrides/conflicts.json

@@ -303,6 +303,7 @@
       "severity": "error",
       "target": ".codex/hooks/inject-workflow-state.py",
       "whenOperations": [
+        "workflow-state-worktree-root-fallback",
         "workflow-state-codex-session-start-guard",
         "workflow-state-stale-task-status",
         "workflow-state-untracked-helper",
@@ -312,11 +313,13 @@
       "assertion": {
         "type": "required-literal",
         "values": [
+          "# BEGIN skill-garden patch workflow-state-worktree-root-fallback v0.6",
           "# BEGIN skill-garden patch workflow-state-codex-session-start-guard v0.6",
           "# BEGIN skill-garden patch workflow-state-stale-task-status v0.6",
           "# BEGIN skill-garden patch workflow-state-untracked-helper v0.6",
           "# BEGIN skill-garden patch workflow-state-breadcrumb-subject v0.6",
           "# BEGIN skill-garden patch workflow-state-main-subject-routing v0.6",
+          "_find_trellis_root_from_git",
           "DEFAULT_PROMPT_INJECTION_SKIP_KEYWORD = \"no-trellis\"",
           "\"ZCODE_PROJECT_DIR\": \"zcode\"",
           "Normalize `codex.dispatch_mode` from .trellis/config.yaml to \"auto\" or \"inline\"."

package/enhancements/0.6/overrides/patches/hooks/inject-workflow-state/shared-runtime/patch.json

@@ -3,6 +3,25 @@
   "id": "inject-workflow-state-shared-runtime",
   "purpose": "hook_override",
   "operations": [
+    {
+      "id": "workflow-state-worktree-root-fallback",
+      "operation": "replace",
+      "targetPolicy": "each-existing",
+      "targets": [
+        { "kind": "file", "path": ".codex/hooks/inject-workflow-state.py", "missing": "skip", "markerStyle": "hash" },
+        { "kind": "file", "path": ".claude/hooks/inject-workflow-state.py", "missing": "skip", "markerStyle": "hash" },
+        { "kind": "file", "path": ".gemini/hooks/inject-workflow-state.py", "missing": "skip", "markerStyle": "hash" },
+        { "kind": "file", "path": ".qoder/hooks/inject-workflow-state.py", "missing": "skip", "markerStyle": "hash" },
+        { "kind": "file", "path": ".github/copilot/hooks/inject-workflow-state.py", "missing": "skip", "markerStyle": "hash" },
+        { "kind": "file", "path": ".codebuddy/hooks/inject-workflow-state.py", "missing": "skip", "markerStyle": "hash" },
+        { "kind": "file", "path": ".factory/hooks/inject-workflow-state.py", "missing": "skip", "markerStyle": "hash" },
+        { "kind": "file", "path": ".kiro/hooks/inject-workflow-state.py", "missing": "skip", "markerStyle": "hash" },
+        { "kind": "file", "path": ".trae/hooks/inject-workflow-state.py", "missing": "skip", "markerStyle": "hash" },
+        { "kind": "file", "path": ".zcode/hooks/inject-workflow-state.py", "missing": "skip", "markerStyle": "hash" }
+      ],
+      "selector": { "type": "literal", "source": "worktree-root-selector.py" },
+      "content": { "source": "worktree-root-content.py" }
+    },
     {
       "id": "workflow-state-codex-session-start-guard",
       "operation": "insert",

package/enhancements/0.6/overrides/patches/hooks/inject-workflow-state/shared-runtime/worktree-root-content.py

@@ -0,0 +1,70 @@
+def _git_output(start: Path, *args: str) -> Optional[str]:
+    """Run a read-only git command for best-effort Trellis root fallback."""
+    import subprocess
+
+    try:
+        result = subprocess.run(
+            ["git", "-C", str(start), *args],
+            check=False,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.DEVNULL,
+            text=True,
+            timeout=2,
+        )
+    except (OSError, subprocess.SubprocessError):
+        return None
+    if result.returncode != 0:
+        return None
+    output = result.stdout.strip()
+    return output or None
+
+
+def _resolve_git_common_dir(start: Path) -> Optional[Path]:
+    """Return the current repository's common git dir."""
+    output = _git_output(start, "rev-parse", "--path-format=absolute", "--git-common-dir")
+    if output is None:
+        output = _git_output(start, "rev-parse", "--git-common-dir")
+    if output is None:
+        return None
+    common_dir = Path(output)
+    if common_dir.is_absolute():
+        return common_dir.resolve()
+    top_level = _git_output(start, "rev-parse", "--show-toplevel")
+    if top_level is None:
+        return None
+    return (Path(top_level) / common_dir).resolve()
+
+
+def _find_trellis_root_from_git(start: Path) -> Optional[Path]:
+    """Find a sibling worktree that carries .trellis/ for this Git repository."""
+    common_dir = _resolve_git_common_dir(start)
+    if common_dir is not None:
+        candidate = common_dir.parent
+        if (candidate / ".trellis").is_dir():
+            return candidate
+
+    output = _git_output(start, "worktree", "list", "--porcelain")
+    if output is None:
+        return None
+    for line in output.splitlines():
+        if not line.startswith("worktree "):
+            continue
+        candidate = Path(line.split(" ", 1)[1]).expanduser().resolve()
+        if (candidate / ".trellis").is_dir():
+            return candidate
+    return None
+
+
+def find_trellis_root(start: Path) -> Optional[Path]:
+    """Walk up from start, then fall back to the Git worktree carrying .trellis/.
+
+    Linked worktrees often do not contain the untracked .trellis/ runtime. The
+    hook still needs the main worktree's runtime state so direct-edit cursors can
+    be resumed from the linked worktree without copying .trellis/.
+    """
+    cur = start.resolve()
+    while cur != cur.parent:
+        if (cur / ".trellis").is_dir():
+            return cur
+        cur = cur.parent
+    return _find_trellis_root_from_git(start.resolve())

package/enhancements/0.6/overrides/patches/hooks/inject-workflow-state/shared-runtime/worktree-root-selector.py

@@ -0,0 +1,12 @@
+def find_trellis_root(start: Path) -> Optional[Path]:
+    """Walk up from start to find directory containing .trellis/.
+
+    Handles CWD drift: subdirectory launches, monorepo packages, etc.
+    Returns None if no .trellis/ found (silent no-op).
+    """
+    cur = start.resolve()
+    while cur != cur.parent:
+        if (cur / ".trellis").is_dir():
+            return cur
+        cur = cur.parent
+    return None

package/enhancements/0.6/scripts/untracked_flow.py

@@ -6,6 +6,7 @@ from __future__ import annotations
 import argparse
 import json
 import os
+import subprocess
 import sys
 import tempfile
 import uuid
@@ -82,9 +83,9 @@ def _utc_now() -> str:
     return datetime.now(timezone.utc).replace(microsecond=0).isoformat().replace("+00:00", "Z")
 
 
-def _find_repo_root(start: Path | None = None) -> Path | None:
-    """从当前路径向上查找 Trellis 项目根目录。"""
-    current = (start or Path.cwd()).resolve()
+def _find_root_upwards(start: Path) -> Path | None:
+    """从指定路径向上查找带 .trellis 的目录。"""
+    current = start.resolve()
     if current.is_file():
         current = current.parent
     while True:
@@ -95,6 +96,80 @@ def _find_repo_root(start: Path | None = None) -> Path | None:
         current = current.parent
 
 
+def _git_output(start: Path, *args: str) -> str | None:
+    """执行只读 git 命令并返回 stdout，失败时返回 None。"""
+    try:
+        result = subprocess.run(
+            ["git", "-C", str(start), *args],
+            check=False,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.DEVNULL,
+            text=True,
+            timeout=2,
+        )
+    except (OSError, subprocess.SubprocessError):
+        return None
+    if result.returncode != 0:
+        return None
+    output = result.stdout.strip()
+    return output or None
+
+
+def _resolve_git_common_dir(start: Path) -> Path | None:
+    """返回当前 Git 仓库的 common dir，兼容旧 git 的相对路径输出。"""
+    output = _git_output(start, "rev-parse", "--path-format=absolute", "--git-common-dir")
+    if output is None:
+        output = _git_output(start, "rev-parse", "--git-common-dir")
+    if output is None:
+        return None
+    common_dir = Path(output)
+    if common_dir.is_absolute():
+        return common_dir.resolve()
+    top_level = _git_output(start, "rev-parse", "--show-toplevel")
+    if top_level is None:
+        return None
+    return (Path(top_level) / common_dir).resolve()
+
+
+def _find_root_from_git_worktrees(start: Path) -> Path | None:
+    """从同一个 Git worktree 集合里寻找承载 .trellis 的主项目根。"""
+    current = start.resolve()
+    if current.is_file():
+        current = current.parent
+
+    common_dir = _resolve_git_common_dir(current)
+    if common_dir is not None:
+        candidate = common_dir.parent
+        if (candidate / ".trellis").is_dir():
+            return candidate
+
+    output = _git_output(current, "worktree", "list", "--porcelain")
+    if output is None:
+        return None
+    for line in output.splitlines():
+        if not line.startswith("worktree "):
+            continue
+        candidate = Path(line.split(" ", 1)[1]).expanduser().resolve()
+        if (candidate / ".trellis").is_dir():
+            return candidate
+    return None
+
+
+def _find_repo_root(start: Path | None = None) -> Path | None:
+    """查找 Trellis 项目根目录，兼容没有 .trellis 的 linked worktree。"""
+    current = (start or Path.cwd()).resolve()
+    root = _find_root_upwards(current)
+    if root is not None:
+        return root
+    root = _find_root_from_git_worktrees(current)
+    if root is not None:
+        return root
+    for parent in Path(__file__).resolve().parents:
+        if (parent / ".trellis").is_dir():
+            return parent
+    return None
+
+
 def _session_path(repo_root: Path, context_key: str) -> Path:
     """返回指定 session runtime 文件路径。"""
     return repo_root / ".trellis/.runtime/sessions" / f"{context_key}.json"