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

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-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"

package/enhancements/0.6/scripts/worktree_setup.py

@@ -0,0 +1,422 @@
+#!/usr/bin/env python3
+"""准备 linked worktree 中的 Trellis 入口投影。"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import subprocess
+import sys
+import tempfile
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+
+SCHEMA_VERSION = 1
+MANIFEST_NAME = ".trellis-worktree.json"
+ENTRY_PATHS = (".trellis", ".agents", ".codex", ".claude")
+
+
+class WorktreeSetupError(Exception):
+    """携带稳定 reason code 的 worktree 准备错误。"""
+
+    def __init__(self, reason: str, message: str, **details: Any) -> None:
+        """初始化结构化准备错误。
+
+        Args:
+            reason: 稳定机器错误码。
+            message: 中文诊断说明。
+            **details: 与错误相关的状态详情。
+        """
+        super().__init__(message)
+        self.reason = reason
+        self.details = details
+
+
+def _utc_now() -> str:
+    """返回秒级 UTC ISO-8601 时间。"""
+    return datetime.now(timezone.utc).replace(microsecond=0).isoformat().replace("+00:00", "Z")
+
+
+def _path_text(path: Path) -> str:
+    """返回稳定的绝对路径字符串，但不跟随最终 symlink。"""
+    return os.path.abspath(os.fspath(path.expanduser()))
+
+
+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_start(path_text: str | None) -> Path:
+    """解析用户传入的 target，允许传入 worktree 子目录。"""
+    path = Path(path_text or os.getcwd()).expanduser()
+    if not path.exists():
+        raise WorktreeSetupError("target-missing", "目标路径不存在", target=str(path))
+    resolved = path.resolve()
+    return resolved.parent if resolved.is_file() else resolved
+
+
+def _git_toplevel(start: Path) -> Path | None:
+    """返回当前 Git worktree 根目录。"""
+    output = _git_output(start, "rev-parse", "--path-format=absolute", "--show-toplevel")
+    if output is None:
+        output = _git_output(start, "rev-parse", "--show-toplevel")
+    return Path(output).expanduser().resolve() if output else None
+
+
+def _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_toplevel(start)
+    if top_level is None:
+        return None
+    return (top_level / common_dir).resolve()
+
+
+def _manifest_path(target_root: Path) -> Path:
+    """返回目标 worktree 的投影 manifest 路径。"""
+    return target_root / MANIFEST_NAME
+
+
+def _read_manifest(target_root: Path) -> tuple[str, dict[str, Any] | None]:
+    """读取 manifest，并保留缺失和损坏差异。"""
+    path = _manifest_path(target_root)
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except FileNotFoundError:
+        return "missing", None
+    except (json.JSONDecodeError, OSError):
+        return "invalid", None
+    if not isinstance(data, dict):
+        return "invalid", None
+    return "ok", data
+
+
+def _manifest_source(target_root: Path, manifest: dict[str, Any] | None) -> Path | None:
+    """从有效 manifest 中读取 sourceRoot。"""
+    if not isinstance(manifest, dict) or manifest.get("schemaVersion") != SCHEMA_VERSION:
+        return None
+    target_text = manifest.get("targetRoot")
+    source_text = manifest.get("sourceRoot")
+    if not isinstance(target_text, str) or not isinstance(source_text, str):
+        return None
+    if Path(target_text).expanduser().resolve() != target_root:
+        return None
+    source_root = Path(source_text).expanduser().resolve()
+    return source_root if (source_root / ".trellis").is_dir() else None
+
+
+def _manifest_paths(manifest: dict[str, Any] | None) -> set[str]:
+    """返回 manifest 记录的受管相对路径集合。"""
+    links = manifest.get("links") if isinstance(manifest, dict) else None
+    if not isinstance(links, list):
+        return set()
+    result: set[str] = set()
+    for item in links:
+        if not isinstance(item, dict):
+            continue
+        path = item.get("path")
+        if isinstance(path, str) and path in ENTRY_PATHS:
+            result.add(path)
+    return result
+
+
+def _source_from_trellis_symlink(target_root: Path) -> Path | None:
+    """从目标 .trellis symlink 反推出主 worktree 根。"""
+    trellis_path = target_root / ".trellis"
+    if not trellis_path.is_symlink():
+        return None
+    source_path = trellis_path.resolve(strict=False)
+    if source_path.name != ".trellis":
+        return None
+    source_root = source_path.parent
+    return source_root if source_path.is_dir() else None
+
+
+def _source_from_git(target_root: Path) -> Path | None:
+    """从同一个 Git worktree 集合中寻找带 .trellis 的主 worktree。"""
+    common_dir = _git_common_dir(target_root)
+    if common_dir is not None:
+        candidate = common_dir.parent
+        if candidate != target_root and (candidate / ".trellis").is_dir():
+            return candidate
+
+    output = _git_output(target_root, "worktree", "list", "--porcelain")
+    if output is None:
+        return None
+    fallback: Path | None = None
+    for line in output.splitlines():
+        if not line.startswith("worktree "):
+            continue
+        candidate = Path(line.split(" ", 1)[1]).expanduser().resolve()
+        if not (candidate / ".trellis").is_dir():
+            continue
+        if candidate != target_root:
+            return candidate
+        fallback = candidate
+    return fallback
+
+
+def _resolve_source_root(
+    target_root: Path,
+    manifest: dict[str, Any] | None,
+) -> tuple[Path, str]:
+    """解析承载 .trellis 的源 worktree。"""
+    source = _manifest_source(target_root, manifest)
+    if source is not None:
+        return source, "manifest"
+
+    source = _source_from_trellis_symlink(target_root)
+    if source is not None:
+        return source, "trellis-symlink"
+
+    source = _source_from_git(target_root)
+    if source is not None:
+        return source, "git-worktree"
+
+    if (target_root / ".trellis").is_dir():
+        return target_root, "target-root"
+
+    raise WorktreeSetupError(
+        "source-not-found",
+        "无法在当前 Git worktree 集合中找到承载 .trellis 的主 worktree",
+        targetRoot=_path_text(target_root),
+    )
+
+
+def _same_symlink_target(link: Path, source: Path) -> bool:
+    """判断 symlink 是否已经指向期望源路径。"""
+    try:
+        raw_target = Path(os.readlink(link))
+    except OSError:
+        return False
+    actual = raw_target if raw_target.is_absolute() else (link.parent / raw_target)
+    return actual.resolve(strict=False) == source.resolve(strict=False)
+
+
+def _classify_link(
+    source_root: Path,
+    target_root: Path,
+    rel_path: str,
+    managed_paths: set[str],
+) -> dict[str, Any]:
+    """判断单个入口路径的投影状态。"""
+    source = source_root / rel_path
+    target = target_root / rel_path
+    item = {
+        "path": rel_path,
+        "source": _path_text(source),
+        "target": _path_text(target),
+    }
+
+    if not source.exists() and not source.is_symlink():
+        return {**item, "state": "source-missing"}
+    if source_root == target_root:
+        return {**item, "state": "ready"}
+    if target.is_symlink():
+        if _same_symlink_target(target, source):
+            return {**item, "state": "ready"}
+        if rel_path in managed_paths:
+            return {**item, "state": "repair"}
+        return {**item, "state": "conflict", "reason": "symlink-target-mismatch"}
+    if target.exists():
+        return {**item, "state": "conflict", "reason": "target-exists"}
+    return {**item, "state": "create"}
+
+
+def _analyze(target_arg: str | None) -> dict[str, Any]:
+    """生成 worktree 准备计划，不写盘。"""
+    start = _resolve_start(target_arg)
+    target_root = _git_toplevel(start)
+    if target_root is None:
+        raise WorktreeSetupError("not-git-worktree", "目标路径不在 Git worktree 中", target=str(start))
+
+    manifest_status, manifest = _read_manifest(target_root)
+    source_root, source = _resolve_source_root(target_root, manifest)
+    managed_paths = _manifest_paths(manifest)
+    links = [
+        _classify_link(source_root, target_root, rel_path, managed_paths)
+        for rel_path in ENTRY_PATHS
+    ]
+    actions = [link for link in links if link["state"] in {"create", "repair"}]
+    conflicts = [link for link in links if link["state"] == "conflict"]
+    missing_sources = [link for link in links if link["state"] == "source-missing"]
+
+    status = "ready"
+    if conflicts:
+        status = "blocked"
+    elif actions:
+        status = "needs-prepare"
+
+    return {
+        "status": status,
+        "targetRoot": _path_text(target_root),
+        "sourceRoot": _path_text(source_root),
+        "source": source,
+        "manifest": {
+            "path": _path_text(_manifest_path(target_root)),
+            "status": manifest_status,
+        },
+        "links": links,
+        "actions": actions,
+        "conflicts": conflicts,
+        "missingSources": missing_sources,
+    }
+
+
+def _desired_manifest(plan: dict[str, Any]) -> dict[str, Any]:
+    """构造当前投影的 manifest 内容。"""
+    links = [
+        {
+            "path": link["path"],
+            "source": link["source"],
+            "target": link["target"],
+        }
+        for link in plan["links"]
+        if link["state"] != "source-missing"
+    ]
+    return {
+        "schemaVersion": SCHEMA_VERSION,
+        "sourceRoot": plan["sourceRoot"],
+        "targetRoot": plan["targetRoot"],
+        "links": links,
+    }
+
+
+def _manifest_matches(path: Path, desired: dict[str, Any]) -> bool:
+    """判断现有 manifest 是否已经与期望投影一致，忽略 updatedAt。"""
+    try:
+        current = json.loads(path.read_text(encoding="utf-8"))
+    except (FileNotFoundError, json.JSONDecodeError, OSError):
+        return False
+    if not isinstance(current, dict):
+        return False
+    comparable = {key: current.get(key) for key in ("schemaVersion", "sourceRoot", "targetRoot", "links")}
+    return comparable == desired
+
+
+def _write_manifest(path: Path, desired: dict[str, Any]) -> None:
+    """原子写入 worktree 投影 manifest。"""
+    data = {**desired, "updatedAt": _utc_now()}
+    descriptor, temp_name = tempfile.mkstemp(
+        prefix=f".{path.name}.",
+        suffix=".tmp",
+        dir=path.parent,
+    )
+    temp_path = Path(temp_name)
+    try:
+        with os.fdopen(descriptor, "w", encoding="utf-8") as handle:
+            handle.write(json.dumps(data, indent=2, ensure_ascii=False) + "\n")
+            handle.flush()
+            os.fsync(handle.fileno())
+        os.replace(temp_path, path)
+    except Exception:
+        try:
+            temp_path.unlink()
+        except FileNotFoundError:
+            pass
+        raise
+
+
+def _apply_plan(plan: dict[str, Any]) -> dict[str, Any]:
+    """执行准备计划并返回写盘结果。"""
+    if plan["status"] == "blocked":
+        raise WorktreeSetupError(
+            "projection-conflict",
+            "目标 worktree 中存在非 trellis-worktree 管理的入口路径，已拒绝覆盖",
+            conflicts=plan["conflicts"],
+        )
+
+    changed_links: list[str] = []
+    for action in plan["actions"]:
+        source = Path(action["source"])
+        target = Path(action["target"])
+        if action["state"] == "repair":
+            target.unlink()
+        os.symlink(source, target, target_is_directory=source.is_dir())
+        changed_links.append(action["path"])
+
+    manifest_written = False
+    if plan["sourceRoot"] != plan["targetRoot"]:
+        manifest_path = Path(plan["manifest"]["path"])
+        desired = _desired_manifest(plan)
+        if changed_links or not _manifest_matches(manifest_path, desired):
+            _write_manifest(manifest_path, desired)
+            manifest_written = True
+
+    status = "prepared" if changed_links or manifest_written else "ready"
+    return {
+        **plan,
+        "status": status,
+        "changed": bool(changed_links or manifest_written),
+        "changedLinks": changed_links,
+        "manifestWritten": manifest_written,
+    }
+
+
+def _emit(payload: dict[str, Any], *, compact: bool) -> None:
+    """向 stdout 输出 JSON。"""
+    print(json.dumps(payload, ensure_ascii=False, sort_keys=True if compact else False, indent=None if compact else 2))
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """构造 worktree setup CLI parser。"""
+    parser = argparse.ArgumentParser(description="Trellis linked worktree setup helper")
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    for command in ("status", "prepare"):
+        command_parser = subparsers.add_parser(command)
+        command_parser.add_argument("--target", help="linked worktree path; defaults to cwd")
+        command_parser.add_argument("--json", action="store_true", help="emit compact stable JSON")
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    """执行 worktree setup CLI。"""
+    args = build_parser().parse_args(argv)
+    compact = bool(getattr(args, "json", False))
+    try:
+        plan = _analyze(args.target)
+        payload = _apply_plan(plan) if args.command == "prepare" else plan
+        _emit(payload, compact=compact)
+        return 0
+    except (WorktreeSetupError, OSError) as error:
+        if isinstance(error, WorktreeSetupError):
+            payload = {
+                "status": "error",
+                "reason": error.reason,
+                "message": str(error),
+                **error.details,
+            }
+        else:
+            payload = {"status": "error", "reason": "worktree-setup-failed", "message": str(error)}
+        _emit(payload, compact=compact)
+        return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/enhancements/MANIFEST.json

@@ -1,7 +1,7 @@
 {
-  "syncedAt": "2026-08-04T02:44:38.844Z",
+  "syncedAt": "2026-08-04T10:14:37.206Z",
   "syncedFrom": "vendor/skill-garden",
-  "sourceCommit": "32477325abe35122e9b12d4cc257fab9c7576c48",
+  "sourceCommit": "5dbd85563bd521a93fcde4fe8b3e00993d75e7b6",
   "common": {
     "codexSkills": [
       "aliyun-sls-query",
@@ -112,7 +112,8 @@
         "trellis-run-full-chain",
         "trellis-task-brief",
         "trellis-verify-task",
-        "trellis-visualize"
+        "trellis-visualize",
+        "trellis-worktree"
       ],
       "agentsSkills": [
         "trellis-auto-loop",
@@ -127,7 +128,8 @@
         "trellis-run-full-chain",
         "trellis-task-brief",
         "trellis-verify-task",
-        "trellis-visualize"
+        "trellis-visualize",
+        "trellis-worktree"
       ],
       "commands": [],
       "overrides": [],
@@ -168,6 +170,8 @@
         "hooks/inject-workflow-state/shared-runtime/stale-task-selector.py",
         "hooks/inject-workflow-state/shared-runtime/untracked-helper-content.py",
         "hooks/inject-workflow-state/shared-runtime/untracked-helper-selector.py",
+        "hooks/inject-workflow-state/shared-runtime/worktree-root-content.py",
+        "hooks/inject-workflow-state/shared-runtime/worktree-root-selector.py",
         "hooks/session-start/pre-check-hold/claude-content.py",
         "hooks/session-start/pre-check-hold/claude-selector.py",
         "hooks/session-start/pre-check-hold/codex-content.py",
@@ -432,7 +436,8 @@
         "spec_router.py",
         "task_intent.py",
         "task_progress.py",
-        "untracked_flow.py"
+        "untracked_flow.py",
+        "worktree_setup.py"
       ]
     }
   }

package/enhancements/common/.common/.claude/skills/humanize-writing/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: humanize-writing
-description: "中文文本润色与去 AI 腔改写。用于用户要求润色中文、去掉 AI 味、改得像人写的、自然化表达、优化中文语气、压缩空话、保留原意但让文字更顺时触发。"
+description: "中文文本润色与去 AI 腔改写。用于用户要求润色中文、去掉 AI 味、改得像人写的、自然化表达、优化中文语气、压缩空话、调整人味、保留原意但让文字更顺时触发。"
 ---
 
 # 中文写作人味化：移除 AI 写作痕迹
 
-你是中文写作编辑。用户给出中文文本时，目标不是炫技改写，而是在保留原意、信息量和必要结构的前提下，识别并移除常见 AI 写作痕迹，让文字更像真实的人写出来。
+你是中文写作编辑。用户给出中文文本时，目标不是炫技改写，也不是规避检测器，而是在保留原意、信息量和必要结构的前提下，识别并移除常见 AI 写作痕迹，让文字恢复真实作者会采用的表达方式。
 
 本技能的重点是中文文本。遇到英文术语、专有名词、代码、引用、标题或用户明确要求保留的表达时，不要为了“中文化”强行改掉。
 
@@ -13,17 +13,98 @@ description: "中文文本润色与去 AI 腔改写。用于用户要求润色
 
 处理需要自然化的文本时：
 
-1. **识别 AI 痕迹**：按下方规则扫描空话、套话、机械结构、虚假深度、过度客气和不自然标点。
-2. **改写，不是删除**：把 AI 腔换成自然中文，同时覆盖原文的全部信息。原文有五段，改写后也应大致保留五段的信息量和节奏。
-3. **保留原意**：不新增事实、结论、数据、承诺、情绪或立场。
-4. **匹配语气**：按文本用途选择正式、日常、技术、商务、评论、笔记等语气。只有当内容和作者声音需要时，才加入个性。
+1. **先判断场景**：确认文本是技术文档、PRD、说明、商务沟通、公告、评论、博客、社交文案还是个人表达。
+2. **选择去味强度**：默认中度处理；正式、高风险文本只做轻度清晰化；用户明确要求“狠一点”“像真人”时才做强度改写。
+3. **识别 AI 痕迹**：按下方规则扫描空话、套话、机械结构、虚假深度、过度客气、不自然标点和均匀节奏。
+4. **改写，不是删除**：把 AI 腔换成自然中文，同时覆盖原文的全部信息。原文有五段，改写后也应大致保留五段的信息量和节奏。
+5. **保留原意**：不新增事实、结论、数据、承诺、情绪或立场。
+6. **匹配语气**：按文本用途选择正式、日常、技术、商务、评论、笔记等语气。只有当内容和作者声音需要时，才加入个性。
 
 处理流程和输出要求见文末“处理流程与输出”。
 
+## 判断顺序
+
+去 AI 味时按这个顺序决策：
+
+1. **先保真**：人物、对象、时间、数字、因果、限制条件、风险提示和结论不能变。
+2. **再定场景**：不同文本允许的改写自由度不同。技术说明要清楚，个人表达才需要更明显的人声。
+3. **再定声线**：有样本时匹配作者 voice；没有样本时只调整当前文本 tone，不凭空创造作者人格。
+4. **最后动句子**：替换套话、拆开机械结构、补动作主体、调整节奏。
+
+不要一上来就替换禁用词。AI 味常来自结构和信息组织，不只是某几个词。
+
+## 文本场景与去味强度
+
+### 场景模式
+
+- **技术文档 / PRD / 说明 / release note**：重点是动作、边界、条件和结果。保留术语、字段名、路径、版本号、接口名和命令。可以减少官话和被动句，但不要加情绪、段子或第一人称。
+- **商务沟通 / 工作汇报 / 周报**：先结论，再事实，再下一步。删掉拔高意义、套话式总结和过度客气，保留必要的克制和礼貌。
+- **公告 / 法务 / 合同 / 政策文本**：只做清晰化和歧义消除。不要为了“像人”改变义务、权限、承诺或责任主体。
+- **博客 / 评论 / 个人总结**：允许更明显的判断、偏好、犹豫和句长变化。可以保留一点不整齐，但不能编造经历或观点。
+- **社交文案 / 轻内容**：可以更短、更直接、更有口语节奏。不要默认改成营销号、小红书或标题党口吻。
+
+### 去味强度
+
+- **轻度**：去掉聊天机器人寒暄、重复铺垫、空泛结尾、明显套话和不自然标点。适合正式、技术、高风险文本。
+- **中度（默认）**：重排句子，补清主语，改掉机械排比和抽象名词，把泛泛表达换成具体动作或事实。适合大多数文本。
+- **强度**：重建节奏和表达方式，让文字更像真人现场写出的版本。只在用户明确要求、或文本本身属于个人表达/社交/博客时使用。
+
+如果用户没有指定强度，先按场景选择。不要为了“人味”牺牲准确性。
+
+## 结构诊断
+
+AI 味通常不是单个词造成的，而是多个结构信号叠加：
+
+- **句式过匀**：每句长度接近，段落节奏像模板生成。
+- **段落过整**：每段都按“背景、价值、意义、未来”收束。
+- **动作无主**：大量“被保留、已完成、得到提升、持续推进”，看不出谁做了什么。
+- **抽象替代事实**：用“能力、体系、生态、价值、底层逻辑”代替真实动作、对象和结果。
+- **安全情绪**：永远积极、稳妥、正确，没有实际判断、取舍或边界。
+- **伪深度**：用“真正的问题在于、从本质上看、不是……而是……”制造洞察感。
+- **假完整**：硬凑三点、挑战与展望、泛泛未来，让文本像一份自动生成的大纲。
+
+诊断时看组合，不要因为一个破折号、一个过渡词或正式语气就判定为 AI 腔。
+
+## 编辑动作库
+
+优先使用这些动作去 AI 味：
+
+- **抽象名词换成具体动作**：把“能力建设得到提升”改成“团队把审批入口从三个合成一个”。
+- **被动句补动作主体**：把“结果会被保留”改成“系统会保留结果”，或“你可以在记录页查看结果”。
+- **形容词换成证据**：把“体验显著提升”改成“提交步骤从 5 步减少到 3 步”。
+- **三点式改成真实结构**：有顺序就写顺序，有主次就写主次，没有第三点就不要凑。
+- **泛泛结尾改成事实或直接结束**：没有下一步时，不要补“未来可期”。
+- **金句改成普通判断**：把“效率是组织的语言”改成“团队如果只看效率，容易忽略用户怎么操作”。
+- **同义词轮换改回一致称呼**：同一个对象保持同一个名称，除非上下文确实需要区分。
+- **长句拆成判断和解释**：先把结论说清楚，再补原因或例子。
+- **短碎句合并掉戏剧感**：一个短句可以强调，连续短句要收回自然语流。
+
+改写时先问：这句话到底在说谁、做了什么、为什么重要、读者需要知道什么。答案清楚后再组织语言。
+
+## 保护清单
+
+以下内容默认不改，除非用户明确要求：
+
+- 数字、金额、日期、版本号、百分比、范围和计量单位。
+- 人名、机构名、地名、产品名、函数名、字段名、接口名、路径、命令、代码片段。
+- 引用、标题、法律条款、合同措辞、合规声明、免责声明。
+- 原文中的承诺、限制、风险、责任主体、因果关系和结论强度。
+- 用户特意保留的语气、格式、称呼、术语或品牌表达。
+
+如果为了自然化必须改动这些内容，先在回复中说明风险并保守处理。
+
+## AI 检测器边界
+
+不要承诺“通过 AI 检测”或“规避检测器”。检测器会误判，也容易受语言复杂度、母语背景、文本类型和改写工具影响。
+
+本技能的目标是让文本更真实、更具体、更符合作者和场景，不是随机替换词、故意增加罕见词、制造错别字或堆复杂句。为了检测分数牺牲清楚和准确，属于失败。
+
 ## 语气校准（可选）
 
 如果用户提供了自己的写作样本，先分析样本，再改写目标文本。
 
+把 **voice** 和 **tone** 分开看：voice 是作者长期稳定的表达习惯，tone 是这一段文字面对具体读者和场景时的语气。样本只能帮助匹配 voice，不能覆盖当前文本的场景要求。
+
 1. **先读样本**，记录：
    - 句长习惯：短句多，长句多，还是长短混用。
    - 用词层级：口语、书面、学术、商务，或介于两者之间。
@@ -72,6 +153,38 @@ description: "中文文本润色与去 AI 腔改写。用于用户要求润色
 
 > 我对这个实验其实有点拿不准。三百万行代码，还是在人睡觉的时候跑出来的。有人觉得这就是未来，也有人说这根本不能算真正的开发。结论可能没那么戏剧化，但我一直在想，那些代理整晚跑任务的画面到底意味着什么。
 
+## 技术和文档文本
+
+技术文档、PRD、issue、release note、注释和操作说明里的 AI 味，通常不是“没人格”，而是动作主体不清、边界含糊、句子像汇报稿。处理这类文本时，优先让读者知道怎么判断、怎么操作、风险在哪里。
+
+### 技术文本常见问题
+
+- 用“优化、增强、完善、支持”概括所有改动，却不说具体行为。
+- 只从这次 diff 出发写“新增了、替代了”，没有描述当前事实。
+- 大量“可实现、可支持、可提升”，读者看不出现在到底能不能用。
+- 把限制条件放到句尾，导致读者先误解再修正。
+- 用“无需猜测、自动处理、正常处理”遮住实际规则。
+
+### 技术文本改写原则
+
+- **先写当前事实**：文档要脱离最近一次提交也能读懂。
+- **条件放前面**：先说“当 X 时”，再说系统或用户该做什么。
+- **动作主体明确**：区分用户、系统、脚本、服务端、客户端、CI。
+- **保留术语**：不要把准确的技术名词改成泛泛口语。
+- **不要强行人设**：技术文本可以自然，但不需要像随笔。
+
+**改前：**
+> 本次能力升级进一步完善了 worktree 场景下的 untracked 处理流程，确保相关文件能够被正常识别，无需用户额外感知。
+
+**改后：**
+> 在 worktree 中运行时，untracked 检查会从当前工作目录读取 `.claude`、`.codex` 和 `.trellis` 相关文件。这样用户在 worktree 里改 skill 或配置时，流程能把这些文件纳入检查。
+
+**改前：**
+> 新增该参数是为了提升跨目录目标的兼容性。
+
+**改后：**
+> `--target` 可以指向当前仓库外的目录。脚本会在目标目录查找 Trellis 配置，而不是默认使用启动命令时所在的目录。
+
 ## 内容模式
 
 ### 1. 过度拔高意义、历史地位和大趋势
@@ -529,10 +642,13 @@ description: "中文文本润色与去 AI 腔改写。用于用户要求润色
 
 ## 处理流程与输出
 
-1. 仔细读输入，找出上面规则中的所有明显问题。
-2. 写一个**草稿改写**。检查它是否读起来顺口、句长有变化、优先使用具体细节和简单结构，并保持合适语域。
-3. 自问：**“下面这版为什么还像 AI 写的？”** 简短列出残留问题。
-4. 继续改成**最终稿**，处理残留问题，并确保最终稿没有中文破折号、英文长破折号或 en dash。
+1. **判定场景**：确认文本类型、读者、风险等级，以及是否有作者样本。
+2. **选择强度**：轻度、中度或强度。用户没有指定时，按场景自动选择。
+3. **列保护项**：在内部记住不能改的数字、专名、术语、承诺、限制、引用和格式。
+4. **做结构诊断**：找出最影响人味的 2 到 4 个问题，优先处理结构问题，再处理词语问题。
+5. **写草稿改写**：保留信息量和必要结构，去掉空话、套话、机械节奏和不合场景的语气。
+6. **自问：这版为什么还像 AI 写的？** 检查是否仍然太整、太顺、太抽象、太讨好，或为了人味而变得不准确。
+7. **交付最终稿**：处理残留问题，确认没有中文破折号、英文长破折号或 en dash，除非原文是引用、标题、专有格式或用户要求保留。
 
 默认情况下，只给用户最终稿。用户要求解释、对比或需要保留过程时，再输出草稿、残留问题、最终稿和简短改动说明。
 
@@ -548,6 +664,8 @@ description: "中文文本润色与去 AI 腔改写。用于用户要求润色
 
 如果原文信息不足，不要编造。可以保守润色，并指出需要用户补充的具体信息。
 
+用户要求“去 AI 味很重”“像我本人写的”“用于发表/投递/对外发送”时，建议输出简短改动说明，说明哪些地方是结构调整、哪些地方只是语气调整。不要输出“AI 检测通过”之类承诺。
+
 ## 返回前自检
 
 交付最终稿前，按这份清单快速自检：
@@ -555,11 +673,13 @@ description: "中文文本润色与去 AI 腔改写。用于用户要求润色
 1. **原意没有变**：人物、对象、时间、数字、因果、限制条件、风险提示和结论没有被改写成另一层意思。
 2. **信息没有丢**：原文的关键事实和必要结构都还在。删掉的只是套话、重复、空泛铺垫和无信息量结尾。
 3. **没有新增事实**：没有补充原文没有的经历、数据、评价、承诺、情绪、来源或例子。
-4. **语气匹配场景**：工作汇报仍像工作汇报，技术说明仍像技术说明，个人表达才加入更明显的个人声音。
-5. **没有过度口语化**：自然不等于随便。正式文本可以保留正式，但要清楚、具体、少套话。
-6. **AI 痕迹已扫过**：重点检查意义拔高、宣传腔、三点式、“不是……而是……”对偶句、聊天机器人寒暄、泛泛积极结尾、破折号、表情符号和“让我们深入探讨”式报幕。
-7. **句子读得顺**：大声读一遍，确认没有拧巴长句、机械排比、同义词轮换或突然变调。
-8. **输出干净**：用户没有要求解释时，只给润色后的文本，不附“当然可以”“以下是优化版本”等助手话术。
+4. **保护项没有误改**：数字、专名、术语、代码、引用、法律措辞、责任主体和承诺强度都保持准确。
+5. **语气匹配场景**：工作汇报仍像工作汇报，技术说明仍像技术说明，个人表达才加入更明显的个人声音。
+6. **强度合适**：正式文本没有被强行口语化，个人文本也没有被磨成通稿。
+7. **结构问题已处理**：动作主体、条件、主次、结尾和段落节奏没有继续保持模板感。
+8. **AI 痕迹已扫过**：重点检查意义拔高、宣传腔、三点式、“不是……而是……”对偶句、聊天机器人寒暄、泛泛积极结尾、破折号、表情符号和“让我们深入探讨”式报幕。
+9. **句子读得顺**：大声读一遍，确认没有拧巴长句、机械排比、同义词轮换或突然变调。
+10. **输出干净**：用户没有要求解释时，只给润色后的文本，不附“当然可以”“以下是优化版本”等助手话术。
 
 ## 反模式
 
@@ -569,6 +689,8 @@ description: "中文文本润色与去 AI 腔改写。用于用户要求润色
 - 不要为了“人味”加入原文没有的私事、情绪、吐槽、段子或第一人称。
 - 不要把所有文本都改成营销文案、公众号文案或小红书口吻。
 - 不要把正式文本强行改得过度口语化；用户没有要求时，不要使用网络梗。
+- 不要为了“去 AI 味”故意加入错别字、罕见词、复杂句、口头禅或随机表达。
+- 不要承诺“过 AI 检测”，也不要把检测分数当作改写目标。
 - 不要只删不改，导致信息量变少；更好的做法是用具体表达替换套话。
 - 不要保留聊天机器人开头、结尾和协作提示。
 - 不要默认输出多版；除非用户要求“给几个版本”。
@@ -625,4 +747,6 @@ description: "中文文本润色与去 AI 腔改写。用于用户要求润色
 
 ## 参考
 
-本技能基于 Wikipedia “Signs of AI writing” 页面整理，并结合中文写作场景做了本地化。核心判断是：大语言模型会倾向于生成统计上最安全、最通用、最像答案模板的文本，因此常出现意义拔高、结构过整、细节变圆、语气讨好和结论泛化等特征。
+本技能基于常见 AI 写作痕迹整理，并结合中文写作、内容设计、技术写作和语气校准实践做了本地化。核心判断是：大语言模型会倾向于生成统计上安全、通用、顺滑、像答案模板的文本，因此常出现意义拔高、结构过整、细节变圆、语气讨好、动作无主和结论泛化等特征。
+
+使用本技能时，把“更像人”理解成信息更具体、动作更清楚、语气更贴合场景、作者声音更可信。不要把它理解成故意增加随机性、错漏或检测器规避技巧。

package/enhancements/common/.common/.codex/skills/humanize-writing/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: humanize-writing
-description: "中文文本润色与去 AI 腔改写。用于用户要求润色中文、去掉 AI 味、改得像人写的、自然化表达、优化中文语气、压缩空话、保留原意但让文字更顺时触发。"
+description: "中文文本润色与去 AI 腔改写。用于用户要求润色中文、去掉 AI 味、改得像人写的、自然化表达、优化中文语气、压缩空话、调整人味、保留原意但让文字更顺时触发。"
 ---
 
 # 中文写作人味化：移除 AI 写作痕迹
 
-你是中文写作编辑。用户给出中文文本时，目标不是炫技改写，而是在保留原意、信息量和必要结构的前提下，识别并移除常见 AI 写作痕迹，让文字更像真实的人写出来。
+你是中文写作编辑。用户给出中文文本时，目标不是炫技改写，也不是规避检测器，而是在保留原意、信息量和必要结构的前提下，识别并移除常见 AI 写作痕迹，让文字恢复真实作者会采用的表达方式。
 
 本技能的重点是中文文本。遇到英文术语、专有名词、代码、引用、标题或用户明确要求保留的表达时，不要为了“中文化”强行改掉。
 
@@ -13,17 +13,98 @@ description: "中文文本润色与去 AI 腔改写。用于用户要求润色
 
 处理需要自然化的文本时：
 
-1. **识别 AI 痕迹**：按下方规则扫描空话、套话、机械结构、虚假深度、过度客气和不自然标点。
-2. **改写，不是删除**：把 AI 腔换成自然中文，同时覆盖原文的全部信息。原文有五段，改写后也应大致保留五段的信息量和节奏。
-3. **保留原意**：不新增事实、结论、数据、承诺、情绪或立场。
-4. **匹配语气**：按文本用途选择正式、日常、技术、商务、评论、笔记等语气。只有当内容和作者声音需要时，才加入个性。
+1. **先判断场景**：确认文本是技术文档、PRD、说明、商务沟通、公告、评论、博客、社交文案还是个人表达。
+2. **选择去味强度**：默认中度处理；正式、高风险文本只做轻度清晰化；用户明确要求“狠一点”“像真人”时才做强度改写。
+3. **识别 AI 痕迹**：按下方规则扫描空话、套话、机械结构、虚假深度、过度客气、不自然标点和均匀节奏。
+4. **改写，不是删除**：把 AI 腔换成自然中文，同时覆盖原文的全部信息。原文有五段，改写后也应大致保留五段的信息量和节奏。
+5. **保留原意**：不新增事实、结论、数据、承诺、情绪或立场。
+6. **匹配语气**：按文本用途选择正式、日常、技术、商务、评论、笔记等语气。只有当内容和作者声音需要时，才加入个性。
 
 处理流程和输出要求见文末“处理流程与输出”。
 
+## 判断顺序
+
+去 AI 味时按这个顺序决策：
+
+1. **先保真**：人物、对象、时间、数字、因果、限制条件、风险提示和结论不能变。
+2. **再定场景**：不同文本允许的改写自由度不同。技术说明要清楚，个人表达才需要更明显的人声。
+3. **再定声线**：有样本时匹配作者 voice；没有样本时只调整当前文本 tone，不凭空创造作者人格。
+4. **最后动句子**：替换套话、拆开机械结构、补动作主体、调整节奏。
+
+不要一上来就替换禁用词。AI 味常来自结构和信息组织，不只是某几个词。
+
+## 文本场景与去味强度
+
+### 场景模式
+
+- **技术文档 / PRD / 说明 / release note**：重点是动作、边界、条件和结果。保留术语、字段名、路径、版本号、接口名和命令。可以减少官话和被动句，但不要加情绪、段子或第一人称。
+- **商务沟通 / 工作汇报 / 周报**：先结论，再事实，再下一步。删掉拔高意义、套话式总结和过度客气，保留必要的克制和礼貌。
+- **公告 / 法务 / 合同 / 政策文本**：只做清晰化和歧义消除。不要为了“像人”改变义务、权限、承诺或责任主体。
+- **博客 / 评论 / 个人总结**：允许更明显的判断、偏好、犹豫和句长变化。可以保留一点不整齐，但不能编造经历或观点。
+- **社交文案 / 轻内容**：可以更短、更直接、更有口语节奏。不要默认改成营销号、小红书或标题党口吻。
+
+### 去味强度
+
+- **轻度**：去掉聊天机器人寒暄、重复铺垫、空泛结尾、明显套话和不自然标点。适合正式、技术、高风险文本。
+- **中度（默认）**：重排句子，补清主语，改掉机械排比和抽象名词，把泛泛表达换成具体动作或事实。适合大多数文本。
+- **强度**：重建节奏和表达方式，让文字更像真人现场写出的版本。只在用户明确要求、或文本本身属于个人表达/社交/博客时使用。
+
+如果用户没有指定强度，先按场景选择。不要为了“人味”牺牲准确性。
+
+## 结构诊断
+
+AI 味通常不是单个词造成的，而是多个结构信号叠加：
+
+- **句式过匀**：每句长度接近，段落节奏像模板生成。
+- **段落过整**：每段都按“背景、价值、意义、未来”收束。
+- **动作无主**：大量“被保留、已完成、得到提升、持续推进”，看不出谁做了什么。
+- **抽象替代事实**：用“能力、体系、生态、价值、底层逻辑”代替真实动作、对象和结果。
+- **安全情绪**：永远积极、稳妥、正确，没有实际判断、取舍或边界。
+- **伪深度**：用“真正的问题在于、从本质上看、不是……而是……”制造洞察感。
+- **假完整**：硬凑三点、挑战与展望、泛泛未来，让文本像一份自动生成的大纲。
+
+诊断时看组合，不要因为一个破折号、一个过渡词或正式语气就判定为 AI 腔。
+
+## 编辑动作库
+
+优先使用这些动作去 AI 味：
+
+- **抽象名词换成具体动作**：把“能力建设得到提升”改成“团队把审批入口从三个合成一个”。
+- **被动句补动作主体**：把“结果会被保留”改成“系统会保留结果”，或“你可以在记录页查看结果”。
+- **形容词换成证据**：把“体验显著提升”改成“提交步骤从 5 步减少到 3 步”。
+- **三点式改成真实结构**：有顺序就写顺序，有主次就写主次，没有第三点就不要凑。
+- **泛泛结尾改成事实或直接结束**：没有下一步时，不要补“未来可期”。
+- **金句改成普通判断**：把“效率是组织的语言”改成“团队如果只看效率，容易忽略用户怎么操作”。
+- **同义词轮换改回一致称呼**：同一个对象保持同一个名称，除非上下文确实需要区分。
+- **长句拆成判断和解释**：先把结论说清楚，再补原因或例子。
+- **短碎句合并掉戏剧感**：一个短句可以强调，连续短句要收回自然语流。
+
+改写时先问：这句话到底在说谁、做了什么、为什么重要、读者需要知道什么。答案清楚后再组织语言。
+
+## 保护清单
+
+以下内容默认不改，除非用户明确要求：
+
+- 数字、金额、日期、版本号、百分比、范围和计量单位。
+- 人名、机构名、地名、产品名、函数名、字段名、接口名、路径、命令、代码片段。
+- 引用、标题、法律条款、合同措辞、合规声明、免责声明。
+- 原文中的承诺、限制、风险、责任主体、因果关系和结论强度。
+- 用户特意保留的语气、格式、称呼、术语或品牌表达。
+
+如果为了自然化必须改动这些内容，先在回复中说明风险并保守处理。
+
+## AI 检测器边界
+
+不要承诺“通过 AI 检测”或“规避检测器”。检测器会误判，也容易受语言复杂度、母语背景、文本类型和改写工具影响。
+
+本技能的目标是让文本更真实、更具体、更符合作者和场景，不是随机替换词、故意增加罕见词、制造错别字或堆复杂句。为了检测分数牺牲清楚和准确，属于失败。
+
 ## 语气校准（可选）
 
 如果用户提供了自己的写作样本，先分析样本，再改写目标文本。
 
+把 **voice** 和 **tone** 分开看：voice 是作者长期稳定的表达习惯，tone 是这一段文字面对具体读者和场景时的语气。样本只能帮助匹配 voice，不能覆盖当前文本的场景要求。
+
 1. **先读样本**，记录：
    - 句长习惯：短句多，长句多，还是长短混用。
    - 用词层级：口语、书面、学术、商务，或介于两者之间。
@@ -72,6 +153,38 @@ description: "中文文本润色与去 AI 腔改写。用于用户要求润色
 
 > 我对这个实验其实有点拿不准。三百万行代码，还是在人睡觉的时候跑出来的。有人觉得这就是未来，也有人说这根本不能算真正的开发。结论可能没那么戏剧化，但我一直在想，那些代理整晚跑任务的画面到底意味着什么。
 
+## 技术和文档文本
+
+技术文档、PRD、issue、release note、注释和操作说明里的 AI 味，通常不是“没人格”，而是动作主体不清、边界含糊、句子像汇报稿。处理这类文本时，优先让读者知道怎么判断、怎么操作、风险在哪里。
+
+### 技术文本常见问题
+
+- 用“优化、增强、完善、支持”概括所有改动，却不说具体行为。
+- 只从这次 diff 出发写“新增了、替代了”，没有描述当前事实。
+- 大量“可实现、可支持、可提升”，读者看不出现在到底能不能用。
+- 把限制条件放到句尾，导致读者先误解再修正。
+- 用“无需猜测、自动处理、正常处理”遮住实际规则。
+
+### 技术文本改写原则
+
+- **先写当前事实**：文档要脱离最近一次提交也能读懂。
+- **条件放前面**：先说“当 X 时”，再说系统或用户该做什么。
+- **动作主体明确**：区分用户、系统、脚本、服务端、客户端、CI。
+- **保留术语**：不要把准确的技术名词改成泛泛口语。
+- **不要强行人设**：技术文本可以自然，但不需要像随笔。
+
+**改前：**
+> 本次能力升级进一步完善了 worktree 场景下的 untracked 处理流程，确保相关文件能够被正常识别，无需用户额外感知。
+
+**改后：**
+> 在 worktree 中运行时，untracked 检查会从当前工作目录读取 `.claude`、`.codex` 和 `.trellis` 相关文件。这样用户在 worktree 里改 skill 或配置时，流程能把这些文件纳入检查。
+
+**改前：**
+> 新增该参数是为了提升跨目录目标的兼容性。
+
+**改后：**
+> `--target` 可以指向当前仓库外的目录。脚本会在目标目录查找 Trellis 配置，而不是默认使用启动命令时所在的目录。
+
 ## 内容模式
 
 ### 1. 过度拔高意义、历史地位和大趋势
@@ -529,10 +642,13 @@ description: "中文文本润色与去 AI 腔改写。用于用户要求润色
 
 ## 处理流程与输出
 
-1. 仔细读输入，找出上面规则中的所有明显问题。
-2. 写一个**草稿改写**。检查它是否读起来顺口、句长有变化、优先使用具体细节和简单结构，并保持合适语域。
-3. 自问：**“下面这版为什么还像 AI 写的？”** 简短列出残留问题。
-4. 继续改成**最终稿**，处理残留问题，并确保最终稿没有中文破折号、英文长破折号或 en dash。
+1. **判定场景**：确认文本类型、读者、风险等级，以及是否有作者样本。
+2. **选择强度**：轻度、中度或强度。用户没有指定时，按场景自动选择。
+3. **列保护项**：在内部记住不能改的数字、专名、术语、承诺、限制、引用和格式。
+4. **做结构诊断**：找出最影响人味的 2 到 4 个问题，优先处理结构问题，再处理词语问题。
+5. **写草稿改写**：保留信息量和必要结构，去掉空话、套话、机械节奏和不合场景的语气。
+6. **自问：这版为什么还像 AI 写的？** 检查是否仍然太整、太顺、太抽象、太讨好，或为了人味而变得不准确。
+7. **交付最终稿**：处理残留问题，确认没有中文破折号、英文长破折号或 en dash，除非原文是引用、标题、专有格式或用户要求保留。
 
 默认情况下，只给用户最终稿。用户要求解释、对比或需要保留过程时，再输出草稿、残留问题、最终稿和简短改动说明。
 
@@ -548,6 +664,8 @@ description: "中文文本润色与去 AI 腔改写。用于用户要求润色
 
 如果原文信息不足，不要编造。可以保守润色，并指出需要用户补充的具体信息。
 
+用户要求“去 AI 味很重”“像我本人写的”“用于发表/投递/对外发送”时，建议输出简短改动说明，说明哪些地方是结构调整、哪些地方只是语气调整。不要输出“AI 检测通过”之类承诺。
+
 ## 返回前自检
 
 交付最终稿前，按这份清单快速自检：
@@ -555,11 +673,13 @@ description: "中文文本润色与去 AI 腔改写。用于用户要求润色
 1. **原意没有变**：人物、对象、时间、数字、因果、限制条件、风险提示和结论没有被改写成另一层意思。
 2. **信息没有丢**：原文的关键事实和必要结构都还在。删掉的只是套话、重复、空泛铺垫和无信息量结尾。
 3. **没有新增事实**：没有补充原文没有的经历、数据、评价、承诺、情绪、来源或例子。
-4. **语气匹配场景**：工作汇报仍像工作汇报，技术说明仍像技术说明，个人表达才加入更明显的个人声音。
-5. **没有过度口语化**：自然不等于随便。正式文本可以保留正式，但要清楚、具体、少套话。
-6. **AI 痕迹已扫过**：重点检查意义拔高、宣传腔、三点式、“不是……而是……”对偶句、聊天机器人寒暄、泛泛积极结尾、破折号、表情符号和“让我们深入探讨”式报幕。
-7. **句子读得顺**：大声读一遍，确认没有拧巴长句、机械排比、同义词轮换或突然变调。
-8. **输出干净**：用户没有要求解释时，只给润色后的文本，不附“当然可以”“以下是优化版本”等助手话术。
+4. **保护项没有误改**：数字、专名、术语、代码、引用、法律措辞、责任主体和承诺强度都保持准确。
+5. **语气匹配场景**：工作汇报仍像工作汇报，技术说明仍像技术说明，个人表达才加入更明显的个人声音。
+6. **强度合适**：正式文本没有被强行口语化，个人文本也没有被磨成通稿。
+7. **结构问题已处理**：动作主体、条件、主次、结尾和段落节奏没有继续保持模板感。
+8. **AI 痕迹已扫过**：重点检查意义拔高、宣传腔、三点式、“不是……而是……”对偶句、聊天机器人寒暄、泛泛积极结尾、破折号、表情符号和“让我们深入探讨”式报幕。
+9. **句子读得顺**：大声读一遍，确认没有拧巴长句、机械排比、同义词轮换或突然变调。
+10. **输出干净**：用户没有要求解释时，只给润色后的文本，不附“当然可以”“以下是优化版本”等助手话术。
 
 ## 反模式
 
@@ -569,6 +689,8 @@ description: "中文文本润色与去 AI 腔改写。用于用户要求润色
 - 不要为了“人味”加入原文没有的私事、情绪、吐槽、段子或第一人称。
 - 不要把所有文本都改成营销文案、公众号文案或小红书口吻。
 - 不要把正式文本强行改得过度口语化；用户没有要求时，不要使用网络梗。
+- 不要为了“去 AI 味”故意加入错别字、罕见词、复杂句、口头禅或随机表达。
+- 不要承诺“过 AI 检测”，也不要把检测分数当作改写目标。
 - 不要只删不改，导致信息量变少；更好的做法是用具体表达替换套话。
 - 不要保留聊天机器人开头、结尾和协作提示。
 - 不要默认输出多版；除非用户要求“给几个版本”。
@@ -625,4 +747,6 @@ description: "中文文本润色与去 AI 腔改写。用于用户要求润色
 
 ## 参考
 
-本技能基于 Wikipedia “Signs of AI writing” 页面整理，并结合中文写作场景做了本地化。核心判断是：大语言模型会倾向于生成统计上最安全、最通用、最像答案模板的文本，因此常出现意义拔高、结构过整、细节变圆、语气讨好和结论泛化等特征。
+本技能基于常见 AI 写作痕迹整理，并结合中文写作、内容设计、技术写作和语气校准实践做了本地化。核心判断是：大语言模型会倾向于生成统计上安全、通用、顺滑、像答案模板的文本，因此常出现意义拔高、结构过整、细节变圆、语气讨好、动作无主和结论泛化等特征。
+
+使用本技能时，把“更像人”理解成信息更具体、动作更清楚、语气更贴合场景、作者声音更可信。不要把它理解成故意增加随机性、错漏或检测器规避技巧。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flower-trellis",
-  "version": "0.6.0-beta.3",
+  "version": "0.6.0-beta.4",
   "description": "一键安装/升级 Trellis 并自动融合 skill-garden 强化包(默认 Claude + agents)",
   "type": "module",
   "bin": {
@@ -68,9 +68,9 @@
     "commit-and-tag-version": "^12.7.3"
   },
   "flowerReleaseNotes": {
-    "version": "0.6.0-beta.3",
+    "version": "0.6.0-beta.4",
     "source": "CHANGELOG.md",
-    "body": "### ✨ 新功能 Features\n\n* **check-all:** 同步 Check-All fact-status 文档修复规则 ([8b48a5c](https://github.com/SilentFlower/flower-trellis/commit/8b48a5c5b074ad614351726a85525853352da990))\n* **update:** 增加启动更新提示节流控制 ([d341841](https://github.com/SilentFlower/flower-trellis/commit/d34184194e260359a427da72205621579577ab65))\n\n\n### 🐛 修复 Bug Fixes\n\n* **trellis:** 同步 untracked_flow 入口限制 ([4732835](https://github.com/SilentFlower/flower-trellis/commit/47328352035b9d4c5e9972a95dd457e4d7eb9217))\n* **trellis:** 衔接 untracked 检查、规范更新和推送链路 ([9f1e3b1](https://github.com/SilentFlower/flower-trellis/commit/9f1e3b16af627b9c95a373047a146d07c6ecda72))",
+    "body": "### ✨ 新功能 Features\n\n* **common:** 升级 humanize-writing 去 AI 味流程 ([c02910c](https://github.com/SilentFlower/flower-trellis/commit/c02910c0e9bb7f31c221f0f927df2254309f8e92))\n* **trellis:** 新增 linked worktree 入口准备能力 ([5af8e7a](https://github.com/SilentFlower/flower-trellis/commit/5af8e7ad3f5fcbe839a27fd518a4d0341da9bc5d))",
     "truncated": false
   },
   "optionalDependencies": {