trellis-hgl 0.6.0-beta.28 → 0.6.0-beta.30

package/README.md

@@ -225,7 +225,7 @@
 ### 安装
 
 ```bash
-npm install -g trellis-hgl@beta
+npm install -g trellis-hgl@latest
 ```
 
 ### 卸载
@@ -241,7 +241,7 @@ npm uninstall -g trellis-hgl
 npm uninstall -g @mindfoldhq/trellis
 
 # 安装最新版 trellis-hgl
-npm install -g trellis-hgl@beta
+npm install -g trellis-hgl@latest
 
 # 进入你自己的项目目录
 cd /path/to/your/project

package/dist/migrations/manifests/0.6.0-beta.29.json

@@ -0,0 +1,9 @@
+{
+  "version": "0.6.0-beta.29",
+  "description": "Beta 补丁：补齐 Claude shared worktree 的 .trellis/scripts bootstrap，并修正 worktree 漂移检测与覆盖保护。",
+  "breaking": false,
+  "recommendMigrate": false,
+  "changelog": "**修复：**\n- fix(worktree): Claude shared worktree 与 Trellis-managed worktree 在派发前会同步 `.trellis/scripts/`、`.trellis/workflow.md`、`.trellis/config.yaml` 与 `.trellis/.gitignore`，避免 subagent 在 worktree 内执行 `./.trellis/scripts/*` 时因缺少脚本而报错。\n- fix(hooks): `inject-subagent-context.py`、`session-start.py` 与 `common/worktree_sync.py` 现在共享同一套 bootstrap、planning snapshot 同步与 drift 检测逻辑，模板与 dogfood 副本保持一致。\n- fix(worktree): \"local code changes\" 现在基于 `git status --porcelain -z --untracked-files=all` 判断，已填充但 git-clean 的 worktree 不再被误判为 dirty；真正有代码改动时仍会阻止主工作区自动覆盖。\n\n**说明：**\n- 现有项目执行 `trellis update` 后即可获得新的 shared worktree scripts/bootstrap 与漂移保护修复。",
+  "migrations": [],
+  "notes": "安装此版本后请运行 `trellis update`，以同步生成的 shared worktree hooks、`.trellis/scripts/` 与 planning drift 保护逻辑；除非你本地手改过生成模板，否则无需手动迁移。"
+}

package/dist/migrations/manifests/0.6.0-beta.30.json

@@ -0,0 +1,9 @@
+{
+  "version": "0.6.0-beta.30",
+  "description": "Beta 补丁：强化 Claude Code planning 的 research-first 提问路径，并用 AskUserQuestion 配置开发策略。",
+  "breaking": false,
+  "recommendMigrate": false,
+  "changelog": "**改进：**\n- feat(workflow): Claude Code planning 在进入 `trellis-brainstorm` 前，会先按 research-first gate 调用 `trellis-research` 调研代码，并把结果写入任务 `research/` 目录。后续问题必须基于调研证据提出，减少盲猜式、兜底式追问。\n- feat(workflow): 开发策略配置优先使用 Claude Code 原生 `AskUserQuestion`，用结构化单选/多选收集执行模式、工作区模式、开发流程、架构指导和 review-gate 选择。\n- docs(upgrade): 升级说明改为推荐 `trellis upgrade` 或 `npm install -g trellis-hgl@latest`，避免依赖当前滞后的 npm `beta` dist-tag。\n\n**说明：**\n- 现有项目执行 `trellis update` 后即可同步新的 workflow、skills 与启动提示。",
+  "migrations": [],
+  "notes": "安装此版本后请在已有项目中运行 `trellis update`，以同步 Claude Code planning 的 research-first 提问路径和 AskUserQuestion 开发策略配置提示。推荐使用 `trellis upgrade` 或 `npm install -g trellis-hgl@latest` 获取最新版本；不要依赖当前滞后的 `trellis-hgl@beta` dist-tag。"
+}

package/dist/templates/common/commands/start.md

@@ -37,7 +37,15 @@ Index files list the specific guideline docs to read when you actually start cod
 From Step 1 you know the current task and status. Check the task directory:
 
 - **Active task status `planning` + no `prd.md`** → Phase 1.1. Load the `trellis-brainstorm` skill.
-- **Active task status `planning` + `prd.md` exists** → stay in Phase 1. Lightweight tasks can be PRD-only; complex tasks need `design.md` + `implement.md`. For the Claude Code path, keep requirement clarification in `prd.md`, continue repository-first follow-up questioning by entering `trellis-grill-me`, and treat it as a required planning gate. Before `trellis-grill-me` is complete, do not enter development strategy decisions, do not create or complete `design.md` / `implement.md`, and do not run `task.py start`. Before `task.py start`, record the decisions in the task documents: development mode, branch vs worktree, default flow vs TDD, plus the task-level review-gate selection. Ask these in one `A.` / `B.` / `C.` style strategy block. New tasks must stamp that block with `Review-gate contract: explicit-selection-v1`. Complex tasks should keep that record in `implement.md` together with the enabled/disabled review gates and the preserved order for any enabled Claude review gates: `trellis-spec-review` → `trellis-code-review` → `trellis-code-architecture-review`. While the choice is still open, `Optional review gates status: pending` is allowed; before `task.py start`, replace it with `Optional review gates status: configured` plus explicit `Enabled optional review gates:` and `Disabled optional review gates:` lists for the selectable review gates (`trellis-spec-review`, `trellis-code-review`, `trellis-code-architecture-review`, `trellis-improve-codebase-architecture`, `trellis-merge-review`). If the user leaves all optional gates off, still record all five in the disabled list while keeping `trellis-check` fixed outside that set. Only tasks that entirely lack `Review-gate contract: explicit-selection-v1` count as legacy tasks and preserve the old behavior; if the marker exists but the configured enabled/disabled lists are missing, planning is incomplete and the task must not start. `trellis-improve-codebase-architecture` deep-review requires `trellis-code-architecture-review`; do not record or accept deep-review without that prerequisite gate. If the strategy is `subagent + worktree`, pin `./.trellis/trellis-worktrees/<task-dir-name>`. On Claude Code, that shared worktree is different from host `Agent(..., isolation: "worktree")`; when both collide, the hook removes the host isolation input before dispatch. If the strategy is TDD, record `trellis-tdd` as the reference flow. Also record whether to run pre-development architecture guidance in that same strategy block. If guidance is enabled, record `架构审查：enabled`, dispatch `trellis-improve-codebase-architecture` with `架构审查模式: guidance` before `task.py start`, and append its output to `design.md`, but do NOT implicitly enable `trellis-improve-codebase-architecture` deep-review; that gate still requires explicit selection in the task-level review-gate set.
+- **Active task status `planning` + `prd.md` exists** → stay in Phase 1. Lightweight tasks can be PRD-only; complex tasks need `design.md` + `implement.md`. For the Claude Code path, keep requirement clarification in `prd.md`, continue repository-first follow-up questioning by entering `trellis-grill-me`, and treat it as a required planning gate. Before `trellis-grill-me` is complete, do not enter development strategy decisions, do not create or complete `design.md` / `implement.md`, and do not run `task.py start`.
+  - Before `task.py start`, record the decisions in the task documents: development mode, branch vs worktree, default flow vs TDD, pre-development architecture guidance, plus the task-level review-gate selection.
+  - On Claude Code, prefer the native `AskUserQuestion` tool for these development strategy decisions instead of a plain Markdown prompt. Each `AskUserQuestion` question must have 2–4 options. Split the decision into structured questions for development/workspace mode, default flow/TDD and architecture guidance, core review gates, and add-on review gates. Use `multiSelect: true` for review-gate questions.
+  - Core review gates are `trellis-spec-review`, `trellis-code-review`, and `trellis-code-architecture-review`; add-on review gates are `trellis-improve-codebase-architecture` and `trellis-merge-review`. Do not offer default review-gate packages; let the user directly select enabled gates, then write explicit enabled/disabled lists.
+  - If `AskUserQuestion` is unavailable, rejected, or the user chooses Other, fall back to a text `A.` / `B.` / `C.` option block or targeted free-text follow-up, but ask only for unresolved fields and never repeat answered choices unchanged.
+  - New tasks must stamp that block with `Review-gate contract: explicit-selection-v1`. Complex tasks should keep that record in `implement.md` together with the enabled/disabled review gates and the preserved order for any enabled Claude review gates: `trellis-spec-review` → `trellis-code-review` → `trellis-code-architecture-review`.
+  - While the choice is still open, `Optional review gates status: pending` is allowed; before `task.py start`, replace it with `Optional review gates status: configured` plus explicit `Enabled optional review gates:` and `Disabled optional review gates:` lists for the selectable review gates (`trellis-spec-review`, `trellis-code-review`, `trellis-code-architecture-review`, `trellis-improve-codebase-architecture`, `trellis-merge-review`). If the user leaves all optional gates off, still record all five in the disabled list while keeping `trellis-check` fixed outside that set.
+  - Only tasks that entirely lack `Review-gate contract: explicit-selection-v1` count as legacy tasks and preserve the old behavior; if the marker exists but the configured enabled/disabled lists are missing, planning is incomplete and the task must not start. `trellis-improve-codebase-architecture` deep-review requires `trellis-code-architecture-review`; do not record or accept deep-review without that prerequisite gate.
+  - If the strategy is `subagent + worktree`, pin `./.trellis/trellis-worktrees/<task-dir-name>`. On Claude Code, that shared worktree is different from host `Agent(..., isolation: "worktree")`; when both collide, the hook removes the host isolation input before dispatch. If the strategy is TDD, record `trellis-tdd` as the reference flow. If guidance is enabled, record `架构审查：enabled`, dispatch `trellis-improve-codebase-architecture` with `架构审查模式: guidance` before `task.py start`, and append its output to `design.md`, but do NOT implicitly enable `trellis-improve-codebase-architecture` deep-review; that gate still requires explicit selection in the task-level review-gate set.
 - **Active task status `in_progress`** → Phase 2 step 2.1. Load the step detail:
   ```bash
   {{PYTHON_CMD}} ./.trellis/scripts/get_context.py --mode phase --step 2.1 --platform {{CLI_FLAG}}

package/dist/templates/common/skills/brainstorm.md

@@ -14,6 +14,14 @@ This is mandatory. Before asking the user a question, first check whether the an
 
 Do not ask the user to confirm facts that the repository can answer. Ask only for product intent, preference, scope, risk tolerance, or decisions that remain ambiguous after inspection.
 
+## Claude Code Research Gate
+
+On the Claude Code path, feature additions, feature changes, and bug fixes that depend on repository facts must run `trellis-research` before the first `trellis-brainstorm` question. When this gate triggers, explicitly tell the user that repository evidence is required, `trellis-research` is running first, and questioning will resume from the findings. Research findings must be persisted to `{TASK_DIR}/research/` and used to frame the first question.
+
+Do not trigger the pre-brainstorm research gate for pure conversation, capability or usage explanation, pure user preference choices, copy edits that do not depend on repository facts, explicitly local-only small tasks, or when the user explicitly asks to skip research and answer directly.
+
+If a later user answer would materially change the current understanding of repository facts, pause the interview and run `trellis-research` again before asking the next question. If research is inconclusive, report what was checked, which evidence is missing, and which product intent or scope decision the user must provide before asking the question.
+
 ---
 
 Use this skill during Phase 1 planning to turn the user's request into clear requirements and planning artifacts.
@@ -49,7 +57,7 @@ Use a concise title from the user's request. Use a slug without a date prefix. `
 6. After each user answer, update `prd.md` before continuing.
 7. Once repository-answerable questions are exhausted, enter `trellis-grill-me` and tighten the remaining requirement gaps one question at a time, each with a recommendation, while still updating `prd.md` after each answer.
 8. On the Claude Code path, `trellis-grill-me` is a required planning gate. Before it is complete, do not switch into development strategy decisions, do not create or complete `design.md` / `implement.md`, and do not run `task.py start`.
-9. Before implementation starts on the Claude Code path, record the development strategy decisions in the task documents: development mode, branch vs worktree, default flow vs TDD, and the task-level review-gate selection. Ask these in a single `A.` / `B.` / `C.` style option block. New tasks must stamp that strategy block with `Review-gate contract: explicit-selection-v1`. Lightweight tasks may keep that record in `prd.md`; complex tasks should keep it in `implement.md` together with the enabled/disabled review gates and the preserved execution order for any enabled Claude review gates: `trellis-spec-review` → `trellis-code-review` → `trellis-code-architecture-review`. The selectable review gates are `trellis-spec-review`, `trellis-code-review`, `trellis-code-architecture-review`, `trellis-improve-codebase-architecture`, and `trellis-merge-review`. While the choice is still open, `Optional review gates status: pending` is allowed; before `task.py start`, replace it with `Optional review gates status: configured` plus explicit `Enabled optional review gates:` and `Disabled optional review gates:` lists. If the user leaves all optional gates off, still record all five in the disabled list; `trellis-check` stays fixed outside this set. Only tasks that entirely lack `Review-gate contract: explicit-selection-v1` count as legacy tasks and preserve the old behavior; if the marker exists but the configured enabled/disabled lists are missing, planning is incomplete and the task must not start. `trellis-improve-codebase-architecture` deep-review requires `trellis-code-architecture-review`, so do not record or accept the deep-review gate without that prerequisite. If the strategy is `subagent + worktree`, pin `./.trellis/trellis-worktrees/<task-dir-name>`. If the strategy is TDD, record `trellis-tdd` as the reference flow. Also record whether to run pre-development architecture guidance in that same strategy block. If guidance is enabled, record `架构审查：enabled`, dispatch `trellis-improve-codebase-architecture` with `架构审查模式: guidance` before `task.py start`, and append its output to `design.md`, but do NOT implicitly enable `trellis-improve-codebase-architecture` deep-review; that gate still requires explicit selection in the task-level review-gate set.
+9. Before implementation starts on the Claude Code path, record the development strategy decisions in the task documents: development mode, branch vs worktree, default flow vs TDD, and the task-level review-gate selection. Prefer Claude Code's native `AskUserQuestion` tool for this development strategy decision instead of a plain Markdown prompt. Every `AskUserQuestion` question must have 2–4 options; do not put all five optional review gates in one question. Use structured questions for development/workspace mode, flow/architecture guidance, core review gates with `multiSelect: true`, and add-on review gates with `multiSelect: true`. Core review gates are `trellis-spec-review`, `trellis-code-review`, and `trellis-code-architecture-review`; add-on review gates are `trellis-improve-codebase-architecture` and `trellis-merge-review`. Do not offer default review-gate packages; let the user directly multi-select enabled gates, then write the explicit enabled/disabled lists. If `AskUserQuestion` is unavailable, rejected, or the user chooses Other, fall back to a text `A.` / `B.` / `C.` option block or targeted free-text follow-up, but ask only for unresolved fields and never repeat answered choices unchanged. New tasks must stamp that strategy block with `Review-gate contract: explicit-selection-v1`. Lightweight tasks may keep that record in `prd.md`; complex tasks should keep it in `implement.md` together with the enabled/disabled review gates and the preserved execution order for any enabled Claude review gates: `trellis-spec-review` → `trellis-code-review` → `trellis-code-architecture-review`. The selectable review gates are `trellis-spec-review`, `trellis-code-review`, `trellis-code-architecture-review`, `trellis-improve-codebase-architecture`, and `trellis-merge-review`. While the choice is still open, `Optional review gates status: pending` is allowed; before `task.py start`, replace it with `Optional review gates status: configured` plus explicit `Enabled optional review gates:` and `Disabled optional review gates:` lists. If the user leaves all optional gates off, still record all five in the disabled list; `trellis-check` stays fixed outside this set. Only tasks that entirely lack `Review-gate contract: explicit-selection-v1` count as legacy tasks and preserve the old behavior; if the marker exists but the configured enabled/disabled lists are missing, planning is incomplete and the task must not start. `trellis-improve-codebase-architecture` deep-review requires `trellis-code-architecture-review`, so do not record or accept the deep-review gate without that prerequisite. If the strategy is `subagent + worktree`, pin `./.trellis/trellis-worktrees/<task-dir-name>`. If the strategy is TDD, record `trellis-tdd` as the reference flow. Also record whether to run pre-development architecture guidance in that same strategy block. If guidance is enabled, record `架构审查：enabled`, dispatch `trellis-improve-codebase-architecture` with `架构审查模式: guidance` before `task.py start`, and append its output to `design.md`, but do NOT implicitly enable `trellis-improve-codebase-architecture` deep-review; that gate still requires explicit selection in the task-level review-gate set.
 10. For complex tasks, create or update `design.md` and `implement.md` only after `trellis-grill-me` is complete and implementation is about to start.
 
 Do not invent a project-specific product/spec hierarchy. If the repository already has product, domain, or spec docs, use them. If it does not, proceed with the evidence that exists.

package/dist/templates/common/skills/grill-me.md

@@ -17,6 +17,14 @@ Use this skill only when:
 
 Do **not** use this skill for questions the codebase can answer directly.
 
+## Claude Code Research Gate
+
+On the Claude Code path, this skill may only continue after the active planning thread has already run any required `trellis-research` pass and persisted findings to `{TASK_DIR}/research/` for repository-dependent feature additions, feature changes, or bug fixes.
+
+Before each question, check whether the remaining gap is still a repository fact. If it is, stop the interview, explicitly tell the user that repository evidence is required, run `trellis-research`, persist the result, and then continue from the evidence. If research is inconclusive, report what was checked, which evidence is missing, and the exact product intent or scope decision needed from the user.
+
+If a user answer would materially change the current understanding of repository facts, run `trellis-research` again before asking the next follow-up question.
+
 ## Interview Contract
 
 - Ask one question at a time.
@@ -47,3 +55,4 @@ By the time this skill is done:
 - `prd.md` has testable acceptance criteria
 - unresolved questions are truly strategic, not factual
 - implementation can move on to development mode / worktree / TDD decisions
+- the next Claude Code development strategy decision should prefer `AskUserQuestion`; each question must have 2–4 options, review gates must be split into core and add-on `multiSelect: true` questions, and text fallback should ask only unresolved fields

package/dist/templates/shared-hooks/inject-subagent-context.py

@@ -49,8 +49,6 @@ if sys.platform.startswith("win"):
 DIR_WORKFLOW = ".trellis"
 DIR_SPEC = "spec"
 FILE_TASK_JSON = "task.json"
-WORKTREE_PARENT_DIR = ".trellis"
-WORKTREE_ROOT_DIR = "trellis-worktrees"
 
 # =============================================================================
 # Subagent Constants (change here to rename subagent types)
@@ -95,21 +93,64 @@ def find_repo_root(start_path: str) -> str | None:
     return None
 
 
+def _candidate_scripts_dirs(repo_root: Path) -> list[Path]:
+    candidates = [repo_root / DIR_WORKFLOW / "scripts"]
+    try:
+        if repo_root.parent.name == "trellis-worktrees" and repo_root.parent.parent.name == DIR_WORKFLOW:
+            candidates.insert(0, repo_root.parent.parent.parent / DIR_WORKFLOW / "scripts")
+    except Exception:
+        pass
+    return candidates
+
+
+def _load_worktree_sync(repo_root: str):
+    repo_path = Path(repo_root).resolve()
+    for scripts_dir in _candidate_scripts_dirs(repo_path):
+        if str(scripts_dir) not in sys.path:
+            sys.path.insert(0, str(scripts_dir))
+        try:
+            from common import worktree_sync  # type: ignore[import-not-found]
+            return worktree_sync
+        except Exception:
+            continue
+    return None
+
+
 def _infer_worktree_task(repo_root: str) -> str | None:
-    root = Path(repo_root).resolve()
+    worktree_sync = _load_worktree_sync(repo_root)
+    if worktree_sync is None:
+        return None
     try:
-        if root.parent.name != WORKTREE_ROOT_DIR:
-            return None
-        if root.parent.parent.name != WORKTREE_PARENT_DIR:
-            return None
+        return worktree_sync.infer_managed_worktree_task(Path(repo_root).resolve())
     except Exception:
         return None
 
-    task_dir_name = root.name
-    task_dir = root / DIR_WORKFLOW / "tasks" / task_dir_name
-    if not task_dir.is_dir():
-        return None
-    return f".trellis/tasks/{task_dir_name}"
+
+def ensure_shared_worktree_bootstrap(repo_root: str, task_dir: str | None) -> None:
+    if not task_dir:
+        return
+
+    worktree_sync = _load_worktree_sync(repo_root)
+    if worktree_sync is None:
+        return
+
+    task_dir_name = Path(task_dir).name
+    if not task_dir_name:
+        return
+
+    resolved = worktree_sync.resolve_shared_worktree_roots(
+        Path(repo_root).resolve(),
+        task_dir_name,
+    )
+    if not resolved:
+        return
+
+    main_root, worktree_root = resolved
+    worktree_sync.sync_runtime_bundle(main_root, worktree_root)
+
+    target_task_dir = worktree_sync.task_dir(worktree_root, task_dir_name)
+    if not worktree_sync.has_any_task_artifact(target_task_dir):
+        worktree_sync.sync_task_snapshot(main_root, worktree_root, task_dir_name)
 
 
 def _detect_platform(input_data: dict) -> str | None:
@@ -880,6 +921,15 @@ def _looks_like_path_key(key: str | None) -> bool:
     return lowered.endswith(("_path", "_paths", "_file", "_files", "_dir", "_root"))
 
 
+def _extract_shared_worktree_task_name(path_value: Any) -> str | None:
+    normalized = _normalize_hook_text(path_value)
+    if CLAUDE_SHARED_WORKTREE_MARKER not in normalized:
+        return None
+    suffix = normalized.split(CLAUDE_SHARED_WORKTREE_MARKER, 1)[1]
+    task_name = suffix.split("/", 1)[0].strip()
+    return task_name or None
+
+
 def _tool_input_targets_shared_worktree(value: Any, key: str | None = None) -> bool:
     if isinstance(value, dict):
         for nested_key, nested_value in value.items():
@@ -896,6 +946,40 @@ def _tool_input_targets_shared_worktree(value: Any, key: str | None = None) -> b
     return _path_uses_shared_worktree(value)
 
 
+def _tool_input_shared_worktree_task(value: Any, key: str | None = None) -> str | None:
+    if isinstance(value, dict):
+        for nested_key, nested_value in value.items():
+            task_name = _tool_input_shared_worktree_task(nested_value, str(nested_key))
+            if task_name:
+                return task_name
+        return None
+    if isinstance(value, list):
+        for item in value:
+            task_name = _tool_input_shared_worktree_task(item, key)
+            if task_name:
+                return task_name
+        return None
+    if not _looks_like_path_key(key):
+        return None
+    return _extract_shared_worktree_task_name(value)
+
+
+def infer_task_dir_from_shared_worktree_signal(
+    repo_root: str,
+    tool_input: dict,
+    cwd: str,
+) -> str | None:
+    for path_value in (cwd, repo_root):
+        task_name = _extract_shared_worktree_task_name(path_value)
+        if task_name:
+            return f".trellis/tasks/{task_name}"
+
+    task_name = _tool_input_shared_worktree_task(tool_input)
+    if task_name:
+        return f".trellis/tasks/{task_name}"
+    return None
+
+
 def has_shared_worktree_signal(
     repo_root: str,
     task_dir: str | None,
@@ -964,6 +1048,8 @@ def main():
 
     # Get current task directory (research doesn't require it)
     task_dir = get_current_task(repo_root, input_data)
+    if not task_dir and is_claude_code_dev_agent(subagent_type):
+        task_dir = infer_task_dir_from_shared_worktree_signal(repo_root, tool_input, cwd)
 
     # implement/check/review need task directory
     if subagent_type in AGENTS_REQUIRE_TASK:
@@ -977,8 +1063,17 @@ def main():
     hook_notice = ""
     hook_system_message = ""
     normalized_tool_input = tool_input
+    shared_worktree_signal = False
+
     if platform == "claude" and is_claude_code_dev_agent(subagent_type):
-        if has_shared_worktree_signal(repo_root, task_dir, tool_input, cwd):
+        shared_worktree_signal = has_shared_worktree_signal(
+            repo_root,
+            task_dir,
+            tool_input,
+            cwd,
+        )
+        if shared_worktree_signal:
+            ensure_shared_worktree_bootstrap(repo_root, task_dir)
             normalized_tool_input, stripped = strip_conflicting_worktree_isolation(tool_input)
             if stripped:
                 hook_notice = _build_shared_worktree_conflict_notice(task_dir)

package/dist/templates/shared-hooks/session-start.py

@@ -9,12 +9,10 @@ from __future__ import annotations
 import warnings
 warnings.filterwarnings("ignore")
 
-import hashlib
 import json
 import os
 import re
 import shlex
-import shutil
 import subprocess
 import sys
 from io import StringIO
@@ -99,210 +97,28 @@ if sys.platform.startswith("win"):
 
 WORKTREE_PARENT_DIR = ".trellis"
 WORKTREE_ROOT_DIR = "trellis-worktrees"
-RUNTIME_BUNDLE_FILES = (
-    ".trellis/workflow.md",
-    ".trellis/config.yaml",
-    ".trellis/.gitignore",
-)
-RUNTIME_BUNDLE_DIRS = (
-    ".trellis/scripts",
-)
-PLANNING_FILE_NAMES = (
-    "task.json",
-    "prd.md",
-    "design.md",
-    "implement.md",
-    "implement.jsonl",
-    "check.jsonl",
-)
-PLANNING_DIR_NAMES = ("research",)
-
-
-def _remove_path(path: Path) -> None:
-    if path.is_symlink() or path.is_file():
-        path.unlink()
-        return
-    if path.is_dir():
-        shutil.rmtree(path)
-
-
-def _hash_file(path: Path) -> str:
-    digest = hashlib.sha256()
-    with path.open("rb") as handle:
-        for chunk in iter(lambda: handle.read(65536), b""):
-            digest.update(chunk)
-    return digest.hexdigest()
-
-
-def _snapshot_dir(path: Path) -> dict[str, str]:
-    if not path.is_dir():
-        return {}
-    snapshot: dict[str, str] = {}
-    for child in sorted(path.rglob("*")):
-        if child.is_file():
-            snapshot[child.relative_to(path).as_posix()] = _hash_file(child)
-    return snapshot
-
-
-def _same_file(src: Path, dst: Path) -> bool:
-    return src.is_file() and dst.is_file() and _hash_file(src) == _hash_file(dst)
-
-
-def _same_tree(src: Path, dst: Path) -> bool:
-    return src.is_dir() and dst.is_dir() and _snapshot_dir(src) == _snapshot_dir(dst)
-
 
-def _copy_file(src: Path, dst: Path) -> None:
-    dst.parent.mkdir(parents=True, exist_ok=True)
-    shutil.copy2(src, dst)
 
-
-def _copy_tree(src: Path, dst: Path) -> None:
-    if dst.exists():
-        _remove_path(dst)
-    dst.parent.mkdir(parents=True, exist_ok=True)
-    shutil.copytree(src, dst)
-
-
-def _detect_trellis_managed_worktree(repo_root: Path) -> tuple[Path, str] | None:
+def _candidate_scripts_dirs(repo_root: Path) -> list[Path]:
+    candidates = [repo_root / ".trellis" / "scripts"]
     try:
-        if repo_root.parent.name != WORKTREE_ROOT_DIR:
-            return None
-        if repo_root.parent.parent.name != WORKTREE_PARENT_DIR:
-            return None
-        main_root = repo_root.parent.parent.parent
-        if not (main_root / ".git").exists():
-            return None
-        return main_root, repo_root.name
+        if repo_root.parent.name == WORKTREE_ROOT_DIR and repo_root.parent.parent.name == WORKTREE_PARENT_DIR:
+            candidates.insert(0, repo_root.parent.parent.parent / ".trellis" / "scripts")
     except Exception:
-        return None
-
-
-def _task_dir(repo_root: Path, task_dir_name: str) -> Path:
-    return repo_root / ".trellis" / "tasks" / task_dir_name
-
-
-def _task_snapshot(task_dir: Path) -> dict[str, str]:
-    snapshot: dict[str, str] = {}
-    for name in PLANNING_FILE_NAMES:
-        file_path = task_dir / name
-        if file_path.is_file():
-            snapshot[name] = _hash_file(file_path)
-    for name in PLANNING_DIR_NAMES:
-        dir_path = task_dir / name
-        if not dir_path.is_dir():
-            continue
-        for child in sorted(dir_path.rglob("*")):
-            if child.is_file():
-                snapshot[child.relative_to(task_dir).as_posix()] = _hash_file(child)
-    return snapshot
-
-
-def _has_any_task_artifact(task_dir: Path) -> bool:
-    for name in PLANNING_FILE_NAMES:
-        if (task_dir / name).is_file():
-            return True
-    for name in PLANNING_DIR_NAMES:
-        if (task_dir / name).exists():
-            return True
-    return False
-
-
-def _sync_runtime_bundle(main_root: Path, worktree_root: Path) -> list[str]:
-    synced: list[str] = []
-    for relative_path in RUNTIME_BUNDLE_FILES:
-        src = main_root / relative_path
-        dst = worktree_root / relative_path
-        if not src.is_file() or _same_file(src, dst):
-            continue
-        _copy_file(src, dst)
-        synced.append(relative_path)
-    for relative_path in RUNTIME_BUNDLE_DIRS:
-        src = main_root / relative_path
-        dst = worktree_root / relative_path
-        if not src.is_dir() or _same_tree(src, dst):
-            continue
-        _copy_tree(src, dst)
-        synced.append(relative_path)
-    return synced
-
-
-def _sync_task_snapshot(main_root: Path, worktree_root: Path, task_dir_name: str) -> list[str]:
-    source_task_dir = _task_dir(main_root, task_dir_name)
-    target_task_dir = _task_dir(worktree_root, task_dir_name)
-    if not source_task_dir.is_dir():
-        return []
-
-    synced: list[str] = []
-    for name in PLANNING_FILE_NAMES:
-        src = source_task_dir / name
-        if not src.is_file():
-            continue
-        dst = target_task_dir / name
-        if _same_file(src, dst):
-            continue
-        _copy_file(src, dst)
-        synced.append(name)
-
-    for name in PLANNING_DIR_NAMES:
-        src = source_task_dir / name
-        if not src.is_dir():
-            continue
-        dst = target_task_dir / name
-        if _same_tree(src, dst):
-            continue
-        _copy_tree(src, dst)
-        synced.append(name)
-
-    return synced
-
-
-def _collect_task_drift(main_root: Path, worktree_root: Path, task_dir_name: str) -> list[str]:
-    source_snapshot = _task_snapshot(_task_dir(main_root, task_dir_name))
-    target_snapshot = _task_snapshot(_task_dir(worktree_root, task_dir_name))
-    keys = sorted(set(source_snapshot) | set(target_snapshot))
-    return [key for key in keys if source_snapshot.get(key) != target_snapshot.get(key)]
-
-
-def _is_managed_worktree_path(path_str: str, task_dir_name: str) -> bool:
-    normalized = path_str.replace("\\", "/").strip().strip("/")
-
-    for relative_path in RUNTIME_BUNDLE_FILES:
-        runtime_path = relative_path.strip("/")
-        if normalized == runtime_path:
-            return True
-    for relative_path in RUNTIME_BUNDLE_DIRS:
-        runtime_dir = relative_path.strip("/")
-        if normalized == runtime_dir or normalized.startswith(runtime_dir + "/"):
-            return True
-
-    task_root = f".trellis/tasks/{task_dir_name}"
-    if normalized in (".trellis/tasks", task_root):
-        return True
-    task_prefix = task_root + "/"
-    if not normalized.startswith(task_prefix):
-        return False
-    task_relative = normalized[len(task_prefix):]
-    if not task_relative:
-        return True
-    if task_relative in PLANNING_FILE_NAMES:
-        return True
-    for dir_name in PLANNING_DIR_NAMES:
-        if task_relative == dir_name or task_relative.startswith(dir_name + "/"):
-            return True
-    return False
+        pass
+    return candidates
 
 
-def _worktree_has_local_code_changes(worktree_root: Path, task_dir_name: str) -> bool:
-    if not worktree_root.exists():
-        return False
-    for child in sorted(worktree_root.rglob("*")):
-        if child.is_dir():
+def _load_worktree_sync(repo_root: Path):
+    for scripts_dir in _candidate_scripts_dirs(repo_root):
+        if str(scripts_dir) not in sys.path:
+            sys.path.insert(0, str(scripts_dir))
+        try:
+            from common import worktree_sync  # type: ignore[import-not-found]
+            return worktree_sync
+        except Exception:
             continue
-        relative_path = child.relative_to(worktree_root).as_posix()
-        if not _is_managed_worktree_path(relative_path, task_dir_name):
-            return True
-    return False
+    return None
 
 
 def _format_changed_paths(paths: list[str], limit: int = 6) -> str:
@@ -313,7 +129,11 @@ def _format_changed_paths(paths: list[str], limit: int = 6) -> str:
 
 def _maybe_sync_trellis_worktree(project_dir: Path) -> str:
     try:
-        detected = _detect_trellis_managed_worktree(project_dir)
+        worktree_sync = _load_worktree_sync(project_dir)
+        if worktree_sync is None:
+            return ""
+
+        detected = worktree_sync.detect_trellis_managed_worktree(project_dir)
         if not detected:
             return ""
 
@@ -322,29 +142,29 @@ def _maybe_sync_trellis_worktree(project_dir: Path) -> str:
             f"Detected Trellis-managed worktree: ./.trellis/trellis-worktrees/{task_dir_name}/",
         ]
 
-        runtime_synced = _sync_runtime_bundle(main_root, project_dir)
+        runtime_synced = worktree_sync.sync_runtime_bundle(main_root, project_dir)
         if runtime_synced:
             notes.append(
                 "Bootstrapped runtime bundle from main workspace: "
                 + ", ".join(runtime_synced)
             )
 
-        target_task_dir = _task_dir(project_dir, task_dir_name)
-        if not _has_any_task_artifact(target_task_dir):
-            planning_synced = _sync_task_snapshot(main_root, project_dir, task_dir_name)
+        target_task_dir = worktree_sync.task_dir(project_dir, task_dir_name)
+        if not worktree_sync.has_any_task_artifact(target_task_dir):
+            planning_synced = worktree_sync.sync_task_snapshot(main_root, project_dir, task_dir_name)
             if planning_synced:
                 notes.append(
                     "Bootstrapped current task planning snapshot from main workspace: "
                     + ", ".join(planning_synced)
                 )
 
-        drift = _collect_task_drift(main_root, project_dir, task_dir_name)
+        drift = worktree_sync.collect_task_drift(main_root, project_dir, task_dir_name)
         if drift:
             notes.append(
                 "Planning drift detected between main workspace and worktree: "
                 + _format_changed_paths(drift)
             )
-            if _worktree_has_local_code_changes(project_dir, task_dir_name):
+            if worktree_sync.worktree_has_local_code_changes(project_dir, task_dir_name):
                 notes.append(
                     "Do NOT auto-overwrite: this worktree has local code changes. "
                     "Explain the conflict first, recommend creating a new Trellis task "
@@ -594,14 +414,13 @@ def run_script(script_path: Path, context_key: str | None = None) -> str:
 
 
 def _infer_worktree_task_ref(repo_root: Path) -> str | None:
-    detected = _detect_trellis_managed_worktree(repo_root)
-    if not detected:
+    worktree_sync = _load_worktree_sync(repo_root)
+    if worktree_sync is None:
         return None
-    _, task_dir_name = detected
-    task_dir = _task_dir(repo_root, task_dir_name)
-    if not task_dir.is_dir():
+    try:
+        return worktree_sync.infer_managed_worktree_task(repo_root)
+    except Exception:
         return None
-    return f".trellis/tasks/{task_dir_name}"
 
 
 def _normalize_task_ref(task_ref: str) -> str:

package/dist/templates/trellis/index.d.ts

@@ -37,6 +37,7 @@ export declare const commonPackagesContext: string;
 export declare const commonWorkflowPhase: string;
 export declare const commonTrellisConfig: string;
 export declare const commonSafeCommit: string;
+export declare const commonWorktreeSync: string;
 export declare const trellisSwitch: string;
 export declare const assertTrellisEnabled: string;
 export declare const getDeveloperScript: string;

package/dist/templates/trellis/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/templates/trellis/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAcH,eAAO,MAAM,WAAW,QAAsC,CAAC;AAG/D,eAAO,MAAM,UAAU,QAA6C,CAAC;AACrE,eAAO,MAAM,WAAW,QAA0C,CAAC;AACnE,eAAO,MAAM,eAAe,QAA8C,CAAC;AAC3E,eAAO,MAAM,gBAAgB,QAAgD,CAAC;AAC9E,eAAO,MAAM,eAAe,QAA+C,CAAC;AAC5E,eAAO,MAAM,eAAe,QAA+C,CAAC;AAC5E,eAAO,MAAM,gBAAgB,QAAgD,CAAC;AAC9E,eAAO,MAAM,gBAAgB,QAAgD,CAAC;AAC9E,eAAO,MAAM,YAAY,QAA2C,CAAC;AACrE,eAAO,MAAM,QAAQ,QAAuC,CAAC;AAC7D,eAAO,MAAM,SAAS,QAAwC,CAAC;AAC/D,eAAO,MAAM,SAAS,QAAwC,CAAC;AAC/D,eAAO,MAAM,WAAW,QAA0C,CAAC;AACnE,eAAO,MAAM,WAAW,QAA0C,CAAC;AACnE,eAAO,MAAM,iBAAiB,QAAiD,CAAC;AAChF,eAAO,MAAM,eAAe,QAA+C,CAAC;AAC5E,eAAO,MAAM,oBAAoB,QAEhC,CAAC;AACF,eAAO,MAAM,qBAAqB,QAEjC,CAAC;AACF,eAAO,MAAM,mBAAmB,QAE/B,CAAC;AACF,eAAO,MAAM,mBAAmB,QAE/B,CAAC;AACF,eAAO,MAAM,gBAAgB,QAAgD,CAAC;AAC9E,eAAO,MAAM,aAAa,QAA4C,CAAC;AACvE,eAAO,MAAM,oBAAoB,QAAoD,CAAC;AAGtF,eAAO,MAAM,kBAAkB,QAA2C,CAAC;AAC3E,eAAO,MAAM,mBAAmB,QAA4C,CAAC;AAC7E,eAAO,MAAM,UAAU,QAAkC,CAAC;AAC1D,eAAO,MAAM,gBAAgB,QAAyC,CAAC;AACvE,eAAO,MAAM,gBAAgB,QAAyC,CAAC;AAGvE,eAAO,MAAM,kBAAkB,QAA8B,CAAC;AAC9D,eAAO,MAAM,kBAAkB,QAA8B,CAAC;AAC9D,eAAO,MAAM,iBAAiB,QAAgC,CAAC;AAE/D;;GAEG;AACH,wBAAgB,aAAa,IAAI,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAuCnD"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/templates/trellis/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAcH,eAAO,MAAM,WAAW,QAAsC,CAAC;AAG/D,eAAO,MAAM,UAAU,QAA6C,CAAC;AACrE,eAAO,MAAM,WAAW,QAA0C,CAAC;AACnE,eAAO,MAAM,eAAe,QAA8C,CAAC;AAC3E,eAAO,MAAM,gBAAgB,QAAgD,CAAC;AAC9E,eAAO,MAAM,eAAe,QAA+C,CAAC;AAC5E,eAAO,MAAM,eAAe,QAA+C,CAAC;AAC5E,eAAO,MAAM,gBAAgB,QAAgD,CAAC;AAC9E,eAAO,MAAM,gBAAgB,QAAgD,CAAC;AAC9E,eAAO,MAAM,YAAY,QAA2C,CAAC;AACrE,eAAO,MAAM,QAAQ,QAAuC,CAAC;AAC7D,eAAO,MAAM,SAAS,QAAwC,CAAC;AAC/D,eAAO,MAAM,SAAS,QAAwC,CAAC;AAC/D,eAAO,MAAM,WAAW,QAA0C,CAAC;AACnE,eAAO,MAAM,WAAW,QAA0C,CAAC;AACnE,eAAO,MAAM,iBAAiB,QAAiD,CAAC;AAChF,eAAO,MAAM,eAAe,QAA+C,CAAC;AAC5E,eAAO,MAAM,oBAAoB,QAEhC,CAAC;AACF,eAAO,MAAM,qBAAqB,QAEjC,CAAC;AACF,eAAO,MAAM,mBAAmB,QAE/B,CAAC;AACF,eAAO,MAAM,mBAAmB,QAE/B,CAAC;AACF,eAAO,MAAM,gBAAgB,QAAgD,CAAC;AAC9E,eAAO,MAAM,kBAAkB,QAAkD,CAAC;AAClF,eAAO,MAAM,aAAa,QAA4C,CAAC;AACvE,eAAO,MAAM,oBAAoB,QAAoD,CAAC;AAGtF,eAAO,MAAM,kBAAkB,QAA2C,CAAC;AAC3E,eAAO,MAAM,mBAAmB,QAA4C,CAAC;AAC7E,eAAO,MAAM,UAAU,QAAkC,CAAC;AAC1D,eAAO,MAAM,gBAAgB,QAAyC,CAAC;AACvE,eAAO,MAAM,gBAAgB,QAAyC,CAAC;AAGvE,eAAO,MAAM,kBAAkB,QAA8B,CAAC;AAC9D,eAAO,MAAM,kBAAkB,QAA8B,CAAC;AAC9D,eAAO,MAAM,iBAAiB,QAAgC,CAAC;AAE/D;;GAEG;AACH,wBAAgB,aAAa,IAAI,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAwCnD"}

package/dist/templates/trellis/index.js

@@ -47,6 +47,7 @@ export const commonPackagesContext = readTemplate("scripts/common/packages_conte
 export const commonWorkflowPhase = readTemplate("scripts/common/workflow_phase.py");
 export const commonTrellisConfig = readTemplate("scripts/common/trellis_config.py");
 export const commonSafeCommit = readTemplate("scripts/common/safe_commit.py");
+export const commonWorktreeSync = readTemplate("scripts/common/worktree_sync.py");
 export const trellisSwitch = readTemplate("scripts/trellis_switch.py");
 export const assertTrellisEnabled = readTemplate("scripts/assert_trellis_enabled.py");
 // Python scripts - main
@@ -88,6 +89,7 @@ export function getAllScripts() {
     scripts.set("common/workflow_phase.py", commonWorkflowPhase);
     scripts.set("common/trellis_config.py", commonTrellisConfig);
     scripts.set("common/safe_commit.py", commonSafeCommit);
+    scripts.set("common/worktree_sync.py", commonWorktreeSync);
     // Main
     scripts.set("get_developer.py", getDeveloperScript);
     scripts.set("init_developer.py", initDeveloperScript);

package/dist/templates/trellis/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/templates/trellis/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/templates/trellis/index.ts"],"names":[],"mappings":"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"}

package/dist/templates/trellis/scripts/common/worktree_sync.py

@@ -0,0 +1,273 @@
+from __future__ import annotations
+
+import hashlib
+import shutil
+from pathlib import Path
+
+from common.git import run_git
+
+DIR_WORKFLOW = ".trellis"
+WORKTREE_PARENT_DIR = ".trellis"
+WORKTREE_ROOT_DIR = "trellis-worktrees"
+RUNTIME_BUNDLE_FILES = (
+    ".trellis/workflow.md",
+    ".trellis/config.yaml",
+    ".trellis/.gitignore",
+)
+RUNTIME_BUNDLE_DIRS = (
+    ".trellis/scripts",
+)
+PLANNING_FILE_NAMES = (
+    "task.json",
+    "prd.md",
+    "design.md",
+    "implement.md",
+    "implement.jsonl",
+    "check.jsonl",
+)
+PLANNING_DIR_NAMES = ("research",)
+
+
+def _remove_path(path: Path) -> None:
+    if path.is_symlink() or path.is_file():
+        path.unlink()
+        return
+    if path.is_dir():
+        shutil.rmtree(path)
+
+
+def _hash_file(path: Path) -> str:
+    digest = hashlib.sha256()
+    with path.open("rb") as handle:
+        for chunk in iter(lambda: handle.read(65536), b""):
+            digest.update(chunk)
+    return digest.hexdigest()
+
+
+def _snapshot_dir(path: Path) -> dict[str, str]:
+    if not path.is_dir():
+        return {}
+    snapshot: dict[str, str] = {}
+    for child in sorted(path.rglob("*")):
+        if child.is_file():
+            snapshot[child.relative_to(path).as_posix()] = _hash_file(child)
+    return snapshot
+
+
+def _same_file(src: Path, dst: Path) -> bool:
+    return src.is_file() and dst.is_file() and _hash_file(src) == _hash_file(dst)
+
+
+def _same_tree(src: Path, dst: Path) -> bool:
+    return src.is_dir() and dst.is_dir() and _snapshot_dir(src) == _snapshot_dir(dst)
+
+
+def _copy_file(src: Path, dst: Path) -> None:
+    dst.parent.mkdir(parents=True, exist_ok=True)
+    shutil.copy2(src, dst)
+
+
+def _copy_tree(src: Path, dst: Path) -> None:
+    if dst.exists():
+        _remove_path(dst)
+    dst.parent.mkdir(parents=True, exist_ok=True)
+    shutil.copytree(src, dst)
+
+
+def task_dir(repo_root: Path, task_dir_name: str) -> Path:
+    return repo_root / DIR_WORKFLOW / "tasks" / task_dir_name
+
+
+def detect_trellis_managed_worktree(repo_root: Path) -> tuple[Path, str] | None:
+    try:
+        if repo_root.parent.name != WORKTREE_ROOT_DIR:
+            return None
+        if repo_root.parent.parent.name != WORKTREE_PARENT_DIR:
+            return None
+        main_root = repo_root.parent.parent.parent
+        if not (main_root / ".git").exists():
+            return None
+        return main_root, repo_root.name
+    except Exception:
+        return None
+
+
+def infer_managed_worktree_task(repo_root: Path) -> str | None:
+    detected = detect_trellis_managed_worktree(repo_root)
+    if not detected:
+        return None
+    _, task_dir_name = detected
+    if not task_dir(repo_root, task_dir_name).is_dir():
+        return None
+    return f".trellis/tasks/{task_dir_name}"
+
+
+def resolve_shared_worktree_roots(
+    repo_root: Path,
+    task_dir_name: str,
+) -> tuple[Path, Path] | None:
+    detected = detect_trellis_managed_worktree(repo_root)
+    if detected:
+        main_root, inferred_task_dir_name = detected
+        if inferred_task_dir_name != task_dir_name:
+            return None
+        return main_root, repo_root
+
+    main_root = repo_root
+    worktree_root = repo_root / WORKTREE_PARENT_DIR / WORKTREE_ROOT_DIR / task_dir_name
+    if not worktree_root.exists():
+        return None
+    if not (main_root / DIR_WORKFLOW / "scripts").is_dir():
+        return None
+    return main_root, worktree_root
+
+
+def task_snapshot(task_dir_path: Path) -> dict[str, str]:
+    snapshot: dict[str, str] = {}
+    for name in PLANNING_FILE_NAMES:
+        file_path = task_dir_path / name
+        if file_path.is_file():
+            snapshot[name] = _hash_file(file_path)
+    for name in PLANNING_DIR_NAMES:
+        dir_path = task_dir_path / name
+        if not dir_path.is_dir():
+            continue
+        for child in sorted(dir_path.rglob("*")):
+            if child.is_file():
+                snapshot[child.relative_to(task_dir_path).as_posix()] = _hash_file(child)
+    return snapshot
+
+
+def has_any_task_artifact(task_dir_path: Path) -> bool:
+    for name in PLANNING_FILE_NAMES:
+        if (task_dir_path / name).is_file():
+            return True
+    for name in PLANNING_DIR_NAMES:
+        if (task_dir_path / name).exists():
+            return True
+    return False
+
+
+def sync_runtime_bundle(main_root: Path, worktree_root: Path) -> list[str]:
+    synced: list[str] = []
+    for relative_path in RUNTIME_BUNDLE_FILES:
+        src = main_root / relative_path
+        dst = worktree_root / relative_path
+        if not src.is_file() or _same_file(src, dst):
+            continue
+        _copy_file(src, dst)
+        synced.append(relative_path)
+    for relative_path in RUNTIME_BUNDLE_DIRS:
+        src = main_root / relative_path
+        dst = worktree_root / relative_path
+        if not src.is_dir() or _same_tree(src, dst):
+            continue
+        _copy_tree(src, dst)
+        synced.append(relative_path)
+    return synced
+
+
+def sync_task_snapshot(main_root: Path, worktree_root: Path, task_dir_name: str) -> list[str]:
+    source_task_dir = task_dir(main_root, task_dir_name)
+    target_task_dir = task_dir(worktree_root, task_dir_name)
+    if not source_task_dir.is_dir():
+        return []
+
+    synced: list[str] = []
+    for name in PLANNING_FILE_NAMES:
+        src = source_task_dir / name
+        if not src.is_file():
+            continue
+        dst = target_task_dir / name
+        if _same_file(src, dst):
+            continue
+        _copy_file(src, dst)
+        synced.append(name)
+
+    for name in PLANNING_DIR_NAMES:
+        src = source_task_dir / name
+        if not src.is_dir():
+            continue
+        dst = target_task_dir / name
+        if _same_tree(src, dst):
+            continue
+        _copy_tree(src, dst)
+        synced.append(name)
+
+    return synced
+
+
+def collect_task_drift(main_root: Path, worktree_root: Path, task_dir_name: str) -> list[str]:
+    source_snapshot = task_snapshot(task_dir(main_root, task_dir_name))
+    target_snapshot = task_snapshot(task_dir(worktree_root, task_dir_name))
+    keys = sorted(set(source_snapshot) | set(target_snapshot))
+    return [key for key in keys if source_snapshot.get(key) != target_snapshot.get(key)]
+
+
+def _is_managed_worktree_path(path_str: str, task_dir_name: str) -> bool:
+    normalized = path_str.replace("\\", "/").strip().strip("/")
+
+    for relative_path in RUNTIME_BUNDLE_FILES:
+        runtime_path = relative_path.strip("/")
+        if normalized == runtime_path:
+            return True
+    for relative_path in RUNTIME_BUNDLE_DIRS:
+        runtime_dir = relative_path.strip("/")
+        if normalized == runtime_dir or normalized.startswith(runtime_dir + "/"):
+            return True
+
+    task_root = f".trellis/tasks/{task_dir_name}"
+    if normalized in (".trellis/tasks", task_root):
+        return True
+    task_prefix = task_root + "/"
+    if not normalized.startswith(task_prefix):
+        return False
+    task_relative = normalized[len(task_prefix):]
+    if not task_relative:
+        return True
+    if task_relative in PLANNING_FILE_NAMES:
+        return True
+    for dir_name in PLANNING_DIR_NAMES:
+        if task_relative == dir_name or task_relative.startswith(dir_name + "/"):
+            return True
+    return False
+
+
+def _changed_paths_from_git_status(worktree_root: Path) -> list[str]:
+    code, stdout, _ = run_git(
+        ["status", "--porcelain", "-z", "--untracked-files=all"],
+        cwd=worktree_root,
+    )
+    if code != 0:
+        return []
+
+    changed_paths: list[str] = []
+    entries = stdout.split("\0")
+    index = 0
+    while index < len(entries):
+        entry = entries[index]
+        if not entry:
+            index += 1
+            continue
+
+        status = entry[:2]
+        if len(entry) > 3:
+            changed_paths.append(entry[3:].replace("\\", "/"))
+
+        if "R" in status or "C" in status:
+            index += 1
+            if index < len(entries) and entries[index]:
+                changed_paths.append(entries[index].replace("\\", "/"))
+
+        index += 1
+
+    return changed_paths
+
+
+def worktree_has_local_code_changes(worktree_root: Path, task_dir_name: str) -> bool:
+    if not worktree_root.exists():
+        return False
+    for relative_path in _changed_paths_from_git_status(worktree_root):
+        if not _is_managed_worktree_path(relative_path, task_dir_name):
+            return True
+    return False

package/dist/templates/trellis/workflow.md

@@ -185,10 +185,12 @@ Lightweight: `prd.md` can be enough. Complex: finish `prd.md`, `design.md`, and
 Multi-deliverable scope: consider a parent task plus independently verifiable child tasks; dependencies must be written in child artifacts, not implied by tree position.
 Sub-agent mode: curate `implement.jsonl` and `check.jsonl` as spec/research manifests before start.
 
-Planning order for this Claude Code path: `task.py create` → `trellis-brainstorm` → `trellis-grill-me` → development strategy decision.
+Claude Code research-first gate: for feature additions, feature changes, and bug fixes that depend on repository facts, run `trellis-research` before the first `trellis-brainstorm` question and persist findings to `{TASK_DIR}/research/`. When this gate triggers, explicitly tell the user that repository evidence is required, `trellis-research` is running first, and questioning will resume from the findings. Do not trigger this pre-brainstorm gate for pure conversation, capability or usage explanation, pure user preference choices, copy edits that do not depend on repository facts, explicitly local-only small tasks, or when the user explicitly asks to skip research and answer directly. If a later user answer would materially change the current understanding of repository facts, pause and run `trellis-research` again before the next question. If research is inconclusive, report what was checked, what evidence is missing, and which product intent or scope decision the user must provide before asking the question.
+Planning order for this Claude Code path: `task.py create` → `trellis-research` when the research-first gate applies → `trellis-brainstorm` → `trellis-grill-me` → development strategy decision.
 `trellis-grill-me` is a required planning gate on this Claude Code path, not an optional suggestion.
 Before `trellis-grill-me` is complete, do not enter development strategy decisions, do not create or complete `design.md` / `implement.md`, and do not run `task.py start`.
 Do not enter development strategy decisions until `prd.md` has been tightened through repository-first clarification and one-question-at-a-time follow-up.
+At the Claude Code development strategy decision point, prefer the native `AskUserQuestion` tool instead of plain Markdown prompts. Every `AskUserQuestion` question must have 2–4 options; do not put all five optional review gates in one question. Use structured questions for development/workspace mode, flow/architecture guidance, core review gates with `multiSelect: true`, and add-on review gates with `multiSelect: true`. Core review gates are `trellis-spec-review`, `trellis-code-review`, and `trellis-code-architecture-review`; add-on review gates are `trellis-improve-codebase-architecture` and `trellis-merge-review`. Do not offer default review-gate packages; let the user directly multi-select enabled gates, then write the explicit enabled/disabled lists. If `AskUserQuestion` is unavailable, rejected, or the user chooses Other, fall back to a text `A.` / `B.` / `C.` block or targeted free-text follow-up, but ask only for unresolved fields and never repeat answered choices unchanged.
 Before `task.py start`, record the development strategy decisions in the task documents. Complex tasks should store them in `implement.md`: development mode (current session / subagent), branch vs worktree, default flow vs TDD, plus a single `A.` / `B.` / `C.` style strategy block that records the task-level selection for `trellis-spec-review`, `trellis-code-review`, `trellis-code-architecture-review`, `trellis-improve-codebase-architecture`, and `trellis-merge-review`. New tasks must stamp that block with `Review-gate contract: explicit-selection-v1`. Use `Optional review gates status: pending` only while the choice is still open; before `task.py start`, replace it with `Optional review gates status: configured` plus explicit `Enabled optional review gates:` and `Disabled optional review gates:` lists. If the user does not select any optional gate, still record all five in the disabled list and keep `trellis-check` fixed outside the optional set. Only tasks that entirely lack `Review-gate contract: explicit-selection-v1` count as legacy tasks and preserve the old behavior; if the marker exists but the configured enabled/disabled lists are missing, planning is incomplete and the task must not start. `trellis-improve-codebase-architecture` deep-review requires `trellis-code-architecture-review`; do not record or accept deep-review without that prerequisite gate. If the strategy is `subagent + worktree`, pin the shared path to `./.trellis/trellis-worktrees/<task-dir-name>` and require every code-development subagent to use it. If the strategy is TDD, record `trellis-tdd` as the reference flow. Record whether to run pre-development architecture guidance in that same strategy block. If guidance is enabled, record `架构审查：enabled` in `implement.md`, dispatch `trellis-improve-codebase-architecture` with `架构审查模式: guidance` before `task.py start`, and append its output to `design.md`, but do NOT implicitly enable `trellis-improve-codebase-architecture` deep-review; that gate still requires explicit selection in the same task-level review-gate set.
 [/workflow-state:planning]
 
@@ -339,6 +341,14 @@ python3 ./.trellis/scripts/task.py create "<任务标题>" --slug <name>
 
 加载 `trellis-brainstorm` skill，并按该 skill 的指导与用户交互式澄清需求。
 
+Claude Code research-first gate:
+- 对新增功能、修改现有功能，以及依赖仓库事实的 bug fix，在第一个 `trellis-brainstorm` 问题前先分派 `trellis-research`，并把研究结果写入 `{TASK_DIR}/research/`。
+- 触发该门槛时，先明确告诉用户当前问题需要仓库证据、正在先执行 `trellis-research`，并会基于调研结果继续提问或收敛需求。
+- 排除：纯对话、能力说明、用法解释、纯用户偏好选择、不依赖仓库事实的文案润色、明确只做局部处理的小任务，以及用户明确要求先别 research / 先直接问的请求。
+- 第一次 research 后，问题必须基于 research 结果提出，而不是脱离仓库事实兜底猜测。
+- 如果用户回答会明显影响“仓库当前事实”，继续追问或收敛需求前必须再次分派 `trellis-research`。
+- 如果 research 无法找到足够证据，继续问用户前必须先报告已查证据、缺失证据和需要用户补充的具体意图或范围。
+
 brainstorm skill 会指导你：
 - 一次只问一个问题
 - 能靠调研回答的就先调研，不要先问用户
@@ -357,6 +367,13 @@ brainstorm skill 会指导你：
 - 启动拥有下一个交付物的子任务。Do not start the parent unless the parent itself has direct implementation work.
 
 在 Claude Code 路径进入实现前，把开发策略决策写入任务文档。
+- 进入开发策略决策时，优先调用 Claude Code 原生 `AskUserQuestion` 工具，而不是只输出普通 Markdown 选项块。
+- 每个 `AskUserQuestion` question 必须只有 2–4 options；不要把 5 个 optional review gates 放进同一个 question。
+- 推荐拆分为：开发模式 / 工作区模式单选、默认流程 / TDD 与架构指导单选、核心 review gates 多选、附加 review gates 多选。
+- 核心 review gates 问题使用 `multiSelect: true`，只包含 `trellis-spec-review`、`trellis-code-review`、`trellis-code-architecture-review`。
+- 附加 review gates 问题使用 `multiSelect: true`，只包含 `trellis-improve-codebase-architecture` 和 `trellis-merge-review`。
+- 不提供默认 review-gate 套餐；让用户直接多选要启用的 gates，再把未选项写入 disabled 列表。
+- 如果 `AskUserQuestion` 不可用、被拒绝或用户选择 Other，退回文本 `A.` / `B.` / `C.` 选项块或定向自由文本补问，但只补齐未决字段，不要原样重复已回答选择。
 - 轻量任务可以把这些记录写在 `prd.md`。
 - 复杂任务应把这些策略、task-local review-gate 选择，以及任何已启用 Claude review gate 的保序执行顺序写在 `implement.md`。
 - 需要在同一个 `A.` / `B.` / `C.` 风格策略块里记录：当前会话 vs subagent、当前分支 vs worktree、默认流程 vs TDD、是否启用 pre-development architecture guidance，以及 `trellis-spec-review`、`trellis-code-review`、`trellis-code-architecture-review`、`trellis-improve-codebase-architecture`、`trellis-merge-review` 的任务级选择。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "trellis-hgl",
-  "version": "0.6.0-beta.28",
+  "version": "0.6.0-beta.30",
   "description": "AI capabilities grow like ivy — Trellis provides the structure to guide them along a disciplined path",
   "type": "module",
   "main": "./dist/index.js",
@@ -34,7 +34,7 @@
     "inquirer": "^9.3.7",
     "undici": "^6.21.0",
     "zod": "^4.4.2",
-    "trellis-hgl-core": "0.6.0-beta.28"
+    "trellis-hgl-core": "0.6.0-beta.30"
   },
   "devDependencies": {
     "@eslint/js": "^9.18.0",