@xulthekl/team-flow 0.39.1 → 0.41.0

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

@@ -1,3 +1,3 @@
-# team-flow v0.39.1 | 阶段: {{state}} | 工作流: {{workflow}}
+# team-flow v0.41.0 | 阶段: {{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.1",
+      "version": "0.41.0",
       "source": "./",
       "author": {
         "name": "LT",

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "team-flow",
-  "version": "0.39.1",
+  "version": "0.41.0",
   "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.1",
+  "version": "0.41.0",
   "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.1"
+    "version": "0.41.0"
   },
   "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.1",
+  "version": "0.41.0",
   "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.1"
+    "version": "0.41.0"
   },
   "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.1",
+      "version": "0.41.0",
       "source": ".",
       "author": {
         "name": "LT",

package/AGENTS.md

@@ -68,8 +68,8 @@ spec 驱动开发过程。8 态变更机：`exploring → specifying → bridgin
 - 与 workflow-start 分层：orchestrator 管"做什么、什么顺序"（产品级策略），workflow-start 管"怎么做"（变更级执行）
 
 ### 7. workflow-bootstrap（1 skill，既有项目接入，v0.15.0 脚本+子代理侦察）
-- 一次性"侦察 + 基线建立"：代码库侦察 → 架构基线文档化 → 领域词汇提取 → 目录初始化 → 进入 workflow-orchestrator
-- **B1 侦察（v0.15.0）**：先跑确定性脚本 `scripts/recon-probe.sh`（可复现固定化采集）→ 并行派发 `codebase-recon-analyst` 子代理语义增强 → 主代理汇总写 baseline.md
+- 一次性"侦察 + 基线建立"：代码库侦察 → 架构基线文档化 → 领域词汇提取 → 目录初始化 → CLAUDE.md 初始化（B4.5，v0.41.0）→ 进入 workflow-orchestrator
+- **B1 侦察（v0.15.0）**：先跑确定性脚本 `scripts/recon-probe.sh`（可复现固定化采集，含 Git 子仓库结构 v0.41.0）→ 并行派发 `codebase-recon-analyst` 子代理语义增强（7 维度含 git-structure）→ 主代理汇总写 baseline.md（维度闭合校验 v0.41.0）
 - 仅首次使用时执行；`docs/architecture/baseline.md` 已存在则跳过
 
 ### 8. session-handoff（1 skill，会话交接，v0.16.0 新增）

package/CHANGELOG.md

@@ -6,6 +6,15 @@ The format loosely follows Keep a Changelog.
 
 ## [Unreleased]
 
+### Added（workflow-bootstrap CLAUDE.md 初始化 + Git 多子仓库识别，v0.41.0）
+
+- **B4.5 CLAUDE.md 初始化**（参考 Claude Code /init）：将项目基本信息（项目概况/开发命令/工作区结构/Git 结构）+ team-flow 产物结构索引写入工作区 CLAUDE.md；维护原则=索引级+结构级；已有 CLAUDE.md 追加模式（产物结构 + Git 管理规则章节），无则从 `templates/claude-md-team-flow.md` 新建
+- **CLAUDE.md 标准模板**：`skills/workflow-bootstrap/templates/claude-md-team-flow.md`（新建），覆盖 /init 内容 + team-flow 产物结构表（代码强制 + 设计层面）
+- **recon-probe.sh ⑧ Git 子仓库扫描**：识别嵌套 git 仓库 / submodule / .gitignore 忽略规则，JSON 新增 `git_structure` 字段（is_git_repo / sub_repos[{path,type,has_remote}] / submodules / gitignore_ignores_subrepos）
+- **codebase-recon-analyst git-structure 维度**：侦察维度 6→7，识别子仓库用途（代码库/文档/工具）+ git 操作约束（提交/推送顺序、版本联动、隔离）
+- **B1.3 维度闭合校验**：汇总前核对已派发维度 vs 已返回 handoff（status + deliverable 非空），缺失维度标 INCOMPLETE（advisory 不阻断，Success Output 警告）
+- **AGENTS.md 同步**：workflow-bootstrap 流程描述补 B4.5 + git-structure + 闭合校验
+
 ## [0.39.0] - 2026-08-06
 
 ### Added（workflow-feedback 环境版本记录）

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.1 | 阶段: {{state}} | 工作流: {{workflow}}
+# team-flow v0.41.0 | 阶段: {{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.1**。
+当前发布版本：**v0.41.0**。
 
 ---
 

package/README.md

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

package/docs/README_en.md

@@ -126,7 +126,7 @@ npm install -g team-flow
 
 ### Version
 
-- Current: `v0.39.1`
+- Current: `v0.41.0`
 - 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.1",
+  "version": "0.41.0",
   "contextFileName": "GEMINI.md"
 }

package/hooks/session-start

@@ -1,11 +1,11 @@
 #!/usr/bin/env bash
-# v0.39.1: auto-sync CLI version with plugin version
+# v0.41.0: auto-sync CLI version with plugin version
 set -e
 
 # ═══════════════════════════════════════════════════════════════
 # Plugin version (update this when releasing new versions)
 # ═══════════════════════════════════════════════════════════════
-PLUGIN_VERSION="0.39.1"
+PLUGIN_VERSION="0.41.0"
 
 # ═══════════════════════════════════════════════════════════════
 # 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.1.
+Current version: v0.41.0.
 
 ## 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.1",
+  "version": "0.41.0",
   "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.1",
+  "version": "0.41.0",
   "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) {