@xulthekl/team-flow 0.36.4 → 0.38.0

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/lib/test-matrix-export.mjs

@@ -54,6 +54,9 @@ const TEST_KIND_TO_TIER = {
   redis_social: 'integration',
   external_api_stub: 'integration',
   test_infrastructure: 'integration',
+  // e2e tier (v0.38.0，对齐 e2e skill 的 prototype/integration 两 project)
+  playwright_prototype: 'e2e',
+  playwright_integration: 'e2e',
 };
 
 /**
@@ -120,6 +123,7 @@ export function convert(matrix, options = {}) {
   // 统计
   const unitCases = cases.filter(c => deriveTestTier(c.test_kind) === 'unit');
   const integrationCases = cases.filter(c => deriveTestTier(c.test_kind) === 'integration');
+  const e2eCases = cases.filter(c => deriveTestTier(c.test_kind) === 'e2e');
 
   // 提取 complexity
   const complexity = matrix.target_complexity || {};
@@ -141,6 +145,7 @@ export function convert(matrix, options = {}) {
   lines.push(`- Modules covered: 1 (${moduleName}, complexity: ${complexityTier})`);
   lines.push(`- Unit cases: ${unitCases.length} (${Math.round(unitCases.length / cases.length * 100) || 0}%)`);
   lines.push(`- Integration cases: ${integrationCases.length} (${Math.round(integrationCases.length / cases.length * 100) || 0}%)`);
+  lines.push(`- E2E cases: ${e2eCases.length} (${Math.round(e2eCases.length / cases.length * 100) || 0}%)`);
   lines.push(`- Deferred items: ${candidateLedger.filter(c => c.decision === 'deferred').length}`);
   lines.push(`- Matrix revision: 1`);
   lines.push('');