@xulthekl/team-flow 0.47.0 → 0.48.0

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

@@ -1,3 +1,3 @@
-# team-flow v0.47.0 | 阶段: {{state}} | 工作流: {{workflow}}
+# team-flow v0.48.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 + independent business analysis. 26 skills + 17 agents with embedded TDD, SDD, code review, debugging, delta spec sync, and design-system-driven prototyping.",
-      "version": "0.47.0",
+      "version": "0.48.0",
       "source": "./",
       "author": {
         "name": "LT",

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "team-flow",
-  "version": "0.47.0",
+  "version": "0.48.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) + business-analysis (independent requirement/scenario artifact). 26 skills + 17 agents, one install.",
   "source": "./",
   "author": {

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "team-flow",
-  "version": "0.47.0",
+  "version": "0.48.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.47.0"
+    "version": "0.48.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) + business-analysis (independent requirement/scenario artifact). 26 skills + 17 agents, one install.",
-  "version": "0.47.0",
+  "version": "0.48.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.47.0"
+    "version": "0.48.0"
   },
   "plugins": [
     {
       "name": "team-flow",
       "description": "Unified workflow with planning artifacts, execution contracts, TDD, review gates, systematic debugging, delta spec sync, architecture-design, independent business analysis, and local HTML prototyping.",
-      "version": "0.47.0",
+      "version": "0.48.0",
       "source": ".",
       "author": {
         "name": "LT",

package/CHANGELOG.md

@@ -4,6 +4,20 @@ All notable changes to `team-flow` will be documented in this file.
 
 The format loosely follows Keep a Changelog.
 
+## [0.48.0] - 2026-08-21
+
+### Added（多仓库场景支持，v0.48.0）
+
+设计来源：`docs/plan/multi-repo-support-design.md` v1.0（2026-08-21，fytx-message 4 feedback：cli-command-1/2 + sop-flow-1/2）
+
+- **repo_layout 机制**（P0）：`detectRepoLayout` 判定 single/monorepo/multi-repo + 代码仓库清单；`tf repo-layout detect <root>` CLI 写 `repo_layout` 段到 `team-flow.config.json`；config-loader DEFAULTS 固化
+- **detect 修复**（P1，cli-command-1）：change 目录→项目根解析（detectWorkspaceRoot/getGitRoot）；repos 清单聚合判定 `is_glaf4_java`（任一仓库 Java → 项目级 true）；`--target-repo` 精确探测；config 主副本写项目根（不再写 change 目录）
+- **review 修复**（P2，cli-command-2）：overlay 目录自动创建（修 ENOENT）；`--repo <代码仓库>` 提供 base/head git 校验上下文；multi-repo 下 change 目录无 git 不再报错（--repo 场景）
+- **isolate 修复**（P2，sop-flow-2）：`checkSharedBranch` 检测 origin tracking + ahead/behind（有 upstream 即共享）；共享分支建 worktree 而非就地实施；`checkUncommitted` 报告未提交变更归属
+- **流程接入**（P3）：workflow-start DP-0 + orchestrator S1 项目模式确认（识别存量结构，写 repo_layout config）
+- **三评审闭环**：P3 code-reviewer（2 Important + 8 Minor）+ P4 plugin-validator（7 minor）+ skill-reviewer（5 minor）全修
+- 723/723 测试通过
+
 ## [0.47.0] - 2026-08-21
 
 ### Added（PRD §8.4 契约级详述规范，v0.47.0）

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

package/README.md

@@ -1,6 +1,6 @@
 # team-flow
 
-> 当前版本：`v0.47.0`
+> 当前版本：`v0.48.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.47.0`
+- Current: `v0.48.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/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) + business-analysis (independent requirement/scenario artifact). 26 skills, one install.",
-  "version": "0.47.0",
+  "version": "0.48.0",
   "contextFileName": "GEMINI.md"
 }

package/hooks/session-start

@@ -1,11 +1,11 @@
 #!/usr/bin/env bash
-# v0.47.0: auto-sync CLI version with plugin version
+# v0.48.0: auto-sync CLI version with plugin version
 set -e
 
 # ═══════════════════════════════════════════════════════════════
 # Plugin version (update this when releasing new versions)
 # ═══════════════════════════════════════════════════════════════
-PLUGIN_VERSION="0.47.0"
+PLUGIN_VERSION="0.48.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.47.0.
+Current version: v0.48.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.47.0",
+  "version": "0.48.0",
   "description": "Unified plugin (26 skills + 17 agents) integrating team-flow, compound-engineering, architecture-design, prototype, design-system, workflow-orchestrator, workflow-bootstrap, e2e, session-handoff, workflow-feedback, business-analysis 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.47.0",
+  "version": "0.48.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) + business-analysis (independent requirement/scenario artifact). 26 skills + 17 agents, one install.",
   "author": {
     "name": "LT"

package/scripts/ensure-branch.mjs

@@ -60,6 +60,53 @@ function sanitizeBranchName(raw) {
   return cleaned || 'change';
 }
 
+// 检查未提交变更（sop-flow-2，multi-repo-support-design v1.0 §4.3 未提交变更归属）。
+// git status --porcelain 统计未提交文件；worktree 基于已提交 HEAD 创建，未提交变更不自动带入，
+// 报告数与文件列表供人工/编排确认归属（是否属于当前 change）。
+function checkUncommitted(repoDir) {
+  const opts = { encoding: 'utf-8', cwd: repoDir, stdio: ['ignore', 'pipe', 'pipe'] };
+  try {
+    const out = execFileSync('git', ['status', '--porcelain'], opts).toString();
+    const files = out.split('\n').filter(Boolean);
+    return { count: files.length, files };
+  } catch {
+    return { count: 0, files: [] };
+  }
+}
+
+// 检查分支是否远程共享（sop-flow-2，multi-repo-support-design v1.0 §4.3）。
+// 通过 git branch -vv 检测 [origin/...] tracking + ahead/behind。
+// P3 #3：有 upstream tracking 即视为共享分支（ahead/behind 非 0 是充分非必要条件——
+// 已同步分支就地实施后也会变 ahead 污染共享分支），须建 worktree/新分支，而非就地实施。
+function checkSharedBranch(repoDir) {
+  const opts = { encoding: 'utf-8', cwd: repoDir, stdio: ['ignore', 'pipe', 'pipe'] };
+  let branch;
+  try {
+    branch = (execFileSync('git', ['branch', '--show-current'], opts) || '').trim();
+  } catch {
+    return { shared: false };
+  }
+  if (!branch) return { shared: false };
+  try {
+    const vv = execFileSync('git', ['branch', '-vv'], opts).toString();
+    // P3 评审 #5：当前分支行以 '*' 开头，避免子串误命中名称含当前分支名的其他分支（如 feature/x vs feature/x2）
+    const line = vv.split('\n').find((l) => l.startsWith('*') && l.includes(branch));
+    if (!line) return { shared: false };
+    const tracking = line.match(/\[([^\]]+)\]/);
+    if (!tracking) return { shared: false };
+    const ahead = line.match(/ahead (\d+)/)?.[1];
+    const behind = line.match(/behind (\d+)/)?.[1];
+    return {
+      shared: true,
+      upstream: tracking[1],
+      ahead: parseInt(ahead || '0', 10),
+      behind: parseInt(behind || '0', 10),
+    };
+  } catch {
+    return { shared: false };
+  }
+}
+
 // 枚举 root 下含 .git 的直接子目录（= 代码仓库），按目录名排序保证确定性。
 // .git 可能是目录（普通仓库）或文件（worktree/submodule 链接），existsSync 均覆盖。
 function listCodeRepos(root) {
@@ -128,8 +175,34 @@ function runMultiRepo(root, repos) {
       continue;
     }
 
-    // 该仓库已不在受保护分支 → 已隔离，无需建 worktree（沿用单仓库 already-isolated 语义）。
+    // 该仓库已不在受保护分支 → 判断是否远程共享分支（sop-flow-2，v1.0 §4.3）：
+    // 共享分支（upstream tracking + ahead/behind 非 0）应视为"非隔离"——就地实施会污染共享分支，
+    // 须建独立 worktree/新分支。纯本地分支或无 tracking → 已隔离。
     if (!PROTECTED.includes(branch)) {
+      const shareInfo = checkSharedBranch(repoDir);
+      // P3 评审 #3：有 upstream tracking 即视为共享分支（ahead/behind 非 0 是充分非必要条件——
+      // 已同步分支就地实施后也会变 ahead 污染共享分支）
+      const sharedRisk = shareInfo.shared;
+      if (sharedRisk) {
+        const uncommitted = checkUncommitted(repoDir);
+        console.error(
+          `ensure-branch: [${repo}] on SHARED branch '${branch}' (upstream ${shareInfo.upstream}, `
+          + `ahead ${shareInfo.ahead}/behind ${shareInfo.behind}) — NOT isolated; creating worktree to avoid polluting the shared branch...`
+          + (uncommitted.count > 0 ? ` (${uncommitted.count} uncommitted change(s) not carried into worktree — verify ownership before discarding)` : '')
+        );
+        try {
+          execFileSync('git', ['worktree', 'add', wtPath, '-b', branchBase], { ...repoOpts, stdio: 'inherit' });
+          console.log(`ensure-branch: [${repo}] created worktree at ${wtPath} on branch '${branchBase}'.`);
+        } catch (e) {
+          console.error(`ensure-branch: [${repo}] worktree creation failed: ${(e.stderr || e.stdout || e.message || 'unknown').toString().trim()}`);
+          failed.push(repo);
+        }
+        continue;
+      }
+      const uncommitted = checkUncommitted(repoDir);
+      if (uncommitted.count > 0) {
+        console.warn(`ensure-branch: [${repo}] has ${uncommitted.count} uncommitted change(s); verify they belong to the current change.`);
+      }
       console.log(`ensure-branch: [${repo}] already isolated on branch '${branch}'.`);
       continue;
     }
@@ -173,11 +246,28 @@ function runSingleRepo() {
   }
 
   if (!PROTECTED.includes(branch)) {
-    console.log(`ensure-branch: already isolated on branch '${branch}'. Proceed with implementation edits.`);
-    process.exit(0);
+    const shareInfo = checkSharedBranch(changeDir);
+    // P3 评审 #3：有 upstream tracking 即视为共享分支
+    const sharedRisk = shareInfo.shared;
+    if (sharedRisk) {
+      const uncommitted = checkUncommitted(changeDir);
+      console.error(
+        `ensure-branch: on SHARED branch '${branch}' (upstream ${shareInfo.upstream}, `
+        + `ahead ${shareInfo.ahead}/behind ${shareInfo.behind}) — NOT isolated; creating worktree to avoid polluting the shared branch...`
+        + (uncommitted.count > 0 ? ` (${uncommitted.count} uncommitted change(s) not carried into worktree — verify ownership before discarding)` : '')
+      );
+      // fall through 到下方 worktree 创建逻辑（不 exit(0)）
+    } else {
+      const uncommitted = checkUncommitted(changeDir);
+      if (uncommitted.count > 0) {
+        console.warn(`ensure-branch: ${uncommitted.count} uncommitted change(s); verify they belong to the current change.`);
+      }
+      console.log(`ensure-branch: already isolated on branch '${branch}'. Proceed with implementation edits.`);
+      process.exit(0);
+    }
   }
 
-  console.error(`ensure-branch: on protected branch '${branch}'. Creating an isolated implementation context...`);
+  console.error(`ensure-branch: on ${PROTECTED.includes(branch) ? 'protected' : 'shared non-protected'} branch '${branch}'. Creating an isolated implementation context...`);
 
   const repoName = basename(changeDir) || 'repo';
   const name = sanitizeBranchName(changeName || repoName);

package/scripts/lib/cmd-repo-layout.mjs

@@ -0,0 +1,51 @@
+#!/usr/bin/env node
+/**
+ * repo-layout — 项目布局检测 CLI（multi-repo-support-design v1.0 §3）
+ *
+ * 用法：tf repo-layout detect <root> [--json]
+ * 判定项目布局（single / monorepo / multi-repo）+ 代码仓库清单，写 team-flow.config.json 的 repo_layout 段。
+ * 由 workflow-start DP-0 / orchestrator S1 项目模式确认调用；detect/review/isolate 按模式路由。
+ */
+
+import { resolve } from 'node:path';
+import { existsSync } from 'node:fs';
+import { detectRepoLayout, writeRepoLayoutConfig } from './conventions-generator.mjs';
+
+export async function run(args) {
+  const positionals = args.filter(a => !a.startsWith('--'));
+  const json = args.includes('--json');
+  const subcommand = positionals[0];
+  const root = positionals[1];
+
+  if (subcommand !== 'detect' || !root) {
+    console.error('Usage: tf repo-layout detect <root> [--json]');
+    process.exit(2);
+  }
+
+  const rootPath = resolve(root);
+  if (!existsSync(rootPath)) {
+    console.error(`❌ 项目根不存在: ${rootPath}`);
+    process.exit(1);
+  }
+  const repoLayout = detectRepoLayout(rootPath);
+  writeRepoLayoutConfig(rootPath, repoLayout);
+
+  if (json) {
+    console.log(JSON.stringify({ ok: true, ...repoLayout }));
+  } else {
+    const repoCount = Object.keys(repoLayout.repos).length;
+    console.log(`✅ repo_layout: ${repoLayout.mode}（${repoCount} 个代码仓库）`);
+    if (repoCount > 0) {
+      console.log(`   仓库清单: ${Object.keys(repoLayout.repos).join(', ')}`);
+    }
+    console.log(`   config 已写 ${rootPath}/.team-flow/team-flow.config.json`);
+  }
+}
+
+// 直接运行
+if (import.meta.url === `file://${process.argv[1]}`) {
+  run(process.argv.slice(2)).catch(err => {
+    console.error(err);
+    process.exit(1);
+  });
+}

package/scripts/lib/config-loader.mjs

@@ -1,10 +1,11 @@
 // Config loader for team-flow
 // Loads team-flow.config.json and merges with built-in defaults.
-// Lookup order: (1) projectRoot, (2) git root, (3) home directory.
+// Lookup order: (1) projectRoot, (2) git root, (3) workspace root, (4) home directory.
 
 import { readFileSync, existsSync } from 'node:fs';
 import { join } from 'node:path';
 import { execFileSync } from 'node:child_process';
+import { detectWorkspaceRoot } from './git-utils.mjs';
 
 const DEFAULTS = {
   artifacts: {
@@ -35,6 +36,12 @@ const DEFAULTS = {
     version: null,
     delegation_mode: 'auto',
   },
+  repo_layout: {
+    // 项目布局（multi-repo-support-design v1.0 §3）
+    // 项目模式确认（DP-0 / orchestrator S1）时写入；detect/review/isolate 按模式路由
+    mode: null,
+    repos: {},
+  },
 };
 
 export const MODEL_PROFILES = Object.freeze([
@@ -106,6 +113,15 @@ function findConfigFile(startDir) {
     // Not a git repo — skip
   }
 
+  // 3.5 multi-repo-support-design v1.0（P3 评审 #2 修复）：change 目录 → 工作区根（changes/ 父目录）的 .team-flow/。
+  // 根非 git 仓库的 multi-repo 下，detect 写项目根 config 后，change 目录 loadConfig 需经此读到（findConfigFile
+  // 三级查找（changeDir→git root→home）不覆盖非 git 根的项目根 .team-flow/）。
+  const workspaceRoot = detectWorkspaceRoot(startDir);
+  if (workspaceRoot && workspaceRoot !== startDir) {
+    const wsTeamFlowDir = join(workspaceRoot, '.team-flow', 'team-flow.config.json');
+    if (existsSync(wsTeamFlowDir)) return wsTeamFlowDir;
+  }
+
   // 4. Check home directory
   const homePath = join(process.env.HOME || '', 'team-flow.config.json');
   if (existsSync(homePath)) return homePath;

package/scripts/lib/conventions-generator.mjs

@@ -59,10 +59,13 @@ export function detectGlaf4DevPlugin(pluginsFilePath = PLUGINS_INSTALLED_PATH) {
  * @returns {{ is_glaf4_java: boolean, glaf4_dev_available: boolean, glaf4_dev_version: string|null, delegation_mode: 'auto'|'manual'|'off' }}
  */
 export function detectGlaf4Delegation(root, options = {}) {
-  const techStack = detectTechStack(root);
   // is_glaf4_java = Java 技术栈命中（pom.xml/build.gradle 存在即可，v2.1 §4）
   // glaf4-dev 只处理 Java，Spring/JUnit 细分由 contract-builder 已有检测负责
-  const isGlaf4Java = techStack.language === 'java';
+  // multi-repo-support-design v1.0 §4.1：多仓库下按 repos 清单聚合判定——任一仓库 Java → 项目级 true
+  const repos = Array.isArray(options.repos) ? options.repos : null;
+  const isGlaf4Java = repos && repos.length > 0
+    ? repos.some(r => detectTechStack(r).language === 'java')
+    : detectTechStack(root).language === 'java';
   const plugin = detectGlaf4DevPlugin(options.pluginsFilePath);
   const mode = options.delegationMode || 'auto';
   return {
@@ -104,6 +107,62 @@ export function writeGlaf4DevConfig(root, glaf4DevInfo) {
   writeFileSync(configPath, JSON.stringify(config, null, 2), 'utf-8');
 }
 
+// ── repo_layout 检测（multi-repo-support-design v1.0 §3，2026-08-21）─────────────
+
+// 非代码仓库目录（team-flow 产物/基础设施），扫描时排除
+const NON_REPO_DIRS = new Set([
+  'changes', '.team-flow', 'docs', 'doc', 'node_modules', '.worktrees',
+  'requirement', 'prototype', 'specs', 'data', 'path', 'template',
+]);
+
+/**
+ * 识别项目布局（single / monorepo / multi-repo，v1.0 §3.1）
+ * @param {string} root 项目根目录
+ * @returns {{ mode: 'single'|'monorepo'|'multi-repo', repos: Record<string,string> }}
+ */
+export function detectRepoLayout(root) {
+  // 1. 根直接含技术栈特征（pom.xml/package.json/build.gradle）→ single 或 monorepo（Maven 聚合/多子模块）
+  if (existsSync(join(root, 'pom.xml')) || existsSync(join(root, 'package.json')) || existsSync(join(root, 'build.gradle'))) {
+    // P3 评审 #6：子模块排除 NON_REPO_DIRS（changes/docs/data 等含 package.json 会被 scanSubProjects 误计为模块 → 误判 monorepo）
+    const subModules = scanSubProjects(root).filter(m => !NON_REPO_DIRS.has(m.name));
+    const repos = {};
+    for (const m of subModules) repos[m.name] = m.path;
+    return { mode: subModules.length > 0 ? 'monorepo' : 'single', repos };
+  }
+  // 2. 根无技术栈特征 → 扫描子目录识别独立代码仓库（含 .git 或有技术栈语言）
+  const repos = {};
+  const entries = readdirSync(root, { withFileTypes: true });
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    if (entry.name.startsWith('.') || NON_REPO_DIRS.has(entry.name)) continue;
+    const sub = join(root, entry.name);
+    const hasGit = existsSync(join(sub, '.git'));
+    const tech = detectTechStack(sub);
+    if (hasGit || tech.language) {
+      repos[entry.name] = sub;
+    }
+  }
+  const repoCount = Object.keys(repos).length;
+  return { mode: repoCount >= 2 ? 'multi-repo' : 'single', repos };
+}
+
+/**
+ * 写 repo_layout 段到 team-flow.config.json（v1.0 §3.2）
+ * @param {string} root 项目根
+ * @param {{ mode: 'single'|'monorepo'|'multi-repo', repos: Record<string,string> }} repoLayout
+ */
+export function writeRepoLayoutConfig(root, repoLayout) {
+  const teamFlowDir = join(root, '.team-flow');
+  const configPath = join(teamFlowDir, 'team-flow.config.json');
+  mkdirSync(teamFlowDir, { recursive: true });
+  let config = {};
+  if (existsSync(configPath)) {
+    try { config = JSON.parse(readFileSync(configPath, 'utf-8')); } catch { config = {}; }
+  }
+  config.repo_layout = repoLayout;
+  writeFileSync(configPath, JSON.stringify(config, null, 2), 'utf-8');
+}
+
 // ── 常量 ─────────────────────────────────────────────────────────────────────
 
 const TEMPLATE_DIR = join(import.meta.dirname, '../../templates/conventions');

package/scripts/lib/execution-plan.mjs

@@ -271,12 +271,12 @@ function getPhysicalReviewsDirectory(changeDir) {
   let directory = changeRoot;
   for (const component of ['.superpowers', 'sdd', 'reviews']) {
     directory = join(directory, component);
-    let metadata;
-    try {
-      metadata = lstatSync(directory);
-    } catch (error) {
-      throw new Error(`Review report evidence cannot read the ${component} overlay directory: ${error.message}`);
+    // multi-repo-support v1.0 §4.2（cli-command-2 修复）：overlay 目录自动创建，修 ENOENT
+    // （首次 review 时 .superpowers/sdd/reviews/ 尚不存在，recordReview 写入前先建）
+    if (!existsSync(directory)) {
+      mkdirSync(directory, { recursive: true });
     }
+    const metadata = lstatSync(directory);
     if (metadata.isSymbolicLink() || !metadata.isDirectory()) {
       throw new Error('Review report evidence requires physical .superpowers/sdd/reviews overlay directories');
     }
@@ -312,8 +312,11 @@ function validateReviewRange(changeDir, base, head, repoPath) {
   // This happens either through automatic fallback (subRepoPath set above)
   // or through explicit --repo pointing to a different repository.
   if (!subRepoPath && repoPath) {
-    const defaultRoot = resolveGitRoot(changeDir);
-    if (gitRoot !== defaultRoot) subRepoPath = gitRoot;
+    // multi-repo-support v1.0 §4.2（cli-command-2 修复）：--repo 场景下 change 目录可能无 git
+    //（多仓库 changes/ 未版本化），defaultRoot 比较容错返回 null，不因 change 目录无 git 报错
+    let defaultRoot = null;
+    try { defaultRoot = resolveGitRoot(changeDir); } catch {}
+    if (defaultRoot && gitRoot !== defaultRoot) subRepoPath = gitRoot;
   }
 
   const effectiveRoot = subRepoPath || gitRoot;

package/scripts/lib/glaf4-delegation.mjs

@@ -3,8 +3,10 @@
  * glaf4-delegation — GLAF4 委托协议 CLI（v2.1 §6.6/§6.3/§6.7，P2 实施委托全链路）
  *
  * 用法：
- *   tf glaf4-delegation detect <root> [--delegation-mode <mode>] [--json]
- *       运行时探测（v2.1 §4 接口①，C1 修复接线）：三态检测 + 写 .team-flow/team-flow.config.json 的 glaf4_dev 段。
+ *   tf glaf4-delegation detect <root> [--delegation-mode <mode>] [--target-repo <模块路径>] [--json]
+ *       运行时探测（v2.1 §4 接口①，C1 修复接线 + multi-repo-support v1.0 §4.1）：
+ *       root 解析（change 目录→项目根）+ 写 .team-flow/team-flow.config.json 的 glaf4_dev 段（项目根）。
+ *       multi-repo 下按 repo_layout 清单聚合判定 is_glaf4_java；--target-repo 精确探测指定模块。
  *       contract-builder 产出 execution-contract 时（DP-4 前）显式调用此命令，recommend 才能读到 glaf4_dev。
  *   tf glaf4-delegation confirm <change-dir> --mode <mode> --write-set <json> [--json]
  *       DP-4 委托方案确认：mode 枚举标量入 state，write_set_boundary 落 .superpowers/glaf4/write-set.json，
@@ -28,7 +30,9 @@ import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync
 import { join, isAbsolute, relative, resolve, normalize, sep } from 'node:path';
 import { readState, writeState } from './state-loader.mjs';
 import { getOverlayPaths } from './sdd-overlay.mjs';
-import { detectGlaf4Delegation, writeGlaf4DevConfig } from './conventions-generator.mjs';
+import { detectGlaf4Delegation, detectTechStack, writeGlaf4DevConfig } from './conventions-generator.mjs';
+import { detectWorkspaceRoot, getGitRoot } from './git-utils.mjs';
+import { loadConfig } from './config-loader.mjs';
 
 // DP-4 委托模式合法枚举（对应 glaf4-dev 七模式中可委托 change 的六种）
 export const GLAF4_DELEGATION_MODES = [
@@ -72,26 +76,42 @@ export function hashWriteSet(writeSet) {
  * @param {string} [delegationMode] 覆盖 delegation_mode（auto/manual/off）
  * @returns {object} { ok, is_glaf4_java, glaf4_dev_available, glaf4_dev_version, delegation_mode, configPath }
  */
-export function detectAndWriteConfig(root, delegationMode) {
-  const detection = detectGlaf4Delegation(root, { delegationMode });
+export function detectAndWriteConfig(root, delegationMode, targetRepo) {
+  // multi-repo-support-design v1.0 §4.1（cli-command-1 修复）：root 解析——change 目录（含 changes/）→ 项目根；否则 git 根
+  const projectRoot = resolveProjectRoot(root);
+
+  // 读 repo_layout（config 已固化时）
+  const config = loadConfig(projectRoot);
+  const repoLayout = config?.repo_layout || null;
+
+  // 探测目标构造（P3 自查补全 + P4 validator W1 放宽，2026-08-21）：
+  //   --target-repo 精确 > repo_layout 清单聚合（repos 非空即聚合，不限 multi-repo——
+  //   壳仓库含 package.json 误判 monorepo 时也应聚合，否则 cli-command-1 在真实项目失效）>
+  //   root 有技术栈（探测 root，如 detect(svcA)）>
+  //   root 无技术栈（change 文档目录/容器根）→ 探测解析后项目根（单仓库项目根有 pom.xml）
+  let repos = null;
+  let probeRoot = root;
+  if (targetRepo) {
+    probeRoot = targetRepo;
+  } else if (repoLayout?.repos && Object.keys(repoLayout.repos).length > 0) {
+    repos = Object.values(repoLayout.repos);
+  } else if (!detectTechStack(root).language) {
+    probeRoot = projectRoot;
+  }
+  const detection = detectGlaf4Delegation(probeRoot, { delegationMode, repos });
 
-  // 复评 C1 嵌套工程根盲区（2026-08-18）：git root ≠ target_root（monorepo 布局）时，
-  // loadConfig(changeDir) 只查 changeDir→git root→home，不查 target_root → 委托链静默断裂。
-  // 写 git root 冗余副本保证从任意 changeDir 都能读到探测结果。gitRoot 提前解析供 mode 优先级使用。
+  // git root（冗余副本判断 + mode 优先级）
   let gitRoot = null;
   try {
-    gitRoot = execFileSync('git', ['rev-parse', '--show-toplevel'], {
-      cwd: root, encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'],
-    }).trim();
+    gitRoot = getGitRoot(projectRoot);
   } catch {
     // 非 git 仓库，跳过
   }
 
-  // 第四轮复评 Important（2026-08-18）：delegation_mode 优先级链补全——显式 > 目标 root 已有 > git root 已有 > auto。
-  // 上轮只查目标 root，非 Java 服务无本地 config → 默认 auto → 覆盖 git root 副本的 off（用户 off 意图被静默翻转）。
+  // delegation_mode 优先级链：显式 > 目标 root 已有 > git root 已有 > auto
   let effectiveMode = delegationMode;
   if (!effectiveMode) {
-    effectiveMode = readGlaf4DelegationMode(root)
+    effectiveMode = readGlaf4DelegationMode(projectRoot)
       || (gitRoot ? readGlaf4DelegationMode(gitRoot) : null)
       || 'auto';
   }
@@ -100,16 +120,17 @@ export function detectAndWriteConfig(root, delegationMode) {
     version: detection.glaf4_dev_version,
     delegationMode: effectiveMode,
   };
-  writeGlaf4DevConfig(root, info);
+  // config 主副本写项目根（cli-command-1 修复：不再写 change 目录）
+  // multi-repo-support v1.0：OR 聚合保留已有 enabled=true——项目级 GLAF4 能力一旦声明，
+  // 不因后续非 Java 目标探测而覆盖丢失（非 Java change detect 不应禁用项目委托）
+  const existingProjEnabled = readGitRootGlaf4Enabled(projectRoot);
+  const projEnabled = info.enabled || existingProjEnabled;
+  writeGlaf4DevConfig(projectRoot, { ...info, enabled: projEnabled, delegationMode: effectiveMode });
 
   let gitRootConfig = null;
-  if (gitRoot && gitRoot !== root) {
-    // 第三轮复评 Important①（2026-08-18）：多服务混合 monorepo 下 git root 副本 last-write-wins 污染——
-    // 非 Java 服务 detect 会把 Java 服务的 enabled=true 覆盖成 false。改为 OR 聚合：
-    // 项目级能力一旦声明（任一服务 enabled=true），不因后续非 Java 服务探测而丢失。
+  if (gitRoot && gitRoot !== projectRoot) {
     const existingEnabled = readGitRootGlaf4Enabled(gitRoot);
     const aggregatedEnabled = info.enabled || existingEnabled;
-    // 第四轮复评：git root 副本 mode 保留已有值（显式传参才覆盖）——用户 off 意图不因新探测静默翻转。
     const gitRootMode = readGlaf4DelegationMode(gitRoot);
     const gitRootEffectiveMode = delegationMode || gitRootMode || effectiveMode;
     writeGlaf4DevConfig(gitRoot, { ...info, enabled: aggregatedEnabled, delegationMode: gitRootEffectiveMode });
@@ -119,11 +140,27 @@ export function detectAndWriteConfig(root, delegationMode) {
   return {
     ok: true,
     ...detection,
-    configPath: join(root, '.team-flow', 'team-flow.config.json'),
+    configPath: join(projectRoot, '.team-flow', 'team-flow.config.json'),
     gitRootConfig,
+    projectRoot,
   };
 }
 
+/**
+ * root 解析（multi-repo-support-design v1.0 §4.1）：change 目录（含 changes/）→ 项目根；否则 git 根；兜底直接用 root
+ * @param {string} root
+ * @returns {string}
+ */
+function resolveProjectRoot(root) {
+  const ws = detectWorkspaceRoot(root);
+  if (ws) return ws;
+  try {
+    return getGitRoot(root);
+  } catch {
+    return root;
+  }
+}
+
 /**
  * 读 git root 现有 config 的 glaf4_dev.enabled（第三轮复评 Important① OR 聚合用）
  * @param {string} gitRoot
@@ -394,7 +431,7 @@ export function resetDelegation(changeDir) {
 
 export async function run(args) {
   const positionals = args.filter(a => !a.startsWith('--'));
-  const flags = new Set(args.filter(a => a.startsWith('--') && a !== '--mode' && a !== '--write-set' && a !== '--run-dir' && a !== '--target-root' && a !== '--json'));
+  const flags = new Set(args.filter(a => a.startsWith('--') && a !== '--mode' && a !== '--write-set' && a !== '--run-dir' && a !== '--target-root' && a !== '--target-repo' && a !== '--delegation-mode' && a !== '--json'));
   const opt = (name) => {
     const i = args.indexOf(`--${name}`);
     return i >= 0 ? args[i + 1] : undefined;
@@ -404,7 +441,7 @@ export async function run(args) {
   const json = flags.has('--json') || args.includes('--json');
 
   const usage = `Usage:
-  tf glaf4-delegation detect <root> [--delegation-mode <auto|manual|off>]
+  tf glaf4-delegation detect <root> [--delegation-mode <auto|manual|off>] [--target-repo <模块路径>]
   tf glaf4-delegation confirm <change-dir> --mode <mode> --write-set <json-file>
   tf glaf4-delegation verify-write-set <change-dir> --run-dir <run-dir>
   tf glaf4-delegation verify-tasks <change-dir>
@@ -424,15 +461,16 @@ export async function run(args) {
   try {
     if (subcommand === 'detect') {
       const mode = opt('delegation-mode');
+      const targetRepo = opt('target-repo');
       // 第四轮复评 Minor-1（2026-08-18）：枚举校验——非法值（如 'foo'）等同 auto 放行会让用户配置失真
       if (mode !== undefined && !['auto', 'manual', 'off'].includes(mode)) {
         console.error(`--delegation-mode 必须为 auto/manual/off 之一（实际: ${mode}）`);
         process.exit(2);
       }
-      const result = detectAndWriteConfig(changeDir, mode);
+      const result = detectAndWriteConfig(changeDir, mode, targetRepo);
       const msg = result.glaf4_dev_available
-        ? `探测: is_glaf4_java=${result.is_glaf4_java}, glaf4-dev v${result.glaf4_dev_version} 可用, delegation_mode=${result.delegation_mode} → config 已写 ${result.configPath}`
-        : `探测: is_glaf4_java=${result.is_glaf4_java}, glaf4-dev 不可用 → config 已写 ${result.configPath}`;
+        ? `探测: is_glaf4_java=${result.is_glaf4_java}, glaf4-dev v${result.glaf4_dev_version} 可用, delegation_mode=${result.delegation_mode} → config 已写 ${result.configPath}${result.projectRoot ? `（项目根 ${result.projectRoot}）` : ''}`
+        : `探测: is_glaf4_java=${result.is_glaf4_java}, glaf4-dev 不可用 → config 已写 ${result.configPath}${result.projectRoot ? `（项目根 ${result.projectRoot}）` : ''}`;
       print(result.ok, result, msg);
     } else if (subcommand === 'confirm') {
       const mode = opt('mode');

package/scripts/team-flow.mjs

@@ -42,6 +42,7 @@ const COMMANDS = {
   'test-matrix-export': () => import('./lib/test-matrix-export.mjs'),
   'glaf4-evidence-export': () => import('./lib/glaf4-evidence-export.mjs'),
   'glaf4-delegation': () => import('./lib/glaf4-delegation.mjs'),
+  'repo-layout': () => import('./lib/cmd-repo-layout.mjs'),
   test:                () => import('./lib/test-record.mjs'),
 };
 
@@ -76,6 +77,8 @@ Commands:
                         Aggregate glaf4-dev run PASS evidence → surefire line (v2.1 §7; feed test record --from)
   glaf4-delegation <sub> <dir> [--mode <m> --write-set <json> | --run-dir <run> | --delegation-mode <mode>]
                         GLAF4 委托协议 (v2.1 §4/6.3/6.6/6.7): detect / confirm / verify-write-set / verify-tasks / record-partial / reset
+  repo-layout detect <root>
+                        Detect project layout (single/monorepo/multi-repo) + code repos, write repo_layout config (v1.0 §3)
   test record <dir> --from <runner-output> [--runner auto|maven-surefire|jest|pytest]
                         Record programmatic test evidence (v0.13 §50; feeds tests-passing gate)
   config [options]      Display or modify configuration

package/skills/contract-builder/references/glaf4-delegation.md

@@ -9,17 +9,19 @@
 contract-builder 产出 execution-contract 时（DP-4 前）实时探测——**显式运行 CLI 命令**（第三轮复评接线统一：探测必须写 config，纯库函数不落盘）：
 
 ```bash
-tf glaf4-delegation detect <target_root> [--delegation-mode <auto|manual|off>]
+tf glaf4-delegation detect <target_root> [--delegation-mode <auto|manual|off>] [--target-repo <模块路径>]
 ```
 
+**target_root 语义（multi-repo-support-design v1.0 §4.1，cli-command-1 修复）**：传入**项目根或 change 目录均可**——detect 自动解析：change 目录（含 `changes/`）→ 项目根，config 主副本写**项目根** `.team-flow/team-flow.config.json`（不写 change 目录）。**多仓库项目（`repo_layout: multi-repo`）推荐传 `--target-repo <模块路径>`**（如 change 涉及 `batch-fytx-msg`），或依赖自动扫描：按 `repo_layout.repos` 清单聚合判定——任一代码仓库是 Java → 项目级 `is_glaf4_java=true`。
+
 `detect` 内部调用 `conventions-generator.mjs` 的 `detectGlaf4Delegation(root)` 解析 `~/.claude/plugins/installed_plugins.json`（glaf4-dev 条目含 installPath + version），产出三态：
 
-- `is_glaf4_java`（技术栈命中：pom.xml/build.gradle + Spring Boot/JUnit5/Mockito）
+- `is_glaf4_java`（技术栈命中：pom.xml/build.gradle + Spring Boot/JUnit5/Mockito；**多仓库下按 repos 清单聚合，任一仓库 Java → true**）
 - `glaf4_dev_available`（插件可用，含 version）
 - `delegation_mode`（auto/manual/off，用户可开关）
 
-探测结果写 `team-flow.config.json` 的 `glaf4_dev: {enabled, version, delegation_mode}` 段
-（git root ≠ target_root 时写 git root 冗余副本，monorepo 下多服务 OR 聚合；未传 `--delegation-mode` 保留已有值）。
+探测结果写 `<项目根>/.team-flow/team-flow.config.json` 的 `glaf4_dev: {enabled, version, delegation_mode}` 段
+（git root ≠ target_root 时写 git root 冗余副本；未传 `--delegation-mode` 保留已有值）。
 
 **判定**：`is_glaf4_java && glaf4_dev_available && delegation_mode !== 'off'` → 产出 GLAF4 Delegation 段。
 **依赖**：`recommendExecutionModesForChange` 读 `config.glaf4_dev.enabled` 决定是否注入 glaf4-delegation——**必须**先跑 detect 写 config，否则委托链不可达。

package/skills/workflow-orchestrator/SKILL.md

@@ -42,6 +42,13 @@ Do NOT invoke for:
 **conventions 注入（v0.11 §33）**：
 - 读取 conventions 配置，注入为需求分析上下文
 
+**项目模式确认（multi-repo-support-design v1.0 §3.3，2026-08-21）**：S1 路由时确认项目布局，写 config 供 detect/review/isolate 按模式路由——
+1. 定位项目根（`detectWorkspaceRoot` / `getGitRoot`）；`<项目根>/.team-flow/team-flow.config.json` 已有 `repo_layout` 段 → 直接读取（已固化跳过）
+2. 否则运行 `tf repo-layout detect <项目根>`：判定 `single`/`monorepo`/`multi-repo` + 代码仓库清单，写 `<项目根>/.team-flow/team-flow.config.json` 的 `repo_layout` 段
+3. 多仓库项目向用户展示判定结果（AskUserQuestion 确认）；单仓库自动；修正 repos 清单编辑 config 的 `repo_layout.repos`
+4. 影响：detect（按仓库清单探测 GLAF4）/ review（`--repo` 放宽 git 约束）/ isolate（共享分支检测）
+5. 边界：本步骤识别存量结构；全新项目骨架引导归 workflow-bootstrap B1.5
+
 ### S2: PRD + 原型阶段
 
 **⛔ MANDATORY：执行S2阶段前，必须先读取 `references/s2-prd-prototype-loop.md`**

package/skills/workflow-start/SKILL.md

@@ -34,6 +34,16 @@ Run DP-0 when: change folder doesn't exist, planning artifacts missing/empty, or
 
 若 `change-brief.md` 存在且 `upstream_source == orchestrator`（本 change 由 orchestrator S4 分发），**继承** brief 的 scope/约束/AC 为默认值，DP-0 从"从零问"改为"一次确认继承或修正"，**不**重新问"你想做什么"。否则（手动新建 / hotfix / 单 change 快速通道 / 存量 change 无 brief）照常 DP-0。**主信号 = brief 文件存在**（非 yaml 字段——可天然排除无 brief 的快速通道，且对存量手动 change 零误伤）；双源冲突以 `requirement/vN/plan.md` 为准并触发 Brief drift（见「Staleness Detection」）。完整判定伪代码与主信号理由见 `references/routing-rules.md`「DP-0」。
 
+### 项目模式确认（multi-repo-support-design v1.0 §3.3，2026-08-21）
+
+DP-0 时确认项目布局（`single`/`monorepo`/`multi-repo`），写 config 供 detect/review/isolate 按模式路由：
+1. **定位项目根**：`detectWorkspaceRoot(changeDir)`（change 目录 → `changes/` 父目录）；非标准布局回退 `getGitRoot`
+2. **已固化跳过**：`<项目根>/.team-flow/team-flow.config.json` 已有 `repo_layout` 段 → 直接读取，跳过 3-4
+3. **运行 `tf repo-layout detect <项目根>`**：判定 `single`/`monorepo`/`multi-repo` + 代码仓库清单，写 `<项目根>/.team-flow/team-flow.config.json` 的 `repo_layout` 段
+4. **多仓库项目首次确认**：向用户展示判定结果（`multi-repo + N 个代码仓库`），AskUserQuestion 确认；单仓库自动。**修正 repos 清单**：确认后编辑 `<项目根>/.team-flow/team-flow.config.json` 的 `repo_layout.repos`（缺省接受检测结果）
+5. **与 workflow-bootstrap 边界**：本步骤识别**存量结构**（single/monorepo/multi-repo 探测 + repos 清单）；全新项目骨架引导（生成 pom.xml/package.json）归 workflow-bootstrap B1.5
+6. 判定结果影响：detect（按仓库清单探测 GLAF4）/ review（`--repo` 放宽 git 约束）/ isolate（共享分支检测）
+
 Ask (manual path): change name + one-sentence intent, known constraints, related optimizations (include or stay focused?), communication preference (ask per decision or draft for review).
 
 After confirmation: