@xulthekl/team-flow 0.47.0 → 0.49.0

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

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

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "team-flow",
-  "version": "0.47.0",
+  "version": "0.49.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.49.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.49.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.49.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.49.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.49.0",
       "source": ".",
       "author": {
         "name": "LT",

package/AGENTS.md

@@ -112,8 +112,8 @@ docs/
       ├── INDEX.md     # L1 轻量索引（≤150行，每条一行摘要+标签）
       ├── requirement/ plan/ architecture/ prototype/ spec/ build/ review/ cross-phase/  # L2 分阶段目录（v0.36.0 加 architecture）
       └── <file>.md    # L3 经验文件（YAML frontmatter: phase/domain/type/severity）
-changes/<name>/        变更脚手架（S4 创建）：.team-flow.yaml（变更级状态文件）/ change-brief.md（产品级交接物，含 upstream_arch_ref）/ architecture/（变更级三件套 + sql/）
-specs/<cap>/            每变更设计/任务/契约：spec.md / design.md / tasks.md / execution-contract.md / learnings.md（v0.9 起 architecture/ 三件套已迁至 changes/<name>/architecture/）
+changes/<name>/        变更脚手架（S4 创建）：.team-flow.yaml（变更级状态文件）/ change-brief.md（产品级交接物，含 upstream_arch_ref）/ proposal.md / design.md / tasks.md / execution-contract.md / learnings.md（变更级经验台账）/ architecture/（变更级三件套 + sql/）
+specs/<cap>/            每变更规格：spec.md（v0.49.0 §83.3.5：learnings.md 归 change 根，不在此目录）
 STRATEGY.md CONCEPTS.md 产品策略(BA) / 领域词汇
 ```
 

package/CHANGELOG.md

@@ -4,6 +4,60 @@ All notable changes to `team-flow` will be documented in this file.
 
 The format loosely follows Keep a Changelog.
 
+## [0.49.0] - 2026-09-09
+
+### Fixed（execution plan 冻结边界与复利链路修复）
+
+设计来源：`docs/architecture-api-db-design-enhancement-v0.21.md` §83（2026-09-09，fytx-gateway-parent 4 条 workflow-feedback：093305 / 093306 / 093307 / 093308）
+
+**根因簇 A — execution plan 冻结边界错配**（3 个落点，构成闭合不可用回路）
+
+- **A1 hash 范围修正**：`normalizeCheckboxes` 归一化 tasks.md 勾选状态后再入 `artifacts_hash` / `computeTaskHash` —— 勾选是执行进度而非规划内容。修复「勾选 → plan 过期 → recordReview 抛错 → build-executor 无法勾选 → closing 死锁」（`hash.mjs`、`sdd-overlay.mjs`）
+- **A2 receipt 判据改 wave 定义指纹**：`recordReview` 写 `wave_fingerprint`（id/strategy/tasks/depends_on），`readCurrentReview` 以其为判据，`plan_hash`/`plan_revision` 降级为审计信息（存量 receipt 回退旧判据）。修复 revise / refresh-hash 后历史 receipt 全部失效且无补录路径；`describeWaves` 新增 `stale_receipt` 诊断（`execution-plan.mjs`）
+- **A3 refresh-hash 同步 recommendation_receipt**：同步 receipt 的 artifacts_hash/contract_hash 并重算 receipt.hash —— 修复 refresh-hash 在其目标场景下自失败（`execution-plan.mjs`）；`stableJson`/`hashObject` 抽到 `hash.mjs` 共享
+
+**根因簇 B — 复利链路断裂**（6 个子项）
+
+- **B1 消费通道**：build-executor Required Inputs 增加 `tf solutions inject --phase cross-phase`（标注为经验提示而非约束）
+- **B2 路径统一**：5 处文档从 `specs/<cap>/learnings.md` 更正为 change 根 `learnings.md`
+- **B3 契约分层**：`schema.yaml` 声明两条产出通道（ce-compound 手工 / promote 自动晋升）与共同消费面 INDEX.md
+- **B4 静默丢弃可见化**：promote 输出「晋升 / 确认 / 跳过」汇总 + 逐条跳过原因
+- **B5 promote 实现修复**：产出文件单 frontmatter 块（原双块，并补回 `## ` 标题前缀）；重复命中真正落盘（INDEX severity 升级 + 条目 `confirmed` 计数）
+- **B6 通道错配修正**：`compound-captured` guard 提示不再指向 `tf solutions capture`（它写全局目录、不创建 learnings.md）；release-archivist 明确 learnings.md 写入方；新增 `templates/learnings.md`
+
+**根因簇 C — 解析器不对称**
+
+- **pytest junit XML 支持**：抽出通用 `parseJunitXml`（maven-surefire 与 pytest 共用）；`parsePytest` 增加 XML 分支；`detectRunner` XML 优先嗅探；错误信息附输入形态指引（`test-record.mjs`）
+
+**协议层**
+
+- build-executor wave 完成协议增加「回写 tasks.md 勾选」；workflow-start 主动串行编排把勾选作为进下一波前置；Artifact Ownership 澄清 tasks.md 勾选状态归属
+- `glaf4-delegation.md` §8 closing 时序协议同步更新
+
+**横展修复**（P3 审查发现的既有缺陷）
+
+- **CLI 入口守卫**：5 处 `process.argv[1]?.includes(...)` 改为 `import.meta.url === pathToFileURL(process.argv[1]).href` —— 原写法使测试文件（如 `solutions-capture.test.mjs`）在 import 时触发 CLI 执行，污染真实 `docs/solutions/`（`solutions-capture/inject/index-gen/promote.mjs`、`prototype-sync.mjs`）
+- **测试隔离**：`ensure-branch.test.mjs` 的 `origin.git` 从固定 `tmpdir()` 路径改为独立随机目录 —— 原写法跨运行残留导致 push 被拒、before 钩子失败、`npm test` exit 1
+- 清理 `docs/solutions/` 中 14 个历史测试污染条目
+
+### Tests
+
+- 新增 18 个用例（A1 勾选归一化、A2 指纹判据与 stale 诊断、A3 refresh-hash 同步、pytest XML、promote 可见化与落盘）；`npm test` 742/742，`npm run test:e2e` 68/68
+
+## [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.49.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.49.0**。
 
 ---
 
@@ -761,7 +761,7 @@ tf execution review changes/my-change --wave foundation --base <sha> --head <sha
 report 本身必须为普通、非空、非符号链接文件。
 
 每一个 wave 均须有当前 `pass` review receipt，才可启动依赖 wave 或进入 closing；
-修订计划会废止旧 receipt。#47 所提出的恢复、切换与手动保存 slash command 尚未实现，
+receipt 绑定该 wave 的定义（v0.49.0 起）：wave 定义未变时，修订计划或刷新 hash 不会废止它。#47 所提出的恢复、切换与手动保存 slash command 尚未实现，
 不能假定有 `/tf:*` 命令。
 
 Delta spec 的规范路径是 `specs/<capability>/spec.md`。扁平的 `specs/<capability>.md` 和根级 `specs/spec.md` 都不会被当作合法规范静默通过。

package/README.md

@@ -1,6 +1,6 @@
 # team-flow
 
-> 当前版本：`v0.47.0`
+> 当前版本：`v0.49.0`
 
 > 统一插件：**team-flow**（spec 驱动开发）+ **compound-engineering 核心子集**（全局复利）+ **architecture-design**（4A+DDD 增量设计）+ **prototype**（本地 HTML 原型）+ **e2e**（AC 驱动 E2E）+ **workflow-orchestrator**（产品级编排）+ **workflow-bootstrap**（既有项目接入）。一次安装，七套能力协同。
 
@@ -66,7 +66,7 @@ prototype/         全局原型（UI 契约真相源）
 docs/
   ├── architecture/  全局架构三层（v0.36.0）：ARCHITECTURE.md / PHYSICAL-MODEL.md / DATABASE.md / API-INDEX.md / INDEX.md / domains/<bc>.md / iterations/vN/（产品级快照）/ baseline.md
   └── solutions/     复利经验库（三层索引：INDEX.md → 分阶段目录 → 经验文件）
-specs/<cap>/        每变更设计/任务/契约 + learnings.md
+specs/<cap>/        每变更规格：spec.md（learnings.md 归 change 根目录）
 STRATEGY.md CONCEPTS.md 策略 / 领域词汇
 ```
 
@@ -155,7 +155,7 @@ tf execution review changes/my-change --wave foundation --base <sha> --head <sha
 report 本身必须为普通、非空、非符号链接文件。
 
 每一个 wave 均须有当前 `pass` review receipt，才可启动依赖 wave 或进入 closing；
-修订计划会废止旧 receipt。#47 所提出的恢复、切换与手动保存 slash command 尚未实现，
+receipt 绑定该 wave 的定义（v0.49.0 起）：wave 定义未变时，修订计划或刷新 hash 不会废止它。#47 所提出的恢复、切换与手动保存 slash command 尚未实现，
 不能假定有 `/tf:*` 命令。
 
 ## OpenAI Codex CLI 安装与升级

package/docs/README_en.md

@@ -126,7 +126,7 @@ npm install -g team-flow
 
 ### Version
 
-- Current: `v0.47.0`
+- Current: `v0.49.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,17 +2,3 @@
 <!-- 每条一行，按 severity 降序，≤150 行硬上限 -->
 | date | phase | domain | type | severity | summary | file |
 |------|-------|--------|------|----------|---------|------|
-| 2026-08-21 | cross-phase | general | insight | medium | (no summary) | cross-phase/2026-08-21-no-summary.md |
-| 2026-08-19 | cross-phase | general | insight | medium | (no summary) | cross-phase/2026-08-19-no-summary.md |
-| 2026-08-18 | cross-phase | general | insight | medium | (no summary) | cross-phase/2026-08-18-no-summary.md |
-| 2026-08-17 | cross-phase | general | insight | medium | (no summary) | cross-phase/2026-08-17-no-summary.md |
-| 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 |
-| 2026-08-03 | cross-phase | general | insight | medium | (no summary) | cross-phase/2026-08-03-no-summary.md |
-| 2026-08-01 | cross-phase | general | insight | medium | (no summary) | cross-phase/2026-08-01-no-summary.md |
-| 2026-07-31 | cross-phase | general | insight | medium | (no summary) | cross-phase/2026-07-31-no-summary.md |
-| 2026-07-30 | cross-phase | general | insight | medium | (no summary) | cross-phase/2026-07-30-no-summary.md |
-| 2026-07-29 | cross-phase | general | insight | medium | (no summary) | cross-phase/2026-07-29-no-summary.md |
-| 2026-07-28 | cross-phase | general | insight | medium | (no summary) | cross-phase/2026-07-28-no-summary.md |

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.49.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.49.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.49.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.49.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.49.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.49.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/guard/checks/compound-captured.mjs

@@ -61,10 +61,13 @@ export function checkCompoundCaptured(changeDir) {
   }
 
   // 3. 未捕获且未豁免 → fail
+  // v0.49.0 §83.3.5：修正通道错配——原提示指向 `tf solutions capture`，但该命令写的是
+  // 全局 docs/solutions/，不会创建 learnings.md（用户照做后 guard 仍 FAIL）。
   failures.push(
-    'Compound capture missing: no learnings.md found in change directory. ' +
-    'Run `tf solutions capture --phase review --domain <d> --type insight --severity medium --summary "..."` ' +
-    'to document session learnings, or `tf state set compound_skipped true` to explicitly skip.'
+    "Compound capture missing: no learnings.md found in change directory. "
+    + "Write this change's session learnings to <change-dir>/learnings.md (format: templates/learnings.md) during closing, "
+    + 'or `tf state set compound_skipped true` to explicitly skip. '
+    + 'Note: `tf solutions capture` writes to global docs/solutions/, not to learnings.md.'
   );
   return { pass: false, failures };
 }

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/cmd-runtime.mjs

@@ -15,6 +15,7 @@ const ASSETS = new Set([
   'skills/build-executor/task-reviewer-prompt.md',
   'templates/design.md',
   'templates/execution-contract.md',
+  'templates/learnings.md',
   'templates/proposal.md',
   'templates/spec.md',
   'templates/tasks.md',

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');