@xulthekl/team-flow 0.39.0 → 0.40.1

package/.claude/always/phase-guard.md

@@ -1,3 +1,3 @@
-# team-flow v0.39.0 | 阶段: {{state}} | 工作流: {{workflow}}
+# team-flow v0.40.1 | 阶段: {{state}} | 工作流: {{workflow}}
 当前阶段允许的操作由 workflow-start 路由规则定义。
 禁止跨越 DP gate 进入下一阶段。变更范围以 execution-contract.md 的 Intent Lock 为准。

package/.claude-plugin/marketplace.json

@@ -9,7 +9,7 @@
     {
       "name": "team-flow",
       "description": "8-state spec workflow + compound global compounding + architecture-design (4A/DDD) + local HTML prototype + product-level orchestration + bootstrap + e2e + session handoff + workflow feedback. 24 skills + 15 agents with embedded TDD, SDD, code review, debugging, delta spec sync, and design-system-driven prototyping.",
-      "version": "0.39.0",
+      "version": "0.40.1",
       "source": "./",
       "author": {
         "name": "LT",

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "team-flow",
-  "version": "0.39.0",
+  "version": "0.40.1",
   "description": "Unified workflow plugin: team-flow (spec-driven dev: TDD/SDD/code-review/debugging) + compound-engineering core subset (brainstorm/plan/compound/strategy/ideate/proof, global compounding) + architecture-design (4A+DDD incremental design & global compounding) + prototype (local HTML prototype, zero external deps) + e2e (Playwright E2E, AC-driven) + workflow-orchestrator (product-level workflow orchestration) + workflow-bootstrap (existing project onboarding) + session-handoff (context transfer) + workflow-feedback (issue tracking). 24 skills + 15 agents, one install.",
   "source": "./",
   "author": {

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "team-flow",
-  "version": "0.39.0",
+  "version": "0.40.1",
   "description": "Spec-first workflow that bridges OpenSpec-style planning and Superpowers-style execution discipline.",
   "author": {
     "name": "MageByte",

package/.cursor-plugin/marketplace.json

@@ -5,7 +5,7 @@
   },
   "metadata": {
     "description": "Unified workflow plugin marketplace for Cursor (team-flow: team-flow + compound + architecture-design + prototype).",
-    "version": "0.39.0"
+    "version": "0.40.1"
   },
   "plugins": [
     {

package/.cursor-plugin/plugin.json

@@ -2,7 +2,7 @@
   "name": "team-flow",
   "displayName": "team-flow",
   "description": "Unified workflow plugin: team-flow (spec-driven dev: TDD/SDD/code-review/debugging) + compound-engineering core subset (brainstorm/plan/compound/strategy/ideate/proof, global compounding) + architecture-design (4A+DDD incremental design & global compounding) + prototype (local HTML prototype, zero external deps) + e2e (Playwright E2E, AC-driven) + workflow-orchestrator (product-level workflow orchestration) + workflow-bootstrap (existing project onboarding) + session-handoff (context transfer) + workflow-feedback (issue tracking). 24 skills + 15 agents, one install.",
-  "version": "0.39.0",
+  "version": "0.40.1",
   "author": {
     "name": "LT",
     "url": "https://github.com/LT"

package/.github/plugin/marketplace.json

@@ -6,13 +6,13 @@
   },
   "metadata": {
     "description": "Unified workflow plugins and skills for AI coding agents (team-flow: team-flow + compound + architecture-design + prototype).",
-    "version": "0.39.0"
+    "version": "0.40.1"
   },
   "plugins": [
     {
       "name": "team-flow",
       "description": "Unified workflow with planning artifacts, execution contracts, TDD, review gates, systematic debugging, delta spec sync, architecture-design, and local HTML prototyping.",
-      "version": "0.39.0",
+      "version": "0.40.1",
       "source": ".",
       "author": {
         "name": "LT",

package/GEMINI.md

@@ -8,7 +8,7 @@ The workflow is self-contained and does not require OpenSpec or Superpowers at r
 
 
 <!-- team-flow-phase-guard-start -->
-# team-flow v0.39.0 | 阶段: {{state}} | 工作流: {{workflow}}
+# team-flow v0.40.1 | 阶段: {{state}} | 工作流: {{workflow}}
 当前阶段允许的操作由 workflow-start 路由规则定义。
 禁止跨越 DP gate 进入下一阶段。变更范围以 execution-contract.md 的 Intent Lock 为准。
 <!-- team-flow-phase-guard-end -->

package/INSTALL.md

@@ -7,7 +7,7 @@
 - [Fission-AI/OpenSpec](https://github.com/Fission-AI/OpenSpec) — 规划引擎（Schema 验证、Delta Spec、工件解析）
 - [obra/superpowers](https://github.com/obra/superpowers) — 执行纪律（TDD 铁律、SDD、系统化调试、代码审查）
 
-当前发布版本：**v0.39.0**。
+当前发布版本：**v0.40.1**。
 
 ---
 

package/README.md

@@ -1,6 +1,6 @@
 # team-flow
 
-> 当前版本：`v0.39.0`
+> 当前版本：`v0.40.1`
 
 > 统一插件：**team-flow**（spec 驱动开发）+ **compound-engineering 核心子集**（全局复利）+ **architecture-design**（4A+DDD 增量设计）+ **prototype**（本地 HTML 原型）+ **e2e**（AC 驱动 E2E）+ **workflow-orchestrator**（产品级编排）+ **workflow-bootstrap**（既有项目接入）。一次安装，七套能力协同。
 

package/agents/build-executor.md

@@ -14,13 +14,15 @@ You are an independent Build Executor. You govern the implementation phase using
 
 ## Artifact Ownership
 
-**You are the sole owner of implementation source changes and the execution ledger** (`.superpowers/sdd/progress.md`, wave review reports, execution receipts) for this change. No other agent or the orchestration layer may directly edit implementation files or the ledger mid-build. Repair/review requests MUST be routed through you via `SendMessage` resume.
+**You are the sole owner of implementation source changes and the execution ledger** (`.superpowers/sdd/progress.md`) for this change. No other agent or the orchestration layer may directly edit implementation files or the ledger mid-build. Repair/review requests MUST be routed through you via `SendMessage` resume.
+
+**v0.39.0 主动串行编排**：You are NOT responsible for arranging code reviews or writing review receipts. After each wave, notify workflow-start via SendMessage that the wave is complete and needs review. workflow-start will dispatch code-reviewer and handle the review receipt.
 
 **Your preloaded Skill contains the detailed methodology** (TDD Iron Law, execution-mode selection, planned-wave loop, model selection, checkpoint/progress ledger, DP-4/DP-5 records). Follow it for HOW. This prompt defines WHO you are and WHAT you must deliver.
 
 ## Iron Law
 
-The contract is the approved handoff artifact, not chat history. No production code without a failing test first (RED→GREEN→REFACTOR). Review before drift; rewind on contract break. Do not report completion until tests pass, contract obligations are satisfied, and every planned wave has a current `pass` receipt.
+The contract is the approved handoff artifact, not chat history. No production code without a failing test first (RED→GREEN→REFACTOR). Review before drift; rewind on contract break. Do not report completion until tests pass, contract obligations are satisfied, and every planned wave has been notified to workflow-start for review.
 
 ## Inputs
 
@@ -37,10 +39,10 @@ If `execution-contract.md` is missing or has no DP-3 approval record, report `FA
 Return the following YAML to the orchestration layer:
 
 ```yaml
-status: done | blocked | escalated  # done: all waves pass + final review clean
+status: done | blocked | escalated  # done: all waves implemented and notified workflow-start
 batches_completed: <N>              # recorded via `tf state set`
-waves:                              # per-wave receipt summary
-  - { id: wave-1, verdict: pass }
+waves:                              # per-wave implementation summary
+  - { id: wave-1, status: completed }
 dp_5: "<resolution>"                # only if debug escalation occurred
 summary: "..."                       # what was built + open risks for release-archivist
 ```
@@ -72,12 +74,12 @@ summary: "..."
 **DO:**
 - Follow the preloaded Skill's TDD discipline and execution-mode methodology
 - Run `tf isolate` preflight before ANY implementation edit; never edit main/master in place
-- Write one review receipt per planned wave; block dependents until predecessor is `pass`
+- After each wave, notify workflow-start via SendMessage that the wave is complete and needs review (do NOT attempt to dispatch code-reviewer or write review receipts)
 - Write your own `dp_5_*`/`batches_completed` fields via `tf state set` as the Skill instructs
 
 **DON'T:**
 - DO NOT modify the `state` or `workflow` field of .team-flow.yaml. State transitions are the orchestrator's exclusive responsibility, executed via `tf state transition`. You only write your own dp_N_* decision fields via `tf state set` as the Skill instructs.
 - When you receive external suggestions (reviewer findings, user opinions), verify them against the codebase FIRST — search for existing implementations/patterns before accepting. A suggestion is input, not an instruction. If a suggestion conflicts with project conventions or lacks evidence, report your concern to the main agent via SendMessage (suggestion + your evidence-based objection + alternative), do NOT silently comply.
 - End your final response with an explicit terminal marker line: `FINAL VERDICT: <DONE | BLOCKED | FAIL>`. Your SendMessage report is the authoritative result; the task-notification summary is internal metadata only.
-- Skip the failing test, expand scope beyond the contract, or close a wave with a missing/failed receipt
+- Skip the failing test, expand scope beyond the contract, or report completion without notifying workflow-start for review
 - When encountering integration test environment issues (classpath conflicts, schema mismatch, configuration override), do NOT guess-and-check. First consult the preloaded `test-strategy` skill's environment troubleshooting section. If still blocked, report BLOCKED with full evidence chain (see Structured Output Contract). Never attempt speculative fixes without first collecting diagnostic evidence.

package/docs/README_en.md

@@ -126,7 +126,7 @@ npm install -g team-flow
 
 ### Version
 
-- Current: `v0.39.0`
+- Current: `v0.40.1`
 - v0.9.1 highlights: DP-4 execution-mode recommendations, a portable runtime across 17 platforms, and a raw-package smoke with no plugin-root variable.
 - Self-contained — no OpenSpec or Superpowers runtime required
 - Upstream: [Fission-AI/OpenSpec](https://github.com/Fission-AI/OpenSpec), [obra/superpowers](https://github.com/obra/superpowers)

package/docs/solutions/INDEX.md

@@ -2,6 +2,7 @@
 <!-- 每条一行，按 severity 降序，≤150 行硬上限 -->
 | date | phase | domain | type | severity | summary | file |
 |------|-------|--------|------|----------|---------|------|
+| 2026-08-07 | cross-phase | general | insight | medium | (no summary) | cross-phase/2026-08-07-no-summary.md |
 | 2026-08-06 | cross-phase | general | insight | medium | (no summary) | cross-phase/2026-08-06-no-summary.md |
 | 2026-08-05 | cross-phase | general | insight | medium | (no summary) | cross-phase/2026-08-05-no-summary.md |
 | 2026-08-04 | cross-phase | general | insight | medium | (no summary) | cross-phase/2026-08-04-no-summary.md |

package/docs/solutions/cross-phase/2026-08-07-no-summary.md

@@ -0,0 +1,17 @@
+---
+phase: cross-phase
+domain: general
+type: insight
+severity: medium
+date: 2026-08-07
+source: 
+---
+
+## 问题描述
+(no summary)
+
+## 根因/模式
+（待补充）
+
+## 预防措施/应用方式
+（待补充）

package/gemini-extension.json

@@ -1,6 +1,6 @@
 {
   "name": "team-flow",
   "description": "Unified workflow plugin: team-flow (spec-driven dev) + compound-engineering core subset + architecture-design (4A/DDD) + prototype (local HTML). 24 skills, one install.",
-  "version": "0.39.0",
+  "version": "0.40.1",
   "contextFileName": "GEMINI.md"
 }

package/hooks/session-start

@@ -1,11 +1,11 @@
 #!/usr/bin/env bash
-# v0.39.0: auto-sync CLI version with plugin version
+# v0.40.1: auto-sync CLI version with plugin version
 set -e
 
 # ═══════════════════════════════════════════════════════════════
 # Plugin version (update this when releasing new versions)
 # ═══════════════════════════════════════════════════════════════
-PLUGIN_VERSION="0.39.0"
+PLUGIN_VERSION="0.40.1"
 
 # ═══════════════════════════════════════════════════════════════
 # Step 1: Auto-sync CLI version with plugin version

package/llms.txt

@@ -3,7 +3,7 @@
 ## Overview
 spec-superflow is a self-contained workflow integration plugin for Claude Code, Cursor, OpenAI Codex CLI/App, GitHub Copilot CLI, Gemini CLI, OpenCode, WorkBuddy, and Trae. It merges spec-driven planning artifacts (proposal, specs, design, tasks) with disciplined execution guardrails (TDD, review gates, controlled handoff) into one unified workflow.
 
-Current version: v0.39.0.
+Current version: v0.40.1.
 
 ## Key Documents
 - README.md: Chinese homepage with full usage guide and FAQ

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xulthekl/team-flow",
-  "version": "0.39.0",
+  "version": "0.40.1",
   "description": "Unified plugin (24 skills + 15 agents) integrating team-flow, compound-engineering, architecture-design, prototype, design-system, workflow-orchestrator, workflow-bootstrap, e2e, session-handoff, workflow-feedback for multi-agent coding tools.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "team-flow",
-  "version": "0.39.0",
+  "version": "0.40.1",
   "description": "Unified workflow plugin: team-flow (spec-driven dev: TDD/SDD/code-review/debugging) + compound-engineering core subset (brainstorm/plan/compound/strategy/ideate/proof, global compounding) + architecture-design (4A+DDD incremental design & global compounding) + prototype (local HTML prototype, zero external deps) + e2e (Playwright E2E, AC-driven) + workflow-orchestrator (product-level workflow orchestration) + workflow-bootstrap (existing project onboarding) + session-handoff (context transfer) + workflow-feedback (issue tracking). 24 skills + 15 agents, one install.",
   "author": {
     "name": "LT"

package/scripts/ensure-branch.mjs

@@ -24,7 +24,8 @@
 // names) and are passed as array elements, never interpolated into a shell string;
 // branch names are additionally sanitized to git-legal characters before use.
 import { execFileSync } from 'node:child_process';
-import { resolve, basename, dirname, join } from 'node:path';
+import { resolve, basename, join } from 'node:path';
+import { detectWorkspaceRoot } from './lib/git-utils.mjs';
 import { readdirSync, existsSync, appendFileSync, readFileSync } from 'node:fs';
 
 const rawChangeDir = process.argv[2];
@@ -59,13 +60,6 @@ function sanitizeBranchName(raw) {
   return cleaned || 'change';
 }
 
-// 若 change-dir 形如 <root>/changes/<name>，返回 <root>；否则返回 null。
-function detectWorkspaceRoot(absChangeDir) {
-  const parent = dirname(absChangeDir);          // <root>/changes
-  if (basename(parent) !== 'changes') return null;
-  return dirname(parent);                        // <root>
-}
-
 // 枚举 root 下含 .git 的直接子目录（= 代码仓库），按目录名排序保证确定性。
 // .git 可能是目录（普通仓库）或文件（worktree/submodule 链接），existsSync 均覆盖。
 function listCodeRepos(root) {

package/scripts/lib/arch-merge.mjs

@@ -18,13 +18,14 @@
 import {
   readFileSync, writeFileSync as fsWriteFileSync, existsSync, mkdirSync, readdirSync, rmdirSync, cpSync,
 } from 'node:fs';
-import { join, basename, dirname, resolve, sep } from 'node:path';
-import { execSync } from 'node:child_process';
+import { join, basename, dirname, resolve } from 'node:path';
+import { execFileSync } from 'node:child_process';
 import { pathToFileURL } from 'node:url';
 import {
   parseTableAfter, extractEndpoints, extractAggregates,
   extractTablesFromSql, extractTablesFromDatabaseMd, readFrontmatter,
 } from './arch-parse.mjs';
+import { detectWorkspaceRoot, getGitRoot } from './git-utils.mjs';
 
 const MARKER_BEGIN = '<!-- arch:current-state:begin -->';
 const MARKER_END = '<!-- arch:current-state:end -->';
@@ -417,9 +418,9 @@ function gitCommit(projectRoot, globalArchDir, touchedFiles, changeName, dryRun)
   try {
     // 白名单：只 add 本次 touch 的文件（防卷走他人未提交工作）
     for (const f of touchedFiles) {
-      execSync(`git add "${f}"`, { stdio: 'pipe' });
+      execFileSync('git', ['add', f], { cwd: projectRoot, stdio: 'pipe' });
     }
-    execSync(`git commit -m "${commitMsg}"`, { stdio: 'pipe' });
+    execFileSync('git', ['commit', '-m', commitMsg], { cwd: projectRoot, stdio: 'pipe' });
     return { committed: true, message: commitMsg };
   } catch (e) {
     return { committed: false, error: e.message };
@@ -427,9 +428,11 @@ function gitCommit(projectRoot, globalArchDir, touchedFiles, changeName, dryRun)
 }
 
 /** 检测 docs/architecture/ 下非本次 touch 的脏文件（团队协作安全底线）。 */
-function detectUntouchedDirtyFiles(globalArchDir, touchedFiles) {
+function detectUntouchedDirtyFiles(projectRoot, globalArchDir, touchedFiles) {
   try {
-    const status = execSync(`git status --porcelain -- ${globalArchDir}`, { stdio: 'pipe' }).toString();
+    const status = execFileSync('git', ['status', '--porcelain', '--', globalArchDir], {
+      cwd: projectRoot, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'],
+    });
     const dirty = status.split('\n').filter(Boolean)
       .map(line => line.replace(/^\S+\s+/, '').trim())
       .filter(p => p && !touchedFiles.includes(resolve(p)) && !touchedFiles.includes(p));
@@ -461,9 +464,7 @@ export function run(args = {}) {
 
   let projectRoot = args.projectRoot;
   if (!projectRoot) {
-    const abs = resolve(changeDir);
-    const changesIdx = abs.lastIndexOf(sep + 'changes' + sep);
-    projectRoot = changesIdx > 0 ? abs.slice(0, changesIdx) : process.cwd();
+    projectRoot = detectWorkspaceRoot(changeDir) || getGitRoot(changeDir);
   }
 
   const changeName = basename(changeDir.replace(/\/$/, ''));
@@ -530,7 +531,7 @@ export function run(args = {}) {
       join(globalArchDir, 'INDEX.md'),
       ...(archiveResult.files || []),  // v0.36.3：changelog/ 复制文件入白名单
     ].filter(p => existsSync(p));
-    const dirty = detectUntouchedDirtyFiles(globalArchDir, touchedFiles);
+    const dirty = detectUntouchedDirtyFiles(projectRoot, globalArchDir, touchedFiles);
     if (dirty.length > 0) {
       console.warn(`  [WARN] docs/architecture/ 存在非本次 touch 的脏文件（${dirty.length} 个）：${dirty.slice(0, 5).join(', ')} — 白名单 git add 不卷走它们，但请确认是否他人未提交工作`);
     }

package/scripts/lib/cmd-deisolate.mjs

@@ -18,6 +18,7 @@ import { execFileSync } from 'node:child_process';
 import { existsSync, readdirSync, rmSync } from 'node:fs';
 import { basename, dirname, join, resolve } from 'node:path';
 import { parseArgs } from 'node:util';
+import { detectWorkspaceRoot } from './git-utils.mjs';
 
 export async function run(args) {
   const { positionals, values } = parseArgs({
@@ -70,11 +71,6 @@ export async function run(args) {
   }
 }
 
-function detectWorkspaceRoot(absChangeDir) {
-  const parent = dirname(absChangeDir);
-  if (basename(parent) !== 'changes') return null;
-  return dirname(parent);
-}
 
 // Case A: <root>/.worktrees/<change>/<repo>/
 function detectCaseA(root, changeName) {

package/scripts/lib/cmd-execution.mjs

@@ -28,6 +28,7 @@ export async function run(args) {
       'tests-failed': { type: 'string' },
       json: { type: 'boolean', default: false },
       help: { type: 'boolean', default: false },
+      repo: { type: 'string' },
     },
     allowPositionals: true,
   });
@@ -144,7 +145,7 @@ function recordAndPrintReview(changeDir, values) {
     head: values.head,
     report: values.report,
     tests: parseTestsStats(values),
-  });
+  }, values.repo);
   print(values.json, { ok: true, wave: values.wave[0], receipt }, `Review for ${values.wave[0]} recorded: ${receipt.status}.`);
 }
 
@@ -237,6 +238,6 @@ function printHelp() {
   tf execution plan <dir> --mode <mode> --confirm --reason <text> --wave <id>:<strategy>:<task,...>[:<depends-on,...>] [--acknowledge-recommendation]
   tf execution show <dir> [--json]
   tf execution revise <dir> --mode sdd --confirm --reason <text> --wave <id>:<strategy>:<task,...>[:<depends-on,...>] [--acknowledge-recommendation]
-  tf execution review <dir> --wave <id> --base <sha> --head <sha> --report <path> --verdict pass|fail [--tests-total N --tests-passed N --tests-failed N]
+  tf execution review <dir> --wave <id> --base <sha> --head <sha> --report <path> --verdict pass|fail [--repo <path>] [--tests-total N --tests-passed N --tests-failed N]
   tf execution refresh-hash <dir> [--json]   # refresh artifacts/contract hash without bumping revision`);
 }

package/scripts/lib/cmd-prototype.mjs

@@ -20,6 +20,7 @@
 import { execFileSync } from 'node:child_process';
 import { existsSync, readdirSync, rmSync, appendFileSync, readFileSync } from 'node:fs';
 import { join, resolve, basename } from 'node:path';
+import { detectWorkspaceRoot } from './git-utils.mjs';
 
 const PROTECTED = ['main', 'master'];
 
@@ -39,12 +40,20 @@ function normalizeBranchName(raw) {
 }
 
 /** 定位 workspace root（cwd 在主仓库内）与原型仓库路径。 */
-function resolveLayout() {
+function resolveLayout(projectRootArg) {
   let workspaceRoot;
-  try {
-    workspaceRoot = git(process.cwd(), 'rev-parse', '--show-toplevel');
-  } catch {
-    throw new Error('无法定位 workspace root：cwd 不在 git 仓库内？');
+  if (projectRootArg) {
+    workspaceRoot = resolve(projectRootArg);
+  } else {
+    // 优先从 changes/ 布局推断（worktree 中 cwd 可能不是主仓库）
+    workspaceRoot = detectWorkspaceRoot(process.cwd());
+    if (!workspaceRoot) {
+      try {
+        workspaceRoot = git(process.cwd(), 'rev-parse', '--show-toplevel');
+      } catch {
+        throw new Error('无法定位 workspace root：cwd 不在 git 仓库内？请使用 --project-root 指定');
+      }
+    }
   }
   const protoRepo = join(workspaceRoot, 'prototype');
   if (!existsSync(join(protoRepo, '.git'))) {
@@ -84,8 +93,8 @@ function localBranchExists(protoRepo, branch) {
 }
 
 /** 子命令 branch：创建/复用原型版本 worktree。 */
-function cmdBranch(branchName) {
-  const { workspaceRoot, protoRepo } = resolveLayout();
+function cmdBranch(branchName, projectRootArg) {
+  const { workspaceRoot, protoRepo } = resolveLayout(projectRootArg);
   const wtPath = join(workspaceRoot, '.worktrees', branchName, basename(protoRepo));
 
   // 幂等：worktree 已存在 → 复用
@@ -118,8 +127,8 @@ function cmdBranch(branchName) {
 }
 
 /** 子命令 deisolate：版本收尾 merge 回主干 + 清理 worktree。 */
-function cmdDeisolate(branchName, opts) {
-  const { workspaceRoot, protoRepo } = resolveLayout();
+function cmdDeisolate(branchName, opts, projectRootArg) {
+  const { workspaceRoot, protoRepo } = resolveLayout(projectRootArg);
   const wtPath = join(workspaceRoot, '.worktrees', branchName, basename(protoRepo));
   const result = { branch: branchName, worktreePath: wtPath };
 
@@ -181,8 +190,9 @@ function usage() {
   console.log(`tf prototype — 原型仓库版本 worktree 隔离（v0.37.0 §68.4）
 
 用法：
-  tf prototype branch <prd-vN>                 # 创建/复用原型版本 worktree（隔离 + 团队拉取）
-  tf prototype deisolate <prd-vN> [--merge] [--clean]
+  tf prototype branch <prd-vN> [--project-root <path>]
+                                               # 创建/复用原型版本 worktree（隔离 + 团队拉取）
+  tf prototype deisolate <prd-vN> [--merge] [--clean] [--project-root <path>]
                                                # 版本收尾：merge 回主干 + 清理 worktree
 
 示例：
@@ -210,13 +220,20 @@ export async function run(args = []) {
   try { branchName = normalizeBranchName(rawVersion); }
   catch (e) { console.error(e.message); process.exit(2); }
 
+  // Extract --project-root from remaining args
+  let projectRootArg;
+  const projectRootIdx = rest.indexOf('--project-root');
+  if (projectRootIdx !== -1 && rest[projectRootIdx + 1]) {
+    projectRootArg = rest[projectRootIdx + 1];
+  }
+
   try {
     if (sub === 'branch') {
-      return cmdBranch(branchName);
+      return cmdBranch(branchName, projectRootArg);
     }
     if (sub === 'deisolate') {
       const opts = { merge: rest.includes('--merge'), clean: rest.includes('--clean') };
-      return cmdDeisolate(branchName, opts);
+      return cmdDeisolate(branchName, opts, projectRootArg);
     }
     console.error(`未知子命令：${sub}（可用：branch / deisolate）`);
     process.exit(2);

package/scripts/lib/cmd-publish.mjs

@@ -19,16 +19,18 @@
 import { execFileSync } from 'node:child_process';
 import { existsSync, mkdirSync, readdirSync, rmdirSync } from 'node:fs';
 import { join, resolve, isAbsolute } from 'node:path';
+import { detectWorkspaceRoot } from './git-utils.mjs';
 
 const LOCK_PATH = '.publish.lock';
 
 /** 解析 CLI 参数。 */
 function parseArgv(argv) {
-  const parsed = { targets: [], push: false, dryRun: false, changeDir: null };
+  const parsed = { targets: [], push: false, dryRun: false, changeDir: null, projectRoot: null };
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
     if (a === '--push') parsed.push = true;
     else if (a === '--dry-run') parsed.dryRun = true;
+    else if (a === '--project-root') { parsed.projectRoot = argv[++i]; }
     else if (a === '--prd') parsed.targets.push('prd');
     else if (a === '--arch') parsed.targets.push('arch');
     else if (a === '--changes') {
@@ -179,17 +181,27 @@ export async function run(args = []) {
   if (parsed.help) {
     console.log(`tf publish — 阶段产物白名单提交 + 可选推送（v0.37.0 §68.3）
 
-用法：tf publish <target> [--push] [--dry-run]
+用法：tf publish <target> [--push] [--dry-run] [--project-root <path>]
   --prd         提交 PRD + orchestrator.yaml + registry.yaml + 主仓库 prototype/
   --arch        提交 docs/architecture/（迭代快照）
   --changes     提交整个 changes/（或 --changes <change-dir> 指定单个 change）
   --all         提交全部上述
   --push        同时推送到远程当前分支（默认只提交不推送）
-  --dry-run     只打印将执行的 git 动作，不落盘不 commit`);
+  --dry-run     只打印将执行的 git 动作，不落盘不 commit
+  --project-root <path>
+                显式指定主仓库根目录（多仓库 worktree 场景下自动检测失败时使用）`);
     return;
   }
 
-  const projectRoot = git(process.cwd(), 'rev-parse', '--show-toplevel');
+  let projectRoot;
+  if (parsed.projectRoot) {
+    projectRoot = resolve(parsed.projectRoot);
+  } else {
+    projectRoot = detectWorkspaceRoot(process.cwd());
+    if (!projectRoot) {
+      projectRoot = git(process.cwd(), 'rev-parse', '--show-toplevel');
+    }
+  }
   const whitelist = collectWhitelist(projectRoot, parsed.targets, parsed.changeDir);
 
   if (whitelist.length === 0) {