@xulthekl/team-flow 0.36.3 → 0.37.0

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

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

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "team-flow",
-  "version": "0.36.3",
+  "version": "0.37.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.36.3",
+  "version": "0.37.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.36.3"
+    "version": "0.37.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.36.3",
+  "version": "0.37.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.36.3"
+    "version": "0.37.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.36.3",
+      "version": "0.37.0",
       "source": ".",
       "author": {
         "name": "LT",

package/AGENTS.md

@@ -49,6 +49,7 @@ spec 驱动开发过程。8 态变更机：`exploring → specifying → bridgin
 
 ### 4. prototype（1 skill，本地 HTML 原型，v0.15.0 内部编排重构）
 - 全局一份 `prototype/`（与 PRD 同级，git 分支隔离），零外部依赖、可离线
+- **v0.37.0 版本 worktree 隔离**：原型独立仓库（有远程），版本分支 `prd-vN` 的 worktree 由 `tf prototype branch <prd-vN>` 创建/复用（隔离 + 团队拉取），版本收尾 `tf prototype deisolate <prd-vN> --merge --clean` merge 回主干（§68.4）；原型 worktree 布局 `<workspace>/.worktrees/<prd-vN>/prototype/`
 - **内部编排器（v0.15.0）**：主代理只编排不实施——环境探查(`prototype-env-scout`)→方案/人工评审→绘制(`prototype-builder`)→评审(`prototype-reviewer`)→循环→人工路由
 - **v0.20.0 产出质量闸门**：builder→reviewer 间主代理强制 `test -f && test -s` 校验入口产物落盘（不信 status=done 字面值，缺失则 resume，不空转评审）；后台子代理依赖 `<task-notification>` 完成通知，禁反复 `TaskOutput(block=true)` 轮询（设计 §22）
 - **v0.21.0 决策点中继（stop-and-resume）**：子代理（无 AskUserQuestion）决策点经 `SendMessage(to: main)` 发问即停，主代理收 task-notification 代问用户、回传自动 resume 子代理续跑；主代理须维护请求-应答匹配（设计 §22.1.1，修订 §18.1.2，LT 实证确认）

package/CHANGELOG.md

@@ -6,6 +6,23 @@ The format loosely follows Keep a Changelog.
 
 ## [Unreleased]
 
+## [0.37.0] - 2026-08-05
+
+### Added（阶段同步 + 原型版本隔离，设计增强方案 v0.15 §68）
+
+- **CLI 新命令 `tf publish`**：阶段产物白名单提交 + 可选推送（`--prd / --arch / --changes <dir> / --all` + `--push` 确认制 + `--dry-run`）；复用 arch-merge 白名单 commit 模式 + 外部脏文件检测 + 独立写锁（`.publish.lock`）
+- **CLI 新命令 `tf prototype branch` / `tf prototype deisolate`**：原型仓库（独立 + 远程）PRD 版本 worktree 隔离——`branch <prd-vN>` 创建/复用版本 worktree（隔离 + 团队一键拉取）；`deisolate <prd-vN> --merge --clean` 版本收尾 merge 回主干 + 清理（方案 A：merge 时机 = 版本收尾）
+- **5 个同步门禁点（G1-G5，§68.2）**：S2 冻结 / ARCH 完成 / orchestrator 结束 / execution-contract 完成 / change closing——各点 AskUserQuestion 三选项（提交并推送 / 仅提交 / 暂不同步），团队协作阶段产物同步
+- **制品链路径版本化修正（§68.5）**：原型引用 = 语义相对 + 版本绑定；spec-writer / build-executor / e2e / contract-builder 声明原型版本 worktree 路径；`prototype-sync --prototype-dir` 缺省按版本解析 worktree（`derivePrdVersion`/`resolvePrototypeDir`，change-brief `upstream_plan_ref` 推导，worktree 缺失回退主仓库并提示）
+- **文档**：设计增强方案 v0.15（§68 阶段同步 + 原型版本隔离 + §69 决策落实状态）
+
+## [0.36.4] - 2026-08-05
+
+### Added（Wave 审查纪律 + 上下文轮转）
+
+- **workflow-start SKILL.md**：Route to code-reviewer 增加逐 wave 审查纪律——每次 code-reviewer dispatch 只审查一个 wave，禁止合并多 wave 审查（vrm4teamflow C1 事件修复）
+- **workflow-start SKILL.md**：Sub-agent Dispatch Protocol 增加 build-executor 交互轮次轮转——累计 ≥6 轮 SendMessage 交互时启动新 build-executor 子代理（交接文档必须含已完成 waves + 累积决策 + worktree SHA）
+
 ## [0.36.3] - 2026-08-05
 
 ### Fixed（v0.14 全链路缺口修复——27 项，复利链路 + agent 契约 + 门禁时序 + 交接/决策门 + guard hook + 快照生命周期 + 旧项目 + 文档同步 + 横展）

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

package/README.md

@@ -1,6 +1,6 @@
 # team-flow
 
-> 当前版本：`v0.36.3`
+> 当前版本：`v0.37.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.36.3`
+- Current: `v0.37.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). 24 skills, one install.",
-  "version": "0.36.3",
+  "version": "0.37.0",
   "contextFileName": "GEMINI.md"
 }

package/hooks/session-start

@@ -1,11 +1,11 @@
 #!/usr/bin/env bash
-# v0.36.3: auto-sync CLI version with plugin version
+# v0.37.0: auto-sync CLI version with plugin version
 set -e
 
 # ═══════════════════════════════════════════════════════════════
 # Plugin version (update this when releasing new versions)
 # ═══════════════════════════════════════════════════════════════
-PLUGIN_VERSION="0.36.3"
+PLUGIN_VERSION="0.37.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.36.3.
+Current version: v0.37.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.36.3",
+  "version": "0.37.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.36.3",
+  "version": "0.37.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/lib/cmd-prototype.mjs

@@ -0,0 +1,227 @@
+#!/usr/bin/env node
+/**
+ * prototype — 原型仓库版本 worktree 隔离（v0.37.0 §68.4）
+ *
+ * 用法：
+ *   tf prototype branch <prd-vN>                # 创建/复用原型版本 worktree（隔离 + 团队拉取）
+ *   tf prototype deisolate <prd-vN> [--merge] [--clean]
+ *                                               # 版本收尾：merge 回主干 + 清理 worktree
+ *
+ * 设计（v0.15 §68.4/§68.6）：
+ * - 原型为独立 git 仓库（有远程），位置约定 = <workspace>/prototype/
+ * - 隔离单位 = PRD 版本（分支 `prd-vN`），worktree 布局 = <workspace>/.worktrees/prd-vN/prototype/
+ *   （与代码实施 ensure-branch 的 .worktrees/ 统一隔离区同构，gitignored）
+ * - branch：幂等（已有 worktree 复用）；从远程拉 prd-vN（远程存在）或从主干创建（不存在）
+ *   —— worktree 命令同时是团队查看者的一键拉取入口（§68.6）
+ * - deisolate：版本收尾（change_dag 该版本全部 closing）时 merge `prd-vN` 回主干 + 清理
+ *   （方案 A，LT 决策 2026-08-05：merge 时机 = 版本收尾，一次 merge 干净）
+ */
+
+import { execFileSync } from 'node:child_process';
+import { existsSync, readdirSync, rmSync, appendFileSync, readFileSync } from 'node:fs';
+import { join, resolve, basename } from 'node:path';
+
+const PROTECTED = ['main', 'master'];
+
+/** git 执行封装（统一 encoding + 错误降级）。 */
+function git(cwd, ...args) {
+  return execFileSync('git', args, { encoding: 'utf-8', cwd, stdio: ['ignore', 'pipe', 'pipe'] }).trim();
+}
+
+/** 规范化 PRD 版本参数 → `prd-vN`。接受 "v2"/"2"/"prd-v2"。 */
+function normalizeBranchName(raw) {
+  const cleaned = String(raw || '').trim();
+  if (!cleaned) throw new Error('缺少 PRD 版本参数（如 tf prototype branch v2）');
+  if (/^prd-v\d+/i.test(cleaned)) return cleaned.toLowerCase();
+  const v = cleaned.replace(/^v/i, '');
+  if (!/^\d+$/.test(v)) throw new Error(`非法 PRD 版本：${raw}（应为 vN，如 v2）`);
+  return `prd-v${v}`;
+}
+
+/** 定位 workspace root（cwd 在主仓库内）与原型仓库路径。 */
+function resolveLayout() {
+  let workspaceRoot;
+  try {
+    workspaceRoot = git(process.cwd(), 'rev-parse', '--show-toplevel');
+  } catch {
+    throw new Error('无法定位 workspace root：cwd 不在 git 仓库内？');
+  }
+  const protoRepo = join(workspaceRoot, 'prototype');
+  if (!existsSync(join(protoRepo, '.git'))) {
+    throw new Error(`原型仓库不存在或非 git 仓库：${protoRepo}\n  约定：原型仓库 = <workspace>/prototype/（独立 git 仓库，有远程）`);
+  }
+  return { workspaceRoot, protoRepo };
+}
+
+function ensureWorktreeGitignore(root) {
+  const gitignorePath = join(root, '.gitignore');
+  let existing = '';
+  try { existing = readFileSync(gitignorePath, 'utf-8'); } catch { existing = ''; }
+  const already = existing.split(/\r?\n/).map(l => l.trim()).some(l => l === '.worktrees/' || l === '.worktrees');
+  if (already) return;
+  appendFileSync(gitignorePath, `${existing.length > 0 && !existing.endsWith('\n') ? '\n' : ''}.worktrees/\n`);
+  console.log(`prototype: added '.worktrees/' to ${gitignorePath}.`);
+}
+
+/** 检查远程 prd-vN 分支是否存在。 */
+function remoteBranchExists(protoRepo, branch) {
+  try {
+    git(protoRepo, 'rev-parse', '--verify', `origin/${branch}`);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** 检查本地 prd-vN 分支是否存在。 */
+function localBranchExists(protoRepo, branch) {
+  try {
+    git(protoRepo, 'rev-parse', '--verify', `refs/heads/${branch}`);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** 子命令 branch：创建/复用原型版本 worktree。 */
+function cmdBranch(branchName) {
+  const { workspaceRoot, protoRepo } = resolveLayout();
+  const wtPath = join(workspaceRoot, '.worktrees', branchName, basename(protoRepo));
+
+  // 幂等：worktree 已存在 → 复用
+  if (existsSync(join(wtPath, '.git'))) {
+    console.log(`prototype: worktree 已存在，复用 ${wtPath}`);
+    console.log(`  分支：${branchName}（原型版本 ${branchName} 的工作区）`);
+    return { created: false, reused: true, worktreePath: wtPath };
+  }
+
+  ensureWorktreeGitignore(workspaceRoot);
+
+  // fetch 远程，获取团队已推送的 prd-vN
+  try { git(protoRepo, 'fetch', 'origin'); } catch { /* 远程不可达时降级为本地创建 */ }
+
+  const fromRemote = remoteBranchExists(protoRepo, branchName);
+  try {
+    if (fromRemote) {
+      git(protoRepo, 'worktree', 'add', wtPath, '-b', branchName, `origin/${branchName}`);
+      console.log(`prototype: 从远程 origin/${branchName} 创建 worktree ${wtPath}`);
+    } else {
+      git(protoRepo, 'worktree', 'add', wtPath, '-b', branchName);
+      console.log(`prototype: 从主干创建分支 ${branchName} 的 worktree ${wtPath}`);
+      console.log(`  提示：该版本原型首次创建，迭代完成后 push origin ${branchName} 供团队拉取`);
+    }
+    return { created: true, fromRemote, worktreePath: wtPath };
+  } catch (e) {
+    const msg = (e.stderr || e.stdout || e.message || '').toString().trim();
+    throw new Error(`worktree 创建失败：${msg}`);
+  }
+}
+
+/** 子命令 deisolate：版本收尾 merge 回主干 + 清理 worktree。 */
+function cmdDeisolate(branchName, opts) {
+  const { workspaceRoot, protoRepo } = resolveLayout();
+  const wtPath = join(workspaceRoot, '.worktrees', branchName, basename(protoRepo));
+  const result = { branch: branchName, worktreePath: wtPath };
+
+  if (!existsSync(join(wtPath, '.git'))) {
+    console.log(`prototype: ${branchName} 无 worktree（${wtPath} 不存在），无可清理。`);
+    return { found: false };
+  }
+  result.found = true;
+
+  const masterBranch = git(protoRepo, 'branch', '--show-current') || 'master';
+  result.master = masterBranch;
+
+  // ahead/behind 摘要
+  try {
+    const ahead = git(protoRepo, 'rev-list', '--count', `${masterBranch}..${branchName}`);
+    const behind = git(protoRepo, 'rev-list', '--count', `${branchName}..${masterBranch}`);
+    result.ahead = parseInt(ahead, 10);
+    result.behind = parseInt(behind, 10);
+  } catch { /* 分支可能未合并过，忽略 */ }
+
+  if (opts.merge) {
+    try {
+      git(protoRepo, 'merge', branchName, '--no-edit');
+      result.merged = true;
+      console.log(`✅ ${branchName} merged → ${masterBranch}（版本收尾，方案 A）`);
+    } catch (e) {
+      result.merged = false;
+      result.mergeError = (e.stderr || e.stdout || e.message || '').toString().trim();
+      console.error(`❌ merge 失败：${result.mergeError}`);
+      console.error('  存在冲突时请先人工解决再重试。');
+    }
+  } else {
+    console.log(`  ahead=${result.ahead ?? '?'} behind=${result.behind ?? '?'}（相对 ${masterBranch}）`);
+    console.log('  未执行 merge（加 --merge 提交合并回主干）。');
+  }
+
+  if (opts.clean) {
+    const errors = [];
+    try { git(protoRepo, 'worktree', 'remove', wtPath, '--force'); result.worktreeRemoved = true; }
+    catch {
+      try { rmSync(wtPath, { recursive: true, force: true }); result.worktreeRemoved = true; }
+      catch (e) { errors.push(`worktree remove: ${e.message}`); }
+    }
+    try { git(protoRepo, 'branch', '-d', branchName); result.branchDeleted = true; }
+    catch {
+      try { git(protoRepo, 'branch', '-D', branchName); result.branchDeleted = true; }
+      catch (e) { errors.push(`branch delete: ${e.message}`); }
+    }
+    if (errors.length > 0) console.error(`  ⚠️ ${errors.join('; ')}`);
+    else console.log('✅ worktree + 分支已清理。');
+  } else {
+    console.log('  未执行清理（加 --clean 删除 worktree + 分支）。');
+  }
+
+  return result;
+}
+
+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]
+                                               # 版本收尾：merge 回主干 + 清理 worktree
+
+示例：
+  tf prototype branch v2                        # 为 PRD v2 创建/复用 prd-v2 worktree
+  tf prototype branch prd-v2                    # 同上（分支名已含前缀）
+  tf prototype deisolate v2 --merge --clean     # v2 收尾：merge 回主干 + 清理
+
+说明：
+  - 原型仓库约定：<workspace>/prototype/（独立 git 仓库，有远程）
+  - worktree 布局：<workspace>/.worktrees/<prd-vN>/prototype/（gitignored 隔离区）
+  - merge 时机 = 版本收尾（change_dag 该版本全部 closing），一次 merge 回主干`);
+}
+
+/** CLI 入口（export 供 team-flow.mjs 注册）。 */
+export async function run(args = []) {
+  const [sub, rawVersion, ...rest] = args;
+  if (!sub || sub === '-h' || sub === '--help') { usage(); return; }
+
+  if (!rawVersion) {
+    console.error(`tf prototype ${sub} 缺少 PRD 版本参数（如 tf prototype ${sub} v2）`);
+    process.exit(2);
+  }
+
+  let branchName;
+  try { branchName = normalizeBranchName(rawVersion); }
+  catch (e) { console.error(e.message); process.exit(2); }
+
+  try {
+    if (sub === 'branch') {
+      return cmdBranch(branchName);
+    }
+    if (sub === 'deisolate') {
+      const opts = { merge: rest.includes('--merge'), clean: rest.includes('--clean') };
+      return cmdDeisolate(branchName, opts);
+    }
+    console.error(`未知子命令：${sub}（可用：branch / deisolate）`);
+    process.exit(2);
+  } catch (e) {
+    console.error(`prototype: ${e.message}`);
+    process.exit(1);
+  }
+}

package/scripts/lib/cmd-publish.mjs

@@ -0,0 +1,254 @@
+#!/usr/bin/env node
+/**
+ * publish — 阶段产物白名单提交 + 可选推送（v0.37.0 §68.3）
+ *
+ * 用法：tf publish <target> [--push] [--dry-run]
+ *   target: --prd（PRD + orchestrator.yaml + registry.yaml + 主仓库 prototype/）
+ *         / --arch（docs/architecture/ 迭代快照）
+ *         / --changes <dir>（change 制品，缺省则整个 changes/）
+ *         / --all（全部）
+ *
+ * 设计（v0.15 §68.3）：
+ * 1. 白名单 git add：只 add 本次 target 对应目录，防卷走无关改动（复用 arch-merge 协作安全模式）
+ * 2. 脏文件检测：target 目录之外存在未提交文件 → 告警（不阻断，提示人工确认）
+ * 3. 写锁：.publish.lock（mkdir 原子语义，防并行 publish 冲突）
+ * 4. push 确认制：--push 显式开启；只推当前分支、不跨分支（push 是外向操作，强制确认）
+ * 5. --dry-run：只打印将执行的 git 动作，不落盘不 commit 不 push
+ */
+
+import { execFileSync } from 'node:child_process';
+import { existsSync, mkdirSync, readdirSync, rmdirSync } from 'node:fs';
+import { join, resolve, isAbsolute } from 'node:path';
+
+const LOCK_PATH = '.publish.lock';
+
+/** 解析 CLI 参数。 */
+function parseArgv(argv) {
+  const parsed = { targets: [], push: false, dryRun: false, changeDir: 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 === '--prd') parsed.targets.push('prd');
+    else if (a === '--arch') parsed.targets.push('arch');
+    else if (a === '--changes') {
+      // 无目录 = 整个 changes/；带目录 = 单个 change（目录以 -- 开头则视为无目录，MAJOR 修复 v0.37.0）
+      parsed.targets.push('changes');
+      const next = argv[i + 1];
+      if (next && !next.startsWith('--')) parsed.changeDir = argv[++i];
+    } else if (a === '--all') parsed.targets.push('all');
+    else if (a === '-h' || a === '--help') parsed.help = true;
+    else {
+      console.error(`Unknown argument: ${a}`);
+      console.error('Usage: tf publish <--prd|--arch|--changes <dir>|--all> [--push] [--dry-run]');
+      process.exit(2);
+    }
+  }
+  if (parsed.targets.length === 0 && !parsed.help) {
+    console.error('No target specified.');
+    console.error('Usage: tf publish <--prd|--arch|--changes <dir>|--all> [--push] [--dry-run]');
+    process.exit(2);
+  }
+  return parsed;
+}
+
+/** git 执行封装（统一 encoding + 错误降级）。 */
+function git(cwd, ...args) {
+  return execFileSync('git', args, { encoding: 'utf-8', cwd, stdio: ['ignore', 'pipe', 'pipe'] }).trim();
+}
+
+function isDir(p) {
+  try { return existsSync(p) && readdirSync(p).length >= 0; } catch { return false; }
+}
+
+/**
+ * 收集本次 publish 的白名单路径（目录级）。
+ * 只 add 这些路径；target 目录之外的未提交改动一律不碰。
+ */
+function collectWhitelist(projectRoot, targets, changeDir) {
+  const paths = [];
+  const want = t => targets.includes('all') || targets.includes(t);
+
+  if (want('prd')) {
+    const prdDir = join(projectRoot, 'prd');
+    if (isDir(prdDir)) paths.push(prdDir);
+    // 主仓库内 prototype/（独立仓库场景由原型 worktree 命令管理，这里仅收集主仓库可见部分）
+    const protoDir = join(projectRoot, 'prototype');
+    if (isDir(protoDir)) paths.push(protoDir);
+    // 产品级编排状态
+    const teamflow = join(projectRoot, '.team-flow');
+    if (isDir(teamflow)) {
+      const registry = join(teamflow, 'registry.yaml');
+      if (existsSync(registry)) paths.push(registry);
+      const reqDir = join(teamflow, 'requirements');
+      if (isDir(reqDir)) {
+        for (const req of readdirSync(reqDir)) {
+          const oy = join(reqDir, req, 'orchestrator.yaml');
+          if (existsSync(oy)) paths.push(oy);
+        }
+      }
+    }
+  }
+
+  if (want('arch')) {
+    const archDir = join(projectRoot, 'docs', 'architecture');
+    if (isDir(archDir)) paths.push(archDir);
+    // arch_baseline 豁免键（v0.37.0 §68.5）：随架构快照一并同步，否则团队拉取后门禁误判存量（IMPORTANT 修复）
+    const archState = join(projectRoot, '.team-flow', 'arch-state.json');
+    if (existsSync(archState)) paths.push(archState);
+  }
+
+  if (want('changes')) {
+    if (changeDir) {
+      const abs = isAbsolute(changeDir) ? changeDir : resolve(projectRoot, changeDir);
+      if (existsSync(abs)) paths.push(abs);
+      else console.warn(`[WARN] change 目录不存在：${abs}`);
+    } else {
+      const changesDir = join(projectRoot, 'changes');
+      if (isDir(changesDir)) paths.push(changesDir);
+    }
+  }
+
+  return paths;
+}
+
+/**
+ * 检测白名单之外的未提交/未跟踪文件（团队协作安全底线，仿 arch-merge detectUntouchedDirtyFiles）。
+ * 返回值：外部脏文件列表（含 staged + unstaged + untracked）。
+ */
+function detectOutsideDirty(projectRoot, whitelist) {
+  const relWhitelist = new Set(whitelist.map(p => {
+    const rel = p.replace(projectRoot + '/', '');
+    return rel.replace(/\/+$/, '');
+  }));
+  try {
+    const status = git(projectRoot, 'status', '--porcelain');
+    if (!status) return [];
+    return status.split('\n').filter(Boolean)
+      .map(line => {
+        // porcelain 前 2 字符是状态，后面是路径（引号包裹的可能带空格）
+        const raw = line.slice(3).replace(/^"|"$/g, '').replace(/\\ /g, ' ');
+        return raw;
+      })
+      .filter(p => {
+        if (!p) return false;
+        const norm = p.replace(/\/+$/, ''); // porcelain 目录级输出带尾斜杠，先去规范化
+        // 跳过 .publish.lock 自身（写锁目录）
+        if (norm === LOCK_PATH || norm.startsWith(LOCK_PATH + '/')) return false;
+        // 跳过 worktree 隔离区（gitignored，理论上不会出现，防御性跳过）
+        if (norm.startsWith('.worktrees/')) return false;
+        // 白名单判定（双向往返匹配）：
+        //  - norm 在白名单项内（norm === w 或 norm.startsWith(w + '/')）→ 豁免
+        //  - 白名单项是 norm 的后代（w.startsWith(norm + '/')）→ 豁免
+        //    （全新仓库 porcelain 对未跟踪内容显示目录级如 `?? docs/`，
+        //      其下白名单子目录 docs/architecture 已被覆盖，属正常提交范围）
+        for (const w of relWhitelist) {
+          if (norm === w || norm.startsWith(w + '/')) return false;
+          if (w.startsWith(norm + '/')) return false;
+        }
+        return true;
+      });
+  } catch {
+    return [];
+  }
+}
+
+function acquireLock(projectRoot) {
+  const lockPath = join(projectRoot, LOCK_PATH);
+  if (existsSync(lockPath)) {
+    throw new Error(`another publish in progress (${LOCK_PATH} exists) — 串行化提交，稍后重试`);
+  }
+  mkdirSync(lockPath);
+  return lockPath;
+}
+
+function releaseLock(lockPath) {
+  try { rmdirSync(lockPath); } catch { /* ignore */ }
+}
+
+function describeTargets(parsed) {
+  const t = parsed.targets.includes('all') ? 'all' : parsed.targets.join('+');
+  return parsed.targets.includes('changes') && parsed.changeDir ? `${t}:${parsed.changeDir}` : t;
+}
+
+/**
+ * CLI 入口（export 供 team-flow.mjs 注册）。
+ */
+export async function run(args = []) {
+  const parsed = parseArgv(args);
+  if (parsed.help) {
+    console.log(`tf publish — 阶段产物白名单提交 + 可选推送（v0.37.0 §68.3）
+
+用法：tf publish <target> [--push] [--dry-run]
+  --prd         提交 PRD + orchestrator.yaml + registry.yaml + 主仓库 prototype/
+  --arch        提交 docs/architecture/（迭代快照）
+  --changes     提交整个 changes/（或 --changes <change-dir> 指定单个 change）
+  --all         提交全部上述
+  --push        同时推送到远程当前分支（默认只提交不推送）
+  --dry-run     只打印将执行的 git 动作，不落盘不 commit`);
+    return;
+  }
+
+  const projectRoot = git(process.cwd(), 'rev-parse', '--show-toplevel');
+  const whitelist = collectWhitelist(projectRoot, parsed.targets, parsed.changeDir);
+
+  if (whitelist.length === 0) {
+    console.log('ℹ️  没有可提交的阶段产物（白名单为空）。');
+    return;
+  }
+
+  // 脏文件检测（target 之外）→ 告警不阻断
+  const outsideDirty = detectOutsideDirty(projectRoot, whitelist);
+  if (outsideDirty.length > 0) {
+    console.warn(`[WARN] 白名单之外存在 ${outsideDirty.length} 个未提交文件（不提交）：`);
+    for (const f of outsideDirty.slice(0, 5)) console.warn(`  - ${f}`);
+    if (outsideDirty.length > 5) console.warn(`  ... 等 ${outsideDirty.length} 个`);
+  }
+
+  const targetDesc = describeTargets(parsed);
+  const commitMsg = `tf publish: ${targetDesc} — sync stage artifacts`;
+
+  if (parsed.dryRun) {
+    console.log('[DRY-RUN] Would execute:');
+    console.log(`  git add ${whitelist.map(p => p.replace(projectRoot + '/', '')).join(' ')}`);
+    console.log(`  git commit -m "${commitMsg}"`);
+    if (parsed.push) {
+      const branch = git(projectRoot, 'branch', '--show-current');
+      console.log(`  git push origin ${branch}`);
+    }
+    return { published: false, dryRun: true };
+  }
+
+  const lockPath = acquireLock(projectRoot);
+  try {
+    // 白名单 git add（只 add 目标目录）
+    for (const p of whitelist) {
+      const rel = p.replace(projectRoot + '/', '');
+      execFileSync('git', ['add', rel], { cwd: projectRoot, stdio: 'pipe' });
+    }
+    // commit（nothing to commit 可接受）
+    try {
+      execFileSync('git', ['commit', '-m', commitMsg], { cwd: projectRoot, stdio: 'pipe' });
+      console.log(`✅ committed: ${commitMsg}`);
+    } catch (e) {
+      // git 空提交消息在 stdout（execFileSync 失败时 stderr 常为空 Buffer，需先排除空值）
+      const msg = (e.stderr && e.stderr.toString()) || (e.stdout && e.stdout.toString()) || '';
+      // git 空提交两种提示：工作树干净 / 有未跟踪但无 staged 变更
+      if (msg.includes('nothing to commit') || msg.includes('nothing added to commit')) {
+        console.log('ℹ️  没有变更需要提交。');
+      } else {
+        throw new Error(`git commit failed: ${msg}`);
+      }
+    }
+    // push（确认制）
+    if (parsed.push) {
+      const branch = git(projectRoot, 'branch', '--show-current');
+      console.log(`↗️  pushing to origin/${branch} ...`);
+      execFileSync('git', ['push', 'origin', branch], { cwd: projectRoot, stdio: 'inherit' });
+      console.log('✅ pushed.');
+    }
+    return { published: true, targets: parsed.targets, pushed: parsed.push };
+  } finally {
+    releaseLock(lockPath);
+  }
+}

package/scripts/lib/prototype-sync.mjs

@@ -15,7 +15,7 @@
  */
 
 import { readFileSync, writeFileSync, existsSync, cpSync, mkdirSync } from 'node:fs';
-import { join, basename, relative } from 'node:path';
+import { join, basename, relative, sep, resolve } from 'node:path';
 
 /**
  * 解析 CLI 参数数组为结构化对象
@@ -36,6 +36,45 @@ function parseArgv(argv) {
   return parsed;
 }
 
+/**
+ * 推导 change 所属 PRD 版本（v0.37.0 §68.5）。
+ * 优先级：change-brief.md 的 upstream_plan_ref → change 目录名 v{N}- 前缀。
+ * @returns {string|null} 如 'v2'；无法推导返回 null
+ */
+function derivePrdVersion(changeDir) {
+  const briefPath = join(changeDir, 'change-brief.md');
+  try {
+    if (existsSync(briefPath)) {
+      const content = readFileSync(briefPath, 'utf-8');
+      const m = content.match(/upstream_plan_ref:\s*prd\/(v\d+)\//);
+      if (m) return m[1];
+    }
+  } catch { /* ignore */ }
+  const m = basename(changeDir).match(/^v(\d+)-/);
+  if (m) return `v${m[1]}`;
+  return null;
+}
+
+/**
+ * 解析原型目录（v0.37.0 §68.5 制品链路径版本化）：
+ * --prototype-dir 显式指定优先；否则从 change 推导 PRD 版本 → 定位版本 worktree 的 prototype/。
+ * worktree 不存在时回退主仓库 prototype/ 并提示。
+ */
+function resolvePrototypeDir(changeDir, prototypeDirArg) {
+  if (prototypeDirArg) return prototypeDirArg;
+  const version = derivePrdVersion(changeDir);
+  if (!version) return 'prototype'; // 无法推导版本 → 回退主仓库 prototype/
+  const abs = resolve(changeDir);
+  const changesIdx = abs.lastIndexOf(sep + 'changes' + sep);
+  const workspaceRoot = changesIdx > 0 ? abs.slice(0, changesIdx) : process.cwd();
+  const branchName = `prd-${version}`;
+  const wt = join(workspaceRoot, '.worktrees', branchName, 'prototype');
+  if (existsSync(join(wt, '.git'))) return wt;
+  const fallback = join(workspaceRoot, 'prototype');
+  console.log(`ℹ️  原型版本 worktree 不存在（${wt}），回退 ${fallback}。原型独立仓库场景请先 \`tf prototype branch ${branchName}\`。`);
+  return fallback;
+}
+
 /**
  * 执行 prototype-sync 合并
  * @param {string[]|object} args - CLI 参数数组（从 tf 框架传入）或已解析的对象
@@ -49,7 +88,7 @@ export function run(args = {}) {
 
   const changeDir = args._?.[0] || args.changeDir;
   const sourcePath = args.source;
-  const prototypeDir = args.prototypeDir || 'prototype';
+  const prototypeDir = resolvePrototypeDir(changeDir, args.prototypeDir);
 
   if (!changeDir) {
     console.error('Usage: tf prototype-sync <change-dir> [--source <ux-delta-path>] [--prototype-dir <path>]');

package/scripts/team-flow.mjs

@@ -34,6 +34,8 @@ const COMMANDS = {
   'install-qoder':    () => import('./lib/cmd-install-qoder.mjs'),
   'install-zcode':     () => import('./lib/cmd-install-zcode.mjs'),
   'prototype-sync':    () => import('./lib/prototype-sync.mjs'),
+  prototype:           () => import('./lib/cmd-prototype.mjs'),
+  publish:             () => import('./lib/cmd-publish.mjs'),
   'arch-merge':        () => import('./lib/arch-merge.mjs'),
   arch:                () => import('./lib/cmd-arch.mjs'),
   'test-merge':        () => import('./lib/test-merge.mjs'),
@@ -53,6 +55,12 @@ Commands:
   sync <change-dir>     Merge delta specs into main specs
   prototype-sync <change-dir> [--source <path>] [--prototype-dir <path>]
                         Merge UX delta into global prototype/ + design-system.md
+  publish <--prd|--arch|--changes <dir>|--all> [--push] [--dry-run]
+                        Commit stage artifacts (whitelist) + optional push (v0.37.0 §68.3)
+  prototype branch <prd-vN>
+                        Create/reuse prototype version worktree (v0.37.0 §68.4)
+  prototype deisolate <prd-vN> [--merge] [--clean]
+                        Version wrap-up: merge prototype branch back + clean worktree
   arch init [--mode reconstruction|design] [--baseline-ref <prd/vN/>]
                         Stamp project-level arch_baseline into .team-flow/arch-state.json (v0.35.0 §59.4)
   arch show             Show current project architecture baseline state

package/skills/architecture-design/references/s3.5-product-architecture.md

@@ -72,6 +72,15 @@
 
 逆向重建工具：`workflow-bootstrap` 的 recon-probe.sh（--ddl-out，路径 `${CLAUDE_PLUGIN_ROOT}/skills/workflow-bootstrap/scripts/recon-probe.sh`）+ codebase-recon-analyst + 新增 `arch-reverse-analyst`（v0.14 §63.2）。
 
+## 阶段产物同步门禁点（v0.37.0 §68.2 G2）
+
+ARCH 完成（评审 PASS 或 skip 已物化）后，**阻塞确认**（AskUserQuestion）是否同步阶段产物（团队协作：架构决策是实施依据）：
+- **A 提交并推送**：`tf publish --arch --push`
+- **B 仅提交不推送**：`tf publish --arch`
+- **C 暂不同步**：继续 S4，后续可补
+
+同步对象：`docs/architecture/iterations/vN/`（架构快照）+ 评审 verdict（含首轮 `tf arch init` 打戳产物 `.team-flow/arch-state.json`）。
+
 ## 完成条件
 
 - `docs/architecture/iterations/vN/architecture.md` 已产出（6 产物，provenance 标注）

package/skills/build-executor/SKILL.md

@@ -43,6 +43,13 @@ Branch/worktree preflight before ANY implementation edit (mandatory — do not s
    aggregated `<workspace>/.worktrees/<change>/` directory — and make all implementation
    edits there.
 
+### UI Contract Prototype Location (v0.37.0 §68.5)
+
+When implementing UI tasks, the UI contract source is the **prototype version worktree**, not the change worktree's prototype copy:
+- **定位**：读 `change-brief.md` 的 `upstream_plan_ref: prd/vN/plan.md`（或 change 目录名 `v{N}-` 前缀）→ PRD 版本 vN → 原型 worktree = `<workspace>/.worktrees/prd-vN/prototype/`
+- **回退**：该 worktree 不存在时用 `<workspace>/prototype/`，并提示 `tf prototype branch <prd-vN>` 创建
+- **引用**：execution-contract / design.md 中引用的原型页面（`prototype/pages/<page>.html` 等）以此为基准定位；**禁止**引用主干上其他版本的旧原型
+
 ## Core Laws
 
 ### Law 0: State Field Boundary (v0.30.0)

package/skills/contract-builder/SKILL.md

@@ -36,6 +36,19 @@ Before finalizing:
 
 Must make obvious: approved behavior, out-of-scope, constraints, batches, test obligations, review gates, and conditions that force a rewind to planning. Prefer compression over repeating planning details.
 
+## UI UX Delta Prototype Reference (v0.37.0 §68.5)
+
+When the change involves UI (design.md has a `## UI Contract` section), the execution-contract's `## UX 增量` section (consumed by `tf prototype-sync`) must **state the prototype version worktree path** in its first line:
+
+```markdown
+## UX 增量
+原型目标：<workspace>/.worktrees/prd-vN/prototype/（PRD 版本 vN，从 change-brief `upstream_plan_ref` 推导）
+[ADD] pages/xxx.html
+[MODIFY] pages/yyy.html
+```
+
+`[ADD]/[MODIFY]` relative paths stay prototype-root-relative; the stated worktree is what `prototype-sync` resolves to when `--prototype-dir` is absent (v0.37.0 §68.5 制品链路径版本化).
+
 ## Test Matrix Generation (v0.12 §42, v0.13 §52 B1 强制化)
 
 `test-matrix.md` 是 `execution-contract.md` 的**附属产物**（不是独立第 6 核心产物），在 contract 的 `## Test Matrix` 段引用。

package/skills/e2e/SKILL.md

@@ -52,5 +52,7 @@ user-invocable: true
 ## 复用机制
 单一 `e2e/` + `playwright.config.ts` `projects`(baseURL)：`prototype` project → http-server 托管 HTML；`integration` project → 真实应用。脚本一致，仅切地址 + 少量选择器/断言适配（高重叠复用，非零触碰；原型绿 ≠ 集成绿）。
 
+**原型期托管（v0.37.0 §68.5）**：`prototype` project 托管的原型 = 对应 PRD 版本 worktree 的 `prototype/`（`<workspace>/.worktrees/prd-vN/prototype/`，版本从 change-brief `upstream_plan_ref` 推导）；baseURL 指向该 worktree 的 http-server，**不指向主干旧版本原型**。该 worktree 缺失时回退 `<workspace>/prototype/` 并提示 `tf prototype branch <prd-vN>` 创建（与 prototype-sync 回退语义一致）。
+
 ## 与 release-archivist 衔接
 e2e 报告 + 4 级制品比对（L1 存在 / L2 实质 / L3 接线 / L4 数据流）作为 closing 验收 gate 的验证维度，由 `release-archivist` 接入（`ce-proof` 是 Proof 编辑器，与此无关）。

package/skills/prototype/SKILL.md

@@ -87,6 +87,7 @@ prototype/
 ## 分支约定
 - 原型随 **PRD 当前版本分支**维护（如 `prd-v2` 分支的 `prototype/` = v2 产品原型）。
 - change 引用其所在 PRD 版本分支的 `prototype/`。
+- **版本 worktree 管理（v0.37.0 §68.4）**：原型为独立仓库（有远程），版本分支的 worktree 由 `tf prototype branch <prd-vN>` 创建/复用（隔离 + 团队拉取入口）；版本收尾（change_dag 该版本全部 closing）由 `tf prototype deisolate <prd-vN> --merge --clean` merge 回主干 + 清理（方案 A：merge 时机 = 版本收尾）。原型 worktree 布局 `<workspace>/.worktrees/prd-vN/prototype/`（与代码实施 `.worktrees/` 统一隔离区）。
 
 ## prototype-sync（change 完成回写，release-archivist 自动触发，v0.24.0 升级）
 

package/skills/release-archivist/SKILL.md

@@ -203,6 +203,15 @@ tf solutions capture \
 
 This check is advisory — skip silently if no learnable moments are detected.
 
+### 阶段产物同步门禁点（v0.37.0 §68.2 G5）
+
+回写链（arch-merge → prototype-sync → test-merge → compound promotion）全部完成后、`tf state transition closing` 之前，**阻塞确认**（AskUserQuestion）是否同步 change 实施结果（团队协作：落地结果是团队最需要看的内容）：
+- **A 提交并推送**：`tf publish --changes <change-dir> --push`
+- **B 仅提交不推送**：`tf publish --changes <change-dir>`（arch-merge/test-merge 已自动 commit，此步补 push）
+- **C 暂不同步**：继续 closing，后续可补
+
+同步对象：实施代码 `changes/<change-dir>/` + arch-merge 回写（docs/architecture/）+ test-ledger（docs/test-ledger/）。**原型独立仓库场景**：若本 change 有 UX 增量回写原型，push 对应 `prd-vN` 分支（`tf prototype branch <prd-vN>` 确认/创建 worktree）。
+
 ### Worktree Deisolation (v0.35.0) — advisory
 
 After compound promotion, check if worktree isolation exists for this change:

package/skills/spec-writer/SKILL.md

@@ -11,15 +11,19 @@ Create or refine planning artifacts when the change has moved beyond exploration
 
 Read `.team-flow.yaml` (especially `dp_0_decisions`, `dp_0_confirmed`) and any existing planning artifacts. If `dp_0_confirmed` is not `true`, stop and route back to `workflow-start` for DP-0.
 
-### Global Prototype Reading (v0.5)
+### Global Prototype Reading (v0.5, v0.37.0 版本化)
 
-Before generating artifacts, check if a global prototype exists:
-1. Read `prototype/flow.md` if it exists — this defines page navigation and user flows
-2. List `prototype/pages/` directory — these are the UI contract pages
-3. Read `prototype/design-system.md` if it exists — component and token definitions
-4. Store as UI contract context for design.md and tasks.md generation
+Before generating artifacts, **resolve the PRD version and locate the prototype worktree**:
+1. **版本推导（v0.37.0 §68.5）**：读 `change-brief.md` 的 `upstream_plan_ref: prd/vN/plan.md`（无 brief 时从 change 目录名 `v{N}-` 前缀推导）→ PRD 版本 vN
+2. **原型定位**：原型为独立仓库（有远程），版本 worktree = `<workspace>/.worktrees/prd-vN/prototype/`（该 worktree 不存在时回退 `<workspace>/prototype/` 并提示"原型应位于版本 worktree，`tf prototype branch <prd-vN>` 创建"）
+3. Read `prototype/flow.md` if it exists — this defines page navigation and user flows
+4. List `prototype/pages/` directory — these are the UI contract pages
+5. Read `prototype/design-system.md` if it exists — component and token definitions
+6. Store as UI contract context for design.md and tasks.md generation
 
-If `prototype/` does not exist or is empty, skip silently — not all projects have prototypes.
+If no prototype exists or it is empty, skip silently — not all projects have prototypes.
+
+**制品引用约定（v0.37.0 §68.5）**：design.md / tasks.md 中引用原型保留 `prototype/<rel>` 相对写法（可读性），但 `## UI Contract` / `**Prototype:**` 段必须**声明本 change 所属 PRD 版本 vN + 原型 worktree 路径**——实施阶段（build-executor）据此定位同一份原型，避免指向主干旧版本或空目录。
 
 ### Solutions Index (v0.5)
 

package/skills/workflow-orchestrator/references/s2-prd-prototype-loop.md

@@ -82,6 +82,15 @@ PRD草稿生成后：
 
 设置 `frozen_downstream`（见 state-model.md「双层冻结」）。冻结后，**迭代内变更不升版**，在 vN 内修订 + 记录决策/变更履历。
 
+### 4.5 阶段产物同步门禁点（v0.37.0 §68.2 G1）
+
+S2 冻结后，**阻塞确认**（AskUserQuestion）是否同步阶段产物（团队协作：PRD+原型是需求讨论基线）：
+- **A 提交并推送**：`tf publish --prd --push`；原型为独立仓库时先 `tf prototype branch <prd-vN>` 确认/创建版本 worktree（迭代完成 push `prd-vN` 分支供团队查看者 `tf prototype branch <prd-vN>` 一键拉取）
+- **B 仅提交不推送**：`tf publish --prd`
+- **C 暂不同步**：继续 S3，后续可补
+
+同步对象：`prd/vN/` + 原型（push `prd-vN` 分支）+ `.team-flow/`（orchestrator.yaml / registry.yaml）。
+
 ### 5. 复利捕获
 
 检测可复利时刻（需求矛盾、原型返工、自动评审发现不一致并修正等）。每次自动评审发现不一致并修正后触发：

package/skills/workflow-orchestrator/references/s4-split-validate.md

@@ -137,6 +137,15 @@ Change C1 已就绪，运行 /workflow-start 进入变更级流程。
 执行顺序建议：C1 → (C2 ∥ C3) → C4（C2/C3 可并行）
 ```
 
+### 5.5 阶段产物同步门禁点（v0.37.0 §68.2 G3）
+
+S4 分发完成（orchestrator 结束）后，**阻塞确认**（AskUserQuestion）是否同步阶段产物（团队协作：成员领取任务的前提）：
+- **A 提交并推送**：`tf publish --changes --push`
+- **B 仅提交不推送**：`tf publish --changes`
+- **C 暂不同步**：结束编排，后续可补
+
+同步对象：`changes/*/`（脚手架 + change-brief.md）+ `.team-flow/`（change_dag / orchestrator.yaml）= 任务分发（成员领取）。
+
 ## 完成条件
 
 - change-split-auditor 审计 verdict = PASS（必选门禁已通过，含 v0.9 D5 拆分维度合规）

package/skills/workflow-start/SKILL.md

@@ -62,6 +62,7 @@ Validate mode against artifact content. If hotfix/tweak criteria not met → upg
 
 - **记录 agentId**：dispatch 后立即记录子代理 ID；修复一律 SendMessage 恢复原子代理（禁启动新子代理，见 v0.29.0 §37）
   - **上下文水位例外（v0.35.0）**：当原子代理 transcript 超过 2MB 或累计 token 消耗超过 200 万时，主代理可以启动新代理替代恢复。新代理必须接收完整交接文档（当前进度、已完成 wave 列表、未解决问题、artifact 位置、已知 blocker），以保证连续性。此为 SendMessage 恢复原则的唯一补充例外
+  - **build-executor 交互轮次轮转（v0.36.4）**：主代理通过 SendMessage 恢复 build-executor 时，累计交互轮次。当累计 ≥6 轮（~3 wave 的典型交互量：放行→实施→审查→FAIL→修→复评）时，checkpoint 当前进度并启动新 build-executor 子代理。交接文档必须包含：已完成 waves 及 receipt 状态、累积技术决策（如命名约定、架构选型）、worktree commit SHA、剩余 waves 及依赖关系。此规则独立于上下文水位例外——两者取先触发者
 - **返回即验证（validation gate）**：子代理返回产物后**立即** `tf validate <change-dir>`；FAIL → SendMessage 回**原**子代理修复，通过后才能继续/转换。把格式失败拦截在返回时，而非状态转换时（避免浪费整次执行后再失败）。**build-executor 附加验证（v0.13 §52 B3，SDD/full 模式）**：返回的 diff 中必须包含测试文件（src/test/ 或项目测试目录）；零测试文件的实现返回一律 BLOCK，SendMessage 回原子代理按 test-matrix.md / TDD Iron Law 补齐——不得以"手动验证"替代（C1-domain-policy 事件教训）。例外：已显式记录 `test_matrix_skipped=true` + 理由的 change（纯文档/配置类）不要求测试文件
 - **结果协议**：子代理终态须标注 `FINAL VERDICT: <DONE|BLOCKED|FAIL>`（审查类用 PASS/PASS_WITH_WARNINGS/FAIL）；**SendMessage 报告为权威结果**，task-notification.result 仅内部元数据
 - **子代理状态边界**：子代理 MUST NOT 修改 `.team-flow.yaml` 的 `state`/`workflow` 核心字段（状态转换是主代理专有职责，经 `tf state transition` 执行），只写自己的 `dp_N_*` 决策字段
@@ -92,12 +93,23 @@ Guard: `... check <dir> specifying bridging --json` → fail = BLOCK. Artifacts
 ### Route to build-executor (dispatch sub-agent)
 Contract exists and approved, contract matches artifacts. Include `DP-4: 执行模式选择`: propose waves, run `tf execution recommend <change-dir> [--wave ...]`, show the user every available mode plus evidence and the recommendation, then obtain a clear selection. The command saves a current receipt; before the first implementation edit, `build-executor` must run `tf execution plan <change-dir> --mode <selected> --confirm ...` (and `--acknowledge-recommendation` when the selected mode differs from the recommendation) using matching artifacts, contract, and waves, then `tf execution show <change-dir> --json`; report the saved revision, selected mode, recommendation alignment, ordered waves, and actual concurrent-dispatch capability. A revision must repeat recommend and confirmation. Do not transition to `executing` until `show` reports `current: true`; then run `... check <dir> approved-for-build executing --json` → fail = BLOCK. **v0.13 §49 门禁前移**：该 guard 含 `test-matrix-ready` 维度——full 模式非存量 change 必须"带着矩阵开工"（矩阵存在非空 OR 显式 skip 附理由）；FAIL 时回 bridging 让 contract-builder 补矩阵，或按指引显式 skip，禁止绕过。
 
+### 阶段产物同步门禁点（v0.37.0 §68.2 G4）
+
+契约批准（DP-3）后、进入实施（DP-4）前，**阻塞确认**（AskUserQuestion）是否同步 change 规划制品（团队协作：契约是实施授权）：
+- **A 提交并推送**：`tf publish --changes <change-dir> --push`
+- **B 仅提交不推送**：`tf publish --changes <change-dir>`
+- **C 暂不同步**：直接进入实施，后续可补
+
+同步对象：change 规划制品 4+1（proposal / specs / design / tasks / execution-contract）+ `architecture/`。
+
 ### Route to bug-investigator
 Execution hit blockage: test failure, unexpected behavior, build error, task cannot proceed. After debugging, route back to build-executor.
 
 ### Route to code-reviewer
 The current planned wave is implemented and ready for spec-compliance + code-quality verification. A reviewer must write an `tf execution review <change-dir> --wave <id> --base <sha> --head <sha> --report <path> --verdict <pass|fail>` receipt before any dependent wave or closing transition.
 
+**逐 wave 审查纪律（v0.36.4）**：每次 code-reviewer dispatch 只审查**一个** wave。禁止将多个 wave 合并为一次审查（vrm4teamflow C1 事件：W1-W4 合并审查导致设计约定类问题在 W4 才发现，修复范围扩大到 8 个 batch）。parallel wave 内的多个 task 作为整体审查一次（receipt 是 wave 级别），但审查 prompt 必须包含每个 task 的独立 diff。
+
 ### Route to release-archivist (dispatch sub-agent)
 Guard: `... check <dir> executing closing --json` → fail = BLOCK. Implementation complete, verification complete/nearly complete. Include `DP-7: 归档确认`.