@xulthekl/team-flow 0.36.4 → 0.38.0

package/scripts/lib/test-merge.mjs

@@ -14,6 +14,14 @@
  * 6. gitCommit — 单次原子提交
  *
  * 回写顺序：arch-merge → prototype-sync → test-merge → compound promotion
+ *
+ * v0.38.0（feedback 2026-08-05 修复 + E2E 层级）：
+ * - resolveDeferred 只删 Deferred Items 段内被覆盖行（原全文件 regex 误删 Current Cases）
+ * - extractSummary 容忍 markdown bold（**87**）+ 识别 E2E cases 行
+ * - mergeExistingBaseline 覆盖式语义修正（原 startsWith('') 恒真导致旧行累积）
+ * - cells 提取按索引保留空列（原 filter(Boolean) 丢空列错位）
+ * - dry-run 真正跳过写盘（原仅 gitCommit 生效）
+ * - rewriteIndex 统计 test_tier=e2e 层级（unit/integration/e2e 三栏）
  */
 
 import { readFileSync, writeFileSync, existsSync, cpSync, mkdirSync, readdirSync } from 'node:fs';
@@ -61,20 +69,24 @@ function preCheck(changeDir) {
 
 /**
  * 从 test-matrix.md 提取 Summary 统计信息
+ * 容忍 markdown bold（`**87**`）与普通数字两种格式（feedback 2026-08-05：C1 矩阵 LLM 手写加粗导致返回 0）
+ * 支持 E2E cases 行（v0.38.0：test_tier=e2e 记录，与复利 E2E 层级联动）
  */
-function extractSummary(content) {
-  const summary = { totalCases: 0, modules: 0, unitCases: 0, integrationCases: 0, deferred: 0 };
+export function extractSummary(content) {
+  const summary = { totalCases: 0, modules: 0, unitCases: 0, integrationCases: 0, e2eCases: 0, deferred: 0 };
   const lines = content.split('\n');
   for (const line of lines) {
-    const totalMatch = line.match(/Total cases:\s*(\d+)/i);
+    const totalMatch = line.match(/Total cases:\s*\*{0,2}\s*(\d+)/i);
     if (totalMatch) summary.totalCases = parseInt(totalMatch[1], 10);
-    const modulesMatch = line.match(/Modules covered:\s*(\d+)/i);
+    const modulesMatch = line.match(/Modules covered:\s*\*{0,2}\s*(\d+)/i);
     if (modulesMatch) summary.modules = parseInt(modulesMatch[1], 10);
-    const unitMatch = line.match(/Unit cases:\s*(\d+)/i);
+    const unitMatch = line.match(/Unit cases:\s*\*{0,2}\s*(\d+)/i);
     if (unitMatch) summary.unitCases = parseInt(unitMatch[1], 10);
-    const intMatch = line.match(/Integration cases:\s*(\d+)/i);
+    const intMatch = line.match(/Integration cases:\s*\*{0,2}\s*(\d+)/i);
     if (intMatch) summary.integrationCases = parseInt(intMatch[1], 10);
-    const defMatch = line.match(/Deferred items:\s*(\d+)/i);
+    const e2eMatch = line.match(/E2E cases:\s*\*{0,2}\s*(\d+)/i);
+    if (e2eMatch) summary.e2eCases = parseInt(e2eMatch[1], 10);
+    const defMatch = line.match(/Deferred items:\s*\*{0,2}\s*(\d+)/i);
     if (defMatch) summary.deferred = parseInt(defMatch[1], 10);
   }
   return summary;
@@ -173,10 +185,11 @@ function extractDeferredItems(content) {
 
 /**
  * Step 2: mergeBaselines — 增量合并到 baselines/{module}.md
+ * dryRun（feedback 2026-08-05）：仅计算不写盘，返回 would-create/would-update 预览
  */
-function mergeBaselines(ledgerDir, changeName, moduleSections, candidateLedger, deferredItems) {
+export function mergeBaselines(ledgerDir, changeName, moduleSections, candidateLedger, deferredItems, dryRun) {
   const baselinesDir = join(ledgerDir, 'baselines');
-  if (!existsSync(baselinesDir)) {
+  if (!existsSync(baselinesDir) && !dryRun) {
     mkdirSync(baselinesDir, { recursive: true });
   }
 
@@ -198,13 +211,13 @@ function mergeBaselines(ledgerDir, changeName, moduleSections, candidateLedger,
       const existing = readFileSync(baselinePath, 'utf-8');
       const updated = mergeExistingBaseline(existing, sectionContent, changeName, today, moduleCandidates, moduleDeferred);
       if (!updated) continue; // no changes
-      writeFileSync(baselinePath, updated, 'utf-8');
-      results[moduleName] = 'updated';
+      if (!dryRun) writeFileSync(baselinePath, updated, 'utf-8');
+      results[moduleName] = dryRun ? 'would-update' : 'updated';
     } else {
       // 新建 baseline
       const newBaseline = createNewBaseline(moduleName, sectionContent, changeName, today, moduleCandidates, moduleDeferred);
-      writeFileSync(baselinePath, newBaseline, 'utf-8');
-      results[moduleName] = 'created';
+      if (!dryRun) writeFileSync(baselinePath, newBaseline, 'utf-8');
+      results[moduleName] = dryRun ? 'would-create' : 'created';
     }
   }
   return results;
@@ -213,7 +226,7 @@ function mergeBaselines(ledgerDir, changeName, moduleSections, candidateLedger,
 /**
  * 创建新 baseline 文件
  */
-function createNewBaseline(moduleName, sectionContent, changeName, date, candidates, deferred) {
+export function createNewBaseline(moduleName, sectionContent, changeName, date, candidates, deferred) {
   const lines = [];
   lines.push(`# ${moduleName} Test Baseline`);
   lines.push('');
@@ -227,12 +240,13 @@ function createNewBaseline(moduleName, sectionContent, changeName, date, candida
   lines.push('|---|---|---|---|---|---|---|---|---|');
 
   // 从 sectionContent 提取 case 行并添加 source_change 列
+  // 空列保留（slice(1,-1) 去首尾空串），避免 filter(Boolean) 丢空列导致索引左移（feedback 2026-08-05）
   const caseLines = sectionContent.split('\n').filter(l =>
     l.startsWith('|') && !l.match(/^\|\s*[-:]+/) && !l.match(/\|\s*case_id/)
   );
   for (const line of caseLines) {
-    const cells = line.split('|').map(c => c.trim()).filter(Boolean);
-    if (cells.length >= 10) {
+    const cells = line.split('|').slice(1, -1).map(c => c.trim());
+    if (cells.length >= 11) {
       lines.push(`| ${cells[0]} | ${cells[1]} | ${cells[2]} | ${cells[5]} | ${cells[6]} | ${cells[8]} | ${cells[9]} | ${cells[10]} | ${changeName} |`);
     }
   }
@@ -258,57 +272,55 @@ function createNewBaseline(moduleName, sectionContent, changeName, date, candida
 }
 
 /**
- * 合并现有 baseline（增量更新 Current Cases + 追加 Evolution Log）
+ * 合并现有 baseline（Current Cases 覆盖式替换 + 追加 Evolution Log）
+ *
+ * feedback 2026-08-05 修复：
+ * 1. 原 `inFrontmatter && (line.startsWith('## ') || line.startsWith(''))` 中 startsWith('') 恒真 →
+ *    Current Cases 旧行不被跳过而累积（覆盖式语义失效）。改为仅在 `## ` 标题退出。
+ * 2. cells 提取改用 slice(1,-1) 保留空列（filter(Boolean) 丢空列导致索引左移错位）。
+ * 3. Evolution Log 幂等：同 change 同日已记录则跳过 append。
  */
-function mergeExistingBaseline(existing, sectionContent, changeName, date, candidates, deferred) {
+export function mergeExistingBaseline(existing, sectionContent, changeName, date, candidates, deferred) {
   const lines = [];
   const existingLines = existing.split('\n');
+  const caseLines = sectionContent.split('\n').filter(l =>
+    l.startsWith('|') && !l.match(/^\|\s*[-:]+/) && !l.match(/\|\s*case_id/)
+  );
+
+  const renderCaseRow = (line) => {
+    const cells = line.split('|').slice(1, -1).map(c => c.trim());
+    if (cells.length < 11) return null;
+    return `| ${cells[0]} | ${cells[1]} | ${cells[2]} | ${cells[5]} | ${cells[6]} | ${cells[8]} | ${cells[9]} | ${cells[10]} | ${changeName} |`;
+  };
+
+  let inCases = false; // Current Cases 段内 → 跳过旧行（覆盖式）
+  const logPattern = new RegExp(`\\*\\*${date}\\*\\* \\[${changeName}\\]:`);
 
-  // 更新 frontmatter
-  let inFrontmatter = false;
-  let frontmatterDone = false;
   for (const line of existingLines) {
     if (line.startsWith('> last_updated_by_change:')) {
       lines.push(`> last_updated_by_change: ${changeName}`);
     } else if (line.startsWith('> last_updated:')) {
       lines.push(`> last_updated: ${date}`);
     } else if (line.startsWith('## Current Cases')) {
-      // 插入 Current Cases header，然后用新数据替换表格
-      lines.push(line);
-      lines.push('');
-      lines.push('| case_id | behavior | design_method | test_kind | test_tier | work_mode | test_file | test_method_name | source_change |');
-      lines.push('|---|---|---|---|---|---|---|---|---|');
-      inFrontmatter = true;
-      // 跳过旧表格
-      continue;
-    } else if (inFrontmatter && (line.startsWith('## ') || line.startsWith(''))) {
-      inFrontmatter = false;
-      // 插入新的 case 行
-      const caseLines = sectionContent.split('\n').filter(l =>
-        l.startsWith('|') && !l.match(/^\|\s*[-:]+/) && !l.match(/\|\s*case_id/)
-      );
+      lines.push(line, '', '| case_id | behavior | design_method | test_kind | test_tier | work_mode | test_file | test_method_name | source_change |', '|---|---|---|---|---|---|---|---|---|');
       for (const cl of caseLines) {
-        const cells = cl.split('|').map(c => c.trim()).filter(Boolean);
-        if (cells.length >= 10) {
-          lines.push(`| ${cells[0]} | ${cells[1]} | ${cells[2]} | ${cells[5]} | ${cells[6]} | ${cells[8]} | ${cells[9]} | ${cells[10]} | ${changeName} |`);
-        }
+        const row = renderCaseRow(cl);
+        if (row) lines.push(row);
       }
-      lines.push(line);
-    } else if (inFrontmatter && line.startsWith('|')) {
-      // 跳过旧表格行（已替换）
-      continue;
+      inCases = true;
     } else if (line.startsWith('## Evolution Log')) {
+      // 优先于 inCases 退出分支：Evolution Log 标题也以 ## 开头，需先处理 append
+      inCases = false;
+      lines.push(line, '');
+      if (!existingLines.some(l => logPattern.test(l))) {
+        lines.push(`- **${date}** [${changeName}]: 新增 ${caseLines.length} case, defer ${deferred.length}`);
+      }
+    } else if (inCases && line.startsWith('## ')) {
+      inCases = false;
       lines.push(line);
-      lines.push('');
-      const caseCount = sectionContent.split('\n').filter(l =>
-        l.startsWith('|') && !l.match(/^\|\s*[-:]+/) && !l.match(/\|\s*case_id/)
-      ).length;
-      lines.push(`- **${date}** [${changeName}]: 新增 ${caseCount} case, defer ${deferred.length}`);
-      frontmatterDone = true;
-    } else if (frontmatterDone && line.startsWith('- **')) {
-      // 保留旧的 evolution log entries
-      lines.push(line);
-    } else if (!inFrontmatter) {
+    } else if (inCases) {
+      continue; // 跳过 Current Cases 段内旧表行/分隔行/空行
+    } else {
       lines.push(line);
     }
   }
@@ -318,8 +330,12 @@ function mergeExistingBaseline(existing, sectionContent, changeName, date, candi
 
 /**
  * Step 3: resolveDeferred — 新 case 覆盖了旧 deferred 项
+ *
+ * feedback 2026-08-05 修复：原实现用全文件 regex `\|<caseId>\|[^\n]*\n` 删除匹配行，
+ * 把 baselines `Current Cases` 表的正常 case 行也一并误删（表体清空、Evolution Log 计数保留）。
+ * 改为逐行扫描，仅删除 `## Deferred Items` 段（到下一个 `## ` 标题之间）内被新 case 覆盖的行。
  */
-function resolveDeferred(ledgerDir, changeName, newCaseIds) {
+export function resolveDeferred(ledgerDir, changeName, newCaseIds, dryRun) {
   const baselinesDir = join(ledgerDir, 'baselines');
   if (!existsSync(baselinesDir)) return { resolved: 0 };
 
@@ -327,47 +343,58 @@ function resolveDeferred(ledgerDir, changeName, newCaseIds) {
   for (const file of readdirSync(baselinesDir)) {
     if (!file.endsWith('.md')) continue;
     const fp = join(baselinesDir, file);
-    let content = readFileSync(fp, 'utf-8');
-    let changed = false;
+    const content = readFileSync(fp, 'utf-8');
+    const lines = content.split('\n');
 
-    // 移除 Deferred Items 中被新 case 覆盖的行
-    for (const caseId of newCaseIds) {
-      const regex = new RegExp(`\\|\\s*${escapeRegex(caseId)}\\s*\\|[^\\n]*\\n`, 'g');
-      if (regex.test(content)) {
-        content = content.replace(regex, '');
-        changed = true;
-        resolved++;
+    let inDeferred = false;
+    const kept = [];
+    let changed = false;
+    for (const line of lines) {
+      if (line.startsWith('## Deferred Items')) {
+        inDeferred = true;
+        kept.push(line);
+        continue;
+      }
+      if (inDeferred && line.startsWith('## ')) {
+        inDeferred = false;
+        kept.push(line);
+        continue;
       }
+      if (inDeferred && line.startsWith('|') && !line.match(/^\|\s*[-:]/)) {
+        const cells = line.split('|').slice(1, -1).map(c => c.trim());
+        if (cells.length && newCaseIds.includes(cells[0])) {
+          changed = true;
+          resolved++;
+          continue; // 被新 case 覆盖 → 删除该 deferred 行
+        }
+      }
+      kept.push(line);
     }
 
-    if (changed) {
-      writeFileSync(fp, content, 'utf-8');
+    if (changed && !dryRun) {
+      writeFileSync(fp, kept.join('\n'), 'utf-8');
     }
   }
   return { resolved };
 }
 
-function escapeRegex(str) {
-  return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-}
-
 /**
  * Step 4: appendChangelog — 归档 test-matrix.md
  */
-function appendChangelog(ledgerDir, changeName, matrixContent) {
+export function appendChangelog(ledgerDir, changeName, matrixContent, dryRun) {
   const changelogDir = join(ledgerDir, 'changelog');
-  if (!existsSync(changelogDir)) {
+  if (!existsSync(changelogDir) && !dryRun) {
     mkdirSync(changelogDir, { recursive: true });
   }
   const destPath = join(changelogDir, `${changeName}.md`);
-  writeFileSync(destPath, matrixContent, 'utf-8');
+  if (!dryRun) writeFileSync(destPath, matrixContent, 'utf-8');
   return destPath;
 }
 
 /**
  * Step 5: rewriteIndex — 重写 INDEX.md
  */
-function rewriteIndex(ledgerDir) {
+export function rewriteIndex(ledgerDir, dryRun) {
   const baselinesDir = join(ledgerDir, 'baselines');
   const indexPath = join(ledgerDir, 'INDEX.md');
   const today = new Date().toISOString().slice(0, 10);
@@ -399,11 +426,12 @@ function rewriteIndex(ledgerDir) {
       if (deferredCount > 0) status = '⚠️ partial';
       if (caseCount === 0) status = '⏭️ not_applicable';
 
-      // test_tier_breakdown
-      const unitCount = (content.match(/unit/gi) || []).length;
-      const intCount = (content.match(/integration/gi) || []).length;
+      // test_tier_breakdown（v0.38.0：补 e2e 层级；\b 词边界防误匹配 community 等）
+      const unitCount = (content.match(/\bunit\b/gi) || []).length;
+      const intCount = (content.match(/\bintegration\b/gi) || []).length;
+      const e2eCount = (content.match(/\be2e\b/gi) || []).length;
 
-      modules.push({ moduleName, caseCount, deferredCount, lastChange, lastDate, status, unitCount, intCount });
+      modules.push({ moduleName, caseCount, deferredCount, lastChange, lastDate, status, unitCount, intCount, e2eCount });
     }
   }
 
@@ -421,10 +449,10 @@ function rewriteIndex(ledgerDir) {
   lines.push('|---|---|---|---|---|---|---|');
 
   for (const m of modules) {
-    lines.push(`| ${m.moduleName} | unit:${m.unitCount}, integration:${m.intCount} | ${m.caseCount} | ${m.deferredCount} | ${m.lastChange} | ${m.lastDate} | ${m.status} |`);
+    lines.push(`| ${m.moduleName} | unit:${m.unitCount}, integration:${m.intCount}, e2e:${m.e2eCount} | ${m.caseCount} | ${m.deferredCount} | ${m.lastChange} | ${m.lastDate} | ${m.status} |`);
   }
 
-  writeFileSync(indexPath, lines.join('\n') + '\n', 'utf-8');
+  if (!dryRun) writeFileSync(indexPath, lines.join('\n') + '\n', 'utf-8');
   return { modules: modules.length, totalCases, totalDeferred };
 }
 
@@ -494,16 +522,21 @@ async function main(argv, projectRoot) {
   const candidateLedger = extractCandidateLedger(matrixContent);
   const deferredItems = extractDeferredItems(matrixContent);
 
-  console.log(`   Summary: ${summary.totalCases} cases, ${summary.modules} modules, ${summary.deferred} deferred`);
+  console.log(`   Summary: ${summary.totalCases} cases (unit ${summary.unitCases} + integration ${summary.integrationCases} + e2e ${summary.e2eCases}), ${summary.modules} modules, ${summary.deferred} deferred`);
 
-  // Ensure ledger directory exists
-  if (!existsSync(ledgerDir)) {
+  // Ensure ledger directory exists（dry-run 不建目录）
+  if (!existsSync(ledgerDir) && !dryRun) {
     mkdirSync(ledgerDir, { recursive: true });
   }
 
+  const mark = dryRun ? '[DRY-RUN]' : '✅';
+
   // Step 2: mergeBaselines
-  const mergeResults = mergeBaselines(ledgerDir, changeName, moduleSections, candidateLedger, deferredItems);
-  console.log(`✅ Step 2: mergeBaselines — ${Object.keys(mergeResults).length} modules processed`);
+  const mergeResults = mergeBaselines(ledgerDir, changeName, moduleSections, candidateLedger, deferredItems, dryRun);
+  const mergeStates = Object.values(mergeResults);
+  const created = mergeStates.filter(s => s === 'created' || s === 'would-create').length;
+  const updated = mergeStates.filter(s => s === 'updated' || s === 'would-update').length;
+  console.log(`${mark} Step 2: mergeBaselines — ${Object.keys(mergeResults).length} modules processed (${created} created, ${updated} updated)`);
 
   // Step 3: resolveDeferred
   const newCaseIds = [];
@@ -511,27 +544,31 @@ async function main(argv, projectRoot) {
     const lines = section.split('\n');
     for (const line of lines) {
       if (line.startsWith('|') && !line.match(/^\|\s*[-:]+/) && !line.match(/\|\s*case_id/)) {
-        const cells = line.split('|').map(c => c.trim()).filter(Boolean);
+        const cells = line.split('|').slice(1, -1).map(c => c.trim());
         if (cells[0]) newCaseIds.push(cells[0]);
       }
     }
   }
-  const deferredResult = resolveDeferred(ledgerDir, changeName, newCaseIds);
-  console.log(`✅ Step 3: resolveDeferred — ${deferredResult.resolved} items resolved`);
+  const deferredResult = resolveDeferred(ledgerDir, changeName, newCaseIds, dryRun);
+  console.log(`${mark} Step 3: resolveDeferred — ${deferredResult.resolved} items resolved`);
 
   // Step 4: appendChangelog
-  const changelogPath = appendChangelog(ledgerDir, changeName, matrixContent);
-  console.log(`✅ Step 4: appendChangelog — ${relative(projectRoot, changelogPath)}`);
+  const changelogPath = appendChangelog(ledgerDir, changeName, matrixContent, dryRun);
+  console.log(`${mark} Step 4: appendChangelog — ${relative(projectRoot, changelogPath)}`);
 
   // Step 5: rewriteIndex
-  const indexResult = rewriteIndex(ledgerDir);
-  console.log(`✅ Step 5: rewriteIndex — ${indexResult.modules} modules, ${indexResult.totalCases} total cases`);
+  const indexResult = rewriteIndex(ledgerDir, dryRun);
+  console.log(`${mark} Step 5: rewriteIndex — ${indexResult.modules} modules, ${indexResult.totalCases} total cases`);
 
   // Step 6: gitCommit
   gitCommit(projectRoot, changeName, dryRun);
-  console.log('✅ Step 6: gitCommit');
+  console.log(`${mark} Step 6: gitCommit`);
 
-  console.log(`\n🎉 test-merge complete for ${changeName}`);
+  if (dryRun) {
+    console.log(`\n🧪 test-merge DRY-RUN complete for ${changeName} — 未写入任何文件`);
+  } else {
+    console.log(`\n🎉 test-merge complete for ${changeName}`);
+  }
 }
 
 // 直接运行（v0.35.0 修复：main() 无参自调用崩溃 → 调用 run() 走正确参数解析）

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/build-executor/implementer-prompt.md

@@ -52,6 +52,8 @@ Subagent (general-purpose):
     If `test-matrix.md` exists, read the module section relevant to your task.
     For each case in the matrix, follow the protocol matching its `work_mode`:
 
+    **test_tier=e2e 豁免（v0.38.0）**: `test_tier=e2e` 的 case 不在 implementer 职责内——由 e2e skill / release-archivist Step 5b 覆盖，跳过（不计入模块 coverage，不按 work_mode 走 TDD）。
+
     **work_mode=TDD** (new behavior):
     1. RED: Write failing test matching `case_id` + `test_method_name`, confirm failure
     2. GREEN: Implement minimum code to pass
@@ -68,7 +70,7 @@ Subagent (general-purpose):
     2. Fix production code, confirm green
     3. Report: defect reproduction + fix evidence
 
-    After all cases: self-check matrix coverage = passed cases / total cases in matrix for your module.
+    After all cases: self-check matrix coverage = passed cases / total cases in matrix for your module（分母排除 test_tier=e2e）。
 
     **两不原则 (Two Prohibitions)**:
     - ⛔ DO NOT write production code and test code simultaneously — RED first, then GREEN

package/skills/ce-brainstorm/references/prototype-loop.md

@@ -39,10 +39,10 @@ PRD 文档写入后、Handoff 之前，执行原型内循环。原型是 PRD 的
 
 ## 3.5.5 PRD 完整性评审（冻结前门禁）
 
-原型审查通过后、冻结前，派发 `prd-completeness-reviewer` 子代理（只读，独立上下文），评审 PRD「是否完整到能支撑后续 plan/spec 实施」（区别于 Phase 2.6 claim verifier——后者管"说得对不对"，本评审管"说得全不全"）。
+原型审查通过后、冻结前，派发 `prd-completeness-reviewer` 子代理（独立上下文），评审 PRD「是否完整到能支撑后续 plan/spec 实施」（区别于 Phase 2.6 claim verifier——后者管"说得对不对"，本评审管"说得全不全"）。
 
 - 派发：按名派发插件 agent `prd-completeness-reviewer`（定义见插件 `agents/prd-completeness-reviewer.md`），传入 PRD 路径 + CONCEPTS.md 路径。
-- 子代理按 §18.1 交接协议返回。报告落盘到 `prd/{ITERATION_VERSION}/prd-completeness-review.md`。
+- agent 直接写审查报告到 `prd/{ITERATION_VERSION}/prd-completeness-review.md`。
 - 判定（柔性）：PASS / PASS_WITH_WARNINGS → 进入冻结；**FAIL（Critical>0）→ 回 Phase 1.3 补充**后重审。
 - 5 维度：用户故事完整性(Critical)/验收标准(Critical)/边界与非功能(Important)/术语一致性(Minor)/范围闭环(Important)。
 

package/skills/code-reviewer/SKILL.md

@@ -144,7 +144,7 @@ If `test-matrix.md` exists in the change directory, audit the implementation aga
    - Verify `design_method` matches actual test approach (a `boundary` case must use real boundary values, not a happy-path disguised as boundary)
 
 2. **Coverage calculation**:
-   - Matrix coverage = implemented cases / total cases in matrix
+   - Matrix coverage = implemented cases / total cases in matrix（**分母排除 test_tier=e2e**——E2E case 由 release-archivist Step 5b 对账，不在实施层判定）
    - Matrix coverage < 100% → **Critical finding** (test-matrix-gap)
    - List missing case_ids
 
@@ -153,8 +153,9 @@ If `test-matrix.md` exists in the change directory, audit the implementation aga
    - Entries with `decision=covered` actually have corresponding tests?
 
 4. **Pyramid ratio check**:
-   - unit cases: 70-80% of total
-   - integration cases: ≤30% of total
+   - 分母 = unit + integration（e2e 不计入金字塔配比，v0.38.0）
+   - unit cases: 70-80% of (unit+integration)
+   - integration cases: ≤30% of (unit+integration)
    - Significant deviation → **Important finding** (test-pyramid-imbalance)
 
 If `test-matrix.md` does NOT exist, skip this step silently (legacy change compatibility).

package/skills/code-reviewer/code-reviewer-prompt.md

@@ -73,9 +73,9 @@ Subagent (general-purpose):
     - Each case has a corresponding test implementation (test_file + test_method_name match)?
     - Assertions match the matrix's `expected` output?
     - `design_method` matches actual test approach (boundary case uses real boundary values)?
-    - Matrix coverage < 100% → Critical finding (test-matrix-gap)
+    - Matrix coverage < 100% → Critical finding (test-matrix-gap)（分母排除 test_tier=e2e，E2E case 由 release-archivist Step 5b 对账）
     - Candidate Coverage Ledger: deferred items have reasonable reasons?
-    - Pyramid ratio: unit 70-80%, integration ≤30%?
+    - Pyramid ratio: unit 70-80%, integration ≤30%?（分母 = unit+integration，e2e 不计入）
     If `test-matrix.md` does NOT exist, skip this section silently.
 
     **Production readiness:**

package/skills/contract-builder/SKILL.md

@@ -11,7 +11,7 @@ Read before generating: `proposal.md`, `specs/`, `design.md`, `tasks.md`, then l
 
 **Architecture Design Outputs (v0.9 §26)**: 若 `architecture/` 目录存在，同时读取 `architecture/architecture.md` / `database.md` / `api.md`，作为执行契约的架构约束补充输入——确保 execution-contract.md 的 Implementation Constraints 段包含架构设计的关键约束（聚合边界/CQRS 分流/API 契约/schema 变更）。`architecture/` 不存在时跳过。
 
-**Test Ledger Injection (v0.12 §43.5)**: 若 `docs/test-ledger/` 存在，读取 `INDEX.md`（模块覆盖概览 coverage_status）+ `baselines/{module}.md`（已有 case 避免重复设计；Deferred Items 评估本次是否可解决），作为 test-matrix.md 生成的增量输入。不存在时跳过（首次使用或无历史数据）。
+**Test Ledger Injection (v0.12 §43.5)**: 若 `docs/test-ledger/` 存在，读取 `INDEX.md`（模块覆盖概览 coverage_status）+ `baselines/{module}.md`（已有 case 避免重复设计；Deferred Items 评估本次是否可解决），作为 test-matrix.md 生成的增量输入。不存在时跳过（首次使用或无历史数据）。**tier 语义（v0.38.0）**：baselines 中 `test_tier=e2e` 的行表示"端到端已覆盖"，不参与 unit/integration 去重与金字塔配比——不得把它误判为单测已覆盖而省略低层级 case 设计。
 
 ## Artifact Mapping
 
@@ -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` 段引用。
@@ -44,19 +57,20 @@ Must make obvious: approved behavior, out-of-scope, constraints, batches, test o
 
 ### Generation Protocol
 
-1. **输入来源**：specs/（Scenario + Unit/Integration 标签）、tasks.md（batch + file structure）、test-strategy skill（design_method 规则）、test-ledger baselines（增量输入）
+1. **输入来源**：specs/（Scenario + Unit/Integration/E2E 标签）、tasks.md（batch + file structure）、test-strategy skill（design_method 规则）、test-ledger baselines（增量输入）
 2. **按模块分组**：为每个有业务逻辑的模块（Service/Controller/Repository 等）生成 case 列表
 3. **复杂度分级**：每个模块标注 trivial/medium/complex，作为用例数下限判据（test-strategy §2）
 4. **design_method 覆盖**：每个模块至少 1 个 `{boundary, equivalence}` case + 1 个 `{error, exception, reject}` case（test-strategy §6 schema 强制覆盖）
 5. **对抗验证**：矩阵生成后执行三招回检（test-strategy §4），缺失则追加 adversarial case
 6. **候选覆盖台账**：列出所有被测候选（方法/类），标注 decision（covered/deferred/not_applicable）
+7. **E2E 层评估（v0.38.0）**：对 specs 中含 **UI 交互/跨层链路**的 Scenario（AC 涉及前端交互、跨服务/跨层数据流）显式评估 E2E 必要性——纳入 `test_tier=e2e` 的 case（标准 12 列，case_id `{Module}-e2e-{scene}-{NNN}`，`work_mode=E2E`（不参与 build-executor 的 TDD 路由），mock 列 `-`，test_kind 用 `playwright_prototype`/`playwright_integration`）或记录"E2E 排除 + 理由"（如无 UI/纯后端）。不得静默跳过。
 
 ### 12-Column Format
 
 | case_id | behavior | design_method | input | expected | test_kind | test_tier | mock | work_mode | test_file | test_method_name | run_command |
 |---|---|---|---|---|---|---|---|---|---|---|---|
 
-字段说明见 test-strategy skill 的 `references/design-methods-detail.md`。`test_tier` 从 `test_kind` 派生（unit/integration）。
+字段说明见 test-strategy skill 的 `references/design-methods-detail.md`。`test_tier` 从 `test_kind` 派生，可取 **unit / integration / e2e** 三值（v0.38.0：E2E case 的 test_kind 用 `playwright_prototype` / `playwright_integration`）。
 
 ### Structure
 
@@ -68,6 +82,7 @@ Must make obvious: approved behavior, out-of-scope, constraints, batches, test o
 - Modules covered: {N} (complexity: trivial×{n}, medium×{n}, complex×{n})
 - Unit cases: {N} ({percent}%)
 - Integration cases: {N} ({percent}%)
+- E2E cases: {N} ({percent}%)
 - Deferred items: {N}
 - Matrix revision: 1
 
@@ -91,7 +106,7 @@ Must make obvious: approved behavior, out-of-scope, constraints, batches, test o
 ```markdown
 ## Test Matrix
 See `test-matrix.md` for the full test case matrix (附属产物, 独立 hash).
-- Total cases: {N}, Unit: {N}, Integration: {N}, Deferred: {N}
+- Total cases: {N}, Unit: {N}, Integration: {N}, E2E: {N}, Deferred: {N}
 ```
 
 然后执行 `tf state rebuild <change-dir>` 更新 `test_matrix_hash`。

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

@@ -23,7 +23,7 @@ description: 本地 HTML 原型设计与维护 skill（零外部依赖、可离
 ① 环境探查 + 方案设计   → sub: prototype-env-scout（只读，产出环境简报+2-3 个差异化方向，v0.18.0）
 ② 方案评审 + 人工评审   → 主代理（方向选定+方案确认 → AskUserQuestion）
 ③ 原型绘制             → sub: prototype-builder（有 Write，种子优先：template.html+layouts.md 组合，v0.18.0）
-④ 原型评审             → sub: prototype-reviewer（只读，PRD 6 维度+P0 grep+craft 4 席 rubric，v0.18.0）
+④ 原型评审             → sub: prototype-reviewer（PRD 6 维度+P0 grep+craft 4 席 rubric，v0.18.0，直接写审查报告）
 ⑤ 循环编排             → 主代理：FAIL→回③修正(≤3轮,收敛检测)；PASS/PASS_WITH_WARNINGS→⑥
 ⑥ 人工评审路由         → 主代理 AskUserQuestion：
                           - PRD 有问题 → 回 orchestrator S2 修订 PRD（vN 内修订，非升版）→ 再更新原型
@@ -38,8 +38,8 @@ description: 本地 HTML 原型设计与维护 skill（零外部依赖、可离
 | ①环境探查+方案设计 | sub `prototype-env-scout`（插件 agent，只读） | 无（简报+方向写 response） |
 | ②方案/人工评审 | 主代理（含方向选定，v0.18.0） | 无 |
 | ③绘制 | sub `prototype-builder`（插件 agent，种子优先） | prototype/ 全部 |
-| ④评审 | sub `prototype-reviewer`（插件 agent，只读，含 craft rubric） | 无（报告写 response，主代理落盘） |
-| ⑤循环编排 | 主代理 | 落盘评审报告 |
+| ④评审 | sub `prototype-reviewer`（插件 agent，含 craft rubric） | 审查报告（直接写文件） |
+| ⑤循环编排 | 主代理 | 无 |
 | ⑥人工路由 | 主代理 | 无 |
 
 ## 内核（零外部依赖）
@@ -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/prototype/references/orchestration-flow.md

@@ -83,12 +83,12 @@ test -f <prototype_path>/index.html && test -s <prototype_path>/index.html && ec
 
 ## 步骤 ④ 原型评审（子代理）
 
-派发插件 agent `prototype-reviewer`（只读，独立上下文），**传入：`prd_path`、`prototype_path`（及当前轮次 N）**，执行：
+派发插件 agent `prototype-reviewer`（独立上下文），**传入：`prd_path`、`prototype_path`（及当前轮次 N）**，执行：
 - PRD 6 维度（D1-D6，D6 含五状态契约）
 - **P0 工艺机械检查（v0.18.0）**：裸 hex / 靛蓝黑名单 / emoji / 填充文案 / scrollIntoView / data-testid / accent 超限——P0 违规 = Critical
 - **Craft Quality 4 席 rubric（v0.18.0）**：工艺(×0.4)+品牌(×0.2)+无障碍(×0.2)+文案(×0.2) 加权合成
 
-报告写 response，主代理落盘到 `prd/vN/prototype-auto-review.md`。
+agent 直接写审查报告到 `prd/vN/prototype-auto-review.md`。
 
 判定（v0.18.0 升级）：
 - **PASS**：Critical=0 且 Important=0 且 craft 合成 ≥6.0